@workos/oagen-emitters 0.12.0 → 0.12.1

package/src/rust/resources.ts

@@ -4,11 +4,13 @@ import type {
   EmitterContext,
   GeneratedFile,
   Parameter,
+  ParameterGroup,
   ResolvedOperation,
   ResolvedWrapper,
+  TypeRef,
 } from '@workos/oagen';
 import { planOperation } from '@workos/oagen';
-import { fieldName, methodName, typeName, moduleName } from './naming.js';
+import { fieldName, methodName, typeName, moduleName, variantName } from './naming.js';
 import { mapTypeRef, makeOptional, UnionRegistry } from './type-map.js';
 import { applySecretRedaction } from './secret.js';
 import { parsePathTemplate } from '../shared/path-template.js';
@@ -75,6 +77,10 @@ function renderMountGroup(
   lines.push('}');
   lines.push('');
 
+  // Parameter-group enums and synthetic body types are emitted once per
+  // distinct shape per file (a single mount). Collect them up front so
+  // duplicates collapse and per-method emit can reference stable names.
+  const groupEmitter = new GroupEmitter();
   const paramsStructs: string[] = [];
   const methods: string[] = [];
   const seenMethods = new Set<string>();
@@ -88,7 +94,7 @@ function renderMountGroup(
         seenMethods.add(wrapperMethodName);
         const paramsType = `${typeName(wrapper.name)}Params`;
         const params = resolveWrapperParams(wrapper, ctx);
-        paramsStructs.push(renderWrapperParamsStruct(paramsType, op, wrapper, params, registry));
+        paramsStructs.push(renderWrapperParamsStruct(paramsType, op, wrapper, params, registry, ctx));
         methods.push(renderWrapperMethod(op, wrapper, params, paramsType, wrapperMethodName));
       }
       continue;
@@ -97,21 +103,40 @@ function renderMountGroup(
     const m = methodName(resolved.methodName);
     if (seenMethods.has(m)) continue;
     seenMethods.add(m);
+
+    // URL-builder ops short-circuit: no params struct (just optional one with
+    // the parameters as fields) but no HTTP-issuing methods.
+    if (resolved.urlBuilder) {
+      const paramsType = `${typeName(resolved.methodName)}Params`;
+      const emptyParams = isEmptyParams(op, resolved);
+      if (!emptyParams) {
+        paramsStructs.push(renderParamsStruct(paramsType, op, resolved, registry, ctx, groupEmitter));
+      }
+      methods.push(renderUrlBuilderMethod(op, resolved, paramsType, m, emptyParams));
+      continue;
+    }
+
     const paramsType = `${typeName(resolved.methodName)}Params`;
     const emptyParams = isEmptyParams(op, resolved);
     if (!emptyParams) {
-      paramsStructs.push(renderParamsStruct(paramsType, op, resolved, registry));
+      paramsStructs.push(renderParamsStruct(paramsType, op, resolved, registry, ctx, groupEmitter));
     }
     methods.push(renderMethod(op, resolved, paramsType, m, emptyParams));
 
-    // For paginated list endpoints, also emit `<method>_auto_paging` returning
-    // `impl Stream<Item = Result<T, Error>>`. Detected by:
-    //   - response is a model with both `data: Vec<T>` and `list_metadata`
-    //   - the params struct has an `after` cursor field
+    // Auto-paging variant driven by `op.pagination` IR metadata. URL-builder
+    // and HTTP-less ops never qualify.
     const autoPaging = renderAutoPagingMethod(op, resolved, paramsType, m, ctx);
     if (autoPaging) methods.push(autoPaging);
   }
 
+  // Group-related type definitions go between the file header and the params
+  // structs so a single file's params can reference them by short name.
+  const groupBlock = groupEmitter.render();
+  if (groupBlock.length > 0) {
+    lines.push(groupBlock);
+    lines.push('');
+  }
+
   for (const s of paramsStructs) {
     lines.push(s);
     lines.push('');
@@ -127,47 +152,340 @@ function renderMountGroup(
   return lines.join('\n').replace(/\n+$/g, '\n');
 }
 
-function renderParamsStruct(name: string, op: Operation, resolved: ResolvedOperation, registry: UnionRegistry): string {
+// ─── Parameter-group emitter ────────────────────────────────────────────────
+//
+// A per-file collector that records each unique enum and synthetic body type
+// requested across the file's operations, deduplicates them by structural key,
+// and renders them in dependency order. The emitter is otherwise stateless so
+// individual `renderParamsStruct` calls just stamp their request and reference
+// the resulting Rust names.
+
+interface GroupEnumSpec {
+  name: string;
+  variants: Array<{
+    name: string;
+    fields: Array<{ rustName: string; wireName: string; rustType: string }>;
+  }>;
+}
+
+interface SyntheticBodySpec {
+  /** PascalCase type name (e.g. `CheckBody`). */
+  name: string;
+  /** Body model fields that survive after grouped-field removal. */
+  flatFields: Array<{
+    rustName: string;
+    wireName: string;
+    rustType: string;
+    required: boolean;
+    doc?: string;
+  }>;
+  /** `#[serde(flatten)]` fields, one per body parameter group. */
+  flattenEnums: Array<{
+    rustName: string;
+    rustType: string;
+    required: boolean;
+    doc?: string;
+  }>;
+}
+
+class GroupEmitter {
+  private enums: GroupEnumSpec[] = [];
+  private bodies: SyntheticBodySpec[] = [];
+  private seenEnums = new Set<string>();
+  private seenBodies = new Set<string>();
+
+  /** Register a parameter-group enum, returning the PascalCase Rust name. */
+  registerEnum(group: ParameterGroup): string {
+    const name = typeName(group.name);
+    const variants = group.variants.map((v) => ({
+      name: typeName(v.name),
+      fields: v.parameters.map((p) => ({
+        rustName: fieldName(p.name),
+        wireName: p.name,
+        // Group variant params are always treated as required within their
+        // variant — picking the variant is the caller's commitment to supply
+        // the variant's full payload.
+        rustType: rustTypeForGroupParam(p.type),
+      })),
+    }));
+    if (!this.seenEnums.has(name)) {
+      this.seenEnums.add(name);
+      this.enums.push({ name, variants });
+    }
+    return name;
+  }
+
+  /** Register a synthetic body struct, returning its PascalCase Rust name. */
+  registerBody(spec: SyntheticBodySpec): string {
+    if (!this.seenBodies.has(spec.name)) {
+      this.seenBodies.add(spec.name);
+      this.bodies.push(spec);
+    }
+    return spec.name;
+  }
+
+  render(): string {
+    const blocks: string[] = [];
+    for (const e of this.enums) {
+      const lines: string[] = [];
+      lines.push('#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]');
+      lines.push('#[serde(untagged)]');
+      lines.push(`pub enum ${e.name} {`);
+      for (const v of e.variants) {
+        if (v.fields.length === 0) {
+          lines.push(`    ${v.name},`);
+          continue;
+        }
+        lines.push(`    ${v.name} {`);
+        for (const f of v.fields) {
+          if (f.rustName !== f.wireName) {
+            lines.push(`        #[serde(rename = ${JSON.stringify(f.wireName)})]`);
+          }
+          lines.push(`        ${f.rustName}: ${f.rustType},`);
+        }
+        lines.push('    },');
+      }
+      lines.push('}');
+      blocks.push(lines.join('\n'));
+    }
+    for (const b of this.bodies) {
+      const lines: string[] = [];
+      // Bodies need `Deserialize` too: the generated test harness builds
+      // request stubs via `serde_json::from_str("{}")` and otherwise can't
+      // refer to the synthetic type without breaking the fixture pipeline.
+      const everythingOptional = b.flatFields.every((f) => !f.required) && b.flattenEnums.every((f) => !f.required);
+      const baseDerives = 'Debug, Clone, serde::Serialize, serde::Deserialize';
+      const derives = everythingOptional ? `${baseDerives}, Default` : baseDerives;
+      lines.push(`#[derive(${derives})]`);
+      lines.push(`pub struct ${b.name} {`);
+      for (const f of b.flatFields) {
+        if (f.doc) {
+          for (const c of paramDocComment(f.doc)) lines.push(`    ${c}`);
+        }
+        if (f.required) {
+          if (f.doc) lines.push('    ///');
+          lines.push('    /// Required.');
+        }
+        if (!f.required) {
+          lines.push('    #[serde(skip_serializing_if = "Option::is_none")]');
+        }
+        if (f.rustName !== f.wireName) {
+          lines.push(`    #[serde(rename = ${JSON.stringify(f.wireName)})]`);
+        }
+        lines.push(`    pub ${f.rustName}: ${f.rustType},`);
+      }
+      for (const f of b.flattenEnums) {
+        if (f.doc) {
+          for (const c of paramDocComment(f.doc)) lines.push(`    ${c}`);
+        }
+        lines.push('    #[serde(flatten)]');
+        if (!f.required) {
+          lines.push('    #[serde(skip_serializing_if = "Option::is_none")]');
+        }
+        lines.push(`    pub ${f.rustName}: ${f.rustType},`);
+      }
+      lines.push('}');
+
+      // Constructor for the synthetic body type. Mirrors the params struct's
+      // ergonomic: required fields land as positional args, optional ones
+      // default via `Default::default`.
+      const required = [...b.flatFields.filter((f) => f.required), ...b.flattenEnums.filter((f) => f.required)];
+      if (required.length > 0 || b.flatFields.length + b.flattenEnums.length > 0) {
+        const ctorArgs = required.map((f) => `${f.rustName}: ${ctorParamType(f.rustType)}`).join(', ');
+        const init: string[] = [];
+        for (const f of b.flatFields) {
+          if (f.required) {
+            const value = ctorParamConvert(f.rustType, f.rustName);
+            init.push(value === f.rustName ? `            ${f.rustName},` : `            ${f.rustName}: ${value},`);
+          } else {
+            init.push(`            ${f.rustName}: Default::default(),`);
+          }
+        }
+        for (const f of b.flattenEnums) {
+          if (f.required) {
+            const value = ctorParamConvert(f.rustType, f.rustName);
+            init.push(value === f.rustName ? `            ${f.rustName},` : `            ${f.rustName}: ${value},`);
+          } else {
+            init.push(`            ${f.rustName}: Default::default(),`);
+          }
+        }
+        lines.push('');
+        lines.push(`impl ${b.name} {`);
+        lines.push(`    /// Construct a new \`${b.name}\` with the required fields set.`);
+        lines.push(`    pub fn new(${ctorArgs}) -> Self {`);
+        lines.push('        Self {');
+        for (const l of init) lines.push(l);
+        lines.push('        }');
+        lines.push('    }');
+        lines.push('}');
+      }
+      blocks.push(lines.join('\n'));
+    }
+    return blocks.join('\n\n');
+  }
+}
+
+/**
+ * Render the Rust type for a parameter-group variant field. Variants commit
+ * the caller to supplying their full payload, so optional individual params
+ * still flow as `String` (not `Option<String>`); the enum-level choice is the
+ * one source of truth for "did the caller pick this variant or not."
+ */
+function rustTypeForGroupParam(type: TypeRef): string {
+  const rust = mapTypeRef(type);
+  // Variant fields are non-optional regardless of the IR's per-param flag.
+  if (rust.startsWith('Option<')) return rust.slice('Option<'.length, -1);
+  return rust;
+}
+
+/** Classify each parameter group on an op as "query" or "body". */
+function classifyGroup(group: ParameterGroup, op: Operation): 'query' | 'body' {
+  const queryNames = new Set(op.queryParams.map((qp) => qp.name));
+  const allInQuery = group.variants.every((v) => v.parameters.every((p) => queryNames.has(p.name)));
+  return allInQuery ? 'query' : 'body';
+}
+
+function renderParamsStruct(
+  name: string,
+  op: Operation,
+  resolved: ResolvedOperation,
+  registry: UnionRegistry,
+  ctx: EmitterContext,
+  groupEmitter: GroupEmitter,
+): string {
   const bodyRequired = isBodyRequired(op);
   const hidden = new Set<string>([...Object.keys(resolved.defaults ?? {}), ...(resolved.inferFromClient ?? [])]);
 
-  type FieldInfo = { fname: string; rust: string; required: boolean; doc?: string };
+  // Names of params that belong to a parameter group; these are folded into
+  // the enum field and must be omitted from the flat params struct.
+  const queryGroupParamNames = new Set<string>();
+  const bodyGroupParamNames = new Set<string>();
+  const queryGroupFields: Array<{
+    name: string;
+    rustType: string;
+    required: boolean;
+    doc?: string;
+  }> = [];
+  const bodyGroupFields: Array<{
+    name: string;
+    rustType: string;
+    required: boolean;
+    doc?: string;
+  }> = [];
+  for (const group of op.parameterGroups ?? []) {
+    const enumName = groupEmitter.registerEnum(group);
+    const rustType = group.optional ? `Option<${enumName}>` : enumName;
+    const groupField = {
+      name: fieldName(group.name),
+      rustType,
+      required: !group.optional,
+      doc: undefined as string | undefined,
+    };
+    if (classifyGroup(group, op) === 'query') {
+      for (const v of group.variants) for (const p of v.parameters) queryGroupParamNames.add(p.name);
+      queryGroupFields.push(groupField);
+    } else {
+      for (const v of group.variants) for (const p of v.parameters) bodyGroupParamNames.add(p.name);
+      bodyGroupFields.push(groupField);
+    }
+  }
+
+  type FieldInfo = {
+    fname: string;
+    rust: string;
+    required: boolean;
+    defaultExpr: string | null;
+    doc?: string;
+  };
   const fields: FieldInfo[] = [];
   const fieldLines: string[] = [];
   const seen = new Set<string>();
-  const emitField = (p: Parameter) => {
+  const emitField = (p: Parameter, opts: { isQuery?: boolean } = {}) => {
     if (hidden.has(p.name)) return;
+    if (queryGroupParamNames.has(p.name)) return;
     const fname = fieldName(p.name);
     if (seen.has(fname)) return;
     seen.add(fname);
-    let rust = mapTypeRef(p.type, { hint: `${name}${typeName(p.name)}`, registry });
+    let rust = mapTypeRef(p.type, {
+      hint: `${name}${typeName(p.name)}`,
+      registry,
+    });
     if (!p.required && !rust.startsWith('Option<')) rust = makeOptional(rust);
     rust = applySecretRedaction(rust, p.name);
+    // Spec-level default → materialise it as a Rust expression so
+    // `Default::default()` and `new(…)` actually produce the documented value.
+    const defaultExpr = p.default != null ? rustDefaultExpr(p.default, p.type, rust.startsWith('Option<'), ctx) : null;
     // Field-level documentation derived from the spec.
     const desc = p.description?.trim();
     if (desc) {
       for (const c of paramDocComment(desc)) fieldLines.push(`    ${c}`);
     }
-    if (p.required && !rust.startsWith('Option<')) {
+    if (p.default != null) {
       if (desc) fieldLines.push('    ///');
+      fieldLines.push(`    /// Defaults to \`${formatDefault(p.default)}\`.`);
+    }
+    if (p.required && !rust.startsWith('Option<')) {
+      if (desc || p.default != null) fieldLines.push('    ///');
       fieldLines.push('    /// Required.');
     }
     if (rust.startsWith('Option<')) {
       fieldLines.push('    #[serde(skip_serializing_if = "Option::is_none")]');
     }
+    // Vec query params with `style: form, explode: false` (the comma-joined
+    // wire format) need a custom serializer — serde alone serialises Vec as
+    // an array, which our query encoder unrolls into repeated keys.
+    if (opts.isQuery && p.explode === false && isVecType(rust)) {
+      fieldLines.push(
+        rust.startsWith('Option<')
+          ? '    #[serde(serialize_with = "crate::query::serialize_comma_separated_opt")]'
+          : '    #[serde(serialize_with = "crate::query::serialize_comma_separated")]',
+      );
+    }
     if (fname !== p.name) {
       fieldLines.push(`    #[serde(rename = ${JSON.stringify(p.name)})]`);
     }
     if (p.deprecated) fieldLines.push('    #[deprecated]');
     fieldLines.push(`    pub ${fname}: ${rust},`);
-    fields.push({ fname, rust, required: !!p.required && !rust.startsWith('Option<') });
+    fields.push({
+      fname,
+      rust,
+      required: !!p.required && !rust.startsWith('Option<'),
+      defaultExpr,
+    });
   };
 
-  for (const p of op.queryParams) emitField(p);
+  for (const p of op.queryParams) emitField(p, { isQuery: true });
   for (const p of op.headerParams) emitField(p);
+  for (const p of op.cookieParams ?? []) emitField(p);
+
+  // Query-side parameter group fields. Flattened so the encoder sees the
+  // variant's own fields at the params struct's top level.
+  for (const g of queryGroupFields) {
+    fieldLines.push('    #[serde(flatten)]');
+    if (!g.required) {
+      fieldLines.push('    #[serde(skip_serializing_if = "Option::is_none")]');
+    }
+    fieldLines.push(`    pub ${g.name}: ${g.rustType},`);
+    fields.push({
+      fname: g.name,
+      rust: g.rustType,
+      required: g.required,
+      defaultExpr: null,
+    });
+  }
 
   if (op.requestBody) {
-    let bodyType = mapTypeRef(op.requestBody, { hint: `${name}Body`, registry });
+    let bodyType: string;
+    if (bodyGroupFields.length > 0) {
+      // Synthesise a body struct that replaces the grouped fields with a
+      // flattened enum. The original body model keeps the flat optional
+      // fields (it's shared with other consumers); the synthetic type is
+      // op-local and serialises with the parameter group's variant in
+      // strongly-typed form.
+      bodyType = registerSyntheticBody(op, name, bodyGroupParamNames, bodyGroupFields, ctx, registry, groupEmitter);
+    } else {
+      bodyType = mapTypeRef(op.requestBody, { hint: `${name}Body`, registry });
+    }
     if (!bodyRequired && !bodyType.startsWith('Option<')) {
       bodyType = makeOptional(bodyType);
     }
@@ -176,14 +494,22 @@ function renderParamsStruct(name: string, op: Operation, resolved: ResolvedOpera
     if (bodyRequired) fieldLines.push('    /// Required.');
     fieldLines.push('    #[serde(skip)]');
     fieldLines.push(`    pub body: ${bodyType},`);
-    fields.push({ fname: 'body', rust: bodyType, required: bodyRequired });
+    fields.push({
+      fname: 'body',
+      rust: bodyType,
+      required: bodyRequired,
+      defaultExpr: null,
+    });
   }
 
-  // Default-derive only when every field is optional (so Default can't
-  // construct a "valid" value with empty strings for required fields).
+  // Default-derive only when every field is optional and no field has a
+  // spec-level default. Spec defaults need a manual `impl Default` since
+  // `Option<T>::default()` is `None`, not `Some(<spec default>)`.
   const requiredFields = fields.filter((f) => f.required);
   const allOptional = fields.length === 0 || requiredFields.length === 0;
-  const derives = allOptional ? 'Debug, Clone, Default, Serialize' : 'Debug, Clone, Serialize';
+  const hasSpecDefault = fields.some((f) => f.defaultExpr !== null);
+  const canDeriveDefault = allOptional && !hasSpecDefault;
+  const derives = canDeriveDefault ? 'Debug, Clone, Default, Serialize' : 'Debug, Clone, Serialize';
 
   const out: string[] = [];
   if (fieldLines.length === 0) {
@@ -192,6 +518,22 @@ function renderParamsStruct(name: string, op: Operation, resolved: ResolvedOpera
     out.push(`#[derive(${derives})]`, `pub struct ${name} {`, ...fieldLines, '}');
   }
 
+  // Manual `Default` impl when every field is optional but some have
+  // spec-level defaults — `Default::default()` now returns those values
+  // instead of `None`.
+  if (allOptional && hasSpecDefault) {
+    const defaultInitLines = fields.map((f) => `            ${f.fname}: ${f.defaultExpr ?? 'Default::default()'},`);
+    out.push('');
+    out.push(`impl Default for ${name} {`);
+    out.push('    #[allow(deprecated)]');
+    out.push('    fn default() -> Self {');
+    out.push('        Self {');
+    out.push(...defaultInitLines);
+    out.push('        }');
+    out.push('    }');
+    out.push('}');
+  }
+
   // Generate `new(...)` constructor when there is at least one required field
   // but at least one optional field — gives callers a clear ergonomic entry
   // point without forcing them to spell out optional fields.
@@ -204,7 +546,7 @@ function renderParamsStruct(name: string, op: Operation, resolved: ResolvedOpera
         // Use field-init shorthand when the parameter and field names match.
         initLines.push(value === f.fname ? `            ${f.fname},` : `            ${f.fname}: ${value},`);
       } else {
-        initLines.push(`            ${f.fname}: Default::default(),`);
+        initLines.push(`            ${f.fname}: ${f.defaultExpr ?? 'Default::default()'},`);
       }
     }
     out.push('');
@@ -222,6 +564,69 @@ function renderParamsStruct(name: string, op: Operation, resolved: ResolvedOpera
   return out.join('\n');
 }
 
+/** True when a Rust type expression is a `Vec<…>` (or `Option<Vec<…>>`). */
+function isVecType(rust: string): boolean {
+  const inner = rust.startsWith('Option<') ? rust.slice('Option<'.length, -1) : rust;
+  return inner.startsWith('Vec<');
+}
+
+/**
+ * Build a synthetic body struct for an op that has body-side parameter
+ * groups. The original body model can't be reused as-is because its grouped
+ * fields are still flat optionals; the synthetic type swaps them for a
+ * flattened enum so callers commit to one variant at construction time.
+ */
+function registerSyntheticBody(
+  op: Operation,
+  paramsName: string,
+  bodyGroupParamNames: Set<string>,
+  bodyGroupFields: Array<{
+    name: string;
+    rustType: string;
+    required: boolean;
+    doc?: string;
+  }>,
+  ctx: EmitterContext,
+  registry: UnionRegistry,
+  groupEmitter: GroupEmitter,
+): string {
+  // Resolve the original body model (only model-kind bodies can have body
+  // groups in the spec; other shapes fall back to the model name directly).
+  const bodyRef = op.requestBody;
+  if (!bodyRef || bodyRef.kind !== 'model') {
+    return mapTypeRef(bodyRef!, { hint: `${paramsName}Body`, registry });
+  }
+  const model = ctx.spec.models.find((m) => m.name === bodyRef.name);
+  if (!model) {
+    return typeName(bodyRef.name);
+  }
+  const name = `${paramsName}Body`;
+  const flatFields = model.fields
+    .filter((f) => !bodyGroupParamNames.has(f.name))
+    .map((f) => {
+      let rust = mapTypeRef(f.type, {
+        hint: `${name}${typeName(f.name)}`,
+        registry,
+      });
+      if (!f.required && !rust.startsWith('Option<')) rust = makeOptional(rust);
+      rust = applySecretRedaction(rust, f.name);
+      return {
+        rustName: fieldName(f.name),
+        wireName: f.name,
+        rustType: rust,
+        required: !!f.required && !rust.startsWith('Option<'),
+        doc: f.description,
+      };
+    });
+  const flattenEnums = bodyGroupFields.map((g) => ({
+    rustName: g.name,
+    rustType: g.rustType,
+    required: g.required,
+    doc: g.doc,
+  }));
+  return groupEmitter.registerBody({ name, flatFields, flattenEnums });
+}
+
 /** Constructor parameter type — accept `impl Into<String>` for ergonomic strings. */
 function ctorParamType(rust: string): string {
   if (rust === 'String') return 'impl Into<String>';
@@ -235,6 +640,17 @@ function ctorParamConvert(rust: string, name: string): string {
   return name;
 }
 
+/**
+ * Detect a non-default per-operation security requirement (e.g. SSO's
+ * `get_profile` requires an OAuth access token rather than the WorkOS API
+ * key). Returns the snake_case parameter name to use for the override.
+ */
+function bearerOverrideToken(op: Operation): string | null {
+  const override = op.security?.find((s) => s.schemeName !== 'bearerAuth');
+  if (!override) return null;
+  return fieldName(override.schemeName);
+}
+
 function renderMethod(
   op: Operation,
   resolved: ResolvedOperation,
@@ -249,13 +665,19 @@ function renderMethod(
 
   const returnType = renderResponseType(op);
   const bodyRequired = isBodyRequired(op);
+  const tokenParam = bearerOverrideToken(op);
 
   const sig: string[] = [];
 
   // Convenience method — no per-request options. Delegates to `_with_options`.
   for (const line of methodDocLines(op)) sig.push(`    ${line}`);
   if (op.deprecated) sig.push('    #[deprecated]');
-  const argsConvenience = ['&self', ...pathArgList, ...(emptyParams ? [] : [`params: ${paramsType}`])];
+  const argsConvenience = [
+    '&self',
+    ...pathArgList,
+    ...(emptyParams ? [] : [`params: ${paramsType}`]),
+    ...(tokenParam ? [`${tokenParam}: impl Into<String>`] : []),
+  ];
   const convenienceSig = `    pub async fn ${method}(${argsConvenience.join(', ')}) -> Result<${returnType}, Error> {`;
   if (convenienceSig.length <= 100) {
     sig.push(convenienceSig);
@@ -264,7 +686,12 @@ function renderMethod(
     for (const arg of argsConvenience) sig.push(`        ${arg},`);
     sig.push(`    ) -> Result<${returnType}, Error> {`);
   }
-  const delegateArgs = [...pathArgNames, ...(emptyParams ? [] : ['params']), 'None'].join(', ');
+  const delegateArgs = [
+    ...pathArgNames,
+    ...(emptyParams ? [] : ['params']),
+    ...(tokenParam ? [tokenParam] : []),
+    'None',
+  ].join(', ');
   sig.push(`        self.${method}_with_options(${delegateArgs}).await`);
   sig.push('    }');
   sig.push('');
@@ -276,6 +703,7 @@ function renderMethod(
     '&self',
     ...pathArgList,
     ...(emptyParams ? [] : [`params: ${paramsType}`]),
+    ...(tokenParam ? [`${tokenParam}: impl Into<String>`] : []),
     'options: Option<&crate::RequestOptions>',
   ];
   const optsSig = `    pub async fn ${method}_with_options(${argsOpts.join(', ')}) -> Result<${returnType}, Error> {`;
@@ -304,6 +732,18 @@ function renderMethod(
 
   sig.push(`        let method = http::Method::${op.httpMethod.toUpperCase()};`);
 
+  // Bearer override: build a one-off `RequestOptions` that re-merges any
+  // caller-supplied options with the override Authorization header. Done
+  // inline so the call site can keep using the standard request helpers.
+  if (tokenParam) {
+    sig.push(`        let ${tokenParam}: String = ${tokenParam}.into();`);
+    sig.push(`        let auth = http::HeaderValue::from_str(&format!("Bearer {${tokenParam}}"))`);
+    sig.push(`            .map_err(|e| Error::Builder(format!("invalid bearer token: {e}")))?;`);
+    sig.push('        let mut merged = options.cloned().unwrap_or_default();');
+    sig.push('        merged.extra_headers.push((http::header::AUTHORIZATION, auth));');
+    sig.push('        let options = Some(&merged);');
+  }
+
   // For empty-params endpoints, pass `&()` as the (empty) query — `()`
   // serialises to nothing under serde, matching the previous empty-struct
   // behaviour without surfacing the struct in the public API.
@@ -334,43 +774,148 @@ function renderMethod(
 }
 
 /**
- * Generate a `<method>_auto_paging` helper for paginated list endpoints.
- * Returns null when the operation isn't a recognised list endpoint (response
- * model lacks both `data: Vec<T>` and `list_metadata`, or the params struct
- * has no `after` cursor).
+ * Render a URL-builder method. URL-builder ops (e.g. `GET /sso/authorize`,
+ * `GET /sso/logout`) issue no HTTP request — they format a redirect URL the
+ * application sends the user to. Generated methods return `Result<String,
+ * Error>` because percent-encoding the query string can still fail.
+ */
+function renderUrlBuilderMethod(
+  op: Operation,
+  resolved: ResolvedOperation,
+  paramsType: string,
+  method: string,
+  emptyParams: boolean,
+): string {
+  const segments = parsePathTemplate(op.path);
+  const pathArgList = op.pathParams.map((p) => `${methodName(p.name)}: &str`);
+  const pathArgNames = op.pathParams.map((p) => methodName(p.name));
+
+  const sig: string[] = [];
+  for (const line of methodDocLines(op)) sig.push(`    ${line}`);
+  if (op.deprecated) sig.push('    #[deprecated]');
+  const args = ['&self', ...pathArgList, ...(emptyParams ? [] : [`params: ${paramsType}`])];
+  const headSig = `    pub fn ${method}(${args.join(', ')}) -> Result<String, Error> {`;
+  if (headSig.length <= 100) {
+    sig.push(headSig);
+  } else {
+    sig.push(`    pub fn ${method}(`);
+    for (const arg of args) sig.push(`        ${arg},`);
+    sig.push('    ) -> Result<String, Error> {');
+  }
+
+  const pathFormat = segments
+    .map((s) => (s.kind === 'literal' ? s.value : `{${methodName(s.name as string)}}`))
+    .join('');
+  const pathHasParams = segments.some((s) => s.kind === 'param');
+
+  if (pathHasParams) {
+    for (const p of op.pathParams) {
+      const n = methodName(p.name);
+      sig.push(`        let ${n} = crate::client::path_segment(${n});`);
+    }
+    sig.push(`        let path = format!(${JSON.stringify(pathFormat)});`);
+  } else {
+    sig.push(`        let path = ${JSON.stringify(pathFormat)}.to_string();`);
+  }
+
+  // Bake constant defaults + inferred client fields directly into the query.
+  // The runtime helper handles encoding, including arrays and flatten-enum
+  // groups, so we just hand it whatever serde produces from `params`.
+  const defaults = (resolved.defaults ?? {}) as Record<string, string | number | boolean>;
+  const inferred = resolved.inferFromClient ?? [];
+  const hasDefaults = Object.keys(defaults).length > 0 || inferred.length > 0;
+  if (hasDefaults) {
+    sig.push('        let mut overlay = serde_json::Map::new();');
+    for (const [k, v] of Object.entries(defaults)) {
+      sig.push(`        overlay.insert(${JSON.stringify(k)}.to_string(), serde_json::json!(${JSON.stringify(v)}));`);
+    }
+    for (const k of inferred) {
+      sig.push(
+        `        overlay.insert(${JSON.stringify(k)}.to_string(), serde_json::Value::String(${clientFieldExpression(k)}.to_string()));`,
+      );
+    }
+    if (!emptyParams) {
+      sig.push('        let params_value = serde_json::to_value(&params)');
+      sig.push('            .map_err(|e| Error::Builder(format!("query encode failed: {e}")))?;');
+      sig.push('        if let serde_json::Value::Object(map) = params_value {');
+      sig.push('            for (k, v) in map { overlay.insert(k, v); }');
+      sig.push('        }');
+    }
+    sig.push('        let merged = serde_json::Value::Object(overlay);');
+    sig.push('        let qs = crate::query::encode_query(&merged)?;');
+  } else if (!emptyParams) {
+    sig.push('        let qs = crate::query::encode_query(&params)?;');
+  } else {
+    sig.push('        let qs = String::new();');
+  }
+
+  sig.push('        let url = if qs.is_empty() {');
+  sig.push('            format!("{}{}", self.client.base_url(), path)');
+  sig.push('        } else {');
+  sig.push('            format!("{}{}?{}", self.client.base_url(), path, qs)');
+  sig.push('        };');
+  sig.push('        Ok(url)');
+  sig.push('    }');
+
+  // Unused path params would otherwise warn; keep them in scope.
+  void pathArgNames;
+  return sig.join('\n');
+}
+
+/**
+ * Generate a `<method>_auto_paging` helper from `op.pagination`. Returns null
+ * when the operation isn't paginated, when the strategy isn't `cursor`, or
+ * when the response model lacks the expected `data` / pagination-cursor
+ * fields (defensive — the IR shouldn't produce that combination today).
  */
 function renderAutoPagingMethod(
   op: Operation,
-  _resolved: ResolvedOperation,
+  resolved: ResolvedOperation,
   paramsType: string,
   method: string,
   ctx: EmitterContext,
 ): string | null {
-  if (!op.response || op.response.kind !== 'model') return null;
-  const responseRef = op.response;
-  const responseModel = ctx.spec.models.find((m) => m.name === responseRef.name);
+  if (!op.pagination) return null;
+  // Only cursor pagination is implemented today; offset / link-header would
+  // need a different stream wrapper.
+  if (op.pagination.strategy !== 'cursor') return null;
+  if (resolved.urlBuilder) return null;
+  if (op.response.kind !== 'model') return null;
+
+  const responseModel = ctx.spec.models.find((m) => m.name === (op.response as { name: string }).name);
   if (!responseModel) return null;
 
-  const dataField = responseModel.fields.find((f) => f.name === 'data');
-  const hasListMetadata = responseModel.fields.some((f) => f.name === 'list_metadata');
-  if (!dataField || !hasListMetadata) return null;
-  if (dataField.type.kind !== 'array') return null;
-
+  const cursorParam = op.pagination.param;
+  const dataPath = op.pagination.dataPath ?? 'data';
+  const dataField = responseModel.fields.find((f) => f.name === dataPath);
+  if (!dataField || dataField.type.kind !== 'array') return null;
+  const listMetadataField = responseModel.fields.find((f) => f.name === 'list_metadata');
+  if (!listMetadataField || listMetadataField.type.kind !== 'model') return null;
+
+  // The response cursor lives on the list-metadata model under the same name
+  // as the request param. Bail if it doesn't — that would mean a spec/IR
+  // mismatch and a hand-written wrapper is safer than a broken generated one.
+  const metadataModel = ctx.spec.models.find((m) => m.name === (listMetadataField.type as { name: string }).name);
+  if (!metadataModel) return null;
+  if (!metadataModel.fields.some((f) => f.name === cursorParam)) return null;
+
+  // The IR's `pagination.itemType` is the response wrapper model (e.g.
+  // `OrganizationList`), so reach into the model's `data: Vec<T>` field to
+  // pull out the actual element type.
   const itemType = mapTypeRef(dataField.type.items);
-  // Require an `after` cursor in the params (query params).
-  const hasAfter = op.queryParams.some((p) => p.name === 'after');
-  if (!hasAfter) return null;
+
+  const cursorField = fieldName(cursorParam);
+  const dataAccessor = fieldName(dataPath);
 
   // Path args are taken by owned `String` so the returned stream borrows
-  // nothing but `&self`. This keeps the lifetime story simple — only `'_`
-  // (the `&self` lifetime) is needed on the returned `impl Stream`.
+  // nothing but `&self`.
   const pathArgList = op.pathParams.map((p) => `${methodName(p.name)}: impl Into<String>`);
   const pathArgNames = op.pathParams.map((p) => methodName(p.name));
 
   const sig: string[] = [];
   sig.push('');
   sig.push(`    /// Returns an async [\`futures_util::Stream\`] that yields every \`${itemType}\``);
-  sig.push(`    /// across all pages, advancing the \`after\` cursor under the hood.`);
+  sig.push(`    /// across all pages, advancing the \`${cursorParam}\` cursor under the hood.`);
   sig.push('    ///');
   sig.push('    /// ```ignore');
   sig.push('    /// use futures_util::TryStreamExt;');
@@ -391,22 +936,17 @@ function renderAutoPagingMethod(
     sig.push(`    ) -> impl futures_util::Stream<Item = Result<${itemType}, Error>> + '_ {`);
   }
 
-  // Coerce path args to owned `String` so the closure passed to the shared
-  // pagination helper doesn't need to borrow them across `.await`s.
   for (const n of pathArgNames) {
     sig.push(`        let ${n}: String = ${n}.into();`);
   }
-  // Delegate cursor management to the shared `auto_paginate_pages` helper:
-  // generated code only has to fetch the next page and return its
-  // `(data, after)` pair.
   sig.push('        crate::pagination::auto_paginate_pages(move |after| {');
   for (const n of pathArgNames) sig.push(`            let ${n} = ${n}.clone();`);
   sig.push('            let mut params = params.clone();');
-  sig.push('            params.after = after;');
+  sig.push(`            params.${cursorField} = after;`);
   sig.push('            async move {');
   const callArgs = [...pathArgNames.map((n) => `&${n}`), 'params'].join(', ');
   sig.push(`                let page = self.${method}(${callArgs}).await?;`);
-  sig.push('                Ok((page.data, page.list_metadata.after))');
+  sig.push(`                Ok((page.${dataAccessor}, page.list_metadata.${cursorField}))`);
   sig.push('            }');
   sig.push('        })');
   sig.push('    }');
@@ -420,8 +960,14 @@ function renderWrapperParamsStruct(
   _wrapper: ResolvedWrapper,
   params: ResolvedWrapperParam[],
   registry: UnionRegistry,
+  ctx: EmitterContext,
 ): string {
-  type FieldInfo = { fname: string; rust: string; required: boolean };
+  type FieldInfo = {
+    fname: string;
+    rust: string;
+    required: boolean;
+    defaultExpr: string | null;
+  };
   const fields: FieldInfo[] = [];
   const fieldLines: string[] = [];
   const seen = new Set<string>();
@@ -431,7 +977,10 @@ function renderWrapperParamsStruct(
     seen.add(fname);
     let rust: string;
     if (rp.field) {
-      rust = mapTypeRef(rp.field.type, { hint: `${name}${typeName(rp.paramName)}`, registry });
+      rust = mapTypeRef(rp.field.type, {
+        hint: `${name}${typeName(rp.paramName)}`,
+        registry,
+      });
     } else {
       rust = 'String';
     }
@@ -441,9 +990,14 @@ function renderWrapperParamsStruct(
     if (desc) {
       for (const c of paramDocComment(desc)) fieldLines.push(`    ${c}`);
     }
+    const fieldDefault = rp.field?.default;
+    if (fieldDefault != null) {
+      if (desc) fieldLines.push('    ///');
+      fieldLines.push(`    /// Defaults to \`${formatDefault(fieldDefault)}\`.`);
+    }
     const required = !rp.isOptional && !rust.startsWith('Option<');
     if (required) {
-      if (desc) fieldLines.push('    ///');
+      if (desc || fieldDefault != null) fieldLines.push('    ///');
       fieldLines.push('    /// Required.');
     }
     if (rust.startsWith('Option<')) {
@@ -453,16 +1007,21 @@ function renderWrapperParamsStruct(
       fieldLines.push(`    #[serde(rename = ${JSON.stringify(rp.paramName)})]`);
     }
     fieldLines.push(`    pub ${fname}: ${rust},`);
-    fields.push({ fname, rust, required });
+    const defaultExpr =
+      fieldDefault != null && rp.field
+        ? rustDefaultExpr(fieldDefault, rp.field.type, rust.startsWith('Option<'), ctx)
+        : null;
+    fields.push({ fname, rust, required, defaultExpr });
   }
 
   // Mirror the regular params struct: derive `Default` only when every field
-  // is optional, otherwise emit a `new(...)` constructor for the required
-  // ones. This prevents callers from cheaply constructing invalid request
-  // states.
+  // is optional and no field carries a spec-level default; spec defaults need
+  // a manual `impl Default` (Option<T>::default() is None).
   const requiredFields = fields.filter((f) => f.required);
   const allOptional = fields.length === 0 || requiredFields.length === 0;
-  const derives = allOptional ? 'Debug, Clone, Default, Serialize' : 'Debug, Clone, Serialize';
+  const hasSpecDefault = fields.some((f) => f.defaultExpr !== null);
+  const canDeriveDefault = allOptional && !hasSpecDefault;
+  const derives = canDeriveDefault ? 'Debug, Clone, Default, Serialize' : 'Debug, Clone, Serialize';
 
   const out: string[] = [];
   if (fieldLines.length === 0) {
@@ -471,6 +1030,18 @@ function renderWrapperParamsStruct(
     out.push(`#[derive(${derives})]`, `pub struct ${name} {`, ...fieldLines, '}');
   }
 
+  if (allOptional && hasSpecDefault) {
+    const defaultInitLines = fields.map((f) => `            ${f.fname}: ${f.defaultExpr ?? 'Default::default()'},`);
+    out.push('');
+    out.push(`impl Default for ${name} {`);
+    out.push('    fn default() -> Self {');
+    out.push('        Self {');
+    out.push(...defaultInitLines);
+    out.push('        }');
+    out.push('    }');
+    out.push('}');
+  }
+
   if (requiredFields.length > 0) {
     const ctorArgs = requiredFields.map((f) => `${f.fname}: ${ctorParamType(f.rust)}`).join(', ');
     const initLines: string[] = [];
@@ -479,7 +1050,7 @@ function renderWrapperParamsStruct(
         const value = ctorParamConvert(f.rust, f.fname);
         initLines.push(value === f.fname ? `            ${f.fname},` : `            ${f.fname}: ${value},`);
       } else {
-        initLines.push(`            ${f.fname}: Default::default(),`);
+        initLines.push(`            ${f.fname}: ${f.defaultExpr ?? 'Default::default()'},`);
       }
     }
     out.push('');
@@ -616,6 +1187,60 @@ function paramDocComment(text: string): string[] {
     .map((l) => `/// ${l}`);
 }
 
+/**
+ * Render a spec-level default value for inclusion in a doc comment. Strings
+ * render bare (e.g. `desc`) so they nest naturally inside the surrounding
+ * backticks; numbers/booleans use JSON encoding.
+ */
+function formatDefault(value: unknown): string {
+  if (typeof value === 'string') return value;
+  return JSON.stringify(value);
+}
+
+/**
+ * Render a spec-level default value as a Rust expression suitable for an
+ * `impl Default` body or a `new(…)` initialiser. When `isOptional` is true the
+ * result is wrapped in `Some(…)` so it matches an `Option<T>` field.
+ *
+ * Returns `null` for types/values the emitter doesn't know how to materialise
+ * — caller falls back to `Default::default()`.
+ */
+function rustDefaultExpr(value: unknown, ref: TypeRef, isOptional: boolean, ctx: EmitterContext): string | null {
+  if (ref.kind === 'nullable') {
+    return rustDefaultExpr(value, ref.inner, isOptional, ctx);
+  }
+
+  let expr: string | null = null;
+  switch (ref.kind) {
+    case 'primitive':
+      if (ref.type === 'integer' && typeof value === 'number' && Number.isFinite(value)) {
+        expr = String(Math.trunc(value));
+      } else if (ref.type === 'number' && typeof value === 'number' && Number.isFinite(value)) {
+        // Floats need a decimal point so the literal parses as `f64`, not `i32`.
+        expr = Number.isInteger(value) ? `${value}.0` : String(value);
+      } else if (ref.type === 'boolean' && typeof value === 'boolean') {
+        expr = String(value);
+      } else if (ref.type === 'string' && typeof value === 'string') {
+        expr = `${JSON.stringify(value)}.to_string()`;
+      }
+      break;
+    case 'enum': {
+      if (typeof value !== 'string' && typeof value !== 'number') break;
+      const enumDef = ctx.spec.enums.find((e) => e.name === ref.name);
+      if (!enumDef) break;
+      const ev = enumDef.values.find((v) => v.value === value);
+      if (!ev) break;
+      expr = `${typeName(ref.name)}::${variantName(ev.value)}`;
+      break;
+    }
+    default:
+      break;
+  }
+
+  if (expr === null) return null;
+  return isOptional ? `Some(${expr})` : expr;
+}
+
 function methodDocLines(op: Operation): string[] {
   const lines: string[] = [];
   if (op.description && op.description.trim().length > 0) {
@@ -659,16 +1284,26 @@ function isBodyRequired(op: Operation): boolean {
 
 /**
  * `true` when the resolved operation contributes nothing to a params struct:
- * no request body, and every exposed query/header parameter is inferred from
- * the client or supplied as a default. Such methods take no `params:` arg in
- * the public API and skip the empty struct entirely.
+ * no request body, and every exposed query/header/cookie parameter is
+ * inferred from the client or supplied as a default. Such methods take no
+ * `params:` arg in the public API and skip the empty struct entirely.
  */
 function isEmptyParams(op: Operation, resolved: ResolvedOperation): boolean {
   if (op.requestBody) return false;
   const hidden = new Set<string>([...Object.keys(resolved.defaults ?? {}), ...(resolved.inferFromClient ?? [])]);
-  const visibleQuery = op.queryParams.filter((p) => !hidden.has(p.name));
+  const grouped = new Set<string>();
+  for (const g of op.parameterGroups ?? []) {
+    for (const v of g.variants) for (const p of v.parameters) grouped.add(p.name);
+  }
+  const visibleQuery = op.queryParams.filter((p) => !hidden.has(p.name) && !grouped.has(p.name));
   const visibleHeader = op.headerParams.filter((p) => !hidden.has(p.name));
-  return visibleQuery.length === 0 && visibleHeader.length === 0;
+  const visibleCookie = (op.cookieParams ?? []).filter((p) => !hidden.has(p.name));
+  return (
+    visibleQuery.length === 0 &&
+    visibleHeader.length === 0 &&
+    visibleCookie.length === 0 &&
+    (op.parameterGroups?.length ?? 0) === 0
+  );
 }
 
 function renderResourcesBarrel(exports: { module: string; struct: string }[]): string {