3 new follow-ups today.
\",\n },\n});\n// res.notification.id — the send is accepted (status \"enqueued\"); the email is\n// resolved asynchronously. Read the outcome back with notifications.get() below.\n```\n\n### Get a notification (check the outcome)\n\nThe send is **asynchronous**: it accepts the notification and returns its id\n(`status: \"enqueued\"`), then the worker resolves in-app delivery and the email.\nFetch the notification by id to see the resolved in-app `status` and, when the send\nincluded an `email` block, the email delivery outcome on `notification.email`.\n\n```typescript\nconst notification = await bodhveda.notifications.get(res.notification!.id);\n\nnotification.status; // \"delivered\" | \"muted\" | \"quota_exceeded\" | \"failed\" | \"enqueued\"\nnotification.email?.status; // \"pending\" | \"sent\" | \"delivered\" | \"bounced\" | ...\nnotification.email?.delivered_at;\n```\n\n---\n\n## Recipients\n\n### Create a recipient\n\nCreate a new recipient.\n\n```typescript\nawait bodhveda.recipients.create({\n id: \"user-123\",\n name: \"Alice\",\n});\n```\n\n### Create multiple recipients (batch)\n\nCreate multiple recipients in a single request.\n\n```typescript\nawait bodhveda.recipients.createBatch({\n recipients: [\n { id: \"user-1\", name: \"Alice\" },\n { id: \"user-2\", name: \"Bob\" },\n ],\n});\n```\n\n### Get a recipient\n\nRetrieve details of a recipient by ID.\n\n```typescript\nconst recipient = await bodhveda.recipients.get(\"user-123\");\n```\n\n### Update a recipient\n\nUpdate recipient details.\n\n```typescript\nawait bodhveda.recipients.update(\"user-123\", { name: \"Alice Updated\" });\n```\n\n### Delete a recipient\n\nDelete a recipient by ID.\n\n```typescript\nawait bodhveda.recipients.delete(\"user-123\");\n```\n\n---\n\n## Recipient Notifications\n\n### List notifications\n\nList notifications for a recipient.\n\n```typescript\nconst notifications = await bodhveda.recipients.notifications.list(\"user-123\");\n```\n\n### Get unread notification count\n\nGet the count of unread notifications for a recipient.\n\n```typescript\nconst { unread_count } = await bodhveda.recipients.notifications.unreadCount(\n \"user-123\"\n);\n```\n\n### Update notification state\n\nUpdate the state (e.g., mark as read) of notifications for a recipient.\n\n```typescript\nawait bodhveda.recipients.notifications.updateState(\"user-123\", {\n ids: [1, 2, 3],\n state: { read: true },\n});\n```\n\n### Delete notifications\n\nDelete notifications for a recipient.\n\n```typescript\nawait bodhveda.recipients.notifications.delete(\"user-123\", {\n ids: [1, 2, 3],\n});\n```\n\n---\n\n## Recipient Preferences\n\n### List preferences\n\nList all preferences for a recipient.\n\n```typescript\nconst preferences = await bodhveda.recipients.preferences.list(\"user-123\");\n```\n\n### Set a preference\n\nSet a notification preference for a recipient. Pass an optional `medium`\n(`\"in_app\"` or `\"email\"`) to toggle in-app and email independently for the same\ntarget. It defaults to `\"in_app\"` when omitted.\n\n```typescript\nawait bodhveda.recipients.preferences.set(\"user-123\", {\n target: { channel: \"digest\", topic: \"none\", event: \"sent\" },\n medium: \"email\",\n state: { enabled: true },\n});\n```\n\n### Check a preference\n\nCheck the state of a specific preference for a recipient.\n\n```typescript\nconst result = await bodhveda.recipients.preferences.check(\"user-123\", {\n target: { channel: \"digest\", topic: \"none\", event: \"sent\" },\n medium: \"email\",\n});\n```\n\n---\n\n## Recipient Contacts\n\nContacts are per-medium addresses for a recipient. To send **email** to a recipient,\nadd an `email` contact and mark it primary. Sync this **server-side** (e.g. on your\n`/me` endpoint) so the address never rides a browser request.\n\n`create`, `list`, and `update` work with a `Full access` or `Recipient access` API\nkey; `delete` requires `Full access`.\n\n### Add a contact\n\n```typescript\nawait bodhveda.recipients.contacts.create(\"user-123\", {\n medium: \"email\",\n address: \"alice@example.com\",\n is_primary: true,\n});\n```\n\n`create` is strict — it rejects with a `409` when the contact already exists. To\nkeep a recipient's primary address current from a server without a\nlist-then-diff, use `setPrimary` instead.\n\n### Set the primary contact\n\nIdempotently ensure an address is the recipient's **primary** contact for a\nmedium — create it if absent, update the existing primary in place if the\naddress differs (which resets verification), or no-op if it already matches.\nReturns the resulting primary contact (`200`) in every case, so a \"keep the\nprimary email current\" sync is a single call.\n\n```typescript\nawait bodhveda.recipients.contacts.setPrimary(\"user-123\", {\n medium: \"email\",\n address: \"alice@example.com\",\n});\n```\n\n### List contacts\n\n```typescript\nconst { contacts } = await bodhveda.recipients.contacts.list(\"user-123\");\n```\n\n### Update a contact\n\n```typescript\nawait bodhveda.recipients.contacts.update(\"user-123\", 1, {\n address: \"alice.new@example.com\",\n});\n```\n\n### Delete a contact\n\nRequires a `Full access` API key.\n\n```typescript\nawait bodhveda.recipients.contacts.delete(\"user-123\", 1);\n```\n\n---\n\n## Project Preferences\n\nThe **project preference catalog** declares which `(target, medium)` pairs your\nproject may send, and the default a recipient inherits until they set a\npreference of their own. This is different from\n[Recipient Preferences](#recipient-preferences), which are a single recipient's\nown toggles — manage the catalog with `bodhveda.preferences`.\n\nRequires a `Full access` API key, and is a **server-side** concern. The project\nis taken from the API key.\n\n> [!IMPORTANT]\n> **Seed the catalog from your deploy, not by hand.**\n>\n> Your desired catalog lives in your code and the real one lives in Bodhveda, so the\n> two drift the moment you ship an event and forget to update Bodhveda to match. An\n> uncataloged target has no preference surface — it appears on no settings screen, so\n> no recipient can mute it — and email to it never sends at all.\n>\n> Derive the array from whatever already defines your events, and run\n> [`upsertMany`](#set-up-a-whole-catalog-at-once) from your deploy pipeline on **every**\n> deploy. It is an idempotent merge, so a deploy that changes nothing is a no-op.\n>\n> This matters more once **strict targets** is on for the project: an uncataloged\n> target then 400s outright. Seed **before** the new code starts serving, and let a\n> failed seed **fail the deploy** — stopping leaves the previous version running, which\n> only sends targets that are already cataloged.\n\n### List the catalog\n\n```typescript\nconst catalog = await bodhveda.preferences.list();\n```\n\n### Create a catalog entry\n\nStrict — rejects with a `409` when an entry for the same\n`(channel, topic, event, medium)` already exists. `medium` defaults to `in_app`\nwhen omitted.\n\n```typescript\nconst entry = await bodhveda.preferences.create({\n channel: \"digest\",\n topic: \"none\",\n event: \"sent\",\n medium: \"email\",\n name: \"Daily digest\",\n description: \"Receive a daily summary of activity.\",\n default_enabled: true,\n});\n```\n\n### Get / update / delete an entry\n\nThe natural key (`channel`/`topic`/`event`/`medium`) is immutable — `update`\nchanges only the name, description and default.\n\n```typescript\nconst entry = await bodhveda.preferences.get(123);\n\nawait bodhveda.preferences.update(123, {\n name: \"Weekly digest\",\n description: \"Receive a weekly summary of activity.\",\n default_enabled: false,\n});\n\n// Un-catalogs the (target, medium).\nawait bodhveda.preferences.delete(123);\n```\n\n### Set up a whole catalog at once\n\n`upsertMany` declaratively merges an entire catalog in one call — the primitive\nfor a one-off \"set up my project's preferences\" script. Each item is upserted by\nits natural key (new inserted, existing name + description + default updated).\nEntries **not** in the array are left untouched.\n\n```typescript\nawait bodhveda.preferences.upsertMany([\n { channel: \"digest\", topic: \"none\", event: \"sent\", medium: \"email\", name: \"Daily digest\", default_enabled: true },\n { channel: \"posts\", topic: \"any\", event: \"new_comment\", medium: \"email\", name: \"Comments\", default_enabled: true },\n]);\n```\n\nPass `{ prune: true }` to also **delete** entries absent from the array, making\nit the entire desired catalog. Pruning un-catalogs a `(target, medium)`, which\nturns a non-`in_app` medium off for recipients relying on the catalog default —\nso it is opt-in.\n\n```typescript\nawait bodhveda.preferences.upsertMany(desiredCatalog, { prune: true });\n```\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}