@workos/oagen-emitters 0.8.2 → 0.9.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.8.2"
+  ".": "0.9.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.9.0](https://github.com/workos/oagen-emitters/compare/v0.8.2...v0.9.0) (2026-05-06)
+
+
+### Features
+
+* **kotlin:** improve emitter output for SDK review feedback ([#90](https://github.com/workos/oagen-emitters/issues/90)) ([14180eb](https://github.com/workos/oagen-emitters/commit/14180eb7919a89a9b08406bc6bc06a35df887e65))
+
+
+### Bug Fixes
+
+* **kotlin:** make ktlintFormat actually run after generation ([#88](https://github.com/workos/oagen-emitters/issues/88)) ([6082a45](https://github.com/workos/oagen-emitters/commit/6082a45ab2b247bbf4630cd0acc6dba5238f5d26))
+
 ## [0.8.2](https://github.com/workos/oagen-emitters/compare/v0.8.1...v0.8.2) (2026-05-05)
 
 

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { _ as nodeEmitter, a as rustExtractor, c as pythonExtractor, d as rubyEmitter, f as kotlinEmitter, g as pythonEmitter, h as phpEmitter, i as kotlinExtractor, l as rubyExtractor, m as goEmitter, n as elixirExtractor, o as goExtractor, p as dotnetEmitter, r as dotnetExtractor, s as phpExtractor, t as workosEmittersPlugin, u as nodeExtractor } from "./plugin-CeNME04k.mjs";
+import { _ as nodeEmitter, a as rustExtractor, c as pythonExtractor, d as rubyEmitter, f as kotlinEmitter, g as pythonEmitter, h as phpEmitter, i as kotlinExtractor, l as rubyExtractor, m as goEmitter, n as elixirExtractor, o as goExtractor, p as dotnetEmitter, r as dotnetExtractor, s as phpExtractor, t as workosEmittersPlugin, u as nodeExtractor } from "./plugin-Dh9JSScr.mjs";
 export { dotnetEmitter, dotnetExtractor, elixirExtractor, goEmitter, goExtractor, kotlinEmitter, kotlinExtractor, nodeEmitter, nodeExtractor, phpEmitter, phpExtractor, pythonEmitter, pythonExtractor, rubyEmitter, rubyExtractor, rustExtractor, workosEmittersPlugin };

package/dist/{plugin-CeNME04k.mjs → plugin-Dh9JSScr.mjs}

@@ -17397,9 +17397,29 @@ function findDotnetWorkspace(targetDir) {
 }
 //#endregion
 //#region src/kotlin/naming.ts
+/**
+* Acronyms that should appear fully uppercase in PascalCase identifiers.
+* `toPascalCase` would otherwise titlecase them (e.g. `Sso`, `Pkce`, `Mfa`).
+* Both [className] and [apiClassName] consult this list so model and service
+* class names stay consistent (e.g. `SsoConnection` -> `SSOConnection`).
+*/
+const PASCAL_ACRONYMS = [
+	"SSO",
+	"PKCE",
+	"MFA"
+];
+function uppercaseAcronyms(pascal) {
+	let result = pascal;
+	for (const acronym of PASCAL_ACRONYMS) {
+		const titled = acronym.charAt(0) + acronym.slice(1).toLowerCase();
+		const re = new RegExp(`${titled}(?=[A-Z0-9]|$)`, "g");
+		result = result.replace(re, acronym);
+	}
+	return result;
+}
 /** PascalCase class/type name. */
 function className$1(name) {
-	return toPascalCase(stripUrnPrefix(name));
+	return uppercaseAcronyms(toPascalCase(stripUrnPrefix(name)));
 }
 /** camelCase method name. */
 function methodName(name) {
@@ -17417,7 +17437,6 @@ function packageSegment(name) {
 }
 /** Kotlin service class name for a mount group (e.g., `Organizations`). */
 function apiClassName(name) {
-	if (className$1(name) === "SSO") return "Sso";
 	return className$1(name);
 }
 /** Accessor property exposed on the WorkOS client (camelCase). */
@@ -17528,6 +17547,33 @@ function clientFieldExpression(field) {
 function humanize(name) {
 	return name.replace(/_/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase();
 }
+/**
+* If the parameter is typed as an enum and its description is long enough
+* that repeating it across every method's KDoc adds noise, return a short
+* description that defers to the enum's own KDoc with a `See [EnumName].`
+* reference. Otherwise return null and the caller keeps the spec text.
+*
+* Currently only `PaginationOrder` is shortened — the SSO/MFA/etc. enums
+* have brief descriptions already. Generalize when other long-description
+* enums appear in the spec.
+*/
+const LONG_ENUM_DESC_THRESHOLD = 120;
+function maybeShortenEnumParamDescription(type, description) {
+	if (!type || !description) return null;
+	const enumName = extractEnumName(type);
+	if (!enumName) return null;
+	if (description.length <= LONG_ENUM_DESC_THRESHOLD) return null;
+	if (className$1(enumName) !== "PaginationOrder") return null;
+	return {
+		description: `the order to return records in. See [${className$1(enumName)}].`,
+		enumRef: className$1(enumName)
+	};
+}
+function extractEnumName(type) {
+	if (type.kind === "enum") return type.name;
+	if (type.kind === "nullable") return extractEnumName(type.inner);
+	return null;
+}
 //#endregion
 //#region src/kotlin/enums.ts
 const KOTLIN_SRC_PREFIX$3 = "src/main/kotlin/";
@@ -17632,15 +17678,20 @@ function generateEnums$1(enums, _ctx) {
 			if (v.deprecated) members.push("  @Deprecated(\"Deprecated enum value\")");
 			members.push(`  ${memberName}(${ktStringLiteral(wire)})`);
 		}
+		let firstValueEmitted = false;
 		for (let i = 0; i < members.length; i++) {
 			const isLast = i === members.length - 1;
 			const line = members[i];
 			const trimmedStart = line.trimStart();
-			if (trimmedStart.startsWith("/**") || trimmedStart.startsWith("@")) {
+			const isDocStart = trimmedStart.startsWith("/**");
+			const isAnnotation = trimmedStart.startsWith("@");
+			if (isDocStart && firstValueEmitted) lines.push("");
+			if (isDocStart || isAnnotation) {
 				lines.push(line);
 				continue;
 			}
 			lines.push(isLast ? line : `${line},`);
+			firstValueEmitted = true;
 		}
 		lines.push("}");
 		lines.push("");
@@ -17912,6 +17963,7 @@ function emitDataClass(model) {
 		for (let i = 0; i < rendered.length; i++) {
 			const suffix = i === rendered.length - 1 ? "" : ",";
 			lines.push(`${rendered[i]}${suffix}`);
+			if (i < rendered.length - 1) lines.push("");
 		}
 		lines.push(`)${implClause}`);
 		lines.push("");
@@ -17929,7 +17981,29 @@ function emitSealedUnion(typeName, disc) {
 	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);
+	const exampleVariantWire = Object.keys(disc.mapping)[0];
+	const exampleVariantType = exampleVariantWire ? className$1(disc.mapping[exampleVariantWire]) : null;
+	lines.push("/**");
+	lines.push(` * Discriminated union over ${typeName} variants. Selected by \`${disc.property}\`.`);
+	if (exampleVariantType) {
+		lines.push(" *");
+		lines.push(" * Usage from Kotlin:");
+		lines.push(" * ```kotlin");
+		lines.push(` * when (val v: ${typeName} = receivedFromApi()) {`);
+		lines.push(` *   is ${exampleVariantType} -> handle(v)`);
+		lines.push(" *   else -> handleOther(v)");
+		lines.push(" * }");
+		lines.push(" * ```");
+		lines.push(" *");
+		lines.push(" * Usage from Java:");
+		lines.push(" * ```java");
+		lines.push(` * ${typeName} v = receivedFromApi();`);
+		lines.push(` * if (v instanceof ${exampleVariantType}) {`);
+		lines.push(` *     handle((${exampleVariantType}) v);`);
+		lines.push(" * }");
+		lines.push(" * ```");
+	}
+	lines.push(" */");
 	lines.push("@JsonTypeInfo(");
 	lines.push("  use = JsonTypeInfo.Id.NAME,");
 	lines.push("  include = JsonTypeInfo.As.EXISTING_PROPERTY,");
@@ -18230,6 +18304,81 @@ function escapeKotlinStringLiteral(literal) {
 	return literal.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\$/g, "\\$");
 }
 //#endregion
+//#region src/kotlin/suspend.ts
+/**
+* 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.
+*/
+/**
+* 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.
+*/
+function emitSuspendVariant(opts) {
+	const { methodName, params, returnType, deprecated } = opts;
+	const suspendName = `${methodName}Suspend`;
+	const lines = [];
+	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.
+*/
+const SUSPEND_IMPORTS = ["kotlinx.coroutines.Dispatchers", "kotlinx.coroutines.withContext"];
+function jvmNameLiteral(name) {
+	return JSON.stringify(name);
+}
+//#endregion
 //#region src/kotlin/wrappers.ts
 /**
 * Emit Kotlin wrapper methods for a union-split operation. Each wrapper
@@ -18262,14 +18411,16 @@ function emitWrapperMethod$1(resolvedOp, wrapper, ctx) {
 	if (opDesc) kdocLines.push(opDesc.split("\n")[0]);
 	else kdocLines.push(`${wrapperHumanName.charAt(0).toUpperCase()}${wrapperHumanName.slice(1)}.`);
 	const paramDocs = [];
-	const pushParamDoc = (kotlinName, sourceName, description) => {
+	const pushParamDoc = (kotlinName, sourceName, description, type) => {
 		const firstLine = description?.split("\n").find((l) => l.trim())?.trim() ?? "";
 		const fallback = `the ${humanize(sourceName)} of the request.`;
-		const text = firstLine || fallback;
+		let text = firstLine || fallback;
+		const shortened = maybeShortenEnumParamDescription(type, text);
+		if (shortened) text = shortened.description;
 		paramDocs.push(`@param ${kotlinName} ${escapeKdoc$1(text)}`);
 	};
-	for (const pp of pathParams) pushParamDoc(propertyName(pp.name), pp.name, pp.description);
-	for (const rp of resolvedParams) pushParamDoc(propertyName(rp.paramName), rp.paramName, rp.field?.description);
+	for (const pp of pathParams) pushParamDoc(propertyName(pp.name), pp.name, pp.description, pp.type);
+	for (const rp of resolvedParams) pushParamDoc(propertyName(rp.paramName), rp.paramName, rp.field?.description, rp.field?.type);
 	pushParamDoc("requestOptions", "request_options", "per-request overrides (idempotency key, API key, headers, timeout)");
 	if (responseClass) paramDocs.push(`@return the ${responseClass}`);
 	lines.push("  /**");
@@ -18279,14 +18430,29 @@ function emitWrapperMethod$1(resolvedOp, wrapper, ctx) {
 	lines.push("   */");
 	lines.push("  @JvmOverloads");
 	const params = [];
-	for (const pp of pathParams) params.push(`    ${propertyName(pp.name)}: String`);
+	const suspendParams = [];
+	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 ? rp.isOptional ? mapTypeRefOptional(rp.field.type) : mapTypeRef$1(rp.field.type) : rp.isOptional ? "String?" : "String";
-		const trailer = rp.isOptional ? " = null" : "";
-		params.push(`    ${paramName}: ${kotlinType}${trailer}`);
+		const decl = `    ${paramName}: ${rp.field ? rp.isOptional ? mapTypeRefOptional(rp.field.type) : mapTypeRef$1(rp.field.type) : rp.isOptional ? "String?" : "String"}${rp.isOptional ? " = null" : ""}`;
+		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) {
 		const single = params[0].replace(/^\s+/, "");
@@ -18316,6 +18482,7 @@ function emitWrapperMethod$1(resolvedOp, wrapper, ctx) {
 		}
 		lines.push(`    )`);
 		lines.push("  }");
+		appendSuspendVariant(lines, method, suspendParams, responseClass ?? "Unit");
 		return lines;
 	}
 	const bodyEntries = [];
@@ -18347,8 +18514,17 @@ function emitWrapperMethod$1(resolvedOp, wrapper, ctx) {
 	if (responseClass) lines.push(`    return workos.baseClient.request(config, ${responseClass}::class.java)`);
 	else lines.push(`    workos.baseClient.requestVoid(config)`);
 	lines.push("  }");
+	appendSuspendVariant(lines, method, suspendParams, responseClass ?? "Unit");
 	return lines;
 }
+function appendSuspendVariant(lines, method, suspendParams, returnType) {
+	lines.push("");
+	for (const ln of emitSuspendVariant({
+		methodName: method,
+		params: suspendParams,
+		returnType
+	})) lines.push(ln);
+}
 function escapeKdoc$1(s) {
 	return s.replace(/\*\//g, "*​/");
 }
@@ -18453,6 +18629,7 @@ function generateApiClass(mountName, operations, ctx, resolvedLookup) {
 	imports.add("com.workos.common.http.Page");
 	imports.add("com.workos.common.http.RequestConfig");
 	imports.add("com.workos.common.http.RequestOptions");
+	for (const imp of SUSPEND_IMPORTS) imports.add(imp);
 	const body = [];
 	const seenMethods = /* @__PURE__ */ new Set();
 	if (operations.some((op) => op.path === "/user_management/authenticate" && op.httpMethod.toUpperCase() === "POST")) {
@@ -18507,15 +18684,21 @@ function generateApiClass(mountName, operations, ctx, resolvedLookup) {
 	lines.push("");
 	for (const line of sealedLines) lines.push(line);
 	const serviceDescription = resolveServiceDescription(ctx, mountName, operations);
+	const suspendNote = "Every operation on this class is available in two flavors: a blocking variant (`<methodName>`) and a coroutine-aware variant (`<methodName>Suspend`). The `Suspend` variants delegate to the blocking ones under `withContext(Dispatchers.IO)`, so they are safe to call from any coroutine dispatcher (including `Dispatchers.Main`).";
 	if (serviceDescription) {
 		const docLines = serviceDescription.trim().split("\n");
-		if (docLines.length === 1) lines.push(`/** ${escapeKdoc(docLines[0].trim())} */`);
-		else {
-			lines.push("/**");
-			for (const l of docLines) lines.push(l ? ` * ${escapeKdoc(l)}` : " *");
-			lines.push(" */");
-		}
-	} else lines.push(`/** API accessor for ${mountName}. */`);
+		lines.push("/**");
+		for (const l of docLines) lines.push(l ? ` * ${escapeKdoc(l)}` : " *");
+		lines.push(" *");
+		lines.push(` * ${escapeKdoc(suspendNote)}`);
+		lines.push(" */");
+	} else {
+		lines.push("/**");
+		lines.push(` * API accessor for ${mountName}.`);
+		lines.push(" *");
+		lines.push(` * ${escapeKdoc(suspendNote)}`);
+		lines.push(" */");
+	}
 	lines.push(`class ${apiClass}(`);
 	lines.push("  internal val workos: WorkOS");
 	lines.push(`) {`);
@@ -18586,14 +18769,22 @@ function renderMethod(_mountName, method, op, ctx, resolvedOp, imports) {
 	}
 	const groupParamNames = assignGroupParameterNames$1(op, paramNames);
 	const params = [];
-	for (const pp of pathParams) params.push(`    ${propertyName(pp.name)}: String`);
+	const suspendParams = [];
+	const pushParam = (decl, name) => {
+		params.push(decl);
+		suspendParams.push({
+			decl,
+			name
+		});
+	};
+	for (const pp of pathParams) pushParam(`    ${propertyName(pp.name)}: String`, propertyName(pp.name));
 	const sortedQuery = [...uniqueQuery].sort((a, b) => a.required === b.required ? 0 : a.required ? -1 : 1);
-	for (const qp of sortedQuery) params.push(renderParam(qp.name, qp.type, qp.required, method.startsWith("list") && qp.name === "limit"));
+	for (const qp of sortedQuery) pushParam(renderParam(qp.name, qp.type, qp.required, method.startsWith("list") && qp.name === "limit"), propertyName(qp.name));
 	for (const group of op.parameterGroups ?? []) {
 		const sealedName = sealedGroupName$1(group.name);
 		const prop = groupParamNames.get(group.name);
-		if (group.optional) params.push(`    ${prop}: ${sealedName}? = null`);
-		else params.push(`    ${prop}: ${sealedName}`);
+		if (group.optional) pushParam(`    ${prop}: ${sealedName}? = null`, prop);
+		else pushParam(`    ${prop}: ${sealedName}`, prop);
 	}
 	const isPatch = httpMethod === "PATCH";
 	const sortedBodyFields = [...bodyFields].sort((a, b) => a.required === b.required ? 0 : a.required ? -1 : 1);
@@ -18602,10 +18793,10 @@ function renderMethod(_mountName, method, op, ctx, resolvedOp, imports) {
 		if (isPatch && !bf.required) {
 			const baseType = mapTypeRef$1(bf.type);
 			imports.add("com.workos.common.http.PatchField");
-			params.push(`    ${bodyParamNames.get(bf.name)}: PatchField<${baseType}> = PatchField.Absent`);
-		} else params.push(renderParamNamed(bodyParamNames.get(bf.name), bf.type, bf.required));
+			pushParam(`    ${bodyParamNames.get(bf.name)}: PatchField<${baseType}> = PatchField.Absent`, bodyParamNames.get(bf.name));
+		} else pushParam(renderParamNamed(bodyParamNames.get(bf.name), bf.type, bf.required), bodyParamNames.get(bf.name));
 	}
-	params.push("    requestOptions: RequestOptions? = null");
+	pushParam("    requestOptions: RequestOptions? = null", "requestOptions");
 	const returnType = resolveReturnType(plan, imports, ctx);
 	const isPaginated = plan.isPaginated && paginatedItemName !== null;
 	const lines = [];
@@ -18649,6 +18840,7 @@ function renderMethod(_mountName, method, op, ctx, resolvedOp, imports) {
 		}
 		lines.push(`    )`);
 		lines.push("  }");
+		appendSuspendVariantLines(lines, method, suspendParams, returnType, op.deprecated);
 		return lines.join("\n");
 	}
 	if (isPaginated) {
@@ -18732,8 +18924,123 @@ function renderMethod(_mountName, method, op, ctx, resolvedOp, imports) {
 		else lines.push(`    workos.baseClient.requestVoid(config)`);
 	}
 	lines.push("  }");
+	appendSuspendVariantLines(lines, method, suspendParams, returnType, op.deprecated);
+	appendJavaFriendlyVariantOverloads(lines, {
+		method,
+		op,
+		canonicalParams: suspendParams,
+		groupParamNames,
+		returnType,
+		deprecated: op.deprecated
+	});
 	return lines.join("\n");
 }
+/**
+* For each variant of every sealed-class parameter group on `op`, append a
+* Java-discoverable overload that takes the variant's flat fields directly
+* and forwards to the canonical (sealed-class) method.
+*
+* Implementation scope: when an operation has multiple parameter groups, we
+* emit overloads for each variant of each group while keeping the *other*
+* groups' sealed-class params unchanged. This avoids combinatorial explosion
+* for ops with several groups while still flattening the common case.
+*
+* Method-name derivation handles the most common variant shapes (`ById`,
+* `ByExternalId`, etc.). Other shapes (e.g. `Plaintext`, `Imported`) are
+* skipped with a comment so unusual unions don't compile-fail the SDK; if
+* one becomes important we can add an explicit case here.
+*/
+function appendJavaFriendlyVariantOverloads(lines, ctx) {
+	const groups = ctx.op.parameterGroups ?? [];
+	if (groups.length === 0) return;
+	for (const group of groups) for (const variant of group.variants) {
+		const overloadMethodName = deriveOverloadMethodName(ctx.method, variant.name);
+		if (overloadMethodName === null) continue;
+		emitOneJavaOverload(lines, ctx, group, variant, overloadMethodName);
+	}
+}
+function deriveOverloadMethodName(baseMethod, variantName) {
+	const v = className$1(variantName);
+	if (v === "ById") return baseMethod;
+	if (/^By[A-Z]/.test(v)) {
+		if (baseMethod.toLowerCase().endsWith(v.toLowerCase())) return baseMethod;
+		return `${baseMethod}${v}`;
+	}
+	return null;
+}
+function emitOneJavaOverload(lines, ctx, group, variant, overloadMethodName) {
+	const sealedName = sealedGroupName$1(group.name);
+	const variantClass = className$1(variant.name);
+	const targetGroupProp = ctx.groupParamNames.get(group.name);
+	const decls = [];
+	const existingNames = /* @__PURE__ */ new Set();
+	for (const cp of ctx.canonicalParams) if (cp.name !== targetGroupProp) existingNames.add(cp.name);
+	const variantFieldDecls = [];
+	const variantArgPairs = [];
+	for (const p of variant.parameters) {
+		const sealedField = deriveShortPropertyName(p.name, group.name);
+		let localName = sealedField;
+		if (existingNames.has(localName)) localName = `${propertyName(group.name)}${localName.charAt(0).toUpperCase()}${localName.slice(1)}`;
+		existingNames.add(localName);
+		const decl = renderParamNamed(localName, p.type, true);
+		variantFieldDecls.push({
+			decl,
+			name: localName
+		});
+		variantArgPairs.push({
+			sealedField,
+			localName
+		});
+	}
+	for (const cp of ctx.canonicalParams) if (cp.name === targetGroupProp) for (const v of variantFieldDecls) decls.push(v);
+	else decls.push({
+		decl: cp.decl,
+		name: cp.name
+	});
+	const returnClause = ctx.returnType === "Unit" ? "" : `: ${ctx.returnType}`;
+	const sealedConstruct = `${sealedName}.${variantClass}(${variantArgPairs.map((p) => `${p.sealedField} = ${p.localName}`).join(", ")})`;
+	const forwardArgs = [];
+	for (const cp of ctx.canonicalParams) if (cp.name === targetGroupProp) forwardArgs.push(`${cp.name} = ${sealedConstruct}`);
+	else forwardArgs.push(`${cp.name} = ${cp.name}`);
+	lines.push("");
+	lines.push("  /**");
+	lines.push(`   * Java-friendly overload — equivalent to`);
+	lines.push(`   * \`${ctx.method}(${sealedName}.${variantClass}(...))\` from Kotlin.`);
+	lines.push(`   *`);
+	lines.push(`   * Accepts the discriminating fields directly so Java callers don't`);
+	lines.push(`   * need to construct \`${sealedName}.${variantClass}\` explicitly.`);
+	lines.push("   */");
+	if (ctx.deprecated) lines.push("  @Deprecated(\"Deprecated operation\")");
+	if (decls.length === 1) {
+		const single = decls[0].decl.replace(/^\s+/, "");
+		lines.push(`  fun ${escapeReserved(overloadMethodName)}(${single})${returnClause} = ${ctx.method}(`);
+	} else {
+		lines.push(`  fun ${escapeReserved(overloadMethodName)}(`);
+		for (let i = 0; i < decls.length; i++) {
+			const sep = i === decls.length - 1 ? "" : ",";
+			lines.push(`${decls[i].decl}${sep}`);
+		}
+		lines.push(`  )${returnClause} = ${ctx.method}(`);
+	}
+	for (let i = 0; i < forwardArgs.length; i++) {
+		const sep = i === forwardArgs.length - 1 ? "" : ",";
+		lines.push(`    ${forwardArgs[i]}${sep}`);
+	}
+	lines.push("  )");
+	appendSuspendVariantLines(lines, overloadMethodName, decls.map((d) => ({
+		decl: d.decl,
+		name: d.name
+	})), ctx.returnType, ctx.deprecated);
+}
+function appendSuspendVariantLines(lines, method, suspendParams, returnType, deprecated) {
+	lines.push("");
+	for (const ln of emitSuspendVariant({
+		methodName: method,
+		params: suspendParams,
+		returnType,
+		deprecated
+	})) lines.push(ln);
+}
 function resolveReturnType(plan, imports, ctx) {
 	const itemName = plan.isPaginated ? resolvePaginatedItemName(plan.paginatedItemModelName, ctx) ?? plan.paginatedItemModelName : null;
 	if (plan.isPaginated && itemName) {
@@ -18786,14 +19093,14 @@ function buildMethodKdoc(op, pathParams, queryParams, bodyFields, bodyParamNames
 	if (descriptionRaw) for (const l of descriptionRaw.split("\n")) textLines.push(escapeKdoc(l));
 	const paramDocs = [];
 	const seenParamDocs = /* @__PURE__ */ new Set();
-	const pushParamDoc = (name, sourceName, description, deprecated) => {
+	const pushParamDoc = (name, sourceName, description, deprecated, type) => {
 		if (seenParamDocs.has(name)) return;
 		seenParamDocs.add(name);
-		paramDocs.push(formatParamDoc(name, description, deprecated, sourceName));
+		paramDocs.push(formatParamDoc(name, description, deprecated, sourceName, type));
 	};
-	for (const pp of pathParams) pushParamDoc(propertyName(pp.name), pp.name, pp.description, pp.deprecated);
-	for (const qp of queryParams) pushParamDoc(propertyName(qp.name), qp.name, qp.description, qp.deprecated);
-	for (const bf of bodyFields) pushParamDoc(bodyParamNames.get(bf.name), bf.name, bf.description, bf.deprecated);
+	for (const pp of pathParams) pushParamDoc(propertyName(pp.name), pp.name, pp.description, pp.deprecated, pp.type);
+	for (const qp of queryParams) pushParamDoc(propertyName(qp.name), qp.name, qp.description, qp.deprecated, qp.type);
+	for (const bf of bodyFields) pushParamDoc(bodyParamNames.get(bf.name), bf.name, bf.description, bf.deprecated, bf.type);
 	pushParamDoc("requestOptions", "request_options", REQUEST_OPTIONS_PARAM_DESCRIPTION);
 	const returnDoc = plan.isPaginated ? "@return a [com.workos.common.http.Page] of results" : plan.responseModelName ? `@return the ${plan.isArrayResponse ? `list of ${className$1(plan.responseModelName)}` : className$1(plan.responseModelName)}` : null;
 	if (!(textLines.length > 0 || paramDocs.length > 0 || returnDoc !== null)) return [];
@@ -18814,11 +19121,14 @@ function buildMethodKdoc(op, pathParams, queryParams, bodyFields, bodyParamNames
 * 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, description, deprecated, sourceName) {
+function formatParamDoc(kotlinName, description, deprecated, sourceName, type) {
 	const specText = (description?.split("\n").find((l) => l.trim()) ?? "").trim();
 	const deprecationNote = deprecated ? "**Deprecated.**" : "";
 	const fallback = `the ${humanize(sourceName ?? kotlinName)} of the request.`;
-	return `@param ${kotlinName} ${escapeKdoc([deprecationNote, specText || fallback].filter(Boolean).join(" "))}`;
+	let text = specText || fallback;
+	const shortened = maybeShortenEnumParamDescription(type, text);
+	if (shortened) text = shortened.description;
+	return `@param ${kotlinName} ${escapeKdoc([deprecationNote, text].filter(Boolean).join(" "))}`;
 }
 /**
 * Unwrap a possibly-nullable type to check if the inner type is an array,
@@ -18961,7 +19271,26 @@ function deriveShortPropertyName(paramName, groupName) {
 function generateSealedClass(group, bodyFieldTypes) {
 	const lines = [];
 	const sealedName = sealedGroupName$1(group.name);
-	lines.push(`/** Mutually exclusive ${humanize(group.name)} parameter variants. */`);
+	const example = group.variants[0];
+	if (example) {
+		const exampleVariant = className$1(example.name);
+		const exampleArgs = example.parameters.map((p) => `${deriveShortPropertyName(p.name, group.name)} = "..."`).join(", ");
+		lines.push("/**");
+		lines.push(` * Mutually exclusive ${humanize(group.name)} parameter variants.`);
+		lines.push(" *");
+		lines.push(" * Usage from Kotlin:");
+		lines.push(" * ```kotlin");
+		lines.push(` * val target: ${sealedName} = ${sealedName}.${exampleVariant}(${exampleArgs})`);
+		lines.push(" * ```");
+		lines.push(" *");
+		lines.push(" * Usage from Java:");
+		lines.push(" * ```java");
+		lines.push(` * ${sealedName} target = new ${sealedName}.${exampleVariant}(${example.parameters.map(() => "\"...\"").join(", ")});`);
+		lines.push(" * ```");
+		lines.push(" *");
+		lines.push(` * Java callers may also use the per-variant overloads on the surrounding API class to skip variant construction entirely.`);
+		lines.push(" */");
+	} else lines.push(`/** Mutually exclusive ${humanize(group.name)} parameter variants. */`);
 	lines.push(`sealed class ${sealedName} {`);
 	for (let vi = 0; vi < group.variants.length; vi++) {
 		const variant = group.variants[vi];
@@ -19084,30 +19413,36 @@ const KOTLIN_SRC_PREFIX = "src/main/kotlin/";
 * contains a `WorkOS` class stub with only these properties — the oagen
 * merger deep-merges them into the existing hand-written `WorkOS.kt`.
 *
-* Accessors use fully-qualified type names so the merger doesn't need to
-* inject imports into the hand-written file.
+* Each referenced service class is hoisted into a top-level `import` so the
+* accessor bodies use the short class name. The live `WorkOS.kt` is marked
+* `@oagen-ignore-file` and won't be regenerated, but the emitter still emits
+* the cleaner shape so future regenerations don't reintroduce the FQN noise.
 */
 function generateClient$1(spec, ctx) {
 	const targets = deduplicateByMount(spec.services, ctx);
 	if (targets.length === 0) return [];
+	const imports = /* @__PURE__ */ new Set();
 	const accessorLines = [];
 	for (const mount of targets) {
 		const apiCls = apiClassName(mount);
 		const fqn = `com.workos.${packageSegment(mount)}.${apiCls}`;
+		imports.add(fqn);
 		const prop = servicePropertyName$1(mount);
 		accessorLines.push("");
-		accessorLines.push(`  /** Lazily-constructed [${fqn}] accessor for this [WorkOS] client. */`);
-		accessorLines.push(`  val ${prop}: ${fqn}`);
+		accessorLines.push(`  /** Lazily-constructed [${apiCls}] accessor for this [WorkOS] client. */`);
+		accessorLines.push(`  val ${prop}: ${apiCls}`);
 		accessorLines.push("    get() =");
 		accessorLines.push("      service(");
-		accessorLines.push(`        ${fqn}::class`);
+		accessorLines.push(`        ${apiCls}::class`);
 		accessorLines.push("      ) {");
-		accessorLines.push(`        ${fqn}(this)`);
+		accessorLines.push(`        ${apiCls}(this)`);
 		accessorLines.push("      }");
 	}
 	const lines = [];
 	lines.push("package com.workos");
 	lines.push("");
+	for (const imp of [...imports].sort()) lines.push(`import ${imp}`);
+	if (imports.size > 0) lines.push("");
 	lines.push("open class WorkOS {");
 	for (const line of accessorLines) lines.push(line);
 	lines.push("}");
@@ -20055,11 +20390,7 @@ const kotlinEmitter = {
 		if (!fs.existsSync(path.join(targetDir, "gradlew"))) return null;
 		return {
 			cmd: "bash",
-			args: [
-				"-c",
-				`cd ${JSON.stringify(targetDir)} && ./gradlew ktlintFormat --quiet 2>/dev/null; true`,
-				"--"
-			]
+			args: ["-c", "./gradlew ktlintFormat --quiet >/dev/null 2>&1; true"]
 		};
 	}
 };
@@ -22469,4 +22800,4 @@ const workosEmittersPlugin = {
 //#endregion
 export { nodeEmitter as _, rustExtractor as a, pythonExtractor as c, rubyEmitter as d, kotlinEmitter as f, pythonEmitter as g, phpEmitter as h, kotlinExtractor as i, rubyExtractor as l, goEmitter as m, elixirExtractor as n, goExtractor as o, dotnetEmitter as p, dotnetExtractor as r, phpExtractor as s, workosEmittersPlugin as t, nodeExtractor as u };
 
-//# sourceMappingURL=plugin-CeNME04k.mjs.map
+//# sourceMappingURL=plugin-Dh9JSScr.mjs.map