> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paddock.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser client

> @paddock/client: turn a session ID and a session token into live session state in any frontend.

`@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`](https://docs.paddock.build/sdks/react), which is built on it.

It runs in browsers with streaming `fetch` (ES2022) and has no runtime dependencies.

## Install

```bash theme={null}
npm install @paddock/client
```

> [!NOTE]
>
> `@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](https://docs.paddock.build/guides/streaming.md)), then:

```ts theme={null}
import { PaddockClient, type SessionState } from "@paddock/client";

const client = new PaddockClient({ token });
const handle = client.session(sessionId);

const unsubscribe = handle.subscribe((state: SessionState) => {
  console.log(state.status, state.messages.length, state.connection);
});

const event = await handle.send("Summarize what changed since yesterday.");
console.log("stored as seq", event.seq);

await handle.stop();
unsubscribe();
```

| `PaddockClientOptions` | Default |
| - | - |
| `token` | Required: the session token, sent only in the `Authorization` header |
| `baseUrl` | `https://api.paddock.build/v1` |
| `maxRetries` | 2 retries of idempotent requests |
| `timeoutMs` | 60 seconds per request |
| `fetch` | A `fetch` to use instead of the global one |

`client.session(id)` returns one handle per session ID. A handle:

| Member | Meaning |
| - | - |
| `state` | The current `SessionState`; replaced on every change, never mutated, so a reference comparison tells whether anything changed |
| `subscribe(listener)` | Calls `listener` with every new state; returns the function that unsubscribes. The first subscriber loads the session and opens the stream; the last one to leave closes it, keeping the state, and a new subscriber resumes where it left off |
| `send(text)` | Stores a user message; resolves with its event, already folded into `messages` |
| `stop()` | Stops the running turn; resolves with the stored `stop.requested` event |
| `close()` | Closes the stream; the state stays |
| `events.list(options)`, `turns.list()`, `turns.get(turnId)`, `get()`, `stream(options)`, `createToken({ ttl })` | The session operations of the server SDK, on this one session |

## SessionState

| Field | Type | Meaning |
| - | - | - |
| `messages` | `ClientMessage[]` | Stored messages in `seq` order, then the messages being generated |
| `status` | `SessionStatus` | `idle`, `running`, `retrying`, `failed`, or `blocked` |
| `turn` | `Turn \| null` | The running turn |
| `error` | `TurnError \| null` | The session's last turn error |
| `processedSeq` | `number` | User messages above it are waiting |
| `heldSeq` | `number` | Waiting messages at or below it are held |
| `session` | `Session \| null` | The latest session snapshot |
| `connection` | `"connecting" \| "open" \| "reconnecting" \| "closed"` | The stream's state |
| `connectionError` | `Error \| null` | The error that closed the connection, if one did |
| `events` | `Event[]` | Every stored event received, once each, in `seq` order |
| `harnessStatus` | `HarnessStatus \| null` | The latest [harness status](https://docs.paddock.build/guides/harness-status.md) |

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](https://docs.paddock.build/platform/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.