/ 
Finance-Bank-NFCU-0.02
/ Finance::Bank::NFCU

NAME

Finance::Bank::NFCU - Module for accessing data in your Navy Federal Credit Union accounts.

SYNOPSIS

use Finance::Bank::NFCU;

my %credentials = (
    access_number => '111111111111',
    user_id       => '1234',
    password      => '*********',
);
my $ncfu = Finance::Bank::NFCU->new( \%credentials )
    || die "failed to authenticate";

$nfcu->config(
    {   cache_dir     => '/var/cache/nfcu',
        tidy_rc       => \&tidy_function,
        categorize_rc => \&categorize_function,
        error_level   => 'non-fatal', # fatal or non-fatal
    }
);

my $balances_ra = $nfcu->get_balances();

die "Your session has (probably) expired."
    if !defined $balances_ra;

for my $balance_rh (@{ $balances_ra }) {

    my $number  = $balance_rh->{account_number};
    my $desc    = $balance_rh->{description};
    my $dollars = $balance_rh->{balance};

    print "$number, $desc -- $dollars\n";
}

my $transaction_ra = $nfcu->get_transactions();

for my $transaction_rh (@{ $transaction_ra }) {

    my ( $date, $item, $amount ) = @{ $transaction_rh }{qw( date item amount )};

    print "$date -- $item -- $amount\n";
}

my $report_ra = $nfcu->get_expenditure_report();

for my $category_rh (@{ $report_ra }) {

    my $category    = $category_rh->{category};
    my $total       = $category_rh->{total};
    my $weekly_ave  = $category_rh->{weekly_ave};
    my $monthly_ave = $category_rh->{monthly_ave};

    print "$category: $total, $weekly_ave, $monthly_ave\n";
}

WARNING

This module is designed to interact with your online banking service at Navy Federal Credit Union. You are fully responsible for the actions taken with this module and you are expected to audit the code yourself to be sure that the security, accuracy and quality is up to your expectations.

The author cannot assume responsibility for any untoward or nefarious activities attempted with this software.

You are advised to never leave passwords, access numbers or user IDs hard coded in your programs.

DESCRIPTION

This is an OO interface to the NFCU online banking interface at: https://www.navyfederal.org/

The goal is to provide a convenient read-only interface for your financial data.

METHODS

new

Creates a new instance of this class which has used the given credentials to authenticate on the NFCU web interface. If the login event fails on the web interface then undef is returned.

Expects a hash ref of credentials with the following keys:

access_number

Same as the field labeled 'Access Number' on the website.

user_id

Same as the field labeled 'User ID' on the website.

password

Same as the 'Password' field on the website.

None of the above values are cached or retained by this module in any form. You need to make yourself aware of, and assume full responsibility for, any potential security risks that may be involved with passing your online banking credentials via this module.

config

Use this function to configure various internal parameters including:

cache_dir

The directory where you'd like to cache the bank statement source data. Caching the data will allow eStatement information to be available after it is no longer on the website. This directory will contain your financial data in plain text and you should choose it carefully.

tidy_rc

This is a code reference for the function that you'd like to use for tidying up the transaction labels. The transaction lable will be passed as a string and the tidied version should be returned. If not given then the default tidy function is used which is optimal for the author's purposes.

categorize_rc

This is a code reference for the function that you'd like to use for determining which category label applies for a given transaction label. The transaction label will be passed as a string and the category label should be returned, or some sensible default category such as 'uncategorized'. If not given then the default tidy function is used which is optimal for the author's purposes.

error_level

As the transactions are read from the web content they're validated for accuracy by double checking the amounts and their affects on the balance. If the math doesn't work out between two adjacent transactions then this module will emit a warning. Set this config parameter to 'fatal' to upgrade this situation to a fatal error. Although the author considers this possibility to be unlikely, you might want to run this in fatal mode just to be certain.

get_balances

Returns a hash of the accounts and the current balances as indicated on the main account page.

get_recent_transactions

Returns an array ref of transaction hash refs. The transactions are drawn from the list of recent activity for the current statement period.

get_estatement_transactions

Returns an array ref of transaction hash refs. The transactions are drawn from the eStatement section and includes all available history.

get_billpay_transactions

Returns an array ref of transaction hash refs. The transactions are drawn from the billpay section of the website and includes Pending status transactions.

get_transactions

Returns an array ref of transaction hash refs. The transactions are an audited aggregation of the transactions returned from the current statement, the eStatements, and pending transactions in the billpay section. The pending billpay transactions suggest a predicted balance history which is based on the current balance as of the most recent confirmed transaction.

get_expenditure_report

This analyzes all the accessible transaction data and computes stats on the amount spent on the various categories (as determined by the categorize_rc function).

TODO

This is currently "EveryDay Checking" oriented. There are some optional (and currently undocumented and untested) parameters which could potentially be used to focus on particular accounts such as a credit card, loan, savings or any other accounts accessible. A future revision will support alternate accounts of interest.

This is a working first draft which is useful to the author. It comes with no guarantee as to the correctness or suitability for any particular purpose.

AUTHOR

Dylan Doxey, <dylan.doxey@gmail.com<gt>

COPYRIGHT AND LICENSE

Copyright (C) 2011 by Dylan Doxey

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.