@workos/oagen-emitters 0.3.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 } from '@workos/oagen';
+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
@@ -103,13 +104,80 @@ function lookupRawSchema(name: string): Record<string, any> | null {
   return spec?.components?.schemas?.[name] ?? null;
 }
 
-/** Convert a raw OpenAPI type+format to an IR TypeRef. */
-function rawSchemaToTypeRef(schema: Record<string, any>): TypeRef {
+// ---------------------------------------------------------------------------
+// Synthetic model / enum collection
+// ---------------------------------------------------------------------------
+
+/**
+ * Accumulator for synthetic models and enums generated from inline
+ * definitions encountered during oneOf flattening.
+ */
+interface SyntheticCollector {
+  models: Model[];
+  enums: Array<{ name: string; values: Array<{ value: string; description?: string }> }>;
+  /** Track names already used to avoid duplicates. */
+  usedNames: Set<string>;
+}
+
+function createCollector(): SyntheticCollector {
+  return { models: [], enums: [], usedNames: new Set() };
+}
+
+/**
+ * Singularize a snake_case name for use as an array-item model name.
+ * `redirect_uris` -> `redirect_uri`, `scopes` -> `scope`.
+ */
+function singularizeSnake(name: string): string {
+  if (name.endsWith('ies') && name.length > 3) {
+    return `${name.slice(0, -3)}y`;
+  }
+  if (name.endsWith('s') && !name.endsWith('ss')) {
+    return name.slice(0, -1);
+  }
+  return name;
+}
+
+// ---------------------------------------------------------------------------
+// rawSchemaToTypeRef  -- with synthetic model/enum generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a raw OpenAPI type+format to an IR TypeRef.
+ *
+ * When `parentModelName` and `fieldName` are provided, inline objects and
+ * enums generate synthetic models/enums instead of degrading to `unknown`
+ * or `string`.
+ */
+function rawSchemaToTypeRef(
+  schema: Record<string, any>,
+  parentModelName?: string,
+  fName?: string,
+  collector?: SyntheticCollector,
+): TypeRef {
   if (schema.const !== undefined) {
     return { kind: 'literal', value: schema.const };
   }
+  if (schema.enum && collector && parentModelName && fName) {
+    // Generate a synthetic enum
+    const syntheticName = `${parentModelName}_${fName}`;
+    if (!collector.usedNames.has(syntheticName) && !collector.usedNames.has(toSnakeCase(syntheticName))) {
+      collector.usedNames.add(syntheticName);
+      collector.enums.push({
+        name: syntheticName,
+        values: (schema.enum as string[]).map((v: string) => ({
+          value: v,
+          description: undefined,
+        })),
+      });
+    }
+    return {
+      kind: 'enum',
+      name: syntheticName,
+      values: schema.enum as string[],
+    } as TypeRef;
+  }
   if (schema.enum) {
-    // Simple string enum -- represent as primitive string
+    // Simple string enum -- represent as primitive string (no collector)
     return { kind: 'primitive', type: 'string' } as TypeRef;
   }
   if (schema.$ref) {
@@ -127,11 +195,39 @@ function rawSchemaToTypeRef(schema: Record<string, any>): TypeRef {
   }
 
   let ref: TypeRef;
-  if (baseType === 'object' && schema.properties) {
-    // Inline object -- treat as unknown
+  if (baseType === 'object' && schema.properties && collector && parentModelName && fName) {
+    // Inline object -- generate a synthetic model
+    const syntheticName = `${parentModelName}_${fName}`;
+    if (!collector.usedNames.has(syntheticName) && !collector.usedNames.has(toSnakeCase(syntheticName))) {
+      collector.usedNames.add(syntheticName);
+      const fields: Field[] = [];
+      const requiredSet = new Set<string>(schema.required ?? []);
+      for (const [propName, propSchema] of Object.entries(schema.properties) as [string, Record<string, any>][]) {
+        fields.push({
+          name: propName,
+          type: rawSchemaToTypeRef(propSchema, syntheticName, propName, collector),
+          required: requiredSet.has(propName),
+          description: propSchema.description,
+          deprecated: propSchema.deprecated,
+        });
+      }
+      collector.models.push({
+        name: syntheticName,
+        fields,
+        description: schema.description,
+      } as Model);
+    }
+    ref = { kind: 'model', name: syntheticName } as TypeRef;
+  } else if (baseType === 'object' && schema.properties) {
+    // Inline object -- treat as unknown (no collector)
     ref = { kind: 'primitive', type: 'unknown' } as TypeRef;
   } else if (baseType === 'array' && schema.items) {
-    ref = { kind: 'array', items: rawSchemaToTypeRef(schema.items) } as TypeRef;
+    // For array items that are inline objects, use the singular field name
+    const itemFieldName = fName ? singularizeSnake(fName) : undefined;
+    ref = {
+      kind: 'array',
+      items: rawSchemaToTypeRef(schema.items, parentModelName, itemFieldName, collector),
+    } as TypeRef;
   } else if (baseType === 'boolean') {
     ref = { kind: 'primitive', type: 'boolean' } as TypeRef;
   } else if (baseType === 'integer' || baseType === 'number') {
@@ -151,13 +247,17 @@ function rawSchemaToTypeRef(schema: Record<string, any>): TypeRef {
  * All fields are returned as optional (not required) since they come from
  * oneOf variants where only one variant is active at a time.
  */
-function extractFieldsFromRawSchema(schema: Record<string, any>): Field[] {
+function extractFieldsFromRawSchema(
+  schema: Record<string, any>,
+  parentModelName?: string,
+  collector?: SyntheticCollector,
+): Field[] {
   const fields: Field[] = [];
   const props = schema.properties ?? {};
   for (const [name, propSchema] of Object.entries(props) as [string, Record<string, any>][]) {
     fields.push({
       name,
-      type: rawSchemaToTypeRef(propSchema),
+      type: rawSchemaToTypeRef(propSchema, parentModelName, name, collector),
       required: false, // All oneOf variant fields are optional
       description: propSchema.description,
       deprecated: propSchema.deprecated,
@@ -170,14 +270,18 @@ function extractFieldsFromRawSchema(schema: Record<string, any>): Field[] {
  * Recursively collect all fields from a oneOf schema, flattening nested
  * allOf+oneOf compositions. All fields are marked optional.
  */
-function collectOneOfFields(schema: Record<string, any>): Field[] {
+function collectOneOfFields(
+  schema: Record<string, any>,
+  parentModelName?: string,
+  collector?: SyntheticCollector,
+): Field[] {
   const allFields: Field[] = [];
   const seenFieldNames = new Set<string>();
 
   function walkSchema(s: Record<string, any>): void {
     // Direct properties
     if (s.properties) {
-      for (const f of extractFieldsFromRawSchema(s)) {
+      for (const f of extractFieldsFromRawSchema(s, parentModelName, collector)) {
         if (!seenFieldNames.has(f.name)) {
           seenFieldNames.add(f.name);
           allFields.push(f);
@@ -208,6 +312,179 @@ function collectOneOfFields(schema: Record<string, any>): Field[] {
   return allFields;
 }
 
+// ---------------------------------------------------------------------------
+// Array-item type upgrade
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if a TypeRef is `unknown` (the degraded type for inline objects).
+ */
+function isUnknownType(ref: TypeRef): boolean {
+  return ref.kind === 'primitive' && (ref as any).type === 'unknown';
+}
+
+/**
+ * If a field is an `array<unknown>` (or `nullable<array<unknown>>`) and the
+ * raw spec defines inline object/enum items, replace the item type with a
+ * synthetic model/enum. Returns the original field unchanged when no upgrade
+ * is needed.
+ */
+function upgradeArrayItemType(
+  field: Field,
+  rawSchema: Record<string, any>,
+  parentModelName: string,
+  collector: SyntheticCollector,
+): Field {
+  // Unwrap nullable to find the array
+  let arrayRef: TypeRef | null = null;
+  let isNullableWrapper = false;
+  if (field.type.kind === 'array') {
+    arrayRef = field.type;
+  } else if (field.type.kind === 'nullable' && field.type.inner.kind === 'array') {
+    arrayRef = field.type.inner;
+    isNullableWrapper = true;
+  }
+  if (!arrayRef || arrayRef.kind !== 'array') return field;
+  if (!isUnknownType(arrayRef.items)) return field;
+
+  // Look up the raw spec for this field
+  const rawProp = rawSchema.properties?.[field.name];
+  if (!rawProp) return field;
+
+  // Handle the case where the raw property is inside a nullable type array
+  let rawArraySchema = rawProp;
+  if (Array.isArray(rawProp.type)) {
+    const nonNull = rawProp.type.filter((t: string) => t !== 'null');
+    if (nonNull[0] === 'array') {
+      rawArraySchema = rawProp;
+    }
+  }
+  if (rawArraySchema.type !== 'array' && !(Array.isArray(rawArraySchema.type) && rawArraySchema.type.includes('array')))
+    return field;
+  if (!rawArraySchema.items) return field;
+
+  // Generate a proper TypeRef from the raw items schema
+  const itemFieldName = singularizeSnake(field.name);
+  const newItemRef = rawSchemaToTypeRef(rawArraySchema.items, parentModelName, itemFieldName, collector);
+  if (isUnknownType(newItemRef)) return field;
+
+  const newArrayRef: TypeRef = { kind: 'array', items: newItemRef } as TypeRef;
+  const newType: TypeRef = isNullableWrapper ? ({ kind: 'nullable', inner: newArrayRef } as TypeRef) : newArrayRef;
+
+  return { ...field, type: newType };
+}
+
+// ---------------------------------------------------------------------------
+// Module-level store for synthetic enums produced during enrichment.
+// Consumed by `getSyntheticEnums()` after `enrichModelsFromSpec` runs.
+// ---------------------------------------------------------------------------
+let _lastSyntheticEnums: Enum[] = [];
+
+/**
+ * Return the synthetic enums generated during the last call to
+ * `enrichModelsFromSpec`. Call this after enrichment to merge them into the
+ * enum generation phase.
+ */
+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.
  *
@@ -217,28 +494,64 @@ function collectOneOfFields(schema: Record<string, any>): Field[] {
  * For models whose raw spec schema has allOf containing a oneOf:
  *   - Collect the missing variant fields and add them as optional.
  *
+ * Inline objects and enums in oneOf branches are promoted to synthetic
+ * models/enums instead of degrading to `object` / `string`.
+ *
  * Returns a new array of enriched models (original models are not mutated).
+ * Synthetic enums are stored internally; retrieve them via `getSyntheticEnums()`.
  */
 export function enrichModelsFromSpec(models: Model[]): Model[] {
   const spec = loadRawSpec();
-  if (!spec) return models;
+  if (!spec) {
+    _lastSyntheticEnums = [];
+    return models;
+  }
 
-  return models.map((model) => {
+  const collector = createCollector();
+  // 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);
     if (!rawSchema) return 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;
 
-    // Collect all variant fields from the raw schema
-    const variantFields = collectOneOfFields(rawSchema);
+    // 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);
     if (variantFields.length === 0) return model;
 
     // Merge variant fields into the existing model, skipping duplicates
@@ -252,4 +565,32 @@ export function enrichModelsFromSpec(models: Model[]): Model[] {
       fields: [...model.fields, ...newFields],
     };
   });
+
+  // Second pass: fix array fields whose items degraded to `unknown` in the
+  // IR but are actually inline objects or enums in the raw spec.
+  const enriched2 = enriched.map((model) => {
+    const rawSchema = lookupRawSchema(model.name);
+    if (!rawSchema?.properties) return model;
+
+    let modified = false;
+    const newFields = model.fields.map((field) => {
+      const upgraded = upgradeArrayItemType(field, rawSchema, model.name, collector);
+      if (upgraded !== field) modified = true;
+      return upgraded;
+    });
+
+    return modified ? { ...model, fields: newFields } : model;
+  });
+
+  // Convert synthetic enum collector entries to proper Enum objects
+  _lastSyntheticEnums = collector.enums.map((e) => ({
+    name: e.name,
+    values: e.values.map((v) => ({ value: v.value, description: v.description })),
+  })) as Enum[];
+
+  // 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];
 }