feat(errors): enhance WebSocket error output and abstract connection setup

lukeocodes · lukeocodes · commit 36778e9614b0 · 2025-06-25T09:34:38.000+01:00
- Add DeepgramWebSocketError class with detailed debugging info including
  HTTP status codes, Deepgram request IDs, response headers, and connection state
- Abstract common connection event setup pattern into reusable
  setupConnectionEvents() method in AbstractLiveClient
- Update all live clients (Listen, Agent, Speak) to use abstracted pattern
- Eliminate ~45 lines of duplicated connection event handling code
- Maintain full backward compatibility with existing error event handlers

Addresses customer feedback about difficulty debugging "non-101 status code"
errors by exposing the actual HTTP status and request ID that were previously
hidden behind generic Node.js WebSocket error messages.
diff --git a/src/lib/errors.ts b/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,
+    };
+  }
+}
diff --git a/src/packages/AbstractLiveClient.ts b/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.
    *
diff --git a/src/packages/AgentLiveClient.ts b/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,
       });
     }
   }
diff --git a/src/packages/ListenLiveClient.ts b/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 ? "..." : ""),
           });
         }
       };
diff --git a/src/packages/SpeakLiveClient.ts b/src/packages/SpeakLiveClient.ts
