@workos/oagen-emitters 0.3.0 → 0.4.0

package/src/dotnet/type-map.ts

@@ -0,0 +1,201 @@
+import type { TypeRef, PrimitiveType, UnionType } from '@workos/oagen';
+import { mapTypeRef as irMapTypeRef } from '@workos/oagen';
+import { className } from './naming.js';
+
+/** Known C# value types that need `?` for nullable. */
+const VALUE_TYPES = new Set(['int', 'long', 'double', 'bool', 'float', 'decimal', 'byte', 'short', 'DateTimeOffset']);
+
+/**
+ * Module-level alias map for structurally-identical enums. Populated by
+ * `setEnumAliases` from the current spec's enum list; consulted by
+ * `mapTypeRef` so that every reference to a duplicate enum resolves to the
+ * canonical name. C# has no first-class type alias for enums, so dedup must
+ * happen at reference-rewrite time rather than via a runtime alias.
+ */
+const enumAliases = new Map<string, string>();
+
+/**
+ * Names of enums that resolve to a single wire value and should therefore be
+ * mapped to C# `string` at reference sites (the owning property emits a
+ * const initializer). Populated by `setSingleValueEnumNames`.
+ */
+const singleValueEnumNames = new Set<string>();
+
+/** Replace the current enum-alias map. Safe to call more than once. */
+export function setEnumAliases(aliases: Map<string, string>): void {
+  enumAliases.clear();
+  for (const [k, v] of aliases) enumAliases.set(k, v);
+}
+
+/** Replace the set of enum names that are single-value discriminator stand-ins. */
+export function setSingleValueEnumNames(names: Iterable<string>): void {
+  singleValueEnumNames.clear();
+  for (const n of names) singleValueEnumNames.add(n);
+}
+
+/** Resolve an enum reference name to its canonical form. */
+export function resolveEnumTypeName(name: string): string {
+  return enumAliases.get(name) ?? name;
+}
+
+/**
+ * Map an IR TypeRef to a C# type string.
+ */
+export function mapTypeRef(ref: TypeRef): string {
+  return irMapTypeRef<string>(ref, {
+    primitive: mapPrimitive,
+    array: (_ref, items) => `List<${items}>`,
+    model: (r) => className(r.name),
+    enum: (r) => {
+      // Single-value enums (discriminator consts in disguise) map to `string`
+      // so the caller can't misuse a public one-member enum type. The
+      // owning property emits a const initializer separately.
+      if ((r.values?.length ?? 0) === 1) return 'string';
+      if (singleValueEnumNames.has(r.name)) return 'string';
+      return className(resolveEnumTypeName(r.name));
+    },
+    union: (_r, variants) => joinUnionVariants(_r, variants),
+    nullable: (_ref, inner) => {
+      // With <Nullable>enable</Nullable>, all nullable types need `?`
+      if (inner.endsWith('?')) return inner; // already nullable (e.g., nested nullable)
+      return `${inner}?`;
+    },
+    literal: (r) => {
+      if (r.value === null) return 'object';
+      if (typeof r.value === 'string') return 'string';
+      if (typeof r.value === 'number') return Number.isInteger(r.value) ? 'int' : 'double';
+      if (typeof r.value === 'boolean') return 'bool';
+      return 'object';
+    },
+    map: (_ref, value) => `Dictionary<string, ${value}>`,
+  });
+}
+
+/**
+ * Map an IR TypeRef to a C# type string, making optional fields nullable.
+ * For value types, appends `?`. For reference types, returns as-is.
+ */
+export function mapTypeRefOptional(ref: TypeRef): string {
+  const baseType = mapTypeRef(ref);
+  if (isValueType(baseType)) return `${baseType}?`;
+  return baseType;
+}
+
+/**
+ * Check if a C# type is a value type (needs ? for nullable).
+ */
+export function isValueType(csType: string): boolean {
+  // Strip trailing ? if present
+  const bare = csType.endsWith('?') ? csType.slice(0, -1) : csType;
+  if (VALUE_TYPES.has(bare)) return true;
+  // Enums are value types, but we can't detect them purely from the type string.
+  // The caller should handle enum nullability explicitly when needed.
+  return false;
+}
+
+/**
+ * Check if an IR TypeRef maps to a C# value type.
+ */
+export function isValueTypeRef(ref: TypeRef): boolean {
+  if (ref.kind === 'enum') return true;
+  if (ref.kind === 'primitive') {
+    // DateTimeOffset is a value type (struct)
+    if (ref.format === 'date-time') return true;
+    switch (ref.type) {
+      case 'integer':
+      case 'number':
+      case 'boolean':
+        return true;
+      default:
+        return false;
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether a TypeRef directly names an enum (no nullable wrapper).
+ * Used to detect required enum request fields that must not silently serialize
+ * their default Unknown sentinel.
+ */
+export function isEnumRef(ref: TypeRef): boolean {
+  return ref.kind === 'enum';
+}
+
+/**
+ * Emit JSON attributes for a request-side property. When `isRequiredEnum` is
+ * true, configure both serializers to skip the field when its value equals the
+ * enum default (0 = Unknown sentinel). This converts "unset required enum"
+ * from a silent `"unknown"` wire value into a clean omission so the API
+ * returns a clear `missing required field` error instead of a confusing 422.
+ */
+export function emitJsonPropertyAttributes(wireName: string, options: { isRequiredEnum?: boolean } = {}): string[] {
+  if (options.isRequiredEnum) {
+    return [
+      `        [JsonProperty("${wireName}", DefaultValueHandling = DefaultValueHandling.Ignore)]`,
+      `        [STJS.JsonPropertyName("${wireName}")]`,
+      `        [STJS.JsonIgnore(Condition = STJS.JsonIgnoreCondition.WhenWritingDefault)]`,
+    ];
+  }
+  return [`        [JsonProperty("${wireName}")]`, `        [STJS.JsonPropertyName("${wireName}")]`];
+}
+
+function mapPrimitive(ref: PrimitiveType): string {
+  if (ref.format === 'binary') return 'byte[]';
+  if (ref.format === 'int32') return 'int';
+  if (ref.format === 'int64') return 'long';
+  if (ref.format === 'date-time') return 'DateTimeOffset';
+  switch (ref.type) {
+    case 'string':
+      return 'string';
+    case 'integer':
+      return 'long';
+    case 'number':
+      return 'double';
+    case 'boolean':
+      return 'bool';
+    case 'unknown':
+      return 'object';
+  }
+}
+
+/**
+ * Track discriminated unions for downstream model generation.
+ * Key = generated base type name, Value = discriminator info.
+ */
+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] ?? 'object';
+  }
+  const unique = [...new Set(variants)];
+  if (unique.length === 1) return unique[0];
+
+  // Discriminated union: register for converter generation and return first variant as base
+  if (_ref.discriminator && _ref.discriminator.mapping) {
+    const baseName = unique[0];
+    discriminatedUnions.set(baseName, {
+      property: _ref.discriminator.property,
+      mapping: _ref.discriminator.mapping,
+      variantTypes: unique,
+    });
+    // Use object with JsonConverter for discriminated unions since
+    // AnyOf<> doesn't support discriminator-based deserialization
+    return 'object';
+  }
+
+  if (unique.length >= 2 && unique.length <= 3) return `AnyOf<${unique.join(', ')}>`;
+  // AnyOf only supports arity 2 and 3. Higher-arity unions collapse to
+  // `object`, losing type information. Warn so the author knows the spec
+  // outgrew the runtime support instead of silently degrading.
+  if (unique.length >= 4) {
+    console.warn(
+      `[oagen:dotnet] Union with ${unique.length} variants exceeds AnyOf<T1,T2,T3> arity; falling back to object. Variants: ${unique.join(', ')}`,
+    );
+  }
+  return 'object';
+}

package/src/dotnet/wrappers.ts

@@ -0,0 +1,186 @@
+import type { EmitterContext, ResolvedOperation, ResolvedWrapper } from '@workos/oagen';
+import {
+  className as csClassName,
+  fieldName as csFieldName,
+  methodName as csMethodName,
+  localName,
+  csLiteral,
+  clientFieldExpression,
+  httpMethodHelperName,
+  escapeXml,
+  emitXmlDoc,
+  humanize,
+} from './naming.js';
+import { sortPathParamsByTemplateOrder } from './resources.js';
+import { resolveWrapperParams, formatWrapperDescription, type ResolvedWrapperParam } from '../shared/wrapper-utils.js';
+import { mapTypeRef, isValueTypeRef, isEnumRef, emitJsonPropertyAttributes } from './type-map.js';
+
+/**
+ * Generate C# wrapper method lines for union split operations.
+ */
+export function generateWrapperMethods(
+  _serviceType: string,
+  resolvedOp: ResolvedOperation,
+  ctx: EmitterContext,
+): string[] {
+  if (!resolvedOp.wrappers || resolvedOp.wrappers.length === 0) return [];
+
+  const lines: string[] = [];
+
+  for (const wrapper of resolvedOp.wrappers) {
+    const wrapperParams = resolveWrapperParams(wrapper, ctx);
+    lines.push('');
+    emitWrapperMethod(lines, resolvedOp, wrapper, wrapperParams, ctx);
+  }
+
+  return lines;
+}
+
+function emitWrapperMethod(
+  lines: string[],
+  resolvedOp: ResolvedOperation,
+  wrapper: ResolvedWrapper,
+  _wrapperParams: ResolvedWrapperParam[],
+  _ctx: EmitterContext,
+): void {
+  const op = resolvedOp.operation;
+  const method = csMethodName(wrapper.name);
+  const optionsClass = `${method}Options`;
+  const responseType = wrapper.responseModelName ? csClassName(wrapper.responseModelName) : null;
+
+  // XML doc
+  lines.push(`        /// <summary>${formatWrapperDescription(wrapper.name)}.</summary>`);
+  for (const p of sortPathParamsByTemplateOrder(op)) {
+    const paramDesc = p.description ? escapeXml(p.description) : `The ${humanize(p.name)}.`;
+    lines.push(`        /// <param name="${localName(p.name)}">${paramDesc}</param>`);
+  }
+  lines.push(`        /// <param name="options">Request options.</param>`);
+  lines.push(`        /// <param name="requestOptions">Per-request configuration overrides.</param>`);
+  lines.push(`        /// <param name="cancellationToken">Cancellation token.</param>`);
+  if (responseType) {
+    lines.push(`        /// <returns>The <see cref="${responseType}"/> result.</returns>`);
+  }
+
+  // Signature
+  const sigParams: string[] = [];
+  for (const p of sortPathParamsByTemplateOrder(op)) {
+    sigParams.push(`string ${localName(p.name)}`);
+  }
+  sigParams.push(`${optionsClass} options`);
+  sigParams.push('RequestOptions? requestOptions = null');
+  sigParams.push('CancellationToken cancellationToken = default');
+
+  const returnType = responseType ? `Task<${responseType}>` : 'Task';
+  lines.push(`        public async ${returnType} ${method}(${sigParams.join(', ')})`);
+  lines.push('        {');
+
+  // Set defaults on options
+  for (const [key, value] of Object.entries(wrapper.defaults)) {
+    lines.push(`            options.${csFieldName(key)} = ${csLiteral(value)};`);
+  }
+
+  // Set inferred fields from client. ClientId is required: fail loudly via RequireClientId()
+  // so that callers who forgot to configure it get a clear error instead of a 422 from the API.
+  for (const field of wrapper.inferFromClient) {
+    if (field === 'client_id') {
+      lines.push(`            options.${csFieldName(field)} = this.Client.RequireClientId();`);
+    } else {
+      lines.push(
+        `            options.${csFieldName(field)} = this.Client.${clientFieldExpression(field)} ?? string.Empty;`,
+      );
+    }
+  }
+
+  // Build path
+  let pathExpr: string;
+  if (op.pathParams.length > 0) {
+    let interpolated = op.path;
+    for (const p of sortPathParamsByTemplateOrder(op)) {
+      interpolated = interpolated.replace(`{${p.name}}`, `{${localName(p.name)}}`);
+    }
+    pathExpr = `$"${interpolated}"`;
+  } else {
+    pathExpr = `"${op.path}"`;
+  }
+
+  // Use the Service base-class helper so wrappers read as one-liners.
+  const helper = httpMethodHelperName(op.httpMethod);
+  if (responseType) {
+    lines.push(
+      `            return await this.${helper}<${responseType}>(${pathExpr}, options, requestOptions, cancellationToken);`,
+    );
+  } else if (helper === 'DeleteAsync') {
+    lines.push(`            await this.${helper}(${pathExpr}, options, requestOptions, cancellationToken);`);
+  } else {
+    lines.push(`            await this.${helper}<object>(${pathExpr}, options, requestOptions, cancellationToken);`);
+  }
+
+  lines.push('        }');
+}
+
+// NOTE: T26 (wrapper DRY) — the AuthenticateWith* wrappers share a small
+// SendAuthenticateAsync helper at runtime to avoid 8x copies of the same
+// MakeAPIRequest call. The helper itself lives in UserManagementService.cs as
+// a hand-maintained method (it can't easily be expressed as a generic because
+// the eight options classes don't share an interface). Keeping each generated
+// wrapper's body short is the practical part of the DRY win.
+
+/**
+ * Generate wrapper options classes. Called from resources.ts options generation.
+ */
+export function generateWrapperOptionsClasses(resolvedOp: ResolvedOperation, ctx: EmitterContext): string[] {
+  if (!resolvedOp.wrappers || resolvedOp.wrappers.length === 0) return [];
+
+  const lines: string[] = [];
+
+  for (const wrapper of resolvedOp.wrappers) {
+    const wrapperParams = resolveWrapperParams(wrapper, ctx);
+    const optionsClass = `${csMethodName(wrapper.name)}Options`;
+
+    lines.push('');
+    lines.push(`    public class ${optionsClass} : BaseOptions`);
+    lines.push('    {');
+
+    // Exposed params
+    for (const { paramName, field, isOptional } of wrapperParams) {
+      const csField = csFieldName(paramName);
+      const csType = field ? resolveSimpleCsType(field.type, isOptional) : isOptional ? 'string?' : 'string';
+      const needsDefault = !isOptional && !csType.endsWith('?') && !(field && isValueTypeRef(field.type));
+      const initializer = needsDefault ? ' = default!;' : '';
+
+      const isRequiredEnum = !isOptional && !!field && isEnumRef(field.type);
+      lines.push(...emitXmlDoc(field?.description, '        '));
+      lines.push(...emitJsonPropertyAttributes(paramName, { isRequiredEnum }));
+      lines.push(`        public ${csType} ${csField} { get; set; }${initializer}`);
+      lines.push('');
+    }
+
+    // Hidden fields (defaults + inferred)
+    for (const key of Object.keys(wrapper.defaults)) {
+      const csField = csFieldName(key);
+      lines.push(`        [JsonProperty("${key}")]`);
+      lines.push(`        [STJS.JsonPropertyName("${key}")]`);
+      lines.push(`        internal string ${csField} { get; set; } = default!;`);
+      lines.push('');
+    }
+    for (const key of wrapper.inferFromClient) {
+      const csField = csFieldName(key);
+      // Skip if already added as a default
+      if (Object.keys(wrapper.defaults).includes(key)) continue;
+      lines.push(`        [JsonProperty("${key}")]`);
+      lines.push(`        [STJS.JsonPropertyName("${key}")]`);
+      lines.push(`        internal string ${csField} { get; set; } = default!;`);
+      lines.push('');
+    }
+
+    lines.push('    }');
+  }
+
+  return lines;
+}
+
+function resolveSimpleCsType(ref: any, isOptional: boolean): string {
+  const base = mapTypeRef(ref);
+  if (isOptional && !base.endsWith('?')) return `${base}?`;
+  return base;
+}

package/src/go/index.ts

@@ -10,7 +10,7 @@ import type {
 } from '@workos/oagen';
 
 import { generateModels } from './models.js';
-import { enrichModelsFromSpec } from '../shared/model-utils.js';
+import { enrichModelsFromSpec, getSyntheticEnums } from '../shared/model-utils.js';
 import { generateEnums } from './enums.js';
 import { generateResources } from './resources.js';
 import { generateClient } from './client.js';
@@ -37,7 +37,10 @@ export const goEmitter: Emitter = {
   },
 
   generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateEnums(enums, ctx));
+    // Merge synthetic enums produced during model enrichment (inline oneOf
+    // definitions) so they get proper type definitions in enums.go.
+    const syntheticEnums = getSyntheticEnums();
+    return ensureTrailingNewlines(generateEnums([...enums, ...syntheticEnums], ctx));
   },
 
   generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {

package/src/go/naming.ts

@@ -1,24 +1,15 @@
 import type { Operation, Service, EmitterContext } from '@workos/oagen';
 import { toPascalCase, toSnakeCase } from '@workos/oagen';
 import { buildResolvedLookup, lookupMethodName, getMountTarget } from '../shared/resolved-ops.js';
-import { stripUrnPrefix } from '../shared/naming-utils.js';
+import { stripUrnPrefix, applyAcronymFixes } from '../shared/naming-utils.js';
 
 /**
- * Acronym map: after PascalCase conversion, fix known acronyms to all-caps Go convention.
+ * Go-specific acronym extensions beyond the shared base set.
+ * Go convention requires ALL_CAPS for well-known initialisms.
  */
-const ACRONYM_FIXES: [RegExp, string][] = [
-  [/Workos/g, 'WorkOS'],
-  [/Sso/g, 'SSO'],
-  [/Mfa/g, 'MFA'],
+const GO_EXTRA_ACRONYM_FIXES: [RegExp, string][] = [
   [/Jwks(?=[A-Z]|$)/g, 'JWKS'],
-  [/Jwt/g, 'JWT'],
   [/Totp(?=[A-Z]|$)/g, 'TOTP'],
-  [/Cors/g, 'CORS'],
-  [/Saml/g, 'SAML'],
-  [/Scim/g, 'SCIM'],
-  [/Rbac/g, 'RBAC'],
-  [/Oauth/g, 'OAuth'],
-  [/Oidc/g, 'OIDC'],
   [/Api(?=[A-Z]|$)/g, 'API'],
   [/Urls(?=[A-Z]|$)/g, 'URLs'],
   [/Url(?=[A-Z]|$)/g, 'URL'],
@@ -45,10 +36,7 @@ function fixTrailingId(s: string): string {
 
 /** Apply all Go acronym conventions to a PascalCase string. */
 function applyAcronyms(s: string): string {
-  let result = s;
-  for (const [pattern, replacement] of ACRONYM_FIXES) {
-    result = result.replace(pattern, replacement);
-  }
+  let result = applyAcronymFixes(s, GO_EXTRA_ACRONYM_FIXES);
   result = fixTrailingId(result);
   return result;
 }

package/src/index.ts

@@ -2,3 +2,4 @@ export { nodeEmitter } from './node/index.js';
 export { pythonEmitter } from './python/index.js';
 export { phpEmitter } from './php/index.js';
 export { goEmitter } from './go/index.js';
+export { dotnetEmitter } from './dotnet/index.js';

package/src/kotlin/client.ts

@@ -0,0 +1,53 @@
+import type { ApiSpec, EmitterContext, GeneratedFile, Service } from '@workos/oagen';
+import { apiClassName, packageSegment, servicePropertyName } from './naming.js';
+import { getMountTarget } from '../shared/resolved-ops.js';
+
+const KOTLIN_SRC_PREFIX = 'src/main/kotlin/';
+
+/**
+ * Generate service accessor properties for the hand-maintained `WorkOS` class.
+ *
+ * Each accessor is a `val` property with a custom getter that delegates to
+ * `WorkOS.service(...)` for lazy, cached construction. The generated file
+ * 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.
+ */
+export function generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+  const targets = deduplicateByMount(spec.services, ctx);
+  if (targets.length === 0) return [];
+
+  const accessorLines: string[] = [];
+  for (const mount of targets) {
+    const apiCls = apiClassName(mount);
+    const fqn = `com.workos.${packageSegment(mount)}.${apiCls}`;
+    const prop = servicePropertyName(mount);
+    accessorLines.push('');
+    accessorLines.push(`  /** Lazily-constructed [${apiCls}] accessor for this [WorkOS] client. */`);
+    accessorLines.push(`  val ${prop}: ${fqn}`);
+    accessorLines.push(`    get() = service(${fqn}::class) { ${fqn}(this) }`);
+  }
+
+  const lines: string[] = [];
+  lines.push('package com.workos');
+  lines.push('');
+  lines.push('open class WorkOS {');
+  for (const line of accessorLines) lines.push(line);
+  lines.push('}');
+  lines.push('');
+
+  return [
+    {
+      path: `${KOTLIN_SRC_PREFIX}com/workos/WorkOS.kt`,
+      content: lines.join('\n'),
+    },
+  ];
+}
+
+function deduplicateByMount(services: Service[], ctx: EmitterContext): string[] {
+  const targets = new Set<string>();
+  for (const s of services) targets.add(getMountTarget(s, ctx));
+  return [...targets].sort();
+}

package/src/kotlin/enums.ts

@@ -0,0 +1,162 @@
+import type { Enum, EmitterContext, GeneratedFile } from '@workos/oagen';
+import { className, ktStringLiteral } from './naming.js';
+
+const KOTLIN_SRC_PREFIX = 'src/main/kotlin/';
+const ENUMS_PACKAGE = 'com.workos.types';
+const ENUMS_DIR = 'com/workos/types';
+
+/**
+ * Mapping from an IR enum name to its canonical enum name. When two enums
+ * share identical sorted wire values the shorter-named one is canonical and
+ * the others become `typealias` files. Downstream consumers (type-map,
+ * resources) use this map to resolve references to the canonical class.
+ */
+export const enumCanonicalMap = new Map<string, string>();
+
+/**
+ * Generate Kotlin `enum class` types from the IR enums. Each enum is emitted
+ * to its own file under `com.workos.types`, annotated with Jackson
+ * `@JsonValue` on the wire value. An `Unknown` sentinel is always the first
+ * constant so that responses with new variants still deserialize instead of
+ * throwing.
+ *
+ * Enums with identical sets of wire values are deduplicated: the one with the
+ * shortest PascalCase name becomes canonical and the rest emit `typealias`
+ * files pointing at the canonical class.
+ */
+export function generateEnums(enums: Enum[], _ctx: EmitterContext): GeneratedFile[] {
+  if (enums.length === 0) return [];
+
+  // Reset the canonical map on every generation run (guards against re-entry).
+  enumCanonicalMap.clear();
+
+  // --- Dedup: group enums by a hash of their sorted wire values. ---
+  const hashGroups = new Map<string, Enum[]>();
+  for (const enumDef of enums) {
+    if (enumDef.values.length === 0) continue;
+    const hash = enumWireHash(enumDef);
+    if (!hashGroups.has(hash)) hashGroups.set(hash, []);
+    hashGroups.get(hash)!.push(enumDef);
+  }
+
+  // Within each group, pick the shortest className as canonical.
+  const aliasOf = new Map<string, string>(); // enum name → canonical enum name
+  for (const [, group] of hashGroups) {
+    if (group.length <= 1) continue;
+    const sorted = [...group].sort(
+      (a, b) =>
+        className(a.name).length - className(b.name).length || className(a.name).localeCompare(className(b.name)),
+    );
+    const canonical = sorted[0];
+    for (let i = 1; i < sorted.length; i++) {
+      aliasOf.set(sorted[i].name, canonical.name);
+      enumCanonicalMap.set(sorted[i].name, canonical.name);
+    }
+  }
+
+  const files: GeneratedFile[] = [];
+
+  for (const enumDef of enums) {
+    if (enumDef.values.length === 0) continue;
+
+    const typeName = className(enumDef.name);
+
+    // Non-canonical enum: emit a typealias instead of a full enum class.
+    const canonicalName = aliasOf.get(enumDef.name);
+    if (canonicalName) {
+      const canonicalType = className(canonicalName);
+      const aliasLine = `typealias ${typeName} = ${canonicalType}`;
+      // ktlint enforces a 140-char max line length. When the typealias
+      // exceeds that, add a @file:Suppress to avoid an unfixable violation.
+      const suppressLine = aliasLine.length > 140 ? `@file:Suppress("ktlint:standard:max-line-length")\n\n` : '';
+      const aliasContent = [`${suppressLine}package ${ENUMS_PACKAGE}`, '', aliasLine, ''].join('\n');
+      files.push({
+        path: `${KOTLIN_SRC_PREFIX}${ENUMS_DIR}/${typeName}.kt`,
+        content: aliasContent,
+        overwriteExisting: true,
+      });
+      continue;
+    }
+
+    const lines: string[] = [];
+    lines.push(`package ${ENUMS_PACKAGE}`);
+    lines.push('');
+    lines.push('import com.fasterxml.jackson.annotation.JsonEnumDefaultValue');
+    lines.push('import com.fasterxml.jackson.annotation.JsonValue');
+    lines.push('');
+    // Replace the tautological "Foo enum." docstring with a slightly more
+    // informative summary. `Unknown` is emitted as the forward-compatibility
+    // sentinel for values the server introduces after this SDK was built.
+    lines.push(`/** Enumeration of valid ${typeName} values returned or accepted by the API. */`);
+    lines.push(`enum class ${typeName}(`);
+    lines.push('  @JsonValue val value: String');
+    lines.push(') {');
+    // `@JsonEnumDefaultValue` makes Jackson's
+    // READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE feature map unrecognized
+    // wire values onto `Unknown` instead of throwing — required for forward
+    // compatibility when the API introduces new variants.
+    lines.push('  @JsonEnumDefaultValue');
+    lines.push(`  Unknown(${ktStringLiteral('unknown')}),`);
+
+    const seenNames = new Set<string>(['Unknown']);
+    const seenWire = new Set<string>(['unknown']);
+    const members: string[] = [];
+
+    for (const v of enumDef.values) {
+      const wire = String(v.value);
+      if (seenWire.has(wire)) continue;
+      seenWire.add(wire);
+
+      let memberName = className(wire);
+      if (!memberName || /^[0-9]/.test(memberName)) memberName = `Value${memberName || wire}`;
+      if (memberName === typeName || seenNames.has(memberName)) {
+        let suffix = 2;
+        while (seenNames.has(`${memberName}${suffix}`)) suffix += 1;
+        memberName = `${memberName}${suffix}`;
+      }
+      seenNames.add(memberName);
+
+      if (v.description?.trim()) {
+        members.push(`  /** ${escapeKdoc(v.description.split('\n')[0].trim())} */`);
+      }
+      if (v.deprecated) {
+        members.push('  @Deprecated("Deprecated enum value")');
+      }
+      members.push(`  ${memberName}(${ktStringLiteral(wire)})`);
+    }
+
+    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('@')) {
+        lines.push(line);
+        continue;
+      }
+      lines.push(isLast ? line : `${line},`);
+    }
+
+    lines.push('}');
+    lines.push('');
+
+    files.push({
+      path: `${KOTLIN_SRC_PREFIX}${ENUMS_DIR}/${typeName}.kt`,
+      content: lines.join('\n'),
+      overwriteExisting: true,
+    });
+  }
+
+  return files;
+}
+
+/** Hash an enum by its sorted wire values so identical enums collide. */
+function enumWireHash(enumDef: Enum): string {
+  return [...enumDef.values]
+    .map((v) => String(v.value))
+    .sort()
+    .join('|');
+}
+
+function escapeKdoc(s: string): string {
+  return s.replace(/\*\//g, '*\u200b/');
+}