aillom-vox-client 1.0.2 → 2.1.0

package/dist/pricing.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VOX_PROVIDER_RATECARD = void 0;
+exports.VOX_PROVIDER_RATECARD = [
+    {
+        label: 'AillomVox',
+        provider: 'aillomvox',
+        ttsEngineHint: 'inworld · xai · lmnt · soniox · rime · fish',
+        usdPerMinute: 0.04,
+        tier: 'Gateway',
+        modelSummary: 'Soniox STT · Groq Llama 3.3 70B · selectable TTS',
+        badge: 'Best Value',
+    },
+    { label: 'AWS Nova', provider: 'aws', usdPerMinute: 0.06, tier: 'S2S', modelSummary: 'nova-2-sonic' },
+    { label: 'Gemini', provider: 'gemini', usdPerMinute: 0.06, tier: 'S2S', modelSummary: 'gemini-3.1-flash-live-preview' },
+    { label: 'Qwen', provider: 'qwen', usdPerMinute: 0.06, tier: 'S2S', modelSummary: 'qwen3.5-omni-flash-realtime' },
+    { label: 'Grok', provider: 'grok', usdPerMinute: 0.1, tier: 'S2S', modelSummary: 'grok-voice-think-fast-1.0' },
+    { label: 'OpenAI', provider: 'openai', usdPerMinute: 0.1, tier: 'S2S', modelSummary: 'gpt-realtime-mini' },
+    { label: 'Ultravox', provider: 'ultravox', usdPerMinute: 0.1, tier: 'Premium', modelSummary: 'ultravox-70B' },
+];

package/dist/types.d.ts

@@ -1,37 +1,194 @@
-export type ProviderType = 'aillomvox' | 'gemini' | 'openai' | 'aws' | 'qwen' | 'grok' | 'ultravox';
-export interface MicrophoneConfig {
-    sampleRate?: 8000 | 16000 | 24000;
-    inputSampleRate?: number;
-}
+import type { AillomVoxTtsEngineId } from './constants';
+/**
+ * Known stable provider ids. The gateway may accept additional strings and normalizes aliases
+ * (see product docs / `GET /api/providers`).
+ */
+export type VoxProviderId = 'aillomvox' | 'openai' | 'gemini' | 'aws' | 'qwen' | 'grok' | 'ultravox' | (string & {});
 export interface ClientTool {
     name: string;
     description: string;
-    parameters: Record<string, any>;
+    /** JSON Schema parameters for the function (OpenAI-style). */
+    parameters?: Record<string, unknown>;
+    /** Backward-compatible location used by some dashboard / n8n tool presets. */
+    config?: Record<string, unknown>;
+    /** Optional server-side endpoint metadata, including `aillom-connect://...` tools. */
+    url?: string;
+    endpoint_url?: string;
+    endpointUrl?: string;
+    [key: string]: unknown;
 }
+export type VoxAuthMode = 'auto' | 'handshake' | 'header' | 'both';
 export interface AillomVoxConfig {
+    /**
+     * Gateway API key (`av_…`). **Secret** — treat like a password.
+     * In public web apps, anyone can extract a key shipped to the browser; prefer a
+     * server-issued short-lived token or a backend proxy that holds the real key.
+     */
     apiKey: string;
-    provider?: ProviderType;
+    /**
+     * WebSocket auth strategy. Default `auto` sends `x-api-key` from Node.js and falls
+     * back to the config `apikey` field in browsers, where custom WebSocket headers are unavailable.
+     */
+    authMode?: VoxAuthMode;
+    /** Lowercase provider id, e.g. `aillomvox`, `openai`. Default: `aillomvox`. */
+    provider?: VoxProviderId;
     voice?: string;
     language?: string;
+    /** Optional workspace scope; requires an API key authorized for that workspace. */
+    workspaceId?: string;
+    /**
+     * Required for production sessions per gateway docs; defaults are applied only client-side for quick tests.
+     */
     systemPrompt?: string;
     sampleRate?: 8000 | 16000 | 24000;
+    /**
+     * When true, logs outbound config (with `apikey` redacted) and unknown inbound JSON.
+     * Disable in production; logs and the `raw` event may contain user speech text (PII).
+     */
     debug?: boolean;
     tools?: ClientTool[];
+    /** HTTPS(S) webhook for server-side session events (if enabled for your key). */
     webhookUrl?: string;
+    /** Session cap in seconds (`30`-`7200`; default gateway cap is 300). */
     maxDuration?: number;
+    /** Spoken right after the session is ready. */
+    firstMessage?: string;
+    /** Spoken before forced hangup when `max_duration` is reached (see protocol docs). */
+    farewellMessage?: string;
+    /**
+     * When `provider === "aillomvox"`, selects the TTS stack from `GET /api/providers`.
+     * Defaults to **`inworld`** when omitted (the SDK sets `tts_engine` in the handshake).
+     */
+    ttsEngine?: AillomVoxTtsEngineId | string;
+    /**
+     * @deprecated Session model overrides are ignored by the current gateway; model selection
+     * is controlled server-side. Use `AillomVox.fetchProviders()` to inspect active defaults.
+     */
+    model?: string;
+    qualityProfile?: string;
+    toolTimeout?: number;
+    ttsBufferMs?: number;
+    ttsEarlyStartMs?: number;
+    ttsMinChunkMs?: number;
+    streamLlmTextToTts?: boolean;
+    accumulatorMs?: number;
+    /** Advanced provider config passed through as `extra_config`. Do not put browser-visible secrets here. */
+    extraConfig?: Record<string, unknown>;
+    /**
+     * WebSocket URL or HTTPS API origin. Examples:
+     * - `wss://vox.aillom.com/ws` (default)
+     * - `https://vox.aillom.com` (normalized to the same WebSocket URL)
+     */
     gatewayUrl?: string;
 }
 export interface TranscriptEvent {
+    type?: 'transcript';
     role: 'user' | 'assistant';
     text: string;
     final: boolean;
 }
 export interface ToolCallEvent {
+    type?: 'tool_call';
     call_id: string;
     name: string;
-    args: any;
+    args: Record<string, unknown>;
+}
+/** Agent state (Ultravox-oriented pipeline). */
+export type VoxAgentState = 'listening' | 'thinking' | 'speaking';
+export interface StateEvent {
+    type: 'state';
+    state: VoxAgentState;
+}
+/** Engine connection milestones from the gateway. */
+export interface ControlEvent {
+    type: 'control';
+    action?: string;
+    provider?: string;
+    model?: string;
+    tts_model?: string;
+    [key: string]: unknown;
+}
+export interface ErrorEvent {
+    type?: 'error';
+    message?: string;
+    error?: string;
+    code?: string;
+}
+export type EventHandler<T = unknown> = (data: T) => void;
+export interface ProvidersCatalogOptions {
+    /** Same base you use for `gatewayUrl` / clone API; defaults to production. */
+    baseUrl?: string;
+    /** When set, `x-api-key` must belong to that workspace (gateway returns 401/403 otherwise). */
+    workspaceId?: string;
+    /** Set false to skip nested voices in `/api/providers` for faster catalog loads. */
+    includeVoices?: boolean;
+    apiKey?: string;
+}
+export interface VoicesCatalogOptions {
+    /** Provider or TTS engine id, e.g. `inworld`, `fish`, `aws`, `qwen`. */
+    provider: string;
+    baseUrl?: string;
+    /** When set, `x-api-key` must belong to that workspace. */
+    workspaceId?: string;
+    apiKey?: string;
+    pageSize?: number;
+    pageNumber?: number;
+    maxPages?: number;
+    q?: string;
+    title?: string;
+    tag?: string;
+    language?: string;
+    titleLanguage?: string;
+    sortBy?: string;
+    preferredLanguage?: string;
+    type?: string;
+    scope?: string;
+    visibility?: string;
+}
+export interface VoicePreviewOptions {
+    provider: string;
+    voice: string;
+    baseUrl?: string;
+}
+export interface DeleteVoiceOptions {
+    provider?: string;
+    workspaceId?: string;
+    baseUrl?: string;
+}
+export interface CloneVoiceProviderResult {
+    status: 'ok' | 'skipped' | 'error' | string;
+    voice_id?: string;
+    name?: string;
+    error?: string;
+    [key: string]: unknown;
 }
-export interface AudioEvent {
-    buffer: ArrayBuffer;
+export interface CloneVoiceResult {
+    voice_id: string | null;
+    name?: string;
+    workspace_id?: string | null;
+    providers?: Record<string, CloneVoiceProviderResult>;
+    message?: string;
+    [key: string]: unknown;
+}
+export interface CloneVoiceOptions {
+    name?: string;
+    description?: string;
+    baseUrl?: string;
+    gatewayUrl?: string;
+    filename?: string;
+    workspaceId?: string;
+    /** Comma-separated internally by the SDK. Defaults to the server route defaults. */
+    providers?: string[];
+    /** BCP 47 locale, or `AUTO`. Helps providers that need language hints. */
+    language?: string;
+    /** Exact transcript of the audio sample; recommended for Inworld and Fish Audio. */
+    transcription?: string;
+    /** Alias accepted by the gateway. */
+    transcript?: string;
+    /** Optional xAI clone metadata. */
+    gender?: 'male' | 'female' | 'neutral';
+    accent?: string;
+    age?: 'young' | 'middle-aged' | 'old';
+    tone?: 'warm' | 'casual' | 'professional' | 'friendly' | 'authoritative' | 'expressive' | 'calm';
+    useCase?: 'conversational' | 'narration' | 'characters' | 'educational' | 'advertisement' | 'social_media' | 'entertainment';
 }
-export type EventHandler<T = any> = (data: T) => void;

package/package.json

@@ -1,13 +1,23 @@
 {
     "name": "aillom-vox-client",
-    "version": "1.0.2",
+    "version": "2.1.0",
     "description": "Enterprise-Grade Voice AI SDK for Speech-to-Speech, Audio-to-Audio, and Realtime Multimodal applications.",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
         "build": "tsc",
         "dev": "tsc --watch",
-        "test": "echo \"Error: no test specified\" && exit 1"
+        "typecheck": "tsc --noEmit",
+        "prepack": "npm run build",
+        "test": "npm run typecheck"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "engines": {
+        "node": ">=18"
     },
     "dependencies": {
         "isomorphic-ws": "^5.0.0",
@@ -34,12 +44,13 @@
         "low-latency",
         "voice-gateway",
         "sip-trunking",
-        "asterisk",
-        "inworld-ai",
-        "gpt-4o-realtime",
         "telephony",
         "ultravox",
-        "nova-sonic"
+        "nova-sonic",
+        "grok-voice",
+        "fish-audio",
+        "rime-ai",
+        "inworld-tts"
     ],
     "author": "Aillom Technologies <contato@aillom.com.br>",
     "license": "ISC",
@@ -47,4 +58,4 @@
         "url": "https://github.com/aillom/aillom-vox-client/issues"
     },
     "homepage": "https://vox.aillom.com"
-}
+}

package/docs/ASTERISK.md

@@ -1,411 +0,0 @@
-# 📞 Asterisk 23 Integration Guide - AillomVox
-
-Complete guide for integrating **Asterisk 23** with **AillomVox** for real-time Voice AI calls.
-
----
-
-## 🎯 Overview
-
-AillomVox provides **two integration architectures** for Asterisk:
-
-### 1. **Direct Mode** (Simple)
-```
-Asterisk → AudioSocket → AillomVox Gateway → AI Provider
-```
-✅ Simple voice conversations  
-❌ No client tools (transfer, AMI control)
-
-### 2. **Middleware Mode** (Advanced)
-```
-Asterisk → AudioSocket → Node.js Middleware → AillomVox Gateway
-                ↓ AMI/ARI
-```
-✅ Client tools enabled (transfer, hangup, dial)  
-✅ Full Asterisk control from AI
-
----
-
-## 📋 Prerequisites
-
-### Asterisk Requirements
-- **Asterisk 23** (or 18+)
-- **AudioSocket** module compiled and enabled
-- **API Key** for AillomVox gateway
-
-### Verify AudioSocket Module
-```bash
-asterisk -rx "module show like audiosocket"
-```
-
-Expected output:
-```
-Module                         Description
-res_audiosocket.so             AudioSocket
-```
-
-If not loaded:
-```bash
-# Load module
-asterisk -rx "module load res_audiosocket"
-
-# Make it persistent
-echo "load = res_audiosocket.so" >> /etc/asterisk/modules.conf
-```
-
----
-
-## 🔐 Authentication
-
-AillomVox uses **API Key** authentication for security and usage tracking.
-
-### Getting Your API Key
-
-Get your API key from the AillomVox dashboard or contact support.
-
-### Storing API Key
-
-Store in `extensions.conf`:
-
-```ini
-[globals]
-AILLOM_API_KEY=your-api-key-here
-```
-
----
-
-## 🏗️ Architecture 1: Direct Mode (Simple)
-
-### When to Use
-- Simple AI voice conversations
-- No need to transfer calls or control Asterisk
-- Just want AI to answer and respond
-
-### Dialplan Configuration
-
-```ini
-[from-internal]
-
-; Call extension 6000 to talk to AI
-exten => 6000,1,NoOp(AillomVox Direct Mode)
- same => n,Set(WS_URL=ws://vox.aillom.com/ws?apiKey=${AILLOM_API_KEY})
- same => n,Set(CONFIG={"provider":"aillomvox","voice":"Heitor","language":"pt-BR","system_prompt":"Você é um assistente. Seja conciso.","first_message":"Olá! Como posso ajudar?","sample_rate":8000})
- same => n,Answer()
- same => n,AudioSocket(${WS_URL},${CONFIG})
- same => n,Hangup()
-```
-
-### Configuration JSON
-
-```json
-{
-  "provider": "aillomvox",
-  "voice": "Heitor",
-  "language": "pt-BR",
-  "system_prompt": "Você é um assistente virtual.",
-  "first_message": "Olá! Como posso ajudar?",
-  "farewell_message": "Obrigado por ligar. Até logo!",
-  "sample_rate": 8000,
-  "max_duration": 300
-}
-```
-
-**Note**: No `tools` array needed in Direct Mode.
-
----
-
-## 🏗️ Architecture 2: Middleware Mode (Advanced)
-
-### When to Use
-- AI needs to **transfer** calls to extensions
-- AI needs to **hangup** via AMI (not just end conversation)
-- AI needs to **dial** external numbers
-- Advanced call control
-
-### Architecture
-```
-Asterisk → AudioSocket (port 9000) → Node.js Middleware
-                                            ↓
-                                       AMI/ARI Control
-                                            ↓
-                                     AillomVox Gateway
-```
-
-### Step 1: Install Dependencies
-
-```bash
-npm install aillom-vox-client asterisk-manager
-```
-
-### Step 2: Create Middleware (`asterisk-bridge.js`)
-
-```javascript
-const net = require('net');
-const AillomVoxClient = require('aillom-vox-client');
-const AMI = require('asterisk-manager');
-
-// AMI connection for Asterisk control
-const ami = new AMI(5038, 'localhost', 'admin', 'secret', true);
-
-ami.keepConnected();
-
-// AudioSocket server (receives from Asterisk)
-const server = net.createServer((socket) => {
-    console.log('[Bridge] New call from Asterisk');
-
-    // Connect to AillomVox
-    const client = new AillomVoxClient({
-        apiKey: process.env.AILLOM_API_KEY,
-        url: 'wss://vox.aillom.com/ws'
-    });
-
-    // Register client tools
-    client.connect({
-        provider: 'aillomvox',
-        voice: 'Heitor',
-        language: 'pt-BR',
-        system_prompt: 'Você é um assistente. Se o usuário pedir, transfira para ramal 100 ou desligue a ligação.',
-        sample_rate: 8000,
-        tools: [{
-            name: 'hangup',
-            description: 'End the call',
-            parameters: { type: 'object', properties: {} }
-        }, {
-            name: 'transfer',
-            description: 'Transfer call to extension',
-            parameters: {
-                type: 'object',
-                properties: {
-                    extension: { type: 'string', description: 'Target extension' }
-                },
-                required: ['extension']
-            }
-        }]
-    });
-
-    // Handle tool calls from AI
-    client.on('tool_call', async (tool) => {
-        console.log(`[Tool] AI called: ${tool.name}`, tool.args);
-        
-        if (tool.name === 'hangup') {
-            console.log('[Tool] Hanging up call');
-            socket.end();
-            client.disconnect();
-            return 'Call ended';
-        }
-        
-        if (tool.name === 'transfer') {
-            const ext = tool.args.extension;
-            console.log(`[Tool] Transferring to ${ext}`);
-            
-            // Use AMI to transfer (implement based on your channel tracking)
-            ami.action({
-                action: 'redirect',
-                channel: 'PJSIP/1234-00000001', // Track this from call setup
-                exten: ext,
-                context: 'from-internal',
-                priority: 1
-            });
-            
-            return `Transferred to extension ${ext}`;
-        }
-    });
-
-    // Pipe audio: Asterisk ↔ AillomVox
-    socket.on('data', (data) => {
-        // Parse AudioSocket protocol if needed, then send PCM
-        client.sendAudio(data);
-    });
-
-    client.on('audio', (pcmData) => {
-        socket.write(pcmData);
-    });
-
-    socket.on('end', () => {
-        console.log('[Bridge] Asterisk closed connection');
-        client.disconnect();
-    });
-});
-
-server.listen(9000, '127.0.0.1', () => {
-    console.log('[Bridge] Listening on 127.0.0.1:9000');
-});
-```
-
-### Step 3: Configure Asterisk
-
-```ini
-[from-internal]
-
-; Call extension 7000 using middleware (with client tools)
-exten => 7000,1,NoOp(AillomVox Middleware Mode)
- same => n,Set(CONFIG={"provider":"aillomvox"})
- same => n,Answer()
- same => n,AudioSocket(127.0.0.1:9000,${CONFIG})
- same => n,Hangup()
-```
-
-### Step 4: Run Middleware
-
-```bash
-AILLOM_API_KEY=your-api-key node asterisk-bridge.js
-```
-
-### Step 5: Test
-
-Call extension 7000 and say:
-- "Transfer me to extension 100" → AI calls `transfer` tool
-- "Goodbye" → AI calls `hangup` tool
-
----
-
-## 🎙️ Audio Format
-
-### AudioSocket Protocol
-- **Format**: PCM 16-bit signed little-endian (`slin`)
-- **Sample Rate**: 8000 Hz (telephony standard)
-- **Channels**: 1 (mono)
-- **Encoding**: `pcm_s16le`
-
-### Codec Conversion (ulaw/alaw → slin)
-
-**No Brasil e na maioria dos países**, trunks SIP usam:
-- **ulaw** (G.711μ) - Padrão nos EUA/Brasil
-- **alaw** (G.711a) - Padrão na Europa
-
-**Asterisk converte automaticamente**:
-```
-Trunk SIP (ulaw/alaw) → Asterisk → slin → AudioSocket → AillomVox
-```
-
-Não precisa configurar nada! Asterisk faz a conversão transparente.
-
-### Forcing Codec (Optional)
-
-Se tiver problemas de áudio, force o codec:
-
-```ini
-exten => 6000,1,Set(CHANNEL(audioreadformat)=slin)
- same => n,Set(CHANNEL(audiowriteformat)=slin)
- same => n,Answer()
- same => n,AudioSocket(...)
-```
-
-Isso garante que Asterisk sempre entrega PCM 16-bit para o AudioSocket.
-
----
-
-## 🌍 Multi-Provider Examples (Direct Mode)
-
-### AillomVox (Best for Telephony)
-
-```ini
-exten => 7001,1,Set(CONFIG={"provider":"aillomvox","voice":"Heitor","sample_rate":8000})
- same => n,AudioSocket(ws://vox.aillom.com/ws?apiKey=${AILLOM_API_KEY},${CONFIG})
-```
-
-**Why?** Lowest latency, optimized for 8kHz, $0.03/min.
-
-### Gemini 2.5 Flash
-
-```ini
-exten => 7002,1,Set(CONFIG={"provider":"gemini","voice":"Puck","sample_rate":8000})
- same => n,AudioSocket(ws://vox.aillom.com/ws?apiKey=${AILLOM_API_KEY},${CONFIG})
-```
-
-**Why?** Multimodal, fast, $0.06/min.
-
-### OpenAI Realtime
-
-```ini
-exten => 7003,1,Set(CONFIG={"provider":"openai","voice":"shimmer","sample_rate":8000})
- same => n,AudioSocket(ws://vox.aillom.com/ws?apiKey=${AILLOM_API_KEY},${CONFIG})
-```
-
-**Why?** Best for complex reasoning, $0.10/min.
-
----
-
-## ⚠️ Troubleshooting
-
-### Problem: "Module audiosocket not loaded"
-
-```bash
-asterisk -rx "module load res_audiosocket"
-echo "load = res_audiosocket.so" >> /etc/asterisk/modules.conf
-```
-
-### Problem: "Connection refused"
-
-**Direct Mode**: Check firewall, verify server is running  
-**Middleware Mode**: Ensure middleware is running on `127.0.0.1:9000`
-
-```bash
-# Test direct connection
-curl -I https://vox.aillom.com/health
-
-# Test middleware
-netstat -tuln | grep 9000
-```
-
-### Problem: "No audio"
-
-Force codec:
-```ini
-exten => 6000,1,Set(CHANNEL(audioreadformat)=slin)
- same => n,Set(CHANNEL(audiowriteformat)=slin)
- same => n,AudioSocket(...)
-```
-
----
-
-## 📊 Configuration Options
-
-| Field | Type | Description | Default |
-|-------|------|-------------|---------|
-| `provider` | string | `aillomvox`, `gemini`, `openai`, `qwen`, `grok`, `aws`, `ultravox` | **Required** |
-| `voice` | string | Voice ID (provider-specific) | **Required** |
-| `language` | string | `pt-BR`, `en-US`, `es-ES`, etc | `en-US` |
-| `system_prompt` | string | Instructions for AI | **Required** |
-| `first_message` | string | Initial greeting | `null` |
-| `farewell_message` | string | Goodbye message | `null` |
-| `sample_rate` | number | `8000` (tel), `16000` (hd) | **Required** |
-| `max_duration` | number | Max seconds (120-3600) | `300` |
-| `tools` | array | Client tools (Middleware only) | `[]` |
-
----
-
-## 🌐 Production Checklist
-
-- [ ] AudioSocket module loaded and persistent
-- [ ] API key stored securely in `[globals]`
-- [ ] Sample rate set to 8000 Hz
-- [ ] Max duration configured
-- [ ] If using Middleware: process manager (PM2, systemd)
-- [ ] If using Middleware: AMI credentials configured
-- [ ] Tested with real calls
-- [ ] Monitoring enabled
-
----
-
-## 💡 Which Architecture Should I Use?
-
-| Feature | Direct Mode | Middleware Mode |
-|---------|-------------|-----------------|
-| Simple conversations | ✅ Yes | ✅ Yes |
-| Transfer calls | ❌ No | ✅ Yes |
-| Hangup via AMI | ❌ No | ✅ Yes |
-| Dial external numbers | ❌ No | ✅ Yes |
-| Complexity | Low | Medium |
-| Setup | 2 minutes | 10 minutes |
-
-**Recommendation**: Start with **Direct Mode**. Upgrade to **Middleware** when you need client tools.
-
----
-
-## 📚 Additional Resources
-
-- [Client Tools Guide](TOOLS.md)
-- [AillomVox Protocol](PROTOCOL.md)
-- [Provider Comparison](PROVIDERS.md)
-
-Happy building! 🎉