🌟 Refactor

- Moved mappings into Sb1 impl
- Moved Actual types to @common
- Moved createDirIfMissing to respective functions
- Refactored main into multiple functions
- Moved create db into Sb1impl and close
- Log requests on info

packages/common/types.ts

@@ -0,0 +1,66 @@
+import type { Dayjs } from "dayjs"
+import type { UUID } from "node:crypto"
+import type { TransactionEntity } from "@actual-app/api/@types/loot-core/types/models"
+
+/**
+ * Defines how to interact with the bank
+ */
+export interface Bank {
+  /**
+   * Fetch all transactions in the specified days, from the given accounts
+   * @param interval Which days to fetch transactions for
+   * @param accountKeys The id of the accounts to fetch transactions from
+   * @returns An array of all transactions
+   */
+  fetchTransactions: (
+    interval: Interval,
+    ...accountKeys: ReadonlyArray<string>
+  ) => Promise<ReadonlyArray<ActualTransaction>>
+
+  /**
+   * Shutdown resources
+   */
+  shutdown: () => Promise<void> | void
+}
+
+export interface Interval {
+  fromDate: Dayjs
+  toDate: Dayjs
+}
+
+/**
+ * Describes how to interact with ActualBudget
+ */
+export interface Actual {
+  /**
+   * Import transactions following the rules defined in the ActualBudget instance
+   * If the transactions exists, it will be updated, or no change should be done.
+   * @param accountId The ActualBudget id to upload to
+   * @param transactions The transactions to import
+   * @returns An object describing what changed
+   */
+  importTransactions: (
+    accountId: UUID,
+    transactions: Iterable<ActualTransaction>,
+  ) => Promise<ImportTransactionsResponse>
+
+  /**
+   * Disconnect from ActualBudget and release resources
+   */
+  shutdown: () => Promise<void>
+}
+
+export interface ActualTransaction extends TransactionEntity {
+  account: UUID
+  payee_name?: string
+}
+
+export interface ImportTransactionsResponse {
+  errors?: Message[]
+  added: number
+  updated: number
+}
+
+export interface Message {
+  message: string
+}

packages/sparebank1/db/queries.ts

@@ -0,0 +1,83 @@
+import Database from "better-sqlite3"
+import dayjs from "dayjs"
+import type { OAuthTokenResponse } from "@sb1/types.ts"
+import type {
+  TokenKey,
+  TokenResponse,
+  TokenResponseRaw,
+} from "@sb1impl/db/types.ts"
+import logger from "@common/logger.ts"
+
+export function createDb(filepath: string) {
+  const db = new Database(filepath)
+  logger.info(`Started Sqlite database at '${filepath}'`)
+  db.pragma("journal_mode = WAL")
+  db.exec(
+    "CREATE TABLE IF NOT EXISTS tokens ('key' VARCHAR PRIMARY KEY, token VARCHAR NOT NULL, expires_at DATETIME NOT NULL)",
+  )
+  return db
+}
+
+export function insertTokens(
+  db: Database.Database,
+  oAuthToken: OAuthTokenResponse,
+): void {
+  insertAccessToken(db, oAuthToken.access_token, oAuthToken.expires_in)
+  insertRefreshToken(
+    db,
+    oAuthToken.refresh_token,
+    oAuthToken.refresh_token_absolute_expires_in,
+  )
+}
+
+function insertAccessToken(
+  db: Database.Database,
+  accessToken: string,
+  expiresIn: number,
+) {
+  insert(db, "access-token", accessToken, expiresIn)
+}
+
+function insertRefreshToken(
+  db: Database.Database,
+  refreshToken: string,
+  expiresIn: number,
+): void {
+  insert(db, "refresh-token", refreshToken, expiresIn)
+}
+
+function insert(
+  db: Database.Database,
+  key: TokenKey,
+  token: string,
+  expiresIn: number,
+): void {
+  db.prepare("INSERT OR REPLACE INTO tokens VALUES (?, ?, ?)").run(
+    key,
+    token,
+    dayjs().add(expiresIn, "seconds").toISOString(),
+  )
+}
+
+export function fetchToken(
+  db: Database.Database,
+  tokenKey: TokenKey,
+): TokenResponse | null {
+  const response = db
+    .prepare("SELECT * FROM tokens WHERE key = ?")
+    .get(tokenKey) as TokenResponseRaw | null
+
+  return (
+    response && {
+      ...response,
+      expires_at: dayjs(response.expires_at),
+    }
+  )
+}
+
+export function clearTokens(db: Database.Database): void {
+  db.prepare("DELETE FROM tokens WHERE key in ( ?, ? )").run([
+    "access-token",
+    "refresh-token",
+  ] as TokenKey[])
+}

packages/sparebank1/db/types.ts

@@ -0,0 +1,13 @@
+import type { Dayjs } from "dayjs"
+
+export type TokenResponse = {
+  key: TokenKey
+  token: string
+  expires_at: Dayjs
+}
+
+export type TokenResponseRaw = {
+  [K in keyof TokenResponse]: K extends "expires_at" ? string : TokenResponse[K]
+}
+
+export type TokenKey = "access-token" | "refresh-token"

packages/sparebank1/mappings.ts

@@ -0,0 +1,46 @@
+import type { UUID } from "node:crypto"
+import dayjs from "dayjs"
+import { ACTUAL_ACCOUNT_IDS, BANK_ACCOUNT_IDS } from "@/config.ts"
+import logger from "@common/logger.ts"
+import { toISODateString } from "@common/date.ts"
+import type { SB1Transaction } from "@sb1/types.ts"
+import type { ActualTransaction } from "@common/types.ts"
+
+export function bankTransactionIntoActualTransaction(
+  transaction: SB1Transaction,
+): ActualTransaction {
+  return {
+    id: transaction.id,
+    // Transactions with the same id will be ignored
+    imported_id: transaction.nonUniqueId,
+    account: getActualAccountId(transaction),
+    // The value without decimals
+    amount: Math.floor(transaction.amount * 100),
+    date: toISODateString(dayjs(transaction.date)),
+    payee_name: transaction.cleanedDescription,
+    // TODO if not cleared or nonUniqueId is 0, rerun later
+    cleared: isCleared(transaction),
+  }
+}
+
+export function isCleared(transaction: SB1Transaction): boolean {
+  const id = Number(transaction.nonUniqueId)
+  return transaction.bookingStatus === "BOOKED" && !Number.isNaN(id) && id > 0
+}
+
+function getActualAccountId(transcation: SB1Transaction): UUID {
+  for (
+    let i = 0;
+    i < Math.min(ACTUAL_ACCOUNT_IDS.length, BANK_ACCOUNT_IDS.length);
+    i++
+  ) {
+    if (BANK_ACCOUNT_IDS[i] === transcation.accountKey) {
+      return ACTUAL_ACCOUNT_IDS[i] as UUID
+    }
+  }
+  const error = new Error(
+    "Failed to find ActualAccountId, length of BANK_ACCOUNT_IDS and ACTUAL_ACCOUNT_IDS must match",
+  )
+  logger.error(error)
+  throw error
+}

packages/sparebank1/sparebank1.ts

@@ -0,0 +1,95 @@
+import {
+  BANK_INITIAL_REFRESH_TOKEN,
+  BANK_OAUTH_CLIENT_ID,
+  BANK_OAUTH_CLIENT_SECRET,
+  DB_DIRECTORY,
+  DB_FILENAME,
+} from "@/config.ts"
+import logger from "@common/logger.ts"
+import dayjs from "dayjs"
+import type { Database } from "better-sqlite3"
+import {
+  clearTokens,
+  createDb,
+  fetchToken,
+  insertTokens,
+} from "@sb1impl/db/queries.ts"
+import * as Oauth from "@sb1/oauth.ts"
+import * as Transactions from "@sb1/transactions.ts"
+import { bankTransactionIntoActualTransaction } from "./mappings.ts"
+import type { OAuthTokenResponse } from "@sb1/types.ts"
+import type { ActualTransaction, Bank, Interval } from "@common/types.ts"
+import type { TokenResponse } from "@sb1impl/db/types.ts"
+import { createDirIfMissing } from "@/fs.ts"
+
+export class Sparebank1Impl implements Bank {
+  private readonly db: Database
+
+  constructor() {
+    createDirIfMissing(DB_DIRECTORY)
+    const databaseFilePath = `${DB_DIRECTORY}/${DB_FILENAME}.sqlite`
+    this.db = createDb(databaseFilePath)
+  }
+
+  async fetchTransactions(
+    interval: Interval,
+    ...accountKeys: ReadonlyArray<string>
+  ): Promise<ReadonlyArray<ActualTransaction>> {
+    const response = await Transactions.list(
+      await this.getAccessToken(),
+      accountKeys,
+      interval,
+    )
+    const sparebankTransactions = response.transactions
+    return sparebankTransactions.map(bankTransactionIntoActualTransaction)
+  }
+
+  shutdown(): void {
+    this.db.close()
+  }
+
+  private async getAccessToken(): Promise<string> {
+    const accessToken = fetchToken(this.db, "access-token")
+
+    if (accessToken && this.isValidToken(accessToken)) {
+      return accessToken.token
+    }
+    const response = await this.fetchNewTokens()
+    return response.access_token
+  }
+
+  private isValidToken(tokenResponse: TokenResponse): boolean {
+    // TODO make sure the same timezone is used. Db uses UTC
+    return dayjs().isBefore(tokenResponse.expires_at)
+  }
+
+  private async getRefreshToken(): Promise<string> {
+    const tokenResponse = fetchToken(this.db, "refresh-token")
+
+    if (!tokenResponse) {
+      return BANK_INITIAL_REFRESH_TOKEN
+    } else if (this.isValidToken(tokenResponse)) {
+      return tokenResponse.token
+    }
+    logger.warn("Refresh token expired, deleting tokens from database")
+    clearTokens(this.db)
+    throw new Error("Refresh token is expired. Create a new one")
+  }
+
+  private async fetchNewTokens(): Promise<OAuthTokenResponse> {
+    const refreshToken = await this.getRefreshToken()
+    const result = await Oauth.refreshToken(
+      BANK_OAUTH_CLIENT_ID,
+      BANK_OAUTH_CLIENT_SECRET,
+      refreshToken,
+    )
+
+    if (result.status === "failure") {
+      throw new Error(`Failed to fetch refresh token: '${result.data}'`)
+    }
+    const oAuthToken = result.data
+
+    insertTokens(this.db, oAuthToken)
+    return oAuthToken
+  }
+}

packages/sparebank1Api/oauth.ts

@@ -1,4 +1,4 @@
-import { OAuthTokenResponse, Result } from "./types"
+import type { OAuthTokenResponse, Result } from "./types"
 import * as querystring from "node:querystring"
 import { baseUrl, failure, success } from "./common"
 import logger from "@common/logger"

packages/sparebank1Api/transactions.ts

@@ -1,8 +1,9 @@
-import type { Interval, TransactionResponse } from "./types"
+import type { TransactionResponse } from "./types"
 import * as querystring from "node:querystring"
 import { toISODateString } from "@common/date"
 import logger from "@common/logger"
 import { baseUrl } from "./common"
+import type { Interval } from "@common/types.ts"
 
 export async function list(
   accessToken: string,
@@ -18,7 +19,7 @@ export async function list(
   })
 
   const url = `${baseUrl}/personal/banking/transactions?${queryString}`
-  logger.debug(`Sending GET request to '${url}'`)
+  logger.info(`GET '${url}'`)
   const response = await fetch(url, {
     headers: {
       Authorization: `Bearer ${accessToken}`,

packages/sparebank1Api/types.ts

@@ -1,14 +1,7 @@
-import type { Dayjs } from "dayjs"
-
 export type Success<T> = { status: "success"; data: T }
 export type Failure<T> = { status: "failure"; data: T }
 export type Result<OK, Err> = Success<OK> | Failure<Err>
 
-export interface Interval {
-  fromDate: Dayjs
-  toDate: Dayjs
-}
-
 export interface OAuthTokenResponse {
   access_token: string
   expires_in: number
@@ -20,6 +13,10 @@ export interface OAuthTokenResponse {
 
 export type BookingStatus = "PENDING" | "BOOKED"
 
+/**
+ * 18-character unique ID used to identify a transaction
+ * The value is "000000000000000000" until the transaction is booked, and might be set a few days later
+ */
 export type NonUniqueId = "000000000000000000" | `${number}`
 
 export interface SB1Transaction {