@hamsa-ai/voice-agents-sdk 0.5.1 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hamsa-ai/voice-agents-sdk",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Hamsa AI - Voice Agents JavaScript SDK",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",

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

@@ -182,6 +182,8 @@ export declare class LiveKitAnalytics extends EventEmitter {
     private lastUserInputTime;
     /** Previous connection quality for jitter change detection (internal) */
     private previousConnectionQuality;
+    /** Debug logger instance for conditional logging */
+    private readonly logger;
     /**
      * Creates a new LiveKitAnalytics instance
      *
@@ -203,7 +205,7 @@ export declare class LiveKitAnalytics extends EventEmitter {
      * analytics.startAnalyticsCollection();
      * ```
      */
-    constructor();
+    constructor(debug?: boolean);
     /**
      * Sets the LiveKit room reference for analytics data collection
      *

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

@@ -154,7 +154,7 @@
  * - Manages DOM element lifecycle to prevent memory leaks
  */
 import { EventEmitter } from 'events';
-import { type RemoteParticipant, type RemoteTrack, type RemoteTrackPublication, type Room } from 'livekit-client';
+import { type LocalTrack, type LocalTrackPublication, type Participant, type RemoteParticipant, type RemoteTrack, type RemoteTrackPublication, type Room, Track, type TrackPublication } from 'livekit-client';
 import type { AudioCaptureOptions, TrackStatsData, TrackStatsResult } from './types';
 /**
  * LiveKitAudioManager class for comprehensive audio stream management
@@ -181,8 +181,14 @@ export declare class LiveKitAudioManager extends EventEmitter {
     private audioCaptureOptions;
     private readonly recorders;
     private readonly processors;
+    private readonly sourceNodes;
+    /** Map of track IDs to cloned MediaStreamTracks for capture */
+    private readonly clonedTracks;
     /** Map of track IDs to their capture state */
     private readonly trackCaptureMap;
+    /** Debug logger instance for conditional logging */
+    private readonly logger;
+    constructor(debug?: boolean);
     /**
      * Provides the LiveKit Room to the audio manager for microphone control.
      */
@@ -459,6 +465,13 @@ export declare class LiveKitAudioManager extends EventEmitter {
      * ```
      */
     handleTrackSubscribed(track: RemoteTrack, publication: RemoteTrackPublication, participant: RemoteParticipant): void;
+    /**
+     * Processes local audio track publications
+     * @param track - The local audio track
+     * @param publication - Local track publication metadata
+     * @param participant - The local participant who published the track
+     */
+    handleLocalTrackPublished(track: LocalTrack, publication: LocalTrackPublication, participant: Participant): void;
     /**
      * Processes audio track unsubscription and cleanup
      *
@@ -495,7 +508,14 @@ export declare class LiveKitAudioManager extends EventEmitter {
      * });
      * ```
      */
-    handleTrackUnsubscribed(track: RemoteTrack, publication: RemoteTrackPublication, participant: RemoteParticipant): void;
+    handleTrackUnsubscribed(track: Track, publication: TrackPublication, participant: Participant): void;
+    /**
+     * Processes local audio track unpublications
+     * @param track - The local audio track
+     * @param publication - Local track publication metadata
+     * @param participant - The local participant who unpublished the track
+     */
+    handleLocalTrackUnsubscribed(track: LocalTrack, publication: LocalTrackPublication, participant: Participant): void;
     /**
      * Pauses playback of all active audio streams
      *
@@ -780,6 +800,11 @@ export declare class LiveKitAudioManager extends EventEmitter {
      * ```
      */
     enableAudioCapture(options: AudioCaptureOptions): void;
+    /**
+     * Internal state for AudioWorklet registration to prevent race conditions
+     * @private
+     */
+    private workletReady;
     /**
      * Disables audio capture and cleans up all capture resources
      *

package/types/classes/types.d.ts

@@ -1,7 +1,7 @@
 /**
  * Shared types and interfaces for LiveKit modules
  */
-import type { ConnectionQuality, RemoteTrack, RemoteTrackPublication } from 'livekit-client';
+import type { ConnectionQuality, Track, TrackPublication } from 'livekit-client';
 /**
  * Agent state as defined by LiveKit
  * Represents the current state of the voice agent
@@ -62,7 +62,7 @@ export type TrackStatsData = {
     /** Unix timestamp when this track was subscribed to */
     subscriptionTime: number;
     /** LiveKit track publication object containing track details */
-    publication: RemoteTrackPublication;
+    publication: TrackPublication;
     /** Track source (microphone, screen_share, etc.) */
     source?: string;
     /** Whether the track is currently muted */
@@ -270,9 +270,9 @@ export type ConnectionQualityData = {
  */
 export type TrackSubscriptionData = {
     /** The LiveKit track object that was subscribed to */
-    track: RemoteTrack;
+    track: Track;
     /** The track publication containing metadata */
-    publication: RemoteTrackPublication;
+    publication: TrackPublication;
     /** Identity of the participant who owns this track */
     participant: string;
     /** Optional statistics about this track subscription */
@@ -284,9 +284,9 @@ export type TrackSubscriptionData = {
  */
 export type TrackUnsubscriptionData = {
     /** The LiveKit track object that was unsubscribed from */
-    track: RemoteTrack;
+    track: Track;
     /** The track publication that was removed */
-    publication: RemoteTrackPublication;
+    publication: TrackPublication;
     /** Identity of the participant who owned this track */
     participant: string;
 };
@@ -336,6 +336,8 @@ export type AudioCaptureMetadata = {
     timestamp: number;
     /** Track ID associated with this audio */
     trackId: string;
+    /** Source of this specific track (e.g. 'microphone', 'screen_share') */
+    trackSource?: string;
     /** Audio format of this chunk */
     format: AudioCaptureFormat;
     /** Sample rate in Hz (for PCM formats) */
@@ -353,6 +355,9 @@ export type AudioCaptureCallback = (audioData: ArrayBuffer | Float32Array | Int1
 export type AudioCaptureOptions = {
     /** Source of audio to capture (default: 'agent') */
     source?: AudioCaptureSource;
+    /** Specific track source to capture (default: 'microphone').
+     * Set to 'all' to capture everything including screen share audio. */
+    trackSourceFilter?: 'microphone' | 'screen_share' | 'all';
     /** Audio format to deliver (default: 'opus-webm') */
     format?: AudioCaptureFormat;
     /** Chunk size in milliseconds for encoded formats (default: 100ms) */
@@ -403,3 +408,8 @@ export type LiveKitAgentMetadata = {
     voiceAgentId: string;
     apiKey: string;
 };
+/**
+ * Valid DTMF (Dual-Tone Multi-Frequency) digits that can be sent during a call.
+ * Includes digits 0-9, asterisk (*), and pound (#) characters.
+ */
+export type DTMFDigit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '*' | '#';

package/types/main.d.ts

@@ -2,9 +2,9 @@ import { EventEmitter } from 'events';
 import type { ConnectionState, LocalTrack, LocalTrackPublication, Participant, RemoteParticipant, RemoteTrack, Room } from 'livekit-client';
 import LiveKitManager, { type AgentState, type AudioLevelsResult, type CallAnalyticsResult, type ConnectionStatsResult, type ParticipantData, type PerformanceMetricsResult, type TrackStatsResult } from './classes/livekit-manager';
 import ScreenWakeLock from './classes/screen-wake-lock';
-import type { AudioCaptureCallback, AudioCaptureOptions, ConnectionQualityData, TrackSubscriptionData, TrackUnsubscriptionData } from './classes/types';
+import type { AudioCaptureCallback, AudioCaptureOptions, ConnectionQualityData, DTMFDigit, TrackSubscriptionData, TrackUnsubscriptionData } from './classes/types';
 export type { AgentState } from './classes/livekit-manager';
-export type { AudioCaptureCallback, AudioCaptureFormat, AudioCaptureMetadata, AudioCaptureOptions, AudioCaptureSource, } from './classes/types';
+export type { AudioCaptureCallback, AudioCaptureFormat, AudioCaptureMetadata, AudioCaptureOptions, AudioCaptureSource, DTMFDigit, } from './classes/types';
 /**
  * Custom error class that includes both human-readable message and machine-readable messageKey
  * for internationalization and programmatic error handling
@@ -190,6 +190,8 @@ type HamsaVoiceAgentEvents = {
     listening: () => void;
     /** Emitted when agent state changes (idle, initializing, listening, thinking, speaking) */
     agentStateChanged: (state: AgentState) => void;
+    /** Emitted when a DTMF digit is successfully sent */
+    dtmfSent: (digit: DTMFDigit) => void;
     /** Emitted when an error occurs */
     error: (error: Error | HamsaApiError) => void;
     /** Emitted when a remote track is subscribed */
@@ -550,6 +552,73 @@ declare class HamsaVoiceAgent extends EventEmitter {
      * ```
      */
     sendContextualUpdate(context: string): void;
+    /**
+     * Sends a DTMF (Dual-Tone Multi-Frequency) digit to the voice agent
+     *
+     * Simulates pressing a key on a phone keypad during the call. This enables
+     * browser-based call testing with DTMF input simulation, allowing users to
+     * test IVR flows and DTMF transitions without making actual phone calls.
+     *
+     * The DTMF digit is sent through the LiveKit data channel to the server,
+     * which processes it as a DTMF input event that can trigger DTMF transitions
+     * in the agent flow.
+     *
+     * @param digit - A single DTMF digit: '0'-'9', '*', or '#'
+     * @throws {Error} If called when not connected (no active call)
+     * @throws {Error} If the digit is not a valid DTMF character
+     * @fires dtmfSent When a DTMF digit is successfully sent to the agent
+     *
+     * @example Basic usage
+     * ```typescript
+     * const agent = new HamsaVoiceAgent(apiKey, config);
+     * await agent.start({ agentId, params });
+     *
+     * // Listen for DTMF send confirmations
+     * agent.on('dtmfSent', (digit) => {
+     *   console.log(`Sent DTMF digit: ${digit}`);
+     *   highlightKeypadButton(digit);
+     * });
+     *
+     * // Later, when user presses a key on the UI keypad:
+     * agent.sendDTMF('1');  // Simulates pressing "1"
+     * agent.sendDTMF('*');  // Simulates pressing "*"
+     * agent.sendDTMF('#');  // Simulates pressing "#"
+     * ```
+     *
+     * @example With UI keypad
+     * ```typescript
+     * // Create keypad buttons
+     * const digits = ['1', '2', '3', '4', '5', '6', '7', '8', '9', '*', '0', '#'];
+     *
+     * digits.forEach(digit => {
+     *   const button = document.createElement('button');
+     *   button.textContent = digit;
+     *   button.onclick = () => {
+     *     try {
+     *       agent.sendDTMF(digit);
+     *       playKeyTone(digit); // Optional: play local tone feedback
+     *     } catch (error) {
+     *       console.error('Failed to send DTMF:', error.message);
+     *     }
+     *   };
+     *   keypadContainer.appendChild(button);
+     * });
+     * ```
+     *
+     * @example Error handling
+     * ```typescript
+     * try {
+     *   agent.sendDTMF('1');
+     * } catch (error) {
+     *   if (error.message.includes('not connected')) {
+     *     showConnectionError();
+     *   } else if (error.message.includes('Invalid DTMF')) {
+     *     showInvalidInputError();
+     *   }
+     * }
+     * ```
+     */
+    sendDTMF(digit: DTMFDigit): void;
     /**
      * Gets frequency data from the user's microphone input
      *