@deepgram/sdk 3.3.4 → 3.4.0

package/src/packages/AbstractClient.ts

@@ -1,89 +1,157 @@
+import EventEmitter from "events";
 import { DEFAULT_OPTIONS, DEFAULT_URL } from "../lib/constants";
 import { DeepgramError } from "../lib/errors";
-import { applySettingDefaults, stripTrailingSlash } from "../lib/helpers";
-import { DeepgramClientOptions } from "../lib/types";
+import { appendSearchParams, applyDefaults, convertLegacyOptions } from "../lib/helpers";
+import type {
+  DeepgramClientOptions,
+  DefaultClientOptions,
+  DefaultNamespaceOptions,
+  NamespaceOptions,
+} from "../lib/types";
+
+export const noop = () => {};
 
 /**
- * Deepgram Client.
+ * Represents an abstract Deepgram client that provides a base implementation for interacting with the Deepgram API.
+ *
+ * The `AbstractClient` class is responsible for:
+ * - Initializing the Deepgram API key
+ * - Applying default options for the client and namespace
+ * - Providing a namespace for organizing API requests
  *
- * An isomorphic Javascript client for interacting with the Deepgram API.
- * @see https://developers.deepgram.com
+ * Subclasses of `AbstractClient` should implement the specific functionality for interacting with the Deepgram API.
  */
-export abstract class AbstractClient {
-  protected baseUrl: URL;
-
-  constructor(protected key: string, protected options: DeepgramClientOptions) {
-    this.key = key;
+export abstract class AbstractClient extends EventEmitter {
+  protected factory: Function | undefined = undefined;
+  protected key: string;
+  protected options: DefaultClientOptions;
+  public namespace: string = "global";
+  public version: string = "v1";
+  public baseUrl: string = DEFAULT_URL;
+  public logger: Function = noop;
+
+  /**
+   * Constructs a new instance of the DeepgramClient class with the provided options.
+   *
+   * @param options - The options to configure the DeepgramClient instance.
+   * @param options.key - The Deepgram API key to use for authentication. If not provided, the `DEEPGRAM_API_KEY` environment variable will be used.
+   * @param options.global - Global options that apply to all requests made by the DeepgramClient instance.
+   * @param options.global.fetch - Options to configure the fetch requests made by the DeepgramClient instance.
+   * @param options.global.fetch.options - Additional options to pass to the fetch function, such as `url` and `headers`.
+   * @param options.namespace - Options specific to a particular namespace within the DeepgramClient instance.
+   */
+  constructor(options: DeepgramClientOptions) {
+    super();
+
+    let key;
+
+    if (typeof options.key === "function") {
+      this.factory = options.key;
+      key = this.factory();
+    } else {
+      key = options.key;
+    }
 
     if (!key) {
-      this.key = process.env.DEEPGRAM_API_KEY as string;
+      key = process.env.DEEPGRAM_API_KEY as string;
     }
 
-    if (!this.key) {
-      throw new DeepgramError("A deepgram API key is required");
+    if (!key) {
+      throw new DeepgramError("A deepgram API key is required.");
     }
 
-    this.options = applySettingDefaults(options, DEFAULT_OPTIONS);
-
-    if (!this.options.global?.url) {
-      throw new DeepgramError(
-        `An API URL is required. It should be set to ${DEFAULT_URL} by default. No idea what happened!`
-      );
-    }
+    this.key = key;
 
-    let baseUrlString: string = this.options.global.url;
-    let proxyUrlString: string;
+    options = convertLegacyOptions(options);
 
     /**
-     * Check if the base URL provided is missing a protocol and warn in the console.
+     * Apply default options.
      */
-    if (!baseUrlString.startsWith("http") && !baseUrlString.startsWith("ws")) {
-      console.warn(
-        `The base URL provided does not begin with http, https, ws, or wss and will default to https as standard.`
-      );
+    this.options = applyDefaults<DeepgramClientOptions, DefaultClientOptions>(
+      options,
+      DEFAULT_OPTIONS
+    );
+  }
+
+  /**
+   * Sets the version for the current instance of the Deepgram API and returns the instance.
+   *
+   * @param version - The version to set for the Deepgram API instance. Defaults to "v1" if not provided.
+   * @returns The current instance of the AbstractClient with the updated version.
+   */
+  public v(version: string = "v1"): this {
+    this.version = version;
+
+    return this;
+  }
+
+  /**
+   * Gets the namespace options for the current instance of the AbstractClient.
+   * The namespace options include the default options merged with the global options,
+   * and the API key for the current instance.
+   *
+   * @returns The namespace options for the current instance.
+   */
+  get namespaceOptions(): DefaultNamespaceOptions {
+    const defaults = applyDefaults<NamespaceOptions, DefaultNamespaceOptions>(
+      (this.options as any)[this.namespace],
+      this.options.global
+    );
+
+    return {
+      ...defaults,
+      key: this.key,
+    };
+  }
+
+  /**
+   * Generates a URL for an API endpoint with optional query parameters and transcription options.
+   *
+   * @param endpoint - The API endpoint URL, which may contain placeholders for fields.
+   * @param fields - An optional object containing key-value pairs to replace placeholders in the endpoint URL.
+   * @param transcriptionOptions - Optional transcription options to include as query parameters in the URL.
+   * @returns A URL object representing the constructed API request URL.
+   */
+  public getRequestUrl(
+    endpoint: string,
+    fields: { [key: string]: string } = { version: this.version },
+    transcriptionOptions?: {
+      [key: string]: unknown;
     }
+  ): URL {
+    /**
+     * If we pass in fields without a version, set a version.
+     */
+    fields.version = this.version;
 
     /**
-     * Applying proxy to base URL.
+     * Version and template the endpoint for input argument..
      */
-    if (this.options.restProxy?.url) {
-      /**
-       * Prevent client using a real API key when using a proxy configuration.
-       */
-      if (this.key !== "proxy") {
-        throw new DeepgramError(
-          `Do not attempt to pass any other API key than the string "proxy" when making proxied REST requests. Please ensure your proxy application is responsible for writing our API key to the Authorization header.`
-        );
-      }
-
-      proxyUrlString = this.options.restProxy.url;
-
-      /**
-       * Check if the proxy URL provided is missing a protocol and warn in the console.
-       */
-      if (!proxyUrlString.startsWith("http") && !proxyUrlString.startsWith("ws")) {
-        console.warn(
-          `The proxy URL provided does not begin with http, https, ws, or wss and will default to https as standard.`
-        );
-      }
-
-      baseUrlString = proxyUrlString;
-    }
+    endpoint = endpoint.replace(/:(\w+)/g, function (_, key) {
+      return fields![key];
+    });
 
-    this.baseUrl = this.resolveBaseUrl(baseUrlString);
-  }
+    /**
+     * Create a URL object.
+     */
+    const url = new URL(endpoint as string, this.baseUrl);
 
-  protected resolveBaseUrl(url: string) {
-    if (!/^https?:\/\//i.test(url)) {
-      url = "https://" + url;
+    /**
+     * If there are transcription options, append them to the request as URL querystring parameters
+     */
+    if (transcriptionOptions) {
+      appendSearchParams(url.searchParams, transcriptionOptions);
     }
 
-    return new URL(stripTrailingSlash(url));
+    return url;
   }
 
-  protected willProxy() {
-    const proxyUrl = this.options.restProxy?.url;
-
-    return !!proxyUrl;
+  /**
+   * Logs the message.
+   *
+   * For customized logging, `this.logger` can be overridden.
+   */
+  public log(kind: string, msg: string, data?: any) {
+    this.logger(kind, msg, data);
   }
 }

package/src/packages/AbstractLiveClient.ts

@@ -0,0 +1,280 @@
+import { AbstractClient, noop } from "./AbstractClient";
+import { CONNECTION_STATE, SOCKET_STATES } from "../lib/constants";
+import type { DeepgramClientOptions, LiveSchema } from "../lib/types";
+import type { WebSocket as WSWebSocket } from "ws";
+
+/**
+ * Represents a constructor for a WebSocket-like object that can be used in the application.
+ * The constructor takes the following parameters:
+ * @param address - The URL or address of the WebSocket server.
+ * @param _ignored - An optional parameter that is ignored.
+ * @param options - An optional object containing headers to be included in the WebSocket connection.
+ * @returns A WebSocket-like object that implements the WebSocketLike interface.
+ */
+interface WebSocketLikeConstructor {
+  new (
+    address: string | URL,
+    _ignored?: any,
+    options?: { headers: Object | undefined }
+  ): WebSocketLike;
+}
+
+/**
+ * Represents the types of WebSocket-like connections that can be used in the application.
+ * This type is used to provide a common interface for different WebSocket implementations,
+ * such as the native WebSocket API, a WebSocket wrapper library, or a dummy implementation
+ * for testing purposes.
+ */
+type WebSocketLike = WebSocket | WSWebSocket | WSWebSocketDummy;
+
+/**
+ * Represents the types of data that can be sent or received over a WebSocket-like connection.
+ */
+type SocketDataLike = string | ArrayBufferLike | Blob;
+
+/**
+ * Represents an error that occurred in a WebSocket-like connection.
+ * @property {any} error - The underlying error object.
+ * @property {string} message - A human-readable error message.
+ * @property {string} type - The type of the error.
+ */
+interface WebSocketLikeError {
+  error: any;
+  message: string;
+  type: string;
+}
+
+/**
+ * Indicates whether a native WebSocket implementation is available in the current environment.
+ */
+const NATIVE_WEBSOCKET_AVAILABLE = typeof WebSocket !== "undefined";
+
+/**
+ * Represents an abstract live client that extends the AbstractClient class.
+ * The AbstractLiveClient class provides functionality for connecting, reconnecting, and disconnecting a WebSocket connection, as well as sending data over the connection.
+ * Subclasses of this class are responsible for setting up the connection event handlers.
+ *
+ * @abstract
+ */
+export abstract class AbstractLiveClient extends AbstractClient {
+  public headers: { [key: string]: string };
+  public transport: WebSocketLikeConstructor | null;
+  public conn: WebSocketLike | null = null;
+  public sendBuffer: Function[] = [];
+
+  constructor(options: DeepgramClientOptions) {
+    super(options);
+
+    const {
+      key,
+      websocket: { options: websocketOptions, client },
+    } = this.namespaceOptions;
+
+    if (this.proxy) {
+      this.baseUrl = websocketOptions.proxy!.url;
+    } else {
+      this.baseUrl = websocketOptions.url;
+    }
+
+    if (client) {
+      this.transport = client;
+    } else {
+      this.transport = null;
+    }
+
+    if (websocketOptions._nodeOnlyHeaders) {
+      this.headers = websocketOptions._nodeOnlyHeaders;
+    } else {
+      this.headers = {};
+    }
+
+    if (!("Authorization" in this.headers)) {
+      this.headers["Authorization"] = `Token ${key}`; // Add default token
+    }
+  }
+
+  /**
+   * Connects the socket, unless already connected.
+   *
+   * @protected Can only be called from within the class.
+   */
+  protected connect(transcriptionOptions: LiveSchema, endpoint: string): void {
+    if (this.conn) {
+      return;
+    }
+
+    this.reconnect = (options = transcriptionOptions) => {
+      this.connect(options, endpoint);
+    };
+
+    const requestUrl = this.getRequestUrl(endpoint, {}, transcriptionOptions);
+
+    /**
+     * Custom websocket transport
+     */
+    if (this.transport) {
+      this.conn = new this.transport(requestUrl, undefined, {
+        headers: this.headers,
+      });
+      return;
+    }
+
+    /**
+     * Native websocket transport (browser)
+     */
+    if (NATIVE_WEBSOCKET_AVAILABLE) {
+      this.conn = new WebSocket(requestUrl, ["token", this.namespaceOptions.key]);
+      this.setupConnection();
+      return;
+    }
+
+    /**
+     * Dummy websocket
+     */
+    this.conn = new WSWebSocketDummy(requestUrl, undefined, {
+      close: () => {
+        this.conn = null;
+      },
+    });
+
+    /**
+     * WS package for node environment
+     */
+    import("ws").then(({ default: WS }) => {
+      this.conn = new WS(requestUrl, undefined, {
+        headers: this.headers,
+      });
+      this.setupConnection();
+    });
+  }
+
+  /**
+   * Reconnects the socket using new or existing transcription options.
+   *
+   * @param options - The transcription options to use when reconnecting the socket.
+   */
+  public reconnect: (options: LiveSchema) => void = noop;
+
+  /**
+   * Disconnects the socket from the client.
+   *
+   * @param code A numeric status code to send on disconnect.
+   * @param reason A custom reason for the disconnect.
+   */
+  public disconnect(code?: number, reason?: string): void {
+    if (this.conn) {
+      this.conn.onclose = function () {}; // noop
+      if (code) {
+        this.conn.close(code, reason ?? "");
+      } else {
+        this.conn.close();
+      }
+      this.conn = null;
+    }
+  }
+
+  /**
+   * Returns the current connection state of the WebSocket connection.
+   *
+   * @returns The current connection state of the WebSocket connection.
+   */
+  public connectionState(): CONNECTION_STATE {
+    switch (this.conn && this.conn.readyState) {
+      case SOCKET_STATES.connecting:
+        return CONNECTION_STATE.Connecting;
+      case SOCKET_STATES.open:
+        return CONNECTION_STATE.Open;
+      case SOCKET_STATES.closing:
+        return CONNECTION_STATE.Closing;
+      default:
+        return CONNECTION_STATE.Closed;
+    }
+  }
+
+  /**
+   * Returns the current ready state of the WebSocket connection.
+   *
+   * @returns The current ready state of the WebSocket connection.
+   */
+  public getReadyState(): SOCKET_STATES {
+    return this.conn?.readyState ?? SOCKET_STATES.closed;
+  }
+
+  /**
+   * Returns `true` is the connection is open.
+   */
+  public isConnected(): boolean {
+    return this.connectionState() === CONNECTION_STATE.Open;
+  }
+
+  /**
+   * Sends data to the Deepgram API via websocket connection
+   * @param data Audio data to send to Deepgram
+   *
+   * Conforms to RFC #146 for Node.js - does not send an empty byte.
+   * @see https://github.com/deepgram/deepgram-python-sdk/issues/146
+   */
+  send(data: SocketDataLike): void {
+    const callback = async () => {
+      if (data instanceof Blob) {
+        if (data.size === 0) {
+          this.log("warn", "skipping `send` for zero-byte blob", data);
+
+          return;
+        }
+
+        data = await data.arrayBuffer();
+      }
+
+      if (typeof data !== "string") {
+        if (data.byteLength === 0) {
+          this.log("warn", "skipping `send` for zero-byte blob", data);
+
+          return;
+        }
+      }
+
+      this.conn?.send(data);
+    };
+
+    if (this.isConnected()) {
+      callback();
+    } else {
+      this.sendBuffer.push(callback);
+    }
+  }
+
+  /**
+   * Determines whether the current instance should proxy requests.
+   * @returns {boolean} true if the current instance should proxy requests; otherwise, false
+   */
+  get proxy(): boolean {
+    return this.key === "proxy" && !!this.namespaceOptions.websocket.options.proxy?.url;
+  }
+
+  /**
+   * Sets up the connection event handlers.
+   *
+   * @abstract Requires subclasses to set up context aware event handlers.
+   */
+  abstract setupConnection(): void;
+}
+
+class WSWebSocketDummy {
+  binaryType: string = "arraybuffer";
+  close: Function;
+  onclose: Function = () => {};
+  onerror: Function = () => {};
+  onmessage: Function = () => {};
+  onopen: Function = () => {};
+  readyState: number = SOCKET_STATES.connecting;
+  send: Function = () => {};
+  url: string | URL | null = null;
+
+  constructor(address: URL, _protocols: undefined, options: { close: Function }) {
+    this.url = address.toString();
+    this.close = options.close;
+  }
+}
+
+export { AbstractLiveClient as AbstractWsClient };