@workos/oagen-emitters 0.2.0 → 0.3.0

package/src/node/resources.ts

@@ -1,22 +1,45 @@
 // @oagen-ignore: Operation.async — all TypeScript SDK methods are async by nature
 
-import type { Service, Operation, EmitterContext, GeneratedFile, TypeRef, Model } from '@workos/oagen';
-import { planOperation, toPascalCase } 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';
 import {
   fieldName,
   wireFieldName,
   fileName,
-  serviceDirName,
+  resolveServiceDir,
   resolveMethodName,
   resolveInterfaceName,
   resolveServiceName,
   wireInterfaceName,
 } from './naming.js';
-import { docComment, createServiceDirResolver, isServiceCoveredByExisting, uncoveredOperations } from './utils.js';
+import {
+  docComment,
+  createServiceDirResolver,
+  isServiceCoveredByExisting,
+  hasMethodsAbsentFromBaseline,
+  uncoveredOperations,
+} 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
@@ -57,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.
@@ -85,28 +102,135 @@ function httpMethodNeedsBody(method: string): boolean {
   return method === 'post' || method === 'put' || method === 'patch';
 }
 
+// ---------------------------------------------------------------------------
+// Method-name deduplication helpers
+// ---------------------------------------------------------------------------
+
+/** Split a camelCase/PascalCase name into lowercase word parts. */
+function splitCamelWords(name: string): string[] {
+  const parts: string[] = [];
+  let start = 0;
+  for (let i = 1; i < name.length; i++) {
+    if (name[i] >= 'A' && name[i] <= 'Z') {
+      parts.push(name.slice(start, i).toLowerCase());
+      start = i;
+    }
+  }
+  parts.push(name.slice(start).toLowerCase());
+  return parts;
+}
+
+/** Naive singularize: strip trailing 's' unless it ends in 'ss'. */
+function singularize(word: string): string {
+  return word.endsWith('s') && !word.endsWith('ss') ? word.slice(0, -1) : word;
+}
+
+/**
+ * Deduplicate method names within the plans array.
+ *
+ * When `disambiguateOperationNames()` in `@workos/oagen` fails (e.g., for
+ * single-segment paths like `/organizations`), two operations can resolve to
+ * the same method name. Disambiguate by appending a path-derived suffix.
+ */
+function deduplicateMethodNames(
+  plans: Array<{ op: Operation; plan: OperationPlan; method: string }>,
+  _ctx: EmitterContext,
+): void {
+  const nameCount = new Map<string, number>();
+  for (const p of plans) {
+    nameCount.set(p.method, (nameCount.get(p.method) ?? 0) + 1);
+  }
+
+  for (const [name, count] of nameCount) {
+    if (count <= 1) continue;
+    const dupes = plans.filter((p) => p.method === name);
+
+    // If all duplicates are on the SAME base path (different HTTP methods),
+    // trust the names — they represent the same resource.
+    const basePaths = new Set(dupes.map((d) => d.op.path.replace(/\/\{[^}]+\}$/, '')));
+    if (basePaths.size <= 1) continue;
+
+    // Disambiguate: keep the name for the plan whose path best matches,
+    // append path suffix for the others.
+    // Score: how many words in the method name appear in the path segments
+    const nameWords = new Set(splitCamelWords(name).map(singularize));
+    const scored = dupes.map((d) => {
+      const pathWords = d.op.path
+        .split('/')
+        .filter((s) => s && !s.startsWith('{'))
+        .flatMap((s) => s.split('_'))
+        .map(singularize);
+      const overlap = pathWords.filter((w) => nameWords.has(w)).length;
+      return { plan: d, score: overlap };
+    });
+    scored.sort((a, b) => b.score - a.score);
+
+    // The best-scoring plan keeps the name; others get disambiguated
+    for (let i = 1; i < scored.length; i++) {
+      const dupe = scored[i].plan;
+      const segments = dupe.op.path.split('/').filter((s) => s && !s.startsWith('{'));
+      // Use first segment as suffix (the resource collection name)
+      const suffix = segments[0] ?? '';
+      if (suffix) {
+        dupe.method = toCamelCase(`${name}_${suffix}`);
+      }
+    }
+
+    // If still colliding after suffix, append index
+    const stillDuped = new Map<string, typeof dupes>();
+    for (const dupe of dupes) {
+      const group = stillDuped.get(dupe.method) ?? [];
+      group.push(dupe);
+      stillDuped.set(dupe.method, group);
+    }
+    for (const [, group] of stillDuped) {
+      if (group.length <= 1) continue;
+      for (let i = 1; i < group.length; i++) {
+        group[i].method = `${group[i].method}${i + 1}`;
+      }
+    }
+  }
+}
+
 export function generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
   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 — skip entirely
+      // Fully covered: generate with ALL operations so the merger's docstring
+      // refresh pass can update JSDoc on existing methods.
+      const file = generateResourceClass(service, ctx);
+      // When the baseline class is missing methods for some operations,
+      // 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;
     }
 
-    // Check for partial coverage: some operations covered, some not.
-    // Generate methods only for uncovered operations.
     const ops = uncoveredOperations(service, ctx);
     if (ops.length === 0) continue;
 
     if (ops.length < service.operations.length) {
-      // Partial coverage: create a service with only uncovered operations.
-      // Remove skipIfExists so the merger can add these new methods to the
-      // existing class file (otherwise uncovered operations are silently lost).
-      const partialService = { ...service, operations: ops };
-      const file = generateResourceClass(partialService, ctx);
+      // Partial coverage: generate with ALL operations so JSDoc is available
+      // for both covered and uncovered methods.  Remove skipIfExists so the
+      // 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));
@@ -118,7 +242,7 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
 
 function generateResourceClass(service: Service, ctx: EmitterContext): GeneratedFile {
   const resolvedName = resolveResourceClassName(service, ctx);
-  const serviceDir = serviceDirName(resolvedName);
+  const serviceDir = resolveServiceDir(resolvedName);
   const serviceClass = resolvedName;
   const resourcePath = `src/${serviceDir}/${fileName(resolvedName)}.ts`;
 
@@ -128,6 +252,13 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
     method: resolveMethodName(op, 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).
+  deduplicateMethodNames(plans, ctx);
+
   // Sort plans to match the existing file's method order.
   // When the merger integrates generated content with existing files, its
   // URL-fingerprint fallback (pass 2) matches by position among methods that
@@ -136,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;
       });
     }
@@ -156,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).
@@ -192,11 +347,10 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
           requestModels.add(name);
         }
       } else {
-        // Non-discriminated union: import variant models as domain types only.
-        // Without a discriminator we can't statically dispatch serialization,
-        // so the payload is passed through as-is.
+        // Non-discriminated union: import variant models with serializers so we
+        // can dispatch to the correct serializer at runtime via field guards.
         for (const name of bodyInfo.modelNames) {
-          paramModels.add(name);
+          requestModels.add(name);
         }
       }
     }
@@ -210,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[] = [];
@@ -355,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('');
     }
   }
 
@@ -381,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('}');
@@ -397,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.
@@ -418,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)`);
-    }
-    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)`);
+  // 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)}`);
+    }
+    // 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);
+    }
+    // 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.');
+    }
+    // @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('@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;
-    }
-    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}`);
+      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('   */');
     }
   }
 
@@ -574,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
@@ -649,7 +856,7 @@ function renderDeleteWithBodyMethod(
     if (bodyInfo.discriminator) {
       bodyExpr = renderUnionBodySerializer(bodyInfo.discriminator, ctx);
     } else {
-      bodyExpr = 'payload';
+      bodyExpr = renderNonDiscriminatedUnionBodySerializer(bodyInfo.modelNames, ctx);
     }
   } else {
     requestType = 'Record<string, unknown>';
@@ -688,12 +895,9 @@ function renderBodyMethod(
   } else if (bodyInfo?.kind === 'union') {
     requestType = bodyInfo.typeStr;
     if (bodyInfo.discriminator) {
-      // Discriminated union: dispatch to the correct serializer at runtime.
       bodyExpr = renderUnionBodySerializer(bodyInfo.discriminator, ctx);
     } else {
-      // Non-discriminated union: cannot statically dispatch —
-      // pass the payload directly (caller provides the correct shape).
-      bodyExpr = 'payload';
+      bodyExpr = renderNonDiscriminatedUnionBodySerializer(bodyInfo.modelNames, ctx);
     }
   } else {
     requestType = 'Record<string, unknown>';
@@ -763,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(
@@ -792,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,
@@ -800,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';
@@ -818,7 +1109,7 @@ function renderVoidMethod(
       if (bodyInfo.discriminator) {
         bodyExpr = renderUnionBodySerializer(bodyInfo.discriminator, ctx);
       } else {
-        bodyExpr = 'payload';
+        bodyExpr = renderNonDiscriminatedUnionBodySerializer(bodyInfo.modelNames, ctx);
       }
     } else {
       bodyParam = 'payload: Record<string, unknown>';
@@ -836,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 {
@@ -940,6 +1268,122 @@ function renderUnionBodySerializer(
   return `(() => { switch ((payload as any).${prop}) { ${cases.join('; ')}; default: return payload } })()`;
 }
 
+/**
+ * Generate an IIFE expression that dispatches to the correct serializer for a
+ * non-discriminated union request body.  Inspects model fields to find a
+ * required field unique to each variant and uses `'field' in payload` guards.
+ * Falls back to `payload` only when no variant can be distinguished.
+ */
+function renderNonDiscriminatedUnionBodySerializer(modelNames: string[], ctx: EmitterContext): string {
+  const modelMap = new Map(ctx.spec.models.map((m) => [m.name, m]));
+
+  // Try to detect an implicit discriminator: a required field present in all
+  // variants whose type is `kind: 'literal'` with a distinct value per variant.
+  // This covers oneOf unions where each variant has e.g. `grant_type: 'authorization_code'`.
+  const implicitDisc = detectImplicitDiscriminator(modelNames, modelMap);
+  if (implicitDisc) {
+    return renderUnionBodySerializer(implicitDisc, ctx);
+  }
+
+  // Collect required field names per model (using camelCase domain names).
+  const requiredFieldsByModel = new Map<string, Set<string>>();
+  for (const name of modelNames) {
+    const model = modelMap.get(name);
+    if (!model) return 'payload';
+    requiredFieldsByModel.set(name, new Set(model.fields.filter((f) => f.required).map((f) => fieldName(f.name))));
+  }
+
+  // For each model, find a required field that no other model has.
+  const guards: Array<{ modelName: string; field: string }> = [];
+  let fallbackModel: string | undefined;
+
+  for (const name of modelNames) {
+    const myFields = requiredFieldsByModel.get(name)!;
+    let uniqueField: string | undefined;
+    for (const field of myFields) {
+      const isUnique = modelNames.every((other) => other === name || !requiredFieldsByModel.get(other)?.has(field));
+      if (isUnique) {
+        uniqueField = field;
+        break;
+      }
+    }
+    if (uniqueField) {
+      guards.push({ modelName: name, field: uniqueField });
+    } else if (!fallbackModel) {
+      fallbackModel = name;
+    } else {
+      // Multiple models with no unique field — can't dispatch
+      return 'payload';
+    }
+  }
+
+  if (guards.length === 0) return 'payload';
+
+  const parts: string[] = [];
+  for (const { modelName, field } of guards) {
+    const resolved = resolveInterfaceName(modelName, ctx);
+    parts.push(`if ('${field}' in payload) return serialize${resolved}(payload as any)`);
+  }
+  if (fallbackModel) {
+    const resolved = resolveInterfaceName(fallbackModel, ctx);
+    parts.push(`return serialize${resolved}(payload as any)`);
+  } else {
+    parts.push('return payload');
+  }
+
+  return `(() => { ${parts.join('; ')} })()`;
+}
+
+/**
+ * Detect an implicit discriminator from literal-typed fields.
+ * Returns a discriminator descriptor if all variants share a required field
+ * whose type is `kind: 'literal'` with a distinct value per variant.
+ */
+function detectImplicitDiscriminator(
+  modelNames: string[],
+  modelMap: Map<string, Model>,
+): { property: string; mapping: Record<string, string> } | null {
+  if (modelNames.length < 2) return null;
+
+  const firstModel = modelMap.get(modelNames[0]);
+  if (!firstModel) return null;
+
+  // Candidate fields: required fields with literal type in the first model.
+  const candidates = firstModel.fields.filter((f) => f.required && f.type.kind === 'literal');
+
+  for (const candidate of candidates) {
+    const mapping: Record<string, string> = {};
+    const values = new Set<string | number | boolean | null>();
+    let valid = true;
+
+    for (const name of modelNames) {
+      const model = modelMap.get(name);
+      if (!model) {
+        valid = false;
+        break;
+      }
+      const field = model.fields.find((f) => f.name === candidate.name);
+      if (!field || !field.required || field.type.kind !== 'literal') {
+        valid = false;
+        break;
+      }
+      const val = field.type.value;
+      if (values.has(val)) {
+        valid = false;
+        break;
+      } // duplicate value
+      values.add(val);
+      mapping[String(val)] = name;
+    }
+
+    if (valid && Object.keys(mapping).length === modelNames.length) {
+      return { property: candidate.name, mapping };
+    }
+  }
+
+  return null;
+}
+
 /** Return type for extractRequestBodyType when the body is a union. */
 interface UnionBodyInfo {
   kind: 'union';
@@ -961,7 +1405,12 @@ function extractRequestBodyType(
     }
     if (modelNames.length > 0) {
       const typeStr = modelNames.map((n) => resolveInterfaceName(n, ctx)).join(' | ');
-      return { kind: 'union', typeStr, modelNames, discriminator: op.requestBody.discriminator };
+      return {
+        kind: 'union',
+        typeStr,
+        modelNames,
+        discriminator: op.requestBody.discriminator,
+      };
     }
   }
   return null;