genoc 0.4.2 → 0.5.0

package/README.md

@@ -12,6 +12,7 @@ Generated code depends only on the tiny `genoc/runtime` module. Full type safety
 
 - 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
+- Typed path parameters: values are typed from their schema and accept `T | string` — pass a pre-formatted string for custom wire formatting; serialization is inline `String()`
 - Works with any HTTP client: plug in fetch, axios, or anything else
 - Shared runtime contract: `genoc/runtime` exports the `Requester` type and response and error classes, so one requester implementation works with every generated client
 - Error types with per-status-code narrowing and type guards
@@ -115,7 +116,7 @@ For the full example of catching and narrowing errors, see [Error handling](./do
 ## Documentation
 
 - [Configuration](./docs/configuration.md): CLI flags, `.genocrc` config files, method naming strategies, and proxy support
-- [Usage](./docs/usage.md): the `Requester` contract, shared runtime, binary and file responses, and JSDoc output
+- [Usage](./docs/usage.md): the `Requester` contract, `createClient` options, shared runtime, binary and file responses, and JSDoc output
 - [Error handling](./docs/error-handling.md): typed errors, `isDefinedError`, and the catching example
 - [OpenAPI 3.0 support](./docs/openapi-3.0-support.md): data types, schema keywords, parameters, bodies, uploads, responses, errors, `$ref`, components, security, servers, and operations
 - [OpenAPI 3.1 support](./docs/openapi-3.1-support.md): all 3.0 features plus webhooks and JSON Schema 2020-12 alignment, with a diff against 3.0

package/dist/analyzer/analyze.js

@@ -1,6 +1,7 @@
 import { RefResolver } from '../parser/ref-resolver.js';
 import { buildSchemaRenameMap, buildTypeJsDoc, sanitizeJsDocText, sanitizeTypeName, toPascalCase, } from '../utils/generator-helpers.js';
 import { operationEmissions, RESERVED_TYPE_NAMES } from '../utils/operation-naming.js';
+import { escapeStringLiteral } from '../utils/string.js';
 import { buildDiscriminatorRegistry, renameAwareTypeName } from './discriminator-registry.js';
 import { analyzePathsDetailed } from './path-analyzer.js';
 import { SchemaMapper } from './schema-mapper.js';
@@ -41,6 +42,34 @@ function attachTypeJsDoc(jsDoc, definition) {
 function indentJsDocBlock(jsDoc) {
     return jsDoc.split('\n').map((line) => `${INDENT_UNIT}${line}`);
 }
+/** Schema used for parameters declared without a `schema` (typed as `string`). */
+function defaultedParamSchema(param) {
+    return param.schema ?? { type: 'string' };
+}
+const STRING_SERIALIZABLE_MEMBER = /^(string|number|boolean|null|true|false|'[^']*'|-?\d+(?:\.\d+)?)$/;
+/**
+ * Whether a finished path-param type can be serialized inline with `String()`:
+ * every union member must be a primitive with a defined string form, or a
+ * string/number literal (literal unions like `'fast' | 'slow'` are kept).
+ * Named component types count when their own mapped definition resolves
+ * (transitively, cycle-safe) to such members — so `$ref` path params to
+ * primitive aliases keep their named type. Anything else — objects, arrays,
+ * named non-primitive `$ref` types — falls back to a `string` signature (the
+ * pre-typed-path-params behavior), because there is no defined string
+ * serialization for such values.
+ */
+function isInlineSerializableType(tsType, namedMappedTypes, seen = new Set()) {
+    return tsType.split('|').every((member) => {
+        const token = member.trim();
+        if (STRING_SERIALIZABLE_MEMBER.test(token))
+            return true;
+        const namedDefinition = namedMappedTypes.get(token);
+        if (namedDefinition === undefined || seen.has(token))
+            return false;
+        const nextSeen = new Set(seen).add(token);
+        return isInlineSerializableType(namedDefinition, namedMappedTypes, nextSeen);
+    });
+}
 /**
  * Build the JSDoc block for a query/header parameter property using the
  * pinned parameter merge rule: parameter-level description / deprecated /
@@ -62,7 +91,7 @@ function buildParamPropertyJsDoc(param, schema) {
 function buildParamTypeBody(params, mapper) {
     const lines = [];
     for (const param of params) {
-        const paramSchema = param.schema ?? { type: 'string' };
+        const paramSchema = defaultedParamSchema(param);
         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}"`;
@@ -123,75 +152,92 @@ function topologicalSort(entries, allNames) {
     }
     return sorted;
 }
-function securitySchemeToTsType(scheme) {
-    const parts = [`type: "${scheme.type}"`];
+/**
+ * Build the `key: "value"` fragments of a security scheme object — shared by
+ * the contracts TYPE renderer (`'; '` separator) and the client CONST value
+ * renderer (`', '` separator).
+ */
+function schemeParts(scheme, separator) {
+    const parts = [`type: '${escapeStringLiteral(scheme.type)}'`];
     if (scheme.description) {
-        parts.push(`description: "${scheme.description}"`);
+        parts.push(`description: '${escapeStringLiteral(scheme.description)}'`);
     }
     if (scheme.type === 'apiKey') {
         if (scheme.name)
-            parts.push(`name: "${scheme.name}"`);
+            parts.push(`name: '${escapeStringLiteral(scheme.name)}'`);
         if (scheme.in)
-            parts.push(`in: "${scheme.in}"`);
+            parts.push(`in: '${escapeStringLiteral(scheme.in)}'`);
     }
     if (scheme.type === 'http') {
         if (scheme.scheme)
-            parts.push(`scheme: "${scheme.scheme}"`);
-        if (scheme.bearerFormat)
-            parts.push(`bearerFormat: "${scheme.bearerFormat}"`);
+            parts.push(`scheme: '${escapeStringLiteral(scheme.scheme)}'`);
+        if (scheme.bearerFormat) {
+            parts.push(`bearerFormat: '${escapeStringLiteral(scheme.bearerFormat)}'`);
+        }
     }
     if (scheme.type === 'oauth2' && scheme.flows) {
         const flowParts = [];
         const flows = scheme.flows;
         if (flows.implicit) {
-            flowParts.push(`implicit: ${oAuth2FlowToTs(flows.implicit, true)}`);
+            flowParts.push(`implicit: ${oAuth2FlowToTs(flows.implicit, true, separator)}`);
         }
         if (flows.password) {
-            flowParts.push(`password: ${oAuth2FlowToTs(flows.password, false)}`);
+            flowParts.push(`password: ${oAuth2FlowToTs(flows.password, false, separator)}`);
         }
         if (flows.clientCredentials) {
-            flowParts.push(`clientCredentials: ${oAuth2FlowToTs(flows.clientCredentials, false)}`);
+            flowParts.push(`clientCredentials: ${oAuth2FlowToTs(flows.clientCredentials, false, separator)}`);
         }
         if (flows.authorizationCode) {
-            flowParts.push(`authorizationCode: ${oAuth2FlowToTs(flows.authorizationCode, true)}`);
+            flowParts.push(`authorizationCode: ${oAuth2FlowToTs(flows.authorizationCode, true, separator)}`);
         }
-        parts.push(`flows: { ${flowParts.join('; ')} }`);
+        parts.push(`flows: { ${flowParts.join(separator)} }`);
     }
     if (scheme.type === 'openIdConnect' && scheme.openIdConnectUrl) {
-        parts.push(`openIdConnectUrl: "${scheme.openIdConnectUrl}"`);
+        parts.push(`openIdConnectUrl: '${escapeStringLiteral(scheme.openIdConnectUrl)}'`);
     }
-    return `{ ${parts.join('; ')} }`;
+    return parts;
+}
+function securitySchemeToTsType(scheme) {
+    return `{ ${schemeParts(scheme, '; ').join('; ')} }`;
+}
+/** The scheme object as a value expression — client-file consts (`as const`). */
+function securitySchemeConstExpression(scheme) {
+    return `{ ${schemeParts(scheme, ', ').join(', ')} } as const`;
 }
-function oAuth2FlowToTs(flow, hasAuthUrl) {
+function oAuth2FlowToTs(flow, hasAuthUrl, separator) {
     const entries = [];
     if (hasAuthUrl && flow.authorizationUrl) {
-        entries.push(`authorizationUrl: "${flow.authorizationUrl}"`);
+        entries.push(`authorizationUrl: '${escapeStringLiteral(flow.authorizationUrl)}'`);
     }
     if (flow.tokenUrl) {
-        entries.push(`tokenUrl: "${flow.tokenUrl}"`);
+        entries.push(`tokenUrl: '${escapeStringLiteral(flow.tokenUrl)}'`);
     }
     if (flow.refreshUrl) {
-        entries.push(`refreshUrl: "${flow.refreshUrl}"`);
+        entries.push(`refreshUrl: '${escapeStringLiteral(flow.refreshUrl)}'`);
     }
     const scopeEntries = Object.entries(flow.scopes)
-        .map(([k, v]) => `"${k}": "${v}"`)
-        .join('; ');
+        .map(([k, v]) => `'${escapeStringLiteral(k)}': '${escapeStringLiteral(v)}'`)
+        .join(separator);
     entries.push(`scopes: { ${scopeEntries} }`);
-    return `{ ${entries.join('; ')} }`;
+    return `{ ${entries.join(separator)} }`;
 }
 /**
  * Translate `components.securitySchemes` into finished `{Name}Auth` type
  * declarations: sanitize + PascalCase the key, number collisions, render the
- * object type text and the description JSDoc. Spec key order preserved.
+ * object type text, the client-file const, and the description JSDoc. Spec
+ * key order preserved; `$ref` entries resolved through the resolver.
  */
-function analyzeSecuritySchemes(securitySchemes) {
+function analyzeSecuritySchemes(securitySchemes, resolver) {
     const entries = [];
     if (!securitySchemes || Object.keys(securitySchemes).length === 0) {
         return entries;
     }
     const usedSecurityTypeNames = new Set();
-    for (const [schemeName, scheme] of Object.entries(securitySchemes)) {
-        const baseTypeName = `${sanitizeTypeName(toPascalCase(schemeName))}Auth`;
+    const usedConstNames = new Set();
+    for (const [schemeName, rawScheme] of Object.entries(securitySchemes)) {
+        const scheme = resolver.resolve(rawScheme);
+        const pascal = sanitizeTypeName(toPascalCase(schemeName));
+        const baseTypeName = `${pascal}Auth`;
         let typeName = baseTypeName;
         let n = 2;
         while (usedSecurityTypeNames.has(typeName)) {
@@ -199,14 +245,36 @@ function analyzeSecuritySchemes(securitySchemes) {
             n += 1;
         }
         usedSecurityTypeNames.add(typeName);
+        const baseConstName = `${pascal.charAt(0).toLowerCase()}${pascal.slice(1)}Scheme`;
+        let constName = baseConstName;
+        n = 2;
+        while (usedConstNames.has(constName)) {
+            constName = `${baseConstName}${n}`;
+            n += 1;
+        }
+        usedConstNames.add(constName);
         entries.push({
+            schemeName,
             name: typeName,
             tsType: securitySchemeToTsType(scheme),
             jsDoc: buildDescriptionJsDoc(scheme.description),
+            constName,
+            constExpression: securitySchemeConstExpression(scheme),
         });
     }
     return entries;
 }
+/**
+ * Resolve effective `security` requirements into per-call facts: each spec
+ * requirement object becomes one AND-list of `{ schemeName, scopes }` calls,
+ * `{}` becoming the empty (anonymous-access) alternative. Scheme names are
+ * passed through unfiltered; the client generator degrades gracefully if a
+ * name has no scheme (unreachable in practice — validation rejects unknown
+ * names before analysis runs).
+ */
+function analyzeSecurityRequirements(requirements) {
+    return requirements.map((requirement) => Object.entries(requirement).map(([schemeName, scopes]) => ({ schemeName, scopes })));
+}
 /**
  * Translate `doc.servers` into finished server variable interface
  * declarations, one per server that declares variables. Names are index-aware
@@ -301,10 +369,14 @@ export function analyze(doc, opts = {}) {
     });
     // Section 1: Schema types
     const schemaEntries = [];
+    // Mapped definition text per renamed component name — lets the path-param
+    // inline-serializability check resolve named types to their primitives.
+    const namedMappedTypes = new Map();
     if (doc.components?.schemas) {
         for (const [name, schema] of Object.entries(doc.components.schemas)) {
             const renamedName = renameMap.get(name) ?? sanitizeTypeName(name);
             const result = mapper.mapSchema(schema, renamedName);
+            namedMappedTypes.set(renamedName, result.tsType);
             const resolved = resolver.resolve(schema);
             const definition = `export type ${renamedName} = ${result.tsType};`;
             schemaEntries.push({
@@ -337,9 +409,48 @@ export function analyze(doc, opts = {}) {
     const { operations: analyzedOperations, requestBodySchemas } = analyzePathsDetailed(doc, resolver, strategy);
     const operations = [];
     for (const op of analyzedOperations) {
+        // Path params render as flat method arguments, so each carries its
+        // finished signature type. A raw `$ref` schema maps to the named contract
+        // type (the same raw-schema travel pattern as request bodies and
+        // responses — the contracts renderer emits the named type from the
+        // component table); the mapper's import facts feed the client file's
+        // `import type` list. Inline schemas map the resolved schema with
+        // `format` stripped: path params are typed by their base primitive
+        // (boolean, number, literal unions) and format brands don't flow into
+        // signatures.
+        const pathParamTypeNames = new Set();
+        for (const param of op.pathParams) {
+            const raw = param.rawSchema;
+            if (raw !== undefined && '$ref' in raw) {
+                const result = mapper.mapSchema(raw);
+                if (isInlineSerializableType(result.tsType, namedMappedTypes)) {
+                    param.finishedType = result.tsType;
+                    for (const name of result.imports) {
+                        pathParamTypeNames.add(name);
+                    }
+                }
+                else {
+                    // Inline-serialization constraint: a `$ref` to an object/array
+                    // schema (or any non-primitive named type) has no defined string
+                    // form, so the parameter falls back to `string` and the named
+                    // type is not imported into the client file.
+                    param.finishedType = 'string';
+                }
+                continue;
+            }
+            const schema = defaultedParamSchema(param);
+            const tracerSchema = schema.format === undefined ? schema : { ...schema, format: undefined };
+            const mapped = mapper.mapSchema(tracerSchema).tsType;
+            param.finishedType = isInlineSerializableType(mapped, namedMappedTypes) ? mapped : 'string';
+        }
+        if (pathParamTypeNames.size > 0) {
+            op.pathParamTypeNames = [...pathParamTypeNames];
+        }
+        const effectiveSecurity = op.security ?? doc.security;
         operations.push({
             ...op,
             contractsLines: [],
+            securityRequirements: effectiveSecurity === undefined ? [] : analyzeSecurityRequirements(effectiveSecurity),
         });
     }
     const hasFileUpload = operations.some((op) => op.requestBody?.isMultipart);
@@ -479,7 +590,7 @@ export function analyze(doc, opts = {}) {
     // Branded types snapshot after every mapSchema call has run, mirroring the
     // pre-refactor read position at the end of generateContracts.
     const brandedTypes = Array.from(mapper.getBrandedTypes().values());
-    const securitySchemeTypes = analyzeSecuritySchemes(doc.components?.securitySchemes);
+    const securitySchemeTypes = analyzeSecuritySchemes(doc.components?.securitySchemes, resolver);
     const serverTypes = analyzeServers(doc.servers);
     return {
         specVersion: doc.openapi,

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

@@ -1,15 +1,27 @@
 import { RefResolver } from '../parser/ref-resolver.js';
 import type { MethodNameStrategy } from '../types/client.js';
-import type { OpenAPIDocument, ReferenceObject, SchemaObject } from '../types/openapi.js';
+import type { OpenAPIDocument, ReferenceObject, SchemaObject, SecurityRequirementObject } from '../types/openapi.js';
 export interface AnalyzedParameter {
     name: string;
     in: 'path' | 'query' | 'header' | 'cookie';
     required: boolean;
     /** Resolved param schema — analyzer-internal translation input for `analyze()`; renderers must not read it. */
     schema: SchemaObject | undefined;
+    /**
+     * Raw (possibly `$ref`) param schema — analyzer-internal translation input
+     * for `analyze()`; renderers must not read it. Kept beside the resolved
+     * schema so `$ref` sites translate to the named contract type (the same
+     * raw-schema travel pattern as request bodies and responses).
+     */
+    rawSchema: SchemaObject | ReferenceObject | undefined;
     description?: string;
     deprecated?: boolean;
     example?: unknown;
+    /**
+     * Finished (real-mapper) TS type text for the method signature — set by
+     * `analyze()` for path params, the only params rendered as flat args.
+     */
+    finishedType?: string;
 }
 export interface AnalyzedRequestBody {
     required: boolean;
@@ -59,8 +71,16 @@ export interface AnalyzedOperation {
     queryParams: AnalyzedParameter[];
     headerParams: AnalyzedParameter[];
     cookieParams: AnalyzedParameter[];
+    /**
+     * Named contract types referenced by path-param finished types (`$ref`
+     * path params). Set by `analyze()` from the mapper's import facts; drives
+     * the client file's `import type` list for method signatures.
+     */
+    pathParamTypeNames?: string[];
     requestBody: AnalyzedRequestBody | undefined;
     responses: AnalyzedResponse[];
+    /** Raw operation-level `security`; `undefined` = inherit the document default. */
+    security?: SecurityRequirementObject[];
 }
 /**
  * Analyzer-internal analysis result: the analyzed operations plus the raw

package/dist/analyzer/path-analyzer.js

@@ -1,8 +1,8 @@
 import { RefResolver } from '../parser/ref-resolver.js';
 import { isBinaryContentType } from '../utils/generator-helpers.js';
+import { HTTP_METHODS } from '../utils/http-methods.js';
 import { getOperationTypePrefix } from '../utils/operation-naming.js';
 import { getMethodName } from './naming.js';
-const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace'];
 /**
  * Resolve a possibly-$ref-ed schema and check for an exact top-level `format: binary`
  * match. Top-level only — intentionally no deep-walk into items/allOf/oneOf/anyOf.
@@ -28,6 +28,7 @@ function analyzeParameter(param, resolver) {
         in: param.in,
         required: param.required ?? param.in === 'path',
         schema,
+        rawSchema: param.schema,
         description: param.description,
         deprecated: param.deprecated,
         example: param.example,
@@ -182,6 +183,7 @@ export function analyzePathsDetailed(doc, resolver, strategy = 'path-based') {
                 ...categorized,
                 requestBody: requestBodyResult?.requestBody,
                 responses,
+                security: operation.security,
             });
             requestBodySchemas.push(requestBodyResult?.rawSchema);
         }

package/dist/analyzer/types.d.ts

@@ -20,12 +20,29 @@ export interface TypeDeclaration {
  * and the description-only JSDoc block ('' when absent).
  */
 export interface SecuritySchemeTypeDeclaration {
+    /** Spec key under `components.securitySchemes` — the requirement lookup name. */
+    schemeName: string;
     /** Emitted `{Name}Auth` type name (sanitized, numbered on collision). */
     name: string;
     /** Rendered object type text — the `securitySchemeToTsType` output. */
     tsType: string;
     /** Description JSDoc block; '' when the scheme carries no description. */
     jsDoc: string;
+    /**
+     * Client-file const identifier holding the full scheme literal. Inline
+     * `scheme:` values in method bodies reference it — one const per scheme
+     * caps oauth2-flows bloat at a single site.
+     */
+    constName: string;
+    /** `{ … } as const` — the scheme object as a value expression. */
+    constExpression: string;
+}
+/** One scheme invocation inside an effective security requirement. */
+export interface AnalyzedSecurityCall {
+    /** Scheme name as declared in `components.securitySchemes` (spec key). */
+    schemeName: string;
+    /** Requested scopes/roles; empty for non-oauth2/openIdConnect schemes. */
+    scopes: string[];
 }
 /**
  * Finished server variable type declaration (contracts Section 1c). Names
@@ -81,6 +98,14 @@ export interface FinishedOperation extends AnalyzedOperation {
      * emission). Sole fact source for the client generator's FormData appends.
      */
     fileUploadProperties?: FileUploadPropertyFact[];
+    /**
+     * Effective security requirements (operation override ?? document default
+     * ?? none): an OR-list of AND-lists. Each call names its scheme by spec
+     * key; the client generator resolves it to a `securitySchemeTypes` const.
+     * `[]` = public operation (explicitly or by absence). An empty AND-list is
+     * the spec's `{}` — "anonymous access acceptable" alternative.
+     */
+    securityRequirements: AnalyzedSecurityCall[][];
 }
 /**
  * Single-pass analysis model of an OpenAPI document — the ONLY input every

package/dist/cli/impl.js

@@ -138,12 +138,14 @@ async function runOneTarget(target, context) {
     }
     context.process.stdout.write(`Loading spec from ${target.input}...\n`);
     const doc = await load(target.input, { proxy: target.proxy });
-    context.process.stdout.write(`Loaded OpenAPI ${doc.openapi} spec\n`);
     const override = target.specVersion;
     if (override !== undefined && override !== '3.0' && override !== '3.1') {
         throw new Error(`No strategy registered for version: ${override}`);
     }
+    // Resolve the dialect before logging so a missing/malformed `openapi`
+    // field is reported (with its spec link) instead of logging "undefined".
     const profile = resolveVersion(doc, override);
+    context.process.stdout.write(`Loaded OpenAPI ${doc.openapi} spec\n`);
     if (override !== undefined &&
         target.strictVersion !== false &&
         profile.detected !== profile.effective) {

package/dist/generator/client-generator.js

@@ -1,5 +1,6 @@
 import { DEFAULT_RUNTIME_IMPORT_PATH, makeHeader } from '../utils/generator-helpers.js';
 import { clientImportedNames, clientValueImports, getErrorType, getSuccessType, operationEmissions, } from '../utils/operation-naming.js';
+import { escapeStringLiteral } from '../utils/string.js';
 import { renderContracts } from './contracts-generator.js';
 import { generateMethod } from './method-generator.js';
 function collectImportTypes(operations) {
@@ -12,12 +13,39 @@ function collectImportTypes(operations) {
     // oxlint-disable-next-line unicorn/no-array-sort
     return [...types].sort();
 }
-function buildClientMethodBody(op) {
+/**
+ * Render the `security` option value for a call: `[[call, …], …]` — an
+ * OR-list of AND-lists, each call naming its scheme and pointing at the
+ * file-level scheme const. Returns `undefined` for public operations (option
+ * omitted) and when any scheme name is missing from the declared schemes
+ * (unreachable post-validation; degrades to omission rather than emitting a
+ * dangling reference).
+ */
+function buildSecurityExpression(requirements, schemeConsts) {
+    if (requirements.length === 0) {
+        return undefined;
+    }
+    const alternatives = [];
+    for (const requirement of requirements) {
+        const calls = [];
+        for (const call of requirement) {
+            const scheme = schemeConsts.get(call.schemeName);
+            if (scheme === undefined) {
+                return undefined;
+            }
+            const scopes = call.scopes.map((scope) => `'${escapeStringLiteral(scope)}'`).join(', ');
+            calls.push(`{ schemeName: '${escapeStringLiteral(call.schemeName)}', scopes: [${scopes}], scheme: ${scheme.constName} }`);
+        }
+        alternatives.push(`[${calls.join(', ')}]`);
+    }
+    return `[${alternatives.join(', ')}]`;
+}
+function buildClientMethodBody(op, schemeConsts) {
     const successType = getSuccessType(op);
     const emissions = operationEmissions(op);
     let urlTemplate = op.path;
     for (const param of op.pathParams) {
-        urlTemplate = urlTemplate.replace(`{${param.name}}`, `\${encodeURIComponent(${param.name})}`);
+        urlTemplate = urlTemplate.replace(`{${param.name}}`, `\${encodeURIComponent(String(${param.name}))}`);
     }
     const urlExpr = `\`${urlTemplate}\``;
     const errorCheckLines = [];
@@ -67,6 +95,10 @@ function buildClientMethodBody(op) {
     if (op.headerParams.length > 0) {
         opts.push('headers');
     }
+    const securityExpression = buildSecurityExpression(op.securityRequirements, schemeConsts);
+    if (securityExpression !== undefined) {
+        opts.push(`security: ${securityExpression}`);
+    }
     const lines = [];
     if (op.requestBody?.isMultipart && op.fileUploadProperties !== undefined) {
         const bodyRequired = op.requestBody.required;
@@ -123,7 +155,23 @@ function buildClientMethodBody(op) {
     }
     return tryCatchLines.join('\n');
 }
-function buildClientFile(operations, version, runtimeImportPath = DEFAULT_RUNTIME_IMPORT_PATH) {
+/**
+ * Collect the scheme consts actually referenced by some operation's effective
+ * security — spec declaration order preserved. Schemes no operation uses are
+ * not emitted (dead weight in the client file).
+ */
+function collectUsedSchemeConsts(operations, securitySchemeTypes) {
+    const used = new Set();
+    for (const op of operations) {
+        for (const requirement of op.securityRequirements) {
+            for (const call of requirement) {
+                used.add(call.schemeName);
+            }
+        }
+    }
+    return securitySchemeTypes.filter((scheme) => used.has(scheme.schemeName));
+}
+function buildClientFile(operations, securitySchemeTypes, version, runtimeImportPath = DEFAULT_RUNTIME_IMPORT_PATH) {
     const lines = [];
     lines.push(makeHeader(version));
     const importTypes = collectImportTypes(operations);
@@ -142,6 +190,18 @@ function buildClientFile(operations, version, runtimeImportPath = DEFAULT_RUNTIM
     lines.push('');
     lines.push(`export { isDefinedError } from '${runtimeImportPath}';`);
     lines.push(`export type { Requester } from '${runtimeImportPath}';`);
+    const schemeConsts = new Map(securitySchemeTypes.map((scheme) => [scheme.schemeName, scheme]));
+    const usedSchemes = collectUsedSchemeConsts(operations, securitySchemeTypes);
+    if (usedSchemes.length > 0) {
+        lines.push('');
+        lines.push('/**');
+        lines.push(' * Security schemes (from `components.securitySchemes`) referenced by operations below.');
+        lines.push(' * Passed to the requester via the `security` option — auth decisions stay in user land.');
+        lines.push(' */');
+        for (const scheme of usedSchemes) {
+            lines.push(`const ${scheme.constName} = ${scheme.constExpression};`);
+        }
+    }
     lines.push('');
     lines.push('export function createClient(requester: Requester) {');
     lines.push('  return {');
@@ -155,7 +215,7 @@ function buildClientFile(operations, version, runtimeImportPath = DEFAULT_RUNTIM
                 .join('\n');
             lines.push(indentedJsDoc);
         }
-        const body = buildClientMethodBody(op);
+        const body = buildClientMethodBody(op, schemeConsts);
         const sig = method.signature;
         const firstParen = sig.indexOf('(');
         const closeParenColon = sig.indexOf('): ');
@@ -202,7 +262,7 @@ function buildIndexFile(version) {
  */
 export function renderClient(analyzed, config) {
     const runtimeImportPath = config.runtimeImportPath ?? DEFAULT_RUNTIME_IMPORT_PATH;
-    const client = buildClientFile(analyzed.operations, analyzed.specVersion, runtimeImportPath);
+    const client = buildClientFile(analyzed.operations, analyzed.securitySchemeTypes, analyzed.specVersion, runtimeImportPath);
     const index = buildIndexFile(analyzed.specVersion);
     return { client, index };
 }

package/dist/generator/contracts-generator.js

@@ -1,5 +1,6 @@
 import { DEFAULT_RUNTIME_IMPORT_PATH, makeHeader } from '../utils/generator-helpers.js';
 import { RUNTIME_CLASS_NAMES } from '../utils/operation-naming.js';
+import { escapeStringLiteral } from '../utils/string.js';
 /**
  * Build the import + re-export block for the shared runtime classes.
  * Generated code re-uses the genoc runtime as the single source of truth
@@ -53,6 +54,12 @@ export function renderContracts(analyzed, runtimeImportPath = DEFAULT_RUNTIME_IM
             lines.push('');
             lines.push(`export type ${entry.name} = ${entry.tsType};`);
         }
+        const nameMembers = analyzed.securitySchemeTypes
+            .map((entry) => `'${escapeStringLiteral(entry.schemeName)}'`)
+            .join(' | ');
+        lines.push('');
+        lines.push('/** Names of the security schemes declared in `components.securitySchemes` (spec keys). */');
+        lines.push(`export type SecuritySchemeName = ${nameMembers};`);
         if (analyzed.securitySchemeTypes.length > 1) {
             const unionMembers = analyzed.securitySchemeTypes.map((entry) => entry.name).join(' | ');
             lines.push('');

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

@@ -1,9 +1,17 @@
 import type { AnalyzedOperation } from '../analyzer/path-analyzer.js';
+import type { FinishedOperation } from '../analyzer/types.js';
 import type { GeneratedMethod } from '../types/client.js';
+/**
+ * Method rendering input: an analyzed operation plus the finished security
+ * facts when available (`analyze()` output; bare `AnalyzedOperation`s from
+ * path analysis render without the `@security` tag).
+ */
+type MethodOperation = AnalyzedOperation & Partial<Pick<FinishedOperation, 'securityRequirements'>>;
 /**
  * Generate a client method from an analyzed OpenAPI operation.
  *
  * @param op - The analyzed operation
  * @returns Generated method with name, JSDoc, and signature
  */
-export declare function generateMethod(op: AnalyzedOperation): GeneratedMethod;
+export declare function generateMethod(op: MethodOperation): GeneratedMethod;
+export {};

package/dist/generator/method-generator.js

@@ -25,7 +25,18 @@ function buildParameters(op) {
     const emissions = operationEmissions(op);
     const specs = [];
     for (const param of op.pathParams) {
-        specs.push({ name: param.name, type: 'string', isOptional: false });
+        // Finished signature type text arrives from the analyzer's translation
+        // layer; `?? 'string'` only guards hand-built `AnalyzedOperation` inputs.
+        const finished = param.finishedType ?? 'string';
+        // `T | string` is the caller escape hatch for custom wire formatting:
+        // pass a pre-formatted string instead of the schema type. When T is
+        // already `string` the union is skipped, and string-literal unions
+        // deliberately widen to `string` (flexibility over strictness here).
+        specs.push({
+            name: param.name,
+            type: finished === 'string' ? 'string' : `${finished} | string`,
+            isOptional: false,
+        });
     }
     if (emissions.query !== undefined) {
         const allOptional = op.queryParams.every((p) => !p.required);
@@ -83,6 +94,13 @@ function buildJsDoc(op) {
         }
         lines.push(` * @param body — request body`);
     }
+    const securitySummary = renderSecuritySummary(op.securityRequirements);
+    if (securitySummary !== undefined) {
+        if (lines.length > 0) {
+            lines.push(' *');
+        }
+        lines.push(` * @security ${sanitizeJsDocText(securitySummary)}`);
+    }
     if (op.tags && op.tags.length > 0) {
         if (lines.length > 0) {
             lines.push(' *');
@@ -111,6 +129,25 @@ function buildJsDoc(op) {
     }
     return `/**\n${lines.join('\n')}\n */`;
 }
+/**
+ * Render the `@security` tag text: OR-joined alternatives, AND-joined schemes
+ * within one alternative (parenthesized), scopes as `name[scope, …]`. An
+ * empty alternative is the spec's `{}` — rendered as `anonymous`. Returns
+ * `undefined` for public operations (no tag emitted).
+ */
+function renderSecuritySummary(requirements) {
+    if (requirements === undefined || requirements.length === 0) {
+        return undefined;
+    }
+    const alternatives = requirements.map((requirement) => {
+        const calls = requirement.map((call) => call.scopes.length > 0 ? `${call.schemeName}[${call.scopes.join(', ')}]` : call.schemeName);
+        if (calls.length === 0) {
+            return 'anonymous';
+        }
+        return calls.length > 1 ? `(${calls.join(' AND ')})` : (calls[0] ?? '');
+    });
+    return alternatives.join(' OR ');
+}
 /**
  * Generate a client method from an analyzed OpenAPI operation.
  *