@heavybit/shared-lib 1.3.1 → 2.1.0

package/dist/esm/contracts/notification-dispatch.js

@@ -1,89 +1,112 @@
+/**
+ * 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 const NOTIFICATION_DISPATCH = 'notification:dispatch';
-/** Channels a dispatch may ask for. `in_app` needs a recipient `userId` (the bell feed is per user). */
-export const DISPATCH_CHANNELS = ['email', 'in_app'];
 /**
- * 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 const NOTIFICATION_CATEGORIES = ['security', 'account', 'team', 'marketing', 'staff'];
 export const DISPATCH_LIMITS = {
     template: 100,
     email: 254,
     name: 200,
+    userId: 36,
     dataKeys: 40,
     dataKey: 64,
     dataValue: 2000,
     secretKeys: 10,
     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 const dispatchValueSchema = z.union([z.string().max(DISPATCH_LIMITS.dataValue), z.number().finite(), z.boolean(), z.null()]);
+/**
+ * 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 const dispatchRecipientSchema = z.object({
     email: z.string().trim().email().max(DISPATCH_LIMITS.email),
     name: z.string().trim().max(DISPATCH_LIMITS.name).optional(),
-    userId: z.string().max(36).nullish(),
+    userId: z.string().max(DISPATCH_LIMITS.userId).nullish(),
     locale: z.string().max(20).nullish(),
     /** IANA zone; time variables are rendered in it. */
     timezone: z.string().max(64).nullish(),
 });
-const dataKey = z.string().regex(/^[A-Za-z][A-Za-z0-9_]*$/, 'Use a template variable name').max(DISPATCH_LIMITS.dataKey);
-export const notificationDispatchSchema = z
-    .object({
-    /** Seeded `notification_templates.slug`. */
-    template: z.string().trim().min(1).max(DISPATCH_LIMITS.template),
-    category: z.enum(NOTIFICATION_CATEGORIES),
-    recipient: dispatchRecipientSchema,
-    channels: z.array(z.enum(DISPATCH_CHANNELS)).min(1).max(DISPATCH_CHANNELS.length),
-    data: z
-        .record(dataKey, dispatchValueSchema)
-        .default({})
-        .refine((data) => Object.keys(data).length <= DISPATCH_LIMITS.dataKeys, `At most ${DISPATCH_LIMITS.dataKeys} variables`),
-    /**
-     * 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.
-     */
-    secretKeys: z.array(dataKey).max(DISPATCH_LIMITS.secretKeys).default([]),
-    /** Security and staff alerts are always delivered, whatever the recipient's preferences. */
-    bypassPreferences: z.boolean().optional(),
-    /** The permission staff recipients hold; informational until recipients are resolved by permission. */
-    targetPermission: z.string().max(DISPATCH_LIMITS.permission).optional(),
-})
-    .superRefine((dispatch, ctx) => {
-    for (const key of dispatch.secretKeys) {
-        if (!(key in dispatch.data)) {
-            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['secretKeys'], message: `Secret key "${key}" is not in data` });
-        }
-    }
-});
 /**
- * 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.
+ * A template variable name the renderer can match.
+ *
+ * @example dispatchDataKeySchema.parse('expiresInMinutes')
  */
-export const DISPATCH_TEMPLATE_VARIABLES = {
-    // auth-admin-service: account and security mail
-    'account-activation': ['name', 'code', 'expiresInHours'],
-    'login-otp': ['name', 'code', 'expiresInMinutes', 'device'],
-    'password-reset': ['name', 'resetUrl', 'expiresInMinutes'],
-    'staff-invitation': ['name', 'resetUrl', 'expiresInMinutes'],
-    'password-changed': ['name', 'changedAt'],
-    'new-device-login': ['name', 'device', 'ip', 'country', 'occurredAt', 'confirmUrl', 'disputeUrl'],
-    'team-member-added': ['name', 'profileName', 'role', 'invitedBy'],
-    'account-suspended': ['name', 'reason'],
-    'welcome-listener': ['name'],
-    'welcome-creator': ['name'],
-    // ai / newswire / editorial: staff alerts
-    'ai_budget_threshold': ['requester', 'period', 'threshold_pct', 'spent_usd', 'limit_usd'],
-    'newswire_source_unhealthy': ['source_name', 'source_slug', 'consecutive_failures', 'last_error', 'last_success_at'],
-    'newswire_block_rate_high': ['blocked', 'total', 'block_rate_pct', 'window_hours'],
-    'autopublish_audit_alert': ['problem_rate_pct', 'problem_count', 'sample_count', 'window_days', 'action_taken'],
-};
+export const dispatchDataKeySchema = z.string().regex(/^[A-Za-z][A-Za-z0-9_]*$/, 'Use a template variable name').max(DISPATCH_LIMITS.dataKey);
+/**
+ * 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 function createNotificationDispatchSchema(vocabulary) {
+    return z
+        .object({
+        /** Seeded template slug in the notification-service. */
+        template: z.string().trim().min(1).max(DISPATCH_LIMITS.template),
+        category: z.enum([...vocabulary.categories]),
+        recipient: dispatchRecipientSchema,
+        channels: z
+            .array(z.enum([...vocabulary.channels]))
+            .min(1)
+            .max(vocabulary.channels.length)
+            .refine((channels) => new Set(channels).size === channels.length, 'Each channel at most once'),
+        data: z
+            .record(dispatchDataKeySchema, dispatchValueSchema)
+            .default({})
+            .refine((data) => Object.keys(data).length <= DISPATCH_LIMITS.dataKeys, `At most ${DISPATCH_LIMITS.dataKeys} variables`),
+        /** Keys of `data` holding a one-time secret: used to render, never stored or shown in a feed. */
+        secretKeys: z.array(dispatchDataKeySchema).max(DISPATCH_LIMITS.secretKeys).default([]),
+        /** Deliver whatever the recipient's notification preferences say (for mail the recipient cannot opt out of). */
+        bypassPreferences: z.boolean().optional(),
+        /** The permission the recipients were resolved by, when they were (traceability only). */
+        targetPermission: z.string().max(DISPATCH_LIMITS.permission).optional(),
+    })
+        .superRefine((dispatch, ctx) => {
+        for (const key of dispatch.secretKeys) {
+            if (!(key in dispatch.data)) {
+                ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['secretKeys'], message: `Secret key "${key}" is not in data` });
+            }
+        }
+    });
+}
 //# sourceMappingURL=notification-dispatch.js.map

package/dist/esm/contracts/notification-dispatch.js.map

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

package/dist/esm/express/auth.js

@@ -1,6 +1,7 @@
 import { hasAllPermissions, hasPermission, hasRole } from '../access/index.js';
 import { safeEqual } from '../common/crypto.js';
-import { errorResponse } from '../common/response.js';
+import { errorBody } from '../common/response.js';
+import { correlationId } from './middleware.js';
 import { CONTEXT_HEADERS, verifyIdentityHeaders } from '../identity/index.js';
 function resolveIdentity(req, options) {
     const result = verifyIdentityHeaders(req.headers, options.secret, { maxSkewMs: options.maxSkewMs });
@@ -14,19 +15,32 @@ function resolveIdentity(req, options) {
     }
     return 'anonymous';
 }
-/** 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 function authenticateFromGateway(options) {
     return (req, res, next) => {
         if (resolveIdentity(req, options) === 'ok')
             return next();
-        res.status(401).json(errorResponse('Authentication required', undefined, 'UNAUTHENTICATED'));
+        res.status(401).json(errorBody('UNAUTHENTICATED', 'Authentication required', { requestId: correlationId(req) }));
     };
 }
-/** 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 function optionalAuthFromGateway(options) {
     return (req, res, next) => {
         if (resolveIdentity(req, options) === 'invalid') {
-            res.status(401).json(errorResponse('Invalid identity', undefined, 'UNAUTHENTICATED'));
+            res.status(401).json(errorBody('UNAUTHENTICATED', 'Invalid identity', { requestId: correlationId(req) }));
             return;
         }
         next();
@@ -35,29 +49,48 @@ export function optionalAuthFromGateway(options) {
 function guard(check, message = 'You do not have permission to perform this action') {
     return (req, res, next) => {
         if (!req.user) {
-            res.status(401).json(errorResponse('Authentication required', undefined, 'UNAUTHENTICATED'));
+            res.status(401).json(errorBody('UNAUTHENTICATED', 'Authentication required', { requestId: correlationId(req) }));
             return;
         }
         if (!check(req.user)) {
-            res.status(403).json(errorResponse(message, undefined, 'FORBIDDEN'));
+            res.status(403).json(errorBody('FORBIDDEN', message, { requestId: correlationId(req) }));
             return;
         }
         next();
     };
 }
-/** 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 const requirePermission = (...permissions) => guard((u) => hasPermission(u, ...permissions));
-/** 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 const requireAllPermissions = (...permissions) => guard((u) => hasAllPermissions(u, ...permissions));
-/** 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 const requireRole = (...roles) => guard((u) => hasRole(u, ...roles), 'Insufficient role');
-/** 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 function requireInternalServiceSecret(secret) {
     return (req, res, next) => {
         const provided = req.headers[CONTEXT_HEADERS.INTERNAL_SECRET];
         if (typeof provided === 'string' && secret && safeEqual(provided, secret))
             return next();
-        res.status(401).json(errorResponse('Invalid internal service credentials', undefined, 'UNAUTHENTICATED'));
+        res.status(401).json(errorBody('UNAUTHENTICATED', 'Invalid internal service credentials', { requestId: correlationId(req) }));
     };
 }
 //# sourceMappingURL=auth.js.map

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

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

package/dist/esm/express/index.js

@@ -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.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","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.js","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/esm/express/middleware.js

@@ -1,84 +1,203 @@
-import { isAppError, publicMessage } from '../common/errors.js';
+import { GENERIC_ERROR_MESSAGE, ValidationError, isAppError, publicMessage } from '../common/errors.js';
 import { newId } from '../common/id.js';
-import { errorResponse } from '../common/response.js';
+import { errorBody } from '../common/response.js';
+import { getRequestContext, runWithContext } from '../context/index.js';
 import { CONTEXT_HEADERS } from '../identity/index.js';
 import { zodIssuesToErrors } from '../validation/index.js';
-/** Ensures every request carries `x-correlation-id` (reused from the gateway when present). */
-export function correlationMiddleware() {
+/** An incoming correlation id is trusted only if it is 8–64 chars of `[A-Za-z0-9-]` (no log injection). */
+export const CORRELATION_ID_PATTERN = /^[A-Za-z0-9-]{8,64}$/;
+/**
+ * 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 function correlationMiddleware(serviceName) {
     return (req, res, next) => {
         const incoming = req.headers[CONTEXT_HEADERS.CORRELATION_ID];
-        const id = typeof incoming === 'string' && incoming.length <= 128 ? incoming : newId();
+        const id = typeof incoming === 'string' && CORRELATION_ID_PATTERN.test(incoming) ? incoming : newId();
         req.headers[CONTEXT_HEADERS.CORRELATION_ID] = id;
         res.setHeader(CONTEXT_HEADERS.CORRELATION_ID, id);
-        next();
+        runWithContext({ correlationId: id, service: serviceName }, next);
     };
 }
+/**
+ * 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 function correlationId(req) {
+    const fromContext = getRequestContext()?.correlationId;
+    if (fromContext)
+        return fromContext;
     const value = req.headers[CONTEXT_HEADERS.CORRELATION_ID];
     return typeof value === 'string' ? value : 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 function clientIp(req) {
     const forwarded = req.headers[CONTEXT_HEADERS.CLIENT_IP];
     if (typeof forwarded === 'string' && forwarded)
         return forwarded;
     return req.ip ?? 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 function clientTimezone(req) {
     const tz = req.headers[CONTEXT_HEADERS.TIMEZONE];
     return typeof tz === 'string' && tz ? tz : 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 function anonId(req) {
     const id = req.headers[CONTEXT_HEADERS.ANON_ID];
     return typeof id === 'string' && id ? id : null;
 }
-/** Validates and replaces `req[part]` with the parsed value; 422 with field errors on failure. */
-export function validate(schema, part = 'body') {
-    return (req, res, next) => {
-        const result = schema.safeParse(req[part]);
-        if (!result.success) {
-            res.status(422).json(errorResponse('Validation failed', zodIssuesToErrors(result.error), 'VALIDATION_FAILED'));
+const PART_ORDER = ['params', 'query', 'body'];
+/** Field-error keys: body fields keep their own path; params/query are prefixed (`query.limit`). */
+function prefixErrors(part, errors) {
+    if (part === 'body')
+        return errors;
+    return Object.fromEntries(Object.entries(errors).map(([key, messages]) => [key === '_' ? part : `${part}.${key}`, messages]));
+}
+function isSchema(value) {
+    return typeof value?.safeParse === 'function';
+}
+/**
+ * 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 function validate(schemas, part = 'body') {
+    const parts = isSchema(schemas) ? { [part]: schemas } : schemas;
+    return (req, _res, next) => {
+        let errors = {};
+        const parsed = {};
+        for (const name of PART_ORDER) {
+            const schema = parts[name];
+            if (!schema)
+                continue;
+            const result = schema.safeParse(req[name]);
+            if (result.success)
+                parsed[name] = result.data;
+            else
+                errors = { ...errors, ...prefixErrors(name, zodIssuesToErrors(result.error)) };
+        }
+        if (Object.keys(errors).length > 0) {
+            next(new ValidationError(errors));
             return;
         }
-        // Express 5 exposes req.query as a getter; redefine to store the parsed value.
-        Object.defineProperty(req, part, { value: result.data, writable: true, configurable: true, enumerable: true });
+        for (const [name, value] of Object.entries(parsed)) {
+            // Express 5 exposes req.query as a getter; redefine to store the parsed value.
+            Object.defineProperty(req, name, { value, writable: true, configurable: true, enumerable: true });
+        }
         next();
     };
 }
-/** Wraps an async handler so rejections reach the error middleware (needed on Express 4). */
+/**
+ * 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 function asyncHandler(fn) {
     return (req, res, next) => {
         fn(req, res, next).catch(next);
     };
 }
-/** Maps AppErrors to their status; everything else becomes a logged 500 with a generic message. */
+/** Zod's error, recognised structurally so a service on another zod copy/version still maps to 422. */
+function isZodError(err) {
+    return err instanceof Error && err.name === 'ZodError' && Array.isArray(err.issues);
+}
+/**
+ * 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 function errorHandler(logger) {
-    return (err, req, res, _next) => {
-        if (res.headersSent)
+    return (err, req, res, next) => {
+        if (res.headersSent) {
+            next(err);
             return;
+        }
+        const requestId = correlationId(req);
         const bodyError = err;
         if (bodyError?.type === 'entity.parse.failed') {
-            res.status(400).json(errorResponse('Malformed JSON body', undefined, 'BAD_REQUEST'));
+            res.status(400).json(errorBody('BAD_REQUEST', 'Malformed JSON body', { requestId }));
             return;
         }
         if (bodyError?.type === 'entity.too.large') {
-            res.status(413).json(errorResponse('Request body too large', undefined, 'PAYLOAD_TOO_LARGE'));
+            res.status(413).json(errorBody('PAYLOAD_TOO_LARGE', 'Request body too large', { requestId }));
+            return;
+        }
+        if (isZodError(err)) {
+            res.status(422).json(errorBody('VALIDATION_FAILED', 'Validation failed', { errors: zodIssuesToErrors(err), requestId }));
             return;
         }
         if (isAppError(err)) {
             if (err.statusCode >= 500)
-                logger?.error(err.message, { path: req.path, code: err.code, correlationId: correlationId(req) });
-            res.status(err.statusCode).json(errorResponse(publicMessage(err), err.errors, err.code));
+                logger?.error(err.message, { path: req.path, errorCode: err.code, stack: err.stack, correlationId: requestId });
+            if (err.retryAfterSeconds !== undefined)
+                res.setHeader('Retry-After', String(Math.max(0, Math.ceil(err.retryAfterSeconds))));
+            const errors = err.statusCode < 500 ? err.errors : undefined;
+            res.status(err.statusCode).json(errorBody(err.code, publicMessage(err), { errors, requestId }));
             return;
         }
         const error = err instanceof Error ? err : new Error(String(err));
-        logger?.error('Unhandled error', { error: error.message, stack: error.stack, path: req.path, correlationId: correlationId(req) });
-        res.status(500).json(errorResponse('Internal server error', undefined, 'INTERNAL_ERROR'));
+        logger?.error('Unhandled error', { error: error.message, stack: error.stack, path: req.path, correlationId: requestId });
+        res.status(500).json(errorBody('INTERNAL_ERROR', GENERIC_ERROR_MESSAGE, { requestId }));
     };
 }
+/**
+ * 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 function notFoundHandler() {
-    return (_req, res) => {
-        res.status(404).json(errorResponse('Resource not found', undefined, 'NOT_FOUND'));
+    return (req, res) => {
+        res.status(404).json(errorBody('NOT_FOUND', 'Resource not found', { requestId: correlationId(req) }));
     };
 }
 //# sourceMappingURL=middleware.js.map

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

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

package/dist/esm/express/respond.js

@@ -0,0 +1,42 @@
+import { cursorPaginatedResponse, successResponse } from '../common/response.js';
+/**
+ * 200 with the success envelope.
+ *
+ * @param res Express response.
+ * @param data The payload placed under `data`.
+ * @param message Optional human-readable message (default `Success`).
+ * @param meta Optional list metadata.
+ * @returns The Express response.
+ * @example ok(res, product, 'Product updated');
+ */
+export function ok(res, data, message, meta) {
+    const body = successResponse(data, message);
+    return res.status(200).json(meta ? { ...body, meta } : body);
+}
+/**
+ * 201 with the success envelope, for a newly created resource.
+ *
+ * @param res Express response.
+ * @param data The created resource (or its id).
+ * @param message Optional message (default `Created`).
+ * @returns The Express response.
+ *
+ * @example created(res, { id }, 'Shop created');
+ */
+export function created(res, data, message = 'Created') {
+    return res.status(201).json(successResponse(data, message));
+}
+/**
+ * 200 with a cursor-paginated list: `data` is the items, `meta` is `{ limit, nextCursor, hasMore }`.
+ *
+ * @param res Express response.
+ * @param page The page from the service (see `buildCursorPageMeta`).
+ * @param message Optional message.
+ * @returns The Express response.
+ *
+ * @example okPage(res, await service.list(scope, { cursor, limit }));
+ */
+export function okPage(res, page, message) {
+    return res.status(200).json(cursorPaginatedResponse(page, message));
+}
+//# sourceMappingURL=respond.js.map