@heavybit/shared-lib 1.3.2 → 2.1.0

package/dist/esm/express/respond.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"respond.js","sourceRoot":"","sources":["../../../src/express/respond.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGjF;;;;;;;;;GASG;AACH,MAAM,UAAU,EAAE,CAAI,GAAa,EAAE,IAAO,EAAE,OAAgB,EAAE,IAAsC;IACpG,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC5C,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,OAAO,CAAI,GAAa,EAAE,IAAO,EAAE,OAAO,GAAG,SAAS;IACpE,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,MAAM,CAAI,GAAa,EAAE,IAAmB,EAAE,OAAgB;IAC5E,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/esm/index.js

@@ -3,6 +3,7 @@
 // live behind subpaths: `@heavybit/shared-lib/express`, `/cache`, `/messaging`, …
 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/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,8FAA8F;AAC9F,kFAAkF;AAClF,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.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,8FAA8F;AAC9F,kFAAkF;AAClF,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/esm/logging/index.js

@@ -1,54 +1,78 @@
 import winston from 'winston';
-const { combine, timestamp, json, errors, colorize, printf, splat } = winston.format;
-/** Keys whose values are replaced with `[REDACTED]` anywhere in log metadata. */
-export const DEFAULT_REDACT_KEYS = [
-    'password', 'newPassword', 'currentPassword', 'passwordHash', 'token', 'accessToken', 'refreshToken',
-    'secret', 'clientSecret', 'apiKey', 'authorization', 'cookie', 'otp', 'pass', 'smtpPassword',
-];
-function redactValue(value, keys, depth = 0) {
-    if (depth > 6 || value === null || typeof value !== 'object')
-        return value;
-    if (Array.isArray(value))
-        return value.map((v) => redactValue(v, keys, depth + 1));
-    if (value instanceof Error)
-        return value;
-    const out = {};
-    for (const [k, v] of Object.entries(value)) {
-        out[k] = keys.has(k) || k.endsWith('Enc') || k.endsWith('_enc') ? '[REDACTED]' : redactValue(v, keys, depth + 1);
-    }
-    return out;
-}
-const redact = (keys) => winston.format((info) => {
-    for (const k of Object.keys(info)) {
-        if (keys.has(k))
-            info[k] = '[REDACTED]';
-        else if (k !== 'message' && k !== 'level')
-            info[k] = redactValue(info[k], keys);
-    }
+import { getRequestContext } from '../context/index.js';
+import { createKeyClassifier, maskPhonesInText, redactValue } from './redact.js';
+export { DEFAULT_ALLOW_KEYS, DEFAULT_REDACT_KEYS, REDACTED, createKeyClassifier, maskPhoneForLog, maskPhonesInText, redactValue } from './redact.js';
+const { combine, timestamp, errors, colorize, printf, splat } = winston.format;
+/** Winston bookkeeping keys that never appear as metadata. */
+const RESERVED_KEYS = new Set(['level', 'message', 'timestamp', 'splat']);
+/** Ids the library itself puts on a line; never redacted or phone-masked. */
+const CONTEXT_KEYS = new Set(['service', 'correlationId', 'userId', 'scopes']);
+/** Adds the request context (correlation id, user id, scopes, service) unless the line already has it. */
+const withContext = winston.format((info) => {
+    const ctx = getRequestContext();
+    if (!ctx)
+        return info;
+    const line = info;
+    line.correlationId ??= ctx.correlationId;
+    if (ctx.userId !== undefined)
+        line.userId ??= ctx.userId;
+    if (ctx.scopes && Object.keys(ctx.scopes).length > 0)
+        line.scopes ??= ctx.scopes;
+    if (ctx.service !== undefined)
+        line.service ??= ctx.service;
+    return info;
+});
+/** Redacts secrets and masks phones in the message and every metadata value. */
+const redact = (classifier) => winston.format((info) => {
+    const line = info;
+    if (typeof line.message === 'string')
+        line.message = maskPhonesInText(line.message);
+    const meta = Object.fromEntries(Object.entries(line).filter(([key]) => !RESERVED_KEYS.has(key) && !CONTEXT_KEYS.has(key)));
+    Object.assign(line, redactValue(meta, classifier));
     return info;
-})();
-const devFormat = printf((info) => {
+});
+/** One JSON object per line: `{ level, time, msg, service, correlationId, userId, scopes, ...meta }`. */
+const jsonLine = printf((info) => {
+    const { level, message, timestamp: time, service, correlationId, userId, scopes, ...meta } = info;
+    return JSON.stringify({ level, time, msg: message, service, correlationId, userId, scopes, ...meta });
+});
+const prettyLine = printf((info) => {
     const { level, message, timestamp: ts, service, stack, ...rest } = info;
-    const meta = Object.fromEntries(Object.entries(rest).filter(([k]) => typeof k === 'string' && k !== 'splat'));
-    const metaStr = Object.keys(meta).length ? ` ${JSON.stringify(meta)}` : '';
+    const metaStr = Object.keys(rest).length ? ` ${JSON.stringify(rest)}` : '';
     return `${String(ts ?? '')} ${String(level)}: ${service ? `[${String(service)}] ` : ''}${String(message)}${metaStr}${stack ? `\n${String(stack)}` : ''}`;
 });
-/** 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 function createLogger(service, options = {}) {
     const isProduction = process.env.NODE_ENV === 'production';
     const level = options.level ?? process.env.LOG_LEVEL ?? (isProduction ? 'info' : 'debug');
     const format = options.format ?? process.env.LOG_FORMAT ?? (isProduction ? 'json' : 'pretty');
-    const keys = new Set([...DEFAULT_REDACT_KEYS, ...(options.redactKeys ?? [])]);
+    const classifier = createKeyClassifier(options.redactKeys, options.allowKeys);
+    const transports = [
+        new winston.transports.Console({
+            silent: process.env.NODE_ENV === 'test' && !process.env.LOG_IN_TESTS,
+            format: format === 'json' ? jsonLine : combine(colorize({ level: true }), prettyLine),
+        }),
+    ];
+    if (options.filePath)
+        transports.push(new winston.transports.File({ filename: options.filePath, format: jsonLine }));
+    if (options.stream)
+        transports.push(new winston.transports.Stream({ stream: options.stream, format: jsonLine }));
     return winston.createLogger({
         level,
         defaultMeta: { service },
-        format: combine(errors({ stack: true }), splat(), redact(keys), timestamp()),
-        transports: [
-            new winston.transports.Console({
-                silent: process.env.NODE_ENV === 'test' && !process.env.LOG_IN_TESTS,
-                format: format === 'json' ? json() : combine(colorize({ level: true }), devFormat),
-            }),
-        ],
+        format: combine(errors({ stack: true }), splat(), withContext(), redact(classifier)(), timestamp()),
+        transports,
     });
 }
 /** Logger that discards everything — handy default for libraries and tests. */
@@ -58,6 +82,11 @@ export const silentLogger = { debug: () => { }, info: () => { }, warn: () => { }
  * 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 function childLogger(logger, context) {
     const base = Object.fromEntries(Object.entries(context).filter(([, v]) => v !== undefined));

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

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

package/dist/esm/logging/redact.js

@@ -0,0 +1,110 @@
+/**
+ * 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 const DEFAULT_REDACT_KEYS = [
+    'password', 'pass', 'passphrase', 'token', 'secret', 'code', 'otp', 'authorization', 'cookie', 'credential',
+    'pin', 'apikey', 'jwt', 'signature',
+];
+/** Keys that are never redacted although they contain a listed word (error, status and reference codes). */
+export const DEFAULT_ALLOW_KEYS = ['errorCode', 'statusCode', 'countryCode', 'currencyCode', 'postalCode', 'zipCode'];
+/** Words that mark a value as a phone number, masked to its last 4 digits. */
+const PHONE_KEY_WORDS = new Set(['phone', 'msisdn', 'mobile', 'tel']);
+/** 9–15 digits, optionally with a leading `+`, not part of a longer word or number. */
+const PHONE_IN_TEXT = /(?<![\w+]|\d\.)\+?\d{9,15}(?!\w|\.\d)/g;
+/** The marker that replaces a secret value. */
+export const REDACTED = '[REDACTED]';
+const MAX_DEPTH = 8;
+/**
+ * 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 function maskPhoneForLog(value) {
+    const digits = value.replace(/\D/g, '');
+    if (digits.length < 5)
+        return '*'.repeat(digits.length || 4);
+    return `${'*'.repeat(digits.length - 4)}${digits.slice(-4)}`;
+}
+/**
+ * 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 function maskPhonesInText(text) {
+    return text.replace(PHONE_IN_TEXT, maskPhoneForLog);
+}
+function keyWords(key) {
+    return key
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z])([A-Z][a-z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(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 function createKeyClassifier(extraKeys = [], allowKeys = DEFAULT_ALLOW_KEYS) {
+    const terms = new Set([...DEFAULT_REDACT_KEYS, ...extraKeys].map((k) => keyWords(k).join('')));
+    const allow = new Set(allowKeys);
+    const matches = (word) => terms.has(word) || (word.endsWith('s') && terms.has(word.slice(0, -1)));
+    return {
+        isSecret(key) {
+            if (allow.has(key))
+                return false;
+            if (key.endsWith('Enc') || key.endsWith('_enc'))
+                return true;
+            const words = keyWords(key);
+            if (matches(words.join('')))
+                return true;
+            return words.some((word, i) => matches(word) || (i > 0 && matches(`${words[i - 1]}${word}`)));
+        },
+        isPhone(key) {
+            return keyWords(key).some((word) => PHONE_KEY_WORDS.has(word));
+        },
+    };
+}
+/**
+ * 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 function redactValue(value, classifier, depth = 0) {
+    if (typeof value === 'string')
+        return maskPhonesInText(value);
+    if (value === null || typeof value !== 'object' || value instanceof Error || value instanceof Date)
+        return value;
+    if (depth >= MAX_DEPTH)
+        return '[TRUNCATED]';
+    if (Array.isArray(value))
+        return value.map((v) => redactValue(v, classifier, depth + 1));
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+        if (classifier.isSecret(key))
+            out[key] = REDACTED;
+        else if (classifier.isPhone(key) && (typeof v === 'string' || typeof v === 'number'))
+            out[key] = maskPhoneForLog(String(v));
+        else
+            out[key] = redactValue(v, classifier, depth + 1);
+    }
+    return out;
+}
+//# sourceMappingURL=redact.js.map

package/dist/esm/logging/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../../src/logging/redact.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qGAAqG;AACrG,MAAM,CAAC,MAAM,mBAAmB,GAAsB;IACpD,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,YAAY;IAC3G,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW;CACpC,CAAC;AAEF,4GAA4G;AAC5G,MAAM,CAAC,MAAM,kBAAkB,GAAsB,CAAC,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;AAEzI,8EAA8E;AAC9E,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;AAEtE,uFAAuF;AACvF,MAAM,aAAa,GAAG,wCAAwC,CAAC;AAE/D,+CAA+C;AAC/C,MAAM,CAAC,MAAM,QAAQ,GAAG,YAAY,CAAC;AACrC,MAAM,SAAS,GAAG,CAAC,CAAC;AAEpB;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACxC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;IAC7D,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW;IAC3B,OAAO,GAAG;SACP,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,OAAO,CAAC,sBAAsB,EAAE,OAAO,CAAC;SACxC,WAAW,EAAE;SACb,KAAK,CAAC,YAAY,CAAC;SACnB,MAAM,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC;AAQD;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAA+B,EAAE,EAAE,YAA+B,kBAAkB;IACtH,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,mBAAmB,EAAE,GAAG,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/F,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;IACjC,MAAM,OAAO,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1G,OAAO;QACL,QAAQ,CAAC,GAAG;YACV,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,OAAO,KAAK,CAAC;YACjC,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC7D,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;YACzC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAChG,CAAC;QACD,OAAO,CAAC,GAAG;YACT,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QACjE,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,UAAyB,EAAE,KAAK,GAAG,CAAC;IAC9E,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC9D,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,KAAK,CAAC;IACjH,IAAI,KAAK,IAAI,SAAS;QAAE,OAAO,aAAa,CAAC;IAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IACzF,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;QACxE,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;aAC7C,IAAI,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;;YACvH,GAAG,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/esm/messaging/index.js

@@ -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';
 /** Wires one connection with a publisher, consumer, RPC server/client and DLQ monitor. */
 export function createMessaging(options) {
     const logger = options.logger ?? silentLogger;

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/messaging/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,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,EAAE,cAAc,EAAiB,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;AAuBpC,0FAA0F;AAC1F,MAAM,UAAU,eAAe,CAAC,OAAyB;IACvD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,YAAY,CAAC;IAC9C,MAAM,QAAQ,GAAG,cAAc,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9E,MAAM,UAAU,GAAG,IAAI,cAAc,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5H,MAAM,SAAS,GAAG,IAAI,gBAAgB,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAClG,MAAM,QAAQ,GAAG,IAAI,eAAe,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACnE,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/E,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAEtF,OAAO;QACL,QAAQ;QACR,UAAU;QACV,SAAS;QACT,QAAQ;QACR,SAAS;QACT,SAAS;QACT,OAAO;QACP,KAAK,CAAC,KAAK;YACT,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC;YACvB,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC;YACvB,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;YACrB,MAAM,UAAU,CAAC,OAAO,EAAE,CAAC;QAC7B,CAAC;QACD,KAAK,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE;KAChC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/messaging/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,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,EAAE,cAAc,EAAiB,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;AAuBtC,0FAA0F;AAC1F,MAAM,UAAU,eAAe,CAAC,OAAyB;IACvD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,YAAY,CAAC;IAC9C,MAAM,QAAQ,GAAG,cAAc,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9E,MAAM,UAAU,GAAG,IAAI,cAAc,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5H,MAAM,SAAS,GAAG,IAAI,gBAAgB,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAClG,MAAM,QAAQ,GAAG,IAAI,eAAe,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACnE,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/E,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAEtF,OAAO;QACL,QAAQ;QACR,UAAU;QACV,SAAS;QACT,QAAQ;QACR,SAAS;QACT,SAAS;QACT,OAAO;QACP,KAAK,CAAC,KAAK;YACT,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC;YACvB,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC;YACvB,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;YACrB,MAAM,UAAU,CAAC,OAAO,EAAE,CAAC;QAC7B,CAAC;QACD,KAAK,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE;KAChC,CAAC;AACJ,CAAC"}

package/dist/esm/messaging/staff-notifier.js

@@ -1,31 +1,47 @@
-import { z } from 'zod';
-import { DISPATCH_LIMITS, NOTIFICATION_DISPATCH, } 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 { NOTIFICATION_DISPATCH, } from '../contracts/notification-dispatch.js';
 import { silentLogger } from '../logging/index.js';
-/** Recipients from configuration (env), keyed by the permission an alert targets. */
-export class ConfiguredStaffRecipients {
-    byPermission;
-    constructor(byPermission) {
-        this.byPermission = byPermission;
-    }
-    async resolve(permission) {
-        return [...(this.byPermission[permission] ?? [])];
-    }
-}
 /**
- * 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.
+ * 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 class StaffNotifier {
     outbox;
     recipients;
+    category;
+    defaultChannels;
+    command;
     logger;
-    constructor(outbox, recipients, logger = silentLogger) {
+    constructor(outbox, recipients, options) {
         this.outbox = outbox;
         this.recipients = recipients;
-        this.logger = logger;
+        this.category = options.category;
+        this.defaultChannels = options.defaultChannels;
+        this.command = options.command ?? NOTIFICATION_DISPATCH;
+        this.logger = options.logger ?? silentLogger;
     }
-    /** Returns how many commands were staged. */
+    /**
+     * 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).
+     */
     async alert(executor, alert, meta = {}) {
         const targets = await this.recipients.resolve(alert.permission);
         if (targets.length === 0) {
@@ -35,39 +51,16 @@ export class StaffNotifier {
         for (const recipient of targets) {
             const dispatch = {
                 template: alert.template,
-                category: 'staff',
+                category: this.category,
                 recipient,
-                channels: alert.channels ?? ['email'],
+                channels: [...(alert.channels ?? this.defaultChannels)],
                 data: alert.data,
                 bypassPreferences: true,
                 targetPermission: alert.permission,
             };
-            await this.outbox.command(executor, NOTIFICATION_DISPATCH, dispatch, { ...meta, actorId: null });
+            await this.outbox.command(executor, this.command, dispatch, { ...meta, actorId: null });
         }
         return targets.length;
     }
 }
-const emailSchema = z.string().email().max(DISPATCH_LIMITS.email);
-/**
- * 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 const staffEmailListSchema = z
-    .string()
-    .optional()
-    .transform((csv) => {
-    const seen = new Set();
-    return (csv ?? '')
-        .split(',')
-        .map((entry) => entry.trim())
-        .filter((email) => email && !seen.has(email.toLowerCase()) && seen.add(email.toLowerCase()));
-})
-    .superRefine((emails, ctx) => {
-    for (const email of emails) {
-        if (!emailSchema.safeParse(email).success)
-            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `Not a valid email address: ${email}` });
-    }
-})
-    .transform((emails) => emails.map((email) => ({ email })));
 //# sourceMappingURL=staff-notifier.js.map

package/dist/esm/messaging/staff-notifier.js.map

@@ -1 +1 @@
-{"version":3,"file":"staff-notifier.js","sourceRoot":"","sources":["../../../src/messaging/staff-notifier.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"staff-notifier.js","sourceRoot":"","sources":["../../../src/messaging/staff-notifier.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,qBAAqB,GAGtB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAsDnD;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,aAAa;IAOL;IACA;IAPF,QAAQ,CAAI;IACZ,eAAe,CAAyB;IACxC,OAAO,CAAS;IAChB,MAAM,CAAS;IAEhC,YACmB,MAAwB,EACxB,UAAkC,EACnD,OAAoC;QAFnB,WAAM,GAAN,MAAM,CAAkB;QACxB,eAAU,GAAV,UAAU,CAAwB;QAGnD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC/C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,qBAAqB,CAAC;QACxD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,YAAY,CAAC;IAC/C,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,KAAK,CAAC,QAAW,EAAE,KAAqB,EAAE,OAAuB,EAAE;QACvE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAChE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oDAAoD,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;YACnI,OAAO,CAAC,CAAC;QACX,CAAC;QACD,KAAK,MAAM,SAAS,IAAI,OAAO,EAAE,CAAC;YAChC,MAAM,QAAQ,GAAuC;gBACnD,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,SAAS;gBACT,QAAQ,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC,eAAe,CAAC,CAAC;gBACvD,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,iBAAiB,EAAE,IAAI;gBACvB,gBAAgB,EAAE,KAAK,CAAC,UAAU;aACnC,CAAC;YACF,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1F,CAAC;QACD,OAAO,OAAO,CAAC,MAAM,CAAC;IACxB,CAAC;CACF"}

package/dist/esm/messaging/staff-recipients.js

@@ -0,0 +1,53 @@
+/**
+ * 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 { DISPATCH_LIMITS } from '../contracts/notification-dispatch.js';
+/**
+ * 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 class ConfiguredStaffRecipients {
+    byPermission;
+    constructor(byPermission) {
+        this.byPermission = byPermission;
+    }
+    /**
+     * @param permission The permission an alert targets.
+     * @returns A copy of the configured recipients, or `[]` when none are configured.
+     */
+    async resolve(permission) {
+        return [...(this.byPermission[permission] ?? [])];
+    }
+}
+const emailSchema = z.string().email().max(DISPATCH_LIMITS.email);
+/**
+ * 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 const staffEmailListSchema = z
+    .string()
+    .optional()
+    .transform((csv) => {
+    const seen = new Set();
+    return (csv ?? '')
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((email) => email && !seen.has(email.toLowerCase()) && seen.add(email.toLowerCase()));
+})
+    .superRefine((emails, ctx) => {
+    for (const email of emails) {
+        if (!emailSchema.safeParse(email).success)
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `Not a valid email address: ${email}` });
+    }
+})
+    .transform((emails) => emails.map((email) => ({ email })));
+//# sourceMappingURL=staff-recipients.js.map

package/dist/esm/messaging/staff-recipients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staff-recipients.js","sourceRoot":"","sources":["../../../src/messaging/staff-recipients.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAA0B,MAAM,uCAAuC,CAAC;AAehG;;;;;GAKG;AACH,MAAM,OAAO,yBAAyB;IACP;IAA7B,YAA6B,YAAoE;QAApE,iBAAY,GAAZ,YAAY,CAAwD;IAAG,CAAC;IAErG;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,UAAkB;QAC9B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACpD,CAAC;CACF;AAED,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;AAElE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,EAAE;KACR,QAAQ,EAAE;KACV,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE;IACjB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC;SACf,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SAC5B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;AACjG,CAAC,CAAC;KACD,WAAW,CAAC,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE;IAC3B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO;YAAE,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,8BAA8B,KAAK,EAAE,EAAE,CAAC,CAAC;IAC3I,CAAC;AACH,CAAC,CAAC;KACD,SAAS,CAAC,CAAC,MAAM,EAAuB,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC"}

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":"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"}
+{"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,iHAAiH;AACjH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;AAEnE,4GAA4G;AAC5G,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;AAExD;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,aAAa,CAAC;AAErC,kHAAkH;AAClH,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,uCAAuC;AACvC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AAEvE,yDAAyD;AACzD,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,+CAA+C;AAC/C,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;;;;;;GAMG;AACH,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;;;;;;;GAOG;AACH,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,yFAAyF;AACzF,OAAO,EAAE,CAAC,EAAE,CAAC"}

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/cache/index.d.ts

@@ -34,7 +34,7 @@ export declare function createCache(options: CacheOptions): Cache;
 export interface RedisClientOptions {
     url?: string;
     db?: number;
-    /** Prepended to every key by ioredis, e.g. `showbiz:prod:`. */
+    /** Prepended to every key by ioredis, e.g. `myapp:prod:`. */
     keyPrefix?: string;
     logger?: Logger;
     options?: RedisOptions;