Changelog

(fix): reference.md is now generated for every output mode, matching the Go and Python generators. It was previously skipped unless the CLI passed a snippet path (local-file-system output without snippets: path: in generators.yml). README.md is unchanged and still requires snippets. Source-only output (outputSourceFiles, the default for local-file-system) now also includes the root README.md, reference.md and CONTRIBUTING.md when they were generated.

(feat): Support inferred bearer auth with type: refresh-token. The SDK always sends grant_type: "refresh_token" to the get-token endpoint, and grantType is no longer exposed as a client auth option. Users pass only the refresh token (and any other non-literal token endpoint parameters).

(feat): With type: refresh-token, inferred auth only exposes and sends the token endpoint parameters used by the OAuth refresh token grant (refresh_token, scope, client_id, client_secret) plus any required ones. Optional parameters of other grants on a shared token endpoint, such as code, code_verifier and redirect_uri, are no longer auth options.

(fix): Paginated endpoints no longer modify the request object you pass in. Calling getNextPage() used to write the next cursor or offset into your original request (including nested fields such as options.offset), so reusing that object started from the wrong position. The pager now sends an updated copy and leaves your request unchanged.

(fix): SSE unions discriminated by the event: line (x-fern-discriminator-context: protocol) now parse both variant styles: envelope variants ({event, data: Payload}) are built from the data: JSON, and payload variants (the data: JSON itself) get the event: value injected as the discriminant. The event name no longer has to be repeated inside the data: JSON.

(fix): Malformed JSON no longer loses HTTP details. An error response labelled JSON whose body isn’t valid JSON (for example a 502 HTML page from a proxy) now throws the SDK’s API error with the status code, raw body and response headers, instead of a generic JSON parse error. Error responses with no Content-Type now carry the raw text as the error body. A successful response with a JSON Content-Type (application/json, text/json or *+json) and malformed JSON now throws the SDK’s API error too, instead of resolving the internal { ok: false, error: ... } record as if it were the endpoint’s data. Successful non-JSON bodies, such as 200 OK as text/plain on a void endpoint, still resolve as before.

(fix): timeoutInSeconds now also covers reading the response body. Before, the timer stopped as soon as headers arrived, so a response whose JSON body was slow to arrive could take far longer than the timeout. Timeouts are also reported as the SDK’s timeout error on every Node version (before, Node 20+ surfaced a generic "timeout" error and Node 18 a TypeError: invalid_argument), and the timeout timer is cleared on every exit, including failed requests. An error status (4xx/5xx) whose body is slower than the timeout now also returns the timeout error. Streaming, SSE and binary responses, and the passthrough client.fetch() (which returns the raw response), still stop the timer when headers arrive. When client.fetch() times out it now rejects like fetch does, with an Error whose name is "TimeoutError"; before, it rejected with the bare string "timeout".

(fix): guardProcessEnvAccess: true now also guards the environment-variable fallback of global headers (headers declared with env, e.g. requestOptions?.version ?? this._options?.version ?? process.env?.["API_VERSION"]). Before, only auth and base-URL reads were guarded, so omitting an optional header option still threw ReferenceError: process is not defined in browsers, Deno and Cloudflare Workers. Output is unchanged when the option is off.

(feat): XML (TwiML) builders can now carry XML comments. comment(text) adds <!--text--> inside the element at its position in the ordered content (interleaved with addText segments and child elements), while commentBefore(text) / commentAfter(text) render a comment immediately before or after the element itself (as a sibling in its parent, or around the root element after the XML declaration). Comments in parsed documents are preserved by fromXml and round-trip through toXml; the new core.xml.XmlComment node exposes the same for untyped XmlElement content.

(feat): With enableForwardCompatibleEnums: true, enum-typed attributes and text on XML (TwiML) types are open on the wire: fromXml keeps a value the enum does not declare (e.g. a voice added after the SDK was generated) instead of throwing, and it round-trips through toXml. Without the flag the parse error now lists at most 10 of the allowed values instead of all of them.

(fix): Offset pagers no longer skip a page when a failed getNextPage() is retried. The pager now advances its saved offset only after the next page loads successfully, so a retry re-requests the same offset instead of moving past it.

(feat): Add opt-in userAgentOnly config. When enabled, generated clients send the User-Agent header (including the structured form from includePlatformHeaders) but omit the X-Fern-Language, X-Fern-SDK-Name, X-Fern-SDK-Version, X-Fern-Runtime, and X-Fern-Runtime-Version headers. Disabled by default, so existing generated output is unchanged. omitFernHeaders still takes precedence and drops the User-Agent too.

(feat): The generated WebhooksHelper HMAC verifier now accepts a per-call algorithm override via an optional algorithm parameter on verifySignature, one of sha1, sha256, sha384 or sha512. When omitted, the algorithm configured in webhook-signature is used, so existing callers are unchanged. This lets one endpoint verify both legacy HMAC-SHA1 (auth-token) and HMAC-SHA256 (shared-key) signed webhooks. The verifier also logs a warning distinguishing an early failure (missing signature header) from a failed verification (signature mismatch); it still returns false and never throws.

(feat): XML (TwiML) types keep text segments, typed children and undeclared XmlElement children in a single ordered content sequence, so toXml() preserves the exact insertion/document order across child types (e.g. <Say>a</Say><Custom/><Say>b</Say>) and fromXml() reconstructs it. Builders gain addText(text) to interleave text with child elements (Say.builder({ message: "Hi " }).addBreak(...).addText(" world")), and addChild(XmlElement) now appends in place rather than after all typed children.

(fix): XML-encoded (TwiML) types now include the <?xml version="1.0" encoding="UTF-8"?> declaration by default when serialized to XML; pass the declaration flag as false to omit it. Nested child elements and raw XmlElements are still written without it.

(feat): SDK variables that declare an environment variable fallback (env in api.yml or x-fern-env on x-fern-sdk-variables) are now optional client options. normalizeClientOptions resolves them from the option first and then from the environment variable, and throws a clear error at client construction when neither is set, instead of interpolating undefined into request paths.

(fix): Fix waitForOpen() on generated WebSocket clients hanging forever when the socket closes without opening. It now rejects when the socket is already closed, when close() is called or the abortSignal fires (including before the underlying WebSocket is created, or when the signal is already aborted), and when the connection closes with no reconnect pending. readyState now reports CLOSED after an abort or close() even if the underlying WebSocket was never created.

(fix): Restore WebSocket retries after connection errors and timeouts, and allow manual reconnect after retry exhaustion. Internal socket cleanup now emits close notifications without consulting shouldReconnect, which continues to control server-initiated closes. Error retries and manual reconnects respect explicit close(), abort signals, and retry limits.

(fix): Redact the API’s own credential headers in debug request logs. The generated SENSITIVE_HEADERS set in core/fetcher/Fetcher.ts now also includes every header an auth scheme writes to (custom header auth names such as PLAID-SECRET, custom OAuth token headers, and inferred-auth headers), plus global, service, and endpoint headers whose names identify them as credentials (e.g. PLAID-CLIENT-ID). Previously only a static list of conventional names (Authorization, X-API-Key, …) was redacted, so custom-named auth headers, including request-level overrides, were logged in plaintext when debug logging was enabled.

(chore): Bump bundled @fern-api/generator-cli to 0.10.3. When the hosted auto-version analysis of the full SDK diff fails, generator-cli now retries chunk-by-chunk instead of silently applying a PATCH bump; any remaining unavailable or incomplete analysis adds a “Version bump not verified” notice to the SDK PR body and disables automerge.

(fix): Fix invalid TypeScript in generated XML (TwiML) classes and builders when a property key is not a valid identifier (e.g. interpret-as or default). The generator now emits bracket access (this["interpret-as"]) and camelCased locals (interpretAs) instead of this.interpret-as.