@deepgram/sdk 5.0.0-beta.3 → 5.0.0

package/dist/esm/middleware/adapters/http.d.mts

@@ -0,0 +1,153 @@
+/**
+ * Raw Node.js HTTP/HTTPS server adapter for proxying Deepgram API requests.
+ *
+ * @packageDocumentation
+ *
+ * **No Dependencies Required** - Uses only built-in Node.js modules
+ *
+ * This module provides a request handler for raw Node.js `http` and `https` servers,
+ * allowing proxy integration without any framework dependencies.
+ */
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
+import type { Duplex } from "node:stream";
+import type { MiddlewareOptions } from "../core/types.mjs";
+/**
+ * Request handler type for Node.js HTTP server
+ */
+export type HttpRequestHandler = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+/**
+ * WebSocket upgrade handler type
+ */
+export type UpgradeHandler = (req: IncomingMessage, socket: Duplex, head: Buffer) => void;
+/**
+ * Create a request handler for raw Node.js HTTP/HTTPS servers
+ *
+ * This handler can be used directly with `http.createServer()` or `https.createServer()`.
+ *
+ * @param options - Middleware configuration options
+ * @returns HTTP request handler function
+ *
+ * @example Basic HTTP server
+ * ```typescript
+ * import http from 'node:http';
+ * import { createHttpHandler, createUpgradeHandler } from '@deepgram/sdk';
+ *
+ * const options = {
+ *   apiKey: process.env.DEEPGRAM_API_KEY!,
+ *   enableTokenAuth: true
+ * };
+ *
+ * // Create request handler
+ * const handler = createHttpHandler(options);
+ *
+ * // Create server
+ * const server = http.createServer(handler);
+ *
+ * // Register WebSocket upgrade handler
+ * server.on('upgrade', createUpgradeHandler(options));
+ *
+ * server.listen(3000);
+ * ```
+ *
+ * @example HTTPS server
+ * ```typescript
+ * import https from 'node:https';
+ * import fs from 'node:fs';
+ * import { createHttpHandler, createUpgradeHandler } from '@deepgram/sdk';
+ *
+ * const options = {
+ *   apiKey: process.env.DEEPGRAM_API_KEY!
+ * };
+ *
+ * const server = https.createServer({
+ *   key: fs.readFileSync('server.key'),
+ *   cert: fs.readFileSync('server.cert')
+ * }, createHttpHandler(options));
+ *
+ * server.on('upgrade', createUpgradeHandler(options));
+ * server.listen(443);
+ * ```
+ *
+ * @example With routing
+ * ```typescript
+ * import http from 'node:http';
+ * import { createHttpHandler } from '@deepgram/sdk';
+ *
+ * const deepgramHandler = createHttpHandler({
+ *   apiKey: process.env.DEEPGRAM_API_KEY!
+ * });
+ *
+ * const server = http.createServer((req, res) => {
+ *   // Route /api/deepgram/* to Deepgram proxy
+ *   if (req.url?.startsWith('/api/deepgram')) {
+ *     // Strip prefix before proxying
+ *     req.url = req.url.slice('/api/deepgram'.length);
+ *     return deepgramHandler(req, res);
+ *   }
+ *
+ *   // Handle other routes
+ *   res.writeHead(404);
+ *   res.end('Not Found');
+ * });
+ *
+ * server.listen(3000);
+ * ```
+ */
+export declare function createHttpHandler(options: MiddlewareOptions): HttpRequestHandler;
+/**
+ * Create WebSocket upgrade handler for raw Node.js HTTP/HTTPS servers
+ *
+ * This must be registered on the server using `server.on('upgrade', handler)`.
+ *
+ * @param options - Middleware configuration options
+ * @returns Upgrade handler function
+ *
+ * @example
+ * ```typescript
+ * import http from 'node:http';
+ * import { createHttpHandler, createUpgradeHandler } from '@deepgram/sdk';
+ *
+ * const options = {
+ *   apiKey: process.env.DEEPGRAM_API_KEY!
+ * };
+ *
+ * const server = http.createServer(createHttpHandler(options));
+ *
+ * // Register WebSocket handler
+ * server.on('upgrade', createUpgradeHandler(options));
+ *
+ * server.listen(3000);
+ * ```
+ */
+export declare function createUpgradeHandler(options: MiddlewareOptions): UpgradeHandler;
+/**
+ * Combined helper that returns both HTTP handler and upgrade handler
+ *
+ * Convenience function for setting up both REST and WebSocket proxying.
+ *
+ * @param options - Middleware configuration options
+ * @returns Object with HTTP handler and upgrade handler
+ *
+ * @example
+ * ```typescript
+ * import http from 'node:http';
+ * import { createDeepgramHttpServer } from '@deepgram/sdk';
+ *
+ * const { handler, upgradeHandler } = createDeepgramHttpServer({
+ *   apiKey: process.env.DEEPGRAM_API_KEY!,
+ *   enableTokenAuth: true
+ * });
+ *
+ * const server = http.createServer(handler);
+ * server.on('upgrade', upgradeHandler);
+ *
+ * server.listen(3000, () => {
+ *   console.log('Deepgram proxy running on port 3000');
+ * });
+ * ```
+ */
+export declare function createDeepgramHttpServer(options: MiddlewareOptions): {
+    handler: HttpRequestHandler;
+    upgradeHandler: UpgradeHandler;
+    server: (httpServer: Server) => void;
+};

package/dist/esm/middleware/adapters/http.mjs

@@ -0,0 +1,187 @@
+/**
+ * Raw Node.js HTTP/HTTPS server adapter for proxying Deepgram API requests.
+ *
+ * @packageDocumentation
+ *
+ * **No Dependencies Required** - Uses only built-in Node.js modules
+ *
+ * This module provides a request handler for raw Node.js `http` and `https` servers,
+ * allowing proxy integration without any framework dependencies.
+ */
+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 { ProxyHandler } from "../core/ProxyHandler.mjs";
+import { TokenManager } from "../core/TokenManager.mjs";
+import { WebSocketProxy } from "../core/WebSocketProxy.mjs";
+/**
+ * Create a request handler for raw Node.js HTTP/HTTPS servers
+ *
+ * This handler can be used directly with `http.createServer()` or `https.createServer()`.
+ *
+ * @param options - Middleware configuration options
+ * @returns HTTP request handler function
+ *
+ * @example Basic HTTP server
+ * ```typescript
+ * import http from 'node:http';
+ * import { createHttpHandler, createUpgradeHandler } from '@deepgram/sdk';
+ *
+ * const options = {
+ *   apiKey: process.env.DEEPGRAM_API_KEY!,
+ *   enableTokenAuth: true
+ * };
+ *
+ * // Create request handler
+ * const handler = createHttpHandler(options);
+ *
+ * // Create server
+ * const server = http.createServer(handler);
+ *
+ * // Register WebSocket upgrade handler
+ * server.on('upgrade', createUpgradeHandler(options));
+ *
+ * server.listen(3000);
+ * ```
+ *
+ * @example HTTPS server
+ * ```typescript
+ * import https from 'node:https';
+ * import fs from 'node:fs';
+ * import { createHttpHandler, createUpgradeHandler } from '@deepgram/sdk';
+ *
+ * const options = {
+ *   apiKey: process.env.DEEPGRAM_API_KEY!
+ * };
+ *
+ * const server = https.createServer({
+ *   key: fs.readFileSync('server.key'),
+ *   cert: fs.readFileSync('server.cert')
+ * }, createHttpHandler(options));
+ *
+ * server.on('upgrade', createUpgradeHandler(options));
+ * server.listen(443);
+ * ```
+ *
+ * @example With routing
+ * ```typescript
+ * import http from 'node:http';
+ * import { createHttpHandler } from '@deepgram/sdk';
+ *
+ * const deepgramHandler = createHttpHandler({
+ *   apiKey: process.env.DEEPGRAM_API_KEY!
+ * });
+ *
+ * const server = http.createServer((req, res) => {
+ *   // Route /api/deepgram/* to Deepgram proxy
+ *   if (req.url?.startsWith('/api/deepgram')) {
+ *     // Strip prefix before proxying
+ *     req.url = req.url.slice('/api/deepgram'.length);
+ *     return deepgramHandler(req, res);
+ *   }
+ *
+ *   // Handle other routes
+ *   res.writeHead(404);
+ *   res.end('Not Found');
+ * });
+ *
+ * server.listen(3000);
+ * ```
+ */
+export function createHttpHandler(options) {
+    const proxyHandler = new ProxyHandler(options);
+    const tokenManager = options.enableTokenAuth ? new TokenManager(options) : null;
+    return (req, res) => __awaiter(this, void 0, void 0, function* () {
+        try {
+            // Handle token generation requests
+            if (options.enableTokenAuth && req.url === "/token" && req.method === "GET") {
+                yield tokenManager.handleTokenRequest(req, res);
+                return;
+            }
+            // Handle all other requests (proxy to Deepgram)
+            yield proxyHandler.handleRequest(req, res);
+        }
+        catch (error) {
+            // Set error response
+            res.statusCode = 500;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    });
+}
+/**
+ * Create WebSocket upgrade handler for raw Node.js HTTP/HTTPS servers
+ *
+ * This must be registered on the server using `server.on('upgrade', handler)`.
+ *
+ * @param options - Middleware configuration options
+ * @returns Upgrade handler function
+ *
+ * @example
+ * ```typescript
+ * import http from 'node:http';
+ * import { createHttpHandler, createUpgradeHandler } from '@deepgram/sdk';
+ *
+ * const options = {
+ *   apiKey: process.env.DEEPGRAM_API_KEY!
+ * };
+ *
+ * const server = http.createServer(createHttpHandler(options));
+ *
+ * // Register WebSocket handler
+ * server.on('upgrade', createUpgradeHandler(options));
+ *
+ * server.listen(3000);
+ * ```
+ */
+export function createUpgradeHandler(options) {
+    const wsProxy = new WebSocketProxy(options);
+    return (req, socket, head) => {
+        wsProxy.handleUpgrade(req, socket, head);
+    };
+}
+/**
+ * Combined helper that returns both HTTP handler and upgrade handler
+ *
+ * Convenience function for setting up both REST and WebSocket proxying.
+ *
+ * @param options - Middleware configuration options
+ * @returns Object with HTTP handler and upgrade handler
+ *
+ * @example
+ * ```typescript
+ * import http from 'node:http';
+ * import { createDeepgramHttpServer } from '@deepgram/sdk';
+ *
+ * const { handler, upgradeHandler } = createDeepgramHttpServer({
+ *   apiKey: process.env.DEEPGRAM_API_KEY!,
+ *   enableTokenAuth: true
+ * });
+ *
+ * const server = http.createServer(handler);
+ * server.on('upgrade', upgradeHandler);
+ *
+ * server.listen(3000, () => {
+ *   console.log('Deepgram proxy running on port 3000');
+ * });
+ * ```
+ */
+export function createDeepgramHttpServer(options) {
+    const handler = createHttpHandler(options);
+    const upgradeHandler = createUpgradeHandler(options);
+    return {
+        handler,
+        upgradeHandler,
+        server: (httpServer) => {
+            httpServer.on("upgrade", upgradeHandler);
+        },
+    };
+}

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

@@ -0,0 +1,35 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { MiddlewareOptions } from "./types.mjs";
+/**
+ * Handles HTTP/REST request proxying to Deepgram API
+ */
+export declare class ProxyHandler {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly tokenMode;
+    constructor(options: MiddlewareOptions);
+    /**
+     * Handle incoming HTTP request and proxy to Deepgram
+     */
+    handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /**
+     * Forward request to Deepgram API
+     */
+    private forwardToDeepgram;
+    /**
+     * Prepare headers for Deepgram request
+     */
+    private prepareHeaders;
+    /**
+     * Add CORS headers to response
+     */
+    private addCorsHeaders;
+    /**
+     * Handle CORS preflight requests
+     */
+    private handleCorsPreflightRequest;
+    /**
+     * Handle errors and send appropriate response
+     */
+    private handleError;
+}

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

@@ -0,0 +1,218 @@
+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 https from "node:https";
+import { URL } from "node:url";
+import { verifyProxyToken } from "./jwt.mjs";
+/**
+ * Handles HTTP/REST request proxying to Deepgram API
+ */
+export 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 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 = https.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 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,
+        }));
+    }
+}

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

@@ -0,0 +1,29 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { MiddlewareOptions } from "./types.mjs";
+/**
+ * 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;
+}