@xtremax/pigeon 0.3.0 → 0.4.0

package/dist/esm/preferences/handler.js

@@ -0,0 +1,92 @@
+import { hostCodeOf, hostData, hostError } from '../inbox/errors.js';
+import { originAllowed } from '../inbox/origin.js';
+import { INBOX_LIMITS, parseBody } from '../inbox/validate.js';
+import { createPreferencesClient } from './client.js';
+export const 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 = 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.
+ */
+export function createPreferencesHandler(options) {
+    const base = (options.basePath ?? '/api/communication/preferences').replace(/\/+$/, '');
+    const mediums = options.mediums && options.mediums.length > 0 ? PREFERENCE_MEDIUMS.filter((m) => options.mediums.includes(m)) : PREFERENCE_MEDIUMS;
+    const evidence = { method: options.evidence?.method ?? 'settings_page', ...(options.evidence?.wordingVersion ? { wordingVersion: options.evidence.wordingVersion } : {}) };
+    let made;
+    const clientOf = () => options.client ?? (made ??= 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 hostError('not_found');
+            if (method === 'PUT' && !originAllowed(request, options.allowedOrigins))
+                return hostError('not_permitted');
+            const person = await options.resolvePerson(request);
+            if (typeof person !== 'string' || person.length === 0 || person.length > INBOX_LIMITS.personMax)
+                return hostError('not_signed_in');
+            const client = clientOf();
+            if (method === 'GET')
+                return answer(await client.get(person, { retry: false, timeoutMs: options.timeoutMs ?? 8000 }));
+            const body = parseBody(await request.text());
+            if (!body.ok)
+                return hostError('invalid_input', body.field);
+            const medium = mediums.find((m) => m === body.value.medium);
+            if (!medium)
+                return hostError('invalid_input', 'medium');
+            const state = body.value.state;
+            if (state !== 'opted_in' && state !== 'opted_out')
+                return hostError('invalid_input', 'state');
+            return answer(await client.set(person, medium, state, evidence, { retry: false, timeoutMs: options.timeoutMs ?? 8000 }));
+        }
+        catch (error) {
+            const code = hostCodeOf(error);
+            if (code === 'unavailable')
+                report(error);
+            return 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 hostError('unavailable');
+            }
+            if (mediums.includes(choice.medium))
+                preferences.push(choice);
+        }
+        return hostData({ preferences });
+    }
+    function report(error) {
+        try {
+            options.onError?.(error);
+        }
+        catch {
+            // A failing logger must not change the answer.
+        }
+    }
+}

package/dist/esm/preferences/index.js

@@ -0,0 +1,2 @@
+export { createPreferencesClient } from './client.js';
+export { createPreferencesHandler, PREFERENCE_MEDIUMS } from './handler.js';

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

@@ -0,0 +1,13 @@
+/**
+ * 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 } from './notification-preferences.js';
+export { DEFAULT_PREFERENCE_LABELS } from './labels.js';

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.0",
+  "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,13 @@
     "./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" }
   },
-  "files": ["dist", "README.md", "CHANGELOG.md"],
+  "bin": { "pigeon": "bin/pigeon.mjs" },
+  "files": ["dist", "bin", "skills", "README.md", "CHANGELOG.md"],
   "scripts": {
     "build": "node scripts/build.mjs",
     "prepublishOnly": "node scripts/build.mjs"