@deepgram/sdk 5.0.0-beta.3 → 5.0.0

package/dist/cjs/middleware/core/ProxyHandler.js

@@ -0,0 +1,225 @@
+"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());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxyHandler = void 0;
+const node_https_1 = __importDefault(require("node:https"));
+const node_url_1 = require("node:url");
+const jwt_js_1 = require("./jwt.js");
+/**
+ * Handles HTTP/REST request proxying to Deepgram API
+ */
+class ProxyHandler {
+    constructor(options) {
+        var _a, _b;
+        this.apiKey = options.apiKey;
+        this.baseUrl = (_a = options.baseUrl) !== null && _a !== void 0 ? _a : "https://api.deepgram.com";
+        this.tokenMode = (_b = options.tokenMode) !== null && _b !== void 0 ? _b : "deepgram";
+    }
+    /**
+     * Handle incoming HTTP request and proxy to Deepgram
+     */
+    handleRequest(req, res) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                // Handle CORS preflight
+                if (req.method === "OPTIONS") {
+                    this.handleCorsPreflightRequest(req, res);
+                    return;
+                }
+                // Forward request to Deepgram
+                yield this.forwardToDeepgram(req, res);
+            }
+            catch (error) {
+                this.handleError(error, res);
+            }
+        });
+    }
+    /**
+     * Forward request to Deepgram API
+     */
+    forwardToDeepgram(req, res) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            console.log(`[ProxyHandler] Starting forward to Deepgram`);
+            console.log(`[ProxyHandler] Original URL: ${req.url}`);
+            // Strip /api/deepgram prefix if present
+            const cleanUrl = ((_a = req.url) !== null && _a !== void 0 ? _a : "/").replace(/^\/api\/deepgram/, "");
+            console.log(`[ProxyHandler] Clean URL: ${cleanUrl}`);
+            // Build Deepgram URL
+            const targetUrl = new node_url_1.URL(cleanUrl, this.baseUrl);
+            console.log(`[ProxyHandler] Target URL: ${targetUrl.toString()}`);
+            // Prepare headers (may verify JWT)
+            const headers = yield this.prepareHeaders(req);
+            console.log(`[ProxyHandler] Request headers prepared`);
+            // Create request to Deepgram
+            const options = {
+                method: req.method,
+                headers,
+            };
+            console.log(`[ProxyHandler] Creating ${req.method} request to Deepgram...`);
+            console.log(`[ProxyHandler] Headers being SENT to Deepgram:`, JSON.stringify(headers, null, 2));
+            const deepgramReq = node_https_1.default.request(targetUrl, options, (deepgramRes) => {
+                var _a;
+                console.log(`[ProxyHandler] Received response from Deepgram: ${deepgramRes.statusCode}`);
+                console.log(`[ProxyHandler] Response headers from Deepgram:`, JSON.stringify(deepgramRes.headers, null, 2));
+                // Don't set headers if they were already sent
+                if (res.headersSent) {
+                    console.log(`[ProxyHandler] Headers already sent, skipping`);
+                    return;
+                }
+                // Build response headers with CORS
+                const responseHeaders = Object.assign(Object.assign({}, deepgramRes.headers), { "access-control-allow-origin": "*", "access-control-allow-methods": "GET, POST, PUT, DELETE, OPTIONS", "access-control-allow-headers": "Authorization, Content-Type, x-fern-language, x-fern-sdk-name, x-fern-sdk-version, x-deepgram-session-id", "access-control-max-age": "3600" });
+                // Forward status and headers
+                console.log(`[ProxyHandler] Writing response headers`);
+                res.writeHead((_a = deepgramRes.statusCode) !== null && _a !== void 0 ? _a : 200, responseHeaders);
+                // Stream response body
+                console.log(`[ProxyHandler] Piping response body to client`);
+                deepgramRes.pipe(res);
+                deepgramRes.on('end', () => {
+                    console.log(`[ProxyHandler] Response stream ended`);
+                });
+            });
+            // Handle request errors
+            deepgramReq.on("error", (error) => {
+                console.error(`[ProxyHandler] Request error:`, error);
+                this.handleError(error, res);
+            });
+            // Check if request stream is readable
+            console.log(`[ProxyHandler] Request stream readable: ${req.readable}`);
+            console.log(`[ProxyHandler] Request stream readableEnded: ${req.readableEnded}`);
+            console.log(`[ProxyHandler] Request method: ${req.method}`);
+            // For POST/PUT requests, manually read and forward the body
+            if (req.method === 'POST' || req.method === 'PUT' || req.method === 'PATCH') {
+                console.log(`[ProxyHandler] Reading request body for ${req.method} request...`);
+                const chunks = [];
+                req.on('data', (chunk) => {
+                    console.log(`[ProxyHandler] Received request chunk: ${chunk.length} bytes`);
+                    chunks.push(chunk);
+                });
+                req.on('end', () => {
+                    const body = Buffer.concat(chunks);
+                    console.log(`[ProxyHandler] Request body complete: ${body.length} bytes total`);
+                    console.log(`[ProxyHandler] Request body content: ${body.toString()}`);
+                    deepgramReq.write(body);
+                    deepgramReq.end();
+                    console.log(`[ProxyHandler] Request sent to Deepgram`);
+                });
+                req.on('error', (err) => {
+                    console.error(`[ProxyHandler] Request stream error:`, err);
+                });
+            }
+            else {
+                // For GET requests, just end immediately
+                console.log(`[ProxyHandler] No body expected for ${req.method} request`);
+                deepgramReq.end();
+            }
+        });
+    }
+    /**
+     * Prepare headers for Deepgram request
+     */
+    prepareHeaders(req) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const headers = {};
+            // Copy relevant headers
+            const allowedHeaders = [
+                "content-type",
+                "content-length",
+                "accept",
+                "user-agent",
+                "x-fern-language",
+                "x-fern-sdk-name",
+                "x-fern-sdk-version",
+                "x-fern-runtime",
+                "x-fern-runtime-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:
+            // 1. If client sends dummy key "Token Dummy key for SDK proxying" -> use server API key
+            // 2. If tokenMode is "jwt" and client sends Bearer token -> verify JWT and use server API key
+            // 3. If tokenMode is "deepgram" and client sends Token -> forward it (Deepgram temp token)
+            // 4. If client sends no auth header -> use server API key
+            const clientAuth = req.headers.authorization;
+            const isDummyKey = clientAuth === "Token Dummy key for SDK proxying";
+            if (clientAuth && !isDummyKey) {
+                // Check if it's a JWT Bearer token
+                if (this.tokenMode === "jwt" && clientAuth.startsWith("Bearer ")) {
+                    const token = clientAuth.replace("Bearer ", "");
+                    console.log(`[ProxyHandler] Client provided JWT token, verifying...`);
+                    try {
+                        yield (0, jwt_js_1.verifyProxyToken)(token, this.apiKey);
+                        console.log(`[ProxyHandler] JWT verified successfully, using server API key`);
+                        headers.authorization = `Token ${this.apiKey}`;
+                    }
+                    catch (error) {
+                        console.error(`[ProxyHandler] JWT verification failed:`, error);
+                        throw new Error("Invalid or expired token");
+                    }
+                }
+                else {
+                    console.log(`[ProxyHandler] Client provided authorization header, forwarding to Deepgram`);
+                    headers.authorization = clientAuth;
+                    console.log(`[ProxyHandler] Authorization header: ${headers.authorization.substring(0, 30)}...`);
+                }
+            }
+            else {
+                if (isDummyKey) {
+                    console.log(`[ProxyHandler] Client sent dummy key, using server API key`);
+                }
+                else {
+                    console.log(`[ProxyHandler] No client auth, using server API key`);
+                }
+                headers.authorization = `Token ${this.apiKey}`;
+                console.log(`[ProxyHandler] Authorization header: ${headers.authorization.substring(0, 30)}...`);
+            }
+            return headers;
+        });
+    }
+    /**
+     * Add CORS headers to response
+     */
+    addCorsHeaders(res) {
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type, x-fern-language, x-fern-sdk-name, x-fern-sdk-version, x-fern-runtime, x-fern-runtime-version, x-deepgram-session-id");
+        res.setHeader("Access-Control-Max-Age", "3600");
+    }
+    /**
+     * Handle CORS preflight requests
+     */
+    handleCorsPreflightRequest(req, res) {
+        this.addCorsHeaders(res);
+        res.writeHead(204);
+        res.end();
+    }
+    /**
+     * Handle errors and send appropriate response
+     */
+    handleError(error, res) {
+        console.error("ProxyHandler error:", error);
+        const message = error instanceof Error ? error.message : "Internal server error";
+        this.addCorsHeaders(res);
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+            error: message,
+        }));
+    }
+}
+exports.ProxyHandler = ProxyHandler;

package/dist/cjs/middleware/core/TokenManager.d.ts

@@ -0,0 +1,29 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { MiddlewareOptions } from "./types.js";
+/**
+ * Manages temporary token generation for client authentication
+ */
+export declare class TokenManager {
+    private readonly client;
+    private readonly apiKey;
+    private readonly tokenMode;
+    private readonly defaultExpiration;
+    constructor(options: MiddlewareOptions);
+    /**
+     * Generate a temporary access token
+     * Uses either Deepgram's native token API or JWT signing based on tokenMode
+     */
+    generateToken(ttlSeconds: number): Promise<string>;
+    /**
+     * Handle token generation request from client
+     */
+    handleTokenRequest(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /**
+     * Parse JSON request body
+     */
+    private parseBody;
+    /**
+     * Handle errors and send appropriate response
+     */
+    private handleError;
+}

package/dist/cjs/middleware/core/TokenManager.js

@@ -0,0 +1,110 @@
+"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 });
+exports.TokenManager = void 0;
+const CustomClient_js_1 = require("../../CustomClient.js");
+const jwt_js_1 = require("./jwt.js");
+/**
+ * Manages temporary token generation for client authentication
+ */
+class TokenManager {
+    constructor(options) {
+        var _a, _b;
+        this.client = new CustomClient_js_1.CustomDeepgramClient({ 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 (0, jwt_js_1.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,
+        }));
+    }
+}
+exports.TokenManager = TokenManager;

package/dist/cjs/middleware/core/WebSocketProxy.d.ts

@@ -0,0 +1,32 @@
+import type { IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+import type { MiddlewareOptions } from "./types.js";
+/**
+ * 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/cjs/middleware/core/WebSocketProxy.js

@@ -0,0 +1,169 @@
+"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());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketProxy = void 0;
+const node_url_1 = require("node:url");
+const ws_1 = __importDefault(require("ws"));
+const jwt_js_1 = require("./jwt.js");
+/**
+ * Handles WebSocket proxying to Deepgram API
+ */
+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 ws_1.default(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 ws_1.default(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 node_url_1.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 (0, jwt_js_1.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 === ws_1.default.OPEN) {
+                deepgramSocket.send(data, { binary: isBinary });
+            }
+        });
+        // Forward Deepgram messages to client
+        deepgramSocket.on("message", (data, isBinary) => {
+            if (clientSocket.readyState === ws_1.default.OPEN) {
+                clientSocket.send(data, { binary: isBinary });
+            }
+        });
+        // Handle closures
+        clientSocket.on("close", (code, reason) => {
+            if (deepgramSocket.readyState === ws_1.default.OPEN) {
+                deepgramSocket.close(code, reason);
+            }
+        });
+        deepgramSocket.on("close", (code, reason) => {
+            if (clientSocket.readyState === ws_1.default.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();
+        });
+    }
+}
+exports.WebSocketProxy = WebSocketProxy;

package/dist/cjs/middleware/core/jwt.d.ts

@@ -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>;