@classytic/primitives 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -3,13 +3,33 @@
 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.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 +40,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 +56,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,141 @@
+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";
+};
+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;
+  /** `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;
+  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>;
+}
+/** Union of all payment event payload types — convenient for exhaustive switches. */
+type PaymentEventPayload = PaymentInitiatedPayload | PaymentSucceededPayload | PaymentFailedPayload | PaymentRefundedPayload | PaymentReversedPayload | PaymentReconciledPayload;
+//#endregion
+export { PAYMENT_EVENT_TYPE, PaymentEventPayload, PaymentEventType, PaymentFailedPayload, PaymentInitiatedPayload, PaymentReconciledPayload, PaymentRefundedPayload, PaymentReversedPayload, PaymentSucceededPayload };

package/dist/payment-events.mjs

@@ -0,0 +1,16 @@
+//#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"
+};
+//#endregion
+export { PAYMENT_EVENT_TYPE };

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

@@ -0,0 +1,36 @@
+//#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.
+ *
+ * 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. */
+  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,31 @@
+//#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.
+*
+* 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",
+	WALLET: "wallet",
+	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.0",
   "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"