@heavybit/shared-lib 1.3.2 → 2.7.0

package/dist/types/common/circuit-breaker.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A minimal in-process circuit breaker for outbound calls.
+ *
+ * Layer: plumbing. States: `closed` (calls flow) → `open` after `failureThreshold` consecutive failures
+ * (calls are refused without touching the network) → `half-open` once `resetAfterMs` has passed, when exactly
+ * one trial call is let through: success closes the circuit, failure re-opens it for another `resetAfterMs`.
+ * State is per instance (per process), so each client owns its breaker; nothing is shared between targets.
+ */
+/** Breaker state. */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+/** Breaker settings. */
+export interface CircuitBreakerOptions {
+    /** Consecutive failures that open the circuit (default 5). */
+    failureThreshold?: number;
+    /** How long the circuit stays open before one trial call is allowed (default 30 000 ms). */
+    resetAfterMs?: number;
+    /** Clock, for tests (default `Date.now`). */
+    now?: () => number;
+}
+/**
+ * Counts consecutive failures and refuses calls while open.
+ *
+ * @example
+ * const breaker = new CircuitBreaker({ failureThreshold: 5, resetAfterMs: 30_000 });
+ * if (!breaker.tryAcquire()) throw new TargetUnavailableError();
+ * try { const r = await call(); breaker.onSuccess(); return r; } catch (e) { breaker.onFailure(); throw e; }
+ */
+export declare class CircuitBreaker {
+    private readonly failureThreshold;
+    private readonly resetAfterMs;
+    private readonly now;
+    private failures;
+    private openedAt;
+    private current;
+    private trialInFlight;
+    /** @param options Threshold, reset time and clock. @throws Error when a setting is not a positive number. */
+    constructor(options?: CircuitBreakerOptions);
+    /** The current state (an open circuit whose reset time has passed reports `half-open`). */
+    get state(): CircuitState;
+    /**
+     * Asks to make a call. While half-open only the first caller gets the trial; the rest are refused until it settles.
+     *
+     * @returns True when the call may go ahead; the caller must then report {@link onSuccess} or {@link onFailure}.
+     */
+    tryAcquire(): boolean;
+    /** Records a successful call: closes the circuit and clears the failure count. */
+    onSuccess(): void;
+    /** Records a failed call: a failed trial re-opens at once; otherwise opens after `failureThreshold` in a row. */
+    onFailure(): void;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/types/common/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../../src/common/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qBAAqB;AACrB,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,wBAAwB;AACxB,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,aAAa,CAAS;IAE9B,6GAA6G;gBACjG,OAAO,GAAE,qBAA0B;IAO/C,2FAA2F;IAC3F,IAAI,KAAK,IAAI,YAAY,CAGxB;IAED;;;;OAIG;IACH,UAAU,IAAI,OAAO;IASrB,kFAAkF;IAClF,SAAS,IAAI,IAAI;IAMjB,iHAAiH;IACjH,SAAS,IAAI,IAAI;CAQlB"}

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

@@ -3,6 +3,12 @@ export type ErrorDetails = Record<string, string[]>;
  * Base class for errors that map to an HTTP status. Throw these from services; the shared
  * error middleware turns them into the standard envelope. Anything that is not an AppError is
  * reported as a 500 with a generic message so internals never leak.
+ *
+ * @param statusCode HTTP status. 4xx messages reach the caller; 5xx messages never do.
+ * @param message Caller-facing message (4xx) or log message (5xx).
+ * @param options `code` (defaults from the status), field `errors`, `retryable` (consumers),
+ *   `retryAfterSeconds` (sent as `Retry-After`) and `cause`.
+ * @example throw new AppError(402, 'Payment is required first', { code: 'PAYMENT_REQUIRED' });
  */
 export declare class AppError extends Error {
     readonly statusCode: number;
@@ -10,48 +16,73 @@ export declare class AppError extends Error {
     readonly errors?: ErrorDetails;
     /** Consumers dead-letter immediately instead of retrying when this is false. */
     readonly retryable: boolean;
-    constructor(statusCode: number, message: string, options?: {
-        code?: string;
-        errors?: ErrorDetails;
-        retryable?: boolean;
-        cause?: unknown;
-    });
+    /** Seconds the caller should wait before retrying; the error middleware sends it as `Retry-After`. */
+    readonly retryAfterSeconds?: number;
+    constructor(statusCode: number, message: string, options?: AppErrorOptions);
+}
+/** Options for {@link AppError}. `code` should be UPPER_SNAKE_CASE; it defaults from the status. */
+export interface AppErrorOptions {
+    code?: string;
+    errors?: ErrorDetails;
+    retryable?: boolean;
+    retryAfterSeconds?: number;
+    cause?: unknown;
 }
+/**
+ * Shorthand for an error with an explicit status and code.
+ *
+ * @param statusCode HTTP status (4xx messages reach the caller; 5xx are replaced with a generic message).
+ * @param code UPPER_SNAKE_CASE machine-readable code, e.g. `SLUG_TAKEN`.
+ * @param message Human-readable message for 4xx responses.
+ * @param errors Optional field errors (`{ 'items.0.qty': ['Must be positive'] }`).
+ * @returns An {@link AppError} to `throw`.
+ * @example throw httpError(409, 'SLUG_TAKEN', 'That address is already in use');
+ */
+export declare function httpError(statusCode: number, code: string, message: string, errors?: ErrorDetails): AppError;
+/** 400 BAD_REQUEST: the request is malformed or breaks a business rule. */
 export declare class BadRequestError extends AppError {
     constructor(message?: string, options?: {
         code?: string;
         errors?: ErrorDetails;
     });
 }
+/** 401 UNAUTHENTICATED: no valid identity. */
 export declare class UnauthorizedError extends AppError {
     constructor(message?: string, options?: {
         code?: string;
     });
 }
+/** 403 FORBIDDEN: authenticated, but not allowed. */
 export declare class ForbiddenError extends AppError {
     constructor(message?: string, options?: {
         code?: string;
     });
 }
+/** 404 NOT_FOUND. Also use it for out-of-scope resources so their existence is not revealed. */
 export declare class NotFoundError extends AppError {
     constructor(message?: string, options?: {
         code?: string;
     });
 }
+/** 409 CONFLICT: duplicate or state conflict. */
 export declare class ConflictError extends AppError {
     constructor(message?: string, options?: {
         code?: string;
         errors?: ErrorDetails;
     });
 }
+/** 422 VALIDATION_FAILED with field errors (`{ 'items.0.qty': ['…'] }`). */
 export declare class ValidationError extends AppError {
     constructor(errors: ErrorDetails, message?: string);
 }
+/** 429. Pass `retryAfterSeconds` so the error middleware sets the `Retry-After` header. */
 export declare class TooManyRequestsError extends AppError {
     constructor(message?: string, options?: {
         code?: string;
+        retryAfterSeconds?: number;
     });
 }
+/** 503 SERVICE_UNAVAILABLE: a dependency is down. The message is logged, never sent (callers see the generic one). */
 export declare class ServiceUnavailableError extends AppError {
     constructor(message?: string, options?: {
         code?: string;
@@ -65,7 +96,17 @@ export declare class NonRetryableError extends AppError {
         cause?: unknown;
     });
 }
+/** Type guard for {@link AppError} (and its subclasses). */
 export declare function isAppError(error: unknown): error is AppError;
-/** Message safe to show a caller; hides internals for unexpected errors. */
+/** The message every 5xx response carries. */
+export declare const GENERIC_ERROR_MESSAGE = "Internal server error";
+/**
+ * Message safe to show a caller. Only 4xx AppErrors keep their own message; every 5xx (including
+ * 503s, whose messages often name upstreams or RPC methods) and every non-AppError get the generic one.
+ *
+ * @param error Anything thrown.
+ * @returns The message to put in the response body.
+ * @example publicMessage(new NotFoundError('Order not found')) // 'Order not found'
+ */
 export declare function publicMessage(error: unknown): string;
 //# sourceMappingURL=errors.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/common/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAEpD;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,YAAY,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAQ9I;AAgBD,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,SAAgB,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,YAAY,CAAA;KAAO;CAC5F;AACD,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,SAA4B,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;CACjF;AACD,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,SAAsD,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;CAC3G;AACD,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,SAAuB,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;CAC5E;AACD,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,SAA4B,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,YAAY,CAAA;KAAO;CACxG;AACD,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,MAAM,EAAE,YAAY,EAAE,OAAO,SAAsB;CAChE;AACD,qBAAa,oBAAqB,SAAQ,QAAQ;gBACpC,OAAO,SAA+C,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;CACpG;AACD,qBAAa,uBAAwB,SAAQ,QAAQ;gBACvC,OAAO,SAAoC,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAC1G;AAED,qFAAqF;AACrF,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAG9E;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIpD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/common/errors.ts"],"names":[],"mappings":"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"}

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

@@ -7,6 +7,10 @@ export * from './jwt.js';
 export * from './text.js';
 export * from './async.js';
 export * from './phone.js';
+export * from './money.js';
 export * from './time.js';
 export * from './audit.js';
+export * from './circuit-breaker.js';
+export * from './internal-service-auth.js';
+export * from './internal-client.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC"}

package/dist/types/common/internal-client.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Typed HTTP client base for service-to-service (`internal`) calls.
+ *
+ * Layer: plumbing for a service's `src/clients/{target}.client.ts`. Key rules:
+ * - Sends the caller's own credential (`x-internal-service-name` + `x-internal-service-secret`) on every call,
+ *   the current correlation id (INT-12) and, when given, the end user's signed identity headers unchanged.
+ * - Callers can tell "service down" from "service said no": network errors, timeouts, 5xx, unreadable bodies
+ *   and an open circuit all throw the target's `{Target}UnavailableError` (503); a 4xx throws an `AppError`
+ *   carrying the remote status, code, message and field errors.
+ * - Only GET is retried (default 2 retries, 100 ms then 400 ms back-off), and only for network errors,
+ *   timeouts and 502/503/504. Mutating calls are never retried here; they accept an idempotency key instead.
+ * - Each client owns one {@link CircuitBreaker}; a call that ends unavailable counts as a failure, any HTTP
+ *   answer below 500 counts as a success.
+ * - Secrets and header values are never logged; failure logs carry target, method, path and reason only.
+ */
+import type { ZodType } from 'zod';
+import { type CircuitBreakerOptions, type CircuitState } from './circuit-breaker.js';
+import { ServiceUnavailableError } from './errors.js';
+import { type InternalCallerCredential } from './internal-service-auth.js';
+import type { Logger } from '../types/index.js';
+/** An unavailable-error class bound to one target service. Instances are 503 `ServiceUnavailableError`s. */
+export type UnavailableErrorClass = new (message?: string, options?: {
+    cause?: unknown;
+}) => ServiceUnavailableError & {
+    readonly target: string;
+};
+/**
+ * Returns the `{Target}UnavailableError` class for a target service (the same class on every call, so
+ * `instanceof` works anywhere in the process).
+ *
+ * @param target The target service name, e.g. `records-service`.
+ * @returns A class named e.g. `RecordsServiceUnavailableError`, extending `ServiceUnavailableError` (503).
+ * @example
+ * const RecordsUnavailable = makeUnavailableError('records-service');
+ * try { await records.get('/records/1'); } catch (e) { if (e instanceof RecordsUnavailable) useCachedCopy(); }
+ */
+export declare function makeUnavailableError(target: string): UnavailableErrorClass;
+/** Settings for {@link createInternalClient}. */
+export interface InternalClientOptions {
+    /** Target service name (compose name), e.g. `records-service`; names the unavailable error. */
+    target: string;
+    /** Target base URL on the private network, e.g. `http://records-service:4000/internal`. */
+    baseUrl: string;
+    /** This service's name and secret; defaults to env `INTERNAL_SERVICE_NAME` / `INTERNAL_SERVICE_CREDENTIAL`. */
+    caller?: InternalCallerCredential;
+    /** Per-attempt timeout (default 3000 ms). */
+    timeoutMs?: number;
+    /** Extra attempts for GET (default 2). */
+    retries?: number;
+    /** Delay before retry n (1-based) is `backoffMs[n-1]`, the last value repeating (default `[100, 400]`). */
+    backoffMs?: readonly number[];
+    /** Breaker settings (default `{ failureThreshold: 5, resetAfterMs: 30000 }`). */
+    breaker?: CircuitBreakerOptions;
+    /** Receives a warning per unavailable call (target, method, path, reason). */
+    logger?: Logger;
+    /** Fetch implementation, for tests (default global `fetch`). */
+    fetch?: typeof fetch;
+}
+/** Options for one call. */
+export interface InternalRequestOptions<T = unknown> {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /** Overrides the correlation id taken from the request context. */
+    correlationId?: string;
+    /**
+     * The end user's gateway identity headers, forwarded unchanged. Gateway signatures are bound to method and
+     * path, so a service acting for a user re-signs them for this exact call with `signedIdentityHeaders`.
+     */
+    identityHeaders?: Record<string, string>;
+    /** Sent as `idempotency-key` so the target can dedupe a mutating call the caller repeats. */
+    idempotencyKey?: string;
+    /** Overrides the client's per-attempt timeout. */
+    timeoutMs?: number;
+    /** Validates the unwrapped `data`; a mismatch throws the unavailable error (the contract is broken). */
+    schema?: ZodType<T>;
+}
+/** A client bound to one target service. */
+export interface InternalClient {
+    readonly target: string;
+    /** This target's unavailable error class, for `instanceof` checks. */
+    readonly UnavailableError: UnavailableErrorClass;
+    /** Current breaker state, for health and metrics. */
+    readonly circuitState: CircuitState;
+    /**
+     * Sends one call to the target. `get` is retried on transient failures; `post`/`put`/`patch`/`delete` never are.
+     *
+     * @param path Path under `baseUrl`, e.g. `/records/01J…`.
+     * @param options Query, body, correlation/identity headers, idempotency key, timeout and response schema.
+     * @returns The unwrapped `data` of the target's success envelope (validated when `schema` is given).
+     * @throws `{Target}UnavailableError` (503) when the target is down, slow, answers 5xx, sends an unreadable or
+     *   schema-mismatched body, or the circuit is open; `AppError` with the remote status/code for a 4xx.
+     * @example const record = await records.get('/records/01J…', { schema: recordSchema });
+     */
+    get<T>(path: string, options?: InternalRequestOptions<T>): Promise<T>;
+    /** Same as {@link InternalClient.get}, never retried; pass `idempotencyKey` so the target can dedupe a repeat. */
+    post<T>(path: string, options?: InternalRequestOptions<T>): Promise<T>;
+    /** Same as {@link InternalClient.post}. */
+    put<T>(path: string, options?: InternalRequestOptions<T>): Promise<T>;
+    /** Same as {@link InternalClient.post}. */
+    patch<T>(path: string, options?: InternalRequestOptions<T>): Promise<T>;
+    /** Same as {@link InternalClient.post}. */
+    delete<T>(path: string, options?: InternalRequestOptions<T>): Promise<T>;
+}
+/**
+ * Creates a client for one target service.
+ *
+ * @param options Target, base URL, caller credential, timeout, retry, breaker and logger settings.
+ * @returns An {@link InternalClient}.
+ * @throws ConfigError when the caller name or credential is missing.
+ * @example
+ * // src/clients/records.client.ts
+ * const http = createInternalClient({ target: 'records-service', baseUrl: config.RECORDS_INTERNAL_URL, logger });
+ * export const getRecord = (id: string) => http.get(`/records/${id}`, { schema: recordSchema });
+ */
+export declare function createInternalClient(options: InternalClientOptions): InternalClient;
+//# sourceMappingURL=internal-client.d.ts.map

package/dist/types/common/internal-client.d.ts.map

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

package/dist/types/common/internal-constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Leaf constants for internal-service auth, shared by `common/internal-service-auth` and the `config` env blocks
+ * (kept dependency-free so neither module imports the other).
+ */
+/** Shortest internal credential accepted in staging and production. */
+export declare const MIN_INTERNAL_CREDENTIAL_LENGTH = 32;
+/** Service names are compose-style: lower-case letters, digits and hyphens, starting with a letter. */
+export declare const SERVICE_NAME_PATTERN: RegExp;
+//# sourceMappingURL=internal-constants.d.ts.map

package/dist/types/common/internal-constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-constants.d.ts","sourceRoot":"","sources":["../../../src/common/internal-constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,uEAAuE;AACvE,eAAO,MAAM,8BAA8B,KAAK,CAAC;AACjD,uGAAuG;AACvG,eAAO,MAAM,oBAAoB,QAA2B,CAAC"}

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

@@ -1,10 +1,49 @@
 /**
- * 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 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 (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 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', 'US') // 'GB'
+ */
+export declare function phoneRegion(phone: string, region: string): string | 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 declare function toE164(phone: string, defaultRegion?: string): string | null;
-/** E.164 without the plus sign, as most SMS gateways expect (`254712345678`). */
-export declare function toMsisdn(phone: string, defaultRegion?: string): string | null;
-export declare function phoneRegion(phone: string, defaultRegion?: string): string | null;
 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;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,SAAO,GAAG,MAAM,GAAG,IAAI,CAOzE;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,SAAO,GAAG,MAAM,GAAG,IAAI,CAG3E;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,SAAO,GAAG,MAAM,GAAG,IAAI,CAM9E;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/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"}