@workos/oagen-emitters 0.8.0 → 0.8.2

package/dist/plugin.mjs

@@ -1,2 +1,2 @@
-import { t as workosEmittersPlugin } from "./plugin-bCMdV7KX.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.0",
+  "version": "0.8.2",
   "description": "WorkOS' oagen emitters",
   "license": "MIT",
   "author": "WorkOS",

package/src/dotnet/index.ts

@@ -133,8 +133,11 @@ export const dotnetEmitter: Emitter = {
         lines.push('    {');
         lines.push('        public override bool CanConvert(Type objectType) => objectType == typeof(object);');
         lines.push('');
+        // Override returns `object?` to match Newtonsoft.Json 13+'s nullable
+        // signature; `JToken.ToObject<T>` is itself `T?`, so a non-nullable
+        // override would trigger CS8603 under <Nullable>enable</Nullable>.
         lines.push(
-          '        public override object ReadJson(Newtonsoft.Json.JsonReader reader, Type objectType, object? existingValue, Newtonsoft.Json.JsonSerializer serializer)',
+          '        public override object? ReadJson(Newtonsoft.Json.JsonReader reader, Type objectType, object? existingValue, Newtonsoft.Json.JsonSerializer serializer)',
         );
         lines.push('        {');
         lines.push('            var jObject = JObject.Load(reader);');
@@ -194,8 +197,9 @@ export const dotnetEmitter: Emitter = {
         `        public override bool CanConvert(Type objectType) => typeof(${baseClass}).IsAssignableFrom(objectType);`,
       );
       lines.push('');
+      // See first converter — `object?` matches Newtonsoft 13+ to avoid CS8603.
       lines.push(
-        '        public override object ReadJson(Newtonsoft.Json.JsonReader reader, Type objectType, object? existingValue, Newtonsoft.Json.JsonSerializer serializer)',
+        '        public override object? ReadJson(Newtonsoft.Json.JsonReader reader, Type objectType, object? existingValue, Newtonsoft.Json.JsonSerializer serializer)',
       );
       lines.push('        {');
       lines.push('            var jObject = JObject.Load(reader);');

package/src/dotnet/models.ts

@@ -7,6 +7,7 @@ import {
   emitJsonPropertyAttributes,
   setModelAliases,
   isModelAlias,
+  resolveModelName,
 } from './type-map.js';
 import {
   articleFor,
@@ -54,6 +55,17 @@ export function generateModels(models: Model[], ctx: EmitterContext, discCtx?: D
     }
   }
 
+  const files: GeneratedFile[] = [];
+
+  // Compute and publish model aliases so mapTypeRef rewrites references.
+  // Must run BEFORE collectRequestBodyOnlyModelNames so the body/non-body
+  // tally collapses aliased pairs onto their canonical name — otherwise a
+  // model that's only a request body in name (e.g. `AddRolePermissionDto`)
+  // but is the canonical for a field-referenced alias (e.g. `SlimRole`)
+  // would be wrongly classified as body-only and skipped from emission,
+  // leaving every alias-rewritten field reference dangling.
+  primeModelAliases(models);
+
   // Models that are referenced ONLY as an operation request body (not by any
   // response, field, or other operation type) are dead surface in .NET because
   // the wrapper generator emits a per-operation `*Options` class containing
@@ -63,11 +75,6 @@ export function generateModels(models: Model[], ctx: EmitterContext, discCtx?: D
   // `UserManagementCreateApiKeyOptions`). Skip emission for those.
   const requestBodyOnlyNames = collectRequestBodyOnlyModelNames(ctx.spec.services, models);
 
-  const files: GeneratedFile[] = [];
-
-  // Compute and publish model aliases so mapTypeRef rewrites references.
-  primeModelAliases(models);
-
   // Build a lookup of base model field C# names → C# types for inheritance.
   // Variant models skip inherited fields and use `new` for type-divergent ones.
   const baseFieldLookup = new Map<string, Map<string, string>>();
@@ -453,17 +460,22 @@ function collectRequestBodyOnlyModelNames(services: Service[], models: Model[]):
   const requestBodyNames = new Set<string>();
   const otherReferences = new Set<string>();
 
+  // Resolve every reference through the alias map so structurally-identical
+  // models share a body/non-body classification. Without this, an alias being
+  // used as a field would only mark the alias name as non-body — leaving its
+  // canonical (which carries the same shape and gets emitted) wrongly tagged
+  // as body-only and skipped.
   const collect = (ref: TypeRef | undefined, into: Set<string>): void => {
     if (!ref) return;
     walkTypeRef(ref, {
-      model: (r) => into.add(r.name),
+      model: (r) => into.add(resolveModelName(r.name)),
     });
   };
 
   for (const service of services) {
     for (const op of service.operations) {
       if (op.requestBody?.kind === 'model') {
-        requestBodyNames.add(op.requestBody.name);
+        requestBodyNames.add(resolveModelName(op.requestBody.name));
       }
       collect(op.response, otherReferences);
       if (op.pagination) collect(op.pagination.itemType, otherReferences);

package/src/go/fixtures.ts

@@ -46,7 +46,12 @@ export function generateFixtures(spec: { models: Model[]; enums: Enum[]; service
     });
   }
 
-  // Generate list fixtures for paginated responses
+  // Generate list fixtures for paginated responses. Multiple operations may
+  // share the same item model (e.g. several role-assignment list endpoints all
+  // returning UserRoleAssignmentList) — emit each fixture path once so the
+  // content-dedup pass below doesn't see N copies of the same path and drop
+  // the file entirely.
+  const seenListPaths = new Set<string>();
   for (const service of spec.services) {
     for (const op of service.operations) {
       if (op.pagination) {
@@ -55,6 +60,9 @@ export function generateFixtures(spec: { models: Model[]; enums: Enum[]; service
           const unwrapped = unwrapListModel(itemModel, modelMap);
           if (unwrapped) itemModel = unwrapped;
           if (itemModel.fields.length === 0) continue;
+          const path = `testdata/list_${fileName(itemModel.name)}.json`;
+          if (seenListPaths.has(path)) continue;
+          seenListPaths.add(path);
           const fixture = generateModelFixture(itemModel, modelMap, enumMap);
           const listFixture = {
             data: [fixture],
@@ -64,7 +72,7 @@ export function generateFixtures(spec: { models: Model[]; enums: Enum[]; service
             },
           };
           files.push({
-            path: `testdata/list_${fileName(itemModel.name)}.json`,
+            path,
             content: JSON.stringify(listFixture, null, 2),
           });
         }

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);
   }