@workos/oagen-emitters 0.16.0 → 0.17.0

package/src/node/resources.ts

@@ -225,7 +225,12 @@ function ignoredResourceMethodNames(ctx: EmitterContext, resourcePath: string):
   const methods = new Set<string>();
   for (const block of content.matchAll(/@oagen-ignore-start[\s\S]*?@oagen-ignore-end/g)) {
     for (const line of block[0].split('\n')) {
-      const match = line.match(/^\s{2}(?:(?:public|private|protected)\s+)?(?:async\s+)?([A-Za-z_$][\w$]*)\s*\(/);
+      // Match the method name followed by `(` or by `<` — the latter covers
+      // generic methods (`getProfile<T extends ...>(...)`), including
+      // multi-line type-parameter lists where the line ends right after `<`.
+      // Matching only up to the opening bracket sidesteps balancing nested
+      // angle brackets like `<T extends Record<string, unknown> = ...>`.
+      const match = line.match(/^\s{2}(?:(?:public|private|protected)\s+)?(?:async\s+)?([A-Za-z_$][\w$]*)\s*[<(]/);
       if (match) methods.add(match[1]);
     }
   }
@@ -310,6 +315,18 @@ function renderOptionsParam(param: OptionsObjectParam): string {
   return `options${param.optional ? '?' : ''}: ${param.type}`;
 }
 
+/**
+ * Whether a baseline-derived type reference is a plain TypeScript identifier
+ * that can appear in a named import. Baseline (live-SDK) method params can
+ * carry inline object-literal TYPES (e.g. `{ intent: GenerateLinkIntent; ... }`);
+ * treating that literal text as a type NAME would slugify it into a filename
+ * and emit a named import of a brace-expression — both invalid. Literal types
+ * are kept inline in the emitted signature instead and never imported.
+ */
+function isValidTypeIdentifier(name: string): boolean {
+  return /^[A-Za-z_$][\w$]*$/.test(name);
+}
+
 function autoPaginatableItemType(returnType: string | undefined): string | undefined {
   // Match both AutoPaginatable<T> and the legacy List<T> pattern so baseline
   // item types are extracted even when the hand-written code predates AutoPaginatable.
@@ -916,6 +933,20 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
     lines.push("import { AutoPaginatable } from '../common/utils/pagination';");
     lines.push("import { fetchAndDeserialize } from '../common/utils/fetch-and-deserialize';");
   }
+  // URL-builder methods serialize their query string client-side via toQueryString.
+  const needsQueryStringImport = plans.some((p) => {
+    const r = lookupResolved(p.op, resolvedLookup);
+    if (!r?.urlBuilder) return false;
+    const hidden = hiddenParamsFor(r);
+    return (
+      p.op.queryParams.some((qp) => !hidden.has(qp.name)) ||
+      Object.keys(getOpDefaults(r)).length > 0 ||
+      getOpInferFromClient(r).length > 0
+    );
+  });
+  if (needsQueryStringImport) {
+    lines.push("import { toQueryString } from '../common/utils/query-string';");
+  }
   const shouldEmitVaultCryptoHelpers =
     serviceClass === 'Vault' && !ignoredMethodNames.has('encrypt') && !ignoredMethodNames.has('decrypt');
   if (shouldEmitVaultCryptoHelpers) {
@@ -933,6 +964,9 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
 
   const importedTypeNames = new Set<string>();
   for (const optionType of optionObjectTypes) {
+    // Inline object-literal types from the baseline surface are rendered
+    // inline in the method signature — they have no importable name or file.
+    if (!isValidTypeIdentifier(optionType)) continue;
     if (importedTypeNames.has(optionType)) continue;
     importedTypeNames.add(optionType);
     const sourceFile = baselineTypeSourceFile(ctx, optionType);
@@ -1313,6 +1347,16 @@ function renderMethod(
   const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
   const baselineClassMethod = baselineMethodFor(service, method, ctx);
   const optionInfo = optionsObjectInfo(service, method, op, plan, ctx, baselineClassMethod, resolvedOp);
+
+  // URL-builder operations (e.g. GET /sso/authorize) are spec-marked client-side
+  // URL constructors: emit a synchronous method that returns the request URL as
+  // a string without performing any I/O. This bypasses the HTTP method dispatch
+  // and the Promise-typed JSDoc below.
+  if (resolvedOp?.urlBuilder) {
+    renderUrlBuilderMethod(lines, op, method, pathStr, optionInfo, specEnumNames, resolvedOp);
+    return lines;
+  }
+
   const overlayMethod = ctx.overlayLookup?.methodByOperation?.get(httpKey) ?? baselineClassMethod;
   let validParamNames: Set<string> | null = null;
   if (optionInfo) {
@@ -1675,7 +1719,17 @@ function renderOptionsObjectMethod(
     const wireType = wireInterfaceName(itemType);
     const extraParams = op.queryParams.filter((p) => !PAGINATION_PARAM_NAMES.has(p.name));
     const needsWireSerializer = extraParams.some((p) => fieldName(p.name) !== wireFieldName(p.name));
-    const paginationType = needsWireSerializer ? 'PaginationOptions' : optionParam.type;
+    // When path params are destructured out of the options object, the value
+    // passed to AutoPaginatable (and to fetchAndDeserialize) is the REST
+    // object — typed Omit<FullOptions, pathFields> — not the full options
+    // interface. Declaring the full interface as the second type argument
+    // fails TS2322 because the rest object lacks the required path-param
+    // fields, so parameterize over the rest type actually passed.
+    const restOptionsType =
+      pathBindings.length > 0
+        ? `Omit<${optionParam.type}, ${pathBindings.map((b) => `'${b}'`).join(' | ')}>`
+        : optionParam.type;
+    const paginationType = needsWireSerializer ? 'PaginationOptions' : restOptionsType;
     const returnType = needsWireSerializer
       ? `Promise<AutoPaginatable<${itemType}, ${paginationType}>>`
       : (preferredBaselineReturnType(ctx, baselineMethod?.returnType) ??
@@ -1793,7 +1847,13 @@ function renderOptionsObjectMethod(
 
     lines.push(`  async ${method}(${renderOptionsParam(optionParam)}): ${methodReturnType} {`);
     renderOptionsObjectDestructure(lines, pathBindings);
-    lines.push(`    const { data } = await this.workos.${op.httpMethod}<${wireType}>(${pathStr}${queryOptionsArg});`);
+    // POST/PUT/PATCH require the entity argument even without a request body —
+    // the client signature is `post(path, entity, options?)`, so a body-less
+    // call must still pass `{}` or the generated code fails with TS2554.
+    const emptyBodyArg = httpMethodNeedsBody(op.httpMethod) ? ', {}' : '';
+    lines.push(
+      `    const { data } = await this.workos.${op.httpMethod}<${wireType}>(${pathStr}${emptyBodyArg}${queryOptionsArg});`,
+    );
     if (override?.returnExpression) {
       lines.push(`    const result = ${returnExpr};`);
       lines.push(`    return ${override.returnExpression};`);
@@ -2173,6 +2233,109 @@ function clientFieldExpression(field: string): string {
   }
 }
 
+/**
+ * Compose a `` `${this.workos.baseURL}<path>[?${query}]` `` template literal from
+ * a path expression produced by {@link buildPathStr}. The path expression is
+ * either a single-quoted static literal (`'/sso/authorize'`) or a backtick
+ * template with interpolated path params; either way its inner body is spliced
+ * into the URL template.
+ */
+function urlTemplateLiteral(pathExpr: string, hasQuery: boolean): string {
+  let inner: string;
+  if ((pathExpr.startsWith('`') && pathExpr.endsWith('`')) || (pathExpr.startsWith("'") && pathExpr.endsWith("'"))) {
+    inner = pathExpr.slice(1, -1);
+  } else {
+    inner = '${' + pathExpr + '}';
+  }
+  return '`${this.workos.baseURL}' + inner + (hasQuery ? '?${query}' : '') + '`';
+}
+
+/**
+ * Emit a URL-builder method for an operation marked with the `urlBuilder` hint
+ * (OAuth-style redirect endpoints such as `/sso/authorize`). The method is
+ * synchronous, returns the constructed URL as a string, and makes no HTTP call.
+ * Visible query params, constant `defaults`, and `inferFromClient` fields are
+ * serialized via `toQueryString` (wire-name keyed), matching the SDK's
+ * hand-written URL builders.
+ */
+function renderUrlBuilderMethod(
+  lines: string[],
+  op: Operation,
+  method: string,
+  pathStr: string,
+  optionInfo: OptionsObjectParam | undefined,
+  specEnumNames: Set<string> | undefined,
+  resolvedOp: ResolvedOperation | undefined,
+): void {
+  const hidden = hiddenParamsFor(resolvedOp);
+  const visibleQueryParams = op.queryParams.filter((p) => !hidden.has(p.name));
+  const hasQuery =
+    visibleQueryParams.length > 0 ||
+    Object.keys(getOpDefaults(resolvedOp)).length > 0 ||
+    getOpInferFromClient(resolvedOp).length > 0;
+
+  // Concise JSDoc — url builders return a string, not a Promise.
+  {
+    const docParts: string[] = [];
+    if (op.description) docParts.push(op.description);
+    docParts.push('@returns {string} The constructed URL.');
+    if (op.deprecated) docParts.push('@deprecated');
+    const allLines = docParts.flatMap((p) => p.split('\n'));
+    if (allLines.length === 1) {
+      lines.push(`  /** ${allLines[0]} */`);
+    } else {
+      lines.push('  /**');
+      for (const line of allLines) lines.push(line === '' ? '   *' : `   * ${line}`);
+      lines.push('   */');
+    }
+  }
+
+  if (optionInfo) {
+    // Options-object convention (matches the surrounding generated methods).
+    lines.push(`  ${method}(${renderOptionsParam(optionInfo)}): string {`);
+    if (hasQuery) {
+      const queryExpr = renderQueryExprWithOptions(visibleQueryParams, optionInfo.optional, resolvedOp);
+      lines.push(`    const query = toQueryString(${queryExpr});`);
+      lines.push(`    return ${urlTemplateLiteral(pathStr, true)};`);
+    } else {
+      lines.push(`    return ${urlTemplateLiteral(pathStr, false)};`);
+    }
+    lines.push('  }');
+    return;
+  }
+
+  // Positional convention (path-only url builders, possibly with injected fields).
+  // Invariant: any visible query param forces the options-object branch above
+  // (operationHasOptionsInput is true whenever one exists), so a positional
+  // builder never declares query params in its signature. Fail loudly if a
+  // future spec breaks that — its query value would have to come from an
+  // undeclared parameter. Past this guard the query is assembled solely from
+  // injected defaults and inferFromClient fields.
+  if (visibleQueryParams.length > 0) {
+    throw new Error(
+      `renderUrlBuilderMethod: positional url builder "${method}" has visible query params ` +
+        `(${visibleQueryParams.map((p) => p.name).join(', ')}) but no options object; they would be ` +
+        'referenced without being declared. Expected the options-object convention.',
+    );
+  }
+  const params = buildPathParams(op, specEnumNames);
+  lines.push(`  ${method}(${params}): string {`);
+  if (hasQuery) {
+    const queryParts: string[] = [];
+    for (const [key, value] of Object.entries(getOpDefaults(resolvedOp))) {
+      queryParts.push(`${key}: ${tsLiteral(value)}`);
+    }
+    for (const field of getOpInferFromClient(resolvedOp)) {
+      queryParts.push(`${field}: ${clientFieldExpression(field)}`);
+    }
+    lines.push(`    const query = toQueryString({ ${queryParts.join(', ')} });`);
+    lines.push(`    return ${urlTemplateLiteral(pathStr, true)};`);
+  } else {
+    lines.push(`    return ${urlTemplateLiteral(pathStr, false)};`);
+  }
+  lines.push('  }');
+}
+
 function renderVoidMethod(
   lines: string[],
   op: Operation,

package/src/node/utils.ts

@@ -11,12 +11,15 @@ import { mapTypeRef } from './type-map.js';
 import {
   resolveInterfaceName,
   fieldName,
+  fileName,
   resolveServiceDir,
   resolveMethodName,
   buildServiceNameMap,
 } from './naming.js';
-import { getMountTarget } from '../shared/resolved-ops.js';
-import { assignModelsToServices } from '@workos/oagen';
+import { getMountTarget, groupByMount } from '../shared/resolved-ops.js';
+import { assignModelsToServices, collectModelRefs, collectFieldDependencies } from '@workos/oagen';
+import { isNodeOwnedService } from './options.js';
+import { liveSurfaceHasExistingSdk, liveSurfaceHasFile } from './live-surface.js';
 
 /**
  * Compute a relative import path between two files within the generated SDK.
@@ -203,7 +206,7 @@ export function createServiceDirResolver(
   serviceNameMap: Map<string, string>;
   resolveDir: (irService: string | undefined) => string;
 } {
-  const modelToService = assignModelsToServices(models, services, ctx.modelHints);
+  const modelToService = assignModelsToEmittableServices(models, services, ctx);
   const serviceNameMap = buildServiceNameMap(services, ctx);
 
   // Per-name → directory override, harvested from the live SDK surface.
@@ -212,25 +215,7 @@ export function createServiceDirResolver(
   // baseline directory string (e.g., "user-management"). The override map is
   // attached by tagging the model name with a directory prefix that bypasses
   // the IR-service lookup. Concretely we keep a side map.
-  const baselineDirByModel = new Map<string, string>();
-  const recordSource = (name: string, info: { sourceFile?: string } | undefined) => {
-    const sourceFile = info?.sourceFile;
-    if (!sourceFile) return;
-    const m = sourceFile.match(/^src\/([^/]+)\//);
-    if (!m) return;
-    baselineDirByModel.set(name, m[1]);
-  };
-  // Both interfaces and type aliases can shadow IR model names — e.g.
-  // `type Role = EnvironmentRole | OrganizationRole;` is the live SDK's
-  // canonical Role definition even though the IR represents Role as a model.
-  for (const [name, info] of Object.entries(ctx.apiSurface?.interfaces ?? {})) {
-    recordSource(name, info as { sourceFile?: string });
-  }
-  for (const [name, info] of Object.entries(ctx.apiSurface?.typeAliases ?? {})) {
-    if (!baselineDirByModel.has(name)) {
-      recordSource(name, info as { sourceFile?: string });
-    }
-  }
+  const baselineDirByModel = harvestBaselineDirByModel(ctx);
 
   // Override modelToService for any IR model that has a baseline sourceFile.
   // We invent a synthetic IR-service key that maps directly to the baseline
@@ -255,6 +240,139 @@ export function createServiceDirResolver(
   return { modelToService, serviceNameMap, resolveDir };
 }
 
+/**
+ * Map baseline interface / type-alias names to the top-level `src/<dir>/`
+ * their `sourceFile` lives in. Both kinds can shadow IR model names — e.g.
+ * `type Role = EnvironmentRole | OrganizationRole;` is the live SDK's
+ * canonical Role definition even though the IR represents Role as a model.
+ */
+function harvestBaselineDirByModel(ctx: EmitterContext): Map<string, string> {
+  const baselineDirByModel = new Map<string, string>();
+  const recordSource = (name: string, info: { sourceFile?: string } | undefined) => {
+    const sourceFile = info?.sourceFile;
+    if (!sourceFile) return;
+    const m = sourceFile.match(/^src\/([^/]+)\//);
+    if (!m) return;
+    baselineDirByModel.set(name, m[1]);
+  };
+  for (const [name, info] of Object.entries(ctx.apiSurface?.interfaces ?? {})) {
+    recordSource(name, info as { sourceFile?: string });
+  }
+  for (const [name, info] of Object.entries(ctx.apiSurface?.typeAliases ?? {})) {
+    if (!baselineDirByModel.has(name)) {
+      recordSource(name, info as { sourceFile?: string });
+    }
+  }
+  return baselineDirByModel;
+}
+
+/**
+ * `assignModelsToServices` plus an owned-service correction pass.
+ *
+ * The engine's assignment is first-reference-wins: a model referenced by both
+ * Organizations and AuditLogs lands in `organizations/` even when only
+ * AuditLogs is owned this run. Against an existing SDK, `applyLiveSurface`
+ * then drops the model file (a non-owned, non-adopted directory cannot
+ * receive new paths) while the owned resource still imports
+ * `../organizations/interfaces/<model>.interface` — an import that resolves
+ * to nothing (TS2307).
+ *
+ * The correction re-homes such models to the owned service that references
+ * them, so emission and import planning agree on a directory that is allowed
+ * to receive files. It only fires when:
+ *  1. `ownedServices` is configured and the run targets an existing SDK;
+ *  2. the model has no baseline `sourceFile` (otherwise the baseline-dir
+ *     override keeps imports pointing at the on-disk location);
+ *  3. the model's computed interface path does not already exist on disk;
+ *  4. the assigned service is neither owned itself nor sharing a directory
+ *     with an owned service.
+ */
+export function assignModelsToEmittableServices(
+  models: Model[],
+  services: Service[],
+  ctx?: EmitterContext,
+): Map<string, string> {
+  const modelToService = assignModelsToServices(models, services, ctx?.modelHints);
+  if (ctx) {
+    reassignOwnedServiceDependencies(modelToService, models, services, ctx);
+  }
+  return modelToService;
+}
+
+function reassignOwnedServiceDependencies(
+  modelToService: Map<string, string>,
+  models: Model[],
+  services: Service[],
+  ctx: EmitterContext,
+): void {
+  const serviceNameMap = buildServiceNameMap(services, ctx);
+  // Ownership is a property of the MOUNT target, not the IR service: an op
+  // can live on a non-owned IR service (e.g. Organizations, because its path
+  // starts with /organizations) while being mounted on an owned service via
+  // `resolvedOperations` (e.g. AuditLogs' retention endpoints). Walking only
+  // IR services misses such ops entirely, so the models they reference stay
+  // assigned to the unemittable IR directory and are never emitted anywhere.
+  // Regroup by mount target when resolved operations exist — same as
+  // `buildGeneratedResourceModelUsage` and `computeOwnedServiceDirs`.
+  const mountGroups = groupByMount(ctx);
+  const candidateServices: Service[] =
+    mountGroups.size > 0 ? [...mountGroups].map(([name, group]) => ({ name, operations: group.operations })) : services;
+  const ownedServices = candidateServices.filter((s) => isNodeOwnedService(ctx, s.name, serviceNameMap.get(s.name)));
+  if (ownedServices.length === 0) return;
+  // Greenfield generation emits every directory; nothing is unemittable.
+  if (!liveSurfaceHasExistingSdk()) return;
+
+  const dirOf = (irService: string | undefined): string =>
+    irService ? resolveServiceDir(serviceNameMap.get(irService) ?? irService) : 'common';
+  const ownedDirs = new Set(ownedServices.map((s) => dirOf(s.name)));
+  const baselineDirByModel = harvestBaselineDirByModel(ctx);
+  const modelsByName = new Map(models.map((m) => [m.name, m]));
+
+  for (const service of ownedServices) {
+    for (const name of collectServiceModelClosure(service, modelsByName)) {
+      if (!modelsByName.has(name)) continue;
+      if (baselineDirByModel.has(name)) continue; // declared in the baseline → on disk
+      const assigned = modelToService.get(name);
+      if (assigned && isNodeOwnedService(ctx, assigned, serviceNameMap.get(assigned))) continue;
+      const assignedDir = dirOf(assigned);
+      if (ownedDirs.has(assignedDir)) continue;
+      if (liveSurfaceHasFile(`src/${assignedDir}/interfaces/${fileName(name)}.interface.ts`)) continue;
+      modelToService.set(name, service.name);
+    }
+  }
+}
+
+/** Model names referenced by a service's operations, expanded through fields. */
+function collectServiceModelClosure(service: Service, modelsByName: Map<string, Model>): Set<string> {
+  const referenced = new Set<string>();
+  const add = (ref: TypeRef | undefined): void => {
+    if (!ref) return;
+    for (const name of collectModelRefs(ref)) referenced.add(name);
+  };
+  for (const op of service.operations) {
+    add(op.requestBody);
+    add(op.response);
+    for (const param of [...op.pathParams, ...op.queryParams, ...op.headerParams, ...(op.cookieParams ?? [])]) {
+      add(param.type);
+    }
+    if (op.pagination) add(op.pagination.itemType);
+  }
+
+  const queue = [...referenced];
+  while (queue.length > 0) {
+    const name = queue.pop()!;
+    const model = modelsByName.get(name);
+    if (!model) continue;
+    for (const dep of collectFieldDependencies(model).models) {
+      if (!referenced.has(dep)) {
+        referenced.add(dep);
+        queue.push(dep);
+      }
+    }
+  }
+  return referenced;
+}
+
 /**
  * Check if baseline interface fields appear to contain generic type parameters.
  *

package/src/rust/resources.ts

@@ -886,29 +886,40 @@ function renderAutoPagingMethod(
   // 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 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);
+  let itemType: string;
+
+  if (op.response.kind === 'model') {
+    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 === 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.
+    itemType = mapTypeRef(dataField.type.items);
+  } else if (isInlineEnvelopeList(op) && cursorParam === 'after') {
+    // Inline-envelope responses decode into `crate::pagination::Page<T>`,
+    // which declares `data` + `list_metadata.after` by construction — only
+    // the request-side cursor param needs to exist.
+    if (!op.queryParams.some((p) => p.name === cursorParam)) return null;
+    itemType = mapTypeRef((op.response as { items: TypeRef }).items);
+  } else {
+    return null;
+  }
 
   const cursorField = fieldName(cursorParam);
   const dataAccessor = fieldName(dataPath);
@@ -1144,19 +1155,27 @@ function renderWrapperMethod(
 
   sig.push(`        let method = http::Method::${op.httpMethod.toUpperCase()};`);
 
-  // Build the JSON body inline: defaults + inferFromClient (read from the
-  // client at request time) + each exposed param.
-  sig.push('        let body = serde_json::json!({');
+  // Build the JSON body inline: defaults + each exposed param. inferFromClient
+  // fields (read from the client at request time) are added afterwards, and
+  // only when non-empty — a client configured without an API key (e.g. a
+  // public client running a PKCE flow) must omit `client_secret` entirely
+  // rather than send `""`, which the API rejects. Mirrors the Go emitter's
+  // `omitempty` on inferred fields.
+  const inferredFields = wrapper.inferFromClient ?? [];
+  sig.push(`        let ${inferredFields.length > 0 ? 'mut ' : ''}body = serde_json::json!({`);
   for (const [k, v] of Object.entries(wrapper.defaults ?? {})) {
     sig.push(`            ${JSON.stringify(k)}: ${JSON.stringify(v)},`);
   }
-  for (const k of wrapper.inferFromClient ?? []) {
-    sig.push(`            ${JSON.stringify(k)}: ${clientFieldExpression(k)},`);
-  }
   for (const rp of params) {
     sig.push(`            ${JSON.stringify(rp.paramName)}: params.${fieldName(rp.paramName)},`);
   }
   sig.push('        });');
+  for (const k of inferredFields) {
+    const expr = clientFieldExpression(k);
+    sig.push(`        if !${expr}.is_empty() {`);
+    sig.push(`            body[${JSON.stringify(k)}] = serde_json::Value::String(${expr}.to_string());`);
+    sig.push('        }');
+  }
 
   sig.push('        #[derive(Serialize)]');
   sig.push('        struct EmptyQuery {}');
@@ -1170,8 +1189,11 @@ function renderWrapperMethod(
 
 /**
  * Rust expression for reading a client-config field at request time. Mirrors
- * the Go emitter's `clientFieldExpression`. Falls back to an empty literal
- * for unknown fields so the body still compiles.
+ * the Go emitter's `clientFieldExpression`. Throws on unknown fields rather
+ * than falling back to an empty literal: with the `if !expr.is_empty()` guard
+ * in `renderWrapperMethod`, an empty literal would silently drop the field from
+ * every request body (and emit dead `if !"".is_empty()` Rust). Failing loud at
+ * generation time surfaces a missing case instead of shipping a broken SDK.
  */
 function clientFieldExpression(field: string): string {
   switch (field) {
@@ -1180,7 +1202,10 @@ function clientFieldExpression(field: string): string {
     case 'client_secret':
       return 'self.client.api_key()';
     default:
-      return '""';
+      throw new Error(
+        `Rust emitter: no client-config accessor for inferFromClient field "${field}". ` +
+          'Add a case to clientFieldExpression.',
+      );
   }
 }
 
@@ -1266,9 +1291,33 @@ function methodDocLines(op: Operation): string[] {
 
 function renderResponseType(op: Operation): string {
   if (isEmptyResponse(op)) return '()';
+  if (isInlineEnvelopeList(op)) {
+    return `crate::pagination::Page<${mapTypeRef((op.response as { items: TypeRef }).items)}>`;
+  }
   return mapTypeRef(op.response!);
 }
 
+/**
+ * True when the spec declared this response as an inline pagination envelope
+ * (`{ object, data: [...], list_metadata }` without a named component). The IR
+ * models these as a bare array plus `pagination.dataPath`, but the wire format
+ * is still the envelope — decoding the body straight into `Vec<T>` fails, so
+ * these ops decode into the hand-maintained `crate::pagination::Page<T>`
+ * instead. Restricted to `data` because that's the field `Page<T>` declares.
+ *
+ * The `=== 'data'` is a strict equality on purpose — deliberately *not* the
+ * `?? 'data'` fallback used elsewhere. `dataPath` is the only signal that
+ * separates an inline envelope (decoded as `Page<T>`) from a genuine paginated
+ * bare array (decoded as `Vec<T>`, see the `responseKind === 'array'` branch in
+ * tests.ts). This therefore relies on the IR setting `dataPath: 'data'`
+ * explicitly for envelope responses and leaving it unset for bare arrays. If
+ * the IR ever omitted it for an envelope op, this would return `false` and the
+ * op would decode into `Vec<T>` and fail — so that invariant must hold upstream.
+ */
+export function isInlineEnvelopeList(op: Operation): boolean {
+  return op.response?.kind === 'array' && op.pagination?.dataPath === 'data';
+}
+
 /**
  * True when the operation has no usable response schema. We treat the IR's
  * `primitive: unknown` and missing-response cases the same way: the spec

package/src/rust/tests.ts

@@ -14,6 +14,7 @@ import { methodName, moduleName, typeName } from './naming.js';
 import { groupByMount } from '../shared/resolved-ops.js';
 import { exampleFor, generateFixtures } from './fixtures.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
+import { isInlineEnvelopeList } from './resources.js';
 
 /**
  * Generate integration tests under `tests/`. Each mount group gets one
@@ -163,7 +164,11 @@ function renderRegularTest(
   const m = methodName(resolved.methodName);
   const literalPath = op.path.replace(/\{[^}]+\}/g, 'test_id');
   const httpMethod = op.httpMethod.toUpperCase();
-  const responseExpr = responseBodyExpr(op.response, modelMap, enumMap);
+  // Inline-envelope lists decode via crate::pagination::Page<T>, so the mock
+  // must serve the envelope even though the IR types the response as an array.
+  const responseExpr = isInlineEnvelopeList(op)
+    ? JSON.stringify('{"object":"list","data":[],"list_metadata":{"before":null,"after":null}}')
+    : responseBodyExpr(op.response, modelMap, enumMap);
   const isUrlBuilder = resolved.urlBuilder === true;
 
   const callArgs = buildCallArgs(op, resolved, crate, accessor, modelMap, enumMap).join(', ');
@@ -413,7 +418,12 @@ function emptyPageTest(op: Operation, shape: CallShape, accessor: string): strin
   const responseKind = op.response.kind;
   let body: string;
   let dataAccessor: string;
-  if (responseKind === 'array') {
+  if (isInlineEnvelopeList(op)) {
+    // Inline-envelope paginated response: SDK returns crate::pagination::Page<T>,
+    // so the mock must serve the envelope and assertions go through `.data`.
+    body = '{"object":"list","data":[],"list_metadata":{"before":null,"after":null}}';
+    dataAccessor = 'resp.data';
+  } else if (responseKind === 'array') {
     // Bare-array paginated response: SDK returns Vec<T>.
     body = '[]';
     dataAccessor = 'resp';
@@ -558,9 +568,10 @@ function encodesQueryParamsTest(
 /** Body expression for the encoding-test response (success, ignored). */
 function encodingResponseExpr(op: Operation, modelMap: Map<string, Model>, enumMap: Map<string, Enum>): string {
   // For paginated ops we serve an empty page so the call succeeds. Use the
-  // bare-array shape for `Vec<T>` responses, the wrapper shape otherwise.
+  // bare-array shape for `Vec<T>` responses, the wrapper shape for named
+  // wrapper models and inline envelopes (decoded via Page<T>).
   if (op.pagination) {
-    if (op.response.kind === 'array') return JSON.stringify('[]');
+    if (op.response.kind === 'array' && !isInlineEnvelopeList(op)) return JSON.stringify('[]');
     return JSON.stringify('{"object":"list","data":[],"list_metadata":{"before":null,"after":null}}');
   }
   return responseBodyExpr(op.response, modelMap, enumMap);