@workos/oagen-emitters 0.4.0 → 0.6.0

package/src/go/tests.ts

@@ -152,6 +152,7 @@ function generateServiceTest(
 
   // Deduplicate test functions by method name
   const emittedTestMethods = new Set<string>();
+  const resolvedLookupMain = buildResolvedLookup(ctx);
   for (const op of service.operations) {
     const plan = planOperation(op);
     const method = resolveGoMethodName(op, resolvedName, ctx);
@@ -162,7 +163,38 @@ function generateServiceTest(
     if (emittedTestMethods.has(method)) continue;
     emittedTestMethods.add(method);
 
+    // Skip operations with wrapper splits — the parent method isn't emitted
+    // (see src/go/resources.ts), only the typed wrappers are tested below.
+    const resolvedMain = lookupResolved(op, resolvedLookupMain);
+    if ((resolvedMain?.wrappers?.length ?? 0) > 0) continue;
+
     const testName = `Test${accessorName}_${method}`;
+    const isUrlBuilder = resolvedMain?.urlBuilder ?? false;
+
+    if (isUrlBuilder) {
+      // URL-builder methods return a string synchronously without making
+      // an HTTP request. Assert the URL contains the expected path.
+      const expectedPath = buildExpectedPath(op);
+      // Call args: no ctx, path params (if any), then params struct.
+      const callArgs: string[] = [];
+      for (const p of sortPathParamsByTemplateOrder(op)) {
+        callArgs.push(`"test_${p.name}"`);
+      }
+      const hidden = buildHiddenParams(resolvedMain);
+      const hasVisibleQueryParams = op.queryParams.filter((qp) => !hidden.has(qp.name)).length > 0;
+      if (hasVisibleQueryParams) {
+        const pName = paramsStructName(resolvedName, method);
+        callArgs.push(`&${ctx.namespace}.${pName}{}`);
+      }
+      lines.push(`func ${testName}(t *testing.T) {`);
+      lines.push(`\tclient := ${ctx.namespace}.NewClient("sk_test", ${ctx.namespace}.WithClientID("client_test"))`);
+      lines.push(`\turl := client.${accessorName}().${method}(${callArgs.join(', ')})`);
+      lines.push('\trequire.NotEmpty(t, url)');
+      lines.push(`\trequire.Contains(t, url, "${expectedPath}")`);
+      lines.push('}');
+      lines.push('');
+      continue;
+    }
 
     if (isPaginated && op.pagination) {
       // Pagination test
@@ -371,7 +403,7 @@ function generateServiceTest(
       if (emittedTestMethods.has(wrapperMethod)) continue;
       emittedTestMethods.add(wrapperMethod);
 
-      const wrapperParamsStruct = `${wrapperMethod}Params`;
+      const wrapperParamsStruct = paramsStructName(resolvedName, wrapperMethod);
       const responseType = wrapper.responseModelName;
       const testName = `Test${accessorName}_${wrapperMethod}`;
       const fixturePath = responseType ? `testdata/${fileName(responseType)}.json` : null;
@@ -398,8 +430,12 @@ function generateServiceTest(
     }
   }
 
-  // Error test (one per file: 401)
-  const sampleOp = service.operations[0];
+  // Error test (one per file: 401). Skip wrapper-split ops (parent method
+  // isn't emitted) and URL-builder ops (no HTTP call to error-test against).
+  const sampleOp = service.operations.find((o) => {
+    const r = lookupResolved(o, resolvedLookupMain);
+    return (r?.wrappers?.length ?? 0) === 0 && !(r?.urlBuilder ?? false);
+  });
   if (sampleOp) {
     const plan = planOperation(sampleOp);
     const method = resolveGoMethodName(sampleOp, resolvedName, ctx);

package/src/go/type-map.ts

@@ -13,8 +13,10 @@ export function mapTypeRef(ref: TypeRef, asPointer = false): string {
     enum: (r) => className(r.name),
     union: (_r, variants) => joinUnionVariants(_r, variants),
     nullable: (_ref, inner) => {
-      // If inner is already a pointer type (model), don't double-pointer
-      if (inner.startsWith('*')) return inner;
+      // Slices, maps, and pointer types (models) don't get pointer-wrapped:
+      // nil slice/map + omitempty already handles absence, and double-pointers
+      // are confusing at the call site.
+      if (inner.startsWith('*') || inner.startsWith('[]') || inner.startsWith('map[')) return inner;
       return `*${inner}`;
     },
     literal: (r) => {
@@ -43,7 +45,10 @@ export function mapTypeRefValue(ref: TypeRef): string {
     model: (r) => className(r.name),
     enum: (r) => className(r.name),
     union: (_r, variants) => joinUnionVariants(_r, variants),
-    nullable: (_ref, inner) => `*${inner}`,
+    nullable: (_ref, inner) => {
+      if (inner.startsWith('*') || inner.startsWith('[]') || inner.startsWith('map[')) return inner;
+      return `*${inner}`;
+    },
     literal: (r) => {
       if (r.value === null) return 'interface{}';
       if (typeof r.value === 'string') return 'string';

package/src/go/wrappers.ts

@@ -5,7 +5,7 @@ import {
   methodName as goMethodName,
   unexportedName,
 } from './naming.js';
-import { sortPathParamsByTemplateOrder } from './resources.js';
+import { sortPathParamsByTemplateOrder, paramsStructName } from './resources.js';
 import { resolveWrapperParams, formatWrapperDescription, type ResolvedWrapperParam } from '../shared/wrapper-utils.js';
 import { lowerFirstForDoc, fieldDocComment } from '../shared/naming-utils.js';
 
@@ -20,6 +20,7 @@ import { lowerFirstForDoc, fieldDocComment } from '../shared/naming-utils.js';
  */
 export function generateWrapperMethods(
   serviceType: string,
+  mountName: string,
   resolvedOp: ResolvedOperation,
   ctx: EmitterContext,
 ): string[] {
@@ -30,20 +31,72 @@ export function generateWrapperMethods(
   for (const wrapper of resolvedOp.wrappers) {
     const wrapperParams = resolveWrapperParams(wrapper, ctx);
     lines.push('');
-    emitWrapperParamsStruct(lines, wrapper, wrapperParams);
+    emitWrapperParamsStruct(lines, mountName, wrapper, wrapperParams);
     lines.push('');
-    emitWrapperMethod(lines, serviceType, resolvedOp, wrapper, wrapperParams);
+    emitWrapperBodyStruct(lines, wrapper, wrapperParams);
+    lines.push('');
+    emitWrapperMethod(lines, serviceType, mountName, resolvedOp, wrapper, wrapperParams);
   }
 
   return lines;
 }
 
+/** Unexported struct name used as the typed JSON body for a wrapper method. */
+function wrapperBodyStructName(wrapper: ResolvedWrapper): string {
+  return `${unexportedName(goMethodName(wrapper.name))}Body`;
+}
+
+/**
+ * Emit the private body struct used to serialize the JSON request for a
+ * wrapper method. Fields come from: constant defaults, required exposed
+ * params, client-inferred fields, and optional exposed params (in that
+ * order to match how bodies are constructed at call sites).
+ */
+function emitWrapperBodyStruct(lines: string[], wrapper: ResolvedWrapper, wrapperParams: ResolvedWrapperParam[]): void {
+  const structName = wrapperBodyStructName(wrapper);
+  lines.push(`// ${structName} is the JSON request body for ${goMethodName(wrapper.name)}.`);
+  lines.push(`type ${structName} struct {`);
+
+  // Constant defaults (always sent — no omitempty so the wire format is deterministic)
+  for (const [key, value] of Object.entries(wrapper.defaults)) {
+    const goField = goFieldName(key);
+    const goType = typeof value === 'boolean' ? 'bool' : typeof value === 'number' ? 'int' : 'string';
+    lines.push(`\t${goField} ${goType} \`json:"${key}"\``);
+  }
+
+  // Required exposed params
+  for (const { paramName, field, isOptional } of wrapperParams) {
+    if (isOptional) continue;
+    const goField = goFieldName(paramName);
+    const goType = field ? resolveSimpleGoType(field.type) : 'string';
+    lines.push(`\t${goField} ${goType} \`json:"${paramName}"\``);
+  }
+
+  // Inferred fields (from client config) — omit when empty
+  for (const inferred of wrapper.inferFromClient) {
+    const goField = goFieldName(inferred);
+    lines.push(`\t${goField} string \`json:"${inferred},omitempty"\``);
+  }
+
+  // Optional exposed params
+  for (const { paramName, field, isOptional } of wrapperParams) {
+    if (!isOptional) continue;
+    const goField = goFieldName(paramName);
+    const baseType = field ? resolveSimpleGoType(field.type) : 'string';
+    const optType = baseType.startsWith('*') || baseType.startsWith('[]') ? baseType : `*${baseType}`;
+    lines.push(`\t${goField} ${optType} \`json:"${paramName},omitempty"\``);
+  }
+
+  lines.push('}');
+}
+
 function emitWrapperParamsStruct(
   lines: string[],
+  mountName: string,
   wrapper: ResolvedWrapper,
   wrapperParams: ResolvedWrapperParam[],
 ): void {
-  const structName = `${goMethodName(wrapper.name)}Params`;
+  const structName = paramsStructName(mountName, goMethodName(wrapper.name));
 
   lines.push(`// ${structName} contains the parameters for ${goMethodName(wrapper.name)}.`);
   lines.push(`type ${structName} struct {`);
@@ -73,13 +126,14 @@ function emitWrapperParamsStruct(
 function emitWrapperMethod(
   lines: string[],
   serviceType: string,
+  mountName: string,
   resolvedOp: ResolvedOperation,
   wrapper: ResolvedWrapper,
   wrapperParams: ResolvedWrapperParam[],
 ): void {
   const op = resolvedOp.operation;
   const method = goMethodName(wrapper.name);
-  const paramsStruct = `${method}Params`;
+  const paramsStruct = paramsStructName(mountName, method);
 
   // Return type
   const responseType = wrapper.responseModelName ? goClassName(wrapper.responseModelName) : null;
@@ -104,38 +158,37 @@ function emitWrapperMethod(
     lines.push(`func (s *${serviceType}) ${method}(${sigParams.join(', ')}) error {`);
   }
 
-  // Build body map with defaults + exposed params
-  lines.push('\tbody := map[string]interface{}{');
+  // Build typed body struct — defaults + required params set at literal,
+  // inferred + optional fields assigned after (conditional on presence).
+  const bodyType = wrapperBodyStructName(wrapper);
+  lines.push(`\tbody := ${bodyType}{`);
 
   // Constant defaults (e.g., grant_type)
   for (const [key, value] of Object.entries(wrapper.defaults)) {
-    lines.push(`\t\t"${key}": ${goLiteral(value)},`);
+    lines.push(`\t\t${goFieldName(key)}: ${goLiteral(value)},`);
   }
 
   // Required exposed params
   for (const { paramName, isOptional } of wrapperParams) {
     if (isOptional) continue;
     const goField = goFieldName(paramName);
-    lines.push(`\t\t"${paramName}": params.${goField},`);
+    lines.push(`\t\t${goField}: params.${goField},`);
   }
 
   lines.push('\t}');
 
-  // Inferred fields from client config
-  for (const field of wrapper.inferFromClient) {
-    const expr = clientFieldExpression(field);
-    lines.push(`\tif ${expr} != "" {`);
-    lines.push(`\t\tbody["${field}"] = ${expr}`);
-    lines.push('\t}');
+  // Inferred fields from client config — omitempty handles the unset case
+  for (const inferred of wrapper.inferFromClient) {
+    const goField = goFieldName(inferred);
+    lines.push(`\tbody.${goField} = ${clientFieldExpression(inferred)}`);
   }
 
-  // Optional exposed params
+  // Optional exposed params copy through as pointers — encoding/json +
+  // omitempty will drop nil fields on the wire.
   for (const { paramName, isOptional } of wrapperParams) {
     if (!isOptional) continue;
     const goField = goFieldName(paramName);
-    lines.push(`\tif params.${goField} != nil {`);
-    lines.push(`\t\tbody["${paramName}"] = *params.${goField}`);
-    lines.push('\t}');
+    lines.push(`\tbody.${goField} = params.${goField}`);
   }
 
   // Build path expression
@@ -145,7 +198,7 @@ function emitWrapperMethod(
     const fmtArgs: string[] = [];
     for (const p of sortPathParamsByTemplateOrder(op)) {
       fmtStr = fmtStr.replace(`{${p.name}}`, '%s');
-      fmtArgs.push(lowerFirstSafe(goFieldName(p.name)));
+      fmtArgs.push(`url.PathEscape(string(${lowerFirstSafe(goFieldName(p.name))}))`);
     }
     pathExpr = `fmt.Sprintf("${fmtStr}", ${fmtArgs.join(', ')})`;
   } else {
@@ -207,7 +260,12 @@ function resolveSimpleGoType(ref: any): string {
         return 'interface{}';
     }
   }
-  if (ref.kind === 'nullable') return `*${resolveSimpleGoType(ref.inner)}`;
+  if (ref.kind === 'nullable') {
+    const inner = resolveSimpleGoType(ref.inner);
+    // Slices, maps, and pointer types don't get pointer-wrapped (mirrors type-map.ts).
+    if (inner.startsWith('*') || inner.startsWith('[]') || inner.startsWith('map[')) return inner;
+    return `*${inner}`;
+  }
   if (ref.kind === 'array') return `[]${resolveSimpleGoType(ref.items)}`;
   if (ref.kind === 'model') return `*${goClassName(ref.name)}`;
   if (ref.kind === 'enum') return goClassName(ref.name);

package/src/index.ts

@@ -3,3 +3,17 @@ export { pythonEmitter } from './python/index.js';
 export { phpEmitter } from './php/index.js';
 export { goEmitter } from './go/index.js';
 export { dotnetEmitter } from './dotnet/index.js';
+export { kotlinEmitter } from './kotlin/index.js';
+export { rubyEmitter } from './ruby/index.js';
+
+export { nodeExtractor } from './compat/extractors/node.js';
+export { rubyExtractor } from './compat/extractors/ruby.js';
+export { pythonExtractor } from './compat/extractors/python.js';
+export { phpExtractor } from './compat/extractors/php.js';
+export { goExtractor } from './compat/extractors/go.js';
+export { rustExtractor } from './compat/extractors/rust.js';
+export { kotlinExtractor } from './compat/extractors/kotlin.js';
+export { dotnetExtractor } from './compat/extractors/dotnet.js';
+export { elixirExtractor } from './compat/extractors/elixir.js';
+
+export { workosEmittersPlugin } from './plugin.js';

package/src/kotlin/client.ts

@@ -25,9 +25,14 @@ export function generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFil
     const fqn = `com.workos.${packageSegment(mount)}.${apiCls}`;
     const prop = servicePropertyName(mount);
     accessorLines.push('');
-    accessorLines.push(`  /** Lazily-constructed [${apiCls}] accessor for this [WorkOS] client. */`);
+    accessorLines.push(`  /** Lazily-constructed [${fqn}] accessor for this [WorkOS] client. */`);
     accessorLines.push(`  val ${prop}: ${fqn}`);
-    accessorLines.push(`    get() = service(${fqn}::class) { ${fqn}(this) }`);
+    accessorLines.push('    get() =');
+    accessorLines.push('      service(');
+    accessorLines.push(`        ${fqn}::class`);
+    accessorLines.push('      ) {');
+    accessorLines.push(`        ${fqn}(this)`);
+    accessorLines.push('      }');
   }
 
   const lines: string[] = [];

package/src/kotlin/enums.ts

@@ -43,6 +43,12 @@ export function generateEnums(enums: Enum[], _ctx: EmitterContext): GeneratedFil
   const aliasOf = new Map<string, string>(); // enum name → canonical enum name
   for (const [, group] of hashGroups) {
     if (group.length <= 1) continue;
+    if (group.every(isSharedSortOrderEnum)) {
+      const [canonical, ...rest] = [...group].sort((a, b) => a.name.localeCompare(b.name));
+      enumCanonicalMap.set(canonical.name, canonical.name);
+      for (const enumDef of rest) enumCanonicalMap.set(enumDef.name, 'SortOrder');
+      continue;
+    }
     const sorted = [...group].sort(
       (a, b) =>
         className(a.name).length - className(b.name).length || className(a.name).localeCompare(className(b.name)),
@@ -59,17 +65,28 @@ export function generateEnums(enums: Enum[], _ctx: EmitterContext): GeneratedFil
   for (const enumDef of enums) {
     if (enumDef.values.length === 0) continue;
 
-    const typeName = className(enumDef.name);
+    const typeName = canonicalEnumTypeName(enumDef);
 
     // Non-canonical enum: emit a typealias instead of a full enum class.
-    const canonicalName = aliasOf.get(enumDef.name);
+    const sharedSortEmitter = isSharedSortOrderEnum(enumDef) && enumCanonicalMap.get(enumDef.name) === enumDef.name;
+    const canonicalName = sharedSortEmitter
+      ? undefined
+      : (aliasOf.get(enumDef.name) ?? enumCanonicalMap.get(enumDef.name));
     if (canonicalName) {
       const canonicalType = className(canonicalName);
+      // Skip when different IR names collapse to the same output name
+      if (typeName === canonicalType) continue;
       const aliasLine = `typealias ${typeName} = ${canonicalType}`;
       // ktlint enforces a 140-char max line length. When the typealias
       // exceeds that, add a @file:Suppress to avoid an unfixable violation.
       const suppressLine = aliasLine.length > 140 ? `@file:Suppress("ktlint:standard:max-line-length")\n\n` : '';
-      const aliasContent = [`${suppressLine}package ${ENUMS_PACKAGE}`, '', aliasLine, ''].join('\n');
+      const aliasContent = [
+        `${suppressLine}package ${ENUMS_PACKAGE}`,
+        '',
+        `/** Alias for [${canonicalType}]. */`,
+        aliasLine,
+        '',
+      ].join('\n');
       files.push({
         path: `${KOTLIN_SRC_PREFIX}${ENUMS_DIR}/${typeName}.kt`,
         content: aliasContent,
@@ -89,6 +106,7 @@ export function generateEnums(enums: Enum[], _ctx: EmitterContext): GeneratedFil
     // sentinel for values the server introduces after this SDK was built.
     lines.push(`/** Enumeration of valid ${typeName} values returned or accepted by the API. */`);
     lines.push(`enum class ${typeName}(`);
+    lines.push('  /** The wire value sent to and received from the API. */');
     lines.push('  @JsonValue val value: String');
     lines.push(') {');
     // `@JsonEnumDefaultValue` makes Jackson's
@@ -149,6 +167,15 @@ export function generateEnums(enums: Enum[], _ctx: EmitterContext): GeneratedFil
   return files;
 }
 
+function canonicalEnumTypeName(enumDef: Enum): string {
+  return isSharedSortOrderEnum(enumDef) ? 'SortOrder' : className(enumDef.name);
+}
+
+function isSharedSortOrderEnum(enumDef: Enum): boolean {
+  const wireValues = [...new Set(enumDef.values.map((value) => String(value.value).toLowerCase()))].sort();
+  return wireValues.length === 2 && wireValues[0] === 'asc' && wireValues[1] === 'desc';
+}
+
 /** Hash an enum by its sorted wire values so identical enums collide. */
 function enumWireHash(enumDef: Enum): string {
   return [...enumDef.values]

package/src/kotlin/index.ts

@@ -16,7 +16,7 @@ import { generateEnums } from './enums.js';
 import { generateResources } from './resources.js';
 import { generateClient } from './client.js';
 import { generateTests } from './tests.js';
-import { generateManifest } from './manifest.js';
+import { buildOperationsMap } from './manifest.js';
 import { enrichModelsFromSpec, getSyntheticEnums } from '../shared/model-utils.js';
 
 /** Ensure every generated file ends with a trailing newline. */
@@ -69,8 +69,8 @@ export const kotlinEmitter: Emitter = {
     return ensureTrailingNewlines(generateTests(enrichedSpec, { ...ctx, spec: enrichedSpec }));
   },
 
-  generateManifest(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
-    return ensureTrailingNewlines(generateManifest(spec, ctx));
+  buildOperationsMap(spec: ApiSpec, ctx: EmitterContext) {
+    return buildOperationsMap(spec, ctx);
   },
 
   fileHeader(): string {

package/src/kotlin/manifest.ts

@@ -1,20 +1,20 @@
-import type { ApiSpec, EmitterContext, GeneratedFile } from '@workos/oagen';
+import type { ApiSpec, EmitterContext, OperationsMap } 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`).
+ * Build the operation-to-SDK-method mapping for the manifest.
+ *
+ * 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.
+ * manifest emits an array of methods 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 }[]> =
-    {};
+export function buildOperationsMap(spec: ApiSpec, ctx: EmitterContext): OperationsMap {
+  const manifest: OperationsMap = {};
   const resolvedLookup = buildResolvedLookup(ctx);
 
   for (const service of spec.services) {
@@ -45,11 +45,5 @@ export function generateManifest(spec: ApiSpec, ctx: EmitterContext): GeneratedF
     }
   }
 
-  return [
-    {
-      path: 'smoke-manifest.json',
-      content: JSON.stringify(manifest, null, 2),
-      integrateTarget: false,
-    },
-  ];
+  return manifest;
 }

package/src/kotlin/models.ts

@@ -1,6 +1,6 @@
 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 { className, propertyName, ktStringLiteral, humanize } from './naming.js';
 import { enumCanonicalMap } from './enums.js';
 import { isListWrapperModel, isListMetadataModel } from '../shared/model-utils.js';
 
@@ -86,10 +86,14 @@ export function generateModels(models: Model[], _ctx: EmitterContext): Generated
 
     const canonical = aliasOf.get(model.name);
     if (canonical) {
+      const canonicalType = className(canonical);
+      // Skip when different IR names collapse to the same output name
+      if (typeName === canonicalType) continue;
       const aliasContent = [
         `package ${MODELS_PACKAGE}`,
         '',
-        `typealias ${typeName} = ${className(canonical)}`,
+        `/** Alias for [${canonicalType}]. */`,
+        `typealias ${typeName} = ${canonicalType}`,
         '',
       ].join('\n');
       files.push({
@@ -103,6 +107,23 @@ export function generateModels(models: Model[], _ctx: EmitterContext): Generated
     files.push(emitDataClass(model));
   }
 
+  // Generate the sealed WorkOSEvent interface. Collect all event envelope
+  // models that have a literal `event` field and build the @JsonSubTypes
+  // mapping so Jackson can deserialize directly to the correct concrete type.
+  const eventMapping: Array<{ wireValue: string; modelName: string }> = [];
+  for (const model of models) {
+    if (isListWrapperModel(model) || isListMetadataModel(model)) continue;
+    if (aliasOf.has(model.name)) continue;
+    if (!isEventEnvelopeModel(model)) continue;
+    const eventField = model.fields.find((f) => f.name === 'event');
+    if (eventField && eventField.type.kind === 'literal' && typeof eventField.type.value === 'string') {
+      eventMapping.push({ wireValue: eventField.type.value, modelName: model.name });
+    }
+  }
+  if (eventMapping.length > 0) {
+    files.push(emitWorkOSEvent(eventMapping));
+  }
+
   return files;
 }
 
@@ -119,7 +140,7 @@ 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');
+  // WorkOSEvent sealed interface is generated in the same package — no import needed.
   const lines: string[] = [];
   lines.push(`package ${MODELS_PACKAGE}`);
   lines.push('');
@@ -202,6 +223,74 @@ function emitSealedUnion(
   };
 }
 
+/**
+ * Emit the sealed `WorkOSEvent` interface with Jackson discriminated
+ * deserialization. Each concrete event model (UserCreated, DsyncUserUpdated,
+ * etc.) already extends this interface. The `@JsonSubTypes` annotation lets
+ * Jackson pick the right subclass when deserializing JSON with an `event`
+ * discriminator field. `EventSchema` is the fallback for unknown event types.
+ */
+function emitWorkOSEvent(eventMapping: Array<{ wireValue: string; modelName: 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('import java.time.OffsetDateTime');
+  lines.push('');
+
+  lines.push('/**');
+  lines.push(' * Sealed interface for all webhook/event envelope models.');
+  lines.push(' *');
+  lines.push(' * Jackson deserializes incoming event JSON to the correct concrete type');
+  lines.push(' * based on the `event` discriminator field. Unknown event types fall back');
+  lines.push(' * to [EventSchema] with untyped `data: Map<String, Any>`.');
+  lines.push(' *');
+  lines.push(' * ```kotlin');
+  lines.push(' * val event: WorkOSEvent = objectMapper.readValue(json, WorkOSEvent::class.java)');
+  lines.push(' * when (event) {');
+  lines.push(' *   is UserCreated -> println("User created: ${event.data.id}")');
+  lines.push(' *   is EventSchema -> println("Unknown event: ${event.event}")');
+  lines.push(' * }');
+  lines.push(' * ```');
+  lines.push(' */');
+
+  lines.push('@JsonTypeInfo(');
+  lines.push('  use = JsonTypeInfo.Id.NAME,');
+  lines.push('  include = JsonTypeInfo.As.EXISTING_PROPERTY,');
+  lines.push('  property = "event",');
+  lines.push('  visible = true,');
+  lines.push('  defaultImpl = EventSchema::class');
+  lines.push(')');
+  lines.push('@JsonSubTypes(');
+  // Sort entries for stable output
+  const sorted = [...eventMapping].sort((a, b) => a.wireValue.localeCompare(b.wireValue));
+  for (let i = 0; i < sorted.length; i++) {
+    const { wireValue, modelName } = sorted[i];
+    const typeName = className(modelName);
+    const suffix = i === sorted.length - 1 ? '' : ',';
+    lines.push(`  JsonSubTypes.Type(value = ${typeName}::class, name = ${ktStringLiteral(wireValue)})${suffix}`);
+  }
+  lines.push(')');
+  lines.push('sealed interface WorkOSEvent {');
+  lines.push('  /** Unique identifier for this event. */');
+  lines.push('  val id: String');
+  lines.push('');
+  lines.push('  /** The event type identifier. */');
+  lines.push('  val event: String');
+  lines.push('');
+  lines.push('  /** Timestamp when the event was created. */');
+  lines.push('  val createdAt: OffsetDateTime');
+  lines.push('}');
+  lines.push('');
+
+  return {
+    path: `${KOTLIN_SRC_PREFIX}${MODELS_DIR}/WorkOSEvent.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[] = [];
@@ -234,9 +323,9 @@ function renderFields(fields: Field[], overrideFields: Set<string> = new Set()):
 
     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');
+    // Omit @JvmField so Kotlin generates proper getter methods (getId(),
+    // 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")');
 
@@ -246,6 +335,8 @@ function renderFields(fields: Field[], overrideFields: Set<string> = new Set()):
       lines.push(`  /** ${escapeKdoc(line.trim())} */`);
     } else if (literalDefault !== null) {
       lines.push(`  /** Always \`${literalDefault}\`. */`);
+    } else {
+      lines.push(`  /** The ${humanize(field.name)}. */`);
     }
     for (const anno of annotations) lines.push(`  ${anno}`);
 

package/src/kotlin/naming.ts

@@ -25,7 +25,12 @@ export function methodName(name: string): string {
 
 /** camelCase Kotlin property / local variable name. */
 export function propertyName(name: string): string {
-  return escapeReserved(toCamelCase(name));
+  const camel = toCamelCase(name);
+  // `object` is a Kotlin reserved word. Instead of backtick-escaping it
+  // (forcing callers to write `event.\`object\``), rename to `objectType`
+  // and rely on @JsonProperty("object") for wire mapping.
+  if (camel === 'object') return 'objectType';
+  return escapeReserved(camel);
 }
 
 /** camelCase alias (kept for parity with other emitters). */
@@ -45,6 +50,7 @@ export function packageSegment(name: string): string {
 
 /** Kotlin service class name for a mount group (e.g., `Organizations`). */
 export function apiClassName(name: string): string {
+  if (className(name) === 'SSO') return 'Sso';
   return className(name);
 }