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

package/package.json

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

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

@@ -188,6 +188,8 @@ export declare class LiveKitConnection extends EventEmitter {
     private reconnectionAttempts;
     /** Whether we've already emitted a 'connected' event for the current session */
     private hasEmittedConnected;
+    /** Debug logger instance for conditional logging */
+    private readonly logger;
     /**
      * Creates a new LiveKitConnection instance
      *
@@ -197,19 +199,21 @@ export declare class LiveKitConnection extends EventEmitter {
      *
      * @param lkUrl - LiveKit WebSocket URL (e.g., 'wss://livekit.example.com')
      * @param accessToken - JWT token for room authentication and authorization
+     * @param debug - Enable debug logging (defaults to false)
      *
      * @example
      * ```typescript
      * const connection = new LiveKitConnection(
      *   'wss://rtc.eu.tryhamsa.com',
-     *   'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+     *   'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
+     *   false
      * );
      *
      * // Connection is ready for use
      * await connection.connect();
      * ```
      */
-    constructor(lkUrl: string, accessToken: string);
+    constructor(lkUrl: string, accessToken: string, debug?: boolean);
     /**
      * Provides access to the underlying LiveKit room instance
      *

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

@@ -33,6 +33,7 @@
  */
 import { EventEmitter } from 'events';
 import type { Room } from 'livekit-client';
+import { type DebugLogger } from '../utils';
 import { LiveKitAnalytics } from './livekit-analytics';
 import { LiveKitAudioManager } from './livekit-audio-manager';
 import { LiveKitConnection } from './livekit-connection';
@@ -59,6 +60,8 @@ export default class LiveKitManager extends EventEmitter {
     lkUrl: string;
     /** JWT access token for authentication */
     accessToken: string;
+    /** Debug logger instance for conditional logging */
+    logger: DebugLogger;
     /**
      * Creates a new LiveKitManager instance
      *
@@ -83,7 +86,7 @@ export default class LiveKitManager extends EventEmitter {
      * );
      * ```
      */
-    constructor(lkUrl: string, accessToken: string, tools?: Tool[]);
+    constructor(lkUrl: string, accessToken: string, tools?: Tool[], debug?: boolean);
     /**
      * Establishes connection to the LiveKit room and initializes voice agent communication
      *

package/types/main.d.ts

@@ -21,6 +21,8 @@ type HamsaVoiceAgentConfig = {
     API_URL?: string;
     /** LiveKit RTC WebSocket URL. Defaults to 'wss://rtc.eu.tryhamsa.com' */
     LIVEKIT_URL?: string;
+    /** Enable debug logging for troubleshooting. Defaults to false */
+    debug?: boolean;
 };
 /**
  * Configuration options for starting a voice agent conversation
@@ -302,8 +304,6 @@ declare class HamsaVoiceAgent extends EventEmitter {
     private static readonly DEFAULT_OUTPUT_VOLUME;
     /** Default fallback input volume when not connected */
     private static readonly DEFAULT_INPUT_VOLUME;
-    /** Delay in milliseconds before auto-disconnect when agent leaves (allows LiveKit cleanup) */
-    private static readonly AGENT_DISCONNECT_DELAY_MS;
     /** Internal LiveKit manager instance for WebRTC communication */
     liveKitManager: LiveKitManager | null;
     /** Hamsa API key for authentication */
@@ -312,12 +312,16 @@ declare class HamsaVoiceAgent extends EventEmitter {
     API_URL: string;
     /** LiveKit RTC WebSocket URL */
     LIVEKIT_URL: string;
+    /** Enable debug logging for troubleshooting */
+    debug: boolean;
     /** Job ID for tracking conversation completion status */
     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 to prevent duplicate disconnection logic */
     private userInitiatedEnd;
+    /** Debug logger instance for conditional logging */
+    private readonly logger;
     /**
      * Creates a new HamsaVoiceAgent instance
      *
@@ -340,7 +344,7 @@ declare class HamsaVoiceAgent extends EventEmitter {
      *
      * @throws {Error} If apiKey is not provided or invalid
      */
-    constructor(apiKey: string, { API_URL, LIVEKIT_URL, }?: HamsaVoiceAgentConfig);
+    constructor(apiKey: string, { API_URL, LIVEKIT_URL, debug, }?: HamsaVoiceAgentConfig);
     /**
      * Adjusts the volume level for voice agent audio playback
      *

package/types/utils/debug.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Debug utility for conditional logging throughout the SDK
+ *
+ * This utility provides a centralized way to handle debug logging without
+ * needing biome-ignore comments for console statements. It only logs when
+ * debug mode is enabled.
+ *
+ * @example
+ * ```typescript
+ * const logger = createDebugLogger(this.debug);
+ * logger.log('Connection established', { source: 'LiveKitConnection' });
+ * logger.error('Failed to connect', { source: 'LiveKitConnection', error });
+ * ```
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+type LogOptions = {
+    source?: string;
+    level?: LogLevel;
+    error?: unknown;
+};
+/**
+ * Debug logger interface
+ */
+export type DebugLogger = {
+    /**
+     * Log a debug message (only when debug mode is enabled)
+     */
+    log: (message: unknown, options?: LogOptions) => void;
+    /**
+     * Log an info message (only when debug mode is enabled)
+     */
+    info: (message: unknown, options?: LogOptions) => void;
+    /**
+     * Log a warning message (only when debug mode is enabled)
+     */
+    warn: (message: unknown, options?: LogOptions) => void;
+    /**
+     * Log an error message (always logs, regardless of debug mode)
+     */
+    error: (message: unknown, options?: LogOptions) => void;
+};
+/**
+ * Creates a debug logger instance
+ *
+ * @param debug - Whether debug mode is enabled
+ * @returns A debug logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = createDebugLogger(true);
+ * logger.log('Starting connection', { source: 'LiveKitConnection' });
+ * logger.error('Connection failed', { source: 'LiveKitConnection', error });
+ * ```
+ */
+export declare const createDebugLogger: (debug: boolean) => DebugLogger;
+export {};

package/types/utils/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Utility functions for the Voice Agents SDK
+ */
+export type { DebugLogger } from './debug';
+export { createDebugLogger } from './debug';