@classytic/primitives 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -3,6 +3,56 @@
 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.7.2] - 2026-05-30
+
+### Added — `BankTransaction` per-account routing + pending lifecycle fields
+
+Three additive optional fields on `BankTransaction` (`/bank-transaction`):
+
+- **`sourceAccountId?: string`** — the vendor-side account this row belongs to
+  (Plaid `account_id`, Xero `BankAccount.AccountID`). Sync feeds return
+  transactions spanning multiple accounts in one batch; this lets consumers
+  route each row to the right account per-transaction (multi-account sync)
+  instead of forcing the whole batch onto one account. Statement formats
+  (single-account files) leave it undefined — the account lives on
+  `BankStatement.account`.
+- **`pending?: boolean`** — the entry hasn't posted/cleared yet (real-time
+  feeds like Plaid `pending: true`; statement formats leave it undefined).
+  Consumers must treat pending rows as provisional — don't reconcile/post
+  them as final.
+- **`supersedesExternalId?: string`** — set on a POSTED row that replaces an
+  earlier PENDING one, carrying the pending row's `externalId` (Plaid
+  `pending_transaction_id`). Pending and posted rows have different
+  `externalId`s, so consumers MUST use this back-pointer to drop/replace the
+  superseded pending row on ingest — otherwise both persist as duplicates.
+
+Backward-compatible (both optional). Closes a fidelity gap where Plaid's
+pending state was dropped at the canonical boundary, so downstream consumers
+(`@classytic/fin-io` Plaid mapper, `@classytic/revenue` import) couldn't
+distinguish provisional rows or dedupe pending→posted.
+
+## [0.7.1] - 2026-05-26
+
+### Added — workflow + scheduling + composition primitives
+
+Four new flat subpaths (additive):
+
+- **`/status-history`** — append-only status transition log primitive.
+- **`/condition`** — declarative condition expressions for workflow gates.
+- **`/mixin`** — composition helpers for primitive object assembly.
+- **`/sla-policy`** — SLA policy definitions paired with the existing `/sla` runtime.
+
+### Added — payment event coverage
+
+Expanded `PAYMENT_EVENT_TYPE` catalogue to cover auth/capture and dispute
+lifecycles: `AUTHORIZED`, `CAPTURED`, `AUTH_VOIDED`, `DISPUTED`,
+`DISPUTE_WON`, `DISPUTE_LOST`, `SETTLED`.
+
+`PaymentRefundedPayload` and `PaymentReversedPayload` now carry
+`originalAmount` (and `reversedAmount` / `isPartial` on reversed) so
+consumers can detect partial vs full operations without a follow-up
+Payment lookup.
+
 ## [0.7.0] - 2026-05-26
 
 ### Added — payment domain primitives

package/dist/bank-transaction.d.mts

@@ -96,6 +96,41 @@ interface BankTransaction {
   balanceAfter?: Money;
   /** Format-specific entry-type code (`'DEBIT'`, `'CREDIT'`, `'CHECK'`, …). */
   type?: string;
+  /**
+   * Vendor-side identifier of the account this row belongs to — Plaid
+   * `account_id`, Xero `BankAccount.AccountID`. Sync feeds return transactions
+   * spanning MULTIPLE accounts in one batch, so this lets a consumer route
+   * each row to the right destination account per-transaction (multi-account
+   * sync) instead of forcing the whole batch onto one account.
+   *
+   * Statement formats (OFX / CAMT.053 / MT940 / CSV / IIF) are single-account
+   * files — they carry the account on `BankStatement.account` and leave this
+   * `undefined`. Distinct from any consumer-side account id (e.g. the host's
+   * own `bankAccountId` used in the import unique index).
+   */
+  sourceAccountId?: string;
+  /**
+   * The entry has not yet posted / cleared — the bank may still change its
+   * amount, description, or drop it entirely. Real-time feeds populate this
+   * (Plaid `pending: true`); statement formats (OFX / CAMT.053 / MT940 / CSV)
+   * only ever carry settled rows and leave it `undefined`.
+   *
+   * Consumers MUST treat `pending: true` rows as provisional — do not
+   * reconcile or post them as final, and expect a superseding posted row to
+   * arrive later (linked via `supersedesExternalId`).
+   */
+  pending?: boolean;
+  /**
+   * Set on a POSTED row that replaces an earlier PENDING one: the
+   * `externalId` of the pending row this entry supersedes (Plaid
+   * `pending_transaction_id`).
+   *
+   * The pending and posted rows carry DIFFERENT `externalId`s, so dedup on
+   * `externalId` alone can't collapse them — consumers MUST use this
+   * back-pointer to drop / replace the superseded pending row on ingest, or
+   * both versions persist as duplicates.
+   */
+  supersedesExternalId?: string;
   /**
    * Format-specific raw record. Pass-through for audit / debugging.
    * Consumers MUST NOT rely on this — schema may change between fin-io

package/dist/payment-events.d.mts

@@ -14,6 +14,13 @@ declare const PAYMENT_EVENT_TYPE: {
   readonly REFUNDED: "payment.refunded";
   readonly REVERSED: "payment.reversed";
   readonly RECONCILED: "payment.reconciled";
+  readonly AUTHORIZED: "payment.authorized";
+  readonly CAPTURED: "payment.captured";
+  readonly AUTH_VOIDED: "payment.auth_voided";
+  readonly DISPUTED: "payment.disputed";
+  readonly DISPUTE_WON: "payment.dispute_won";
+  readonly DISPUTE_LOST: "payment.dispute_lost";
+  readonly SETTLED: "payment.settled";
 };
 type PaymentEventType = (typeof PAYMENT_EVENT_TYPE)[keyof typeof PAYMENT_EVENT_TYPE];
 /**
@@ -93,6 +100,8 @@ interface PaymentRefundedPayload {
   providerCode: string;
   /** Amount refunded in this event — may be less than the original payment. */
   refundedAmount: Money;
+  /** Original payment total — present so consumers can compute remaining refundable without a Payment lookup. */
+  originalAmount: Money;
   /** `true` if this refund returns less than the original payment total. */
   isPartial: boolean;
   reason?: string;
@@ -110,6 +119,12 @@ interface PaymentReversedPayload {
   paymentId: string;
   providerRef?: string;
   providerCode: string;
+  /** Amount being unwound — equals the original payment for full reversal, less for partial. */
+  reversedAmount: Money;
+  /** Original payment total — present so consumers can detect partial vs full without a Payment lookup. */
+  originalAmount: Money;
+  /** `true` when reversedAmount < originalAmount. */
+  isPartial: boolean;
   reason: string;
   occurredAt: Date;
   metadata?: Record<string, unknown>;
@@ -135,7 +150,122 @@ interface PaymentReconciledPayload {
   reconciledBy: string;
   metadata?: Record<string, unknown>;
 }
+/**
+ * Gateway has placed an authorisation hold but has NOT captured funds.
+ * Distinct from {@link PaymentSucceededPayload} — auth-only flows split
+ * "hold" from "settle"; consumers should NOT treat this as cleared funds.
+ */
+interface PaymentAuthorizedPayload {
+  paymentId: string;
+  providerRef?: string;
+  providerCode: string;
+  /** Amount the gateway has placed a hold for — may be captured later in full or part. */
+  authorizedAmount: Money;
+  methodKind: PaymentMethodKind;
+  methodCode?: string;
+  /** When the auth hold expires if not captured — Stripe defaults to 7 days for cards. */
+  expiresAt?: Date;
+  occurredAt: Date;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Gateway has captured a previously-authorised payment — funds confirmed.
+ * Pairs with {@link PaymentAuthorizedPayload} for two-phase flows.
+ */
+interface PaymentCapturedPayload {
+  paymentId: string;
+  providerRef?: string;
+  providerCode: string;
+  /** Amount actually captured — `<=` original auth. */
+  capturedAmount: Money;
+  /** Total authorised — present so consumers can compute remaining holdable. */
+  authorizedAmount: Money;
+  /** `true` when capturedAmount < authorizedAmount (partial capture). */
+  isPartial: boolean;
+  methodKind: PaymentMethodKind;
+  methodCode?: string;
+  occurredAt: Date;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Authorisation hold released — uncaptured auth voided before settlement.
+ */
+interface PaymentAuthVoidedPayload {
+  paymentId: string;
+  providerRef?: string;
+  providerCode: string;
+  /** Amount released back to the customer's available balance. */
+  voidedAmount: Money;
+  reason?: string;
+  occurredAt: Date;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Customer / issuing bank opened a dispute or chargeback against this
+ * payment. The merchant typically has a deadline to submit evidence.
+ */
+interface PaymentDisputedPayload {
+  paymentId: string;
+  /** Provider's dispute / chargeback id. */
+  disputeId: string;
+  providerRef?: string;
+  providerCode: string;
+  /** Amount being disputed — may be less than the original payment for partial chargebacks. */
+  disputedAmount: Money;
+  /** Provider's category — `'fraudulent'`, `'product_not_received'`, `'duplicate'`, etc. */
+  reason: string;
+  /** Provider lifecycle phase at the time of emit — `'warning_needs_response'`, `'needs_response'`, `'under_review'`. */
+  status: string;
+  /** When the host must submit evidence by, if applicable. */
+  evidenceDueBy?: Date;
+  occurredAt: Date;
+  metadata?: Record<string, unknown>;
+}
+/** Dispute resolved in merchant's favour — funds restored. */
+interface PaymentDisputeWonPayload {
+  paymentId: string;
+  disputeId: string;
+  providerRef?: string;
+  providerCode: string;
+  /** Amount restored to the merchant. */
+  recoveredAmount: Money;
+  occurredAt: Date;
+  metadata?: Record<string, unknown>;
+}
+/** Dispute resolved against merchant — funds permanently lost plus fee. */
+interface PaymentDisputeLostPayload {
+  paymentId: string;
+  disputeId: string;
+  providerRef?: string;
+  providerCode: string;
+  /** Amount permanently debited from the merchant. */
+  lostAmount: Money;
+  /** Dispute / chargeback fee the merchant pays in addition. */
+  feeAmount?: Money;
+  occurredAt: Date;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Funds have been settled to the merchant bank account by the gateway —
+ * the gross-vs-net delta is the processor fee. Use for bank-statement
+ * reconciliation in country-aware ledger bridges.
+ */
+interface PaymentSettledPayload {
+  paymentId: string;
+  providerRef?: string;
+  providerCode: string;
+  /** Net amount transferred to the merchant bank account (gross - fees). */
+  settledAmount: Money;
+  /** Provider fee deducted before settlement. */
+  feeAmount?: Money;
+  /** Provider's payout / settlement batch identifier — useful for bank-statement matching. */
+  payoutId?: string;
+  /** When the funds become available in the merchant account. */
+  expectedArrivalAt?: Date;
+  occurredAt: Date;
+  metadata?: Record<string, unknown>;
+}
 /** Union of all payment event payload types — convenient for exhaustive switches. */
-type PaymentEventPayload = PaymentInitiatedPayload | PaymentSucceededPayload | PaymentFailedPayload | PaymentRefundedPayload | PaymentReversedPayload | PaymentReconciledPayload;
+type PaymentEventPayload = PaymentInitiatedPayload | PaymentSucceededPayload | PaymentFailedPayload | PaymentRefundedPayload | PaymentReversedPayload | PaymentReconciledPayload | PaymentAuthorizedPayload | PaymentCapturedPayload | PaymentAuthVoidedPayload | PaymentDisputedPayload | PaymentDisputeWonPayload | PaymentDisputeLostPayload | PaymentSettledPayload;
 //#endregion
-export { PAYMENT_EVENT_TYPE, PaymentEventPayload, PaymentEventType, PaymentFailedPayload, PaymentInitiatedPayload, PaymentReconciledPayload, PaymentRefundedPayload, PaymentReversedPayload, PaymentSucceededPayload };
+export { PAYMENT_EVENT_TYPE, PaymentAuthVoidedPayload, PaymentAuthorizedPayload, PaymentCapturedPayload, PaymentDisputeLostPayload, PaymentDisputeWonPayload, PaymentDisputedPayload, PaymentEventPayload, PaymentEventType, PaymentFailedPayload, PaymentInitiatedPayload, PaymentReconciledPayload, PaymentRefundedPayload, PaymentReversedPayload, PaymentSettledPayload, PaymentSucceededPayload };

package/dist/payment-events.mjs

@@ -10,7 +10,14 @@ const PAYMENT_EVENT_TYPE = {
 	FAILED: "payment.failed",
 	REFUNDED: "payment.refunded",
 	REVERSED: "payment.reversed",
-	RECONCILED: "payment.reconciled"
+	RECONCILED: "payment.reconciled",
+	AUTHORIZED: "payment.authorized",
+	CAPTURED: "payment.captured",
+	AUTH_VOIDED: "payment.auth_voided",
+	DISPUTED: "payment.disputed",
+	DISPUTE_WON: "payment.dispute_won",
+	DISPUTE_LOST: "payment.dispute_lost",
+	SETTLED: "payment.settled"
 };
 //#endregion
 export { PAYMENT_EVENT_TYPE };

package/dist/payment-gateway.d.mts

@@ -1,4 +1,5 @@
 import { Money } from "./money.mjs";
+import { PaymentMethodKind } from "./payment-method-kind.mjs";
 
 //#region src/money/payment-gateway.d.ts
 /**
@@ -43,6 +44,14 @@ interface CreateIntentParams {
    */
   [key: string]: unknown;
 }
+/**
+ * Closed set of intent lifecycle states the engine recognises. Modelled on
+ * Stripe's PaymentIntent status because every other gateway maps cleanly
+ * INTO this set; gateways that lack a state simply never emit it.
+ */
+type PaymentIntentStatus = 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'requires_capture' | 'canceled' | 'succeeded';
+/** Closed set of refund lifecycle states the engine recognises. */
+type RefundResultStatus = 'pending' | 'requires_action' | 'succeeded' | 'failed' | 'canceled';
 /**
  * What `provider.createIntent(...)` returns. The engine persists
  * `id` / `paymentIntentId` / `sessionId` on the Transaction's
@@ -55,12 +64,10 @@ interface PaymentIntent {
   /** 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'`.
+   * Lifecycle status — closed union the engine state-machines branch on.
+   * Adapters MUST map provider-native strings into this set.
    */
-  status: string;
+  status: PaymentIntentStatus;
   /** Amount + currency that the intent locks in. */
   amount: Money;
   /**
@@ -80,6 +87,8 @@ interface PaymentIntent {
   paymentUrl?: string;
   /** Manual-flow instructions ("transfer to A/c 1234, reference X"). */
   instructions?: string;
+  /** Canonical method kind if known at intent creation (customer pre-selected). */
+  methodKind?: PaymentMethodKind;
   /** Pass-through metadata echoed from the create call. */
   metadata?: Record<string, unknown>;
   /** Raw provider response — kept for audit. Consumers MUST NOT rely on shape. */
@@ -108,6 +117,8 @@ interface PaymentResult {
   amount?: Money;
   /** When the gateway booked the capture. */
   paidAt?: Date;
+  /** Canonical method kind chosen by the customer (typically known post-settlement). */
+  methodKind?: PaymentMethodKind;
   /** Pass-through metadata (gateway customer id, fee breakdown, etc.). */
   metadata?: Record<string, unknown>;
   /** Raw response — audit only. */
@@ -122,7 +133,7 @@ interface RefundResult {
   id: string;
   /** Lowercase gateway name. */
   provider: string;
-  status: 'succeeded' | 'failed' | 'processing';
+  status: RefundResultStatus;
   /** Amount reversed, as the gateway reports it. May be partial. */
   amount?: Money;
   /** When the gateway booked the refund. */
@@ -161,8 +172,18 @@ interface WebhookEvent {
   };
   /** When the gateway emitted the event. */
   createdAt?: Date;
+  /** Canonical method kind derived from the event payload, when present. */
+  methodKind?: PaymentMethodKind;
+  /** Provider signature header value — kept for delayed verification / audit replay. */
+  signature?: string;
+  /** Signature timestamp the provider asserted — for replay-window enforcement. */
+  signatureTimestamp?: Date;
+  /** Connected-account id for multi-tenant routing — Stripe Connect uses `event.account`. */
+  accountId?: string;
+  /** Test vs production mode — Stripe's `livemode`. False / undefined = test. */
+  livemode?: boolean;
   /** Raw provider payload — audit only. */
   raw?: unknown;
 }
 //#endregion
-export { CreateIntentParams, PaymentIntent, PaymentResult, ProviderCapabilities, RefundResult, WebhookEvent };
+export { CreateIntentParams, PaymentIntent, PaymentIntentStatus, PaymentResult, ProviderCapabilities, RefundResult, RefundResultStatus, WebhookEvent };

package/dist/payment-method-kind.d.mts

@@ -12,13 +12,25 @@
  * (show wallet form vs card form vs cash form) while the host owns the
  * concrete method catalogue.
  *
+ * The enum is curated for distinct lifecycle / accounting / reporting
+ * characteristics, not provider variants. Provider-specific identification
+ * belongs in a host `methodCode` (e.g. `'stripe_card'`, `'bkash'`,
+ * `'klarna'`) and per-payment metadata. Consumers SHOULD handle unknown
+ * values defensively (fall through to `'other'` semantics) since the
+ * union may grow in future minor versions.
+ *
  * Zero runtime, zero deps. Mirror this exactly anywhere a payment leg's
  * "what kind of payment was this" needs to be typed.
  */
 declare const PAYMENT_METHOD_KIND: {
-  /** Credit / debit card — Visa, Mastercard, Amex, RuPay, UnionPay, … */readonly CARD: "card"; /** Direct bank transfer — ACH, SEPA, IMPS, NEFT, RTGS, wire, … */
-  readonly BANK_TRANSFER: "bank_transfer"; /** Digital wallet — bKash, Nagad, PayPal, Apple Pay, Google Pay, Alipay, … */
-  readonly WALLET: "wallet"; /** Physical cash. */
+  /** Credit / debit card — Visa, Mastercard, Amex, RuPay, UnionPay, … */readonly CARD: "card"; /** Standard bank transfer — ACH credit, SEPA credit, IMPS, NEFT, RTGS, wire. */
+  readonly BANK_TRANSFER: "bank_transfer"; /** Real-time bank rails — UPI, Pix, FedNow, PromptPay, FPX, GrabPay rails. */
+  readonly INSTANT_BANK_TRANSFER: "instant_bank_transfer"; /** Mandate-based bank pull — SEPA Direct Debit, ACH Debit, BACS Direct Debit, AU BECS. */
+  readonly DIRECT_DEBIT: "direct_debit"; /** Digital wallet — Apple Pay, Google Pay, Link, PayPal, Cashapp, Alipay, WeChat Pay, Revolut Pay. */
+  readonly WALLET: "wallet"; /** Cash-in/out wallet infrastructure in unbanked markets — bKash, Nagad, M-Pesa, MoMo, GCash. */
+  readonly MOBILE_MONEY: "mobile_money"; /** Buy now pay later — Klarna, Afterpay, Affirm, Tabby, Tamara. */
+  readonly BNPL: "bnpl"; /** Customer-purchased prepaid credit / voucher. */
+  readonly GIFT_CARD: "gift_card"; /** Physical cash. */
   readonly CASH: "cash"; /** Paper cheque. */
   readonly CHEQUE: "cheque"; /** Cryptocurrency settlement. */
   readonly CRYPTO: "cryptocurrency";

package/dist/payment-method-kind.mjs

@@ -12,13 +12,25 @@
 * (show wallet form vs card form vs cash form) while the host owns the
 * concrete method catalogue.
 *
+* The enum is curated for distinct lifecycle / accounting / reporting
+* characteristics, not provider variants. Provider-specific identification
+* belongs in a host `methodCode` (e.g. `'stripe_card'`, `'bkash'`,
+* `'klarna'`) and per-payment metadata. Consumers SHOULD handle unknown
+* values defensively (fall through to `'other'` semantics) since the
+* union may grow in future minor versions.
+*
 * Zero runtime, zero deps. Mirror this exactly anywhere a payment leg's
 * "what kind of payment was this" needs to be typed.
 */
 const PAYMENT_METHOD_KIND = {
 	CARD: "card",
 	BANK_TRANSFER: "bank_transfer",
+	INSTANT_BANK_TRANSFER: "instant_bank_transfer",
+	DIRECT_DEBIT: "direct_debit",
 	WALLET: "wallet",
+	MOBILE_MONEY: "mobile_money",
+	BNPL: "bnpl",
+	GIFT_CARD: "gift_card",
 	CASH: "cash",
 	CHEQUE: "cheque",
 	CRYPTO: "cryptocurrency",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",