@xtremax/pigeon 0.0.0-stage → 0.3.0

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 };

package/dist/esm/client.js

@@ -0,0 +1,107 @@
+import { CommunicationError, fromResponse, redact } from './errors.js';
+import { newIdempotencyKey } from './idempotency.js';
+import { DEFAULT_RETRY, backoffMs, isRetryableStatus } from './retry.js';
+/** Where a client keeps its transport, so `@xtremax/pigeon/inbox` can reuse the key handling, retries and errors. */
+export const TRANSPORT = Symbol.for('@xtremax/pigeon.transport');
+const sleepDefault = (ms) => new Promise((r) => setTimeout(r, ms));
+export function createCommunicationClient(options = {}) {
+    if (typeof window !== 'undefined' && typeof globalThis.document !== 'undefined') {
+        throw new CommunicationError({ code: 'server_only', message: 'The Communication client holds a secret key and must run on the server.' });
+    }
+    const env = typeof process !== 'undefined' ? process.env : {};
+    const apiKey = options.apiKey ?? env.COMMUNICATION_API_KEY;
+    const baseUrl = (options.baseUrl ?? env.COMMUNICATION_URL ?? '').replace(/\/$/, '');
+    if (!apiKey || !baseUrl)
+        throw new CommunicationError({ code: 'not_configured', message: 'Set COMMUNICATION_API_KEY and COMMUNICATION_URL (the connector provides both).' });
+    const policy = { ...DEFAULT_RETRY, ...options.retry };
+    const doFetch = options.fetch ?? fetch;
+    const sleep = options.sleep ?? sleepDefault;
+    async function request(method, path, body, opts = {}) {
+        const started = Date.now();
+        const max = opts.retry === false ? 1 : policy.maxAttempts;
+        const totalMs = Math.min(policy.totalTimeoutMs, opts.timeoutMs && opts.timeoutMs > 0 ? opts.timeoutMs : policy.totalTimeoutMs);
+        let last = null;
+        for (let attempt = 1; attempt <= max; attempt += 1) {
+            const ctrl = new AbortController();
+            const timer = setTimeout(() => ctrl.abort(), Math.min(policy.perAttemptTimeoutMs, Math.max(1, totalMs - (Date.now() - started))));
+            try {
+                const res = await doFetch(`${baseUrl}/api/external/v1${path}`, {
+                    method,
+                    headers: { ...(opts.headers ?? {}), Authorization: `Bearer ${apiKey}`, Accept: 'application/json', ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}) },
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    signal: ctrl.signal,
+                    redirect: 'error',
+                });
+                const text = await res.text();
+                let parsed = null;
+                try {
+                    parsed = text ? JSON.parse(text) : null;
+                }
+                catch {
+                    if (res.ok)
+                        throw new CommunicationError({ code: 'invalid_response', message: 'The service answered with something that is not JSON', status: res.status, attempts: attempt });
+                }
+                if (res.ok)
+                    return { data: parsed.data, headers: res.headers };
+                last = fromResponse(res.status, parsed, res.headers, attempt);
+                if (!isRetryableStatus(res.status))
+                    throw last;
+            }
+            catch (e) {
+                if (e instanceof CommunicationError) {
+                    if (!e.retryable || e.code === 'invalid_response')
+                        throw e;
+                    last = e;
+                }
+                else {
+                    const aborted = e.name === 'AbortError';
+                    last = new CommunicationError({ code: aborted ? 'timeout' : 'network_error', message: aborted ? 'The request timed out' : 'The service could not be reached', retryable: true, attempts: attempt });
+                }
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            const wait = backoffMs(attempt, policy, last?.retryAfterSeconds ?? null, options.random);
+            if (attempt >= max || Date.now() - started + wait >= totalMs)
+                break;
+            await sleep(wait);
+        }
+        throw new CommunicationError({ code: last?.code ?? 'unknown_error', apiCode: last?.apiCode, message: last?.message ?? 'The request failed', status: last?.status, requestId: last?.requestId, details: last?.details, retryable: true, retryAfterSeconds: last?.retryAfterSeconds, attempts: Math.min(max, policy.maxAttempts) });
+    }
+    const put = (path, body) => request('PUT', path, body).then((r) => r.data);
+    const enc = encodeURIComponent;
+    return {
+        messages: {
+            /** Sends are retried safely because every request carries an idempotency key (yours, or a random one). */
+            async send(req) {
+                const { data } = await request('POST', '/messages', { ...req, idempotencyKey: req.idempotencyKey ?? newIdempotencyKey() });
+                return data;
+            },
+            get: (id) => request('GET', `/messages/${enc(id)}`).then((r) => r.data),
+        },
+        channels: { list: () => request('GET', '/channels').then((r) => r.data) },
+        ping: () => request('GET', '/ping').then((r) => r.data),
+        recipients: {
+            put: (personId, body) => put(`/recipients/${enc(personId)}`, body),
+            get: (personId) => request('GET', `/recipients/${enc(personId)}`).then((r) => r.data),
+            async delete(personId) {
+                await request('DELETE', `/recipients/${enc(personId)}`);
+            },
+            putAddress: (personId, body) => put(`/recipients/${enc(personId)}/addresses`, body),
+            async deleteAddress(personId, addressId) {
+                await request('DELETE', `/recipients/${enc(personId)}/addresses/${enc(addressId)}`);
+            },
+        },
+        preferences: {
+            record: (body) => request('POST', '/preferences', body).then((r) => r.data),
+        },
+        messageClasses: {
+            put: (templateKey, body) => put(`/message-classes/${enc(templateKey)}`, body),
+            list: () => request('GET', '/message-classes').then((r) => r.data),
+        },
+        /** For logs: never prints the key. */
+        describe: () => redact(`CommunicationClient(${baseUrl})`),
+        [TRANSPORT]: request,
+    };
+}
+export { CommunicationError } from './errors.js';

package/dist/esm/contract.js

@@ -0,0 +1,2 @@
+/** Types mirrored from the Gateway's external API (types only; safe in any bundle). */
+export const SUPPORTED_API_VERSION = 'v1';

package/dist/esm/errors.js

@@ -0,0 +1,42 @@
+const KEY_PATTERN = /cgk_[A-Za-z0-9]{8}_[A-Za-z0-9_-]{43}/g;
+/** Removes anything shaped like a key from text that may be logged. */
+export const redact = (text) => text.replace(KEY_PATTERN, 'cgk_[redacted]').replace(/Bearer\s+\S+/gi, 'Bearer [redacted]');
+export class CommunicationError extends Error {
+    code;
+    apiCode;
+    status;
+    requestId;
+    details;
+    retryable;
+    retryAfterSeconds;
+    attempts;
+    constructor(init) {
+        super(redact(init.message));
+        this.name = 'CommunicationError';
+        this.code = init.code;
+        this.apiCode = init.apiCode ?? null;
+        this.status = init.status ?? null;
+        this.requestId = init.requestId ?? null;
+        this.details = init.details ?? [];
+        this.retryable = init.retryable ?? false;
+        this.retryAfterSeconds = init.retryAfterSeconds ?? null;
+        this.attempts = init.attempts ?? 1;
+    }
+    toJSON() {
+        return { name: this.name, code: this.code, message: this.message, status: this.status, requestId: this.requestId, retryable: this.retryable, attempts: this.attempts };
+    }
+}
+const KNOWN = [
+    'invalid_json', 'invalid_credentials', 'forbidden', 'not_found', 'idempotency_conflict', 'payload_too_large', 'unsupported_media_type', 'validation_failed',
+    'channel_unavailable', 'tls_required', 'rate_limited', 'internal_error', 'temporarily_unavailable', 'conflict',
+];
+export function fromResponse(status, body, headers, attempts) {
+    const err = body?.error;
+    const apiCode = err?.code ?? null;
+    const code = apiCode && KNOWN.includes(apiCode) ? apiCode : 'unknown_error';
+    const retryAfter = Number(headers.get('retry-after'));
+    return new CommunicationError({
+        code, apiCode, status, requestId: err?.requestId ?? headers.get('x-request-id'), details: err?.details ?? [],
+        message: err?.message ?? `The request failed with status ${status}`, retryable: status === 429 || status >= 500, retryAfterSeconds: Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : null, attempts,
+    });
+}

package/dist/esm/events.js

@@ -0,0 +1,57 @@
+import { CommunicationError } from './errors.js';
+export const DEFAULT_TOLERANCE_SECONDS = 300;
+const toHex = (buf) => Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, '0')).join('');
+async function hmac(secret, data) {
+    const key = await globalThis.crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return toHex(await globalThis.crypto.subtle.sign('HMAC', key, new TextEncoder().encode(data)));
+}
+function equal(a, b) {
+    let diff = a.length ^ b.length;
+    for (let i = 0; i < Math.max(a.length, b.length); i += 1)
+        diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+    return diff === 0;
+}
+/** Verifies `X-Communication-Signature` over `timestamp + "." + rawBody`. Pass the RAW body text, not a parsed object. During secret rotation the header carries two values; either may match. */
+export async function verifyEventSignature(input) {
+    if (!input.timestamp || !input.signature)
+        return { valid: false, reason: 'missing' };
+    const ts = Number(input.timestamp);
+    if (!Number.isFinite(ts))
+        return { valid: false, reason: 'missing' };
+    const now = input.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(now - ts) > (input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS))
+        return { valid: false, reason: 'stale' };
+    const presented = input.signature.split(/[,\s]+/).filter(Boolean);
+    for (const secret of Array.isArray(input.secret) ? input.secret : [input.secret]) {
+        const expected = `v1=${await hmac(secret, `${input.timestamp}.${input.rawBody}`)}`;
+        if (presented.some((p) => equal(p, expected)))
+            return { valid: true };
+    }
+    return { valid: false, reason: 'mismatch' };
+}
+/** A ready-made handler for a Next.js route or any Request/Response runtime. Answers 2xx only after `onEvent` succeeded. */
+export function createEventHandler(options) {
+    return async (req) => {
+        const rawBody = await req.text();
+        const verdict = await verifyEventSignature({ secret: options.secret, timestamp: req.headers.get('x-communication-timestamp'), signature: req.headers.get('x-communication-signature'), rawBody, toleranceSeconds: options.toleranceSeconds });
+        if (!verdict.valid)
+            return new Response(null, { status: 401 });
+        let event;
+        try {
+            event = JSON.parse(rawBody);
+        }
+        catch {
+            return new Response(null, { status: 400 });
+        }
+        if (event.type !== 'message.state_changed' || event.version !== 1)
+            return new Response(null, { status: 204 }); // unknown future types are acknowledged and ignored
+        try {
+            if (!(await options.alreadyProcessed?.(event)))
+                await options.onEvent(event);
+        }
+        catch (e) {
+            throw new CommunicationError({ code: 'unknown_error', message: e instanceof Error ? e.message : 'The event handler failed', retryable: true });
+        }
+        return new Response(null, { status: 204 });
+    };
+}

package/dist/esm/idempotency.js

@@ -0,0 +1,10 @@
+/** A random key for a send you will not retry yourself. Prefer `deriveIdempotencyKey` so your own retries are safe too. */
+export function newIdempotencyKey() {
+    return `sdk-${globalThis.crypto.randomUUID()}`;
+}
+/** A stable key derived from parts you choose, for example an order id and an event name. Same input, same key. */
+export async function deriveIdempotencyKey(...parts) {
+    const data = new TextEncoder().encode(parts.map(String).join('\u001f'));
+    const hash = await globalThis.crypto.subtle.digest('SHA-256', data);
+    return `d-${Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, '0')).join('').slice(0, 48)}`;
+}

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

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