@xtremax/pigeon 0.0.0-stage → 0.3.1

package/skills/add-pigeon-notifications/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: add-pigeon-notifications
+description: Add in-app notifications to an app with Pigeon (the Buildpad Communication Gateway) - a notification bell with an unread badge, a panel, a full list and an on/off preference from the @xtremax/pigeon npm package, plus sending notifications from server code. Use whenever the user asks for a notification bell, in-app notifications, a notification inbox or centre, an unread badge, "notify the user when X happens", or mentions Pigeon or the Communication connector, even if they do not name the package. Do not build a custom bell, a notifications table or polling code - this skill replaces all of that.
+user-invokable: true
+---
+
+# Add Pigeon Notifications
+
+Gives an app a notification bell and the code to send notifications, using **Pigeon** and its npm package `@xtremax/pigeon`. Pigeon stores the notifications, the read state and each person's on/off choice. The app stores nothing.
+
+This skill ships inside the package. `npx @xtremax/pigeon add-skill` copies it into the app's `.claude/skills/` (and `.kiro/skills/`); run that again after upgrading the package to get the newer skill. It is self-contained: it assumes you have none of Pigeon's own repository.
+
+## What you are building
+
+```
+browser: the bell  ->  the app's own route: /api/communication/inbox/*  ->  Pigeon
+(from the package)     (one file, from the package's handler)               (holds the notifications)
+
+the app's server code  ->  communication.messages.send(...)  ->  Pigeon  ->  the person's bell
+```
+
+Three small pieces, all from one package:
+
+| Piece | Where | From |
+|---|---|---|
+| The route the bell calls | `app/api/communication/inbox/[...path]/route.ts` | `@xtremax/pigeon/inbox` |
+| The bell | the app's header | `@xtremax/pigeon/inbox-react` |
+| Sending | wherever something happens that a person should know | `@xtremax/pigeon/client` |
+
+A bell shows a person two things: what **this app** sent them, and the organisation's **announcements**. Another app's notifications never appear in it. There is nothing to configure for that.
+
+## The rules
+
+These are what keeps the integration safe. Each has a reason; do not trade one away for convenience.
+
+1. **The key stays on the server.** `COMMUNICATION_API_KEY` is a secret that can read anybody's notifications. Never give it a `NEXT_PUBLIC_` name, never send it to the browser, never log it.
+2. **The browser never calls Pigeon.** It calls the app's own route, and that route decides who the person is. This is why a person can only ever see their own notifications.
+3. **The person comes from the app's own session only.** `resolvePerson` reads the signed-in user on the server. Never read a person id from the request's path, query or body: anyone could put another person's id there.
+4. **One id per person, everywhere.** The id you send to (`personId`) must be the exact string `resolvePerson` returns. Use one helper for both (Step 4). A mismatch is the most common mistake: the message is delivered and the bell stays empty.
+5. **Do not build what the package has.** No custom bell, panel, unread counter, polling hook, notifications collection or "mark as read" endpoint. No `CollectionList` for notifications: they are not a collection of this app.
+6. **A notification must never break the action that caused it.** If sending fails, log it and carry on (Step 6).
+
+The package's preference dialog uses Mantine's `Switch` internally. That is inside the package, not app code, so the Buildpad-First rule does not apply to it. Do not wrap or replace it.
+
+## Before you start
+
+**1. The app must have** Next.js (App Router), React 19, Mantine 8 (`@mantine/core`, `@mantine/hooks`) and `@tabler/icons-react`. Every Buildpad starter has them. Check `package.json`. If the app is not on React and Mantine, read `references/inbox-contract.instructions.md`: the route still works, and you build the bell against its six operations.
+
+**2. You need a key and Pigeon's address.** Look in this order, and stop at the first that has them:
+
+- `get_project_detail` (the platform MCP tool): if `connectors[]` has `communication`, its variables are `COMMUNICATION_API_KEY` and `COMMUNICATION_URL`.
+- `.env.local` already has both.
+- Otherwise **ask the user for both**. Do not invent them and do not continue without them. Tell the user how an operator gets them, in Pigeon's console:
+  1. Open the organisation's tenant and add a **sub-tenant** for this app (this is what gives the app a bell of its own).
+  2. Switch to that sub-tenant, then **Delivery › API clients › New API client**. The key is shown once.
+  3. Under **Channels**, the in-app channel must be switched on for the tenant.
+
+**3. The package must be installable.** If `pnpm add @xtremax/pigeon` answers 404, the package is not published yet or the registry is wrong. Stop and tell the user. Do not recreate the bell by hand.
+
+## Step 1: Install
+
+```bash
+pnpm add @xtremax/pigeon
+```
+
+Version 0.3.1 or later. No component files are copied into the app.
+
+If you are reading this skill from `node_modules/@xtremax/pigeon/skills/`, the package is already installed: run `npx @xtremax/pigeon add-skill` so the skill is in the project for the next session, and carry on.
+
+## Step 2: Environment
+
+`.env.local`:
+
+```env
+COMMUNICATION_API_KEY=<the key>
+COMMUNICATION_URL=<Pigeon's address, for example https://pigeon.example.com>
+```
+
+For a deployed app on AWS Amplify, do both of these, or the running app will not see the variables:
+
+- Set the two variables on the Amplify app (the `amplify_set_env_vars` platform tool, or the Amplify console).
+- Add them to `amplify.yml`, in the build commands, beside the other server-only variables:
+
+```yaml
+        - echo "COMMUNICATION_API_KEY=$COMMUNICATION_API_KEY" >> .env.production
+        - echo "COMMUNICATION_URL=$COMMUNICATION_URL" >> .env.production
+```
+
+## Step 3: Check the key works
+
+Run this once, from the app's folder. It prints where the key sits and which channels it can use. It never prints the key.
+
+```bash
+node --env-file=.env.local --input-type=module -e "import { createCommunicationClient } from '@xtremax/pigeon/client'; const c = createCommunicationClient(); console.log(await c.ping()); console.log(await c.channels.list());"
+```
+
+Read the output:
+
+- `scopes` must include `inbox:read` and `inbox:write`. If not, the key is an old one: ask the user for a new key.
+- `subKey` is the app's sub-tenant, or `null` for a key at tenant level. Either works. With `null`, the app shares a bell with every other tenant-level app.
+- In the channel list, find the entry with `medium: 'in_app'` and `ready: true`. Its `key` is the channel you send on, usually `in-app`. If there is none, the operator has to switch the in-app channel on; nothing can be sent until then.
+
+## Step 4: One helper for the person's id
+
+```ts
+// lib/communication/person.ts
+/** The id Pigeon knows a person by: their email, in lower case. Used for reading and for sending. */
+export const personIdOf = (email: string): string => email.trim().toLowerCase();
+```
+
+Use the lower-cased email unless the user tells you otherwise. It is the same in every app of the organisation, so an announcement read in one app's bell is read in the others.
+
+## Step 5: The route
+
+One file. It needs no other code.
+
+```ts
+// app/api/communication/inbox/[...path]/route.ts
+import { createInboxHandler } from '@xtremax/pigeon/inbox';
+import { personIdOf } from '@/lib/communication/person';
+import { createClient } from '@/lib/supabase/server';
+
+export const dynamic = 'force-dynamic';
+
+const handler = createInboxHandler({
+  // Who is signed in, from this app's own session. null means nobody.
+  resolvePerson: async () => {
+    const supabase = await createClient();
+    const { data } = await supabase.auth.getUser();
+    return data.user?.email ? personIdOf(data.user.email) : null;
+  },
+  // The browser is never told why something failed. This is where you see it.
+  onError: (error) => console.error('[communication-inbox]', error),
+});
+
+export { handler as GET, handler as POST, handler as PUT };
+```
+
+- `createClient` from `@/lib/supabase/server` is how a Buildpad starter reads the signed-in user, on an Engine project and on a Supabase project alike. If the app signs people in another way, read the user from that session instead. The rule is only: from the server's session, never from the request.
+- In an app with locale routes (`app/[lang]/...`), the route still lives at `app/api/...`, not under `[lang]`.
+- **Check the middleware.** A signed-out call to this route must get the handler's own `401` JSON, not a redirect to a login page. If the app's middleware redirects `/api/*` requests, exclude `/api/communication/inbox`.
+- The handler reads the key and the address on the first request. A missing one answers `503 unavailable` and never stops the build.
+
+## Step 6: The bell
+
+Import the stylesheet once, in the root layout, **after** Mantine's:
+
+```tsx
+// app/layout.tsx
+import '@mantine/core/styles.css';
+import '@xtremax/pigeon/inbox-react/styles.css';
+```
+
+Put the bell in the header that signed-in people see. In a Buildpad starter that is `<AppShell.Header>` in `components/layout/AuthenticatedShell.tsx`:
+
+```tsx
+import { InboxProvider, NotificationBell } from '@xtremax/pigeon/inbox-react';
+
+<InboxProvider>
+  <NotificationBell />
+</InboxProvider>
+```
+
+- It must render inside `MantineProvider`, and only for signed-in people.
+- It follows the app's Mantine theme and colour scheme. Do not restyle it.
+- In an app with locale routes, pass the locale: `<InboxProvider locale={lang}>`. For a language other than English pass `labels` too; the list of labels is in `references/inbox-contract.instructions.md`.
+- Render it once per page: one `InboxProvider` with one `NotificationBell`. Each provider asks for the count on its own, so two of them double the calls.
+
+## Step 7: Send notifications
+
+One module makes the client, lazily, so a missing key cannot break the build:
+
+```ts
+// lib/communication/client.ts
+import { createCommunicationClient, type CommunicationClient } from '@xtremax/pigeon/client';
+
+let client: CommunicationClient | undefined;
+/** Server only. Reads COMMUNICATION_API_KEY and COMMUNICATION_URL. */
+export const communication = (): CommunicationClient => (client ??= createCommunicationClient());
+```
+
+One function sends, and never throws:
+
+```ts
+// lib/communication/notify.ts
+import { deriveIdempotencyKey } from '@xtremax/pigeon';
+import { CommunicationError } from '@xtremax/pigeon/client';
+import { communication } from './client';
+import { personIdOf } from './person';
+
+/** The in-app channel's key, as `channels.list()` named it in Step 3. */
+const IN_APP_CHANNEL = 'in-app';
+
+export interface Notification {
+  /** The recipient's email. */
+  to: string;
+  /** Plain text, at most 120 characters. */
+  title: string;
+  /** Plain text, at most 1800 characters. */
+  body: string;
+  /** What makes this notification unique: the event, the record and the recipient. Sent twice with the same parts, it arrives once. */
+  dedupe: Array<string | number>;
+}
+
+/** Sends one in-app notification. Answers whether Pigeon accepted it. Never throws: a notification must not break the action that caused it. */
+export async function notify({ to, title, body, dedupe }: Notification): Promise<boolean> {
+  try {
+    const personId = personIdOf(to);
+    const message = await communication().messages.send({
+      templateKey: 'generic.notification',
+      channel: IN_APP_CHANNEL,
+      recipient: { personId },
+      variables: { title: title.slice(0, 120), body: body.slice(0, 1800) },
+      idempotencyKey: await deriveIdempotencyKey(...dedupe, personId),
+    });
+    // `failed` here is usually the person's own choice: they switched this app's notifications off.
+    return message.state !== 'failed';
+  } catch (error) {
+    console.error('[communication] notification not sent:', error instanceof CommunicationError ? error.code : error);
+    return false;
+  }
+}
+```
+
+Call it from server code only (an API route or a server action), after the action itself has succeeded:
+
+```ts
+await notify({
+  to: member.email,
+  title: 'You were added to Finance',
+  body: 'Open Organisations to see your unit.',
+  dedupe: ['unit-member-added', unit.id],
+});
+```
+
+What to know when choosing what to send:
+
+- **Ask the user which events should notify whom** if they have not said. Do not notify on everything.
+- **Do not notify the person who did the action** about their own action.
+- **`generic.notification`** is a template every tenant has: a title and a body, plain text. Markup is shown as text.
+- **A notification that opens a page** needs a template with a link, which an operator adds under **Templates** in Pigeon's console (an in-app variant with a `link`). Use its key as `templateKey` and pass its variables. Only absolute `https://` links open. You cannot create a template from the app: ask the user.
+- **Many recipients:** call `notify` once per person. For "everyone in the organisation", that is an announcement, which an operator sends from Pigeon's console; do not loop over all users.
+- **`dedupe`** must name the event and the record; the recipient is added for you. Sent again with the same parts, the notification arrives once, which is what makes a retry safe. So when the same thing can truly happen twice (added, removed, added again), include what tells the two apart, such as the id of the membership record. The same parts with different text are refused.
+
+## Step 8: Tests
+
+Add these. They are quick, and the first group needs no key.
+
+**Playwright, signed out** (the route protects itself):
+
+```ts
+test('the inbox route refuses a signed-out caller and a foreign origin', async ({ request }) => {
+  const signedOut = await request.get('/api/communication/inbox/summary');
+  expect(signedOut.status()).toBe(401);
+  expect((await signedOut.json()).error.code).toBe('not_signed_in');
+
+  const foreign = await request.post('/api/communication/inbox/read-all', { headers: { origin: 'https://evil.example' }, data: {} });
+  expect(foreign.status()).toBe(403);
+
+  expect((await request.get('/api/communication/inbox/everyone')).status()).toBe(404);
+});
+```
+
+**Playwright, signed in** (with the app's existing test sign-in): the bell is in the header and opens.
+
+```ts
+const bell = page.getByRole('button', { name: /^Notifications/ });
+await expect(bell).toBeVisible();
+await bell.click();
+await expect(page.getByRole('dialog').getByRole('heading', { name: 'Notifications' })).toBeVisible();
+```
+
+**Vitest:** `personIdOf(' Ana@Acme.com ')` is `'ana@acme.com'`; and `notify` answers `false` without throwing when the client throws (mock `./client`).
+
+## Step 9: Verify
+
+- [ ] `pnpm build` and the type check pass.
+- [ ] Signed out, `GET /api/communication/inbox/summary` answers `401` with `{"error":{"code":"not_signed_in",...}}`, as JSON and not as a redirect.
+- [ ] Signed in, the same call answers `200` with `unreadCount`, and the bell shows in the header.
+- [ ] Trigger a `notify`. The badge appears at the bell's next check, within 60 seconds. Opening the bell shows the notification; selecting it marks it read.
+- [ ] `grep -rn "COMMUNICATION_API_KEY" app components lib` shows no file with `'use client'` and no `NEXT_PUBLIC_` name.
+- [ ] No custom bell, notifications collection or polling code was added.
+- [ ] The app's docs say where notifications are sent from and which two variables a deployment needs.
+
+## When it does not work
+
+| What you see | Cause |
+|---|---|
+| `pnpm add` answers 404 | The package is not published, or the registry is not npm's. Stop and tell the user. |
+| The bell's calls answer `503 unavailable` | The key or the address is missing or wrong, or `resolvePerson` threw. The server log has the real error after `[communication-inbox]`. On Amplify, the two `amplify.yml` lines are usually what is missing. |
+| The bell's calls answer `401 not_signed_in` while signed in | `resolvePerson` returned `null`: the session is not read in the route. |
+| The bell's calls return HTML, or the bell never shows a count | The middleware redirects the route to a login page. Exclude `/api/communication/inbox`. |
+| A send throws `channel_unavailable` | The in-app channel is not switched on for the tenant, or `IN_APP_CHANNEL` is not the key that `channels.list()` named. |
+| A send throws `forbidden` | The key lacks a scope. Ask for a new key. |
+| The message is delivered but the bell is empty | The `personId` sent to differs from what `resolvePerson` returns, or the key used for sending sits in another sub-tenant than the key the route uses. Use one key and `personIdOf` on both sides. |
+| `notify` answers `false` and nothing is logged | The message was refused by the person's own choice: they switched this app's notifications off in the bell's preferences. This is correct. |
+| The list inside the bell looks unstyled | The stylesheet import of Step 6 is missing. |
+| An error says `MantineProvider` was not found | The bell is rendered outside `MantineProvider`. |
+
+## Reference
+
+`references/inbox-contract.instructions.md`: every option of `InboxProvider` and `createInboxHandler`, the list of labels for translation, the six operations of the route with their answers and error codes, calling the inbox directly from server code, and what to do in an app without React or Mantine.

package/skills/add-pigeon-notifications/references/inbox-contract.instructions.md

@@ -0,0 +1,208 @@
+# Pigeon inbox: the full contract
+
+Read this when the steps in `SKILL.md` are not enough: translating the bell, placing the full list on a page of its own, reading the inbox from server code, or building a bell without React and Mantine.
+
+## Contents
+
+- [The package's entries](#the-packages-entries)
+- [`InboxProvider`, `NotificationBell`, `InboxFullList`](#inboxprovider-notificationbell-inboxfulllist)
+- [Labels](#labels)
+- [`createInboxHandler`](#createinboxhandler)
+- [The six operations of the route](#the-six-operations-of-the-route)
+- [Error codes](#error-codes)
+- [How the bell behaves](#how-the-bell-behaves)
+- [Reading the inbox from server code](#reading-the-inbox-from-server-code)
+- [An app without React or Mantine](#an-app-without-react-or-mantine)
+
+## The package's entries
+
+| Import | Runs | Holds |
+|---|---|---|
+| `@xtremax/pigeon/client` | server | `createCommunicationClient`, `CommunicationError` |
+| `@xtremax/pigeon/inbox` | server | `createInboxHandler`, `createInboxClient` |
+| `@xtremax/pigeon/inbox-react` | browser | `InboxProvider`, `NotificationBell`, `InboxFullList`, `DEFAULT_INBOX_LABELS` |
+| `@xtremax/pigeon/inbox-react/styles.css` | browser | the bell's stylesheet |
+| `@xtremax/pigeon/events` | server | `createEventHandler`, `verifyEventSignature` (delivery events; not needed for the bell) |
+| `@xtremax/pigeon` | server | all server entries, plus `deriveIdempotencyKey`, `newIdempotencyKey` |
+
+The server entries hold the key. Imported into a browser bundle they resolve to a stub that throws `server_only`. `inbox-react` holds no key and calls only the app's own route.
+
+The names in the code say `Communication` (`createCommunicationClient`, `COMMUNICATION_API_KEY`). That is Pigeon's name on the Buildpad platform, where it is the Communication connector. It is the same service.
+
+## `InboxProvider`, `NotificationBell`, `InboxFullList`
+
+`InboxProvider` props, all optional:
+
+| Prop | Default | Use |
+|---|---|---|
+| `apiBase` | `/api/communication/inbox` | Where the app mounted the route. A path on the app's own origin only: an absolute URL is refused. |
+| `labels` | English | Replaces any visible or spoken text. See [Labels](#labels). |
+| `locale` | the browser's | Formats times, for example `'id'` or `'en-GB'`. |
+| `onViewAll` | opens the full list in a dialog | Call your router to open a page of your own instead. |
+| `onOpenPreferences` | opens the preference dialog | Open a settings page of your own instead. |
+| `openLink` | a new tab, `noopener,noreferrer` | Open a notification's link your own way, for example in the same tab. |
+
+`labels` is a plain object, so it can be passed from a server component. The three callbacks are functions: to use one, render `InboxProvider` from a client component (`'use client'`).
+
+`NotificationBell` takes `size` (pixels, never under 44). It must be inside `InboxProvider`.
+
+`InboxFullList` is the full, paged list. Use it with `onViewAll` to give notifications a page of their own. It needs an `InboxProvider` above it, so put the provider around the whole signed-in layout: the header's bell and the page's list then share one, and the count is asked for once.
+
+```tsx
+'use client';
+import { InboxFullList, InboxProvider, NotificationBell } from '@xtremax/pigeon/inbox-react';
+import { useRouter } from 'next/navigation';
+
+// around the signed-in layout: the header with the bell, and the pages
+const router = useRouter();
+<InboxProvider onViewAll={() => router.push('/notifications')}>
+  <header><NotificationBell /></header>
+  {children}
+</InboxProvider>
+
+// on app/(authenticated)/notifications/page.tsx
+<InboxFullList maxHeight="70vh" />
+```
+
+## Labels
+
+Pass any of these in `labels`. `{n}` and `{label}` are filled in.
+
+| Key | English default |
+|---|---|
+| `bell` | Notifications |
+| `bellWithCount` | {label}, {n} unread |
+| `heading` | Notifications |
+| `tabAll` | All |
+| `tabUnread` | Unread |
+| `tabUnreadWithCount` | Unread ({n}) |
+| `markAllRead` | Mark all as read |
+| `viewAll` | View all |
+| `preferences` | Notification preferences |
+| `emptyAll` | You have no notifications. |
+| `emptyUnread` | You have no unread notifications. |
+| `loading` | Loading notifications |
+| `loadError` | Notifications could not be loaded. |
+| `retry` | Try again |
+| `actionError` | That did not work. Try again. |
+| `dismiss` | Dismiss |
+| `close` | Close |
+| `unread` | Unread |
+| `announcement` | Announcement |
+| `loadMore` | Show older notifications |
+| `newOne` | 1 new notification |
+| `newMany` | {n} new notifications |
+| `fullListTitle` | All notifications |
+| `preferencesTitle` | Notification preferences |
+| `preferenceToggle` | Receive in-app notifications |
+| `preferenceOn` | New notifications from this app appear here. |
+| `preferenceOff` | New notifications from this app do not appear here. The ones you already have stay. Other apps are not affected. |
+| `preferenceLoadError` | Your preference could not be loaded. |
+| `preferenceSaveError` | Your choice was not saved. Try again. |
+
+The titles and bodies of notifications are not labels: they are written by whoever sent them, in the language they chose.
+
+## `createInboxHandler`
+
+```ts
+createInboxHandler(options): (request: Request) => Promise<Response>
+```
+
+| Option | Default | Use |
+|---|---|---|
+| `resolvePerson` (required) | | `(request) => string \| null`, sync or async. The signed-in person's id from the app's own session. `null` or an empty string means nobody. At most 128 characters. |
+| `client` | made on the first request from `COMMUNICATION_API_KEY` and `COMMUNICATION_URL` | Pass `createInboxClient({ apiKey, baseUrl })` to use other settings. |
+| `basePath` | `/api/communication/inbox` | Set it when the route file is somewhere else. It must match `apiBase` on `InboxProvider`. |
+| `allowedOrigins` | the request's own origin | Origins that may send `POST` and `PUT`. Needed only when pages are served from another origin than the route. |
+| `timeoutMs` | 8000 | Bounds each call to Pigeon. |
+| `onError` | | Told about every failure answered as `unavailable`. Log it: the browser is never told the cause. |
+
+The handler takes a standard `Request` and answers a standard `Response`, so it works in any server that speaks the Fetch API, not only Next.js. Export it for `GET`, `POST` and `PUT`.
+
+## The six operations of the route
+
+All paths are under the base path. Every answer is JSON with `Cache-Control: no-store`. A success is `{ "data": ... }`; a failure is `{ "error": { "code", "message", "field"? } }`.
+
+| Method and path | Request | `data` in the answer |
+|---|---|---|
+| `GET /summary` | | `{ unreadCount, newestUnreadAt, pollSeconds }` |
+| `GET /notifications` | query `limit` (1 to 100, default 20), `cursor`, `unread=true` | `{ notifications: [...], nextCursor, unreadCount }` |
+| `POST /notifications/{id}/read` | empty JSON body | `{ notification, unreadCount }` |
+| `POST /read-all` | `{ "upTo"?: ISO time }` | `{ marked, remaining, unreadCount }`; call again while `remaining > 0` |
+| `GET /preference` | | `{ state, changedAt, delivers }` |
+| `PUT /preference` | `{ "state": "opted_in" \| "opted_out" }` | `{ state, changedAt, delivers }` |
+
+A notification:
+
+```ts
+interface InboxNotification {
+  id: string;
+  kind: 'notification' | 'announcement';
+  title: string;            // plain text; never render it as markup
+  body: string;             // plain text
+  link: string | null;      // absolute https, or null
+  source: { type: 'xapp' | 'tenant'; name: string };
+  createdAt: string;        // ISO time
+  read: boolean;
+  readAt: string | null;
+}
+```
+
+- `nextCursor` is `null` on the last page. Pass it back as `cursor` unchanged.
+- `state` is `opted_in`, `opted_out` or `not_set`; `delivers` says whether new notifications reach the person now.
+- `POST` and `PUT` must come from the app's own pages: the handler checks `Sec-Fetch-Site: same-origin` or the `Origin` header.
+
+## Error codes
+
+| Code | Status | Meaning |
+|---|---|---|
+| `not_signed_in` | 401 | `resolvePerson` returned nobody. The bell stops asking, silently. |
+| `not_permitted` | 403 | A `POST` or `PUT` from another origin, or Pigeon refused the key for this call. |
+| `not_found` | 404 | No such operation, or a notification that is not this person's or not this app's. |
+| `invalid_input` | 422 | A value from the browser was refused; `field` names it. |
+| `rate_limited` | 429 | Too many calls. |
+| `unavailable` | 503 | Everything else: a wrong or revoked key, a timeout, Pigeon not reachable. The cause goes to `onError` only. |
+
+Errors thrown by `createCommunicationClient` and `createInboxClient` are `CommunicationError` with `code`, `status`, `requestId` and `retryable`. Codes you may meet when sending: `channel_unavailable`, `validation_failed` (a missing or too long variable, an unknown template), `forbidden`, `invalid_credentials`, `rate_limited`, `idempotency_conflict`, `not_configured`, `timeout`, `network_error`.
+
+## How the bell behaves
+
+- **Updates.** It asks for the count every 60 seconds (Pigeon's setting, never under 15). It pauses while the page is hidden and asks at once when it is visible again. After failures it waits longer, up to 5 minutes. There is no realtime push.
+- **Outage.** It keeps the last count and the page keeps working. A list that cannot load shows "Try again".
+- **Selecting a notification** marks it read, and opens its link when it has an `https` one.
+- **"Mark all as read"** covers what this bell shows, never another app's notifications.
+- **Announcements** are one copy per person: read in one app's bell, they are read in every bell.
+- **The preference** is this app's own. Switching it off stops this app's notifications for the person; other apps and announcements go on.
+- **Nothing is kept in the browser's storage.**
+
+## Reading the inbox from server code
+
+For a count in a server-rendered page, a digest email or a test. Each call takes the person id first.
+
+```ts
+import { createInboxClient } from '@xtremax/pigeon/inbox';
+import { communication } from '@/lib/communication/client';
+
+const inbox = createInboxClient(communication()); // shares the key and settings
+
+const { unreadCount } = await inbox.summary(personId);
+const page = await inbox.list(personId, { limit: 20, unreadOnly: true });
+await inbox.markRead(personId, page.notifications[0].id);
+await inbox.markAllRead(personId);
+const preference = await inbox.getPreference(personId);
+await inbox.setPreference(personId, 'opted_out');
+```
+
+These throw `CommunicationError` on failure. The person id here is trusted, so it must come from your own session or data, never from a request.
+
+## An app without React or Mantine
+
+The route is the same: mount `createInboxHandler` on a catch-all route of the app's server. Then build the bell with the app's own components against the six operations above:
+
+1. Ask `GET /summary` when the page loads, then every `pollSeconds`. Stop on `401`. Wait longer after a failure.
+2. Show `unreadCount` on the bell (`99+` above 99).
+3. On open, `GET /notifications`. Show `title` and `body` as text. Offer `nextCursor` as "show older".
+4. On select, `POST /notifications/{id}/read`, and open `link` in a new tab with `noopener,noreferrer` only when it starts with `https://`.
+5. Offer "mark all as read" (`POST /read-all`, repeated while `remaining > 0`) and the on/off choice (`GET` and `PUT /preference`).
+
+Send requests with `credentials: 'same-origin'`. Never call Pigeon from the browser and never put the key in the page.