@schmock/openapi 1.2.1 → 1.7.0

package/dist/plugin.js

@@ -1,7 +1,11 @@
-/// <reference path="../../../types/schmock.d.ts" />
+/// <reference path="../../core/schmock.d.ts" />
+import { generateFromSchema } from "@schmock/faker";
+import Ajv from "ajv";
+import { negotiateContentType } from "./content-negotiation.js";
 import { detectCrudResources } from "./crud-detector.js";
-import { createCreateGenerator, createDeleteGenerator, createListGenerator, createReadGenerator, createStaticGenerator, createUpdateGenerator, } from "./generators.js";
+import { createCreateGenerator, createDeleteGenerator, createListGenerator, createReadGenerator, createStaticGenerator, createUpdateGenerator, findArrayProperty, } from "./generators.js";
 import { parseSpec } from "./parser.js";
+import { parsePreferHeader } from "./prefer.js";
 import { loadSeed } from "./seed.js";
 import { isRecord } from "./utils.js";
 /**
@@ -22,72 +26,439 @@ export async function openapi(options) {
     const seedData = options.seed
         ? loadSeed(options.seed, resources)
         : new Map();
+    // Build a lookup of all parsed paths for process() to reference
+    const allParsedPaths = new Map();
+    for (const pp of [...spec.paths]) {
+        allParsedPaths.set(`${pp.method} ${pp.path}`, pp);
+    }
+    // Security scheme lookup
+    const securitySchemes = spec.securitySchemes;
+    const globalSecurity = spec.globalSecurity;
     return {
         name: "@schmock/openapi",
-        version: "1.1.1",
+        version: "1.4.0",
         install(instance) {
-            // Seed initial state — we need state to be initialized before registering routes
-            // The state is populated via generator context.state on first request,
-            // but we need to pre-populate it. We'll use a global config state approach.
-            // Since generators use ctx.state (the global config state), we set up seed
-            // data through a setup route that runs on first access, or we just seed
-            // in the generators themselves.
-            // Register CRUD routes
+            if (options.debug) {
+                console.log(`[@schmock/openapi] Detected ${resources.length} CRUD resources, ${nonCrudPaths.length} static routes`);
+            }
+            // Register CRUD routes with metadata
             for (const resource of resources) {
-                registerCrudRoutes(instance, resource, seedData.get(resource.name));
+                const override = options.resources?.[resource.name];
+                if (override) {
+                    applyOverrides(resource, override);
+                }
+                if (options.debug) {
+                    logResourceDetection(resource, override);
+                }
+                registerCrudRoutes(instance, resource, seedData.get(resource.name), allParsedPaths);
             }
             // Register non-CRUD routes with static generators
             for (const parsedPath of nonCrudPaths) {
                 const routeKey = `${parsedPath.method} ${parsedPath.path}`;
-                instance(routeKey, createStaticGenerator(parsedPath));
+                const config = {
+                    "openapi:responses": parsedPath.responses,
+                    "openapi:path": parsedPath.path,
+                    "openapi:requestBody": parsedPath.requestBody,
+                    "openapi:security": parsedPath.security,
+                    "openapi:callbacks": parsedPath.callbacks,
+                };
+                instance(routeKey, createStaticGenerator(parsedPath, options.fakerSeed), config);
             }
         },
         process(context, response) {
-            // Pass through — generators handle everything
-            return { context, response };
+            // 1. Security validation (if enabled)
+            if (options.security && securitySchemes) {
+                const securityResult = validateSecurity(context, securitySchemes, globalSecurity);
+                if (securityResult)
+                    return securityResult;
+            }
+            // 2. Content negotiation
+            const contentResult = processContentNegotiation(context);
+            if (contentResult)
+                return contentResult;
+            // 3. Request validation (if enabled)
+            if (options.validateRequests) {
+                const validationResult = validateRequestBody(context);
+                if (validationResult) {
+                    return validationResult;
+                }
+            }
+            // 4. Prefer header handling
+            const result = processPreferHeader(context, response, options.fakerSeed);
+            // 5. Fire callbacks (fire-and-forget, after response is determined)
+            const callbacks = context.route["openapi:callbacks"];
+            if (callbacks && callbacks.length > 0) {
+                fireCallbacks(callbacks, context, result.response);
+            }
+            return result;
         },
     };
 }
-function registerCrudRoutes(instance, resource, seedItems) {
-    // Create a seeded generator wrapper that initializes state on first call
-    const ensureSeeded = createSeeder(resource, seedItems);
-    for (const op of resource.operations) {
-        switch (op) {
-            case "list": {
-                const gen = createListGenerator(resource);
-                const routeKey = `GET ${resource.basePath}`;
-                instance(routeKey, wrapWithSeeder(ensureSeeded, gen));
-                break;
+/**
+ * Validate security requirements for the request.
+ * Returns 401 if auth is required and missing/invalid.
+ */
+function validateSecurity(context, schemes, globalSecurity) {
+    // Determine applicable security: operation-level overrides global
+    const routeSecurity = context.route["openapi:security"];
+    const security = routeSecurity ?? globalSecurity;
+    // No security requirements
+    if (!security || security.length === 0)
+        return undefined;
+    // Check each OR group — if any group passes, request is authorized
+    for (const group of security) {
+        // Empty group = public endpoint (security: [{}])
+        if (group.length === 0)
+            return undefined;
+        // All schemes in the group must pass (AND)
+        const allPass = group.every((schemeName) => {
+            const scheme = schemes.get(schemeName);
+            if (!scheme)
+                return false;
+            return checkSchemePresence(scheme, context.headers);
+        });
+        if (allPass)
+            return undefined;
+    }
+    // No group passed — build WWW-Authenticate header
+    const wwwAuth = buildWwwAuthenticate(security, schemes);
+    const headers = {};
+    if (wwwAuth) {
+        headers["www-authenticate"] = wwwAuth;
+    }
+    return {
+        context,
+        response: [
+            401,
+            {
+                error: "Unauthorized",
+                code: "UNAUTHORIZED",
+            },
+            headers,
+        ],
+    };
+}
+function checkSchemePresence(scheme, headers) {
+    if (scheme.type === "http") {
+        const auth = headers.authorization ?? headers.Authorization ?? "";
+        if (scheme.scheme === "bearer") {
+            return auth.toLowerCase().startsWith("bearer ");
+        }
+        if (scheme.scheme === "basic") {
+            return auth.toLowerCase().startsWith("basic ");
+        }
+        // Other http schemes — just check authorization exists
+        return auth.length > 0;
+    }
+    if (scheme.type === "apiKey") {
+        if (scheme.in === "header" && scheme.name) {
+            const headerName = scheme.name.toLowerCase();
+            return (headers[headerName] ?? headers[scheme.name] ?? "") !== "";
+        }
+        // query and cookie api keys can't be checked from headers alone
+        // For simplicity, pass through (they'd need query/cookie context)
+        return true;
+    }
+    // oauth2 / openIdConnect — just check for bearer token
+    if (scheme.type === "oauth2" || scheme.type === "openIdConnect") {
+        const auth = headers.authorization ?? headers.Authorization ?? "";
+        return auth.toLowerCase().startsWith("bearer ");
+    }
+    return true;
+}
+function buildWwwAuthenticate(security, schemes) {
+    const challenges = [];
+    for (const group of security) {
+        for (const schemeName of group) {
+            const scheme = schemes.get(schemeName);
+            if (!scheme)
+                continue;
+            if (scheme.type === "http" && scheme.scheme === "bearer") {
+                if (!challenges.includes("Bearer"))
+                    challenges.push("Bearer");
             }
-            case "create": {
-                const gen = createCreateGenerator(resource);
-                const routeKey = `POST ${resource.basePath}`;
-                instance(routeKey, wrapWithSeeder(ensureSeeded, gen));
-                break;
+            else if (scheme.type === "http" && scheme.scheme === "basic") {
+                if (!challenges.includes("Basic"))
+                    challenges.push("Basic");
             }
-            case "read": {
-                const gen = createReadGenerator(resource);
-                const routeKey = `GET ${resource.itemPath}`;
-                instance(routeKey, wrapWithSeeder(ensureSeeded, gen));
-                break;
+            else if (scheme.type === "oauth2" || scheme.type === "openIdConnect") {
+                if (!challenges.includes("Bearer"))
+                    challenges.push("Bearer");
             }
-            case "update": {
-                const gen = createUpdateGenerator(resource);
-                const putKey = `PUT ${resource.itemPath}`;
-                const patchKey = `PATCH ${resource.itemPath}`;
-                instance(putKey, wrapWithSeeder(ensureSeeded, gen));
-                instance(patchKey, wrapWithSeeder(ensureSeeded, gen));
-                break;
+        }
+    }
+    return challenges.join(", ");
+}
+/**
+ * Check Accept header against available content types. Returns 406 if no match.
+ */
+function processContentNegotiation(context) {
+    const accept = context.headers.accept ?? context.headers.Accept;
+    if (!accept || accept === "*/*")
+        return undefined;
+    const responses = context.route["openapi:responses"];
+    if (!responses)
+        return undefined;
+    // Collect all available content types across responses
+    const allContentTypes = new Set();
+    for (const entry of responses.values()) {
+        if (entry.contentTypes) {
+            for (const ct of entry.contentTypes) {
+                allContentTypes.add(ct);
             }
-            case "delete": {
-                const gen = createDeleteGenerator(resource);
-                const routeKey = `DELETE ${resource.itemPath}`;
-                instance(routeKey, wrapWithSeeder(ensureSeeded, gen));
-                break;
+        }
+    }
+    // No content types defined in spec → skip negotiation
+    if (allContentTypes.size === 0)
+        return undefined;
+    const matched = negotiateContentType(accept, [...allContentTypes]);
+    if (!matched) {
+        return {
+            context,
+            response: [
+                406,
+                {
+                    error: "Not Acceptable",
+                    code: "NOT_ACCEPTABLE",
+                    acceptable: [...allContentTypes],
+                },
+            ],
+        };
+    }
+    return undefined;
+}
+/**
+ * Handle Prefer header directives: code=N, example=name, dynamic=true
+ */
+function processPreferHeader(context, response, fakerSeed) {
+    const preferValue = context.headers.prefer ?? context.headers.Prefer;
+    if (!preferValue) {
+        return { context, response };
+    }
+    const prefer = parsePreferHeader(preferValue);
+    const responses = context.route["openapi:responses"];
+    if (!responses) {
+        return { context, response };
+    }
+    // Prefer: code=N — return the response for that status code
+    if (prefer.code !== undefined) {
+        const entry = responses.get(prefer.code);
+        if (entry) {
+            const body = entry.schema
+                ? generateResponseBody(entry.schema, fakerSeed)
+                : {};
+            return { context, response: [prefer.code, body] };
+        }
+    }
+    // Prefer: example=name — find a named example across responses
+    if (prefer.example !== undefined) {
+        for (const [code, entry] of responses) {
+            if (entry.examples?.has(prefer.example)) {
+                return {
+                    context,
+                    response: [code, entry.examples.get(prefer.example)],
+                };
+            }
+        }
+    }
+    // Prefer: dynamic=true — regenerate from schema
+    if (prefer.dynamic) {
+        for (const [code, entry] of responses) {
+            if (code >= 200 && code < 300 && entry.schema) {
+                const body = generateResponseBody(entry.schema, fakerSeed);
+                return { context, response: [code, body] };
+            }
+        }
+    }
+    return { context, response };
+}
+const ajv = new Ajv({ allErrors: true });
+/**
+ * Validate request body against the spec's requestBody schema.
+ * Returns a PluginResult with 400 status if validation fails, or undefined to continue.
+ */
+function validateRequestBody(context) {
+    const requestBodySchema = context.route["openapi:requestBody"];
+    if (!requestBodySchema || context.body === undefined) {
+        return undefined;
+    }
+    const validate = ajv.compile(requestBodySchema);
+    if (!validate(context.body)) {
+        const errors = validate.errors?.map((e) => ({
+            path: e.instancePath || "/",
+            message: e.message ?? "validation failed",
+            keyword: e.keyword,
+        })) ?? [];
+        return {
+            context,
+            response: [
+                400,
+                {
+                    error: "Request validation failed",
+                    code: "VALIDATION_ERROR",
+                    details: errors,
+                },
+            ],
+        };
+    }
+    return undefined;
+}
+/**
+ * Resolve a callback URL expression using runtime values.
+ * Handles expressions like "{$request.body#/callbackUrl}" and literal URLs.
+ */
+function resolveCallbackUrl(expression, context, response) {
+    // Replace all runtime expression tokens
+    return expression.replace(/\{\$([^}]+)\}/g, (_, expr) => {
+        // $request.body#/path — JSON pointer into request body
+        if (expr.startsWith("request.body#")) {
+            const pointer = expr.slice("request.body#".length);
+            const value = resolveJsonPointer(context.body, pointer);
+            return typeof value === "string" ? value : "";
+        }
+        // $request.header.name
+        if (expr.startsWith("request.header.")) {
+            const headerName = expr.slice("request.header.".length).toLowerCase();
+            return context.headers[headerName] ?? "";
+        }
+        // $request.query.name
+        if (expr.startsWith("request.query.")) {
+            const queryName = expr.slice("request.query.".length);
+            return context.query[queryName] ?? "";
+        }
+        // $request.path.param
+        if (expr.startsWith("request.path.")) {
+            const paramName = expr.slice("request.path.".length);
+            return context.params[paramName] ?? "";
+        }
+        // $response.body#/path — JSON pointer into response body
+        if (expr.startsWith("response.body#")) {
+            const pointer = expr.slice("response.body#".length);
+            const responseBody = Array.isArray(response) ? response[1] : response;
+            const value = resolveJsonPointer(responseBody, pointer);
+            return typeof value === "string" ? value : "";
+        }
+        return "";
+    });
+}
+function resolveJsonPointer(obj, pointer) {
+    if (!isRecord(obj) || !pointer.startsWith("/"))
+        return undefined;
+    const parts = pointer.slice(1).split("/");
+    let current = obj;
+    for (const part of parts) {
+        if (!isRecord(current))
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Fire callbacks in a fire-and-forget manner.
+ * Silently ignores failures — callbacks are best-effort.
+ */
+function fireCallbacks(callbacks, context, response) {
+    for (const callback of callbacks) {
+        const url = resolveCallbackUrl(callback.urlExpression, context, response);
+        if (!url || !url.startsWith("http"))
+            continue;
+        const body = Array.isArray(response) ? response[1] : response;
+        // Fire and forget
+        void fetch(url, {
+            method: callback.method,
+            headers: { "content-type": "application/json" },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        }).catch(() => {
+            // Silently ignore callback failures
+        });
+    }
+}
+function generateResponseBody(schema, seed) {
+    try {
+        return generateFromSchema({ schema, seed });
+    }
+    catch {
+        return {};
+    }
+}
+function registerCrudRoutes(instance, resource, seedItems, allParsedPaths) {
+    const ensureSeeded = createSeeder(resource, seedItems);
+    for (const op of resource.operations) {
+        const meta = resource.operationMeta?.get(op);
+        const routeEntries = getCrudRouteEntries(op, resource);
+        for (const { routeKey, method } of routeEntries) {
+            const gen = createCrudGenerator(op, resource, meta);
+            const parsedPath = allParsedPaths.get(`${method} ${resource.basePath}`) ??
+                allParsedPaths.get(`${method} ${resource.itemPath}`);
+            const config = {};
+            if (parsedPath) {
+                config["openapi:responses"] = parsedPath.responses;
+                config["openapi:path"] = parsedPath.path;
+                config["openapi:requestBody"] = parsedPath.requestBody;
+                config["openapi:security"] = parsedPath.security;
+                config["openapi:callbacks"] = parsedPath.callbacks;
             }
+            instance(routeKey, wrapWithSeeder(ensureSeeded, gen), config);
         }
     }
 }
+function getCrudRouteEntries(op, resource) {
+    switch (op) {
+        case "list":
+            return [
+                {
+                    routeKey: `GET ${resource.basePath}`,
+                    method: "GET",
+                },
+            ];
+        case "create":
+            return [
+                {
+                    routeKey: `POST ${resource.basePath}`,
+                    method: "POST",
+                },
+            ];
+        case "read":
+            return [
+                {
+                    routeKey: `GET ${resource.itemPath}`,
+                    method: "GET",
+                },
+            ];
+        case "update":
+            return [
+                {
+                    routeKey: `PUT ${resource.itemPath}`,
+                    method: "PUT",
+                },
+                {
+                    routeKey: `PATCH ${resource.itemPath}`,
+                    method: "PATCH",
+                },
+            ];
+        case "delete":
+            return [
+                {
+                    routeKey: `DELETE ${resource.itemPath}`,
+                    method: "DELETE",
+                },
+            ];
+    }
+}
+function createCrudGenerator(op, resource, meta) {
+    switch (op) {
+        case "list":
+            return createListGenerator(resource, meta);
+        case "create":
+            return createCreateGenerator(resource, meta);
+        case "read":
+            return createReadGenerator(resource, meta);
+        case "update":
+            return createUpdateGenerator(resource, meta);
+        case "delete":
+            return createDeleteGenerator(resource, meta);
+    }
+}
 /**
  * Create a seeder function that initializes collection state once.
  */
@@ -101,7 +472,6 @@ function createSeeder(resource, seedItems) {
         state[seededKey] = true;
         if (seedItems && seedItems.length > 0) {
             state[stateKey] = [...seedItems];
-            // Set counter to highest existing ID
             let maxId = 0;
             for (const item of seedItems) {
                 if (isRecord(item) && resource.idParam in item) {
@@ -125,3 +495,92 @@ function wrapWithSeeder(seeder, generator) {
         return generator(ctx);
     };
 }
+/**
+ * Apply manual overrides to a resource's operation metadata.
+ */
+function applyOverrides(resource, override) {
+    if (!resource.operationMeta) {
+        resource.operationMeta = new Map();
+    }
+    if (override.listWrapProperty !== undefined ||
+        override.listFlat !== undefined) {
+        const listMeta = resource.operationMeta.get("list") ?? {};
+        if (override.listFlat) {
+            delete listMeta.responseSchema;
+        }
+        else if (override.listWrapProperty && listMeta.responseSchema) {
+            const arrayInfo = findArrayProperty(listMeta.responseSchema);
+            if (!arrayInfo.property ||
+                arrayInfo.property !== override.listWrapProperty) {
+                const itemSchema = arrayInfo.itemSchema ?? resource.schema ?? {};
+                listMeta.responseSchema = {
+                    type: "object",
+                    properties: {
+                        [override.listWrapProperty]: {
+                            type: "array",
+                            items: itemSchema,
+                        },
+                    },
+                };
+            }
+        }
+        else if (override.listWrapProperty) {
+            const itemSchema = resource.schema ?? {};
+            listMeta.responseSchema = {
+                type: "object",
+                properties: {
+                    [override.listWrapProperty]: {
+                        type: "array",
+                        items: itemSchema,
+                    },
+                },
+            };
+        }
+        resource.operationMeta.set("list", listMeta);
+    }
+    if (override.errorSchema) {
+        const errorSchemaMap = new Map();
+        errorSchemaMap.set(404, override.errorSchema);
+        errorSchemaMap.set(400, override.errorSchema);
+        errorSchemaMap.set(409, override.errorSchema);
+        for (const op of ["read", "update", "delete"]) {
+            const meta = resource.operationMeta.get(op) ?? {};
+            meta.errorSchemas = errorSchemaMap;
+            resource.operationMeta.set(op, meta);
+        }
+    }
+}
+/**
+ * Log resource detection info for debug mode.
+ */
+function logResourceDetection(resource, override) {
+    const listMeta = resource.operationMeta?.get("list");
+    let listFormat = "flat";
+    if (listMeta?.responseSchema) {
+        const arrayInfo = findArrayProperty(listMeta.responseSchema);
+        if (arrayInfo.property) {
+            const hasAllOf = "allOf" in (listMeta.responseSchema ?? {});
+            listFormat = `wrapped("${arrayInfo.property}"${hasAllOf ? " via allOf" : ""})`;
+        }
+    }
+    const readMeta = resource.operationMeta?.get("read");
+    const errorFormat = readMeta?.errorSchemas?.has(404)
+        ? "schema(404)"
+        : "default";
+    const headerCount = listMeta?.responseHeaders
+        ? Object.keys(listMeta.responseHeaders).length
+        : 0;
+    console.log(`[@schmock/openapi] ${resource.name}: list=${listFormat}, error=${errorFormat}, headers=${headerCount}`);
+    if (override) {
+        const definedKeys = [];
+        if (override.listWrapProperty !== undefined)
+            definedKeys.push("listWrapProperty");
+        if (override.listFlat !== undefined)
+            definedKeys.push("listFlat");
+        if (override.errorSchema !== undefined)
+            definedKeys.push("errorSchema");
+        if (definedKeys.length > 0) {
+            console.log(`[@schmock/openapi] Override applied: ${resource.name}.${definedKeys.join(", ")}`);
+        }
+    }
+}

package/dist/prefer.d.ts

@@ -0,0 +1,12 @@
+interface PreferDirectives {
+    code?: number;
+    example?: string;
+    dynamic?: boolean;
+}
+/**
+ * Parse the RFC 7240 Prefer header for mock-specific directives.
+ * Supports: code=N, example=name, dynamic=true
+ */
+export declare function parsePreferHeader(value: string): PreferDirectives;
+export {};
+//# sourceMappingURL=prefer.d.ts.map

package/dist/prefer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefer.d.ts","sourceRoot":"","sources":["../src/prefer.ts"],"names":[],"mappings":"AAEA,UAAU,gBAAgB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAwBjE"}

package/dist/prefer.js

@@ -0,0 +1,25 @@
+/// <reference path="../../core/schmock.d.ts" />
+/**
+ * Parse the RFC 7240 Prefer header for mock-specific directives.
+ * Supports: code=N, example=name, dynamic=true
+ */
+export function parsePreferHeader(value) {
+    const result = {};
+    for (const part of value.split(",")) {
+        const trimmed = part.trim();
+        const codeMatch = trimmed.match(/^code\s*=\s*(\d+)$/);
+        if (codeMatch) {
+            result.code = Number(codeMatch[1]);
+            continue;
+        }
+        const exampleMatch = trimmed.match(/^example\s*=\s*(.+)$/);
+        if (exampleMatch) {
+            result.example = exampleMatch[1].trim();
+            continue;
+        }
+        if (trimmed === "dynamic=true" || trimmed === "dynamic") {
+            result.dynamic = true;
+        }
+    }
+    return result;
+}

package/dist/seed.js

@@ -1,4 +1,4 @@
-/// <reference path="../../../types/schmock.d.ts" />
+/// <reference path="../../core/schmock.d.ts" />
 import { readFileSync } from "node:fs";
 import { generateSeedItems } from "./generators.js";
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@schmock/openapi",
   "description": "OpenAPI/Swagger spec-driven auto-registration plugin for Schmock",
-  "version": "1.2.1",
+  "version": "1.7.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -25,15 +25,17 @@
     "test:watch": "vitest --watch",
     "test:bdd": "vitest run --config vitest.config.bdd.ts",
     "lint": "biome check src/*.ts",
-    "lint:fix": "biome check --write --unsafe src/*.ts"
+    "lint:fix": "biome check --write --unsafe src/*.ts",
+    "check:publish": "publint && attw --pack --ignore-rules cjs-resolves-to-esm"
   },
   "license": "MIT",
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.0.0",
-    "@schmock/schema": "^1.3.0"
+    "@schmock/faker": "^1.7.0",
+    "ajv": "^8.17.1"
   },
   "peerDependencies": {
-    "@schmock/core": "^1.0.0"
+    "@schmock/core": "^1.7.0"
   },
   "devDependencies": {
     "@amiceli/vitest-cucumber": "^6.2.0",