@heavybit/shared-lib 1.3.2 → 2.7.0

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/common/time.d.ts

@@ -1,4 +1,4 @@
-/** True for IANA zones the runtime knows (`Africa/Nairobi`), false for garbage. */
+/** True for IANA zones the runtime knows (`Europe/Berlin`), false for garbage. */
 export declare function isValidTimeZone(zone: string): boolean;
 /** Formats an instant in a zone, e.g. `30 Sep 2026, 14:05 EAT`. Falls back to UTC for invalid zones. */
 export declare function formatInTimeZone(date: Date | string | number, zone: string, locale?: string): string;
@@ -27,7 +27,16 @@ export declare function parseClockTime(value: string): number;
  * time skipped by a spring-forward resolves to the nearest valid instant.
  */
 export declare function zonedWallTimeToInstant(year: number, month: number, day: number, minutesOfDay: number, zone: string): Date;
-/** The local calendar day containing `at` in `zone`, as a half-open `[start, end)` UTC range (23–25 h on DST days). */
+/**
+ * The local calendar day containing `at` in `zone`, as a half-open `[start, end)` UTC range (23–25 h on
+ * DST days). Use it for "today" in reports, business days and daily limits.
+ *
+ * @param at Any instant in the day.
+ * @param zone IANA zone (required; no app default).
+ * @returns `{ start, end }` with `start` inclusive and `end` exclusive.
+ * @throws RangeError for an unknown zone.
+ * @example zonedDayBounds(new Date('2026-10-11T22:30:00Z'), 'Asia/Riyadh') // 2026-10-11T21:00Z → 2026-10-12T21:00Z
+ */
 export declare function zonedDayBounds(at: Date, zone: string): {
     start: Date;
     end: Date;
@@ -37,4 +46,13 @@ export declare function zonedDayBounds(at: Date, zone: string): {
  * cross midnight), the instant that window ends; otherwise null. `start === end` means no window.
  */
 export declare function quietWindowEndAt(at: Date, zone: string, start: string, end: string): Date | null;
+/**
+ * The instant as a UTC ISO-8601 string (`2026-11-13T09:00:00.000Z`), the form every timestamp travels in.
+ *
+ * @param instant A Date, an epoch-milliseconds number or a string `Date` can parse.
+ * @returns The `toISOString()` form.
+ * @throws RangeError when the input is not a valid instant (never returns `"Invalid Date"`).
+ * @example toUtcIso('2026-11-13T12:00:00+03:00') // '2026-11-13T09:00:00.000Z'
+ */
+export declare function toUtcIso(instant: Date | string | number): string;
 //# sourceMappingURL=time.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../../src/common/time.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED,wGAAwG;AACxG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,SAAU,GAAG,MAAM,CAWrG;AAED,MAAM,WAAW,SAAS;IACxB,wGAAwG;IACxG,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,SAAQ,EAAE,MAAM,SAAU,GAAG,SAAS,CAKrI;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAE,IAAiB,GAAG,MAAM,CAOjF;AAED,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,EAAE,SAAS,MAAM,KAAG,IAAiD,CAAC;AAC3G,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,EAAE,SAAS,MAAM,KAAG,IAAsC,CAAC;AAMhG,uGAAuG;AACvG,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpD;AASD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAIzH;AAED,uHAAuH;AACvH,wBAAgB,cAAc,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,CAGjF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAchG"}
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../../src/common/time.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED,wGAAwG;AACxG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,SAAU,GAAG,MAAM,CAWrG;AAED,MAAM,WAAW,SAAS;IACxB,wGAAwG;IACxG,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,SAAQ,EAAE,MAAM,SAAU,GAAG,SAAS,CAKrI;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAE,IAAiB,GAAG,MAAM,CAOjF;AAED,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,EAAE,SAAS,MAAM,KAAG,IAAiD,CAAC;AAC3G,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,EAAE,SAAS,MAAM,KAAG,IAAsC,CAAC;AAMhG,uGAAuG;AACvG,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpD;AASD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAIzH;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,CAIjF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAchG;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAIhE"}

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

@@ -1,40 +1,53 @@
 import { z } from 'zod';
-/**
- * Environment building blocks. Services compose the pieces they need:
- *
- *   const env = loadEnv(serviceEnv.merge(databaseEnv).merge(messagingEnv).extend({ MY_VAR: z.string() }));
- */
+/** Service identity, logging, CORS and the gateway signing secret. */
 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>;
-    /** Verifies gateway-signed identity headers. */
-    GATEWAY_SHARED_SECRET: z.ZodString;
-    /** Authenticates service-to-service `/internal/*` calls. */
-    INTERNAL_SERVICE_SECRET: z.ZodString;
+    /** Verifies gateway-signed identity headers (v2); at least 32 characters, same value on the gateway and every service. */
+    GATEWAY_SIGNING_SECRET: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    NODE_ENV: "production" | "test" | "development" | "staging";
+    NODE_ENV: "development" | "test" | "staging" | "production";
     PORT: number;
     SERVICE_NAME: string;
     APP_NAME: string;
     CORS_ORIGINS: string;
-    GATEWAY_SHARED_SECRET: string;
-    INTERNAL_SERVICE_SECRET: string;
-    LOG_LEVEL?: "info" | "debug" | "error" | "warn" | "http" | undefined;
+    GATEWAY_SIGNING_SECRET: string;
+    LOG_LEVEL?: "error" | "warn" | "info" | "http" | "debug" | undefined;
 }, {
     PORT: number;
     SERVICE_NAME: string;
-    GATEWAY_SHARED_SECRET: string;
-    INTERNAL_SERVICE_SECRET: string;
-    NODE_ENV?: "production" | "test" | "development" | "staging" | undefined;
-    LOG_LEVEL?: "info" | "debug" | "error" | "warn" | "http" | undefined;
+    GATEWAY_SIGNING_SECRET: string;
+    NODE_ENV?: "development" | "test" | "staging" | "production" | undefined;
     APP_NAME?: string | undefined;
+    LOG_LEVEL?: "error" | "warn" | "info" | "http" | "debug" | undefined;
     CORS_ORIGINS?: string | undefined;
 }>;
+/**
+ * Service-to-service credentials. Optional here because development may run without them;
+ * `assertInternalServiceAuthConfigured` enforces them in staging and production.
+ */
+export declare const internalServiceEnv: z.ZodObject<{
+    /** This service's own name (its compose service name), sent with every internal call. */
+    INTERNAL_SERVICE_NAME: z.ZodOptional<z.ZodString>;
+    /** This service's own secret (at least 32 characters), sent with every internal call. */
+    INTERNAL_SERVICE_CREDENTIAL: z.ZodOptional<z.ZodString>;
+    /** JSON map of caller name → secret this service accepts from that caller. */
+    INTERNAL_SERVICE_CREDENTIALS: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    INTERNAL_SERVICE_NAME?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIAL?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIALS?: string | undefined;
+}, {
+    INTERNAL_SERVICE_NAME?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIAL?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIALS?: string | undefined;
+}>;
+/** Database connection env vars (MySQL defaults). */
 export declare const databaseEnv: z.ZodObject<{
     DB_HOST: z.ZodDefault<z.ZodString>;
     DB_PORT: z.ZodDefault<z.ZodNumber>;
@@ -57,6 +70,7 @@ export declare const databaseEnv: z.ZodObject<{
     DB_PASSWORD?: string | undefined;
     DB_POOL_MAX?: number | undefined;
 }>;
+/** RabbitMQ connection and queue-prefix env vars. */
 export declare const messagingEnv: z.ZodObject<{
     RABBITMQ_URL: z.ZodOptional<z.ZodString>;
     RABBITMQ_HOST: z.ZodDefault<z.ZodString>;
@@ -86,30 +100,240 @@ export declare const messagingEnv: z.ZodObject<{
     QUEUE_PREFIX?: string | undefined;
     RABBITMQ_ENABLED?: "true" | "false" | undefined;
 }>;
+/** Redis connection env vars. Keys are prefixed by the keyspace (`createRedisKeyspace`), never by the client. */
 export declare const redisEnv: z.ZodObject<{
+    /** Full connection URL; overrides host/port/password when set. */
     REDIS_URL: z.ZodOptional<z.ZodString>;
+    REDIS_HOST: z.ZodDefault<z.ZodString>;
+    REDIS_PORT: z.ZodDefault<z.ZodNumber>;
+    REDIS_PASSWORD: z.ZodOptional<z.ZodString>;
     REDIS_DB: z.ZodDefault<z.ZodNumber>;
-    /** Key prefix, e.g. `app:dev:` — never share one between apps or environments. */
-    REDIS_PREFIX: z.ZodDefault<z.ZodString>;
+    /**
+     * Environment segment of every Redis key (`{app}:{env}:{service}:…`), e.g. `dev`, `staging`, `prod`.
+     * Required in staging and production; never share one between environments.
+     */
+    CACHE_KEY_PREFIX: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
+    REDIS_HOST: string;
+    REDIS_PORT: number;
     REDIS_DB: number;
-    REDIS_PREFIX: string;
     REDIS_URL?: string | undefined;
+    REDIS_PASSWORD?: string | undefined;
+    CACHE_KEY_PREFIX?: string | undefined;
 }, {
     REDIS_URL?: string | undefined;
+    REDIS_HOST?: string | undefined;
+    REDIS_PORT?: number | undefined;
+    REDIS_PASSWORD?: string | undefined;
     REDIS_DB?: number | undefined;
-    REDIS_PREFIX?: string | undefined;
+    CACHE_KEY_PREFIX?: string | undefined;
 }>;
-/** Builds an AMQP URL from discrete env vars (or returns RABBITMQ_URL when set). */
+/**
+ * Builds an AMQP URL from discrete env vars (or returns RABBITMQ_URL when set). User, password and vhost are URL-encoded.
+ *
+ * @param env Parsed {@link messagingEnv} values.
+ * @returns An `amqp://` URL.
+ * @example const url = amqpUrlFromEnv(parseEnv(messagingEnv));
+ */
 export declare function amqpUrlFromEnv(env: z.infer<typeof messagingEnv>): string;
-/** Reads `KEY=value` lines from a dotenv file into process.env without overriding set values. */
+/**
+ * Reads `KEY=value` lines from a dotenv file into process.env without overriding set values. Missing file is a no-op.
+ *
+ * @param path Dotenv file (default `./.env`).
+ * @example loadDotEnv(resolve(__dirname, '../.env.test'));
+ */
 export declare function loadDotEnv(path?: string): void;
+/** Thrown by the env loader when required variables are missing or invalid; lists every problem. */
 export declare class ConfigError extends Error {
 }
-/** Loads `.env` (if present) and validates process.env. Throws ConfigError listing every problem. */
-export declare function loadEnv<S extends z.ZodTypeAny>(schema: S, source?: NodeJS.ProcessEnv, options?: {
+/**
+ * The base environment every service validates: service identity, gateway secret, database, Redis,
+ * RabbitMQ and internal-service credentials. `loadEnv` merges a service's own schema onto it.
+ */
+export declare const baseEnv: 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. `myapp`). */
+    APP_NAME: z.ZodDefault<z.ZodString>;
+    LOG_LEVEL: z.ZodOptional<z.ZodEnum<["error", "warn", "info", "http", "debug"]>>;
+    CORS_ORIGINS: z.ZodDefault<z.ZodString>;
+    /** Verifies gateway-signed identity headers (v2); at least 32 characters, same value on the gateway and every service. */
+    GATEWAY_SIGNING_SECRET: z.ZodString;
+} & {
+    DB_HOST: z.ZodDefault<z.ZodString>;
+    DB_PORT: z.ZodDefault<z.ZodNumber>;
+    DB_USER: z.ZodDefault<z.ZodString>;
+    DB_PASSWORD: z.ZodDefault<z.ZodString>;
+    DB_NAME: z.ZodString;
+    DB_POOL_MAX: z.ZodDefault<z.ZodNumber>;
+} & {
+    /** Full connection URL; overrides host/port/password when set. */
+    REDIS_URL: z.ZodOptional<z.ZodString>;
+    REDIS_HOST: z.ZodDefault<z.ZodString>;
+    REDIS_PORT: z.ZodDefault<z.ZodNumber>;
+    REDIS_PASSWORD: z.ZodOptional<z.ZodString>;
+    REDIS_DB: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Environment segment of every Redis key (`{app}:{env}:{service}:…`), e.g. `dev`, `staging`, `prod`.
+     * Required in staging and production; never share one between environments.
+     */
+    CACHE_KEY_PREFIX: z.ZodOptional<z.ZodString>;
+} & {
+    RABBITMQ_URL: z.ZodOptional<z.ZodString>;
+    RABBITMQ_HOST: z.ZodDefault<z.ZodString>;
+    RABBITMQ_PORT: z.ZodDefault<z.ZodNumber>;
+    RABBITMQ_USER: z.ZodDefault<z.ZodString>;
+    RABBITMQ_PASSWORD: z.ZodDefault<z.ZodString>;
+    RABBITMQ_VHOST: z.ZodDefault<z.ZodString>;
+    /** Environment prefix for queue and exchange names (`dev`, `staging`, `prod`). */
+    QUEUE_PREFIX: z.ZodDefault<z.ZodString>;
+    RABBITMQ_ENABLED: z.ZodEffects<z.ZodDefault<z.ZodEnum<["true", "false"]>>, boolean, "true" | "false" | undefined>;
+} & {
+    /** This service's own name (its compose service name), sent with every internal call. */
+    INTERNAL_SERVICE_NAME: z.ZodOptional<z.ZodString>;
+    /** This service's own secret (at least 32 characters), sent with every internal call. */
+    INTERNAL_SERVICE_CREDENTIAL: z.ZodOptional<z.ZodString>;
+    /** JSON map of caller name → secret this service accepts from that caller. */
+    INTERNAL_SERVICE_CREDENTIALS: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    NODE_ENV: "development" | "test" | "staging" | "production";
+    PORT: number;
+    SERVICE_NAME: string;
+    APP_NAME: string;
+    CORS_ORIGINS: string;
+    GATEWAY_SIGNING_SECRET: string;
+    DB_HOST: string;
+    DB_PORT: number;
+    DB_USER: string;
+    DB_PASSWORD: string;
+    DB_NAME: string;
+    DB_POOL_MAX: number;
+    RABBITMQ_HOST: string;
+    RABBITMQ_PORT: number;
+    RABBITMQ_USER: string;
+    RABBITMQ_PASSWORD: string;
+    RABBITMQ_VHOST: string;
+    QUEUE_PREFIX: string;
+    RABBITMQ_ENABLED: boolean;
+    REDIS_HOST: string;
+    REDIS_PORT: number;
+    REDIS_DB: number;
+    LOG_LEVEL?: "error" | "warn" | "info" | "http" | "debug" | undefined;
+    INTERNAL_SERVICE_NAME?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIAL?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIALS?: string | undefined;
+    RABBITMQ_URL?: string | undefined;
+    REDIS_URL?: string | undefined;
+    REDIS_PASSWORD?: string | undefined;
+    CACHE_KEY_PREFIX?: string | undefined;
+}, {
+    PORT: number;
+    SERVICE_NAME: string;
+    GATEWAY_SIGNING_SECRET: string;
+    DB_NAME: string;
+    NODE_ENV?: "development" | "test" | "staging" | "production" | undefined;
+    APP_NAME?: string | undefined;
+    LOG_LEVEL?: "error" | "warn" | "info" | "http" | "debug" | undefined;
+    CORS_ORIGINS?: string | undefined;
+    INTERNAL_SERVICE_NAME?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIAL?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIALS?: string | undefined;
+    DB_HOST?: string | undefined;
+    DB_PORT?: number | undefined;
+    DB_USER?: string | undefined;
+    DB_PASSWORD?: string | undefined;
+    DB_POOL_MAX?: number | undefined;
+    RABBITMQ_URL?: string | undefined;
+    RABBITMQ_HOST?: string | undefined;
+    RABBITMQ_PORT?: number | undefined;
+    RABBITMQ_USER?: string | undefined;
+    RABBITMQ_PASSWORD?: string | undefined;
+    RABBITMQ_VHOST?: string | undefined;
+    QUEUE_PREFIX?: string | undefined;
+    RABBITMQ_ENABLED?: "true" | "false" | undefined;
+    REDIS_URL?: string | undefined;
+    REDIS_HOST?: string | undefined;
+    REDIS_PORT?: number | undefined;
+    REDIS_PASSWORD?: string | undefined;
+    REDIS_DB?: number | undefined;
+    CACHE_KEY_PREFIX?: string | undefined;
+}>;
+/** Variables that have a development default but must be set explicitly in staging and production. */
+export declare const DEPLOYED_REQUIRED_ENV: readonly string[];
+/**
+ * True for NODE_ENV values that must name their environments explicitly (staging, production).
+ *
+ * @param nodeEnv NODE_ENV value (default `process.env.NODE_ENV`).
+ * @returns Whether it is a deployed environment.
+ * @example isDeployedNodeEnv('production') // true
+ */
+export declare function isDeployedNodeEnv(nodeEnv?: string | undefined): boolean;
+/** One problem with one variable. Holds the variable name and kind of problem only, never its value. */
+export interface EnvProblem {
+    name: string;
+    problem: 'missing' | 'invalid';
+}
+type EnvSource = Record<string, string | undefined>;
+/**
+ * Formats problems as `NAME: missing|invalid` lines (names only — values are never printed, because
+ * Zod's own messages can echo them).
+ *
+ * @param problems Problems from validation.
+ * @returns A multi-line message.
+ * @example formatEnvProblems([{ name: 'DB_NAME', problem: 'missing' }]) // 'Invalid environment configuration:\n  DB_NAME: missing'
+ */
+export declare function formatEnvProblems(problems: EnvProblem[]): string;
+/** Options for {@link parseEnv}. */
+export interface ParseEnvOptions {
+    /** Read `./.env` first when `source` is `process.env` (default true). */
     dotenv?: boolean;
-}): z.infer<S>;
-/** Comma-separated env value → trimmed, non-empty list. */
+    /** Names that must be set when NODE_ENV is staging or production (default {@link DEPLOYED_REQUIRED_ENV}). */
+    deployedRequired?: readonly string[];
+}
+/**
+ * Validates `source` against `schema` without merging the base or exiting. Use for partial configs
+ * (scripts, tests) and wherever the caller handles the error.
+ *
+ * @param schema Any Zod schema over the env object.
+ * @param source Values to validate (default process.env).
+ * @param options Dotenv and deployed-environment checks.
+ * @returns The parsed, typed config.
+ * @throws ConfigError listing every missing or invalid variable by name (never its value).
+ * @example const env = parseEnv(databaseEnv, { DB_NAME: 'app_test' });
+ */
+export declare function parseEnv<S extends z.ZodTypeAny>(schema: S, source?: EnvSource, options?: ParseEnvOptions): z.infer<S>;
+/** Options for {@link loadEnv}: parse options plus source, base and injectable output/exit. */
+export interface LoadEnvOptions extends ParseEnvOptions {
+    /** Values to validate (default process.env). */
+    source?: EnvSource;
+    /** Base schema merged under the service schema (default {@link baseEnv}). */
+    base?: z.AnyZodObject;
+    /** Where the problem list is written (default stderr). */
+    write?: (text: string) => void;
+    /** Called with exit code 1 on failure (default `process.exit`). */
+    exit?: (code: number) => never;
+}
+/**
+ * Service startup config: merges the base env schema with the service's own, validates, and on
+ * failure prints the missing/invalid variable **names** (never values) and exits non-zero.
+ *
+ * @param schema The service's own variables (default none).
+ * @param options Source, base override and injectable write/exit for tests.
+ * @returns The parsed, typed config (base + service variables).
+ * @example
+ * export const config = loadEnv(z.object({ UPSTREAM_INTERNAL_URL: z.string().url() }));
+ */
+export declare function loadEnv<S extends z.AnyZodObject = z.ZodObject<Record<string, never>>, B extends z.AnyZodObject = typeof baseEnv>(schema?: S, options?: LoadEnvOptions & {
+    base?: B;
+}): z.infer<B> & z.infer<S>;
+/**
+ * Comma-separated env value → trimmed, non-empty list.
+ *
+ * @param value Raw env value.
+ * @returns The list (empty when unset).
+ * @example listFromEnv(' a, b ,,c') // ['a', 'b', 'c']
+ */
 export declare const listFromEnv: (value: string | undefined) => string[];
+export {};
 //# sourceMappingURL=index.d.ts.map

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":"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"}

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"}