@workos/oagen-emitters 0.10.0 → 0.11.0

package/dist/plugin.mjs

@@ -1,2 +1,2 @@
-import { t as workosEmittersPlugin } from "./plugin-H0KhxbN7.mjs";
+import { t as workosEmittersPlugin } from "./plugin-DW3cnedr.mjs";
 export { workosEmittersPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos/oagen-emitters",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "WorkOS' oagen emitters",
   "license": "MIT",
   "author": "WorkOS",
@@ -54,6 +54,6 @@
     "node": ">=24.10.0"
   },
   "dependencies": {
-    "@workos/oagen": "^0.18.0"
+    "@workos/oagen": "^0.18.1"
   }
 }

package/src/go/models.ts

@@ -198,7 +198,16 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     lines.push('');
   }
 
-  // Emit shared PaginationParams struct for list operations to embed
+  // Emit shared PaginationParams struct for list operations to embed.
+  //
+  // The Order field's type is derived from the spec rather than hardcoded:
+  // when every paginated `order` query parameter $refs the same top-level
+  // enum (typically `PaginationOrder` in the WorkOS spec), we emit the typed
+  // enum so callers get compile-time validation. Otherwise we fall back to
+  // *string. The fallback handles older specs that don't lift the enum into a
+  // named component schema.
+  const orderEnumType = detectSharedOrderEnum(ctx.spec.services);
+  const orderGoType = orderEnumType ? `*${className(orderEnumType)}` : '*string';
   lines.push('// PaginationParams contains common pagination parameters for list operations.');
   lines.push('type PaginationParams struct {');
   lines.push('\t// Before is a cursor for reverse pagination.');
@@ -207,8 +216,8 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
   lines.push('\tAfter *string `url:"after,omitempty" json:"-"`');
   lines.push('\t// Limit is the maximum number of items to return per page.');
   lines.push('\tLimit *int `url:"limit,omitempty" json:"-"`');
-  lines.push('\t// Order is the sort order for results (asc or desc).');
-  lines.push('\tOrder *string `url:"order,omitempty" json:"-"`');
+  lines.push('\t// Order is the sort order for results.');
+  lines.push(`\tOrder ${orderGoType} \`url:"order,omitempty" json:"-"\``);
   lines.push('}');
   lines.push('');
 
@@ -311,6 +320,42 @@ function lowerFirst(s: string): string {
   return lowerFirstForDoc(s);
 }
 
+/**
+ * If every paginated list operation's `order` query parameter $refs the same
+ * top-level enum, return that enum's IR name. Otherwise return null. When
+ * the spec is consistent this lifts `PaginationParams.Order` from `*string`
+ * to `*PaginationOrder` (or whatever the spec calls it), giving callers
+ * compile-time validation.
+ *
+ * We require strict consistency: if any operation uses a primitive string for
+ * `order`, or two operations reference different enums, we conservatively
+ * stay on `*string` so the shared struct doesn't lie about its accepted
+ * values.
+ */
+function detectSharedOrderEnum(services: Service[]): string | null {
+  let candidate: string | null = null;
+  let sawAny = false;
+  for (const service of services) {
+    for (const op of service.operations) {
+      if (!op.pagination) continue;
+      const orderParam = op.queryParams.find((p) => p.name === 'order');
+      if (!orderParam) continue;
+      sawAny = true;
+      const enumName = unwrapEnumName(orderParam.type);
+      if (!enumName) return null;
+      if (candidate === null) candidate = enumName;
+      else if (candidate !== enumName) return null;
+    }
+  }
+  return sawAny ? candidate : null;
+}
+
+function unwrapEnumName(ref: TypeRef): string | null {
+  if (ref.kind === 'enum') return ref.name;
+  if (ref.kind === 'nullable') return unwrapEnumName(ref.inner);
+  return null;
+}
+
 /**
  * Extract a deprecation reason from a field description.
  * Looks for patterns like "Use X instead", "Replaced by Y", etc.

package/src/php/models.ts

@@ -221,15 +221,19 @@ function generateFromArrayValue(ref: TypeRef, accessor: string): string {
       return generateFromArrayValue(ref.inner, accessor);
     case 'union': {
       // Discriminated union: dispatch via match() on the discriminator
-      // property to call the matching variant's fromArray. Unknown values
-      // pass through as raw arrays so callers can introspect.
+      // property to call the matching variant's fromArray. An unknown
+      // discriminator value would otherwise assign a raw array to a typed
+      // property and crash later with a confusing TypeError, so throw
+      // immediately with the offending value.
       if (ref.discriminator && ref.discriminator.mapping) {
         const entries = Object.entries(ref.discriminator.mapping);
         if (entries.length > 0) {
           const arms = entries
             .map(([value, modelName]) => `'${value}' => ${className(modelName)}::fromArray(${accessor})`)
             .join(', ');
-          return `match (${accessor}['${ref.discriminator.property}'] ?? null) { ${arms}, default => ${accessor} }`;
+          const discProp = ref.discriminator.property;
+          const throwArm = `default => throw new \\UnexpectedValueException(sprintf('Unknown ${discProp}: %s', json_encode(${accessor}['${discProp}'] ?? null)))`;
+          return `match (${accessor}['${discProp}'] ?? null) { ${arms}, ${throwArm} }`;
         }
       }
       const resolved = resolveDegenerateUnion(ref);
@@ -313,6 +317,26 @@ function generateToArrayValue(ref: TypeRef, accessor: string, nullable = false):
     case 'union': {
       const resolved = resolveDegenerateUnion(ref);
       if (resolved) return generateToArrayValue(resolved, accessor, nullable);
+      // Polymorphic union of model variants: PHP dispatches to the concrete
+      // instance's toArray() at runtime, so a single ->toArray() call serializes
+      // any branch correctly without a match here.
+      if (ref.variants.every((v) => v.kind === 'model')) {
+        return `${accessor}${ns}->toArray()`;
+      }
+      // Heterogeneous unions involving models or enums have no uniform
+      // serialization strategy (->toArray() vs ->value vs raw scalar), so fail
+      // at codegen time rather than silently emitting a raw object that breaks
+      // the toArray contract. Pure scalar unions (e.g. string|int) fall
+      // through to the bare accessor below — that is correct.
+      if (ref.variants.some((v) => v.kind === 'model' || v.kind === 'enum')) {
+        const summary = ref.variants
+          .map((v) => (v.kind === 'model' ? `model:${v.name}` : v.kind === 'enum' ? `enum:${v.name}` : v.kind))
+          .join(' | ');
+        throw new Error(
+          `[php emitter] Cannot generate toArray for heterogeneous union: ${summary}. ` +
+            `Unions must be all-model or all-scalar; mixed and all-enum unions are not yet supported.`,
+        );
+      }
       return accessor;
     }
     case 'literal':

package/src/php/resources.ts

@@ -301,9 +301,10 @@ function generateMethod(
     const phpName = fieldName(q.name);
     if (seenDocParams.has(phpName)) continue;
     seenDocParams.add(phpName);
-    // order params with enum defaults are non-nullable (they default to Desc, not null)
-    const isNonNullableOrder = q.name === 'order' && q.type.kind === 'enum';
-    const nullSuffix = !q.required && !isNonNullableOrder && !docType.endsWith('|null') ? '|null' : '';
+    // 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';
+    const nullSuffix = !q.required && !hasEnumDefault && !docType.endsWith('|null') ? '|null' : '';
     const prefix = q.deprecated ? '(deprecated) ' : '';
     let desc = q.description ? ` ${prefix}${q.description}` : q.deprecated ? ' (deprecated)' : '';
     if (q.default != null) desc += ` Defaults to ${JSON.stringify(q.default)}.`;
@@ -682,16 +683,14 @@ function buildMethodParams(
     usedNames.add(phpName);
     if (q.required) {
       required.push(`${phpType} $${phpName}`);
-    } else if (q.name === 'order') {
-      // Hardcode order default to desc for pagination consistency
-      if (q.type.kind === 'enum') {
-        const enumType = mapTypeRef(q.type, { qualified: true });
-        const caseName = toPascalCase('desc');
-        optional.push(`${enumType} $${phpName} = ${enumType}::${caseName}`);
-      } else {
-        const nullableType = phpType.startsWith('?') ? phpType : `?${phpType}`;
-        optional.push(`${nullableType} $${phpName} = 'desc'`);
-      }
+    } else if (q.default != null && q.type.kind === 'enum') {
+      // 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
+      // callers can distinguish "unset" from "explicit value".
+      const enumType = mapTypeRef(q.type, { qualified: true });
+      const caseName = toPascalCase(String(q.default));
+      optional.push(`${enumType} $${phpName} = ${enumType}::${caseName}`);
     } else {
       const nullableType = phpType.startsWith('?') ? phpType : `?${phpType}`;
       optional.push(`${nullableType} $${phpName} = null`);
@@ -756,9 +755,10 @@ function buildQueryArray(op: Operation, hiddenParams?: Set<string>): string[] {
     .map((q) => {
       const phpName = fieldName(q.name);
       if (isEnumType(q.type)) {
-        // order params with enum defaults are non-nullable (default to Desc, not null)
-        const isNonNullableOrder = q.name === 'order' && q.type.kind === 'enum';
-        const nullsafe = q.required || isNonNullableOrder ? '' : '?';
+        // 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';
+        const nullsafe = q.required || hasEnumDefault ? '' : '?';
         return `'${q.name}' => $${phpName}${nullsafe}->value,`;
       }
       return `'${q.name}' => $${phpName},`;

package/src/python/enums.ts

@@ -1,6 +1,7 @@
-import type { Enum, EmitterContext, GeneratedFile, Service } from '@workos/oagen';
-import { toUpperSnakeCase, walkTypeRef } from '@workos/oagen';
+import type { Enum, EmitterContext, GeneratedFile } from '@workos/oagen';
+import { toUpperSnakeCase } from '@workos/oagen';
 import { className, fileName, buildMountDirMap, dirToModule } from './naming.js';
+import { computeSchemaPlacement } from './shared-schemas.js';
 
 /**
  * Convert a PascalCase class name to a human-readable lowercase string,
@@ -21,14 +22,18 @@ function humanizeClassName(name: string): string {
 export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
   if (enums.length === 0) return [];
 
-  const enumToService = assignEnumsToServices(enums, ctx.spec.services);
+  // Tests sometimes pass enums that aren't in ctx.spec.enums, so synthesize a
+  // spec view with the passed-in enums to keep the placement logic accurate.
+  const placementSpec = enums === ctx.spec.enums ? ctx.spec : { ...ctx.spec, enums };
+  const placement = computeSchemaPlacement(placementSpec, ctx);
+  const enumToService = placement.enumToService;
   const mountDirMap = buildMountDirMap(ctx);
   const resolveDir = (irService: string | undefined) =>
     irService ? (mountDirMap.get(irService) ?? 'common') : 'common';
   const files: GeneratedFile[] = [];
   const compatAliases = collectCompatEnumAliases(enums, ctx);
 
-  const aliasOf = collectEnumAliasOf(enums);
+  const aliasOf = placement.enumAliases;
 
   for (const enumDef of enums) {
     const service = enumToService.get(enumDef.name);
@@ -260,31 +265,9 @@ export function collectCompatEnumAliases(enums: Enum[], ctx: EmitterContext): Ma
   return aliases;
 }
 
-function collectEnumAliasOf(enums: Enum[]): Map<string, string> {
-  const hashGroups = new Map<string, string[]>();
-  for (const enumDef of enums) {
-    const hash = [...enumDef.values]
-      .map((v) => String(v.value))
-      .sort()
-      .join('|');
-    if (!hashGroups.has(hash)) hashGroups.set(hash, []);
-    hashGroups.get(hash)!.push(enumDef.name);
-  }
-
-  const aliasOf = new Map<string, string>();
-  for (const [, names] of hashGroups) {
-    if (names.length <= 1) continue;
-    const sorted = [...names].sort();
-    const canonical = sorted[0];
-    for (let i = 1; i < sorted.length; i++) {
-      aliasOf.set(sorted[i], canonical);
-    }
-  }
-  return aliasOf;
-}
-
 export function collectGeneratedEnumSymbolsByDir(enums: Enum[], ctx: EmitterContext): Map<string, string[]> {
-  const enumToService = assignEnumsToServices(enums, ctx.spec.services);
+  const placementSpec = enums === ctx.spec.enums ? ctx.spec : { ...ctx.spec, enums };
+  const enumToService = computeSchemaPlacement(placementSpec, ctx).enumToService;
   const mountDirMap = buildMountDirMap(ctx);
   const resolveDir = (irService: string | undefined) =>
     irService ? (mountDirMap.get(irService) ?? 'common') : 'common';
@@ -310,29 +293,3 @@ function enumValueHash(enumDef: Enum): string {
     .sort()
     .join('|');
 }
-
-export function assignEnumsToServices(enums: Enum[], services: Service[]): Map<string, string> {
-  const enumToService = new Map<string, string>();
-  const enumNames = new Set(enums.map((e) => e.name));
-
-  for (const service of services) {
-    for (const op of service.operations) {
-      const refs = new Set<string>();
-      const collect = (ref: any) => {
-        walkTypeRef(ref, { enum: (r: any) => refs.add(r.name) });
-      };
-      if (op.requestBody) collect(op.requestBody);
-      collect(op.response);
-      for (const p of [...op.pathParams, ...op.queryParams, ...op.headerParams, ...(op.cookieParams ?? [])]) {
-        collect(p.type);
-      }
-      for (const name of refs) {
-        if (enumNames.has(name) && !enumToService.has(name)) {
-          enumToService.set(name, service.name);
-        }
-      }
-    }
-  }
-
-  return enumToService;
-}