@deepgram/sdk 2.4.0 → 3.0.0-alpha.2

package/src/lib/types/TranscriptionOptions.ts

@@ -0,0 +1,158 @@
+/**
+ * Options for transcription
+ */
+interface TranscriptionOptions extends Record<string, unknown> {
+  /**
+   * @see https://developers.deepgram.com/docs/model
+   */
+  model?: string;
+
+  /**
+   * @see https://developers.deepgram.com/docs/tier
+   */
+  tier?: string;
+
+  /**
+   * @see https://developers.deepgram.com/docs/version
+   */
+  version?: string;
+
+  /**
+   * @see https://developers.deepgram.com/docs/language
+   */
+  language?: string;
+
+  /**
+   * @see https://developers.deepgram.com/docs/punctuation
+   */
+  punctuate?: boolean;
+
+  /**
+   * @see https://developers.deepgram.com/docs/profanity-filter
+   */
+  profanity_filter?: boolean;
+
+  /**
+   * @see https://developers.deepgram.com/docs/redaction
+   */
+  redact?: Array<string> | Array<boolean> | boolean;
+
+  /**
+   * @see https://developers.deepgram.com/docs/diarization
+   */
+  diarize?: boolean;
+
+  /**
+   * @see https://developers.deepgram.com/docs/smart-format
+   */
+  smart_format?: boolean;
+
+  /**
+   * @see https://developers.deepgram.com/docs/multichannel
+   */
+  multichannel?: boolean;
+
+  /**
+   * @see https://developers.deepgram.com/docs/numerals
+   * @deprecated
+   */
+  numerals?: boolean;
+
+  /**
+   * @see https://developers.deepgram.com/docs/search
+   */
+  search?: string[] | string;
+
+  /**
+   * @see https://developers.deepgram.com/docs/find-and-replace
+   */
+  replace?: string[] | string;
+
+  /**
+   * @see https://developers.deepgram.com/docs/callback
+   */
+  callback?: string;
+
+  /**
+   * @see https://developers.deepgram.com/docs/keywords
+   */
+  keywords?: string[] | string;
+
+  /**
+   * @see https://developers.deepgram.com/docs/tagging
+   */
+  tag?: Array<string>;
+
+  [key: string]: unknown;
+}
+
+interface PrerecordedOptions extends TranscriptionOptions {
+  /**
+   * @see https://developers.deepgram.com/docs/detect-entities
+   */
+  detect_entities?: boolean;
+
+  /**
+   * @see https://developers.deepgram.com/docs/language-detection
+   */
+  detect_language?: boolean;
+
+  /**
+   * @see https://developers.deepgram.com/docs/topic-detection
+   */
+  detect_topics?: boolean;
+
+  /**
+   * Undocumented feature.
+   */
+  alternatives?: number;
+
+  /**
+   * @see https://developers.deepgram.com/docs/paragraphs
+   */
+  paragraphs?: boolean;
+
+  /**
+   * @see https://developers.deepgram.com/docs/summarization
+   */
+  summarize?: boolean | string;
+
+  /**
+   * @see https://developers.deepgram.com/docs/utterances
+   */
+  utterances?: boolean;
+
+  /**
+   * @see https://developers.deepgram.com/docs/utterance-split
+   */
+  utt_split?: number;
+}
+
+interface LiveOptions extends TranscriptionOptions {
+  /**
+   * @see https://developers.deepgram.com/docs/channels
+   */
+  channels?: number;
+
+  /**
+   * @see https://developers.deepgram.com/docs/encoding
+   */
+  encoding?: string;
+
+  /**
+   * @see https://developers.deepgram.com/docs/sample-rate
+   */
+  sample_rate?: number;
+
+  /**
+   * @see https://developers.deepgram.com/docs/endpointing
+   */
+  endpointing?: number;
+
+  /**
+   * @see https://developers.deepgram.com/docs/interim-results
+   */
+  interim_results?: boolean;
+}
+
+export type { TranscriptionOptions, PrerecordedOptions, LiveOptions };

package/src/lib/types/UpdateProjectMemberScopeOptions.ts

@@ -0,0 +1,3 @@
+export interface UpdateProjectMemberScopeOptions {
+  scope: string;
+}

package/src/lib/types/UpdateProjectOptions.ts

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

package/src/lib/types/VoidResponse.ts

@@ -0,0 +1,11 @@
+import { DeepgramError } from "../errors";
+
+export type VoidResponse = SuccessResponse | ErrorResponse;
+
+interface SuccessResponse {
+  error: null;
+}
+
+interface ErrorResponse {
+  error: DeepgramError;
+}

package/src/lib/types/index.ts

@@ -0,0 +1,47 @@
+export type { AsyncPrerecordedResponse } from "./AsyncPrerecordedResponse";
+export type { CreateOnPremCredentialsOptions } from "./CreateOnPremCredentialsOptions";
+export type { CreateProjectKeyOptions } from "./CreateProjectKeyOptions";
+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 { GetProjectUsageFieldsOptions } from "./GetProjectUsageFieldsOptions";
+export type { GetProjectUsageFieldsResponse } from "./GetProjectUsageFieldsResponse";
+export type {
+  GetProjectUsageRequestResponse,
+  GetProjectUsageRequestsResponse,
+} from "./GetProjectUsageRequestsResponse";
+export type { GetProjectUsageRequestsOptions } from "./GetProjectUsageRequestsOptions";
+export type { GetProjectUsageSummaryOptions } from "./GetProjectUsageSummaryOptions";
+export type { GetProjectUsageSummaryResponse } from "./GetProjectUsageSummaryResponse";
+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 {
+  BufferSource,
+  FileSource,
+  PrerecordedSource,
+  ReadStreamSource,
+  UrlSource,
+} from "./PrerecordedSource";
+export type { SendProjectInviteOptions } from "./SendProjectInviteOptions";
+export type { SyncPrerecordedResponse } from "./SyncPrerecordedResponse";
+export type { TranscriptionOptions, PrerecordedOptions, LiveOptions } from "./TranscriptionOptions";
+export type { UpdateProjectMemberScopeOptions } from "./UpdateProjectMemberScopeOptions";
+export type { UpdateProjectOptions } from "./UpdateProjectOptions";
+export type { VoidResponse } from "./VoidResponse";

package/src/lib/version.ts

@@ -0,0 +1 @@
+export const version = "3.0.0-alpha.2";

package/src/packages/AbstractRestfulClient.ts

@@ -0,0 +1,123 @@
+import { DeepgramApiError, DeepgramUnknownError } from "../lib/errors";
+import { Readable } from "stream";
+import { fetchWithAuth, resolveResponse } from "../lib/fetch";
+import type { Fetch, FetchOptions, FetchParameters, RequestMethodType } from "../lib/types/Fetch";
+
+export class AbstractRestfulClient {
+  protected baseUrl: URL;
+  protected headers: Record<string, string>;
+  protected fetch: Fetch;
+
+  constructor(baseUrl: URL, headers: Record<string, string>, apiKey: string) {
+    this.baseUrl = baseUrl;
+    this.headers = headers;
+
+    this.fetch = fetchWithAuth(apiKey);
+  }
+
+  protected _getErrorMessage(err: any): string {
+    return err.msg || err.message || err.error_description || err.error || JSON.stringify(err);
+  }
+
+  protected async handleError(error: unknown, reject: (reason?: any) => void) {
+    const Res = await resolveResponse();
+
+    if (error instanceof Res) {
+      error
+        .json()
+        .then((err) => {
+          reject(new DeepgramApiError(this._getErrorMessage(err), error.status || 500));
+        })
+        .catch((err) => {
+          reject(new DeepgramUnknownError(this._getErrorMessage(err), err));
+        });
+    } else {
+      reject(new DeepgramUnknownError(this._getErrorMessage(error), error));
+    }
+  }
+
+  protected _getRequestParams(
+    method: RequestMethodType,
+    options?: FetchOptions,
+    parameters?: FetchParameters,
+    body?: string | Buffer | Readable
+  ) {
+    const params: { [k: string]: any } = { method, headers: options?.headers || {} };
+
+    if (method === "GET") {
+      return params;
+    }
+
+    params.headers = { "Content-Type": "application/json", ...options?.headers };
+    params.body = body;
+    return { ...params, ...parameters, duplex: "half" };
+  }
+
+  protected async _handleRequest(
+    fetcher: Fetch,
+    method: RequestMethodType,
+    url: string | URL,
+    options?: FetchOptions,
+    parameters?: FetchParameters,
+    body?: string | Buffer | Readable
+  ): Promise<any> {
+    return new Promise((resolve, reject) => {
+      fetcher(url, this._getRequestParams(method, options, parameters, body))
+        .then((result) => {
+          if (!result.ok) throw result;
+          if (options?.noResolveJson) return result;
+          return result.json();
+        })
+        .then((data) => resolve(data))
+        .catch((error) => this.handleError(error, reject));
+    });
+  }
+
+  protected async get(
+    fetcher: Fetch,
+    url: string | URL,
+    options?: FetchOptions,
+    parameters?: FetchParameters
+  ): Promise<any> {
+    return this._handleRequest(fetcher, "GET", url, options, parameters);
+  }
+
+  protected async post(
+    fetcher: Fetch,
+    url: string | URL,
+    body: string | Buffer | Readable,
+    options?: FetchOptions,
+    parameters?: FetchParameters
+  ): Promise<any> {
+    return this._handleRequest(fetcher, "POST", url, options, parameters, body);
+  }
+
+  protected async put(
+    fetcher: Fetch,
+    url: string | URL,
+    body: string | Buffer | Readable,
+    options?: FetchOptions,
+    parameters?: FetchParameters
+  ): Promise<any> {
+    return this._handleRequest(fetcher, "PUT", url, options, parameters, body);
+  }
+
+  protected async patch(
+    fetcher: Fetch,
+    url: string | URL,
+    body: string | Buffer | Readable,
+    options?: FetchOptions,
+    parameters?: FetchParameters
+  ): Promise<any> {
+    return this._handleRequest(fetcher, "PATCH", url, options, parameters, body);
+  }
+
+  protected async delete(
+    fetcher: Fetch,
+    url: string | URL,
+    options?: FetchOptions,
+    parameters?: FetchParameters
+  ): Promise<any> {
+    return this._handleRequest(fetcher, "DELETE", url, options, parameters);
+  }
+}

package/src/packages/ListenClient.ts

@@ -0,0 +1,23 @@
+import { PrerecordedClient } from "./PrerecordedClient";
+import { LiveClient } from "./LiveClient";
+import { LiveOptions } from "../lib/types";
+
+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;
+  }
+
+  get prerecorded() {
+    return new PrerecordedClient(this.baseUrl, this.headers, this.key);
+  }
+
+  public live(options: LiveOptions, endpoint = "v1/listen") {
+    return new LiveClient(this.baseUrl, this.key, options, endpoint);
+  }
+}

package/src/packages/LiveClient.ts

@@ -0,0 +1,143 @@
+import { EventEmitter } from "events";
+import { appendSearchParams, isBrowser } from "../lib/helpers";
+import WebSocket from "modern-isomorphic-ws";
+import { LiveConnectionState, LiveTranscriptionEvents } from "../lib/enums";
+import type {
+  LiveOptions,
+  LiveConfigOptions,
+  LiveMetadataEvent,
+  LiveTranscriptionEvent,
+} from "../lib/types";
+import { DEFAULT_HEADERS } from "../lib/constants";
+
+export class LiveClient extends EventEmitter {
+  private _socket: WebSocket;
+
+  constructor(baseUrl: URL, apiKey: string, options: LiveOptions, endpoint = "v1/listen") {
+    super();
+
+    const transcriptionOptions: LiveOptions = { ...{}, ...options };
+    const url = new URL(endpoint, baseUrl);
+    url.protocol = url.protocol.toLowerCase().replace(/(http)(s)?/gi, "ws$2");
+    appendSearchParams(url.searchParams, transcriptionOptions);
+
+    if (isBrowser()) {
+      this._socket = new WebSocket(url.toString(), ["token", apiKey]);
+    } else {
+      this._socket = new WebSocket(url.toString(), {
+        headers: {
+          Authorization: `token ${apiKey}`,
+          ...DEFAULT_HEADERS,
+        },
+      });
+    }
+
+    this._socket.onopen = () => {
+      this.emit(LiveTranscriptionEvents.Open, this);
+    };
+
+    this._socket.onclose = (event: WebSocket.CloseEvent) => {
+      /**
+       * changing the event.target to any to access the private _req
+       * property that isn't available on the WebSocket.CloseEvent type
+       **/
+      const newTarget: any = event.target;
+
+      if (newTarget["_req"]) {
+        const dgErrorIndex = newTarget["_req"].res.rawHeaders.indexOf("dg-error");
+        event.reason = newTarget["_req"].res.rawHeaders[dgErrorIndex + 1];
+      }
+
+      this.emit(LiveTranscriptionEvents.Close, event);
+    };
+
+    this._socket.onerror = (event) => {
+      this.emit(LiveTranscriptionEvents.Error, event);
+    };
+
+    this._socket.onmessage = (event) => {
+      try {
+        const data: any = JSON.parse(event.data.toString());
+
+        if (data.type === LiveTranscriptionEvents.Metadata) {
+          this.emit(LiveTranscriptionEvents.Metadata, data as LiveMetadataEvent);
+        }
+
+        if (data.type === LiveTranscriptionEvents.Transcript) {
+          this.emit(LiveTranscriptionEvents.Transcript, data as LiveTranscriptionEvent);
+        }
+      } catch (error) {
+        this.emit(LiveTranscriptionEvents.Error, {
+          event,
+          message: "Unable to parse `data` as JSON.",
+          error,
+        });
+      }
+    };
+  }
+
+  public configure(config: LiveConfigOptions): void {
+    this._socket.send(
+      JSON.stringify({
+        type: "Configure",
+        processors: config,
+      })
+    );
+  }
+
+  public keepAlive(): void {
+    this._socket.send(
+      JSON.stringify({
+        type: "KeepAlive",
+      })
+    );
+  }
+
+  public getReadyState(): LiveConnectionState {
+    return this._socket.readyState;
+  }
+
+  /**
+   * Sends data to the Deepgram API via websocket connection
+   * @param data Audio data to send to Deepgram
+   *
+   * Conforms to RFC #146 - does not send an empty byte.
+   * @see https://github.com/deepgram/deepgram-python-sdk/issues/146
+   */
+  public send(data: string | ArrayBufferLike | ArrayBufferView): void {
+    if (this._socket.readyState === LiveConnectionState.OPEN) {
+      if (typeof data === "string") {
+        this._socket.send(data); // send text data
+      } else {
+        if (data.byteLength > 0) {
+          this._socket.send(data); // send buffer when not zero-byte
+        } else {
+          this.emit(
+            LiveTranscriptionEvents.Warning,
+            "Zero-byte detected, skipping. Send `CloseStream` if trying to close the connection."
+          );
+        }
+      }
+    } else {
+      this.emit(LiveTranscriptionEvents.Error, "Could not send. Connection not open.");
+    }
+  }
+
+  /**
+   * Denote that you are finished sending audio and close
+   * the websocket connection when transcription is finished
+   */
+  public finish(): void {
+    // tell the server to close the socket
+    this._socket.send(
+      JSON.stringify({
+        type: "CloseStream",
+      })
+    );
+
+    // close the socket from the client end
+    if (this._socket.readyState === LiveConnectionState.OPEN) {
+      this._socket.close();
+    }
+  }
+}