@voice-ai-labs/web-sdk 0.3.0 → 0.5.0

package/dist/client/tts.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Text-to-Speech (TTS) Client
+ *
+ * Provides methods for:
+ * - Generating speech from text (synchronous and streaming)
+ * - Listing available voices
+ * - Getting voice details
+ * - Cloning voices from audio samples
+ * - Updating and deleting voices
+ */
+import { BaseClient, BaseClientConfig } from './base';
+import type { SynthesizeRequest, CloneVoiceOptions, CloneVoiceResponse, VoiceResponse, UpdateVoiceOptions, DeleteVoiceResponse } from '../types';
+/**
+ * Client for Text-to-Speech operations
+ *
+ * @example
+ * ```typescript
+ * // List available voices
+ * const voices = await client.tts.listVoices();
+ *
+ * // Generate speech
+ * const audio = await client.tts.synthesize({
+ *   text: 'Hello world!',
+ *   voice_id: 'voice-123',
+ *   language: 'en',
+ * });
+ *
+ * // Clone a voice
+ * const cloned = await client.tts.cloneVoice({
+ *   file: audioFile,
+ *   name: 'My Voice',
+ *   language: 'en',
+ * });
+ * ```
+ */
+export declare class TTSClient extends BaseClient {
+    constructor(config: BaseClientConfig);
+    /**
+     * Generate speech from text (returns complete audio file)
+     *
+     * This is the synchronous endpoint - it blocks until generation completes
+     * and returns the entire audio file as a Blob. For lower latency with
+     * chunked streaming, use {@link synthesizeStream}.
+     *
+     * @param options - Speech generation options
+     * @returns Audio blob in the requested format
+     *
+     * @example
+     * ```typescript
+     * const audio = await client.tts.synthesize({
+     *   text: 'Hello, welcome to Voice AI!',
+     *   voice_id: 'voice-123',
+     *   language: 'en',
+     *   audio_format: 'mp3',
+     * });
+     *
+     * // Play in browser
+     * const url = URL.createObjectURL(audio);
+     * new Audio(url).play();
+     *
+     * // Or download
+     * const a = document.createElement('a');
+     * a.href = url;
+     * a.download = 'speech.mp3';
+     * a.click();
+     * ```
+     */
+    synthesize(options: SynthesizeRequest): Promise<Blob>;
+    /**
+     * Generate speech from text with HTTP chunked streaming
+     *
+     * Returns a Response object with a readable body stream. Audio chunks
+     * are sent to the client as they are generated, providing lower perceived
+     * latency than {@link synthesize}.
+     *
+     * @param options - Speech generation options
+     * @returns Fetch Response with streaming body
+     *
+     * @example
+     * ```typescript
+     * const response = await client.tts.synthesizeStream({
+     *   text: 'Hello, welcome to Voice AI!',
+     *   voice_id: 'voice-123',
+     *   language: 'en',
+     * });
+     *
+     * // Read chunks as they arrive
+     * const reader = response.body!.getReader();
+     * while (true) {
+     *   const { done, value } = await reader.read();
+     *   if (done) break;
+     *   // Process audio chunk (Uint8Array)
+     *   console.log('Received chunk:', value.length, 'bytes');
+     * }
+     *
+     * // Or collect all chunks and create a blob
+     * const response = await client.tts.synthesizeStream({ text: '...', voice_id: '...' });
+     * const blob = await response.blob();
+     * ```
+     */
+    synthesizeStream(options: SynthesizeRequest): Promise<Response>;
+    /**
+     * List voices available to the current user
+     *
+     * Returns voices owned by the authenticated user plus default/public voices.
+     * Deleted voices are excluded.
+     *
+     * @returns Array of voice objects
+     *
+     * @example
+     * ```typescript
+     * const voices = await client.tts.listVoices();
+     *
+     * for (const voice of voices) {
+     *   console.log(`${voice.name} (${voice.voice_id}): ${voice.status}`);
+     * }
+     *
+     * // Filter to only available voices
+     * const available = voices.filter(v => v.status === 'AVAILABLE');
+     * ```
+     */
+    listVoices(): Promise<VoiceResponse[]>;
+    /**
+     * Get voice details and status
+     *
+     * Useful for polling the status of a voice clone operation
+     * (PENDING -> PROCESSING -> AVAILABLE).
+     *
+     * Access control:
+     * - PUBLIC voices: readable by any authenticated user
+     * - PRIVATE voices: readable only by owner (returns 404 otherwise)
+     *
+     * @param voiceId - The voice ID
+     * @returns Voice details and status
+     *
+     * @example
+     * ```typescript
+     * const voice = await client.tts.getVoice('voice-123');
+     *
+     * if (voice.status === 'AVAILABLE') {
+     *   console.log('Voice is ready to use!');
+     * } else if (voice.status === 'PROCESSING') {
+     *   console.log('Voice is still being processed...');
+     * }
+     * ```
+     */
+    getVoice(voiceId: string): Promise<VoiceResponse>;
+    /**
+     * Clone a voice from a reference audio file
+     *
+     * Accepts an audio file (MP3, WAV, or OGG, max 7.5MB) and creates
+     * a cloned voice. The voice starts in PENDING status and moves to
+     * PROCESSING, then AVAILABLE once ready.
+     *
+     * Use {@link getVoice} to poll the voice status.
+     *
+     * @param options - Clone voice options including audio file
+     * @returns Created voice with ID and initial status (PENDING)
+     *
+     * @example
+     * ```typescript
+     * // From a file input
+     * const fileInput = document.querySelector('input[type="file"]');
+     * const file = fileInput.files[0];
+     *
+     * const voice = await client.tts.cloneVoice({
+     *   file: file,
+     *   name: 'My Custom Voice',
+     *   language: 'en',
+     *   voice_visibility: 'PRIVATE',
+     * });
+     *
+     * console.log('Voice ID:', voice.voice_id);
+     * console.log('Status:', voice.status); // 'PENDING'
+     *
+     * // Poll until ready
+     * let status = voice.status;
+     * while (status !== 'AVAILABLE' && status !== 'FAILED') {
+     *   await new Promise(r => setTimeout(r, 2000));
+     *   const updated = await client.tts.getVoice(voice.voice_id);
+     *   status = updated.status;
+     *   console.log('Status:', status);
+     * }
+     * ```
+     */
+    cloneVoice(options: CloneVoiceOptions): Promise<CloneVoiceResponse>;
+    /**
+     * Update voice metadata (name and/or visibility)
+     *
+     * Only the voice owner can update a voice.
+     *
+     * @param voiceId - The voice ID to update
+     * @param options - Fields to update
+     * @returns Updated voice details
+     *
+     * @example
+     * ```typescript
+     * // Rename a voice
+     * const updated = await client.tts.updateVoice('voice-123', {
+     *   name: 'New Voice Name',
+     * });
+     *
+     * // Make a voice private
+     * const updated = await client.tts.updateVoice('voice-123', {
+     *   voice_visibility: 'PRIVATE',
+     * });
+     * ```
+     */
+    updateVoice(voiceId: string, options: UpdateVoiceOptions): Promise<VoiceResponse>;
+    /**
+     * Delete a voice
+     *
+     * Only the voice owner can delete a voice. The voice will no longer
+     * appear in voice listings.
+     *
+     * @param voiceId - The voice ID to delete
+     * @returns Deletion confirmation
+     *
+     * @example
+     * ```typescript
+     * await client.tts.deleteVoice('voice-123');
+     * console.log('Voice deleted');
+     * ```
+     */
+    deleteVoice(voiceId: string): Promise<DeleteVoiceResponse>;
+}
+//# sourceMappingURL=tts.d.ts.map

package/dist/client/tts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts.d.ts","sourceRoot":"","sources":["../../src/client/tts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AACtD,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,SAAU,SAAQ,UAAU;gBAC3B,MAAM,EAAE,gBAAgB;IAQpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAQrE;;;;;;;;;;;;;;;;;;;OAmBG;IACG,UAAU,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAI5C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAIvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACG,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAiBzE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC;IAIvF;;;;;;;;;;;;;;OAcG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAGjE"}

package/dist/client/tts.js

@@ -0,0 +1,259 @@
+/**
+ * Text-to-Speech (TTS) Client
+ *
+ * Provides methods for:
+ * - Generating speech from text (synchronous and streaming)
+ * - Listing available voices
+ * - Getting voice details
+ * - Cloning voices from audio samples
+ * - Updating and deleting voices
+ */
+import { BaseClient } from './base';
+/**
+ * Client for Text-to-Speech operations
+ *
+ * @example
+ * ```typescript
+ * // List available voices
+ * const voices = await client.tts.listVoices();
+ *
+ * // Generate speech
+ * const audio = await client.tts.synthesize({
+ *   text: 'Hello world!',
+ *   voice_id: 'voice-123',
+ *   language: 'en',
+ * });
+ *
+ * // Clone a voice
+ * const cloned = await client.tts.cloneVoice({
+ *   file: audioFile,
+ *   name: 'My Voice',
+ *   language: 'en',
+ * });
+ * ```
+ */
+export class TTSClient extends BaseClient {
+    constructor(config) {
+        super(config);
+    }
+    // ==========================================================================
+    // SPEECH GENERATION
+    // ==========================================================================
+    /**
+     * Generate speech from text (returns complete audio file)
+     *
+     * This is the synchronous endpoint - it blocks until generation completes
+     * and returns the entire audio file as a Blob. For lower latency with
+     * chunked streaming, use {@link synthesizeStream}.
+     *
+     * @param options - Speech generation options
+     * @returns Audio blob in the requested format
+     *
+     * @example
+     * ```typescript
+     * const audio = await client.tts.synthesize({
+     *   text: 'Hello, welcome to Voice AI!',
+     *   voice_id: 'voice-123',
+     *   language: 'en',
+     *   audio_format: 'mp3',
+     * });
+     *
+     * // Play in browser
+     * const url = URL.createObjectURL(audio);
+     * new Audio(url).play();
+     *
+     * // Or download
+     * const a = document.createElement('a');
+     * a.href = url;
+     * a.download = 'speech.mp3';
+     * a.click();
+     * ```
+     */
+    async synthesize(options) {
+        return this.postForBlob('/tts/speech', options);
+    }
+    /**
+     * Generate speech from text with HTTP chunked streaming
+     *
+     * Returns a Response object with a readable body stream. Audio chunks
+     * are sent to the client as they are generated, providing lower perceived
+     * latency than {@link synthesize}.
+     *
+     * @param options - Speech generation options
+     * @returns Fetch Response with streaming body
+     *
+     * @example
+     * ```typescript
+     * const response = await client.tts.synthesizeStream({
+     *   text: 'Hello, welcome to Voice AI!',
+     *   voice_id: 'voice-123',
+     *   language: 'en',
+     * });
+     *
+     * // Read chunks as they arrive
+     * const reader = response.body!.getReader();
+     * while (true) {
+     *   const { done, value } = await reader.read();
+     *   if (done) break;
+     *   // Process audio chunk (Uint8Array)
+     *   console.log('Received chunk:', value.length, 'bytes');
+     * }
+     *
+     * // Or collect all chunks and create a blob
+     * const response = await client.tts.synthesizeStream({ text: '...', voice_id: '...' });
+     * const blob = await response.blob();
+     * ```
+     */
+    async synthesizeStream(options) {
+        return this.postForStream('/tts/speech/stream', options);
+    }
+    // ==========================================================================
+    // VOICE MANAGEMENT
+    // ==========================================================================
+    /**
+     * List voices available to the current user
+     *
+     * Returns voices owned by the authenticated user plus default/public voices.
+     * Deleted voices are excluded.
+     *
+     * @returns Array of voice objects
+     *
+     * @example
+     * ```typescript
+     * const voices = await client.tts.listVoices();
+     *
+     * for (const voice of voices) {
+     *   console.log(`${voice.name} (${voice.voice_id}): ${voice.status}`);
+     * }
+     *
+     * // Filter to only available voices
+     * const available = voices.filter(v => v.status === 'AVAILABLE');
+     * ```
+     */
+    async listVoices() {
+        return this.get('/tts/voices');
+    }
+    /**
+     * Get voice details and status
+     *
+     * Useful for polling the status of a voice clone operation
+     * (PENDING -> PROCESSING -> AVAILABLE).
+     *
+     * Access control:
+     * - PUBLIC voices: readable by any authenticated user
+     * - PRIVATE voices: readable only by owner (returns 404 otherwise)
+     *
+     * @param voiceId - The voice ID
+     * @returns Voice details and status
+     *
+     * @example
+     * ```typescript
+     * const voice = await client.tts.getVoice('voice-123');
+     *
+     * if (voice.status === 'AVAILABLE') {
+     *   console.log('Voice is ready to use!');
+     * } else if (voice.status === 'PROCESSING') {
+     *   console.log('Voice is still being processed...');
+     * }
+     * ```
+     */
+    async getVoice(voiceId) {
+        return this.get(`/tts/voice/${encodeURIComponent(voiceId)}`);
+    }
+    /**
+     * Clone a voice from a reference audio file
+     *
+     * Accepts an audio file (MP3, WAV, or OGG, max 7.5MB) and creates
+     * a cloned voice. The voice starts in PENDING status and moves to
+     * PROCESSING, then AVAILABLE once ready.
+     *
+     * Use {@link getVoice} to poll the voice status.
+     *
+     * @param options - Clone voice options including audio file
+     * @returns Created voice with ID and initial status (PENDING)
+     *
+     * @example
+     * ```typescript
+     * // From a file input
+     * const fileInput = document.querySelector('input[type="file"]');
+     * const file = fileInput.files[0];
+     *
+     * const voice = await client.tts.cloneVoice({
+     *   file: file,
+     *   name: 'My Custom Voice',
+     *   language: 'en',
+     *   voice_visibility: 'PRIVATE',
+     * });
+     *
+     * console.log('Voice ID:', voice.voice_id);
+     * console.log('Status:', voice.status); // 'PENDING'
+     *
+     * // Poll until ready
+     * let status = voice.status;
+     * while (status !== 'AVAILABLE' && status !== 'FAILED') {
+     *   await new Promise(r => setTimeout(r, 2000));
+     *   const updated = await client.tts.getVoice(voice.voice_id);
+     *   status = updated.status;
+     *   console.log('Status:', status);
+     * }
+     * ```
+     */
+    async cloneVoice(options) {
+        const formData = new FormData();
+        formData.append('file', options.file);
+        if (options.name !== undefined) {
+            formData.append('name', options.name);
+        }
+        if (options.voice_visibility !== undefined) {
+            formData.append('voice_visibility', options.voice_visibility);
+        }
+        if (options.language !== undefined) {
+            formData.append('language', options.language);
+        }
+        return this.postFormData('/tts/clone-voice', formData);
+    }
+    /**
+     * Update voice metadata (name and/or visibility)
+     *
+     * Only the voice owner can update a voice.
+     *
+     * @param voiceId - The voice ID to update
+     * @param options - Fields to update
+     * @returns Updated voice details
+     *
+     * @example
+     * ```typescript
+     * // Rename a voice
+     * const updated = await client.tts.updateVoice('voice-123', {
+     *   name: 'New Voice Name',
+     * });
+     *
+     * // Make a voice private
+     * const updated = await client.tts.updateVoice('voice-123', {
+     *   voice_visibility: 'PRIVATE',
+     * });
+     * ```
+     */
+    async updateVoice(voiceId, options) {
+        return this.patch(`/tts/voice/${encodeURIComponent(voiceId)}`, options);
+    }
+    /**
+     * Delete a voice
+     *
+     * Only the voice owner can delete a voice. The voice will no longer
+     * appear in voice listings.
+     *
+     * @param voiceId - The voice ID to delete
+     * @returns Deletion confirmation
+     *
+     * @example
+     * ```typescript
+     * await client.tts.deleteVoice('voice-123');
+     * console.log('Voice deleted');
+     * ```
+     */
+    async deleteVoice(voiceId) {
+        return this.httpDelete(`/tts/voice/${encodeURIComponent(voiceId)}`);
+    }
+}
+//# sourceMappingURL=tts.js.map

package/dist/client/tts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts.js","sourceRoot":"","sources":["../../src/client/tts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAoB,MAAM,QAAQ,CAAC;AAUtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,SAAU,SAAQ,UAAU;IACvC,YAAY,MAAwB;QAClC,KAAK,CAAC,MAAM,CAAC,CAAC;IAChB,CAAC;IAED,6EAA6E;IAC7E,oBAAoB;IACpB,6EAA6E;IAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,KAAK,CAAC,UAAU,CAAC,OAA0B;QACzC,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,KAAK,CAAC,gBAAgB,CAAC,OAA0B;QAC/C,OAAO,IAAI,CAAC,aAAa,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED,6EAA6E;IAC7E,mBAAmB;IACnB,6EAA6E;IAE7E;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,UAAU;QACd,OAAO,IAAI,CAAC,GAAG,CAAkB,aAAa,CAAC,CAAC;IAClD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,KAAK,CAAC,QAAQ,CAAC,OAAe;QAC5B,OAAO,IAAI,CAAC,GAAG,CAAgB,cAAc,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,KAAK,CAAC,UAAU,CAAC,OAA0B;QACzC,MAAM,QAAQ,GAAG,IAAI,QAAQ,EAAE,CAAC;QAChC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAEtC,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC/B,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QACxC,CAAC;QACD,IAAI,OAAO,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;YAC3C,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;QAChE,CAAC;QACD,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YACnC,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QAChD,CAAC;QAED,OAAO,IAAI,CAAC,YAAY,CAAqB,kBAAkB,EAAE,QAAQ,CAAC,CAAC;IAC7E,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,WAAW,CAAC,OAAe,EAAE,OAA2B;QAC5D,OAAO,IAAI,CAAC,KAAK,CAAgB,cAAc,kBAAkB,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACzF,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,WAAW,CAAC,OAAe;QAC/B,OAAO,IAAI,CAAC,UAAU,CAAsB,cAAc,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC3F,CAAC;CACF"}

package/dist/index.d.ts

@@ -24,7 +24,8 @@ import { AgentClient } from './client/agents';
 import { AnalyticsClient } from './client/analytics';
 import { KnowledgeBaseClient } from './client/knowledge-base';
 import { PhoneNumberClient } from './client/phone-numbers';
-import type { ConnectionOptions, ConnectionStatus, TranscriptionHandler, ConnectionStatusHandler, ErrorHandler, AudioCaptureOptions, AgentStateInfo, MicrophoneState, AgentStateHandler, AudioLevelHandler, MicrophoneStateHandler, VoiceAIConfig } from './types';
+import { TTSClient } from './client/tts';
+import type { ConnectionOptions, ConnectionDetails, ConnectionStatus, TranscriptionHandler, ConnectionStatusHandler, ErrorHandler, AudioCaptureOptions, AgentStateInfo, MicrophoneState, AgentStateHandler, AudioLevelHandler, MicrophoneStateHandler, VoiceAIConfig } from './types';
 /**
  * VoiceAI - The unified Voice.ai SDK
  *
@@ -50,14 +51,21 @@ import type { ConnectionOptions, ConnectionStatus, TranscriptionHandler, Connect
  * ```
  */
 export declare class VoiceAI {
-    /** Agent management - create, update, deploy, pause, delete agents */
-    readonly agents: AgentClient;
-    /** Analytics - call history, transcripts, stats */
-    readonly analytics: AnalyticsClient;
-    /** Knowledge Base - manage RAG documents */
-    readonly knowledgeBase: KnowledgeBaseClient;
-    /** Phone Numbers - search, select, release phone numbers */
-    readonly phoneNumbers: PhoneNumberClient;
+    /** Agent management - create, update, deploy, pause, delete agents. */
+    get agents(): AgentClient;
+    private _agents?;
+    /** Analytics - call history, transcripts, stats. */
+    get analytics(): AnalyticsClient;
+    private _analytics?;
+    /** Knowledge Base - manage RAG documents. */
+    get knowledgeBase(): KnowledgeBaseClient;
+    private _knowledgeBase?;
+    /** Phone Numbers - search, select, release phone numbers. */
+    get phoneNumbers(): PhoneNumberClient;
+    private _phoneNumbers?;
+    /** Text-to-Speech - generate speech, manage voices, clone voices. */
+    get tts(): TTSClient;
+    private _tts?;
     private room;
     private connectionStatus;
     private transcriptionHandlers;
@@ -68,6 +76,7 @@ export declare class VoiceAI {
     private microphoneStateHandlers;
     private apiUrl;
     private apiKey;
+    private effectiveApiKey;
     private cachedConnectionDetails;
     private currentAgentState;
     private agentParticipantId;
@@ -75,17 +84,61 @@ export declare class VoiceAI {
     /**
      * Create a new VoiceAI client
      *
-     * @param config - Configuration options
-     * @param config.apiKey - Your Voice.ai API key (required)
+     * @param config - Configuration options (optional for frontend-only usage)
+     * @param config.apiKey - Your Voice.ai API key (required for API operations and `getConnectionDetails`)
      * @param config.apiUrl - Custom API URL (optional, defaults to production)
      */
-    constructor(config: VoiceAIConfig);
+    constructor(config?: VoiceAIConfig);
     /**
-     * Connect to a voice agent for real-time conversation
+     * Get connection details for a voice agent.
+     *
+     * Requires an API key. Call this from your backend, then pass the result
+     * to `connectRoom()` on the frontend.
+     *
+     * @param options - Connection options (agentId, testMode, etc.)
+     * @returns Connection details (serverUrl, participantToken, callId)
+     *
+     * @example
+     * ```typescript
+     * // Server-side: get connection details
+     * const details = await voiceai.getConnectionDetails({ agentId: 'agent-123' });
+     * // Return details to frontend...
+     *
+     * // With test mode
+     * const details = await voiceai.getConnectionDetails({
+     *   agentId: 'agent-123',
+     *   testMode: true
+     * });
+     * ```
+     */
+    getConnectionDetails(options: ConnectionOptions): Promise<ConnectionDetails>;
+    /**
+     * Connect to a LiveKit room using pre-fetched connection details.
+     *
+     * This is the browser-safe method -- it only needs a room token,
+     * no API key required. Get the connection details from your backend
+     * using `getConnectionDetails()`.
+     *
+     * @param connectionDetails - Server URL, participant token, and call ID from your backend
+     * @param options - Audio/microphone options
+     *
+     * @example
+     * ```typescript
+     * // Frontend: connect using token from your backend
+     * const voiceai = new VoiceAI();
+     * await voiceai.connectRoom(
+     *   { serverUrl, participantToken, callId },
+     *   { autoPublishMic: true }
+     * );
+     * ```
+     */
+    connectRoom(connectionDetails: ConnectionDetails, options?: Pick<ConnectionOptions, 'autoPublishMic' | 'audioOptions' | 'preConnectBuffer'>): Promise<void>;
+    /**
+     * Connect to a voice agent for real-time conversation.
+     *
+     * Convenience method that combines `getConnectionDetails()` + `connectRoom()`.
      *
      * @param options - Connection options
-     * @param options.agentId - ID of the agent to connect to
-     * @param options.autoPublishMic - Auto-enable microphone (default: true)
      *
      * @example
      * ```typescript
@@ -94,7 +147,12 @@ export declare class VoiceAI {
      */
     connect(options: ConnectionOptions): Promise<void>;
     /**
-     * Disconnect from the voice agent and end the call
+     * Disconnect from the room and end the call.
+     *
+     * Signals the server to free the concurrency slot using endToken from
+     * connection details. Connection details always include end_token when
+     * fetched from the API; backends must pass it when using pre-fetched details.
+     * If no endToken, the server detects room disconnect as fallback.
      */
     disconnect(): Promise<void>;
     /**
@@ -153,7 +211,16 @@ export declare class VoiceAI {
     onMicrophoneStateChange(handler: MicrophoneStateHandler): () => void;
     private isTokenExpired;
     private getOrRefreshConnectionDetails;
-    private getConnectionDetails;
+    /**
+     * Fetch connection details from the developer's backend endpoint.
+     * The backend holds the API key and calls the Voice.AI API server-side.
+     */
+    /**
+     * Fetch connection details using the API key directly.
+     * Used by the public getConnectionDetails() method.
+     */
+    private fetchConnectionDetails;
+    private fetchConnectionDetailsFromApi;
     private setupAudio;
     private setupRoomListeners;
     private detectAgentParticipant;
@@ -171,7 +238,7 @@ export declare class VoiceAI {
 export default VoiceAI;
 /** Error class for API errors */
 export { VoiceAIError } from './client/base';
-export type { VoiceAIConfig, ConnectionOptions, ConnectionDetails, ConnectionStatus, TranscriptionSegment, TranscriptionHandler, ConnectionStatusHandler, ErrorHandler, AgentStateHandler, AudioLevelHandler, MicrophoneStateHandler, AgentState, AgentStateInfo, AudioLevelInfo, MicrophoneState, AudioCaptureOptions, TTSParams, MCPServerConfig, AgentConfig, Agent, CreateAgentRequest, UpdateAgentRequest, AgentDeployResponse, AgentPauseResponse, AgentDeleteResponse, AgentConnectionStatusResponse, InitAgentRequest, InitAgentResponse, PaginatedAgentResponse, ListAgentsOptions, WebhookEventType, WebhookEventsConfig, WebhooksConfig, WebhookEvent, WebhookTestResponse, CallHistoryItem, PaginatedCallHistoryResponse, GetCallHistoryOptions, TranscriptResponse, KnowledgeBaseDocument, CreateKnowledgeBaseRequest, UpdateKnowledgeBaseRequest, KnowledgeBaseResponse, KnowledgeBaseWithDocuments, PaginatedKnowledgeBaseResponse, PhoneNumberInfo, AvailablePhoneNumber, SearchPhoneNumbersRequest, SearchPhoneNumbersResponse, PurchasePhoneNumberRequest, PurchasePhoneNumberResponse, AllPhoneNumbersResponse, PaginationMeta, PaginationOptions, ErrorResponse, } from './types';
+export type { VoiceAIConfig, ConnectionOptions, ConnectionDetails, ConnectionStatus, TranscriptionSegment, AgentState, AgentStateInfo, AudioLevelInfo, MicrophoneState, Agent, VoiceResponse, VoiceStatus, } from './types';
 /**
  * Generate optimized audio capture options for voice agents
  *

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}