@classytic/primitives 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -3,6 +3,47 @@
 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.9.1] - 2026-07-04
+
+### Added
+
+- **`CURRENCY_PATTERN` exported from `/currency`** — the ISO 4217 regex
+  (`/^[A-Z]{3}$/`) behind `isCurrencyCode` / `toCurrencyCode`. Consumers
+  embed the SAME pattern in JSON-Schema-representable validators (zod
+  `.regex`, Mongoose `match`, OpenAPI `pattern`) instead of hand-rolling
+  copies — `.refine(isCurrencyCode)` validates at runtime but is dropped
+  by `z.toJSONSchema`, silently losing the constraint from generated API
+  docs.
+
+## [0.9.0] - 2026-07-02
+
+### Added — `/timezone`: IANA resolution + civil dates (the door for `/calendar`'s escape hatch)
+
+`/calendar` owns wall-clock ARITHMETIC over a fixed `UtcOffsetMinutes` and
+tells hosts to "resolve the offset for the instant and pass it in" — but the
+stack had no shared resolver, so consumers hand-rolled `Intl.DateTimeFormat`
+(three divergent copies found: catalog ×2, be-prod POS). `/timezone` is that
+resolver — zero-dep (Intl IS the ICU tz database), Temporal-shaped names for
+a future mechanical migration:
+
+- **`zoneOffsetMinutes(instant, zone)`** — per-instant, DST-exact offset;
+  composes directly with `/calendar`: `startOfMonth(i, zoneOffsetMinutes(i, z))`.
+- **`localTimeParts(instant, zone)`** — `{ isoWeekday, hour, minute,
+  minutesOfDay }` in the zone; what pricing windows / slot grids /
+  working-hours checks evaluate against (canonicalizes catalog's resolvers).
+- **`CivilDate`** (branded `'YYYY-MM-DD'`) + `civilDate` / `isCivilDate` /
+  `civilDateOf(instant, zone)` / `civilDateToInstant(cd, zone, time?)`
+  (two-pass DST-safe) / `addCivilDays` / `civilDaysBetween` — the type for
+  hotel nights, POS business dates, VAT filing years. Lexicographic ==
+  chronological, so it's a range-queryable Mongo string key.
+- **`isValidTimeZone(zone)`** — boot-time host-config validation;
+  **`listTimeZones()`** + **`zoneOffsetLabel(instant, zone)`** — the data
+  source + label for Google-Calendar-style zone pickers, straight from ICU
+  (`Intl.supportedValuesOf`), no bundled list to go stale.
+- `TimeZoneError`; formatter instances cached per zone.
+
+No arithmetic here (that stays in `/calendar`) — resolution only.
+
 ## [0.7.2] - 2026-05-30
 
 ### Added — `BankTransaction` per-account routing + pending lifecycle fields

package/dist/calendar.d.mts

@@ -0,0 +1,46 @@
+//#region src/scheduling/calendar.d.ts
+/**
+ * Calendar boundaries + arithmetic — the ONE place the stack computes
+ * "start of day / month", weekday, and month/day/year addition, so no package
+ * hand-rolls it with server-LOCAL `Date` methods (`getFullYear`/`getMonth`/
+ * `getDate`/`getDay`), which silently shift with the deploy machine's `TZ` env.
+ *
+ * Every function is PURE and takes a fixed **UTC offset in minutes** (east of
+ * UTC — `360` = UTC+6 / Asia-Dhaka). Same convention as `cadence` / `sla-policy`:
+ * no IANA tz database, no DST. A fixed offset is exact for zones without DST
+ * (e.g. Bangladesh, India, most of Asia) and is what a "daily limit resets at
+ * local midnight" boundary needs. For DST-correct wall-clock math the host
+ * resolves the offset for the instant and passes it in.
+ *
+ * `Date` instants are UTC epoch and timezone-independent — these helpers only
+ * decide WHERE the day/month boundary falls, never how "now" is recorded.
+ *
+ * Resolving that offset from an IANA zone name is `/timezone`'s job — the
+ * two compose: `startOfMonth(instant, zoneOffsetMinutes(instant, zone))`.
+ * For a DST-exact DAY boundary prefer the civil-date round-trip from
+ * `/timezone`: `civilDateToInstant(civilDateOf(instant, zone), zone)`.
+ */
+/** Minutes east of UTC. `0` = UTC, `360` = UTC+6 (Asia/Dhaka), `-300` = UTC-5. */
+type UtcOffsetMinutes = number;
+/**
+ * The absolute instant of local midnight for the day CONTAINING `instant`, in
+ * the given offset. `startOfDay(2026-07-02T03:00Z, 360)` → `2026-07-01T18:00Z`
+ * (Dhaka midnight). With `offsetMinutes = 0` it's plain UTC midnight.
+ */
+declare function startOfDay(instant: Date, offsetMinutes?: UtcOffsetMinutes): Date;
+/** The absolute instant of the first-of-month midnight, in the given offset. */
+declare function startOfMonth(instant: Date, offsetMinutes?: UtcOffsetMinutes): Date;
+/** ISO weekday (1 = Monday … 7 = Sunday) of `instant` in the given offset. */
+declare function isoWeekday(instant: Date, offsetMinutes?: UtcOffsetMinutes): number;
+/** Add whole days as an exact 24h × n duration (offset-agnostic, no DST skew). */
+declare function addDays(instant: Date, days: number): Date;
+/**
+ * Add calendar months in UTC, clamping the day so month-ends never overflow
+ * (`addMonths(Jan 31, 1)` → Feb 28/29). Use for subscription/access periods
+ * instead of local `setMonth(getMonth() + n)`.
+ */
+declare function addMonths(instant: Date, months: number): Date;
+/** Add calendar years in UTC (clamps Feb 29 → Feb 28 on non-leap years). */
+declare function addYears(instant: Date, years: number): Date;
+//#endregion
+export { UtcOffsetMinutes, addDays, addMonths, addYears, isoWeekday, startOfDay, startOfMonth };

package/dist/calendar.mjs

@@ -0,0 +1,47 @@
+//#region src/scheduling/calendar.ts
+const MINUTE_MS = 6e4;
+const DAY_MS = 864e5;
+/**
+* The absolute instant of local midnight for the day CONTAINING `instant`, in
+* the given offset. `startOfDay(2026-07-02T03:00Z, 360)` → `2026-07-01T18:00Z`
+* (Dhaka midnight). With `offsetMinutes = 0` it's plain UTC midnight.
+*/
+function startOfDay(instant, offsetMinutes = 0) {
+	const shifted = new Date(instant.getTime() + offsetMinutes * MINUTE_MS);
+	const localMidnightAsUtc = Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth(), shifted.getUTCDate());
+	return new Date(localMidnightAsUtc - offsetMinutes * MINUTE_MS);
+}
+/** The absolute instant of the first-of-month midnight, in the given offset. */
+function startOfMonth(instant, offsetMinutes = 0) {
+	const shifted = new Date(instant.getTime() + offsetMinutes * MINUTE_MS);
+	const localFirstAsUtc = Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth(), 1);
+	return new Date(localFirstAsUtc - offsetMinutes * MINUTE_MS);
+}
+/** ISO weekday (1 = Monday … 7 = Sunday) of `instant` in the given offset. */
+function isoWeekday(instant, offsetMinutes = 0) {
+	return (new Date(instant.getTime() + offsetMinutes * MINUTE_MS).getUTCDay() + 6) % 7 + 1;
+}
+/** Add whole days as an exact 24h × n duration (offset-agnostic, no DST skew). */
+function addDays(instant, days) {
+	return new Date(instant.getTime() + days * DAY_MS);
+}
+/**
+* Add calendar months in UTC, clamping the day so month-ends never overflow
+* (`addMonths(Jan 31, 1)` → Feb 28/29). Use for subscription/access periods
+* instead of local `setMonth(getMonth() + n)`.
+*/
+function addMonths(instant, months) {
+	const d = new Date(instant.getTime());
+	const day = d.getUTCDate();
+	d.setUTCDate(1);
+	d.setUTCMonth(d.getUTCMonth() + months);
+	const daysInTarget = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate();
+	d.setUTCDate(Math.min(day, daysInTarget));
+	return d;
+}
+/** Add calendar years in UTC (clamps Feb 29 → Feb 28 on non-leap years). */
+function addYears(instant, years) {
+	return addMonths(instant, years * 12);
+}
+//#endregion
+export { addDays, addMonths, addYears, isoWeekday, startOfDay, startOfMonth };

package/dist/{currency-B4rSdN7D.d.mts → currency-BCJnJBlb.d.mts}

@@ -43,6 +43,15 @@ declare const CURRENCIES: {
  * isn't in this table, {@link minorUnitFactor} returns 100 as the safe default.
  */
 declare const MINOR_UNIT_FACTOR: Readonly<Record<string, number>>;
+/**
+ * ISO 4217 format — 3 uppercase letters. Exported so consumers can embed
+ * the SAME pattern in JSON-Schema-representable validators (zod `.regex`,
+ * Mongoose `match`, OpenAPI `pattern`) instead of hand-rolling a copy:
+ * `.refine(isCurrencyCode)` validates at runtime but is dropped by
+ * `z.toJSONSchema`, losing the constraint from generated API docs.
+ * `isCurrencyCode` / `toCurrencyCode` remain the runtime API.
+ */
+declare const CURRENCY_PATTERN: RegExp;
 /**
  * Narrow a raw string to a {@link CurrencyCode}. Returns `null` if the string
  * is not a valid ISO 4217 format (3 uppercase letters). This does not verify
@@ -107,4 +116,4 @@ declare function reverseWithSnapshot(baseAmount: number, fx: FxSnapshot): number
  */
 declare function isFxSnapshot(value: unknown): value is FxSnapshot;
 //#endregion
-export { convertWithSnapshot as a, minorUnitFactor as c, MINOR_UNIT_FACTOR as i, reverseWithSnapshot as l, CurrencyCode as n, isCurrencyCode as o, FxSnapshot as r, isFxSnapshot as s, CURRENCIES as t, toCurrencyCode as u };
+export { MINOR_UNIT_FACTOR as a, isFxSnapshot as c, toCurrencyCode as d, FxSnapshot as i, minorUnitFactor as l, CURRENCY_PATTERN as n, convertWithSnapshot as o, CurrencyCode as r, isCurrencyCode as s, CURRENCIES as t, reverseWithSnapshot as u };

package/dist/currency.d.mts

@@ -1,2 +1,2 @@
-import { a as convertWithSnapshot, c as minorUnitFactor, i as MINOR_UNIT_FACTOR, l as reverseWithSnapshot, n as CurrencyCode, o as isCurrencyCode, r as FxSnapshot, s as isFxSnapshot, t as CURRENCIES, u as toCurrencyCode } from "./currency-B4rSdN7D.mjs";
-export { CURRENCIES, CurrencyCode, FxSnapshot, MINOR_UNIT_FACTOR, convertWithSnapshot, isCurrencyCode, isFxSnapshot, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };
+import { a as MINOR_UNIT_FACTOR, c as isFxSnapshot, d as toCurrencyCode, i as FxSnapshot, l as minorUnitFactor, n as CURRENCY_PATTERN, o as convertWithSnapshot, r as CurrencyCode, s as isCurrencyCode, t as CURRENCIES, u as reverseWithSnapshot } from "./currency-BCJnJBlb.mjs";
+export { CURRENCIES, CURRENCY_PATTERN, CurrencyCode, FxSnapshot, MINOR_UNIT_FACTOR, convertWithSnapshot, isCurrencyCode, isFxSnapshot, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };

package/dist/currency.mjs

@@ -61,6 +61,14 @@ const MINOR_UNIT_FACTOR = {
 	OMR: 1e3,
 	TND: 1e3
 };
+/**
+* ISO 4217 format — 3 uppercase letters. Exported so consumers can embed
+* the SAME pattern in JSON-Schema-representable validators (zod `.regex`,
+* Mongoose `match`, OpenAPI `pattern`) instead of hand-rolling a copy:
+* `.refine(isCurrencyCode)` validates at runtime but is dropped by
+* `z.toJSONSchema`, losing the constraint from generated API docs.
+* `isCurrencyCode` / `toCurrencyCode` remain the runtime API.
+*/
 const CURRENCY_PATTERN = /^[A-Z]{3}$/;
 /**
 * Narrow a raw string to a {@link CurrencyCode}. Returns `null` if the string
@@ -113,4 +121,4 @@ function isFxSnapshot(value) {
 	return typeof v.sourceCurrency === "string" && typeof v.baseCurrency === "string" && typeof v.rate === "number" && Number.isFinite(v.rate) && v.rate > 0 && v.snapshotAt instanceof Date;
 }
 //#endregion
-export { CURRENCIES, MINOR_UNIT_FACTOR, convertWithSnapshot, isCurrencyCode, isFxSnapshot, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };
+export { CURRENCIES, CURRENCY_PATTERN, MINOR_UNIT_FACTOR, convertWithSnapshot, isCurrencyCode, isFxSnapshot, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };

package/dist/money.d.mts

@@ -1,4 +1,4 @@
-import { n as CurrencyCode } from "./currency-B4rSdN7D.mjs";
+import { r as CurrencyCode } from "./currency-BCJnJBlb.mjs";
 
 //#region src/money/money.d.ts
 /**

package/dist/timezone.d.mts

@@ -0,0 +1,100 @@
+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 };

package/dist/timezone.mjs

@@ -0,0 +1,238 @@
+//#region src/scheduling/timezone.ts
+const MINUTE_MS = 6e4;
+var TimeZoneError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "TimeZoneError";
+	}
+};
+const offsetFormatters = /* @__PURE__ */ new Map();
+const partsFormatters = /* @__PURE__ */ new Map();
+const civilFormatters = /* @__PURE__ */ new Map();
+function offsetFormatter(zone) {
+	let fmt = offsetFormatters.get(zone);
+	if (!fmt) {
+		fmt = new Intl.DateTimeFormat("en-US", {
+			timeZone: zone,
+			timeZoneName: "longOffset"
+		});
+		offsetFormatters.set(zone, fmt);
+	}
+	return fmt;
+}
+function partsFormatter(zone) {
+	let fmt = partsFormatters.get(zone);
+	if (!fmt) {
+		fmt = new Intl.DateTimeFormat("en-US", {
+			timeZone: zone,
+			weekday: "short",
+			hour: "2-digit",
+			minute: "2-digit",
+			hour12: false
+		});
+		partsFormatters.set(zone, fmt);
+	}
+	return fmt;
+}
+function civilFormatter(zone) {
+	let fmt = civilFormatters.get(zone);
+	if (!fmt) {
+		fmt = new Intl.DateTimeFormat("en-CA", {
+			timeZone: zone,
+			year: "numeric",
+			month: "2-digit",
+			day: "2-digit"
+		});
+		civilFormatters.set(zone, fmt);
+	}
+	return fmt;
+}
+/**
+* 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.
+*/
+function isValidTimeZone(zone) {
+	if (typeof zone !== "string" || zone.length === 0) return false;
+	try {
+		offsetFormatter(zone);
+		return true;
+	} catch {
+		offsetFormatters.delete(zone);
+		return false;
+	}
+}
+let cachedZones;
+/**
+* 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) }))`.
+*/
+function listTimeZones() {
+	if (cachedZones) return cachedZones;
+	const intl = Intl;
+	if (typeof intl.supportedValuesOf !== "function") throw new TimeZoneError("Intl.supportedValuesOf is unavailable on this runtime (requires Node >= 18 / a modern browser). Upgrade the runtime or supply a static zone list.");
+	cachedZones = Object.freeze(intl.supportedValuesOf("timeZone"));
+	return cachedZones;
+}
+const OFFSET_RE = /GMT(?:([+-])(\d{2}):(\d{2}))?/;
+/**
+* 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))`.
+*/
+function zoneOffsetMinutes(instant, zone) {
+	const label = zoneOffsetLabel(instant, zone);
+	const m = OFFSET_RE.exec(label);
+	if (!m) throw new TimeZoneError(`Unparseable offset '${label}' for zone '${zone}'.`);
+	if (m[1] === void 0) return 0;
+	return (m[1] === "-" ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3]));
+}
+/**
+* The zone's offset label AT `instant` — `'GMT+06:00'` / `'GMT-05:30'` /
+* `'GMT'`. Ready-made display text for zone pickers.
+*/
+function zoneOffsetLabel(instant, zone) {
+	let fmt;
+	try {
+		fmt = offsetFormatter(zone);
+	} catch {
+		offsetFormatters.delete(zone);
+		throw new TimeZoneError(`Invalid IANA timezone: '${zone}'.`);
+	}
+	const part = fmt.formatToParts(instant).find((p) => p.type === "timeZoneName");
+	if (!part) throw new TimeZoneError(`Runtime produced no offset part for zone '${zone}'.`);
+	return part.value;
+}
+const WEEKDAY_TO_ISO = {
+	Mon: 1,
+	Tue: 2,
+	Wed: 3,
+	Thu: 4,
+	Fri: 5,
+	Sat: 6,
+	Sun: 7
+};
+/**
+* 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.
+*/
+function localTimeParts(instant, zone) {
+	let fmt;
+	try {
+		fmt = partsFormatter(zone);
+	} catch {
+		partsFormatters.delete(zone);
+		throw new TimeZoneError(`Invalid IANA timezone: '${zone}'.`);
+	}
+	let weekday;
+	let hour;
+	let minute;
+	for (const part of fmt.formatToParts(instant)) if (part.type === "weekday") weekday = part.value;
+	else if (part.type === "hour") hour = Number(part.value);
+	else if (part.type === "minute") minute = Number(part.value);
+	const isoWeekday = weekday !== void 0 ? WEEKDAY_TO_ISO[weekday] : void 0;
+	if (isoWeekday === void 0 || hour === void 0 || minute === void 0) throw new TimeZoneError(`Runtime produced incomplete wall parts for zone '${zone}'.`);
+	const h = hour === 24 ? 0 : hour;
+	return {
+		isoWeekday,
+		hour: h,
+		minute,
+		minutesOfDay: h * 60 + minute
+	};
+}
+const CIVIL_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+/** Runtime guard for external input. */
+function isCivilDate(value) {
+	if (typeof value !== "string") return false;
+	const m = CIVIL_RE.exec(value);
+	if (!m) return false;
+	const y = Number(m[1]);
+	const mo = Number(m[2]);
+	const d = Number(m[3]);
+	if (mo < 1 || mo > 12 || d < 1) return false;
+	return d <= new Date(Date.UTC(y, mo, 0)).getUTCDate();
+}
+/** Validate + brand a `'YYYY-MM-DD'` string. Throws on malformed input. */
+function civilDate(value) {
+	if (!isCivilDate(value)) throw new TimeZoneError(`Invalid civil date '${value}' — expected 'YYYY-MM-DD'.`);
+	return value;
+}
+/**
+* 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.
+*/
+function civilDateOf(instant, zone) {
+	let fmt;
+	try {
+		fmt = civilFormatter(zone);
+	} catch {
+		civilFormatters.delete(zone);
+		throw new TimeZoneError(`Invalid IANA timezone: '${zone}'.`);
+	}
+	let y = "";
+	let m = "";
+	let d = "";
+	for (const part of fmt.formatToParts(instant)) if (part.type === "year") y = part.value;
+	else if (part.type === "month") m = part.value;
+	else if (part.type === "day") d = part.value;
+	return civilDate(`${y.padStart(4, "0")}-${m}-${d}`);
+}
+/**
+* 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.
+*/
+function civilDateToInstant(cd, zone, time = {}) {
+	const m = CIVIL_RE.exec(cd);
+	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 firstOffset = zoneOffsetMinutes(new Date(wallAsUtc), zone);
+	let instantMs = wallAsUtc - firstOffset * MINUTE_MS;
+	const refined = zoneOffsetMinutes(new Date(instantMs), zone);
+	if (refined !== firstOffset) instantMs = wallAsUtc - refined * MINUTE_MS;
+	return new Date(instantMs);
+}
+/**
+* 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.
+*/
+function addCivilDays(cd, days) {
+	const m = CIVIL_RE.exec(cd);
+	if (!m) throw new TimeZoneError(`Invalid civil date '${cd}'.`);
+	const d = new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]) + days));
+	return civilDate(`${String(d.getUTCFullYear()).padStart(4, "0")}-${String(d.getUTCMonth() + 1).padStart(2, "0")}-${String(d.getUTCDate()).padStart(2, "0")}`);
+}
+/**
+* Whole days from `a` to `b` (positive when `b` is later) — the NIGHTS
+* count for a `[checkIn, checkOut)` stay expressed as civil dates.
+*/
+function civilDaysBetween(a, b) {
+	const pa = CIVIL_RE.exec(a);
+	const pb = CIVIL_RE.exec(b);
+	if (!pa || !pb) throw new TimeZoneError(`Invalid civil date '${!pa ? a : b}'.`);
+	const ma = Date.UTC(Number(pa[1]), Number(pa[2]) - 1, Number(pa[3]));
+	const mb = Date.UTC(Number(pb[1]), Number(pb[2]) - 1, Number(pb[3]));
+	return Math.round((mb - ma) / 864e5);
+}
+//#endregion
+export { TimeZoneError, addCivilDays, civilDate, civilDateOf, civilDateToInstant, civilDaysBetween, isCivilDate, isValidTimeZone, listTimeZones, localTimeParts, zoneOffsetLabel, zoneOffsetMinutes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -37,6 +37,14 @@
       "types": "./dist/period.d.mts",
       "default": "./dist/period.mjs"
     },
+    "./calendar": {
+      "types": "./dist/calendar.d.mts",
+      "default": "./dist/calendar.mjs"
+    },
+    "./timezone": {
+      "types": "./dist/timezone.d.mts",
+      "default": "./dist/timezone.mjs"
+    },
     "./reference": {
       "types": "./dist/reference.d.mts",
       "default": "./dist/reference.mjs"