@deepgram/sdk 5.0.0 → 5.1.0

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

@@ -1,136 +0,0 @@
-/**
- * Express middleware for proxying Deepgram API requests.
- *
- * @packageDocumentation
- *
- * **Peer Dependencies Required:**
- * ```bash
- * npm install express
- * # or
- * pnpm add express
- * ```
- *
- * This module provides Express-compatible middleware for proxying requests to the
- * Deepgram API, including REST endpoints and WebSocket connections.
- */
-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 Express middleware for proxying Deepgram API requests
- *
- * @param options - Middleware configuration options
- * @returns Express middleware function
- *
- * @example
- * ```typescript
- * import express from 'express';
- * import { createDeepgramProxy, createWebSocketHandler } from '@deepgram/sdk';
- *
- * const app = express();
- * const proxyOptions = {
- *   apiKey: process.env.DEEPGRAM_API_KEY!,
- *   enableTokenAuth: true
- * };
- *
- * // REST API proxy
- * app.use('/api/deepgram', createDeepgramProxy(proxyOptions));
- *
- * // WebSocket upgrade handler
- * const server = app.listen(3000);
- * server.on('upgrade', createWebSocketHandler(proxyOptions));
- * ```
- */
-export function createDeepgramProxy(options) {
-    const proxyHandler = new ProxyHandler(options);
-    const tokenManager = options.enableTokenAuth
-        ? new TokenManager(options)
-        : null;
-    return (req, res, next) => __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) {
-            next(error instanceof Error ? error : new Error(String(error)));
-        }
-    });
-}
-/**
- * Create WebSocket upgrade handler for Express
- *
- * This must be registered on the HTTP server, not the Express app.
- *
- * @param options - Middleware configuration options
- * @returns Upgrade handler function
- *
- * @example
- * ```typescript
- * import express from 'express';
- * import { createWebSocketHandler } from '@deepgram/sdk';
- *
- * const app = express();
- * const server = app.listen(3000);
- *
- * // Register WebSocket handler on the server
- * server.on('upgrade', createWebSocketHandler({
- *   apiKey: process.env.DEEPGRAM_API_KEY!
- * }));
- * ```
- */
-export function createWebSocketHandler(options) {
-    const wsProxy = new WebSocketProxy(options);
-    return (req, socket, head) => {
-        wsProxy.handleUpgrade(req, socket, head);
-    };
-}
-/**
- * Combined helper that returns both middleware and upgrade handler
- *
- * @param options - Middleware configuration options
- * @returns Object with middleware and upgrade handler
- *
- * @example
- * ```typescript
- * import express from 'express';
- * import { createDeepgramMiddleware } from '@deepgram/sdk';
- *
- * const app = express();
- * const { middleware, upgradeHandler } = createDeepgramMiddleware({
- *   apiKey: process.env.DEEPGRAM_API_KEY!,
- *   enableTokenAuth: true
- * });
- *
- * app.use('/api/deepgram', middleware);
- *
- * const server = app.listen(3000);
- * server.on('upgrade', upgradeHandler);
- * ```
- */
-export function createDeepgramMiddleware(options) {
-    const middleware = createDeepgramProxy(options);
-    const upgradeHandler = createWebSocketHandler(options);
-    return {
-        middleware,
-        upgradeHandler,
-        server: (httpServer) => {
-            httpServer.on("upgrade", upgradeHandler);
-        },
-    };
-}

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

@@ -1,32 +0,0 @@
-/**
- * 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.mjs";
-/**
- * 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/esm/middleware/adapters/fastify.mjs

@@ -1,157 +0,0 @@
-/**
- * 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 __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";
-// 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 import("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(options);
-    const tokenManager = options.enableTokenAuth
-        ? new TokenManager(options)
-        : null;
-    const wsProxy = new 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
- */
-export 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);
-});
-/**
- * Alternative export for direct usage (without fastify-plugin wrapper)
- */
-export const deepgramProxyPlugin = fastifyDeepgramProxyPlugin;

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

@@ -1,153 +0,0 @@
-/**
- * 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

@@ -1,187 +0,0 @@
-/**
- * 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

@@ -1,35 +0,0 @@
-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;
-}