@workos/oagen-emitters 0.2.1 → 0.4.0

package/src/kotlin/manifest.ts

@@ -0,0 +1,55 @@
+import type { ApiSpec, EmitterContext, GeneratedFile } from '@workos/oagen';
+import { resolveMethodName, servicePropertyName, resolveClassName } from './naming.js';
+import { buildResolvedLookup, lookupResolved, getMountTarget } from '../shared/resolved-ops.js';
+import { propertyName } from './naming.js';
+import { isHandwrittenOverride } from './overrides.js';
+
+/**
+ * Generate the smoke-test manifest mapping `"HTTP_METHOD /path"` to
+ * `{ sdkMethod, service }`. The `service` is the camelCase accessor property
+ * on the main `WorkOS` client (e.g., `organizations`).
+ *
+ * For polymorphic/split operations (e.g., authenticate -> 8 methods), the
+ * manifest emits one entry per wrapper method so each variant is addressable.
+ */
+export function generateManifest(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+  const manifest: Record<string, { sdkMethod: string; service: string } | { sdkMethod: string; service: string }[]> =
+    {};
+  const resolvedLookup = buildResolvedLookup(ctx);
+
+  for (const service of spec.services) {
+    const mountTarget = getMountTarget(service, ctx);
+    const prop = servicePropertyName(resolveClassName(service, ctx) || mountTarget);
+    for (const op of service.operations) {
+      if (isHandwrittenOverride(op)) continue;
+      const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
+
+      // Check if this operation is split into wrapper methods
+      const resolved = lookupResolved(op, resolvedLookup);
+      const wrappers = resolved?.wrappers ?? [];
+
+      // Use the resolved mount target for correct service attribution
+      const resolvedProp = resolved ? servicePropertyName(resolved.mountOn) : prop;
+
+      if (wrappers.length > 0) {
+        // Polymorphic operation: emit an array of methods
+        const methods = wrappers.map((w) => ({
+          sdkMethod: propertyName(w.name),
+          service: resolvedProp,
+        }));
+        manifest[httpKey] = methods;
+      } else {
+        const method = resolveMethodName(op, service, ctx);
+        manifest[httpKey] = { sdkMethod: method, service: resolvedProp };
+      }
+    }
+  }
+
+  return [
+    {
+      path: 'smoke-manifest.json',
+      content: JSON.stringify(manifest, null, 2),
+      integrateTarget: false,
+    },
+  ];
+}

package/src/kotlin/models.ts

@@ -0,0 +1,395 @@
+import type { Model, EmitterContext, GeneratedFile, TypeRef, Field } from '@workos/oagen';
+import { mapTypeRef, discriminatedUnions } from './type-map.js';
+import { className, propertyName, ktStringLiteral } from './naming.js';
+import { enumCanonicalMap } from './enums.js';
+import { isListWrapperModel, isListMetadataModel } from '../shared/model-utils.js';
+
+const KOTLIN_SRC_PREFIX = 'src/main/kotlin/';
+const MODELS_PACKAGE = 'com.workos.models';
+const MODELS_DIR = 'com/workos/models';
+
+/**
+ * Generate Kotlin `data class` models. Each model becomes a separate `.kt`
+ * file under `com.workos.models`. Discriminated unions emit a sealed class
+ * with Jackson `@JsonTypeInfo` / `@JsonSubTypes` annotations so the base type
+ * picks the right variant at deserialization time.
+ *
+ * List wrappers (`{ data, list_metadata }`) and the shared `ListMetadata`
+ * model are skipped — the hand-maintained runtime provides [Page]/[ListMetadata].
+ */
+export function generateModels(models: Model[], _ctx: EmitterContext): GeneratedFile[] {
+  if (models.length === 0) return [];
+
+  // First pass: call mapTypeRef on every model field so discriminator info is
+  // registered before we start emitting parents.
+  for (const model of models) {
+    for (const field of model.fields) mapTypeRef(field.type);
+  }
+
+  const files: GeneratedFile[] = [];
+
+  // Deduplication: identical structures become typealiases.
+  // Pass 1: hash without nested-alias resolution.
+  modelAliasMap = null;
+  const hashGroupsPass1 = new Map<string, string[]>();
+  for (const model of models) {
+    if (isListWrapperModel(model) || isListMetadataModel(model)) continue;
+    if (model.fields.length === 0 && discriminatedUnions.has(className(model.name))) continue;
+    const hash = structuralHash(model);
+    if (!hashGroupsPass1.has(hash)) hashGroupsPass1.set(hash, []);
+    hashGroupsPass1.get(hash)!.push(model.name);
+  }
+
+  const aliasOf = new Map<string, string>();
+  for (const [hash, names] of hashGroupsPass1) {
+    if (names.length <= 1 || hash === '') continue;
+    const sorted = [...names].sort(preferShorterCanonical);
+    const canonical = sorted[0];
+    for (let i = 1; i < sorted.length; i++) {
+      if (hasRequestSuffix(sorted[i]) !== hasRequestSuffix(canonical)) continue;
+      aliasOf.set(sorted[i], canonical);
+    }
+  }
+
+  // Pass 2: re-hash with the alias map so models whose only difference was
+  // referencing aliased vs canonical nested types now collide.
+  modelAliasMap = aliasOf;
+  const hashGroupsPass2 = new Map<string, string[]>();
+  for (const model of models) {
+    if (isListWrapperModel(model) || isListMetadataModel(model)) continue;
+    if (model.fields.length === 0 && discriminatedUnions.has(className(model.name))) continue;
+    if (aliasOf.has(model.name)) continue; // already aliased in pass 1
+    const hash = structuralHash(model);
+    if (!hashGroupsPass2.has(hash)) hashGroupsPass2.set(hash, []);
+    hashGroupsPass2.get(hash)!.push(model.name);
+  }
+  for (const [hash, names] of hashGroupsPass2) {
+    if (names.length <= 1 || hash === '') continue;
+    const sorted = [...names].sort(preferShorterCanonical);
+    const canonical = sorted[0];
+    for (let i = 1; i < sorted.length; i++) {
+      if (aliasOf.has(sorted[i])) continue;
+      if (hasRequestSuffix(sorted[i]) !== hasRequestSuffix(canonical)) continue;
+      aliasOf.set(sorted[i], canonical);
+    }
+  }
+
+  for (const model of models) {
+    if (isListWrapperModel(model) || isListMetadataModel(model)) continue;
+    const typeName = className(model.name);
+
+    // Parent of a discriminated union: emit a sealed class.
+    if (model.fields.length === 0 && discriminatedUnions.has(typeName)) {
+      files.push(emitSealedUnion(typeName, discriminatedUnions.get(typeName)!));
+      continue;
+    }
+
+    const canonical = aliasOf.get(model.name);
+    if (canonical) {
+      const aliasContent = [
+        `package ${MODELS_PACKAGE}`,
+        '',
+        `typealias ${typeName} = ${className(canonical)}`,
+        '',
+      ].join('\n');
+      files.push({
+        path: `${KOTLIN_SRC_PREFIX}${MODELS_DIR}/${typeName}.kt`,
+        content: aliasContent,
+        overwriteExisting: true,
+      });
+      continue;
+    }
+
+    files.push(emitDataClass(model));
+  }
+
+  return files;
+}
+
+/**
+ * Detect whether a model follows the webhook event envelope pattern:
+ * has required `id`, `event`, `created_at` fields plus a `data` field.
+ */
+function isEventEnvelopeModel(model: Model): boolean {
+  const fieldNames = new Set(model.fields.map((f) => f.name));
+  return fieldNames.has('id') && fieldNames.has('event') && fieldNames.has('created_at') && fieldNames.has('data');
+}
+
+function emitDataClass(model: Model): GeneratedFile {
+  const typeName = className(model.name);
+  const imports = collectImports(model.fields);
+  const implementsEvent = isEventEnvelopeModel(model);
+  if (implementsEvent) imports.add('com.workos.common.http.WorkOSEvent');
+  const lines: string[] = [];
+  lines.push(`package ${MODELS_PACKAGE}`);
+  lines.push('');
+  for (const imp of [...imports].sort()) lines.push(`import ${imp}`);
+  if (imports.size > 0) lines.push('');
+
+  appendKdoc(lines, model.description ?? `${typeName} model.`, 0);
+
+  if (model.fields.length === 0) {
+    // Kotlin data classes require at least one primary constructor param.
+    // Use a regular empty class instead.
+    lines.push(`class ${typeName}`);
+    lines.push('');
+  } else {
+    const implClause = implementsEvent ? ' : WorkOSEvent' : '';
+    lines.push(`data class ${typeName}(`);
+
+    // Emit non-defaulted params first, then defaulted — Kotlin requires
+    // non-defaulted params before defaulted ones. Literal-typed fields always
+    // receive a default, so they sort after plain required fields.
+    const hasDefault = (f: Field): boolean => !f.required || f.type.kind === 'literal';
+    const ordered = [...model.fields].sort((a, b) => {
+      const aDef = hasDefault(a);
+      const bDef = hasDefault(b);
+      if (aDef === bDef) return 0;
+      return aDef ? 1 : -1;
+    });
+    // When implementing WorkOSEvent, matching fields need `override`.
+    const overrideFields = implementsEvent ? new Set(['id', 'event', 'createdAt']) : new Set<string>();
+    const rendered = renderFields(ordered, overrideFields);
+    for (let i = 0; i < rendered.length; i++) {
+      const suffix = i === rendered.length - 1 ? '' : ',';
+      lines.push(`${rendered[i]}${suffix}`);
+    }
+
+    lines.push(`)${implClause}`);
+    lines.push('');
+  }
+
+  return {
+    path: `${KOTLIN_SRC_PREFIX}${MODELS_DIR}/${typeName}.kt`,
+    content: lines.join('\n'),
+    overwriteExisting: true,
+  };
+}
+
+function emitSealedUnion(
+  typeName: string,
+  disc: { property: string; mapping: Record<string, string>; variantTypes: string[] },
+): GeneratedFile {
+  const lines: string[] = [];
+  lines.push(`package ${MODELS_PACKAGE}`);
+  lines.push('');
+  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);
+  lines.push('@JsonTypeInfo(');
+  lines.push('  use = JsonTypeInfo.Id.NAME,');
+  lines.push('  include = JsonTypeInfo.As.EXISTING_PROPERTY,');
+  lines.push(`  property = ${ktStringLiteral(disc.property)},`);
+  lines.push('  visible = true');
+  lines.push(')');
+  lines.push('@JsonSubTypes(');
+  const entries = Object.entries(disc.mapping);
+  for (let i = 0; i < entries.length; i++) {
+    const [wireValue, modelName] = entries[i];
+    const variantType = className(modelName);
+    const suffix = i === entries.length - 1 ? '' : ',';
+    lines.push(`  JsonSubTypes.Type(value = ${variantType}::class, name = ${ktStringLiteral(wireValue)})${suffix}`);
+  }
+  lines.push(')');
+  lines.push(`sealed class ${typeName}`);
+  lines.push('');
+
+  return {
+    path: `${KOTLIN_SRC_PREFIX}${MODELS_DIR}/${typeName}.kt`,
+    content: lines.join('\n'),
+    overwriteExisting: true,
+  };
+}
+
+function renderFields(fields: Field[], overrideFields: Set<string> = new Set()): string[] {
+  const seen = new Set<string>();
+  const lines: string[] = [];
+
+  for (const field of fields) {
+    const kotlinName = propertyName(field.name);
+    if (seen.has(kotlinName)) continue;
+    seen.add(kotlinName);
+
+    const baseType = mapTypeRef(field.type);
+    let kotlinType: string;
+    let defaultExpr: string | null = null;
+
+    // Const literal fields: always emit a hardcoded default matching the
+    // literal value so callers don't have to pass it.
+    const literalDefault = literalDefaultExpr(field.type);
+
+    if (literalDefault !== null) {
+      kotlinType = baseType;
+      defaultExpr = literalDefault;
+    } else if (!field.required) {
+      kotlinType = baseType.endsWith('?') ? baseType : `${baseType}?`;
+      defaultExpr = 'null';
+    } else if (baseType.endsWith('?')) {
+      // Required field whose underlying type is already nullable.
+      kotlinType = baseType;
+    } else {
+      kotlinType = baseType;
+    }
+
+    const isOverride = overrideFields.has(kotlinName);
+    const annotations: string[] = [];
+    // @JvmField cannot be applied to override properties in Kotlin.
+    // Java callers can still reach the field through the generated getter.
+    if (!isOverride) annotations.push('@JvmField');
+    annotations.push(`@JsonProperty(${ktStringLiteral(field.name)})`);
+    if (field.deprecated) annotations.push('@Deprecated("Deprecated field")');
+
+    const paramParts: string[] = [];
+    if (field.description?.trim()) {
+      const line = field.description.split('\n').find((l) => l.trim()) ?? '';
+      lines.push(`  /** ${escapeKdoc(line.trim())} */`);
+    } else if (literalDefault !== null) {
+      lines.push(`  /** Always \`${literalDefault}\`. */`);
+    }
+    for (const anno of annotations) lines.push(`  ${anno}`);
+
+    const overridePrefix = isOverride ? 'override ' : '';
+    const rendered = `  ${overridePrefix}val ${kotlinName}: ${kotlinType}`;
+    paramParts.push(rendered);
+    if (defaultExpr !== null) paramParts[0] = `${paramParts[0]} = ${defaultExpr}`;
+    lines.push(paramParts[0]);
+  }
+  // Collapse annotation + val pairs into a list where each contiguous block
+  // becomes one field entry, preserving order.
+  return collapseFieldEntries(lines);
+}
+
+function collapseFieldEntries(rawLines: string[]): string[] {
+  // `rawLines` intermixes kdoc comments, annotations, and `val` declarations.
+  // Group them so each field is a single multi-line entry, so the caller can
+  // append a trailing comma at the right spot.
+  const entries: string[] = [];
+  let current: string[] = [];
+  for (const line of rawLines) {
+    const trimmed = line.trimStart();
+    const isDeclaration = trimmed.startsWith('val ') || trimmed.startsWith('override val ');
+    current.push(line);
+    if (isDeclaration) {
+      entries.push(current.join('\n'));
+      current = [];
+    }
+  }
+  if (current.length > 0) entries.push(current.join('\n'));
+  return entries;
+}
+
+/**
+ * If the TypeRef is a literal (const) with a string, number, or boolean value,
+ * return the Kotlin expression for that default. Otherwise return null.
+ */
+function literalDefaultExpr(ref: TypeRef): string | null {
+  if (ref.kind !== 'literal' || ref.value === null) return null;
+  if (typeof ref.value === 'string') return ktStringLiteral(ref.value);
+  if (typeof ref.value === 'number') return Number.isInteger(ref.value) ? `${ref.value}L` : String(ref.value);
+  if (typeof ref.value === 'boolean') return ref.value ? 'true' : 'false';
+  return null;
+}
+
+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) {
+    const mapped = mapTypeRef(field.type);
+    if (/\bOffsetDateTime\b/.test(mapped)) imports.add('java.time.OffsetDateTime');
+    for (const enumName of collectEnumNames(field.type)) {
+      // Resolve through the canonical map so imports point at the actual
+      // enum class, not an alias that may not have its own file.
+      const canonical = enumCanonicalMap.get(enumName) ?? enumName;
+      imports.add(`com.workos.types.${className(canonical)}`);
+    }
+  }
+  return imports;
+}
+
+function collectEnumNames(ref: TypeRef, acc: Set<string> = new Set()): Set<string> {
+  if (ref.kind === 'enum') acc.add(ref.name);
+  else if (ref.kind === 'array') collectEnumNames(ref.items, acc);
+  else if (ref.kind === 'map') collectEnumNames(ref.valueType, acc);
+  else if (ref.kind === 'nullable') collectEnumNames(ref.inner, acc);
+  else if (ref.kind === 'union') for (const v of ref.variants) collectEnumNames(v, acc);
+  return acc;
+}
+
+function appendKdoc(lines: string[], text: string, indent: number): void {
+  const pad = ' '.repeat(indent);
+  const firstLine = text.split('\n').find((l) => l.trim()) ?? '';
+  lines.push(`${pad}/** ${escapeKdoc(firstLine.trim())} */`);
+}
+
+function escapeKdoc(s: string): string {
+  return s.replace(/\*\//g, '*\u200b/');
+}
+
+// Re-exported so downstream emitters (resources, tests) can filter wrapper models.
+export { isListWrapperModel, isListMetadataModel };
+
+// --- Canonical name selection ---
+
+/**
+ * When picking which model name should be the concrete class (canonical) vs.
+ * a typealias, prefer shorter names first (they tend to be the public-facing
+ * names like `User`, `Role`), then fall back to alphabetical order for
+ * stability. This avoids situations where `User = EmailChangeConfirmationUser`
+ * or `SlimRole = AddRolePermission`.
+ */
+function preferShorterCanonical(a: string, b: string): number {
+  const aName = className(a);
+  const bName = className(b);
+  if (aName.length !== bName.length) return aName.length - bName.length;
+  return aName.localeCompare(bName);
+}
+
+// --- Unsafe typealias guard ---
+
+/** Suffixes that indicate a request / mutation DTO. */
+const REQUEST_SUFFIXES = /(?:Dto|Request|Create|Update|Add|Remove|Set)$/i;
+
+/**
+ * Returns true when [name] looks like a request DTO based on its suffix.
+ * Used to prevent aliasing request DTOs to response models that happen to
+ * share the same field shapes today.
+ */
+function hasRequestSuffix(name: string): boolean {
+  return REQUEST_SUFFIXES.test(className(name));
+}
+
+// --- Structural dedup ---
+
+/**
+ * Resolve a model name through the alias map so that two models referencing
+ * aliased nested types produce the same structural hash. Called after the
+ * first alias pass to catch transitive matches.
+ */
+let modelAliasMap: Map<string, string> | null = null;
+
+function normalizeTypeForHash(ref: TypeRef): unknown {
+  if (ref.kind === 'enum') {
+    const vals = ref.values ? [...ref.values].sort() : [];
+    return { kind: 'enum', values: vals };
+  }
+  if (ref.kind === 'model') {
+    // Resolve through the alias map so `FooData` and `BarData` (aliased to
+    // FooData) produce the same hash when referenced as nested types.
+    const resolved = modelAliasMap?.get(ref.name) ?? ref.name;
+    return { kind: 'model', name: resolved };
+  }
+  if (ref.kind === 'nullable') return { kind: 'nullable', inner: normalizeTypeForHash(ref.inner) };
+  if (ref.kind === 'array') return { kind: 'array', items: normalizeTypeForHash(ref.items) };
+  if (ref.kind === 'union') return { kind: 'union', variants: ref.variants.map(normalizeTypeForHash) };
+  if (ref.kind === 'map') return { kind: 'map', valueType: normalizeTypeForHash(ref.valueType) };
+  return ref;
+}
+
+function structuralHash(model: Model): string {
+  return model.fields
+    .map((f) => `${f.name}:${JSON.stringify(normalizeTypeForHash(f.type))}:${f.required}`)
+    .sort()
+    .join('|');
+}

package/src/kotlin/naming.ts

@@ -0,0 +1,223 @@
+import type { Operation, Service, EmitterContext } 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';
+
+/** PascalCase class/type name. */
+export function className(name: string): string {
+  return toPascalCase(stripUrnPrefix(name));
+}
+
+/** PascalCase file name (matches the primary class). */
+export function fileName(name: string): string {
+  return toPascalCase(stripUrnPrefix(name));
+}
+
+/** snake_case file name for fixtures/test data. */
+export function fixtureFileName(name: string): string {
+  return toSnakeCase(stripUrnPrefix(name));
+}
+
+/** camelCase method name. */
+export function methodName(name: string): string {
+  return toCamelCase(name);
+}
+
+/** camelCase Kotlin property / local variable name. */
+export function propertyName(name: string): string {
+  return escapeReserved(toCamelCase(name));
+}
+
+/** camelCase alias (kept for parity with other emitters). */
+export const fieldName = propertyName;
+export const localName = propertyName;
+
+/** PascalCase directory segment for a service / mount group. */
+export function moduleName(name: string): string {
+  return toPascalCase(name);
+}
+
+/** Lower-case Kotlin package segment for a service / mount group. */
+export function packageSegment(name: string): string {
+  // Kotlin package convention: all-lowercase, no separators.
+  return toPascalCase(name).toLowerCase();
+}
+
+/** Kotlin service class name for a mount group (e.g., `Organizations`). */
+export function apiClassName(name: string): string {
+  return className(name);
+}
+
+/** Accessor property exposed on the WorkOS client (camelCase). */
+export function servicePropertyName(name: string): string {
+  return toCamelCase(name);
+}
+
+/** Resolve the effective service (mount target) name. */
+export function resolveServiceName(service: Service, ctx: EmitterContext): string {
+  return resolveClassName(service, ctx);
+}
+
+/** Build a map from IR service name -> resolved mount-target name (PascalCase). */
+export function buildServiceNameMap(services: Service[], ctx: EmitterContext): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const service of services) {
+    map.set(service.name, resolveServiceName(service, ctx));
+  }
+  return map;
+}
+
+/** Resolve the SDK method name (camelCase) for an operation. */
+export function resolveMethodName(op: Operation, service: Service, ctx: EmitterContext): string {
+  const lookup = buildResolvedLookup(ctx);
+  const resolved = lookupMethodName(op, lookup);
+  if (resolved) {
+    return trimMountedResourceFromMethod(methodName(resolved), resolveClassName(service, ctx));
+  }
+  const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
+  const existing = ctx.overlayLookup?.methodByOperation?.get(httpKey);
+  if (existing) {
+    return trimMountedResourceFromMethod(methodName(existing.methodName), resolveClassName(service, ctx));
+  }
+  return trimMountedResourceFromMethod(methodName(op.name), resolveClassName(service, ctx));
+}
+
+/** Resolve the SDK class name (PascalCase) for a service. */
+export function resolveClassName(service: Service, ctx: EmitterContext): string {
+  for (const r of ctx.resolvedOperations ?? []) {
+    if (r.service.name === service.name) return className(r.mountOn);
+  }
+  if (ctx.overlayLookup?.methodByOperation) {
+    for (const op of service.operations) {
+      const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
+      const existing = ctx.overlayLookup.methodByOperation.get(httpKey);
+      if (existing) return className(existing.className);
+    }
+  }
+  return className(service.name);
+}
+
+/** Build a map from IR service name -> mount-target directory (PascalCase). */
+export function buildMountDirMap(ctx: EmitterContext): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const service of ctx.spec.services) {
+    const target = getMountTarget(service, ctx);
+    map.set(service.name, moduleName(target));
+  }
+  return map;
+}
+
+function splitPascalWords(name: string): string[] {
+  return name.match(/[A-Z]+(?:[a-z]+|(?=[A-Z]|$))|[A-Z]?[a-z]+|[0-9]+/g) ?? [name];
+}
+
+function singularize(word: string): string {
+  if (word.endsWith('ies') && word.length > 3) {
+    return `${word.slice(0, -3)}y`;
+  }
+  if (word.endsWith('s') && !word.endsWith('ss')) {
+    return word.slice(0, -1);
+  }
+  return word;
+}
+
+function wordsMatch(left: string, right: string): boolean {
+  return singularize(left.toLowerCase()) === singularize(right.toLowerCase());
+}
+
+/**
+ * Trim the mount-target resource words from the start of a method name.
+ * E.g. `listOrganizations` on OrganizationsApi becomes `list`.
+ */
+function trimMountedResourceFromMethod(method: string, mountName: string): string {
+  const methodWords = splitPascalWords(method);
+  if (methodWords.length < 2) return method;
+
+  const mountWords = splitPascalWords(className(mountName));
+  if (mountWords.length === 0) return method;
+
+  let matched = 0;
+  while (
+    matched < mountWords.length &&
+    matched + 1 < methodWords.length &&
+    wordsMatch(methodWords[matched + 1], mountWords[matched])
+  ) {
+    matched++;
+  }
+
+  if (matched === 0) return method;
+
+  return [methodWords[0], ...methodWords.slice(matched + 1)].join('');
+}
+
+/** Kotlin hard/soft keywords that must be back-ticked when used as identifiers. */
+const KOTLIN_RESERVED = new Set([
+  'as',
+  'break',
+  'class',
+  'continue',
+  'do',
+  'else',
+  'false',
+  'for',
+  'fun',
+  'if',
+  'in',
+  'interface',
+  'is',
+  'null',
+  'object',
+  'package',
+  'return',
+  'super',
+  'this',
+  'throw',
+  'true',
+  'try',
+  'typealias',
+  'typeof',
+  'val',
+  'var',
+  'when',
+  'while',
+]);
+
+/** Escape a Kotlin identifier if it collides with a reserved word. */
+export function escapeReserved(name: string): string {
+  return KOTLIN_RESERVED.has(name) ? `\`${name}\`` : name;
+}
+
+/** Escape a string literal for Kotlin source. */
+export function ktStringLiteral(value: string): string {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r')}"`;
+}
+
+/** Escape any scalar as a Kotlin literal expression. */
+export function ktLiteral(value: string | number | boolean): string {
+  if (typeof value === 'string') return ktStringLiteral(value);
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  return String(value);
+}
+
+/**
+ * Map a wire field name to the expression that reads it off a WorkOS client
+ * instance (used for inferFromClient fields).
+ */
+export function clientFieldExpression(field: string): string {
+  switch (field) {
+    case 'client_id':
+      return 'clientId';
+    case 'client_secret':
+      return 'apiKey';
+    default:
+      return propertyName(field);
+  }
+}
+
+/** Convert snake_case / camelCase to a human-readable lowercase phrase for docs. */
+export function humanize(name: string): string {
+  return name
+    .replace(/_/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .toLowerCase();
+}

package/src/kotlin/overrides.ts

@@ -0,0 +1,25 @@
+import type { Operation } from '@workos/oagen';
+
+/**
+ * Operations whose generated implementation would be wrong (URL builders
+ * served as HTTP calls). Hand-maintained code in `workos-kotlin` owns these
+ * method names instead; the emitter must skip resources, tests, and the
+ * smoke manifest for any operation in this set.
+ *
+ * Keys are `"METHOD path"` in the same form used by the smoke manifest.
+ */
+export const HANDWRITTEN_OVERRIDE_OPS: ReadonlySet<string> = new Set([
+  // AuthKit authorization URL (H09 / H10 are hand-built).
+  'GET /user_management/authorize',
+  // AuthKit logout URL (H17 — URL, not HTTP call).
+  'GET /user_management/sessions/logout',
+  // SSO authorization URL (H14 / H15 are hand-built).
+  'GET /sso/authorize',
+  // SSO logout URL (H17 — URL, not HTTP call).
+  'GET /sso/logout',
+]);
+
+/** True if the operation is owned by a hand-maintained override. */
+export function isHandwrittenOverride(op: Operation): boolean {
+  return HANDWRITTEN_OVERRIDE_OPS.has(`${op.httpMethod.toUpperCase()} ${op.path}`);
+}