@xtremax/pigeon 0.0.0-stage → 0.3.0

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;

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

@@ -0,0 +1,24 @@
+import type { InboxMarkReadResult, InboxNotificationPage, InboxPreference, InboxReadAllResult, InboxResult, InboxSummary } from './types.js';
+export declare const DEFAULT_API_BASE = "/api/communication/inbox";
+/**
+ * The browser talks only to the host xApp's own origin (14.2). The base is a path on that origin: an absolute URL,
+ * a protocol-relative one or anything with a query is refused.
+ */
+export declare function normalizeApiBase(apiBase: string | undefined): string | null;
+export interface InboxBrowserClient {
+    summary(): Promise<InboxResult<InboxSummary>>;
+    list(query?: {
+        cursor?: string | null;
+        unreadOnly?: boolean;
+        limit?: number;
+    }): Promise<InboxResult<InboxNotificationPage>>;
+    markRead(id: string): Promise<InboxResult<InboxMarkReadResult>>;
+    markAllRead(upTo?: string | null): Promise<InboxResult<InboxReadAllResult>>;
+    getPreference(): Promise<InboxResult<InboxPreference>>;
+    setPreference(state: 'opted_in' | 'opted_out'): Promise<InboxResult<InboxPreference>>;
+}
+/**
+ * Every call answers a result and never throws, so an outage cannot break the host page (14.9).
+ * The bell shows what this xApp's own sub-tenant sent the person, and the tenant's announcements: there is nothing to choose.
+ */
+export declare function createInboxBrowserClient(apiBase?: string, fetchImpl?: typeof fetch): InboxBrowserClient;

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

@@ -0,0 +1,29 @@
+import { type RefObject } from 'react';
+import type { InboxBrowserClient } from './inbox-client.js';
+import type { InboxState } from './inbox-state.js';
+import type { InboxLabels } from './labels.js';
+import type { InboxNotification, InboxTab } from './types.js';
+export interface InboxContextValue {
+    state: InboxState;
+    labels: InboxLabels;
+    locale: string | undefined;
+    client: InboxBrowserClient;
+    panelOpened: boolean;
+    /** The bell, so focus returns to it when the panel or a dialog closes. */
+    bellRef: RefObject<HTMLButtonElement | null>;
+    openPanel: () => void;
+    closePanel: () => void;
+    setTab: (tab: InboxTab) => void;
+    /** Marks the notification read and opens its link when it has a safe one. */
+    select: (item: InboxNotification) => void;
+    markAllRead: () => void;
+    loadMore: () => void;
+    viewAll: () => void;
+    openPreferences: () => void;
+    retry: () => void;
+    clearMessage: () => void;
+    /** A visible list calls this on mount and the returned function on unmount; a shown list is kept fresh by the poll. */
+    attachList: () => () => void;
+}
+export declare const InboxContext: import("react").Context<InboxContextValue | null>;
+export declare function useInbox(): InboxContextValue;

package/dist/types/inbox-react/inbox-full-list.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Every notification, a page at a time. The provider shows it in a dialog for "View all"; a host that passes
+ * `onViewAll` can place it on a page of its own instead.
+ */
+export declare function InboxFullList({ maxHeight }: {
+    maxHeight?: number | string;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+import { type ReactNode } from 'react';
+interface InboxListViewProps {
+    /** Shown beside "Mark all as read". */
+    heading?: ReactNode;
+    /** The list scrolls inside this height. */
+    maxHeight?: number | string;
+    /** Offers older notifications below the list. */
+    paged?: boolean;
+}
+/** Tabs, "Mark all as read", the list and its loading, empty and error states. Shared by the panel and the full list. */
+export declare function InboxListView({ heading, maxHeight, paged }: InboxListViewProps): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,2 @@
+/** What the bell opens: the newest notifications, with the ways on to the full list and the preference. */
+export declare function InboxPanel(): import("react").JSX.Element;

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

@@ -0,0 +1,18 @@
+import { type ReactNode } from 'react';
+import { type InboxLabels } from './labels.js';
+export interface InboxProviderProps {
+    /** A path on the host's own origin. Default `/api/communication/inbox`. */
+    apiBase?: string;
+    /** Replaces any visible or accessible text. */
+    labels?: Partial<InboxLabels>;
+    /** Formats relative and exact times. Default: the browser's locale. */
+    locale?: string;
+    /** Default: opens the built-in full list in a dialog. */
+    onViewAll?: () => void;
+    /** Default: opens the built-in preference dialog. */
+    onOpenPreferences?: () => void;
+    /** Default: a new tab with `noopener,noreferrer`. */
+    openLink?: (url: string) => void;
+    children: ReactNode;
+}
+export declare function InboxProvider({ apiBase, labels, locale, onViewAll, onOpenPreferences, openLink, children }: InboxProviderProps): import("react").JSX.Element;

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

@@ -0,0 +1,70 @@
+import type { InboxNotification, InboxNotificationPage, InboxSummary, InboxTab } from './types.js';
+export interface InboxState {
+    unreadCount: number;
+    newestUnreadAt: string | null;
+    items: InboxNotification[];
+    nextCursor: string | null;
+    tab: InboxTab;
+    /** `error` only when nothing could be shown; a failed refresh keeps the last data. */
+    status: 'idle' | 'loading' | 'error' | 'refreshing';
+    /** The current tab has been loaded at least once. */
+    loaded: boolean;
+    loadingMore: boolean;
+    lastSyncedAt: string | null;
+    /** Items marked read before the server answered, as they were, so a failure puts them back. */
+    pending: Record<string, InboxNotification>;
+    /** The list and count as they were before "Mark all as read", until the server answers. */
+    markAll: {
+        items: InboxNotification[];
+        unreadCount: number;
+    } | null;
+    /** An action failed and was undone. Shown without closing the panel. */
+    actionFailed: boolean;
+}
+export declare const initialInboxState: InboxState;
+/** `replace` shows a first page; `append` adds an older page; `merge` refreshes the newest page and keeps older ones already shown. */
+export type PageMode = 'replace' | 'append' | 'merge';
+export type InboxAction = {
+    type: 'summaryReceived';
+    summary: InboxSummary;
+    at: string;
+} | {
+    type: 'loadStarted';
+    mode: PageMode;
+} | {
+    type: 'pageReceived';
+    page: InboxNotificationPage;
+    mode: PageMode;
+    at: string;
+} | {
+    type: 'loadFailed';
+    mode: PageMode;
+} | {
+    type: 'tabChanged';
+    tab: InboxTab;
+} | {
+    type: 'markReadOptimistic';
+    id: string;
+    at: string;
+} | {
+    type: 'markReadConfirmed';
+    id: string;
+    notification: InboxNotification;
+    unreadCount: number;
+} | {
+    type: 'markReadFailed';
+    id: string;
+} | {
+    type: 'markAllOptimistic';
+    at: string;
+} | {
+    type: 'markAllConfirmed';
+    unreadCount: number;
+} | {
+    type: 'markAllFailed';
+} | {
+    type: 'messageCleared';
+};
+export declare function inboxReducer(s: InboxState, a: InboxAction): InboxState;
+/** "Mark all as read" is offered only when something is unread and no such request is running (12.8). */
+export declare function canMarkAll(s: InboxState): boolean;