Changelog

(fix): Fix dynamic snippets emitting a dangling argument delimiter (e.g. client.refunds.refund("id", )) when an example omits the request body.

(fix): Send the caller’s request when fetching the first page of a next_uri/next_path paginated endpoint. Previously the first page was requested through the same headers-only helper used for subsequent pages, so query parameters, request bodies and requestOptions.queryParams were silently dropped (and the unused request parameter was emitted as _request). Subsequent pages keep using the next URL as-is.

(fix): The appInfo User-Agent helper emitted when allowUserAgentAppInfo is enabled no longer uses a control-character regex range, so generated SDKs lint cleanly under rules such as Biome’s noControlCharactersInRegex without a suppression comment. Escaping behavior is unchanged.

(feat): Add a requireBaseUrl config option. When enabled, baseUrl is a required client option and environment is optional, for APIs whose users always pass an explicit server URL. Generated snippets, README, and wire tests use baseUrl accordingly. The option is ignored for APIs with multiple base URLs, whose clients resolve each URL from environment. Defaults to false, so existing SDKs are unchanged.

(feat): Add opt-in allowUserAgentAppInfo config. When enabled, generated clients accept an appInfo: { name, version?, comment? } option whose product token is appended to the User-Agent header ({sdk}/{version} ... {product}/{product-version} ({comment})), following RFC 9110. Disabled by default, so existing generated output is unchanged, and it composes with includePlatformHeaders, the user-agent template config, and the default {package}/{version} value. Caller-supplied values are token-encoded.

(fix): Respect the user-agent config template when includePlatformHeaders is enabled. The structured User-Agent previously always used the npm package name and version, ignoring the configured template.

(fix): Fixed the generated wire tests for endpoints that use offset pagination. The tests asserted page.hasNextPage() was true for every example, but the generated client reports no next page when the response returns fewer items than the requested page size (the pagination step), or when the response’s has-next-page property is false. The wire test now evaluates the same condition against the mocked response, and only asserts hasNextPage()/getNextPage() when a next page is actually expected.

(feat): Add an opt-in optional-auth config flag. When enabled, client auth parameters are made optional even when the API spec mandates auth on all endpoints (isAuthMandatory=true), so the client can be constructed without credentials. Requests are then sent unauthenticated when no credentials are supplied, instead of throwing from the auth provider. Useful for hand-maintained wrapper clients that authenticate via external means (e.g. cloud provider credentials). Defaults to false, so existing behavior is unchanged.

(feat): Generated error classes now redeclare the body property with the error’s typed body (e.g. public declare readonly body: MyErrorBody;) instead of inheriting body?: unknown from the base API error class. This makes err.body.<field> type-check in catch blocks without casting when the error has a declared body schema.

(fix): Global headers declared with an env now fall back to that environment variable at runtime. The resolution order for a global header is the explicit option, then the environment variable, then the client default.

(fix): Scope the passthrough client.fetch() auth headers to the configured base URL. Auth headers are now only attached when the resolved request URL has the same origin as the configured base URL (or environment), so passing an absolute cross-origin URL into the passthrough fetch escape hatch no longer leaks the SDK’s credentials to an unrelated host. Relative paths and same-origin absolute URLs are unaffected. Passthrough debug logs now redact credentials in the request URL, matching the main fetcher.

(feat): Add support for webhook body-hash binding in the generated verifySignature helper. When a webhook’s signature declares a body-hash binding, the helper now hashes the raw request body and compares it to the hash transmitted separately as a query parameter on the notification URL (e.g. Twilio’s bodySHA256) before verifying the HMAC signature. Both checks must pass. The body-hash algorithm and encoding are independent of the outer HMAC’s.

(fix): Fix server URL variable interpolation to render the selected environment’s URL template instead of always using the first environment’s template. When a client is constructed with both an environment and server URL variable values (e.g. region), the base URL is now built from the selected environment’s template(s); for multi-host environments every host’s template is formatted. An explicitly provided baseUrl or custom environment value is no longer overridden.

(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.