@heavybit/shared-lib 1.3.1 → 2.1.0

package/dist/types/contracts/notification-dispatch.d.ts

@@ -1,33 +1,51 @@
+/**
+ * Notification dispatch: a generic command contract (shared plumbing, no app vocabulary).
+ *
+ * Services never send email, SMS or push themselves. They stage one dispatch command (default
+ * `notification:dispatch`) through their outbox, and the app's notification-service renders a seeded
+ * template and delivers it. Both sides build their schema from {@link createNotificationDispatchSchema},
+ * so producers and the consumer cannot drift.
+ *
+ * App-specific parts are parameters: the app passes its own categories (e.g. `security`, `order`) and
+ * channels (e.g. `email`, `sms`, `in_app`). Template slugs and their variables also belong to the app
+ * (keep a table next to the notification-service seeds and test both sides against it).
+ */
 import { z } from 'zod';
 /**
- * `notification:dispatch` — the one command every Showbiz service stages (through its outbox) to have
- * notification-service render a seeded template and deliver it by email and/or the in-app feed. No
- * other service sends email itself. One contract for both sides: producers type their payload with it
- * and notification-service validates against it, so the two cannot drift.
+ * Default command name for a dispatch. An app may use another name and pass it to its producers.
+ *
+ * @example await outbox.command(tx, NOTIFICATION_DISPATCH, dispatch, { correlationId });
  */
 export declare const NOTIFICATION_DISPATCH = "notification:dispatch";
-/** Channels a dispatch may ask for. `in_app` needs a recipient `userId` (the bell feed is per user). */
-export declare const DISPATCH_CHANNELS: readonly ["email", "in_app"];
-export type DispatchChannel = (typeof DISPATCH_CHANNELS)[number];
 /**
- * What a dispatch is about. Account mail (`security`, `account`, `team`, `marketing`) goes to a user;
- * `staff` is an operational alert to a configured staff address.
+ * Size limits that keep a dispatch small enough for a queue message and safe to render.
+ *
+ * @example z.string().max(DISPATCH_LIMITS.template)
  */
-export declare const NOTIFICATION_CATEGORIES: readonly ["security", "account", "team", "marketing", "staff"];
-export type NotificationCategory = (typeof NOTIFICATION_CATEGORIES)[number];
 export declare const DISPATCH_LIMITS: {
     readonly template: 100;
     readonly email: 254;
     readonly name: 200;
+    readonly userId: 36;
     readonly dataKeys: 40;
     readonly dataKey: 64;
     readonly dataValue: 2000;
     readonly secretKeys: 10;
     readonly permission: 100;
 };
-/** Template variables are flat scalars: they are printed into the copy, never serialised objects. */
+/**
+ * Template variables are flat scalars: they are printed into the copy, never serialised objects.
+ *
+ * @example dispatchValueSchema.parse('1250.00')
+ */
 export declare const dispatchValueSchema: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
 export type DispatchValue = z.infer<typeof dispatchValueSchema>;
+/**
+ * Who receives a dispatch. `userId` is needed for per-user channels such as an in-app feed;
+ * addresses with no account behind them carry only `email`.
+ *
+ * @example { email: 'wanjiru@example.com', name: 'Wanjiru', userId: '01J…', timezone: 'Africa/Nairobi' }
+ */
 export declare const dispatchRecipientSchema: z.ZodObject<{
     email: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
@@ -37,22 +55,58 @@ export declare const dispatchRecipientSchema: z.ZodObject<{
     timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     email: string;
-    name?: string | undefined;
     userId?: string | null | undefined;
+    name?: string | undefined;
     locale?: string | null | undefined;
     timezone?: string | null | undefined;
 }, {
     email: string;
-    name?: string | undefined;
     userId?: string | null | undefined;
+    name?: string | undefined;
     locale?: string | null | undefined;
     timezone?: string | null | undefined;
 }>;
 export type DispatchRecipient = z.infer<typeof dispatchRecipientSchema>;
-export declare const notificationDispatchSchema: z.ZodEffects<z.ZodObject<{
-    /** Seeded `notification_templates.slug`. */
+/**
+ * A template variable name the renderer can match.
+ *
+ * @example dispatchDataKeySchema.parse('expiresInMinutes')
+ */
+export declare const dispatchDataKeySchema: z.ZodString;
+/**
+ * The app's vocabulary: which categories and channels a dispatch may name.
+ *
+ * @example { categories: ['security', 'order', 'staff'], channels: ['email', 'sms'] }
+ */
+export interface DispatchVocabulary<C extends string, Ch extends string> {
+    /** What a dispatch is about, e.g. `['security', 'account', 'order', 'staff']`. */
+    categories: readonly [C, ...C[]];
+    /** Delivery channels the notification-service supports, e.g. `['email', 'sms', 'in_app']`. */
+    channels: readonly [Ch, ...Ch[]];
+}
+/**
+ * Build the dispatch schema for an app's categories and channels. Producers type their payload with it;
+ * the notification-service validates incoming commands with the same schema.
+ *
+ * Rules every app gets: a seeded `template` slug; one or more distinct channels; at most 40 flat-scalar `data`
+ * variables with renderer-safe names; `secretKeys` (one-time codes, reset links) must be keys of `data`;
+ * the consumer must use them only to render, never store them or show them in a feed.
+ *
+ * @typeParam C The app's categories (inferred as literals).
+ * @typeParam Ch The app's channels (inferred as literals).
+ * @param vocabulary The app's categories and channels.
+ * @returns A Zod schema; `data` defaults to `{}` and `secretKeys` to `[]`.
+ * @example
+ * export const dispatchSchema = createNotificationDispatchSchema({
+ *   categories: ['security', 'account', 'order', 'staff'],
+ *   channels: ['email', 'sms'],
+ * });
+ * export type Dispatch = z.input<typeof dispatchSchema>;
+ */
+export declare function createNotificationDispatchSchema<const C extends string, const Ch extends string>(vocabulary: DispatchVocabulary<C, Ch>): z.ZodEffects<z.ZodObject<{
+    /** Seeded template slug in the notification-service. */
     template: z.ZodString;
-    category: z.ZodEnum<["security", "account", "team", "marketing", "staff"]>;
+    category: z.ZodEnum<[C, ...C[]]>;
     recipient: z.ZodObject<{
         email: z.ZodString;
         name: z.ZodOptional<z.ZodString>;
@@ -62,114 +116,178 @@ export declare const notificationDispatchSchema: z.ZodEffects<z.ZodObject<{
         timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, "strip", z.ZodTypeAny, {
         email: string;
-        name?: string | undefined;
         userId?: string | null | undefined;
+        name?: string | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
     }, {
         email: string;
-        name?: string | undefined;
         userId?: string | null | undefined;
+        name?: string | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
     }>;
-    channels: z.ZodArray<z.ZodEnum<["email", "in_app"]>, "many">;
+    channels: z.ZodEffects<z.ZodArray<z.ZodEnum<[Ch, ...Ch[]]>, "many">, Ch[], Ch[]>;
     data: z.ZodEffects<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>, Record<string, string | number | boolean | null>, Record<string, string | number | boolean | null> | undefined>;
-    /**
-     * Keys of `data` holding a one-time secret (a sign-in code, a reset or confirm link). They are used to
-     * render the email and nothing else: notification-service never stores them and never puts them in the
-     * in-app feed, and email-service masks them in what it keeps.
-     */
+    /** Keys of `data` holding a one-time secret: used to render, never stored or shown in a feed. */
     secretKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    /** Security and staff alerts are always delivered, whatever the recipient's preferences. */
+    /** Deliver whatever the recipient's notification preferences say (for mail the recipient cannot opt out of). */
     bypassPreferences: z.ZodOptional<z.ZodBoolean>;
-    /** The permission staff recipients hold; informational until recipients are resolved by permission. */
+    /** The permission the recipients were resolved by, when they were (traceability only). */
     targetPermission: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    data: Record<string, string | number | boolean | null>;
-    category: "security" | "account" | "team" | "marketing" | "staff";
-    template: string;
-    recipient: {
+}, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    /** Seeded template slug in the notification-service. */
+    template: z.ZodString;
+    category: z.ZodEnum<[C, ...C[]]>;
+    recipient: z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** IANA zone; time variables are rendered in it. */
+        timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
         email: string;
+        userId?: string | null | undefined;
         name?: string | undefined;
+        locale?: string | null | undefined;
+        timezone?: string | null | undefined;
+    }, {
+        email: string;
         userId?: string | null | undefined;
+        name?: string | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
-    };
-    channels: ("email" | "in_app")[];
-    secretKeys: string[];
-    bypassPreferences?: boolean | undefined;
-    targetPermission?: string | undefined;
-}, {
-    category: "security" | "account" | "team" | "marketing" | "staff";
-    template: string;
-    recipient: {
+    }>;
+    channels: z.ZodEffects<z.ZodArray<z.ZodEnum<[Ch, ...Ch[]]>, "many">, Ch[], Ch[]>;
+    data: z.ZodEffects<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>, Record<string, string | number | boolean | null>, Record<string, string | number | boolean | null> | undefined>;
+    /** Keys of `data` holding a one-time secret: used to render, never stored or shown in a feed. */
+    secretKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Deliver whatever the recipient's notification preferences say (for mail the recipient cannot opt out of). */
+    bypassPreferences: z.ZodOptional<z.ZodBoolean>;
+    /** The permission the recipients were resolved by, when they were (traceability only). */
+    targetPermission: z.ZodOptional<z.ZodString>;
+}>, any> extends infer T ? { [k in keyof T]: T[k]; } : never, z.baseObjectInputType<{
+    /** Seeded template slug in the notification-service. */
+    template: z.ZodString;
+    category: z.ZodEnum<[C, ...C[]]>;
+    recipient: z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** IANA zone; time variables are rendered in it. */
+        timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
         email: string;
+        userId?: string | null | undefined;
         name?: string | undefined;
+        locale?: string | null | undefined;
+        timezone?: string | null | undefined;
+    }, {
+        email: string;
         userId?: string | null | undefined;
+        name?: string | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
-    };
-    channels: ("email" | "in_app")[];
-    data?: Record<string, string | number | boolean | null> | undefined;
-    secretKeys?: string[] | undefined;
-    bypassPreferences?: boolean | undefined;
-    targetPermission?: string | undefined;
-}>, {
-    data: Record<string, string | number | boolean | null>;
-    category: "security" | "account" | "team" | "marketing" | "staff";
-    template: string;
-    recipient: {
+    }>;
+    channels: z.ZodEffects<z.ZodArray<z.ZodEnum<[Ch, ...Ch[]]>, "many">, Ch[], Ch[]>;
+    data: z.ZodEffects<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>, Record<string, string | number | boolean | null>, Record<string, string | number | boolean | null> | undefined>;
+    /** Keys of `data` holding a one-time secret: used to render, never stored or shown in a feed. */
+    secretKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Deliver whatever the recipient's notification preferences say (for mail the recipient cannot opt out of). */
+    bypassPreferences: z.ZodOptional<z.ZodBoolean>;
+    /** The permission the recipients were resolved by, when they were (traceability only). */
+    targetPermission: z.ZodOptional<z.ZodString>;
+}> extends infer T_1 ? { [k_1 in keyof T_1]: T_1[k_1]; } : never>, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    /** Seeded template slug in the notification-service. */
+    template: z.ZodString;
+    category: z.ZodEnum<[C, ...C[]]>;
+    recipient: z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** IANA zone; time variables are rendered in it. */
+        timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
         email: string;
+        userId?: string | null | undefined;
         name?: string | undefined;
+        locale?: string | null | undefined;
+        timezone?: string | null | undefined;
+    }, {
+        email: string;
         userId?: string | null | undefined;
+        name?: string | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
-    };
-    channels: ("email" | "in_app")[];
-    secretKeys: string[];
-    bypassPreferences?: boolean | undefined;
-    targetPermission?: string | undefined;
-}, {
-    category: "security" | "account" | "team" | "marketing" | "staff";
-    template: string;
-    recipient: {
+    }>;
+    channels: z.ZodEffects<z.ZodArray<z.ZodEnum<[Ch, ...Ch[]]>, "many">, Ch[], Ch[]>;
+    data: z.ZodEffects<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>, Record<string, string | number | boolean | null>, Record<string, string | number | boolean | null> | undefined>;
+    /** Keys of `data` holding a one-time secret: used to render, never stored or shown in a feed. */
+    secretKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Deliver whatever the recipient's notification preferences say (for mail the recipient cannot opt out of). */
+    bypassPreferences: z.ZodOptional<z.ZodBoolean>;
+    /** The permission the recipients were resolved by, when they were (traceability only). */
+    targetPermission: z.ZodOptional<z.ZodString>;
+}>, any> extends infer T_2 ? { [k in keyof T_2]: T_2[k]; } : never, z.baseObjectInputType<{
+    /** Seeded template slug in the notification-service. */
+    template: z.ZodString;
+    category: z.ZodEnum<[C, ...C[]]>;
+    recipient: z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** IANA zone; time variables are rendered in it. */
+        timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
         email: string;
+        userId?: string | null | undefined;
         name?: string | undefined;
+        locale?: string | null | undefined;
+        timezone?: string | null | undefined;
+    }, {
+        email: string;
         userId?: string | null | undefined;
+        name?: string | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
-    };
-    channels: ("email" | "in_app")[];
-    data?: Record<string, string | number | boolean | null> | undefined;
-    secretKeys?: string[] | undefined;
-    bypassPreferences?: boolean | undefined;
-    targetPermission?: string | undefined;
-}>;
+    }>;
+    channels: z.ZodEffects<z.ZodArray<z.ZodEnum<[Ch, ...Ch[]]>, "many">, Ch[], Ch[]>;
+    data: z.ZodEffects<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>, Record<string, string | number | boolean | null>, Record<string, string | number | boolean | null> | undefined>;
+    /** Keys of `data` holding a one-time secret: used to render, never stored or shown in a feed. */
+    secretKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Deliver whatever the recipient's notification preferences say (for mail the recipient cannot opt out of). */
+    bypassPreferences: z.ZodOptional<z.ZodBoolean>;
+    /** The permission the recipients were resolved by, when they were (traceability only). */
+    targetPermission: z.ZodOptional<z.ZodString>;
+}> extends infer T_3 ? { [k_1 in keyof T_3]: T_3[k_1]; } : never>;
 /**
- * The seeded templates Showbiz services dispatch, with the variables (`data` keys) each dispatch carries.
- * Producers send exactly these keys; a seeded template may use any subset (notification-service dead-letters
- * a dispatch missing a variable its template uses). Both sides test against this table.
+ * What a producer stages, as a plain type (usable while categories/channels are still generic, e.g. in
+ * shared helpers). Equivalent to {@link NotificationDispatchInput} for a concrete vocabulary.
+ *
+ * @example
+ * const dispatch: NotificationDispatchPayload<'security', 'email'> = {
+ *   template: 'login-otp', category: 'security', recipient: { email }, channels: ['email'],
+ *   data: { code }, secretKeys: ['code'], bypassPreferences: true,
+ * };
  */
-export declare const DISPATCH_TEMPLATE_VARIABLES: {
-    readonly 'account-activation': readonly ["name", "code", "expiresInHours"];
-    readonly 'login-otp': readonly ["name", "code", "expiresInMinutes", "device"];
-    readonly 'password-reset': readonly ["name", "resetUrl", "expiresInMinutes"];
-    readonly 'staff-invitation': readonly ["name", "resetUrl", "expiresInMinutes"];
-    readonly 'password-changed': readonly ["name", "changedAt"];
-    readonly 'new-device-login': readonly ["name", "device", "ip", "country", "occurredAt", "confirmUrl", "disputeUrl"];
-    readonly 'team-member-added': readonly ["name", "profileName", "role", "invitedBy"];
-    readonly 'account-suspended': readonly ["name", "reason"];
-    readonly 'welcome-listener': readonly ["name"];
-    readonly 'welcome-creator': readonly ["name"];
-    readonly ai_budget_threshold: readonly ["requester", "period", "threshold_pct", "spent_usd", "limit_usd"];
-    readonly newswire_source_unhealthy: readonly ["source_name", "source_slug", "consecutive_failures", "last_error", "last_success_at"];
-    readonly newswire_block_rate_high: readonly ["blocked", "total", "block_rate_pct", "window_hours"];
-    readonly autopublish_audit_alert: readonly ["problem_rate_pct", "problem_count", "sample_count", "window_days", "action_taken"];
-};
-export type DispatchTemplate = keyof typeof DISPATCH_TEMPLATE_VARIABLES;
+export interface NotificationDispatchPayload<C extends string = string, Ch extends string = string> {
+    template: string;
+    category: C;
+    recipient: DispatchRecipient;
+    channels: Ch[];
+    data?: Record<string, DispatchValue>;
+    secretKeys?: string[];
+    bypassPreferences?: boolean;
+    targetPermission?: string;
+}
+/** The schema type for a given vocabulary. */
+export type NotificationDispatchSchema<C extends string, Ch extends string> = ReturnType<typeof createNotificationDispatchSchema<C, Ch>>;
 /** The validated command (defaults applied). */
-export type NotificationDispatch = z.infer<typeof notificationDispatchSchema>;
+export type NotificationDispatch<C extends string = string, Ch extends string = string> = z.output<NotificationDispatchSchema<C, Ch>>;
 /** What a producer stages: `data` and `secretKeys` may be omitted. */
-export type NotificationDispatchInput = z.input<typeof notificationDispatchSchema>;
+export type NotificationDispatchInput<C extends string = string, Ch extends string = string> = z.input<NotificationDispatchSchema<C, Ch>>;
 //# sourceMappingURL=notification-dispatch.d.ts.map

package/dist/types/contracts/notification-dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notification-dispatch.d.ts","sourceRoot":"","sources":["../../../src/contracts/notification-dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D,wGAAwG;AACxG,eAAO,MAAM,iBAAiB,8BAA+B,CAAC;AAC9D,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,uBAAuB,gEAAiE,CAAC;AACtG,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,eAAO,MAAM,eAAe;;;;;;;;;CASlB,CAAC;AAEX,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,iEAAmG,CAAC;AACpI,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,uBAAuB;;;;;IAKlC,oDAAoD;;;;;;;;;;;;;;EAEpD,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAIxE,eAAO,MAAM,0BAA0B;IAEnC,4CAA4C;;;;;;;;QAT9C,oDAAoD;;;;;;;;;;;;;;;;;IAkBlD;;;;OAIG;;IAEH,4FAA4F;;IAE5F,uGAAuG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASvG,CAAC;AAEL;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;CAiBc,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,2BAA2B,CAAC;AAExE,gDAAgD;AAChD,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,sEAAsE;AACtE,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC"}
+{"version":3,"file":"notification-dispatch.d.ts","sourceRoot":"","sources":["../../../src/contracts/notification-dispatch.ts"],"names":[],"mappings":"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"}

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

@@ -7,21 +7,57 @@ declare global {
         }
     }
 }
+/** Options for the gateway identity middleware. */
 export interface GatewayAuthOptions {
+    /** HMAC secret shared with the gateway; verifies the signed identity headers. */
     secret: string;
+    /** Maximum age of the gateway timestamp before the identity counts as stale (replay guard). */
     maxSkewMs?: number;
+    /** Receives a warning (reason + path, no header values) when a forged or stale identity is rejected. */
     logger?: Logger;
 }
-/** Requires a valid gateway-signed identity; 401 otherwise. */
+/**
+ * Requires a valid gateway-signed identity and sets `req.user`; 401 UNAUTHENTICATED (with `requestId`) otherwise.
+ *
+ * @param options Secret, skew window and logger.
+ * @returns Express middleware.
+ * @example router.use(authenticateFromGateway({ secret: config.gatewaySecret, logger }));
+ */
 export declare function authenticateFromGateway(options: GatewayAuthOptions): RequestHandler;
-/** Attaches `req.user` when a valid identity is present; continues anonymously otherwise. */
+/**
+ * Attaches `req.user` when a valid identity is present and continues anonymously when none is sent.
+ * A forged or stale identity is still rejected with 401, never downgraded to anonymous.
+ *
+ * @param options Secret, skew window and logger.
+ * @returns Express middleware.
+ * @example router.get('/products', optionalAuthFromGateway({ secret }), controller.list);
+ */
 export declare function optionalAuthFromGateway(options: GatewayAuthOptions): RequestHandler;
-/** Allows callers holding any of `permissions`. */
+/**
+ * Allows callers holding any of `permissions` (401 without identity, 403 FORBIDDEN otherwise).
+ *
+ * @example router.post('/refunds', requirePermission('refunds.create'), controller.create);
+ */
 export declare const requirePermission: (...permissions: string[]) => RequestHandler;
-/** Allows callers holding every one of `permissions`. */
+/**
+ * Allows callers holding every one of `permissions`.
+ *
+ * @example router.delete('/x/:id', requireAllPermissions('x.read', 'x.delete'), controller.remove);
+ */
 export declare const requireAllPermissions: (...permissions: string[]) => RequestHandler;
-/** Allows callers with any of `roles`. Prefer permissions; roles are for coarse gates only. */
+/**
+ * Allows callers with any of `roles`. Prefer permissions; roles are for coarse gates only.
+ *
+ * @example router.use('/ops', requireRole('platform_admin'));
+ */
 export declare const requireRole: (...roles: string[]) => RequestHandler;
-/** Guards `/internal/*` routes: requires the shared service secret header. */
+/**
+ * Guards `/internal/*` routes: requires the service secret header (constant-time compare);
+ * 401 UNAUTHENTICATED with `requestId` otherwise.
+ *
+ * @param secret The expected `x-internal-service-secret`; an empty secret rejects every call (fail closed).
+ * @returns Express middleware.
+ * @example router.use('/internal', requireInternalServiceSecret(config.internalSecret));
+ */
 export declare function requireInternalServiceSecret(secret: string): RequestHandler;
 //# sourceMappingURL=auth.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/express/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,cAAc,EAAY,MAAM,SAAS,CAAC;AAK/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,IAAI,CAAC,EAAE,QAAQ,CAAC;SACjB;KACF;CACF;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD,+DAA+D;AAC/D,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAKnF;AAED,6FAA6F;AAC7F,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAQnF;AAgBD,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,GAAI,GAAG,aAAa,MAAM,EAAE,KAAG,cAAgE,CAAC;AAE9H,yDAAyD;AACzD,eAAO,MAAM,qBAAqB,GAAI,GAAG,aAAa,MAAM,EAAE,KAAG,cAAoE,CAAC;AAEtI,+FAA+F;AAC/F,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,MAAM,EAAE,KAAG,cAAyE,CAAC;AAE3H,8EAA8E;AAC9E,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAM3E"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/express/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,cAAc,EAAY,MAAM,SAAS,CAAC;AAM/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,IAAI,CAAC,EAAE,QAAQ,CAAC;SACjB;KACF;CACF;AAED,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wGAAwG;IACxG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAKnF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAQnF;AAgBD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,GAAG,aAAa,MAAM,EAAE,KAAG,cAAgE,CAAC;AAE9H;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,GAAG,aAAa,MAAM,EAAE,KAAG,cAAoE,CAAC;AAEtI;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,MAAM,EAAE,KAAG,cAAyE,CAAC;AAE3H;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAM3E"}

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

@@ -2,4 +2,5 @@ export * from './auth.js';
 export * from './middleware.js';
 export * from './health.js';
 export * from './security.js';
+export * from './respond.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/express/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/express/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}

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

@@ -1,20 +1,99 @@
 import type { ErrorRequestHandler, NextFunction, Request, RequestHandler, Response } from 'express';
 import type { ZodTypeAny } from 'zod';
 import type { Logger } from '../types/index.js';
-/** Ensures every request carries `x-correlation-id` (reused from the gateway when present). */
-export declare function correlationMiddleware(): RequestHandler;
+/** An incoming correlation id is trusted only if it is 8–64 chars of `[A-Za-z0-9-]` (no log injection). */
+export declare const CORRELATION_ID_PATTERN: RegExp;
+/**
+ * Gives every request one correlation id and runs the rest of the request inside a
+ * {@link RequestContext}. A valid incoming `x-correlation-id` (see {@link CORRELATION_ID_PATTERN}) is
+ * kept; anything else is replaced with a new ULID. The id is echoed on the response, written back to
+ * the request header (so outbound calls forward it) and becomes every error body's `requestId`.
+ * Mount it first: correlation → json → routes → notFoundHandler → errorHandler.
+ *
+ * @param serviceName Recorded in the context (and so in log lines written without a service).
+ * @returns Express middleware.
+ * @example app.use(correlationMiddleware('orders'));
+ */
+export declare function correlationMiddleware(serviceName?: string): RequestHandler;
+/**
+ * The request's correlation id (the source of every error body's `requestId`): the active request
+ * context's id, else the `x-correlation-id` header.
+ *
+ * @param req Express request.
+ * @returns The id, or undefined when neither is present.
+ * @example logger.info('Order placed', { correlationId: correlationId(req) });
+ */
 export declare function correlationId(req: Request): string | undefined;
-/** Real client IP: gateway-forwarded header first, then Express's `req.ip`. */
+/**
+ * Real client IP: gateway-forwarded header first, then Express's `req.ip`.
+ *
+ * @param req Express request.
+ * @returns The IP, or null when unknown.
+ * @example const ip = clientIp(req);
+ */
 export declare function clientIp(req: Request): string | null;
+/**
+ * The caller's IANA time zone as forwarded by the gateway.
+ *
+ * @param req Express request.
+ * @returns e.g. `Europe/Paris`, or null when not sent.
+ * @example formatInTimeZone(date, clientTimezone(req) ?? 'UTC');
+ */
 export declare function clientTimezone(req: Request): string | null;
+/**
+ * The anonymous visitor id forwarded by the gateway (for anonymous visitor state, rate limits and analytics).
+ *
+ * @param req Express request.
+ * @returns The id, or null when not sent.
+ * @example const visitor = req.user?.id ?? anonId(req);
+ */
 export declare function anonId(req: Request): string | null;
 type RequestPart = 'body' | 'query' | 'params';
-/** Validates and replaces `req[part]` with the parsed value; 422 with field errors on failure. */
-export declare function validate(schema: ZodTypeAny, part?: RequestPart): RequestHandler;
-/** Wraps an async handler so rejections reach the error middleware (needed on Express 4). */
+/** Zod schemas for the parts of a request that {@link validate} checks. */
+export type RequestSchemas = Partial<Record<RequestPart, ZodTypeAny>>;
+/**
+ * Validates the request with Zod at the controller boundary. Each given part is parsed and
+ * `req[part]` is replaced with the parsed value, so unknown keys are stripped (or rejected with
+ * `.strict()`) and coercions/defaults apply. Every part is checked before failing, and the combined
+ * field errors are thrown as a 422 {@link ValidationError} for the error handler (body fields keep
+ * their path; params and query fields are prefixed, e.g. `params.id`).
+ *
+ * The older single-schema form `validate(schema, part = 'body')` still works.
+ *
+ * @param schemas `{ params?, query?, body? }`, or one schema.
+ * @param part With a single schema: the part it checks (default `body`).
+ * @returns Express middleware.
+ * @example router.patch('/:id', validate({ params: idParam, body: updateSchema }), controller.update);
+ */
+export declare function validate(schemas: RequestSchemas | ZodTypeAny, part?: RequestPart): RequestHandler;
+/**
+ * Wraps an async handler so rejections reach the error middleware (needed on Express 4; harmless on 5).
+ *
+ * @param fn Async route handler.
+ * @returns A handler that forwards rejections to `next(err)`.
+ * @example router.get('/:id', asyncHandler(controller.get));
+ */
 export declare function asyncHandler<Req extends Request = Request>(fn: (req: Req, res: Response, next: NextFunction) => Promise<unknown>): RequestHandler;
-/** Maps AppErrors to their status; everything else becomes a logged 500 with a generic message. */
+/**
+ * Last error middleware. Every body is `{ success: false, code, message, errors?, requestId }`:
+ * - body-parser failures → 400 BAD_REQUEST / 413 PAYLOAD_TOO_LARGE;
+ * - a thrown ZodError (e.g. from `schema.parse`) → 422 VALIDATION_FAILED with field errors;
+ * - AppError → its status, code and errors; 4xx keep their message, 5xx get a generic one; a
+ *   `retryAfterSeconds` becomes the `Retry-After` header;
+ * - anything else → logged in full, answered 500 INTERNAL_ERROR with a generic message.
+ * `requestId` is the request context's correlation id (set by {@link correlationMiddleware}).
+ *
+ * @param logger Receives 5xx details (message, stack, path, correlation id); never sent to the client.
+ * @returns Express error middleware.
+ * @example app.use(notFoundHandler()); app.use(errorHandler(logger));
+ */
 export declare function errorHandler(logger?: Logger): ErrorRequestHandler;
+/**
+ * Catch-all for unmatched routes: 404 NOT_FOUND with the request id. Mount after every router.
+ *
+ * @returns Express middleware.
+ * @example app.use(notFoundHandler()); app.use(errorHandler(logger));
+ */
 export declare function notFoundHandler(): RequestHandler;
 export {};
 //# sourceMappingURL=middleware.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../src/express/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACpG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAKtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,+FAA+F;AAC/F,wBAAgB,qBAAqB,IAAI,cAAc,CAQtD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG9D;AAED,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAIpD;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAG1D;AAED,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAGlD;AAED,KAAK,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/C,kGAAkG;AAClG,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,WAAoB,GAAG,cAAc,CAWvF;AAED,6FAA6F;AAC7F,wBAAgB,YAAY,CAAC,GAAG,SAAS,OAAO,GAAG,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,cAAc,CAIjJ;AAED,mGAAmG;AACnG,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAqBjE;AAED,wBAAgB,eAAe,IAAI,cAAc,CAIhD"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../src/express/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACpG,OAAO,KAAK,EAAY,UAAU,EAAE,MAAM,KAAK,CAAC;AAMhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,2GAA2G;AAC3G,eAAO,MAAM,sBAAsB,QAAyB,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,cAAc,CAQ1E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAK9D;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAIpD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAG1D;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAGlD;AAED,KAAK,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/C,2EAA2E;AAC3E,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;AActE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,UAAU,EAAE,IAAI,GAAE,WAAoB,GAAG,cAAc,CAsBzG;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,SAAS,OAAO,GAAG,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,cAAc,CAIjJ;AAOD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,mBAAmB,CA+BjE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,cAAc,CAIhD"}