@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
- Read the session, then page through its events, 200 at a time, from the start.
- Follow the live stream after the highest
seqloaded. - On a dropped connection, a server error, or 45 seconds without a byte, reconnect with capped backoff and resume after the highest
seqthe load or the stream delivered, without resetting the state. An event thatsendorstopadded early does not count, so an earlier event another writer stored is still fetched; an event already held is ignored. - On an
errorevent or any other failure to connect, such as an expired token, stop withconnection: "closed"andconnectionErrorset.
PaddockClient with a new token from your backend.
Errors
Requests throwPaddockError 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.