@classytic/primitives 0.19.0 → 0.21.0

package/dist/money.mjs

@@ -1,4 +1,4 @@
-import { minorUnitFactor } from "./currency.mjs";
+import { CurrencyMismatchError, currencyCode, isCurrencyCode, minorUnitFactor } from "./currency.mjs";
 //#region src/money/money.ts
 /**
 * Cast a raw number to {@link MinorUnits}. Pass the currency as the second
@@ -12,26 +12,17 @@ import { minorUnitFactor } from "./currency.mjs";
 function MinorUnits(amount, _currency) {
 	return amount;
 }
-var CurrencyMismatchError = class extends Error {
-	name = "CurrencyMismatchError";
-	left;
-	right;
-	constructor(left, right) {
-		super(`Currency mismatch: ${left} vs ${right}`);
-		this.left = left;
-		this.right = right;
-	}
-};
 /**
 * Construct {@link Money} from an integer minor-unit amount.
 *
 * @throws TypeError if `amount` is not a finite integer.
+* @throws InvalidCurrencyCodeError if `currency` is not ISO 4217 format.
 */
 function money(amount, currency) {
 	if (!Number.isFinite(amount) || !Number.isInteger(amount)) throw new TypeError(`Money.amount must be a finite integer in minor units, got ${amount}`);
 	return {
 		amount,
-		currency
+		currency: currencyCode(currency)
 	};
 }
 /**
@@ -60,7 +51,7 @@ function fromMajor(major, currency) {
 	const cleaned = Number(raw.toPrecision(15));
 	return {
 		amount: Math.round(Math.abs(cleaned)) * (cleaned < 0 ? -1 : 1),
-		currency
+		currency: currencyCode(currency)
 	};
 }
 /** Convert {@link Money} back to its major-unit floating-point representation. */
@@ -100,7 +91,7 @@ function multiplyMoney(m, scalar) {
 function sumMoney(values, currency) {
 	return values.reduce((acc, v) => addMoney(acc, v), {
 		amount: 0,
-		currency
+		currency: currencyCode(currency)
 	});
 }
 /** Strict equality (amount and currency both match). */
@@ -180,7 +171,7 @@ function formatMinorUnits(minor, minorUnitDecimals = 2) {
 }
 /** Structural type guard. */
 function isMoney(value) {
-	return typeof value === "object" && value !== null && typeof value.amount === "number" && Number.isInteger(value.amount) && typeof value.currency === "string";
+	return typeof value === "object" && value !== null && typeof value.amount === "number" && Number.isInteger(value.amount) && isCurrencyCode(value.currency);
 }
 //#endregion
 export { CurrencyMismatchError, MinorUnits, absMoney, addMoney, compareMoney, equalsMoney, formatMinorUnits, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, majorToMinorUnits, minorUnitsToMajor, money, multiplyMoney, negateMoney, percentOfMinor, subtractMoney, sumMoney, toMajor };

package/dist/otp.mjs

@@ -26,7 +26,7 @@ import { createHmac, randomInt, timingSafeEqual } from "node:crypto";
 * modeled here so the verify primitive stays stateless between attempts.
 */
 const DEFAULT_LENGTH = 6;
-const DEFAULT_TTL_MS = 300 * 1e3;
+const DEFAULT_TTL_MS = 3e5;
 const DEFAULT_MAX_ATTEMPTS = 5;
 function hmac(code, secret) {
 	return createHmac("sha256", secret).update(code).digest("hex");

package/dist/outbox.d.mts

@@ -1,5 +1,4 @@
 import { DeadLetteredEvent, DomainEvent } from "./events.mjs";
-
 //#region src/events/outbox.d.ts
 /**
  * Options passed to {@link OutboxStore.save} for richer write semantics.
@@ -157,6 +156,19 @@ declare class InvalidOutboxEventError extends Error {
  *    `claimPending`.** If the underlying storage has corrupt rows, the
  *    store is responsible for quarantining them.
  */
+/**
+ * The delivery states an outbox row can hold.
+ *
+ * Named HERE, in the contract, rather than in each store. It went unnamed while every
+ * method took an event id and none took a state — `countByStatus` is the first member
+ * that makes the vocabulary part of the interface, and two stores had already written
+ * the same three strings independently by then.
+ *
+ * `dead_letter` is terminal until an operator calls `requeue`; it is a durable statement
+ * that something is owed, not a deletion.
+ */
+declare const OUTBOX_STATUSES: readonly ["pending", "delivered", "dead_letter"];
+type OutboxStatus = (typeof OUTBOX_STATUSES)[number];
 interface OutboxStore {
   /**
    * Declares that `save` ENLISTS `options.session` in the caller's transaction,
@@ -242,6 +254,41 @@ interface OutboxStore {
    * @returns Number of purged events.
    */
   purge?(olderThanMs: number): Promise<number>;
+  /**
+   * Re-drive ONE dead-lettered event: back to `pending`, attempts reset, lease cleared,
+   * immediately visible.
+   *
+   * The other half of `fail({ deadLetter: true })`. Dead-lettering is only a durable
+   * statement that something is owed; a store that can dead-letter but not requeue leaves
+   * an operator who has fixed the root cause with no way to act on the worklist except
+   * hand-editing rows in the database.
+   *
+   * MUST be scoped to `dead_letter` — requeuing a `pending` row would reset the attempt
+   * count on an event that is merely backing off, defeating the retry policy, and
+   * requeuing a `delivered` row would republish an event every subscriber already saw.
+   *
+   * @returns `true` if a dead-lettered event was requeued, `false` if no such event
+   *   exists — NOT an error. An operator re-driving a worklist races the relay, and an
+   *   id that has already been dealt with is an ordinary outcome.
+   */
+  requeue?(eventId: string): Promise<boolean>;
+  /**
+   * How many events are in `status`. The health surface behind an operator dashboard or
+   * an alert (`dead_letter > 0` means money or access may be unrecorded).
+   */
+  countByStatus?(status: OutboxStatus): Promise<number>;
+  /**
+   * Age in ms of the OLDEST pending event, or `null` when nothing is pending.
+   *
+   * The single most useful outbox health signal, and the one a naive dashboard misses: a
+   * pending COUNT looks identical whether the queue is draining briskly or has been
+   * wedged for an hour behind one poison row. Age distinguishes them.
+   *
+   * Measured from the event's creation, not its last attempt — the question being asked
+   * is "how long has this event gone undelivered", and resetting the clock on each retry
+   * would make a permanently-failing row look permanently fresh.
+   */
+  oldestPendingAgeMs?(): Promise<number | null>;
 }
 //#endregion
-export { InvalidOutboxEventError, OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxErrorInfo, OutboxFailOptions, OutboxFailureContext, OutboxFailureDecision, OutboxFailurePolicy, OutboxOwnershipError, OutboxStore, OutboxWriteOptions };
+export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxErrorInfo, OutboxFailOptions, OutboxFailureContext, OutboxFailureDecision, OutboxFailurePolicy, OutboxOwnershipError, OutboxStatus, OutboxStore, OutboxWriteOptions };

package/dist/outbox.mjs

@@ -26,5 +26,68 @@ var InvalidOutboxEventError = class extends Error {
 		super(`Invalid outbox event: ${reason}`);
 	}
 };
+/**
+* Durable storage contract for the transactional outbox pattern.
+*
+* **Required methods**: `save`, `getPending`, `acknowledge`.
+*
+* **Optional capabilities** — stores opt-in to richer semantics:
+*
+*   - `claimPending` — lease-based work claim for multi-worker relay
+*   - `fail` — failure tracking with retry scheduling and dead-letter
+*   - `getDeadLettered` — typed DLQ replay surface
+*   - `purge` — acknowledged event cleanup
+*
+* Arc's runtime detects capabilities at runtime and degrades gracefully for
+* legacy stores that only implement the required methods.
+*
+* ## Required semantics
+*
+* Implementations MUST honor these contracts — arc's relay depends on them
+* for correctness of at-least-once delivery:
+*
+* 1. **`save` must reject invalid events.** If `event.type` or `event.meta.id`
+*    is missing/empty, throw — do not persist. Callers pre-validate but
+*    stores should defend against direct-save code paths.
+*
+* 2. **`claimPending` must be atomic.** Two workers calling `claimPending`
+*    concurrently must never receive the same event. SQL: `SELECT ... FOR
+*    UPDATE SKIP LOCKED`; Mongo: `findOneAndUpdate` with `{ leaseOwner:
+*    null }` in the match condition.
+*
+* 3. **`acknowledge` / `fail` must throw {@link OutboxOwnershipError} on
+*    ownership mismatch.** When `options.consumerId` is provided and does
+*    not match the current lease owner, throw — never silently no-op. The
+*    relay relies on this signal to avoid counting hijacked events as
+*    successfully relayed.
+*
+* 4. **`acknowledge` on an unknown `eventId` is a no-op.** Keeps the relay
+*    idempotent when the store has been purged or the event was manually
+*    removed. Do NOT throw `OutboxOwnershipError` in this case.
+*
+* 5. **`fail` must deterministically update lease/visibility.** On success,
+*    the event MUST become re-claimable (immediately or at `retryAt`) or
+*    transition to dead-letter. Lease owner should be cleared.
+*
+* 6. **Malformed events must never be returned by `getPending` /
+*    `claimPending`.** If the underlying storage has corrupt rows, the
+*    store is responsible for quarantining them.
+*/
+/**
+* The delivery states an outbox row can hold.
+*
+* Named HERE, in the contract, rather than in each store. It went unnamed while every
+* method took an event id and none took a state — `countByStatus` is the first member
+* that makes the vocabulary part of the interface, and two stores had already written
+* the same three strings independently by then.
+*
+* `dead_letter` is terminal until an operator calls `requeue`; it is a durable statement
+* that something is owed, not a deletion.
+*/
+const OUTBOX_STATUSES = [
+	"pending",
+	"delivered",
+	"dead_letter"
+];
 //#endregion
-export { InvalidOutboxEventError, OutboxOwnershipError };
+export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxOwnershipError };

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

@@ -20,8 +20,11 @@
  * 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`. */
+  /** 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
@@ -31,8 +34,11 @@ declare const PAYMENT_ALLOCATION_STATUS: {
 };
 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). */
+  /** 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

package/dist/payment-allocation-status.mjs

@@ -20,15 +20,29 @@
 * Zero runtime, zero deps.
 */
 const PAYMENT_ALLOCATION_STATUS = {
+	/** No portion of the payment has been applied to any obligation yet. */
 	UNALLOCATED: "unallocated",
+	/** Some of the payment is applied; remainder is available credit. */
 	PARTIAL: "partial",
+	/** Fully applied — `sum(allocations) === payment.totalAmount`. */
 	ALLOCATED: "allocated",
+	/**
+	* Sum of allocations exceeds the payment total — invariant violation
+	* that should be flagged for operator review, never silently accepted.
+	*/
 	OVER_ALLOCATED: "over_allocated"
 };
 const RECONCILIATION_STATUS = {
+	/** No bank statement line / settlement record has been linked yet. */
 	UNRECONCILED: "unreconciled",
+	/** Auto-matched to a `BankTransaction` by amount + date + reference. */
 	MATCHED: "matched",
+	/** Operator-confirmed match (auto-match failed or was overridden). */
 	MANUAL: "manual",
+	/**
+	* Match was contested — amount mismatch, duplicate claim, chargeback
+	* in flight. Halts further automated processing until resolved.
+	*/
 	DISPUTED: "disputed"
 };
 const ALLOCATION_VALUES = new Set(Object.values(PAYMENT_ALLOCATION_STATUS));

package/dist/payment-events.d.mts

@@ -1,6 +1,6 @@
-import { Money } from "./money.mjs";
+import { n as Money } from "./money-CfAvfNiM.mjs";
 import { PaymentMethodKind } from "./payment-method-kind.mjs";
-
+import { ProviderUnknownCause } from "./payment-gateway.mjs";
 //#region src/events/payment-events.d.ts
 /**
  * Canonical event-name constants. Packages SHOULD publish events
@@ -21,6 +21,19 @@ declare const PAYMENT_EVENT_TYPE: {
   readonly DISPUTE_WON: "payment.dispute_won";
   readonly DISPUTE_LOST: "payment.dispute_lost";
   readonly SETTLED: "payment.settled";
+  /**
+   * The provider command produced NO observable outcome — timeout, abort,
+   * network fault, or a provider that holds no record and refuses to guess.
+   *
+   * This member exists because the port contract (`ProviderCommandResult` in
+   * `/payment-gateway`) is three-valued — `confirmed | declined | unknown` —
+   * while this catalogue was two-valued. An adapter that hit the third case had
+   * nowhere to publish it, so the only shapes on the bus were SUCCEEDED and
+   * FAILED, and an unobserved outcome had to be forced into one of them.
+   * Forcing it into FAILED is the one that double-charges: it licenses a retry
+   * for a command that may already have moved money.
+   */
+  readonly UNKNOWN: "payment.unknown";
 };
 type PaymentEventType = (typeof PAYMENT_EVENT_TYPE)[keyof typeof PAYMENT_EVENT_TYPE];
 /**
@@ -30,6 +43,8 @@ type PaymentEventType = (typeof PAYMENT_EVENT_TYPE)[keyof typeof PAYMENT_EVENT_T
  * "money in flight" not "money received".
  */
 interface PaymentInitiatedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.INITIATED;
   /** Stable payment identifier owned by the emitting package. */
   paymentId: string;
   /**
@@ -57,6 +72,8 @@ interface PaymentInitiatedPayload {
  * downstream fulfilment unlocks.
  */
 interface PaymentSucceededPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.SUCCEEDED;
   paymentId: string;
   providerRef?: string;
   providerCode: string;
@@ -73,6 +90,8 @@ interface PaymentSucceededPayload {
  * overdue.
  */
 interface PaymentFailedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.FAILED;
   paymentId: string;
   providerRef?: string;
   providerCode: string;
@@ -93,6 +112,8 @@ interface PaymentFailedPayload {
  * itself (pre- or post-clearing, often due to operator error).
  */
 interface PaymentRefundedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.REFUNDED;
   paymentId: string;
   /** Refund identifier (separate from `paymentId`). */
   refundId: string;
@@ -116,6 +137,8 @@ interface PaymentRefundedPayload {
  * state.
  */
 interface PaymentReversedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.REVERSED;
   paymentId: string;
   providerRef?: string;
   providerCode: string;
@@ -136,6 +159,8 @@ interface PaymentReversedPayload {
  * ledger bridges and closes the audit loop.
  */
 interface PaymentReconciledPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.RECONCILED;
   /** Allocation identifier — NOT the payment id (a payment can have many). */
   allocationId: string;
   paymentId: string;
@@ -156,6 +181,8 @@ interface PaymentReconciledPayload {
  * "hold" from "settle"; consumers should NOT treat this as cleared funds.
  */
 interface PaymentAuthorizedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.AUTHORIZED;
   paymentId: string;
   providerRef?: string;
   providerCode: string;
@@ -173,6 +200,8 @@ interface PaymentAuthorizedPayload {
  * Pairs with {@link PaymentAuthorizedPayload} for two-phase flows.
  */
 interface PaymentCapturedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.CAPTURED;
   paymentId: string;
   providerRef?: string;
   providerCode: string;
@@ -191,6 +220,8 @@ interface PaymentCapturedPayload {
  * Authorisation hold released — uncaptured auth voided before settlement.
  */
 interface PaymentAuthVoidedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.AUTH_VOIDED;
   paymentId: string;
   providerRef?: string;
   providerCode: string;
@@ -205,6 +236,8 @@ interface PaymentAuthVoidedPayload {
  * payment. The merchant typically has a deadline to submit evidence.
  */
 interface PaymentDisputedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.DISPUTED;
   paymentId: string;
   /** Provider's dispute / chargeback id. */
   disputeId: string;
@@ -223,6 +256,8 @@ interface PaymentDisputedPayload {
 }
 /** Dispute resolved in merchant's favour — funds restored. */
 interface PaymentDisputeWonPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.DISPUTE_WON;
   paymentId: string;
   disputeId: string;
   providerRef?: string;
@@ -234,6 +269,8 @@ interface PaymentDisputeWonPayload {
 }
 /** Dispute resolved against merchant — funds permanently lost plus fee. */
 interface PaymentDisputeLostPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.DISPUTE_LOST;
   paymentId: string;
   disputeId: string;
   providerRef?: string;
@@ -251,6 +288,8 @@ interface PaymentDisputeLostPayload {
  * reconciliation in country-aware ledger bridges.
  */
 interface PaymentSettledPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.SETTLED;
   paymentId: string;
   providerRef?: string;
   providerCode: string;
@@ -265,7 +304,95 @@ interface PaymentSettledPayload {
   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;
+/**
+ * The provider command produced no observable outcome. **This is not a
+ * failure**, and it is not a success — it is the absence of an answer.
+ *
+ * The obligation's state is genuinely unknown: the capture may have landed at
+ * the gateway with the acknowledgement lost in transit. The ONLY correct
+ * reaction is to reconcile the payment's real status before acting. A blind
+ * retry is a double charge; marking it failed and releasing the order is a
+ * shipped-but-unpaid order. Both are silent.
+ *
+ * Consumers MUST NOT treat this as a terminal state. It is a prompt to go and
+ * find out, and it resolves later into `payment.succeeded` or `payment.failed`.
+ */
+interface PaymentUnknownPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.UNKNOWN;
+  paymentId: string;
+  providerRef?: string;
+  providerCode: string;
+  /** Which command went unanswered — the retry policy differs per verb. */
+  operation: 'create_intent' | 'verify' | 'authorize' | 'capture' | 'refund' | 'void';
+  /** The amount at stake, when the command carried one. */
+  amount?: Money;
+  methodKind?: PaymentMethodKind;
+  methodCode?: string;
+  /**
+   * NORMALIZED reason the outcome was not observed — mirrors
+   * `ProviderUnknownCause` from `/payment-gateway`. Never a raw vendor error
+   * string: this value is persisted and displayed, and vendor errors embed
+   * request URLs, tokens and body fragments.
+   */
+  causeCode: ProviderUnknownCause;
+  /** The idempotency key the command carried — what reconciliation asks with. */
+  idempotencyKey?: string;
+  occurredAt: Date;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Union of all payment event payload types.
+ *
+ * DISCRIMINATED on `eventType`. Before the discriminant existed,
+ * `PaymentInitiatedPayload` and `PaymentSucceededPayload` were structurally
+ * IDENTICAL — so a handler typed for "funds received" accepted "money in
+ * flight" with no error anywhere, and TypeScript could not tell them apart even
+ * in principle. Structural identity between two events that mean opposite
+ * things is precisely where a nominal tag has to carry the meaning.
+ */
+type PaymentEventPayload = PaymentInitiatedPayload | PaymentSucceededPayload | PaymentFailedPayload | PaymentRefundedPayload | PaymentReversedPayload | PaymentReconciledPayload | PaymentAuthorizedPayload | PaymentCapturedPayload | PaymentAuthVoidedPayload | PaymentDisputedPayload | PaymentDisputeWonPayload | PaymentDisputeLostPayload | PaymentSettledPayload | PaymentUnknownPayload;
+/** Event type → its payload. The lookup a typed publisher/handler pair needs. */
+interface PaymentEventPayloadMap {
+  'payment.initiated': PaymentInitiatedPayload;
+  'payment.succeeded': PaymentSucceededPayload;
+  'payment.failed': PaymentFailedPayload;
+  'payment.refunded': PaymentRefundedPayload;
+  'payment.reversed': PaymentReversedPayload;
+  'payment.reconciled': PaymentReconciledPayload;
+  'payment.authorized': PaymentAuthorizedPayload;
+  'payment.captured': PaymentCapturedPayload;
+  'payment.auth_voided': PaymentAuthVoidedPayload;
+  'payment.disputed': PaymentDisputedPayload;
+  'payment.dispute_won': PaymentDisputeWonPayload;
+  'payment.dispute_lost': PaymentDisputeLostPayload;
+  'payment.settled': PaymentSettledPayload;
+  'payment.unknown': PaymentUnknownPayload;
+}
+type Assert<T extends true> = T;
+/** Every declared event type has a payload in the map. */
+type _EveryTypeMapped = Assert<PaymentEventType extends keyof PaymentEventPayloadMap ? true : false>;
+/** The map declares no key that is not a real event type. */
+type _NoStrayMapKeys = Assert<keyof PaymentEventPayloadMap extends PaymentEventType ? true : false>;
+/** Each payload's own `eventType` literal matches the key it is filed under. */
+type _DiscriminantMatchesKey = Assert<{ [K in keyof PaymentEventPayloadMap]: PaymentEventPayloadMap[K] extends {
+  eventType: K;
+} ? true : false; }[keyof PaymentEventPayloadMap] extends true ? true : false>;
+type PaymentEventContractGuards = [_EveryTypeMapped, _NoStrayMapKeys, _DiscriminantMatchesKey];
+/**
+ * Narrow a payload by event type at RUNTIME, with the compile-time narrowing
+ * to match. `if (isPaymentEvent(PAYMENT_EVENT_TYPE.SUCCEEDED, p)) { … }` —
+ * inside the branch `p` is `PaymentSucceededPayload` and cannot be an
+ * initiated payload, which is the whole point of the discriminant.
+ */
+declare function isPaymentEvent<T extends PaymentEventType>(type: T, payload: PaymentEventPayload): payload is PaymentEventPayloadMap[T];
+/**
+ * Is this payload a CLEARED-FUNDS event?
+ *
+ * The named answer to the question that used to be answerable only by
+ * structural shape — and answered wrong, because `initiated` had the same
+ * shape. `captured` counts; `initiated`, `authorized` and `unknown` do not.
+ */
+declare function isFundsReceived(payload: PaymentEventPayload): boolean;
 //#endregion
-export { PAYMENT_EVENT_TYPE, PaymentAuthVoidedPayload, PaymentAuthorizedPayload, PaymentCapturedPayload, PaymentDisputeLostPayload, PaymentDisputeWonPayload, PaymentDisputedPayload, PaymentEventPayload, PaymentEventType, PaymentFailedPayload, PaymentInitiatedPayload, PaymentReconciledPayload, PaymentRefundedPayload, PaymentReversedPayload, PaymentSettledPayload, PaymentSucceededPayload };
+export { PAYMENT_EVENT_TYPE, PaymentAuthVoidedPayload, PaymentAuthorizedPayload, PaymentCapturedPayload, PaymentDisputeLostPayload, PaymentDisputeWonPayload, PaymentDisputedPayload, PaymentEventContractGuards, PaymentEventPayload, PaymentEventPayloadMap, PaymentEventType, PaymentFailedPayload, PaymentInitiatedPayload, PaymentReconciledPayload, PaymentRefundedPayload, PaymentReversedPayload, PaymentSettledPayload, PaymentSucceededPayload, PaymentUnknownPayload, isFundsReceived, isPaymentEvent };

package/dist/payment-events.mjs

@@ -17,7 +17,39 @@ const PAYMENT_EVENT_TYPE = {
 	DISPUTED: "payment.disputed",
 	DISPUTE_WON: "payment.dispute_won",
 	DISPUTE_LOST: "payment.dispute_lost",
-	SETTLED: "payment.settled"
+	SETTLED: "payment.settled",
+	/**
+	* The provider command produced NO observable outcome — timeout, abort,
+	* network fault, or a provider that holds no record and refuses to guess.
+	*
+	* This member exists because the port contract (`ProviderCommandResult` in
+	* `/payment-gateway`) is three-valued — `confirmed | declined | unknown` —
+	* while this catalogue was two-valued. An adapter that hit the third case had
+	* nowhere to publish it, so the only shapes on the bus were SUCCEEDED and
+	* FAILED, and an unobserved outcome had to be forced into one of them.
+	* Forcing it into FAILED is the one that double-charges: it licenses a retry
+	* for a command that may already have moved money.
+	*/
+	UNKNOWN: "payment.unknown"
 };
+/**
+* Narrow a payload by event type at RUNTIME, with the compile-time narrowing
+* to match. `if (isPaymentEvent(PAYMENT_EVENT_TYPE.SUCCEEDED, p)) { … }` —
+* inside the branch `p` is `PaymentSucceededPayload` and cannot be an
+* initiated payload, which is the whole point of the discriminant.
+*/
+function isPaymentEvent(type, payload) {
+	return payload.eventType === type;
+}
+/**
+* Is this payload a CLEARED-FUNDS event?
+*
+* The named answer to the question that used to be answerable only by
+* structural shape — and answered wrong, because `initiated` had the same
+* shape. `captured` counts; `initiated`, `authorized` and `unknown` do not.
+*/
+function isFundsReceived(payload) {
+	return payload.eventType === PAYMENT_EVENT_TYPE.SUCCEEDED || payload.eventType === PAYMENT_EVENT_TYPE.CAPTURED;
+}
 //#endregion
-export { PAYMENT_EVENT_TYPE };
+export { PAYMENT_EVENT_TYPE, isFundsReceived, isPaymentEvent };