voice-router-dev 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SAS SPOKE / Meeting BaaS
+
+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,455 @@
+# Voice Router SDK
+
+> Universal speech-to-text router for 6+ transcription providers with a single, unified API.
+
+[![npm version](https://badge.fury.io/js/voice-router-dev.svg)](https://www.npmjs.com/package/voice-router-dev)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
+
+## Why Voice Router?
+
+Switch between speech-to-text providers **without changing your code**. One API for Gladia, AssemblyAI, Deepgram, Azure, OpenAI Whisper, and Speechmatics.
+
+```typescript
+import { VoiceRouter } from 'voice-router-dev';
+
+const router = new VoiceRouter({
+  providers: {
+    gladia: { apiKey: process.env.GLADIA_KEY },
+    deepgram: { apiKey: process.env.DEEPGRAM_KEY }
+  }
+});
+
+// Same code works with ANY provider
+const result = await router.transcribe(audio, {
+  provider: 'gladia'  // Switch to 'deepgram' anytime
+});
+```
+
+## Features
+
+- 🔄 **Provider-Agnostic** - Switch providers with one line
+- 🎯 **Unified API** - Same interface for all providers
+- 📦 **Webhook Normalization** - Auto-detect and parse webhooks
+- 🔊 **Real-time Streaming** - WebSocket support (Gladia, AssemblyAI, Deepgram)
+- 📊 **Advanced Features** - Diarization, sentiment, summarization
+- 🔒 **Type-Safe** - Full TypeScript support
+- ⚡ **Provider Fallback** - Automatic failover strategies
+- 🎨 **Zero Config** - Works out of the box
+
+## Supported Providers
+
+| Provider | Batch | Streaming | Webhooks | Special Features |
+|----------|-------|-----------|----------|------------------|
+| **Gladia** | ✅ | ✅ WebSocket | ✅ | Multi-language, code-switching |
+| **AssemblyAI** | ✅ | ✅ Real-time | ✅ HMAC | Auto chapters, content moderation |
+| **Deepgram** | ✅ Sync | ✅ WebSocket | ✅ | PII redaction, keyword boosting |
+| **Azure STT** | ✅ Async | ❌ | ✅ HMAC | Custom models, language ID |
+| **OpenAI Whisper** | ✅ Sync | ❌ | ❌ | gpt-4o, multi-model support |
+| **Speechmatics** | ✅ Async | ❌ | ✅ Query params | High accuracy, enhanced mode |
+
+## Installation
+
+```bash
+npm install voice-router-dev
+# or
+pnpm add voice-router-dev
+# or
+yarn add voice-router-dev
+```
+
+## Quick Start
+
+### Basic Transcription
+
+```typescript
+import { VoiceRouter, GladiaAdapter } from 'voice-router-dev';
+
+// Initialize router
+const router = new VoiceRouter({
+  providers: {
+    gladia: { apiKey: 'YOUR_GLADIA_KEY' }
+  },
+  defaultProvider: 'gladia'
+});
+
+// Register adapter
+router.registerAdapter(new GladiaAdapter());
+
+// Transcribe from URL
+const result = await router.transcribe({
+  type: 'url',
+  url: 'https://example.com/audio.mp3'
+}, {
+  language: 'en',
+  diarization: true
+});
+
+if (result.success) {
+  console.log('Transcript:', result.data.text);
+  console.log('Speakers:', result.data.speakers);
+}
+```
+
+### Multi-Provider with Fallback
+
+```typescript
+import {
+  VoiceRouter,
+  GladiaAdapter,
+  AssemblyAIAdapter,
+  DeepgramAdapter
+} from 'voice-router-dev';
+
+const router = new VoiceRouter({
+  providers: {
+    gladia: { apiKey: process.env.GLADIA_KEY },
+    assemblyai: { apiKey: process.env.ASSEMBLYAI_KEY },
+    deepgram: { apiKey: process.env.DEEPGRAM_KEY }
+  },
+  selectionStrategy: 'round-robin'  // Auto load-balance
+});
+
+// Register all providers
+router.registerAdapter(new GladiaAdapter());
+router.registerAdapter(new AssemblyAIAdapter());
+router.registerAdapter(new DeepgramAdapter());
+
+// Automatically rotates between providers
+await router.transcribe(audio1);  // Uses Gladia
+await router.transcribe(audio2);  // Uses AssemblyAI
+await router.transcribe(audio3);  // Uses Deepgram
+```
+
+### Real-time Streaming
+
+```typescript
+import { VoiceRouter, DeepgramAdapter } from 'voice-router-dev';
+
+const router = new VoiceRouter({
+  providers: {
+    deepgram: { apiKey: process.env.DEEPGRAM_KEY }
+  }
+});
+
+router.registerAdapter(new DeepgramAdapter());
+
+// Start streaming session
+const session = await router.transcribeStream({
+  provider: 'deepgram',
+  encoding: 'linear16',
+  sampleRate: 16000,
+  language: 'en',
+  interimResults: true
+}, {
+  onTranscript: (event) => {
+    if (event.isFinal) {
+      console.log('Final:', event.text);
+    } else {
+      console.log('Interim:', event.text);
+    }
+  },
+  onError: (error) => console.error(error)
+});
+
+// Send audio chunks
+const audioStream = getMicrophoneStream();
+for await (const chunk of audioStream) {
+  await session.sendAudio({ data: chunk });
+}
+
+await session.close();
+```
+
+### Webhook Normalization
+
+```typescript
+import express from 'express';
+import { WebhookRouter } from 'voice-router-dev';
+
+const app = express();
+const webhookRouter = new WebhookRouter();
+
+// Single endpoint handles ALL providers
+app.post('/webhooks/transcription', express.json(), (req, res) => {
+  // Auto-detect provider from payload
+  const result = webhookRouter.route(req.body, {
+    queryParams: req.query,
+    userAgent: req.headers['user-agent'],
+    verification: {
+      signature: req.headers['x-signature'],
+      secret: process.env.WEBHOOK_SECRET
+    }
+  });
+
+  if (!result.success) {
+    return res.status(400).json({ error: result.error });
+  }
+
+  // Unified format across all providers
+  console.log('Provider:', result.provider);  // 'gladia' | 'assemblyai' | etc
+  console.log('Event:', result.event?.eventType);  // 'transcription.completed'
+  console.log('ID:', result.event?.data?.id);
+  console.log('Text:', result.event?.data?.text);
+
+  res.json({ received: true });
+});
+```
+
+## Advanced Usage
+
+### Provider-Specific Features
+
+```typescript
+// Gladia - Multi-language detection
+const result = await router.transcribe(audio, {
+  provider: 'gladia',
+  languageDetection: true,
+  summarization: true,
+  sentimentAnalysis: true
+});
+
+// AssemblyAI - Content moderation
+const result = await router.transcribe(audio, {
+  provider: 'assemblyai',
+  entityDetection: true,
+  metadata: {
+    content_safety: true,
+    auto_chapters: true
+  }
+});
+
+// Deepgram - PII redaction
+const result = await router.transcribe(audio, {
+  provider: 'deepgram',
+  piiRedaction: true,
+  customVocabulary: ['technical', 'terms']
+});
+
+// OpenAI Whisper - Model selection
+const result = await router.transcribe(audio, {
+  provider: 'openai-whisper',
+  metadata: {
+    model: 'gpt-4o-transcribe',  // or 'whisper-1'
+    temperature: 0.2
+  }
+});
+
+// Speechmatics - Enhanced accuracy
+const result = await router.transcribe(audio, {
+  provider: 'speechmatics',
+  metadata: {
+    operating_point: 'enhanced',  // Higher accuracy
+    enable_sentiment_analysis: true
+  }
+});
+```
+
+### Error Handling
+
+```typescript
+const result = await router.transcribe(audio, {
+  provider: 'gladia',
+  language: 'en'
+});
+
+if (!result.success) {
+  console.error('Provider:', result.provider);
+  console.error('Error:', result.error);
+  console.error('Details:', result.data);
+
+  // Implement fallback strategy
+  const fallbackResult = await router.transcribe(audio, {
+    provider: 'assemblyai'  // Try different provider
+  });
+}
+```
+
+### Custom Provider Selection
+
+```typescript
+// Explicit provider selection
+const router = new VoiceRouter({
+  providers: {
+    gladia: { apiKey: '...' },
+    deepgram: { apiKey: '...' }
+  },
+  selectionStrategy: 'explicit'  // Must specify provider
+});
+
+// Round-robin load balancing
+const router = new VoiceRouter({
+  providers: { /* ... */ },
+  selectionStrategy: 'round-robin'
+});
+
+// Default fallback
+const router = new VoiceRouter({
+  providers: { /* ... */ },
+  defaultProvider: 'gladia',
+  selectionStrategy: 'default'
+});
+```
+
+## API Reference
+
+### VoiceRouter
+
+Main class for provider-agnostic transcription.
+
+**Constructor:**
+```typescript
+new VoiceRouter(config: VoiceRouterConfig)
+```
+
+**Methods:**
+- `registerAdapter(adapter: TranscriptionAdapter)` - Register a provider adapter
+- `transcribe(audio: AudioInput, options?: TranscribeOptions)` - Transcribe audio
+- `transcribeStream(options: StreamingOptions, callbacks: StreamingCallbacks)` - Stream audio
+- `getTranscript(id: string, provider: string)` - Get transcript by ID
+- `getProviderCapabilities(provider: string)` - Get provider features
+
+### WebhookRouter
+
+Automatic webhook detection and normalization.
+
+**Methods:**
+- `route(payload: unknown, options?: WebhookRouterOptions)` - Parse webhook
+- `detectProvider(payload: unknown)` - Detect provider from payload
+- `validate(payload: unknown)` - Validate webhook structure
+
+### Adapters
+
+Provider-specific implementations:
+- `GladiaAdapter` - Gladia transcription
+- `AssemblyAIAdapter` - AssemblyAI transcription
+- `DeepgramAdapter` - Deepgram transcription
+- `AzureSTTAdapter` - Azure Speech-to-Text
+- `OpenAIWhisperAdapter` - OpenAI Whisper
+- `SpeechmaticsAdapter` - Speechmatics transcription
+
+## TypeScript Support
+
+Full type definitions included:
+
+```typescript
+import type {
+  VoiceRouter,
+  VoiceRouterConfig,
+  AudioInput,
+  TranscribeOptions,
+  UnifiedTranscriptResponse,
+  StreamingSession,
+  StreamingOptions,
+  UnifiedWebhookEvent,
+  TranscriptionProvider
+} from 'voice-router-dev';
+```
+
+## Requirements
+
+- **Node.js**: 20.0.0 or higher
+- **TypeScript**: 5.0+ (optional)
+- **Package Managers**: npm, pnpm, or yarn
+
+## Documentation
+
+- **Full API Docs**: [Generated TypeDoc](https://github.com/Meeting-Baas/sdk-generator/tree/main/docs/generated)
+- **Provider Integration Guide**: See `PROVIDER_INTEGRATION_PLAN.md`
+- **Examples**: See `examples/` directory
+
+## Provider Setup Guides
+
+### Gladia
+```typescript
+import { VoiceRouter, GladiaAdapter } from 'voice-router-dev';
+
+const router = new VoiceRouter({
+  providers: { gladia: { apiKey: 'YOUR_KEY' } }
+});
+router.registerAdapter(new GladiaAdapter());
+```
+
+Get your API key: https://gladia.io
+
+### AssemblyAI
+```typescript
+import { VoiceRouter, AssemblyAIAdapter } from 'voice-router-dev';
+
+const router = new VoiceRouter({
+  providers: { assemblyai: { apiKey: 'YOUR_KEY' } }
+});
+router.registerAdapter(new AssemblyAIAdapter());
+```
+
+Get your API key: https://assemblyai.com
+
+### Deepgram
+```typescript
+import { VoiceRouter, DeepgramAdapter } from 'voice-router-dev';
+
+const router = new VoiceRouter({
+  providers: { deepgram: { apiKey: 'YOUR_KEY' } }
+});
+router.registerAdapter(new DeepgramAdapter());
+```
+
+Get your API key: https://deepgram.com
+
+### Azure Speech-to-Text
+```typescript
+import { VoiceRouter, AzureSTTAdapter } from 'voice-router-dev';
+
+const router = new VoiceRouter({
+  providers: {
+    'azure-stt': {
+      apiKey: 'YOUR_KEY',
+      region: 'eastus'  // Required
+    }
+  }
+});
+router.registerAdapter(new AzureSTTAdapter());
+```
+
+Get your credentials: https://azure.microsoft.com/en-us/services/cognitive-services/speech-to-text/
+
+### OpenAI Whisper
+```typescript
+import { VoiceRouter, OpenAIWhisperAdapter } from 'voice-router-dev';
+
+const router = new VoiceRouter({
+  providers: { 'openai-whisper': { apiKey: 'YOUR_KEY' } }
+});
+router.registerAdapter(new OpenAIWhisperAdapter());
+```
+
+Get your API key: https://platform.openai.com
+
+### Speechmatics
+```typescript
+import { VoiceRouter, SpeechmaticsAdapter } from 'voice-router-dev';
+
+const router = new VoiceRouter({
+  providers: { speechmatics: { apiKey: 'YOUR_KEY' } }
+});
+router.registerAdapter(new SpeechmaticsAdapter());
+```
+
+Get your API key: https://speechmatics.com
+
+## Contributing
+
+Contributions welcome! Please read our [Contributing Guide](CONTRIBUTING.md).
+
+## License
+
+MIT © [Lazare Zemliak](https://github.com/Meeting-Baas)
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/Meeting-Baas/sdk-generator/issues)
+- **Repository**: [GitHub](https://github.com/Meeting-Baas/sdk-generator)
+
+---
+
+**Note**: This is a development version (`voice-router-dev`). The stable release will be published as `voice-router`.