watch

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

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(
    *, 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
objectsSequence[str] | Nonedefault None
userAny

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
clientClient | None

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

(default None)
tokenTokenSource | Nonedefault None
on_statusCallable[[str], None] | Nonedefault None
Returns
Iterator[WatchMessage]

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

Usage

Follow your deployments as they move:

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:

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

watch_token

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
objectsSequence[str] | Nonedefault None
originstr | Nonedefault None
userAny

Who the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).

(defaults to the current user)
clientClient | None

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

(default None)
Returns
WatchToken

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

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

WatchReady

class WatchReady

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

Attributes
resumedbool
typestr

WatchChange

class WatchChange

An object changed: read it again.

Attributes
idstr

This change's place in the stream (what a reconnect resumes after).

atAny
objectstr
object_idstr | None

Its id; None for a coding_agent change that may be any of them.

statusstr | None

Its status as its read gave it then (advisory: the read is the truth); None once it's gone.

parentdict[str, str] | None

What it belongs to ({"object": "project", "id": ...} for a deployment), else None.

changestr | None

What moved: an agent's turn, step, definition, ...; a channel's message, reaction, ...

versionint | None

A workflow's graph version now.

workspace_idstr | None
message_idstr | None
thread_idstr | None
rawdict[str, Any]

The response JSON exactly as the API sent it.

typestr

WatchTyping

class WatchTyping

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

Attributes
channel_idstr
workspace_idstr | None
user_idstr

Who: a user's id, or account for the account's owner.

typingbool
rawdict[str, Any]

The response JSON exactly as the API sent it.

typestr

WatchReset

class WatchReset

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

Attributes
typestr

WatchToken

class WatchToken

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

Attributes
urlstr
tokenstr
expires_atAny
connection_ends_atAny

When the connection it opens ends (watch then reconnects with a new token).

objectslist[str]
user_idstr | None

The user whose objects it follows; None for the account's.

originstr | None

The page's origin the socket must come from, when one was given.

rawdict[str, Any]

The response JSON exactly as the API sent it.

WatchRefused

class WatchRefused(Error)

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

WatchMessage

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.