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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hamsa-ai/voice-agents-sdk",
-  "version": "0.4.0-beta.9",
+  "version": "0.4.1-beta.1",
   "description": "Hamsa AI - Voice Agents JavaScript SDK",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -26,7 +26,8 @@
     "build": "npm run clean && npm run build:types && npm run build:rollup",
     "test": "jest",
     "test:watch": "jest --watch",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "tag:push": "VERSION=$(node -p \"require('./package.json').version\") && TAG=v$VERSION && git fetch --tags -q && if git rev-parse -q --verify \"refs/tags/$TAG\" >/dev/null; then echo \"Tag $TAG already exists locally.\"; else git tag -a \"$TAG\" -m \"Release $TAG\"; fi && if git ls-remote --exit-code --tags origin \"$TAG\" >/dev/null 2>&1; then echo \"Tag $TAG already exists on origin.\"; else git push origin \"$TAG\"; fi && echo \"Done: $TAG\""
   },
   "author": "Hamsa AI Inc.",
   "license": "MIT",

package/types/classes/livekit-analytics.d.ts

@@ -166,6 +166,22 @@ export declare class LiveKitAnalytics extends EventEmitter {
     private room;
     /** Current connection state flag for controlling analytics collection */
     private isConnected;
+    /** Last recorded user audio level for dropout detection */
+    private lastUserAudioLevel;
+    /** Last recorded agent audio level for dropout detection */
+    private lastAgentAudioLevel;
+    /** Timestamp when user audio level dropped below threshold */
+    private userDropoutStartTime;
+    /** Timestamp when agent audio level dropped below threshold */
+    private agentDropoutStartTime;
+    /** Timestamp when user started speaking (VAD-based) */
+    private vadUserSpeakStart;
+    /** Timestamp when agent started speaking (VAD-based) */
+    private vadAgentSpeakStart;
+    /** Timestamp when user input was detected (for response time measurement) */
+    private lastUserInputTime;
+    /** Previous connection quality for jitter change detection (internal) */
+    private previousConnectionQuality;
     /**
      * Creates a new LiveKitAnalytics instance
      *
@@ -346,7 +362,7 @@ export declare class LiveKitAnalytics extends EventEmitter {
      */
     handleAudioPlaybackChanged(playing: boolean): void;
     /**
-     * Gets current connection statistics
+     * Gets current connection statistics (customer-facing - verified data only)
      */
     getConnectionStats(): ConnectionStatsResult;
     /**
@@ -354,15 +370,57 @@ export declare class LiveKitAnalytics extends EventEmitter {
      */
     getAudioLevels(): AudioLevelsResult;
     /**
-     * Gets current performance metrics
+     * Gets current performance metrics (customer-facing - verified data only)
      */
     getPerformanceMetrics(): PerformanceMetricsResult;
     /**
-     * Gets comprehensive call analytics
+     * Manually records response time for agent interactions
+     *
+     * @param responseTime - Response time in milliseconds
+     *
+     * @example
+     * ```typescript
+     * // Record custom response time measurement
+     * const startTime = Date.now();
+     * // ... agent processing ...
+     * const responseTime = Date.now() - startTime;
+     * analytics.recordResponseTime(responseTime);
+     * ```
+     */
+    recordResponseTime(responseTime: number): void;
+    /**
+     * Gets current voice activity detection thresholds
+     */
+    getVADSettings(): {
+        audioThreshold: number;
+        minSpeakingDuration: number;
+        dropoutThreshold: number;
+        dropoutDetectionDuration: number;
+    };
+    /**
+     * Gets comprehensive call analytics (customer-facing - verified data only)
      */
     getCallAnalytics(participants: ParticipantData[], trackStats: TrackStatsResult, volume: number, isPaused: boolean): CallAnalyticsResult & {
         callDuration: number;
     };
+    /**
+     * Gets full connection statistics including estimated metrics (internal use only)
+     * @internal
+     */
+    getInternalConnectionStats(): ConnectionMetrics & {
+        connectionAttempts: number;
+        reconnectionAttempts: number;
+        connectionEstablishedTime: number;
+        isConnected: boolean;
+    };
+    /**
+     * Gets full performance metrics including estimated network latency (internal use only)
+     * @internal
+     */
+    getInternalPerformanceMetrics(): PerformanceMetrics & {
+        callDuration: number;
+        averageResponseTime: number;
+    };
     /**
      * Cleans up analytics resources
      */

package/types/classes/livekit-manager.d.ts

@@ -314,14 +314,14 @@ export default class LiveKitManager extends EventEmitter {
     /**
      * Retrieves current network connection statistics and quality metrics
      *
-     * @returns Object containing latency, packet loss, bandwidth, quality rating, and connection counts
+     * @returns Object containing connection quality, connection counts, and timing data
      *
      * @example
      * ```typescript
      * const stats = manager.getConnectionStats();
-     * console.log(`Latency: ${stats.latency}ms`);
-     * console.log(`Packet loss: ${stats.packetLoss}%`);
      * console.log(`Connection quality: ${stats.quality}`);
+     * console.log(`Connection attempts: ${stats.connectionAttempts}`);
+     * console.log(`Reconnections: ${stats.reconnectionAttempts}`);
      *
      * if (stats.quality === 'poor') {
      *   showNetworkWarning();
@@ -354,7 +354,7 @@ export default class LiveKitManager extends EventEmitter {
     /**
      * Retrieves current performance metrics including response times and call duration
      *
-     * @returns Object containing response times, network latency, call duration, and connection timing
+     * @returns Object containing response times, call duration, and connection timing
      *
      * @example
      * ```typescript
@@ -442,7 +442,7 @@ export default class LiveKitManager extends EventEmitter {
      * });
      *
      * // Check for quality issues
-     * if (analytics.connectionStats.packetLoss > 5) {
+     * if (analytics.connectionStats.quality === 'poor') {
      *   reportNetworkIssue(analytics.connectionStats);
      * }
      * ```

package/types/classes/livekit-tool-registry.d.ts

@@ -178,7 +178,7 @@
  * - Includes automatic cleanup and resource management
  */
 import { EventEmitter } from 'events';
-import { type Room } from 'livekit-client';
+import type { Room } from 'livekit-client';
 import type { Tool } from './types';
 /**
  * LiveKitToolRegistry class for client-side tool management and RPC handling
@@ -445,71 +445,6 @@ export declare class LiveKitToolRegistry extends EventEmitter {
         text?: string;
         final?: boolean;
     }>): void;
-    /**
-     * Provides access to the local microphone audio stream for external processing
-     *
-     * Retrieves the local participant's microphone track and creates a MediaStream
-     * for external audio processing applications. This enables advanced integrations
-     * such as real-time audio analysis, recording, or additional audio effects
-     * processing outside of the LiveKit pipeline.
-     *
-     * @fires localAudioStreamAvailable When local audio stream is successfully extracted
-     *
-     * @example
-     * ```typescript
-     * // Listen for local audio stream availability
-     * registry.on('localAudioStreamAvailable', (stream) => {
-     *   console.log('Local audio stream is available');
-     *
-     *   // Set up real-time audio analysis
-     *   const audioAnalyzer = new AudioAnalyzer(stream);
-     *   audioAnalyzer.on('volumeLevel', (level) => {
-     *     updateVolumeIndicator(level);
-     *   });
-     *
-     *   // Enable noise gate functionality
-     *   const noiseGate = new NoiseGate(stream);
-     *   noiseGate.threshold = -40; // dB
-     *
-     *   // Record conversation for quality assurance
-     *   if (recordingEnabled) {
-     *     const mediaRecorder = new MediaRecorder(stream);
-     *     mediaRecorder.start();
-     *
-     *     mediaRecorder.ondataavailable = (event) => {
-     *       saveAudioChunk(event.data);
-     *     };
-     *   }
-     * });
-     *
-     * // Call after connection is established
-     * registry.emitLocalAudioStream();
-     * ```
-     *
-     * @example Audio Processing Pipeline
-     * ```typescript
-     * registry.on('localAudioStreamAvailable', (stream) => {
-     *   // Create audio context for advanced processing
-     *   const audioContext = new AudioContext();
-     *   const source = audioContext.createMediaStreamSource(stream);
-     *
-     *   // Add audio effects
-     *   const gainNode = audioContext.createGain();
-     *   const filterNode = audioContext.createBiquadFilter();
-     *
-     *   // Connect processing chain
-     *   source.connect(gainNode);
-     *   gainNode.connect(filterNode);
-     *   filterNode.connect(audioContext.destination);
-     *
-     *   // Configure effects
-     *   gainNode.gain.value = 1.2;
-     *   filterNode.type = 'highpass';
-     *   filterNode.frequency.value = 80;
-     * });
-     * ```
-     */
-    emitLocalAudioStream(): void;
     /**
      * Returns the count of currently registered tools
      *

package/types/classes/types.d.ts

@@ -98,18 +98,18 @@ export type CallStats = {
 };
 /**
  * Real-time network connection quality metrics.
- * Provides detailed information about network performance and reliability.
+ * Internal structure includes estimated values for future use.
  */
 export type ConnectionMetrics = {
-    /** Current network latency in milliseconds */
+    /** Current network latency in milliseconds (internal - estimated) */
     latency: number;
-    /** Packet loss percentage (0.0 to 100.0) */
+    /** Packet loss percentage (internal - estimated) */
     packetLoss: number;
-    /** Current bandwidth usage in bytes per second */
+    /** Current bandwidth usage in bytes per second (internal - estimated) */
     bandwidth: number;
     /** Qualitative assessment of connection ('excellent', 'good', 'poor', 'lost') */
     quality: string;
-    /** Network jitter measurement in milliseconds */
+    /** Network jitter measurement in milliseconds (internal - estimated) */
     jitter: number;
 };
 /**
@@ -132,12 +132,12 @@ export type AudioMetrics = {
 };
 /**
  * Performance metrics tracking response times and connection reliability.
- * Measures various aspects of system and network performance.
+ * Internal structure includes estimated network latency for future use.
  */
 export type PerformanceMetrics = {
     /** Total response time for agent interactions in milliseconds */
     responseTime: number;
-    /** Current network latency measurement in milliseconds */
+    /** Current network latency measurement in milliseconds (internal - estimated) */
     networkLatency: number;
     /** Time taken to establish the initial connection in milliseconds */
     connectionEstablishedTime: number;
@@ -146,19 +146,11 @@ export type PerformanceMetrics = {
 };
 /**
  * Complete connection statistics result returned by getConnectionStats().
- * Combines real-time metrics with historical connection data.
+ * Only includes verified data - no estimated metrics exposed to customers.
  */
 export type ConnectionStatsResult = {
-    /** Current network latency in milliseconds */
-    latency: number;
-    /** Current packet loss percentage */
-    packetLoss: number;
-    /** Current bandwidth usage in bytes per second */
-    bandwidth: number;
-    /** Current connection quality assessment */
+    /** Current connection quality assessment from LiveKit */
     quality: string;
-    /** Current network jitter in milliseconds */
-    jitter: number;
     /** Total connection attempts made */
     connectionAttempts: number;
     /** Total reconnection attempts made */
@@ -196,13 +188,11 @@ export type AudioLevelsResult = {
 };
 /**
  * Complete performance metrics result returned by getPerformanceMetrics().
- * Provides comprehensive system and network performance data.
+ * Only includes verified performance data - no estimated metrics exposed.
  */
 export type PerformanceMetricsResult = {
     /** Total response time in milliseconds */
     responseTime: number;
-    /** Current network latency in milliseconds */
-    networkLatency: number;
     /** Connection establishment time in milliseconds */
     connectionEstablishedTime: number;
     /** Total reconnection count */
@@ -264,10 +254,8 @@ export type ConnectionQualityData = {
     quality: ConnectionQuality;
     /** Identity of the participant this quality measurement applies to */
     participant: string;
-    /** Detailed connection metrics including latency, packet loss, etc. */
+    /** Connection quality string from LiveKit (estimated metrics available internally) */
     metrics: {
-        latency: number;
-        packetLoss: number;
         quality: string;
     };
 };

package/types/main.d.ts

@@ -1,6 +1,16 @@
 import { EventEmitter } from 'events';
+import type { Room } from 'livekit-client';
 import LiveKitManager, { type AudioLevelsResult, type CallAnalyticsResult, type ConnectionStatsResult, type ParticipantData, type PerformanceMetricsResult, type TrackStatsResult } from './classes/livekit-manager';
 import ScreenWakeLock from './classes/screen-wake-lock';
+/**
+ * Custom error class that includes both human-readable message and machine-readable messageKey
+ * for internationalization and programmatic error handling
+ */
+declare class HamsaApiError extends Error {
+    /** Machine-readable error key for i18n or programmatic handling */
+    readonly messageKey?: string;
+    constructor(message: string, messageKey?: string);
+}
 /**
  * Configuration options for the HamsaVoiceAgent constructor
  * Allows customization of API endpoints and other global settings
@@ -164,6 +174,32 @@ type JobDetails = {
  * // Get analytics snapshot anytime
  * const analytics = agent.getCallAnalytics();
  * ```
+ *
+ * @example Track-based Audio Processing
+ * ```typescript
+ * // Handle incoming audio tracks from voice agent
+ * agent.on('trackSubscribed', ({ track, publication, participant }) => {
+ *   if (track.kind === 'audio') {
+ *     // Option 1: Attach to DOM element (LiveKit way)
+ *     track.attach(audioElement);
+ *
+ *     // Option 2: Create MediaStream for custom processing
+ *     const stream = new MediaStream([track.mediaStreamTrack]);
+ *     const audioContext = new AudioContext();
+ *     const source = audioContext.createMediaStreamSource(stream);
+ *     // Add custom audio processing...
+ *   }
+ * });
+ *
+ * // Handle local audio track availability
+ * agent.on('localTrackPublished', ({ track, publication }) => {
+ *   if (track && track.source === 'microphone') {
+ *     // Access local microphone track for recording/analysis
+ *     const stream = new MediaStream([track.mediaStreamTrack]);
+ *     setupVoiceAnalyzer(stream);
+ *   }
+ * });
+ * ```
  */
 declare class HamsaVoiceAgent extends EventEmitter {
     #private;
@@ -181,6 +217,8 @@ declare class HamsaVoiceAgent extends EventEmitter {
     jobId: string | null;
     /** Screen wake lock manager to prevent device sleep during calls */
     wakeLockManager: ScreenWakeLock;
+    /** Flag to track if the user initiated the call end */
+    private userInitiatedEnd;
     /**
      * Creates a new HamsaVoiceAgent instance
      *
@@ -710,6 +748,41 @@ declare class HamsaVoiceAgent extends EventEmitter {
      * ```
      */
     getCallAnalytics(): CallAnalyticsResult | null;
+    /**
+     * Gets the LiveKit Room instance for React SDK integration
+     *
+     * Provides access to the underlying LiveKit Room object for use with
+     * LiveKit React components. This enables integration with the broader
+     * LiveKit React ecosystem while maintaining the benefits of the
+     * HamsaVoiceAgent abstraction.
+     *
+     * @internal - For use by @hamsa-ai/voice-agents-react only
+     * @returns LiveKit Room instance or null if not connected
+     *
+     * @example React SDK Integration
+     * ```typescript
+     * import { RoomContext } from '@livekit/components-react';
+     *
+     * function VoiceProvider({ agent, children }) {
+     *   const [room, setRoom] = useState(null);
+     *
+     *   useEffect(() => {
+     *     agent.on('callStarted', () => {
+     *       setRoom(agent.getRoom());
+     *     });
+     *   }, [agent]);
+     *
+     *   if (!room) return children;
+     *
+     *   return (
+     *     <RoomContext.Provider value={room}>
+     *       {children}
+     *     </RoomContext.Provider>
+     *   );
+     * }
+     * ```
+     */
+    getRoom(): Room | null;
 }
-export { HamsaVoiceAgent };
+export { HamsaVoiceAgent, HamsaApiError };
 export default HamsaVoiceAgent;