# watch

> Watch: one socket that says which of your objects changed, so what shows them reads them again instead of polling.

```python
for message in noclick.watch(objects=["deployment", "domain"]):
    if message.type == "change":
        refresh(message.object, message.object_id)
    elif message.type == "reset" or (message.type == "ready" and not message.resumed):
        refresh_all()
```

A change names an object (as its read's `object` says it: `deployment`, `channel`, `agent`, ...) and its
id, never its data: read it again. It is not the event log (`noclick.Event`, webhooks), which records what
happened, with data, for 30 days and delivers each event at least once. A change is a hint, delivered at most once:
re-read everything you show on `reset`, on a `ready` that didn't resume (the first one too, for anything you read
before it), and on a slow timer of your own if you must never be stale.

Your key follows the account's objects, its users' included; acting for one user (`user`), only that user's. A
server whose page should watch hands the page a token from `watch_token` (pass the page's `origin`); the page
opens it with the TypeScript SDK's `watch({ token })`.

`watch` needs the `websockets` package: `pip install "noclick[live]"`.

## watch

```typescript
async *function watch(options?: WatchOptions): AsyncGenerator<WatchMessage>
```

Follow your objects' changes until `signal` aborts or you stop reading. Reconnects by itself (a new token each
time), resuming after the last change it gave you; it throws only what can't be fixed by trying again: the token
call refused (a revoked key, a scope the key lacks, a deployment where watching isn't available) or the room
refusing two fresh tokens in a row (`WatchRefused`).

A change can be lost (a deploy, a dropped connection, a busy second), and nothing says so but these: read again
what you show on `reset`, on a `ready` that didn't resume, and on a slow timer of your own if it must never be stale.

Parameters:

- `options.objects` (`readonly (WatchedObject | string)[]`): Follow only these (default: every object the key may read).
- `options.user` (`UserOption`, default: the current user): Act for one of your users: follow only their objects.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.
- `options.token` (`() => Promise<{ url: string; token: string }>`): Where a token comes from, when not this client: your own server's endpoint that calls `watchToken`.
- `options.onStatus` (`(status: WatchStatus) => void`): Where the socket stands, as it moves.
- `options.signal` (`AbortSignal`): Stops watching (the generator returns).
- `options.WebSocket` (`typeof WebSocket`): A WebSocket class, where the runtime has none of its own (Node before 22).
- `options.origin` (`string`): The page's origin the socket will come from (a browser sends its own).

Returns: `WatchMessage` values: `ready` as each connection opens, `change`, `typing` and `reset`.

Types:

```typescript
/** Where the socket stands: `connecting`, `live`, `reconnecting` (it will on its own), or `stopped`. */
type WatchStatus = "connecting" | "live" | "reconnecting" | "stopped";

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** What `watch` follows: each an object as its read names it. */
type WatchedObject =
  | "domain" | "deployment" | "repo" | "mcp_server" | "live_session" | "phone_call" | "workflow"
  | "durable_object_class" | "skill" | "memory" | "machine" | "sandbox" | "agent_move" | "connection" | "plan_usage"
  | "agent_trigger" | "approval" | "browser" | "agent" | "coding_agent" | "channel" | "workspace"
  | "workspace_resource" | "channel_sections" | "space_question";
```

## watchToken

```typescript
function watchToken(options?: WatchTokenOptions): Promise<WatchToken>
```

A single-use token for the watch socket (`POST /v1/watch/tokens`), for a page to open with `watch({ token })`.

Parameters:

- `options.objects` (`readonly (WatchedObject | string)[]`): Follow only these (default: every object the key may read).
- `options.origin` (`string`): The page's origin the socket will come from (a browser sends its own).
- `options.user` (`UserOption`, default: the current user): Act for one of your users: follow only their objects.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: A `WatchToken`: the socket's `url`, the `token`, when it expires and when the connection it opens ends.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** What `watch` follows: each an object as its read names it. */
type WatchedObject =
  | "domain" | "deployment" | "repo" | "mcp_server" | "live_session" | "phone_call" | "workflow"
  | "durable_object_class" | "skill" | "memory" | "machine" | "sandbox" | "agent_move" | "connection" | "plan_usage"
  | "agent_trigger" | "approval" | "browser" | "agent" | "coding_agent" | "channel" | "workspace"
  | "workspace_resource" | "channel_sections" | "space_question";
```

## WatchReady

```typescript
interface WatchReady
```

The socket is open: `resumed` when it carried on from the last change you got, so nothing was missed.

| Attribute | Type | Description |
| --- | --- | --- |
| `resumed` | `boolean` |  |
| `type` | `"ready"` |  |

## WatchChange

```typescript
interface WatchChange
```

An object changed: read it again.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` | This change's place in the stream (what a reconnect resumes after). |
| `at` | `Date | null` |  |
| `object` | `WatchedObject | string` |  |
| `objectId` | `string | null` | Its id; null for a `coding_agent` change that may be any of them. |
| `status` | `string | null` | Its status as its read gave it then (advisory: the read is the truth); null once it's gone. |
| `parent` | `{ object: string; id: string } | null` | What it belongs to: a deployment's project, a call's phone number, a trigger's agent, ... |
| `change` | `string | null` | What moved: an agent's `turn`, `step`, `definition`, ...; a channel's `message`, `reaction`, `thread`, ... |
| `version` | `number | null` | A workflow's graph version now. |
| `workspaceId` | `string | null` |  |
| `messageId` | `string | null` |  |
| `threadId` | `string | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |
| `type` | `"change"` |  |

Types:

```typescript
/** What `watch` follows: each an object as its read names it. */
type WatchedObject =
  | "domain" | "deployment" | "repo" | "mcp_server" | "live_session" | "phone_call" | "workflow"
  | "durable_object_class" | "skill" | "memory" | "machine" | "sandbox" | "agent_move" | "connection" | "plan_usage"
  | "agent_trigger" | "approval" | "browser" | "agent" | "coding_agent" | "channel" | "workspace"
  | "workspace_resource" | "channel_sections" | "space_question";

type JsonObject = { [key: string]: unknown };
```

## WatchTyping

```typescript
interface WatchTyping
```

Someone started or stopped typing in a channel you read (never sent to the one typing).

| Attribute | Type | Description |
| --- | --- | --- |
| `channelId` | `string` |  |
| `workspaceId` | `string | null` |  |
| `userId` | `string` | Who: a user's id, or `account` for the account's owner. |
| `typing` | `boolean` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |
| `type` | `"typing"` |  |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## WatchReset

```typescript
interface WatchReset
```

Too much changed to say each: read again everything you show.

| Attribute | Type | Description |
| --- | --- | --- |
| `type` | `"reset"` |  |

## WatchToken

```typescript
interface WatchToken
```

A single-use token for the socket at `url`, good until `expiresAt`.

| Attribute | Type | Description |
| --- | --- | --- |
| `url` | `string` |  |
| `token` | `string` |  |
| `expiresAt` | `Date | null` |  |
| `connectionEndsAt` | `Date | null` | When the connection it opens ends (watch then reconnects with a new token). |
| `objects` | `string[]` |  |
| `userId` | `string | null` | The user whose objects it follows; null for the account's. |
| `origin` | `string | null` | The page's origin the socket must come from, when one was given. |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## WatchRefused

```typescript
class WatchRefused extends NoClickError
```

The error that ends a watch: the room refused it again right after a fresh token (access ended).

Error type `watch_refused`.

### WatchRefused.retryAfter

```typescript
retryAfter: number | undefined
```

Seconds the server asked us to wait (from `Retry-After`), when it did.

### WatchRefused.errorType

```typescript
static errorType: string
```

## WatchMessage

```typescript
const WatchMessage: any
```

What `watch` yields; a message type this version doesn't know is skipped, so the stream can grow.
