@heavybit/shared-lib 1.3.1 → 2.1.0

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

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

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

@@ -3,6 +3,12 @@ export type ErrorDetails = Record<string, string[]>;
  * Base class for errors that map to an HTTP status. Throw these from services; the shared
  * error middleware turns them into the standard envelope. Anything that is not an AppError is
  * reported as a 500 with a generic message so internals never leak.
+ *
+ * @param statusCode HTTP status. 4xx messages reach the caller; 5xx messages never do.
+ * @param message Caller-facing message (4xx) or log message (5xx).
+ * @param options `code` (defaults from the status), field `errors`, `retryable` (consumers),
+ *   `retryAfterSeconds` (sent as `Retry-After`) and `cause`.
+ * @example throw new AppError(402, 'Payment is required first', { code: 'PAYMENT_REQUIRED' });
  */
 export declare class AppError extends Error {
     readonly statusCode: number;
@@ -10,48 +16,73 @@ export declare class AppError extends Error {
     readonly errors?: ErrorDetails;
     /** Consumers dead-letter immediately instead of retrying when this is false. */
     readonly retryable: boolean;
-    constructor(statusCode: number, message: string, options?: {
-        code?: string;
-        errors?: ErrorDetails;
-        retryable?: boolean;
-        cause?: unknown;
-    });
+    /** Seconds the caller should wait before retrying; the error middleware sends it as `Retry-After`. */
+    readonly retryAfterSeconds?: number;
+    constructor(statusCode: number, message: string, options?: AppErrorOptions);
+}
+/** Options for {@link AppError}. `code` should be UPPER_SNAKE_CASE; it defaults from the status. */
+export interface AppErrorOptions {
+    code?: string;
+    errors?: ErrorDetails;
+    retryable?: boolean;
+    retryAfterSeconds?: number;
+    cause?: unknown;
 }
+/**
+ * Shorthand for an error with an explicit status and code.
+ *
+ * @param statusCode HTTP status (4xx messages reach the caller; 5xx are replaced with a generic message).
+ * @param code UPPER_SNAKE_CASE machine-readable code, e.g. `SLUG_TAKEN`.
+ * @param message Human-readable message for 4xx responses.
+ * @param errors Optional field errors (`{ 'items.0.qty': ['Must be positive'] }`).
+ * @returns An {@link AppError} to `throw`.
+ * @example throw httpError(409, 'SLUG_TAKEN', 'That address is already in use');
+ */
+export declare function httpError(statusCode: number, code: string, message: string, errors?: ErrorDetails): AppError;
+/** 400 BAD_REQUEST: the request is malformed or breaks a business rule. */
 export declare class BadRequestError extends AppError {
     constructor(message?: string, options?: {
         code?: string;
         errors?: ErrorDetails;
     });
 }
+/** 401 UNAUTHENTICATED: no valid identity. */
 export declare class UnauthorizedError extends AppError {
     constructor(message?: string, options?: {
         code?: string;
     });
 }
+/** 403 FORBIDDEN: authenticated, but not allowed. */
 export declare class ForbiddenError extends AppError {
     constructor(message?: string, options?: {
         code?: string;
     });
 }
+/** 404 NOT_FOUND. Also use it for out-of-scope resources so their existence is not revealed. */
 export declare class NotFoundError extends AppError {
     constructor(message?: string, options?: {
         code?: string;
     });
 }
+/** 409 CONFLICT: duplicate or state conflict. */
 export declare class ConflictError extends AppError {
     constructor(message?: string, options?: {
         code?: string;
         errors?: ErrorDetails;
     });
 }
+/** 422 VALIDATION_FAILED with field errors (`{ 'items.0.qty': ['…'] }`). */
 export declare class ValidationError extends AppError {
     constructor(errors: ErrorDetails, message?: string);
 }
+/** 429. Pass `retryAfterSeconds` so the error middleware sets the `Retry-After` header. */
 export declare class TooManyRequestsError extends AppError {
     constructor(message?: string, options?: {
         code?: string;
+        retryAfterSeconds?: number;
     });
 }
+/** 503 SERVICE_UNAVAILABLE: a dependency is down. The message is logged, never sent (callers see the generic one). */
 export declare class ServiceUnavailableError extends AppError {
     constructor(message?: string, options?: {
         code?: string;
@@ -65,7 +96,17 @@ export declare class NonRetryableError extends AppError {
         cause?: unknown;
     });
 }
+/** Type guard for {@link AppError} (and its subclasses). */
 export declare function isAppError(error: unknown): error is AppError;
-/** Message safe to show a caller; hides internals for unexpected errors. */
+/** The message every 5xx response carries. */
+export declare const GENERIC_ERROR_MESSAGE = "Internal server error";
+/**
+ * Message safe to show a caller. Only 4xx AppErrors keep their own message; every 5xx (including
+ * 503s, whose messages often name upstreams or RPC methods) and every non-AppError get the generic one.
+ *
+ * @param error Anything thrown.
+ * @returns The message to put in the response body.
+ * @example publicMessage(new NotFoundError('Order not found')) // 'Order not found'
+ */
 export declare function publicMessage(error: unknown): string;
 //# sourceMappingURL=errors.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/common/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAEpD;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,YAAY,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAQ9I;AAgBD,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,SAAgB,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,YAAY,CAAA;KAAO;CAC5F;AACD,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,SAA4B,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;CACjF;AACD,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,SAAsD,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;CAC3G;AACD,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,SAAuB,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;CAC5E;AACD,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,SAA4B,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,YAAY,CAAA;KAAO;CACxG;AACD,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,MAAM,EAAE,YAAY,EAAE,OAAO,SAAsB;CAChE;AACD,qBAAa,oBAAqB,SAAQ,QAAQ;gBACpC,OAAO,SAA+C,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;CACpG;AACD,qBAAa,uBAAwB,SAAQ,QAAQ;gBACvC,OAAO,SAAoC,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAC1G;AAED,qFAAqF;AACrF,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAG9E;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIpD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/common/errors.ts"],"names":[],"mappings":"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"}

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

@@ -1,10 +1,39 @@
 /**
- * Normalises a phone number to E.164 (`+254712345678`). Returns null for anything that is not a
- * valid number for the given default region.
+ * Normalises a phone number to E.164. The region is required (no app default): local formats such as
+ * `0712345678` only make sense against a country, and that country is app configuration.
+ *
+ * @param phone Number as typed (local or international format).
+ * @param region ISO 3166-1 alpha-2 region used for local formats (e.g. `KE`, `GB`).
+ * @returns E.164 (`+254712345678`), or null when not a valid number for that region.
+ * @example toE164('0712345678', 'KE') // '+254712345678'
+ */
+export declare function toE164(phone: string, region: string): string | null;
+/**
+ * E.164 without the plus sign, as most SMS gateways expect.
+ *
+ * @param phone Number as typed.
+ * @param region ISO region for local formats.
+ * @returns Digits only, or null when invalid.
+ * @example toMsisdn('0712345678', 'KE') // '254712345678'
+ */
+export declare function toMsisdn(phone: string, region: string): string | null;
+/**
+ * The region a number belongs to.
+ *
+ * @param phone Number as typed.
+ * @param region ISO region used to interpret local formats.
+ * @returns ISO region code, or null when it cannot be determined.
+ * @example phoneRegion('+447400123456', 'KE') // 'GB'
+ */
+export declare function phoneRegion(phone: string, region: string): string | null;
+/**
+ * Masks a phone number for logs and UI, so a full number never lands in a log line or screen.
+ * Never reveals more than about a third of the input: numbers of 10+ characters keep the first 4 and
+ * last 2; shorter inputs keep only the last 2; 4 characters or fewer are fully masked.
+ *
+ * @param phone Any phone string (normalised or not).
+ * @returns The masked value.
+ * @example maskPhone('254712345678') // '2547****78'
  */
-export declare function toE164(phone: string, defaultRegion?: string): string | null;
-/** E.164 without the plus sign, as most SMS gateways expect (`254712345678`). */
-export declare function toMsisdn(phone: string, defaultRegion?: string): string | null;
-export declare function phoneRegion(phone: string, defaultRegion?: string): string | null;
 export declare function maskPhone(phone: string): string;
 //# sourceMappingURL=phone.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"phone.d.ts","sourceRoot":"","sources":["../../../src/common/phone.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,SAAO,GAAG,MAAM,GAAG,IAAI,CAOzE;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,SAAO,GAAG,MAAM,GAAG,IAAI,CAG3E;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,SAAO,GAAG,MAAM,GAAG,IAAI,CAM9E;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C"}
+{"version":3,"file":"phone.d.ts","sourceRoot":"","sources":["../../../src/common/phone.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOnE;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGrE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI/C"}

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

@@ -1,12 +1,73 @@
-import type { ApiResponse, PaginationMeta, PaginatedResult } from '../types/index.js';
-/** Standard success envelope: `{ success, message, data }`. */
+import type { ApiResponse, CursorPage, CursorPageMeta, ErrorBody, PaginationMeta, PaginatedResult } from '../types/index.js';
+/**
+ * Standard success envelope: `{ success, message, data }`.
+ *
+ * @param data Payload placed under `data`.
+ * @param message Human-readable message (default `Success`).
+ * @returns The envelope, ready for `res.json`.
+ * @example res.json(successResponse(order, 'Order placed'));
+ */
 export declare function successResponse<T>(data: T, message?: string): ApiResponse<T>;
-/** Standard error envelope: `{ success: false, message, code?, errors? }`. */
-export declare function errorResponse(message: string, errors?: Record<string, string[]>, code?: string): ApiResponse<never>;
+/**
+ * Standard error envelope: `{ success: false, message, code?, errors?, requestId? }`.
+ * Prefer throwing an AppError and letting the error middleware answer; use this only where a
+ * middleware must answer directly. For a body with a guaranteed `code`, use {@link errorBody}.
+ *
+ * @param message Message for the caller (never an internal error message).
+ * @param errors Optional field errors.
+ * @param code Optional UPPER_SNAKE_CASE code.
+ * @param requestId Optional correlation id of the request.
+ * @returns An envelope with `success: false`.
+ */
+export declare function errorResponse(message: string, errors?: Record<string, string[]>, code?: string, requestId?: string): ApiResponse<never>;
+/**
+ * The error body with a required `code`, as the error middleware sends it.
+ *
+ * @param code UPPER_SNAKE_CASE machine-readable code.
+ * @param message Message for the caller (generic for 5xx).
+ * @param options `errors` (field errors) and `requestId` (correlation id), both omitted when absent.
+ * @returns `{ success: false, code, message, errors?, requestId? }`.
+ *
+ * @example res.status(404).json(errorBody('NOT_FOUND', 'Resource not found', { requestId }));
+ */
+export declare function errorBody(code: string, message: string, options?: {
+    errors?: Record<string, string[]>;
+    requestId?: string;
+}): ErrorBody;
+/**
+ * Offset pagination meta. `totalPages` is at least 1 so an empty list still reads as "page 1 of 1".
+ *
+ * @param total Total matching rows.
+ * @param page 1-based page that was returned.
+ * @param limit Page size.
+ * @returns `{ page, limit, total, totalPages, hasNext, hasPrev }`.
+ * @example buildPaginationMeta(45, 2, 20) // { page: 2, totalPages: 3, hasNext: true, hasPrev: true, … }
+ */
 export declare function buildPaginationMeta(total: number, page: number, limit: number): PaginationMeta;
-/** Paginated envelope: `{ success, message, data: T[], meta }`. */
+/**
+ * Offset-paginated envelope: `{ success, message, data: T[], meta }`.
+ *
+ * @returns The envelope with meta from {@link buildPaginationMeta}.
+ * @example res.json(paginatedResponse(rows, total, page, limit));
+ */
 export declare function paginatedResponse<T>(data: T[], total: number, page: number, limit: number, message?: string): ApiResponse<T[]>;
+/**
+ * Offset page as a service returns it (data + meta, no envelope).
+ *
+ * @returns `{ data, meta }`.
+ * @example return buildPaginatedResult(rows, total, page, limit);
+ */
 export declare function buildPaginatedResult<T>(data: T[], total: number, page: number, limit: number): PaginatedResult<T>;
 /** SQL offset for 1-based pages. */
 export declare function pageOffset(page: number, limit: number): number;
+/**
+ * Cursor pagination meta. `hasMore` is derived from `nextCursor`, so the two can never disagree.
+ *
+ * @param limit The page size that was applied.
+ * @param nextCursor Opaque cursor for the next page, or null on the last page.
+ * @example buildCursorPageMeta(20, rows.length > 20 ? encodeCursor(rows[19]) : null)
+ */
+export declare function buildCursorPageMeta(limit: number, nextCursor: string | null): CursorPageMeta;
+/** Cursor-paginated envelope: `{ success, message, data: T[], meta: { limit, nextCursor, hasMore } }`. */
+export declare function cursorPaginatedResponse<T>(page: CursorPage<T>, message?: string): ApiResponse<T[]>;
 //# sourceMappingURL=response.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../../src/common/response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEtF,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,SAAY,GAAG,WAAW,CAAC,CAAC,CAAC,CAE/E;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAEnH;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAG9F;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,SAAY,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAEjI;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,CAEjH;AAED,oCAAoC;AACpC,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D"}
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../../src/common/response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,SAAS,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE7H;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,SAAY,GAAG,WAAW,CAAC,CAAC,CAAC,CAE/E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAEvI;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,SAAS,CAQ3I;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAG9F;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,SAAY,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAEjI;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,CAEjH;AAED,oCAAoC;AACpC,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc,CAE5F;AAED,0GAA0G;AAC1G,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,OAAO,SAAY,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAErG"}

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

@@ -8,7 +8,7 @@ export declare const serviceEnv: z.ZodObject<{
     NODE_ENV: z.ZodDefault<z.ZodEnum<["development", "test", "staging", "production"]>>;
     PORT: z.ZodNumber;
     SERVICE_NAME: z.ZodString;
-    /** Short app identifier used in exchange names and key prefixes (e.g. `showbiz`). */
+    /** Short app identifier used in exchange names and key prefixes (e.g. `myapp`). */
     APP_NAME: z.ZodDefault<z.ZodString>;
     LOG_LEVEL: z.ZodOptional<z.ZodEnum<["error", "warn", "info", "http", "debug"]>>;
     CORS_ORIGINS: z.ZodDefault<z.ZodString>;

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

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

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

@@ -0,0 +1,39 @@
+/**
+ * Per-request values that follow the request through every `await`, timer and callback, so loggers,
+ * error handlers and outbound clients can read them without threading `req` through every call.
+ * `scopes` is a generic map of the scope ids the caller acts within (for example `{ tenant: '01J…' }`);
+ * the app decides the key names.
+ */
+export interface RequestContext {
+    correlationId: string;
+    service?: string;
+    userId?: string;
+    scopes?: Record<string, string>;
+}
+/**
+ * Runs `fn` (and all async work it starts) inside `context`. Use it at every entry point that is not an
+ * HTTP request: queue consumers, jobs and scripts.
+ *
+ * @param context Values for the duration of `fn`; the object is copied, so later edits don't leak back.
+ * @param fn Work to run inside the context.
+ * @returns Whatever `fn` returns.
+ * @example await runWithContext({ correlationId: msg.correlationId, service: 'worker' }, () => handle(msg));
+ */
+export declare function runWithContext<T>(context: RequestContext, fn: () => T): T;
+/**
+ * The current request context.
+ *
+ * @returns The context, or undefined outside {@link runWithContext} / `correlationMiddleware`.
+ * @example const id = getRequestContext()?.correlationId;
+ */
+export declare function getRequestContext(): Readonly<RequestContext> | undefined;
+/**
+ * Adds values to the current context, for example the user id and scopes once auth has run. A no-op
+ * outside a context. The correlation id can't be changed once set.
+ *
+ * @param patch Values to add or replace; `scopes` are merged key by key.
+ * @returns True when a context was active and updated.
+ * @example updateRequestContext({ userId: user.id, scopes: user.scopes });
+ */
+export declare function updateRequestContext(patch: Partial<Omit<RequestContext, 'correlationId'>>): boolean;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/context/index.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAID;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,QAAQ,CAAC,cAAc,CAAC,GAAG,SAAS,CAExE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,GAAG,OAAO,CAOnG"}

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

@@ -1,4 +1,2 @@
-export * from './editorial-draft.js';
 export * from './notification-dispatch.js';
-export * from './upload-import.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/contracts/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/contracts/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC"}