@actual-app/sync-server 25.4.0-alpha.0

package/src/app-gocardless/app-gocardless.js

@@ -0,0 +1,274 @@
+import path from 'path';
+import { inspect } from 'util';
+
+import { isAxiosError } from 'axios';
+import express from 'express';
+
+import { sha256String } from '../util/hash.js';
+import {
+  requestLoggerMiddleware,
+  validateSessionMiddleware,
+} from '../util/middlewares.js';
+
+import {
+  AccountNotLinkedToRequisition,
+  GenericGoCardlessError,
+  RateLimitError,
+  RequisitionNotLinked,
+} from './errors.js';
+import { goCardlessService } from './services/gocardless-service.js';
+import { handleError } from './util/handle-error.js';
+
+const app = express();
+app.use(requestLoggerMiddleware);
+
+app.get('/link', function (req, res) {
+  res.sendFile('link.html', { root: path.resolve('./src/app-gocardless') });
+});
+
+export { app as handlers };
+app.use(express.json());
+app.use(validateSessionMiddleware);
+
+app.post('/status', async (req, res) => {
+  res.send({
+    status: 'ok',
+    data: {
+      configured: goCardlessService.isConfigured(),
+    },
+  });
+});
+
+app.post(
+  '/create-web-token',
+  handleError(async (req, res) => {
+    const { institutionId } = req.body;
+    const { origin } = req.headers;
+
+    const { link, requisitionId } = await goCardlessService.createRequisition({
+      institutionId,
+      host: origin,
+    });
+
+    res.send({
+      status: 'ok',
+      data: {
+        link,
+        requisitionId,
+      },
+    });
+  }),
+);
+
+app.post(
+  '/get-accounts',
+  handleError(async (req, res) => {
+    const { requisitionId } = req.body;
+
+    try {
+      const { requisition, accounts } =
+        await goCardlessService.getRequisitionWithAccounts(requisitionId);
+
+      res.send({
+        status: 'ok',
+        data: {
+          ...requisition,
+          accounts: await Promise.all(
+            accounts.map(async account =>
+              account?.iban
+                ? { ...account, iban: await sha256String(account.iban) }
+                : account,
+            ),
+          ),
+        },
+      });
+    } catch (error) {
+      if (error instanceof RequisitionNotLinked) {
+        res.send({
+          status: 'ok',
+          requisitionStatus: error.details.requisitionStatus,
+        });
+      } else {
+        throw error;
+      }
+    }
+  }),
+);
+
+app.post(
+  '/get-banks',
+  handleError(async (req, res) => {
+    const { country, showDemo = false } = req.body;
+
+    await goCardlessService.setToken();
+    const data = await goCardlessService.getInstitutions(country);
+
+    res.send({
+      status: 'ok',
+      data: showDemo
+        ? [
+            {
+              id: 'SANDBOXFINANCE_SFIN0000',
+              name: 'DEMO bank (used for testing bank-sync)',
+            },
+            ...data,
+          ]
+        : data,
+    });
+  }),
+);
+
+app.post(
+  '/remove-account',
+  handleError(async (req, res) => {
+    const { requisitionId } = req.body;
+
+    const data = await goCardlessService.deleteRequisition(requisitionId);
+    if (data.summary === 'Requisition deleted') {
+      res.send({
+        status: 'ok',
+        data,
+      });
+    } else {
+      res.send({
+        status: 'error',
+        data: {
+          data,
+          reason: 'Can not delete requisition',
+        },
+      });
+    }
+  }),
+);
+
+app.post(
+  '/transactions',
+  handleError(async (req, res) => {
+    const {
+      requisitionId,
+      startDate,
+      endDate,
+      accountId,
+      includeBalance = true,
+    } = req.body;
+
+    try {
+      if (includeBalance) {
+        const {
+          balances,
+          institutionId,
+          startingBalance,
+          transactions: { booked, pending, all },
+        } = await goCardlessService.getTransactionsWithBalance(
+          requisitionId,
+          accountId,
+          startDate,
+          endDate,
+        );
+
+        res.send({
+          status: 'ok',
+          data: {
+            balances,
+            institutionId,
+            startingBalance,
+            transactions: {
+              booked,
+              pending,
+              all,
+            },
+          },
+        });
+      } else {
+        const {
+          institutionId,
+          transactions: { booked, pending, all },
+        } = await goCardlessService.getNormalizedTransactions(
+          requisitionId,
+          accountId,
+          startDate,
+          endDate,
+        );
+
+        res.send({
+          status: 'ok',
+          data: {
+            institutionId,
+            transactions: {
+              booked,
+              pending,
+              all,
+            },
+          },
+        });
+      }
+    } catch (error) {
+      const headers = error.details?.response?.headers ?? {};
+
+      const rateLimitHeaders = Object.fromEntries(
+        Object.entries(headers).filter(([key]) =>
+          key.startsWith('http_x_ratelimit'),
+        ),
+      );
+
+      const sendErrorResponse = data =>
+        res.send({
+          status: 'ok',
+          data: { ...data, details: error.details, rateLimitHeaders },
+        });
+
+      switch (true) {
+        case error instanceof RequisitionNotLinked:
+          sendErrorResponse({
+            error_type: 'ITEM_ERROR',
+            error_code: 'ITEM_LOGIN_REQUIRED',
+            status: 'expired',
+            reason:
+              'Access to account has expired as set in End User Agreement',
+          });
+          break;
+        case error instanceof AccountNotLinkedToRequisition:
+          sendErrorResponse({
+            error_type: 'INVALID_INPUT',
+            error_code: 'INVALID_ACCESS_TOKEN',
+            status: 'rejected',
+            reason: 'Account not linked with this requisition',
+          });
+          break;
+        case error instanceof RateLimitError:
+          sendErrorResponse({
+            error_type: 'RATE_LIMIT_EXCEEDED',
+            error_code: 'NORDIGEN_ERROR',
+            status: 'rejected',
+            reason: 'Rate limit exceeded',
+          });
+          break;
+        case error instanceof GenericGoCardlessError:
+          console.log('Something went wrong', inspect(error, { depth: null }));
+          sendErrorResponse({
+            error_type: 'SYNC_ERROR',
+            error_code: 'NORDIGEN_ERROR',
+          });
+          break;
+        case isAxiosError(error):
+          console.log(
+            'Something went wrong',
+            inspect(error.response?.data || error, { depth: null }),
+          );
+          sendErrorResponse({
+            error_type: 'SYNC_ERROR',
+            error_code: 'NORDIGEN_ERROR',
+          });
+          break;
+        default:
+          console.log('Something went wrong', inspect(error, { depth: null }));
+          sendErrorResponse({
+            error_type: 'UNKNOWN',
+            error_code: 'UNKNOWN',
+            reason: 'Something went wrong',
+          });
+          break;
+      }
+    }
+  }),
+);

package/src/app-gocardless/bank-factory.js

@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import IntegrationBank from './banks/integration-bank.js';
+
+const dirname = path.resolve(fileURLToPath(import.meta.url), '..');
+const banksDir = path.resolve(dirname, 'banks');
+
+async function loadBanks() {
+  const bankHandlers = fs
+    .readdirSync(banksDir)
+    .filter(filename => filename.includes('_') && filename.endsWith('.js'));
+
+  const imports = await Promise.all(
+    bankHandlers.map(file => {
+      const fileUrlToBank = pathToFileURL(path.resolve(banksDir, file)); // pathToFileURL for ESM compatibility
+      return import(fileUrlToBank.toString()).then(handler => handler.default);
+    }),
+  );
+
+  return imports;
+}
+
+export const banks = await loadBanks();
+
+export function BankFactory(institutionId) {
+  return (
+    banks.find(b => b.institutionIds.includes(institutionId)) || IntegrationBank
+  );
+}
+
+export const BANKS_WITH_LIMITED_HISTORY = [
+  'AIRBANK_AIRACZPP',
+  'BANCA_AIDEXA_AIDXITMM',
+  'BANCA_PATRIMONI_SENVITT1',
+  'BANCA_SELLA_SELBIT2B',
+  'BANK_MILLENNIUM_BIGBPLPW',
+  'BANKINTER_BKBKESMM',
+  'BBVA_BBVAESMM',
+  'BNP_PL_PPABPLPK',
+  'BRED_BREDFRPPXXX',
+  'CAIXA_GERAL_DEPOSITOS_CGDIPTPL',
+  'CAIXABANK_CAIXESBB',
+  'CARTALIS_CIMTITR1',
+  'CESKA_SPORITELNA_LONG_GIBACZPX',
+  'COOP_EKRDEE22',
+  'DKB_BYLADEM1',
+  'DOTS_HYEEIT22',
+  'FINECO_FEBIITM2XXX',
+  'FINECO_UK_FEBIITM2XXX',
+  'FORTUNEO_FTNOFRP1XXX',
+  'HYPE_BUSINESS_HYEEIT22',
+  'HYPE_HYEEIT22',
+  'ILLIMITY_ITTPIT2M',
+  'INDUSTRA_MULTLV2X',
+  'INDUSTRIEL_CMCIFRPAXXX',
+  'JEKYLL_JEYKLL002',
+  'KBC_KREDBEBB',
+  'LABORALKUTXA_CLPEES2M',
+  'LHV_LHVBEE22',
+  'LUMINOR_AGBLLT2X',
+  'LUMINOR_NDEAEE2X',
+  'LUMINOR_NDEALT2X',
+  'LUMINOR_NDEALV2X',
+  'LUMINOR_RIKOEE22',
+  'LUMINOR_RIKOLV2X',
+  'MBANK_RETAIL_BREXPLPW',
+  'MEDICINOSBANK_MDBALT22XXX',
+  'NORDEA_NDEADKKK',
+  'N26_NTSBDEB1',
+  'OPYN_BITAITRRB2B',
+  'PAYTIPPER_PAYTITM1',
+  'QONTO_QNTOFRP1',
+  'REVOLUT_REVOLT21',
+  'SANTANDER_BSCHESMM',
+  'SANTANDER_DE_SCFBDE33',
+  'SEB_CBVILT2X',
+  'SEB_EEUHEE2X',
+  'SEB_UNLALV2X',
+  'SELLA_PERSONAL_CREDIT_SELBIT22',
+  'BANCOACTIVOBANK_ACTVPTPL',
+  'SMARTIKA_SELBIT22',
+  'SWEDBANK_HABAEE2X',
+  'SWEDBANK_HABALT22',
+  'SWEDBANK_HABALV22',
+  'SWEDBANK_SWEDSESS',
+  'TIM_HYEEIT22',
+  'TOT_SELBIT2B',
+  'VUB_BANKA_SUBASKBX',
+];

package/src/app-gocardless/banks/abanca_caglesmm.js

@@ -0,0 +1,22 @@
+import Fallback from './integration-bank.js';
+
+/** @type {import('./bank.interface.js').IBank} */
+export default {
+  ...Fallback,
+
+  institutionIds: [
+    'ABANCA_CAGLESMM',
+    'ABANCA_CAGLPTPL',
+    'ABANCA_CORP_CAGLPTPL',
+  ],
+
+  // Abanca transactions doesn't get the creditorName/debtorName properly
+  normalizeTransaction(transaction, booked) {
+    const editedTrans = { ...transaction };
+
+    editedTrans.creditorName = transaction.remittanceInformationStructured;
+    editedTrans.debtorName = transaction.remittanceInformationStructured;
+
+    return Fallback.normalizeTransaction(transaction, booked, editedTrans);
+  },
+};

package/src/app-gocardless/banks/abnamro_abnanl2a.js

@@ -0,0 +1,57 @@
+import { amountToInteger } from '../utils.js';
+
+import Fallback from './integration-bank.js';
+
+/** @type {import('./bank.interface.js').IBank} */
+export default {
+  ...Fallback,
+
+  institutionIds: ['ABNAMRO_ABNANL2A'],
+
+  normalizeTransaction(transaction, booked) {
+    const editedTrans = { ...transaction };
+
+    // There is no remittanceInformationUnstructured, so we'll make it
+    editedTrans.remittanceInformationUnstructured =
+      transaction.remittanceInformationUnstructuredArray.join(', ');
+
+    // Remove clutter to extract the payee from remittanceInformationUnstructured ...
+    // ... when not otherwise provided.
+    const payeeName = transaction.remittanceInformationUnstructuredArray
+      .map(el => el.match(/^(?:.*\*)?(.+),PAS\d+$/))
+      .find(match => match)?.[1];
+
+    editedTrans.debtorName = transaction.debtorName || payeeName;
+    editedTrans.creditorName = transaction.creditorName || payeeName;
+
+    editedTrans.date = transaction.valueDateTime.slice(0, 10);
+
+    return Fallback.normalizeTransaction(transaction, booked, editedTrans);
+  },
+
+  sortTransactions(transactions = []) {
+    return transactions.sort(
+      (a, b) => +new Date(b.valueDateTime) - +new Date(a.valueDateTime),
+    );
+  },
+
+  calculateStartingBalance(sortedTransactions = [], balances = []) {
+    if (sortedTransactions.length) {
+      const oldestTransaction =
+        sortedTransactions[sortedTransactions.length - 1];
+      const oldestKnownBalance = amountToInteger(
+        oldestTransaction.balanceAfterTransaction.balanceAmount.amount,
+      );
+      const oldestTransactionAmount = amountToInteger(
+        oldestTransaction.transactionAmount.amount,
+      );
+
+      return oldestKnownBalance - oldestTransactionAmount;
+    } else {
+      return amountToInteger(
+        balances.find(balance => 'interimBooked' === balance.balanceType)
+          .balanceAmount.amount,
+      );
+    }
+  },
+};

package/src/app-gocardless/banks/american_express_aesudef1.js

@@ -0,0 +1,40 @@
+import { amountToInteger } from '../utils.js';
+
+import Fallback from './integration-bank.js';
+
+/** @type {import('./bank.interface.js').IBank} */
+export default {
+  ...Fallback,
+
+  institutionIds: ['AMERICAN_EXPRESS_AESUDEF1'],
+
+  normalizeAccount(account) {
+    return {
+      ...Fallback.normalizeAccount(account),
+      // The `iban` field for these American Express cards is actually a masked
+      // version of the PAN.  No IBAN is provided.
+      mask: account.iban.slice(-5),
+      iban: null,
+      name: [account.details, `(${account.iban.slice(-5)})`].join(' '),
+      official_name: account.details,
+    };
+  },
+
+  /**
+   *  For AMERICAN_EXPRESS_AESUDEF1 we don't know what balance was
+   *  after each transaction so we have to calculate it by getting
+   *  current balance from the account and subtract all the transactions
+   *
+   *  As a current balance we use the non-standard `information` balance type
+   *  which is the only one provided for American Express.
+   */
+  calculateStartingBalance(sortedTransactions = [], balances = []) {
+    const currentBalance = balances.find(
+      balance => 'information' === balance.balanceType.toString(),
+    );
+
+    return sortedTransactions.reduce((total, trans) => {
+      return total - amountToInteger(trans.transactionAmount.amount);
+    }, amountToInteger(currentBalance.balanceAmount.amount));
+  },
+};

package/src/app-gocardless/banks/bancsabadell_bsabesbbb.js

@@ -0,0 +1,31 @@
+import Fallback from './integration-bank.js';
+
+/** @type {import('./bank.interface.js').IBank} */
+export default {
+  ...Fallback,
+
+  institutionIds: ['BANCSABADELL_BSABESBB'],
+
+  // Sabadell transactions don't get the creditorName/debtorName properly
+  normalizeTransaction(transaction, booked) {
+    const editedTrans = { ...transaction };
+
+    const amount = transaction.transactionAmount.amount;
+
+    // The amount is negative for outgoing transactions, positive for incoming transactions.
+    const isCreditorPayee = Number.parseFloat(amount) < 0;
+
+    const payeeName = transaction.remittanceInformationUnstructuredArray
+      .join(' ')
+      .trim();
+
+    // The payee name is the creditor name for outgoing transactions and the debtor name for incoming transactions.
+    const creditorName = isCreditorPayee ? payeeName : null;
+    const debtorName = isCreditorPayee ? null : payeeName;
+
+    editedTrans.creditorName = creditorName;
+    editedTrans.debtorName = debtorName;
+
+    return Fallback.normalizeTransaction(transaction, booked, editedTrans);
+  },
+};

package/src/app-gocardless/banks/bank.interface.ts

@@ -0,0 +1,51 @@
+import { Transaction, Balance } from '../gocardless-node.types.js';
+import {
+  DetailedAccountWithInstitution,
+  NormalizedAccountDetails,
+} from '../gocardless.types.js';
+
+type TransactionExtended = Transaction & {
+  date?: string;
+  payeeName?: string;
+  notes?: string;
+  remittanceInformationUnstructuredArrayString?: string;
+  remittanceInformationStructuredArrayString?: string;
+};
+
+export interface IBank {
+  institutionIds: string[];
+
+  /**
+   * Returns normalized object with required data for the frontend
+   */
+  normalizeAccount: (
+    account: DetailedAccountWithInstitution,
+  ) => NormalizedAccountDetails;
+
+  /**
+   * Returns a normalized transaction object
+   *
+   * The GoCardless integrations with different banks are very inconsistent in
+   * what each of the different date fields actually mean, so this function is
+   * expected to set a `date` field which corresponds to the expected
+   * transaction date.
+   */
+  normalizeTransaction: (
+    transaction: TransactionExtended,
+    booked: boolean,
+    editedTransaction?: TransactionExtended,
+  ) => TransactionExtended | null;
+
+  /**
+   * Function sorts an array of transactions from newest to oldest
+   */
+  sortTransactions: <T extends Transaction>(transactions: T[]) => T[];
+
+  /**
+   * Calculates account balance before which was before transactions provided in sortedTransactions param
+   */
+  calculateStartingBalance: (
+    sortedTransactions: Transaction[],
+    balances: Balance[],
+  ) => number;
+}

package/src/app-gocardless/banks/bank_of_ireland_b365_bofiie2d.js

@@ -0,0 +1,39 @@
+import Fallback from './integration-bank.js';
+
+/** @type {import('./bank.interface.js').IBank} */
+export default {
+  ...Fallback,
+
+  institutionIds: ['BANK_OF_IRELAND_B365_BOFIIE2D'],
+
+  normalizeTransaction(transaction, booked) {
+    const editedTrans = { ...transaction };
+
+    editedTrans.remittanceInformationUnstructured = fixupPayee(
+      transaction.remittanceInformationUnstructured,
+    );
+
+    return Fallback.normalizeTransaction(transaction, booked, editedTrans);
+  },
+};
+
+function fixupPayee(/** @type {string} */ payee) {
+  let fixedPayee = payee;
+
+  // remove all duplicate whitespace
+  fixedPayee = fixedPayee.replace(/\s+/g, ' ').trim();
+
+  // remove date prefix
+  fixedPayee = fixedPayee.replace(/^(POS)?(C)?[0-9]{1,2}\w{3}/, '').trim();
+
+  // remove direct debit postfix
+  fixedPayee = fixedPayee.replace(/sepa dd$/i, '').trim();
+
+  // remove bank transfer prefix
+  fixedPayee = fixedPayee.replace(/^365 online/i, '').trim();
+
+  // remove curve card prefix
+  fixedPayee = fixedPayee.replace(/^CRV\*/, '').trim();
+
+  return fixedPayee;
+}

package/src/app-gocardless/banks/bankinter_bkbkesmm.js

@@ -0,0 +1,24 @@
+import Fallback from './integration-bank.js';
+
+/** @type {import('./bank.interface.js').IBank} */
+export default {
+  ...Fallback,
+
+  institutionIds: ['BANKINTER_BKBKESMM'],
+
+  normalizeTransaction(transaction, booked) {
+    const editedTrans = { ...transaction };
+
+    editedTrans.remittanceInformationUnstructured =
+      transaction.remittanceInformationUnstructured
+        .replaceAll(/\/Txt\/(\w\|)?/gi, '')
+        .replaceAll(';', ' ');
+
+    editedTrans.debtorName = transaction.debtorName?.replaceAll(';', ' ');
+    editedTrans.creditorName =
+      transaction.creditorName?.replaceAll(';', ' ') ??
+      editedTrans.remittanceInformationUnstructured;
+
+    return Fallback.normalizeTransaction(transaction, booked, editedTrans);
+  },
+};

package/src/app-gocardless/banks/belfius_gkccbebb.js

@@ -0,0 +1,17 @@
+import Fallback from './integration-bank.js';
+
+/** @type {import('./bank.interface.js').IBank} */
+export default {
+  ...Fallback,
+
+  institutionIds: ['BELFIUS_GKCCBEBB'],
+
+  // The problem is that we have transaction with duplicated transaction ids.
+  // This is not expected and the nordigen api has a work-around for some backs
+  // They will set an internalTransactionId which is unique
+  normalizeTransaction(transaction, booked) {
+    transaction.transactionId = transaction.internalTransactionId;
+
+    return Fallback.normalizeTransaction(transaction, booked);
+  },
+};