Appearance
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
- Define one bank-source interface in
src/banks/: given a bank account, a period and options, returnBankLine[](integer pence, London dates, direction, counterparty, optional bank id) or a clear "not available". - 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. - The reconciliation rules in
src/rules/takeBankLine[]only. Nothing outsidesrc/banks/knows the source.src/banks/still never importssrc/xero/orsrc/hmrc/(CLAUDE.md); a Xero-feed source therefore lives behind the interface in a wiring module, not insidesrc/banks/. - 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.
- 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_accountneeds 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.