@xtremax/pigeon 0.0.0-stage → 0.3.1

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

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

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+export { createCommunicationClient, CommunicationError } from './client.js';
+export { createEventHandler, verifyEventSignature } from './events.js';
+export { deriveIdempotencyKey, newIdempotencyKey } from './idempotency.js';
+export { DEFAULT_RETRY } from './retry.js';

package/dist/esm/retry.js

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

package/dist/inbox-react/styles.css

@@ -0,0 +1,65 @@
+/*
+ * The inbox's own styles. Import once in the host app, after Mantine's styles:
+ *   import '@xtremax/communication/inbox-react/styles.css';
+ * Colours come from Mantine theme variables only, so the inbox follows the host app's theme and colour scheme (12.16).
+ */
+.xci-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.xci-entry + .xci-entry {
+  border-top: 1px solid var(--mantine-color-default-border);
+}
+
+/* Two classes, so these win over Mantine's own button styles whichever stylesheet loads first. */
+.xci-list .xci-row {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--mantine-spacing-sm);
+  width: 100%;
+  min-height: 44px;
+  padding: var(--mantine-spacing-sm) var(--mantine-spacing-md);
+  text-align: start;
+  color: var(--mantine-color-text);
+}
+
+@media (hover: hover) {
+  .xci-list .xci-row:hover {
+    background-color: var(--mantine-color-default-hover);
+  }
+}
+
+.xci-dot {
+  flex: none;
+  width: 8px;
+  height: 8px;
+  margin-top: 6px;
+  border-radius: 50%;
+  background-color: transparent;
+}
+
+.xci-dot[data-unread] {
+  background-color: var(--mantine-primary-color-filled);
+}
+
+.xci-content {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+}
+
+.xci-meta {
+  display: flex;
+  align-items: center;
+  gap: var(--mantine-spacing-xs);
+  min-width: 0;
+}
+
+.xci-line {
+  display: block;
+  overflow-wrap: anywhere;
+}

package/dist/types/browser-stub.d.ts

@@ -0,0 +1,4 @@
+import { CommunicationError } from './errors.js';
+/** Selected by the `browser` export condition so a secret key can never be bundled into client code. */
+export declare function createCommunicationClient(): never;
+export { CommunicationError };

package/dist/types/client.d.ts

@@ -0,0 +1,94 @@
+import type { AcceptedMessage, ChannelInfo, MessageView, PingInfo, RecipientView, SendMessageRequest } from './contract.js';
+import { type RetryPolicy } from './retry.js';
+export interface ClientOptions {
+    /** Defaults to `process.env.COMMUNICATION_API_KEY`. */
+    apiKey?: string;
+    /** Defaults to `process.env.COMMUNICATION_URL`. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    retry?: Partial<RetryPolicy>;
+    /** Injectable for tests. */
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+}
+/** Per-call choices. `retry: false` makes one attempt; `timeoutMs` bounds the whole call; `headers` never replace the key. */
+export interface RequestOptions {
+    retry?: boolean;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
+export type Transport = <T>(method: string, path: string, body?: unknown, opts?: RequestOptions) => Promise<{
+    data: T;
+    headers: Headers;
+}>;
+/** Where a client keeps its transport, so `@xtremax/pigeon/inbox` can reuse the key handling, retries and errors. */
+export declare const TRANSPORT: unique symbol;
+export declare function createCommunicationClient(options?: ClientOptions): {
+    messages: {
+        /** Sends are retried safely because every request carries an idempotency key (yours, or a random one). */
+        send(req: SendMessageRequest): Promise<AcceptedMessage>;
+        get: (id: string) => Promise<MessageView>;
+    };
+    channels: {
+        list: () => Promise<ChannelInfo[]>;
+    };
+    ping: () => Promise<PingInfo>;
+    recipients: {
+        put: (personId: string, body: {
+            timezone?: string | null;
+            locale?: string | null;
+            quietHours?: {
+                start: string;
+                end: string;
+            } | null;
+        }) => Promise<RecipientView>;
+        get: (personId: string) => Promise<RecipientView>;
+        delete(personId: string): Promise<void>;
+        putAddress: (personId: string, body: {
+            medium: "email" | "whatsapp";
+            address: string;
+            primary?: boolean;
+            verified?: boolean;
+        }) => Promise<{
+            id: string;
+            masked: string;
+        }>;
+        deleteAddress(personId: string, addressId: string): Promise<void>;
+    };
+    preferences: {
+        record: (body: {
+            recipient: {
+                personId?: string;
+                address?: string;
+                medium?: "email" | "whatsapp";
+            };
+            medium: "email" | "whatsapp" | "in_app";
+            state: "opted_in" | "opted_out";
+            expressedAt?: string;
+            evidence?: {
+                method?: string;
+                wordingVersion?: string;
+                proofRef?: string;
+            };
+        }) => Promise<{
+            changed: boolean;
+            current: unknown;
+        }>;
+    };
+    messageClasses: {
+        put: (templateKey: string, body: {
+            class: "transactional" | "non_transactional";
+            note?: string;
+        }) => Promise<unknown>;
+        list: () => Promise<{
+            templateKey: string;
+            class: string;
+            note: string | null;
+        }[]>;
+    };
+    /** For logs: never prints the key. */
+    describe: () => string;
+    [TRANSPORT]: Transport;
+};
+export type CommunicationClient = ReturnType<typeof createCommunicationClient>;
+export { CommunicationError } from './errors.js';

package/dist/types/contract.d.ts

@@ -0,0 +1,182 @@
+/** Types mirrored from the Gateway's external API (types only; safe in any bundle). */
+export declare const SUPPORTED_API_VERSION = "v1";
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type MessageState = 'queued' | 'sent' | 'delivered' | 'read' | 'failed';
+export type FailureCategory = 'invalid_recipient' | 'recipient_unreachable' | 'recipient_blocked' | 'content_rejected' | 'provider_rejected' | 'provider_unavailable' | 'rate_limited' | 'configuration_error' | 'policy_refused' | 'retries_exhausted' | 'unknown';
+export interface NeutralReason {
+    category: FailureCategory;
+    code: string;
+    message: string;
+}
+export type ApiErrorCode = '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 interface ApiErrorDetail {
+    field?: string;
+    code?: string;
+    message?: string;
+    reason?: string;
+}
+export interface ApiErrorBody {
+    error: {
+        code: string;
+        message: string;
+        requestId?: string;
+        details?: ApiErrorDetail[];
+    };
+}
+export interface SendMessageRequest {
+    templateKey: string;
+    channel: string;
+    recipient: {
+        personId?: string;
+        address?: string;
+    };
+    variables?: Record<string, JsonValue>;
+    /** Optional: the SDK derives a stable key from the request when you leave it out. */
+    idempotencyKey?: string;
+    reference?: JsonValue;
+    locale?: string;
+    options?: {
+        testOutcome?: 'accepted' | 'delivered' | 'read' | 'transient_failure' | 'permanent_failure';
+        succeedOnAttempt?: number;
+    };
+}
+export interface AcceptedMessage {
+    id: string;
+    state: MessageState;
+    channel: string;
+    reference: JsonValue | null;
+    acceptedAt: string;
+    idempotentReplay: boolean;
+}
+export interface MessageView {
+    id: string;
+    state: MessageState;
+    channel: string;
+    templateKey: string;
+    reference: JsonValue | null;
+    acceptedAt: string;
+    test: boolean;
+    failure: NeutralReason | null;
+    history: Array<{
+        sequence: number;
+        previousState: MessageState | null;
+        state: MessageState;
+        occurredAt: string;
+        cause: string;
+        reason: NeutralReason | null;
+    }>;
+    attempts: Array<{
+        attempt: number;
+        startedAt: string;
+        finishedAt: string | null;
+        outcome: 'in_progress' | 'accepted' | 'transient_failure' | 'permanent_failure' | 'interrupted';
+        reasonCode: string | null;
+    }>;
+}
+export interface ChannelInfo {
+    key: string;
+    name: string;
+    medium: 'email' | 'whatsapp' | 'in_app';
+    owner: 'shared' | 'tenant';
+    ready: boolean;
+    reason: string | null;
+}
+export interface PingInfo {
+    clientId: string;
+    tenantKey: string; /** The sub-tenant this key belongs to, or null at tenant level. The in-app inbox shows a person what this sub-tenant sent them. */
+    subKey?: string | null;
+    scopes: string[];
+}
+export interface MessageStateChangedEvent {
+    eventId: string;
+    type: 'message.state_changed';
+    version: 1;
+    sequence: number;
+    messageId: string;
+    reference: JsonValue | null;
+    channel: string;
+    previousState: MessageState;
+    state: MessageState;
+    occurredAt: string;
+    reason: {
+        category: FailureCategory;
+        code: string;
+        message: string;
+    } | null;
+    test: boolean;
+}
+export interface RecipientView {
+    personId: string;
+    status: 'active' | 'erased';
+    timezone: string | null;
+    locale: string | null;
+    quietHours: {
+        start: string;
+        end: string;
+    } | null;
+    addresses: Array<{
+        id: string;
+        medium: string;
+        masked: string;
+        primary: boolean;
+        verifiedAt: string | null;
+    }>;
+    preferences: Array<{
+        medium: string;
+        state: 'opted_in' | 'opted_out' | 'not_set';
+        changedAt: string | null;
+        source: string | null;
+    }>;
+}
+export interface InboxNotification {
+    /** The inbox item, not the message. */
+    id: string;
+    kind: 'notification' | 'announcement';
+    /** Plain text. */
+    title: string;
+    body: string;
+    /** Absolute https, or null. */
+    link: string | null;
+    source: {
+        type: 'xapp' | 'tenant';
+        name: string;
+    };
+    createdAt: string;
+    read: boolean;
+    readAt: string | null;
+}
+export interface InboxSummary {
+    unreadCount: number;
+    newestUnreadAt: string | null;
+    pollSeconds: number;
+}
+export interface InboxNotificationPage {
+    notifications: InboxNotification[];
+    nextCursor: string | null;
+    unreadCount: number;
+}
+export interface InboxPreference {
+    state: 'opted_in' | 'opted_out' | 'not_set';
+    changedAt: string | null;
+    delivers: boolean;
+}
+export interface InboxMarkReadResult {
+    notification: InboxNotification;
+    unreadCount: number;
+}
+export interface InboxReadAllResult {
+    marked: number;
+    remaining: number;
+    unreadCount: number;
+}
+/** What the host's browser-facing inbox routes answer when a call fails (IB-8). */
+export type InboxHostErrorCode = 'not_signed_in' | 'not_permitted' | 'not_found' | 'invalid_input' | 'rate_limited' | 'unavailable';
+export interface InboxHostErrorBody {
+    error: {
+        code: InboxHostErrorCode;
+        message: string;
+        field?: string;
+    };
+}

package/dist/types/errors.d.ts

@@ -0,0 +1,29 @@
+import type { ApiErrorCode, ApiErrorDetail } from './contract.js';
+export type ErrorCode = ApiErrorCode | 'unknown_error' | 'network_error' | 'timeout' | 'aborted' | 'invalid_response' | 'not_configured' | 'server_only';
+/** Removes anything shaped like a key from text that may be logged. */
+export declare const redact: (text: string) => string;
+export declare class CommunicationError extends Error {
+    readonly code: ErrorCode;
+    readonly apiCode: string | null;
+    readonly status: number | null;
+    readonly requestId: string | null;
+    readonly details: readonly ApiErrorDetail[];
+    readonly retryable: boolean;
+    readonly retryAfterSeconds: number | null;
+    readonly attempts: number;
+    constructor(init: {
+        code: ErrorCode;
+        message: string;
+        apiCode?: string | null;
+        status?: number | null;
+        requestId?: string | null;
+        details?: readonly ApiErrorDetail[];
+        retryable?: boolean;
+        retryAfterSeconds?: number | null;
+        attempts?: number;
+    });
+    toJSON(): Record<string, unknown>;
+}
+export declare function fromResponse(status: number, body: unknown, headers: {
+    get(n: string): string | null;
+}, attempts: number): CommunicationError;

package/dist/types/events.d.ts

@@ -0,0 +1,26 @@
+import type { MessageStateChangedEvent } from './contract.js';
+export declare const DEFAULT_TOLERANCE_SECONDS = 300;
+export type VerifyResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: 'missing' | 'mismatch' | 'stale';
+};
+/** 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 declare function verifyEventSignature(input: {
+    secret: string | readonly string[];
+    timestamp: string | null | undefined;
+    signature: string | null | undefined;
+    rawBody: string;
+    nowSeconds?: number;
+    toleranceSeconds?: number;
+}): Promise<VerifyResult>;
+export interface EventHandlerOptions {
+    secret: string | readonly string[];
+    onEvent(event: MessageStateChangedEvent): void | Promise<void>;
+    /** Return true when this event, or a later one for the same message, was already processed. Keeps retries and reordering harmless. */
+    alreadyProcessed?(event: MessageStateChangedEvent): boolean | Promise<boolean>;
+    toleranceSeconds?: number;
+}
+/** A ready-made handler for a Next.js route or any Request/Response runtime. Answers 2xx only after `onEvent` succeeded. */
+export declare function createEventHandler(options: EventHandlerOptions): (req: Request) => Promise<Response>;

package/dist/types/idempotency.d.ts

@@ -0,0 +1,4 @@
+/** A random key for a send you will not retry yourself. Prefer `deriveIdempotencyKey` so your own retries are safe too. */
+export declare function newIdempotencyKey(): string;
+/** A stable key derived from parts you choose, for example an order id and an event name. Same input, same key. */
+export declare function deriveIdempotencyKey(...parts: Array<string | number>): Promise<string>;

package/dist/types/inbox/browser-stub.d.ts

@@ -0,0 +1,3 @@
+/** Selected by the `browser` export condition: the inbox entry never reaches client code. The component talks to the host's own routes instead. */
+export declare const createInboxClient: () => never;
+export declare const createInboxHandler: () => never;

package/dist/types/inbox/client.d.ts

@@ -0,0 +1,34 @@
+import { type ClientOptions, type CommunicationClient } from '../client.js';
+import type { InboxMarkReadResult, InboxNotificationPage, InboxPreference, InboxReadAllResult, InboxSummary } from '../contract.js';
+export interface CallOptions {
+    /** Reads are retried by the SDK's policy unless this is `false`. Writes make one attempt unless this is `true`. */
+    retry?: boolean;
+    /** Bounds the whole call, in milliseconds. */
+    timeoutMs?: number;
+}
+/**
+ * The in-app inbox as this key sees it: what its own sub-tenant (or the tenant level, for a key outside any) sent to
+ * the person, and the tenant's announcements. Another app's notifications are not part of it.
+ */
+export interface InboxClient {
+    summary(personId: string, options?: CallOptions): Promise<InboxSummary>;
+    list(personId: string, query?: {
+        limit?: number;
+        cursor?: string;
+        unreadOnly?: boolean;
+    }, options?: CallOptions): Promise<InboxNotificationPage>;
+    markRead(personId: string, id: string, options?: CallOptions): Promise<InboxMarkReadResult>;
+    markAllRead(personId: string, input?: {
+        upTo?: string;
+    }, options?: CallOptions): Promise<InboxReadAllResult>;
+    /** The person's choice for this app's notifications. Another app's choice is its own. */
+    getPreference(personId: string, options?: CallOptions): Promise<InboxPreference>;
+    setPreference(personId: string, state: 'opted_in' | 'opted_out', options?: CallOptions): Promise<InboxPreference>;
+}
+/** `X-Communication-Person` is base64url of the UTF-8 person id, so any identifier travels safely in a header. */
+export declare function personHeader(personId: string): string;
+/**
+ * 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 declare function createInboxClient(client?: ClientOptions | CommunicationClient): InboxClient;

package/dist/types/inbox/errors.d.ts

@@ -0,0 +1,13 @@
+import type { InboxHostErrorCode } from '../contract.js';
+/** The six answers a browser can get from the host's inbox routes. The messages are fixed: nothing from upstream is repeated. */
+export declare const HOST_ERRORS: Readonly<Record<InboxHostErrorCode, {
+    status: number;
+    message: string;
+}>>;
+/**
+ * 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 declare function hostCodeOf(error: unknown): InboxHostErrorCode;
+export declare function hostError(code: InboxHostErrorCode, field?: string): Response;
+export declare function hostData(data: unknown): Response;

package/dist/types/inbox/handler.d.ts

@@ -0,0 +1,25 @@
+import { type InboxClient } from './client.js';
+export interface InboxHandlerOptions {
+    /** Default: a client made on the first request from `COMMUNICATION_API_KEY` and `COMMUNICATION_URL`. */
+    client?: InboxClient;
+    /** The xApp's only job: who is signed in. `null` means nobody. Read it from your own session, never from the request's path, query or body. */
+    resolvePerson: (request: Request) => Promise<string | null> | string | null;
+    /** Where the routes are mounted. Default `/api/communication/inbox`. */
+    basePath?: string;
+    /** Origins that may send POST and PUT. Default: the request's own origin. */
+    allowedOrigins?: readonly string[];
+    /** Default 8000. */
+    timeoutMs?: number;
+    /** Told about every failure answered as `unavailable`, for the host's own log. The browser never sees it. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * 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 declare function createInboxHandler(options: InboxHandlerOptions): (request: Request) => Promise<Response>;

package/dist/types/inbox/index.d.ts

@@ -0,0 +1,6 @@
+export { createInboxClient, personHeader, type CallOptions, type InboxClient } from './client.js';
+export { createInboxHandler, type InboxHandlerOptions } from './handler.js';
+export { HOST_ERRORS, hostCodeOf } from './errors.js';
+export { originAllowed } from './origin.js';
+export { INBOX_LIMITS } from './validate.js';
+export type { InboxHostErrorBody, InboxHostErrorCode, InboxMarkReadResult, InboxNotification, InboxNotificationPage, InboxPreference, InboxReadAllResult, InboxSummary } from '../contract.js';

package/dist/types/inbox/origin.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 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 declare function originAllowed(request: Request, allowedOrigins?: readonly string[]): boolean;

package/dist/types/inbox/project.d.ts

@@ -0,0 +1,7 @@
+import type { InboxMarkReadResult, InboxNotification, InboxNotificationPage, InboxPreference, InboxReadAllResult, InboxSummary } from '../contract.js';
+export declare function projectNotification(v: unknown): InboxNotification | null;
+export declare function projectSummary(v: unknown): InboxSummary | null;
+export declare function projectPage(v: unknown): InboxNotificationPage | null;
+export declare function projectMarkRead(v: unknown): InboxMarkReadResult | null;
+export declare function projectReadAll(v: unknown): InboxReadAllResult | null;
+export declare function projectPreference(v: unknown): InboxPreference | null;

package/dist/types/inbox/validate.d.ts

@@ -0,0 +1,25 @@
+/** Bounded parsing of every value that comes from a browser. A value is either refused, naming its field, or inside the documented bounds. */
+export type Parsed<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    field: string;
+};
+export declare const INBOX_LIMITS: {
+    readonly pageMin: 1;
+    readonly pageMax: 100;
+    readonly cursorMax: 128;
+    readonly idMax: 64;
+    readonly upToMax: 40;
+    readonly bodyBytes: 1024;
+    readonly personMax: 128;
+};
+export declare function parseLimit(raw: string | null): Parsed<number | undefined>;
+export declare function parseCursor(raw: string | null): Parsed<string | undefined>;
+export declare function parseUnread(raw: string | null): Parsed<boolean>;
+export declare function parseId(raw: string): Parsed<string>;
+export declare function parseUpTo(raw: unknown): Parsed<string | undefined>;
+export declare function parseState(raw: unknown): Parsed<'opted_in' | 'opted_out'>;
+/** A JSON object of at most 1024 bytes. An empty body is an empty object. */
+export declare function parseBody(text: string): Parsed<Record<string, unknown>>;

package/dist/types/inbox-react/format.d.ts

@@ -0,0 +1,13 @@
+import type { InboxLabels } from './labels.js';
+/** Fills `{name}` placeholders. Values are text, never markup. */
+export declare function fill(template: string, values: Record<string, string | number>): string;
+/** Nothing for 0, the number for 1 to 99, "99+" above (12.1). */
+export declare function badgeText(count: number): string;
+/** The bell's accessible name: "{label}, {n} unread", or the label alone when nothing is unread (15.3). */
+export declare function bellName(labels: Pick<InboxLabels, 'bell' | 'bellWithCount'>, count: number): string;
+/** Accepts exactly what the inbox stores: an absolute https URL without credentials, at most 2048 characters (12.15). */
+export declare function safeLink(link: string | null | undefined): string | null;
+/** "now", "5 minutes ago", "yesterday", then a short date after a week. A time in the future (clock skew) reads as now. */
+export declare function relativeTime(iso: string, now: Date, locale?: string): string;
+/** The full date and time, for the `title` of a relative time. */
+export declare function exactTime(iso: string, locale?: string): string;