@workos/oagen-emitters 0.4.0 → 0.5.0

package/src/ruby/wrappers.ts

@@ -0,0 +1,161 @@
+import type { EmitterContext, Operation, ResolvedOperation, ResolvedWrapper } from '@workos/oagen';
+import { className, fieldName, safeParamName } from './naming.js';
+import { resolveWrapperParams, formatWrapperDescription } from '../shared/wrapper-utils.js';
+import { mapTypeRefForYard } from './type-map.js';
+
+/**
+ * Generate Ruby wrapper method lines for union split operations.
+ *
+ * Each wrapper is a typed convenience method that:
+ * - Accepts only the exposed params (keyword args)
+ * - Injects constant defaults (e.g., grant_type)
+ * - Reads inferred fields from client config (e.g., client_id)
+ * - Delegates to the same HTTP runtime as the main method
+ */
+export function generateWrapperMethods(
+  resolvedOp: ResolvedOperation,
+  ctx: EmitterContext,
+  modelNames: Set<string>,
+  requires: Set<string>,
+): string[] {
+  if (!resolvedOp.wrappers || resolvedOp.wrappers.length === 0) return [];
+  const out: string[] = [];
+  for (const wrapper of resolvedOp.wrappers) {
+    const body = emitWrapperMethod(resolvedOp.operation, wrapper, ctx, modelNames, requires);
+    out.push(body);
+  }
+  return out;
+}
+
+/** Collect response model filenames needed for wrapper imports. */
+export function collectWrapperResponseModels(resolvedOp: ResolvedOperation): Set<string> {
+  const models = new Set<string>();
+  for (const w of resolvedOp.wrappers ?? []) {
+    if (w.responseModelName) models.add(w.responseModelName);
+  }
+  return models;
+}
+
+function emitWrapperMethod(
+  op: Operation,
+  wrapper: ResolvedWrapper,
+  ctx: EmitterContext,
+  modelNames: Set<string>,
+  requires: Set<string>,
+): string {
+  void requires;
+  const method = wrapper.name; // already snake_case
+  const wrapperParams = resolveWrapperParams(wrapper, ctx);
+  const lines: string[] = [];
+
+  // YARD doc
+  lines.push(`    # ${formatWrapperDescription(wrapper.name)}.`);
+  for (const p of op.pathParams ?? []) {
+    const pyType = mapTypeRefForYard(p.type);
+    lines.push(`    # @param ${safeParamName(p.name)} [${pyType}]`);
+  }
+  for (const wp of wrapperParams) {
+    const type = wp.field ? mapTypeRefForYard(wp.field.type) : 'String';
+    const alreadyNilable = type.split(', ').includes('nil');
+    const suffix = wp.isOptional && !alreadyNilable ? ', nil' : '';
+    lines.push(`    # @param ${fieldName(wp.paramName)} [${type}${suffix}]`);
+  }
+  lines.push(`    # @param request_options [Hash] Per-request overrides.`);
+  if (wrapper.responseModelName) {
+    lines.push(`    # @return [WorkOS::${className(wrapper.responseModelName)}]`);
+  } else {
+    lines.push(`    # @return [nil]`);
+  }
+
+  // Signature
+  const sigParts: string[] = [];
+  const seen = new Set<string>();
+  for (const p of op.pathParams ?? []) {
+    const n = safeParamName(p.name);
+    if (seen.has(n)) continue;
+    seen.add(n);
+    sigParts.push(`${n}:`);
+  }
+  // Required first, then optional
+  for (const wp of wrapperParams) {
+    if (wp.isOptional) continue;
+    const n = fieldName(wp.paramName);
+    if (seen.has(n)) continue;
+    seen.add(n);
+    sigParts.push(`${n}:`);
+  }
+  for (const wp of wrapperParams) {
+    if (!wp.isOptional) continue;
+    const n = fieldName(wp.paramName);
+    if (seen.has(n)) continue;
+    seen.add(n);
+    sigParts.push(`${n}: nil`);
+  }
+  sigParts.push('request_options: {}');
+
+  if (sigParts.length === 1 && sigParts[0].length < 60) {
+    lines.push(`    def ${method}(${sigParts[0]})`);
+  } else {
+    lines.push(`    def ${method}(`);
+    for (let i = 0; i < sigParts.length; i++) {
+      const sep = i === sigParts.length - 1 ? '' : ',';
+      lines.push(`      ${sigParts[i]}${sep}`);
+    }
+    lines.push('    )');
+  }
+
+  // Body hash
+  const bodyEntries: string[] = [];
+  for (const [k, v] of Object.entries(wrapper.defaults)) {
+    const lit = typeof v === 'string' ? rubyStringLit(v) : String(v);
+    bodyEntries.push(`${rubyStringLit(k)} => ${lit}`);
+  }
+  for (const fc of wrapper.inferFromClient) {
+    const clientProp = fc === 'client_secret' ? 'api_key' : fc;
+    bodyEntries.push(`${rubyStringLit(fc)} => @client.${clientProp}`);
+  }
+  for (const wp of wrapperParams) {
+    bodyEntries.push(`${rubyStringLit(wp.paramName)} => ${fieldName(wp.paramName)}`);
+  }
+  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');
+
+  // Path string — use the unified @client.request helper.
+  const rubyPath = interpolateRubyPath(op.path, op.pathParams ?? []);
+  const verbSym = op.httpMethod.toLowerCase();
+  lines.push('      response = @client.request(');
+  lines.push(`        method: :${verbSym},`);
+  lines.push(`        path: ${rubyPath},`);
+  lines.push('        auth: true,');
+  lines.push('        body: body,');
+  lines.push('        request_options: request_options');
+  lines.push('      )');
+
+  // Response handling
+  if (wrapper.responseModelName && modelNames.has(wrapper.responseModelName)) {
+    lines.push(`      WorkOS::${className(wrapper.responseModelName)}.new(response.body)`);
+  } else {
+    lines.push('      JSON.parse(response.body)');
+  }
+
+  lines.push('    end');
+
+  return lines.join('\n');
+}
+
+function interpolateRubyPath(path: string, pathParams: Operation['pathParams']): string {
+  if (!pathParams || pathParams.length === 0) return `'${path}'`;
+  let result = path;
+  for (const p of pathParams) {
+    result = result.split(`{${p.name}}`).join(`#{WorkOS::Util.encode_path(${safeParamName(p.name)})}`);
+  }
+  return `"${result}"`;
+}
+
+function rubyStringLit(s: string): string {
+  return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}

package/src/shared/model-utils.ts

@@ -1,4 +1,5 @@
 import type { Model, Field, TypeRef, Enum } from '@workos/oagen';
+import { toSnakeCase } from '@workos/oagen';
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 // @ts-ignore -- js-yaml has no type declarations in this project
@@ -159,7 +160,7 @@ function rawSchemaToTypeRef(
   if (schema.enum && collector && parentModelName && fName) {
     // Generate a synthetic enum
     const syntheticName = `${parentModelName}_${fName}`;
-    if (!collector.usedNames.has(syntheticName)) {
+    if (!collector.usedNames.has(syntheticName) && !collector.usedNames.has(toSnakeCase(syntheticName))) {
       collector.usedNames.add(syntheticName);
       collector.enums.push({
         name: syntheticName,
@@ -197,7 +198,7 @@ function rawSchemaToTypeRef(
   if (baseType === 'object' && schema.properties && collector && parentModelName && fName) {
     // Inline object -- generate a synthetic model
     const syntheticName = `${parentModelName}_${fName}`;
-    if (!collector.usedNames.has(syntheticName)) {
+    if (!collector.usedNames.has(syntheticName) && !collector.usedNames.has(toSnakeCase(syntheticName))) {
       collector.usedNames.add(syntheticName);
       const fields: Field[] = [];
       const requiredSet = new Set<string>(schema.required ?? []);
@@ -388,6 +389,102 @@ export function getSyntheticEnums(): Enum[] {
   return _lastSyntheticEnums;
 }
 
+// ---------------------------------------------------------------------------
+// Implicit discriminator detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Find a property name that has a `const` value in ALL oneOf variants.
+ * Returns null if no shared const property is found.
+ */
+function findSharedConstProperty(oneOfSchemas: Record<string, any>[]): string | null {
+  if (oneOfSchemas.length === 0) return null;
+
+  const first = oneOfSchemas[0];
+  if (!first.properties) return null;
+
+  // Candidate properties from the first variant that have const values
+  const candidates = Object.keys(first.properties).filter((name) => first.properties[name].const !== undefined);
+
+  // Return the first candidate that has const values in ALL variants
+  for (const candidate of candidates) {
+    const allHaveConst = oneOfSchemas.every((variant) => variant.properties?.[candidate]?.const !== undefined);
+    if (allHaveConst) return candidate;
+  }
+
+  return null;
+}
+
+/**
+ * Build a discriminator mapping from const values to IR model names.
+ * For each oneOf variant's const value on `discProperty`, find the IR model
+ * whose field with the same name is a Literal type with that value.
+ */
+function buildDiscriminatorMapping(
+  discProperty: string,
+  oneOfSchemas: Record<string, any>[],
+  models: Model[],
+  parentModelName: string,
+): Record<string, string> {
+  const mapping: Record<string, string> = {};
+
+  for (const variant of oneOfSchemas) {
+    const constValue = variant.properties?.[discProperty]?.const;
+    if (constValue === undefined) continue;
+
+    const variantModel = models.find(
+      (m) =>
+        m.name !== parentModelName &&
+        m.fields.some(
+          (f) => f.name === discProperty && f.type.kind === 'literal' && (f.type as any).value === constValue,
+        ),
+    );
+    if (variantModel) {
+      mapping[String(constValue)] = variantModel.name;
+    }
+  }
+
+  return mapping;
+}
+
+/**
+ * Detect implicit discriminators on models without full oneOf flattening.
+ * Returns a new array with discriminator annotations; models without
+ * discriminators are returned as-is. Use this when you need discriminator
+ * info but don't want the side-effects of full enrichment (synthetic
+ * models/enums, field flattening).
+ */
+export function detectDiscriminators(models: Model[]): Model[] {
+  const spec = loadRawSpec();
+  if (!spec) return models;
+
+  let changed = false;
+  const result = models.map((model) => {
+    if ((model as any).discriminator) return model;
+
+    const rawSchema = lookupRawSchema(model.name);
+    if (!rawSchema) return model;
+
+    const oneOfContainer = rawSchema.allOf?.find((s: any) => s.oneOf);
+    if (!oneOfContainer?.oneOf || oneOfContainer.oneOf.length === 0) return model;
+
+    const discProperty = findSharedConstProperty(oneOfContainer.oneOf);
+    if (!discProperty) return model;
+
+    const mapping = buildDiscriminatorMapping(discProperty, oneOfContainer.oneOf, models, model.name);
+    if (Object.keys(mapping).length === 0) return model;
+
+    changed = true;
+    return {
+      ...model,
+      fields: [],
+      discriminator: { property: discProperty, mapping },
+    };
+  });
+
+  return changed ? result : models;
+}
+
 /**
  * Enrich IR models by flattening oneOf/allOf+oneOf variant fields from the raw spec.
  *
@@ -411,8 +508,13 @@ export function enrichModelsFromSpec(models: Model[]): Model[] {
   }
 
   const collector = createCollector();
-  // Avoid name collisions with existing models
-  for (const m of models) collector.usedNames.add(m.name);
+  // Avoid name collisions with existing models (check both PascalCase and
+  // snake_case to prevent synthetic models from shadowing existing ones when
+  // they share a file name, e.g. FooBar vs Foo_bar -> foo_bar).
+  for (const m of models) {
+    collector.usedNames.add(m.name);
+    collector.usedNames.add(toSnakeCase(m.name));
+  }
 
   const enriched = models.map((model) => {
     const rawSchema = lookupRawSchema(model.name);
@@ -421,13 +523,32 @@ export function enrichModelsFromSpec(models: Model[]): Model[] {
     const hasOneOf = rawSchema.oneOf || rawSchema.allOf?.some((s: any) => s.oneOf);
     if (!hasOneOf) return model;
 
-    // Skip schemas with discriminator -- those are intentional unions
+    // Skip schemas with explicit discriminator -- those are intentional unions
     const hasDiscriminator =
       rawSchema.discriminator ||
       rawSchema.oneOf?.some((v: any) => v.discriminator) ||
       rawSchema.allOf?.some((s: any) => s.discriminator || s.oneOf?.some((v: any) => v.discriminator));
     if (hasDiscriminator) return model;
 
+    // Detect implicit discriminators: allOf+oneOf where all variants share a
+    // property with const values (e.g., EventSchema with event: const: "user.created").
+    // When found, attach a discriminator mapping and clear fields so the emitter
+    // generates a dispatcher class instead of a flat dataclass.
+    const oneOfContainer = rawSchema.allOf?.find((s: any) => s.oneOf);
+    if (oneOfContainer?.oneOf && oneOfContainer.oneOf.length > 0) {
+      const discProperty = findSharedConstProperty(oneOfContainer.oneOf);
+      if (discProperty) {
+        const mapping = buildDiscriminatorMapping(discProperty, oneOfContainer.oneOf, models, model.name);
+        if (Object.keys(mapping).length > 0) {
+          return {
+            ...model,
+            fields: [],
+            discriminator: { property: discProperty, mapping },
+          };
+        }
+      }
+    }
+
     // Collect all variant fields from the raw schema, generating synthetic
     // models/enums for inline definitions along the way.
     const variantFields = collectOneOfFields(rawSchema, model.name, collector);
@@ -467,6 +588,9 @@ export function enrichModelsFromSpec(models: Model[]): Model[] {
     values: e.values.map((v) => ({ value: v.value, description: v.description })),
   })) as Enum[];
 
-  // Append synthetic models to the output
-  return [...enriched2, ...collector.models];
+  // Append synthetic models, skipping those whose snake_case name collides
+  // with an existing model (prevents broken TypeAlias self-imports).
+  const existingSnakeNames = new Set(enriched2.map((m) => toSnakeCase(m.name)));
+  const filteredSynthetic = collector.models.filter((m) => !existingSnakeNames.has(toSnakeCase(m.name)));
+  return [...enriched2, ...filteredSynthetic];
 }

package/src/shared/naming-utils.ts

@@ -125,10 +125,46 @@ function startsWithVerb(desc: string): boolean {
   return VERB_STARTERS.has(firstWord);
 }
 
+/**
+ * Words beginning with a vowel letter but a consonant /j/ or /w/ sound —
+ * take "a", not "an".
+ */
+const CONSONANT_SOUND_INITIAL_VOWEL = new Set([
+  'user',
+  'unit',
+  'unique',
+  'united',
+  'universal',
+  'university',
+  'european',
+  'one',
+  'once',
+  'useful',
+  'used',
+  'usable',
+  'ubiquitous',
+]);
+
+/**
+ * Words beginning with a consonant letter but a vowel sound (silent h) —
+ * take "an", not "a".
+ */
+const VOWEL_SOUND_INITIAL_CONSONANT = new Set(['hour', 'honest', 'honor', 'honorable', 'heir']);
+
 /**
  * Select the correct indefinite article ("a" or "an") for a word.
+ *
+ * Matches English phonetics, not orthography: "a user" (consonant /j/ sound
+ * despite leading 'u'), "an hour" (vowel sound despite leading 'h'). Falls
+ * back to a vowel-letter regex for words not in either exception set.
  */
 export function articleFor(word: string): string {
+  const firstWord = word
+    .split(/\s+/)[0]
+    .toLowerCase()
+    .replace(/[^a-z]/g, '');
+  if (CONSONANT_SOUND_INITIAL_VOWEL.has(firstWord)) return 'a';
+  if (VOWEL_SOUND_INITIAL_CONSONANT.has(firstWord)) return 'an';
   return /^[aeiou]/i.test(word) ? 'an' : 'a';
 }
 

package/src/shared/non-spec-services.ts

@@ -18,6 +18,17 @@ export interface NonSpecService {
    * someone reading this file understands what the service does.
    */
   description: string;
+
+  /**
+   * When true, the generated Client struct includes a cached field for this
+   * service and a public accessor method — identical to spec-driven services.
+   * The hand-written file must export the service type (e.g. PasswordlessService)
+   * but should NOT define its own Client accessor (the generated code handles that).
+   *
+   * Defaults to false — most non-spec modules are standalone helpers, not
+   * Client-mounted services.
+   */
+  hasClientAccessor?: boolean;
 }
 
 /**
@@ -29,10 +40,12 @@ export const NON_SPEC_SERVICES: readonly NonSpecService[] = [
   {
     id: 'passwordless',
     description: 'Passwordless (magic-link) session endpoints, not yet in the OpenAPI spec.',
+    hasClientAccessor: true,
   },
   {
     id: 'vault',
     description: 'Vault KV storage, key operations, and client-side AES-GCM encrypt/decrypt.',
+    hasClientAccessor: true,
   },
   {
     id: 'webhook_verification',

package/src/shared/resolved-ops.ts

@@ -1,11 +1,42 @@
-import type { Operation, EmitterContext, Service, ResolvedOperation } from '@workos/oagen';
+import type { Operation, EmitterContext, Service, ResolvedOperation, Model, TypeRef } from '@workos/oagen';
 import { toPascalCase } from '@workos/oagen';
 
+/**
+ * Fail fast when two distinct paths in the same mount resolve to the same SDK
+ * method name. Emitters can sometimes paper over this with per-language
+ * deduplication, but manifests and cross-language parity become inconsistent.
+ */
+export function assertUniqueResolvedMethods(ctx: EmitterContext): void {
+  const seen = new Map<string, { path: string; httpMethod: string }>();
+
+  for (const resolved of ctx.resolvedOperations ?? []) {
+    const key = `${resolved.mountOn}.${resolved.methodName}`;
+    const current = {
+      path: resolved.operation.path,
+      httpMethod: resolved.operation.httpMethod.toUpperCase(),
+    };
+    const existing = seen.get(key);
+
+    if (existing && existing.path !== current.path) {
+      throw new Error(
+        `Resolved operation name collision for ${key}: ` +
+          `${existing.httpMethod} ${existing.path} conflicts with ${current.httpMethod} ${current.path}`,
+      );
+    }
+
+    if (!existing) {
+      seen.set(key, current);
+    }
+  }
+}
+
 /**
  * Build a lookup map from "METHOD /path" to ResolvedOperation.
  * Used by emitters to find the resolved method name for any IR operation.
  */
 export function buildResolvedLookup(ctx: EmitterContext): Map<string, ResolvedOperation> {
+  assertUniqueResolvedMethods(ctx);
+
   const map = new Map<string, ResolvedOperation>();
   for (const r of ctx.resolvedOperations ?? []) {
     const key = `${r.operation.httpMethod.toUpperCase()} ${r.operation.path}`;
@@ -107,3 +138,46 @@ export function buildHiddenParams(resolvedOp?: ResolvedOperation): Set<string> {
 export function hasHiddenParams(resolvedOp?: ResolvedOperation): boolean {
   return Object.keys(getOpDefaults(resolvedOp)).length > 0 || getOpInferFromClient(resolvedOp).length > 0;
 }
+
+// ---------------------------------------------------------------------------
+// Parameter group helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Collect all parameter names that belong to any mutually-exclusive parameter group.
+ * These params are serialized via group-level dispatch (e.g. applyToQuery, isinstance,
+ * sealed-class when, etc.) instead of individual struct/class fields.
+ */
+export function collectGroupedParamNames(op: Operation): Set<string> {
+  const names = new Set<string>();
+  for (const group of op.parameterGroups ?? []) {
+    for (const variant of group.variants) {
+      for (const param of variant.parameters) {
+        names.add(param.name);
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * Build a fallback map from request-body wire field name to TypeRef.
+ *
+ * Some parameter-group variants lose array/object fidelity in the IR and fall
+ * back to primitive strings. Cross-referencing the request body model restores
+ * the actual field type when the grouped params belong to the body.
+ */
+export function collectBodyFieldTypes(op: Operation, models: Model[]): Map<string, TypeRef> {
+  const fieldTypes = new Map<string, TypeRef>();
+  const reqBody = op.requestBody;
+  if (reqBody?.kind !== 'model') return fieldTypes;
+
+  const bodyModel = models.find((model) => model.name === reqBody.name);
+  if (!bodyModel) return fieldTypes;
+
+  for (const field of bodyModel.fields) {
+    fieldTypes.set(field.name, field.type);
+  }
+
+  return fieldTypes;
+}

package/test/dotnet/client.test.ts

@@ -76,8 +76,8 @@ describe('dotnet/client', () => {
     expect(content).not.toContain('SendAsync');
     expect(content).not.toContain('RequestAsync');
     expect(content).not.toContain('ApiBaseURL');
-    expect(content).not.toContain('AuthenticationError');
-    expect(content).not.toContain('RateLimitExceededError');
+    expect(content).not.toContain('AuthenticationException');
+    expect(content).not.toContain('RateLimitExceededException');
   });
 
   it('deduplicates services by mount target', () => {

package/test/dotnet/models.test.ts

@@ -80,18 +80,17 @@ describe('dotnet/models', () => {
     // Class definition
     expect(content).toContain('public class Organization');
 
-    // Required fields with JSON attributes
-    expect(content).toContain('[JsonProperty("id")]');
+    // Required fields — convention-based naming (no per-property JSON attributes)
     expect(content).toContain('public string Id');
-    expect(content).toContain('[JsonProperty("name")]');
     expect(content).toContain('public string Name');
+    expect(content).not.toContain('[JsonProperty("id")]');
+    expect(content).not.toContain('[STJS.JsonPropertyName(');
 
     // DateTime field
     expect(content).toContain('DateTimeOffset');
-    expect(content).toContain('[JsonProperty("created_at")]');
 
     // Optional/nullable field
-    expect(content).toContain('[JsonProperty("external_id")]');
+    expect(content).toContain('public string? ExternalId');
   });
 
   it('skips list wrapper and list metadata models', () => {
@@ -168,10 +167,9 @@ describe('dotnet/models', () => {
     expect(canonicalFile).toBeDefined();
     expect(canonicalFile.content).toContain('public class OrganizationDomain');
 
-    // Alias model should be a subclass of canonical
-    const aliasFile = files.find((f) => f.path.includes('OrganizationDomainStandAlone.cs'))!;
-    expect(aliasFile).toBeDefined();
-    expect(aliasFile.content).toContain('OrganizationDomain');
+    // Alias model should NOT be emitted — references are rewritten to the canonical
+    const aliasFile = files.find((f) => f.path.includes('OrganizationDomainStandAlone.cs'));
+    expect(aliasFile).toBeUndefined();
   });
 
   it('emits [System.Obsolete] for deprecated fields', () => {