@heavybit/shared-lib 1.3.2 → 2.7.0

package/dist/esm/knex/index.js

@@ -1,29 +1,12 @@
+import { DEFAULT_OUTBOX_TABLE } from '../database/table-names.js';
+import { actorColumns, timestamps, ulidColumn, ulidPrimary } from './columns.js';
+import { outboxColumns } from './migration-helpers.js';
+export * from './columns.js';
+export * from './migration-helpers.js';
 /**
  * Migration helpers (usable from CommonJS `.cjs` migrations via `require('@heavybit/shared-lib/knex')`).
  * They keep ID, timestamp and audit column definitions identical across services.
  */
-/** `id CHAR(26)` primary key for ULIDs. */
-export function ulidPrimary(table, name = 'id') {
-    table.specificType(name, 'char(26)').notNullable().primary();
-}
-/** `CHAR(26)` column referencing another ULID (FK constraints only within the same database). */
-export function ulidColumn(table, name) {
-    return table.specificType(name, 'char(26)');
-}
-/** `created_at` / `updated_at` as `DATETIME(3)` in UTC, maintained by MySQL. */
-export function timestamps(table, knex) {
-    table.specificType('created_at', 'datetime(3)').notNullable().defaultTo(knex.raw('CURRENT_TIMESTAMP(3)'));
-    table.specificType('updated_at', 'datetime(3)').notNullable().defaultTo(knex.raw('CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3)'));
-}
-/** `created_by` / `updated_by` actor columns (null for system operations). */
-export function actorColumns(table) {
-    ulidColumn(table, 'created_by').nullable();
-    ulidColumn(table, 'updated_by').nullable();
-}
-/** Nullable `DATETIME(3)` column. */
-export function datetime(table, name) {
-    return table.specificType(name, 'datetime(3)');
-}
 /**
  * Creates `<parent>_audits`: every parent column (defined again by `columns`) plus `parent_id`
  * and `action`. Audit rows are append-only history, so no unique constraints are copied.
@@ -42,20 +25,11 @@ export async function createAuditTable(knex, parentTable, columns) {
         table.index(['parent_id', 'created_at']);
     });
 }
-/** Transactional outbox table used by `OutboxRelay`. */
-export async function createOutboxTable(knex, name = 'event_outbox') {
+/** Transactional outbox table used by `OutboxRelay` (columns from {@link outboxColumns}). */
+export async function createOutboxTable(knex, name = DEFAULT_OUTBOX_TABLE) {
     if (await knex.schema.hasTable(name))
         return;
-    await knex.schema.createTable(name, (table) => {
-        ulidPrimary(table);
-        table.string('routing_key', 191).notNullable();
-        table.json('payload').notNullable();
-        table.integer('attempts').unsigned().notNullable().defaultTo(0);
-        table.string('last_error', 500).nullable();
-        table.specificType('created_at', 'datetime(3)').notNullable().defaultTo(knex.raw('CURRENT_TIMESTAMP(3)'));
-        datetime(table, 'published_at').nullable();
-        table.index(['published_at', 'id']);
-    });
+    await knex.schema.createTable(name, (table) => outboxColumns(table, knex));
 }
 /** Standard table options: InnoDB, utf8mb4. Call inside `createTable`. */
 export function utf8mb4(table) {

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/knex/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/knex/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAY,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3F,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AAEvC;;;GAGG;AAEH;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAU,EAAE,WAAmB,EAAE,OAAiD;IACvH,MAAM,IAAI,GAAG,GAAG,WAAW,SAAS,CAAC;IACrC,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO;IAC7C,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE;QAC5C,WAAW,CAAC,KAAK,CAAC,CAAC;QACnB,UAAU,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,CAAC;QACrD,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QAClE,OAAO,CAAC,KAAK,CAAC,CAAC;QACf,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACxB,KAAK,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC;AAED,6FAA6F;AAC7F,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAU,EAAE,IAAI,GAAG,oBAAoB;IAC7E,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO;IAC7C,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,OAAO,CAAC,KAA8B;IACpD,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACvB,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACzB,KAAK,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;AACtC,CAAC"}

package/dist/esm/knex/migration-helpers.js

@@ -0,0 +1,51 @@
+import { OUTBOX_EXCHANGES, SCHEDULER_RUN_STATUSES } from '../database/table-names.js';
+import { createdAtColumn, datetime, ulidPrimary } from './columns.js';
+/**
+ * Outbox columns: id, routing_key, exchange, payload, correlation_id, attempts, last_error, created_at,
+ * published_at (+ relay index).
+ */
+export function outboxColumns(t, knex) {
+    ulidPrimary(t);
+    t.string('routing_key', 191).notNullable();
+    t.enu('exchange', [...OUTBOX_EXCHANGES]).notNullable().defaultTo('events');
+    t.json('payload').notNullable();
+    t.string('correlation_id', 64).nullable();
+    t.integer('attempts').unsigned().notNullable().defaultTo(0);
+    t.string('last_error', 500).nullable();
+    createdAtColumn(t, knex, 'created_at');
+    datetime(t, 'published_at').nullable();
+    t.index(['published_at', 'id']);
+}
+/** Consumer idempotency columns: id, consumer, event_id (unique together), processed_at. */
+export function processedEventsColumns(t, knex) {
+    ulidPrimary(t);
+    t.string('consumer', 191).notNullable();
+    t.string('event_id', 64).notNullable();
+    createdAtColumn(t, knex, 'processed_at');
+    t.unique(['consumer', 'event_id']);
+    t.index(['processed_at']);
+}
+/** Scheduler run columns: id, job, run_key (unique together), status, error, started_at, finished_at. */
+export function schedulerRunsColumns(t, knex) {
+    ulidPrimary(t);
+    t.string('job', 191).notNullable();
+    t.string('run_key', 191).notNullable();
+    t.enu('status', [...SCHEDULER_RUN_STATUSES]).notNullable().defaultTo('running');
+    t.string('error', 500).nullable();
+    createdAtColumn(t, knex, 'started_at');
+    datetime(t, 'finished_at').nullable();
+    t.unique(['job', 'run_key']);
+    t.index(['job', 'started_at']);
+}
+/**
+ * Index that always leads with the scope column (TEN-4); `columns` follow in order, duplicates of
+ * the scope column are dropped.
+ *
+ * @example scopedIndex(t, 'workspace_id', ['status', 'created_at'])
+ */
+export function scopedIndex(t, scopeColumn, columns = [], indexName) {
+    if (!scopeColumn)
+        throw new Error('scopedIndex needs a scope column');
+    t.index([scopeColumn, ...columns.filter((c) => c !== scopeColumn)], indexName);
+}
+//# sourceMappingURL=migration-helpers.js.map

package/dist/esm/knex/migration-helpers.js.map

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

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":"AACA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,WAAW,EAAsB,MAAM,aAAa,CAAC;AAErG,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,QAAQ,EAAE,mBAAmB,EAAE,eAAe,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGrJ,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;AAE/E,8DAA8D;AAC9D,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;AAC1E,6EAA6E;AAC7E,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,eAAe,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE/E,0GAA0G;AAC1G,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;IAC1C,MAAM,GAAG,GAAG,iBAAiB,EAAE,CAAC;IAChC,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,IAAI,GAAG,IAA+B,CAAC;IAC7C,IAAI,CAAC,aAAa,KAAK,GAAG,CAAC,aAAa,CAAC;IACzC,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS;QAAE,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC;IACzD,IAAI,GAAG,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC;IACjF,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS;QAAE,IAAI,CAAC,OAAO,KAAK,GAAG,CAAC,OAAO,CAAC;IAC5D,OAAO,IAAI,CAAC;AACd,CAAC,CAAC,CAAC;AAEH,gFAAgF;AAChF,MAAM,MAAM,GAAG,CAAC,UAAyB,EAAE,EAAE,CAC3C,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;IACtB,MAAM,IAAI,GAAG,IAA+B,CAAC;IAC7C,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ;QAAE,IAAI,CAAC,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpF,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC3H,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;IACnD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC,CAAC;AAEL,yGAAyG;AACzG,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;IAC/B,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,IAA+B,CAAC;IAC7H,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AACxG,CAAC,CAAC,CAAC;AAEH,MAAM,UAAU,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;IACjC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,IAA+B,CAAC;IACnG,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3E,OAAO,GAAG,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AAC3J,CAAC,CAAC,CAAC;AAkBH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,UAAyB,EAAE;IACvE,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC;IAC3D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC1F,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAK,OAAO,CAAC,GAAG,CAAC,UAA4C,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IACjI,MAAM,UAAU,GAAG,mBAAmB,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAE9E,MAAM,UAAU,GAAwB;QACtC,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC;YAC7B,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY;YACpE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,UAAU,CAAC;SACtF,CAAC;KACH,CAAC;IACF,IAAI,OAAO,CAAC,QAAQ;QAAE,UAAU,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IACrH,IAAI,OAAO,CAAC,MAAM;QAAE,UAAU,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IAEjH,OAAO,OAAO,CAAC,YAAY,CAAC;QAC1B,KAAK;QACL,WAAW,EAAE,EAAE,OAAO,EAAE;QACxB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC;QACnG,UAAU;KACX,CAA4B,CAAC;AAChC,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,MAAM,YAAY,GAAW,EAAE,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;AAEzG;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,OAAgC;IAC1E,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC;IAC5F,MAAM,KAAK,GAAG,CAAC,KAAmB,EAAE,EAAE,CAAC,CAAC,OAAe,EAAE,IAA8B,EAAE,EAAE,CACzF,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;AACpG,CAAC"}

package/dist/esm/logging/redact.js

@@ -0,0 +1,106 @@
+/**
+ * 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.
+ */
+import { maskPhone } from '../common/phone.js';
+/** 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; the same rule as `maskPhone` in common (one rule for logs and UI).
+ *
+ * @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 const maskPhoneForLog = maskPhone;
+/**
+ * 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":"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"}

package/dist/esm/messaging/base-consumer.js

@@ -0,0 +1,32 @@
+/**
+ * Base for a service's queue consumers (one class per queue in `src/consumers/`). The subclass declares
+ * its queue, bindings, payload schema, retry policy, dedupe and scope in the constructor and implements
+ * {@link BaseConsumer.handle}; `worker.ts` registers it. Validation, dedupe, retries, dead-lettering and
+ * context restore are done by {@link MessageConsumer}.
+ *
+ * @typeParam T Validated payload type.
+ * @typeParam TTx Dedupe transaction type (`DbExecutor` with `ProcessedEventsDeduper`).
+ * @example
+ * class ThingCreatedConsumer extends BaseConsumer<ThingCreated, DbExecutor> {
+ *   constructor(private readonly things: ThingService, dedupe: ProcessedEventsDeduper) {
+ *     super({ queue: 'thing-created', bindings: [{ exchange: 'events', routingKey: 'thing.created' }],
+ *       schema: thingCreatedSchema, dedupe, scopeFrom: (d) => ({ tenantId: d.tenantId }) });
+ *   }
+ *   protected handle({ data, tx, scope }: InboundMessage<ThingCreated, DbExecutor>) { return this.things.onCreated(scope!, data, tx!); }
+ * }
+ */
+export class BaseConsumer {
+    definition;
+    constructor(definition) {
+        this.definition = definition;
+    }
+    /**
+     * Subscribes this consumer.
+     *
+     * @param consumer The service's {@link MessageConsumer}.
+     */
+    register(consumer) {
+        return consumer.subscribe({ ...this.definition, handler: (message) => this.handle(message) });
+    }
+}
+//# sourceMappingURL=base-consumer.js.map

package/dist/esm/messaging/base-consumer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-consumer.js","sourceRoot":"","sources":["../../../src/messaging/base-consumer.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAgB,YAAY;IACS;IAAzC,YAAyC,UAAsC;QAAtC,eAAU,GAAV,UAAU,CAA4B;IAAG,CAAC;IAKnF;;;;OAIG;IACH,QAAQ,CAAC,QAAyB;QAChC,OAAO,QAAQ,CAAC,SAAS,CAAS,EAAE,GAAG,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACxG,CAAC;CACF"}