voice-router-dev 0.1.8 → 0.2.0

package/README.md

@@ -330,7 +330,7 @@ Provider-specific implementations:
 
 ## TypeScript Support
 
-Full type definitions included:
+Full type definitions included with **provider-specific type safety**:
 
 ```typescript
 import type {
@@ -346,6 +346,108 @@ import type {
 } from 'voice-router-dev';
 ```
 
+### Provider-Specific Type Safety
+
+**🎯 New: Type-safe responses with provider discrimination**
+
+The SDK now provides full type safety for provider-specific responses:
+
+```typescript
+// Generic response - raw field is unknown
+const result: UnifiedTranscriptResponse = await router.transcribe(audio);
+
+// Provider-specific response - raw field is properly typed!
+const deepgramResult: UnifiedTranscriptResponse<'deepgram'> = await router.transcribe(audio, {
+  provider: 'deepgram'
+});
+
+// ✅ TypeScript knows raw is ListenV1Response
+const metadata = deepgramResult.raw?.metadata;
+const model = deepgramResult.raw?.results?.channels?.[0]?.alternatives?.[0]?.model;
+```
+
+**Provider-specific raw response types:**
+- `gladia` → `PreRecordedResponse`
+- `deepgram` → `ListenV1Response`
+- `openai-whisper` → `CreateTranscription200One`
+- `assemblyai` → `AssemblyAITranscript`
+- `azure-stt` → `AzureTranscription`
+
+### Exported Parameter Enums
+
+**🎯 New: Direct access to provider parameter enums**
+
+Import and use provider-specific enums for type-safe configuration:
+
+```typescript
+import {
+  // Deepgram enums
+  ListenV1EncodingParameter,
+  ListenV1ModelParameter,
+  SpeakV1EncodingParameter,
+
+  // Gladia enums
+  StreamingSupportedEncodingEnum,
+  StreamingSupportedSampleRateEnum,
+
+  // OpenAI types
+  AudioResponseFormat
+} from 'voice-router-dev';
+
+// ✅ Type-safe Deepgram encoding
+const session = await router.transcribeStream({
+  provider: 'deepgram',
+  encoding: ListenV1EncodingParameter.linear16,  // Autocomplete works!
+  model: ListenV1ModelParameter['nova-2'],
+  sampleRate: 16000
+});
+
+// ✅ Type-safe Gladia encoding
+const gladiaSession = await router.transcribeStream({
+  provider: 'gladia',
+  encoding: StreamingSupportedEncodingEnum['wav/pcm'],
+  sampleRate: StreamingSupportedSampleRateEnum['16000']
+});
+```
+
+### Type-Safe Streaming Options
+
+Streaming options are now fully typed based on provider OpenAPI specifications:
+
+```typescript
+// Deepgram streaming - all options are type-safe
+const deepgramSession = await router.transcribeStream({
+  provider: 'deepgram',
+  encoding: 'linear16',           // ✅ Only Deepgram encodings
+  model: 'nova-3',                // ✅ Validated model names
+  language: 'en-US',              // ✅ BCP-47 language codes
+  diarization: true,
+  smartFormat: true
+}, callbacks);
+
+// Gladia streaming - different options
+const gladiaSession = await router.transcribeStream({
+  provider: 'gladia',
+  encoding: 'wav/pcm',            // ✅ Only Gladia encodings
+  sampleRate: 16000,              // ✅ Only supported rates
+  bitDepth: 16,                   // ✅ Only supported depths
+  languageConfig: { languages: ['en'] }
+}, callbacks);
+
+// AssemblyAI streaming - simpler options
+const assemblySession = await router.transcribeStream({
+  provider: 'assemblyai',
+  sampleRate: 16000,              // ✅ Only 8000, 16000, 22050, 44100, 48000
+  wordTimestamps: true
+}, callbacks);
+```
+
+**Benefits:**
+- ✅ **Full IntelliSense** - Autocomplete for all provider-specific options
+- ✅ **Compile-time Safety** - Invalid options caught before runtime
+- ✅ **Provider Discrimination** - Type system knows which provider you're using
+- ✅ **OpenAPI-Generated** - Types come directly from provider specifications
+
 ## Requirements
 
 - **Node.js**: 20.0.0 or higher
@@ -354,9 +456,41 @@ import type {
 
 ## 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
+### API Reference (Auto-Generated)
+
+Comprehensive API documentation is auto-generated with [TypeDoc](https://typedoc.org/) from TypeScript source code:
+
+📁 **[docs/generated/](./docs/generated/)** - Complete API reference
+
+**Main Documentation Sets**:
+
+1. **[router/](./docs/generated/router/)** - Core SDK API
+   - `voice-router.md` - VoiceRouter class (main entry point)
+   - `types.md` - Unified types (UnifiedTranscriptResponse, StreamingOptions, etc.)
+   - `adapters/base-adapter.md` - BaseAdapter interface
+
+2. **[webhooks/](./docs/generated/webhooks/)** - Webhook handling
+   - `webhook-router.md` - WebhookRouter class (auto-detect providers)
+   - `types.md` - Webhook event types
+   - `{provider}-webhook.md` - Provider-specific webhook handlers
+
+3. **Provider-Specific Adapters**:
+   - [gladia/](./docs/generated/gladia/) - Gladia adapter API
+   - [deepgram/](./docs/generated/deepgram/) - Deepgram adapter API
+   - [assemblyai/](./docs/generated/assemblyai/) - AssemblyAI adapter API
+   - [openai/](./docs/generated/openai/) - OpenAI Whisper adapter API
+   - [azure/](./docs/generated/azure/) - Azure STT adapter API
+   - [speechmatics/](./docs/generated/speechmatics/) - Speechmatics adapter API
+
+**Most Important Files**:
+- `docs/generated/router/router/voice-router.md` - Main router class
+- `docs/generated/router/router/types.md` - Core types
+- `docs/generated/webhooks/webhook-router.md` - Webhook handling
+
+### Developer Documentation
+
+- **[docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md)** - Quick reference for developers
+- **[docs/SDK_GENERATION_WORKFLOW.md](./docs/SDK_GENERATION_WORKFLOW.md)** - Technical workflow
 
 ## Provider Setup Guides