getpatter 0.4.3 → 0.4.4

package/dist/index.d.ts

@@ -10,13 +10,21 @@ interface STTConfig {
     readonly provider: string;
     readonly apiKey: string;
     readonly language: string;
-    toDict(): Record<string, string>;
+    /**
+     * Optional — when present, called by internal serialisation. Not required for
+     * callers that pass a plain object literal (``{ provider, apiKey, language }``)
+     * to maintain parity with the Python SDK, which accepts dataclass-like inputs.
+     */
+    toDict?(): Record<string, string | Record<string, unknown>>;
+    /** Provider-specific knobs (e.g. Deepgram endpointing). */
+    options?: Record<string, unknown>;
 }
 interface TTSConfig {
     readonly provider: string;
     readonly apiKey: string;
     readonly voice: string;
-    toDict(): Record<string, string>;
+    toDict?(): Record<string, string | Record<string, unknown>>;
+    options?: Record<string, unknown>;
 }
 type MessageHandler = (msg: IncomingMessage) => Promise<string>;
 type CallEventHandler = (data: Record<string, unknown>) => Promise<void>;
@@ -99,7 +107,12 @@ interface Call {
     }> | null;
 }
 interface LocalOptions {
-    mode: 'local';
+    /**
+     * Optional — when omitted, local mode is auto-detected from the presence of
+     * ``twilioSid`` or ``telnyxKey`` (matches the Python SDK which treats
+     * ``Patter(twilio_sid=...)`` as local mode by default).
+     */
+    mode?: 'local';
     twilioSid?: string;
     twilioToken?: string;
     openaiKey?: string;
@@ -113,6 +126,14 @@ interface LocalOptions {
      * signature verification. When provided, unauthenticated requests are rejected.
      */
     telnyxPublicKey?: string;
+    /**
+     * Provider-level Deepgram API key. When set, agents that don't override
+     * ``agent.deepgramKey`` / ``agent.stt`` use this as the default STT key.
+     * Mirrors Python's ``Patter(deepgram_key=...)``.
+     */
+    deepgramKey?: string;
+    /** Provider-level ElevenLabs API key (same semantics as ``deepgramKey``). */
+    elevenlabsKey?: string;
 }
 interface Guardrail {
     /** Name for logging when triggered */
@@ -197,6 +218,13 @@ interface AgentOptions {
     audioFilter?: AudioFilter;
     /** Optional background audio mixer (hold music, thinking cues). Pipeline mode only. */
     backgroundAudio?: BackgroundAudioPlayer$1;
+    /**
+     * Minimum sustained voice (ms) before treating caller audio as a barge-in
+     * and interrupting TTS. `0` disables barge-in entirely — useful on noisy
+     * links (ngrok tunnels, speakerphone) where the agent can hear itself.
+     * Default: 300.
+     */
+    bargeInThresholdMs?: number;
 }
 type PipelineMessageHandler = (data: Record<string, unknown>) => Promise<string>;
 interface ServeOptions {
@@ -235,11 +263,28 @@ interface LocalCallOptions {
     voicemailMessage?: string;
     /** Dynamic variables merged into agent.variables before call. Override agent-level variables. */
     variables?: Record<string, string>;
+    /**
+     * Ring timeout in seconds. Forwarded to Twilio as `Timeout` and to Telnyx
+     * as `timeout_secs`. Defaults to the carrier default (~28 s on Twilio) when
+     * omitted. Increase for international routes where the remote carrier
+     * silences short US→IT rings.
+     */
+    ringTimeout?: number;
 }
 
+/**
+ * Deepgram STT config. Tune latency via ``endpointingMs`` / ``utteranceEndMs``
+ * — mirrors Python's ``Patter.deepgram(endpointing_ms=..., utterance_end_ms=...)``.
+ */
 declare function deepgram(opts: {
     apiKey: string;
     language?: string;
+    model?: string;
+    endpointingMs?: number;
+    utteranceEndMs?: number | null;
+    smartFormat?: boolean;
+    interimResults?: boolean;
+    vadEvents?: boolean;
 }): STTConfig;
 declare function whisper(opts: {
     apiKey: string;
@@ -253,6 +298,18 @@ declare function openaiTts(opts: {
     apiKey: string;
     voice?: string;
 }): TTSConfig;
+declare function cartesia(opts: {
+    apiKey: string;
+    voice?: string;
+}): TTSConfig;
+declare function rime(opts: {
+    apiKey: string;
+    voice?: string;
+}): TTSConfig;
+declare function lmnt(opts: {
+    apiKey: string;
+    voice?: string;
+}): TTSConfig;
 
 declare class Patter {
     readonly apiKey: string;
@@ -282,6 +339,9 @@ declare class Patter {
     static whisper: typeof whisper;
     static elevenlabs: typeof elevenlabs;
     static openaiTts: typeof openaiTts;
+    static cartesia: typeof cartesia;
+    static rime: typeof rime;
+    static lmnt: typeof lmnt;
     static guardrail(opts: {
         name: string;
         blockedTerms?: string[];
@@ -699,19 +759,65 @@ interface Transcript$4 {
     readonly confidence: number;
 }
 type TranscriptCallback$4 = (transcript: Transcript$4) => void;
+/**
+ * Optional tuning knobs for Deepgram live transcription.
+ *
+ * Mirrors Python's ``DeepgramSTT`` kwargs so callers can lower turn latency
+ * without monkey-patching (BUG #13).
+ */
+interface DeepgramSTTOptions {
+    /** Model name. Default ``nova-3``. */
+    readonly model?: string;
+    /** Audio encoding (``linear16`` | ``mulaw`` | etc). Default ``linear16``. */
+    readonly encoding?: string;
+    /** Sample rate in Hz. Default ``16000``. */
+    readonly sampleRate?: number;
+    /**
+     * Voice-activity endpointing threshold in milliseconds.
+     * Lower values reduce turn latency at the cost of more false-start cuts.
+     * Default ``150``.
+     */
+    readonly endpointingMs?: number;
+    /**
+     * End-of-utterance silence window in milliseconds. Deepgram enforces a
+     * hard minimum of 1000 ms. Set to ``null`` to disable. Default ``1000``.
+     */
+    readonly utteranceEndMs?: number | null;
+    /** Enable smart formatting (punctuation + numerals). Default ``true``. */
+    readonly smartFormat?: boolean;
+    /** Emit interim (non-final) transcripts. Default ``true``. */
+    readonly interimResults?: boolean;
+    /** Emit VAD events (``SpeechStarted`` / ``UtteranceEnd``). Default ``true``. */
+    readonly vadEvents?: boolean;
+}
 declare class DeepgramSTT {
+    private ws;
+    private callbacks;
+    /** Request ID from Deepgram — used to query actual cost post-call. */
+    requestId: string;
     private readonly apiKey;
     private readonly language;
     private readonly model;
     private readonly encoding;
     private readonly sampleRate;
-    private ws;
-    private callbacks;
-    /** Request ID from Deepgram — used to query actual cost post-call. */
-    requestId: string;
-    constructor(apiKey: string, language?: string, model?: string, encoding?: string, sampleRate?: number);
-    /** Factory for Twilio calls — mulaw 8 kHz. */
-    static forTwilio(apiKey: string, language?: string, model?: string): DeepgramSTT;
+    private readonly endpointingMs;
+    private readonly utteranceEndMs;
+    private readonly smartFormat;
+    private readonly interimResults;
+    private readonly vadEvents;
+    /**
+     * New ergonomic constructor accepting an options object (mirrors Python kwargs).
+     *
+     * Also accepts the legacy positional form
+     * ``(apiKey, language?, model?, encoding?, sampleRate?)`` for backward
+     * compatibility with code that predated BUG #13.
+     */
+    constructor(apiKey: string, language?: string, model?: string, encoding?: string, sampleRate?: number, options?: DeepgramSTTOptions);
+    constructor(apiKey: string, options: DeepgramSTTOptions & {
+        language?: string;
+    });
+    /** Factory for Twilio calls — mulaw 8 kHz. Forwards tuning options through. */
+    static forTwilio(apiKey: string, language?: string, model?: string, options?: DeepgramSTTOptions): DeepgramSTT;
     connect(): Promise<void>;
     sendAudio(audio: Buffer): void;
     onTranscript(callback: TranscriptCallback$4): void;
@@ -750,6 +856,76 @@ declare class WhisperSTT {
     private transcribeBuffer;
 }
 
+/**
+ * In-memory metrics store for the local dashboard.
+ *
+ * Keeps the last `maxCalls` completed calls and tracks active calls.
+ * Supports SSE event subscribers for real-time updates.
+ */
+
+interface CallRecord {
+    call_id: string;
+    caller: string;
+    callee: string;
+    direction: string;
+    started_at: number;
+    ended_at?: number;
+    /**
+     * Current lifecycle state: ``initiated`` (pre-registered), ``ringing``,
+     * ``in-progress``, ``completed``, ``no-answer``, ``busy``, ``failed``,
+     * ``canceled``, or ``webhook_error``.
+     */
+    status?: string;
+    transcript?: Array<{
+        role: string;
+        text: string;
+        timestamp: number;
+    }>;
+    turns?: unknown[];
+    metrics?: Record<string, unknown> | null;
+    [key: string]: unknown;
+}
+interface SSEEvent {
+    type: string;
+    data: Record<string, unknown>;
+}
+declare class MetricsStore extends EventEmitter {
+    private readonly maxCalls;
+    private calls;
+    private activeCalls;
+    /**
+     * Accepts either a numeric ``maxCalls`` (legacy positional — matches the
+     * original TS API) or an options object ``{ maxCalls }`` to align with the
+     * Python SDK's keyword-argument style. Plain literals also work:
+     * ``new MetricsStore()`` / ``new MetricsStore(100)`` / ``new MetricsStore({ maxCalls: 100 })``.
+     */
+    constructor(maxCallsOrOpts?: number | {
+        maxCalls?: number;
+    });
+    private publish;
+    recordCallStart(data: Record<string, unknown>): void;
+    /**
+     * Pre-register an outbound call before any webhook fires. Lets the
+     * dashboard surface attempts that never reach media (no-answer, busy,
+     * carrier-rejected). Mirrors the Python ``record_call_initiated``.
+     */
+    recordCallInitiated(data: Record<string, unknown>): void;
+    /**
+     * Update the status of an active or completed call. Terminal states
+     * (completed, no-answer, busy, failed, canceled, webhook_error) move the
+     * row from active to completed so the UI freezes the live duration timer.
+     */
+    updateCallStatus(callId: string, status: string, extra?: Record<string, unknown>): void;
+    recordTurn(data: Record<string, unknown>): void;
+    recordCallEnd(data: Record<string, unknown>, metrics?: Record<string, unknown> | null): void;
+    getCalls(limit?: number, offset?: number): CallRecord[];
+    getCall(callId: string): CallRecord | null;
+    getActiveCalls(): CallRecord[];
+    getAggregates(): Record<string, unknown>;
+    getCallsInRange(fromTs?: number, toTs?: number): CallRecord[];
+    get callCount(): number;
+}
+
 /**
  * Remote message handler for B2B webhook and WebSocket integration.
  *
@@ -800,50 +976,6 @@ declare function isRemoteUrl(onMessage: unknown): onMessage is string;
 /** Check if a URL is a WebSocket URL. */
 declare function isWebSocketUrl(url: string): boolean;
 
-/**
- * In-memory metrics store for the local dashboard.
- *
- * Keeps the last `maxCalls` completed calls and tracks active calls.
- * Supports SSE event subscribers for real-time updates.
- */
-
-interface CallRecord {
-    call_id: string;
-    caller: string;
-    callee: string;
-    direction: string;
-    started_at: number;
-    ended_at?: number;
-    transcript?: Array<{
-        role: string;
-        text: string;
-        timestamp: number;
-    }>;
-    turns?: unknown[];
-    metrics?: Record<string, unknown> | null;
-    [key: string]: unknown;
-}
-interface SSEEvent {
-    type: string;
-    data: Record<string, unknown>;
-}
-declare class MetricsStore extends EventEmitter {
-    private readonly maxCalls;
-    private calls;
-    private activeCalls;
-    constructor(maxCalls?: number);
-    private publish;
-    recordCallStart(data: Record<string, unknown>): void;
-    recordTurn(data: Record<string, unknown>): void;
-    recordCallEnd(data: Record<string, unknown>, metrics?: Record<string, unknown> | null): void;
-    getCalls(limit?: number, offset?: number): CallRecord[];
-    getCall(callId: string): CallRecord | null;
-    getActiveCalls(): CallRecord[];
-    getAggregates(): Record<string, unknown>;
-    getCallsInRange(fromTs?: number, toTs?: number): CallRecord[];
-    get callCount(): number;
-}
-
 interface LocalConfig {
     twilioSid?: string;
     twilioToken?: string;
@@ -1009,6 +1141,27 @@ declare class FallbackLLMProvider implements LLMProvider {
     getAvailability(): ReadonlyArray<boolean>;
     /** Clears all background recovery timers. Call this when shutting down. */
     destroy(): void;
+    /**
+     * Async-friendly disposer. Parity with Python's ``FallbackLLMProvider.aclose()``
+     * — safe to call multiple times, returns a resolved Promise once all probe
+     * timers are cleared. Prefer this in async contexts so awaiting the
+     * shutdown integrates naturally with the owning lifecycle.
+     */
+    aclose(): Promise<void>;
+    /**
+     * Explicit-resource-management hook so callers can write
+     * ``await using fallback = new FallbackLLMProvider([...])`` and have
+     * background probe timers cleared automatically when the block exits.
+     * Mirrors Python's ``async with FallbackLLMProvider(...)``.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Stream only the text deltas, flattening the chunk envelope. Parity with
+     * Python's ``FallbackLLMProvider.complete_stream``. Tool-call and done
+     * markers are filtered out so callers can concatenate the yielded strings
+     * directly.
+     */
+    completeStream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null): AsyncGenerator<string, void, unknown>;
     stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null): AsyncGenerator<LLMChunk, void, unknown>;
     private tryProviders;
     private markUnavailable;
@@ -1159,12 +1312,33 @@ interface ScheduleHandle {
     cancel(): void;
     readonly pending: boolean;
 }
-/** Schedule ``callback`` on a cron expression (node-cron dialect). */
-declare function scheduleCron(cron: string, callback: JobCallback): Promise<ScheduleHandle>;
+/** Schedule ``callback`` on a cron expression (node-cron dialect).
+ *
+ * Returns a ``ScheduleHandle`` synchronously (parity with Python
+ * ``schedule_cron``). The handle is "pending" until the lazy ``node-cron``
+ * import resolves; cancelling the handle before then discards the pending
+ * job cleanly. If ``node-cron`` is not installed, the returned promise
+ * attached to ``.ready`` rejects with a helpful install message.
+ */
+declare function scheduleCron(cron: string, callback: JobCallback): ScheduleHandle;
 /** Schedule ``callback`` once at the given date. */
 declare function scheduleOnce(at: Date, callback: JobCallback): ScheduleHandle;
-/** Schedule ``callback`` every ``intervalMs`` milliseconds. */
-declare function scheduleInterval(intervalMs: number, callback: JobCallback): ScheduleHandle;
+/**
+ * Schedule ``callback`` on a recurring interval.
+ *
+ * Accepts either a millisecond number (legacy, matches the original TS API)
+ * or an object with ``seconds`` / ``intervalMs`` for parity with Python's
+ * ``schedule_interval(seconds=...)``.
+ *
+ * Examples:
+ *   scheduleInterval(5000, cb)              // 5 s, legacy
+ *   scheduleInterval({ intervalMs: 5000 }, cb)
+ *   scheduleInterval({ seconds: 5 }, cb)    // parity with Python
+ */
+declare function scheduleInterval(intervalOrOpts: number | {
+    seconds?: number;
+    intervalMs?: number;
+}, callback: JobCallback): ScheduleHandle;
 
 /**
  * Soniox Speech-to-Text adapter for Patter (TypeScript).
@@ -1354,9 +1528,9 @@ declare class CartesiaSTT {
 
 declare class ElevenLabsTTS {
     private readonly apiKey;
-    private readonly voiceId;
     private readonly modelId;
     private readonly outputFormat;
+    private readonly voiceId;
     constructor(apiKey: string, voiceId?: string, modelId?: string, outputFormat?: string);
     /**
      * Synthesise text to speech and return the full audio as a single Buffer.
@@ -1389,15 +1563,22 @@ declare class OpenAITTS {
      *
      * OpenAI returns 24 kHz PCM16; each chunk is resampled to 16 kHz before
      * yielding so the output is ready for telephony pipelines.
+     *
+     * The resampler carries state (buffered samples + odd trailing byte)
+     * between chunks — without that state cross-chunk sample alignment drifts
+     * and the caller hears pops / dropped audio (BUG #23, mirror of the
+     * Python `audioop.ratecv` fix).
      */
     synthesizeStream(text: string): AsyncGenerator<Buffer>;
     /**
-     * Resample 24 kHz PCM16-LE to 16 kHz by taking 2 out of every 3 samples.
-     *
-     * For each group of 3 input samples the first is kept as-is and the second
-     * output sample is the average of input samples 2 and 3.  This matches the
-     * Python SDK implementation.
+     * Streaming 24 kHz → 16 kHz resampler (PCM16-LE). Maintains cross-chunk
+     * state so the 3:2 pattern doesn't reset at every network read.
      */
+    static resampleStreaming(audio: Buffer, ctx: {
+        carryByte: number | null;
+        leftover: number[];
+    }): Buffer;
+    /** @deprecated use {@link resampleStreaming} with persistent state. */
     static resample24kTo16k(audio: Buffer): Buffer;
 }