# 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]"`.

## noclick.watch

```python
noclick.watch(
    *, objects=None, user=..., client=None, token=None, on_status=None
) -> Iterator[WatchMessage]
```

Follow your objects' changes until you stop reading. Reconnects by itself (a new token each time), resuming
after the last change it gave you; raises only what trying again can't fix: the token call refused (a revoked
key, a scope the key lacks, a deployment where watching isn't available) or `WatchRefused`, the room refusing
two fresh tokens in a row. `token`: where tokens come from instead of this client, a function returning
`(url, token)`. `on_status` hears `connecting`, `live`, `reconnecting` and `stopped`.

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:

- `objects` (`Sequence[str] | None`, default `None`)
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.
- `token` (`TokenSource | None`, default `None`)
- `on_status` (`Callable[[str], None] | None`, default `None`)

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

Usage:

Follow your deployments as they move:

```python
for message in noclick.watch(objects=["deployment"]):
    if message.type == "change":
        print(message.object, message.object_id, message.status)
```

In async code, relay it to your own UI:

```python
async for message in noclick.watch.aio(objects=["channel"]):
    if message.type == "change":
        await websocket.send_json(message.raw)
```

## noclick.watch_token

```python
noclick.watch_token(*, objects=None, origin=None, user=..., client=None) -> WatchToken
```

A single-use token for the watch socket (`POST /v1/watch/tokens`), to open within a minute: hand `url` and
`token` to the page that connects, with its `origin` (the socket must then come from that page).

Parameters:

- `objects` (`Sequence[str] | None`, default `None`)
- `origin` (`str | None`, default `None`)
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

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

Usage:

```python
token = noclick.watch_token(user="user_42", origin="https://app.example.com")
return {"url": token.url, "token": token.token}
```

## noclick.WatchReady

```python
class WatchReady
```

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

| Attribute | Type | Description |
| --- | --- | --- |
| `resumed` | `bool` |  |
| `type` | `str` |  |

## noclick.WatchChange

```python
class WatchChange
```

An object changed: read it again.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `str` | This change's place in the stream (what a reconnect resumes after). |
| `at` | `Any` |  |
| `object` | `str` |  |
| `object_id` | `str | None` | Its id; None for a `coding_agent` change that may be any of them. |
| `status` | `str | None` | Its status as its read gave it then (advisory: the read is the truth); None once it's gone. |
| `parent` | `dict[str, str] | None` | What it belongs to (`{"object": "project", "id": ...}` for a deployment), else None. |
| `change` | `str | None` | What moved: an agent's `turn`, `step`, `definition`, ...; a channel's `message`, `reaction`, ... |
| `version` | `int | None` | A workflow's graph version now. |
| `workspace_id` | `str | None` |  |
| `message_id` | `str | None` |  |
| `thread_id` | `str | None` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |
| `type` | `str` |  |

## noclick.WatchTyping

```python
class WatchTyping
```

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

| Attribute | Type | Description |
| --- | --- | --- |
| `channel_id` | `str` |  |
| `workspace_id` | `str | None` |  |
| `user_id` | `str` | Who: a user's id, or `account` for the account's owner. |
| `typing` | `bool` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |
| `type` | `str` |  |

## noclick.WatchReset

```python
class WatchReset
```

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

| Attribute | Type | Description |
| --- | --- | --- |
| `type` | `str` |  |

## noclick.WatchToken

```python
class WatchToken
```

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

| Attribute | Type | Description |
| --- | --- | --- |
| `url` | `str` |  |
| `token` | `str` |  |
| `expires_at` | `Any` |  |
| `connection_ends_at` | `Any` | When the connection it opens ends (`watch` then reconnects with a new token). |
| `objects` | `list[str]` |  |
| `user_id` | `str | None` | The user whose objects it follows; None for the account's. |
| `origin` | `str | None` | The page's origin the socket must come from, when one was given. |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

## noclick.WatchRefused

```python
class WatchRefused(Error)
```

The room refused two fresh tokens in a row: access ended (a revoked key, a deleted user).

Error type `watch_refused`.

## noclick.WatchMessage

```python
noclick.WatchMessage = Union[WatchReady, WatchChange, WatchTyping, WatchReset]
```

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