@centive/aria-sdk 0.1.0 → 0.1.1

package/README.md

@@ -61,23 +61,31 @@ import { AriaProvider, AriaAssistant, AriaTriggerButton } from '@centive/aria-sd
 import '@centive/aria-sdk/styles.css';
 
 function App() {
+  // Note: Persona configuration is now handled by the backend
+  // The backend determines which persona to display based on user context
   const config = {
     websocketUrl: 'ws://localhost:8000/ws',
-    userId: 'user_123', // Required for message accumulation
+    userId: 'user_123', // Required for backend persona selection & message accumulation
     theme: 'light', // or 'dark'
-    personaConfig: {
-      name: 'Aria',
-      avatarId: 'your-avatar-id',
-      voiceId: 'your-voice-id',
-      llmId: 'your-llm-id',
-      systemPrompt: 'You are Aria, a helpful AI assistant.',
-    },
+    
+    // WebSocket event callbacks
     onWebSocketEvent: (event) => {
       console.log('Incoming WebSocket event:', event);
     },
     onError: (error) => console.error('Error:', error),
     onSessionReady: () => console.log('Session ready!'),
     onConnectionStateChange: (connected) => console.log('Connected:', connected),
+    
+    // Message accumulation callbacks
+    onMessageHistoryAck: (messageCount) => {
+      console.log(`Message history saved: ${messageCount} messages`);
+    },
+    onSessionEndAck: (savedCount) => {
+      console.log(`Session ended: ${savedCount} messages saved`);
+    },
+    onSessionEndError: (error, errorType) => {
+      console.error(`Session end failed: ${errorType} - ${error}`);
+    },
   };
 
   return (
@@ -105,14 +113,20 @@ import '@centive/aria-sdk/styles.css';
 ### 3. Set Up Backend WebSocket Server
 
 The SDK requires a backend WebSocket server that:
+- **Configures AI persona** based on user context (role, permissions, etc.)
 - Handles session token generation via Anam AI API
 - Manages WebSocket connections
 - Accumulates and persists messages
 - Handles trigger events
 
+**Important:** Persona configuration (avatar, voice, LLM, system prompt) is now controlled by the backend, not the frontend. This allows for:
+- Security: Frontend cannot manipulate AI behavior
+- Flexibility: Change personas based on user roles, context, or A/B testing
+- Centralization: Manage all persona configurations in one place
+
 See the included example servers:
-- `example-ws-server.js` - Basic WebSocket server
-- `example-server.js` - Full-featured server with message accumulation
+- `example-ws-server.js` - WebSocket server with backend persona configuration
+- `example-server.js` - HTTP server for session tokens
 
 ## 📖 Core Concepts
 
@@ -219,29 +233,53 @@ function MyComponent() {
 ```typescript
 interface AriaSDKConfig {
   websocketUrl: string;              // WebSocket server URL
-  personaConfig: PersonaConfig;      // AI persona configuration
-  userId?: string;                   // User ID for message accumulation
+  userId?: string;                   // User ID for backend persona selection & message accumulation
   theme?: 'light' | 'dark';          // Initial theme (default: 'light')
   triggerLabel?: string;             // Button label text
+  
+  // Event callbacks
   onError?: (error: Error) => void;
   onSessionReady?: () => void;
   onConnectionStateChange?: (connected: boolean) => void;
   onWebSocketEvent?: (event: any) => void;
+  
+  // Message accumulation callbacks
+  onMessageHistoryAck?: (messageCount: number) => void;
+  onMessageStreamAck?: () => void;
+  onSessionEndAck?: (savedCount: number) => void;
+  onSessionEndError?: (error: string, errorType: string) => void;
 }
 ```
 
-### PersonaConfig
+### Backend Persona Configuration
 
-```typescript
-interface PersonaConfig {
-  name: string;        // Display name
-  avatarId: string;    // Anam avatar ID
-  voiceId: string;     // Anam voice ID
-  llmId: string;       // Anam LLM ID
-  systemPrompt: string; // AI system prompt
-}
+**Persona configuration is now handled entirely by your backend server.** This provides:
+
+- **Security**: Frontend cannot manipulate AI behavior or system prompts
+- **Flexibility**: Dynamically select personas based on user roles, context, subscription tier, or A/B testing
+- **Centralization**: Manage all persona configurations in one secure location
+
+Your backend should configure personas when creating Anam sessions:
+
+```javascript
+// Backend example: Configure persona based on user context
+const getPersonaConfig = (userId, userRole) => {
+  // Your business logic here
+  return {
+    name: 'Aria - AI Assistant',
+    avatarId: 'your-avatar-id',
+    voiceId: 'your-voice-id',
+    llmId: 'your-llm-id',
+    systemPrompt: 'You are Aria, a helpful AI assistant.',
+  };
+};
+
+// Use this config when calling Anam AI API
+const personaConfig = getPersonaConfig(userId, userRole);
 ```
 
+See `example-ws-server.js` for a complete implementation.
+
 ## 🌐 WebSocket Events
 
 ### Automatic Session Trigger (Backend → Frontend)
@@ -330,10 +368,10 @@ function CustomController() {
 ### Custom Event Handling
 
 ```tsx
+// Note: Persona configuration is handled by the backend
 const config = {
   websocketUrl: 'ws://localhost:8000/ws',
-  userId: 'user_123',
-  personaConfig: { /* ... */ },
+  userId: 'user_123', // Backend uses this for persona selection
   
   onWebSocketEvent: (event) => {
     if (event.data.eventType === 'incoming_call') {
@@ -349,6 +387,26 @@ const config = {
   onError: (error) => {
     captureError(error);
   },
+  
+  // Message accumulation callbacks
+  onMessageHistoryAck: (messageCount) => {
+    console.log(`Conversation saved: ${messageCount} messages`);
+    updateUI({ messagesSaved: true });
+  },
+  
+  onSessionEndAck: (savedCount) => {
+    console.log(`Session completed: ${savedCount} messages persisted`);
+    showSuccessNotification('Conversation saved successfully');
+  },
+  
+  onSessionEndError: (error, errorType) => {
+    console.error(`Failed to save: ${errorType}`, error);
+    if (errorType === 'CIRCUIT_BREAKER_OPEN') {
+      showWarning('Saving temporarily unavailable, will retry automatically');
+    } else {
+      showError('Failed to save conversation');
+    }
+  },
 };
 ```
 
@@ -404,6 +462,8 @@ function SessionMonitor() {
 ## 📚 Documentation
 
 For more detailed documentation, see:
+- [Type Reference](./TYPE_REFERENCE.md) - Complete TypeScript type reference
+- [WebSocket Events Guide](./WEBSOCKET_EVENTS.md) - Complete WebSocket message specification
 - [WebSocket Guide](./WEBSOCKET_GUIDE.md) - WebSocket integration details
 - [Publishing Guide](./PUBLISHING_GUIDE.md) - npm publishing instructions  
 - [Setup Summary](./SETUP_SUMMARY.md) - Complete setup overview

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,KAA4B,MAAM,OAAO,CAAC;AAQjD,UAAU,eAAe;IACvB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAgOhD,CAAC"}
+{"version":3,"file":"AriaWidget.d.ts","sourceRoot":"","sources":["../../src/components/AriaWidget.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4B,MAAM,OAAO,CAAC;AAQjD,UAAU,eAAe;IACvB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CA+NhD,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,KAAmD,MAAM,OAAO,CAAC;AAExE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAK7C,UAAU,iBAAiB;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CA2dpD,CAAC"}
+{"version":3,"file":"AriaProvider.d.ts","sourceRoot":"","sources":["../../src/context/AriaProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmD,MAAM,OAAO,CAAC;AAmBxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAK7C,UAAU,iBAAiB;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAgGD,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CAugBpD,CAAC"}