@xtremax/pigeon 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.0
+- New entry `@xtremax/pigeon/preferences` (server only): `createPreferencesHandler`, the app's own route for a notification settings page (`GET` answers the signed-in person's choices, `PUT` records one with evidence), and `createPreferencesClient`.
+- New entry `@xtremax/pigeon/preferences-react`: `NotificationPreferences`, one switch per medium the app can send on, with a sentence that says what each switch covers. It needs React 19 and Mantine 8, and no stylesheet.
+- `communication.preferences.get(personId)`: each medium's choice, whether a message reaches the person now (`delivers`), what the choice covers and whether the app can send on the medium. It needs a Pigeon deployment that has `GET /preferences`.
+- `communication.preferences.record` answers a typed result.
+- The skill covers consent: what an app must and must not do, the defaults per medium, registering people and addresses, the settings page, transactional templates and erasure. New file `skills/add-pigeon-notifications/references/consent.instructions.md`.
+- No change to existing calls.
+
+## 0.3.1
+- The package carries its agent skill, `skills/add-pigeon-notifications/`: the steps a coding agent follows to add the bell and the sending code to an app.
+- New command `npx @xtremax/pigeon add-skill`: copies the skill into the project's `.claude/skills/`, and into `.kiro/skills/` when the project has a `.kiro` folder. Run it again after an upgrade to get the new version's skill. `--check` says what would change.
+- No change to the library.
+
 ## 0.3.0
 - The package is named `@xtremax/pigeon`. Earlier versions were called `@xtremax/communication` and were never published. Only the import path changes: function names, environment variables and headers are the same.
 - New entry `@xtremax/pigeon/inbox-react`: the notification bell (`InboxProvider`, `NotificationBell`, `InboxFullList`), with its stylesheet at `@xtremax/pigeon/inbox-react/styles.css`. It replaces the files that were copied into each app. React 19, Mantine 8 and `@tabler/icons-react` are optional peer dependencies.

package/README.md

@@ -54,4 +54,43 @@ import '@xtremax/pigeon/inbox-react/styles.css'; // once, after Mantine's styles
 - **Direct calls:** `createInboxClient()` has `summary`, `list`, `markRead`, `markAllRead`, `getPreference` and `setPreference`, each taking the person id first.
 - **What a key sees:** what its own sub-tenant (or the tenant level, for a key outside any) sent the person, and the tenant's announcements. Another app's notifications are not part of it, and the on/off preference is this app's own. `ping()` returns the key's `subKey`.
 
-Entry points: `/client`, `/inbox`, `/events` and `/contract` (types only) for the server; `/inbox-react` and `/inbox-react/styles.css` for the browser. Node 20 or later. Below 1.0 a breaking change raises the minor version.
+## Notification settings
+
+A person's choices for email, WhatsApp and in-app notifications, on a settings page of your app. Pigeon keeps the choices and decides for every message; your app keeps nothing. Two pieces again:
+
+```ts
+// app/api/communication/preferences/route.ts
+import { createPreferencesHandler } from '@xtremax/pigeon/preferences';
+
+const handler = createPreferencesHandler({
+  resolvePerson: async () => (await currentUser())?.email ?? null, // your own session
+  evidence: { wordingVersion: '2026-11' },                          // recorded with every choice
+});
+export { handler as GET, handler as PUT };
+```
+
+```tsx
+// on your settings page
+import { NotificationPreferences } from '@xtremax/pigeon/preferences-react';
+
+<NotificationPreferences />
+```
+
+- **It shows a switch for each medium your app can send on**, and each switch shows what is recorded: it moves when the choice is saved.
+- **The sentences say what a switch covers:** email and WhatsApp hold in every app of the organisation, in-app in this app only. Pass `labels` to translate, `mediums` to choose which switches to show.
+- **In server code,** `communication.preferences.get(personId)` answers each medium's choice with `delivers`: whether a message reaches the person now. Do not use it to decide whether to send: send, and Pigeon refuses when it must.
+- **Do not keep consent in your app.** No opt-in column, no cached copy.
+
+## For AI coding agents
+
+The package carries a skill that tells a coding agent (Claude Code, Kiro and others that read `SKILL.md`) how to add the bell and the sending code to an app, step by step, with tests and a troubleshooting table.
+
+```bash
+npx @xtremax/pigeon add-skill
+```
+
+It copies `add-pigeon-notifications` into the project's `.claude/skills/`, and into `.kiro/skills/` when the project has a `.kiro` folder (`--kiro` forces it, `--dir` names another project folder, `--check` changes nothing and says what would change). Then ask the agent to "add a notification bell", or run `/add-pigeon-notifications`. Run the command again after upgrading the package: the skill's files are replaced with the new version's.
+
+An agent that has not been given the skill can read it in place: `node_modules/@xtremax/pigeon/skills/add-pigeon-notifications/SKILL.md`.
+
+Entry points: `/client`, `/inbox`, `/preferences`, `/events` and `/contract` (types only) for the server; `/inbox-react`, `/inbox-react/styles.css` and `/preferences-react` for the browser. Node 20 or later. Below 1.0 a breaking change raises the minor version.

package/bin/pigeon.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// The package's command line. One job: put the agent skills that ship with the package where a coding agent finds them.
+//
+//   npx @xtremax/pigeon add-skill            copy the skills into this project
+//   npx @xtremax/pigeon add-skill --check    say what would change, and change nothing
+//   npx @xtremax/pigeon add-skill --dir app  another project folder
+//
+// The skills go to .claude/skills/ always, and to .kiro/skills/ when the project has a .kiro folder (or with --kiro).
+// Run it again after upgrading the package: it replaces the skill's files with the new version's.
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const skillsRoot = join(packageRoot, 'skills');
+const { name, version } = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+
+const USAGE = `${name} ${version}
+
+Usage:
+  npx ${name} add-skill [--dir <project folder>] [--kiro] [--check]
+
+  add-skill   Copy the agent skills of this package into the project:
+              .claude/skills/<skill>/, and .kiro/skills/<skill>/ when the project has a .kiro folder.
+  --dir       The project folder. Default: the current folder.
+  --kiro      Also write .kiro/skills/ when the project has no .kiro folder yet.
+  --check     Say what would change and change nothing. Exits 1 when something would.
+`;
+
+function fail(message) {
+  process.stderr.write(`${message}\n\n${USAGE}`);
+  process.exit(2);
+}
+
+/** Every file under a folder, as paths relative to it. */
+function filesOf(dir, base = dir) {
+  return readdirSync(dir).flatMap((entry) => {
+    const path = join(dir, entry);
+    return statSync(path).isDirectory() ? filesOf(path, base) : [relative(base, path)];
+  });
+}
+
+function addSkill(args) {
+  let dir = process.cwd();
+  let kiro = false;
+  let check = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--dir') {
+      const value = args[(i += 1)];
+      if (!value) fail('--dir needs a folder.');
+      dir = resolve(value);
+    } else if (arg === '--kiro') kiro = true;
+    else if (arg === '--check') check = true;
+    else fail(`Unknown option: ${arg}`);
+  }
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) fail(`Not a folder: ${dir}`);
+  // A project, not any folder: writing skills into the wrong place helps nobody.
+  if (!existsSync(join(dir, 'package.json'))) fail(`No package.json in ${dir}. Run this in the project's folder, or pass --dir.`);
+
+  const skills = readdirSync(skillsRoot).filter((entry) => existsSync(join(skillsRoot, entry, 'SKILL.md')));
+  const homes = ['.claude/skills', ...(kiro || existsSync(join(dir, '.kiro')) ? ['.kiro/skills'] : [])];
+  const counts = { added: 0, updated: 0, same: 0 };
+
+  for (const home of homes) {
+    for (const skill of skills) {
+      for (const file of filesOf(join(skillsRoot, skill))) {
+        const content = readFileSync(join(skillsRoot, skill, file));
+        const target = join(dir, home, skill, file);
+        const state = !existsSync(target) ? 'added' : readFileSync(target).equals(content) ? 'same' : 'updated';
+        counts[state] += 1;
+        if (state === 'same') continue;
+        process.stdout.write(`${check ? `would be ${state}` : state}: ${join(home, skill, file)}\n`);
+        if (check) continue;
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, content);
+      }
+    }
+  }
+
+  const changed = counts.added + counts.updated;
+  if (changed === 0) process.stdout.write(`Up to date: ${skills.join(', ')} (${name} ${version}) in ${homes.join(' and ')}.\n`);
+  else if (check) process.stdout.write(`${changed} file(s) would change. Run without --check to write them.\n`);
+  else process.stdout.write(`\nDone: ${skills.join(', ')} (${name} ${version}) in ${homes.join(' and ')}.\nAsk your coding agent to "add a notification bell", or run /${skills[0]}.\n`);
+  process.exit(check && changed > 0 ? 1 : 0);
+}
+
+const [command, ...rest] = process.argv.slice(2);
+if (command === 'add-skill') addSkill(rest);
+else if (command === undefined || command === 'help' || command === '--help' || command === '-h') process.stdout.write(USAGE);
+else if (command === '--version' || command === '-v') process.stdout.write(`${version}\n`);
+else fail(`Unknown command: ${command}`);

package/dist/cjs/client.js

@@ -4,6 +4,7 @@ exports.CommunicationError = exports.TRANSPORT = void 0;
 exports.createCommunicationClient = createCommunicationClient;
 const errors_1 = require("./errors");
 const idempotency_1 = require("./idempotency");
+const person_1 = require("./person");
 const retry_1 = require("./retry");
 /** Where a client keeps its transport, so `@xtremax/pigeon/inbox` can reuse the key handling, retries and errors. */
 exports.TRANSPORT = Symbol.for('@xtremax/pigeon.transport');
@@ -97,6 +98,8 @@ function createCommunicationClient(options = {}) {
             },
         },
         preferences: {
+            /** A person's choice for each medium, and whether a message reaches them now. Someone Pigeon has not met has made no choice. */
+            get: (personId) => request('GET', '/preferences', undefined, { headers: { 'X-Communication-Person': (0, person_1.personHeader)(personId) } }).then((r) => r.data.preferences),
             record: (body) => request('POST', '/preferences', body).then((r) => r.data),
         },
         messageClasses: {

package/dist/cjs/inbox/client.js

@@ -1,15 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.personHeader = personHeader;
+exports.personHeader = void 0;
 exports.createInboxClient = createInboxClient;
 const client_1 = require("../client");
-/** `X-Communication-Person` is base64url of the UTF-8 person id, so any identifier travels safely in a header. */
-function personHeader(personId) {
-    let binary = '';
-    for (const byte of new TextEncoder().encode(personId))
-        binary += String.fromCharCode(byte);
-    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-}
+const person_1 = require("../person");
+Object.defineProperty(exports, "personHeader", { enumerable: true, get: function () { return person_1.personHeader; } });
 const isClient = (v) => client_1.TRANSPORT in v;
 /**
  * The in-app inbox of one person. Pass an existing client to share its key and settings, or the same options as
@@ -17,7 +12,7 @@ const isClient = (v) => client_1.TRANSPORT in v;
  */
 function createInboxClient(client = {}) {
     const request = (isClient(client) ? client : (0, client_1.createCommunicationClient)(client))[client_1.TRANSPORT];
-    const call = (method, path, personId, body, read, options = {}) => request(method, path, body, { headers: { 'X-Communication-Person': personHeader(personId) }, retry: options.retry ?? read, timeoutMs: options.timeoutMs }).then((r) => r.data);
+    const call = (method, path, personId, body, read, options = {}) => request(method, path, body, { headers: { 'X-Communication-Person': (0, person_1.personHeader)(personId) }, retry: options.retry ?? read, timeoutMs: options.timeoutMs }).then((r) => r.data);
     return {
         summary: (personId, options) => call('GET', '/inbox/summary', personId, undefined, true, options),
         list(personId, query = {}, options) {

package/dist/cjs/person.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.personHeader = personHeader;
+/** `X-Communication-Person` is base64url of the UTF-8 person id, so any identifier travels safely in a header. */
+function personHeader(personId) {
+    let binary = '';
+    for (const byte of new TextEncoder().encode(personId))
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}

package/dist/cjs/preferences/browser-stub.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPreferencesHandler = exports.createPreferencesClient = void 0;
+const errors_1 = require("../errors");
+const serverOnly = () => {
+    throw new errors_1.CommunicationError({ code: 'server_only', message: 'The Communication preferences client holds a secret key and must run on the server.' });
+};
+/** Selected by the `browser` export condition: this entry never reaches client code. The component talks to the host's own route instead. */
+exports.createPreferencesClient = serverOnly;
+exports.createPreferencesHandler = serverOnly;

package/dist/cjs/preferences/client.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPreferencesClient = createPreferencesClient;
+const client_1 = require("../client");
+const person_1 = require("../person");
+const isClient = (v) => client_1.TRANSPORT in v;
+/**
+ * Pass an existing client to share its key and settings, or the same options as `createCommunicationClient`.
+ * The key needs the scopes `recipients:read` and `consent:write`.
+ */
+function createPreferencesClient(client = {}) {
+    const request = (isClient(client) ? client : (0, client_1.createCommunicationClient)(client))[client_1.TRANSPORT];
+    const get = (personId, options = {}) => request('GET', '/preferences', undefined, { headers: { 'X-Communication-Person': (0, person_1.personHeader)(personId) }, retry: options.retry ?? true, timeoutMs: options.timeoutMs }).then((r) => r.data.preferences);
+    return {
+        get,
+        async set(personId, medium, state, evidence, options = {}) {
+            await request('POST', '/preferences', { recipient: { personId }, medium, state, expressedAt: new Date().toISOString(), ...(evidence ? { evidence } : {}) }, { retry: options.retry ?? false, timeoutMs: options.timeoutMs });
+            return get(personId, options);
+        },
+    };
+}

package/dist/cjs/preferences/handler.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREFERENCE_MEDIUMS = void 0;
+exports.createPreferencesHandler = createPreferencesHandler;
+const errors_1 = require("../inbox/errors");
+const origin_1 = require("../inbox/origin");
+const validate_1 = require("../inbox/validate");
+const client_1 = require("./client");
+exports.PREFERENCE_MEDIUMS = ['email', 'whatsapp', 'in_app'];
+/** Allowlist projection: only the documented fields leave the host. A value of the wrong shape gives `null`. */
+function projectChoice(v) {
+    if (typeof v !== 'object' || v === null)
+        return null;
+    const o = v;
+    const medium = exports.PREFERENCE_MEDIUMS.find((m) => m === o.medium);
+    if (!medium)
+        return null;
+    if (o.state !== 'opted_in' && o.state !== 'opted_out' && o.state !== 'not_set')
+        return null;
+    if (o.changedAt !== null && typeof o.changedAt !== 'string')
+        return null;
+    if (typeof o.delivers !== 'boolean' || typeof o.available !== 'boolean')
+        return null;
+    if (o.covers !== 'tenant' && o.covers !== 'app')
+        return null;
+    return { medium, state: o.state, changedAt: o.changedAt, delivers: o.delivers, covers: o.covers, available: o.available };
+}
+/**
+ * The host app's browser-facing route for a person's notification choices, in one tested function:
+ *
+ *   // app/api/communication/preferences/route.ts
+ *   const handler = createPreferencesHandler({ resolvePerson });
+ *   export { handler as GET, handler as PUT };
+ *
+ * `GET` answers the signed-in person's choices; `PUT` with `{ medium, state }` records one and answers them again.
+ * The person comes only from `resolvePerson`. A `PUT` from another origin is refused. The host stores nothing.
+ */
+function createPreferencesHandler(options) {
+    const base = (options.basePath ?? '/api/communication/preferences').replace(/\/+$/, '');
+    const mediums = options.mediums && options.mediums.length > 0 ? exports.PREFERENCE_MEDIUMS.filter((m) => options.mediums.includes(m)) : exports.PREFERENCE_MEDIUMS;
+    const evidence = { method: options.evidence?.method ?? 'settings_page', ...(options.evidence?.wordingVersion ? { wordingVersion: options.evidence.wordingVersion } : {}) };
+    let made;
+    const clientOf = () => options.client ?? (made ??= (0, client_1.createPreferencesClient)());
+    return async function preferencesHandler(request) {
+        try {
+            const method = request.method.toUpperCase();
+            if (new URL(request.url).pathname.replace(/\/+$/, '') !== base || (method !== 'GET' && method !== 'PUT'))
+                return (0, errors_1.hostError)('not_found');
+            if (method === 'PUT' && !(0, origin_1.originAllowed)(request, options.allowedOrigins))
+                return (0, errors_1.hostError)('not_permitted');
+            const person = await options.resolvePerson(request);
+            if (typeof person !== 'string' || person.length === 0 || person.length > validate_1.INBOX_LIMITS.personMax)
+                return (0, errors_1.hostError)('not_signed_in');
+            const client = clientOf();
+            if (method === 'GET')
+                return answer(await client.get(person, { retry: false, timeoutMs: options.timeoutMs ?? 8000 }));
+            const body = (0, validate_1.parseBody)(await request.text());
+            if (!body.ok)
+                return (0, errors_1.hostError)('invalid_input', body.field);
+            const medium = mediums.find((m) => m === body.value.medium);
+            if (!medium)
+                return (0, errors_1.hostError)('invalid_input', 'medium');
+            const state = body.value.state;
+            if (state !== 'opted_in' && state !== 'opted_out')
+                return (0, errors_1.hostError)('invalid_input', 'state');
+            return answer(await client.set(person, medium, state, evidence, { retry: false, timeoutMs: options.timeoutMs ?? 8000 }));
+        }
+        catch (error) {
+            const code = (0, errors_1.hostCodeOf)(error);
+            if (code === 'unavailable')
+                report(error);
+            return (0, errors_1.hostError)(code);
+        }
+    };
+    function answer(data) {
+        const preferences = [];
+        for (const raw of Array.isArray(data) ? data : [null]) {
+            const choice = projectChoice(raw);
+            if (!choice) {
+                report(new Error('The preferences answer did not have the documented shape'));
+                return (0, errors_1.hostError)('unavailable');
+            }
+            if (mediums.includes(choice.medium))
+                preferences.push(choice);
+        }
+        return (0, errors_1.hostData)({ preferences });
+    }
+    function report(error) {
+        try {
+            options.onError?.(error);
+        }
+        catch {
+            // A failing logger must not change the answer.
+        }
+    }
+}

package/dist/cjs/preferences/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREFERENCE_MEDIUMS = exports.createPreferencesHandler = exports.createPreferencesClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "createPreferencesClient", { enumerable: true, get: function () { return client_1.createPreferencesClient; } });
+var handler_1 = require("./handler");
+Object.defineProperty(exports, "createPreferencesHandler", { enumerable: true, get: function () { return handler_1.createPreferencesHandler; } });
+Object.defineProperty(exports, "PREFERENCE_MEDIUMS", { enumerable: true, get: function () { return handler_1.PREFERENCE_MEDIUMS; } });

package/dist/cjs/preferences-react/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PREFERENCE_LABELS = exports.NotificationPreferences = void 0;
+/**
+ * A person's notification choices for a settings page: one switch per medium the app can send on.
+ *
+ *   import { NotificationPreferences } from '@xtremax/pigeon/preferences-react';
+ *
+ *   <NotificationPreferences />
+ *
+ * The component calls the host app's own route (default `/api/communication/preferences`), which
+ * `createPreferencesHandler` from `@xtremax/pigeon/preferences` serves. It needs React 19 and Mantine 8, and no
+ * stylesheet of its own. Nothing here holds a key or talks to another origin.
+ */
+var notification_preferences_1 = require("./notification-preferences");
+Object.defineProperty(exports, "NotificationPreferences", { enumerable: true, get: function () { return notification_preferences_1.NotificationPreferences; } });
+var labels_1 = require("./labels");
+Object.defineProperty(exports, "DEFAULT_PREFERENCE_LABELS", { enumerable: true, get: function () { return labels_1.DEFAULT_PREFERENCE_LABELS; } });

package/dist/cjs/preferences-react/labels.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PREFERENCE_LABELS = void 0;
+exports.mergePreferenceLabels = mergePreferenceLabels;
+/**
+ * The sentences say what each switch covers, and Pigeon says which applies (`covers` in its answer): a choice that
+ * holds in every app of the organisation, or in this app only. Keep that when you translate.
+ */
+exports.DEFAULT_PREFERENCE_LABELS = {
+    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.',
+};
+function mergePreferenceLabels(labels) {
+    return { ...exports.DEFAULT_PREFERENCE_LABELS, ...(labels ?? {}) };
+}

package/dist/cjs/preferences-react/notification-preferences.js

@@ -0,0 +1,76 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationPreferences = NotificationPreferences;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const core_1 = require("@mantine/core");
+const labels_1 = require("./labels");
+const preferences_client_1 = require("./preferences-client");
+const words = (labels, choice) => {
+    // Pigeon says what a choice covers, so the sentence stays true if that changes on Pigeon's side.
+    const own = choice.covers === 'app';
+    if (choice.medium === 'email')
+        return { label: labels.email, description: choice.delivers ? (own ? labels.emailOnApp : labels.emailOn) : own ? labels.emailOffApp : labels.emailOff };
+    if (choice.medium === 'whatsapp')
+        return { label: labels.whatsapp, description: choice.delivers ? (own ? labels.whatsappOnApp : labels.whatsappOn) : own ? labels.whatsappOffApp : labels.whatsappOff };
+    return { label: labels.inApp, description: choice.delivers ? labels.inAppOn : labels.inAppOff };
+};
+/**
+ * A person's notification choices: one switch per medium, with a sentence that says what the switch covers.
+ * It shows what is recorded: a switch moves when the choice is saved, not before. Place it on a settings page,
+ * inside `MantineProvider`. It calls the host app's own route, which `createPreferencesHandler` serves.
+ */
+function NotificationPreferences({ apiBase, labels, mediums, onChange }) {
+    const client = (0, react_1.useMemo)(() => (0, preferences_client_1.createPreferencesBrowserClient)(apiBase), [apiBase]);
+    const merged = (0, react_1.useMemo)(() => (0, labels_1.mergePreferenceLabels)(labels), [labels]);
+    const [choices, setChoices] = (0, react_1.useState)(null);
+    const [status, setStatus] = (0, react_1.useState)('loading');
+    const [saving, setSaving] = (0, react_1.useState)(null);
+    const [saveFailed, setSaveFailed] = (0, react_1.useState)(false);
+    const load = (0, react_1.useCallback)(async () => {
+        setStatus('loading');
+        const res = await client.get();
+        if (res.ok)
+            setChoices(res.choices);
+        setStatus(res.ok ? 'ready' : 'error');
+    }, [client]);
+    (0, react_1.useEffect)(() => {
+        void load();
+    }, [load]);
+    const change = async (medium, on) => {
+        if (saving)
+            return;
+        setSaving(medium);
+        setSaveFailed(false);
+        const res = await client.set(medium, on);
+        setSaving(null);
+        if (!res.ok) {
+            setSaveFailed(true);
+            return;
+        }
+        setChoices(res.choices);
+        const saved = res.choices.find((choice) => choice.medium === medium);
+        // A choice that was recorded and still does not hold (for example a suspended person) is said, not hidden.
+        if (!saved || saved.delivers !== on)
+            setSaveFailed(true);
+        else
+            onChange?.(saved);
+    };
+    if (status === 'loading' && !choices) {
+        return ((0, jsx_runtime_1.jsx)(core_1.Center, { mih: 96, role: "status", "aria-label": merged.loading, children: (0, jsx_runtime_1.jsx)(core_1.Loader, { size: "sm" }) }));
+    }
+    if (!choices) {
+        return ((0, jsx_runtime_1.jsx)(core_1.Alert, { color: "red", variant: "light", title: merged.loadError, children: (0, jsx_runtime_1.jsx)(core_1.Button, { variant: "default", size: "sm", mih: 44, onClick: () => void load(), children: merged.retry }) }));
+    }
+    const shown = mediums
+        ? mediums.flatMap((medium) => choices.filter((choice) => choice.medium === medium))
+        : choices.filter((choice) => choice.available);
+    if (shown.length === 0) {
+        return ((0, jsx_runtime_1.jsx)(core_1.Text, { c: "dimmed", size: "sm", children: merged.none }));
+    }
+    return ((0, jsx_runtime_1.jsxs)(core_1.Stack, { gap: "md", role: "group", "aria-label": merged.group, children: [shown.map((choice) => {
+                const { label, description } = words(merged, choice);
+                return ((0, jsx_runtime_1.jsx)(core_1.Switch, { label: label, description: description, checked: choice.delivers, disabled: saving !== null, onChange: (event) => void change(choice.medium, event.currentTarget.checked) }, choice.medium));
+            }), saveFailed && ((0, jsx_runtime_1.jsx)(core_1.Alert, { color: "red", variant: "light", role: "alert", children: merged.saveError }))] }));
+}

package/dist/cjs/preferences-react/preferences-client.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREFERENCE_MEDIUMS = exports.DEFAULT_PREFERENCES_API_BASE = void 0;
+exports.parseChoice = parseChoice;
+exports.parseChoices = parseChoices;
+exports.createPreferencesBrowserClient = createPreferencesBrowserClient;
+const inbox_client_1 = require("../inbox-react/inbox-client");
+exports.DEFAULT_PREFERENCES_API_BASE = '/api/communication/preferences';
+exports.PREFERENCE_MEDIUMS = ['email', 'whatsapp', 'in_app'];
+/** A choice as the host route answers it. Anything else is refused, so a wrong answer never becomes a switch. */
+function parseChoice(v) {
+    if (typeof v !== 'object' || v === null)
+        return null;
+    const o = v;
+    const medium = exports.PREFERENCE_MEDIUMS.find((m) => m === o.medium);
+    if (!medium)
+        return null;
+    if (o.state !== 'opted_in' && o.state !== 'opted_out' && o.state !== 'not_set')
+        return null;
+    if (o.changedAt !== null && typeof o.changedAt !== 'string')
+        return null;
+    if (typeof o.delivers !== 'boolean' || typeof o.available !== 'boolean')
+        return null;
+    if (o.covers !== 'tenant' && o.covers !== 'app')
+        return null;
+    return { medium, state: o.state, changedAt: o.changedAt, delivers: o.delivers, covers: o.covers, available: o.available };
+}
+function parseChoices(v) {
+    const list = v?.preferences;
+    if (!Array.isArray(list))
+        return null;
+    const choices = [];
+    for (const raw of list) {
+        const choice = parseChoice(raw);
+        if (!choice)
+            return null;
+        choices.push(choice);
+    }
+    return choices;
+}
+/**
+ * The browser talks only to the host app's own route. Every call answers a result and never throws, so an outage
+ * cannot break the host page.
+ */
+function createPreferencesBrowserClient(apiBase, fetchImpl) {
+    const base = (0, inbox_client_1.normalizeApiBase)(apiBase ?? exports.DEFAULT_PREFERENCES_API_BASE);
+    async function call(method, body) {
+        if (base === null)
+            return { ok: false, code: 'unavailable' };
+        try {
+            const res = await (fetchImpl ?? fetch)(base, {
+                method,
+                credentials: 'same-origin',
+                cache: 'no-store',
+                headers: { Accept: 'application/json', ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}) },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+            if (res.status === 401)
+                return { ok: false, code: 'not_signed_in' };
+            const json = await res.json().catch(() => null);
+            const choices = res.ok ? parseChoices(json?.data) : null;
+            return choices ? { ok: true, choices } : { ok: false, code: 'unavailable' };
+        }
+        catch {
+            return { ok: false, code: 'unavailable' };
+        }
+    }
+    return {
+        get: () => call('GET'),
+        set: (medium, on) => call('PUT', { medium, state: on ? 'opted_in' : 'opted_out' }),
+    };
+}

package/dist/esm/client.js

@@ -1,5 +1,6 @@
 import { CommunicationError, fromResponse, redact } from './errors.js';
 import { newIdempotencyKey } from './idempotency.js';
+import { personHeader } from './person.js';
 import { DEFAULT_RETRY, backoffMs, isRetryableStatus } from './retry.js';
 /** Where a client keeps its transport, so `@xtremax/pigeon/inbox` can reuse the key handling, retries and errors. */
 export const TRANSPORT = Symbol.for('@xtremax/pigeon.transport');
@@ -93,6 +94,8 @@ export function createCommunicationClient(options = {}) {
             },
         },
         preferences: {
+            /** A person's choice for each medium, and whether a message reaches them now. Someone Pigeon has not met has made no choice. */
+            get: (personId) => request('GET', '/preferences', undefined, { headers: { 'X-Communication-Person': personHeader(personId) } }).then((r) => r.data.preferences),
             record: (body) => request('POST', '/preferences', body).then((r) => r.data),
         },
         messageClasses: {

package/dist/esm/inbox/client.js

@@ -1,11 +1,5 @@
 import { TRANSPORT, createCommunicationClient } from '../client.js';
-/** `X-Communication-Person` is base64url of the UTF-8 person id, so any identifier travels safely in a header. */
-export function personHeader(personId) {
-    let binary = '';
-    for (const byte of new TextEncoder().encode(personId))
-        binary += String.fromCharCode(byte);
-    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-}
+import { personHeader } from '../person.js';
 const isClient = (v) => TRANSPORT in v;
 /**
  * The in-app inbox of one person. Pass an existing client to share its key and settings, or the same options as
@@ -33,3 +27,4 @@ export function createInboxClient(client = {}) {
         setPreference: (personId, state, options) => call('PUT', '/inbox/preference', personId, { state }, false, options),
     };
 }
+export { personHeader };

package/dist/esm/person.js

@@ -0,0 +1,7 @@
+/** `X-Communication-Person` is base64url of the UTF-8 person id, so any identifier travels safely in a header. */
+export function personHeader(personId) {
+    let binary = '';
+    for (const byte of new TextEncoder().encode(personId))
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}

package/dist/esm/preferences/browser-stub.js

@@ -0,0 +1,7 @@
+import { CommunicationError } from '../errors.js';
+const serverOnly = () => {
+    throw new CommunicationError({ code: 'server_only', message: 'The Communication preferences client holds a secret key and must run on the server.' });
+};
+/** Selected by the `browser` export condition: this entry never reaches client code. The component talks to the host's own route instead. */
+export const createPreferencesClient = serverOnly;
+export const createPreferencesHandler = serverOnly;

package/dist/esm/preferences/client.js

@@ -0,0 +1,18 @@
+import { TRANSPORT, createCommunicationClient } from '../client.js';
+import { personHeader } from '../person.js';
+const isClient = (v) => TRANSPORT in v;
+/**
+ * Pass an existing client to share its key and settings, or the same options as `createCommunicationClient`.
+ * The key needs the scopes `recipients:read` and `consent:write`.
+ */
+export function createPreferencesClient(client = {}) {
+    const request = (isClient(client) ? client : createCommunicationClient(client))[TRANSPORT];
+    const get = (personId, options = {}) => request('GET', '/preferences', undefined, { headers: { 'X-Communication-Person': personHeader(personId) }, retry: options.retry ?? true, timeoutMs: options.timeoutMs }).then((r) => r.data.preferences);
+    return {
+        get,
+        async set(personId, medium, state, evidence, options = {}) {
+            await request('POST', '/preferences', { recipient: { personId }, medium, state, expressedAt: new Date().toISOString(), ...(evidence ? { evidence } : {}) }, { retry: options.retry ?? false, timeoutMs: options.timeoutMs });
+            return get(personId, options);
+        },
+    };
+}