@classytic/primitives 0.7.2 → 0.8.0

package/dist/shelf-life.d.mts

@@ -0,0 +1,114 @@
+//#region src/scheduling/shelf-life.d.ts
+/**
+ * Shelf-life / lot-tracking policy + pure expiry-date derivation.
+ *
+ * Describes whether a SKU is tracked by lot/serial, whether it carries an
+ * expiration date, and the day-offsets used to derive the four lifecycle
+ * dates of a freshly-received lot. The *policy* is product-level metadata
+ * (owned by a catalog); the *derived dates* are per-lot facts (owned by a
+ * WMS). This module is the shared contract both speak so the shape can't
+ * drift between packages.
+ *
+ * Modeled on Odoo's `product_expiry` addon, which puts `tracking` +
+ * `use_expiration_date` and four integer day-deltas on `product.template`,
+ * then computes four dates on each `stock.lot`:
+ *
+ *   expiration = receivedAt + shelfLifeDays
+ *   bestBefore = expiration − bestBeforeDays   (still safe, starts deteriorating)
+ *   removal    = expiration − removalDays      (stop selling — FEFO sorts on THIS)
+ *   alert      = expiration − alertDays         (raise a reminder)
+ *
+ * Consumed by `@classytic/catalog` (variant tracking policy) and
+ * `@classytic/flow` (lot date derivation at receipt, FEFO, fresh-on-hand).
+ *
+ * Zero-dep, pure UTC day arithmetic — safe in unit tests with no clock.
+ *
+ * @example
+ * const policy: ShelfLifePolicy = {
+ *   mode: 'lot',
+ *   useExpiration: true,
+ *   shelfLifeDays: 540,   // 18-month medicine
+ *   removalDays: 30,      // pull 30 days before expiry
+ *   alertDays: 60,        // remind 60 days before expiry
+ * };
+ * deriveShelfLifeDates(new Date('2026-01-01T00:00:00Z'), policy);
+ * // → { expiresAt: 2027-06-25…, removalDate: 2027-05-26…, alertDate: 2027-04-26… }
+ */
+/** How a SKU's stock identity is tracked. Mirrors Odoo `product.tracking`. */
+type TrackingMode = 'none' | 'lot' | 'serial';
+interface ShelfLifePolicy {
+  /** `'none'` = tracked by quantity only; `'lot'` = batch; `'serial'` = unique unit. */
+  readonly mode: TrackingMode;
+  /**
+   * When `true`, received lots carry an expiration date and the freshness
+   * lifecycle (best-before / removal / alert) applies. When `false`, the
+   * SKU may still be lot/serial tracked for traceability but has no expiry.
+   */
+  readonly useExpiration: boolean;
+  /**
+   * Total shelf life in days: `expiration = receivedAt + shelfLifeDays`.
+   * Omit to require a manual expiration date at receipt (no auto-derivation).
+   */
+  readonly shelfLifeDays?: number;
+  /** Days before expiration when goods start deteriorating (best-before / use date). */
+  readonly bestBeforeDays?: number;
+  /**
+   * Days before expiration when goods must be pulled from sellable stock.
+   * This is the FEFO sort key and the fresh-on-hand cutoff — NOT the
+   * expiration date itself.
+   */
+  readonly removalDays?: number;
+  /** Days before expiration when an expiry reminder should fire. */
+  readonly alertDays?: number;
+}
+/** The four lifecycle dates of a received lot. All optional — only what the policy can derive. */
+interface ShelfLifeDates {
+  readonly expiresAt?: Date;
+  readonly bestBeforeDate?: Date;
+  readonly removalDate?: Date;
+  readonly alertDate?: Date;
+}
+interface DeriveOptions {
+  /**
+   * Explicit expiration date — overrides `shelfLifeDays` derivation (manual
+   * receiving, GS1-scanned expiry). The other three dates are then offset
+   * back from THIS date, matching Odoo's edit-expiration behavior.
+   */
+  readonly expiresAt?: Date;
+}
+type ShelfLifeErrorCode = 'INVALID_MODE' | 'INVALID_DAYS' | 'INVALID_RECEIVED_AT' | 'INVALID_EXPIRES_AT';
+declare class ShelfLifeError extends Error {
+  readonly name = "ShelfLifeError";
+  readonly code: ShelfLifeErrorCode;
+  constructor(code: ShelfLifeErrorCode, message: string);
+}
+/** True when the policy requires lot OR serial identity (i.e. lots get created). */
+declare function isTracked(policy: ShelfLifePolicy): boolean;
+/** True when received lots carry an expiration date. */
+declare function isExpiryTracked(policy: ShelfLifePolicy): boolean;
+/** Validate a policy. Call before storing host-side. */
+declare function validateShelfLifePolicy(policy: ShelfLifePolicy): void;
+/**
+ * Derive the four lifecycle dates for a lot received at `receivedAt`.
+ *
+ * Returns an empty object when the policy does not track expiry (`mode:
+ * 'none'` or `useExpiration: false`) and no explicit `expiresAt` override is
+ * given. Each of the three sub-dates is emitted only when both an expiration
+ * date resolves AND the corresponding offset is present in the policy.
+ *
+ * Offsets are clamped to never produce a date before `receivedAt` (an offset
+ * larger than the shelf life would otherwise yield a removal date in the
+ * past on day one).
+ */
+declare function deriveShelfLifeDates(receivedAt: Date, policy: ShelfLifePolicy, opts?: DeriveOptions): ShelfLifeDates;
+type ShelfLifeStatus = 'none' | 'fresh' | 'alert' | 'removed' | 'expired';
+/**
+ * Classify a lot's freshness as of `asOf`. `'removed'` means past its removal
+ * date (excluded from fresh-on-hand even though not yet expired); `'expired'`
+ * means past the hard expiration date. Returns `'none'` when no dates apply.
+ *
+ * Precedence (most severe first): expired > removed > alert > fresh.
+ */
+declare function shelfLifeStatus(dates: ShelfLifeDates, asOf: Date): ShelfLifeStatus;
+//#endregion
+export { DeriveOptions, ShelfLifeDates, ShelfLifeError, ShelfLifeErrorCode, ShelfLifePolicy, ShelfLifeStatus, TrackingMode, deriveShelfLifeDates, isExpiryTracked, isTracked, shelfLifeStatus, validateShelfLifePolicy };

package/dist/shelf-life.mjs

@@ -0,0 +1,88 @@
+//#region src/scheduling/shelf-life.ts
+var ShelfLifeError = class extends Error {
+	name = "ShelfLifeError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+const DAY_MS = 1440 * 60 * 1e3;
+const TRACKING_MODES = [
+	"none",
+	"lot",
+	"serial"
+];
+/** True when the policy requires lot OR serial identity (i.e. lots get created). */
+function isTracked(policy) {
+	return policy.mode !== "none";
+}
+/** True when received lots carry an expiration date. */
+function isExpiryTracked(policy) {
+	return policy.mode !== "none" && policy.useExpiration;
+}
+/** Validate a policy. Call before storing host-side. */
+function validateShelfLifePolicy(policy) {
+	if (!TRACKING_MODES.includes(policy.mode)) throw new ShelfLifeError("INVALID_MODE", `mode must be one of ${TRACKING_MODES.join(", ")}, got ${String(policy.mode)}`);
+	for (const [key, val] of [
+		["shelfLifeDays", policy.shelfLifeDays],
+		["bestBeforeDays", policy.bestBeforeDays],
+		["removalDays", policy.removalDays],
+		["alertDays", policy.alertDays]
+	]) {
+		if (val === void 0) continue;
+		if (!Number.isFinite(val) || val < 0) throw new ShelfLifeError("INVALID_DAYS", `${key} must be a non-negative number, got ${String(val)}`);
+	}
+}
+/**
+* Derive the four lifecycle dates for a lot received at `receivedAt`.
+*
+* Returns an empty object when the policy does not track expiry (`mode:
+* 'none'` or `useExpiration: false`) and no explicit `expiresAt` override is
+* given. Each of the three sub-dates is emitted only when both an expiration
+* date resolves AND the corresponding offset is present in the policy.
+*
+* Offsets are clamped to never produce a date before `receivedAt` (an offset
+* larger than the shelf life would otherwise yield a removal date in the
+* past on day one).
+*/
+function deriveShelfLifeDates(receivedAt, policy, opts = {}) {
+	validateShelfLifePolicy(policy);
+	if (Number.isNaN(receivedAt.getTime())) throw new ShelfLifeError("INVALID_RECEIVED_AT", "receivedAt is not a valid Date");
+	if (opts.expiresAt && Number.isNaN(opts.expiresAt.getTime())) throw new ShelfLifeError("INVALID_EXPIRES_AT", "opts.expiresAt is not a valid Date");
+	let expiresAt;
+	if (opts.expiresAt) expiresAt = opts.expiresAt;
+	else if (isExpiryTracked(policy) && policy.shelfLifeDays !== void 0) expiresAt = addDays(receivedAt, policy.shelfLifeDays);
+	if (!expiresAt) return {};
+	const floor = receivedAt.getTime();
+	const offsetBack = (days) => days === void 0 ? void 0 : new Date(Math.max(floor, expiresAt.getTime() - days * DAY_MS));
+	return {
+		expiresAt,
+		...defined("bestBeforeDate", offsetBack(policy.bestBeforeDays)),
+		...defined("removalDate", offsetBack(policy.removalDays)),
+		...defined("alertDate", offsetBack(policy.alertDays))
+	};
+}
+/**
+* Classify a lot's freshness as of `asOf`. `'removed'` means past its removal
+* date (excluded from fresh-on-hand even though not yet expired); `'expired'`
+* means past the hard expiration date. Returns `'none'` when no dates apply.
+*
+* Precedence (most severe first): expired > removed > alert > fresh.
+*/
+function shelfLifeStatus(dates, asOf) {
+	const now = asOf.getTime();
+	if (!dates.expiresAt && !dates.removalDate && !dates.alertDate) return "none";
+	if (dates.expiresAt && now >= dates.expiresAt.getTime()) return "expired";
+	if (dates.removalDate && now >= dates.removalDate.getTime()) return "removed";
+	if (dates.alertDate && now >= dates.alertDate.getTime()) return "alert";
+	return "fresh";
+}
+function addDays(d, days) {
+	return new Date(d.getTime() + days * DAY_MS);
+}
+function defined(key, val) {
+	return val === void 0 ? {} : { [key]: val };
+}
+//#endregion
+export { ShelfLifeError, deriveShelfLifeDates, isExpiryTracked, isTracked, shelfLifeStatus, validateShelfLifePolicy };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -81,6 +81,10 @@
       "types": "./dist/sla.d.mts",
       "default": "./dist/sla.mjs"
     },
+    "./shelf-life": {
+      "types": "./dist/shelf-life.d.mts",
+      "default": "./dist/shelf-life.mjs"
+    },
     "./person": {
       "types": "./dist/person.d.mts",
       "default": "./dist/person.mjs"