@classytic/primitives 0.5.0 → 0.7.0

package/dist/sla-policy.d.mts

@@ -0,0 +1,116 @@
+import { IsoWeekday } from "./cadence.mjs";
+import { SLA } from "./sla.mjs";
+
+//#region src/scheduling/sla-policy.d.ts
+/**
+ * Tier of severity. Hosts decide the keys ('urgent' / 'p0' / 'gold' / etc.) —
+ * keep them stable across the org so reports and routing stay consistent.
+ */
+type PriorityKey = string;
+interface PriorityRule {
+  /** Time allotted for the FIRST reply. */
+  readonly firstResponseMs: number;
+  /** Time allotted for EACH subsequent reply (after first response was made). */
+  readonly rollingResponseMs: number;
+}
+/**
+ * Working-hours window. Times are minutes-since-midnight in the org's
+ * timezone — same convention as `cadence` for ISO weekdays.
+ *
+ * For simple "always on" SLAs, omit this field entirely.
+ */
+interface WorkingHours {
+  /** ISO weekdays when work happens (1=Mon … 7=Sun). */
+  readonly weekdays: readonly IsoWeekday[];
+  readonly startMinute: number;
+  readonly endMinute: number;
+  /**
+   * IANA timezone (e.g. `'Asia/Dhaka'`). Optional — pure math here is UTC,
+   * but the host can localize when displaying.
+   */
+  readonly timezone?: string;
+  /**
+   * Dates to skip entirely (holidays). Stored as YYYY-MM-DD strings so
+   * round-trips through JSON stay lossless.
+   */
+  readonly holidays?: readonly string[];
+}
+interface SLAPolicy {
+  readonly id?: string;
+  readonly name: string;
+  /** Map of priority → durations. Must include `defaultPriority`. */
+  readonly priorities: Readonly<Record<PriorityKey, PriorityRule>>;
+  readonly defaultPriority: PriorityKey;
+  /** Optional — omit for 24/7 SLAs. */
+  readonly workingHours?: WorkingHours;
+  /** Optional human label for dashboards. */
+  readonly label?: string;
+}
+type SLAPolicyErrorCode = 'EMPTY_PRIORITIES' | 'UNKNOWN_DEFAULT' | 'INVALID_DURATION' | 'INVALID_HOURS';
+declare class SLAPolicyError extends Error {
+  readonly name = "SLAPolicyError";
+  readonly code: SLAPolicyErrorCode;
+  constructor(code: SLAPolicyErrorCode, message: string);
+}
+/** Validate + freeze. Use this when registering a policy at app boot. */
+declare function defineSLAPolicy(spec: SLAPolicy): SLAPolicy;
+/**
+ * Convert a `SLAPolicy + priority` into the simpler `SLA` value object the
+ * `./sla` module already knows how to evaluate. The host stores the policy
+ * once; per-entity it persists `{ slaPolicyId, priority, startedAt }` and
+ * derives the SLA on demand.
+ */
+declare function deriveFirstResponseSLA(policy: SLAPolicy, priority?: PriorityKey): SLA;
+declare function deriveRollingResponseSLA(policy: SLAPolicy, priority?: PriorityKey): SLA;
+/**
+ * Materialized SLA state at evaluation time. Hosts persist the inputs
+ * (`startedAt`, `firstRespondedAt`, `lastRespondedAt`); the output is derived
+ * on read so changes to the policy take effect immediately.
+ */
+type SLAStatusKind = 'FirstResponseDue' | 'FirstResponseFulfilled' | 'RollingResponseDue' | 'Failed';
+interface SLAStatus {
+  readonly kind: SLAStatusKind;
+  readonly responseBy: Date;
+  readonly remainingMs: number;
+  readonly breached: boolean;
+  /** Which SLA was driving the deadline calculation. */
+  readonly underlying: SLA;
+}
+interface SLAInputs {
+  readonly priority?: PriorityKey;
+  readonly startedAt: Date;
+  /** Set when the first agent reply has been recorded. */
+  readonly firstRespondedAt: Date | null;
+  /**
+   * Set to the most recent agent reply that closed the rolling window.
+   * Falls back to `firstRespondedAt` when no rolling cycle has elapsed.
+   */
+  readonly lastRespondedAt: Date | null;
+}
+/**
+ * Compute current SLA status against a policy. Pure — no clock side effects
+ * beyond the explicit `now` argument.
+ *
+ * Decision table:
+ *   - firstRespondedAt == null  → FirstResponseDue/Failed against firstResponseMs
+ *   - firstRespondedAt set, no further outstanding cycle → FirstResponseFulfilled
+ *   - firstRespondedAt set + a rolling cycle has started → RollingResponseDue/Failed
+ *
+ * The "rolling cycle has started" half is host-driven: when the customer
+ * replies again, the host sets `lastRespondedAt` to the prior agent reply
+ * and the SLA clock resumes from there. Until that happens, the status is
+ * `FirstResponseFulfilled`.
+ */
+declare function evaluateSLAStatus(policy: SLAPolicy, inputs: SLAInputs, now?: Date): SLAStatus;
+/**
+ * Is `instant` within the policy's working hours? Returns `true` when the
+ * policy has no `workingHours` defined (always-on SLA).
+ *
+ * NOTE: math here is UTC-based for determinism — if the host needs the
+ * policy in local time, normalize `instant` to the policy's `timezone`
+ * before passing in. Bringing a tz lib into `@classytic/primitives` is a
+ * dep we don't want.
+ */
+declare function isWithinWorkingHours(policy: SLAPolicy, instant: Date): boolean;
+//#endregion
+export { PriorityKey, PriorityRule, SLAInputs, SLAPolicy, SLAPolicyError, SLAPolicyErrorCode, SLAStatus, SLAStatusKind, WorkingHours, defineSLAPolicy, deriveFirstResponseSLA, deriveRollingResponseSLA, evaluateSLAStatus, isWithinWorkingHours };

package/dist/sla-policy.mjs

@@ -0,0 +1,120 @@
+import { isBreached, remainingMs } from "./sla.mjs";
+//#region src/scheduling/sla-policy.ts
+var SLAPolicyError = class extends Error {
+	name = "SLAPolicyError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+/** Validate + freeze. Use this when registering a policy at app boot. */
+function defineSLAPolicy(spec) {
+	const keys = Object.keys(spec.priorities);
+	if (keys.length === 0) throw new SLAPolicyError("EMPTY_PRIORITIES", "priorities map is empty");
+	if (!keys.includes(spec.defaultPriority)) throw new SLAPolicyError("UNKNOWN_DEFAULT", `defaultPriority '${spec.defaultPriority}' is not present in priorities map`);
+	for (const [key, rule] of Object.entries(spec.priorities)) if (!Number.isFinite(rule.firstResponseMs) || rule.firstResponseMs <= 0 || !Number.isFinite(rule.rollingResponseMs) || rule.rollingResponseMs <= 0) throw new SLAPolicyError("INVALID_DURATION", `priority '${key}' has non-positive duration`);
+	if (spec.workingHours !== void 0) {
+		const wh = spec.workingHours;
+		if (wh.startMinute < 0 || wh.startMinute >= 1440 || wh.endMinute <= wh.startMinute || wh.endMinute > 1440 || wh.weekdays.length === 0) throw new SLAPolicyError("INVALID_HOURS", "workingHours bounds are invalid");
+	}
+	return spec;
+}
+/**
+* Convert a `SLAPolicy + priority` into the simpler `SLA` value object the
+* `./sla` module already knows how to evaluate. The host stores the policy
+* once; per-entity it persists `{ slaPolicyId, priority, startedAt }` and
+* derives the SLA on demand.
+*/
+function deriveFirstResponseSLA(policy, priority) {
+	return {
+		targetDurationMs: priorityRule(policy, priority).firstResponseMs,
+		breachPolicy: "escalate",
+		label: `${policy.name} · first response · ${priority ?? policy.defaultPriority}`
+	};
+}
+function deriveRollingResponseSLA(policy, priority) {
+	return {
+		targetDurationMs: priorityRule(policy, priority).rollingResponseMs,
+		breachPolicy: "escalate",
+		label: `${policy.name} · rolling response · ${priority ?? policy.defaultPriority}`
+	};
+}
+function priorityRule(policy, priority) {
+	const key = priority ?? policy.defaultPriority;
+	const rule = policy.priorities[key] ?? policy.priorities[policy.defaultPriority];
+	if (rule === void 0) throw new SLAPolicyError("UNKNOWN_DEFAULT", `priority '${key}' not found and defaultPriority resolution failed`);
+	return rule;
+}
+/**
+* Compute current SLA status against a policy. Pure — no clock side effects
+* beyond the explicit `now` argument.
+*
+* Decision table:
+*   - firstRespondedAt == null  → FirstResponseDue/Failed against firstResponseMs
+*   - firstRespondedAt set, no further outstanding cycle → FirstResponseFulfilled
+*   - firstRespondedAt set + a rolling cycle has started → RollingResponseDue/Failed
+*
+* The "rolling cycle has started" half is host-driven: when the customer
+* replies again, the host sets `lastRespondedAt` to the prior agent reply
+* and the SLA clock resumes from there. Until that happens, the status is
+* `FirstResponseFulfilled`.
+*/
+function evaluateSLAStatus(policy, inputs, now = /* @__PURE__ */ new Date()) {
+	if (inputs.firstRespondedAt === null) {
+		const sla = deriveFirstResponseSLA(policy, inputs.priority);
+		const responseBy = new Date(inputs.startedAt.getTime() + sla.targetDurationMs);
+		const breached = isBreached(sla, inputs.startedAt, now);
+		return {
+			kind: breached ? "Failed" : "FirstResponseDue",
+			responseBy,
+			remainingMs: remainingMs(sla, inputs.startedAt, now),
+			breached,
+			underlying: sla
+		};
+	}
+	const rollingBase = inputs.lastRespondedAt ?? inputs.firstRespondedAt;
+	if (rollingBase === inputs.firstRespondedAt && inputs.lastRespondedAt === null) {
+		const sla = deriveFirstResponseSLA(policy, inputs.priority);
+		return {
+			kind: "FirstResponseFulfilled",
+			responseBy: new Date(inputs.firstRespondedAt.getTime()),
+			remainingMs: 0,
+			breached: false,
+			underlying: sla
+		};
+	}
+	const sla = deriveRollingResponseSLA(policy, inputs.priority);
+	const responseBy = new Date(rollingBase.getTime() + sla.targetDurationMs);
+	const breached = isBreached(sla, rollingBase, now);
+	return {
+		kind: breached ? "Failed" : "RollingResponseDue",
+		responseBy,
+		remainingMs: remainingMs(sla, rollingBase, now),
+		breached,
+		underlying: sla
+	};
+}
+/**
+* Is `instant` within the policy's working hours? Returns `true` when the
+* policy has no `workingHours` defined (always-on SLA).
+*
+* NOTE: math here is UTC-based for determinism — if the host needs the
+* policy in local time, normalize `instant` to the policy's `timezone`
+* before passing in. Bringing a tz lib into `@classytic/primitives` is a
+* dep we don't want.
+*/
+function isWithinWorkingHours(policy, instant) {
+	if (!policy.workingHours) return true;
+	const wh = policy.workingHours;
+	const weekday = (instant.getUTCDay() + 6) % 7 + 1;
+	if (!wh.weekdays.includes(weekday)) return false;
+	if (wh.holidays !== void 0 && wh.holidays.length > 0) {
+		const isoDate = instant.toISOString().slice(0, 10);
+		if (wh.holidays.includes(isoDate)) return false;
+	}
+	const minuteOfDay = instant.getUTCHours() * 60 + instant.getUTCMinutes();
+	return minuteOfDay >= wh.startMinute && minuteOfDay < wh.endMinute;
+}
+//#endregion
+export { SLAPolicyError, defineSLAPolicy, deriveFirstResponseSLA, deriveRollingResponseSLA, evaluateSLAStatus, isWithinWorkingHours };

package/dist/sla.d.mts

@@ -1,4 +1,4 @@
-//#region src/sla.d.ts
+//#region src/scheduling/sla.d.ts
 /**
  * Service-Level Agreement value object + breach-detection helpers.
  *

package/dist/sla.mjs

@@ -1,4 +1,4 @@
-//#region src/sla.ts
+//#region src/scheduling/sla.ts
 var SLAError = class extends Error {
 	name = "SLAError";
 	code;

package/dist/split-allocation.d.mts

@@ -1,4 +1,4 @@
-//#region src/split-allocation.d.ts
+//#region src/money/split-allocation.d.ts
 /**
  * Deterministic integer allocation across N subjects.
  *

package/dist/split-allocation.mjs

@@ -1,4 +1,4 @@
-//#region src/split-allocation.ts
+//#region src/money/split-allocation.ts
 var SplitAllocationError = class extends Error {
 	name = "SplitAllocationError";
 	code;

package/dist/state-machine.d.mts

@@ -1,4 +1,4 @@
-//#region src/state-machine.d.ts
+//#region src/workflow/state-machine.d.ts
 /**
  * Declarative state-machine primitive.
  *

package/dist/state-machine.mjs

@@ -1,4 +1,4 @@
-//#region src/state-machine.ts
+//#region src/workflow/state-machine.ts
 /**
 * Declarative state-machine primitive.
 *

package/dist/status-history.d.mts

@@ -0,0 +1,85 @@
+//#region src/workflow/status-history.d.ts
+/**
+ * Generic, immutable status-change log.
+ *
+ * Every domain aggregate that has a state machine (Order, Lead, Opportunity,
+ * Campaign, Subscription, Approval, Shipment, …) ends up reinventing the same
+ * triple: `{ status, occurredAt, by? }` + an append-only array on the entity.
+ * This module gives that pattern one canonical type and one zero-allocation
+ * helper, so domains stay focused on their *transitions* not the bookkeeping.
+ *
+ * Pairs naturally with `state-machine`: the machine decides if a transition
+ * is legal; this helper records the move that happened.
+ *
+ * Recording `durationInPriorMs` at write time means funnel-velocity reports
+ * (avg time spent in "Qualification") fall out of a single field instead of
+ * a re-walk over raw timestamps later.
+ *
+ * @example
+ *   import { appendStatus, type StatusHistory } from '@classytic/primitives/status-history';
+ *   import { defineStateMachine } from '@classytic/primitives/state-machine';
+ *
+ *   type LeadStatus = 'new' | 'qualified' | 'converted' | 'disqualified';
+ *   const MACHINE = defineStateMachine<LeadStatus>({ ... });
+ *
+ *   function qualify(lead: Lead, by: string): Lead {
+ *     MACHINE.assertTransition(lead.id, lead.status, 'qualified');
+ *     return {
+ *       ...lead,
+ *       status: 'qualified',
+ *       statusHistory: appendStatus(lead.statusHistory, 'qualified', { by }),
+ *     };
+ *   }
+ */
+/**
+ * One row of the immutable history. Generic over the status enum so each
+ * domain stays type-safe (`StatusChangeEntry<LeadStatus>` rejects
+ * `'shipped'` at compile time).
+ */
+interface StatusChangeEntry<TStatus extends string> {
+  readonly status: TStatus;
+  readonly occurredAt: Date;
+  /** Who triggered the transition (user id, system actor name, etc.). */
+  readonly by?: string;
+  /** Free-form note — disqualify reason, comments, etc. */
+  readonly note?: string;
+  /**
+   * Milliseconds spent in the previous status. `0` for the first entry.
+   * Computed at write time so downstream funnel-velocity / SLA aggregates
+   * never need to walk timestamps.
+   */
+  readonly durationInPriorMs: number;
+}
+/**
+ * Convenience alias for entity fields: `statusHistory: StatusHistory<LeadStatus>`.
+ */
+type StatusHistory<TStatus extends string> = readonly StatusChangeEntry<TStatus>[];
+interface AppendOptions {
+  by?: string;
+  note?: string;
+  /** Override the timestamp — useful for replay / migration. Defaults to `new Date()`. */
+  at?: Date;
+}
+/**
+ * Append a new status entry, computing `durationInPriorMs` from the last
+ * entry (or `0` for the first row). Returns a fresh array — never mutates.
+ *
+ * The previous-entry lookup is `O(1)` (last element), so this is safe to
+ * call from hot paths.
+ */
+declare function appendStatus<TStatus extends string>(history: StatusHistory<TStatus>, status: TStatus, options?: AppendOptions): StatusHistory<TStatus>;
+/**
+ * Time spent in a status across the entire history. Used for funnel-velocity
+ * dashboards: "how long did this lead sit in `qualified` before it converted?".
+ *
+ * Counts duration on the entries that EXITED `status`. If the entity is
+ * currently in `status` and hasn't transitioned out, the still-elapsing time
+ * is added from `now`.
+ */
+declare function timeInStatus<TStatus extends string>(history: StatusHistory<TStatus>, status: TStatus, now?: Date): number;
+/** Most recent entry, or `null` for an empty history. */
+declare function latestEntry<TStatus extends string>(history: StatusHistory<TStatus>): StatusChangeEntry<TStatus> | null;
+/** Most recent occurrence of `status`, or `null` if it never appeared. */
+declare function lastTransitionTo<TStatus extends string>(history: StatusHistory<TStatus>, status: TStatus): StatusChangeEntry<TStatus> | null;
+//#endregion
+export { AppendOptions, StatusChangeEntry, StatusHistory, appendStatus, lastTransitionTo, latestEntry, timeInStatus };

package/dist/status-history.mjs

@@ -0,0 +1,48 @@
+//#region src/workflow/status-history.ts
+/**
+* Append a new status entry, computing `durationInPriorMs` from the last
+* entry (or `0` for the first row). Returns a fresh array — never mutates.
+*
+* The previous-entry lookup is `O(1)` (last element), so this is safe to
+* call from hot paths.
+*/
+function appendStatus(history, status, options = {}) {
+	const now = options.at ?? /* @__PURE__ */ new Date();
+	const prior = history.length === 0 ? void 0 : history[history.length - 1];
+	const entry = {
+		status,
+		occurredAt: now,
+		durationInPriorMs: prior === void 0 ? 0 : Math.max(0, now.getTime() - prior.occurredAt.getTime()),
+		...options.by !== void 0 ? { by: options.by } : {},
+		...options.note !== void 0 ? { note: options.note } : {}
+	};
+	return [...history, entry];
+}
+/**
+* Time spent in a status across the entire history. Used for funnel-velocity
+* dashboards: "how long did this lead sit in `qualified` before it converted?".
+*
+* Counts duration on the entries that EXITED `status`. If the entity is
+* currently in `status` and hasn't transitioned out, the still-elapsing time
+* is added from `now`.
+*/
+function timeInStatus(history, status, now = /* @__PURE__ */ new Date()) {
+	let total = 0;
+	for (let i = 0; i < history.length; i++) {
+		const entry = history[i];
+		if (i > 0 && history[i - 1].status === status) total += entry.durationInPriorMs;
+	}
+	if (history.length > 0 && history[history.length - 1].status === status) total += Math.max(0, now.getTime() - history[history.length - 1].occurredAt.getTime());
+	return total;
+}
+/** Most recent entry, or `null` for an empty history. */
+function latestEntry(history) {
+	return history.length === 0 ? null : history[history.length - 1];
+}
+/** Most recent occurrence of `status`, or `null` if it never appeared. */
+function lastTransitionTo(history, status) {
+	for (let i = history.length - 1; i >= 0; i--) if (history[i].status === status) return history[i];
+	return null;
+}
+//#endregion
+export { appendStatus, lastTransitionTo, latestEntry, timeInStatus };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -97,6 +97,38 @@
       "types": "./dist/payment-gateway.d.mts",
       "default": "./dist/payment-gateway.mjs"
     },
+    "./payment-method-kind": {
+      "types": "./dist/payment-method-kind.d.mts",
+      "default": "./dist/payment-method-kind.mjs"
+    },
+    "./payment-allocation-status": {
+      "types": "./dist/payment-allocation-status.d.mts",
+      "default": "./dist/payment-allocation-status.mjs"
+    },
+    "./payment-events": {
+      "types": "./dist/payment-events.d.mts",
+      "default": "./dist/payment-events.mjs"
+    },
+    "./phone": {
+      "types": "./dist/phone.d.mts",
+      "default": "./dist/phone.mjs"
+    },
+    "./status-history": {
+      "types": "./dist/status-history.d.mts",
+      "default": "./dist/status-history.mjs"
+    },
+    "./condition": {
+      "types": "./dist/condition.d.mts",
+      "default": "./dist/condition.mjs"
+    },
+    "./mixin": {
+      "types": "./dist/mixin.d.mts",
+      "default": "./dist/mixin.mjs"
+    },
+    "./sla-policy": {
+      "types": "./dist/sla-policy.d.mts",
+      "default": "./dist/sla-policy.mjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [