@workos/oagen-emitters 0.6.7 → 0.7.0

package/dist/plugin.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos/oagen-emitters",
-  "version": "0.6.7",
+  "version": "0.7.0",
   "description": "WorkOS' oagen emitters",
   "license": "MIT",
   "author": "WorkOS",
@@ -54,6 +54,6 @@
     "node": ">=24.10.0"
   },
   "dependencies": {
-    "@workos/oagen": "^0.9.0"
+    "@workos/oagen": "^0.12.0"
   }
 }

package/src/node/tests.ts

@@ -854,7 +854,7 @@ function modelNeedsRoundTripTest(model: Model): boolean {
  */
 function generateSerializerTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
   const files: GeneratedFile[] = [];
-  const modelToService = assignModelsToServices(spec.models, spec.services);
+  const modelToService = assignModelsToServices(spec.models, spec.services, ctx.modelHints);
   const serviceNameMap = new Map<string, string>();
   for (const service of spec.services) {
     serviceNameMap.set(service.name, resolveResourceClassName(service, ctx));

package/src/node/utils.ts

@@ -223,7 +223,7 @@ export function createServiceDirResolver(
   serviceNameMap: Map<string, string>;
   resolveDir: (irService: string | undefined) => string;
 } {
-  const modelToService = assignModelsToServices(models, services);
+  const modelToService = assignModelsToServices(models, services, ctx.modelHints);
   const serviceNameMap = buildServiceNameMap(services, ctx);
   const resolveDir = (irService: string | undefined) =>
     irService ? resolveServiceDir(serviceNameMap.get(irService) ?? irService) : 'common';

package/src/python/models.ts

@@ -11,7 +11,7 @@ import { assignEnumsToServices, collectGeneratedEnumSymbolsByDir } from './enums
 export function generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
   if (models.length === 0) return [];
 
-  const modelToService = assignModelsToServices(models, ctx.spec.services);
+  const modelToService = assignModelsToServices(models, ctx.spec.services, ctx.modelHints);
   const enumToService = assignEnumsToServices(ctx.spec.enums, ctx.spec.services);
   const mountDirMap = buildMountDirMap(ctx);
   const resolveDir = (irService: string | undefined) =>

package/src/python/resources.ts

@@ -1116,7 +1116,7 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
     const actualModelImports = [...modelImports];
 
     // Split imports into same-service and cross-service (using mount-based dirs)
-    const modelToServiceMap = assignModelsToServices(ctx.spec.models, ctx.spec.services);
+    const modelToServiceMap = assignModelsToServices(ctx.spec.models, ctx.spec.services, ctx.modelHints);
     // Discriminator variant type aliases (e.g. EventSchemaVariant) live in the same
     // service as their dispatcher model, so ensure they resolve to the same directory.
     for (const model of ctx.spec.models) {

package/src/python/tests.ts

@@ -227,7 +227,7 @@ function generateServiceTest(
   });
 
   // Group imports by their actual service directory (models may live in different services)
-  const modelToServiceMap = assignModelsToServices(spec.models, spec.services);
+  const modelToServiceMap = assignModelsToServices(spec.models, spec.services, ctx.modelHints);
   const mountDirMap = buildMountDirMap(ctx);
   const resolveModelDir = (modelName: string) => {
     const svc = modelToServiceMap.get(modelName);
@@ -1402,7 +1402,7 @@ function generateModelRoundTripTests(spec: ApiSpec, ctx: EmitterContext): Genera
   );
   if (models.length === 0) return null;
 
-  const modelToService = assignModelsToServices(spec.models, spec.services);
+  const modelToService = assignModelsToServices(spec.models, spec.services, ctx.modelHints);
   const roundTripDirMap = buildMountDirMap(ctx);
   const resolveDir = (irService: string | undefined) =>
     irService ? (roundTripDirMap.get(irService) ?? 'common') : 'common';

package/src/ruby/client.ts

@@ -182,7 +182,7 @@ function generateMainEntryFile(spec: ApiSpec, ctx: EmitterContext): GeneratedFil
  * keep the generated namespace flat while the filesystem is grouped.
  */
 function collectModelSubdirs(spec: ApiSpec, ctx: EmitterContext): string[] {
-  const modelToService = assignModelsToServices(spec.models as Model[], spec.services);
+  const modelToService = assignModelsToServices(spec.models as Model[], spec.services, ctx.modelHints);
   const mountDirMap = buildMountDirMap(ctx);
   const subdirs = new Set<string>();
   for (const model of spec.models as Model[]) {

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/models.ts

@@ -67,7 +67,7 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
   // Model → mount target directory. Each model is assigned to the first service
   // that references it (transitively). Orphans land in `shared/`. Zeitwerk is
   // told to collapse each subfolder (in client.ts) so the namespace stays flat.
-  const modelToService = assignModelsToServices(models, ctx.spec.services);
+  const modelToService = assignModelsToServices(models, ctx.spec.services, ctx.modelHints);
   const mountDirMap = buildMountDirMap(ctx);
   const dirFor = (modelName: string): string => {
     const service = modelToService.get(modelName);

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