@workos/oagen-emitters 0.8.1 → 0.9.0

package/src/kotlin/suspend.ts

@@ -0,0 +1,96 @@
+/**
+ * Helpers for emitting `suspend` overloads alongside every generated
+ * blocking SDK method. The suspend variant simply delegates to the blocking
+ * implementation under `withContext(Dispatchers.IO)`, so callers can invoke
+ * any operation from a coroutine context without blocking the calling
+ * dispatcher.
+ *
+ * Naming: the suspend variant uses a `Suspend`-suffixed Kotlin source name
+ * (e.g. `deleteEndpointSuspend`). This matters because Kotlin does not let
+ * a `suspend` function and a non-`suspend` function with the same name and
+ * identical value parameters coexist in the same scope — they are not
+ * distinguishable at call sites, even with `@JvmName`. (`@JvmName` only
+ * disambiguates JVM signatures, not Kotlin source names.) Naming the suspend
+ * variant explicitly sidesteps the conflict and makes the choice between
+ * blocking and suspending callable obvious at the call site. The matching
+ * `@JvmName("...Suspend")` is now technically redundant but kept for
+ * explicit clarity in Java interop / tooling.
+ */
+
+import { escapeReserved } from './naming.js';
+
+export interface SuspendParam {
+  /** Already-rendered "name: Type" or "name: Type = default" Kotlin declaration. */
+  decl: string;
+  /** Bare parameter name to forward to the blocking version. */
+  name: string;
+}
+
+/**
+ * Emit a suspend overload that delegates to a blocking method.
+ *
+ * The emitted lines preserve the parameter declarations (including default
+ * values) so callers can invoke the suspend variant with named arguments and
+ * skip optional parameters, just as they do with the blocking version.
+ *
+ * The emitted suspend method is named `${methodName}Suspend` (a distinct
+ * Kotlin source name from the blocking method) — see the file-level KDoc for
+ * why this is required.
+ */
+export function emitSuspendVariant(opts: {
+  methodName: string;
+  params: SuspendParam[];
+  returnType: string;
+  deprecated?: boolean;
+}): string[] {
+  const { methodName, params, returnType, deprecated } = opts;
+  const suspendName = `${methodName}Suspend`;
+  const lines: string[] = [];
+
+  lines.push('  /**');
+  lines.push(`   * Coroutine-aware variant of [${escapeReserved(methodName)}]. Use this from`);
+  lines.push('   * a `suspend` function or coroutine scope.');
+  lines.push('   *');
+  lines.push(`   * Delegates to the blocking [${escapeReserved(methodName)}] under`);
+  lines.push('   * `withContext(Dispatchers.IO)`, so this is safe to call from any');
+  lines.push('   * coroutine dispatcher (including `Dispatchers.Main`).');
+  lines.push('   */');
+  if (deprecated) lines.push('  @Deprecated("Deprecated operation")');
+  lines.push(`  @JvmName(${jvmNameLiteral(suspendName)})`);
+
+  const returnClause = returnType === 'Unit' ? '' : `: ${returnType}`;
+  const callArgs = params.map((p) => p.name).join(', ');
+
+  if (params.length === 0) {
+    lines.push(`  suspend fun ${escapeReserved(suspendName)}()${returnClause} = withContext(Dispatchers.IO) {`);
+    lines.push(`    ${escapeReserved(methodName)}()`);
+    lines.push('  }');
+    return lines;
+  }
+
+  if (params.length === 1) {
+    const single = params[0].decl.replace(/^\s+/, '');
+    lines.push(
+      `  suspend fun ${escapeReserved(suspendName)}(${single})${returnClause} = withContext(Dispatchers.IO) {`,
+    );
+  } else {
+    lines.push(`  suspend fun ${escapeReserved(suspendName)}(`);
+    for (let i = 0; i < params.length; i++) {
+      const suffix = i === params.length - 1 ? '' : ',';
+      lines.push(`${params[i].decl}${suffix}`);
+    }
+    lines.push(`  )${returnClause} = withContext(Dispatchers.IO) {`);
+  }
+  lines.push(`    ${escapeReserved(methodName)}(${callArgs})`);
+  lines.push('  }');
+  return lines;
+}
+
+/**
+ * Imports a service file needs to declare any suspend overloads.
+ */
+export const SUSPEND_IMPORTS: readonly string[] = ['kotlinx.coroutines.Dispatchers', 'kotlinx.coroutines.withContext'];
+
+function jvmNameLiteral(name: string): string {
+  return JSON.stringify(name);
+}

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,9 +1,18 @@
 import type { EmitterContext, ResolvedOperation, ResolvedWrapper } from '@workos/oagen';
-import { className, propertyName, ktLiteral, clientFieldExpression, escapeReserved } from './naming.js';
+import {
+  className,
+  propertyName,
+  ktLiteral,
+  clientFieldExpression,
+  escapeReserved,
+  humanize,
+  maybeShortenEnumParamDescription,
+} from './naming.js';
 import { mapTypeRef, mapTypeRefOptional } from './type-map.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
 import { sortPathParamsByTemplateOrder } from './resources.js';
 import { buildKotlinPathExpression } from './path-expression.js';
+import { emitSuspendVariant, type SuspendParam } from './suspend.js';
 
 /**
  * Emit Kotlin wrapper methods for a union-split operation. Each wrapper
@@ -35,7 +44,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,35 +58,57 @@ 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,
+    type?: import('@workos/oagen').TypeRef,
+  ) => {
+    const firstLine =
+      description
+        ?.split('\n')
+        .find((l) => l.trim())
+        ?.trim() ?? '';
+    const fallback = `the ${humanize(sourceName)} of the request.`;
+    let text = firstLine || fallback;
+    const shortened = maybeShortenEnumParamDescription(type, text);
+    if (shortened) text = shortened.description;
+    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, pp.type);
   }
   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, rp.field?.type);
   }
+  // 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');
 
-  // Build the method parameter list: path params, wrapper params, requestOptions
+  // Build the method parameter list: path params, wrapper params, requestOptions.
+  // `suspendParams` mirrors `params` but tracks the bare parameter name so the
+  // suspend overload (emitted at the end of this function) can forward each
+  // argument to the blocking implementation.
   const params: string[] = [];
-  for (const pp of pathParams) params.push(`    ${propertyName(pp.name)}: String`);
+  const suspendParams: SuspendParam[] = [];
+  for (const pp of pathParams) {
+    const decl = `    ${propertyName(pp.name)}: String`;
+    params.push(decl);
+    suspendParams.push({ decl, name: propertyName(pp.name) });
+  }
   for (const rp of resolvedParams) {
     const paramName = propertyName(rp.paramName);
     const kotlinType = rp.field
@@ -84,9 +119,12 @@ function emitWrapperMethod(resolvedOp: ResolvedOperation, wrapper: ResolvedWrapp
         ? 'String?'
         : 'String';
     const trailer = rp.isOptional ? ' = null' : '';
-    params.push(`    ${paramName}: ${kotlinType}${trailer}`);
+    const decl = `    ${paramName}: ${kotlinType}${trailer}`;
+    params.push(decl);
+    suspendParams.push({ decl, name: paramName });
   }
   params.push('    requestOptions: RequestOptions? = null');
+  suspendParams.push({ decl: '    requestOptions: RequestOptions? = null', name: 'requestOptions' });
 
   const returnClause = responseClass ? `: ${responseClass}` : '';
   if (params.length === 1) {
@@ -101,6 +139,38 @@ 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('  }');
+    appendSuspendVariant(lines, method, suspendParams, responseClass ?? 'Unit');
+    return lines;
+  }
+
   // Build body using bodyOf() — consistent with non-wrapper methods.
   // bodyOf() automatically drops null optional values.
   const bodyEntries: string[] = [];
@@ -149,9 +219,22 @@ function emitWrapperMethod(resolvedOp: ResolvedOperation, wrapper: ResolvedWrapp
   }
 
   lines.push('  }');
+  appendSuspendVariant(lines, method, suspendParams, responseClass ?? 'Unit');
   return lines;
 }
 
+function appendSuspendVariant(
+  lines: string[],
+  method: string,
+  suspendParams: SuspendParam[],
+  returnType: string,
+): void {
+  lines.push('');
+  for (const ln of emitSuspendVariant({ methodName: method, params: suspendParams, returnType })) {
+    lines.push(ln);
+  }
+}
+
 function escapeKdoc(s: string): string {
   return s.replace(/\*\//g, '*\u200b/');
 }

package/test/kotlin/resources.test.ts

@@ -103,7 +103,7 @@ describe('kotlin/resources', () => {
       ],
     };
     const files = generateResources(services, { ...ctxFor(services), spec: spec as ApiSpec });
-    const ssoFile = files.find((file) => file.path.endsWith('/Sso.kt'));
+    const ssoFile = files.find((file) => file.path.endsWith('/SSO.kt'));
     expect(ssoFile).toBeDefined();
     expect(ssoFile!.content).toContain('fun getProfileAndToken(');
     expect(ssoFile!.content).toContain('code: String');
@@ -236,4 +236,97 @@ describe('kotlin/resources', () => {
     expect(sortOrder!.content).toContain('enum class SortOrder');
     expect(aliases.length).toBeLessThanOrEqual(1);
   });
+
+  it('emits a coroutine-friendly suspend overload alongside every blocking method', () => {
+    const services: Service[] = [
+      {
+        name: 'Users',
+        operations: [
+          {
+            name: 'getUser',
+            httpMethod: 'get',
+            path: '/users/{id}',
+            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'primitive', type: 'unknown' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ];
+    const files = generateResources(services, ctxFor(services));
+    const file = files.find((f) => f.path.endsWith('/Users.kt'))!;
+    expect(file.content).toContain('import kotlinx.coroutines.Dispatchers');
+    expect(file.content).toContain('import kotlinx.coroutines.withContext');
+    expect(file.content).toContain('@JvmName("getSuspend")');
+    expect(file.content).toMatch(/suspend fun getSuspend\([\s\S]*?withContext\(Dispatchers\.IO\)/);
+  });
+
+  it('emits Java-friendly per-variant overloads for sealed-class parameter groups', () => {
+    const services: Service[] = [
+      {
+        name: 'Authorization',
+        operations: [
+          {
+            name: 'check',
+            httpMethod: 'post',
+            path: '/authorization/check',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            requestBody: { kind: 'model', name: 'CheckRequest' },
+            response: { kind: 'primitive', type: 'unknown' },
+            errors: [],
+            injectIdempotencyKey: false,
+            parameterGroups: [
+              {
+                name: 'resource_target',
+                optional: false,
+                variants: [
+                  {
+                    name: 'ById',
+                    parameters: [{ name: 'resource_id', type: { kind: 'primitive', type: 'string' }, required: true }],
+                  },
+                  {
+                    name: 'ByExternalId',
+                    parameters: [
+                      { name: 'resource_external_id', type: { kind: 'primitive', type: 'string' }, required: true },
+                      { name: 'resource_type_slug', type: { kind: 'primitive', type: 'string' }, required: true },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ];
+    const spec = {
+      ...baseSpec,
+      services,
+      models: [
+        ...baseSpec.models,
+        {
+          name: 'CheckRequest',
+          fields: [],
+        },
+      ],
+    };
+    const files = generateResources(services, { ...ctxFor(services), spec: spec as ApiSpec });
+    const file = files.find((f) => f.path.endsWith('/Authorization.kt'))!;
+    // The canonical method still takes the sealed class.
+    expect(file.content).toMatch(/fun check\([\s\S]*?resourceTarget: ResourceTarget[\s\S]*?\)/);
+    // Java-friendly ById overload — keeps the base method name and takes the
+    // flat resource_id field.
+    expect(file.content).toMatch(/fun check\([\s\S]*?resourceId: String[\s\S]*?\) = check\(/);
+    // Java-friendly ByExternalId overload — uses the variant suffix.
+    expect(file.content).toMatch(/fun checkByExternalId\([\s\S]*?resourceExternalId: String/);
+    expect(file.content).toContain('ResourceTarget.ById(resourceId = resourceId)');
+    expect(file.content).toContain('Java-friendly overload');
+    // The sealed class itself carries Kotlin + Java construction examples.
+    expect(file.content).toContain('Usage from Kotlin:');
+    expect(file.content).toContain('Usage from Java:');
+  });
 });