@heavybit/shared-lib 1.3.2 → 2.7.0

package/dist/esm/testing/index.js

@@ -1,5 +1,5 @@
 import { newId } from '../common/id.js';
-import { signIdentityHeaders } from '../identity/index.js';
+import { signedIdentityHeaders } from '../identity/index.js';
 import { buildEnvelope } from '../messaging/envelope.js';
 /** A logger spy: records every line (level, message, meta) so tests can assert on log context. */
 export class RecordingLogger {
@@ -13,24 +13,26 @@ export class RecordingLogger {
 export function makeAuthUser(overrides = {}) {
     return { id: newId(), email: 'user@example.com', roles: [], permissions: [], scopes: {}, attrs: {}, ...overrides };
 }
-/** Gateway-signed identity headers for route tests (use with supertest `.set()`). */
-export function identityHeaders(user, secret) {
-    return signIdentityHeaders(user, secret);
+/**
+ * Gateway-signed (v2) identity headers for route tests (use with supertest `.set()`). The method and path
+ * must match the request the test sends.
+ *
+ * @example request(app).get('/v1/items').set(identityHeaders({ user, secret, protocol, method: 'GET', path: '/v1/items' }));
+ */
+export function identityHeaders(input) {
+    return signedIdentityHeaders(input);
 }
-/** Records everything published/sent so tests can assert on events, commands and direct queue sends. */
+/** Records everything published/sent so tests can assert on events, commands, queue sends and delayed sends. */
 export class RecordingBus {
-    source;
     events = [];
     commands = [];
     queued = [];
+    delayed = [];
     failWith = null;
-    constructor(source = 'test') {
-        this.source = source;
-    }
-    async publish(type, data, meta) {
+    async publish(routingKey, data, meta) {
         if (this.failWith)
             throw this.failWith;
-        const envelope = buildEnvelope(type, data, this.source, meta);
+        const envelope = buildEnvelope(routingKey, data, meta);
         this.events.push(envelope);
         return envelope;
     }
@@ -42,7 +44,7 @@ export class RecordingBus {
     async send(command, data, meta) {
         if (this.failWith)
             throw this.failWith;
-        const envelope = buildEnvelope(command, data, this.source, meta);
+        const envelope = buildEnvelope(command, data, meta);
         this.commands.push(envelope);
         return envelope;
     }
@@ -56,11 +58,18 @@ export class RecordingBus {
             throw this.failWith;
         this.queued.push({ queue, payload, options });
     }
-    eventsOfType(type) {
-        return this.events.filter((e) => e.type === type);
+    async scheduleDelayed(queue, payload, delayMs, options = {}) {
+        if (this.failWith)
+            throw this.failWith;
+        this.delayed.push({ queue, payload, delayMs, options });
+    }
+    /** Published events with this routing key. */
+    eventsOfType(routingKey) {
+        return this.events.filter((e) => e.routingKey === routingKey);
     }
+    /** Sent commands with this name. */
     commandsOfType(command) {
-        return this.commands.filter((e) => e.type === command);
+        return this.commands.filter((e) => e.routingKey === command);
     }
 }
 //# sourceMappingURL=index.js.map

package/dist/esm/testing/index.js.map

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

package/dist/esm/validation/index.js

@@ -1,14 +1,25 @@
 import { z } from 'zod';
 import { ID_PATTERN } from '../common/id.js';
 import { ValidationError } from '../common/errors.js';
+/** A ULID in canonical form (26 upper-case Crockford base32 chars), as `newId()` makes and `CHAR(26)` stores. */
 export const idSchema = z.string().regex(ID_PATTERN, 'Invalid id');
+/** Route params `{ id }` where `id` is a canonical ULID. Use with `validate({ params: idParamSchema })`. */
 export const idParamSchema = z.object({ id: idSchema });
+/**
+ * Alias of {@link idParamSchema} for `validate({ params: idParam })`. Stricter than `z.string().ulid()`:
+ * lower-case ULIDs are rejected, so a lookup never misses a stored upper-case id.
+ */
+export const idParam = idParamSchema;
+/** Offset pagination query: `page` ≥ 1 (default 1), `limit` 1–100 (default 20). Prefer cursor pagination (D6). */
 export const paginationSchema = z.object({
     page: z.coerce.number().int().min(1).default(1),
     limit: z.coerce.number().int().min(1).max(100).default(20),
 });
+/** `asc` or `desc`, default `desc`. */
 export const sortOrderSchema = z.enum(['asc', 'desc']).default('desc');
+/** Trimmed, lower-cased email address, max 191 chars. */
 export const emailSchema = z.string().trim().toLowerCase().email('Invalid email address').max(191);
+/** Lower-case kebab-case slug, 1–120 chars. */
 export const slugSchema = z.string().trim().min(1).max(120).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'Invalid slug');
 /** Length-first password rule (NIST 800-63B): 8–128 chars, no composition rules. Tighten per app if needed. */
 export const passwordSchema = z.string().min(8, 'Password must be at least 8 characters').max(128, 'Password is too long');
@@ -16,7 +27,13 @@ export const passwordSchema = z.string().min(8, 'Password must be at least 8 cha
 export const booleanish = z.union([z.boolean(), z.enum(['true', 'false', '1', '0', 'yes', 'no'])]).transform((v) => v === true || v === 'true' || v === '1' || v === 'yes');
 /** Comma list or repeated query param → string[]. */
 export const csvList = z.union([z.string(), z.array(z.string())]).transform((v) => (Array.isArray(v) ? v : v.split(',')).map((s) => s.trim()).filter(Boolean));
-/** Converts Zod issues into the `{ field: [messages] }` shape used by the error envelope. */
+/**
+ * Converts Zod issues into the `{ field: [messages] }` shape used by the error envelope.
+ *
+ * @param error A Zod error.
+ * @returns Messages keyed by dotted field path (`_` for the root).
+ * @example zodIssuesToErrors(result.error) // { 'items.0': ['Expected string'] }
+ */
 export function zodIssuesToErrors(error) {
     const errors = {};
     for (const issue of error.issues) {
@@ -25,12 +42,20 @@ export function zodIssuesToErrors(error) {
     }
     return errors;
 }
-/** Parses `input` or throws a ValidationError (422). */
+/**
+ * Parses `input` or throws a ValidationError (422).
+ *
+ * @param schema Zod schema.
+ * @param input Untrusted value.
+ * @returns The parsed value.
+ * @example const dto = parseOrThrow(createSchema, payload);
+ */
 export function parseOrThrow(schema, input) {
     const result = schema.safeParse(input);
     if (!result.success)
         throw new ValidationError(zodIssuesToErrors(result.error));
     return result.data;
 }
+/** Zod re-exported so services build schemas on the same zod instance as the library. */
 export { z };
 //# sourceMappingURL=index.js.map

package/dist/esm/validation/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/validation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;AAEnE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;AAExD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAC3D,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AAEvE,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAEnG,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,4BAA4B,EAAE,cAAc,CAAC,CAAC;AAEhH,+GAA+G;AAC/G,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,wCAAwC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,sBAAsB,CAAC,CAAC;AAE3H,0DAA0D;AAC1D,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC;AAE5K,qDAAqD;AACrD,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;AAE/J,6FAA6F;AAC7F,MAAM,UAAU,iBAAiB,CAAC,KAAiB;IACjD,MAAM,MAAM,GAA6B,EAAE,CAAC;IAC5C,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;QACxC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,YAAY,CAAyB,MAAS,EAAE,KAAc;IAC5E,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,MAAM,IAAI,eAAe,CAAC,iBAAiB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAChF,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,OAAO,EAAE,CAAC,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/validation/index.ts"],"names":[],"mappings":"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"}

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

@@ -7,11 +7,16 @@ import type { AuthUser } from '../types/index.js';
  * 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;
+type PermissionHolder = Pick<AuthUser, 'permissions' | 'isSuperAdmin'>;
+/** True when the user holds at least one of `required`. A super admin holds every permission. */
+export declare function hasPermission(user: PermissionHolder | null | undefined, ...required: string[]): boolean;
+/** True when the user holds every one of `required`. A super admin holds every permission. */
+export declare function hasAllPermissions(user: PermissionHolder | null | undefined, ...required: string[]): boolean;
+/** True when the user has at least one of `roles`. Prefer permission checks; roles are coarse. */
 export declare function hasRole(user: Pick<AuthUser, 'roles'> | null | undefined, ...roles: string[]): boolean;
+/** Returns the user, or throws UnauthorizedError (401) when there is none. */
 export declare function requireUser(user: AuthUser | null | undefined): AuthUser;
+/** Returns the user when they hold any of `required` (super admin always does); throws 401/403 otherwise. */
 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[];
@@ -47,4 +52,5 @@ export type OwnerFilter = {
  * otherwise the caller's own scope IDs (possibly empty → return nothing).
  */
 export declare function ownerFilter(user: AuthUser | null | undefined, scope: string, bypassPermission?: string): OwnerFilter;
+export {};
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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"}
+{"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,KAAK,gBAAgB,GAAG,IAAI,CAAC,QAAQ,EAAE,aAAa,GAAG,cAAc,CAAC,CAAC;AAEvE,iGAAiG;AACjG,wBAAgB,aAAa,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAIvG;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAI3G;AAED,kGAAkG;AAClG,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,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,GAAG,QAAQ,CAGvE;AAED,6GAA6G;AAC7G,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

@@ -17,7 +17,7 @@ export interface SlackAlertPayload {
 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`. */
+    /** Product name shown on the alert, e.g. `Acme Shop`. */
     app: string;
     /** `staging`, `production`… */
     environment: string;

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

@@ -1 +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"}
+{"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,yDAAyD;IACzD,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/approvals/index.d.ts

@@ -0,0 +1,99 @@
+import type { AuthUser } from '../types/index.js';
+/**
+ * Two-person approval state machine. A requester asks for a sensitive operation; a different person who
+ * holds both the operation's permission and the app's "decide" permission approves or rejects it; the
+ * approved operation is then executed once (or fails). Pending requests expire after a TTL.
+ *
+ * ```
+ * pending ──► approved ──► executed
+ *    │            └──────► failed
+ *    ├──► rejected
+ *    ├──► cancelled
+ *    └──► expired
+ * ```
+ *
+ * App values (the decide permission and the TTL) are passed in through {@link createApprovalPolicy}.
+ */
+/** Every approval state. */
+export declare const APPROVAL_STATES: readonly ["pending", "approved", "rejected", "cancelled", "expired", "executed", "failed"];
+/** One approval state. */
+export type ApprovalState = (typeof APPROVAL_STATES)[number];
+/** The approval facts the checks need. */
+export interface ApprovalSubject {
+    state: ApprovalState;
+    requesterUserId: string;
+    /** Permission needed to perform the operation itself, e.g. `payouts.manage`. */
+    operationPermission: string;
+    /** When a pending request stops being decidable (omit for no expiry). */
+    expiresAt?: Date | string | null;
+}
+/** The caller deciding or cancelling. */
+export type ApprovalActor = Pick<AuthUser, 'id' | 'permissions' | 'isSuperAdmin'>;
+/**
+ * True when `from → to` is an allowed move.
+ *
+ * @example canTransition('pending', 'approved') // true
+ */
+export declare function canTransition(from: ApprovalState, to: ApprovalState): boolean;
+/**
+ * Throws unless `from → to` is allowed.
+ *
+ * @throws ConflictError (`APPROVAL_INVALID_TRANSITION`).
+ */
+export declare function assertTransition(from: ApprovalState, to: ApprovalState): void;
+/** True when the state allows no further moves. */
+export declare function isTerminalApprovalState(state: ApprovalState): boolean;
+/**
+ * Throws unless `approver` may approve or reject `approval`: it is pending and not expired, the approver
+ * is not the requester (even a super admin cannot approve their own request), and holds both the
+ * operation permission and `decidePermission`.
+ *
+ * @param approval The request.
+ * @param approver The deciding user.
+ * @param decidePermission The app's "may decide approvals" permission.
+ * @param now Clock (tests).
+ * @throws ConflictError (`APPROVAL_NOT_PENDING`, `APPROVAL_EXPIRED`) or ForbiddenError
+ *   (`APPROVAL_SELF_DECISION`, `APPROVAL_FORBIDDEN`).
+ */
+export declare function assertCanDecide(approval: ApprovalSubject, approver: ApprovalActor, decidePermission: string, now?: Date): void;
+/**
+ * Throws unless `user` may cancel `approval`: only the requester, and only while it is pending.
+ *
+ * @throws ConflictError (`APPROVAL_NOT_PENDING`) or ForbiddenError (`APPROVAL_NOT_REQUESTER`).
+ */
+export declare function assertCanCancel(approval: ApprovalSubject, user: Pick<AuthUser, 'id'>): void;
+/**
+ * When a request made at `from` expires.
+ *
+ * @param ttlSeconds Positive lifetime in seconds.
+ * @param from Creation time (default now).
+ * @returns The expiry instant.
+ * @example approvalExpiresAt(3600, new Date('2026-01-01T00:00:00Z')) // 2026-01-01T01:00:00Z
+ */
+export declare function approvalExpiresAt(ttlSeconds: number, from?: Date): Date;
+/** App settings for {@link createApprovalPolicy}. */
+export interface ApprovalPolicyOptions {
+    /** Permission every approver must hold in addition to the operation's permission. */
+    decidePermission: string;
+    /** Lifetime of a pending request, in seconds. */
+    ttlSeconds: number;
+}
+/** The approval rules bound to one app's decide permission and TTL. */
+export interface ApprovalPolicy {
+    readonly decidePermission: string;
+    readonly ttlSeconds: number;
+    canTransition: typeof canTransition;
+    assertTransition: typeof assertTransition;
+    assertCanDecide(approval: ApprovalSubject, approver: ApprovalActor, now?: Date): void;
+    assertCanCancel: typeof assertCanCancel;
+    expiresAt(from?: Date): Date;
+}
+/**
+ * Binds the approval rules to an app's decide permission and TTL.
+ *
+ * @param options Decide permission and TTL.
+ * @returns The bound policy.
+ * @example const approvals = createApprovalPolicy({ decidePermission: 'requests.decide', ttlSeconds: 86_400 });
+ */
+export declare function createApprovalPolicy(options: ApprovalPolicyOptions): ApprovalPolicy;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/approvals/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AAEH,4BAA4B;AAC5B,eAAO,MAAM,eAAe,4FAA6F,CAAC;AAE1H,0BAA0B;AAC1B,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAY7D,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yEAAyE;IACzE,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,yCAAyC;AACzC,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,aAAa,GAAG,cAAc,CAAC,CAAC;AAElF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,aAAa,GAAG,OAAO,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,aAAa,GAAG,IAAI,CAI7E;AAED,mDAAmD;AACnD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAErE;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,IAAI,CAQ1I;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,IAAI,CAO3F;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,IAAI,CAGnF;AAED,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACpC,qFAAqF;IACrF,gBAAgB,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,gBAAgB,EAAE,OAAO,gBAAgB,CAAC;IAC1C,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACtF,eAAe,EAAE,OAAO,eAAe,CAAC;IACxC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAYnF"}

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

@@ -0,0 +1,82 @@
+/**
+ * Business audit events: who did what to which entity, in which scope, and which fields changed. Each
+ * service builds the event here and stages it through its outbox for the audit store; the app's contracts
+ * map it to its own event payload. Secrets never reach the event: keys matching the redaction list are
+ * dropped (only their names are kept), and phone-like values are masked.
+ */
+/** The tenant or other scope the audited entity belongs to, e.g. `{ key: 'tenant', id: '01J…' }`. */
+export interface AuditScope {
+    key: string;
+    id: string;
+}
+/** Whoever performed the action; `null` (or an absent id) means the system. */
+export interface AuditActor {
+    id: string | null;
+}
+/** One changed field: its value before and after (null when absent). */
+export interface AuditChange {
+    before: unknown;
+    after: unknown;
+}
+/** Input to {@link buildAuditEvent}. */
+export interface AuditEventInput {
+    /** What happened, as a dotted verb, e.g. `widget.price.changed`. */
+    action: string;
+    entityType: string;
+    entityId: string | null;
+    scope: AuditScope | null;
+    actor: AuditActor | null;
+    /** Entity state before the action (`null` on create). */
+    before?: Record<string, unknown> | null;
+    /** Entity state after the action (`null` on delete). */
+    after?: Record<string, unknown> | null;
+    ip?: string | null;
+    userAgent?: string | null;
+    outcome?: AuditOutcome;
+    /** When it happened; defaults to now. */
+    occurredAt?: Date | string | number;
+}
+/** Whether the audited action succeeded. */
+export type AuditOutcome = 'success' | 'failure';
+/** The built event: app-neutral, ready for an app binding to map onto its event payload. */
+export interface AuditEvent {
+    action: string;
+    entityType: string;
+    entityId: string | null;
+    scope: AuditScope | null;
+    actorUserId: string | null;
+    outcome: AuditOutcome;
+    occurredAt: string;
+    /** Only the fields whose value changed (deep comparison), secrets excluded. */
+    changes: Record<string, AuditChange>;
+    /** Names of changed fields whose values were dropped because they match the redaction list. */
+    redactedFields: string[];
+    ip: string | null;
+    /** Truncated to {@link MAX_USER_AGENT_LENGTH} characters. */
+    userAgent: string | null;
+}
+/** Options for {@link createAuditEventBuilder}. */
+export interface AuditEventBuilderOptions {
+    /** Extra key words to drop, on top of the logger's default redaction list (`password`, `token`, …). */
+    redactKeys?: readonly string[];
+}
+/** User-agent strings are cut to this length. */
+export declare const MAX_USER_AGENT_LENGTH = 255;
+/**
+ * Creates an audit-event builder with the app's extra redaction words.
+ *
+ * @param options Extra redaction words.
+ * @returns `buildAuditEvent` bound to that list.
+ * @example const buildAudit = createAuditEventBuilder({ redactKeys: ['nationalId'] });
+ */
+export declare function createAuditEventBuilder(options?: AuditEventBuilderOptions): (input: AuditEventInput) => AuditEvent;
+/**
+ * Builds an audit event with the default redaction list: the diff holds only changed fields; secret
+ * fields are dropped (named in `redactedFields`); phone fields are masked to their last 4 digits.
+ *
+ * @param input Action, entity, scope, actor, before/after state and request facts.
+ * @returns The event.
+ * @example buildAuditEvent({ action: 'widget.updated', entityType: 'widget', entityId, scope: { key: 'tenant', id: tenantId }, actor: req.user ?? null, before, after, ip: req.ip, userAgent: req.get('user-agent') })
+ */
+export declare const buildAuditEvent: (input: AuditEventInput) => AuditEvent;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/audit/index.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,qGAAqG;AACrG,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CACnB;AAED,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACvC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,yCAAyC;IACzC,UAAU,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;CACrC;AAED,4CAA4C;AAC5C,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;AAEjD,4FAA4F;AAC5F,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrC,+FAA+F;IAC/F,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,mDAAmD;AACnD,MAAM,WAAW,wBAAwB;IACvC,uGAAuG;IACvG,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,iDAAiD;AACjD,eAAO,MAAM,qBAAqB,MAAM,CAAC;AA+BzC;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,wBAA6B,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,UAAU,CAmBtH;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,UAAsC,CAAC"}

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

@@ -1,45 +1,95 @@
 import { Redis, type RedisOptions } from 'ioredis';
 import type { Logger } from '../types/index.js';
+import type { RedisKey, RedisKeyspace } from './keyspace.js';
+export * from './keyspace.js';
+/** Per-write options: required TTL and optional invalidation tags. */
 export interface CacheSetOptions {
-    ttlSec?: number;
+    /** Time to live in whole seconds; required and must be > 0 (every Redis key gets a TTL). */
+    ttlSec: number;
     /** Tags let one call invalidate every key derived from an entity (e.g. `user:01J…`). */
     tags?: string[];
 }
+/** Cache-aside store. Keys come only from the cache's {@link RedisKeyspace}; there are no KEYS/FLUSH helpers. */
 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>;
+    /** Reads a value; `undefined` on a miss. */
+    get<T>(key: RedisKey): Promise<T | undefined>;
+    /** Stores a value for `ttlSec` seconds. */
+    set<T>(key: RedisKey, value: T, options: CacheSetOptions): Promise<void>;
+    /** Deletes keys (Redis and the in-memory fallback). */
+    del(...keys: RedisKey[]): 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 & {
+    wrap<T>(key: RedisKey, loader: () => Promise<T>, options: CacheSetOptions & {
         cacheNull?: boolean;
     }): Promise<T>;
+    /** Deletes every key stored with any of `tags`. */
     invalidateTags(...tags: string[]): Promise<void>;
 }
+/** Inputs to {@link createCache}. */
 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;
+    /** The service keyspace; every key passed in must come from it, and tag sets live under it. */
+    keyspace: RedisKeyspace;
     /** Upper bound for the in-memory layer / fallback. */
     memoryMaxEntries?: number;
     logger?: Logger;
 }
+/** Purpose segment for tag index sets: `{prefix}cache-tag:{tag}`. */
+export declare const CACHE_TAG_PURPOSE = "cache-tag";
+/**
+ * Throws unless `ttlSec` is a positive whole number of seconds.
+ *
+ * @param ttlSec Proposed TTL.
+ * @throws ConfigError for ttl ≤ 0, fractions, NaN or Infinity.
+ * @example assertTtl(60)
+ */
+export declare function assertTtl(ttlSec: number): void;
 /**
  * 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.
+ *
+ * @param options Redis client (or null for memory only), the service keyspace, memory bound, logger.
+ * @returns The {@link Cache}.
+ * @example
+ * const cache = createCache({ redis, keyspace: ks, logger });
+ * const widget = await cache.wrap(ks.key('widget', id), () => repo.find(id), { ttlSec: 300 });
  */
 export declare function createCache(options: CacheOptions): Cache;
+/** Connection settings for {@link createRedisClient} (the parsed `redisEnv` block fits). */
+export interface RedisConnectionEnv {
+    REDIS_URL?: string;
+    REDIS_HOST?: string;
+    REDIS_PORT?: number;
+    REDIS_PASSWORD?: string;
+    REDIS_DB?: number;
+}
+/** Extra inputs to {@link createRedisClient}. */
 export interface RedisClientOptions {
-    url?: string;
-    db?: number;
-    /** Prepended to every key by ioredis, e.g. `showbiz:prod:`. */
-    keyPrefix?: string;
     logger?: Logger;
+    /** Extra ioredis options. `keyPrefix` is always cleared: the keyspace does the prefixing. */
     options?: RedisOptions;
 }
-/** ioredis client that never crashes the process on connection errors and retries forever. */
-export declare function createRedisClient(opts: RedisClientOptions): Redis;
+/**
+ * ioredis client that never crashes the process on connection errors and retries forever.
+ * It sets no `keyPrefix`: keys carry their full `{app}:{env}:{service}:` prefix from the keyspace.
+ *
+ * @param env Connection env (`REDIS_URL`, or host/port/password, and `REDIS_DB`).
+ * @param opts Logger and extra ioredis options.
+ * @returns The client.
+ * @example const redis = createRedisClient(config, { logger });
+ */
+export declare function createRedisClient(env: RedisConnectionEnv, opts?: RedisClientOptions): Redis;
+/**
+ * `SET key value EX ttlSec` for a keyspace key; refuses a TTL ≤ 0 so no key lives forever.
+ *
+ * @param redis Client (or anything with a compatible `set`).
+ * @param key Key from the service keyspace.
+ * @param value String value.
+ * @param ttlSec TTL in whole seconds (> 0).
+ * @throws ConfigError for an invalid TTL.
+ * @example await setWithTtl(redis, ks.key('session', id), payload, 900);
+ */
+export declare function setWithTtl(redis: Pick<Redis, 'set'>, key: RedisKey, value: string, ttlSec: number): Promise<void>;
 export type { Redis };
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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"}
+{"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;AAGnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE7D,cAAc,eAAe,CAAC;AAE9B,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,4FAA4F;IAC5F,MAAM,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,iHAAiH;AACjH,MAAM,WAAW,KAAK;IACpB,4CAA4C;IAC5C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC9C,2CAA2C;IAC3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE,uDAAuD;IACvD,GAAG,CAAC,GAAG,IAAI,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,+GAA+G;IAC/G,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,GAAG;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACjH,mDAAmD;IACnD,cAAc,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAED,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,+FAA+F;IAC/F,QAAQ,EAAE,aAAa,CAAC;IACxB,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qEAAqE;AACrE,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAI7C;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE9C;AAmCD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,CAoGxD;AAED,4FAA4F;AAC5F,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,kBAAkB,EAAE,IAAI,GAAE,kBAAuB,GAAG,KAAK,CAsB/F;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvH;AAED,YAAY,EAAE,KAAK,EAAE,CAAC"}

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

@@ -0,0 +1,84 @@
+/**
+ * Redis keyspace: every key is `{app}:{env}:{service}:{purpose}[:{part}…]`.
+ *
+ * One Redis installation may serve several apps and environments, so keys are namespaced by the app
+ * slug (a parameter — shared-lib names no app), the environment (`CACHE_KEY_PREFIX`) and the owning
+ * service. Build every key through {@link createRedisKeyspace}; never hand-write prefixes.
+ *
+ * Dependency-free (no ioredis), so it is exported from the package root as well as `/cache`.
+ */
+/** A key built by a {@link RedisKeyspace}. The brand stops hand-written strings reaching the cache helpers. */
+export type RedisKey = string & {
+    readonly __redisKey: true;
+};
+/** A value to hash before it goes into a key (personal data or secrets). Create with {@link sensitivePart}. */
+export interface SensitiveKeyPart {
+    readonly sensitive: string;
+}
+/** One variable part of a key. */
+export type RedisKeyPart = string | number | SensitiveKeyPart;
+/** Inputs to {@link createRedisKeyspace}. */
+export interface RedisKeyspaceOptions {
+    /** App slug, e.g. `myapp` (lower-case kebab-case). */
+    app: string;
+    /** Owning service (the service that writes the key), e.g. `widget-service`. */
+    service: string;
+    /** Environment segment, normally the `CACHE_KEY_PREFIX` env value (`dev`, `staging`, `prod`). */
+    env?: string;
+    /** Node environment used for the deployed-environment check (default `process.env.NODE_ENV`). */
+    nodeEnv?: string;
+    /** When set, hashed parts use HMAC-SHA256 with this secret instead of plain SHA-256. */
+    hashSecret?: string;
+}
+/** One service's key builder; every key it makes starts with {@link RedisKeyspace.prefix}. */
+export interface RedisKeyspace {
+    readonly app: string;
+    readonly env: string;
+    readonly service: string;
+    /** `{app}:{env}:{service}:` — every key and pattern starts with this. */
+    readonly prefix: string;
+    /**
+     * Builds `{prefix}{purpose}[:{part}…]`. Parts are percent-encoded so they cannot add segments or
+     * widen a SCAN pattern; long, email-like, phone-like and {@link sensitivePart} parts are hashed.
+     */
+    key(purpose: string, ...parts: RedisKeyPart[]): RedisKey;
+    /** SCAN pattern anchored on the prefix: `{prefix}{purpose}:{suffix}` (suffix defaults to `*`). */
+    pattern(purpose: string, suffix?: string): string;
+    /** True when `key` lies inside this keyspace. */
+    owns(key: string): key is RedisKey;
+}
+/** Environment segment used outside staging and production when none is given. */
+export declare const DEFAULT_KEY_ENV = "dev";
+/** Parts longer than this are hashed. */
+export declare const MAX_PLAIN_KEY_PART_LENGTH = 64;
+/** Marker that starts every hashed part. */
+export declare const HASHED_PART_PREFIX = "h.";
+/**
+ * Marks a key part as personal data or a secret so the keyspace always hashes it.
+ *
+ * @param value Raw value (e.g. an email address or a token).
+ * @returns A part the keyspace hashes.
+ * @example ks.key('otp', sensitivePart(email))
+ */
+export declare const sensitivePart: (value: string) => SensitiveKeyPart;
+/**
+ * Percent-encodes a plain key part, including the glob characters SCAN interprets.
+ *
+ * @param value Part text (non-empty).
+ * @returns The encoded part.
+ * @throws ConfigError when the part is empty.
+ * @example encodeKeyPart('a:b*') // 'a%3Ab%2A'
+ */
+export declare function encodeKeyPart(value: string): string;
+/**
+ * Creates the keyspace for one service.
+ *
+ * @param options App slug, service, env segment (`CACHE_KEY_PREFIX`), optional hash secret.
+ * @returns A {@link RedisKeyspace}.
+ * @throws ConfigError on an invalid segment, or when `env` is missing in staging/production.
+ * @example
+ * const ks = createRedisKeyspace({ app: 'myapp', service: 'widget-service', env: config.CACHE_KEY_PREFIX });
+ * ks.key('widget', widgetId) // 'myapp:prod:widget-service:widget:01J…'
+ */
+export declare function createRedisKeyspace(options: RedisKeyspaceOptions): RedisKeyspace;
+//# sourceMappingURL=keyspace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keyspace.d.ts","sourceRoot":"","sources":["../../../src/cache/keyspace.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,+GAA+G;AAC/G,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAA;CAAE,CAAC;AAE9D,+GAA+G;AAC/G,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,kCAAkC;AAClC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,gBAAgB,CAAC;AAE9D,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,8FAA8F;AAC9F,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,YAAY,EAAE,GAAG,QAAQ,CAAC;IACzD,kGAAkG;IAClG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAClD,iDAAiD;IACjD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,QAAQ,CAAC;CACpC;AAED,kFAAkF;AAClF,eAAO,MAAM,eAAe,QAAQ,CAAC;AACrC,yCAAyC;AACzC,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAC5C,4CAA4C;AAC5C,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAWvC;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,KAAG,gBAA0C,CAAC;AAEzF;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGnD;AA2BD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAuBhF"}