@classytic/primitives 0.26.4 → 0.28.0

package/dist/bank-transaction.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-CfAvfNiM.mjs";
+import { n as Money } from "./money-C9iLWiWR.mjs";
 //#region src/money/bank-transaction.d.ts
 /**
  * The other side of a bank transaction. All fields optional — different

package/dist/csv.d.mts

@@ -0,0 +1,36 @@
+//#region src/serialization/csv.d.ts
+/**
+ * `@classytic/primitives/csv` — make one value safe to put in a CSV cell.
+ *
+ * Two defences, deliberately separable because a consumer that already has a
+ * real CSV writer must NOT get its quoting done twice:
+ *
+ *   - `neutralizeCsvFormula` — stops the cell being executed as a formula when
+ *     the file is opened in Excel / Sheets / LibreOffice. Use this when a
+ *     library (`csv-stringify`, `papaparse`, …) is doing the quoting.
+ *   - `escapeCsvCell` — neutralize + RFC 4180 quoting. Use this in a
+ *     hand-rolled `rows.map(...).join(',')` serializer.
+ *
+ * WHY quoting is not enough: a spreadsheet strips the quotes first and
+ * evaluates what is left, so `"=cmd|'/c calc'!A1"` still executes. Only
+ * changing the LEADING character stops it, which is why these are one module
+ * and not a quoting helper someone can use alone.
+ *
+ * Well-formed numbers are exempt. Prefixing `-1500` would make every negative
+ * amount text and break the reader's `SUM` — a fix that quietly corrupts every
+ * finance export is worse than the hole. The exemption is the WHOLE cell
+ * matching a number, so `-2+3+cmd|'/c calc'!A0` is still neutralized.
+ *
+ * NOT for a machine-to-machine upload contract with a fixed column spec (a
+ * courier's bulk-import CSV, say) — there the receiver is a parser, not a
+ * spreadsheet, and an added `'` corrupts the payload.
+ */
+/**
+ * Prefix `'` when the cell would otherwise be evaluated as a formula.
+ * `null`/`undefined` become `''`. Numbers are returned unchanged.
+ */
+declare function neutralizeCsvFormula(value: unknown): string;
+/** `neutralizeCsvFormula` + RFC 4180 quoting. The one-call form. */
+declare function escapeCsvCell(value: unknown): string;
+//#endregion
+export { escapeCsvCell, neutralizeCsvFormula };

package/dist/csv.mjs

@@ -0,0 +1,50 @@
+//#region src/serialization/csv.ts
+/**
+* `@classytic/primitives/csv` — make one value safe to put in a CSV cell.
+*
+* Two defences, deliberately separable because a consumer that already has a
+* real CSV writer must NOT get its quoting done twice:
+*
+*   - `neutralizeCsvFormula` — stops the cell being executed as a formula when
+*     the file is opened in Excel / Sheets / LibreOffice. Use this when a
+*     library (`csv-stringify`, `papaparse`, …) is doing the quoting.
+*   - `escapeCsvCell` — neutralize + RFC 4180 quoting. Use this in a
+*     hand-rolled `rows.map(...).join(',')` serializer.
+*
+* WHY quoting is not enough: a spreadsheet strips the quotes first and
+* evaluates what is left, so `"=cmd|'/c calc'!A1"` still executes. Only
+* changing the LEADING character stops it, which is why these are one module
+* and not a quoting helper someone can use alone.
+*
+* Well-formed numbers are exempt. Prefixing `-1500` would make every negative
+* amount text and break the reader's `SUM` — a fix that quietly corrupts every
+* finance export is worse than the hole. The exemption is the WHOLE cell
+* matching a number, so `-2+3+cmd|'/c calc'!A0` is still neutralized.
+*
+* NOT for a machine-to-machine upload contract with a fixed column spec (a
+* courier's bulk-import CSV, say) — there the receiver is a parser, not a
+* spreadsheet, and an added `'` corrupts the payload.
+*/
+/** Leading characters a spreadsheet may treat as the start of a formula or DDE call. */
+const FORMULA_LEAD = /^[=+\-@\t\r]/;
+/** The WHOLE cell is a plain number — no separators, no currency symbol. */
+const WHOLE_NUMBER = /^[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?$/;
+/** Characters that force RFC 4180 quoting. */
+const NEEDS_QUOTING = /[",\r\n]/;
+/**
+* Prefix `'` when the cell would otherwise be evaluated as a formula.
+* `null`/`undefined` become `''`. Numbers are returned unchanged.
+*/
+function neutralizeCsvFormula(value) {
+	const text = value == null ? "" : String(value);
+	if (!FORMULA_LEAD.test(text)) return text;
+	if (WHOLE_NUMBER.test(text)) return text;
+	return `'${text}`;
+}
+/** `neutralizeCsvFormula` + RFC 4180 quoting. The one-call form. */
+function escapeCsvCell(value) {
+	const text = neutralizeCsvFormula(value);
+	return NEEDS_QUOTING.test(text) ? `"${text.replace(/"/g, "\"\"")}"` : text;
+}
+//#endregion
+export { escapeCsvCell, neutralizeCsvFormula };

package/dist/currency.d.mts

@@ -1,2 +1,2 @@
-import { A as convertWithSnapshot, C as CURRENCY_PATTERN, D as FxSnapshot, E as FxRounding, F as minorUnitFactor, I as reverseWithSnapshot, L as toCurrencyCode, M as isCurrencyCode, N as isFxSnapshot, O as InvalidCurrencyCodeError, P as isKnownCurrency, S as CURRENCIES, T as CurrencyMismatchError, j as currencyCode, k as MINOR_UNIT_FACTOR, w as CurrencyCode } from "./money-CfAvfNiM.mjs";
+import { A as FxRounding, B as reverseWithSnapshot, D as CURRENCY_PATTERN, E as CURRENCIES, F as currencyCode, I as isCurrencyCode, L as isFxSnapshot, M as InvalidCurrencyCodeError, N as MINOR_UNIT_FACTOR, O as CurrencyCode, P as convertWithSnapshot, R as isKnownCurrency, V as toCurrencyCode, j as FxSnapshot, k as CurrencyMismatchError, z as minorUnitFactor } from "./money-C9iLWiWR.mjs";
 export { CURRENCIES, CURRENCY_PATTERN, CurrencyCode, CurrencyMismatchError, FxRounding, FxSnapshot, InvalidCurrencyCodeError, MINOR_UNIT_FACTOR, convertWithSnapshot, currencyCode, isCurrencyCode, isFxSnapshot, isKnownCurrency, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };

package/dist/monetization.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-CfAvfNiM.mjs";
+import { n as Money } from "./money-C9iLWiWR.mjs";
 //#region src/money/monetization.d.ts
 /**
  * A map of currency code → {@link Money} for explicit per-currency pricing.
@@ -17,8 +17,11 @@ type MoneyByCurrency = Record<string, Money>;
  *   - `bundle`       — a composite priced from its members.
  *   - `usage`        — metered / per-seat / consumption (billed per unit or in
  *                      arrears). The extension point for rating models.
+ *   - `pass`         — paid once, grants a TERM, never renews (a course access
+ *                      pass, a gym or transit pass, a parking or day pass, a
+ *                      term licence). See {@link PassMonetization}.
  */
-declare const MONETIZATION_KINDS: readonly ["free", "one_time", "subscription", "bundle", "usage"];
+declare const MONETIZATION_KINDS: readonly ["free", "one_time", "subscription", "bundle", "usage", "pass"];
 type MonetizationKind = (typeof MONETIZATION_KINDS)[number];
 /** True when `value` is one of the canonical kinds. */
 declare function isMonetizationKind(value: unknown): value is MonetizationKind;
@@ -103,6 +106,31 @@ interface SubscriptionPlan {
   /** Optional auto-calculated discount vs the highest-frequency plan. */
   readonly discount?: number;
 }
+/**
+ * One buyable term: a price that grants access for a fixed span.
+ *
+ * Shaped like {@link SubscriptionPlan} on purpose (same `duration` +
+ * `durationUnit` vocabulary, so a term means the same thing everywhere) and
+ * kept separate on purpose: a plan carries `trialDays` and a renewal discount,
+ * which are recurring-billing concepts a pass has none of. Reusing the plan
+ * would re-blur the very line this kind exists to draw.
+ */
+interface AccessPass {
+  /** Internal key ('pass-30d', 'season', 'day'). Stable across edits. */
+  readonly key: string;
+  /** Display label ("1 month", "Season pass", "Day pass"). */
+  readonly label: string;
+  /** Price for this term in the default currency. */
+  readonly price: Money;
+  /** Explicit per-currency overrides. */
+  readonly priceByCurrency?: MoneyByCurrency;
+  /** Optional strikethrough / "was" price for this term. */
+  readonly compareAtPrice?: Money;
+  /** Length of access this term buys. */
+  readonly duration: number;
+  /** Unit of that length. */
+  readonly durationUnit: DurationUnit;
+}
 /**
  * One band of a metered rate table.
  *
@@ -180,17 +208,63 @@ interface UsageMonetization {
     readonly durationUnit: DurationUnit;
   };
 }
+/**
+ * Paid once, grants a TERM, never renews.
+ *
+ * The gap this closes: `one_time` prices a thing but says nothing about how
+ * long it is yours, and `subscription` prices a term but means it RECURS. A
+ * prepaid term fits neither, so hosts selling one reached for `subscription`
+ * and then had to explain, wherever the value was read, that it does not
+ * actually renew — a classification that needs a comment to be understood has
+ * already failed, and `toRevenueMonetizationType` would have settled those
+ * sales as subscriptions in the ledger.
+ *
+ * Buying again EXTENDS rather than renewing: nothing schedules a charge, the
+ * buyer chooses when (or whether) to pay for the next term. A perpetual sale
+ * is `one_time`, not a pass with an enormous duration: "forever" is the
+ * absence of a term, not a long one.
+ */
+interface PassMonetization {
+  readonly type: 'pass';
+  /** At least one term. Several means the buyer picks (1 month / 1 year). */
+  readonly passes: readonly AccessPass[];
+}
 /**
  * The canonical monetization value object. The `type` discriminant selects the
  * pricing detail. Matches `@classytic/catalog`'s existing discriminants (so no
  * data migration) plus `usage`.
  */
-type Monetization = FreeMonetization | OneTimeMonetization | SubscriptionMonetization | BundleMonetization | UsageMonetization;
+type Monetization = FreeMonetization | OneTimeMonetization | SubscriptionMonetization | BundleMonetization | UsageMonetization | PassMonetization;
 declare const isFreeMonetization: (m: Monetization) => m is FreeMonetization;
 declare const isOneTimeMonetization: (m: Monetization) => m is OneTimeMonetization;
 declare const isSubscriptionMonetization: (m: Monetization) => m is SubscriptionMonetization;
 declare const isBundleMonetization: (m: Monetization) => m is BundleMonetization;
 declare const isUsageMonetization: (m: Monetization) => m is UsageMonetization;
+declare const isPassMonetization: (m: Monetization) => m is PassMonetization;
+/**
+ * A term's length in APPROXIMATE days, for ORDERING AND LABELS ONLY.
+ *
+ * A month is 30 here and a year 365, which is wrong as a date and right as a
+ * comparison: it answers "is this term longer than that one" and "call this
+ * one '6 months'", both of which only need a stable ranking.
+ *
+ * NEVER compute an expiry from it. A term that ENDS on a date must be added
+ * with calendar arithmetic (`addMonths` / `addYears`), or February and leap
+ * years quietly short-change the buyer. That belongs to the host's date
+ * library, not to a pure money value object.
+ */
+declare function approxTermDays(duration: number, unit: DurationUnit): number;
+/**
+ * The term a storefront leads with: the CHEAPEST, ties broken by the shortest
+ * span so the answer is deterministic whatever order the passes were authored
+ * in. One definition, because a card reading the cheapest while a checkout
+ * defaulted to the first is the divergence {@link unitPriceOf} exists to stop.
+ *
+ * The tie-break compares SPANS, not the raw `duration`: "1 year" and "1 month"
+ * are both `duration: 1`, so a number-only comparison ranks them by whichever
+ * happened to be authored first.
+ */
+declare function defaultPassOf(m: PassMonetization): AccessPass | null;
 /** The kind of a monetization value (its discriminant, narrowed to the union). */
 declare const monetizationKindOf: (m: Monetization) => MonetizationKind;
 /**
@@ -205,6 +279,8 @@ declare const monetizationKindOf: (m: Monetization) => MonetizationKind;
  *   - `bundle`       → the FIXED bundle price; `null` in `dynamic` mode (that
  *                      price is computed from the members, not stored here)
  *   - `free`         → `null`
+ *   - `pass`         → the cheapest term's price (the "from" price a
+ *                      storefront leads with), see {@link defaultPassOf}
  *   - `usage`        → `null` — a metered item has no single unit price; it is
  *                      rated per consumption via {@link UsageRating}
  *
@@ -212,7 +288,14 @@ declare const monetizationKindOf: (m: Monetization) => MonetizationKind;
  * it prices, instead of silently returning `null`.
  */
 declare function unitPriceOf(m: Monetization): Money | null;
-/** The strikethrough / MSRP price, if the kind carries one (only `one_time`). */
+/**
+ * The strikethrough / MSRP price, for the kinds that carry one.
+ *
+ * Always paired with whatever {@link unitPriceOf} returned, so a card can
+ * never strike through the "was" of one term beside the price of another:
+ * `one_time` compares against its base price, `pass` against the term
+ * `defaultPassOf` picked.
+ */
 declare function compareAtPriceOf(m: Monetization): Money | null;
 /**
  * `@classytic/revenue`'s coarse wire enum. `purchase` is the paid-once case that
@@ -224,10 +307,13 @@ type RevenueMonetizationType = 'free' | 'purchase' | 'subscription';
 /**
  * Canonical kind → revenue wire type. Everything that is not `free` or
  * `subscription` settles as a `purchase` in revenue's ledger vocabulary
- * (one_time, bundle, and a usage charge are all "a purchase happened").
+ * (one_time, bundle, a usage charge and a pass are all "a purchase
+ * happened"). A `pass` in particular must NOT land on `subscription`: nothing
+ * schedules a renewal, and a ledger that thinks otherwise forecasts revenue
+ * that will never be billed.
  */
 declare function toRevenueMonetizationType(kind: MonetizationKind): RevenueMonetizationType;
 /** Revenue wire type → canonical kind (`purchase` → `one_time`). */
 declare function fromRevenueMonetizationType(type: RevenueMonetizationType): MonetizationKind;
 //#endregion
-export { BundleMonetization, DurationUnit, FreeMonetization, MONETIZATION_KINDS, Monetization, MonetizationKind, MoneyByCurrency, OneTimeMonetization, OneTimePricing, PriceTier, RevenueMonetizationType, SubscriptionMonetization, SubscriptionPlan, UPFRONT_COLLECTION_MODES, UpfrontCollectionMode, UsageMonetization, UsageRating, UsageTier, compareAtPriceOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };
+export { AccessPass, BundleMonetization, DurationUnit, FreeMonetization, MONETIZATION_KINDS, Monetization, MonetizationKind, MoneyByCurrency, OneTimeMonetization, OneTimePricing, PassMonetization, PriceTier, RevenueMonetizationType, SubscriptionMonetization, SubscriptionPlan, UPFRONT_COLLECTION_MODES, UpfrontCollectionMode, UsageMonetization, UsageRating, UsageTier, approxTermDays, compareAtPriceOf, defaultPassOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isPassMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };

package/dist/monetization.mjs

@@ -8,13 +8,17 @@
 *   - `bundle`       — a composite priced from its members.
 *   - `usage`        — metered / per-seat / consumption (billed per unit or in
 *                      arrears). The extension point for rating models.
+*   - `pass`         — paid once, grants a TERM, never renews (a course access
+*                      pass, a gym or transit pass, a parking or day pass, a
+*                      term licence). See {@link PassMonetization}.
 */
 const MONETIZATION_KINDS = [
 	"free",
 	"one_time",
 	"subscription",
 	"bundle",
-	"usage"
+	"usage",
+	"pass"
 ];
 const MONETIZATION_KIND_SET = new Set(MONETIZATION_KINDS);
 /** True when `value` is one of the canonical kinds. */
@@ -71,6 +75,50 @@ const isOneTimeMonetization = (m) => m.type === "one_time";
 const isSubscriptionMonetization = (m) => m.type === "subscription";
 const isBundleMonetization = (m) => m.type === "bundle";
 const isUsageMonetization = (m) => m.type === "usage";
+const isPassMonetization = (m) => m.type === "pass";
+const APPROX_DAYS_PER_UNIT = {
+	day: 1,
+	week: 7,
+	month: 30,
+	year: 365
+};
+/**
+* A term's length in APPROXIMATE days, for ORDERING AND LABELS ONLY.
+*
+* A month is 30 here and a year 365, which is wrong as a date and right as a
+* comparison: it answers "is this term longer than that one" and "call this
+* one '6 months'", both of which only need a stable ranking.
+*
+* NEVER compute an expiry from it. A term that ENDS on a date must be added
+* with calendar arithmetic (`addMonths` / `addYears`), or February and leap
+* years quietly short-change the buyer. That belongs to the host's date
+* library, not to a pure money value object.
+*/
+function approxTermDays(duration, unit) {
+	return duration * APPROX_DAYS_PER_UNIT[unit];
+}
+/**
+* The term a storefront leads with: the CHEAPEST, ties broken by the shortest
+* span so the answer is deterministic whatever order the passes were authored
+* in. One definition, because a card reading the cheapest while a checkout
+* defaulted to the first is the divergence {@link unitPriceOf} exists to stop.
+*
+* The tie-break compares SPANS, not the raw `duration`: "1 year" and "1 month"
+* are both `duration: 1`, so a number-only comparison ranks them by whichever
+* happened to be authored first.
+*/
+function defaultPassOf(m) {
+	let best = null;
+	let bestSpan = Number.POSITIVE_INFINITY;
+	for (const pass of m.passes) {
+		const span = approxTermDays(pass.duration, pass.durationUnit);
+		if (best === null || pass.price.amount < best.price.amount || pass.price.amount === best.price.amount && span < bestSpan) {
+			best = pass;
+			bestSpan = span;
+		}
+	}
+	return best;
+}
 /** The kind of a monetization value (its discriminant, narrowed to the union). */
 const monetizationKindOf = (m) => m.type;
 /**
@@ -85,6 +133,8 @@ const monetizationKindOf = (m) => m.type;
 *   - `bundle`       → the FIXED bundle price; `null` in `dynamic` mode (that
 *                      price is computed from the members, not stored here)
 *   - `free`         → `null`
+*   - `pass`         → the cheapest term's price (the "from" price a
+*                      storefront leads with), see {@link defaultPassOf}
 *   - `usage`        → `null` — a metered item has no single unit price; it is
 *                      rated per consumption via {@link UsageRating}
 *
@@ -96,18 +146,31 @@ function unitPriceOf(m) {
 		case "one_time": return m.pricing.basePrice;
 		case "subscription": return m.plans[0]?.price ?? null;
 		case "bundle": return m.basePrice ?? null;
+		case "pass": return defaultPassOf(m)?.price ?? null;
 		case "free":
 		case "usage": return null;
 	}
 }
-/** The strikethrough / MSRP price, if the kind carries one (only `one_time`). */
+/**
+* The strikethrough / MSRP price, for the kinds that carry one.
+*
+* Always paired with whatever {@link unitPriceOf} returned, so a card can
+* never strike through the "was" of one term beside the price of another:
+* `one_time` compares against its base price, `pass` against the term
+* `defaultPassOf` picked.
+*/
 function compareAtPriceOf(m) {
-	return m.type === "one_time" ? m.pricing.compareAtPrice ?? null : null;
+	if (m.type === "one_time") return m.pricing.compareAtPrice ?? null;
+	if (m.type === "pass") return defaultPassOf(m)?.compareAtPrice ?? null;
+	return null;
 }
 /**
 * Canonical kind → revenue wire type. Everything that is not `free` or
 * `subscription` settles as a `purchase` in revenue's ledger vocabulary
-* (one_time, bundle, and a usage charge are all "a purchase happened").
+* (one_time, bundle, a usage charge and a pass are all "a purchase
+* happened"). A `pass` in particular must NOT land on `subscription`: nothing
+* schedules a renewal, and a ledger that thinks otherwise forecasts revenue
+* that will never be billed.
 */
 function toRevenueMonetizationType(kind) {
 	if (kind === "free") return "free";
@@ -121,4 +184,4 @@ function fromRevenueMonetizationType(type) {
 	return "one_time";
 }
 //#endregion
-export { MONETIZATION_KINDS, UPFRONT_COLLECTION_MODES, compareAtPriceOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };
+export { MONETIZATION_KINDS, UPFRONT_COLLECTION_MODES, approxTermDays, compareAtPriceOf, defaultPassOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isPassMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };

package/dist/money-BBOARE5f.mjs

@@ -0,0 +1,204 @@
+import { CurrencyMismatchError, currencyCode, isCurrencyCode, minorUnitFactor } from "./currency.mjs";
+//#region src/money/cash-destination.ts
+/**
+* WHERE received cash landed, as an INTENT — never a chart-of-accounts code.
+*
+* The one vocabulary a request body, a domain event, a client SDK and a
+* settlement dialog all speak. The accounting tier maps an intent to whatever
+* account the active chart assigns, so a chart renumber cannot reach any of
+* them. A literal code in a client once named a bank account the chart had
+* already renumbered, and every settlement it sent was refused.
+*
+* `cash` — the business's bank / current account, the default for a courier
+*          remittance, a card payout or a transfer.
+* `petty_cash` — cash in hand, for an in-person handover at the till.
+*/
+const CASH_DESTINATIONS = ["cash", "petty_cash"];
+function isCashDestination(value) {
+	return typeof value === "string" && CASH_DESTINATIONS.includes(value);
+}
+/** Human label for a destination — the ONE place the wording lives. */
+function cashDestinationLabel(destination) {
+	switch (destination) {
+		case "cash": return "Bank account";
+		case "petty_cash": return "Cash in hand";
+		default: throw new Error(`unknown cash destination ${String(destination)}`);
+	}
+}
+//#endregion
+//#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>`
+* — 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'>
+*/
+function MinorUnits(amount, _currency) {
+	return amount;
+}
+/**
+* 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: currencyCode(currency)
+	};
+}
+/**
+* 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' }
+*/
+function fromMajor(major, currency) {
+	if (!Number.isFinite(major)) throw new TypeError(`fromMajor received non-finite value: ${major}`);
+	const raw = major * minorUnitFactor(currency);
+	const cleaned = Number(raw.toPrecision(15));
+	return {
+		amount: Math.round(Math.abs(cleaned)) * (cleaned < 0 ? -1 : 1),
+		currency: currencyCode(currency)
+	};
+}
+/** Convert {@link Money} back to its major-unit floating-point representation. */
+function toMajor(m) {
+	return m.amount / minorUnitFactor(m.currency);
+}
+function assertSameCurrency(a, b) {
+	if (a.currency !== b.currency) throw new CurrencyMismatchError(a.currency, b.currency);
+}
+function addMoney(a, b) {
+	assertSameCurrency(a, b);
+	return {
+		amount: a.amount + b.amount,
+		currency: a.currency
+	};
+}
+function subtractMoney(a, b) {
+	assertSameCurrency(a, b);
+	return {
+		amount: a.amount - b.amount,
+		currency: a.currency
+	};
+}
+/**
+* Multiply money by a scalar. The result is rounded to an integer number of
+* minor units using half-away-from-zero rounding.
+*/
+function multiplyMoney(m, scalar) {
+	if (!Number.isFinite(scalar)) throw new TypeError(`multiplyMoney received non-finite scalar: ${scalar}`);
+	const raw = m.amount * scalar;
+	return {
+		amount: Math.round(Math.abs(raw)) * (raw < 0 ? -1 : 1),
+		currency: m.currency
+	};
+}
+/** Sum a list of {@link Money}. Returns zero in the given currency for empty input. */
+function sumMoney(values, currency) {
+	return values.reduce((acc, v) => addMoney(acc, v), {
+		amount: 0,
+		currency: currencyCode(currency)
+	});
+}
+/** Strict equality (amount and currency both match). */
+function equalsMoney(a, b) {
+	return a.amount === b.amount && a.currency === b.currency;
+}
+/**
+* Ordering predicate. Returns -1, 0, or 1. Throws on currency mismatch — use
+* {@link equalsMoney} for a total equality check across currencies.
+*/
+function compareMoney(a, b) {
+	assertSameCurrency(a, b);
+	if (a.amount < b.amount) return -1;
+	if (a.amount > b.amount) return 1;
+	return 0;
+}
+function isZeroMoney(m) {
+	return m.amount === 0;
+}
+function isPositiveMoney(m) {
+	return m.amount > 0;
+}
+function isNegativeMoney(m) {
+	return m.amount < 0;
+}
+function negateMoney(m) {
+	return {
+		amount: m.amount === 0 ? 0 : -m.amount,
+		currency: m.currency
+	};
+}
+function absMoney(m) {
+	return m.amount < 0 ? negateMoney(m) : m;
+}
+/**
+* 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
+*/
+function majorToMinorUnits(major, minorUnitDecimals = 2) {
+	const factor = 10 ** minorUnitDecimals;
+	const minor = Math.round(major * factor);
+	if (!Number.isSafeInteger(minor)) throw new RangeError(`Amount ${major} exceeds safe integer limit when converted to minor units. Max safe amount: ${Number.MAX_SAFE_INTEGER / factor}`);
+	return minor;
+}
+/** Integer minor units → decimal major-unit number by decimal exponent: `1050 → 10.5`. */
+function minorUnitsToMajor(minor, minorUnitDecimals = 2) {
+	return minor / 10 ** minorUnitDecimals;
+}
+/**
+* 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.
+*/
+function percentOfMinor(minor, ratePercent) {
+	if (!Number.isFinite(minor) || !Number.isFinite(ratePercent)) throw new TypeError(`percentOfMinor received non-finite input: minor=${minor}, ratePercent=${ratePercent}`);
+	return Math.round(minor * ratePercent / 100);
+}
+/**
+* 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.
+*/
+function formatMinorUnits(minor, minorUnitDecimals = 2) {
+	return minorUnitsToMajor(minor, minorUnitDecimals).toFixed(minorUnitDecimals);
+}
+/** Structural type guard. */
+function isMoney(value) {
+	return typeof value === "object" && value !== null && typeof value.amount === "number" && Number.isInteger(value.amount) && isCurrencyCode(value.currency);
+}
+//#endregion
+export { isCashDestination as C, cashDestinationLabel as S, percentOfMinor as _, equalsMoney as a, toMajor as b, isMoney as c, isZeroMoney as d, majorToMinorUnits as f, negateMoney as g, multiplyMoney as h, compareMoney as i, isNegativeMoney as l, money as m, absMoney as n, formatMinorUnits as o, minorUnitsToMajor as p, addMoney as r, fromMajor as s, MinorUnits as t, isPositiveMoney as u, subtractMoney as v, CASH_DESTINATIONS as x, sumMoney as y };

package/dist/{money-CfAvfNiM.d.mts → money-C9iLWiWR.d.mts}

@@ -196,6 +196,26 @@ declare function reverseWithSnapshot(base: Money, fx: FxSnapshot, options?: {
  */
 declare function isFxSnapshot(value: unknown): value is FxSnapshot;
 //#endregion
+//#region src/money/cash-destination.d.ts
+/**
+ * WHERE received cash landed, as an INTENT — never a chart-of-accounts code.
+ *
+ * The one vocabulary a request body, a domain event, a client SDK and a
+ * settlement dialog all speak. The accounting tier maps an intent to whatever
+ * account the active chart assigns, so a chart renumber cannot reach any of
+ * them. A literal code in a client once named a bank account the chart had
+ * already renumbered, and every settlement it sent was refused.
+ *
+ * `cash` — the business's bank / current account, the default for a courier
+ *          remittance, a card payout or a transfer.
+ * `petty_cash` — cash in hand, for an in-person handover at the till.
+ */
+declare const CASH_DESTINATIONS: readonly ["cash", "petty_cash"];
+type CashDestination = (typeof CASH_DESTINATIONS)[number];
+declare function isCashDestination(value: unknown): value is CashDestination;
+/** Human label for a destination — the ONE place the wording lives. */
+declare function cashDestinationLabel(destination: CashDestination): string;
+//#endregion
 //#region src/money/money.d.ts
 /**
  * Wire-format monetary amount: integer minor units, branded with a phantom
@@ -343,4 +363,4 @@ declare function formatMinorUnits(minor: number, minorUnitDecimals?: number): st
 /** 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 };
+export { FxRounding as A, reverseWithSnapshot as B, CashDestination as C, CURRENCY_PATTERN as D, CURRENCIES as E, currencyCode as F, isCurrencyCode as I, isFxSnapshot as L, InvalidCurrencyCodeError as M, MINOR_UNIT_FACTOR as N, CurrencyCode as O, convertWithSnapshot as P, isKnownCurrency as R, CASH_DESTINATIONS as S, isCashDestination as T, toCurrencyCode as V, 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, FxSnapshot as j, CurrencyMismatchError 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, cashDestinationLabel as w, toMajor as x, subtractMoney as y, minorUnitFactor as z };

package/dist/money.d.mts

@@ -1,2 +1,2 @@
-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-CfAvfNiM.mjs";
-export { CurrencyMismatchError, MinorUnits, Money, absMoney, addMoney, compareMoney, equalsMoney, formatMinorUnits, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, majorToMinorUnits, minorUnitsToMajor, money, multiplyMoney, negateMoney, percentOfMinor, subtractMoney, sumMoney, toMajor };
+import { C as CashDestination, S as CASH_DESTINATIONS, T as isCashDestination, _ 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, k as CurrencyMismatchError, 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, w as cashDestinationLabel, x as toMajor, y as subtractMoney } from "./money-C9iLWiWR.mjs";
+export { CASH_DESTINATIONS, type CashDestination, CurrencyMismatchError, MinorUnits, Money, absMoney, addMoney, cashDestinationLabel, compareMoney, equalsMoney, formatMinorUnits, fromMajor, isCashDestination, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, majorToMinorUnits, minorUnitsToMajor, money, multiplyMoney, negateMoney, percentOfMinor, subtractMoney, sumMoney, toMajor };