@workos/oagen-emitters 0.8.1 → 0.9.0

package/dist/plugin.mjs

@@ -1,2 +1,2 @@
-import { t as workosEmittersPlugin } from "./plugin-DOE0FqrZ.mjs";
+import { t as workosEmittersPlugin } from "./plugin-Dh9JSScr.mjs";
 export { workosEmittersPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos/oagen-emitters",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "WorkOS' oagen emitters",
   "license": "MIT",
   "author": "WorkOS",
@@ -42,8 +42,8 @@
     "@commitlint/config-conventional": "^20.5.3",
     "@types/node": "^25.6.0",
     "husky": "^9.1.7",
-    "oxfmt": "^0.47.0",
-    "oxlint": "^1.62.0",
+    "oxfmt": "^0.48.0",
+    "oxlint": "^1.63.0",
     "prettier": "^3.8.3",
     "tsdown": "^0.21.10",
     "tsx": "^4.21.0",
@@ -54,6 +54,6 @@
     "node": ">=24.10.0"
   },
   "dependencies": {
-    "@workos/oagen": "^0.17.0"
+    "@workos/oagen": "^0.17.2"
   }
 }

package/src/kotlin/client.ts

@@ -12,32 +12,38 @@ const KOTLIN_SRC_PREFIX = 'src/main/kotlin/';
  * contains a `WorkOS` class stub with only these properties — the oagen
  * merger deep-merges them into the existing hand-written `WorkOS.kt`.
  *
- * Accessors use fully-qualified type names so the merger doesn't need to
- * inject imports into the hand-written file.
+ * Each referenced service class is hoisted into a top-level `import` so the
+ * accessor bodies use the short class name. The live `WorkOS.kt` is marked
+ * `@oagen-ignore-file` and won't be regenerated, but the emitter still emits
+ * the cleaner shape so future regenerations don't reintroduce the FQN noise.
  */
 export function generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
   const targets = deduplicateByMount(spec.services, ctx);
   if (targets.length === 0) return [];
 
+  const imports = new Set<string>();
   const accessorLines: string[] = [];
   for (const mount of targets) {
     const apiCls = apiClassName(mount);
     const fqn = `com.workos.${packageSegment(mount)}.${apiCls}`;
+    imports.add(fqn);
     const prop = servicePropertyName(mount);
     accessorLines.push('');
-    accessorLines.push(`  /** Lazily-constructed [${fqn}] accessor for this [WorkOS] client. */`);
-    accessorLines.push(`  val ${prop}: ${fqn}`);
+    accessorLines.push(`  /** Lazily-constructed [${apiCls}] accessor for this [WorkOS] client. */`);
+    accessorLines.push(`  val ${prop}: ${apiCls}`);
     accessorLines.push('    get() =');
     accessorLines.push('      service(');
-    accessorLines.push(`        ${fqn}::class`);
+    accessorLines.push(`        ${apiCls}::class`);
     accessorLines.push('      ) {');
-    accessorLines.push(`        ${fqn}(this)`);
+    accessorLines.push(`        ${apiCls}(this)`);
     accessorLines.push('      }');
   }
 
   const lines: string[] = [];
   lines.push('package com.workos');
   lines.push('');
+  for (const imp of [...imports].sort()) lines.push(`import ${imp}`);
+  if (imports.size > 0) lines.push('');
   lines.push('open class WorkOS {');
   for (const line of accessorLines) lines.push(line);
   lines.push('}');

package/src/kotlin/enums.ts

@@ -143,15 +143,26 @@ export function generateEnums(enums: Enum[], _ctx: EmitterContext): GeneratedFil
       members.push(`  ${memberName}(${ktStringLiteral(wire)})`);
     }
 
+    // Track whether we are currently in a doc block leading up to the next
+    // enum value declaration. When the upcoming case has KDoc, insert a blank
+    // line before the doc comment for visual separation (skip for the very
+    // first case so we don't open the block with a blank).
+    let firstValueEmitted = false;
     for (let i = 0; i < members.length; i++) {
       const isLast = i === members.length - 1;
       const line = members[i];
       const trimmedStart = line.trimStart();
-      if (trimmedStart.startsWith('/**') || trimmedStart.startsWith('@')) {
+      const isDocStart = trimmedStart.startsWith('/**');
+      const isAnnotation = trimmedStart.startsWith('@');
+      if (isDocStart && firstValueEmitted) {
+        lines.push('');
+      }
+      if (isDocStart || isAnnotation) {
         lines.push(line);
         continue;
       }
       lines.push(isLast ? line : `${line},`);
+      firstValueEmitted = true;
     }
 
     lines.push('}');

package/src/kotlin/index.ts

@@ -93,15 +93,17 @@ export const kotlinEmitter: Emitter = {
   },
 
   formatCommand(targetDir: string): FormatCommand | null {
-    // ktlint enforces a 140-char max line length that cannot be auto-corrected
-    // by the Gradle plugin alone, but `./gradlew ktlintFormat` fixes most
-    // violations (trailing whitespace, import ordering, etc.) across all
-    // generated files. The file list appended by oagen is ignored — Gradle
-    // reformats the whole source set.
+    // `./gradlew ktlintFormat` fixes whitespace, import ordering, and most
+    // wrapping/line-length violations across the whole source set. The file
+    // list appended by oagen is ignored — Gradle reformats every Kotlin
+    // file. oagen's writer already runs the spawned process with
+    // `cwd: targetDir`, so we don't `cd` again (an additional `cd` re-resolves
+    // a relative `targetDir` against itself and silently lands in a missing
+    // directory, which is what was causing this command to no-op in practice).
     if (!fs.existsSync(path.join(targetDir, 'gradlew'))) return null;
     return {
       cmd: 'bash',
-      args: ['-c', `cd ${JSON.stringify(targetDir)} && ./gradlew ktlintFormat --quiet 2>/dev/null; true`, '--'],
+      args: ['-c', './gradlew ktlintFormat --quiet >/dev/null 2>&1; true'],
     };
   },
 };

package/src/kotlin/models.ts

@@ -8,6 +8,36 @@ const KOTLIN_SRC_PREFIX = 'src/main/kotlin/';
 const MODELS_PACKAGE = 'com.workos.models';
 const MODELS_DIR = 'com/workos/models';
 
+/**
+ * Some specs leave string fields without `format: date-time` even though the
+ * description (or the example) makes clear they carry an ISO-8601 timestamp.
+ * Detect that here so we can promote the type to `OffsetDateTime` in the
+ * Kotlin output.
+ */
+const ISO_8601_DESCRIPTION_RE = /\bISO[-_ ]?8601\b/i;
+
+function looksLikeIso8601String(description: string | undefined): boolean {
+  if (!description) return false;
+  return ISO_8601_DESCRIPTION_RE.test(description);
+}
+
+function promoteIso8601TypeRef(type: TypeRef, description: string | undefined): TypeRef {
+  if (!looksLikeIso8601String(description)) return type;
+  const promote = (t: TypeRef): TypeRef => {
+    if (t.kind === 'primitive' && t.type === 'string' && !t.format) {
+      return { kind: 'primitive', type: 'string', format: 'date-time' };
+    }
+    if (t.kind === 'nullable') return { kind: 'nullable', inner: promote(t.inner) };
+    return t;
+  };
+  return promote(type);
+}
+
+function promoteFieldType(f: Field): Field {
+  const promoted = promoteIso8601TypeRef(f.type, f.description);
+  return promoted === f.type ? f : { ...f, type: promoted };
+}
+
 /**
  * Generate Kotlin `data class` models. Each model becomes a separate `.kt`
  * file under `com.workos.models`. Discriminated unions emit a sealed class
@@ -174,6 +204,12 @@ function emitDataClass(model: Model): GeneratedFile {
     for (let i = 0; i < rendered.length; i++) {
       const suffix = i === rendered.length - 1 ? '' : ',';
       lines.push(`${rendered[i]}${suffix}`);
+      // Visually separate properties: KDoc + annotations for the next field
+      // get their own paragraph. Kotlin requires the comma to come *before*
+      // the blank line; we already appended it above.
+      if (i < rendered.length - 1) {
+        lines.push('');
+      }
     }
 
     lines.push(`)${implClause}`);
@@ -197,7 +233,32 @@ function emitSealedUnion(
   lines.push('import com.fasterxml.jackson.annotation.JsonSubTypes');
   lines.push('import com.fasterxml.jackson.annotation.JsonTypeInfo');
   lines.push('');
-  appendKdoc(lines, `Discriminated union over ${typeName} variants. Selected by \`${disc.property}\`.`, 0);
+  // KDoc with worked Kotlin + Java consumption examples. These unions are
+  // returned by Jackson; callers branch on the concrete subtype to access
+  // variant-specific data.
+  const exampleVariantWire = Object.keys(disc.mapping)[0];
+  const exampleVariantType = exampleVariantWire ? className(disc.mapping[exampleVariantWire]) : null;
+  lines.push('/**');
+  lines.push(` * Discriminated union over ${typeName} variants. Selected by \`${disc.property}\`.`);
+  if (exampleVariantType) {
+    lines.push(' *');
+    lines.push(' * Usage from Kotlin:');
+    lines.push(' * ```kotlin');
+    lines.push(` * when (val v: ${typeName} = receivedFromApi()) {`);
+    lines.push(` *   is ${exampleVariantType} -> handle(v)`);
+    lines.push(' *   else -> handleOther(v)');
+    lines.push(' * }');
+    lines.push(' * ```');
+    lines.push(' *');
+    lines.push(' * Usage from Java:');
+    lines.push(' * ```java');
+    lines.push(` * ${typeName} v = receivedFromApi();`);
+    lines.push(` * if (v instanceof ${exampleVariantType}) {`);
+    lines.push(` *     handle((${exampleVariantType}) v);`);
+    lines.push(' * }');
+    lines.push(' * ```');
+  }
+  lines.push(' */');
   lines.push('@JsonTypeInfo(');
   lines.push('  use = JsonTypeInfo.Id.NAME,');
   lines.push('  include = JsonTypeInfo.As.EXISTING_PROPERTY,');
@@ -295,7 +356,8 @@ function renderFields(fields: Field[], overrideFields: Set<string> = new Set()):
   const seen = new Set<string>();
   const lines: string[] = [];
 
-  for (const field of fields) {
+  for (const rawField of fields) {
+    const field = promoteFieldType(rawField);
     const kotlinName = propertyName(field.name);
     if (seen.has(kotlinName)) continue;
     seen.add(kotlinName);
@@ -329,7 +391,7 @@ function renderFields(fields: Field[], overrideFields: Set<string> = new Set()):
     // isEmailVerified(), etc.) for Java callers — matching the accessor
     // convention used by Stripe, AWS SDK v2, and Twilio.
     annotations.push(`@JsonProperty(${ktStringLiteral(field.name)})`);
-    if (field.deprecated) annotations.push('@Deprecated("Deprecated field")');
+    if (field.deprecated) annotations.push(buildDeprecatedAnnotation(field.description));
 
     const paramParts: string[] = [];
     if (field.description?.trim()) {
@@ -372,6 +434,38 @@ function collapseFieldEntries(rawLines: string[]): string[] {
   return entries;
 }
 
+/**
+ * Pull the most useful free-form deprecation hint out of a field description
+ * and lift it into the `@Deprecated(...)` message argument. Most WorkOS
+ * deprecations are written as a description that begins with "Deprecated"
+ * (e.g. "Deprecated. Use `domain_data` instead."). When the description
+ * doesn't carry a hint we fall back to a short, self-explanatory message
+ * rather than the generic "Deprecated field" placeholder.
+ */
+function deprecationMessageFromDescription(description: string | undefined): string {
+  if (!description) return 'Deprecated.';
+  const firstLine = description
+    .split('\n')
+    .map((l) => l.trim())
+    .find((l) => l.length > 0);
+  if (!firstLine) return 'Deprecated.';
+  // Trim trailing whitespace and collapse internal whitespace runs so the
+  // annotation argument stays on one line.
+  const collapsed = firstLine.replace(/\s+/g, ' ').trim();
+  if (collapsed.length === 0) return 'Deprecated.';
+  // Only lift the description when it actually carries a deprecation hint
+  // (e.g. "Deprecated. Use `domain_data` instead.") — many fields keep their
+  // forward-looking description verbatim, which would be misleading inside
+  // an `@Deprecated(...)` argument.
+  if (/\bdeprecat/i.test(collapsed)) return collapsed;
+  return 'Deprecated.';
+}
+
+function buildDeprecatedAnnotation(description: string | undefined): string {
+  const message = deprecationMessageFromDescription(description);
+  return `@Deprecated(${ktStringLiteral(message)})`;
+}
+
 /**
  * If the TypeRef is a literal (const) with a string, number, or boolean value,
  * return the Kotlin expression for that default. Otherwise return null.
@@ -388,7 +482,8 @@ function collectImports(fields: Field[]): Set<string> {
   const imports = new Set<string>();
   if (fields.length === 0) return imports;
   imports.add('com.fasterxml.jackson.annotation.JsonProperty');
-  for (const field of fields) {
+  for (const rawField of fields) {
+    const field = promoteFieldType(rawField);
     const mapped = mapTypeRef(field.type);
     if (/\bOffsetDateTime\b/.test(mapped)) imports.add('java.time.OffsetDateTime');
     for (const enumName of collectEnumNames(field.type)) {

package/src/kotlin/naming.ts

@@ -1,16 +1,36 @@
-import type { Operation, Service, EmitterContext } from '@workos/oagen';
+import type { Operation, Service, EmitterContext, TypeRef } from '@workos/oagen';
 import { toPascalCase, toCamelCase, toSnakeCase } from '@workos/oagen';
 import { buildResolvedLookup, lookupMethodName, getMountTarget } from '../shared/resolved-ops.js';
 import { stripUrnPrefix } from '../shared/naming-utils.js';
 
+/**
+ * Acronyms that should appear fully uppercase in PascalCase identifiers.
+ * `toPascalCase` would otherwise titlecase them (e.g. `Sso`, `Pkce`, `Mfa`).
+ * Both [className] and [apiClassName] consult this list so model and service
+ * class names stay consistent (e.g. `SsoConnection` -> `SSOConnection`).
+ */
+const PASCAL_ACRONYMS = ['SSO', 'PKCE', 'MFA'];
+
+function uppercaseAcronyms(pascal: string): string {
+  let result = pascal;
+  for (const acronym of PASCAL_ACRONYMS) {
+    // Match the titlecased form (e.g. `Sso`) at any position where it stands
+    // as a complete word (followed by an uppercase letter, digit, or end).
+    const titled = acronym.charAt(0) + acronym.slice(1).toLowerCase();
+    const re = new RegExp(`${titled}(?=[A-Z0-9]|$)`, 'g');
+    result = result.replace(re, acronym);
+  }
+  return result;
+}
+
 /** PascalCase class/type name. */
 export function className(name: string): string {
-  return toPascalCase(stripUrnPrefix(name));
+  return uppercaseAcronyms(toPascalCase(stripUrnPrefix(name)));
 }
 
 /** PascalCase file name (matches the primary class). */
 export function fileName(name: string): string {
-  return toPascalCase(stripUrnPrefix(name));
+  return uppercaseAcronyms(toPascalCase(stripUrnPrefix(name)));
 }
 
 /** snake_case file name for fixtures/test data. */
@@ -50,7 +70,6 @@ export function packageSegment(name: string): string {
 
 /** Kotlin service class name for a mount group (e.g., `Organizations`). */
 export function apiClassName(name: string): string {
-  if (className(name) === 'SSO') return 'Sso';
   return className(name);
 }
 
@@ -227,3 +246,38 @@ export function humanize(name: string): string {
     .replace(/([a-z])([A-Z])/g, '$1 $2')
     .toLowerCase();
 }
+
+/**
+ * If the parameter is typed as an enum and its description is long enough
+ * that repeating it across every method's KDoc adds noise, return a short
+ * description that defers to the enum's own KDoc with a `See [EnumName].`
+ * reference. Otherwise return null and the caller keeps the spec text.
+ *
+ * Currently only `PaginationOrder` is shortened — the SSO/MFA/etc. enums
+ * have brief descriptions already. Generalize when other long-description
+ * enums appear in the spec.
+ */
+const LONG_ENUM_DESC_THRESHOLD = 120;
+
+export function maybeShortenEnumParamDescription(
+  type: TypeRef | undefined,
+  description: string | undefined,
+): { description: string; enumRef: string } | null {
+  if (!type || !description) return null;
+  const enumName = extractEnumName(type);
+  if (!enumName) return null;
+  if (description.length <= LONG_ENUM_DESC_THRESHOLD) return null;
+  // Only special-case PaginationOrder for now; other enums keep their
+  // descriptions verbatim so we don't over-trim until a pattern emerges.
+  if (className(enumName) !== 'PaginationOrder') return null;
+  return {
+    description: `the order to return records in. See [${className(enumName)}].`,
+    enumRef: className(enumName),
+  };
+}
+
+function extractEnumName(type: TypeRef): string | null {
+  if (type.kind === 'enum') return type.name;
+  if (type.kind === 'nullable') return extractEnumName(type.inner);
+  return null;
+}