@heavybit/shared-lib 2.1.0 → 2.7.0

package/dist/types/common/internal-service-auth.d.ts

@@ -0,0 +1,102 @@
+/** Header carrying the calling service's name. */
+export declare const INTERNAL_SERVICE_NAME_HEADER: "x-internal-service-name";
+/** Header carrying the calling service's own secret. */
+export declare const INTERNAL_SERVICE_SECRET_HEADER: "x-internal-service-secret";
+export { MIN_INTERNAL_CREDENTIAL_LENGTH, SERVICE_NAME_PATTERN } from './internal-constants.js';
+/** The credential a service sends when it calls another service. */
+export interface InternalCallerCredential {
+    /** This service's own name (`INTERNAL_SERVICE_NAME`). */
+    name: string;
+    /** This service's own secret (`INTERNAL_SERVICE_CREDENTIAL`). */
+    secret: string;
+}
+/** Internal-auth settings read from the environment. */
+export interface InternalServiceAuthConfig {
+    /** Own name, or `''` when unset. */
+    name: string;
+    /** Own secret, or `''` when unset. */
+    credential: string;
+    /** Caller name → secret accepted from it (empty when unset). */
+    credentials: Readonly<Record<string, string>>;
+}
+/** process.env or a parsed config object; only string values are read. */
+type Env = Readonly<Record<string, unknown>>;
+/**
+ * Parses `INTERNAL_SERVICE_CREDENTIALS` (a JSON object of caller name → secret).
+ *
+ * @param raw The env value; empty or undefined gives `{}`.
+ * @returns A frozen map of caller name → secret.
+ * @throws ConfigError when the JSON is malformed, not an object, a name is not a valid service name, or a
+ *   secret is not a non-empty string. The message names the bad key, never a secret.
+ * @example parseInternalServiceCredentials('{"alpha-service":"<secret>"}') // { 'alpha-service': '<secret>' }
+ */
+export declare function parseInternalServiceCredentials(raw: string | undefined): Readonly<Record<string, string>>;
+/**
+ * Reads `INTERNAL_SERVICE_NAME`, `INTERNAL_SERVICE_CREDENTIAL` and `INTERNAL_SERVICE_CREDENTIALS`.
+ *
+ * @param env process.env (default) or a parsed config object.
+ * @returns The settings; missing values are empty.
+ * @throws ConfigError when `INTERNAL_SERVICE_CREDENTIALS` is malformed.
+ * @example const internalAuth = internalServiceAuthConfigFromEnv();
+ */
+export declare function internalServiceAuthConfigFromEnv(env?: Env): InternalServiceAuthConfig;
+/**
+ * The headers a service adds to every internal call it makes.
+ *
+ * @param caller This service's name and secret.
+ * @returns `{ 'x-internal-service-name', 'x-internal-service-secret' }`.
+ * @example fetch(url, { headers: { ...internalServiceHeaders({ name, secret }) } });
+ */
+export declare function internalServiceHeaders(caller: InternalCallerCredential): Record<string, string>;
+/** What a service does with internal routes, for {@link assertInternalServiceAuthConfigured}. */
+export interface InternalServiceAuthReadiness {
+    /** The service calls other services' internal routes (needs its own name and credential). */
+    calls?: boolean;
+    /** The service exposes internal routes (needs the map of accepted callers). */
+    serves?: boolean;
+    /** Defaults to env `NODE_ENV`. */
+    nodeEnv?: string;
+    /** Defaults to process.env. */
+    env?: Env;
+}
+/**
+ * Startup guard. In staging and production it refuses to start when a calling service lacks a valid name or a
+ * credential of at least 32 characters, or when a serving service has no accepted callers or any accepted
+ * secret shorter than 32 characters. In other environments it only checks that what is set parses.
+ *
+ * @param options Whether the service calls and/or serves internal routes.
+ * @throws ConfigError listing every problem (names only, never secret values).
+ * @example assertInternalServiceAuthConfigured({ calls: true, serves: true });
+ */
+export declare function assertInternalServiceAuthConfigured(options: InternalServiceAuthReadiness): void;
+/** Outcome of {@link verifyInternalCaller}. */
+export type InternalCallerVerdict = {
+    ok: true;
+    caller: string;
+} | {
+    ok: false;
+    status: 401;
+    reason: 'missing-credentials' | 'invalid-credentials';
+    caller?: string;
+} | {
+    ok: false;
+    status: 403;
+    reason: 'caller-not-allowed';
+    caller: string;
+};
+type HeaderBag = Readonly<Record<string, string | string[] | undefined>>;
+/**
+ * Checks the internal headers against the accepted credentials and the route's caller list.
+ * 401 when the name or secret is missing, the name is unknown or the secret is wrong; 403 when a correctly
+ * authenticated caller is not in `allowed`.
+ *
+ * @param input Request headers, accepted credentials and the route's allowed callers.
+ * @returns A verdict; the caller name is included when one was sent (safe to log), the secret never is.
+ * @example verifyInternalCaller({ headers: req.headers, credentials, allowed: ['alpha-service'] });
+ */
+export declare function verifyInternalCaller(input: {
+    headers: HeaderBag;
+    credentials: Readonly<Record<string, string>>;
+    allowed: readonly string[];
+}): InternalCallerVerdict;
+//# sourceMappingURL=internal-service-auth.d.ts.map

package/dist/types/common/internal-service-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-service-auth.d.ts","sourceRoot":"","sources":["../../../src/common/internal-service-auth.ts"],"names":[],"mappings":"AAoBA,kDAAkD;AAClD,eAAO,MAAM,4BAA4B,2BAAwC,CAAC;AAClF,wDAAwD;AACxD,eAAO,MAAM,8BAA8B,6BAAkC,CAAC;AAC9E,OAAO,EAAE,8BAA8B,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAK/F,oEAAoE;AACpE,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wDAAwD;AACxD,MAAM,WAAW,yBAAyB;IACxC,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC/C;AAED,0EAA0E;AAC1E,KAAK,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAO7C;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAkBzG;AAED;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,CAAC,GAAG,GAAE,GAAiB,GAAG,yBAAyB,CAMlG;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE/F;AAED,iGAAiG;AACjG,MAAM,WAAW,4BAA4B;IAC3C,6FAA6F;IAC7F,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AAED;;;;;;;;GAQG;AACH,wBAAgB,mCAAmC,CAAC,OAAO,EAAE,4BAA4B,GAAG,IAAI,CAmB/F;AAMD,+CAA+C;AAC/C,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,qBAAqB,GAAG,qBAAqB,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAClG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7E,KAAK,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC;AAOzE;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,OAAO,EAAE,SAAS,CAAC;IACnB,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9C,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GAAG,qBAAqB,CASxB"}

package/dist/types/common/money.d.ts

@@ -0,0 +1,104 @@
+/** A currency: its ISO 4217 code and how many decimal places its minor unit has. */
+export interface CurrencySpec {
+    /** ISO 4217 code, e.g. `USD`. */
+    readonly code: string;
+    /** Decimal places of the minor unit (2 for cents, 3 for fils, 0 for yen). */
+    readonly minorUnits: number;
+}
+/** A currency code (minor units read from the runtime's ISO 4217 data) or an explicit spec. */
+export type CurrencyInput = string | CurrencySpec;
+/** A rate or ratio: a decimal string (`"0.16"`) or a finite number (converted through its shortest decimal form). */
+export type DecimalInput = string | number;
+/**
+ * Resolves a currency code or spec, validating both.
+ *
+ * @param currency ISO 4217 code (minor units from `Intl`) or `{ code, minorUnits }`.
+ * @returns The spec.
+ * @throws RangeError for a malformed code or minor-unit count.
+ * @example resolveCurrency('USD') // { code: 'USD', minorUnits: 2 }
+ */
+export declare function resolveCurrency(currency: CurrencyInput): CurrencySpec;
+/** An immutable amount of one currency, always a whole number of minor units. */
+export declare class Money {
+    private readonly value;
+    /** The amount's currency. */
+    readonly currency: CurrencySpec;
+    private constructor();
+    /**
+     * Parses a decimal string. Strict: no thousands separators, symbols or more decimals than the
+     * currency allows (D5), so a stored value is never silently rounded on the way in.
+     *
+     * @param amount e.g. `"1250.5"` or `"-3.25"`.
+     * @param currency Code or spec.
+     * @returns The amount.
+     * @throws RangeError for anything else.
+     * @example Money.fromDecimalString('19.99', 'USD')
+     */
+    static fromDecimalString(amount: string, currency: CurrencyInput): Money;
+    /**
+     * Builds an amount from an integer count of minor units (e.g. cents).
+     *
+     * @param units Integer (number within the safe range, or bigint).
+     * @param currency Code or spec.
+     * @returns The amount.
+     * @example Money.fromMinorUnits(1999, 'USD').toDecimalString() // '19.99'
+     */
+    static fromMinorUnits(units: number | bigint, currency: CurrencyInput): Money;
+    /**
+     * Zero in a currency.
+     *
+     * @param currency Code or spec.
+     * @returns `0` of that currency.
+     */
+    static zero(currency: CurrencyInput): Money;
+    /** The amount with exactly the currency's decimal places, e.g. `"1250.00"` — the wire and storage form. */
+    toDecimalString(): string;
+    /** The amount as an integer count of minor units. */
+    toMinorUnits(): bigint;
+    /** Serialises as the decimal string, so an amount never becomes a JSON number by accident. */
+    toJSON(): string;
+    /** Same as {@link toDecimalString}. */
+    toString(): string;
+    /** Sum of two amounts of the same currency. */
+    add(other: Money): Money;
+    /** Difference of two amounts of the same currency. */
+    sub(other: Money): Money;
+    /**
+     * Multiplies by a rate (tax, fee, quantity), rounding half-up to the minor unit.
+     *
+     * @param rate e.g. `"0.16"` or `3`.
+     * @returns The rounded product.
+     * @example Money.fromDecimalString('10.05', 'USD').mul('0.5').toDecimalString() // '5.03'
+     */
+    mul(rate: DecimalInput): Money;
+    /**
+     * Splits the amount in proportion to `ratios`; the parts always sum to the amount exactly. Each part is
+     * rounded down to the minor unit and the left-over units go, one each, to the parts with the largest
+     * remainders (earlier parts win ties). A negative amount is split like its absolute value, then negated.
+     *
+     * @param ratios Non-negative weights with a positive sum, e.g. `['1', '1', '1']` or `[70, 30]`.
+     * @returns One amount per ratio, in order.
+     * @throws RangeError for an empty list, a negative ratio or a zero sum.
+     * @example Money.fromDecimalString('100.00', 'USD').allocate([1, 1, 1]).map(String) // ['33.34', '33.33', '33.33']
+     */
+    allocate(ratios: readonly DecimalInput[]): Money[];
+    /**
+     * Rounds up (toward +∞) to a multiple of `unit`, e.g. whole units for a payment rail that rejects cents.
+     *
+     * @param unit Positive step in major units, e.g. `"1"` or `"0.05"`; defaults to `"1"`.
+     * @returns The rounded-up amount.
+     * @example Money.fromDecimalString('99.01', 'USD').ceilToUnit().toDecimalString() // '100.00'
+     */
+    ceilToUnit(unit?: DecimalInput): Money;
+    /** -1, 0 or 1 comparing this amount with `other` (same currency). */
+    compare(other: Money): -1 | 0 | 1;
+    /** True when both amounts have the same currency and value. */
+    equals(other: Money): boolean;
+    /** True for zero. */
+    isZero(): boolean;
+    /** True below zero. */
+    isNegative(): boolean;
+    private same;
+    private round;
+}
+//# sourceMappingURL=money.d.ts.map

package/dist/types/common/money.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.d.ts","sourceRoot":"","sources":["../../../src/common/money.ts"],"names":[],"mappings":"AAeA,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,+FAA+F;AAC/F,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,YAAY,CAAC;AAElD,qHAAqH;AACrH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAK3C;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,aAAa,GAAG,YAAY,CAWrE;AASD,iFAAiF;AACjF,qBAAa,KAAK;IAEd,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,6BAA6B;IAC7B,QAAQ,CAAC,QAAQ,EAAE,YAAY;IAHjC,OAAO;IAQP;;;;;;;;;OASG;IACH,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,KAAK;IAUxE;;;;;;;OAOG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,KAAK;IAM7E;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,GAAG,KAAK;IAI3C,2GAA2G;IAC3G,eAAe,IAAI,MAAM;IAIzB,qDAAqD;IACrD,YAAY,IAAI,MAAM;IAItB,8FAA8F;IAC9F,MAAM,IAAI,MAAM;IAIhB,uCAAuC;IACvC,QAAQ,IAAI,MAAM;IAIlB,+CAA+C;IAC/C,GAAG,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK;IAIxB,sDAAsD;IACtD,GAAG,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK;IAIxB;;;;;;OAMG;IACH,GAAG,CAAC,IAAI,EAAE,YAAY,GAAG,KAAK;IAI9B;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,KAAK,EAAE;IAsBlD;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,GAAE,YAAkB,GAAG,KAAK;IAO3C,qEAAqE;IACrE,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAIjC,+DAA+D;IAC/D,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAI7B,qBAAqB;IACrB,MAAM,IAAI,OAAO;IAIjB,uBAAuB;IACvB,UAAU,IAAI,OAAO;IAIrB,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,KAAK;CAGd"}

package/dist/types/common/phone.d.ts

@@ -3,37 +3,47 @@
  * `0712345678` only make sense against a country, and that country is app configuration.
  *
  * @param phone Number as typed (local or international format).
- * @param region ISO 3166-1 alpha-2 region used for local formats (e.g. `KE`, `GB`).
- * @returns E.164 (`+254712345678`), or null when not a valid number for that region.
- * @example toE164('0712345678', 'KE') // '+254712345678'
+ * @param region ISO 3166-1 alpha-2 region used for local formats (e.g. `GB`, `US`).
+ * @returns E.164 (`+447400123456`), or null when not a valid number for that region.
+ * @example toE164('07400 123456', 'GB') // '+447400123456'
  */
 export declare function toE164(phone: string, region: string): string | null;
+/** Options for {@link toMsisdn}. */
+export interface MsisdnOptions {
+    /** Reject numbers that are not mobile (or mobile-or-fixed) lines, e.g. for SMS or mobile-money payers. */
+    mobileOnly?: boolean;
+    /** Reject numbers that belong to another country than `region` (a foreign `+…` number). */
+    regionOnly?: boolean;
+}
 /**
- * E.164 without the plus sign, as most SMS gateways expect.
+ * E.164 without the plus sign (an MSISDN), as SMS gateways and mobile-money rails expect. Throws instead of
+ * returning null so a bad number can never be stored or sent by mistake; use {@link toE164} to test input.
  *
- * @param phone Number as typed.
- * @param region ISO region for local formats.
- * @returns Digits only, or null when invalid.
- * @example toMsisdn('0712345678', 'KE') // '254712345678'
+ * @param phone Number as typed (local or international format).
+ * @param region ISO 3166-1 alpha-2 region used for local formats (required; no app default).
+ * @param options Mobile-only and same-region checks.
+ * @returns Digits only, country code first.
+ * @throws BadRequestError (`INVALID_PHONE`) when the number is invalid or fails an option.
+ * @example toMsisdn('07400 123456', 'GB') // '447400123456'
  */
-export declare function toMsisdn(phone: string, region: string): string | null;
+export declare function toMsisdn(phone: string, region: string, options?: MsisdnOptions): string;
 /**
  * The region a number belongs to.
  *
  * @param phone Number as typed.
  * @param region ISO region used to interpret local formats.
  * @returns ISO region code, or null when it cannot be determined.
- * @example phoneRegion('+447400123456', 'KE') // 'GB'
+ * @example phoneRegion('+447400123456', 'US') // 'GB'
  */
 export declare function phoneRegion(phone: string, region: string): string | null;
 /**
- * Masks a phone number for logs and UI, so a full number never lands in a log line or screen.
- * Never reveals more than about a third of the input: numbers of 10+ characters keep the first 4 and
- * last 2; shorter inputs keep only the last 2; 4 characters or fewer are fully masked.
+ * Masks a phone number for logs, audit metadata and UI: every digit except the last 4 becomes `*`, so a
+ * full number never lands in a log line or on a screen. Fewer than 5 digits are fully masked
+ * (the same rule the logger applies to phone-like values).
  *
  * @param phone Any phone string (normalised or not).
- * @returns The masked value.
- * @example maskPhone('254712345678') // '2547****78'
+ * @returns The masked digits.
+ * @example maskPhone('+44 7400 123456') // '********3456'
  */
 export declare function maskPhone(phone: string): string;
 //# sourceMappingURL=phone.d.ts.map

package/dist/types/common/phone.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"phone.d.ts","sourceRoot":"","sources":["../../../src/common/phone.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOnE;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGrE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI/C"}
+{"version":3,"file":"phone.d.ts","sourceRoot":"","sources":["../../../src/common/phone.ts"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOnE;AAED,oCAAoC;AACpC,MAAM,WAAW,aAAa;IAC5B,0GAA0G;IAC1G,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAa3F;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI/C"}

package/dist/types/common/time.d.ts

@@ -1,4 +1,4 @@
-/** True for IANA zones the runtime knows (`Africa/Nairobi`), false for garbage. */
+/** True for IANA zones the runtime knows (`Europe/Berlin`), false for garbage. */
 export declare function isValidTimeZone(zone: string): boolean;
 /** Formats an instant in a zone, e.g. `30 Sep 2026, 14:05 EAT`. Falls back to UTC for invalid zones. */
 export declare function formatInTimeZone(date: Date | string | number, zone: string, locale?: string): string;
@@ -27,7 +27,16 @@ export declare function parseClockTime(value: string): number;
  * time skipped by a spring-forward resolves to the nearest valid instant.
  */
 export declare function zonedWallTimeToInstant(year: number, month: number, day: number, minutesOfDay: number, zone: string): Date;
-/** The local calendar day containing `at` in `zone`, as a half-open `[start, end)` UTC range (23–25 h on DST days). */
+/**
+ * The local calendar day containing `at` in `zone`, as a half-open `[start, end)` UTC range (23–25 h on
+ * DST days). Use it for "today" in reports, business days and daily limits.
+ *
+ * @param at Any instant in the day.
+ * @param zone IANA zone (required; no app default).
+ * @returns `{ start, end }` with `start` inclusive and `end` exclusive.
+ * @throws RangeError for an unknown zone.
+ * @example zonedDayBounds(new Date('2026-10-11T22:30:00Z'), 'Asia/Riyadh') // 2026-10-11T21:00Z → 2026-10-12T21:00Z
+ */
 export declare function zonedDayBounds(at: Date, zone: string): {
     start: Date;
     end: Date;
@@ -37,4 +46,13 @@ export declare function zonedDayBounds(at: Date, zone: string): {
  * cross midnight), the instant that window ends; otherwise null. `start === end` means no window.
  */
 export declare function quietWindowEndAt(at: Date, zone: string, start: string, end: string): Date | null;
+/**
+ * The instant as a UTC ISO-8601 string (`2026-11-13T09:00:00.000Z`), the form every timestamp travels in.
+ *
+ * @param instant A Date, an epoch-milliseconds number or a string `Date` can parse.
+ * @returns The `toISOString()` form.
+ * @throws RangeError when the input is not a valid instant (never returns `"Invalid Date"`).
+ * @example toUtcIso('2026-11-13T12:00:00+03:00') // '2026-11-13T09:00:00.000Z'
+ */
+export declare function toUtcIso(instant: Date | string | number): string;
 //# sourceMappingURL=time.d.ts.map

package/dist/types/common/time.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../../src/common/time.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED,wGAAwG;AACxG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,SAAU,GAAG,MAAM,CAWrG;AAED,MAAM,WAAW,SAAS;IACxB,wGAAwG;IACxG,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,SAAQ,EAAE,MAAM,SAAU,GAAG,SAAS,CAKrI;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAE,IAAiB,GAAG,MAAM,CAOjF;AAED,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,EAAE,SAAS,MAAM,KAAG,IAAiD,CAAC;AAC3G,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,EAAE,SAAS,MAAM,KAAG,IAAsC,CAAC;AAMhG,uGAAuG;AACvG,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpD;AASD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAIzH;AAED,uHAAuH;AACvH,wBAAgB,cAAc,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,CAGjF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAchG"}
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../../src/common/time.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED,wGAAwG;AACxG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,SAAU,GAAG,MAAM,CAWrG;AAED,MAAM,WAAW,SAAS;IACxB,wGAAwG;IACxG,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,SAAQ,EAAE,MAAM,SAAU,GAAG,SAAS,CAKrI;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAE,IAAiB,GAAG,MAAM,CAOjF;AAED,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,EAAE,SAAS,MAAM,KAAG,IAAiD,CAAC;AAC3G,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,EAAE,SAAS,MAAM,KAAG,IAAsC,CAAC;AAMhG,uGAAuG;AACvG,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpD;AASD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAIzH;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,CAIjF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAchG;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAIhE"}