@classytic/primitives 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -3,6 +3,34 @@
 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.7.2] - 2026-05-30
+
+### Added — `BankTransaction` per-account routing + pending lifecycle fields
+
+Three additive optional fields on `BankTransaction` (`/bank-transaction`):
+
+- **`sourceAccountId?: string`** — the vendor-side account this row belongs to
+  (Plaid `account_id`, Xero `BankAccount.AccountID`). Sync feeds return
+  transactions spanning multiple accounts in one batch; this lets consumers
+  route each row to the right account per-transaction (multi-account sync)
+  instead of forcing the whole batch onto one account. Statement formats
+  (single-account files) leave it undefined — the account lives on
+  `BankStatement.account`.
+- **`pending?: boolean`** — the entry hasn't posted/cleared yet (real-time
+  feeds like Plaid `pending: true`; statement formats leave it undefined).
+  Consumers must treat pending rows as provisional — don't reconcile/post
+  them as final.
+- **`supersedesExternalId?: string`** — set on a POSTED row that replaces an
+  earlier PENDING one, carrying the pending row's `externalId` (Plaid
+  `pending_transaction_id`). Pending and posted rows have different
+  `externalId`s, so consumers MUST use this back-pointer to drop/replace the
+  superseded pending row on ingest — otherwise both persist as duplicates.
+
+Backward-compatible (both optional). Closes a fidelity gap where Plaid's
+pending state was dropped at the canonical boundary, so downstream consumers
+(`@classytic/fin-io` Plaid mapper, `@classytic/revenue` import) couldn't
+distinguish provisional rows or dedupe pending→posted.
+
 ## [0.7.1] - 2026-05-26
 
 ### Added — workflow + scheduling + composition primitives

package/dist/bank-transaction.d.mts

@@ -96,6 +96,41 @@ interface BankTransaction {
   balanceAfter?: Money;
   /** Format-specific entry-type code (`'DEBIT'`, `'CREDIT'`, `'CHECK'`, …). */
   type?: string;
+  /**
+   * Vendor-side identifier of the account this row belongs to — Plaid
+   * `account_id`, Xero `BankAccount.AccountID`. Sync feeds return transactions
+   * spanning MULTIPLE accounts in one batch, so this lets a consumer route
+   * each row to the right destination account per-transaction (multi-account
+   * sync) instead of forcing the whole batch onto one account.
+   *
+   * Statement formats (OFX / CAMT.053 / MT940 / CSV / IIF) are single-account
+   * files — they carry the account on `BankStatement.account` and leave this
+   * `undefined`. Distinct from any consumer-side account id (e.g. the host's
+   * own `bankAccountId` used in the import unique index).
+   */
+  sourceAccountId?: string;
+  /**
+   * The entry has not yet posted / cleared — the bank may still change its
+   * amount, description, or drop it entirely. Real-time feeds populate this
+   * (Plaid `pending: true`); statement formats (OFX / CAMT.053 / MT940 / CSV)
+   * only ever carry settled rows and leave it `undefined`.
+   *
+   * Consumers MUST treat `pending: true` rows as provisional — do not
+   * reconcile or post them as final, and expect a superseding posted row to
+   * arrive later (linked via `supersedesExternalId`).
+   */
+  pending?: boolean;
+  /**
+   * Set on a POSTED row that replaces an earlier PENDING one: the
+   * `externalId` of the pending row this entry supersedes (Plaid
+   * `pending_transaction_id`).
+   *
+   * The pending and posted rows carry DIFFERENT `externalId`s, so dedup on
+   * `externalId` alone can't collapse them — consumers MUST use this
+   * back-pointer to drop / replace the superseded pending row on ingest, or
+   * both versions persist as duplicates.
+   */
+  supersedesExternalId?: string;
   /**
    * Format-specific raw record. Pass-through for audit / debugging.
    * Consumers MUST NOT rely on this — schema may change between fin-io

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.1",
+  "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"