Skip to content

0034: One bank-source interface for statement import, Starling and aggregators ​

Status note: the Starling and aggregator sources are superseded by ADR 0035 (2026-10-08); statement import is the only source.

Context ​

ADR 0015 made bank reading provider-neutral in principle (bank_account.source = Starling token, statement file or aggregator) and said the rules never know the source. In code, src/banks/read-lines.ts still special-cases Starling and the Amex CSV format. SPEC-013 (issue #225) adds any bank's CSV or OFX file with a saved column mapping, and may later add Xero feed lines and Finexer. Xero's unreconciled statement lines are not in the Accounting API; they sit behind restricted Finance API access (SPEC-013, QD-39).

Decision ​

  1. Define one bank-source interface in src/banks/: given a bank account, a period and options, return BankLine[] (integer pence, London dates, direction, counterparty, optional bank id) or a clear "not available".
  2. Implementations: statement import (CSV and OFX, saved mapping per account), Starling API, and later Finexer and a Xero Finance API feed if access is granted. Each is chosen by bank_account.source.
  3. The reconciliation rules in src/rules/ take BankLine[] only. Nothing outside src/banks/ knows the source. src/banks/ still never imports src/xero/ or src/hmrc/ (CLAUDE.md); a Xero-feed source therefore lives behind the interface in a wiring module, not inside src/banks/.
  4. Every source keeps the guards: the owner confirms statement files, the statement text is processed in memory and never stored (ADR 0032), errors do not echo content, and a missing or unavailable source never falls back silently to Xero's own records.
  5. Statement import is the baseline every bank can use; live sources are conveniences, not requirements.

Why ​

Customers bank anywhere. File import works on day one for any bank with no licence, aggregator or Xero approval. A single interface keeps the rules and tests the same however lines arrive, and lets Finexer drop in later (ADR 0015) without touching the check.

Consequences ​

  • The Amex parser becomes a preset of the generic importer; its tests must pass unchanged.
  • bank_account needs a migration (expand, then contract, ADR 0029) and a new mapping table; mappings hold column names, never statement content.
  • Starling keeps working as one source; its token handling is unchanged.
  • Slice (c) of SPEC-013 depends on Xero's answer (QD-39). If refused, the interface still serves the other sources.
  • Customers must supply their own files for statement import, which ADR 0032 and QD-29 already accept for a customer's own statements.