@orbitconnect/react 0.1.1 → 0.1.4

package/dist/offline/BroadcastChannelCoordinator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * BroadcastChannelCoordinator — OrbitConnect Web SDK
+ *
+ * Coordinates offline queue operations across multiple browser tabs:
+ * - Leader election: only one tab owns the flush loop
+ * - Message state sync: when one tab sends, all tabs update
+ * - Prevents duplicate queue flushes
+ */
+export interface BroadcastMessage {
+    type: 'leader_claim' | 'leader_heartbeat' | 'message_sent' | 'message_failed' | 'queue_flushed';
+    tabId: string;
+    payload?: Record<string, unknown>;
+}
+export declare class BroadcastChannelCoordinator {
+    private channel;
+    private tabId;
+    private isLeader;
+    private leaderTabId;
+    private heartbeatTimer;
+    private leaderTimeoutTimer;
+    private onBecomeLeader;
+    private onMessageSent;
+    private static readonly CHANNEL_NAME;
+    private static readonly HEARTBEAT_INTERVAL;
+    private static readonly LEADER_TIMEOUT;
+    constructor();
+    /** Start coordination — attempts leader election */
+    start(opts: {
+        onBecomeLeader: () => void;
+        onMessageSent?: (localId: string, serverId: string) => void;
+    }): void;
+    /** Stop coordination */
+    stop(): void;
+    /** Whether this tab is the current leader (owns flush loop) */
+    get isCurrentLeader(): boolean;
+    /** Broadcast that a message was sent (so other tabs can update their UI) */
+    broadcastMessageSent(localId: string, serverId: string): void;
+    /** Broadcast that a message failed */
+    broadcastMessageFailed(localId: string, error: string): void;
+    private claimLeadership;
+    private becomeLeader;
+    private handleMessage;
+    private resetLeaderTimeout;
+    private broadcast;
+}

package/dist/offline/BrowserNetworkListener.d.ts

@@ -0,0 +1,16 @@
+/**
+ * BrowserNetworkListener — OrbitConnect Web SDK
+ *
+ * Monitors browser online/offline state using the Navigator API
+ * and window events. Triggers queue flush on reconnect.
+ */
+import type { NetworkListener } from './types';
+export declare class BrowserNetworkListener implements NetworkListener {
+    private onOnlineCb;
+    private onOfflineCb;
+    private boundOnline;
+    private boundOffline;
+    start(onOnline: () => void, onOffline: () => void): void;
+    stop(): void;
+    isOnline(): boolean;
+}

package/dist/offline/IndexedDBStorageAdapter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * IndexedDB Storage Adapter — OrbitConnect Web SDK
+ *
+ * Persists the offline message queue to IndexedDB for:
+ * - Page refresh survival
+ * - Browser restart recovery
+ * - Tab crash recovery
+ */
+import type { OrbitOfflineMessage, OfflineStorageAdapter } from './types';
+export declare class IndexedDBStorageAdapter implements OfflineStorageAdapter {
+    private db;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    enqueue(message: OrbitOfflineMessage): Promise<void>;
+    update(localId: string, updates: Partial<OrbitOfflineMessage>): Promise<void>;
+    remove(localId: string): Promise<void>;
+    getPending(): Promise<OrbitOfflineMessage[]>;
+    getByConversation(conversationId: string): Promise<OrbitOfflineMessage[]>;
+    findByIdempotencyKey(key: string): Promise<OrbitOfflineMessage | undefined>;
+    clearFailed(conversationId?: string): Promise<void>;
+    getCounts(): Promise<{
+        pending: number;
+        failed: number;
+        sending: number;
+    }>;
+    private getDb;
+}

package/dist/offline/OfflineContext.d.ts

@@ -0,0 +1,33 @@
+/**
+ * OfflineContext — React context for the offline queue system.
+ */
+import type { QueueManager } from './QueueManager';
+import type { OrbitOfflineMessage, QueueSendOptions } from './types';
+export interface OfflineQueueContextValue {
+    /** The queue manager instance */
+    queueManager: QueueManager;
+    /** Whether the device/browser is currently online */
+    isOnline: boolean;
+    /** Enqueue a message (persist + optimistic + attempt send) */
+    enqueue: (opts: QueueSendOptions) => Promise<OrbitOfflineMessage>;
+    /** Retry a specific failed message */
+    retryMessage: (localId: string) => Promise<void>;
+    /** Retry all failed messages */
+    retryAll: () => Promise<void>;
+    /** Pause the queue */
+    pauseQueue: () => void;
+    /** Resume the queue */
+    resumeQueue: () => void;
+    /** Get pending messages for a conversation */
+    getPendingMessages: (conversationId?: string) => Promise<OrbitOfflineMessage[]>;
+    /** Clear all failed messages */
+    clearFailedMessages: (conversationId?: string) => Promise<void>;
+    /** Get queue status counts */
+    getQueueStatus: () => Promise<{
+        pending: number;
+        failed: number;
+        sending: number;
+    }>;
+}
+export declare const OfflineQueueContext: import("react").Context<OfflineQueueContextValue | null>;
+export declare function useOfflineQueue(): OfflineQueueContextValue;

package/dist/offline/OfflineQueueProvider.d.ts

@@ -0,0 +1,15 @@
+/**
+ * OfflineQueueProvider — React Web SDK
+ *
+ * Manages the offline queue lifecycle:
+ * - Initializes IndexedDB storage
+ * - Creates QueueManager
+ * - Wires network listener (browser online/offline events)
+ * - Wires socket status listener (flush on reconnect)
+ * - Provides BroadcastChannel multi-tab coordination
+ * - Exposes queue operations via context
+ */
+import { type ReactNode } from 'react';
+export declare function OfflineQueueProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/offline/QueueManager.d.ts

@@ -0,0 +1,68 @@
+/**
+ * QueueManager — Core offline queue engine for OrbitConnect SDK.
+ *
+ * Responsibilities:
+ * - Enqueue messages with localId generation
+ * - Maintain FIFO order per conversation
+ * - Retry failed sends with exponential backoff
+ * - Handle ACK reconciliation (match serverId to localId)
+ * - Recover pending/failed items after reconnect
+ * - Remove sent items from persistent storage
+ * - Emit SDK events for each state transition
+ */
+import type { OrbitOfflineMessage, OfflineStorageAdapter, QueueEventType, QueueEventHandler, QueueSendOptions } from './types';
+export type SendFn = (msg: OrbitOfflineMessage) => Promise<{
+    id: string;
+    sequence_number: number;
+}>;
+export declare class QueueManager {
+    private storage;
+    private sendFn;
+    private listeners;
+    private retryTimers;
+    private flushing;
+    private paused;
+    private online;
+    constructor(storage: OfflineStorageAdapter);
+    /** Set the send function (provided by the SDK layer with apiClient access) */
+    setSendFn(fn: SendFn): void;
+    /** Set network status */
+    setOnline(online: boolean): void;
+    /** Restore queue from storage — call on initialization */
+    restore(): Promise<OrbitOfflineMessage[]>;
+    /** Enqueue a new message — persists locally and attempts send */
+    enqueue(opts: QueueSendOptions): Promise<OrbitOfflineMessage>;
+    /** Retry a specific failed message */
+    retryMessage(localId: string): Promise<void>;
+    /** Retry all failed messages */
+    retryAll(): Promise<void>;
+    /** Flush all pending messages (queued status) */
+    flushPending(): Promise<void>;
+    /** Mark a message as sent (called when server ACK arrives via WS) */
+    markSentByIdempotencyKey(idempotencyKey: string, serverId: string): Promise<boolean>;
+    /** Pause the queue — stops all sends and retries */
+    pause(): void;
+    /** Resume the queue — triggers flush */
+    resume(): void;
+    /** Get all pending messages for a conversation */
+    getPendingMessages(conversationId?: string): Promise<OrbitOfflineMessage[]>;
+    /** Clear all failed messages */
+    clearFailed(conversationId?: string): Promise<void>;
+    /** Get queue status counts */
+    getStatus(): Promise<{
+        pending: number;
+        failed: number;
+        sending: number;
+    }>;
+    /** Subscribe to queue events */
+    on<K extends QueueEventType>(event: K, handler: QueueEventHandler<K>): () => void;
+    /** Unsubscribe from queue events */
+    off<K extends QueueEventType>(event: K, handler: QueueEventHandler<K>): void;
+    /** Destroy — clear all timers */
+    destroy(): void;
+    private emit;
+    /** Fire-and-forget send attempt (used for immediate sends after enqueue) */
+    private attemptSend;
+    /** Synchronous send attempt — returns true if sent successfully */
+    private attemptSendSync;
+}

package/dist/offline/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Offline Queue — Public API
+ */
+export { OfflineQueueProvider } from './OfflineQueueProvider';
+export { useOfflineQueue } from './OfflineContext';
+export { QueueManager } from './QueueManager';
+export { IndexedDBStorageAdapter } from './IndexedDBStorageAdapter';
+export { BrowserNetworkListener } from './BrowserNetworkListener';
+export { BroadcastChannelCoordinator } from './BroadcastChannelCoordinator';
+export type { OrbitOfflineMessage, OfflineStorageAdapter, OfflineMessageStatus, QueueEventType, QueueEventPayloads, QueueEventHandler, NetworkListener, QueueSendOptions, } from './types';

package/dist/offline/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Offline Queue Types — OrbitConnect SDK
+ *
+ * Shared type definitions for the offline messaging system.
+ * Used by both React Web and React Native SDKs.
+ */
+/** Message status in the offline queue lifecycle */
+export type OfflineMessageStatus = 'queued' | 'sending' | 'sent' | 'failed';
+/** Offline message model — persisted locally before sending */
+export interface OrbitOfflineMessage {
+    /** Client-generated UUID — used for optimistic rendering and dedup */
+    localId: string;
+    /** Server-assigned UUID — populated after successful send */
+    serverId?: string;
+    /** Target conversation */
+    conversationId: string;
+    /** Sender app_user ID */
+    senderId: string;
+    /** Message content (text or encrypted) */
+    body: string | null;
+    /** Current queue status */
+    status: OfflineMessageStatus;
+    /** Number of send attempts */
+    retries: number;
+    /** Whether the message has been confirmed by the server */
+    synced: boolean;
+    /** Client-side creation timestamp (epoch ms) */
+    createdAt: number;
+    /** Last status change timestamp (epoch ms) */
+    updatedAt: number;
+    /** Idempotency key sent to backend */
+    idempotencyKey: string;
+    /** Message type matching backend enum */
+    type: 'text' | 'media' | 'system';
+    /** Optional metadata (reply_to, attachment_type, e2e flags, etc.) */
+    metadata?: Record<string, unknown>;
+    /** Media file ID (if attachment was already uploaded) */
+    mediaId?: string;
+}
+/** Storage adapter interface — implemented per platform */
+export interface OfflineStorageAdapter {
+    /** Open/initialize the storage backend */
+    open(): Promise<void>;
+    /** Close the storage backend */
+    close(): Promise<void>;
+    /** Persist a message to the queue */
+    enqueue(message: OrbitOfflineMessage): Promise<void>;
+    /** Update an existing queued message */
+    update(localId: string, updates: Partial<OrbitOfflineMessage>): Promise<void>;
+    /** Remove a message from the queue */
+    remove(localId: string): Promise<void>;
+    /** Get all pending messages (queued + failed), ordered by createdAt */
+    getPending(): Promise<OrbitOfflineMessage[]>;
+    /** Get all messages for a specific conversation */
+    getByConversation(conversationId: string): Promise<OrbitOfflineMessage[]>;
+    /** Find a message by its idempotency key */
+    findByIdempotencyKey(key: string): Promise<OrbitOfflineMessage | undefined>;
+    /** Clear all failed messages, optionally scoped to a conversation */
+    clearFailed(conversationId?: string): Promise<void>;
+    /** Get queue counts by status */
+    getCounts(): Promise<{
+        pending: number;
+        failed: number;
+        sending: number;
+    }>;
+}
+/** Queue event types emitted by the QueueManager */
+export type QueueEventType = 'messageQueued' | 'messageSending' | 'messageSent' | 'messageFailed' | 'queueFlushed' | 'networkRestored' | 'networkLost';
+/** Payload for queue events */
+export interface QueueEventPayloads {
+    messageQueued: {
+        localId: string;
+        conversationId: string;
+    };
+    messageSending: {
+        localId: string;
+        attempt: number;
+    };
+    messageSent: {
+        localId: string;
+        serverId: string;
+        conversationId: string;
+    };
+    messageFailed: {
+        localId: string;
+        error: string;
+        retries: number;
+        conversationId: string;
+    };
+    queueFlushed: {
+        count: number;
+        conversationId?: string;
+    };
+    networkRestored: undefined;
+    networkLost: undefined;
+}
+/** Queue event handler */
+export type QueueEventHandler<K extends QueueEventType> = (payload: QueueEventPayloads[K]) => void;
+/** Network status listener interface */
+export interface NetworkListener {
+    /** Start listening for network changes */
+    start(onOnline: () => void, onOffline: () => void): void;
+    /** Stop listening */
+    stop(): void;
+    /** Current online status */
+    isOnline(): boolean;
+}
+/** Options for sending a message through the offline queue */
+export interface QueueSendOptions {
+    conversationId: string;
+    senderId: string;
+    body: string | null;
+    type?: 'text' | 'media' | 'system';
+    metadata?: Record<string, unknown>;
+    mediaId?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbitconnect/react",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "OrbitConnect React SDK — drop-in real-time chat, voice/video calls, and meetings",
   "author": "OrbitConnect <sdk@orbitconnect.cloud>",
   "license": "MIT",