typed-openapi 1.5.1 → 2.0.0

package/dist/node.export.d.ts

@@ -1,5 +1,5 @@
 import * as arktype_internal_methods_object_ts from 'arktype/internal/methods/object.ts';
-import { N as NameTransformOptions } from './types-DLE5RaXi.js';
+import { N as NameTransformOptions } from './types-DsI2d-HE.js';
 import 'openapi3-ts/oas31';
 import 'openapi3-ts/oas30';
 
@@ -8,6 +8,9 @@ declare const optionsSchema: arktype_internal_methods_object_ts.ObjectType<{
     tanstack: string | boolean;
     schemasOnly: boolean;
     output?: string;
+    includeClient?: boolean | "false" | "true";
+    successStatusCodes?: string;
+    errorStatusCodes?: string;
 }, {}>;
 type GenerateClientFilesOptions = typeof optionsSchema.infer & {
     nameTransform?: NameTransformOptions;

package/dist/node.export.js

@@ -1,7 +1,7 @@
 import {
   generateClientFiles
-} from "./chunk-O7DZWQK4.js";
-import "./chunk-OVT6OLBK.js";
+} from "./chunk-MCVYB63W.js";
+import "./chunk-E6A7N4ND.js";
 import "./chunk-KAEXXJ7X.js";
 export {
   generateClientFiles

package/dist/{types-DLE5RaXi.d.ts → types-DsI2d-HE.d.ts}

@@ -100,6 +100,7 @@ type RequestFormat = "json" | "form-data" | "form-url" | "binary" | "text";
 type DefaultEndpoint = {
     parameters?: EndpointParameters | undefined;
     response: AnyBox;
+    responses?: Record<string, AnyBox>;
     responseHeaders?: Record<string, AnyBox>;
 };
 type Endpoint<TConfig extends DefaultEndpoint = DefaultEndpoint> = {
@@ -114,6 +115,7 @@ type Endpoint<TConfig extends DefaultEndpoint = DefaultEndpoint> = {
         areParametersRequired: boolean;
     };
     response: TConfig["response"];
+    responses?: TConfig["responses"];
     responseHeaders?: TConfig["responseHeaders"];
 };
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typed-openapi",
   "type": "module",
-  "version": "1.5.1",
+  "version": "2.0.0",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "exports": {
@@ -30,8 +30,10 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.4",
+    "@tanstack/react-query": "5.85.0",
     "@types/node": "^22.15.17",
     "@types/prettier": "3.0.0",
+    "msw": "2.10.5",
     "tsup": "^8.4.0",
     "typescript": "^5.8.3",
     "vitest": "^3.1.3"
@@ -64,6 +66,9 @@
     "dev": "tsup --watch",
     "build": "tsup",
     "test": "vitest",
+    "generate:runtime": "node bin.js ./tests/samples/petstore.yaml --output ./tmp/generated-client.ts --tanstack generated-tanstack.ts",
+    "test:runtime:run": "vitest run tests/integration-runtime-msw.test.ts",
+    "test:runtime": "pnpm run generate:runtime && pnpm run test:runtime:run",
     "fmt": "prettier --write src",
     "typecheck": "tsc -b ./tsconfig.build.json"
   }

package/src/cli.ts

@@ -1,5 +1,4 @@
 import { cac } from "cac";
-
 import { readFileSync } from "fs";
 import { generateClientFiles } from "./generate-client-files.ts";
 import { allowedRuntimes } from "./generator.ts";
@@ -11,16 +10,22 @@ cli
   .command("<input>", "Generate")
   .option("-o, --output <path>", "Output path for the api client ts file (defaults to `<input>.<runtime>.ts`)")
   .option(
-    "-r, --runtime <name>",
+    "-r, --runtime <n>",
     `Runtime to use for validation; defaults to \`none\`; available: ${allowedRuntimes.toString()}`,
     { default: "none" },
   )
   .option("--schemas-only", "Only generate schemas, skipping client generation (defaults to false)", { default: false })
+  .option("--include-client", "Include API client types and implementation (defaults to true)", { default: true })
+  .option(
+    "--success-status-codes <codes>",
+    "Comma-separated list of success status codes (defaults to 2xx and 3xx ranges)",
+  )
+  .option("--error-status-codes <codes>", "Comma-separated list of error status codes (defaults to 4xx and 5xx ranges)")
   .option(
     "--tanstack [name]",
     "Generate tanstack client, defaults to false, can optionally specify a name for the generated file",
   )
-  .action(async (input, _options) => {
+  .action(async (input: string, _options: any) => {
     return generateClientFiles(input, _options);
   });
 

package/src/generate-client-files.ts

@@ -3,7 +3,13 @@ import type { OpenAPIObject } from "openapi3-ts/oas31";
 import { basename, join, dirname } from "pathe";
 import { type } from "arktype";
 import { mkdir, writeFile } from "fs/promises";
-import { allowedRuntimes, generateFile } from "./generator.ts";
+import {
+  allowedRuntimes,
+  generateFile,
+  DEFAULT_SUCCESS_STATUS_CODES,
+  DEFAULT_ERROR_STATUS_CODES,
+  type GeneratorOptions,
+} from "./generator.ts";
 import { mapOpenApiEndpoints } from "./map-openapi-endpoints.ts";
 import { generateTanstackQueryFile } from "./tanstack-query.generator.ts";
 import { prettify } from "./format.ts";
@@ -25,6 +31,9 @@ export const optionsSchema = type({
   runtime: allowedRuntimes,
   tanstack: "boolean | string",
   schemasOnly: "boolean",
+  "includeClient?": "boolean | 'true' | 'false'",
+  "successStatusCodes?": "string",
+  "errorStatusCodes?": "string",
 });
 
 type GenerateClientFilesOptions = typeof optionsSchema.infer & {
@@ -37,14 +46,31 @@ export async function generateClientFiles(input: string, options: GenerateClient
   const ctx = mapOpenApiEndpoints(openApiDoc, options);
   console.log(`Found ${ctx.endpointList.length} endpoints`);
 
-  const content = await prettify(
-    generateFile({
-      ...ctx,
-      runtime: options.runtime,
-      schemasOnly: options.schemasOnly,
-      nameTransform: options.nameTransform,
-    }),
-  );
+  // Parse success status codes if provided
+  const successStatusCodes = options.successStatusCodes
+    ? (options.successStatusCodes.split(",").map((code) => parseInt(code.trim(), 10)) as readonly number[])
+    : undefined;
+
+  // Parse error status codes if provided
+  const errorStatusCodes = options.errorStatusCodes
+    ? (options.errorStatusCodes.split(",").map((code) => parseInt(code.trim(), 10)) as readonly number[])
+    : undefined;
+
+  // Convert string boolean to actual boolean
+  const includeClient =
+    options.includeClient === "false" ? false : options.includeClient === "true" ? true : options.includeClient;
+
+  const generatorOptions: GeneratorOptions = {
+    ...ctx,
+    runtime: options.runtime,
+    schemasOnly: options.schemasOnly,
+    nameTransform: options.nameTransform,
+    includeClient: includeClient ?? true,
+    successStatusCodes: successStatusCodes ?? DEFAULT_SUCCESS_STATUS_CODES,
+    errorStatusCodes: errorStatusCodes ?? DEFAULT_ERROR_STATUS_CODES,
+  };
+
+  const content = await prettify(generateFile(generatorOptions));
   const outputPath = join(
     cwd,
     options.output ?? input + `.${options.runtime === "none" ? "client" : options.runtime}.ts`,
@@ -56,7 +82,7 @@ export async function generateClientFiles(input: string, options: GenerateClient
 
   if (options.tanstack) {
     const tanstackContent = await generateTanstackQueryFile({
-      ...ctx,
+      ...generatorOptions,
       relativeApiClientPath: "./" + basename(outputPath),
     });
     const tanstackOutputPath = join(

package/src/generator.ts

@@ -8,10 +8,26 @@ import { type } from "arktype";
 import { wrapWithQuotesIfNeeded } from "./string-utils.ts";
 import type { NameTransformOptions } from "./types.ts";
 
-type GeneratorOptions = ReturnType<typeof mapOpenApiEndpoints> & {
+// Default success status codes (2xx and 3xx ranges)
+export const DEFAULT_SUCCESS_STATUS_CODES = [
+  200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308,
+] as const;
+
+// Default error status codes (4xx and 5xx ranges)
+export const DEFAULT_ERROR_STATUS_CODES = [
+  400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 421, 422, 423, 424,
+  425, 426, 428, 429, 431, 451, 500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511,
+] as const;
+
+export type ErrorStatusCode = (typeof DEFAULT_ERROR_STATUS_CODES)[number];
+
+export type GeneratorOptions = ReturnType<typeof mapOpenApiEndpoints> & {
   runtime?: "none" | keyof typeof runtimeValidationGenerator;
   schemasOnly?: boolean;
   nameTransform?: NameTransformOptions | undefined;
+  successStatusCodes?: readonly number[];
+  errorStatusCodes?: readonly number[];
+  includeClient?: boolean;
 };
 type GeneratorContext = Required<GeneratorOptions>;
 
@@ -62,11 +78,18 @@ const replacerByRuntime = {
 };
 
 export const generateFile = (options: GeneratorOptions) => {
-  const ctx = { ...options, runtime: options.runtime ?? "none" } as GeneratorContext;
+  const ctx = {
+    ...options,
+    runtime: options.runtime ?? "none",
+    successStatusCodes: options.successStatusCodes ?? DEFAULT_SUCCESS_STATUS_CODES,
+    errorStatusCodes: options.errorStatusCodes ?? DEFAULT_ERROR_STATUS_CODES,
+    includeClient: options.includeClient ?? true,
+  } as GeneratorContext;
 
   const schemaList = generateSchemaList(ctx);
   const endpointSchemaList = options.schemasOnly ? "" : generateEndpointSchemaList(ctx);
-  const apiClient = options.schemasOnly ? "" : generateApiClient(ctx);
+  const endpointByMethod = options.schemasOnly ? "" : generateEndpointByMethod(ctx);
+  const apiClient = options.schemasOnly || !ctx.includeClient ? "" : generateApiClient(ctx);
 
   const transform =
     ctx.runtime === "none"
@@ -98,6 +121,7 @@ export const generateFile = (options: GeneratorOptions) => {
 
   const file = `
   ${transform(schemaList + endpointSchemaList)}
+  ${endpointByMethod}
   ${apiClient}
   `;
 
@@ -153,6 +177,24 @@ const responseHeadersObjectToString = (responseHeaders: Record<string, AnyBox>,
   return str + "}";
 };
 
+const generateResponsesObject = (responses: Record<string, AnyBox>, ctx: GeneratorContext) => {
+  let str = "{";
+  for (const [statusCode, responseType] of Object.entries(responses)) {
+    const value =
+      ctx.runtime === "none"
+        ? responseType.recompute((box) => {
+            if (Box.isReference(box) && !box.params.generics && box.value !== "null") {
+              box.value = `Schemas.${box.value}`;
+            }
+
+            return box;
+          }).value
+        : responseType.value;
+    str += `${wrapWithQuotesIfNeeded(statusCode)}: ${value},\n`;
+  }
+  return str + "}";
+};
+
 const generateEndpointSchemaList = (ctx: GeneratorContext) => {
   let file = `
   ${ctx.runtime === "none" ? "export namespace Endpoints {" : ""}
@@ -199,6 +241,7 @@ const generateEndpointSchemaList = (ctx: GeneratorContext) => {
             }).value
           : endpoint.response.value
       },
+      ${endpoint.responses ? `responses: ${generateResponsesObject(endpoint.responses, ctx)},` : ""}
       ${
         endpoint.responseHeaders
           ? `responseHeaders: ${responseHeadersObjectToString(endpoint.responseHeaders, ctx)},`
@@ -227,9 +270,11 @@ const generateEndpointByMethod = (ctx: GeneratorContext) => {
      ${Object.entries(byMethods)
        .map(([method, list]) => {
          return `${method}: {
-           ${list.map(
-             (endpoint) => `"${endpoint.path}": ${ctx.runtime === "none" ? "Endpoints." : ""}${endpoint.meta.alias}`,
-           )}
+           ${list
+             .map(
+               (endpoint) => `"${endpoint.path}": ${ctx.runtime === "none" ? "Endpoints." : ""}${endpoint.meta.alias}`,
+             )
+             .join(",\n")}
          }`;
        })
        .join(",\n")}
@@ -251,9 +296,12 @@ const generateEndpointByMethod = (ctx: GeneratorContext) => {
 };
 
 const generateApiClient = (ctx: GeneratorContext) => {
+  if (!ctx.includeClient) {
+    return "";
+  }
+
   const { endpointList } = ctx;
   const byMethods = groupBy(endpointList, "method");
-  const endpointSchemaList = generateEndpointByMethod(ctx);
 
   const apiClientTypes = `
 // <ApiClientTypes>
@@ -272,6 +320,7 @@ type RequestFormat = "json" | "form-data" | "form-url" | "binary" | "text";
 export type DefaultEndpoint = {
   parameters?: EndpointParameters | undefined;
   response: unknown;
+  responses?: Record<string, unknown>;
   responseHeaders?: Record<string, unknown>;
 };
 
@@ -287,11 +336,64 @@ export type Endpoint<TConfig extends DefaultEndpoint = DefaultEndpoint> = {
     areParametersRequired: boolean;
   };
   response: TConfig["response"];
+  responses?: TConfig["responses"];
   responseHeaders?: TConfig["responseHeaders"]
 };
 
 export type Fetcher = (method: Method, url: string, parameters?: EndpointParameters | undefined) => Promise<Response>;
 
+export const successStatusCodes = [${ctx.successStatusCodes.join(",")}] as const;
+export type SuccessStatusCode = typeof successStatusCodes[number];
+
+export const errorStatusCodes = [${ctx.errorStatusCodes.join(",")}] as const;
+export type ErrorStatusCode = typeof errorStatusCodes[number];
+
+// Error handling types
+/** @see https://developer.mozilla.org/en-US/docs/Web/API/Response */
+interface SuccessResponse<TSuccess, TStatusCode> extends Omit<Response, "ok" | "status" | "json"> {
+  ok: true;
+  status: TStatusCode;
+  data: TSuccess;
+  /** [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/Response/json) */
+  json: () => Promise<TSuccess>;
+}
+
+/** @see https://developer.mozilla.org/en-US/docs/Web/API/Response */
+interface ErrorResponse<TData, TStatusCode> extends Omit<Response, "ok" | "status" | "json"> {
+  ok: false;
+  status: TStatusCode;
+  data: TData;
+  /** [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/Response/json) */
+  json: () => Promise<TData>;
+}
+
+export type TypedApiResponse<TSuccess, TAllResponses extends Record<string | number, unknown> = {}> =
+  (keyof TAllResponses extends never
+    ? SuccessResponse<TSuccess, number>
+    : {
+        [K in keyof TAllResponses]: K extends string
+          ? K extends \`\${infer TStatusCode extends number}\`
+            ? TStatusCode extends SuccessStatusCode
+              ? SuccessResponse<TSuccess, TStatusCode>
+              : ErrorResponse<TAllResponses[K], TStatusCode>
+            : never
+          : K extends number
+            ? K extends SuccessStatusCode
+              ? SuccessResponse<TSuccess, K>
+              : ErrorResponse<TAllResponses[K], K>
+            : never;
+      }[keyof TAllResponses]);
+
+export type SafeApiResponse<TEndpoint> = TEndpoint extends { response: infer TSuccess; responses: infer TResponses }
+  ? TResponses extends Record<string, unknown>
+    ? TypedApiResponse<TSuccess, TResponses>
+    : SuccessResponse<TSuccess, number>
+  : TEndpoint extends { response: infer TSuccess }
+    ? SuccessResponse<TSuccess, number>
+    : never;
+
+export type InferResponseByStatus<TEndpoint, TStatusCode> = Extract<SafeApiResponse<TEndpoint>, { status: TStatusCode }>
+
 type RequiredKeys<T> = {
   [P in keyof T]-?: undefined extends T[P] ? never : P;
 }[keyof T];
@@ -302,9 +404,23 @@ type MaybeOptionalArg<T> = RequiredKeys<T> extends never ? [config?: T] : [confi
 `;
 
   const apiClient = `
+// <TypedResponseError>
+export class TypedResponseError extends Error {
+  response: ErrorResponse<unknown, ErrorStatusCode>;
+  status: number;
+  constructor(response: ErrorResponse<unknown, ErrorStatusCode>) {
+    super(\`HTTP \${response.status}: \${response.statusText}\`);
+    this.name = 'TypedResponseError';
+    this.response = response;
+    this.status = response.status;
+  }
+}
+// </TypedResponseError>
 // <ApiClient>
 export class ApiClient {
   baseUrl: string = "";
+  successStatusCodes = successStatusCodes;
+  errorStatusCodes = errorStatusCodes;
 
   constructor(public fetcher: Fetcher) {}
 
@@ -333,16 +449,53 @@ export class ApiClient {
       ...params: MaybeOptionalArg<${match(ctx.runtime)
         .with("zod", "yup", () => infer(`TEndpoint["parameters"]`))
         .with("arktype", "io-ts", "typebox", "valibot", () => infer(`TEndpoint`) + `["parameters"]`)
-        .otherwise(() => `TEndpoint["parameters"]`)}>
+        .otherwise(() => `TEndpoint["parameters"]`)} & { withResponse?: false; throwOnStatusError?: boolean }>
     ): Promise<${match(ctx.runtime)
       .with("zod", "yup", () => infer(`TEndpoint["response"]`))
       .with("arktype", "io-ts", "typebox", "valibot", () => infer(`TEndpoint`) + `["response"]`)
-      .otherwise(() => `TEndpoint["response"]`)}> {
-      return this.fetcher("${method}", this.baseUrl + path, params[0])
-          .then(response => this.parseResponse(response))${match(ctx.runtime)
+      .otherwise(() => `TEndpoint["response"]`)}>;
+
+    ${method}<Path extends keyof ${capitalizedMethod}Endpoints, TEndpoint extends ${capitalizedMethod}Endpoints[Path]>(
+      path: Path,
+      ...params: MaybeOptionalArg<${match(ctx.runtime)
+        .with("zod", "yup", () => infer(`TEndpoint["parameters"]`))
+        .with("arktype", "io-ts", "typebox", "valibot", () => infer(`TEndpoint`) + `["parameters"]`)
+        .otherwise(() => `TEndpoint["parameters"]`)} & { withResponse: true; throwOnStatusError?: boolean }>
+    ): Promise<SafeApiResponse<TEndpoint>>;
+
+    ${method}<Path extends keyof ${capitalizedMethod}Endpoints, TEndpoint extends ${capitalizedMethod}Endpoints[Path]>(
+      path: Path,
+      ...params: MaybeOptionalArg<any>
+    ): Promise<any> {
+      const requestParams = params[0];
+      const withResponse = requestParams?.withResponse;
+      const { withResponse: _, throwOnStatusError = withResponse ? false : true, ...fetchParams } = requestParams || {};
+
+      const promise = this.fetcher("${method}", this.baseUrl + path, Object.keys(fetchParams).length ? requestParams : undefined)
+        .then(async (response) => {
+          const data = await this.parseResponse(response);
+          const typedResponse = Object.assign(response, {
+            data: data,
+            json: () => Promise.resolve(data)
+          }) as SafeApiResponse<TEndpoint>;
+
+          if (throwOnStatusError && errorStatusCodes.includes(response.status as never)) {
+            throw new TypedResponseError(typedResponse as never);
+          }
+
+          return withResponse ? typedResponse : data;
+        });
+
+        return promise ${match(ctx.runtime)
             .with("zod", "yup", () => `as Promise<${infer(`TEndpoint["response"]`)}>`)
-            .with("arktype", "io-ts", "typebox", "valibot", () => `as Promise<${infer(`TEndpoint`) + `["response"]`}>`)
-            .otherwise(() => `as Promise<TEndpoint["response"]>`)};
+            .with(
+              "arktype",
+              "io-ts",
+              "typebox",
+              "valibot",
+              () => `as Promise<${infer(`TEndpoint`) + `["response"]`}>`,
+            )
+            .otherwise(() => `as Promise<TEndpoint["response"]>`)}
     }
     // </ApiClient.${method}>
     `
@@ -373,11 +526,8 @@ export class ApiClient {
           () => inferByRuntime[ctx.runtime](`TEndpoint`) + `["parameters"]`,
         )
         .otherwise(() => `TEndpoint extends { parameters: infer Params } ? Params : never`)}>)
-    : Promise<Omit<Response, "json"> & {
-      /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/json) */
-      json: () => Promise<TEndpoint extends { response: infer Res } ? Res : never>;
-    }> {
-      return this.fetcher(method, this.baseUrl + (path as string), params[0] as EndpointParameters);
+    : Promise<SafeApiResponse<TEndpoint>> {
+      return this.fetcher(method, this.baseUrl + (path as string), params[0] as EndpointParameters) as Promise<SafeApiResponse<TEndpoint>>;
     }
     // </ApiClient.request>
 }
@@ -395,10 +545,25 @@ export function createApiClient(fetcher: Fetcher, baseUrl?: string) {
  api.get("/users").then((users) => console.log(users));
  api.post("/users", { body: { name: "John" } }).then((user) => console.log(user));
  api.put("/users/:id", { path: { id: 1 }, body: { name: "John" } }).then((user) => console.log(user));
+
+ // With error handling
+ const result = await api.get("/users/{id}", { path: { id: "123" }, withResponse: true });
+ if (result.ok) {
+   // Access data directly
+   const user = result.data;
+   console.log(user);
+
+   // Or use the json() method for compatibility
+   const userFromJson = await result.json();
+   console.log(userFromJson);
+ } else {
+   const error = result.data;
+   console.error(\`Error \${result.status}:\`, error);
+ }
 */
 
-// </ApiClient
+// </ApiClient>
 `;
 
-  return endpointSchemaList + apiClientTypes + apiClient;
+  return apiClientTypes + apiClient;
 };

package/src/map-openapi-endpoints.ts

@@ -130,14 +130,56 @@ export const mapOpenApiEndpoints = (doc: OpenAPIObject, options?: { nameTransfor
 
       // Match the first 2xx-3xx response found, or fallback to default one otherwise
       let responseObject: ResponseObject | undefined;
+      const allResponses: Record<string, AnyBox> = {};
+
       Object.entries(operation.responses ?? {}).map(([status, responseOrRef]) => {
         const statusCode = Number(status);
-        if (statusCode >= 200 && statusCode < 300) {
-          responseObject = refs.unwrap<ResponseObject>(responseOrRef);
+        const responseObj = refs.unwrap<ResponseObject>(responseOrRef);
+
+        // Collect all responses for error handling
+        const content = responseObj?.content;
+        if (content) {
+          const matchingMediaType = Object.keys(content).find(isResponseMediaType);
+          if (matchingMediaType && content[matchingMediaType]) {
+            allResponses[status] = openApiSchemaToTs({
+              schema: content[matchingMediaType]?.schema ?? {},
+              ctx,
+            });
+          } else {
+            // If no JSON content, use unknown type
+            allResponses[status] = openApiSchemaToTs({ schema: {}, ctx });
+          }
+        } else {
+          // If no content defined, use unknown type
+          allResponses[status] = openApiSchemaToTs({ schema: {}, ctx });
+        }
+
+        // Keep the current logic for the main response (first 2xx-3xx)
+        if (statusCode >= 200 && statusCode < 300 && !responseObject) {
+          responseObject = responseObj;
         }
       });
+
       if (!responseObject && operation.responses?.default) {
         responseObject = refs.unwrap(operation.responses.default);
+        // Also add default to all responses if not already covered
+        if (!allResponses["default"]) {
+          const content = responseObject?.content;
+          if (content) {
+            const matchingMediaType = Object.keys(content).find(isResponseMediaType);
+            if (matchingMediaType && content[matchingMediaType]) {
+              allResponses["default"] = openApiSchemaToTs({
+                schema: content[matchingMediaType]?.schema ?? {},
+                ctx,
+              });
+            }
+          }
+        }
+      }
+
+      // Set the responses collection
+      if (Object.keys(allResponses).length > 0) {
+        endpoint.responses = allResponses;
       }
 
       const content = responseObject?.content;
@@ -206,6 +248,7 @@ type RequestFormat = "json" | "form-data" | "form-url" | "binary" | "text";
 type DefaultEndpoint = {
   parameters?: EndpointParameters | undefined;
   response: AnyBox;
+  responses?: Record<string, AnyBox>;
   responseHeaders?: Record<string, AnyBox>;
 };
 
@@ -221,5 +264,6 @@ export type Endpoint<TConfig extends DefaultEndpoint = DefaultEndpoint> = {
     areParametersRequired: boolean;
   };
   response: TConfig["response"];
+  responses?: TConfig["responses"];
   responseHeaders?: TConfig["responseHeaders"];
 };