@voice-kit/core 0.1.0 → 0.1.2

package/dist/errors.d.cts

@@ -1,55 +1,8 @@
-import { ErrorSeverity } from './index.cjs';
+import { V as VoiceKitError } from './telephony.errors-BQYr6-vl.cjs';
+export { A as AudioTransportError, C as CallConnectionError, a as CallNotFoundError, T as TelephonyError } from './telephony.errors-BQYr6-vl.cjs';
+import { E as ErrorSeverity } from './index-D3KfRXMP.cjs';
 import 'ai';
 
-/**
- * @voice-kit/core — Typed error hierarchy
- *
- * All VoiceKit errors extend VoiceKitError. Never throw raw Error.
- * Every error carries: code, message, provider, callId, retryable, severity.
- */
-
-/**
- * Base class for all VoiceKit errors. Provides structured context for
- * logging, alerting, and programmatic error handling.
- *
- * @example
- * ```ts
- * try {
- *   await stt.transcribeBatch(audio)
- * } catch (err) {
- *   if (err instanceof STTError) {
- *     console.error(err.code, err.provider, err.retryable)
- *   }
- * }
- * ```
- */
-declare class VoiceKitError extends Error {
-    readonly code: string;
-    readonly callId?: string;
-    readonly provider?: string;
-    readonly retryable: boolean;
-    readonly severity: ErrorSeverity;
-    readonly cause?: unknown;
-    constructor(params: {
-        code: string;
-        message: string;
-        callId?: string;
-        provider?: string;
-        retryable?: boolean;
-        severity?: ErrorSeverity;
-        cause?: unknown;
-    });
-    toJSON(): {
-        name: string;
-        code: string;
-        message: string;
-        callId: string | undefined;
-        provider: string | undefined;
-        retryable: boolean;
-        severity: ErrorSeverity;
-    };
-}
-
 /**
  * Errors from agent orchestration (turn engine, handoff, injection).
  */
@@ -129,34 +82,6 @@ declare class STTLanguageNotSupportedError extends STTError {
     constructor(provider: string, language: string);
 }
 
-/**
- * Errors from telephony providers.
- */
-declare class TelephonyError extends VoiceKitError {
-    readonly to?: string;
-    readonly from?: string;
-    constructor(params: {
-        code: string;
-        message: string;
-        callId?: string;
-        provider?: string;
-        retryable?: boolean;
-        severity?: ErrorSeverity;
-        cause?: unknown;
-        to?: string;
-        from?: string;
-    });
-}
-declare class CallConnectionError extends TelephonyError {
-    constructor(provider: string, to: string, cause?: unknown);
-}
-declare class CallNotFoundError extends TelephonyError {
-    constructor(callId: string, provider: string);
-}
-declare class AudioTransportError extends TelephonyError {
-    constructor(provider: string, cause?: unknown, callId?: string);
-}
-
 /**
  * Errors from text-to-speech providers.
  */
@@ -172,4 +97,4 @@ declare class TTSVoiceNotFoundError extends TTSError {
     constructor(provider: string, voiceId: string);
 }
 
-export { AgentError, AgentHandoffError, AudioTransportError, CallConnectionError, CallNotFoundError, CallingHoursError, ComplianceError, ConsentMissingError, DNCBlockedError, InngestError, STTConnectionError, STTError, STTLanguageNotSupportedError, STTStreamError, TTSConnectionError, TTSError, TTSStreamError, TTSVoiceNotFoundError, TelephonyError, TurnTransitionError, VoiceKitError };
+export { AgentError, AgentHandoffError, CallingHoursError, ComplianceError, ConsentMissingError, DNCBlockedError, InngestError, STTConnectionError, STTError, STTLanguageNotSupportedError, STTStreamError, TTSConnectionError, TTSError, TTSStreamError, TTSVoiceNotFoundError, TurnTransitionError, VoiceKitError };

package/dist/errors.d.ts

@@ -1,55 +1,8 @@
-import { ErrorSeverity } from './index.js';
+import { V as VoiceKitError } from './telephony.errors-C0-nScrF.js';
+export { A as AudioTransportError, C as CallConnectionError, a as CallNotFoundError, T as TelephonyError } from './telephony.errors-C0-nScrF.js';
+import { E as ErrorSeverity } from './index-D3KfRXMP.js';
 import 'ai';
 
-/**
- * @voice-kit/core — Typed error hierarchy
- *
- * All VoiceKit errors extend VoiceKitError. Never throw raw Error.
- * Every error carries: code, message, provider, callId, retryable, severity.
- */
-
-/**
- * Base class for all VoiceKit errors. Provides structured context for
- * logging, alerting, and programmatic error handling.
- *
- * @example
- * ```ts
- * try {
- *   await stt.transcribeBatch(audio)
- * } catch (err) {
- *   if (err instanceof STTError) {
- *     console.error(err.code, err.provider, err.retryable)
- *   }
- * }
- * ```
- */
-declare class VoiceKitError extends Error {
-    readonly code: string;
-    readonly callId?: string;
-    readonly provider?: string;
-    readonly retryable: boolean;
-    readonly severity: ErrorSeverity;
-    readonly cause?: unknown;
-    constructor(params: {
-        code: string;
-        message: string;
-        callId?: string;
-        provider?: string;
-        retryable?: boolean;
-        severity?: ErrorSeverity;
-        cause?: unknown;
-    });
-    toJSON(): {
-        name: string;
-        code: string;
-        message: string;
-        callId: string | undefined;
-        provider: string | undefined;
-        retryable: boolean;
-        severity: ErrorSeverity;
-    };
-}
-
 /**
  * Errors from agent orchestration (turn engine, handoff, injection).
  */
@@ -129,34 +82,6 @@ declare class STTLanguageNotSupportedError extends STTError {
     constructor(provider: string, language: string);
 }
 
-/**
- * Errors from telephony providers.
- */
-declare class TelephonyError extends VoiceKitError {
-    readonly to?: string;
-    readonly from?: string;
-    constructor(params: {
-        code: string;
-        message: string;
-        callId?: string;
-        provider?: string;
-        retryable?: boolean;
-        severity?: ErrorSeverity;
-        cause?: unknown;
-        to?: string;
-        from?: string;
-    });
-}
-declare class CallConnectionError extends TelephonyError {
-    constructor(provider: string, to: string, cause?: unknown);
-}
-declare class CallNotFoundError extends TelephonyError {
-    constructor(callId: string, provider: string);
-}
-declare class AudioTransportError extends TelephonyError {
-    constructor(provider: string, cause?: unknown, callId?: string);
-}
-
 /**
  * Errors from text-to-speech providers.
  */
@@ -172,4 +97,4 @@ declare class TTSVoiceNotFoundError extends TTSError {
     constructor(provider: string, voiceId: string);
 }
 
-export { AgentError, AgentHandoffError, AudioTransportError, CallConnectionError, CallNotFoundError, CallingHoursError, ComplianceError, ConsentMissingError, DNCBlockedError, InngestError, STTConnectionError, STTError, STTLanguageNotSupportedError, STTStreamError, TTSConnectionError, TTSError, TTSStreamError, TTSVoiceNotFoundError, TelephonyError, TurnTransitionError, VoiceKitError };
+export { AgentError, AgentHandoffError, CallingHoursError, ComplianceError, ConsentMissingError, DNCBlockedError, InngestError, STTConnectionError, STTError, STTLanguageNotSupportedError, STTStreamError, TTSConnectionError, TTSError, TTSStreamError, TTSVoiceNotFoundError, TurnTransitionError, VoiceKitError };

package/dist/index-D3KfRXMP.d.cts

@@ -0,0 +1,319 @@
+import * as ai from 'ai';
+
+/**
+ * @voice-kit/core — Type definitions
+ */
+/**
+ * A single word with timing information from an STT provider.
+ */
+interface WordTimestamp {
+    word: string;
+    startMs: number;
+    endMs: number;
+    confidence: number;
+}
+/**
+ * The result of a speech-to-text transcription, either streaming partial
+ * or final. `isFinal` distinguishes the two.
+ *
+ * @example
+ * ```ts
+ * for await (const result of stt.transcribeStream(audioIterable)) {
+ *   if (result.isFinal) console.log('Final:', result.transcript)
+ * }
+ * ```
+ */
+interface STTResult {
+    /** The transcribed text. May be a partial result if `isFinal` is false. */
+    transcript: string;
+    /** Whether this is the final result for this utterance. */
+    isFinal: boolean;
+    /** Confidence score from the provider, 0–1. */
+    confidence: number;
+    /** BCP-47 language tag, e.g. 'hi-IN', 'en-IN'. */
+    language: string;
+    /** True if a mid-sentence language switch was detected (e.g. Hinglish). */
+    languageSwitchDetected: boolean;
+    /** Word-level timestamps if supported by the provider. */
+    words?: WordTimestamp[];
+    /** Time from audio start to this result being emitted, in ms. */
+    latencyMs: number;
+}
+/**
+ * Configuration for STT provider instantiation.
+ */
+interface STTConfig {
+    /** BCP-47 language code. Defaults to 'en-IN'. */
+    language?: string;
+    /** Additional languages to detect for code-switching. */
+    alternateLanguages?: string[];
+    /** API key. Falls back to provider-specific env var if omitted. */
+    apiKey?: string;
+    /** Custom model name. Provider-specific. */
+    model?: string;
+    /** Enable word-level timestamps. Default false. */
+    wordTimestamps?: boolean;
+    /** Enable interim / partial results. Default true. */
+    interimResults?: boolean;
+    /** Deepgram-specific: smart formatting. Default true. */
+    smartFormat?: boolean;
+    /** Sarvam-specific: region hint. */
+    region?: string;
+}
+/**
+ * The STTProvider interface. Obtained via `createSTT()` — never instantiate
+ * provider classes directly.
+ *
+ * @example
+ * ```ts
+ * const stt = createSTT('deepgram', { language: 'en-IN' })
+ * for await (const result of stt.transcribeStream(audioStream)) {
+ *   console.log(result.transcript)
+ * }
+ * ```
+ */
+interface STTProvider {
+    /** Stream audio in, stream STTResults out. Primary realtime path. */
+    transcribeStream(audio: AsyncIterable<Buffer>): AsyncIterable<STTResult>;
+    /** Batch transcription for recordings. Returns single final result. */
+    transcribeBatch(audio: Buffer): Promise<STTResult>;
+    /** Whether this provider supports streaming (all except Whisper). */
+    readonly supportsStreaming: boolean;
+    /** BCP-47 codes this provider can handle. */
+    readonly supportedLanguages: string[];
+    /** Human-readable provider name for logging. */
+    readonly name: string;
+}
+/**
+ * Configuration for TTS provider instantiation.
+ */
+interface TTSConfig {
+    /** Voice identifier. Provider-specific. */
+    voiceId?: string;
+    /** Output sample rate. Defaults to provider native rate. */
+    sampleRate?: number;
+    /** Speaking speed multiplier. Default 1.0. */
+    speed?: number;
+    /** Pitch adjustment. Provider-specific. */
+    pitch?: number;
+    /** API key. Falls back to provider-specific env var if omitted. */
+    apiKey?: string;
+    /** ElevenLabs-specific: model ID. */
+    modelId?: string;
+    /** Cartesia-specific: emotion control. */
+    emotion?: string;
+    /** Sarvam-specific: target language for Indic voices. */
+    targetLanguage?: string;
+}
+/**
+ * The TTSProvider interface. Obtained via `createTTS()` — never instantiate
+ * provider classes directly.
+ *
+ * @example
+ * ```ts
+ * const tts = createTTS('elevenlabs', { voiceId: 'your-voice-id' })
+ * for await (const chunk of tts.synthesizeStream('Hello, how can I help?')) {
+ *   socket.write(chunk)
+ * }
+ * ```
+ */
+interface TTSProvider {
+    /** Stream synthesis — preferred for realtime. First chunk < 300ms. */
+    synthesizeStream(text: string, config?: TTSConfig): AsyncIterable<Buffer>;
+    /** Synthesize full audio — for pre-recorded prompts or caching. */
+    synthesizeFull(text: string, config?: TTSConfig): Promise<Buffer>;
+    /** Native output sample rate of this provider in Hz. */
+    readonly outputSampleRate: number;
+    /** Native output format before any resampling. */
+    readonly outputFormat: 'pcm' | 'mulaw' | 'opus' | 'mp3';
+    /** Human-readable provider name for logging. */
+    readonly name: string;
+}
+/**
+ * A frame of audio classified by the VAD engine.
+ * Developers subscribe to these events — never to raw VAD API.
+ */
+interface VoiceFrame {
+    /** Event type. */
+    type: 'speech_start' | 'speech_end' | 'speech';
+    /** VAD confidence 0–1. */
+    confidence: number;
+    /** Raw PCM audio bytes for this frame. */
+    audioBuffer: Buffer;
+    /** Duration of audio in this frame, in ms. */
+    durationMs: number;
+}
+/**
+ * Configuration for the VAD engine.
+ */
+interface VADConfig {
+    /** Activation threshold 0–1. Default 0.6. */
+    threshold?: number;
+    /** Consecutive positive frames before speech_start. Default 3. */
+    positiveSpeechFrames?: number;
+    /** Consecutive negative frames before speech_end. Default 5. */
+    negativeSpeechFrames?: number;
+    /** Debounce window in ms to prevent rapid flip-flop. Default 150. */
+    debounceMs?: number;
+    /** Input sample rate. Auto-set by AudioPipeline — do not override. */
+    sampleRate?: number;
+}
+/**
+ * Configuration for call memory (LRU-backed sliding window of turns).
+ */
+interface CallMemoryConfig {
+    /** Maximum number of turns to retain. Default 20. */
+    maxTurns?: number;
+    /** Maximum bytes of conversation history to retain. Default 512KB. */
+    maxBytes?: number;
+    /** TTL for the entire call memory entry in ms. Default 30 minutes. */
+    ttlMs?: number;
+}
+/**
+ * In-process LRU-backed call memory. Obtained via `createCallMemory()`.
+ *
+ * @example
+ * ```ts
+ * const memory = createCallMemory({ maxTurns: 20 })
+ * memory.addTurn(callId, { role: 'user', content: 'Hello' })
+ * const history = memory.getTurns(callId)
+ * ```
+ */
+interface CallMemory {
+    addTurn(callId: string, message: ai.ModelMessage): void;
+    getTurns(callId: string): ai.ModelMessage[];
+    clearCall(callId: string): void;
+    getTokenEstimate(callId: string): number;
+    /** Truncate oldest turns to stay within budget. */
+    trimToTokenBudget(callId: string, maxTokens: number): void;
+}
+/**
+ * Type of call for TRAI DND classification.
+ */
+type CallPurpose = 'TRANSACTIONAL' | 'PROMOTIONAL' | 'SERVICE' | 'EMERGENCY';
+/**
+ * TRAI DNC check parameters.
+ */
+interface DNCCheckParams {
+    /** E.164 format phone number, validated via libphonenumber-js. */
+    to: string;
+    /** Purpose category for TRAI classification. */
+    purpose: CallPurpose;
+    /** Scheduled call time. Defaults to now. */
+    scheduledAt?: Date;
+}
+/**
+ * Result of a TRAI DNC check.
+ */
+interface DNCCheckResult {
+    /** Whether the call is permitted. */
+    allowed: boolean;
+    /** Human-readable reason if not allowed. */
+    reason?: string;
+    /** When this result was fetched (from LRU cache). */
+    cachedAt?: Date;
+    /** Whether result came from local LRU cache. */
+    fromCache: boolean;
+}
+/**
+ * Consent record stored for TRAI compliance.
+ */
+interface ConsentRecord {
+    phoneNumber: string;
+    consentedAt: Date;
+    /** Channel through which consent was obtained. */
+    channel: 'voice' | 'sms' | 'web' | 'ivr';
+    /** Call purpose consent was given for. */
+    purpose: CallPurpose;
+    /** Optional reference ID (e.g. recording URL). */
+    referenceId?: string;
+}
+/**
+ * TRAI compliance configuration.
+ */
+interface TRAIConfig {
+    /** Disable TRAI checks entirely. Default false. */
+    disabled?: boolean;
+    /** Calling timezone override. Default 'Asia/Kolkata'. */
+    timezone?: string;
+    /** Override calling hours start (24h). Default 9. */
+    callingHoursStart?: number;
+    /** Override calling hours end (24h). Default 21. */
+    callingHoursEnd?: number;
+    /** Custom DNC API endpoint. Default: mock endpoint (must be replaced in production). */
+    dncApiEndpoint?: string;
+}
+/**
+ * Aggregated metrics for a completed or in-progress call.
+ */
+interface CallMetricsSummary {
+    callId: string;
+    sttFirstByteMs: number[];
+    ttsFirstByteMs: number[];
+    llmFirstTokenMs: number[];
+    turnLatencyMs: number[];
+    interruptionCount: number;
+    interruptionPositions: number[];
+    tokenCost: {
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        estimatedUsdCost: number;
+    }[];
+    avgTurnLatencyMs: number;
+    p95TurnLatencyMs: number;
+}
+/**
+ * Error severity level.
+ */
+type ErrorSeverity = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Base error context shared by all VoiceKit errors.
+ */
+interface VoiceKitErrorContext {
+    /** Error code for programmatic handling. */
+    code: string;
+    /** Associated call ID if applicable. */
+    callId?: string;
+    /** The provider that threw (e.g. 'deepgram', 'elevenlabs'). */
+    provider?: string;
+    /** Whether this error is safe to retry. */
+    retryable: boolean;
+    /** Severity for alerting/logging. */
+    severity: ErrorSeverity;
+    /** Original upstream error if wrapping. */
+    cause?: unknown;
+}
+/**
+ * Create an STT provider instance. This is the ONLY public API for STT.
+ * Never instantiate provider classes directly.
+ *
+ * @example
+ * ```ts
+ * const stt = createSTT('deepgram', { language: 'hi-IN' })
+ * const stt2 = createSTT('sarvam', { language: 'ta-IN' })
+ * ```
+ */
+declare function createSTT(provider: 'deepgram' | 'whisper' | 'assemblyai' | 'sarvam', config?: STTConfig): STTProvider;
+/**
+ * Create a TTS provider instance. This is the ONLY public API for TTS.
+ * Never instantiate provider classes directly.
+ *
+ * @example
+ * ```ts
+ * const tts = createTTS('elevenlabs', { voiceId: 'your-voice-id' })
+ * const tts2 = createTTS('sarvam', { targetLanguage: 'hi-IN' })
+ * ```
+ */
+declare function createTTS(provider: 'elevenlabs' | 'cartesia' | 'sarvam', config?: TTSConfig): TTSProvider;
+/**
+ * Create an LRU-backed call memory instance.
+ *
+ * @example
+ * ```ts
+ * const memory = createCallMemory({ maxTurns: 20, maxBytes: 512_000 })
+ * ```
+ */
+declare function createCallMemory(config?: CallMemoryConfig): CallMemory;
+
+export { type CallMemoryConfig as C, type DNCCheckParams as D, type ErrorSeverity as E, type STTProvider as S, type TRAIConfig as T, type VADConfig as V, type WordTimestamp as W, type CallMemory as a, type DNCCheckResult as b, type ConsentRecord as c, type CallMetricsSummary as d, type TTSProvider as e, type TTSConfig as f, type VoiceFrame as g, type STTConfig as h, type STTResult as i, type CallPurpose as j, type VoiceKitErrorContext as k, createCallMemory as l, createSTT as m, createTTS as n };