@classytic/primitives 0.4.0 → 0.6.0

package/dist/phone.mjs

@@ -0,0 +1,310 @@
+import { err, ok } from "./result.mjs";
+//#region src/identity/phone.ts
+/**
+* Phone number value object.
+*
+* `PersonName` and `Address` are typed; phones have been a plain `string` in
+* `ContactInfo` so far. This primitive closes that gap with a tiny,
+* zero-dependency wrapper that:
+*   1. Normalizes E.164 input (strips formatting, keeps the leading `+`).
+*   2. Captures the country calling code as a discrete field for routing /
+*      regional analytics.
+*   3. Surfaces parse failures via `Result<PhoneNumber, PhoneError>` so
+*      callers don't deal with thrown errors at value-object construction.
+*
+* Deliberately NOT a full libphonenumber dep — that ships ~500 KB of metadata
+* and is per-locale. We accept E.164 input and validate format; deeper
+* validation (region-of-issue, mobile-vs-landline) is the host's call to
+* layer on top. This keeps `@classytic/primitives` zero-dep and tree-shakeable.
+*
+* @example
+*   import { parsePhone, formatPhone, type PhoneNumber } from '@classytic/primitives/phone';
+*
+*   const parsed = parsePhone('+1 (415) 555-0182');
+*   if (parsed.ok) {
+*     formatPhone(parsed.value); // '+14155550182'
+*     parsed.value.callingCode;  // '1'
+*   }
+*/
+var PhoneError = class extends Error {
+	name = "PhoneError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+/**
+* E.164 country calling codes by length. We accept 1–3 digits and let the
+* longest-prefix-match decide. Source: ITU-T E.164 assignments (snapshot —
+* stable across decades).
+*
+* Kept inline (not exported) because it's an implementation detail of the
+* parser. Length is the only thing we actually need for the split.
+*/
+const E164_PREFIXES_3 = new Set([
+	"210",
+	"211",
+	"212",
+	"213",
+	"216",
+	"218",
+	"220",
+	"221",
+	"222",
+	"223",
+	"224",
+	"225",
+	"226",
+	"227",
+	"228",
+	"229",
+	"230",
+	"231",
+	"232",
+	"233",
+	"234",
+	"235",
+	"236",
+	"237",
+	"238",
+	"239",
+	"240",
+	"241",
+	"242",
+	"243",
+	"244",
+	"245",
+	"246",
+	"247",
+	"248",
+	"249",
+	"250",
+	"251",
+	"252",
+	"253",
+	"254",
+	"255",
+	"256",
+	"257",
+	"258",
+	"260",
+	"261",
+	"262",
+	"263",
+	"264",
+	"265",
+	"266",
+	"267",
+	"268",
+	"269",
+	"290",
+	"291",
+	"297",
+	"298",
+	"299",
+	"350",
+	"351",
+	"352",
+	"353",
+	"354",
+	"355",
+	"356",
+	"357",
+	"358",
+	"359",
+	"370",
+	"371",
+	"372",
+	"373",
+	"374",
+	"375",
+	"376",
+	"377",
+	"378",
+	"379",
+	"380",
+	"381",
+	"382",
+	"383",
+	"385",
+	"386",
+	"387",
+	"389",
+	"420",
+	"421",
+	"423",
+	"500",
+	"501",
+	"502",
+	"503",
+	"504",
+	"505",
+	"506",
+	"507",
+	"508",
+	"509",
+	"590",
+	"591",
+	"592",
+	"593",
+	"594",
+	"595",
+	"596",
+	"597",
+	"598",
+	"599",
+	"670",
+	"672",
+	"673",
+	"674",
+	"675",
+	"676",
+	"677",
+	"678",
+	"679",
+	"680",
+	"681",
+	"682",
+	"683",
+	"685",
+	"686",
+	"687",
+	"688",
+	"689",
+	"690",
+	"691",
+	"692",
+	"800",
+	"808",
+	"850",
+	"852",
+	"853",
+	"855",
+	"856",
+	"870",
+	"878",
+	"880",
+	"881",
+	"882",
+	"883",
+	"886",
+	"888",
+	"960",
+	"961",
+	"962",
+	"963",
+	"964",
+	"965",
+	"966",
+	"967",
+	"968",
+	"970",
+	"971",
+	"972",
+	"973",
+	"974",
+	"975",
+	"976",
+	"977",
+	"979",
+	"992",
+	"993",
+	"994",
+	"995",
+	"996",
+	"998"
+]);
+const E164_PREFIXES_2 = new Set([
+	"20",
+	"27",
+	"30",
+	"31",
+	"32",
+	"33",
+	"34",
+	"36",
+	"39",
+	"40",
+	"41",
+	"43",
+	"44",
+	"45",
+	"46",
+	"47",
+	"48",
+	"49",
+	"51",
+	"52",
+	"53",
+	"54",
+	"55",
+	"56",
+	"57",
+	"58",
+	"60",
+	"61",
+	"62",
+	"63",
+	"64",
+	"65",
+	"66",
+	"81",
+	"82",
+	"84",
+	"86",
+	"90",
+	"91",
+	"92",
+	"93",
+	"94",
+	"95",
+	"98"
+]);
+const E164_PREFIXES_1 = new Set(["1", "7"]);
+/**
+* Parse free-form phone input into a normalized `PhoneNumber`. Accepts:
+*   - `'+14155550182'`           → e164 unchanged
+*   - `'+1 (415) 555-0182'`     → strips spaces / punctuation
+*   - `'+1.415.555.0182'`        → strips dots
+*
+* Rejects anything without a leading `+` — we don't guess the country.
+* If the host knows the user's region, prepend the code before calling.
+*/
+function parsePhone(input) {
+	if (typeof input !== "string" || input.trim().length === 0) return err(new PhoneError("EMPTY", "phone input is empty"));
+	const trimmed = input.trim();
+	if (!trimmed.startsWith("+")) return err(new PhoneError("MISSING_PLUS", `phone must be E.164 (start with '+'): got ${JSON.stringify(input)}`));
+	const digits = trimmed.slice(1).replace(/[^0-9]/g, "");
+	if (digits.length === 0) return err(new PhoneError("NOT_E164", "phone has no digits"));
+	if (digits.length > 15) return err(new PhoneError("TOO_LONG", `phone exceeds E.164 15-digit limit: ${digits.length} digits`));
+	if (digits.length < 7) return err(new PhoneError("TOO_SHORT", `phone too short to be E.164: ${digits.length} digits`));
+	const callingCode = E164_PREFIXES_3.has(digits.slice(0, 3)) ? digits.slice(0, 3) : E164_PREFIXES_2.has(digits.slice(0, 2)) ? digits.slice(0, 2) : E164_PREFIXES_1.has(digits.slice(0, 1)) ? digits.slice(0, 1) : null;
+	if (callingCode === null) return err(new PhoneError("NOT_E164", `unrecognized country calling code in ${JSON.stringify(input)}`));
+	return ok({
+		e164: `+${digits}`,
+		callingCode,
+		nationalNumber: digits.slice(callingCode.length)
+	});
+}
+/** Convenience: returns the E.164 string. Useful when piping to a transport. */
+function formatPhone(phone) {
+	return phone.e164;
+}
+/**
+* Best-effort national-format render: groups the national number into 3-digit
+* blocks. Not locale-aware — for display polish, hosts should format per
+* region. Useful as a default in admin UIs.
+*
+* @example formatNational(parsePhone('+14155550182').value!) → '+1 415 555 0182'
+*/
+function formatNational(phone) {
+	const groups = phone.nationalNumber.match(/.{1,3}/g) ?? [];
+	return `+${phone.callingCode} ${groups.join(" ")}`.trim();
+}
+/** Type guard. */
+function isPhoneNumber(value) {
+	return typeof value === "object" && value !== null && typeof value.e164 === "string" && typeof value.callingCode === "string" && typeof value.nationalNumber === "string" && value.e164.startsWith("+");
+}
+//#endregion
+export { PhoneError, formatNational, formatPhone, isPhoneNumber, parsePhone };

package/dist/reference.d.mts

@@ -1,4 +1,4 @@
-//#region src/reference.d.ts
+//#region src/composition/reference.d.ts
 /**
  * Minimal structural type for any ID object with a `.toString()` method. Does
  * NOT depend on `mongoose` — `Types.ObjectId` satisfies this shape

package/dist/reference.mjs

@@ -1,4 +1,4 @@
-//#region src/reference.ts
+//#region src/composition/reference.ts
 /** Coerce any {@link IdLike} to its canonical string form. */
 function idToString(id) {
 	return typeof id === "string" ? id : id.toString();

package/dist/result.d.mts

@@ -1,4 +1,4 @@
-//#region src/result.d.ts
+//#region src/composition/result.d.ts
 /**
  * A discriminated-union result type — an alternative to throwing for expected
  * domain failures. Zero-cost: use it where failure is a first-class outcome

package/dist/result.mjs

@@ -1,4 +1,4 @@
-//#region src/result.ts
+//#region src/composition/result.ts
 function ok(value) {
 	return {
 		ok: true,

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.
 *