Changelog

(fix): Generated endpoint JSDoc now documents all thrown error paths: in addition to the errors declared in the API definition, each method’s @throws annotations include the base API error class (thrown for any undeclared HTTP error status code) and the timeout error class (thrown when the request times out).

(fix): Send grant_type: "client_credentials" in the OAuth token request when the token endpoint models grant_type as a plain (non-literal) string. Previously the generated OAuthAuthProvider omitted grant_type entirely, so token requests against OpenAPI-imported specs (where grant_type is an optional string rather than a literal) failed. A required non-literal grant_type is no longer surfaced as a user-supplied client-credentials option; it is synthesized automatically.

(feat): Add automatic idempotency-key generation, driven by the centralized idempotencyKeyGeneration config in the IR. When enabled, the generated SDK attaches a UUIDv4 idempotency-key header (default Idempotency-Key) to requests whose HTTP method is listed in the IR (default POST/PUT). A caller-supplied key in request options still takes precedence.

(feat): Add support for server URL variables (e.g. region/edge routing). Server variables defined on the API’s environments are now exposed as optional string options on the client constructor and interpolated into the base URL(s) at request time. Reserved option names are de-collided by prefixing with serverUrl (e.g. a variable named environment is exposed as serverUrlEnvironment).

(fix): Fix compile errors in the generated OAuthAuthProvider when the serde layer is disabled: the token endpoint method is now called with the same camelCase name that the generated client exposes (previously the original casing, e.g. CreateOauth2Token, was used). Also guard against optional access_token response properties so the token refresh path satisfies its Promise<string> return type instead of string | undefined.

(fix): Make the structured User-Agent (emitted when includePlatformHeaders is enabled) comply with the RFC 7230 token grammar. The npm package name is now percent-encoded in the product token so the @ and / of a scoped package are escaped (e.g. @dummy/sdk/0.0.1 becomes %40dummy%2Fsdk/0.0.1); the original name can be recovered by URL-decoding. The architecture label is also normalized so the 64-bit x86 aliases (x64, amd64, x86_64) all report as the canonical x86_64.

(feat): Add opt-in support for a structured User-Agent header of the form {sdkName}/{version} ({os}; {arch}) {runtime}/{runtimeVersion}, matching the Twilio helper-library shape. This is gated behind the includePlatformHeaders config option and is disabled by default, so existing generated output is unchanged. When enabled, the platform + runtime information is consolidated into the User-Agent and the discrete X-Fern-Runtime / X-Fern-Runtime-Version headers are omitted. The platform group and runtime segment are dropped gracefully in environments where they cannot be determined (e.g. browsers), and the header remains subject to omitFernHeaders.

(fix): Pin the npm toolchain used by the generated publish workflow. The .github/workflows/ci.yml publish job now runs on a pinned Node LTS (node-version: "lts/Krypton") and calls npm publish directly instead of npx -y npm@latest publish. Relying on npm@latest pulled whatever npm release was newest at publish time, so a broken npm release could break publishing. The pinned Node LTS bundles an npm that supports OIDC trusted publishing. The npx semver invocation used for backport detection is also pinned to semver@7.8.1.

(fix): Generated snippets now use baseUrl instead of environment when no environments are defined in the API spec, matching the actual constructor parameter users should provide.

(feat): 新增以毫秒表示的 defaultTimeout 自定义配置选项，这对 JavaScript/TypeScript 更为地道（setTimeout、AbortSignal.timeout(ms)）。使用 "infinity" 可禁用超时。基于秒的 defaultTimeoutInSeconds 和 timeoutInSeconds 键现已弃用，但仍继续有效：其值会被转换为毫秒（× 1000）。优先级为 defaultTimeout > defaultTimeoutInSeconds > timeoutInSeconds。对于现有配置，生成的 SDK 输出保持不变。

(fix): 修复了一个回归问题：由可选映射值支撑的生成 Record 类型（例如可选的 additionalProperties）的值类型丢失了 | undefined。可选映射值现在正确生成 Record<string, T | undefined>，序列化为 record(string(), T.optional())，而 unknown/any 映射值仍保留去除多余 | undefined 的形式（Record<string, unknown>）。

(fix): 修复当运行时向文件上传参数传入 null 或 undefined 时出现的 TypeError: Cannot use 'in' operator to search for 'path' in undefined 崩溃。该错误现在会是一个清晰的 TypeError，描述期望的类型，而不再是晦涩的 in 运算符失败。

(feat): 新增 additionalBodyParameters 请求选项，将额外参数展开到端点的 JSON 请求体中。调用方提供的属性会覆盖端点请求体中匹配的键，与 Python、Swift 和 Ruby SDK 的行为一致。省略该选项时请求体保持不变，且绝不会为无请求体的请求伪造请求体。

(fix): 撤销对与请求体属性冲突的内联路径参数的自动重命名（在 3.77.1 中引入）。这类冲突现在在 CLI 层面被拒绝：fern check 会报错并要求用户消除名称歧义（例如通过 x-fern-parameter-name）。

(fix): 当内联路径参数（inlinePathParameters: true）与内联请求体属性共享属性名称时（例如 {idType} 路径参数和 idType 体字段），请求包装器现在通过为路径参数添加 PathParam 后缀（例如 idTypePathParam）来保留两个字段。之前两个值被合并为单个共享字段，导致无法为 URL 路径和请求体发送不同的值。

(feat): 为可恢复端点实现 SSE 流自动重连。当 SSE 流在连接中途断开且端点标记为 resumable: true 时，SDK 现在使用 Last-Event-ID header 自动重连，遵守服务器发送的 retry 指令（上限 30 秒）。重连遵守 reconnectionEnabled 和 maxReconnectionAttempts 选项。

(feat): 通过 generateReactQueryHooks 配置标志添加 React Query hooks 生成支持。 启用后，生成一个 react-query/ 目录，其中包含一个 tRPC 风格的命名空间对象，镜像 SDK 客户端层次结构（例如 seedApi.user.list.useQuery()）。每个查询端点公开 useQuery、useSuspenseQuery、getQueryKey、getQueryOptions（用于 SSR/RSC）和 invalidate。变更端点公开 useMutation。端点、服务和 SDK 级别的层次化缓存失效。按服务文件拆分并支持通配符子导出以实现 tree-shaking。所有导出通过 ./react-query package.json 子导出提供，对 react 和 @tanstack/react-query 有可选的 peer 依赖。

(fix): 当键是有效的 JavaScript 标识符时，在生成的动态代码片段中不再为对象键添加引号。 之前，映射和自由格式对象的键（例如 map<string, unknown> 的值）总是被加引号， 导致输出不一致，其中 metadata: { "releaseDate": ... } 与未加引号的类型属性并列。 非有效标识符的键仍然保持引号。

(fix): 修复非对称 webhook 签名验证以支持 payload-format 配置。 当 payload-format.components 包含 timestamp 时，时间戳头部值现在包含在 非对称签名验证的数据中，关闭了时间戳未经认证的重放保护漏洞。

(fix): 在生成的 Headers.ts 填充中使用 IterableIterator<T> 代替 HeadersIterator<T>。 HeadersIterator 在 TypeScript 5.6 中添加；之前的注解在 TS < 5.6 上导致编译失败。

(chore): 升级 oxc 工具链：oxlint 1.69.0 → 1.72.0，oxfmt 0.54.0 → 0.57.0， oxlint-tsgolint 0.23.0 → 0.24.0。

(feat): TimeoutError 现在扩展基础 API 错误类而非直接扩展 Error， 因此 instanceof ApiError 可以捕获超时错误。在基础 API 错误类上添加了 requestId getter， 从原始响应头中提取 x-request-id。