Bank reconciliation for the fin.cx accounting stack: one canonical signed-integer-cent transaction model fed by @fin.cx/camt (CAMT.052/053/054) and @fin.cx/mt940 (legacy MT940), a cross-statement continuity control, and a confidence-scored matching engine for settling open items.

Everything is pure functions — no database. The caller executes match decisions (e.g. via the @fin.cx/skr booking recipes) and owns the thresholds; matches stay reversible until the period is festgeschrieben.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

What This Package Does

Canonical transactions: fromCamtStatement() / fromMt940Statement() normalize either format into IBankTransaction — signed integer cents (credits positive), SEPA references, counterparty data, return reasons, stable ids derived from bank references
Continuity control: checkStatementContinuity() verifies per account that every closing balance equals the next opening balance and electronic sequence numbers are gapless — the hard monthly-close gate against silently missing statements
Matching engine: matchTransactions() scores bank transactions against open items with weighted signals (exact reference 50, invoice number in remittance 35, exact amount 30, Skonto-window short payment 20, known IBAN 20, name similarity 10, date proximity 5). Direction is a hard filter, returns/reversals never auto-settle, ambiguous ties force review, and every auto decision consumes its open item exactly once

Installation

pnpm add @fin.cx/bankrec

Usage

import { parseCamt } from '@fin.cx/camt';
import {
  fromCamtStatement,
  checkStatementContinuity,
  matchTransactions,
} from '@fin.cx/bankrec';

const statements = parseCamt(xml);
const normalized = statements.map(fromCamtStatement);

const continuity = checkStatementContinuity(normalized.map((entry) => entry.link));
if (!continuity.valid) throw new Error(continuity.issues.join('; '));

const decisions = matchTransactions(
  normalized.flatMap((entry) => entry.transactions),
  openItems, // receivables/payables from your ledger
  { autoThreshold: 85, reviewThreshold: 50 },
);

for (const decision of decisions) {
  // 'auto'      -> book via skr recipes (bookBankPayment)
  // 'review'    -> human queue with decision.candidates + signals
  // 'unmatched' -> suspense (bookToSuspense) or manual handling
}

Development

pnpm build
pnpm test

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@fin.cx/bankrec