@solveo-ai/react-native 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @solveo-ai/react-native
+
+React Native SDK for the Solveo AI platform. Build AI-powered chat experiences in your mobile apps.
+
+## Installation
+
+```bash
+npm install @solveo-ai/react-native @solveo-ai/sdk-core
+# or
+yarn add @solveo-ai/react-native @solveo-ai/sdk-core
+```
+
+## Quick Start
+
+```tsx
+import { SolveoProvider, useChat } from '@solveo-ai/react-native';
+
+// Wrap your app
+function App() {
+  return (
+    <SolveoProvider
+      config={{
+        apiUrl: 'https://api.solveoai.io',
+        widgetId: 'your-widget-id',
+      }}
+    >
+      <ChatScreen />
+    </SolveoProvider>
+  );
+}
+
+// Use in any component
+function ChatScreen() {
+  const { conversation, messages, sendMessage, createConversation } = useChat();
+
+  useEffect(() => {
+    createConversation();
+  }, []);
+
+  return (
+    <View>
+      {messages.map((msg) => (
+        <Text key={msg.id}>{msg.content}</Text>
+      ))}
+    </View>
+  );
+}
+```
+
+## Documentation
+
+See [full documentation](https://docs.solveoai.io/sdk/react-native).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@solveo-ai/react-native",
+  "version": "0.1.0",
+  "description": "React Native SDK for Solveo AI platform",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "solveo",
+    "ai",
+    "chat",
+    "react-native",
+    "mobile",
+    "sdk"
+  ],
+  "author": "Solveo AI",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0",
+    "@solveo-ai/sdk-core": "^0.1.0"
+  },
+  "dependencies": {
+    "@react-native-async-storage/async-storage": "^2.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-native": "^0.73.0",
+    "react": "^19.2.3",
+    "react-native": "^0.76.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "optionalDependencies": {
+    "expo-image-picker": "^16.0.0",
+    "expo-av": "^15.0.0",
+    "expo-file-system": "^18.0.0",
+    "react-native-image-picker": "^7.0.0"
+  }
+}

package/src/SolveoProvider.tsx

@@ -0,0 +1,200 @@
+import React, { createContext, useContext, useMemo, ReactNode, useEffect, useState } from 'react';
+import {
+  SolveoSDK,
+  type SolveoClientConfig,
+  createCustomerSocket,
+  createAgentSocket,
+  createStreamingSocket,
+  CustomerSocketManager,
+  AgentSocketManager,
+  StreamingSocket,
+} from '@solveo-ai/sdk-core';
+import type { Socket } from 'socket.io-client';
+
+// ============================================================================
+// Context Types
+// ============================================================================
+
+export interface SolveoContextValue {
+  sdk: SolveoSDK;
+  config: SolveoProviderConfig;
+  // Customer socket (for widget mode)
+  customerSocket: Socket | null;
+  customerSocketManager: CustomerSocketManager | null;
+  // Agent socket (for management mode)
+  agentSocket: Socket | null;
+  agentSocketManager: AgentSocketManager | null;
+  // Streaming socket (for AI responses)
+  streamingSocket: StreamingSocket | null;
+  // Connection helpers
+  connectCustomerSocket: (conversationId: string) => void;
+  disconnectCustomerSocket: () => void;
+  connectAgentSocket: (token: string) => void;
+  disconnectAgentSocket: () => void;
+  connectStreamingSocket: (conversationId: string) => void;
+  disconnectStreamingSocket: () => void;
+}
+
+const SolveoContext = createContext<SolveoContextValue | null>(null);
+
+// ============================================================================
+// Provider Props
+// ============================================================================
+
+export interface SolveoProviderConfig extends Omit<SolveoClientConfig, 'platform'> {
+  // User identity (optional)
+  user?: {
+    email?: string;
+    name?: string;
+    id?: string;
+  };
+  // Auto-connect options
+  autoConnectCustomer?: boolean;
+  autoConnectAgent?: boolean;
+  conversationId?: string; // For auto-connecting customer socket
+  // Error handler
+  onError?: (error: Error) => void;
+}
+
+export interface SolveoProviderProps {
+  children: ReactNode;
+  config: SolveoProviderConfig;
+}
+
+// ============================================================================
+// Provider Component
+// ============================================================================
+
+export function SolveoProvider({ children, config }: SolveoProviderProps) {
+  const sdk = useMemo(
+    () =>
+      new SolveoSDK({
+        ...config,
+        platform: 'react-native',
+      }),
+    [config.apiUrl, config.apiKey, config.token, config.widgetId]
+  );
+
+  // Socket states
+  const [customerSocket, setCustomerSocket] = useState<Socket | null>(null);
+  const [customerSocketManager, setCustomerSocketManager] = useState<CustomerSocketManager | null>(null);
+  const [agentSocket, setAgentSocket] = useState<Socket | null>(null);
+  const [agentSocketManager, setAgentSocketManager] = useState<AgentSocketManager | null>(null);
+  const [streamingSocket, setStreamingSocket] = useState<StreamingSocket | null>(null);
+
+  // Connect customer socket
+  const connectCustomerSocket = (conversationId: string) => {
+    if (customerSocket) {
+      customerSocket.disconnect();
+    }
+
+    const socket = createCustomerSocket(config.apiUrl, conversationId);
+    const manager = new CustomerSocketManager(socket);
+
+    setCustomerSocket(socket);
+    setCustomerSocketManager(manager);
+
+    socket.connect();
+  };
+
+  // Disconnect customer socket
+  const disconnectCustomerSocket = () => {
+    if (customerSocket) {
+      customerSocket.disconnect();
+      setCustomerSocket(null);
+      setCustomerSocketManager(null);
+    }
+  };
+
+  // Connect agent socket
+  const connectAgentSocket = (token: string) => {
+    if (agentSocket) {
+      agentSocket.disconnect();
+    }
+
+    const socket = createAgentSocket(config.apiUrl, token);
+    const manager = new AgentSocketManager(socket);
+
+    setAgentSocket(socket);
+    setAgentSocketManager(manager);
+
+    socket.connect();
+  };
+
+  // Disconnect agent socket
+  const disconnectAgentSocket = () => {
+    if (agentSocket) {
+      agentSocket.disconnect();
+      setAgentSocket(null);
+      setAgentSocketManager(null);
+    }
+  };
+
+  // Connect streaming socket
+  const connectStreamingSocket = (conversationId: string) => {
+    if (streamingSocket) {
+      streamingSocket.disconnect();
+    }
+
+    const socket = createStreamingSocket(config.apiUrl, conversationId);
+    setStreamingSocket(socket);
+
+    socket.connect();
+  };
+
+  // Disconnect streaming socket
+  const disconnectStreamingSocket = () => {
+    if (streamingSocket) {
+      streamingSocket.disconnect();
+      setStreamingSocket(null);
+    }
+  };
+
+  // Auto-connect on mount
+  useEffect(() => {
+    if (config.autoConnectCustomer && config.conversationId) {
+      connectCustomerSocket(config.conversationId);
+    }
+
+    if (config.autoConnectAgent && config.token) {
+      connectAgentSocket(config.token);
+    }
+
+    // Cleanup on unmount
+    return () => {
+      disconnectCustomerSocket();
+      disconnectAgentSocket();
+      disconnectStreamingSocket();
+    };
+  }, [config.autoConnectCustomer, config.autoConnectAgent, config.conversationId, config.token]);
+
+  const value: SolveoContextValue = {
+    sdk,
+    config,
+    customerSocket,
+    customerSocketManager,
+    agentSocket,
+    agentSocketManager,
+    streamingSocket,
+    connectCustomerSocket,
+    disconnectCustomerSocket,
+    connectAgentSocket,
+    disconnectAgentSocket,
+    connectStreamingSocket,
+    disconnectStreamingSocket,
+  };
+
+  return <SolveoContext.Provider value={value}>{children}</SolveoContext.Provider>;
+}
+
+// ============================================================================
+// Hook to use Solveo context
+// ============================================================================
+
+export function useSolveo(): SolveoContextValue {
+  const context = useContext(SolveoContext);
+  if (!context) {
+    throw new Error('useSolveo must be used within a SolveoProvider');
+  }
+  return context;
+}

package/src/hooks/index.ts

@@ -0,0 +1,11 @@
+export { useChat } from './useChat';
+export { useRealtime } from './useRealtime';
+export { useEscalation } from './useEscalation';
+export { useWidgetConfig } from './useWidgetConfig';
+
+// Simplified exports for remaining hooks (implementations can be expanded as needed)
+export { usePushNotifications } from './usePushNotifications';
+export { useAttachments } from './useAttachments';
+export { useAgents } from './useAgents';
+export { useConversations } from './useConversations';
+export { useAnalytics } from './useAnalytics';

package/src/hooks/useAgents.ts

@@ -0,0 +1,57 @@
+import { useState, useEffect, useCallback } from 'react';
+import { useSolveo } from '../SolveoProvider';
+import type { Agent, AgentCreateRequest, AgentUpdateRequest } from '@solveo-ai/sdk-core';
+
+export function useAgents(accountId?: string) {
+  const { sdk } = useSolveo();
+  const [agents, setAgents] = useState<Agent[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const loadAgents = useCallback(async () => {
+    if (!accountId) return;
+    setIsLoading(true);
+    try {
+      const data = await sdk.agents.list(accountId);
+      setAgents(data);
+    } catch (err: any) {
+      setError(err);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [sdk, accountId]);
+
+  useEffect(() => {
+    if (accountId) {
+      loadAgents();
+    }
+  }, [accountId]);
+
+  const createAgent = useCallback(async (data: AgentCreateRequest) => {
+    if (!accountId) throw new Error('No account ID');
+    const agent = await sdk.agents.create(accountId, data);
+    setAgents((prev) => [...prev, agent]);
+    return agent;
+  }, [sdk, accountId]);
+
+  const updateAgent = useCallback(async (id: string, data: AgentUpdateRequest) => {
+    const agent = await sdk.agents.update(id, data);
+    setAgents((prev) => prev.map((a) => (a.id === id ? agent : a)));
+    return agent;
+  }, [sdk]);
+
+  const deleteAgent = useCallback(async (id: string) => {
+    await sdk.agents.delete(id);
+    setAgents((prev) => prev.filter((a) => a.id !== id));
+  }, [sdk]);
+
+  return {
+    agents,
+    isLoading,
+    error,
+    createAgent,
+    updateAgent,
+    deleteAgent,
+    reload: loadAgents,
+  };
+}

package/src/hooks/useAnalytics.ts

@@ -0,0 +1,55 @@
+import { useState, useEffect, useCallback } from 'react';
+import { useSolveo } from '../SolveoProvider';
+import type {
+  ConversationMetrics,
+  SentimentDistribution,
+  FeedbackStats,
+  TokenUsageMetrics,
+} from '@solveo-ai/sdk-core';
+
+export function useAnalytics(accountId?: string, days = 30) {
+  const { sdk } = useSolveo();
+  const [metrics, setMetrics] = useState<ConversationMetrics | null>(null);
+  const [sentiment, setSentiment] = useState<SentimentDistribution | null>(null);
+  const [feedback, setFeedback] = useState<FeedbackStats | null>(null);
+  const [tokenUsage, setTokenUsage] = useState<TokenUsageMetrics | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const loadAnalytics = useCallback(async () => {
+    if (!accountId) return;
+    setIsLoading(true);
+    try {
+      const [m, s, f, t] = await Promise.all([
+        sdk.analytics.getMetrics(accountId, days),
+        sdk.analytics.getSentiment(accountId, days),
+        sdk.analytics.getFeedback(accountId, days),
+        sdk.analytics.getTokenUsage(accountId, days),
+      ]);
+      setMetrics(m);
+      setSentiment(s);
+      setFeedback(f);
+      setTokenUsage(t);
+    } catch (err: any) {
+      setError(err);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [sdk, accountId, days]);
+
+  useEffect(() => {
+    if (accountId) {
+      loadAnalytics();
+    }
+  }, [accountId, days]);
+
+  return {
+    metrics,
+    sentiment,
+    feedback,
+    tokenUsage,
+    isLoading,
+    error,
+    reload: loadAnalytics,
+  };
+}

package/src/hooks/useAttachments.ts

@@ -0,0 +1,43 @@
+import { useState, useCallback } from 'react';
+import { useSolveo } from '../SolveoProvider';
+import type { MessageAttachment } from '@solveo-ai/sdk-core';
+
+export function useAttachments(conversationId?: string) {
+  const { sdk } = useSolveo();
+  const [uploading, setUploading] = useState(false);
+  const [uploadProgress, setUploadProgress] = useState(0);
+
+  const uploadAttachment = useCallback(async (
+    file: { uri: string; type?: string; name?: string },
+    attachmentType: 'IMAGE' | 'AUDIO' | 'VIDEO' | 'DOCUMENT' | 'VOICE_NOTE'
+  ): Promise<MessageAttachment> => {
+    if (!conversationId) {
+      throw new Error('No conversation ID provided');
+    }
+
+    setUploading(true);
+    setUploadProgress(0);
+
+    try {
+      // Convert file URI to blob (platform-specific)
+      const response = await fetch(file.uri);
+      const blob = await response.blob();
+
+      const attachment = await sdk.widgetAttachments.upload(conversationId, blob, attachmentType);
+      setUploadProgress(100);
+      return attachment;
+    } catch (error) {
+      console.error('Failed to upload attachment:', error);
+      throw error;
+    } finally {
+      setUploading(false);
+      setUploadProgress(0);
+    }
+  }, [sdk, conversationId]);
+
+  return {
+    uploading,
+    uploadProgress,
+    uploadAttachment,
+  };
+}

package/src/hooks/useChat.ts

@@ -0,0 +1,149 @@
+import { useState, useEffect, useCallback } from 'react';
+import { useSolveo } from '../SolveoProvider';
+import { storage } from '../utils/storage';
+import type { Message, Conversation } from '@solveo-ai/sdk-core';
+
+export interface UseChatOptions {
+  widgetId?: string;
+  agentId?: string;
+  persistConversation?: boolean;
+}
+
+export function useChat(options: UseChatOptions = {}) {
+  const { sdk, config, streamingSocket, connectStreamingSocket, disconnectStreamingSocket } = useSolveo();
+  const [conversation, setConversation] = useState<Conversation | null>(null);
+  const [messages, setMessages] = useState<Message[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [streamingContent, setStreamingContent] = useState('');
+  const [error, setError] = useState<Error | null>(null);
+
+  // Load persisted conversation
+  useEffect(() => {
+    if (options.persistConversation) {
+      loadPersistedConversation();
+    }
+  }, [options.persistConversation]);
+
+  // Setup streaming socket listeners
+  useEffect(() => {
+    if (!streamingSocket || !conversation) return;
+
+    streamingSocket.on('message', (msg) => {
+      if (msg.type === 'agent_typing') {
+        setIsStreaming(true);
+        setStreamingContent('');
+      } else if (msg.type === 'agent_message_chunk') {
+        setStreamingContent((prev) => prev + (msg.content || ''));
+      } else if (msg.type === 'agent_message_complete') {
+        setIsStreaming(false);
+        if (msg.message_id) {
+          loadMessages(conversation.id);
+        }
+      }
+    });
+
+    streamingSocket.on('error', (err) => {
+      setError(new Error(err.message || 'Streaming error'));
+      setIsStreaming(false);
+    });
+
+    return () => {
+      streamingSocket.off('message');
+      streamingSocket.off('error');
+    };
+  }, [streamingSocket, conversation]);
+
+  const loadPersistedConversation = async () => {
+    try {
+      const convId = await storage.getConversationId();
+      if (convId) {
+        const conv = await sdk.widgetConversations.get(convId);
+        setConversation(conv);
+        await loadMessages(convId);
+      }
+    } catch (err: any) {
+      console.error('Failed to load persisted conversation:', err);
+    }
+  };
+
+  const createConversation = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const identity = await storage.getUserIdentity();
+      const conv = await sdk.widgetConversations.create({
+        widget_id: options.widgetId || config.widgetId,
+        agent_id: options.agentId,
+        customer_email: identity?.email || config.user?.email,
+        customer_name: identity?.name || config.user?.name,
+      });
+      setConversation(conv);
+      if (options.persistConversation) {
+        await storage.setConversationId(conv.id);
+      }
+      connectStreamingSocket(conv.id);
+      return conv;
+    } catch (err: any) {
+      setError(err);
+      throw err;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [sdk, options, config]);
+
+  const loadMessages = useCallback(async (conversationId: string) => {
+    try {
+      const msgs = await sdk.widgetMessages.list(conversationId);
+      setMessages(msgs);
+      if (options.persistConversation) {
+        await storage.setMessages(conversationId, msgs);
+      }
+    } catch (err: any) {
+      setError(err);
+    }
+  }, [sdk, options]);
+
+  const sendMessage = useCallback(async (content: string) => {
+    if (!conversation) {
+      throw new Error('No active conversation');
+    }
+    setIsLoading(true);
+    setError(null);
+    try {
+      if (streamingSocket?.isConnected()) {
+        streamingSocket.sendMessage(content);
+      } else {
+        const response = await sdk.widgetMessages.send(conversation.id, { content });
+        setMessages((prev) => [...prev, response.message, response.ai_response!].filter(Boolean));
+      }
+    } catch (err: any) {
+      setError(err);
+      throw err;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [conversation, streamingSocket, sdk]);
+
+  const submitFeedback = useCallback(async (messageId: string, rating: 'THUMBS_UP' | 'THUMBS_DOWN') => {
+    if (!conversation) return;
+    try {
+      await sdk.widgetMessages.submitFeedback(conversation.id, messageId, rating);
+    } catch (err: any) {
+      setError(err);
+    }
+  }, [conversation, sdk]);
+
+  return {
+    conversation,
+    messages,
+    isLoading,
+    isStreaming,
+    streamingContent,
+    error,
+    createConversation,
+    sendMessage,
+    loadMessages,
+    submitFeedback,
+  };
+}

package/src/hooks/useConversations.ts

@@ -0,0 +1,42 @@
+import { useState, useEffect, useCallback } from 'react';
+import { useSolveo } from '../SolveoProvider';
+import type { Conversation } from '@solveo-ai/sdk-core';
+
+export function useConversations(accountId?: string) {
+  const { sdk } = useSolveo();
+  const [conversations, setConversations] = useState<Conversation[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const loadConversations = useCallback(async () => {
+    if (!accountId) return;
+    setIsLoading(true);
+    try {
+      const data = await sdk.conversations.list(accountId);
+      setConversations(data);
+    } catch (err: any) {
+      setError(err);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [sdk, accountId]);
+
+  useEffect(() => {
+    if (accountId) {
+      loadConversations();
+    }
+  }, [accountId]);
+
+  const resolveConversation = useCallback(async (id: string) => {
+    await sdk.conversations.resolve(id);
+    setConversations((prev) => prev.map((c) => (c.id === id ? { ...c, status: 'RESOLVED' as const } : c)));
+  }, [sdk]);
+
+  return {
+    conversations,
+    isLoading,
+    error,
+    resolveConversation,
+    reload: loadConversations,
+  };
+}

package/src/hooks/useEscalation.ts

@@ -0,0 +1,70 @@
+import { useState, useEffect, useCallback } from 'react';
+import { useSolveo } from '../SolveoProvider';
+import type { HumanAgent } from '@solveo-ai/sdk-core';
+
+export function useEscalation() {
+  const { customerSocketManager, connectCustomerSocket, disconnectCustomerSocket } = useSolveo();
+  const [escalationId, setEscalationId] = useState<string | null>(null);
+  const [assignedAgent, setAssignedAgent] = useState<HumanAgent | null>(null);
+  const [status, setStatus] = useState<'idle' | 'requesting' | 'queued' | 'active' | 'resolved'>('idle');
+
+  useEffect(() => {
+    if (!customerSocketManager) return;
+
+    customerSocketManager.onAgentConnected((data) => {
+      setEscalationId(data.escalation_id);
+      setAssignedAgent({
+        name: data.agent_name,
+        avatar_url: data.agent_avatar,
+      } as HumanAgent);
+      setStatus('active');
+    });
+
+    customerSocketManager.onQueueUpdate((data) => {
+      setStatus('queued');
+    });
+
+    customerSocketManager.onEscalationResolved(() => {
+      setStatus('resolved');
+    });
+
+    customerSocketManager.onHandedBack(() => {
+      setStatus('idle');
+      setEscalationId(null);
+      setAssignedAgent(null);
+    });
+  }, [customerSocketManager]);
+
+  const requestHuman = useCallback((conversationId: string) => {
+    connectCustomerSocket(conversationId);
+    if (customerSocketManager) {
+      customerSocketManager.requestHuman();
+      setStatus('requesting');
+    }
+  }, [customerSocketManager, connectCustomerSocket]);
+
+  const endChat = useCallback(() => {
+    if (escalationId && customerSocketManager) {
+      customerSocketManager.endChat(escalationId);
+      disconnectCustomerSocket();
+      setStatus('idle');
+      setEscalationId(null);
+      setAssignedAgent(null);
+    }
+  }, [escalationId, customerSocketManager, disconnectCustomerSocket]);
+
+  const submitCSAT = useCallback((rating: number) => {
+    if (escalationId && customerSocketManager) {
+      customerSocketManager.submitCSAT(escalationId, rating);
+    }
+  }, [escalationId, customerSocketManager]);
+
+  return {
+    escalationId,
+    assignedAgent,
+    status,
+    requestHuman,
+    endChat,
+    submitCSAT,
+  };
+}

package/src/hooks/usePushNotifications.ts

@@ -0,0 +1,414 @@
+import { useState, useCallback, useEffect } from 'react';
+import { useSolveo } from '../SolveoProvider';
+import { Platform } from 'react-native';
+import type { Device } from '@solveoai/sdk-core';
+
+/**
+ * Push notification event handlers
+ */
+export interface PushNotificationHandlers {
+  onNotificationReceived?: (notification: any) => void;
+  onNotificationTapped?: (notification: any) => void;
+}
+
+/**
+ * Push notification state
+ */
+export interface PushNotificationState {
+  device: Device | null;
+  isRegistered: boolean;
+  isInitialized: boolean;
+  permissionStatus: 'granted' | 'denied' | 'undetermined';
+}
+
+/**
+ * Hook options
+ */
+export interface UsePushNotificationsOptions {
+  mode?: 'widget' | 'agent';  // 'widget' for customer-facing, 'agent' for dashboard
+  conversationId?: string;     // Required for widget mode
+  autoRegister?: boolean;      // Auto-register if permission granted
+  handlers?: PushNotificationHandlers;
+}
+
+/**
+ * Enhanced Push Notifications Hook for React Native
+ * 
+ * Supports both customer (widget) and agent (dashboard) modes.
+ * Handles permissions, registration, and notification events.
+ * 
+ * SETUP INSTRUCTIONS:
+ * 1. Install peer dependencies:
+ *    npm install @react-native-firebase/app @react-native-firebase/messaging
+ *    (or expo-notifications for Expo projects)
+ * 
+ * 2. Configure Firebase/APNs:
+ *    - Android: Add google-services.json to android/app/
+ *    - iOS: Add GoogleService-Info.plist to ios/ and configure APNs
+ * 
+ * 3. Add permissions to manifests:
+ *    - Android: INTERNET, VIBRATE, RECEIVE_BOOT_COMPLETED
+ *    - iOS: User Notifications capability
+ */
+export function usePushNotifications(options: UsePushNotificationsOptions = {}) {
+  const { sdk } = useSolveo();
+  const {
+    mode = 'widget',
+    conversationId,
+    autoRegister = false,
+    handlers,
+  } = options;
+
+  const [state, setState] = useState<PushNotificationState>({
+    device: null,
+    isRegistered: false,
+    isInitialized: false,
+    permissionStatus: 'undetermined',
+  });
+
+  /**
+   * Request notification permission from the OS
+   */
+  const requestPermission = useCallback(async (): Promise<boolean> => {
+    try {
+      // Try to import Firebase Messaging
+      const messaging = await import('@react-native-firebase/messaging').then(m => m.default);
+      
+      const authStatus = await messaging().requestPermission();
+      const enabled =
+        authStatus === messaging.AuthorizationStatus.AUTHORIZED ||
+        authStatus === messaging.AuthorizationStatus.PROVISIONAL;
+
+      setState(prev => ({
+        ...prev,
+        permissionStatus: enabled ? 'granted' : 'denied',
+      }));
+
+      return enabled;
+    } catch (error) {
+      console.error('Failed to request permission (Firebase Messaging not installed?):', error);
+      
+      // Fallback: Try expo-notifications if Firebase not available
+      try {
+        const Notifications = await import('expo-notifications');
+        const { status } = await Notifications.requestPermissionsAsync();
+        const granted = status === 'granted';
+        
+        setState(prev => ({
+          ...prev,
+          permissionStatus: granted ? 'granted' : 'denied',
+        }));
+        
+        return granted;
+      } catch (expoError) {
+        console.error('Failed to request permission (Expo Notifications not installed?):', expoError);
+        setState(prev => ({ ...prev, permissionStatus: 'denied' }));
+        return false;
+      }
+    }
+  }, []);
+
+  /**
+   * Get FCM token from device
+   */
+  const getToken = useCallback(async (): Promise<string | null> => {
+    try {
+      // Try Firebase Messaging first
+      const messaging = await import('@react-native-firebase/messaging').then(m => m.default);
+      const token = await messaging().getToken();
+      return token;
+    } catch (error) {
+      console.error('Failed to get FCM token:', error);
+      
+      // Fallback to Expo push token
+      try {
+        const Notifications = await import('expo-notifications');
+        const token = await Notifications.getExpoPushTokenAsync();
+        return token.data;
+      } catch (expoError) {
+        console.error('Failed to get Expo push token:', expoError);
+        return null;
+      }
+    }
+  }, []);
+
+  /**
+   * Register device for push notifications (customer/widget mode)
+   */
+  const registerDevice = useCallback(
+    async (convId?: string, pushToken?: string, bundleId?: string): Promise<Device | null> => {
+      if (mode !== 'widget') {
+        console.warn('registerDevice is only for widget mode. Use registerAgentDevice for agent mode.');
+        return null;
+      }
+
+      const targetConversationId = convId || conversationId;
+      if (!targetConversationId) {
+        console.error('conversationId is required for widget mode registration');
+        return null;
+      }
+
+      try {
+        const token = pushToken || (await getToken());
+        if (!token) {
+          throw new Error('Failed to get push token');
+        }
+
+        const platform = Platform.OS === 'ios' ? 'IOS' : 'ANDROID';
+        const device = await sdk.widgetDevices.register({
+          conversation_id: targetConversationId,
+          platform,
+          push_token: token,
+          bundle_id: bundleId,
+        });
+
+        setState(prev => ({ ...prev, device, isRegistered: true }));
+        return device;
+      } catch (error) {
+        console.error('Failed to register device:', error);
+        throw error;
+      }
+    },
+    [sdk, conversationId, mode, getToken]
+  );
+
+  /**
+   * Register device for push notifications (agent/dashboard mode)
+   */
+  const registerAgentDevice = useCallback(
+    async (pushToken?: string, deviceName?: string): Promise<any> => {
+      if (mode !== 'agent') {
+        console.warn('registerAgentDevice is only for agent mode. Use registerDevice for widget mode.');
+        return null;
+      }
+
+      try {
+        const token = pushToken || (await getToken());
+        if (!token) {
+          throw new Error('Failed to get push token');
+        }
+
+        const platform = Platform.OS === 'ios' ? 'IOS' : 'ANDROID';
+        
+        // Call authenticated endpoint for agent device registration
+        const response = await sdk.client.post('/user-devices', {
+          platform,
+          push_token: token,
+          device_name: deviceName || `${Platform.OS} Device`,
+        });
+
+        setState(prev => ({
+          ...prev,
+          device: response.data,
+          isRegistered: true,
+        }));
+
+        return response.data;
+      } catch (error) {
+        console.error('Failed to register agent device:', error);
+        throw error;
+      }
+    },
+    [sdk, mode, getToken]
+  );
+
+  /**
+   * Unregister device from push notifications
+   */
+  const unregisterDevice = useCallback(async () => {
+    if (!state.device) {
+      return;
+    }
+
+    try {
+      if (mode === 'widget') {
+        await sdk.widgetDevices.unregister(state.device.id);
+      } else {
+        await sdk.client.delete(`/user-devices/${state.device.id}`);
+      }
+      
+      setState(prev => ({
+        ...prev,
+        device: null,
+        isRegistered: false,
+      }));
+    } catch (error) {
+      console.error('Failed to unregister device:', error);
+      throw error;
+    }
+  }, [sdk, state.device, mode]);
+
+  /**
+   * Setup foreground notification handler
+   */
+  useEffect(() => {
+    if (!handlers?.onNotificationReceived) {
+      return;
+    }
+
+    let unsubscribe: (() => void) | undefined;
+
+    const setupForegroundHandler = async () => {
+      try {
+        // Try Firebase Messaging
+        const messaging = await import('@react-native-firebase/messaging').then(m => m.default);
+        
+        unsubscribe = messaging().onMessage(async remoteMessage => {
+          console.log('Foreground notification received:', remoteMessage);
+          handlers.onNotificationReceived?.(remoteMessage);
+        });
+      } catch (error) {
+        // Fallback to Expo
+        try {
+          const Notifications = await import('expo-notifications');
+          
+          const subscription = Notifications.addNotificationReceivedListener(notification => {
+            console.log('Foreground notification received (Expo):', notification);
+            handlers.onNotificationReceived?.(notification);
+          });
+          
+          unsubscribe = () => subscription.remove();
+        } catch (expoError) {
+          console.error('Failed to setup foreground handler:', expoError);
+        }
+      }
+    };
+
+    setupForegroundHandler();
+
+    return () => {
+      unsubscribe?.();
+    };
+  }, [handlers?.onNotificationReceived]);
+
+  /**
+   * Setup notification tap handler
+   */
+  useEffect(() => {
+    if (!handlers?.onNotificationTapped) {
+      return;
+    }
+
+    let unsubscribe: (() => void) | undefined;
+
+    const setupTapHandler = async () => {
+      try {
+        // Try Firebase Messaging
+        const messaging = await import('@react-native-firebase/messaging').then(m => m.default);
+        
+        // Handle notification opened app from quit state
+        messaging()
+          .getInitialNotification()
+          .then(remoteMessage => {
+            if (remoteMessage) {
+              console.log('Notification opened app from quit state:', remoteMessage);
+              handlers.onNotificationTapped?.(remoteMessage);
+            }
+          });
+
+        // Handle notification opened app from background state
+        unsubscribe = messaging().onNotificationOpenedApp(remoteMessage => {
+          console.log('Notification opened app from background:', remoteMessage);
+          handlers.onNotificationTapped?.(remoteMessage);
+        });
+      } catch (error) {
+        // Fallback to Expo
+        try {
+          const Notifications = await import('expo-notifications');
+          
+          const subscription = Notifications.addNotificationResponseReceivedListener(response => {
+            console.log('Notification tapped (Expo):', response);
+            handlers.onNotificationTapped?.(response.notification);
+          });
+          
+          unsubscribe = () => subscription.remove();
+        } catch (expoError) {
+          console.error('Failed to setup tap handler:', expoError);
+        }
+      }
+    };
+
+    setupTapHandler();
+
+    return () => {
+      unsubscribe?.();
+    };
+  }, [handlers?.onNotificationTapped]);
+
+  /**
+   * Handle token refresh
+   */
+  useEffect(() => {
+    let unsubscribe: (() => void) | undefined;
+
+    const setupTokenRefreshHandler = async () => {
+      try {
+        const messaging = await import('@react-native-firebase/messaging').then(m => m.default);
+        
+        unsubscribe = messaging().onTokenRefresh(async newToken => {
+          console.log('FCM token refreshed:', newToken);
+          
+          // Re-register with new token
+          if (state.isRegistered) {
+            if (mode === 'widget' && conversationId) {
+              await registerDevice(conversationId, newToken);
+            } else if (mode === 'agent') {
+              await registerAgentDevice(newToken);
+            }
+          }
+        });
+      } catch (error) {
+        console.error('Failed to setup token refresh handler:', error);
+      }
+    };
+
+    setupTokenRefreshHandler();
+
+    return () => {
+      unsubscribe?.();
+    };
+  }, [state.isRegistered, mode, conversationId, registerDevice, registerAgentDevice]);
+
+  /**
+   * Check permission status on mount
+   */
+  useEffect(() => {
+    const checkPermission = async () => {
+      try {
+        const messaging = await import('@react-native-firebase/messaging').then(m => m.default);
+        const authStatus = await messaging().hasPermission();
+        const granted =
+          authStatus === messaging.AuthorizationStatus.AUTHORIZED ||
+          authStatus === messaging.AuthorizationStatus.PROVISIONAL;
+
+        setState(prev => ({
+          ...prev,
+          permissionStatus: granted ? 'granted' : authStatus === messaging.AuthorizationStatus.NOT_DETERMINED ? 'undetermined' : 'denied',
+          isInitialized: true,
+        }));
+
+        // Auto-register if permission granted and autoRegister enabled
+        if (granted && autoRegister && !state.isRegistered) {
+          if (mode === 'widget' && conversationId) {
+            await registerDevice();
+          } else if (mode === 'agent') {
+            await registerAgentDevice();
+          }
+        }
+      } catch (error) {
+        console.error('Failed to check permission:', error);
+        setState(prev => ({ ...prev, isInitialized: true }));
+      }
+    };
+
+    checkPermission();
+  }, [autoRegister, mode, conversationId, registerDevice, registerAgentDevice]);
+
+  return {
+    ...state,
+    requestPermission,
+    registerDevice,
+    registerAgentDevice,
+    unregisterDevice,
+  };
+}

package/src/hooks/useRealtime.ts

@@ -0,0 +1,41 @@
+import { useState, useEffect } from 'react';
+import { useSolveo } from '../SolveoProvider';
+
+export function useRealtime() {
+  const { customerSocketManager } = useSolveo();
+  const [isConnected, setIsConnected] = useState(false);
+  const [agentTyping, setAgentTyping] = useState(false);
+  const [queuePosition, setQueuePosition] = useState<number | null>(null);
+  const [estimatedWait, setEstimatedWait] = useState<number | null>(null);
+
+  useEffect(() => {
+    if (!customerSocketManager) return;
+
+    const socket = customerSocketManager.getSocket();
+
+    socket.on('connect', () => setIsConnected(true));
+    socket.on('disconnect', () => setIsConnected(false));
+
+    customerSocketManager.onAgentTyping(() => {
+      setAgentTyping(true);
+      setTimeout(() => setAgentTyping(false), 3000);
+    });
+
+    customerSocketManager.onQueueUpdate((data) => {
+      setQueuePosition(data.queue_position);
+      setEstimatedWait(data.estimated_wait);
+    });
+
+    return () => {
+      socket.off('connect');
+      socket.off('disconnect');
+    };
+  }, [customerSocketManager]);
+
+  return {
+    isConnected,
+    agentTyping,
+    queuePosition,
+    estimatedWait,
+  };
+}

package/src/hooks/useWidgetConfig.ts

@@ -0,0 +1,52 @@
+import { useState, useEffect } from 'react';
+import { useSolveo } from '../SolveoProvider';
+import { storage } from '../utils/storage';
+import type { Widget, WidgetConfig } from '@solveo-ai/sdk-core';
+
+export function useWidgetConfig(widgetId?: string) {
+  const { sdk, config } = useSolveo();
+  const effectiveWidgetId = widgetId || config.widgetId;
+  const [widget, setWidget] = useState<Widget | null>(null);
+  const [widgetConfig, setWidgetConfig] = useState<WidgetConfig | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    if (effectiveWidgetId) {
+      loadConfig();
+    }
+  }, [effectiveWidgetId]);
+
+  const loadConfig = async () => {
+    if (!effectiveWidgetId) return;
+    
+    setIsLoading(true);
+    setError(null);
+    try {
+      // Try cache first
+      const cached = await storage.getWidgetConfig(effectiveWidgetId);
+      if (cached) {
+        setWidget(cached);
+        setWidgetConfig(cached.config);
+      }
+
+      // Fetch fresh config
+      const w = await sdk.widgetConfig.getConfig(effectiveWidgetId);
+      setWidget(w);
+      setWidgetConfig(w.config);
+      await storage.setWidgetConfig(effectiveWidgetId, w);
+    } catch (err: any) {
+      setError(err);
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  return {
+    widget,
+    widgetConfig,
+    isLoading,
+    error,
+    reload: loadConfig,
+  };
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// Provider
+export { SolveoProvider, useSolveo, type SolveoProviderConfig, type SolveoProviderProps } from './SolveoProvider';
+
+// Hooks
+export * from './hooks';
+
+// Utils
+export { storage } from './utils/storage';
+
+// Re-export core SDK types and utilities
+export type {
+  Message,
+  Conversation,
+  Agent,
+  Widget,
+  MessageAttachment,
+  SentimentType,
+  ConversationStatus,
+  FeedbackType,
+} from '@solveo-ai/sdk-core';

package/src/utils/storage.ts

@@ -0,0 +1,49 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+const STORAGE_KEYS = {
+  CONVERSATION_ID: '@solveo/conversation_id',
+  MESSAGES: '@solveo/messages',
+  USER_IDENTITY: '@solveo/user_identity',
+  WIDGET_CONFIG: '@solveo/widget_config',
+};
+
+export const storage = {
+  async getConversationId(): Promise<string | null> {
+    return AsyncStorage.getItem(STORAGE_KEYS.CONVERSATION_ID);
+  },
+
+  async setConversationId(id: string): Promise<void> {
+    await AsyncStorage.setItem(STORAGE_KEYS.CONVERSATION_ID, id);
+  },
+
+  async clearConversationId(): Promise<void> {
+    await AsyncStorage.removeItem(STORAGE_KEYS.CONVERSATION_ID);
+  },
+
+  async getMessages(conversationId: string): Promise<any[]> {
+    const data = await AsyncStorage.getItem(`${STORAGE_KEYS.MESSAGES}_${conversationId}`);
+    return data ? JSON.parse(data) : [];
+  },
+
+  async setMessages(conversationId: string, messages: any[]): Promise<void> {
+    await AsyncStorage.setItem(`${STORAGE_KEYS.MESSAGES}_${conversationId}`, JSON.stringify(messages));
+  },
+
+  async getUserIdentity(): Promise<{ email?: string; name?: string } | null> {
+    const data = await AsyncStorage.getItem(STORAGE_KEYS.USER_IDENTITY);
+    return data ? JSON.parse(data) : null;
+  },
+
+  async setUserIdentity(identity: { email?: string; name?: string }): Promise<void> {
+    await AsyncStorage.setItem(STORAGE_KEYS.USER_IDENTITY, JSON.stringify(identity));
+  },
+
+  async getWidgetConfig(widgetId: string): Promise<any | null> {
+    const data = await AsyncStorage.getItem(`${STORAGE_KEYS.WIDGET_CONFIG}_${widgetId}`);
+    return data ? JSON.parse(data) : null;
+  },
+
+  async setWidgetConfig(widgetId: string, config: any): Promise<void> {
+    await AsyncStorage.setItem(`${STORAGE_KEYS.WIDGET_CONFIG}_${widgetId}`, JSON.stringify(config));
+  },
+};