@deepgram/sdk 5.0.0-beta.3 → 5.0.0

package/dist/cjs/middleware/adapters/fastify.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Fastify plugin for proxying Deepgram API requests.
+ *
+ * @packageDocumentation
+ *
+ * **Peer Dependencies Required:**
+ * ```bash
+ * npm install fastify fastify-plugin
+ * # or
+ * pnpm add fastify fastify-plugin
+ * ```
+ *
+ * This module provides a Fastify plugin for proxying requests to the Deepgram API,
+ * including REST endpoints and WebSocket connections.
+ */
+import type { FastifyPluginAsync, FastifyPluginOptions } from "fastify";
+import type { MiddlewareOptions } from "../core/types.js";
+/**
+ * Fastify plugin options
+ */
+export interface FastifyDeepgramProxyOptions extends MiddlewareOptions, FastifyPluginOptions {
+    /** URL prefix for the proxy routes (default: "") */
+    prefix?: string;
+}
+/**
+ * Export as Fastify plugin with proper typing
+ */
+export declare const fastifyDeepgramProxy: FastifyPluginAsync<FastifyDeepgramProxyOptions>;
+/**
+ * Alternative export for direct usage (without fastify-plugin wrapper)
+ */
+export declare const deepgramProxyPlugin: FastifyPluginAsync<FastifyDeepgramProxyOptions>;

package/dist/cjs/middleware/adapters/fastify.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Fastify plugin for proxying Deepgram API requests.
+ *
+ * @packageDocumentation
+ *
+ * **Peer Dependencies Required:**
+ * ```bash
+ * npm install fastify fastify-plugin
+ * # or
+ * pnpm add fastify fastify-plugin
+ * ```
+ *
+ * This module provides a Fastify plugin for proxying requests to the Deepgram API,
+ * including REST endpoints and WebSocket connections.
+ */
+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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepgramProxyPlugin = exports.fastifyDeepgramProxy = void 0;
+const ProxyHandler_js_1 = require("../core/ProxyHandler.js");
+const TokenManager_js_1 = require("../core/TokenManager.js");
+const WebSocketProxy_js_1 = require("../core/WebSocketProxy.js");
+// Lazy-load fastify-plugin
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Dynamic loading
+let fp = null;
+function loadFastifyPlugin() {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (fp) {
+            return fp;
+        }
+        try {
+            const module = yield Promise.resolve().then(() => __importStar(require("fastify-plugin")));
+            fp = module.default || module;
+            return fp;
+        }
+        catch (_a) {
+            throw new Error("fastify-plugin is required for Fastify middleware. Install it with: npm install fastify-plugin");
+        }
+    });
+}
+/**
+ * Fastify plugin for proxying Deepgram API requests
+ *
+ * @param fastify - Fastify instance
+ * @param options - Plugin configuration options
+ *
+ * @example
+ * ```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 });
+ * ```
+ */
+const fastifyDeepgramProxyPlugin = (fastify, options) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const proxyHandler = new ProxyHandler_js_1.ProxyHandler(options);
+    const tokenManager = options.enableTokenAuth
+        ? new TokenManager_js_1.TokenManager(options)
+        : null;
+    const wsProxy = new WebSocketProxy_js_1.WebSocketProxy(options);
+    // NOTE: We do NOT add a custom content type parser here because:
+    // 1. fastify-plugin breaks encapsulation, so it would affect ALL routes
+    // 2. We handle body reconstruction in our route handlers instead
+    // This allows users to use their own body parsers for their routes
+    // Register token endpoint if token auth is enabled
+    if (tokenManager) {
+        fastify.get("/token", (request, reply) => {
+            reply.hijack();
+            tokenManager.handleTokenRequest(request.raw, reply.raw).catch((error) => {
+                console.error("Token generation error:", error);
+            });
+        });
+    }
+    // Register wildcard route to catch ALL paths
+    // This must match any path depth: /, /v1, /v1/listen, /v1/listen/more/paths
+    fastify.all("/*", (request, reply) => {
+        reply.hijack();
+        // Fastify has already consumed the request body stream, so we need to
+        // write the parsed body back to the raw request
+        if (request.body && (request.method === 'POST' || request.method === 'PUT' || request.method === 'PATCH')) {
+            const bodyString = typeof request.body === 'string' ? request.body : JSON.stringify(request.body);
+            // Write the body to the raw request stream
+            process.nextTick(() => {
+                request.raw.emit('data', Buffer.from(bodyString));
+                request.raw.emit('end');
+            });
+        }
+        proxyHandler.handleRequest(request.raw, reply.raw).catch((error) => {
+            console.error("[Fastify] Proxy error:", error);
+        });
+    });
+    // Also catch root path explicitly
+    fastify.all("/", (request, reply) => {
+        reply.hijack();
+        // Reconstruct body if needed
+        if (request.body && (request.method === 'POST' || request.method === 'PUT' || request.method === 'PATCH')) {
+            const bodyString = typeof request.body === 'string' ? request.body : JSON.stringify(request.body);
+            process.nextTick(() => {
+                request.raw.emit('data', Buffer.from(bodyString));
+                request.raw.emit('end');
+            });
+        }
+        proxyHandler.handleRequest(request.raw, reply.raw).catch((error) => {
+            console.error("[Fastify] Root proxy error:", error);
+        });
+    });
+    // Register WebSocket upgrade handler
+    if (fastify.server) {
+        const prefix = (_a = options.prefix) !== null && _a !== void 0 ? _a : "";
+        fastify.server.on("upgrade", (req, socket, head) => {
+            var _a;
+            // Only handle requests matching our prefix
+            if ((_a = req.url) === null || _a === void 0 ? void 0 : _a.startsWith(prefix)) {
+                // Remove prefix from URL before proxying
+                const originalUrl = req.url;
+                req.url = originalUrl.slice(prefix.length);
+                wsProxy.handleUpgrade(req, socket, head);
+            }
+        });
+    }
+});
+/**
+ * Lazy-loaded Fastify plugin (only loads fastify-plugin when called)
+ */
+let _fastifyDeepgramProxy = null;
+/**
+ * Export as Fastify plugin with proper typing
+ */
+const fastifyDeepgramProxy = (fastify, options) => __awaiter(void 0, void 0, void 0, function* () {
+    if (!_fastifyDeepgramProxy) {
+        const pluginWrapper = yield loadFastifyPlugin();
+        _fastifyDeepgramProxy = pluginWrapper(fastifyDeepgramProxyPlugin, {
+            fastify: ">=4.0.0",
+            name: "@deepgram/sdk-middleware",
+        });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Guaranteed to be set above
+    return _fastifyDeepgramProxy(fastify, options);
+});
+exports.fastifyDeepgramProxy = fastifyDeepgramProxy;
+/**
+ * Alternative export for direct usage (without fastify-plugin wrapper)
+ */
+exports.deepgramProxyPlugin = fastifyDeepgramProxyPlugin;

package/dist/cjs/middleware/adapters/http.d.ts

@@ -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.js";
+/**
+ * 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/cjs/middleware/adapters/http.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * 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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHttpHandler = createHttpHandler;
+exports.createUpgradeHandler = createUpgradeHandler;
+exports.createDeepgramHttpServer = createDeepgramHttpServer;
+const ProxyHandler_js_1 = require("../core/ProxyHandler.js");
+const TokenManager_js_1 = require("../core/TokenManager.js");
+const WebSocketProxy_js_1 = require("../core/WebSocketProxy.js");
+/**
+ * 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);
+ * ```
+ */
+function createHttpHandler(options) {
+    const proxyHandler = new ProxyHandler_js_1.ProxyHandler(options);
+    const tokenManager = options.enableTokenAuth ? new TokenManager_js_1.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);
+ * ```
+ */
+function createUpgradeHandler(options) {
+    const wsProxy = new WebSocketProxy_js_1.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');
+ * });
+ * ```
+ */
+function createDeepgramHttpServer(options) {
+    const handler = createHttpHandler(options);
+    const upgradeHandler = createUpgradeHandler(options);
+    return {
+        handler,
+        upgradeHandler,
+        server: (httpServer) => {
+            httpServer.on("upgrade", upgradeHandler);
+        },
+    };
+}

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

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