@xtremax/pigeon 0.0.0-stage → 0.3.1

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;

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

@@ -0,0 +1,19 @@
+/**
+ * The in-app inbox for an app: a bell with an unread badge, a panel, a full list and the person's preference.
+ * The bell shows what this app sent the person, and the tenant's announcements.
+ *
+ *   import { InboxProvider, NotificationBell } from '@xtremax/pigeon/inbox-react';
+ *   import '@xtremax/pigeon/inbox-react/styles.css';
+ *
+ *   <InboxProvider>
+ *     <NotificationBell />
+ *   </InboxProvider>
+ *
+ * The components call the host app's own routes (default `/api/communication/inbox`), which
+ * `createInboxHandler` from `@xtremax/pigeon/inbox` serves. They need React 19, Mantine 8 and Tabler icons. Nothing here holds a key or talks to another origin.
+ */
+export { InboxProvider, type InboxProviderProps } from './inbox-provider.js';
+export { NotificationBell } from './notification-bell.js';
+export { InboxFullList } from './inbox-full-list.js';
+export { DEFAULT_INBOX_LABELS, type InboxLabels } from './labels.js';
+export type { InboxNotification, InboxPreference, InboxSummary } from './types.js';

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

@@ -0,0 +1,40 @@
+/** Every visible and accessible text of the inbox (15.9). Pass `labels` to `InboxProvider` to replace any of them. `{n}` and `{label}` are filled in. */
+export interface InboxLabels {
+    /** The bell's accessible name when nothing is unread. */
+    bell: string;
+    /** The bell's accessible name with a count: "{label}, {n} unread". */
+    bellWithCount: string;
+    heading: string;
+    tabAll: string;
+    tabUnread: string;
+    /** The Unread tab with its count: "Unread ({n})". */
+    tabUnreadWithCount: string;
+    markAllRead: string;
+    viewAll: string;
+    preferences: string;
+    emptyAll: string;
+    emptyUnread: string;
+    loading: string;
+    loadError: string;
+    retry: string;
+    actionError: string;
+    dismiss: string;
+    /** The accessible name of a dialog's close button. */
+    close: string;
+    /** Read out before an unread row, so unread is not shown by colour alone. */
+    unread: string;
+    announcement: string;
+    loadMore: string;
+    /** Announced when the count rises while the panel is closed. */
+    newOne: string;
+    newMany: string;
+    fullListTitle: string;
+    preferencesTitle: string;
+    preferenceToggle: string;
+    preferenceOn: string;
+    preferenceOff: string;
+    preferenceLoadError: string;
+    preferenceSaveError: string;
+}
+export declare const DEFAULT_INBOX_LABELS: InboxLabels;
+export declare function mergeLabels(labels?: Partial<InboxLabels>): InboxLabels;

package/dist/types/inbox-react/notification-bell.d.ts

@@ -0,0 +1,4 @@
+/** The bell with its unread badge. Opens the inbox panel. Place it inside `InboxProvider`. */
+export declare function NotificationBell({ size }: {
+    size?: number;
+}): import("react").JSX.Element;

package/dist/types/inbox-react/notification-item.d.ts

@@ -0,0 +1,9 @@
+import type { InboxNotification } from './types.js';
+/**
+ * One notification. The whole row is one button: selecting it marks the notification read and opens its link when
+ * it has a safe one. Title and body are text nodes, never markup (12.14).
+ */
+export declare function NotificationItem({ item, now }: {
+    item: InboxNotification;
+    now: Date;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,9 @@
+import { type InboxErrorCode, type InboxMarkReadResult, type InboxNotification, type InboxNotificationPage, type InboxPreference, type InboxReadAllResult, type InboxSummary } from './types.js';
+export declare function parseNotification(v: unknown): InboxNotification | null;
+export declare function parseSummary(v: unknown): InboxSummary | null;
+export declare function parsePage(v: unknown): InboxNotificationPage | null;
+export declare function parseMarkRead(v: unknown): InboxMarkReadResult | null;
+export declare function parseReadAll(v: unknown): InboxReadAllResult | null;
+export declare function parsePreference(v: unknown): InboxPreference | null;
+/** The code of an error body, or the nearest one for the status. Anything unknown is `unavailable`. */
+export declare function parseErrorCode(status: number, body: unknown): InboxErrorCode;

package/dist/types/inbox-react/preference-dialog.d.ts

@@ -0,0 +1,5 @@
+/** The person's own choice for this app's in-app notifications. Other apps are not affected. */
+export declare function PreferenceDialog({ opened, onClose }: {
+    opened: boolean;
+    onClose: () => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,55 @@
+/**
+ * The inbox formats as the component reads them (IB-2). This module imports nothing from the SDK or the Gateway:
+ * it talks only to the host xApp's own routes.
+ */
+export interface InboxNotification {
+    id: string;
+    kind: 'notification' | 'announcement';
+    /** Plain text. Never rendered as markup. */
+    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;
+}
+/** The six answers of the host routes (IB-8). */
+export type InboxErrorCode = 'not_signed_in' | 'not_permitted' | 'not_found' | 'invalid_input' | 'rate_limited' | 'unavailable';
+export declare const INBOX_ERROR_CODES: readonly InboxErrorCode[];
+export type InboxResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    code: InboxErrorCode;
+};
+export type InboxTab = 'all' | 'unread';

package/dist/types/inbox-react/use-inbox-polling.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Visibility-aware polling (13.1 to 13.9). This is the only file a push transport would replace.
+ * No realtime connection and no web storage are used.
+ */
+export type PollOutcome = {
+    result: 'ok';
+    pollSeconds: number;
+} | {
+    result: 'failed';
+} | {
+    result: 'stop';
+};
+export declare const POLL_FLOOR_SECONDS = 15;
+export declare 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 declare function nextPollDelay(failures: number, recommendedSeconds: number, random?: () => number): number;
+export interface PollingEnvironment {
+    isVisible: () => boolean;
+    onVisibilityChange: (listener: () => void) => () => void;
+    setTimer: (fn: () => void, ms: number) => unknown;
+    clearTimer: (handle: unknown) => void;
+    random: () => number;
+}
+/**
+ * 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 declare function startPolling(poll: () => Promise<PollOutcome>, env: PollingEnvironment): () => void;
+/** Runs `poll` for as long as the component is mounted and `enabled` is true. `poll` may change between renders. */
+export declare function useInboxPolling(poll: () => Promise<PollOutcome>, enabled?: boolean): void;

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export { createCommunicationClient, CommunicationError, type ClientOptions, type CommunicationClient } from './client.js';
+export { createEventHandler, verifyEventSignature, type EventHandlerOptions, type VerifyResult } from './events.js';
+export { deriveIdempotencyKey, newIdempotencyKey } from './idempotency.js';
+export { DEFAULT_RETRY, type RetryPolicy } from './retry.js';
+export type * from './contract.js';
+export type { ErrorCode } from './errors.js';

package/dist/types/retry.d.ts

@@ -0,0 +1,13 @@
+export interface RetryPolicy {
+    maxAttempts: number;
+    baseDelayMs: number;
+    capDelayMs: number;
+    /** Total time across attempts and waits. */
+    totalTimeoutMs: number;
+    perAttemptTimeoutMs: number;
+}
+export declare const DEFAULT_RETRY: RetryPolicy;
+/** Exponential backoff with full jitter, honouring Retry-After when the server sent one. */
+export declare function backoffMs(attempt: number, policy: RetryPolicy, retryAfterSeconds: number | null, random?: () => number): number;
+/** Only transient failures are retried: network errors, timeouts, 429 and 5xx. Client errors never are. */
+export declare const isRetryableStatus: (status: number) => boolean;

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@xtremax/pigeon",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "Client for Pigeon, the Buildpad Communication Gateway: send messages, verify signed events, serve an in-app inbox and show its notification bell.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "sideEffects": ["**/*.css"],
+  "engines": { "node": ">=20" },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": { "browser": "./dist/esm/browser-stub.js", "types": "./dist/types/index.d.ts", "import": "./dist/esm/index.js", "require": "./dist/cjs/index.js" },
+    "./client": { "browser": "./dist/esm/browser-stub.js", "types": "./dist/types/client.d.ts", "import": "./dist/esm/client.js", "require": "./dist/cjs/client.js" },
+    "./inbox": { "browser": "./dist/esm/inbox/browser-stub.js", "types": "./dist/types/inbox/index.d.ts", "import": "./dist/esm/inbox/index.js", "require": "./dist/cjs/inbox/index.js" },
+    "./inbox-react": { "types": "./dist/types/inbox-react/index.d.ts", "import": "./dist/esm/inbox-react/index.js", "require": "./dist/cjs/inbox-react/index.js" },
+    "./inbox-react/styles.css": "./dist/inbox-react/styles.css",
+    "./events": { "types": "./dist/types/events.d.ts", "import": "./dist/esm/events.js", "require": "./dist/cjs/events.js" },
+    "./contract": { "types": "./dist/types/contract.d.ts" }
+  },
+  "bin": { "pigeon": "./bin/pigeon.mjs" },
+  "files": ["dist", "bin", "skills", "README.md", "CHANGELOG.md"],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepublishOnly": "node scripts/build.mjs"
+  },
+  "publishConfig": { "access": "public" },
+  "peerDependencies": { "@mantine/core": "^8", "@mantine/hooks": "^8", "@tabler/icons-react": "^3", "react": "^19" },
+  "peerDependenciesMeta": {
+    "@mantine/core": { "optional": true },
+    "@mantine/hooks": { "optional": true },
+    "@tabler/icons-react": { "optional": true },
+    "react": { "optional": true }
+  },
+  "devDependencies": { "@types/node": "^20", "typescript": "^5" }
+}