@classytic/primitives 0.9.1 → 0.13.0

package/CHANGELOG.md

@@ -3,6 +3,64 @@
 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.13.0] - 2026-07-22
+
+### Added — `/unit-cost-rate`: exact per-unit monetary rates (bigint-safe)
+
+- **`@classytic/primitives/unit-cost-rate`** — fractional per-unit monetary
+  rates stored as scaled integers (`scaledAmount = minorPerUnit × RATE_SCALE`,
+  `RATE_SCALE = 1_000_000`). Solves the WAC / FIFO valuation problem where
+  dividing a total by a fractional quantity yields a sub-minor-unit rate
+  (100 paisa ÷ 3 units = 33.333… paisa/unit) that must not lose precision.
+  Exports:
+  - `unitCostRate(minorPerUnit, currency)` — direct rate constructor
+  - `unitCostRateFromTotal(totalMinor, quantity, currency)` — WAC/FIFO
+    constructor; bigint-safe, QTY_SCALE grid for fractional quantities
+  - `extendedAmount(rate, qty, mode?)` — the ONE rate→total rounding boundary;
+    bigint multiplication to keep large amounts exact; default `'half-even'`
+    (banker's rounding), `'half-up'` available for legacy parity
+  - `rateMinorPerUnit(rate)` — display helper (fractional number, NOT for math)
+  - `isUnitCostRate(value)` — structural type guard
+  - `UnitCostRate<C>` interface, `UnitCostRateError`, `UnitCostRateErrorCode`,
+    `RoundingMode`, `RATE_SCALE`
+  - For distributing a top-down charge across lines with no lost minor unit,
+    compose with `allocate` from `@classytic/primitives/split-allocation`.
+
+### Changed — `/outbox` is now the canonical contract owner
+
+- **`@classytic/primitives/outbox` owns the transactional-outbox contract.**
+  Previously this file was documented as a mirror of `@classytic/arc`'s copy
+  ("arc is source of truth, keep bit-identical") while arc's docs said the
+  opposite — a manual-sync drift risk. Settled: primitives owns pure
+  cross-package contracts (events + outbox); arc owns runtime behavior
+  (`EventOutbox` relay, stores, backoff, Fastify integration) and, from
+  arc 2.24+, imports + re-exports this contract instead of duplicating it.
+- **Cross-package `instanceof` now works.** Because arc re-exports these exact
+  `OutboxOwnershipError` / `InvalidOutboxEventError` classes, a store built
+  against primitives throws the same class identity arc's relay catches.
+  Under the old duplication, arc's `instanceof` checks silently missed
+  primitives-thrown ownership errors.
+- No export names or signatures changed — contract surface is identical.
+
+## [0.11.0] - 2026-07-08
+
+### Added — eKYC vocabulary + secure OTP primitive
+
+- **`@classytic/primitives/identity-verification`** — cross-package eKYC data shapes:
+  `IdentityDocumentType`, `VerificationCheck`, `VerificationLevel`, `SubjectKind`,
+  `IdentitySubject`, `DocumentReference`, `IdentityProviderCapabilities`,
+  `VerificationStatus`, `CheckResult`, `CreateVerificationParams`,
+  `VerificationSession`, `VerificationWebhookEvent`. Pure helpers: `isVerified`,
+  `checksSatisfy`, `deriveStatus`. The identity twin of `payment-gateway` — shapes
+  here, contracts in engines, provider implementations anywhere. Serves `@classytic/esign`
+  (IdentityBridge port), `@classytic/payee` (ComplianceBridge), and PSP merchant KYC.
+- **`@classytic/primitives/otp`** — secure OTP challenge lifecycle. Guarantees: code
+  never persisted (only HMAC-SHA256 digest stored), constant-time `timingSafeEqual`
+  comparison, rejection-free `randomInt` CSPRNG (no modulo bias), bounded attempt
+  counter, TTL expiry, single-use verified state. Exports: `createOtpChallenge`,
+  `verifyOtpChallenge`, `isOtpVerified`, `isOtpActive`. Delivery stays in
+  `@classytic/notifications` — this primitive owns only the verify half.
+
 ## [0.9.1] - 2026-07-04
 
 ### Added

package/dist/identity-verification.d.mts

@@ -0,0 +1,113 @@
+import { PersonName } from "./person.mjs";
+
+//#region src/identity/identity-verification.d.ts
+/**
+ * Government / institutional identity documents. `trade_license` and
+ * `tin_certificate` support MERCHANT (business) onboarding — a payment gateway
+ * KYBs the business, not just a person.
+ */
+type IdentityDocumentType = 'nid' | 'passport' | 'driving_license' | 'birth_certificate' | 'residence_permit' | 'trade_license' | 'tin_certificate' | 'other';
+/** A single verification check a session can run. Providers advertise support. */
+type VerificationCheck = 'document' | 'liveness' | 'face_match' | 'database' | 'address' | 'sanctions' | 'pep' | 'adverse_media';
+/**
+ * Assurance tier — mirrors the market (Stripe Identity / Persona levels).
+ * Higher tiers imply a superset of checks; the exact mapping is host policy.
+ */
+type VerificationLevel = 'basic' | 'standard' | 'enhanced';
+/** The kind of subject under verification — a natural person or a business. */
+type SubjectKind = 'individual' | 'business';
+interface DocumentReference {
+  readonly type: IdentityDocumentType;
+  /** Document number (NID/passport no.). May be redacted/tokenized at rest. */
+  readonly number?: string;
+  /** ISO 3166-1 alpha-2 issuing country. */
+  readonly country?: string;
+  /** ISO date (YYYY-MM-DD). */
+  readonly expiresOn?: string;
+}
+interface IdentitySubject {
+  readonly kind: SubjectKind;
+  readonly name?: PersonName;
+  /** Legal/business name when `kind === 'business'`. */
+  readonly legalName?: string;
+  /** ISO date (YYYY-MM-DD). */
+  readonly dateOfBirth?: string;
+  /** ISO 3166-1 alpha-2. */
+  readonly country?: string;
+}
+interface IdentityProviderCapabilities {
+  readonly checks: readonly VerificationCheck[];
+  readonly documents: readonly IdentityDocumentType[];
+  /** ISO 3166-1 alpha-2 codes; empty ⇒ global. */
+  readonly countries: readonly string[];
+  /** Delivers async results via webhook (vs poll-only). */
+  readonly webhooks: boolean;
+  /** Supports business/KYB flows, not just individuals. */
+  readonly business: boolean;
+}
+type VerificationStatus = 'pending' | 'processing' | 'verified' | 'rejected' | 'review' | 'expired';
+type CheckOutcome = 'pass' | 'fail' | 'manual' | 'skipped';
+interface CheckResult {
+  readonly check: VerificationCheck;
+  readonly outcome: CheckOutcome;
+  /** Provider-specific reason/code for a fail/manual outcome. */
+  readonly reason?: string;
+}
+interface CreateVerificationParams {
+  readonly subject: IdentitySubject;
+  readonly level: VerificationLevel;
+  /** Checks the host requires to consider the subject verified. */
+  readonly requiredChecks?: readonly VerificationCheck[];
+  readonly documents?: readonly DocumentReference[];
+  /** Where the provider redirects the subject after a hosted flow. */
+  readonly redirectUrl?: string;
+  /** Correlates the session back to a host entity (payee id, signer id, …). */
+  readonly reference?: string;
+  readonly metadata?: Readonly<Record<string, string>>;
+}
+interface VerificationSession {
+  /** Provider-side session id — the handle a host stores and polls. */
+  readonly id: string;
+  readonly provider: string;
+  readonly level: VerificationLevel;
+  readonly status: VerificationStatus;
+  readonly checks: readonly CheckResult[];
+  /** Hosted-flow URL for the subject, when the provider uses one. */
+  readonly url?: string;
+  readonly reference?: string;
+  /** ISO timestamp the verification was decided. */
+  readonly decidedAt?: string;
+  /**
+   * ISO timestamp the verification lapses and re-KYC is required. Periodic
+   * re-KYC is an AML requirement; consumers gate on this (payee pauses
+   * payability, esign re-verifies before signing).
+   */
+  readonly expiresAt?: string;
+  /** Raw provider payload for audit/debugging. */
+  readonly raw?: unknown;
+}
+/** Normalized provider webhook — the async-decision callback shape. */
+interface VerificationWebhookEvent {
+  readonly sessionId: string;
+  readonly provider: string;
+  readonly status: VerificationStatus;
+  readonly checks?: readonly CheckResult[];
+  readonly occurredAt: string;
+  readonly raw?: unknown;
+}
+/** A session is usable when it passed and has not lapsed at `now`. */
+declare function isVerified(session: VerificationSession, now?: Date): boolean;
+/**
+ * Do the check RESULTS satisfy the REQUIRED checks? Every required check must
+ * have a `pass`. Missing or non-pass required checks ⇒ false. Extra results
+ * are ignored.
+ */
+declare function checksSatisfy(required: readonly VerificationCheck[], results: readonly CheckResult[]): boolean;
+/**
+ * Derive a session status from check results alone (for providers that return
+ * raw checks without a verdict): any `fail` ⇒ rejected; any `manual` ⇒ review;
+ * all required present and `pass` ⇒ verified; otherwise processing.
+ */
+declare function deriveStatus(results: readonly CheckResult[], required?: readonly VerificationCheck[]): VerificationStatus;
+//#endregion
+export { CheckOutcome, CheckResult, CreateVerificationParams, DocumentReference, IdentityDocumentType, IdentityProviderCapabilities, IdentitySubject, SubjectKind, VerificationCheck, VerificationLevel, VerificationSession, VerificationStatus, VerificationWebhookEvent, checksSatisfy, deriveStatus, isVerified };

package/dist/identity-verification.mjs

@@ -0,0 +1,30 @@
+//#region src/identity/identity-verification.ts
+/** A session is usable when it passed and has not lapsed at `now`. */
+function isVerified(session, now) {
+	if (session.status !== "verified") return false;
+	if (!session.expiresAt) return true;
+	const at = (now ?? /* @__PURE__ */ new Date()).toISOString();
+	return session.expiresAt > at;
+}
+/**
+* Do the check RESULTS satisfy the REQUIRED checks? Every required check must
+* have a `pass`. Missing or non-pass required checks ⇒ false. Extra results
+* are ignored.
+*/
+function checksSatisfy(required, results) {
+	const passed = new Set(results.filter((r) => r.outcome === "pass").map((r) => r.check));
+	return required.every((c) => passed.has(c));
+}
+/**
+* Derive a session status from check results alone (for providers that return
+* raw checks without a verdict): any `fail` ⇒ rejected; any `manual` ⇒ review;
+* all required present and `pass` ⇒ verified; otherwise processing.
+*/
+function deriveStatus(results, required = []) {
+	if (results.some((r) => r.outcome === "fail")) return "rejected";
+	if (results.some((r) => r.outcome === "manual")) return "review";
+	if (required.length > 0 && checksSatisfy(required, results)) return "verified";
+	return "processing";
+}
+//#endregion
+export { checksSatisfy, deriveStatus, isVerified };

package/dist/otp.d.mts

@@ -0,0 +1,96 @@
+//#region src/identity/otp.d.ts
+/**
+ * OTP challenge — the pure, secure *verify* half of one-time-code verification.
+ *
+ * This primitive owns SECURITY, never delivery. Delivery (SMS / email / push /
+ * WhatsApp, templates, retry, fallback) is `@classytic/notifications`; the host
+ * passes the returned `code` to whichever channel/provider it likes. This file
+ * only guarantees the code cannot be forged, replayed, brute-forced, or leaked:
+ *
+ *   - the plaintext code is NEVER persisted — only its HMAC-SHA256 digest is
+ *     (a stolen challenge row cannot reveal the code);
+ *   - comparison is constant-time (`timingSafeEqual`) — no timing oracle;
+ *   - the code is drawn from a CSPRNG with rejection-free `randomInt` — no
+ *     modulo bias;
+ *   - a bounded attempt counter locks the challenge — no online brute force;
+ *   - a TTL expires the challenge — no indefinite window;
+ *   - a verified challenge is single-use — no replay.
+ *
+ * The shape is a plain value object: create it, persist `challenge`, and on each
+ * attempt feed the stored challenge back through `verifyOtpChallenge` and persist
+ * the returned next state. No I/O, no clock capture beyond an injectable `now`.
+ *
+ * Resend throttling (don't mint a new code too soon) is a host / arc-layer
+ * concern — rate-limit calls to `createOtpChallenge`; it is deliberately not
+ * modeled here so the verify primitive stays stateless between attempts.
+ */
+/** Terminal + in-flight states a persisted challenge can hold. */
+type OtpStatus = 'pending' | 'verified' | 'failed' | 'expired';
+/** The result of a single `verifyOtpChallenge` call. */
+type OtpOutcome = 'verified' | 'incorrect' | 'expired' | 'locked' | 'already_used';
+/**
+ * The persistable challenge. Contains no secret material: `hash` is an HMAC of
+ * the code under a server-side `secret`, so the row is useless to a thief who
+ * lacks the secret. Persist this verbatim; never add the plaintext code to it.
+ */
+interface OtpChallenge {
+  /** HMAC-SHA256(code, secret) as hex. The plaintext code is never stored. */
+  readonly hash: string;
+  /** ISO-8601 instant after which the challenge is dead. */
+  readonly expiresAt: string;
+  /** Failed attempts so far. */
+  readonly attempts: number;
+  /** Attempts allowed before the challenge locks (`failed`). */
+  readonly maxAttempts: number;
+  /** Lifecycle state. */
+  readonly status: OtpStatus;
+}
+interface CreateOtpOptions {
+  /** Server-side HMAC key. Required — a challenge with no secret is forgeable. */
+  readonly secret: string;
+  /** Number of digits in the code. Default 6. */
+  readonly length?: number;
+  /** Time-to-live in ms. Default 5 minutes. */
+  readonly ttlMs?: number;
+  /** Failed attempts before lock. Default 5. */
+  readonly maxAttempts?: number;
+  /** Injectable clock for deterministic tests. Default `new Date()`. */
+  readonly now?: Date;
+}
+interface CreatedOtp {
+  /** Persist this. Contains only the HMAC digest, never the code. */
+  readonly challenge: OtpChallenge;
+  /** Deliver this via `@classytic/notifications`. NEVER persist it. */
+  readonly code: string;
+}
+interface VerifyOtpOptions {
+  /** The same server-side HMAC key used at creation. */
+  readonly secret: string;
+  /** Injectable clock for deterministic tests. Default `new Date()`. */
+  readonly now?: Date;
+}
+interface OtpVerification {
+  /** The next challenge state to persist (attempt count / status advanced). */
+  readonly challenge: OtpChallenge;
+  /** What happened on this attempt. */
+  readonly outcome: OtpOutcome;
+}
+/**
+ * Mint a challenge + its one-time code. Persist `challenge`; hand `code` to the
+ * delivery layer. The code exists only in this return value and in the delivered
+ * message — it is never recoverable from the persisted challenge.
+ */
+declare function createOtpChallenge(options: CreateOtpOptions): CreatedOtp;
+/**
+ * Check `input` against a persisted challenge and return the next state. This is
+ * a pure transition — the caller persists `result.challenge`. Fail-closed: any
+ * non-`pending` challenge, an expired window, or an over-limit attempt yields a
+ * non-`verified` outcome and never re-opens a settled challenge.
+ */
+declare function verifyOtpChallenge(challenge: OtpChallenge, input: string, options: VerifyOtpOptions): OtpVerification;
+/** True once a challenge has been successfully verified. */
+declare function isOtpVerified(challenge: OtpChallenge): boolean;
+/** True while a challenge can still accept an attempt (pending + unexpired). */
+declare function isOtpActive(challenge: OtpChallenge, now?: Date): boolean;
+//#endregion
+export { CreateOtpOptions, CreatedOtp, OtpChallenge, OtpOutcome, OtpStatus, OtpVerification, VerifyOtpOptions, createOtpChallenge, isOtpActive, isOtpVerified, verifyOtpChallenge };

package/dist/otp.mjs

@@ -0,0 +1,132 @@
+import { createHmac, randomInt, timingSafeEqual } from "node:crypto";
+//#region src/identity/otp.ts
+/**
+* OTP challenge — the pure, secure *verify* half of one-time-code verification.
+*
+* This primitive owns SECURITY, never delivery. Delivery (SMS / email / push /
+* WhatsApp, templates, retry, fallback) is `@classytic/notifications`; the host
+* passes the returned `code` to whichever channel/provider it likes. This file
+* only guarantees the code cannot be forged, replayed, brute-forced, or leaked:
+*
+*   - the plaintext code is NEVER persisted — only its HMAC-SHA256 digest is
+*     (a stolen challenge row cannot reveal the code);
+*   - comparison is constant-time (`timingSafeEqual`) — no timing oracle;
+*   - the code is drawn from a CSPRNG with rejection-free `randomInt` — no
+*     modulo bias;
+*   - a bounded attempt counter locks the challenge — no online brute force;
+*   - a TTL expires the challenge — no indefinite window;
+*   - a verified challenge is single-use — no replay.
+*
+* The shape is a plain value object: create it, persist `challenge`, and on each
+* attempt feed the stored challenge back through `verifyOtpChallenge` and persist
+* the returned next state. No I/O, no clock capture beyond an injectable `now`.
+*
+* Resend throttling (don't mint a new code too soon) is a host / arc-layer
+* concern — rate-limit calls to `createOtpChallenge`; it is deliberately not
+* modeled here so the verify primitive stays stateless between attempts.
+*/
+const DEFAULT_LENGTH = 6;
+const DEFAULT_TTL_MS = 300 * 1e3;
+const DEFAULT_MAX_ATTEMPTS = 5;
+function hmac(code, secret) {
+	return createHmac("sha256", secret).update(code).digest("hex");
+}
+/** CSPRNG numeric code with no modulo bias (`randomInt` rejection-samples). */
+function generateCode(length) {
+	let code = "";
+	for (let i = 0; i < length; i += 1) code += randomInt(0, 10).toString();
+	return code;
+}
+/** Constant-time compare of two equal-length hex digests. */
+function constantTimeEqualHex(a, b) {
+	const ab = Buffer.from(a, "hex");
+	const bb = Buffer.from(b, "hex");
+	return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+/**
+* Mint a challenge + its one-time code. Persist `challenge`; hand `code` to the
+* delivery layer. The code exists only in this return value and in the delivered
+* message — it is never recoverable from the persisted challenge.
+*/
+function createOtpChallenge(options) {
+	if (!options.secret) throw new Error("[otp] a `secret` is required to HMAC the code.");
+	const length = options.length ?? DEFAULT_LENGTH;
+	if (length < 4) throw new Error("[otp] `length` must be at least 4 digits.");
+	const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+	if (ttlMs <= 0) throw new Error("[otp] `ttlMs` must be positive.");
+	const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+	if (maxAttempts < 1) throw new Error("[otp] `maxAttempts` must be at least 1.");
+	const now = options.now ?? /* @__PURE__ */ new Date();
+	const code = generateCode(length);
+	return {
+		code,
+		challenge: {
+			hash: hmac(code, options.secret),
+			expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+			attempts: 0,
+			maxAttempts,
+			status: "pending"
+		}
+	};
+}
+/**
+* Check `input` against a persisted challenge and return the next state. This is
+* a pure transition — the caller persists `result.challenge`. Fail-closed: any
+* non-`pending` challenge, an expired window, or an over-limit attempt yields a
+* non-`verified` outcome and never re-opens a settled challenge.
+*/
+function verifyOtpChallenge(challenge, input, options) {
+	if (!options.secret) throw new Error("[otp] a `secret` is required to verify the code.");
+	if (challenge.status === "verified") return {
+		challenge,
+		outcome: "already_used"
+	};
+	if (challenge.status === "failed") return {
+		challenge,
+		outcome: "locked"
+	};
+	if (challenge.status === "expired") return {
+		challenge,
+		outcome: "expired"
+	};
+	if ((options.now ?? /* @__PURE__ */ new Date()).getTime() > Date.parse(challenge.expiresAt)) return {
+		challenge: {
+			...challenge,
+			status: "expired"
+		},
+		outcome: "expired"
+	};
+	if (constantTimeEqualHex(hmac(input, options.secret), challenge.hash)) return {
+		challenge: {
+			...challenge,
+			status: "verified"
+		},
+		outcome: "verified"
+	};
+	const attempts = challenge.attempts + 1;
+	if (attempts >= challenge.maxAttempts) return {
+		challenge: {
+			...challenge,
+			attempts,
+			status: "failed"
+		},
+		outcome: "locked"
+	};
+	return {
+		challenge: {
+			...challenge,
+			attempts
+		},
+		outcome: "incorrect"
+	};
+}
+/** True once a challenge has been successfully verified. */
+function isOtpVerified(challenge) {
+	return challenge.status === "verified";
+}
+/** True while a challenge can still accept an attempt (pending + unexpired). */
+function isOtpActive(challenge, now = /* @__PURE__ */ new Date()) {
+	return challenge.status === "pending" && now.getTime() <= Date.parse(challenge.expiresAt);
+}
+//#endregion
+export { createOtpChallenge, isOtpActive, isOtpVerified, verifyOtpChallenge };

package/dist/unit-cost-rate.d.mts

@@ -0,0 +1,56 @@
+import { r as CurrencyCode } from "./currency-BCJnJBlb.mjs";
+import { MinorUnits } from "./money.mjs";
+
+//#region src/money/unit-cost-rate.d.ts
+/** Fixed, ecosystem-wide rate scale: 6 decimal places below the minor unit. */
+declare const RATE_SCALE = 1000000;
+/** Half-to-even (banker's) is the default; half-up available for legacy parity. */
+type RoundingMode = 'half-even' | 'half-up';
+/**
+ * Minor units per unit, stored as an integer scaled by {@link RATE_SCALE}.
+ * `scale` is carried so a value is self-describing on the wire even if
+ * `RATE_SCALE` ever changes; it is always `RATE_SCALE` today.
+ */
+interface UnitCostRate<C extends string = string> {
+  /** Integer: minor units per unit × `scale`. */
+  readonly scaledAmount: number;
+  readonly currency: C | CurrencyCode | string;
+  /** Always {@link RATE_SCALE}. */
+  readonly scale: number;
+}
+type UnitCostRateErrorCode = 'NOT_FINITE' | 'NEGATIVE' | 'NOT_INTEGER' | 'UNSAFE_INTEGER' | 'NON_POSITIVE_QUANTITY';
+declare class UnitCostRateError extends Error {
+  readonly name = "UnitCostRateError";
+  readonly code: UnitCostRateErrorCode;
+  constructor(code: UnitCostRateErrorCode, message: string);
+}
+/**
+ * Construct a rate from a (possibly fractional) minor-units-per-unit value.
+ *
+ * @example unitCostRate(33.3333, 'BDT') // { scaledAmount: 33_333_300, ... }
+ */
+declare function unitCostRate<C extends string = string>(minorPerUnit: number, currency: C): UnitCostRate<C>;
+/**
+ * Weighted-average constructor: the rate implied by an integer minor-unit
+ * `totalMinor` spread over a (possibly fractional) `quantity`. This is the WAC
+ * / layer-average rate. Overflow-safe via bigint; quantity rounded to the
+ * {@link QTY_SCALE} grid.
+ *
+ * @example unitCostRateFromTotal(100, 3, 'BDT') // 33.333… paisa/unit
+ */
+declare function unitCostRateFromTotal<C extends string = string>(totalMinor: number, quantity: number, currency: C): UnitCostRate<C>;
+/**
+ * The extended monetary amount for `quantity` units at `rate`, rounded to
+ * integer {@link MinorUnits} — the ONE rate→total rounding boundary.
+ *
+ * `round(quantity × scaledAmount / RATE_SCALE)`, computed in bigint so large
+ * amounts never lose precision. A fractional quantity is honoured to
+ * {@link QTY_SCALE} precision.
+ */
+declare function extendedAmount<C extends string = string>(rate: UnitCostRate<C>, quantity: number, mode?: RoundingMode): MinorUnits<C>;
+/** The rate as a plain (fractional) minor-units-per-unit number — for display only. */
+declare function rateMinorPerUnit(rate: UnitCostRate): number;
+/** Structural guard. */
+declare function isUnitCostRate(value: unknown): value is UnitCostRate;
+//#endregion
+export { RATE_SCALE, RoundingMode, UnitCostRate, UnitCostRateError, UnitCostRateErrorCode, extendedAmount, isUnitCostRate, rateMinorPerUnit, unitCostRate, unitCostRateFromTotal };

package/dist/unit-cost-rate.mjs

@@ -0,0 +1,116 @@
+import { MinorUnits } from "./money.mjs";
+//#region src/money/unit-cost-rate.ts
+/** Fixed, ecosystem-wide rate scale: 6 decimal places below the minor unit. */
+const RATE_SCALE = 1e6;
+/**
+* Quantity scale used internally so a fractional quantity (e.g. `2.5`, a UoM
+* split) participates in exact integer/bigint arithmetic. 6 dp of quantity
+* precision — quantities finer than 1e-6 unit are rounded to this grid.
+*/
+const QTY_SCALE = 1e6;
+const DEFAULT_ROUNDING = "half-even";
+var UnitCostRateError = class extends Error {
+	name = "UnitCostRateError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+function assertSafe(scaled) {
+	if (!Number.isFinite(scaled)) throw new UnitCostRateError("NOT_FINITE", `unit cost rate is not finite: ${scaled}`);
+	if (!Number.isSafeInteger(scaled)) throw new UnitCostRateError("UNSAFE_INTEGER", `scaled unit cost ${scaled} exceeds Number.MAX_SAFE_INTEGER — value too large for this rate scale`);
+}
+/**
+* Scale a (possibly fractional) quantity onto the {@link QTY_SCALE} grid as a
+* bigint. Guards against a quantity so large that `quantity × QTY_SCALE` loses
+* integer precision as a double BEFORE reaching bigint (≈ >9e9 units).
+*/
+function scaleQuantity(quantity) {
+	const q = Math.round(quantity * QTY_SCALE);
+	if (!Number.isSafeInteger(q)) throw new UnitCostRateError("UNSAFE_INTEGER", `quantity ${quantity} is too large to scale precisely — exceeds safe-integer range`);
+	return BigInt(q);
+}
+/**
+* Construct a rate from a (possibly fractional) minor-units-per-unit value.
+*
+* @example unitCostRate(33.3333, 'BDT') // { scaledAmount: 33_333_300, ... }
+*/
+function unitCostRate(minorPerUnit, currency) {
+	if (!Number.isFinite(minorPerUnit)) throw new UnitCostRateError("NOT_FINITE", `minorPerUnit is not finite: ${minorPerUnit}`);
+	if (minorPerUnit < 0) throw new UnitCostRateError("NEGATIVE", `unit cost cannot be negative: ${minorPerUnit}`);
+	const scaledAmount = Math.round(minorPerUnit * RATE_SCALE);
+	assertSafe(scaledAmount);
+	return {
+		scaledAmount,
+		currency,
+		scale: RATE_SCALE
+	};
+}
+/**
+* Weighted-average constructor: the rate implied by an integer minor-unit
+* `totalMinor` spread over a (possibly fractional) `quantity`. This is the WAC
+* / layer-average rate. Overflow-safe via bigint; quantity rounded to the
+* {@link QTY_SCALE} grid.
+*
+* @example unitCostRateFromTotal(100, 3, 'BDT') // 33.333… paisa/unit
+*/
+function unitCostRateFromTotal(totalMinor, quantity, currency) {
+	if (!Number.isInteger(totalMinor)) throw new UnitCostRateError("NOT_INTEGER", `totalMinor must be integer minor units: ${totalMinor}`);
+	if (!Number.isFinite(quantity) || quantity <= 0) throw new UnitCostRateError("NON_POSITIVE_QUANTITY", `quantity must be > 0, got ${quantity}`);
+	const qScaled = scaleQuantity(quantity);
+	const numerator = BigInt(totalMinor) * BigInt(RATE_SCALE) * BigInt(QTY_SCALE);
+	const scaled = Number(roundedDiv(numerator, qScaled, "half-even"));
+	assertSafe(scaled);
+	return {
+		scaledAmount: scaled,
+		currency,
+		scale: RATE_SCALE
+	};
+}
+/**
+* The extended monetary amount for `quantity` units at `rate`, rounded to
+* integer {@link MinorUnits} — the ONE rate→total rounding boundary.
+*
+* `round(quantity × scaledAmount / RATE_SCALE)`, computed in bigint so large
+* amounts never lose precision. A fractional quantity is honoured to
+* {@link QTY_SCALE} precision.
+*/
+function extendedAmount(rate, quantity, mode = DEFAULT_ROUNDING) {
+	if (!Number.isFinite(quantity) || quantity < 0) throw new UnitCostRateError("NON_POSITIVE_QUANTITY", `quantity must be >= 0, got ${quantity}`);
+	const qScaled = scaleQuantity(quantity);
+	const numerator = BigInt(rate.scaledAmount) * qScaled;
+	const denominator = BigInt(rate.scale) * BigInt(QTY_SCALE);
+	const minor = Number(roundedDiv(numerator, denominator, mode));
+	if (!Number.isSafeInteger(minor)) throw new UnitCostRateError("UNSAFE_INTEGER", `extended amount ${minor} exceeds safe integer range`);
+	return MinorUnits(minor, rate.currency);
+}
+/** The rate as a plain (fractional) minor-units-per-unit number — for display only. */
+function rateMinorPerUnit(rate) {
+	return rate.scaledAmount / rate.scale;
+}
+/** Structural guard. */
+function isUnitCostRate(value) {
+	return typeof value === "object" && value !== null && Number.isInteger(value.scaledAmount) && typeof value.currency === "string" && typeof value.scale === "number";
+}
+/**
+* Rounded integer division of two bigints, `numerator / denominator`
+* (`denominator > 0`), honouring the rounding mode at the exact half.
+* Sign-safe for negative numerators.
+*/
+function roundedDiv(numerator, denominator, mode) {
+	const neg = numerator < 0n;
+	const n = neg ? -numerator : numerator;
+	const q = n / denominator;
+	const remainder = n - q * denominator;
+	if (remainder === 0n) return neg ? -q : q;
+	const twiceRem = remainder * 2n;
+	let up;
+	if (twiceRem > denominator) up = true;
+	else if (twiceRem < denominator) up = false;
+	else up = mode === "half-up" ? true : q % 2n !== 0n;
+	const result = up ? q + 1n : q;
+	return neg ? -result : result;
+}
+//#endregion
+export { RATE_SCALE, UnitCostRateError, extendedAmount, isUnitCostRate, rateMinorPerUnit, unitCostRate, unitCostRateFromTotal };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.9.1",
+  "version": "0.13.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -29,6 +29,10 @@
       "types": "./dist/currency.d.mts",
       "default": "./dist/currency.mjs"
     },
+    "./unit-cost-rate": {
+      "types": "./dist/unit-cost-rate.d.mts",
+      "default": "./dist/unit-cost-rate.mjs"
+    },
     "./address": {
       "types": "./dist/address.d.mts",
       "default": "./dist/address.mjs"
@@ -97,6 +101,14 @@
       "types": "./dist/person.d.mts",
       "default": "./dist/person.mjs"
     },
+    "./identity-verification": {
+      "types": "./dist/identity-verification.d.mts",
+      "default": "./dist/identity-verification.mjs"
+    },
+    "./otp": {
+      "types": "./dist/otp.d.mts",
+      "default": "./dist/otp.mjs"
+    },
     "./state-machine": {
       "types": "./dist/state-machine.d.mts",
       "default": "./dist/state-machine.mjs"