@contractkit/plugin-typescript 0.30.0 → 0.31.0

package/dist/index.js

@@ -1105,7 +1105,7 @@ function pascalToDotCase(name) {
 __name(pascalToDotCase, "pascalToDotCase");
 
 // src/codegen-operation.ts
-import { resolveModifiers, resolveSecurity, SECURITY_NONE, classifyContentType } from "@contractkit/core";
+import { resolveModifiers, resolveSecurity, SECURITY_NONE, classifyContentType, emittedResponses } from "@contractkit/core";
 import { basename, dirname as dirname2, relative as relative2 } from "path";
 function bodyParserToken(contentType) {
   switch (classifyContentType(contentType)) {
@@ -1182,20 +1182,6 @@ function generateOp(root, options = {}) {
   const types = collectTypes(root, options.modelsWithInput, options.modelsWithOutput);
   const services = collectServices(root);
   const routerName = deriveRouterName(root.file);
-  const helpers = [];
-  if (opNeedsScalar(root, "binary")) {
-    helpers.push(`const _ZodBinary = z.custom<Buffer>((val) => Buffer.isBuffer(val), { error: 'Must be binary data' });`);
-  }
-  if (opNeedsScalar(root, "datetime")) {
-    helpers.push(`const _ZodDatetime = z.preprocess((val) => typeof val === 'string' ? DateTime.fromISO(val) : val, z.custom<DateTime>((val) => val instanceof DateTime && val.isValid, { message: 'Must be in ISO 8601 format' }));`);
-  }
-  if (opNeedsScalar(root, "interval")) {
-    helpers.push(`const _ZodInterval = z.preprocess((val) => typeof val === 'string' ? Interval.fromISO(val) : val, z.custom<Interval>((val) => val instanceof Interval && val.isValid, { message: 'Must be an ISO 8601 interval' })).transform(val => val.toISO()!);`);
-  }
-  if (opNeedsScalar(root, "json")) {
-    helpers.push(`type _JsonValue = string | number | boolean | null | _JsonValue[] | { [key: string]: _JsonValue };`);
-    helpers.push(`const _ZodJson: z.ZodType<_JsonValue> = z.lazy(() => z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(_ZodJson), z.record(z.string(), _ZodJson)]));`);
-  }
   const lines = [];
   lines.push("");
   lines.push("/**");
@@ -1212,6 +1198,25 @@ function generateOp(root, options = {}) {
       lines.push("");
     }
   }
+  const handlerBody = lines.join("\n");
+  const references = /* @__PURE__ */ __name((symbol) => new RegExp(`\\b${symbol}\\b`).test(handlerBody), "references");
+  const helpers = [];
+  if (references("_ZodBinary")) {
+    helpers.push(`const _ZodBinary = z.custom<Buffer>((val) => Buffer.isBuffer(val), { error: 'Must be binary data' });`);
+  }
+  if (references("_ZodDatetime")) {
+    helpers.push(`const _ZodDatetime = z.preprocess((val) => typeof val === 'string' ? DateTime.fromISO(val) : val, z.custom<DateTime>((val) => val instanceof DateTime && val.isValid, { message: 'Must be in ISO 8601 format' }));`);
+  }
+  if (references("_ZodInterval")) {
+    helpers.push(`const _ZodInterval = z.preprocess((val) => typeof val === 'string' ? Interval.fromISO(val) : val, z.custom<Interval>((val) => val instanceof Interval && val.isValid, { message: 'Must be an ISO 8601 interval' })).transform(val => val.toISO()!);`);
+  }
+  const needsZodJson = references("_ZodJson");
+  if (needsZodJson || references("_JsonValue")) {
+    helpers.push(`type _JsonValue = string | number | boolean | null | _JsonValue[] | { [key: string]: _JsonValue };`);
+  }
+  if (needsZodJson) {
+    helpers.push(`const _ZodJson: z.ZodType<_JsonValue> = z.lazy(() => z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(_ZodJson), z.record(z.string(), _ZodJson)]));`);
+  }
   const generated = [
     ...helpers.length ? [
       "",
@@ -1336,50 +1341,161 @@ function generateHandler(route, op, root, options) {
       lines.push("");
     }
   }
-  const primaryResponse2 = op.responses.find((r) => r.bodyType) ?? op.responses[0];
+  const emitted = emittedResponses(op);
   const serviceParts = inferService(op, route, file);
-  const respHeaders = primaryResponse2?.headers ?? [];
+  const call = `await service.${serviceParts.methodName}(${buildArgs(route, op)})`;
+  if (emitted.length > 1) {
+    lines.push(...generateMultiStatusResult(emitted, serviceParts.className, call, options));
+  } else {
+    lines.push(...generateSingleStatusResult(emitted[0], op, serviceParts.className, call, options));
+  }
+  lines.push(`});`);
+  return lines;
+}
+__name(generateHandler, "generateHandler");
+function generateSingleStatusResult(resp, op, className, call, options) {
+  const lines = [];
+  const bodies = resp ? resp.bodies : [];
+  const respHeaders = resp?.headers ?? [];
   const hasRespHeaders = respHeaders.length > 0;
-  const headersAnnotation = hasRespHeaders ? `{ ${respHeaders.map((h) => `${quoteKey(headerNameToProperty(h.name))}${h.optional ? "?" : ""}: ${renderOutputTsType(h.type, options.modelsWithOutput, "server")}`).join("; ")} }` : "";
-  if (primaryResponse2?.bodyType) {
-    const { annotation, prelude } = formatTypeAnnotation(primaryResponse2.bodyType, options.modelsWithOutput);
-    if (prelude) {
-      lines.push(`    ${prelude}`);
-    }
-    lines.push(`    const service = ctx.container.get(${serviceParts.className});`);
+  const headersAnnotation = hasRespHeaders ? renderHeadersAnnotation(respHeaders, options.modelsWithOutput) : "";
+  if (bodies.length === 1) {
+    const { annotation, prelude } = formatTypeAnnotation(bodies[0].bodyType, options.modelsWithOutput);
+    if (prelude) lines.push(`    ${prelude}`);
+    lines.push(`    const service = ctx.container.get(${className});`);
     if (hasRespHeaders) {
-      lines.push(`    const result: { body: ${annotation}; headers: ${headersAnnotation} } = await service.${serviceParts.methodName}(${buildArgs(route, op)});`);
+      lines.push(`    const result: { body: ${annotation}; headers: ${headersAnnotation} } = ${call};`);
     } else {
-      lines.push(`    const result: ${annotation} = await service.${serviceParts.methodName}(${buildArgs(route, op)});`);
+      lines.push(`    const result: ${annotation} = ${call};`);
     }
+  } else if (bodies.length > 1) {
+    const { members, preludes } = renderResponseMembers(resp, options, {
+      includeStatus: false,
+      varPrefix: "result"
+    });
+    for (const prelude of preludes) lines.push(`    ${prelude}`);
+    lines.push(`    const service = ctx.container.get(${className});`);
+    lines.push(`    const result: ${members.join(" | ")} = ${call};`);
   } else {
-    lines.push(`    const service = ctx.container.get(${serviceParts.className});`);
+    lines.push(`    const service = ctx.container.get(${className});`);
     if (hasRespHeaders) {
-      lines.push(`    const result: { headers: ${headersAnnotation} } = await service.${serviceParts.methodName}(${buildArgs(route, op)});`);
+      lines.push(`    const result: { headers: ${headersAnnotation} } = ${call};`);
     } else {
-      lines.push(`    await service.${serviceParts.methodName}(${buildArgs(route, op)});`);
+      lines.push(`    ${call};`);
     }
   }
   lines.push("");
-  lines.push(`    ctx.status = ${primaryResponse2?.statusCode ?? 200};`);
-  if (hasRespHeaders) {
-    for (const h of respHeaders) {
-      const accessor = `result.headers[${JSON.stringify(headerNameToProperty(h.name))}]`;
-      if (h.optional) {
-        lines.push(`    if (${accessor} !== undefined) ctx.set('${h.name}', String(${accessor}));`);
-      } else {
-        lines.push(`    ctx.set('${h.name}', String(${accessor}));`);
-      }
-    }
-  }
-  if (primaryResponse2?.bodyType && primaryResponse2.contentType) {
-    lines.push(`    ctx.type = '${primaryResponse2.contentType}';`);
+  lines.push(`    ctx.status = ${resp?.statusCode ?? op.responses[0]?.statusCode ?? 200};`);
+  lines.push(...headerSetLines(respHeaders, "    "));
+  if (bodies.length === 1) {
+    lines.push(`    ctx.type = '${bodies[0].contentType}';`);
     lines.push(`    ctx.body = ${hasRespHeaders ? "result.body" : "result"};`);
+  } else if (bodies.length > 1) {
+    lines.push(`    ctx.type = result.contentType;`);
+    lines.push(`    ctx.body = result.body;`);
   }
-  lines.push(`});`);
   return lines;
 }
-__name(generateHandler, "generateHandler");
+__name(generateSingleStatusResult, "generateSingleStatusResult");
+function generateMultiStatusResult(emitted, className, call, options) {
+  const lines = [];
+  const members = [];
+  const preludes = [];
+  for (const resp of emitted) {
+    const rendered = renderResponseMembers(resp, options, {
+      includeStatus: true,
+      varPrefix: `result${resp.statusCode}`
+    });
+    members.push(...rendered.members);
+    preludes.push(...rendered.preludes);
+  }
+  for (const prelude of preludes) lines.push(`    ${prelude}`);
+  lines.push(`    const service = ctx.container.get(${className});`);
+  lines.push(`    const result:`);
+  for (const member of members) lines.push(`        | ${member}`);
+  lines.push(`        = ${call};`);
+  lines.push("");
+  lines.push(`    ctx.status = result.status;`);
+  lines.push(`    switch (result.status) {`);
+  for (const resp of emitted) {
+    lines.push(`        case ${resp.statusCode}:`);
+    lines.push(...headerSetLines(resp.headers ?? [], "            "));
+    if (resp.bodies.length > 0) {
+      lines.push(`            ctx.type = result.contentType;`);
+      lines.push(`            ctx.body = result.body;`);
+    }
+    lines.push(`            break;`);
+  }
+  lines.push(`    }`);
+  return lines;
+}
+__name(generateMultiStatusResult, "generateMultiStatusResult");
+function renderResponseMembers(resp, options, opts) {
+  const bodies = resp.bodies;
+  const headers = resp.headers ?? [];
+  const leading = opts.includeStatus ? [
+    `status: ${resp.statusCode}`
+  ] : [];
+  const trailing = headers.length > 0 ? [
+    `headers: ${renderHeadersAnnotation(headers, options.modelsWithOutput)}`
+  ] : [];
+  const preludes = [];
+  if (bodies.length === 0) {
+    return {
+      members: [
+        `{ ${[
+          ...leading,
+          ...trailing
+        ].join("; ")} }`
+      ],
+      preludes
+    };
+  }
+  const uniform = bodies.every((b) => bodyTypesStructurallyEqual(b.bodyType, bodies[0].bodyType));
+  if (uniform) {
+    const { annotation, prelude } = formatTypeAnnotation(bodies[0].bodyType, options.modelsWithOutput, `${opts.varPrefix}Type`);
+    if (prelude) preludes.push(prelude);
+    const contentType = bodies.map((b) => `'${b.contentType}'`).join(" | ");
+    return {
+      members: [
+        `{ ${[
+          ...leading,
+          `contentType: ${contentType}`,
+          `body: ${annotation}`,
+          ...trailing
+        ].join("; ")} }`
+      ],
+      preludes
+    };
+  }
+  const members = bodies.map((b, i) => {
+    const { annotation, prelude } = formatTypeAnnotation(b.bodyType, options.modelsWithOutput, `${opts.varPrefix}Type${i}`);
+    if (prelude) preludes.push(prelude);
+    return `{ ${[
+      ...leading,
+      `contentType: '${b.contentType}'`,
+      `body: ${annotation}`,
+      ...trailing
+    ].join("; ")} }`;
+  });
+  return {
+    members,
+    preludes
+  };
+}
+__name(renderResponseMembers, "renderResponseMembers");
+function renderHeadersAnnotation(headers, modelsWithOutput) {
+  const fields = headers.map((h) => `${quoteKey(headerNameToProperty(h.name))}${h.optional ? "?" : ""}: ${renderOutputTsType(h.type, modelsWithOutput, "server")}`);
+  return `{ ${fields.join("; ")} }`;
+}
+__name(renderHeadersAnnotation, "renderHeadersAnnotation");
+function headerSetLines(headers, indent) {
+  return headers.map((h) => {
+    const accessor = `result.headers[${JSON.stringify(headerNameToProperty(h.name))}]`;
+    return h.optional ? `${indent}if (${accessor} !== undefined) ctx.set('${h.name}', String(${accessor}));` : `${indent}ctx.set('${h.name}', String(${accessor}));`;
+  });
+}
+__name(headerSetLines, "headerSetLines");
 function inferService(op, route, file) {
   if (op.service) {
     const [cls = "", method] = op.service.split(".");
@@ -1473,9 +1589,9 @@ function serverTsScalar(name) {
   }
 }
 __name(serverTsScalar, "serverTsScalar");
-function formatTypeAnnotation(bodyType, modelsWithOutput) {
+function formatTypeAnnotation(bodyType, modelsWithOutput, varName = "resultType") {
   if (bodyType.kind === "array") {
-    const inner = formatTypeAnnotation(bodyType.item, modelsWithOutput);
+    const inner = formatTypeAnnotation(bodyType.item, modelsWithOutput, varName);
     return {
       annotation: `${inner.annotation}[]`,
       prelude: inner.prelude
@@ -1492,8 +1608,8 @@ function formatTypeAnnotation(bodyType, modelsWithOutput) {
   };
   const schema = renderType(bodyType);
   return {
-    annotation: "z.infer<typeof resultType>",
-    prelude: `const resultType = ${schema};`
+    annotation: `z.infer<typeof ${varName}>`,
+    prelude: `const ${varName} = ${schema};`
   };
 }
 __name(formatTypeAnnotation, "formatTypeAnnotation");
@@ -1579,9 +1695,9 @@ function collectTypes(root, modelsWithInput, modelsWithOutput) {
         }
       }
       for (const resp of op.responses) {
-        if (resp.bodyType) {
-          collectTypeNodeRefs(resp.bodyType, types);
-          collectOutputTypeNodeRefs(resp.bodyType, types, modelsWithOutput);
+        for (const body of resp.bodies) {
+          collectTypeNodeRefs(body.bodyType, types);
+          collectOutputTypeNodeRefs(body.bodyType, types, modelsWithOutput);
         }
         if (resp.headers) {
           for (const h of resp.headers) {
@@ -1724,17 +1840,6 @@ function collectTypeNodeRefs(type, out) {
   }
 }
 __name(collectTypeNodeRefs, "collectTypeNodeRefs");
-function paramSourceNeedsScalar(source, name) {
-  if (!source) return false;
-  if (source.kind === "ref") return false;
-  if (source.kind === "params") return source.nodes.some((p) => typeNeedsScalar(p.type, name));
-  return typeNeedsScalar(source.node, name);
-}
-__name(paramSourceNeedsScalar, "paramSourceNeedsScalar");
-function opNeedsScalar(root, name) {
-  return root.routes.some((route) => paramSourceNeedsScalar(route.params, name) || route.operations.some((op) => !!op.request?.bodies.some((b) => typeNeedsScalar(b.bodyType, name)) || op.responses.some((r) => r.bodyType && typeNeedsScalar(r.bodyType, name)) || paramSourceNeedsScalar(op.query, name) || paramSourceNeedsScalar(op.headers, name)));
-}
-__name(opNeedsScalar, "opNeedsScalar");
 function collectServices(root) {
   const services = /* @__PURE__ */ new Set();
   const inferredService = `${deriveBaseName(root.file)}Service`;
@@ -1788,7 +1893,7 @@ __name(deriveTypeImportPath, "deriveTypeImportPath");
 import { runIncrementalCodegen, parseIncrementalManifest, emptyIncrementalManifest, serializeIncrementalManifest, hashFingerprint, collectTransitiveModelRefs } from "@contractkit/core";
 
 // src/codegen-sdk.ts
-import { resolveModifiers as resolveModifiers2, isJsonMime, classifyContentType as classifyContentType2 } from "@contractkit/core";
+import { resolveModifiers as resolveModifiers2, isJsonMime, classifyContentType as classifyContentType2, observableResponses, thrownResponses } from "@contractkit/core";
 import { basename as basename2, dirname as dirname3, relative as relative3 } from "path";
 function jsonOrFormSerialize(varName, contentType) {
   if (contentType === "application/x-www-form-urlencoded") {
@@ -1865,16 +1970,17 @@ function generateSdk(root, options = {}) {
     if (sdkNeedsBigIntReplacer(root, includeInternal)) valueImports.push("bigIntReplacer");
     if (sdkNeedsBigIntReviver(root, includeInternal)) valueImports.push("parseJson");
     if (sdkNeedsQueryString(root, includeInternal)) valueImports.push("buildQueryString");
+    if (sdkNeedsReadContentType(root, includeInternal)) valueImports.push("readContentType");
     if (valueImports.length > 0) {
       lines.push(`import { ${valueImports.join(", ")} } from '${rel}';`);
     }
   } else {
     lines.push("");
-    lines.push("export class SdkError extends Error {");
+    lines.push("export class SdkError<TBody = unknown> extends Error {");
     lines.push("    constructor(");
     lines.push("        public readonly status: number,");
     lines.push("        public readonly statusText: string,");
-    lines.push("        public readonly body: unknown,");
+    lines.push("        public readonly body: TBody,");
     lines.push("        public readonly headers: Headers,");
     lines.push("    ) {");
     lines.push("        super(`${status} ${statusText}`);");
@@ -1882,7 +1988,16 @@ function generateSdk(root, options = {}) {
     lines.push("    }");
     lines.push("}");
     lines.push("");
-    lines.push("export type SdkFetch = (url: string, init: RequestInit) => Promise<Response>;");
+    lines.push("export interface SdkRequestInit extends RequestInit {");
+    lines.push("    /**");
+    lines.push("     * Statuses this operation declares as values rather than errors \u2014 a 304 from");
+    lines.push("     * conditional-GET middleware, or an error status the service returns deliberately.");
+    lines.push("     * Anything else at or above 400 still throws SdkError.");
+    lines.push("     */");
+    lines.push("    expectStatuses?: number[];");
+    lines.push("}");
+    lines.push("");
+    lines.push("export type SdkFetch = (url: string, init: SdkRequestInit) => Promise<Response>;");
     lines.push("");
     lines.push("export interface SdkOptions {");
     lines.push("    baseUrl: string;");
@@ -1892,9 +2007,13 @@ function generateSdk(root, options = {}) {
     lines.push("    requestIdFactory?: () => string;");
     lines.push("}");
     lines.push("");
+    lines.push("export function readContentType(res: Response): string {");
+    lines.push("    return res.headers.get('content-type')?.split(';')[0]?.trim() ?? '';");
+    lines.push("}");
+    lines.push("");
     lines.push("export function createSdkFetch(options: SdkOptions): SdkFetch {");
     lines.push("    const getRequestId = options.requestIdFactory ?? (() => crypto.randomUUID());");
-    lines.push("    return async (url: string, init: RequestInit): Promise<Response> => {");
+    lines.push("    return async (url: string, init: SdkRequestInit): Promise<Response> => {");
     lines.push("        const baseHeaders = typeof options.headers === 'function'");
     lines.push("            ? await options.headers()");
     lines.push("            : options.headers ?? {};");
@@ -1902,7 +2021,7 @@ function generateSdk(root, options = {}) {
     lines.push("            ...init,");
     lines.push("            headers: { ...baseHeaders, 'X-Request-ID': getRequestId(), ...init.headers as Record<string, string> },");
     lines.push("        });");
-    lines.push("        if (!res.ok) {");
+    lines.push("        if (!res.ok && !(init.expectStatuses ?? []).includes(res.status)) {");
     lines.push("            const text = await res.text();");
     lines.push("            let body: unknown;");
     lines.push("            try { body = JSON.parse(text); } catch { body = text; }");
@@ -1933,6 +2052,11 @@ function generateSdk(root, options = {}) {
     lines.push(JSON_VALUE_TYPE_DECL);
   }
   lines.push("");
+  const errorAliases = generateErrorBodyAliases(root, options);
+  if (errorAliases.length > 0) {
+    lines.push(...errorAliases);
+    lines.push("");
+  }
   lines.push("/**");
   const relFile = options.outPath ? relative3(dirname3(options.outPath), root.file) : root.file;
   lines.push(` * generated from [${basename2(root.file)}](file://./${relFile})`);
@@ -1980,19 +2104,37 @@ function generateMethod(route, op, file, options) {
   const { modelsWithInput, modelsWithOutput } = options;
   const params = buildMethodParams(route, op, modelsWithInput);
   const paramStr = params.map((p) => `${p.name}${p.optional ? "?" : ""}: ${p.type}`).join(", ");
-  const primaryResponse2 = op.responses.find((r) => r.bodyType) ?? op.responses[0];
-  const isVoid = !primaryResponse2?.bodyType;
-  const respCategory = primaryResponse2?.contentType ? classifyContentType2(primaryResponse2.contentType) : "json";
-  const dataType = isVoid ? "void" : respCategory === "text" ? "string" : respCategory === "binary" ? "Blob" : renderOutputTsType(primaryResponse2.bodyType, modelsWithOutput);
-  const respHeaders = primaryResponse2?.headers ?? [];
+  const observable = observableResponses(op);
+  const thrown = thrownResponses(op);
+  const isMultiStatus = observable.length > 1;
+  const primaryResponse = observable[0];
+  const primaryBodies = primaryResponse ? primaryResponse.bodies : [];
+  const isVoid = primaryBodies.length === 0;
+  const respHeaders = primaryResponse?.headers ?? [];
   const hasRespHeaders = respHeaders.length > 0;
-  const headersShape = hasRespHeaders ? `{ ${respHeaders.map((h) => `${quoteKey(headerNameToProperty(h.name))}${h.optional ? "?" : ""}: ${renderOutputTsType(h.type, modelsWithOutput)}`).join("; ")} }` : "";
-  const returnType = hasRespHeaders ? isVoid ? `{ headers: ${headersShape} }` : `{ data: ${dataType}; headers: ${headersShape} }` : dataType;
+  const headersShape = hasRespHeaders ? renderSdkHeadersShape(respHeaders, modelsWithOutput) : "";
+  let returnMembers;
+  let returnType = "";
+  if (isMultiStatus) {
+    returnMembers = observable.flatMap((r) => sdkResponseMembers(r, modelsWithOutput, true));
+  } else if (primaryBodies.length > 1) {
+    returnMembers = sdkResponseMembers(primaryResponse, modelsWithOutput, false);
+  } else {
+    const dataType = isVoid ? "void" : sdkDataType(primaryBodies[0], modelsWithOutput);
+    returnType = hasRespHeaders ? isVoid ? `{ headers: ${headersShape} }` : `{ data: ${dataType}; headers: ${headersShape} }` : dataType;
+  }
+  if (returnMembers?.length === 1) {
+    returnType = returnMembers[0];
+    returnMembers = void 0;
+  }
+  const expectStatuses = observable.filter((r) => r.statusCode < 200 || r.statusCode >= 300).map((r) => r.statusCode);
   const desc = op.description ?? route.description;
-  if (op.name || desc) {
+  const errorBodyName = thrown.some((r) => r.bodies.length > 0) ? errorBodyTypeName(route, op) : void 0;
+  if (op.name || desc || errorBodyName) {
     const tags = [];
     if (op.name) tags.push(`@name ${op.name}`);
     if (desc) tags.push(`@description ${desc}`);
+    if (errorBodyName) tags.push(`@throws {SdkError<${errorBodyName}>} on ${thrown.map((r) => r.statusCode).join(", ")}`);
     const contentLines = tags.flatMap((t) => escapeJsDocLines(t));
     if (contentLines.length === 1) {
       lines.push(`    /** ${contentLines[0]} */`);
@@ -2002,7 +2144,13 @@ function generateMethod(route, op, file, options) {
       lines.push(`     */`);
     }
   }
-  lines.push(`    async ${methodName}(${paramStr}): Promise<${returnType}> {`);
+  if (returnMembers) {
+    lines.push(`    async ${methodName}(${paramStr}): Promise<`);
+    for (const member of returnMembers) lines.push(`        | ${member}`);
+    lines.push(`    > {`);
+  } else {
+    lines.push(`    async ${methodName}(${paramStr}): Promise<${returnType}> {`);
+  }
   const urlExpr = buildUrlExpression(route.path, route.params);
   const hasQuery = !!op.query;
   let fetchUrl = urlExpr;
@@ -2062,7 +2210,9 @@ function generateMethod(route, op, file, options) {
       fetchArgs.push("headers: customHeaders");
     }
   }
-  const resultPrefix = isVoid && !hasRespHeaders ? "" : "const result = ";
+  if (expectStatuses.length > 0) fetchArgs.push(`expectStatuses: [${expectStatuses.join(", ")}]`);
+  const needsResult = isMultiStatus || !isVoid || hasRespHeaders;
+  const resultPrefix = needsResult ? "const result = " : "";
   if (fetchArgs.length === 2 && !hasBody && !hasOpHeaders && !hasQuery) {
     lines.push(`        ${resultPrefix}await this.fetch(\`${fetchUrl}\`, { method: '${httpMethod}' });`);
   } else {
@@ -2072,22 +2222,185 @@ function generateMethod(route, op, file, options) {
     }
     lines.push(`        });`);
   }
-  const readBodyExpr = respCategory === "text" ? `await result.text()` : respCategory === "binary" ? `await result.blob()` : `await parseJson<${dataType}>(result)`;
-  if (hasRespHeaders) {
-    const headerEntries = respHeaders.map((h) => `${quoteKey(headerNameToProperty(h.name))}: result.headers.get('${h.name}') ?? undefined`).join(", ");
+  if (isMultiStatus) {
+    const [fallback, ...rest] = observable;
+    lines.push(`        switch (result.status) {`);
+    for (const resp of rest) {
+      lines.push(`            case ${resp.statusCode}:`);
+      lines.push(...sdkReturnLines(resp, modelsWithOutput, "                ", true));
+    }
+    lines.push(`            default:`);
+    lines.push(...sdkReturnLines(fallback, modelsWithOutput, "                ", true));
+    lines.push(`        }`);
+  } else if (primaryBodies.length > 1) {
+    lines.push(...sdkReturnLines(primaryResponse, modelsWithOutput, "        ", false));
+  } else if (hasRespHeaders) {
+    const headerEntries = sdkHeaderEntries(respHeaders);
     if (isVoid) {
       lines.push(`        return { headers: { ${headerEntries} } };`);
     } else {
-      lines.push(`        const data = ${readBodyExpr};`);
+      lines.push(`        const data = ${sdkReadExpr(primaryBodies[0], modelsWithOutput)};`);
       lines.push(`        return { data, headers: { ${headerEntries} } };`);
     }
   } else if (!isVoid) {
-    lines.push(`        return ${readBodyExpr};`);
+    lines.push(`        return ${sdkReadExpr(primaryBodies[0], modelsWithOutput)};`);
   }
   lines.push("    }");
   return lines;
 }
 __name(generateMethod, "generateMethod");
+function sdkDataType(body, modelsWithOutput) {
+  const category = classifyContentType2(body.contentType);
+  if (category === "text") return "string";
+  if (category === "binary") return "Blob";
+  return renderOutputTsType(body.bodyType, modelsWithOutput);
+}
+__name(sdkDataType, "sdkDataType");
+function sdkReadExpr(body, modelsWithOutput) {
+  const category = classifyContentType2(body.contentType);
+  if (category === "text") return "await result.text()";
+  if (category === "binary") return "await result.blob()";
+  return `await parseJson<${renderOutputTsType(body.bodyType, modelsWithOutput)}>(result)`;
+}
+__name(sdkReadExpr, "sdkReadExpr");
+function renderSdkHeadersShape(headers, modelsWithOutput) {
+  const fields = headers.map((h) => `${quoteKey(headerNameToProperty(h.name))}${h.optional ? "?" : ""}: ${renderOutputTsType(h.type, modelsWithOutput)}`);
+  return `{ ${fields.join("; ")} }`;
+}
+__name(renderSdkHeadersShape, "renderSdkHeadersShape");
+function sdkHeaderEntries(headers) {
+  return headers.map((h) => `${quoteKey(headerNameToProperty(h.name))}: result.headers.get('${h.name}') ?? undefined`).join(", ");
+}
+__name(sdkHeaderEntries, "sdkHeaderEntries");
+function sdkResponseMembers(resp, modelsWithOutput, includeStatus) {
+  const bodies = resp.bodies;
+  const headers = resp.headers ?? [];
+  const leading = includeStatus ? [
+    `status: ${resp.statusCode}`
+  ] : [];
+  const trailing = headers.length > 0 ? [
+    `headers: ${renderSdkHeadersShape(headers, modelsWithOutput)}`
+  ] : [];
+  if (bodies.length === 0) {
+    return [
+      `{ ${[
+        ...leading,
+        ...trailing
+      ].join("; ")} }`
+    ];
+  }
+  const dataTypes = bodies.map((b) => sdkDataType(b, modelsWithOutput));
+  if (dataTypes.every((t) => t === dataTypes[0])) {
+    const contentType = bodies.map((b) => `'${b.contentType}'`).join(" | ");
+    return [
+      `{ ${[
+        ...leading,
+        `contentType: ${contentType}`,
+        `data: ${dataTypes[0]}`,
+        ...trailing
+      ].join("; ")} }`
+    ];
+  }
+  return bodies.map((b, i) => `{ ${[
+    ...leading,
+    `contentType: '${b.contentType}'`,
+    `data: ${dataTypes[i]}`,
+    ...trailing
+  ].join("; ")} }`);
+}
+__name(sdkResponseMembers, "sdkResponseMembers");
+function sdkReturnLines(resp, modelsWithOutput, indent, includeStatus) {
+  const bodies = resp.bodies;
+  const headers = resp.headers ?? [];
+  const leading = includeStatus ? [
+    `status: ${resp.statusCode}`
+  ] : [];
+  const trailing = headers.length > 0 ? [
+    `headers: { ${sdkHeaderEntries(headers)} }`
+  ] : [];
+  if (bodies.length === 0) {
+    return [
+      `${indent}return { ${[
+        ...leading,
+        ...trailing
+      ].join(", ")} };`
+    ];
+  }
+  if (bodies.length === 1) {
+    const fields = [
+      ...leading,
+      `contentType: '${bodies[0].contentType}'`,
+      `data: ${sdkReadExpr(bodies[0], modelsWithOutput)}`,
+      ...trailing
+    ];
+    return [
+      `${indent}return { ${fields.join(", ")} };`
+    ];
+  }
+  const dataTypes = bodies.map((b) => sdkDataType(b, modelsWithOutput));
+  if (dataTypes.every((t) => t === dataTypes[0])) {
+    const cast = bodies.map((b) => `'${b.contentType}'`).join(" | ");
+    const fields = [
+      ...leading,
+      `contentType: readContentType(result) as ${cast}`,
+      `data: ${sdkReadExpr(bodies[0], modelsWithOutput)}`,
+      ...trailing
+    ];
+    return [
+      `${indent}return { ${fields.join(", ")} };`
+    ];
+  }
+  const lines = [
+    `${indent}switch (readContentType(result)) {`
+  ];
+  for (const body of bodies.slice(1)) {
+    const fields = [
+      ...leading,
+      `contentType: '${body.contentType}'`,
+      `data: ${sdkReadExpr(body, modelsWithOutput)}`,
+      ...trailing
+    ];
+    lines.push(`${indent}    case '${body.contentType}':`);
+    lines.push(`${indent}        return { ${fields.join(", ")} };`);
+  }
+  const first = bodies[0];
+  const fallbackFields = [
+    ...leading,
+    `contentType: '${first.contentType}'`,
+    `data: ${sdkReadExpr(first, modelsWithOutput)}`,
+    ...trailing
+  ];
+  lines.push(`${indent}    default:`);
+  lines.push(`${indent}        return { ${fallbackFields.join(", ")} };`);
+  lines.push(`${indent}}`);
+  return lines;
+}
+__name(sdkReturnLines, "sdkReturnLines");
+function errorBodyTypeName(route, op) {
+  const method = deriveMethodName(op, route);
+  return `${method.charAt(0).toUpperCase()}${method.slice(1)}ErrorBody`;
+}
+__name(errorBodyTypeName, "errorBodyTypeName");
+function generateErrorBodyAliases(root, options) {
+  const includeInternal = options.includeInternal ?? false;
+  const lines = [];
+  for (const route of root.routes) {
+    for (const op of route.operations) {
+      const mods = resolveModifiers2(route, op);
+      if (!includeInternal && mods.includes("internal")) continue;
+      const types = /* @__PURE__ */ new Set();
+      for (const resp of thrownResponses(op)) {
+        for (const body of resp.bodies) types.add(sdkDataType(body, options.modelsWithOutput));
+      }
+      if (types.size === 0) continue;
+      lines.push(`export type ${errorBodyTypeName(route, op)} = ${[
+        ...types
+      ].join(" | ")};`);
+    }
+  }
+  return lines;
+}
+__name(generateErrorBodyAliases, "generateErrorBodyAliases");
 function buildUrlExpression(path, _) {
   return path.replace(/\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g, (_match, name) => {
     return `\${encodeURIComponent(${name})}`;
@@ -2324,9 +2637,9 @@ function collectTypes2(root, modelsWithInput, modelsWithOutput, includeInternal
         }
       }
       for (const resp of op.responses) {
-        if (resp.bodyType) {
-          collectTypeNodeRefs2(resp.bodyType, types);
-          collectOutputTypeNodeRefs2(resp.bodyType, types, modelsWithOutput);
+        for (const body of resp.bodies) {
+          collectTypeNodeRefs2(body.bodyType, types);
+          collectOutputTypeNodeRefs2(body.bodyType, types, modelsWithOutput);
         }
         if (resp.headers) {
           for (const h of resp.headers) {
@@ -2428,6 +2741,16 @@ function sdkNeedsQueryString(root, includeInternal = false) {
   return false;
 }
 __name(sdkNeedsQueryString, "sdkNeedsQueryString");
+function sdkNeedsReadContentType(root, includeInternal = false) {
+  for (const route of root.routes) {
+    for (const op of route.operations) {
+      if (!includeInternal && resolveModifiers2(route, op).includes("internal")) continue;
+      if (observableResponses(op).some((r) => r.bodies.length > 1)) return true;
+    }
+  }
+  return false;
+}
+__name(sdkNeedsReadContentType, "sdkNeedsReadContentType");
 function sdkNeedsBigIntReplacer(root, includeInternal = false) {
   for (const route of root.routes) {
     for (const op of route.operations) {
@@ -2442,10 +2765,7 @@ function sdkNeedsBigIntReviver(root, includeInternal = false) {
   for (const route of root.routes) {
     for (const op of route.operations) {
       if (!includeInternal && resolveModifiers2(route, op).includes("internal")) continue;
-      if (op.responses.some((r) => {
-        if (!r.bodyType) return false;
-        return !r.contentType || classifyContentType2(r.contentType) === "json";
-      })) {
+      if (op.responses.some((r) => r.bodies.some((b) => classifyContentType2(b.contentType) === "json"))) {
         return true;
       }
     }
@@ -2462,7 +2782,7 @@ function sdkNeedsJson(root, includeInternal = false) {
         if (src.kind === "params") return src.nodes.some((p) => typeNeedsScalar(p.type, "json"));
         return typeNeedsScalar(src.node, "json");
       }, "check");
-      if (!!op.request?.bodies.some((b) => typeNeedsScalar(b.bodyType, "json")) || op.responses.some((r) => r.bodyType && typeNeedsScalar(r.bodyType, "json")) || check(op.query) || check(op.headers) || check(route.params)) return true;
+      if (!!op.request?.bodies.some((b) => typeNeedsScalar(b.bodyType, "json")) || op.responses.some((r) => r.bodies.some((b) => typeNeedsScalar(b.bodyType, "json"))) || check(op.query) || check(op.headers) || check(route.params)) return true;
     }
   }
   return false;
@@ -2546,11 +2866,11 @@ function deriveTypeImportPath2(file, template) {
 __name(deriveTypeImportPath2, "deriveTypeImportPath");
 function generateSdkOptions() {
   return [
-    "export class SdkError extends Error {",
+    "export class SdkError<TBody = unknown> extends Error {",
     "    constructor(",
     "        public readonly status: number,",
     "        public readonly statusText: string,",
-    "        public readonly body: unknown,",
+    "        public readonly body: TBody,",
     "        public readonly headers: Headers,",
     "    ) {",
     "        super(`${status} ${statusText}`);",
@@ -2558,7 +2878,16 @@ function generateSdkOptions() {
     "    }",
     "}",
     "",
-    "export type SdkFetch = (url: string, init: RequestInit) => Promise<Response>;",
+    "export interface SdkRequestInit extends RequestInit {",
+    "    /**",
+    "     * Statuses this operation declares as values rather than errors \u2014 a 304 from",
+    "     * conditional-GET middleware, or an error status the service returns deliberately.",
+    "     * Anything else at or above 400 still throws SdkError.",
+    "     */",
+    "    expectStatuses?: number[];",
+    "}",
+    "",
+    "export type SdkFetch = (url: string, init: SdkRequestInit) => Promise<Response>;",
     "",
     "export interface SdkOptions {",
     "    baseUrl: string;",
@@ -2584,9 +2913,13 @@ function generateSdkOptions() {
     "",
     JSON_VALUE_TYPE_DECL,
     "",
+    "export function readContentType(res: Response): string {",
+    "    return res.headers.get('content-type')?.split(';')[0]?.trim() ?? '';",
+    "}",
+    "",
     "export function createSdkFetch(options: SdkOptions): SdkFetch {",
     "    const getRequestId = options.requestIdFactory ?? (() => crypto.randomUUID());",
-    "    return async (url: string, init: RequestInit): Promise<Response> => {",
+    "    return async (url: string, init: SdkRequestInit): Promise<Response> => {",
     "        const baseHeaders = typeof options.headers === 'function'",
     "            ? await options.headers()",
     "            : options.headers ?? {};",
@@ -2594,7 +2927,7 @@ function generateSdkOptions() {
     "            ...init,",
     "            headers: { ...baseHeaders, 'X-Request-ID': getRequestId(), ...init.headers as Record<string, string> },",
     "        });",
-    "        if (!res.ok) {",
+    "        if (!res.ok && !(init.expectStatuses ?? []).includes(res.status)) {",
     "            const text = await res.text();",
     "            let body: unknown;",
     "            try { body = JSON.parse(text); } catch { body = text; }",
@@ -2693,6 +3026,7 @@ function generateAreaClient(input) {
   const { area, outPath, inlineFiles, subareaClients, sdkOptionsPath } = input;
   const className = deriveAreaClientClassName(area);
   const collectedMethodLines = [];
+  const collectedErrorAliases = /* @__PURE__ */ new Set();
   const seenMethods = /* @__PURE__ */ new Set();
   const typesByImportPath = /* @__PURE__ */ new Map();
   const unresolvedTypes = /* @__PURE__ */ new Set();
@@ -2700,6 +3034,7 @@ function generateAreaClient(input) {
   let needsBigIntReplacer = false;
   let needsBigIntReviver = false;
   let needsQueryString = false;
+  let needsReadContentType = false;
   for (const inline of inlineFiles) {
     const includeInternal = inline.codegenOptions.includeInternal ?? false;
     const { lines: methodLines, methodNames } = generateClientMethods(inline.root, inline.codegenOptions);
@@ -2710,10 +3045,12 @@ function generateAreaClient(input) {
       seenMethods.add(name);
     }
     collectedMethodLines.push(...methodLines);
+    for (const alias of generateErrorBodyAliases(inline.root, inline.codegenOptions)) collectedErrorAliases.add(alias);
     if (sdkNeedsJson(inline.root, includeInternal)) needsJson = true;
     if (sdkNeedsBigIntReplacer(inline.root, includeInternal)) needsBigIntReplacer = true;
     if (sdkNeedsBigIntReviver(inline.root, includeInternal)) needsBigIntReviver = true;
     if (sdkNeedsQueryString(inline.root, includeInternal)) needsQueryString = true;
+    if (sdkNeedsReadContentType(inline.root, includeInternal)) needsReadContentType = true;
     const typesForFile = collectTypes2(inline.root, inline.codegenOptions.modelsWithInput, inline.codegenOptions.modelsWithOutput, includeInternal);
     const { modelOutPaths } = inline.codegenOptions;
     if (modelOutPaths) {
@@ -2741,6 +3078,7 @@ function generateAreaClient(input) {
   if (needsBigIntReplacer) valueImports.push("bigIntReplacer");
   if (needsBigIntReviver) valueImports.push("parseJson");
   if (needsQueryString) valueImports.push("buildQueryString");
+  if (needsReadContentType) valueImports.push("readContentType");
   if (valueImports.length > 0) {
     lines.push(`import { ${valueImports.join(", ")} } from '${sdkOptionsRel}';`);
   }
@@ -2765,6 +3103,10 @@ function generateAreaClient(input) {
     lines.push(`import { ${sc.client.className} } from '${sc.client.importPath}';`);
   }
   lines.push("");
+  if (collectedErrorAliases.size > 0) {
+    lines.push(...collectedErrorAliases);
+    lines.push("");
+  }
   lines.push(`export class ${className} {`);
   for (const sc of subareaClients) {
     lines.push(`    readonly ${sc.propertyName}: ${sc.client.className};`);
@@ -3061,7 +3403,7 @@ function renderOutputField(field, outputCase, modelsWithOutput, target) {
 __name(renderOutputField, "renderOutputField");
 
 // src/codegen-mcp.ts
-import { resolveModifiers as resolveModifiers3 } from "@contractkit/core";
+import { resolveModifiers as resolveModifiers3, emittedResponses as emittedResponses2 } from "@contractkit/core";
 import { basename as basename3, dirname as dirname5, relative as relative5 } from "path";
 function mcpConfig(op) {
   return op.mcp && typeof op.mcp === "object" ? op.mcp : void 0;
@@ -3187,12 +3529,15 @@ function argsSchemaExpr(props) {
   return `z.object({ ${fields} })`;
 }
 __name(argsSchemaExpr, "argsSchemaExpr");
-function primaryResponse(op) {
-  return op.responses.find((r) => r.bodyType) ?? op.responses[0];
+function primaryResponseBody(op) {
+  for (const resp of emittedResponses2(op)) {
+    if (resp.bodies[0]) return resp.bodies[0].bodyType;
+  }
+  return void 0;
 }
-__name(primaryResponse, "primaryResponse");
+__name(primaryResponseBody, "primaryResponseBody");
 function outputSchemaExpr(op) {
-  const body = primaryResponse(op)?.bodyType;
+  const body = primaryResponseBody(op);
   if (!body) return void 0;
   if (body.kind === "ref") return body.name;
   if (body.kind === "inlineObject") return renderType(body);
@@ -3261,7 +3606,7 @@ function collectSchemaIds(ops, modelsWithInput) {
     }
     walkSourceRefs(op.query, ids, modelsWithInput);
     walkSourceRefs(op.headers, ids, modelsWithInput);
-    const body = primaryResponse(op)?.bodyType;
+    const body = primaryResponseBody(op);
     if (body && (body.kind === "ref" || body.kind === "inlineObject")) walkTypeRefs(body, ids, "read");
   }
   return ids;
@@ -3365,7 +3710,7 @@ function renderToolClass(plan, file, options) {
   const props = buildArgsProps(route, op, options.modelsWithInput);
   const destructure = props.map((p) => p.key);
   const callArgs = buildArgs(route, op);
-  const isVoid = !primaryResponse(op)?.bodyType;
+  const isVoid = !primaryResponseBody(op);
   const structured = !!outExpr;
   lines.push("    async handle(args: Record<string, unknown>, _context: McpToolContext): Promise<CallToolResult> {");
   if (destructure.length > 0) {
@@ -3777,7 +4122,7 @@ function collectOpRootRefs(root, modelMap) {
         for (const body of op.request.bodies) seeds.push(body.bodyType);
       }
       for (const resp of op.responses) {
-        if (resp.bodyType) seeds.push(resp.bodyType);
+        for (const body of resp.bodies) seeds.push(body.bodyType);
         if (resp.headers) {
           for (const h of resp.headers) seeds.push(h.type);
         }