@deepgram/sdk 4.6.0 → 4.8.0

package/dist/umd/deepgram.js.LICENSE.txt

@@ -0,0 +1,10 @@
+/*!
+ * The buffer module from node.js, for the browser.
+ *
+ * @author   Feross Aboukhadijeh <https://feross.org>
+ * @license  MIT
+ */
+
+/*! ieee754. BSD-3-Clause License. Feross Aboukhadijeh <https://feross.org/opensource> */
+
+/*! safe-buffer. MIT License. Feross Aboukhadijeh <https://feross.org/opensource> */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepgram/sdk",
-  "version": "4.6.0",
+  "version": "4.8.0",
   "description": "Isomorphic Javascript client for Deepgram",
   "keywords": [
     "javascript",
@@ -10,6 +10,7 @@
     "speech",
     "sdk"
   ],
+  "packageManager": "pnpm@10.12.1",
   "homepage": "https://github.com/deepgram/deepgram-js-sdk",
   "bugs": "https://github.com/deepgram/deepgram-js-sdk/issues",
   "license": "MIT",
@@ -39,21 +40,26 @@
   "repository": "deepgram/deepgram-js-sdk",
   "scripts": {
     "clean": "rimraf dist docs/v2",
-    "format": "prettier --write \"{src,test}/**/*.ts\"",
+    "format": "prettier --write \"src/**/*.ts\"",
     "build": "run-s clean format build:*",
     "build:main": "tsc -p tsconfig.json",
     "build:module": "tsc -p tsconfig.module.json",
     "build:umd": "webpack --mode=production",
     "lint": "run-s lint:*",
-    "lint:js": "eslint --no-eslintrc  -c .eslintrc-examples.js examples --max-warnings 0",
+    "lint:js": "eslint -c .eslintrc-examples.js examples --max-warnings 0",
     "lint:md": "markdownlint **/*.md *.md",
     "lint:yml": "yamllint .github/workflows",
     "lint:ts": "eslint src --max-warnings 0",
     "watch": "nodemon -e ts --watch src --exec \"npm run build\"",
-    "test": "mocha -r ts-node/register test/*test.ts test/**/*test.ts --inspect --exit",
-    "test:coverage": "nyc --reporter=lcovonly --reporter=text --reporter=text-summary npm run test",
     "docs": "typedoc --entryPoints src/index.ts --out docs/ --includes src/packages/**/*.ts   --emit none",
-    "docs:json": "typedoc --entryPoints src/index.ts --includes src/packages/**/*.ts --json docs/spec.json   --emit none"
+    "docs:json": "typedoc --entryPoints src/index.ts --includes src/packages/**/*.ts --json docs/spec.json   --emit none",
+    "test": "jest",
+    "test:unit": "jest --testPathPattern=tests/unit",
+    "test:e2e": "jest --testPathPattern=tests/e2e",
+    "test:e2e:offline": "node scripts/test-offline.js",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:ci": "jest --ci --coverage --watchAll=false"
   },
   "dependencies": {
     "@deepgram/captions": "^1.1.1",
@@ -66,33 +72,33 @@
   "devDependencies": {
     "@commitlint/cli": "^17.6.7",
     "@commitlint/config-conventional": "^17.6.7",
-    "@faker-js/faker": "^8.0.2",
-    "@flydotio/dockerfile": "^0.4.10",
-    "@types/chai": "^4.3.5",
-    "@types/mocha": "^9.1.1",
-    "@types/sinon": "^17.0.3",
+    "@types/jest": "^29.5.12",
     "@types/ws": "^8.5.10",
     "@typescript-eslint/eslint-plugin": "^8.7.0",
     "@typescript-eslint/parser": "^8.7.0",
-    "chai": "^4.3.7",
+    "buffer": "^6.0.3",
     "cross-env": "^7.0.3",
+    "dotenv": "^16.5.0",
     "eslint": "^8.57.1",
     "husky": "^4.3.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
     "markdownlint": "^0.35.0",
     "markdownlint-cli": "^0.42.0",
-    "mocha": "^9.2.2",
     "nodemon": "^3.0.1",
     "npm-run-all": "^4.1.5",
-    "nyc": "^15.1.0",
     "prettier": "^2.5.1",
     "pretty-quick": "^3.1.3",
     "rimraf": "^3.0.2",
     "semantic-release-plugin-update-version-in-files": "^1.1.0",
-    "sinon": "^17.0.1",
+    "stream-browserify": "^3.0.0",
+    "ts-jest": "^29.1.2",
     "ts-loader": "^8.0.11",
     "ts-node": "^10.9.1",
     "typedoc": "^0.22.16",
     "typescript": "^4.5.5",
+    "url": "^0.11.4",
+    "util": "^0.12.5",
     "webpack": "^5.69.1",
     "webpack-cli": "^4.9.2",
     "yaml-lint": "^1.7.0"

package/src/lib/errors.ts

@@ -48,3 +48,55 @@ export class DeepgramVersionError extends DeepgramError {
     this.name = "DeepgramVersionError";
   }
 }
+
+/**
+ * Enhanced WebSocket error that captures additional debugging information
+ * including status codes, request IDs, and response headers when available.
+ */
+export class DeepgramWebSocketError extends DeepgramError {
+  originalEvent?: ErrorEvent | Event;
+  statusCode?: number;
+  requestId?: string;
+  responseHeaders?: Record<string, string>;
+  url?: string;
+  readyState?: number;
+
+  constructor(
+    message: string,
+    options: {
+      originalEvent?: ErrorEvent | Event;
+      statusCode?: number;
+      requestId?: string;
+      responseHeaders?: Record<string, string>;
+      url?: string;
+      readyState?: number;
+    } = {}
+  ) {
+    super(message);
+    this.name = "DeepgramWebSocketError";
+    this.originalEvent = options.originalEvent;
+    this.statusCode = options.statusCode;
+    this.requestId = options.requestId;
+    this.responseHeaders = options.responseHeaders;
+    this.url = options.url;
+    this.readyState = options.readyState;
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      statusCode: this.statusCode,
+      requestId: this.requestId,
+      responseHeaders: this.responseHeaders,
+      url: this.url,
+      readyState: this.readyState,
+      originalEvent: this.originalEvent
+        ? {
+            type: this.originalEvent.type,
+            timeStamp: this.originalEvent.timeStamp,
+          }
+        : undefined,
+    };
+  }
+}

package/src/lib/helpers.ts

@@ -47,7 +47,7 @@ export const resolveHeadersConstructor = () => {
 export const isUrlSource = (
   providedSource: PrerecordedSource | AnalyzeSource
 ): providedSource is UrlSource => {
-  if ((providedSource as UrlSource).url) return true;
+  if (providedSource && (providedSource as UrlSource).url) return true;
 
   return false;
 };
@@ -55,7 +55,7 @@ export const isUrlSource = (
 export const isTextSource = (
   providedSource: PrerecordedSource | AnalyzeSource
 ): providedSource is TextSource => {
-  if ((providedSource as TextSource).text) return true;
+  if (providedSource && (providedSource as TextSource).text) return true;
 
   return false;
 };
@@ -67,15 +67,11 @@ export const isFileSource = (providedSource: PrerecordedSource): providedSource
 };
 
 const isBufferSource = (providedSource: PrerecordedSource): providedSource is Buffer => {
-  if (providedSource as Buffer) return true;
-
-  return false;
+  return providedSource != null && Buffer.isBuffer(providedSource);
 };
 
 const isReadStreamSource = (providedSource: PrerecordedSource): providedSource is Readable => {
-  if (providedSource as Readable) return true;
-
-  return false;
+  return providedSource != null && providedSource instanceof Readable;
 };
 
 export class CallbackUrl extends URL {
@@ -100,11 +96,11 @@ export const buildRequestUrl = (
 };
 
 export function isLiveSchema(arg: any): arg is LiveSchema {
-  return arg && typeof arg.interim_results !== "undefined";
+  return arg != null && typeof arg.interim_results !== "undefined";
 }
 
 export function isDeepgramClientOptions(arg: any): arg is DeepgramClientOptions {
-  return arg && typeof arg.global !== "undefined";
+  return arg != null && typeof arg.global !== "undefined";
 }
 
 export const convertLegacyOptions = (optionsArg: DeepgramClientOptions): DeepgramClientOptions => {

package/src/lib/version.ts

@@ -1 +1 @@
-export const version = "4.6.0";
+export const version = "4.8.0";

package/src/packages/AbstractLiveClient.ts

@@ -3,6 +3,7 @@ import { CONNECTION_STATE, SOCKET_STATES } from "../lib/constants";
 import type { DeepgramClientOptions, LiveSchema } from "../lib/types";
 import type { WebSocket as WSWebSocket } from "ws";
 import { isBun } from "../lib/runtime";
+import { DeepgramWebSocketError } from "../lib/errors";
 
 /**
  * Represents a constructor for a WebSocket-like object that can be used in the application.
@@ -285,6 +286,235 @@ export abstract class AbstractLiveClient extends AbstractClient {
     return this.key === "proxy" && !!this.namespaceOptions.websocket.options.proxy?.url;
   }
 
+  /**
+   * Extracts enhanced error information from a WebSocket error event.
+   * This method attempts to capture additional debugging information such as
+   * status codes, request IDs, and response headers when available.
+   *
+   * @example
+   * ```typescript
+   * // Enhanced error information is now available in error events:
+   * connection.on(LiveTranscriptionEvents.Error, (err) => {
+   *   console.error("WebSocket Error:", err.message);
+   *
+   *   // Access HTTP status code (e.g., 502, 403, etc.)
+   *   if (err.statusCode) {
+   *     console.error(`HTTP Status Code: ${err.statusCode}`);
+   *   }
+   *
+   *   // Access Deepgram request ID for support tickets
+   *   if (err.requestId) {
+   *     console.error(`Deepgram Request ID: ${err.requestId}`);
+   *   }
+   *
+   *   // Access WebSocket URL and connection state
+   *   if (err.url) {
+   *     console.error(`WebSocket URL: ${err.url}`);
+   *   }
+   *
+   *   if (err.readyState !== undefined) {
+   *     const stateNames = ['CONNECTING', 'OPEN', 'CLOSING', 'CLOSED'];
+   *     console.error(`Connection State: ${stateNames[err.readyState]}`);
+   *   }
+   *
+   *   // Access response headers for additional debugging
+   *   if (err.responseHeaders) {
+   *     console.error("Response Headers:", err.responseHeaders);
+   *   }
+   *
+   *   // Access the enhanced error object for detailed debugging
+   *   if (err.error?.name === 'DeepgramWebSocketError') {
+   *     console.error("Enhanced Error Details:", err.error.toJSON());
+   *   }
+   * });
+   * ```
+   *
+   * @param event - The error event from the WebSocket
+   * @param conn - The WebSocket connection object
+   * @returns Enhanced error information object
+   */
+  protected extractErrorInformation(
+    event: ErrorEvent | Event,
+    conn?: WebSocketLike
+  ): {
+    statusCode?: number;
+    requestId?: string;
+    responseHeaders?: Record<string, string>;
+    url?: string;
+    readyState?: number;
+  } {
+    const errorInfo: {
+      statusCode?: number;
+      requestId?: string;
+      responseHeaders?: Record<string, string>;
+      url?: string;
+      readyState?: number;
+    } = {};
+
+    // Extract basic connection information
+    if (conn) {
+      errorInfo.readyState = conn.readyState;
+      errorInfo.url = typeof conn.url === "string" ? conn.url : conn.url?.toString();
+    }
+
+    // Try to extract additional information from the WebSocket connection
+    // This works with the 'ws' package which exposes more detailed error information
+    if (conn && typeof conn === "object") {
+      const wsConn = conn as any;
+
+      // Extract status code if available (from 'ws' package)
+      if (wsConn._req && wsConn._req.res) {
+        errorInfo.statusCode = wsConn._req.res.statusCode;
+
+        // Extract response headers if available
+        if (wsConn._req.res.headers) {
+          errorInfo.responseHeaders = { ...wsConn._req.res.headers };
+
+          // Extract request ID from Deepgram response headers
+          const requestId =
+            wsConn._req.res.headers["dg-request-id"] || wsConn._req.res.headers["x-dg-request-id"];
+          if (requestId) {
+            errorInfo.requestId = requestId;
+          }
+        }
+      }
+
+      // For native WebSocket, try to extract information from the event
+      if (event && "target" in event && event.target) {
+        const target = event.target as any;
+        if (target.url) {
+          errorInfo.url = target.url;
+        }
+        if (target.readyState !== undefined) {
+          errorInfo.readyState = target.readyState;
+        }
+      }
+    }
+
+    return errorInfo;
+  }
+
+  /**
+   * Creates an enhanced error object with additional debugging information.
+   * This method provides backward compatibility by including both the original
+   * error event and enhanced error information.
+   *
+   * @param event - The original error event
+   * @param enhancedInfo - Additional error information extracted from the connection
+   * @returns An object containing both original and enhanced error information
+   */
+  protected createEnhancedError(
+    event: ErrorEvent | Event,
+    enhancedInfo: {
+      statusCode?: number;
+      requestId?: string;
+      responseHeaders?: Record<string, string>;
+      url?: string;
+      readyState?: number;
+    }
+  ) {
+    // Create the enhanced error for detailed debugging
+    const enhancedError = new DeepgramWebSocketError(
+      (event as ErrorEvent).message || "WebSocket connection error",
+      {
+        originalEvent: event,
+        ...enhancedInfo,
+      }
+    );
+
+    // Return an object that maintains backward compatibility
+    // while providing enhanced information
+    return {
+      // Original event for backward compatibility
+      ...event,
+      // Enhanced error information
+      error: enhancedError,
+      // Additional fields for easier access
+      statusCode: enhancedInfo.statusCode,
+      requestId: enhancedInfo.requestId,
+      responseHeaders: enhancedInfo.responseHeaders,
+      url: enhancedInfo.url,
+      readyState: enhancedInfo.readyState,
+      // Enhanced message with more context
+      message: this.buildEnhancedErrorMessage(event, enhancedInfo),
+    };
+  }
+
+  /**
+   * Builds an enhanced error message with additional context information.
+   *
+   * @param event - The original error event
+   * @param enhancedInfo - Additional error information
+   * @returns A more descriptive error message
+   */
+  protected buildEnhancedErrorMessage(
+    event: ErrorEvent | Event,
+    enhancedInfo: {
+      statusCode?: number;
+      requestId?: string;
+      responseHeaders?: Record<string, string>;
+      url?: string;
+      readyState?: number;
+    }
+  ): string {
+    let message = (event as ErrorEvent).message || "WebSocket connection error";
+
+    const details: string[] = [];
+
+    if (enhancedInfo.statusCode) {
+      details.push(`Status: ${enhancedInfo.statusCode}`);
+    }
+
+    if (enhancedInfo.requestId) {
+      details.push(`Request ID: ${enhancedInfo.requestId}`);
+    }
+
+    if (enhancedInfo.readyState !== undefined) {
+      const stateNames = ["CONNECTING", "OPEN", "CLOSING", "CLOSED"];
+      const stateName =
+        stateNames[enhancedInfo.readyState] || `Unknown(${enhancedInfo.readyState})`;
+      details.push(`Ready State: ${stateName}`);
+    }
+
+    if (enhancedInfo.url) {
+      details.push(`URL: ${enhancedInfo.url}`);
+    }
+
+    if (details.length > 0) {
+      message += ` (${details.join(", ")})`;
+    }
+
+    return message;
+  }
+
+  /**
+   * Sets up the standard connection event handlers (open, close, error) for WebSocket connections.
+   * This method abstracts the common connection event registration pattern used across all live clients.
+   *
+   * @param events - Object containing the event constants for the specific client type
+   * @param events.Open - Event constant for connection open
+   * @param events.Close - Event constant for connection close
+   * @param events.Error - Event constant for connection error
+   * @protected
+   */
+  protected setupConnectionEvents(events: { Open: string; Close: string; Error: string }): void {
+    if (this.conn) {
+      this.conn.onopen = () => {
+        this.emit(events.Open, this);
+      };
+
+      this.conn.onclose = (event: any) => {
+        this.emit(events.Close, event);
+      };
+
+      this.conn.onerror = (event: ErrorEvent) => {
+        const enhancedInfo = this.extractErrorInformation(event, this.conn || undefined);
+        const enhancedError = this.createEnhancedError(event, enhancedInfo);
+        this.emit(events.Error, enhancedError);
+      };
+    }
+  }
+
   /**
    * Sets up the connection event handlers.
    *

package/src/packages/AgentLiveClient.ts

@@ -22,19 +22,15 @@ export class AgentLiveClient extends AbstractLiveClient {
    * - When a message is received, it parses the message and emits the appropriate event based on the message type.
    */
   public setupConnection(): void {
-    if (this.conn) {
-      this.conn.onopen = () => {
-        this.emit(AgentEvents.Open, this);
-      };
-
-      this.conn.onclose = (event: any) => {
-        this.emit(AgentEvents.Close, event);
-      };
-
-      this.conn.onerror = (event: ErrorEvent) => {
-        this.emit(AgentEvents.Error, event);
-      };
+    // Set up standard connection events (open, close, error) using abstracted method
+    this.setupConnectionEvents({
+      Open: AgentEvents.Open,
+      Close: AgentEvents.Close,
+      Error: AgentEvents.Error,
+    });
 
+    // Set up message handling specific to agent conversations
+    if (this.conn) {
       this.conn.onmessage = (event: MessageEvent) => {
         this.handleMessage(event);
       };
@@ -53,9 +49,13 @@ export class AgentLiveClient extends AbstractLiveClient {
       } catch (error) {
         this.emit(AgentEvents.Error, {
           event,
-          data: event.data,
+          data:
+            event.data?.toString().substring(0, 200) +
+            (event.data?.toString().length > 200 ? "..." : ""),
           message: "Unable to parse `data` as JSON.",
           error,
+          url: this.conn?.url,
+          readyState: this.conn?.readyState,
         });
       }
     } else if (event.data instanceof Blob) {
@@ -71,6 +71,9 @@ export class AgentLiveClient extends AbstractLiveClient {
       this.emit(AgentEvents.Error, {
         event,
         message: "Received unknown data type.",
+        url: this.conn?.url,
+        readyState: this.conn?.readyState,
+        dataType: typeof event.data,
       });
     }
   }
@@ -137,6 +140,17 @@ export class AgentLiveClient extends AbstractLiveClient {
     this.send(JSON.stringify({ type: "InjectAgentMessage", content }));
   }
 
+  /**
+   * Send a text-based message to the agent as if it came from the user.
+   * This allows you to inject user messages into the conversation for the agent to respond to.
+   * @example "Hello! Can you hear me?"
+   * @example "What's the weather like today?"
+   * @param content - The specific phrase or statement the agent should respond to.
+   */
+  public injectUserMessage(content: string): void {
+    this.send(JSON.stringify({ type: "InjectUserMessage", content }));
+  }
+
   /**
    * Respond to a function call request.
    * @param response  - The response to the function call request.

package/src/packages/ListenLiveClient.ts

@@ -51,19 +51,15 @@ export class ListenLiveClient extends AbstractLiveClient {
    * - When a message is received, it parses the message and emits the appropriate event based on the message type, such as `LiveTranscriptionEvents.Metadata`, `LiveTranscriptionEvents.Transcript`, `LiveTranscriptionEvents.UtteranceEnd`, and `LiveTranscriptionEvents.SpeechStarted`.
    */
   public setupConnection(): void {
-    if (this.conn) {
-      this.conn.onopen = () => {
-        this.emit(LiveTranscriptionEvents.Open, this);
-      };
-
-      this.conn.onclose = (event: any) => {
-        this.emit(LiveTranscriptionEvents.Close, event);
-      };
-
-      this.conn.onerror = (event: ErrorEvent) => {
-        this.emit(LiveTranscriptionEvents.Error, event);
-      };
+    // Set up standard connection events (open, close, error) using abstracted method
+    this.setupConnectionEvents({
+      Open: LiveTranscriptionEvents.Open,
+      Close: LiveTranscriptionEvents.Close,
+      Error: LiveTranscriptionEvents.Error,
+    });
 
+    // Set up message handling specific to transcription
+    if (this.conn) {
       this.conn.onmessage = (event: MessageEvent) => {
         try {
           const data: any = JSON.parse(event.data.toString());
@@ -84,6 +80,11 @@ export class ListenLiveClient extends AbstractLiveClient {
             event,
             message: "Unable to parse `data` as JSON.",
             error,
+            url: this.conn?.url,
+            readyState: this.conn?.readyState,
+            data:
+              event.data?.toString().substring(0, 200) +
+              (event.data?.toString().length > 200 ? "..." : ""),
           });
         }
       };

package/src/packages/ManageRestClient.ts

@@ -515,7 +515,7 @@ export class ManageRestClient extends AbstractRestClient {
   ): Promise<VoidResponse> {
     try {
       const requestUrl = this.getRequestUrl(endpoint, { projectId, email });
-      await this.delete(requestUrl).then((result) => result.json());
+      await this.delete(requestUrl);
 
       return { error: null };
     } catch (error) {

package/src/packages/SpeakLiveClient.ts

@@ -42,19 +42,15 @@ export class SpeakLiveClient extends AbstractLiveClient {
    * - When a message is received, it parses the message and emits the appropriate event based on the message type, such as `LiveTTSEvents.Metadata`, `LiveTTSEvents.Flushed`, and `LiveTTSEvents.Warning`.
    */
   public setupConnection(): void {
-    if (this.conn) {
-      this.conn.onopen = () => {
-        this.emit(LiveTTSEvents.Open, this);
-      };
-
-      this.conn.onclose = (event: any) => {
-        this.emit(LiveTTSEvents.Close, event);
-      };
-
-      this.conn.onerror = (event: ErrorEvent) => {
-        this.emit(LiveTTSEvents.Error, event);
-      };
+    // Set up standard connection events (open, close, error) using abstracted method
+    this.setupConnectionEvents({
+      Open: LiveTTSEvents.Open,
+      Close: LiveTTSEvents.Close,
+      Error: LiveTTSEvents.Error,
+    });
 
+    // Set up message handling specific to text-to-speech
+    if (this.conn) {
       this.conn.onmessage = (event: MessageEvent) => {
         this.handleMessage(event);
       };
@@ -146,6 +142,11 @@ export class SpeakLiveClient extends AbstractLiveClient {
           event,
           message: "Unable to parse `data` as JSON.",
           error,
+          url: this.conn?.url,
+          readyState: this.conn?.readyState,
+          data:
+            event.data?.toString().substring(0, 200) +
+            (event.data?.toString().length > 200 ? "..." : ""),
         });
       }
     } else if (event.data instanceof Blob) {
@@ -161,6 +162,9 @@ export class SpeakLiveClient extends AbstractLiveClient {
       this.emit(LiveTTSEvents.Error, {
         event,
         message: "Received unknown data type.",
+        url: this.conn?.url,
+        readyState: this.conn?.readyState,
+        dataType: typeof event.data,
       });
     }
   }