@centive/aria-sdk 0.5.6 → 0.5.8

package/README.md

@@ -13,9 +13,10 @@ A production-ready React SDK for [Anam AI](https://docs.anam.ai/) with dual-mode
 - **Both modes work simultaneously** - Maximum flexibility for any use case
 
 ### 🚀 Global Session Management
-- **Session Preloading** - Session is ready before user clicks, for instant response
+- **Lazy Session Initialization** - Greeting plays exactly when user opens widget (not preloaded)
 - **Session Persistence** - Session survives page navigation in SPAs
 - **Widget Toggle Persistence** - Keep session alive when widget is closed/reopened (optional)
+- **Minimized Widget State** - Click outside to minimize, keeping session active
 - **Proactive Refresh** - Automatically refreshes session before expiration
 - **Tab Visibility Awareness** - Only refreshes when tab is active
 - **Error Recovery** - Exponential backoff retry on failures
@@ -32,6 +33,7 @@ A production-ready React SDK for [Anam AI](https://docs.anam.ai/) with dual-mode
 - Mute/unmute audio controls
 - Live transcription display
 - Message history tracking
+- **Tool Call Indicators** - Visual feedback when AI is executing tools/functions
 
 ### 🎨 Modern UI
 - Video-call-style interface
@@ -260,6 +262,7 @@ function MyComponent() {
   const {
     // UI State
     isOpen,
+    isMinimized,           // True when widget is minimized (compact floating state)
     isConnected,
     isLoading,
     displayMode,
@@ -271,15 +274,20 @@ function MyComponent() {
     isMuted,
     error,
     
+    // Tool Call State
+    toolCallState,         // { isActive: boolean, toolName: string | null, toolData: object | null }
+    
     // Session State
     sessionState,
     sessionManagerStatus,  // 'idle' | 'connecting' | 'connected' | 'preloading' | 'ready' | 'refreshing' | 'error'
-    isSessionPreloaded,    // True when session is ready before widget opens
+    isSessionPreloaded,    // True when session token is ready
     isSessionPaused,       // True when session is paused (widget closed with persistSession: true)
     
     // Actions
     openAssistant,
     closeAssistant,
+    minimizeAssistant,     // Minimize widget to compact floating state
+    maximizeAssistant,     // Restore widget from minimized state
     toggleChat,
     sendMessage,
     toggleMute,
@@ -495,20 +503,25 @@ See `example-ws-server.js` for a complete implementation.
 
 The SDK uses a singleton pattern to maintain session state globally, ensuring:
 
-1. **Session Preloading** - When `AriaProvider` mounts, it automatically:
+1. **Lazy Session Initialization** - When `AriaProvider` mounts, it automatically:
    - Connects to WebSocket
-   - Requests a session token
-   - Pre-initializes the Anam client
-   - Prepares video streaming in a hidden element
+   - Requests a session token (token is ready)
+   - **Does NOT initialize Anam client yet** (lazy mode)
 
-2. **Instant Response** - When users click the trigger button:
-   - Session is already ready (no loading delay)
-   - Video stream transfers instantly to the visible widget
+2. **Greeting Plays on Open** - When users click the trigger button:
+   - Anam client initializes at this moment
+   - **Greeting plays exactly when user sees the widget**
+   - No missed greetings from preloading
 
 3. **Session Persistence** - During page navigation:
    - Session survives component unmounts/remounts
    - No reconnection needed when navigating between pages
 
+4. **Minimized Widget State** - When users click outside the widget:
+   - Widget minimizes to a compact floating state
+   - Session stays active (no interruption)
+   - Click to restore full widget
+
 ### Provider Placement (Critical)
 
 **Correct:** Place at app root, above router:
@@ -543,6 +556,68 @@ function App() {
 
 > **Note:** Even if placed incorrectly, the SDK's singleton pattern provides a safety net to maintain session continuity.
 
+### Minimized Widget State
+
+When users click outside the widget (on the backdrop), the widget minimizes to a compact floating state instead of closing completely. This allows users to:
+
+- Navigate the platform while keeping the session active
+- See a preview of the live transcript
+- Quickly resume the conversation with one click
+
+```tsx
+function WidgetController() {
+  const { 
+    isMinimized,
+    minimizeAssistant,
+    maximizeAssistant,
+    closeAssistant,
+  } = useAria();
+  
+  return (
+    <div>
+      <p>Minimized: {isMinimized ? 'Yes' : 'No'}</p>
+      
+      {/* Programmatic control */}
+      <button onClick={minimizeAssistant}>Minimize</button>
+      <button onClick={maximizeAssistant}>Maximize</button>
+      <button onClick={closeAssistant}>Close (End Session)</button>
+    </div>
+  );
+}
+```
+
+**Behavior:**
+| Action | Result |
+|--------|--------|
+| Click outside widget (backdrop) | Widget minimizes, session stays active |
+| Click minimized widget | Widget maximizes |
+| Click "End Call" button | Session ends completely |
+| Click X on minimized widget | Session ends completely |
+
+### Tool Call Indicators
+
+When Aria executes tool calls (function calling), the widget displays a visual indicator showing:
+- The tool name being executed
+- An animated "processing" state
+- Auto-clears when the tool completes
+
+```tsx
+function ToolCallMonitor() {
+  const { toolCallState } = useAria();
+  
+  return (
+    <div>
+      {toolCallState.isActive && (
+        <p>
+          Running tool: {toolCallState.toolName}
+          Data: {JSON.stringify(toolCallState.toolData)}
+        </p>
+      )}
+    </div>
+  );
+}
+```
+
 ### 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:
@@ -661,7 +736,14 @@ function SessionController() {
 
 ```tsx
 function CustomController() {
-  const { openAssistant, closeAssistant, triggerSession } = useAria();
+  const { 
+    openAssistant, 
+    closeAssistant, 
+    minimizeAssistant,
+    maximizeAssistant,
+    triggerSession,
+    isMinimized,
+  } = useAria();
   
   return (
     <div>
@@ -675,6 +757,16 @@ function CustomController() {
         Start Video Call
       </button>
       
+      {/* Minimize/Maximize widget */}
+      <button onClick={isMinimized ? maximizeAssistant : minimizeAssistant}>
+        {isMinimized ? 'Maximize' : 'Minimize'}
+      </button>
+      
+      {/* Close widget (ends session) */}
+      <button onClick={closeAssistant}>
+        End Session
+      </button>
+      
       {/* Manually trigger session */}
       <button onClick={triggerSession}>
         Create New Session

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

@@ -1 +1 @@
-{"version":3,"file":"AriaAssistant.d.ts","sourceRoot":"","sources":["../../src/components/AriaAssistant.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAOhC,UAAU,kBAAkB;IAC1B,uDAAuD;IACvD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oDAAoD;IACpD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,aAAa,EAAE,EAAE,CAAC,kBAAkB,CAwDhD,CAAC"}
+{"version":3,"file":"AriaAssistant.d.ts","sourceRoot":"","sources":["../../src/components/AriaAssistant.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAUhC,UAAU,kBAAkB;IAC1B,uDAAuD;IACvD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oDAAoD;IACpD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAmID,eAAO,MAAM,aAAa,EAAE,EAAE,CAAC,kBAAkB,CAyEhD,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,CA0T1C,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,CAmY1C,CAAC"}

package/dist/context/AriaContext.d.ts

@@ -1,6 +1,8 @@
-import type { ChatMessage, AriaSDKConfig, DisplayMode, TriggerMode, Theme, SessionState, TriggerSessionOptions, SessionManagerStatus } from '@/types';
+import type { ChatMessage, AriaSDKConfig, DisplayMode, TriggerMode, Theme, SessionState, TriggerSessionOptions, SessionManagerStatus, ToolCallState } from '@/types';
 export interface AriaContextType {
     isOpen: boolean;
+    /** Whether the widget is minimized (compact floating state) */
+    isMinimized: boolean;
     isConnected: boolean;
     isLoading: boolean;
     chatMessages: ChatMessage[];
@@ -8,6 +10,8 @@ export interface AriaContextType {
     isChatVisible: boolean;
     isMuted: boolean;
     error: string | null;
+    /** Current tool call state for UI display */
+    toolCallState: ToolCallState;
     sessionState: SessionState;
     /** Current status of the session manager */
     sessionManagerStatus: SessionManagerStatus;
@@ -17,6 +21,10 @@ export interface AriaContextType {
     isSessionPaused: boolean;
     openAssistant: (mode?: TriggerMode) => void;
     closeAssistant: () => void;
+    /** Minimize the widget to a compact floating state */
+    minimizeAssistant: () => void;
+    /** Maximize the widget from minimized state */
+    maximizeAssistant: () => void;
     toggleChat: () => void;
     sendMessage: (message: string) => Promise<void>;
     toggleMute: () => 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;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"}
+{"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,aAAa,EAAE,MAAM,SAAS,CAAC;AAErK,MAAM,WAAW,eAAe;IAE9B,MAAM,EAAE,OAAO,CAAC;IAChB,+DAA+D;IAC/D,WAAW,EAAE,OAAO,CAAC;IACrB,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,6CAA6C;IAC7C,aAAa,EAAE,aAAa,CAAC;IAG7B,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,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,+CAA+C;IAC/C,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,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,CA6a9C,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;AAW1F,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,CAwf9C,CAAC"}

package/dist/hooks/useAriaSession.d.ts

@@ -0,0 +1,75 @@
+import type { SessionState, SessionManagerStatus } from '@/types';
+/**
+ * Session information returned by useAriaSession hook
+ */
+export interface AriaSessionInfo {
+    /** Current session state including token, expiry, and readiness */
+    sessionState: SessionState;
+    /** Current status of the session manager */
+    status: SessionManagerStatus;
+    /** Whether the session is preloaded and ready for instant use */
+    isPreloaded: boolean;
+    /** Whether the session is currently paused (widget closed with persistSession: true) */
+    isPaused: boolean;
+    /** Whether the session is connected */
+    isConnected: boolean;
+    /** Whether the session is currently loading */
+    isLoading: boolean;
+    /** Current session ID if available */
+    sessionId: string | null;
+    /** Whether the session token is expired */
+    isExpired: boolean;
+    /** Whether the session is expiring soon (within refresh buffer) */
+    isExpiringSoon: boolean;
+    /** Time until session expires in milliseconds (null if no expiry) */
+    timeUntilExpiry: number | null;
+}
+/**
+ * Session control actions returned by useAriaSession hook
+ */
+export interface AriaSessionActions {
+    /** End the current session explicitly (for logout scenarios) */
+    endSession: () => Promise<void>;
+    /** Refresh the session token proactively */
+    refreshSession: () => Promise<void>;
+    /** Start a new session (if not already active) */
+    startSession: () => Promise<void>;
+    /** Trigger a session with optional user trigger flag */
+    triggerSession: (userTrigger?: boolean) => void;
+}
+/**
+ * Return type for useAriaSession hook
+ */
+export interface UseAriaSessionReturn {
+    /** Session information and state */
+    session: AriaSessionInfo;
+    /** Session control actions */
+    actions: AriaSessionActions;
+}
+/**
+ * Hook to access and control Aria session state.
+ *
+ * This hook provides:
+ * - Session state information (token, expiry, status)
+ * - Session control actions (end, refresh, start)
+ * - Expiry tracking utilities
+ *
+ * @example
+ * ```tsx
+ * const { session, actions } = useAriaSession();
+ *
+ * // Check session state
+ * if (session.isExpiringSoon) {
+ *   console.log('Session expiring soon, will auto-refresh');
+ * }
+ *
+ * // End session on logout
+ * const handleLogout = async () => {
+ *   await actions.endSession();
+ *   // ... rest of logout logic
+ * };
+ * ```
+ */
+export declare const useAriaSession: () => UseAriaSessionReturn;
+export default useAriaSession;
+//# sourceMappingURL=useAriaSession.d.ts.map

package/dist/hooks/useAriaSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAriaSession.d.ts","sourceRoot":"","sources":["../../src/hooks/useAriaSession.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,YAAY,EAAE,YAAY,CAAC;IAC3B,4CAA4C;IAC5C,MAAM,EAAE,oBAAoB,CAAC;IAC7B,iEAAiE;IACjE,WAAW,EAAE,OAAO,CAAC;IACrB,wFAAwF;IACxF,QAAQ,EAAE,OAAO,CAAC;IAClB,uCAAuC;IACvC,WAAW,EAAE,OAAO,CAAC;IACrB,+CAA+C;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,2CAA2C;IAC3C,SAAS,EAAE,OAAO,CAAC;IACnB,mEAAmE;IACnE,cAAc,EAAE,OAAO,CAAC;IACxB,qEAAqE;IACrE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,4CAA4C;IAC5C,cAAc,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,kDAAkD;IAClD,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,wDAAwD;IACxD,cAAc,EAAE,CAAC,WAAW,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,oCAAoC;IACpC,OAAO,EAAE,eAAe,CAAC;IACzB,8BAA8B;IAC9B,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,cAAc,QAAO,oBAyFjC,CAAC;AAEF,eAAe,cAAc,CAAC"}