@parlr/react-native 0.1.0

package/src/hooks/useChat.ts

@@ -0,0 +1,534 @@
+// ---------------------------------------------------------------------------
+// Parlr React Native SDK - useChat Hook
+// ---------------------------------------------------------------------------
+//
+// Manages real-time chat state for a single conversation. Handles:
+// - Message fetching and pagination
+// - Optimistic message sending with crypto.randomUUID() idempotency keys
+// - WebSocket subscriptions (new messages, typing indicators)
+// - Typing notification debouncing
+// - Message retry for failed sends
+// ---------------------------------------------------------------------------
+
+import { useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { ParlrError } from '../core/errors';
+import { ParlrContext } from '../provider/ParlrContext';
+import type {
+  Conversation,
+  Message,
+  WsConversationUpdatedPayload,
+  WsNewMessagePayload,
+  WsTypingPayload,
+} from '../core/types';
+
+const MAX_SEND_RETRIES = 3;
+const RETRY_BASE_DELAY_MS = 1_000;
+
+export interface UseChatReturn {
+  /** Ordered message list (newest last). */
+  messages: Message[];
+  /** True while the initial message page is loading. */
+  isLoading: boolean;
+  /** True if a load/send error occurred. */
+  hasError: boolean;
+  /** The active conversation (may be null until first message). */
+  conversation: Conversation | null;
+  /** Whether an agent is currently typing. */
+  agentTyping: boolean;
+  /** Send a text message. Creates the conversation on first call if needed. */
+  sendMessage: (content: string) => Promise<void>;
+  /** Retry sending a failed message by its clientId. */
+  retryMessage: (clientId: string) => Promise<void>;
+  /** Notify the server that the contact started/stopped typing. */
+  notifyTyping: (isTyping: boolean) => void;
+  /** Load older messages (pagination). */
+  loadMore: () => Promise<void>;
+  /** Whether there are older messages to load. */
+  hasMore: boolean;
+  /** Close the current conversation. */
+  closeConversation: () => Promise<void>;
+  /** Reopen the current conversation. */
+  reopenConversation: () => Promise<void>;
+}
+
+/** Generate a UUID v4 using crypto.randomUUID (available in Hermes/RN). */
+function generateId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  // Fallback using crypto.getRandomValues (available in Hermes).
+  if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    // Set version (4) and variant (RFC4122).
+    bytes[6] = (bytes[6]! & 0x0f) | 0x40;
+    bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+  }
+  // Last-resort fallback for environments without crypto.
+  return `${Date.now().toString(36)}-${Array.from({ length: 12 }, () => ((Math.random() * 36) | 0).toString(36)).join('')}`;
+}
+
+/**
+ * Chat hook — manages messages and typing for one conversation.
+ *
+ * @param conversationId - Existing conversation ID, or undefined to create
+ *                         one on first `sendMessage`.
+ */
+export function useChat(conversationId?: string): UseChatReturn {
+  const { api, ws, config, session, refreshConversations } =
+    useContext(ParlrContext);
+
+  const [messages, setMessages] = useState<Message[]>([]);
+  const [conversation, setConversation] = useState<Conversation | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [hasError, setHasError] = useState(false);
+  const [agentTyping, setAgentTyping] = useState(false);
+  const [page, setPage] = useState(1);
+  const [hasMore, setHasMore] = useState(true);
+
+  // Resolved conversation ID: uses the prop when provided, otherwise
+  // auto-resolved from the API by picking the most recent open conversation.
+  const [resolvedConvId, setResolvedConvId] = useState<string | undefined>(conversationId);
+
+  // Mutable ref for the active conversation id (may be set lazily).
+  const activeConvId = useRef<string | undefined>(resolvedConvId);
+  activeConvId.current = resolvedConvId ?? activeConvId.current;
+
+  // Track retry attempts per clientId.
+  const retryCountRef = useRef<Map<string, number>>(new Map());
+
+  // Agent typing timeout — auto-clear after 5 s of silence.
+  const typingTimeout = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Contact typing debounce — avoid spamming the server.
+  const lastTypingNotify = useRef<number>(0);
+
+  // --- Keep resolved ID in sync with the prop (prop always wins) -------------
+
+  useEffect(() => {
+    if (conversationId) {
+      setResolvedConvId(conversationId);
+    }
+  }, [conversationId]);
+
+  // --- Auto-resolve: fetch the most recent open conversation from the API ---
+  // This runs only when no conversationId prop is provided, so returning users
+  // see their message history immediately without having to send a new message.
+
+  useEffect(() => {
+    console.log('[@parlr/react-native][useChat] auto-resolve check', {
+      conversationId,
+      resolvedConvId,
+      hasApi: !!api,
+      hasSession: !!session,
+    });
+
+    if (conversationId || resolvedConvId || !api || !session) return;
+
+    let cancelled = false;
+
+    async function resolve() {
+      try {
+        console.log('[@parlr/react-native][useChat] fetching conversations for auto-resolve...');
+        const res = await api!.listConversations();
+        console.log('[@parlr/react-native][useChat] listConversations result', {
+          count: res.data.length,
+          conversations: res.data.map((c: Conversation) => ({ id: c.id, status: c.status, lastMessageAt: c.lastMessageAt })),
+        });
+        if (cancelled) return;
+
+        const open = res.data
+          .filter((c: Conversation) => c.status !== 'closed')
+          .sort((a: Conversation, b: Conversation) => {
+            const aT = a.lastMessageAt ? new Date(a.lastMessageAt).getTime() : 0;
+            const bT = b.lastMessageAt ? new Date(b.lastMessageAt).getTime() : 0;
+            return bT - aT;
+          });
+
+        console.log('[@parlr/react-native][useChat] open conversations', {
+          count: open.length,
+          picked: open[0]?.id ?? 'none',
+        });
+
+        if (open.length > 0 && open[0]) {
+          setResolvedConvId(open[0].id);
+        }
+      } catch (err) {
+        console.warn('[@parlr/react-native][useChat] auto-resolve failed', err);
+      }
+    }
+
+    resolve();
+
+    return () => { cancelled = true; };
+  }, [conversationId, resolvedConvId, api, session]);
+
+  // --- Fetch initial messages ------------------------------------------------
+
+  useEffect(() => {
+    console.log('[@parlr/react-native][useChat] fetch effect', {
+      hasApi: !!api,
+      activeConvId: activeConvId.current,
+      hasSession: !!session,
+      resolvedConvId,
+    });
+    if (!api || !activeConvId.current || !session) return;
+
+    let cancelled = false;
+
+    async function fetchMessages() {
+      setIsLoading(true);
+      setHasError(false);
+
+      try {
+        const res = await api!.getMessages(activeConvId.current!, 1);
+        if (!cancelled) {
+          setMessages(res.data);
+          setHasMore(res.meta.hasMore);
+          setPage(1);
+        }
+      } catch (err) {
+        if (config.debug) {
+          console.warn('[@parlr/react-native] Failed to load messages:', err);
+        }
+        config.onError?.(err instanceof ParlrError ? err : new ParlrError(err instanceof Error ? err.message : String(err)));
+        if (!cancelled) setHasError(true);
+      } finally {
+        if (!cancelled) setIsLoading(false);
+      }
+    }
+
+    fetchMessages();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [api, session, config, resolvedConvId]);
+
+  // --- WebSocket subscriptions -----------------------------------------------
+
+  useEffect(() => {
+    if (!ws) return;
+
+    const offMessage = ws.on('new_message', (payload: WsNewMessagePayload) => {
+      // Only append if it belongs to our active conversation.
+      if (payload.conversationId !== activeConvId.current) return;
+
+      const msg: Message = {
+        id: payload.id,
+        conversationId: payload.conversationId,
+        senderType: payload.senderType,
+        senderName: payload.senderName,
+        senderAvatarUrl: payload.senderAvatarUrl,
+        content: payload.content,
+        createdAt: payload.createdAt,
+        clientId: payload.clientId,
+        status: 'sent',
+      };
+
+      setMessages((prev: Message[]) => {
+        // Deduplicate: replace optimistic message with server-confirmed one.
+        const withoutOptimistic = prev.filter(
+          (m: Message) => !(m.clientId && m.clientId === msg.clientId),
+        );
+        return [...withoutOptimistic, msg];
+      });
+
+      // Clear agent typing when a real message arrives.
+      if (msg.senderType === 'agent') {
+        setAgentTyping(false);
+      }
+    });
+
+    const offTypingStart = ws.on('typing_start', (payload: WsTypingPayload) => {
+      if (payload.conversationId !== activeConvId.current) return;
+      setAgentTyping(true);
+
+      // Auto-clear after 5 s of no further typing event.
+      if (typingTimeout.current) clearTimeout(typingTimeout.current);
+      typingTimeout.current = setTimeout(() => setAgentTyping(false), 5_000);
+    });
+
+    const offTypingStop = ws.on('typing_stop', (payload: WsTypingPayload) => {
+      if (payload.conversationId !== activeConvId.current) return;
+      setAgentTyping(false);
+      if (typingTimeout.current) clearTimeout(typingTimeout.current);
+    });
+
+    const offConvUpdated = ws.on('conversation_updated', (payload: WsConversationUpdatedPayload) => {
+      if (payload.conversationId !== activeConvId.current) return;
+      setConversation((prev) => {
+        if (!prev) return prev;
+        return {
+          ...prev,
+          ...(payload.status !== undefined ? { status: payload.status } : {}),
+          ...(payload.assignee !== undefined ? { assignee: payload.assignee } : {}),
+        };
+      });
+    });
+
+    return () => {
+      offMessage();
+      offTypingStart();
+      offTypingStop();
+      offConvUpdated();
+    };
+  }, [ws]);
+
+  // --- Polling fallback when WebSocket is not connected ----------------------
+
+  useEffect(() => {
+    if (!api || !session) return;
+
+    const POLL_INTERVAL = 5_000; // 5 seconds
+
+    const poll = async () => {
+      // Skip this tick if WebSocket is connected (real-time push handles it).
+      if (ws?.connected) return;
+
+      const convId = activeConvId.current;
+      if (!convId) return;
+
+      try {
+        const res = await api.getMessages(convId, 1);
+        setMessages(res.data);
+      } catch {
+        // Silently ignore polling errors.
+      }
+    };
+
+    const interval = setInterval(poll, POLL_INTERVAL);
+    return () => clearInterval(interval);
+  }, [api, session, ws]);
+
+  // --- Internal send logic ---------------------------------------------------
+
+  const doSend = useCallback(
+    async (convId: string, content: string, clientId: string): Promise<void> => {
+      /* istanbul ignore next -- defensive guard: callers already check api */
+      if (!api) return;
+
+      try {
+        ws?.send({
+          type: 'send_message',
+          payload: { conversationId: convId, content, clientId },
+        });
+
+        const confirmed = await api.sendMessage(convId, content, clientId);
+
+        setMessages((prev: Message[]) =>
+          prev.map((m: Message) =>
+            m.clientId === clientId ? { ...confirmed, status: 'sent' as const } : m,
+          ),
+        );
+
+        // Clean up retry tracking.
+        retryCountRef.current.delete(clientId);
+      } catch (err) {
+        console.error('[@parlr/react-native] Failed to send message:', err);
+        config.onError?.(err instanceof ParlrError ? err : new ParlrError(err instanceof Error ? err.message : String(err)));
+        setMessages((prev: Message[]) =>
+          prev.map((m: Message) =>
+            m.clientId === clientId ? { ...m, status: 'failed' as const } : m,
+          ),
+        );
+      }
+    },
+    [api, ws, config],
+  );
+
+  // --- Send message ----------------------------------------------------------
+
+  const sendMessage = useCallback(
+    async (content: string) => {
+      if (!api) return;
+
+      const trimmed = content.trim();
+      if (!trimmed) return;
+
+      // 1. Create conversation if needed.
+      let convId = activeConvId.current;
+
+      if (!convId) {
+        try {
+          const conv = await api.createConversation(trimmed);
+          convId = conv.id;
+          activeConvId.current = convId;
+          setResolvedConvId(convId);
+          setConversation(conv);
+          refreshConversations();
+
+          // The server created the conversation AND the first message;
+          // fetch messages so we have the server-assigned IDs.
+          const res = await api.getMessages(convId);
+          setMessages(res.data);
+          return;
+        } catch (err) {
+          console.error(
+            '[@parlr/react-native] Failed to create conversation:',
+            err,
+          );
+          config.onError?.(err instanceof ParlrError ? err : new ParlrError(err instanceof Error ? err.message : String(err)));
+          setHasError(true);
+          return;
+        }
+      }
+
+      // 2. Optimistic insert.
+      const clientId = generateId();
+      const optimistic: Message = {
+        id: clientId,
+        conversationId: convId,
+        senderType: 'contact',
+        content: trimmed,
+        createdAt: new Date().toISOString(),
+        clientId,
+        status: 'sending',
+      };
+
+      setMessages((prev: Message[]) => [...prev, optimistic]);
+
+      // 3. Send via REST (for reliability) and via WS (for speed).
+      await doSend(convId, trimmed, clientId);
+    },
+    [api, config, refreshConversations, doSend],
+  );
+
+  // --- Retry failed message --------------------------------------------------
+
+  const retryMessage = useCallback(
+    async (clientId: string) => {
+      const msg = messages.find(
+        (m: Message) => m.clientId === clientId && m.status === 'failed',
+      );
+      if (!msg) return;
+
+      const currentRetries = retryCountRef.current.get(clientId) ?? 0;
+      if (currentRetries >= MAX_SEND_RETRIES) {
+        console.warn(
+          `[@parlr/react-native] Max retries (${MAX_SEND_RETRIES}) reached for message ${clientId}`,
+        );
+        return;
+      }
+
+      retryCountRef.current.set(clientId, currentRetries + 1);
+
+      // Mark as sending again.
+      setMessages((prev: Message[]) =>
+        prev.map((m: Message) =>
+          m.clientId === clientId ? { ...m, status: 'sending' as const } : m,
+        ),
+      );
+
+      // Backoff before retry.
+      const backoff = RETRY_BASE_DELAY_MS * Math.pow(2, currentRetries);
+      await new Promise((resolve) => setTimeout(resolve, backoff));
+
+      await doSend(msg.conversationId, msg.content, clientId);
+    },
+    [messages, doSend],
+  );
+
+  // --- Typing notification ---------------------------------------------------
+
+  const notifyTyping = useCallback(
+    (isTyping: boolean) => {
+      const convId = activeConvId.current;
+      if (!convId) return;
+
+      // Debounce: only send typing_start at most once every 3 s.
+      if (isTyping) {
+        const now = Date.now();
+        if (now - lastTypingNotify.current < 3_000) return;
+        lastTypingNotify.current = now;
+      }
+
+      ws?.send({
+        type: isTyping ? 'typing_start' : 'typing_stop',
+        payload: { conversationId: convId },
+      });
+
+      // Also notify via REST for reliability.
+      api?.sendTypingIndicator(convId, isTyping).catch(() => {
+        // Best-effort — swallow errors on typing indicators.
+      });
+    },
+    [api, ws],
+  );
+
+  // --- Load more (pagination) ------------------------------------------------
+
+  const loadMore = useCallback(async () => {
+    const convId = activeConvId.current;
+    if (!api || !convId || !hasMore || isLoading) return;
+
+    const nextPage = page + 1;
+    try {
+      const res = await api.getMessages(convId, nextPage);
+      setMessages((prev: Message[]) => [...res.data, ...prev]);
+      setPage(nextPage);
+      setHasMore(res.meta.hasMore);
+    } catch (err) {
+      if (config.debug) {
+        console.warn('[@parlr/react-native] Failed to load more:', err);
+      }
+    }
+  }, [api, hasMore, isLoading, page, config.debug]);
+
+  // --- Close / Reopen --------------------------------------------------------
+
+  const closeConversation = useCallback(async () => {
+    const convId = activeConvId.current;
+    if (!api || !convId) return;
+
+    try {
+      const updated = await api.closeConversation(convId);
+      setConversation(updated);
+    } catch (err) {
+      if (config.debug) {
+        console.warn('[@parlr/react-native] Failed to close conversation:', err);
+      }
+      config.onError?.(err instanceof ParlrError ? err : new ParlrError(err instanceof Error ? err.message : String(err)));
+    }
+  }, [api, config]);
+
+  const reopenConversation = useCallback(async () => {
+    const convId = activeConvId.current;
+    if (!api || !convId) return;
+
+    try {
+      const updated = await api.reopenConversation(convId);
+      setConversation(updated);
+    } catch (err) {
+      if (config.debug) {
+        console.warn('[@parlr/react-native] Failed to reopen conversation:', err);
+      }
+      config.onError?.(err instanceof ParlrError ? err : new ParlrError(err instanceof Error ? err.message : String(err)));
+    }
+  }, [api, config]);
+
+  // --- Cleanup ---------------------------------------------------------------
+
+  useEffect(() => {
+    return () => {
+      if (typingTimeout.current) clearTimeout(typingTimeout.current);
+    };
+  }, []);
+
+  return {
+    messages,
+    isLoading,
+    hasError,
+    conversation,
+    agentTyping,
+    sendMessage,
+    retryMessage,
+    notifyTyping,
+    loadMore,
+    hasMore,
+    closeConversation,
+    reopenConversation,
+  };
+}

package/src/hooks/useParlr.ts

@@ -0,0 +1,43 @@
+// ---------------------------------------------------------------------------
+// Parlr React Native SDK - useParlr Hook
+// ---------------------------------------------------------------------------
+//
+// High-level hook for programmatic access to the SDK state and actions.
+// Must be used within a <ParlrProvider>.
+// ---------------------------------------------------------------------------
+
+import { useContext } from 'react';
+import { ParlrContext } from '../provider/ParlrContext';
+import type { ParlrContextValue } from '../core/types';
+
+/**
+ * Access the Parlr SDK from any component within a `<ParlrProvider>`.
+ *
+ * @example
+ * ```tsx
+ * const { isReady, identify, conversations, unreadCount } = useParlr();
+ * ```
+ */
+export function useParlr(): ParlrContextValue {
+  const ctx = useContext(ParlrContext);
+
+  if (!ctx.config.workspaceId) {
+    throw new Error(
+      '[@parlr/react-native] useParlr() must be used within a <ParlrProvider>. ' +
+        'Wrap your app root with <ParlrProvider workspaceId="ws_xxx">.',
+    );
+  }
+
+  // Return only the public-facing subset (omitting api/ws internals).
+  return {
+    config: ctx.config,
+    session: ctx.session,
+    isReady: ctx.isReady,
+    isConnected: ctx.isConnected,
+    conversations: ctx.conversations,
+    unreadCount: ctx.unreadCount,
+    identify: ctx.identify,
+    refreshConversations: ctx.refreshConversations,
+    theme: ctx.theme,
+  };
+}

package/src/index.ts

@@ -0,0 +1,98 @@
+// ---------------------------------------------------------------------------
+// @parlr/react-native - Official Parlr Live Chat SDK for React Native
+// ---------------------------------------------------------------------------
+//
+// Public API surface. Everything exported here is part of the stable contract.
+//
+// Usage:
+//
+//   import { ParlrProvider, ParlrChat, useParlr, useChat } from '@parlr/react-native';
+//
+//   // 1. Wrap your app
+//   <ParlrProvider workspaceId="ws_xxx">
+//     <App />
+//   </ParlrProvider>
+//
+//   // 2. Drop the chat screen anywhere
+//   <ParlrChat user={{ email: 'alice@acme.com', name: 'Alice' }} onBack={goBack} />
+//
+//   // 3. Or use hooks for programmatic access
+//   const { isReady, identify, unreadCount } = useParlr();
+//   const { messages, sendMessage, agentTyping } = useChat(conversationId);
+//
+// ---------------------------------------------------------------------------
+
+// Components
+export { ParlrProvider } from './provider/ParlrProvider';
+export { ParlrChat } from './components/ParlrChat';
+export { ParlrConversationList } from './components/ParlrConversationList';
+export { ChatBubble } from './components/ChatBubble';
+export { TypingIndicator } from './components/TypingIndicator';
+export { EmptyState } from './components/EmptyState';
+export { PreChatForm } from './components/PreChatForm';
+export { SatisfactionSurvey } from './components/SatisfactionSurvey';
+export { AttachmentPicker } from './components/AttachmentPicker';
+export { AttachmentPreview } from './components/AttachmentPreview';
+export { RichMessage } from './components/RichMessage';
+
+// Hooks
+export { useParlr } from './hooks/useParlr';
+export { useChat } from './hooks/useChat';
+
+// Errors
+export {
+  ParlrError,
+  ParlrNetworkError,
+  ParlrAuthError,
+  ParlrValidationError,
+  ParlrConnectionError,
+} from './core/errors';
+
+// Types
+export type {
+  Attachment,
+  MessageContentType,
+  RatingRequest,
+  ParlrConfig,
+  ParlrUser,
+  Conversation,
+  Message,
+  Session,
+  ResolvedConfig,
+  ParlrContextValue,
+  WsEventMap,
+  WsNewMessagePayload,
+  WsTypingPayload,
+  WsConversationUpdatedPayload,
+} from './core/types';
+
+// Offline queue
+export {
+  queueMessage,
+  getQueuedMessages,
+  removeFromQueue,
+  flushQueue,
+} from './core/offlineQueue';
+export type { QueuedMessage } from './core/offlineQueue';
+
+// Push notifications
+export { registerPushToken, unregisterPushToken } from './core/pushNotifications';
+
+// Theme
+export {
+  defaultLightTheme,
+  defaultDarkTheme,
+  mergeTheme,
+} from './core/theme';
+export type { ParlrTheme } from './core/theme';
+
+// Props types (for consumers that need to type-check wrappers)
+export type { ParlrProviderProps } from './provider/ParlrProvider';
+export type { ParlrChatProps } from './components/ParlrChat';
+export type { ParlrConversationListProps } from './components/ParlrConversationList';
+export type { PreChatFormProps } from './components/PreChatForm';
+export type { SatisfactionSurveyProps } from './components/SatisfactionSurvey';
+export type { AttachmentPickerProps, PickedFile } from './components/AttachmentPicker';
+export type { AttachmentPreviewProps } from './components/AttachmentPreview';
+export type { RichMessageProps, RichContent, RichCard, RichAction } from './components/RichMessage';
+export type { UseChatReturn } from './hooks/useChat';