@deepgram/sdk 3.3.4 → 3.4.0

package/src/lib/constants.ts

@@ -1,28 +1,48 @@
-import { isBrowser } from "./helpers";
-import { DeepgramClientOptions } from "./types/DeepgramClientOptions";
-import { FetchOptions } from "./types/Fetch";
+import { convertProtocolToWs, isBrowser } from "./helpers";
 import { version } from "./version";
+import type { DefaultNamespaceOptions, DefaultClientOptions } from "./types";
 
 export const NODE_VERSION =
-  typeof process === "undefined" ? "Unknown" : process?.versions?.node || "Unknown";
+  typeof process !== "undefined" && process.versions && process.versions.node
+    ? process.versions.node
+    : "unknown";
+
+export const BROWSER_AGENT =
+  typeof window !== "undefined" && window.navigator && window.navigator.userAgent
+    ? window.navigator.userAgent
+    : "unknown";
 
 export const DEFAULT_HEADERS = {
   "Content-Type": `application/json`,
   "X-Client-Info": `@deepgram/sdk; ${isBrowser() ? "browser" : "server"}; v${version}`,
-  "User-Agent": `@deepgram/sdk/${version} ${isBrowser() ? "javascript" : `node/${NODE_VERSION}`}`,
+  "User-Agent": `@deepgram/sdk/${version} ${
+    isBrowser() ? `javascript ${BROWSER_AGENT}` : `node/${NODE_VERSION}`
+  }`,
 };
 
 export const DEFAULT_URL = "https://api.deepgram.com";
 
-export const DEFAULT_GLOBAL_OPTIONS = {
-  url: DEFAULT_URL,
-};
-
-export const DEFAULT_FETCH_OPTIONS: FetchOptions = {
-  headers: DEFAULT_HEADERS,
+export const DEFAULT_GLOBAL_OPTIONS: Partial<DefaultNamespaceOptions> = {
+  fetch: { options: { url: DEFAULT_URL, headers: DEFAULT_HEADERS } },
+  websocket: {
+    options: { url: convertProtocolToWs(DEFAULT_URL), _nodeOnlyHeaders: DEFAULT_HEADERS },
+  },
 };
 
-export const DEFAULT_OPTIONS: DeepgramClientOptions = {
+export const DEFAULT_OPTIONS: DefaultClientOptions = {
   global: DEFAULT_GLOBAL_OPTIONS,
-  fetch: DEFAULT_FETCH_OPTIONS,
 };
+
+export enum SOCKET_STATES {
+  connecting = 0,
+  open = 1,
+  closing = 2,
+  closed = 3,
+}
+
+export enum CONNECTION_STATE {
+  Connecting = "connecting",
+  Open = "open",
+  Closing = "closing",
+  Closed = "closed",
+}

package/src/lib/enums/LiveConnectionState.ts

@@ -1,6 +1,13 @@
+import { SOCKET_STATES } from "../constants";
+
+/**
+ * Enum representing the different states of a live connection.
+ *
+ * @deprecated Since 3.4. Use `SOCKET_STATES` for generic socket connection states instead.
+ */
 export enum LiveConnectionState {
-  CONNECTING = 0,
-  OPEN = 1,
-  CLOSING = 2,
-  CLOSED = 3,
+  CONNECTING = SOCKET_STATES.connecting,
+  OPEN = SOCKET_STATES.open,
+  CLOSING = SOCKET_STATES.closing,
+  CLOSED = SOCKET_STATES.closed,
 }

package/src/lib/enums/LiveTranscriptionEvents.ts

@@ -1,10 +1,33 @@
+/**
+ * Enumeration of events related to live transcription.
+ *
+ * - `Open`: Built-in socket event for when the connection is opened.
+ * - `Close`: Built-in socket event for when the connection is closed.
+ * - `Error`: Built-in socket event for when an error occurs.
+ * - `Transcript`: Event for when a transcript message is received.
+ * - `Metadata`: Event for when metadata is received.
+ * - `UtteranceEnd`: Event for when an utterance ends.
+ * - `SpeechStarted`: Event for when speech is detected.
+ * - `Unhandled`: Catch-all event for any other message event.
+ */
 export enum LiveTranscriptionEvents {
+  /**
+   * Built in socket events.
+   */
   Open = "open",
   Close = "close",
-  Transcript = "Results", // exact match to data type from API
-  Metadata = "Metadata", // exact match to data type from API
   Error = "error",
-  Warning = "warning",
-  UtteranceEnd = "UtteranceEnd", // exact match to data type from API
+
+  /**
+   * Message { type: string }
+   */
+  Transcript = "Results",
+  Metadata = "Metadata",
+  UtteranceEnd = "UtteranceEnd",
   SpeechStarted = "SpeechStarted",
+
+  /**
+   * Catch all for any other message event
+   */
+  Unhandled = "Unhandled",
 }

package/src/lib/enums/index.ts

@@ -1,2 +1,2 @@
-export { LiveConnectionState } from "./LiveConnectionState";
-export { LiveTranscriptionEvents } from "./LiveTranscriptionEvents";
+export * from "./LiveConnectionState";
+export * from "./LiveTranscriptionEvents";

package/src/lib/fetch.ts

@@ -1,9 +1,16 @@
-import crossFetch from "cross-fetch";
 import { resolveHeadersConstructor } from "./helpers";
-import type { Fetch } from "./types/Fetch";
+import crossFetch from "cross-fetch";
+import type { Fetch } from "./types";
 
+/**
+ * Resolves the appropriate fetch function to use, either a custom fetch function provided as an argument, or the global fetch function if available, or the cross-fetch library if the global fetch function is not available.
+ *
+ * @param customFetch - An optional custom fetch function to use instead of the global fetch function.
+ * @returns A fetch function that can be used to make HTTP requests.
+ */
 export const resolveFetch = (customFetch?: Fetch): Fetch => {
   let _fetch: Fetch;
+
   if (customFetch) {
     _fetch = customFetch;
   } else if (typeof fetch === "undefined") {
@@ -11,9 +18,17 @@ export const resolveFetch = (customFetch?: Fetch): Fetch => {
   } else {
     _fetch = fetch;
   }
+
   return (...args) => _fetch(...args);
 };
 
+/**
+ * Resolves a fetch function that includes an "Authorization" header with the provided API key.
+ *
+ * @param apiKey - The API key to include in the "Authorization" header.
+ * @param customFetch - An optional custom fetch function to use instead of the global fetch function.
+ * @returns A fetch function that can be used to make HTTP requests with the provided API key in the "Authorization" header.
+ */
 export const fetchWithAuth = (apiKey: string, customFetch?: Fetch): Fetch => {
   const fetch = resolveFetch(customFetch);
   const HeadersConstructor = resolveHeadersConstructor();
@@ -29,6 +44,11 @@ export const fetchWithAuth = (apiKey: string, customFetch?: Fetch): Fetch => {
   };
 };
 
+/**
+ * Resolves the appropriate Response object to use, either the global Response object if available, or the Response object from the cross-fetch library if the global Response object is not available.
+ *
+ * @returns The appropriate Response object to use for making HTTP requests.
+ */
 export const resolveResponse = async () => {
   if (typeof Response === "undefined") {
     return (await import("cross-fetch")).Response;

package/src/lib/helpers.ts

@@ -1,4 +1,3 @@
-import { Headers as CrossFetchHeaders } from "cross-fetch";
 import {
   DeepgramClientOptions,
   FileSource,
@@ -6,7 +5,10 @@ import {
   UrlSource,
   TextSource,
   AnalyzeSource,
+  LiveSchema,
+  TranscriptionSchema,
 } from "./types";
+import { Headers as CrossFetchHeaders } from "cross-fetch";
 import { Readable } from "stream";
 import merge from "deepmerge";
 
@@ -14,14 +16,12 @@ export function stripTrailingSlash(url: string): string {
   return url.replace(/\/$/, "");
 }
 
-export const isBrowser = () => typeof window !== "undefined";
-export const isServer = () => typeof process !== "undefined";
+export function isBrowser() {
+  return typeof window !== "undefined" && typeof window.document !== "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 +83,94 @@ const isReadStreamSource = (providedSource: PrerecordedSource): providedSource i
 };
 
 export class CallbackUrl extends URL {
-  private callbackUrl = true;
+  public callbackUrl = true;
+}
+
+export const convertProtocolToWs = (url: string) => {
+  const convert = (string: string) => string.toLowerCase().replace(/^http/, "ws");
+
+  return convert(url);
+};
+
+export const buildRequestUrl = (
+  endpoint: string,
+  baseUrl: string | URL,
+  transcriptionOptions: LiveSchema | TranscriptionSchema
+): URL => {
+  const url = new URL(endpoint, baseUrl);
+  appendSearchParams(url.searchParams, transcriptionOptions);
+
+  return url;
+};
+
+export function isLiveSchema(arg: any): arg is LiveSchema {
+  return arg && typeof arg.interim_results !== "undefined";
+}
+
+export function isDeepgramClientOptions(arg: any): arg is DeepgramClientOptions {
+  return arg && typeof arg.global !== "undefined";
 }
+
+export const convertLegacyOptions = (optionsArg: DeepgramClientOptions): DeepgramClientOptions => {
+  const newOptions: DeepgramClientOptions = {};
+
+  if (optionsArg._experimentalCustomFetch) {
+    newOptions.global = {
+      fetch: {
+        client: optionsArg._experimentalCustomFetch,
+      },
+    };
+  }
+
+  optionsArg = merge(optionsArg, newOptions);
+
+  if (optionsArg.restProxy?.url) {
+    newOptions.global = {
+      fetch: {
+        options: {
+          proxy: {
+            url: optionsArg.restProxy?.url,
+          },
+        },
+      },
+    };
+  }
+
+  optionsArg = merge(optionsArg, newOptions);
+
+  if (optionsArg.global?.url) {
+    newOptions.global = {
+      fetch: {
+        options: {
+          url: optionsArg.global.url,
+        },
+      },
+      websocket: {
+        options: {
+          url: optionsArg.global.url,
+        },
+      },
+    };
+  }
+
+  optionsArg = merge(optionsArg, newOptions);
+
+  if (optionsArg.global?.headers) {
+    newOptions.global = {
+      fetch: {
+        options: {
+          headers: optionsArg.global?.headers,
+        },
+      },
+      websocket: {
+        options: {
+          _nodeOnlyHeaders: optionsArg.global?.headers,
+        },
+      },
+    };
+  }
+
+  optionsArg = merge(optionsArg, newOptions);
+
+  return optionsArg;
+};

package/src/lib/types/CreateProjectKeySchema.ts

@@ -12,5 +12,4 @@ interface CommonOptions extends Record<string, unknown> {
   comment: string;
   scopes: string[];
   tags?: string[];
-  [key: string]: unknown;
 }

package/src/lib/types/DeepgramClientOptions.ts

@@ -1,19 +1,83 @@
 import { Fetch, FetchOptions } from "./Fetch";
 
-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;
+export type IKeyFactory = () => string;
+export type IFetch = typeof fetch;
+export type IWebSocket = typeof WebSocket;
+
+interface TransportFetchOptions extends TransportOptions, FetchOptions {}
+interface TransportWebSocketOptions extends TransportOptions {
+  _nodeOnlyHeaders?: { [index: string]: any };
+}
+
+type TransportUrl = string;
+
+interface TransportOptions {
+  url?: TransportUrl;
+  proxy?: {
+    url: TransportUrl;
+  };
+}
+
+interface ITransport<C, O> {
+  client?: C;
+  options?: O;
+}
+
+export type DefaultNamespaceOptions = {
+  key: string;
+  fetch: {
+    options: { url: TransportUrl };
   };
+  websocket: {
+    options: { url: TransportUrl };
+  };
+} & NamespaceOptions;
+
+export interface NamespaceOptions {
+  key?: string;
+  fetch?: ITransport<IFetch, TransportFetchOptions>;
+  websocket?: ITransport<IWebSocket, TransportWebSocketOptions>;
+}
+
+export type DefaultClientOptions = {
+  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;
   };

package/src/lib/types/Fetch.ts

@@ -1,27 +1,5 @@
 export type Fetch = typeof fetch;
 
-export interface FetchOptions {
-  method?: RequestMethodType;
-  headers?: Record<string, string>;
-  cache?: "default" | "no-cache" | "reload" | "force-cache" | "only-if-cached"; // default, no-cache, reload, force-cache, only-if-cached
-  credentials?: "include" | "same-origin" | "omit"; // include, same-origin, omit
-  redirect?: "manual" | "follow" | "error"; // manual, follow, error
-  referrerPolicy?: // no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin, same-origin, strict-origin, strict-origin-when-cross-origin, unsafe-url
-  | "no-referrer"
-    | "no-referrer-when-downgrade"
-    | "origin"
-    | "origin-when-cross-origin"
-    | "same-origin"
-    | "strict-origin"
-    | "strict-origin-when-cross-origin"
-    | "unsafe-url";
-}
+export type FetchOptions = RequestInit & { method?: RequestMethodType; duplex?: string };
 
-export type RequestMethodType = "GET" | "POST" | "PUT" | "DELETE" | "PATCH"; // GET, POST, PUT, DELETE, etc.
-
-export interface FetchParameters {
-  /**
-   * Pass in an AbortController's signal to cancel the request.
-   */
-  signal?: AbortSignal;
-}
+export type RequestMethodType = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";

package/src/lib/types/LiveConfigOptions.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">>;

package/src/lib/types/SyncPrerecordedResponse.ts

@@ -90,6 +90,7 @@ interface Paragraph {
   start: number;
   end: number;
   num_words: number;
+  speaker?: number;
 }
 
 interface ParagraphGroup {

package/src/lib/types/TranscriptionSchema.ts

@@ -138,8 +138,6 @@ interface TranscriptionSchema extends Record<string, unknown> {
    * @see https://developers.deepgram.com/docs/extra-metadata
    */
   extra?: string[] | string;
-
-  [key: string]: unknown;
 }
 
 interface PrerecordedSchema extends TranscriptionSchema {

package/src/lib/types/UpdateProjectMemberScopeSchema.ts

@@ -1,3 +1,3 @@
-export interface UpdateProjectMemberScopeSchema {
+export interface UpdateProjectMemberScopeSchema extends Record<string, unknown> {
   scope: string;
 }

package/src/lib/types/UpdateProjectSchema.ts

@@ -1,5 +1,4 @@
 export interface UpdateProjectSchema extends Record<string, unknown> {
   name?: string;
   company?: string;
-  [key: string]: unknown;
 }

package/src/lib/types/index.ts

@@ -1,54 +1,39 @@
-export type { AnalyzeSchema } from "./AnalyzeSchema";
-export type { AsyncPrerecordedResponse } from "./AsyncPrerecordedResponse";
-export type { AsyncAnalyzeResponse } from "./AsyncAnalyzeResponse";
-export type { CreateOnPremCredentialsSchema } from "./CreateOnPremCredentialsSchema";
-export type { CreateProjectKeySchema } from "./CreateProjectKeySchema";
-export type { CreateProjectKeyResponse } from "./CreateProjectKeyResponse";
-export type { DeepgramClientOptions } from "./DeepgramClientOptions";
-export type { DeepgramResponse } from "./DeepgramResponse";
-export type { Fetch } from "./Fetch";
-export type {
-  GetProjectBalanceResponse,
-  GetProjectBalancesResponse,
-} from "./GetProjectBalancesResponse";
-export type { GetProjectInvitesResponse } from "./GetProjectInvitesResponse";
-export type { GetProjectKeyResponse, GetProjectKeysResponse } from "./GetProjectKeysResponse";
-export type { GetProjectMemberScopesResponse } from "./GetProjectMemberScopesResponse";
-export type { GetProjectMembersResponse } from "./GetProjectMembersResponse";
-export type { GetProjectResponse } from "./GetProjectResponse";
-export type { GetProjectsResponse } from "./GetProjectsResponse";
-export type { GetProjectUsageFieldsSchema } from "./GetProjectUsageFieldsSchema";
-export type { GetProjectUsageFieldsResponse } from "./GetProjectUsageFieldsResponse";
-export type {
-  GetProjectUsageRequestResponse,
-  GetProjectUsageRequestsResponse,
-} from "./GetProjectUsageRequestsResponse";
-export type { GetProjectUsageRequestsSchema } from "./GetProjectUsageRequestsSchema";
-export type { GetProjectUsageSummarySchema } from "./GetProjectUsageSummarySchema";
-export type { GetProjectUsageSummaryResponse } from "./GetProjectUsageSummaryResponse";
-export type { GetTokenDetailsResponse } from "./GetTokenDetailsResponse";
-export type {
-  ListOnPremCredentialsResponse,
-  OnPremCredentialResponse,
-} from "./ListOnPremCredentialsResponse";
-export type { LiveConfigOptions } from "./LiveConfigOptions";
-export type { LiveMetadataEvent } from "./LiveMetadataEvent";
-export type { LiveTranscriptionEvent } from "./LiveTranscriptionEvent";
-export type { MessageResponse } from "./MessageResponse";
-export type {
-  FileSource,
-  PrerecordedSource,
-  UrlSource,
-  TextSource,
-  AnalyzeSource,
-} from "./DeepgramSource";
-export type { SendProjectInviteSchema } from "./SendProjectInviteSchema";
-export type { SpeakSchema } from "./SpeakSchema";
-export type { SpeechStartedEvent } from "./SpeechStartedEvent";
-export type { SyncPrerecordedResponse } from "./SyncPrerecordedResponse";
-export type { SyncAnalyzeResponse } from "./SyncAnalyzeResponse";
-export type { TranscriptionSchema, PrerecordedSchema, LiveSchema } from "./TranscriptionSchema";
-export type { UpdateProjectMemberScopeSchema } from "./UpdateProjectMemberScopeSchema";
-export type { UpdateProjectSchema } from "./UpdateProjectSchema";
-export type { UtteranceEndEvent } from "./UtteranceEndEvent";
-export type { VoidResponse } from "./VoidResponse";
+export * from "./AnalyzeSchema";
+export * from "./AsyncAnalyzeResponse";
+export * from "./AsyncPrerecordedResponse";
+export * from "./CreateOnPremCredentialsSchema";
+export * from "./CreateProjectKeyResponse";
+export * from "./CreateProjectKeySchema";
+export * from "./DeepgramClientOptions";
+export * from "./DeepgramResponse";
+export * from "./DeepgramSource";
+export * from "./Fetch";
+export * from "./GetProjectBalancesResponse";
+export * from "./GetProjectInvitesResponse";
+export * from "./GetProjectKeysResponse";
+export * from "./GetProjectMemberScopesResponse";
+export * from "./GetProjectMembersResponse";
+export * from "./GetProjectResponse";
+export * from "./GetProjectsResponse";
+export * from "./GetProjectUsageFieldsResponse";
+export * from "./GetProjectUsageFieldsSchema";
+export * from "./GetProjectUsageRequestsResponse";
+export * from "./GetProjectUsageRequestsSchema";
+export * from "./GetProjectUsageSummaryResponse";
+export * from "./GetProjectUsageSummarySchema";
+export * from "./GetTokenDetailsResponse";
+export * from "./ListOnPremCredentialsResponse";
+export * from "./LiveConfigOptions";
+export * from "./LiveMetadataEvent";
+export * from "./LiveTranscriptionEvent";
+export * from "./MessageResponse";
+export * from "./SendProjectInviteSchema";
+export * from "./SpeakSchema";
+export * from "./SpeechStartedEvent";
+export * from "./SyncAnalyzeResponse";
+export * from "./SyncPrerecordedResponse";
+export * from "./TranscriptionSchema";
+export * from "./UpdateProjectMemberScopeSchema";
+export * from "./UpdateProjectSchema";
+export * from "./UtteranceEndEvent";
+export * from "./VoidResponse";

package/src/lib/version.ts

@@ -1 +1 @@
-export const version = "3.3.4";
+export const version = "3.4.0";