feat: merge in new websocket transmitter changes

Author: lukeocodes

test/live.test.ts disabled_tests/live.test.tstest/live.test.ts renamed to disabled_tests/live.test.ts

@@ -21,7 +21,7 @@ const transcribeUrl = async () => {
 const transcribeFile = async () => {
   const deepgram = createClient(process.env.DEEPGRAM_API_KEY);
 
-  const file = fs.readFileSync("./examples/nasa.mp4");
+  const file = fs.readFileSync("./examples/spacewalk.wav");
 
   console.log("Transcribing file", file);
   const { result, error } = await deepgram.listen.prerecorded.transcribeFile(file, {

examples/node-prerecorded/index.js

@@ -47,8 +47,8 @@
     "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/v2 --includes src/**/*.ts",
-    "docs:json": "typedoc --entryPoints src/index.ts --includes src/**/*.ts --json docs/v2/spec.json --excludeExternals"
+    "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"
   },
   "dependencies": {
     "@deepgram/captions": "^1.1.1",

examples/spacewalk.wav

@@ -4,41 +4,68 @@ import {
   ListenClient,
   ManageClient,
   ReadClient,
-  SelfHostedClient as OnPremClient,
-  SelfHostedClient,
+  OnPremClient,
+  SelfHostedRestClient,
   SpeakClient,
 } from "./packages";
 
 /**
- * The DeepgramClient class provides access to various Deepgram API clients, including ListenClient, ManageClient, SelfHostedClient, ReadClient, and SpeakClient.
+ * The DeepgramClient class provides access to various Deepgram API clients, including ListenClient, ManageClient, SelfHostedRestClient, ReadClient, and SpeakClient.
  *
  * @see https://github.com/deepgram/deepgram-js-sdk
  */
 export default class DeepgramClient extends AbstractClient {
+  /**
+   * Returns a new instance of the ListenClient, which provides access to the Deepgram API's listening functionality.
+   *
+   * @returns {ListenClient} A new instance of the ListenClient.
+   */
   get listen(): ListenClient {
     return new ListenClient(this.options);
   }
 
+  /**
+   * Returns a new instance of the ManageClient, which provides access to the Deepgram API's management functionality.
+   *
+   * @returns {ManageClient} A new instance of the ManageClient.
+   */
   get manage(): ManageClient {
     return new ManageClient(this.options);
   }
 
   /**
-   * backwards compatibility for renaming onprem to selfhosted
+   * Returns a new instance of the SelfHostedRestClient, which provides access to the Deepgram API's self-hosted functionality.
+   *
+   * @returns {OnPremClient} A new instance of the SelfHostedRestClient named as OnPremClient.
    * @deprecated use selfhosted() instead
    */
   get onprem(): OnPremClient {
     return this.selfhosted;
   }
 
-  get selfhosted(): SelfHostedClient {
-    return new SelfHostedClient(this.options);
+  /**
+   * Returns a new instance of the SelfHostedRestClient, which provides access to the Deepgram API's self-hosted functionality.
+   *
+   * @returns {SelfHostedRestClient} A new instance of the SelfHostedRestClient.
+   */
+  get selfhosted(): SelfHostedRestClient {
+    return new SelfHostedRestClient(this.options);
   }
 
+  /**
+   * Returns a new instance of the ReadClient, which provides access to the Deepgram API's reading functionality.
+   *
+   * @returns {ReadClient} A new instance of the ReadClient.
+   */
   get read(): ReadClient {
     return new ReadClient(this.options);
   }
 
+  /**
+   * Returns a new instance of the SpeakClient, which provides access to the Deepgram API's speaking functionality.
+   *
+   * @returns {SpeakClient} A new instance of the SpeakClient.
+   */
   get speak(): SpeakClient {
     return new SpeakClient(this.options);
   }

package.json

@@ -10,13 +10,15 @@ import type { Fetch } from "./types";
  */
 export const resolveFetch = (customFetch?: Fetch): Fetch => {
   let _fetch: Fetch;
+
   if (customFetch) {
     _fetch = customFetch;
   } else if (typeof fetch === "undefined") {
     _fetch = crossFetch as unknown as Fetch;
   } else {
     _fetch = fetch;
   }
+
   return (...args) => _fetch(...args);
 };
 

src/DeepgramClient.ts

@@ -19,7 +19,7 @@ export function stripTrailingSlash(url: string): string {
 export const isBrowser = () => typeof window !== "undefined";
 export const isServer = () => typeof process !== "undefined";
 
-export function applyDefaults<O, S>(options: Partial<O>, subordinate: Partial<S>): S {
+export function applyDefaults<O, S>(options: Partial<O> = {}, subordinate: Partial<S> = {}): S {
   return merge(subordinate, options);
 }
 

src/lib/fetch.ts

@@ -1,46 +1,9 @@
-import { FetchOptions } from "./Fetch";
+import { Fetch, FetchOptions } from "./Fetch";
 
 export type IKeyFactory = () => string;
 export type IFetch = typeof fetch;
 export type IWebSocket = typeof WebSocket;
 
-/**
- * Defines the arguments for creating a Deepgram client.
- *
- * The `DeepgramClientArgs` type represents the possible arguments that can be passed when creating a Deepgram client. It can be either:
- *
- * 1. An array with two elements:
- *    - The first element is a string or an `IKeyFactory` object, representing the API key.
- *    - The second element is a `DeepgramClientOptions` object, representing the configuration options for the Deepgram client.
- * 2. An array with a single `DeepgramClientOptions` object, representing the configuration options for the Deepgram client.
- */
-
-/**
- * Configures the options for a Deepgram client.
- *
- * The `DeepgramClientOptions` interface defines the configuration options for a Deepgram client. It includes options for various namespaces, such as `global`, `listen`, `manage`, `onprem`, `read`, and `speak`. Each namespace has its own options for configuring the transport, including the URL, proxy, and options for the fetch and WebSocket clients.
- *
- * The `global` namespace is used to configure options that apply globally to the Deepgram client. The other namespaces are used to configure options specific to different Deepgram API endpoints.
- */
-export interface DeepgramClientOptions {
-  key?: string | IKeyFactory;
-  global?: NamespaceOptions & { url?: string; headers?: { [index: string]: any } };
-  listen?: NamespaceOptions;
-  manage?: NamespaceOptions;
-  onprem?: NamespaceOptions;
-  read?: NamespaceOptions;
-  speak?: NamespaceOptions;
-
-  /**
-   * Support introductory format
-   */
-  [index: string]: any;
-  // _experimentalCustomFetch?: Fetch;
-  // restProxy?: {
-  //   url: null | string;
-  // };
-}
-
 interface TransportFetchOptions extends TransportOptions, FetchOptions {}
 interface TransportWebSocketOptions extends TransportOptions {
   _nodeOnlyHeaders?: { [index: string]: any };
@@ -59,12 +22,9 @@ interface ITransport<C, O> {
   client?: C;
   options?: O;
 }
-export interface NamespaceOptions {
-  fetch?: ITransport<IFetch, TransportFetchOptions>;
-  websocket?: ITransport<IWebSocket, TransportWebSocketOptions>;
-}
 
 export type DefaultNamespaceOptions = {
+  key: string;
   fetch: {
     options: { url: TransportUrl };
   };
@@ -73,6 +33,52 @@ export type DefaultNamespaceOptions = {
   };
 } & NamespaceOptions;
 
+export interface NamespaceOptions {
+  key?: string;
+  fetch?: ITransport<IFetch, TransportFetchOptions>;
+  websocket?: ITransport<IWebSocket, TransportWebSocketOptions>;
+}
+
 export type DefaultClientOptions = {
-  global: DefaultNamespaceOptions;
+  global: Partial<DefaultNamespaceOptions>;
 } & DeepgramClientOptions;
+
+/**
+ * Configures the options for a Deepgram client.
+ *
+ * The `DeepgramClientOptions` interface defines the configuration options for a Deepgram client. It includes options for various namespaces, such as `global`, `listen`, `manage`, `onprem`, `read`, and `speak`. Each namespace has its own options for configuring the transport, including the URL, proxy, and options for the fetch and WebSocket clients.
+ *
+ * The `global` namespace is used to configure options that apply globally to the Deepgram client. The other namespaces are used to configure options specific to different Deepgram API endpoints.
+ * Support introductory formats:
+ * - fetch: FetchOptions;
+ * - _experimentalCustomFetch?: Fetch;
+ * - restProxy?: {
+ *     url: null | string;
+ *   };
+ */
+export interface DeepgramClientOptions {
+  key?: string | IKeyFactory;
+  global?: NamespaceOptions & { url?: string; headers?: { [index: string]: any } };
+  listen?: NamespaceOptions;
+  manage?: NamespaceOptions;
+  onprem?: NamespaceOptions;
+  read?: NamespaceOptions;
+  speak?: NamespaceOptions;
+
+  /**
+   * @deprecated as of 3.4, use a namespace like `global` instead
+   */
+  fetch?: FetchOptions;
+
+  /**
+   * @deprecated as of 3.4, use a namespace like `global` instead
+   */
+  _experimentalCustomFetch?: Fetch;
+
+  /**
+   * @deprecated as of 3.4, use a namespace like `global` instead
+   */
+  restProxy?: {
+    url: null | string;
+  };
+}

src/lib/helpers.ts

@@ -1,3 +1,7 @@
-export interface LiveConfigOptions {
-  numerals?: boolean;
-}
+import { LiveSchema } from "./TranscriptionSchema";
+
+/**
+ * Partial configuration options for the LiveSchema, including:
+ * - `numerals`: Configures how numerals are handled in the live transcription.
+ */
+export type LiveConfigOptions = Partial<Pick<LiveSchema, "numerals">>;

src/lib/types/DeepgramClientOptions.ts

@@ -2,12 +2,14 @@ import EventEmitter from "events";
 import { DEFAULT_OPTIONS, DEFAULT_URL } from "../lib/constants";
 import { DeepgramError } from "../lib/errors";
 import { appendSearchParams, applyDefaults, convertLegacyOptions } from "../lib/helpers";
-import { DeepgramClientOptions, LiveSchema, TranscriptionSchema } from "../lib/types";
-import {
+import type {
+  DeepgramClientOptions,
   DefaultClientOptions,
   DefaultNamespaceOptions,
   NamespaceOptions,
-} from "../lib/types/DeepgramClientOptions";
+} from "../lib/types";
+
+export const noop = () => {};
 
 /**
  * Represents an abstract Deepgram client that provides a base implementation for interacting with the Deepgram API.
@@ -22,11 +24,11 @@ import {
 export abstract class AbstractClient extends EventEmitter {
   protected factory: Function | undefined = undefined;
   protected key: string;
-  protected namespaceOptions: DefaultNamespaceOptions;
   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.
@@ -69,28 +71,37 @@ export abstract class AbstractClient extends EventEmitter {
       options,
       DEFAULT_OPTIONS
     );
-
-    /**
-     * Roll up options for this namespace.
-     */
-    this.namespaceOptions = applyDefaults<NamespaceOptions, DefaultNamespaceOptions>(
-      this.options[this.namespace],
-      this.options.global!
-    );
   }
 
+  /**
+   * 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;
   }
 
   /**
-   * Determines whether the current instance should proxy requests.
-   * @returns {boolean} true if the current instance should proxy requests; otherwise, false
+   * 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 proxy(): boolean {
-    return this.key === "proxy" && !!this.namespaceOptions.fetch.options.proxy?.url;
+  get namespaceOptions(): DefaultNamespaceOptions {
+    const defaults = applyDefaults<NamespaceOptions, DefaultNamespaceOptions>(
+      (this.options as any)[this.namespace],
+      this.options.global
+    );
+
+    return {
+      ...defaults,
+      key: this.key,
+    };
   }
 
   /**
@@ -134,4 +145,13 @@ export abstract class AbstractClient extends EventEmitter {
 
     return url;
   }
+
+  /**
+   * Logs the message.
+   *
+   * For customized logging, `this.logger` can be overridden.
+   */
+  public log(kind: string, msg: string, data?: any) {
+    this.logger(kind, msg, data);
+  }
 }