banker/README.md

Downloads transactions and balances from online banking websites using Zombie.js.

# banker

This is a command-line script that downloads transactions and balances from
financial institutions using [Zombie.js](https://github.com/assaf/zombie).
Currently supported banks:

- [PayPal](https://www.paypal.com/)
  - Works regardless of whether the account has opted in to the new PayPal
    website.

- [Avadian Credit Union](https://www.avadiancu.com/) (formerly Alabama Telco
  Credit Union)

- Credit unions handled by the new Fiserv software (if your online banking URL
  starts with `https://www.financial-net.com/*` or
  `https://www.ea.financial-net.com/vbsts/*`)
  - [Trust Federal Credit Union](http://trustfcu.com/)
  - Probably others

- Credit unions handled by the old Fiserv software (if your online banking URL
  starts with `https://www.netit.financial-net.com/*`)
  - [BlueCross BlueShield of Tennessee Employee Credit Union](http://bcbstecu.com/)
  - Probably others

- [Regions Bank](https://www.regions.com/)

- [Tennessee Valley Federal Credit Union](http://tvfcu.com/)

- **Please help add your bank!** See [below](#adding-banks) for details.

## Installation

[Install Node.js](http://nodejs.org/), then:

```
sudo npm install -g banker
banker --help
```

## Usage

```
banker --config config.json --output data/results.json
```

Running `banker --help` shows documentation for other command-line options:

```
Usage: banker options

Options:
  -b, --banks          Just list the banks that this program can download
                       information from.
  -l, --list           Just list the banks and accounts in the given config
                       file.
  --describe-output    Just list the banks and accounts in the given output
                       file.
  -c, --config         The JSON config file(s) describing the banks and
                       accounts to process.
  -o, --output         The JSON output file with transaction details.
  -s, --skip           Skip the specified bank(s) or account(s).
  --only               Only process the specified bank(s) or account(s) - see
                       --list for valid specifiers.
  -d, --debug-browser  Save pages fetched by the browser (to the same directory
                       as the output file).
  -v, --verbose        Increase verbosity (up to -vvv).

Config filename is required unless '--banks' is specified.
```

Note that if you are using the `--debug-browser` option, you should put the
`--output` file in its own directory, since the program will dump a bunch of
HTML pages in the same directory.  (The directory will be created if it doesn't
exist.)

## Configuration

Create a JSON configuration file (`config.json` above) that contains a bank
configuration or an array of bank configurations.  Bank configurations usually
need to contain the following items, see the output of `banker --banks` for
exact settings required for a given bank.

- **bankName** - the name of the bank.  This should be the name of the
  JavaScript file in `lib/banks` without the `.js` extension.

- **username** - your online banking username.

- **password** - your online banking password.

- **securityQuestions** - a hash of security questions and answers, like this:
```js
"securityQuestions" : {
    "What is your favorite color?" : "Black"
}
```

- **accounts** - a list of account configurations.  The required items vary by
  bank - use the output of `banker --banks` to determine which fields are
  required.

  If you are using the `--debug-browser` option, specify a `filename` field for
  each account, and this value will appear in the filenames of the HTML pages
  the program saves.

  Also, any additional data that you include in the account configurations will
  appear in the output file, so you can use this to pass identifier fields etc.

See the output of `banker --banks` or the files in the `configs` directory for
more details about the configuration file.

## Output

The program will write a JSON file to the path specified after `--output`, with
the following structure:

```js
[
    // object for first bank data
    {
        "bank"   : // bank name
        "status" : // may contain a message like "skipped"
        "error"  : // the error message for this bank, if any
        "data"   : [ // list of data objects, one for each account

            // account information (copied from config file)
            "account" : {
                // ...
            },

            // transactions downloaded from this bank
            "transactions" : [
                {
                    "date"        : // self-explanatory
                    "amount"      : // self-explanatory
                    "description" : // self-explanatory
                    "memo"        : // like a "sub-description" (if any)
                    "images"      : /* any images downloaded for this
                                       transaction (encoded as a data: url) */
                    "sourceId"    : /* transaction ID, from bank or
                                       generated from other fields */
                    // (transaction objects may also contain other fields)
                }, {
                    // ... (more transactions)
                }
            ],

            // balances downloaded from this bank
            "balances" : {
                "actual"    : // latest posted balance
                "available" : // available balance
                "fromList"  : /* balance from transaction list (hint: it's
                                 worth checking if this matches the other
                                 balances since some bank software is buggy) */
            }
        ]
    }, {
        // ... (data objects for more banks)
    }
]
```

## Adding Banks

To add a new bank, write a driver for it and put it in the `lib/banks`
directory.  The filename of the driver will be the string used to specify that
bank in a config file.

Drivers should inherit from `BankSession` (`lib/banks/base.js`) and should
define the following methods:

```js
MyBankSession.prototype.info = function() {
    // For documentation, return an object like this:
    return {
        description  : // Bank description
        configItems  : // Bank configuration items
        accountItems : // Configuration items needed for each account
    };
};

MyBankSession.prototype.login = function(cb) {
    // Try to log in to the bank website, then call:
    //  - cb(err)  on failure
    //  - cb(null) on success
};

MyBankSession.prototype.getTransactions = function(accountConfig, cb) {
    // Try to get transactions from the given account, and call cb(err) on
    // failure or cb(data) on success, where data is an object like this:
    var data = {
        transactions : // List of transactions downloaded from this bank, in
                       // the same format as the output file described above
        balances : // Balances downloaded from this bank
    };
};

MyBankSession.prototype.logout = function(cb) {
    // Try to log out of the bank website, then call:
    //  - cb(err)  on failure
    //  - cb(null) on success
};
```

Finally, drivers should export themselves as `module.exports`:

```js
module.exports = MyBankSession;
```