@festapp/banksync 0.1.5 → 0.2.1

package/README.md

@@ -23,8 +23,8 @@ receive bank activity → authenticate → normalize → deduplicate → deliver
 | | |
 |---|---|
 | **Inputs** | Fio Bank email, Fio API, Air Bank email |
-| **Output** | Signed `transaction.received` webhook, version `1` |
-| **Runtime** | Cloudflare Workers, Email Routing, D1 and Queues; optional R2 |
+| **Output** | Signed `transaction.received` webhook, consumer-selected version `1` or `2` |
+| **Runtime** | Cloudflare Workers, Email Routing, D1 and Queues; R2 required for durable email recovery |
 | **Package** | Runtime-neutral helpers plus a separate Cloudflare Worker export |
 | **Safety model** | Tenant ownership, authenticated email identity, durable idempotency and exact-host callback policy |
 
@@ -109,7 +109,7 @@ export type { Env } from "@festapp/banksync/cloudflare";
 
 - Node.js 20 or newer and pnpm;
 - a Cloudflare account with Workers, D1, Queues and Email Routing;
-- an R2 bucket only if encrypted backups are enabled;
+- an R2 bucket for authenticated email recovery or encrypted backups;
 - exact callback hostnames for every intended webhook consumer.
 
 ### Setup
@@ -118,9 +118,9 @@ export type { Env } from "@festapp/banksync/cloudflare";
 2. Copy [`wrangler.example.toml`](wrangler.example.toml) to `wrangler.toml` and
    replace every resource placeholder.
 3. Create the D1 database and queues named by the configuration.
-4. For a fresh database, apply `migrations/0001_schema.sql`. For a production
-   database whose recorded history ends at `0009`, apply only
-   `migrations/0010_security_hardening.sql` through a scoped, reviewed migration.
+4. Apply the baseline and forward migrations on a fresh database. An existing
+   version-10 database advances only through `0011_complete_bank_facts.sql`.
+   Preserve recorded migration history and use a scoped reviewed rollout.
 5. Configure `ADMIN_SECRET`, `WEBHOOK_KEK`, `ENCRYPTION_KEY_V1`, and—when R2
    backups are enabled—the selected `BACKUP_ENCRYPTION_KEY_Vn` with
    `pnpm wrangler secret put <NAME>`.
@@ -142,8 +142,8 @@ keys outside R2 and prove restore before rotation. Never commit `wrangler.toml`,
 
 Fresh databases use the single canonical baseline `0001_schema.sql`, which
 creates schema version 10. Existing databases retain their recorded `0001`–`0009`
-history and advance through `0010_security_hardening.sql`. Future migrations
-must start at `0011`; never renumber or replace the baseline.
+history and advance through `0010_security_hardening.sql`, then
+`0011_complete_bank_facts.sql` to version 11. Never renumber or replace the baseline.
 
 BankSync D1 is intentionally independent of consumer billing databases.
 BankSync emits authenticated transaction facts. Each consumer owns settlement,
@@ -216,6 +216,13 @@ pnpm pack --dry-run
 builds, and package-export verification. Provider-live tests are intentionally
 outside the default suite and must never use production bank credentials.
 
+Dependabot minor and patch updates for development dependencies and GitHub
+Actions automatically merge after all required checks pass on an up-to-date
+branch. Major updates and production dependency updates require manual review.
+TypeScript major updates are held back until the declaration build supports
+the newer compiler API. The auto-merge workflow reads verified Dependabot
+metadata only; it never checks out or runs pull-request code.
+
 Stable releases are created from protected `v*` tags by GitHub Actions, publish
 to npm through OIDC trusted publishing, and attach the exact same tarball,
 checksum, provenance and SBOM to the GitHub Release.
@@ -223,3 +230,52 @@ checksum, provenance and SBOM to the GitHub Release.
 ## License
 
 [MIT](LICENSE) © Festapp
+
+
+## Version 0.2 integration contract
+
+Existing consumers default to event version 1. Register a new prepared consumer
+with `event_version: "2"`; its receiver calls `verifyWebhook({...args,
+eventVersion: "2"})`. Receipt version remains 1. V1 receives only incoming facts
+in its original shape; archived delivery payloads are immutable.
+
+V2 adds `payer_reference`, `raw_vs`, signed `amount_cents`, `direction`,
+`identity_kind` and `identity_provenance`. Decimal amounts and numeric bank IDs
+are range-checked without rounding. Similar VS/amount/date never deduplicates
+real movements. Transport IDs are account-scoped. Fio `ID pokynu` is a command,
+not a movement; unproven email IDs are observations. Financial consumers must
+quarantine observations until their own authorized reconciliation establishes
+bank identity. `both` is unavailable to v2 pending provider correlation proof.
+
+On schema 11, all Fio manual/queue/cron imports share physical-account and full
+credential-hash leases. Imports use bounded `periods` reads, an encrypted durable
+batch, and a checkpoint committed only after every row succeeds. They never
+advance `/last`. The bootstrap covers 90 calendar dates; subsequent pulls overlap
+three days. Older unresolved windows require operator/bank authorization rather
+than silent truncation. Receiving-account and statement currency mismatches leave
+the batch open.
+
+A new connection can be created with `ingest_enabled:false`. Persist mapping and
+verify its owner subscription before `PUT /bank-accounts/:id/ingest-state` with
+`{enabled:true}`. Account identity cannot change under existing movements.
+`GET .../ingest-state` provides the full credential digest for timeout recovery,
+never the credential. Creation idempotency receipts are retained permanently.
+
+New v2 email connections require `AUTHENTICATED_EMAIL_SPOOL=on` and `BACKUPS`.
+Strict bank authentication precedes encrypted R2 persistence; persistence precedes
+D1 account lookup. Original MIME bytes and trusted envelope evidence survive D1
+outages. Scheduled cursor recovery visits failed messages without starving newer
+ones. Authenticated parse failures stay quarantined. No active legacy recipient
+migration is implied. New provider email automation requires real sanitized bank
+fixtures and a genuine authenticated ingress canary.
+
+`GET /bank-accounts/:id/transaction-export` returns complete account facts with
+`cursor`, fixed `high_water` and `complete`; persist both coordinates.
+`POST /admin/cutover-reconcile` is admin-only, requires a manifest SHA-256 and
+an exact owner consumer/account/ID window, creates only missing v2 intents, and
+never rewrites an archived payload or globally changes subscription intervals.
+Unresolved or quarantined facts are retained beyond the usual 90-day cleanup.
+Publishing this package does not deploy the shared Worker, mutate D1, enable bank
+polling, or authorize replay of another consumer's history.
+
+Canonical v2 transactions preserve bank-provided VS and payer reference without inferring an order identifier. Each consumer (Festapp, Mendelio, or another application) owns payment matching and business rules. The existing v1 RF-to-VS projection remains only as an explicit backwards-compatible adapter.

package/dist/{chunk-5QXHZGAW.js → chunk-3WM2GGFL.js}

@@ -28,6 +28,15 @@ function toCents(amount, currency) {
   }
   return Math.round(amount * 10 ** dec);
 }
+function decimalToCents(raw, currency) {
+  if (MINOR_UNIT_DECIMALS[currency] !== 2) throw new Error("unsupported_currency_minor_unit");
+  const normalized = raw.replace(/\s/g, "").replace(",", ".");
+  const match = /^([+-]?)(\d+)(?:\.(\d{1,2}))?$/.exec(normalized);
+  if (!match) throw new Error("invalid_exact_amount");
+  const cents = (BigInt(match[2]) * 100n + BigInt((match[3] ?? "").padEnd(2, "0"))) * (match[1] === "-" ? -1n : 1n);
+  if (cents > BigInt(Number.MAX_SAFE_INTEGER) || cents < BigInt(Number.MIN_SAFE_INTEGER)) throw new Error("amount_out_of_range");
+  return Number(cents);
+}
 
 // src/parser.ts
 var BANK_CODES = {
@@ -200,15 +209,15 @@ function parseEmail(text, provider) {
     const currency = normalizeCurrency(rawCurrencyStr);
     const amount = parseAmount(amountField.rawAmount);
     if (isNaN(amount)) return null;
-    if (amount < 0) return null;
-    const amount_cents = toCents(amount, currency);
+    const amount_cents = decimalToCents(amountField.rawAmount, currency);
     const accountMatch = text.match(/(?:Protiúčet|Protiucet|Account):\s*([0-9\/\s]+)/i);
     const vsMatch = text.match(/VS:\s*([0-9]+)/i);
     const ksMatch = text.match(/KS:\s*([0-9]+)/i);
     const ssMatch = text.match(/SS:\s*([0-9]+)/i);
     const msgMatch = text.match(/(?:Zpráva pro příjemce|Message):\s*(.*)/i);
     const nameMatch = text.match(/(?:Název protiúčtu|Account Name):\s*(.*)/i);
-    const idMatch = text.match(/(?:ID pokynu|Transaction ID):\s*([0-9]+)/i);
+    const commandMatch = text.match(/ID pokynu:\s*([0-9]+)/i);
+    const idMatch = text.match(/ID pohybu:\s*([0-9]+)/i);
     const dateMatch = text.match(
       /Datum(?:\s+pohybu|\s+provedení|\s+zaúčtování)?:\s*(\d{2}\.\d{2}\.\d{4}(?:\s+\d{2}:\d{2}(?::\d{2})?(?:\s*[+-]\d{2}:?\d{2})?)?)/i
     );
@@ -236,11 +245,16 @@ function parseEmail(text, provider) {
       transaction_type: null,
       performed_by: null,
       comment: null,
-      command_id: null,
+      payer_reference: null,
+      raw_vs: vsMatch ? vsMatch[1] ?? null : null,
+      direction: amount_cents > 0 ? "incoming" : amount_cents < 0 ? "outgoing" : "zero",
+      identity_kind: "observation",
+      identity_provenance: "authenticated_email_unverified_movement",
+      command_id: commandMatch ? commandMatch[1] ?? null : null,
       source: "email",
       date,
       date_offset_min,
-      transaction_id: idMatch ? idMatch[1] ?? null : null,
+      transaction_id: null,
       external_id: null
     };
   }
@@ -253,8 +267,7 @@ function parseEmail(text, provider) {
     if (!amountStr) return null;
     const amount = parseAmount(amountField.rawAmount);
     if (isNaN(amount)) return null;
-    if (amount < 0) return null;
-    const amount_cents = toCents(amount, currency);
+    const amount_cents = decimalToCents(amountField.rawAmount, currency);
     const counterparty = parseAirbankCounterparty(text);
     const vsMatch = text.match(/(?:Variabilní symbol|\bVS\b)\s*:\s*([0-9]+)/i);
     const ksMatch = text.match(/(?:Konstantní symbol|\bKS\b)\s*:\s*([0-9]+)/i);
@@ -290,6 +303,11 @@ function parseEmail(text, provider) {
       transaction_type: null,
       performed_by: null,
       comment: null,
+      payer_reference: null,
+      raw_vs: vsMatch ? vsMatch[1] ?? null : null,
+      direction: amount_cents > 0 ? "incoming" : amount_cents < 0 ? "outgoing" : "zero",
+      identity_kind: "observation",
+      identity_provenance: "authenticated_email_unverified_movement",
       command_id: null,
       source: "email",
       date,
@@ -400,12 +418,17 @@ function concatBytes(...parts) {
   return out;
 }
 function buildWebhookEnvelope(args) {
+  const keys = ["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"];
+  if (args.event_version === "2") keys.push("payer_reference", "raw_vs", "direction", "identity_kind", "identity_provenance");
+  const data = Object.fromEntries(keys.map((key) => [key, args.transaction[key]]));
+  if (args.event_version !== "2") data.vs = resolveVariableSymbol(args.transaction);
+  if (args.event_version !== "2" && data.amount_cents <= 0) throw new Error("v1_incoming_only");
   return {
     event: "transaction.received",
-    event_version: "1",
+    event_version: args.event_version ?? "1",
     delivery_id: args.delivery_id,
     pairing_code: args.pairing_code,
-    data: args.transaction
+    data
   };
 }
 async function signWebhook(args) {
@@ -452,7 +475,7 @@ function isNullableString(value) {
 function isPositiveSafeInteger(value) {
   return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }
-function isTransaction(value) {
+function isTransaction(value, version) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const data = value;
   const nullableStrings = [
@@ -472,7 +495,8 @@ function isTransaction(value) {
     "transaction_id",
     "external_id"
   ];
-  return isPositiveSafeInteger(data.id) && isPositiveSafeInteger(data.bank_account_id) && isPositiveSafeInteger(data.amount_cents) && typeof data.currency === "string" && /^[A-Z]{3}$/.test(data.currency) && nullableStrings.every((field) => isNullableString(data[field])) && (data.source === "email" || data.source === "fio_api") && typeof data.date === "string" && data.date.length > 0 && (data.date_offset_min === null || typeof data.date_offset_min === "number" && Number.isSafeInteger(data.date_offset_min));
+  const v2Valid = version === "1" || ["CZK", "EUR", "USD"].includes(String(data.currency)) && typeof data.date === "string" && /^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/.test(data.date) && Number.isFinite(Date.parse(data.date)) && isNullableString(data.raw_vs) && isNullableString(data.payer_reference) && data.direction === (data.amount_cents > 0 ? "incoming" : data.amount_cents < 0 ? "outgoing" : "zero") && ["movement", "observation", "historical_unverified"].includes(String(data.identity_kind)) && typeof data.identity_provenance === "string" && data.identity_provenance.length > 0 && (data.identity_kind !== "movement" || typeof data.transaction_id === "string" && data.transaction_id.length > 0 && data.identity_provenance === "fio_api_column22" && data.source === "fio_api");
+  return v2Valid && isPositiveSafeInteger(data.id) && isPositiveSafeInteger(data.bank_account_id) && (version === "1" ? isPositiveSafeInteger(data.amount_cents) : typeof data.amount_cents === "number" && Number.isSafeInteger(data.amount_cents)) && typeof data.currency === "string" && /^[A-Z]{3}$/.test(data.currency) && nullableStrings.every((field) => isNullableString(data[field])) && (data.source === "email" || data.source === "fio_api") && typeof data.date === "string" && data.date.length > 0 && (data.date_offset_min === null || typeof data.date_offset_min === "number" && Number.isSafeInteger(data.date_offset_min));
 }
 async function verifyWebhook(args) {
   if (!/^\d{10}$/.test(args.timestamp)) throw new WebhookVerificationError("timestamp_invalid");
@@ -527,8 +551,8 @@ async function verifyWebhook(args) {
     throw new WebhookVerificationError("body_invalid");
   }
   if (value.event !== "transaction.received") throw new WebhookVerificationError("event_unsupported");
-  if (value.event_version !== "1") throw new WebhookVerificationError("event_version_unsupported");
-  if (typeof value.pairing_code !== "string" || !/^[0-9a-f]{10}$/i.test(value.pairing_code) || !isTransaction(value.data)) {
+  if (value.event_version !== (args.eventVersion ?? "1")) throw new WebhookVerificationError("event_version_unsupported");
+  if (typeof value.pairing_code !== "string" || !/^[0-9a-f]{10}$/i.test(value.pairing_code) || !isTransaction(value.data, args.eventVersion ?? "1")) {
     throw new WebhookVerificationError("body_invalid");
   }
   return envelope;
@@ -561,15 +585,16 @@ var FioTransientFailure = class extends FioApiError {
 function endpoint(path, token) {
   return `${FIO_BASE}/${path}/${encodeURIComponent(token)}`;
 }
-async function fioRequest(op, token, directUrl, proxy, date) {
+async function fioRequest(op, token, directUrl, proxy, date, toDate) {
   if (proxy?.url && proxy.secret) {
     return fetch(proxy.url, {
       method: "POST",
       headers: { "content-type": "application/json", "x-fio-proxy-secret": proxy.secret },
-      body: JSON.stringify(date === void 0 ? { op, token } : { op, token, date })
+      body: JSON.stringify(date === void 0 ? { op, token } : { op, token, date, ...toDate ? { toDate } : {} }),
+      signal: AbortSignal.timeout(2e4)
     });
   }
-  return fetch(directUrl);
+  return fetch(directUrl, { signal: AbortSignal.timeout(2e4) });
 }
 function retryAfterSeconds(headers) {
   const raw = headers.get("Retry-After");
@@ -578,7 +603,7 @@ function retryAfterSeconds(headers) {
   return Number.isFinite(n) && n >= 0 ? n : null;
 }
 async function ensureFioResponse(res) {
-  if (res.status === 429) {
+  if (res.status === 429 || res.status === 409) {
     throw new FioRateLimited(res.status, retryAfterSeconds(res.headers));
   }
   if (res.status >= 500) {
@@ -605,14 +630,10 @@ async function setFioPointer(token, yyyyMmDd, proxy) {
 function column(raw, idx) {
   const value = raw[`column${idx}`]?.value;
   if (value === null || value === void 0) return null;
+  if (typeof value === "number" && (idx === 22 || idx === 17) && !Number.isSafeInteger(value)) throw new Error("unsafe_fio_identity");
   const s = String(value).trim();
   return s.length > 0 ? s : null;
 }
-function parseAmount2(raw) {
-  if (raw === null) return 0;
-  const normalized = raw.replace(/\s/g, "").replace(",", ".");
-  return Number.parseFloat(normalized);
-}
 function parseOffsetMinutes(raw) {
   const m = raw.match(/([+-])(\d{2}):?(\d{2})$/);
   if (!m) return null;
@@ -620,7 +641,7 @@ function parseOffsetMinutes(raw) {
   return sign * (Number.parseInt(m[2] ?? "0", 10) * 60 + Number.parseInt(m[3] ?? "0", 10));
 }
 function parseFioDate(raw) {
-  if (!raw) return { date: (/* @__PURE__ */ new Date()).toISOString(), date_offset_min: null };
+  if (!raw) throw new Error("missing_fio_date");
   const isoDateOnly = raw.match(/^(\d{4}-\d{2}-\d{2})(?:[+-]\d{2}:?\d{2})?$/);
   if (isoDateOnly) {
     return {
@@ -645,12 +666,17 @@ function parseFioDate(raw) {
   throw new Error(`invalid_fio_date: ${JSON.stringify(raw)}`);
 }
 function mapFioTransaction(raw) {
-  const amount = parseAmount2(column(raw, 1));
-  if (!(amount > 0)) return null;
+  const rawAmount = column(raw, 1);
+  if (rawAmount === null) throw new Error("missing_fio_amount");
   const currency = normalizeCurrency(column(raw, 14) ?? "");
   const { date, date_offset_min } = parseFioDate(column(raw, 0));
   return {
-    amount_cents: toCents(amount, currency),
+    amount_cents: decimalToCents(rawAmount, currency),
+    payer_reference: column(raw, 27),
+    raw_vs: column(raw, 5),
+    direction: decimalToCents(rawAmount, currency) > 0 ? "incoming" : decimalToCents(rawAmount, currency) < 0 ? "outgoing" : "zero",
+    identity_kind: column(raw, 22) ? "movement" : "observation",
+    identity_provenance: "fio_api_column22",
     currency,
     counter_account: column(raw, 2),
     bank_code: column(raw, 3),
@@ -672,10 +698,22 @@ function mapFioTransaction(raw) {
     external_id: null
   };
 }
+async function fetchFioStatement(token, from, to, proxy) {
+  for (const date of [from, to]) if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || !Number.isFinite(Date.parse(date))) throw new Error("invalid_statement_window");
+  if (from > to || Date.parse(to) - Date.parse(from) > 90 * 864e5) throw new Error("unbounded_statement_window");
+  const response = await fioRequest("periods", token, `${endpoint("periods", token)}/${from}/${to}/transactions.json`, proxy, from, to);
+  await ensureFioResponse(response);
+  const document = await response.json();
+  const statement = document.accountStatement;
+  if (!statement?.info) throw new Error("missing_statement_info");
+  const rows = statement.transactionList?.transaction ?? [];
+  return { info: statement.info, transactions: Array.isArray(rows) ? rows : [rows] };
+}
 
 export {
   normalizeCurrency,
   toCents,
+  decimalToCents,
   BANK_CODES,
   detectProvider,
   parseEmail,
@@ -692,5 +730,6 @@ export {
   FioTransientFailure,
   fetchNewTransactions,
   setFioPointer,
-  mapFioTransaction
+  mapFioTransaction,
+  fetchFioStatement
 };

package/dist/{chunk-PBN2BUNR.cjs → chunk-N7BVOSFN.cjs}

@@ -28,6 +28,15 @@ function toCents(amount, currency) {
   }
   return Math.round(amount * 10 ** dec);
 }
+function decimalToCents(raw, currency) {
+  if (MINOR_UNIT_DECIMALS[currency] !== 2) throw new Error("unsupported_currency_minor_unit");
+  const normalized = raw.replace(/\s/g, "").replace(",", ".");
+  const match = /^([+-]?)(\d+)(?:\.(\d{1,2}))?$/.exec(normalized);
+  if (!match) throw new Error("invalid_exact_amount");
+  const cents = (BigInt(match[2]) * 100n + BigInt((_nullishCoalesce(match[3], () => ( ""))).padEnd(2, "0"))) * (match[1] === "-" ? -1n : 1n);
+  if (cents > BigInt(Number.MAX_SAFE_INTEGER) || cents < BigInt(Number.MIN_SAFE_INTEGER)) throw new Error("amount_out_of_range");
+  return Number(cents);
+}
 
 // src/parser.ts
 var BANK_CODES = {
@@ -200,15 +209,15 @@ function parseEmail(text, provider) {
     const currency = normalizeCurrency(rawCurrencyStr);
     const amount = parseAmount(amountField.rawAmount);
     if (isNaN(amount)) return null;
-    if (amount < 0) return null;
-    const amount_cents = toCents(amount, currency);
+    const amount_cents = decimalToCents(amountField.rawAmount, currency);
     const accountMatch = text.match(/(?:Protiúčet|Protiucet|Account):\s*([0-9\/\s]+)/i);
     const vsMatch = text.match(/VS:\s*([0-9]+)/i);
     const ksMatch = text.match(/KS:\s*([0-9]+)/i);
     const ssMatch = text.match(/SS:\s*([0-9]+)/i);
     const msgMatch = text.match(/(?:Zpráva pro příjemce|Message):\s*(.*)/i);
     const nameMatch = text.match(/(?:Název protiúčtu|Account Name):\s*(.*)/i);
-    const idMatch = text.match(/(?:ID pokynu|Transaction ID):\s*([0-9]+)/i);
+    const commandMatch = text.match(/ID pokynu:\s*([0-9]+)/i);
+    const idMatch = text.match(/ID pohybu:\s*([0-9]+)/i);
     const dateMatch = text.match(
       /Datum(?:\s+pohybu|\s+provedení|\s+zaúčtování)?:\s*(\d{2}\.\d{2}\.\d{4}(?:\s+\d{2}:\d{2}(?::\d{2})?(?:\s*[+-]\d{2}:?\d{2})?)?)/i
     );
@@ -236,11 +245,16 @@ function parseEmail(text, provider) {
       transaction_type: null,
       performed_by: null,
       comment: null,
-      command_id: null,
+      payer_reference: null,
+      raw_vs: vsMatch ? _nullishCoalesce(vsMatch[1], () => ( null)) : null,
+      direction: amount_cents > 0 ? "incoming" : amount_cents < 0 ? "outgoing" : "zero",
+      identity_kind: "observation",
+      identity_provenance: "authenticated_email_unverified_movement",
+      command_id: commandMatch ? _nullishCoalesce(commandMatch[1], () => ( null)) : null,
       source: "email",
       date,
       date_offset_min,
-      transaction_id: idMatch ? _nullishCoalesce(idMatch[1], () => ( null)) : null,
+      transaction_id: null,
       external_id: null
     };
   }
@@ -253,8 +267,7 @@ function parseEmail(text, provider) {
     if (!amountStr) return null;
     const amount = parseAmount(amountField.rawAmount);
     if (isNaN(amount)) return null;
-    if (amount < 0) return null;
-    const amount_cents = toCents(amount, currency);
+    const amount_cents = decimalToCents(amountField.rawAmount, currency);
     const counterparty = parseAirbankCounterparty(text);
     const vsMatch = text.match(/(?:Variabilní symbol|\bVS\b)\s*:\s*([0-9]+)/i);
     const ksMatch = text.match(/(?:Konstantní symbol|\bKS\b)\s*:\s*([0-9]+)/i);
@@ -290,6 +303,11 @@ function parseEmail(text, provider) {
       transaction_type: null,
       performed_by: null,
       comment: null,
+      payer_reference: null,
+      raw_vs: vsMatch ? _nullishCoalesce(vsMatch[1], () => ( null)) : null,
+      direction: amount_cents > 0 ? "incoming" : amount_cents < 0 ? "outgoing" : "zero",
+      identity_kind: "observation",
+      identity_provenance: "authenticated_email_unverified_movement",
       command_id: null,
       source: "email",
       date,
@@ -400,12 +418,17 @@ function concatBytes(...parts) {
   return out;
 }
 function buildWebhookEnvelope(args) {
+  const keys = ["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"];
+  if (args.event_version === "2") keys.push("payer_reference", "raw_vs", "direction", "identity_kind", "identity_provenance");
+  const data = Object.fromEntries(keys.map((key) => [key, args.transaction[key]]));
+  if (args.event_version !== "2") data.vs = resolveVariableSymbol(args.transaction);
+  if (args.event_version !== "2" && data.amount_cents <= 0) throw new Error("v1_incoming_only");
   return {
     event: "transaction.received",
-    event_version: "1",
+    event_version: _nullishCoalesce(args.event_version, () => ( "1")),
     delivery_id: args.delivery_id,
     pairing_code: args.pairing_code,
-    data: args.transaction
+    data
   };
 }
 async function signWebhook(args) {
@@ -452,7 +475,7 @@ function isNullableString(value) {
 function isPositiveSafeInteger(value) {
   return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }
-function isTransaction(value) {
+function isTransaction(value, version) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const data = value;
   const nullableStrings = [
@@ -472,7 +495,8 @@ function isTransaction(value) {
     "transaction_id",
     "external_id"
   ];
-  return isPositiveSafeInteger(data.id) && isPositiveSafeInteger(data.bank_account_id) && isPositiveSafeInteger(data.amount_cents) && typeof data.currency === "string" && /^[A-Z]{3}$/.test(data.currency) && nullableStrings.every((field) => isNullableString(data[field])) && (data.source === "email" || data.source === "fio_api") && typeof data.date === "string" && data.date.length > 0 && (data.date_offset_min === null || typeof data.date_offset_min === "number" && Number.isSafeInteger(data.date_offset_min));
+  const v2Valid = version === "1" || ["CZK", "EUR", "USD"].includes(String(data.currency)) && typeof data.date === "string" && /^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/.test(data.date) && Number.isFinite(Date.parse(data.date)) && isNullableString(data.raw_vs) && isNullableString(data.payer_reference) && data.direction === (data.amount_cents > 0 ? "incoming" : data.amount_cents < 0 ? "outgoing" : "zero") && ["movement", "observation", "historical_unverified"].includes(String(data.identity_kind)) && typeof data.identity_provenance === "string" && data.identity_provenance.length > 0 && (data.identity_kind !== "movement" || typeof data.transaction_id === "string" && data.transaction_id.length > 0 && data.identity_provenance === "fio_api_column22" && data.source === "fio_api");
+  return v2Valid && isPositiveSafeInteger(data.id) && isPositiveSafeInteger(data.bank_account_id) && (version === "1" ? isPositiveSafeInteger(data.amount_cents) : typeof data.amount_cents === "number" && Number.isSafeInteger(data.amount_cents)) && typeof data.currency === "string" && /^[A-Z]{3}$/.test(data.currency) && nullableStrings.every((field) => isNullableString(data[field])) && (data.source === "email" || data.source === "fio_api") && typeof data.date === "string" && data.date.length > 0 && (data.date_offset_min === null || typeof data.date_offset_min === "number" && Number.isSafeInteger(data.date_offset_min));
 }
 async function verifyWebhook(args) {
   if (!/^\d{10}$/.test(args.timestamp)) throw new WebhookVerificationError("timestamp_invalid");
@@ -527,8 +551,8 @@ async function verifyWebhook(args) {
     throw new WebhookVerificationError("body_invalid");
   }
   if (value.event !== "transaction.received") throw new WebhookVerificationError("event_unsupported");
-  if (value.event_version !== "1") throw new WebhookVerificationError("event_version_unsupported");
-  if (typeof value.pairing_code !== "string" || !/^[0-9a-f]{10}$/i.test(value.pairing_code) || !isTransaction(value.data)) {
+  if (value.event_version !== (_nullishCoalesce(args.eventVersion, () => ( "1")))) throw new WebhookVerificationError("event_version_unsupported");
+  if (typeof value.pairing_code !== "string" || !/^[0-9a-f]{10}$/i.test(value.pairing_code) || !isTransaction(value.data, _nullishCoalesce(args.eventVersion, () => ( "1")))) {
     throw new WebhookVerificationError("body_invalid");
   }
   return envelope;
@@ -561,15 +585,16 @@ var FioTransientFailure = class extends FioApiError {
 function endpoint(path, token) {
   return `${FIO_BASE}/${path}/${encodeURIComponent(token)}`;
 }
-async function fioRequest(op, token, directUrl, proxy, date) {
+async function fioRequest(op, token, directUrl, proxy, date, toDate) {
   if (_optionalChain([proxy, 'optionalAccess', _3 => _3.url]) && proxy.secret) {
     return fetch(proxy.url, {
       method: "POST",
       headers: { "content-type": "application/json", "x-fio-proxy-secret": proxy.secret },
-      body: JSON.stringify(date === void 0 ? { op, token } : { op, token, date })
+      body: JSON.stringify(date === void 0 ? { op, token } : { op, token, date, ...toDate ? { toDate } : {} }),
+      signal: AbortSignal.timeout(2e4)
     });
   }
-  return fetch(directUrl);
+  return fetch(directUrl, { signal: AbortSignal.timeout(2e4) });
 }
 function retryAfterSeconds(headers) {
   const raw = headers.get("Retry-After");
@@ -578,7 +603,7 @@ function retryAfterSeconds(headers) {
   return Number.isFinite(n) && n >= 0 ? n : null;
 }
 async function ensureFioResponse(res) {
-  if (res.status === 429) {
+  if (res.status === 429 || res.status === 409) {
     throw new FioRateLimited(res.status, retryAfterSeconds(res.headers));
   }
   if (res.status >= 500) {
@@ -605,14 +630,10 @@ async function setFioPointer(token, yyyyMmDd, proxy) {
 function column(raw, idx) {
   const value = _optionalChain([raw, 'access', _7 => _7[`column${idx}`], 'optionalAccess', _8 => _8.value]);
   if (value === null || value === void 0) return null;
+  if (typeof value === "number" && (idx === 22 || idx === 17) && !Number.isSafeInteger(value)) throw new Error("unsafe_fio_identity");
   const s = String(value).trim();
   return s.length > 0 ? s : null;
 }
-function parseAmount2(raw) {
-  if (raw === null) return 0;
-  const normalized = raw.replace(/\s/g, "").replace(",", ".");
-  return Number.parseFloat(normalized);
-}
 function parseOffsetMinutes(raw) {
   const m = raw.match(/([+-])(\d{2}):?(\d{2})$/);
   if (!m) return null;
@@ -620,7 +641,7 @@ function parseOffsetMinutes(raw) {
   return sign * (Number.parseInt(_nullishCoalesce(m[2], () => ( "0")), 10) * 60 + Number.parseInt(_nullishCoalesce(m[3], () => ( "0")), 10));
 }
 function parseFioDate(raw) {
-  if (!raw) return { date: (/* @__PURE__ */ new Date()).toISOString(), date_offset_min: null };
+  if (!raw) throw new Error("missing_fio_date");
   const isoDateOnly = raw.match(/^(\d{4}-\d{2}-\d{2})(?:[+-]\d{2}:?\d{2})?$/);
   if (isoDateOnly) {
     return {
@@ -645,12 +666,17 @@ function parseFioDate(raw) {
   throw new Error(`invalid_fio_date: ${JSON.stringify(raw)}`);
 }
 function mapFioTransaction(raw) {
-  const amount = parseAmount2(column(raw, 1));
-  if (!(amount > 0)) return null;
+  const rawAmount = column(raw, 1);
+  if (rawAmount === null) throw new Error("missing_fio_amount");
   const currency = normalizeCurrency(_nullishCoalesce(column(raw, 14), () => ( "")));
   const { date, date_offset_min } = parseFioDate(column(raw, 0));
   return {
-    amount_cents: toCents(amount, currency),
+    amount_cents: decimalToCents(rawAmount, currency),
+    payer_reference: column(raw, 27),
+    raw_vs: column(raw, 5),
+    direction: decimalToCents(rawAmount, currency) > 0 ? "incoming" : decimalToCents(rawAmount, currency) < 0 ? "outgoing" : "zero",
+    identity_kind: column(raw, 22) ? "movement" : "observation",
+    identity_provenance: "fio_api_column22",
     currency,
     counter_account: column(raw, 2),
     bank_code: column(raw, 3),
@@ -672,6 +698,19 @@ function mapFioTransaction(raw) {
     external_id: null
   };
 }
+async function fetchFioStatement(token, from, to, proxy) {
+  for (const date of [from, to]) if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || !Number.isFinite(Date.parse(date))) throw new Error("invalid_statement_window");
+  if (from > to || Date.parse(to) - Date.parse(from) > 90 * 864e5) throw new Error("unbounded_statement_window");
+  const response = await fioRequest("periods", token, `${endpoint("periods", token)}/${from}/${to}/transactions.json`, proxy, from, to);
+  await ensureFioResponse(response);
+  const document = await response.json();
+  const statement = document.accountStatement;
+  if (!_optionalChain([statement, 'optionalAccess', _9 => _9.info])) throw new Error("missing_statement_info");
+  const rows = _nullishCoalesce(_optionalChain([statement, 'access', _10 => _10.transactionList, 'optionalAccess', _11 => _11.transaction]), () => ( []));
+  return { info: statement.info, transactions: Array.isArray(rows) ? rows : [rows] };
+}
+
+
 
 
 
@@ -693,4 +732,4 @@ function mapFioTransaction(raw) {
 
 
 
-exports.normalizeCurrency = normalizeCurrency; exports.toCents = toCents; exports.BANK_CODES = BANK_CODES; exports.detectProvider = detectProvider; exports.parseEmail = parseEmail; exports.encodeRf = encodeRf; exports.decodeRf = decodeRf; exports.resolveVariableSymbol = resolveVariableSymbol; exports.extractReferenceCandidates = extractReferenceCandidates; exports.buildWebhookEnvelope = buildWebhookEnvelope; exports.signWebhook = signWebhook; exports.WebhookVerificationError = WebhookVerificationError; exports.verifyWebhook = verifyWebhook; exports.FioApiError = FioApiError; exports.FioRateLimited = FioRateLimited; exports.FioTransientFailure = FioTransientFailure; exports.fetchNewTransactions = fetchNewTransactions; exports.setFioPointer = setFioPointer; exports.mapFioTransaction = mapFioTransaction;
+exports.normalizeCurrency = normalizeCurrency; exports.toCents = toCents; exports.decimalToCents = decimalToCents; exports.BANK_CODES = BANK_CODES; exports.detectProvider = detectProvider; exports.parseEmail = parseEmail; exports.encodeRf = encodeRf; exports.decodeRf = decodeRf; exports.resolveVariableSymbol = resolveVariableSymbol; exports.extractReferenceCandidates = extractReferenceCandidates; exports.buildWebhookEnvelope = buildWebhookEnvelope; exports.signWebhook = signWebhook; exports.WebhookVerificationError = WebhookVerificationError; exports.verifyWebhook = verifyWebhook; exports.FioApiError = FioApiError; exports.FioRateLimited = FioRateLimited; exports.FioTransientFailure = FioTransientFailure; exports.fetchNewTransactions = fetchNewTransactions; exports.setFioPointer = setFioPointer; exports.mapFioTransaction = mapFioTransaction; exports.fetchFioStatement = fetchFioStatement;