@classytic/primitives 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.26.0] — 2026-08-27
+
+### Added
+
+- **`./deadline` subpath** — `Deadline` value type + helpers for date-bounded
+  obligations (reservations, SLA windows, contract terms).
+- **`./stock-level` subpath** — canonical stock-level representation and helpers.
+- **`./item-facts` subpath** — cross-kernel item fact contract (weight, dimensions,
+  hazmat flags) that catalog declares and logistics/inventory reads.
+- **`StockKey` branded type** (`./item-identity`) — prevents a bare merchandising
+  label or ObjectId being passed where a quant key is expected; the only source is
+  `stockKeyOf()` / `requireStockKey()`. Return types of both functions updated.
+- **Upfront collection policy** (`./monetization`) — `UpfrontCollectionPolicy`
+  (`'full_payment' | 'deposit' | 'deferred'`) + `UPFRONT_COLLECTION_POLICIES`
+  const. Cross-kernel: catalog declares the policy, order turns it into tenders,
+  revenue settles them.
+
 ## [0.25.0] - 2026-08-24
 
 ### Added

package/dist/deadline.d.mts

@@ -0,0 +1,16 @@
+//#region src/composition/deadline.d.ts
+/**
+ * Race a promise against a deadline without leaking the loser.
+ *
+ * A call that can hang — no throw, no response, the underlying layer just
+ * never settles — must not block its caller forever. Nothing here cancels
+ * the original promise; it keeps running after the deadline, so its eventual
+ * settlement is swallowed rather than surfaced a second time to a caller
+ * that already moved on.
+ */
+declare class DeadlineExceededError extends Error {
+  constructor(label: string, timeoutMs: number);
+}
+declare function withDeadline<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T>;
+//#endregion
+export { DeadlineExceededError, withDeadline };

package/dist/deadline.mjs

@@ -0,0 +1,31 @@
+//#region src/composition/deadline.ts
+/**
+* Race a promise against a deadline without leaking the loser.
+*
+* A call that can hang — no throw, no response, the underlying layer just
+* never settles — must not block its caller forever. Nothing here cancels
+* the original promise; it keeps running after the deadline, so its eventual
+* settlement is swallowed rather than surfaced a second time to a caller
+* that already moved on.
+*/
+var DeadlineExceededError = class extends Error {
+	constructor(label, timeoutMs) {
+		super(`${label} timed out after ${timeoutMs}ms`);
+		this.name = "DeadlineExceededError";
+	}
+};
+function withDeadline(promise, timeoutMs, label) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(new DeadlineExceededError(label, timeoutMs)), timeoutMs);
+		timer.unref?.();
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+	});
+}
+//#endregion
+export { DeadlineExceededError, withDeadline };

package/dist/item-facts.d.mts

@@ -0,0 +1,73 @@
+import { ShelfLifePolicy } from "./shelf-life.mjs";
+//#region src/inventory/item-facts.d.ts
+/** Coarse lot/serial tracking. `trackingPolicy.mode` wins when both are set. */
+type TrackingMode = "none" | "lot" | "serial";
+/** The stock facts an Item contributes. Persistence and classification are the owning package's. */
+interface ItemStockSource {
+  skuRef: string;
+  sku: string;
+  displayName: string;
+  /** The canonical STOCK unit — what quants and moves are balanced in. */
+  uom: string;
+  trackingMode: TrackingMode;
+  trackingPolicy?: ShelfLifePolicy | undefined;
+  /**
+   * Variable-weight item (deli, meat, loose produce): a measured weight is
+   * captured per received lot while the piece count stays the stock dimension.
+   */
+  catchWeight?: boolean | undefined;
+  weightUom?: string | undefined;
+  weight?: number | undefined;
+  volume?: number | undefined;
+  barcode?: string[] | undefined;
+  /** Retired items are not stockable. Independent of whether a Product sells. */
+  isActive: boolean;
+}
+/** The merchandising side. Every stock fact is optional — the Item owns those. */
+interface ProductFacet {
+  skuRef: string;
+  sku: string;
+  displayName: string;
+  uom?: string | undefined;
+  trackingMode?: TrackingMode | undefined;
+  trackingPolicy?: ShelfLifePolicy | undefined;
+  catchWeight?: boolean | undefined;
+  weightUom?: string | undefined;
+  weight?: number | undefined;
+  volume?: number | undefined;
+  barcode?: string[] | undefined;
+  isActive?: boolean | undefined;
+}
+/** The resolved answer. `@classytic/flow`'s `SkuDetails` IS this type. */
+interface ItemStockFacts {
+  skuRef: string;
+  sku: string;
+  displayName: string;
+  trackingMode: TrackingMode;
+  trackingPolicy?: ShelfLifePolicy;
+  uom: string;
+  catchWeight?: boolean;
+  weightUom?: string;
+  weight?: number;
+  volume?: number;
+  barcode?: string[];
+  isActive: boolean;
+}
+/**
+ * Merge an Item with its Product facet.
+ *
+ * - **Neither** ⇒ `null`. An unknown SKU is ordinary (a deleted line), not an error.
+ * - **Product only** ⇒ the product's own facts — every deployment before an Item exists.
+ * - **Item only** ⇒ the item's facts. A raw material nobody sells.
+ * - **Both** ⇒ stock facts from the Item, name and label from the Product.
+ *
+ * `isActive` follows the ITEM when one exists: a product withdrawn from sale is
+ * still stock on a shelf, whereas a retired item is not stockable at all. Taking
+ * the product's flag would make unlisting a product silently orphan its stock.
+ */
+declare function resolveStockFacts(input: {
+  item?: ItemStockSource | null | undefined;
+  product?: ProductFacet | null | undefined;
+}): ItemStockFacts | null;
+//#endregion
+export { ItemStockFacts, ItemStockSource, ProductFacet, TrackingMode, resolveStockFacts };

package/dist/item-facts.mjs

@@ -0,0 +1,53 @@
+//#region src/inventory/item-facts.ts
+/** Unit assumed when neither side declares one. A deployment-wide guess, and a bad one — set a real `uom` on the Item. */
+const FALLBACK_UOM = "unit";
+const defined = (key, value) => value === void 0 ? {} : { [key]: value };
+/**
+* Merge an Item with its Product facet.
+*
+* - **Neither** ⇒ `null`. An unknown SKU is ordinary (a deleted line), not an error.
+* - **Product only** ⇒ the product's own facts — every deployment before an Item exists.
+* - **Item only** ⇒ the item's facts. A raw material nobody sells.
+* - **Both** ⇒ stock facts from the Item, name and label from the Product.
+*
+* `isActive` follows the ITEM when one exists: a product withdrawn from sale is
+* still stock on a shelf, whereas a retired item is not stockable at all. Taking
+* the product's flag would make unlisting a product silently orphan its stock.
+*/
+function resolveStockFacts(input) {
+	const { item, product } = input;
+	if (!item && !product) return null;
+	if (!item) {
+		const p = product;
+		return {
+			skuRef: p.skuRef,
+			sku: p.sku,
+			displayName: p.displayName,
+			uom: p.uom ?? FALLBACK_UOM,
+			trackingMode: p.trackingMode ?? "none",
+			...defined("trackingPolicy", p.trackingPolicy),
+			...defined("catchWeight", p.catchWeight),
+			...defined("weightUom", p.weightUom),
+			...defined("weight", p.weight),
+			...defined("volume", p.volume),
+			...defined("barcode", p.barcode),
+			isActive: p.isActive ?? true
+		};
+	}
+	return {
+		skuRef: item.skuRef,
+		sku: product?.sku ?? item.sku,
+		displayName: product?.displayName ?? item.displayName,
+		uom: item.uom,
+		trackingMode: item.trackingMode,
+		...defined("trackingPolicy", item.trackingPolicy),
+		...defined("catchWeight", item.catchWeight),
+		...defined("weightUom", item.weightUom),
+		...defined("weight", item.weight),
+		...defined("volume", item.volume),
+		...defined("barcode", item.barcode),
+		isActive: item.isActive
+	};
+}
+//#endregion
+export { resolveStockFacts };

package/dist/item-identity.d.mts

@@ -1,24 +1,14 @@
+import { t as Brand } from "./brand-Lj_75Y_r.mjs";
 //#region src/identity/item-identity.d.ts
 /**
- * `sku` is a LABEL; `skuRef` is the stock IDENTITY. Never one field.
+ * A resolved STOCK key — the string quants, moves and reservations are keyed by.
  *
- * | field | mutable? | job |
- * |---|---|---|
- * | `skuRef` | never | keys quants, moves and ledger rows |
- * | `sku` | operator edits it | what a human reads, types, searches |
- *
- * Use `stockKeyOf` for anything that reserves or moves stock, `skuDisplay` for
- * anything a human reads. Never hand-roll either: both fall back, in OPPOSITE
- * directions, and getting one backwards type-checks and returns a plausible
- * string.
- *
- * - stock key = `skuRef ?? sku` — absent `skuRef` means a pre-split producer
- *   whose `sku` still IS the key.
- * - display = `skuLabel ?? sku ?? skuRef` — the ref last, and flagged, because
- *   it can be an opaque id with no merchandising meaning.
- *
- * Pinned by `tests/unit/item-identity.test.ts`.
+ * Branded so a port that moves stock cannot accept a bare string: the only way
+ * to obtain one is {@link stockKeyOf} / {@link requireStockKey}, which apply the
+ * `skuRef ?? sku` rule. A merchandising label passed where a stock key belongs
+ * finds no quant and reports "out of stock" against a full shelf.
  */
+type StockKey = Brand<string, "StockKey">;
 /** Identifier fields a record may carry — each shape populates a different subset. */
 interface SkuFields {
   /** Merchandising label — mutable, human-facing. */
@@ -40,12 +30,12 @@ interface SkuFields {
  */
 declare function stockKeyOf(item: SkuFields, fallback?: string | {
   toString(): string;
-}): string | undefined;
+}): StockKey | undefined;
 /**
  * {@link stockKeyOf} that THROWS. Use wherever the key feeds a stock movement:
  * a reservation on `undefined` returns "out of stock" instead of failing.
  */
-declare function requireStockKey(item: SkuFields, context?: string): string;
+declare function requireStockKey(item: SkuFields, context?: string): StockKey;
 /** What a surface should render for an item, and whether it had a real label. */
 interface SkuDisplay {
   /** Best human-facing value. `undefined` = no identifier at all; render a dash. */
@@ -68,4 +58,4 @@ declare function skuDisplay(item: SkuFields): SkuDisplay;
  */
 declare function looksLikeOpaqueId(value: string | undefined): boolean;
 //#endregion
-export { SkuDisplay, SkuFields, looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyOf };
+export { SkuDisplay, SkuFields, StockKey, looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyOf };

package/dist/monetization.d.mts

@@ -22,6 +22,45 @@ declare const MONETIZATION_KINDS: readonly ["free", "one_time", "subscription",
 type MonetizationKind = (typeof MONETIZATION_KINDS)[number];
 /** True when `value` is one of the canonical kinds. */
 declare function isMonetizationKind(value: unknown): value is MonetizationKind;
+/**
+ * HOW MUCH of a price is collected at the point of sale.
+ *
+ * Distinct from every neighbouring vocabulary, which is why it is its own:
+ *
+ *   - order's `PAYMENT_TERMS` (`prepaid` | `collect_on_delivery`) says WHEN.
+ *   - `PaymentAllocationStatus` (`partial`, `allocated`…) says how much of a
+ *     RECEIVED payment has been applied to what it settles.
+ *   - revenue's `PARTIALLY_REFUNDED` is a transaction's own state.
+ *
+ * None of them answers "what do we charge this customer right now", and a host
+ * that guesses charges either nothing or everything — opposite answers to the
+ * same question.
+ *
+ * It lives here, beside {@link MONETIZATION_KINDS}, for the reason stated in
+ * catalog's barrel: monetization is a CROSS-KERNEL contract. Catalog declares
+ * the policy on a product, order turns it into tenders, revenue settles them.
+ * Three packages reading one definition, none re-exporting it.
+ *
+ *   - `full_payment` — the whole price, before the sale completes.
+ *   - `deposit`      — a fixed amount now, the balance outstanding on the
+ *                      order and settled later by another tender. One provider
+ *                      line instead of two, which matters when card fees are
+ *                      charged per transaction.
+ *   - `pay_later`    — nothing now. The order still records what is owed.
+ *
+ * ABSENCE means `full_payment` — the behaviour before this existed — so no
+ * stored record changes meaning when a build that knows this field ships.
+ */
+declare const UPFRONT_COLLECTION_MODES: readonly ["full_payment", "deposit", "pay_later"];
+type UpfrontCollectionMode = (typeof UPFRONT_COLLECTION_MODES)[number];
+/**
+ * Narrow an unknown value to a collection mode.
+ *
+ * Readers MUST treat `false` as UNKNOWN, never as `full_payment`: a record
+ * written by a build that knows a mode this one does not has not said "charge
+ * everything", and assuming so takes money nobody agreed to.
+ */
+declare function isUpfrontCollectionMode(value: unknown): value is UpfrontCollectionMode;
 /** A quantity-based price break. `price` (fixed override) XOR `discountPercent`. */
 interface PriceTier {
   /** Minimum quantity to qualify. */
@@ -191,4 +230,4 @@ declare function toRevenueMonetizationType(kind: MonetizationKind): RevenueMonet
 /** 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, UsageMonetization, UsageRating, UsageTier, compareAtPriceOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isSubscriptionMonetization, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };
+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 };

package/dist/monetization.mjs

@@ -21,6 +21,51 @@ const MONETIZATION_KIND_SET = new Set(MONETIZATION_KINDS);
 function isMonetizationKind(value) {
 	return typeof value === "string" && MONETIZATION_KIND_SET.has(value);
 }
+/**
+* HOW MUCH of a price is collected at the point of sale.
+*
+* Distinct from every neighbouring vocabulary, which is why it is its own:
+*
+*   - order's `PAYMENT_TERMS` (`prepaid` | `collect_on_delivery`) says WHEN.
+*   - `PaymentAllocationStatus` (`partial`, `allocated`…) says how much of a
+*     RECEIVED payment has been applied to what it settles.
+*   - revenue's `PARTIALLY_REFUNDED` is a transaction's own state.
+*
+* None of them answers "what do we charge this customer right now", and a host
+* that guesses charges either nothing or everything — opposite answers to the
+* same question.
+*
+* It lives here, beside {@link MONETIZATION_KINDS}, for the reason stated in
+* catalog's barrel: monetization is a CROSS-KERNEL contract. Catalog declares
+* the policy on a product, order turns it into tenders, revenue settles them.
+* Three packages reading one definition, none re-exporting it.
+*
+*   - `full_payment` — the whole price, before the sale completes.
+*   - `deposit`      — a fixed amount now, the balance outstanding on the
+*                      order and settled later by another tender. One provider
+*                      line instead of two, which matters when card fees are
+*                      charged per transaction.
+*   - `pay_later`    — nothing now. The order still records what is owed.
+*
+* ABSENCE means `full_payment` — the behaviour before this existed — so no
+* stored record changes meaning when a build that knows this field ships.
+*/
+const UPFRONT_COLLECTION_MODES = [
+	"full_payment",
+	"deposit",
+	"pay_later"
+];
+const UPFRONT_COLLECTION_MODE_SET = new Set(UPFRONT_COLLECTION_MODES);
+/**
+* Narrow an unknown value to a collection mode.
+*
+* Readers MUST treat `false` as UNKNOWN, never as `full_payment`: a record
+* written by a build that knows a mode this one does not has not said "charge
+* everything", and assuming so takes money nobody agreed to.
+*/
+function isUpfrontCollectionMode(value) {
+	return typeof value === "string" && UPFRONT_COLLECTION_MODE_SET.has(value);
+}
 const isFreeMonetization = (m) => m.type === "free";
 const isOneTimeMonetization = (m) => m.type === "one_time";
 const isSubscriptionMonetization = (m) => m.type === "subscription";
@@ -76,4 +121,4 @@ function fromRevenueMonetizationType(type) {
 	return "one_time";
 }
 //#endregion
-export { MONETIZATION_KINDS, compareAtPriceOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isSubscriptionMonetization, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };
+export { MONETIZATION_KINDS, UPFRONT_COLLECTION_MODES, compareAtPriceOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };

package/dist/stock-level.d.mts

@@ -0,0 +1,59 @@
+import { t as Brand } from "./brand-Lj_75Y_r.mjs";
+//#region src/inventory/stock-level.d.ts
+/**
+ * Stock quantities as NOMINAL types, so "how many are there" and "how many may
+ * I still promise" cannot be passed for one another.
+ *
+ * They are different questions with the same JavaScript type, and every layer
+ * re-derived the relationship between them: the flow ledger, the catalog
+ * bridge, the quant invariants, and the storefront cache each knew that
+ * available is on-hand minus reserved, and one of them still shipped on-hand
+ * into a field named `totalAvailable` — so the shop advertised units already
+ * held in someone else's cart and checkout refused the sale it had promised.
+ *
+ * Same fix as money's `MinorUnits<C>` brand, and for the same reason: a unit
+ * confusion that a reviewer must notice becomes one the compiler refuses.
+ * Zero runtime cost — the brands erase at compile time.
+ */
+/** Units physically present. INCLUDES units promised to open carts. */
+type OnHand = Brand<number, "OnHand">;
+/** Units held against an owner (cart, order, move group) — present, not free. */
+type Reserved = Brand<number, "Reserved">;
+/**
+ * Units that may still be promised to a NEW buyer: `onHand - reserved`.
+ *
+ * Constructible only via {@link sellable}, which is what makes passing on-hand
+ * where sellable is required a type error rather than an oversell.
+ */
+type Sellable = Brand<number, "Sellable">;
+/** What a location holds, as the ledger records it. */
+interface StockLevel {
+  readonly onHand: OnHand;
+  readonly reserved: Reserved;
+}
+declare const onHand: (n: number) => OnHand;
+declare const reserved: (n: number) => Reserved;
+/**
+ * The ONE definition of sellable stock.
+ *
+ * Deliberately NOT clamped at zero. Writing stock off below what is already
+ * reserved (goods damaged after being promised) is a real state, not an error —
+ * you cannot un-promise a cart. A negative reads as OVERSOLD, and every
+ * consumer already treats `<= 0` as unsellable; clamping would erase the only
+ * signal operations has that the condition exists.
+ */
+declare const sellable: (level: StockLevel) => Sellable;
+/** `true` when more is promised than is physically present. */
+declare const isOversold: (level: StockLevel) => boolean;
+/**
+ * Build a level from a ledger row, whatever it calls its fields.
+ *
+ * A quant reports all three; `available` is IGNORED on purpose and recomputed,
+ * so a source whose stored total has drifted cannot import that drift.
+ */
+declare const levelOf: (row: {
+  quantityOnHand?: number;
+  quantityReserved?: number;
+}) => StockLevel;
+//#endregion
+export { OnHand, Reserved, Sellable, StockLevel, isOversold, levelOf, onHand, reserved, sellable };

package/dist/stock-level.mjs

@@ -0,0 +1,27 @@
+//#region src/inventory/stock-level.ts
+const onHand = (n) => n;
+const reserved = (n) => n;
+/**
+* The ONE definition of sellable stock.
+*
+* Deliberately NOT clamped at zero. Writing stock off below what is already
+* reserved (goods damaged after being promised) is a real state, not an error —
+* you cannot un-promise a cart. A negative reads as OVERSOLD, and every
+* consumer already treats `<= 0` as unsellable; clamping would erase the only
+* signal operations has that the condition exists.
+*/
+const sellable = (level) => level.onHand - level.reserved;
+/** `true` when more is promised than is physically present. */
+const isOversold = (level) => sellable(level) < 0;
+/**
+* Build a level from a ledger row, whatever it calls its fields.
+*
+* A quant reports all three; `available` is IGNORED on purpose and recomputed,
+* so a source whose stored total has drifted cannot import that drift.
+*/
+const levelOf = (row) => ({
+	onHand: onHand(row.quantityOnHand ?? 0),
+	reserved: reserved(row.quantityReserved ?? 0)
+});
+//#endregion
+export { isOversold, levelOf, onHand, reserved, sellable };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -185,6 +185,10 @@
       "types": "./dist/mixin.d.mts",
       "default": "./dist/mixin.mjs"
     },
+    "./deadline": {
+      "types": "./dist/deadline.d.mts",
+      "default": "./dist/deadline.mjs"
+    },
     "./sla-policy": {
       "types": "./dist/sla-policy.d.mts",
       "default": "./dist/sla-policy.mjs"
@@ -213,6 +217,14 @@
     "./item-identity": {
       "types": "./dist/item-identity.d.mts",
       "default": "./dist/item-identity.mjs"
+    },
+    "./stock-level": {
+      "types": "./dist/stock-level.d.mts",
+      "default": "./dist/stock-level.mjs"
+    },
+    "./item-facts": {
+      "types": "./dist/item-facts.d.mts",
+      "default": "./dist/item-facts.mjs"
     }
   },
   "files": [