@codewithagents/openapi-server 1.7.0 → 1.9.0

package/dist/plugins/router.js

@@ -1,155 +1,8 @@
-import { toTypeName } from 'openapi-zod-ts';
-const SUPPORTED_METHODS = ['get', 'post', 'put', 'patch', 'delete'];
-// ── Helpers ───────────────────────────────────────────────────────────────────
-function isRef(obj) {
-    return typeof obj === 'object' && obj !== null && '$ref' in obj;
-}
-function refToName(ref) {
-    const parts = ref.split('/');
-    return toTypeName(parts[parts.length - 1]);
-}
-function extractPathParamsFromPath(path) {
-    const matches = path.match(/\{([^}]+)\}/g);
-    if (matches === null)
-        return [];
-    // Keep raw param names: they are used in c.req.param() which must match
-    // the actual Hono route pattern (e.g. :job-id requires c.req.param('job-id'))
-    return matches.map((m) => m.slice(1, -1));
-}
+import { SUPPORTED_METHODS, isRef, 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');
 }
-function resolveParam(p, spec) {
-    if (!isRef(p))
-        return p;
-    const refStr = p.$ref;
-    const name = refToName(refStr);
-    const components = spec.components;
-    if (components?.parameters === undefined)
-        return undefined;
-    const resolved = components.parameters[name];
-    if (resolved === undefined || isRef(resolved))
-        return undefined;
-    return resolved;
-}
-function deriveServiceName(spec) {
-    const title = spec.info?.title ?? '';
-    const pascal = title
-        .replace(/[^a-zA-Z0-9 ]/g, '')
-        .split(/\s+/)
-        .filter((s) => s.length > 0)
-        .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
-        .join('');
-    if (pascal.length === 0)
-        return 'ApiService';
-    // Guard against numeric-start identifiers (e.g. '1Password Connect' -> '_1PasswordConnect')
-    const safePascal = /^[0-9]/.test(pascal) ? `_${pascal}` : pascal;
-    if (safePascal.endsWith('Service'))
-        return safePascal;
-    return `${safePascal}Service`;
-}
-/**
- * Converts a raw operationId into a valid camelCase JS identifier.
- * Handles kebab-case, snake_case, dots, spaces, parens, braces and other
- * non-alphanumeric separators found in real-world OpenAPI specs.
- * e.g. "post-applePay-sessions"   -> "postApplePaySessions"
- * e.g. "calendar.calendars.insert" -> "calendarCalendarsInsert"
- * e.g. "Get User Profile"          -> "getUserProfile"
- * e.g. "forgotPassword(oneTimeCode)" -> "forgotPasswordOneTimeCode"
- */
-function sanitizeOperationId(id) {
-    const parts = id
-        .replace(/'/g, '') // strip apostrophes without splitting ("user's" -> "users")
-        .split(/[^a-zA-Z0-9]+/) // split on any non-alphanumeric sequence
-        .filter(Boolean);
-    if (parts.length === 0)
-        return 'unknown';
-    const [first = '', ...rest] = parts;
-    const camel = first.charAt(0).toLowerCase() +
-        first.slice(1) +
-        rest.map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join('');
-    // If result starts with a digit, prefix with underscore
-    return /^[0-9]/.test(camel) ? `_${camel}` : camel;
-}
-function deriveMethodName(operationId, method, path) {
-    if (operationId !== undefined && operationId.length > 0) {
-        return sanitizeOperationId(operationId);
-    }
-    return deriveOperationName(method, path);
-}
-function deriveOperationName(method, path) {
-    const prefixMap = {
-        get: 'get',
-        post: 'create',
-        put: 'update',
-        patch: 'patch',
-        delete: 'delete',
-    };
-    const prefix = prefixMap[method] ?? method;
-    const segments = path.replace(/^\/api\/v\d+\//, '').replace(/^\//, '');
-    const parts = segments.split('/').map((seg) => {
-        // Handle mixed segments like "{maxLat}.{format}": extract each {param} inside
-        const paramMatches = seg.match(/\{([^}]+)\}/g);
-        if (paramMatches !== null && !(seg.startsWith('{') && seg.endsWith('}'))) {
-            return paramMatches
-                .map((m) => {
-                const name = sanitizeOperationId(m.slice(1, -1));
-                return 'By' + name.charAt(0).toUpperCase() + name.slice(1);
-            })
-                .join('');
-        }
-        if (seg.startsWith('{') && seg.endsWith('}')) {
-            const name = seg.slice(1, -1);
-            const sanitized = sanitizeOperationId(name);
-            return 'By' + sanitized.charAt(0).toUpperCase() + sanitized.slice(1);
-        }
-        return toTypeName(seg);
-    });
-    return prefix + parts.join('');
-}
-/** Normalize a raw query param name to a valid TypeScript identifier.
- *  Strips trailing [] (array marker), converts separators to camelCase.
- */
-function normalizeParamName(name) {
-    // Split on non-alphanumeric sequences to avoid polynomial ReDoS from [^x]+y patterns.
-    const stripped = name.replace(/\[\]$/, '').replace(/'/g, '');
-    const parts = stripped.split(/[^a-zA-Z0-9]+/).filter(Boolean);
-    if (parts.length === 0)
-        return '_';
-    const camel = parts
-        .map((part, i) => (i === 0 ? part : part[0].toUpperCase() + part.slice(1)))
-        .join('');
-    return /^[^a-zA-Z_$]/.test(camel) ? `_${camel}` : camel;
-}
-function schemaToTsType(schema) {
-    if (schema === undefined || isRef(schema))
-        return 'string';
-    const s = schema;
-    if (s.type === 'number' || s.type === 'integer')
-        return 'number';
-    if (s.type === 'boolean')
-        return 'boolean';
-    return 'string';
-}
-function getQueryParams(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 !== 'query')
-            continue;
-        const schema = resolved.schema;
-        result.push({
-            name: normalizeParamName(resolved.name),
-            tsType: schemaToTsType(schema),
-            required: resolved.required === true,
-        });
-    }
-    return result;
-}
 /**
  * Map a schema format string to a Zod chain modifier.
  * Returns an empty string when no specific format validation is needed.
@@ -171,13 +24,38 @@ function formatToZodModifier(format) {
 }
 /**
  * Build a Zod expression for a path parameter based on its schema.
- * Returns undefined when the parameter does not need format validation
- * (simple string with no format constraint or non-string types used as strings in URLs).
+ * Returns undefined when the parameter does not need validation.
+ *
+ * String params: validates format (uuid, email, url, date-time) via z.string().format().
+ * Integer/number params: validates range (minimum/maximum) via z.coerce.number().min().max().
+ * z.coerce.number() is used for path params because c.req.param() always returns a string;
+ * coercion converts the URL string to a number before the min/max check.
  */
 function pathParamZodExpr(schema) {
     if (schema === undefined || isRef(schema))
         return undefined;
     const s = schema;
+    // Integer / number path params with range constraints
+    if (s.type === 'integer' || s.type === 'number') {
+        const hasMin = typeof s.minimum === 'number';
+        const hasMax = typeof s.maximum === 'number';
+        const hasExcMin = typeof s.exclusiveMinimum === 'number';
+        const hasExcMax = typeof s.exclusiveMaximum === 'number';
+        if (hasMin || hasMax || hasExcMin || hasExcMax) {
+            let expr = 'z.coerce.number()';
+            if (hasMin)
+                expr += `.min(${s.minimum})`;
+            if (hasMax)
+                expr += `.max(${s.maximum})`;
+            if (hasExcMin)
+                expr += `.gt(${s.exclusiveMinimum})`;
+            if (hasExcMax)
+                expr += `.lt(${s.exclusiveMaximum})`;
+            return expr;
+        }
+        return undefined;
+    }
+    // String path params: only validated when a known format modifier exists
     if (s.type !== 'string')
         return undefined;
     const format = s.format;
@@ -188,33 +66,102 @@ function pathParamZodExpr(schema) {
         return undefined;
     return `z.string()${modifier}`;
 }
+// ── queryParamZodExpr helpers (one per param kind) ───────────────────────────
+/** Delimited array param: value has been split into string[] by the extraction layer. */
+function queryParamDelimitedZodBase(_param) {
+    return 'z.array(z.string())';
+}
+/**
+ * DeepObject param: assembled into Record<string, string>.
+ * Emits z.object({...}) with per-property coercion; all properties are .optional()
+ * because their presence is governed by the outer object's required flag.
+ */
+function queryParamDeepObjectZodBase(param) {
+    const propFields = (param.deepObjectProperties ?? []).map((p) => {
+        const coerced = p.tsType === 'number' ? 'z.coerce.number()' : 'z.string()';
+        return `${p.key}: ${coerced}.optional()`;
+    });
+    return `z.object({ ${propFields.join(', ')} })`;
+}
+/** Number/integer param: z.number() with optional range modifiers. */
+function queryParamNumberZodBase(param) {
+    let base = 'z.number()';
+    if (param.minimum !== undefined)
+        base += `.min(${param.minimum})`;
+    if (param.maximum !== undefined)
+        base += `.max(${param.maximum})`;
+    if (param.exclusiveMinimum !== undefined)
+        base += `.gt(${param.exclusiveMinimum})`;
+    if (param.exclusiveMaximum !== undefined)
+        base += `.lt(${param.exclusiveMaximum})`;
+    return base;
+}
+/** String param: z.string() or z.enum([...]) with optional length/pattern modifiers. */
+function queryParamStringZodBase(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 base;
+}
 /**
- * Build a Zod expression for a query or header parameter based on its schema.
+ * Build a Zod expression for a query parameter based on its captured constraints.
  * Number/integer types use z.number() (after coercion by extraction code).
- * String types use z.string(). Boolean types use z.boolean().
+ * String types use z.string() with optional format/enum/pattern/length modifiers.
+ * Delimited array params use z.array(z.string()).
+ * DeepObject params use z.object({...}) with per-property coercion.
  * Appends .optional() for non-required params.
  */
-function paramZodExpr(tsType, required, schema) {
+function queryParamZodExpr(param) {
     let base;
-    if (tsType === 'number') {
-        base = 'z.number()';
+    if (param.delimiterStyle !== undefined) {
+        base = queryParamDelimitedZodBase(param);
+    }
+    else if (param.isDeepObject === true && param.deepObjectProperties !== undefined) {
+        base = queryParamDeepObjectZodBase(param);
+    }
+    else if (param.tsType === 'number') {
+        base = queryParamNumberZodBase(param);
     }
-    else if (tsType === 'boolean') {
+    else if (param.tsType === 'boolean') {
         base = 'z.boolean()';
     }
     else {
-        // string
-        if (schema !== undefined && !isRef(schema)) {
-            const s = schema;
-            const format = s.format;
-            const modifier = format !== undefined ? formatToZodModifier(format) : '';
-            base = `z.string()${modifier}`;
-        }
-        else {
-            base = 'z.string()';
-        }
+        base = queryParamStringZodBase(param);
     }
-    return required ? base : `${base}.optional()`;
+    return param.required ? base : `${base}.optional()`;
+}
+/**
+ * Build a Zod expression for a header parameter based on its captured constraints.
+ * Header values are always strings; emits z.string() or z.enum([...]) with optional
+ * pattern/length modifiers. Appends .optional() for non-required params.
+ */
+function headerParamZodExpr(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 path parameters that have Zod format constraints.
@@ -245,7 +192,7 @@ function getPathParamValidations(operation, spec, rawPathParamNames) {
     return result;
 }
 /**
- * Collect header parameters from an operation.
+ * Collect header parameters from an operation, including schema constraints.
  */
 function getHeaderParams(operation, spec) {
     const parameters = operation.parameters;
@@ -256,19 +203,60 @@ function getHeaderParams(operation, spec) {
         const resolved = resolveParam(p, spec);
         if (resolved === undefined || resolved.in !== 'header')
             continue;
-        result.push({
+        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.
+ */
+function queryParamHasConstraints(q) {
+    // Fields that, when defined, indicate schema constraints are present.
+    const constraintFields = [
+        q.enum,
+        q.minimum,
+        q.maximum,
+        q.exclusiveMinimum,
+        q.exclusiveMaximum,
+        q.minLength,
+        q.maxLength,
+        q.pattern,
+        q.delimiterStyle,
+    ];
+    return constraintFields.some((f) => f !== undefined) || q.isDeepObject === true;
+}
 /**
  * Determine whether query params need a Zod validation block.
- * Triggered when any param is required or has a non-string type (to catch NaN/invalid input).
+ * Triggered when any param is required, has a non-string type (to catch NaN/invalid input),
+ * or carries schema constraints (enum, min/max, pattern, etc.).
  */
 function queryParamsNeedValidation(queryParams) {
-    return queryParams.some((q) => q.required || q.tsType !== 'string');
+    return queryParams.some((q) => q.required || q.tsType !== 'string' || queryParamHasConstraints(q));
+}
+/** Returns the delimiter character for a delimited-style array query param. */
+function delimiterChar(style) {
+    if (style === 'ssv')
+        return ' ';
+    if (style === 'psv')
+        return '|';
+    return ',';
 }
 /**
  * Emit Zod validation lines for query parameters into the handler line buffer.
@@ -281,7 +269,7 @@ function emitQueryValidation(lines, queryParams, indent) {
     const fieldIndent = `${indent}    `;
     const fields = queryParams
         .map((q) => {
-        const expr = paramZodExpr(q.tsType, q.required);
+        const expr = queryParamZodExpr(q);
         return `${fieldIndent}${q.name}: ${expr}`;
     })
         .join(',\n');
@@ -342,7 +330,7 @@ function emitHeaderValidation(lines, headerParams, indent, framework) {
     const schemaFields = headerParams
         .map((h) => {
         const key = JSON.stringify(h.rawName);
-        const expr = h.required ? 'z.string()' : 'z.string().optional()';
+        const expr = headerParamZodExpr(h);
         return `${fieldIndent}${key}: ${expr}`;
     })
         .join(',\n');
@@ -369,25 +357,6 @@ function emitHeaderValidation(lines, headerParams, indent, framework) {
     lines.push(rawFields);
     lines.push(`${inner}})`);
 }
-function getBodyInfo(operation) {
-    const requestBody = operation.requestBody;
-    if (requestBody === undefined)
-        return undefined;
-    if (isRef(requestBody))
-        return { typeName: undefined };
-    const rb = requestBody;
-    const content = rb.content;
-    if (content === undefined)
-        return { typeName: undefined };
-    const jsonContent = content['application/json'];
-    if (jsonContent === undefined || jsonContent.schema === undefined)
-        return { typeName: undefined };
-    const schema = jsonContent.schema;
-    if (isRef(schema)) {
-        return { typeName: refToName(schema.$ref) };
-    }
-    return { typeName: undefined };
-}
 function response200IsVoid(resp) {
     if (isRef(resp))
         return false;
@@ -395,22 +364,84 @@ function response200IsVoid(resp) {
     const content = r.content;
     return content === undefined || Object.keys(content).length === 0;
 }
+/**
+ * Detect the success response content type from a ResponseObject.
+ * Returns 'text/plain' or 'application/octet-stream' for non-JSON responses,
+ * or 'application/json' as the default.
+ */
+function detectResponseContentType(resp) {
+    if (isRef(resp))
+        return 'application/json';
+    const r = resp;
+    const content = r.content;
+    if (content === undefined)
+        return 'application/json';
+    if ('text/plain' in content)
+        return 'text/plain';
+    if ('application/octet-stream' in content)
+        return 'application/octet-stream';
+    return 'application/json';
+}
 function getResponseStatus(operation, httpMethod) {
     const responses = operation.responses;
     if (responses === undefined) {
-        return httpMethod === 'delete' ? { status: 204, isVoid: true } : { status: 200, isVoid: false };
+        return httpMethod === 'delete'
+            ? { status: 204, isVoid: true, responseContentType: 'application/json' }
+            : { status: 200, isVoid: false, responseContentType: 'application/json' };
+    }
+    // Multi-status: more than one 2xx response with a body (excluding 204/void).
+    // Must be checked before individual 200/201/204 branches so that e.g. 200+202
+    // is not absorbed by the responses['200'] early return.
+    // The handler selects the status at runtime via a { status, body } envelope.
+    const contentfulTwoxxKeys = Object.keys(responses)
+        .filter((k) => /^2\d\d$/.test(k) && k !== '204')
+        .sort();
+    if (contentfulTwoxxKeys.length > 1) {
+        return {
+            status: 200,
+            isVoid: false,
+            responseContentType: 'application/json',
+            isMultiStatus: true,
+        };
+    }
+    if (responses['201'] !== undefined) {
+        return {
+            status: 201,
+            isVoid: false,
+            responseContentType: detectResponseContentType(responses['201']),
+        };
+    }
+    if (responses['204'] !== undefined) {
+        return { status: 204, isVoid: true, responseContentType: 'application/json' };
     }
-    if (responses['201'] !== undefined)
-        return { status: 201, isVoid: false };
-    if (responses['204'] !== undefined)
-        return { status: 204, isVoid: true };
     if (responses['200'] !== undefined) {
-        if (response200IsVoid(responses['200']))
-            return { status: 204, isVoid: true };
-        return { status: 200, isVoid: false };
+        if (response200IsVoid(responses['200'])) {
+            return { status: 204, isVoid: true, responseContentType: 'application/json' };
+        }
+        return {
+            status: 200,
+            isVoid: false,
+            responseContentType: detectResponseContentType(responses['200']),
+        };
+    }
+    // Single non-200/201/204 2xx declared: honor that exact status code.
+    const twoxxKeys = Object.keys(responses).filter((k) => /^2\d\d$/.test(k) && k !== '200' && k !== '201' && k !== '204');
+    if (twoxxKeys.length === 1) {
+        const code = parseInt(twoxxKeys[0], 10);
+        const resp = responses[twoxxKeys[0]];
+        const isVoid = isRef(resp)
+            ? false
+            : (() => {
+                const r = resp;
+                const content = r.content;
+                return content === undefined || Object.keys(content).length === 0;
+            })();
+        return { status: code, isVoid, responseContentType: detectResponseContentType(resp) };
     }
     // Default: delete -> 204, otherwise 200
-    return httpMethod === 'delete' ? { status: 204, isVoid: true } : { status: 200, isVoid: false };
+    return httpMethod === 'delete'
+        ? { status: 204, isVoid: true, responseContentType: 'application/json' }
+        : { status: 200, isVoid: false, responseContentType: 'application/json' };
 }
 function collectOperations(spec) {
     const paths = spec.paths;
@@ -445,12 +476,16 @@ function collectOperations(spec) {
     }
     return operations;
 }
-/** Collect sorted body type names from all operations. */
+/** Collect sorted body type names from all operations.
+ * Synthesized names (inline schema, no $ref) are excluded because they have no
+ * corresponding entry in models.ts and must not appear in the model import.
+ */
 function collectSortedBodyTypes(operations) {
     const bodyTypes = new Set();
     for (const op of operations) {
-        if (op.bodyInfo?.typeName !== undefined)
+        if (op.bodyInfo?.typeName !== undefined && !op.bodyInfo.isSynthesized) {
             bodyTypes.add(op.bodyInfo.typeName);
+        }
     }
     return Array.from(bodyTypes).sort();
 }
@@ -494,8 +529,30 @@ function buildRouteHandler(op, indent, schemaNames) {
     }
     // Query params extraction
     if (op.queryParams.length > 0) {
+        // Emit deepObject assembly blocks before the params object.
+        // c.req.queries() returns Record<string, string[]> with raw bracket-notation keys.
+        const deepObjectParams = op.queryParams.filter((q) => q.isDeepObject === true);
+        if (deepObjectParams.length > 0) {
+            lines.push(`${indent}  const _dq = c.req.queries()`);
+            for (const q of deepObjectParams) {
+                const prefixLen = q.rawName.length + 1; // e.g. 'filter['.length
+                const bracketPrefix = q.rawName + '[';
+                lines.push(`${indent}  const ${q.name} = Object.fromEntries(`);
+                lines.push(`${indent}    Object.entries(_dq).filter(([k]) => k.startsWith('${bracketPrefix}') && k.endsWith(']')).map(([k, vs]) => [k.slice(${prefixLen}, -1), vs[0]])`);
+                lines.push(`${indent}  )`);
+            }
+        }
         const fields = op.queryParams
             .map((q) => {
+            if (q.isDeepObject === true) {
+                // Already assembled above as a local variable
+                return `    ${q.name}`;
+            }
+            if (q.delimiterStyle !== undefined) {
+                // Use rawName to match the actual URL query key (e.g. 'csv', 'ssv', 'psv').
+                const delim = JSON.stringify(delimiterChar(q.delimiterStyle));
+                return `    ${q.name}: c.req.query('${q.rawName}') !== undefined ? c.req.query('${q.rawName}')!.split(${delim}) : undefined`;
+            }
             if (q.tsType === 'number') {
                 return `    ${q.name}: c.req.query('${q.name}') !== undefined ? Number(c.req.query('${q.name}')) : undefined`;
             }
@@ -523,8 +580,43 @@ function buildRouteHandler(op, indent, schemaNames) {
     // Body extraction
     let bodyVarName = 'body';
     if (op.bodyInfo !== undefined) {
-        const typeAnnotation = op.bodyInfo.typeName !== undefined ? `<${op.bodyInfo.typeName}>` : '';
-        lines.push(`${indent}  const body = await c.req.json${typeAnnotation}()`);
+        // Synthesized names (inline schemas) are schema-only; the TS type is unknown.
+        const typeDecl = op.bodyInfo.typeName !== undefined && !op.bodyInfo.isSynthesized
+            ? op.bodyInfo.typeName
+            : 'unknown';
+        if (op.bodyInfo.contentType === 'application/x-www-form-urlencoded') {
+            // Form-urlencoded: check Content-Type then decode with parseBody().
+            // Values arrive as strings; Zod coercion handles type conversion (e.g. z.coerce.number()).
+            lines.push(`${indent}  const _ct = c.req.header('content-type') ?? ''`);
+            lines.push(`${indent}  if (!_ct.toLowerCase().startsWith('application/x-www-form-urlencoded')) {`);
+            lines.push(`${indent}    return c.json({ error: 'Unsupported Media Type' }, 415)`);
+            lines.push(`${indent}  }`);
+            lines.push(`${indent}  const body: unknown = await c.req.parseBody()`);
+        }
+        else if (op.bodyInfo.contentType === 'multipart/form-data') {
+            // Multipart: decode with parseBody({ all: true }) so repeated file fields arrive as arrays.
+            // File fields are web-standard File objects; text fields are strings.
+            // No manual Content-Type check needed: parseBody handles multipart natively in Hono.
+            lines.push(`${indent}  // multipart/form-data: parseBody({ all: true }) collects repeated keys into arrays.`);
+            lines.push(`${indent}  const body: unknown = await c.req.parseBody({ all: true })`);
+        }
+        else {
+            // JSON body: check Content-Type then parse with JSON.parse (not c.req.json()).
+            // c.req.text() + JSON.parse() is used instead of c.req.json() because Hono's
+            // c.req.json() silently returns null for an empty body instead of throwing,
+            // which would pass the try/catch and reach Zod as null, causing a 422 rather
+            // than the correct 400. JSON.parse('') always throws SyntaxError.
+            lines.push(`${indent}  const _ct = c.req.header('content-type') ?? ''`);
+            lines.push(`${indent}  if (!_ct.toLowerCase().startsWith('application/json')) {`);
+            lines.push(`${indent}    return c.json({ error: 'Unsupported Media Type' }, 415)`);
+            lines.push(`${indent}  }`);
+            lines.push(`${indent}  let body: ${typeDecl}`);
+            lines.push(`${indent}  try {`);
+            lines.push(`${indent}    body = JSON.parse(await c.req.text()) as ${typeDecl}`);
+            lines.push(`${indent}  } catch {`);
+            lines.push(`${indent}    return c.json({ error: 'Invalid JSON body' }, 400)`);
+            lines.push(`${indent}  }`);
+        }
         // Zod validation when schema is available
         const schemaName = op.bodyInfo.typeName !== undefined ? `${op.bodyInfo.typeName}Schema` : undefined;
         if (schemaName !== undefined && schemaNames !== undefined && schemaNames.has(schemaName)) {
@@ -549,17 +641,47 @@ function buildRouteHandler(op, indent, schemaNames) {
         serviceArgs.push('params');
     }
     const serviceCall = `service.${op.methodName}(${serviceArgs.join(', ')})`;
-    // Response
+    // Response — wrap in try/catch to map HttpError to its status
+    lines.push(`${indent}  try {`);
     if (op.responseStatus.isVoid) {
-        lines.push(`${indent}  await ${serviceCall}`);
-        lines.push(`${indent}  return new Response(null, { status: ${op.responseStatus.status} })`);
+        lines.push(`${indent}    await ${serviceCall}`);
+        lines.push(`${indent}    return new Response(null, { status: ${op.responseStatus.status} })`);
+    }
+    else if (op.responseStatus.isMultiStatus === true) {
+        // Multi-status: service returns { status: number; body: T }; router forwards both.
+        lines.push(`${indent}    const _envelope = await ${serviceCall}`);
+        lines.push(`${indent}    return c.json(_envelope.body, _envelope.status as any)`);
+    }
+    else if (op.responseStatus.responseContentType === 'text/plain') {
+        if (op.responseStatus.status === 200) {
+            lines.push(`${indent}    return c.text(await ${serviceCall})`);
+        }
+        else {
+            lines.push(`${indent}    return c.text(await ${serviceCall}, ${op.responseStatus.status})`);
+        }
+    }
+    else if (op.responseStatus.responseContentType === 'application/octet-stream') {
+        if (op.responseStatus.status === 200) {
+            lines.push(`${indent}    const _result = await ${serviceCall}`);
+            lines.push(`${indent}    return new Response(_result, { headers: { 'content-type': 'application/octet-stream' } })`);
+        }
+        else {
+            lines.push(`${indent}    const _result = await ${serviceCall}`);
+            lines.push(`${indent}    return new Response(_result, { status: ${op.responseStatus.status}, headers: { 'content-type': 'application/octet-stream' } })`);
+        }
     }
-    else if (op.responseStatus.status === 201) {
-        lines.push(`${indent}  return c.json(await ${serviceCall}, 201)`);
+    else if (op.responseStatus.status === 200) {
+        lines.push(`${indent}    return c.json(await ${serviceCall})`);
     }
     else {
-        lines.push(`${indent}  return c.json(await ${serviceCall})`);
+        lines.push(`${indent}    return c.json(await ${serviceCall}, ${op.responseStatus.status})`);
     }
+    lines.push(`${indent}  } catch (err) {`);
+    lines.push(`${indent}    if (err instanceof HttpError) {`);
+    lines.push(`${indent}      return new Response(JSON.stringify({ error: err.message }), { status: err.status, headers: { 'content-type': 'application/json' } })`);
+    lines.push(`${indent}    }`);
+    lines.push(`${indent}    throw err`);
+    lines.push(`${indent}  }`);
     lines.push(`${indent}})`);
     return lines.join('\n');
 }
@@ -577,8 +699,19 @@ function buildExpressRouteHandler(op, indent, schemaNames) {
     }
     // Query params extraction
     if (op.queryParams.length > 0) {
+        // Express (qs, extended:true) parses bracket-notation automatically:
+        // filter[gte]=10 → req.query.filter = { gte: '10' }.
+        // DeepObject params are already assembled; just cast the nested object.
         const fields = op.queryParams
             .map((q) => {
+            if (q.isDeepObject === true) {
+                // Express with qs: req.query['filter'] is already { gte: '10', lte: '20' }
+                return `    ${q.name}: (req.query['${q.rawName}'] ?? {}) as Record<string, string | undefined>`;
+            }
+            if (q.delimiterStyle !== undefined) {
+                const delim = JSON.stringify(delimiterChar(q.delimiterStyle));
+                return `    ${q.name}: typeof req.query['${q.rawName}'] === 'string' ? (req.query['${q.rawName}'] as string).split(${delim}) : undefined`;
+            }
             if (q.tsType === 'number') {
                 return `    ${q.name}: Number(req.query['${q.name}'] as string)`;
             }
@@ -606,23 +739,38 @@ 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}  }`);
     }
-    // Body extraction, with optional Zod validation
+    // 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.
+    // For multipart/form-data: assumes multer (or equivalent) middleware is applied before this
+    // router, populating req.files and req.body with the parsed multipart fields.
     let bodyVarName = 'body';
     if (op.bodyInfo !== undefined) {
-        const schemaName = op.bodyInfo.typeName !== undefined ? `${op.bodyInfo.typeName}Schema` : undefined;
-        const useZod = schemaName !== undefined && schemaNames !== undefined && schemaNames.has(schemaName);
-        if (useZod) {
-            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 void res.status(422).json({ error: 'Invalid request body', issues: parseResult.error.issues })`);
-            lines.push(`${indent}  }`);
-            lines.push(`${indent}  const validatedBody = parseResult.data`);
-            bodyVarName = 'validatedBody';
+        if (op.bodyInfo.contentType === 'multipart/form-data') {
+            // Multipart assumption: multer middleware populates req.files (file fields) and
+            // req.body (text fields) before this handler runs. Merge them for service consumption.
+            lines.push(`${indent}  // multipart/form-data: assumes multer middleware has populated req.files + req.body.`);
+            lines.push(`${indent}  const body = { ...req.body, ...(req as any).files } as unknown`);
         }
         else {
-            const typeAnnotation = op.bodyInfo.typeName !== undefined ? ` as ${op.bodyInfo.typeName}` : '';
-            lines.push(`${indent}  const body = req.body${typeAnnotation}`);
+            const schemaName = op.bodyInfo.typeName !== undefined ? `${op.bodyInfo.typeName}Schema` : undefined;
+            const useZod = schemaName !== undefined && schemaNames !== undefined && schemaNames.has(schemaName);
+            if (useZod) {
+                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 void res.status(422).json({ error: 'Invalid request body', issues: parseResult.error.issues })`);
+                lines.push(`${indent}  }`);
+                lines.push(`${indent}  const validatedBody = parseResult.data`);
+                bodyVarName = 'validatedBody';
+            }
+            else {
+                // Synthesized names (inline schemas) have no model type — use plain cast to unknown.
+                const typeAnnotation = op.bodyInfo.typeName !== undefined && !op.bodyInfo.isSynthesized
+                    ? ` as ${op.bodyInfo.typeName}`
+                    : '';
+                lines.push(`${indent}  const body = req.body${typeAnnotation}`);
+            }
         }
     }
     // Build service call args
@@ -637,17 +785,45 @@ function buildExpressRouteHandler(op, indent, schemaNames) {
         serviceArgs.push('params');
     }
     const serviceCall = `service.${op.methodName}(${serviceArgs.join(', ')})`;
-    // Response
+    // Response — wrap in try/catch to map HttpError to its status
+    lines.push(`${indent}  try {`);
     if (op.responseStatus.isVoid) {
-        lines.push(`${indent}  await ${serviceCall}`);
-        lines.push(`${indent}  res.status(${op.responseStatus.status}).end()`);
+        lines.push(`${indent}    await ${serviceCall}`);
+        lines.push(`${indent}    res.status(${op.responseStatus.status}).end()`);
     }
-    else if (op.responseStatus.status === 201) {
-        lines.push(`${indent}  res.status(201).json(await ${serviceCall})`);
+    else if (op.responseStatus.isMultiStatus === true) {
+        // Multi-status: service returns { status: number; body: T }; router forwards both.
+        lines.push(`${indent}    const _envelope = await ${serviceCall}`);
+        lines.push(`${indent}    res.status(_envelope.status).json(_envelope.body)`);
+    }
+    else if (op.responseStatus.responseContentType === 'text/plain') {
+        if (op.responseStatus.status === 200) {
+            lines.push(`${indent}    res.type('text/plain').send(await ${serviceCall})`);
+        }
+        else {
+            lines.push(`${indent}    res.status(${op.responseStatus.status}).type('text/plain').send(await ${serviceCall})`);
+        }
+    }
+    else if (op.responseStatus.responseContentType === 'application/octet-stream') {
+        if (op.responseStatus.status === 200) {
+            lines.push(`${indent}    res.setHeader('Content-Type', 'application/octet-stream').send(Buffer.from(await ${serviceCall}))`);
+        }
+        else {
+            lines.push(`${indent}    res.status(${op.responseStatus.status}).setHeader('Content-Type', 'application/octet-stream').send(Buffer.from(await ${serviceCall}))`);
+        }
+    }
+    else if (op.responseStatus.status === 200) {
+        lines.push(`${indent}    res.json(await ${serviceCall})`);
     }
     else {
-        lines.push(`${indent}  res.json(await ${serviceCall})`);
+        lines.push(`${indent}    res.status(${op.responseStatus.status}).json(await ${serviceCall})`);
     }
+    lines.push(`${indent}  } catch (err) {`);
+    lines.push(`${indent}    if (err instanceof HttpError) {`);
+    lines.push(`${indent}      return void res.status(err.status).json({ error: err.message })`);
+    lines.push(`${indent}    }`);
+    lines.push(`${indent}    throw err`);
+    lines.push(`${indent}  }`);
     lines.push(`${indent}})`);
     return lines.join('\n');
 }
@@ -658,18 +834,30 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
     // Build generic type argument
     const genericParts = [];
     if (op.queryParams.length > 0) {
-        const queryFields = op.queryParams
-            .map((q) => {
-            if (q.tsType === 'number')
-                return `${q.name}?: number`;
-            if (q.tsType === 'boolean')
-                return `${q.name}?: boolean`;
-            return `${q.name}?: string`;
-        })
-            .join('; ');
-        genericParts.push(`Querystring: { ${queryFields} }`);
+        // DeepObject and delimited params use bracket-notation keys or raw strings;
+        // include them as Record<string, string> or string[] in the Querystring generic.
+        const hasDeepOrDelimited = op.queryParams.some((q) => q.isDeepObject === true || q.delimiterStyle !== undefined);
+        let querystringType;
+        if (hasDeepOrDelimited) {
+            // Use a loose Querystring type that allows bracket-notation keys (fast-querystring stores
+            // them as literal strings, e.g. 'filter[gte]') and array values for delimited params.
+            querystringType = 'Record<string, string | string[] | undefined>';
+        }
+        else {
+            const queryFields = op.queryParams
+                .map((q) => {
+                if (q.tsType === 'number')
+                    return `${q.name}?: number`;
+                if (q.tsType === 'boolean')
+                    return `${q.name}?: boolean`;
+                return `${q.name}?: string`;
+            })
+                .join('; ');
+            querystringType = `{ ${queryFields} }`;
+        }
+        genericParts.push(`Querystring: ${querystringType}`);
     }
-    if (op.bodyInfo !== undefined && op.bodyInfo.typeName !== undefined) {
+    if (op.bodyInfo !== undefined && op.bodyInfo.typeName !== undefined && !op.bodyInfo.isSynthesized) {
         genericParts.push(`Body: ${op.bodyInfo.typeName}`);
     }
     else if (op.bodyInfo !== undefined) {
@@ -693,7 +881,39 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
     }
     // Query params extraction
     if (op.queryParams.length > 0) {
-        const fields = op.queryParams.map((q) => `    ${q.name}: req.query.${q.name}`).join(',\n');
+        // fast-querystring (Fastify default) stores bracket-notation keys as literals:
+        // filter[gte]=10 → req.query['filter[gte]'] = '10'.
+        // DeepObject and delimited params need raw string access; emit _dq cast once.
+        const deepObjectParams = op.queryParams.filter((q) => q.isDeepObject === true);
+        const hasDeepOrDelimited = op.queryParams.some((q) => q.isDeepObject === true || q.delimiterStyle !== undefined);
+        if (hasDeepOrDelimited) {
+            lines.push(`${indent}  const _dq = req.query as unknown as Record<string, string | undefined>`);
+        }
+        if (deepObjectParams.length > 0) {
+            for (const q of deepObjectParams) {
+                const prefixLen = q.rawName.length + 1; // e.g. 'filter['.length
+                const bracketPrefix = q.rawName + '[';
+                lines.push(`${indent}  const ${q.name} = Object.fromEntries(`);
+                lines.push(`${indent}    Object.entries(_dq).filter(([k]) => k.startsWith('${bracketPrefix}') && k.endsWith(']')).map(([k, v]) => [k.slice(${prefixLen}, -1), v])`);
+                lines.push(`${indent}  )`);
+            }
+        }
+        const fields = op.queryParams
+            .map((q) => {
+            if (q.isDeepObject === true) {
+                // Already assembled above as a local variable
+                return `    ${q.name}`;
+            }
+            if (q.delimiterStyle !== undefined) {
+                const delim = JSON.stringify(delimiterChar(q.delimiterStyle));
+                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.
+            return hasDeepOrDelimited
+                ? `    ${q.name}: _dq['${q.rawName}']`
+                : `    ${q.name}: req.query.${q.name}`;
+        })
+            .join(',\n');
         lines.push(`${indent}  const params = {`);
         lines.push(fields);
         lines.push(`${indent}  }`);
@@ -718,18 +938,29 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
         lines.push(`${indent}    })`);
         lines.push(`${indent}  }`);
     }
-    // Body handling, with optional Zod validation
+    // 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.
     let bodyVarName = 'req.body';
     if (op.bodyInfo !== undefined) {
-        const schemaName = op.bodyInfo.typeName !== undefined ? `${op.bodyInfo.typeName}Schema` : undefined;
-        const useZod = schemaName !== undefined && schemaNames !== undefined && schemaNames.has(schemaName);
-        if (useZod) {
-            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}  }`);
-            bodyVarName = 'parseResult.data';
+        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.`);
+            // bodyVarName stays 'req.body'
+        }
+        else {
+            const schemaName = op.bodyInfo.typeName !== undefined ? `${op.bodyInfo.typeName}Schema` : undefined;
+            const useZod = schemaName !== undefined && schemaNames !== undefined && schemaNames.has(schemaName);
+            if (useZod) {
+                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}  }`);
+                bodyVarName = 'parseResult.data';
+            }
         }
     }
     // Build service call args
@@ -744,21 +975,65 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
         serviceArgs.push('params');
     }
     const serviceCall = `service.${op.methodName}(${serviceArgs.join(', ')})`;
-    // Response
+    // Response — wrap in try/catch to map HttpError to its status
+    lines.push(`${indent}  try {`);
     if (op.responseStatus.isVoid) {
-        lines.push(`${indent}  await ${serviceCall}`);
-        lines.push(`${indent}  reply.status(${op.responseStatus.status}).send()`);
+        lines.push(`${indent}    await ${serviceCall}`);
+        lines.push(`${indent}    reply.status(${op.responseStatus.status}).send()`);
+    }
+    else if (op.responseStatus.isMultiStatus === true) {
+        // Multi-status: service returns { status: number; body: T }; router forwards both.
+        lines.push(`${indent}    const _envelope = await ${serviceCall}`);
+        lines.push(`${indent}    return reply.status(_envelope.status).send(_envelope.body)`);
     }
-    else if (op.responseStatus.status === 201) {
-        lines.push(`${indent}  reply.status(201)`);
-        lines.push(`${indent}  return ${serviceCall}`);
+    else if (op.responseStatus.responseContentType === 'text/plain') {
+        if (op.responseStatus.status === 200) {
+            lines.push(`${indent}    return reply.type('text/plain').send(await ${serviceCall})`);
+        }
+        else {
+            lines.push(`${indent}    return reply.status(${op.responseStatus.status}).type('text/plain').send(await ${serviceCall})`);
+        }
+    }
+    else if (op.responseStatus.responseContentType === 'application/octet-stream') {
+        if (op.responseStatus.status === 200) {
+            lines.push(`${indent}    return reply.type('application/octet-stream').send(Buffer.from(await ${serviceCall}))`);
+        }
+        else {
+            lines.push(`${indent}    return reply.status(${op.responseStatus.status}).type('application/octet-stream').send(Buffer.from(await ${serviceCall}))`);
+        }
+    }
+    else if (op.responseStatus.status === 200) {
+        lines.push(`${indent}    return ${serviceCall}`);
     }
     else {
-        lines.push(`${indent}  return ${serviceCall}`);
+        lines.push(`${indent}    reply.status(${op.responseStatus.status})`);
+        lines.push(`${indent}    return ${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}    }`);
+    lines.push(`${indent}    throw err`);
+    lines.push(`${indent}  }`);
     lines.push(`${indent}})`);
     return lines.join('\n');
 }
+// ── HttpError class ───────────────────────────────────────────────────────────
+/**
+ * Lines that emit the exported HttpError class into a generated router file.
+ * Services throw `new HttpError(404, 'Not found')` and the generated router
+ * catches it, returning the matching HTTP status instead of a generic 500.
+ */
+function httpErrorClassLines() {
+    return [
+        'export class HttpError extends Error {',
+        '  constructor(public readonly status: number, message: string) {',
+        '    super(message)',
+        "    this.name = 'HttpError'",
+        '  }',
+        '}',
+    ];
+}
 // ── Zod import helpers ────────────────────────────────────────────────────────
 /**
  * Returns true when any operation in the list generates param validation code
@@ -799,6 +1074,9 @@ export function generateExpressRouter(spec, options) {
         lines.push(`import { ${sortedUsedSchemas.join(', ')} } from '${options.schemaImportPath}'`);
     }
     lines.push('');
+    for (const l of httpErrorClassLines())
+        lines.push(l);
+    lines.push('');
     lines.push(`export function createRouter(service: ${serviceName}): Router {`);
     lines.push('  const router = Router()');
     lines.push('');
@@ -836,6 +1114,9 @@ export function generateFastifyRouter(spec, options) {
         lines.push(`import { ${sortedUsedSchemas.join(', ')} } from '${options.schemaImportPath}'`);
     }
     lines.push('');
+    for (const l of httpErrorClassLines())
+        lines.push(l);
+    lines.push('');
     lines.push(`export function createRouter(app: FastifyInstance, service: ${serviceName}): void {`);
     for (const op of operations) {
         lines.push('');
@@ -870,6 +1151,9 @@ export function generateRouter(spec, options) {
         lines.push(`import { ${sortedUsedSchemas.join(', ')} } from '${options.schemaImportPath}'`);
     }
     lines.push('');
+    for (const l of httpErrorClassLines())
+        lines.push(l);
+    lines.push('');
     lines.push(`export function createRouter(service: ${serviceName}): Hono {`);
     lines.push('  const app = new Hono()');
     lines.push('');