feat: improve websocket management

README.md

@@ -11,7 +11,14 @@ Official JavaScript SDK for [Deepgram](https://www.deepgram.com/). Power your ap
 - [Initialization](#initialization)
   - [Getting an API Key](#getting-an-api-key)
 - [Scoped Configuration](#scoped-configuration)
-  - [Rest requests in the browser](#rest-requests-in-the-browser)
+  - [1. Global Defaults](#1-global-defaults)
+  - [2. Namespace-specific Configurations](#2-namespace-specific-configurations)
+  - [3. Transport Options](#3-transport-options)
+  - [Change the API url used for all SDK methods](#change-the-api-url-used-for-all-sdk-methods)
+  - [Change the API url used for transcription only](#change-the-api-url-used-for-transcription-only)
+  - [Override fetch transmitter](#override-fetch-transmitter)
+  - [Proxy requests in the browser](#proxy-requests-in-the-browser)
+  - [Set custom headers for fetch](#set-custom-headers-for-fetch)
 - [Transcription (Synchronous)](#transcription-synchronous)
   - [Remote Files](#remote-files)
   - [Local Files](#local-files)
@@ -55,7 +62,7 @@ Official JavaScript SDK for [Deepgram](https://www.deepgram.com/). Power your ap
   - [Get On-Prem credentials](#get-on-prem-credentials)
   - [Create On-Prem credentials](#create-on-prem-credentials)
   - [Delete On-Prem credentials](#delete-on-prem-credentials)
--  [Backwards Compatibility](#backwards-compatibility)
+- [Backwards Compatibility](#backwards-compatibility)
 - [Development and Contributing](#development-and-contributing)
   - [Debugging and making changes locally](#debugging-and-making-changes-locally)
 - [Getting Help](#getting-help)
@@ -130,28 +137,82 @@ const deepgram = createClient(DEEPGRAM_API_KEY);
 
 # Scoped Configuration
 
-A new feature is scoped configuration. You'll be able to configure various aspects of the SDK from the initialization.
+The SDK supports scoped configurtion. You'll be able to configure various aspects of each namespace of the SDK from the initialization. Below outlines a flexible and customizable configuration system for the Deepgram SDK. Here’s how the namespace configuration works:
+
+## 1. Global Defaults
+
+- The `global` namespace serves as the foundational configuration applicable across all other namespaces unless overridden.
+- Includes general settings like URL and headers applicable for all API calls.
+- If no specific configurations are provided for other namespaces, the `global` defaults are used.
+
+## 2. Namespace-specific Configurations
+
+- Each namespace (`listen`, `manage`, `onprem`, `read`, `speak`) can have its specific configurations which override the `global` settings within their respective scopes.
+- Allows for detailed control over different parts of the application interacting with various Deepgram API endpoints.
+
+## 3. Transport Options
+
+- Configurations for both `fetch` and `websocket` can be specified under each namespace, allowing different transport mechanisms for different operations.
+- For example, the `fetch` configuration can have its own URL and proxy settings distinct from the `websocket`.
+- The generic interfaces define a structure for transport options which include a client (like a `fetch` or `WebSocket` instance) and associated options (like headers, URL, proxy settings).
+
+This configuration system enables robust customization where defaults provide a foundation, but every aspect of the client's interaction with the API can be finely controlled and tailored to specific needs through namespace-specific settings. This enhances the maintainability and scalability of the application by localizing configurations to their relevant contexts.
+
+## Change the API url used for all SDK methods
+
+Useful for using different API environments (for e.g. beta).
+
+```js
+import { createClient } from "@deepgram/sdk";
+// - or -
+// const { createClient } = require("@deepgram/sdk");
+
+const deepgram = createClient(DEEPGRAM_API_KEY, {
+  global: { fetch: { options: { url: "https://api.beta.deepgram.com" } } },
+});
+```
+
+## Change the API url used for transcription only
+
+Useful for on-prem installations. Only affects requests to `/listen` endpoints.
+
+```js
+import { createClient } from "@deepgram/sdk";
+// - or -
+// const { createClient } = require("@deepgram/sdk");
+
+const deepgram = createClient(DEEPGRAM_API_KEY, {
+  listen: { fetch: { options: { url: "http://localhost:8080" } } },
+});
+```
+
+## Override fetch transmitter
+
+Useful for providing a custom http client.
 
 ```js
 import { createClient } from "@deepgram/sdk";
 // - or -
 // const { createClient } = require("@deepgram/sdk");
 
+const yourFetch = async () => {
+  return Response("...etc");
+};
+
 const deepgram = createClient(DEEPGRAM_API_KEY, {
-  global: { url: "https://api.beta.deepgram.com" },
-  // restProxy: { url: "http://localhost:8080" }
+  global: { fetch: { client: yourFetch } },
 });
 ```
 
-## Rest requests in the browser
+## Proxy requests in the browser
 
 This SDK now works in the browser. If you'd like to make REST-based requests (pre-recorded transcription, on-premise, and management requests), then you'll need to use a proxy as we do not support custom CORS origins on our API. To set up your proxy, you configure the SDK like so:
 
 ```js
 import { createClient } from "@deepgram/sdk";
 
 const deepgram = createClient("proxy", {
-  restProxy: { url: "http://localhost:8080" },
+  global: { fetch: { options: { proxy: { url: "http://localhost:8080" } } } },
 });
 ```
 
@@ -161,6 +222,18 @@ Your proxy service should replace the Authorization header with `Authorization:
 
 Check out our example Node-based proxy here: [Deepgram Node Proxy](https://github.com/deepgram-devs/deepgram-node-proxy).
 
+## Set custom headers for fetch
+
+Useful for many things.
+
+```js
+import { createClient } from "@deepgram/sdk";
+
+const deepgram = createClient("proxy", {
+  global: { fetch: { options: { headers: { "x-custom-header": "foo" } } } },
+});
+```
+
 # Transcription (Synchronous)
 
 ## Remote Files
@@ -562,6 +635,8 @@ const { result, error } = await deepgram.onprem.deleteCredentials(projectId, cre
 
 Older SDK versions will receive Priority 1 (P1) bug support only. Security issues, both in our code and dependencies, are promptly addressed. Significant bugs without clear workarounds are also given priority attention.
 
+We strictly follow semver, and will not introduce breaking changes to the publicly documented interfaces of the SDK. Use internal and undocumented interfaces without pinning your version, at your own risk.
+
 # Development and Contributing
 
 Interested in contributing? We ❤️ pull requests!

examples/browser-live/index.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <script src="../../dist/umd/deepgram.js"></script>
+    <script>
+      const { createClient } = deepgram;
+      const _deepgram = createClient("deepgram-api-key", {
+        global: {
+          fetch: {
+            options: {
+              url: "https://api.mock.deepgram.com",
+            },
+          },
+        },
+      });
+
+      console.log("Deepgram Instance: ", _deepgram);
+
+      (async () => {
+        const { result, error } = await _deepgram.manage.getProjects();
+
+        console.log(result, error);
+      })();
+
+      // ...
+    </script>
+  </head>
+  <body>
+    Running test... check the developer console.
+  </body>
+</html>

examples/browser-prerecorded/index.html

@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <script src="../../dist/umd/deepgram.js"></script>
+    <script>
+      const { createClient } = deepgram;
+      const _deepgram = createClient("deepgram-api-key", {
+        global: {
+          fetch: {
+            options: {
+              url: "https://api.mock.deepgram.com",
+            },
+          },
+        },
+      });
+
+      console.log("Deepgram Instance: ", _deepgram);
+
+      const transcribeUrl = async () => {
+        const { result, error } = await _deepgram.listen.prerecorded.transcribeUrl(
+          {
+            url: "https://dpgr.am/spacewalk.wav",
+          },
+          {
+            model: "nova",
+          }
+        );
+
+        if (error) throw error;
+        if (!error) console.dir(result, { depth: null });
+      };
+
+      const transcribeFile = async () => {
+        const { result, error } = await _deepgram.listen.prerecorded.transcribeFile(
+          fs.readFileSync("./examples/nasa.mp4"),
+          {
+            model: "nova",
+          }
+        );
+
+        if (error) throw error;
+        if (!error) console.dir(result, { depth: null });
+      };
+
+      transcribeUrl();
+      transcribeFile();
+      // ...
+    </script>
+  </head>
+  <body>
+    Running test... check the developer console.
+  </body>
+</html>