genoc 0.1.3 → 0.3.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,14 @@ 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                                       |
+| `--proxy`                | (none)          | HTTP(S) proxy URL for fetching specs from URLs; overrides HTTP_PROXY/HTTPS_PROXY/NO_PROXY env vars |
 
 ## Method Naming Strategies
 
@@ -168,6 +190,36 @@ genoc <spec> [flags]
 - **`operationId-with-fallback`** — Use `operationId` if present, otherwise
   fall back to path-based naming.
 
+## Proxy Support
+
+When fetching a spec from a URL, `genoc` can route the request through an
+HTTP(S) proxy:
+
+```bash
+genoc https://api.example.com/openapi.yaml --output-dir ./src/api \
+  --proxy http://user:pass@proxy.example.com:8080
+```
+
+- Credentials are supported in the proxy URL (`user:pass@host:port`).
+- Without `--proxy`, the `HTTP_PROXY` / `HTTPS_PROXY` environment variables
+  (either casing) are respected automatically, minus `NO_PROXY` exclusions.
+- An explicit `--proxy` flag overrides environment detection entirely.
+- Programmatic equivalent: `proxy: 'http://proxy.example.com:8080'` in the
+  `generateClient` config, or an optional second argument `loadSpec(url, { proxy })`.
+- SOCKS proxies and `ALL_PROXY` are not supported.
+
+Note: if you already have `HTTP_PROXY` set in your environment, spec fetches
+now go through it (previously ignored). Use `NO_PROXY` to opt out.
+
+## 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
@@ -179,6 +231,7 @@ await generateClient({
   methodNameStrategy: 'path-based',
   specVersion: '3.1',
   strictVersion: true,
+  proxy: 'http://proxy.example.com:8080',
 });
 ```
 
@@ -194,7 +247,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/naming.js

@@ -1,4 +1,5 @@
 import { toPascalCaseSegment } from '../utils/case.js';
+import { sanitizeTypeName } from '../utils/generator-helpers.js';
 import { sanitizeIdentifier } from '../utils/string.js';
 import { isPathParam, extractParamName } from '../utils/url.js';
 /**
@@ -51,9 +52,9 @@ export function generateMethodName(method, path) {
     }
     const transformedSegments = segments.map((segment, index) => {
         if (isParam[index]) {
-            return `By${toPascalCaseSegment(segment)}`;
+            return `By${sanitizeTypeName(toPascalCaseSegment(segment))}`;
         }
-        return toPascalCaseSegment(segment);
+        return sanitizeTypeName(toPascalCaseSegment(segment));
     });
     return lowerMethod + transformedSegments.join('');
 }

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;
@@ -30,6 +32,8 @@ export interface AnalyzedOperation {
     path: string;
     operationId: string | undefined;
     methodName: string;
+    /** Deduped by analyzePaths; computed from method + path when absent. */
+    typePrefix?: string;
     summary: string | undefined;
     description: string | undefined;
     deprecated: boolean;

package/dist/analyzer/path-analyzer.js

@@ -1,5 +1,5 @@
 import { RefResolver } from '../parser/ref-resolver.js';
-import { sanitizeTypeName } from '../utils/generator-helpers.js';
+import { sanitizeTypeName, getOperationTypePrefix } from '../utils/generator-helpers.js';
 import { getMethodName } from './naming.js';
 const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace'];
 function isRef(obj) {
@@ -78,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) {
@@ -120,6 +121,7 @@ function analyzeRequestBody(body, resolver) {
         schema,
         tsType,
         isMultipart,
+        description: resolved.description,
     };
 }
 function analyzeResponses(responses, resolver) {
@@ -193,6 +195,8 @@ export function analyzePaths(doc, resolver, strategy = 'path-based') {
     const operations = [];
     if (!doc.paths)
         return operations;
+    const usedTypePrefixes = new Set();
+    const usedMethodNames = new Set();
     for (const [urlPath, pathItem] of Object.entries(doc.paths)) {
         for (const method of HTTP_METHODS) {
             const operation = pathItem[method];
@@ -219,5 +223,31 @@ export function analyzePaths(doc, resolver, strategy = 'path-based') {
             });
         }
     }
+    // Dedupe type prefixes and method names so that distinct routes folding to
+    // the same identifier (e.g. "/weird" and "/weird-", or "/Weird" and
+    // "/weird") cannot produce duplicate exported types or client methods.
+    // NOTE: analyzePaths runs twice per generation (contracts pass + client
+    // pass); this assignment must stay deterministic - it relies on insertion
+    // order and the fixed HTTP_METHODS loop - so both passes agree.
+    for (const op of operations) {
+        const baseTypePrefix = getOperationTypePrefix(op);
+        let typePrefix = baseTypePrefix;
+        let n = 2;
+        while (usedTypePrefixes.has(typePrefix)) {
+            typePrefix = `${baseTypePrefix}${n}`;
+            n += 1;
+        }
+        usedTypePrefixes.add(typePrefix);
+        op.typePrefix = typePrefix;
+        const baseMethodName = op.methodName;
+        let methodName = baseMethodName;
+        n = 2;
+        while (usedMethodNames.has(methodName)) {
+            methodName = `${baseMethodName}${n}`;
+            n += 1;
+        }
+        usedMethodNames.add(methodName);
+        op.methodName = methodName;
+    }
     return operations;
 }

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,7 +1,12 @@
 import { RefResolver } from '../parser/ref-resolver.js';
 import { formatToBrandTypeName } from '../utils/case.js';
-import { sanitizeTypeName } from '../utils/generator-helpers.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"
@@ -37,6 +42,10 @@ export class SchemaMapper {
     brandedTypes = new Map();
     static nullableWarned = false;
     constructor(resolver, typeNameGenerator, discriminatorTargets, reservedNames) {
+        // NOTE: discriminatorTargets must be keyed by names produced by the SAME
+        // (rename-aware) typeNameGenerator that resolves $refs. Passing targets
+        // keyed by raw schema names means renamed subtypes silently lose their
+        // `& { prop: 'literal' }` intersection in the generated output.
         this.resolver = resolver;
         this.typeNameGenerator = typeNameGenerator ?? defaultTypeNameGenerator;
         this.discriminatorTargets = discriminatorTargets ?? new Map();
@@ -58,7 +67,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}' }`;
@@ -75,7 +84,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);
@@ -89,7 +98,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;
                 }
@@ -121,7 +130,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)
@@ -134,8 +143,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)
@@ -148,8 +157,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)
@@ -169,7 +178,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`,
@@ -224,15 +233,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 = sanitizeTypeName(refStr.split('/').pop());
+        const schemaName = this.typeNameGenerator(refStr);
         const target = this.discriminatorTargets.get(schemaName);
         if (target)
             return target;
@@ -270,8 +279,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);
@@ -285,14 +294,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})`);
@@ -323,14 +332,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}[]`;
@@ -339,7 +348,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);
@@ -354,7 +389,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;
@@ -362,15 +399,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;
@@ -381,11 +419,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) {
@@ -400,7 +438,7 @@ export class SchemaMapper {
             const valueType = indexSignature.replace('[key: string]: ', '');
             if (name) {
                 result = {
-                    tsType: `{ ${indexSignature}; }`,
+                    tsType: `{\n${memberIndent}${indexSignature};\n${ownIndent}}`,
                     imports: allImports,
                 };
             }
@@ -412,16 +450,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,8 @@ interface Flags {
     methodNameStrategy: 'path-based' | 'operationId' | 'operationId-with-fallback';
     specVersion?: string;
     strictVersion: boolean;
+    runtimeImportPath?: string;
+    proxy?: 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,20 @@ 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',
+            },
+            proxy: {
+                kind: 'parsed',
+                parse: String,
+                brief: 'HTTP(S) proxy URL for fetching specs (overrides HTTP_PROXY/HTTPS_PROXY env vars)',
+                optional: true,
+                placeholder: 'url',
+            },
         },
         positional: {
             kind: 'tuple',

package/dist/cli/impl.js

@@ -2,11 +2,20 @@ import { generateFullOutput } from '../generator/client-generator.js';
 import { load } from '../parser/spec-reader.js';
 import { validateSpec } from '../parser/validators.js';
 import { defaultRegistry } from '../parser/version/index.js';
+import { assertValidProxyUrl } from '../utils/proxy.js';
 import { UserError } from './errors.js';
 export default async function (flags, spec) {
     try {
+        if (flags.proxy) {
+            try {
+                assertValidProxyUrl(flags.proxy);
+            }
+            catch (err) {
+                throw new UserError(err.message);
+            }
+        }
         this.process.stdout.write(`Loading spec from ${spec}...\n`);
-        const doc = await load(spec);
+        const doc = await load(spec, { proxy: flags.proxy });
         this.process.stdout.write(`Loaded OpenAPI ${doc.openapi} spec\n`);
         const strategy = flags.specVersion
             ? defaultRegistry.get(flags.specVersion)
@@ -27,6 +36,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');