> ## 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.

# VFS Notifications

> Notification services and Python and TypeScript functions for reporting file and directory changes in the virtual filesystem.

Connect your VFS to a notification service using Push or Poll.
See the [overview](/home/notifications) for listening to changes and event types.

## Push

Receive file changes through webhooks, streams or external file watchers. Convert them
with the functions below, then call `ws.notify()` for each change.
See the [Python and TypeScript examples](#push-examples).

| VFS | Notification service | Python method | TypeScript method |
| - | - | - | - |
| Disk | External tools: [watchdog](https://github.com/gorakhargosh/watchdog) / [chokidar](https://github.com/paulmillr/chokidar) | `DiskEventHook.to_events` | `DiskEventHook.toEvents` |
| S3 | [S3 Event Notifications](https://docs.aws.amazon.com/AmazonS3/latest/userguide/EventNotifications.html) | `S3EventHook.to_events` | `S3EventHook.toEvents` |
| GitHub | [Push webhooks](https://docs.github.com/en/webhooks/webhook-events-and-payloads#push) | `GitHubEventHook.to_events` | `GitHubEventHook.toEvents` |
| Nextcloud | [Webhook Listeners](https://docs.nextcloud.com/server/latest/admin_manual/webhook_listeners/index.html) | `NextcloudEventHook.to_events` | `NextcloudEventHook.toEvents` |
| MongoDB | [Change streams](https://www.mongodb.com/docs/manual/changestreams/) | `MongoDBEventHook.to_events` | `MongoDBEventHook.toEvents` |
| GridFS | [Change streams](https://www.mongodb.com/docs/manual/changestreams/) on `<bucket>.files` | `GridFSEventHook.to_events` | `GridFSEventHook.toEvents` |
| Slack | [Events API](https://docs.slack.dev/apis/events-api/) | `SlackEventHook.to_events` | `SlackEventHook.toEvents` |
| Redis | [Keyspace notifications](https://redis.io/docs/latest/develop/pubsub/keyspace-notifications/) | `RedisEventHook.to_events` | `RedisEventHook.toEvents` |
| Discord | [Gateway events](https://docs.discord.com/developers/events/gateway-events) | `DiscordEventHook.to_events` | `DiscordEventHook.toEvents` |
| Linear | [Webhooks](https://linear.app/developers/webhooks) | `LinearEventHook.to_events` | `LinearEventHook.toEvents` |
| Trello | [Webhooks](https://developer.atlassian.com/cloud/trello/guides/rest-api/webhooks/) | `TrelloEventHook.to_events` | `TrelloEventHook.toEvents` |
| Notion | [Webhooks](https://developers.notion.com/reference/webhooks) | `NotionEventHook.to_events` | `NotionEventHook.toEvents` |
| Email | [IMAP IDLE](https://datatracker.ietf.org/doc/html/rfc2177) | `EmailEventHook.to_events` | `EmailEventHook.toEvents` |

### Push examples

| Backend | Python | TypeScript | What to provide |
| - | - | - | - |
| Disk | [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; changes temporary files locally |
| S3 | [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 |
| GitHub | [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` accepts a short name or full ref and defaults to `main` |

The S3 and GitHub examples process a saved payload; they do not start a webhook server.
Run from the repository root after installing the language's dependencies:

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

```bash TypeScript theme={null}
pnpm -C examples/typescript exec tsx notifications/push/disk.ts
pnpm -C examples/typescript exec tsx notifications/push/s3.ts /absolute/path/to/notification.json
```

The Disk example creates, updates and deletes temporary local files, then
reports those changes directly to Mirage. It prints:

```text Disk output theme={null}
read before: 'first quarter'

file changes:
  create /data/reports/q3.txt
  update /data/reports/q1.txt
  delete /data/reports/q2.txt

read after notify: 'first quarter, revised'
listing: q1.txt q3.txt
```

For S3, a saved `ObjectCreated:Put` notification for `report.csv` in your
configured bucket produces:

```text S3 output theme={null}
create: /s3/report.csv
```

## Poll

Fetch changed files from the service, on a schedule or after a notification.
Create `hook` with `vfs.delta_hook()` (Python) or `vfs.deltaHook()` (TypeScript).
Call `await hook.pull(root, checkpoint)`, send each item in `result.changes`
to `ws.notify()`, and save `result.checkpoint` for the next call.
See the [Python and TypeScript examples](#poll-examples).

| VFS | Notification service | Python | TypeScript |
| - | - | - | - |
| Airtable | [Webhooks API](https://airtable.com/developers/web/api/webhooks-overview) | `vfs.delta_hook()` | `vfs.deltaHook()` |
| Box | [Long-poll events](https://developer.box.com/guides/events/user-events/polling) | `vfs.delta_hook()` | `vfs.deltaHook()` |
| Box | [Events API responses](https://developer.box.com/guides/events/user-events/polling) | `BoxEventHook.to_events` | `BoxEventHook.toEvents` |
| Dropbox | [Webhooks or long polling](https://docs.dropboxapi.com/dropbox-api/docs/detecting-changes) | `vfs.delta_hook()` | `vfs.deltaHook()` |
| Gmail | [Pub/Sub notifications](https://developers.google.com/workspace/gmail/api/guides/push) | `vfs.delta_hook()` | `vfs.deltaHook()` |
| Google Calendar | [Push notifications](https://developers.google.com/workspace/calendar/api/guides/push) | `vfs.delta_hook()` | `vfs.deltaHook()` |
| Google Drive, Docs, Sheets, Slides | [Drive notifications](https://developers.google.com/workspace/drive/api/guides/push) | `vfs.delta_hook()` | `vfs.deltaHook()` |
| OneDrive / SharePoint | [Microsoft Graph notifications](https://learn.microsoft.com/en-us/graph/change-notifications-overview) | `vfs.delta_hook()` | `vfs.deltaHook()` |

For other VFS types, your application can detect changes and report them
directly with `ws.notify()`.

### Poll examples

| Backend | Python | TypeScript | Environment variables |
| - | - | - | - |
| Dropbox | [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` |
| Box | [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` |
| Google Drive | [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` |

Dropbox waits for a long-poll notification. Box and Google Drive check every
five seconds. Start an example, then edit files in that service to see their
virtual paths. Press Ctrl-C to stop. Each run starts from the current state.

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

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

For example, start the Box example, then upload a new `report.csv` to the
root folder in Box:

```text Example output theme={null}
Watching /box; edit files in the service (Ctrl-C to stop)
create: /box/report.csv
```


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