@xtremax/pigeon 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.3.0
+- The package is named `@xtremax/pigeon`. Earlier versions were called `@xtremax/communication` and were never published. Only the import path changes: function names, environment variables and headers are the same.
+- New entry `@xtremax/pigeon/inbox-react`: the notification bell (`InboxProvider`, `NotificationBell`, `InboxFullList`), with its stylesheet at `@xtremax/pigeon/inbox-react/styles.css`. It replaces the files that were copied into each app. React 19, Mantine 8 and `@tabler/icons-react` are optional peer dependencies.
+- `createInboxHandler` no longer needs `client`: without one it makes a client on the first request from `COMMUNICATION_API_KEY` and `COMMUNICATION_URL`, and a missing one answers `unavailable`.
+- The ESM build loads in plain Node: relative imports carry their file extension.
+- Moving from the copied files: remove `components/ui/communication-inbox/`, import from `@xtremax/pigeon/inbox-react`, and import the stylesheet once. The preference switch is now Mantine's `Switch`.
+
+## 0.2.0
+- New entry `@xtremax/pigeon/inbox` (server only): `createInboxClient` (summary, list, mark read, mark all read, preference) and `createInboxHandler`, the host xApp's browser-facing inbox routes in one function.
+- `ping()` also answers `subKey`: the sub-tenant the key belongs to, whose notifications the inbox calls return.
+- Inbox types in `/contract`: `InboxNotification`, `InboxSummary`, `InboxNotificationPage`, `InboxPreference`, `InboxHostErrorCode`.
+- No change to existing calls.
+
+## 0.1.0
+- First release: `createCommunicationClient` (messages, channels, ping, recipients, preferences, message classes), `createEventHandler`, `verifyEventSignature`, `deriveIdempotencyKey`, contract types.

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# @xtremax/pigeon
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Client for Pigeon, the Buildpad Communication Gateway. Send email, WhatsApp and in-app notifications through one call, verify signed delivery events, and show a person their in-app notifications with a ready-made bell.
+
+```bash
+npm install @xtremax/pigeon
+```
+
+The names in the code say `Communication` (`createCommunicationClient`, `COMMUNICATION_API_KEY`): that is the service's name on the Buildpad platform, where Pigeon is the Communication connector.
+
+```ts
+import { createCommunicationClient } from '@xtremax/pigeon/client';
+const communication = createCommunicationClient(); // COMMUNICATION_API_KEY and COMMUNICATION_URL
+
+await communication.messages.send({ templateKey: 'welcome', channel: 'email-main', recipient: { personId: 'ana@acme.com' }, variables: { name: 'Ana' } });
+```
+
+- **Server only.** The client holds a secret key; importing it in a browser bundle resolves to a stub that throws `server_only`.
+- **Safe retries.** Network errors, timeouts, `429` and `5xx` are retried (3 attempts, 250 ms base, 5 s cap, 25 s total, honouring `Retry-After`). Every send carries an idempotency key, so a retry never sends twice. Client errors are never retried.
+- **Errors you can branch on.** `CommunicationError` with `code`, `status`, `requestId`, `details`, `retryable`. The key never appears in an error.
+- **Events.** `createEventHandler` and `verifyEventSignature` (`@xtremax/pigeon/events`) check the HMAC over the raw body, the five-minute window and secret rotation.
+
+## In-app inbox
+
+A person's in-app notifications are read through your app's own server, never from the browser. Two pieces: one catch-all route, and the bell.
+
+```ts
+// app/api/communication/inbox/[...path]/route.ts
+import { createInboxHandler } from '@xtremax/pigeon/inbox';
+
+const handler = createInboxHandler({
+  resolvePerson: async () => (await currentUser())?.email ?? null, // your own session
+});
+export { handler as GET, handler as POST, handler as PUT };
+```
+
+```tsx
+// in your header, a client component
+import { InboxProvider, NotificationBell } from '@xtremax/pigeon/inbox-react';
+import '@xtremax/pigeon/inbox-react/styles.css'; // once, after Mantine's styles
+
+<InboxProvider>
+  <NotificationBell />
+</InboxProvider>
+```
+
+- **The bell needs** React 19, Mantine 8 (`@mantine/core`, `@mantine/hooks`) and `@tabler/icons-react` in your app. They are optional peers: an app that only sends needs none of them. The bell follows your Mantine theme and colour scheme.
+- **`InboxProvider` takes** `apiBase` (default `/api/communication/inbox`), `labels` (every visible and spoken text), `locale`, `onViewAll`, `onOpenPreferences` and `openLink`. `InboxFullList` is the full list, for a page of your own.
+- **The key and the address** (`COMMUNICATION_API_KEY`, `COMMUNICATION_URL`) are read on the first request. A missing one answers `unavailable`; pass `onError` to see why in your server log. Pass `client` to use a client of your own.
+
+- **One function is yours:** `resolvePerson(request)` returns the signed-in person's id from your own session, or `null`. Use the same id you send to as `personId`. The handler never reads a person from the path, query or body.
+- **Scopes:** the key needs `inbox:read` and `inbox:write`.
+- **What the browser can get wrong is bounded:** six operations, validated input, a same-origin check on POST and PUT, `Cache-Control: no-store`, and six fixed error codes (`not_signed_in`, `not_permitted`, `not_found`, `invalid_input`, `rate_limited`, `unavailable`).
+- **Direct calls:** `createInboxClient()` has `summary`, `list`, `markRead`, `markAllRead`, `getPreference` and `setPreference`, each taking the person id first.
+- **What a key sees:** what its own sub-tenant (or the tenant level, for a key outside any) sent the person, and the tenant's announcements. Another app's notifications are not part of it, and the on/off preference is this app's own. `ping()` returns the key's `subKey`.
+
+Entry points: `/client`, `/inbox`, `/events` and `/contract` (types only) for the server; `/inbox-react` and `/inbox-react/styles.css` for the browser. Node 20 or later. Below 1.0 a breaking change raises the minor version.

package/dist/cjs/browser-stub.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommunicationError = void 0;
+exports.createCommunicationClient = createCommunicationClient;
+const errors_1 = require("./errors");
+Object.defineProperty(exports, "CommunicationError", { enumerable: true, get: function () { return errors_1.CommunicationError; } });
+/** Selected by the `browser` export condition so a secret key can never be bundled into client code. */
+function createCommunicationClient() {
+    throw new errors_1.CommunicationError({ code: 'server_only', message: 'The Communication client must run on the server.' });
+}

package/dist/cjs/client.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommunicationError = exports.TRANSPORT = void 0;
+exports.createCommunicationClient = createCommunicationClient;
+const errors_1 = require("./errors");
+const idempotency_1 = require("./idempotency");
+const retry_1 = require("./retry");
+/** Where a client keeps its transport, so `@xtremax/pigeon/inbox` can reuse the key handling, retries and errors. */
+exports.TRANSPORT = Symbol.for('@xtremax/pigeon.transport');
+const sleepDefault = (ms) => new Promise((r) => setTimeout(r, ms));
+function createCommunicationClient(options = {}) {
+    if (typeof window !== 'undefined' && typeof globalThis.document !== 'undefined') {
+        throw new errors_1.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 errors_1.CommunicationError({ code: 'not_configured', message: 'Set COMMUNICATION_API_KEY and COMMUNICATION_URL (the connector provides both).' });
+    const policy = { ...retry_1.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 errors_1.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 = (0, errors_1.fromResponse)(res.status, parsed, res.headers, attempt);
+                if (!(0, retry_1.isRetryableStatus)(res.status))
+                    throw last;
+            }
+            catch (e) {
+                if (e instanceof errors_1.CommunicationError) {
+                    if (!e.retryable || e.code === 'invalid_response')
+                        throw e;
+                    last = e;
+                }
+                else {
+                    const aborted = e.name === 'AbortError';
+                    last = new errors_1.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 = (0, retry_1.backoffMs)(attempt, policy, last?.retryAfterSeconds ?? null, options.random);
+            if (attempt >= max || Date.now() - started + wait >= totalMs)
+                break;
+            await sleep(wait);
+        }
+        throw new errors_1.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 ?? (0, idempotency_1.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: () => (0, errors_1.redact)(`CommunicationClient(${baseUrl})`),
+        [exports.TRANSPORT]: request,
+    };
+}
+var errors_2 = require("./errors");
+Object.defineProperty(exports, "CommunicationError", { enumerable: true, get: function () { return errors_2.CommunicationError; } });

package/dist/cjs/contract.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_API_VERSION = void 0;
+/** Types mirrored from the Gateway's external API (types only; safe in any bundle). */
+exports.SUPPORTED_API_VERSION = 'v1';

package/dist/cjs/errors.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommunicationError = exports.redact = void 0;
+exports.fromResponse = fromResponse;
+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. */
+const redact = (text) => text.replace(KEY_PATTERN, 'cgk_[redacted]').replace(/Bearer\s+\S+/gi, 'Bearer [redacted]');
+exports.redact = redact;
+class CommunicationError extends Error {
+    code;
+    apiCode;
+    status;
+    requestId;
+    details;
+    retryable;
+    retryAfterSeconds;
+    attempts;
+    constructor(init) {
+        super((0, exports.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 };
+    }
+}
+exports.CommunicationError = CommunicationError;
+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',
+];
+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/cjs/events.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TOLERANCE_SECONDS = void 0;
+exports.verifyEventSignature = verifyEventSignature;
+exports.createEventHandler = createEventHandler;
+const errors_1 = require("./errors");
+exports.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. */
+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 ?? exports.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. */
+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 errors_1.CommunicationError({ code: 'unknown_error', message: e instanceof Error ? e.message : 'The event handler failed', retryable: true });
+        }
+        return new Response(null, { status: 204 });
+    };
+}

package/dist/cjs/idempotency.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newIdempotencyKey = newIdempotencyKey;
+exports.deriveIdempotencyKey = deriveIdempotencyKey;
+/** A random key for a send you will not retry yourself. Prefer `deriveIdempotencyKey` so your own retries are safe too. */
+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. */
+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/cjs/inbox/browser-stub.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInboxHandler = exports.createInboxClient = void 0;
+const errors_1 = require("../errors");
+const serverOnly = () => {
+    throw new errors_1.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. */
+exports.createInboxClient = serverOnly;
+exports.createInboxHandler = serverOnly;

package/dist/cjs/inbox/client.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.personHeader = personHeader;
+exports.createInboxClient = createInboxClient;
+const client_1 = require("../client");
+/** `X-Communication-Person` is base64url of the UTF-8 person id, so any identifier travels safely in a header. */
+function personHeader(personId) {
+    let binary = '';
+    for (const byte of new TextEncoder().encode(personId))
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+const isClient = (v) => client_1.TRANSPORT in v;
+/**
+ * The in-app inbox of one person. Pass an existing client to share its key and settings, or the same options as
+ * `createCommunicationClient`. The key needs the scopes `inbox:read` and `inbox:write`.
+ */
+function createInboxClient(client = {}) {
+    const request = (isClient(client) ? client : (0, client_1.createCommunicationClient)(client))[client_1.TRANSPORT];
+    const call = (method, path, personId, body, read, options = {}) => request(method, path, body, { headers: { 'X-Communication-Person': personHeader(personId) }, retry: options.retry ?? read, timeoutMs: options.timeoutMs }).then((r) => r.data);
+    return {
+        summary: (personId, options) => call('GET', '/inbox/summary', personId, undefined, true, options),
+        list(personId, query = {}, options) {
+            const q = new URLSearchParams();
+            if (query.limit !== undefined)
+                q.set('limit', String(query.limit));
+            if (query.cursor)
+                q.set('cursor', query.cursor);
+            if (query.unreadOnly)
+                q.set('unread', 'true');
+            const qs = q.toString();
+            return call('GET', `/inbox/notifications${qs ? `?${qs}` : ''}`, personId, undefined, true, options);
+        },
+        markRead: (personId, id, options) => call('POST', `/inbox/notifications/${encodeURIComponent(id)}/read`, personId, {}, false, options),
+        markAllRead: (personId, input = {}, options) => call('POST', '/inbox/read-all', personId, input.upTo ? { upTo: input.upTo } : {}, false, options),
+        getPreference: (personId, options) => call('GET', '/inbox/preference', personId, undefined, true, options),
+        setPreference: (personId, state, options) => call('PUT', '/inbox/preference', personId, { state }, false, options),
+    };
+}

package/dist/cjs/inbox/errors.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOST_ERRORS = void 0;
+exports.hostCodeOf = hostCodeOf;
+exports.hostError = hostError;
+exports.hostData = hostData;
+const errors_1 = require("../errors");
+/** The six answers a browser can get from the host's inbox routes. The messages are fixed: nothing from upstream is repeated. */
+exports.HOST_ERRORS = {
+    not_signed_in: { status: 401, message: 'Sign in to see your notifications.' },
+    not_permitted: { status: 403, message: 'This request is not allowed.' },
+    not_found: { status: 404, message: 'This notification is not available.' },
+    invalid_input: { status: 422, message: 'The request is not valid.' },
+    rate_limited: { status: 429, message: 'Too many requests. Try again in a moment.' },
+    unavailable: { status: 503, message: 'Notifications are not available right now.' },
+};
+/**
+ * Total: every failure is one of the six codes. A revoked or misconfigured key, a timeout and anything unknown are
+ * `unavailable`, because the person in the browser cannot fix them and must not be told about them.
+ */
+function hostCodeOf(error) {
+    if (!(error instanceof errors_1.CommunicationError))
+        return 'unavailable';
+    switch (error.code) {
+        case 'forbidden':
+            return 'not_permitted';
+        case 'not_found':
+            return 'not_found';
+        case 'validation_failed':
+            return 'invalid_input';
+        case 'rate_limited':
+            return 'rate_limited';
+        default:
+            return 'unavailable';
+    }
+}
+const HEADERS = { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' };
+function hostError(code, field) {
+    const body = { error: { code, message: exports.HOST_ERRORS[code].message, ...(field ? { field } : {}) } };
+    return new Response(JSON.stringify(body), { status: exports.HOST_ERRORS[code].status, headers: HEADERS });
+}
+function hostData(data) {
+    return new Response(JSON.stringify({ data }), { status: 200, headers: HEADERS });
+}

package/dist/cjs/inbox/handler.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInboxHandler = createInboxHandler;
+const client_1 = require("./client");
+const errors_1 = require("./errors");
+const origin_1 = require("./origin");
+const project_1 = require("./project");
+const validate_1 = require("./validate");
+/** The six operations of IB-8, and nothing else. */
+function match(method, pathname, base) {
+    if (pathname !== base && !pathname.startsWith(`${base}/`))
+        return null;
+    const rest = pathname.slice(base.length).replace(/\/+$/, '');
+    if (method === 'GET' && rest === '/summary')
+        return { name: 'summary', write: false };
+    if (method === 'GET' && rest === '/notifications')
+        return { name: 'list', write: false };
+    if (method === 'GET' && rest === '/preference')
+        return { name: 'getPreference', write: false };
+    if (method === 'PUT' && rest === '/preference')
+        return { name: 'setPreference', write: true };
+    if (method === 'POST' && rest === '/read-all')
+        return { name: 'readAll', write: true };
+    const read = method === 'POST' ? /^\/notifications\/([^/]+)\/read$/.exec(rest) : null;
+    if (read)
+        return { name: 'markRead', write: true, id: read[1] };
+    return null;
+}
+/**
+ * The host xApp's browser-facing inbox routes, in one tested function. Mount it on a catch-all route:
+ *
+ *   const handler = createInboxHandler({ resolvePerson });
+ *   export { handler as GET, handler as POST, handler as PUT };
+ *
+ * The person comes only from `resolvePerson`. The host stores nothing. Without `client`, the key and the address are
+ * read on the first request, so a missing one answers `unavailable` and never stops the host's build.
+ */
+function createInboxHandler(options) {
+    const base = (options.basePath ?? '/api/communication/inbox').replace(/\/+$/, '');
+    const call = { retry: false, timeoutMs: options.timeoutMs ?? 8000 };
+    let made;
+    const clientOf = () => options.client ?? (made ??= (0, client_1.createInboxClient)());
+    return async function inboxHandler(request) {
+        try {
+            const url = new URL(request.url);
+            const op = match(request.method.toUpperCase(), url.pathname, base);
+            if (!op)
+                return (0, errors_1.hostError)('not_found');
+            if (op.write && !(0, origin_1.originAllowed)(request, options.allowedOrigins))
+                return (0, errors_1.hostError)('not_permitted');
+            const person = await options.resolvePerson(request);
+            if (typeof person !== 'string' || person.length === 0 || person.length > validate_1.INBOX_LIMITS.personMax)
+                return (0, errors_1.hostError)('not_signed_in');
+            const client = clientOf();
+            switch (op.name) {
+                case 'summary':
+                    return answer((0, project_1.projectSummary)(await client.summary(person, call)));
+                case 'list': {
+                    const limit = (0, validate_1.parseLimit)(url.searchParams.get('limit'));
+                    if (!limit.ok)
+                        return (0, errors_1.hostError)('invalid_input', limit.field);
+                    const cursor = (0, validate_1.parseCursor)(url.searchParams.get('cursor'));
+                    if (!cursor.ok)
+                        return (0, errors_1.hostError)('invalid_input', cursor.field);
+                    const unread = (0, validate_1.parseUnread)(url.searchParams.get('unread'));
+                    if (!unread.ok)
+                        return (0, errors_1.hostError)('invalid_input', unread.field);
+                    return answer((0, project_1.projectPage)(await client.list(person, { limit: limit.value, cursor: cursor.value, unreadOnly: unread.value }, call)));
+                }
+                case 'markRead': {
+                    let raw;
+                    try {
+                        raw = decodeURIComponent(op.id);
+                    }
+                    catch {
+                        return (0, errors_1.hostError)('invalid_input', 'id');
+                    }
+                    const id = (0, validate_1.parseId)(raw);
+                    if (!id.ok)
+                        return (0, errors_1.hostError)('invalid_input', id.field);
+                    return answer((0, project_1.projectMarkRead)(await client.markRead(person, id.value, call)));
+                }
+                case 'readAll': {
+                    const body = (0, validate_1.parseBody)(await request.text());
+                    if (!body.ok)
+                        return (0, errors_1.hostError)('invalid_input', body.field);
+                    const upTo = (0, validate_1.parseUpTo)(body.value.upTo);
+                    if (!upTo.ok)
+                        return (0, errors_1.hostError)('invalid_input', upTo.field);
+                    return answer((0, project_1.projectReadAll)(await client.markAllRead(person, { upTo: upTo.value }, call)));
+                }
+                case 'getPreference':
+                    return answer((0, project_1.projectPreference)(await client.getPreference(person, call)));
+                case 'setPreference': {
+                    const body = (0, validate_1.parseBody)(await request.text());
+                    if (!body.ok)
+                        return (0, errors_1.hostError)('invalid_input', body.field);
+                    const state = (0, validate_1.parseState)(body.value.state);
+                    if (!state.ok)
+                        return (0, errors_1.hostError)('invalid_input', state.field);
+                    return answer((0, project_1.projectPreference)(await client.setPreference(person, state.value, call)));
+                }
+            }
+        }
+        catch (error) {
+            const code = (0, errors_1.hostCodeOf)(error);
+            if (code === 'unavailable')
+                report(error);
+            return (0, errors_1.hostError)(code);
+        }
+    };
+    function answer(data) {
+        if (data === null) {
+            report(new Error('The inbox answer did not have the documented shape'));
+            return (0, errors_1.hostError)('unavailable');
+        }
+        return (0, errors_1.hostData)(data);
+    }
+    function report(error) {
+        try {
+            options.onError?.(error);
+        }
+        catch {
+            // A failing logger must not change the answer.
+        }
+    }
+}

package/dist/cjs/inbox/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INBOX_LIMITS = exports.originAllowed = exports.hostCodeOf = exports.HOST_ERRORS = exports.createInboxHandler = exports.personHeader = exports.createInboxClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "createInboxClient", { enumerable: true, get: function () { return client_1.createInboxClient; } });
+Object.defineProperty(exports, "personHeader", { enumerable: true, get: function () { return client_1.personHeader; } });
+var handler_1 = require("./handler");
+Object.defineProperty(exports, "createInboxHandler", { enumerable: true, get: function () { return handler_1.createInboxHandler; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "HOST_ERRORS", { enumerable: true, get: function () { return errors_1.HOST_ERRORS; } });
+Object.defineProperty(exports, "hostCodeOf", { enumerable: true, get: function () { return errors_1.hostCodeOf; } });
+var origin_1 = require("./origin");
+Object.defineProperty(exports, "originAllowed", { enumerable: true, get: function () { return origin_1.originAllowed; } });
+var validate_1 = require("./validate");
+Object.defineProperty(exports, "INBOX_LIMITS", { enumerable: true, get: function () { return validate_1.INBOX_LIMITS; } });

package/dist/cjs/inbox/origin.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.originAllowed = originAllowed;
+/**
+ * A request that changes something must come from the host's own pages (14.5): the browser says `Sec-Fetch-Site: same-origin`,
+ * or the `Origin` header equals an allowed origin. Without `allowedOrigins`, the only allowed origin is the request's own.
+ */
+function originAllowed(request, allowedOrigins) {
+    if (request.headers.get('sec-fetch-site') === 'same-origin')
+        return true;
+    const origin = request.headers.get('origin');
+    if (!origin)
+        return false;
+    let allowed;
+    try {
+        allowed = allowedOrigins && allowedOrigins.length > 0 ? allowedOrigins : [new URL(request.url).origin];
+    }
+    catch {
+        return false;
+    }
+    return allowed.includes(origin);
+}