@classytic/primitives 0.18.0 → 0.20.0

package/dist/person-parse.mjs

@@ -0,0 +1,109 @@
+//#region src/identity/person-parse.ts
+/**
+* Does this `PersonName` carry at least one usable, non-empty name part?
+*
+* Used by both the customer-model virtuals (`fullName` / `displayName`) and
+* any code path that needs to decide "is this customer effectively unnamed".
+* Defends against the legacy data shape and any future write that lands an
+* all-empty `{ given: '', family: '' }`. Without this, `formatDisplayName`
+* from `@classytic/primitives` returns the literal string `"undefined
+* undefined"` for empty names — a bug we've patched at the write boundary
+* but keep guarding at the read boundary too (defense in depth).
+*/
+function hasUsableName(name) {
+	if (!name) return false;
+	return Boolean(name.preferred?.trim() || name.given?.trim() || name.family?.trim() || name.middle?.trim() || name.prefix?.trim() || name.suffix?.trim());
+}
+/**
+* Detect a "looks like an identifier, not a person name" string.
+*
+* Better Auth signs OAuth users in with `user.name` populated from the
+* provider — but Apple-private-relay / Google-custom-name flows (and our
+* own guest-checkout fallback) sometimes put the BA `user.id` string into
+* `user.name`. That id is a 20-char base64-url-safe nanoid like
+* `gcqAUBgGpRnDZbyPgKbS`, and storing it as `name.given` leaks the
+* internal id into the dashboard customers table.
+*
+* Heuristic (cheap, no false-positives observed on real BD names):
+*   - 12+ chars
+*   - no whitespace (real "full names" have spaces; single-name locales
+*     are usually < 12 chars: "Sadman", "Nirjhar", "Subarna", etc.)
+*   - at least 3 uppercase AND 3 lowercase letters (Title-Case names
+*     don't qualify — "Sadman Chowdhury" has 2 uppercase chars; even
+*     the longest single Bangla romanisation rarely hits 3+ uppercase
+*     in one token)
+*   - OR a bare 24-char lowercase hex (ObjectId)
+*
+* If a real name ever gets misclassified, the customer can edit it from
+* the profile page and the heuristic only runs at create / link time.
+*/
+function looksLikeIdentifierNotName(value) {
+	if (!value) return false;
+	if (/^[a-f0-9]{24}$/.test(value)) return true;
+	if (value.length < 12) return false;
+	if (/\s/.test(value)) return false;
+	const upper = (value.match(/[A-Z]/g) ?? []).length;
+	const lower = (value.match(/[a-z]/g) ?? []).length;
+	return upper >= 3 && lower >= 3;
+}
+/**
+* Pick a display fallback when `user.name` is missing or token-like.
+* Prefers the email local-part (capitalised) so customers see a recognisable
+* label in the dashboard instead of "Unknown" or a leaked id.
+*/
+function fallbackNameFromUser(user, defaultLabel) {
+	const email = user.email?.trim();
+	if (email?.includes("@")) {
+		const cleaned = (email.split("@", 1)[0] ?? "").replace(/[^a-zA-Z]+/g, " ").trim();
+		if (cleaned.length >= 2) return cleaned.split(/\s+/).map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()).join(" ");
+	}
+	return defaultLabel;
+}
+/**
+* Sanitize a display-name string before it gets snapshotted into a
+* derivative collection (order, invoice, shipment, transaction, etc.).
+*
+* The customer-creation boundary (`customer.repository.ts`) already
+* scrubs token-shaped names. This helper is the second line of defence
+* for write paths that copy `customer.name` somewhere else — if the
+* source ever regressed, the snapshot still wouldn't carry the leak.
+*
+* Returns:
+*   - the trimmed input when it's a real-looking name
+*   - `fallback` when the input is empty, undefined, or token-shaped
+*
+* Caller is responsible for picking a sensible `fallback` (e.g. the
+* email local-part, "Customer", "Walk-in", etc.).
+*/
+function sanitizeDisplayName(value, fallback) {
+	const trimmed = (value ?? "").trim();
+	if (!trimmed) return fallback;
+	if (looksLikeIdentifierNotName(trimmed)) return fallback;
+	return trimmed;
+}
+/**
+* Split a flat "Full Name" string into a structured `PersonName`.
+*
+* Callers at the auth / POS boundary pass flat names; storage is structured.
+* Single-token names go in `given` with an empty `family` (many BD and
+* single-name locales store a single name, which is valid).
+*
+* `user` (optional) supplies an `email` so we can derive a sensible display
+* fallback when the input is empty or looks like a BA user id rather than
+* a real name. Without `user`, the static `fallback` arg is the floor.
+*/
+function nameFromString(flat, fallback, user) {
+	const trimmed = (flat ?? "").trim();
+	const parts = (trimmed && !looksLikeIdentifierNotName(trimmed) ? trimmed : user ? fallbackNameFromUser(user, fallback) : fallback).split(/\s+/);
+	if (parts.length <= 1) return {
+		given: parts[0] ?? fallback,
+		family: ""
+	};
+	const family = parts.pop() ?? "";
+	return {
+		given: parts.join(" "),
+		family
+	};
+}
+//#endregion
+export { fallbackNameFromUser, hasUsableName, looksLikeIdentifierNotName, nameFromString, sanitizeDisplayName };

package/dist/proration.d.mts

@@ -0,0 +1,76 @@
+import { n as Money } from "./money-DPo9fLBi.mjs";
+
+//#region src/money/proration.d.ts
+/**
+ * How to count days within a period.
+ *
+ * - `'whole_day'` (default) — integer calendar-day counts. Callers normalize
+ *   `periodStart`/`periodEnd`/`asOf` to business-local midnight first, so this
+ *   matches "day-of-month" proration (the Stripe default, how ~99% of SaaS
+ *   bill). `periodDays` is clamped to `>= 1`.
+ * - `'exact'` — fractional wall-clock day counts (`ms / 86_400_000`). Use when
+ *   cycles are short and a partial day must be billed precisely.
+ */
+type ProrationGranularity = 'whole_day' | 'exact';
+/** The elapsed/remaining split of a billing period at a change instant. */
+interface PeriodFraction {
+  /** Total days in the period. `>= 1` for `whole_day`; `> 0` for `exact`. */
+  readonly periodDays: number;
+  /** Days consumed as of the change instant, clamped to `[0, periodDays]`. */
+  readonly elapsedDays: number;
+  /** `periodDays - elapsedDays`. */
+  readonly remainingDays: number;
+  /** `remainingDays / periodDays`, in `[0, 1]`. */
+  readonly remainingFraction: number;
+}
+interface PeriodProgressInput {
+  /** Period start instant (business-tz-normalized by the caller). */
+  readonly periodStart: Date;
+  /** Period end instant — must be strictly after `periodStart`. */
+  readonly periodEnd: Date;
+  /** The change/quote instant. Clamped into `[periodStart, periodEnd]`. */
+  readonly asOf: Date;
+  /** Day-counting granularity. Default `'whole_day'`. */
+  readonly granularity?: ProrationGranularity;
+}
+type ProrationErrorCode = 'INVALID_PERIOD' | 'INVALID_FRACTION' | 'ALLOCATION_INVARIANT';
+declare class ProrationError extends Error {
+  readonly name = "ProrationError";
+  readonly code: ProrationErrorCode;
+  constructor(code: ProrationErrorCode, message: string);
+}
+/**
+ * Compute how much of a period is elapsed vs remaining at `asOf`.
+ *
+ * `asOf` before the period start ⇒ nothing elapsed (full remaining);
+ * `asOf` after the period end ⇒ fully elapsed (nothing remaining).
+ *
+ * @throws ProrationError('INVALID_PERIOD') if a date is invalid or
+ *   `periodEnd <= periodStart`.
+ */
+declare function periodProgress(input: PeriodProgressInput): PeriodFraction;
+/**
+ * Split a `Money` amount into its consumed and remaining parts across a
+ * {@link PeriodFraction}, drift-free: `consumed.amount + remaining.amount ===
+ * amount.amount` exactly (largest-remainder allocation). Sign is preserved, so
+ * a negative amount (a reversal) splits symmetrically.
+ *
+ * This is the load-bearing primitive for proration: the "unused value" a
+ * plan-change credits is `remaining`; the "already-consumed value" is
+ * `consumed`.
+ */
+declare function splitByPeriodFraction(amount: Money, fraction: PeriodFraction): {
+  readonly consumed: Money;
+  readonly remaining: Money;
+};
+/**
+ * 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]`.
+ *
+ * @throws ProrationError('INVALID_FRACTION') if `fraction` is outside `[0, 1]`
+ *   or not finite.
+ */
+declare function allocateMoneyByFraction(amount: Money, fraction: number): Money;
+//#endregion
+export { PeriodFraction, PeriodProgressInput, ProrationError, ProrationErrorCode, ProrationGranularity, allocateMoneyByFraction, periodProgress, splitByPeriodFraction };

package/dist/proration.mjs

@@ -0,0 +1,132 @@
+import { allocate } from "./split-allocation.mjs";
+//#region src/money/proration.ts
+/**
+* Pure proration ARITHMETIC — fraction / period / allocation / rounding only.
+*
+* This module deliberately holds **no commercial policy**. It does not know
+* what "an upgrade" is, whether a discount is creditable, how tax is treated,
+* or whether a downgrade yields cash vs store credit. Those decisions live in
+* the subscription/contract kernel (`@classytic/contract`
+* `calculatePlanChangeProration(...)`), which composes these primitives.
+*
+* It is also **timezone-agnostic**: callers pass already-resolved `Date`
+* instants (normalized to the deployment's business timezone via
+* `@classytic/primitives/timezone` upstream). This module never reads a clock
+* and never applies an offset — pass instants, get numbers.
+*
+* Money is integer minor units throughout; splits use the largest-remainder
+* allocator so `consumed + remaining === amount` exactly, with no penny drift.
+*/
+const MS_PER_DAY = 864e5;
+var ProrationError = class extends Error {
+	name = "ProrationError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+function isValidDate(d) {
+	return d instanceof Date && !Number.isNaN(d.getTime());
+}
+/**
+* Compute how much of a period is elapsed vs remaining at `asOf`.
+*
+* `asOf` before the period start ⇒ nothing elapsed (full remaining);
+* `asOf` after the period end ⇒ fully elapsed (nothing remaining).
+*
+* @throws ProrationError('INVALID_PERIOD') if a date is invalid or
+*   `periodEnd <= periodStart`.
+*/
+function periodProgress(input) {
+	const { periodStart, periodEnd, asOf, granularity = "whole_day" } = input;
+	if (!isValidDate(periodStart) || !isValidDate(periodEnd) || !isValidDate(asOf)) throw new ProrationError("INVALID_PERIOD", "periodStart, periodEnd and asOf must be valid Dates");
+	const startMs = periodStart.getTime();
+	const endMs = periodEnd.getTime();
+	if (endMs <= startMs) throw new ProrationError("INVALID_PERIOD", `periodEnd (${periodEnd.toISOString()}) must be after periodStart (${periodStart.toISOString()})`);
+	const clampedAsOfMs = Math.min(Math.max(asOf.getTime(), startMs), endMs);
+	const rawPeriodDays = (endMs - startMs) / MS_PER_DAY;
+	const rawElapsedDays = (clampedAsOfMs - startMs) / MS_PER_DAY;
+	let periodDays;
+	let elapsedDays;
+	if (granularity === "whole_day") {
+		periodDays = Math.max(1, Math.round(rawPeriodDays));
+		elapsedDays = Math.min(periodDays, Math.max(0, Math.round(rawElapsedDays)));
+	} else {
+		periodDays = rawPeriodDays;
+		elapsedDays = Math.min(periodDays, Math.max(0, rawElapsedDays));
+	}
+	const remainingDays = periodDays - elapsedDays;
+	return {
+		periodDays,
+		elapsedDays,
+		remainingDays,
+		remainingFraction: remainingDays / periodDays
+	};
+}
+/**
+* Split a `Money` amount into its consumed and remaining parts across a
+* {@link PeriodFraction}, drift-free: `consumed.amount + remaining.amount ===
+* amount.amount` exactly (largest-remainder allocation). Sign is preserved, so
+* a negative amount (a reversal) splits symmetrically.
+*
+* This is the load-bearing primitive for proration: the "unused value" a
+* plan-change credits is `remaining`; the "already-consumed value" is
+* `consumed`.
+*/
+function splitByPeriodFraction(amount, fraction) {
+	const result = allocate(amount.amount, [{
+		id: "consumed",
+		weight: fraction.elapsedDays
+	}, {
+		id: "remaining",
+		weight: fraction.remainingDays
+	}], "by-weight");
+	return {
+		consumed: {
+			amount: requirePart(result, "consumed"),
+			currency: amount.currency
+		},
+		remaining: {
+			amount: requirePart(result, "remaining"),
+			currency: amount.currency
+		}
+	};
+}
+/**
+* Read one allocated part by id, or THROW.
+*
+* This used to be `…?.amount ?? 0`. A missing part is not "no money" — it is a
+* broken allocator, and defaulting it to zero turns that into a silently
+* plausible number: the unused-value credit on a plan change becomes 0 and the
+* customer is quietly not credited. Nothing downstream can tell that apart from
+* a genuinely fully-consumed period.
+*/
+function requirePart(result, id) {
+	const part = result.parts.find((p) => p.id === id);
+	if (part === void 0) throw new ProrationError("ALLOCATION_INVARIANT", `allocator returned no part '${id}' (got: ${result.parts.map((p) => p.id).join(", ") || "none"})`);
+	return part.amount;
+}
+/**
+* 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]`.
+*
+* @throws ProrationError('INVALID_FRACTION') if `fraction` is outside `[0, 1]`
+*   or not finite.
+*/
+function allocateMoneyByFraction(amount, fraction) {
+	if (!Number.isFinite(fraction) || fraction < 0 || fraction > 1) throw new ProrationError("INVALID_FRACTION", `fraction must be in [0, 1], got ${fraction}`);
+	return {
+		amount: requirePart(allocate(amount.amount, [{
+			id: "part",
+			weight: fraction
+		}, {
+			id: "rest",
+			weight: 1 - fraction
+		}], "by-weight"), "part"),
+		currency: amount.currency
+	};
+}
+//#endregion
+export { ProrationError, allocateMoneyByFraction, periodProgress, splitByPeriodFraction };

package/dist/sla-policy.d.mts

@@ -1,4 +1,4 @@
-import { IsoWeekday } from "./cadence.mjs";
+import { s as IsoWeekday } from "./cadence-BFQVC1Qp.mjs";
 import { SLA } from "./sla.mjs";
 
 //#region src/scheduling/sla-policy.d.ts

package/dist/state-machine.mjs

@@ -149,6 +149,19 @@ function defineStateMachine(definition) {
 */
 async function assertAndClaim(machine, repo, id, args) {
 	const sources = Array.isArray(args.from) ? args.from : [args.from];
+	/**
+	* An EMPTY source list must never reach `claim()`.
+	*
+	* `validSources(to)` returns `[]` for a status nothing transitions into, and
+	* the multi-source idiom in the docblock above (`from: machine.validSources(x)`)
+	* makes that easy to hit. With `[]` the assert loop below runs ZERO times — the
+	* domain check silently does not happen — and the CAS is then handed an empty
+	* allow-list. Mongo's `$in: []` matches nothing so today that fails closed and
+	* looks exactly like a race-loss (`null`), which is the wrong diagnosis; a kit
+	* that read an empty list as "no constraint" would fail OPEN and claim from any
+	* state at all. An empty allow-list must never mean "any".
+	*/
+	if (sources.length === 0) throw new IllegalTransitionError(machine.name, id, "(none)", args.to);
 	for (const from of sources) machine.assertTransition(id, from, args.to);
 	return repo.claim(id, {
 		from: Array.isArray(args.from) ? args.from : args.from,

package/dist/suspension.d.mts

@@ -1,4 +1,4 @@
-import { UtcOffsetMinutes } from "./calendar.mjs";
+import { t as UtcOffsetMinutes } from "./calendar-B6fm-FbR.mjs";
 import { DateRange } from "./period.mjs";
 import { StatusChangeEntry } from "./status-history.mjs";
 

package/dist/timezone-tlG7ygwx.d.mts

@@ -0,0 +1,114 @@
+import { t as Brand } from "./brand-LLXqoh5J.mjs";
+import { s as IsoWeekday } from "./cadence-BFQVC1Qp.mjs";
+import { t as UtcOffsetMinutes } from "./calendar-B6fm-FbR.mjs";
+
+//#region src/scheduling/timezone.d.ts
+declare class TimeZoneError extends Error {
+  constructor(message: string);
+}
+/**
+ * Is `zone` a valid IANA timezone name on this runtime's ICU data?
+ * Use at BOOT to validate host config (an offer's `timezone`, an org
+ * setting) — fail loud at wiring time, not on the first localized read.
+ */
+declare function isValidTimeZone(zone: string): boolean;
+/**
+ * Every IANA timezone name this runtime supports — the data source for a
+ * Google-Calendar-style zone picker. Straight from ICU via
+ * `Intl.supportedValuesOf` (Node >= 18); no bundled tz list to go stale.
+ *
+ * UIs typically label each entry with its current offset:
+ * `listTimeZones().map((z) => ({ zone: z, label: zoneOffsetLabel(now, z) }))`.
+ */
+declare function listTimeZones(): readonly string[];
+/**
+ * The zone's UTC offset AT `instant`, in minutes east of UTC — DST-exact.
+ * `zoneOffsetMinutes(july, 'Europe/London')` → 60; `(january, …)` → 0;
+ * `(any, 'Asia/Dhaka')` → 360.
+ *
+ * This is the value `/calendar`'s docstring tells hosts to "resolve and pass
+ * in": `startOfMonth(instant, zoneOffsetMinutes(instant, zone))`.
+ */
+declare function zoneOffsetMinutes(instant: Date, zone: string): UtcOffsetMinutes;
+/**
+ * The zone's offset label AT `instant` — `'GMT+06:00'` / `'GMT-05:30'` /
+ * `'GMT'`. Ready-made display text for zone pickers.
+ */
+declare function zoneOffsetLabel(instant: Date, zone: string): string;
+interface LocalTimeParts {
+  /** ISO weekday in the zone — 1=Mon … 7=Sun (matches `/cadence`). */
+  isoWeekday: IsoWeekday;
+  /** Hour of day in the zone, 0–23. */
+  hour: number;
+  /** Minute of hour, 0–59. */
+  minute: number;
+  /** `hour * 60 + minute` — the shape "HH:MM window" checks want. */
+  minutesOfDay: number;
+}
+/**
+ * The wall-clock weekday + time of `instant` in `zone` — what pricing
+ * schedules ("peak Fri 17:00–22:00"), slot grids, and working-hours checks
+ * evaluate against. DST-exact per instant.
+ */
+declare function localTimeParts(instant: Date, zone: string): LocalTimeParts;
+/**
+ * A calendar day — `'YYYY-MM-DD'` — with NO time and NO zone until one is
+ * bound. The type for hotel nights, POS business dates, statement periods,
+ * VAT filing years. Lexicographic order == chronological order, so it's
+ * index- and range-query-friendly as a Mongo string key.
+ */
+type CivilDate = Brand<string, 'CivilDate'>;
+/** Runtime guard for external input. */
+declare function isCivilDate(value: unknown): value is CivilDate;
+/** Validate + brand a `'YYYY-MM-DD'` string. Throws on malformed input. */
+declare function civilDate(value: string): CivilDate;
+/**
+ * The calendar day `instant` falls on IN `zone` — e.g. the POS business
+ * date: `civilDateOf(new Date(), 'Asia/Dhaka')`. Never depends on the
+ * server's TZ env.
+ */
+declare function civilDateOf(instant: Date, zone: string): CivilDate;
+/**
+ * Bind a civil date (+ optional wall time) to a zone → the exact instant.
+ * `civilDateToInstant(night, hotelZone, { hour: 14 })` = check-in instant;
+ * with no `time`, local midnight — the DST-exact "start of that day in that
+ * zone".
+ *
+ * Two-pass offset resolution: the offset is looked up AT the candidate
+ * instant, then re-checked, so days where a DST transition sits between the
+ * wall time and the first guess still resolve correctly. Honest limit: a
+ * wall time that does not exist (inside a spring-forward gap) resolves to
+ * the instant the shifted clock reaches — the same choice Temporal's
+ * `disambiguation: 'compatible'` makes.
+ */
+declare function civilDateToInstant(cd: CivilDate, zone: string, time?: {
+  hour?: number;
+  minute?: number;
+  second?: number;
+  millisecond?: number;
+}): Date;
+/**
+ * Pure calendar-day arithmetic — `addCivilDays('2026-02-28', 1)` →
+ * `'2026-03-01'`. Zone-free by definition (a civil date has no zone);
+ * use it to iterate hotel nights / statement days.
+ */
+declare function addCivilDays(cd: CivilDate, days: number): CivilDate;
+/**
+ * Whole days from `a` to `b` (positive when `b` is later) — the NIGHTS
+ * count for a `[checkIn, checkOut)` stay expressed as civil dates.
+ */
+/**
+ * The ISO-8601 week a civil date belongs to, as `YYYY-Www`.
+ *
+ * Zone-free by definition — a civil date has no zone — so callers resolve the
+ * date in their business timezone FIRST (`civilDateOf`) and label it here.
+ *
+ * ISO week 1 is the week containing the first Thursday, which means the week
+ * YEAR can differ from the date's own: 2025-12-29 is `2026-W01`. Naive
+ * "day-of-year / 7" numbering gets that wrong every few years, silently
+ * splitting one business week across two report buckets.
+ */
+declare function isoWeekOfCivilDate(cd: CivilDate): string;
+declare function civilDaysBetween(a: CivilDate, b: CivilDate): number;
+//#endregion
+export { civilDate as a, civilDaysBetween as c, isoWeekOfCivilDate as d, listTimeZones as f, zoneOffsetMinutes as h, addCivilDays as i, isCivilDate as l, zoneOffsetLabel as m, LocalTimeParts as n, civilDateOf as o, localTimeParts as p, TimeZoneError as r, civilDateToInstant as s, CivilDate as t, isValidTimeZone as u };

package/dist/timezone.d.mts

@@ -1,100 +1,2 @@
-import { t as Brand } from "./brand-LLXqoh5J.mjs";
-import { IsoWeekday } from "./cadence.mjs";
-import { UtcOffsetMinutes } from "./calendar.mjs";
-
-//#region src/scheduling/timezone.d.ts
-declare class TimeZoneError extends Error {
-  constructor(message: string);
-}
-/**
- * Is `zone` a valid IANA timezone name on this runtime's ICU data?
- * Use at BOOT to validate host config (an offer's `timezone`, an org
- * setting) — fail loud at wiring time, not on the first localized read.
- */
-declare function isValidTimeZone(zone: string): boolean;
-/**
- * Every IANA timezone name this runtime supports — the data source for a
- * Google-Calendar-style zone picker. Straight from ICU via
- * `Intl.supportedValuesOf` (Node >= 18); no bundled tz list to go stale.
- *
- * UIs typically label each entry with its current offset:
- * `listTimeZones().map((z) => ({ zone: z, label: zoneOffsetLabel(now, z) }))`.
- */
-declare function listTimeZones(): readonly string[];
-/**
- * The zone's UTC offset AT `instant`, in minutes east of UTC — DST-exact.
- * `zoneOffsetMinutes(july, 'Europe/London')` → 60; `(january, …)` → 0;
- * `(any, 'Asia/Dhaka')` → 360.
- *
- * This is the value `/calendar`'s docstring tells hosts to "resolve and pass
- * in": `startOfMonth(instant, zoneOffsetMinutes(instant, zone))`.
- */
-declare function zoneOffsetMinutes(instant: Date, zone: string): UtcOffsetMinutes;
-/**
- * The zone's offset label AT `instant` — `'GMT+06:00'` / `'GMT-05:30'` /
- * `'GMT'`. Ready-made display text for zone pickers.
- */
-declare function zoneOffsetLabel(instant: Date, zone: string): string;
-interface LocalTimeParts {
-  /** ISO weekday in the zone — 1=Mon … 7=Sun (matches `/cadence`). */
-  isoWeekday: IsoWeekday;
-  /** Hour of day in the zone, 0–23. */
-  hour: number;
-  /** Minute of hour, 0–59. */
-  minute: number;
-  /** `hour * 60 + minute` — the shape "HH:MM window" checks want. */
-  minutesOfDay: number;
-}
-/**
- * The wall-clock weekday + time of `instant` in `zone` — what pricing
- * schedules ("peak Fri 17:00–22:00"), slot grids, and working-hours checks
- * evaluate against. DST-exact per instant.
- */
-declare function localTimeParts(instant: Date, zone: string): LocalTimeParts;
-/**
- * A calendar day — `'YYYY-MM-DD'` — with NO time and NO zone until one is
- * bound. The type for hotel nights, POS business dates, statement periods,
- * VAT filing years. Lexicographic order == chronological order, so it's
- * index- and range-query-friendly as a Mongo string key.
- */
-type CivilDate = Brand<string, 'CivilDate'>;
-/** Runtime guard for external input. */
-declare function isCivilDate(value: unknown): value is CivilDate;
-/** Validate + brand a `'YYYY-MM-DD'` string. Throws on malformed input. */
-declare function civilDate(value: string): CivilDate;
-/**
- * The calendar day `instant` falls on IN `zone` — e.g. the POS business
- * date: `civilDateOf(new Date(), 'Asia/Dhaka')`. Never depends on the
- * server's TZ env.
- */
-declare function civilDateOf(instant: Date, zone: string): CivilDate;
-/**
- * Bind a civil date (+ optional wall time) to a zone → the exact instant.
- * `civilDateToInstant(night, hotelZone, { hour: 14 })` = check-in instant;
- * with no `time`, local midnight — the DST-exact "start of that day in that
- * zone".
- *
- * Two-pass offset resolution: the offset is looked up AT the candidate
- * instant, then re-checked, so days where a DST transition sits between the
- * wall time and the first guess still resolve correctly. Honest limit: a
- * wall time that does not exist (inside a spring-forward gap) resolves to
- * the instant the shifted clock reaches — the same choice Temporal's
- * `disambiguation: 'compatible'` makes.
- */
-declare function civilDateToInstant(cd: CivilDate, zone: string, time?: {
-  hour?: number;
-  minute?: number;
-}): Date;
-/**
- * Pure calendar-day arithmetic — `addCivilDays('2026-02-28', 1)` →
- * `'2026-03-01'`. Zone-free by definition (a civil date has no zone);
- * use it to iterate hotel nights / statement days.
- */
-declare function addCivilDays(cd: CivilDate, days: number): CivilDate;
-/**
- * Whole days from `a` to `b` (positive when `b` is later) — the NIGHTS
- * count for a `[checkIn, checkOut)` stay expressed as civil dates.
- */
-declare function civilDaysBetween(a: CivilDate, b: CivilDate): number;
-//#endregion
-export { CivilDate, LocalTimeParts, TimeZoneError, addCivilDays, civilDate, civilDateOf, civilDateToInstant, civilDaysBetween, isCivilDate, isValidTimeZone, listTimeZones, localTimeParts, zoneOffsetLabel, zoneOffsetMinutes };
+import { a as civilDate, c as civilDaysBetween, d as isoWeekOfCivilDate, f as listTimeZones, h as zoneOffsetMinutes, i as addCivilDays, l as isCivilDate, m as zoneOffsetLabel, n as LocalTimeParts, o as civilDateOf, p as localTimeParts, r as TimeZoneError, s as civilDateToInstant, t as CivilDate, u as isValidTimeZone } from "./timezone-tlG7ygwx.mjs";
+export { CivilDate, LocalTimeParts, TimeZoneError, addCivilDays, civilDate, civilDateOf, civilDateToInstant, civilDaysBetween, isCivilDate, isValidTimeZone, isoWeekOfCivilDate, listTimeZones, localTimeParts, zoneOffsetLabel, zoneOffsetMinutes };

package/dist/timezone.mjs

@@ -78,7 +78,19 @@ function listTimeZones() {
 	cachedZones = Object.freeze(intl.supportedValuesOf("timeZone"));
 	return cachedZones;
 }
-const OFFSET_RE = /GMT(?:([+-])(\d{2}):(\d{2}))?/;
+/**
+* ANCHORED on purpose.
+*
+* The unanchored form (`/GMT(?:([+-])(\d{2}):(\d{2}))?/`) made the offset group
+* OPTIONAL *and* skippable: any label the runtime emits that this pattern cannot
+* fully parse — `'GMT+5:30'` from an ICU build that does not zero-pad, or a
+* locale that prefixes text — still matched the bare `GMT` alternative and
+* resolved to offset **0**. A half-read offset became "UTC" with no error, which
+* silently shifts every business-day boundary derived from it. Anchoring makes an
+* unrecognised label throw instead; `\d{1,2}` accepts the unpadded variant rather
+* than mis-reading it.
+*/
+const OFFSET_RE = /^GMT(?:([+-])(\d{1,2}):(\d{2}))?$/;
 /**
 * The zone's UTC offset AT `instant`, in minutes east of UTC — DST-exact.
 * `zoneOffsetMinutes(july, 'Europe/London')` → 60; `(january, …)` → 0;
@@ -204,7 +216,9 @@ function civilDateToInstant(cd, zone, time = {}) {
 	if (!m) throw new TimeZoneError(`Invalid civil date '${cd}'.`);
 	const hour = time.hour ?? 0;
 	const minute = time.minute ?? 0;
-	const wallAsUtc = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]), hour, minute);
+	const second = time.second ?? 0;
+	const millisecond = time.millisecond ?? 0;
+	const wallAsUtc = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]), hour, minute, second, millisecond);
 	const firstOffset = zoneOffsetMinutes(new Date(wallAsUtc), zone);
 	let instantMs = wallAsUtc - firstOffset * MINUTE_MS;
 	const refined = zoneOffsetMinutes(new Date(instantMs), zone);
@@ -226,6 +240,27 @@ function addCivilDays(cd, days) {
 * Whole days from `a` to `b` (positive when `b` is later) — the NIGHTS
 * count for a `[checkIn, checkOut)` stay expressed as civil dates.
 */
+/**
+* The ISO-8601 week a civil date belongs to, as `YYYY-Www`.
+*
+* Zone-free by definition — a civil date has no zone — so callers resolve the
+* date in their business timezone FIRST (`civilDateOf`) and label it here.
+*
+* ISO week 1 is the week containing the first Thursday, which means the week
+* YEAR can differ from the date's own: 2025-12-29 is `2026-W01`. Naive
+* "day-of-year / 7" numbering gets that wrong every few years, silently
+* splitting one business week across two report buckets.
+*/
+function isoWeekOfCivilDate(cd) {
+	const m = CIVIL_RE.exec(cd);
+	if (!m) throw new TimeZoneError(`Invalid civil date '${cd}'.`);
+	const utc = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+	const dow = new Date(utc).getUTCDay() || 7;
+	const thursday = new Date(utc + (4 - dow) * 864e5);
+	const weekYear = thursday.getUTCFullYear();
+	const week = Math.floor((thursday.getTime() - Date.UTC(weekYear, 0, 1)) / 864e5 / 7) + 1;
+	return `${weekYear}-W${String(week).padStart(2, "0")}`;
+}
 function civilDaysBetween(a, b) {
 	const pa = CIVIL_RE.exec(a);
 	const pb = CIVIL_RE.exec(b);
@@ -235,4 +270,4 @@ function civilDaysBetween(a, b) {
 	return Math.round((mb - ma) / 864e5);
 }
 //#endregion
-export { TimeZoneError, addCivilDays, civilDate, civilDateOf, civilDateToInstant, civilDaysBetween, isCivilDate, isValidTimeZone, listTimeZones, localTimeParts, zoneOffsetLabel, zoneOffsetMinutes };
+export { TimeZoneError, addCivilDays, civilDate, civilDateOf, civilDateToInstant, civilDaysBetween, isCivilDate, isValidTimeZone, isoWeekOfCivilDate, listTimeZones, localTimeParts, zoneOffsetLabel, zoneOffsetMinutes };

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

@@ -1,5 +1,4 @@
-import { r as CurrencyCode } from "./currency-BCJnJBlb.mjs";
-import { MinorUnits } from "./money.mjs";
+import { t as MinorUnits, w as CurrencyCode } from "./money-DPo9fLBi.mjs";
 
 //#region src/money/unit-cost-rate.d.ts
 /** Fixed, ecosystem-wide rate scale: 6 decimal places below the minor unit. */