beanni

Your friendly Australian bean-counter.

Usage no npm install needed!

<script type="module">
  import beanni from 'https://cdn.skypack.dev/beanni';
</script>

README

Beanni

Your friendly Australian bean-counter, Beanni.

npm npm GitHub contributors Build Status

By @mjhilton and @tathamoddie.

Beanni helps gather financial data from all of your various providers, institutions, and banks. Having all of this cached in a local database allows you to do deeper analysis than typical online banking tools would allow, such as spend-by-merchant stats, or net-worth trends.

Beanni is just a local helper, on your own machine. You're not sharing your passwords with us, or anybody else. You're not reverse engineering your bank. Beanni is just a robot that's really fast at clicking the same transaction export buttons that you would otherwise have to click manually.

Usage

First Run

Get started in minutes:

Step Run Why
1. https://nodejs.org/en/download/ Beanni is built on Node.js
2. node --version Make sure you're on Node ≥10.13.0
3. npm --version Make sure you're on NPM ≥6.8.0
4. mkdir beanni
cd beanni		 Create a local folder where config and data will be stored
5. npm install beanni Install Beanni into this folder
6. npx beanni init Create an example config.yaml
7. Edit config.yaml Add your own banking relationships
8. npx beanni fetch Grab your data
9. npx beanni explore Launch the analysis UI

💡 Be careful with npm vs npx in some of those commands; they look very similar at a glance.

Ongoing Usage

In future:

Step Run Why
1. npm update beanni Update Beanni to the latest version
2. npx beanni fetch Grab your data
3. npx beanni explore Launch the analysis UI

Uninstall

  1. Delete the local working folder (the database contains bank account numbers and financial data)
  2. Remove secrets from your operating system's credential store
    • Windows:
      1. Win > credential manager
      2. Windows Credentials
      3. Generic Credentials
      4. Look for anything that starts with Beanni:
    • MacOS: Keychain

Security, by design

Execution Environment

Beanni all runs locally on your own machine, or your own hosting. There are no shared web services in play.

Secret Storage

Secrets are kept out of configuration files entirely, by design.

Secrets are stored in your operating system's credential store (Credential Manager on Windows, or Keychain on MacOS). We use keytar to do this, which is built and maintained by the Atom project.

Dependency Supply Chain

Our dependency supply chain is the biggest risk. We've been careful to keep our package.json dependencies list short, and highly trustworthy:

Package Weekly Package Downloads Known/Trusted Maintainer
commander >15M
express >5M
inquirer ~10M
js-yaml >10M
keytar >20k Atom
lodash >15M
pug >300k
puppeteer >500k Google Chrome
request ~15M
sqlite >20k
ts-node >1M

It would be very visible if any of these packages, or their dependencies, were to be compromised.

You can compare this table with https://www.npmjs.com/package/beanni (NPM's view of Beanni's dependencies, based on the package we publish), or https://github.com/beanni/beanni/network/dependencies (GitHub's view of Beanni's dependencies, based on what's in source control).

We use Dependabot to ensure we adopt updates to these dependencies as fast as possible. It's a busy little bot.

Development

Ubuntu Dependencies

Run it locally

  1. Clone
  2. npm install
  3. One of:
    • VS Code > Ctrl+F5
    • npx ts-node ./src/app.ts --help

To release (if you have the rights):

  1. Clean git context
  2. npm version major|minor|patch
  3. npm pack
  4. Validate the file list. ⚠ Make sure config.yaml or other dev-local files aren't in there.
  5. npm publish ./beanni-x.x.xx.tgz
  6. git push
  7. git push --tags