@centive/aria-sdk 0.5.4 → 0.5.5

package/README.md

@@ -15,6 +15,7 @@ A production-ready React SDK for [Anam AI](https://docs.anam.ai/) with dual-mode
 ### 🚀 Global Session Management
 - **Session Preloading** - Session is ready before user clicks, for instant response
 - **Session Persistence** - Session survives page navigation in SPAs
+- **Widget Toggle Persistence** - Keep session alive when widget is closed/reopened (optional)
 - **Proactive Refresh** - Automatically refreshes session before expiration
 - **Tab Visibility Awareness** - Only refreshes when tab is active
 - **Error Recovery** - Exponential backoff retry on failures
@@ -274,6 +275,7 @@ function MyComponent() {
     sessionState,
     sessionManagerStatus,  // 'idle' | 'connecting' | 'connected' | 'preloading' | 'ready' | 'refreshing' | 'error'
     isSessionPreloaded,    // True when session is ready before widget opens
+    isSessionPaused,       // True when session is paused (widget closed with persistSession: true)
     
     // Actions
     openAssistant,
@@ -282,7 +284,7 @@ function MyComponent() {
     sendMessage,
     toggleMute,
     startSession,
-    stopSession,
+    stopSession,           // Ends session (ignores persistSession setting)
     triggerSession,
     refreshSession,        // Manually refresh the session
     setVideoElement,
@@ -390,6 +392,12 @@ interface AriaSDKConfig {
   onSessionRefresh?: () => void;     // Callback when session is refreshed
   onSessionRefreshError?: (error: Error) => void; // Callback when refresh fails
   
+  // Session persistence options (Widget Toggle Persistence)
+  persistSession?: boolean;          // Keep session alive when widget closes (default: false)
+  keepWebSocketAlive?: boolean;      // Keep WebSocket connected when paused (default: true)
+  onSessionPaused?: () => void;      // Callback when session is paused (widget closed)
+  onSessionResumed?: () => void;     // Callback when session is resumed (widget reopened)
+  
   // Rendering options
   showFloatingButton?: boolean;      // Show the default floating button (default: true)
   showAssistant?: boolean;           // Show the assistant widget (default: true)
@@ -535,6 +543,66 @@ function App() {
 
 > **Note:** Even if placed incorrectly, the SDK's singleton pattern provides a safety net to maintain session continuity.
 
+### Session Persistence (Widget Toggle)
+
+By default, the SDK ends the session when the widget is closed. With `persistSession: true`, the session stays alive across widget open/close cycles:
+
+```tsx
+const config = {
+  websocketUrl: 'ws://localhost:8000/ws',
+  userId: 'user_123',
+  
+  // Enable session persistence
+  persistSession: true,              // Keep session alive when widget closes
+  keepWebSocketAlive: true,          // Keep WebSocket connected (default: true)
+  
+  // Callbacks
+  onSessionPaused: () => {
+    console.log('Session paused - widget closed');
+  },
+  onSessionResumed: () => {
+    console.log('Session resumed - widget reopened');
+  },
+};
+```
+
+**Behavior with `persistSession: true`:**
+
+| Action | Result |
+|--------|--------|
+| User opens widget | Uses existing session (or creates new if none) |
+| User closes widget | Session paused, stays alive |
+| User reopens widget | Session resumed instantly |
+| User calls `stopSession()` | Session ends (explicit action) |
+| Tab/window closes | Session ends (beforeunload) |
+| Session token expires | New session created on next open |
+
+**Use Cases:**
+- Customer support chat - User minimizes to browse, reopens to continue
+- Sales assistant - Persistent context across multiple page views
+- Onboarding flow - AI maintains context as user navigates steps
+- Dashboard help - Toggle help widget without losing conversation
+
+```tsx
+function SessionController() {
+  const { 
+    isSessionPaused,
+    stopSession,
+  } = useAria();
+  
+  return (
+    <div>
+      <p>Session paused: {isSessionPaused ? 'Yes' : 'No'}</p>
+      
+      {/* Explicitly end session (ignores persistSession) */}
+      <button onClick={stopSession}>
+        End Session
+      </button>
+    </div>
+  );
+}
+```
+
 ### Session Refresh
 
 The SDK automatically refreshes sessions before they expire:

package/dist/context/AriaContext.d.ts

@@ -13,6 +13,8 @@ export interface AriaContextType {
     sessionManagerStatus: SessionManagerStatus;
     /** Whether the session is preloaded and ready for instant use */
     isSessionPreloaded: boolean;
+    /** Whether the session is currently paused (widget closed with persistSession: true) */
+    isSessionPaused: boolean;
     openAssistant: (mode?: TriggerMode) => void;
     closeAssistant: () => void;
     toggleChat: () => void;

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,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"}
+{"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;IAC5B,wFAAwF;IACxF,eAAe,EAAE,OAAO,CAAC;IAGzB,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;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"}
+{"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,CAka9C,CAAC"}