Kildekode

What is it?

Actual Budget is an open-source budgeting platform, it can very simply be self-hosted and accessed throught the browser. While Sparebank1 is a Norwegian bank, with a great developer experience and an easy to use API that can be used to fetch transactions for example.

Actual has an API that can be used to interact with your own instance of Actual, like importing transactions.

Which is what the Sparebank1 Actual Budget integration does. It fetches transactions from my accounts in Sparebank1 and imports them automatically into Actual. The operation runs daily and can be configured to import from multiple accounts at once.

The purpose of this application is to automatically transfer transactions to the budget, to avoid doing it manually often, or once in a while.

The techy stuff

Since the Actual Budget API is an NPM package, the application had to be created in TypeScript. I looked at options to NodeJS but neither Bun or Deno was compatible with the better-sqlite3 package which was a dependency to the API, so the best option for now was NodeJS.

The application runs a cronJob that executes once a day at 1 am. The specific time is not really that important since it fetches transactions from 3-4 days before the day it runs. This is done to avoid fetching transactions which are not fully cleared yet. Some transactions can even be cleared but the unique Id for the transaction might not be set yet. Actual uses that unique Id in order to avoid duplicate transactions, and makes it possible to update transactions if the content has changed.

Rules can be defined within the Actual application, so transactions are automatically sorted into the correct categories on import.

The application supports importing multiple accounts from a single user. This is done by specifying the account keys to Sparebank1 and a equal length array of ids for the Actual accounts.

Low Coupling

In order to make it easy to reuse the same application for other banks, it was created with low coupling in mind. Interfaces are defined for the different parts of the application, and in order to implement it for any other bank, the Bank interface can be implemented on any class, and requires two methods.

export interface Bank {
  fetchTransactions: (
    interval: Interval,
    ...accountKeys: ReadonlyArray<string>
  ) => Promise<ReadonlyArray<ActualTransaction>>

  shutdown: () => Promise<void> | void
}

Authentication

Both Sparebank1 and Actual requires different secrets and keys to work.

Actual only requires that secrets are passed into the client that handles the requests, but Sparebank1 requires more effort in order to fetch data. First it requires a authentication code that can only be fetched using my own BankID account. The authentication code must be swapped for a refresh token within 2 minutes or the process must be started over. The refresh token has a lifetime of a year unless used, so it can be saved for later use. The refresh token is added as an environmental variable that can be used to fetch the first access token. After that, both the new refresh token and access token is stored in a Sqlite database so they can be reused until they expire.

Deployement

The application runs in a docker container on my Homelab. It is build from a Gitea Act runner that adds the needed secrets and variables from the Gitea instance.

name: Deploy application

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: host

    env:
      # Secrets and vars
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4
      - name: Run docker-compose
        run: docker compose up -d --build

The road ahead

Future plans incude adding more features to the application and some more error handling. Then potentially implementing the integration for other banks or credit cards to automate even more.

I also want to rewrite it in Bun when they implement the needed APIs to get Better-sqlite3 working.