@centive/aria-sdk 0.9.0 → 0.9.2

package/README.md

@@ -122,9 +122,78 @@ The SDK connects to your backend via WebSocket. Your backend handles:
 1. **User Authentication** - Validate the connecting user
 2. **Session Token Generation** - Create Anam AI sessions
 3. **Persona Configuration** - Control AI behavior server-side (avatar, voice, LLM, system prompt)
+4. **Message Storage** - Store conversation history (optional)
+
+### Messages from SDK to Backend
+
+#### 1. Session Request (user_trigger)
+
+Sent when user opens the widget to request a new session token.
+
+```json
+{
+  "user_trigger": true,
+  "userId": "user_123",
+  "skip_greeting": true  // true after first session (to skip greeting on reopen)
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `user_trigger` | boolean | Always `true` when requesting a session |
+| `userId` | string | User identifier passed to `Aria.init()` |
+| `skip_greeting` | boolean | `true` if user has already had a session (skip greeting on subsequent opens) |
+
+#### 2. Message History
+
+Sent when conversation messages are updated.
+
+```json
+{
+  "type": "message_history",
+  "session_id": "anam_session_abc123",
+  "user_id": "user_123",
+  "messages": [
+    { "role": "persona", "content": "Hello! How can I help?", "timestamp": "2026-01-29T12:00:00.000Z" },
+    { "role": "user", "content": "I need help with my account", "timestamp": "2026-01-29T12:00:05.000Z" }
+  ]
+}
+```
+
+#### 3. Message Stream
+
+Sent for real-time message streaming (as user/persona speaks).
+
+```json
+{
+  "type": "message_stream",
+  "session_id": "anam_session_abc123",
+  "user_id": "user_123",
+  "message": {
+    "role": "user",
+    "content": "partial transcript...",
+    "timestamp": "2026-01-29T12:00:05.000Z",
+    "is_final": false
+  }
+}
+```
+
+#### 4. Session End
+
+Sent when user closes the widget (hangs up).
+
+```json
+{
+  "type": "session_end",
+  "session_id": "anam_session_abc123",
+  "user_id": "user_123"
+}
+```
 
 ### Expected Response Format
 
+#### Session Token Response
+
 ```json
 {
   "status": "success",
@@ -138,6 +207,19 @@ The SDK connects to your backend via WebSocket. Your backend handles:
 }
 ```
 
+#### Message Acknowledgments (Optional)
+
+```json
+// Message history acknowledgment
+{ "status": "ok", "type": "message_history_ack", "message_count": 5 }
+
+// Message stream acknowledgment (for is_final: true)
+{ "status": "ok", "type": "message_stream_ack" }
+
+// Session end acknowledgment
+{ "status": "ok", "type": "session_end_ack", "message": "Session ended", "saved_count": 10 }
+```
+
 ### Backend Example (Node.js)
 
 ```javascript
@@ -150,40 +232,94 @@ wss.on('connection', (ws) => {
   ws.on('message', async (message) => {
     const data = JSON.parse(message);
     
+    // Handle session request
     if (data.user_trigger !== undefined) {
-      const session = await createAnamSession(data.userId);
+      const startTime = Date.now();
+      const session = await createAnamSession(data.userId, data.skip_greeting);
       
       ws.send(JSON.stringify({
         status: 'success',
         message: 'Session created',
         session_data: {
           session_id: session.id,
-          token: session.token,
+          token: session.sessionToken,
           expires_at: session.expiresAt,
         },
         time_taken: Date.now() - startTime,
       }));
     }
+    
+    // Handle message history (store in database)
+    if (data.type === 'message_history') {
+      await storeMessages(data.session_id, data.user_id, data.messages);
+      ws.send(JSON.stringify({
+        status: 'ok',
+        type: 'message_history_ack',
+        message_count: data.messages.length,
+      }));
+    }
+    
+    // Handle session end
+    if (data.type === 'session_end') {
+      await finalizeSession(data.session_id, data.user_id);
+      ws.send(JSON.stringify({
+        status: 'ok',
+        type: 'session_end_ack',
+        message: 'Session ended',
+        saved_count: 10,
+      }));
+    }
   });
 });
 
-async function createAnamSession(userId) {
-  const response = await axios.post('https://api.anam.ai/v1/sessions', {
-    persona: {
-      name: 'Aria',
-      avatarId: 'your-avatar-id',
-      voiceId: 'your-voice-id',
-      llmId: 'your-llm-id',
-      systemPrompt: 'You are Aria, a helpful AI assistant.',
+async function createAnamSession(userId, skipGreeting = false) {
+  const response = await axios.post(
+    'https://api.anam.ai/v1/auth/session-token',
+    {
+      personaConfig: {
+        name: 'Aria',
+        avatarId: 'your-avatar-id',
+        voiceId: 'your-voice-id',
+        llmId: 'your-llm-id',
+        systemPrompt: 'You are Aria, a helpful AI assistant.',
+        skip_greeting: skipGreeting,  // Pass skip_greeting to Anam
+      },
     },
-  }, {
-    headers: { 'Authorization': `Bearer ${process.env.ANAM_API_KEY}` }
-  });
+    {
+      headers: { 'Authorization': `Bearer ${process.env.ANAM_API_KEY}` },
+    }
+  );
   
   return response.data;
 }
+
+async function storeMessages(sessionId, userId, messages) {
+  // Store messages in your database
+  console.log(`Storing ${messages.length} messages for user ${userId}`);
+}
+
+async function finalizeSession(sessionId, userId) {
+  // Mark session as complete, perform any cleanup
+  console.log(`Session ${sessionId} ended for user ${userId}`);
+}
 ```
 
+## Session Lifecycle
+
+The SDK manages Anam sessions automatically:
+
+| Event | What Happens |
+|-------|--------------|
+| **Widget Opens (first time)** | Sends `user_trigger` with `skip_greeting: false` → Creates Anam session with greeting |
+| **Widget Closes (hang up)** | Sends `session_end` → Ends Anam session to free resources |
+| **Widget Reopens** | Sends `user_trigger` with `skip_greeting: true` → Creates new session without greeting |
+| **Page Refresh** | Sends `user_trigger` with `skip_greeting: false` → Fresh session with greeting |
+
+This ensures:
+- Anam resources are freed when the widget is closed
+- Users don't hear the greeting repeatedly when reopening the widget
+- Conversation context can be restored via your backend's message storage
+
 ## Session Persistence
 
 For video sessions to persist across page navigation, initialize the SDK at the **root level** of your application:

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

@@ -1 +1 @@
-{"version":3,"file":"AriaStandaloneUI.d.ts","sourceRoot":"","sources":["../../src/components/AriaStandaloneUI.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAA4C,KAAK,EAAE,EAAE,MAAM,OAAO,CAAC;AAgB1E,OAAO,KAAK,EAOV,KAAK,EACN,MAAM,SAAS,CAAC;AAOjB,UAAU,qBAAqB;IAC7B,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,WAAW,CAAC;CACxB;AAED,eAAO,MAAM,gBAAgB,EAAE,EAAE,CAAC,qBAAqB,CAmhBtD,CAAC;AA45BF,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"AriaStandaloneUI.d.ts","sourceRoot":"","sources":["../../src/components/AriaStandaloneUI.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAA4C,KAAK,EAAE,EAAE,MAAM,OAAO,CAAC;AAgB1E,OAAO,KAAK,EAOV,KAAK,EACN,MAAM,SAAS,CAAC;AAOjB,UAAU,qBAAqB;IAC7B,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,WAAW,CAAC;CACxB;AAED,eAAO,MAAM,gBAAgB,EAAE,EAAE,CAAC,qBAAqB,CAmjBtD,CAAC;AA45BF,eAAe,gBAAgB,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;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,CAmmB9C,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,CA+nB9C,CAAC"}