@workos/oagen-emitters 0.6.7 → 0.6.8

package/dist/plugin.mjs

@@ -1,2 +1,2 @@
-import { t as workosEmittersPlugin } from "./plugin-Bk0xWTQC.mjs";
+import { t as workosEmittersPlugin } from "./plugin-Cmg_LFtm.mjs";
 export { workosEmittersPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos/oagen-emitters",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "description": "WorkOS' oagen emitters",
   "license": "MIT",
   "author": "WorkOS",

package/src/ruby/index.ts

@@ -30,7 +30,8 @@ export const rubyEmitter: Emitter = {
   language: 'ruby',
 
   generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateModels(models, ctx));
+    const modelFiles = generateModels(models, ctx);
+    return ensureTrailingNewlines(modelFiles);
   },
 
   generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
@@ -54,7 +55,8 @@ export const rubyEmitter: Emitter = {
   },
 
   generateTypeSignatures(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateRbiFiles(spec, ctx));
+    const rbiFiles = generateRbiFiles(spec, ctx);
+    return ensureTrailingNewlines(rbiFiles);
   },
 
   generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {

package/src/ruby/naming.ts

@@ -117,6 +117,29 @@ export function moduleName(name: string): string {
   return toSnakeCase(name);
 }
 
+/**
+ * PascalCase class name for a parameter-group variant. Mirrors the Python
+ * convention: group "password" + variant "plaintext" → `PasswordPlaintext`.
+ * Used as the Ruby constant under the WorkOS module.
+ */
+export function groupVariantClassName(groupName: string, variantName: string): string {
+  return className(`${groupName}_${variantName}`);
+}
+
+/** snake_case Zeitwerk-compatible filename for a parameter-group variant. */
+export function groupVariantFileName(groupName: string, variantName: string): string {
+  return fileName(`${groupName}_${variantName}`);
+}
+
+/**
+ * Fully-qualified Ruby constant for a parameter-group variant scoped under
+ * its owning resource module — e.g. "WorkOS::UserManagement::PasswordPlaintext".
+ * Mirrors Python's `workos.user_management.PasswordPlaintext` namespacing.
+ */
+export function scopedGroupVariantClassName(mountTarget: string, groupName: string, variantName: string): string {
+  return `WorkOS::${className(mountTarget)}::${groupVariantClassName(groupName, variantName)}`;
+}
+
 /** snake_case property name for service accessors on the client. */
 export function servicePropertyName(name: string): string {
   return toSnakeCase(name);

package/src/ruby/parameter-groups.ts

@@ -0,0 +1,221 @@
+import type { EmitterContext, TypeRef, Model } from '@workos/oagen';
+import { className, fieldName, groupVariantClassName } from './naming.js';
+import { mapTypeRefForYard } from './type-map.js';
+import { collectBodyFieldTypes, groupByMount } from '../shared/resolved-ops.js';
+
+/**
+ * Sorbet type string for a TypeRef. Mirrors `mapSorbetType` in rbi.ts but
+ * lives here so the parameter-groups module is self-contained.
+ */
+function mapSorbetType(ref: TypeRef): string {
+  switch (ref.kind) {
+    case 'primitive':
+      switch (ref.type) {
+        case 'string':
+          return 'String';
+        case 'integer':
+          return 'Integer';
+        case 'number':
+          return 'Float';
+        case 'boolean':
+          return 'T::Boolean';
+        case 'unknown':
+          return 'T.untyped';
+      }
+      break;
+    case 'array':
+      return `T::Array[${mapSorbetType(ref.items)}]`;
+    case 'model':
+      return `WorkOS::${className(ref.name)}`;
+    case 'enum':
+      return 'String';
+    case 'nullable':
+      return `T.nilable(${mapSorbetType(ref.inner)})`;
+    case 'literal':
+      if (typeof ref.value === 'string') return 'String';
+      if (ref.value === null) return 'NilClass';
+      if (typeof ref.value === 'number') return Number.isInteger(ref.value) ? 'Integer' : 'Float';
+      return 'T::Boolean';
+    case 'union': {
+      const variants = ref.variants.map((v) => mapSorbetType(v));
+      const unique = [...new Set(variants)];
+      if (unique.length === 1) return unique[0];
+      return `T.any(${unique.join(', ')})`;
+    }
+    case 'map':
+      return `T::Hash[String, ${mapSorbetType(ref.valueType)}]`;
+  }
+  return 'T.untyped';
+}
+
+export interface CollectedVariant {
+  className: string;
+  groupName: string;
+  variantName: string;
+  /** PascalCase mount target this variant is scoped under (e.g. "UserManagement"). */
+  mountTarget: string;
+  parameters: { name: string; type: TypeRef }[];
+}
+
+/**
+ * Build a stable groupName -> mountTarget map. Each parameter group is owned
+ * by exactly one resource module — Ruby variant classes are inlined into
+ * `WorkOS::<MountTarget>::<Variant>` (matching Python's per-resource layout),
+ * so a dispatcher in another resource that references the same group still
+ * resolves to a single canonical class.
+ *
+ * Mount targets are visited in alphabetical order so first-wins is
+ * deterministic across runs. In the current spec no group is shared across
+ * mount targets; if one ever is, the alphabetically-first owner gets the
+ * class and other dispatchers reference it by full path.
+ */
+export function buildGroupOwnerMap(ctx: EmitterContext): Map<string, string> {
+  const owner = new Map<string, string>();
+  const groups = groupByMount(ctx);
+  const sortedTargets = [...groups.keys()].sort();
+  for (const target of sortedTargets) {
+    const g = groups.get(target);
+    if (!g) continue;
+    for (const op of g.operations) {
+      for (const grp of op.parameterGroups ?? []) {
+        if (!owner.has(grp.name)) owner.set(grp.name, target);
+      }
+    }
+  }
+  return owner;
+}
+
+/**
+ * Collect all variant classes a given mount target owns. Variants are
+ * inlined into the resource file (and its RBI counterpart) — Zeitwerk's
+ * collapse convention means subdirectories under `lib/workos/<service>/`
+ * don't add a namespace level, so files there can't define
+ * `WorkOS::<Service>::<Variant>`. Inline definitions sidestep that.
+ *
+ * Variant parameter types are taken from the IR's leaf type. When the IR's
+ * leaf is a bare primitive but the request body model has a richer type
+ * (array/enum/model/map), we fall back to the body type to recover fidelity
+ * the IR drops. Body nullability is stripped — when a parameter group is
+ * optional, the body field for the group becomes nullable, but within a
+ * variant the leaf is always required (selecting the variant means passing it).
+ */
+export function collectVariantsForMountTarget(
+  ctx: EmitterContext,
+  models: Model[],
+  mountTarget: string,
+): CollectedVariant[] {
+  const owner = buildGroupOwnerMap(ctx);
+  const seen = new Set<string>();
+  const out: CollectedVariant[] = [];
+  const groups = groupByMount(ctx);
+  const g = groups.get(mountTarget);
+  if (!g) return out;
+  for (const op of g.operations) {
+    const bodyFieldTypes = collectBodyFieldTypes(op, models);
+    for (const group of op.parameterGroups ?? []) {
+      if (owner.get(group.name) !== mountTarget) continue;
+      for (const variant of group.variants) {
+        const cls = groupVariantClassName(group.name, variant.name);
+        if (seen.has(cls)) continue;
+        seen.add(cls);
+        out.push({
+          className: cls,
+          groupName: group.name,
+          variantName: variant.name,
+          mountTarget,
+          parameters: variant.parameters.map((p) => ({
+            name: p.name,
+            type: pickVariantParamType(p.type, bodyFieldTypes.get(p.name)),
+          })),
+        });
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Pick the type for a variant leaf parameter.
+ *
+ * Prefer the IR's leaf type. Use the body model's type only when the IR is a
+ * bare primitive but the body has a structured type — that's the original
+ * fidelity-recovery case the body fallback was added for. Strip any outer
+ * nullable from the body type, since body nullability reflects the parent
+ * group's optionality, not the leaf's required-ness within the variant.
+ *
+ * Exported so the test emitter can recover the same type the variant class
+ * declares — IR primitives for fields like `role_slugs` would otherwise stub
+ * as `"stub"` strings instead of the `["stub"]` arrays the class accepts.
+ */
+export function pickVariantParamType(irType: TypeRef, bodyType: TypeRef | undefined): TypeRef {
+  if (!bodyType) return irType;
+  const unwrappedBody = bodyType.kind === 'nullable' ? bodyType.inner : bodyType;
+  const bodyIsStructured =
+    unwrappedBody.kind === 'array' ||
+    unwrappedBody.kind === 'enum' ||
+    unwrappedBody.kind === 'model' ||
+    unwrappedBody.kind === 'map';
+  if (irType.kind === 'primitive' && bodyIsStructured) return unwrappedBody;
+  return irType;
+}
+
+function readableName(name: string): string {
+  return name.replace(/_/g, ' ');
+}
+
+/**
+ * Render the inline `Data.define` block for a single variant, indented for
+ * inclusion inside a `class <Service>` body. Returns an array of lines with
+ * 4-space indent (the resource file's class members are 4-space indented).
+ */
+export function emitInlineVariantClass(v: CollectedVariant): string[] {
+  const lines: string[] = [];
+  lines.push(`    # Identifies the ${readableName(v.groupName)} (${readableName(v.variantName)} variant).`);
+  lines.push('    #');
+  for (const p of v.parameters) {
+    const yardType = mapTypeRefForYard(p.type);
+    lines.push(`    # @!attribute [r] ${fieldName(p.name)}`);
+    lines.push(`    #   @return [${yardType}]`);
+  }
+  if (v.parameters.length === 0) {
+    lines.push(`    ${v.className} = Data.define`);
+  } else {
+    const fields = v.parameters.map((p) => `:${fieldName(p.name)}`).join(', ');
+    lines.push(`    ${v.className} = Data.define(${fields})`);
+  }
+  return lines;
+}
+
+/**
+ * Render the inline RBI `class` block for a single variant, indented for
+ * inclusion inside a `class <Service>` body in a service .rbi file. Returns
+ * lines with 4-space indent.
+ */
+export function emitInlineVariantRbi(v: CollectedVariant): string[] {
+  const lines: string[] = [];
+  const fqcn = `WorkOS::${v.mountTarget}::${v.className}`;
+  lines.push(`    class ${v.className}`);
+  for (const p of v.parameters) {
+    lines.push(`      sig { returns(${mapSorbetType(p.type)}) }`);
+    lines.push(`      def ${fieldName(p.name)}; end`);
+    lines.push('');
+  }
+  if (v.parameters.length === 0) {
+    lines.push(`      sig { returns(${fqcn}) }`);
+    lines.push(`      def self.new; end`);
+  } else {
+    lines.push('      sig do');
+    lines.push('        params(');
+    for (let i = 0; i < v.parameters.length; i++) {
+      const p = v.parameters[i];
+      const sep = i === v.parameters.length - 1 ? '' : ',';
+      lines.push(`          ${fieldName(p.name)}: ${mapSorbetType(p.type)}${sep}`);
+    }
+    lines.push(`        ).returns(${fqcn})`);
+    lines.push('      end');
+    const kwargs = v.parameters.map((p) => `${fieldName(p.name)}:`).join(', ');
+    lines.push(`      def self.new(${kwargs}); end`);
+  }
+  lines.push('    end');
+  return lines;
+}

package/src/ruby/rbi.ts

@@ -1,6 +1,13 @@
 import type { ApiSpec, EmitterContext, GeneratedFile, TypeRef, Model } from '@workos/oagen';
 import { mapTypeRef as irMapTypeRef } from '@workos/oagen';
-import { className, fieldName, fileName, safeParamName, resolveMethodName } from './naming.js';
+import {
+  className,
+  fieldName,
+  fileName,
+  safeParamName,
+  scopedGroupVariantClassName,
+  resolveMethodName,
+} from './naming.js';
 import {
   buildResolvedLookup,
   groupByMount,
@@ -9,6 +16,7 @@ import {
   collectGroupedParamNames,
 } from '../shared/resolved-ops.js';
 import { isListWrapperModel, isListMetadataModel } from '../shared/model-utils.js';
+import { buildGroupOwnerMap, collectVariantsForMountTarget, emitInlineVariantRbi } from './parameter-groups.js';
 
 /**
  * Map an IR TypeRef to a Sorbet type string for RBI files.
@@ -120,6 +128,7 @@ export function generateRbiFiles(spec: ApiSpec, ctx: EmitterContext): GeneratedF
   for (const m of spec.models as Model[]) {
     if (isListWrapperModel(m)) listWrapperModels.set(m.name, m);
   }
+  const groupOwners = buildGroupOwnerMap(ctx);
 
   for (const [mountTarget, group] of groups) {
     const cls = className(mountTarget);
@@ -129,6 +138,15 @@ export function generateRbiFiles(spec: ApiSpec, ctx: EmitterContext): GeneratedF
     lines.push('module WorkOS');
     lines.push(`  class ${cls}`);
 
+    // Inline parameter-group variant RBI blocks owned by this mount target.
+    // Mirrors the runtime `class ... PasswordPlaintext = Data.define(...) end`
+    // layout in lib/workos/<service>.rb.
+    const variants = collectVariantsForMountTarget(ctx, spec.models as Model[], mountTarget);
+    for (const v of variants) {
+      for (const line of emitInlineVariantRbi(v)) lines.push(line);
+      lines.push('');
+    }
+
     lines.push('    sig { params(client: WorkOS::BaseClient).void }');
     lines.push('    def initialize(client); end');
     lines.push('');
@@ -153,9 +171,26 @@ export function generateRbiFiles(spec: ApiSpec, ctx: EmitterContext): GeneratedF
       const hiddenParams = buildHiddenParams(resolved);
       const groupedParamNames = collectGroupedParamNames(op);
       const queryParams = (op.queryParams ?? []).filter((q) => !groupedParamNames.has(q.name));
-      const bodyFields = getRequestBodyFieldsFlat(op, hiddenParams, modelByName);
+      // Drop body fields that collide with a parameter-group name; the group
+      // dispatcher kwarg handles them. See ruby/resources.ts for the matching
+      // filter on the runtime side.
+      const bodyFields = getRequestBodyFieldsFlat(op, hiddenParams, modelByName).filter(
+        (f) => !groupedParamNames.has(f.name),
+      );
+      const parameterGroups = op.parameterGroups ?? [];
+      const groupSorbetType = (group: (typeof parameterGroups)[number]): string => {
+        const owner = groupOwners.get(group.name);
+        if (!owner) {
+          throw new Error(`No owner mount target found for parameter group '${group.name}'`);
+        }
+        const variants = group.variants.map((v) => scopedGroupVariantClassName(owner, group.name, v.name));
+        if (variants.length === 1) return variants[0];
+        return `T.any(${variants.join(', ')})`;
+      };
 
-      // Build parameter list for sig
+      // Build parameter list for sig. Order mirrors the runtime emitter:
+      // path → required body → required query → required groups → optional
+      // body → optional query → optional groups → request_options.
       const sigParams: string[] = [];
       const seen = new Set<string>();
 
@@ -181,6 +216,13 @@ export function generateRbiFiles(spec: ApiSpec, ctx: EmitterContext): GeneratedF
         seen.add(n);
         sigParams.push(`${n}: ${mapSorbetType(q.type)}`);
       }
+      for (const group of parameterGroups) {
+        if (group.optional) continue;
+        const n = fieldName(group.name);
+        if (seen.has(n)) continue;
+        seen.add(n);
+        sigParams.push(`${n}: ${groupSorbetType(group)}`);
+      }
       for (const f of bodyFields) {
         if (hiddenParams.has(f.name)) continue;
         if (f.required) continue;
@@ -197,6 +239,13 @@ export function generateRbiFiles(spec: ApiSpec, ctx: EmitterContext): GeneratedF
         seen.add(n);
         sigParams.push(`${n}: T.nilable(${unwrapNilable(mapSorbetType(q.type))})`);
       }
+      for (const group of parameterGroups) {
+        if (!group.optional) continue;
+        const n = fieldName(group.name);
+        if (seen.has(n)) continue;
+        seen.add(n);
+        sigParams.push(`${n}: T.nilable(${groupSorbetType(group)})`);
+      }
       sigParams.push('request_options: T::Hash[Symbol, T.untyped]');
 
       // Return type

package/src/ruby/resources.ts

@@ -1,6 +1,14 @@
 import type { Service, EmitterContext, GeneratedFile, Operation, TypeRef, Parameter, Model } from '@workos/oagen';
 import { planOperation } from '@workos/oagen';
-import { className, fieldName, fileName, methodName, safeParamName, resolveMethodName } from './naming.js';
+import {
+  className,
+  fieldName,
+  fileName,
+  methodName,
+  safeParamName,
+  resolveMethodName,
+  scopedGroupVariantClassName,
+} from './naming.js';
 import { mapTypeRefForYard } from './type-map.js';
 import {
   buildResolvedLookup,
@@ -13,6 +21,7 @@ import {
 } from '../shared/resolved-ops.js';
 import { isListWrapperModel } from '../shared/model-utils.js';
 import { generateWrapperMethods, collectWrapperResponseModels } from './wrappers.js';
+import { buildGroupOwnerMap, collectVariantsForMountTarget, emitInlineVariantClass } from './parameter-groups.js';
 
 /**
  * Generate Ruby resource (service) classes from IR services.
@@ -35,6 +44,11 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
     if (isListWrapperModel(m)) listWrapperModels.set(m.name, m);
   }
 
+  // Resolve groupName -> owner mountTarget once per generation pass; every
+  // dispatcher and YARD `@param` reference resolves variant classes through
+  // this map so cross-resource references stay consistent.
+  const groupOwners = buildGroupOwnerMap(ctx);
+
   for (const [mountTarget, group] of groups) {
     const cls = className(mountTarget);
     const file = fileName(mountTarget);
@@ -88,6 +102,7 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
         modelByName,
         listWrapperModels,
         requires,
+        groupOwners,
       });
       methodBodies.push(body);
 
@@ -121,6 +136,18 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
     }
     lines.push('module WorkOS');
     lines.push(`  class ${cls}`);
+
+    // Inline parameter-group variant classes owned by this mount target.
+    // Zeitwerk's `loader.collapse` flattens `lib/workos/<service>/` so files
+    // there can't define `WorkOS::<Service>::*` constants — variants must
+    // live inside the service's own file. Matches Python's per-resource
+    // dataclass layout.
+    const variants = collectVariantsForMountTarget(ctx, ctx.spec.models as Model[], mountTarget);
+    for (const v of variants) {
+      for (const line of emitInlineVariantClass(v)) lines.push(line);
+      lines.push('');
+    }
+
     lines.push('    def initialize(client)');
     lines.push('      @client = client');
     lines.push('    end');
@@ -154,6 +181,7 @@ function emitMethod(args: {
   modelByName: Map<string, Model>;
   listWrapperModels: Map<string, Model>;
   requires: Set<string>;
+  groupOwners: Map<string, string>;
 }): string {
   const {
     op,
@@ -166,9 +194,19 @@ function emitMethod(args: {
     modelByName,
     listWrapperModels,
     requires,
+    groupOwners,
   } = args;
   void enumNames;
 
+  /** Fully-qualified Ruby constant for a variant (e.g. WorkOS::UserManagement::PasswordPlaintext). */
+  const variantClassRef = (group: { name: string }, variantName: string): string => {
+    const owner = groupOwners.get(group.name);
+    if (!owner) {
+      throw new Error(`No owner mount target found for parameter group '${group.name}'`);
+    }
+    return scopedGroupVariantClassName(owner, group.name, variantName);
+  };
+
   const plan = planOperation(op);
   const lines: string[] = [];
 
@@ -177,8 +215,11 @@ function emitMethod(args: {
   const groupedParamNames = collectGroupedParamNames(op);
   const queryParams = (op.queryParams ?? []).filter((q) => !groupedParamNames.has(q.name));
 
-  // Request body params: if body is a model, expand its fields.
-  const bodyFields = getRequestBodyFields(op, hiddenParams, modelByName);
+  // Request body params: if body is a model, expand its fields. Drop any field
+  // whose name is also a parameter-group name — those are dispatched by the
+  // group kwarg below, so emitting them as flat kwargs would shadow the group
+  // and cause `String#[Symbol]` TypeErrors when the dispatcher reads `:type`.
+  const bodyFields = getRequestBodyFields(op, hiddenParams, modelByName).filter((f) => !groupedParamNames.has(f.name));
 
   // Detect path/body name collisions and build a rename map for body fields.
   // When a body field's snake_case name matches a path param, prefix with "body_"
@@ -269,7 +310,16 @@ function emitMethod(args: {
   sigParts.push('request_options: {}');
 
   // YARD docs.
-  const doc = buildYardDoc(op, pathParams, queryParams, bodyFields, hiddenParams, bodyFieldRenames, listWrapperModels);
+  const doc = buildYardDoc(
+    op,
+    pathParams,
+    queryParams,
+    bodyFields,
+    hiddenParams,
+    bodyFieldRenames,
+    listWrapperModels,
+    variantClassRef,
+  );
   for (const line of doc) lines.push(`    ${line}`);
 
   // Signature.
@@ -309,30 +359,41 @@ function emitMethod(args: {
   const groupsGoToQuery = hasGroups && !hasBodyMethod;
   const hasQuery = qEntries.length > 0 || groupsGoToQuery;
   if (hasQuery) {
+    // Skip `.compact` when no entry can be nil — required kwargs are always
+    // passed (Ruby raises ArgumentError otherwise), so the literal has no nil
+    // values to drop. Group dispatch happens after the literal is built and
+    // doesn't contribute potentially-nil entries either.
+    const queryHasNilable = qEntries.some((q) => !q.required);
+    const queryCompact = queryHasNilable ? '.compact' : '';
     lines.push('      params = {');
     for (let i = 0; i < qEntries.length; i++) {
       const q = qEntries[i];
       const sep = i === qEntries.length - 1 && !groupsGoToQuery ? '' : ',';
       lines.push(`        ${rubyStringLit(q.name)} => ${safeParamName(q.name)}${sep}`);
     }
-    lines.push('      }.compact');
+    lines.push(`      }${queryCompact}`);
 
     if (groupsGoToQuery) {
-      // Parameter group dispatch: merge grouped params into the query hash
+      // Parameter group dispatch: callers pass a typed variant class instance
+      // (e.g. `WorkOS::ParentResourceById`); we pattern-match on its class
+      // and forward its readers into the query hash.
       for (const group of op.parameterGroups ?? []) {
         const prop = fieldName(group.name);
         if (group.optional) {
           lines.push(`      if ${prop}`);
-          lines.push(`        case ${prop}[:type]`);
+          lines.push(`        case ${prop}`);
         } else {
-          lines.push(`      case ${prop}[:type]`);
+          lines.push(`      case ${prop}`);
         }
         for (const variant of group.variants) {
-          lines.push(`      when ${rubyStringLit(variant.name)}`);
+          const variantClass = variantClassRef(group, variant.name);
+          lines.push(`      when ${variantClass}`);
           for (const p of variant.parameters) {
-            lines.push(`        params[${rubyStringLit(p.name)}] = ${prop}[:${fieldName(p.name)}]`);
+            lines.push(`        params[${rubyStringLit(p.name)}] = ${prop}.${fieldName(p.name)}`);
           }
         }
+        lines.push(`      else`);
+        lines.push(`        raise ArgumentError, ${dispatchErrorLiteral(group, prop, variantClassRef)}`);
         lines.push('      end');
         if (group.optional) {
           lines.push('      end');
@@ -341,8 +402,12 @@ function emitMethod(args: {
     }
   }
 
-  // Request body
-  const hasBody = bodyFields.length > 0 && !['get', 'head'].includes(method_http);
+  // Request body. Emit when there are non-group body fields OR a parameter
+  // group dispatches into the body — the latter case matters when an
+  // operation's body is exclusively managed by a group (e.g.
+  // update_organization_membership's `role`), where filtering the group's
+  // leaves leaves bodyFields empty but the request still needs a payload.
+  const hasBody = (bodyFields.length > 0 && !['get', 'head'].includes(method_http)) || (hasGroups && hasBodyMethod);
 
   if (hasBody) {
     const bodyEntries: string[] = [];
@@ -355,35 +420,44 @@ function emitMethod(args: {
       const optKey = fc === 'client_secret' ? 'api_key' : fc;
       bodyEntries.push(`${rubyStringLit(fc)} => (request_options[:${optKey}] || @client.${clientProp})`);
     }
+    // Track whether any literal entry can be nil — defaults/inferFromClient
+    // resolve to non-nil values, so only optional body kwargs are nilable.
+    let bodyHasNilable = false;
     for (const f of bodyFields) {
       if (hiddenParams.has(f.name)) continue;
       bodyEntries.push(`${rubyStringLit(f.name)} => ${bodyKwargName(f.name)}`);
+      if (!f.required) bodyHasNilable = true;
     }
+    const bodyCompact = bodyHasNilable ? '.compact' : '';
     lines.push('      body = {');
     for (let i = 0; i < bodyEntries.length; i++) {
       const sep = i === bodyEntries.length - 1 ? '' : ',';
       lines.push(`        ${bodyEntries[i]}${sep}`);
     }
-    lines.push('      }.compact');
+    lines.push(`      }${bodyCompact}`);
 
     // Parameter group dispatch into body for POST/PUT/PATCH so sensitive
     // fields (passwords, role slugs) never leak into the URL query string.
     // DELETE groups are already handled via query above (groupsGoToQuery).
+    // Callers pass a typed variant class instance and we pattern-match on it.
     if (hasGroups && hasBodyMethod) {
       for (const group of op.parameterGroups ?? []) {
         const prop = fieldName(group.name);
         if (group.optional) {
           lines.push(`      if ${prop}`);
-          lines.push(`        case ${prop}[:type]`);
+          lines.push(`        case ${prop}`);
         } else {
-          lines.push(`      case ${prop}[:type]`);
+          lines.push(`      case ${prop}`);
         }
         for (const variant of group.variants) {
-          lines.push(`      when ${rubyStringLit(variant.name)}`);
+          const variantClass = variantClassRef(group, variant.name);
+          lines.push(`      when ${variantClass}`);
           for (const p of variant.parameters) {
-            lines.push(`        body[${rubyStringLit(p.name)}] = ${prop}[:${fieldName(p.name)}]`);
+            lines.push(`        body[${rubyStringLit(p.name)}] = ${prop}.${fieldName(p.name)}`);
           }
         }
+        lines.push(`      else`);
+        lines.push(`        raise ArgumentError, ${dispatchErrorLiteral(group, prop, variantClassRef)}`);
         lines.push('      end');
         if (group.optional) {
           lines.push('      end');
@@ -719,8 +793,9 @@ function buildYardDoc(
   queryParams: Parameter[],
   bodyFields: { name: string; required: boolean; type: TypeRef; description?: string; deprecated?: boolean }[],
   hiddenParams: Set<string>,
-  bodyFieldRenames?: Map<string, string>,
-  listWrapperModels?: Map<string, Model>,
+  bodyFieldRenames: Map<string, string> | undefined,
+  listWrapperModels: Map<string, Model> | undefined,
+  variantClassRef: (group: { name: string }, variantName: string) => string,
 ): string[] {
   const lines: string[] = [];
   const summary = op.description ?? `${op.httpMethod.toUpperCase()} ${op.path}`;
@@ -764,6 +839,16 @@ function buildYardDoc(
     const deprecatedPrefix = q.deprecated ? '(deprecated) ' : '';
     lines.push(`# @param ${n} [${type}${suffix}] ${deprecatedPrefix}${oneLine(q.description)}`.trim());
   }
+  // Parameter group kwargs: the type bracket lists the variant classes the
+  // caller may pass; no extra prose needed since YARD already renders them.
+  for (const group of op.parameterGroups ?? []) {
+    const n = fieldName(group.name);
+    if (emittedParamNames.has(n)) continue;
+    emittedParamNames.add(n);
+    const variantTypes = group.variants.map((v) => variantClassRef(group, v.name)).join(', ');
+    const suffix = group.optional ? ', nil' : '';
+    lines.push(`# @param ${n} [${variantTypes}${suffix}] Identifies the ${group.name.replace(/_/g, ' ')}.`);
+  }
   lines.push(`# @param request_options [Hash] (see WorkOS::Types::RequestOptions)`);
 
   // Return type: void for unknown-primitive, ListStruct for list wrappers and
@@ -797,3 +882,17 @@ void methodName;
 function rubyStringLit(s: string): string {
   return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
+
+/**
+ * Build a Ruby double-quoted string expression for the `else raise ArgumentError`
+ * arm of a parameter-group dispatcher. Lists the expected variant classes and
+ * interpolates the actual class of the value the caller passed.
+ */
+function dispatchErrorLiteral(
+  group: { name: string; variants: { name: string }[] },
+  prop: string,
+  variantClassRef: (group: { name: string }, variantName: string) => string,
+): string {
+  const expected = group.variants.map((v) => variantClassRef(group, v.name)).join(', ');
+  return `"expected ${prop} to be one of: ${expected}, got #{${prop}.class}"`;
+}