@xtremax/pigeon 0.0.0-stage → 0.3.1

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;

package/dist/esm/inbox/client.js

@@ -0,0 +1,35 @@
+import { TRANSPORT, createCommunicationClient } from '../client.js';
+/** `X-Communication-Person` is base64url of the UTF-8 person id, so any identifier travels safely in a header. */
+export 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) => 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`.
+ */
+export function createInboxClient(client = {}) {
+    const request = (isClient(client) ? client : createCommunicationClient(client))[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/esm/inbox/errors.js

@@ -0,0 +1,38 @@
+import { CommunicationError } from '../errors.js';
+/** The six answers a browser can get from the host's inbox routes. The messages are fixed: nothing from upstream is repeated. */
+export const 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.
+ */
+export function hostCodeOf(error) {
+    if (!(error instanceof 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' };
+export function hostError(code, field) {
+    const body = { error: { code, message: HOST_ERRORS[code].message, ...(field ? { field } : {}) } };
+    return new Response(JSON.stringify(body), { status: HOST_ERRORS[code].status, headers: HEADERS });
+}
+export function hostData(data) {
+    return new Response(JSON.stringify({ data }), { status: 200, headers: HEADERS });
+}

package/dist/esm/inbox/handler.js

@@ -0,0 +1,124 @@
+import { createInboxClient } from './client.js';
+import { hostCodeOf, hostData, hostError } from './errors.js';
+import { originAllowed } from './origin.js';
+import { projectMarkRead, projectPage, projectPreference, projectReadAll, projectSummary } from './project.js';
+import { INBOX_LIMITS, parseBody, parseCursor, parseId, parseLimit, parseState, parseUnread, parseUpTo } from './validate.js';
+/** 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.
+ */
+export 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 ??= 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 hostError('not_found');
+            if (op.write && !originAllowed(request, options.allowedOrigins))
+                return hostError('not_permitted');
+            const person = await options.resolvePerson(request);
+            if (typeof person !== 'string' || person.length === 0 || person.length > INBOX_LIMITS.personMax)
+                return hostError('not_signed_in');
+            const client = clientOf();
+            switch (op.name) {
+                case 'summary':
+                    return answer(projectSummary(await client.summary(person, call)));
+                case 'list': {
+                    const limit = parseLimit(url.searchParams.get('limit'));
+                    if (!limit.ok)
+                        return hostError('invalid_input', limit.field);
+                    const cursor = parseCursor(url.searchParams.get('cursor'));
+                    if (!cursor.ok)
+                        return hostError('invalid_input', cursor.field);
+                    const unread = parseUnread(url.searchParams.get('unread'));
+                    if (!unread.ok)
+                        return hostError('invalid_input', unread.field);
+                    return answer(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 hostError('invalid_input', 'id');
+                    }
+                    const id = parseId(raw);
+                    if (!id.ok)
+                        return hostError('invalid_input', id.field);
+                    return answer(projectMarkRead(await client.markRead(person, id.value, call)));
+                }
+                case 'readAll': {
+                    const body = parseBody(await request.text());
+                    if (!body.ok)
+                        return hostError('invalid_input', body.field);
+                    const upTo = parseUpTo(body.value.upTo);
+                    if (!upTo.ok)
+                        return hostError('invalid_input', upTo.field);
+                    return answer(projectReadAll(await client.markAllRead(person, { upTo: upTo.value }, call)));
+                }
+                case 'getPreference':
+                    return answer(projectPreference(await client.getPreference(person, call)));
+                case 'setPreference': {
+                    const body = parseBody(await request.text());
+                    if (!body.ok)
+                        return hostError('invalid_input', body.field);
+                    const state = parseState(body.value.state);
+                    if (!state.ok)
+                        return hostError('invalid_input', state.field);
+                    return answer(projectPreference(await client.setPreference(person, state.value, call)));
+                }
+            }
+        }
+        catch (error) {
+            const code = hostCodeOf(error);
+            if (code === 'unavailable')
+                report(error);
+            return hostError(code);
+        }
+    };
+    function answer(data) {
+        if (data === null) {
+            report(new Error('The inbox answer did not have the documented shape'));
+            return hostError('unavailable');
+        }
+        return hostData(data);
+    }
+    function report(error) {
+        try {
+            options.onError?.(error);
+        }
+        catch {
+            // A failing logger must not change the answer.
+        }
+    }
+}

package/dist/esm/inbox/index.js

@@ -0,0 +1,5 @@
+export { createInboxClient, personHeader } from './client.js';
+export { createInboxHandler } from './handler.js';
+export { HOST_ERRORS, hostCodeOf } from './errors.js';
+export { originAllowed } from './origin.js';
+export { INBOX_LIMITS } from './validate.js';

package/dist/esm/inbox/origin.js

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+export 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);
+}

package/dist/esm/inbox/project.js

@@ -0,0 +1,76 @@
+/**
+ * Allowlist projection: only the documented fields of IB-2 leave the host, so nothing the Gateway adds later reaches a
+ * browser by accident. A value of the wrong shape gives `null`, which the handler answers as `unavailable`.
+ */
+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);
+export function projectNotification(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 };
+}
+export function projectSummary(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 };
+}
+export function projectPage(v) {
+    const o = obj(v);
+    if (!o || !Array.isArray(o.notifications))
+        return null;
+    const notifications = [];
+    for (const raw of o.notifications) {
+        const n = projectNotification(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 };
+}
+export function projectMarkRead(v) {
+    const o = obj(v);
+    const notification = projectNotification(o?.notification);
+    const unreadCount = count(o?.unreadCount);
+    return notification && unreadCount !== null ? { notification, unreadCount } : null;
+}
+export function projectReadAll(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 };
+}
+export function projectPreference(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 };
+}

package/dist/esm/inbox/validate.js

@@ -0,0 +1,49 @@
+export const INBOX_LIMITS = { pageMin: 1, pageMax: 100, cursorMax: 128, idMax: 64, upToMax: 40, bodyBytes: 1024, personMax: 128 };
+const ok = (value) => ({ ok: true, value });
+const bad = (field) => ({ ok: false, field });
+export function parseLimit(raw) {
+    if (raw === null)
+        return ok(undefined);
+    if (!/^\d{1,3}$/.test(raw))
+        return bad('limit');
+    const n = Number(raw);
+    return n >= INBOX_LIMITS.pageMin && n <= INBOX_LIMITS.pageMax ? ok(n) : bad('limit');
+}
+export function parseCursor(raw) {
+    if (raw === null)
+        return ok(undefined);
+    return raw.length > 0 && raw.length <= INBOX_LIMITS.cursorMax && /^[A-Za-z0-9_-]+$/.test(raw) ? ok(raw) : bad('cursor');
+}
+export function parseUnread(raw) {
+    if (raw === null || raw === 'false')
+        return ok(false);
+    return raw === 'true' ? ok(true) : bad('unread');
+}
+export function parseId(raw) {
+    return raw.length > 0 && raw.length <= INBOX_LIMITS.idMax && /^[A-Za-z0-9_-]+$/.test(raw) ? ok(raw) : bad('id');
+}
+export function parseUpTo(raw) {
+    if (raw === undefined || raw === null)
+        return ok(undefined);
+    if (typeof raw !== 'string' || raw.length > INBOX_LIMITS.upToMax || !/^\d{4}-\d{2}-\d{2}T[\d:.]+(Z|[+-]\d{2}:\d{2})$/.test(raw))
+        return bad('upTo');
+    const t = Date.parse(raw);
+    return Number.isFinite(t) ? ok(new Date(t).toISOString()) : bad('upTo');
+}
+export function parseState(raw) {
+    return raw === 'opted_in' || raw === 'opted_out' ? ok(raw) : bad('state');
+}
+/** A JSON object of at most 1024 bytes. An empty body is an empty object. */
+export function parseBody(text) {
+    if (new TextEncoder().encode(text).length > INBOX_LIMITS.bodyBytes)
+        return bad('body');
+    if (text.trim() === '')
+        return ok({});
+    try {
+        const v = JSON.parse(text);
+        return typeof v === 'object' && v !== null && !Array.isArray(v) ? ok(v) : bad('body');
+    }
+    catch {
+        return bad('body');
+    }
+}

package/dist/esm/inbox-react/format.js

@@ -0,0 +1,64 @@
+/** Fills `{name}` placeholders. Values are text, never markup. */
+export function fill(template, values) {
+    return template.replace(/\{(\w+)\}/g, (whole, key) => (key in values ? String(values[key]) : whole));
+}
+/** Nothing for 0, the number for 1 to 99, "99+" above (12.1). */
+export function badgeText(count) {
+    if (!Number.isFinite(count) || count < 1)
+        return '';
+    return count > 99 ? '99+' : String(Math.floor(count));
+}
+/** The bell's accessible name: "{label}, {n} unread", or the label alone when nothing is unread (15.3). */
+export function bellName(labels, count) {
+    return count > 0 ? fill(labels.bellWithCount, { label: labels.bell, n: count }) : labels.bell;
+}
+const LINK_MAX = 2048;
+/** Accepts exactly what the inbox stores: an absolute https URL without credentials, at most 2048 characters (12.15). */
+export function safeLink(link) {
+    if (!link || link.length > LINK_MAX)
+        return null;
+    try {
+        const u = new URL(link);
+        return u.protocol === 'https:' && !u.username && !u.password ? u.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+const MINUTE = 60;
+const HOUR = 3600;
+const DAY = 86400;
+/** "now", "5 minutes ago", "yesterday", then a short date after a week. A time in the future (clock skew) reads as now. */
+export function relativeTime(iso, now, locale) {
+    const then = Date.parse(iso);
+    if (!Number.isFinite(then))
+        return '';
+    const seconds = Math.max(0, Math.floor((now.getTime() - then) / 1000));
+    try {
+        const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+        if (seconds < MINUTE)
+            return rtf.format(0, 'second');
+        if (seconds < HOUR)
+            return rtf.format(-Math.floor(seconds / MINUTE), 'minute');
+        if (seconds < DAY)
+            return rtf.format(-Math.floor(seconds / HOUR), 'hour');
+        if (seconds < 7 * DAY)
+            return rtf.format(-Math.floor(seconds / DAY), 'day');
+        return new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }).format(new Date(then));
+    }
+    catch {
+        return new Date(then).toISOString().slice(0, 10);
+    }
+}
+/** The full date and time, for the `title` of a relative time. */
+export function exactTime(iso, locale) {
+    const then = Date.parse(iso);
+    if (!Number.isFinite(then))
+        return '';
+    try {
+        return new Intl.DateTimeFormat(locale, { dateStyle: 'full', timeStyle: 'short' }).format(new Date(then));
+    }
+    catch {
+        return new Date(then).toISOString();
+    }
+}