@xtremax/pigeon 0.0.0-stage → 0.3.0

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,35 @@
 {
   "name": "@xtremax/pigeon",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "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" }
+  },
+  "files": ["dist", "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" }
+}