@workos/oagen-emitters 0.3.0 → 0.4.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,3 +1,5 @@
+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';
@@ -85,6 +87,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);`);
   }
 
@@ -253,6 +264,45 @@ function generateServiceBarrels(spec: ApiSpec, ctx: EmitterContext): GeneratedFi
       addBaselineExports(ctx.apiSurface.interfaces);
       addBaselineExports(ctx.apiSurface.typeAliases);
       addBaselineExports(ctx.apiSurface.enums);
+
+      // Scan the target directory for interface files not captured by the
+      // api-surface (e.g., list wrappers, hand-written types).  Only add
+      // files whose exported symbols don't collide with symbols already
+      // claimed by another directory's barrel (TS2308 prevention).
+      if (ctx.targetDir) {
+        const interfacesDir = path.join(ctx.targetDir, 'src', dirName, 'interfaces');
+        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

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';