genoc 0.1.3 → 0.3.0

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;

package/dist/generator/contracts-generator.js

@@ -1,7 +1,7 @@
 import { analyzePaths } from '../analyzer/path-analyzer.js';
 import { SchemaMapper } from '../analyzer/schema-mapper.js';
 import { RefResolver } from '../parser/ref-resolver.js';
-import { RESERVED_TYPE_NAMES, buildSchemaRenameMap, sanitizeTypeName, toPascalCase, getOperationTypePrefix, makeHeader, } from '../utils/generator-helpers.js';
+import { RESERVED_TYPE_NAMES, buildSchemaRenameMap, DEFAULT_RUNTIME_IMPORT_PATH, buildTypeJsDoc, sanitizeJsDocText, sanitizeTypeName, toPascalCase, getOperationTypePrefix, makeHeader, } from '../utils/generator-helpers.js';
 function isBinaryContentType(ct) {
     if (ct === 'application/octet-stream')
         return true;
@@ -22,28 +22,88 @@ function substituteDiscriminatedType(tsType, schema, discriminatorInfo, renameMa
     if (!refSchema || typeof refSchema !== 'object')
         return tsType;
     if (typeof refSchema.$ref === 'string') {
-        const schemaName = sanitizeTypeName(refSchema.$ref.split('/').pop());
+        const rawName = refSchema.$ref.split('/').pop();
+        const schemaName = sanitizeTypeName(rawName);
         if (schemaName && discriminatorInfo.has(schemaName)) {
-            const renamed = renameMap.get(schemaName) ?? schemaName;
+            const renamed = renameMap.get(rawName) ?? schemaName;
             return tsType.replace(new RegExp(`\\b${renamed}\\b`, 'g'), `${renamed}Variant`);
         }
     }
     if (refSchema.items && typeof refSchema.items === 'object') {
         const items = refSchema.items;
         if (typeof items.$ref === 'string') {
-            const schemaName = sanitizeTypeName(items.$ref.split('/').pop());
+            const rawName = items.$ref.split('/').pop();
+            const schemaName = sanitizeTypeName(rawName);
             if (schemaName && discriminatorInfo.has(schemaName)) {
-                const renamed = renameMap.get(schemaName) ?? schemaName;
+                const renamed = renameMap.get(rawName) ?? schemaName;
                 return tsType.replace(new RegExp(`\\b${renamed}\\b`, 'g'), `${renamed}Variant`);
             }
         }
     }
     return tsType;
 }
-function buildJsDoc(description) {
-    if (!description)
-        return undefined;
-    return `/** ${description} */`;
+/**
+ * Indent unit matching `INDENT_UNIT` in schema-mapper.ts (2 spaces, pinned by
+ * the mapper's golden tests). Kept local to avoid modifying the mapper module.
+ */
+const INDENT_UNIT = '  ';
+/**
+ * Build a description-only type-level JSDoc comment for operation-derived
+ * types (body / response). Returns '' when the description is absent or
+ * whitespace-only so callers can skip emission entirely.
+ */
+function buildDescriptionJsDoc(description) {
+    if (description === undefined)
+        return '';
+    const sanitized = sanitizeJsDocText(description);
+    return sanitized === '' ? '' : `/** ${sanitized} */`;
+}
+/**
+ * Prefix a type definition with its JSDoc block (single- or multi-line),
+ * keeping the comment directly above the `export type` line.
+ */
+function attachTypeJsDoc(jsDoc, definition) {
+    return jsDoc === '' ? definition : `${jsDoc}\n${definition}`;
+}
+/**
+ * Indent every line of a JSDoc block by one indent unit so property comments
+ * line up exactly with their property line (mapper indentation contract).
+ */
+function indentJsDocBlock(jsDoc) {
+    return jsDoc.split('\n').map((line) => `${INDENT_UNIT}${line}`);
+}
+/**
+ * Build the JSDoc block for a query/header parameter property using the
+ * pinned parameter merge rule: parameter-level description / deprecated /
+ * example win over the schema's; default, title and examples come from the
+ * schema only (carried by the spread).
+ */
+function buildParamPropertyJsDoc(param, schema) {
+    return buildTypeJsDoc({
+        ...schema,
+        description: param.description ?? schema.description,
+        deprecated: param.deprecated === true || schema.deprecated === true,
+        example: param.example ?? schema.example,
+    });
+}
+/**
+ * Render a `${prefix}Query` / `${prefix}Headers` object body in the mapper's
+ * multi-line format with per-property JSDoc from the parameter merge rule.
+ */
+function buildParamTypeBody(params, mapper) {
+    const lines = [];
+    for (const param of params) {
+        const paramSchema = param.schema ?? { type: 'string' };
+        const result = mapper.mapSchema(paramSchema);
+        const optional = param.required ? '' : '?';
+        const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(param.name) ? param.name : `"${param.name}"`;
+        const jsDoc = buildParamPropertyJsDoc(param, paramSchema);
+        if (jsDoc !== '') {
+            lines.push(...indentJsDocBlock(jsDoc));
+        }
+        lines.push(`${INDENT_UNIT}${key}${optional}: ${result.tsType};`);
+    }
+    return `{\n${lines.join('\n')}\n}`;
 }
 function securitySchemeToTsType(scheme) {
     const parts = [`type: "${scheme.type}"`];
@@ -150,6 +210,25 @@ function topologicalSort(entries, allNames) {
     }
     return sorted;
 }
+/**
+ * Build the import + re-export block for the shared runtime classes.
+ * Generated code re-uses the genoc runtime as the single source of truth
+ * for class identity, so `instanceof` checks work across module boundaries.
+ */
+function buildRuntimeReexport(runtimeImportPath) {
+    return [
+        '',
+        `import { ApiError, StreamResponse } from '${runtimeImportPath}';`,
+        'export {',
+        '  ApiError,',
+        '  UnspecifiedApiError,',
+        '  DefaultApiError,',
+        '  RequesterFailError,',
+        '  StreamResponse,',
+        '  ErrorResponse,',
+        `} from '${runtimeImportPath}';`,
+    ];
+}
 /**
  * Generate the complete `*.contracts.ts` file content as a string.
  *
@@ -160,22 +239,20 @@ function topologicalSort(entries, allNames) {
  * 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 function generateContracts(doc, resolver) {
+export function generateContracts(doc, resolver, runtimeImportPath = DEFAULT_RUNTIME_IMPORT_PATH) {
     const schemaNameList = doc.components?.schemas ? Object.keys(doc.components.schemas) : [];
     const renameMap = buildSchemaRenameMap(schemaNameList, RESERVED_TYPE_NAMES);
     for (const [original, renamed] of renameMap) {
         // TODO: Replace with structured logging solution
         // oxlint-disable-next-line no-console
-        console.warn(`Warning: Schema "${original}" collides with a built-in type and was renamed to "${renamed}".`);
+        console.warn(`Warning: Schema "${original}" collides with a built-in type or another schema and was renamed to "${renamed}".`);
     }
     const renamingTypeGenerator = (refString) => {
         const segments = refString.split('/');
         const rawSegment = segments[segments.length - 1] || 'unknown';
-        const lastSegment = sanitizeTypeName(rawSegment);
-        return renameMap.get(lastSegment) ?? lastSegment;
+        return renameMap.get(rawSegment) ?? sanitizeTypeName(rawSegment);
     };
     const discriminatorInfo = new Map();
     if (doc.components?.schemas) {
@@ -185,12 +262,13 @@ export function generateContracts(doc, resolver) {
                 const mapping = new Map();
                 if (resolved.discriminator.mapping) {
                     for (const [key, ref] of Object.entries(resolved.discriminator.mapping)) {
-                        const targetName = sanitizeTypeName(ref.split('/').pop() || key);
-                        const renamedTarget = renameMap.get(targetName) ?? targetName;
+                        const rawTarget = ref.split('/').pop() || key;
+                        const renamedTarget = renameMap.get(rawTarget) ?? sanitizeTypeName(rawTarget);
                         mapping.set(key, renamedTarget);
                     }
                 }
                 discriminatorInfo.set(sanitizeTypeName(name), {
+                    rawName: name,
                     propertyName: resolved.discriminator.propertyName,
                     mapping,
                 });
@@ -209,26 +287,27 @@ export function generateContracts(doc, resolver) {
     const allSchemaNames = new Set();
     if (doc.components?.schemas) {
         for (const name of Object.keys(doc.components.schemas)) {
-            allSchemaNames.add(sanitizeTypeName(name));
+            allSchemaNames.add(renameMap.get(name) ?? sanitizeTypeName(name));
         }
     }
     const mapper = new SchemaMapper(resolver, renamingTypeGenerator, discriminatorTargets, allSchemaNames);
     const lines = [];
     lines.push(makeHeader(doc.openapi));
+    const runtimeReexport = buildRuntimeReexport(runtimeImportPath);
+    lines.push(...runtimeReexport);
     // Section 1: Schema types
     const schemaEntries = [];
     if (doc.components?.schemas) {
         for (const [name, schema] of Object.entries(doc.components.schemas)) {
-            const sanitizedName = sanitizeTypeName(name);
-            const renamedName = renameMap.get(sanitizedName) ?? sanitizedName;
-            const result = mapper.mapSchema(schema, sanitizedName);
+            const renamedName = renameMap.get(name) ?? sanitizeTypeName(name);
+            const result = mapper.mapSchema(schema, renamedName);
             const resolved = resolver.resolve(schema);
             const definition = `export type ${renamedName} = ${result.tsType};`;
             schemaEntries.push({
                 name: renamedName,
                 kind: 'type',
                 definition,
-                jsDoc: buildJsDoc(resolved.description),
+                jsDoc: buildTypeJsDoc(resolved) || undefined,
             });
         }
     }
@@ -240,12 +319,12 @@ export function generateContracts(doc, resolver) {
         }
         lines.push(entry.definition);
     }
-    for (const [baseName, info] of discriminatorInfo) {
+    for (const [, info] of discriminatorInfo) {
         const subtypeNames = Array.from(info.mapping.values());
         if (subtypeNames.length === 0)
             continue;
         const unionType = subtypeNames.join(' | ');
-        const renamedBase = renameMap.get(sanitizeTypeName(baseName)) ?? sanitizeTypeName(baseName);
+        const renamedBase = renameMap.get(info.rawName) ?? sanitizeTypeName(info.rawName);
         lines.push('');
         lines.push(`export type ${renamedBase}Variant = ${unionType};`);
         allSchemaNames.add(`${renamedBase}Variant`);
@@ -254,12 +333,21 @@ export function generateContracts(doc, resolver) {
     const securitySchemes = doc.components?.securitySchemes;
     if (securitySchemes && Object.keys(securitySchemes).length > 0) {
         const securityTypeNames = [];
+        const usedSecurityTypeNames = new Set();
         for (const [schemeName, scheme] of Object.entries(securitySchemes)) {
-            const typeName = `${toPascalCase(schemeName)}Auth`;
+            const baseTypeName = `${sanitizeTypeName(toPascalCase(schemeName))}Auth`;
+            let typeName = baseTypeName;
+            let n = 2;
+            while (usedSecurityTypeNames.has(typeName)) {
+                typeName = `${baseTypeName}${n}`;
+                n += 1;
+            }
+            usedSecurityTypeNames.add(typeName);
             const tsType = securitySchemeToTsType(scheme);
-            if (scheme.description) {
+            const schemeJsDoc = buildDescriptionJsDoc(scheme.description);
+            if (schemeJsDoc !== '') {
                 lines.push('');
-                lines.push(buildJsDoc(scheme.description));
+                lines.push(schemeJsDoc);
             }
             lines.push('');
             lines.push(`export type ${typeName} = ${tsType};`);
@@ -283,10 +371,13 @@ export function generateContracts(doc, resolver) {
                 const sv = variable;
                 const jsDocParts = [];
                 if (sv.description) {
-                    jsDocParts.push(sv.description);
+                    const description = sanitizeJsDocText(sv.description);
+                    if (description !== '') {
+                        jsDocParts.push(description);
+                    }
                 }
                 if (sv.default !== undefined) {
-                    jsDocParts.push(`@default ${sv.default}`);
+                    jsDocParts.push(`@default ${sanitizeJsDocText(String(sv.default))}`);
                 }
                 let tsType;
                 if (sv.enum && sv.enum.length > 0) {
@@ -327,31 +418,19 @@ export function generateContracts(doc, resolver) {
         const opLines = [];
         // Section 2: Query parameter types
         if (op.queryParams.length > 0) {
-            const props = op.queryParams.map((param) => {
-                const paramSchema = param.schema ?? { type: 'string' };
-                const result = mapper.mapSchema(paramSchema);
-                const optional = param.required ? '' : '?';
-                const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(param.name) ? param.name : `"${param.name}"`;
-                return `${key}${optional}: ${result.tsType}`;
-            });
-            opLines.push(`export type ${prefix}Query = { ${props.join('; ')}; };`);
+            opLines.push(`export type ${prefix}Query = ${buildParamTypeBody(op.queryParams, mapper)};`);
         }
         // Section 2b: Header parameter types
         if (op.headerParams.length > 0) {
-            const props = op.headerParams.map((param) => {
-                const paramSchema = param.schema ?? { type: 'string' };
-                const result = mapper.mapSchema(paramSchema);
-                const optional = param.required ? '' : '?';
-                const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(param.name) ? param.name : `"${param.name}"`;
-                return `${key}${optional}: ${result.tsType}`;
-            });
-            opLines.push(`export type ${prefix}Headers = { ${props.join('; ')}; };`);
+            opLines.push(`export type ${prefix}Headers = ${buildParamTypeBody(op.headerParams, mapper)};`);
         }
         // Section 3: Request body types
+        const bodyJsDoc = op.requestBody ? buildDescriptionJsDoc(op.requestBody.description) : '';
         if (op.requestBody?.isMultipart && op.requestBody.schema) {
             const schema = resolver.resolveSchema(op.requestBody.schema);
             const requiredSet = new Set(schema.required ?? []);
-            const props = Object.entries(schema.properties ?? {}).map(([name, propSchema]) => {
+            const propLines = [];
+            for (const [name, propSchema] of Object.entries(schema.properties ?? {})) {
                 const resolved = resolver.resolveSchema(propSchema);
                 const optional = requiredSet.has(name) ? '' : '?';
                 let tsType;
@@ -364,23 +443,27 @@ export function generateContracts(doc, resolver) {
                 else {
                     tsType = 'string';
                 }
-                return `${name}${optional}: ${tsType}`;
-            });
-            if (props.length > 0) {
-                opLines.push(`export type ${prefix}Body = { ${props.join('; ')}; };`);
+                const jsDoc = buildTypeJsDoc(resolved);
+                if (jsDoc !== '') {
+                    propLines.push(...indentJsDocBlock(jsDoc));
+                }
+                propLines.push(`${INDENT_UNIT}${name}${optional}: ${tsType};`);
+            }
+            if (propLines.length > 0) {
+                opLines.push(attachTypeJsDoc(bodyJsDoc, `export type ${prefix}Body = {\n${propLines.join('\n')}\n};`));
             }
             else {
-                opLines.push(`export type ${prefix}Body = Record<string, never>;`);
+                opLines.push(attachTypeJsDoc(bodyJsDoc, `export type ${prefix}Body = Record<string, never>;`));
             }
         }
         else if (op.requestBody?.schema) {
             const hasBinaryContentType = op.requestBody.contentTypes.some(isBinaryContentType);
             if (hasBinaryContentType) {
-                opLines.push(`export type ${prefix}Body = Blob;`);
+                opLines.push(attachTypeJsDoc(bodyJsDoc, `export type ${prefix}Body = Blob;`));
             }
             else {
                 const result = mapper.mapSchema(op.requestBody.schema, undefined, 'request');
-                opLines.push(`export type ${prefix}Body = ${result.tsType};`);
+                opLines.push(attachTypeJsDoc(bodyJsDoc, `export type ${prefix}Body = ${result.tsType};`));
             }
         }
         // Section 4: Response types
@@ -399,7 +482,10 @@ export function generateContracts(doc, resolver) {
                 return r.tsType;
             });
             const successType = types.length === 1 ? types[0] : types.join(' | ');
-            opLines.push(`export type ${prefix}Response = ${successType};`);
+            // Type-level JSDoc from the lowest-numbered 2xx response (the analyzer
+            // returns success responses in ascending status order).
+            const responseJsDoc = buildDescriptionJsDoc(successResponses[0].description);
+            opLines.push(attachTypeJsDoc(responseJsDoc, `export type ${prefix}Response = ${successType};`));
         }
         // Error types per status
         const errorTypes = [];
@@ -452,92 +538,7 @@ export function generateContracts(doc, resolver) {
         for (const brand of brandedTypes.values()) {
             brandLines.push(`export type ${brand.name} = ${brand.baseType} & { readonly __format?: '${brand.format}' };`);
         }
-        lines.splice(1, 0, '', ...brandLines);
-    }
-    // Always emit StreamResponse class (used by Requester type)
-    lines.push('');
-    lines.push('export class StreamResponse {');
-    lines.push('  constructor(');
-    lines.push('    public readonly data: ReadableStream<Uint8Array>,');
-    lines.push('    public readonly filename?: string,');
-    lines.push('    public readonly headers: Record<string, string> = {},');
-    lines.push('  ) {}');
-    lines.push('}');
-    lines.push('');
-    lines.push(`export function streamResponse(
-  data: ReadableStream<Uint8Array>,
-  filename?: string,
-  headers?: Record<string, string>,
-): StreamResponse {
-  return new StreamResponse(data, filename, headers ?? {});
-}`);
-    // ErrorResponse class
-    lines.push('');
-    lines.push(`export class ErrorResponse {
-  constructor(
-    public readonly status: number,
-    public readonly data: unknown,
-    public readonly headers: Record<string, string>,
-    public readonly message?: string,
-  ) {}
-}`);
-    // errorResponse() helper
-    lines.push('');
-    lines.push(`export function errorResponse(
-  status: number,
-  data: unknown,
-  headers?: Record<string, string>,
-  message?: string,
-): ErrorResponse {
-  return new ErrorResponse(status, data, headers ?? {}, message);
-}`);
-    // RequesterFailError class
-    lines.push('');
-    lines.push(`export class RequesterFailError extends Error {
-  constructor(
-    public readonly cause: unknown,
-  ) {
-    super(\`Request failed: \${cause instanceof Error ? cause.message : String(cause)}\`);
-    this.name = "RequesterFailError";
-  }
-}`);
-    // Section 5: ApiError class
-    lines.push('');
-    lines.push(`export class ApiError<TStatus extends number, TData> extends Error {
-  constructor(
-    public readonly status: TStatus,
-    public readonly data: TData,
-    message: string,
-  ) {
-    super(message);
-    this.name = "ApiError";
-  }
-}`);
-    // Section 5b: UnspecifiedApiError class
-    lines.push('');
-    lines.push(`export class UnspecifiedApiError extends ApiError<number, unknown> {
-  constructor(
-    status: number,
-    data: unknown,
-    message: string,
-  ) {
-    super(status, data, message);
-    this.name = "UnspecifiedApiError";
-  }
-}`);
-    const needsDefaultApiError = operations.some((op) => op.responses.some((r) => !r.isSuccess && r.statusCode === 'default'));
-    if (needsDefaultApiError) {
-        lines.push('');
-        lines.push(`export class DefaultApiError<TData> extends Error {
-  constructor(
-    public readonly status: number,
-    public readonly data: TData,
-    message: string,
-  ) {
-    super(message);
-    this.name = "DefaultApiError";
-  }
-}`);
+        lines.splice(1 + runtimeReexport.length, 0, '', ...brandLines);
     }
     return lines.join('\n');
 }

package/dist/generator/method-generator.js

@@ -1,4 +1,4 @@
-import { getOperationTypePrefix, getSuccessType } from '../utils/generator-helpers.js';
+import { getOperationTypePrefix, getSuccessType, sanitizeJsDocText, } from '../utils/generator-helpers.js';
 function buildParameters(op) {
     const params = [];
     for (const param of op.pathParams) {
@@ -42,6 +42,16 @@ function buildJsDoc(op) {
         }
         lines.push(` * ${op.description}`);
     }
+    // Responses iterate ascending-numeric with 'default' last (Object.entries
+    // integer-key semantics in path-analyzer), so the first success is the
+    // lowest-numbered 2xx. No fallback to later 2xx when it is undescribed.
+    const firstSuccess = op.responses.find((response) => response.isSuccess);
+    if (firstSuccess?.description !== undefined && firstSuccess.description.trim() !== '') {
+        if (lines.length > 0) {
+            lines.push(' *');
+        }
+        lines.push(` * ${sanitizeJsDocText(firstSuccess.description)}`);
+    }
     const allParams = [...op.pathParams, ...op.queryParams, ...op.headerParams, ...op.cookieParams];
     const paramsWithDescriptions = allParams.filter((param) => param.description);
     if (paramsWithDescriptions.length > 0) {

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import { type ApiClient } from './generator/client-generator.js';
-import { ApiError, DefaultApiError } from './generator/error-types.js';
 import type { GeneratorConfig } from './types/client.js';
+import { type LoadOptions } from './utils/proxy.js';
 export declare function generateClient(config: GeneratorConfig): Promise<void>;
-export type { GeneratorConfig, ApiClient, ApiError, DefaultApiError };
+export { ApiError, UnspecifiedApiError, DefaultApiError, RequesterFailError, StreamResponse, ErrorResponse, decorateWithErrors, isDefinedError, } from './runtime/index.js';
+export type { Requester } from './runtime/index.js';
+export type { GeneratorConfig, ApiClient, LoadOptions };
 export type { GenerationOptions } from './generator/client-generator.js';
 export { load as loadSpec } from './parser/spec-reader.js';

package/dist/index.js

@@ -1,8 +1,11 @@
 import { generateFullOutput } from './generator/client-generator.js';
-import { ApiError, DefaultApiError } from './generator/error-types.js';
 import { load } from './parser/spec-reader.js';
+import { assertValidProxyUrl } from './utils/proxy.js';
 export async function generateClient(config) {
-    const doc = await load(config.input);
+    if (config.proxy)
+        assertValidProxyUrl(config.proxy);
+    const doc = await load(config.input, { proxy: config.proxy });
     await generateFullOutput(doc, config);
 }
+export { ApiError, UnspecifiedApiError, DefaultApiError, RequesterFailError, StreamResponse, ErrorResponse, decorateWithErrors, isDefinedError, } from './runtime/index.js';
 export { load as loadSpec } from './parser/spec-reader.js';

package/dist/parser/spec-reader.d.ts

@@ -1,4 +1,5 @@
 import type { OpenAPIDocument } from '../types/openapi.js';
+import { type LoadOptions } from '../utils/proxy.js';
 export declare function loadFromFile(filePath: string): Promise<OpenAPIDocument>;
-export declare function loadFromUrl(url: string): Promise<OpenAPIDocument>;
-export declare function load(source: string): Promise<OpenAPIDocument>;
+export declare function loadFromUrl(url: string, opts?: LoadOptions): Promise<OpenAPIDocument>;
+export declare function load(source: string, opts?: LoadOptions): Promise<OpenAPIDocument>;

package/dist/parser/spec-reader.js

@@ -1,6 +1,7 @@
 import { readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { parse as parseYaml } from 'yaml';
+import { fetchSpec } from '../utils/proxy.js';
 import { isUrl } from '../utils/url.js';
 const VALID_EXTENSIONS = ['.json', '.yaml', '.yml'];
 const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50MB
@@ -74,10 +75,10 @@ export async function loadFromFile(filePath) {
     assertSupportedVersion(doc);
     return doc;
 }
-export async function loadFromUrl(url) {
+export async function loadFromUrl(url, opts) {
     let response;
     try {
-        response = await fetch(url);
+        response = await fetchSpec(url, opts);
     }
     catch (err) {
         throw new Error(`Failed to fetch spec from URL: ${err.message}`, { cause: err });
@@ -108,9 +109,9 @@ export async function loadFromUrl(url) {
     assertSupportedVersion(doc);
     return doc;
 }
-export async function load(source) {
+export async function load(source, opts) {
     if (isUrl(source)) {
-        return loadFromUrl(source);
+        return loadFromUrl(source, opts);
     }
     return loadFromFile(source);
 }

package/dist/runtime/defined-errors.d.ts

@@ -0,0 +1,17 @@
+import { ApiError } from './errors.js';
+/**
+ * Attaches the `__definedErrors` metadata property to a client method.
+ * The property carries the method's error codes and is used by
+ * `isDefinedError` for type narrowing.
+ */
+export declare function decorateWithErrors<T, E>(item: T, runtimeErrors: unknown): T & {
+    __definedErrors: E;
+};
+/**
+ * Type guard that narrows a caught error to a method's defined error union.
+ * Returns false for `UnspecifiedApiError` (status not declared in the spec)
+ * and for anything that is not an `ApiError`.
+ */
+export declare function isDefinedError<E extends ApiError<number, unknown>>(err: unknown, _fn: {
+    __definedErrors: E;
+}): err is E;