@deepgram/sdk 4.11.3 → 5.0.0-alpha.2

package/src/packages/AbstractRestClient.ts

@@ -1,223 +0,0 @@
-import { DeepgramApiError, DeepgramError, DeepgramUnknownError } from "../lib/errors";
-import type { Readable } from "node:stream";
-import { fetchWithAuth, resolveResponse } from "../lib/fetch";
-import type { Fetch, FetchOptions, RequestMethodType } from "../lib/types/Fetch";
-import { AbstractClient } from "./AbstractClient";
-import { DeepgramClientOptions } from "../lib/types";
-import { isBrowser } from "../lib/runtime";
-import merge from "deepmerge";
-
-/**
- * An abstract class that extends `AbstractClient` and provides a base implementation for a REST-based API client.
- * This class handles authentication, error handling, and other common functionality for REST API clients.
- */
-export abstract class AbstractRestClient extends AbstractClient {
-  protected fetch: Fetch;
-
-  /**
-   * Constructs a new instance of the `AbstractRestClient` class with the provided options.
-   *
-   * @param options - The client options to use for this instance.
-   * @throws {DeepgramError} If the client is being used in a browser and no proxy is provided.
-   */
-  constructor(options: DeepgramClientOptions) {
-    super(options);
-
-    if (isBrowser() && !this.proxy) {
-      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: https://dpgr.am/js-proxy for more information."
-      );
-    }
-
-    const { accessToken, key: apiKey, fetch: customFetch } = this;
-
-    this.fetch = fetchWithAuth({ accessToken, apiKey, customFetch });
-
-    if (this.proxy) {
-      this.baseUrl = this.namespaceOptions.fetch.options.proxy!.url;
-    } else {
-      this.baseUrl = this.namespaceOptions.fetch.options.url;
-    }
-  }
-
-  /**
-   * Constructs an error message from the provided error object.
-   *
-   * @param err - The error object to extract the error message from.
-   * @returns The constructed error message.
-   */
-  protected _getErrorMessage(err: any): string {
-    return err.msg || err.message || err.error_description || err.error || JSON.stringify(err);
-  }
-
-  /**
-   * Handles an error that occurred during a request.
-   *
-   * @param error - The error that occurred during the request.
-   * @param reject - The rejection function to call with the error.
-   * @returns A Promise that resolves when the error has been handled.
-   */
-  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));
-    }
-  }
-
-  /**
-   * Constructs the options object to be used for a fetch request.
-   *
-   * @param method - The HTTP method to use for the request, such as "GET", "POST", "PUT", "PATCH", or "DELETE".
-   * @param bodyOrOptions - For "POST", "PUT", and "PATCH" requests, the request body as a string, Buffer, or Readable stream. For "GET" and "DELETE" requests, the fetch options to use.
-   * @param options - Additional fetch options to use for the request.
-   * @returns The constructed fetch options object.
-   */
-  protected _getRequestOptions(
-    method: RequestMethodType,
-    bodyOrOptions?: string | Buffer | Readable | FetchOptions,
-    options?: FetchOptions
-  ): FetchOptions {
-    let reqOptions: FetchOptions = { method };
-
-    if (method === "GET" || method === "DELETE") {
-      reqOptions = { ...reqOptions, ...(bodyOrOptions as FetchOptions) };
-    } else {
-      reqOptions = {
-        duplex: "half",
-        body: bodyOrOptions as BodyInit,
-        ...reqOptions,
-        ...options,
-      };
-    }
-
-    return merge(this.namespaceOptions.fetch.options, reqOptions, { clone: false });
-  }
-
-  /**
-   * Handles an HTTP request using the provided method, URL, and optional request body and options.
-   *
-   * @param method - The HTTP method to use for the request, such as "GET", "POST", "PUT", "PATCH", or "DELETE".
-   * @param url - The URL to send the request to.
-   * @param bodyOrOptions - For "POST", "PUT", and "PATCH" requests, the request body as a string, Buffer, or Readable stream. For "GET" and "DELETE" requests, the fetch options to use.
-   * @param options - Additional fetch options to use for the request.
-   * @returns A Promise that resolves to the Response object for the request.
-   */
-  protected async _handleRequest(
-    method: "GET" | "DELETE",
-    url: URL,
-    options?: FetchOptions
-  ): Promise<Response>;
-  protected async _handleRequest(
-    method: "POST" | "PUT" | "PATCH",
-    url: URL,
-    body: string | Buffer | Readable,
-    options?: FetchOptions
-  ): Promise<Response>;
-  protected async _handleRequest(
-    method: RequestMethodType,
-    url: URL,
-    bodyOrOptions?: string | Buffer | Readable | FetchOptions,
-    options?: FetchOptions
-  ): Promise<Response> {
-    return new Promise((resolve, reject) => {
-      const fetcher = this.fetch;
-
-      fetcher(url, this._getRequestOptions(method, bodyOrOptions, options))
-        .then((result) => {
-          if (!result.ok) throw result;
-          resolve(result);
-        })
-        .catch((error) => this._handleError(error, reject));
-    });
-  }
-
-  /**
-   * Handles an HTTP GET request using the provided URL and optional request options.
-   *
-   * @param url - The URL to send the GET request to.
-   * @param options - Additional fetch options to use for the GET request.
-   * @returns A Promise that resolves to the Response object for the GET request.
-   */
-  protected async get(url: URL, options?: FetchOptions): Promise<any> {
-    return this._handleRequest("GET", url, options);
-  }
-
-  /**
-   * Handles an HTTP POST request using the provided URL, request body, and optional request options.
-   *
-   * @param url - The URL to send the POST request to.
-   * @param body - The request body as a string, Buffer, or Readable stream.
-   * @param options - Additional fetch options to use for the POST request.
-   * @returns A Promise that resolves to the Response object for the POST request.
-   */
-  protected async post(
-    url: URL,
-    body: string | Buffer | Readable,
-    options?: FetchOptions
-  ): Promise<any> {
-    return this._handleRequest("POST", url, body, options);
-  }
-
-  /**
-   * Handles an HTTP PUT request using the provided URL, request body, and optional request options.
-   *
-   * @param url - The URL to send the PUT request to.
-   * @param body - The request body as a string, Buffer, or Readable stream.
-   * @param options - Additional fetch options to use for the PUT request.
-   * @returns A Promise that resolves to the Response object for the PUT request.
-   */
-  protected async put(
-    url: URL,
-    body: string | Buffer | Readable,
-    options?: FetchOptions
-  ): Promise<any> {
-    return this._handleRequest("PUT", url, body, options);
-  }
-
-  /**
-   * Handles an HTTP PATCH request using the provided URL, request body, and optional request options.
-   *
-   * @param url - The URL to send the PATCH request to.
-   * @param body - The request body as a string, Buffer, or Readable stream.
-   * @param options - Additional fetch options to use for the PATCH request.
-   * @returns A Promise that resolves to the Response object for the PATCH request.
-   */
-  protected async patch(
-    url: URL,
-    body: string | Buffer | Readable,
-    options?: FetchOptions
-  ): Promise<any> {
-    return this._handleRequest("PATCH", url, body, options);
-  }
-
-  /**
-   * Handles an HTTP DELETE request using the provided URL and optional request options.
-   *
-   * @param url - The URL to send the DELETE request to.
-   * @param options - Additional fetch options to use for the DELETE request.
-   * @returns A Promise that resolves to the Response object for the DELETE request.
-   */
-  protected async delete(url: URL, options?: FetchOptions): Promise<any> {
-    return this._handleRequest("DELETE", url, options);
-  }
-
-  /**
-   * Determines whether the current instance should proxy requests.
-   * @returns {boolean} true if the current instance should proxy requests; otherwise, false
-   */
-  get proxy(): boolean {
-    return this.key === "proxy" && !!this.namespaceOptions.fetch.options.proxy?.url;
-  }
-}
-
-export { AbstractRestClient as AbstractRestfulClient };

package/src/packages/AgentLiveClient.ts

@@ -1,170 +0,0 @@
-import { DEFAULT_AGENT_URL } from "../lib/constants";
-import { AgentEvents } from "../lib/enums/AgentEvents";
-import type { AgentLiveSchema, DeepgramClientOptions, FunctionCallResponse } from "../lib/types";
-import { AbstractLiveClient } from "./AbstractLiveClient";
-
-export class AgentLiveClient extends AbstractLiveClient {
-  public namespace: string = "agent";
-
-  constructor(options: DeepgramClientOptions, endpoint: string = "/:version/agent/converse") {
-    super(options);
-    this.baseUrl = options.agent?.websocket?.options?.url ?? DEFAULT_AGENT_URL;
-
-    this.connect({}, endpoint);
-  }
-
-  /**
-   * Sets up the connection event handlers.
-   * This method is responsible for handling the various events that can occur on the WebSocket connection, such as opening, closing, and receiving messages.
-   * - When the connection is opened, it emits the `AgentEvents.Open` event.
-   * - When the connection is closed, it emits the `AgentEvents.Close` event.
-   * - When an error occurs on the connection, it emits the `AgentEvents.Error` event.
-   * - When a message is received, it parses the message and emits the appropriate event based on the message type.
-   */
-  public setupConnection(): void {
-    // Set up standard connection events (open, close, error) using abstracted method
-    this.setupConnectionEvents({
-      Open: AgentEvents.Open,
-      Close: AgentEvents.Close,
-      Error: AgentEvents.Error,
-    });
-
-    // Set up message handling specific to agent conversations
-    if (this.conn) {
-      this.conn.onmessage = (event: MessageEvent) => {
-        this.handleMessage(event);
-      };
-    }
-  }
-
-  /**
-   * Handles incoming messages from the WebSocket connection.
-   * @param event - The MessageEvent object representing the received message.
-   */
-  protected handleMessage(event: MessageEvent): void {
-    if (typeof event.data === "string") {
-      try {
-        const data = JSON.parse(event.data);
-        this.handleTextMessage(data);
-      } catch (error) {
-        this.emit(AgentEvents.Error, {
-          event,
-          data:
-            event.data?.toString().substring(0, 200) +
-            (event.data?.toString().length > 200 ? "..." : ""),
-          message: "Unable to parse `data` as JSON.",
-          error,
-          url: this.conn?.url,
-          readyState: this.conn?.readyState,
-        });
-      }
-    } else if (event.data instanceof Blob) {
-      event.data.arrayBuffer().then((buffer) => {
-        this.handleBinaryMessage(Buffer.from(buffer));
-      });
-    } else if (event.data instanceof ArrayBuffer) {
-      this.handleBinaryMessage(Buffer.from(event.data));
-    } else if (Buffer.isBuffer(event.data)) {
-      this.handleBinaryMessage(event.data);
-    } else {
-      console.log("Received unknown data type", event.data);
-      this.emit(AgentEvents.Error, {
-        event,
-        message: "Received unknown data type.",
-        url: this.conn?.url,
-        readyState: this.conn?.readyState,
-        dataType: typeof event.data,
-      });
-    }
-  }
-
-  /**
-   * Handles binary messages received from the WebSocket connection.
-   * @param data - The binary data.
-   */
-  protected handleBinaryMessage(data: Buffer): void {
-    this.emit(AgentEvents.Audio, data);
-  }
-
-  /**
-   * Handles text messages received from the WebSocket connection.
-   * @param data - The parsed JSON data.
-   */
-  protected handleTextMessage(data: any): void {
-    if (data.type in AgentEvents) {
-      this.emit(data.type, data);
-    } else {
-      this.emit(AgentEvents.Unhandled, data);
-    }
-  }
-
-  /**
-   * To be called with your model configuration BEFORE sending
-   * any audio data.
-   * @param options - The SettingsConfiguration object.
-   */
-  public configure(options: AgentLiveSchema): void {
-    const string = JSON.stringify({
-      type: "Settings",
-      ...options,
-    });
-    this.send(string);
-  }
-
-  /**
-   * Provide new system prompt to the LLM.
-   * @param prompt - The system prompt to provide.
-   */
-  public updatePrompt(prompt: string): void {
-    this.send(JSON.stringify({ type: "UpdatePrompt", prompt }));
-  }
-
-  /**
-   * Change the speak model.
-   * @param model - The new model to use.
-   */
-  public updateSpeak(speakConfig: Exclude<AgentLiveSchema["agent"]["speak"], undefined>): void {
-    this.send(JSON.stringify({ type: "UpdateSpeak", speak: speakConfig }));
-  }
-
-  /**
-   * Immediately trigger an agent message. If this message
-   * is sent while the user is speaking, or while the server is in the
-   * middle of sending audio, then the request will be ignored and an InjectionRefused
-   * event will be emitted.
-   * @example "Hold on while I look that up for you."
-   * @example "Are you still on the line?"
-   * @param content - The message to speak.
-   */
-  public injectAgentMessage(content: string): void {
-    this.send(JSON.stringify({ type: "InjectAgentMessage", content }));
-  }
-
-  /**
-   * Send a text-based message to the agent as if it came from the user.
-   * This allows you to inject user messages into the conversation for the agent to respond to.
-   * @example "Hello! Can you hear me?"
-   * @example "What's the weather like today?"
-   * @param content - The specific phrase or statement the agent should respond to.
-   */
-  public injectUserMessage(content: string): void {
-    this.send(JSON.stringify({ type: "InjectUserMessage", content }));
-  }
-
-  /**
-   * Respond to a function call request.
-   * @param response  - The response to the function call request.
-   */
-  public functionCallResponse(response: FunctionCallResponse): void {
-    this.send(JSON.stringify({ type: "FunctionCallResponse", ...response }));
-  }
-
-  /**
-   * Send a keepalive to avoid closing the websocket while you
-   * are not transmitting audio. This should be sent at least
-   * every 8 seconds.
-   */
-  public keepAlive(): void {
-    this.send(JSON.stringify({ type: "KeepAlive" }));
-  }
-}

package/src/packages/AuthRestClient.ts

@@ -1,36 +0,0 @@
-import { isDeepgramError } from "../lib/errors";
-import type { DeepgramResponse } from "../lib/types/DeepgramResponse";
-import type { GrantTokenResponse } from "../lib/types/GrantTokenResponse";
-import type { GrantTokenSchema } from "../lib/types/GrantTokenSchema";
-import { AbstractRestClient } from "./AbstractRestClient";
-
-export class AuthRestClient extends AbstractRestClient {
-  public namespace: string = "auth";
-
-  /**
-   * Generates a new temporary token for the Deepgram API.
-   * @param options Optional configuration options for the token generation. Includes ttl_seconds to set token expiration.
-   * @param endpoint Optional custom endpoint to use for the request. Defaults to ":version/auth/grant".
-   * @returns Object containing the result of the request or an error if one occurred. Result will contain access_token and expires_in properties.
-   */
-  public async grantToken(
-    options: GrantTokenSchema = {},
-    endpoint = ":version/auth/grant"
-  ): Promise<DeepgramResponse<GrantTokenResponse>> {
-    try {
-      const requestUrl = this.getRequestUrl(endpoint);
-      const body = JSON.stringify(options);
-      const result: GrantTokenResponse = await this.post(requestUrl, body, {
-        headers: { "Content-Type": "application/json" },
-      }).then((result) => result.json());
-
-      return { result, error: null };
-    } catch (error) {
-      if (isDeepgramError(error)) {
-        return { result: null, error };
-      }
-
-      throw error;
-    }
-  }
-}

package/src/packages/ListenClient.ts

@@ -1,35 +0,0 @@
-import { AbstractClient } from "./AbstractClient";
-import { ListenLiveClient } from "./ListenLiveClient";
-import { ListenRestClient } from "./ListenRestClient";
-import { LiveSchema } from "../lib/types";
-
-/**
- * The `ListenClient` class extends the `AbstractClient` class and provides access to the "listen" namespace.
- * It exposes two methods:
- *
- * 1. `prerecorded()`: Returns a `ListenRestClient` instance for interacting with the prerecorded listen API.
- * 2. `live(transcriptionOptions: LiveSchema = {}, endpoint = ":version/listen")`: Returns a `ListenLiveClient` instance for interacting with the live listen API, with the provided transcription options and endpoint.
- */
-export class ListenClient extends AbstractClient {
-  public namespace: string = "listen";
-
-  /**
-   * Returns a `ListenRestClient` instance for interacting with the prerecorded listen API.
-   */
-  get prerecorded() {
-    return new ListenRestClient(this.options);
-  }
-
-  /**
-   * Returns a `ListenLiveClient` instance for interacting with the live listen API, with the provided transcription options and endpoint.
-   * @param {LiveSchema} [transcriptionOptions={}] - The transcription options to use for the live listen API.
-   * @param {string} [endpoint=":version/listen"] - The endpoint to use for the live listen API.
-   * @returns {ListenLiveClient} - A `ListenLiveClient` instance for interacting with the live listen API.
-   */
-  public live(
-    transcriptionOptions: LiveSchema = {},
-    endpoint: string = ":version/listen"
-  ): ListenLiveClient {
-    return new ListenLiveClient(this.options, transcriptionOptions, endpoint);
-  }
-}

package/src/packages/ListenLiveClient.ts

@@ -1,145 +0,0 @@
-import { AbstractLiveClient } from "./AbstractLiveClient";
-import { LiveTranscriptionEvents } from "../lib/enums";
-import type { LiveSchema, LiveConfigOptions, DeepgramClientOptions } from "../lib/types";
-
-/**
- * The `ListenLiveClient` class extends the `AbstractLiveClient` class and provides functionality for setting up and managing a WebSocket connection for live transcription.
- *
- * The constructor takes in `DeepgramClientOptions` and an optional `LiveSchema` object, as well as an optional `endpoint` string. It then calls the `connect` method of the parent `AbstractLiveClient` class to establish the WebSocket connection.
- *
- * The `setupConnection` method is responsible for handling the various events that can occur on the WebSocket connection, such as opening, closing, and receiving messages. It sets up event handlers for these events and emits the appropriate events based on the message type.
- *
- * The `configure` method allows you to send additional configuration options to the connected session, such as enabling numerals.
- *
- * The `keepAlive` method sends a "KeepAlive" message to the server to maintain the connection.
- *
- * The `requestClose` method requests the server to close the connection.
- *
- * The `finish` method is deprecated as of version 3.4 and will be removed in version 4.0. Use `requestClose` instead.
- */
-export class ListenLiveClient extends AbstractLiveClient {
-  public namespace: string = "listen";
-
-  /**
-   * Constructs a new `ListenLiveClient` instance with the provided options.
-   *
-   * @param options - The `DeepgramClientOptions` to use for the client connection.
-   * @param transcriptionOptions - An optional `LiveSchema` object containing additional configuration options for the live transcription.
-   * @param endpoint - An optional string representing the WebSocket endpoint to connect to. Defaults to `:version/listen`.
-   */
-  constructor(
-    options: DeepgramClientOptions,
-    transcriptionOptions: LiveSchema = {},
-    endpoint: string = ":version/listen"
-  ) {
-    super(options);
-
-    this.connect(transcriptionOptions, endpoint);
-  }
-
-  /**
-   * Sets up the connection event handlers.
-   * This method is responsible for handling the various events that can occur on the WebSocket connection, such as opening, closing, and receiving messages.
-   * - When the connection is opened, it emits the `LiveTranscriptionEvents.Open` event.
-   * - When the connection is closed, it emits the `LiveTranscriptionEvents.Close` event.
-   * - When an error occurs on the connection, it emits the `LiveTranscriptionEvents.Error` event.
-   * - When a message is received, it parses the message and emits the appropriate event based on the message type, such as `LiveTranscriptionEvents.Metadata`, `LiveTranscriptionEvents.Transcript`, `LiveTranscriptionEvents.UtteranceEnd`, and `LiveTranscriptionEvents.SpeechStarted`.
-   */
-  public setupConnection(): void {
-    // Set up standard connection events (open, close, error) using abstracted method
-    this.setupConnectionEvents({
-      Open: LiveTranscriptionEvents.Open,
-      Close: LiveTranscriptionEvents.Close,
-      Error: LiveTranscriptionEvents.Error,
-    });
-
-    // Set up message handling specific to transcription
-    if (this.conn) {
-      this.conn.onmessage = (event: MessageEvent) => {
-        try {
-          const data: any = JSON.parse(event.data.toString());
-
-          if (data.type === LiveTranscriptionEvents.Metadata) {
-            this.emit(LiveTranscriptionEvents.Metadata, data);
-          } else if (data.type === LiveTranscriptionEvents.Transcript) {
-            this.emit(LiveTranscriptionEvents.Transcript, data);
-          } else if (data.type === LiveTranscriptionEvents.UtteranceEnd) {
-            this.emit(LiveTranscriptionEvents.UtteranceEnd, data);
-          } else if (data.type === LiveTranscriptionEvents.SpeechStarted) {
-            this.emit(LiveTranscriptionEvents.SpeechStarted, data);
-          } else {
-            this.emit(LiveTranscriptionEvents.Unhandled, data);
-          }
-        } catch (error) {
-          this.emit(LiveTranscriptionEvents.Error, {
-            event,
-            message: "Unable to parse `data` as JSON.",
-            error,
-            url: this.conn?.url,
-            readyState: this.conn?.readyState,
-            data:
-              event.data?.toString().substring(0, 200) +
-              (event.data?.toString().length > 200 ? "..." : ""),
-          });
-        }
-      };
-    }
-  }
-
-  /**
-   * Sends additional config to the connected session.
-   *
-   * @param config - The configuration options to apply to the LiveClient.
-   * @param config.numerals - We currently only support numerals.
-   */
-  public configure(config: LiveConfigOptions): void {
-    this.send(
-      JSON.stringify({
-        type: "Configure",
-        processors: config,
-      })
-    );
-  }
-
-  /**
-   * Sends a "KeepAlive" message to the server to maintain the connection.
-   */
-  public keepAlive(): void {
-    this.send(
-      JSON.stringify({
-        type: "KeepAlive",
-      })
-    );
-  }
-
-  /**
-   * Sends a "Finalize" message to flush any transcription sitting in the server's buffer.
-   */
-  public finalize(): void {
-    this.send(
-      JSON.stringify({
-        type: "Finalize",
-      })
-    );
-  }
-
-  /**
-   * @deprecated Since version 3.4. Will be removed in version 4.0. Use `requestClose` instead.
-   */
-  public finish(): void {
-    this.requestClose();
-  }
-
-  /**
-   * Requests the server close the connection.
-   */
-  public requestClose(): void {
-    this.send(
-      JSON.stringify({
-        type: "CloseStream",
-      })
-    );
-  }
-}
-
-export { ListenLiveClient as LiveClient };