@voice-ai-labs/web-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Voice.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# Voice.AI Web SDK
+
+The official Voice.AI SDK for JavaScript/TypeScript applications.
+
+## Installation
+
+```bash
+npm install @voice-ai-labs/web-sdk
+```
+
+## Quick Start
+
+```typescript
+import VoiceAI from '@voice-ai-labs/web-sdk';
+
+// Initialize with your API key
+const voiceai = new VoiceAI({ apiKey: 'vk_your_api_key' });
+
+// Connect to a voice agent
+await voiceai.connect({ agentId: 'your-agent-id' });
+
+// Listen for transcriptions
+voiceai.onTranscription((segment) => {
+  console.log(`${segment.role}: ${segment.text}`);
+});
+
+// Disconnect when done
+await voiceai.disconnect();
+```
+
+## Features
+
+The SDK provides a unified interface for:
+
+- **Real-time Voice** - Connect to voice agents with live transcription
+- **Agent Management** - Create, update, deploy, and manage agents
+- **Analytics** - Access call history and transcripts
+- **Knowledge Base** - Manage RAG documents for your agents
+- **Phone Numbers** - Search and manage phone numbers
+
+## Real-time Voice
+
+### Connect to an Agent
+
+```typescript
+await voiceai.connect({
+  agentId: 'agent-123',
+  autoPublishMic: true  // default: true
+});
+```
+
+### Events
+
+```typescript
+// Transcriptions (user and agent speech)
+voiceai.onTranscription((segment) => {
+  console.log(`${segment.role}: ${segment.text}`);
+  console.log('Final:', segment.isFinal);
+});
+
+// Connection status
+voiceai.onStatusChange((status) => {
+  if (status.connected) console.log('Connected!');
+  if (status.error) console.error('Error:', status.error);
+});
+
+// Agent state (listening, speaking, thinking)
+voiceai.onAgentStateChange((state) => {
+  console.log('Agent is:', state.state);
+});
+
+// Audio levels (for visualizations)
+voiceai.onAudioLevel((level) => {
+  console.log('Level:', level.level, 'Speaking:', level.isSpeaking);
+});
+
+// Errors
+voiceai.onError((error) => {
+  console.error('Error:', error.message);
+});
+```
+
+### Microphone Control
+
+```typescript
+await voiceai.setMicrophoneEnabled(true);   // Enable
+await voiceai.setMicrophoneEnabled(false);  // Disable
+```
+
+### Send Text Message
+
+```typescript
+await voiceai.sendMessage('Hello agent!');
+```
+
+### Disconnect
+
+```typescript
+await voiceai.disconnect();
+```
+
+## Agent Management
+
+```typescript
+// List agents
+const agents = await voiceai.agents.list();
+
+// Create an agent
+const agent = await voiceai.agents.create({
+  name: 'Customer Support',
+  config: {
+    prompt: 'You are a helpful customer support agent.',
+    greeting: 'Hello! How can I help you today?',
+    tts_params: {
+      voice_id: 'my-voice-id',
+      model: 'voiceai-tts-multilingual-v1-latest',
+      language: 'en'
+    }
+  }
+});
+
+// Deploy the agent
+await voiceai.agents.deploy(agent.agent_id);
+
+// Update an agent
+await voiceai.agents.update(agent.agent_id, {
+  name: 'Updated Name'
+});
+
+// Pause an agent
+await voiceai.agents.pause(agent.agent_id);
+
+// Delete an agent
+await voiceai.agents.disable(agent.agent_id);
+```
+
+## Analytics
+
+```typescript
+// Get call history
+const history = await voiceai.analytics.getCallHistory({
+  page: 1,
+  limit: 20,
+  agent_ids: ['agent-123']
+});
+
+// Get transcript URL
+const transcript = await voiceai.analytics.getTranscriptUrl(summaryId);
+
+// Get stats summary
+const stats = await voiceai.analytics.getStatsSummary();
+```
+
+## Knowledge Base
+
+```typescript
+// Create a knowledge base
+const kb = await voiceai.knowledgeBase.create({
+  name: 'Product FAQ',
+  documents: [
+    { content: 'Return policy: 30 days for full refund.' },
+    { content: 'Shipping: Free on orders over $50.' }
+  ]
+});
+
+// Assign to an agent
+await voiceai.agents.assignKnowledgeBase(agentId, kb.kb_id);
+
+// List knowledge bases
+const kbs = await voiceai.knowledgeBase.list();
+
+// Update a knowledge base
+await voiceai.knowledgeBase.update(kb.kb_id, {
+  documents: [{ content: 'Updated content' }]
+});
+
+// Delete a knowledge base
+await voiceai.knowledgeBase.remove(kb.kb_id);
+```
+
+## Phone Numbers
+
+```typescript
+// Search available numbers
+const numbers = await voiceai.phoneNumbers.search({
+  country_code: 'US',
+  area_code: '415'
+});
+
+// Select a number
+await voiceai.phoneNumbers.select('+14155551234');
+
+// List your numbers
+const myNumbers = await voiceai.phoneNumbers.list();
+
+// Release a number
+await voiceai.phoneNumbers.release('+14155551234');
+```
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```typescript
+import VoiceAI, {
+  type Agent,
+  type TranscriptionSegment,
+  type ConnectionStatus,
+  type TTSParams,
+} from '@voice-ai-labs/web-sdk';
+```
+
+## Browser Support
+
+Chrome, Firefox, Safari (latest versions). Requires microphone permission for voice features.
+
+## License
+
+MIT

package/dist/__tests__/setup.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=setup.d.ts.map

package/dist/__tests__/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/__tests__/setup.ts"],"names":[],"mappings":""}

package/dist/__tests__/setup.js

@@ -0,0 +1,13 @@
+import { vi } from 'vitest';
+// Mock fetch globally
+global.fetch = vi.fn();
+// Mock window for browser environment detection
+Object.defineProperty(global, 'window', {
+    value: {
+        location: {
+            origin: 'http://localhost:3000',
+        },
+    },
+    writable: true,
+});
+//# sourceMappingURL=setup.js.map

package/dist/__tests__/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/__tests__/setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE5B,sBAAsB;AACtB,MAAM,CAAC,KAAK,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;AAEvB,gDAAgD;AAChD,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE;IACtC,KAAK,EAAE;QACL,QAAQ,EAAE;YACR,MAAM,EAAE,uBAAuB;SAChC;KACF;IACD,QAAQ,EAAE,IAAI;CACf,CAAC,CAAC"}

package/dist/client/agents.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Agent Management Client
+ *
+ * Provides methods for:
+ * - Creating, updating, and deleting agents
+ * - Deploying and pausing agents
+ * - Checking agent connection status
+ * - Managing agent knowledge bases
+ */
+import { BaseClient, BaseClientConfig } from './base';
+import type { Agent, CreateAgentRequest, UpdateAgentRequest, AgentDeployResponse, AgentPauseResponse, AgentDeleteResponse, AgentConnectionStatusResponse, InitAgentRequest, InitAgentResponse, PaginatedAgentResponse, ListAgentsOptions } from '../types';
+/**
+ * Client for Agent management operations
+ */
+export declare class AgentClient extends BaseClient {
+    constructor(config: BaseClientConfig);
+    /**
+     * List agents with optional pagination and filtering
+     *
+     * @param options - Pagination and filter options
+     * @returns Paginated list of agents or array of agents
+     *
+     * @example
+     * ```typescript
+     * // Get all deployed agents
+     * const result = await client.agents.list({
+     *   page: 1,
+     *   limit: 10,
+     *   show_statuses: ['deployed']
+     * });
+     *
+     * for (const agent of result.items) {
+     *   console.log(`${agent.name}: ${agent.status}`);
+     * }
+     * ```
+     */
+    list(options?: ListAgentsOptions): Promise<PaginatedAgentResponse | Agent[]>;
+    /**
+     * Create a new agent
+     *
+     * @param options - Agent creation options
+     * @returns Created agent
+     *
+     * @example
+     * ```typescript
+     * const agent = await client.agents.create({
+     *   name: 'Customer Support Agent',
+     *   config: {
+     *     prompt: 'You are a helpful customer support agent.',
+     *     greeting: 'Hello! How can I help you today?',
+     *     tts_params: {
+     *       voice_id: 'my-voice-id'
+     *     }
+     *   }
+     * });
+     *
+     * console.log('Created agent:', agent.agent_id);
+     * ```
+     */
+    create(options: CreateAgentRequest): Promise<Agent>;
+    /**
+     * Get agent details by ID
+     *
+     * @param agentId - The agent ID
+     * @returns Agent details
+     *
+     * @example
+     * ```typescript
+     * const agent = await client.agents.getById('agent-123');
+     * console.log('Agent config:', agent.config);
+     * ```
+     */
+    getById(agentId: string): Promise<Agent>;
+    /**
+     * Update an existing agent
+     *
+     * @param agentId - The agent ID to update
+     * @param options - Fields to update
+     * @returns Updated agent
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.agents.update('agent-123', {
+     *   name: 'Updated Agent Name',
+     *   config: {
+     *     greeting: 'Hi there! What can I do for you?'
+     *   }
+     * });
+     * ```
+     */
+    update(agentId: string, options: UpdateAgentRequest): Promise<Agent>;
+    /**
+     * Deploy an agent (prepare for phone calls)
+     *
+     * @param agentId - The agent ID to deploy
+     * @returns Deployment response with agent and status
+     *
+     * @example
+     * ```typescript
+     * const result = await client.agents.deploy('agent-123');
+     * console.log('Deployed:', result.message);
+     * console.log('SIP status:', result.sip_status);
+     * ```
+     */
+    deploy(agentId: string): Promise<AgentDeployResponse>;
+    /**
+     * Pause an agent (frees phone number)
+     *
+     * This endpoint is idempotent.
+     *
+     * @param agentId - The agent ID to pause
+     * @returns Pause response with agent
+     *
+     * @example
+     * ```typescript
+     * const result = await client.agents.pause('agent-123');
+     * console.log('Agent status:', result.agent.status);
+     * ```
+     */
+    pause(agentId: string): Promise<AgentPauseResponse>;
+    /**
+     * Delete/disable an agent
+     *
+     * An agent must be paused before being deleted.
+     * Disabled agents will be automatically deleted after a grace period.
+     *
+     * @param agentId - The agent ID to delete
+     * @returns Delete response
+     *
+     * @example
+     * ```typescript
+     * // First pause, then delete
+     * await client.agents.pause('agent-123');
+     * const result = await client.agents.disable('agent-123');
+     * console.log('Deleted:', result.message);
+     * ```
+     */
+    disable(agentId: string): Promise<AgentDeleteResponse>;
+    /**
+     * Initialize agent from template
+     *
+     * @param options - Template options
+     * @returns Template configuration and available types
+     *
+     * @example
+     * ```typescript
+     * // Get available templates
+     * const result = await client.agents.initFromTemplate();
+     * console.log('Available types:', result.available_types);
+     *
+     * // Initialize from specific template
+     * const template = await client.agents.initFromTemplate({
+     *   agent_template: 'customer_support'
+     * });
+     * ```
+     */
+    initFromTemplate(options?: InitAgentRequest): Promise<InitAgentResponse>;
+    /**
+     * Check if an agent is available for connection
+     *
+     * @param agentId - The agent ID to check
+     * @returns Agent connection status
+     *
+     * @example
+     * ```typescript
+     * const status = await client.agents.getStatus('agent-123');
+     *
+     * if (status.call_allowed) {
+     *   console.log('Agent is available for calls');
+     * } else {
+     *   console.log('Reason:', status.call_validation_details);
+     * }
+     * ```
+     */
+    getStatus(agentId: string): Promise<AgentConnectionStatusResponse>;
+    /**
+     * Assign a knowledge base to an agent for RAG
+     *
+     * @param agentId - The agent ID
+     * @param kbId - The knowledge base ID to assign
+     * @returns Updated agent
+     *
+     * @example
+     * ```typescript
+     * const agent = await client.agents.assignKnowledgeBase('agent-123', 42);
+     * console.log('KB assigned:', agent.kb_id);
+     * ```
+     */
+    assignKnowledgeBase(agentId: string, kbId: number): Promise<Agent>;
+    /**
+     * Remove knowledge base from an agent
+     *
+     * @param agentId - The agent ID
+     *
+     * @example
+     * ```typescript
+     * await client.agents.unassignKnowledgeBase('agent-123');
+     * ```
+     */
+    unassignKnowledgeBase(agentId: string): Promise<void>;
+}
+//# sourceMappingURL=agents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/client/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AACtD,OAAO,KAAK,EACV,KAAK,EACL,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,6BAA6B,EAC7B,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EAElB,MAAM,UAAU,CAAC;AAElB;;GAEG;AACH,qBAAa,WAAY,SAAQ,UAAU;gBAC7B,MAAM,EAAE,gBAAgB;IAIpC;;;;;;;;;;;;;;;;;;;OAmBG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,sBAAsB,GAAG,KAAK,EAAE,CAAC;IAUlF;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,MAAM,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,KAAK,CAAC;IAIzD;;;;;;;;;;;OAWG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAI9C;;;;;;;;;;;;;;;;OAgBG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,KAAK,CAAC;IAI1E;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI3D;;;;;;;;;;;;;OAaG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIzD;;;;;;;;;;;;;;;;OAgBG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI5D;;;;;;;;;;;;;;;;;OAiBG;IACG,gBAAgB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAI9E;;;;;;;;;;;;;;;;OAgBG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAIxE;;;;;;;;;;;;OAYG;IACG,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAKxE;;;;;;;;;OASG;IACG,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG5D"}

package/dist/client/agents.js

@@ -0,0 +1,233 @@
+/**
+ * Agent Management Client
+ *
+ * Provides methods for:
+ * - Creating, updating, and deleting agents
+ * - Deploying and pausing agents
+ * - Checking agent connection status
+ * - Managing agent knowledge bases
+ */
+import { BaseClient } from './base';
+/**
+ * Client for Agent management operations
+ */
+export class AgentClient extends BaseClient {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * List agents with optional pagination and filtering
+     *
+     * @param options - Pagination and filter options
+     * @returns Paginated list of agents or array of agents
+     *
+     * @example
+     * ```typescript
+     * // Get all deployed agents
+     * const result = await client.agents.list({
+     *   page: 1,
+     *   limit: 10,
+     *   show_statuses: ['deployed']
+     * });
+     *
+     * for (const agent of result.items) {
+     *   console.log(`${agent.name}: ${agent.status}`);
+     * }
+     * ```
+     */
+    async list(options) {
+        const params = {};
+        if (options?.page !== undefined)
+            params.page = options.page;
+        if (options?.limit !== undefined)
+            params.limit = options.limit;
+        if (options?.show_statuses)
+            params.show_statuses = options.show_statuses;
+        return super.get('/agent/', params);
+    }
+    /**
+     * Create a new agent
+     *
+     * @param options - Agent creation options
+     * @returns Created agent
+     *
+     * @example
+     * ```typescript
+     * const agent = await client.agents.create({
+     *   name: 'Customer Support Agent',
+     *   config: {
+     *     prompt: 'You are a helpful customer support agent.',
+     *     greeting: 'Hello! How can I help you today?',
+     *     tts_params: {
+     *       voice_id: 'my-voice-id'
+     *     }
+     *   }
+     * });
+     *
+     * console.log('Created agent:', agent.agent_id);
+     * ```
+     */
+    async create(options) {
+        return this.post('/agent/', options);
+    }
+    /**
+     * Get agent details by ID
+     *
+     * @param agentId - The agent ID
+     * @returns Agent details
+     *
+     * @example
+     * ```typescript
+     * const agent = await client.agents.getById('agent-123');
+     * console.log('Agent config:', agent.config);
+     * ```
+     */
+    async getById(agentId) {
+        return super.get(`/agent/${encodeURIComponent(agentId)}`);
+    }
+    /**
+     * Update an existing agent
+     *
+     * @param agentId - The agent ID to update
+     * @param options - Fields to update
+     * @returns Updated agent
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.agents.update('agent-123', {
+     *   name: 'Updated Agent Name',
+     *   config: {
+     *     greeting: 'Hi there! What can I do for you?'
+     *   }
+     * });
+     * ```
+     */
+    async update(agentId, options) {
+        return this.put(`/agent/${encodeURIComponent(agentId)}`, options);
+    }
+    /**
+     * Deploy an agent (prepare for phone calls)
+     *
+     * @param agentId - The agent ID to deploy
+     * @returns Deployment response with agent and status
+     *
+     * @example
+     * ```typescript
+     * const result = await client.agents.deploy('agent-123');
+     * console.log('Deployed:', result.message);
+     * console.log('SIP status:', result.sip_status);
+     * ```
+     */
+    async deploy(agentId) {
+        return this.post(`/agent/${encodeURIComponent(agentId)}/deploy`);
+    }
+    /**
+     * Pause an agent (frees phone number)
+     *
+     * This endpoint is idempotent.
+     *
+     * @param agentId - The agent ID to pause
+     * @returns Pause response with agent
+     *
+     * @example
+     * ```typescript
+     * const result = await client.agents.pause('agent-123');
+     * console.log('Agent status:', result.agent.status);
+     * ```
+     */
+    async pause(agentId) {
+        return this.post(`/agent/${encodeURIComponent(agentId)}/pause`);
+    }
+    /**
+     * Delete/disable an agent
+     *
+     * An agent must be paused before being deleted.
+     * Disabled agents will be automatically deleted after a grace period.
+     *
+     * @param agentId - The agent ID to delete
+     * @returns Delete response
+     *
+     * @example
+     * ```typescript
+     * // First pause, then delete
+     * await client.agents.pause('agent-123');
+     * const result = await client.agents.disable('agent-123');
+     * console.log('Deleted:', result.message);
+     * ```
+     */
+    async disable(agentId) {
+        return this.post(`/agent/${encodeURIComponent(agentId)}/disable`);
+    }
+    /**
+     * Initialize agent from template
+     *
+     * @param options - Template options
+     * @returns Template configuration and available types
+     *
+     * @example
+     * ```typescript
+     * // Get available templates
+     * const result = await client.agents.initFromTemplate();
+     * console.log('Available types:', result.available_types);
+     *
+     * // Initialize from specific template
+     * const template = await client.agents.initFromTemplate({
+     *   agent_template: 'customer_support'
+     * });
+     * ```
+     */
+    async initFromTemplate(options) {
+        return this.post('/agent/init-agent', options || {});
+    }
+    /**
+     * Check if an agent is available for connection
+     *
+     * @param agentId - The agent ID to check
+     * @returns Agent connection status
+     *
+     * @example
+     * ```typescript
+     * const status = await client.agents.getStatus('agent-123');
+     *
+     * if (status.call_allowed) {
+     *   console.log('Agent is available for calls');
+     * } else {
+     *   console.log('Reason:', status.call_validation_details);
+     * }
+     * ```
+     */
+    async getStatus(agentId) {
+        return super.get(`/connection/agent-status/${encodeURIComponent(agentId)}`);
+    }
+    /**
+     * Assign a knowledge base to an agent for RAG
+     *
+     * @param agentId - The agent ID
+     * @param kbId - The knowledge base ID to assign
+     * @returns Updated agent
+     *
+     * @example
+     * ```typescript
+     * const agent = await client.agents.assignKnowledgeBase('agent-123', 42);
+     * console.log('KB assigned:', agent.kb_id);
+     * ```
+     */
+    async assignKnowledgeBase(agentId, kbId) {
+        const body = { kb_id: kbId };
+        return this.post(`/agent/${encodeURIComponent(agentId)}/assign-knowledge-base`, body);
+    }
+    /**
+     * Remove knowledge base from an agent
+     *
+     * @param agentId - The agent ID
+     *
+     * @example
+     * ```typescript
+     * await client.agents.unassignKnowledgeBase('agent-123');
+     * ```
+     */
+    async unassignKnowledgeBase(agentId) {
+        await this.delete(`/agent/${encodeURIComponent(agentId)}/knowledge-base`);
+    }
+}
+//# sourceMappingURL=agents.js.map