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

# Notifications

> Tell agents when files or directories change in the virtual filesystem.

Notifications tell an agent when a file or directory changes in the virtual
filesystem: a teammate edits a report in Box, and the agent gets
`update /box/report.csv`.

1. The application receives a change from the service, or asks it for one.
2. It reports the change with `ws.notify()`, which also drops Mirage's cached
   copy of that path.
3. The agent receives it from `ws.events()`.

`ws.events()` alone watches nothing: the application connects the service, by
[push](#push) or [poll](#poll).

## Listen for changes

```python Python theme={null}
async for change in ws.events("/data"):
    print(f"{change.kind.value}: {change.path.virtual}")
```

```typescript TypeScript theme={null}
for await (const change of ws.events('/data')) {
  console.log(`${change.kind}: ${change.path.virtual}`)
}
```

```text theme={null}
update: /data/report.csv
```

| Path | Receives |
| - | - |
| `/data` | every change under `/data` |
| `/data/*.csv` | changes to CSV files directly inside `/data` |
| `["/data/reports", "/data/config.json"]` | changes under `reports` or to `config.json` |

| Kind | Meaning |
| - | - |
| `create` | a file or directory was added |
| `update` | its contents or metadata changed |
| `delete` | it was removed |
| `move` | it was renamed or moved; the change also carries its previous path |
| `unknown` | something changed but the service gave no details; read the path again |

## Push

The service sends each change: a webhook, a stream or a file watcher. A hook
turns its payload into changes for `ws.notify()`:

```python Python theme={null}
from mirage.core.s3.events import S3EventHook
from mirage.types import PathSpec

hook = S3EventHook(vfs.accessor)
root = PathSpec.from_str_path("/s3", "")
for record in payload["Records"]:
    for change in await hook.to_events(root, record["eventName"], record):
        await ws.notify(change)
```

```typescript TypeScript theme={null}
import { PathSpec } from '@struktoai/mirage-node'
import { S3EventHook } from '@struktoai/mirage-core/core/s3/events'

const hook = new S3EventHook(vfs.accessor)
const root = PathSpec.fromStrPath('/s3', '')
for (const record of payload.Records) {
  for (const change of await hook.toEvents(root, record.eventName, record)) {
    await ws.notify(change)
  }
}
```

| VFS | Service | Hook (`to_events`, `toEvents`) |
| - | - | - |
|  [Disk](https://docs.mirage.strukto.ai/home/setup/disk.md) | File watchers: [watchdog](https://github.com/gorakhargosh/watchdog), [chokidar](https://github.com/paulmillr/chokidar) | `DiskEventHook` |
| ![](https://mintcdn.com/struktoai/AvU64XZuiQaceY0a/images/s3-logo.svg?fit=max\&auto=format\&n=AvU64XZuiQaceY0a\&q=85\&s=3a2c625e597531599eca1cdb67504e6b)[S3](https://docs.mirage.strukto.ai/home/setup/s3.md) | [Event Notifications](https://docs.aws.amazon.com/AmazonS3/latest/userguide/EventNotifications.html) | `S3EventHook` |
| ![](https://mintcdn.com/struktoai/wbn_tJeahvJMuT6I/images/github-logo.svg?fit=max\&auto=format\&n=wbn_tJeahvJMuT6I\&q=85\&s=c8293df924c23b66e4aae30931882bac)[GitHub](https://docs.mirage.strukto.ai/home/setup/github.md) | [Push webhooks](https://docs.github.com/en/webhooks/webhook-events-and-payloads#push) | `GitHubEventHook` |
| ![](https://mintcdn.com/struktoai/CsxMCKUyfoQQJYHB/images/nextcloud-logo.svg?fit=max\&auto=format\&n=CsxMCKUyfoQQJYHB\&q=85\&s=8dc313df81e8df7e4a821c131e599348)[Nextcloud](https://docs.mirage.strukto.ai/home/setup/nextcloud.md) | [Webhook listeners](https://docs.nextcloud.com/server/latest/admin_manual/webhook_listeners/index.html) | `NextcloudEventHook` |
| ![](https://mintcdn.com/struktoai/CsxMCKUyfoQQJYHB/images/mongodb-logo.svg?fit=max\&auto=format\&n=CsxMCKUyfoQQJYHB\&q=85\&s=b2b0a224242b5d843a468f880febb2d9)[MongoDB](https://docs.mirage.strukto.ai/home/setup/mongodb.md) | [Change streams](https://www.mongodb.com/docs/manual/changestreams/) | `MongoDBEventHook` |
| ![](https://mintcdn.com/struktoai/CsxMCKUyfoQQJYHB/images/mongodb-logo.svg?fit=max\&auto=format\&n=CsxMCKUyfoQQJYHB\&q=85\&s=b2b0a224242b5d843a468f880febb2d9)[GridFS](https://docs.mirage.strukto.ai/home/setup/gridfs.md) | [Change streams](https://www.mongodb.com/docs/manual/changestreams/) on `<bucket>.files` | `GridFSEventHook` |
| ![](https://mintcdn.com/struktoai/AvU64XZuiQaceY0a/images/slack-logo.svg?fit=max\&auto=format\&n=AvU64XZuiQaceY0a\&q=85\&s=3179a7f44417e57a2d5ea310b04234f9)[Slack](https://docs.mirage.strukto.ai/home/setup/slack.md) | [Events API](https://docs.slack.dev/apis/events-api/) | `SlackEventHook` |
| ![](https://mintcdn.com/struktoai/CsxMCKUyfoQQJYHB/images/redis-logo.svg?fit=max\&auto=format\&n=CsxMCKUyfoQQJYHB\&q=85\&s=1f81a02282061ad43e3aa8f86b01434a)[Redis](https://docs.mirage.strukto.ai/home/setup/redis.md) | [Keyspace notifications](https://redis.io/docs/latest/develop/pubsub/keyspace-notifications/) | `RedisEventHook` |
| ![](https://mintcdn.com/struktoai/AvU64XZuiQaceY0a/images/discord-logo.svg?fit=max\&auto=format\&n=AvU64XZuiQaceY0a\&q=85\&s=d18fb2b5008fbab5622dc98e1c487f46)[Discord](https://docs.mirage.strukto.ai/home/setup/discord.md) | [Gateway events](https://docs.discord.com/developers/events/gateway-events) | `DiscordEventHook` |
| ![](https://mintcdn.com/struktoai/CsxMCKUyfoQQJYHB/images/linear-logo.svg?fit=max\&auto=format\&n=CsxMCKUyfoQQJYHB\&q=85\&s=e3b137d0009673120cbfb7f54318569f)[Linear](https://docs.mirage.strukto.ai/home/setup/linear.md) | [Webhooks](https://linear.app/developers/webhooks) | `LinearEventHook` |
| ![](https://mintcdn.com/struktoai/AvU64XZuiQaceY0a/images/trello-logo.svg?fit=max\&auto=format\&n=AvU64XZuiQaceY0a\&q=85\&s=85c19ea2096091fb3921f6e9e65e3943)[Trello](https://docs.mirage.strukto.ai/home/setup/trello.md) | [Webhooks](https://developer.atlassian.com/cloud/trello/guides/rest-api/webhooks/) | `TrelloEventHook` |
| ![](https://mintcdn.com/struktoai/CsxMCKUyfoQQJYHB/images/notion-logo.svg?fit=max\&auto=format\&n=CsxMCKUyfoQQJYHB\&q=85\&s=56d8acf991bbacdee6349192f8aa16ef)[Notion](https://docs.mirage.strukto.ai/home/setup/notion.md) | [Webhooks](https://developers.notion.com/reference/webhooks) | `NotionEventHook` |
|  [Email](https://docs.mirage.strukto.ai/home/setup/email.md) | [IMAP IDLE](https://datatracker.ietf.org/doc/html/rfc2177) | `EmailEventHook` |
| ![](https://mintcdn.com/struktoai/CsxMCKUyfoQQJYHB/images/box-logo.svg?fit=max\&auto=format\&n=CsxMCKUyfoQQJYHB\&q=85\&s=70a2254be6ebf081ee4934b27d41dcf5)[Box](https://docs.mirage.strukto.ai/home/setup/box.md) | [Events API](https://developer.box.com/guides/events/user-events/polling), read by a long poll | `BoxEventHook` |

## Poll

The VFS asks the service what changed since a checkpoint. The first `pull`,
with no checkpoint, returns none and records where to start:

```python Python theme={null}
import asyncio

from mirage.types import PathSpec

hook = vfs.delta_hook()
root = PathSpec.from_str_path("/box", "")
checkpoint = (await hook.pull(root, None)).checkpoint
while True:
    await asyncio.sleep(5)
    result = await hook.pull(root, checkpoint)
    for change in result.changes:
        await ws.notify(change)
    checkpoint = result.checkpoint
```

```typescript TypeScript theme={null}
import { setTimeout as delay } from 'node:timers/promises'
import { PathSpec } from '@struktoai/mirage-node'

const hook = vfs.deltaHook()
const root = PathSpec.fromStrPath('/box', '')
let checkpoint = (await hook.pull(root, null)).checkpoint
for (;;) {
  await delay(5000)
  const result = await hook.pull(root, checkpoint)
  for (const change of result.changes) await ws.notify(change)
  checkpoint = result.checkpoint
}
```

| VFS | Service |
| - | - |
| ![](https://mintcdn.com/struktoai/i_m5DIPdui2Jlopk/images/airtable-logo.svg?fit=max\&auto=format\&n=i_m5DIPdui2Jlopk\&q=85\&s=2b429baafe9b4e57a07cf90f0c4252f1)[Airtable](https://docs.mirage.strukto.ai/home/setup/airtable.md) | [Webhooks API](https://airtable.com/developers/web/api/webhooks-overview) |
| ![](https://mintcdn.com/struktoai/CsxMCKUyfoQQJYHB/images/box-logo.svg?fit=max\&auto=format\&n=CsxMCKUyfoQQJYHB\&q=85\&s=70a2254be6ebf081ee4934b27d41dcf5)[Box](https://docs.mirage.strukto.ai/home/setup/box.md) | [Long-poll events](https://developer.box.com/guides/events/user-events/polling) |
| ![](https://mintcdn.com/struktoai/AvU64XZuiQaceY0a/images/dropbox-logo.svg?fit=max\&auto=format\&n=AvU64XZuiQaceY0a\&q=85\&s=7701d8372130b5e8818af52655c6ecab)[Dropbox](https://docs.mirage.strukto.ai/home/setup/dropbox.md) | [Webhooks or long polling](https://docs.dropboxapi.com/dropbox-api/docs/detecting-changes) |
| ![](https://mintcdn.com/struktoai/AvU64XZuiQaceY0a/images/gmail-logo.svg?fit=max\&auto=format\&n=AvU64XZuiQaceY0a\&q=85\&s=31cc2874ffc7fed853ce07a178a70b16)[Gmail](https://docs.mirage.strukto.ai/home/setup/google.md) | [Pub/Sub notifications](https://developers.google.com/workspace/gmail/api/guides/push) |
| ![](https://mintcdn.com/struktoai/AvU64XZuiQaceY0a/images/gcal-logo.svg?fit=max\&auto=format\&n=AvU64XZuiQaceY0a\&q=85\&s=1904e1a1d24572d9a2663ae910cb5882)[Google Calendar](https://docs.mirage.strukto.ai/home/setup/gcal.md) | [Push notifications](https://developers.google.com/workspace/calendar/api/guides/push) |
| ![](https://mintcdn.com/struktoai/AvU64XZuiQaceY0a/images/gdrive-logo.svg?fit=max\&auto=format\&n=AvU64XZuiQaceY0a\&q=85\&s=94291d56fedde3d667a564b1917de57a)[Google Drive, Docs, Sheets, Slides](https://docs.mirage.strukto.ai/home/setup/google.md) | [Drive notifications](https://developers.google.com/workspace/drive/api/guides/push) |
|  [OneDrive](https://docs.mirage.strukto.ai/home/setup/onedrive.md) | [Microsoft Graph notifications](https://learn.microsoft.com/en-us/graph/change-notifications-overview) |
|  [SharePoint](https://docs.mirage.strukto.ai/home/setup/sharepoint.md) | [Microsoft Graph notifications](https://learn.microsoft.com/en-us/graph/change-notifications-overview) |

Any other VFS: the application detects the change itself and calls
`ws.notify()`.

## Examples

| VFS | Kind | Code | Needs |
| - | - | - | - |
|  [Disk](https://docs.mirage.strukto.ai/home/setup/disk.md) | Push | [disk.py](https://github.com/strukto-ai/mirage/blob/main/examples/python/notifications/push/disk.py), [disk.ts](https://github.com/strukto-ai/mirage/blob/main/examples/typescript/notifications/push/disk.ts) | nothing; it edits temporary local files |
| ![](https://mintcdn.com/struktoai/AvU64XZuiQaceY0a/images/s3-logo.svg?fit=max\&auto=format\&n=AvU64XZuiQaceY0a\&q=85\&s=3a2c625e597531599eca1cdb67504e6b)[S3](https://docs.mirage.strukto.ai/home/setup/s3.md) | Push | [s3.py](https://github.com/strukto-ai/mirage/blob/main/examples/python/notifications/push/s3.py), [s3.ts](https://github.com/strukto-ai/mirage/blob/main/examples/typescript/notifications/push/s3.ts) | `S3_BUCKET` and a saved S3 notification JSON file |
| ![](https://mintcdn.com/struktoai/wbn_tJeahvJMuT6I/images/github-logo.svg?fit=max\&auto=format\&n=wbn_tJeahvJMuT6I\&q=85\&s=c8293df924c23b66e4aae30931882bac)[GitHub](https://docs.mirage.strukto.ai/home/setup/github.md) | Push | [github.py](https://github.com/strukto-ai/mirage/blob/main/examples/python/notifications/push/github.py), [github.ts](https://github.com/strukto-ai/mirage/blob/main/examples/typescript/notifications/push/github.ts) | `GITHUB_TOKEN`, `GITHUB_REPOSITORY` (`owner/repo`) and a saved push webhook JSON file; `GITHUB_REF` defaults to `main` |
| ![](https://mintcdn.com/struktoai/AvU64XZuiQaceY0a/images/dropbox-logo.svg?fit=max\&auto=format\&n=AvU64XZuiQaceY0a\&q=85\&s=7701d8372130b5e8818af52655c6ecab)[Dropbox](https://docs.mirage.strukto.ai/home/setup/dropbox.md) | Poll | [dropbox.py](https://github.com/strukto-ai/mirage/blob/main/examples/python/notifications/poll/dropbox.py), [dropbox.ts](https://github.com/strukto-ai/mirage/blob/main/examples/typescript/notifications/poll/dropbox.ts) | `DROPBOX_APP_KEY`, `DROPBOX_APP_SECRET`, `DROPBOX_REFRESH_TOKEN` |
| ![](https://mintcdn.com/struktoai/CsxMCKUyfoQQJYHB/images/box-logo.svg?fit=max\&auto=format\&n=CsxMCKUyfoQQJYHB\&q=85\&s=70a2254be6ebf081ee4934b27d41dcf5)[Box](https://docs.mirage.strukto.ai/home/setup/box.md) | Poll | [box.py](https://github.com/strukto-ai/mirage/blob/main/examples/python/notifications/poll/box.py), [box.ts](https://github.com/strukto-ai/mirage/blob/main/examples/typescript/notifications/poll/box.ts) | `BOX_ACCESS_TOKEN` |
| ![](https://mintcdn.com/struktoai/AvU64XZuiQaceY0a/images/gdrive-logo.svg?fit=max\&auto=format\&n=AvU64XZuiQaceY0a\&q=85\&s=94291d56fedde3d667a564b1917de57a)[Google Drive](https://docs.mirage.strukto.ai/home/setup/google.md) | Poll | [gdrive.py](https://github.com/strukto-ai/mirage/blob/main/examples/python/notifications/poll/gdrive.py), [gdrive.ts](https://github.com/strukto-ai/mirage/blob/main/examples/typescript/notifications/poll/gdrive.ts) | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_REFRESH_TOKEN` |

```bash Python theme={null}
./python/.venv/bin/python examples/python/notifications/push/disk.py
```

```bash TypeScript theme={null}
pnpm -C examples/typescript exec tsx notifications/push/disk.ts
```

The Disk example edits files behind Mirage, reports each change, and reads
again:

```text theme={null}
$ cat /data/reports/q1.txt
first quarter
create: /data/reports/q3.txt
update: /data/reports/q1.txt
delete: /data/reports/q2.txt
$ cat /data/reports/q1.txt
first quarter, revised
$ ls /data/reports
q1.txt
q3.txt
```

The S3 and GitHub examples read a saved payload and start no webhook server.
Dropbox waits on a long poll; Box and Google Drive check every five seconds
until Ctrl-C.


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