@workos/oagen-emitters 0.14.4 → 0.15.1

package/src/node/tests.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import type { ApiSpec, Service, Operation, Model, TypeRef, EmitterContext, GeneratedFile } from '@workos/oagen';
-import { planOperation, toCamelCase } from '@workos/oagen';
+import { planOperation, toCamelCase, toPascalCase } from '@workos/oagen';
 import { unwrapListModel, ID_PREFIXES } from './fixtures.js';
 import {
   fieldName,
@@ -27,13 +27,17 @@ import {
   computeNonEventReachable,
 } from './utils.js';
 import { groupByMount } from '../shared/resolved-ops.js';
-import { isNodeOwnedService } from './options.js';
+import { isNodeOwnedService, nodeOptions } from './options.js';
 
 type BaselineMethod = {
   params: Array<{ name: string; type: string; optional?: boolean; passingStyle?: string }>;
   returnType?: string;
 };
 
+function operationOverrideFor(ctx: EmitterContext, op: Operation) {
+  return nodeOptions(ctx).operationOverrides?.[`${op.httpMethod.toUpperCase()} ${op.path}`];
+}
+
 function baselineMethodFor(service: Service, method: string, ctx: EmitterContext): BaselineMethod | undefined {
   const serviceClass = resolveResourceClassName(service, ctx);
   return ctx.apiSurface?.classes?.[serviceClass]?.methods?.[method]?.[0] as BaselineMethod | undefined;
@@ -48,6 +52,48 @@ function optionsObjectParam(method: BaselineMethod | undefined): { name: string;
   return { name: param.name, type: param.type };
 }
 
+function configuredOptionsMethod(ctx: EmitterContext, op: Operation): BaselineMethod | undefined {
+  const optionsType = operationOverrideFor(ctx, op)?.optionsType;
+  if (!optionsType) return undefined;
+  return {
+    params: [{ name: 'options', type: optionsType, passingStyle: 'options_object' }],
+  };
+}
+
+function methodOptionsName(method: string, serviceClass: string): string {
+  if (method === 'list') return `${toPascalCase(serviceClass)}ListOptions`;
+  return `${toPascalCase(method)}Options`;
+}
+
+function hasOptionsInput(op: Operation, plan: any): boolean {
+  return op.pathParams.length > 0 || plan.hasBody || plan.isPaginated || op.queryParams.length > 0;
+}
+
+function optionsMethodFor(
+  service: Service,
+  method: string,
+  op: Operation,
+  plan: any,
+  ctx: EmitterContext,
+): BaselineMethod | undefined {
+  const baseline = baselineMethodFor(service, method, ctx);
+  if (optionsObjectParam(baseline)) return baseline;
+
+  const configured = configuredOptionsMethod(ctx, op);
+  if (configured) return configured;
+
+  if (!hasOptionsInput(op, plan)) return baseline;
+  return {
+    params: [
+      {
+        name: 'options',
+        type: methodOptionsName(method, resolveResourceClassName(service, ctx)),
+        passingStyle: 'options_object',
+      },
+    ],
+  };
+}
+
 function autoPaginatableItemType(returnType: string | undefined): string | undefined {
   return returnType?.match(/\bAutoPaginatable<\s*([A-Za-z_$][\w$]*)/)?.[1];
 }
@@ -249,7 +295,7 @@ function generateServiceTest(
   lines.push('  beforeEach(() => fetch.resetMocks());');
 
   for (const { op, plan, method } of plans) {
-    const existingMethod = baselineMethodFor(service, method, ctx);
+    const existingMethod = optionsMethodFor(service, method, op, plan, ctx);
     lines.push('');
     lines.push(`  describe('${method}', () => {`);
 
@@ -447,6 +493,13 @@ function renderBodyTest(
     lines.push('      expect(Array.isArray(result)).toBe(true);');
   }
 
+  const override = ctx ? operationOverrideFor(ctx, op) : undefined;
+  if (override?.returnExpression || override?.returnDataProperty) {
+    lines.push('      expect(result).toBeDefined();');
+    lines.push('    });');
+    return;
+  }
+
   // Use entity helper if available, otherwise inline assertions
   const bodyHelperName = ctx ? `expect${resolveInterfaceName(responseModelName, ctx)}` : null;
   if (bodyHelperName && entityHelpers?.has(bodyHelperName)) {
@@ -503,6 +556,19 @@ function renderGetTest(
     lines.push('      expect(Array.isArray(result)).toBe(true);');
   }
 
+  const returnDataProperty = ctx ? operationOverrideFor(ctx, op)?.returnDataProperty : undefined;
+  if (returnDataProperty) {
+    const responseModel = modelMap.get(responseModelName);
+    const returnedField = responseModel?.fields.find((field) => fieldName(field.name) === returnDataProperty);
+    if (returnedField?.type.kind === 'array') {
+      lines.push('      expect(Array.isArray(result)).toBe(true);');
+    } else {
+      lines.push('      expect(result).toBeDefined();');
+    }
+    lines.push('    });');
+    return;
+  }
+
   // Use entity helper if available, otherwise inline assertions
   const helperName = ctx ? `expect${resolveInterfaceName(responseModelName, ctx)}` : null;
   if (helperName && entityHelpers?.has(helperName)) {
@@ -575,14 +641,43 @@ function buildOptionsObjectTestArg(
     entries.push(`${optionField}: ${JSON.stringify(pathParamTestValue(param, localName))}`);
   }
 
+  if (plan.isPaginated) {
+    entries.push("order: 'desc'");
+  }
+  const queryParams = plan.isPaginated
+    ? op.queryParams.filter((param) => !['limit', 'before', 'after', 'order'].includes(param.name))
+    : op.queryParams;
+  for (const param of queryParams) {
+    const localName = fieldName(param.name);
+    const value = fixtureValueForType(param.type, param.name, 'Options', modelMap) ?? "'test'";
+    entries.push(`${localName}: ${value}`);
+  }
+
   if (plan.hasBody) {
     const payload = buildTestPayload(op, modelMap);
-    if (payload) entries.push(...objectLiteralEntries(payload.camelCaseObj));
+    if (payload) {
+      const bodyFieldMap = ctx ? operationOverrideFor(ctx, op)?.bodyFieldMap : undefined;
+      entries.push(...mapBodyOptionEntries(objectLiteralEntries(payload.camelCaseObj), bodyFieldMap));
+    } else if (entries.length === 0) {
+      return '({} as any)';
+    }
   }
 
   return `{ ${entries.join(', ')} }`;
 }
 
+function mapBodyOptionEntries(entries: string[], bodyFieldMap: Record<string, string> | undefined): string[] {
+  const reverseMap = new Map(Object.entries(bodyFieldMap ?? {}).map(([source, target]) => [target, source]));
+  if (reverseMap.size === 0) return entries;
+
+  return entries.map((entry) => {
+    const match = entry.match(/^([A-Za-z_$][\w$]*)\s*:/);
+    if (!match) return entry;
+    const source = reverseMap.get(match[1]);
+    return source ? entry.replace(match[1], source) : entry;
+  });
+}
+
 function objectLiteralEntries(literal: string): string[] {
   const trimmed = literal.trim();
   if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) return [];
@@ -693,7 +788,12 @@ function buildFieldAssertions(model: Model, accessor: string, modelMap?: Map<str
         // Objects and arrays need toEqual with JSON serialization
         assertions.push(`expect(${accessor}.${domainField}).toEqual(${JSON.stringify(field.example)});`);
       } else {
-        const exampleLiteral = typeof field.example === 'string' ? `'${field.example}'` : String(field.example);
+        const exampleLiteral =
+          isDateTime && typeof field.example === 'string'
+            ? `'${new Date(field.example).toISOString()}'`
+            : typeof field.example === 'string'
+              ? `'${field.example}'`
+              : String(field.example);
         assertions.push(`expect(${fieldAccessor}).toBe(${exampleLiteral});`);
       }
       continue;
@@ -739,7 +839,7 @@ function fixtureValueForType(
 ): string | null {
   switch (ref.kind) {
     case 'primitive':
-      return fixtureValueForPrimitive(ref.type, ref.format, name, modelName);
+      return fixtureValueForPrimitive(ref.type, ref.format, name, modelName, wire);
     case 'literal':
       return typeof ref.value === 'string' ? `'${ref.value}'` : String(ref.value);
     case 'enum':
@@ -781,10 +881,11 @@ function fixtureValueForPrimitive(
   format: string | undefined,
   name: string,
   modelName: string,
+  wire?: boolean,
 ): string | null {
   switch (type) {
     case 'string':
-      if (format === 'date-time') return "'2023-01-01T00:00:00.000Z'";
+      if (format === 'date-time') return wire ? "'2023-01-01T00:00:00.000Z'" : "new Date('2023-01-01T00:00:00.000Z')";
       if (format === 'date') return "'2023-01-01'";
       if (format === 'uuid') return "'00000000-0000-0000-0000-000000000000'";
       if (name === 'id') {

package/src/php/fixtures.ts

@@ -1,5 +1,6 @@
 import type { Model, TypeRef, Enum } from '@workos/oagen';
 import { isListMetadataModel, isListWrapperModel } from './models.js';
+import { collectNonPaginatedResponseModelNames, collectReferencedListMetadataModels } from '../shared/model-utils.js';
 import { snakeName } from './naming.js';
 
 /**
@@ -34,9 +35,11 @@ export function generateFixtures(spec: {
   const modelMap = new Map(spec.models.map((m) => [m.name, m]));
   const enumMap = new Map(spec.enums.map((e) => [e.name, e]));
   const files: { path: string; content: string }[] = [];
+  const nonPaginatedRefs = collectNonPaginatedResponseModelNames(spec.services);
+  const listMetadataNeeded = collectReferencedListMetadataModels(spec.models, nonPaginatedRefs);
 
   for (const model of spec.models) {
-    if (isListMetadataModel(model)) continue;
+    if (isListMetadataModel(model) && !listMetadataNeeded.has(model.name)) continue;
     if (isListWrapperModel(model)) continue;
 
     const fixture = generateModelFixture(model, modelMap, enumMap);

package/src/php/models.ts

@@ -8,6 +8,7 @@ import {
   isListMetadataModel,
   isListWrapperModel,
   collectNonPaginatedResponseModelNames,
+  collectReferencedListMetadataModels,
 } from '../shared/model-utils.js';
 export { isListMetadataModel, isListWrapperModel };
 
@@ -40,9 +41,10 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
   // for `GET /vault/v1/kv/{id}/versions`) must still be emitted — the resource
   // code references them by name and the pagination iterator doesn't unwrap them.
   const nonPaginatedRefs = collectNonPaginatedResponseModelNames(ctx.spec.services);
+  const listMetadataNeeded = collectReferencedListMetadataModels(models, nonPaginatedRefs);
 
   for (const model of models) {
-    if (isListMetadataModel(model)) continue;
+    if (isListMetadataModel(model) && !listMetadataNeeded.has(model.name)) continue;
     if (isListWrapperModel(model) && !nonPaginatedRefs.has(model.name)) continue;
     const name = className(model.name);
     const lines: string[] = [];

package/src/php/resources.ts

@@ -1,4 +1,12 @@
-import type { Service, Operation, Model, EmitterContext, GeneratedFile, ResolvedOperation } from '@workos/oagen';
+import type {
+  Service,
+  Operation,
+  Model,
+  EmitterContext,
+  GeneratedFile,
+  ResolvedOperation,
+  Parameter,
+} from '@workos/oagen';
 import { planOperation, toCamelCase, toPascalCase } from '@workos/oagen';
 import { mapTypeRef, mapTypeRefForPHPDoc } from './type-map.js';
 import { className, fieldName, resolveMethodName, buildExportedClassNameSet, resolveServiceTarget } from './naming.js';
@@ -243,7 +251,8 @@ function generateMethod(
   ]);
 
   const isRedirect = isRedirectEndpoint(op, resolvedOp);
-  const params = buildMethodParams(op, plan, modelMap, ctx, hiddenParams);
+  const materializeQueryDefaults = !isRedirect;
+  const params = buildMethodParams(op, plan, modelMap, ctx, hiddenParams, { materializeQueryDefaults });
   const returnType = isRedirect ? 'string' : getReturnType(plan, ctx);
 
   // PHPDoc block
@@ -302,9 +311,10 @@ function generateMethod(
     const phpName = fieldName(q.name);
     if (seenDocParams.has(phpName)) continue;
     seenDocParams.add(phpName);
-    // Spec-defaulted enum params are non-nullable (the signature default is the
-    // enum case, never null). Without a spec default, the param is nullable.
-    const hasEnumDefault = q.default != null && q.type.kind === 'enum';
+    // Spec-defaulted enum params on HTTP calls are non-nullable because the
+    // signature default is the enum case. URL builders keep them nullable so
+    // omitted optional query params stay omitted from the generated URL.
+    const hasEnumDefault = shouldMaterializeQueryDefault(q, materializeQueryDefaults);
     const nullSuffix = !q.required && !hasEnumDefault && !docType.endsWith('|null') ? '|null' : '';
     const prefix = q.deprecated ? '(deprecated) ' : '';
     let desc = q.description ? ` ${prefix}${q.description}` : q.deprecated ? ' (deprecated)' : '';
@@ -358,7 +368,7 @@ function generateMethod(
 
   if (isRedirect) {
     // Redirect endpoint: construct URL client-side instead of making HTTP request
-    const queryLines = buildQueryArray(op, hiddenParams);
+    const queryLines = buildQueryArray(op, hiddenParams, { materializeQueryDefaults });
     const hasDefaults = Object.keys(getOpDefaults(resolvedOp)).length > 0;
     const hasInferred = getOpInferFromClient(resolvedOp).length > 0;
     const hasGroups = (op.parameterGroups?.length ?? 0) > 0;
@@ -617,6 +627,7 @@ function buildMethodParams(
   modelMap: Map<string, Model>,
   ctx: EmitterContext,
   hiddenParams?: Set<string>,
+  opts?: { materializeQueryDefaults?: boolean },
 ): string[] {
   // Collect all params into required/optional buckets to avoid
   // PHP's "required after optional" deprecation.
@@ -684,7 +695,7 @@ function buildMethodParams(
     usedNames.add(phpName);
     if (q.required) {
       required.push(`${phpType} $${phpName}`);
-    } else if (q.default != null && q.type.kind === 'enum') {
+    } else if (shouldMaterializeQueryDefault(q, opts?.materializeQueryDefaults ?? true)) {
       // Spec-provided default for an enum-typed param: emit a non-nullable
       // typed default (e.g. PaginationOrder $order = PaginationOrder::Desc).
       // Only enums are safe to default this way — primitives stay nullable so
@@ -748,7 +759,17 @@ function isEnumType(ref: import('@workos/oagen').TypeRef): boolean {
   return false;
 }
 
-function buildQueryArray(op: Operation, hiddenParams?: Set<string>): string[] {
+function isDateTimeType(ref: import('@workos/oagen').TypeRef): boolean {
+  if (ref.kind === 'primitive' && ref.format === 'date-time') return true;
+  if (ref.kind === 'nullable') return isDateTimeType(ref.inner);
+  return false;
+}
+
+function buildQueryArray(
+  op: Operation,
+  hiddenParams?: Set<string>,
+  opts?: { materializeQueryDefaults?: boolean },
+): string[] {
   const hidden = hiddenParams ?? new Set();
   const groupedParams = collectGroupedParamNames(op);
   return op.queryParams
@@ -756,16 +777,24 @@ function buildQueryArray(op: Operation, hiddenParams?: Set<string>): string[] {
     .map((q) => {
       const phpName = fieldName(q.name);
       if (isEnumType(q.type)) {
-        // Mirrors the signature: enum params with a spec default are
-        // non-nullable, so we can dereference ->value without the nullsafe op.
-        const hasEnumDefault = q.default != null && q.type.kind === 'enum';
+        // Mirrors the signature: only materialized enum defaults are
+        // non-nullable, so other optional enum params use the nullsafe op.
+        const hasEnumDefault = shouldMaterializeQueryDefault(q, opts?.materializeQueryDefaults ?? true);
         const nullsafe = q.required || hasEnumDefault ? '' : '?';
         return `'${q.name}' => $${phpName}${nullsafe}->value,`;
       }
+      if (isDateTimeType(q.type)) {
+        const nullsafe = q.required ? '' : '?';
+        return `'${q.name}' => $${phpName}${nullsafe}->format(\\DateTimeInterface::RFC3339_EXTENDED),`;
+      }
       return `'${q.name}' => $${phpName},`;
     });
 }
 
+function shouldMaterializeQueryDefault(param: Parameter, enabled: boolean): boolean {
+  return enabled && param.default != null && param.type.kind === 'enum';
+}
+
 function phpLiteral(value: unknown): string {
   if (typeof value === 'string') return `'${value}'`;
   if (typeof value === 'number') return String(value);

package/src/php/tests.ts

@@ -375,9 +375,15 @@ function buildTestArgs(
   return args.join(', ');
 }
 
-function generateTestValue(ref: { kind: string; type?: string; name?: string }, ctx?: EmitterContext): string {
+function generateTestValue(
+  ref: { kind: string; type?: string; name?: string; format?: string },
+  ctx?: EmitterContext,
+): string {
   switch (ref.kind) {
     case 'primitive':
+      if (ref.format === 'date-time') {
+        return "new \\DateTimeImmutable('2023-01-01T00:00:00Z')";
+      }
       switch (ref.type) {
         case 'string':
           return "'test_value'";
@@ -529,17 +535,21 @@ function emitQueryAssertions(lines: string[], op: Operation, ctx: EmitterContext
         lines.push(`        $this->assertSame('${e.values[0].value}', $query['${q.name}']);`);
       }
     } else if (innerType.kind === 'primitive') {
-      switch (innerType.type) {
-        case 'string':
-          lines.push(`        $this->assertSame('test_value', $query['${q.name}']);`);
-          break;
-        case 'integer':
-        case 'number':
-          lines.push(`        $this->assertArrayHasKey('${q.name}', $query);`);
-          break;
-        case 'boolean':
-          lines.push(`        $this->assertArrayHasKey('${q.name}', $query);`);
-          break;
+      if ((innerType as { format?: string }).format === 'date-time') {
+        lines.push(`        $this->assertArrayHasKey('${q.name}', $query);`);
+      } else {
+        switch (innerType.type) {
+          case 'string':
+            lines.push(`        $this->assertSame('test_value', $query['${q.name}']);`);
+            break;
+          case 'integer':
+          case 'number':
+            lines.push(`        $this->assertArrayHasKey('${q.name}', $query);`);
+            break;
+          case 'boolean':
+            lines.push(`        $this->assertArrayHasKey('${q.name}', $query);`);
+            break;
+        }
       }
     }
   }

package/src/python/client.ts

@@ -32,14 +32,6 @@ const PYTHON_NON_SPEC_WIRING: Record<string, PythonNonSpecWiring> = {
     ctorArg: 'self',
     docstring: 'Passwordless authentication sessions.',
   },
-  vault: {
-    importLine: 'from .vault import AsyncVault, Vault',
-    prop: 'vault',
-    syncClass: 'Vault',
-    asyncClass: 'AsyncVault',
-    ctorArg: 'self',
-    docstring: 'Vault encryption, key management, and secret storage.',
-  },
   actions: {
     importLine: 'from .actions import Actions, AsyncActions',
     prop: 'actions',

package/src/python/enums.ts

@@ -49,18 +49,29 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       const canonicalCls = className(canonicalName);
       const aliasCls = className(enumDef.name);
       const lines: string[] = [];
-      lines.push('from typing import TypeAlias');
       // Use explicit __all__ to prevent ruff F401 from stripping the re-export
       // Always use direct file import to avoid barrel dependency on the canonical
       if (canonicalDir === dirName) {
+        lines.push('from typing import TypeAlias');
         lines.push(`from .${fileName(canonicalName)} import ${canonicalCls}`);
+        lines.push('');
+        lines.push(`${aliasCls}: TypeAlias = ${canonicalCls}`);
       } else {
-        lines.push(
-          `from ${ctx.namespace}.${dirToModule(canonicalDir)}.models.${fileName(canonicalName)} import ${canonicalCls}`,
-        );
+        // Cross-service enum aliases use TYPE_CHECKING + __getattr__ to avoid
+        // circular imports caused by service __init__.py eagerly re-exporting
+        // all models (e.g. common → radar → common cycle).
+        const modPath = `${ctx.namespace}.${dirToModule(canonicalDir)}.models.${fileName(canonicalName)}`;
+        lines.push('from typing import TYPE_CHECKING');
+        lines.push('');
+        lines.push('if TYPE_CHECKING:');
+        lines.push(`    from ${modPath} import ${canonicalCls} as ${aliasCls}`);
+        lines.push('else:');
+        lines.push('    def __getattr__(name: str):');
+        lines.push(`        if name == "${aliasCls}":`);
+        lines.push(`            from ${modPath} import ${canonicalCls}`);
+        lines.push(`            return ${canonicalCls}`);
+        lines.push('        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")');
       }
-      lines.push('');
-      lines.push(`${aliasCls}: TypeAlias = ${canonicalCls}`);
       lines.push(`__all__ = ["${aliasCls}"]`);
       files.push({
         path: `src/${ctx.namespace}/${dirName}/models/${fileName(enumDef.name)}.py`,
@@ -71,19 +82,34 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
 
       // Also generate compat alias files for dedup aliases (they may have compat aliases too)
       for (const aliasName of compatAliases.get(enumDef.name) ?? []) {
-        const importLine =
-          canonicalDir === dirName
-            ? `from .${fileName(canonicalName)} import ${canonicalCls}`
-            : `from ${ctx.namespace}.${dirToModule(canonicalDir)}.models.${fileName(canonicalName)} import ${canonicalCls}`;
-        files.push({
-          path: `src/${ctx.namespace}/${dirName}/models/${fileName(aliasName)}.py`,
-          content: [
+        let compatContent: string;
+        if (canonicalDir === dirName) {
+          compatContent = [
             'from typing import TypeAlias',
-            importLine,
+            `from .${fileName(canonicalName)} import ${canonicalCls}`,
             '',
             `${aliasName}: TypeAlias = ${canonicalCls}`,
             `__all__ = ["${aliasName}"]`,
-          ].join('\n'),
+          ].join('\n');
+        } else {
+          const modPath = `${ctx.namespace}.${dirToModule(canonicalDir)}.models.${fileName(canonicalName)}`;
+          compatContent = [
+            'from typing import TYPE_CHECKING',
+            '',
+            'if TYPE_CHECKING:',
+            `    from ${modPath} import ${canonicalCls} as ${aliasName}`,
+            'else:',
+            '    def __getattr__(name: str):',
+            `        if name == "${aliasName}":`,
+            `            from ${modPath} import ${canonicalCls}`,
+            `            return ${canonicalCls}`,
+            '        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")',
+            `__all__ = ["${aliasName}"]`,
+          ].join('\n');
+        }
+        files.push({
+          path: `src/${ctx.namespace}/${dirName}/models/${fileName(aliasName)}.py`,
+          content: compatContent,
           integrateTarget: true,
           overwriteExisting: true,
         });

package/src/python/fixtures.ts

@@ -117,7 +117,7 @@ export function generateModelFixture(
     // Use the original field name as the wire key (matches from_dict access patterns)
     const wireName = field.name;
     if (field.example !== undefined) {
-      fixture[wireName] = field.example;
+      fixture[wireName] = normalizeDateTimeExample(field, field.example);
     } else {
       fixture[wireName] = generateFieldValue(field.type, field.name, model.name, modelMap, enumMap);
     }
@@ -129,12 +129,10 @@ export function generateModelFixture(
     const variantModel = modelMap.get(variantName);
     if (variantModel) {
       for (const field of variantModel.fields) {
-        if (!(field.name in fixture)) {
-          fixture[field.name] =
-            field.example !== undefined
-              ? field.example
-              : generateFieldValue(field.type, field.name, model.name, modelMap, enumMap);
-        }
+        fixture[field.name] =
+          field.example !== undefined
+            ? normalizeDateTimeExample(field, field.example)
+            : generateFieldValue(field.type, field.name, variantName, modelMap, enumMap);
       }
     }
   }
@@ -187,6 +185,24 @@ function generateFieldValue(
   }
 }
 
+/**
+ * Normalize date-time example values to millisecond precision so that
+ * round-trip tests (from_dict → to_dict) produce identical output.
+ * Python's _format_datetime always serializes with milliseconds.
+ */
+function normalizeDateTimeExample(
+  field: { type: { kind: string; format?: string; type?: string; inner?: any } },
+  value: any,
+): any {
+  if (typeof value !== 'string') return value;
+  const ref = field.type.kind === 'nullable' ? field.type.inner : field.type;
+  if (ref?.kind !== 'primitive' || ref?.type !== 'string' || ref?.format !== 'date-time') return value;
+  const match = value.match(/^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(\.\d+)?(Z|[+-]\d{2}:\d{2})$/);
+  if (!match) return value;
+  const [, prefix, , suffix] = match;
+  return `${prefix}.000${suffix}`;
+}
+
 function generatePrimitiveValue(type: string, format: string | undefined, name: string, modelName: string): any {
   switch (type) {
     case 'string':

package/src/python/models.ts

@@ -51,6 +51,12 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
   // otherwise the wrapper's module imports a class that was never written.
   const listMetadataNeeded = collectReferencedListMetadataModels(models, nonPaginatedRefs);
 
+  // Discriminator model names — fields referencing these should use the Variant union type
+  const discriminatorNames = new Set<string>();
+  for (const m of models) {
+    if ((m as any).discriminator) discriminatorNames.add(m.name);
+  }
+
   for (const model of models) {
     // Skip list wrapper models (e.g., OrganizationList) — SyncPage handles envelopes
     if (isListWrapperModel(model) && !nonPaginatedRefs.has(model.name)) continue;
@@ -201,7 +207,6 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
       const canonicalClassName = className(canonicalName);
       const lines: string[] = [];
       lines.push('from typing import TypeAlias');
-      // Always use direct file import to avoid barrel dependency on the canonical
       if (canonicalDir === dirName) {
         lines.push(`from .${fileName(canonicalName)} import ${canonicalClassName}`);
       } else {
@@ -274,11 +279,15 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
         if (modelName === model.name) continue; // skip self
         const modelService = modelToService.get(modelName);
         const modelDir = resolveDir(modelService);
+        // For discriminator models, also import the Variant type alias (lives in same file)
+        const importNames = discriminatorNames.has(modelName)
+          ? `${className(modelName)}, ${className(modelName)}Variant`
+          : className(modelName);
         if (modelDir === dirName) {
-          lines.push(`from .${fileName(modelName)} import ${className(modelName)}`);
+          lines.push(`from .${fileName(modelName)} import ${importNames}`);
         } else {
           lines.push(
-            `from ${ctx.namespace}.${dirToModule(modelDir)}.models.${fileName(modelName)} import ${className(modelName)}`,
+            `from ${ctx.namespace}.${dirToModule(modelDir)}.models.${fileName(modelName)} import ${importNames}`,
           );
         }
       }
@@ -321,9 +330,21 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     const requiredFields = deduplicatedFields.filter((f) => !isOptionalField(model.name, f, ctx));
     const optionalFields = deduplicatedFields.filter((f) => isOptionalField(model.name, f, ctx));
 
+    // Rewrite discriminator model references to their Variant union type.
+    // E.g. `"ConnectApplication"` → `"ConnectApplicationVariant"`
+    const rewriteDiscriminatorType = (typeStr: string): string => {
+      for (const discName of discriminatorNames) {
+        const quoted = `"${className(discName)}"`;
+        if (typeStr.includes(quoted)) {
+          typeStr = typeStr.replace(quoted, `"${className(discName)}Variant"`);
+        }
+      }
+      return typeStr;
+    };
+
     for (const field of requiredFields) {
       const pyFieldName = fieldName(field.name);
-      const pyType = resolveModelFieldType(field.type);
+      const pyType = rewriteDiscriminatorType(resolveModelFieldType(field.type));
       if (field.description || field.deprecated) {
         const parts: string[] = [];
         if (field.description) parts.push(field.description);
@@ -339,7 +360,7 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
       const pyFieldName = fieldName(field.name);
       const innerType =
         field.type.kind === 'nullable' ? resolveModelFieldType(field.type.inner) : resolveModelFieldType(field.type);
-      const pyType = `Optional[${innerType}]`;
+      const pyType = `Optional[${rewriteDiscriminatorType(innerType)}]`;
       if (field.description || field.deprecated) {
         const parts: string[] = [];
         if (field.description) parts.push(field.description);