getpatter 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,866 @@
+import { EventEmitter } from 'events';
+import { Request, Response, NextFunction, Express } from 'express';
+
+interface IncomingMessage {
+    readonly text: string;
+    readonly callId: string;
+    readonly caller: string;
+}
+interface STTConfig {
+    readonly provider: string;
+    readonly apiKey: string;
+    readonly language: string;
+    toDict(): Record<string, string>;
+}
+interface TTSConfig {
+    readonly provider: string;
+    readonly apiKey: string;
+    readonly voice: string;
+    toDict(): Record<string, string>;
+}
+type MessageHandler = (msg: IncomingMessage) => Promise<string>;
+type CallEventHandler = (data: Record<string, unknown>) => Promise<void>;
+interface PatterOptions {
+    apiKey: string;
+    backendUrl?: string;
+    restUrl?: string;
+}
+interface ConnectOptions {
+    onMessage: MessageHandler;
+    onCallStart?: CallEventHandler;
+    onCallEnd?: CallEventHandler;
+    provider?: string;
+    providerKey?: string;
+    providerSecret?: string;
+    number?: string;
+    country?: string;
+    stt?: STTConfig;
+    tts?: TTSConfig;
+}
+interface CallOptions {
+    to: string;
+    onMessage?: MessageHandler;
+    firstMessage?: string;
+    fromNumber?: string;
+    agentId?: string;
+    machineDetection?: boolean;
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    /** Webhook URL — called when the LLM invokes this tool. Mutually exclusive with handler. */
+    webhookUrl?: string;
+    /** Local handler function — when provided, called instead of webhookUrl. */
+    handler?: (args: Record<string, unknown>, context: Record<string, unknown>) => Promise<string>;
+}
+interface CreateAgentOptions {
+    name: string;
+    systemPrompt: string;
+    model?: string;
+    voice?: string;
+    voiceProvider?: string;
+    language?: string;
+    firstMessage?: string;
+    tools?: ToolDefinition[];
+}
+interface Agent {
+    id: string;
+    name: string;
+    systemPrompt: string;
+    model: string;
+    voice: string;
+    voiceProvider: string;
+    language: string;
+    firstMessage: string | null;
+    tools: ToolDefinition[] | null;
+}
+interface PhoneNumber {
+    id: string;
+    number: string;
+    provider: string;
+    country: string;
+    status: string;
+    agentId: string | null;
+}
+interface Call {
+    id: string;
+    direction: string;
+    caller: string;
+    callee: string;
+    startedAt: string;
+    endedAt: string | null;
+    durationSeconds: number | null;
+    status: string;
+    transcript: Array<{
+        role: string;
+        text: string;
+        timestamp: string;
+    }> | null;
+}
+interface LocalOptions {
+    mode: 'local';
+    twilioSid?: string;
+    twilioToken?: string;
+    openaiKey?: string;
+    phoneNumber: string;
+    webhookUrl: string;
+    telephonyProvider?: 'twilio' | 'telnyx';
+    telnyxKey?: string;
+    telnyxConnectionId?: string;
+    /**
+     * Telnyx Ed25519 public key (base64-encoded, DER/SPKI format) for webhook
+     * signature verification. When provided, unauthenticated requests are rejected.
+     */
+    telnyxPublicKey?: string;
+}
+interface Guardrail {
+    /** Name for logging when triggered */
+    name: string;
+    /** List of terms that trigger the guardrail (case-insensitive) */
+    blockedTerms?: string[];
+    /** Custom check function — return true to block the response */
+    check?: (text: string) => boolean;
+    /** Replacement text spoken when guardrail triggers */
+    replacement?: string;
+}
+interface AgentOptions {
+    systemPrompt: string;
+    voice?: string;
+    model?: string;
+    language?: string;
+    firstMessage?: string;
+    tools?: ToolDefinition[];
+    provider?: 'openai_realtime' | 'elevenlabs_convai' | 'pipeline';
+    elevenlabsKey?: string;
+    elevenlabsAgentId?: string;
+    deepgramKey?: string;
+    /** STT provider config for pipeline mode. Use ``Patter.deepgram()`` or ``Patter.whisper()``. */
+    stt?: STTConfig;
+    /** TTS provider config for pipeline mode. Use ``Patter.elevenlabs()`` or ``Patter.openaiTts()``. */
+    tts?: TTSConfig;
+    /** Dynamic variables for ``{placeholder}`` substitution in systemPrompt at call time. */
+    variables?: Record<string, string>;
+    /** Output guardrails — filter AI responses before TTS */
+    guardrails?: Guardrail[];
+}
+type PipelineMessageHandler = (data: Record<string, unknown>) => Promise<string>;
+interface ServeOptions {
+    agent: AgentOptions;
+    port?: number;
+    onCallStart?: (data: Record<string, unknown>) => Promise<void>;
+    onCallEnd?: (data: Record<string, unknown>) => Promise<void>;
+    onTranscript?: (data: Record<string, unknown>) => Promise<void>;
+    /** Pipeline mode only — called with the user's transcript; return value is spoken.
+     *  Can also be a URL string for remote webhook/WebSocket integration. */
+    onMessage?: PipelineMessageHandler | string;
+    /** Called after each turn with per-turn metrics. */
+    onMetrics?: (data: Record<string, unknown>) => Promise<void>;
+    /** When true, record calls via the Twilio Recordings API. */
+    recording?: boolean;
+    /** If set, spoken as a voicemail message when AMD detects a machine. */
+    voicemailMessage?: string;
+    /** Custom pricing overrides for cost calculation. */
+    pricing?: Record<string, Record<string, unknown>>;
+    /** When true (default), serve a dashboard UI at /dashboard. */
+    dashboard?: boolean;
+    /** Bearer token for dashboard/API authentication. */
+    dashboardToken?: string;
+    /** Path to SQLite database for dashboard persistence (not used in TS yet). */
+    dashboardDb?: string;
+    /** When true (default), persist dashboard data. */
+    dashboardPersist?: boolean;
+}
+interface LocalCallOptions {
+    to: string;
+    agent: AgentOptions;
+    machineDetection?: boolean;
+    /** If set, spoken as a voicemail message when AMD detects a machine. Requires machineDetection=true. */
+    voicemailMessage?: string;
+    /** Dynamic variables merged into agent.variables before call. Override agent-level variables. */
+    variables?: Record<string, string>;
+}
+
+declare function deepgram(opts: {
+    apiKey: string;
+    language?: string;
+}): STTConfig;
+declare function whisper(opts: {
+    apiKey: string;
+    language?: string;
+}): STTConfig;
+declare function elevenlabs(opts: {
+    apiKey: string;
+    voice?: string;
+}): TTSConfig;
+declare function openaiTts(opts: {
+    apiKey: string;
+    voice?: string;
+}): TTSConfig;
+
+declare class Patter {
+    readonly apiKey: string;
+    private readonly backendUrl;
+    private readonly restUrl;
+    private readonly connection;
+    private readonly mode;
+    private readonly localConfig;
+    private embeddedServer;
+    constructor(options: PatterOptions | LocalOptions);
+    agent(opts: AgentOptions): AgentOptions;
+    serve(opts: ServeOptions): Promise<void>;
+    test(opts: ServeOptions): Promise<void>;
+    connect(options: ConnectOptions): Promise<void>;
+    call(options: CallOptions | LocalCallOptions): Promise<void>;
+    disconnect(): Promise<void>;
+    createAgent(opts: CreateAgentOptions): Promise<Agent>;
+    listAgents(): Promise<Agent[]>;
+    buyNumber(opts?: {
+        country?: string;
+        provider?: string;
+    }): Promise<PhoneNumber>;
+    assignAgent(numberId: string, agentId: string): Promise<void>;
+    listCalls(limit?: number): Promise<Call[]>;
+    static deepgram: typeof deepgram;
+    static whisper: typeof whisper;
+    static elevenlabs: typeof elevenlabs;
+    static openaiTts: typeof openaiTts;
+    static guardrail(opts: {
+        name: string;
+        blockedTerms?: string[];
+        check?: (text: string) => boolean;
+        replacement?: string;
+    }): Guardrail;
+    /**
+     * Create a tool definition for use with `agent({ tools: [...] })`.
+     *
+     * Either `handler` (a function) or `webhookUrl` must be provided.
+     *
+     * @param opts.name - Tool name (visible to the LLM).
+     * @param opts.description - What the tool does (visible to the LLM).
+     * @param opts.parameters - JSON Schema for tool arguments.
+     * @param opts.handler - Async function called in-process when the LLM invokes the tool.
+     * @param opts.webhookUrl - URL to POST to when the LLM invokes the tool.
+     *
+     * @example
+     * ```ts
+     * phone.agent({
+     *   systemPrompt: 'You are a pizza bot.',
+     *   tools: [
+     *     Patter.tool({
+     *       name: 'check_menu',
+     *       description: 'Check available menu items',
+     *       handler: async (args) => JSON.stringify({ items: ['margherita'] }),
+     *     }),
+     *   ],
+     * });
+     * ```
+     */
+    static tool(opts: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+        handler?: (args: Record<string, unknown>, context: Record<string, unknown>) => Promise<string>;
+        webhookUrl?: string;
+    }): ToolDefinition;
+    private registerNumber;
+}
+
+interface Logger {
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+declare function getLogger(): Logger;
+declare function setLogger(logger: Logger): void;
+
+declare class PatterError extends Error {
+    constructor(message: string);
+}
+declare class PatterConnectionError extends PatterError {
+    constructor(message: string);
+}
+declare class AuthenticationError extends PatterError {
+    constructor(message: string);
+}
+declare class ProvisionError extends PatterError {
+    constructor(message: string);
+}
+
+/**
+ * Default provider pricing and merge utilities.
+ *
+ * Pricing is based on public provider rates (as of early 2025).
+ * Developers can override any provider's pricing.
+ */
+interface ProviderPricing {
+    unit: string;
+    price?: number;
+    audio_input_per_token?: number;
+    audio_output_per_token?: number;
+    text_input_per_token?: number;
+    text_output_per_token?: number;
+}
+declare const DEFAULT_PRICING: Record<string, ProviderPricing>;
+/**
+ * Merge user overrides into a copy of DEFAULT_PRICING.
+ * Performs a shallow per-provider merge.
+ */
+declare function mergePricing(overrides?: Record<string, Partial<ProviderPricing>> | null): Record<string, ProviderPricing>;
+/** Calculate STT cost from audio duration. */
+declare function calculateSttCost(provider: string, audioSeconds: number, pricing: Record<string, ProviderPricing>): number;
+/** Calculate TTS cost from character count. */
+declare function calculateTtsCost(provider: string, characterCount: number, pricing: Record<string, ProviderPricing>): number;
+/** Calculate OpenAI Realtime cost from token usage. */
+declare function calculateRealtimeCost(usage: {
+    input_token_details?: {
+        audio_tokens?: number;
+        text_tokens?: number;
+    };
+    output_token_details?: {
+        audio_tokens?: number;
+        text_tokens?: number;
+    };
+}, pricing: Record<string, ProviderPricing>): number;
+/** Calculate telephony cost from call duration. */
+declare function calculateTelephonyCost(provider: string, durationSeconds: number, pricing: Record<string, ProviderPricing>): number;
+
+/**
+ * Call metrics accumulator — tracks cost and latency during a call.
+ *
+ * Port of the Python `CallMetricsAccumulator` from `sdk/patter/services/metrics.py`.
+ */
+
+interface LatencyBreakdown {
+    stt_ms: number;
+    llm_ms: number;
+    tts_ms: number;
+    total_ms: number;
+}
+interface CostBreakdown {
+    stt: number;
+    tts: number;
+    llm: number;
+    telephony: number;
+    total: number;
+}
+interface TurnMetrics {
+    turn_index: number;
+    user_text: string;
+    agent_text: string;
+    latency: LatencyBreakdown;
+    stt_audio_seconds: number;
+    tts_characters: number;
+    timestamp: number;
+}
+interface CallMetrics {
+    call_id: string;
+    duration_seconds: number;
+    turns: TurnMetrics[];
+    cost: CostBreakdown;
+    latency_avg: LatencyBreakdown;
+    latency_p95: LatencyBreakdown;
+    provider_mode: string;
+    stt_provider: string;
+    tts_provider: string;
+    llm_provider: string;
+    telephony_provider: string;
+}
+interface CallControl {
+    /** Transfer the call to a different number. */
+    transfer(number: string): Promise<void>;
+    /** Hang up the call. */
+    hangup(): Promise<void>;
+    /** Current call ID. */
+    readonly callId: string;
+    /** Caller number. */
+    readonly caller: string;
+    /** Callee number. */
+    readonly callee: string;
+}
+declare class CallMetricsAccumulator {
+    callId: string;
+    readonly providerMode: string;
+    readonly telephonyProvider: string;
+    readonly sttProvider: string;
+    readonly ttsProvider: string;
+    readonly llmProvider: string;
+    private readonly _pricing;
+    private readonly _callStart;
+    private readonly _turns;
+    private _turnStart;
+    private _sttComplete;
+    private _llmComplete;
+    private _ttsFirstByte;
+    private _turnUserText;
+    private _turnSttAudioSeconds;
+    private _totalSttAudioSeconds;
+    private _totalTtsCharacters;
+    private _totalRealtimeCost;
+    private _sttByteCount;
+    private _sttSampleRate;
+    private _sttBytesPerSample;
+    private _actualTelephonyCost;
+    private _actualSttCost;
+    constructor(opts: {
+        callId: string;
+        providerMode: string;
+        telephonyProvider: string;
+        sttProvider?: string;
+        ttsProvider?: string;
+        llmProvider?: string;
+        pricing?: Record<string, Partial<ProviderPricing>> | null;
+    });
+    /** Configure audio format for STT byte-to-seconds conversion. */
+    configureSttFormat(sampleRate?: number, bytesPerSample?: number): void;
+    startTurn(): void;
+    recordSttComplete(text: string, audioSeconds?: number): void;
+    recordLlmComplete(): void;
+    recordTtsFirstByte(): void;
+    recordTtsComplete(text: string): void;
+    recordTurnComplete(agentText: string): TurnMetrics;
+    recordTurnInterrupted(): TurnMetrics | null;
+    addSttAudioBytes(byteCount: number): void;
+    recordRealtimeUsage(usage: {
+        input_token_details?: {
+            audio_tokens?: number;
+            text_tokens?: number;
+        };
+        output_token_details?: {
+            audio_tokens?: number;
+            text_tokens?: number;
+        };
+    }): void;
+    setActualTelephonyCost(cost: number): void;
+    setActualSttCost(cost: number): void;
+    endCall(): CallMetrics;
+    getCostSoFar(): CostBreakdown;
+    private _resetTurnState;
+    private _computeTurnLatency;
+    private _computeCost;
+    private _computeAverageLatency;
+    private _computeP95Latency;
+}
+
+declare class OpenAIRealtimeAdapter {
+    private readonly apiKey;
+    private readonly model;
+    private readonly voice;
+    private readonly instructions;
+    private readonly tools?;
+    private ws;
+    constructor(apiKey: string, model?: string, voice?: string, instructions?: string, tools?: Array<{
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    }> | undefined);
+    connect(): Promise<void>;
+    sendAudio(mulawAudio: Buffer): void;
+    onEvent(callback: (type: string, data: unknown) => void): void;
+    cancelResponse(): void;
+    sendText(text: string): Promise<void>;
+    sendFunctionResult(callId: string, result: string): Promise<void>;
+    close(): void;
+}
+
+declare class ElevenLabsConvAIAdapter {
+    private readonly apiKey;
+    private readonly agentId;
+    private readonly voiceId;
+    private readonly firstMessage;
+    private ws;
+    private eventCallback;
+    constructor(apiKey: string, agentId?: string, voiceId?: string, _modelId?: string, _language?: string, firstMessage?: string);
+    connect(): Promise<void>;
+    sendAudio(audioBytes: Buffer): void;
+    onEvent(callback: (type: string, data: unknown) => void): void;
+    close(): void;
+}
+
+interface LocalConfig {
+    twilioSid?: string;
+    twilioToken?: string;
+    openaiKey?: string;
+    phoneNumber: string;
+    webhookUrl: string;
+    telephonyProvider?: 'twilio' | 'telnyx';
+    telnyxKey?: string;
+    telnyxConnectionId?: string;
+    /**
+     * Telnyx Ed25519 public key (base64-encoded, DER/SPKI format) used to verify
+     * incoming webhook signatures. Obtain from the Telnyx portal under
+     * API Keys → Webhook Keys. When provided, unauthenticated webhook requests
+     * are rejected with HTTP 403.
+     */
+    telnyxPublicKey?: string;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Dashboard authentication middleware for Express.
+ *
+ * When a token is configured, requests must include either:
+ * - Authorization: Bearer <token> header
+ * - ?token=<token> query parameter
+ */
+
+declare function makeAuthMiddleware(token?: string): (req: Request, res: Response, next: NextFunction) => void;
+
+/**
+ * Data export utilities for the dashboard.
+ */
+
+/**
+ * Convert call list to CSV string.
+ *
+ * Columns: call_id, caller, callee, direction, started_at, ended_at,
+ * duration_s, cost_total, cost_stt, cost_tts, cost_llm, cost_telephony,
+ * avg_latency_ms, turns_count, provider_mode
+ */
+declare function callsToCsv(calls: CallRecord[]): string;
+/**
+ * Convert call list to JSON string.
+ */
+declare function callsToJson(calls: CallRecord[]): string;
+
+/**
+ * Dashboard and B2B API routes for the EmbeddedServer (Express).
+ *
+ * Mounts:
+ *   GET /                               - HTML UI
+ *   GET /api/dashboard/calls            - call list JSON
+ *   GET /api/dashboard/calls/:callId    - single call JSON
+ *   GET /api/dashboard/active           - active calls JSON
+ *   GET /api/dashboard/aggregates       - aggregate stats JSON
+ *   GET /api/dashboard/events           - SSE event stream
+ *   GET /api/dashboard/export/calls     - CSV/JSON export
+ *
+ *   GET /api/v1/calls                   - B2B paginated call history
+ *   GET /api/v1/calls/active            - B2B active calls
+ *   GET /api/v1/calls/:callId           - B2B single call detail
+ *   GET /api/v1/analytics/overview      - B2B aggregate stats
+ *   GET /api/v1/analytics/costs         - B2B cost breakdown
+ */
+
+declare function mountDashboard(app: Express, store: MetricsStore, token?: string): void;
+declare function mountApi(app: Express, store: MetricsStore, token?: string): void;
+
+/**
+ * Built-in LLM loop for pipeline mode when no onMessage handler is provided.
+ *
+ * Uses a pluggable ``LLMProvider`` interface so callers can supply OpenAI,
+ * Anthropic, Gemini, or any custom provider.  The default provider is
+ * ``OpenAILLMProvider`` which preserves full backward compatibility.
+ */
+
+/** A single streaming chunk yielded by an LLM provider. */
+interface LLMChunk {
+    type: 'text' | 'tool_call' | 'done';
+    content?: string;
+    index?: number;
+    id?: string;
+    name?: string;
+    arguments?: string;
+}
+/**
+ * Interface that any LLM provider must satisfy.
+ *
+ * Implementors yield streaming ``LLMChunk`` objects:
+ * - ``{ type: "text", content: "..." }`` — a text token.
+ * - ``{ type: "tool_call", index, id?, name?, arguments? }`` — a (partial) tool
+ *   invocation.  Chunks with the same ``index`` are concatenated.
+ * - ``{ type: "done" }`` — signals the end of the stream (optional).
+ */
+interface LLMProvider {
+    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null): AsyncGenerator<LLMChunk, void, unknown>;
+}
+/** LLM provider backed by OpenAI Chat Completions (streaming). */
+declare class OpenAILLMProvider implements LLMProvider {
+    private readonly apiKey;
+    private readonly model;
+    constructor(apiKey: string, model: string);
+    stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null): AsyncGenerator<LLMChunk, void, unknown>;
+}
+declare class LLMLoop {
+    private readonly provider;
+    private readonly systemPrompt;
+    private readonly tools;
+    private readonly openaiTools;
+    private readonly toolMap;
+    constructor(apiKey: string, model: string, systemPrompt: string, tools?: ToolDefinition[] | null, llmProvider?: LLMProvider);
+    /**
+     * Stream LLM response tokens, handling tool calls automatically.
+     * Yields text tokens as they arrive from the LLM.
+     */
+    run(userText: string, history: Array<{
+        role: string;
+        text: string;
+    }>, callContext: Record<string, unknown>): AsyncGenerator<string, void, unknown>;
+    private executeTool;
+    private buildMessages;
+}
+
+/**
+ * Remote message handler for B2B webhook and WebSocket integration.
+ *
+ * Allows onMessage to be a URL string instead of a callable:
+ * - HTTP webhook: onMessage="https://api.customer.com/patter/message"
+ * - WebSocket: onMessage="ws://localhost:9000/stream"
+ */
+declare class RemoteMessageHandler {
+    private readonly webhookSecret;
+    /**
+     * @param webhookSecret Optional HMAC secret. When provided, outgoing webhook
+     *   requests include an `X-Patter-Signature` header so the receiver can
+     *   verify the payload originated from Patter.
+     */
+    constructor(webhookSecret?: string);
+    /**
+     * Compute HMAC-SHA256 hex digest for the given body.
+     */
+    private signPayload;
+    /**
+     * Release resources held by this handler.
+     */
+    close(): void;
+    /**
+     * POST transcript to HTTP webhook, return response text.
+     *
+     * The webhook receives a JSON payload:
+     *   { text, call_id, caller, callee, history }
+     *
+     * The response can be plain text or JSON { text: "..." }.
+     *
+     * When `webhookSecret` was provided at construction time, the request
+     * includes an `X-Patter-Signature` header with the HMAC-SHA256 hex
+     * digest of the JSON body.
+     */
+    callWebhook(url: string, data: Record<string, unknown>): Promise<string>;
+    /**
+     * Send transcript via WebSocket, yield response chunks.
+     *
+     * Sends the message data as JSON. Receives one or more JSON frames
+     * with { text: "..." } - multiple frames enable streaming.
+     * A frame with { done: true } signals end of response.
+     */
+    callWebSocket(url: string, data: Record<string, unknown>): AsyncGenerator<string, void, unknown>;
+}
+/** Check if onMessage is a remote URL string. */
+declare function isRemoteUrl(onMessage: unknown): onMessage is string;
+/** Check if a URL is a WebSocket URL. */
+declare function isWebSocketUrl(url: string): boolean;
+
+/**
+ * Interactive terminal test mode for voice agents.
+ *
+ * Simulates a phone call without telephony, STT, or TTS - pure text
+ * input/output in the terminal. Useful for rapid agent development.
+ */
+
+declare class TestSession {
+    run(opts: {
+        agent: AgentOptions;
+        openaiKey?: string;
+        onMessage?: PipelineMessageHandler;
+        onCallStart?: (data: Record<string, unknown>) => Promise<void>;
+        onCallEnd?: (data: Record<string, unknown>) => Promise<void>;
+    }): Promise<void>;
+}
+
+interface Transcript$1 {
+    readonly text: string;
+    readonly isFinal: boolean;
+    readonly confidence: number;
+}
+type TranscriptCallback$1 = (transcript: Transcript$1) => void;
+declare class DeepgramSTT {
+    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;
+    connect(): Promise<void>;
+    sendAudio(audio: Buffer): void;
+    onTranscript(callback: TranscriptCallback$1): void;
+    close(): void;
+}
+
+/**
+ * OpenAI Whisper STT adapter for the Patter SDK pipeline mode.
+ *
+ * Buffers incoming PCM16 audio and periodically sends it to the
+ * OpenAI Whisper transcription API as a WAV file.
+ */
+interface Transcript {
+    readonly text: string;
+    readonly isFinal: boolean;
+    readonly confidence: number;
+}
+type TranscriptCallback = (transcript: Transcript) => void;
+declare class WhisperSTT {
+    private readonly apiKey;
+    private readonly model;
+    private readonly language;
+    private readonly bufferSize;
+    private buffer;
+    private callbacks;
+    private running;
+    constructor(apiKey: string, model?: string, language?: string, bufferSize?: number);
+    /** Factory for Twilio calls — mulaw 8 kHz is transcoded upstream, so we still receive PCM 16-bit. */
+    static forTwilio(apiKey: string, language?: string, model?: string): WhisperSTT;
+    connect(): Promise<void>;
+    sendAudio(audio: Buffer): void;
+    onTranscript(callback: TranscriptCallback): void;
+    close(): void;
+    private transcribeBuffer;
+}
+
+declare class ElevenLabsTTS {
+    private readonly apiKey;
+    private readonly voiceId;
+    private readonly modelId;
+    private readonly outputFormat;
+    constructor(apiKey: string, voiceId?: string, modelId?: string, outputFormat?: string);
+    /**
+     * Synthesise text to speech and return the full audio as a single Buffer.
+     *
+     * For large chunks (or when latency matters) call `synthesizeStream` instead.
+     */
+    synthesize(text: string): Promise<Buffer>;
+    /**
+     * Synthesise text and yield audio chunks as they arrive (streaming).
+     *
+     * The yielded buffers are raw PCM at 16 kHz (or whatever `outputFormat` is
+     * configured to).
+     */
+    synthesizeStream(text: string): AsyncGenerator<Buffer>;
+}
+
+declare class OpenAITTS {
+    private readonly apiKey;
+    private readonly voice;
+    private readonly model;
+    constructor(apiKey: string, voice?: string, model?: string);
+    /**
+     * Synthesise text to speech and return the full audio as a single Buffer.
+     *
+     * For large chunks (or when latency matters) call `synthesizeStream` instead.
+     */
+    synthesize(text: string): Promise<Buffer>;
+    /**
+     * Synthesise text and yield audio chunks as they arrive (streaming).
+     *
+     * OpenAI returns 24 kHz PCM16; each chunk is resampled to 16 kHz before
+     * yielding so the output is ready for telephony pipelines.
+     */
+    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.
+     */
+    static resample24kTo16k(audio: Buffer): Buffer;
+}
+
+/**
+ * Audio transcoding utilities for Patter TypeScript SDK.
+ *
+ * Pure TypeScript implementation — no native dependencies required.
+ * Handles mulaw (G.711) encoding/decoding and PCM16 resampling for
+ * telephony audio pipelines (Twilio mulaw 8kHz, Telnyx 16kHz PCM,
+ * OpenAI TTS 24kHz PCM).
+ */
+/**
+ * Decode mu-law 8-bit audio to signed 16-bit little-endian PCM.
+ *
+ * Each input byte produces one 16-bit sample (2 bytes), so the output
+ * buffer is exactly twice the length of the input.
+ */
+declare function mulawToPcm16(mulawData: Buffer): Buffer;
+/**
+ * Encode signed 16-bit little-endian PCM to mu-law 8-bit audio.
+ *
+ * Each pair of input bytes (one 16-bit sample) produces one output byte.
+ * If the input length is odd, the trailing byte is ignored.
+ */
+declare function pcm16ToMulaw(pcmData: Buffer): Buffer;
+/**
+ * Upsample 8 kHz PCM16 to 16 kHz using linear interpolation.
+ *
+ * For each pair of consecutive samples (s[n], s[n+1]) the output
+ * contains s[n] followed by (s[n] + s[n+1]) / 2. The last sample
+ * is duplicated to fill the final position.
+ *
+ * Output length = input length * 2.
+ */
+declare function resample8kTo16k(pcm8k: Buffer): Buffer;
+/**
+ * Downsample 16 kHz PCM16 to 8 kHz by taking every 2nd sample.
+ *
+ * Output length = input length / 2.
+ */
+declare function resample16kTo8k(pcm16k: Buffer): Buffer;
+/**
+ * Downsample 24 kHz PCM16 to 16 kHz by taking 2 of every 3 samples.
+ *
+ * Matches the Python backend approach: for every group of 3 input samples,
+ * output the 1st and 2nd, skip the 3rd.
+ *
+ * Output length = floor(inputSamples * 2 / 3) * 2 bytes.
+ */
+declare function resample24kTo16k(pcm24k: Buffer): Buffer;
+
+export { type Agent, type AgentOptions, AuthenticationError, type Call, type CallControl, type CallEventHandler, type CallMetrics, CallMetricsAccumulator, type CallOptions, type CallRecord, type ConnectOptions, type CostBreakdown, type CreateAgentOptions, DEFAULT_PRICING, DeepgramSTT, ElevenLabsConvAIAdapter, ElevenLabsTTS, type Guardrail, type IncomingMessage, type LLMChunk, LLMLoop, type LLMProvider, type LatencyBreakdown, type LocalCallOptions, type LocalConfig, type LocalOptions, type Logger, type MessageHandler, MetricsStore, OpenAILLMProvider, OpenAIRealtimeAdapter, OpenAITTS, Patter, PatterConnectionError, PatterError, type PatterOptions, type PhoneNumber, type PipelineMessageHandler, type ProviderPricing, ProvisionError, RemoteMessageHandler, type SSEEvent, type STTConfig, type ServeOptions, type TTSConfig, TestSession, type ToolDefinition, type TurnMetrics, WhisperSTT, calculateRealtimeCost, calculateSttCost, calculateTelephonyCost, calculateTtsCost, callsToCsv, callsToJson, deepgram, elevenlabs, getLogger, isRemoteUrl, isWebSocketUrl, makeAuthMiddleware, mergePricing, mountApi, mountDashboard, mulawToPcm16, openaiTts, pcm16ToMulaw, resample16kTo8k, resample24kTo16k, resample8kTo16k, setLogger, whisper };