@classytic/primitives 0.18.0 → 0.20.0

package/dist/memory-outbox.mjs

@@ -0,0 +1,172 @@
+import { InvalidOutboxEventError, OutboxOwnershipError } from "./outbox.mjs";
+//#region src/events/memory-outbox.ts
+/**
+* In-memory outbox store — reference implementation for dev / testing.
+*
+* Supports the full `OutboxStore` capability set (claim/lease, fail/retry,
+* dedupe, visibleAt). Production deployments should pass a `repository` to
+* `EventOutbox` instead of using this; the memory store exists for unit
+* tests and single-process dev where durable persistence is noise.
+*/
+const DEFAULT_LEASE_MS = 3e4;
+var MemoryOutboxStore = class {
+	entries = [];
+	seenDedupeKeys = /* @__PURE__ */ new Set();
+	/**
+	* Drop every entry (including delivered / failed / dead-lettered rows) and
+	* the dedupe-key memory.
+	*
+	* For tests only — it is the in-memory analogue of truncating the table, and
+	* exists so a suite can isolate cases against ONE store instance (the
+	* `reset` hook of `runOutboxStoreContract`). Not part of `OutboxStore`; a
+	* production store must never expose this.
+	*/
+	clear() {
+		this.entries.length = 0;
+		this.seenDedupeKeys.clear();
+	}
+	/**
+	* For tests only — every stored event regardless of status, in insertion
+	* order. The in-memory analogue of `SELECT * FROM outbox`, used by the
+	* `/event-infra` contract test to assert what a `purge` left behind. Not part
+	* of `OutboxStore`; a production store must never expose this.
+	*/
+	all() {
+		return this.entries.map((e) => e.event);
+	}
+	async save(event, options) {
+		if (!event?.type || typeof event.type !== "string") throw new InvalidOutboxEventError("event.type is required");
+		if (!event.meta?.id || typeof event.meta.id !== "string") throw new InvalidOutboxEventError("event.meta.id is required");
+		if (options?.dedupeKey) {
+			if (this.seenDedupeKeys.has(options.dedupeKey)) return;
+			this.seenDedupeKeys.add(options.dedupeKey);
+		}
+		this.entries.push({
+			createdAt: Date.now(),
+			event,
+			status: "pending",
+			attempts: 0,
+			visibleAt: options?.visibleAt?.getTime() ?? 0,
+			leaseOwner: null,
+			leaseExpiresAt: 0,
+			deliveredAt: null,
+			firstFailedAt: null,
+			lastFailedAt: null,
+			lastError: null,
+			dedupeKey: options?.dedupeKey
+		});
+	}
+	async getPending(limit) {
+		const now = Date.now();
+		return this.entries.filter((e) => e.status === "pending" && e.visibleAt <= now && (e.leaseOwner === null || e.leaseExpiresAt <= now)).slice(0, limit).map((e) => e.event);
+	}
+	async claimPending(options) {
+		const now = Date.now();
+		const limit = options?.limit ?? 100;
+		const leaseMs = options?.leaseMs ?? DEFAULT_LEASE_MS;
+		const consumerId = options?.consumerId ?? "anonymous";
+		const typeFilter = options?.types ? new Set(options.types) : null;
+		const claimed = [];
+		for (const entry of this.entries) {
+			if (claimed.length >= limit) break;
+			if (entry.status !== "pending") continue;
+			if (entry.visibleAt > now) continue;
+			if (entry.leaseOwner !== null && entry.leaseExpiresAt > now) continue;
+			if (typeFilter && !typeFilter.has(entry.event.type)) continue;
+			entry.leaseOwner = consumerId;
+			entry.leaseExpiresAt = now + leaseMs;
+			entry.attempts++;
+			claimed.push(entry.event);
+		}
+		return claimed;
+	}
+	async acknowledge(eventId, options) {
+		const entry = this.entries.find((e) => e.event.meta.id === eventId);
+		if (!entry) return;
+		if (entry.status === "delivered") return;
+		if (options?.consumerId && entry.leaseOwner && entry.leaseOwner !== options.consumerId) throw new OutboxOwnershipError(eventId, options.consumerId, entry.leaseOwner);
+		entry.status = "delivered";
+		entry.deliveredAt = Date.now();
+		entry.leaseOwner = null;
+	}
+	async fail(eventId, error, options) {
+		const entry = this.entries.find((e) => e.event.meta.id === eventId);
+		if (!entry) return;
+		if (options?.consumerId && entry.leaseOwner && entry.leaseOwner !== options.consumerId) throw new OutboxOwnershipError(eventId, options.consumerId, entry.leaseOwner);
+		const now = Date.now();
+		entry.lastError = error;
+		entry.leaseOwner = null;
+		entry.leaseExpiresAt = 0;
+		if (entry.firstFailedAt === null) entry.firstFailedAt = now;
+		entry.lastFailedAt = now;
+		if (options?.deadLetter) {
+			entry.status = "dead_letter";
+			return;
+		}
+		entry.status = "pending";
+		entry.visibleAt = options?.retryAt ? options.retryAt.getTime() : 0;
+	}
+	async getDeadLettered(limit) {
+		const out = [];
+		for (const entry of this.entries) {
+			if (out.length >= limit) break;
+			if (entry.status !== "dead_letter") continue;
+			out.push({
+				event: entry.event,
+				error: {
+					message: entry.lastError?.message ?? "unknown",
+					...entry.lastError?.code !== void 0 ? { code: entry.lastError.code } : {}
+				},
+				attempts: entry.attempts,
+				firstFailedAt: new Date(entry.firstFailedAt ?? entry.lastFailedAt ?? Date.now()),
+				lastFailedAt: new Date(entry.lastFailedAt ?? entry.firstFailedAt ?? Date.now())
+			});
+		}
+		return out;
+	}
+	async purge(olderThanMs) {
+		const cutoff = Date.now() - olderThanMs;
+		let purged = 0;
+		for (let i = this.entries.length - 1; i >= 0; i--) {
+			const entry = this.entries[i];
+			if (!entry) continue;
+			if (entry.status === "delivered" && entry.deliveredAt !== null && entry.deliveredAt < cutoff) {
+				if (entry.dedupeKey) this.seenDedupeKeys.delete(entry.dedupeKey);
+				this.entries.splice(i, 1);
+				purged++;
+			}
+		}
+		return purged;
+	}
+	/**
+	* Re-drive one dead-lettered row. Scoped to `dead_letter`: a row that is merely
+	* backing off must keep its attempt count, and the id alone cannot tell the two apart.
+	*/
+	async requeue(eventId) {
+		const entry = this.entries.find((e) => e.event.meta.id === eventId && e.status === "dead_letter");
+		if (!entry) return false;
+		entry.status = "pending";
+		entry.attempts = 0;
+		entry.leaseOwner = null;
+		entry.leaseExpiresAt = 0;
+		entry.visibleAt = 0;
+		entry.lastError = null;
+		return true;
+	}
+	async countByStatus(status) {
+		return this.entries.filter((e) => e.status === status).length;
+	}
+	/** Age of the oldest PENDING row — see `MemoryEntry.createdAt` for why not `visibleAt`. */
+	async oldestPendingAgeMs() {
+		const pending = this.entries.filter((e) => e.status === "pending");
+		if (pending.length === 0) return null;
+		const oldest = Math.min(...pending.map((e) => e.createdAt));
+		return Date.now() - oldest;
+	}
+	/** Test helper: inspect entry by id */
+	_getEntry(eventId) {
+		return this.entries.find((e) => e.event.meta.id === eventId);
+	}
+};
+//#endregion
+export { MemoryOutboxStore };

package/dist/monetization.d.mts

@@ -0,0 +1,195 @@
+import { n as Money } from "./money-DPo9fLBi.mjs";
+
+//#region src/money/monetization.d.ts
+/**
+ * A map of currency code → {@link Money} for explicit per-currency pricing.
+ * Explicit entries always win over a currency-conversion fallback.
+ *
+ * Canonical home (was hand-declared in `@classytic/catalog`; re-exported there
+ * for back-compat). Belongs with money because it is a money-shaped value.
+ */
+type MoneyByCurrency = Record<string, Money>;
+/**
+ * The canonical monetization kinds. Order is stable; append only.
+ *
+ *   - `free`         — no charge.
+ *   - `one_time`     — charged once (catalog `one_time`; revenue `purchase`).
+ *   - `subscription` — recurring plan / membership.
+ *   - `bundle`       — a composite priced from its members.
+ *   - `usage`        — metered / per-seat / consumption (billed per unit or in
+ *                      arrears). The extension point for rating models.
+ */
+declare const MONETIZATION_KINDS: readonly ["free", "one_time", "subscription", "bundle", "usage"];
+type MonetizationKind = (typeof MONETIZATION_KINDS)[number];
+/** True when `value` is one of the canonical kinds. */
+declare function isMonetizationKind(value: unknown): value is MonetizationKind;
+/** A quantity-based price break. `price` (fixed override) XOR `discountPercent`. */
+interface PriceTier {
+  /** Minimum quantity to qualify. */
+  readonly minQuantity: number;
+  /** Fixed override price for this tier. */
+  readonly price?: Money;
+  /** OR a percentage discount (0–100). Mutually exclusive with `price`. */
+  readonly discountPercent?: number;
+}
+interface OneTimePricing {
+  /** Required base (list) price. */
+  readonly basePrice: Money;
+  /** Default currency (redundant with `basePrice.currency`, indexed for queries). */
+  readonly currency: string;
+  /** Optional strikethrough / MSRP price. */
+  readonly compareAtPrice?: Money;
+  /** Explicit per-currency price overrides. */
+  readonly priceByCurrency?: MoneyByCurrency;
+  /** Optional cost (role-gated — filtered for non-finance readers). */
+  readonly costPrice?: Money;
+  /** Optional volume tiers (quantity-based discounts). */
+  readonly tiers?: readonly PriceTier[];
+}
+type DurationUnit = 'day' | 'week' | 'month' | 'year';
+interface SubscriptionPlan {
+  /** Internal key ('monthly', 'quarterly', 'annual'). */
+  readonly key: string;
+  /** Display label ("Monthly", "Annual (save 20%)"). */
+  readonly label: string;
+  /** Base price for this plan in the default currency. */
+  readonly price: Money;
+  /** Explicit per-currency overrides. */
+  readonly priceByCurrency?: MoneyByCurrency;
+  /** Billing cycle length. */
+  readonly duration: number;
+  /** Unit of the billing cycle. */
+  readonly durationUnit: DurationUnit;
+  /** Optional free trial length in days. */
+  readonly trialDays?: number;
+  /** Optional auto-calculated discount vs the highest-frequency plan. */
+  readonly discount?: number;
+}
+/**
+ * One band of a metered rate table.
+ *
+ * `upTo` is the inclusive upper bound of the band; omit it for the final,
+ * open-ended band. Within a band either a `perUnit` rate applies (per metered
+ * unit) or a `flatPrice` (a stairstep charge for landing in the band).
+ */
+interface UsageTier {
+  readonly upTo?: number;
+  readonly perUnit?: Money;
+  readonly flatPrice?: Money;
+}
+/**
+ * How a metered unit is priced. One `scheme`, composed with the fields it needs
+ * — this single shape covers per-seat, metered, graduated, volume, package and
+ * base-plus-overage without a separate kind for each.
+ *
+ *   - `per_unit` — price × quantity (per-seat licensing, flat metering).
+ *   - `tiered`   — graduated: each unit priced at the rate of the band it falls in.
+ *   - `volume`   — the WHOLE quantity priced at the band the total lands in.
+ *   - `package`  — priced per package of `packageSize` units.
+ *
+ * `includedUnits` are free before metering starts (base-plus-overage when paired
+ * with {@link UsageMonetization.baseFee}).
+ */
+interface UsageRating {
+  readonly scheme: 'per_unit' | 'tiered' | 'volume' | 'package';
+  /** Flat per-unit rate (`per_unit` scheme). */
+  readonly perUnit?: Money;
+  /** Rate table (`tiered` / `volume` schemes). */
+  readonly tiers?: readonly UsageTier[];
+  /** Units per package and the package price (`package` scheme). */
+  readonly packageSize?: number;
+  readonly packagePrice?: Money;
+  /** Free units before metering starts (base-plus-overage). */
+  readonly includedUnits?: number;
+  /** Display label for one unit ("seat", "GB", "call", "visit"). */
+  readonly unitLabel?: string;
+}
+interface FreeMonetization {
+  readonly type: 'free';
+}
+interface OneTimeMonetization {
+  readonly type: 'one_time';
+  readonly pricing: OneTimePricing;
+}
+interface SubscriptionMonetization {
+  readonly type: 'subscription';
+  /** At least one plan is required. */
+  readonly plans: readonly SubscriptionPlan[];
+}
+interface BundleMonetization {
+  readonly type: 'bundle';
+  /** Optional fixed bundle price (overrides the dynamic sum). */
+  readonly basePrice?: Money;
+  /** How bundle pricing is computed. */
+  readonly pricingMode: 'fixed' | 'dynamic';
+  /** For `dynamic` mode, an optional 0–100 discount on the members' sum. */
+  readonly dynamicDiscountPercent?: number;
+}
+/**
+ * Metered / consumption pricing. The extension point for per-seat, metered,
+ * graduated, volume, package and base-plus-overage — all via {@link UsageRating}
+ * so the classification does not grow one kind per rating model.
+ */
+interface UsageMonetization {
+  readonly type: 'usage';
+  /** Optional recurring base fee charged regardless of usage (base + overage). */
+  readonly baseFee?: Money;
+  /** How each metered unit is priced. */
+  readonly rating: UsageRating;
+  /** Settlement cadence when usage is billed in arrears. */
+  readonly billingPeriod?: {
+    readonly duration: number;
+    readonly durationUnit: DurationUnit;
+  };
+}
+/**
+ * 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;
+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;
+/** The kind of a monetization value (its discriminant, narrowed to the union). */
+declare const monetizationKindOf: (m: Monetization) => MonetizationKind;
+/**
+ * The single headline unit price for a monetization, or `null` when there isn't
+ * one. This is the ONE place that decides "which number is the price" per kind,
+ * so a cart line, an order snapshot and a storefront card never re-`switch` on
+ * `type` and drift (a host that read `plans[0].price` while another read
+ * `plans[1]` is exactly the divergence this prevents).
+ *
+ *   - `one_time`     → the base (list) price
+ *   - `subscription` → the first plan's price (the default / most-frequent plan)
+ *   - `bundle`       → the FIXED bundle price; `null` in `dynamic` mode (that
+ *                      price is computed from the members, not stored here)
+ *   - `free`         → `null`
+ *   - `usage`        → `null` — a metered item has no single unit price; it is
+ *                      rated per consumption via {@link UsageRating}
+ *
+ * Exhaustive on purpose: a new kind fails to compile here until it declares how
+ * 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`). */
+declare function compareAtPriceOf(m: Monetization): Money | null;
+/**
+ * `@classytic/revenue`'s coarse wire enum. `purchase` is the paid-once case that
+ * the rest of the ecosystem calls `one_time`. Kept as its own type so revenue's
+ * PERSISTED values never have to change — only the mapping to the canonical kind
+ * lives here, in one place, instead of an implicit hand-conversion per call site.
+ */
+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").
+ */
+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, UsageMonetization, UsageRating, UsageTier, compareAtPriceOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isSubscriptionMonetization, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };

package/dist/monetization.mjs

@@ -0,0 +1,79 @@
+//#region src/money/monetization.ts
+/**
+* The canonical monetization kinds. Order is stable; append only.
+*
+*   - `free`         — no charge.
+*   - `one_time`     — charged once (catalog `one_time`; revenue `purchase`).
+*   - `subscription` — recurring plan / membership.
+*   - `bundle`       — a composite priced from its members.
+*   - `usage`        — metered / per-seat / consumption (billed per unit or in
+*                      arrears). The extension point for rating models.
+*/
+const MONETIZATION_KINDS = [
+	"free",
+	"one_time",
+	"subscription",
+	"bundle",
+	"usage"
+];
+const MONETIZATION_KIND_SET = new Set(MONETIZATION_KINDS);
+/** True when `value` is one of the canonical kinds. */
+function isMonetizationKind(value) {
+	return typeof value === "string" && MONETIZATION_KIND_SET.has(value);
+}
+const isFreeMonetization = (m) => m.type === "free";
+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";
+/** The kind of a monetization value (its discriminant, narrowed to the union). */
+const monetizationKindOf = (m) => m.type;
+/**
+* The single headline unit price for a monetization, or `null` when there isn't
+* one. This is the ONE place that decides "which number is the price" per kind,
+* so a cart line, an order snapshot and a storefront card never re-`switch` on
+* `type` and drift (a host that read `plans[0].price` while another read
+* `plans[1]` is exactly the divergence this prevents).
+*
+*   - `one_time`     → the base (list) price
+*   - `subscription` → the first plan's price (the default / most-frequent plan)
+*   - `bundle`       → the FIXED bundle price; `null` in `dynamic` mode (that
+*                      price is computed from the members, not stored here)
+*   - `free`         → `null`
+*   - `usage`        → `null` — a metered item has no single unit price; it is
+*                      rated per consumption via {@link UsageRating}
+*
+* Exhaustive on purpose: a new kind fails to compile here until it declares how
+* it prices, instead of silently returning `null`.
+*/
+function unitPriceOf(m) {
+	switch (m.type) {
+		case "one_time": return m.pricing.basePrice;
+		case "subscription": return m.plans[0]?.price ?? null;
+		case "bundle": return m.basePrice ?? null;
+		case "free":
+		case "usage": return null;
+	}
+}
+/** The strikethrough / MSRP price, if the kind carries one (only `one_time`). */
+function compareAtPriceOf(m) {
+	return m.type === "one_time" ? m.pricing.compareAtPrice ?? null : 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").
+*/
+function toRevenueMonetizationType(kind) {
+	if (kind === "free") return "free";
+	if (kind === "subscription") return "subscription";
+	return "purchase";
+}
+/** Revenue wire type → canonical kind (`purchase` → `one_time`). */
+function fromRevenueMonetizationType(type) {
+	if (type === "free") return "free";
+	if (type === "subscription") return "subscription";
+	return "one_time";
+}
+//#endregion
+export { MONETIZATION_KINDS, compareAtPriceOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isSubscriptionMonetization, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };