@classytic/primitives 0.28.0 → 0.30.0

package/dist/monetization.mjs

@@ -164,6 +164,12 @@ function compareAtPriceOf(m) {
 	if (m.type === "pass") return defaultPassOf(m)?.compareAtPrice ?? null;
 	return null;
 }
+/** On sale: a compare-at price above the selling price, same currency. The ONE on-sale predicate. */
+function isOnSale(m) {
+	const compareAt = compareAtPriceOf(m);
+	const price = unitPriceOf(m);
+	return compareAt !== null && price !== null && compareAt.currency === price.currency && compareAt.amount > price.amount;
+}
 /**
 * Canonical kind → revenue wire type. Everything that is not `free` or
 * `subscription` settles as a `purchase` in revenue's ledger vocabulary
@@ -184,4 +190,4 @@ function fromRevenueMonetizationType(type) {
 	return "one_time";
 }
 //#endregion
-export { MONETIZATION_KINDS, UPFRONT_COLLECTION_MODES, approxTermDays, compareAtPriceOf, defaultPassOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isPassMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };
+export { MONETIZATION_KINDS, UPFRONT_COLLECTION_MODES, approxTermDays, compareAtPriceOf, defaultPassOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOnSale, isOneTimeMonetization, isPassMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };

package/dist/outbox.d.mts

@@ -46,6 +46,20 @@ interface OutboxClaimOptions {
 interface OutboxClaimedEvent {
   readonly event: DomainEvent;
   readonly fencingToken: number;
+  /**
+   * DURABLE delivery-attempt count for this event, INCLUDING the claim that
+   * returned it (1 on the first claim). Optional: stores that persist a
+   * per-row counter report it; stores that don't leave it absent.
+   *
+   * Why it exists: a relay can only count failures in its own memory, and
+   * that count is wrong in exactly the cases a failure policy exists for.
+   * A poison event that crashes the relay restarts at 1 on every boot, so
+   * `attempts >= 5 → deadLetter` never fires; and across N relays sharing a
+   * store, each counts its own attempts, so "5" means 5×N. The store already
+   * increments a counter atomically inside the claim — reporting it here is
+   * what lets the policy see the true number.
+   */
+  readonly attempts?: number;
 }
 /** Options for {@link OutboxStore.acknowledge}. */
 interface OutboxAcknowledgeOptions {
@@ -81,9 +95,12 @@ interface OutboxFailureContext {
   /** The error returned by the transport / handler. */
   readonly error: Error;
   /**
-   * Attempt count including this failure (1 on the first fail). Tracked
-   * in-process by the relay; accurate within a single relay process, resets
-   * on restart. For durable attempt counts, the policy can query the store.
+   * Attempt count including this failure (1 on the first fail).
+   *
+   * DURABLE when the store reports {@link OutboxClaimedEvent.attempts} from a
+   * fenced claim — survives relay restarts and is shared by every relay on the
+   * store. Otherwise the relay's in-process count: accurate within one relay
+   * process, reset on restart. Relays take the larger of the two.
    */
   readonly attempts: number;
 }
@@ -124,6 +141,23 @@ declare class OutboxOwnershipError extends Error {
   readonly currentOwner: string | null;
   constructor(eventId: string, attemptedBy: string, currentOwner: string | null);
 }
+/**
+ * Thrown by `save` when a row with this event id already exists with a DIFFERENT payload.
+ * A same-id, same-payload save is an idempotent success; a different payload is two
+ * occurrences minted onto one id, and dropping either one loses money silently.
+ */
+declare class OutboxConflictError extends Error {
+  readonly name = "OutboxConflictError";
+  readonly code = "outbox.conflict";
+  readonly eventId: string;
+  readonly eventType: string;
+  constructor(eventId: string, eventType: string);
+}
+/**
+ * Order-independent fingerprint of an event payload as it travels (JSON: `Date` becomes its
+ * ISO string, `undefined` drops). Stores compare it on a duplicate id; see {@link OutboxConflictError}.
+ */
+declare function outboxPayloadFingerprint(event: DomainEvent): string;
 /** Thrown when an event missing `type` or `meta.id` is passed to the outbox. */
 declare class InvalidOutboxEventError extends Error {
   readonly name = "InvalidOutboxEventError";
@@ -218,7 +252,8 @@ interface OutboxStore {
   /**
    * Save an event to the outbox (typically called inside a business
    * transaction). MUST reject events missing `type` or `meta.id` — throw
-   * rather than persist.
+   * rather than persist. A second save of an existing `meta.id` is a no-op when
+   * the payload matches, and throws {@link OutboxConflictError} when it does not.
    */
   save(event: DomainEvent, options?: OutboxWriteOptions): Promise<void>;
   /**
@@ -250,6 +285,12 @@ interface OutboxStore {
    * @throws {@link OutboxOwnershipError} on ownership mismatch
    */
   acknowledge(eventId: string, options?: OutboxAcknowledgeOptions): Promise<void>;
+  /**
+   * Mark every listed event delivered in ONE write — what a unit of work's post-commit flush
+   * calls, so N delivered events cost one command, not N. Unleased rows only (no fencing);
+   * unknown or already-delivered ids are ignored.
+   */
+  acknowledgeMany?(eventIds: readonly string[]): Promise<void>;
   /**
    * Record a relay failure. When implemented, the relay calls this instead
    * of stopping the batch — enables retry scheduling and DLQ.
@@ -318,4 +359,4 @@ interface OutboxStore {
   oldestPendingAgeMs?(): Promise<number | null>;
 }
 //#endregion
-export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxClaimedEvent, OutboxErrorInfo, OutboxFailOptions, OutboxFailureContext, OutboxFailureDecision, OutboxFailurePolicy, OutboxOwnershipError, OutboxStatus, OutboxStore, OutboxWriteOptions };
+export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxClaimedEvent, OutboxConflictError, OutboxErrorInfo, OutboxFailOptions, OutboxFailureContext, OutboxFailureDecision, OutboxFailurePolicy, OutboxOwnershipError, OutboxStatus, OutboxStore, OutboxWriteOptions, outboxPayloadFingerprint };

package/dist/outbox.mjs

@@ -1,5 +1,23 @@
+import { canonicalDigest } from "./canonical.mjs";
 //#region src/events/outbox.ts
 /**
+* Transactional outbox CONTRACT — the canonical owner. `@classytic/arc`
+* re-exports this; it keeps no copy of its own.
+*
+* Contract surface only: {@link OutboxStore}, its option types, the
+* {@link OutboxFailurePolicy} retry/DLQ contract, and the error classes.
+*
+* The split exists because a domain package MUST NOT peer-dep arc. Owning the
+* contract here lets a package write `implements OutboxStore` and hand the
+* result to arc's `new EventOutbox({ store })`, and since arc re-exports these
+* exact classes, `instanceof OutboxOwnershipError` works across the boundary.
+*
+* Runtimes live elsewhere: the DURABLE one (`EventOutbox` relay, Mongo store,
+* backoff, Fastify wiring) in `@classytic/arc/events`; the dependency-free
+* in-process reference (kernel bus + memory store, for tests/dev) in
+* `@classytic/primitives/event-infra`.
+*/
+/**
 * Thrown by a store when `acknowledge` / `fail` is called by a consumer that
 * does not own the event's current lease.
 *
@@ -19,6 +37,30 @@ var OutboxOwnershipError = class extends Error {
 		this.currentOwner = currentOwner;
 	}
 };
+/**
+* Thrown by `save` when a row with this event id already exists with a DIFFERENT payload.
+* A same-id, same-payload save is an idempotent success; a different payload is two
+* occurrences minted onto one id, and dropping either one loses money silently.
+*/
+var OutboxConflictError = class extends Error {
+	name = "OutboxConflictError";
+	code = "outbox.conflict";
+	eventId;
+	eventType;
+	constructor(eventId, eventType) {
+		super(`Outbox already holds event "${eventId}" (${eventType}) with a different payload — two occurrences share one id. Derive the occurrence from the aggregate id plus the step.`);
+		this.eventId = eventId;
+		this.eventType = eventType;
+	}
+};
+/**
+* Order-independent fingerprint of an event payload as it travels (JSON: `Date` becomes its
+* ISO string, `undefined` drops). Stores compare it on a duplicate id; see {@link OutboxConflictError}.
+*/
+function outboxPayloadFingerprint(event) {
+	const wire = JSON.parse(JSON.stringify(event.payload ?? null));
+	return canonicalDigest(wire);
+}
 /** Thrown when an event missing `type` or `meta.id` is passed to the outbox. */
 var InvalidOutboxEventError = class extends Error {
 	name = "InvalidOutboxEventError";
@@ -90,4 +132,4 @@ const OUTBOX_STATUSES = [
 	"dead_letter"
 ];
 //#endregion
-export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxOwnershipError };
+export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxConflictError, OutboxOwnershipError, outboxPayloadFingerprint };

package/dist/payment-events.d.mts

@@ -119,6 +119,9 @@ interface PaymentRefundedPayload {
   refundId: string;
   providerRef?: string;
   providerCode: string;
+  /** How the original payment moved — money goes back the way it came, so this places the refund too. */
+  methodKind: PaymentMethodKind;
+  methodCode?: string;
   /** Amount refunded in this event — may be less than the original payment. */
   refundedAmount: Money;
   /** Original payment total — present so consumers can compute remaining refundable without a Payment lookup. */
@@ -142,6 +145,9 @@ interface PaymentReversedPayload {
   paymentId: string;
   providerRef?: string;
   providerCode: string;
+  /** How the payment being unwound moved. */
+  methodKind: PaymentMethodKind;
+  methodCode?: string;
   /** Amount being unwound — equals the original payment for full reversal, less for partial. */
   reversedAmount: Money;
   /** Original payment total — present so consumers can detect partial vs full without a Payment lookup. */

package/dist/period.d.mts

@@ -123,6 +123,27 @@ declare function resolveMonth(year: number, month: number, timezone: string): Da
 declare function resolveQuarter(year: number, quarter: 1 | 2 | 3 | 4, timezone: string): DateRange;
 /** Half-open `[start, end)` range covering one local calendar year. */
 declare function resolveYear(year: number, timezone: string): DateRange;
+/** A fiscal year: the calendar year it starts in, its label, and its half-open local range. */
+interface FiscalYear {
+  startYear: number;
+  /** `2026-27` for a year starting mid-calendar-year; `2026` for one starting in January. */
+  label: string;
+  range: DateRange;
+}
+/** Half-open range of the fiscal year starting on the 1st of `startMonth` of `startYear`, local to `timezone`. */
+declare function resolveFiscalYear(startYear: number, opts: {
+  startMonth: number;
+  timezone: string;
+}): DateRange;
+/**
+ * The fiscal year `date` falls in — 1 July–30 June (Bangladesh, Australia), 1 April–31 March (India),
+ * 1 January (most) — decided on the LOCAL calendar day in `timezone`, so the last evening of June in Dhaka
+ * is still the old year.
+ */
+declare function fiscalYearOf(date: Date, opts: {
+  startMonth: number;
+  timezone: string;
+}): FiscalYear;
 /**
  * Half-open range spanning two local dates, INCLUSIVE of both days — what an
  * operator means by "1st to 31st". The half-open end is therefore the start of
@@ -209,4 +230,4 @@ declare function parsePeriod(label: string, timezone?: string): Period;
  */
 declare function formatPeriod(period: Period): string;
 //#endregion
-export { DateRange, DateRangeError, Period, PeriodError, PeriodErrorCode, PeriodGranularity, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };
+export { DateRange, DateRangeError, FiscalYear, Period, PeriodError, PeriodErrorCode, PeriodGranularity, dayStart, fiscalYearOf, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveFiscalYear, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };

package/dist/period.mjs

@@ -181,6 +181,35 @@ function resolveYear(year, timezone) {
 		end: dayStart(`${y + 1}-01-01`, zone)
 	};
 }
+/** Half-open range of the fiscal year starting on the 1st of `startMonth` of `startYear`, local to `timezone`. */
+function resolveFiscalYear(startYear, opts) {
+	const zone = assertZone(opts.timezone);
+	const y = assertYear(startYear);
+	const m = assertMonth(opts.startMonth);
+	return {
+		start: dayStart(`${y}-${pad2(m)}-01`, zone),
+		end: dayStart(`${y + 1}-${pad2(m)}-01`, zone)
+	};
+}
+/**
+* The fiscal year `date` falls in — 1 July–30 June (Bangladesh, Australia), 1 April–31 March (India),
+* 1 January (most) — decided on the LOCAL calendar day in `timezone`, so the last evening of June in Dhaka
+* is still the old year.
+*/
+function fiscalYearOf(date, opts) {
+	const zone = assertZone(opts.timezone);
+	const m = assertMonth(opts.startMonth);
+	const [y, mm] = String(civilDateOf(date, zone)).split("-").map(Number);
+	const startYear = mm >= m ? y : y - 1;
+	return {
+		startYear,
+		label: m === 1 ? String(startYear) : `${startYear}-${pad2((startYear + 1) % 100)}`,
+		range: resolveFiscalYear(startYear, {
+			startMonth: m,
+			timezone: zone
+		})
+	};
+}
 /**
 * Half-open range spanning two local dates, INCLUSIVE of both days — what an
 * operator means by "1st to 31st". The half-open end is therefore the start of
@@ -388,4 +417,4 @@ function formatPeriod(period) {
 	throw new PeriodError("INVALID_LABEL", "An ad-hoc Period (start + end) has no canonical label.");
 }
 //#endregion
-export { DateRangeError, PeriodError, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };
+export { DateRangeError, PeriodError, dayStart, fiscalYearOf, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveFiscalYear, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };

package/dist/phone.d.mts

@@ -40,7 +40,19 @@ declare function formatPhone(phone: PhoneNumber): string;
  * @example formatNational(parsePhone('+14155550182').value!) → '+1 415 555 0182'
  */
 declare function formatNational(phone: PhoneNumber): string;
+/**
+ * Prefix of a stored PLACEHOLDER phone: a record whose `phone` is required and
+ * unique but was created before a number was known gets `pending_<id>`. It means
+ * "no number collected" — never a number to show, dial, dedupe or search on.
+ */
+declare const PLACEHOLDER_PHONE_PREFIX = "pending_";
+/** Mint the placeholder for a phone-less record — unique per `id`. */
+declare function placeholderPhone(id: string): string;
+/** True for a stored placeholder (see {@link PLACEHOLDER_PHONE_PREFIX}); whitespace-tolerant. */
+declare function isPlaceholderPhone(value: unknown): boolean;
+/** A stored phone worth showing: trimmed, or `null` for empty or a placeholder. */
+declare function shownPhone(value: unknown): string | null;
 /** Type guard. */
 declare function isPhoneNumber(value: unknown): value is PhoneNumber;
 //#endregion
-export { PhoneError, PhoneErrorCode, PhoneNumber, formatNational, formatPhone, isPhoneNumber, parsePhone };
+export { PLACEHOLDER_PHONE_PREFIX, PhoneError, PhoneErrorCode, PhoneNumber, formatNational, formatPhone, isPhoneNumber, isPlaceholderPhone, parsePhone, placeholderPhone, shownPhone };

package/dist/phone.mjs

@@ -302,9 +302,29 @@ function formatNational(phone) {
 	const groups = phone.nationalNumber.match(/.{1,3}/g) ?? [];
 	return `+${phone.callingCode} ${groups.join(" ")}`.trim();
 }
+/**
+* Prefix of a stored PLACEHOLDER phone: a record whose `phone` is required and
+* unique but was created before a number was known gets `pending_<id>`. It means
+* "no number collected" — never a number to show, dial, dedupe or search on.
+*/
+const PLACEHOLDER_PHONE_PREFIX = "pending_";
+/** Mint the placeholder for a phone-less record — unique per `id`. */
+function placeholderPhone(id) {
+	return `${PLACEHOLDER_PHONE_PREFIX}${id}`;
+}
+/** True for a stored placeholder (see {@link PLACEHOLDER_PHONE_PREFIX}); whitespace-tolerant. */
+function isPlaceholderPhone(value) {
+	return typeof value === "string" && value.trim().startsWith("pending_");
+}
+/** A stored phone worth showing: trimmed, or `null` for empty or a placeholder. */
+function shownPhone(value) {
+	if (typeof value !== "string") return null;
+	const v = value.trim();
+	return v && !isPlaceholderPhone(v) ? v : null;
+}
 /** 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 };
+export { PLACEHOLDER_PHONE_PREFIX, PhoneError, formatNational, formatPhone, isPhoneNumber, isPlaceholderPhone, parsePhone, placeholderPhone, shownPhone };

package/dist/proration.d.mts

@@ -62,6 +62,16 @@ declare function splitByPeriodFraction(amount: Money, fraction: PeriodFraction):
   readonly consumed: Money;
   readonly remaining: Money;
 };
+/**
+ * The share of `total` carried by `part` of `whole`, in integer minor units — the VAT on a partial
+ * refund, the tax on one tender of a split sale. Largest-remainder rounding, so the share and its
+ * complement sum to `total` exactly; `part === whole` returns `total` untouched.
+ *
+ * @throws ProrationError('INVALID_FRACTION') when an input is not an integer, `whole` is not
+ *   positive, or `part` lies outside `[0, whole]` — a refund larger than its payment is a defect
+ *   upstream, and clamping it would book a plausible number.
+ */
+declare function apportion(total: number, part: number, whole: number): number;
 /**
  * Allocate the `fraction`-weighted part of a `Money` amount, drift-free — the
  * complement (`1 - fraction`) is discarded but computed so rounding is exact
@@ -72,4 +82,4 @@ declare function splitByPeriodFraction(amount: Money, fraction: PeriodFraction):
  */
 declare function allocateMoneyByFraction(amount: Money, fraction: number): Money;
 //#endregion
-export { PeriodFraction, PeriodProgressInput, ProrationError, ProrationErrorCode, ProrationGranularity, allocateMoneyByFraction, periodProgress, splitByPeriodFraction };
+export { PeriodFraction, PeriodProgressInput, ProrationError, ProrationErrorCode, ProrationGranularity, allocateMoneyByFraction, apportion, periodProgress, splitByPeriodFraction };

package/dist/proration.mjs

@@ -108,6 +108,29 @@ function requirePart(result, id) {
 	return part.amount;
 }
 /**
+* The share of `total` carried by `part` of `whole`, in integer minor units — the VAT on a partial
+* refund, the tax on one tender of a split sale. Largest-remainder rounding, so the share and its
+* complement sum to `total` exactly; `part === whole` returns `total` untouched.
+*
+* @throws ProrationError('INVALID_FRACTION') when an input is not an integer, `whole` is not
+*   positive, or `part` lies outside `[0, whole]` — a refund larger than its payment is a defect
+*   upstream, and clamping it would book a plausible number.
+*/
+function apportion(total, part, whole) {
+	if (![
+		total,
+		part,
+		whole
+	].every(Number.isInteger) || whole <= 0 || part < 0 || part > whole) throw new ProrationError("INVALID_FRACTION", `cannot apportion ${total} by ${part} of ${whole}`);
+	return requirePart(allocate(total, [{
+		id: "part",
+		weight: part
+	}, {
+		id: "rest",
+		weight: whole - part
+	}], "by-weight"), "part");
+}
+/**
 * Allocate the `fraction`-weighted part of a `Money` amount, drift-free — the
 * complement (`1 - fraction`) is discarded but computed so rounding is exact
 * against the whole. `fraction` must be in `[0, 1]`.
@@ -129,4 +152,4 @@ function allocateMoneyByFraction(amount, fraction) {
 	};
 }
 //#endregion
-export { ProrationError, allocateMoneyByFraction, periodProgress, splitByPeriodFraction };
+export { ProrationError, allocateMoneyByFraction, apportion, periodProgress, splitByPeriodFraction };

package/dist/signed-token.d.mts

@@ -0,0 +1,54 @@
+//#region src/security/signed-token.d.ts
+/**
+ * Signed tokens: compact JWS (RFC 7515), ES256 over WebCrypto — a server and an offline device sign
+ * and verify the same bytes with no dependency. Claims follow RFC 7519 (`exp`/`nbf`/`iat` in
+ * seconds).
+ *
+ *   const token = await signToken({ sub, exp }, { kid, privateKey }, { typ: 'till-grant+jwt' });
+ *   const read = await verifyToken<Grant>(token, (kid) => keys.get(kid), { typ: 'till-grant+jwt' });
+ *
+ * `typ` is required on both sides, so one kind of token is never accepted as another, and a token
+ * without `exp` is refused.
+ */
+declare const SIGNED_TOKEN_ALG = "ES256";
+/** A P-256 key as JWK; `d` only on a private key. */
+interface EcJwk {
+  kty?: string;
+  crv?: string;
+  x?: string;
+  y?: string;
+  d?: string;
+  [member: string]: unknown;
+}
+interface SigningKey {
+  /** Published with the public key; names it in each token's header. */
+  readonly kid: string;
+  readonly privateKey: CryptoKey;
+}
+type TokenRefusal = 'malformed' | 'unsupported' | 'wrong_type' | 'unknown_key' | 'bad_signature' | 'no_expiry' | 'expired' | 'not_yet_valid';
+type VerifiedToken<T> = {
+  readonly ok: true;
+  readonly claims: T;
+  readonly kid: string;
+} | {
+  readonly ok: false;
+  readonly reason: TokenRefusal;
+};
+declare function signToken(claims: Record<string, unknown>, key: SigningKey, options: {
+  typ: string;
+}): Promise<string>;
+declare function verifyToken<T>(token: string, keyOf: (kid: string) => CryptoKey | undefined | Promise<CryptoKey | undefined>, options: {
+  typ: string;
+  now?: Date | undefined;
+  leewaySeconds?: number | undefined;
+}): Promise<VerifiedToken<T>>;
+/** A P-256 private JWK as a non-extractable signing key. */
+declare function importSigningKey(privateJwk: EcJwk): Promise<CryptoKey>;
+/** A P-256 public JWK as a verifying key. */
+declare function importVerifyingKey(publicJwk: EcJwk): Promise<CryptoKey>;
+/** The public half of a P-256 private JWK — what is published. */
+declare function publicJwkOf(privateJwk: EcJwk): EcJwk;
+/** A fresh key pair as JWKs — for provisioning a deployment's signing key. */
+declare function generateSigningJwk(): Promise<EcJwk>;
+//#endregion
+export { EcJwk, SIGNED_TOKEN_ALG, SigningKey, TokenRefusal, VerifiedToken, generateSigningJwk, importSigningKey, importVerifyingKey, publicJwkOf, signToken, verifyToken };

package/dist/signed-token.mjs

@@ -0,0 +1,139 @@
+//#region src/security/signed-token.ts
+/**
+* Signed tokens: compact JWS (RFC 7515), ES256 over WebCrypto — a server and an offline device sign
+* and verify the same bytes with no dependency. Claims follow RFC 7519 (`exp`/`nbf`/`iat` in
+* seconds).
+*
+*   const token = await signToken({ sub, exp }, { kid, privateKey }, { typ: 'till-grant+jwt' });
+*   const read = await verifyToken<Grant>(token, (kid) => keys.get(kid), { typ: 'till-grant+jwt' });
+*
+* `typ` is required on both sides, so one kind of token is never accepted as another, and a token
+* without `exp` is refused.
+*/
+const SIGNED_TOKEN_ALG = "ES256";
+const ECDSA = {
+	name: "ECDSA",
+	namedCurve: "P-256"
+};
+const SIGN = {
+	name: "ECDSA",
+	hash: "SHA-256"
+};
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function toBase64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(text) {
+	if (!/^[A-Za-z0-9_-]*$/.test(text)) return null;
+	const binary = atob(text.replace(/-/g, "+").replace(/_/g, "/"));
+	const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+	for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+function parseJson(segment) {
+	const bytes = fromBase64Url(segment);
+	if (!bytes) return null;
+	try {
+		const value = JSON.parse(decoder.decode(bytes));
+		return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+	} catch {
+		return null;
+	}
+}
+async function signToken(claims, key, options) {
+	const input = `${toBase64Url(encoder.encode(JSON.stringify({
+		alg: SIGNED_TOKEN_ALG,
+		typ: options.typ,
+		kid: key.kid
+	})))}.${toBase64Url(encoder.encode(JSON.stringify(claims)))}`;
+	return `${input}.${toBase64Url(new Uint8Array(await crypto.subtle.sign(SIGN, key.privateKey, encoder.encode(input))))}`;
+}
+async function verifyToken(token, keyOf, options) {
+	const parts = typeof token === "string" ? token.split(".") : [];
+	if (parts.length !== 3) return {
+		ok: false,
+		reason: "malformed"
+	};
+	const [headerPart, payloadPart, signaturePart] = parts;
+	const header = parseJson(headerPart);
+	const claims = parseJson(payloadPart);
+	const signature = fromBase64Url(signaturePart);
+	if (!header || !claims || !signature) return {
+		ok: false,
+		reason: "malformed"
+	};
+	if (header.alg !== "ES256" || header.crit !== void 0) return {
+		ok: false,
+		reason: "unsupported"
+	};
+	if (header.typ !== options.typ) return {
+		ok: false,
+		reason: "wrong_type"
+	};
+	if (typeof header.kid !== "string") return {
+		ok: false,
+		reason: "unknown_key"
+	};
+	const key = await keyOf(header.kid);
+	if (!key) return {
+		ok: false,
+		reason: "unknown_key"
+	};
+	if (!await crypto.subtle.verify(SIGN, key, signature, encoder.encode(`${headerPart}.${payloadPart}`))) return {
+		ok: false,
+		reason: "bad_signature"
+	};
+	const now = Math.floor((options.now ?? /* @__PURE__ */ new Date()).getTime() / 1e3);
+	const leeway = options.leewaySeconds ?? 0;
+	if (typeof claims.exp !== "number") return {
+		ok: false,
+		reason: "no_expiry"
+	};
+	if (now >= claims.exp + leeway) return {
+		ok: false,
+		reason: "expired"
+	};
+	if (typeof claims.nbf === "number" && now < claims.nbf - leeway) return {
+		ok: false,
+		reason: "not_yet_valid"
+	};
+	return {
+		ok: true,
+		claims,
+		kid: header.kid
+	};
+}
+/** A P-256 private JWK as a non-extractable signing key. */
+function importSigningKey(privateJwk) {
+	return crypto.subtle.importKey("jwk", privateJwk, ECDSA, false, ["sign"]);
+}
+/** A P-256 public JWK as a verifying key. */
+function importVerifyingKey(publicJwk) {
+	const { kty, crv, x, y } = publicJwk;
+	return crypto.subtle.importKey("jwk", {
+		kty,
+		crv,
+		x,
+		y
+	}, ECDSA, false, ["verify"]);
+}
+/** The public half of a P-256 private JWK — what is published. */
+function publicJwkOf(privateJwk) {
+	const { kty, crv, x, y } = privateJwk;
+	return {
+		kty,
+		crv,
+		x,
+		y
+	};
+}
+/** A fresh key pair as JWKs — for provisioning a deployment's signing key. */
+async function generateSigningJwk() {
+	const pair = await crypto.subtle.generateKey(ECDSA, true, ["sign", "verify"]);
+	return await crypto.subtle.exportKey("jwk", pair.privateKey);
+}
+//#endregion
+export { SIGNED_TOKEN_ALG, generateSigningJwk, importSigningKey, importVerifyingKey, publicJwkOf, signToken, verifyToken };

package/dist/split-allocation.d.mts

@@ -60,7 +60,7 @@ interface SplitResult {
   readonly method: SplitMethod;
   readonly parts: readonly SplitPart[];
 }
-type SplitAllocationErrorCode = 'INVALID_TOTAL' | 'EMPTY_SUBJECTS' | 'INVALID_WEIGHT' | 'INVALID_PERCENT' | 'ZERO_WEIGHT_SUM' | 'DUPLICATE_SUBJECT_ID';
+type SplitAllocationErrorCode = 'INVALID_TOTAL' | 'EMPTY_SUBJECTS' | 'INVALID_WEIGHT' | 'INVALID_PERCENT' | 'ZERO_WEIGHT_SUM' | 'DUPLICATE_SUBJECT_ID' | 'DISCOUNT_EXCEEDS_BASE';
 declare class SplitAllocationError extends Error {
   readonly name = "SplitAllocationError";
   readonly code: SplitAllocationErrorCode;
@@ -80,5 +80,23 @@ declare class SplitAllocationError extends Error {
 declare function allocate(total: number, subjects: readonly SplitSubject[], method: SplitMethod): SplitResult;
 /** True if `sum(parts[i].amount) === result.total`. Useful as an assertion in host code. */
 declare function isBalanced(result: SplitResult): boolean;
+/** A line a document-level discount may be spread over. */
+interface DiscountSubject {
+  readonly id: string;
+  /** The line's value before the discount, integer minor units (non-negative). */
+  readonly weight: number;
+  /** `false` for a line the discount was never computed on (a delivery charge, an auto-added fee). Absent ⇒ eligible. */
+  readonly discountable?: boolean;
+}
+/**
+ * THE discount allocation: spread a document-level discount over its eligible lines, by value,
+ * exact largest remainder. Every document that splits one discount — the order, its invoice,
+ * its credit notes, a return's value — calls this, so they agree to the minor unit.
+ *
+ * Returns a FULL map in input order: every subject id, `0` for an ineligible or zero-weight one.
+ * `0` discount allocates zeros; a discount equal to the eligible base allocates all of it; a
+ * discount above it throws `DISCOUNT_EXCEEDS_BASE` — the figures disagree.
+ */
+declare function allocateDiscount(discount: number, subjects: readonly DiscountSubject[]): ReadonlyMap<string, number>;
 //#endregion
-export { SplitAllocationError, SplitAllocationErrorCode, SplitMethod, SplitPart, SplitResult, SplitSubject, allocate, isBalanced };
+export { DiscountSubject, SplitAllocationError, SplitAllocationErrorCode, SplitMethod, SplitPart, SplitResult, SplitSubject, allocate, allocateDiscount, isBalanced };