genoc 0.2.0 → 0.3.0

package/README.md

@@ -170,13 +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         |
-| `--runtime-import-path`  | `genoc/runtime` | Module specifier generated code imports runtime classes from |
+| 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
 
@@ -189,6 +190,27 @@ 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`
@@ -209,6 +231,7 @@ await generateClient({
   methodNameStrategy: 'path-based',
   specVersion: '3.1',
   strictVersion: true,
+  proxy: 'http://proxy.example.com:8080',
 });
 ```
 

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

@@ -32,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) {
@@ -195,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];
@@ -221,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.js

@@ -42,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();
@@ -237,7 +241,7 @@ export class SchemaMapper {
         }
     }
     resolveDiscriminatorInfo(schema, refStr) {
-        const schemaName = sanitizeTypeName(refStr.split('/').pop());
+        const schemaName = this.typeNameGenerator(refStr);
         const target = this.discriminatorTargets.get(schemaName);
         if (target)
             return target;

package/dist/cli/app.d.ts

@@ -4,6 +4,7 @@ interface Flags {
     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

@@ -36,6 +36,13 @@ const command = buildCommand({
                 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)

package/dist/generator/contracts-generator.js

@@ -22,18 +22,20 @@ 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`);
             }
         }
@@ -245,13 +247,12 @@ export function generateContracts(doc, resolver, runtimeImportPath = DEFAULT_RUN
     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) {
@@ -261,12 +262,13 @@ export function generateContracts(doc, resolver, runtimeImportPath = DEFAULT_RUN
                 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,
                 });
@@ -285,7 +287,7 @@ export function generateContracts(doc, resolver, runtimeImportPath = DEFAULT_RUN
     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);
@@ -297,9 +299,8 @@ export function generateContracts(doc, resolver, runtimeImportPath = DEFAULT_RUN
     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({
@@ -318,12 +319,12 @@ export function generateContracts(doc, resolver, runtimeImportPath = DEFAULT_RUN
         }
         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`);
@@ -332,8 +333,16 @@ export function generateContracts(doc, resolver, runtimeImportPath = DEFAULT_RUN
     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);
             const schemeJsDoc = buildDescriptionJsDoc(scheme.description);
             if (schemeJsDoc !== '') {

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { type ApiClient } from './generator/client-generator.js';
 import type { GeneratorConfig } from './types/client.js';
+import { type LoadOptions } from './utils/proxy.js';
 export declare function generateClient(config: GeneratorConfig): Promise<void>;
 export { ApiError, UnspecifiedApiError, DefaultApiError, RequesterFailError, StreamResponse, ErrorResponse, decorateWithErrors, isDefinedError, } from './runtime/index.js';
 export type { Requester } from './runtime/index.js';
-export type { GeneratorConfig, ApiClient };
+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,7 +1,10 @@
 import { generateFullOutput } from './generator/client-generator.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';

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/types/client.d.ts

@@ -7,6 +7,7 @@ export type GeneratorConfig = {
     specVersion?: string;
     strictVersion?: boolean;
     runtimeImportPath?: string;
+    proxy?: string;
 };
 export type RequesterFunction = <TResponse>(method: string, path: string, options: {
     query?: Record<string, unknown>;

package/dist/utils/generator-helpers.d.ts

@@ -9,15 +9,32 @@ export declare const RESERVED_TYPE_NAMES: ReadonlySet<string>;
 /** Default module specifier generated code imports shared runtime classes from. */
 export declare const DEFAULT_RUNTIME_IMPORT_PATH = "genoc/runtime";
 /**
- * Sanitize a schema type name by converting dot-separated segments into
- * PascalCase. Names without dots pass through unchanged.
+ * Sanitize a schema type name into a valid TypeScript identifier.
  *
- * "Api.Error" → "ApiError", "Simple" → "Simple"
+ * Any run of non-identifier characters (dots, brackets, backticks, hyphens,
+ * spaces, slashes, ...) splits the name into segments that are re-joined in
+ * PascalCase:
+ *
+ *   "Api.Error"  → "ApiError"
+ *   "User[Dto]"  → "UserDto"
+ *   "my-schema"  → "MySchema"
+ *   "payment id" → "PaymentId"
+ *
+ * Names that are already valid identifiers pass through unchanged
+ * ("User", "my_schema", "mySchema", "$Foo", "Данные"). Results that would
+ * start with a digit ("2FA") get an "_" prefix, as do exact reserved words
+ * ("class" → "_class"). Names with no usable characters collapse to "_".
  */
 export declare function sanitizeTypeName(name: string): string;
 /**
- * Build a mapping of sanitized schema names → renamed names for any that
- * collide with reserved type names.
+ * Build a mapping of raw schema names → renamed names for any whose
+ * sanitized name collides with a reserved type name or with another
+ * schema's sanitized name (e.g. "User-Dto" and "User[Dto]" both → "UserDto").
+ *
+ * The map is keyed by the raw schema name (component keys are unique by
+ * construction), so callers resolve raw $ref segments / schema keys first
+ * and fall back to sanitizeTypeName for the common no-collision case.
+ * Numbered suffixes are used when the first renamed candidate also collides.
  */
 export declare function buildSchemaRenameMap(schemaNames: Iterable<string>, reserved: ReadonlySet<string>, suffix?: string): Map<string, string>;
 /**
@@ -28,6 +45,10 @@ export declare function toPascalCase(str: string): string;
 /**
  * Build a PascalCase type-name prefix from an operation's method + path.
  * get + /api/v1/products → "GetApiV1Products"
+ *
+ * Returns the deduped prefix assigned by analyzePaths when available
+ * (distinct routes folding to the same identifier get numbered suffixes),
+ * otherwise computes it from the operation directly.
  */
 export declare function getOperationTypePrefix(op: AnalyzedOperation): string;
 /**

package/dist/utils/generator-helpers.js

@@ -1,3 +1,87 @@
+/**
+ * TypeScript/JavaScript reserved words, matched case-sensitively: a type
+ * named "Null" or "Class" is legal, only the exact lowercase keywords are.
+ */
+const RESERVED_WORDS = new Set([
+    'abstract',
+    'any',
+    'as',
+    'asserts',
+    'assert',
+    'async',
+    'await',
+    'boolean',
+    'break',
+    'case',
+    'catch',
+    'class',
+    'continue',
+    'const',
+    'constructor',
+    'debugger',
+    'declare',
+    'default',
+    'delete',
+    'do',
+    'else',
+    'enum',
+    'export',
+    'extends',
+    'false',
+    'finally',
+    'for',
+    'from',
+    'function',
+    'get',
+    'if',
+    'implements',
+    'import',
+    'in',
+    'infer',
+    'instanceof',
+    'interface',
+    'is',
+    'keyof',
+    'let',
+    'module',
+    'namespace',
+    'never',
+    'new',
+    'null',
+    'number',
+    'object',
+    'package',
+    'private',
+    'protected',
+    'public',
+    'readonly',
+    'require',
+    'return',
+    'satisfies',
+    'set',
+    'static',
+    'string',
+    'super',
+    'switch',
+    'symbol',
+    'this',
+    'throw',
+    'true',
+    'try',
+    'type',
+    'typeof',
+    'undefined',
+    'unique',
+    'unknown',
+    'var',
+    'void',
+    'while',
+    'with',
+    'yield',
+]);
+function isReservedTypeName(name) {
+    return RESERVED_WORDS.has(name);
+}
 /**
  * Reserved type names used by the generated output's built-in classes,
  * functions, and types. User-defined schema names that collide with these
@@ -22,30 +106,72 @@ export const RESERVED_TYPE_NAMES = new Set([
 /** Default module specifier generated code imports shared runtime classes from. */
 export const DEFAULT_RUNTIME_IMPORT_PATH = 'genoc/runtime';
 /**
- * Sanitize a schema type name by converting dot-separated segments into
- * PascalCase. Names without dots pass through unchanged.
+ * Sanitize a schema type name into a valid TypeScript identifier.
+ *
+ * Any run of non-identifier characters (dots, brackets, backticks, hyphens,
+ * spaces, slashes, ...) splits the name into segments that are re-joined in
+ * PascalCase:
  *
- * "Api.Error" → "ApiError", "Simple" → "Simple"
+ *   "Api.Error"  → "ApiError"
+ *   "User[Dto]"  → "UserDto"
+ *   "my-schema"  → "MySchema"
+ *   "payment id" → "PaymentId"
+ *
+ * Names that are already valid identifiers pass through unchanged
+ * ("User", "my_schema", "mySchema", "$Foo", "Данные"). Results that would
+ * start with a digit ("2FA") get an "_" prefix, as do exact reserved words
+ * ("class" → "_class"). Names with no usable characters collapse to "_".
  */
 export function sanitizeTypeName(name) {
-    if (!name.includes('.'))
+    if (!name)
+        return '_';
+    // Exact reserved words keep their casing and get an "_" prefix
+    // ("class" → "_class"), while "Null" / "Class" are legal and pass through.
+    if (isReservedTypeName(name))
+        return `_${name}`;
+    const isValidIdentifier = /^[\p{ID_Start}$_][\p{ID_Continue}$]*$/u.test(name);
+    if (isValidIdentifier)
         return name;
-    return name
-        .split('.')
+    const segments = name.match(/[\p{ID_Continue}$]+/gu) ?? [];
+    const result = segments
         .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
         .join('');
+    // Covers empty results, ASCII digits, and non-ASCII digits (Nd but not
+    // ID_Start, e.g. Arabic-Indic) alike: anything not starting with a valid
+    // identifier start character gets the "_" prefix.
+    if (!/^[\p{ID_Start}$_]/u.test(result))
+        return `_${result}`;
+    if (isReservedTypeName(result))
+        return `_${result}`;
+    return result;
 }
 /**
- * Build a mapping of sanitized schema names → renamed names for any that
- * collide with reserved type names.
+ * Build a mapping of raw schema names → renamed names for any whose
+ * sanitized name collides with a reserved type name or with another
+ * schema's sanitized name (e.g. "User-Dto" and "User[Dto]" both → "UserDto").
+ *
+ * The map is keyed by the raw schema name (component keys are unique by
+ * construction), so callers resolve raw $ref segments / schema keys first
+ * and fall back to sanitizeTypeName for the common no-collision case.
+ * Numbered suffixes are used when the first renamed candidate also collides.
  */
 export function buildSchemaRenameMap(schemaNames, reserved, suffix = 'Model') {
     const renameMap = new Map();
+    const used = new Set(reserved);
     for (const name of schemaNames) {
         const sanitized = sanitizeTypeName(name);
-        if (reserved.has(sanitized)) {
-            renameMap.set(sanitized, `${sanitized}${suffix}`);
+        if (!used.has(sanitized)) {
+            used.add(sanitized);
+            continue;
+        }
+        let candidate = `${sanitized}${suffix}`;
+        let counter = 2;
+        while (used.has(candidate)) {
+            candidate = `${sanitized}${suffix}${counter}`;
+            counter += 1;
         }
+        used.add(candidate);
+        renameMap.set(name, candidate);
     }
     return renameMap;
 }
@@ -64,15 +190,24 @@ export function toPascalCase(str) {
 /**
  * Build a PascalCase type-name prefix from an operation's method + path.
  * get + /api/v1/products → "GetApiV1Products"
+ *
+ * Returns the deduped prefix assigned by analyzePaths when available
+ * (distinct routes folding to the same identifier get numbered suffixes),
+ * otherwise computes it from the operation directly.
  */
 export function getOperationTypePrefix(op) {
+    if (op.typePrefix)
+        return op.typePrefix;
+    return computeOperationTypePrefix(op);
+}
+function computeOperationTypePrefix(op) {
     const methodPascal = op.method.charAt(0).toUpperCase() + op.method.slice(1).toLowerCase();
     const segments = op.path
         .split('/')
         .filter((s) => s.length > 0)
         .map((s) => {
         const cleaned = s.replace(/[{}]/g, '');
-        return toPascalCase(cleaned);
+        return sanitizeTypeName(toPascalCase(cleaned));
     });
     return methodPascal + segments.join('');
 }

package/dist/utils/proxy.d.ts

@@ -0,0 +1,6 @@
+export type LoadOptions = {
+    proxy?: string;
+};
+export declare function assertValidProxyUrl(url: string): void;
+export declare function hasProxyEnv(): boolean;
+export declare function fetchSpec(url: string, opts?: LoadOptions): Promise<Response>;

package/dist/utils/proxy.js

@@ -0,0 +1,81 @@
+const SUPPORTED_PROXY_PROTOCOLS = new Set(['http:', 'https:']);
+/** Security: never echo credentials — user:pass@ becomes ***@ in any echoed value. */
+function redactCredentials(proxyUrl) {
+    try {
+        const url = new URL(proxyUrl);
+        if (url.username || url.password) {
+            url.username = '***';
+            url.password = '';
+        }
+        return url.toString();
+    }
+    catch {
+        return proxyUrl;
+    }
+}
+const MAX_CAUSE_DEPTH = 5;
+/**
+ * undici's fetch() nests the meaningful error up to 3 levels deep via `cause`
+ * (e.g. "fetch failed" → "Request was cancelled." → "Proxy response (502) !== 200...").
+ * Flatten the chain so the deepest message (proxy status, ECONNREFUSED, ...) is user-visible.
+ */
+function describeFetchError(err) {
+    const messages = [];
+    let current = err;
+    for (let depth = 0; depth <= MAX_CAUSE_DEPTH && current instanceof Error; depth++) {
+        if (!messages.includes(current.message)) {
+            messages.push(current.message);
+        }
+        current = current.cause;
+    }
+    return messages.join(': ');
+}
+export function assertValidProxyUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid proxy URL "${redactCredentials(url)}": only http:// and https:// proxies are supported`);
+    }
+    if (!SUPPORTED_PROXY_PROTOCOLS.has(parsed.protocol)) {
+        throw new Error(`Invalid proxy URL "${redactCredentials(url)}": only http:// and https:// proxies are supported (got scheme "${parsed.protocol.replace(/:$/, '')}:")`);
+    }
+}
+export function hasProxyEnv() {
+    return Boolean(process.env.HTTP_PROXY ||
+        process.env.http_proxy ||
+        process.env.HTTPS_PROXY ||
+        process.env.https_proxy);
+}
+export async function fetchSpec(url, opts) {
+    if (opts?.proxy) {
+        assertValidProxyUrl(opts.proxy);
+        const redacted = redactCredentials(opts.proxy);
+        try {
+            const { fetch: undiciFetch, ProxyAgent } = await import('undici');
+            return (await undiciFetch(url, {
+                dispatcher: new ProxyAgent(opts.proxy),
+            }));
+        }
+        catch (err) {
+            throw new Error(`Failed to fetch spec from URL via proxy ${redacted}: ${describeFetchError(err)}`, {
+                cause: err,
+            });
+        }
+    }
+    if (hasProxyEnv()) {
+        try {
+            const { fetch: undiciFetch, EnvHttpProxyAgent } = await import('undici');
+            return (await undiciFetch(url, {
+                dispatcher: new EnvHttpProxyAgent(),
+            }));
+        }
+        catch (err) {
+            throw new Error(`Failed to fetch spec from URL via proxy env: ${describeFetchError(err)}`, {
+                cause: err,
+            });
+        }
+    }
+    return fetch(url);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genoc",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Generate typed HTTP clients from OpenAPI 3.0 / 3.1 specifications",
   "keywords": [
     "client",
@@ -48,6 +48,7 @@
   },
   "dependencies": {
     "@stricli/core": "^1.2.6",
+    "undici": "^6.13.0",
     "yaml": "^2.8.4"
   },
   "devDependencies": {

package/dist/generator/error-types.d.ts

@@ -1,13 +0,0 @@
-import type { AnalyzedOperation } from '../analyzer/path-analyzer.js';
-/**
- * Generate error types for a set of analyzed operations.
- *
- * Produces:
- * 1. `ApiError<TStatus, TData>` class
- * 2. `UnspecifiedApiError` class (extends ApiError, for status codes not in spec)
- * 3. Per-operation error union types (e.g. `GetApiV1ProductsErrors`)
- * 4. Per-operation per-status error type aliases (e.g. `GetApiV1ProductsError400`)
- * 5. `DefaultErrorBody` type for `default` responses
- * 6. Catch-all `UnspecifiedApiError` in error unions for unexpected status codes
- */
-export declare function generateErrorTypes(operations: AnalyzedOperation[]): string;

package/dist/generator/error-types.js

@@ -1,67 +0,0 @@
-/**
- * Generate error types for a set of analyzed operations.
- *
- * Produces:
- * 1. `ApiError<TStatus, TData>` class
- * 2. `UnspecifiedApiError` class (extends ApiError, for status codes not in spec)
- * 3. Per-operation error union types (e.g. `GetApiV1ProductsErrors`)
- * 4. Per-operation per-status error type aliases (e.g. `GetApiV1ProductsError400`)
- * 5. `DefaultErrorBody` type for `default` responses
- * 6. Catch-all `UnspecifiedApiError` in error unions for unexpected status codes
- */
-export function generateErrorTypes(operations) {
-    const lines = [];
-    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";
-  }
-}`);
-    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";
-  }
-}`);
-    lines.push('');
-    let needsDefaultErrorBody = false;
-    for (const op of operations) {
-        const errorResponses = op.responses.filter((r) => !r.isSuccess && r.statusCode !== 'default');
-        const defaultResponse = op.responses.find((r) => !r.isSuccess && r.statusCode === 'default');
-        if (errorResponses.length === 0 && !defaultResponse) {
-            continue;
-        }
-        const methodName = op.methodName;
-        const errorTypeName = (status) => `${methodName}Error${status}`;
-        lines.push('');
-        for (const err of errorResponses) {
-            const tsType = err.tsType || 'unknown';
-            lines.push(`export type ${errorTypeName(err.statusCode)} = ${tsType};`);
-        }
-        const unionParts = [];
-        for (const err of errorResponses) {
-            const status = Number(err.statusCode);
-            unionParts.push(`ApiError<${status}, ${errorTypeName(err.statusCode)}>`);
-        }
-        if (defaultResponse) {
-            needsDefaultErrorBody = true;
-            unionParts.push(`ApiError<number, DefaultErrorBody>`);
-        }
-        unionParts.push(`UnspecifiedApiError`);
-        lines.push(`export type ${methodName}Errors = ${unionParts.join('\n  | ')};`);
-    }
-    if (needsDefaultErrorBody) {
-        lines.push('');
-        lines.push('export type DefaultErrorBody = unknown;');
-    }
-    return lines.join('\n');
-}