@deepgram/sdk 5.0.0-beta.3 → 5.0.0

package/dist/esm/middleware/core/TokenManager.mjs

@@ -0,0 +1,106 @@
+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());
+    });
+};
+import { CustomDeepgramClient as DeepgramClient } from "../../CustomClient.mjs";
+import { createProxyToken } from "./jwt.mjs";
+/**
+ * Manages temporary token generation for client authentication
+ */
+export class TokenManager {
+    constructor(options) {
+        var _a, _b;
+        this.client = new DeepgramClient({ apiKey: options.apiKey });
+        this.apiKey = options.apiKey;
+        this.tokenMode = (_a = options.tokenMode) !== null && _a !== void 0 ? _a : "deepgram";
+        this.defaultExpiration = (_b = options.defaultTokenExpiration) !== null && _b !== void 0 ? _b : 3600;
+    }
+    /**
+     * Generate a temporary access token
+     * Uses either Deepgram's native token API or JWT signing based on tokenMode
+     */
+    generateToken(ttlSeconds) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.tokenMode === "jwt") {
+                return createProxyToken(this.apiKey, { ttl: ttlSeconds });
+            }
+            const response = yield this.client.auth.v1.tokens.grant({
+                ttl_seconds: ttlSeconds,
+            });
+            return response.access_token;
+        });
+    }
+    /**
+     * Handle token generation request from client
+     */
+    handleTokenRequest(req, res) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                // Parse request body
+                const body = yield this.parseBody(req);
+                const tokenRequest = body;
+                // Generate token with requested or default TTL
+                const ttlSeconds = (_a = tokenRequest.ttlSeconds) !== null && _a !== void 0 ? _a : this.defaultExpiration;
+                const token = yield this.generateToken(ttlSeconds);
+                // Send response
+                const response = {
+                    token,
+                    expiresIn: ttlSeconds,
+                };
+                res.writeHead(200, {
+                    "Content-Type": "application/json",
+                    "Access-Control-Allow-Origin": "*",
+                    "Access-Control-Allow-Methods": "POST, OPTIONS",
+                    "Access-Control-Allow-Headers": "Content-Type",
+                });
+                res.end(JSON.stringify(response));
+            }
+            catch (error) {
+                this.handleError(error, res);
+            }
+        });
+    }
+    /**
+     * Parse JSON request body
+     */
+    parseBody(req) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => {
+                let body = "";
+                req.on("data", (chunk) => {
+                    body += chunk.toString();
+                });
+                req.on("end", () => {
+                    try {
+                        resolve(body ? JSON.parse(body) : {});
+                    }
+                    catch (error) {
+                        reject(new Error("Invalid JSON in request body"));
+                    }
+                });
+                req.on("error", reject);
+            });
+        });
+    }
+    /**
+     * Handle errors and send appropriate response
+     */
+    handleError(error, res) {
+        console.error("TokenManager error:", error);
+        const message = error instanceof Error ? error.message : "Internal server error";
+        const statusCode = message.includes("Invalid JSON") ? 400 : 500;
+        res.writeHead(statusCode, {
+            "Content-Type": "application/json",
+            "Access-Control-Allow-Origin": "*",
+        });
+        res.end(JSON.stringify({
+            error: message,
+        }));
+    }
+}

package/dist/esm/middleware/core/WebSocketProxy.d.mts

@@ -0,0 +1,32 @@
+import type { IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+import type { MiddlewareOptions } from "./types.mjs";
+/**
+ * Handles WebSocket proxying to Deepgram API
+ */
+export declare class WebSocketProxy {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly tokenMode;
+    constructor(options: MiddlewareOptions);
+    /**
+     * Handle WebSocket upgrade request
+     */
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void;
+    /**
+     * Async version of handleUpgrade to support JWT verification
+     */
+    private handleUpgradeAsync;
+    /**
+     * Build WebSocket URL for Deepgram
+     */
+    private buildWebSocketUrl;
+    /**
+     * Prepare headers for Deepgram WebSocket connection
+     */
+    private prepareHeaders;
+    /**
+     * Forward WebSocket messages bidirectionally
+     */
+    private forwardMessages;
+}

package/dist/esm/middleware/core/WebSocketProxy.mjs

@@ -0,0 +1,162 @@
+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());
+    });
+};
+import { URL } from "node:url";
+import WebSocket from "ws";
+import { verifyProxyToken } from "./jwt.mjs";
+/**
+ * Handles WebSocket proxying to Deepgram API
+ */
+export class WebSocketProxy {
+    constructor(options) {
+        var _a, _b;
+        this.apiKey = options.apiKey;
+        this.tokenMode = (_a = options.tokenMode) !== null && _a !== void 0 ? _a : "deepgram";
+        // Convert HTTP(S) base URL to WebSocket URL
+        this.baseUrl = ((_b = options.baseUrl) !== null && _b !== void 0 ? _b : "https://api.deepgram.com")
+            .replace(/^https:/, "wss:")
+            .replace(/^http:/, "ws:");
+    }
+    /**
+     * Handle WebSocket upgrade request
+     */
+    handleUpgrade(req, socket, head) {
+        this.handleUpgradeAsync(req, socket, head).catch((error) => {
+            console.error("WebSocket upgrade error:", error);
+            socket.destroy();
+        });
+    }
+    /**
+     * Async version of handleUpgrade to support JWT verification
+     */
+    handleUpgradeAsync(req, socket, head) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                // Build Deepgram WebSocket URL
+                const targetUrl = this.buildWebSocketUrl(req);
+                // Prepare headers (may verify JWT)
+                const headers = yield this.prepareHeaders(req);
+                // Connect to Deepgram WebSocket
+                const deepgramSocket = new WebSocket(targetUrl, { headers });
+                // Handle connection open
+                deepgramSocket.on("open", () => {
+                    // Complete the client upgrade
+                    socket.write("HTTP/1.1 101 Switching Protocols\r\n" +
+                        "Upgrade: websocket\r\n" +
+                        "Connection: Upgrade\r\n" +
+                        "\r\n");
+                    // Create client WebSocket
+                    const clientSocket = new WebSocket(null, null);
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- WebSocket internals
+                    clientSocket.setSocket(socket, head, { maxPayload: 100 * 1024 * 1024 });
+                    // Forward messages bidirectionally
+                    this.forwardMessages(clientSocket, deepgramSocket);
+                });
+                // Handle connection errors
+                deepgramSocket.on("error", (error) => {
+                    console.error("WebSocket proxy error (Deepgram):", error);
+                    socket.destroy();
+                });
+            }
+            catch (error) {
+                console.error("WebSocket upgrade error:", error);
+                throw error;
+            }
+        });
+    }
+    /**
+     * Build WebSocket URL for Deepgram
+     */
+    buildWebSocketUrl(req) {
+        var _a;
+        // Strip /api/deepgram prefix if present
+        const cleanUrl = ((_a = req.url) !== null && _a !== void 0 ? _a : "/").replace(/^\/api\/deepgram/, "");
+        const url = new URL(cleanUrl, this.baseUrl);
+        return url.toString();
+    }
+    /**
+     * Prepare headers for Deepgram WebSocket connection
+     */
+    prepareHeaders(req) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const headers = {};
+            // Copy relevant headers
+            const allowedHeaders = [
+                "user-agent",
+                "x-fern-language",
+                "x-fern-sdk-name",
+                "x-fern-sdk-version",
+                "x-deepgram-session-id",
+            ];
+            for (const header of allowedHeaders) {
+                const value = req.headers[header];
+                if (value) {
+                    headers[header] = Array.isArray(value) ? value[0] : value;
+                }
+            }
+            // Authentication logic (similar to ProxyHandler)
+            const clientAuth = req.headers.authorization;
+            if (clientAuth && this.tokenMode === "jwt" && clientAuth.startsWith("Bearer ")) {
+                const token = clientAuth.replace("Bearer ", "");
+                console.log(`[WebSocketProxy] Client provided JWT token, verifying...`);
+                try {
+                    yield verifyProxyToken(token, this.apiKey);
+                    console.log(`[WebSocketProxy] JWT verified successfully, using server API key`);
+                    headers.authorization = `Token ${this.apiKey}`;
+                }
+                catch (error) {
+                    console.error(`[WebSocketProxy] JWT verification failed:`, error);
+                    throw new Error("Invalid or expired token");
+                }
+            }
+            else {
+                // Use server API key
+                headers.authorization = `Token ${this.apiKey}`;
+            }
+            return headers;
+        });
+    }
+    /**
+     * Forward WebSocket messages bidirectionally
+     */
+    forwardMessages(clientSocket, deepgramSocket) {
+        // Forward client messages to Deepgram
+        clientSocket.on("message", (data, isBinary) => {
+            if (deepgramSocket.readyState === WebSocket.OPEN) {
+                deepgramSocket.send(data, { binary: isBinary });
+            }
+        });
+        // Forward Deepgram messages to client
+        deepgramSocket.on("message", (data, isBinary) => {
+            if (clientSocket.readyState === WebSocket.OPEN) {
+                clientSocket.send(data, { binary: isBinary });
+            }
+        });
+        // Handle closures
+        clientSocket.on("close", (code, reason) => {
+            if (deepgramSocket.readyState === WebSocket.OPEN) {
+                deepgramSocket.close(code, reason);
+            }
+        });
+        deepgramSocket.on("close", (code, reason) => {
+            if (clientSocket.readyState === WebSocket.OPEN) {
+                clientSocket.close(code, reason);
+            }
+        });
+        // Handle errors
+        clientSocket.on("error", (error) => {
+            console.error("WebSocket error (client):", error);
+            deepgramSocket.close();
+        });
+        deepgramSocket.on("error", (error) => {
+            console.error("WebSocket error (Deepgram):", error);
+            clientSocket.close();
+        });
+    }
+}

package/dist/esm/middleware/core/jwt.d.mts

@@ -0,0 +1,71 @@
+/**
+ * Options for creating a proxy token
+ */
+export interface ProxyTokenOptions {
+    /** Optional user or session identifier */
+    identity?: string;
+    /** Token time-to-live (e.g., "1h", "30m", 3600). Defaults to "1h" */
+    ttl?: string | number;
+    /** Optional scopes/permissions for the token */
+    scopes?: string[];
+    /** Optional custom metadata to include in token */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Decoded proxy token payload
+ */
+export interface ProxyTokenPayload {
+    /** Issuer - the project ID extracted from API key */
+    iss: string;
+    /** Subject - optional user/session identifier */
+    sub?: string;
+    /** Issued at timestamp */
+    iat: number;
+    /** Expiration timestamp */
+    exp: number;
+    /** Not before timestamp */
+    nbf: number;
+    /** Optional scopes/permissions */
+    scopes?: string[];
+    /** Optional custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Creates a proxy token signed with the Deepgram API key.
+ * This token should be generated on the backend and sent to browser clients.
+ * The browser uses this token to connect to the proxy middleware.
+ *
+ * @param apiKey - Deepgram API key (used as signing secret)
+ * @param options - Token configuration options
+ * @returns JWT token string
+ *
+ * @example
+ * ```typescript
+ * const token = await createProxyToken(process.env.DEEPGRAM_API_KEY, {
+ *   identity: 'user-123',
+ *   ttl: '1h',
+ *   scopes: ['listen', 'speak']
+ * });
+ * ```
+ */
+export declare function createProxyToken(apiKey: string, options?: ProxyTokenOptions): Promise<string>;
+/**
+ * Verifies a proxy token and returns the decoded payload.
+ * This should be called by the proxy middleware to validate tokens from clients.
+ *
+ * @param token - JWT token to verify
+ * @param apiKey - Deepgram API key (used to verify signature)
+ * @returns Decoded token payload
+ * @throws Error if token is invalid, expired, or signature doesn't match
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const payload = await verifyProxyToken(token, process.env.DEEPGRAM_API_KEY);
+ *   console.log('Valid token for user:', payload.sub);
+ * } catch (error) {
+ *   console.error('Invalid token:', error);
+ * }
+ * ```
+ */
+export declare function verifyProxyToken(token: string, apiKey: string): Promise<ProxyTokenPayload>;

package/dist/esm/middleware/core/jwt.mjs

@@ -0,0 +1,99 @@
+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());
+    });
+};
+import * as jose from "jose";
+/**
+ * Creates a proxy token signed with the Deepgram API key.
+ * This token should be generated on the backend and sent to browser clients.
+ * The browser uses this token to connect to the proxy middleware.
+ *
+ * @param apiKey - Deepgram API key (used as signing secret)
+ * @param options - Token configuration options
+ * @returns JWT token string
+ *
+ * @example
+ * ```typescript
+ * const token = await createProxyToken(process.env.DEEPGRAM_API_KEY, {
+ *   identity: 'user-123',
+ *   ttl: '1h',
+ *   scopes: ['listen', 'speak']
+ * });
+ * ```
+ */
+export function createProxyToken(apiKey_1) {
+    return __awaiter(this, arguments, void 0, function* (apiKey, options = {}) {
+        const { identity, ttl = "1h", scopes, metadata } = options;
+        const projectId = extractProjectId(apiKey);
+        const secret = new TextEncoder().encode(apiKey);
+        const payload = {};
+        if (scopes !== undefined) {
+            payload.scopes = scopes;
+        }
+        if (metadata !== undefined) {
+            payload.metadata = metadata;
+        }
+        const expirationTime = typeof ttl === "number"
+            ? Math.floor(Date.now() / 1000) + ttl
+            : ttl;
+        const jwt = new jose.SignJWT(payload)
+            .setProtectedHeader({ alg: "HS256" })
+            .setIssuer(projectId)
+            .setIssuedAt()
+            .setNotBefore(new Date())
+            .setExpirationTime(expirationTime);
+        if (identity !== undefined) {
+            jwt.setSubject(identity);
+        }
+        return jwt.sign(secret);
+    });
+}
+/**
+ * Verifies a proxy token and returns the decoded payload.
+ * This should be called by the proxy middleware to validate tokens from clients.
+ *
+ * @param token - JWT token to verify
+ * @param apiKey - Deepgram API key (used to verify signature)
+ * @returns Decoded token payload
+ * @throws Error if token is invalid, expired, or signature doesn't match
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const payload = await verifyProxyToken(token, process.env.DEEPGRAM_API_KEY);
+ *   console.log('Valid token for user:', payload.sub);
+ * } catch (error) {
+ *   console.error('Invalid token:', error);
+ * }
+ * ```
+ */
+export function verifyProxyToken(token, apiKey) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const secret = new TextEncoder().encode(apiKey);
+        const projectId = extractProjectId(apiKey);
+        const { payload } = yield jose.jwtVerify(token, secret, {
+            algorithms: ["HS256"],
+            issuer: projectId,
+        });
+        return payload;
+    });
+}
+/**
+ * Extracts the project ID from a Deepgram API key.
+ * API keys are formatted as: {project_id}:{secret}
+ *
+ * @param apiKey - Deepgram API key
+ * @returns Project ID portion of the API key
+ */
+function extractProjectId(apiKey) {
+    const parts = apiKey.split(":");
+    if (parts.length < 2) {
+        throw new Error("Invalid API key format");
+    }
+    return parts[0];
+}

package/dist/esm/middleware/core/types.d.mts

@@ -0,0 +1,37 @@
+/**
+ * Options for configuring the Deepgram proxy middleware
+ */
+export interface MiddlewareOptions {
+    /** Deepgram API key for server-side authentication */
+    apiKey: string;
+    /** Enable temporary token generation endpoint (GET /token) */
+    enableTokenAuth?: boolean;
+    /**
+     * Token mode: how tokens are generated and verified
+     * - "deepgram": Use Deepgram's native temporary token API (legacy)
+     * - "jwt": Use JWT tokens signed with API key (recommended for browser clients)
+     *
+     * @default "deepgram"
+     */
+    tokenMode?: "deepgram" | "jwt";
+    /** Custom Deepgram API base URL (e.g., for EU endpoint) */
+    baseUrl?: string;
+    /** Default token expiration in seconds (default: 3600 = 1 hour) */
+    defaultTokenExpiration?: number;
+}
+/**
+ * Request body for token generation
+ */
+export interface TokenRequest {
+    /** Token time-to-live in seconds */
+    ttlSeconds?: number;
+}
+/**
+ * Response from token generation
+ */
+export interface TokenResponse {
+    /** The generated access token */
+    token: string;
+    /** Token expiration time in seconds */
+    expiresIn: number;
+}

package/dist/esm/middleware/core/types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/esm/middleware/index.d.mts

@@ -0,0 +1,55 @@
+/**
+ * Deepgram SDK Middleware
+ *
+ * This module provides middleware for integrating Deepgram API proxying
+ * into Node.js web frameworks like Express and Fastify.
+ *
+ * ## Features
+ * - Server-side API key injection (hide keys from clients)
+ * - Temporary token generation (client requests token, uses it temporarily)
+ * - WebSocket proxying for Live/Agent APIs
+ * - Framework integration (Raw Node.js, Express, Fastify)
+ *
+ * @example Express
+ * ```typescript
+ * import express from 'express';
+ * import { createDeepgramProxy, createWebSocketHandler } from '@deepgram/sdk';
+ *
+ * const app = express();
+ * const options = {
+ *   apiKey: process.env.DEEPGRAM_API_KEY!,
+ *   enableTokenAuth: true
+ * };
+ *
+ * app.use('/api/deepgram', createDeepgramProxy(options));
+ *
+ * const server = app.listen(3000);
+ * server.on('upgrade', createWebSocketHandler(options));
+ * ```
+ *
+ * @example Fastify
+ * ```typescript
+ * import Fastify from 'fastify';
+ * import { fastifyDeepgramProxy } from '@deepgram/sdk';
+ *
+ * const fastify = Fastify();
+ *
+ * fastify.register(fastifyDeepgramProxy, {
+ *   prefix: '/api/deepgram',
+ *   apiKey: process.env.DEEPGRAM_API_KEY!,
+ *   enableTokenAuth: true
+ * });
+ *
+ * fastify.listen({ port: 3000 });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { MiddlewareOptions, TokenRequest, TokenResponse } from "./core/types.mjs";
+export { createHttpHandler, createUpgradeHandler as createHttpUpgradeHandler, createDeepgramHttpServer, type HttpRequestHandler, type UpgradeHandler as HttpUpgradeHandler, } from "./adapters/http.mjs";
+export { createDeepgramProxy, createDeepgramMiddleware, createWebSocketHandler, type ExpressMiddleware, type UpgradeHandler, } from "./adapters/express.mjs";
+export { fastifyDeepgramProxy, deepgramProxyPlugin, type FastifyDeepgramProxyOptions, } from "./adapters/fastify.mjs";
+export { createProxyToken, verifyProxyToken, type ProxyTokenOptions, type ProxyTokenPayload, } from "./core/jwt.mjs";
+export { ProxyHandler } from "./core/ProxyHandler.mjs";
+export { TokenManager } from "./core/TokenManager.mjs";
+export { WebSocketProxy } from "./core/WebSocketProxy.mjs";

package/dist/esm/middleware/index.mjs

@@ -0,0 +1,59 @@
+/**
+ * Deepgram SDK Middleware
+ *
+ * This module provides middleware for integrating Deepgram API proxying
+ * into Node.js web frameworks like Express and Fastify.
+ *
+ * ## Features
+ * - Server-side API key injection (hide keys from clients)
+ * - Temporary token generation (client requests token, uses it temporarily)
+ * - WebSocket proxying for Live/Agent APIs
+ * - Framework integration (Raw Node.js, Express, Fastify)
+ *
+ * @example Express
+ * ```typescript
+ * import express from 'express';
+ * import { createDeepgramProxy, createWebSocketHandler } from '@deepgram/sdk';
+ *
+ * const app = express();
+ * const options = {
+ *   apiKey: process.env.DEEPGRAM_API_KEY!,
+ *   enableTokenAuth: true
+ * };
+ *
+ * app.use('/api/deepgram', createDeepgramProxy(options));
+ *
+ * const server = app.listen(3000);
+ * server.on('upgrade', createWebSocketHandler(options));
+ * ```
+ *
+ * @example Fastify
+ * ```typescript
+ * import Fastify from 'fastify';
+ * import { fastifyDeepgramProxy } from '@deepgram/sdk';
+ *
+ * const fastify = Fastify();
+ *
+ * fastify.register(fastifyDeepgramProxy, {
+ *   prefix: '/api/deepgram',
+ *   apiKey: process.env.DEEPGRAM_API_KEY!,
+ *   enableTokenAuth: true
+ * });
+ *
+ * fastify.listen({ port: 3000 });
+ * ```
+ *
+ * @packageDocumentation
+ */
+// Raw Node.js HTTP/HTTPS adapter (no dependencies)
+export { createHttpHandler, createUpgradeHandler as createHttpUpgradeHandler, createDeepgramHttpServer, } from "./adapters/http.mjs";
+// Express adapter
+export { createDeepgramProxy, createDeepgramMiddleware, createWebSocketHandler, } from "./adapters/express.mjs";
+// Fastify adapter
+export { fastifyDeepgramProxy, deepgramProxyPlugin, } from "./adapters/fastify.mjs";
+// JWT token management
+export { createProxyToken, verifyProxyToken, } from "./core/jwt.mjs";
+// Core classes (for advanced usage)
+export { ProxyHandler } from "./core/ProxyHandler.mjs";
+export { TokenManager } from "./core/TokenManager.mjs";
+export { WebSocketProxy } from "./core/WebSocketProxy.mjs";

package/dist/esm/version.d.mts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.0.283";
+export declare const SDK_VERSION = "4.11.4";

package/dist/esm/version.mjs

@@ -1 +1 @@
-export const SDK_VERSION = "0.0.283";
+export const SDK_VERSION = "4.11.4";