Changelog

4.0.3

(fix): Fix WebSocket handleIncomingMessage() using Fern-internal message IDs (e.g. AgentV1Welcome, ListenV1Results) instead of the wire discriminant values from the spec (e.g. Welcome, Results). This caused all incoming message handlers to never fire, falling through to the unknown type handler.

The generator now extracts wire discriminant values from each message body’s type property — resolving literal values (e.g. literal<"Welcome">) and enum values (e.g. enum[Flushed, Cleared]) — and dispatches via a switch statement on those values. This aligns with the approach used by the Python generator.

(fix): WebSocket handler registration methods and field names now use wire discriminant values instead of Fern-internal prefixed names. For example, onAgentV1Welcome(handler) is now onWelcome(handler), and onAgentV1PromptUpdated(handler) is now onPromptUpdated(handler). Methods that were already backed by a custom x-fern-sdk-method-name (e.g. onFunctionCallResponse) are unchanged.

(chore): Improve generated WebSocket client code quality: use a string literal for static URL paths instead of StringBuilder, remove dead if/else branches in async sendMessage(), consolidate redundant catch blocks in message dispatch, and correct Javadoc articles (“a” vs “an”) for type names starting with vowels.

4.0.2

(fix): Fix binary file upload for wrapped request endpoints (endpoints with query parameters alongside an application/octet-stream body). The body type is now byte[] instead of String, and the request is sent via InputStreamRequestBody instead of String.valueOf().getBytes(UTF_8), which was corrupting binary data.

4.0.1

(fix): Fix generated snippets producing OptionalNullable.of(...) for fields that are only optional (not nullable) when collapse-optional-nullable is enabled.

4.0.0

(feat): Breaking change for WebSocket users only. REST-only SDKs are unaffected — no code changes required.

Overhaul generated WebSocket clients. The generated API is restructured around a factory → configure → connect lifecycle that separates client creation from connection parameters:

1
// Create client from the service tree — no connection params yet
2
V1WebSocketClient ws = client.listen().v1WebSocket();
3
4
// Register handlers before connecting
5
ws.onListenV1Results(results ->
6
    System.out.println(results.getChannel().getAlternatives()));
7
ws.onError(error -> error.printStackTrace());
8
9
// Connect with channel-specific options (required params enforced at compile time)
10
ws.connect(V1ConnectOptions.builder()
11
    .model(ListenV1Model.NOVA3)
12
    .encoding(ListenV1Encoding.LINEAR16)
13
    .sampleRate(16000)
14
    .build());
15
16
// Stream audio and disconnect
17
ws.sendMedia(audioBytes);
18
ws.disconnect();

Query parameters move from constructor to connect(). The factory method (client.listen().v1WebSocket()) now takes no channel-specific arguments. All query parameters are passed via a builder-pattern ConnectOptions object to connect(), matching the Python SDK’s design. Required parameters use staged builders so missing fields are caught at compile time.

AutoCloseable — clients implement AutoCloseable for try-with-resources, calling disconnect() automatically on scope exit.

Configurable reconnection — reconnectOptions(ReconnectOptions) lets callers tune max retries, backoff delay, and queue size before calling connect().

Generic onMessage(Consumer<String>) handler — fires for every incoming text frame with the raw JSON string, before type-specific dispatch. Useful for logging or custom routing.

Binary WebSocket support — channels that define binary messages now generate typed send and receive methods. Binary frames queue when disconnected and flush on reconnect, matching text behavior.

Shared core types — DisconnectReason and WebSocketReadyState are generated once in the core package instead of duplicated as inner classes inside every WebSocket client.

Thread safety — all handler fields are now volatile so handlers registered from the main thread are visible to OkHttp callback threads. Previously only readyState was volatile.

x-fern-sdk-method-name support — WebSocket send/receive methods use the custom method name from the Fern config when set.

Also removes the deprecated hasWebSocketInstance() method and fires onError for unrecognized incoming message types instead of silently dropping them.

(fix): Fix WebSocket connect() crashing with NullPointerException when the environment URL uses wss:// or ws:// schemes. OkHttp’s HttpUrl.parse() only accepts http/https, so the client now rewrites the scheme before parsing and null-checks the result.

(fix): Fix WebSocket clients always calling environment().getUrl(), which does not exist on multi-URL environment classes. The generator now resolves the correct per-URL getter (e.g. environment().getAgentURL()) based on the channel’s baseUrl field in the IR, matching the pattern already used by REST endpoints.

(fix): Fix WebSocket clients not sending authentication headers when the channel’s auth field is false in the IR. Previously, headers were only applied when websocketChannel.getAuth() was true. connect() now unconditionally applies clientOptions.headers() to the upgrade request, ensuring bearer tokens, API keys, and custom headers are always sent regardless of the channel’s auth configuration.

(fix): Fix WebSocket message serialization wrapping every outgoing message in a {"type": "...", "body": {...}} envelope and expecting the same format for incoming messages. Messages are now serialized directly as flat JSON (the discriminated union already contains the type field), and incoming messages are deserialized from the root JSON object instead of extracting a nested body sub-field.

(fix): Fix binary file upload endpoints (application/octet-stream) serializing the request body through Jackson, which corrupted binary data with JSON string escaping. These endpoints now send raw bytes via InputStreamRequestBody.

3.44.6

(fix): Fix duplicate discriminator keys in union serialization. When a discriminated union variant uses @JsonUnwrapped and the wrapped object already contains the discriminant property (e.g., “type”), the serialized JSON previously contained the key twice. The generator now adds a field-level @JsonIgnoreProperties annotation with allowSetters = true on @JsonUnwrapped fields to suppress the duplicate during serialization while preserving deserialization.

3.44.5

(fix): Fix floating-point serialization of integer-valued doubles. Values like 24000.0 are now serialized as 24000 instead of 24000.0 in JSON output. This prevents API rejections for fields defined as type: number when the value happens to be a whole number. Non-integer double values like 3.14 continue to serialize normally.

3.44.4

(fix): Fix dynamic snippet compilation errors for objects with required fields in staged builders. When an endpoint example omits a required property, the snippet generator now fills in a type-appropriate default value instead of producing an invalid .builder().build() call that skips mandatory builder stages.

(fix): Fix dynamic snippet builder ordering when default values are added for missing required properties. Properties are now re-sorted to match schema declaration order after defaults are injected, ensuring Java staged builder method calls follow the correct sequence.

(fix): Fix undiscriminated union variant matching selecting incorrect variants when example data doesn’t match. Required properties and their nested types are now validated during matching, so variants with mismatched enum values or missing required fields are correctly rejected.

(fix): Fix hardcoded com.seed.api.core.OptionalNullable import in generated README OptionalNullable documentation. The import now uses the correct dynamic package name for the SDK being generated.

(fix): Fix incorrect raw response type name in generated README. The “Access Raw Response Data” section now uses the correct {BaseNamePrefix}HttpResponse class name (e.g., Auth0ApiHttpResponse) instead of the endpoint-derived name (e.g., CreateHttpResponse).

(fix): Fix missing environment URL variables in generated README Usage example. Builder parameters like tenantDomain from OpenAPI server URL templates are now included in the Usage snippet alongside auth parameters.

3.44.3

(fix): Fix auth header prefix missing trailing space.

3.44.2

(fix): Generate named Java wrapper classes for unknown type aliases. Previously, when an API schema had no type and no properties (representing an “any” type), the generator dropped the named type definition and inlined Object wherever it was referenced. Unknown type aliases now generate a proper wrapper class (e.g. DocumentedUnknownType) based on java.lang.Object, consistent with how other alias types are handled.

3.44.1

(fix): Fix enable-forward-compatible-enums config flag being ignored in download files mode. The flag was missing from JavaSdkDownloadFilesCustomConfig, so enable-forward-compatible-enums: false in generators.yml had no effect when using --local generation.

3.43.0

(fix): Fix WebSocket client compilation error when a server message type produces the same method name as a lifecycle handler. For example, a message type error generated onError(Consumer<Error>) which clashed with the lifecycle onError(Consumer<Exception>) due to Java generics type erasure. Colliding message handler methods are now suffixed with Message (e.g. onErrorMessage).

3.44.0

(feat): Add omit-fern-headers configuration option. When enabled, Fern platform headers (X-Fern-Language, X-Fern-SDK-Name, X-Fern-SDK-Version, User-Agent) are omitted from generated SDK requests.

3.42.9

(chore): Update bundled npm tar package from 7.5.10 to 7.5.11.

3.42.8

(fix): Add equals(), hashCode(), and toString() methods to interface-based discriminated union wrapper classes. Previously, the outer wrapper class fell back to Object.equals() (reference identity), breaking equality for any type that transitively contained the union. The methods now delegate to the inner Value field.

3.42.7

(chore): Add concurrency configuration to generated CI workflow with cancel-in-progress: false to prevent stacked runs from being cancelled when a newer run starts.

3.42.6

(fix): Fix dynamic snippets to include global headers in generated code examples. Previously, required global headers (e.g., X-Organization-ID) configured via x-fern-global-headers were missing from dynamic snippet output. Also fixes header value lookup to use wire values instead of a non-existent property.

3.42.5

(fix): Fix custom-interceptors support for OAuth staged builders. When custom-interceptors: true is enabled, the _Builder inner class now generates an interceptors field, addInterceptor(Interceptor) method, and forwards interceptors to _TokenAuth and _CredentialsAuth via token() and credentials() methods. Previously, only the root builder received interceptor support, causing OAuth staged builders to lose interceptor configuration.

3.42.4

(chore): Parallelize endpoint snippet generation in populateSnippetsCache(). All endpoints are now processed concurrently via Promise.all instead of sequentially, reducing snippet generation time for large APIs.