feat(openapi-resource-gen): emit typed XxxError type aliases for 4xx/5xx JSON responses

Endpoints that define application/json content on 4xx, 5xx, or default
response codes now get an exported `XxxError` type alias alongside the
existing `XxxResponse` and `XxxParams` aliases. Multiple error codes
produce a union type; the `default` catch-all key is included when
present. Specs with no JSON error bodies (e.g. Petstore) emit no error
type, keeping output identical to before.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: constantant

tools/openapi-resource-gen/src/generators/api-resource/endpoint-model.ts

@@ -33,6 +33,8 @@ export interface EndpointModel {
   hasResponse: boolean;
   /** All 2xx response codes that carry application/json content, in priority order. */
   responseStatuses: string[];
+  /** 4xx/5xx/default response codes that carry application/json content. */
+  errorStatuses: string[];
   bodyContentType: string | null;
   /** True when bodyContentType is not json / form-urlencoded / multipart (e.g. octet-stream, pdf, image). */
   isBinaryBody: boolean;

tools/openapi-resource-gen/src/generators/api-resource/generator.spec.ts

@@ -623,6 +623,123 @@ describe('api-resource generator', () => {
     });
   });
 
+  describe('typed error responses', () => {
+    it('emits a single XxxError type for a single 4xx JSON response', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue({
+        paths: {
+          '/pets/{id}': {
+            get: {
+              operationId: 'getPet',
+              tags: ['pets'],
+              parameters: [{ in: 'path', name: 'id', required: true, schema: { type: 'string' } }],
+              responses: {
+                '200': { content: { 'application/json': { schema: {} } } },
+                '404': { content: { 'application/json': { schema: {} } } },
+              },
+            },
+          },
+        },
+      } as never);
+
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/error-single/src',
+      });
+      const content = tree.read('libs/error-single/src/pets/get-pet.token.ts', 'utf-8')!;
+      expect(content).toContain('export type GetPetError =');
+      expect(content).toContain("['responses']['404']['content']['application/json']");
+      expect(content).not.toMatch(/export type GetPetError =\s*\|/);
+    });
+
+    it('emits a union XxxError type for multiple error codes', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue({
+        paths: {
+          '/pets': {
+            post: {
+              operationId: 'createPet',
+              tags: ['pets'],
+              requestBody: { content: { 'application/json': { schema: {} } } },
+              responses: {
+                '201': { content: { 'application/json': { schema: {} } } },
+                '400': { content: { 'application/json': { schema: {} } } },
+                '422': { content: { 'application/json': { schema: {} } } },
+              },
+            },
+          },
+        },
+      } as never);
+
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/error-union/src',
+      });
+      const content = tree.read('libs/error-union/src/pets/create-pet.token.ts', 'utf-8')!;
+      expect(content).toContain('export type CreatePetError =');
+      expect(content).toContain("['responses']['400']['content']['application/json']");
+      expect(content).toContain("['responses']['422']['content']['application/json']");
+      expect(content).toMatch(/\|\s*paths\[.*\['responses'\]\['400'\]/);
+    });
+
+    it('includes the default catch-all response code in the error type', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue({
+        paths: {
+          '/items': {
+            get: {
+              operationId: 'listItems',
+              tags: ['items'],
+              responses: {
+                '200': { content: { 'application/json': { schema: {} } } },
+                default: { content: { 'application/json': { schema: {} } } },
+              },
+            },
+          },
+        },
+      } as never);
+
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/error-default/src',
+      });
+      const content = tree.read('libs/error-default/src/items/list-items.token.ts', 'utf-8')!;
+      expect(content).toContain('export type ListItemsError =');
+      expect(content).toContain("['responses']['default']['content']['application/json']");
+    });
+
+    it('does not emit XxxError type when no error responses carry JSON', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue({
+        paths: {
+          '/files/{id}': {
+            delete: {
+              operationId: 'deleteFile',
+              tags: ['files'],
+              parameters: [{ in: 'path', name: 'id', required: true, schema: { type: 'string' } }],
+              responses: {
+                '204': {},
+                '404': { content: { 'text/plain': { schema: {} } } },
+              },
+            },
+          },
+        },
+      } as never);
+
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/no-error-type/src',
+      });
+      const content = tree.read('libs/no-error-type/src/files/delete-file.token.ts', 'utf-8')!;
+      expect(content).not.toContain('Error =');
+    });
+
+    it('does not emit XxxError type when no error responses are defined', async () => {
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/no-errors/src',
+      });
+      const content = tree.read('libs/no-errors/src/pets/list-pets.token.ts', 'utf-8')!;
+      expect(content).not.toContain('Error =');
+    });
+  });
+
   describe('verbose output', () => {
     it('prints a file summary when verbose is true', async () => {
       const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);

tools/openapi-resource-gen/src/generators/api-resource/parse-spec.ts

@@ -162,6 +162,13 @@ export function buildEndpoints(
       });
       const hasResponse = responseStatuses.length > 0;
 
+      const errorStatuses = Object.keys(operation.responses ?? {})
+        .filter((code) => code === 'default' || /^[45]/.test(code))
+        .filter((code) => {
+          const obj = operation.responses?.[code] as OpenAPIV3.ResponseObject | undefined;
+          return obj?.content?.['application/json'] != null;
+        });
+
       const deprecated = operation.deprecated === true;
 
       endpoints.push({
@@ -182,6 +189,7 @@ export function buildEndpoints(
         isBinaryBody,
         deprecated,
         securitySchemeNames,
+        errorStatuses,
       });
     }
   }

tools/openapi-resource-gen/src/generators/api-resource/render-token.ts

@@ -141,6 +141,23 @@ export function renderTokenFile(
       lines.push('');
     }
   }
+  if (ep.errorStatuses.length > 0) {
+    if (ep.errorStatuses.length === 1) {
+      lines.push(
+        `export type ${pascal}Error =`,
+        `  paths['${ep.apiPath}']['${ep.method}']['responses']['${ep.errorStatuses[0]}']['content']['application/json'];`,
+        ''
+      );
+    } else {
+      lines.push(`export type ${pascal}Error =`);
+      for (const code of ep.errorStatuses) {
+        lines.push(
+          `  | paths['${ep.apiPath}']['${ep.method}']['responses']['${code}']['content']['application/json']`
+        );
+      }
+      lines.push('');
+    }
+  }
 
   const responseT = hasResponse ? `${pascal}Response` : 'unknown';
   const fnArgs = buildFnArgs(ep, pascal, isGet);