@workos/oagen-emitters 0.8.1 → 0.8.2

package/dist/plugin.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos/oagen-emitters",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "WorkOS' oagen emitters",
   "license": "MIT",
   "author": "WorkOS",

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
@@ -295,7 +325,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 +360,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 +403,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 +451,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/resources.ts

@@ -41,6 +41,46 @@ import { buildKotlinPathExpression, KOTLIN_PATH_ENCODE_IMPORT } from './path-exp
 
 const KOTLIN_SRC_PREFIX = 'src/main/kotlin/';
 
+/**
+ * Some specs leave query params / fields typed as plain `string` even though
+ * the description (or the field name) makes clear they carry an ISO-8601
+ * timestamp. Detecting that here lets us emit `OffsetDateTime` so callers
+ * don't have to format the wire string themselves.
+ */
+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);
+}
+
+/**
+ * Promote a string `TypeRef` to a `format: date-time` primitive when the
+ * accompanying description identifies it as an ISO-8601 timestamp. Leaves
+ * non-string types untouched.
+ */
+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 promoteParameterType(p: Parameter): Parameter {
+  const promoted = promoteIso8601TypeRef(p.type, p.description);
+  return promoted === p.type ? p : { ...p, type: promoted };
+}
+
+function promoteFieldType(f: Field): Field {
+  const promoted = promoteIso8601TypeRef(f.type, f.description);
+  return promoted === f.type ? f : { ...f, type: promoted };
+}
+
 /**
  * Generate one API class per mount group. Methods map 1:1 to IR operations.
  * Path params, query params, and body fields are flattened into the method
@@ -249,10 +289,12 @@ function renderMethod(
   const pathParams = sortPathParamsByTemplateOrder(op);
   const groupedParamNames = collectGroupedParamNames(op);
   const hasGroups = (op.parameterGroups?.length ?? 0) > 0;
-  const queryParams = op.queryParams.filter((p) => !hidden.has(p.name) && !groupedParamNames.has(p.name));
+  const queryParams = op.queryParams
+    .filter((p) => !hidden.has(p.name) && !groupedParamNames.has(p.name))
+    .map(promoteParameterType);
   const bodyModel = resolveBodyModel(op, ctx);
   const bodyFields = bodyModel
-    ? bodyModel.fields.filter((f) => !hidden.has(f.name) && !groupedParamNames.has(f.name))
+    ? bodyModel.fields.filter((f) => !hidden.has(f.name) && !groupedParamNames.has(f.name)).map(promoteFieldType)
     : [];
 
   // Track imports we need
@@ -426,12 +468,13 @@ function renderMethod(
     lines.push(`      before = ${pickNamedQueryParam(sortedQuery, 'before')},`);
     lines.push(`      after = ${pickNamedQueryParam(sortedQuery, 'after')}`);
     lines.push(`    ) {`);
-    lines.push(`      val params = this`);
     for (const qp of sortedQuery.filter((p) => p.name !== 'after' && p.name !== 'before')) {
-      for (const ln of emitQueryParam(qp, '      ')) lines.push(ln);
+      for (const ln of emitQueryParam(qp, '      ', true)) lines.push(ln);
     }
     for (const group of op.parameterGroups ?? []) {
-      for (const ln of emitGroupQueryDispatch(group, groupParamNames.get(group.name)!, '      ')) lines.push(ln);
+      for (const ln of emitGroupQueryDispatch(group, groupParamNames.get(group.name)!, '      ', true)) {
+        lines.push(ln);
+      }
     }
     lines.push(`    }`);
   } else {
@@ -609,31 +652,32 @@ function buildMethodKdoc(
   }
 
   // @param lines. Use the Kotlin-visible parameter name (body collisions get
-  // renamed, e.g. slug → bodySlug).  Deprecated parameters always get a
-  // @param entry even without a description so the deprecation note is
-  // surfaced in the docs.
+  // renamed, e.g. slug → bodySlug). Every parameter gets an `@param` line —
+  // Dokka does not flag missing `@param` blocks (only fully undocumented
+  // declarations), so we have to enforce coverage at emit time. Spec-provided
+  // descriptions are preferred; missing descriptions get a templated fallback
+  // derived from the parameter name. The fallback is intentionally a little
+  // ugly — it nudges callers to add real descriptions to the spec.
   const paramDocs: string[] = [];
   const seenParamDocs = new Set<string>();
-  const pushParamDoc = (name: string, description: string | undefined, deprecated?: boolean) => {
+  const pushParamDoc = (name: string, sourceName: string, description: string | undefined, deprecated?: boolean) => {
     if (seenParamDocs.has(name)) return;
     seenParamDocs.add(name);
-    paramDocs.push(formatParamDoc(name, description, deprecated));
+    paramDocs.push(formatParamDoc(name, description, deprecated, sourceName));
   };
   for (const pp of pathParams) {
-    if (pp.description?.trim() || pp.deprecated) {
-      pushParamDoc(propertyName(pp.name), pp.description, pp.deprecated);
-    }
+    pushParamDoc(propertyName(pp.name), pp.name, pp.description, pp.deprecated);
   }
   for (const qp of queryParams) {
-    if (qp.description?.trim() || qp.deprecated) {
-      pushParamDoc(propertyName(qp.name), qp.description, qp.deprecated);
-    }
+    pushParamDoc(propertyName(qp.name), qp.name, qp.description, qp.deprecated);
   }
   for (const bf of bodyFields) {
-    if (bf.description?.trim() || bf.deprecated) {
-      pushParamDoc(bodyParamNames.get(bf.name)!, bf.description, bf.deprecated);
-    }
+    pushParamDoc(bodyParamNames.get(bf.name)!, bf.name, bf.description, bf.deprecated);
   }
+  // Always document the trailing `requestOptions` parameter with a stable,
+  // canned phrasing so generated SDKs are consistent and Dokka's coverage
+  // reporting has nothing to flag.
+  pushParamDoc('requestOptions', 'request_options', REQUEST_OPTIONS_PARAM_DESCRIPTION);
 
   const returnDoc = plan.isPaginated
     ? '@return a [com.workos.common.http.Page] of results'
@@ -658,12 +702,29 @@ function buildMethodKdoc(
   return out;
 }
 
-function formatParamDoc(kotlinName: string, description: string | undefined, deprecated?: boolean): string {
+/**
+ * Stable, canned description for the trailing `requestOptions` parameter that
+ * every generated method exposes. Kept as a constant so the same phrasing
+ * appears across resource methods, wrapper methods, and union-split helpers.
+ */
+const REQUEST_OPTIONS_PARAM_DESCRIPTION = 'per-request overrides (idempotency key, API key, headers, timeout)';
+
+function formatParamDoc(
+  kotlinName: string,
+  description: string | undefined,
+  deprecated?: boolean,
+  sourceName?: string,
+): string {
   const firstLine = description?.split('\n').find((l) => l.trim()) ?? '';
-  const text = firstLine.trim();
+  const specText = firstLine.trim();
   const deprecationNote = deprecated ? '**Deprecated.**' : '';
+  // Fall back to a templated description derived from the parameter name when
+  // the spec didn't provide one. Dokka has no `-Xdoclint:missing` analogue,
+  // so emitting a placeholder is the only way to guarantee `@param` coverage.
+  const fallback = `the ${humanize(sourceName ?? kotlinName)} of the request.`;
+  const text = specText || fallback;
   const parts = [deprecationNote, text].filter(Boolean).join(' ');
-  return `@param ${kotlinName}${parts ? ` ${escapeKdoc(parts)}` : ''}`;
+  return `@param ${kotlinName} ${escapeKdoc(parts)}`;
 }
 
 /**
@@ -684,43 +745,66 @@ function unwrapArray(t: TypeRef): TypeRef | null {
 function valueExprForQuery(type: TypeRef): string {
   const inner = type.kind === 'nullable' ? type.inner : type;
   if (inner.kind === 'enum') return 'it.value';
-  if (inner.kind === 'primitive' && inner.type === 'string') return 'it';
+  if (inner.kind === 'primitive' && inner.type === 'string') {
+    return inner.format === 'date-time' ? 'it.toString()' : 'it';
+  }
   return 'it.toString()';
 }
 
-function emitQueryParam(p: Parameter, indent: string): string[] {
+function emitQueryParam(p: Parameter, indent: string, receiverMode = false): string[] {
   const prop = propertyName(p.name);
   const rendered = queryParamToString(p.type, prop);
   const inner = p.type.kind === 'nullable' ? p.type.inner : p.type;
   const arrayItem = unwrapArray(p.type);
+  // In receiver-lambda mode (`requestPage { ... }`) the surrounding closure is
+  // an extension on `MutableList<Pair<String, String>>`, so we elide the
+  // explicit `params.` qualifier (extension functions resolve via implicit
+  // receiver) and route `+=` through `add(pair)` to keep ktlint happy.
+  const callPrefix = receiverMode ? '' : 'params.';
+  const addPair = (pair: string) => (receiverMode ? `add(${pair})` : `params += ${pair}`);
   if (arrayItem) {
     // Honor `style: form, explode: false` → comma-joined. Default (explode:true
     // or unspecified for form) → repeated keys.  `p.explode ?? true` matches
     // the OpenAPI default for query parameters when `style` is form.
     const explode = p.explode ?? true;
     const itemExpr = valueExprForQuery(arrayItem);
+    // `it` is the loop variable in the trivial mapping case — `xs.map { it }`
+    // is the identity function, so emit the collection directly when the per-
+    // item expression doesn't transform the value.
+    const isIdentity = itemExpr === 'it';
     if (!explode) {
       if (p.required) {
-        return [`${indent}params.addJoinedIfNotNull(${ktLiteral(p.name)}, ${prop}.map { ${itemExpr} })`];
+        const arg = isIdentity ? prop : `${prop}.map { ${itemExpr} }`;
+        return [`${indent}${callPrefix}addJoinedIfNotNull(${ktLiteral(p.name)}, ${arg})`];
       }
-      return [`${indent}params.addJoinedIfNotNull(${ktLiteral(p.name)}, ${prop}?.map { ${itemExpr} })`];
+      const arg = isIdentity ? prop : `${prop}?.map { ${itemExpr} }`;
+      return [`${indent}${callPrefix}addJoinedIfNotNull(${ktLiteral(p.name)}, ${arg})`];
     }
     if (p.required) {
-      return [`${indent}params.addEach(${ktLiteral(p.name)}, ${prop}.map { ${itemExpr} })`];
+      const arg = isIdentity ? prop : `${prop}.map { ${itemExpr} }`;
+      return [`${indent}${callPrefix}addEach(${ktLiteral(p.name)}, ${arg})`];
+    }
+    if (isIdentity) {
+      return [`${indent}${prop}?.let { ${callPrefix}addEach(${ktLiteral(p.name)}, it) }`];
     }
-    return [`${indent}${prop}?.let { params.addEach(${ktLiteral(p.name)}, it.map { ${itemExpr} }) }`];
+    return [`${indent}${prop}?.let { ${callPrefix}addEach(${ktLiteral(p.name)}, it.map { ${itemExpr} }) }`];
   }
-  if (p.required) return [`${indent}params += ${ktLiteral(p.name)} to ${rendered}`];
-  if (inner.kind === 'primitive' && inner.type === 'string') {
-    return [`${indent}params.addIfNotNull(${ktLiteral(p.name)}, ${prop})`];
+  if (p.required) return [`${indent}${addPair(`${ktLiteral(p.name)} to ${rendered}`)}`];
+  if (inner.kind === 'primitive' && inner.type === 'string' && inner.format !== 'date-time') {
+    return [`${indent}${callPrefix}addIfNotNull(${ktLiteral(p.name)}, ${prop})`];
   }
-  return [`${indent}${prop}?.let { params += ${ktLiteral(p.name)} to ${queryParamToString(inner, 'it')} }`];
+  return [`${indent}${prop}?.let { ${addPair(`${ktLiteral(p.name)} to ${queryParamToString(inner, 'it')}`)} }`];
 }
 
 function queryParamToString(type: TypeRef, varName: string): string {
   if (type.kind === 'enum') return `${varName}.value`;
   if (type.kind === 'nullable') return queryParamToString(type.inner, varName);
-  if (type.kind === 'primitive' && type.type === 'string') return varName;
+  // Plain `string` is already the wire type. ISO-8601 strings get promoted to
+  // `OffsetDateTime`, so we need an explicit `.toString()` to serialize them
+  // as the spec-required ISO-8601 representation.
+  if (type.kind === 'primitive' && type.type === 'string') {
+    return type.format === 'date-time' ? `${varName}.toString()` : varName;
+  }
   return `${varName}.toString()`;
 }
 
@@ -870,16 +954,21 @@ function generateSealedClass(
 }
 
 /** Emit `when` dispatch that serializes a parameter group into query params. */
-function emitGroupQueryDispatch(group: import('@workos/oagen').ParameterGroup, prop: string, indent: string): string[] {
+function emitGroupQueryDispatch(
+  group: import('@workos/oagen').ParameterGroup,
+  prop: string,
+  indent: string,
+  receiverMode = false,
+): string[] {
   const sealedName = sealedGroupName(group.name);
   const lines: string[] = [];
 
   if (group.optional) {
     lines.push(`${indent}if (${prop} != null) {`);
-    emitWhenBlock(lines, group, sealedName, prop, `${indent}  `);
+    emitWhenBlock(lines, group, sealedName, prop, `${indent}  `, receiverMode);
     lines.push(`${indent}}`);
   } else {
-    emitWhenBlock(lines, group, sealedName, prop, indent);
+    emitWhenBlock(lines, group, sealedName, prop, indent, receiverMode);
   }
   return lines;
 }
@@ -920,13 +1009,15 @@ function emitWhenBlock(
   sealedName: string,
   prop: string,
   indent: string,
+  receiverMode = false,
 ): void {
   lines.push(`${indent}when (${prop}) {`);
   for (const variant of group.variants) {
     const variantName = className(variant.name);
     const entries = variant.parameters.map((p) => {
       const fieldProp = deriveShortPropertyName(p.name, group.name);
-      return `params += ${ktLiteral(p.name)} to ${prop}.${fieldProp}`;
+      const pair = `${ktLiteral(p.name)} to ${prop}.${fieldProp}`;
+      return receiverMode ? `add(${pair})` : `params += ${pair}`;
     });
     if (entries.length === 1) {
       lines.push(`${indent}  is ${sealedName}.${variantName} -> ${entries[0]}`);

package/src/kotlin/tests.ts

@@ -25,6 +25,31 @@ import { isHandwrittenOverride } from './overrides.js';
 
 const TEST_PREFIX = 'src/test/kotlin/';
 
+/**
+ * Mirror the ISO-8601 hint promotion the resource/model emitters use so tests
+ * synthesize values whose Kotlin type matches the generated method signature.
+ * Kept in sync with the helpers in `resources.ts` / `models.ts`; if the
+ * detection rule changes, update all three.
+ */
+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);
+}
+
 /**
  * Generate one JUnit 5 + WireMock test class per API mount group, plus a
  * cross-cutting model round-trip test.
@@ -254,12 +279,13 @@ function buildOperationTest(
   }
   for (const qp of sortedQuery) {
     if (!qp.required) break;
-    const val = synthValue(qp.type, ctx, imports);
+    const promotedType = promoteIso8601TypeRef(qp.type, qp.description);
+    const val = synthValue(promotedType, ctx, imports);
     if (val === null) return null;
     argParts.push(val);
     // Best-effort wire assertion: for primitives/strings we know the synthesized
     // value so we can assert equality; otherwise just assert presence.
-    const regex = queryValueRegexFor(qp.type);
+    const regex = queryValueRegexFor(promotedType);
     if (regex !== null) requiredQueryAssertions.push({ name: qp.name, valueRegex: regex });
   }
 
@@ -283,14 +309,15 @@ function buildOperationTest(
     for (const bf of sortedBody) {
       if (sharedQueryBodyParams.has(bf.name)) continue;
       if (!bf.required) break;
-      const val = synthValue(bf.type, ctx, imports);
+      const promotedType = promoteIso8601TypeRef(bf.type, bf.description);
+      const val = synthValue(promotedType, ctx, imports);
       if (val === null) return null;
       argParts.push(val);
       // matchingJsonPath on an array/map body field fails on empty
       // synthesized collections because JsonPath returns an empty result
       // set.  Scalar fields always materialize with a concrete value, so
       // we only assert those paths.
-      if (isScalarBodyField(bf.type)) requiredBodyPaths.push(bf.name);
+      if (isScalarBodyField(promotedType)) requiredBodyPaths.push(bf.name);
     }
   }
 
@@ -464,7 +491,8 @@ function buildWrapperTest(op: Operation, wrapper: ResolvedWrapper, ctx: EmitterC
       argParts.push(ktStringLiteral('sample-arg'));
       continue;
     }
-    const val = synthValue(rp.field.type, ctx, imports);
+    const promotedType = promoteIso8601TypeRef(rp.field.type, rp.field.description);
+    const val = synthValue(promotedType, ctx, imports);
     if (val === null) return null;
     argParts.push(val);
   }

package/src/kotlin/wrappers.ts

@@ -1,5 +1,5 @@
 import type { EmitterContext, ResolvedOperation, ResolvedWrapper } from '@workos/oagen';
-import { className, propertyName, ktLiteral, clientFieldExpression, escapeReserved } from './naming.js';
+import { className, propertyName, ktLiteral, clientFieldExpression, escapeReserved, humanize } from './naming.js';
 import { mapTypeRef, mapTypeRefOptional } from './type-map.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
 import { sortPathParamsByTemplateOrder } from './resources.js';
@@ -35,7 +35,11 @@ function emitWrapperMethod(resolvedOp: ResolvedOperation, wrapper: ResolvedWrapp
 
   const lines: string[] = [];
 
-  // Build KDoc from operation description + @param docs for each wrapper param.
+  // Build KDoc: operation description + a `@param` line for *every* parameter
+  // (Dokka does not flag missing @param blocks, so coverage has to be enforced
+  // at emit time) + `@return` when there's a response model. Spec-provided
+  // descriptions are preferred; the fallback is templated from the parameter
+  // name so the SDK still compiles cleanly under failOnWarning.
   const kdocLines: string[] = [];
   const opDesc = (op.description ?? '').trim();
   const wrapperHumanName = method.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
@@ -45,29 +49,36 @@ function emitWrapperMethod(resolvedOp: ResolvedOperation, wrapper: ResolvedWrapp
     kdocLines.push(`${wrapperHumanName.charAt(0).toUpperCase()}${wrapperHumanName.slice(1)}.`);
   }
   const paramDocs: string[] = [];
+  const pushParamDoc = (kotlinName: string, sourceName: string, description: string | undefined) => {
+    const firstLine =
+      description
+        ?.split('\n')
+        .find((l) => l.trim())
+        ?.trim() ?? '';
+    const fallback = `the ${humanize(sourceName)} of the request.`;
+    const text = firstLine || fallback;
+    paramDocs.push(`@param ${kotlinName} ${escapeKdoc(text)}`);
+  };
   for (const pp of pathParams) {
-    if (pp.description?.trim()) {
-      paramDocs.push(`@param ${propertyName(pp.name)} ${escapeKdoc(pp.description.split('\n')[0].trim())}`);
-    }
+    pushParamDoc(propertyName(pp.name), pp.name, pp.description);
   }
   for (const rp of resolvedParams) {
-    const desc = rp.field?.description?.trim();
-    if (desc) {
-      paramDocs.push(`@param ${propertyName(rp.paramName)} ${escapeKdoc(desc.split('\n')[0])}`);
-    }
+    pushParamDoc(propertyName(rp.paramName), rp.paramName, rp.field?.description);
   }
+  // Trailing `requestOptions` parameter — stable canned phrasing.
+  pushParamDoc(
+    'requestOptions',
+    'request_options',
+    'per-request overrides (idempotency key, API key, headers, timeout)',
+  );
   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('  /**');
+  for (const l of kdocLines) lines.push(`   * ${escapeKdoc(l)}`);
+  lines.push('   *');
+  for (const p of paramDocs) lines.push(`   * ${p}`);
+  lines.push('   */');
 
   lines.push('  @JvmOverloads');
 
@@ -101,6 +112,37 @@ function emitWrapperMethod(resolvedOp: ResolvedOperation, wrapper: ResolvedWrapp
     lines.push(`  )${returnClause} {`);
   }
 
+  // The /user_management/authenticate endpoint is union-split into one
+  // wrapper per grant_type. Every variant posts the same shape (caller
+  // params + grant_type + client_id + client_secret) to the same path with
+  // the same response model, so we route through a single `authenticate(...)`
+  // private helper instead of duplicating the request boilerplate per grant.
+  const inferred = wrapper.inferFromClient ?? [];
+  const usesStandardClientCreds = inferred.includes('client_id') && inferred.includes('client_secret');
+  if (
+    op.path === '/user_management/authenticate' &&
+    op.httpMethod.toUpperCase() === 'POST' &&
+    responseClass === 'AuthenticateResponse' &&
+    typeof wrapper.defaults?.grant_type === 'string' &&
+    usesStandardClientCreds
+  ) {
+    const grantType = wrapper.defaults.grant_type;
+    lines.push(`    return authenticate(`);
+    lines.push(`      grantType = ${ktLiteral(grantType)},`);
+    lines.push(`      requestOptions = requestOptions,`);
+    const entryLines = resolvedParams.map((rp) => {
+      const paramName = propertyName(rp.paramName);
+      return `      ${ktLiteral(rp.paramName)} to ${paramName}`;
+    });
+    for (let i = 0; i < entryLines.length; i++) {
+      const sep = i === entryLines.length - 1 ? '' : ',';
+      lines.push(`${entryLines[i]}${sep}`);
+    }
+    lines.push(`    )`);
+    lines.push('  }');
+    return lines;
+  }
+
   // Build body using bodyOf() — consistent with non-wrapper methods.
   // bodyOf() automatically drops null optional values.
   const bodyEntries: string[] = [];