aillom-vox-client 1.0.2 → 2.1.1

package/README.md

@@ -1,272 +1,173 @@
-# 🎙️ AillomVox Public Client
+# AillomVox client (TypeScript)
 
-[![npm version](https://img.shields.io/npm/v/aillom-vox-client.svg)](https://www.npmjs.com/package/aillom-vox-client)
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org/)
 
-**The Enterprise-Grade Voice AI SDK.** 
+Official **browser + Node.js** SDK for [AillomVox](https://vox.aillom.com): one WebSocket to the gateway (`wss://vox.aillom.com/ws`), PCM16 streaming, transcripts, tools, and REST helpers for the public catalog (`GET /api/providers`) and pricing (`GET /api/pricing`).
 
-Build **Speech-to-Speech**, **Audio-to-Audio**, and **Realtime Multimodal** applications with a single, unified protocol. 
-Connect effortlessly to **OpenAI Realtime**, **Gemini Multimodal**, **AWS Nova**, **Qwen**, **Grok**, **UltraVox**, and **AillomVox** native models.
+Companion server, dashboard, and adapter code ship from the Vox product monorepo; **this** repository is only the npm client surface.
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install aillom-vox-client
 ```
 
-## 📚 Documentation
-- [**Quick Start (SDK)**](#-quick-start-sdk) - The modern way
-- [**Quick Start (WebSocket)**](#-quick-start-websocket) - The low-level way
-- [**Examples**](#-examples) - Ready-to-use client implementations
-- [**N8N Integration**](#-n8n-node) - Official AillomVox node for n8n
-- [**Client Tools**](#-client-tools) - Add custom UI controls to your AI
-- [**Voice Catalog**](docs/VOICES.md) - All voices across all providers
-- [**Asterisk Integration**](docs/ASTERISK.md) - Complete guide for Asterisk 23/SIP
-- [**Protocol Specification**](docs/PROTOCOL.md) - WebSocket messages and binary formats
-- [**Supported Providers**](docs/PROVIDERS.md) - AI models and configuration options
-- [**Troubleshooting**](docs/TROUBLESHOOTING.md) - Common errors and solutions
+## Security considerations
 
----
-
-## 🚀 Key Features
-- **Unified API**: Switch between OpenAI, Gemini, and others by changing one string
-- **Real-Time Streaming**: Full-duplex WebSocket for sub-500ms latency
-- **65 Voices**: Full Inworld TTS 1.5 catalog across 15 languages
-- **Robust Audio**: Native PCM 16-bit at **8kHz**, **16kHz**, or **24kHz**
-- **Client Tools**: Add custom UI controls (hangup, alerts, navigation) to your AI
-- **15 Languages**: en, pt, es, fr, de, it, ja, zh, ko, hi, ar, ru, pl, nl, he
-- **Event Driven**: Simple event emitter (`audio`, `transcript`, `interrupt`)
-- **Enterprise Security**: Automatic key redaction and sanitized error messages
-
----
+- **API keys are secrets.** Never commit real keys, never paste them into public tickets or client-side source that ships to browsers unless you accept that end users can extract them.
+- **Browser apps:** a key embedded in frontend JavaScript or Web apps is visible in DevTools and bundled files. Safer patterns: your **backend** exchanges a session cookie or a **short-lived token** for voice access, or proxies the WebSocket with the real key on the server.
+- **Do not put `apikey` in the WebSocket URL** (e.g. `wss://.../ws?apiKey=...`). That string is prone to leaking via server logs, reverse proxies, and referrer headers. The SDK uses `x-api-key` headers in Node.js and falls back to the first JSON **`config.apikey`** field in browsers, where custom WebSocket headers are unavailable.
+- **`debug: true`:** logs structured config with `apikey` **redacted**, but may still log other inbound JSON; transcripts can contain **PII**. Keep `debug` off in production.
+- **TLS:** use **`wss://`** against production (`wss://vox.aillom.com/ws`), not `ws://`, except on trusted local networks.
+- **User data:** voice audio and transcripts flow through the gateway; document your own privacy policy and minimize what you log on the client.
 
-## 💰 Pricing & Performance
+## Documentation in this repo
 
-Choose the tier that fits your budget. **AillomVox** is optimized for telephony and high-volume use cases.
+| Doc | Purpose |
+| :--- | :--- |
+| [docs/PROTOCOL.md](docs/PROTOCOL.md) | WebSocket lifecycle, handshake JSON, PCM rules |
+| [docs/PROVIDERS.md](docs/PROVIDERS.md) | Provider matrix, **public USD/min rate card**, `tts_engine` for `aillomvox` |
+| [docs/VOICES.md](docs/VOICES.md) | Voice catalog notes |
+| [docs/TOOLS.md](docs/TOOLS.md) | Client-side tools |
+| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common failures |
 
-| Provider | Cost/Min | Tier | Recommended For |
-| :--- | :--- | :--- | :--- |
-| **AillomVox** | **$0.03** | 🚀 **Best Value** | High volume, Telephony, Support |
-| **Gemini** | $0.06 | Standard | Google Gemini 2.5 Flash. Multimodal |
-| **AWS** | $0.06 | Standard | AWS Nova Sonic 2. Enterprise |
-| **Qwen** | $0.06 | Standard | Alibaba Qwen Omni 3. Cost-effective |
-| **OpenAI** | $0.10 | Premium | GPT Realtime Mini. Logic-heavy |
-| **Grok** | $0.10 | Premium | Grok Beta. Witty personality |
-| **UltraVox** | $0.10 | Premium | High emotional intelligence |
-
-> **Why AillomVox?**  
-> Native optimized pipeline delivers **sub-500ms latency** and **8kHz support** at less than half the cost. Choose from **65 voices** with dynamic mid-conversation switching.
+Hosted docs: `https://vox.aillom.com/docs`
 
 ---
 
-## 📱 Examples
-
-This repository contains multiple examples ranging from a minimal connection script to full-featured dashboards and creative use cases.
+## What changed in v2.1
 
-| Folder | Level | Description |
-| :--- | :--- | :--- |
-| [`examples/01-basic`](./examples/01-basic) | ⭐ Beginner | Minimal HTML/JS implementation. Connects, sends defaults, streams audio. Perfect for understanding the core protocol. |
-| [`examples/02-advanced-dashboard`](./examples/02-advanced-dashboard) | ⭐⭐⭐ Expert | Full-featured UI with Dark Mode. Configures Voice, LLM Provider, Tools, and Visualizations. |
-| [`examples/03-smart-home`](./examples/03-smart-home) | ⭐⭐ Creative | A Smart Home Controller simulation. Use voice to "turn on lights" or "adjust temperature" via Tool Calling. |
-| [`examples/04-customer-support`](./examples/04-customer-support) | ⭐⭐ Industry | A CRM / Support Agent interface. Demonstrates integration with business data. |
+- The canonical WebSocket endpoint is **`wss://vox.aillom.com/ws`**. If you still have `wss://wss.aillom.com/ws` (or `https://wss.aillom.com`), the SDK migrates the host automatically via `normalizeWebSocketUrl()` and `migrateLegacyGatewayUrl()` — you can drop the legacy host from config whenever you like.
+- `gatewayUrl` accepts either a WebSocket URL **or** an HTTPS origin; both are normalized.
+- Auth now matches the live gateway: Node.js uses `x-api-key`; browser sessions keep using `config.apikey`.
+- New helpers: `AillomVox.fetchProviders({ includeVoices })`, `AillomVox.fetchPricing()`, `AillomVox.fetchVoices()`, `AillomVox.fetchVoicePreview()`, `AillomVox.deleteVoice()`, `AillomVox.cloneVoiceDetailed()`, `sendHangup()`, `sendText()`, and `sendImage()`.
+- Events: `playback_clear_buffer` (barge-in), `state`, `control`, and `raw` for advanced logging.
+- Config: `workspaceId`, `firstMessage`, `farewellMessage`, `ttsEngine` (for `provider: 'aillomvox'`), and advanced timing knobs. Per-session `model` overrides are ignored by the current gateway; use `fetchProviders()` to inspect server defaults.
 
 ---
 
-## ⚡ Quick Start (SDK)
-
-The easiest way to connect to AillomVox.
+## Quick start
 
 ```typescript
 import { AillomVox } from 'aillom-vox-client';
 
 const client = new AillomVox({
-  apiKey: 'av_YOUR_KEY',
-  voice: 'Edward',
-  debug: true
+  apiKey: process.env.AILLOMVOX_KEY!,
+  provider: 'aillomvox',
+  ttsEngine: 'inworld',
+  voice: 'Aanya',
+  language: 'en-US',
+  sampleRate: 16000,
+  systemPrompt: 'You are a concise, professional assistant.',
+  firstMessage: 'Hello! How can I help you today?',
 });
 
-client.on('transcript', (msg) => {
-  console.log(`[${msg.role}] ${msg.text}`);
+client.on('transcript', (t) => console.log(t.role, t.text));
+client.on('audio', (pcm) => {
+  /* Int16 LE mono — play or forward */
 });
-
-client.on('audio', (chunk) => {
-  // Play chunk (ArrayBuffer)
+client.on('playback_clear_buffer', () => {
+  /* Flush scheduled playback — user interrupted assistant */
 });
 
 await client.connect();
 ```
 
----
-
-## 🔌 Quick Start (WebSocket)
-
-If you prefer raw WebSockets (e.g. for Python, Go, or minimal JS):
+### Load the live provider + voice tree
 
-```javascript
-const ws = new WebSocket("wss://vox.aillom.com/ws");
-
-ws.onopen = () => {
-  ws.send(JSON.stringify({
-    type: "config",
-    apikey: "YOUR_API_KEY",
-    provider: "aillomvox",
-    voice: "Edward"
-  }));
-};
+```typescript
+import { AillomVox } from 'aillom-vox-client';
 
-ws.onmessage = (event) => {
-  if (event.data instanceof ArrayBuffer) {
-    playAudio(event.data);
-  }
-};
+const catalog = await AillomVox.fetchProviders({ includeVoices: false });
+const pricing = await AillomVox.fetchPricing();
+console.log({ catalog, pricing });
 ```
 
 ---
 
-## 🎤 Voices
-
-AillomVox uses **Inworld TTS 1.5** with 65 voices across 15 languages. See the full [Voice Catalog](docs/VOICES.md).
-
-### Top Picks
-
-| Voice | Gender | Style | Best For |
-| :--- | :--- | :--- | :--- |
-| **Edward** | Male | Fast-talking, emphatic | General purpose (default EN) |
-| **Julia** | Female | Quirky, playful | Customer support |
-| **Heitor** | Male | Composed, neutral | Portuguese (default PT) |
-| **Maitê** | Female | Professional | Portuguese |
-| **Ashley** | Female | Warm, natural | Sales, onboarding |
-| **Craig** | Male | Refined, articulate | Enterprise, authority |
-| **Diego** | Male | Soothing, gentle | Spanish (default ES) |
-| **Luna** | Female | Calm, relaxing | Wellness, concierge |
-
----
-
-## 🛠️ Client Tools
+### List pricing (USD / minute)
 
-**Client Tools** allow the AI to control your application's UI directly. When the AI decides to execute a tool, your app receives a callback and can respond.
+Published alongside the [marketing site](https://vox.aillom.com); full table in [docs/PROVIDERS.md](docs/PROVIDERS.md). The SDK exports the same rows as data:
 
-### Registering Tools
+```typescript
+import { VOX_PROVIDER_RATECARD } from 'aillom-vox-client';
 
-```javascript
-{
-    "provider": "aillomvox",
-    "voice": "Edward",
-    "tools": [
-        {
-            "name": "hangup",
-            "description": "End the call when user says goodbye.",
-            "parameters": { "type": "object", "properties": {} }
-        },
-        {
-            "name": "show_alert",
-            "description": "Show alert to user",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "message": { "type": "string", "description": "Alert message" }
-                },
-                "required": ["message"]
-            }
-        }
-    ]
+for (const row of VOX_PROVIDER_RATECARD) {
+  console.log(row.label, row.provider, row.usdPerMinute);
 }
 ```
 
-### Handling Tool Calls (Client-Side)
+The live endpoint is the preferred source for public list prices. Invoices can differ (credits, negotiated SKUs). Use the product billing UI as the contract.
 
-```javascript
-socket.onmessage = (event) => {
-    if (typeof event.data !== 'string') return;
-    const msg = JSON.parse(event.data);
-    
-    if (msg.type === 'tool_call') {
-        console.log(`Tool requested: ${msg.name}`, msg.args);
-        
-        let result = 'OK';
-        if (msg.name === 'hangup') {
-            disconnect();
-            result = 'Call ended';
-        } else if (msg.name === 'show_alert') {
-            alert(msg.args.message);
-            result = 'Alert displayed';
-        }
-
-        // Always respond — AI waits for this (15s timeout)
-        socket.send(JSON.stringify({
-            type: 'tool_result',
-            call_id: msg.call_id,
-            result: result
-        }));
-    }
-};
-```
 
----
+### Current public providers and prices
 
-## 🔧 Advanced Configuration
+Use `AillomVox.fetchPricing()` for the live table. Current public list prices:
 
-### Audio Formats
+| Provider | Model / stack | USD/min |
+| :--- | :--- | ---: |
+| `aillomvox` | Soniox STT · Groq Llama 3.3 70B · selectable TTS | **0.04** |
+| `aws` | nova-2-sonic | **0.06** |
+| `gemini` | gemini-3.1-flash-live-preview | **0.06** |
+| `qwen` | qwen3.5-omni-flash-realtime | **0.06** |
+| `grok` | grok-voice-think-fast-1.0 | **0.10** |
+| `openai` | gpt-realtime-mini | **0.10** |
+| `ultravox` | ultravox-70B | **0.10** |
 
-```javascript
-{
-    sample_rate: 16000,  // 8000 (telephony), 16000 (standard), 24000 (high-quality)
-    // Audio is PCM 16-bit little-endian Mono
-}
-```
+For `provider: 'aillomvox'`, current TTS engines are `inworld`, `xai`, `lmnt`, `soniox`, `rime`, and `fish`. Cartesia is disabled in the public client docs for now; `aillomvoxmax` is deprecated.
 
-### Session Limits
+---
 
-```javascript
-{
-    max_duration: 300,  // 1-3600 seconds (default: 300 = 5 minutes)
-}
-```
+## Raw WebSocket (no SDK)
 
-At 15 seconds remaining, the AI will say the `farewell_message`. At 0 seconds, the connection closes.
+```javascript
+const ws = new WebSocket('wss://vox.aillom.com/ws');
 
-### Multi-Language Support
+ws.onopen = () => {
+  ws.send(JSON.stringify({
+    type: 'config',
+    apikey: 'YOUR_API_KEY',
+    provider: 'aillomvox',
+    tts_engine: 'inworld',
+    voice: 'Aanya',
+    language: 'en-US',
+    sample_rate: 16000,
+    system_prompt: 'You are a helpful assistant.',
+  }));
+};
 
-```javascript
-{
-    language: 'pt-BR',
-    voice: 'Heitor',  // or 'Maitê' for female
-    system_prompt: 'Você é um assistente da Aillom. Seja conciso.',
-    first_message: 'Olá! Como posso ajudar?',
-    farewell_message: 'Obrigado por ligar. Até logo!'
-}
+ws.onmessage = (event) => {
+  if (event.data instanceof ArrayBuffer) {
+    /* PCM chunk */
+  }
+};
 ```
 
-Supported: `en-US`, `pt-BR`, `es-ES`, `fr-FR`, `de-DE`, `it-IT`, `ja-JP`, `ko-KR`, `zh-CN`, `hi-IN`, `ar-SA`, `ru-RU`, `pl-PL`, `nl-NL`, `he-IL`
-
 ---
 
-## 🛡️ Security & Limits
+## Examples
 
-### Automatic Sanitization
-- All error messages are stripped of sensitive data
-- API keys are never exposed in logs
-- Client cannot access server-side resources
+See **[examples/README.md](examples/README.md)** for how to run the browser demos and the TypeScript sample (`npx serve`, `tsx`, API keys).
 
-### Rate Limits
-- **Concurrent**: 3 connections per user, 2 per API key
-- **Max Duration**: 1-60 minutes per call
-- **Default**: 5 minutes per session
-- **Behavior**: Warning at 15s remaining, force disconnect at 0s
+| Path | Description |
+| :--- | :--- |
+| [examples/sdk-usage.ts](examples/sdk-usage.ts) | TypeScript sample with catalog fetch + handlers |
+| [examples/01-basic/](examples/01-basic/) | Minimal browser demo |
+| [examples/02-advanced-dashboard/](examples/02-advanced-dashboard/) | Larger UI example |
+| [examples/03-smart-home/](examples/03-smart-home/) | Tool-calling illustration |
+| [examples/04-customer-support/](examples/04-customer-support/) | Support-style UI |
 
 ---
 
-## 🤝 Support
+## Voice clone (REST)
 
-- **Documentation**: [https://vox.aillom.com/docs](https://vox.aillom.com/docs)
-- **Issues**: [GitHub Issues](https://github.com/aillom/aillom-vox-client/issues)
-- **Email**: contato@aillom.com.br
+`AillomVox.cloneVoice(blob, apiKey, { gatewayUrl, workspaceId, providers, language, transcription })` posts to `/api/voices/clone` with `x-api-key` and returns the primary `voice_id`. Use `cloneVoiceDetailed()` when you need the per-provider clone result, and `deleteVoice()` to remove a workspace-owned clone. Production voice cloning is unlocked after the user's first paid top-up; the free $1.00 signup credit is for call testing.
 
 ---
 
-## 📄 License
+## License
 
 ISC © Aillom Technologies

package/dist/AillomVox.d.ts

@@ -1,36 +1,95 @@
-import { AillomVoxConfig, TranscriptEvent, ToolCallEvent } from './types';
+import { AillomVoxConfig, CloneVoiceOptions, CloneVoiceResult, DeleteVoiceOptions, ErrorEvent, EventHandler, ProvidersCatalogOptions, StateEvent, ToolCallEvent, TranscriptEvent, VoicePreviewOptions, VoicesCatalogOptions } from './types';
+import WebSocket from 'isomorphic-ws';
+export type ClientEvent = 'audio' | 'transcript' | 'tool_call' | 'error' | 'connected' | 'disconnected' | 'interruption' | 'playback_clear_buffer' | 'state' | 'control' | 'raw';
+export interface VoxClientEventMap {
+    audio: ArrayBuffer | Buffer;
+    transcript: TranscriptEvent;
+    tool_call: ToolCallEvent;
+    error: ErrorEvent | WebSocket.ErrorEvent | unknown;
+    connected: Record<string, never>;
+    disconnected: {
+        code?: number;
+        reason?: string;
+    };
+    interruption: Record<string, never>;
+    playback_clear_buffer: Record<string, never>;
+    state: StateEvent;
+    control: Record<string, unknown>;
+    raw: Record<string, unknown>;
+}
+/**
+ * Browser or Node.js WebSocket client for the AillomVox voice gateway.
+ *
+ * Protocol summary: after `connect()`, the first outbound message must be the JSON `config`
+ * handshake (sent automatically). All further outbound binary messages are PCM16 mono chunks.
+ */
 export declare class AillomVox {
     private ws;
-    private config;
-    private eventListeners;
+    private readonly config;
+    private readonly eventListeners;
     private isConnected;
-    private url;
+    private readonly url;
     constructor(config: AillomVoxConfig);
+    /** Resolved WebSocket URL after normalization. */
+    get websocketUrl(): string;
+    /** True when the underlying WebSocket is open. */
+    get connected(): boolean;
     /**
-     * Connects to the AillomVox Gateway
+     * Connects to the gateway and sends the `config` handshake as the first message.
      */
     connect(): Promise<void>;
+    private createWebSocket;
+    private shouldUseHeaderAuth;
+    private shouldSendHandshakeApiKey;
     /**
-     * Sends audio chunk (PCM 16-bit) to the AI
+     * Send microphone capture to the model. PCM16 LE mono at the configured `sampleRate`.
      */
     sendAudio(chunk: ArrayBuffer | Int16Array | Buffer): void;
     /**
-     * Sends a tool result back to the AI
-     */
-    sendToolResult(callId: string, result: any): void;
-    /**
-     * Disconnects the session
+     * Reply to a `tool_call` event within 15 seconds or the model may stall.
      */
+    sendToolResult(callId: string, result: unknown): void;
+    /** Ask the server to end the call (mirrors dashboard playground). */
+    sendHangup(): void;
+    /** Send a text turn over the same WebSocket session. */
+    sendText(text: string): void;
+    /** Send image payload data for gateways with vision support. */
+    sendImage(data: string | Record<string, unknown>): void;
+    private sendJson;
     disconnect(): void;
-    /**
-     * Subscribes to an event
-     */
-    on(event: 'audio', handler: (data: ArrayBuffer) => void): void;
-    on(event: 'transcript', handler: (data: TranscriptEvent) => void): void;
-    on(event: 'tool_call', handler: (data: ToolCallEvent) => void): void;
-    on(event: 'error', handler: (error: any) => void): void;
-    on(event: 'connected' | 'disconnected' | 'interruption', handler: (data: any) => void): void;
+    on<K extends keyof VoxClientEventMap>(event: K, handler: EventHandler<VoxClientEventMap[K]>): void;
+    on(event: string, handler: EventHandler): void;
+    off<K extends keyof VoxClientEventMap>(event: K, handler: EventHandler<VoxClientEventMap[K]>): void;
+    off(event: string, handler: EventHandler): void;
     private sendConfig;
     private handleMessage;
     private emit;
+    /**
+     * `GET /api/providers` — models and nested voices (public; optional auth for workspace scoping).
+     */
+    static fetchProviders(options?: ProvidersCatalogOptions): Promise<unknown>;
+    /**
+     * `GET /api/pricing` — public USD/min rate card from the live gateway.
+     */
+    static fetchPricing(options?: {
+        baseUrl?: string;
+    }): Promise<unknown>;
+    /**
+     * `GET /api/voices` — optional provider filter matches dashboard catalog keys.
+     */
+    static fetchVoices(options: VoicesCatalogOptions): Promise<unknown>;
+    /** Build the public `/api/voices/preview` URL for a provider voice. */
+    static buildVoicePreviewUrl(options: VoicePreviewOptions): string;
+    /** `GET /api/voices/preview` — returns an audio Blob for UI preview playback. */
+    static fetchVoicePreview(options: VoicePreviewOptions): Promise<Blob>;
+    /** `DELETE /api/voices/:id` — removes a workspace-owned cloned voice. */
+    static deleteVoice(voiceId: string, apiKey: string, options?: DeleteVoiceOptions): Promise<unknown>;
+    /**
+     * Upload a short clean recording to create a cloned voice handle.
+     */
+    static cloneVoice(clip: Blob, apiKey: string, options?: CloneVoiceOptions): Promise<string>;
+    /**
+     * Upload a short clean recording and return the full multi-provider clone response.
+     */
+    static cloneVoiceDetailed(clip: Blob, apiKey: string, options?: CloneVoiceOptions): Promise<CloneVoiceResult>;
 }