@classytic/primitives 0.20.0 → 0.22.0

package/dist/period.d.mts

@@ -1,5 +1,4 @@
-import { t as CivilDate } from "./timezone-tlG7ygwx.mjs";
-
+import { t as CivilDate } from "./timezone-CxUjxmRU.mjs";
 //#region src/scheduling/period.d.ts
 /**
  * A date range `[start, end]`.
@@ -55,7 +54,19 @@ type PeriodGranularity = 'year' | 'quarter' | 'month' | 'custom';
 declare class DateRangeError extends Error {
   readonly name = "DateRangeError";
 }
-type PeriodErrorCode = /** Two resolution shapes at once (`month` + `quarter`, or either + `start`/`end`). */'AMBIGUOUS_PERIOD' /** `start` without `end`, or vice versa. */ | 'INCOMPLETE_RANGE' /** `year` / `month` / `quarter` outside its legal domain, or non-integer. */ | 'INVALID_FIELD' /** No zone on the period and none supplied by the caller. */ | 'MISSING_TIMEZONE' /** The period's own zone and the caller's zone disagree. */ | 'TIMEZONE_CONFLICT' /** A `'YYYY'` / `'YYYY-MM'` / `'YYYY-Qn'` label that could not be read. */ | 'INVALID_LABEL';
+type PeriodErrorCode =
+/** Two resolution shapes at once (`month` + `quarter`, or either + `start`/`end`). */
+'AMBIGUOUS_PERIOD' |
+/** `start` without `end`, or vice versa. */
+'INCOMPLETE_RANGE' |
+/** `year` / `month` / `quarter` outside its legal domain, or non-integer. */
+'INVALID_FIELD' |
+/** No zone on the period and none supplied by the caller. */
+'MISSING_TIMEZONE' |
+/** The period's own zone and the caller's zone disagree. */
+'TIMEZONE_CONFLICT' |
+/** A `'YYYY'` / `'YYYY-MM'` / `'YYYY-Qn'` label that could not be read. */
+'INVALID_LABEL';
 declare class PeriodError extends Error {
   readonly name = "PeriodError";
   readonly code: PeriodErrorCode;
@@ -149,6 +160,30 @@ declare function resolvePeriod(period: Period, timezone?: string): DateRange;
  * For the `$lte` call sites that predate half-open ranges. Derived from the
  * resolved end rather than `start + 24h - 1`, so it stays DST-exact.
  */
+/**
+ * Shift a MONTH or QUARTER period by `n` of its own units (negative = back).
+ *
+ * The arithmetic a caller would otherwise write inline, and the reason this is
+ * here rather than in each of them: "two filing months ago" is a `Period`
+ * question, and the shapes reachable without it are both wrong in the same way.
+ *
+ *   `new Date(Date.UTC(y, m - 1 - n, 1))` — a UTC instant used to answer a
+ *   BUSINESS-calendar question. Six hours off in Asia/Dhaka at both ends; the
+ *   five silent defects in this module's header are all that shape.
+ *
+ *   hand-rolled integer math (`y * 12 + (m - 1) - n`) — correct, but it is a
+ *   third copy of a rule the `Period` type already owns, and the year rollover
+ *   is exactly where a copy goes wrong.
+ *
+ * NO Date is constructed and no zone is consulted: shifting a month is pure
+ * calendar arithmetic on `(year, month)`. The `timezone` rides along unchanged,
+ * so the shifted period still resolves against the calendar it was defined in —
+ * `resolvePeriod` / {@link resolveMonth} remain the only places instants appear.
+ *
+ * A YEAR period shifts by years; a `custom` (ad-hoc start/end) period has no
+ * unit to shift and throws rather than guessing one.
+ */
+declare function shiftPeriod(period: Period, n: number): Period;
 declare function inclusiveEnd(range: DateRange): Date;
 /**
  * The period an INSTANT falls in, on the local calendar.
@@ -174,4 +209,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 };
+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 };

package/dist/period.mjs

@@ -261,6 +261,55 @@ function resolvePeriod(period, timezone) {
 * For the `$lte` call sites that predate half-open ranges. Derived from the
 * resolved end rather than `start + 24h - 1`, so it stays DST-exact.
 */
+/**
+* Shift a MONTH or QUARTER period by `n` of its own units (negative = back).
+*
+* The arithmetic a caller would otherwise write inline, and the reason this is
+* here rather than in each of them: "two filing months ago" is a `Period`
+* question, and the shapes reachable without it are both wrong in the same way.
+*
+*   `new Date(Date.UTC(y, m - 1 - n, 1))` — a UTC instant used to answer a
+*   BUSINESS-calendar question. Six hours off in Asia/Dhaka at both ends; the
+*   five silent defects in this module's header are all that shape.
+*
+*   hand-rolled integer math (`y * 12 + (m - 1) - n`) — correct, but it is a
+*   third copy of a rule the `Period` type already owns, and the year rollover
+*   is exactly where a copy goes wrong.
+*
+* NO Date is constructed and no zone is consulted: shifting a month is pure
+* calendar arithmetic on `(year, month)`. The `timezone` rides along unchanged,
+* so the shifted period still resolves against the calendar it was defined in —
+* `resolvePeriod` / {@link resolveMonth} remain the only places instants appear.
+*
+* A YEAR period shifts by years; a `custom` (ad-hoc start/end) period has no
+* unit to shift and throws rather than guessing one.
+*/
+function shiftPeriod(period, n) {
+	if (!Number.isInteger(n)) throw new PeriodError("INVALID_FIELD", `shiftPeriod expects an integer offset, received ${String(n)}.`);
+	const granularity = granularityOf(period);
+	const zone = period.timezone !== void 0 ? { timezone: period.timezone } : {};
+	if (granularity === "month") {
+		const zeroBased = period.year * 12 + (period.month - 1) + n;
+		return {
+			year: Math.floor(zeroBased / 12),
+			month: zeroBased % 12 + 1,
+			...zone
+		};
+	}
+	if (granularity === "quarter") {
+		const zeroBased = period.year * 4 + (period.quarter - 1) + n;
+		return {
+			year: Math.floor(zeroBased / 4),
+			quarter: zeroBased % 4 + 1,
+			...zone
+		};
+	}
+	if (granularity === "year") return {
+		year: period.year + n,
+		...zone
+	};
+	throw new PeriodError("AMBIGUOUS_PERIOD", "shiftPeriod has no unit to shift for an ad-hoc start/end period — shift the instants, or use a calendar period.");
+}
 function inclusiveEnd(range) {
 	assertUsableRange(range, "range");
 	return /* @__PURE__ */ new Date(range.end.getTime() - 1);
@@ -339,4 +388,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 };
+export { DateRangeError, PeriodError, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };

package/dist/person-parse.d.mts

@@ -1,5 +1,4 @@
 import { PersonName } from "./person.mjs";
-
 //#region src/identity/person-parse.d.ts
 /**
  * Does this `PersonName` carry at least one usable, non-empty name part?

package/dist/phone.d.mts

@@ -1,5 +1,4 @@
 import { Result } from "./result.mjs";
-
 //#region src/identity/phone.d.ts
 type PhoneErrorCode = 'EMPTY' | 'MISSING_PLUS' | 'NOT_E164' | 'TOO_SHORT' | 'TOO_LONG';
 declare class PhoneError extends Error {

package/dist/phone.mjs

@@ -42,7 +42,7 @@ var PhoneError = class extends Error {
 * Kept inline (not exported) because it's an implementation detail of the
 * parser. Length is the only thing we actually need for the split.
 */
-const E164_PREFIXES_3 = new Set([
+const E164_PREFIXES_3 = /* @__PURE__ */ new Set([
 	"210",
 	"211",
 	"212",
@@ -215,7 +215,7 @@ const E164_PREFIXES_3 = new Set([
 	"996",
 	"998"
 ]);
-const E164_PREFIXES_2 = new Set([
+const E164_PREFIXES_2 = /* @__PURE__ */ new Set([
 	"20",
 	"27",
 	"30",
@@ -261,7 +261,7 @@ const E164_PREFIXES_2 = new Set([
 	"95",
 	"98"
 ]);
-const E164_PREFIXES_1 = new Set(["1", "7"]);
+const E164_PREFIXES_1 = /* @__PURE__ */ new Set(["1", "7"]);
 /**
 * Parse free-form phone input into a normalized `PhoneNumber`. Accepts:
 *   - `'+14155550182'`           → e164 unchanged

package/dist/proration.d.mts

@@ -1,5 +1,4 @@
-import { n as Money } from "./money-DPo9fLBi.mjs";
-
+import { n as Money } from "./money-CfAvfNiM.mjs";
 //#region src/money/proration.d.ts
 /**
  * How to count days within a period.

package/dist/retention.mjs

@@ -1,15 +1,15 @@
 //#region src/retention/purge-evidence.ts
-const STRATEGY_KINDS = new Set([
+const STRATEGY_KINDS = /* @__PURE__ */ new Set([
 	"hard",
 	"soft",
 	"anonymize"
 ]);
-const ACTOR_KINDS = new Set([
+const ACTOR_KINDS = /* @__PURE__ */ new Set([
 	"user",
 	"system",
 	"service"
 ]);
-const STATUS_KINDS = new Set([
+const STATUS_KINDS = /* @__PURE__ */ new Set([
 	"completed",
 	"partial",
 	"failed"

package/dist/shelf-life.mjs

@@ -43,7 +43,7 @@ var ShelfLifeError = class extends Error {
 		this.code = code;
 	}
 };
-const DAY_MS = 1440 * 60 * 1e3;
+const DAY_MS = 864e5;
 const TRACKING_MODES = [
 	"none",
 	"lot",

package/dist/sla-policy.d.mts

@@ -1,6 +1,5 @@
-import { s as IsoWeekday } from "./cadence-BFQVC1Qp.mjs";
+import { s as IsoWeekday } from "./cadence-5X6TiD49.mjs";
 import { SLA } from "./sla.mjs";
-
 //#region src/scheduling/sla-policy.d.ts
 /**
  * Tier of severity. Hosts decide the keys ('urgent' / 'p0' / 'gold' / etc.) —

package/dist/state-diagram.d.mts

@@ -1,5 +1,4 @@
 import { StateMachine } from "./state-machine.mjs";
-
 //#region src/workflow/state-diagram.d.ts
 interface StateDiagramOptions<TStatus extends string> {
   /**

package/dist/state-diagram.mjs

@@ -54,7 +54,7 @@ function describeStateMachine(machine) {
 * that can never leave the state it is stuck in.
 */
 function unreachableStates(machine, initial) {
-	const seen = new Set([initial]);
+	const seen = /* @__PURE__ */ new Set([initial]);
 	const queue = [initial];
 	while (queue.length > 0) for (const next of machine.validTargets(queue.pop())) if (!seen.has(next)) {
 		seen.add(next);

package/dist/suspension.d.mts

@@ -1,7 +1,6 @@
-import { t as UtcOffsetMinutes } from "./calendar-B6fm-FbR.mjs";
+import { t as UtcOffsetMinutes } from "./calendar-DJWSbcgE.mjs";
 import { DateRange } from "./period.mjs";
 import { StatusChangeEntry } from "./status-history.mjs";
-
 //#region src/workflow/suspension.d.ts
 /**
  * One suspension, past or current.
@@ -84,7 +83,9 @@ declare function allowancePeriod(at: Date, periodMonths?: number, offsetMinutes?
  * December. Ignoring that double-counts a straddling pause in both periods and
  * refuses a member who is within their allowance.
  */
-declare function suspendedDaysInPeriod(history: readonly SuspensionSpan[], period: DateRange, /** Now — bounds still-open spans. Defaults to the period end. */at?: Date): number;
+declare function suspendedDaysInPeriod(history: readonly SuspensionSpan[], period: DateRange,
+/** Now — bounds still-open spans. Defaults to the period end. */
+at?: Date): number;
 /** Is any span still open at `at`? */
 declare function openSpans(history: readonly SuspensionSpan[], at: Date): readonly SuspensionSpan[];
 /**
@@ -144,7 +145,8 @@ declare function spansFromStatusHistory<TStatus extends string>(history: readonl
    * resume yet (a crash between the write and the append). Leaving it open would
    * charge the member allowance for time they were not frozen.
    */
-  readonly currentStatus?: TStatus | undefined; /** Closes a genuinely-open trailing span for counting. Defaults to open. */
+  readonly currentStatus?: TStatus | undefined;
+  /** Closes a genuinely-open trailing span for counting. Defaults to open. */
   readonly openEndedAt?: Date | undefined;
 }): SuspensionSpan[];
 //#endregion

package/dist/suspension.mjs

@@ -39,11 +39,12 @@ import { addMonths, startOfDay } from "./calendar.mjs";
 * PURE: no clock reads beyond the `at` you pass, no I/O. The same evaluation runs
 * on the server, in an admin preview, and in a test.
 */
-const MS_PER_DAY = 1440 * 60 * 1e3;
+const MS_PER_DAY = 864e5;
 /** The allowance period containing `at`, as a half-open range. */
 function allowancePeriod(at, periodMonths = 12, offsetMinutes = 0) {
+	const anchor = startOfDay(at, offsetMinutes);
 	return {
-		start: addMonths(startOfDay(at, offsetMinutes), -periodMonths),
+		start: addMonths(anchor, -periodMonths),
 		end: at
 	};
 }

package/dist/{timezone-tlG7ygwx.d.mts → timezone-CxUjxmRU.d.mts}

@@ -1,7 +1,6 @@
-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";
-
+import { t as Brand } from "./brand-Lj_75Y_r.mjs";
+import { s as IsoWeekday } from "./cadence-5X6TiD49.mjs";
+import { t as UtcOffsetMinutes } from "./calendar-DJWSbcgE.mjs";
 //#region src/scheduling/timezone.d.ts
 declare class TimeZoneError extends Error {
   constructor(message: string);

package/dist/timezone.d.mts

@@ -1,2 +1,2 @@
-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";
+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-CxUjxmRU.mjs";
 export { CivilDate, LocalTimeParts, 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 { t as MinorUnits, w as CurrencyCode } from "./money-DPo9fLBi.mjs";
-
+import { t as MinorUnits, w as CurrencyCode } from "./money-CfAvfNiM.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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -57,6 +57,10 @@
       "types": "./dist/context.d.mts",
       "default": "./dist/context.mjs"
     },
+    "./environment": {
+      "types": "./dist/environment.d.mts",
+      "default": "./dist/environment.mjs"
+    },
     "./events": {
       "types": "./dist/events.d.mts",
       "default": "./dist/events.mjs"
@@ -225,7 +229,8 @@
     "@biomejs/biome": "^2.4.9",
     "@classytic/dev-tools": "^0.2.0",
     "@types/node": "^25.5.0",
-    "tsdown": "^0.21.7",
+    "publint": "^0.3.23",
+    "tsdown": "^0.22.14",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },