genoc 0.1.2 → 0.2.0

package/README.md

@@ -1,7 +1,7 @@
 # genoc
 
 Generate TypeScript HTTP clients from OpenAPI 3.0 / 3.1 specifications.
-The generated code has zero runtime dependencies. Full type safety. Bring your own HTTP client.
+Generated code depends only on the tiny `genoc/runtime` module. Full type safety. Bring your own HTTP client.
 
 [![npm version](https://img.shields.io/npm/v/genoc)](https://www.npmjs.com/package/genoc)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org/)
@@ -13,6 +13,7 @@ The generated code has zero runtime dependencies. Full type safety. Bring your o
 - Full OpenAPI 3.0 and 3.1 specification support with automatic version detection
 - End-to-end type safety — requests, responses, and errors are fully typed
 - HTTP-client agnostic — adapter pattern lets you plug in fetch, axios, or anything else
+- Shared runtime contract — `genoc/runtime` exports the `Requester` type and response/error classes, so one requester implementation works with every generated client
 - Error types with per-status-code narrowing and type guards
 - File and binary upload/download with stream handling
 - Flexible method naming strategies (path-based, operationId, operationId-with-fallback)
@@ -23,9 +24,12 @@ The generated code has zero runtime dependencies. Full type safety. Bring your o
 Install:
 
 ```bash
-npm install -D genoc
+npm install genoc
 ```
 
+Generated code imports from `genoc/runtime`, so `genoc` is a runtime
+dependency (not just `devDependencies`).
+
 Generate:
 
 ```bash
@@ -40,8 +44,13 @@ This creates two files in `./src/api`:
 ## Usage
 
 The generated client requires a `Requester` implementation — a function that
-performs the actual HTTP call and returns the result. This is the type your
-implementation must satisfy:
+performs the actual HTTP call and returns the result. The type lives in
+`genoc/runtime`, so you can write and compile a requester before generating
+anything:
+
+```typescript
+import type { Requester } from 'genoc/runtime';
+```
 
 ```typescript
 type Requester = <TResponse>(
@@ -60,7 +69,8 @@ type Requester = <TResponse>(
 
 ```typescript
 import { createClient } from './client.js';
-import { ApiError, RequesterFailError, ErrorResponse } from './contracts.js';
+import type { Requester } from 'genoc/runtime';
+import { RequesterFailError, ErrorResponse } from 'genoc/runtime';
 
 const baseUrl = 'https://api.example.com';
 
@@ -85,7 +95,7 @@ const requester: Requester = async (method, path, options) => {
     return new ErrorResponse(
       response.status,
       await response.json(),
-      response.headers,
+      Object.fromEntries(response.headers.entries()),
       response.statusText
     );
   }
@@ -101,6 +111,27 @@ const pets = await client.getPets({ limit: 10 });
 
 See [Binary / File Responses](#binary--file-responses) for handling `expectStream: true`.
 
+## Shared Runtime (`genoc/runtime`)
+
+Generated clients import their response and error classes from `genoc/runtime`
+instead of declaring inline copies (the generated `contracts.ts` re-exports
+them, so existing imports keep working). This gives every generated client the
+same class identity — `instanceof` checks work across clients, and you can
+implement **one shared requester** typed against the package:
+
+```typescript
+// common-requester.ts — reusable across all generated clients,
+// no generated imports needed
+import type { Requester } from 'genoc/runtime';
+
+export const requester: Requester = async (method, path, options) => {
+  // ...your fetch/axios/etc. implementation
+};
+```
+
+To pin a specific version or point at a mirror, override the import specifier
+via `--runtime-import-path` (CLI) or `runtimeImportPath` (programmatic config).
+
 ## Binary / File Responses
 
 When your spec defines binary responses (e.g. `format: binary`,
@@ -109,14 +140,14 @@ When your spec defines binary responses (e.g. `format: binary`,
 `StreamResponse` in that case:
 
 ```typescript
-import { StreamResponse } from './contracts.js';
+import { StreamResponse } from 'genoc/runtime';
 
 // Inside your Requester implementation:
 if (options.expectStream === true) {
   return new StreamResponse(
     response.body as ReadableStream<Uint8Array>,
     getFilename(response.headers), // extract from Content-Disposition
-    response.headers
+    Object.fromEntries(response.headers.entries())
   );
 }
 ```
@@ -131,17 +162,6 @@ class StreamResponse {
 }
 ```
 
-### Response Helpers
-
-The generated `contracts.ts` includes helper functions for constructing
-responses in your `Requester` implementation:
-
-- `streamResponse(data, filename?, headers?)` — Creates a `StreamResponse` instance
-- `errorResponse(status, data, headers?, message?)` — Creates an `ErrorResponse` instance
-
-These are convenience wrappers around the `StreamResponse` and `ErrorResponse`
-constructors.
-
 ## CLI Reference
 
 ```bash
@@ -150,12 +170,13 @@ genoc <spec> [flags]
 
 `<spec>` — Path or URL to an OpenAPI 3.0 / 3.1 spec (JSON or YAML).
 
-| Flag                     | Default      | Description                                          |
-| ------------------------ | ------------ | ---------------------------------------------------- |
-| `--output-dir`           | (required)   | Output directory for generated files                 |
-| `--method-name-strategy` | `path-based` | Method naming strategy                               |
-| `--spec-version`         | auto-detect  | Override version detection (`"3.0"` or `"3.1"`)      |
-| `--strict-version`       | `true`       | Warn if `--spec-version` mismatches detected version |
+| Flag                     | Default         | Description                                                  |
+| ------------------------ | --------------- | ------------------------------------------------------------ |
+| `--output-dir`           | (required)      | Output directory for generated files                         |
+| `--method-name-strategy` | `path-based`    | Method naming strategy                                       |
+| `--spec-version`         | auto-detect     | Override version detection (`"3.0"` or `"3.1"`)              |
+| `--strict-version`       | `true`          | Warn if `--spec-version` mismatches detected version         |
+| `--runtime-import-path`  | `genoc/runtime` | Module specifier generated code imports runtime classes from |
 
 ## Method Naming Strategies
 
@@ -168,6 +189,15 @@ genoc <spec> [flags]
 - **`operationId-with-fallback`** — Use `operationId` if present, otherwise
   fall back to path-based naming.
 
+## JSDoc Documentation Output
+
+`description`, `deprecated`, `default`, `example`/`examples`, and `title`
+fields from your spec become JSDoc comments in the generated code — on object
+type properties, named schemas, and client methods. Object types are always
+emitted multi-line, so per-property JSDoc stays aligned at each nesting depth.
+`@deprecated` tags give you editor strikethrough on deprecated fields and
+methods for free.
+
 ## Programmatic API
 
 ```typescript
@@ -194,7 +224,7 @@ union, and `isDefinedError` narrows a caught error to that union:
 
 ```typescript
 import { UnspecifiedApiError, RequesterFailError } from './contracts.js';
-import { isDefinedError } from './client.js';
+import { isDefinedError } from 'genoc/runtime';
 
 try {
   const result = await client.getPets();

package/dist/analyzer/path-analyzer.d.ts

@@ -9,6 +9,7 @@ export interface AnalyzedParameter {
     tsType: string;
     description?: string;
     deprecated?: boolean;
+    example?: unknown;
 }
 export interface AnalyzedRequestBody {
     required: boolean;
@@ -16,6 +17,7 @@ export interface AnalyzedRequestBody {
     schema: SchemaObject | ReferenceObject | undefined;
     tsType: string;
     isMultipart: boolean;
+    description?: string;
 }
 export interface AnalyzedResponse {
     statusCode: string;

package/dist/analyzer/path-analyzer.js

@@ -1,4 +1,5 @@
 import { RefResolver } from '../parser/ref-resolver.js';
+import { sanitizeTypeName } from '../utils/generator-helpers.js';
 import { getMethodName } from './naming.js';
 const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace'];
 function isRef(obj) {
@@ -21,7 +22,7 @@ function schemaToTsType(schema, resolver) {
     if (isRef(schema)) {
         const resolved = resolver.resolve(schema);
         const refStr = schema.$ref;
-        const lastSegment = refStr.split('/').pop();
+        const lastSegment = sanitizeTypeName(refStr.split('/').pop());
         if (lastSegment && resolved.type) {
             return lastSegment;
         }
@@ -77,6 +78,7 @@ function analyzeParameter(param, resolver) {
         tsType: schemaToTsType(param.schema, resolver),
         description: param.description,
         deprecated: param.deprecated,
+        example: param.example,
     };
 }
 function mergeParameters(pathItemParams, operationParams, resolver) {
@@ -119,6 +121,7 @@ function analyzeRequestBody(body, resolver) {
         schema,
         tsType,
         isMultipart,
+        description: resolved.description,
     };
 }
 function analyzeResponses(responses, resolver) {

package/dist/analyzer/schema-mapper.d.ts

@@ -44,5 +44,13 @@ export declare class SchemaMapper {
     private mapDiscriminatedUnion;
     private resolveDiscriminantValue;
     private mapArray;
+    /**
+     * Render the per-property JSDoc comment lines for an object property.
+     *
+     * Metadata comes from the property's own schema node; for a `$ref` property
+     * the resolved target's own node metadata is used (one level only — never
+     * recursed), so self-referential schemas cannot loop here.
+     */
+    private renderPropertyJsDoc;
     private mapObject;
 }

package/dist/analyzer/schema-mapper.js

@@ -1,13 +1,20 @@
 import { RefResolver } from '../parser/ref-resolver.js';
 import { formatToBrandTypeName } from '../utils/case.js';
+import { buildTypeJsDoc, sanitizeTypeName } from '../utils/generator-helpers.js';
 import { quoteKey } from '../utils/string.js';
+/** Indentation contract for multi-line types — 2-space unit pinned from the generated ServerParams interface; binding for downstream generators. */
+const INDENT_UNIT = '  ';
+function indentBy(level) {
+    return INDENT_UNIT.repeat(level);
+}
 /**
  * Default: extracts the last segment of the JSON pointer.
  * "#/components/schemas/User" -> "User"
  */
 function defaultTypeNameGenerator(refString) {
     const segments = refString.split('/');
-    return segments[segments.length - 1] || 'unknown';
+    const rawSegment = segments[segments.length - 1] || 'unknown';
+    return sanitizeTypeName(rawSegment);
 }
 function isRefObject(obj) {
     return (obj !== null &&
@@ -56,7 +63,7 @@ export class SchemaMapper {
             return { tsType: schema ? 'unknown' : 'never', imports: [] };
         }
         const visited = new Set();
-        const result = this.mapInternal(schema, name, context, visited);
+        const result = this.mapInternal(schema, name, context, visited, 0);
         if (name && this.discriminatorTargets.has(name)) {
             const target = this.discriminatorTargets.get(name);
             result.tsType += ` & { ${quoteKey(target.propertyName)}: '${target.literalValue}' }`;
@@ -73,7 +80,7 @@ export class SchemaMapper {
             return null;
         return brandName;
     }
-    mapInternal(schema, name, context, visited) {
+    mapInternal(schema, name, context, visited, indent) {
         if (isRefObject(schema)) {
             const refStr = schema.$ref;
             const refName = this.typeNameGenerator(refStr);
@@ -87,7 +94,7 @@ export class SchemaMapper {
             if (resolved) {
                 const discInfo = this.resolveDiscriminatorInfo(resolved, refStr);
                 if (discInfo) {
-                    const expanded = this.mapInternal(resolved, undefined, context, visited);
+                    const expanded = this.mapInternal(resolved, undefined, context, visited, indent);
                     expanded.tsType += ` & { ${quoteKey(discInfo.propertyName)}: '${discInfo.literalValue}' }`;
                     return expanded;
                 }
@@ -119,7 +126,7 @@ export class SchemaMapper {
             return { tsType, imports: [] };
         }
         if (s.allOf !== undefined && s.allOf.length > 0) {
-            const result = this.mapCombinator(s.allOf, '&', context, visited);
+            const result = this.mapCombinator(s.allOf, '&', context, visited, indent);
             if (s.nullable === true) {
                 return {
                     tsType: needsParens(result.tsType)
@@ -132,8 +139,8 @@ export class SchemaMapper {
         }
         if (s.oneOf !== undefined && s.oneOf.length > 0) {
             const result = s.discriminator
-                ? this.mapDiscriminatedUnion(s.oneOf, s.discriminator, context, visited)
-                : this.mapCombinator(s.oneOf, '|', context, visited);
+                ? this.mapDiscriminatedUnion(s.oneOf, s.discriminator, context, visited, indent)
+                : this.mapCombinator(s.oneOf, '|', context, visited, indent);
             if (s.nullable === true) {
                 return {
                     tsType: needsParens(result.tsType)
@@ -146,8 +153,8 @@ export class SchemaMapper {
         }
         if (s.anyOf !== undefined && s.anyOf.length > 0) {
             const result = s.discriminator
-                ? this.mapDiscriminatedUnion(s.anyOf, s.discriminator, context, visited)
-                : this.mapCombinator(s.anyOf, '|', context, visited);
+                ? this.mapDiscriminatedUnion(s.anyOf, s.discriminator, context, visited, indent)
+                : this.mapCombinator(s.anyOf, '|', context, visited, indent);
             if (s.nullable === true) {
                 return {
                     tsType: needsParens(result.tsType)
@@ -167,7 +174,7 @@ export class SchemaMapper {
             if (nonNull.length === 0) {
                 return { tsType: 'null', imports: [] };
             }
-            const baseResult = this.mapInternal({ ...s, type: nonNull[0] }, name, context, new Set(visited));
+            const baseResult = this.mapInternal({ ...s, type: nonNull[0] }, name, context, new Set(visited), indent);
             if (hasNull) {
                 return {
                     tsType: `${baseResult.tsType} | null`,
@@ -222,15 +229,15 @@ export class SchemaMapper {
             case 'null':
                 return { tsType: 'null', imports: [] };
             case 'array':
-                return this.mapArray(s, context, visited);
+                return this.mapArray(s, context, visited, indent);
             case 'object':
-                return this.mapObject(s, name, context, visited);
+                return this.mapObject(s, name, context, visited, indent);
             default:
                 return { tsType: 'unknown', imports: [] };
         }
     }
     resolveDiscriminatorInfo(schema, refStr) {
-        const schemaName = refStr.split('/').pop();
+        const schemaName = sanitizeTypeName(refStr.split('/').pop());
         const target = this.discriminatorTargets.get(schemaName);
         if (target)
             return target;
@@ -268,8 +275,8 @@ export class SchemaMapper {
         })
             .join(' | ');
     }
-    mapCombinator(schemas, kind, context, visited) {
-        const results = schemas.map((s) => this.mapInternal(s, undefined, context, visited));
+    mapCombinator(schemas, kind, context, visited, indent) {
+        const results = schemas.map((s) => this.mapInternal(s, undefined, context, visited, indent));
         const allImports = [];
         for (const r of results) {
             allImports.push(...r.imports);
@@ -283,14 +290,14 @@ export class SchemaMapper {
         });
         return { tsType: parts.join(separator), imports: allImports };
     }
-    mapDiscriminatedUnion(schemas, discriminator, context, visited) {
+    mapDiscriminatedUnion(schemas, discriminator, context, visited, indent) {
         const propertyName = discriminator.propertyName;
         const mapping = discriminator.mapping;
         const allImports = [];
         const parts = [];
         for (const schema of schemas) {
             const discriminantValue = this.resolveDiscriminantValue(schema, propertyName, mapping);
-            const variantResult = this.mapInternal(schema, undefined, context, visited);
+            const variantResult = this.mapInternal(schema, undefined, context, visited, indent);
             allImports.push(...variantResult.imports);
             const quotedProp = quoteKey(propertyName);
             parts.push(`({ ${quotedProp}: '${discriminantValue}' } & ${variantResult.tsType})`);
@@ -321,14 +328,14 @@ export class SchemaMapper {
         }
         return 'unknown';
     }
-    mapArray(schema, context, visited) {
+    mapArray(schema, context, visited, indent) {
         if (!schema.items) {
             return {
                 tsType: schema.nullable === true ? 'unknown[] | null' : 'unknown[]',
                 imports: [],
             };
         }
-        const itemResult = this.mapInternal(schema.items, undefined, context, visited);
+        const itemResult = this.mapInternal(schema.items, undefined, context, visited, indent);
         const tsType = isComplexType(itemResult.tsType)
             ? `Array<${itemResult.tsType}>`
             : `${itemResult.tsType}[]`;
@@ -337,7 +344,33 @@ export class SchemaMapper {
             imports: itemResult.imports,
         };
     }
-    mapObject(schema, name, context, visited) {
+    /**
+     * Render the per-property JSDoc comment lines for an object property.
+     *
+     * Metadata comes from the property's own schema node; for a `$ref` property
+     * the resolved target's own node metadata is used (one level only — never
+     * recursed), so self-referential schemas cannot loop here.
+     */
+    renderPropertyJsDoc(propSchema, indentLevel) {
+        let metaSchema;
+        if (isRefObject(propSchema)) {
+            try {
+                metaSchema = this.resolver.resolveSchema(propSchema);
+            }
+            catch {
+                return [];
+            }
+        }
+        else {
+            metaSchema = propSchema;
+        }
+        const block = buildTypeJsDoc(metaSchema);
+        if (block === '')
+            return [];
+        const ind = indentBy(indentLevel);
+        return block.split('\n').map((line) => `${ind}${line}`);
+    }
+    mapObject(schema, name, context, visited, indent) {
         const properties = schema.properties ?? {};
         const requiredSet = new Set(schema.required ?? []);
         const propNames = Object.keys(properties);
@@ -352,7 +385,9 @@ export class SchemaMapper {
                 return false;
             return true;
         });
-        const propEntries = [];
+        const ownIndent = indentBy(indent);
+        const memberIndent = indentBy(indent + 1);
+        const memberLines = [];
         const allImports = [];
         if (schema.discriminator) {
             const discPropName = schema.discriminator.propertyName;
@@ -360,15 +395,16 @@ export class SchemaMapper {
             if (discIndex !== -1) {
                 filteredPropNames.splice(discIndex, 1);
             }
-            propEntries.push(`"${discPropName}": string`);
+            memberLines.push(`${memberIndent}"${discPropName}": string;`);
         }
         for (const propName of filteredPropNames) {
             const propSchema = properties[propName];
-            const propResult = this.mapInternal(propSchema, undefined, context, visited);
+            const propResult = this.mapInternal(propSchema, undefined, context, visited, indent + 1);
             allImports.push(...propResult.imports);
+            memberLines.push(...this.renderPropertyJsDoc(propSchema, indent + 1));
             const optional = requiredSet.has(propName) ? '' : '?';
             const quotedName = quoteKey(propName);
-            propEntries.push(`${quotedName}${optional}: ${propResult.tsType}`);
+            memberLines.push(`${memberIndent}${quotedName}${optional}: ${propResult.tsType};`);
         }
         const additionalProps = schema.additionalProperties;
         let indexSignature = null;
@@ -379,11 +415,11 @@ export class SchemaMapper {
             indexSignature = '[key: string]: unknown';
         }
         else if (additionalProps !== undefined && typeof additionalProps === 'object') {
-            const addPropResult = this.mapInternal(additionalProps, undefined, context, visited);
+            const addPropResult = this.mapInternal(additionalProps, undefined, context, visited, indent + 1);
             allImports.push(...addPropResult.imports);
             indexSignature = `[key: string]: ${addPropResult.tsType}`;
         }
-        const hasProps = propEntries.length > 0;
+        const hasProps = memberLines.length > 0;
         const hasIndex = indexSignature !== null;
         let result;
         if (!hasProps && !hasIndex) {
@@ -398,7 +434,7 @@ export class SchemaMapper {
             const valueType = indexSignature.replace('[key: string]: ', '');
             if (name) {
                 result = {
-                    tsType: `{ ${indexSignature}; }`,
+                    tsType: `{\n${memberIndent}${indexSignature};\n${ownIndent}}`,
                     imports: allImports,
                 };
             }
@@ -410,16 +446,17 @@ export class SchemaMapper {
             }
         }
         else {
-            const propsBody = propEntries.join('; ') + ';';
+            const propsBlock = `{\n${memberLines.join('\n')}\n${ownIndent}}`;
             if (hasIndex) {
+                const indexBlock = `{\n${memberIndent}${indexSignature};\n${ownIndent}}`;
                 result = {
-                    tsType: `{ ${propsBody} } & { ${indexSignature}; }`,
+                    tsType: `${propsBlock} & ${indexBlock}`,
                     imports: allImports,
                 };
             }
             else {
                 result = {
-                    tsType: `{ ${propsBody} }`,
+                    tsType: propsBlock,
                     imports: allImports,
                 };
             }

package/dist/cli/app.d.ts

@@ -3,6 +3,7 @@ interface Flags {
     methodNameStrategy: 'path-based' | 'operationId' | 'operationId-with-fallback';
     specVersion?: string;
     strictVersion: boolean;
+    runtimeImportPath?: string;
 }
 export type AppFlags = Flags;
 export declare const app: import("@stricli/core").Application<import("@stricli/core").CommandContext>;

package/dist/cli/app.js

@@ -29,6 +29,13 @@ const command = buildCommand({
                 default: true,
                 brief: 'Enable strict version checking',
             },
+            runtimeImportPath: {
+                kind: 'parsed',
+                parse: String,
+                brief: 'Module specifier for runtime imports (default: genoc/runtime)',
+                optional: true,
+                placeholder: 'module',
+            },
         },
         positional: {
             kind: 'tuple',

package/dist/cli/impl.js

@@ -27,6 +27,7 @@ export default async function (flags, spec) {
             methodNameStrategy: flags.methodNameStrategy || 'path-based',
             specVersion: flags.specVersion,
             strictVersion: flags.strictVersion,
+            runtimeImportPath: flags.runtimeImportPath,
         };
         const preserveRefSiblings = strategy.version() === '3.1';
         this.process.stdout.write('Generating client...\n');

package/dist/generator/client-generator.js

@@ -2,7 +2,7 @@ import { mkdir, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { analyzePaths } from '../analyzer/path-analyzer.js';
 import { RefResolver } from '../parser/ref-resolver.js';
-import { getOperationTypePrefix, getSuccessType, getErrorType, makeHeader, } from '../utils/generator-helpers.js';
+import { DEFAULT_RUNTIME_IMPORT_PATH, getOperationTypePrefix, getSuccessType, getErrorType, makeHeader, } from '../utils/generator-helpers.js';
 import { generateContracts } from './contracts-generator.js';
 import { generateMethod } from './method-generator.js';
 function collectImportTypes(operations) {
@@ -156,7 +156,7 @@ function buildClientMethodBody(op) {
     }
     return tryCatchLines.join('\n');
 }
-function buildClientFile(operations, version) {
+function buildClientFile(operations, version, runtimeImportPath = DEFAULT_RUNTIME_IMPORT_PATH) {
     const lines = [];
     lines.push(makeHeader(version));
     const importTypes = collectImportTypes(operations);
@@ -180,47 +180,11 @@ function buildClientFile(operations, version) {
     if (hasMultipart) {
         lines.push('/* global FormData */');
     }
+    lines.push(`import { decorateWithErrors } from '${runtimeImportPath}';`);
+    lines.push(`import type { Requester } from '${runtimeImportPath}';`);
     lines.push('');
-    lines.push('function decorateWithErrors<T, E>(');
-    lines.push('  item: T,');
-    lines.push('  runtimeErrors: unknown,');
-    lines.push('): T & { __definedErrors: E } {');
-    lines.push('  Object.defineProperty(item, "__definedErrors", {');
-    lines.push('    value: runtimeErrors,');
-    lines.push('    enumerable: false,');
-    lines.push('    configurable: true,');
-    lines.push('    writable: false,');
-    lines.push('  });');
-    lines.push('  return item as T & { __definedErrors: E };');
-    lines.push('}');
-    lines.push('');
-    lines.push('export function isDefinedError<E extends ApiError<number, unknown>>(');
-    lines.push('  err: unknown,');
-    lines.push('  fn: { __definedErrors: E },');
-    lines.push('): err is E {');
-    lines.push('  if (err instanceof UnspecifiedApiError) return false;');
-    lines.push('  if (!(err instanceof ApiError)) return false;');
-    lines.push('  return true;');
-    lines.push('}');
-    lines.push('');
-    lines.push('/**');
-    lines.push(' * Performs an HTTP request and returns the response.');
-    lines.push(' *');
-    lines.push(' * When `expectStream` is true, the implementation should return');
-    lines.push(' * a `StreamResponse` containing the stream data, filename (from');
-    lines.push(' * Content-Disposition header), and response headers.');
-    lines.push(' */');
-    lines.push('export type Requester = <TResponse>(');
-    lines.push('  method: string,');
-    lines.push('  path: string,');
-    lines.push('  options: {');
-    lines.push('    query?: Record<string, unknown>;');
-    lines.push('    body?: unknown;');
-    lines.push('    headers?: Record<string, string>;');
-    lines.push('    expectStream?: true;');
-    lines.push('  },');
-    lines.push(') => Promise<TResponse | StreamResponse | ErrorResponse>;');
-    lines.push('');
+    lines.push(`export { isDefinedError } from '${runtimeImportPath}';`);
+    lines.push(`export type { Requester } from '${runtimeImportPath}';`);
     lines.push('');
     lines.push('export function createClient(requester: Requester) {');
     lines.push('  return {');
@@ -269,9 +233,10 @@ export function generateClient(doc, config, options) {
     const resolver = new RefResolver(doc, undefined, {
         preserveRefSiblings: options?.preserveRefSiblings,
     });
-    const contracts = generateContracts(doc, resolver);
+    const runtimeImportPath = config.runtimeImportPath ?? DEFAULT_RUNTIME_IMPORT_PATH;
+    const contracts = generateContracts(doc, resolver, runtimeImportPath);
     const operations = analyzePaths(doc, resolver, config.methodNameStrategy ?? 'path-based');
-    const client = buildClientFile(operations, doc.openapi);
+    const client = buildClientFile(operations, doc.openapi, runtimeImportPath);
     return { contracts, client };
 }
 /**

package/dist/generator/contracts-generator.d.ts

@@ -10,7 +10,6 @@ import type { OpenAPIDocument } from '../types/openapi.js';
  * 4. Header parameter types per operation
  * 5. Request body types per operation
  * 6. Response / error types per operation
- * 7. ApiError class
- * 7b. UnspecifiedApiError class
+ * 7. Runtime re-export block (shared classes from the genoc runtime package)
  */
-export declare function generateContracts(doc: OpenAPIDocument, resolver: RefResolver): string;
+export declare function generateContracts(doc: OpenAPIDocument, resolver: RefResolver, runtimeImportPath?: string): string;