@workos/oagen-emitters 0.3.0 → 0.5.0

package/src/kotlin/type-map.ts

@@ -0,0 +1,123 @@
+import type { TypeRef, PrimitiveType, UnionType } from '@workos/oagen';
+import { mapTypeRef as irMapTypeRef } from '@workos/oagen';
+import { className } from './naming.js';
+import { enumCanonicalMap } from './enums.js';
+
+/** Resolve an enum name through the canonical map (identity when no alias). */
+function resolveEnumName(name: string): string {
+  return className(enumCanonicalMap.get(name) ?? name);
+}
+
+/**
+ * Map an IR TypeRef to a non-nullable Kotlin type expression.
+ *
+ * Kotlin's type system marks nullability at use-sites (`T?`). Optional fields
+ * on generated models append `?` to the output of this function.
+ */
+export function mapTypeRef(ref: TypeRef): string {
+  return irMapTypeRef<string>(ref, {
+    primitive: mapPrimitive,
+    array: (_ref, items) => `List<${items}>`,
+    model: (r) => className(r.name),
+    enum: (r) => resolveEnumName(r.name),
+    union: (r, variants) => joinUnionVariants(r, variants),
+    nullable: (_ref, inner) => (inner.endsWith('?') ? inner : `${inner}?`),
+    literal: (r) => {
+      if (r.value === null) return 'Any?';
+      if (typeof r.value === 'string') return 'String';
+      if (typeof r.value === 'number') return Number.isInteger(r.value) ? 'Long' : 'Double';
+      if (typeof r.value === 'boolean') return 'Boolean';
+      return 'Any';
+    },
+    map: (_ref, value) => `Map<String, ${value}>`,
+  });
+}
+
+/**
+ * Map an IR TypeRef to a nullable Kotlin type expression (always appends `?`).
+ * Useful for optional fields on models / request options.
+ */
+export function mapTypeRefOptional(ref: TypeRef): string {
+  const baseType = mapTypeRef(ref);
+  return baseType.endsWith('?') ? baseType : `${baseType}?`;
+}
+
+/**
+ * Is the given IR TypeRef a primitive value? Useful when deciding whether a
+ * nullable field needs an explicit `= null` default.
+ */
+export function isValueTypeRef(ref: TypeRef): boolean {
+  if (ref.kind === 'enum') return true;
+  if (ref.kind === 'primitive') {
+    if (ref.format === 'date-time') return true;
+    switch (ref.type) {
+      case 'integer':
+      case 'number':
+      case 'boolean':
+        return true;
+      default:
+        return false;
+    }
+  }
+  return false;
+}
+
+function mapPrimitive(ref: PrimitiveType): string {
+  if (ref.format === 'binary') return 'ByteArray';
+  if (ref.format === 'int32') return 'Int';
+  if (ref.format === 'int64') return 'Long';
+  if (ref.format === 'date-time') return 'OffsetDateTime';
+  switch (ref.type) {
+    case 'string':
+      return 'String';
+    case 'integer':
+      return 'Long';
+    case 'number':
+      return 'Double';
+    case 'boolean':
+      return 'Boolean';
+    case 'unknown':
+      return 'Any';
+  }
+}
+
+/**
+ * Track discriminated unions so the model generator can emit the appropriate
+ * Jackson `@JsonTypeInfo` / `@JsonSubTypes` annotations on the sealed parent.
+ */
+export const discriminatedUnions = new Map<
+  string,
+  { property: string; mapping: Record<string, string>; variantTypes: string[] }
+>();
+
+function joinUnionVariants(ref: UnionType, variants: string[]): string {
+  if (ref.compositionKind === 'allOf') {
+    return variants[0] ?? 'Any';
+  }
+  const unique = [...new Set(variants)];
+  if (unique.length === 1) return unique[0];
+
+  if (ref.discriminator && ref.discriminator.mapping) {
+    const baseName = unique[0];
+    discriminatedUnions.set(baseName, {
+      property: ref.discriminator.property,
+      mapping: ref.discriminator.mapping,
+      variantTypes: unique,
+    });
+    // Use the base sealed type; Jackson @JsonTypeInfo handles variant selection.
+    return baseName;
+  }
+
+  // Non-discriminated unions fall back to the Kotlin top type. A generic
+  // AnyOf<> is planned for a future phase if emitter tests prove it necessary.
+  return 'Any';
+}
+
+/** Kotlin imports implied by a given type expression. Caller collects into a set. */
+export function implicitImportsFor(kotlinType: string): string[] {
+  const imports: string[] = [];
+  if (/\bOffsetDateTime\b/.test(kotlinType)) {
+    imports.push('java.time.OffsetDateTime');
+  }
+  return imports;
+}

package/src/kotlin/wrappers.ts

@@ -0,0 +1,168 @@
+import type { EmitterContext, ResolvedOperation, ResolvedWrapper, Parameter } from '@workos/oagen';
+import { className, propertyName, ktLiteral, clientFieldExpression, escapeReserved } from './naming.js';
+import { mapTypeRef, mapTypeRefOptional } from './type-map.js';
+import { resolveWrapperParams } from '../shared/wrapper-utils.js';
+import { sortPathParamsByTemplateOrder } from './resources.js';
+
+/**
+ * Emit Kotlin wrapper methods for a union-split operation. Each wrapper
+ * method takes only the fields it needs for its variant, fills in the
+ * operation-level defaults and client-inferred values, and posts to the
+ * underlying operation.
+ *
+ * Returns a list of lines (with leading indentation suitable for inclusion
+ * inside the service class body).
+ */
+export function generateWrapperMethods(resolvedOp: ResolvedOperation, ctx: EmitterContext): string[] {
+  if (!resolvedOp.wrappers || resolvedOp.wrappers.length === 0) return [];
+
+  const out: string[] = [];
+  for (const wrapper of resolvedOp.wrappers) {
+    if (out.length > 0) out.push('');
+    for (const line of emitWrapperMethod(resolvedOp, wrapper, ctx)) out.push(line);
+  }
+  return out;
+}
+
+function emitWrapperMethod(resolvedOp: ResolvedOperation, wrapper: ResolvedWrapper, ctx: EmitterContext): string[] {
+  const op = resolvedOp.operation;
+  const method = propertyName(wrapper.name);
+  const resolvedParams = resolveWrapperParams(wrapper, ctx);
+  const responseClass = wrapper.responseModelName ? className(wrapper.responseModelName) : null;
+
+  const pathParams = sortPathParamsByTemplateOrder(op);
+
+  const lines: string[] = [];
+
+  // Build KDoc from operation description + @param docs for each wrapper param.
+  const kdocLines: string[] = [];
+  const opDesc = (op.description ?? '').trim();
+  const wrapperHumanName = method.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
+  if (opDesc) {
+    kdocLines.push(opDesc.split('\n')[0]);
+  } else {
+    kdocLines.push(`${wrapperHumanName.charAt(0).toUpperCase()}${wrapperHumanName.slice(1)}.`);
+  }
+  const paramDocs: string[] = [];
+  for (const pp of pathParams) {
+    if (pp.description?.trim()) {
+      paramDocs.push(`@param ${propertyName(pp.name)} ${escapeKdoc(pp.description.split('\n')[0].trim())}`);
+    }
+  }
+  for (const rp of resolvedParams) {
+    const desc = rp.field?.description?.trim();
+    if (desc) {
+      paramDocs.push(`@param ${propertyName(rp.paramName)} ${escapeKdoc(desc.split('\n')[0])}`);
+    }
+  }
+  if (responseClass) {
+    paramDocs.push(`@return the ${responseClass}`);
+  }
+  if (paramDocs.length > 0 || kdocLines.length > 0) {
+    lines.push('  /**');
+    for (const l of kdocLines) lines.push(`   * ${escapeKdoc(l)}`);
+    if (paramDocs.length > 0) {
+      lines.push('   *');
+      for (const p of paramDocs) lines.push(`   * ${p}`);
+    }
+    lines.push('   */');
+  }
+
+  lines.push('  @JvmOverloads');
+
+  // Build the method parameter list: path params, wrapper params, requestOptions
+  const params: string[] = [];
+  for (const pp of pathParams) params.push(`    ${propertyName(pp.name)}: String`);
+  for (const rp of resolvedParams) {
+    const paramName = propertyName(rp.paramName);
+    const kotlinType = rp.field
+      ? rp.isOptional
+        ? mapTypeRefOptional(rp.field.type)
+        : mapTypeRef(rp.field.type)
+      : rp.isOptional
+        ? 'String?'
+        : 'String';
+    const trailer = rp.isOptional ? ' = null' : '';
+    params.push(`    ${paramName}: ${kotlinType}${trailer}`);
+  }
+  params.push('    requestOptions: RequestOptions? = null');
+
+  const returnClause = responseClass ? `: ${responseClass}` : '';
+  if (params.length === 1) {
+    const single = params[0].replace(/^\s+/, '');
+    lines.push(`  fun ${escapeReserved(method)}(${single})${returnClause} {`);
+  } else {
+    lines.push(`  fun ${escapeReserved(method)}(`);
+    for (let i = 0; i < params.length; i++) {
+      const suffix = i === params.length - 1 ? '' : ',';
+      lines.push(`${params[i]}${suffix}`);
+    }
+    lines.push(`  )${returnClause} {`);
+  }
+
+  // Build body using bodyOf() — consistent with non-wrapper methods.
+  // bodyOf() automatically drops null optional values.
+  const bodyEntries: string[] = [];
+  for (const rp of resolvedParams) {
+    const paramName = propertyName(rp.paramName);
+    bodyEntries.push(`      ${ktLiteral(rp.paramName)} to ${paramName}`);
+  }
+  for (const [k, v] of Object.entries(wrapper.defaults ?? {})) {
+    bodyEntries.push(`      ${ktLiteral(k)} to ${ktLiteral(v)}`);
+  }
+  for (const k of wrapper.inferFromClient ?? []) {
+    bodyEntries.push(`      ${ktLiteral(k)} to workos.${clientFieldExpression(k)}`);
+  }
+  if (bodyEntries.length > 0) {
+    lines.push(`    val body =`);
+    lines.push(`      bodyOf(`);
+    for (let i = 0; i < bodyEntries.length; i++) {
+      const sep = i === bodyEntries.length - 1 ? '' : ',';
+      lines.push(`  ${bodyEntries[i]}${sep}`);
+    }
+    lines.push(`      )`);
+  } else {
+    lines.push(`    val body = linkedMapOf<String, Any?>()`);
+  }
+
+  const pathExpr = buildPathExpr(op.path, pathParams);
+  const httpMethod = op.httpMethod.toUpperCase();
+
+  lines.push(`    val config =`);
+  lines.push(`      RequestConfig(`);
+  lines.push(`        method = ${ktLiteral(httpMethod)},`);
+  lines.push(`        path = ${pathExpr},`);
+  lines.push(`        body = body,`);
+  if (op.requestBodyEncoding === 'form-urlencoded') {
+    // Some ops (SSO token, User Management authenticate) are form-encoded.
+    // Rewrite as formBody mapping string→string instead of JSON body.
+    // Fallback: leave body as JSON — the API accepts JSON for these too.
+  }
+  lines.push(`        requestOptions = requestOptions`);
+  lines.push(`      )`);
+
+  if (responseClass) {
+    lines.push(`    return workos.baseClient.request(config, ${responseClass}::class.java)`);
+  } else {
+    lines.push(`    workos.baseClient.requestVoid(config)`);
+  }
+
+  lines.push('  }');
+  return lines;
+}
+
+function escapeKdoc(s: string): string {
+  return s.replace(/\*\//g, '*\u200b/');
+}
+
+function buildPathExpr(path: string, pathParams: Parameter[]): string {
+  if (pathParams.length === 0) return ktLiteral(path);
+  let result = path;
+  for (const pp of pathParams) {
+    const placeholder = `{${pp.name}}`;
+    const propName = propertyName(pp.name);
+    const replacement = /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(propName) ? `\$${propName}` : `\${${propName}}`;
+    result = result.replaceAll(placeholder, replacement);
+  }
+  return `"${result.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}

package/src/node/client.ts

@@ -1,5 +1,7 @@
+import fs from 'node:fs';
+import path from 'node:path';
 import type { ApiSpec, AuthScheme, EmitterContext, GeneratedFile, Service } from '@workos/oagen';
-import { collectReferencedNames } from '@workos/oagen';
+
 import { fileName, resolveServiceDir, servicePropertyName, resolveInterfaceName, wireInterfaceName } from './naming.js';
 import {
   docComment,
@@ -7,6 +9,7 @@ import {
   isServiceCoveredByExisting,
   isListMetadataModel,
   isListWrapperModel,
+  computeNonEventReachable,
 } from './utils.js';
 import { resolveResourceClassName } from './resources.js';
 
@@ -85,6 +88,15 @@ function generateWorkOSClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
     const resolvedName = resolveResourceClassName(service, ctx);
     const propName = servicePropertyName(resolvedName);
     if (existingProps.has(propName)) continue;
+    // Propagate `@deprecated` from the service class to the property so
+    // IDEs surface the strikethrough at `workos.xyz` access sites, not
+    // just when users `new Xyz()` directly.  TS's deprecation-lint reads
+    // the property JSDoc, not the underlying type declaration.
+    const classDeprecation = ctx.apiSurface?.classes?.[resolvedName]?.deprecationMessage;
+    if (classDeprecation !== undefined) {
+      const body = classDeprecation ? ` ${classDeprecation}` : '';
+      lines.push(`  /** @deprecated${body} */`);
+    }
     lines.push(`  readonly ${propName} = new ${resolvedName}(this);`);
   }
 
@@ -175,12 +187,12 @@ function generateServiceBarrels(spec: ApiSpec, ctx: EmitterContext): GeneratedFi
   // Models -> service directories
   // Skip list wrapper and list metadata models — they use shared List<T>/ListMetadata
   // from common utils, so no per-resource interface file is generated.
-  // Also skip unreachable models — oagen only passes service-referenced models
-  // to generateModels, so unreachable models have no interface file to export.
-  const barrelReachable = collectReferencedNames(spec.services, spec.models);
+  // Also skip unreachable models — use the same non-event reachability as model
+  // generation so every barrel entry has a corresponding generated file.
+  const barrelReachable = computeNonEventReachable(spec.services, spec.models);
   for (const model of spec.models) {
     if (isListMetadataModel(model) || isListWrapperModel(model)) continue;
-    if (!barrelReachable.models.has(model.name)) continue;
+    if (!barrelReachable.has(model.name)) continue;
     const service = modelToService.get(model.name);
     const dirName = resolveDir(service);
     if (!dirExports.has(dirName)) {
@@ -253,6 +265,71 @@ function generateServiceBarrels(spec: ApiSpec, ctx: EmitterContext): GeneratedFi
       addBaselineExports(ctx.apiSurface.interfaces);
       addBaselineExports(ctx.apiSurface.typeAliases);
       addBaselineExports(ctx.apiSurface.enums);
+
+      // Preserve existing barrel entries: read the current barrel from the
+      // target directory and keep every `export * from './<stem>'` whose
+      // corresponding file still exists on disk.  This prevents dropping
+      // hand-written types (e.g., Factor in multi-factor-auth) when a
+      // generated model in the same file causes a symbol collision.
+      if (ctx.targetDir) {
+        const interfacesDir = path.join(ctx.targetDir, 'src', dirName, 'interfaces');
+        try {
+          const barrelPath = path.join(interfacesDir, 'index.ts');
+          const barrelContent = fs.readFileSync(barrelPath, 'utf-8');
+          for (const line of barrelContent.split('\n')) {
+            const match = line.match(/^export \* from '\.\/(.*?)';?$/);
+            if (!match) continue;
+            const stem = match[1];
+            const exportLine = `export * from './${stem}';`;
+            if (exportSet.has(exportLine)) continue;
+            // Verify the referenced file still exists
+            const filePath = path.join(interfacesDir, `${stem}.ts`);
+            try {
+              fs.accessSync(filePath);
+              exportSet.add(exportLine);
+            } catch {
+              // File no longer exists — don't preserve stale entry
+            }
+          }
+        } catch {
+          // No existing barrel — nothing to preserve
+        }
+
+        // Also scan for NEW interface files not in the existing barrel or
+        // apiSurface (e.g., list wrappers, hand-written types added after
+        // the last generation).
+        const symbols = dirSymbols.get(dirName) ?? new Set<string>();
+        try {
+          for (const entry of fs.readdirSync(interfacesDir)) {
+            if (entry === 'index.ts') continue;
+            if (!entry.endsWith('.ts')) continue;
+            const stem = entry.replace(/\.ts$/, '');
+            const exportLine = `export * from './${stem}';`;
+            if (exportSet.has(exportLine)) continue;
+
+            // Extract exported symbol names from the file to check for conflicts
+            const content = fs.readFileSync(path.join(interfacesDir, entry), 'utf-8');
+            const exportedNames: string[] = [];
+            for (const m of content.matchAll(/export\s+(?:interface|type|enum|class|const|function)\s+(\w+)/g)) {
+              exportedNames.push(m[1]);
+            }
+
+            // Skip if any exported name collides with a symbol already
+            // claimed by any file (same or different directory)
+            const hasCollision = exportedNames.some((name) => globalExistingSymbols.has(name));
+            if (hasCollision) continue;
+
+            // Safe to add — register symbols and include in barrel
+            for (const name of exportedNames) {
+              symbols.add(name);
+              globalExistingSymbols.add(name);
+            }
+            exportSet.add(exportLine);
+          }
+        } catch {
+          // Directory doesn't exist in target — nothing to scan
+        }
+      }
     }
 
     // Deduplicate and sort
@@ -495,8 +572,8 @@ function generateBarrel(spec: ApiSpec, ctx: EmitterContext): GeneratedFile {
   // Filter to reachable models only: oagen's generateAllFiles passes only
   // service-referenced models to generateModels, so unreachable models
   // never get interface files.  Exporting them here would create broken imports.
-  const reachable = collectReferencedNames(spec.services, spec.models);
-  const unassignedModels = spec.models.filter((m) => !modelToService.has(m.name) && reachable.models.has(m.name));
+  const reachable = computeNonEventReachable(spec.services, spec.models);
+  const unassignedModels = spec.models.filter((m) => !modelToService.has(m.name) && reachable.has(m.name));
   const commonEnums = spec.enums.filter((e) => {
     const enumService = findEnumService(e.name, spec.services);
     return !enumService;

package/src/node/field-plan.ts

@@ -582,7 +582,6 @@ function emitAssignment(lhs: string, expr: string, accessExpr: string, guard: Gu
 interface SerializerContext {
   modelToService: Map<string, string>;
   resolveDir: (irService: string | undefined) => string;
-  useStringDates: boolean;
   dedup: Map<string, string>;
   skippedSerializeModels: Set<string>;
   ctx: EmitterContext;
@@ -614,31 +613,30 @@ export function buildSerializerImports(
     const depSerializerPath = `src/${depDir}/serializers/${fileName(dep)}.serializer.ts`;
     const depName = resolveInterfaceName(dep, sctx.ctx);
     const rel = relativeImport(serializerPath, depSerializerPath);
-    lines.push(`import { deserialize${depName}, serialize${depName} } from '${rel}';`);
+    // Check the canonical name for dedup'd models
+    const canon = sctx.dedup.get(dep);
+    const depSkipSerialize =
+      sctx.skippedSerializeModels.has(dep) || (canon != null && sctx.skippedSerializeModels.has(canon));
+    if (depSkipSerialize) {
+      lines.push(`import { deserialize${depName} } from '${rel}';`);
+    } else {
+      lines.push(`import { deserialize${depName}, serialize${depName} } from '${rel}';`);
+    }
   }
   lines.push('');
   return lines;
 }
 
 /** Build the set of field names where format conversion should be skipped. */
-export function buildSkipFormatFields(
-  model: Model,
-  useStringDates: boolean,
-  baselineDomain: BaselineInterface | undefined,
-): Set<string> {
+export function buildSkipFormatFields(model: Model, baselineDomain: BaselineInterface | undefined): Set<string> {
   const skipFormatFields = new Set<string>();
-  if (useStringDates) {
-    for (const field of model.fields) {
-      if (hasDateTimeConversion(field.type)) {
-        skipFormatFields.add(field.name);
-      }
-    }
-  }
   if (baselineDomain) {
     for (const field of model.fields) {
       if (skipFormatFields.has(field.name)) continue;
       const baselineField = baselineDomain.fields?.[fieldName(field.name)];
       if (baselineField && !baselineField.type.includes('Date') && hasFormatConversion(field.type)) {
+        // Always convert date-time fields to Date regardless of baseline
+        if (hasDateTimeConversion(field.type)) continue;
         skipFormatFields.add(field.name);
       }
     }

package/src/node/fixtures.ts

@@ -48,15 +48,51 @@ export function generateFixtures(
   const enumMap = new Map(spec.enums.map((e) => [e.name, e]));
   const files: { path: string; content: string }[] = [];
 
+  // Only generate fixtures for models reachable from non-event operations
+  const fixtureSeeds = new Set<string>();
+  for (const svc of spec.services) {
+    if (svc.name.toLowerCase() === 'events') continue;
+    for (const op of svc.operations) {
+      const collectFromRef = (t: import('@workos/oagen').TypeRef | undefined): void => {
+        if (!t) return;
+        if (t.kind === 'model') fixtureSeeds.add(t.name);
+        if (t.kind === 'array') collectFromRef(t.items);
+        if (t.kind === 'nullable') collectFromRef(t.inner);
+        if (t.kind === 'union') t.variants.forEach(collectFromRef);
+      };
+      collectFromRef(op.response);
+      collectFromRef(op.requestBody);
+      if (op.pagination?.itemType) collectFromRef(op.pagination.itemType);
+    }
+  }
+  const fixtureModelMap = new Map(spec.models.map((m: Model) => [m.name, m]));
+  const fixtureReachable = new Set<string>();
+  const fixtureQueue = [...fixtureSeeds];
+  while (fixtureQueue.length > 0) {
+    const name = fixtureQueue.pop()!;
+    if (fixtureReachable.has(name)) continue;
+    fixtureReachable.add(name);
+    const m = fixtureModelMap.get(name);
+    if (!m) continue;
+    for (const field of m.fields) {
+      const walk = (t: import('@workos/oagen').TypeRef): void => {
+        if (t.kind === 'model' && !fixtureReachable.has(t.name)) fixtureQueue.push(t.name);
+        if (t.kind === 'array') walk(t.items);
+        if (t.kind === 'nullable') walk(t.inner);
+        if (t.kind === 'union') t.variants.forEach(walk);
+      };
+      walk(field.type);
+    }
+  }
   const seenFixturePaths = new Set<string>();
   for (const model of spec.models) {
-    // Skip redundant list-metadata and list-wrapper models (handled by shared types)
+    if (!fixtureReachable.has(model.name)) continue;
     if (isListMetadataModel(model)) continue;
     if (isListWrapperModel(model)) continue;
 
     const service = modelToService.get(model.name);
     const dirName = resolveDir(service);
-    const fixturePath = `src/${dirName}/fixtures/${fileName(model.name)}.fixture.json`;
+    const fixturePath = `src/${dirName}/fixtures/${fileName(model.name)}.json`;
 
     // After noise suffix stripping, multiple models may resolve to the same
     // fixture path (e.g., OrganizationDto and Organization).  Skip duplicates.
@@ -94,7 +130,7 @@ export function generateFixtures(
             },
           };
           files.push({
-            path: `src/${serviceDir}/fixtures/list-${fileName(itemModel.name)}.fixture.json`,
+            path: `src/${serviceDir}/fixtures/list-${fileName(itemModel.name)}.json`,
             content: JSON.stringify(listFixture, null, 2),
           });
         }

package/src/node/index.ts

@@ -16,6 +16,7 @@ import { generateEnums } from './enums.js';
 import { generateResources } from './resources.js';
 import { generateClient } from './client.js';
 import { generateErrors } from './errors.js';
+
 import { generateTests } from './tests.js';
 import { generateManifest } from './manifest.js';