@hamsa-ai/voice-agents-sdk 0.5.2 → 0.5.4

package/package.json

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

package/types/classes/types.d.ts

@@ -408,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,72 @@ 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.
+     *
+     * Uses LiveKit's native DTMF API (publishDtmf) which properly integrates with
+     * telephony systems and SIP infrastructure per RFC 4733 standard.
+     *
+     * @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
      *