@elevenlabs/elevenlabs-js 2.46.0 → 2.48.0

package/dist/wrapper/speech-engine/SpeechEngineResource.js

@@ -0,0 +1,261 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+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());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpeechEngineResource = void 0;
+exports.verifySpeechEngineJwt = verifySpeechEngineJwt;
+const node_crypto_1 = require("node:crypto");
+const ws_1 = __importDefault(require("ws"));
+const core = __importStar(require("../../core"));
+const types_1 = require("./types");
+const SpeechEngineSession_1 = require("./SpeechEngineSession");
+const SpeechEngineAttachment_1 = require("./SpeechEngineAttachment");
+/**
+ * Represents a speech engine instance. Returned by `elevenlabs.speechEngine.get()`.
+ *
+ * Use `engine.attach(httpServer, path, callbacks)` to integrate with an existing
+ * HTTP server, or drop down to `engine.verifyRequest()` and `engine.createSession()`
+ * for full control.
+ *
+ * @example
+ * ```typescript
+ * const engine = await elevenlabs.speechEngine.get("seng_123");
+ *
+ * engine.attach(httpServer, "/api/speech-engine/ws", {
+ *     async onTranscript(transcript, signal, session) {
+ *         session.sendResponse(await llm.generate(transcript, { signal }));
+ *     },
+ * });
+ * ```
+ */
+class SpeechEngineResource {
+    /** @internal */
+    constructor(engineId, options) {
+        this.engineId = engineId;
+        this._options = options;
+    }
+    /**
+     * Attach to an existing HTTP server and begin accepting Speech Engine
+     * connections at the given path.
+     *
+     * Handles WebSocket upgrades, path routing, and request verification
+     * automatically. Returns a `SpeechEngineAttachment` whose `.close()` stops
+     * accepting connections without affecting the HTTP server.
+     *
+     * @example
+     * ```typescript
+     * engine.attach(httpServer, "/api/speech-engine/ws", {
+     *     async onTranscript(transcript, signal, session) {
+     *         const stream = await openai.responses.create({ model: "gpt-4o", input: transcript, stream: true }, { signal });
+     *         session.sendResponse(stream);
+     *     },
+     * });
+     * ```
+     */
+    attach(httpServer, path, handler) {
+        var _a;
+        const debug = (_a = handler.debug) !== null && _a !== void 0 ? _a : false;
+        const log = debug ? (...args) => console.log("[SpeechEngine]", ...args) : () => { };
+        const wss = new ws_1.default.Server({ noServer: true });
+        const upgradeListener = (req, socket, head) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const url = new URL((_a = req.url) !== null && _a !== void 0 ? _a : "/", `http://${req.headers.host}`);
+            log(`upgrade request: ${req.method} ${url.pathname}`);
+            if (url.pathname !== path) {
+                log(`path mismatch: expected ${path}, got ${url.pathname} — skipping`);
+                return;
+            }
+            if (!(yield this.verifyRequest(req))) {
+                // verifyRequest returned false — get the detailed reason for debug logging
+                const reason = yield this.getVerificationFailure(req);
+                log(`rejected connection — ${reason}`);
+                socket.destroy();
+                return;
+            }
+            log("upgrading connection to WebSocket");
+            wss.handleUpgrade(req, socket, head, (ws) => {
+                log("WebSocket connection established");
+                wss.emit("connection", ws);
+            });
+        });
+        httpServer.on("upgrade", upgradeListener);
+        wss.on("connection", (ws) => {
+            log("creating new session");
+            const session = this.createSession(ws, { debug });
+            this.wireHandler(session, handler);
+        });
+        log(`listening for WebSocket upgrades on ${path}`);
+        return new SpeechEngineAttachment_1.SpeechEngineAttachment(wss, httpServer, upgradeListener);
+    }
+    /**
+     * Verify that an incoming HTTP upgrade request is a legitimate connection
+     * from the ElevenLabs Speech Engine API.
+     *
+     * Checks the `X-Elevenlabs-Speech-Engine-Authorization` header for a valid
+     * JWT signed with the SHA-256 hash of the API key.
+     *
+     * Only needed when managing the WebSocket upgrade yourself. When using
+     * `engine.attach()`, verification is handled automatically.
+     */
+    verifyRequest(req) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return (yield this.getVerificationFailure(req)) === null;
+        });
+    }
+    /** @internal Returns `null` when the request is valid, or a human-readable reason when rejected. */
+    getVerificationFailure(req) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const apiKey = yield core.Supplier.get(this._options.apiKey);
+            if (!apiKey) {
+                return "no API key configured on the client";
+            }
+            const raw = req.headers["x-elevenlabs-speech-engine-authorization"];
+            const headerValue = Array.isArray(raw) ? raw[0] : raw;
+            if (!headerValue) {
+                return "missing X-Elevenlabs-Speech-Engine-Authorization header";
+            }
+            try {
+                verifySpeechEngineJwt(headerValue, apiKey);
+                return null;
+            }
+            catch (err) {
+                return err instanceof Error ? err.message : String(err);
+            }
+        });
+    }
+    /**
+     * Wrap an accepted WebSocket in a `SpeechEngineSession`.
+     *
+     * Only needed when managing the WebSocket upgrade yourself. When using
+     * `engine.attach()`, sessions are created automatically.
+     */
+    createSession(ws, options) {
+        return new SpeechEngineSession_1.SpeechEngineSession(ws, options);
+    }
+    /** @internal */
+    wireHandler(session, handler) {
+        const { onInit, onTranscript, onClose, onDisconnect, onError } = handler;
+        if (onInit)
+            session.on("init", (id) => onInit.call(session, id, session));
+        if (onTranscript) {
+            session.on("user_transcript", (t, s) => {
+                Promise.resolve(onTranscript.call(session, t, s, session)).catch((err) => {
+                    if ((0, types_1.isAbortError)(err))
+                        return;
+                    const error = err instanceof Error ? err : new Error(String(err));
+                    if (onError)
+                        onError.call(session, error, session);
+                });
+            });
+        }
+        if (onClose)
+            session.on("close", () => onClose.call(session, session));
+        if (onDisconnect)
+            session.on("disconnected", () => onDisconnect.call(session, session));
+        if (onError)
+            session.on("error", (err) => onError.call(session, err, session));
+    }
+}
+exports.SpeechEngineResource = SpeechEngineResource;
+// ---------------------------------------------------------------------------
+// JWT verification (HS256, no external dependency)
+// ---------------------------------------------------------------------------
+const ISSUER = "https://api.elevenlabs.io/convai/speech-engine";
+const SUBJECT = "convai_speech_engine_upstream";
+const LEEWAY_SECONDS = 60;
+function base64UrlDecode(input) {
+    const padded = input.replace(/-/g, "+").replace(/_/g, "/");
+    return Buffer.from(padded, "base64");
+}
+/** @internal — exported for testing only */
+function verifySpeechEngineJwt(value, apiKey) {
+    let token = value.trim();
+    if (token.toLowerCase().startsWith("bearer ")) {
+        token = token.slice(7).trim();
+    }
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+        throw new Error("Invalid JWT: expected 3 parts");
+    }
+    const [headerB64, payloadB64, signatureB64] = parts;
+    let payload;
+    try {
+        payload = JSON.parse(base64UrlDecode(payloadB64).toString("utf-8"));
+    }
+    catch (_a) {
+        throw new Error("Invalid JWT: failed to decode payload");
+    }
+    // SHA-256 hash of the API key, used as the HMAC secret
+    const trimmedKey = apiKey.trim();
+    const secret = (0, node_crypto_1.createHash)("sha256").update(trimmedKey, "utf-8").digest();
+    const expectedSignature = (0, node_crypto_1.createHmac)("sha256", secret)
+        .update(`${headerB64}.${payloadB64}`)
+        .digest();
+    const actualSignature = base64UrlDecode(signatureB64);
+    if (!expectedSignature.equals(actualSignature)) {
+        throw new Error("Invalid JWT: signature mismatch — make sure the API key used by your Speech Engine server matches the one used to create the engine.");
+    }
+    if (payload.iss !== ISSUER) {
+        throw new Error(`Invalid JWT: expected issuer "${ISSUER}", got "${payload.iss}"`);
+    }
+    if (payload.sub !== SUBJECT) {
+        throw new Error(`Invalid JWT: expected subject "${SUBJECT}", got "${payload.sub}"`);
+    }
+    const now = Math.floor(Date.now() / 1000);
+    if (typeof payload.exp !== "number") {
+        throw new Error("Invalid JWT: missing exp claim");
+    }
+    if (typeof payload.iat !== "number") {
+        throw new Error("Invalid JWT: missing iat claim");
+    }
+    if (payload.exp + LEEWAY_SECONDS < now) {
+        throw new Error("Invalid JWT: token has expired");
+    }
+    if (payload.iat - LEEWAY_SECONDS > now) {
+        throw new Error("Invalid JWT: iat is in the future");
+    }
+    return payload;
+}

package/dist/wrapper/speech-engine/SpeechEngineServer.d.ts

@@ -0,0 +1,54 @@
+import WebSocket from "ws";
+import { type SpeechEngineCallbacks } from "./types";
+import { SpeechEngineSession } from "./SpeechEngineSession";
+export interface SpeechEngineServerOptions extends SpeechEngineCallbacks {
+    /**
+     * Port to listen on. Defaults to 3001.
+     */
+    port?: number;
+    /**
+     * Your ElevenLabs API key. Used to verify that incoming WebSocket
+     * connections originate from the ElevenLabs API.
+     *
+     * When omitted, the server will reject all connections and throw
+     * an error on start. Pass `{ apiKey: "..." }` or set the
+     * `ELEVENLABS_API_KEY` environment variable.
+     */
+    apiKey?: string;
+    /**
+     * The ID of the speech engine this server handles connections for.
+     * Populated automatically when created via `engine.listen()`.
+     */
+    engineId?: string;
+}
+/**
+ * Standalone WebSocket server that produces `SpeechEngineSession` instances for
+ * each incoming connection from the ElevenLabs Speech Engine API.
+ *
+ * Every incoming connection is verified against the ElevenLabs API using the
+ * configured API key before being accepted.
+ *
+ * For integration with an existing HTTP server (e.g. Express, Next.js), use
+ * `engine.attach()` instead.
+ */
+export declare class SpeechEngineServer {
+    private wss;
+    private httpServer;
+    private options;
+    constructor(options: SpeechEngineServerOptions);
+    /**
+     * Create a `SpeechEngineSession` from an existing WebSocket. Use this
+     * when you manage your own WebSocket server and want to wrap individual
+     * connections.
+     */
+    handleConnection(ws: WebSocket): SpeechEngineSession;
+    /**
+     * Start the standalone WebSocket server on the configured port.
+     */
+    start(): void;
+    private wireHandler;
+    /**
+     * Stop the WebSocket server and close all active connections.
+     */
+    stop(): Promise<void>;
+}

package/dist/wrapper/speech-engine/SpeechEngineServer.js

@@ -0,0 +1,135 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpeechEngineServer = void 0;
+const node_http_1 = require("node:http");
+const ws_1 = __importDefault(require("ws"));
+const types_1 = require("./types");
+const SpeechEngineSession_1 = require("./SpeechEngineSession");
+const SpeechEngineResource_1 = require("./SpeechEngineResource");
+/**
+ * Standalone WebSocket server that produces `SpeechEngineSession` instances for
+ * each incoming connection from the ElevenLabs Speech Engine API.
+ *
+ * Every incoming connection is verified against the ElevenLabs API using the
+ * configured API key before being accepted.
+ *
+ * For integration with an existing HTTP server (e.g. Express, Next.js), use
+ * `engine.attach()` instead.
+ */
+class SpeechEngineServer {
+    constructor(options) {
+        this.wss = null;
+        this.httpServer = null;
+        this.options = options;
+    }
+    /**
+     * Create a `SpeechEngineSession` from an existing WebSocket. Use this
+     * when you manage your own WebSocket server and want to wrap individual
+     * connections.
+     */
+    handleConnection(ws) {
+        const session = new SpeechEngineSession_1.SpeechEngineSession(ws, { debug: this.options.debug });
+        this.wireHandler(session);
+        return session;
+    }
+    /**
+     * Start the standalone WebSocket server on the configured port.
+     */
+    start() {
+        var _a, _b, _c;
+        if (this.wss) {
+            throw new Error("Server is already started");
+        }
+        const apiKey = (_a = this.options.apiKey) !== null && _a !== void 0 ? _a : process.env.ELEVENLABS_API_KEY;
+        if (!apiKey) {
+            throw new Error("SpeechEngine.Server requires an API key to verify incoming connections. " +
+                "Pass { apiKey: \"...\" } or set the ELEVENLABS_API_KEY environment variable.");
+        }
+        const debug = (_b = this.options.debug) !== null && _b !== void 0 ? _b : false;
+        const log = debug ? (...args) => console.log("[SpeechEngine]", ...args) : () => { };
+        const httpServer = (0, node_http_1.createServer)();
+        const wss = new ws_1.default.Server({ noServer: true });
+        httpServer.on("upgrade", (req, socket, head) => {
+            const headerValue = req.headers["x-elevenlabs-speech-engine-authorization"];
+            const token = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+            if (!token) {
+                log("rejected connection — missing X-Elevenlabs-Speech-Engine-Authorization header");
+                socket.destroy();
+                return;
+            }
+            try {
+                (0, SpeechEngineResource_1.verifySpeechEngineJwt)(token, apiKey);
+            }
+            catch (err) {
+                log(`rejected connection — ${err instanceof Error ? err.message : String(err)}`);
+                socket.destroy();
+                return;
+            }
+            log("verified connection, upgrading to WebSocket");
+            wss.handleUpgrade(req, socket, head, (ws) => {
+                wss.emit("connection", ws);
+            });
+        });
+        wss.on("connection", (ws) => {
+            this.handleConnection(ws);
+        });
+        httpServer.listen((_c = this.options.port) !== null && _c !== void 0 ? _c : 3001);
+        this.wss = wss;
+        this.httpServer = httpServer;
+    }
+    wireHandler(session) {
+        const { onInit, onTranscript, onClose, onDisconnect, onError } = this.options;
+        if (onInit)
+            session.on("init", (id) => onInit.call(session, id, session));
+        if (onTranscript) {
+            session.on("user_transcript", (t, s) => {
+                Promise.resolve(onTranscript.call(session, t, s, session)).catch((err) => {
+                    if ((0, types_1.isAbortError)(err))
+                        return;
+                    const error = err instanceof Error ? err : new Error(String(err));
+                    if (onError)
+                        onError.call(session, error, session);
+                });
+            });
+        }
+        if (onClose)
+            session.on("close", () => onClose.call(session, session));
+        if (onDisconnect)
+            session.on("disconnected", () => onDisconnect.call(session, session));
+        if (onError)
+            session.on("error", (err) => onError.call(session, err, session));
+    }
+    /**
+     * Stop the WebSocket server and close all active connections.
+     */
+    stop() {
+        return new Promise((resolve, reject) => {
+            if (!this.wss) {
+                resolve();
+                return;
+            }
+            this.wss.close((wssErr) => {
+                this.wss = null;
+                if (this.httpServer) {
+                    this.httpServer.close((httpErr) => {
+                        this.httpServer = null;
+                        if (wssErr || httpErr)
+                            reject(wssErr || httpErr);
+                        else
+                            resolve();
+                    });
+                }
+                else {
+                    if (wssErr)
+                        reject(wssErr);
+                    else
+                        resolve();
+                }
+            });
+        });
+    }
+}
+exports.SpeechEngineServer = SpeechEngineServer;

package/dist/wrapper/speech-engine/SpeechEngineSession.d.ts

@@ -0,0 +1,79 @@
+import { type SpeechEngineEventMap, type SpeechEngineEventName, type WebSocketLike } from "./types";
+/**
+ * Wraps a WebSocket connection from the ElevenLabs Speech Engine API into a
+ * typed, event-driven session.
+ *
+ * The ElevenLabs API connects to the developer's server via WebSocket. Each
+ * connection represents one conversation. The session emits events for
+ * transcripts and lifecycle changes, and provides methods to send LLM
+ * responses back. When a new transcript arrives, the previous transcript's
+ * abort signal is fired automatically, cancelling any in-flight LLM call.
+ *
+ * @example
+ * ```typescript
+ * import { SpeechEngine } from "@elevenlabs/elevenlabs-js";
+ *
+ * wss.on("connection", (ws) => {
+ *     const session = new SpeechEngine.Session(ws);
+ *
+ *     session.on(SpeechEngine.USER_TRANSCRIPT, async (transcript, { signal }) => {
+ *         const response = await llm.generate(transcript, { signal });
+ *         session.sendResponse(response);
+ *     });
+ * });
+ * ```
+ */
+export declare class SpeechEngineSession {
+    private ws;
+    private emitter;
+    private currentAbortController;
+    private currentEventId;
+    private inTranscriptHandler;
+    private _conversationId;
+    private closed;
+    private log;
+    constructor(ws: WebSocketLike, options?: {
+        debug?: boolean;
+    });
+    on<E extends SpeechEngineEventName>(event: E, listener: (...args: SpeechEngineEventMap[E]) => void): this;
+    off<E extends SpeechEngineEventName>(event: E, listener: (...args: SpeechEngineEventMap[E]) => void): this;
+    once<E extends SpeechEngineEventName>(event: E, listener: (...args: SpeechEngineEventMap[E]) => void): this;
+    /**
+     * Send an LLM response back to the Speech Engine API for TTS synthesis.
+     *
+     * Accepts a complete string, an `AsyncIterable<string>` for streaming
+     * token-by-token responses, or an LLM stream that yields event objects
+     * (e.g. an OpenAI Responses API stream). Event objects are automatically
+     * parsed to extract text deltas.
+     */
+    sendResponse(response: string | AsyncIterable<unknown>): Promise<void>;
+    /**
+     * Close the session and the underlying WebSocket connection.
+     */
+    close(): void;
+    /**
+     * The conversation ID assigned by the Speech Engine API, available after
+     * the `init` event.
+     */
+    get conversationId(): string | undefined;
+    /**
+     * Whether the session is still open.
+     */
+    get isOpen(): boolean;
+    private setupWebSocket;
+    private handleMessage;
+    private streamResponse;
+    /**
+     * Extract text content from a stream chunk. Handles plain strings and
+     * common LLM stream event formats:
+     *
+     * - OpenAI Responses API (`response.output_text.delta`)
+     * - OpenAI Chat Completions API (`choices[0].delta.content`)
+     * - Anthropic Messages API (`content_block_delta` with `text_delta`)
+     * - Google Gemini API (`candidates[0].content.parts[0].text`)
+     */
+    private extractText;
+    private sendAgentResponse;
+    private send;
+    private abortCurrent;
+}