@databehave/server 0.1.0

package/dist/middleware/request-validation.js

@@ -0,0 +1,328 @@
+import { matchPattern, parseRoutePattern } from '../route-key.js';
+import { compileValidator } from '../validation/validate.js';
+const PROBLEM_TYPE_BASE = 'https://github.com/ochairo/databehave/blob/main/docs/errors';
+const PROBLEM_TYPE_SLUG = {
+    400: 'malformed-body',
+    401: 'unauthorized',
+    413: 'payload-too-large',
+    415: 'unsupported-media-type',
+    422: 'request-validation',
+};
+const problemType = (status) => `${PROBLEM_TYPE_BASE}/${PROBLEM_TYPE_SLUG[status] ?? 'request-validation'}.md`;
+const HTTP_METHODS = new Set(['get', 'post', 'put', 'delete', 'patch', 'options', 'head', 'trace']);
+// Default cap on request-body size (bytes). Matches the express
+// `body-parser` default; raise via `validation.maxBodyBytes` only if
+// the spec genuinely demands large bodies.
+const DEFAULT_MAX_BODY_BYTES = 102400;
+const STATUS_TITLES = {
+    400: 'Malformed request',
+    401: 'Unauthorized',
+    413: 'Payload too large',
+    415: 'Unsupported media type',
+    422: 'Request validation failed',
+};
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const oasPathToInternal = (p) => p
+    .split('/')
+    .map((s) => (s.startsWith('{') && s.endsWith('}') ? `:${s.slice(1, -1)}` : s))
+    .join('/');
+const resolveParam = (raw, doc) => {
+    if (!isObj(raw))
+        return null;
+    let node = raw;
+    if (typeof node.$ref === 'string') {
+        const m = /^#\/components\/parameters\/(.+)$/.exec(node.$ref);
+        if (!m)
+            return null;
+        const docAny = doc;
+        const target = docAny.components?.parameters?.[decodeURIComponent(m[1])];
+        if (!isObj(target))
+            return null;
+        node = target;
+    }
+    if (typeof node.in !== 'string' || typeof node.name !== 'string')
+        return null;
+    return node;
+};
+export const createRequestValidationContext = (oas, options = {}) => {
+    const doc = oas;
+    const schemes = new Map();
+    for (const [name, scheme] of Object.entries(doc.components?.securitySchemes ?? {})) {
+        if (isObj(scheme) && typeof scheme.type === 'string') {
+            schemes.set(name, scheme);
+        }
+    }
+    const globalSecurity = doc.security ?? [];
+    const routes = [];
+    for (const [oasPath, methods] of Object.entries(doc.paths ?? {})) {
+        if (!isObj(methods))
+            continue;
+        let pattern;
+        try {
+            pattern = parseRoutePattern(oasPathToInternal(oasPath));
+        }
+        catch {
+            continue;
+        }
+        const pathLevelParams = Array.isArray(methods.parameters)
+            ? methods.parameters
+            : [];
+        for (const [methodName, op] of Object.entries(methods)) {
+            if (methodName === 'parameters' || !HTTP_METHODS.has(methodName))
+                continue;
+            if (!isObj(op))
+                continue;
+            const opNode = op;
+            const params = [];
+            const rawParams = [...pathLevelParams, ...(opNode.parameters ?? [])];
+            for (const raw of rawParams) {
+                const p = resolveParam(raw, doc);
+                if (!p || p.in === 'cookie')
+                    continue;
+                const schema = (p.schema ?? {});
+                const validator = compileValidator(schema, doc, `#/paths/${oasPath}/${methodName}/parameters/${p.name}`);
+                params.push({
+                    name: p.name,
+                    in: p.in,
+                    required: p.required === true || p.in === 'path',
+                    type: typeof schema.type === 'string' ? schema.type : null,
+                    validator,
+                });
+            }
+            const requestBody = opNode.requestBody;
+            const content = requestBody?.content;
+            const declaredTypes = content ? Object.keys(content) : [];
+            const hasJsonBody = declaredTypes.length > 0;
+            const bodyOnlyJson = hasJsonBody &&
+                declaredTypes.every((c) => /^application\/json(\b|;)/i.test(c));
+            const jsonSchema = content?.['application/json']?.schema;
+            const bodyValidator = jsonSchema
+                ? compileValidator(jsonSchema, doc, `#/paths/${oasPath}/${methodName}/requestBody`)
+                : null;
+            routes.push({
+                method: methodName.toUpperCase(),
+                pattern,
+                hasJsonBody,
+                bodyOnlyJson,
+                bodyRequired: requestBody?.required === true,
+                bodyValidator,
+                params,
+                security: opNode.security ?? globalSecurity,
+            });
+        }
+    }
+    return {
+        routes,
+        schemes,
+        maxBodyBytes: typeof options.maxBodyBytes === 'number' && options.maxBodyBytes > 0
+            ? options.maxBodyBytes
+            : DEFAULT_MAX_BODY_BYTES,
+    };
+};
+const coerce = (raw, type) => {
+    if (type === 'integer') {
+        if (!/^-?\d+$/.test(raw))
+            return raw;
+        const n = Number(raw);
+        return Number.isFinite(n) ? n : raw;
+    }
+    if (type === 'number') {
+        if (!/^-?\d+(?:\.\d+)?$/.test(raw))
+            return raw;
+        const n = Number(raw);
+        return Number.isFinite(n) ? n : raw;
+    }
+    if (type === 'boolean') {
+        if (raw === 'true')
+            return true;
+        if (raw === 'false')
+            return false;
+        return raw;
+    }
+    return raw;
+};
+const isSecuritySatisfied = (req, ctx, headers, url) => {
+    const names = Object.keys(req);
+    if (names.length === 0)
+        return true;
+    return names.every((name) => {
+        const scheme = ctx.schemes.get(name);
+        if (!scheme)
+            return false;
+        if (scheme.type === 'http') {
+            const auth = headers.get('authorization') ?? '';
+            const want = (scheme.scheme ?? 'bearer').toLowerCase();
+            return new RegExp(`^${want}\\s+`, 'i').test(auth);
+        }
+        if (scheme.type === 'apiKey') {
+            if (scheme.in === 'header' && scheme.name) {
+                return headers.has(scheme.name.toLowerCase());
+            }
+            if (scheme.in === 'query' && scheme.name) {
+                return url.searchParams.has(scheme.name);
+            }
+            return false;
+        }
+        // oauth2 / openIdConnect: presence-only check; full token validation
+        // (introspection, signature verification) is out of scope for a
+        // zero-dep walker. Consumers needing it should layer it via
+        // `hooks.onRequest`.
+        return headers.has('authorization');
+    });
+};
+const buildAuthChallenge = (reqs, ctx) => {
+    for (const r of reqs) {
+        for (const name of Object.keys(r)) {
+            const scheme = ctx.schemes.get(name);
+            if (scheme?.type === 'http') {
+                const s = (scheme.scheme ?? 'bearer').replace(/^./, (c) => c.toUpperCase());
+                return { 'www-authenticate': `${s} realm="api"` };
+            }
+        }
+    }
+    return { 'www-authenticate': 'Bearer realm="api"' };
+};
+const problem = (status, detail, violations = [], extraHeaders = {}) => {
+    const body = {
+        type: problemType(status),
+        title: STATUS_TITLES[status] ?? 'Request validation failed',
+        status,
+        detail,
+    };
+    if (violations.length > 0)
+        body.violations = violations;
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: {
+            'content-type': 'application/problem+json',
+            ...extraHeaders,
+        },
+    });
+};
+export const validateRequest = async (req, ctx) => {
+    const url = new URL(req.url);
+    const method = req.method.toUpperCase();
+    let matched = null;
+    for (const r of ctx.routes) {
+        if (r.method !== method)
+            continue;
+        const params = matchPattern(r.pattern, url.pathname);
+        if (params) {
+            matched = { route: r, params };
+            break;
+        }
+    }
+    // Unmatched paths fall through — they are either hand-written routes
+    // outside the OAS document or genuine 404s. Either way the validator
+    // has no contract to enforce.
+    if (!matched)
+        return null;
+    const { route, params } = matched;
+    const headers = new Map();
+    req.headers.forEach((v, k) => headers.set(k.toLowerCase(), v));
+    // 1) Security gate.
+    if (route.security.length > 0) {
+        const ok = route.security.some((sr) => isSecuritySatisfied(sr, ctx, headers, url));
+        if (!ok) {
+            return problem(401, 'missing or invalid credentials', [], buildAuthChallenge(route.security, ctx));
+        }
+    }
+    const hasBodyMethod = method !== 'GET' && method !== 'HEAD' && method !== 'OPTIONS';
+    const contentType = (headers.get('content-type') ?? '').split(';')[0]?.trim().toLowerCase() ?? '';
+    // 2) Content-Type guard for routes that declare a JSON-only requestBody.
+    if (hasBodyMethod && route.bodyOnlyJson && contentType && contentType !== 'application/json') {
+        return problem(415, `unsupported media type '${contentType}' (expected application/json)`);
+    }
+    const violations = [];
+    // 3) Body parse + validate.
+    if (hasBodyMethod && route.bodyValidator) {
+        let raw = '';
+        try {
+            raw = await req.clone().text();
+            /* c8 ignore start — `Request#clone().text()` only rejects on stream
+               I/O errors which the in-process unit harness cannot trigger. */
+        }
+        catch {
+            raw = '';
+        }
+        /* c8 ignore stop */
+        if (raw.length === 0) {
+            if (route.bodyRequired) {
+                return problem(422, 'request body is required', [
+                    { path: '/body', keyword: 'required', message: 'missing required body' },
+                ]);
+            }
+        }
+        else {
+            // Cap pre-parse body size (UTF-8 byte length, not JS string length).
+            // Default matches express body-parser; raise via
+            // `validation.maxBodyBytes` only if the spec demands large bodies.
+            const byteLen = Buffer.byteLength(raw, 'utf8');
+            if (byteLen > ctx.maxBodyBytes) {
+                return problem(413, `request body exceeds maxBodyBytes (${ctx.maxBodyBytes})`);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                return problem(400, 'malformed JSON body');
+            }
+            violations.push(...route.bodyValidator(parsed, '/body'));
+        }
+    }
+    // 4) Param validation (with type coercion for query/path/header).
+    for (const p of route.params) {
+        if (p.in === 'query') {
+            const raw = url.searchParams.get(p.name);
+            if (raw === null) {
+                if (p.required) {
+                    violations.push({
+                        path: `/query/${p.name}`,
+                        keyword: 'required',
+                        message: 'missing required query parameter',
+                    });
+                }
+                continue;
+            }
+            violations.push(...p.validator(coerce(raw, p.type), `/query/${p.name}`));
+        }
+        else if (p.in === 'path') {
+            const raw = params[p.name];
+            // Defensive: `matchPattern` always populates every named path
+            // segment when the route matches, so a missing path param is
+            // unreachable in practice. Kept as a guard against future
+            // refactors that loosen the matcher contract.
+            /* c8 ignore start */
+            if (raw === undefined) {
+                violations.push({
+                    path: `/path/${p.name}`,
+                    keyword: 'required',
+                    message: 'missing required path parameter',
+                });
+                continue;
+            }
+            /* c8 ignore stop */
+            violations.push(...p.validator(coerce(raw, p.type), `/path/${p.name}`));
+        }
+        else {
+            const raw = headers.get(p.name.toLowerCase());
+            if (raw === undefined) {
+                if (p.required) {
+                    violations.push({
+                        path: `/header/${p.name}`,
+                        keyword: 'required',
+                        message: 'missing required header',
+                    });
+                }
+                continue;
+            }
+            violations.push(...p.validator(coerce(raw, p.type), `/header/${p.name}`));
+        }
+    }
+    if (violations.length > 0) {
+        return problem(422, `request validation failed (${violations.length} violation${violations.length === 1 ? '' : 's'})`, violations);
+    }
+    return null;
+};
+//# sourceMappingURL=request-validation.js.map

package/dist/middleware/request-validation.js.map

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

package/dist/mock-mode.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Built-in mock-mode middleware.
+ *
+ * Selects an HTTP *status* per request and either short-circuits the
+ * handler with a synthesized response of that status or lets it
+ * through. All configuration is declarative — driven entirely by
+ * `mockMode` in `databehave.json`.
+ *
+ * Resolution order per request (first hit wins):
+ *   1. `pathOverrides["<METHOD> <path>"]`
+ *   2. `pathOverrides["<path>"]`
+ *   3. `defaultStatus`
+ *   4. passthrough (real handler runs)
+ *
+ * Body resolution for a non-passthrough status N:
+ *   1. status === 204                → empty body
+ *   2. `bodyResolver(method, path, N)` returns a body
+ *      (typically OpenAPI `responses[N]` schema mock)
+ *   3. fallback envelope `{ error: true, status: N }`
+ *
+ * The header `x-mock-status` is always tagged on the final response
+ * (configurable via `header`). Health paths bypass everything.
+ */
+import type { MockRequest, MockResponse } from './types.js';
+export type BodyResolver = (method: string, path: string, status: number) => unknown | undefined;
+/**
+ * Minimal logger interface (compatible with the host server's logger
+ * and with `console`). Only `warn` is required by mock-mode today; the
+ * shape is kept narrow so callers can pass an existing logger without
+ * adapter glue.
+ */
+export interface MockModeLogger {
+    warn(message: string): void;
+}
+export interface MockModeConfig {
+    /** Master switch. When `false` or absent, the feature is disabled. */
+    enabled?: boolean;
+    /** MockResponse header that tags every response with the resolved status. */
+    header?: string;
+    /**
+     * When `true`, an incoming request may force the mocked status by
+     * sending the same header (default `x-mock-status: 500`). Disabled
+     * by default so production-style mock servers don't expose status
+     * injection to arbitrary clients. Resolution becomes:
+     *   1. request `header` value (when `allowHeaderOverride === true`)
+     *   2. `pathOverrides["<METHOD> <path>"]`
+     *   3. `pathOverrides["<path>"]`
+     *   4. `defaultStatus`
+     *   5. passthrough
+     */
+    allowHeaderOverride?: boolean;
+    /** Paths exempt from status injection (typically health probes). */
+    healthPaths?: readonly string[];
+    /**
+     * Status applied when no `pathOverrides` entry matches. Omit (or set
+     * `undefined`) for passthrough (real handler runs). Set to an error
+     * code (e.g. `500`) to force every route to that status by default.
+     */
+    defaultStatus?: number;
+    /**
+     * Per-route status overrides. Keys use one of:
+     *   - `"<METHOD> <path>"` (e.g. `"GET /api/v1/x"`) — method-scoped
+     *   - `"<path>"`          (e.g. `"/api/v1/x"`)     — any method
+     * Paths must be absolute (start with `/`). Values are HTTP status codes.
+     */
+    pathOverrides?: Record<string, number>;
+    /**
+     * Logger used for non-fatal diagnostics (e.g. out-of-range header
+     * overrides). Defaults to the global `console`. Pass the host
+     * application's logger to keep mock-server output in one place
+     * instead of leaking to stdout/stderr.
+     */
+    logger?: MockModeLogger;
+}
+export interface MockModeHooks {
+    onRequest: (req: MockRequest) => MockResponse | undefined;
+    onResponse: (req: MockRequest, res: MockResponse) => MockResponse;
+}
+/**
+ * Resolve the status code for a request using only the supplied config.
+ * Returns `undefined` when the request should pass through.
+ * Exported for unit-testing; callers normally use `buildMockModeHooks`.
+ */
+export declare const resolveStatus: (method: string, path: string, config: MockModeConfig) => number | undefined;
+/**
+ * Build the onRequest / onResponse hook pair. Returns `undefined`
+ * when the feature is disabled (caller may skip wiring entirely).
+ *
+ * `bodyResolver` is optional. When provided, @databehave/server asks it for a
+ * body for the configured status (typically a generator backed by
+ * the OpenAPI `responses[N]` schema). When it returns `undefined`,
+ * the minimal envelope `{ error: true, status: N }` is used instead.
+ */
+export declare const buildMockModeHooks: (config: MockModeConfig, bodyResolver?: BodyResolver) => MockModeHooks | undefined;
+//# sourceMappingURL=mock-mode.d.ts.map

package/dist/mock-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-mode.d.ts","sourceRoot":"","sources":["../src/mock-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE3D,MAAM,MAAM,YAAY,GAAG,CACzB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,KACX,OAAO,GAAG,SAAS,CAAA;AAExB;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,oEAAoE;IACpE,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC/B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACtC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,cAAc,CAAA;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,YAAY,GAAG,SAAS,CAAA;IACzD,UAAU,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,YAAY,KAAK,YAAY,CAAA;CAClE;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,MAAM,EACd,MAAM,MAAM,EACZ,QAAQ,cAAc,KACrB,MAAM,GAAG,SAQX,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,cAAc,EACtB,eAAe,YAAY,KAC1B,aAAa,GAAG,SA4ElB,CAAA"}

package/dist/mock-mode.js

@@ -0,0 +1,95 @@
+/**
+ * Resolve the status code for a request using only the supplied config.
+ * Returns `undefined` when the request should pass through.
+ * Exported for unit-testing; callers normally use `buildMockModeHooks`.
+ */
+export const resolveStatus = (method, path, config) => {
+    const overrides = config.pathOverrides ?? {};
+    const m = method.toUpperCase();
+    const byMethodPath = overrides[`${m} ${path}`];
+    if (byMethodPath !== undefined)
+        return byMethodPath;
+    const byPath = overrides[path];
+    if (byPath !== undefined)
+        return byPath;
+    return config.defaultStatus;
+};
+/**
+ * Build the onRequest / onResponse hook pair. Returns `undefined`
+ * when the feature is disabled (caller may skip wiring entirely).
+ *
+ * `bodyResolver` is optional. When provided, @databehave/server asks it for a
+ * body for the configured status (typically a generator backed by
+ * the OpenAPI `responses[N]` schema). When it returns `undefined`,
+ * the minimal envelope `{ error: true, status: N }` is used instead.
+ */
+export const buildMockModeHooks = (config, bodyResolver) => {
+    if (config.enabled !== true)
+        return undefined;
+    const header = config.header ?? 'x-mock-status';
+    const healthPaths = new Set(config.healthPaths ?? []);
+    const isHealthPath = (p) => healthPaths.has(p);
+    const logger = config.logger ?? console;
+    const synthesize = (method, path, status) => {
+        const headers = { [header]: String(status) };
+        if (status === 204) {
+            return { status, empty: true, headers };
+        }
+        const body = bodyResolver?.(method, path, status) ?? {
+            error: true,
+            status,
+        };
+        return { status, json: body, headers };
+    };
+    const onRequest = (req) => {
+        if (isHealthPath(req.path))
+            return undefined;
+        // Header override (opt-in). The header name is the same one used
+        // to tag responses so a single curl flag flips both directions.
+        // 1xx (informational) responses are rejected: Node's HTTP layer
+        // treats them specially and a mock server has no use for them.
+        if (config.allowHeaderOverride === true) {
+            const raw = req.headers[header.toLowerCase()];
+            if (raw !== undefined) {
+                const n = Number.parseInt(raw, 10);
+                if (Number.isFinite(n) && n >= 200 && n < 600) {
+                    return synthesize(req.method, req.path, n);
+                }
+                // Out-of-range or non-numeric values were previously dropped on
+                // the floor, which made debugging "why doesn't my override
+                // work?" needlessly hard. Emit a single warn line so the typo
+                // is visible without escalating to a hard failure (which would
+                // break legitimate clients that ship the header for other
+                // reasons).
+                logger.warn(`@databehave/server/mock-mode: ignored ${header}=${JSON.stringify(raw)} ` +
+                    `(must be an integer in [200, 600))`);
+            }
+        }
+        const status = resolveStatus(req.method, req.path, config);
+        if (status === undefined)
+            return undefined;
+        return synthesize(req.method, req.path, status);
+    };
+    const onResponse = (req, res) => {
+        if (isHealthPath(req.path))
+            return res;
+        // Skip when the response (synthesised or handler-supplied) already
+        // carries the tag header. Header lookup is case-insensitive so
+        // `'X-Mock-Status'` from a handler is recognised against the
+        // configured (typically lowercase) `header` name.
+        if (res.headers) {
+            const wanted = header.toLowerCase();
+            for (const k of Object.keys(res.headers)) {
+                if (k.toLowerCase() === wanted)
+                    return res;
+            }
+        }
+        const tag = String(res.status ?? 200);
+        return {
+            ...res,
+            headers: { ...(res.headers ?? {}), [header]: tag },
+        };
+    };
+    return { onRequest, onResponse };
+};
+//# sourceMappingURL=mock-mode.js.map

package/dist/mock-mode.js.map

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

package/dist/openapi/auto-schema.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Auto-schema dispatch wiring (Phase 2C / brief item #11).
+ *
+ * When the JSONC config sets a top-level `schema:` field, this module:
+ *
+ *   1. Resolves the optional peer `@databehave/schema` via a single
+ *      `await import('@databehave/schema')` (string literal — never a
+ *      variable, never a helper). On `ERR_MODULE_NOT_FOUND` / similar
+ *      "Cannot find module" errors, the native error is suppressed
+ *      and replaced with the friendly multi-line install-hint
+ *      template (see `INSTALL_HINT`). Throws fail-fast at server
+ *      creation; never lazily on first request.
+ *   2. Pre-translates every OAS path/method (whose 200 / first 2xx
+ *      response carries a JSON schema) into a `@databehave/schema`
+ *      IR node via `translateOasToIR`. Translation errors throw at
+ *      server-creation time so OAS gaps surface fail-loud — same
+ *      philosophy as the validator and the OAS-only generator.
+ *   3. Synthesizes a per-route handler closing over the cached
+ *      schema module + IR. At request time the handler derives a
+ *      seed (per `config.schema.seed`), invokes `mock(ir, { seed })`,
+ *      and returns `{ json: ... }`.
+ *
+ * Hand-written `endpoints` always win — auto-mode only fills routes
+ * absent from the user's `endpoints` map. Genuine-separation
+ * invariant: this file MUST NOT statically value-import
+ * `@databehave/schema`. Type-only imports are erased at compile time
+ * and are fine.
+ */
+import type { Handler, RouteKey } from '../types.js';
+import type { OasDoc } from './walker.js';
+/** Fully-resolved schema-mode config (after JSONC validation). */
+export interface ResolvedSchemaConfig {
+    readonly seed: number | 'stable' | 'random';
+    readonly locale?: string;
+    readonly arrayCount?: number;
+}
+/**
+ * Friendly install-hint emitted when `config.schema.enabled === true`
+ * but the `@databehave/schema` peer is not installed. Verbatim from
+ * the brief — names the package, the field, the file, all three
+ * install commands, the README anchor, and the opt-out instruction.
+ */
+export declare const INSTALL_HINT: string;
+/**
+ * Validate the raw JSONC `schema:` value and normalise to the
+ * resolved shape. The value MUST be an object with an explicit
+ * `enabled: boolean`. The boolean shorthand (`schema: true` /
+ * `schema: false`) was removed — callers receive a migration
+ * error pointing at the new shape. Returns `null` when
+ * `enabled === false` so the caller can short-circuit auto-mode.
+ * Unknown keys throw with a message pointing at the offending key.
+ */
+export declare const normaliseSchemaConfig: (raw: unknown) => ResolvedSchemaConfig | null;
+/**
+ * Load the optional peer `@databehave/schema` package. On
+ * "Cannot find module" failures the native Node error is suppressed
+ * and replaced with the friendly install hint above. Other errors
+ * (e.g. broken install) re-throw verbatim — those are real bugs.
+ */
+export declare const loadSchemaModule: () => Promise<typeof import("@databehave/schema")>;
+/**
+ * FNV-1a 32-bit hash. Tiny, zero-dep, stable across machines —
+ * exactly what the per-request `seed: 'stable'` derivation needs.
+ *
+ * Input format: `${METHOD} ${endpointPath}|${sortedQuery}|${sortedPathParams}`,
+ * where sorted means lex-sorted keys joined by `&` as `key=value`.
+ *
+ * Example input  → output (uint32):
+ *   `GET /users/:id|page=2|id=42` → 0x9b1ed8c5
+ */
+export declare const hashSeed: (input: string) => number;
+/**
+ * Build a route-key → handler map for every OAS path/method whose
+ * response carries a usable JSON schema and is NOT already covered
+ * by hand-written `endpoints`. Each handler is closed over the
+ * cached schema module and pre-translated IR.
+ *
+ * `declaredKeys` is the set of route keys the user already declared
+ * via `endpoints`; auto-mode skips those so hand-written routes
+ * always win.
+ */
+export declare const buildAutoSchemaRoutes: (doc: OasDoc, cfg: ResolvedSchemaConfig, schemaModule: typeof import("@databehave/schema"), declaredKeys: ReadonlySet<RouteKey>) => Promise<Map<RouteKey, Handler>>;
+//# sourceMappingURL=auto-schema.d.ts.map

package/dist/openapi/auto-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-schema.d.ts","sourceRoot":"","sources":["../../src/openapi/auto-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,OAAO,EAAuB,QAAQ,EAAE,MAAM,aAAa,CAAA;AAGzE,OAAO,KAAK,EAAE,MAAM,EAAW,MAAM,aAAa,CAAA;AAElD,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAA;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAaD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,QAY6D,CAAA;AAEtF;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GAAI,KAAK,OAAO,KAAG,oBAAoB,GAAG,IA+D3E,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAa,OAAO,CAAC,cAAc,oBAAoB,CAAC,CAmBpF,CAAA;AAiBD;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,KAAG,MAOxC,CAAA;AA+CD;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,GAChC,KAAK,MAAM,EACX,KAAK,oBAAoB,EACzB,cAAc,cAAc,oBAAoB,CAAC,EACjD,cAAc,WAAW,CAAC,QAAQ,CAAC,KAClC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAgChC,CAAA"}