@workos/oagen-emitters 0.3.0 → 0.5.0

package/src/node/resources.ts

@@ -40,6 +40,7 @@ import {
   getOpInferFromClient,
 } from '../shared/resolved-ops.js';
 import { generateWrapperMethods, collectWrapperResponseModels } from './wrappers.js';
+import { resolveWrapperParams } from '../shared/wrapper-utils.js';
 
 /**
  * Check whether the baseline (hand-written) class has a constructor compatible
@@ -192,6 +193,62 @@ function deduplicateMethodNames(
   }
 }
 
+/**
+ * Emit one interface file per paginated list operation that has extension
+ * query params.  Placing the options interface under `interfaces/` lets the
+ * per-service barrel pick it up via `export * from './interfaces'`, which
+ * is what the root `src/index.ts` re-exports.  When the interface was
+ * declared inline in the resource file, it was unreachable from the barrel
+ * and callers couldn't import the type by name from the package root.
+ */
+function generatePaginatedOptionsInterfaces(
+  service: Service,
+  ctx: EmitterContext,
+  specEnumNames: Set<string>,
+): GeneratedFile[] {
+  const files: GeneratedFile[] = [];
+  const resolvedName = resolveResourceClassName(service, ctx);
+  const serviceDir = resolveServiceDir(resolvedName);
+
+  const plans = service.operations.map((op) => ({
+    op,
+    plan: planOperation(op),
+    method: resolveMethodName(op, service, ctx),
+  }));
+
+  for (const { op, plan, method } of plans) {
+    if (!plan.isPaginated) continue;
+    const extraParams = op.queryParams.filter((p) => !PAGINATION_PARAM_NAMES.has(p.name));
+    if (extraParams.length === 0) continue;
+
+    const optionsName = paginatedOptionsName(method, resolvedName);
+    const filePath = `src/${serviceDir}/interfaces/${fileName(optionsName)}.interface.ts`;
+
+    const lines: string[] = [];
+    lines.push("import type { PaginationOptions } from '../../common/interfaces/pagination-options.interface';");
+    lines.push('');
+    lines.push(`export interface ${optionsName} extends PaginationOptions {`);
+    for (const param of extraParams) {
+      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('}');
+
+    files.push({
+      path: filePath,
+      content: lines.join('\n'),
+    });
+  }
+
+  return files;
+}
+
 export function generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
   if (services.length === 0) return [];
   const files: GeneratedFile[] = [];
@@ -202,19 +259,19 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
   const mergedServices: Service[] =
     mountGroups.size > 0 ? [...mountGroups].map(([name, group]) => ({ name, operations: group.operations })) : services;
 
+  const topLevelEnumNames = new Set(ctx.spec.enums.map((e) => e.name));
+
   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.
-      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';
+      if (!hasMethodsAbsentFromBaseline(service, ctx)) {
+        continue; // Fully covered, no new methods -- skip entirely
       }
+      // Partially covered -- has new methods that need to be added.
+      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);
       continue;
     }
@@ -233,10 +290,25 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
       file.headerPlacement = 'skip';
       files.push(file);
     } else {
-      files.push(generateResourceClass(service, ctx));
+      // Purely oagen-managed: no baseline class exists, so the file is owned
+      // end-to-end by the emitter.  Remove skipIfExists so regeneration always
+      // overwrites — emitter improvements (serializer dispatch, JSDoc, etc.)
+      // must propagate without manual intervention.
+      const file = generateResourceClass(service, ctx);
+      delete file.skipIfExists;
+      files.push(file);
     }
   }
 
+  // Emit paginated list options interfaces AFTER the resource classes so
+  // tests and manifest ordering that index `files[0]` as the class stay
+  // stable.  Placing them under `interfaces/` lets the per-service barrel
+  // pick them up automatically.
+  for (const service of mergedServices) {
+    if (isServiceCoveredByExisting(service, ctx) && !hasMethodsAbsentFromBaseline(service, ctx)) continue;
+    files.push(...generatePaginatedOptionsInterfaces(service, ctx, topLevelEnumNames));
+  }
+
   return files;
 }
 
@@ -311,11 +383,19 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
   const paramEnums = new Set<string>();
   const paramModels = new Set<string>();
   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`).
+    // Always collect param type refs for enums — inline options interfaces
+    // are generated for all methods (including baseline ones), so their
+    // type dependencies must always be imported.
+    const queryParams = plan.isPaginated
+      ? op.queryParams.filter((p) => !PAGINATION_PARAM_NAMES.has(p.name))
+      : op.queryParams;
+    for (const param of [...queryParams, ...op.pathParams]) {
+      collectParamTypeRefs(param.type, paramEnums, paramModels);
+    }
+
+    // Skip response/request model 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.
     if (baselineMethodSet.has(method)) continue;
 
     if (plan.isPaginated && op.pagination?.itemType.kind === 'model') {
@@ -354,19 +434,13 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
         }
       }
     }
-    // Collect types referenced in query and path parameters.
-    // For paginated operations, skip standard pagination params (limit, before, after, order)
-    // since they're handled by PaginationOptions and don't need explicit imports.
-    const queryParams = plan.isPaginated
-      ? op.queryParams.filter((p) => !PAGINATION_PARAM_NAMES.has(p.name))
-      : op.queryParams;
-    for (const param of [...queryParams, ...op.pathParams]) {
-      collectParamTypeRefs(param.type, paramEnums, paramModels);
-    }
   }
 
   // Collect response models from union split wrappers so their types and
   // deserializers are imported alongside the primary operation models.
+  // Also collect models referenced in wrapper param signatures (e.g.,
+  // `redirect_uris: RedirectUriInput[]`) — otherwise the wrapper emits a
+  // reference to a type it never imported.
   const resolvedLookup = buildResolvedLookup(ctx);
   for (const { op, method } of plans) {
     if (baselineMethodSet.has(method)) continue;
@@ -375,6 +449,11 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
       for (const name of collectWrapperResponseModels(resolved)) {
         responseModels.add(name);
       }
+      for (const wrapper of resolved.wrappers ?? []) {
+        for (const { field } of resolveWrapperParams(wrapper, ctx)) {
+          if (field) collectParamTypeRefs(field.type, paramEnums, paramModels);
+        }
+      }
     }
   }
 
@@ -386,8 +465,19 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
   lines.push("import type { WorkOS } from '../workos';");
   if (hasPaginated) {
     lines.push("import type { PaginationOptions } from '../common/interfaces/pagination-options.interface';");
-    lines.push("import type { AutoPaginatable } from '../common/utils/pagination';");
-    lines.push("import { createPaginatedList } from '../common/utils/fetch-and-deserialize';");
+    lines.push("import { AutoPaginatable } from '../common/utils/pagination';");
+    lines.push("import { fetchAndDeserialize } from '../common/utils/fetch-and-deserialize';");
+  }
+
+  // Paginated list options live in their own interface files so they're
+  // picked up by the per-service barrel (and flow through to the root
+  // package barrel).  Import them here rather than declaring inline.
+  for (const { op, plan, method } of plans) {
+    if (!plan.isPaginated) continue;
+    const extraParams = op.queryParams.filter((p) => !PAGINATION_PARAM_NAMES.has(p.name));
+    if (extraParams.length === 0) continue;
+    const optionsName = paginatedOptionsName(method, resolvedName);
+    lines.push(`import type { ${optionsName} } from './interfaces/${fileName(optionsName)}.interface';`);
   }
 
   // Check if any operation needs PostOptions (idempotent POST or custom encoding)
@@ -493,32 +583,43 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
 
   lines.push('');
 
-  // Options interfaces for operations with query params.
-  // Paginated operations extend PaginationOptions; non-paginated operations get standalone interfaces.
+  // Per-operation helpers (wire-format option serializers etc.) emitted
+  // alongside the resource class.  The options interfaces themselves live
+  // in separate files under `interfaces/` so the per-service barrel can
+  // re-export them; see the earlier import block at the top of the file.
   for (const { op, plan, method } of plans) {
     if (plan.isPaginated) {
       const extraParams = op.queryParams.filter((p) => !PAGINATION_PARAM_NAMES.has(p.name));
       if (extraParams.length > 0) {
         const optionsName = paginatedOptionsName(method, resolvedName);
-        // Always generate the options interface locally in the resource file.
-        // Previously we skipped generation when a baseline interface with a matching
-        // name existed, but the baseline interface may live in a different module
-        // (e.g., `user-management/` vs `user-management-users/`) and would not be
-        // available without an import.  Generating locally is safe and avoids
-        // cross-module import resolution issues.
-        lines.push(`export interface ${optionsName} extends PaginationOptions {`);
-        for (const param of extraParams) {
-          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));
+
+        // When any extension param has a camelCase domain name that differs
+        // from its snake_case wire name, emit a serializer that translates
+        // the user-facing options into the wire query shape.  Without this,
+        // the query string uses camelCase keys (e.g. `organizationId=...`)
+        // that the API silently ignores — the filter becomes a no-op.
+        const needsWireSerializer = extraParams.some((p) => fieldName(p.name) !== wireFieldName(p.name));
+        if (needsWireSerializer) {
+          const serializerName = `serialize${optionsName}`;
+          lines.push(`const ${serializerName} = (options: ${optionsName}): PaginationOptions => {`);
+          // Pagination fields pass through unchanged (limit/before/after/order
+          // share spelling in both cases).  Spread first so that wire-named
+          // extension fields land on top and the camelCase keys don't also
+          // leak into the query string.
+          lines.push('  const wire: Record<string, unknown> = {');
+          for (const p of PAGINATION_PARAM_NAMES) {
+            lines.push(`    ${p}: options.${p},`);
           }
-          lines.push(`  ${fieldName(param.name)}${opt}: ${mapParamType(param.type, specEnumNames)};`);
+          lines.push('  };');
+          for (const param of extraParams) {
+            const camel = fieldName(param.name);
+            const snake = wireFieldName(param.name);
+            lines.push(`  if (options.${camel} !== undefined) wire.${snake} = options.${camel};`);
+          }
+          lines.push('  return wire as PaginationOptions;');
+          lines.push('};');
+          lines.push('');
         }
-        lines.push('}');
-        lines.push('');
       }
     } 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
@@ -628,12 +729,16 @@ function renderMethod(
     if (op.description) docParts.push(op.description);
     for (const param of op.pathParams) {
       const paramName = fieldName(param.name);
-      if (validParamNames && !validParamNames.has(paramName)) continue;
+      // When the overlay folds a path param into the options object,
+      // document it as @param options.paramName instead of top-level.
+      const folded = validParamNames && !validParamNames.has(paramName) && validParamNames.has('options');
+      if (validParamNames && !validParamNames.has(paramName) && !folded) continue;
+      const docName = folded ? `options.${paramName}` : paramName;
       const deprecatedPrefix = param.deprecated ? '(deprecated) ' : '';
       if (param.description) {
-        docParts.push(`@param ${paramName} - ${deprecatedPrefix}${param.description}`);
+        docParts.push(`@param ${docName} - ${deprecatedPrefix}${param.description}`);
       } else if (param.deprecated) {
-        docParts.push(`@param ${paramName} - (deprecated)`);
+        docParts.push(`@param ${docName} - (deprecated)`);
       }
       if (param.default !== undefined) docParts.push(`@default ${JSON.stringify(param.default)}`);
       if (param.example !== undefined) docParts.push(`@example ${JSON.stringify(param.example)}`);
@@ -660,36 +765,122 @@ function renderMethod(
     }
     // 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
+    // Document payload/body parameter when there is a request body.
+    // Detect the actual param name from the overlay — the hand-written SDK may
+    // fold the body into an 'options' param instead of the generated 'payload'.
+    let bodyDocParamName: string | null = null;
     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.';
+      let bodyParamName = 'payload';
+      let overlayHadUnusableName = false;
+      if (validParamNames && !validParamNames.has('payload') && overlayMethod) {
+        const pathNames = new Set(op.pathParams.map((p) => fieldName(p.name)));
+        const candidates = overlayMethod.params.filter((p) => !pathNames.has(p.name) && p.name !== 'requestOptions');
+        // Filter out destructuring artifacts (e.g., __0) from extracted param names
+        const isUsableName = (name: string) => !/^__\d+$/.test(name);
+        if (candidates.length === 1 && isUsableName(candidates[0].name)) {
+          bodyParamName = candidates[0].name;
+        } else if (candidates.length === 1 && !isUsableName(candidates[0].name)) {
+          overlayHadUnusableName = true;
+        } else if (candidates.length > 1) {
+          // Multiple non-path params — match by type against the request body model
+          const bodyInfo = extractRequestBodyType(op, ctx);
+          if (bodyInfo?.kind === 'model') {
+            const bodyTypeName = resolveInterfaceName(bodyInfo.name, ctx);
+            const typeMatch = candidates.find((p) => p.type === bodyTypeName && isUsableName(p.name));
+            if (typeMatch) {
+              bodyParamName = typeMatch.name;
+            } else {
+              // Type names diverge (overlay vs spec). Fall back to matching
+              // overlay param names against body model field names so each
+              // extracted param gets documented individually.
+              const bodyModel = ctx.spec.models.find((m) => m.name === bodyInfo.name);
+              if (bodyModel) {
+                const fieldMap = new Map(bodyModel.fields.map((f) => [fieldName(f.name), f]));
+                for (const candidate of candidates) {
+                  const matchingField = fieldMap.get(candidate.name);
+                  if (matchingField?.description) {
+                    docParts.push(`@param ${candidate.name} - ${matchingField.description}`);
+                    if (matchingField.example !== undefined)
+                      docParts.push(`@example ${JSON.stringify(matchingField.example)}`);
+                  }
+                }
+                bodyDocParamName = '__multi__'; // prevent duplicate body doc below
+              }
+            }
+          }
+        }
+      }
+
+      // When the overlay had an unusable param name (e.g., destructured __0),
+      // force documentation under 'payload' so the body isn't silently dropped.
+      if (
+        bodyDocParamName !== '__multi__' &&
+        (overlayHadUnusableName || !validParamNames || validParamNames.has(bodyParamName))
+      ) {
+        bodyDocParamName = bodyParamName;
+        const bodyInfo = extractRequestBodyType(op, ctx);
+        if (bodyInfo?.kind === 'model') {
+          const bodyModel = ctx.spec.models.find((m) => m.name === bodyInfo.name);
+          let bodyDesc: string;
+          if (bodyModel?.description) {
+            bodyDesc = `@param ${bodyParamName} - ${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));
+            bodyDesc =
+              requiredFieldNames.length > 0
+                ? `@param ${bodyParamName} - Object containing ${requiredFieldNames.join(', ')}.`
+                : `@param ${bodyParamName} - The request body.`;
+          } else {
+            bodyDesc = `@param ${bodyParamName} - The request body.`;
+          }
+          docParts.push(bodyDesc);
+
+          // When the body is folded into an options-style param (not 'payload'),
+          // expand individual fields so IDEs surface per-field documentation.
+          if (bodyParamName !== 'payload' && bodyModel) {
+            for (const bField of bodyModel.fields) {
+              const fName = `${bodyParamName}.${fieldName(bField.name)}`;
+              const deprecatedPrefix = bField.deprecated ? '(deprecated) ' : '';
+              if (bField.description) {
+                docParts.push(`@param ${fName} - ${deprecatedPrefix}${bField.description}`);
+              } else if (bField.deprecated) {
+                docParts.push(`@param ${fName} - (deprecated)`);
+              }
+              if (bField.example !== undefined) docParts.push(`@example ${JSON.stringify(bField.example)}`);
+            }
+          }
         } else {
-          payloadDesc = '@param payload - The request body.';
+          docParts.push(`@param ${bodyParamName} - The request body.`);
         }
-        docParts.push(payloadDesc);
-      } else {
-        docParts.push('@param payload - The request body.');
       }
     }
     // Document options parameter for paginated operations
+    const hasOptionsSummary = () => docParts.some((p) => /^@param options(\s|$)/.test(p));
     if (plan.isPaginated) {
       docParts.push('@param options - Pagination and filter options.');
-    } else if (op.queryParams.filter((q) => !hiddenParams.has(q.name)).length > 0) {
+    } else if (!hasOptionsSummary() && op.queryParams.filter((q) => !hiddenParams.has(q.name)).length > 0) {
       docParts.push('@param options - Additional query options.');
     }
+    // Ensure an @param options summary exists when there are @param options.xxx
+    // entries (from folded path/body params) or when the overlay exposes an
+    // options param that wasn't otherwise documented.
+    if (validParamNames?.has('options') && !hasOptionsSummary()) {
+      const hasOptionsDotEntries = docParts.some((p) => p.startsWith('@param options.'));
+      if (hasOptionsDotEntries || overlayMethod) {
+        docParts.push('@param options - The request options.');
+      }
+    }
+    // Reorder: ensure @param options summary comes before any @param options.xxx entries
+    {
+      const summaryIdx = docParts.findIndex((p) => /^@param options(\s|$)/.test(p));
+      const firstDotIdx = docParts.findIndex((p) => p.startsWith('@param options.'));
+      if (summaryIdx > firstDotIdx && firstDotIdx >= 0) {
+        const [summary] = docParts.splice(summaryIdx, 1);
+        docParts.splice(firstDotIdx, 0, summary);
+      }
+    }
     // @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
@@ -708,7 +899,8 @@ function renderMethod(
       const itemTypeName = resolveInterfaceName(itemRawName, ctx);
       docParts.push(`@returns {Promise<AutoPaginatable<${itemTypeName}>>}`);
     } else if (responseModel) {
-      docParts.push(`@returns {Promise<${responseModel}>}`);
+      const returnTypeDoc = plan.isArrayResponse ? `${responseModel}[]` : responseModel;
+      docParts.push(`@returns {Promise<${returnTypeDoc}>}`);
     } else {
       docParts.push('@returns {Promise<void>}');
     }
@@ -811,14 +1003,35 @@ function renderPaginatedMethod(
 ): void {
   const extraParams = op.queryParams.filter((p) => !PAGINATION_PARAM_NAMES.has(p.name));
   const optionsType = extraParams.length > 0 ? paginatedOptionsName(method, resolvedServiceName) : 'PaginationOptions';
+  // When any extension param has a camelCase/snake_case divergence, the
+  // resource file emits a `serialize<OptionsName>` helper — pass it to
+  // createPaginatedList so the wire query uses snake_case keys.
+  const needsWireSerializer = extraParams.some((p) => fieldName(p.name) !== wireFieldName(p.name));
+  const serializerArg = needsWireSerializer ? `, serialize${optionsType}` : '';
 
   const pathParams = buildPathParams(op, specEnumNames);
   const allParams = pathParams ? `${pathParams}, options?: ${optionsType}` : `options?: ${optionsType}`;
 
+  const wireType = wireInterfaceName(itemType);
+  const serializeCall = serializerArg ? `options ? serialize${optionsType}(options) : undefined` : 'options';
+
   lines.push(`  async ${method}(${allParams}): Promise<AutoPaginatable<${itemType}, ${optionsType}>> {`);
-  lines.push(
-    `    return createPaginatedList<${wireInterfaceName(itemType)}, ${itemType}, ${optionsType}>(this.workos, ${pathStr}, deserialize${itemType}, options);`,
-  );
+  lines.push(`    return new AutoPaginatable(`);
+  lines.push(`      await fetchAndDeserialize<${wireType}, ${itemType}>(`);
+  lines.push(`        this.workos,`);
+  lines.push(`        ${pathStr},`);
+  lines.push(`        deserialize${itemType},`);
+  lines.push(`        ${serializeCall},`);
+  lines.push(`      ),`);
+  lines.push(`      (params) =>`);
+  lines.push(`        fetchAndDeserialize<${wireType}, ${itemType}>(`);
+  lines.push(`          this.workos,`);
+  lines.push(`          ${pathStr},`);
+  lines.push(`          deserialize${itemType},`);
+  lines.push(`          params,`);
+  lines.push(`        ),`);
+  lines.push(`      options,`);
+  lines.push(`    );`);
   lines.push('  }');
 }
 
@@ -926,16 +1139,22 @@ function renderBodyMethod(
   const encodingOption = encoding && encoding !== 'json' ? `, encoding: '${encoding}' as const` : '';
   const hasCustomEncoding = encodingOption !== '';
 
-  lines.push(`  async ${method}(${paramsStr}): Promise<${responseModel}> {`);
+  const returnType = plan.isArrayResponse ? `${responseModel}[]` : responseModel;
+  const wireType = plan.isArrayResponse ? `${wireInterfaceName(responseModel)}[]` : wireInterfaceName(responseModel);
+  const returnExpr = plan.isArrayResponse
+    ? `data.map(deserialize${responseModel})`
+    : `deserialize${responseModel}(data)`;
+
+  lines.push(`  async ${method}(${paramsStr}): Promise<${returnType}> {`);
   if (plan.isIdempotentPost) {
     if (hasCustomEncoding) {
-      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(`);
+      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(`);
       lines.push(`      ${pathStr},`);
       lines.push(`      ${bodyExpr},`);
       lines.push(`      { ...requestOptions${encodingOption} },`);
       lines.push('    );');
     } else {
-      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(`);
+      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(`);
       lines.push(`      ${pathStr},`);
       lines.push(`      ${bodyExpr},`);
       lines.push('      requestOptions,');
@@ -943,19 +1162,19 @@ function renderBodyMethod(
     }
   } else {
     if (hasCustomEncoding) {
-      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(`);
+      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(`);
       lines.push(`      ${pathStr},`);
       lines.push(`      ${bodyExpr},`);
       lines.push(`      { ${encodingOption.slice(2)} },`);
       lines.push('    );');
     } else {
-      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(`);
+      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(`);
       lines.push(`      ${pathStr},`);
       lines.push(`      ${bodyExpr},`);
       lines.push('    );');
     }
   }
-  lines.push(`    return deserialize${responseModel}(data);`);
+  lines.push(`    return ${returnExpr};`);
   lines.push('  }');
 }
 
@@ -989,7 +1208,13 @@ function renderGetMethod(
       : `options?: ${optionsType}`
     : params;
 
-  lines.push(`  async ${method}(${allParams}): Promise<${responseModel}> {`);
+  const returnType = plan.isArrayResponse ? `${responseModel}[]` : responseModel;
+  const wireType = plan.isArrayResponse ? `${wireInterfaceName(responseModel)}[]` : wireInterfaceName(responseModel);
+  const returnExpr = plan.isArrayResponse
+    ? `data.map(deserialize${responseModel})`
+    : `deserialize${responseModel}(data)`;
+
+  lines.push(`  async ${method}(${allParams}): Promise<${returnType}> {`);
   if (hasQuery) {
     if (hasInjected) {
       // Build the query object with visible params, defaults, and inferred fields
@@ -1026,30 +1251,22 @@ function renderGetMethod(
         queryParts.push(`${field}: ${clientFieldExpression(field)}`);
       }
 
-      lines.push(
-        `    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(${pathStr}, {`,
-      );
+      lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(${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(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(${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(
-      `    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(${pathStr}, {});`,
-    );
+    lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(${pathStr}, {});`);
   } else {
-    lines.push(
-      `    const { data } = await this.workos.${op.httpMethod}<${wireInterfaceName(responseModel)}>(${pathStr});`,
-    );
+    lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(${pathStr});`);
   }
-  lines.push(`    return deserialize${responseModel}(data);`);
+  lines.push(`    return ${returnExpr};`);
   lines.push('  }');
 }
 
@@ -1263,9 +1480,16 @@ function renderUnionBodySerializer(
   const cases: string[] = [];
   for (const [value, modelName] of Object.entries(disc.mapping)) {
     const resolved = resolveInterfaceName(modelName, ctx);
-    cases.push(`case '${value}': return serialize${resolved}(payload as any)`);
+    // Switch on a typed discriminator narrows `payload` to the variant, so the
+    // serializer call type-checks without any casts.
+    cases.push(`case '${value}': return serialize${resolved}(payload)`);
   }
-  return `(() => { switch ((payload as any).${prop}) { ${cases.join('; ')}; default: return payload } })()`;
+  // Assign `payload` to `never` in the default branch to get a compile-time
+  // exhaustiveness check — if a new variant is added to the union but not to
+  // the switch, the build fails here.  At runtime, we still throw so an
+  // unknown discriminator slipping through via `as any` fails loudly rather
+  // than silently forwarding camelCase to the API.
+  return `(() => { switch (payload.${prop}) { ${cases.join('; ')}; default: { const _unknown: never = payload; throw new Error(\`Unknown ${prop}: \${(_unknown as { ${prop}?: unknown }).${prop}}\`) } } })()`;
 }
 
 /**