@classytic/primitives 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -3,13 +3,55 @@
 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.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
+
+Three new subpaths shared across every payment-aware package
+(`@classytic/invoice`, `@classytic/revenue`, `@classytic/order`, future
+POS / AP / subscription packages). Each ships under a flat subpath so
+consumers tree-shake what they don't import.
+
+- **`/payment-method-kind`** — `PaymentMethodKind` universal vocabulary
+  (kind vs host-registered `methodCode`) so packages can speak `kind`
+  while hosts speak `code`.
+- **`/payment-allocation-status`** — orthogonal allocation +
+  reconciliation status enums for payment legs (`unallocated`,
+  `partial`, `allocated`, `over_allocated`, plus reconciliation states).
+- **`/payment-events`** — pure TS payload contracts for payment domain
+  events. Wire-only (no Zod, no runtime). Anchored on `Money` +
+  `PaymentMethodKind`; causation/correlation stay on `EventMeta`.
+
+No breaking changes.
+
 ## [0.6.0] - 2026-05-17
 
 ### Added — five new primitives for CRM / workflow domains
 
-These were extracted after deep-diving Twenty, Huly Platform, Frappe CRM,
-and NocoBase. Each fills a gap the existing primitives didn't cover, and
-each ships under its own flat subpath import (no breaking changes).
+Five new primitives covering gaps the existing surface didn't address.
+Each ships under its own flat subpath import (no breaking changes).
 
 - **`/phone`** — `PhoneNumber` value object + `parsePhone(input)` that
   normalizes free-form input to E.164, captures the country calling code
@@ -20,10 +62,9 @@ each ships under its own flat subpath import (no breaking changes).
 
 - **`/status-history`** — Generic, immutable status-change log:
   `StatusChangeEntry<TStatus>`, `appendStatus()`, `timeInStatus()`,
-  `lastTransitionTo()`. Captures `durationInPriorMs` at write time
-  (Frappe's "status change log" pattern), so funnel-velocity dashboards
-  ("avg time in Qualification") work without re-walking timestamps.
-  Pairs naturally with `/state-machine`.
+  `lastTransitionTo()`. Captures `durationInPriorMs` at write time so
+  funnel-velocity dashboards ("avg time in Qualification") work without
+  re-walking timestamps. Pairs naturally with `/state-machine`.
 
 - **`/condition`** — Tiny JSON-serializable predicate DSL: `FieldCondition`
   (`{ field, op, value }`) composed via `AllCondition` / `AnyCondition`
@@ -37,8 +78,8 @@ each ships under its own flat subpath import (no breaking changes).
   `withMixin<T, K, M>()` / `getMixin()` / `hasMixin()` / `withoutMixin()`.
   Lets a `Contact` carry per-domain payloads (`mixins.customer`,
   `mixins.lead-fit`) on a typed `mixins` namespace without bloating the
-  base type. Distilled from Huly's mixin idea minus the decorators,
-  global hierarchy, and proxies.
+  base type. Plain object composition — no decorators, no global
+  hierarchy, no proxies.
 
 - **`/sla-policy`** — Higher-order SLA layered on the existing `/sla`:
   priority matrix (`urgent` / `high` / `normal` → durations), first-

package/dist/payment-allocation-status.d.mts

@@ -0,0 +1,47 @@
+//#region src/money/payment-allocation-status.d.ts
+/**
+ * Allocation + reconciliation status enums for payment legs.
+ *
+ * Two orthogonal dimensions sit on every PaymentAllocation row (or
+ * equivalent in any package that settles money against an invoice /
+ * order / claim):
+ *
+ *   1. **Allocation status** — has this payment been *applied* against
+ *      the obligation(s) it's meant to settle? (`unallocated`,
+ *      `partial`, `allocated`, `over_allocated`)
+ *   2. **Reconciliation status** — has this allocation been *matched*
+ *      to a bank statement line / processor settlement record?
+ *      (`unreconciled`, `matched`, `manual`, `disputed`)
+ *
+ * Both are needed because a payment can be allocated (the AR ledger
+ * thinks it's done) without being reconciled (the bank statement
+ * hasn't been imported / matched yet), and vice versa.
+ *
+ * Zero runtime, zero deps.
+ */
+declare const PAYMENT_ALLOCATION_STATUS: {
+  /** No portion of the payment has been applied to any obligation yet. */readonly UNALLOCATED: "unallocated"; /** Some of the payment is applied; remainder is available credit. */
+  readonly PARTIAL: "partial"; /** Fully applied — `sum(allocations) === payment.totalAmount`. */
+  readonly ALLOCATED: "allocated";
+  /**
+   * Sum of allocations exceeds the payment total — invariant violation
+   * that should be flagged for operator review, never silently accepted.
+   */
+  readonly OVER_ALLOCATED: "over_allocated";
+};
+type PaymentAllocationStatus = (typeof PAYMENT_ALLOCATION_STATUS)[keyof typeof PAYMENT_ALLOCATION_STATUS];
+declare const RECONCILIATION_STATUS: {
+  /** No bank statement line / settlement record has been linked yet. */readonly UNRECONCILED: "unreconciled"; /** Auto-matched to a `BankTransaction` by amount + date + reference. */
+  readonly MATCHED: "matched"; /** Operator-confirmed match (auto-match failed or was overridden). */
+  readonly MANUAL: "manual";
+  /**
+   * Match was contested — amount mismatch, duplicate claim, chargeback
+   * in flight. Halts further automated processing until resolved.
+   */
+  readonly DISPUTED: "disputed";
+};
+type ReconciliationStatus = (typeof RECONCILIATION_STATUS)[keyof typeof RECONCILIATION_STATUS];
+declare const isPaymentAllocationStatus: (value: unknown) => value is PaymentAllocationStatus;
+declare const isReconciliationStatus: (value: unknown) => value is ReconciliationStatus;
+//#endregion
+export { PAYMENT_ALLOCATION_STATUS, PaymentAllocationStatus, RECONCILIATION_STATUS, ReconciliationStatus, isPaymentAllocationStatus, isReconciliationStatus };

package/dist/payment-allocation-status.mjs

@@ -0,0 +1,39 @@
+//#region src/money/payment-allocation-status.ts
+/**
+* Allocation + reconciliation status enums for payment legs.
+*
+* Two orthogonal dimensions sit on every PaymentAllocation row (or
+* equivalent in any package that settles money against an invoice /
+* order / claim):
+*
+*   1. **Allocation status** — has this payment been *applied* against
+*      the obligation(s) it's meant to settle? (`unallocated`,
+*      `partial`, `allocated`, `over_allocated`)
+*   2. **Reconciliation status** — has this allocation been *matched*
+*      to a bank statement line / processor settlement record?
+*      (`unreconciled`, `matched`, `manual`, `disputed`)
+*
+* Both are needed because a payment can be allocated (the AR ledger
+* thinks it's done) without being reconciled (the bank statement
+* hasn't been imported / matched yet), and vice versa.
+*
+* Zero runtime, zero deps.
+*/
+const PAYMENT_ALLOCATION_STATUS = {
+	UNALLOCATED: "unallocated",
+	PARTIAL: "partial",
+	ALLOCATED: "allocated",
+	OVER_ALLOCATED: "over_allocated"
+};
+const RECONCILIATION_STATUS = {
+	UNRECONCILED: "unreconciled",
+	MATCHED: "matched",
+	MANUAL: "manual",
+	DISPUTED: "disputed"
+};
+const ALLOCATION_VALUES = new Set(Object.values(PAYMENT_ALLOCATION_STATUS));
+const RECONCILIATION_VALUES = new Set(Object.values(RECONCILIATION_STATUS));
+const isPaymentAllocationStatus = (value) => typeof value === "string" && ALLOCATION_VALUES.has(value);
+const isReconciliationStatus = (value) => typeof value === "string" && RECONCILIATION_VALUES.has(value);
+//#endregion
+export { PAYMENT_ALLOCATION_STATUS, RECONCILIATION_STATUS, isPaymentAllocationStatus, isReconciliationStatus };

package/dist/payment-events.d.mts

@@ -0,0 +1,271 @@
+import { Money } from "./money.mjs";
+import { PaymentMethodKind } from "./payment-method-kind.mjs";
+
+//#region src/events/payment-events.d.ts
+/**
+ * Canonical event-name constants. Packages SHOULD publish events
+ * keyed by these strings so consumers can subscribe by type without
+ * importing per-package catalogues.
+ */
+declare const PAYMENT_EVENT_TYPE: {
+  readonly INITIATED: "payment.initiated";
+  readonly SUCCEEDED: "payment.succeeded";
+  readonly FAILED: "payment.failed";
+  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];
+/**
+ * A payment attempt has been started against a provider — intent
+ * created, checkout session opened, manual record drafted. The
+ * obligation is NOT settled yet; consumers should treat this as
+ * "money in flight" not "money received".
+ */
+interface PaymentInitiatedPayload {
+  /** Stable payment identifier owned by the emitting package. */
+  paymentId: string;
+  /**
+   * Provider's reference for this attempt — Stripe payment intent id,
+   * bKash sessionId, internal sequence number for manual entries.
+   */
+  providerRef?: string;
+  /** Provider name — `'stripe'`, `'bkash'`, `'manual'`, host-defined. */
+  providerCode: string;
+  amount: Money;
+  methodKind: PaymentMethodKind;
+  /**
+   * Host-specific method code from the host's PaymentMethod registry
+   * (e.g. `'bkash'`, `'stripe_card'`). Optional because not every host
+   * runs a registry; when absent, `methodKind` is the only classifier.
+   */
+  methodCode?: string;
+  occurredAt: Date;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * A payment has cleared — funds are confirmed received by the merchant
+ * (gateway success, manual confirmation, bank credit). This is the
+ * trigger for AR settlement, invoice paymentStatus updates, and
+ * downstream fulfilment unlocks.
+ */
+interface PaymentSucceededPayload {
+  paymentId: string;
+  providerRef?: string;
+  providerCode: string;
+  amount: Money;
+  methodKind: PaymentMethodKind;
+  methodCode?: string;
+  occurredAt: Date;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * A payment attempt failed before clearing — card declined, wallet
+ * timeout, manual rejection. The obligation remains unsettled;
+ * consumers may retry, prompt the customer, or mark the invoice
+ * overdue.
+ */
+interface PaymentFailedPayload {
+  paymentId: string;
+  providerRef?: string;
+  providerCode: string;
+  amount: Money;
+  methodKind: PaymentMethodKind;
+  methodCode?: string;
+  /** Human-readable reason from the provider or operator. */
+  reason: string;
+  /** Machine code for failure classification — e.g. `'card_declined'`. */
+  reasonCode?: string;
+  occurredAt: Date;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * A previously-succeeded payment has been refunded — partial or full.
+ * Distinct from {@link PaymentReversedPayload}: a refund returns money
+ * to the customer (post-settlement); a reversal undoes the settlement
+ * itself (pre- or post-clearing, often due to operator error).
+ */
+interface PaymentRefundedPayload {
+  paymentId: string;
+  /** Refund identifier (separate from `paymentId`). */
+  refundId: string;
+  providerRef?: string;
+  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;
+  occurredAt: Date;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * A payment has been reversed — the settlement is being unwound,
+ * typically because of operator error, duplicate capture, or
+ * pre-clearing cancellation. Allocations referencing this payment
+ * MUST be unwound by consumers; AR balance restores to pre-payment
+ * state.
+ */
+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>;
+}
+/**
+ * An allocation (the row that ties a payment to an obligation — invoice,
+ * order, claim) has been reconciled against a bank-statement line or
+ * processor settlement record. Triggers GL posting in country-aware
+ * ledger bridges and closes the audit loop.
+ */
+interface PaymentReconciledPayload {
+  /** Allocation identifier — NOT the payment id (a payment can have many). */
+  allocationId: string;
+  paymentId: string;
+  /**
+   * External reference of the matched record — typically a
+   * `BankTransaction.externalId`, processor settlement id, or
+   * operator-supplied note.
+   */
+  externalRef: string;
+  reconciledAt: Date;
+  /** Actor id who confirmed the match (operator) or `'system'` for auto-match. */
+  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 | PaymentAuthorizedPayload | PaymentCapturedPayload | PaymentAuthVoidedPayload | PaymentDisputedPayload | PaymentDisputeWonPayload | PaymentDisputeLostPayload | PaymentSettledPayload;
+//#endregion
+export { PAYMENT_EVENT_TYPE, PaymentAuthVoidedPayload, PaymentAuthorizedPayload, PaymentCapturedPayload, PaymentDisputeLostPayload, PaymentDisputeWonPayload, PaymentDisputedPayload, PaymentEventPayload, PaymentEventType, PaymentFailedPayload, PaymentInitiatedPayload, PaymentReconciledPayload, PaymentRefundedPayload, PaymentReversedPayload, PaymentSettledPayload, PaymentSucceededPayload };

package/dist/payment-events.mjs

@@ -0,0 +1,23 @@
+//#region src/events/payment-events.ts
+/**
+* Canonical event-name constants. Packages SHOULD publish events
+* keyed by these strings so consumers can subscribe by type without
+* importing per-package catalogues.
+*/
+const PAYMENT_EVENT_TYPE = {
+	INITIATED: "payment.initiated",
+	SUCCEEDED: "payment.succeeded",
+	FAILED: "payment.failed",
+	REFUNDED: "payment.refunded",
+	REVERSED: "payment.reversed",
+	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

@@ -0,0 +1,48 @@
+//#region src/money/payment-method-kind.d.ts
+/**
+ * Canonical payment method kinds — the universal vocabulary every
+ * payment-aware package speaks (`@classytic/invoice`, `@classytic/revenue`,
+ * `@classytic/order`, future POS / AP / subscription packages, …).
+ *
+ * **Kind vs code.** A `PaymentMethodKind` is the universal category
+ * (every payment system on earth has these). A `methodCode` is the
+ * host-specific string registered in a host's `PaymentMethod` registry
+ * (`'bkash'`, `'nagad'`, `'stripe_card'`, `'cash_register_3'`). Packages
+ * speak `kind`; hosts speak `code`. The pair lets UIs branch on kind
+ * (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"; /** 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";
+  /**
+   * Operator-recorded settlement that doesn't fit any other kind — e.g.
+   * an offline bank deposit confirmed by phone, an in-kind exchange, a
+   * manual write-off. Always-valid escape hatch.
+   */
+  readonly MANUAL: "manual"; /** Unknown or vendor-specific kind — last resort. Prefer a specific kind. */
+  readonly OTHER: "other";
+};
+type PaymentMethodKind = (typeof PAYMENT_METHOD_KIND)[keyof typeof PAYMENT_METHOD_KIND];
+declare const isPaymentMethodKind: (value: unknown) => value is PaymentMethodKind;
+//#endregion
+export { PAYMENT_METHOD_KIND, PaymentMethodKind, isPaymentMethodKind };

package/dist/payment-method-kind.mjs

@@ -0,0 +1,43 @@
+//#region src/money/payment-method-kind.ts
+/**
+* Canonical payment method kinds — the universal vocabulary every
+* payment-aware package speaks (`@classytic/invoice`, `@classytic/revenue`,
+* `@classytic/order`, future POS / AP / subscription packages, …).
+*
+* **Kind vs code.** A `PaymentMethodKind` is the universal category
+* (every payment system on earth has these). A `methodCode` is the
+* host-specific string registered in a host's `PaymentMethod` registry
+* (`'bkash'`, `'nagad'`, `'stripe_card'`, `'cash_register_3'`). Packages
+* speak `kind`; hosts speak `code`. The pair lets UIs branch on kind
+* (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",
+	MANUAL: "manual",
+	OTHER: "other"
+};
+const KIND_VALUES = new Set(Object.values(PAYMENT_METHOD_KIND));
+const isPaymentMethodKind = (value) => typeof value === "string" && KIND_VALUES.has(value);
+//#endregion
+export { PAYMENT_METHOD_KIND, isPaymentMethodKind };

package/dist/status-history.d.mts

@@ -11,10 +11,9 @@
  * Pairs naturally with `state-machine`: the machine decides if a transition
  * is legal; this helper records the move that happened.
  *
- * Frappe's "status change log" with `duration_in_prior_status` was the
- * inspiration — funnel velocity reports (avg time spent in "Qualification")
- * are free when you store the duration at write time instead of recomputing
- * from raw timestamps later.
+ * Recording `durationInPriorMs` at write time means funnel-velocity reports
+ * (avg time spent in "Qualification") fall out of a single field instead of
+ * a re-walk over raw timestamps later.
  *
  * @example
  *   import { appendStatus, type StatusHistory } from '@classytic/primitives/status-history';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -97,6 +97,18 @@
       "types": "./dist/payment-gateway.d.mts",
       "default": "./dist/payment-gateway.mjs"
     },
+    "./payment-method-kind": {
+      "types": "./dist/payment-method-kind.d.mts",
+      "default": "./dist/payment-method-kind.mjs"
+    },
+    "./payment-allocation-status": {
+      "types": "./dist/payment-allocation-status.d.mts",
+      "default": "./dist/payment-allocation-status.mjs"
+    },
+    "./payment-events": {
+      "types": "./dist/payment-events.d.mts",
+      "default": "./dist/payment-events.mjs"
+    },
     "./phone": {
       "types": "./dist/phone.d.mts",
       "default": "./dist/phone.mjs"