Skip to main content

Server-Sent Events (SSE) Streaming in TypeScript SDKs

· 3 min read

Generated TypeScript SDKs now support streaming API responses over Server-Sent Events (SSE). When an operation streams its response instead of returning a single buffered body, the SDK exposes it as a typed, async-iterable stream that you consume with a familiar for await...of loop.

What's New?​

Previously, an operation whose response was streamed could only be consumed as an unstructured, buffered body, leaving developers to read the raw stream, split it into events, and decode each payload themselves. Generated TypeScript SDKs now do all of this for you.

Any operation whose success response declares a text/event-stream media type is automatically detected as a streaming endpoint. No special specification extension is required. The schema associated with the media type describes each event's payload, and the SDK decodes every incoming frame into that type.

Such an endpoint now returns a Promise<ApiResponse<SseStream<T>>>, where T is the decoded event type. The SseStream<T> is a single-use, asynchronously-iterable stream:

const response = await chatController.createChatCompletion(body);

// Iterate decoded events of type `T` as they arrive.
for await (const event of response.result) {
  console.log(event);
}

console.log(response.statusCode);
console.log(response.headers);

Event metadata​

Iterating the stream directly yields decoded payloads. To also read the SSE frame metadata (the id, event, and retry fields), iterate via withMetadata(), which yields full SseEvent<T> objects:

for await (const event of response.result.withMetadata()) {
  console.log(event.data, event.id, event.event, event.retry);
}

Configurable read timeout​

A new streamReadTimeout client configuration option (default 60000 ms) bounds the idle window allowed between two consecutive frames, so a stalled server can't hang the stream indefinitely. Exceeding it raises an SseTimeoutError.

const client = new Client({ streamReadTimeout: 30000 });

SSE-specific error handling​

Alongside the usual ApiError, streaming endpoints can surface two SSE-specific errors while the stream is consumed:

  • SseTimeoutError: the server stalled between frames longer than streamReadTimeout (exposes idleTimeoutMs).
  • SseDecodeError: a frame's payload couldn't be decoded into the expected type (exposes rawFrame and cause).

Both extend the SseError base type. Breaking out of the loop, or calling result.close(), aborts the underlying connection so it's never left open.

Why This Matters​

  • Typed, incremental responses. Consume streamed responses as decoded, typed events instead of hand-parsing a raw byte stream.
  • A familiar interface. The stream is a standard async-iterable, consumed with an ordinary for await...of loop, with no new programming model to learn.
  • Zero configuration. Streaming is applied automatically to any operation with a text/event-stream response.
  • Safe by default. A configurable read timeout guards against stalled connections, and the connection is aborted as soon as iteration stops.

For more details, see the Server-Sent Events (SSE) Streaming feature documentation.