@heavybit/shared-lib 1.3.2 → 2.7.0

package/dist/esm/common/internal-service-auth.js

@@ -0,0 +1,150 @@
+/**
+ * Per-caller service-to-service credentials.
+ *
+ * Layer: plumbing (no HTTP framework). Key rules:
+ * - Every calling service has its **own** secret (`INTERNAL_SERVICE_CREDENTIAL`) and sends it with its name
+ *   (`INTERNAL_SERVICE_NAME`). A receiving service holds `INTERNAL_SERVICE_CREDENTIALS`, a JSON map of
+ *   caller name → the secret it accepts from that caller, and each internal route lists the callers it allows.
+ *   One leaked credential therefore reaches only the routes meant for that one caller.
+ * - Secrets are compared in constant time (SHA-256 digests + `timingSafeEqual`, so lengths don't leak) and
+ *   are never logged or put in error messages.
+ * - Staging and production refuse to start without the credentials a service needs
+ *   ({@link assertInternalServiceAuthConfigured}); development and test may run without them.
+ *
+ * App-independent: caller names are whatever the app's compose service names are.
+ */
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { ConfigError } from '../config/index.js';
+import { CONTEXT_HEADERS } from '../identity/index.js';
+import { MIN_INTERNAL_CREDENTIAL_LENGTH, SERVICE_NAME_PATTERN } from './internal-constants.js';
+/** Header carrying the calling service's name. */
+export const INTERNAL_SERVICE_NAME_HEADER = CONTEXT_HEADERS.INTERNAL_SERVICE_NAME;
+/** Header carrying the calling service's own secret. */
+export const INTERNAL_SERVICE_SECRET_HEADER = CONTEXT_HEADERS.INTERNAL_SECRET;
+export { MIN_INTERNAL_CREDENTIAL_LENGTH, SERVICE_NAME_PATTERN } from './internal-constants.js';
+/** Environments where missing or weak internal credentials stop the service from starting. */
+const STRICT_ENVIRONMENTS = new Set(['staging', 'production']);
+const read = (env, key) => {
+    const value = env[key];
+    return typeof value === 'string' ? value.trim() : '';
+};
+/**
+ * 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 function parseInternalServiceCredentials(raw) {
+    if (!raw?.trim())
+        return Object.freeze({});
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new ConfigError('INTERNAL_SERVICE_CREDENTIALS must be a JSON object of service name to secret');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new ConfigError('INTERNAL_SERVICE_CREDENTIALS must be a JSON object of service name to secret');
+    }
+    const credentials = {};
+    for (const [name, secret] of Object.entries(parsed)) {
+        if (!SERVICE_NAME_PATTERN.test(name))
+            throw new ConfigError(`INTERNAL_SERVICE_CREDENTIALS has an invalid service name: "${name}"`);
+        if (typeof secret !== 'string' || !secret)
+            throw new ConfigError(`INTERNAL_SERVICE_CREDENTIALS has an empty or non-string secret for "${name}"`);
+        credentials[name] = secret;
+    }
+    return Object.freeze(credentials);
+}
+/**
+ * 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 function internalServiceAuthConfigFromEnv(env = process.env) {
+    return {
+        name: read(env, 'INTERNAL_SERVICE_NAME'),
+        credential: read(env, 'INTERNAL_SERVICE_CREDENTIAL'),
+        credentials: parseInternalServiceCredentials(read(env, 'INTERNAL_SERVICE_CREDENTIALS')),
+    };
+}
+/**
+ * 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 function internalServiceHeaders(caller) {
+    return { [INTERNAL_SERVICE_NAME_HEADER]: caller.name, [INTERNAL_SERVICE_SECRET_HEADER]: caller.secret };
+}
+/**
+ * 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 function assertInternalServiceAuthConfigured(options) {
+    const env = options.env ?? process.env;
+    const config = internalServiceAuthConfigFromEnv(env);
+    if (!STRICT_ENVIRONMENTS.has(options.nodeEnv ?? read(env, 'NODE_ENV')))
+        return;
+    const problems = [];
+    if (options.calls) {
+        if (!SERVICE_NAME_PATTERN.test(config.name))
+            problems.push('INTERNAL_SERVICE_NAME is missing or not a valid service name');
+        if (config.credential.length < MIN_INTERNAL_CREDENTIAL_LENGTH) {
+            problems.push(`INTERNAL_SERVICE_CREDENTIAL must be at least ${MIN_INTERNAL_CREDENTIAL_LENGTH} characters`);
+        }
+    }
+    if (options.serves) {
+        const callers = Object.keys(config.credentials);
+        if (!callers.length)
+            problems.push('INTERNAL_SERVICE_CREDENTIALS is empty: no internal caller can authenticate');
+        const weak = callers.filter((name) => (config.credentials[name] ?? '').length < MIN_INTERNAL_CREDENTIAL_LENGTH);
+        if (weak.length)
+            problems.push(`INTERNAL_SERVICE_CREDENTIALS has secrets shorter than ${MIN_INTERNAL_CREDENTIAL_LENGTH} characters for: ${weak.join(', ')}`);
+    }
+    if (problems.length)
+        throw new ConfigError(`Refusing to start: ${problems.join('; ')}`);
+}
+const digest = (value) => createHash('sha256').update(value).digest();
+/** A fixed value to compare against when the caller is unknown, so unknown and known callers take the same time. */
+const UNKNOWN_CALLER_DIGEST = digest('unknown-caller');
+const header = (headers, name) => {
+    const value = headers[name];
+    return typeof value === 'string' ? value : '';
+};
+/**
+ * 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 function verifyInternalCaller(input) {
+    const caller = header(input.headers, INTERNAL_SERVICE_NAME_HEADER);
+    const secret = header(input.headers, INTERNAL_SERVICE_SECRET_HEADER);
+    if (!caller || !secret)
+        return { ok: false, status: 401, reason: 'missing-credentials', caller: caller || undefined };
+    const expected = Object.prototype.hasOwnProperty.call(input.credentials, caller) ? input.credentials[caller] : undefined;
+    const matches = timingSafeEqual(digest(secret), expected ? digest(expected) : UNKNOWN_CALLER_DIGEST) && expected !== undefined;
+    if (!matches)
+        return { ok: false, status: 401, reason: 'invalid-credentials', caller };
+    if (!input.allowed.includes(caller))
+        return { ok: false, status: 403, reason: 'caller-not-allowed', caller };
+    return { ok: true, caller };
+}
+//# sourceMappingURL=internal-service-auth.js.map

package/dist/esm/common/internal-service-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-service-auth.js","sourceRoot":"","sources":["../../../src/common/internal-service-auth.ts"],"names":[],"mappings":"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"}

package/dist/esm/common/money.js

@@ -0,0 +1,207 @@
+import Decimal from 'decimal.js';
+/**
+ * Exact money arithmetic. Amounts travel and persist as decimal strings (`"1250.00"`) and are only ever
+ * computed with a decimal type, never JS numbers. The currency is always passed in: shared-lib has no
+ * default currency.
+ *
+ * Rounding is half-up (half away from zero) to the currency's minor unit, after every operation that can
+ * produce extra digits (`mul`), so a `Money` value always holds a whole number of minor units.
+ */
+/** A decimal.js constructor with enough precision for any realistic amount and half-up rounding. */
+const Dec = Decimal.clone({ precision: 40, rounding: Decimal.ROUND_HALF_UP, toExpNeg: -40, toExpPos: 40 });
+const CODE_PATTERN = /^[A-Z]{3}$/;
+const AMOUNT_PATTERN = /^-?\d+(\.\d+)?$/;
+/**
+ * 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 function resolveCurrency(currency) {
+    if (typeof currency !== 'string') {
+        if (!CODE_PATTERN.test(currency.code))
+            throw new RangeError(`Invalid currency code "${currency.code}"`);
+        if (!Number.isInteger(currency.minorUnits) || currency.minorUnits < 0 || currency.minorUnits > 6) {
+            throw new RangeError(`Invalid minor units ${currency.minorUnits} for ${currency.code}`);
+        }
+        return { code: currency.code, minorUnits: currency.minorUnits };
+    }
+    if (!CODE_PATTERN.test(currency))
+        throw new RangeError(`Invalid currency code "${currency}"`);
+    const minorUnits = new Intl.NumberFormat('en', { style: 'currency', currency }).resolvedOptions().maximumFractionDigits ?? 2;
+    return { code: currency, minorUnits };
+}
+function toDecimal(value, what) {
+    if (typeof value === 'number' && !Number.isFinite(value))
+        throw new RangeError(`${what} must be finite`);
+    const text = String(value).trim();
+    if (!AMOUNT_PATTERN.test(text))
+        throw new RangeError(`${what} must be a decimal number, got "${value}"`);
+    return new Dec(text);
+}
+/** An immutable amount of one currency, always a whole number of minor units. */
+export class Money {
+    value;
+    currency;
+    constructor(value, 
+    /** The amount's currency. */
+    currency) {
+        this.value = value;
+        this.currency = currency;
+        Object.freeze(this);
+    }
+    /**
+     * 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, currency) {
+        const spec = resolveCurrency(currency);
+        if (typeof amount !== 'string')
+            throw new RangeError('Amount must be a decimal string');
+        const value = toDecimal(amount, 'Amount');
+        if (value.decimalPlaces() > spec.minorUnits) {
+            throw new RangeError(`Amount "${amount}" has more than ${spec.minorUnits} decimal places for ${spec.code}`);
+        }
+        return new Money(value, spec);
+    }
+    /**
+     * 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, currency) {
+        const spec = resolveCurrency(currency);
+        if (typeof units === 'number' && !Number.isSafeInteger(units))
+            throw new RangeError('Minor units must be a safe integer');
+        return new Money(new Dec(units.toString()).div(new Dec(10).pow(spec.minorUnits)), spec);
+    }
+    /**
+     * Zero in a currency.
+     *
+     * @param currency Code or spec.
+     * @returns `0` of that currency.
+     */
+    static zero(currency) {
+        return new Money(new Dec(0), resolveCurrency(currency));
+    }
+    /** The amount with exactly the currency's decimal places, e.g. `"1250.00"` — the wire and storage form. */
+    toDecimalString() {
+        return this.value.toFixed(this.currency.minorUnits);
+    }
+    /** The amount as an integer count of minor units. */
+    toMinorUnits() {
+        return BigInt(this.value.times(new Dec(10).pow(this.currency.minorUnits)).toFixed(0));
+    }
+    /** Serialises as the decimal string, so an amount never becomes a JSON number by accident. */
+    toJSON() {
+        return this.toDecimalString();
+    }
+    /** Same as {@link toDecimalString}. */
+    toString() {
+        return this.toDecimalString();
+    }
+    /** Sum of two amounts of the same currency. */
+    add(other) {
+        return new Money(this.value.plus(this.same(other).value), this.currency);
+    }
+    /** Difference of two amounts of the same currency. */
+    sub(other) {
+        return new Money(this.value.minus(this.same(other).value), this.currency);
+    }
+    /**
+     * 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) {
+        return new Money(this.round(this.value.times(toDecimal(rate, 'Rate'))), this.currency);
+    }
+    /**
+     * 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) {
+        if (ratios.length === 0)
+            throw new RangeError('allocate needs at least one ratio');
+        const weights = ratios.map((r) => toDecimal(r, 'Ratio'));
+        if (weights.some((w) => w.isNegative()))
+            throw new RangeError('Ratios must not be negative');
+        const sum = weights.reduce((acc, w) => acc.plus(w), new Dec(0));
+        if (sum.isZero())
+            throw new RangeError('Ratios must not all be zero');
+        const scale = new Dec(10).pow(this.currency.minorUnits);
+        const total = this.value.abs().times(scale);
+        const exact = weights.map((w) => total.times(w).div(sum));
+        const floors = exact.map((e) => e.floor());
+        let leftover = total.minus(floors.reduce((acc, f) => acc.plus(f), new Dec(0))).toNumber();
+        const order = exact.map((e, i) => ({ i, rem: e.minus(floors[i]) })).sort((a, b) => b.rem.comparedTo(a.rem) || a.i - b.i);
+        for (const { i } of order) {
+            if (leftover <= 0)
+                break;
+            floors[i] = floors[i].plus(1);
+            leftover -= 1;
+        }
+        const sign = this.value.isNegative() ? -1 : 1;
+        return floors.map((units) => new Money(units.div(scale).times(sign), this.currency));
+    }
+    /**
+     * 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 = '1') {
+        const step = toDecimal(unit, 'Unit');
+        if (step.lte(0))
+            throw new RangeError('Unit must be positive');
+        if (step.decimalPlaces() > this.currency.minorUnits)
+            throw new RangeError(`Unit is finer than the ${this.currency.code} minor unit`);
+        return new Money(this.value.div(step).ceil().times(step), this.currency);
+    }
+    /** -1, 0 or 1 comparing this amount with `other` (same currency). */
+    compare(other) {
+        return this.value.comparedTo(this.same(other).value);
+    }
+    /** True when both amounts have the same currency and value. */
+    equals(other) {
+        return this.currency.code === other.currency.code && this.value.equals(other.value);
+    }
+    /** True for zero. */
+    isZero() {
+        return this.value.isZero();
+    }
+    /** True below zero. */
+    isNegative() {
+        return this.value.isNegative() && !this.value.isZero();
+    }
+    same(other) {
+        if (other.currency.code !== this.currency.code) {
+            throw new RangeError(`Currency mismatch: ${this.currency.code} vs ${other.currency.code}`);
+        }
+        return other;
+    }
+    round(value) {
+        return value.toDecimalPlaces(this.currency.minorUnits, Decimal.ROUND_HALF_UP);
+    }
+}
+//# sourceMappingURL=money.js.map

package/dist/esm/common/money.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.js","sourceRoot":"","sources":["../../../src/common/money.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,YAAY,CAAC;AAEjC;;;;;;;GAOG;AAEH,oGAAoG;AACpG,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,aAAa,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;AAiB3G,MAAM,YAAY,GAAG,YAAY,CAAC;AAClC,MAAM,cAAc,GAAG,iBAAiB,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,QAAuB;IACrD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,0BAA0B,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC;QACxG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,QAAQ,CAAC,UAAU,GAAG,CAAC,IAAI,QAAQ,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;YACjG,MAAM,IAAI,UAAU,CAAC,uBAAuB,QAAQ,CAAC,UAAU,QAAQ,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1F,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,CAAC;IAClE,CAAC;IACD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,0BAA0B,QAAQ,GAAG,CAAC,CAAC;IAC9F,MAAM,UAAU,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC,eAAe,EAAE,CAAC,qBAAqB,IAAI,CAAC,CAAC;IAC7H,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AACxC,CAAC;AAED,SAAS,SAAS,CAAC,KAAmB,EAAE,IAAY;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,iBAAiB,CAAC,CAAC;IACzG,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IAClC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,mCAAmC,KAAK,GAAG,CAAC,CAAC;IACzG,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC;AAED,iFAAiF;AACjF,MAAM,OAAO,KAAK;IAEG;IAER;IAHX,YACmB,KAAU;IAC3B,6BAA6B;IACpB,QAAsB;QAFd,UAAK,GAAL,KAAK,CAAK;QAElB,aAAQ,GAAR,QAAQ,CAAc;QAE/B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,iBAAiB,CAAC,MAAc,EAAE,QAAuB;QAC9D,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;QACvC,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,MAAM,IAAI,UAAU,CAAC,iCAAiC,CAAC,CAAC;QACxF,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC1C,IAAI,KAAK,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YAC5C,MAAM,IAAI,UAAU,CAAC,WAAW,MAAM,mBAAmB,IAAI,CAAC,UAAU,uBAAuB,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9G,CAAC;QACD,OAAO,IAAI,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,cAAc,CAAC,KAAsB,EAAE,QAAuB;QACnE,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;QACvC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,oCAAoC,CAAC,CAAC;QAC1H,OAAO,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC1F,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,QAAuB;QACjC,OAAO,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,2GAA2G;IAC3G,eAAe;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACtD,CAAC;IAED,qDAAqD;IACrD,YAAY;QACV,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IACxF,CAAC;IAED,8FAA8F;IAC9F,MAAM;QACJ,OAAO,IAAI,CAAC,eAAe,EAAE,CAAC;IAChC,CAAC;IAED,uCAAuC;IACvC,QAAQ;QACN,OAAO,IAAI,CAAC,eAAe,EAAE,CAAC;IAChC,CAAC;IAED,+CAA+C;IAC/C,GAAG,CAAC,KAAY;QACd,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC3E,CAAC;IAED,sDAAsD;IACtD,GAAG,CAAC,KAAY;QACd,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5E,CAAC;IAED;;;;;;OAMG;IACH,GAAG,CAAC,IAAkB;QACpB,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACzF,CAAC;IAED;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAA+B;QACtC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,mCAAmC,CAAC,CAAC;QACnF,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACzD,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,6BAA6B,CAAC,CAAC;QAC7F,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAChE,IAAI,GAAG,CAAC,MAAM,EAAE;YAAE,MAAM,IAAI,UAAU,CAAC,6BAA6B,CAAC,CAAC;QAEtE,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1D,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;QAC3C,IAAI,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC1F,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACzH,KAAK,MAAM,EAAE,CAAC,EAAE,IAAI,KAAK,EAAE,CAAC;YAC1B,IAAI,QAAQ,IAAI,CAAC;gBAAE,MAAM;YACzB,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC9B,QAAQ,IAAI,CAAC,CAAC;QAChB,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IACvF,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,OAAqB,GAAG;QACjC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACrC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,uBAAuB,CAAC,CAAC;QAC/D,IAAI,IAAI,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU;YAAE,MAAM,IAAI,UAAU,CAAC,0BAA0B,IAAI,CAAC,QAAQ,CAAC,IAAI,aAAa,CAAC,CAAC;QACrI,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC3E,CAAC;IAED,qEAAqE;IACrE,OAAO,CAAC,KAAY;QAClB,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAe,CAAC;IACrE,CAAC;IAED,+DAA+D;IAC/D,MAAM,CAAC,KAAY;QACjB,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,KAAK,CAAC,QAAQ,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACtF,CAAC;IAED,qBAAqB;IACrB,MAAM;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;IAC7B,CAAC;IAED,uBAAuB;IACvB,UAAU;QACR,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;IACzD,CAAC;IAEO,IAAI,CAAC,KAAY;QACvB,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC/C,MAAM,IAAI,UAAU,CAAC,sBAAsB,IAAI,CAAC,QAAQ,CAAC,IAAI,OAAO,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QAC7F,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAEO,KAAK,CAAC,KAAU;QACtB,OAAO,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAChF,CAAC;CACF"}

package/dist/esm/common/phone.js

@@ -1,33 +1,85 @@
 import libphonenumber from 'google-libphonenumber';
+import { BadRequestError } from './errors.js';
 const util = libphonenumber.PhoneNumberUtil.getInstance();
 const { PhoneNumberFormat } = libphonenumber;
 /**
- * Normalises a phone number to E.164 (`+254712345678`). Returns null for anything that is not a
- * valid number for the given default region.
+ * Normalises a phone number to E.164. The region is required (no app default): local formats such as
+ * `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. `GB`, `US`).
+ * @returns E.164 (`+447400123456`), or null when not a valid number for that region.
+ * @example toE164('07400 123456', 'GB') // '+447400123456'
  */
-export function toE164(phone, defaultRegion = 'KE') {
+export function toE164(phone, region) {
     try {
-        const parsed = util.parseAndKeepRawInput(phone.trim(), defaultRegion);
+        const parsed = util.parseAndKeepRawInput(phone.trim(), region);
         return util.isValidNumber(parsed) ? util.format(parsed, PhoneNumberFormat.E164) : null;
     }
     catch {
         return null;
     }
 }
-/** E.164 without the plus sign, as most SMS gateways expect (`254712345678`). */
-export function toMsisdn(phone, defaultRegion = 'KE') {
-    const e164 = toE164(phone, defaultRegion);
-    return e164 ? e164.slice(1) : null;
+const MOBILE_TYPES = new Set([libphonenumber.PhoneNumberType.MOBILE, libphonenumber.PhoneNumberType.FIXED_LINE_OR_MOBILE]);
+/**
+ * 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 (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 function toMsisdn(phone, region, options = {}) {
+    const invalid = () => new BadRequestError('Enter a valid phone number', { code: 'INVALID_PHONE' });
+    if (typeof phone !== 'string' || !region)
+        throw invalid();
+    let parsed;
+    try {
+        parsed = util.parseAndKeepRawInput(phone.trim(), region);
+    }
+    catch {
+        throw invalid();
+    }
+    if (!util.isValidNumber(parsed))
+        throw invalid();
+    if (options.regionOnly && util.getRegionCodeForNumber(parsed) !== region.toUpperCase())
+        throw invalid();
+    if (options.mobileOnly && !MOBILE_TYPES.has(util.getNumberType(parsed)))
+        throw invalid();
+    return util.format(parsed, PhoneNumberFormat.E164).slice(1);
 }
-export function phoneRegion(phone, defaultRegion = 'KE') {
+/**
+ * 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', 'US') // 'GB'
+ */
+export function phoneRegion(phone, region) {
     try {
-        return util.getRegionCodeForNumber(util.parse(phone, defaultRegion)) ?? null;
+        return util.getRegionCodeForNumber(util.parse(phone, region)) ?? null;
     }
     catch {
         return null;
     }
 }
+/**
+ * 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 digits.
+ * @example maskPhone('+44 7400 123456') // '********3456'
+ */
 export function maskPhone(phone) {
-    return phone.length <= 4 ? '****' : `${phone.slice(0, 4)}****${phone.slice(-2)}`;
+    const digits = String(phone ?? '').replace(/\D/g, '');
+    if (digits.length < 5)
+        return '*'.repeat(digits.length || 4);
+    return `${'*'.repeat(digits.length - 4)}${digits.slice(-4)}`;
 }
 //# sourceMappingURL=phone.js.map

package/dist/esm/common/phone.js.map

@@ -1 +1 @@
-{"version":3,"file":"phone.js","sourceRoot":"","sources":["../../../src/common/phone.ts"],"names":[],"mappings":"AAAA,OAAO,cAAc,MAAM,uBAAuB,CAAC;AAEnD,MAAM,IAAI,GAAG,cAAc,CAAC,eAAe,CAAC,WAAW,EAAE,CAAC;AAC1D,MAAM,EAAE,iBAAiB,EAAE,GAAG,cAAc,CAAC;AAE7C;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,aAAa,GAAG,IAAI;IACxD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,aAAa,CAAC,CAAC;QACtE,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACzF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,QAAQ,CAAC,KAAa,EAAE,aAAa,GAAG,IAAI;IAC1D,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IAC1C,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,aAAa,GAAG,IAAI;IAC7D,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC,IAAI,IAAI,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACnF,CAAC"}
+{"version":3,"file":"phone.js","sourceRoot":"","sources":["../../../src/common/phone.ts"],"names":[],"mappings":"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"}

package/dist/esm/common/response.js

@@ -1,19 +1,75 @@
-/** Standard success envelope: `{ success, message, data }`. */
+/**
+ * Standard success envelope: `{ success, message, data }`.
+ *
+ * @param data Payload placed under `data`.
+ * @param message Human-readable message (default `Success`).
+ * @returns The envelope, ready for `res.json`.
+ * @example res.json(successResponse(order, 'Order placed'));
+ */
 export function successResponse(data, message = 'Success') {
     return { success: true, message, data };
 }
-/** Standard error envelope: `{ success: false, message, code?, errors? }`. */
-export function errorResponse(message, errors, code) {
-    return { success: false, message, ...(code ? { code } : {}), ...(errors ? { errors } : {}) };
+/**
+ * Standard error envelope: `{ success: false, message, code?, errors?, requestId? }`.
+ * Prefer throwing an AppError and letting the error middleware answer; use this only where a
+ * middleware must answer directly. For a body with a guaranteed `code`, use {@link errorBody}.
+ *
+ * @param message Message for the caller (never an internal error message).
+ * @param errors Optional field errors.
+ * @param code Optional UPPER_SNAKE_CASE code.
+ * @param requestId Optional correlation id of the request.
+ * @returns An envelope with `success: false`.
+ */
+export function errorResponse(message, errors, code, requestId) {
+    return { success: false, message, ...(code ? { code } : {}), ...(errors ? { errors } : {}), ...(requestId ? { requestId } : {}) };
 }
+/**
+ * The error body with a required `code`, as the error middleware sends it.
+ *
+ * @param code UPPER_SNAKE_CASE machine-readable code.
+ * @param message Message for the caller (generic for 5xx).
+ * @param options `errors` (field errors) and `requestId` (correlation id), both omitted when absent.
+ * @returns `{ success: false, code, message, errors?, requestId? }`.
+ *
+ * @example res.status(404).json(errorBody('NOT_FOUND', 'Resource not found', { requestId }));
+ */
+export function errorBody(code, message, options = {}) {
+    return {
+        success: false,
+        code,
+        message,
+        ...(options.errors ? { errors: options.errors } : {}),
+        ...(options.requestId ? { requestId: options.requestId } : {}),
+    };
+}
+/**
+ * Offset pagination meta. `totalPages` is at least 1 so an empty list still reads as "page 1 of 1".
+ *
+ * @param total Total matching rows.
+ * @param page 1-based page that was returned.
+ * @param limit Page size.
+ * @returns `{ page, limit, total, totalPages, hasNext, hasPrev }`.
+ * @example buildPaginationMeta(45, 2, 20) // { page: 2, totalPages: 3, hasNext: true, hasPrev: true, … }
+ */
 export function buildPaginationMeta(total, page, limit) {
     const totalPages = limit > 0 ? Math.max(1, Math.ceil(total / limit)) : 1;
     return { page, limit, total, totalPages, hasNext: page < totalPages, hasPrev: page > 1 };
 }
-/** Paginated envelope: `{ success, message, data: T[], meta }`. */
+/**
+ * Offset-paginated envelope: `{ success, message, data: T[], meta }`.
+ *
+ * @returns The envelope with meta from {@link buildPaginationMeta}.
+ * @example res.json(paginatedResponse(rows, total, page, limit));
+ */
 export function paginatedResponse(data, total, page, limit, message = 'Success') {
     return { success: true, message, data, meta: buildPaginationMeta(total, page, limit) };
 }
+/**
+ * Offset page as a service returns it (data + meta, no envelope).
+ *
+ * @returns `{ data, meta }`.
+ * @example return buildPaginatedResult(rows, total, page, limit);
+ */
 export function buildPaginatedResult(data, total, page, limit) {
     return { data, meta: buildPaginationMeta(total, page, limit) };
 }
@@ -21,4 +77,18 @@ export function buildPaginatedResult(data, total, page, limit) {
 export function pageOffset(page, limit) {
     return Math.max(0, (Math.max(1, page) - 1) * limit);
 }
+/**
+ * Cursor pagination meta. `hasMore` is derived from `nextCursor`, so the two can never disagree.
+ *
+ * @param limit The page size that was applied.
+ * @param nextCursor Opaque cursor for the next page, or null on the last page.
+ * @example buildCursorPageMeta(20, rows.length > 20 ? encodeCursor(rows[19]) : null)
+ */
+export function buildCursorPageMeta(limit, nextCursor) {
+    return { limit, nextCursor, hasMore: nextCursor !== null };
+}
+/** Cursor-paginated envelope: `{ success, message, data: T[], meta: { limit, nextCursor, hasMore } }`. */
+export function cursorPaginatedResponse(page, message = 'Success') {
+    return { success: true, message, data: page.data, meta: page.meta };
+}
 //# sourceMappingURL=response.js.map

package/dist/esm/common/response.js.map

@@ -1 +1 @@
-{"version":3,"file":"response.js","sourceRoot":"","sources":["../../../src/common/response.ts"],"names":[],"mappings":"AAEA,+DAA+D;AAC/D,MAAM,UAAU,eAAe,CAAI,IAAO,EAAE,OAAO,GAAG,SAAS;IAC7D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC1C,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,MAAiC,EAAE,IAAa;IAC7F,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC/F,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,IAAY,EAAE,KAAa;IAC5E,MAAM,UAAU,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,GAAG,UAAU,EAAE,OAAO,EAAE,IAAI,GAAG,CAAC,EAAE,CAAC;AAC3F,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,iBAAiB,CAAI,IAAS,EAAE,KAAa,EAAE,IAAY,EAAE,KAAa,EAAE,OAAO,GAAG,SAAS;IAC7G,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,mBAAmB,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;AACzF,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAI,IAAS,EAAE,KAAa,EAAE,IAAY,EAAE,KAAa;IAC3F,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,mBAAmB,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;AACjE,CAAC;AAED,oCAAoC;AACpC,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,KAAa;IACpD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;AACtD,CAAC"}
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../../src/common/response.ts"],"names":[],"mappings":"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"}

package/dist/esm/common/time.js

@@ -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 function isValidTimeZone(zone) {
     try {
         new Intl.DateTimeFormat('en-US', { timeZone: zone });
@@ -68,8 +68,19 @@ export function zonedWallTimeToInstant(year, month, day, minutesOfDay, zone) {
     const estimate = wall - timeZoneOffsetMinutes(zone, new Date(wall)) * MS_PER_MINUTE;
     return new Date(wall - timeZoneOffsetMinutes(zone, new Date(estimate)) * MS_PER_MINUTE);
 }
-/** 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 function zonedDayBounds(at, zone) {
+    if (!isValidTimeZone(zone))
+        throw new RangeError(`Unknown time zone "${zone}"`);
     const { year, month, day } = localDate(at, zone);
     return { start: zonedWallTimeToInstant(year, month, day, 0, zone), end: zonedWallTimeToInstant(year, month, day + 1, 0, zone) };
 }
@@ -93,4 +104,18 @@ export function quietWindowEndAt(at, zone, start, end) {
     const endsTomorrow = crossesMidnight && msOfDay >= startMs;
     return zonedWallTimeToInstant(year, month, day + (endsTomorrow ? 1 : 0), endMin, zone);
 }
+/**
+ * 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 function toUtcIso(instant) {
+    const date = instant instanceof Date ? instant : new Date(instant);
+    if (Number.isNaN(date.getTime()))
+        throw new RangeError(`Not a valid instant: "${String(instant)}"`);
+    return date.toISOString();
+}
 //# sourceMappingURL=time.js.map