@perrylink/dsh-bankrec 0.1.0-alpha.0 → 0.1.0-alpha.2

package/README.md

@@ -1,3 +1,3 @@
 # @perrylink/dsh-bankrec
 Bank CSV/GL ingest, 1:1 matching and 3-sheet reconciliation workpaper — SKU-06 S1 public/synthetic demo. **Partial, not GA**: 0 real firms; user-approved public/synthetic (2026-10-31).
-Tools: `bankrec.ingest`, `bankrec.match`, `bankrec.export` (Bank/GL/Matches xlsx). Env `DSH_BANKREC_HOME`. Apache-2.0.
+Tools: `bankrec.ingest`, `bankrec.ingest_camt` (CAMT.053), `bankrec.reconcile_camt`, `bankrec.match`, `bankrec.export` (Bank/GL/Matches xlsx). Env `DSH_BANKREC_HOME`. Apache-2.0.

package/lib/core/camt.d.ts

@@ -0,0 +1,8 @@
+import type { TxnRecord } from '../plugin/storage.js';
+export declare function parseCamt(text: string, accountOverride?: string, evidenceSha?: string): TxnRecord[];
+export interface CamtBalance {
+    type: string;
+    amount_cents: number;
+    date: string;
+}
+export declare function parseCamtBalances(text: string): CamtBalance[];

package/lib/core/camt.js

@@ -0,0 +1,66 @@
+import { createHash } from 'node:crypto';
+import { XMLParser } from 'fast-xml-parser';
+import { BankrecError, cents } from './bankrec.js';
+const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: '@_', removeNSPrefix: true, parseTagValue: false, trimValues: true, processEntities: false });
+const asArray = (value) => Array.isArray(value) ? value : value === undefined ? [] : [value];
+const asObject = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+function scalar(value) { if (value === null || value === undefined)
+    return ''; if (typeof value !== 'object')
+    return String(value); const o = value; return String(o['#text'] ?? ''); }
+function dateOf(entry) { const d = scalar(entry.BookgDt?.Dt) || scalar(entry.BookgDt?.DtTm) || scalar(entry.ValDt?.Dt) || scalar(entry.ValDt?.DtTm); return d.slice(0, 10); }
+export function parseCamt(text, accountOverride, evidenceSha) {
+    let root;
+    try {
+        root = parser.parse(text);
+    }
+    catch {
+        throw new BankrecError('E_BR_CSV_INVALID', 'CAMT XML is not parseable');
+    }
+    const statements = asArray(asObject(root?.Document)?.BkToCstmrStmt?.Stmt);
+    if (statements.length === 0)
+        throw new BankrecError('E_BR_CSV_INVALID', 'CAMT has no BkToCstmrStmt/Stmt');
+    const evidence = evidenceSha ?? createHash('sha256').update(text).digest('hex');
+    const out = [];
+    for (const stmt of statements) {
+        const iban = scalar(stmt?.Acct?.Id?.IBAN) || scalar(stmt?.Acct?.Id?.Othr?.Id);
+        const account = accountOverride?.trim() || iban;
+        if (!account)
+            throw new BankrecError('E_BR_CSV_INVALID', 'CAMT statement has no account/IBAN');
+        for (const [index, entry] of asArray(stmt?.Ntry).entries()) {
+            const amount = scalar(entry?.Amt);
+            const sign = scalar(entry?.CdtDbtInd).toUpperCase() === 'DBIT' ? -1 : 1;
+            const value = sign * cents(amount);
+            const date = dateOf(entry);
+            if (!/^\d{4}-\d{2}-\d{2}$/.test(date))
+                throw new BankrecError('E_BR_CSV_INVALID', `CAMT entry has no booking date (${index})`);
+            const details = entry?.NtryDtls?.TxDtls;
+            const reference = scalar(entry?.AcctSvcrRef) || scalar(details?.Refs?.TxId) || scalar(details?.Refs?.EndToEndId) || scalar(details?.RmtInf?.Ustrd) || scalar(details?.RmtInf?.Strd?.CdtrRefInf?.Ref) || 'camt';
+            out.push({ txn_id: `camt-${account}-${date}-${value}-${index}`, account_id: account, period: date.slice(0, 7), side: 'bank', date, amount_cents: value, reference, evidence_sha256: evidence, created_at: new Date().toISOString() });
+        }
+    }
+    if (out.length === 0)
+        throw new BankrecError('E_BR_CSV_INVALID', 'CAMT has no entries');
+    return out;
+}
+export function parseCamtBalances(text) {
+    let root;
+    try {
+        root = parser.parse(text);
+    }
+    catch {
+        throw new BankrecError('E_BR_CSV_INVALID', 'CAMT XML is not parseable');
+    }
+    const statements = asArray(asObject(root?.Document)?.BkToCstmrStmt?.Stmt);
+    const balances = [];
+    for (const stmt of statements) {
+        for (const bal of asArray(stmt?.Bal)) {
+            const type = scalar(bal?.Tp?.CdOrPrtry?.Cd);
+            const raw = scalar(bal?.Amt);
+            if (!type || !raw)
+                continue;
+            const sign = scalar(bal?.CdtDbtInd).toUpperCase() === 'DBIT' ? -1 : 1;
+            balances.push({ type, amount_cents: sign * cents(raw), date: scalar(bal?.Dt?.Dt) || scalar(bal?.Dt?.DtTm).slice(0, 10) });
+        }
+    }
+    return balances;
+}

package/lib/plugin/tools.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import * as XLSX from 'xlsx';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { BankrecError, parseCsv } from '../core/bankrec.js';
+import { parseCamt, parseCamtBalances } from '../core/camt.js';
 const text = (t) => [{ type: 'text', text: t }];
 const sha = (v) => createHash('sha256').update(v).digest('hex');
 export function createTools(deps) {
@@ -21,6 +22,10 @@ export function createTools(deps) {
             }
         } return { matched, unmatched_bank: bank.filter(b => !usedBank.has(b.txn_id)).map(b => b.txn_id), unmatched_gl: gl.filter(g => !used.has(g.txn_id)).map(g => g.txn_id) }; } });
     // fix unmatched_bank below via replacement later
+    const camt = defineTool({ name: 'bankrec.ingest_camt', description: 'Ingest CAMT.053 XML bank statement entries; supports DBIT/CRDT and stores bank rows. Local R1 write.', parameters: { camt_xml: { type: 'string', required: true }, account_id: { type: 'string' } }, output: { schema: { type: 'object', additionalProperties: false, properties: { rows: { type: 'number', required: true }, accounts: { type: 'array', items: { type: 'string' }, required: true }, periods: { type: 'array', items: { type: 'string' }, required: true } } }, render: (_a, v) => text(`CAMT rows=${v.rows}`) }, async execute(a) { const rows = parseCamt(a.camt_xml, a.account_id); for (const t of rows)
+            await deps.transactions.put(t.txn_id, t); return { rows: rows.length, accounts: [...new Set(rows.map(r => r.account_id))], periods: [...new Set(rows.map(r => r.period))] }; } });
     const exportTool = defineTool({ name: 'bankrec.export', description: 'Export 3-sheet reconciliation xlsx (Bank, GL, Matches). Local R1 write.', parameters: { account_id: { type: 'string', required: true }, period: { type: 'string', required: true } }, output: { schema: { type: 'object', additionalProperties: false, properties: { path: { type: 'string', required: true }, sha256: { type: 'string', required: true }, sheets: { type: 'number', required: true } } }, render: (_a, v) => text(`export ${v.sheets} sheets`) }, async execute(args) { const all = [...deps.transactions.entries()].map(([, v]) => v).filter(t => t.account_id === args.account_id && t.period === args.period); const ms = [...deps.matches.entries()].map(([, v]) => v); const wb = XLSX.utils.book_new(); XLSX.utils.book_append_sheet(wb, XLSX.utils.json_to_sheet(all.filter(t => t.side === 'bank').map(t => ({ date: t.date, amount_cents: t.amount_cents, reference: t.reference, txn_id: t.txn_id }))), 'Bank'); XLSX.utils.book_append_sheet(wb, XLSX.utils.json_to_sheet(all.filter(t => t.side === 'gl').map(t => ({ date: t.date, amount_cents: t.amount_cents, reference: t.reference, txn_id: t.txn_id }))), 'GL'); XLSX.utils.book_append_sheet(wb, XLSX.utils.json_to_sheet(ms), 'Matches'); const dir = path.join(deps.baseDir, 'exports'); await mkdir(dir, { recursive: true }); const p = path.join(dir, `${args.account_id}-${args.period}.xlsx`); const b = Buffer.from(XLSX.write(wb, { type: 'buffer', bookType: 'xlsx' })); await writeFile(p, b); return { path: p, sha256: sha(b), sheets: wb.SheetNames.length }; } });
-    return [ingest, match, exportTool];
+    const reconcile = defineTool({ name: 'bankrec.reconcile_camt', description: 'Check CAMT.053 opening/closing balance continuity against the sum of entries; read-only.', parameters: { camt_xml: { type: 'string', required: true } }, output: { schema: { type: 'object', additionalProperties: false, properties: { opening_cents: { type: 'number', required: true }, closing_cents: { type: 'number', required: true }, net_cents: { type: 'number', required: true }, difference_cents: { type: 'number', required: true }, balanced: { type: 'boolean', required: true } } }, render: (_a, v) => text(`CAMT balance ${v.balanced ? 'ok' : 'DIFF'} (${v.difference_cents})`) }, async execute(a) { const balances = parseCamtBalances(a.camt_xml); const rows = parseCamt(a.camt_xml); const open = balances.find(b => /^OPBD|^PRCD/.test(b.type)); const close = balances.find(b => /^CLBD|^CLAV/.test(b.type)); if (!open || !close)
+            throw new BankrecError('E_BR_CSV_INVALID', 'CAMT lacks opening/closing balance'); const net = rows.reduce((n, r) => n + r.amount_cents, 0); const diff = open.amount_cents + net - close.amount_cents; return { opening_cents: open.amount_cents, closing_cents: close.amount_cents, net_cents: net, difference_cents: diff, balanced: diff === 0 }; } });
+    return [ingest, camt, match, reconcile, exportTool];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perrylink/dsh-bankrec",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "description": "Bank statement ingest, 1:1 matching and reconciliation workpaper (SKU-06 S1 public/synthetic demo).",
   "type": "module",
   "main": "./lib/plugin/index.js",
@@ -61,9 +61,10 @@
     "@deepseek-ai/dsh-tools": ">=0.2.1-rc.3 <0.3.0"
   },
   "dependencies": {
+    "fast-xml-parser": "5.11.2",
     "fflate": "0.8.3",
-    "zod": "4.4.3",
-    "xlsx": "0.18.5"
+    "xlsx": "0.18.5",
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.5",