@hamsa-ai/voice-agents-sdk 0.3.1 → 0.4.0-beta.1

package/README.md

@@ -1,6 +1,6 @@
 # Hamsa Voice Agents Web SDK
 
-Hamsa Voice Agents Web SDK is a JavaScript library for integrating voice agents from <https://dashboard.tryhamsa.com>. This SDK provides a seamless way to incorporate voice interactions into your web applications.
+Hamsa Voice Agents Web SDK is a JavaScript library for integrating voice agents from <https://dashboard.tryhamsa.com>. This SDK provides a seamless way to incorporate voice interactions into your web applications with high-quality real-time audio communication.
 
 ## Installation
 
@@ -17,7 +17,7 @@ npm i @hamsa-ai/voice-agents-sdk
 First, import the package in your code:
 
 ```javascript
-import { HamsaVoiceAgent } from '@hamsa-ai/voice-agents-sdk'
+import { HamsaVoiceAgent } from "@hamsa-ai/voice-agents-sdk";
 ```
 
 Initialize the SDK with your API key:
@@ -37,9 +37,11 @@ Include the script from a CDN:
 Then, you can initialize the agent like this:
 
 ```javascript
-const agent = new HamsaVoiceAgent('YOUR_API_KEY');
+const agent = new HamsaVoiceAgent("YOUR_API_KEY");
 
-agent.on("callStarted", () => { console.log("Conversation has started!"); });
+agent.on("callStarted", () => {
+	console.log("Conversation has started!");
+});
 
 // Example: Start a call
 // agent.start({ agentId: 'YOUR_AGENT_ID' });
@@ -53,11 +55,11 @@ Start a conversation with an existing agent by calling the "start" function. You
 
 ```javascript
 agent.start({
-    agentId: YOUR_AGENT_ID,
-    params: {
-        param1: "NAME",
-        param2: "NAME2"
-    }
+	agentId: YOUR_AGENT_ID,
+	params: {
+		param1: "NAME",
+		param2: "NAME2",
+	},
 });
 ```
 
@@ -92,29 +94,379 @@ During the conversation, the SDK emits events to update your application about t
 ### Conversation Status Events
 
 ```javascript
-agent.on("callStarted", () => { console.log("Conversation has started!"); });
-agent.on("callEnded", () => { console.log("Conversation has ended!"); });
-agent.on("callPaused", () => { console.log("The conversation is paused"); });
-agent.on("callResumed", () => { console.log("Conversation has resumed"); });
+agent.on("callStarted", () => {
+	console.log("Conversation has started!");
+});
+agent.on("callEnded", () => {
+	console.log("Conversation has ended!");
+});
+agent.on("callPaused", () => {
+	console.log("The conversation is paused");
+});
+agent.on("callResumed", () => {
+	console.log("Conversation has resumed");
+});
 ```
 
 ### Agent Status Events
 
 ```javascript
-agent.on("speaking", () => { console.log("The agent is speaking"); });
-agent.on("listening", () => { console.log("The agent is listening"); });
+agent.on("speaking", () => {
+	console.log("The agent is speaking");
+});
+agent.on("listening", () => {
+	console.log("The agent is listening");
+});
 ```
 
 ### Conversation Script Events
 
 ```javascript
-agent.on("transcriptionReceived", (text) => { console.log("User speech transcription received", text); });
-agent.on("answerReceived", (text) => { console.log("Agent answer received", text); });
+agent.on("transcriptionReceived", (text) => {
+	console.log("User speech transcription received", text);
+});
+agent.on("answerReceived", (text) => {
+	console.log("Agent answer received", text);
+});
 ```
 
 ### Error Events
 
 ```javascript
-agent.on("closed", () => { console.log("Conversation was closed"); });
-agent.on("error", (e) => { console.log("Error was received", e); });
+agent.on("closed", () => {
+	console.log("Conversation was closed");
+});
+agent.on("error", (e) => {
+	console.log("Error was received", e);
+});
+```
+
+### Advanced Analytics Events
+
+The SDK provides comprehensive analytics for monitoring call quality, performance, and custom agent events:
+
+```javascript
+// Real-time connection quality updates
+agent.on("connectionQualityChanged", ({ quality, participant, metrics }) => {
+	console.log(`Connection quality: ${quality}`, metrics);
+});
+
+// Periodic analytics updates (every second during calls)
+agent.on("analyticsUpdated", (analytics) => {
+	console.log("Call analytics:", analytics);
+	// Contains: connectionStats, audioMetrics, performanceMetrics, etc.
+});
+
+// Participant events
+agent.on("participantConnected", (participant) => {
+	console.log("Participant joined:", participant.identity);
+});
+
+agent.on("participantDisconnected", (participant) => {
+	console.log("Participant left:", participant.identity);
+});
+
+// Track subscription events (audio/video streams)
+agent.on("trackSubscribed", ({ track, participant, trackStats }) => {
+	console.log("New track:", track.kind, "from", participant);
+});
+
+agent.on("trackUnsubscribed", ({ track, participant }) => {
+	console.log("Track ended:", track.kind, "from", participant);
+});
+
+// Connection state changes
+agent.on("reconnecting", () => {
+	console.log("Attempting to reconnect...");
+});
+
+agent.on("reconnected", () => {
+	console.log("Successfully reconnected");
+});
+
+// Custom events from agents
+agent.on("customEvent", (eventType, eventData, metadata) => {
+	console.log(`Custom event: ${eventType}`, eventData);
+	// Examples: flow_navigation, tool_execution, agent_state_change
+});
+```
+
+## Analytics & Monitoring
+
+The SDK provides comprehensive real-time analytics for monitoring call quality, performance metrics, and custom agent events. Access analytics data through both synchronous methods and event-driven updates.
+
+### Synchronous Analytics Methods
+
+Get real-time analytics data instantly for dashboards and monitoring:
+
+```javascript
+// Connection quality and network statistics
+const connectionStats = agent.getConnectionStats();
+console.log(connectionStats);
+/*
+{
+  latency: 45,              // Network latency in ms
+  packetLoss: 0.1,         // Packet loss percentage
+  bandwidth: 128000,       // Current bandwidth usage
+  quality: 'good',         // Connection quality: excellent/good/poor/lost
+  jitter: 2,               // Network jitter
+  connectionAttempts: 1,   // Total connection attempts
+  reconnectionAttempts: 0, // Reconnection attempts
+  isConnected: true        // Current connection status
+}
+*/
+
+// Audio levels and quality metrics
+const audioLevels = agent.getAudioLevels();
+console.log(audioLevels);
+/*
+{
+  userAudioLevel: 0.8,         // Current user audio level
+  agentAudioLevel: 0.3,        // Current agent audio level
+  userSpeakingTime: 30000,     // User speaking duration (ms)
+  agentSpeakingTime: 20000,    // Agent speaking duration (ms)
+  audioDropouts: 0,            // Audio interruption count
+  echoCancellationActive: true,// Echo cancellation status
+  volume: 1.0,                 // Current volume setting
+  isPaused: false              // Pause state
+}
+*/
+
+// Performance metrics
+const performance = agent.getPerformanceMetrics();
+console.log(performance);
+/*
+{
+  responseTime: 1200,          // Total response time
+  networkLatency: 45,          // Network round-trip time
+  callDuration: 60000,         // Current call duration (ms)
+  connectionEstablishedTime: 250, // Time to establish connection
+  reconnectionCount: 0         // Number of reconnections
+}
+*/
+
+// Participant information
+const participants = agent.getParticipants();
+console.log(participants);
+/*
+[
+  {
+    identity: "agent",
+    sid: "participant-sid",
+    connectionTime: 1638360000000,
+    metadata: "agent-metadata"
+  }
+]
+*/
+
+// Track statistics (audio/video streams)
+const trackStats = agent.getTrackStats();
+console.log(trackStats);
+/*
+{
+  totalTracks: 2,
+  activeTracks: 2,
+  audioElements: 1,
+  trackDetails: [
+    ["track-id", { trackId: "track-id", kind: "audio", participant: "agent" }]
+  ]
+}
+*/
+
+// Complete analytics snapshot
+const analytics = agent.getCallAnalytics();
+console.log(analytics);
+/*
+{
+  callDuration: 60000,
+  callStartTime: 1638360000000,
+  isConnected: true,
+  isPaused: false,
+  connectionStats: { ... },
+  audioMetrics: { ... },
+  performanceMetrics: { ... },
+  participants: [ ... ],
+  trackStats: { ... },
+  callStats: { ... }
+}
+*/
+```
+
+### Real-time Dashboard Example
+
+Build live monitoring dashboards using the analytics data:
+
+```javascript
+// Update dashboard every second
+const updateDashboard = () => {
+	const stats = agent.getConnectionStats();
+	const audio = agent.getAudioLevels();
+	const performance = agent.getPerformanceMetrics();
+	
+	// Update UI elements
+	document.getElementById('latency').textContent = `${stats.latency}ms`;
+	document.getElementById('quality').textContent = stats.quality;
+	document.getElementById('duration').textContent = `${Math.floor(performance.callDuration / 1000)}s`;
+	document.getElementById('user-audio').style.width = `${audio.userAudioLevel * 100}%`;
+	document.getElementById('agent-audio').style.width = `${audio.agentAudioLevel * 100}%`;
+};
+
+// Start dashboard updates when call begins
+agent.on('callStarted', () => {
+	const dashboardInterval = setInterval(updateDashboard, 1000);
+	
+	agent.on('callEnded', () => {
+		clearInterval(dashboardInterval);
+	});
+});
+```
+
+### Custom Event Tracking
+
+Track custom events from your voice agents:
+
+```javascript
+agent.on("customEvent", (eventType, eventData, metadata) => {
+	switch(eventType) {
+		case "flow_navigation":
+			console.log("Agent navigated:", eventData.from, "->", eventData.to);
+			// Track conversation flow
+			break;
+			
+		case "tool_execution":
+			console.log("Tool called:", eventData.toolName, "Result:", eventData.success);
+			// Monitor tool usage
+			break;
+			
+		case "agent_state_change":
+			console.log("Agent state:", eventData.state);
+			// Track agent behavior
+			break;
+			
+		case "user_intent_detected":
+			console.log("User intent:", eventData.intent, "Confidence:", eventData.confidence);
+			// Analyze user intent
+			break;
+			
+		default:
+			console.log("Custom event:", eventType, eventData);
+	}
+});
 ```
+
+## Configuration Options
+
+The SDK accepts optional configuration parameters:
+
+```javascript
+const agent = new HamsaVoiceAgent("YOUR_API_KEY", {
+	API_URL: "https://api.tryhamsa.com", // API endpoint (default)
+});
+```
+
+## Client-Side Tools
+
+You can register client-side tools that the agent can call during conversations:
+
+```javascript
+const tools = [
+	{
+		function_name: "getUserInfo",
+		description: "Get user information",
+		parameters: [
+			{
+				name: "userId",
+				type: "string",
+				description: "User ID to look up",
+			},
+		],
+		required: ["userId"],
+		fn: async (userId) => {
+			// Your tool implementation
+			const userInfo = await fetchUserInfo(userId);
+			return userInfo;
+		},
+	},
+];
+
+agent.start({
+	agentId: "YOUR_AGENT_ID",
+	tools: tools,
+	voiceEnablement: true,
+});
+```
+
+## Migration from Previous Versions
+
+If you're upgrading from a previous version, see the [Migration Guide](./MIGRATION_GUIDE.md) for detailed instructions. Connection details are now automatically managed and no longer need to be configured.
+
+## Browser Compatibility
+
+This SDK supports modern browsers with WebRTC capabilities:
+
+-   Chrome 60+
+-   Firefox 60+
+-   Safari 12+
+-   Edge 79+
+
+## TypeScript Support
+
+The SDK includes comprehensive TypeScript definitions with detailed analytics interfaces:
+
+```typescript
+import { HamsaVoiceAgent } from "@hamsa-ai/voice-agents-sdk";
+
+// All analytics methods return strongly typed data
+const agent = new HamsaVoiceAgent("API_KEY");
+
+// TypeScript will provide autocomplete and type checking
+agent.on("analyticsUpdated", (analytics: CallAnalytics) => {
+    console.log(analytics.connectionStats.latency); // number
+    console.log(analytics.audioMetrics.userAudioLevel); // number
+    console.log(analytics.performanceMetrics.callDuration); // number
+});
+
+// Strongly typed custom events
+agent.on("customEvent", (eventType: string, eventData: any, metadata: CustomEventMetadata) => {
+    console.log(metadata.timestamp); // number
+    console.log(metadata.participant); // string
+});
+```
+
+## Use Cases
+
+### Real-time Call Quality Monitoring
+```javascript
+agent.on("connectionQualityChanged", ({ quality, metrics }) => {
+    if (quality === 'poor') {
+        showNetworkWarning();
+        logQualityIssue(metrics);
+    }
+});
+```
+
+### Analytics Dashboard
+```javascript
+const analytics = agent.getCallAnalytics();
+sendToAnalytics({
+    callDuration: analytics.callDuration,
+    audioQuality: analytics.audioMetrics,
+    participantCount: analytics.participants.length,
+    performance: analytics.performanceMetrics
+});
+```
+
+### Conversation Flow Analysis
+```javascript
+agent.on("customEvent", (eventType, data) => {
+    if (eventType === "flow_navigation") {
+        trackConversationFlow(data.from, data.to);
+        optimizeAgentResponses(data);
+    }
+});
+```
+
+## Dependencies
+
+-   **livekit-client**: Real-time communication infrastructure
+-   **events**: EventEmitter for browser compatibility