@deepgram/sdk 3.0.0-alpha.9 → 3.0.0-beta.1

package/src/lib/constants.ts

@@ -1,7 +1,9 @@
 import { isBrowser } from "./helpers";
+import { FetchOptions } from "./types/Fetch";
 import { version } from "./version";
 
 export const DEFAULT_HEADERS = {
+  "Content-Type": `application/json`,
   "X-Client-Info": `@deepgram/sdk; ${isBrowser() ? "browser" : "server"}; v${version}`,
   "User-Agent": `@deepgram/sdk/${version}`,
 };
@@ -10,9 +12,13 @@ export const DEFAULT_URL = "api.deepgram.com";
 
 export const DEFAULT_GLOBAL_OPTIONS = {
   url: DEFAULT_URL,
+};
+
+export const DEFAULT_FETCH_OPTIONS: FetchOptions = {
   headers: DEFAULT_HEADERS,
 };
 
 export const DEFAULT_OPTIONS = {
   global: DEFAULT_GLOBAL_OPTIONS,
+  fetch: DEFAULT_FETCH_OPTIONS,
 };

package/src/lib/helpers.ts

@@ -1,6 +1,7 @@
 import { Headers as CrossFetchHeaders } from "cross-fetch";
 import { DeepgramClientOptions, FileSource, PrerecordedSource, UrlSource } from "./types";
 import { Readable } from "stream";
+import merge from "deepmerge";
 
 export function stripTrailingSlash(url: string): string {
   return url.replace(/\/$/, "");
@@ -12,16 +13,7 @@ export function applySettingDefaults(
   options: DeepgramClientOptions,
   defaults: DeepgramClientOptions
 ): DeepgramClientOptions {
-  const { global: globalOptions } = options;
-
-  const { global: DEFAULT_GLOBAL_OPTIONS } = defaults;
-
-  return {
-    global: {
-      ...DEFAULT_GLOBAL_OPTIONS,
-      ...globalOptions,
-    },
-  };
+  return merge(defaults, options);
 }
 
 export function appendSearchParams(

package/src/lib/types/DeepgramClientOptions.ts

@@ -1,5 +1,7 @@
+import { FetchOptions } from "./Fetch";
+
 export interface DeepgramClientOptions {
-  global: {
+  global?: {
     /**
      * Optional headers for initializing the client.
      */
@@ -10,4 +12,8 @@ export interface DeepgramClientOptions {
      */
     url?: string;
   };
+  fetch?: FetchOptions;
+  restProxy?: {
+    url: null | string;
+  };
 }

package/src/lib/types/Fetch.ts

@@ -1,13 +1,23 @@
 export type Fetch = typeof fetch;
 
 export interface FetchOptions {
-  headers?: {
-    [key: string]: string;
-  };
-  noResolveJson?: boolean;
+  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 RequestMethodType = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+export type RequestMethodType = "GET" | "POST" | "PUT" | "DELETE" | "PATCH"; // GET, POST, PUT, DELETE, etc.
 
 export interface FetchParameters {
   /**

package/src/lib/types/GetProjectBalancesResponse.ts

@@ -1,5 +1,5 @@
 export interface GetProjectBalancesResponse {
-  balances: [GetProjectBalanceResponse];
+  balances: GetProjectBalanceResponse[];
 }
 
 export interface GetProjectBalanceResponse {

package/src/lib/types/GetProjectInvitesResponse.ts

@@ -1,5 +1,5 @@
 export interface GetProjectInvitesResponse {
-  invites: [Invite];
+  invites: Invite[];
 }
 
 interface Invite {

package/src/lib/types/GetProjectKeysResponse.ts

@@ -1,5 +1,5 @@
 export interface GetProjectKeysResponse {
-  api_keys: [GetProjectKeyResponse];
+  api_keys: GetProjectKeyResponse[];
 }
 
 export interface GetProjectKeyResponse {

package/src/lib/types/GetProjectMembersResponse.ts

@@ -1,5 +1,5 @@
 export interface GetProjectMembersResponse {
-  members: [Member];
+  members: Member[];
 }
 
 interface Member {

package/src/lib/types/GetProjectUsageFieldsResponse.ts

@@ -1,6 +1,6 @@
 export interface GetProjectUsageFieldsResponse {
   tags: string[];
-  models: [UsageModel];
+  models: UsageModel[];
   processing_methods: string[];
   languages: string[];
   features: string[];

package/src/lib/types/GetProjectUsageRequestsResponse.ts

@@ -1,7 +1,7 @@
 export interface GetProjectUsageRequestsResponse {
   page: number;
   limit: number;
-  requests: [GetProjectUsageRequestResponse];
+  requests: GetProjectUsageRequestResponse[];
 }
 
 export interface GetProjectUsageRequestResponse {

package/src/lib/types/GetProjectUsageSummaryResponse.ts

@@ -5,7 +5,7 @@ export interface GetProjectUsageSummaryResponse {
     units: string;
     amount: number;
   };
-  results: [UsageSummary];
+  results: UsageSummary[];
 }
 
 interface UsageSummary {

package/src/lib/types/GetProjectsResponse.ts

@@ -1,5 +1,5 @@
 export interface GetProjectsResponse {
-  projects: [Project];
+  projects: Project[];
 }
 
 interface Project {

package/src/lib/types/ListOnPremCredentialsResponse.ts

@@ -1,5 +1,5 @@
 export interface ListOnPremCredentialsResponse {
-  distribution_credentials: [OnPremCredentialResponse];
+  distribution_credentials: OnPremCredentialResponse[];
 }
 
 export interface OnPremCredentialResponse {

package/src/lib/types/LiveTranscriptionEvent.ts

@@ -6,21 +6,17 @@ export interface LiveTranscriptionEvent {
   is_final?: boolean;
   speech_final?: boolean;
   channel: {
-    alternatives: [
-      {
-        transcript: string;
-        confidence: boolean;
-        words: [
-          {
-            word: string;
-            start: number;
-            end: number;
-            confidence: number;
-            punctuated_word: string;
-          }
-        ];
-      }
-    ];
+    alternatives: {
+      transcript: string;
+      confidence: boolean;
+      words: {
+        word: string;
+        start: number;
+        end: number;
+        confidence: number;
+        punctuated_word: string;
+      }[];
+    }[];
   };
   metadata: {
     request_id: string;

package/src/lib/types/SyncPrerecordedResponse.ts

@@ -6,17 +6,17 @@ export interface SyncPrerecordedResponse {
 interface Alternative {
   transcript: string;
   confidence: number;
-  words: Array<WordBase>;
-  summaries?: Array<Summary>;
+  words: WordBase[];
+  summaries?: Summary[];
   paragraphs?: ParagraphGroup;
-  entities?: Array<Entity>;
-  translations?: Array<Translation>;
-  topics?: Array<TopicGroup>;
+  entities?: Entity[];
+  translations?: Translation[];
+  topics?: TopicGroup[];
 }
 
 interface Channel {
-  search?: Array<Search>;
-  alternatives: Array<Alternative>;
+  search?: Search[];
+  alternatives: Alternative[];
   detected_language?: string;
 }
 
@@ -42,9 +42,9 @@ interface Metadata {
   created: string;
   duration: number;
   channels: number;
-  models: Array<string>;
+  models: string[];
   model_info: Record<string, ModelInfo>;
-  warnings?: Array<Warning>;
+  warnings?: Warning[];
 }
 
 interface ModelInfo {
@@ -54,7 +54,7 @@ interface ModelInfo {
 }
 
 interface Paragraph {
-  sentences: Array<Sentence>;
+  sentences: Sentence[];
   start: number;
   end: number;
   num_words: number;
@@ -62,18 +62,18 @@ interface Paragraph {
 
 interface ParagraphGroup {
   transcript: string;
-  paragraphs: Array<Paragraph>;
+  paragraphs: Paragraph[];
 }
 
 interface Result {
-  channels: Array<Channel>;
-  utterances?: Array<Utterance>;
+  channels: Channel[];
+  utterances?: Utterance[];
   summary?: TranscriptionSummary;
 }
 
 interface Search {
   query: string;
-  hits: Array<Hit>;
+  hits: Hit[];
 }
 
 interface Sentence {
@@ -98,7 +98,7 @@ interface Topic {
 }
 
 interface TopicGroup {
-  topics: Array<Topic>;
+  topics: Topic[];
   text: string;
   start_word: number;
   end_word: number;
@@ -115,7 +115,7 @@ interface Utterance {
   confidence: number;
   channel: number;
   transcript: string;
-  words: Array<WordBase>;
+  words: WordBase[];
   speaker?: number;
   id: string;
 }

package/src/lib/types/TranscriptionSchema.ts

@@ -35,7 +35,7 @@ interface TranscriptionSchema extends Record<string, unknown> {
   /**
    * @see https://developers.deepgram.com/docs/redaction
    */
-  redact?: Array<string> | string | boolean;
+  redact?: string[] | string | boolean;
 
   /**
    * @see https://developers.deepgram.com/docs/diarization
@@ -81,7 +81,7 @@ interface TranscriptionSchema extends Record<string, unknown> {
   /**
    * @see https://developers.deepgram.com/docs/tagging
    */
-  tag?: Array<string>;
+  tag?: string[];
 
   [key: string]: unknown;
 }

package/src/lib/version.ts

@@ -1 +1 @@
-export const version = "3.0.0-alpha.9";
+export const version = "3.0.0-beta.1";

package/src/packages/AbstractClient.ts

@@ -0,0 +1,57 @@
+import { DEFAULT_OPTIONS, DEFAULT_URL } from "../lib/constants";
+import { applySettingDefaults, stripTrailingSlash } from "../lib/helpers";
+import { DeepgramClientOptions } from "../lib/types";
+
+/**
+ * Deepgram Client.
+ *
+ * An isomorphic Javascript client for interacting with the Deepgram API.
+ * @see https://developers.deepgram.com
+ */
+export abstract class AbstractClient {
+  protected baseUrl: URL;
+
+  constructor(protected key: string, protected options: DeepgramClientOptions) {
+    this.key = key;
+
+    if (!key) {
+      this.key = process.env.DEEPGRAM_API_KEY as string;
+    }
+
+    if (!this.key) {
+      throw new Error("A deepgram API key is required");
+    }
+
+    this.options = applySettingDefaults(options, DEFAULT_OPTIONS);
+
+    if (!this.options.global?.url) {
+      throw new Error(
+        `An API URL is required. It should be set to ${DEFAULT_URL} by default. No idea what happened!`
+      );
+    }
+
+    if (this.willProxy()) {
+      this.baseUrl = this.resolveBaseUrl(this.options.restProxy?.url as string);
+
+      if (this.options.global.headers) {
+        this.options.global.headers["X-Deepgram-Proxy"] = this.options.global.url;
+      }
+    } else {
+      this.baseUrl = this.resolveBaseUrl(this.options.global.url);
+    }
+  }
+
+  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;
+  }
+}

package/src/packages/AbstractRestfulClient.ts

@@ -1,18 +1,24 @@
-import { DeepgramApiError, DeepgramUnknownError } from "../lib/errors";
+import { DeepgramApiError, DeepgramError, DeepgramUnknownError } from "../lib/errors";
 import { Readable } from "stream";
 import { fetchWithAuth, resolveResponse } from "../lib/fetch";
-import type { Fetch, FetchOptions, FetchParameters, RequestMethodType } from "../lib/types/Fetch";
+import type { Fetch, FetchParameters, RequestMethodType } from "../lib/types/Fetch";
+import { AbstractClient } from "./AbstractClient";
+import { DeepgramClientOptions } from "../lib/types";
+import { isBrowser } from "../lib/helpers";
 
-export class AbstractRestfulClient {
-  protected baseUrl: URL;
-  protected headers: Record<string, string>;
+export abstract class AbstractRestfulClient extends AbstractClient {
   protected fetch: Fetch;
 
-  constructor(baseUrl: URL, headers: Record<string, string>, apiKey: string) {
-    this.baseUrl = baseUrl;
-    this.headers = headers;
+  constructor(protected key: string, protected options: DeepgramClientOptions) {
+    super(key, options);
 
-    this.fetch = fetchWithAuth(apiKey);
+    if (isBrowser() && !this.willProxy()) {
+      throw new DeepgramError(
+        "Due to CORS we are unable to support REST-based API calls to our API from the browser. Please consider using a proxy, and including a `restProxy: { url: ''}` in your Deepgram client options."
+      );
+    }
+
+    this.fetch = fetchWithAuth(this.key);
   }
 
   protected _getErrorMessage(err: any): string {
@@ -38,35 +44,38 @@ export class AbstractRestfulClient {
 
   protected _getRequestParams(
     method: RequestMethodType,
-    options?: FetchOptions,
+    headers?: Record<string, string>,
     parameters?: FetchParameters,
     body?: string | Buffer | Readable
   ) {
-    const params: { [k: string]: any } = { method, headers: options?.headers || {} };
+    const params: { [k: string]: any } = {
+      ...this.options?.fetch,
+      method,
+      headers: { ...this.options?.fetch?.headers, ...headers } || {},
+    };
 
     if (method === "GET") {
       return params;
     }
 
-    params.headers = { "Content-Type": "application/json", ...options?.headers };
     params.body = body;
+    params.duplex = "half";
 
-    return { ...params, ...parameters, duplex: "half" };
+    return { ...params, ...parameters };
   }
 
   protected async _handleRequest(
     fetcher: Fetch,
     method: RequestMethodType,
     url: string | URL,
-    options?: FetchOptions,
+    headers?: Record<string, string>,
     parameters?: FetchParameters,
     body?: string | Buffer | Readable
   ): Promise<any> {
     return new Promise((resolve, reject) => {
-      fetcher(url, this._getRequestParams(method, options, parameters, body))
+      fetcher(url, this._getRequestParams(method, headers, parameters, body))
         .then((result) => {
           if (!result.ok) throw result;
-          if (options?.noResolveJson) return result;
           return result.json();
         })
         .then((data) => resolve(data))
@@ -77,48 +86,48 @@ export class AbstractRestfulClient {
   protected async get(
     fetcher: Fetch,
     url: string | URL,
-    options?: FetchOptions,
+    headers?: Record<string, string>,
     parameters?: FetchParameters
   ): Promise<any> {
-    return this._handleRequest(fetcher, "GET", url, options, parameters);
+    return this._handleRequest(fetcher, "GET", url, headers, parameters);
   }
 
   protected async post(
     fetcher: Fetch,
     url: string | URL,
     body: string | Buffer | Readable,
-    options?: FetchOptions,
+    headers?: Record<string, string>,
     parameters?: FetchParameters
   ): Promise<any> {
-    return this._handleRequest(fetcher, "POST", url, options, parameters, body);
+    return this._handleRequest(fetcher, "POST", url, headers, parameters, body);
   }
 
   protected async put(
     fetcher: Fetch,
     url: string | URL,
     body: string | Buffer | Readable,
-    options?: FetchOptions,
+    headers?: Record<string, string>,
     parameters?: FetchParameters
   ): Promise<any> {
-    return this._handleRequest(fetcher, "PUT", url, options, parameters, body);
+    return this._handleRequest(fetcher, "PUT", url, headers, parameters, body);
   }
 
   protected async patch(
     fetcher: Fetch,
     url: string | URL,
     body: string | Buffer | Readable,
-    options?: FetchOptions,
+    headers?: Record<string, string>,
     parameters?: FetchParameters
   ): Promise<any> {
-    return this._handleRequest(fetcher, "PATCH", url, options, parameters, body);
+    return this._handleRequest(fetcher, "PATCH", url, headers, parameters, body);
   }
 
   protected async delete(
     fetcher: Fetch,
     url: string | URL,
-    options?: FetchOptions,
+    headers?: Record<string, string>,
     parameters?: FetchParameters
   ): Promise<any> {
-    return this._handleRequest(fetcher, "DELETE", url, options, parameters);
+    return this._handleRequest(fetcher, "DELETE", url, headers, parameters);
   }
 }

package/src/packages/AbstractWsClient.ts

@@ -0,0 +1,42 @@
+import { EventEmitter } from "events";
+import { DEFAULT_OPTIONS, DEFAULT_URL } from "../lib/constants";
+import { applySettingDefaults, stripTrailingSlash } from "../lib/helpers";
+import { DeepgramClientOptions } from "../lib/types";
+
+export abstract class AbstractWsClient extends EventEmitter {
+  protected baseUrl: URL;
+
+  constructor(
+    protected key: string,
+    protected options: DeepgramClientOptions | undefined = DEFAULT_OPTIONS
+  ) {
+    super();
+
+    this.key = key;
+
+    if (!key) {
+      this.key = process.env.DEEPGRAM_API_KEY as string;
+    }
+
+    if (!this.key) {
+      throw new Error("A deepgram API key is required");
+    }
+
+    this.options = applySettingDefaults(options, DEFAULT_OPTIONS);
+
+    if (!this.options.global?.url) {
+      throw new Error(
+        `An API URL is required. It should be set to ${DEFAULT_URL} by default. No idea what happened!`
+      );
+    }
+
+    let url = this.options.global.url;
+
+    if (!/^https?:\/\//i.test(url)) {
+      url = "https://" + url;
+    }
+
+    this.baseUrl = new URL(stripTrailingSlash(url));
+    this.baseUrl.protocol = this.baseUrl.protocol.toLowerCase().replace(/(http)(s)?/gi, "ws$2");
+  }
+}

package/src/packages/ListenClient.ts

@@ -1,23 +1,14 @@
-import { PrerecordedClient } from "./PrerecordedClient";
+import { AbstractClient } from "./AbstractClient";
 import { LiveClient } from "./LiveClient";
 import { LiveSchema } from "../lib/types";
+import { PrerecordedClient } from "./PrerecordedClient";
 
-export class ListenClient {
-  protected baseUrl: URL;
-  protected headers: Record<string, string>;
-  protected key: string;
-
-  constructor(baseUrl: URL, headers: Record<string, string>, apiKey: string) {
-    this.baseUrl = baseUrl;
-    this.headers = headers;
-    this.key = apiKey;
-  }
-
+export class ListenClient extends AbstractClient {
   get prerecorded() {
-    return new PrerecordedClient(this.baseUrl, this.headers, this.key);
+    return new PrerecordedClient(this.key, this.options);
   }
 
-  public live(options: LiveSchema, endpoint = "v1/listen") {
-    return new LiveClient(this.baseUrl, this.key, options, endpoint);
+  public live(transcriptionOptions: LiveSchema, endpoint = "v1/listen") {
+    return new LiveClient(this.key, this.options, transcriptionOptions, endpoint);
   }
 }