@workos/oagen-emitters 0.4.0 → 0.5.0

package/src/php/wrappers.ts

@@ -31,7 +31,7 @@ function emitWrapperMethod(
   // PHPDoc block
   const docParts: string[] = [];
   for (const { paramName, field, isOptional } of wrapperParams) {
-    const docType = field ? mapTypeRefForPHPDoc(field.type) : 'mixed';
+    const docType = field ? mapTypeRefForPHPDoc(field.type) : 'string';
     const nullSuffix = isOptional && !docType.endsWith('|null') ? '|null' : '';
     docParts.push(`@param ${docType}${nullSuffix} $${fieldName(paramName)}`);
   }
@@ -57,7 +57,11 @@ function emitWrapperMethod(
         requiredParams.push(`        ${phpType} $${phpName},`);
       }
     } else {
-      optionalParamLines.push(`        mixed $${phpName} = null,`);
+      if (isOptional) {
+        optionalParamLines.push(`        ?string $${phpName} = null,`);
+      } else {
+        requiredParams.push(`        string $${phpName},`);
+      }
     }
   }
   optionalParamLines.push(`        ?\\${ns}\\RequestOptions $options = null,`);

package/src/plugin.ts

@@ -0,0 +1,50 @@
+import { fileURLToPath } from 'node:url';
+import * as path from 'node:path';
+import type { OagenConfig } from '@workos/oagen';
+import { nodeEmitter } from './node/index.js';
+import { pythonEmitter } from './python/index.js';
+import { phpEmitter } from './php/index.js';
+import { goEmitter } from './go/index.js';
+import { dotnetEmitter } from './dotnet/index.js';
+import { kotlinEmitter } from './kotlin/index.js';
+import { rubyEmitter } from './ruby/index.js';
+import { nodeExtractor } from './compat/extractors/node.js';
+import { rubyExtractor } from './compat/extractors/ruby.js';
+import { pythonExtractor } from './compat/extractors/python.js';
+import { phpExtractor } from './compat/extractors/php.js';
+import { goExtractor } from './compat/extractors/go.js';
+import { rustExtractor } from './compat/extractors/rust.js';
+import { kotlinExtractor } from './compat/extractors/kotlin.js';
+import { dotnetExtractor } from './compat/extractors/dotnet.js';
+import { elixirExtractor } from './compat/extractors/elixir.js';
+
+// Resolve smoke runner paths relative to the package root so they work
+// regardless of which project loads the config (CWD-independent).
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const smokeDir = path.resolve(__dirname, '..', 'smoke');
+
+export const workosEmittersPlugin: Pick<OagenConfig, 'emitters' | 'extractors' | 'smokeRunners'> = {
+  emitters: [nodeEmitter, pythonEmitter, phpEmitter, goEmitter, dotnetEmitter, kotlinEmitter, rubyEmitter],
+  extractors: [
+    nodeExtractor,
+    rubyExtractor,
+    pythonExtractor,
+    phpExtractor,
+    goExtractor,
+    rustExtractor,
+    kotlinExtractor,
+    dotnetExtractor,
+    elixirExtractor,
+  ],
+  smokeRunners: {
+    node: path.join(smokeDir, 'sdk-node.ts'),
+    ruby: path.join(smokeDir, 'sdk-ruby.ts'),
+    python: path.join(smokeDir, 'sdk-python.ts'),
+    php: path.join(smokeDir, 'sdk-php.ts'),
+    go: path.join(smokeDir, 'sdk-go.ts'),
+    rust: path.join(smokeDir, 'sdk-rust.ts'),
+    elixir: path.join(smokeDir, 'sdk-elixir.ts'),
+    kotlin: path.join(smokeDir, 'sdk-kotlin.ts'),
+    dotnet: path.join(smokeDir, 'sdk-dotnet.ts'),
+  },
+};

package/src/python/client.ts

@@ -1,8 +1,8 @@
 import type { ApiSpec, EmitterContext, GeneratedFile, Service } from '@workos/oagen';
 import { toPascalCase } from '@workos/oagen';
 import { className, resolveServiceDir, servicePropertyName, buildMountDirMap, dirToModule } from './naming.js';
-import { resolveResourceClassName } from './resources.js';
-import { getMountTarget } from '../shared/resolved-ops.js';
+import { resolveResourceClassName, collectParameterGroupClassNames } from './resources.js';
+import { getMountTarget, groupByMount } from '../shared/resolved-ops.js';
 import { NON_SPEC_SERVICES } from '../shared/non-spec-services.js';
 
 /** Python-specific wiring for each non-spec service. */
@@ -254,12 +254,22 @@ function generateServiceInits(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
   const topLevel = deduplicateByMount(spec.services, ctx);
   const serviceDirMap = buildMountDirMap(ctx);
 
+  // Build a map from mount target -> operations so we can discover parameter
+  // group dataclasses that need re-exporting from __init__.py.
+  const mountGroups = groupByMount(ctx);
+
   for (const service of topLevel) {
     const resolvedName = resolveResourceClassName(service, ctx);
     const dirName = serviceDirMap.get(service.name) ?? resolveServiceDir(resolvedName);
     const lines: string[] = [];
 
-    lines.push(`from ._resource import ${resolvedName}, Async${resolvedName}`);
+    // Collect parameter group class names from all operations in this mount group
+    const mountTarget = getMountTarget(service, ctx);
+    const ops = mountGroups.get(mountTarget)?.operations ?? service.operations;
+    const groupClassNames = collectParameterGroupClassNames(ops);
+
+    const resourceImports = [resolvedName, `Async${resolvedName}`, ...groupClassNames];
+    lines.push(`from ._resource import ${resourceImports.join(', ')}`);
     lines.push('from .models import *');
 
     files.push({

package/src/python/enums.ts

@@ -37,6 +37,8 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
     // If this enum is an alias for a canonical enum, generate a type alias file
     const canonicalName = aliasOf.get(enumDef.name);
     if (canonicalName) {
+      // Skip when alias and canonical produce the same file name (self-import)
+      if (fileName(enumDef.name) === fileName(canonicalName)) continue;
       const canonicalService = enumToService.get(canonicalName);
       const canonicalDir = resolveDir(canonicalService);
       const canonicalCls = className(canonicalName);
@@ -137,7 +139,15 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
         lines.push('from typing import Union');
         lines.push('from typing import Literal, TypeAlias');
         lines.push('');
-        const literals = uniqueValues.map((v) => (typeof v.value === 'string' ? `"${v.value}"` : String(v.value)));
+        const literals = uniqueValues.map((v) =>
+          typeof v.value === 'string'
+            ? `"${v.value}"`
+            : typeof v.value === 'boolean'
+              ? v.value
+                ? 'True'
+                : 'False'
+              : String(v.value),
+        );
         lines.push(`${cls}: TypeAlias = Union[Literal[${literals.join(', ')}], str]`);
         files.push({
           path: `src/${ctx.namespace}/${dirName}/models/${fileName(enumDef.name)}.py`,
@@ -157,7 +167,14 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
           memberName = `${memberName}_${suffix}`;
         }
         usedNames.add(memberName);
-        const valueStr = typeof v.value === 'string' ? `"${v.value}"` : String(v.value);
+        const valueStr =
+          typeof v.value === 'string'
+            ? `"${v.value}"`
+            : typeof v.value === 'boolean'
+              ? v.value
+                ? 'True'
+                : 'False'
+              : String(v.value);
         lines.push(`    ${memberName} = ${valueStr}`);
         if (v.description || v.deprecated) {
           const parts: string[] = [];
@@ -180,7 +197,15 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       lines.push('');
       lines.push(
         `${cls}Literal: TypeAlias = Literal[${uniqueValues
-          .map((v) => (typeof v.value === 'string' ? `"${v.value}"` : String(v.value)))
+          .map((v) =>
+            typeof v.value === 'string'
+              ? `"${v.value}"`
+              : typeof v.value === 'boolean'
+                ? v.value
+                  ? 'True'
+                  : 'False'
+                : String(v.value),
+          )
           .join(', ')}]`,
       );
     }

package/src/python/index.ts

@@ -8,10 +8,9 @@ import type {
   Enum,
   Service,
 } from '@workos/oagen';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
 
 import { generateModels } from './models.js';
+import { detectDiscriminators } from '../shared/model-utils.js';
 import { generateEnums } from './enums.js';
 import { generateResources } from './resources.js';
 import { generateClient } from './client.js';
@@ -27,11 +26,23 @@ function ensureTrailingNewlines(files: GeneratedFile[]): GeneratedFile[] {
   return files;
 }
 
+/**
+ * Annotate models with implicit discriminator info (without full oneOf
+ * field flattening which can break existing model structures/fixtures).
+ */
+function withDiscriminators(ctx: EmitterContext): EmitterContext {
+  const annotated = detectDiscriminators(ctx.spec.models);
+  if (annotated === ctx.spec.models) return ctx;
+  const spec: ApiSpec = { ...ctx.spec, models: annotated };
+  return { ...ctx, spec };
+}
+
 export const pythonEmitter: Emitter = {
   language: 'python',
 
   generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateModels(models, ctx));
+    const annotated = detectDiscriminators(models);
+    return ensureTrailingNewlines(generateModels(annotated, ctx));
   },
 
   generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
@@ -39,11 +50,11 @@ export const pythonEmitter: Emitter = {
   },
 
   generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateResources(services, ctx));
+    return ensureTrailingNewlines(generateResources(services, withDiscriminators(ctx)));
   },
 
   generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateClient(spec, ctx));
+    return ensureTrailingNewlines(generateClient(spec, withDiscriminators(ctx)));
   },
 
   generateErrors(): GeneratedFile[] {
@@ -59,7 +70,15 @@ export const pythonEmitter: Emitter = {
   },
 
   generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateTests(spec, ctx));
+    // Use original spec for model filtering (requestOnlyModelNames etc.) but
+    // annotate discriminator models so dispatch tests are generated.
+    const annotated = detectDiscriminators(spec.models);
+    // Only replace discriminator-annotated models, keep the rest unchanged
+    // so request-only filtering and field-based logic work correctly.
+    const annotatedByName = new Map(annotated.filter((m: any) => m.discriminator).map((m) => [m.name, m]));
+    const testModels = spec.models.map((m) => annotatedByName.get(m.name) ?? m);
+    const testSpec: ApiSpec = { ...spec, models: testModels };
+    return ensureTrailingNewlines(generateTests(testSpec, { ...ctx, spec: testSpec }));
   },
 
   generateManifest(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
@@ -70,26 +89,15 @@ export const pythonEmitter: Emitter = {
     return '# This file is auto-generated by oagen. Do not edit.';
   },
 
-  formatCommand(targetDir: string): FormatCommand | null {
-    const hasRuff =
-      fs.existsSync(path.join(targetDir, 'ruff.toml')) || fs.existsSync(path.join(targetDir, '.ruff.toml'));
-    // Also check pyproject.toml for [tool.ruff] section
-    const pyproject = path.join(targetDir, 'pyproject.toml');
-    const hasRuffInPyproject = fs.existsSync(pyproject) && fs.readFileSync(pyproject, 'utf8').includes('[tool.ruff]');
-    // Check for noxfile that uses ruff
-    const noxfile = path.join(targetDir, 'noxfile.py');
-    const hasRuffInNox = fs.existsSync(noxfile) && fs.readFileSync(noxfile, 'utf8').includes('ruff');
-
-    if (hasRuff || hasRuffInPyproject || hasRuffInNox) {
-      return {
-        cmd: 'bash',
-        args: [
-          '-c',
-          'PY_FILES=$(printf "%s\\n" "$@" | grep "\\.py$"); [ -n "$PY_FILES" ] && echo "$PY_FILES" | xargs ruff check --fix --quiet 2>/dev/null; [ -n "$PY_FILES" ] && echo "$PY_FILES" | xargs ruff format --quiet',
-          '--',
-        ],
-      };
-    }
-    return null;
+  formatCommand(_targetDir: string): FormatCommand | null {
+    return {
+      cmd: 'bash',
+      args: [
+        '-c',
+        'PY_FILES=$(printf "%s\\n" "$@" | grep "\\.py$" || true); if [ -n "$PY_FILES" ]; then echo "$PY_FILES" | xargs ruff check --fix --quiet 2>/dev/null; echo "$PY_FILES" | xargs ruff format --quiet; fi',
+        '--',
+      ],
+      batchSize: 1000,
+    };
   },
 };

package/src/python/models.ts

@@ -18,6 +18,9 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     irService ? (mountDirMap.get(irService) ?? 'common') : 'common';
   const files: GeneratedFile[] = [];
   const emittedModelSymbolsByDir = new Map<string, string[]>();
+  // Overrides fileName() for symbols that live in a differently-named file.
+  // Used for variant type aliases (e.g. EventSchemaVariant → event_schema).
+  const symbolToFile = new Map<string, string>();
   const modelUsage = collectModelUsage(ctx.spec);
 
   // Build recursive structural hashes for deduplication.
@@ -45,6 +48,10 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     }
   }
 
+  // Track emitted file paths to prevent duplicates when synthetic models from
+  // oneOf enrichment collide with existing IR models in snake_case.
+  const emittedFilePaths = new Set<string>();
+
   for (const model of models) {
     // Skip list wrapper models (e.g., OrganizationList) — SyncPage handles envelopes
     if (isListWrapperModel(model)) continue;
@@ -55,9 +62,135 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     const dirName = resolveDir(service);
     const modelClassName = className(model.name);
 
+    // Skip models whose file path was already emitted (name collision after snake_case)
+    const modelFilePath = `src/${ctx.namespace}/${dirName}/models/${fileName(model.name)}.py`;
+    if (emittedFilePaths.has(modelFilePath)) continue;
+    emittedFilePaths.add(modelFilePath);
+
+    // If this model is a discriminated union dispatcher, generate a factory class
+    // instead of a regular dataclass (e.g. EventSchema where each variant has
+    // event: const: "..."). The dispatcher owns a Union type alias and a from_dict
+    // method that routes to the correct concrete variant at runtime.
+    if ((model as any).discriminator) {
+      const disc = (model as any).discriminator as { property: string; mapping: Record<string, string> };
+      const variantNames = Object.values(disc.mapping); // model names, e.g. ["ActionAuthenticationDenied", ...]
+      const variantTypeName = `${modelClassName}Variant`; // e.g. "EventSchemaVariant"
+
+      const dispLines: string[] = [];
+      dispLines.push('from __future__ import annotations');
+      dispLines.push('');
+      dispLines.push('from dataclasses import dataclass');
+      dispLines.push('from typing import Any, ClassVar, Dict, Union, cast');
+      dispLines.push(`from ${ctx.namespace}._types import _raise_deserialize_error`);
+      dispLines.push('');
+
+      // Import each variant model from its resolved location
+      const sortedVariants = [...new Set(variantNames)].sort();
+      for (const variantModelName of sortedVariants) {
+        const variantService = modelToService.get(variantModelName);
+        const variantDir = resolveDir(variantService);
+        if (variantDir === dirName) {
+          dispLines.push(`from .${fileName(variantModelName)} import ${className(variantModelName)}`);
+        } else {
+          dispLines.push(
+            `from ${ctx.namespace}.${dirToModule(variantDir)}.models.${fileName(variantModelName)} import ${className(variantModelName)}`,
+          );
+        }
+      }
+
+      // Unknown variant for forward-compatible unknown discriminator values
+      const unknownClassName = `${modelClassName}Unknown`;
+      dispLines.push('');
+      dispLines.push('');
+      dispLines.push('@dataclass(slots=True)');
+      dispLines.push(`class ${unknownClassName}:`);
+      dispLines.push(`    """Unknown variant of ${modelClassName} not yet recognized by this SDK version."""`);
+      dispLines.push('');
+      dispLines.push('    raw_data: Dict[str, Any]');
+      dispLines.push('    """The raw payload, preserved so callers can still inspect the data."""');
+      dispLines.push('');
+      dispLines.push('    @classmethod');
+      dispLines.push(`    def from_dict(cls, data: Dict[str, Any]) -> "${unknownClassName}":`);
+      dispLines.push('        """Wrap raw data in an unknown variant."""');
+      dispLines.push('        return cls(raw_data=data)');
+      dispLines.push('');
+      dispLines.push('    def to_dict(self) -> Dict[str, Any]:');
+      dispLines.push('        """Return the original raw data."""');
+      dispLines.push('        return dict(self.raw_data)');
+
+      dispLines.push('');
+      dispLines.push('');
+
+      // Union type alias — includes unknown variant for forward compatibility
+      dispLines.push(`${variantTypeName} = Union[`);
+      for (const variantModelName of sortedVariants) {
+        dispLines.push(`    ${className(variantModelName)},`);
+      }
+      dispLines.push(`    ${unknownClassName},`);
+      dispLines.push(']');
+
+      dispLines.push('');
+      dispLines.push('');
+
+      // Dispatcher class
+      if (model.description) {
+        dispLines.push(`class ${modelClassName}:`);
+        dispLines.push(`    """${model.description}"""`);
+      } else {
+        dispLines.push(`class ${modelClassName}:`);
+        dispLines.push(`    """Discriminated union dispatcher (discriminated by '${disc.property}')."""`);
+      }
+      dispLines.push('');
+      dispLines.push(`    _DISPATCH: ClassVar[Dict[str, type]] = {`);
+      for (const [value, variantModelName] of Object.entries(disc.mapping).sort(([a], [b]) => a.localeCompare(b))) {
+        dispLines.push(`        "${value}": ${className(variantModelName)},`);
+      }
+      dispLines.push('    }');
+      dispLines.push('');
+      dispLines.push('    @classmethod');
+      dispLines.push(`    def from_dict(cls, data: Dict[str, Any]) -> "${variantTypeName}":`);
+      dispLines.push('        """Deserialize from a dictionary, dispatching to the correct variant."""');
+      dispLines.push(`        if "${disc.property}" not in data:`);
+      dispLines.push(
+        `            _raise_deserialize_error("${modelClassName}", ValueError("Missing required field '${disc.property}'"))`,
+      );
+      dispLines.push(`        disc_value = data["${disc.property}"]`);
+      dispLines.push('        if disc_value is None:');
+      dispLines.push(
+        `            _raise_deserialize_error("${modelClassName}", ValueError("${disc.property} must not be None"))`,
+      );
+      dispLines.push('        dispatch_cls = cls._DISPATCH.get(disc_value)');
+      dispLines.push('        if dispatch_cls is not None:');
+      dispLines.push(`            return cast("${variantTypeName}", dispatch_cls.from_dict(data))`);
+      dispLines.push(`        return ${unknownClassName}.from_dict(data)`);
+
+      files.push({
+        path: `src/${ctx.namespace}/${dirName}/models/${fileName(model.name)}.py`,
+        content: dispLines.join('\n'),
+        integrateTarget: true,
+        overwriteExisting: true,
+      });
+
+      if (!emittedModelSymbolsByDir.has(dirName)) emittedModelSymbolsByDir.set(dirName, []);
+      emittedModelSymbolsByDir.get(dirName)!.push(model.name);
+      // Also register the variant type alias and unknown variant in the barrel,
+      // pointing to the same file as the dispatcher.
+      emittedModelSymbolsByDir.get(dirName)!.push(variantTypeName);
+      symbolToFile.set(variantTypeName, fileName(model.name));
+      emittedModelSymbolsByDir.get(dirName)!.push(unknownClassName);
+      symbolToFile.set(unknownClassName, fileName(model.name));
+      continue;
+    }
+
     // If this model is an alias for a canonical model, generate a type alias file
     const canonicalName = aliasOf.get(model.name);
     if (canonicalName) {
+      // Skip when alias and canonical produce the same file name (self-import).
+      // This happens when synthetic models from oneOf enrichment collide with
+      // existing IR models in snake_case (e.g., Foo_bar vs FooBar).
+      if (fileName(model.name) === fileName(canonicalName)) {
+        continue;
+      }
       const canonicalService = modelToService.get(canonicalName);
       const canonicalDir = resolveDir(canonicalService);
       const canonicalClassName = className(canonicalName);
@@ -312,7 +445,8 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     const uniqueNames = [...new Set(names)].sort();
     const importLines: string[] = [];
     for (const name of uniqueNames) {
-      importLines.push(`from .${fileName(name)} import ${className(name)} as ${className(name)}`);
+      const fileNameForSymbol = symbolToFile.get(name) ?? fileName(name);
+      importLines.push(`from .${fileNameForSymbol} import ${className(name)} as ${className(name)}`);
     }
     const imports = importLines.join('\n');
     files.push({
@@ -473,6 +607,9 @@ function compareAliasPriority(left: string, right: string, usage: ReturnType<typ
 }
 
 function canAliasModels(canonical: string, alias: string, usage: ReturnType<typeof collectModelUsage>): boolean {
+  // Don't alias when both models produce the same file name — the TypeAlias
+  // file would import from itself (e.g., FooBar aliased to Foo_bar).
+  if (fileName(canonical) === fileName(alias)) return false;
   // Don't alias across request/response boundaries — a request-only model
   // and a response-only model may look identical today but evolve independently.
   if (