@parlr/react-native 0.1.0

package/src/provider/ParlrContext.ts

@@ -0,0 +1,40 @@
+// ---------------------------------------------------------------------------
+// Parlr React Native SDK - React Context
+// ---------------------------------------------------------------------------
+
+import { createContext } from 'react';
+import type { ParlrApiClient } from '../core/api';
+import { defaultLightTheme } from '../core/theme';
+import type { ParlrContextValue, ResolvedConfig } from '../core/types';
+import type { ParlrWebSocket } from '../core/websocket';
+
+/**
+ * Public context consumed by hooks (`useParlr`, `useChat`).
+ * Includes both user-facing state and internal plumbing (api, ws).
+ */
+export interface ParlrContextInternal extends ParlrContextValue {
+  api: ParlrApiClient | null;
+  ws: ParlrWebSocket | null;
+}
+
+const NOOP = async () => {};
+
+export const ParlrContext = createContext<ParlrContextInternal>({
+  config: {
+    workspaceId: '',
+    apiBaseUrl: '',
+    wsUrl: '',
+    locale: 'fr',
+    debug: false,
+  } satisfies ResolvedConfig,
+  session: null,
+  isReady: false,
+  isConnected: false,
+  conversations: [],
+  unreadCount: 0,
+  identify: NOOP,
+  refreshConversations: NOOP,
+  theme: defaultLightTheme,
+  api: null,
+  ws: null,
+});

package/src/provider/ParlrProvider.tsx

@@ -0,0 +1,338 @@
+// ---------------------------------------------------------------------------
+// Parlr React Native SDK - Provider
+// ---------------------------------------------------------------------------
+//
+// Initializes the session, REST client and WebSocket on mount, then provides
+// them to the rest of the tree through React context.
+// ---------------------------------------------------------------------------
+
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type PropsWithChildren,
+} from 'react';
+import { useColorScheme } from 'react-native';
+import { createApiClient, type ParlrApiClient } from '../core/api';
+import { resolveConfig } from '../core/config';
+import { ParlrError } from '../core/errors';
+import {
+  clearSession,
+  isSessionValid,
+  loadSession,
+  saveSession,
+} from '../core/session';
+import {
+  defaultDarkTheme,
+  defaultLightTheme,
+  mergeTheme,
+} from '../core/theme';
+import type {
+  Conversation,
+  ParlrConfig,
+  ParlrUser,
+  ResolvedConfig,
+  Session,
+} from '../core/types';
+import { createWebSocket, type ParlrWebSocket } from '../core/websocket';
+import { ParlrContext, type ParlrContextInternal } from './ParlrContext';
+
+// ---------------------------------------------------------------------------
+// Props
+// ---------------------------------------------------------------------------
+
+export type ParlrProviderProps = PropsWithChildren<ParlrConfig>;
+
+// ---------------------------------------------------------------------------
+// Debounce helper
+// ---------------------------------------------------------------------------
+
+function useDebouncedCallback<T extends (...args: never[]) => void>(
+  fn: T,
+  delayMs: number,
+): T {
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const fnRef = useRef(fn);
+  fnRef.current = fn;
+
+  return useCallback(
+    ((...args: Parameters<T>) => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => fnRef.current(...args), delayMs);
+    }) as T,
+    [delayMs],
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export function ParlrProvider({
+  children,
+  ...configProps
+}: ParlrProviderProps) {
+  // --- Resolved config (stable across renders unless props change) ----------
+  const config: ResolvedConfig = useMemo(
+    () => resolveConfig(configProps),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+      configProps.workspaceId,
+      configProps.apiBaseUrl,
+      configProps.wsUrl,
+      configProps.locale,
+      configProps.debug,
+      configProps.onError,
+    ],
+  );
+
+  // --- Resolve theme based on system color scheme + user overrides ----------
+  const colorScheme = useColorScheme();
+  const theme = useMemo(() => {
+    const base = colorScheme === 'dark' ? defaultDarkTheme : defaultLightTheme;
+    return configProps.theme ? mergeTheme(base, configProps.theme) : base;
+  }, [colorScheme, configProps.theme]);
+
+  // --- State -----------------------------------------------------------------
+  const [session, setSession] = useState<Session | null>(null);
+  const [isReady, setIsReady] = useState(false);
+  const [isConnected, setIsConnected] = useState(false);
+  const [conversations, setConversations] = useState<Conversation[]>([]);
+
+  // --- Refs (singletons across the provider lifecycle) -----------------------
+  const sessionRef = useRef<Session | null>(null);
+  const apiRef = useRef<ParlrApiClient | null>(null);
+  const wsRef = useRef<ParlrWebSocket | null>(null);
+
+  // Keep ref in sync with state so the token accessor always returns latest.
+  sessionRef.current = session;
+
+  // --- Create API client (once per config) -----------------------------------
+  useEffect(() => {
+    const api = createApiClient(config, () => sessionRef.current?.token ?? null);
+    apiRef.current = api;
+  }, [config]);
+
+  // --- Fetch conversations (debounced) ---------------------------------------
+  const refreshConversationsImpl = useCallback(async () => {
+    const api = apiRef.current;
+    /* istanbul ignore next -- defensive: apiRef always set by preceding effect */
+    if (!api || !sessionRef.current) return;
+
+    try {
+      const res = await api.listConversations();
+      setConversations(res.data);
+    } catch (err) {
+      if (config.debug) {
+        console.warn(
+          '[@parlr/react-native] Failed to refresh conversations:',
+          err,
+        );
+      }
+      config.onError?.(err instanceof ParlrError ? err : new ParlrError(err instanceof Error ? err.message : String(err)));
+    }
+  }, [config]);
+
+  const refreshConversations = useDebouncedCallback(
+    refreshConversationsImpl as (...args: never[]) => void,
+    500,
+  ) as unknown as () => Promise<void>;
+
+  // --- Create WS client (once per config) ------------------------------------
+  useEffect(() => {
+    const ws = createWebSocket(config);
+    wsRef.current = ws;
+
+    const offConnected = ws.on('auth_ok', () => setIsConnected(true));
+    const offAuthError = ws.on('auth_error', () => setIsConnected(false));
+    const offDisconnected = ws.on('disconnected', () => setIsConnected(false));
+
+    // When a new message arrives for any conversation, refresh list.
+    const offMessage = ws.on('new_message', () => {
+      refreshConversations();
+    });
+
+    const offConvUpdated = ws.on('conversation_updated', () => {
+      refreshConversations();
+    });
+
+    return () => {
+      offConnected();
+      offAuthError();
+      offDisconnected();
+      offMessage();
+      offConvUpdated();
+      ws.disconnect();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [config]);
+
+  // --- Bootstrap session on mount --------------------------------------------
+  useEffect(() => {
+    let cancelled = false;
+
+    async function bootstrap() {
+      const api = apiRef.current;
+      if (!api) return;
+
+      try {
+        // 1. Try to restore a persisted session.
+        const existing = await loadSession(config.workspaceId);
+
+        if (existing && isSessionValid(existing)) {
+          if (!cancelled) {
+            setSession(existing);
+            sessionRef.current = existing;
+          }
+        } else {
+          // 2. Create a new session.
+          if (existing) {
+            await clearSession(config.workspaceId);
+          }
+
+          const newSession = await api.createSession();
+          await saveSession(config.workspaceId, newSession);
+
+          if (!cancelled) {
+            setSession(newSession);
+            sessionRef.current = newSession;
+          }
+        }
+
+        if (!cancelled) {
+          setIsReady(true);
+        }
+      } catch (err) {
+        console.error(
+          '[@parlr/react-native] Failed to bootstrap session:',
+          err,
+        );
+        config.onError?.(err instanceof ParlrError ? err : new ParlrError(err instanceof Error ? err.message : String(err)));
+        if (!cancelled) {
+          setIsReady(true); // still "ready" so UI can render an error state
+        }
+      }
+    }
+
+    bootstrap();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [config]);
+
+  // --- Connect WebSocket once session is available ---------------------------
+  useEffect(() => {
+    if (session?.token && wsRef.current) {
+      wsRef.current.connect(session.token);
+    }
+  }, [session]);
+
+  // --- Auto-refresh session when expired -------------------------------------
+  useEffect(() => {
+    if (!session || !apiRef.current) return;
+
+    // Check session validity periodically.
+    const interval = setInterval(async () => {
+      if (session && !isSessionValid(session)) {
+        if (config.debug) {
+          console.log('[@parlr/react-native] Session expired, refreshing...');
+        }
+        try {
+          const api = apiRef.current;
+          /* istanbul ignore next -- defensive: apiRef always set by preceding effect */
+          if (!api) return;
+
+          const newSession = await api.createSession();
+          await saveSession(config.workspaceId, newSession);
+          setSession(newSession);
+          sessionRef.current = newSession;
+        } catch (err) {
+          console.error(
+            '[@parlr/react-native] Failed to refresh session:',
+            err,
+          );
+          config.onError?.(err instanceof ParlrError ? err : new ParlrError(err instanceof Error ? err.message : String(err)));
+        }
+      }
+    }, 60_000); // Check every minute.
+
+    return () => clearInterval(interval);
+  }, [session, config]);
+
+  // --- Fetch conversations once session is ready -----------------------------
+  useEffect(() => {
+    if (isReady && session) {
+      refreshConversationsImpl();
+    }
+  }, [isReady, session, refreshConversationsImpl]);
+
+  // --- Poll conversations when WebSocket is not connected --------------------
+  // Without WS, the conversation list (unread counts, new conversations from
+  // agent replies) would never update. Poll every 10 s as a fallback.
+  useEffect(() => {
+    if (!isReady || !session) return;
+    // Skip polling if WS is live — the new_message listener already refreshes.
+    if (isConnected) return;
+
+    const interval = setInterval(() => {
+      refreshConversationsImpl();
+    }, 10_000);
+
+    return () => clearInterval(interval);
+  }, [isReady, session, isConnected, refreshConversationsImpl]);
+
+  // --- Identify callback -----------------------------------------------------
+  const identify = useCallback(
+    async (user: ParlrUser) => {
+      const api = apiRef.current;
+      if (!api) {
+        throw new Error(
+          '[@parlr/react-native] Cannot identify before SDK is initialised.',
+        );
+      }
+      await api.identify(user);
+    },
+    [],
+  );
+
+  // --- Unread count (derived) ------------------------------------------------
+  const unreadCount = useMemo(
+    () => conversations.reduce((sum, c) => sum + c.unreadCount, 0),
+    [conversations],
+  );
+
+  // --- Context value ---------------------------------------------------------
+  const value: ParlrContextInternal = useMemo(
+    () => ({
+      config,
+      session,
+      isReady,
+      isConnected,
+      conversations,
+      unreadCount,
+      identify,
+      refreshConversations: refreshConversationsImpl,
+      theme,
+      api: apiRef.current,
+      ws: wsRef.current,
+    }),
+    [
+      config,
+      session,
+      isReady,
+      isConnected,
+      conversations,
+      unreadCount,
+      identify,
+      refreshConversationsImpl,
+      theme,
+    ],
+  );
+
+  return (
+    <ParlrContext.Provider value={value}>{children}</ParlrContext.Provider>
+  );
+}