@elevenlabs/elevenlabs-js 2.5.0 → 2.6.0

package/api/resources/conversationalAi/conversation/__tests__/Conversation.test.js

@@ -0,0 +1,358 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const Conversation_1 = require("../Conversation");
+const AudioInterface_1 = require("../AudioInterface");
+const ClientTools_1 = require("../ClientTools");
+// Mock WebSocket
+jest.mock("ws", () => {
+    return jest.fn().mockImplementation(() => ({
+        on: jest.fn(),
+        send: jest.fn(),
+        close: jest.fn(),
+        readyState: 1, // OPEN
+        OPEN: 1,
+    }));
+});
+// Mock ElevenLabsClient
+const mockClient = {
+    conversationalAi: {
+        conversations: {
+            getSignedUrl: jest.fn().mockResolvedValue({ signedUrl: "wss://test.com/signed" }),
+        },
+    },
+};
+// Mock AudioInterface
+class MockAudioInterface extends AudioInterface_1.AudioInterface {
+    start(inputCallback) {
+        this.inputCallback = inputCallback;
+    }
+    stop() {
+        this.inputCallback = undefined;
+    }
+    output(audio) {
+        // Mock output
+    }
+    interrupt() {
+        // Mock interrupt
+    }
+    simulateInput(audio) {
+        if (this.inputCallback) {
+            this.inputCallback(audio);
+        }
+    }
+}
+describe("Conversation", () => {
+    let conversation;
+    let mockAudioInterface;
+    let mockClientTools;
+    let mockWebSocket;
+    beforeEach(() => {
+        // Reset all mocks
+        jest.clearAllMocks();
+        // Create mock instances
+        mockAudioInterface = new MockAudioInterface();
+        mockClientTools = new ClientTools_1.ClientTools();
+        // Mock WebSocket constructor
+        const WebSocket = require("ws");
+        mockWebSocket = {
+            on: jest.fn(),
+            send: jest.fn(),
+            close: jest.fn(),
+            readyState: 1, // OPEN
+        };
+        WebSocket.mockImplementation(() => mockWebSocket);
+        WebSocket.OPEN = 1;
+        // Create conversation instance
+        conversation = new Conversation_1.Conversation({
+            client: mockClient,
+            agentId: "test-agent-id",
+            requiresAuth: false,
+            audioInterface: mockAudioInterface,
+            clientTools: mockClientTools,
+        });
+    });
+    afterEach(() => {
+        conversation.endSession();
+    });
+    describe("constructor", () => {
+        it("should initialize with correct properties", () => {
+            expect(conversation.getConversationId()).toBeUndefined();
+            expect(conversation.isSessionActive()).toBe(false);
+        });
+        it("should accept callback functions", () => {
+            const agentResponseCallback = jest.fn();
+            const userTranscriptCallback = jest.fn();
+            const conversationWithCallbacks = new Conversation_1.Conversation({
+                client: mockClient,
+                agentId: "test-agent-id",
+                requiresAuth: false,
+                audioInterface: mockAudioInterface,
+                callbackAgentResponse: agentResponseCallback,
+                callbackUserTranscript: userTranscriptCallback,
+            });
+            expect(conversationWithCallbacks).toBeDefined();
+        });
+    });
+    describe("startSession", () => {
+        it("should start a session without auth", () => __awaiter(void 0, void 0, void 0, function* () {
+            // Mock WebSocket events
+            mockWebSocket.on.mockImplementation((event, callback) => {
+                if (event === "open") {
+                    setTimeout(() => callback(), 0);
+                }
+            });
+            yield conversation.startSession();
+            expect(mockWebSocket.on).toHaveBeenCalledWith("open", expect.any(Function));
+            expect(mockWebSocket.on).toHaveBeenCalledWith("message", expect.any(Function));
+            expect(mockWebSocket.on).toHaveBeenCalledWith("error", expect.any(Function));
+            expect(mockWebSocket.on).toHaveBeenCalledWith("close", expect.any(Function));
+        }));
+        it("should start a session with auth", () => __awaiter(void 0, void 0, void 0, function* () {
+            const authConversation = new Conversation_1.Conversation({
+                client: mockClient,
+                agentId: "test-agent-id",
+                requiresAuth: true,
+                audioInterface: mockAudioInterface,
+            });
+            mockWebSocket.on.mockImplementation((event, callback) => {
+                if (event === "open") {
+                    setTimeout(() => callback(), 0);
+                }
+            });
+            yield authConversation.startSession();
+            expect(mockClient.conversationalAi.conversations.getSignedUrl).toHaveBeenCalledWith({
+                agentId: "test-agent-id",
+            });
+        }));
+        it("should throw error if session already started", () => __awaiter(void 0, void 0, void 0, function* () {
+            mockWebSocket.on.mockImplementation((event, callback) => {
+                if (event === "open") {
+                    setTimeout(() => callback(), 0);
+                }
+            });
+            yield conversation.startSession();
+            yield expect(conversation.startSession()).rejects.toThrow("Session already started");
+        }));
+    });
+    describe("message handling", () => {
+        beforeEach(() => __awaiter(void 0, void 0, void 0, function* () {
+            mockWebSocket.on.mockImplementation((event, callback) => {
+                if (event === "open") {
+                    setTimeout(() => callback(), 0);
+                }
+            });
+            yield conversation.startSession();
+        }));
+        it("should send user messages", () => {
+            conversation.sendUserMessage("Hello, how are you?");
+            expect(mockWebSocket.send).toHaveBeenCalledWith(JSON.stringify({
+                type: "user_message",
+                text: "Hello, how are you?",
+            }));
+        });
+        it("should register user activity", () => {
+            conversation.registerUserActivity();
+            expect(mockWebSocket.send).toHaveBeenCalledWith(JSON.stringify({
+                type: "user_activity",
+            }));
+        });
+        it("should send contextual updates", () => {
+            conversation.sendContextualUpdate("User is looking at product page");
+            expect(mockWebSocket.send).toHaveBeenCalledWith(JSON.stringify({
+                type: "contextual_update",
+                text: "User is looking at product page",
+            }));
+        });
+        it("should throw error when sending message without active session", () => {
+            conversation.endSession();
+            expect(() => conversation.sendUserMessage("test")).toThrow("Session not started or websocket not connected");
+        });
+    });
+    describe("message receiving", () => {
+        let messageHandler;
+        let agentResponseCallback;
+        let userTranscriptCallback;
+        beforeEach(() => __awaiter(void 0, void 0, void 0, function* () {
+            agentResponseCallback = jest.fn();
+            userTranscriptCallback = jest.fn();
+            conversation = new Conversation_1.Conversation({
+                client: mockClient,
+                agentId: "test-agent-id",
+                requiresAuth: false,
+                audioInterface: mockAudioInterface,
+                callbackAgentResponse: agentResponseCallback,
+                callbackUserTranscript: userTranscriptCallback,
+            });
+            mockWebSocket.on.mockImplementation((event, callback) => {
+                if (event === "open") {
+                    setTimeout(() => callback(), 0);
+                }
+                else if (event === "message") {
+                    messageHandler = callback;
+                }
+            });
+            yield conversation.startSession();
+        }));
+        it("should handle conversation initiation metadata", () => {
+            const message = {
+                type: "conversation_initiation_metadata",
+                conversation_initiation_metadata_event: {
+                    conversation_id: "test-conversation-123",
+                },
+            };
+            messageHandler(Buffer.from(JSON.stringify(message)));
+            expect(conversation.getConversationId()).toBe("test-conversation-123");
+        });
+        it("should handle agent responses", () => {
+            const message = {
+                type: "agent_response",
+                agent_response_event: {
+                    agent_response: "  Hello! How can I help you today?  ",
+                },
+            };
+            messageHandler(Buffer.from(JSON.stringify(message)));
+            expect(agentResponseCallback).toHaveBeenCalledWith("Hello! How can I help you today?");
+        });
+        it("should handle user transcripts", () => {
+            const message = {
+                type: "user_transcript",
+                user_transcription_event: {
+                    user_transcript: "  Hello, I need help  ",
+                },
+            };
+            messageHandler(Buffer.from(JSON.stringify(message)));
+            expect(userTranscriptCallback).toHaveBeenCalledWith("Hello, I need help");
+        });
+        it("should handle audio messages", () => {
+            const audioData = Buffer.from("test audio data").toString("base64");
+            const message = {
+                type: "audio",
+                audio_event: {
+                    event_id: "1",
+                    audio_base_64: audioData,
+                },
+            };
+            const outputSpy = jest.spyOn(mockAudioInterface, "output");
+            messageHandler(Buffer.from(JSON.stringify(message)));
+            expect(outputSpy).toHaveBeenCalledWith(Buffer.from("test audio data"));
+        });
+        it("should handle ping messages", () => {
+            const message = {
+                type: "ping",
+                ping_event: {
+                    event_id: "ping-123",
+                    ping_ms: "50",
+                },
+            };
+            messageHandler(Buffer.from(JSON.stringify(message)));
+            expect(mockWebSocket.send).toHaveBeenCalledWith(JSON.stringify({
+                type: "pong",
+                event_id: "ping-123",
+            }));
+        });
+    });
+    describe("client tools integration", () => {
+        let messageHandler;
+        beforeEach(() => __awaiter(void 0, void 0, void 0, function* () {
+            mockWebSocket.on.mockImplementation((event, callback) => {
+                if (event === "open") {
+                    setTimeout(() => callback(), 0);
+                }
+                else if (event === "message") {
+                    messageHandler = callback;
+                }
+            });
+            yield conversation.startSession();
+        }));
+        it("should handle client tool calls", () => __awaiter(void 0, void 0, void 0, function* () {
+            // Register a test tool
+            mockClientTools.register("test_tool", (params) => {
+                return `Tool called with: ${params.input}`;
+            });
+            const message = {
+                type: "client_tool_call",
+                client_tool_call: {
+                    tool_name: "test_tool",
+                    tool_call_id: "call-123",
+                    parameters: {
+                        input: "test input",
+                    },
+                },
+            };
+            messageHandler(Buffer.from(JSON.stringify(message)));
+            // Wait for async tool execution
+            yield new Promise(resolve => setTimeout(resolve, 10));
+            expect(mockWebSocket.send).toHaveBeenLastCalledWith(JSON.stringify({
+                type: "client_tool_result",
+                tool_call_id: "call-123",
+                result: "Tool called with: test input",
+                is_error: false,
+            }));
+        }));
+    });
+    describe("session management", () => {
+        it("should properly end session", () => __awaiter(void 0, void 0, void 0, function* () {
+            mockWebSocket.on.mockImplementation((event, callback) => {
+                if (event === "open") {
+                    setTimeout(() => callback(), 0);
+                }
+            });
+            yield conversation.startSession();
+            // Wait for session to be fully started
+            yield new Promise(resolve => setTimeout(resolve, 10));
+            expect(conversation.isSessionActive()).toBe(true);
+            conversation.endSession();
+            expect(conversation.isSessionActive()).toBe(false);
+            expect(mockWebSocket.close).toHaveBeenCalled();
+        }));
+        it("should emit session events", () => __awaiter(void 0, void 0, void 0, function* () {
+            const sessionStartedSpy = jest.fn();
+            const sessionEndedSpy = jest.fn();
+            conversation.on("session_started", sessionStartedSpy);
+            conversation.on("session_ended", sessionEndedSpy);
+            mockWebSocket.on.mockImplementation((event, callback) => {
+                if (event === "open") {
+                    setTimeout(() => callback(), 0);
+                }
+            });
+            yield conversation.startSession();
+            conversation.endSession();
+            // Wait for events to be emitted
+            yield new Promise(resolve => setTimeout(resolve, 10));
+            expect(sessionStartedSpy).toHaveBeenCalled();
+            expect(sessionEndedSpy).toHaveBeenCalled();
+        }));
+    });
+    describe("audio integration", () => {
+        it("should start audio interface on session start", () => __awaiter(void 0, void 0, void 0, function* () {
+            const startSpy = jest.spyOn(mockAudioInterface, "start");
+            mockWebSocket.on.mockImplementation((event, callback) => {
+                if (event === "open") {
+                    setTimeout(() => callback(), 0);
+                }
+            });
+            yield conversation.startSession();
+            expect(startSpy).toHaveBeenCalled();
+        }));
+        it("should stop audio interface on session end", () => __awaiter(void 0, void 0, void 0, function* () {
+            const stopSpy = jest.spyOn(mockAudioInterface, "stop");
+            mockWebSocket.on.mockImplementation((event, callback) => {
+                if (event === "open") {
+                    setTimeout(() => callback(), 0);
+                }
+            });
+            yield conversation.startSession();
+            conversation.endSession();
+            expect(stopSpy).toHaveBeenCalled();
+        }));
+    });
+});

package/api/resources/conversationalAi/conversation/events.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Event types that can be sent from client to orchestrator.
+ */
+export declare enum ClientToOrchestratorEvent {
+    /** Response to a ping request. */
+    PONG = "pong",
+    CLIENT_TOOL_RESULT = "client_tool_result",
+    CONVERSATION_INITIATION_CLIENT_DATA = "conversation_initiation_client_data",
+    FEEDBACK = "feedback",
+    /** Non-interrupting content that is sent to the server to update the conversation state. */
+    CONTEXTUAL_UPDATE = "contextual_update",
+    /** User text message. */
+    USER_MESSAGE = "user_message",
+    USER_ACTIVITY = "user_activity"
+}
+/**
+ * Base interface for all client-to-orchestrator events.
+ */
+export interface BaseClientToOrchestratorEvent {
+    type: ClientToOrchestratorEvent;
+}
+/**
+ * Event for sending user text messages.
+ */
+export interface UserMessageClientToOrchestratorEvent extends BaseClientToOrchestratorEvent {
+    type: ClientToOrchestratorEvent.USER_MESSAGE;
+    text?: string;
+}
+/**
+ * Event for registering user activity (ping to prevent timeout).
+ */
+export interface UserActivityClientToOrchestratorEvent extends BaseClientToOrchestratorEvent {
+    type: ClientToOrchestratorEvent.USER_ACTIVITY;
+}
+/**
+ * Event for sending non-interrupting contextual updates to the conversation state.
+ */
+export interface ContextualUpdateClientToOrchestratorEvent extends BaseClientToOrchestratorEvent {
+    type: ClientToOrchestratorEvent.CONTEXTUAL_UPDATE;
+    text: string;
+}
+/**
+ * Event for conversation initiation with client data.
+ */
+export interface ConversationInitiationClientDataEvent extends BaseClientToOrchestratorEvent {
+    type: ClientToOrchestratorEvent.CONVERSATION_INITIATION_CLIENT_DATA;
+    custom_llm_extra_body?: Record<string, any>;
+    conversation_config_override?: Record<string, any>;
+    dynamic_variables?: Record<string, any>;
+}
+/**
+ * Event for client tool results.
+ */
+export interface ClientToolResultEvent extends BaseClientToOrchestratorEvent {
+    type: ClientToOrchestratorEvent.CLIENT_TOOL_RESULT;
+    tool_call_id?: string;
+    result: any;
+    is_error: boolean;
+}
+/**
+ * Event for pong response.
+ */
+export interface PongEvent extends BaseClientToOrchestratorEvent {
+    type: ClientToOrchestratorEvent.PONG;
+    event_id: string;
+}
+/**
+ * Event for sending feedback.
+ */
+export interface FeedbackEvent extends BaseClientToOrchestratorEvent {
+    type: ClientToOrchestratorEvent.FEEDBACK;
+    feedback: string;
+    rating?: number;
+}
+/**
+ * Event for sending user audio chunks.
+ */
+export interface UserAudioChunkEvent {
+    user_audio_chunk: string;
+}
+/**
+ * Union type for all client-to-orchestrator events.
+ */
+export type ClientToOrchestratorEventUnion = UserMessageClientToOrchestratorEvent | UserActivityClientToOrchestratorEvent | ContextualUpdateClientToOrchestratorEvent | ConversationInitiationClientDataEvent | ClientToolResultEvent | PongEvent | FeedbackEvent;

package/api/resources/conversationalAi/conversation/events.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientToOrchestratorEvent = void 0;
+/**
+ * Event types that can be sent from client to orchestrator.
+ */
+var ClientToOrchestratorEvent;
+(function (ClientToOrchestratorEvent) {
+    /** Response to a ping request. */
+    ClientToOrchestratorEvent["PONG"] = "pong";
+    ClientToOrchestratorEvent["CLIENT_TOOL_RESULT"] = "client_tool_result";
+    ClientToOrchestratorEvent["CONVERSATION_INITIATION_CLIENT_DATA"] = "conversation_initiation_client_data";
+    ClientToOrchestratorEvent["FEEDBACK"] = "feedback";
+    /** Non-interrupting content that is sent to the server to update the conversation state. */
+    ClientToOrchestratorEvent["CONTEXTUAL_UPDATE"] = "contextual_update";
+    /** User text message. */
+    ClientToOrchestratorEvent["USER_MESSAGE"] = "user_message";
+    ClientToOrchestratorEvent["USER_ACTIVITY"] = "user_activity";
+})(ClientToOrchestratorEvent || (exports.ClientToOrchestratorEvent = ClientToOrchestratorEvent = {}));

package/api/resources/conversationalAi/conversation/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./Conversation";
+export * from "./ClientTools";
+export * from "./events";
+export * from "./ConversationConfig";
+export * from "./DefaultAudioInterface";
+export * from "./AudioInterface";

package/api/resources/conversationalAi/conversation/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./Conversation"), exports);
+__exportStar(require("./ClientTools"), exports);
+__exportStar(require("./events"), exports);
+__exportStar(require("./ConversationConfig"), exports);
+__exportStar(require("./DefaultAudioInterface"), exports);
+__exportStar(require("./AudioInterface"), exports);

package/api/resources/conversationalAi/conversation/interfaces/ConversationClient.d.ts

@@ -0,0 +1,11 @@
+export interface ConversationClient {
+    conversationalAi: {
+        conversations: {
+            getSignedUrl(params: {
+                agentId: string;
+            }): Promise<{
+                signedUrl: string;
+            }>;
+        };
+    };
+}

package/api/resources/conversationalAi/conversation/interfaces/ConversationClient.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/api/resources/conversationalAi/conversation/interfaces/WebSocketInterface.d.ts

@@ -0,0 +1,12 @@
+import { EventEmitter } from "events";
+export interface WebSocketInterface extends EventEmitter {
+    readyState: number;
+    send(data: string): void;
+    close(): void;
+}
+export interface WebSocketFactory {
+    create(url: string, options?: any): WebSocketInterface;
+}
+export declare class DefaultWebSocketFactory implements WebSocketFactory {
+    create(url: string, options?: any): WebSocketInterface;
+}

package/api/resources/conversationalAi/conversation/interfaces/WebSocketInterface.js

@@ -0,0 +1,13 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultWebSocketFactory = void 0;
+const ws_1 = __importDefault(require("ws"));
+class DefaultWebSocketFactory {
+    create(url, options) {
+        return new ws_1.default(url, options);
+    }
+}
+exports.DefaultWebSocketFactory = DefaultWebSocketFactory;

package/api/resources/conversationalAi/conversation/mocks/ConversationTestFactory.d.ts

@@ -0,0 +1,15 @@
+import { Conversation } from "../Conversation";
+import { MockAudioInterface, MockConversationClient, MockWebSocket } from "./MockConversation";
+import { ClientTools } from "../ClientTools";
+export interface TestConversationSetup {
+    conversation: Conversation;
+    mockWebSocket: MockWebSocket;
+    mockAudio: MockAudioInterface;
+    mockClient: MockConversationClient;
+    mockTools: ClientTools;
+}
+export declare function createTestConversation(options?: {
+    agentId?: string;
+    requiresAuth?: boolean;
+    config?: any;
+}): TestConversationSetup;

package/api/resources/conversationalAi/conversation/mocks/ConversationTestFactory.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTestConversation = createTestConversation;
+const Conversation_1 = require("../Conversation");
+const MockConversation_1 = require("./MockConversation");
+const ClientTools_1 = require("../ClientTools");
+function createTestConversation(options = {}) {
+    const mockWebSocketFactory = new MockConversation_1.MockWebSocketFactory();
+    const mockAudio = new MockConversation_1.MockAudioInterface();
+    const mockClient = new MockConversation_1.MockConversationClient();
+    const mockTools = new ClientTools_1.ClientTools();
+    const conversation = new Conversation_1.Conversation({
+        conversationClient: mockClient,
+        webSocketFactory: mockWebSocketFactory,
+        agentId: options.agentId || "test-agent-id",
+        requiresAuth: options.requiresAuth || false,
+        audioInterface: mockAudio,
+        clientTools: mockTools,
+        config: options.config
+    });
+    return {
+        conversation,
+        mockWebSocket: mockWebSocketFactory.getMockWebSocket(),
+        mockAudio,
+        mockClient,
+        mockTools
+    };
+}

package/api/resources/conversationalAi/conversation/mocks/MockConversation.d.ts

@@ -0,0 +1,43 @@
+import { EventEmitter } from "events";
+import { WebSocketInterface, WebSocketFactory } from "../interfaces/WebSocketInterface";
+import { ConversationClient } from "../interfaces/ConversationClient";
+import { AudioInterface } from "../AudioInterface";
+export declare class MockWebSocket extends EventEmitter implements WebSocketInterface {
+    readyState: number;
+    private mockMessages;
+    send(data: string): void;
+    close(): void;
+    simulateMessage(message: any): void;
+    simulateError(error: Error): void;
+    simulateOpen(): void;
+    getSentMessages(): any[];
+    getLastMessage(): any;
+    clearMessages(): void;
+}
+export declare class MockWebSocketFactory implements WebSocketFactory {
+    private mockWebSocket;
+    create(url: string, options?: any): WebSocketInterface;
+    getMockWebSocket(): MockWebSocket;
+}
+export declare class MockAudioInterface extends AudioInterface {
+    private inputCallback?;
+    private outputBuffer;
+    private isStarted;
+    start(inputCallback: (audio: Buffer) => void): void;
+    stop(): void;
+    output(audio: Buffer): void;
+    interrupt(): void;
+    simulateAudioInput(audio: Buffer): void;
+    getOutputBuffer(): Buffer[];
+    clearOutputBuffer(): void;
+    isAudioStarted(): boolean;
+}
+export declare class MockConversationClient implements ConversationClient {
+    private mockSignedUrl;
+    conversationalAi: {
+        conversations: {
+            getSignedUrl: jest.Mock<any, any, any>;
+        };
+    };
+    setMockSignedUrl(url: string): void;
+}