@centive/aria-sdk 0.5.2 → 0.5.3

package/README.md

@@ -12,6 +12,13 @@ A production-ready React SDK for [Anam AI](https://docs.anam.ai/) with dual-mode
 - **Center Modal Mode** - Auto-opens when WebSocket events arrive (e.g., incoming calls)
 - **Both modes work simultaneously** - Maximum flexibility for any use case
 
+### 🚀 Global Session Management
+- **Session Preloading** - Session is ready before user clicks, for instant response
+- **Session Persistence** - Session survives page navigation in SPAs
+- **Proactive Refresh** - Automatically refreshes session before expiration
+- **Tab Visibility Awareness** - Only refreshes when tab is active
+- **Error Recovery** - Exponential backoff retry on failures
+
 ### 🔌 WebSocket Integration
 - Real-time bidirectional communication
 - Automatic session management
@@ -58,21 +65,33 @@ npm install react@^18.0.0 react-dom@^18.0.0
 
 The SDK provides an all-in-one container that handles WebSocket connection, state management, and the UI. Just import and drop it in! By default, this includes both the floating trigger button and the assistant widget.
 
+> **Important:** Place `Aria` (or `AriaProvider`) at your app's root level, **above your router**. This ensures the session persists across page navigation and provides instant response when users click the trigger button.
+
 ```tsx
 import { Aria } from '@centive/aria-sdk';
 import '@centive/aria-sdk/styles.css';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
 
 function App() {
   const config = {
     websocketUrl: 'ws://localhost:8000/ws',
     userId: 'user_123',
     theme: 'light', // or 'dark'
+    // Session preloading is enabled by default
+    preloadSession: true,
+    // Refresh session 5 minutes before expiry (default)
+    sessionRefreshBuffer: 5,
   };
 
   return (
-    // This automatically renders the Trigger Button and Assistant Widget
+    // Place Aria at the root, ABOVE the router for session persistence
     <Aria config={config}>
-      <YourApp />
+      <BrowserRouter>
+        <Routes>
+          <Route path="/" element={<Home />} />
+          <Route path="/dashboard" element={<Dashboard />} />
+        </Routes>
+      </BrowserRouter>
     </Aria>
   );
 }
@@ -84,6 +103,7 @@ If you need full control over where components are rendered, you can disable the
 
 ```tsx
 import { AriaProvider, AriaAssistant } from '@centive/aria-sdk';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
 
 function App() {
   const config = {
@@ -93,8 +113,14 @@ function App() {
   };
 
   return (
+    // Always place AriaProvider at the root, above the router
     <AriaProvider config={config}>
-      <YourApp />
+      <BrowserRouter>
+        <Routes>
+          <Route path="/" element={<Home />} />
+          <Route path="/dashboard" element={<Dashboard />} />
+        </Routes>
+      </BrowserRouter>
       
       {/* AriaAssistant includes both the trigger button and the widget */}
       <AriaAssistant 
@@ -231,13 +257,25 @@ import { useAria } from '@centive/aria-sdk';
 
 function MyComponent() {
   const {
+    // UI State
     isOpen,
     isConnected,
+    isLoading,
     displayMode,
     triggerMode,
     theme,
     chatMessages,
+    liveTranscript,
+    isChatVisible,
+    isMuted,
+    error,
+    
+    // Session State
     sessionState,
+    sessionManagerStatus,  // 'idle' | 'connecting' | 'connected' | 'preloading' | 'ready' | 'refreshing' | 'error'
+    isSessionPreloaded,    // True when session is ready before widget opens
+    
+    // Actions
     openAssistant,
     closeAssistant,
     toggleChat,
@@ -246,7 +284,12 @@ function MyComponent() {
     startSession,
     stopSession,
     triggerSession,
-    getSessionIdFromToken,  // Extract session ID from tokens
+    refreshSession,        // Manually refresh the session
+    setVideoElement,
+    
+    // Utilities
+    getSessionId,
+    config,
   } = useAria();
   
   // Use the methods and state
@@ -340,6 +383,13 @@ interface AriaSDKConfig {
   onSessionEndAck?: (savedCount: number) => void;
   onSessionEndError?: (error: string, errorType: string) => void;
   
+  // Session preloading options (Global Session Management)
+  preloadSession?: boolean;          // Enable session preloading on mount (default: true)
+  sessionRefreshBuffer?: number;     // Minutes before expiry to refresh (default: 5)
+  onSessionPreloaded?: () => void;   // Callback when session is preloaded and ready
+  onSessionRefresh?: () => void;     // Callback when session is refreshed
+  onSessionRefreshError?: (error: Error) => void; // Callback when refresh fails
+  
   // Rendering options
   showFloatingButton?: boolean;      // Show the default floating button (default: true)
   showAssistant?: boolean;           // Show the assistant widget (default: true)
@@ -431,6 +481,112 @@ See `example-ws-server.js` for a complete implementation.
 }
 ```
 
+## 🔄 Session Management
+
+### Global Session Architecture
+
+The SDK uses a singleton pattern to maintain session state globally, ensuring:
+
+1. **Session Preloading** - When `AriaProvider` mounts, it automatically:
+   - Connects to WebSocket
+   - Requests a session token
+   - Pre-initializes the Anam client
+   - Prepares video streaming in a hidden element
+
+2. **Instant Response** - When users click the trigger button:
+   - Session is already ready (no loading delay)
+   - Video stream transfers instantly to the visible widget
+
+3. **Session Persistence** - During page navigation:
+   - Session survives component unmounts/remounts
+   - No reconnection needed when navigating between pages
+
+### Provider Placement (Critical)
+
+**Correct:** Place at app root, above router:
+```tsx
+function App() {
+  return (
+    <AriaProvider config={config}>
+      <BrowserRouter>
+        <Routes>...</Routes>
+      </BrowserRouter>
+    </AriaProvider>
+  );
+}
+```
+
+**Incorrect:** Inside route (session lost on navigation):
+```tsx
+function App() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route path="/" element={
+          <AriaProvider config={config}>  {/* Don't do this! */}
+            <Home />
+          </AriaProvider>
+        } />
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+> **Note:** Even if placed incorrectly, the SDK's singleton pattern provides a safety net to maintain session continuity.
+
+### Session Refresh
+
+The SDK automatically refreshes sessions before they expire:
+
+```tsx
+const config = {
+  websocketUrl: 'ws://localhost:8000/ws',
+  userId: 'user_123',
+  
+  // Session refresh configuration
+  sessionRefreshBuffer: 5, // Refresh 5 minutes before expiry (default)
+  
+  // Callbacks
+  onSessionPreloaded: () => {
+    console.log('Session is preloaded and ready!');
+  },
+  onSessionRefresh: () => {
+    console.log('Session refreshed successfully');
+  },
+  onSessionRefreshError: (error) => {
+    console.error('Session refresh failed:', error);
+  },
+};
+```
+
+### Manual Session Control
+
+```tsx
+function SessionController() {
+  const { 
+    sessionState,
+    sessionManagerStatus,
+    isSessionPreloaded,
+    refreshSession,
+  } = useAria();
+  
+  return (
+    <div>
+      <p>Status: {sessionManagerStatus}</p>
+      <p>Preloaded: {isSessionPreloaded ? 'Yes' : 'No'}</p>
+      <p>Session ID: {sessionState.session_id}</p>
+      <p>Expires: {sessionState.expires_at}</p>
+      
+      {/* Manual refresh if needed */}
+      <button onClick={refreshSession}>
+        Refresh Session
+      </button>
+    </div>
+  );
+}
+```
+
 ## 💡 Advanced Usage
 
 ### Programmatic Control

package/dist/components/AriaTriggerButton.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AriaTriggerButton.d.ts","sourceRoot":"","sources":["../../src/components/AriaTriggerButton.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAGhC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAM1D,UAAU,sBAAuB,SAAQ,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,eAAO,MAAM,iBAAiB,EAAE,EAAE,CAAC,sBAAsB,CAkHxD,CAAC"}
+{"version":3,"file":"AriaTriggerButton.d.ts","sourceRoot":"","sources":["../../src/components/AriaTriggerButton.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAGhC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAM1D,UAAU,sBAAuB,SAAQ,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,eAAO,MAAM,iBAAiB,EAAE,EAAE,CAAC,sBAAsB,CAsHxD,CAAC"}

package/dist/components/AriaWidget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AriaWidget.d.ts","sourceRoot":"","sources":["../../src/components/AriaWidget.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,EAAE,EAAE,MAAM,OAAO,CAAC;AAOnD,UAAU,eAAe;IACvB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,eAAO,MAAM,UAAU,EAAE,EAAE,CAAC,eAAe,CAyS1C,CAAC"}
+{"version":3,"file":"AriaWidget.d.ts","sourceRoot":"","sources":["../../src/components/AriaWidget.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,EAAE,EAAE,MAAM,OAAO,CAAC;AAOnD,UAAU,eAAe;IACvB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,eAAO,MAAM,UAAU,EAAE,EAAE,CAAC,eAAe,CA0T1C,CAAC"}

package/dist/context/AriaContext.d.ts

@@ -1,4 +1,4 @@
-import type { ChatMessage, AriaSDKConfig, DisplayMode, TriggerMode, Theme, SessionState, TriggerSessionOptions } from '@/types';
+import type { ChatMessage, AriaSDKConfig, DisplayMode, TriggerMode, Theme, SessionState, TriggerSessionOptions, SessionManagerStatus } from '@/types';
 export interface AriaContextType {
     isOpen: boolean;
     isConnected: boolean;
@@ -9,7 +9,11 @@ export interface AriaContextType {
     isMuted: boolean;
     error: string | null;
     sessionState: SessionState;
-    openAssistant: (mode: TriggerMode) => void;
+    /** Current status of the session manager */
+    sessionManagerStatus: SessionManagerStatus;
+    /** Whether the session is preloaded and ready for instant use */
+    isSessionPreloaded: boolean;
+    openAssistant: (mode?: TriggerMode) => void;
     closeAssistant: () => void;
     toggleChat: () => void;
     sendMessage: (message: string) => Promise<void>;
@@ -17,6 +21,8 @@ export interface AriaContextType {
     startSession: () => Promise<void>;
     stopSession: () => Promise<void>;
     triggerSession: (options?: TriggerSessionOptions) => void;
+    /** Manually refresh the session (useful for error recovery) */
+    refreshSession: () => Promise<void>;
     setVideoElement: (element: HTMLVideoElement | null) => void;
     displayMode: DisplayMode;
     triggerMode: TriggerMode;

package/dist/context/AriaContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AriaContext.d.ts","sourceRoot":"","sources":["../../src/context/AriaContext.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAEhI,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,YAAY,CAAC;IAC3B,aAAa,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;IAC3C,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,cAAc,EAAE,CAAC,OAAO,CAAC,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC1D,eAAe,EAAE,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,KAAK,IAAI,CAAC;IAC5D,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,YAAY,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,eAAO,MAAM,WAAW,iDAA8C,CAAC"}
+{"version":3,"file":"AriaContext.d.ts","sourceRoot":"","sources":["../../src/context/AriaContext.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEtJ,MAAM,WAAW,eAAe;IAE9B,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAGrB,YAAY,EAAE,YAAY,CAAC;IAC3B,4CAA4C;IAC5C,oBAAoB,EAAE,oBAAoB,CAAC;IAC3C,iEAAiE;IACjE,kBAAkB,EAAE,OAAO,CAAC;IAG5B,aAAa,EAAE,CAAC,IAAI,CAAC,EAAE,WAAW,KAAK,IAAI,CAAC;IAC5C,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,cAAc,EAAE,CAAC,OAAO,CAAC,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC1D,+DAA+D;IAC/D,cAAc,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,eAAe,EAAE,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,KAAK,IAAI,CAAC;IAG5D,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,EAAE,KAAK,CAAC;IAGb,MAAM,EAAE,aAAa,CAAC;IAGtB,YAAY,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,eAAO,MAAM,WAAW,iDAA8C,CAAC"}

package/dist/context/AriaProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AriaProvider.d.ts","sourceRoot":"","sources":["../../src/context/AriaProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA4C,KAAK,EAAE,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAoB1F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAM7C,UAAU,iBAAiB;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAgGD,eAAO,MAAM,YAAY,EAAE,EAAE,CAAC,iBAAiB,CA8qB9C,CAAC"}
+{"version":3,"file":"AriaProvider.d.ts","sourceRoot":"","sources":["../../src/context/AriaProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA4C,KAAK,EAAE,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAU1F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAK7C,UAAU,iBAAiB;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAMD,eAAO,MAAM,YAAY,EAAE,EAAE,CAAC,iBAAiB,CA2X9C,CAAC"}