@workos/oagen-emitters 0.4.0 → 0.6.0

package/src/dotnet/resources.ts

@@ -5,16 +5,20 @@ import type {
   EmitterContext,
   GeneratedFile,
   ResolvedOperation,
+  Model,
+  TypeRef,
 } from '@workos/oagen';
 import { planOperation } from '@workos/oagen';
 import { isListWrapperModel } from './models.js';
-import { mapTypeRef, isValueTypeRef, isEnumRef, emitJsonPropertyAttributes } from './type-map.js';
+import { mapTypeRef, isValueTypeRef, isEnumRef, emitJsonPropertyAttributes, resolveModelName } from './type-map.js';
 import {
+  appendAsyncSuffix,
   className,
   fieldName,
   methodName,
   resolveClassName,
   resolveMethodName,
+  resolveMethodStem,
   serviceTypeName,
   localName,
   csLiteral,
@@ -26,6 +30,7 @@ import {
   deprecationMessage,
   escapeCsAttributeString,
   humanize,
+  modelClassName,
 } from './naming.js';
 import {
   buildResolvedLookup,
@@ -35,6 +40,8 @@ import {
   getOpInferFromClient,
   buildHiddenParams,
   hasHiddenParams,
+  collectGroupedParamNames,
+  collectBodyFieldTypes,
 } from '../shared/resolved-ops.js';
 import { generateWrapperMethods } from './wrappers.js';
 
@@ -82,6 +89,193 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
   return files;
 }
 
+// ---------------------------------------------------------------------------
+// Mutually-exclusive parameter group support
+// ---------------------------------------------------------------------------
+
+/** Abstract base class name for a parameter group (e.g. UserManagementRole). */
+function groupBaseClassName(mountName: string, groupName: string): string {
+  return `${className(mountName)}${className(groupName)}`;
+}
+
+/** Concrete variant class name (e.g. UserManagementRoleSingle). */
+function groupVariantClassName(mountName: string, groupName: string, variantName: string): string {
+  return `${className(mountName)}${className(groupName)}${className(variantName)}`;
+}
+
+/**
+ * Generate C# abstract base class + concrete subtypes for all parameter groups
+ * on an operation. Each group becomes an abstract class with concrete subclasses
+ * for each variant containing the variant's parameters as properties.
+ */
+function generateParameterGroupTypes(
+  mountName: string,
+  op: Operation,
+  models: Model[],
+  emitted?: Set<string>,
+): string[] {
+  const lines: string[] = [];
+  const bodyFieldTypes = collectBodyFieldTypes(op, models);
+
+  for (const group of op.parameterGroups ?? []) {
+    const baseName = groupBaseClassName(mountName, group.name);
+    if (emitted?.has(baseName)) continue;
+    emitted?.add(baseName);
+
+    lines.push('');
+    lines.push(`    public abstract class ${baseName} { }`);
+
+    for (const variant of group.variants) {
+      const variantName = groupVariantClassName(mountName, group.name, variant.name);
+      lines.push('');
+      lines.push(`    public class ${variantName} : ${baseName}`);
+      lines.push('    {');
+      for (const param of variant.parameters) {
+        const csField = fieldName(param.name);
+        const effectiveType = bodyFieldTypes.get(param.name) ?? param.type;
+        const csType = mapTypeRef(effectiveType);
+        lines.push(`        public ${csType} ${csField} { get; set; } = default!;`);
+        lines.push('');
+      }
+      lines.push('    }');
+    }
+  }
+
+  return lines;
+}
+
+/**
+ * Emit manual serialization for parameter group variants in the service
+ * method body. Each group field on the options class is pattern-matched via
+ * `is` checks and its variant parameters are added to the appropriate target
+ * (query string or request body).
+ */
+function emitGroupSerialization(
+  mountName: string,
+  op: Operation,
+  indent: string,
+  models: Model[],
+  target: 'query' | 'body',
+): string[] {
+  const lines: string[] = [];
+  const bodyFieldTypes = collectBodyFieldTypes(op, models);
+
+  for (const group of op.parameterGroups ?? []) {
+    const groupField = fieldName(group.name);
+    let first = true;
+
+    for (const variant of group.variants) {
+      const variantName = groupVariantClassName(mountName, group.name, variant.name);
+      // Use a short local variable derived from the variant name
+      const localVar = localName(variant.name);
+      const keyword = first ? 'if' : 'else if';
+      first = false;
+
+      lines.push(`${indent}${keyword} (options?.${groupField} is ${variantName} ${localVar})`);
+      lines.push(`${indent}{`);
+      let prevWasBlock = false;
+      for (const param of variant.parameters) {
+        const csField = fieldName(param.name);
+        const effectiveType = bodyFieldTypes.get(param.name) ?? param.type;
+        const accessor = `${localVar}.${csField}`;
+        const paramLines = emitParamValue(param.name, accessor, effectiveType, indent + '    ', target);
+        // SA1513: closing brace must be followed by a blank line before the next statement
+        if (prevWasBlock) lines.push('');
+        lines.push(...paramLines);
+        prevWasBlock = paramLines.length > 1;
+      }
+      lines.push(`${indent}}`);
+    }
+  }
+
+  return lines;
+}
+
+/**
+ * Emit one or more lines to add a param to the query string or request body,
+ * adapting to the parameter's IR type: enums use JsonConvert for wire-value
+ * serialization, arrays are comma-joined, and reference types (string, List)
+ * get a null guard.
+ *
+ * Reference types always get a null guard because variant classes are shared
+ * across operations whose body models may disagree on nullability.
+ */
+function emitParamValue(
+  wireName: string,
+  accessor: string,
+  typeRef: TypeRef,
+  indent: string,
+  target: 'query' | 'body',
+): string[] {
+  const method = target === 'body' ? 'AddBodyParam' : 'AddQueryParam';
+  const isNullable = typeRef.kind === 'nullable';
+  const inner: TypeRef = isNullable ? (typeRef as { kind: 'nullable'; inner: TypeRef }).inner : typeRef;
+
+  // Reference types (arrays, strings, models) are always guarded for null
+  // because the variant class property may be nullable even when the current
+  // operation's body model says "required".
+  const needsNullGuard = isNullable || !isValueTypeRef(inner);
+
+  if (inner.kind === 'array') {
+    // Body params pass the list directly so it serializes as a JSON array;
+    // query params comma-join into a single string value.
+    const valueExpr = target === 'body' ? accessor : `string.Join(",", ${accessor})`;
+    if (needsNullGuard) {
+      return [
+        `${indent}if (${accessor} != null)`,
+        `${indent}{`,
+        `${indent}    request.${method}("${wireName}", ${valueExpr});`,
+        `${indent}}`,
+      ];
+    }
+    return [`${indent}request.${method}("${wireName}", ${valueExpr});`];
+  }
+
+  if (inner.kind === 'enum') {
+    const serExpr = `JsonConvert.SerializeObject(${accessor}).Trim('"')`;
+    if (isNullable) {
+      return [
+        `${indent}if (${accessor} != null)`,
+        `${indent}{`,
+        `${indent}    request.${method}("${wireName}", ${serExpr});`,
+        `${indent}}`,
+      ];
+    }
+    return [`${indent}request.${method}("${wireName}", ${serExpr});`];
+  }
+
+  if (needsNullGuard) {
+    return [
+      `${indent}if (${accessor} != null)`,
+      `${indent}{`,
+      `${indent}    request.${method}("${wireName}", ${accessor});`,
+      `${indent}}`,
+    ];
+  }
+
+  return [`${indent}request.${method}("${wireName}", ${accessor});`];
+}
+
+/** Check whether any parameter group variant contains an enum-typed parameter. */
+function groupsNeedJsonConvert(operations: Operation[], models: Model[]): boolean {
+  for (const op of operations) {
+    const bodyFieldTypes = collectBodyFieldTypes(op, models);
+    for (const group of op.parameterGroups ?? []) {
+      for (const variant of group.variants) {
+        for (const param of variant.parameters) {
+          const effectiveType = bodyFieldTypes.get(param.name) ?? param.type;
+          const inner: TypeRef =
+            effectiveType.kind === 'nullable'
+              ? (effectiveType as { kind: 'nullable'; inner: TypeRef }).inner
+              : effectiveType;
+          if (inner.kind === 'enum') return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
 function generateServiceFile(mountName: string, operations: Operation[], ctx: EmitterContext): GeneratedFile | null {
   const lines: string[] = [];
   const svcTypeName = serviceTypeName(mountName);
@@ -91,10 +285,14 @@ function generateServiceFile(mountName: string, operations: Operation[], ctx: Em
 
   lines.push(`namespace ${ctx.namespacePascal}`);
   lines.push('{');
+  lines.push('    using System;');
   lines.push('    using System.Collections.Generic;');
   lines.push('    using System.Net.Http;');
   lines.push('    using System.Threading;');
   lines.push('    using System.Threading.Tasks;');
+  if (groupsNeedJsonConvert(operations, ctx.spec.models)) {
+    lines.push('    using Newtonsoft.Json;');
+  }
   lines.push('');
   lines.push(
     `    /// <summary>Service that exposes the ${humanize(mountName)} API operations on <see cref="WorkOSClient"/>.</summary>`,
@@ -119,6 +317,7 @@ function generateServiceFile(mountName: string, operations: Operation[], ctx: Em
   const emittedMethods = new Set<string>();
   for (const op of operations) {
     const plan = planOperation(op);
+    const methodStem = resolveCsMethodStem(op, mountName, ctx);
     const method = resolveCsMethodName(op, mountName, ctx);
 
     if (emittedMethods.has(method)) continue;
@@ -132,13 +331,18 @@ function generateServiceFile(mountName: string, operations: Operation[], ctx: Em
     // get a 422 from the API. Only emit the typed AuthenticateWith* wrappers.
     if (!isUnionSplit) {
       lines.push('');
-      const methodCode = generateMethod(svcTypeName, mountName, method, op, plan, ctx, resolvedOp);
+      const methodCode = generateMethod(svcTypeName, mountName, method, methodStem, op, plan, ctx, resolvedOp);
       lines.push(methodCode);
 
+      if (!(resolvedOp?.urlBuilder ?? false) && method !== methodStem) {
+        lines.push('');
+        lines.push(generateCompatibilityMethod(mountName, method, methodStem, op, plan, ctx, resolvedOp));
+      }
+
       // Generate auto-pagination method for paginated list operations
       if (plan.isPaginated && op.pagination) {
         lines.push('');
-        const autoPagingCode = generateAutoPagingMethod(mountName, method, op, plan, ctx, resolvedOp);
+        const autoPagingCode = generateAutoPagingMethod(mountName, method, methodStem, op, plan, ctx, resolvedOp);
         lines.push(autoPagingCode);
       }
     }
@@ -148,7 +352,7 @@ function generateServiceFile(mountName: string, operations: Operation[], ctx: Em
       const wrapperLines = generateWrapperMethods(svcTypeName, resolvedOp!, ctx);
       lines.push(...wrapperLines);
       for (const w of resolvedOp!.wrappers!) {
-        emittedMethods.add(methodName(w.name));
+        emittedMethods.add(appendAsyncSuffix(methodName(w.name)));
       }
     }
   }
@@ -176,6 +380,7 @@ function generateOptionsFile(mountName: string, operations: Operation[], ctx: Em
   optionsLines.push('    using STJS = System.Text.Json.Serialization;');
 
   const emittedOptions = new Set<string>();
+  const emittedGroupTypes = new Set<string>();
   for (const op of operations) {
     const plan = planOperation(op);
     const method = resolveCsMethodName(op, mountName, ctx);
@@ -190,7 +395,10 @@ function generateOptionsFile(mountName: string, operations: Operation[], ctx: Em
     const optionsClass = optionsClassName(mountName, method);
     if (emittedOptions.has(optionsClass)) continue;
 
-    const hasVisibleQueryParams = op.queryParams.filter((qp) => !hidden.has(qp.name)).length > 0;
+    const groupedParams = collectGroupedParamNames(op);
+    const hasGroups = (op.parameterGroups?.length ?? 0) > 0;
+    const hasVisibleQueryParams =
+      op.queryParams.filter((qp) => !hidden.has(qp.name) && !groupedParams.has(qp.name)).length > 0;
     const hasBody = plan.hasBody && op.requestBody;
     let hasVisibleBodyFields = false;
     if (hasBody && op.requestBody?.kind === 'model') {
@@ -200,7 +408,7 @@ function generateOptionsFile(mountName: string, operations: Operation[], ctx: Em
       hasVisibleBodyFields = true;
     }
 
-    if (!hasVisibleQueryParams && !hasVisibleBodyFields) continue;
+    if (!hasVisibleQueryParams && !hasVisibleBodyFields && !hasGroups) continue;
 
     emittedOptions.add(optionsClass);
     hasOptions = true;
@@ -225,6 +433,7 @@ function generateOptionsFile(mountName: string, operations: Operation[], ctx: Em
       if (bodyModel) {
         for (const field of bodyModel.fields) {
           if (hidden.has(field.name)) continue;
+          if (groupedParams.has(field.name)) continue;
           const csField = fieldName(field.name);
           if (emittedFields.has(csField)) continue;
           emittedFields.add(csField);
@@ -263,10 +472,12 @@ function generateOptionsFile(mountName: string, operations: Operation[], ctx: Em
       }
     }
 
-    // Query params (skip pagination fields for list options — they're in ListOptions base)
+    // Query params (skip pagination fields for list options — they're in ListOptions base,
+    // and skip grouped params which get their own abstract class hierarchy)
     const PAGINATION_FIELDS = new Set(['before', 'after', 'limit', 'order']);
     for (const param of op.queryParams) {
       if (hidden.has(param.name)) continue;
+      if (groupedParams.has(param.name)) continue;
       if (isPaginated && PAGINATION_FIELDS.has(param.name)) continue;
       const csField = fieldName(param.name);
       if (emittedFields.has(csField)) continue;
@@ -311,8 +522,6 @@ function generateOptionsFile(mountName: string, operations: Operation[], ctx: Em
       const csField = fieldName(key);
       if (emittedFields.has(csField)) continue;
       emittedFields.add(csField);
-      optionsLines.push(`        [JsonProperty("${key}")]`);
-      optionsLines.push(`        [STJS.JsonPropertyName("${key}")]`);
       optionsLines.push(`        internal string ${csField} { get; set; } = default!;`);
       optionsLines.push('');
     }
@@ -320,13 +529,28 @@ function generateOptionsFile(mountName: string, operations: Operation[], ctx: Em
       const csField = fieldName(key);
       if (emittedFields.has(csField)) continue;
       emittedFields.add(csField);
-      optionsLines.push(`        [JsonProperty("${key}")]`);
-      optionsLines.push(`        [STJS.JsonPropertyName("${key}")]`);
       optionsLines.push(`        internal string ${csField} { get; set; } = default!;`);
       optionsLines.push('');
     }
 
+    // Parameter group properties (serialized manually in the service method, not by JSON)
+    for (const group of op.parameterGroups ?? []) {
+      const baseName = groupBaseClassName(mountName, group.name);
+      const csField = fieldName(group.name);
+      optionsLines.push('        [JsonIgnore]');
+      optionsLines.push('        [STJS.JsonIgnore]');
+      const initializer = group.optional ? '' : ' = default!;';
+      const csType = group.optional ? `${baseName}?` : baseName;
+      optionsLines.push(`        public ${csType} ${csField} { get; set; }${initializer}`);
+      optionsLines.push('');
+    }
+
     optionsLines.push('    }');
+
+    // Emit parameter group abstract base + concrete variant classes
+    if (hasGroups) {
+      optionsLines.push(...generateParameterGroupTypes(mountName, op, ctx.spec.models, emittedGroupTypes));
+    }
   }
 
   optionsLines.push('}');
@@ -344,6 +568,7 @@ function generateMethod(
   _serviceType: string,
   mountName: string,
   method: string,
+  methodStem: string,
   op: Operation,
   plan: OperationPlan,
   ctx: EmitterContext,
@@ -354,7 +579,10 @@ function generateMethod(
   const isDelete = plan.isDelete;
   const hasBody = plan.hasBody && op.requestBody;
   const hidden = buildHiddenParams(resolvedOp);
-  const hasVisibleQueryParams = op.queryParams.filter((qp) => !hidden.has(qp.name)).length > 0;
+  const groupedParams = collectGroupedParamNames(op);
+  const hasGroups = (op.parameterGroups?.length ?? 0) > 0;
+  const hasVisibleQueryParams =
+    op.queryParams.filter((qp) => !hidden.has(qp.name) && !groupedParams.has(qp.name)).length > 0;
 
   let hasVisibleBodyFields = false;
   if (hasBody && op.requestBody?.kind === 'model') {
@@ -364,8 +592,8 @@ function generateMethod(
     hasVisibleBodyFields = true;
   }
 
-  const hasParams = hasVisibleBodyFields || hasVisibleQueryParams;
-  const optionsClass = hasParams ? optionsClassName(mountName, method) : null;
+  const hasParams = hasVisibleBodyFields || hasVisibleQueryParams || hasGroups;
+  const optionsClass = hasParams ? optionsClassName(mountName, methodStem) : null;
   const hasHidden = hasHiddenParams(resolvedOp);
 
   // Per-operation Bearer token auth (e.g., SSO GetProfile uses access_token instead of API key)
@@ -388,7 +616,7 @@ function generateMethod(
   } else if (isDelete) {
     returnType = 'Task';
   } else if (plan.responseModelName) {
-    const respType = className(plan.responseModelName);
+    const respType = modelClassName(resolveModelName(plan.responseModelName));
     if (!isPaginated && op.response?.kind === 'array') {
       returnType = `Task<List<${respType}>>`;
     } else {
@@ -420,7 +648,7 @@ function generateMethod(
     const itemType = resolveListItemType(op.pagination.itemType, ctx);
     lines.push(`        /// <returns>A page of <see cref="${itemType}"/> results.</returns>`);
   } else if (plan.responseModelName) {
-    const respType = className(plan.responseModelName);
+    const respType = modelClassName(resolveModelName(plan.responseModelName));
     lines.push(`        /// <returns>The <see cref="${respType}"/> result.</returns>`);
   }
   if (op.deprecated) {
@@ -474,10 +702,11 @@ function generateMethod(
   // Build path
   const pathExpr = buildPathExpr(op);
 
-  // URL-builders and bearer-override operations keep the inlined WorkOSRequest
-  // form because the Service helpers don't expose BuildRequestUri or
-  // AccessToken configuration. Everything else uses the helper one-liners.
-  const needsInlineRequest = isUrlBuilder || (hasBearerOverride && !!bearerParamName);
+  // URL-builders, bearer-override operations, and operations with parameter
+  // groups keep the inlined WorkOSRequest form because the Service helpers
+  // don't expose BuildRequestUri, AccessToken configuration, or manual
+  // query param injection. Everything else uses the helper one-liners.
+  const needsInlineRequest = isUrlBuilder || (hasBearerOverride && !!bearerParamName) || hasGroups;
   const optionsArg = optionsClass ? 'options' : 'null';
 
   if (needsInlineRequest) {
@@ -496,6 +725,17 @@ function generateMethod(
     }
     lines.push('            };');
 
+    // Serialize parameter group variants into query params (GET/DELETE)
+    // or body params (POST/PUT/PATCH) so sensitive fields like passwords
+    // never leak into the URL.  DELETE is routed to query because the
+    // dotnet HTTP client only sends body content for non-GET/DELETE methods.
+    if (hasGroups) {
+      const groupTarget = hasBody && !isDelete ? 'body' : 'query';
+      lines.push('');
+      lines.push(...emitGroupSerialization(mountName, op, '            ', ctx.spec.models, groupTarget));
+      lines.push('');
+    }
+
     if (isUrlBuilder) {
       lines.push('            return this.Client.BuildRequestUri(request).ToString();');
     } else if (returnType.startsWith('Task<')) {
@@ -526,6 +766,7 @@ function generateMethod(
 function generateAutoPagingMethod(
   mountName: string,
   method: string,
+  methodStem: string,
   op: Operation,
   plan: OperationPlan,
   ctx: EmitterContext,
@@ -533,7 +774,10 @@ function generateAutoPagingMethod(
 ): string {
   const lines: string[] = [];
   const hidden = buildHiddenParams(resolvedOp);
-  const hasVisibleQueryParams = op.queryParams.filter((qp) => !hidden.has(qp.name)).length > 0;
+  const groupedParams = collectGroupedParamNames(op);
+  const hasGroups = (op.parameterGroups?.length ?? 0) > 0;
+  const hasVisibleQueryParams =
+    op.queryParams.filter((qp) => !hidden.has(qp.name) && !groupedParams.has(qp.name)).length > 0;
 
   let hasVisibleBodyFields = false;
   if (plan.hasBody && op.requestBody?.kind === 'model') {
@@ -541,8 +785,8 @@ function generateAutoPagingMethod(
     if (bodyModel) hasVisibleBodyFields = bodyModel.fields.some((f) => !hidden.has(f.name));
   }
 
-  const hasParams = hasVisibleBodyFields || hasVisibleQueryParams;
-  const optionsClass = hasParams ? optionsClassName(mountName, method) : null;
+  const hasParams = hasVisibleBodyFields || hasVisibleQueryParams || hasGroups;
+  const optionsClass = hasParams ? optionsClassName(mountName, methodStem) : null;
 
   const itemType = resolveListItemType(op.pagination!.itemType, ctx);
 
@@ -572,7 +816,7 @@ function generateAutoPagingMethod(
   params.push('RequestOptions? requestOptions = null');
   params.push('CancellationToken cancellationToken = default');
 
-  lines.push(`        public virtual IAsyncEnumerable<${itemType}> ${method}AutoPagingAsync(${params.join(', ')})`);
+  lines.push(`        public virtual IAsyncEnumerable<${itemType}> ${methodStem}AutoPagingAsync(${params.join(', ')})`);
   lines.push('        {');
 
   const pathExpr = buildPathExpr(op);
@@ -589,10 +833,15 @@ function resolveCsMethodName(op: Operation, mountName: string, ctx: EmitterConte
   return resolveMethodName(op, { name: mountName, operations: [op] }, ctx);
 }
 
+export function resolveCsMethodStem(op: Operation, mountName: string, ctx: EmitterContext): string {
+  return resolveMethodStem(op, { name: mountName, operations: [op] }, ctx);
+}
+
 export function optionsClassName(mountName: string, method: string): string {
+  const methodStem = method.endsWith('Async') ? method.slice(0, -5) : method;
   const prefix = className(mountName);
-  if (method.startsWith(prefix)) return `${method}Options`;
-  return `${prefix}${method}Options`;
+  if (methodStem.startsWith(prefix)) return `${methodStem}Options`;
+  return `${prefix}${methodStem}Options`;
 }
 
 function buildPathExpr(op: Operation): string {
@@ -602,7 +851,7 @@ function buildPathExpr(op: Operation): string {
   // Build C# string interpolation
   let interpolated = op.path;
   for (const p of sortPathParamsByTemplateOrder(op)) {
-    interpolated = interpolated.replace(`{${p.name}}`, `{${localName(p.name)}}`);
+    interpolated = interpolated.replace(`{${p.name}}`, `{Uri.EscapeDataString(${localName(p.name)})}`);
   }
   return `$"${interpolated}"`;
 }
@@ -613,10 +862,82 @@ function resolveListItemType(itemType: import('@workos/oagen').TypeRef, ctx: Emi
     if (model && isListWrapperModel(model)) {
       const dataField = model.fields.find((f) => f.name === 'data');
       if (dataField && dataField.type.kind === 'array' && dataField.type.items.kind === 'model') {
-        return className(dataField.type.items.name);
+        return modelClassName(resolveModelName(dataField.type.items.name));
       }
     }
-    return className(itemType.name);
+    return modelClassName(resolveModelName(itemType.name));
   }
   return mapTypeRef(itemType);
 }
+
+function generateCompatibilityMethod(
+  mountName: string,
+  asyncMethod: string,
+  methodStem: string,
+  op: Operation,
+  plan: OperationPlan,
+  ctx: EmitterContext,
+  resolvedOp?: ResolvedOperation,
+): string {
+  const lines: string[] = [];
+  const hidden = buildHiddenParams(resolvedOp);
+  const groupedParams = collectGroupedParamNames(op);
+  const hasGroups = (op.parameterGroups?.length ?? 0) > 0;
+  const hasVisibleQueryParams =
+    op.queryParams.filter((qp) => !hidden.has(qp.name) && !groupedParams.has(qp.name)).length > 0;
+
+  let hasVisibleBodyFields = false;
+  if (plan.hasBody && op.requestBody?.kind === 'model') {
+    const bodyModel = ctx.spec.models.find((m) => op.requestBody?.kind === 'model' && m.name === op.requestBody.name);
+    if (bodyModel) hasVisibleBodyFields = bodyModel.fields.some((f) => !hidden.has(f.name));
+  } else if (plan.hasBody && op.requestBody) {
+    hasVisibleBodyFields = true;
+  }
+
+  const hasParams = hasVisibleBodyFields || hasVisibleQueryParams || hasGroups;
+  const optionsClass = hasParams ? optionsClassName(mountName, methodStem) : null;
+
+  let returnType = 'Task';
+  if (plan.isPaginated && op.pagination) {
+    const itemType = resolveListItemType(op.pagination.itemType, ctx);
+    returnType = `Task<WorkOSList<${itemType}>>`;
+  } else if (plan.responseModelName) {
+    const respType = modelClassName(resolveModelName(plan.responseModelName));
+    returnType = !plan.isPaginated && op.response?.kind === 'array' ? `Task<List<${respType}>>` : `Task<${respType}>`;
+  }
+
+  const params: string[] = [];
+  const args: string[] = [];
+  for (const p of sortPathParamsByTemplateOrder(op)) {
+    const name = localName(p.name);
+    params.push(`string ${name}`);
+    args.push(name);
+  }
+
+  const hasBearerOverride = op.security?.some((s: any) => s.schemeName !== 'bearerAuth') ?? false;
+  if (hasBearerOverride) {
+    const bearerParamName = op.security!.find((s: any) => s.schemeName !== 'bearerAuth')!.schemeName;
+    const bearerLocal = localName(bearerParamName);
+    params.push(`string ${bearerLocal}`);
+    args.push(bearerLocal);
+  }
+
+  if (optionsClass) {
+    const isRequired = hasVisibleBodyFields && !plan.isPaginated;
+    params.push(isRequired ? `${optionsClass} options` : `${optionsClass}? options = null`);
+    args.push('options');
+  }
+
+  params.push('RequestOptions? requestOptions = null');
+  params.push('CancellationToken cancellationToken = default');
+  args.push('requestOptions');
+  args.push('cancellationToken');
+
+  lines.push(`        /// <summary>Compatibility wrapper for <see cref="${asyncMethod}"/>.</summary>`);
+  lines.push(`        public virtual ${returnType} ${methodStem}(${params.join(', ')})`);
+  lines.push('        {');
+  lines.push(`            return this.${asyncMethod}(${args.join(', ')});`);
+  lines.push('        }');
+
+  return lines.join('\n');
+}