@workos/oagen-emitters 0.4.0 → 0.6.0

package/src/node/utils.ts

@@ -1,4 +1,4 @@
-import type { Model, EmitterContext, Service, Operation } from '@workos/oagen';
+import type { Model, EmitterContext, Service, Operation, TypeRef } from '@workos/oagen';
 import { toPascalCase } from '@workos/oagen';
 export {
   collectModelRefs,
@@ -269,17 +269,31 @@ function modelFingerprint(model: Model): string {
  *
  * Returns a Map from duplicate model name → canonical model name.
  */
-export function buildDeduplicationMap(models: Model[], ctx?: EmitterContext): Map<string, string> {
+export function buildDeduplicationMap(
+  models: Model[],
+  ctx?: EmitterContext,
+  reachable?: Set<string>,
+): Map<string, string> {
   const dedup = new Map<string, string>();
 
   // Pass 1: structural fingerprint dedup (exact match)
+  // When a reachability set is provided, prefer reachable models as canonicals
+  // so that aliases always point to models that will actually be generated.
   const fingerprints = new Map<string, string>();
   for (const model of models) {
     if (model.fields.length === 0) continue;
     const fp = modelFingerprint(model);
     const existing = fingerprints.get(fp);
     if (existing) {
-      dedup.set(model.name, existing);
+      // If the existing canonical is unreachable but this model is reachable,
+      // swap: make this model the canonical and demote the old one to alias.
+      if (reachable && !reachable.has(existing) && reachable.has(model.name)) {
+        dedup.delete(existing); // remove stale alias if present
+        dedup.set(existing, model.name);
+        fingerprints.set(fp, model.name);
+      } else {
+        dedup.set(model.name, existing);
+      }
     } else {
       fingerprints.set(fp, model.name);
     }
@@ -287,7 +301,8 @@ export function buildDeduplicationMap(models: Model[], ctx?: EmitterContext): Ma
 
   // Pass 2: name-based dedup for models that resolve to the same interface
   // name across services.  Only applies when context with name resolution is
-  // available.  Picks the model with the most fields as canonical.
+  // available.  Picks the model with the most fields as canonical, preferring
+  // reachable models when a reachability set is provided.
   if (ctx) {
     const byDomainName = new Map<string, Model[]>();
     for (const model of models) {
@@ -303,8 +318,15 @@ export function buildDeduplicationMap(models: Model[], ctx?: EmitterContext): Ma
     }
     for (const [, group] of byDomainName) {
       if (group.length < 2) continue;
-      // Choose canonical: most fields, then alphabetically by name
-      group.sort((a, b) => b.fields.length - a.fields.length || a.name.localeCompare(b.name));
+      // Choose canonical: prefer reachable, then most fields, then alphabetically
+      group.sort((a, b) => {
+        if (reachable) {
+          const aReach = reachable.has(a.name) ? 0 : 1;
+          const bReach = reachable.has(b.name) ? 0 : 1;
+          if (aReach !== bReach) return aReach - bReach;
+        }
+        return b.fields.length - a.fields.length || a.name.localeCompare(b.name);
+      });
       const canonical = group[0];
       for (let i = 1; i < group.length; i++) {
         dedup.set(group[i].name, canonical.name);
@@ -397,6 +419,26 @@ export function hasMethodsAbsentFromBaseline(service: Service, ctx: EmitterConte
   return false;
 }
 
+/**
+ * Check whether an IR model has fields not present in the baseline interface.
+ * Returns true if the model has new fields that need generation.
+ * Returns true if no baseline exists (new model entirely).
+ */
+export function modelHasNewFields(model: Model, ctx: EmitterContext): boolean {
+  if (!ctx.apiSurface?.interfaces) return true; // No surface = generate everything
+
+  const domainName = resolveInterfaceName(model.name, ctx);
+  const baseline = ctx.apiSurface.interfaces[domainName];
+  if (!baseline?.fields) return true; // No baseline for this model = new model
+
+  for (const field of model.fields) {
+    const camelName = fieldName(field.name);
+    if (!baseline.fields[camelName]) return true; // New field found
+  }
+
+  return false; // All fields exist in baseline
+}
+
 /**
  * Return operations in a service that are NOT covered by existing hand-written
  * service classes. For fully uncovered services, returns all operations.
@@ -417,3 +459,51 @@ export function uncoveredOperations(service: Service, ctx: EmitterContext): Oper
     return !existingClassNames.has(match.className); // Class doesn't exist → uncovered
   });
 }
+
+/**
+ * Compute the set of model names reachable from non-event service operations.
+ * The Events service pulls in hundreds of webhook payload models that the
+ * existing SDK handles via hand-written event types, so those models are
+ * excluded from generation.
+ *
+ * Shared between model generation, barrel generation, dedup, and tests to
+ * ensure consistency: every module agrees on which models will be generated.
+ */
+export function computeNonEventReachable(services: Service[], models: Model[]): Set<string> {
+  const seeds = new Set<string>();
+  for (const svc of services) {
+    if (svc.name.toLowerCase() === 'events') continue;
+    for (const op of svc.operations) {
+      const collectFromRef = (t: TypeRef | undefined): void => {
+        if (!t) return;
+        if (t.kind === 'model') seeds.add(t.name);
+        if (t.kind === 'array') collectFromRef(t.items);
+        if (t.kind === 'nullable') collectFromRef(t.inner);
+        if (t.kind === 'union') t.variants.forEach(collectFromRef);
+      };
+      collectFromRef(op.response);
+      collectFromRef(op.requestBody);
+      if (op.pagination?.itemType) collectFromRef(op.pagination.itemType);
+    }
+  }
+  const modelMap = new Map(models.map((m) => [m.name, m]));
+  const reachable = new Set<string>();
+  const queue = [...seeds];
+  while (queue.length > 0) {
+    const name = queue.pop()!;
+    if (reachable.has(name)) continue;
+    reachable.add(name);
+    const m = modelMap.get(name);
+    if (!m) continue;
+    for (const field of m.fields) {
+      const walk = (t: TypeRef): void => {
+        if (t.kind === 'model' && !reachable.has(t.name)) queue.push(t.name);
+        if (t.kind === 'array') walk(t.items);
+        if (t.kind === 'nullable') walk(t.inner);
+        if (t.kind === 'union') t.variants.forEach(walk);
+      };
+      walk(field.type);
+    }
+  }
+  return reachable;
+}

package/src/node/wrappers.ts

@@ -77,7 +77,37 @@ function emitWrapperMethod(
   const returnType = responseTypeName ?? 'void';
 
   // JSDoc
-  lines.push(`  /** ${formatWrapperDescription(wrapper.name)}. */`);
+  const docParts: string[] = [];
+  docParts.push(formatWrapperDescription(wrapper.name) + '.');
+
+  for (const p of op.pathParams) {
+    if (p.description) {
+      docParts.push(`@param ${fieldName(p.name)} - ${p.description}`);
+    }
+  }
+
+  for (const { paramName, field } of wrapperParams) {
+    const tsName = fieldName(paramName);
+    if (field?.description) {
+      docParts.push(`@param ${tsName} - ${field.description}`);
+    }
+  }
+
+  if (responseTypeName) {
+    docParts.push(`@returns {Promise<${returnType}>}`);
+  }
+
+  if (docParts.length === 1) {
+    lines.push(`  /** ${docParts[0]} */`);
+  } else {
+    lines.push('  /**');
+    for (const part of docParts) {
+      for (const line of part.split('\n')) {
+        lines.push(line === '' ? '   *' : `   * ${line}`);
+      }
+    }
+    lines.push('   */');
+  }
 
   // Method signature
   lines.push(`  async ${method}(${paramParts.join(', ')}): Promise<${returnType}> {`);

package/src/php/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 { initializeEnumDedup } from './naming.js';
 
 /** Initialize enum deduplication from spec data. */
@@ -71,9 +71,9 @@ export const phpEmitter: Emitter = {
     return ensureTrailingNewlines(generateTests(spec, ctx));
   },
 
-  generateManifest(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
+  buildOperationsMap(spec: ApiSpec, ctx: EmitterContext) {
     ensureNamingInitialized(ctx);
-    return ensureTrailingNewlines(generateManifest(spec, ctx));
+    return buildOperationsMap(spec, ctx);
   },
 
   fileHeader(): string {

package/src/php/manifest.ts

@@ -1,13 +1,13 @@
-import type { ApiSpec, EmitterContext, GeneratedFile } from '@workos/oagen';
+import type { ApiSpec, EmitterContext, OperationsMap } from '@workos/oagen';
 import { resolveMethodName } from './naming.js';
 import { buildServiceAccessPaths } from './client.js';
 import { getMountTarget } from '../shared/resolved-ops.js';
 
 /**
- * Generate smoke test manifest mapping HTTP operations to SDK methods.
+ * Build operation-to-SDK-method mapping for the manifest.
  */
-export function generateManifest(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
-  const manifest: Record<string, { sdkMethod: string; service: string }> = {};
+export function buildOperationsMap(spec: ApiSpec, ctx: EmitterContext): OperationsMap {
+  const manifest: OperationsMap = {};
   const accessPaths = buildServiceAccessPaths(spec.services, ctx);
 
   for (const service of spec.services) {
@@ -26,11 +26,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/php/models.ts

@@ -13,30 +13,6 @@ export { isListMetadataModel, isListWrapperModel };
 export function generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
   if (models.length === 0) return [];
 
-  // Build structural hash for deduplication
-  const modelHashMap = new Map<string, string>();
-  const hashGroups = new Map<string, string[]>();
-  for (const model of models) {
-    if (isListMetadataModel(model)) continue;
-    if (isListWrapperModel(model)) continue;
-    const hash = structuralHash(model);
-    modelHashMap.set(model.name, hash);
-    if (!hashGroups.has(hash)) hashGroups.set(hash, []);
-    hashGroups.get(hash)!.push(model.name);
-  }
-
-  // Pick canonical for each duplicate group (shortest class name wins)
-  const aliasOf = new Map<string, string>();
-  for (const [hash, names] of hashGroups) {
-    if (names.length <= 1) continue;
-    if (hash === '') continue;
-    const sorted = [...names].sort((a, b) => className(a).length - className(b).length);
-    const canonical = sorted[0];
-    for (let i = 1; i < sorted.length; i++) {
-      aliasOf.set(sorted[i], canonical);
-    }
-  }
-
   const files: GeneratedFile[] = [];
 
   // Emit shared JsonSerializableTrait once
@@ -59,8 +35,6 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
   for (const model of models) {
     if (isListMetadataModel(model)) continue;
     if (isListWrapperModel(model)) continue;
-    if (aliasOf.has(model.name)) continue; // skip structural duplicates
-
     const name = className(model.name);
     const lines: string[] = [];
 
@@ -301,10 +275,3 @@ function needsVarAnnotation(ref: TypeRef): boolean {
       return false;
   }
 }
-
-function structuralHash(model: Model): string {
-  return model.fields
-    .map((f) => `${f.name}:${JSON.stringify(f.type)}:${f.required}`)
-    .sort()
-    .join('|');
-}

package/src/php/resources.ts

@@ -1,5 +1,5 @@
 import type { Service, Operation, Model, EmitterContext, GeneratedFile, ResolvedOperation } from '@workos/oagen';
-import { planOperation, toCamelCase } from '@workos/oagen';
+import { planOperation, toCamelCase, toPascalCase } from '@workos/oagen';
 import { mapTypeRef, mapTypeRefForPHPDoc } from './type-map.js';
 import { className, fieldName, resolveMethodName } from './naming.js';
 import { isListWrapperModel } from './models.js';
@@ -9,6 +9,8 @@ import {
   lookupResolved,
   getOpDefaults,
   getOpInferFromClient,
+  collectGroupedParamNames,
+  collectBodyFieldTypes,
 } from '../shared/resolved-ops.js';
 import { generateWrapperMethods } from './wrappers.js';
 import { phpDocComment } from './utils.js';
@@ -91,6 +93,13 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
       content: lines.join('\n'),
       overwriteExisting: true,
     });
+
+    // Generate variant class files for operations with parameter groups
+    for (const op of operations) {
+      if ((op.parameterGroups?.length ?? 0) > 0) {
+        files.push(...generateParameterGroupFiles(op, ctx, modelMap));
+      }
+    }
   }
 
   return files;
@@ -119,6 +128,100 @@ export function isRedirectEndpoint(op: Operation, resolvedOp?: ResolvedOperation
   return false;
 }
 
+// ---------------------------------------------------------------------------
+// Mutually-exclusive parameter group support
+// ---------------------------------------------------------------------------
+
+/** PHP class name for a parameter group variant (e.g. ParentResourceById). */
+function groupVariantClassName(groupName: string, variantName: string): string {
+  return `${className(groupName)}${className(variantName)}`;
+}
+
+/**
+ * Derive a short PHP property name for a parameter within a variant class.
+ * Strips the group name prefix when present to avoid stuttering
+ * (e.g. parent_resource_id in group parent_resource -> id -> camelCase).
+ */
+export function deriveVariantFieldName(paramName: string, groupName: string): string {
+  const prefix = groupName + '_';
+  const stripped = paramName.startsWith(prefix) ? paramName.slice(prefix.length) : paramName;
+  return fieldName(stripped);
+}
+
+/**
+ * Generate PHP variant class files for all parameter groups on an operation.
+ * Each variant becomes a simple PHP class with readonly constructor properties.
+ */
+function generateParameterGroupFiles(
+  op: Operation,
+  ctx: EmitterContext,
+  modelMap: Map<string, Model>,
+): GeneratedFile[] {
+  const files: GeneratedFile[] = [];
+  const bodyFieldTypes = collectBodyFieldTypes(op, [...modelMap.values()]);
+
+  for (const group of op.parameterGroups ?? []) {
+    for (const variant of group.variants) {
+      const variantClass = groupVariantClassName(group.name, variant.name);
+      const lines: string[] = [];
+
+      lines.push(`namespace ${ctx.namespacePascal}\\Service;`);
+      lines.push('');
+      lines.push(`class ${variantClass}`);
+      lines.push('{');
+      lines.push('    public function __construct(');
+      for (let i = 0; i < variant.parameters.length; i++) {
+        const param = variant.parameters[i];
+        const effectiveType = bodyFieldTypes.get(param.name) ?? param.type;
+        const phpType = mapTypeRef(effectiveType, { qualified: true });
+        const phpName = deriveVariantFieldName(param.name, group.name);
+        const comma = ',';
+        lines.push(`        public readonly ${phpType} $${phpName}${comma}`);
+      }
+      lines.push('    ) {');
+      lines.push('    }');
+      lines.push('}');
+
+      files.push({
+        path: `lib/Service/${variantClass}.php`,
+        content: lines.join('\n'),
+        overwriteExisting: true,
+      });
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Generate instanceof dispatch lines to serialize a grouped parameter
+ * into a target array ($query or $body) using each variant's wire names.
+ */
+function generateGroupDispatch(op: Operation, indent: string, target: '$query' | '$body' = '$query'): string[] {
+  const lines: string[] = [];
+
+  for (const group of op.parameterGroups ?? []) {
+    const phpParamName = fieldName(group.name);
+
+    for (let vi = 0; vi < group.variants.length; vi++) {
+      const variant = group.variants[vi];
+      const variantClass = groupVariantClassName(group.name, variant.name);
+      const keyword = vi === 0 ? 'if' : 'elseif';
+
+      lines.push(`${indent}${keyword} ($${phpParamName} instanceof ${variantClass}) {`);
+
+      for (const param of variant.parameters) {
+        const phpField = deriveVariantFieldName(param.name, group.name);
+        lines.push(`${indent}    ${target}['${param.name}'] = $${phpParamName}->${phpField};`);
+      }
+
+      lines.push(`${indent}}`);
+    }
+  }
+
+  return lines;
+}
+
 function generateMethod(
   lines: string[],
   op: Operation,
@@ -176,14 +279,29 @@ function generateMethod(
     }
   }
 
-  // @param for query params
+  // @param for parameter groups (union-typed)
+  const groupedParamNames = collectGroupedParamNames(op);
+  for (const group of op.parameterGroups ?? []) {
+    const phpName = fieldName(group.name);
+    if (seenDocParams.has(phpName)) continue;
+    seenDocParams.add(phpName);
+    const variantTypes = group.variants.map((v) => groupVariantClassName(group.name, v.name));
+    const unionDocType = variantTypes.join('|');
+    const nullPrefix = group.optional ? 'null|' : '';
+    docParts.push(`@param ${nullPrefix}${unionDocType} $${phpName}`);
+  }
+
+  // @param for query params (skip grouped params — they appear as group union params)
   for (const q of op.queryParams) {
     if (hiddenParams.has(q.name)) continue;
+    if (groupedParamNames.has(q.name)) continue;
     const docType = mapTypeRefForPHPDoc(q.type);
     const phpName = fieldName(q.name);
     if (seenDocParams.has(phpName)) continue;
     seenDocParams.add(phpName);
-    const nullSuffix = !q.required && !docType.endsWith('|null') ? '|null' : '';
+    // 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' : '';
     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)}.`;
@@ -239,12 +357,18 @@ function generateMethod(
     const queryLines = buildQueryArray(op, hiddenParams);
     const hasDefaults = Object.keys(getOpDefaults(resolvedOp)).length > 0;
     const hasInferred = getOpInferFromClient(resolvedOp).length > 0;
-    const needsQuery = queryLines.length > 0 || hasDefaults || hasInferred;
+    const hasGroups = (op.parameterGroups?.length ?? 0) > 0;
+    const needsQuery = queryLines.length > 0 || hasDefaults || hasInferred || hasGroups;
 
     if (needsQuery) {
-      const hasOptionalQuery = op.queryParams.some((q) => !q.required && !hiddenParams.has(q.name));
+      const groupedParams = collectGroupedParamNames(op);
+      const hasOptionalQuery = op.queryParams.some(
+        (q) => !q.required && !hiddenParams.has(q.name) && !groupedParams.has(q.name),
+      );
       if (hasOptionalQuery) {
         lines.push('        $query = array_filter([');
+      } else if (queryLines.length > 0) {
+        lines.push('        $query = [');
       } else {
         lines.push('        $query = [');
       }
@@ -264,23 +388,33 @@ function generateMethod(
       for (const clientField of getOpInferFromClient(resolvedOp)) {
         lines.push(`        $query['${clientField}'] = ${clientFieldExpression(clientField)};`);
       }
-      lines.push(`        return $this->client->buildUrl(${path}, $query, $options);`);
+      // Inject parameter group dispatch (instanceof checks)
+      lines.push(...generateGroupDispatch(op, '        '));
+      lines.push(`        return $this->client->buildUrl(path: ${path}, query: $query, options: $options);`);
     } else {
-      lines.push(`        return $this->client->buildUrl(${path}, [], $options);`);
+      lines.push(`        return $this->client->buildUrl(path: ${path}, query: [], options: $options);`);
     }
   } else if (plan.isPaginated) {
     const queryLines = buildQueryArray(op);
-    if (queryLines.length > 0) {
-      lines.push('        $query = array_filter([');
-      for (const q of queryLines) {
-        lines.push(`            ${q}`);
+    const hasGroups = (op.parameterGroups?.length ?? 0) > 0;
+    const needsQuery = queryLines.length > 0 || hasGroups;
+    if (needsQuery) {
+      if (queryLines.length > 0) {
+        lines.push('        $query = array_filter([');
+        for (const q of queryLines) {
+          lines.push(`            ${q}`);
+        }
+        lines.push('        ], fn ($v) => $v !== null);');
+      } else {
+        lines.push('        $query = [];');
       }
-      lines.push('        ], fn ($v) => $v !== null);');
+      // Inject parameter group dispatch (instanceof checks)
+      lines.push(...generateGroupDispatch(op, '        '));
     }
     lines.push('        return $this->client->requestPage(');
     lines.push(`            method: '${httpMethod}',`);
     lines.push(`            path: ${path},`);
-    if (queryLines.length > 0) {
+    if (needsQuery) {
       lines.push('            query: $query,');
     }
     const itemType = op.pagination?.itemType;
@@ -330,6 +464,10 @@ function generateMethod(
       for (const clientField of getOpInferFromClient(resolvedOp)) {
         lines.push(`        $body['${clientField}'] = ${clientFieldExpression(clientField)};`);
       }
+      // Inject parameter group dispatch into body
+      if ((op.parameterGroups?.length ?? 0) > 0) {
+        lines.push(...generateGroupDispatch(op, '        ', '$body'));
+      }
     }
     // Build query params if present
     const deleteQueryLines = buildQueryArray(op);
@@ -381,6 +519,11 @@ function generateMethod(
     for (const clientField of getOpInferFromClient(resolvedOp)) {
       lines.push(`        $body['${clientField}'] = ${clientFieldExpression(clientField)};`);
     }
+    // Inject parameter group dispatch into body so sensitive fields
+    // (passwords, role slugs) never leak into the URL query string.
+    if ((op.parameterGroups?.length ?? 0) > 0) {
+      lines.push(...generateGroupDispatch(op, '        ', '$body'));
+    }
     lines.push('        $response = $this->client->request(');
     lines.push(`            method: '${httpMethod}',`);
     lines.push(`            path: ${path},`);
@@ -402,12 +545,18 @@ function generateMethod(
     const queryLines = buildQueryArray(op, hiddenParams);
     const hasDefaults = Object.keys(getOpDefaults(resolvedOp)).length > 0;
     const hasInferred = getOpInferFromClient(resolvedOp).length > 0;
-    const needsQuery = queryLines.length > 0 || hasDefaults || hasInferred;
+    const hasGroups = (op.parameterGroups?.length ?? 0) > 0;
+    const needsQuery = queryLines.length > 0 || hasDefaults || hasInferred || hasGroups;
 
     if (needsQuery) {
-      const hasOptionalQuery = op.queryParams.some((q) => !q.required && !hiddenParams.has(q.name));
+      const groupedParams = collectGroupedParamNames(op);
+      const hasOptionalQuery = op.queryParams.some(
+        (q) => !q.required && !hiddenParams.has(q.name) && !groupedParams.has(q.name),
+      );
       if (hasOptionalQuery) {
         lines.push('        $query = array_filter([');
+      } else if (queryLines.length > 0) {
+        lines.push('        $query = [');
       } else {
         lines.push('        $query = [');
       }
@@ -427,6 +576,8 @@ function generateMethod(
       for (const clientField of getOpInferFromClient(resolvedOp)) {
         lines.push(`        $query['${clientField}'] = ${clientFieldExpression(clientField)};`);
       }
+      // Inject parameter group dispatch (instanceof checks)
+      lines.push(...generateGroupDispatch(op, '        '));
     }
     lines.push('        $response = $this->client->request(');
     lines.push(`            method: '${httpMethod}',`);
@@ -465,6 +616,7 @@ function buildMethodParams(
   const optional: string[] = [];
   const usedNames = new Set<string>();
   const hidden = hiddenParams ?? new Set();
+  const groupedParams = collectGroupedParamNames(op);
 
   // Path params (always required)
   for (const p of op.pathParams) {
@@ -499,15 +651,41 @@ function buildMethodParams(
     }
   }
 
-  // Query params
+  // Parameter group union-typed params (before individual query params)
+  for (const group of op.parameterGroups ?? []) {
+    const phpName = fieldName(group.name);
+    if (usedNames.has(phpName)) continue;
+    usedNames.add(phpName);
+    // PHP 8.0+ union syntax: VariantA|VariantB $paramName
+    const variantTypes = group.variants.map((v) => groupVariantClassName(group.name, v.name));
+    const unionType = variantTypes.join('|');
+    if (group.optional) {
+      optional.push(`null|${unionType} $${phpName} = null`);
+    } else {
+      required.push(`${unionType} $${phpName}`);
+    }
+  }
+
+  // Query params (skip grouped params — they are serialized via group dispatch)
   for (const q of op.queryParams) {
     if (hidden.has(q.name)) continue;
+    if (groupedParams.has(q.name)) continue;
     const phpType = mapTypeRef(q.type, { qualified: true });
     let phpName = fieldName(q.name);
     if (usedNames.has(phpName)) continue;
     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 {
       const nullableType = phpType.startsWith('?') ? phpType : `?${phpType}`;
       optional.push(`${nullableType} $${phpName} = null`);
@@ -574,12 +752,15 @@ function isEnumType(ref: import('@workos/oagen').TypeRef): boolean {
 
 function buildQueryArray(op: Operation, hiddenParams?: Set<string>): string[] {
   const hidden = hiddenParams ?? new Set();
+  const groupedParams = collectGroupedParamNames(op);
   return op.queryParams
-    .filter((q) => !hidden.has(q.name))
+    .filter((q) => !hidden.has(q.name) && !groupedParams.has(q.name))
     .map((q) => {
       const phpName = fieldName(q.name);
       if (isEnumType(q.type)) {
-        const nullsafe = q.required ? '' : '?';
+        // 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 ? '' : '?';
         return `'${q.name}' => $${phpName}${nullsafe}->value,`;
       }
       return `'${q.name}' => $${phpName},`;