@festapp/banksync 0.0.0-bootstrap.20260831

package/dist/index.cjs

@@ -0,0 +1,42 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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;

package/dist/index.d.cts

@@ -0,0 +1,121 @@
+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';
+
+declare const BANK_CODES: Record<string, string>;
+type EmailProvider = 'fio_email' | 'airbank_email';
+declare function detectProvider(text: string, accountNumber: string | null): 'fio_email' | 'airbank_email' | 'unknown';
+type ParsedEmailTransaction = Omit<Transaction, 'id' | 'bank_account_id' | 'created_at' | 'date'> & {
+    date: string | null;
+};
+declare function parseEmail(text: string, provider: EmailProvider): ParsedEmailTransaction | null;
+
+declare function normalizeCurrency(raw: string): string;
+declare function toCents(amount: number, 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.
+ */
+interface ReferenceSource {
+    vs?: string | null;
+    ss?: string | null;
+    message?: string | null;
+    user_identification?: string | null;
+    comment?: string | null;
+}
+/**
+ * Canonical persistence value for a bank transaction. 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.
+ */
+declare function resolveVariableSymbol(src: ReferenceSource): string | null;
+declare function extractReferenceCandidates(src: ReferenceSource): string[];
+
+interface SignedWebhook {
+    bodyBytes: Uint8Array;
+    headers: {
+        'Content-Type': 'application/json';
+        'X-BankSync-Timestamp': string;
+        'X-BankSync-Delivery-Id': string;
+        'X-BankSync-Signature': string;
+    };
+}
+declare function buildWebhookEnvelope(args: {
+    delivery_id: string;
+    pairing_code: string;
+    transaction: Transaction;
+}): WebhookEnvelope;
+declare function signWebhook(args: {
+    envelope: WebhookEnvelope;
+    secret: string;
+    timestamp?: number;
+}): Promise<SignedWebhook>;
+type WebhookVerificationCode = 'timestamp_invalid' | 'timestamp_out_of_range' | 'signature_invalid' | 'body_invalid' | 'delivery_id_mismatch' | 'event_unsupported' | 'event_version_unsupported';
+declare class WebhookVerificationError extends Error {
+    readonly code: WebhookVerificationCode;
+    constructor(code: WebhookVerificationCode);
+}
+interface VerifyWebhookArgs {
+    secret: string;
+    timestamp: string;
+    deliveryId: string;
+    bodyBytes: Uint8Array;
+    signature: string;
+    toleranceSeconds?: number;
+    nowSeconds?: number;
+}
+/**
+ * Safe public verification contract. Consumers must durably claim the returned
+ * delivery_id before performing side effects; transport verification cannot
+ * provide durable replay protection by itself.
+ */
+declare function verifyWebhook(args: VerifyWebhookArgs): Promise<WebhookEnvelope>;
+
+/** Encode an alphanumeric payload as an ISO 11649 creditor reference. */
+declare function encodeRf(input: string): string;
+/** Validate an ISO 11649 creditor reference and return its payload. */
+declare function decodeRf(input: unknown): string | null;
+
+interface FioColumn {
+    value?: unknown;
+}
+type FioTransaction = Record<`column${number}`, FioColumn | undefined>;
+declare class FioApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+declare class FioRateLimited extends FioApiError {
+    readonly retryAfterS: number | null;
+    constructor(status: number, retryAfterS: number | null);
+}
+declare class FioTransientFailure extends FioApiError {
+    constructor(status: number);
+}
+/**
+ * Egress relay for Fio pulls. Cloudflare Workers `fetch()` to fioapi.fio.cz
+ * fails the TLS handshake (HTTP 525) — Fio blocks Cloudflare egress — while a
+ * a relay on a network accepted by Fio can reach it. When configured,
+ * Fio requests are POSTed to the proxy edge function which makes the real call
+ * from a non-Cloudflare IP and forwards Fio's status + body verbatim. When
+ * unset, requests go directly to Fio (legacy behaviour, used by unit tests).
+ */
+interface FioProxyConfig {
+    url: string;
+    secret: string;
+}
+declare function fetchNewTransactions(token: string, proxy?: FioProxyConfig): Promise<FioTransaction[]>;
+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 };

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+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';
+
+declare const BANK_CODES: Record<string, string>;
+type EmailProvider = 'fio_email' | 'airbank_email';
+declare function detectProvider(text: string, accountNumber: string | null): 'fio_email' | 'airbank_email' | 'unknown';
+type ParsedEmailTransaction = Omit<Transaction, 'id' | 'bank_account_id' | 'created_at' | 'date'> & {
+    date: string | null;
+};
+declare function parseEmail(text: string, provider: EmailProvider): ParsedEmailTransaction | null;
+
+declare function normalizeCurrency(raw: string): string;
+declare function toCents(amount: number, 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.
+ */
+interface ReferenceSource {
+    vs?: string | null;
+    ss?: string | null;
+    message?: string | null;
+    user_identification?: string | null;
+    comment?: string | null;
+}
+/**
+ * Canonical persistence value for a bank transaction. 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.
+ */
+declare function resolveVariableSymbol(src: ReferenceSource): string | null;
+declare function extractReferenceCandidates(src: ReferenceSource): string[];
+
+interface SignedWebhook {
+    bodyBytes: Uint8Array;
+    headers: {
+        'Content-Type': 'application/json';
+        'X-BankSync-Timestamp': string;
+        'X-BankSync-Delivery-Id': string;
+        'X-BankSync-Signature': string;
+    };
+}
+declare function buildWebhookEnvelope(args: {
+    delivery_id: string;
+    pairing_code: string;
+    transaction: Transaction;
+}): WebhookEnvelope;
+declare function signWebhook(args: {
+    envelope: WebhookEnvelope;
+    secret: string;
+    timestamp?: number;
+}): Promise<SignedWebhook>;
+type WebhookVerificationCode = 'timestamp_invalid' | 'timestamp_out_of_range' | 'signature_invalid' | 'body_invalid' | 'delivery_id_mismatch' | 'event_unsupported' | 'event_version_unsupported';
+declare class WebhookVerificationError extends Error {
+    readonly code: WebhookVerificationCode;
+    constructor(code: WebhookVerificationCode);
+}
+interface VerifyWebhookArgs {
+    secret: string;
+    timestamp: string;
+    deliveryId: string;
+    bodyBytes: Uint8Array;
+    signature: string;
+    toleranceSeconds?: number;
+    nowSeconds?: number;
+}
+/**
+ * Safe public verification contract. Consumers must durably claim the returned
+ * delivery_id before performing side effects; transport verification cannot
+ * provide durable replay protection by itself.
+ */
+declare function verifyWebhook(args: VerifyWebhookArgs): Promise<WebhookEnvelope>;
+
+/** Encode an alphanumeric payload as an ISO 11649 creditor reference. */
+declare function encodeRf(input: string): string;
+/** Validate an ISO 11649 creditor reference and return its payload. */
+declare function decodeRf(input: unknown): string | null;
+
+interface FioColumn {
+    value?: unknown;
+}
+type FioTransaction = Record<`column${number}`, FioColumn | undefined>;
+declare class FioApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+declare class FioRateLimited extends FioApiError {
+    readonly retryAfterS: number | null;
+    constructor(status: number, retryAfterS: number | null);
+}
+declare class FioTransientFailure extends FioApiError {
+    constructor(status: number);
+}
+/**
+ * Egress relay for Fio pulls. Cloudflare Workers `fetch()` to fioapi.fio.cz
+ * fails the TLS handshake (HTTP 525) — Fio blocks Cloudflare egress — while a
+ * a relay on a network accepted by Fio can reach it. When configured,
+ * Fio requests are POSTed to the proxy edge function which makes the real call
+ * from a non-Cloudflare IP and forwards Fio's status + body verbatim. When
+ * unset, requests go directly to Fio (legacy behaviour, used by unit tests).
+ */
+interface FioProxyConfig {
+    url: string;
+    secret: string;
+}
+declare function fetchNewTransactions(token: string, proxy?: FioProxyConfig): Promise<FioTransaction[]>;
+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 };

package/dist/index.js

@@ -0,0 +1,42 @@
+import {
+  BANK_CODES,
+  FioApiError,
+  FioRateLimited,
+  FioTransientFailure,
+  WebhookVerificationError,
+  buildWebhookEnvelope,
+  decodeRf,
+  detectProvider,
+  encodeRf,
+  extractReferenceCandidates,
+  fetchNewTransactions,
+  mapFioTransaction,
+  normalizeCurrency,
+  parseEmail,
+  resolveVariableSymbol,
+  setFioPointer,
+  signWebhook,
+  toCents,
+  verifyWebhook
+} from "./chunk-5QXHZGAW.js";
+export {
+  BANK_CODES,
+  FioApiError,
+  FioRateLimited,
+  FioTransientFailure,
+  WebhookVerificationError,
+  buildWebhookEnvelope,
+  decodeRf,
+  detectProvider,
+  encodeRf,
+  extractReferenceCandidates,
+  fetchNewTransactions,
+  mapFioTransaction,
+  normalizeCurrency,
+  parseEmail,
+  resolveVariableSymbol,
+  setFioPointer,
+  signWebhook,
+  toCents,
+  verifyWebhook
+};

package/dist/types-Cb5l2lXq.d.cts

@@ -0,0 +1,86 @@
+interface BankAccount {
+    id: number;
+    account_number: string;
+    account_type: string;
+    ingest_mode: 'email' | 'api' | 'both';
+    pairing_code: string;
+    label: string | null;
+    owner_app_id: string | null;
+    /** CF Email Routing rule id (set when banksync calls CF API on account create); null in dev/test environments without CF_API_TOKEN. */
+    cf_rule_id: string | null;
+    api_token_set: boolean;
+    api_token_prefix: string | null;
+    api_fetch_enabled: boolean;
+    api_last_fetch_at: string | null;
+    api_last_success_at: string | null;
+    api_last_error: string | null;
+    api_backfill_done: boolean;
+    created_at: string;
+}
+interface Transaction {
+    id: number;
+    bank_account_id: number;
+    /** INTEGER, lowest unit (e.g. 1990 = 19.90 CZK), incoming-only — always positive */
+    amount_cents: number;
+    /** ISO 4217 alpha-3 uppercase (CZK/EUR/USD) */
+    currency: string;
+    counter_account: string | null;
+    bank_code: string | null;
+    bank_name: string | null;
+    vs: string | null;
+    ks: string | null;
+    ss: string | null;
+    message: string | null;
+    sender_name: string | null;
+    /** Fio API column7, available only from Fio API pull */
+    user_identification: string | null;
+    /** Fio API column8, available only from Fio API pull */
+    transaction_type: string | null;
+    /** Fio API column9, available only from Fio API pull */
+    performed_by: string | null;
+    /** Fio API column25, available only from Fio API pull */
+    comment: string | null;
+    /** Fio API column17 — ID pokynu, available only from Fio API pull */
+    command_id: string | null;
+    source: 'email' | 'fio_api';
+    date: string;
+    /** Original timezone offset in minutes (e.g. CET=60, CEST=120). Debug only — all queries use UTC date. */
+    date_offset_min: number | null;
+    transaction_id: string | null;
+    external_id: string | null;
+}
+interface WebhookEnvelope {
+    event: 'transaction.received';
+    /** Bumped when shape of `data` or signing string changes */
+    event_version: '1';
+    /** ULID, stable across retries — sole idempotence key */
+    delivery_id: string;
+    pairing_code: string;
+    data: Transaction;
+}
+interface WebhookConsumer {
+    id: number;
+    app_id: string;
+    callback_url: string;
+    /** AES-GCM ciphertext; base64(iv || ct || tag) */
+    secret_cipher: string;
+    /** SHA-256(plaintext) hex — audit / mismatch detection */
+    secret_hash: string;
+    /** First 6 characters of plaintext for identification */
+    secret_prefix: string;
+    /** Previous secret ciphertext during rotation grace period */
+    prev_secret_cipher: string | null;
+    /** UTC ISO; NULL when no active rotation grace */
+    prev_expires_at: string | null;
+    admin_key_hash: string | null;
+    admin_key_prefix: string | null;
+    created_at: string;
+}
+interface WebhookSubscription {
+    id: number;
+    bank_account_id: number;
+    consumer_app_id: string;
+    created_at: string;
+}
+
+export type { BankAccount as B, Transaction as T, WebhookEnvelope as W, WebhookConsumer as a, WebhookSubscription as b };

package/dist/types-Cb5l2lXq.d.ts

@@ -0,0 +1,86 @@
+interface BankAccount {
+    id: number;
+    account_number: string;
+    account_type: string;
+    ingest_mode: 'email' | 'api' | 'both';
+    pairing_code: string;
+    label: string | null;
+    owner_app_id: string | null;
+    /** CF Email Routing rule id (set when banksync calls CF API on account create); null in dev/test environments without CF_API_TOKEN. */
+    cf_rule_id: string | null;
+    api_token_set: boolean;
+    api_token_prefix: string | null;
+    api_fetch_enabled: boolean;
+    api_last_fetch_at: string | null;
+    api_last_success_at: string | null;
+    api_last_error: string | null;
+    api_backfill_done: boolean;
+    created_at: string;
+}
+interface Transaction {
+    id: number;
+    bank_account_id: number;
+    /** INTEGER, lowest unit (e.g. 1990 = 19.90 CZK), incoming-only — always positive */
+    amount_cents: number;
+    /** ISO 4217 alpha-3 uppercase (CZK/EUR/USD) */
+    currency: string;
+    counter_account: string | null;
+    bank_code: string | null;
+    bank_name: string | null;
+    vs: string | null;
+    ks: string | null;
+    ss: string | null;
+    message: string | null;
+    sender_name: string | null;
+    /** Fio API column7, available only from Fio API pull */
+    user_identification: string | null;
+    /** Fio API column8, available only from Fio API pull */
+    transaction_type: string | null;
+    /** Fio API column9, available only from Fio API pull */
+    performed_by: string | null;
+    /** Fio API column25, available only from Fio API pull */
+    comment: string | null;
+    /** Fio API column17 — ID pokynu, available only from Fio API pull */
+    command_id: string | null;
+    source: 'email' | 'fio_api';
+    date: string;
+    /** Original timezone offset in minutes (e.g. CET=60, CEST=120). Debug only — all queries use UTC date. */
+    date_offset_min: number | null;
+    transaction_id: string | null;
+    external_id: string | null;
+}
+interface WebhookEnvelope {
+    event: 'transaction.received';
+    /** Bumped when shape of `data` or signing string changes */
+    event_version: '1';
+    /** ULID, stable across retries — sole idempotence key */
+    delivery_id: string;
+    pairing_code: string;
+    data: Transaction;
+}
+interface WebhookConsumer {
+    id: number;
+    app_id: string;
+    callback_url: string;
+    /** AES-GCM ciphertext; base64(iv || ct || tag) */
+    secret_cipher: string;
+    /** SHA-256(plaintext) hex — audit / mismatch detection */
+    secret_hash: string;
+    /** First 6 characters of plaintext for identification */
+    secret_prefix: string;
+    /** Previous secret ciphertext during rotation grace period */
+    prev_secret_cipher: string | null;
+    /** UTC ISO; NULL when no active rotation grace */
+    prev_expires_at: string | null;
+    admin_key_hash: string | null;
+    admin_key_prefix: string | null;
+    created_at: string;
+}
+interface WebhookSubscription {
+    id: number;
+    bank_account_id: number;
+    consumer_app_id: string;
+    created_at: string;
+}
+
+export type { BankAccount as B, Transaction as T, WebhookEnvelope as W, WebhookConsumer as a, WebhookSubscription as b };