@heavybit/shared-lib 0.0.0-stage → 1.1.0

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

@@ -0,0 +1,50 @@
+import type { AuthUser } from '../types/index.js';
+/**
+ * Permission and ownership checks. Keep every authorization decision in these helpers (not
+ * inline in controllers) so the rules are identical across endpoints and services.
+ *
+ * Permission strings are dotted (`users.manage`, `media.manage.any`). Grants may use
+ * wildcards: `*` grants everything; `media.*` grants any permission starting with `media.`.
+ */
+export declare const WILDCARD_PERMISSION = "*";
+/** True when the user holds at least one of `required`. */
+export declare function hasPermission(user: Pick<AuthUser, 'permissions'> | null | undefined, ...required: string[]): boolean;
+export declare function hasAllPermissions(user: Pick<AuthUser, 'permissions'> | null | undefined, ...required: string[]): boolean;
+export declare function hasRole(user: Pick<AuthUser, 'roles'> | null | undefined, ...roles: string[]): boolean;
+export declare function requireUser(user: AuthUser | null | undefined): AuthUser;
+export declare function assertPermission(user: AuthUser | null | undefined, ...required: string[]): AuthUser;
+/** IDs the user may act on within a scope (e.g. profiles they are a member of). */
+export declare function scopeIds(user: Pick<AuthUser, 'scopes'> | null | undefined, scope: string): string[];
+/**
+ * Self-owned data: allow when the caller *is* `ownerUserId`, or holds `bypassPermission`.
+ * Throws ForbiddenError otherwise.
+ */
+export declare function assertSelfOrPermission(user: AuthUser | null | undefined, ownerUserId: string, bypassPermission?: string): AuthUser;
+/**
+ * Scoped data: allow when `resourceScopeId` is one of the caller's scope IDs, or the caller holds
+ * `bypassPermission`.
+ */
+export declare function assertInScope(user: AuthUser | null | undefined, scope: string, resourceScopeId: string, bypassPermission?: string): AuthUser;
+/**
+ * Resolves the single scope ID a request acts on. With one membership it is implicit; with
+ * several the client names one (e.g. `x-active-profile-id`), which must be a member ID.
+ * IDs from request bodies are never trusted — only the gateway-signed scopes.
+ */
+export declare function resolveActiveScopeId(user: AuthUser | null | undefined, scope: string, requested?: string | null): string;
+/**
+ * Like `resolveActiveScopeId`, for screens that work without a selector: with several memberships
+ * and none named, the first (primary) one is used. A named ID must still be a member ID.
+ */
+export declare function resolvePrimaryScopeId(user: AuthUser | null | undefined, scope: string, requested?: string | null): string;
+export type OwnerFilter = {
+    all: true;
+} | {
+    all: false;
+    ids: string[];
+};
+/**
+ * Repository filter for list queries: `{ all: true }` for callers holding `bypassPermission`,
+ * otherwise the caller's own scope IDs (possibly empty → return nothing).
+ */
+export declare function ownerFilter(user: AuthUser | null | undefined, scope: string, bypassPermission?: string): OwnerFilter;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/access/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAOvC,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAGpH;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAGxH;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAErG;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,GAAG,QAAQ,CAGvE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,QAAQ,CAInG;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAEnG;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,QAAQ,CAKlI;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,QAAQ,CAK5I;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CASxH;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGzH;AAED,MAAM,MAAM,WAAW,GAAG;IAAE,GAAG,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAExE;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,WAAW,CAIpH"}

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

@@ -0,0 +1,43 @@
+import type { Logger } from '../types/index.js';
+/** Sends operator alerts (DLQ depth, stalled queues…). Never throws: alerting must not break its caller. */
+export interface AlertSender {
+    /** True when the alert was accepted; false when it was not sent (not configured, or the hook failed). */
+    send(messages: string[], options?: {
+        alertType?: string;
+    }): Promise<boolean>;
+}
+/** The body the platform's Slack notification app accepts (the same one `health-monitor.sh` posts). */
+export interface SlackAlertPayload {
+    messages: string[];
+    alert_type: string;
+    app_name: string;
+    environment: string;
+    consolidate: boolean;
+}
+export interface SlackAlerterOptions {
+    /** The notification app's URL. Empty = not configured: alerts are logged and skipped. */
+    url: string;
+    /** Product name shown on the alert, e.g. `Showbiz`. */
+    app: string;
+    /** `staging`, `production`… */
+    environment: string;
+    logger?: Logger;
+    timeoutMs?: number;
+    /** Injected in tests; defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * Posts alerts to a Slack notification webhook as `{ messages, alert_type, app_name, environment, consolidate }`.
+ * An unset URL is a valid "alerts off" configuration: the first skipped alert is warned about once, then silently.
+ */
+export declare class SlackAlerter implements AlertSender {
+    private readonly options;
+    private warnedUnconfigured;
+    private readonly logger;
+    constructor(options: SlackAlerterOptions);
+    get configured(): boolean;
+    send(messages: string[], options?: {
+        alertType?: string;
+    }): Promise<boolean>;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/alerting/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,4GAA4G;AAC5G,MAAM,WAAW,WAAW;IAC1B,yGAAyG;IACzG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9E;AAED,uGAAuG;AACvG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;GAGG;AACH,qBAAa,YAAa,YAAW,WAAW;IAIlC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEH,OAAO,EAAE,mBAAmB;IAIzD,IAAI,UAAU,IAAI,OAAO,CAExB;IAEK,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CAgCvF"}

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

@@ -0,0 +1,45 @@
+import { Redis, type RedisOptions } from 'ioredis';
+import type { Logger } from '../types/index.js';
+export interface CacheSetOptions {
+    ttlSec?: number;
+    /** Tags let one call invalidate every key derived from an entity (e.g. `user:01J…`). */
+    tags?: string[];
+}
+export interface Cache {
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    del(...keys: string[]): Promise<void>;
+    /** Cache-aside: returns the cached value or loads, stores and returns it. Concurrent misses share one load. */
+    wrap<T>(key: string, loader: () => Promise<T>, options?: CacheSetOptions & {
+        cacheNull?: boolean;
+    }): Promise<T>;
+    invalidateTags(...tags: string[]): Promise<void>;
+}
+export interface CacheOptions {
+    /** Null → in-memory only (tests, local tooling). */
+    redis: Redis | null;
+    /** Key namespace, e.g. `auth` → keys `auth:<key>`. Combine with the client-level env prefix. */
+    namespace: string;
+    defaultTtlSec?: number;
+    /** Upper bound for the in-memory layer / fallback. */
+    memoryMaxEntries?: number;
+    logger?: Logger;
+}
+/**
+ * Redis-backed cache with tag invalidation. If Redis errors, reads fall through to the loader
+ * and writes go to a bounded in-memory store, so a cache outage degrades latency rather than
+ * availability.
+ */
+export declare function createCache(options: CacheOptions): Cache;
+export interface RedisClientOptions {
+    url?: string;
+    db?: number;
+    /** Prepended to every key by ioredis, e.g. `showbiz:prod:`. */
+    keyPrefix?: string;
+    logger?: Logger;
+    options?: RedisOptions;
+}
+/** ioredis client that never crashes the process on connection errors and retries forever. */
+export declare function createRedisClient(opts: RedisClientOptions): Redis;
+export type { Redis };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAEnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,KAAK;IACpB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC5C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,GAAG,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,+GAA+G;IAC/G,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChH,cAAc,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,gGAAgG;IAChG,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA+BD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,CA+FxD;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,KAAK,CAmBjE;AAED,YAAY,EAAE,KAAK,EAAE,CAAC"}

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

@@ -0,0 +1,14 @@
+export declare const sleep: (ms: number) => Promise<void>;
+export interface RetryOptions {
+    retries: number;
+    /** Delay before attempt n (1-based retry number). Default: 200ms × 2^(n-1), capped at 5s. */
+    delayMs?: (attempt: number) => number;
+    shouldRetry?: (error: unknown) => boolean;
+}
+/** Runs `fn`, retrying failures with exponential back-off. */
+export declare function retry<T>(fn: (attempt: number) => Promise<T>, options: RetryOptions): Promise<T>;
+/** Rejects with `onTimeout()` if `promise` does not settle within `ms`. */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, onTimeout: () => Error): Promise<T>;
+/** Splits `items` into arrays of at most `size`. */
+export declare function chunk<T>(items: readonly T[], size: number): T[][];
+//# sourceMappingURL=async.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../../../src/common/async.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,KAAK,GAAI,IAAI,MAAM,KAAG,OAAO,CAAC,IAAI,CAAsD,CAAC;AAEtG,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACtC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CAC3C;AAED,8DAA8D;AAC9D,wBAAsB,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAYrG;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAMlG;AAED,oDAAoD;AACpD,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAIjE"}

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

@@ -0,0 +1,17 @@
+export type AuditAction = 'create' | 'update' | 'delete';
+type AuditRow<T> = Omit<T, 'id' | 'createdAt' | 'updatedAt'> & {
+    id: string;
+    parentId: string;
+    action: AuditAction;
+};
+/**
+ * Builds the row for a `*_audits` sibling table: a copy of the parent row plus `action`,
+ * `parentId`, and a fresh `id`. The parent's timestamps are dropped so the audit row records
+ * when the change happened. The actor lands in `createdBy`/`updatedBy` exactly as on the parent
+ * (null for system operations). Strip secrets (e.g. password hashes) before calling.
+ */
+export declare function buildAuditRow<T extends {
+    id: string;
+}>(row: T, action: AuditAction, actorId?: string | null): AuditRow<T>;
+export {};
+//# sourceMappingURL=audit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/common/audit.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEzD,KAAK,QAAQ,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC;AAErH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,MAAM,GAAG,IAAW,GAAG,QAAQ,CAAC,CAAC,CAAC,CAS/H"}

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

@@ -0,0 +1,18 @@
+export declare function sha256(value: string | Buffer): string;
+export declare function hmacSha256(secret: string | Buffer, value: string): string;
+/** Constant-time string comparison (false when lengths differ). */
+export declare function safeEqual(a: string, b: string): boolean;
+/** URL-safe random token (default 32 bytes of entropy). */
+export declare function randomToken(bytes?: number): string;
+/** Numeric one-time code, e.g. `'042917'`. Uses a CSPRNG. */
+export declare function randomNumericCode(length?: number): string;
+/**
+ * Hash a value that must be looked up later (refresh tokens, reset tokens, OTPs) with a
+ * server-side pepper so a database leak alone cannot be replayed.
+ */
+export declare function hashToken(token: string, pepper: string): string;
+/** AES-256-GCM encrypt. Output: `v1:<iv>:<tag>:<ciphertext>` (base64url parts). */
+export declare function encryptSecret(plaintext: string, key: string): string;
+export declare function decryptSecret(payload: string, key: string): string;
+export declare function isEncryptedSecret(value: unknown): value is string;
+//# sourceMappingURL=crypto.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../../src/common/crypto.ts"],"names":[],"mappings":"AAEA,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAErD;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAIvD;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,KAAK,SAAK,GAAG,MAAM,CAE9C;AAED,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,MAAM,SAAI,GAAG,MAAM,CAIpD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE/D;AAcD,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAMpE;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAQlE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEjE"}

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

@@ -0,0 +1,71 @@
+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.
+ */
+export declare class AppError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    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;
+    });
+}
+export declare class BadRequestError extends AppError {
+    constructor(message?: string, options?: {
+        code?: string;
+        errors?: ErrorDetails;
+    });
+}
+export declare class UnauthorizedError extends AppError {
+    constructor(message?: string, options?: {
+        code?: string;
+    });
+}
+export declare class ForbiddenError extends AppError {
+    constructor(message?: string, options?: {
+        code?: string;
+    });
+}
+export declare class NotFoundError extends AppError {
+    constructor(message?: string, options?: {
+        code?: string;
+    });
+}
+export declare class ConflictError extends AppError {
+    constructor(message?: string, options?: {
+        code?: string;
+        errors?: ErrorDetails;
+    });
+}
+export declare class ValidationError extends AppError {
+    constructor(errors: ErrorDetails, message?: string);
+}
+export declare class TooManyRequestsError extends AppError {
+    constructor(message?: string, options?: {
+        code?: string;
+    });
+}
+export declare class ServiceUnavailableError extends AppError {
+    constructor(message?: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+/** A failure that will never succeed on retry (bad payload, unknown template, …). */
+export declare class NonRetryableError extends AppError {
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+export declare function isAppError(error: unknown): error is AppError;
+/** Message safe to show a caller; hides internals for unexpected errors. */
+export declare function publicMessage(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,14 @@
+export declare const ID_LENGTH = 26;
+export declare const ID_PATTERN: RegExp;
+/** A new time-ordered, monotonic ULID. */
+export declare function newId(): string;
+export declare function isId(value: unknown): value is string;
+/** Creation time encoded in a ULID. */
+export declare function idTimestamp(id: string): Date;
+/**
+ * A stable, valid ID for seed/fixture rows: the same `(namespace, n)` always yields the same ID, so
+ * seeds in different services can reference each other's rows without sharing a database.
+ * `namespace` is two Crockford characters (e.g. `PR` for profiles).
+ */
+export declare function fixtureId(namespace: string, n: number): string;
+//# sourceMappingURL=id.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../../src/common/id.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,SAAS,KAAK,CAAC;AAC5B,eAAO,MAAM,UAAU,QAA6B,CAAC;AAErD,0CAA0C;AAC1C,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEpD;AAED,uCAAuC;AACvC,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE5C;AAID;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAI9D"}

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

@@ -0,0 +1,12 @@
+export * from './id.js';
+export * from './errors.js';
+export * from './response.js';
+export * from './crypto.js';
+export * from './password.js';
+export * from './jwt.js';
+export * from './text.js';
+export * from './async.js';
+export * from './phone.js';
+export * from './time.js';
+export * from './audit.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,28 @@
+export interface JwtSignOptions {
+    expiresIn: string | number;
+    issuer?: string;
+    audience?: string;
+    jwtId?: string;
+}
+export interface JwtVerifyOptions {
+    issuer?: string;
+    audience?: string;
+}
+/** Registered claims plus custom ones. Declared here so consumers never need `@types/jsonwebtoken`. */
+export interface JwtClaims {
+    sub: string;
+    iat?: number;
+    exp?: number;
+    iss?: string;
+    aud?: string | string[];
+    jti?: string;
+    [claim: string]: unknown;
+}
+export declare function signJwt(payload: Record<string, unknown>, secret: string, options: JwtSignOptions): string;
+/** Verifies signature, expiry and (when given) issuer/audience. Throws on any failure. */
+export declare function verifyJwt<T extends JwtClaims = JwtClaims>(token: string, secret: string, options?: JwtVerifyOptions): T;
+export declare function decodeJwt<T extends JwtClaims = JwtClaims>(token: string): T | null;
+export declare function extractBearerToken(header?: string | null): string | null;
+/** Converts `'15m'`, `'30d'`, `3600` into seconds. */
+export declare function durationToSeconds(value: string | number): number;
+//# sourceMappingURL=jwt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../../src/common/jwt.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,uGAAuG;AACvG,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,CAQzG;AAED,0FAA0F;AAC1F,wBAAgB,SAAS,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,CAAC,CAQ3H;AAED,wBAAgB,SAAS,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAGlF;AAED,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAIxE;AAED,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAahE"}

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

@@ -0,0 +1,4 @@
+export declare function hashPassword(password: string): Promise<string>;
+export declare function verifyPassword(password: string, hash: string | null | undefined): Promise<boolean>;
+export declare function needsRehash(hash: string): boolean;
+//# sourceMappingURL=password.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"password.d.ts","sourceRoot":"","sources":["../../../src/common/password.ts"],"names":[],"mappings":"AAYA,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEpE;AAED,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAQxG;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGjD"}

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

@@ -0,0 +1,10 @@
+/**
+ * Normalises a phone number to E.164 (`+254712345678`). Returns null for anything that is not a
+ * valid number for the given default region.
+ */
+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

@@ -0,0 +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"}

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

@@ -0,0 +1,12 @@
+import type { ApiResponse, PaginationMeta, PaginatedResult } from '../types/index.js';
+/** Standard success envelope: `{ success, message, data }`. */
+export declare function successResponse<T>(data: T, message?: string): ApiResponse<T>;
+/** Standard error envelope: `{ success: false, message, code?, errors? }`. */
+export declare function errorResponse(message: string, errors?: Record<string, string[]>, code?: string): ApiResponse<never>;
+export declare function buildPaginationMeta(total: number, page: number, limit: number): PaginationMeta;
+/** Paginated envelope: `{ success, message, data: T[], meta }`. */
+export declare function paginatedResponse<T>(data: T[], total: number, page: number, limit: number, message?: string): ApiResponse<T[]>;
+export declare function buildPaginatedResult<T>(data: T[], total: number, page: number, limit: number): PaginatedResult<T>;
+/** SQL offset for 1-based pages. */
+export declare function pageOffset(page: number, limit: number): number;
+//# sourceMappingURL=response.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../../src/common/response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEtF,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,SAAY,GAAG,WAAW,CAAC,CAAC,CAAC,CAE/E;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAEnH;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAG9F;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,SAAY,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAEjI;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,CAEjH;AAED,oCAAoC;AACpC,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D"}

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

@@ -0,0 +1,10 @@
+/** URL slug: lowercase ASCII, dash-separated, accents folded. */
+export declare function slugify(value: string, maxLength?: number): string;
+/** Replaces `{{ name }}` placeholders; unknown names become empty strings. */
+export declare function interpolate(template: string, variables: Record<string, unknown>, escape?: (value: string) => string): string;
+/** Placeholder names used by a template, e.g. `['user.name', 'code']`. */
+export declare function templateVariables(template: string): string[];
+export declare function escapeHtml(value: string): string;
+/** `jane.doe@example.com` → `ja***@example.com` for logs and audit trails. */
+export declare function maskEmail(email: string): string;
+//# sourceMappingURL=text.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../../src/common/text.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,SAAK,GAAG,MAAM,CAU7D;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAM5H;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAI5D;AAID,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI/C"}

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

@@ -0,0 +1,40 @@
+/** True for IANA zones the runtime knows (`Africa/Nairobi`), 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;
+export interface ZonedText {
+    /** The formatted instant, e.g. `30 Sep 2026, 14:05 EAT`; empty when the instant is not a valid date. */
+    text: string;
+    /** The zone actually used. */
+    timezone: string;
+    /** True when `zone` was missing or invalid and `fallbackZone` was used instead. */
+    usedFallback: boolean;
+}
+/**
+ * Formats an instant for a person in their zone, falling back to `fallbackZone` (itself falling back to
+ * UTC) when theirs is missing or unknown. Never throws, and says when it fell back so callers can log it.
+ */
+export declare function formatInstantInZone(instant: Date | string | number, zone: unknown, fallbackZone?: string, locale?: string): ZonedText;
+/** Offset of `zone` from UTC in minutes at `at` (positive east of Greenwich). */
+export declare function timeZoneOffsetMinutes(zone: string, at?: Date): number;
+export declare const addSeconds: (date: Date, seconds: number) => Date;
+export declare const addMinutes: (date: Date, minutes: number) => Date;
+/** Minutes since midnight of a 24-hour `HH:MM` clock time. Throws on anything else (never guesses). */
+export declare function parseClockTime(value: string): number;
+/**
+ * The instant a wall-clock time occurs in `zone` (month is 0-based; an overflowing day rolls over).
+ * The offset is read again at the first estimate, so the result is right across a DST change; a wall
+ * 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). */
+export declare function zonedDayBounds(at: Date, zone: string): {
+    start: Date;
+    end: Date;
+};
+/**
+ * When `at` falls inside the daily window `[start, end)` (local `HH:MM` times in `zone`; the window may
+ * 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;
+//# sourceMappingURL=time.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,115 @@
+import { z } from 'zod';
+/**
+ * Environment building blocks. Services compose the pieces they need:
+ *
+ *   const env = loadEnv(serviceEnv.merge(databaseEnv).merge(messagingEnv).extend({ MY_VAR: z.string() }));
+ */
+export declare const serviceEnv: z.ZodObject<{
+    NODE_ENV: z.ZodDefault<z.ZodEnum<["development", "test", "staging", "production"]>>;
+    PORT: z.ZodNumber;
+    SERVICE_NAME: z.ZodString;
+    /** Short app identifier used in exchange names and key prefixes (e.g. `showbiz`). */
+    APP_NAME: z.ZodDefault<z.ZodString>;
+    LOG_LEVEL: z.ZodOptional<z.ZodEnum<["error", "warn", "info", "http", "debug"]>>;
+    CORS_ORIGINS: z.ZodDefault<z.ZodString>;
+    /** Verifies gateway-signed identity headers. */
+    GATEWAY_SHARED_SECRET: z.ZodString;
+    /** Authenticates service-to-service `/internal/*` calls. */
+    INTERNAL_SERVICE_SECRET: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    NODE_ENV: "production" | "test" | "development" | "staging";
+    PORT: number;
+    SERVICE_NAME: string;
+    APP_NAME: string;
+    CORS_ORIGINS: string;
+    GATEWAY_SHARED_SECRET: string;
+    INTERNAL_SERVICE_SECRET: string;
+    LOG_LEVEL?: "info" | "debug" | "error" | "warn" | "http" | undefined;
+}, {
+    PORT: number;
+    SERVICE_NAME: string;
+    GATEWAY_SHARED_SECRET: string;
+    INTERNAL_SERVICE_SECRET: string;
+    NODE_ENV?: "production" | "test" | "development" | "staging" | undefined;
+    LOG_LEVEL?: "info" | "debug" | "error" | "warn" | "http" | undefined;
+    APP_NAME?: string | undefined;
+    CORS_ORIGINS?: string | undefined;
+}>;
+export declare const databaseEnv: z.ZodObject<{
+    DB_HOST: z.ZodDefault<z.ZodString>;
+    DB_PORT: z.ZodDefault<z.ZodNumber>;
+    DB_USER: z.ZodDefault<z.ZodString>;
+    DB_PASSWORD: z.ZodDefault<z.ZodString>;
+    DB_NAME: z.ZodString;
+    DB_POOL_MAX: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    DB_HOST: string;
+    DB_PORT: number;
+    DB_USER: string;
+    DB_PASSWORD: string;
+    DB_NAME: string;
+    DB_POOL_MAX: number;
+}, {
+    DB_NAME: string;
+    DB_HOST?: string | undefined;
+    DB_PORT?: number | undefined;
+    DB_USER?: string | undefined;
+    DB_PASSWORD?: string | undefined;
+    DB_POOL_MAX?: number | undefined;
+}>;
+export declare const messagingEnv: z.ZodObject<{
+    RABBITMQ_URL: z.ZodOptional<z.ZodString>;
+    RABBITMQ_HOST: z.ZodDefault<z.ZodString>;
+    RABBITMQ_PORT: z.ZodDefault<z.ZodNumber>;
+    RABBITMQ_USERNAME: z.ZodDefault<z.ZodString>;
+    RABBITMQ_PASSWORD: z.ZodDefault<z.ZodString>;
+    RABBITMQ_VHOST: z.ZodDefault<z.ZodString>;
+    /** Environment prefix for queue and exchange names (`dev`, `staging`, `prod`). */
+    QUEUE_PREFIX: z.ZodDefault<z.ZodString>;
+    RABBITMQ_ENABLED: z.ZodEffects<z.ZodDefault<z.ZodEnum<["true", "false"]>>, boolean, "true" | "false" | undefined>;
+}, "strip", z.ZodTypeAny, {
+    RABBITMQ_HOST: string;
+    RABBITMQ_PORT: number;
+    RABBITMQ_USERNAME: string;
+    RABBITMQ_PASSWORD: string;
+    RABBITMQ_VHOST: string;
+    QUEUE_PREFIX: string;
+    RABBITMQ_ENABLED: boolean;
+    RABBITMQ_URL?: string | undefined;
+}, {
+    RABBITMQ_URL?: string | undefined;
+    RABBITMQ_HOST?: string | undefined;
+    RABBITMQ_PORT?: number | undefined;
+    RABBITMQ_USERNAME?: string | undefined;
+    RABBITMQ_PASSWORD?: string | undefined;
+    RABBITMQ_VHOST?: string | undefined;
+    QUEUE_PREFIX?: string | undefined;
+    RABBITMQ_ENABLED?: "true" | "false" | undefined;
+}>;
+export declare const redisEnv: z.ZodObject<{
+    REDIS_URL: z.ZodOptional<z.ZodString>;
+    REDIS_DB: z.ZodDefault<z.ZodNumber>;
+    /** Key prefix, e.g. `app:dev:` — never share one between apps or environments. */
+    REDIS_PREFIX: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    REDIS_DB: number;
+    REDIS_PREFIX: string;
+    REDIS_URL?: string | undefined;
+}, {
+    REDIS_URL?: string | undefined;
+    REDIS_DB?: number | undefined;
+    REDIS_PREFIX?: string | undefined;
+}>;
+/** Builds an AMQP URL from discrete env vars (or returns RABBITMQ_URL when set). */
+export declare function amqpUrlFromEnv(env: z.infer<typeof messagingEnv>): string;
+/** Reads `KEY=value` lines from a dotenv file into process.env without overriding set values. */
+export declare function loadDotEnv(path?: string): void;
+export declare class ConfigError extends Error {
+}
+/** Loads `.env` (if present) and validates process.env. Throws ConfigError listing every problem. */
+export declare function loadEnv<S extends z.ZodTypeAny>(schema: S, source?: NodeJS.ProcessEnv, options?: {
+    dotenv?: boolean;
+}): z.infer<S>;
+/** Comma-separated env value → trimmed, non-empty list. */
+export declare const listFromEnv: (value: string | undefined) => string[];
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/config/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;;IAIrB,qFAAqF;;;;IAIrF,gDAAgD;;IAEhD,4DAA4D;;;;;;;;;;;;;;;;;;;;EAE5D,CAAC;AAEH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;EAOtB,CAAC;AAEH,eAAO,MAAM,YAAY;;;;;;;IAOvB,kFAAkF;;;;;;;;;;;;;;;;;;;;;EAGlF,CAAC;AAEH,eAAO,MAAM,QAAQ;;;IAGnB,kFAAkF;;;;;;;;;;EAElF,CAAC;AAEH,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,GAAG,MAAM,CAIxE;AAED,iGAAiG;AACjG,wBAAgB,UAAU,CAAC,IAAI,SAAiC,GAAG,IAAI,CAYtE;AAED,qBAAa,WAAY,SAAQ,KAAK;CAAG;AAEzC,qGAAqG;AACrG,wBAAgB,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAE,MAAM,CAAC,UAAwB,EAAE,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAQlJ;AAED,2DAA2D;AAC3D,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,MAAM,EAAmE,CAAC"}