thunder-bridge 1.4.1 → 1.5.0

package/dist/bank-B3mHISn1.d.cts

@@ -0,0 +1,92 @@
+/** One incoming payment as the bank booked it, in the smallest unit of its currency */
+interface Credit {
+    amountMinor: number;
+    currency: string;
+    /** Whatever the payer wrote, wherever this bank puts it. Matching is a substring, so noise around it is fine */
+    reference: string;
+    /**
+     * Unix seconds. A bank that books a day rather than an instant, as Fio does,
+     * gives the day's midnight in its own zone, so rendering this in UTC can show
+     * the day before. Nothing here matches on it, it is yours to read
+     */
+    bookedAt: number;
+}
+/**
+ * Recent credits on one account, oldest or newest first, it makes no difference.
+ * This is the whole plugin seam: a bank is a function of this shape, and
+ * `fioStatement` is one implementation of it
+ */
+type Statement = (sinceUnix: number) => Promise<Credit[]>;
+/** One transfer to ask for: what is owed, where it lands, and where its arrival is read back from */
+interface BankTransferParams {
+    /** Long lived and server side. The preimage is derived from it, so losing it loses every proof */
+    secret: string;
+    /** What the payer must leave on the transfer, an order id or a nonce. It is matched, not stored */
+    reference: string;
+    /** The price in the smallest unit, so 48055 is 480.55 CZK */
+    amountMinor: number;
+    /** The account the money goes to, as an IBAN */
+    iban: string;
+    /** Where `bankVerifyEndpoint` is mounted, a public https URL with no query of its own */
+    verifyUrl: string;
+    /** When the offer dies, in unix seconds. Money in a bank moves on banking days, so give it days */
+    expiresAt: number;
+    /** Defaults to CZK */
+    currency?: string;
+    /** Up to ten digits, for accounting systems that still want one */
+    variableSymbol?: string;
+    /**
+     * Groups this transfer with everything else paid to the same secret, so one
+     * `followTrigger` socket hears about it. Give the Lightning leg of the same
+     * order the same secret and both rails arrive on one stream
+     */
+    trigger?: string;
+    /** How many settlements of that trigger the gateway keeps replayable past the hour, needs `trigger` */
+    replay?: number;
+    /**
+     * Handed back untouched on that stream, so a watcher learns which order settled
+     * without asking anyone. `seal` it and the gateway cannot read it either
+     */
+    sealed?: string;
+    /**
+     * Where the gateway posts once the money lands, a public https URL. Without one
+     * a transfer is only ever learned by following the trigger or asking
+     */
+    webhookUrl?: string;
+    /**
+     * Register on a gateway you do not own anyway. The verify URL names the amount
+     * and the reference, so its operator ends up reading your order book, and the
+     * URL itself answers whether that order was paid. Say true only when the order
+     * book is not worth hiding
+     */
+    allowPublicGateway?: boolean;
+}
+/** A transfer the gateway is now watching, and the descriptor the payer scans */
+interface BankTransfer {
+    /** The watched payment's id at the gateway, which is how you read this order back */
+    id: string;
+    /** What the gateway was given, and what the preimage has to hash to */
+    paymentHash: string;
+    /** The same URL you mounted, carrying what to look for and a signature over it */
+    verifyUrl: string;
+    /** The payer scans this, it is a Short Payment Descriptor, the Czech QR platba format */
+    spd: string;
+}
+/** The endpoint the gateway polls for a bank transfer, answering off your own statement */
+interface BankVerifyConfig {
+    /** The same secret `bankTransfer` was given */
+    secret: string;
+    /** The account to read */
+    statement: Statement;
+    /** How far back a credit still counts, seven days by default */
+    lookBackSecs?: number;
+    /**
+     * How often you want the gateway to ask, in seconds. It goes out as
+     * `Cache-Control: max-age`, so the pace is yours to set rather than the
+     * gateway's, and a bank that updates once a minute should say so instead of
+     * being polled every few seconds. Thirty by default, clamped to an hour
+     */
+    pollEverySecs?: number;
+}
+
+export type { BankTransfer as B, Credit as C, Statement as S, BankTransferParams as a, BankVerifyConfig as b };

package/dist/bank-B3mHISn1.d.ts

@@ -0,0 +1,92 @@
+/** One incoming payment as the bank booked it, in the smallest unit of its currency */
+interface Credit {
+    amountMinor: number;
+    currency: string;
+    /** Whatever the payer wrote, wherever this bank puts it. Matching is a substring, so noise around it is fine */
+    reference: string;
+    /**
+     * Unix seconds. A bank that books a day rather than an instant, as Fio does,
+     * gives the day's midnight in its own zone, so rendering this in UTC can show
+     * the day before. Nothing here matches on it, it is yours to read
+     */
+    bookedAt: number;
+}
+/**
+ * Recent credits on one account, oldest or newest first, it makes no difference.
+ * This is the whole plugin seam: a bank is a function of this shape, and
+ * `fioStatement` is one implementation of it
+ */
+type Statement = (sinceUnix: number) => Promise<Credit[]>;
+/** One transfer to ask for: what is owed, where it lands, and where its arrival is read back from */
+interface BankTransferParams {
+    /** Long lived and server side. The preimage is derived from it, so losing it loses every proof */
+    secret: string;
+    /** What the payer must leave on the transfer, an order id or a nonce. It is matched, not stored */
+    reference: string;
+    /** The price in the smallest unit, so 48055 is 480.55 CZK */
+    amountMinor: number;
+    /** The account the money goes to, as an IBAN */
+    iban: string;
+    /** Where `bankVerifyEndpoint` is mounted, a public https URL with no query of its own */
+    verifyUrl: string;
+    /** When the offer dies, in unix seconds. Money in a bank moves on banking days, so give it days */
+    expiresAt: number;
+    /** Defaults to CZK */
+    currency?: string;
+    /** Up to ten digits, for accounting systems that still want one */
+    variableSymbol?: string;
+    /**
+     * Groups this transfer with everything else paid to the same secret, so one
+     * `followTrigger` socket hears about it. Give the Lightning leg of the same
+     * order the same secret and both rails arrive on one stream
+     */
+    trigger?: string;
+    /** How many settlements of that trigger the gateway keeps replayable past the hour, needs `trigger` */
+    replay?: number;
+    /**
+     * Handed back untouched on that stream, so a watcher learns which order settled
+     * without asking anyone. `seal` it and the gateway cannot read it either
+     */
+    sealed?: string;
+    /**
+     * Where the gateway posts once the money lands, a public https URL. Without one
+     * a transfer is only ever learned by following the trigger or asking
+     */
+    webhookUrl?: string;
+    /**
+     * Register on a gateway you do not own anyway. The verify URL names the amount
+     * and the reference, so its operator ends up reading your order book, and the
+     * URL itself answers whether that order was paid. Say true only when the order
+     * book is not worth hiding
+     */
+    allowPublicGateway?: boolean;
+}
+/** A transfer the gateway is now watching, and the descriptor the payer scans */
+interface BankTransfer {
+    /** The watched payment's id at the gateway, which is how you read this order back */
+    id: string;
+    /** What the gateway was given, and what the preimage has to hash to */
+    paymentHash: string;
+    /** The same URL you mounted, carrying what to look for and a signature over it */
+    verifyUrl: string;
+    /** The payer scans this, it is a Short Payment Descriptor, the Czech QR platba format */
+    spd: string;
+}
+/** The endpoint the gateway polls for a bank transfer, answering off your own statement */
+interface BankVerifyConfig {
+    /** The same secret `bankTransfer` was given */
+    secret: string;
+    /** The account to read */
+    statement: Statement;
+    /** How far back a credit still counts, seven days by default */
+    lookBackSecs?: number;
+    /**
+     * How often you want the gateway to ask, in seconds. It goes out as
+     * `Cache-Control: max-age`, so the pace is yours to set rather than the
+     * gateway's, and a bank that updates once a minute should say so instead of
+     * being polled every few seconds. Thirty by default, clamped to an hour
+     */
+    pollEverySecs?: number;
+}
+
+export type { BankTransfer as B, Credit as C, Statement as S, BankTransferParams as a, BankVerifyConfig as b };

package/dist/bank.cjs

@@ -0,0 +1,141 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/entry/bank.ts
+var bank_exports = {};
+__export(bank_exports, {
+  fioStatement: () => fioStatement
+});
+module.exports = __toCommonJS(bank_exports);
+
+// src/fio.ts
+var BASE_URL = "https://fioapi.fio.cz/v1/rest";
+var MINOR_UNITS = 100;
+var MILLIS = 1e3;
+var DATE_CHARS = "2026-08-04".length;
+var DEFAULT_MIN_INTERVAL_SECS = 30;
+var TOO_SOON = 409;
+var BOOKED_AT = "column0";
+var AMOUNT = "column1";
+var CURRENCY = "column14";
+var VARIABLE_SYMBOL = "column5";
+var USER_IDENTIFICATION = "column7";
+var MESSAGE_FOR_RECIPIENT = "column16";
+var PAYER_REFERENCE = "column27";
+var WHERE_A_PAYER_WRITES = [
+  MESSAGE_FOR_RECIPIENT,
+  VARIABLE_SYMBOL,
+  USER_IDENTIFICATION,
+  PAYER_REFERENCE
+];
+var UTC_OFFSET = /^[+-]\d{4}$/;
+function fioStatement(config) {
+  const named = typeof config.token === "string" ? [config.token] : config.token;
+  if (named.length === 0) {
+    throw new Error("fioStatement needs at least one token to read with");
+  }
+  const usedAt = new Map(named.map((token) => [token, Number.NEGATIVE_INFINITY]));
+  const tokenWindowMs = (config.minIntervalSecs ?? DEFAULT_MIN_INTERVAL_SECS) * MILLIS;
+  const paceMs = tokenWindowMs / usedAt.size;
+  let lastRead = Number.NEGATIVE_INFINITY;
+  let credits = [];
+  return async (sinceUnix) => {
+    const now = Date.now();
+    if (now - lastRead < paceMs) {
+      return credits;
+    }
+    const idlest = longestUnused(usedAt);
+    if (now - idlest.usedAt < tokenWindowMs) {
+      return credits;
+    }
+    usedAt.set(idlest.token, now);
+    lastRead = now;
+    const url = [
+      config.baseUrl ?? BASE_URL,
+      "periods",
+      idlest.token,
+      asDate(sinceUnix),
+      asDate(Math.floor(now / MILLIS)),
+      "transactions.json"
+    ].join("/");
+    const answer = await fetch(url, { headers: { accept: "application/json" } });
+    if (answer.status === TOO_SOON) {
+      throw new Error("fio refuses a second read of this token inside its 30 second window");
+    }
+    if (!answer.ok) {
+      throw new Error(`fio answered ${answer.status} reading the statement`);
+    }
+    const read = await answer.json();
+    credits = (read.accountStatement?.transactionList?.transaction ?? []).filter(isCredit).map(asCredit);
+    return credits;
+  };
+}
+function longestUnused(usedAt) {
+  let token = "";
+  let idleSince = Number.POSITIVE_INFINITY;
+  for (const [candidate, at] of usedAt) {
+    if (at < idleSince) {
+      token = candidate;
+      idleSince = at;
+    }
+  }
+  return { token, usedAt: idleSince };
+}
+function isCredit(transaction) {
+  return numberIn(transaction[AMOUNT]) > 0;
+}
+function asCredit(transaction) {
+  return {
+    amountMinor: Math.round(numberIn(transaction[AMOUNT]) * MINOR_UNITS),
+    currency: textIn(transaction[CURRENCY]),
+    reference: WHERE_A_PAYER_WRITES.map((column) => textIn(transaction[column])).filter((written) => written.length > 0).join(" "),
+    bookedAt: bookedAtIn(transaction[BOOKED_AT])
+  };
+}
+function bookedAtIn(cell) {
+  const value = cell?.value;
+  if (typeof value === "number") {
+    return Math.floor(value / MILLIS);
+  }
+  const at = Date.parse(asIso8601(textIn(cell)));
+  return Number.isFinite(at) ? Math.floor(at / MILLIS) : 0;
+}
+function asIso8601(booked) {
+  const day = booked.slice(0, DATE_CHARS);
+  const zone = booked.slice(DATE_CHARS);
+  if (!UTC_OFFSET.test(zone)) {
+    return `${day}T00:00:00Z`;
+  }
+  return `${day}T00:00:00${zone.slice(0, 3)}:${zone.slice(3)}`;
+}
+function numberIn(cell) {
+  const value = Number(cell?.value ?? Number.NaN);
+  return Number.isFinite(value) ? value : 0;
+}
+function textIn(cell) {
+  const value = cell?.value;
+  return value === null || value === void 0 ? "" : String(value).trim();
+}
+function asDate(unix) {
+  return new Date(unix * MILLIS).toISOString().slice(0, DATE_CHARS);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fioStatement
+});

package/dist/bank.d.cts

@@ -0,0 +1,44 @@
+import { S as Statement } from './bank-B3mHISn1.cjs';
+export { B as BankTransfer, a as BankTransferParams, b as BankVerifyConfig, C as Credit } from './bank-B3mHISn1.cjs';
+
+/** A Fio account to read credits from, as its own API describes one */
+interface FioConfig {
+    /**
+     * A token with "Sledování účtu" rights, which is read only and cannot move
+     * money. One token is one account, which is why this takes no account number.
+     *
+     * Give it several and they are used in turn. Fio's window is per token rather
+     * than per account, so five tokens on one account is a read every six seconds,
+     * and generating another token for the same account is what Fio's own
+     * documentation suggests when one is not enough
+     */
+    token: string | string[];
+    /**
+     * Fio's window for one token, 30 seconds. No token is ever asked twice inside
+     * it, and the gap between reads is this divided by however many tokens were
+     * given, so the answers stay evenly spaced rather than arriving in bursts.
+     * Inside that gap the last answer is handed back. Only helps a process that
+     * stays up
+     */
+    minIntervalSecs?: number;
+    /** Override to point at a mock */
+    baseUrl?: string;
+}
+/**
+ * Read one Fio account as a `Statement`, so a bank transfer proves itself the
+ * way a Lightning payment does.
+ *
+ * The token is the read only kind, generated in internetbanking under Nastavení
+ * and API, and it is the whole configuration: a token belongs to one account, so
+ * there is no account number to get wrong. It cannot pay anyone, and the worst a
+ * leaked one costs you is that someone else can read the statement.
+ *
+ * Every field on a Fio transaction is optional and arrives as `null` when it is
+ * absent, the amount carries its direction in its sign rather than in a flag,
+ * and the date is a day and a UTC offset, `2026-07-15+0200`. This reads all
+ * three the way the bank answers them and treats a missing field as absent
+ * rather than guessing.
+ */
+declare function fioStatement(config: FioConfig): Statement;
+
+export { type FioConfig, Statement, fioStatement };

package/dist/bank.d.ts

@@ -0,0 +1,44 @@
+import { S as Statement } from './bank-B3mHISn1.js';
+export { B as BankTransfer, a as BankTransferParams, b as BankVerifyConfig, C as Credit } from './bank-B3mHISn1.js';
+
+/** A Fio account to read credits from, as its own API describes one */
+interface FioConfig {
+    /**
+     * A token with "Sledování účtu" rights, which is read only and cannot move
+     * money. One token is one account, which is why this takes no account number.
+     *
+     * Give it several and they are used in turn. Fio's window is per token rather
+     * than per account, so five tokens on one account is a read every six seconds,
+     * and generating another token for the same account is what Fio's own
+     * documentation suggests when one is not enough
+     */
+    token: string | string[];
+    /**
+     * Fio's window for one token, 30 seconds. No token is ever asked twice inside
+     * it, and the gap between reads is this divided by however many tokens were
+     * given, so the answers stay evenly spaced rather than arriving in bursts.
+     * Inside that gap the last answer is handed back. Only helps a process that
+     * stays up
+     */
+    minIntervalSecs?: number;
+    /** Override to point at a mock */
+    baseUrl?: string;
+}
+/**
+ * Read one Fio account as a `Statement`, so a bank transfer proves itself the
+ * way a Lightning payment does.
+ *
+ * The token is the read only kind, generated in internetbanking under Nastavení
+ * and API, and it is the whole configuration: a token belongs to one account, so
+ * there is no account number to get wrong. It cannot pay anyone, and the worst a
+ * leaked one costs you is that someone else can read the statement.
+ *
+ * Every field on a Fio transaction is optional and arrives as `null` when it is
+ * absent, the amount carries its direction in its sign rather than in a flag,
+ * and the date is a day and a UTC offset, `2026-07-15+0200`. This reads all
+ * three the way the bank answers them and treats a missing field as absent
+ * rather than guessing.
+ */
+declare function fioStatement(config: FioConfig): Statement;
+
+export { type FioConfig, Statement, fioStatement };

package/dist/bank.js

@@ -0,0 +1,114 @@
+// src/fio.ts
+var BASE_URL = "https://fioapi.fio.cz/v1/rest";
+var MINOR_UNITS = 100;
+var MILLIS = 1e3;
+var DATE_CHARS = "2026-08-04".length;
+var DEFAULT_MIN_INTERVAL_SECS = 30;
+var TOO_SOON = 409;
+var BOOKED_AT = "column0";
+var AMOUNT = "column1";
+var CURRENCY = "column14";
+var VARIABLE_SYMBOL = "column5";
+var USER_IDENTIFICATION = "column7";
+var MESSAGE_FOR_RECIPIENT = "column16";
+var PAYER_REFERENCE = "column27";
+var WHERE_A_PAYER_WRITES = [
+  MESSAGE_FOR_RECIPIENT,
+  VARIABLE_SYMBOL,
+  USER_IDENTIFICATION,
+  PAYER_REFERENCE
+];
+var UTC_OFFSET = /^[+-]\d{4}$/;
+function fioStatement(config) {
+  const named = typeof config.token === "string" ? [config.token] : config.token;
+  if (named.length === 0) {
+    throw new Error("fioStatement needs at least one token to read with");
+  }
+  const usedAt = new Map(named.map((token) => [token, Number.NEGATIVE_INFINITY]));
+  const tokenWindowMs = (config.minIntervalSecs ?? DEFAULT_MIN_INTERVAL_SECS) * MILLIS;
+  const paceMs = tokenWindowMs / usedAt.size;
+  let lastRead = Number.NEGATIVE_INFINITY;
+  let credits = [];
+  return async (sinceUnix) => {
+    const now = Date.now();
+    if (now - lastRead < paceMs) {
+      return credits;
+    }
+    const idlest = longestUnused(usedAt);
+    if (now - idlest.usedAt < tokenWindowMs) {
+      return credits;
+    }
+    usedAt.set(idlest.token, now);
+    lastRead = now;
+    const url = [
+      config.baseUrl ?? BASE_URL,
+      "periods",
+      idlest.token,
+      asDate(sinceUnix),
+      asDate(Math.floor(now / MILLIS)),
+      "transactions.json"
+    ].join("/");
+    const answer = await fetch(url, { headers: { accept: "application/json" } });
+    if (answer.status === TOO_SOON) {
+      throw new Error("fio refuses a second read of this token inside its 30 second window");
+    }
+    if (!answer.ok) {
+      throw new Error(`fio answered ${answer.status} reading the statement`);
+    }
+    const read = await answer.json();
+    credits = (read.accountStatement?.transactionList?.transaction ?? []).filter(isCredit).map(asCredit);
+    return credits;
+  };
+}
+function longestUnused(usedAt) {
+  let token = "";
+  let idleSince = Number.POSITIVE_INFINITY;
+  for (const [candidate, at] of usedAt) {
+    if (at < idleSince) {
+      token = candidate;
+      idleSince = at;
+    }
+  }
+  return { token, usedAt: idleSince };
+}
+function isCredit(transaction) {
+  return numberIn(transaction[AMOUNT]) > 0;
+}
+function asCredit(transaction) {
+  return {
+    amountMinor: Math.round(numberIn(transaction[AMOUNT]) * MINOR_UNITS),
+    currency: textIn(transaction[CURRENCY]),
+    reference: WHERE_A_PAYER_WRITES.map((column) => textIn(transaction[column])).filter((written) => written.length > 0).join(" "),
+    bookedAt: bookedAtIn(transaction[BOOKED_AT])
+  };
+}
+function bookedAtIn(cell) {
+  const value = cell?.value;
+  if (typeof value === "number") {
+    return Math.floor(value / MILLIS);
+  }
+  const at = Date.parse(asIso8601(textIn(cell)));
+  return Number.isFinite(at) ? Math.floor(at / MILLIS) : 0;
+}
+function asIso8601(booked) {
+  const day = booked.slice(0, DATE_CHARS);
+  const zone = booked.slice(DATE_CHARS);
+  if (!UTC_OFFSET.test(zone)) {
+    return `${day}T00:00:00Z`;
+  }
+  return `${day}T00:00:00${zone.slice(0, 3)}:${zone.slice(3)}`;
+}
+function numberIn(cell) {
+  const value = Number(cell?.value ?? Number.NaN);
+  return Number.isFinite(value) ? value : 0;
+}
+function textIn(cell) {
+  const value = cell?.value;
+  return value === null || value === void 0 ? "" : String(value).trim();
+}
+function asDate(unix) {
+  return new Date(unix * MILLIS).toISOString().slice(0, DATE_CHARS);
+}
+export {
+  fioStatement
+};