Skip to main content
@paddock/client runs in the browser with a session token. It loads a session’s events, follows its live stream, reconnects on its own, and folds everything into one SessionState, so your frontend writes no streaming, reconnection, or state code. It is framework-independent; with React, use @paddock/react, which is built on it. It runs in browsers with streaming fetch (ES2022) and has no runtime dependencies.

Install

@paddock/client is not on npm yet. Until it is published, build it from the sdk/js workspace of the paddock repository.

Use a session

Get a session ID and a session token from your backend (see Streaming to the browser), then:
client.session(id) returns one handle per session ID. A handle:

SessionState

A ClientMessage is a message with the position of its event: seq (null while it is streaming), turnId, and createdAt. The timeline keeps one entry per message ID: a streaming entry’s text is replaced by each newer one, and the finished assistant message takes its place.

How it loads and reconnects

  1. Read the session, then page through its events, 200 at a time, from the start.
  2. Follow the live stream after the highest seq loaded.
  3. On a dropped connection, a server error, or 45 seconds without a byte, reconnect with capped backoff and resume after the highest seq the load or the stream delivered, without resetting the state. An event that send or stop added early does not count, so an earlier event another writer stored is still fetched; an event already held is ignored.
  4. On an error event or any other failure to connect, such as an expired token, stop with connection: "closed" and connectionError set.
The client does not refresh tokens: when one expires, create a new PaddockClient with a new token from your backend.

Errors

Requests throw PaddockError for a non-2xx answer, with status, code, message, details, and requestId, and PaddockConnectionError or PaddockTimeoutError when no answer came. send and stop are never retried automatically. See Errors.