@classytic/primitives 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,96 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-05-05
+
+### Added — `/bank-transaction` subpath
+
+Canonical bank-feed shapes shared across `@classytic/fin-io` (parsers
+produce these), `@classytic/revenue` (`transactionRepository.import()`
+consumes them), and `@classytic/ledger` (`bankStatementMapper`
+consumes them). Single source of truth for the cross-package
+vocabulary; eliminates the structural mirrors fin-io and revenue
+were carrying.
+
+Exports: `BankTransaction`, `BankCounterparty`, `BankAccount`,
+`BankStatement`, `BankStatementSource`, `BankImportReport`,
+`BankImportRowError`. All anchored on `Money` from `/money` (integer
+minor units, `number`).
+
+### Added — `/payment-gateway` subpath
+
+Canonical payment-gateway data shapes. **Lets any provider package
+(Stripe, Razorpay, SSLCommerz, PayPal, bKash, Nagad, manual, …)
+implement against primitives' types without depending on revenue's
+heavyweight runtime.** Provider authors peer-dep on
+`@classytic/primitives` only.
+
+Exports: `CreateIntentParams`, `PaymentIntent`, `PaymentResult`,
+`RefundResult`, `WebhookEvent`, `ProviderCapabilities`. All `amount`
+fields are `Money` from `/money` (no flat `amount: number, currency:
+string` pairs — currency travels inside Money).
+
+The `PaymentProvider` abstract class — the *contract* every provider
+must satisfy — stays in `@classytic/revenue`. Revenue is the data
+engine that consumes providers; provider packages live elsewhere.
+
+### Architectural intent
+
+Revenue 3.0 + primitives 0.5 + fin-io 0.3 establish a clean
+three-tier seam:
+
+  1. **primitives** — pure data shapes (no runtime, no deps). Owns
+     `Money`, `BankTransaction`, `PaymentIntent`, every cross-
+     package vocabulary type.
+  2. **revenue** — the engine. Owns the abstract contracts
+     (`PaymentProvider`, `BankFeedProvider`), state machines, repos.
+     Consumes primitives shapes.
+  3. **provider packages** (`revenue-stripe`, `revenue-razorpay`,
+     `@classytic/fin-io/adapters/revenue`, …) — implementations.
+     Peer-dep on primitives. Optional peer-dep on revenue for the
+     abstract base class.
+
+This eliminates the cycle where every provider package transitively
+pulled mongoose + mongokit just to know what a `PaymentIntent`
+looked like. Tree-shaking, build times, and dep-graph honesty all
+improve.
+
+### Migration
+
+Consumers MUST import from primitives subpaths. No re-exports from
+revenue or fin-io (PACKAGE_RULES P2):
+
+```ts
+// Before
+import type { PaymentIntent, CreateIntentParams } from '@classytic/revenue';
+import type { CanonicalTransaction, Money } from '@classytic/fin-io';
+
+// After
+import type {
+  PaymentIntent,
+  CreateIntentParams,
+} from '@classytic/primitives/payment-gateway';
+import type { BankTransaction } from '@classytic/primitives/bank-transaction';
+import type { Money } from '@classytic/primitives/money';
+```
+
+Provider helper classes (`PaymentIntent`, `PaymentResult`,
+`RefundResult`, `WebhookEvent`) are deleted from revenue — they were
+trivial wrappers around plain objects. Provider implementations now
+return plain object literals matching the interface.
+
+`CreateIntentParams.amount` is now `Money` (`{ amount: number,
+currency: string }`), not the flat `amount + currency` pair. Revenue's
+repository wraps internally:
+
+```ts
+const intent = await provider.createIntent({
+  amount: { amount: params.amount, currency },
+  metadata: params.metadata,
+  ...params.paymentData,
+});
+```
+
 ## [0.3.1] - 2026-05-02
 
 ### Added — state-machine ↔ mongokit/sqlitekit integration

package/dist/bank-transaction.d.mts

@@ -0,0 +1,167 @@
+import { Money } from "./money.mjs";
+
+//#region src/bank-transaction.d.ts
+/**
+ * The other side of a bank transaction. All fields optional — different
+ * formats populate different subsets:
+ *   OFX     usually carries `name` only.
+ *   CAMT    carries IBAN + BIC + name (SEPA structured data).
+ *   Plaid   carries `merchant_name` mapped to `name`.
+ *   CSV     varies; usually `name` + maybe `accountNumber`.
+ */
+interface BankCounterparty {
+  /** Free-text name as the bank emits it. */
+  name?: string;
+  /**
+   * Vendor-stable identifier — bank's own customer ID, structured
+   * remittance reference (ISO 11649), etc. Distinct from the
+   * transaction-level `reference`.
+   */
+  identifier?: string;
+  /** International Bank Account Number (SEPA / EU). */
+  iban?: string;
+  /** Domestic account number. */
+  accountNumber?: string;
+  /** Bank / SWIFT BIC. */
+  bic?: string;
+  /** US ABA routing / Canadian transit. */
+  routingNumber?: string;
+}
+/**
+ * Identifies the account a statement / sync batch is for. Different
+ * formats populate different subsets — consumers should treat every
+ * field except `currency` as best-effort.
+ */
+interface BankAccount {
+  iban?: string;
+  accountNumber?: string;
+  /** US ABA / SWIFT BIC / domestic bank code. Generic — format-specific. */
+  bankCode?: string;
+  /** Human-readable bank name. */
+  bankName?: string;
+  /** Account holder name as the bank emits it. */
+  ownerName?: string;
+  /** Type as the bank classifies it: `'CHECKING'`, `'SAVINGS'`, `'CREDITLINE'`. */
+  accountType?: string;
+  /**
+   * ISO 4217 of the account itself. REQUIRED — synthesized from format
+   * defaults if absent (parsers MUST fill this in).
+   */
+  currency: string;
+}
+/**
+ * One row from a bank statement / accounting feed sync.
+ *
+ * `externalId` is REQUIRED — without it idempotent re-import is broken.
+ * Synthesize one from `(date | amount | description hash)` if the
+ * upstream format lacks a vendor-stable id.
+ */
+interface BankTransaction {
+  /**
+   * Vendor-stable unique identifier. REQUIRED.
+   *
+   *   OFX:    `<FITID>` from the source file.
+   *   CAMT:   `<NtryRef>` or `<AcctSvcrRef>`.
+   *   QBO:    `Id` from the QBO API.
+   *   Plaid:  `transaction_id`.
+   *   CSV:    synthesized as `sha256(date|amount|description)` truncated
+   *           to 16 hex chars; parser should emit a warning.
+   *
+   * Used by consumers to enforce idempotent re-import via
+   * `(orgId, bankAccountId, externalId)` partial-unique indexes.
+   * Distinct from any host-chosen request-scoped idempotency key.
+   */
+  externalId: string;
+  /** When the bank booked the entry. */
+  postedDate: Date;
+  /** When funds become available (cleared). May equal `postedDate`. */
+  valueDate?: Date;
+  /**
+   * Signed amount in integer minor units. Positive = inflow to the
+   * account holder, negative = outflow. Currency carried inside `Money`.
+   */
+  amount: Money;
+  /** Free-text description as the bank emitted it. */
+  description: string;
+  /** Counterparty (payer / payee) when the format provides one. */
+  counterparty?: BankCounterparty;
+  /** Bank-provided reference number, check number, end-to-end id. */
+  reference?: string;
+  /**
+   * Bank-provided category if any. Rare in OFX / CAMT, common in
+   * Plaid and consumer-finance CSV (Mint / YNAB).
+   */
+  category?: string;
+  /** Running balance on the account after this entry, if available. */
+  balanceAfter?: Money;
+  /** Format-specific entry-type code (`'DEBIT'`, `'CREDIT'`, `'CHECK'`, …). */
+  type?: string;
+  /**
+   * Format-specific raw record. Pass-through for audit / debugging.
+   * Consumers MUST NOT rely on this — schema may change between fin-io
+   * minor versions. Discard before persistence if size is a concern.
+   */
+  raw?: unknown;
+}
+/**
+ * Aggregate envelope produced by file-format parsers (OFX, CAMT.053,
+ * MT940, CSV, IIF). Sync providers (Plaid CDC, QBO CDC) emit
+ * `BankTransaction[]` directly without the statement wrapper because
+ * sync is continuous, not statement-scoped.
+ */
+interface BankStatement {
+  account: BankAccount;
+  /** Statement period the parser observed. */
+  period: {
+    from: Date;
+    to: Date;
+  };
+  /** Opening balance at `period.from`. */
+  openingBalance: Money;
+  /** Closing balance at `period.to`. */
+  closingBalance: Money;
+  /**
+   * Available balance at statement end (may differ from
+   * `closingBalance` for pending-but-not-cleared items).
+   */
+  availableBalance?: Money;
+  transactions: BankTransaction[];
+  /** Provenance metadata — which format produced this statement. */
+  source: BankStatementSource;
+}
+interface BankStatementSource {
+  /**
+   * Format the statement was parsed from. The set is closed —
+   * consumers can switch on it exhaustively. Add new variants here
+   * (and bump the package minor version) when adding a new parser.
+   */
+  format: 'ofx' | 'qfx' | 'camt053' | 'mt940' | 'csv' | 'iif' | 'xero-csv' | 'plaid' | 'qbo';
+  /** Format version — `'OFX 2.1.1'`, `'CAMT.053.001.08'`, etc. */
+  version?: string;
+  /** When the file was generated by the bank, if present. */
+  generatedAt?: Date;
+  /** Bank / vendor software fingerprint (e.g. OFX FI ORG). */
+  softwareId?: string;
+}
+/**
+ * Per-row failure during a bulk import. Consumers (revenue's `import()`)
+ * collect these without aborting the batch.
+ */
+interface BankImportRowError {
+  externalId: string;
+  reason: string;
+  row?: BankTransaction;
+}
+/**
+ * Outcome of a bulk import. Same shape ledger's `wireImport` reports
+ * for symmetry.
+ */
+interface BankImportReport {
+  inserted: number;
+  updated: number;
+  skipped: number;
+  errors: BankImportRowError[];
+  durationMs: number;
+}
+//#endregion
+export { BankAccount, BankCounterparty, BankImportReport, BankImportRowError, BankStatement, BankStatementSource, BankTransaction };

package/dist/bank-transaction.mjs

@@ -0,0 +1 @@
+export {};

package/dist/currency-rgUAn5KM.d.mts

@@ -0,0 +1,110 @@
+import { t as Brand } from "./brand-DApaegoR.mjs";
+
+//#region src/currency.d.ts
+/**
+ * ISO 4217 currency code (3 uppercase letters).
+ *
+ * Branded `string` — any 3-letter string is structurally valid, but the brand
+ * prevents accidental mixing with raw strings. Use {@link toCurrencyCode} to
+ * construct one safely.
+ */
+type CurrencyCode = Brand<string, 'CurrencyCode'>;
+/**
+ * Common ISO 4217 codes. Non-exhaustive — add more at the consumer level if
+ * needed. Listed here because shared-types ships with these by default.
+ */
+declare const CURRENCIES: {
+  readonly USD: "USD";
+  readonly EUR: "EUR";
+  readonly GBP: "GBP";
+  readonly JPY: "JPY";
+  readonly CNY: "CNY";
+  readonly INR: "INR";
+  readonly BDT: "BDT";
+  readonly AED: "AED";
+  readonly SAR: "SAR";
+  readonly PKR: "PKR";
+  readonly NPR: "NPR";
+  readonly LKR: "LKR";
+  readonly MYR: "MYR";
+  readonly SGD: "SGD";
+  readonly AUD: "AUD";
+  readonly CAD: "CAD";
+  readonly CHF: "CHF";
+  readonly HKD: "HKD";
+  readonly THB: "THB";
+  readonly IDR: "IDR";
+};
+/**
+ * Number of minor units per major unit for common currencies.
+ *
+ * ISO 4217 defines most currencies with 2 decimal places (cents). A few are
+ * zero-decimal (JPY, KRW) or three-decimal (BHD, KWD, JOD). When a currency
+ * isn't in this table, {@link minorUnitFactor} returns 100 as the safe default.
+ */
+declare const MINOR_UNIT_FACTOR: Readonly<Record<string, number>>;
+/**
+ * Narrow a raw string to a {@link CurrencyCode}. Returns `null` if the string
+ * is not a valid ISO 4217 format (3 uppercase letters). This does not verify
+ * the code is registered with ISO — use your own whitelist for that.
+ */
+declare function toCurrencyCode(value: string): CurrencyCode | null;
+/** Type predicate for `unknown` input. */
+declare function isCurrencyCode(value: unknown): value is CurrencyCode;
+/**
+ * Minor units per major unit (e.g. 100 for USD, 1 for JPY, 1000 for KWD).
+ * Falls back to 100 when the currency is unknown — matches the ISO 4217 default.
+ */
+declare function minorUnitFactor(currency: string): number;
+/**
+ * Frozen FX conversion record — the cost of record for cross-currency
+ * transactions. Stored alongside a base-currency amount at the seam where
+ * currency crossed (procurement receipt, landed-cost entry, foreign refund).
+ *
+ * Invariant: once written, never mutated. Revaluation is a new snapshot on
+ * a new document — rewriting an existing snapshot corrupts audit history.
+ *
+ * `rate` is expressed as: 1 sourceCurrency = rate * baseCurrency
+ * (e.g. USD→BDT at 110 means rate = 110, so sourceAmount 10 USD → baseAmount 1100 BDT).
+ * This matches how banks quote — the source is the "from" currency.
+ */
+interface FxSnapshot {
+  /** Currency the transaction was invoiced / quoted in. ISO 4217. */
+  sourceCurrency: string;
+  /** Organisation's functional currency the base amount is expressed in. */
+  baseCurrency: string;
+  /** 1 unit of sourceCurrency equals this many units of baseCurrency. */
+  rate: number;
+  /** When the rate was captured — NOT when the document was last touched. */
+  snapshotAt: Date;
+  /**
+   * Optional provenance tag — e.g. 'manual', 'bangladesh-bank',
+   * 'openexchangerates.org', 'supplier-invoice'. Free-form; hosts use it for
+   * audit filtering and re-pricing policy.
+   */
+  source?: string;
+}
+/**
+ * Apply an {@link FxSnapshot} to a source-currency amount. Returns the
+ * equivalent base-currency amount. No rounding — callers that persist into
+ * an integer minor-unit column must round explicitly with a deterministic
+ * rule (`Math.round`, banker's rounding, floor for duty-conservative
+ * postings, etc.).
+ */
+declare function convertWithSnapshot(sourceAmount: number, fx: FxSnapshot): number;
+/**
+ * Reverse an {@link FxSnapshot} — reconstruct the source-currency amount
+ * from a stored base amount. Useful for reporting "cost in original
+ * currency". Not round-trip safe under rounding; prefer storing the
+ * original source amount alongside the base amount when audit fidelity
+ * matters.
+ */
+declare function reverseWithSnapshot(baseAmount: number, fx: FxSnapshot): number;
+/**
+ * Structural validation — checks shape only. Does NOT verify the rate is
+ * economically sensible (8.5 USD→BDT would pass this check). Host-level
+ * guards / anomaly detection handle that.
+ */
+declare function isFxSnapshot(value: unknown): value is FxSnapshot;
+//#endregion
+export { convertWithSnapshot as a, minorUnitFactor as c, MINOR_UNIT_FACTOR as i, reverseWithSnapshot as l, CurrencyCode as n, isCurrencyCode as o, FxSnapshot as r, isFxSnapshot as s, CURRENCIES as t, toCurrencyCode as u };

package/dist/currency.d.mts

@@ -1,110 +1,2 @@
-import { t as Brand } from "./brand-DApaegoR.mjs";
-
-//#region src/currency.d.ts
-/**
- * ISO 4217 currency code (3 uppercase letters).
- *
- * Branded `string` — any 3-letter string is structurally valid, but the brand
- * prevents accidental mixing with raw strings. Use {@link toCurrencyCode} to
- * construct one safely.
- */
-type CurrencyCode = Brand<string, 'CurrencyCode'>;
-/**
- * Common ISO 4217 codes. Non-exhaustive — add more at the consumer level if
- * needed. Listed here because shared-types ships with these by default.
- */
-declare const CURRENCIES: {
-  readonly USD: "USD";
-  readonly EUR: "EUR";
-  readonly GBP: "GBP";
-  readonly JPY: "JPY";
-  readonly CNY: "CNY";
-  readonly INR: "INR";
-  readonly BDT: "BDT";
-  readonly AED: "AED";
-  readonly SAR: "SAR";
-  readonly PKR: "PKR";
-  readonly NPR: "NPR";
-  readonly LKR: "LKR";
-  readonly MYR: "MYR";
-  readonly SGD: "SGD";
-  readonly AUD: "AUD";
-  readonly CAD: "CAD";
-  readonly CHF: "CHF";
-  readonly HKD: "HKD";
-  readonly THB: "THB";
-  readonly IDR: "IDR";
-};
-/**
- * Number of minor units per major unit for common currencies.
- *
- * ISO 4217 defines most currencies with 2 decimal places (cents). A few are
- * zero-decimal (JPY, KRW) or three-decimal (BHD, KWD, JOD). When a currency
- * isn't in this table, {@link minorUnitFactor} returns 100 as the safe default.
- */
-declare const MINOR_UNIT_FACTOR: Readonly<Record<string, number>>;
-/**
- * Narrow a raw string to a {@link CurrencyCode}. Returns `null` if the string
- * is not a valid ISO 4217 format (3 uppercase letters). This does not verify
- * the code is registered with ISO — use your own whitelist for that.
- */
-declare function toCurrencyCode(value: string): CurrencyCode | null;
-/** Type predicate for `unknown` input. */
-declare function isCurrencyCode(value: unknown): value is CurrencyCode;
-/**
- * Minor units per major unit (e.g. 100 for USD, 1 for JPY, 1000 for KWD).
- * Falls back to 100 when the currency is unknown — matches the ISO 4217 default.
- */
-declare function minorUnitFactor(currency: string): number;
-/**
- * Frozen FX conversion record — the cost of record for cross-currency
- * transactions. Stored alongside a base-currency amount at the seam where
- * currency crossed (procurement receipt, landed-cost entry, foreign refund).
- *
- * Invariant: once written, never mutated. Revaluation is a new snapshot on
- * a new document — rewriting an existing snapshot corrupts audit history.
- *
- * `rate` is expressed as: 1 sourceCurrency = rate * baseCurrency
- * (e.g. USD→BDT at 110 means rate = 110, so sourceAmount 10 USD → baseAmount 1100 BDT).
- * This matches how banks quote — the source is the "from" currency.
- */
-interface FxSnapshot {
-  /** Currency the transaction was invoiced / quoted in. ISO 4217. */
-  sourceCurrency: string;
-  /** Organisation's functional currency the base amount is expressed in. */
-  baseCurrency: string;
-  /** 1 unit of sourceCurrency equals this many units of baseCurrency. */
-  rate: number;
-  /** When the rate was captured — NOT when the document was last touched. */
-  snapshotAt: Date;
-  /**
-   * Optional provenance tag — e.g. 'manual', 'bangladesh-bank',
-   * 'openexchangerates.org', 'supplier-invoice'. Free-form; hosts use it for
-   * audit filtering and re-pricing policy.
-   */
-  source?: string;
-}
-/**
- * Apply an {@link FxSnapshot} to a source-currency amount. Returns the
- * equivalent base-currency amount. No rounding — callers that persist into
- * an integer minor-unit column must round explicitly with a deterministic
- * rule (`Math.round`, banker's rounding, floor for duty-conservative
- * postings, etc.).
- */
-declare function convertWithSnapshot(sourceAmount: number, fx: FxSnapshot): number;
-/**
- * Reverse an {@link FxSnapshot} — reconstruct the source-currency amount
- * from a stored base amount. Useful for reporting "cost in original
- * currency". Not round-trip safe under rounding; prefer storing the
- * original source amount alongside the base amount when audit fidelity
- * matters.
- */
-declare function reverseWithSnapshot(baseAmount: number, fx: FxSnapshot): number;
-/**
- * Structural validation — checks shape only. Does NOT verify the rate is
- * economically sensible (8.5 USD→BDT would pass this check). Host-level
- * guards / anomaly detection handle that.
- */
-declare function isFxSnapshot(value: unknown): value is FxSnapshot;
-//#endregion
+import { a as convertWithSnapshot, c as minorUnitFactor, i as MINOR_UNIT_FACTOR, l as reverseWithSnapshot, n as CurrencyCode, o as isCurrencyCode, r as FxSnapshot, s as isFxSnapshot, t as CURRENCIES, u as toCurrencyCode } from "./currency-rgUAn5KM.mjs";
 export { CURRENCIES, CurrencyCode, FxSnapshot, MINOR_UNIT_FACTOR, convertWithSnapshot, isCurrencyCode, isFxSnapshot, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };

package/dist/money.d.mts

@@ -1,4 +1,4 @@
-import { CurrencyCode } from "./currency.mjs";
+import { n as CurrencyCode } from "./currency-rgUAn5KM.mjs";
 
 //#region src/money.d.ts
 /**

package/dist/payment-gateway.d.mts

@@ -0,0 +1,168 @@
+import { Money } from "./money.mjs";
+
+//#region src/payment-gateway.d.ts
+/**
+ * Static capability declaration — providers expose this so the engine
+ * can branch on what's supported (e.g. skip the refund button for
+ * cash providers, route 3DS-required cards to verification flows).
+ */
+interface ProviderCapabilities {
+  /** Provider exposes a webhook endpoint the host can register. */
+  supportsWebhooks: boolean;
+  /** Provider can reverse a captured charge. */
+  supportsRefunds: boolean;
+  /** Provider can refund less than the captured amount. */
+  supportsPartialRefunds: boolean;
+  /**
+   * Verification requires a human (admin marks "received") rather than
+   * an API call. True for cash, manual bank transfer, mobile-money
+   * outside an API window.
+   */
+  requiresManualVerification: boolean;
+}
+/**
+ * Arguments to `provider.createIntent(...)`. Engine constructs this
+ * from the host's checkout payload and the resolved currency. The
+ * `metadata` blob is opaque pass-through — providers MAY forward it to
+ * the upstream gateway (Stripe attaches it to the PaymentIntent), but
+ * MUST NOT mutate or interpret it.
+ */
+interface CreateIntentParams {
+  /** Amount + currency. Integer minor units; provider converts to its native shape. */
+  amount: Money;
+  /** Host-side customer id, if any. Forwarded to the gateway. */
+  customerId?: string;
+  /** Where the customer returns after off-site payment (Stripe Checkout, PayPal). */
+  returnUrl?: string;
+  /** Pass-through metadata. Visible on the gateway dashboard / webhook events. */
+  metadata?: Record<string, unknown>;
+  /**
+   * Provider-specific knobs. Each gateway documents its own keys —
+   * Stripe has `payment_method_types`, SSLCommerz has `tran_id`, bKash
+   * has `intent`, etc. Engine doesn't peek inside.
+   */
+  [key: string]: unknown;
+}
+/**
+ * What `provider.createIntent(...)` returns. The engine persists
+ * `id` / `paymentIntentId` / `sessionId` on the Transaction's
+ * `gateway` block so subsequent `verify` / webhook lookups can find
+ * the row.
+ */
+interface PaymentIntent {
+  /** Unique gateway-scoped id for this intent (`pi_xxx`, `ch_xxx`, etc.). */
+  id: string;
+  /** Lowercase gateway name (`'stripe'`, `'razorpay'`, `'sslcommerz'`, `'bkash'`, `'manual'`). */
+  provider: string;
+  /**
+   * Lifecycle status as the gateway reports it. Free-form string —
+   * engine maps known values to its own state machine. Common values:
+   * `'pending'`, `'processing'`, `'requires_action'`, `'succeeded'`,
+   * `'failed'`, `'cancelled'`.
+   */
+  status: string;
+  /** Amount + currency that the intent locks in. */
+  amount: Money;
+  /**
+   * Session token for hosted checkout flows (Stripe Checkout `session_id`,
+   * SSLCommerz `sessionkey`, bKash `paymentID`). When the gateway
+   * uses a redirect-style flow this is the lookup key.
+   */
+  sessionId?: string | null;
+  /**
+   * Stripe-style `pi_xxx` payment-intent id. May equal `id` for
+   * gateways that don't distinguish session vs intent.
+   */
+  paymentIntentId?: string | null;
+  /** Frontend hand-off — Stripe Elements / Razorpay Checkout consume this. */
+  clientSecret?: string;
+  /** Off-site redirect URL (PayPal `approve` link, SSLCommerz GatewayPageURL). */
+  paymentUrl?: string;
+  /** Manual-flow instructions ("transfer to A/c 1234, reference X"). */
+  instructions?: string;
+  /** Pass-through metadata echoed from the create call. */
+  metadata?: Record<string, unknown>;
+  /** Raw provider response — kept for audit. Consumers MUST NOT rely on shape. */
+  raw?: unknown;
+}
+/**
+ * What `provider.verifyPayment(intentId)` returns. The engine maps
+ * this to its `TRANSACTION_STATUS` state machine.
+ */
+interface PaymentResult {
+  /** Gateway-scoped id (intent id, charge id, tran id — whatever the gateway uses). */
+  id: string;
+  /** Lowercase gateway name. */
+  provider: string;
+  /**
+   * Closed status set — narrower than `PaymentIntent.status` because
+   * verification has settled the lifecycle.
+   *
+   * - `'succeeded'` — payment captured, funds owed to merchant.
+   * - `'failed'` — terminal failure. Engine moves Transaction to FAILED.
+   * - `'processing'` — async processing (ACH, e-wallet pending bank).
+   * - `'requires_action'` — 3DS, OTP, or out-of-band approval pending.
+   */
+  status: 'succeeded' | 'failed' | 'processing' | 'requires_action';
+  /** Captured amount as the gateway reports it (may differ from intent on partial capture). */
+  amount?: Money;
+  /** When the gateway booked the capture. */
+  paidAt?: Date;
+  /** Pass-through metadata (gateway customer id, fee breakdown, etc.). */
+  metadata?: Record<string, unknown>;
+  /** Raw response — audit only. */
+  raw?: unknown;
+}
+/**
+ * What `provider.refund(...)` returns. Successful refunds become a
+ * new `'refund'` Transaction (flow: `'outflow'`) on the engine side.
+ */
+interface RefundResult {
+  /** Gateway-scoped refund id (Stripe `re_xxx`, etc.). */
+  id: string;
+  /** Lowercase gateway name. */
+  provider: string;
+  status: 'succeeded' | 'failed' | 'processing';
+  /** Amount reversed, as the gateway reports it. May be partial. */
+  amount?: Money;
+  /** When the gateway booked the refund. */
+  refundedAt?: Date;
+  /** Reason string forwarded from the engine call (or filled by the gateway). */
+  reason?: string;
+  metadata?: Record<string, unknown>;
+  raw?: unknown;
+}
+/**
+ * Parsed webhook event from a gateway's HTTP delivery. Engine stamps
+ * `id` on the Transaction's `webhook.eventId` for atomic dedup —
+ * replays of the same `id` are no-ops.
+ */
+interface WebhookEvent {
+  /**
+   * Gateway-scoped event id (Stripe `evt_xxx`, Razorpay
+   * `webhook_event_id`). Used as the dedup key — repeating delivery
+   * attempts MUST share the same id.
+   */
+  id: string;
+  /** Lowercase gateway name. */
+  provider: string;
+  /** Event type (`'payment.succeeded'`, `'charge.refunded'`, etc.). */
+  type: string;
+  /**
+   * Routing fields the engine uses to find the matching Transaction:
+   *   - `sessionId` — for redirect-style flows.
+   *   - `paymentIntentId` — for Stripe-style flows.
+   * Plus arbitrary additional gateway data.
+   */
+  data: {
+    sessionId?: string;
+    paymentIntentId?: string;
+    [key: string]: unknown;
+  };
+  /** When the gateway emitted the event. */
+  createdAt?: Date;
+  /** Raw provider payload — audit only. */
+  raw?: unknown;
+}
+//#endregion
+export { CreateIntentParams, PaymentIntent, PaymentResult, ProviderCapabilities, RefundResult, WebhookEvent };

package/dist/payment-gateway.mjs

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -89,6 +89,14 @@
       "types": "./dist/state-machine.d.mts",
       "default": "./dist/state-machine.mjs"
     },
+    "./bank-transaction": {
+      "types": "./dist/bank-transaction.d.mts",
+      "default": "./dist/bank-transaction.mjs"
+    },
+    "./payment-gateway": {
+      "types": "./dist/payment-gateway.d.mts",
+      "default": "./dist/payment-gateway.mjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [