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

> ## Agent Instructions
> The docs are served at https://docs.devias.io. Every path in these docs is relative to that root: /llms.txt is https://docs.devias.io/llms.txt.
> Devias is an open-source platform that works as an operating system for a business: a core (records, views, workflows, agents, permissions) with installable modules.
> Pages are typed by folder. concepts/ explains what things are, guides/ gives procedures, reference/ is exhaustive (SDK, CLI, HTTP API), operate/ covers hosting. Use /start/glossary for exact terms.
> Every id in a module (module, object, field, view, action, workflow, step, connection, variable, event, policy) is a uuid. Generate them with `devias id <count>`. Never invent dotted or readable ids.
> Run `devias plan` and read its output before `devias apply`. Apply only what the plan says.
> The OpenAPI document, including the routes of the modules in the reference setup, is at /reference/api/openapi.json.
> Devias is young and changes quickly. If a page and the source repository (github.com/devias-io/devias) disagree, the repository is right.

# SDK events and notifications

> How to follow workspace changes with client.events.subscribe (event type, sequence, actor and occurredAt, resuming with after, connection status) and how to send and read notifications with client.notifications, including the to targets all, roles, users and me.

`client.events` follows changes in a workspace as they happen, and `client.notifications` sends and reads messages for the people in it.

## Subscribe to live events

Every change in a workspace is written to a log, and `events.subscribe` listens to it.

```ts theme={"dark"}
const stop = client.events.subscribe((event) => {
  console.log(event.type);
});

// later
stop();
```

`subscribe` returns a function that stops listening. The connection recovers by itself if it drops.

### Shape of an event

Each event has a `type`, a `sequence` number that only increases, the `actor` that caused it and `occurredAt`. Common types:

| Type | When |
| - | - |
| `record.created`, `record.updated`, `record.deleted` | A record changed. |
| `metadata.changed` | The data model changed. |
| `module.applied` | A module was installed or updated. |
| `module.event` | A module received an event from an outside service. |
| `workflow.run` | A workflow ran. |
| `task.changed`, `document.changed` | A task or a document changed. |

The [change feed](https://docs.devias.io/reference/api/change-feed.md#event-types) lists every type.

### Resume after a restart

Store the `sequence` of the last event handled. After a restart, pass it as `after` to receive only later events.

```ts theme={"dark"}
client.events.subscribe(handle, { after: lastSequence });
```

`onStatus` reports the state of the connection: `connecting`, `open`, `reconnecting` or `closed`.

## Notifications

`notifications` is the signed-in person's own inbox, and the way to notify others.

```ts theme={"dark"}
await client.notifications.send({
  title: 'Invoice paid',
  to: { roles: ['admin'] },
});

const { items } = await client.notifications.list({ unread: true });
```

`to` is `all`, a list of `roles`, a list of `users`, or `me`. `markRead`, `markUnread`, `markAllRead` and `delete` manage received notifications.

## Related

* [Change feed over HTTP](https://docs.devias.io/reference/api/change-feed.md): the same stream for any language.
* [Workflows and tasks](https://docs.devias.io/concepts/automation.md): act on events without code.


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