@xtremax/pigeon 0.3.1 → 0.4.0

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.

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

@@ -22,10 +22,12 @@ Read this when the steps in `SKILL.md` are not enough: translating the bell, pla
 | `@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/preferences` | server | `createPreferencesHandler`, `createPreferencesClient` (see `consent.instructions.md`) |
+| `@xtremax/pigeon/preferences-react` | browser | `NotificationPreferences`, `DEFAULT_PREFERENCE_LABELS` |
 | `@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 server entries hold the key. Imported into a browser bundle they resolve to a stub that throws `server_only`. `inbox-react` and `preferences-react` hold no key and call only the app's own routes.
 
 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.