Jakob Wennberg
70845edf69
* feat(transactions): structured transaction_method instead of channel-in-the-name
Swedish bank feeds embed the payment channel in the description string
("Vercel Jul Överföring via internet", "ANTHROPIC* ... Kortköp/uttag"):
the PSD2 remittance array is joined into one string and the ISO 20022
type codes were dropped at insert. This promotes the channel to data:
- transactions.transaction_method (text + CHECK closed vocabulary: card,
transfer, bankgiro, plusgiro, swish, autogiro, e_invoice, international,
deposit, withdrawal, salary, fee, interest, adjustment) plus verbatim
bank_transaction_code / proprietary_bank_transaction_code evidence
columns (data_quality_master Appendix B "Layer-A capture").
- classifyTransactionMethod() in lib/transactions/transaction-method.ts:
explicit source method (Stripe txn.type) > trailing Swedish channel
phrase > ISO 20022 family/subfamily > proprietary-code keywords > MCC.
It also splits the clean display title off the description.
- Ingest stores the clean title as description and the full bank string
as original_description; dedup is untouched (external_id is date+öre,
the content bridge reads original_description and is prefix-based, and
a trailing strip leaves a prefix). Enable Banking passes the codes
through; the Stripe feed sets methods from its balance-txn types.
- Backfill migration classifies existing rows from the description text
(+ MCC and Stripe prefixes) and strips unedited titles; user-edited
titles are never rewritten.
- mapping-engine also matches original_description so user rules written
against the full bank text keep firing.
- UI: the inbox row shows the clean name; clicking it now folds out
"Betalsätt: Kortköp" etc. (sv/en), making every classified row
expandable.
A card purchase implies a physical receipt, a Bankgiro/e-invoice payment
implies a supplier invoice: downstream automations can now branch on the
rail instead of regexing display strings.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(transactions): anchor counterparty-template identity on original_description
Audit follow-up to the phrase-strip change: counterparty template lookup
AND learning derived their key from merchant_name || description. With
the working title now stripped ("SPOTIFY AB Kortköp" -> "SPOTIFY AB"),
templates learned from the full bank string would only re-match via the
occurrence-gated single-token tier, and single-token counterparties with
fewer than 3 bookings would silently stop matching.
Both sides now read merchant_name || original_description || description:
the immutable bank original is identical across eras (and across user
renames), so every stored key and alias keeps matching exactly. Same
anchoring rationale as buildMerchantHistory in category-suggestions.
Existing tests that relied on the fixture's default original_description
now state it explicitly; two new regression tests pin the era stability
(lookup via alias on the full string, learning key derivation).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(transactions): review follow-ups on method classification
- methodFromCodes: two-pass subfamily-then-family scan so a SALA/XBCT
refinement on the proprietary code beats a bare family match on the
ISO code, matching the documented precedence; pinned by a test.
- mapping-engine: regression tests for merchant/description patterns
that only match original_description, including the invalid-regex
substring fallback and the no-match default.
- Stripe: regression test for the SDK-unmodeled 'tax' balance-txn type
mapping to 'fee'.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(transactions): scope method classification to feed rows + adjective guard
Multi-bank risk hardening before the backfill ships:
- Feed-row scope: classification and title stripping now require a real
import feed (import_source present, not manual/mcp), both at the
ingest boundary (USER_CREATED_IMPORT_SOURCES, now exported) and in
every backfill statement. User-authored titles like "Egen insättning"
on manual/MCP rows are never classified and never rewritten.
- Adjective guard (TS + SQL): a strip that would leave the title ending
in a possessive/scope adjective (egen/eget/privat/intern/extern ...)
is skipped, so "Egen insättning" stays whole even on bank-feed rows;
the method column still classifies (deposit).
- Unknown bank phrasings remain untouched by construction: an unmatched
phrase means no method and no rewrite, so the worst case for any bank
whose vocabulary we have not seen is the status quo.
Pinned by new unit + pg-real cases (user-created exclusion for
NULL/manual/mcp, adjective guard, feed defaults in the pg fixture).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(migrations): re-timestamp transaction_method migrations after rebase
Main gained migrations dated 20260729-20260730 (already applied to prod)
while this branch carried 20260728 versions, which would have applied
out-of-order on merge. The files have never reached prod, so renaming to
current timestamps is safe and removes any dependence on the integration's
out-of-order handling. All code/doc references updated; the pg test reads
the backfill by its new filename.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(migrations): bump transaction_method versions past prod's max
Main's newest applied migration is 20260730090000 (future-leaning
timestamp), so the previous 202607300731xx rename still sorted before
prod's tail and risked a silent skip on merge-time apply. Versions are
now 20260730100000/20260730100100, strictly after everything applied to
prod. References updated; full migration stream replays clean.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(transactions): final review round: keyboard guard + bank_connection_id feed marker
- TransactionInboxCard: row-level Enter/Space handling now ignores events
bubbling from nested controls, so keyboard activation of Bokför / the
overflow menu is no longer cancelled by the (now much more common)
expandable row.
- Feed predicate parity with isImportedTransaction(): a live
bank_connection_id marks a feed row even when import_source is unset
(the oldest PSD2 rows predate that column), in both the ingest
classifier and every backfill statement: those legacy rows now get
classified instead of being skipped as user-created.
- pg fixture typing uses the TransactionMethod union.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(migrations): re-timestamp transaction_method migrations past prod's 20260807 tail
Prod max applied is 20260807170000 (verified by name via list_migrations);
the 20260730-stamped pair would sort before it. References in code,
tests, and DECISIONS.md updated to the new versions.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(migrations): enforce, not assume, original_description preservation in the title strip
The strip UPDATE now fills a NULL original_description from the
pre-strip description in the same statement. Prod has zero such rows
(0/25,566 feed-scope rows, verified read-only), and 20260605120000's
backfill plus ingest make the NULL case unreachable on any DB that
replayed history, but the migration should not depend on that history
to avoid losing the only copy of a bank string.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: record the compliance-review triage of the backfill's booked-row title strip
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Jakob Wennberg <jakob.wennberg@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com>
64 lines
3.1 KiB
TypeScript
64 lines
3.1 KiB
TypeScript
/**
|
|
* Transaction origin helpers: distinguish rows the user created INSIDE the app
|
|
* from rows that were fetched/imported from an external feed (bank sync or a
|
|
* bank-file upload).
|
|
*
|
|
* Why this matters
|
|
* ----------------
|
|
* An imported row is an external system's record of money that actually moved.
|
|
* The user may *ignore* it (`is_ignored`) to take it off the to-book /
|
|
* reconciliation lists, but must never be able to *delete* it: deleting would
|
|
* silently drop a real bank line, and the next sync (or a re-import of the same
|
|
* file) would either bring it back as a "new" row or, worse, leave the books
|
|
* out of step with the bank. Only hand-entered rows are the user's to remove.
|
|
*
|
|
* The two import paths that populate `transactions` from outside the app:
|
|
* - Enable Banking (PSD2) live sync → sets `bank_connection_id`
|
|
* (and `import_source = 'enable_banking'`). See
|
|
* `extensions/general/enable-banking/lib/sync.ts`.
|
|
* - Bank-file import (CSV / CAMT053) → sets `import_source` to `'camt053'` or
|
|
* `'csv_<format>'` (no live connection). See
|
|
* `app/api/import/bank-file/execute/route.ts`.
|
|
*
|
|
* Everything else is user-created and therefore deletable (subject to the
|
|
* separate "booked rows are immutable" rule):
|
|
* - manual add via POST /api/transactions → `import_source = null`
|
|
* - create-from-document → `import_source = 'manual'`
|
|
* - MCP / agent create → `import_source = 'mcp'`
|
|
*
|
|
* Safe-by-default: this is an ALLOWLIST of known user-created sources. Any other
|
|
* `import_source` tag (including an import feed added in the future) is
|
|
* treated as imported (ignore-only), so a new feed can never accidentally
|
|
* become user-deletable before someone consciously adds it here.
|
|
*/
|
|
|
|
/** Minimal shape: the two columns that record where a transaction came from. */
|
|
export type TransactionOrigin = {
|
|
bank_connection_id?: string | null
|
|
import_source?: string | null
|
|
}
|
|
|
|
/**
|
|
* `import_source` values produced by in-app creation flows. A `null` source
|
|
* (with no bank connection) is also user-created: that's the plain manual-add
|
|
* path. Anything NOT in this set is considered an external import feed.
|
|
* Exported for the ingest boundary: transaction_method classification and
|
|
* title stripping are feed-row concepts and must skip user-created sources.
|
|
*/
|
|
export const USER_CREATED_IMPORT_SOURCES: ReadonlySet<string> = new Set(['manual', 'mcp'])
|
|
|
|
/**
|
|
* True when the transaction was fetched via bank sync or uploaded via a
|
|
* bank-file import, i.e. NOT created by the user inside the app. Such rows are
|
|
* ignore-only and can never be deleted (booked or not).
|
|
*/
|
|
export function isImportedTransaction(tx: TransactionOrigin): boolean {
|
|
// A live bank connection is the unambiguous PSD2 marker (Enable Banking).
|
|
if (tx.bank_connection_id) return true
|
|
const src = tx.import_source
|
|
// No source and no bank link → a hand-entered row.
|
|
if (src == null) return false
|
|
// Known in-app sources are user-created; everything else is an import feed.
|
|
return !USER_CREATED_IMPORT_SOURCES.has(src)
|
|
}
|