@xtremax/pigeon 0.0.0-stage → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.3.1
+- The package carries its agent skill, `skills/add-pigeon-notifications/`: the steps a coding agent follows to add the bell and the sending code to an app.
+- New command `npx @xtremax/pigeon add-skill`: copies the skill into the project's `.claude/skills/`, and into `.kiro/skills/` when the project has a `.kiro` folder. Run it again after an upgrade to get the new version's skill. `--check` says what would change.
+- No change to the library.
+
+## 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,69 @@
-# 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`.
+
+## For AI coding agents
+
+The package carries a skill that tells a coding agent (Claude Code, Kiro and others that read `SKILL.md`) how to add the bell and the sending code to an app, step by step, with tests and a troubleshooting table.
+
+```bash
+npx @xtremax/pigeon add-skill
+```
+
+It copies `add-pigeon-notifications` into the project's `.claude/skills/`, and into `.kiro/skills/` when the project has a `.kiro` folder (`--kiro` forces it, `--dir` names another project folder, `--check` changes nothing and says what would change). Then ask the agent to "add a notification bell", or run `/add-pigeon-notifications`. Run the command again after upgrading the package: the skill's files are replaced with the new version's.
+
+An agent that has not been given the skill can read it in place: `node_modules/@xtremax/pigeon/skills/add-pigeon-notifications/SKILL.md`.
+
+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/bin/pigeon.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// The package's command line. One job: put the agent skills that ship with the package where a coding agent finds them.
+//
+//   npx @xtremax/pigeon add-skill            copy the skills into this project
+//   npx @xtremax/pigeon add-skill --check    say what would change, and change nothing
+//   npx @xtremax/pigeon add-skill --dir app  another project folder
+//
+// The skills go to .claude/skills/ always, and to .kiro/skills/ when the project has a .kiro folder (or with --kiro).
+// Run it again after upgrading the package: it replaces the skill's files with the new version's.
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const skillsRoot = join(packageRoot, 'skills');
+const { name, version } = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+
+const USAGE = `${name} ${version}
+
+Usage:
+  npx ${name} add-skill [--dir <project folder>] [--kiro] [--check]
+
+  add-skill   Copy the agent skills of this package into the project:
+              .claude/skills/<skill>/, and .kiro/skills/<skill>/ when the project has a .kiro folder.
+  --dir       The project folder. Default: the current folder.
+  --kiro      Also write .kiro/skills/ when the project has no .kiro folder yet.
+  --check     Say what would change and change nothing. Exits 1 when something would.
+`;
+
+function fail(message) {
+  process.stderr.write(`${message}\n\n${USAGE}`);
+  process.exit(2);
+}
+
+/** Every file under a folder, as paths relative to it. */
+function filesOf(dir, base = dir) {
+  return readdirSync(dir).flatMap((entry) => {
+    const path = join(dir, entry);
+    return statSync(path).isDirectory() ? filesOf(path, base) : [relative(base, path)];
+  });
+}
+
+function addSkill(args) {
+  let dir = process.cwd();
+  let kiro = false;
+  let check = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--dir') {
+      const value = args[(i += 1)];
+      if (!value) fail('--dir needs a folder.');
+      dir = resolve(value);
+    } else if (arg === '--kiro') kiro = true;
+    else if (arg === '--check') check = true;
+    else fail(`Unknown option: ${arg}`);
+  }
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) fail(`Not a folder: ${dir}`);
+  // A project, not any folder: writing skills into the wrong place helps nobody.
+  if (!existsSync(join(dir, 'package.json'))) fail(`No package.json in ${dir}. Run this in the project's folder, or pass --dir.`);
+
+  const skills = readdirSync(skillsRoot).filter((entry) => existsSync(join(skillsRoot, entry, 'SKILL.md')));
+  const homes = ['.claude/skills', ...(kiro || existsSync(join(dir, '.kiro')) ? ['.kiro/skills'] : [])];
+  const counts = { added: 0, updated: 0, same: 0 };
+
+  for (const home of homes) {
+    for (const skill of skills) {
+      for (const file of filesOf(join(skillsRoot, skill))) {
+        const content = readFileSync(join(skillsRoot, skill, file));
+        const target = join(dir, home, skill, file);
+        const state = !existsSync(target) ? 'added' : readFileSync(target).equals(content) ? 'same' : 'updated';
+        counts[state] += 1;
+        if (state === 'same') continue;
+        process.stdout.write(`${check ? `would be ${state}` : state}: ${join(home, skill, file)}\n`);
+        if (check) continue;
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, content);
+      }
+    }
+  }
+
+  const changed = counts.added + counts.updated;
+  if (changed === 0) process.stdout.write(`Up to date: ${skills.join(', ')} (${name} ${version}) in ${homes.join(' and ')}.\n`);
+  else if (check) process.stdout.write(`${changed} file(s) would change. Run without --check to write them.\n`);
+  else process.stdout.write(`\nDone: ${skills.join(', ')} (${name} ${version}) in ${homes.join(' and ')}.\nAsk your coding agent to "add a notification bell", or run /${skills[0]}.\n`);
+  process.exit(check && changed > 0 ? 1 : 0);
+}
+
+const [command, ...rest] = process.argv.slice(2);
+if (command === 'add-skill') addSkill(rest);
+else if (command === undefined || command === 'help' || command === '--help' || command === '-h') process.stdout.write(USAGE);
+else if (command === '--version' || command === '-v') process.stdout.write(`${version}\n`);
+else fail(`Unknown command: ${command}`);

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