@workos/oagen-emitters 0.2.1 → 0.3.0

package/src/node/resources.ts

@@ -1,6 +1,14 @@
 // @oagen-ignore: Operation.async — all TypeScript SDK methods are async by nature
 
-import type { Service, Operation, EmitterContext, GeneratedFile, TypeRef, Model } from '@workos/oagen';
+import type {
+  Service,
+  Operation,
+  EmitterContext,
+  GeneratedFile,
+  TypeRef,
+  Model,
+  ResolvedOperation,
+} from '@workos/oagen';
 import { planOperation, toPascalCase, toCamelCase } from '@workos/oagen';
 import type { OperationPlan } from '@workos/oagen';
 import { mapTypeRef } from './type-map.js';
@@ -23,6 +31,15 @@ import {
 } from './utils.js';
 import { assignEnumsToServices } from './enums.js';
 import { unwrapListModel } from './fixtures.js';
+import { buildNodeStatusExceptions } from './sdk-errors.js';
+import {
+  buildResolvedLookup,
+  lookupResolved,
+  groupByMount,
+  getOpDefaults,
+  getOpInferFromClient,
+} from '../shared/resolved-ops.js';
+import { generateWrapperMethods, collectWrapperResponseModels } from './wrappers.js';
 
 /**
  * Check whether the baseline (hand-written) class has a constructor compatible
@@ -63,15 +80,9 @@ export function resolveResourceClassName(service: Service, ctx: EmitterContext):
 /** Standard pagination query params handled by PaginationOptions — not imported individually. */
 const PAGINATION_PARAM_NAMES = new Set(['limit', 'before', 'after', 'order']);
 
-/** Map HTTP status codes to their corresponding exception class names for @throws docs. */
-const STATUS_TO_EXCEPTION_NAME: Record<number, string> = {
-  400: 'BadRequestException',
-  401: 'UnauthorizedException',
-  404: 'NotFoundException',
-  409: 'ConflictException',
-  422: 'UnprocessableEntityException',
-  429: 'RateLimitExceededException',
-};
+/** Map HTTP status codes to their corresponding exception class names for @throws docs.
+ *  Built from sdk.errors.statusCodeMap with Node-specific naming overrides. */
+const STATUS_TO_EXCEPTION_NAME: Record<number, string> = buildNodeStatusExceptions();
 
 /**
  * Compute the options interface name for a paginated method.
@@ -92,18 +103,9 @@ function httpMethodNeedsBody(method: string): boolean {
 }
 
 // ---------------------------------------------------------------------------
-// Method-name reconciliation helpers
+// Method-name deduplication helpers
 // ---------------------------------------------------------------------------
 
-/** Map HTTP methods to expected CRUD verb prefixes for method name matching. */
-const HTTP_VERB_PREFIXES: Record<string, string[]> = {
-  get: ['list', 'get', 'fetch', 'retrieve', 'find'],
-  post: ['create', 'add', 'insert', 'send'],
-  put: ['set', 'update', 'replace', 'put'],
-  patch: ['update', 'patch', 'modify'],
-  delete: ['delete', 'remove', 'revoke'],
-};
-
 /** Split a camelCase/PascalCase name into lowercase word parts. */
 function splitCamelWords(name: string): string[] {
   const parts: string[] = [];
@@ -123,209 +125,6 @@ function singularize(word: string): string {
   return word.endsWith('s') && !word.endsWith('ss') ? word.slice(0, -1) : word;
 }
 
-/**
- * Batch-reconcile generated method names against the api-surface class methods.
- *
- * When the overlay doesn't map an operation (missing from previous manifest or
- * fuzzy-matching failed), the emitter falls back to the spec-derived name which
- * often doesn't match the hand-written SDK. This function uses three passes
- * with progressive exclusion to find the best surface match:
- *
- * 1. **Overlay-resolved** — already correct, mark as taken.
- * 2. **Word-set match** — same content words regardless of order (handles
- *    `listRolesOrganizations` ↔ `listOrganizationRoles`).
- * 3. **Path-context match** — all surface-method content words appear in the
- *    operation's URL path segments (handles `findById` ↔ `getResource`).
- *
- * After each pass, matched surface methods are removed from the pool so that
- * ambiguous cases (e.g., `listEnvironmentRoles` vs `listOrganizationRoles`)
- * resolve by elimination.
- */
-function reconcileMethodNames(
-  plans: Array<{ op: Operation; plan: OperationPlan; method: string }>,
-  service: Service,
-  ctx: EmitterContext,
-): void {
-  const className = resolveResourceClassName(service, ctx);
-  const classMethods = ctx.apiSurface?.classes?.[className]?.methods;
-  if (!classMethods) return;
-
-  const available = new Set(Object.keys(classMethods));
-  const resolved = new Map<(typeof plans)[number], string>();
-
-  // Exclude surface methods that are overlay-mapped by OTHER services'
-  // operations.  This prevents the reconciliation from stealing methods
-  // that belong to a different service (e.g., `createPermission` belongs
-  // to the Permissions service, not the Authorization service).
-  const thisServicePaths = new Set(service.operations.map((op) => op.path));
-  if (ctx.overlayLookup?.methodByOperation) {
-    for (const [httpKey, info] of ctx.overlayLookup.methodByOperation) {
-      if (info.className !== className) continue; // different class
-      const path = httpKey.split(' ')[1];
-      if (thisServicePaths.has(path)) continue; // same service
-      // This method is mapped to an operation in a different service
-      available.delete(info.methodName);
-    }
-  }
-
-  // Determine which plans are already overlay-resolved
-  const overlayResolved = new Set<(typeof plans)[number]>();
-  for (const plan of plans) {
-    const httpKey = `${plan.op.httpMethod.toUpperCase()} ${plan.op.path}`;
-    if (ctx.overlayLookup?.methodByOperation?.get(httpKey)) {
-      overlayResolved.add(plan);
-      if (available.has(plan.method)) {
-        resolved.set(plan, plan.method);
-        available.delete(plan.method);
-      }
-    }
-  }
-
-  // Helper: check verb compatibility.
-  // When specVerb is provided, require the surface method to use the same verb
-  // subgroup (e.g., "list" operations only match "list" methods, not "get").
-  const verbMatches = (methodName: string, httpMethod: string, specVerb?: string): boolean => {
-    const prefixes = HTTP_VERB_PREFIXES[httpMethod] ?? [];
-    const lower = methodName.toLowerCase();
-    if (!prefixes.some((p) => lower.startsWith(p))) return false;
-    if (specVerb) {
-      const surfaceVerb = splitCamelWords(methodName)[0];
-      // "list" is a distinct verb subgroup from "get/find/fetch/retrieve"
-      if (specVerb === 'list' && surfaceVerb !== 'list') return false;
-      if (specVerb !== 'list' && surfaceVerb === 'list') return false;
-    }
-    return true;
-  };
-
-  // Pass 1: Word-set matching (handles word-order differences)
-  for (const plan of plans) {
-    if (resolved.has(plan)) continue;
-    const specVerb = splitCamelWords(plan.method)[0];
-    const specWords = splitCamelWords(plan.method).slice(1).map(singularize); // skip verb
-    const specSet = new Set(specWords);
-    if (specSet.size === 0) continue;
-
-    let match: string | null = null;
-    for (const name of available) {
-      if (!verbMatches(name, plan.op.httpMethod, specVerb)) continue;
-      const methodWords = splitCamelWords(name).slice(1).map(singularize);
-      if (methodWords.length !== specWords.length) continue;
-      const methodSet = new Set(methodWords);
-      if (specSet.size === methodSet.size && [...specSet].every((w) => methodSet.has(w))) {
-        if (match !== null) {
-          match = null; // ambiguous — more than one match
-          break;
-        }
-        match = name;
-      }
-    }
-    if (match) {
-      resolved.set(plan, match);
-      available.delete(match);
-    }
-  }
-
-  // Pass 2: Path-context matching (handles different naming e.g., findById → getResource)
-  // To avoid false matches (e.g., `createPermission` matching a role-permission path
-  // just because "permission" appears somewhere in the URL), require that the method's
-  // content words reference the LEAF resource of the path, not just any segment.
-  for (const plan of plans) {
-    if (resolved.has(plan)) continue;
-    const specVerb = splitCamelWords(plan.method)[0];
-    const pathSegments = plan.op.path.split('/').filter((s) => s && !s.startsWith('{'));
-    const pathWords = new Set(pathSegments.flatMap((s) => s.split('_')).map(singularize));
-    // The "leaf" words come from the last non-param segment — the most specific resource.
-    let bestMatch: string | null = null;
-    let bestLen = 0;
-    let ambiguous = false;
-    for (const name of available) {
-      if (!verbMatches(name, plan.op.httpMethod, specVerb)) continue;
-      const methodWords = splitCamelWords(name).slice(1).map(singularize);
-      if (methodWords.length === 0) continue;
-      // All method content words must appear in path context
-      if (!methodWords.every((w) => pathWords.has(w))) continue;
-      // For paths with 3+ non-param segments (nested sub-resources like
-      // /authorization/roles/{slug}/permissions), require at least 2 content
-      // words.  A single-word method like `createPermission` should only match
-      // a top-level path like /authorization/permissions, not a nested one.
-      if (methodWords.length < 2 && pathSegments.length > 2) continue;
-      if (methodWords.length > bestLen) {
-        bestMatch = name;
-        bestLen = methodWords.length;
-        ambiguous = false;
-      } else if (methodWords.length === bestLen) {
-        ambiguous = true;
-      }
-    }
-    if (bestMatch && !ambiguous) {
-      resolved.set(plan, bestMatch);
-      available.delete(bestMatch);
-    }
-  }
-
-  // Pass 3: Retry word-set and path-context for still-unresolved plans
-  // (earlier passes may have eliminated ambiguous candidates)
-  for (const plan of plans) {
-    if (resolved.has(plan)) continue;
-    const specVerb = splitCamelWords(plan.method)[0];
-
-    // Retry word-set
-    const specWords = splitCamelWords(plan.method).slice(1).map(singularize);
-    const specSet = new Set(specWords);
-    let match: string | null = null;
-    for (const name of available) {
-      if (!verbMatches(name, plan.op.httpMethod, specVerb)) continue;
-      const methodWords = splitCamelWords(name).slice(1).map(singularize);
-      if (methodWords.length !== specWords.length) continue;
-      const methodSet = new Set(methodWords);
-      if (specSet.size === methodSet.size && [...specSet].every((w) => methodSet.has(w))) {
-        if (match !== null) {
-          match = null;
-          break;
-        }
-        match = name;
-      }
-    }
-    if (match) {
-      resolved.set(plan, match);
-      available.delete(match);
-      continue;
-    }
-
-    // Retry path-context (with leaf-word check)
-    const pathSegments = plan.op.path.split('/').filter((s) => s && !s.startsWith('{'));
-    const pathWords = new Set(pathSegments.flatMap((s) => s.split('_')).map(singularize));
-    let bestMatch: string | null = null;
-    let bestLen = 0;
-    let ambiguous = false;
-    for (const name of available) {
-      if (!verbMatches(name, plan.op.httpMethod, specVerb)) continue;
-      const methodWords = splitCamelWords(name).slice(1).map(singularize);
-      if (methodWords.length === 0) continue;
-      if (!methodWords.every((w) => pathWords.has(w))) continue;
-      if (methodWords.length < 2 && pathSegments.length > 2) continue;
-      if (methodWords.length > bestLen) {
-        bestMatch = name;
-        bestLen = methodWords.length;
-        ambiguous = false;
-      } else if (methodWords.length === bestLen) {
-        ambiguous = true;
-      }
-    }
-    if (bestMatch && !ambiguous) {
-      resolved.set(plan, bestMatch);
-      available.delete(bestMatch);
-    }
-  }
-
-  // Apply resolved names (only for non-overlay plans)
-  for (const plan of plans) {
-    if (overlayResolved.has(plan)) continue;
-    const name = resolved.get(plan);
-    if (name) plan.method = name;
-  }
-}
-
 /**
  * Deduplicate method names within the plans array.
  *
@@ -397,7 +196,13 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
   if (services.length === 0) return [];
   const files: GeneratedFile[] = [];
 
-  for (const service of services) {
+  // Group services by mount target to avoid file path collisions when
+  // multiple IR services mount to the same resource class.
+  const mountGroups = groupByMount(ctx);
+  const mergedServices: Service[] =
+    mountGroups.size > 0 ? [...mountGroups].map(([name, group]) => ({ name, operations: group.operations })) : services;
+
+  for (const service of mergedServices) {
     if (isServiceCoveredByExisting(service, ctx)) {
       // Fully covered: generate with ALL operations so the merger's docstring
       // refresh pass can update JSDoc on existing methods.
@@ -406,6 +211,9 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
       // remove skipIfExists so the merger adds the new methods.
       if (hasMethodsAbsentFromBaseline(service, ctx)) {
         delete file.skipIfExists;
+        // Suppress auto-generated header — the file is a merge target
+        // containing hand-written code, not a fully generated file.
+        file.headerPlacement = 'skip';
       }
       files.push(file);
       continue;
@@ -420,6 +228,9 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
       // merger adds new methods AND refreshes existing JSDoc.
       const file = generateResourceClass(service, ctx);
       delete file.skipIfExists;
+      // Suppress auto-generated header — the file is a merge target
+      // containing hand-written code, not a fully generated file.
+      file.headerPlacement = 'skip';
       files.push(file);
     } else {
       files.push(generateResourceClass(service, ctx));
@@ -441,10 +252,8 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
     method: resolveMethodName(op, service, ctx),
   }));
 
-  // Reconcile method names against the api-surface class methods.
-  // This fixes cases where the overlay is missing mappings and the
-  // spec-derived name doesn't match the hand-written SDK name.
-  reconcileMethodNames(plans, service, ctx);
+  // Resolved operations already produce correct method names via the
+  // centralized hint map — no per-emitter reconciliation needed.
 
   // Deduplicate method names within the class (e.g., two operations both
   // resolving to "create" for different paths).
@@ -458,18 +267,23 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
   // order, JSDoc comments get attached to the wrong methods (list↔create,
   // add↔set swaps).  Sorting by the overlay's method order ensures the
   // generated output matches the existing file's method order.
+  //
+  // We build the order from HTTP operation keys (e.g., "GET /organizations")
+  // rather than method names, because resolveMethodName may return a different
+  // name than the overlay's methodName (e.g., when the hint map overrides it),
+  // causing the lookup to fail and the sort to produce wrong order.
   if (ctx.overlayLookup?.methodByOperation) {
-    const methodOrder = new Map<string, number>();
+    const httpKeyOrder = new Map<string, number>();
     let pos = 0;
-    for (const [, info] of ctx.overlayLookup.methodByOperation) {
-      if (!methodOrder.has(info.methodName)) {
-        methodOrder.set(info.methodName, pos++);
-      }
+    for (const [httpKey] of ctx.overlayLookup.methodByOperation) {
+      httpKeyOrder.set(httpKey, pos++);
     }
-    if (methodOrder.size > 0) {
+    if (httpKeyOrder.size > 0) {
       plans.sort((a, b) => {
-        const aPos = methodOrder.get(a.method) ?? Number.MAX_SAFE_INTEGER;
-        const bPos = methodOrder.get(b.method) ?? Number.MAX_SAFE_INTEGER;
+        const aKey = `${a.op.httpMethod.toUpperCase()} ${a.op.path}`;
+        const bKey = `${b.op.httpMethod.toUpperCase()} ${b.op.path}`;
+        const aPos = httpKeyOrder.get(aKey) ?? Number.MAX_SAFE_INTEGER;
+        const bPos = httpKeyOrder.get(bKey) ?? Number.MAX_SAFE_INTEGER;
         return aPos - bPos;
       });
     }
@@ -478,13 +292,32 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
   const hasPaginated = plans.some((p) => p.plan.isPaginated);
   const modelMap = new Map(ctx.spec.models.map((m) => [m.name, m]));
 
+  // When merging into an existing class, the merger keeps baseline method
+  // bodies but may add imports from the generated code.  To avoid orphaned
+  // imports for types used only by baseline methods (whose bodies are kept
+  // intact), skip model collection for methods that already exist.
+  const baselineMethodSet = new Set<string>();
+  const baselineClass = ctx.apiSurface?.classes?.[serviceClass];
+  if (baselineClass?.methods) {
+    for (const name of Object.keys(baselineClass.methods)) {
+      baselineMethodSet.add(name);
+    }
+  }
+
   // Collect models for imports — only include models that are actually used
   // in method signatures (not all union variants from the spec)
   const responseModels = new Set<string>();
   const requestModels = new Set<string>();
   const paramEnums = new Set<string>();
   const paramModels = new Set<string>();
-  for (const { op, plan } of plans) {
+  for (const { op, plan, method } of plans) {
+    // Skip imports for methods that already exist in the baseline class.
+    // The merger keeps baseline method bodies, so their imports are already
+    // present in the existing file.  Including them here would create
+    // orphaned imports when the generated return type differs from the
+    // baseline's (e.g., generated `List` vs baseline `RoleList`).
+    if (baselineMethodSet.has(method)) continue;
+
     if (plan.isPaginated && op.pagination?.itemType.kind === 'model') {
       // For paginated operations, import the item type (e.g., Connection)
       // rather than the list wrapper type (e.g., ConnectionList).
@@ -531,6 +364,20 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
       collectParamTypeRefs(param.type, paramEnums, paramModels);
     }
   }
+
+  // Collect response models from union split wrappers so their types and
+  // deserializers are imported alongside the primary operation models.
+  const resolvedLookup = buildResolvedLookup(ctx);
+  for (const { op, method } of plans) {
+    if (baselineMethodSet.has(method)) continue;
+    const resolved = lookupResolved(op, resolvedLookup);
+    if (resolved) {
+      for (const name of collectWrapperResponseModels(resolved)) {
+        responseModels.add(name);
+      }
+    }
+  }
+
   const allModels = new Set([...responseModels, ...requestModels, ...paramModels]);
 
   const lines: string[] = [];
@@ -676,20 +523,29 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
     } else if (!plan.isPaginated && !plan.hasBody && !plan.isDelete && op.queryParams.length > 0) {
       // Non-paginated GET or void methods with query params get a typed options interface
       // instead of falling back to Record<string, unknown>.
-      const optionsName = toPascalCase(method) + 'Options';
-      lines.push(`export interface ${optionsName} {`);
-      for (const param of op.queryParams) {
-        const opt = !param.required ? '?' : '';
-        if (param.description || param.deprecated) {
-          const parts: string[] = [];
-          if (param.description) parts.push(param.description);
-          if (param.deprecated) parts.push('@deprecated');
-          lines.push(...docComment(parts.join('\n'), 2));
+      // Filter out hidden params (defaults and inferFromClient fields)
+      const resolved = lookupResolved(op, resolvedLookup);
+      const opHiddenParams = new Set<string>([
+        ...Object.keys(getOpDefaults(resolved)),
+        ...getOpInferFromClient(resolved),
+      ]);
+      const visibleParams = op.queryParams.filter((p) => !opHiddenParams.has(p.name));
+      if (visibleParams.length > 0) {
+        const optionsName = toPascalCase(method) + 'Options';
+        lines.push(`export interface ${optionsName} {`);
+        for (const param of visibleParams) {
+          const opt = !param.required ? '?' : '';
+          if (param.description || param.deprecated) {
+            const parts: string[] = [];
+            if (param.description) parts.push(param.description);
+            if (param.deprecated) parts.push('@deprecated');
+            lines.push(...docComment(parts.join('\n'), 2));
+          }
+          lines.push(`  ${fieldName(param.name)}${opt}: ${mapParamType(param.type, specEnumNames)};`);
         }
-        lines.push(`  ${fieldName(param.name)}${opt}: ${mapParamType(param.type, specEnumNames)};`);
+        lines.push('}');
+        lines.push('');
       }
-      lines.push('}');
-      lines.push('');
     }
   }
 
@@ -702,7 +558,13 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
 
   for (const { op, plan, method } of plans) {
     lines.push('');
-    lines.push(...renderMethod(op, plan, method, service, ctx, modelMap, specEnumNames));
+    const resolved = lookupResolved(op, resolvedLookup);
+    lines.push(...renderMethod(op, plan, method, service, ctx, modelMap, specEnumNames, resolved));
+
+    // Emit union split wrapper methods (typed convenience methods for each variant)
+    if (resolved?.wrappers && resolved.wrappers.length > 0) {
+      lines.push(...generateWrapperMethods(resolved, ctx));
+    }
   }
 
   lines.push('}');
@@ -718,12 +580,20 @@ function renderMethod(
   ctx: EmitterContext,
   modelMap: Map<string, Model>,
   specEnumNames?: Set<string>,
+  resolvedOp?: ResolvedOperation,
 ): string[] {
   const lines: string[] = [];
   const responseModel = plan.responseModelName ? resolveInterfaceName(plan.responseModelName, ctx) : null;
 
   const pathStr = buildPathStr(op);
 
+  // Build the set of params hidden from the method signature
+  // (injected from client config or as constant defaults)
+  const hiddenParams = new Set<string>([
+    ...Object.keys(getOpDefaults(resolvedOp)),
+    ...getOpInferFromClient(resolvedOp),
+  ]);
+
   // Build set of valid param names to filter @param tags.
   // Prefer the overlay (existing method signature) if available;
   // otherwise compute from what the render path will actually include.
@@ -739,119 +609,135 @@ function renderMethod(
     for (const p of op.pathParams) actualParams.add(fieldName(p.name));
     if (plan.hasBody) actualParams.add('payload');
     if (plan.isPaginated) actualParams.add('options');
-    // renderGetMethod adds options when there are non-paginated query params
-    if (!plan.isPaginated && op.queryParams.length > 0 && !plan.isDelete && responseModel) {
+    // renderGetMethod/renderVoidMethod add options when there are visible non-paginated query params
+    const visibleQueryCount = op.queryParams.filter((q) => !hiddenParams.has(q.name)).length;
+    if (!plan.isPaginated && visibleQueryCount > 0 && !plan.isDelete) {
       actualParams.add('options');
     }
     validParamNames = actualParams;
   }
 
-  const docParts: string[] = [];
-  if (op.description) docParts.push(op.description);
-  for (const param of op.pathParams) {
-    const paramName = fieldName(param.name);
-    if (validParamNames && !validParamNames.has(paramName)) continue;
-    const deprecatedPrefix = param.deprecated ? '(deprecated) ' : '';
-    if (param.description) {
-      docParts.push(`@param ${paramName} - ${deprecatedPrefix}${param.description}`);
-    } else if (param.deprecated) {
-      docParts.push(`@param ${paramName} - (deprecated)`);
+  // Always generate JSDoc for all methods (both existing and new).
+  // The merger matches docstrings by member name — if we skip JSDoc for
+  // existing methods, previously misplaced docstrings can never be corrected.
+  // Hand-written docs (e.g., @deprecated, PKCE flow descriptions) are
+  // preserved by the merger's @deprecated-preservation and @oagen-ignore
+  // mechanisms instead.
+  {
+    const docParts: string[] = [];
+    if (op.description) docParts.push(op.description);
+    for (const param of op.pathParams) {
+      const paramName = fieldName(param.name);
+      if (validParamNames && !validParamNames.has(paramName)) continue;
+      const deprecatedPrefix = param.deprecated ? '(deprecated) ' : '';
+      if (param.description) {
+        docParts.push(`@param ${paramName} - ${deprecatedPrefix}${param.description}`);
+      } else if (param.deprecated) {
+        docParts.push(`@param ${paramName} - (deprecated)`);
+      }
+      if (param.default !== undefined) docParts.push(`@default ${JSON.stringify(param.default)}`);
+      if (param.example !== undefined) docParts.push(`@example ${JSON.stringify(param.example)}`);
     }
-    if (param.default !== undefined) docParts.push(`@default ${JSON.stringify(param.default)}`);
-    if (param.example !== undefined) docParts.push(`@example ${JSON.stringify(param.example)}`);
-  }
-  // Document query params for non-paginated operations
-  if (!plan.isPaginated) {
-    // Only document query params if the method will have an options parameter
-    if (validParamNames && (validParamNames.has('options') || overlayMethod)) {
-      for (const param of op.queryParams) {
-        const paramName = `options.${fieldName(param.name)}`;
-        if (validParamNames && !validParamNames.has('options') && !validParamNames.has(fieldName(param.name))) continue;
-        const deprecatedPrefix = param.deprecated ? '(deprecated) ' : '';
-        if (param.description) {
-          docParts.push(`@param ${paramName} - ${deprecatedPrefix}${param.description}`);
-        } else if (param.deprecated) {
-          docParts.push(`@param ${paramName} - (deprecated)`);
+    // Document query params for non-paginated operations
+    if (!plan.isPaginated) {
+      // Only document query params if the method will have an options parameter
+      if (validParamNames && (validParamNames.has('options') || overlayMethod)) {
+        for (const param of op.queryParams) {
+          if (hiddenParams.has(param.name)) continue;
+          const paramName = `options.${fieldName(param.name)}`;
+          if (validParamNames && !validParamNames.has('options') && !validParamNames.has(fieldName(param.name)))
+            continue;
+          const deprecatedPrefix = param.deprecated ? '(deprecated) ' : '';
+          if (param.description) {
+            docParts.push(`@param ${paramName} - ${deprecatedPrefix}${param.description}`);
+          } else if (param.deprecated) {
+            docParts.push(`@param ${paramName} - (deprecated)`);
+          }
+          if (param.default !== undefined) docParts.push(`@default ${JSON.stringify(param.default)}`);
+          if (param.example !== undefined) docParts.push(`@example ${JSON.stringify(param.example)}`);
         }
-        if (param.default !== undefined) docParts.push(`@default ${JSON.stringify(param.default)}`);
-        if (param.example !== undefined) docParts.push(`@example ${JSON.stringify(param.example)}`);
       }
     }
-  }
-  // Skip header and cookie params in JSDoc — they are not exposed in the method signature.
-  // The SDK handles headers and cookies internally, so documenting them would be misleading.
-  // Document payload parameter when there is a request body
-  if (plan.hasBody) {
-    const bodyInfo = extractRequestBodyType(op, ctx);
-    if (bodyInfo?.kind === 'model') {
-      const bodyModel = ctx.spec.models.find((m) => m.name === bodyInfo.name);
-      let payloadDesc: string;
-      if (bodyModel?.description) {
-        payloadDesc = `@param payload - ${bodyModel.description}`;
-      } else if (bodyModel) {
-        // When the model lacks a description, list its required fields to help
-        // callers understand what must be provided.
-        const requiredFieldNames = bodyModel.fields.filter((f) => f.required).map((f) => fieldName(f.name));
-        payloadDesc =
-          requiredFieldNames.length > 0
-            ? `@param payload - Object containing ${requiredFieldNames.join(', ')}.`
-            : '@param payload - The request body.';
+    // Skip header and cookie params in JSDoc — they are not exposed in the method signature.
+    // The SDK handles headers and cookies internally, so documenting them would be misleading.
+    // Document payload parameter when there is a request body
+    if (plan.hasBody) {
+      const bodyInfo = extractRequestBodyType(op, ctx);
+      if (bodyInfo?.kind === 'model') {
+        const bodyModel = ctx.spec.models.find((m) => m.name === bodyInfo.name);
+        let payloadDesc: string;
+        if (bodyModel?.description) {
+          payloadDesc = `@param payload - ${bodyModel.description}`;
+        } else if (bodyModel) {
+          // When the model lacks a description, list its required fields to help
+          // callers understand what must be provided.
+          const requiredFieldNames = bodyModel.fields.filter((f) => f.required).map((f) => fieldName(f.name));
+          payloadDesc =
+            requiredFieldNames.length > 0
+              ? `@param payload - Object containing ${requiredFieldNames.join(', ')}.`
+              : '@param payload - The request body.';
+        } else {
+          payloadDesc = '@param payload - The request body.';
+        }
+        docParts.push(payloadDesc);
       } else {
-        payloadDesc = '@param payload - The request body.';
+        docParts.push('@param payload - The request body.');
       }
-      docParts.push(payloadDesc);
-    } else {
-      docParts.push('@param payload - The request body.');
     }
-  }
-  // Document options parameter for paginated operations
-  if (plan.isPaginated) {
-    docParts.push('@param options - Pagination and filter options.');
-  } else if (op.queryParams.length > 0) {
-    docParts.push('@param options - Additional query options.');
-  }
-  // @returns for the primary response model (use item type for paginated operations).
-  // Unwrap list wrapper models to match the actual return type — the method returns
-  // AutoPaginatable<ItemType>, not the list wrapper.
-  if (plan.isPaginated && op.pagination?.itemType.kind === 'model') {
-    let itemRawName = op.pagination.itemType.name;
-    const pModel = modelMap.get(itemRawName);
-    if (pModel) {
-      const unwrapped = unwrapListModel(pModel, modelMap);
-      if (unwrapped) itemRawName = unwrapped.name;
+    // Document options parameter for paginated operations
+    if (plan.isPaginated) {
+      docParts.push('@param options - Pagination and filter options.');
+    } else if (op.queryParams.filter((q) => !hiddenParams.has(q.name)).length > 0) {
+      docParts.push('@param options - Additional query options.');
     }
-    const itemTypeName = resolveInterfaceName(itemRawName, ctx);
-    docParts.push(`@returns {AutoPaginatable<${itemTypeName}>}`);
-  } else if (responseModel) {
-    docParts.push(`@returns {${responseModel}}`);
-  } else {
-    docParts.push('@returns {void}');
-  }
-  // @throws for error responses
-  for (const err of op.errors) {
-    const exceptionName = STATUS_TO_EXCEPTION_NAME[err.statusCode];
-    if (exceptionName) {
-      docParts.push(`@throws {${exceptionName}} ${err.statusCode}`);
+    // @returns for the primary response model.
+    // When an overlay method exists, prefer its return type so the JSDoc
+    // matches the actual TypeScript signature (the overlay may use a
+    // different model name than the OpenAPI schema).
+    if (overlayMethod?.returnType) {
+      docParts.push(`@returns {${overlayMethod.returnType}}`);
+    } else if (plan.isPaginated && op.pagination?.itemType.kind === 'model') {
+      // Unwrap list wrapper models to match the actual return type — the method returns
+      // AutoPaginatable<ItemType>, not the list wrapper.
+      let itemRawName = op.pagination.itemType.name;
+      const pModel = modelMap.get(itemRawName);
+      if (pModel) {
+        const unwrapped = unwrapListModel(pModel, modelMap);
+        if (unwrapped) itemRawName = unwrapped.name;
+      }
+      const itemTypeName = resolveInterfaceName(itemRawName, ctx);
+      docParts.push(`@returns {Promise<AutoPaginatable<${itemTypeName}>>}`);
+    } else if (responseModel) {
+      docParts.push(`@returns {Promise<${responseModel}>}`);
+    } else {
+      docParts.push('@returns {Promise<void>}');
     }
-  }
-  if (op.deprecated) docParts.push('@deprecated');
-
-  if (docParts.length > 0) {
-    // Flatten all parts, splitting multiline descriptions into individual lines
-    const allLines: string[] = [];
-    for (const part of docParts) {
-      for (const line of part.split('\n')) {
-        allLines.push(line);
+    // @throws for error responses
+    for (const err of op.errors) {
+      const exceptionName = STATUS_TO_EXCEPTION_NAME[err.statusCode];
+      if (exceptionName) {
+        docParts.push(`@throws {${exceptionName}} ${err.statusCode}`);
       }
     }
-    if (allLines.length === 1) {
-      lines.push(`  /** ${allLines[0]} */`);
-    } else {
-      lines.push('  /**');
-      for (const line of allLines) {
-        lines.push(line === '' ? '   *' : `   * ${line}`);
+    if (op.deprecated) docParts.push('@deprecated');
+
+    if (docParts.length > 0) {
+      // Flatten all parts, splitting multiline descriptions into individual lines
+      const allLines: string[] = [];
+      for (const part of docParts) {
+        for (const line of part.split('\n')) {
+          allLines.push(line);
+        }
+      }
+      if (allLines.length === 1) {
+        lines.push(`  /** ${allLines[0]} */`);
+      } else {
+        lines.push('  /**');
+        for (const line of allLines) {
+          lines.push(line === '' ? '   *' : `   * ${line}`);
+        }
+        lines.push('   */');
       }
-      lines.push('   */');
     }
   }
 
@@ -895,9 +781,9 @@ function renderMethod(
   } else if (plan.hasBody && responseModel) {
     renderBodyMethod(lines, op, plan, method, responseModel, pathStr, ctx, specEnumNames);
   } else if (responseModel) {
-    renderGetMethod(lines, op, plan, method, responseModel, pathStr, specEnumNames);
+    renderGetMethod(lines, op, plan, method, responseModel, pathStr, specEnumNames, resolvedOp);
   } else {
-    renderVoidMethod(lines, op, plan, method, pathStr, ctx, specEnumNames);
+    renderVoidMethod(lines, op, plan, method, pathStr, ctx, specEnumNames, resolvedOp);
   }
 
   // Defensive: if no render function produced a method body, emit a stub
@@ -1081,21 +967,78 @@ function renderGetMethod(
   responseModel: string,
   pathStr: string,
   specEnumNames?: Set<string>,
+  resolvedOp?: ResolvedOperation,
 ): void {
-  const params = buildPathParams(op, specEnumNames);
-  const hasQuery = op.queryParams.length > 0 && !plan.isPaginated;
-  const optionsType = hasQuery ? toPascalCase(method) + 'Options' : null;
+  const hiddenParams = new Set<string>([
+    ...Object.keys(getOpDefaults(resolvedOp)),
+    ...getOpInferFromClient(resolvedOp),
+  ]);
 
-  const allParams = hasQuery ? (params ? `${params}, options?: ${optionsType}` : `options?: ${optionsType}`) : params;
+  const params = buildPathParams(op, specEnumNames);
+  const visibleQueryParams = op.queryParams.filter((p) => !hiddenParams.has(p.name));
+  const hasVisibleQuery = visibleQueryParams.length > 0 && !plan.isPaginated;
+  const hasDefaults = Object.keys(getOpDefaults(resolvedOp)).length > 0;
+  const hasInferred = getOpInferFromClient(resolvedOp).length > 0;
+  const hasInjected = hasDefaults || hasInferred;
+  const hasQuery = (op.queryParams.length > 0 && !plan.isPaginated) || hasInjected;
+  const optionsType = hasVisibleQuery ? toPascalCase(method) + 'Options' : null;
+
+  const allParams = optionsType
+    ? params
+      ? `${params}, options?: ${optionsType}`
+      : `options?: ${optionsType}`
+    : params;
 
   lines.push(`  async ${method}(${allParams}): Promise<${responseModel}> {`);
   if (hasQuery) {
-    const queryExpr = renderQueryExpr(op.queryParams);
-    lines.push(
-      `    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(${pathStr}, {`,
-    );
-    lines.push(`      query: ${queryExpr},`);
-    lines.push('    });');
+    if (hasInjected) {
+      // Build the query object with visible params, defaults, and inferred fields
+      const queryParts: string[] = [];
+
+      // Regular visible query params (from options)
+      if (hasVisibleQuery) {
+        for (const param of visibleQueryParams) {
+          const camel = fieldName(param.name);
+          const snake = wireFieldName(param.name);
+          if (camel === snake) {
+            if (param.required) {
+              queryParts.push(`${camel}: options.${camel}`);
+            } else {
+              queryParts.push(`...(options?.${camel} !== undefined && { ${camel}: options.${camel} })`);
+            }
+          } else {
+            if (param.required) {
+              queryParts.push(`${snake}: options.${camel}`);
+            } else {
+              queryParts.push(`...(options?.${camel} !== undefined && { ${snake}: options.${camel} })`);
+            }
+          }
+        }
+      }
+
+      // Constant defaults (e.g., response_type: 'code')
+      for (const [key, value] of Object.entries(getOpDefaults(resolvedOp))) {
+        queryParts.push(`${key}: ${tsLiteral(value)}`);
+      }
+
+      // Inferred fields from client config (e.g., client_id from this.workos.options.clientId)
+      for (const field of getOpInferFromClient(resolvedOp)) {
+        queryParts.push(`${field}: ${clientFieldExpression(field)}`);
+      }
+
+      lines.push(
+        `    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(${pathStr}, {`,
+      );
+      lines.push(`      query: { ${queryParts.join(', ')} },`);
+      lines.push('    });');
+    } else {
+      const queryExpr = renderQueryExpr(visibleQueryParams);
+      lines.push(
+        `    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(${pathStr}, {`,
+      );
+      lines.push(`      query: ${queryExpr},`);
+      lines.push('    });');
+    }
   } else if (httpMethodNeedsBody(op.httpMethod)) {
     // PUT/PATCH/POST require a body argument even when the spec has no request body
     lines.push(
@@ -1110,6 +1053,25 @@ function renderGetMethod(
   lines.push('  }');
 }
 
+/** Convert a JS value to a TypeScript literal. */
+function tsLiteral(value: string | number | boolean): string {
+  if (typeof value === 'string') return `'${value.replace(/'/g, "\\'")}'`;
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  return String(value);
+}
+
+/** Get the TypeScript expression for reading a client config field. */
+function clientFieldExpression(field: string): string {
+  switch (field) {
+    case 'client_id':
+      return 'this.workos.options.clientId';
+    case 'client_secret':
+      return 'this.workos.key';
+    default:
+      return `this.workos.${toCamelCase(field)}`;
+  }
+}
+
 function renderVoidMethod(
   lines: string[],
   op: Operation,
@@ -1118,10 +1080,21 @@ function renderVoidMethod(
   pathStr: string,
   ctx: EmitterContext,
   specEnumNames?: Set<string>,
+  resolvedOp?: ResolvedOperation,
 ): void {
+  const hiddenParams = new Set<string>([
+    ...Object.keys(getOpDefaults(resolvedOp)),
+    ...getOpInferFromClient(resolvedOp),
+  ]);
+
   const params = buildPathParams(op, specEnumNames);
-  const hasQuery = op.queryParams.length > 0 && !plan.hasBody;
-  const optionsType = hasQuery ? toPascalCase(method) + 'Options' : null;
+  const visibleQueryParams = op.queryParams.filter((p) => !hiddenParams.has(p.name));
+  const hasVisibleQuery = visibleQueryParams.length > 0 && !plan.hasBody;
+  const hasDefaults = Object.keys(getOpDefaults(resolvedOp)).length > 0;
+  const hasInferred = getOpInferFromClient(resolvedOp).length > 0;
+  const hasInjected = hasDefaults || hasInferred;
+  const hasQuery = hasVisibleQuery || (hasInjected && !plan.hasBody);
+  const optionsType = hasVisibleQuery ? toPascalCase(method) + 'Options' : null;
 
   let bodyParam = '';
   let bodyExpr = 'payload';
@@ -1154,10 +1127,47 @@ function renderVoidMethod(
   if (plan.hasBody) {
     lines.push(`    await this.workos.${op.httpMethod}(${pathStr}, ${bodyExpr});`);
   } else if (hasQuery) {
-    const queryExpr = renderQueryExpr(op.queryParams);
-    lines.push(`    await this.workos.${op.httpMethod}(${pathStr}, {`);
-    lines.push(`      query: ${queryExpr},`);
-    lines.push('    });');
+    if (hasInjected) {
+      // Build query object with visible params, defaults, and inferred fields
+      const queryParts: string[] = [];
+
+      if (hasVisibleQuery) {
+        for (const param of visibleQueryParams) {
+          const camel = fieldName(param.name);
+          const snake = wireFieldName(param.name);
+          if (camel === snake) {
+            if (param.required) {
+              queryParts.push(`${camel}: options.${camel}`);
+            } else {
+              queryParts.push(`...(options?.${camel} !== undefined && { ${camel}: options.${camel} })`);
+            }
+          } else {
+            if (param.required) {
+              queryParts.push(`${snake}: options.${camel}`);
+            } else {
+              queryParts.push(`...(options?.${camel} !== undefined && { ${snake}: options.${camel} })`);
+            }
+          }
+        }
+      }
+
+      for (const [key, value] of Object.entries(getOpDefaults(resolvedOp))) {
+        queryParts.push(`${key}: ${tsLiteral(value)}`);
+      }
+
+      for (const field of getOpInferFromClient(resolvedOp)) {
+        queryParts.push(`${field}: ${clientFieldExpression(field)}`);
+      }
+
+      lines.push(`    await this.workos.${op.httpMethod}(${pathStr}, {`);
+      lines.push(`      query: { ${queryParts.join(', ')} },`);
+      lines.push('    });');
+    } else {
+      const queryExpr = renderQueryExpr(visibleQueryParams);
+      lines.push(`    await this.workos.${op.httpMethod}(${pathStr}, {`);
+      lines.push(`      query: ${queryExpr},`);
+      lines.push('    });');
+    }
   } else if (httpMethodNeedsBody(op.httpMethod)) {
     lines.push(`    await this.workos.${op.httpMethod}(${pathStr}, {});`);
   } else {