@classytic/primitives 0.4.0 → 0.6.0

package/dist/currency-B4rSdN7D.d.mts

@@ -0,0 +1,110 @@
+import { t as Brand } from "./brand-LLXqoh5J.mjs";
+
+//#region src/money/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-B4rSdN7D.mjs";
 export { CURRENCIES, CurrencyCode, FxSnapshot, MINOR_UNIT_FACTOR, convertWithSnapshot, isCurrencyCode, isFxSnapshot, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };

package/dist/currency.mjs

@@ -1,4 +1,4 @@
-//#region src/currency.ts
+//#region src/money/currency.ts
 /**
 * Common ISO 4217 codes. Non-exhaustive — add more at the consumer level if
 * needed. Listed here because shared-types ships with these by default.

package/dist/events.d.mts

@@ -1,4 +1,4 @@
-//#region src/events.d.ts
+//#region src/events/events.d.ts
 /**
  * Domain event transport primitives.
  *

package/dist/events.mjs

@@ -1,4 +1,4 @@
-//#region src/events.ts
+//#region src/events/events.ts
 /**
 * Build a {@link DomainEvent} with auto-filled `id` + `timestamp`. All other
 * `EventMeta` fields are caller-controlled and override the defaults if

package/dist/hold.d.mts

@@ -1,4 +1,4 @@
-//#region src/hold.d.ts
+//#region src/workflow/hold.d.ts
 /**
  * Hold reason value object + collection helpers.
  *

package/dist/hold.mjs

@@ -1,4 +1,4 @@
-//#region src/hold.ts
+//#region src/workflow/hold.ts
 var HoldError = class extends Error {
 	name = "HoldError";
 	code;

package/dist/mixin.d.mts

@@ -0,0 +1,73 @@
+//#region src/composition/mixin.d.ts
+/**
+ * Additive composition for domain entities — without subclassing.
+ *
+ * Most mixin system (good idea, heavy implementation) lets a `Contact`
+ * become a `Contact & Customer` without rewriting the type or copying
+ * fields. We replicate the GOOD bit (additive type composition stored as
+ * nested data) with none of the bad bits (no decorators, no global class
+ * registry, no proxies).
+ *
+ * Pattern: store mixin payloads on a known well-typed key (`mixins.customer`,
+ * `mixins.lead-fit`, …) instead of spreading them onto the entity root. This
+ * keeps the base type stable and lets each mixin own its own keyspace —
+ * additive schema evolution without breaking exhaustiveness.
+ *
+ * @example
+ *   import { withMixin, getMixin, hasMixin } from '@classytic/primitives/mixin';
+ *
+ *   interface Contact { id: string; name: string; mixins?: Record<string, unknown>; }
+ *   interface CustomerFacts { lifetimeValue: number; firstOrderAt: Date; }
+ *
+ *   const c: Contact = { id: 'c1', name: 'Acme' };
+ *   const enriched = withMixin<Contact, 'customer', CustomerFacts>(c, 'customer', {
+ *     lifetimeValue: 9200,
+ *     firstOrderAt: new Date('2024-09-12'),
+ *   });
+ *
+ *   getMixin<CustomerFacts>(enriched, 'customer')?.lifetimeValue; // 9200
+ *   hasMixin(enriched, 'customer');                               // true
+ *
+ *   // Domain stays exhaustive — the base type didn't change, only the
+ *   // optional `mixins` namespace did.
+ */
+/**
+ * Marker interface — entities that participate in the mixin protocol declare
+ * `mixins?: Mixinable['mixins']`. Hosts can opt in retroactively by widening
+ * their existing types via intersection.
+ */
+interface Mixinable {
+  readonly mixins?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Result type: the base `T` with `mixins[K]` typed as `M`. The intersection
+ * keeps callers exhaustive over the original entity while exposing the
+ * mixin payload through a well-typed accessor.
+ */
+type WithMixin<T, K extends string, M> = T & {
+  readonly mixins: Readonly<Record<string, unknown>> & { readonly [P in K]: M };
+};
+/**
+ * Attach (or overwrite) a mixin on a base entity. Returns a NEW object —
+ * never mutates. The other mixins on the entity are preserved by spread.
+ *
+ * Type-level: caller picks the mixin key and the mixin payload shape; we
+ * intersect them into the return type so chained reads stay precise.
+ */
+declare function withMixin<T extends Mixinable, K extends string, M>(base: T, key: K, data: M): WithMixin<T, K, M>;
+/**
+ * Pull a mixin payload off an entity by key. Returns `null` (not `undefined`)
+ * so call sites can use `??` to fall through to a default without ambiguity
+ * with a real `undefined` field on the payload itself.
+ */
+declare function getMixin<M>(entity: Mixinable, key: string): M | null;
+/** Cheap presence check — useful for `if (hasMixin(c, 'customer')) …` branches. */
+declare function hasMixin(entity: Mixinable, key: string): boolean;
+/**
+ * Remove a mixin. Returns a new entity. No-op if the mixin isn't present.
+ * Useful for migrations / GDPR scrubs ("remove `customer` payload but keep
+ * the base `Contact` row").
+ */
+declare function withoutMixin<T extends Mixinable>(entity: T, key: string): T;
+//#endregion
+export { Mixinable, WithMixin, getMixin, hasMixin, withMixin, withoutMixin };

package/dist/mixin.mjs

@@ -0,0 +1,47 @@
+//#region src/composition/mixin.ts
+/**
+* Attach (or overwrite) a mixin on a base entity. Returns a NEW object —
+* never mutates. The other mixins on the entity are preserved by spread.
+*
+* Type-level: caller picks the mixin key and the mixin payload shape; we
+* intersect them into the return type so chained reads stay precise.
+*/
+function withMixin(base, key, data) {
+	return {
+		...base,
+		mixins: {
+			...base.mixins ?? {},
+			[key]: data
+		}
+	};
+}
+/**
+* Pull a mixin payload off an entity by key. Returns `null` (not `undefined`)
+* so call sites can use `??` to fall through to a default without ambiguity
+* with a real `undefined` field on the payload itself.
+*/
+function getMixin(entity, key) {
+	if (entity.mixins === void 0 || entity.mixins === null) return null;
+	const found = entity.mixins[key];
+	return found === void 0 ? null : found;
+}
+/** Cheap presence check — useful for `if (hasMixin(c, 'customer')) …` branches. */
+function hasMixin(entity, key) {
+	return entity.mixins !== void 0 && entity.mixins !== null && entity.mixins[key] !== void 0;
+}
+/**
+* Remove a mixin. Returns a new entity. No-op if the mixin isn't present.
+* Useful for migrations / GDPR scrubs ("remove `customer` payload but keep
+* the base `Contact` row").
+*/
+function withoutMixin(entity, key) {
+	if (!hasMixin(entity, key)) return entity;
+	const next = { ...entity.mixins };
+	delete next[key];
+	return {
+		...entity,
+		mixins: next
+	};
+}
+//#endregion
+export { getMixin, hasMixin, withMixin, withoutMixin };

package/dist/money.d.mts

@@ -1,6 +1,6 @@
-import { CurrencyCode } from "./currency.mjs";
+import { n as CurrencyCode } from "./currency-B4rSdN7D.mjs";
 
-//#region src/money.d.ts
+//#region src/money/money.d.ts
 /**
  * Wire-format monetary amount: integer minor units, branded with a phantom
  * currency type so calls like `formatBdt(usdValue)` fail at compile time.

package/dist/money.mjs

@@ -1,5 +1,5 @@
 import { minorUnitFactor } from "./currency.mjs";
-//#region src/money.ts
+//#region src/money/money.ts
 /**
 * Cast a raw number to {@link MinorUnits}. Pass the currency as the second
 * argument to fix the phantom type. With no second arg, `MinorUnits<string>`

package/dist/outbox.d.mts

@@ -1,6 +1,6 @@
 import { DeadLetteredEvent, DomainEvent } from "./events.mjs";
 
-//#region src/outbox.d.ts
+//#region src/events/outbox.d.ts
 /**
  * Options passed to {@link OutboxStore.save} for richer write semantics.
  * Stores may ignore fields they don't support — contract is best-effort.

package/dist/outbox.mjs

@@ -1,4 +1,4 @@
-//#region src/outbox.ts
+//#region src/events/outbox.ts
 /**
 * Thrown by a store when `acknowledge` / `fail` is called by a consumer that
 * does not own the event's current lease.

package/dist/payment-gateway.d.mts

@@ -0,0 +1,168 @@
+import { Money } from "./money.mjs";
+
+//#region src/money/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/dist/period.d.mts

@@ -1,4 +1,4 @@
-//#region src/period.d.ts
+//#region src/scheduling/period.d.ts
 /**
  * A closed date range `[start, end]`. Both endpoints inclusive — consumers
  * decide whether to treat them as `[start, end)` at the query layer.

package/dist/period.mjs

@@ -1,4 +1,4 @@
-//#region src/period.ts
+//#region src/scheduling/period.ts
 function isDateRange(value) {
 	return typeof value === "object" && value !== null && value.start instanceof Date && value.end instanceof Date;
 }

package/dist/person.d.mts

@@ -1,4 +1,4 @@
-//#region src/person.d.ts
+//#region src/identity/person.d.ts
 /**
  * Structured person name. Handles the parts most locales need; domains that
  * require more (per-locale honorifics, patronymics) extend from here.

package/dist/person.mjs

@@ -1,4 +1,4 @@
-//#region src/person.ts
+//#region src/identity/person.ts
 function formatFullName(name) {
 	return [
 		name.prefix,

package/dist/phone.d.mts

@@ -0,0 +1,47 @@
+import { Result } from "./result.mjs";
+
+//#region src/identity/phone.d.ts
+type PhoneErrorCode = 'EMPTY' | 'MISSING_PLUS' | 'NOT_E164' | 'TOO_SHORT' | 'TOO_LONG';
+declare class PhoneError extends Error {
+  readonly name = "PhoneError";
+  readonly code: PhoneErrorCode;
+  constructor(code: PhoneErrorCode, message: string);
+}
+/**
+ * Parsed phone number. Stored E.164 (always begins with `+`, digits only after).
+ * `callingCode` is the 1–3 digit country dial code (`'1'` US, `'44'` UK,
+ * `'880'` BD, etc.) — useful for routing without re-parsing.
+ *
+ * Construction goes through `parsePhone()` (never assemble by hand) so the
+ * invariants are guaranteed by the parser.
+ */
+interface PhoneNumber {
+  readonly e164: string;
+  readonly callingCode: string;
+  /** The national-number portion (digits after the calling code). */
+  readonly nationalNumber: string;
+}
+/**
+ * Parse free-form phone input into a normalized `PhoneNumber`. Accepts:
+ *   - `'+14155550182'`           → e164 unchanged
+ *   - `'+1 (415) 555-0182'`     → strips spaces / punctuation
+ *   - `'+1.415.555.0182'`        → strips dots
+ *
+ * Rejects anything without a leading `+` — we don't guess the country.
+ * If the host knows the user's region, prepend the code before calling.
+ */
+declare function parsePhone(input: string): Result<PhoneNumber, PhoneError>;
+/** Convenience: returns the E.164 string. Useful when piping to a transport. */
+declare function formatPhone(phone: PhoneNumber): string;
+/**
+ * Best-effort national-format render: groups the national number into 3-digit
+ * blocks. Not locale-aware — for display polish, hosts should format per
+ * region. Useful as a default in admin UIs.
+ *
+ * @example formatNational(parsePhone('+14155550182').value!) → '+1 415 555 0182'
+ */
+declare function formatNational(phone: PhoneNumber): string;
+/** Type guard. */
+declare function isPhoneNumber(value: unknown): value is PhoneNumber;
+//#endregion
+export { PhoneError, PhoneErrorCode, PhoneNumber, formatNational, formatPhone, isPhoneNumber, parsePhone };