@pipeline-builder/api-server 0.0.1

package/lib/api/etag-middleware.js

@@ -0,0 +1,44 @@
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from 'crypto';
+/**
+ * Middleware that adds ETag support for conditional GET requests.
+ * Generates a weak ETag from the response body hash.
+ * Returns 304 Not Modified when the client's If-None-Match header matches.
+ */
+export function etagMiddleware() {
+    return (req, res, next) => {
+        // Only apply to GET requests
+        if (req.method !== 'GET')
+            return next();
+        res.json = (body) => {
+            // Serialize once, hash, and send — avoids double JSON.stringify
+            const serialized = JSON.stringify(body);
+            // Only ETag/304 SUCCESSFUL responses. For non-2xx (errors), skip the
+            // conditional logic entirely — otherwise an error response whose body
+            // happens to hash-match the client's If-None-Match would be turned into a
+            // 304 Not Modified, making the client serve a stale (possibly successful)
+            // cached body in place of the error.
+            if (res.statusCode < 200 || res.statusCode >= 300) {
+                res.setHeader('Content-Type', 'application/json');
+                res.end(serialized);
+                return res;
+            }
+            const hash = createHash('md5').update(serialized).digest('hex').slice(0, 16);
+            const etag = `W/"${hash}"`;
+            res.setHeader('ETag', etag);
+            // Check If-None-Match header
+            const ifNoneMatch = req.headers['if-none-match'];
+            if (ifNoneMatch && ifNoneMatch === etag) {
+                res.status(304).end();
+                return res;
+            }
+            // Send pre-serialized body to avoid double JSON.stringify
+            res.setHeader('Content-Type', 'application/json');
+            res.end(serialized);
+            return res;
+        };
+        next();
+    };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXRhZy1taWRkbGV3YXJlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2FwaS9ldGFnLW1pZGRsZXdhcmUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsK0NBQStDO0FBQy9DLHNDQUFzQztBQUV0QyxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sUUFBUSxDQUFDO0FBR3BDOzs7O0dBSUc7QUFDSCxNQUFNLFVBQVUsY0FBYztJQUM1QixPQUFPLENBQUMsR0FBWSxFQUFFLEdBQWEsRUFBRSxJQUFrQixFQUFFLEVBQUU7UUFDekQsNkJBQTZCO1FBQzdCLElBQUksR0FBRyxDQUFDLE1BQU0sS0FBSyxLQUFLO1lBQUUsT0FBTyxJQUFJLEVBQUUsQ0FBQztRQUV4QyxHQUFHLENBQUMsSUFBSSxHQUFHLENBQUMsSUFBYSxFQUFFLEVBQUU7WUFDM0IsZ0VBQWdFO1lBQ2hFLE1BQU0sVUFBVSxHQUFHLElBQUksQ0FBQyxTQUFTLENBQUMsSUFBSSxDQUFDLENBQUM7WUFFeEMscUVBQXFFO1lBQ3JFLHNFQUFzRTtZQUN0RSwwRUFBMEU7WUFDMUUsMEVBQTBFO1lBQzFFLHFDQUFxQztZQUNyQyxJQUFJLEdBQUcsQ0FBQyxVQUFVLEdBQUcsR0FBRyxJQUFJLEdBQUcsQ0FBQyxVQUFVLElBQUksR0FBRyxFQUFFLENBQUM7Z0JBQ2xELEdBQUcsQ0FBQyxTQUFTLENBQUMsY0FBYyxFQUFFLGtCQUFrQixDQUFDLENBQUM7Z0JBQ2xELEdBQUcsQ0FBQyxHQUFHLENBQUMsVUFBVSxDQUFDLENBQUM7Z0JBQ3BCLE9BQU8sR0FBRyxDQUFDO1lBQ2IsQ0FBQztZQUVELE1BQU0sSUFBSSxHQUFHLFVBQVUsQ0FBQyxLQUFLLENBQUMsQ0FBQyxNQUFNLENBQUMsVUFBVSxDQUFDLENBQUMsTUFBTSxDQUFDLEtBQUssQ0FBQyxDQUFDLEtBQUssQ0FBQyxDQUFDLEVBQUUsRUFBRSxDQUFDLENBQUM7WUFDN0UsTUFBTSxJQUFJLEdBQUcsTUFBTSxJQUFJLEdBQUcsQ0FBQztZQUUzQixHQUFHLENBQUMsU0FBUyxDQUFDLE1BQU0sRUFBRSxJQUFJLENBQUMsQ0FBQztZQUU1Qiw2QkFBNkI7WUFDN0IsTUFBTSxXQUFXLEdBQUcsR0FBRyxDQUFDLE9BQU8sQ0FBQyxlQUFlLENBQUMsQ0FBQztZQUNqRCxJQUFJLFdBQVcsSUFBSSxXQUFXLEtBQUssSUFBSSxFQUFFLENBQUM7Z0JBQ3hDLEdBQUcsQ0FBQyxNQUFNLENBQUMsR0FBRyxDQUFDLENBQUMsR0FBRyxFQUFFLENBQUM7Z0JBQ3RCLE9BQU8sR0FBRyxDQUFDO1lBQ2IsQ0FBQztZQUVELDBEQUEwRDtZQUMxRCxHQUFHLENBQUMsU0FBUyxDQUFDLGNBQWMsRUFBRSxrQkFBa0IsQ0FBQyxDQUFDO1lBQ2xELEdBQUcsQ0FBQyxHQUFHLENBQUMsVUFBVSxDQUFDLENBQUM7WUFDcEIsT0FBTyxHQUFHLENBQUM7UUFDYixDQUFDLENBQUM7UUFFRixJQUFJLEVBQUUsQ0FBQztJQUNULENBQUMsQ0FBQztBQUNKLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuaW1wb3J0IHsgY3JlYXRlSGFzaCB9IGZyb20gJ2NyeXB0byc7XG5pbXBvcnQgdHlwZSB7IFJlcXVlc3QsIFJlc3BvbnNlLCBOZXh0RnVuY3Rpb24gfSBmcm9tICdleHByZXNzJztcblxuLyoqXG4gKiBNaWRkbGV3YXJlIHRoYXQgYWRkcyBFVGFnIHN1cHBvcnQgZm9yIGNvbmRpdGlvbmFsIEdFVCByZXF1ZXN0cy5cbiAqIEdlbmVyYXRlcyBhIHdlYWsgRVRhZyBmcm9tIHRoZSByZXNwb25zZSBib2R5IGhhc2guXG4gKiBSZXR1cm5zIDMwNCBOb3QgTW9kaWZpZWQgd2hlbiB0aGUgY2xpZW50J3MgSWYtTm9uZS1NYXRjaCBoZWFkZXIgbWF0Y2hlcy5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGV0YWdNaWRkbGV3YXJlKCkge1xuICByZXR1cm4gKHJlcTogUmVxdWVzdCwgcmVzOiBSZXNwb25zZSwgbmV4dDogTmV4dEZ1bmN0aW9uKSA9PiB7XG4gICAgLy8gT25seSBhcHBseSB0byBHRVQgcmVxdWVzdHNcbiAgICBpZiAocmVxLm1ldGhvZCAhPT0gJ0dFVCcpIHJldHVybiBuZXh0KCk7XG5cbiAgICByZXMuanNvbiA9IChib2R5OiB1bmtub3duKSA9PiB7XG4gICAgICAvLyBTZXJpYWxpemUgb25jZSwgaGFzaCwgYW5kIHNlbmQg4oCUIGF2b2lkcyBkb3VibGUgSlNPTi5zdHJpbmdpZnlcbiAgICAgIGNvbnN0IHNlcmlhbGl6ZWQgPSBKU09OLnN0cmluZ2lmeShib2R5KTtcblxuICAgICAgLy8gT25seSBFVGFnLzMwNCBTVUNDRVNTRlVMIHJlc3BvbnNlcy4gRm9yIG5vbi0yeHggKGVycm9ycyksIHNraXAgdGhlXG4gICAgICAvLyBjb25kaXRpb25hbCBsb2dpYyBlbnRpcmVseSDigJQgb3RoZXJ3aXNlIGFuIGVycm9yIHJlc3BvbnNlIHdob3NlIGJvZHlcbiAgICAgIC8vIGhhcHBlbnMgdG8gaGFzaC1tYXRjaCB0aGUgY2xpZW50J3MgSWYtTm9uZS1NYXRjaCB3b3VsZCBiZSB0dXJuZWQgaW50byBhXG4gICAgICAvLyAzMDQgTm90IE1vZGlmaWVkLCBtYWtpbmcgdGhlIGNsaWVudCBzZXJ2ZSBhIHN0YWxlIChwb3NzaWJseSBzdWNjZXNzZnVsKVxuICAgICAgLy8gY2FjaGVkIGJvZHkgaW4gcGxhY2Ugb2YgdGhlIGVycm9yLlxuICAgICAgaWYgKHJlcy5zdGF0dXNDb2RlIDwgMjAwIHx8IHJlcy5zdGF0dXNDb2RlID49IDMwMCkge1xuICAgICAgICByZXMuc2V0SGVhZGVyKCdDb250ZW50LVR5cGUnLCAnYXBwbGljYXRpb24vanNvbicpO1xuICAgICAgICByZXMuZW5kKHNlcmlhbGl6ZWQpO1xuICAgICAgICByZXR1cm4gcmVzO1xuICAgICAgfVxuXG4gICAgICBjb25zdCBoYXNoID0gY3JlYXRlSGFzaCgnbWQ1JykudXBkYXRlKHNlcmlhbGl6ZWQpLmRpZ2VzdCgnaGV4Jykuc2xpY2UoMCwgMTYpO1xuICAgICAgY29uc3QgZXRhZyA9IGBXL1wiJHtoYXNofVwiYDtcblxuICAgICAgcmVzLnNldEhlYWRlcignRVRhZycsIGV0YWcpO1xuXG4gICAgICAvLyBDaGVjayBJZi1Ob25lLU1hdGNoIGhlYWRlclxuICAgICAgY29uc3QgaWZOb25lTWF0Y2ggPSByZXEuaGVhZGVyc1snaWYtbm9uZS1tYXRjaCddO1xuICAgICAgaWYgKGlmTm9uZU1hdGNoICYmIGlmTm9uZU1hdGNoID09PSBldGFnKSB7XG4gICAgICAgIHJlcy5zdGF0dXMoMzA0KS5lbmQoKTtcbiAgICAgICAgcmV0dXJuIHJlcztcbiAgICAgIH1cblxuICAgICAgLy8gU2VuZCBwcmUtc2VyaWFsaXplZCBib2R5IHRvIGF2b2lkIGRvdWJsZSBKU09OLnN0cmluZ2lmeVxuICAgICAgcmVzLnNldEhlYWRlcignQ29udGVudC1UeXBlJywgJ2FwcGxpY2F0aW9uL2pzb24nKTtcbiAgICAgIHJlcy5lbmQoc2VyaWFsaXplZCk7XG4gICAgICByZXR1cm4gcmVzO1xuICAgIH07XG5cbiAgICBuZXh0KCk7XG4gIH07XG59XG4iXX0=

package/lib/api/get-context.d.ts

@@ -0,0 +1,22 @@
+import type { Request } from 'express';
+import type { RequestContext } from './request-types.js';
+/**
+ * Safely retrieve the RequestContext from an Express request.
+ *
+ * Throws a descriptive error if the context middleware has not been applied,
+ * instead of silently returning undefined or crashing with a cryptic error.
+ *
+ * @param req - Express request object
+ * @returns The attached RequestContext
+ * @throws Error if req.context is not initialized
+ *
+ * @example
+ * ```typescript
+ * app.get('/pipelines', requireAuth, async (req, res) => {
+ *   const ctx = getContext(req);
+ *   ctx.log('INFO', 'Fetching pipelines');
+ *   // ...
+ * });
+ * ```
+ */
+export declare function getContext(req: Request): RequestContext;

package/lib/api/get-context.js

@@ -0,0 +1,28 @@
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Safely retrieve the RequestContext from an Express request.
+ *
+ * Throws a descriptive error if the context middleware has not been applied,
+ * instead of silently returning undefined or crashing with a cryptic error.
+ *
+ * @param req - Express request object
+ * @returns The attached RequestContext
+ * @throws Error if req.context is not initialized
+ *
+ * @example
+ * ```typescript
+ * app.get('/pipelines', requireAuth, async (req, res) => {
+ *   const ctx = getContext(req);
+ *   ctx.log('INFO', 'Fetching pipelines');
+ *   // ...
+ * });
+ * ```
+ */
+export function getContext(req) {
+    if (!req.context) {
+        throw new Error('Request context not initialized. Ensure attachRequestContext middleware is applied.');
+    }
+    return req.context;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ2V0LWNvbnRleHQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvYXBpL2dldC1jb250ZXh0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLCtDQUErQztBQUMvQyxzQ0FBc0M7QUFLdEM7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQWtCRztBQUNILE1BQU0sVUFBVSxVQUFVLENBQUMsR0FBWTtJQUNyQyxJQUFJLENBQUMsR0FBRyxDQUFDLE9BQU8sRUFBRSxDQUFDO1FBQ2pCLE1BQU0sSUFBSSxLQUFLLENBQ2IscUZBQXFGLENBQ3RGLENBQUM7SUFDSixDQUFDO0lBQ0QsT0FBTyxHQUFHLENBQUMsT0FBTyxDQUFDO0FBQ3JCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuaW1wb3J0IHR5cGUgeyBSZXF1ZXN0IH0gZnJvbSAnZXhwcmVzcyc7XG5pbXBvcnQgdHlwZSB7IFJlcXVlc3RDb250ZXh0IH0gZnJvbSAnLi9yZXF1ZXN0LXR5cGVzLmpzJztcblxuLyoqXG4gKiBTYWZlbHkgcmV0cmlldmUgdGhlIFJlcXVlc3RDb250ZXh0IGZyb20gYW4gRXhwcmVzcyByZXF1ZXN0LlxuICpcbiAqIFRocm93cyBhIGRlc2NyaXB0aXZlIGVycm9yIGlmIHRoZSBjb250ZXh0IG1pZGRsZXdhcmUgaGFzIG5vdCBiZWVuIGFwcGxpZWQsXG4gKiBpbnN0ZWFkIG9mIHNpbGVudGx5IHJldHVybmluZyB1bmRlZmluZWQgb3IgY3Jhc2hpbmcgd2l0aCBhIGNyeXB0aWMgZXJyb3IuXG4gKlxuICogQHBhcmFtIHJlcSAtIEV4cHJlc3MgcmVxdWVzdCBvYmplY3RcbiAqIEByZXR1cm5zIFRoZSBhdHRhY2hlZCBSZXF1ZXN0Q29udGV4dFxuICogQHRocm93cyBFcnJvciBpZiByZXEuY29udGV4dCBpcyBub3QgaW5pdGlhbGl6ZWRcbiAqXG4gKiBAZXhhbXBsZVxuICogYGBgdHlwZXNjcmlwdFxuICogYXBwLmdldCgnL3BpcGVsaW5lcycsIHJlcXVpcmVBdXRoLCBhc3luYyAocmVxLCByZXMpID0+IHtcbiAqICAgY29uc3QgY3R4ID0gZ2V0Q29udGV4dChyZXEpO1xuICogICBjdHgubG9nKCdJTkZPJywgJ0ZldGNoaW5nIHBpcGVsaW5lcycpO1xuICogICAvLyAuLi5cbiAqIH0pO1xuICogYGBgXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBnZXRDb250ZXh0KHJlcTogUmVxdWVzdCk6IFJlcXVlc3RDb250ZXh0IHtcbiAgaWYgKCFyZXEuY29udGV4dCkge1xuICAgIHRocm93IG5ldyBFcnJvcihcbiAgICAgICdSZXF1ZXN0IGNvbnRleHQgbm90IGluaXRpYWxpemVkLiBFbnN1cmUgYXR0YWNoUmVxdWVzdENvbnRleHQgbWlkZGxld2FyZSBpcyBhcHBsaWVkLicsXG4gICAgKTtcbiAgfVxuICByZXR1cm4gcmVxLmNvbnRleHQ7XG59XG4iXX0=

package/lib/api/health-checks.d.ts

@@ -0,0 +1,62 @@
+type HealthStatus = 'connected' | 'disconnected' | 'unknown';
+type HealthResult = Record<string, HealthStatus>;
+/**
+ * Postgres health probe: returns `{ postgres: 'connected' }` when the pool's
+ * connection test succeeds, `{ postgres: 'disconnected' }` on any error or
+ * timeout (so `/ready` correctly reports 503). Use as (part of) the
+ * `checkDependencies` option of `createApp()` for any service backed by the
+ * shared pipeline-data Drizzle connection.
+ */
+export declare function postgresHealthCheck(timeoutMs?: number): Promise<HealthResult>;
+/** Minimal shape of an ioredis client needed for a health PING. */
+interface RedisLike {
+    ping(): Promise<string>;
+}
+/**
+ * Source of a redis client: either the client itself, or a (sync/async) getter.
+ * The getter form supports BullMQ's `queue.client` (a `Promise<RedisClient>`)
+ * so a service can probe the exact connection its queue uses without opening
+ * a second one.
+ */
+type RedisClientSource = RedisLike | (() => RedisLike | Promise<RedisLike>);
+/**
+ * Redis health probe factory: pass the service's EXISTING ioredis connection
+ * (or a getter for it — e.g. `() => queue.client`) and get back a
+ * `checkDependencies` callback that `PING`s it. Mirrors `mongoHealthCheck` —
+ * it probes the real connection rather than opening a throwaway one per call.
+ * The PING is time-boxed so a down redis (whose offline queue would otherwise
+ * buffer the command) reports `disconnected` quickly instead of hanging.
+ */
+export declare function redisHealthCheck(source: RedisClientSource, timeoutMs?: number): () => Promise<HealthResult>;
+/**
+ * Combine several dependency probes into one `checkDependencies` callback that
+ * runs them IN PARALLEL and merges their results. A slow/failed probe can't
+ * delay the others or time out the whole `/ready` response.
+ *
+ * CONTRACT: each probe must CATCH internally and RETURN its `{ name: status }`
+ * (as the built-in postgres/redis/mongo probes do). A probe that THROWS is
+ * merged as `{}` — its dependency then vanishes from the map and `/ready`
+ * reports 200 with the dep simply absent (a silent false-healthy), rather than
+ * surfacing it as `disconnected`. The `.catch(() => ({}))` below only exists so
+ * one misbehaving probe can't take down the others, NOT as a substitute for a
+ * probe returning its own disconnected status.
+ */
+export declare function combineHealthChecks(...checks: Array<() => Promise<HealthResult>>): () => Promise<HealthResult>;
+/**
+ * Minimal shape expected of a mongoose connection for the health probe.
+ * Accepts `mongoose.connection` directly without requiring mongoose as a
+ * dependency of api-server.
+ */
+interface MongooseConnectionLike {
+    readyState: number;
+}
+/**
+ * MongoDB health probe factory: pass `mongoose.connection` and get back a
+ * `checkDependencies` callback that reports based on mongoose's readyState.
+ *
+ * Mapping (per mongoose docs): 1=connected, 2=connecting, 3=disconnecting,
+ * any other value (0=disconnected, 99=uninitialized) is treated as
+ * 'disconnected' so `/health` returns 503.
+ */
+export declare function mongoHealthCheck(connection: MongooseConnectionLike): () => Promise<HealthResult>;
+export {};

package/lib/api/health-checks.js

@@ -0,0 +1,87 @@
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+import { getConnection } from '@pipeline-builder/pipeline-data';
+/**
+ * Reject if `promise` hasn't settled within `ms`. A health/readiness probe
+ * must never hang the `/ready` response — a down datastore (or a BullMQ
+ * ioredis client with `maxRetriesPerRequest: null` + an offline queue) can
+ * leave a `ping()`/query pending indefinitely, so every probe is time-boxed.
+ */
+function withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+        timer.unref?.();
+        promise.then((value) => { clearTimeout(timer); resolve(value); }, (err) => { clearTimeout(timer); reject(err); });
+    });
+}
+/**
+ * Postgres health probe: returns `{ postgres: 'connected' }` when the pool's
+ * connection test succeeds, `{ postgres: 'disconnected' }` on any error or
+ * timeout (so `/ready` correctly reports 503). Use as (part of) the
+ * `checkDependencies` option of `createApp()` for any service backed by the
+ * shared pipeline-data Drizzle connection.
+ */
+export async function postgresHealthCheck(timeoutMs = 3000) {
+    try {
+        await withTimeout(getConnection().testConnection(), timeoutMs, 'postgres testConnection');
+        return { postgres: 'connected' };
+    }
+    catch {
+        return { postgres: 'disconnected' };
+    }
+}
+/**
+ * Redis health probe factory: pass the service's EXISTING ioredis connection
+ * (or a getter for it — e.g. `() => queue.client`) and get back a
+ * `checkDependencies` callback that `PING`s it. Mirrors `mongoHealthCheck` —
+ * it probes the real connection rather than opening a throwaway one per call.
+ * The PING is time-boxed so a down redis (whose offline queue would otherwise
+ * buffer the command) reports `disconnected` quickly instead of hanging.
+ */
+export function redisHealthCheck(source, timeoutMs = 2000) {
+    return async () => {
+        try {
+            const client = typeof source === 'function' ? await source() : source;
+            await withTimeout(client.ping(), timeoutMs, 'redis ping');
+            return { redis: 'connected' };
+        }
+        catch {
+            return { redis: 'disconnected' };
+        }
+    };
+}
+/**
+ * Combine several dependency probes into one `checkDependencies` callback that
+ * runs them IN PARALLEL and merges their results. A slow/failed probe can't
+ * delay the others or time out the whole `/ready` response.
+ *
+ * CONTRACT: each probe must CATCH internally and RETURN its `{ name: status }`
+ * (as the built-in postgres/redis/mongo probes do). A probe that THROWS is
+ * merged as `{}` — its dependency then vanishes from the map and `/ready`
+ * reports 200 with the dep simply absent (a silent false-healthy), rather than
+ * surfacing it as `disconnected`. The `.catch(() => ({}))` below only exists so
+ * one misbehaving probe can't take down the others, NOT as a substitute for a
+ * probe returning its own disconnected status.
+ */
+export function combineHealthChecks(...checks) {
+    return async () => {
+        const results = await Promise.all(checks.map((check) => check().catch(() => ({}))));
+        return Object.assign({}, ...results);
+    };
+}
+/**
+ * MongoDB health probe factory: pass `mongoose.connection` and get back a
+ * `checkDependencies` callback that reports based on mongoose's readyState.
+ *
+ * Mapping (per mongoose docs): 1=connected, 2=connecting, 3=disconnecting,
+ * any other value (0=disconnected, 99=uninitialized) is treated as
+ * 'disconnected' so `/health` returns 503.
+ */
+export function mongoHealthCheck(connection) {
+    return async () => ({
+        mongodb: connection.readyState === 1 ? 'connected'
+            : connection.readyState === 2 ? 'unknown' // connecting; treat as transient
+                : 'disconnected',
+    });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaGVhbHRoLWNoZWNrcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9hcGkvaGVhbHRoLWNoZWNrcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwrQ0FBK0M7QUFDL0Msc0NBQXNDO0FBRXRDLE9BQU8sRUFBRSxhQUFhLEVBQUUsTUFBTSxpQ0FBaUMsQ0FBQztBQUtoRTs7Ozs7R0FLRztBQUNILFNBQVMsV0FBVyxDQUFJLE9BQW1CLEVBQUUsRUFBVSxFQUFFLEtBQWE7SUFDcEUsT0FBTyxJQUFJLE9BQU8sQ0FBSSxDQUFDLE9BQU8sRUFBRSxNQUFNLEVBQUUsRUFBRTtRQUN4QyxNQUFNLEtBQUssR0FBRyxVQUFVLENBQUMsR0FBRyxFQUFFLENBQUMsTUFBTSxDQUFDLElBQUksS0FBSyxDQUFDLEdBQUcsS0FBSyxvQkFBb0IsRUFBRSxJQUFJLENBQUMsQ0FBQyxFQUFFLEVBQUUsQ0FBQyxDQUFDO1FBQzFGLEtBQUssQ0FBQyxLQUFLLEVBQUUsRUFBRSxDQUFDO1FBQ2hCLE9BQU8sQ0FBQyxJQUFJLENBQ1YsQ0FBQyxLQUFLLEVBQUUsRUFBRSxHQUFHLFlBQVksQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQUMsRUFDbkQsQ0FBQyxHQUFHLEVBQUUsRUFBRSxHQUFHLFlBQVksQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxHQUFHLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FDL0MsQ0FBQztJQUNKLENBQUMsQ0FBQyxDQUFDO0FBQ0wsQ0FBQztBQUVEOzs7Ozs7R0FNRztBQUNILE1BQU0sQ0FBQyxLQUFLLFVBQVUsbUJBQW1CLENBQUMsU0FBUyxHQUFHLElBQUk7SUFDeEQsSUFBSSxDQUFDO1FBQ0gsTUFBTSxXQUFXLENBQUMsYUFBYSxFQUFFLENBQUMsY0FBYyxFQUFFLEVBQUUsU0FBUyxFQUFFLHlCQUF5QixDQUFDLENBQUM7UUFDMUYsT0FBTyxFQUFFLFFBQVEsRUFBRSxXQUFXLEVBQUUsQ0FBQztJQUNuQyxDQUFDO0lBQUMsTUFBTSxDQUFDO1FBQ1AsT0FBTyxFQUFFLFFBQVEsRUFBRSxjQUFjLEVBQUUsQ0FBQztJQUN0QyxDQUFDO0FBQ0gsQ0FBQztBQWVEOzs7Ozs7O0dBT0c7QUFDSCxNQUFNLFVBQVUsZ0JBQWdCLENBQUMsTUFBeUIsRUFBRSxTQUFTLEdBQUcsSUFBSTtJQUMxRSxPQUFPLEtBQUssSUFBSSxFQUFFO1FBQ2hCLElBQUksQ0FBQztZQUNILE1BQU0sTUFBTSxHQUFHLE9BQU8sTUFBTSxLQUFLLFVBQVUsQ0FBQyxDQUFDLENBQUMsTUFBTSxNQUFNLEVBQUUsQ0FBQyxDQUFDLENBQUMsTUFBTSxDQUFDO1lBQ3RFLE1BQU0sV0FBVyxDQUFDLE1BQU0sQ0FBQyxJQUFJLEVBQUUsRUFBRSxTQUFTLEVBQUUsWUFBWSxDQUFDLENBQUM7WUFDMUQsT0FBTyxFQUFFLEtBQUssRUFBRSxXQUFXLEVBQUUsQ0FBQztRQUNoQyxDQUFDO1FBQUMsTUFBTSxDQUFDO1lBQ1AsT0FBTyxFQUFFLEtBQUssRUFBRSxjQUFjLEVBQUUsQ0FBQztRQUNuQyxDQUFDO0lBQ0gsQ0FBQyxDQUFDO0FBQ0osQ0FBQztBQUVEOzs7Ozs7Ozs7Ozs7R0FZRztBQUNILE1BQU0sVUFBVSxtQkFBbUIsQ0FDakMsR0FBRyxNQUEwQztJQUU3QyxPQUFPLEtBQUssSUFBSSxFQUFFO1FBQ2hCLE1BQU0sT0FBTyxHQUFHLE1BQU0sT0FBTyxDQUFDLEdBQUcsQ0FBQyxNQUFNLENBQUMsR0FBRyxDQUFDLENBQUMsS0FBSyxFQUFFLEVBQUUsQ0FBQyxLQUFLLEVBQUUsQ0FBQyxLQUFLLENBQUMsR0FBRyxFQUFFLENBQUMsQ0FBQyxFQUFtQixDQUFBLENBQUMsQ0FBQyxDQUFDLENBQUM7UUFDcEcsT0FBTyxNQUFNLENBQUMsTUFBTSxDQUFDLEVBQUUsRUFBRSxHQUFHLE9BQU8sQ0FBaUIsQ0FBQztJQUN2RCxDQUFDLENBQUM7QUFDSixDQUFDO0FBV0Q7Ozs7Ozs7R0FPRztBQUNILE1BQU0sVUFBVSxnQkFBZ0IsQ0FBQyxVQUFrQztJQUNqRSxPQUFPLEtBQUssSUFBSSxFQUFFLENBQUMsQ0FBQztRQUNsQixPQUFPLEVBQUUsVUFBVSxDQUFDLFVBQVUsS0FBSyxDQUFDLENBQUMsQ0FBQyxDQUFDLFdBQVc7WUFDaEQsQ0FBQyxDQUFDLFVBQVUsQ0FBQyxVQUFVLEtBQUssQ0FBQyxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUMsaUNBQWlDO2dCQUN6RSxDQUFDLENBQUMsY0FBYztLQUNyQixDQUFDLENBQUM7QUFDTCxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gQ29weXJpZ2h0IDIwMjYgUGlwZWxpbmUgQnVpbGRlciBDb250cmlidXRvcnNcbi8vIFNQRFgtTGljZW5zZS1JZGVudGlmaWVyOiBBcGFjaGUtMi4wXG5cbmltcG9ydCB7IGdldENvbm5lY3Rpb24gfSBmcm9tICdAcGlwZWxpbmUtYnVpbGRlci9waXBlbGluZS1kYXRhJztcblxudHlwZSBIZWFsdGhTdGF0dXMgPSAnY29ubmVjdGVkJyB8ICdkaXNjb25uZWN0ZWQnIHwgJ3Vua25vd24nO1xudHlwZSBIZWFsdGhSZXN1bHQgPSBSZWNvcmQ8c3RyaW5nLCBIZWFsdGhTdGF0dXM+O1xuXG4vKipcbiAqIFJlamVjdCBpZiBgcHJvbWlzZWAgaGFzbid0IHNldHRsZWQgd2l0aGluIGBtc2AuIEEgaGVhbHRoL3JlYWRpbmVzcyBwcm9iZVxuICogbXVzdCBuZXZlciBoYW5nIHRoZSBgL3JlYWR5YCByZXNwb25zZSDigJQgYSBkb3duIGRhdGFzdG9yZSAob3IgYSBCdWxsTVFcbiAqIGlvcmVkaXMgY2xpZW50IHdpdGggYG1heFJldHJpZXNQZXJSZXF1ZXN0OiBudWxsYCArIGFuIG9mZmxpbmUgcXVldWUpIGNhblxuICogbGVhdmUgYSBgcGluZygpYC9xdWVyeSBwZW5kaW5nIGluZGVmaW5pdGVseSwgc28gZXZlcnkgcHJvYmUgaXMgdGltZS1ib3hlZC5cbiAqL1xuZnVuY3Rpb24gd2l0aFRpbWVvdXQ8VD4ocHJvbWlzZTogUHJvbWlzZTxUPiwgbXM6IG51bWJlciwgbGFiZWw6IHN0cmluZyk6IFByb21pc2U8VD4ge1xuICByZXR1cm4gbmV3IFByb21pc2U8VD4oKHJlc29sdmUsIHJlamVjdCkgPT4ge1xuICAgIGNvbnN0IHRpbWVyID0gc2V0VGltZW91dCgoKSA9PiByZWplY3QobmV3IEVycm9yKGAke2xhYmVsfSB0aW1lZCBvdXQgYWZ0ZXIgJHttc31tc2ApKSwgbXMpO1xuICAgIHRpbWVyLnVucmVmPy4oKTtcbiAgICBwcm9taXNlLnRoZW4oXG4gICAgICAodmFsdWUpID0+IHsgY2xlYXJUaW1lb3V0KHRpbWVyKTsgcmVzb2x2ZSh2YWx1ZSk7IH0sXG4gICAgICAoZXJyKSA9PiB7IGNsZWFyVGltZW91dCh0aW1lcik7IHJlamVjdChlcnIpOyB9LFxuICAgICk7XG4gIH0pO1xufVxuXG4vKipcbiAqIFBvc3RncmVzIGhlYWx0aCBwcm9iZTogcmV0dXJucyBgeyBwb3N0Z3JlczogJ2Nvbm5lY3RlZCcgfWAgd2hlbiB0aGUgcG9vbCdzXG4gKiBjb25uZWN0aW9uIHRlc3Qgc3VjY2VlZHMsIGB7IHBvc3RncmVzOiAnZGlzY29ubmVjdGVkJyB9YCBvbiBhbnkgZXJyb3Igb3JcbiAqIHRpbWVvdXQgKHNvIGAvcmVhZHlgIGNvcnJlY3RseSByZXBvcnRzIDUwMykuIFVzZSBhcyAocGFydCBvZikgdGhlXG4gKiBgY2hlY2tEZXBlbmRlbmNpZXNgIG9wdGlvbiBvZiBgY3JlYXRlQXBwKClgIGZvciBhbnkgc2VydmljZSBiYWNrZWQgYnkgdGhlXG4gKiBzaGFyZWQgcGlwZWxpbmUtZGF0YSBEcml6emxlIGNvbm5lY3Rpb24uXG4gKi9cbmV4cG9ydCBhc3luYyBmdW5jdGlvbiBwb3N0Z3Jlc0hlYWx0aENoZWNrKHRpbWVvdXRNcyA9IDMwMDApOiBQcm9taXNlPEhlYWx0aFJlc3VsdD4ge1xuICB0cnkge1xuICAgIGF3YWl0IHdpdGhUaW1lb3V0KGdldENvbm5lY3Rpb24oKS50ZXN0Q29ubmVjdGlvbigpLCB0aW1lb3V0TXMsICdwb3N0Z3JlcyB0ZXN0Q29ubmVjdGlvbicpO1xuICAgIHJldHVybiB7IHBvc3RncmVzOiAnY29ubmVjdGVkJyB9O1xuICB9IGNhdGNoIHtcbiAgICByZXR1cm4geyBwb3N0Z3JlczogJ2Rpc2Nvbm5lY3RlZCcgfTtcbiAgfVxufVxuXG4vKiogTWluaW1hbCBzaGFwZSBvZiBhbiBpb3JlZGlzIGNsaWVudCBuZWVkZWQgZm9yIGEgaGVhbHRoIFBJTkcuICovXG5pbnRlcmZhY2UgUmVkaXNMaWtlIHtcbiAgcGluZygpOiBQcm9taXNlPHN0cmluZz47XG59XG5cbi8qKlxuICogU291cmNlIG9mIGEgcmVkaXMgY2xpZW50OiBlaXRoZXIgdGhlIGNsaWVudCBpdHNlbGYsIG9yIGEgKHN5bmMvYXN5bmMpIGdldHRlci5cbiAqIFRoZSBnZXR0ZXIgZm9ybSBzdXBwb3J0cyBCdWxsTVEncyBgcXVldWUuY2xpZW50YCAoYSBgUHJvbWlzZTxSZWRpc0NsaWVudD5gKVxuICogc28gYSBzZXJ2aWNlIGNhbiBwcm9iZSB0aGUgZXhhY3QgY29ubmVjdGlvbiBpdHMgcXVldWUgdXNlcyB3aXRob3V0IG9wZW5pbmdcbiAqIGEgc2Vjb25kIG9uZS5cbiAqL1xudHlwZSBSZWRpc0NsaWVudFNvdXJjZSA9IFJlZGlzTGlrZSB8ICgoKSA9PiBSZWRpc0xpa2UgfCBQcm9taXNlPFJlZGlzTGlrZT4pO1xuXG4vKipcbiAqIFJlZGlzIGhlYWx0aCBwcm9iZSBmYWN0b3J5OiBwYXNzIHRoZSBzZXJ2aWNlJ3MgRVhJU1RJTkcgaW9yZWRpcyBjb25uZWN0aW9uXG4gKiAob3IgYSBnZXR0ZXIgZm9yIGl0IOKAlCBlLmcuIGAoKSA9PiBxdWV1ZS5jbGllbnRgKSBhbmQgZ2V0IGJhY2sgYVxuICogYGNoZWNrRGVwZW5kZW5jaWVzYCBjYWxsYmFjayB0aGF0IGBQSU5HYHMgaXQuIE1pcnJvcnMgYG1vbmdvSGVhbHRoQ2hlY2tgIOKAlFxuICogaXQgcHJvYmVzIHRoZSByZWFsIGNvbm5lY3Rpb24gcmF0aGVyIHRoYW4gb3BlbmluZyBhIHRocm93YXdheSBvbmUgcGVyIGNhbGwuXG4gKiBUaGUgUElORyBpcyB0aW1lLWJveGVkIHNvIGEgZG93biByZWRpcyAod2hvc2Ugb2ZmbGluZSBxdWV1ZSB3b3VsZCBvdGhlcndpc2VcbiAqIGJ1ZmZlciB0aGUgY29tbWFuZCkgcmVwb3J0cyBgZGlzY29ubmVjdGVkYCBxdWlja2x5IGluc3RlYWQgb2YgaGFuZ2luZy5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHJlZGlzSGVhbHRoQ2hlY2soc291cmNlOiBSZWRpc0NsaWVudFNvdXJjZSwgdGltZW91dE1zID0gMjAwMCk6ICgpID0+IFByb21pc2U8SGVhbHRoUmVzdWx0PiB7XG4gIHJldHVybiBhc3luYyAoKSA9PiB7XG4gICAgdHJ5IHtcbiAgICAgIGNvbnN0IGNsaWVudCA9IHR5cGVvZiBzb3VyY2UgPT09ICdmdW5jdGlvbicgPyBhd2FpdCBzb3VyY2UoKSA6IHNvdXJjZTtcbiAgICAgIGF3YWl0IHdpdGhUaW1lb3V0KGNsaWVudC5waW5nKCksIHRpbWVvdXRNcywgJ3JlZGlzIHBpbmcnKTtcbiAgICAgIHJldHVybiB7IHJlZGlzOiAnY29ubmVjdGVkJyB9O1xuICAgIH0gY2F0Y2gge1xuICAgICAgcmV0dXJuIHsgcmVkaXM6ICdkaXNjb25uZWN0ZWQnIH07XG4gICAgfVxuICB9O1xufVxuXG4vKipcbiAqIENvbWJpbmUgc2V2ZXJhbCBkZXBlbmRlbmN5IHByb2JlcyBpbnRvIG9uZSBgY2hlY2tEZXBlbmRlbmNpZXNgIGNhbGxiYWNrIHRoYXRcbiAqIHJ1bnMgdGhlbSBJTiBQQVJBTExFTCBhbmQgbWVyZ2VzIHRoZWlyIHJlc3VsdHMuIEEgc2xvdy9mYWlsZWQgcHJvYmUgY2FuJ3RcbiAqIGRlbGF5IHRoZSBvdGhlcnMgb3IgdGltZSBvdXQgdGhlIHdob2xlIGAvcmVhZHlgIHJlc3BvbnNlLlxuICpcbiAqIENPTlRSQUNUOiBlYWNoIHByb2JlIG11c3QgQ0FUQ0ggaW50ZXJuYWxseSBhbmQgUkVUVVJOIGl0cyBgeyBuYW1lOiBzdGF0dXMgfWBcbiAqIChhcyB0aGUgYnVpbHQtaW4gcG9zdGdyZXMvcmVkaXMvbW9uZ28gcHJvYmVzIGRvKS4gQSBwcm9iZSB0aGF0IFRIUk9XUyBpc1xuICogbWVyZ2VkIGFzIGB7fWAg4oCUIGl0cyBkZXBlbmRlbmN5IHRoZW4gdmFuaXNoZXMgZnJvbSB0aGUgbWFwIGFuZCBgL3JlYWR5YFxuICogcmVwb3J0cyAyMDAgd2l0aCB0aGUgZGVwIHNpbXBseSBhYnNlbnQgKGEgc2lsZW50IGZhbHNlLWhlYWx0aHkpLCByYXRoZXIgdGhhblxuICogc3VyZmFjaW5nIGl0IGFzIGBkaXNjb25uZWN0ZWRgLiBUaGUgYC5jYXRjaCgoKSA9PiAoe30pKWAgYmVsb3cgb25seSBleGlzdHMgc29cbiAqIG9uZSBtaXNiZWhhdmluZyBwcm9iZSBjYW4ndCB0YWtlIGRvd24gdGhlIG90aGVycywgTk9UIGFzIGEgc3Vic3RpdHV0ZSBmb3IgYVxuICogcHJvYmUgcmV0dXJuaW5nIGl0cyBvd24gZGlzY29ubmVjdGVkIHN0YXR1cy5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGNvbWJpbmVIZWFsdGhDaGVja3MoXG4gIC4uLmNoZWNrczogQXJyYXk8KCkgPT4gUHJvbWlzZTxIZWFsdGhSZXN1bHQ+PlxuKTogKCkgPT4gUHJvbWlzZTxIZWFsdGhSZXN1bHQ+IHtcbiAgcmV0dXJuIGFzeW5jICgpID0+IHtcbiAgICBjb25zdCByZXN1bHRzID0gYXdhaXQgUHJvbWlzZS5hbGwoY2hlY2tzLm1hcCgoY2hlY2spID0+IGNoZWNrKCkuY2F0Y2goKCkgPT4gKHt9IGFzIEhlYWx0aFJlc3VsdCkpKSk7XG4gICAgcmV0dXJuIE9iamVjdC5hc3NpZ24oe30sIC4uLnJlc3VsdHMpIGFzIEhlYWx0aFJlc3VsdDtcbiAgfTtcbn1cblxuLyoqXG4gKiBNaW5pbWFsIHNoYXBlIGV4cGVjdGVkIG9mIGEgbW9uZ29vc2UgY29ubmVjdGlvbiBmb3IgdGhlIGhlYWx0aCBwcm9iZS5cbiAqIEFjY2VwdHMgYG1vbmdvb3NlLmNvbm5lY3Rpb25gIGRpcmVjdGx5IHdpdGhvdXQgcmVxdWlyaW5nIG1vbmdvb3NlIGFzIGFcbiAqIGRlcGVuZGVuY3kgb2YgYXBpLXNlcnZlci5cbiAqL1xuaW50ZXJmYWNlIE1vbmdvb3NlQ29ubmVjdGlvbkxpa2Uge1xuICByZWFkeVN0YXRlOiBudW1iZXI7XG59XG5cbi8qKlxuICogTW9uZ29EQiBoZWFsdGggcHJvYmUgZmFjdG9yeTogcGFzcyBgbW9uZ29vc2UuY29ubmVjdGlvbmAgYW5kIGdldCBiYWNrIGFcbiAqIGBjaGVja0RlcGVuZGVuY2llc2AgY2FsbGJhY2sgdGhhdCByZXBvcnRzIGJhc2VkIG9uIG1vbmdvb3NlJ3MgcmVhZHlTdGF0ZS5cbiAqXG4gKiBNYXBwaW5nIChwZXIgbW9uZ29vc2UgZG9jcyk6IDE9Y29ubmVjdGVkLCAyPWNvbm5lY3RpbmcsIDM9ZGlzY29ubmVjdGluZyxcbiAqIGFueSBvdGhlciB2YWx1ZSAoMD1kaXNjb25uZWN0ZWQsIDk5PXVuaW5pdGlhbGl6ZWQpIGlzIHRyZWF0ZWQgYXNcbiAqICdkaXNjb25uZWN0ZWQnIHNvIGAvaGVhbHRoYCByZXR1cm5zIDUwMy5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIG1vbmdvSGVhbHRoQ2hlY2soY29ubmVjdGlvbjogTW9uZ29vc2VDb25uZWN0aW9uTGlrZSk6ICgpID0+IFByb21pc2U8SGVhbHRoUmVzdWx0PiB7XG4gIHJldHVybiBhc3luYyAoKSA9PiAoe1xuICAgIG1vbmdvZGI6IGNvbm5lY3Rpb24ucmVhZHlTdGF0ZSA9PT0gMSA/ICdjb25uZWN0ZWQnXG4gICAgICA6IGNvbm5lY3Rpb24ucmVhZHlTdGF0ZSA9PT0gMiA/ICd1bmtub3duJyAvLyBjb25uZWN0aW5nOyB0cmVhdCBhcyB0cmFuc2llbnRcbiAgICAgICAgOiAnZGlzY29ubmVjdGVkJyxcbiAgfSk7XG59XG4iXX0=

package/lib/api/idempotency-middleware.d.ts

@@ -0,0 +1,80 @@
+import type { Request, Response, NextFunction } from 'express';
+interface CachedEntry {
+    statusCode: number;
+    body: unknown;
+    expiresAt: number;
+    /** Reservation placeholder: the request is in-flight, no real response yet.
+     *  A duplicate that sees a pending entry is rejected with 409, not replayed. */
+    pending?: boolean;
+}
+/**
+ * Pluggable backend for idempotency-key replay cache. The default in-memory
+ * implementation works fine single-replica; a Redis-backed implementation
+ * is required for correct deduplication across horizontally-scaled replicas
+ * (otherwise two replicas behind a load-balancer cache independently and a
+ * retry hitting a different pod won't replay).
+ */
+export interface IdempotencyStore {
+    get(key: string): Promise<CachedEntry | null>;
+    set(key: string, entry: CachedEntry, ttlSeconds: number): Promise<void>;
+    /**
+     * Atomically claim `key` IFF it is currently absent. Returns `true` when THIS
+     * caller set the entry (won the race), `false` when an entry already exists.
+     * This is what serializes concurrent first-time requests that share an
+     * Idempotency-Key — a plain get-then-set leaves a window where two requests
+     * both see "not cached" and both execute the mutation.
+     */
+    reserve(key: string, entry: CachedEntry, ttlSeconds: number): Promise<boolean>;
+    /** Remove a key — releases a reservation after a non-cacheable (non-2xx) response. */
+    delete(key: string): Promise<void>;
+}
+/** Default in-memory store. Single-replica only. Exported for testing. */
+export declare function createMemoryStore(): IdempotencyStore;
+/**
+ * Minimal Redis surface the idempotency store needs (an ioredis subset).
+ * `set` supports the variadic option tail: `SET key val EX <ttl> [NX]`, which
+ * returns `'OK'` on success and `null` when an `NX` set was refused.
+ */
+export interface RedisIdempotencyClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: (string | number)[]): Promise<string | null>;
+    del(key: string): Promise<number>;
+}
+/**
+ * Redis-backed {@link IdempotencyStore} for correct deduplication across
+ * horizontally-scaled replicas. `reserve` maps to an atomic `SET … NX` so two
+ * pods behind a load-balancer can't both win a first-time request sharing an
+ * Idempotency-Key; a retry landing on ANY pod sees the same committed response.
+ * Redis TTL owns expiry (the `CachedEntry.expiresAt` field is carried only for
+ * API-shape parity with the memory store).
+ */
+export declare function createRedisIdempotencyStore(redis: RedisIdempotencyClient): IdempotencyStore;
+/**
+ * Build a Redis-backed idempotency store from the shared env Redis (the same
+ * `REDIS_URL` / `REDIS_HOST` wiring the rate-limiter and audit-spool use).
+ * Returns `null` when Redis isn't configured/available so the caller keeps the
+ * in-memory default (single-replica correctness). Never throws.
+ */
+export declare function createEnvRedisIdempotencyStore(): IdempotencyStore | null;
+/** Inject the process-wide idempotency store (e.g. a Redis-backed one). */
+export declare function setIdempotencyStore(store: IdempotencyStore): void;
+/** The current process-wide default store (in-memory unless overridden). */
+export declare function getIdempotencyStore(): IdempotencyStore;
+export interface IdempotencyMiddlewareOptions {
+    /** Custom store backend. Defaults to the process-wide store set via
+     *  {@link setIdempotencyStore} (in-memory until `createApp` wires Redis). */
+    store?: IdempotencyStore;
+}
+/**
+ * Middleware that supports idempotency keys for POST/PUT/DELETE mutations.
+ *
+ * When a request includes the `Idempotency-Key` header:
+ * - First call: processes normally, caches the response
+ * - Subsequent calls with same key: returns cached response (prevents duplicate mutations)
+ *
+ * Defaults to an in-memory store (single-replica). Pass a custom
+ * cross-replica `{ store }` implementing `IdempotencyStore` to dedupe across
+ * replicas.
+ */
+export declare function idempotencyMiddleware(options?: IdempotencyMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => void;
+export {};