@xtremax/pigeon 0.3.1 → 0.4.0

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

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+export const 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.',
+};
+export function mergePreferenceLabels(labels) {
+    return { ...DEFAULT_PREFERENCE_LABELS, ...(labels ?? {}) };
+}

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

@@ -0,0 +1,73 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { Alert, Button, Center, Loader, Stack, Switch, Text } from '@mantine/core';
+import { mergePreferenceLabels } from './labels.js';
+import { createPreferencesBrowserClient } from './preferences-client.js';
+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.
+ */
+export function NotificationPreferences({ apiBase, labels, mediums, onChange }) {
+    const client = useMemo(() => createPreferencesBrowserClient(apiBase), [apiBase]);
+    const merged = useMemo(() => mergePreferenceLabels(labels), [labels]);
+    const [choices, setChoices] = useState(null);
+    const [status, setStatus] = useState('loading');
+    const [saving, setSaving] = useState(null);
+    const [saveFailed, setSaveFailed] = useState(false);
+    const load = useCallback(async () => {
+        setStatus('loading');
+        const res = await client.get();
+        if (res.ok)
+            setChoices(res.choices);
+        setStatus(res.ok ? 'ready' : 'error');
+    }, [client]);
+    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 (_jsx(Center, { mih: 96, role: "status", "aria-label": merged.loading, children: _jsx(Loader, { size: "sm" }) }));
+    }
+    if (!choices) {
+        return (_jsx(Alert, { color: "red", variant: "light", title: merged.loadError, children: _jsx(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 (_jsx(Text, { c: "dimmed", size: "sm", children: merged.none }));
+    }
+    return (_jsxs(Stack, { gap: "md", role: "group", "aria-label": merged.group, children: [shown.map((choice) => {
+                const { label, description } = words(merged, choice);
+                return (_jsx(Switch, { label: label, description: description, checked: choice.delivers, disabled: saving !== null, onChange: (event) => void change(choice.medium, event.currentTarget.checked) }, choice.medium));
+            }), saveFailed && (_jsx(Alert, { color: "red", variant: "light", role: "alert", children: merged.saveError }))] }));
+}

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

@@ -0,0 +1,66 @@
+import { normalizeApiBase } from '../inbox-react/inbox-client.js';
+export const DEFAULT_PREFERENCES_API_BASE = '/api/communication/preferences';
+export const 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. */
+export function parseChoice(v) {
+    if (typeof v !== 'object' || v === null)
+        return null;
+    const o = v;
+    const medium = 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 };
+}
+export 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.
+ */
+export function createPreferencesBrowserClient(apiBase, fetchImpl) {
+    const base = normalizeApiBase(apiBase ?? 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/types/client.d.ts

@@ -1,4 +1,4 @@
-import type { AcceptedMessage, ChannelInfo, MessageView, PingInfo, RecipientView, SendMessageRequest } from './contract.js';
+import type { AcceptedMessage, ChannelInfo, MessageView, PingInfo, PreferenceChoice, PreferenceEvidence, PreferenceRecorded, RecipientView, SendMessageRequest } from './contract.js';
 import { type RetryPolicy } from './retry.js';
 export interface ClientOptions {
     /** Defaults to `process.env.COMMUNICATION_API_KEY`. */
@@ -56,6 +56,8 @@ export declare function createCommunicationClient(options?: ClientOptions): {
         deleteAddress(personId: string, addressId: string): Promise<void>;
     };
     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: string) => Promise<PreferenceChoice[]>;
         record: (body: {
             recipient: {
                 personId?: string;
@@ -65,15 +67,8 @@ export declare function createCommunicationClient(options?: ClientOptions): {
             medium: "email" | "whatsapp" | "in_app";
             state: "opted_in" | "opted_out";
             expressedAt?: string;
-            evidence?: {
-                method?: string;
-                wordingVersion?: string;
-                proofRef?: string;
-            };
-        }) => Promise<{
-            changed: boolean;
-            current: unknown;
-        }>;
+            evidence?: PreferenceEvidence;
+        }) => Promise<PreferenceRecorded>;
     };
     messageClasses: {
         put: (templateKey: string, body: {

package/dist/types/contract.d.ts

@@ -130,6 +130,33 @@ export interface RecipientView {
         source: string | null;
     }>;
 }
+export type PreferenceMedium = 'email' | 'whatsapp' | 'in_app';
+export interface PreferenceChoice {
+    medium: PreferenceMedium;
+    state: 'opted_in' | 'opted_out' | 'not_set';
+    changedAt: string | null;
+    /** Whether a message on this medium reaches the person now: the choice, the tenant's consent mode and the person's status together. */
+    delivers: boolean;
+    /** `tenant`: the choice holds in every application of the tenant. `app`: it holds for the calling application only. */
+    covers: 'tenant' | 'app';
+    /** Whether the calling key has a ready channel of this medium. */
+    available: boolean;
+}
+/** How a choice was made: where, which wording the person saw, and your own record of it. */
+export interface PreferenceEvidence {
+    method?: string;
+    wordingVersion?: string;
+    proofRef?: string;
+}
+export interface PreferenceRecorded {
+    changed: boolean;
+    current: {
+        medium: string;
+        state: 'opted_in' | 'opted_out' | 'not_set';
+        changedAt: string | null;
+        source: string | null;
+    };
+}
 export interface InboxNotification {
     /** The inbox item, not the message. */
     id: string;

package/dist/types/inbox/client.d.ts

@@ -1,4 +1,5 @@
 import { type ClientOptions, type CommunicationClient } from '../client.js';
+import { personHeader } from '../person.js';
 import type { InboxMarkReadResult, InboxNotificationPage, InboxPreference, InboxReadAllResult, InboxSummary } from '../contract.js';
 export interface CallOptions {
     /** Reads are retried by the SDK's policy unless this is `false`. Writes make one attempt unless this is `true`. */
@@ -25,10 +26,9 @@ export interface InboxClient {
     getPreference(personId: string, options?: CallOptions): Promise<InboxPreference>;
     setPreference(personId: string, state: 'opted_in' | 'opted_out', options?: CallOptions): Promise<InboxPreference>;
 }
-/** `X-Communication-Person` is base64url of the UTF-8 person id, so any identifier travels safely in a header. */
-export declare function personHeader(personId: string): string;
 /**
  * The in-app inbox of one person. Pass an existing client to share its key and settings, or the same options as
  * `createCommunicationClient`. The key needs the scopes `inbox:read` and `inbox:write`.
  */
 export declare function createInboxClient(client?: ClientOptions | CommunicationClient): InboxClient;
+export { personHeader };

package/dist/types/person.d.ts

@@ -0,0 +1,2 @@
+/** `X-Communication-Person` is base64url of the UTF-8 person id, so any identifier travels safely in a header. */
+export declare function personHeader(personId: string): string;

package/dist/types/preferences/browser-stub.d.ts

@@ -0,0 +1,3 @@
+/** Selected by the `browser` export condition: this entry never reaches client code. The component talks to the host's own route instead. */
+export declare const createPreferencesClient: () => never;
+export declare const createPreferencesHandler: () => never;

package/dist/types/preferences/client.d.ts

@@ -0,0 +1,18 @@
+import { type ClientOptions, type CommunicationClient } from '../client.js';
+import type { PreferenceChoice, PreferenceEvidence, PreferenceMedium } from '../contract.js';
+import type { CallOptions } from '../inbox/client.js';
+/**
+ * A person's consent choices as this key meets them: email and WhatsApp for the whole tenant, in-app for this key's
+ * own sub-tenant (or the tenant level, for a key outside any).
+ */
+export interface PreferencesClient {
+    /** One entry per medium. Someone Pigeon has not met has made no choice. */
+    get(personId: string, options?: CallOptions): Promise<PreferenceChoice[]>;
+    /** Records one choice with how it was made, and answers the choices as they are afterwards. */
+    set(personId: string, medium: PreferenceMedium, state: 'opted_in' | 'opted_out', evidence?: PreferenceEvidence, options?: CallOptions): Promise<PreferenceChoice[]>;
+}
+/**
+ * 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 declare function createPreferencesClient(client?: ClientOptions | CommunicationClient): PreferencesClient;

package/dist/types/preferences/handler.d.ts

@@ -0,0 +1,32 @@
+import type { PreferenceEvidence, PreferenceMedium } from '../contract.js';
+import { type PreferencesClient } from './client.js';
+export declare const PREFERENCE_MEDIUMS: readonly PreferenceMedium[];
+export interface PreferencesHandlerOptions {
+    /** The app's only job: who is signed in. `null` means nobody. Read it from your own session, never from the request's path, query or body. */
+    resolvePerson: (request: Request) => Promise<string | null> | string | null;
+    /** Default: a client made on the first request from `COMMUNICATION_API_KEY` and `COMMUNICATION_URL`. */
+    client?: PreferencesClient;
+    /** Where the route is mounted. Default `/api/communication/preferences`. */
+    basePath?: string;
+    /** The media a person may see and change through this route. Default: all three. */
+    mediums?: readonly PreferenceMedium[];
+    /** Recorded with every choice. `method` defaults to `settings_page`; set `wordingVersion` and change it when the text beside the switches changes. */
+    evidence?: Pick<PreferenceEvidence, 'method' | 'wordingVersion'>;
+    /** Origins that may send PUT. Default: the request's own origin. */
+    allowedOrigins?: readonly string[];
+    /** Default 8000. */
+    timeoutMs?: number;
+    /** Told about every failure answered as `unavailable`, for the host's own log. The browser never sees it. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * 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.
+ */
+export declare function createPreferencesHandler(options: PreferencesHandlerOptions): (request: Request) => Promise<Response>;

package/dist/types/preferences/index.d.ts

@@ -0,0 +1,3 @@
+export { createPreferencesClient, type PreferencesClient } from './client.js';
+export { createPreferencesHandler, PREFERENCE_MEDIUMS, type PreferencesHandlerOptions } from './handler.js';
+export type { PreferenceChoice, PreferenceEvidence, PreferenceMedium } from '../contract.js';

package/dist/types/preferences-react/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+export { NotificationPreferences, type NotificationPreferencesProps } from './notification-preferences.js';
+export { DEFAULT_PREFERENCE_LABELS, type PreferenceLabels } from './labels.js';
+export type { PreferenceChoice, PreferenceMedium } from '../contract.js';

package/dist/types/preferences-react/labels.d.ts

@@ -0,0 +1,32 @@
+/** Every visible and accessible text of the preferences component. Pass `labels` to replace any of them. */
+export interface PreferenceLabels {
+    /** The accessible name of the group of switches. */
+    group: string;
+    email: string;
+    /** Email, when the choice holds in every app of the organisation. */
+    emailOn: string;
+    emailOff: string;
+    /** Email, when Pigeon says the choice holds for this app only (`covers: 'app'`). */
+    emailOnApp: string;
+    emailOffApp: string;
+    whatsapp: string;
+    whatsappOn: string;
+    whatsappOff: string;
+    whatsappOnApp: string;
+    whatsappOffApp: string;
+    inApp: string;
+    inAppOn: string;
+    inAppOff: string;
+    loading: string;
+    loadError: string;
+    retry: string;
+    saveError: string;
+    /** Shown when the app can send on no medium. */
+    none: string;
+}
+/**
+ * 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.
+ */
+export declare const DEFAULT_PREFERENCE_LABELS: PreferenceLabels;
+export declare function mergePreferenceLabels(labels?: Partial<PreferenceLabels>): PreferenceLabels;

package/dist/types/preferences-react/notification-preferences.d.ts

@@ -0,0 +1,18 @@
+import type { PreferenceChoice, PreferenceMedium } from '../contract.js';
+import { type PreferenceLabels } from './labels.js';
+export interface NotificationPreferencesProps {
+    /** A path on the host's own origin. Default `/api/communication/preferences`. */
+    apiBase?: string;
+    /** Replaces any visible or accessible text. */
+    labels?: Partial<PreferenceLabels>;
+    /** Which media to show, in this order. Default: the ones the app can send on. */
+    mediums?: readonly PreferenceMedium[];
+    /** Told after a choice was saved. */
+    onChange?: (choice: PreferenceChoice) => void;
+}
+/**
+ * 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.
+ */
+export declare function NotificationPreferences({ apiBase, labels, mediums, onChange }: NotificationPreferencesProps): import("react").JSX.Element;

package/dist/types/preferences-react/preferences-client.d.ts

@@ -0,0 +1,22 @@
+import type { PreferenceChoice, PreferenceMedium } from '../contract.js';
+export declare const DEFAULT_PREFERENCES_API_BASE = "/api/communication/preferences";
+export declare const PREFERENCE_MEDIUMS: readonly PreferenceMedium[];
+export type PreferencesResult = {
+    ok: true;
+    choices: PreferenceChoice[];
+} | {
+    ok: false;
+    code: 'not_signed_in' | 'unavailable';
+};
+/** A choice as the host route answers it. Anything else is refused, so a wrong answer never becomes a switch. */
+export declare function parseChoice(v: unknown): PreferenceChoice | null;
+export declare function parseChoices(v: unknown): PreferenceChoice[] | null;
+export interface PreferencesBrowserClient {
+    get(): Promise<PreferencesResult>;
+    set(medium: PreferenceMedium, on: boolean): Promise<PreferencesResult>;
+}
+/**
+ * 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.
+ */
+export declare function createPreferencesBrowserClient(apiBase?: string, fetchImpl?: typeof fetch): PreferencesBrowserClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtremax/pigeon",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Client for Pigeon, the Buildpad Communication Gateway: send messages, verify signed events, serve an in-app inbox and show its notification bell.",
   "license": "UNLICENSED",
   "type": "module",
@@ -15,10 +15,12 @@
     "./inbox": { "browser": "./dist/esm/inbox/browser-stub.js", "types": "./dist/types/inbox/index.d.ts", "import": "./dist/esm/inbox/index.js", "require": "./dist/cjs/inbox/index.js" },
     "./inbox-react": { "types": "./dist/types/inbox-react/index.d.ts", "import": "./dist/esm/inbox-react/index.js", "require": "./dist/cjs/inbox-react/index.js" },
     "./inbox-react/styles.css": "./dist/inbox-react/styles.css",
+    "./preferences": { "browser": "./dist/esm/preferences/browser-stub.js", "types": "./dist/types/preferences/index.d.ts", "import": "./dist/esm/preferences/index.js", "require": "./dist/cjs/preferences/index.js" },
+    "./preferences-react": { "types": "./dist/types/preferences-react/index.d.ts", "import": "./dist/esm/preferences-react/index.js", "require": "./dist/cjs/preferences-react/index.js" },
     "./events": { "types": "./dist/types/events.d.ts", "import": "./dist/esm/events.js", "require": "./dist/cjs/events.js" },
     "./contract": { "types": "./dist/types/contract.d.ts" }
   },
-  "bin": { "pigeon": "./bin/pigeon.mjs" },
+  "bin": { "pigeon": "bin/pigeon.mjs" },
   "files": ["dist", "bin", "skills", "README.md", "CHANGELOG.md"],
   "scripts": {
     "build": "node scripts/build.mjs",

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

@@ -1,6 +1,6 @@
 ---
 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.
+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
 ---
 
@@ -24,6 +24,7 @@ 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` |
 
@@ -38,7 +39,8 @@ These are what keeps the integration safe. Each has a reason; do not trade one a
 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).
+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.
 
@@ -63,7 +65,7 @@ The package's preference dialog uses Mantine's `Switch` internally. That is insi
 pnpm add @xtremax/pigeon
 ```
 
-Version 0.3.1 or later. No component files are copied into the app.
+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.
 
@@ -100,7 +102,7 @@ Read the output:
 - `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
+## Step 4: Who the person is
 
 ```ts
 // lib/communication/person.ts
@@ -110,6 +112,23 @@ 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.
@@ -117,18 +136,12 @@ 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';
+import { resolvePerson } from '@/lib/communication/session';
 
 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;
-  },
+  resolvePerson,
   // The browser is never told why something failed. This is where you see it.
   onError: (error) => console.error('[communication-inbox]', error),
 });
@@ -136,7 +149,6 @@ const handler = createInboxHandler({
 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.
@@ -242,6 +254,27 @@ What to know when choosing what to send:
 - **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.
@@ -279,7 +312,7 @@ await expect(page.getByRole('dialog').getByRole('heading', { name: 'Notification
 - [ ] 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.
+- [ ] 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
@@ -299,4 +332,6 @@ await expect(page.getByRole('dialog').getByRole('heading', { name: 'Notification
 
 ## 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.