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

package/package.json

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

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

@@ -38,7 +38,7 @@ import { LiveKitAudioManager } from './livekit-audio-manager';
 import { LiveKitConnection } from './livekit-connection';
 import { LiveKitToolRegistry } from './livekit-tool-registry';
 import type { AudioLevelsResult, CallAnalyticsResult, ConnectionStatsResult, ParticipantData, PerformanceMetricsResult, Tool, TrackStatsResult } from './types';
-export type { AudioLevelsResult, CallAnalyticsResult, ConnectionStatsResult, ParticipantData, PerformanceMetricsResult, TrackStatsData, TrackStatsResult, } from './types';
+export type { AgentState, AudioLevelsResult, CallAnalyticsResult, ConnectionStatsResult, ParticipantData, PerformanceMetricsResult, TrackStatsData, TrackStatsResult, } from './types';
 /**
  * Main LiveKitManager class that orchestrates voice agent communication
  *

package/types/classes/types.d.ts

@@ -2,6 +2,11 @@
  * Shared types and interfaces for LiveKit modules
  */
 import type { ConnectionQuality, RemoteTrack, RemoteTrackPublication } from 'livekit-client';
+/**
+ * Agent state as defined by LiveKit
+ * Represents the current state of the voice agent
+ */
+export type AgentState = 'idle' | 'initializing' | 'listening' | 'thinking' | 'speaking';
 /**
  * Function signature for client-side tools that can be executed by the agent.
  * Tools can be synchronous or asynchronous and accept variable arguments.

package/types/main.d.ts

@@ -1,7 +1,8 @@
 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 type { ConnectionState, LocalTrack, LocalTrackPublication, Participant, RemoteParticipant, RemoteTrack, RemoteTrackPublication, 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';
+export type { AgentState } from './classes/livekit-manager';
 /**
  * Custom error class that includes both human-readable message and machine-readable messageKey
  * for internationalization and programmatic error handling
@@ -97,6 +98,95 @@ type JobDetails = {
     /** Additional job properties that may be returned by the API */
     [key: string]: unknown;
 };
+/**
+ * Event handler signatures for HamsaVoiceAgent
+ *
+ * Defines the type-safe interface for all events emitted by the HamsaVoiceAgent.
+ * Each event specifies its exact handler signature, enabling full type safety
+ * and IntelliSense support when using the event emitter API.
+ *
+ * @example
+ * ```typescript
+ * // Fully type-safe event handlers
+ * agent.on('transcriptionReceived', (text: string) => {
+ *   console.log('User said:', text);
+ * });
+ *
+ * agent.on('connectionQualityChanged', ({ quality, metrics }) => {
+ *   if (quality === 'poor') {
+ *     showNetworkWarning(metrics);
+ *   }
+ * });
+ * ```
+ */
+type HamsaVoiceAgentEvents = {
+    /** Emitted when connection is established (before call fully starts) */
+    start: () => void;
+    /** Emitted when call is fully started and ready */
+    callStarted: () => void;
+    /** Emitted when call ends (user or agent initiated) */
+    callEnded: () => void;
+    /** Emitted when call is paused */
+    callPaused: () => void;
+    /** Emitted when call is resumed */
+    callResumed: () => void;
+    /** Emitted when connection is closed */
+    closed: () => void;
+    /** Emitted when attempting to reconnect */
+    reconnecting: () => void;
+    /** Emitted when reconnection succeeds */
+    reconnected: () => void;
+    /** Emitted when user speech is transcribed */
+    transcriptionReceived: (text: string) => void;
+    /** Emitted when agent response is received */
+    answerReceived: (text: string) => void;
+    /** Emitted when agent starts speaking */
+    speaking: () => void;
+    /** Emitted when agent is listening */
+    listening: () => void;
+    /** Emitted when agent state changes (idle, initializing, listening, thinking, speaking) */
+    agentStateChanged: (state: AgentState) => void;
+    /** Emitted when an error occurs */
+    error: (error: Error | HamsaApiError) => void;
+    /** Emitted when a remote track is subscribed */
+    trackSubscribed: (data: {
+        track: RemoteTrack;
+        publication: RemoteTrackPublication;
+        participant: RemoteParticipant;
+    }) => void;
+    /** Emitted when a remote track is unsubscribed */
+    trackUnsubscribed: (data: {
+        track: RemoteTrack;
+        publication: RemoteTrackPublication;
+        participant: RemoteParticipant;
+    }) => void;
+    /** Emitted when a local track is published */
+    localTrackPublished: (data: {
+        track?: LocalTrack;
+        publication: LocalTrackPublication;
+    }) => void;
+    /** Emitted when analytics data is updated */
+    analyticsUpdated: (analytics: CallAnalyticsResult) => void;
+    /** Emitted when connection quality changes */
+    connectionQualityChanged: (data: {
+        quality: 'excellent' | 'good' | 'poor';
+        metrics: ConnectionStatsResult;
+    }) => void;
+    /** Emitted when connection state changes */
+    connectionStateChanged: (state: ConnectionState) => void;
+    /** Emitted when audio playback state changes */
+    audioPlaybackChanged: (playing: boolean) => void;
+    /** Emitted when a participant connects */
+    participantConnected: (participant: RemoteParticipant) => void;
+    /** Emitted when a participant disconnects */
+    participantDisconnected: (participant: RemoteParticipant) => void;
+    /** Emitted when data is received */
+    dataReceived: (message: Uint8Array, participant: Participant) => void;
+    /** Emitted for custom events */
+    customEvent: (eventType: string, eventData: unknown, metadata?: Record<string, unknown>) => void;
+    /** Emitted for informational messages */
+    info: (info: string) => void;
+};
 /**
  * HamsaVoiceAgent - Main SDK class for voice agent integration
  *
@@ -104,6 +194,9 @@ type JobDetails = {
  * into web applications. It handles authentication, connection management,
  * conversation lifecycle, analytics, and client-side tool execution.
  *
+ * Note: This class uses declaration merging with an interface (defined below)
+ * to provide type-safe event handlers. This is intentional and safe.
+ *
  * Key features:
  * - Real-time voice communication with AI agents
  * - Comprehensive analytics and quality monitoring
@@ -784,5 +877,47 @@ declare class HamsaVoiceAgent extends EventEmitter {
      */
     getRoom(): Room | null;
 }
+/**
+ * Declaration merging: Add type-safe event methods to HamsaVoiceAgent
+ *
+ * This interface merges with the HamsaVoiceAgent class to provide fully
+ * typed event handler methods without requiring explicit type assertions.
+ *
+ * @example
+ * ```typescript
+ * const agent = new HamsaVoiceAgent('api_key');
+ *
+ * // ✅ Fully type-safe - no casting needed!
+ * agent.on('transcriptionReceived', (text) => {
+ *   console.log(text); // text is inferred as string
+ * });
+ *
+ * // ❌ Type error - wrong event name
+ * agent.on('wrongEvent', () => {});
+ *
+ * // ❌ Type error - wrong handler signature
+ * agent.on('transcriptionReceived', () => {}); // Missing parameter
+ * ```
+ */
+interface HamsaVoiceAgent {
+    /**
+     * Registers an event listener with type-safe event names and handlers
+     */
+    on<K extends keyof HamsaVoiceAgentEvents>(event: K, listener: HamsaVoiceAgentEvents[K]): this;
+    /**
+     * Removes an event listener with type-safe event names and handlers
+     */
+    off<K extends keyof HamsaVoiceAgentEvents>(event: K, listener: HamsaVoiceAgentEvents[K]): this;
+    /**
+     * Registers a one-time event listener with type-safe event names and handlers
+     */
+    once<K extends keyof HamsaVoiceAgentEvents>(event: K, listener: HamsaVoiceAgentEvents[K]): this;
+    /**
+     * Emits an event with type-safe event names and arguments
+     */
+    emit<K extends keyof HamsaVoiceAgentEvents>(event: K, ...args: Parameters<HamsaVoiceAgentEvents[K]>): boolean;
+}
 export { HamsaVoiceAgent, HamsaApiError };
 export default HamsaVoiceAgent;
+export type { AudioLevelsResult, CallAnalyticsResult, ConnectionStatsResult, ParticipantData, PerformanceMetricsResult, TrackStatsResult, } from './classes/livekit-manager';
+export type { HamsaVoiceAgentEvents, StartOptions, Tool, JobDetails };