voice-router-dev 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -9,9 +9,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+#### Gladia Audio File Download
+
+New `getAudioFile()` method for Gladia adapter - download the original audio used for transcription.
+
+Returns `ArrayBuffer` for cross-platform compatibility (Node.js and browser):
+
+```typescript
+const result = await gladiaAdapter.getAudioFile('transcript-123')
+if (result.success && result.data) {
+  // Node.js: Convert to Buffer and save
+  const buffer = Buffer.from(result.data)
+  fs.writeFileSync('audio.mp3', buffer)
+
+  // Browser: Convert to Blob for playback/download
+  const blob = new Blob([result.data], { type: result.contentType || 'audio/mpeg' })
+  const url = URL.createObjectURL(blob)
+}
+
+// Download audio from a live/streaming session
+const liveResult = await gladiaAdapter.getAudioFile('stream-456', 'streaming')
+console.log('Size:', liveResult.data?.byteLength, 'bytes')
+```
+
+**Note:** This is a Gladia-specific feature. Other providers (Deepgram, AssemblyAI, Azure) do not store audio files after transcription.
+
+New capability flag: `capabilities.getAudioFile` indicates provider support for audio retrieval.
+
+#### Improved Metadata Clarity
+
+New metadata fields for better discoverability:
+
+```typescript
+interface TranscriptMetadata {
+  /** Original audio URL you provided (echoed back) - renamed from audioUrl */
+  sourceAudioUrl?: string
+
+  /** True if getAudioFile() can retrieve the audio (Gladia only) */
+  audioFileAvailable?: boolean
+  // ...
+}
+```
+
+Usage pattern:
+```typescript
+const { transcripts } = await router.listTranscripts('gladia')
+
+transcripts.forEach(item => {
+  // What you sent
+  console.log(item.data?.metadata?.sourceAudioUrl)  // "https://your-bucket.s3.amazonaws.com/audio.mp3"
+
+  // Can we download from provider?
+  if (item.data?.metadata?.audioFileAvailable) {
+    const audio = await gladiaAdapter.getAudioFile(item.data.id)
+    // audio.data is a Blob - actual file stored by Gladia
+  }
+})
+```
+
+### Changed
+
+- **BREAKING:** `metadata.audioUrl` renamed to `metadata.sourceAudioUrl` for clarity
+  - This field contains the URL you originally provided, not a provider-hosted URL
+- `audioFileAvailable` is now set on all provider responses (derived from `capabilities.getAudioFile`)
+
 #### listTranscripts Implementation
 
-Full `listTranscripts()` support for AssemblyAI, Gladia, and Azure using only generated types:
+Full `listTranscripts()` support for AssemblyAI, Gladia, Azure, and Deepgram using only generated types:
 
 ```typescript
 // List recent transcripts with filtering
@@ -31,6 +95,23 @@ const { transcripts } = await router.listTranscripts('gladia', {
 const { transcripts } = await router.listTranscripts('assemblyai', {
   assemblyai: { after_id: 'cursor-123' }
 })
+
+// Deepgram request history (requires projectId)
+const adapter = new DeepgramAdapter()
+adapter.initialize({
+  apiKey: process.env.DEEPGRAM_API_KEY,
+  projectId: process.env.DEEPGRAM_PROJECT_ID
+})
+
+// List requests (metadata only)
+const { transcripts } = await adapter.listTranscripts({
+  status: 'succeeded',
+  afterDate: '2026-01-01'
+})
+
+// Get full transcript by request ID
+const fullTranscript = await adapter.getTranscript(transcripts[0].data?.id)
+console.log(fullTranscript.data?.text)  // Full transcript!
 ```
 
 #### Status Enums for Filtering
@@ -38,7 +119,7 @@ const { transcripts } = await router.listTranscripts('assemblyai', {
 New status constants with IDE autocomplete:
 
 ```typescript
-import { AssemblyAIStatus, GladiaStatus, AzureStatus } from 'voice-router-dev/constants'
+import { AssemblyAIStatus, GladiaStatus, AzureStatus, DeepgramStatus } from 'voice-router-dev/constants'
 
 await router.listTranscripts('assemblyai', {
   status: AssemblyAIStatus.completed  // queued | processing | completed | error
@@ -51,6 +132,11 @@ await router.listTranscripts('gladia', {
 await router.listTranscripts('azure-stt', {
   status: AzureStatus.Succeeded  // NotStarted | Running | Succeeded | Failed
 })
+
+// Deepgram (request history - requires projectId)
+await adapter.listTranscripts({
+  status: DeepgramStatus.succeeded  // succeeded | failed
+})
 ```
 
 #### JSDoc Comments for All Constants
@@ -60,10 +146,84 @@ All constants now have JSDoc with:
 - Usage examples
 - Provider-specific notes
 
+#### Typed Response Interfaces
+
+New exported types for full autocomplete on transcript responses:
+
+```typescript
+import type {
+  TranscriptData,
+  TranscriptMetadata,
+  ListTranscriptsResponse
+} from 'voice-router-dev';
+
+const response: ListTranscriptsResponse = await router.listTranscripts('assemblyai', { limit: 20 });
+
+response.transcripts.forEach(item => {
+  // Full autocomplete - no `as any` casts needed!
+  console.log(item.data?.id);                    // string
+  console.log(item.data?.status);                // TranscriptionStatus
+  console.log(item.data?.metadata?.audioUrl);    // string | undefined
+  console.log(item.data?.metadata?.createdAt);   // string | undefined
+});
+```
+
+**Note:** These are manual normalization types that unify different provider schemas.
+For raw provider types, use `result.raw` with the generic parameter:
+
+```typescript
+const result: UnifiedTranscriptResponse<'assemblyai'> = await adapter.transcribe(audio);
+// result.raw is typed as AssemblyAITranscript
+```
+
+#### DeepgramSampleRate Const
+
+New convenience const for Deepgram sample rates (not in OpenAPI spec):
+
+```typescript
+import { DeepgramSampleRate } from 'voice-router-dev/constants'
+
+{ sampleRate: DeepgramSampleRate.NUMBER_16000 }
+```
+
+#### Additional Deepgram OpenAPI Re-exports
+
+New constants directly re-exported from OpenAPI-generated types:
+
+```typescript
+import { DeepgramIntentMode, DeepgramCallbackMethod } from 'voice-router-dev/constants'
+
+// Intent detection mode
+{ customIntentMode: DeepgramIntentMode.extended }  // extended | strict
+
+// Async callback method
+{ callbackMethod: DeepgramCallbackMethod.POST }  // POST | PUT
+```
+
 ### Changed
 
 - All adapter `listTranscripts()` implementations use generated API functions and types only
-- Status mappings use generated enums (`TranscriptStatus`, `TranscriptionControllerListV2StatusItem`, `Status`)
+- Status mappings use generated enums (`TranscriptStatus`, `TranscriptionControllerListV2StatusItem`, `Status`, `ManageV1FilterStatusParameter`)
+- Deepgram adapter now supports `listTranscripts()` via request history API (metadata only)
+- Deepgram `getTranscript()` now returns full transcript data from request history
+
+### Fixed
+
+- Gladia `listTranscripts()` now includes file metadata:
+  - `data.duration` - audio duration in seconds
+  - `metadata.audioUrl` - source URL (if audio_url was used)
+  - `metadata.filename` - original filename
+  - `metadata.audioDuration` - audio duration (also in metadata)
+  - `metadata.numberOfChannels` - number of audio channels
+
+- All adapters now include `raw: item` in `listTranscripts()` responses for consistency:
+  - AssemblyAI: now includes `raw` field with original `TranscriptListItem`
+  - Azure: now includes `raw` field with original `Transcription` item
+  - Added `metadata.description` to Azure list responses
+
+- Added clarifying comments in adapters about provider limitations:
+  - AssemblyAI: `audio_duration` only available in full `Transcript`, not `TranscriptListItem`
+  - Azure: `contentUrls` is write-only (not returned in list responses per API docs)
 
 ---
 

package/dist/constants.d.mts

@@ -69,6 +69,61 @@ declare const DeepgramTopicMode: {
     readonly extended: "extended";
     readonly strict: "strict";
 };
+/**
+ * Deepgram intent detection modes
+ *
+ * Values: `extended`, `strict`
+ *
+ * @example
+ * ```typescript
+ * import { DeepgramIntentMode } from 'voice-router-dev/constants'
+ *
+ * { customIntentMode: DeepgramIntentMode.extended }
+ * ```
+ */
+declare const DeepgramIntentMode: {
+    readonly extended: "extended";
+    readonly strict: "strict";
+};
+/**
+ * Deepgram callback HTTP methods for async transcription
+ *
+ * Values: `POST`, `PUT`
+ *
+ * @example
+ * ```typescript
+ * import { DeepgramCallbackMethod } from 'voice-router-dev/constants'
+ *
+ * { callbackMethod: DeepgramCallbackMethod.POST }
+ * ```
+ */
+declare const DeepgramCallbackMethod: {
+    readonly POST: "POST";
+    readonly PUT: "PUT";
+};
+/**
+ * Deepgram supported sample rates (Hz)
+ *
+ * **Note:** This const is NOT type-checked against a generated type.
+ * Deepgram's OpenAPI spec accepts any `number` for sampleRate.
+ * These values are from Deepgram documentation for convenience.
+ *
+ * Values: `8000`, `16000`, `32000`, `44100`, `48000`
+ *
+ * @example
+ * ```typescript
+ * import { DeepgramSampleRate } from 'voice-router-dev/constants'
+ *
+ * { sampleRate: DeepgramSampleRate.NUMBER_16000 }
+ * ```
+ */
+declare const DeepgramSampleRate: {
+    readonly NUMBER_8000: 8000;
+    readonly NUMBER_16000: 16000;
+    readonly NUMBER_32000: 32000;
+    readonly NUMBER_44100: 44100;
+    readonly NUMBER_48000: 48000;
+};
 /**
  * Deepgram transcription models
  *
@@ -525,12 +580,39 @@ declare const AzureStatus: {
     readonly Succeeded: "Succeeded";
     readonly Failed: "Failed";
 };
+/**
+ * Deepgram request history status values for filtering
+ *
+ * Values: `succeeded`, `failed`
+ *
+ * Note: Deepgram only stores request metadata, not transcript content.
+ * Requires `projectId` to be set during adapter initialization.
+ *
+ * @example
+ * ```typescript
+ * import { DeepgramStatus } from 'voice-router-dev/constants'
+ *
+ * await router.listTranscripts('deepgram', {
+ *   status: DeepgramStatus.succeeded
+ * })
+ * ```
+ */
+declare const DeepgramStatus: {
+    readonly succeeded: "succeeded";
+    readonly failed: "failed";
+};
 /** Deepgram encoding type derived from const object */
 type DeepgramEncodingType = (typeof DeepgramEncoding)[keyof typeof DeepgramEncoding];
 /** Deepgram redaction type derived from const object */
 type DeepgramRedactType = (typeof DeepgramRedact)[keyof typeof DeepgramRedact];
 /** Deepgram topic mode type derived from const object */
 type DeepgramTopicModeType = (typeof DeepgramTopicMode)[keyof typeof DeepgramTopicMode];
+/** Deepgram intent mode type derived from const object */
+type DeepgramIntentModeType = (typeof DeepgramIntentMode)[keyof typeof DeepgramIntentMode];
+/** Deepgram callback method type derived from const object */
+type DeepgramCallbackMethodType = (typeof DeepgramCallbackMethod)[keyof typeof DeepgramCallbackMethod];
+/** Deepgram sample rate type derived from const object */
+type DeepgramSampleRateType = (typeof DeepgramSampleRate)[keyof typeof DeepgramSampleRate];
 /** Deepgram model type derived from const object */
 type DeepgramModelType = (typeof DeepgramModel)[keyof typeof DeepgramModel];
 /** Gladia encoding type derived from const object */
@@ -557,5 +639,7 @@ type AssemblyAIStatusType = (typeof AssemblyAIStatus)[keyof typeof AssemblyAISta
 type GladiaStatusType = (typeof GladiaStatus)[keyof typeof GladiaStatus];
 /** Azure status type derived from const object */
 type AzureStatusType = (typeof AzureStatus)[keyof typeof AzureStatus];
+/** Deepgram status type derived from const object */
+type DeepgramStatusType = (typeof DeepgramStatus)[keyof typeof DeepgramStatus];
 
-export { AssemblyAIEncoding, type AssemblyAIEncodingType, AssemblyAISampleRate, type AssemblyAISampleRateType, AssemblyAISpeechModel, type AssemblyAISpeechModelType, AssemblyAIStatus, type AssemblyAIStatusType, AzureStatus, type AzureStatusType, DeepgramEncoding, type DeepgramEncodingType, DeepgramModel, type DeepgramModelType, DeepgramRedact, type DeepgramRedactType, DeepgramTopicMode, type DeepgramTopicModeType, GladiaBitDepth, type GladiaBitDepthType, GladiaEncoding, type GladiaEncodingType, GladiaLanguage, type GladiaLanguageType, GladiaModel, type GladiaModelType, GladiaSampleRate, type GladiaSampleRateType, GladiaStatus, type GladiaStatusType, GladiaTranslationLanguage, type GladiaTranslationLanguageType };
+export { AssemblyAIEncoding, type AssemblyAIEncodingType, AssemblyAISampleRate, type AssemblyAISampleRateType, AssemblyAISpeechModel, type AssemblyAISpeechModelType, AssemblyAIStatus, type AssemblyAIStatusType, AzureStatus, type AzureStatusType, DeepgramCallbackMethod, type DeepgramCallbackMethodType, DeepgramEncoding, type DeepgramEncodingType, DeepgramIntentMode, type DeepgramIntentModeType, DeepgramModel, type DeepgramModelType, DeepgramRedact, type DeepgramRedactType, DeepgramSampleRate, type DeepgramSampleRateType, DeepgramStatus, type DeepgramStatusType, DeepgramTopicMode, type DeepgramTopicModeType, GladiaBitDepth, type GladiaBitDepthType, GladiaEncoding, type GladiaEncodingType, GladiaLanguage, type GladiaLanguageType, GladiaModel, type GladiaModelType, GladiaSampleRate, type GladiaSampleRateType, GladiaStatus, type GladiaStatusType, GladiaTranslationLanguage, type GladiaTranslationLanguageType };

package/dist/constants.d.ts

@@ -69,6 +69,61 @@ declare const DeepgramTopicMode: {
     readonly extended: "extended";
     readonly strict: "strict";
 };
+/**
+ * Deepgram intent detection modes
+ *
+ * Values: `extended`, `strict`
+ *
+ * @example
+ * ```typescript
+ * import { DeepgramIntentMode } from 'voice-router-dev/constants'
+ *
+ * { customIntentMode: DeepgramIntentMode.extended }
+ * ```
+ */
+declare const DeepgramIntentMode: {
+    readonly extended: "extended";
+    readonly strict: "strict";
+};
+/**
+ * Deepgram callback HTTP methods for async transcription
+ *
+ * Values: `POST`, `PUT`
+ *
+ * @example
+ * ```typescript
+ * import { DeepgramCallbackMethod } from 'voice-router-dev/constants'
+ *
+ * { callbackMethod: DeepgramCallbackMethod.POST }
+ * ```
+ */
+declare const DeepgramCallbackMethod: {
+    readonly POST: "POST";
+    readonly PUT: "PUT";
+};
+/**
+ * Deepgram supported sample rates (Hz)
+ *
+ * **Note:** This const is NOT type-checked against a generated type.
+ * Deepgram's OpenAPI spec accepts any `number` for sampleRate.
+ * These values are from Deepgram documentation for convenience.
+ *
+ * Values: `8000`, `16000`, `32000`, `44100`, `48000`
+ *
+ * @example
+ * ```typescript
+ * import { DeepgramSampleRate } from 'voice-router-dev/constants'
+ *
+ * { sampleRate: DeepgramSampleRate.NUMBER_16000 }
+ * ```
+ */
+declare const DeepgramSampleRate: {
+    readonly NUMBER_8000: 8000;
+    readonly NUMBER_16000: 16000;
+    readonly NUMBER_32000: 32000;
+    readonly NUMBER_44100: 44100;
+    readonly NUMBER_48000: 48000;
+};
 /**
  * Deepgram transcription models
  *
@@ -525,12 +580,39 @@ declare const AzureStatus: {
     readonly Succeeded: "Succeeded";
     readonly Failed: "Failed";
 };
+/**
+ * Deepgram request history status values for filtering
+ *
+ * Values: `succeeded`, `failed`
+ *
+ * Note: Deepgram only stores request metadata, not transcript content.
+ * Requires `projectId` to be set during adapter initialization.
+ *
+ * @example
+ * ```typescript
+ * import { DeepgramStatus } from 'voice-router-dev/constants'
+ *
+ * await router.listTranscripts('deepgram', {
+ *   status: DeepgramStatus.succeeded
+ * })
+ * ```
+ */
+declare const DeepgramStatus: {
+    readonly succeeded: "succeeded";
+    readonly failed: "failed";
+};
 /** Deepgram encoding type derived from const object */
 type DeepgramEncodingType = (typeof DeepgramEncoding)[keyof typeof DeepgramEncoding];
 /** Deepgram redaction type derived from const object */
 type DeepgramRedactType = (typeof DeepgramRedact)[keyof typeof DeepgramRedact];
 /** Deepgram topic mode type derived from const object */
 type DeepgramTopicModeType = (typeof DeepgramTopicMode)[keyof typeof DeepgramTopicMode];
+/** Deepgram intent mode type derived from const object */
+type DeepgramIntentModeType = (typeof DeepgramIntentMode)[keyof typeof DeepgramIntentMode];
+/** Deepgram callback method type derived from const object */
+type DeepgramCallbackMethodType = (typeof DeepgramCallbackMethod)[keyof typeof DeepgramCallbackMethod];
+/** Deepgram sample rate type derived from const object */
+type DeepgramSampleRateType = (typeof DeepgramSampleRate)[keyof typeof DeepgramSampleRate];
 /** Deepgram model type derived from const object */
 type DeepgramModelType = (typeof DeepgramModel)[keyof typeof DeepgramModel];
 /** Gladia encoding type derived from const object */
@@ -557,5 +639,7 @@ type AssemblyAIStatusType = (typeof AssemblyAIStatus)[keyof typeof AssemblyAISta
 type GladiaStatusType = (typeof GladiaStatus)[keyof typeof GladiaStatus];
 /** Azure status type derived from const object */
 type AzureStatusType = (typeof AzureStatus)[keyof typeof AzureStatus];
+/** Deepgram status type derived from const object */
+type DeepgramStatusType = (typeof DeepgramStatus)[keyof typeof DeepgramStatus];
 
-export { AssemblyAIEncoding, type AssemblyAIEncodingType, AssemblyAISampleRate, type AssemblyAISampleRateType, AssemblyAISpeechModel, type AssemblyAISpeechModelType, AssemblyAIStatus, type AssemblyAIStatusType, AzureStatus, type AzureStatusType, DeepgramEncoding, type DeepgramEncodingType, DeepgramModel, type DeepgramModelType, DeepgramRedact, type DeepgramRedactType, DeepgramTopicMode, type DeepgramTopicModeType, GladiaBitDepth, type GladiaBitDepthType, GladiaEncoding, type GladiaEncodingType, GladiaLanguage, type GladiaLanguageType, GladiaModel, type GladiaModelType, GladiaSampleRate, type GladiaSampleRateType, GladiaStatus, type GladiaStatusType, GladiaTranslationLanguage, type GladiaTranslationLanguageType };
+export { AssemblyAIEncoding, type AssemblyAIEncodingType, AssemblyAISampleRate, type AssemblyAISampleRateType, AssemblyAISpeechModel, type AssemblyAISpeechModelType, AssemblyAIStatus, type AssemblyAIStatusType, AzureStatus, type AzureStatusType, DeepgramCallbackMethod, type DeepgramCallbackMethodType, DeepgramEncoding, type DeepgramEncodingType, DeepgramIntentMode, type DeepgramIntentModeType, DeepgramModel, type DeepgramModelType, DeepgramRedact, type DeepgramRedactType, DeepgramSampleRate, type DeepgramSampleRateType, DeepgramStatus, type DeepgramStatusType, DeepgramTopicMode, type DeepgramTopicModeType, GladiaBitDepth, type GladiaBitDepthType, GladiaEncoding, type GladiaEncodingType, GladiaLanguage, type GladiaLanguageType, GladiaModel, type GladiaModelType, GladiaSampleRate, type GladiaSampleRateType, GladiaStatus, type GladiaStatusType, GladiaTranslationLanguage, type GladiaTranslationLanguageType };

package/dist/constants.js

@@ -26,9 +26,13 @@ __export(constants_exports, {
   AssemblyAISpeechModel: () => AssemblyAISpeechModel,
   AssemblyAIStatus: () => AssemblyAIStatus,
   AzureStatus: () => AzureStatus,
+  DeepgramCallbackMethod: () => DeepgramCallbackMethod,
   DeepgramEncoding: () => DeepgramEncoding,
+  DeepgramIntentMode: () => DeepgramIntentMode,
   DeepgramModel: () => DeepgramModel,
   DeepgramRedact: () => DeepgramRedact,
+  DeepgramSampleRate: () => DeepgramSampleRate,
+  DeepgramStatus: () => DeepgramStatus,
   DeepgramTopicMode: () => DeepgramTopicMode,
   GladiaBitDepth: () => GladiaBitDepth,
   GladiaEncoding: () => GladiaEncoding,
@@ -63,6 +67,18 @@ var SharedCustomTopicModeParameter = {
   strict: "strict"
 };
 
+// src/generated/deepgram/schema/sharedCustomIntentModeParameter.ts
+var SharedCustomIntentModeParameter = {
+  extended: "extended",
+  strict: "strict"
+};
+
+// src/generated/deepgram/schema/sharedCallbackMethodParameter.ts
+var SharedCallbackMethodParameter = {
+  POST: "POST",
+  PUT: "PUT"
+};
+
 // src/generated/gladia/schema/streamingSupportedEncodingEnum.ts
 var StreamingSupportedEncodingEnum = {
   "wav/pcm": "wav/pcm",
@@ -323,10 +339,25 @@ var Status = {
   Failed: "Failed"
 };
 
+// src/generated/deepgram/schema/manageV1FilterStatusParameter.ts
+var ManageV1FilterStatusParameter = {
+  succeeded: "succeeded",
+  failed: "failed"
+};
+
 // src/constants.ts
 var DeepgramEncoding = ListenV1EncodingParameter;
 var DeepgramRedact = ListenV1RedactParameterOneOfItem;
 var DeepgramTopicMode = SharedCustomTopicModeParameter;
+var DeepgramIntentMode = SharedCustomIntentModeParameter;
+var DeepgramCallbackMethod = SharedCallbackMethodParameter;
+var DeepgramSampleRate = {
+  NUMBER_8000: 8e3,
+  NUMBER_16000: 16e3,
+  NUMBER_32000: 32e3,
+  NUMBER_44100: 44100,
+  NUMBER_48000: 48e3
+};
 var DeepgramModel = {
   // Nova 3 models (latest)
   "nova-3": "nova-3",
@@ -391,6 +422,7 @@ var AssemblyAISampleRate = {
 var AssemblyAIStatus = TranscriptStatus;
 var GladiaStatus = TranscriptionControllerListV2StatusItem;
 var AzureStatus = Status;
+var DeepgramStatus = ManageV1FilterStatusParameter;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AssemblyAIEncoding,
@@ -398,9 +430,13 @@ var AzureStatus = Status;
   AssemblyAISpeechModel,
   AssemblyAIStatus,
   AzureStatus,
+  DeepgramCallbackMethod,
   DeepgramEncoding,
+  DeepgramIntentMode,
   DeepgramModel,
   DeepgramRedact,
+  DeepgramSampleRate,
+  DeepgramStatus,
   DeepgramTopicMode,
   GladiaBitDepth,
   GladiaEncoding,