@codewithagents/openapi-server 1.9.0 → 1.10.0

package/dist/plugins/router.js

@@ -1,4 +1,4 @@
-import { SUPPORTED_METHODS, isRef, extractPathParamsFromPath, resolveParam, deriveServiceName, deriveMethodName, getQueryParams, getBodyInfo, } from './shared.js';
+import { SUPPORTED_METHODS, isRef, refToName, extractPathParamsFromPath, resolveParam, deriveServiceName, deriveMethodName, getQueryParams, getBodyInfo, } from './shared.js';
 /** Convert OpenAPI path to Hono path: {id} -> :id */
 function toHonoPath(openapiPath) {
     return openapiPath.replace(/\{([^}]+)\}/g, ':$1');
@@ -83,9 +83,11 @@ function queryParamDeepObjectZodBase(param) {
     });
     return `z.object({ ${propFields.join(', ')} })`;
 }
-/** Number/integer param: z.number() with optional range modifiers. */
+/** Number/integer param: z.coerce.number() with optional range modifiers.
+ * Uses coerce so that Fastify's raw string values (fast-querystring never converts types)
+ * are accepted alongside the already-coerced numbers from Express/Hono extraction. */
 function queryParamNumberZodBase(param) {
-    let base = 'z.number()';
+    let base = 'z.coerce.number()';
     if (param.minimum !== undefined)
         base += `.min(${param.minimum})`;
     if (param.maximum !== undefined)
@@ -191,6 +193,28 @@ function getPathParamValidations(operation, spec, rawPathParamNames) {
     }
     return result;
 }
+/**
+ * Build a Zod expression for a cookie parameter based on its captured constraints.
+ * Cookie values are always strings; emits z.string() or z.enum([...]) with optional
+ * pattern/length modifiers. Appends .optional() for non-required params.
+ */
+function cookieParamZodExpr(param) {
+    let base;
+    if (param.enum !== undefined && param.enum.length > 0) {
+        const members = param.enum.map((v) => JSON.stringify(v)).join(', ');
+        base = `z.enum([${members}])`;
+    }
+    else {
+        base = 'z.string()';
+    }
+    if (param.minLength !== undefined)
+        base += `.min(${param.minLength})`;
+    if (param.maxLength !== undefined)
+        base += `.max(${param.maxLength})`;
+    if (param.pattern !== undefined)
+        base += `.regex(/${param.pattern}/)`;
+    return param.required ? base : `${base}.optional()`;
+}
 /**
  * Collect header parameters from an operation, including schema constraints.
  */
@@ -223,6 +247,39 @@ function getHeaderParams(operation, spec) {
     }
     return result;
 }
+/**
+ * Collect cookie parameters (in: cookie) from an operation, including schema constraints.
+ * Cookie names are case-sensitive and are used as-is for both the Zod field key and value lookup.
+ */
+function getCookieParams(operation, spec) {
+    const parameters = operation.parameters;
+    if (parameters === undefined)
+        return [];
+    const result = [];
+    for (const p of parameters) {
+        const resolved = resolveParam(p, spec);
+        if (resolved === undefined || resolved.in !== 'cookie')
+            continue;
+        const param = {
+            rawName: resolved.name,
+            required: resolved.required === true,
+        };
+        const schema = resolved.schema;
+        if (schema !== undefined && !isRef(schema)) {
+            const s = schema;
+            if (Array.isArray(s.enum))
+                param.enum = s.enum;
+            if (typeof s.minLength === 'number')
+                param.minLength = s.minLength;
+            if (typeof s.maxLength === 'number')
+                param.maxLength = s.maxLength;
+            if (typeof s.pattern === 'string')
+                param.pattern = s.pattern;
+        }
+        result.push(param);
+    }
+    return result;
+}
 /**
  * Returns true when a query param carries schema constraints beyond basic type/required.
  * These constraints require a Zod validation block even if the param is optional or string.
@@ -301,7 +358,9 @@ function emitPathValidation(lines, validations, indent, framework) {
             access = `c.req.param(${JSON.stringify(v.rawName)})`;
         }
         else if (framework === 'express') {
-            access = `req.params[${JSON.stringify(v.rawName)}]`;
+            // Cast to string: Express 5 types req.params values as string | string[],
+            // but path params are always single strings in practice.
+            access = `req.params[${JSON.stringify(v.rawName)}] as string`;
         }
         else {
             access = /[^a-zA-Z0-9_$]/.test(v.rawName)
@@ -337,15 +396,16 @@ function emitHeaderValidation(lines, headerParams, indent, framework) {
     const rawFields = headerParams
         .map((h) => {
         const key = JSON.stringify(h.rawName);
+        const lookupKey = JSON.stringify(h.rawName.toLowerCase());
         let access;
         if (framework === 'hono') {
             access = `c.req.header(${key})`;
         }
         else if (framework === 'express') {
-            access = `req.headers[${key}] as string | undefined`;
+            access = `req.headers[${lookupKey}] as string | undefined`;
         }
         else {
-            access = `req.headers[${key}]`;
+            access = `req.headers[${lookupKey}]`;
         }
         return `${fieldIndent}${key}: ${access}`;
     })
@@ -357,6 +417,56 @@ function emitHeaderValidation(lines, headerParams, indent, framework) {
     lines.push(rawFields);
     lines.push(`${inner}})`);
 }
+/**
+ * Emit Zod validation lines for cookie parameters into the handler line buffer.
+ * Cookie names are case-sensitive: the exact name is used for both the Zod field key and
+ * the value lookup (unlike headers, which are lowercased for lookup on Express/Fastify).
+ *
+ * Required plugins per framework:
+ *   Fastify: register @fastify/cookie before creating the router.
+ *   Express: apply cookie-parser middleware before mounting this router.
+ *   Hono:    getCookie is imported from 'hono/cookie' (added to generated output automatically).
+ *
+ * Uses short variable name _ckv to keep the 422 return line under Prettier's print width.
+ * @param indent - outer handler indent (e.g. '  ')
+ * @param framework - used to generate the correct cookie accessor syntax
+ */
+function emitCookieValidation(lines, cookieParams, indent, framework) {
+    const inner = `${indent}  `;
+    const fieldIndent = `${indent}    `;
+    const schemaFields = cookieParams
+        .map((ck) => {
+        const key = JSON.stringify(ck.rawName);
+        const expr = cookieParamZodExpr(ck);
+        return `${fieldIndent}${key}: ${expr}`;
+    })
+        .join(',\n');
+    const rawFields = cookieParams
+        .map((ck) => {
+        const key = JSON.stringify(ck.rawName);
+        let access;
+        if (framework === 'hono') {
+            // getCookie is imported from 'hono/cookie' when cookie params are present.
+            access = `getCookie(c, ${key})`;
+        }
+        else if (framework === 'express') {
+            // Requires cookie-parser middleware: req.cookies['name']
+            access = `req.cookies[${key}] as string | undefined`;
+        }
+        else {
+            // Requires @fastify/cookie plugin: req.cookies['name']
+            access = `req.cookies[${key}]`;
+        }
+        return `${fieldIndent}${key}: ${access}`;
+    })
+        .join(',\n');
+    lines.push(`${inner}// Validate request cookies: returns 422 with Zod issues on failure`);
+    lines.push(`${inner}const _ckv = z.object({`);
+    lines.push(schemaFields);
+    lines.push(`${inner}}).safeParse({`);
+    lines.push(rawFields);
+    lines.push(`${inner}})`);
+}
 function response200IsVoid(resp) {
     if (isRef(resp))
         return false;
@@ -443,6 +553,44 @@ function getResponseStatus(operation, httpMethod) {
         ? { status: 204, isVoid: true, responseContentType: 'application/json' }
         : { status: 200, isVoid: false, responseContentType: 'application/json' };
 }
+/**
+ * Resolve the response type name and shape for Fastify schema.response wiring.
+ * Returns the PascalCase type name of the first JSON 2xx response if it is a
+ * direct $ref or an array-of-$ref. Returns undefined for inline schemas, void,
+ * text/plain, or octet-stream responses.
+ *
+ * Priority order mirrors service.ts getReturnInfo: 200, 201, then other 2xx codes.
+ */
+function getResponseTypeName(operation) {
+    const responses = operation.responses;
+    if (responses === undefined)
+        return undefined;
+    const priority = ['200', '201', ...Object.keys(responses).filter((k) => /^2\d\d$/.test(k) && k !== '200' && k !== '201' && k !== '204')];
+    for (const code of priority) {
+        const response = responses[code];
+        if (response === undefined || isRef(response))
+            continue;
+        const resp = response;
+        const content = resp.content;
+        if (content === undefined)
+            continue;
+        const jsonContent = content['application/json'];
+        if (jsonContent === undefined || jsonContent.schema === undefined)
+            continue;
+        const schema = jsonContent.schema;
+        if (isRef(schema)) {
+            return { typeName: refToName(schema.$ref), isArray: false };
+        }
+        const s = schema;
+        if (s.type === 'array' && s.items !== undefined && isRef(s.items)) {
+            return {
+                typeName: refToName(s.items.$ref),
+                isArray: true,
+            };
+        }
+    }
+    return undefined;
+}
 function collectOperations(spec) {
     const paths = spec.paths;
     if (paths === undefined)
@@ -458,8 +606,10 @@ function collectOperations(spec) {
             const pathParamValidations = getPathParamValidations(operation, spec, pathParams);
             const queryParams = getQueryParams(operation, spec);
             const headerParams = getHeaderParams(operation, spec);
+            const cookieParams = getCookieParams(operation, spec);
             const bodyInfo = getBodyInfo(operation);
             const responseStatus = getResponseStatus(operation, method);
+            const responseTypeInfo = getResponseTypeName(operation);
             operations.push({
                 methodName,
                 httpMethod: method,
@@ -469,8 +619,11 @@ function collectOperations(spec) {
                 pathParamValidations,
                 queryParams,
                 headerParams,
+                cookieParams,
                 bodyInfo,
                 responseStatus,
+                responseTypeName: responseTypeInfo?.typeName,
+                responseIsArray: responseTypeInfo?.isArray,
             });
         }
     }
@@ -502,6 +655,26 @@ function collectUsedSchemaNames(operations, schemaNames) {
     }
     return used;
 }
+/**
+ * Collect the subset of schemaNames used as Fastify response schemas.
+ * Only operations with a resolvable $ref response type (direct or array-of-$ref)
+ * and a matching schema in schemaNames are included.
+ * Multi-status operations are excluded because they cannot be mapped to a single
+ * status code in schema.response at generation time.
+ */
+function collectUsedResponseSchemaNames(operations, schemaNames) {
+    const used = new Set();
+    for (const op of operations) {
+        if (op.responseTypeName === undefined)
+            continue;
+        if (op.responseStatus.isMultiStatus === true)
+            continue;
+        const schemaName = `${op.responseTypeName}Schema`;
+        if (schemaNames.has(schemaName))
+            used.add(schemaName);
+    }
+    return used;
+}
 /**
  * Collect body type names, used schema names, and whether Zod is needed.
  * Shared by all three generator functions to avoid duplication.
@@ -511,13 +684,23 @@ function collectGeneratorSetup(operations, options) {
     const usedSchemaNames = options?.schemaNames !== undefined
         ? collectUsedSchemaNames(operations, options.schemaNames)
         : new Set();
+    const usedResponseSchemaNames = options?.schemaNames !== undefined
+        ? collectUsedResponseSchemaNames(operations, options.schemaNames)
+        : new Set();
+    // Zod is needed for param validation, body schema validation, or array response schemas.
+    // Array response schemas emit z.array(XSchema) which requires the z import.
+    const hasArrayResponseSchema = usedResponseSchemaNames.size > 0 &&
+        operations.some((op) => op.responseIsArray === true &&
+            op.responseTypeName !== undefined &&
+            usedResponseSchemaNames.has(`${op.responseTypeName}Schema`));
     const needsZod = (usedSchemaNames.size > 0 && options?.schemaImportPath !== undefined) ||
-        operationsNeedZodForParams(operations);
-    return { sortedBodyTypes, usedSchemaNames, needsZod };
+        operationsNeedZodForParams(operations) ||
+        (usedResponseSchemaNames.size > 0 && options?.schemaImportPath !== undefined && hasArrayResponseSchema);
+    return { sortedBodyTypes, usedSchemaNames, usedResponseSchemaNames, needsZod };
 }
 // ── Hono route handler ────────────────────────────────────────────────────────
 // fallow-ignore-next-line complexity
-function buildRouteHandler(op, indent, schemaNames) {
+function buildRouteHandler(op, indent, schemaNames, contextType) {
     const lines = [];
     lines.push(`${indent}app.${op.httpMethod}(${JSON.stringify(op.honoPath)}, async (c) => {`);
     // Path param format validation (e.g. uuid)
@@ -577,6 +760,14 @@ function buildRouteHandler(op, indent, schemaNames) {
         lines.push(`${indent}    return c.json({ error: 'Invalid request headers', issues: _hv.error.issues }, 422)`);
         lines.push(`${indent}  }`);
     }
+    // Cookie param validation
+    // Requires @fastify/cookie on Fastify, cookie-parser on Express, getCookie from hono/cookie on Hono.
+    if (op.cookieParams.length > 0) {
+        emitCookieValidation(lines, op.cookieParams, indent, 'hono');
+        lines.push(`${indent}  if (!_ckv.success) {`);
+        lines.push(`${indent}    return c.json({ error: 'Invalid request cookies', issues: _ckv.error.issues }, 422)`);
+        lines.push(`${indent}  }`);
+    }
     // Body extraction
     let bodyVarName = 'body';
     if (op.bodyInfo !== undefined) {
@@ -625,7 +816,12 @@ function buildRouteHandler(op, indent, schemaNames) {
             lines.push(`${indent}  if (!parseResult.success) {`);
             lines.push(`${indent}    return c.json({ error: 'Invalid request body', issues: parseResult.error.issues }, 422)`);
             lines.push(`${indent}  }`);
-            lines.push(`${indent}  const validatedBody = parseResult.data`);
+            // Forward the validated/coerced data (parseResult.data), NOT the raw parsed body,
+            // so Zod coercion is preserved (e.g. form-urlencoded numeric fields via
+            // z.coerce.number()). Cast to the declared model type so the service-call type
+            // stays correct even when the schema infers a narrower shape (e.g. z.unknown()
+            // for inline-union properties); safeParse above guarantees runtime safety.
+            lines.push(`${indent}  const validatedBody = parseResult.data as ${typeDecl}`);
             bodyVarName = 'validatedBody';
         }
     }
@@ -638,7 +834,15 @@ function buildRouteHandler(op, indent, schemaNames) {
         serviceArgs.push(bodyVarName);
     }
     if (op.queryParams.length > 0) {
-        serviceArgs.push('params');
+        // After successful Zod validation _qv.data carries the correct required/typed
+        // values (e.g. string[] for delimited arrays, object shape for deepObject params,
+        // and non-optional values for required scalar params). Use _qv.data when validation
+        // was applied; fall back to params when no validation is needed.
+        serviceArgs.push(queryParamsNeedValidation(op.queryParams) ? '_qv.data' : 'params');
+    }
+    // Context arg: pass the Hono Context object (c) as the final argument when contextType is set.
+    if (contextType !== undefined) {
+        serviceArgs.push('c');
     }
     const serviceCall = `service.${op.methodName}(${serviceArgs.join(', ')})`;
     // Response — wrap in try/catch to map HttpError to its status
@@ -687,7 +891,7 @@ function buildRouteHandler(op, indent, schemaNames) {
 }
 // ── Express route handler ─────────────────────────────────────────────────────
 // fallow-ignore-next-line complexity
-function buildExpressRouteHandler(op, indent, schemaNames) {
+function buildExpressRouteHandler(op, indent, schemaNames, contextType) {
     const lines = [];
     lines.push(`${indent}router.${op.httpMethod}(${JSON.stringify(op.honoPath)}, async (req: Request, res: Response) => {`);
     // Path param format validation (e.g. uuid)
@@ -739,6 +943,14 @@ function buildExpressRouteHandler(op, indent, schemaNames) {
         lines.push(`${indent}    return void res.status(422).json({ error: 'Invalid request headers', issues: _hv.error.issues })`);
         lines.push(`${indent}  }`);
     }
+    // Cookie param validation
+    // Requires cookie-parser middleware: app.use(cookieParser()) before mounting this router.
+    if (op.cookieParams.length > 0) {
+        emitCookieValidation(lines, op.cookieParams, indent, 'express');
+        lines.push(`${indent}  if (!_ckv.success) {`);
+        lines.push(`${indent}    return void res.status(422).json({ error: 'Invalid request cookies', issues: _ckv.error.issues })`);
+        lines.push(`${indent}  }`);
+    }
     // Body extraction, with optional Zod validation.
     // For both JSON and form-urlencoded bodies Express pre-populates req.body via middleware
     // (express.json() for JSON, express.urlencoded() for form). The router just reads req.body.
@@ -761,7 +973,14 @@ function buildExpressRouteHandler(op, indent, schemaNames) {
                 lines.push(`${indent}  if (!parseResult.success) {`);
                 lines.push(`${indent}    return void res.status(422).json({ error: 'Invalid request body', issues: parseResult.error.issues })`);
                 lines.push(`${indent}  }`);
-                lines.push(`${indent}  const validatedBody = parseResult.data`);
+                // Cast parseResult.data to the declared model type so the service call receives
+                // the correct TypeScript type even when the Zod schema infers a narrower or
+                // different shape (e.g. z.unknown() for inline-union properties). The cast is
+                // safe because safeParse already confirmed the value is structurally valid.
+                const typeDecl = op.bodyInfo.typeName !== undefined && !op.bodyInfo.isSynthesized
+                    ? op.bodyInfo.typeName
+                    : 'unknown';
+                lines.push(`${indent}  const validatedBody = parseResult.data as ${typeDecl}`);
                 bodyVarName = 'validatedBody';
             }
             else {
@@ -776,13 +995,23 @@ function buildExpressRouteHandler(op, indent, schemaNames) {
     // Build service call args
     const serviceArgs = [];
     for (const p of op.pathParams) {
-        serviceArgs.push(`req.params['${p}']!`);
+        // Cast to string: Express 5 types req.params values as string | string[],
+        // but path params are always single strings in practice.
+        serviceArgs.push(`(req.params['${p}'] as string)`);
     }
     if (op.bodyInfo !== undefined) {
         serviceArgs.push(bodyVarName);
     }
     if (op.queryParams.length > 0) {
-        serviceArgs.push('params');
+        // After successful Zod validation _qv.data carries the correct required/typed
+        // values (e.g. string[] for delimited arrays, object shape for deepObject params,
+        // and non-optional values for required scalar params). Use _qv.data when validation
+        // was applied; fall back to params when no validation is needed.
+        serviceArgs.push(queryParamsNeedValidation(op.queryParams) ? '_qv.data' : 'params');
+    }
+    // Context arg: pass the Express Request object (req) as the final argument when contextType is set.
+    if (contextType !== undefined) {
+        serviceArgs.push('req');
     }
     const serviceCall = `service.${op.methodName}(${serviceArgs.join(', ')})`;
     // Response — wrap in try/catch to map HttpError to its status
@@ -828,8 +1057,45 @@ function buildExpressRouteHandler(op, indent, schemaNames) {
     return lines.join('\n');
 }
 // ── Fastify route handler ─────────────────────────────────────────────────────
+/**
+ * Build the route options object literal string for a Fastify route registration.
+ * Always includes config.operationId so onRequest hooks can identify the operation
+ * via request.routeOptions.config.operationId (issue #309).
+ * When a response schema is available in schemaNames, also includes schema.response
+ * so Fastify validates the response against the Zod schema (issue #308).
+ * Both properties are merged into a single options object literal when both apply.
+ */
+function buildFastifyRouteOptions(op, schemaNames) {
+    const parts = [];
+    const responseSchemaExpr = buildFastifyResponseSchemaExpr(op, schemaNames);
+    if (responseSchemaExpr !== undefined) {
+        parts.push(`schema: { response: { ${op.responseStatus.status}: ${responseSchemaExpr} } }`);
+    }
+    parts.push(`config: { operationId: '${op.methodName}' }`);
+    return `{ ${parts.join(', ')} }`;
+}
+/**
+ * Build the Zod schema expression for a Fastify schema.response entry.
+ * Returns undefined when no schema is available or the operation is multi-status.
+ * Direct $ref response: 'PetSchema'
+ * Array-of-$ref response: 'z.array(PetSchema)'
+ */
+function buildFastifyResponseSchemaExpr(op, schemaNames) {
+    if (schemaNames === undefined)
+        return undefined;
+    if (op.responseTypeName === undefined)
+        return undefined;
+    if (op.responseStatus.isMultiStatus === true)
+        return undefined;
+    if (op.responseStatus.isVoid)
+        return undefined;
+    const schemaName = `${op.responseTypeName}Schema`;
+    if (!schemaNames.has(schemaName))
+        return undefined;
+    return op.responseIsArray === true ? `z.array(${schemaName})` : schemaName;
+}
 // fallow-ignore-next-line complexity
-function buildFastifyRouteHandler(op, indent, schemaNames) {
+function buildFastifyRouteHandler(op, indent, schemaNames, contextType) {
     const lines = [];
     // Build generic type argument
     const genericParts = [];
@@ -868,12 +1134,13 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
         genericParts.push(`Params: { ${paramFields} }`);
     }
     const generic = genericParts.length > 0 ? `<{ ${genericParts.join('; ')} }>` : '';
-    lines.push(`${indent}app.${op.httpMethod}${generic}(${JSON.stringify(op.honoPath)}, async (req, reply) => {`);
+    const routeOpts = buildFastifyRouteOptions(op, schemaNames);
+    lines.push(`${indent}app.${op.httpMethod}${generic}(${JSON.stringify(op.honoPath)}, ${routeOpts}, async (req, reply) => {`);
     // Path param format validation (e.g. uuid)
     if (op.pathParamValidations.length > 0) {
         emitPathValidation(lines, op.pathParamValidations, indent, 'fastify');
         lines.push(`${indent}  if (!_pv.success) {`);
-        lines.push(`${indent}    return reply.status(422).send({`);
+        lines.push(`${indent}    return (reply as FastifyReply).status(422).send({`);
         lines.push(`${indent}      error: 'Invalid path parameters',`);
         lines.push(`${indent}      issues: _pv.error.issues,`);
         lines.push(`${indent}    })`);
@@ -909,6 +1176,13 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
                 return `    ${q.name}: typeof _dq['${q.rawName}'] === 'string' ? _dq['${q.rawName}']!.split(${delim}) : undefined`;
             }
             // When _dq is defined, use it for consistent access; otherwise use typed req.query.
+            // Boolean params must be coerced from string at extraction time: z.coerce.boolean()
+            // is unusable because Boolean('false') === true, so mirror the Express === 'true' pattern.
+            if (q.tsType === 'boolean') {
+                return hasDeepOrDelimited
+                    ? `    ${q.name}: _dq['${q.rawName}'] === 'true'`
+                    : `    ${q.name}: (req.query.${q.name} as unknown as string) === 'true'`;
+            }
             return hasDeepOrDelimited
                 ? `    ${q.name}: _dq['${q.rawName}']`
                 : `    ${q.name}: req.query.${q.name}`;
@@ -921,7 +1195,7 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
         if (queryParamsNeedValidation(op.queryParams)) {
             emitQueryValidation(lines, op.queryParams, indent);
             lines.push(`${indent}  if (!_qv.success) {`);
-            lines.push(`${indent}    return reply.status(422).send({`);
+            lines.push(`${indent}    return (reply as FastifyReply).status(422).send({`);
             lines.push(`${indent}      error: 'Invalid query parameters',`);
             lines.push(`${indent}      issues: _qv.error.issues,`);
             lines.push(`${indent}    })`);
@@ -932,22 +1206,43 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
     if (op.headerParams.length > 0) {
         emitHeaderValidation(lines, op.headerParams, indent, 'fastify');
         lines.push(`${indent}  if (!_hv.success) {`);
-        lines.push(`${indent}    return reply.status(422).send({`);
+        lines.push(`${indent}    return (reply as FastifyReply).status(422).send({`);
         lines.push(`${indent}      error: 'Invalid request headers',`);
         lines.push(`${indent}      issues: _hv.error.issues,`);
         lines.push(`${indent}    })`);
         lines.push(`${indent}  }`);
     }
+    // Cookie param validation
+    // Requires @fastify/cookie plugin registered before creating the router: fastify.register(fastifyCookie).
+    if (op.cookieParams.length > 0) {
+        emitCookieValidation(lines, op.cookieParams, indent, 'fastify');
+        lines.push(`${indent}  if (!_ckv.success) {`);
+        lines.push(`${indent}    return (reply as FastifyReply).status(422).send({`);
+        lines.push(`${indent}      error: 'Invalid request cookies',`);
+        lines.push(`${indent}      issues: _ckv.error.issues,`);
+        lines.push(`${indent}    })`);
+        lines.push(`${indent}  }`);
+    }
     // Body handling, with optional Zod validation.
-    // Fastify pre-parses req.body for both JSON and form-urlencoded bodies via plugins.
-    // For multipart/form-data: assumes @fastify/multipart (or equivalent) plugin is registered
-    // so that req.body contains the parsed fields and file parts.
+    // Fastify natively parses only application/json and text/plain.
+    // For application/x-www-form-urlencoded: register @fastify/formbody before this router
+    // so that req.body is populated.
+    // For multipart/form-data: register @fastify/multipart with attachFieldsToBody: true before
+    // this router so that req.body is populated with parsed fields. Without attachFieldsToBody,
+    // @fastify/multipart v10 exposes files via async iterators (request.parts()), not req.body.
     let bodyVarName = 'req.body';
     if (op.bodyInfo !== undefined) {
         if (op.bodyInfo.contentType === 'multipart/form-data') {
-            // Multipart assumption: @fastify/multipart plugin has populated req.body before this
-            // handler runs. The body is forwarded to the service as-is.
-            lines.push(`${indent}  // multipart/form-data: assumes @fastify/multipart plugin has populated req.body.`);
+            // multipart/form-data: @fastify/multipart must be registered with attachFieldsToBody: true.
+            // Without that option, files are only accessible via async iterators (request.parts()),
+            // NOT via req.body. The consumer must register the plugin before creating this router.
+            lines.push(`${indent}  // multipart/form-data: requires @fastify/multipart registered with { attachFieldsToBody: true }.`);
+            // bodyVarName stays 'req.body'
+        }
+        else if (op.bodyInfo.contentType === 'application/octet-stream') {
+            // application/octet-stream: req.body is a Buffer (parsed by the addContentTypeParser
+            // registration emitted in the createRouter body above). Forward it to the service as-is.
+            lines.push(`${indent}  // application/octet-stream: req.body is a Buffer from the registered content-type parser.`);
             // bodyVarName stays 'req.body'
         }
         else {
@@ -957,9 +1252,18 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
                 lines.push(`${indent}  // Validate request body: returns 422 with Zod issues on failure`);
                 lines.push(`${indent}  const parseResult = ${schemaName}.safeParse(req.body)`);
                 lines.push(`${indent}  if (!parseResult.success) {`);
-                lines.push(`${indent}    return reply.status(422).send({ error: 'Invalid request body', issues: parseResult.error.issues })`);
+                lines.push(`${indent}    return (reply as FastifyReply).status(422).send({ error: 'Invalid request body', issues: parseResult.error.issues })`);
                 lines.push(`${indent}  }`);
-                bodyVarName = 'parseResult.data';
+                // Forward the validated/coerced data (parseResult.data), NOT the raw req.body,
+                // so Zod coercion is preserved (e.g. form-urlencoded numeric fields via
+                // z.coerce.number()). Cast to the declared model type so the service-call type
+                // stays correct even when the schema infers a narrower shape (e.g. z.unknown()
+                // for inline-union properties); safeParse above guarantees runtime safety.
+                const bodyCastType = op.bodyInfo.typeName !== undefined && !op.bodyInfo.isSynthesized
+                    ? op.bodyInfo.typeName
+                    : 'unknown';
+                lines.push(`${indent}  const validatedBody = parseResult.data as ${bodyCastType}`);
+                bodyVarName = 'validatedBody';
             }
         }
     }
@@ -972,7 +1276,15 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
         serviceArgs.push(bodyVarName);
     }
     if (op.queryParams.length > 0) {
-        serviceArgs.push('params');
+        // After successful Zod validation _qv.data carries the correct required/typed
+        // values (e.g. string[] for delimited arrays, object shape for deepObject params,
+        // and non-optional values for required scalar params). Use _qv.data when validation
+        // was applied; fall back to params when no validation is needed.
+        serviceArgs.push(queryParamsNeedValidation(op.queryParams) ? '_qv.data' : 'params');
+    }
+    // Context arg: pass the Fastify Request object (req) as the final argument when contextType is set.
+    if (contextType !== undefined) {
+        serviceArgs.push('req');
     }
     const serviceCall = `service.${op.methodName}(${serviceArgs.join(', ')})`;
     // Response — wrap in try/catch to map HttpError to its status
@@ -1003,15 +1315,15 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
         }
     }
     else if (op.responseStatus.status === 200) {
-        lines.push(`${indent}    return ${serviceCall}`);
+        lines.push(`${indent}    return await ${serviceCall}`);
     }
     else {
         lines.push(`${indent}    reply.status(${op.responseStatus.status})`);
-        lines.push(`${indent}    return ${serviceCall}`);
+        lines.push(`${indent}    return await ${serviceCall}`);
     }
     lines.push(`${indent}  } catch (err) {`);
     lines.push(`${indent}    if (err instanceof HttpError) {`);
-    lines.push(`${indent}      return reply.status(err.status).send({ error: err.message })`);
+    lines.push(`${indent}      return (reply as FastifyReply).status(err.status).send({ error: err.message })`);
     lines.push(`${indent}    }`);
     lines.push(`${indent}    throw err`);
     lines.push(`${indent}  }`);
@@ -1037,7 +1349,8 @@ function httpErrorClassLines() {
 // ── Zod import helpers ────────────────────────────────────────────────────────
 /**
  * Returns true when any operation in the list generates param validation code
- * that requires Zod (path format validation, required/typed query params, or header params).
+ * that requires Zod (path format validation, required/typed query params, header params,
+ * or cookie params).
  */
 function operationsNeedZodForParams(operations) {
     for (const op of operations) {
@@ -1047,6 +1360,8 @@ function operationsNeedZodForParams(operations) {
             return true;
         if (op.headerParams.length > 0)
             return true;
+        if (op.cookieParams.length > 0)
+            return true;
     }
     return false;
 }
@@ -1056,6 +1371,7 @@ export function generateExpressRouter(spec, options) {
     const serviceName = deriveServiceName(spec);
     const operations = collectOperations(spec);
     const { sortedBodyTypes, usedSchemaNames, needsZod } = collectGeneratorSetup(operations, options);
+    // usedResponseSchemaNames is Fastify-only; not used in Express generator.
     const lines = [];
     lines.push('// This file is auto-generated. Do not edit manually.');
     lines.push('// Express: apply express.json() middleware before mounting this router so req.body is populated.');
@@ -1065,6 +1381,8 @@ export function generateExpressRouter(spec, options) {
     if (sortedBodyTypes.length > 0) {
         lines.push(`import type { ${sortedBodyTypes.join(', ')} } from './models.js'`);
     }
+    const ctx = options?.contextType;
+    const serviceRef = ctx !== undefined ? `${serviceName}<${ctx}>` : serviceName;
     lines.push(`import type { ${serviceName} } from './service.js'`);
     if (needsZod) {
         lines.push(`import { z } from 'zod'`);
@@ -1077,11 +1395,11 @@ export function generateExpressRouter(spec, options) {
     for (const l of httpErrorClassLines())
         lines.push(l);
     lines.push('');
-    lines.push(`export function createRouter(service: ${serviceName}): Router {`);
+    lines.push(`export function createRouter(service: ${serviceRef}): Router {`);
     lines.push('  const router = Router()');
     lines.push('');
     for (const op of operations) {
-        lines.push(buildExpressRouteHandler(op, '  ', options?.schemaNames));
+        lines.push(buildExpressRouteHandler(op, '  ', options?.schemaNames, ctx));
         lines.push('');
     }
     lines.push('  return router');
@@ -1097,11 +1415,20 @@ export function generateExpressRouter(spec, options) {
 export function generateFastifyRouter(spec, options) {
     const serviceName = deriveServiceName(spec);
     const operations = collectOperations(spec);
-    const { sortedBodyTypes, usedSchemaNames, needsZod } = collectGeneratorSetup(operations, options);
+    const { sortedBodyTypes, usedSchemaNames, usedResponseSchemaNames, needsZod } = collectGeneratorSetup(operations, options);
+    // Merge body and response schema imports into a single sorted import list.
+    const allUsedSchemaNames = new Set([...usedSchemaNames, ...usedResponseSchemaNames]);
+    // Detect operations that need the octet-stream request body parser.
+    const hasOctetStreamRequestBody = operations.some((op) => op.bodyInfo?.contentType === 'application/octet-stream');
     const lines = [];
     lines.push('// This file is auto-generated. Do not edit manually.');
+    lines.push('// Fastify natively parses only application/json and text/plain request bodies.');
+    lines.push('// For application/x-www-form-urlencoded bodies, register @fastify/formbody before this router.');
+    lines.push('// For multipart/form-data bodies, register @fastify/multipart with { attachFieldsToBody: true } before this router.');
     lines.push('');
-    lines.push("import type { FastifyInstance } from 'fastify'");
+    const ctx = options?.contextType;
+    const serviceRef = ctx !== undefined ? `${serviceName}<${ctx}>` : serviceName;
+    lines.push("import type { FastifyInstance, FastifyReply } from 'fastify'");
     if (sortedBodyTypes.length > 0) {
         lines.push(`import type { ${sortedBodyTypes.join(', ')} } from './models.js'`);
     }
@@ -1109,18 +1436,46 @@ export function generateFastifyRouter(spec, options) {
     if (needsZod) {
         lines.push(`import { z } from 'zod'`);
     }
-    if (usedSchemaNames.size > 0 && options?.schemaImportPath !== undefined) {
-        const sortedUsedSchemas = Array.from(usedSchemaNames).sort();
+    if (allUsedSchemaNames.size > 0 && options?.schemaImportPath !== undefined) {
+        const sortedUsedSchemas = Array.from(allUsedSchemaNames).sort();
         lines.push(`import { ${sortedUsedSchemas.join(', ')} } from '${options.schemaImportPath}'`);
     }
     lines.push('');
+    // Augment FastifyContextConfig so that config: { operationId } on each route is type-safe.
+    // Without this, TypeScript rejects the operationId property because FastifyContextConfig
+    // is empty by default. The augmentation is scoped to the generated router module.
+    lines.push("declare module 'fastify' {");
+    lines.push('  interface FastifyContextConfig {');
+    lines.push('    operationId?: string');
+    lines.push('  }');
+    lines.push('}');
+    lines.push('');
     for (const l of httpErrorClassLines())
         lines.push(l);
     lines.push('');
-    lines.push(`export function createRouter(app: FastifyInstance, service: ${serviceName}): void {`);
+    lines.push(`export function createRouter(app: FastifyInstance, service: ${serviceRef}): void {`);
+    // Register a built-in content-type parser for application/octet-stream so that
+    // req.body is a Buffer. Fastify 5 does not parse octet-stream natively; without
+    // this registration the framework returns a 415 before the handler runs.
+    // addContentTypeParser is a core Fastify API and requires no extra dependency.
+    if (hasOctetStreamRequestBody) {
+        lines.push("  app.addContentTypeParser('application/octet-stream', { parseAs: 'buffer' }, (req, body, done) => done(null, body))");
+    }
+    // Wire a Zod-aware serializer compiler when response schemas are present.
+    // Fastify's default serializer does not understand Zod schemas; this compiler
+    // detects any Zod schema by its .parse method and validates before serializing.
+    if (usedResponseSchemaNames.size > 0 && options?.schemaImportPath !== undefined) {
+        lines.push('  app.setSerializerCompiler(({ schema }) => {');
+        lines.push("    if (schema !== null && typeof schema === 'object' && 'parse' in schema) {");
+        lines.push('      const zodSchema = schema as { parse: (data: unknown) => unknown }');
+        lines.push('      return (data: unknown) => JSON.stringify(zodSchema.parse(data))');
+        lines.push('    }');
+        lines.push('    return (data: unknown) => JSON.stringify(data)');
+        lines.push('  })');
+    }
     for (const op of operations) {
         lines.push('');
-        lines.push(buildFastifyRouteHandler(op, '  ', options?.schemaNames));
+        lines.push(buildFastifyRouteHandler(op, '  ', options?.schemaNames, ctx));
     }
     lines.push('}');
     lines.push('');
@@ -1138,7 +1493,14 @@ export function generateRouter(spec, options) {
     const lines = [];
     lines.push('// This file is auto-generated. Do not edit manually.');
     lines.push('');
+    const ctx = options?.contextType;
+    const serviceRef = ctx !== undefined ? `${serviceName}<${ctx}>` : serviceName;
+    // getCookie from hono/cookie is needed when any operation declares cookie params.
+    const needsGetCookie = operations.some((op) => op.cookieParams.length > 0);
     lines.push("import { Hono } from 'hono'");
+    if (needsGetCookie) {
+        lines.push("import { getCookie } from 'hono/cookie'");
+    }
     if (sortedBodyTypes.length > 0) {
         lines.push(`import type { ${sortedBodyTypes.join(', ')} } from './models.js'`);
     }
@@ -1154,11 +1516,11 @@ export function generateRouter(spec, options) {
     for (const l of httpErrorClassLines())
         lines.push(l);
     lines.push('');
-    lines.push(`export function createRouter(service: ${serviceName}): Hono {`);
+    lines.push(`export function createRouter(service: ${serviceRef}): Hono {`);
     lines.push('  const app = new Hono()');
     lines.push('');
     for (const op of operations) {
-        lines.push(buildRouteHandler(op, '  ', options?.schemaNames));
+        lines.push(buildRouteHandler(op, '  ', options?.schemaNames, ctx));
         lines.push('');
     }
     lines.push('  return app');