feat: abstract client rebuilt for namespace options

Author: lukeocodes

src/lib/constants.ts

@@ -1,6 +1,5 @@
-import { isBrowser } from "./helpers";
-import { DeepgramClientOptions } from "./types/DeepgramClientOptions";
-import { FetchOptions } from "./types/Fetch";
+import { convertProtocolToWs, isBrowser } from "./helpers";
+import { DefaultNamespaceOptions, DefaultClientOptions } from "./types/DeepgramClientOptions";
 import { version } from "./version";
 
 export const NODE_VERSION =
@@ -16,15 +15,11 @@ export const DEFAULT_HEADERS = {
 
 export const DEFAULT_URL = "https://api.deepgram.com";
 
-export const DEFAULT_GLOBAL_OPTIONS = {
-  url: DEFAULT_URL,
+export const DEFAULT_GLOBAL_OPTIONS: DefaultNamespaceOptions = {
+  fetch: { options: { url: DEFAULT_URL, headers: DEFAULT_HEADERS } },
+  websocket: { options: { url: convertProtocolToWs(DEFAULT_URL) } },
 };
 
-export const DEFAULT_FETCH_OPTIONS: FetchOptions = {
-  headers: DEFAULT_HEADERS,
-};
-
-export const DEFAULT_OPTIONS: DeepgramClientOptions = {
+export const DEFAULT_OPTIONS: DefaultClientOptions = {
   global: DEFAULT_GLOBAL_OPTIONS,
-  fetch: DEFAULT_FETCH_OPTIONS,
 };

src/lib/helpers.ts

@@ -17,11 +17,8 @@ export function stripTrailingSlash(url: string): string {
 export const isBrowser = () => typeof window !== "undefined";
 export const isServer = () => typeof process !== "undefined";
 
-export function applySettingDefaults(
-  options: DeepgramClientOptions,
-  defaults: DeepgramClientOptions
-): DeepgramClientOptions {
-  return merge(defaults, options);
+export function applyDefaults<O, S>(options: Partial<O>, subordinate: Partial<S>): S {
+  return merge(subordinate, options);
 }
 
 export function appendSearchParams(
@@ -83,5 +80,19 @@ const isReadStreamSource = (providedSource: PrerecordedSource): providedSource i
 };
 
 export class CallbackUrl extends URL {
-  private callbackUrl = true;
+  public callbackUrl = true;
 }
+
+export const convertProtocolToWs = (url: string | URL) => {
+  const convert = (string: string) => string.toLowerCase().replace(/(http)(s)?/gi, "ws$2");
+
+  if (url instanceof URL) {
+    return new URL(convert(url.toString()));
+  }
+
+  if (typeof url === "string") {
+    return new URL(convert(url));
+  }
+
+  throw new Error("URL must be a string or `URL` object");
+};

src/lib/types/DeepgramClientOptions.ts

@@ -1,20 +1,62 @@
-import { Fetch, FetchOptions } from "./Fetch";
+import { FetchOptions } from "./Fetch";
 
+export type IFetch = typeof fetch;
+export type IWebSocket = typeof WebSocket;
+
+/**
+ * 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 {
-  global?: {
-    /**
-     * Optional headers for initializing the client.
-     */
-    headers?: Record<string, string>;
-
-    /**
-     * The URL used to interact with production, On-prem and other Deepgram environments. Defaults to `api.deepgram.com`.
-     */
-    url?: string;
-  };
-  fetch?: FetchOptions;
-  _experimentalCustomFetch?: Fetch;
-  restProxy?: {
-    url: null | string;
+  global?: NamespaceOptions;
+  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 {}
+
+type TransportUrl = URL | string;
+
+interface TransportOptions {
+  url?: TransportUrl;
+  proxy?: {
+    url?: null | TransportUrl;
   };
 }
+
+interface ITransport<C, O> {
+  client?: C;
+  options?: O;
+}
+export interface NamespaceOptions {
+  fetch?: ITransport<IFetch, TransportFetchOptions>;
+  websocket?: ITransport<IWebSocket, TransportOptions>;
+}
+
+export type DefaultNamespaceOptions = {
+  fetch: {
+    options: { url: TransportUrl };
+  };
+  websocket: {
+    options: { url: TransportUrl };
+  };
+} & NamespaceOptions;
+
+export type DefaultClientOptions = {
+  global: DefaultNamespaceOptions;
+} & DeepgramClientOptions;

src/packages/AbstractClient.ts

@@ -1,18 +1,29 @@
-import { DEFAULT_OPTIONS, DEFAULT_URL } from "../lib/constants";
+import { DEFAULT_OPTIONS } from "../lib/constants";
 import { DeepgramError } from "../lib/errors";
-import { applySettingDefaults, stripTrailingSlash } from "../lib/helpers";
+import { applyDefaults } from "../lib/helpers";
 import { DeepgramClientOptions } from "../lib/types";
+import {
+  DefaultClientOptions,
+  DefaultNamespaceOptions,
+  NamespaceOptions,
+} from "../lib/types/DeepgramClientOptions";
 
 /**
- * Deepgram Client.
+ * Represents an abstract Deepgram client that provides a base implementation for interacting with the Deepgram API.
  *
- * An isomorphic Javascript client for interacting with the Deepgram API.
- * @see https://developers.deepgram.com
+ * 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
+ *
+ * Subclasses of `AbstractClient` should implement the specific functionality for interacting with the Deepgram API.
  */
 export abstract class AbstractClient {
-  protected baseUrl: URL;
+  public namespace: string = "global";
+  protected namespaceOptions: DefaultNamespaceOptions;
+  protected options: DefaultClientOptions;
 
-  constructor(protected key: string, protected options: DeepgramClientOptions) {
+  constructor(protected key: string, options: DeepgramClientOptions) {
     this.key = key;
 
     if (!key) {
@@ -23,67 +34,20 @@ export abstract class AbstractClient {
       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!`
-      );
-    }
-
-    let baseUrlString: string = this.options.global.url;
-    let proxyUrlString: string;
-
     /**
-     * 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
+    );
 
     /**
-     * Applying proxy to base URL.
+     * Roll up options for this namespace.
      */
-    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;
-    }
-
-    this.baseUrl = this.resolveBaseUrl(baseUrlString);
-  }
-
-  protected resolveBaseUrl(url: string) {
-    if (!/^https?:\/\//i.test(url)) {
-      url = "https://" + url;
-    }
-
-    return new URL(stripTrailingSlash(url));
-  }
-
-  protected willProxy() {
-    const proxyUrl = this.options.restProxy?.url;
-
-    return !!proxyUrl;
+    this.namespaceOptions = applyDefaults<NamespaceOptions, DefaultNamespaceOptions>(
+      this.options[this.namespace],
+      this.options.global!
+    );
   }
 }

src/packages/AbstractRestfulClient.ts

@@ -9,7 +9,7 @@ import { isBrowser } from "../lib/helpers";
 export abstract class AbstractRestfulClient extends AbstractClient {
   protected fetch: Fetch;
 
-  constructor(protected key: string, protected options: DeepgramClientOptions) {
+  constructor(protected key: string, options: DeepgramClientOptions) {
     super(key, options);
 
     if (isBrowser() && !this._willProxy()) {
@@ -18,7 +18,7 @@ export abstract class AbstractRestfulClient extends AbstractClient {
       );
     }
 
-    this.fetch = fetchWithAuth(this.key, options._experimentalCustomFetch);
+    this.fetch = fetchWithAuth(this.key, this.namespaceOptions.fetch.client);
   }
 
   protected _getErrorMessage(err: any): string {
@@ -153,7 +153,7 @@ export abstract class AbstractRestfulClient extends AbstractClient {
   }
 
   private _willProxy() {
-    const proxyUrl = this.options.restProxy?.url;
+    const proxyUrl = this.key === "proxy" && !!this.namespaceOptions.fetch.options.proxy?.url;
 
     return !!proxyUrl;
   }