@telnyx/ai-agent-lib 0.2.10 → 0.2.12

package/dist/agent-state.d.ts

@@ -0,0 +1,3 @@
+import EventEmitter from "eventemitter3";
+import type { AgentStateEvents } from "./types";
+export declare const agentStateBus: EventEmitter<AgentStateEvents, any>;

package/dist/audio-stream-monitor.d.ts

@@ -0,0 +1,55 @@
+import type { VADOptions } from "./types";
+export declare class AudioStreamMonitor {
+    private remoteIntervalId;
+    private localIntervalId;
+    private remoteStream;
+    private localStream;
+    private remoteAudioContext;
+    private remoteSource;
+    private remoteAnalyser;
+    private localAudioContext;
+    private localSource;
+    private localAnalyser;
+    private thinkingStartTime;
+    private lastState;
+    private userIsSpeaking;
+    private lastUserAudioTime;
+    private userSpeechStartTime;
+    private userSilenceStartTime;
+    private isFirstAgentSpeech;
+    private monitorStartTime;
+    private volumeThreshold;
+    private silenceDurationMs;
+    private minSpeechDurationMs;
+    private maxLatencyMs;
+    constructor(options?: VADOptions);
+    private updateAgentState;
+    /**
+     * Set the remote audio stream (agent's voice) to monitor for speech detection
+     */
+    setRemoteStream(stream: MediaStream): void;
+    /**
+     * Set the local audio stream (user's microphone) to monitor for VAD
+     */
+    setLocalStream(stream: MediaStream): void;
+    setMonitoredAudioStream(stream: MediaStream): void;
+    private stopRemoteMonitor;
+    private stopLocalMonitor;
+    /**
+     * Reset all latency tracking state for a fresh call.
+     * Should be called when a call ends to prevent stale data affecting the next call.
+     */
+    private resetLatencyState;
+    stopAudioStreamMonitor(): void;
+    /**
+     * Monitor remote stream (agent's audio) for speech detection
+     * Detects when agent starts speaking to calculate latency
+     */
+    private startRemoteMonitor;
+    /**
+     * Monitor local stream (user's microphone) for VAD
+     * Detects when user stops speaking (1000ms of silence) to start latency measurement
+     */
+    private startLocalMonitor;
+    destroy(): void;
+}

package/dist/client.d.ts

@@ -0,0 +1,109 @@
+import { Call } from "@telnyx/webrtc";
+import EventEmitter from "eventemitter3";
+import type { AIAgentEvents, TranscriptItem, VADOptions } from "./types";
+export type TelnyxAIAgentConstructorParams = {
+    agentId: string;
+    versionId?: string;
+    environment?: "production" | "development";
+    debug?: boolean;
+    trickleIce?: boolean;
+    /**
+     * Voice Activity Detection options for controlling speech detection and latency measurement.
+     */
+    vad?: VADOptions;
+};
+export declare class TelnyxAIAgent extends EventEmitter<AIAgentEvents> {
+    private telnyxRTC;
+    private transcription;
+    agentId: string;
+    versionId: string;
+    debug: boolean;
+    private audioStreamMonitor;
+    activeCall: Call | null;
+    constructor(params: TelnyxAIAgentConstructorParams);
+    /**
+     * Connects to the Telnyx WebRTC service and establishes a session with the AI agent.
+     *
+     * @returns Promise that resolves when the connection is established
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the Telnyx WebRTC service and cleans up all event listeners.
+     * Emits an 'agent.disconnected' event before completing cleanup.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Sends a text message to the AI agent during an active conversation.
+     * Requires an active conversation to be in progress.
+     *
+     * @param message - The text message to send to the AI agent
+     * @param attachments - Optional array of base64 encoded file attachments (defaults to empty array)
+     *
+     * @example
+     * client.sendConversationMessage('Hello, I need help with my account');
+     *
+     * @example
+     * // With attachments
+     * client.sendConversationMessage('Please review this document', ['base64EncodedData...']);
+     */
+    sendConversationMessage(message: string, attachments?: string[]): void;
+    /**
+     * Gets the current conversation transcript.
+     *
+     * @returns Array of transcript items containing all messages exchanged during the conversation
+     */
+    get transcript(): TranscriptItem[];
+    /**
+     * Initiates a conversation with the AI agent.
+     *
+     * @param options - Optional configuration for the call.
+     * Note: This method will ALWAYS call the AI agent, the optional parameters are primarily used for log referencing or passing parameters to the agent via the custom headers.
+     * @param options.destinationNumber - The destination phone number (defaults to "xxx"). Note, regardless of the destination number, the call will be made to the AI agent.
+     * @param options.callerNumber - The caller's phone number
+     * @param options.callerName - The caller's display name
+     * @param options.customHeaders - Custom SIP headers to pass to the AI agent. Headers with the `X-` prefix
+     * will be mapped to dynamic variables in the AI assistant (e.g., `X-Account-Number` becomes `{{account_number}}`).
+     * Note: Hyphens in header names are converted to underscores in variable names.
+     *
+     * @example
+     * // Start conversation with custom headers for dynamic variables
+     * client.startConversation({
+     *   callerName: 'John Doe',
+     *   customHeaders: [
+     *     { name: 'X-User-Name', value: 'user-name' },
+     *     { name: 'X-Agent-Session', value: 'session-abc' }
+     *   ]
+     * });
+     * // These headers will be available in your AI assistant as {{user_name}} and {{agent_session}}
+     * @param options.audio - Audio constraints for the call (boolean or MediaTrackConstraints)
+     */
+    startConversation(options?: {
+        destinationNumber?: string;
+        callerNumber?: string;
+        callerName?: string;
+        customHeaders?: {
+            name: string;
+            value: string;
+        }[];
+        audio?: boolean | MediaTrackConstraints;
+    }): Promise<void>;
+    /**
+     * Ends the current active conversation with the AI agent.
+     *
+     * @returns Promise that resolves when the call is hung up, or undefined if there is no active call
+     */
+    endConversation(): void | undefined;
+    /**
+     * Sets the remote audio stream for monitoring agent speech.
+     * Use this when call.remoteStream is not available and you need to provide
+     * the stream from the peer connection receiver.
+     *
+     * @param stream - The MediaStream containing the remote (agent) audio
+     */
+    setRemoteStream(stream: MediaStream): void;
+    private onClientReady;
+    private onClientOrSocketError;
+    private onNotification;
+    private onTranscriptItem;
+    private onAgentStateChange;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./client";
+export * from "./react/client-context";
+export * from "./react/use-transcript";
+export * from "./react/use-client-connection-state";
+export * from "./react/use-client";
+export * from "./react/use-conversation";
+export * from "./react/use-agent-state";
+export * from "./types";