@xtremax/pigeon 0.3.0 → 0.4.0

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

@@ -0,0 +1,337 @@
+---
+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. Also use it for notification settings, opt-in and opt-out, unsubscribe and consent for messages sent through Pigeon. Do not build a custom bell, a notifications table, polling code or a local consent flag - 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` |
+| A settings page, if the app has one | a route and one component | `@xtremax/pigeon/preferences`, `@xtremax/pigeon/preferences-react` |
+| 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 7).
+7. **Pigeon decides who may be messaged, not the app.** Keep no opt-in or opt-out flag in the app and do not check one before sending (see "Consent" below).
+
+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.4.0 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: Who the person is
+
+```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.
+
+And one function that says who is signed in. Every route of this skill uses it:
+
+```ts
+// lib/communication/session.ts
+import { personIdOf } from './person';
+import { createClient } from '@/lib/supabase/server';
+
+/** Who is signed in, from this app's own session. null means nobody. Never read a person from the request. */
+export async function resolvePerson(): Promise<string | null> {
+  const supabase = await createClient();
+  const { data } = await supabase.auth.getUser();
+  return data.user?.email ? personIdOf(data.user.email) : null;
+}
+```
+
+`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.
+
+## 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 { resolvePerson } from '@/lib/communication/session';
+
+export const dynamic = 'force-dynamic';
+
+const handler = createInboxHandler({
+  resolvePerson,
+  // 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 };
+```
+
+- 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.
+
+## Consent
+
+A person can switch notifications off, and Pigeon enforces it. For in-app notifications this is **already done** when the steps above are done:
+
+- The bell has "Notification preferences", where a person switches **this app's** notifications off or on. Other apps and the organisation's announcements are not affected.
+- When it is off, `notify` answers `false` and nothing arrives. That is the person's choice, not a failure: do not retry, do not send by another route, do not tell the person who triggered it.
+
+What the app must not do, because each of these breaks a choice the person made:
+
+- **No consent kept in the app**: no `notifications_enabled` column, no settings collection for it, no cached copy. Pigeon is where the choice lives, so it also holds when the person changes it somewhere else.
+- **No check before sending.** Send, and let Pigeon refuse.
+- **No switching a person back on for them**, and no pre-ticked box.
+
+Read `references/consent.instructions.md` before you build any of these. It has the code and the wording:
+
+- a **notification settings page** (email, WhatsApp and in-app switches in one place): the package has the route and the component, `createPreferencesHandler` and `NotificationPreferences`, so it is two short files;
+- sending **email or WhatsApp** through Pigeon as well, where choices cover every app of the organisation and WhatsApp needs an explicit opt-in;
+- **collecting a phone number**, importing people, or recording a choice on someone's behalf;
+- messages that **must always arrive** (receipts, security alerts);
+- **erasing** a person.
+
+## 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, and no field or collection that stores an opt-in or opt-out.
+- [ ] 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/consent.instructions.md`: who decides whether a message goes out, the rules for an app, the defaults per medium, registering people and addresses, a settings page from the package's `createPreferencesHandler` and `NotificationPreferences` (options, labels and the route's contract), transactional templates and erasure.
+
+`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/consent.instructions.md

@@ -0,0 +1,263 @@
+# Consent: who may be messaged, and how an app takes part
+
+Read this when the app has a notification settings page, sends email or WhatsApp through Pigeon as well as in-app notifications, collects phone numbers, imports people, or has to erase a person.
+
+## Contents
+
+- [Who decides](#who-decides)
+- [The rules](#the-rules)
+- [What each medium does by default](#what-each-medium-does-by-default)
+- [What the package gives you, and what it does not](#what-the-package-gives-you-and-what-it-does-not)
+- [1. When a person joins](#1-when-a-person-joins)
+- [2. A settings page](#2-a-settings-page)
+- [3. Messages that must always arrive](#3-messages-that-must-always-arrive)
+- [4. Erasing a person](#4-erasing-a-person)
+- [Tests](#tests)
+
+## Who decides
+
+**Pigeon decides, for every message, whether it may go out.** It checks, in this order: the person was erased; the person is suspended; the address is suppressed (for example a hard bounce); the person opted out; the medium needs an opt-in that was not given; it is inside the person's quiet hours. The first that applies wins.
+
+The app has two jobs and no more:
+
+1. **Tell Pigeon what people chose**, when they choose it.
+2. **Show people their choices** and let them change them.
+
+The app never decides itself. This is what makes a choice hold in every app of the organisation: an opt-out recorded by one app stops the mail of all of them.
+
+## The rules
+
+1. **Keep no consent in the app.** No `email_opt_in` column, no `notification_settings` collection, no cached copy. Read it from Pigeon when you show it; record it in Pigeon when it changes. A local copy goes stale the moment the person unsubscribes from an email or changes it in another app.
+2. **Do not check before sending.** Send, and let Pigeon refuse. A refused message is not an error: `messages.send` answers a message whose `state` is `failed`, and `messages.get(id)` gives the reason, which starts `policy_refused.`. Do not show it to the person who triggered the send, and do not retry it.
+3. **Only the person records their own choice.** The route that records a choice reads the person from the signed-in session, never from the request. Recording for someone else (an import, a paper form) needs evidence of how they chose.
+4. **Never opt a person in for them.** No pre-ticked box, no "on" written at sign-up without a tick. With no choice recorded, Pigeon already does the right thing for each medium.
+5. **Say what a switch covers.** The email and WhatsApp choices cover **every app of the organisation**. The in-app choice covers **this app only**. The words beside each switch must say so (see the wording below).
+6. **Make switching off as easy as switching on.** Same page, same kind of control, no confirmation that argues.
+7. **Do not mark a message transactional to get round an opt-out.** That class is for messages a person must get: receipts, security alerts, password resets.
+
+## What each medium does by default
+
+| Medium | With no choice recorded | A choice covers | How a person changes it outside your app |
+|---|---|---|---|
+| Email | Sent | Every app of the organisation | The unsubscribe link in every email |
+| WhatsApp | **Not sent.** It needs an explicit opt-in, for every message, transactional ones too | Every app of the organisation | Texting STOP or START to the number |
+| In-app | Shown | This app only (its sub-tenant) | The preferences in the bell |
+
+An operator can set email to need an opt-in too; then email behaves like WhatsApp in the table. You do not have to know: `delivers` in a person's choices says whether a message reaches them now, and the settings component follows it.
+
+## What the package gives you, and what it does not
+
+| Piece | From | Does |
+|---|---|---|
+| `createPreferencesHandler` | `@xtremax/pigeon/preferences` (server) | The app's own route for a settings page: `GET` answers the signed-in person's choices, `PUT` records one, with evidence |
+| `NotificationPreferences` | `@xtremax/pigeon/preferences-react` (browser) | One switch per medium the app can send on, with a sentence that says what the switch covers |
+| The bell's preference dialog | `@xtremax/pigeon/inbox-react` | The in-app choice, with no code from you |
+| `preferences.get(personId)` | the client | Each medium's choice, and `delivers`: whether a message reaches the person now |
+| `preferences.record({ recipient, medium, state, expressedAt?, evidence? })` | the client | Records a choice. Creates the person if Pigeon has not met them |
+| `recipients.put(personId, { locale?, timezone?, quietHours? })` | the client | Creates or updates the person |
+| `recipients.putAddress(personId, { medium, address, primary?, verified? })` | the client | Stores an email address or a WhatsApp number (E.164) |
+| `recipients.get(personId)` | the client | The person and their masked addresses |
+| `messageClasses.put(templateKey, { class })` | the client | Marks a template `transactional` or `non_transactional` |
+| `recipients.delete(personId)` | the client | Erases the person's data, for the whole organisation |
+
+"The client" is `communication()` from `lib/communication/client.ts`; its calls are server-side only.
+
+**Not in the package**, so do not look for it: choices per topic ("product news" but not "weekly digest"). Pigeon knows one choice per medium. If the app wants topics, they are the app's own settings about *what it sends*, kept in the app, and they never replace the person's consent.
+
+## 1. When a person joins
+
+For in-app notifications alone, **do nothing**: sending to a `personId` is enough.
+
+Register the person only when the app sends them **email or WhatsApp** by `personId`, because Pigeon then needs an address on record. Do it after the sign-up itself has succeeded, and never let it fail the sign-up:
+
+```ts
+// lib/communication/recipients.ts
+import { communication } from './client';
+import { personIdOf } from './person';
+
+/** Tells Pigeon about a person and where to reach them. Never throws: a sign-up must not fail because of it. */
+export async function registerRecipient(person: { email: string; locale?: string; timezone?: string; whatsapp?: string }): Promise<void> {
+  const personId = personIdOf(person.email);
+  try {
+    const pigeon = communication();
+    // Only what you know: a field you leave out keeps the value another app may have set.
+    await pigeon.recipients.put(personId, { ...(person.locale ? { locale: person.locale } : {}), ...(person.timezone ? { timezone: person.timezone } : {}) });
+    // `verified` only for an address the person proved is theirs, such as the one they signed in with.
+    await pigeon.recipients.putAddress(personId, { medium: 'email', address: person.email, primary: true, verified: true });
+    if (person.whatsapp) await pigeon.recipients.putAddress(personId, { medium: 'whatsapp', address: person.whatsapp, primary: true });
+  } catch (error) {
+    console.error('[communication] recipient not registered:', error);
+  }
+}
+```
+
+Storing a WhatsApp number is not an opt-in. To message it, the person must have agreed, and Pigeon must have that on record with evidence. Ask where you collect the number, with a box that starts **unticked**, and record it only when it was ticked:
+
+```ts
+if (form.whatsappAgreed) {
+  await communication().preferences.record({
+    recipient: { personId: personIdOf(form.email) },
+    medium: 'whatsapp',
+    state: 'opted_in',
+    expressedAt: new Date().toISOString(),
+    evidence: { method: 'signup_form', wordingVersion: '2026-11', proofRef: submission.id },
+  });
+}
+```
+
+`evidence` is what you would show if asked "when did this person agree, and to what words": `method` (where they chose), `wordingVersion` (which text they saw; change it when the text changes), `proofRef` (your own record's id).
+
+An address that already belongs to another person is refused (`conflict`); a person may have at most 10.
+
+## 2. A settings page
+
+Two pieces, both from the package. Do not write the route or the switches yourself.
+
+**The route.** It uses the same `resolvePerson` as the inbox route:
+
+```ts
+// app/api/communication/preferences/route.ts
+import { createPreferencesHandler } from '@xtremax/pigeon/preferences';
+import { resolvePerson } from '@/lib/communication/session';
+
+export const dynamic = 'force-dynamic';
+
+const handler = createPreferencesHandler({
+  resolvePerson,
+  // Recorded with every choice. Change the version whenever the text beside the switches changes.
+  evidence: { wordingVersion: '2026-11' },
+  onError: (error) => console.error('[communication-preferences]', error),
+});
+
+export { handler as GET, handler as PUT };
+```
+
+**The switches.** Put the component on the app's settings page, inside `MantineProvider`:
+
+```tsx
+// app/(authenticated)/settings/notifications/page.tsx
+import { Stack, Title } from '@mantine/core';
+import { NotificationPreferences } from '@xtremax/pigeon/preferences-react';
+
+export default function NotificationSettingsPage() {
+  return (
+    <Stack gap="md" maw={560}>
+      <Title order={2}>Notifications</Title>
+      <NotificationPreferences />
+    </Stack>
+  );
+}
+```
+
+That is the whole settings page. What it does:
+
+- It shows a switch for each medium **the app can send on** (Pigeon says which), so an app with no WhatsApp channel shows no WhatsApp switch.
+- A switch shows what is **recorded**: it moves when the choice is saved, not before. A failure says so.
+- Each switch has a sentence that says what it covers: email and WhatsApp "every app of your organisation", in-app "this app".
+- With no choice recorded, email and in-app are on and WhatsApp is off. If an operator made email need an opt-in, the switch follows.
+- The in-app switch is the same choice as the one in the bell.
+
+The component's switches are Mantine's, inside the package. That is not app code, so the Buildpad-First rule does not apply to it; do not rebuild it with the Buildpad `Toggle`. If the page needs a layout of its own, build that page against the route's contract below, and there use the Buildpad `Toggle`.
+
+`createPreferencesHandler` options:
+
+| Option | Default | Use |
+|---|---|---|
+| `resolvePerson` (required) | | The signed-in person's id from the app's own session, or `null` |
+| `client` | made on the first request from `COMMUNICATION_API_KEY` and `COMMUNICATION_URL` | `createPreferencesClient(...)` with other settings |
+| `basePath` | `/api/communication/preferences` | Where the route is mounted. Must match the component's `apiBase` |
+| `mediums` | all three | The media a person may see and change through this route, for example `['email', 'in_app']` |
+| `evidence` | `{ method: 'settings_page' }` | `method` and `wordingVersion`, recorded with every choice |
+| `allowedOrigins` | the request's own origin | Origins that may send `PUT` |
+| `timeoutMs` | 8000 | Bounds each call to Pigeon |
+| `onError` | | Told about every failure answered as `unavailable` |
+
+`NotificationPreferences` props, all optional:
+
+| Prop | Default | Use |
+|---|---|---|
+| `apiBase` | `/api/communication/preferences` | A path on the app's own origin |
+| `labels` | English | Replaces any text. See below |
+| `mediums` | the media the app can send on | Which switches to show, in this order |
+| `onChange` | | Called with the saved choice, for example to show a toast. Needs a client component |
+
+Labels, for another language. Translate the words and keep what each sentence says about scope. The component picks the sentence from what Pigeon says the choice covers: today email and WhatsApp choices cover the whole organisation, and the `...App` sentences are shown only if Pigeon answers that a choice covers this app alone.
+
+| Key | English default |
+|---|---|
+| `group` | Notification preferences |
+| `email` | Email |
+| `emailOn` | You receive email from every app of your organisation. |
+| `emailOff` | You receive no email from any app of your organisation, except messages you must get, such as receipts and security alerts. |
+| `emailOnApp` | You receive email from this app. |
+| `emailOffApp` | You receive no email from this app, except messages you must get, such as receipts and security alerts. Other apps are not affected. |
+| `whatsapp` | WhatsApp |
+| `whatsappOn` | You receive WhatsApp messages from every app of your organisation. |
+| `whatsappOff` | You receive no WhatsApp messages from any app of your organisation. |
+| `whatsappOnApp` | You receive WhatsApp messages from this app. |
+| `whatsappOffApp` | You receive no WhatsApp messages from this app. Other apps are not affected. |
+| `inApp` | Notifications in this app |
+| `inAppOn` | New notifications from this app appear under the bell. |
+| `inAppOff` | New notifications from this app do not appear. The ones you already have stay. Other apps are not affected. |
+| `loading` | Loading your notification preferences |
+| `loadError` | Your notification preferences could not be loaded. |
+| `retry` | Try again |
+| `saveError` | Your choice was not saved. Try again. |
+| `none` | There is nothing to choose here yet. |
+
+The route's contract, for a page of your own. Answers are JSON with `Cache-Control: no-store`; failures use the same six codes as the inbox route.
+
+| Method | Request | `data` in the answer |
+|---|---|---|
+| `GET` | | `{ preferences: [...] }` |
+| `PUT` | `{ "medium": "email" \| "whatsapp" \| "in_app", "state": "opted_in" \| "opted_out" }` | `{ preferences: [...] }`, as they are afterwards |
+
+```ts
+interface PreferenceChoice {
+  medium: 'email' | 'whatsapp' | 'in_app';
+  state: 'opted_in' | 'opted_out' | 'not_set';
+  changedAt: string | null;
+  delivers: boolean;        // whether a message on this medium reaches the person now
+  covers: 'tenant' | 'app'; // tenant: every app of the organisation; app: this app only
+  available: boolean;       // whether this app can send on the medium
+}
+```
+
+To read a person's choices in server code (never to decide whether to send):
+
+```ts
+const choices = await communication().preferences.get(personId);
+const emailArrives = choices.find((choice) => choice.medium === 'email')?.delivers ?? false;
+```
+
+- In an app with a `[lang]` segment, the route still lives at `app/api/...`.
+- Check the middleware lets `/api/communication/preferences` answer its own `401` JSON, as for the inbox route.
+- If the route answers `503` and the server log shows `not_found`, the Pigeon deployment is older than the package: it has no `GET /preferences` yet. Tell the user; do not work around it.
+
+## 3. Messages that must always arrive
+
+By default every template is `non_transactional`: an opt-out stops it. For a receipt, a security alert or a password reset, mark the template once (a one-off script or a deploy step, not on every send):
+
+```ts
+await communication().messageClasses.put('order.receipt', { class: 'transactional', note: 'Order receipts' });
+```
+
+- A transactional email is sent to a person who opted out, and is not held by quiet hours.
+- It changes nothing on WhatsApp, which needs an opt-in for every message.
+- A suppressed address, a suspended person and an erased person are still not messaged.
+- Ask the user which templates qualify. Do not decide it yourself, and never mark `generic.notification`.
+
+## 4. Erasing a person
+
+```ts
+await communication().recipients.delete(personId);
+```
+
+This erases the person's data in Pigeon **for the whole organisation, for good**: every app loses the ability to message them. Use it only for a real erasure request, and only after the user has confirmed. It is not what you call when a person merely leaves this app or switches notifications off.
+
+## Tests
+
+- **Playwright, signed out:** `GET /api/communication/preferences` answers `401`; a `PUT` with `origin: https://evil.example` answers `403`.
+- **Playwright, signed in:** the settings page shows the switches (`getByRole('switch', { name: 'Email' })` inside `getByRole('group', { name: 'Notification preferences' })`); switching one off shows its "off" sentence and survives a reload. Wait for the `PUT` to answer before you assert: the switch moves only when the choice is saved.
+- **Vitest, `registerRecipient`** with `./client` mocked: it never throws, and it sends no `locale` or `timezone` it was not given.
+- **A grep:** no column, field or collection in the app that stores an opt-in or opt-out.