@xtremax/pigeon 0.0.0-stage → 0.3.1

package/dist/cjs/inbox-react/inbox-provider.js

@@ -0,0 +1,157 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboxProvider = InboxProvider;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const core_1 = require("@mantine/core");
+const hooks_1 = require("@mantine/hooks");
+const format_1 = require("./format");
+const inbox_client_1 = require("./inbox-client");
+const inbox_context_1 = require("./inbox-context");
+const inbox_full_list_1 = require("./inbox-full-list");
+const inbox_state_1 = require("./inbox-state");
+const labels_1 = require("./labels");
+const preference_dialog_1 = require("./preference-dialog");
+const use_inbox_polling_1 = require("./use-inbox-polling");
+const openInNewTab = (url) => {
+    window.open(url, '_blank', 'noopener,noreferrer');
+};
+/** "Mark all as read" changes at most one batch per call; repeat while something remains, within a bound. */
+const READ_ALL_MAX_CALLS = 10;
+const nowIso = () => new Date().toISOString();
+function InboxProvider({ apiBase, labels, locale, onViewAll, onOpenPreferences, openLink, children }) {
+    const client = (0, react_1.useMemo)(() => (0, inbox_client_1.createInboxBrowserClient)(apiBase), [apiBase]);
+    const merged = (0, react_1.useMemo)(() => (0, labels_1.mergeLabels)(labels), [labels]);
+    const [state, dispatch] = (0, react_1.useReducer)(inbox_state_1.inboxReducer, inbox_state_1.initialInboxState);
+    const [panelOpened, setPanelOpened] = (0, react_1.useState)(false);
+    const [fullOpened, setFullOpened] = (0, react_1.useState)(false);
+    const [preferencesOpened, setPreferencesOpened] = (0, react_1.useState)(false);
+    const reduceMotion = (0, hooks_1.useReducedMotion)();
+    const bellRef = (0, react_1.useRef)(null);
+    const latest = (0, react_1.useRef)(state);
+    (0, react_1.useEffect)(() => {
+        latest.current = state;
+    }, [state]);
+    // The tab is also kept here: a list that mounts in the same render as a tab change must load the new tab.
+    const tabRef = (0, react_1.useRef)('all');
+    const lists = (0, react_1.useRef)(0);
+    const request = (0, react_1.useRef)(0);
+    const load = (0, react_1.useCallback)(async (mode, tab, cursor) => {
+        const mine = (request.current += 1);
+        dispatch({ type: 'loadStarted', mode });
+        const res = await client.list({ unreadOnly: tab === 'unread', cursor });
+        // An answer for a tab or a list the person has already left is dropped.
+        if (mine !== request.current)
+            return;
+        if (res.ok)
+            dispatch({ type: 'pageReceived', page: res.data, mode, at: nowIso() });
+        else
+            dispatch({ type: 'loadFailed', mode });
+    }, [client]);
+    const poll = (0, react_1.useCallback)(async () => {
+        const res = await client.summary();
+        if (!res.ok)
+            return res.code === 'not_signed_in' ? { result: 'stop' } : { result: 'failed' };
+        const before = latest.current;
+        dispatch({ type: 'summaryReceived', summary: res.data, at: nowIso() });
+        const changed = res.data.unreadCount !== before.unreadCount || res.data.newestUnreadAt !== before.newestUnreadAt;
+        // A list on screen follows the change (13.3). One that is mid-action is left alone.
+        if (changed && lists.current > 0 && before.loaded && before.status === 'idle' && !before.markAll && Object.keys(before.pending).length === 0)
+            void load('merge', before.tab);
+        return { result: 'ok', pollSeconds: res.data.pollSeconds };
+    }, [client, load]);
+    (0, use_inbox_polling_1.useInboxPolling)(poll);
+    const attachList = (0, react_1.useCallback)(() => {
+        lists.current += 1;
+        const shown = latest.current;
+        void load(shown.loaded && shown.tab === tabRef.current ? 'merge' : 'replace', tabRef.current);
+        return () => {
+            lists.current -= 1;
+        };
+    }, [load]);
+    const setTab = (0, react_1.useCallback)((tab) => {
+        if (tab === tabRef.current)
+            return;
+        tabRef.current = tab;
+        dispatch({ type: 'tabChanged', tab });
+        void load('replace', tab);
+    }, [load]);
+    const select = (0, react_1.useCallback)((item) => {
+        const link = (0, format_1.safeLink)(item.link);
+        if (link)
+            (openLink ?? openInNewTab)(link);
+        if (item.read || latest.current.pending[item.id])
+            return;
+        dispatch({ type: 'markReadOptimistic', id: item.id, at: nowIso() });
+        void client.markRead(item.id).then((res) => {
+            if (res.ok)
+                dispatch({ type: 'markReadConfirmed', id: item.id, notification: res.data.notification, unreadCount: res.data.unreadCount });
+            else
+                dispatch({ type: 'markReadFailed', id: item.id });
+        });
+    }, [client, openLink]);
+    const markAllRead = (0, react_1.useCallback)(() => {
+        const before = latest.current;
+        if (!(0, inbox_state_1.canMarkAll)(before))
+            return;
+        // Only what the person could have seen: notifications that arrive later stay unread.
+        const upTo = before.newestUnreadAt ?? before.items[0]?.createdAt ?? null;
+        dispatch({ type: 'markAllOptimistic', at: nowIso() });
+        void (async () => {
+            let unreadCount = 0;
+            for (let i = 0; i < READ_ALL_MAX_CALLS; i += 1) {
+                const res = await client.markAllRead(upTo);
+                if (!res.ok) {
+                    dispatch({ type: 'markAllFailed' });
+                    return;
+                }
+                unreadCount = res.data.unreadCount;
+                if (res.data.remaining === 0)
+                    break;
+            }
+            dispatch({ type: 'markAllConfirmed', unreadCount });
+        })();
+    }, [client]);
+    const loadMore = (0, react_1.useCallback)(() => {
+        const s = latest.current;
+        if (s.nextCursor && !s.loadingMore)
+            void load('append', s.tab, s.nextCursor);
+    }, [load]);
+    const retry = (0, react_1.useCallback)(() => void load('replace', latest.current.tab), [load]);
+    const clearMessage = (0, react_1.useCallback)(() => dispatch({ type: 'messageCleared' }), []);
+    const openPanel = (0, react_1.useCallback)(() => setPanelOpened(true), []);
+    const closePanel = (0, react_1.useCallback)(() => setPanelOpened(false), []);
+    const viewAll = (0, react_1.useCallback)(() => {
+        setPanelOpened(false);
+        // "View all" means all: it never opens on the Unread tab the panel was showing.
+        if (tabRef.current !== 'all') {
+            tabRef.current = 'all';
+            dispatch({ type: 'tabChanged', tab: 'all' });
+        }
+        if (onViewAll)
+            onViewAll();
+        else
+            setFullOpened(true);
+    }, [onViewAll]);
+    const openPreferences = (0, react_1.useCallback)(() => {
+        setPanelOpened(false);
+        if (onOpenPreferences)
+            onOpenPreferences();
+        else
+            setPreferencesOpened(true);
+    }, [onOpenPreferences]);
+    // The control that opened a dialog is gone with the panel, so focus goes back to the bell (15.2).
+    const focusBell = (0, react_1.useCallback)(() => {
+        window.setTimeout(() => bellRef.current?.focus(), 0);
+    }, []);
+    const value = (0, react_1.useMemo)(() => ({ state, labels: merged, locale, client, panelOpened, bellRef, openPanel, closePanel, setTab, select, markAllRead, loadMore, viewAll, openPreferences, retry, clearMessage, attachList }), [state, merged, locale, client, panelOpened, openPanel, closePanel, setTab, select, markAllRead, loadMore, viewAll, openPreferences, retry, clearMessage, attachList]);
+    const transition = reduceMotion ? { duration: 0 } : undefined;
+    return ((0, jsx_runtime_1.jsxs)(inbox_context_1.InboxContext.Provider, { value: value, children: [children, (0, jsx_runtime_1.jsx)(core_1.Modal, { opened: fullOpened, onClose: () => {
+                    setFullOpened(false);
+                    focusBell();
+                }, title: merged.fullListTitle, closeButtonProps: { 'aria-label': merged.close }, size: "lg", returnFocus: false, transitionProps: transition, styles: { body: { padding: 0 } }, children: fullOpened && (0, jsx_runtime_1.jsx)(inbox_full_list_1.InboxFullList, {}) }), (0, jsx_runtime_1.jsx)(preference_dialog_1.PreferenceDialog, { opened: preferencesOpened, onClose: () => {
+                    setPreferencesOpened(false);
+                    focusBell();
+                } })] }));
+}

package/dist/cjs/inbox-react/inbox-state.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initialInboxState = void 0;
+exports.inboxReducer = inboxReducer;
+exports.canMarkAll = canMarkAll;
+exports.initialInboxState = {
+    unreadCount: 0, newestUnreadAt: null, items: [], nextCursor: null, tab: 'all', status: 'idle', loaded: false, loadingMore: false, lastSyncedAt: null, pending: {}, markAll: null, actionFailed: false,
+};
+const busy = (s) => s.markAll !== null || Object.keys(s.pending).length > 0;
+const asRead = (n, at) => (n.read ? n : { ...n, read: true, readAt: at });
+/** Newest first by (createdAt, id): true when `a` comes after `b` in the list. */
+const olderThan = (a, b) => a.createdAt < b.createdAt || (a.createdAt === b.createdAt && a.id < b.id);
+function mergePage(s, page, mode) {
+    if (mode === 'append') {
+        const seen = new Set(s.items.map((n) => n.id));
+        return { items: [...s.items, ...page.notifications.filter((n) => !seen.has(n.id))], nextCursor: page.nextCursor };
+    }
+    const last = page.notifications.at(-1);
+    if (mode === 'replace' || !last || page.nextCursor === null)
+        return { items: page.notifications, nextCursor: page.nextCursor };
+    // merge: the page is the newest part; keep what was already shown below it.
+    const fresh = new Set(page.notifications.map((n) => n.id));
+    const kept = s.items.filter((n) => !fresh.has(n.id) && olderThan(n, last));
+    return kept.length > 0 ? { items: [...page.notifications, ...kept], nextCursor: s.nextCursor } : { items: page.notifications, nextCursor: page.nextCursor };
+}
+function inboxReducer(s, a) {
+    switch (a.type) {
+        case 'summaryReceived':
+            // While an optimistic change waits for its answer, the count on screen is the newer truth.
+            return busy(s) ? { ...s, lastSyncedAt: a.at } : { ...s, unreadCount: a.summary.unreadCount, newestUnreadAt: a.summary.newestUnreadAt, lastSyncedAt: a.at };
+        case 'loadStarted':
+            if (a.mode === 'append')
+                return { ...s, loadingMore: true };
+            return { ...s, loadingMore: false, status: s.loaded ? 'refreshing' : 'loading' };
+        case 'pageReceived': {
+            const merged = mergePage(s, a.page, a.mode);
+            // An item whose "mark read" is still in flight stays read, whatever this page says.
+            const stillUnread = merged.items.filter((n) => !n.read && (s.pending[n.id] || s.markAll)).length;
+            const items = merged.items.map((n) => (s.pending[n.id] || s.markAll ? asRead(n, a.at) : n));
+            return {
+                ...s, items, nextCursor: merged.nextCursor, loaded: true, loadingMore: false, status: 'idle', lastSyncedAt: a.at,
+                unreadCount: s.markAll ? s.unreadCount : Math.max(0, a.page.unreadCount - stillUnread),
+            };
+        }
+        case 'loadFailed':
+            if (a.mode === 'append')
+                return { ...s, loadingMore: false, actionFailed: true };
+            return { ...s, loadingMore: false, status: s.loaded ? 'idle' : 'error' };
+        case 'tabChanged':
+            return a.tab === s.tab ? s : { ...s, tab: a.tab, items: [], nextCursor: null, loaded: false, loadingMore: false, status: 'loading' };
+        case 'markReadOptimistic': {
+            const item = s.items.find((n) => n.id === a.id);
+            if (!item || item.read || s.pending[a.id])
+                return s;
+            return { ...s, items: s.items.map((n) => (n.id === a.id ? asRead(n, a.at) : n)), unreadCount: Math.max(0, s.unreadCount - 1), pending: { ...s.pending, [a.id]: item } };
+        }
+        case 'markReadConfirmed': {
+            if (!s.pending[a.id])
+                return s;
+            const { [a.id]: _done, ...pending } = s.pending;
+            void _done;
+            const settled = Object.keys(pending).length === 0 && !s.markAll;
+            return { ...s, pending, items: s.items.map((n) => (n.id === a.id ? a.notification : n)), unreadCount: settled ? a.unreadCount : s.unreadCount };
+        }
+        case 'markReadFailed': {
+            const previous = s.pending[a.id];
+            if (!previous)
+                return s;
+            const { [a.id]: _undone, ...pending } = s.pending;
+            void _undone;
+            return { ...s, pending, items: s.items.map((n) => (n.id === a.id ? previous : n)), unreadCount: s.unreadCount + 1, actionFailed: true };
+        }
+        case 'markAllOptimistic':
+            if (!canMarkAll(s))
+                return s;
+            return { ...s, markAll: { items: s.items, unreadCount: s.unreadCount }, items: s.items.map((n) => asRead(n, a.at)), unreadCount: 0 };
+        case 'markAllConfirmed':
+            return s.markAll ? { ...s, markAll: null, unreadCount: a.unreadCount } : s;
+        case 'markAllFailed':
+            return s.markAll ? { ...s, markAll: null, items: s.markAll.items, unreadCount: s.markAll.unreadCount, actionFailed: true } : s;
+        case 'messageCleared':
+            return s.actionFailed ? { ...s, actionFailed: false } : s;
+    }
+}
+/** "Mark all as read" is offered only when something is unread and no such request is running (12.8). */
+function canMarkAll(s) {
+    return s.unreadCount > 0 && s.markAll === null;
+}

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_INBOX_LABELS = exports.InboxFullList = exports.NotificationBell = exports.InboxProvider = void 0;
+/**
+ * The in-app inbox for an app: a bell with an unread badge, a panel, a full list and the person's preference.
+ * The bell shows what this app sent the person, and the tenant's announcements.
+ *
+ *   import { InboxProvider, NotificationBell } from '@xtremax/pigeon/inbox-react';
+ *   import '@xtremax/pigeon/inbox-react/styles.css';
+ *
+ *   <InboxProvider>
+ *     <NotificationBell />
+ *   </InboxProvider>
+ *
+ * The components call the host app's own routes (default `/api/communication/inbox`), which
+ * `createInboxHandler` from `@xtremax/pigeon/inbox` serves. They need React 19, Mantine 8 and Tabler icons. Nothing here holds a key or talks to another origin.
+ */
+var inbox_provider_1 = require("./inbox-provider");
+Object.defineProperty(exports, "InboxProvider", { enumerable: true, get: function () { return inbox_provider_1.InboxProvider; } });
+var notification_bell_1 = require("./notification-bell");
+Object.defineProperty(exports, "NotificationBell", { enumerable: true, get: function () { return notification_bell_1.NotificationBell; } });
+var inbox_full_list_1 = require("./inbox-full-list");
+Object.defineProperty(exports, "InboxFullList", { enumerable: true, get: function () { return inbox_full_list_1.InboxFullList; } });
+var labels_1 = require("./labels");
+Object.defineProperty(exports, "DEFAULT_INBOX_LABELS", { enumerable: true, get: function () { return labels_1.DEFAULT_INBOX_LABELS; } });

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

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_INBOX_LABELS = void 0;
+exports.mergeLabels = mergeLabels;
+exports.DEFAULT_INBOX_LABELS = {
+    bell: 'Notifications',
+    bellWithCount: '{label}, {n} unread',
+    heading: 'Notifications',
+    tabAll: 'All',
+    tabUnread: 'Unread',
+    tabUnreadWithCount: 'Unread ({n})',
+    markAllRead: 'Mark all as read',
+    viewAll: 'View all',
+    preferences: 'Notification preferences',
+    emptyAll: 'You have no notifications.',
+    emptyUnread: 'You have no unread notifications.',
+    loading: 'Loading notifications',
+    loadError: 'Notifications could not be loaded.',
+    retry: 'Try again',
+    actionError: 'That did not work. Try again.',
+    dismiss: 'Dismiss',
+    close: 'Close',
+    unread: 'Unread',
+    announcement: 'Announcement',
+    loadMore: 'Show older notifications',
+    newOne: '1 new notification',
+    newMany: '{n} new notifications',
+    fullListTitle: 'All notifications',
+    preferencesTitle: 'Notification preferences',
+    preferenceToggle: 'Receive in-app notifications',
+    preferenceOn: 'New notifications from this app appear here.',
+    preferenceOff: 'New notifications from this app do not appear here. The ones you already have stay. Other apps are not affected.',
+    preferenceLoadError: 'Your preference could not be loaded.',
+    preferenceSaveError: 'Your choice was not saved. Try again.',
+};
+function mergeLabels(labels) {
+    return { ...exports.DEFAULT_INBOX_LABELS, ...(labels ?? {}) };
+}

package/dist/cjs/inbox-react/notification-bell.js

@@ -0,0 +1,32 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationBell = NotificationBell;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const core_1 = require("@mantine/core");
+const hooks_1 = require("@mantine/hooks");
+const icons_react_1 = require("@tabler/icons-react");
+const format_1 = require("./format");
+const inbox_context_1 = require("./inbox-context");
+const inbox_panel_1 = require("./inbox-panel");
+/** The bell with its unread badge. Opens the inbox panel. Place it inside `InboxProvider`. */
+function NotificationBell({ size = 44 }) {
+    const { state, labels, panelOpened, openPanel, closePanel, bellRef } = (0, inbox_context_1.useInbox)();
+    const reduceMotion = (0, hooks_1.useReducedMotion)();
+    const badge = (0, format_1.badgeText)(state.unreadCount);
+    // A rise of the count while the panel is closed is announced, without moving focus (15.4). The first count is not news.
+    const [announcement, setAnnouncement] = (0, react_1.useState)('');
+    const known = (0, react_1.useRef)(null);
+    (0, react_1.useEffect)(() => {
+        if (state.lastSyncedAt === null)
+            return;
+        const before = known.current;
+        known.current = state.unreadCount;
+        if (before === null || state.unreadCount <= before || panelOpened)
+            return;
+        const rise = state.unreadCount - before;
+        setAnnouncement(rise === 1 ? labels.newOne : (0, format_1.fill)(labels.newMany, { n: rise }));
+    }, [state.unreadCount, state.lastSyncedAt, panelOpened, labels]);
+    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(core_1.Indicator, { inline: true, label: badge, disabled: !badge, size: 18, offset: 8, children: (0, jsx_runtime_1.jsxs)(core_1.Popover, { opened: panelOpened, onChange: (opened) => (opened ? openPanel() : closePanel()), position: "bottom-end", shadow: "md", trapFocus: true, returnFocus: true, closeOnEscape: true, withinPortal: true, transitionProps: reduceMotion ? { duration: 0 } : undefined, children: [(0, jsx_runtime_1.jsx)(core_1.Popover.Target, { children: (0, jsx_runtime_1.jsx)(core_1.ActionIcon, { ref: bellRef, variant: "subtle", color: "gray", radius: "xl", size: Math.max(44, size), "aria-label": (0, format_1.bellName)(labels, state.unreadCount), onClick: () => (panelOpened ? closePanel() : openPanel()), children: (0, jsx_runtime_1.jsx)(icons_react_1.IconBell, { size: 22, stroke: 1.75, "aria-hidden": "true" }) }) }), (0, jsx_runtime_1.jsx)(core_1.Popover.Dropdown, { p: 0, style: { width: 'min(380px, calc(100vw - 16px))' }, children: (0, jsx_runtime_1.jsx)(inbox_panel_1.InboxPanel, {}) })] }) }), (0, jsx_runtime_1.jsx)(core_1.VisuallyHidden, { role: "status", "aria-live": "polite", children: announcement })] }));
+}

package/dist/cjs/inbox-react/notification-item.js

@@ -0,0 +1,17 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationItem = NotificationItem;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const core_1 = require("@mantine/core");
+const format_1 = require("./format");
+const inbox_context_1 = require("./inbox-context");
+/**
+ * One notification. The whole row is one button: selecting it marks the notification read and opens its link when
+ * it has a safe one. Title and body are text nodes, never markup (12.14).
+ */
+function NotificationItem({ item, now }) {
+    const { labels, locale, select } = (0, inbox_context_1.useInbox)();
+    const unread = !item.read;
+    return ((0, jsx_runtime_1.jsxs)(core_1.UnstyledButton, { className: "xci-row", onClick: () => select(item), "data-unread": unread || undefined, children: [(0, jsx_runtime_1.jsx)("span", { className: "xci-dot", "data-unread": unread || undefined, "aria-hidden": "true" }), (0, jsx_runtime_1.jsxs)("span", { className: "xci-content", children: [unread && (0, jsx_runtime_1.jsxs)(core_1.VisuallyHidden, { children: [labels.unread, "."] }), (0, jsx_runtime_1.jsxs)("span", { className: "xci-meta", children: [(0, jsx_runtime_1.jsx)(core_1.Text, { component: "span", size: "xs", c: "dimmed", truncate: true, children: item.source.name }), item.kind === 'announcement' && ((0, jsx_runtime_1.jsx)(core_1.Badge, { component: "span", size: "xs", variant: "light", style: { flex: 'none' }, children: labels.announcement }))] }), (0, jsx_runtime_1.jsx)(core_1.Text, { component: "span", className: "xci-line", size: "sm", fw: unread ? 700 : 400, lineClamp: 2, children: item.title }), (0, jsx_runtime_1.jsx)(core_1.Text, { component: "span", className: "xci-line", size: "sm", c: "dimmed", lineClamp: 3, children: item.body }), (0, jsx_runtime_1.jsx)(core_1.Text, { component: "time", className: "xci-line", size: "xs", c: "dimmed", dateTime: item.createdAt, title: (0, format_1.exactTime)(item.createdAt, locale), children: (0, format_1.relativeTime)(item.createdAt, now, locale) })] })] }));
+}

package/dist/cjs/inbox-react/parse.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseNotification = parseNotification;
+exports.parseSummary = parseSummary;
+exports.parsePage = parsePage;
+exports.parseMarkRead = parseMarkRead;
+exports.parseReadAll = parseReadAll;
+exports.parsePreference = parsePreference;
+exports.parseErrorCode = parseErrorCode;
+const types_1 = require("./types");
+/**
+ * Tolerant parsing (17.4): each parser takes only the fields it knows and ignores the rest at any depth, so a field
+ * added later changes nothing here. A value that lacks a known field gives `null`, never a half-filled object.
+ */
+const obj = (v) => (typeof v === 'object' && v !== null && !Array.isArray(v) ? v : null);
+const str = (v) => (typeof v === 'string' ? v : null);
+const strOrNull = (v) => (v === null ? null : typeof v === 'string' ? v : undefined);
+const count = (v) => (typeof v === 'number' && Number.isInteger(v) && v >= 0 ? v : null);
+function parseNotification(v) {
+    const o = obj(v);
+    const source = obj(o?.source);
+    if (!o || !source)
+        return null;
+    const id = str(o.id);
+    const title = str(o.title);
+    const body = str(o.body);
+    const createdAt = str(o.createdAt);
+    const link = strOrNull(o.link);
+    const readAt = strOrNull(o.readAt);
+    const name = str(source.name);
+    if (id === null || title === null || body === null || createdAt === null || link === undefined || readAt === undefined || name === null)
+        return null;
+    if (o.kind !== 'notification' && o.kind !== 'announcement')
+        return null;
+    if (source.type !== 'xapp' && source.type !== 'tenant')
+        return null;
+    if (typeof o.read !== 'boolean')
+        return null;
+    return { id, kind: o.kind, title, body, link, source: { type: source.type, name }, createdAt, read: o.read, readAt };
+}
+function parseSummary(v) {
+    const o = obj(v);
+    if (!o)
+        return null;
+    const unreadCount = count(o.unreadCount);
+    const newestUnreadAt = strOrNull(o.newestUnreadAt);
+    const pollSeconds = count(o.pollSeconds);
+    return unreadCount === null || newestUnreadAt === undefined || pollSeconds === null ? null : { unreadCount, newestUnreadAt, pollSeconds };
+}
+function parsePage(v) {
+    const o = obj(v);
+    if (!o || !Array.isArray(o.notifications))
+        return null;
+    const notifications = [];
+    for (const raw of o.notifications) {
+        const n = parseNotification(raw);
+        if (!n)
+            return null;
+        notifications.push(n);
+    }
+    const nextCursor = strOrNull(o.nextCursor);
+    const unreadCount = count(o.unreadCount);
+    return nextCursor === undefined || unreadCount === null ? null : { notifications, nextCursor, unreadCount };
+}
+function parseMarkRead(v) {
+    const o = obj(v);
+    const notification = parseNotification(o?.notification);
+    const unreadCount = count(o?.unreadCount);
+    return notification && unreadCount !== null ? { notification, unreadCount } : null;
+}
+function parseReadAll(v) {
+    const o = obj(v);
+    const marked = count(o?.marked);
+    const remaining = count(o?.remaining);
+    const unreadCount = count(o?.unreadCount);
+    return marked === null || remaining === null || unreadCount === null ? null : { marked, remaining, unreadCount };
+}
+function parsePreference(v) {
+    const o = obj(v);
+    if (!o)
+        return null;
+    const changedAt = strOrNull(o.changedAt);
+    if (o.state !== 'opted_in' && o.state !== 'opted_out' && o.state !== 'not_set')
+        return null;
+    return changedAt === undefined || typeof o.delivers !== 'boolean' ? null : { state: o.state, changedAt, delivers: o.delivers };
+}
+/** The code of an error body, or the nearest one for the status. Anything unknown is `unavailable`. */
+function parseErrorCode(status, body) {
+    const code = obj(obj(body)?.error)?.code;
+    if (typeof code === 'string' && types_1.INBOX_ERROR_CODES.includes(code))
+        return code;
+    const byStatus = { 401: 'not_signed_in', 403: 'not_permitted', 404: 'not_found', 422: 'invalid_input', 429: 'rate_limited' };
+    return byStatus[status] ?? 'unavailable';
+}

package/dist/cjs/inbox-react/preference-dialog.js

@@ -0,0 +1,49 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreferenceDialog = PreferenceDialog;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const core_1 = require("@mantine/core");
+const hooks_1 = require("@mantine/hooks");
+const inbox_context_1 = require("./inbox-context");
+/** The person's own choice for this app's in-app notifications. Other apps are not affected. */
+function PreferenceDialog({ opened, onClose }) {
+    const { client, labels } = (0, inbox_context_1.useInbox)();
+    const reduceMotion = (0, hooks_1.useReducedMotion)();
+    const [preference, setPreference] = (0, react_1.useState)(null);
+    const [status, setStatus] = (0, react_1.useState)('loading');
+    const [saving, setSaving] = (0, react_1.useState)(false);
+    const [saveFailed, setSaveFailed] = (0, react_1.useState)(false);
+    const load = (0, react_1.useCallback)(async () => {
+        setStatus('loading');
+        const res = await client.getPreference();
+        if (res.ok)
+            setPreference(res.data);
+        setStatus(res.ok ? 'ready' : 'error');
+    }, [client]);
+    (0, react_1.useEffect)(() => {
+        if (!opened)
+            return;
+        setSaveFailed(false);
+        void load();
+    }, [opened, load]);
+    // The switch moves at once; a failure moves it back and says so.
+    const change = async (on) => {
+        if (!preference || saving)
+            return;
+        const before = preference;
+        setSaveFailed(false);
+        setSaving(true);
+        setPreference({ ...preference, state: on ? 'opted_in' : 'opted_out', delivers: on });
+        const res = await client.setPreference(on ? 'opted_in' : 'opted_out');
+        setSaving(false);
+        if (res.ok)
+            setPreference(res.data);
+        else {
+            setPreference(before);
+            setSaveFailed(true);
+        }
+    };
+    return ((0, jsx_runtime_1.jsxs)(core_1.Modal, { opened: opened, onClose: onClose, title: labels.preferencesTitle, closeButtonProps: { 'aria-label': labels.close }, returnFocus: false, transitionProps: reduceMotion ? { duration: 0 } : undefined, children: [status === 'loading' && ((0, jsx_runtime_1.jsx)(core_1.Center, { mih: 96, role: "status", "aria-label": labels.loading, children: (0, jsx_runtime_1.jsx)(core_1.Loader, { size: "sm" }) })), status === 'error' && ((0, jsx_runtime_1.jsx)(core_1.Alert, { color: "red", variant: "light", title: labels.preferenceLoadError, children: (0, jsx_runtime_1.jsx)(core_1.Button, { variant: "default", size: "sm", mih: 44, onClick: () => void load(), children: labels.retry }) })), status === 'ready' && preference && ((0, jsx_runtime_1.jsxs)(core_1.Stack, { gap: "sm", children: [(0, jsx_runtime_1.jsx)(core_1.Switch, { label: labels.preferenceToggle, description: preference.delivers ? labels.preferenceOn : labels.preferenceOff, checked: preference.state === 'not_set' ? preference.delivers : preference.state === 'opted_in', onChange: (event) => void change(event.currentTarget.checked) }), saveFailed && ((0, jsx_runtime_1.jsx)(core_1.Alert, { color: "red", variant: "light", role: "alert", children: labels.preferenceSaveError }))] }))] }));
+}

package/dist/cjs/inbox-react/types.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INBOX_ERROR_CODES = void 0;
+exports.INBOX_ERROR_CODES = ['not_signed_in', 'not_permitted', 'not_found', 'invalid_input', 'rate_limited', 'unavailable'];

package/dist/cjs/inbox-react/use-inbox-polling.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POLL_CAP_SECONDS = exports.POLL_FLOOR_SECONDS = void 0;
+exports.nextPollDelay = nextPollDelay;
+exports.startPolling = startPolling;
+exports.useInboxPolling = useInboxPolling;
+const react_1 = require("react");
+exports.POLL_FLOOR_SECONDS = 15;
+exports.POLL_CAP_SECONDS = 300;
+/**
+ * Seconds until the next poll. After a success: the recommended interval, at least 15. After failures:
+ * `min(300, base * 2^failures)` with plus or minus 20 percent jitter, still between 15 and 300.
+ */
+function nextPollDelay(failures, recommendedSeconds, random = Math.random) {
+    const base = Math.max(exports.POLL_FLOOR_SECONDS, Number.isFinite(recommendedSeconds) ? recommendedSeconds : 60);
+    if (failures <= 0)
+        return base;
+    const backoff = Math.min(exports.POLL_CAP_SECONDS, base * 2 ** Math.min(failures, 16));
+    const jitter = 0.8 + 0.4 * Math.min(1, Math.max(0, random()));
+    return Math.min(exports.POLL_CAP_SECONDS, Math.max(exports.POLL_FLOOR_SECONDS, backoff * jitter));
+}
+/**
+ * Polls now, then after each answer waits `nextPollDelay`. Pauses while the page is hidden and polls at once when it
+ * is visible again. `stop` (nobody is signed in) ends polling silently. Returns a function that stops it.
+ */
+function startPolling(poll, env) {
+    let stopped = false;
+    let running = false;
+    let failures = 0;
+    let recommended = 60;
+    let timer = null;
+    const tick = async () => {
+        if (stopped || running || !env.isVisible())
+            return;
+        running = true;
+        let outcome;
+        try {
+            outcome = await poll();
+        }
+        catch {
+            outcome = { result: 'failed' };
+        }
+        running = false;
+        if (stopped)
+            return;
+        if (outcome.result === 'stop') {
+            stopped = true;
+            return;
+        }
+        if (outcome.result === 'ok') {
+            failures = 0;
+            recommended = outcome.pollSeconds;
+        }
+        else
+            failures += 1;
+        timer = env.setTimer(() => void tick(), nextPollDelay(failures, recommended, env.random) * 1000);
+    };
+    const unsubscribe = env.onVisibilityChange(() => {
+        if (stopped)
+            return;
+        env.clearTimer(timer);
+        timer = null;
+        if (env.isVisible())
+            void tick();
+    });
+    void tick();
+    return () => {
+        stopped = true;
+        env.clearTimer(timer);
+        unsubscribe();
+    };
+}
+const browserEnvironment = () => ({
+    isVisible: () => document.visibilityState !== 'hidden',
+    onVisibilityChange: (listener) => {
+        document.addEventListener('visibilitychange', listener);
+        return () => document.removeEventListener('visibilitychange', listener);
+    },
+    setTimer: (fn, ms) => window.setTimeout(fn, ms),
+    clearTimer: (handle) => window.clearTimeout(handle),
+    random: Math.random,
+});
+/** Runs `poll` for as long as the component is mounted and `enabled` is true. `poll` may change between renders. */
+function useInboxPolling(poll, enabled = true) {
+    const latest = (0, react_1.useRef)(poll);
+    (0, react_1.useEffect)(() => {
+        latest.current = poll;
+    }, [poll]);
+    (0, react_1.useEffect)(() => {
+        if (!enabled)
+            return undefined;
+        return startPolling(() => latest.current(), browserEnvironment());
+    }, [enabled]);
+}

package/dist/cjs/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RETRY = exports.newIdempotencyKey = exports.deriveIdempotencyKey = exports.verifyEventSignature = exports.createEventHandler = exports.CommunicationError = exports.createCommunicationClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "createCommunicationClient", { enumerable: true, get: function () { return client_1.createCommunicationClient; } });
+Object.defineProperty(exports, "CommunicationError", { enumerable: true, get: function () { return client_1.CommunicationError; } });
+var events_1 = require("./events");
+Object.defineProperty(exports, "createEventHandler", { enumerable: true, get: function () { return events_1.createEventHandler; } });
+Object.defineProperty(exports, "verifyEventSignature", { enumerable: true, get: function () { return events_1.verifyEventSignature; } });
+var idempotency_1 = require("./idempotency");
+Object.defineProperty(exports, "deriveIdempotencyKey", { enumerable: true, get: function () { return idempotency_1.deriveIdempotencyKey; } });
+Object.defineProperty(exports, "newIdempotencyKey", { enumerable: true, get: function () { return idempotency_1.newIdempotencyKey; } });
+var retry_1 = require("./retry");
+Object.defineProperty(exports, "DEFAULT_RETRY", { enumerable: true, get: function () { return retry_1.DEFAULT_RETRY; } });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/retry.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRetryableStatus = exports.DEFAULT_RETRY = void 0;
+exports.backoffMs = backoffMs;
+exports.DEFAULT_RETRY = { maxAttempts: 3, baseDelayMs: 250, capDelayMs: 5000, totalTimeoutMs: 25_000, perAttemptTimeoutMs: 10_000 };
+/** Exponential backoff with full jitter, honouring Retry-After when the server sent one. */
+function backoffMs(attempt, policy, retryAfterSeconds, random = Math.random) {
+    const exp = Math.min(policy.capDelayMs, policy.baseDelayMs * 2 ** (attempt - 1));
+    const jittered = Math.round(exp * (0.5 + random() * 0.5));
+    return retryAfterSeconds ? Math.min(policy.capDelayMs, Math.max(jittered, retryAfterSeconds * 1000)) : jittered;
+}
+/** Only transient failures are retried: network errors, timeouts, 429 and 5xx. Client errors never are. */
+const isRetryableStatus = (status) => status === 429 || (status >= 500 && status !== 501);
+exports.isRetryableStatus = isRetryableStatus;

package/dist/esm/browser-stub.js

@@ -0,0 +1,6 @@
+import { CommunicationError } from './errors.js';
+/** Selected by the `browser` export condition so a secret key can never be bundled into client code. */
+export function createCommunicationClient() {
+    throw new CommunicationError({ code: 'server_only', message: 'The Communication client must run on the server.' });
+}
+export { CommunicationError };