@heavybit/shared-lib 1.3.2 → 2.1.0

package/dist/types/express/respond.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Success-response helpers for Express controllers (HTTP layer only).
+ * They write the standard envelope `{ success: true, message, data, meta? }`, so controllers never
+ * hand-build bodies. Errors are not sent here: throw an AppError and let `errorHandler` answer.
+ */
+import type { Response } from 'express';
+import type { CursorPage, CursorPageMeta, PaginationMeta } from '../types/index.js';
+/**
+ * 200 with the success envelope.
+ *
+ * @param res Express response.
+ * @param data The payload placed under `data`.
+ * @param message Optional human-readable message (default `Success`).
+ * @param meta Optional list metadata.
+ * @returns The Express response.
+ * @example ok(res, product, 'Product updated');
+ */
+export declare function ok<T>(res: Response, data: T, message?: string, meta?: PaginationMeta | CursorPageMeta): Response;
+/**
+ * 201 with the success envelope, for a newly created resource.
+ *
+ * @param res Express response.
+ * @param data The created resource (or its id).
+ * @param message Optional message (default `Created`).
+ * @returns The Express response.
+ *
+ * @example created(res, { id }, 'Shop created');
+ */
+export declare function created<T>(res: Response, data: T, message?: string): Response;
+/**
+ * 200 with a cursor-paginated list: `data` is the items, `meta` is `{ limit, nextCursor, hasMore }`.
+ *
+ * @param res Express response.
+ * @param page The page from the service (see `buildCursorPageMeta`).
+ * @param message Optional message.
+ * @returns The Express response.
+ *
+ * @example okPage(res, await service.list(scope, { cursor, limit }));
+ */
+export declare function okPage<T>(res: Response, page: CursorPage<T>, message?: string): Response;
+//# sourceMappingURL=respond.d.ts.map

package/dist/types/express/respond.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"respond.d.ts","sourceRoot":"","sources":["../../../src/express/respond.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEpF;;;;;;;;;GASG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,cAAc,GAAG,QAAQ,CAGhH;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,SAAY,GAAG,QAAQ,CAEhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAExF"}

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types/index.js';
 export * from './common/index.js';
+export * from './context/index.js';
 export * from './identity/index.js';
 export * from './access/index.js';
 export * from './validation/index.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}

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

@@ -1,14 +1,35 @@
+import type { Writable } from 'node:stream';
 import winston from 'winston';
 import type { Logger } from '../types/index.js';
-/** Keys whose values are replaced with `[REDACTED]` anywhere in log metadata. */
-export declare const DEFAULT_REDACT_KEYS: string[];
+export { DEFAULT_ALLOW_KEYS, DEFAULT_REDACT_KEYS, REDACTED, createKeyClassifier, maskPhoneForLog, maskPhonesInText, redactValue } from './redact.js';
+export type { KeyClassifier } from './redact.js';
+/** Options for {@link createLogger}. */
 export interface LoggerOptions {
+    /** Minimum level; defaults to `LOG_LEVEL`, else `info` in production and `debug` elsewhere. */
     level?: string;
-    /** `json` for machines (default in production), `pretty` for humans. */
+    /** `json` for machines (default in production), `pretty` for humans. Files and streams are always JSON. */
     format?: 'json' | 'pretty';
+    /** Extra sensitive words, matched like {@link DEFAULT_REDACT_KEYS} (e.g. `nationalId`). */
     redactKeys?: string[];
+    /** Exact keys never redacted; replaces {@link DEFAULT_ALLOW_KEYS}. */
+    allowKeys?: string[];
+    /** Also append JSON lines to this file (e.g. `logs/api.log`). */
+    filePath?: string;
+    /** Also write JSON lines to this stream (log shippers, tests). */
+    stream?: Writable;
 }
-/** Structured logger with secret redaction. JSON to stdout in production, pretty otherwise. */
+/**
+ * Structured logger. Every line carries `service` and, inside a request or {@link runWithContext}, the
+ * context's `correlationId`, `userId` and `scopes`. Secrets are redacted by key word (see
+ * {@link DEFAULT_REDACT_KEYS}) and phone numbers are masked to their last 4 digits, in the message and
+ * at any depth of the metadata. Writes to stdout (JSON in production, pretty otherwise; silent under
+ * `NODE_ENV=test` unless `LOG_IN_TESTS` is set) plus an optional file and stream.
+ *
+ * @param service Service name on every line.
+ * @param options Level, format, extra redact/allow keys, file path, stream.
+ * @returns A winston logger that satisfies {@link Logger}.
+ * @example const logger = createLogger('api', { filePath: 'logs/api.log' });
+ */
 export declare function createLogger(service: string, options?: LoggerOptions): winston.Logger & Logger;
 /** Logger that discards everything — handy default for libraries and tests. */
 export declare const silentLogger: Logger;
@@ -17,6 +38,11 @@ export declare const silentLogger: Logger;
  * meta wins on a key clash. `undefined` context values are dropped so lines never carry empty keys.
  * Works over any {@link Logger} (winston, a test spy, or another child), so handlers can create one
  * per message and pass it down.
+ *
+ * @param logger The logger to write through.
+ * @param context Values added to every line.
+ * @returns A {@link Logger}.
+ * @example const log = childLogger(logger, { jobId });
  */
 export declare function childLogger(logger: Logger, context: Record<string, unknown>): Logger;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/logging/index.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAIhD,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,UAG/B,CAAC;AA6BF,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,+FAA+F;AAC/F,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,GAAG,MAAM,CAiBlG;AAED,+EAA+E;AAC/E,eAAO,MAAM,YAAY,EAAE,MAA6E,CAAC;AAEzG;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAKpF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/logging/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,QAAQ,EAAE,mBAAmB,EAAE,eAAe,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrJ,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA2CjD,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2GAA2G;IAC3G,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC3B,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,MAAM,CAAC,EAAE,QAAQ,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,GAAG,MAAM,CAqBlG;AAED,+EAA+E;AAC/E,eAAO,MAAM,YAAY,EAAE,MAA6E,CAAC;AAEzG;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAKpF"}

package/dist/types/logging/redact.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Secret redaction and phone masking for log lines. Matching is by key *word*, not substring: a key is
+ * split on camelCase and separators (`refresh_token` → `refresh`, `token`; `OTPCode` → `otp`, `code`),
+ * and it is sensitive when a word (or two adjacent words joined, e.g. `api`+`key`) equals a listed term
+ * or its plural. So `accessToken` and `Set-Cookie` are redacted while `pinned` or `spinner` are not.
+ */
+/** Words whose values are always replaced with `[REDACTED]`. Apps add their own via `redactKeys`. */
+export declare const DEFAULT_REDACT_KEYS: readonly string[];
+/** Keys that are never redacted although they contain a listed word (error, status and reference codes). */
+export declare const DEFAULT_ALLOW_KEYS: readonly string[];
+/** The marker that replaces a secret value. */
+export declare const REDACTED = "[REDACTED]";
+/**
+ * Masks every digit except the last four (log rule; the UI uses `maskPhone` from common).
+ *
+ * @param value A phone number in any format.
+ * @returns e.g. `********5678`; values with fewer than 5 digits are fully masked.
+ * @example maskPhoneForLog('15551234567') // '*******4567'
+ */
+export declare function maskPhoneForLog(value: string): string;
+/**
+ * Masks phone-number-looking runs inside free text.
+ *
+ * @param text Any string (a log message or value).
+ * @returns The text with each 9–15 digit run masked to its last 4 digits.
+ * @example maskPhonesInText('OTP sent to 15551234567') // 'OTP sent to *******4567'
+ */
+export declare function maskPhonesInText(text: string): string;
+/** Decides, per key, whether a value is a secret, a phone number or neither. */
+export interface KeyClassifier {
+    isSecret(key: string): boolean;
+    isPhone(key: string): boolean;
+}
+/**
+ * Builds a key classifier from the default terms plus app-specific ones.
+ *
+ * @param extraKeys Extra words (matched like the defaults, case-insensitive).
+ * @param allowKeys Exact keys never treated as secret (defaults to {@link DEFAULT_ALLOW_KEYS}).
+ * @returns The classifier.
+ * @example createKeyClassifier(['nationalId']).isSecret('nationalId') // true
+ */
+export declare function createKeyClassifier(extraKeys?: readonly string[], allowKeys?: readonly string[]): KeyClassifier;
+/**
+ * Returns a copy of `value` with secrets replaced by `[REDACTED]` and phone numbers masked, at any depth
+ * (up to 8 levels; deeper values are dropped as `[TRUNCATED]`). Errors are kept as-is.
+ *
+ * @param value Log metadata (object, array or scalar).
+ * @param classifier From {@link createKeyClassifier}.
+ * @param depth Internal recursion depth; callers omit it.
+ * @returns The redacted copy; the input is not modified.
+ * @example redactValue({ user: { otp: '1234', phone: '15551234567' } }, createKeyClassifier())
+ */
+export declare function redactValue(value: unknown, classifier: KeyClassifier, depth?: number): unknown;
+//# sourceMappingURL=redact.d.ts.map

package/dist/types/logging/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../../src/logging/redact.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAGhD,CAAC;AAEF,4GAA4G;AAC5G,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAwF,CAAC;AAQzI,+CAA+C;AAC/C,eAAO,MAAM,QAAQ,eAAe,CAAC;AAGrC;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAWD,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,GAAE,SAAS,MAAM,EAAO,EAAE,SAAS,GAAE,SAAS,MAAM,EAAuB,GAAG,aAAa,CAgBvI;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,KAAK,SAAI,GAAG,OAAO,CAYzF"}

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

@@ -15,6 +15,7 @@ export * from './rpc.js';
 export * from './outbox.js';
 export * from './monitor.js';
 export * from './staff-notifier.js';
+export * from './staff-recipients.js';
 export interface MessagingOptions {
     url: string;
     app: string;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/messaging/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9D,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AAEpC,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,cAAc,CAAC;IAC3B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,YAAY,CAAC;IACtB,0FAA0F;IAC1F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA0BpE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/messaging/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9D,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AAEtC,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,cAAc,CAAC;IAC3B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,YAAY,CAAC;IACtB,0FAA0F;IAC1F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA0BpE"}

package/dist/types/messaging/staff-notifier.d.ts

@@ -1,56 +1,87 @@
-import { z } from 'zod';
-import { type DispatchChannel, type DispatchRecipient, type DispatchValue } from '../contracts/notification-dispatch.js';
+/**
+ * Staff alerts (messaging layer helper): stage one notification dispatch per recipient of a
+ * permission through the caller's outbox. App vocabulary (category, channels, command name) is
+ * passed in as options; nothing app-specific is assumed.
+ */
+import { type DispatchValue } from '../contracts/notification-dispatch.js';
 import type { Logger } from '../types/index.js';
 import type { EnvelopeMeta } from './envelope.js';
-/** The slice of a service's outbox the notifier needs; `E` is that service's transaction type. */
+import type { StaffRecipientResolver } from './staff-recipients.js';
+/**
+ * The slice of a service's outbox the notifier needs.
+ *
+ * @typeParam E The service's transaction/executor type.
+ * @example const outbox: CommandOutbox<Tx> = { command: (tx, name, data, meta) => outboxRepo.stageCommand(tx, name, data, meta) };
+ */
 export interface CommandOutbox<E> {
     command<T>(executor: E, command: string, data: T, meta?: EnvelopeMeta): Promise<void>;
 }
-/** Who holds a permission, as staff alert recipients. Configured lists today; an auth-admin lookup later. */
-export interface StaffRecipientResolver {
-    resolve(permission: string): Promise<DispatchRecipient[]>;
-}
-/** Recipients from configuration (env), keyed by the permission an alert targets. */
-export declare class ConfiguredStaffRecipients implements StaffRecipientResolver {
-    private readonly byPermission;
-    constructor(byPermission: Readonly<Record<string, readonly DispatchRecipient[]>>);
-    resolve(permission: string): Promise<DispatchRecipient[]>;
-}
-export interface StaffAlert {
+/**
+ * One operational alert to the staff who hold a permission.
+ *
+ * @example { template: 'payout-failed', permission: 'payouts.manage', data: { reference: 'PO-1' } }
+ */
+export interface StaffAlert<Ch extends string = string> {
     /** Seeded notification template slug. */
     template: string;
-    /** The permission its recipients hold (e.g. `newsdesk.policy.manage`). */
+    /** The permission its recipients hold (e.g. `orders.manage`). */
     permission: string;
     /** Template variables. */
     data: Record<string, DispatchValue>;
-    /** Defaults to email: staff addresses have no account, so the in-app feed cannot reach them. */
-    channels?: DispatchChannel[];
+    /** Channels for this alert (at least one); defaults to the notifier's `defaultChannels`. */
+    channels?: [Ch, ...Ch[]];
 }
-/** Tracing for the staged commands; the actor is always the system. */
+/**
+ * Tracing for the staged commands; the actor is always the system.
+ *
+ * @example { correlationId: correlationId(req), aggregate: { type: 'payout', id: payout.id } }
+ */
 export type StaffAlertMeta = Pick<EnvelopeMeta, 'correlationId' | 'aggregate'>;
 /**
- * Stages one `notification:dispatch` per recipient through the outbox, in the caller's transaction, so an
- * alert is sent if and only if the state change that raised it commits. Never sends email itself.
+ * How the notifier stages commands. All app vocabulary is passed in; nothing is assumed.
+ *
+ * @example { category: 'staff', defaultChannels: ['email'], logger }
+ */
+export interface StaffNotifierOptions<C extends string, Ch extends string> {
+    /** The dispatch category for staff alerts in this app (e.g. `staff`). */
+    category: C;
+    /** Channels used when an alert names none. Staff addresses usually have no account, so typically `['email']`. */
+    defaultChannels: [Ch, ...Ch[]];
+    /** Command name; defaults to {@link NOTIFICATION_DISPATCH}. */
+    command?: string;
+    /** Warns when an alert resolves to no recipients; silent when omitted. */
+    logger?: Logger;
+}
+/**
+ * Stages one dispatch command per recipient through the outbox, in the caller's transaction, so an
+ * alert is sent if and only if the state change that raised it commits. Never sends anything itself.
  * An alert that resolves to nobody is logged as a warning (an unconfigured list must not fail silently).
+ * Staff alerts always bypass recipient preferences and record the target permission.
+ *
+ * @typeParam E The service's transaction/executor type.
+ * @typeParam C The app's dispatch categories.
+ * @typeParam Ch The app's dispatch channels.
+ * @example
+ * const notifier = new StaffNotifier(outbox, new ConfiguredStaffRecipients({ 'payouts.manage': config.financeEmails }),
+ *   { category: 'staff', defaultChannels: ['email'], logger });
+ * await notifier.alert(tx, { template: 'payout-failed', permission: 'payouts.manage', data: { reference } }, { correlationId });
  */
-export declare class StaffNotifier<E> {
+export declare class StaffNotifier<E, C extends string = string, Ch extends string = string> {
     private readonly outbox;
     private readonly recipients;
+    private readonly category;
+    private readonly defaultChannels;
+    private readonly command;
     private readonly logger;
-    constructor(outbox: CommandOutbox<E>, recipients: StaffRecipientResolver, logger?: Logger);
-    /** Returns how many commands were staged. */
-    alert(executor: E, alert: StaffAlert, meta?: StaffAlertMeta): Promise<number>;
+    constructor(outbox: CommandOutbox<E>, recipients: StaffRecipientResolver, options: StaffNotifierOptions<C, Ch>);
+    /**
+     * Stage the alert for every recipient of its permission.
+     *
+     * @param executor The caller's open transaction; the commands commit or roll back with it.
+     * @param alert Template, permission, variables and optional channels.
+     * @param meta Correlation id and aggregate for tracing; the actor is always the system.
+     * @returns How many commands were staged (0 when nobody is configured).
+     */
+    alert(executor: E, alert: StaffAlert<Ch>, meta?: StaffAlertMeta): Promise<number>;
 }
-/**
- * A comma-separated staff address list from env (`"a@x.io, b@y.io"`): trimmed, blanks dropped,
- * de-duplicated case-insensitively. An invalid address fails validation, so a typo is caught at boot
- * instead of dead-lettering in notification-service when the alert finally fires.
- */
-export declare const staffEmailListSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodString>, string[], string | undefined>, string[], string | undefined>, {
-    email: string;
-    name?: string | undefined;
-    userId?: string | null | undefined;
-    locale?: string | null | undefined;
-    timezone?: string | null | undefined;
-}[], string | undefined>;
 //# sourceMappingURL=staff-notifier.d.ts.map

package/dist/types/messaging/staff-notifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staff-notifier.d.ts","sourceRoot":"","sources":["../../../src/messaging/staff-notifier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAEnB,MAAM,uCAAuC,CAAC;AAE/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,kGAAkG;AAClG,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvF;AAED,6GAA6G;AAC7G,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;CAC3D;AAED,qFAAqF;AACrF,qBAAa,yBAA0B,YAAW,sBAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAAZ,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC,CAAC;IAE3F,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;CAGhE;AAED,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACpC,gGAAgG;IAChG,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;CAC9B;AAED,uEAAuE;AACvE,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,WAAW,CAAC,CAAC;AAE/E;;;;GAIG;AACH,qBAAa,aAAa,CAAC,CAAC;IAExB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAFN,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,UAAU,EAAE,sBAAsB,EAClC,MAAM,GAAE,MAAqB;IAGhD,6CAA6C;IACvC,KAAK,CAAC,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;CAoBxF;AAID;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;wBAegD,CAAC"}
+{"version":3,"file":"staff-notifier.d.ts","sourceRoot":"","sources":["../../../src/messaging/staff-notifier.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,uCAAuC,CAAC;AAE/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvF;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM;IACpD,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACpC,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,WAAW,CAAC,CAAC;AAE/E;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,SAAS,MAAM;IACvE,yEAAyE;IACzE,QAAQ,EAAE,CAAC,CAAC;IACZ,iHAAiH;IACjH,eAAe,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAC/B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAa,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,SAAS,MAAM,GAAG,MAAM;IAO/E,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAP7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAI;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAGb,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,UAAU,EAAE,sBAAsB,EACnD,OAAO,EAAE,oBAAoB,CAAC,CAAC,EAAE,EAAE,CAAC;IAQtC;;;;;;;OAOG;IACG,KAAK,CAAC,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;CAoB5F"}

package/dist/types/messaging/staff-recipients.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Staff alert recipients (messaging layer helper): who receives an alert raised for a permission.
+ * Today the lists come from configuration; an app can plug in a lookup (e.g. its auth service)
+ * by implementing {@link StaffRecipientResolver}.
+ */
+import { z } from 'zod';
+import { type DispatchRecipient } from '../contracts/notification-dispatch.js';
+/**
+ * Resolves the recipients who hold a permission.
+ *
+ * @example const resolver: StaffRecipientResolver = { resolve: async (p) => authClient.usersWithPermission(p) };
+ */
+export interface StaffRecipientResolver {
+    /**
+     * @param permission The permission an alert targets.
+     * @returns Recipients (possibly empty).
+     */
+    resolve(permission: string): Promise<DispatchRecipient[]>;
+}
+/**
+ * Recipients from configuration (env), keyed by the permission an alert targets.
+ *
+ * @param byPermission Map of permission → recipients, typically built with {@link staffEmailListSchema}.
+ * @example new ConfiguredStaffRecipients({ 'payouts.manage': env.FINANCE_ALERT_EMAILS })
+ */
+export declare class ConfiguredStaffRecipients implements StaffRecipientResolver {
+    private readonly byPermission;
+    constructor(byPermission: Readonly<Record<string, readonly DispatchRecipient[]>>);
+    /**
+     * @param permission The permission an alert targets.
+     * @returns A copy of the configured recipients, or `[]` when none are configured.
+     */
+    resolve(permission: string): Promise<DispatchRecipient[]>;
+}
+/**
+ * A comma-separated staff address list from env (`"a@x.io, b@y.io"`): trimmed, blanks dropped,
+ * de-duplicated case-insensitively. An invalid address fails validation, so a typo is caught at boot
+ * instead of dead-lettering in the notification-service when the alert finally fires.
+ *
+ * @returns (on parse) `DispatchRecipient[]` with `email` only.
+ * @example const config = z.object({ FINANCE_ALERT_EMAILS: staffEmailListSchema }).parse(process.env);
+ */
+export declare const staffEmailListSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodString>, string[], string | undefined>, string[], string | undefined>, {
+    email: string;
+    userId?: string | null | undefined;
+    name?: string | undefined;
+    locale?: string | null | undefined;
+    timezone?: string | null | undefined;
+}[], string | undefined>;
+//# sourceMappingURL=staff-recipients.d.ts.map

package/dist/types/messaging/staff-recipients.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staff-recipients.d.ts","sourceRoot":"","sources":["../../../src/messaging/staff-recipients.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAEhG;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;CAC3D;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,YAAW,sBAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAAZ,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC,CAAC;IAEjG;;;OAGG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;CAGhE;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB;;;;;;wBAegD,CAAC"}

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

@@ -13,6 +13,7 @@ export interface AuthUser {
     attrs: Record<string, unknown>;
     sessionId?: string;
 }
+/** Offset pagination metadata (page/limit with totals). For large or growing lists prefer {@link CursorPageMeta}. */
 export interface PaginationMeta {
     page: number;
     limit: number;
@@ -21,18 +22,52 @@ export interface PaginationMeta {
     hasNext: boolean;
     hasPrev: boolean;
 }
+/**
+ * Cursor (keyset) pagination metadata: no totals or page numbers, so it stays cheap on large tables.
+ * `nextCursor` is opaque to clients (it encodes the sort key + an id tie-breaker); `null` on the last page.
+ */
+export interface CursorPageMeta {
+    limit: number;
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+/** One page of a cursor-paginated list, as a repository or service returns it. */
+export interface CursorPage<T> {
+    data: T[];
+    meta: CursorPageMeta;
+}
+/**
+ * The standard response envelope. Success: `{ success: true, message, data, meta? }`.
+ * Error: see {@link ErrorBody}.
+ */
 export interface ApiResponse<T = unknown> {
     success: boolean;
     message: string;
     code?: string;
     data?: T;
-    meta?: PaginationMeta;
+    meta?: PaginationMeta | CursorPageMeta;
+    errors?: Record<string, string[]>;
+    /** Correlation id of the failed request (error bodies only), so support can find the log lines. */
+    requestId?: string;
+}
+/**
+ * The error body every service returns: `{ success: false, code, message, errors?, requestId? }`.
+ * `code` is UPPER_SNAKE_CASE; `errors` maps field paths to messages (validation only); 5xx bodies
+ * always carry a generic message.
+ */
+export interface ErrorBody {
+    success: false;
+    code: string;
+    message: string;
     errors?: Record<string, string[]>;
+    requestId?: string;
 }
+/** One page of an offset-paginated list, as a repository or service returns it. */
 export interface PaginatedResult<T> {
     data: T[];
     meta: PaginationMeta;
 }
+/** Parsed offset-pagination query: 1-based `page` and page size `limit`. */
 export interface PageQuery {
     page: number;
     limit: number;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,IAAI,EAAE,cAAc,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,8CAA8C;AAC9C,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAClC,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,IAAI,EAAE,CAAC,CAAC;CACT;AAED,+FAA+F;AAC/F,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"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"}

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

@@ -1,5 +1,7 @@
 import { z } from 'zod';
+/** A ULID in canonical form (26 upper-case Crockford base32 chars), as `newId()` makes and `CHAR(26)` stores. */
 export declare const idSchema: z.ZodString;
+/** Route params `{ id }` where `id` is a canonical ULID. Use with `validate({ params: idParamSchema })`. */
 export declare const idParamSchema: z.ZodObject<{
     id: z.ZodString;
 }, "strip", z.ZodTypeAny, {
@@ -7,6 +9,18 @@ export declare const idParamSchema: z.ZodObject<{
 }, {
     id: string;
 }>;
+/**
+ * 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 declare const idParam: z.ZodObject<{
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+/** Offset pagination query: `page` ≥ 1 (default 1), `limit` 1–100 (default 20). Prefer cursor pagination (D6). */
 export declare const paginationSchema: z.ZodObject<{
     page: z.ZodDefault<z.ZodNumber>;
     limit: z.ZodDefault<z.ZodNumber>;
@@ -17,8 +31,11 @@ export declare const paginationSchema: z.ZodObject<{
     page?: number | undefined;
     limit?: number | undefined;
 }>;
+/** `asc` or `desc`, default `desc`. */
 export declare const sortOrderSchema: z.ZodDefault<z.ZodEnum<["asc", "desc"]>>;
+/** Trimmed, lower-cased email address, max 191 chars. */
 export declare const emailSchema: z.ZodString;
+/** Lower-case kebab-case slug, 1–120 chars. */
 export declare const slugSchema: z.ZodString;
 /** Length-first password rule (NIST 800-63B): 8–128 chars, no composition rules. Tighten per app if needed. */
 export declare const passwordSchema: z.ZodString;
@@ -26,9 +43,23 @@ export declare const passwordSchema: z.ZodString;
 export declare const booleanish: z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodEnum<["true", "false", "1", "0", "yes", "no"]>]>, boolean, boolean | "0" | "1" | "true" | "false" | "yes" | "no">;
 /** Comma list or repeated query param → string[]. */
 export declare const csvList: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>, string[], string | string[]>;
-/** 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 declare function zodIssuesToErrors(error: z.ZodError): Record<string, string[]>;
-/** 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 declare function parseOrThrow<S extends z.ZodTypeAny>(schema: S, input: unknown): z.infer<S>;
+/** Zod re-exported so services build schemas on the same zod instance as the library. */
 export { z };
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/validation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,QAAQ,aAA6C,CAAC;AAEnE,eAAO,MAAM,aAAa;;;;;;EAA6B,CAAC;AAExD,eAAO,MAAM,gBAAgB;;;;;;;;;EAG3B,CAAC;AAEH,eAAO,MAAM,eAAe,0CAA0C,CAAC;AAEvE,eAAO,MAAM,WAAW,aAA0E,CAAC;AAEnG,eAAO,MAAM,UAAU,aAAwF,CAAC;AAEhH,+GAA+G;AAC/G,eAAO,MAAM,cAAc,aAA+F,CAAC;AAE3H,0DAA0D;AAC1D,eAAO,MAAM,UAAU,+JAAoJ,CAAC;AAE5K,qDAAqD;AACrD,eAAO,MAAM,OAAO,uGAA0I,CAAC;AAE/J,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAO7E;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAI1F;AAED,OAAO,EAAE,CAAC,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/validation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,iHAAiH;AACjH,eAAO,MAAM,QAAQ,aAA6C,CAAC;AAEnE,4GAA4G;AAC5G,eAAO,MAAM,aAAa;;;;;;EAA6B,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,OAAO;;;;;;EAAgB,CAAC;AAErC,kHAAkH;AAClH,eAAO,MAAM,gBAAgB;;;;;;;;;EAG3B,CAAC;AAEH,uCAAuC;AACvC,eAAO,MAAM,eAAe,0CAA0C,CAAC;AAEvE,yDAAyD;AACzD,eAAO,MAAM,WAAW,aAA0E,CAAC;AAEnG,+CAA+C;AAC/C,eAAO,MAAM,UAAU,aAAwF,CAAC;AAEhH,+GAA+G;AAC/G,eAAO,MAAM,cAAc,aAA+F,CAAC;AAE3H,0DAA0D;AAC1D,eAAO,MAAM,UAAU,+JAAoJ,CAAC;AAE5K,qDAAqD;AACrD,eAAO,MAAM,OAAO,uGAA0I,CAAC;AAE/J;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAO7E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAI1F;AAED,yFAAyF;AACzF,OAAO,EAAE,CAAC,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heavybit/shared-lib",
-  "version": "1.3.2",
+  "version": "2.1.0",
   "description": "App-agnostic building blocks for Express/TypeScript microservices: gateway identity, access scoping, RabbitMQ events/commands/RPC with retries and DLQs, outbox, cache-aside, rate limiting, sockets, signing, logging and config.",
   "license": "MIT",
   "type": "module",