@classytic/primitives 0.18.0 → 0.20.0

package/dist/money-DPo9fLBi.d.mts

@@ -0,0 +1,347 @@
+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, by ISO 4217 code.
+ *
+ * **This table must list EVERY currency whose exponent is not 2.** ISO 4217
+ * defaults to 2 decimals, and {@link minorUnitFactor} falls back to 100 for a
+ * code it does not know — which is correct for the ~150 two-decimal currencies
+ * and catastrophically wrong for the others. A missing zero-decimal entry does
+ * not throw: it makes `fromMajor(1500, 'GNF')` store 150 000 minor units, a
+ * 100× error that reads as a plausible number all the way to the gateway.
+ *
+ * So the exceptions are enumerated EXHAUSTIVELY (all 0-, 3- and 4-decimal
+ * codes), leaving the `?? 100` fallback reachable only by a code that is not a
+ * real ISO 4217 currency — a typo, a lowercased code, or a placeholder. The
+ * two-decimal entries below are redundant with the default and kept only as
+ * documentation of the common set.
+ */
+declare const MINOR_UNIT_FACTOR: Readonly<Record<string, number>>;
+/**
+ * ISO 4217 format — 3 uppercase letters. Exported so consumers can embed
+ * the SAME pattern in JSON-Schema-representable validators (zod `.regex`,
+ * Mongoose `match`, OpenAPI `pattern`) instead of hand-rolling a copy:
+ * `.refine(isCurrencyCode)` validates at runtime but is dropped by
+ * `z.toJSONSchema`, losing the constraint from generated API docs.
+ * `isCurrencyCode` / `toCurrencyCode` remain the runtime API.
+ */
+declare const CURRENCY_PATTERN: RegExp;
+/**
+ * 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;
+/**
+ * Validate + brand, or throw. The constructor form — same relationship to
+ * {@link toCurrencyCode} that `civilDate` has to `isCivilDate`.
+ *
+ * `Money` carries a {@link CurrencyCode}, not a bare string, and this is where
+ * an untrusted value earns the brand. Rejecting `'jpy'` here matters: lowercase
+ * misses {@link MINOR_UNIT_FACTOR}, so it silently becomes a 2-decimal currency
+ * and every JPY amount is off by 100×.
+ */
+declare function currencyCode(value: string): CurrencyCode;
+declare class InvalidCurrencyCodeError extends Error {
+  readonly name = "InvalidCurrencyCodeError";
+  readonly value: string;
+  constructor(value: string);
+}
+/**
+ * Raised when an operation combines two currencies.
+ *
+ * Declared HERE rather than in `/money` so the FX seam below can throw it
+ * without a runtime import back into `/money` (which imports
+ * {@link minorUnitFactor} from this file). `/money` re-exports it, so
+ * `import { CurrencyMismatchError } from '@classytic/primitives/money'` still
+ * resolves.
+ */
+declare class CurrencyMismatchError extends Error {
+  readonly name = "CurrencyMismatchError";
+  readonly left: string;
+  readonly right: string;
+  constructor(left: string, right: string);
+}
+/** Type predicate for `unknown` input. */
+declare function isCurrencyCode(value: unknown): value is CurrencyCode;
+/**
+ * Minor units per major unit (100 for USD, 1 for JPY, 1000 for KWD, 10 000 for CLF).
+ *
+ * Falls back to 100 for an unlisted code — the ISO 4217 default exponent. Because
+ * {@link MINOR_UNIT_FACTOR} enumerates every non-2-decimal currency, that fallback
+ * is now only reached by codes that are not ISO 4217 currencies at all; use
+ * {@link isKnownCurrency} at a config/boot boundary if you need to reject those
+ * rather than assume two decimals for them.
+ */
+declare function minorUnitFactor(currency: string): number;
+/**
+ * Does {@link MINOR_UNIT_FACTOR} carry an explicit exponent for this code?
+ *
+ * `false` means {@link minorUnitFactor} would ASSUME two decimals. That
+ * assumption is right for an ordinary ISO 4217 code and wrong by 100× for a
+ * mistyped or lowercased one (`'jpy'`), so a boot-time config validator that
+ * accepts an operator-supplied currency should gate on this instead of letting
+ * the default answer for it.
+ */
+declare function isKnownCurrency(currency: string): boolean;
+/**
+ * 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;
+}
+/**
+ * How to land a converted amount on an integer number of minor units.
+ * Required to be deterministic and named, never implicit — the old signature
+ * returned an unrounded float and left the choice to whoever persisted it, so
+ * two call sites rounding differently produced two answers for one conversion.
+ */
+type FxRounding = 'half-away-from-zero' | 'floor' | 'ceil';
+/**
+ * Apply an {@link FxSnapshot} to a source-currency amount.
+ *
+ * ## Why this takes `Money` and not a number
+ *
+ * It used to take a bare `number`, which meant nothing could check the amount
+ * was denominated in `fx.sourceCurrency`. Applying a USD→BDT snapshot to a EUR
+ * amount type-checked, ran, and returned a plausible wrong number — the
+ * arithmetic is identical, only the meaning is wrong, so no test that asserts a
+ * total would notice. Taking `Money` lets the seam enforce its own
+ * precondition: a mismatch throws {@link CurrencyMismatchError}.
+ *
+ * ## Minor-unit exponents are handled
+ *
+ * The rate is quoted in MAJOR units (1 source = `rate` base), while `Money`
+ * holds minor units, and the two currencies need not share an exponent
+ * (USD has 2, JPY has 0). The conversion therefore goes
+ * `minor → major → ×rate → base minor`, not a naive `amount × rate`, which is
+ * off by 100× for any pair whose exponents differ.
+ */
+declare function convertWithSnapshot(source: Money, fx: FxSnapshot, options?: {
+  rounding?: FxRounding;
+}): Money;
+/**
+ * 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.
+ *
+ * Symmetrically guarded: a base amount that is not in `fx.baseCurrency` throws
+ * rather than dividing by a rate that does not describe it.
+ */
+declare function reverseWithSnapshot(base: Money, fx: FxSnapshot, options?: {
+  rounding?: FxRounding;
+}): Money;
+/**
+ * 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
+//#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.
+ *
+ * Use this for HTTP/JSON fields where transmitting a `Money` struct would be
+ * overkill: `interface Order { grandTotal: MinorUnits<'BDT'>; ... }`. Pair
+ * with the structured {@link Money} for in-process arithmetic.
+ *
+ * Erases at runtime — branded types have zero cost.
+ *
+ * @example
+ * type Paisa = MinorUnits<'BDT'>;
+ * type UsdCents = MinorUnits<'USD'>;
+ * const p: Paisa = MinorUnits(489900, 'BDT');
+ * const c: UsdCents = p; // ❌ type error: BDT vs USD
+ */
+declare const __unitBrand: unique symbol;
+declare const __currencyBrand: unique symbol;
+type MinorUnits<C extends string = string> = number & {
+  readonly [__unitBrand]: 'minor';
+  readonly [__currencyBrand]: C;
+};
+/**
+ * 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>`
+ * — useful for generic SDK boundaries that don't know the currency yet.
+ *
+ * @example
+ * MinorUnits(489900, 'BDT')   // typed MinorUnits<'BDT'>
+ * MinorUnits(199, 'USD')      // typed MinorUnits<'USD'>
+ */
+declare function MinorUnits<C extends string = string>(amount: number, _currency?: C): MinorUnits<C>;
+/**
+ * A monetary amount stored as an integer in the currency's minor unit.
+ *
+ * Examples:
+ *  - `{ amount: 19_99,   currency: 'USD' }` — 19.99 USD (2 decimals)
+ *  - `{ amount: 1_500,   currency: 'JPY' }` — 1500 JPY (0 decimals)
+ *  - `{ amount: 500_000, currency: 'KWD' }` — 500.000 KWD (3 decimals)
+ *
+ * Storing as integers avoids IEEE 754 rounding across arithmetic. Never store
+ * `Money.amount` as a float.
+ *
+ * ## `currency` is a branded {@link CurrencyCode}, not a string
+ *
+ * It was declared `CurrencyCode | string`, and a union with `string` collapses
+ * TO `string` — so the brand was decoration on the one type in the package
+ * where it matters, and `money()` validated nothing. Any string reached the
+ * field: `'jpy'`, `''`, `'US Dollar'`, a mistyped `'BTD'`. None of those are in
+ * {@link MINOR_UNIT_FACTOR}, so `minorUnitFactor` assumes two decimals for them
+ * and every JPY-style amount is 100× wrong while looking perfectly ordinary.
+ *
+ * Construct through {@link money} / {@link fromMajor} (which validate and
+ * brand) or through `currencyCode()` at your own boundary. A raw object literal
+ * `{ amount, currency: someString }` is now a compile error — deliberately, so
+ * the validation cannot be bypassed by the shape that skipped it before.
+ */
+interface Money {
+  readonly amount: number;
+  readonly currency: CurrencyCode;
+}
+/**
+ * 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.
+ */
+declare function money(amount: number, currency: string): Money;
+/**
+ * Construct {@link Money} from a major-unit number (e.g. dollars, taka) by
+ * scaling to the currency's minor unit and rounding half-away-from-zero.
+ *
+ * Uses `toPrecision(15)` to strip the trailing-bit noise that appears in
+ * multiply-then-round (e.g. `0.1 + 0.2 = 0.30000000000000004`). This is
+ * enough for the vast majority of decimals encountered in real-world pricing.
+ *
+ * **Precision caveat.** A handful of decimals cannot be represented exactly
+ * in IEEE 754 and will round to the IEEE-closest integer rather than the
+ * mathematically-expected one — e.g. `1.005` is stored as `1.00499999…` and
+ * rounds to `100` minor units, not `101`. If you need decimal-exact rounding,
+ * construct money from a string or use integer minor units directly via
+ * {@link money}.
+ *
+ * @example
+ * fromMajor(19.99, 'USD')      // { amount: 1999, currency: 'USD' }
+ * fromMajor(0.1 + 0.2, 'USD')  // { amount: 30,   currency: 'USD' }
+ * fromMajor(1500,  'JPY')      // { amount: 1500, currency: 'JPY' }
+ */
+declare function fromMajor(major: number, currency: string): Money;
+/** Convert {@link Money} back to its major-unit floating-point representation. */
+declare function toMajor(m: Money): number;
+declare function addMoney(a: Money, b: Money): Money;
+declare function subtractMoney(a: Money, b: Money): Money;
+/**
+ * Multiply money by a scalar. The result is rounded to an integer number of
+ * minor units using half-away-from-zero rounding.
+ */
+declare function multiplyMoney(m: Money, scalar: number): Money;
+/** Sum a list of {@link Money}. Returns zero in the given currency for empty input. */
+declare function sumMoney(values: readonly Money[], currency: string): Money;
+/** Strict equality (amount and currency both match). */
+declare function equalsMoney(a: Money, b: Money): boolean;
+/**
+ * Ordering predicate. Returns -1, 0, or 1. Throws on currency mismatch — use
+ * {@link equalsMoney} for a total equality check across currencies.
+ */
+declare function compareMoney(a: Money, b: Money): -1 | 0 | 1;
+declare function isZeroMoney(m: Money): boolean;
+declare function isPositiveMoney(m: Money): boolean;
+declare function isNegativeMoney(m: Money): boolean;
+declare function negateMoney(m: Money): Money;
+declare function absMoney(m: Money): Money;
+/**
+ * Decimal major-unit number → integer minor units by decimal exponent.
+ * Rounding: raw IEEE `Math.round` — half-up toward +∞ (so `-10.5 → -10`),
+ * documented above. Throws when the result leaves the safe-integer range
+ * (also catches `NaN`/`Infinity` inputs).
+ *
+ * @example
+ * majorToMinorUnits(10.5)      // 1050
+ * majorToMinorUnits(1000, 0)   // 1000 (JPY-style)
+ * majorToMinorUnits(1.005)     // 100 — IEEE, see note above
+ */
+declare function majorToMinorUnits(major: number, minorUnitDecimals?: number): number;
+/** Integer minor units → decimal major-unit number by decimal exponent: `1050 → 10.5`. */
+declare function minorUnitsToMajor(minor: number, minorUnitDecimals?: number): number;
+/**
+ * Percentage of an integer minor-unit amount → integer minor units.
+ * EXACT multiply-then-round: `Math.round((minor × ratePercent) / 100)` —
+ * one rounding point, half-up toward +∞. Handles genuinely fractional rates
+ * (QST 9.975 %) without precision loss: `percentOfMinor(20000, 9.975) === 1995`.
+ *
+ * Hosts whose domain guarantees at-most-2-decimal rates MAY snap the rate to
+ * integer basis points BEFORE calling (be-prod's `#shared/money` seam does) —
+ * that is host policy layered on top, not part of this primitive.
+ */
+declare function percentOfMinor(minor: number, ratePercent: number): number;
+/**
+ * Integer minor units → plain decimal string (no currency symbol, no locale):
+ * `formatMinorUnits(10550) → "105.50"`, `formatMinorUnits(1000, 0) → "1000"`.
+ * For localized currency strings use `Intl.NumberFormat` at the display layer.
+ */
+declare function formatMinorUnits(minor: number, minorUnitDecimals?: number): string;
+/** Structural type guard. */
+declare function isMoney(value: unknown): value is Money;
+//#endregion
+export { convertWithSnapshot as A, CURRENCY_PATTERN as C, FxSnapshot as D, FxRounding as E, minorUnitFactor as F, reverseWithSnapshot as I, toCurrencyCode as L, isCurrencyCode as M, isFxSnapshot as N, InvalidCurrencyCodeError as O, isKnownCurrency as P, CURRENCIES as S, CurrencyMismatchError as T, negateMoney as _, compareMoney as a, sumMoney as b, fromMajor as c, isPositiveMoney as d, isZeroMoney as f, multiplyMoney as g, money as h, addMoney as i, currencyCode as j, MINOR_UNIT_FACTOR as k, isMoney as l, minorUnitsToMajor as m, Money as n, equalsMoney as o, majorToMinorUnits as p, absMoney as r, formatMinorUnits as s, MinorUnits as t, isNegativeMoney as u, percentOfMinor as v, CurrencyCode as w, toMajor as x, subtractMoney as y };

package/dist/money.d.mts

@@ -1,141 +1,2 @@
-import { r as CurrencyCode } from "./currency-BCJnJBlb.mjs";
-
-//#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.
- *
- * Use this for HTTP/JSON fields where transmitting a `Money` struct would be
- * overkill: `interface Order { grandTotal: MinorUnits<'BDT'>; ... }`. Pair
- * with the structured {@link Money} for in-process arithmetic.
- *
- * Erases at runtime — branded types have zero cost.
- *
- * @example
- * type Paisa = MinorUnits<'BDT'>;
- * type UsdCents = MinorUnits<'USD'>;
- * const p: Paisa = MinorUnits(489900, 'BDT');
- * const c: UsdCents = p; // ❌ type error: BDT vs USD
- */
-declare const __unitBrand: unique symbol;
-declare const __currencyBrand: unique symbol;
-type MinorUnits<C extends string = string> = number & {
-  readonly [__unitBrand]: 'minor';
-  readonly [__currencyBrand]: C;
-};
-/**
- * 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>`
- * — useful for generic SDK boundaries that don't know the currency yet.
- *
- * @example
- * MinorUnits(489900, 'BDT')   // typed MinorUnits<'BDT'>
- * MinorUnits(199, 'USD')      // typed MinorUnits<'USD'>
- */
-declare function MinorUnits<C extends string = string>(amount: number, _currency?: C): MinorUnits<C>;
-/**
- * A monetary amount stored as an integer in the currency's minor unit.
- *
- * Examples:
- *  - `{ amount: 19_99,   currency: 'USD' }` — 19.99 USD (2 decimals)
- *  - `{ amount: 1_500,   currency: 'JPY' }` — 1500 JPY (0 decimals)
- *  - `{ amount: 500_000, currency: 'KWD' }` — 500.000 KWD (3 decimals)
- *
- * Storing as integers avoids IEEE 754 rounding across arithmetic. Never store
- * `Money.amount` as a float.
- */
-interface Money {
-  readonly amount: number;
-  readonly currency: CurrencyCode | string;
-}
-declare class CurrencyMismatchError extends Error {
-  readonly name = "CurrencyMismatchError";
-  readonly left: string;
-  readonly right: string;
-  constructor(left: string, right: string);
-}
-/**
- * Construct {@link Money} from an integer minor-unit amount.
- *
- * @throws TypeError if `amount` is not a finite integer.
- */
-declare function money(amount: number, currency: string): Money;
-/**
- * Construct {@link Money} from a major-unit number (e.g. dollars, taka) by
- * scaling to the currency's minor unit and rounding half-away-from-zero.
- *
- * Uses `toPrecision(15)` to strip the trailing-bit noise that appears in
- * multiply-then-round (e.g. `0.1 + 0.2 = 0.30000000000000004`). This is
- * enough for the vast majority of decimals encountered in real-world pricing.
- *
- * **Precision caveat.** A handful of decimals cannot be represented exactly
- * in IEEE 754 and will round to the IEEE-closest integer rather than the
- * mathematically-expected one — e.g. `1.005` is stored as `1.00499999…` and
- * rounds to `100` minor units, not `101`. If you need decimal-exact rounding,
- * construct money from a string or use integer minor units directly via
- * {@link money}.
- *
- * @example
- * fromMajor(19.99, 'USD')      // { amount: 1999, currency: 'USD' }
- * fromMajor(0.1 + 0.2, 'USD')  // { amount: 30,   currency: 'USD' }
- * fromMajor(1500,  'JPY')      // { amount: 1500, currency: 'JPY' }
- */
-declare function fromMajor(major: number, currency: string): Money;
-/** Convert {@link Money} back to its major-unit floating-point representation. */
-declare function toMajor(m: Money): number;
-declare function addMoney(a: Money, b: Money): Money;
-declare function subtractMoney(a: Money, b: Money): Money;
-/**
- * Multiply money by a scalar. The result is rounded to an integer number of
- * minor units using half-away-from-zero rounding.
- */
-declare function multiplyMoney(m: Money, scalar: number): Money;
-/** Sum a list of {@link Money}. Returns zero in the given currency for empty input. */
-declare function sumMoney(values: readonly Money[], currency: string): Money;
-/** Strict equality (amount and currency both match). */
-declare function equalsMoney(a: Money, b: Money): boolean;
-/**
- * Ordering predicate. Returns -1, 0, or 1. Throws on currency mismatch — use
- * {@link equalsMoney} for a total equality check across currencies.
- */
-declare function compareMoney(a: Money, b: Money): -1 | 0 | 1;
-declare function isZeroMoney(m: Money): boolean;
-declare function isPositiveMoney(m: Money): boolean;
-declare function isNegativeMoney(m: Money): boolean;
-declare function negateMoney(m: Money): Money;
-declare function absMoney(m: Money): Money;
-/**
- * Decimal major-unit number → integer minor units by decimal exponent.
- * Rounding: raw IEEE `Math.round` — half-up toward +∞ (so `-10.5 → -10`),
- * documented above. Throws when the result leaves the safe-integer range
- * (also catches `NaN`/`Infinity` inputs).
- *
- * @example
- * majorToMinorUnits(10.5)      // 1050
- * majorToMinorUnits(1000, 0)   // 1000 (JPY-style)
- * majorToMinorUnits(1.005)     // 100 — IEEE, see note above
- */
-declare function majorToMinorUnits(major: number, minorUnitDecimals?: number): number;
-/** Integer minor units → decimal major-unit number by decimal exponent: `1050 → 10.5`. */
-declare function minorUnitsToMajor(minor: number, minorUnitDecimals?: number): number;
-/**
- * Percentage of an integer minor-unit amount → integer minor units.
- * EXACT multiply-then-round: `Math.round((minor × ratePercent) / 100)` —
- * one rounding point, half-up toward +∞. Handles genuinely fractional rates
- * (QST 9.975 %) without precision loss: `percentOfMinor(20000, 9.975) === 1995`.
- *
- * Hosts whose domain guarantees at-most-2-decimal rates MAY snap the rate to
- * integer basis points BEFORE calling (be-prod's `#shared/money` seam does) —
- * that is host policy layered on top, not part of this primitive.
- */
-declare function percentOfMinor(minor: number, ratePercent: number): number;
-/**
- * Integer minor units → plain decimal string (no currency symbol, no locale):
- * `formatMinorUnits(10550) → "105.50"`, `formatMinorUnits(1000, 0) → "1000"`.
- * For localized currency strings use `Intl.NumberFormat` at the display layer.
- */
-declare function formatMinorUnits(minor: number, minorUnitDecimals?: number): string;
-/** Structural type guard. */
-declare function isMoney(value: unknown): value is Money;
-//#endregion
+import { T as CurrencyMismatchError, _ as negateMoney, a as compareMoney, b as sumMoney, c as fromMajor, d as isPositiveMoney, f as isZeroMoney, g as multiplyMoney, h as money, i as addMoney, l as isMoney, m as minorUnitsToMajor, n as Money, o as equalsMoney, p as majorToMinorUnits, r as absMoney, s as formatMinorUnits, t as MinorUnits, u as isNegativeMoney, v as percentOfMinor, x as toMajor, y as subtractMoney } from "./money-DPo9fLBi.mjs";
 export { CurrencyMismatchError, MinorUnits, Money, absMoney, addMoney, compareMoney, equalsMoney, formatMinorUnits, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, majorToMinorUnits, minorUnitsToMajor, money, multiplyMoney, negateMoney, percentOfMinor, subtractMoney, sumMoney, toMajor };

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/outbox.d.mts

@@ -157,6 +157,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 +255,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 };