Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
bc04875
money: scaffold the Money drive app (view, controller, fake store, bu…
Sep 24, 2026
5b1345f
money: shared plugin shell tokens and components in app/ui/ (M-2)
Sep 24, 2026
87bafe4
money: exact-decimal formatting, totals and day grouping (M-3)
Sep 24, 2026
f3477ba
money: Transactions tab ledger with filters, search and summary strip…
Sep 24, 2026
d6456fd
money: declare category and note annotations on bank transactions (M-5)
Sep 24, 2026
48fdeb6
money: transaction detail with category and note saved on blur (M-6)
Sep 24, 2026
6e86815
money: structured statement errors with codes and data (M-9)
Sep 24, 2026
4390c9d
money: in-app import sheet: check, preview, designed errors (M-10, pa…
Sep 24, 2026
ca01f14
money: Imports tab built from the imported rows (M-11, partial)
Sep 24, 2026
7ac0f5e
money: accessibility and responsive checks, shortcuts popover (M-13)
Sep 24, 2026
0c3a623
money: minify the app bundle and its embedded stylesheets
Sep 24, 2026
a4dcae3
money: document the Money app, re-verify the importer at the new pin
Sep 24, 2026
41e8843
money: host E2E for the Money app as a view of the Bank transactions …
Sep 24, 2026
dae051e
money: keep the compare table's labels whole at 360 px
Sep 24, 2026
d6e91b3
money e2e: pick the release card by the id just published
Sep 24, 2026
4d106d2
money: use the 007869464 host APIs where the app had fallbacks
Sep 24, 2026
39303d3
money: README: verified at 007869464, e2e passes on a reused lane store
Sep 24, 2026
6fa6be9
money: store each imported statement with its balances in a second ta…
Sep 25, 2026
46449be
money: statements, row editing and import through the host (M-6, M-10…
Sep 25, 2026
a1d3c52
money: host E2E through the real review and Allow editing; statement …
Sep 25, 2026
ff4aca8
money: keep the preview's New / Already imported tabs in reach
Sep 25, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 94 additions & 9 deletions integrations/money/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
This needs an atomic-server with the generic file entry point
(atomic-server#1653: manifest `accepts` and `destination`, and the Import tab
on a plugin's page; merged as atomic-server#1691). The pinned
`.atomic-server-ref`, `2f403624e`, includes it; see [Verified](#verified).
`.atomic-server-ref`, `bc39dac4b`, includes it; see [Verified](#verified).

1. **Publish** (once per server, by whoever maintains it): create a Plugin,
replace its source with this folder's `plugin.js`, name it "Bank
Expand All @@ -15,10 +15,15 @@ on a plugin's page; merged as atomic-server#1691). The pinned
2. **Find it**: Integrations → Show experimental plugins → Community
plugins → Bank statements → Open → Create draft.
3. **Set up**: on the draft's Import tab, choose Set up. This creates the
banking properties and the Bank transactions class in the drive ontology,
and a Bank transactions table with a default view beneath the importer. It
stores `{ table, rowClass, properties }` as the importer's config, under
the key `money`.
banking properties and the Bank transaction and Bank statement classes in
the drive ontology, and two tables with default views beneath the
importer: Bank transactions, and Imported statements (one row per
statement with its reconciled opening and closing balances, through the
manifest's `destination.tables`, atomic-server#1768). It stores
`{ table, rowClass, properties, tables: { statements: { table, rowClass } } }`
as the importer's config, under the key `money`. An importer set up before
the statements table existed pauses on the missing `tables`; running Set
up again adds only the missing table.
4. **Import**: choose an MT940 or camt.053 (ISO 20022 XML) file, then
Preview import, then Apply. The format is detected from the file contents:
XML is read as camt.053, and anything else as MT940. Nothing is written
Expand Down Expand Up @@ -47,6 +52,15 @@ No network operations or secrets are declared. File contents are runtime input,
not plugin source. Proposals and approved transactions contain financial data
and are handled by the user's AtomicServer; they are not sent to an LLM.

`app/` is a separate drive app (shape 1 in AGENTS.md), the Money view of the
same Bank transactions table ([design](design/DESIGN.md), #89). It never runs
in the QuickJS sandbox and never writes imported bank fields: the importer
above stays their only writer. `app/build.mjs` bundles it to one ES module
exporting `view({ root, store })`, with no stylesheet file and no network
code. It reads the table the host points it at (`store.getData()`), finds the
banking properties through the table's row class, and subscribes to the table
so rows from a new import appear without a reload.

Amounts are exact signed decimal **strings**, not floating point numbers.
Opening/closing balances are reconciled with integer arithmetic (up to five
fractional digits). Dates have no inferred time zone. Original :86: descriptions
Expand Down Expand Up @@ -94,6 +108,16 @@ offline peers still need collision resolution after synchronization.
since-removed `ImportMT940` upload dialog. Private bank data is not committed. Synthetic fixtures
test format behavior; this does not establish compatibility with every bank's
dialect.
- `money-category` and `money-note` (the person's own category and note,
edited in the Money app) are declared on the Bank transaction class but
never written by the importer, so a reimport leaves them alone
(`plugin.test.ts`). The category is free text; a Category resource was
the alternative (issues.md M-5) and is not built. Installations set up
before these properties existed do not have them: running Set up again
goes through `ensureSchema`, which creates missing terms by `localId`,
but whether it also adds them to an existing class's `recommends` is not
verified. Until the class declares both, the app shows Category and Note
as unavailable instead of writing undeclared properties.
- Set up reuses the table and view (found by `localId` beneath the importer)
when it runs again after a lost response. Schema creation goes through the
host's `ensureSchema`, which finds existing terms by `localId`.
Expand All @@ -112,15 +136,76 @@ Bundle: `./browser/node_modules/.bin/esbuild integrations/money/plugin.ts --pres
Browser: `node integrations/tooling/run-lane.mjs money --tier e2e` runs
`e2e/money.spec.ts` against `ATOMIC_SERVER_CHECKOUT`'s `target/e2e` build.

## Money app (`app/`)

A drive app (DESIGN.md in [`design/`](design/DESIGN.md), #89) that shows the
Bank transactions table as a ledger. It is a view of the table it is opened
on (`store.getData()`), so it belongs on the importer's table as an app
view; the table's own Table tab stays next to it.

- **Transactions**: account switcher (account + currency), a strip per
account + currency (never summed across currencies) with the latest stored
closing balance in the period and its date, or the period's net where no
statement ends in it (never a balance computed from rows), money in and
out; search over description and reference, period, direction and
Uncategorised filters, a day-grouped ledger (a table at 560 px and wider,
a list of buttons below), 200 rows at a time. Amounts are formatted from
their exact strings (`app/amounts.ts`); sums use `parser.ts`'s `units()`.
- **Detail**: the bank's fields read-only with the verbatim narrative;
category and note (`money-category`, `money-note`) saved on change. The
host lets an app edit the rows of the table it views only after the
person allows it (`rowAccess`/`requestRowAccess`, atomic-server#1788):
the detail says so up front, saving asks in the host's bar while the typed
text stays, and a refusal is shown with a way to ask again.
- **Import statement**: checks a chosen or dropped file in the browser
with the importer's own readers and identity rules (`app/check.ts`,
`identity.ts`), shows the reconciliation per statement and what is new,
already imported or blocked, or a designed error, and then imports it
through the importer with the host's own review (`importer.run`,
atomic-server#1774). Nothing is written before Apply there.
- **Imports**: the stored statements, with period, opening → closing,
entries and import date; on a table without them, one row per statement
the transactions came from.
- **Sources**: statement files; Moneybird and QuickBooks shown as not
available yet.

Each host call is feature-detected (`getMany`, `getTheme`/`onThemeChange`,
`--t-color-success`, `openResource`, `rowAccess`, `importer.run`,
`getData().tables`), so on an older host the app falls back: rows one by
one, a pointer to the importer's Import tab instead of Import, the host's
refusal instead of a save, statements derived from the rows.

Evidence: unit tests with a fake store that models both a current and an
older host (`app/*.test.ts`), screenshots and axe from
`app/harness/screenshots.mjs`, and a host E2E test in `e2e/money.spec.ts`
against `bc39dac4b`: it sets up the importer, installs the built app
test-side as a new App that renders bank transactions, adds it as a
read-only view through Add view, imports the synthetic MT940 from inside
the app through the host's review, checks the strip's closing balance and
the Imports tab, saves a category after clicking the host's "Allow
editing", and checks the in-app check (nothing new; a changed transaction
blocks). Not yet: installing from the catalog (no catalog entry).

Build: `node integrations/money/app/build.mjs` (writes `app/dist/ui.js`,
minified, one module). Screenshots, axe and the render budget:
`node integrations/money/app/harness/screenshots.mjs --axe` (writes to
`app/dist/screenshots/`).

## Verified

`e2e/money.spec.ts` passed on 2026-09-24 against the pinned atomic-server
`2f403624e` (which includes #1691, the change for atomic-server#1653), with this
package at version 0.2.0 (`plugin.js` sha256 `e189564805c807ffc60177b62e50eca8a39b6d2701cc26f7a63e204daae91f8c`). It covers these
`e2e/money.spec.ts` passed on 2026-09-25 against the pinned atomic-server
`bc39dac4b` (earlier against `007869464`, `11264e83e` and `2f403624e`, which includes #1691,
the change for atomic-server#1653), with this package at version 0.2.0
(`plugin.js` sha256 `a8f84cd07899984529b505d2719e83b1ec4bed805c9e2459e895c0956f784efe`,
the bundle with the annotations, structured errors and the statements
table). The
spec picks the release it just published by its id, so it also passes on a
lane store kept from earlier runs (checked twice in a row). It covers these
steps, all with the synthetic files in `fixtures/` and generated variants:

- publish, then discover under Community plugins, then create a draft;
- Set up, then an MT940 preview (2 new, "1 statements reconciled"), then
- Set up, then an MT940 preview (2 new transactions and their statement,
"Apply 3 changes", "1 statements reconciled"), then
Apply, then a full page reload, then the rows in the table;
- a reimport of the same file: "2 previously imported transactions skipped",
and nothing to apply;
Expand Down
163 changes: 163 additions & 0 deletions integrations/money/app/amounts.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
// @wc-ignore-file
import { readFileSync } from 'node:fs';
import { describe, expect, it } from 'vitest';
import {
addAmounts,
amountLabel,
currencyDigits,
formatAmount,
fromUnits,
groupByDay,
isOut,
negate,
sumByCurrency,
totals,
} from './amounts.js';

const MINUS = '−';
const both = ['intl', 'split'] as const;

describe('formatAmount: exact decimal display', () => {
for (const exact of both)
describe(`${exact} path`, () => {
const f = (
amount: string,
currency = 'EUR',
options: Parameters<typeof formatAmount>[3] = {},
) => formatAmount(amount, currency, 'en-GB', { exact, ...options });

it('signs money in with + and money out with a true minus', () => {
expect(f('2420')).toBe('+€2,420.00');
expect(f('-850')).toBe(`${MINUS}€850.00`);
expect(f('-84.3')).toBe(`${MINUS}€84.30`);
expect(f('0')).toBe('+€0.00');
expect(f('7921.95', 'EUR', { sign: 'negative' })).toBe('€7,921.95');
expect(f('-5', 'EUR', { sign: 'negative' })).toBe(`${MINUS}€5.00`);
});

it('never rounds through a float', () => {
expect(f('12345678901234.56789')).toBe('+€12,345,678,901,234.56789');
expect(f('9007199254740993')).toBe('+€9,007,199,254,740,993.00');
expect(f('-0.00001')).toBe(`${MINUS}€0.00001`);
expect(f('0.1')).toBe('+€0.10');
});

it('uses each currency’s own minor units', () => {
expect(f('-1200', 'JPY')).toBe(`${MINUS}JP¥1,200`);
expect(f('1.25', 'BHD')).toBe('+BHD 1.250');
expect(f('1.2345', 'BHD')).toBe('+BHD 1.2345');
});

it('can leave the symbol out (the currency sits in a header)', () => {
expect(f('-850', 'EUR', { symbol: false })).toBe(`${MINUS}850.00`);
expect(f('2420', 'EUR', { symbol: false })).toBe('+2,420.00');
});

it('formats in the given locale', () => {
expect(
formatAmount('-1850.5', 'EUR', 'nl-NL', { exact, sign: 'negative' }),
).toBe(`${MINUS}€ 1.850,50`);
});
});

it('falls back to plain text for a code Intl refuses', () => {
expect(formatAmount('-12.5', 'XX1', 'en-GB')).toBe(`${MINUS}12.5 XX1`);
});

it('knows minor units per currency', () => {
expect(currencyDigits('EUR')).toBe(2);
expect(currencyDigits('JPY')).toBe(0);
expect(currencyDigits('BHD')).toBe(3);
});
});

describe('amountLabel: words for aria-label', () => {
it('reads sign, whole units, currency and minor units', () => {
expect(amountLabel('-84.30', 'EUR', 'en')).toBe('minus 84 euro 30');
expect(amountLabel('1250', 'EUR', 'en')).toBe('plus 1,250 euro');
expect(amountLabel('-850.00', 'EUR', 'en')).toBe('minus 850 euro');
expect(amountLabel('84.05', 'EUR', 'en')).toBe('plus 84 euro 5');
expect(amountLabel('-1200', 'JPY', 'en')).toBe('minus 1,200 japanese yen');
expect(amountLabel('-0.00001', 'EUR', 'en')).toBe('minus 0.00001 euro');
});
});

describe('arithmetic on exact strings', () => {
it('adds, negates and converts without floats', () => {
expect(addAmounts(['0.1', '0.2'])).toBe('0.3');
expect(addAmounts(['-850', '-23.47'])).toBe('-873.47');
expect(addAmounts([])).toBe('0');
expect(negate('-12.5')).toBe('12.5');
expect(negate('0')).toBe('0');
expect(fromUnits(-100001n)).toBe('-1.00001');
expect(isOut('-0.01')).toBe(true);
expect(isOut('0')).toBe(false);
});

it('totals per account and currency, never across currencies', () => {
const rows = [
{ account: 'A', currency: 'EUR', amount: '-850' },
{ account: 'A', currency: 'EUR', amount: '2420' },
{ account: 'A', currency: 'USD', amount: '-29' },
{ account: 'B', currency: 'EUR', amount: '-1312' },
];
expect(totals(rows)).toEqual([
{
account: 'A',
currency: 'EUR',
in: '2420',
out: '-850',
net: '1570',
count: 2,
},
{
account: 'A',
currency: 'USD',
in: '0',
out: '-29',
net: '-29',
count: 1,
},
{
account: 'B',
currency: 'EUR',
in: '0',
out: '-1312',
net: '-1312',
count: 1,
},
]);
expect(sumByCurrency(rows)).toEqual([
{ currency: 'EUR', amount: '258' },
{ currency: 'USD', amount: '-29' },
]);
});

it('groups by booking date, newest first, with a net per currency', () => {
const rows = [
{ id: 1, bookingDate: '2026-09-16', currency: 'EUR', amount: '-1312' },
{ id: 2, bookingDate: '2026-09-22', currency: 'EUR', amount: '-850' },
{ id: 3, bookingDate: '2026-09-16', currency: 'EUR', amount: '318.20' },
{ id: 4, bookingDate: '2026-09-22', currency: 'EUR', amount: '-23.47' },
{ id: 5, bookingDate: '2026-09-16', currency: 'USD', amount: '-29' },
];
const days = groupByDay(rows);
expect(days.map(d => d.date)).toEqual(['2026-09-22', '2026-09-16']);
expect(days[0].rows.map(r => r.id)).toEqual([2, 4]);
expect(days[0].net).toEqual([{ currency: 'EUR', amount: '-873.47' }]);
expect(days[1].net).toEqual([
{ currency: 'EUR', amount: '-993.8' },
{ currency: 'USD', amount: '-29' },
]);
});
});

describe('no float round-trip', () => {
it('amounts.ts never converts an amount to a Number', () => {
const source = readFileSync(
new URL('./amounts.ts', import.meta.url),
'utf8',
);
expect(source).not.toMatch(/\bNumber\(|parseFloat|parseInt|Math\./);
});
});
Loading
Loading