@festapp/banksync 0.1.6 → 0.2.2

package/dist/index.cjs

@@ -18,8 +18,8 @@
 
 
 
-var _chunkPBN2BUNRcjs = require('./chunk-PBN2BUNR.cjs');
 
+var _chunkN7BVOSFNcjs = require('./chunk-N7BVOSFN.cjs');
 
 
 
@@ -39,4 +39,6 @@ var _chunkPBN2BUNRcjs = require('./chunk-PBN2BUNR.cjs');
 
 
 
-exports.BANK_CODES = _chunkPBN2BUNRcjs.BANK_CODES; exports.FioApiError = _chunkPBN2BUNRcjs.FioApiError; exports.FioRateLimited = _chunkPBN2BUNRcjs.FioRateLimited; exports.FioTransientFailure = _chunkPBN2BUNRcjs.FioTransientFailure; exports.WebhookVerificationError = _chunkPBN2BUNRcjs.WebhookVerificationError; exports.buildWebhookEnvelope = _chunkPBN2BUNRcjs.buildWebhookEnvelope; exports.decodeRf = _chunkPBN2BUNRcjs.decodeRf; exports.detectProvider = _chunkPBN2BUNRcjs.detectProvider; exports.encodeRf = _chunkPBN2BUNRcjs.encodeRf; exports.extractReferenceCandidates = _chunkPBN2BUNRcjs.extractReferenceCandidates; exports.fetchNewTransactions = _chunkPBN2BUNRcjs.fetchNewTransactions; exports.mapFioTransaction = _chunkPBN2BUNRcjs.mapFioTransaction; exports.normalizeCurrency = _chunkPBN2BUNRcjs.normalizeCurrency; exports.parseEmail = _chunkPBN2BUNRcjs.parseEmail; exports.resolveVariableSymbol = _chunkPBN2BUNRcjs.resolveVariableSymbol; exports.setFioPointer = _chunkPBN2BUNRcjs.setFioPointer; exports.signWebhook = _chunkPBN2BUNRcjs.signWebhook; exports.toCents = _chunkPBN2BUNRcjs.toCents; exports.verifyWebhook = _chunkPBN2BUNRcjs.verifyWebhook;
+
+
+exports.BANK_CODES = _chunkN7BVOSFNcjs.BANK_CODES; exports.FioApiError = _chunkN7BVOSFNcjs.FioApiError; exports.FioRateLimited = _chunkN7BVOSFNcjs.FioRateLimited; exports.FioTransientFailure = _chunkN7BVOSFNcjs.FioTransientFailure; exports.WebhookVerificationError = _chunkN7BVOSFNcjs.WebhookVerificationError; exports.buildWebhookEnvelope = _chunkN7BVOSFNcjs.buildWebhookEnvelope; exports.decimalToCents = _chunkN7BVOSFNcjs.decimalToCents; exports.decodeRf = _chunkN7BVOSFNcjs.decodeRf; exports.detectProvider = _chunkN7BVOSFNcjs.detectProvider; exports.encodeRf = _chunkN7BVOSFNcjs.encodeRf; exports.extractReferenceCandidates = _chunkN7BVOSFNcjs.extractReferenceCandidates; exports.fetchNewTransactions = _chunkN7BVOSFNcjs.fetchNewTransactions; exports.mapFioTransaction = _chunkN7BVOSFNcjs.mapFioTransaction; exports.normalizeCurrency = _chunkN7BVOSFNcjs.normalizeCurrency; exports.parseEmail = _chunkN7BVOSFNcjs.parseEmail; exports.resolveVariableSymbol = _chunkN7BVOSFNcjs.resolveVariableSymbol; exports.setFioPointer = _chunkN7BVOSFNcjs.setFioPointer; exports.signWebhook = _chunkN7BVOSFNcjs.signWebhook; exports.toCents = _chunkN7BVOSFNcjs.toCents; exports.verifyWebhook = _chunkN7BVOSFNcjs.verifyWebhook;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { T as Transaction, W as WebhookEnvelope } from './types-Cb5l2lXq.cjs';
-export { B as BankAccount, a as WebhookConsumer, b as WebhookSubscription } from './types-Cb5l2lXq.cjs';
+import { T as Transaction, W as WebhookEnvelope } from './types-DZX_B1qb.cjs';
+export { B as BankAccount, a as WebhookConsumer, b as WebhookSubscription } from './types-DZX_B1qb.cjs';
 
 declare const BANK_CODES: Record<string, string>;
 type EmailProvider = 'fio_email' | 'airbank_email';
@@ -11,21 +11,11 @@ declare function parseEmail(text: string, provider: EmailProvider): ParsedEmailT
 
 declare function normalizeCurrency(raw: string): string;
 declare function toCents(amount: number, currency: string): number;
+/** Convert a decimal representation without binary floating point rounding. */
+declare function decimalToCents(raw: string, currency: string): number;
 
-/**
- * Payment identification — the one place that knows what an order identifier
- * looks like in free text. banksync extracts *candidate* tokens; the billing
- * resolver (`billing_credit_mark_paid`) decides which pending order they hit.
- *
- * Carriers, in descending confidence:
- *   1. the structured `vs` field (Czech variable symbol)
- *   2. a labelled `VS<digits>` / `/VS/<digits>` token in the message
- *   3. an ISO 11649 `RF` creditor reference (our EUR/EPC rail wraps the VS in it)
- *   4. a bare VS-shaped 6–10 digit run
- *
- * A candidate only ever credits when it EQUALS a pending order's ledger-unique
- * VS and the amount/currency guard passes — so over-generating here is safe.
- */
+/** Legacy v1 compatibility utilities. Canonical v2 bank facts do not infer order identifiers.
+ * Consumers own payment identification and their business rules. */
 interface ReferenceSource {
     vs?: string | null;
     ss?: string | null;
@@ -34,7 +24,7 @@ interface ReferenceSource {
     comment?: string | null;
 }
 /**
- * Canonical persistence value for a bank transaction. A real structured VS
+ * Legacy v1 projection value. A real structured VS
  * wins. Otherwise only a checksum-valid RF carrying a 1-10 digit VS may fill
  * the field; labelled/bare free-text candidates remain resolver hints and are
  * never promoted into stored structured data.
@@ -55,6 +45,7 @@ declare function buildWebhookEnvelope(args: {
     delivery_id: string;
     pairing_code: string;
     transaction: Transaction;
+    event_version?: '1' | '2';
 }): WebhookEnvelope;
 declare function signWebhook(args: {
     envelope: WebhookEnvelope;
@@ -74,6 +65,8 @@ interface VerifyWebhookArgs {
     signature: string;
     toleranceSeconds?: number;
     nowSeconds?: number;
+    /** Defaults to v1 for existing consumers. Festapp explicitly opts into v2. */
+    eventVersion?: '1' | '2';
 }
 /**
  * Safe public verification contract. Consumers must durably claim the returned
@@ -118,4 +111,4 @@ declare function fetchNewTransactions(token: string, proxy?: FioProxyConfig): Pr
 declare function setFioPointer(token: string, yyyyMmDd: string, proxy?: FioProxyConfig): Promise<void>;
 declare function mapFioTransaction(raw: FioTransaction): Omit<Transaction, 'id' | 'bank_account_id'> | null;
 
-export { BANK_CODES, type EmailProvider, FioApiError, type FioColumn, type FioProxyConfig, FioRateLimited, type FioTransaction, FioTransientFailure, type ParsedEmailTransaction, type ReferenceSource, type SignedWebhook, Transaction, type VerifyWebhookArgs, WebhookEnvelope, type WebhookVerificationCode, WebhookVerificationError, buildWebhookEnvelope, decodeRf, detectProvider, encodeRf, extractReferenceCandidates, fetchNewTransactions, mapFioTransaction, normalizeCurrency, parseEmail, resolveVariableSymbol, setFioPointer, signWebhook, toCents, verifyWebhook };
+export { BANK_CODES, type EmailProvider, FioApiError, type FioColumn, type FioProxyConfig, FioRateLimited, type FioTransaction, FioTransientFailure, type ParsedEmailTransaction, type ReferenceSource, type SignedWebhook, Transaction, type VerifyWebhookArgs, WebhookEnvelope, type WebhookVerificationCode, WebhookVerificationError, buildWebhookEnvelope, decimalToCents, decodeRf, detectProvider, encodeRf, extractReferenceCandidates, fetchNewTransactions, mapFioTransaction, normalizeCurrency, parseEmail, resolveVariableSymbol, setFioPointer, signWebhook, toCents, verifyWebhook };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { T as Transaction, W as WebhookEnvelope } from './types-Cb5l2lXq.js';
-export { B as BankAccount, a as WebhookConsumer, b as WebhookSubscription } from './types-Cb5l2lXq.js';
+import { T as Transaction, W as WebhookEnvelope } from './types-DZX_B1qb.js';
+export { B as BankAccount, a as WebhookConsumer, b as WebhookSubscription } from './types-DZX_B1qb.js';
 
 declare const BANK_CODES: Record<string, string>;
 type EmailProvider = 'fio_email' | 'airbank_email';
@@ -11,21 +11,11 @@ declare function parseEmail(text: string, provider: EmailProvider): ParsedEmailT
 
 declare function normalizeCurrency(raw: string): string;
 declare function toCents(amount: number, currency: string): number;
+/** Convert a decimal representation without binary floating point rounding. */
+declare function decimalToCents(raw: string, currency: string): number;
 
-/**
- * Payment identification — the one place that knows what an order identifier
- * looks like in free text. banksync extracts *candidate* tokens; the billing
- * resolver (`billing_credit_mark_paid`) decides which pending order they hit.
- *
- * Carriers, in descending confidence:
- *   1. the structured `vs` field (Czech variable symbol)
- *   2. a labelled `VS<digits>` / `/VS/<digits>` token in the message
- *   3. an ISO 11649 `RF` creditor reference (our EUR/EPC rail wraps the VS in it)
- *   4. a bare VS-shaped 6–10 digit run
- *
- * A candidate only ever credits when it EQUALS a pending order's ledger-unique
- * VS and the amount/currency guard passes — so over-generating here is safe.
- */
+/** Legacy v1 compatibility utilities. Canonical v2 bank facts do not infer order identifiers.
+ * Consumers own payment identification and their business rules. */
 interface ReferenceSource {
     vs?: string | null;
     ss?: string | null;
@@ -34,7 +24,7 @@ interface ReferenceSource {
     comment?: string | null;
 }
 /**
- * Canonical persistence value for a bank transaction. A real structured VS
+ * Legacy v1 projection value. A real structured VS
  * wins. Otherwise only a checksum-valid RF carrying a 1-10 digit VS may fill
  * the field; labelled/bare free-text candidates remain resolver hints and are
  * never promoted into stored structured data.
@@ -55,6 +45,7 @@ declare function buildWebhookEnvelope(args: {
     delivery_id: string;
     pairing_code: string;
     transaction: Transaction;
+    event_version?: '1' | '2';
 }): WebhookEnvelope;
 declare function signWebhook(args: {
     envelope: WebhookEnvelope;
@@ -74,6 +65,8 @@ interface VerifyWebhookArgs {
     signature: string;
     toleranceSeconds?: number;
     nowSeconds?: number;
+    /** Defaults to v1 for existing consumers. Festapp explicitly opts into v2. */
+    eventVersion?: '1' | '2';
 }
 /**
  * Safe public verification contract. Consumers must durably claim the returned
@@ -118,4 +111,4 @@ declare function fetchNewTransactions(token: string, proxy?: FioProxyConfig): Pr
 declare function setFioPointer(token: string, yyyyMmDd: string, proxy?: FioProxyConfig): Promise<void>;
 declare function mapFioTransaction(raw: FioTransaction): Omit<Transaction, 'id' | 'bank_account_id'> | null;
 
-export { BANK_CODES, type EmailProvider, FioApiError, type FioColumn, type FioProxyConfig, FioRateLimited, type FioTransaction, FioTransientFailure, type ParsedEmailTransaction, type ReferenceSource, type SignedWebhook, Transaction, type VerifyWebhookArgs, WebhookEnvelope, type WebhookVerificationCode, WebhookVerificationError, buildWebhookEnvelope, decodeRf, detectProvider, encodeRf, extractReferenceCandidates, fetchNewTransactions, mapFioTransaction, normalizeCurrency, parseEmail, resolveVariableSymbol, setFioPointer, signWebhook, toCents, verifyWebhook };
+export { BANK_CODES, type EmailProvider, FioApiError, type FioColumn, type FioProxyConfig, FioRateLimited, type FioTransaction, FioTransientFailure, type ParsedEmailTransaction, type ReferenceSource, type SignedWebhook, Transaction, type VerifyWebhookArgs, WebhookEnvelope, type WebhookVerificationCode, WebhookVerificationError, buildWebhookEnvelope, decimalToCents, decodeRf, detectProvider, encodeRf, extractReferenceCandidates, fetchNewTransactions, mapFioTransaction, normalizeCurrency, parseEmail, resolveVariableSymbol, setFioPointer, signWebhook, toCents, verifyWebhook };

package/dist/index.js

@@ -5,6 +5,7 @@ import {
   FioTransientFailure,
   WebhookVerificationError,
   buildWebhookEnvelope,
+  decimalToCents,
   decodeRf,
   detectProvider,
   encodeRf,
@@ -18,7 +19,7 @@ import {
   signWebhook,
   toCents,
   verifyWebhook
-} from "./chunk-5QXHZGAW.js";
+} from "./chunk-3WM2GGFL.js";
 export {
   BANK_CODES,
   FioApiError,
@@ -26,6 +27,7 @@ export {
   FioTransientFailure,
   WebhookVerificationError,
   buildWebhookEnvelope,
+  decimalToCents,
   decodeRf,
   detectProvider,
   encodeRf,

package/dist/{types-Cb5l2lXq.d.cts → types-DZX_B1qb.d.cts}

@@ -20,7 +20,7 @@ interface BankAccount {
 interface Transaction {
     id: number;
     bank_account_id: number;
-    /** INTEGER, lowest unit (e.g. 1990 = 19.90 CZK), incoming-only — always positive */
+    /** INTEGER, lowest unit (e.g. 1990 = 19.90 CZK), signed exact minor units */
     amount_cents: number;
     /** ISO 4217 alpha-3 uppercase (CZK/EUR/USD) */
     currency: string;
@@ -42,6 +42,12 @@ interface Transaction {
     comment: string | null;
     /** Fio API column17 — ID pokynu, available only from Fio API pull */
     command_id: string | null;
+    /** V2 facts; absent only on retained v1 records. */
+    payer_reference?: string | null;
+    raw_vs?: string | null;
+    direction?: 'incoming' | 'outgoing' | 'zero';
+    identity_kind?: 'movement' | 'observation' | 'historical_unverified';
+    identity_provenance?: string;
     source: 'email' | 'fio_api';
     date: string;
     /** Original timezone offset in minutes (e.g. CET=60, CEST=120). Debug only — all queries use UTC date. */
@@ -52,7 +58,7 @@ interface Transaction {
 interface WebhookEnvelope {
     event: 'transaction.received';
     /** Bumped when shape of `data` or signing string changes */
-    event_version: '1';
+    event_version: '1' | '2';
     /** ULID, stable across retries — sole idempotence key */
     delivery_id: string;
     pairing_code: string;

package/dist/{types-Cb5l2lXq.d.ts → types-DZX_B1qb.d.ts}

@@ -20,7 +20,7 @@ interface BankAccount {
 interface Transaction {
     id: number;
     bank_account_id: number;
-    /** INTEGER, lowest unit (e.g. 1990 = 19.90 CZK), incoming-only — always positive */
+    /** INTEGER, lowest unit (e.g. 1990 = 19.90 CZK), signed exact minor units */
     amount_cents: number;
     /** ISO 4217 alpha-3 uppercase (CZK/EUR/USD) */
     currency: string;
@@ -42,6 +42,12 @@ interface Transaction {
     comment: string | null;
     /** Fio API column17 — ID pokynu, available only from Fio API pull */
     command_id: string | null;
+    /** V2 facts; absent only on retained v1 records. */
+    payer_reference?: string | null;
+    raw_vs?: string | null;
+    direction?: 'incoming' | 'outgoing' | 'zero';
+    identity_kind?: 'movement' | 'observation' | 'historical_unverified';
+    identity_provenance?: string;
     source: 'email' | 'fio_api';
     date: string;
     /** Original timezone offset in minutes (e.g. CET=60, CEST=120). Debug only — all queries use UTC date. */
@@ -52,7 +58,7 @@ interface Transaction {
 interface WebhookEnvelope {
     event: 'transaction.received';
     /** Bumped when shape of `data` or signing string changes */
-    event_version: '1';
+    event_version: '1' | '2';
     /** ULID, stable across retries — sole idempotence key */
     delivery_id: string;
     pairing_code: string;

package/migrations/0011_complete_bank_facts.sql

@@ -0,0 +1,52 @@
+-- Schema 11: preserve row IDs and immutable delivery payloads. No historical email ID reinterpretation.
+CREATE TABLE bank_sync_upgrade_sequence AS SELECT seq FROM sqlite_sequence WHERE name='transactions';
+CREATE TABLE transactions_v2 (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  bank_account_id INTEGER NOT NULL REFERENCES bank_accounts(id),
+  amount_cents INTEGER NOT NULL CHECK (amount_cents BETWEEN -9007199254740991 AND 9007199254740991),
+  currency TEXT NOT NULL CHECK (length(currency) = 3 AND currency = upper(currency)),
+  counter_account TEXT,
+  bank_code TEXT,
+  bank_name TEXT,
+  vs TEXT,
+  ks TEXT,
+  ss TEXT,
+  message TEXT,
+  sender_name TEXT,
+  user_identification TEXT,
+  transaction_type TEXT,
+  performed_by TEXT,
+  comment TEXT,
+  command_id TEXT,
+  source TEXT NOT NULL,
+  date TEXT NOT NULL,
+  date_offset_min INTEGER,
+  transaction_id TEXT,
+  external_id TEXT,
+  payer_reference TEXT,
+  raw_vs TEXT,
+  direction TEXT NOT NULL DEFAULT 'incoming' CHECK (direction IN ('incoming','outgoing','zero')),
+  identity_kind TEXT NOT NULL DEFAULT 'historical_unverified',
+  identity_provenance TEXT NOT NULL DEFAULT 'historical_unverified',
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+INSERT INTO transactions_v2 (id, bank_account_id, amount_cents, currency, counter_account, bank_code, bank_name, vs, ks, ss, message, sender_name, user_identification, transaction_type, performed_by, comment, command_id, source, date, date_offset_min, transaction_id, external_id, created_at, raw_vs, identity_kind, identity_provenance)
+SELECT id, bank_account_id, amount_cents, currency, counter_account, bank_code, bank_name, vs, ks, ss, message, sender_name, user_identification, transaction_type, performed_by, comment, command_id, source, date, date_offset_min, transaction_id, external_id, created_at, vs, CASE WHEN source='fio_api' AND transaction_id IS NOT NULL THEN 'movement' ELSE 'historical_unverified' END,
+CASE WHEN source='fio_api' AND transaction_id IS NOT NULL THEN 'fio_api_column22' ELSE 'historical_unverified' END FROM transactions;
+DROP TABLE transactions;
+ALTER TABLE transactions_v2 RENAME TO transactions;
+INSERT INTO sqlite_sequence(name,seq) SELECT 'transactions',COALESCE((SELECT seq FROM bank_sync_upgrade_sequence),0) WHERE NOT EXISTS(SELECT 1 FROM sqlite_sequence WHERE name='transactions');
+UPDATE sqlite_sequence SET seq=MAX(seq,COALESCE((SELECT seq FROM bank_sync_upgrade_sequence),0)) WHERE name='transactions';
+DROP TABLE bank_sync_upgrade_sequence;
+CREATE UNIQUE INDEX idx_tx_ext ON transactions(bank_account_id, external_id) WHERE external_id IS NOT NULL;
+CREATE UNIQUE INDEX idx_tx_fio ON transactions(bank_account_id, transaction_id) WHERE transaction_id IS NOT NULL AND identity_kind='movement';
+ALTER TABLE webhook_consumers ADD COLUMN event_version TEXT NOT NULL DEFAULT '1' CHECK(event_version IN ('1','2'));
+CREATE TABLE bank_poll_leases (credential_hash TEXT PRIMARY KEY, token TEXT NOT NULL, lease_until TEXT NOT NULL, next_allowed_at TEXT NOT NULL);
+CREATE TABLE bank_recovery_batches (id TEXT PRIMARY KEY, bank_account_id INTEGER NOT NULL REFERENCES bank_accounts(id), from_date TEXT NOT NULL, to_date TEXT NOT NULL, cipher TEXT, key_version INTEGER, state TEXT NOT NULL CHECK(state IN ('fetching','spooled','completed')), created_at TEXT NOT NULL DEFAULT (datetime('now')), completed_at TEXT);
+ALTER TABLE bank_accounts ADD COLUMN ingest_enabled INTEGER NOT NULL DEFAULT 1;
+ALTER TABLE bank_accounts ADD COLUMN api_token_hash TEXT;
+ALTER TABLE bank_accounts ADD COLUMN api_pointer_initialized INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE bank_accounts ADD COLUMN api_reconciled_through TEXT;
+UPDATE bank_accounts SET api_pointer_initialized=1 WHERE api_last_success_at IS NOT NULL;
+CREATE TABLE authenticated_email_spool (id TEXT PRIMARY KEY, bank_account_id INTEGER NOT NULL REFERENCES bank_accounts(id), body_sha256 TEXT NOT NULL, cipher TEXT NOT NULL, key_version INTEGER NOT NULL, state TEXT NOT NULL DEFAULT 'pending' CHECK(state IN ('pending','completed')), attempts INTEGER NOT NULL DEFAULT 0, created_at TEXT NOT NULL DEFAULT (datetime('now')), completed_at TEXT);
+UPDATE schema_meta SET value='11' WHERE key='version';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@festapp/banksync",
-  "version": "0.1.6",
+  "version": "0.2.2",
   "description": "Bank transaction ingestion for Cloudflare Workers: Czech bank email and Fio API parsing, durable deduplication, and signed webhook delivery.",
   "type": "module",
   "packageManager": "pnpm@11.24.0",
@@ -50,13 +50,13 @@
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^5.20260730.1",
-    "@types/better-sqlite3": "^7.6.13",
+    "@types/better-sqlite3": "^9.6.0",
     "better-sqlite3": "^13.0.3",
     "tsup": "^8.5.0",
     "typescript": "^5.9.3",
     "vite": "^8.2.2",
     "vitest": "^4.1.5",
-    "wrangler": "4.127.1"
+    "wrangler": "4.130.0"
   },
   "engines": {
     "node": ">=20"