@pedi/chika-sdk 1.0.4 → 1.0.6

package/README.md

@@ -14,16 +14,27 @@ Provides a drop-in React hook (`useChat`) that connects your React Native app to
 - **Message deduplication** — Prevents duplicate messages from SSE echo and reconnection replays
 - **Optimistic UI** — Messages appear in the local list instantly on send, before server confirmation
 - **Type-safe chat domains** — Full generic support via `ChatDomain` so message types, roles, and attributes are enforced at compile time
+- **Automatic retry on failure** — Failed message sends are automatically retried with exponential backoff before giving up
+- **Offline message queuing** — Messages sent while offline are queued and flushed when connectivity returns
+- **Network-aware reconnection** — SSE reconnection waits for network availability and uses exponential backoff instead of fixed delays
 
 ## Key Features
 
 - `useChat<D>()` React hook with full TypeScript generics
 - `createChatSession<D>()` imperative API for non-React usage
+- **`useUnread()` hook** — Real-time unread count tracking via dedicated SSE stream with passive listening support
 - Automatic SSE reconnection with configurable delay
 - Platform-aware AppState handling (iOS vs Android)
 - Optimistic message sending with deduplication
 - Hash-based bucket routing for multi-server deployments
-- Custom error classes (`ChatDisconnectedError`, `ChannelClosedError`)
+- Custom error classes (`ChatDisconnectedError`, `ChannelClosedError`, `HttpError`, `RetryExhaustedError`, `QueueFullError`)
+- Network resilience with automatic retry (exponential backoff, jitter, 429 Retry-After support)
+- Offline message queue with per-message status tracking (`sending`, `queued`, `failed`)
+- Optional `@react-native-community/netinfo` integration for network-aware reconnection
+- Persistent queue storage via auto-detected MMKV or AsyncStorage
+- Server-side idempotency keys to prevent duplicate messages on retry
+- Per-message `cancelMessage()` and `retryMessage()` controls
+- All resilience features togglable — set `resilience: false` to disable
 
 ## Quick Start
 
@@ -45,12 +56,80 @@ function ChatScreen({ bookingId, user }) {
 }
 ```
 
+### Unread Notifications
+
+Monitor unread message counts in real-time — even for channels the user hasn't joined yet:
+
+```typescript
+import { useUnread } from '@pedi/chika-sdk';
+
+function ChatListItem({ channelId, userId, config }) {
+  const { unreadCount, hasUnread, lastMessageAt } = useUnread({
+    config,
+    channelId,
+    participantId: userId,
+  });
+
+  return (
+    <View>
+      <Text>{channelId}</Text>
+      {hasUnread && <Badge count={unreadCount} />}
+    </View>
+  );
+}
+```
+
+The hook handles SSE reconnection and AppState-aware lifecycle management automatically. Disable it with `enabled: false` when `useChat` is already active on the same channel.
+
+### Network Resilience
+
+Resilience features automatically handle failures, offline scenarios, and network transitions:
+
+```typescript
+import { useChat, createManifest, createQueueStorage } from '@pedi/chika-sdk';
+
+function ChatScreen({ bookingId, user }) {
+  const {
+    messages, status, sendMessage,
+    pendingMessages, cancelMessage, retryMessage,
+  } = useChat<PediChat>({
+    config: {
+      manifest: createManifest('https://chat.example.com'),
+      headers: { Authorization: `Bearer ${token}` },
+      resilience: {
+        retry: { maxAttempts: 5 },
+        queueStorage: createQueueStorage() ?? undefined,
+      },
+    },
+    channelId: `booking_${bookingId}`,
+    profile: { id: user.id, role: 'rider', name: user.name },
+  });
+
+  // Messages queue automatically when offline, retry on failure
+  await sendMessage('chat', 'Hello!');
+
+  // Show per-message status in UI
+  for (const msg of pendingMessages) {
+    if (msg.status === 'failed') {
+      // Show retry/cancel buttons
+      retryMessage(msg.optimisticId);
+      // or: cancelMessage(msg.optimisticId);
+    }
+  }
+}
+```
+
+Resilience is enabled by default. Disable with `resilience: false` for manual control.
+
 **Peer dependencies:** `react >= 18`, `react-native >= 0.72`
 
+**Optional peer dependencies:** `@react-native-community/netinfo` (network monitoring), `react-native-mmkv` or `@react-native-async-storage/async-storage` (queue persistence)
+
 ## Documentation
 
 See the [docs](./docs/) for detailed documentation:
 
 - [API Reference](./docs/api-reference.md) — `useChat`, `createChatSession`, utilities, error classes, and all config options
 - [Guides](./docs/guides.md) — Connection lifecycle, AppState handling, reconnection, deduplication, custom domains
+- [Network Resilience Guide](./docs/resilience-guide.md) — Retry, offline queue, network monitoring, persistent storage, and configuration
 - [AI Agent Integration Guide](./docs/llm-integration-guide.md) — Patterns, recipes, pitfalls, and checklists for LLM-assisted implementation

package/dist/index.d.mts

@@ -1,23 +1,84 @@
 import { ChatManifest, ChatDomain, DefaultDomain, Participant, Message, MessageAttributes, SendMessageResponse } from '@pedi/chika-types';
 export { ChatBucket, ChatDomain, ChatManifest, DefaultDomain, MarkReadRequest, Message, MessageAttributes, Participant, PediChat, PediLocation, PediMessageAttributes, PediMessageType, PediParticipantMeta, PediRole, PediVehicle, SSEUnreadClearEvent, SSEUnreadEvent, SSEUnreadUpdateEvent, SendMessageResponse, UnreadCountResponse } from '@pedi/chika-types';
 
-type ChatStatus = 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'closed' | 'error';
+interface RetryConfig {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitterFactor: number;
+}
+declare function calculateBackoff(attempt: number, config: RetryConfig): number;
+declare function isRetryableError(error: unknown): boolean;
+declare function resolveRetryConfig(resilience: {
+    retry?: Partial<RetryConfig> | false;
+} | false | undefined): RetryConfig | null;
+declare function withRetry<T>(fn: () => Promise<T>, config?: RetryConfig, signal?: AbortSignal): Promise<T>;
+
+interface NetworkMonitor {
+    isConnected(): boolean;
+    subscribe(cb: (connected: boolean) => void): () => void;
+    waitForOnline(signal?: AbortSignal): Promise<void>;
+    dispose(): void;
+}
+declare function createNetworkMonitor(): NetworkMonitor;
+
+interface QueueStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
 /**
- * Configuration for the chat SDK.
+ * Auto-detect the best available storage for queue persistence.
+ * Priority: react-native-mmkv (fastest, sync) > AsyncStorage > null.
+ * Returns `null` if neither is installed — no hard dependencies.
  *
- * @property manifest - Bucket routing manifest for server URL resolution.
- * @property headers - Custom headers applied to all HTTP and SSE requests (e.g., auth tokens).
- * @property reconnectDelayMs - Delay before SSE reconnection attempt. Default: 3000ms.
- * @property backgroundGraceMs - Grace period before teardown on app background. Default: 2000ms on Android, 0ms on iOS.
+ * Usage:
+ * ```ts
+ * import { createQueueStorage } from '@pedi/chika-sdk';
+ *
+ * const config: ChatConfig = {
+ *   resilience: {
+ *     queueStorage: createQueueStorage() ?? undefined,
+ *   },
+ * };
+ * ```
  */
+declare function createQueueStorage(): QueueStorage | null;
+/**
+ * Creates a QueueStorage adapter backed by `@react-native-async-storage/async-storage`.
+ * Returns `null` if the package is not installed.
+ */
+declare function createAsyncStorageAdapter(): QueueStorage | null;
+type MessageSendStatus = 'sending' | 'queued' | 'failed';
+interface QueuedMessage {
+    optimisticId: string;
+    status: MessageSendStatus;
+    error?: Error;
+    retryCount: number;
+}
+
+type ChatStatus = 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'closed' | 'error';
+interface ResilienceConfig {
+    /** Retry config overrides. Set false to disable retry entirely. */
+    retry?: Partial<RetryConfig> | false;
+    /** Enable offline message queuing. Default: true. */
+    offlineQueue?: boolean;
+    /** Max queued messages. Default: 50. */
+    maxQueueSize?: number;
+    /** Inject custom NetworkMonitor (bypasses built-in NetInfo detection). */
+    networkMonitor?: NetworkMonitor;
+    /** Persistent storage adapter for queue (AsyncStorage/MMKV/etc). */
+    queueStorage?: QueueStorage;
+}
 /**
  * Configuration for the chat SDK.
  *
  * @property manifest - Bucket routing manifest for server URL resolution.
  * @property headers - Custom headers applied to all HTTP and SSE requests (e.g., auth tokens).
- * @property reconnectDelayMs - Delay before SSE reconnection attempt. Default: 3000ms.
+ * @property reconnectDelayMs - Base delay before SSE reconnection attempt. Default: 3000ms.
  * @property backgroundGraceMs - Grace period before teardown on app background. Default: 2000ms on Android, 0ms on iOS.
  * @property optimisticSend - Append messages to the local array immediately on send. Default: true.
+ * @property resilience - Network resilience options. Enabled by default. Set false to disable all.
  */
 interface ChatConfig {
     manifest: ChatManifest;
@@ -25,6 +86,7 @@ interface ChatConfig {
     reconnectDelayMs?: number;
     backgroundGraceMs?: number;
     optimisticSend?: boolean;
+    resilience?: ResilienceConfig | false;
 }
 interface UseChatOptions<D extends ChatDomain = DefaultDomain> {
     config: ChatConfig;
@@ -39,11 +101,18 @@ interface UseChatReturn<D extends ChatDomain = DefaultDomain> {
     error: Error | null;
     sendMessage: (type: D['messageType'], body: string, attributes?: MessageAttributes<D>) => Promise<SendMessageResponse>;
     disconnect: () => void;
+    /** Per-message send status for queued/retrying messages. Empty when resilience disabled. */
+    pendingMessages: QueuedMessage[];
+    /** Cancel a queued or failed message by its optimistic ID. */
+    cancelMessage: (optimisticId: string) => void;
+    /** Retry a failed message by its optimistic ID. */
+    retryMessage: (optimisticId: string) => void;
 }
 
 /**
  * React hook for real-time chat over SSE.
- * Manages connection lifecycle, AppState transitions, message deduplication, and reconnection.
+ * Manages connection lifecycle, AppState transitions, message deduplication, reconnection,
+ * and optional network resilience (retry, offline queue, network monitoring).
  *
  * @template D - Chat domain type for role/message type narrowing. Defaults to DefaultDomain.
  */
@@ -74,11 +143,12 @@ interface ChatSession<D extends ChatDomain = DefaultDomain> {
     channelId: string;
     initialParticipants: Participant<D>[];
     initialMessages: Message<D>[];
-    sendMessage: (type: D['messageType'], body: string, attributes?: MessageAttributes<D>) => Promise<SendMessageResponse>;
+    networkMonitor: NetworkMonitor | null;
+    sendMessage: (type: D['messageType'], body: string, attributes?: MessageAttributes<D>, idempotencyKey?: string) => Promise<SendMessageResponse>;
     markAsRead: (messageId: string) => Promise<void>;
     disconnect: () => void;
 }
-declare function createChatSession<D extends ChatDomain = DefaultDomain>(config: ChatConfig, channelId: string, profile: Participant<D>, callbacks: SessionCallbacks<D>): Promise<ChatSession<D>>;
+declare function createChatSession<D extends ChatDomain = DefaultDomain>(config: ChatConfig, channelId: string, profile: Participant<D>, callbacks: SessionCallbacks<D>, networkMonitor?: NetworkMonitor): Promise<ChatSession<D>>;
 
 /**
  * Creates a single-server manifest. Use this when all channels route to the same server.
@@ -97,6 +167,7 @@ interface SSEConnectionConfig {
     reconnectDelayMs?: number;
     lastEventId?: string;
     customEvents?: string[];
+    networkMonitor?: NetworkMonitor;
 }
 interface SSEConnectionCallbacks {
     onOpen?: () => void;
@@ -107,6 +178,7 @@ interface SSEConnectionCallbacks {
 }
 interface SSEConnection {
     close: () => void;
+    reconnectImmediate: () => void;
 }
 declare function createSSEConnection(config: SSEConnectionConfig, callbacks: SSEConnectionCallbacks): SSEConnection;
 
@@ -118,5 +190,21 @@ declare class ChannelClosedError extends Error {
     readonly channelId: string;
     constructor(channelId: string);
 }
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    readonly retryAfter?: number | undefined;
+    constructor(status: number, body: string, retryAfter?: number | undefined);
+}
+declare class RetryExhaustedError extends Error {
+    readonly operation: string;
+    readonly attempts: number;
+    readonly lastError: Error;
+    constructor(operation: string, attempts: number, lastError: Error);
+}
+declare class QueueFullError extends Error {
+    readonly maxSize: number;
+    constructor(maxSize: number);
+}
 
-export { ChannelClosedError, type ChatConfig, ChatDisconnectedError, type ChatSession, type ChatStatus, type SSEConnection, type SSEConnectionCallbacks, type SSEConnectionConfig, type SessionCallbacks, type UseChatOptions, type UseChatReturn, type UseUnreadOptions, type UseUnreadReturn, createChatSession, createManifest, createSSEConnection, resolveServerUrl, useChat, useUnread };
+export { ChannelClosedError, type ChatConfig, ChatDisconnectedError, type ChatSession, type ChatStatus, HttpError, type MessageSendStatus, type NetworkMonitor, QueueFullError, type QueueStorage, type QueuedMessage, type ResilienceConfig, type RetryConfig, RetryExhaustedError, type SSEConnection, type SSEConnectionCallbacks, type SSEConnectionConfig, type SessionCallbacks, type UseChatOptions, type UseChatReturn, type UseUnreadOptions, type UseUnreadReturn, calculateBackoff, createAsyncStorageAdapter, createChatSession, createManifest, createNetworkMonitor, createQueueStorage, createSSEConnection, isRetryableError, resolveRetryConfig, resolveServerUrl, useChat, useUnread, withRetry };

package/dist/index.d.ts

@@ -1,23 +1,84 @@
 import { ChatManifest, ChatDomain, DefaultDomain, Participant, Message, MessageAttributes, SendMessageResponse } from '@pedi/chika-types';
 export { ChatBucket, ChatDomain, ChatManifest, DefaultDomain, MarkReadRequest, Message, MessageAttributes, Participant, PediChat, PediLocation, PediMessageAttributes, PediMessageType, PediParticipantMeta, PediRole, PediVehicle, SSEUnreadClearEvent, SSEUnreadEvent, SSEUnreadUpdateEvent, SendMessageResponse, UnreadCountResponse } from '@pedi/chika-types';
 
-type ChatStatus = 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'closed' | 'error';
+interface RetryConfig {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitterFactor: number;
+}
+declare function calculateBackoff(attempt: number, config: RetryConfig): number;
+declare function isRetryableError(error: unknown): boolean;
+declare function resolveRetryConfig(resilience: {
+    retry?: Partial<RetryConfig> | false;
+} | false | undefined): RetryConfig | null;
+declare function withRetry<T>(fn: () => Promise<T>, config?: RetryConfig, signal?: AbortSignal): Promise<T>;
+
+interface NetworkMonitor {
+    isConnected(): boolean;
+    subscribe(cb: (connected: boolean) => void): () => void;
+    waitForOnline(signal?: AbortSignal): Promise<void>;
+    dispose(): void;
+}
+declare function createNetworkMonitor(): NetworkMonitor;
+
+interface QueueStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
 /**
- * Configuration for the chat SDK.
+ * Auto-detect the best available storage for queue persistence.
+ * Priority: react-native-mmkv (fastest, sync) > AsyncStorage > null.
+ * Returns `null` if neither is installed — no hard dependencies.
  *
- * @property manifest - Bucket routing manifest for server URL resolution.
- * @property headers - Custom headers applied to all HTTP and SSE requests (e.g., auth tokens).
- * @property reconnectDelayMs - Delay before SSE reconnection attempt. Default: 3000ms.
- * @property backgroundGraceMs - Grace period before teardown on app background. Default: 2000ms on Android, 0ms on iOS.
+ * Usage:
+ * ```ts
+ * import { createQueueStorage } from '@pedi/chika-sdk';
+ *
+ * const config: ChatConfig = {
+ *   resilience: {
+ *     queueStorage: createQueueStorage() ?? undefined,
+ *   },
+ * };
+ * ```
  */
+declare function createQueueStorage(): QueueStorage | null;
+/**
+ * Creates a QueueStorage adapter backed by `@react-native-async-storage/async-storage`.
+ * Returns `null` if the package is not installed.
+ */
+declare function createAsyncStorageAdapter(): QueueStorage | null;
+type MessageSendStatus = 'sending' | 'queued' | 'failed';
+interface QueuedMessage {
+    optimisticId: string;
+    status: MessageSendStatus;
+    error?: Error;
+    retryCount: number;
+}
+
+type ChatStatus = 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'closed' | 'error';
+interface ResilienceConfig {
+    /** Retry config overrides. Set false to disable retry entirely. */
+    retry?: Partial<RetryConfig> | false;
+    /** Enable offline message queuing. Default: true. */
+    offlineQueue?: boolean;
+    /** Max queued messages. Default: 50. */
+    maxQueueSize?: number;
+    /** Inject custom NetworkMonitor (bypasses built-in NetInfo detection). */
+    networkMonitor?: NetworkMonitor;
+    /** Persistent storage adapter for queue (AsyncStorage/MMKV/etc). */
+    queueStorage?: QueueStorage;
+}
 /**
  * Configuration for the chat SDK.
  *
  * @property manifest - Bucket routing manifest for server URL resolution.
  * @property headers - Custom headers applied to all HTTP and SSE requests (e.g., auth tokens).
- * @property reconnectDelayMs - Delay before SSE reconnection attempt. Default: 3000ms.
+ * @property reconnectDelayMs - Base delay before SSE reconnection attempt. Default: 3000ms.
  * @property backgroundGraceMs - Grace period before teardown on app background. Default: 2000ms on Android, 0ms on iOS.
  * @property optimisticSend - Append messages to the local array immediately on send. Default: true.
+ * @property resilience - Network resilience options. Enabled by default. Set false to disable all.
  */
 interface ChatConfig {
     manifest: ChatManifest;
@@ -25,6 +86,7 @@ interface ChatConfig {
     reconnectDelayMs?: number;
     backgroundGraceMs?: number;
     optimisticSend?: boolean;
+    resilience?: ResilienceConfig | false;
 }
 interface UseChatOptions<D extends ChatDomain = DefaultDomain> {
     config: ChatConfig;
@@ -39,11 +101,18 @@ interface UseChatReturn<D extends ChatDomain = DefaultDomain> {
     error: Error | null;
     sendMessage: (type: D['messageType'], body: string, attributes?: MessageAttributes<D>) => Promise<SendMessageResponse>;
     disconnect: () => void;
+    /** Per-message send status for queued/retrying messages. Empty when resilience disabled. */
+    pendingMessages: QueuedMessage[];
+    /** Cancel a queued or failed message by its optimistic ID. */
+    cancelMessage: (optimisticId: string) => void;
+    /** Retry a failed message by its optimistic ID. */
+    retryMessage: (optimisticId: string) => void;
 }
 
 /**
  * React hook for real-time chat over SSE.
- * Manages connection lifecycle, AppState transitions, message deduplication, and reconnection.
+ * Manages connection lifecycle, AppState transitions, message deduplication, reconnection,
+ * and optional network resilience (retry, offline queue, network monitoring).
  *
  * @template D - Chat domain type for role/message type narrowing. Defaults to DefaultDomain.
  */
@@ -74,11 +143,12 @@ interface ChatSession<D extends ChatDomain = DefaultDomain> {
     channelId: string;
     initialParticipants: Participant<D>[];
     initialMessages: Message<D>[];
-    sendMessage: (type: D['messageType'], body: string, attributes?: MessageAttributes<D>) => Promise<SendMessageResponse>;
+    networkMonitor: NetworkMonitor | null;
+    sendMessage: (type: D['messageType'], body: string, attributes?: MessageAttributes<D>, idempotencyKey?: string) => Promise<SendMessageResponse>;
     markAsRead: (messageId: string) => Promise<void>;
     disconnect: () => void;
 }
-declare function createChatSession<D extends ChatDomain = DefaultDomain>(config: ChatConfig, channelId: string, profile: Participant<D>, callbacks: SessionCallbacks<D>): Promise<ChatSession<D>>;
+declare function createChatSession<D extends ChatDomain = DefaultDomain>(config: ChatConfig, channelId: string, profile: Participant<D>, callbacks: SessionCallbacks<D>, networkMonitor?: NetworkMonitor): Promise<ChatSession<D>>;
 
 /**
  * Creates a single-server manifest. Use this when all channels route to the same server.
@@ -97,6 +167,7 @@ interface SSEConnectionConfig {
     reconnectDelayMs?: number;
     lastEventId?: string;
     customEvents?: string[];
+    networkMonitor?: NetworkMonitor;
 }
 interface SSEConnectionCallbacks {
     onOpen?: () => void;
@@ -107,6 +178,7 @@ interface SSEConnectionCallbacks {
 }
 interface SSEConnection {
     close: () => void;
+    reconnectImmediate: () => void;
 }
 declare function createSSEConnection(config: SSEConnectionConfig, callbacks: SSEConnectionCallbacks): SSEConnection;
 
@@ -118,5 +190,21 @@ declare class ChannelClosedError extends Error {
     readonly channelId: string;
     constructor(channelId: string);
 }
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    readonly retryAfter?: number | undefined;
+    constructor(status: number, body: string, retryAfter?: number | undefined);
+}
+declare class RetryExhaustedError extends Error {
+    readonly operation: string;
+    readonly attempts: number;
+    readonly lastError: Error;
+    constructor(operation: string, attempts: number, lastError: Error);
+}
+declare class QueueFullError extends Error {
+    readonly maxSize: number;
+    constructor(maxSize: number);
+}
 
-export { ChannelClosedError, type ChatConfig, ChatDisconnectedError, type ChatSession, type ChatStatus, type SSEConnection, type SSEConnectionCallbacks, type SSEConnectionConfig, type SessionCallbacks, type UseChatOptions, type UseChatReturn, type UseUnreadOptions, type UseUnreadReturn, createChatSession, createManifest, createSSEConnection, resolveServerUrl, useChat, useUnread };
+export { ChannelClosedError, type ChatConfig, ChatDisconnectedError, type ChatSession, type ChatStatus, HttpError, type MessageSendStatus, type NetworkMonitor, QueueFullError, type QueueStorage, type QueuedMessage, type ResilienceConfig, type RetryConfig, RetryExhaustedError, type SSEConnection, type SSEConnectionCallbacks, type SSEConnectionConfig, type SessionCallbacks, type UseChatOptions, type UseChatReturn, type UseUnreadOptions, type UseUnreadReturn, calculateBackoff, createAsyncStorageAdapter, createChatSession, createManifest, createNetworkMonitor, createQueueStorage, createSSEConnection, isRetryableError, resolveRetryConfig, resolveServerUrl, useChat, useUnread, withRetry };