@centralping/ergo 0.1.0-beta.2 → 0.1.0-beta.4

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+## [0.1.0-beta.4] - 2026-05-29
+
+### Added
+
+- JSON Schema `format` keyword support via `ajv-formats`. Standard formats (`email`, `uri`,
+  `date-time`, `uuid`, etc.) are validated by default. Opt out with `formats: false` or select
+  specific formats with an array (e.g. `formats: ['email', 'uri']`). (#58)
+
+### Fixed
+
+- **BREAKING**: `accepts()` now defaults `throwIfFail` to `true`, enforcing 406 responses for unsatisfied content negotiation per the Fast Fail pipeline contract. Set `throwIfFail: false` to restore the previous informational-only behavior. (#55)
+- `body()` default types now include `application/merge-patch+json` (RFC 7386) and `application/json-patch+json` (RFC 6902), resolving 415 rejections for valid PATCH content types that ergo-router's `strictPatch` allows. (#56)
+- `validate()` params validation now checks `acc.route.params` (ergo-router convention) with fallback to `acc.params` (standalone), fixing silent no-op validation when used with ergo-router. (#57)
+
 ## [0.1.0-beta.1] - 2026-05-20
 
 ### Changed

package/README.md

@@ -135,4 +135,4 @@ npm run format      # Prettier
 
 ## License
 
-[MIT](LICENSE) © 2019-present Jason Cust
+[MIT](https://github.com/CentralPing/ergo/blob/main/LICENSE) © 2019-present Jason Cust

package/http/accepts.js

@@ -5,9 +5,9 @@
  * `Accept-Charset`, and `Accept-Encoding` request headers and determine the best
  * matching content type, language, charset, and encoding for the response.
  *
- * When `throwIfFail` is true, returns `{response: {statusCode: 406, detail}}` for any
- * header that cannot be satisfied, enforcing strict content negotiation in the
- * Fast Fail pipeline.
+ * By default, returns `{response: {statusCode: 406, detail}}` for any header
+ * that cannot be satisfied, enforcing strict content negotiation in the Fast
+ * Fail pipeline. Set `throwIfFail: false` for informational-only negotiation.
  *
  * @module http/accepts
  * @since 0.1.0
@@ -37,14 +37,14 @@ const headerMap = {
  * Creates a content negotiation middleware.
  *
  * @param {object} [options] - Negotiation configuration
- * @param {boolean} [options.throwIfFail=false] - Return `{response: {statusCode: 406, detail}}` if any negotiation key is undefined
+ * @param {boolean} [options.throwIfFail=true] - Return `{response: {statusCode: 406, detail}}` if any negotiation key is undefined
  * @param {string[]} [options.types] - Acceptable media types
  * @param {string[]} [options.languages] - Acceptable languages
  * @param {string[]} [options.charsets] - Acceptable character sets
  * @param {string[]} [options.encodings] - Acceptable content encodings
  * @returns {function} - Middleware `(req) => {type, language, charset, encoding}` on success, or `{response: {statusCode: 406, detail: string}}` when `throwIfFail` is true and any negotiation value is undefined
  */
-export default ({throwIfFail = false, ...options} = {}) => {
+export default ({throwIfFail = true, ...options} = {}) => {
   const acceptor = accepts(options);
 
   return ({headers = {}} = {}) => {

package/http/body.js

@@ -2,7 +2,8 @@
  * @fileoverview HTTP middleware factory for request body parsing.
  *
  * Reads and parses the request body according to the declared `Content-Type`. Supports:
- * - `application/json` and `application/vnd.api+json` — parsed via `JSON.parse`
+ * - `application/json`, `application/vnd.api+json`, `application/merge-patch+json`
+ *   (RFC 7386), and `application/json-patch+json` (RFC 6902) — parsed via `JSON.parse`
  * - `application/x-www-form-urlencoded` — parsed via the query string parser
  * - `multipart/form-data` — parsed via the RFC 7578 streaming multipart parser
  *
@@ -128,6 +129,8 @@ export default ({
     types = [
       'application/vnd.api+json',
       'application/json',
+      'application/merge-patch+json',
+      'application/json-patch+json',
       'application/x-www-form-urlencoded',
       'multipart/form-data'
     ],

package/http/idempotency.js

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Idempotency-Key pipeline middleware.
+ *
+ * Detects duplicate requests by `Idempotency-Key` header value per
+ * draft-ietf-httpapi-idempotency-key-header-07. When a matching key with
+ * the same request fingerprint is found, the stored response is replayed.
+ * When a key matches but the fingerprint differs, a 409 Conflict is returned.
+ *
+ * Placed in Stage 3 (Validation) after body parsing so the request body
+ * fingerprint can be computed from the parsed body.
+ *
+ * @module http/idempotency
+ * @since 0.1.0-beta.2
+ * @requires ../lib/idempotency.js
+ *
+ * @example
+ * import {compose, body, idempotency} from '@centralping/ergo';
+ *
+ * const pipeline = compose(
+ *   [body(), 'body'],
+ *   [idempotency({required: true}), 'idempotency'],
+ *   (req, res, acc) => ({response: {statusCode: 201, body: {created: true}}})
+ * );
+ *
+ * @see {@link https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/ Idempotency-Key Header (IETF Draft)}
+ */
+import {IdempotencyStore, parseIdempotencyKey, generateFingerprint} from '../lib/idempotency.js';
+
+const DEFAULT_METHODS = new Set(['POST', 'PATCH']);
+
+/**
+ * Create an idempotency middleware.
+ *
+ * @param {object} [options]
+ * @param {object} [options.store] - Pluggable store (must implement get/set/complete/delete).
+ *   Defaults to an in-memory store with 24h TTL.
+ * @param {number} [options.ttlMs=86400000] - TTL for stored entries in milliseconds (default: 24h).
+ *   Only used when creating the default in-memory store.
+ * @param {boolean} [options.required=false] - When true, returns 400 if the header is missing
+ *   on applicable methods
+ * @param {Set<string>|string[]} [options.methods] - HTTP methods to apply idempotency to
+ *   (default: POST, PATCH)
+ * @returns {function} - Middleware `(req, res, domainAcc) => {value?, response?}`
+ */
+export default function idempotency({store, ttlMs, required = false, methods} = {}) {
+  const _store = store ?? new IdempotencyStore(ttlMs ? {ttlMs} : undefined);
+  const _methods = methods instanceof Set ? methods : new Set(methods ?? DEFAULT_METHODS);
+
+  return (req, _res, domainAcc) => {
+    if (!_methods.has(req.method)) return {};
+
+    const key = parseIdempotencyKey(req.headers?.['idempotency-key']);
+
+    if (!key) {
+      if (required) {
+        return {
+          response: {
+            statusCode: 400,
+            detail: 'Idempotency-Key header is required'
+          }
+        };
+      }
+      return {};
+    }
+
+    const rawBody = domainAcc?.body?.raw ?? domainAcc?.body?.parsed ?? '';
+    const fingerprint = generateFingerprint(
+      typeof rawBody === 'string' ? rawBody : JSON.stringify(rawBody)
+    );
+
+    const existing = _store.get(key);
+
+    if (existing) {
+      if (existing.fingerprint !== fingerprint) {
+        return {
+          response: {
+            statusCode: 409,
+            detail: 'Idempotency key already used with a different request'
+          }
+        };
+      }
+
+      if (existing.status === 'complete' && existing.response) {
+        return {
+          value: {replayed: true},
+          response: existing.response
+        };
+      }
+
+      // Still processing — concurrent duplicate
+      return {
+        response: {
+          statusCode: 409,
+          detail: 'A request with this idempotency key is already being processed'
+        }
+      };
+    }
+
+    _store.set(key, fingerprint);
+
+    return {
+      value: {
+        key,
+        fingerprint,
+        complete: response => _store.complete(key, response),
+        discard: () => _store.delete(key)
+      }
+    };
+  };
+}

package/http/main.js

@@ -80,6 +80,7 @@ import rateLimit from './rate-limit.js';
 import securityHeaders from './security-headers.js';
 import send from './send.js';
 import timeout from './timeout.js';
+import idempotency from './idempotency.js';
 import validate from './validate.js';
 import httpErrors from '../utils/http-errors.js';
 import fromConnect from '../lib/from-connect.js';
@@ -99,6 +100,7 @@ export {
   csrf,
   fromConnect,
   httpErrors,
+  idempotency,
   jsonApiQuery,
   logger,
   prefer,
@@ -126,6 +128,7 @@ export default {
   csrf,
   fromConnect,
   httpErrors,
+  idempotency,
   jsonApiQuery,
   logger,
   prefer,

package/http/validate.js

@@ -1,8 +1,10 @@
 /**
  * @fileoverview HTTP middleware factory for JSON Schema validation.
  *
- * Validates properties from the accumulator (body, url, params) against provided JSON
- * Schemas using AJV. Schemas are compiled once at middleware creation time for performance.
+ * Validates properties from the accumulator (body, url, route params) against provided
+ * JSON Schemas using AJV. Schemas are compiled once at middleware creation time for
+ * performance. Route params are resolved from `acc.route.params` (ergo-router) with
+ * fallback to `acc.params` (standalone).
  *
  * Returns `{response: {statusCode: 422, detail: ...}}` with structured error details on validation failure.
  * Must be placed after `body()` and/or `url()` in the pipeline so accumulator values
@@ -39,8 +41,10 @@ import createValidator from '../lib/validate.js';
  * @param {object} [schemas] - Schema map; each key corresponds to an accumulator property
  * @param {object} [schemas.body] - JSON Schema for the parsed request body
  * @param {object} [schemas.query] - JSON Schema for parsed query parameters
- * @param {object} [schemas.params] - JSON Schema for route path parameters
+ * @param {object} [schemas.params] - JSON Schema for route path parameters (reads `acc.route.params` or `acc.params`)
  * @param {object} [options] - AJV options forwarded to each compiled validator
+ * @param {boolean|Array<string>|object} [options.formats] - Format keyword support via
+ *   `ajv-formats`; forwarded to `createValidator`. Defaults to all standard formats enabled
  * @returns {function} - Ergo middleware `(req, res, acc) => void` that returns `{response: {statusCode: 422}}`
  *   (with `detail` and `details` from AJV) on validation failure
  */
@@ -67,8 +71,8 @@ export default (schemas = {}, options = {}) => {
         validators.query(acc.url.query);
       }
 
-      if (validators.params && acc.params) {
-        validators.params(acc.params);
+      if (validators.params && (acc.route?.params ?? acc.params)) {
+        validators.params(acc.route?.params ?? acc.params);
       }
     } catch (err) {
       return {

package/lib/idempotency.js

@@ -0,0 +1,139 @@
+/**
+ * @fileoverview Idempotency-Key shared primitives.
+ *
+ * Provides the core building blocks for idempotent request handling per
+ * draft-ietf-httpapi-idempotency-key-header-07. The `IdempotencyStore`
+ * manages key lifecycle (storage, expiry, replay). `parseIdempotencyKey`
+ * extracts the key value from the RFC 8941 structured field header.
+ * `generateFingerprint` creates a SHA-256 hash of the request body for
+ * detecting key reuse with different payloads.
+ *
+ * Used by:
+ * - `http/idempotency.js` (ergo pipeline middleware)
+ *
+ * @module lib/idempotency
+ * @since 0.1.0-beta.2
+ *
+ * @example
+ * import {IdempotencyStore, parseIdempotencyKey, generateFingerprint}
+ *   from '@centralping/ergo/lib/idempotency';
+ *
+ * const store = new IdempotencyStore();
+ * const key = parseIdempotencyKey(req.headers['idempotency-key']);
+ * const fingerprint = generateFingerprint(body);
+ *
+ * @see {@link https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/ Idempotency-Key Header (IETF Draft)}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8941 RFC 8941 - Structured Field Values}
+ */
+import {createHash} from 'node:crypto';
+
+const SF_STRING_RE = /^"([^"\\]*(?:\\.[^"\\]*)*)"$/;
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+/**
+ * In-memory idempotency key store with TTL-based expiry.
+ *
+ * Entries transition through states: `processing` -> `complete`.
+ * Expired entries are pruned lazily on `get()` calls.
+ */
+export class IdempotencyStore {
+  constructor({maxKeys = 10_000, ttlMs = DEFAULT_TTL_MS} = {}) {
+    this._entries = new Map();
+    this._maxKeys = maxKeys;
+    this._ttlMs = ttlMs;
+  }
+
+  /**
+   * Retrieve a stored entry by key. Returns `undefined` if not found or expired.
+   * @param {string} key - Idempotency key
+   * @returns {{fingerprint: string, response: object, status: string, expiresAt: number} | undefined}
+   */
+  get(key) {
+    const entry = this._entries.get(key);
+    if (!entry) return undefined;
+
+    if (Date.now() > entry.expiresAt) {
+      this._entries.delete(key);
+      return undefined;
+    }
+
+    return entry;
+  }
+
+  /**
+   * Store a new idempotency entry in `processing` state.
+   * @param {string} key - Idempotency key
+   * @param {string} fingerprint - Request body fingerprint
+   */
+  set(key, fingerprint) {
+    if (this._entries.size >= this._maxKeys) {
+      const oldest = this._entries.keys().next().value;
+      this._entries.delete(oldest);
+    }
+
+    const entry = Object.create(null);
+    entry.fingerprint = fingerprint;
+    entry.response = undefined;
+    entry.status = 'processing';
+    entry.expiresAt = Date.now() + this._ttlMs;
+    this._entries.set(key, entry);
+  }
+
+  /**
+   * Mark an entry as complete with the response to replay.
+   * @param {string} key - Idempotency key
+   * @param {object} response - Response accumulator snapshot to replay
+   */
+  complete(key, response) {
+    const entry = this._entries.get(key);
+    if (entry) {
+      entry.status = 'complete';
+      entry.response = response;
+    }
+  }
+
+  /**
+   * Remove an entry (e.g. on request failure where replay is not desired).
+   * @param {string} key - Idempotency key
+   */
+  delete(key) {
+    this._entries.delete(key);
+  }
+}
+
+/**
+ * Parse an `Idempotency-Key` header value as an RFC 8941 sf-string.
+ *
+ * The draft specifies the header is an Item Structured Header whose value
+ * is a String. This means the wire format is `"value"` (double-quoted).
+ * Returns `undefined` for missing, empty, or malformed values.
+ *
+ * @param {string | undefined} header - Raw header value
+ * @returns {string | undefined} - Parsed key value, or undefined
+ */
+export function parseIdempotencyKey(header) {
+  if (!header) return undefined;
+
+  const trimmed = header.trim();
+  const match = SF_STRING_RE.exec(trimmed);
+  if (!match) return undefined;
+
+  const inner = match[1];
+  if (inner.replace(/\\["\\]/g, '').includes('\\')) return undefined;
+  return inner.replace(/\\(["\\])/g, '$1');
+}
+
+/**
+ * Generate a SHA-256 fingerprint of the request body.
+ *
+ * Used to detect key reuse with different payloads (which should return 409).
+ * Accepts strings or Buffers. Returns the hex digest.
+ *
+ * @param {string | Buffer} body - Serialized request body
+ * @returns {string} - Hex-encoded SHA-256 hash
+ */
+export function generateFingerprint(body) {
+  return createHash('sha256')
+    .update(body ?? '')
+    .digest('hex');
+}

package/lib/link.js

@@ -2,9 +2,9 @@
  * @fileoverview RFC 8288 Web Linking utilities.
  *
  * Provides functions for formatting `Link` response headers per RFC 8288.
- * `formatLinkHeader` is the low-level formatter; `paginationLinks` is a
- * convenience helper that generates `first`, `prev`, `next`, `last` link
- * objects from pagination parameters.
+ * `formatLinkHeader` is the low-level formatter; `paginationLinks` and
+ * `cursorPaginationLinks` are convenience helpers that generate link objects
+ * for offset-based and cursor-based pagination respectively.
  *
  * These are pure utility functions (not middleware). Consumers wire the
  * formatted header value into the accumulator's `headers` array for `send()`.
@@ -15,8 +15,10 @@
  * @see {@link https://www.rfc-editor.org/rfc/rfc8288 RFC 8288 - Web Linking}
  *
  * @example
- * import {formatLinkHeader, paginationLinks} from '@centralping/ergo/lib/link';
+ * import {formatLinkHeader, paginationLinks, cursorPaginationLinks}
+ *   from '@centralping/ergo/lib/link';
  *
+ * // Offset-based pagination
  * const links = paginationLinks({
  *   baseUrl: '/articles',
  *   searchParams: 'sort=date',
@@ -26,6 +28,15 @@
  * });
  * const header = formatLinkHeader(links);
  * // '</articles?sort=date&page=1&per_page=25>; rel="first", ...'
+ *
+ * // Cursor-based pagination
+ * const cursorLinks = cursorPaginationLinks({
+ *   baseUrl: '/articles',
+ *   searchParams: 'sort=date',
+ *   nextCursor: 'eyJpZCI6NDJ9.abc123'
+ * });
+ * const cursorHeader = formatLinkHeader(cursorLinks);
+ * // '</articles?sort=date>; rel="first", </articles?sort=date&cursor=eyJpZCI6NDJ9.abc123>; rel="next"'
  */
 import sanitizeQuotedString from './sanitize-quoted-string.js';
 
@@ -93,3 +104,45 @@ export function paginationLinks({baseUrl, page, perPage, total, searchParams = '
 
   return links;
 }
+
+/**
+ * Generates cursor-based pagination link objects for first, prev, and next pages.
+ *
+ * Unlike offset pagination, cursor-based pagination uses opaque continuation
+ * tokens instead of page numbers. There is no `last` link because the total
+ * number of pages is unknown in cursor-based schemes.
+ *
+ * The `first` link is always present and points to the base URL without any
+ * cursor parameter (requesting the first page). `prev` and `next` are
+ * included only when the corresponding cursor token is provided.
+ *
+ * @param {object} options - Cursor pagination parameters
+ * @param {string} options.baseUrl - Base URL path (e.g. '/articles')
+ * @param {string} [options.searchParams=''] - Additional query parameters to preserve
+ *   (e.g. 'sort=date&filter=active'). Appended before the cursor parameter.
+ * @param {string} [options.nextCursor] - Opaque cursor token for the next page
+ * @param {string} [options.prevCursor] - Opaque cursor token for the previous page
+ * @returns {Array<{href: string, rel: string}>} - Array of link objects
+ */
+export function cursorPaginationLinks({baseUrl, searchParams = '', nextCursor, prevCursor}) {
+  const base = searchParams ? `${baseUrl}?${searchParams}` : baseUrl;
+  const sep = searchParams ? '&' : '?';
+
+  const links = [{href: base, rel: 'first'}];
+
+  if (prevCursor !== undefined) {
+    links.push({
+      href: `${base}${sep}cursor=${encodeURIComponent(prevCursor)}`,
+      rel: 'prev'
+    });
+  }
+
+  if (nextCursor !== undefined) {
+    links.push({
+      href: `${base}${sep}cursor=${encodeURIComponent(nextCursor)}`,
+      rel: 'next'
+    });
+  }
+
+  return links;
+}

package/lib/validate.js

@@ -10,6 +10,7 @@
  * @module lib/validate
  * @since 0.1.0
  * @requires ajv
+ * @requires ajv-formats
  * @requires ../utils/http-errors.js
  *
  * @example
@@ -25,6 +26,7 @@
  * validate({});                    // throws 422 with details
  */
 import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
 import httpErrors from '../utils/http-errors.js';
 
 /**
@@ -34,6 +36,11 @@ import httpErrors from '../utils/http-errors.js';
  * @param {object} [options] - Validator options
  * @param {boolean} [options.allErrors=true] - Report all errors instead of stopping at the first
  * @param {boolean} [options.coerceTypes=false] - Coerce input values to match schema types
+ * @param {boolean|Array<string>|object} [options.formats] - Format keyword support via
+ *   `ajv-formats`. `undefined` or `true` enables all standard formats; `false` disables (AJV
+ *   strict mode rejects unknown formats); an array enables selective formats
+ *   (e.g. `['email', 'uri']`); an object is passed as the full plugin config
+ *   (e.g. `{mode: 'fast'}`)
  * @param {object} [options.ajv] - Additional AJV constructor options
  * @returns {function} - `validateData(data)` — returns `data` on success, throws 422 on failure
  * @throws {Error} 422 with `details` array if schema validation fails
@@ -45,6 +52,13 @@ export default function createValidator(schema, options = {}) {
     ...options.ajv
   });
 
+  if (options.formats !== false) {
+    addFormats(
+      ajv,
+      options.formats === true || options.formats === undefined ? undefined : options.formats
+    );
+  }
+
   const validate = ajv.compile(schema);
 
   return function validateData(data) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centralping/ergo",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "description": "A Fast Fail REST API toolkit for Node.js -- composable middleware with structured Negotiation, Authorization, Validation, and Execution stages.",
   "main": "http/index.js",
   "type": "module",
@@ -116,6 +116,7 @@
   },
   "dependencies": {
     "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "content-type": "^2.0.0",
     "etag": "^1.8.1",
     "negotiator": "^1.0.0"

package/types/http/idempotency.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Create an idempotency middleware.
+ *
+ * @param {object} [options]
+ * @param {object} [options.store] - Pluggable store (must implement get/set/complete/delete).
+ *   Defaults to an in-memory store with 24h TTL.
+ * @param {number} [options.ttlMs=86400000] - TTL for stored entries in milliseconds (default: 24h).
+ *   Only used when creating the default in-memory store.
+ * @param {boolean} [options.required=false] - When true, returns 400 if the header is missing
+ *   on applicable methods
+ * @param {Set<string>|string[]} [options.methods] - HTTP methods to apply idempotency to
+ *   (default: POST, PATCH)
+ * @returns {function} - Middleware `(req, res, domainAcc) => {value?, response?}`
+ */
+export default function idempotency({ store, ttlMs, required, methods }?: {
+    store?: object | undefined;
+    ttlMs?: number | undefined;
+    required?: boolean | undefined;
+    methods?: string[] | Set<string> | undefined;
+}): Function;

package/types/http/main.d.ts

@@ -75,6 +75,7 @@ declare const _default: {
     }) => object;
     fromConnect: typeof fromConnect;
     httpErrors: typeof httpErrors;
+    idempotency: typeof idempotency;
     jsonApiQuery: (...options: any[]) => Function;
     logger: ({ log, error: logError, uuid, headerRequestIdName, headerRequestIpName, redactHeaders }?: {
         log?: Function | undefined;
@@ -112,7 +113,9 @@ declare const _default: {
         body?: object | undefined;
         query?: object | undefined;
         params?: object | undefined;
-    }, options?: object) => Function;
+    }, options?: {
+        formats?: boolean | object | string[] | undefined;
+    }) => Function;
 };
 export default _default;
 import compose from '../utils/compose-with.js';
@@ -129,6 +132,7 @@ import cors from './cors.js';
 import csrf from './csrf.js';
 import fromConnect from '../lib/from-connect.js';
 import httpErrors from '../utils/http-errors.js';
+import idempotency from './idempotency.js';
 import jsonApiQuery from './json-api-query.js';
 import logger from './logger.js';
 import prefer from './prefer.js';
@@ -139,4 +143,4 @@ import url from './url.js';
 import send from './send.js';
 import timeout from './timeout.js';
 import validate from './validate.js';
-export { compose, createResponseAcc, mergeResponse, handler, accepts, authorization, body, cacheControl, compress, cookie, cors, csrf, fromConnect, httpErrors, jsonApiQuery, logger, prefer, precondition, rateLimit, securityHeaders, url, send, timeout, validate };
+export { compose, createResponseAcc, mergeResponse, handler, accepts, authorization, body, cacheControl, compress, cookie, cors, csrf, fromConnect, httpErrors, idempotency, jsonApiQuery, logger, prefer, precondition, rateLimit, securityHeaders, url, send, timeout, validate };

package/types/http/validate.d.ts

@@ -2,5 +2,7 @@ declare function _default(schemas?: {
     body?: object | undefined;
     query?: object | undefined;
     params?: object | undefined;
-}, options?: object): Function;
+}, options?: {
+    formats?: boolean | object | string[] | undefined;
+}): Function;
 export default _default;

package/types/lib/idempotency.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Parse an `Idempotency-Key` header value as an RFC 8941 sf-string.
+ *
+ * The draft specifies the header is an Item Structured Header whose value
+ * is a String. This means the wire format is `"value"` (double-quoted).
+ * Returns `undefined` for missing, empty, or malformed values.
+ *
+ * @param {string | undefined} header - Raw header value
+ * @returns {string | undefined} - Parsed key value, or undefined
+ */
+export function parseIdempotencyKey(header: string | undefined): string | undefined;
+/**
+ * Generate a SHA-256 fingerprint of the request body.
+ *
+ * Used to detect key reuse with different payloads (which should return 409).
+ * Accepts strings or Buffers. Returns the hex digest.
+ *
+ * @param {string | Buffer} body - Serialized request body
+ * @returns {string} - Hex-encoded SHA-256 hash
+ */
+export function generateFingerprint(body: string | Buffer): string;
+/**
+ * In-memory idempotency key store with TTL-based expiry.
+ *
+ * Entries transition through states: `processing` -> `complete`.
+ * Expired entries are pruned lazily on `get()` calls.
+ */
+export class IdempotencyStore {
+    constructor({ maxKeys, ttlMs }?: {
+        maxKeys?: number | undefined;
+        ttlMs?: number | undefined;
+    });
+    _entries: Map<any, any>;
+    _maxKeys: number;
+    _ttlMs: number;
+    /**
+     * Retrieve a stored entry by key. Returns `undefined` if not found or expired.
+     * @param {string} key - Idempotency key
+     * @returns {{fingerprint: string, response: object, status: string, expiresAt: number} | undefined}
+     */
+    get(key: string): {
+        fingerprint: string;
+        response: object;
+        status: string;
+        expiresAt: number;
+    } | undefined;
+    /**
+     * Store a new idempotency entry in `processing` state.
+     * @param {string} key - Idempotency key
+     * @param {string} fingerprint - Request body fingerprint
+     */
+    set(key: string, fingerprint: string): void;
+    /**
+     * Mark an entry as complete with the response to replay.
+     * @param {string} key - Idempotency key
+     * @param {object} response - Response accumulator snapshot to replay
+     */
+    complete(key: string, response: object): void;
+    /**
+     * Remove an entry (e.g. on request failure where replay is not desired).
+     * @param {string} key - Idempotency key
+     */
+    delete(key: string): void;
+}

package/types/lib/link.d.ts

@@ -35,3 +35,31 @@ export function paginationLinks({ baseUrl, page, perPage, total, searchParams }:
     href: string;
     rel: string;
 }>;
+/**
+ * Generates cursor-based pagination link objects for first, prev, and next pages.
+ *
+ * Unlike offset pagination, cursor-based pagination uses opaque continuation
+ * tokens instead of page numbers. There is no `last` link because the total
+ * number of pages is unknown in cursor-based schemes.
+ *
+ * The `first` link is always present and points to the base URL without any
+ * cursor parameter (requesting the first page). `prev` and `next` are
+ * included only when the corresponding cursor token is provided.
+ *
+ * @param {object} options - Cursor pagination parameters
+ * @param {string} options.baseUrl - Base URL path (e.g. '/articles')
+ * @param {string} [options.searchParams=''] - Additional query parameters to preserve
+ *   (e.g. 'sort=date&filter=active'). Appended before the cursor parameter.
+ * @param {string} [options.nextCursor] - Opaque cursor token for the next page
+ * @param {string} [options.prevCursor] - Opaque cursor token for the previous page
+ * @returns {Array<{href: string, rel: string}>} - Array of link objects
+ */
+export function cursorPaginationLinks({ baseUrl, searchParams, nextCursor, prevCursor }: {
+    baseUrl: string;
+    searchParams?: string | undefined;
+    nextCursor?: string | undefined;
+    prevCursor?: string | undefined;
+}): Array<{
+    href: string;
+    rel: string;
+}>;

package/types/lib/validate.d.ts

@@ -5,6 +5,11 @@
  * @param {object} [options] - Validator options
  * @param {boolean} [options.allErrors=true] - Report all errors instead of stopping at the first
  * @param {boolean} [options.coerceTypes=false] - Coerce input values to match schema types
+ * @param {boolean|Array<string>|object} [options.formats] - Format keyword support via
+ *   `ajv-formats`. `undefined` or `true` enables all standard formats; `false` disables (AJV
+ *   strict mode rejects unknown formats); an array enables selective formats
+ *   (e.g. `['email', 'uri']`); an object is passed as the full plugin config
+ *   (e.g. `{mode: 'fast'}`)
  * @param {object} [options.ajv] - Additional AJV constructor options
  * @returns {function} - `validateData(data)` — returns `data` on success, throws 422 on failure
  * @throws {Error} 422 with `details` array if schema validation fails
@@ -12,5 +17,6 @@
 export default function createValidator(schema: object, options?: {
     allErrors?: boolean | undefined;
     coerceTypes?: boolean | undefined;
+    formats?: boolean | object | string[] | undefined;
     ajv?: object | undefined;
 }): Function;