feat: new metadata models endpoints

src/DeepgramClient.ts

@@ -7,6 +7,7 @@ import {
   OnPremClient,
   SelfHostedRestClient,
   SpeakClient,
+  ModelsRestClient,
 } from "./packages";
 
 /**
@@ -33,6 +34,15 @@ export default class DeepgramClient extends AbstractClient {
     return new ManageClient(this.options);
   }
 
+  /**
+   * Returns a new instance of the ModelsRestClient, which provides access to the Deepgram API's model functionality.
+   *
+   * @returns {ModelsRestClient} A new instance of the ModelsRestClient.
+   */
+  get models(): ModelsRestClient {
+    return new ModelsRestClient(this.options);
+  }
+
   /**
    * Returns a new instance of the SelfHostedRestClient, which provides access to the Deepgram API's self-hosted functionality.
    *

src/lib/types/GetModelsResponse.ts

@@ -0,0 +1,24 @@
+type Model = {
+  name: string;
+  canonical_name: string;
+  architecture: string;
+  languages?: string[];
+  version: string;
+  uuid: string;
+  batch?: boolean;
+  streaming?: boolean;
+  formatted_output?: boolean;
+  metadata?: {
+    accent: string;
+    color: string;
+    image: string;
+    sample: string;
+  };
+};
+
+export type GetModelResponse = Model;
+
+export type GetModelsResponse = {
+  stt: Model[];
+  tts: Model[];
+};

src/lib/types/GetModelsSchema.ts

@@ -0,0 +1,3 @@
+export interface GetModelsSchema extends Record<string, unknown> {
+  include_outdated?: boolean;
+}

src/lib/types/index.ts

@@ -8,6 +8,8 @@ export * from "./DeepgramClientOptions";
 export * from "./DeepgramResponse";
 export * from "./DeepgramSource";
 export * from "./Fetch";
+export * from "./GetModelsResponse";
+export * from "./GetModelsSchema";
 export * from "./GetProjectBalancesResponse";
 export * from "./GetProjectInvitesResponse";
 export * from "./GetProjectKeysResponse";

src/packages/ManageRestClient.ts

@@ -25,6 +25,9 @@ import type {
   UpdateProjectSchema,
   VoidResponse,
   GetTokenDetailsResponse,
+  GetModelsResponse,
+  GetModelResponse,
+  GetModelsSchema,
 } from "../lib/types";
 import { AbstractRestClient } from "./AbstractRestClient";
 
@@ -755,6 +758,85 @@ export class ManageRestClient extends AbstractRestClient {
       throw error;
     }
   }
+
+  /**
+   * Retrieves all models for a given project.
+   *
+   * @param projectId - The ID of the project.
+   * @param endpoint - (optional) The endpoint URL for retrieving models. Defaults to ":version/projects/:projectId/models".
+   * @returns A promise that resolves to a DeepgramResponse containing the GetModelsResponse.
+   * @example
+   * ```typescript
+   * import { createClient } from "@deepgram/sdk";
+   *
+   * const deepgram = createClient(DEEPGRAM_API_KEY);
+   * const { result: models, error } = deepgram.manage.getAllModels("projectId");
+   *
+   * if (error) {
+   *   console.error(error);
+   * } else {
+   *   console.log(models);
+   * }
+   * ```
+   */
+  async getAllModels(
+    projectId: string,
+    options: GetModelsSchema = {},
+    endpoint = ":version/projects/:projectId/models"
+  ): Promise<DeepgramResponse<GetModelsResponse>> {
+    try {
+      const requestUrl = this.getRequestUrl(endpoint, { projectId }, options);
+      const result: GetModelsResponse = await this.get(requestUrl).then((result) => result.json());
+
+      return { result, error: null };
+    } catch (error) {
+      if (isDeepgramError(error)) {
+        return { result: null, error };
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Retrieves a model from the specified project.
+   *
+   * @param projectId - The ID of the project.
+   * @param modelId - The ID of the model.
+   * @param endpoint - (optional) The endpoint URL for the request. Default value is ":version/projects/:projectId/models/:modelId".
+   * @returns A promise that resolves to a DeepgramResponse containing the GetModelResponse.
+   * @example
+   * ```typescript
+   * import { createClient } from "@deepgram/sdk";
+   *
+   * const deepgram = createClient(DEEPGRAM_API_KEY);
+   * const { result: model, error } = deepgram.models.getModel("projectId", "modelId");
+   *
+   * if (error) {
+   *   console.error(error);
+   * } else {
+   *   console.log(model);
+   * }
+   * ```
+   */
+  async getModel(
+    projectId: string,
+    modelId: string,
+    endpoint = ":version/projects/:projectId/models/:modelId"
+  ): Promise<DeepgramResponse<GetModelResponse>> {
+    try {
+      const requestUrl = this.getRequestUrl(endpoint, { projectId, modelId });
+      const result: GetModelResponse = await this.get(requestUrl).then((result) => result.json());
+
+      return { result, error: null };
+    } catch (error) {
+      if (isDeepgramError(error)) {
+        return { result: null, error };
+      }
+
+      throw error;
+    }
+  }
 }
 
 export { ManageRestClient as ManageClient };

src/packages/ModelsRestClient.ts

@@ -0,0 +1,93 @@
+import { isDeepgramError } from "../lib/errors";
+import {
+  DeepgramResponse,
+  GetModelResponse,
+  GetModelsResponse,
+  GetModelsSchema,
+} from "../lib/types";
+import { AbstractRestClient } from "./AbstractRestClient";
+
+/**
+ * Represents a REST client for interacting with the Deepgram API.
+ *
+ * The `ModelsRestClient` class provides methods for interacting with the Deepgram API to retrieve information about available models.
+ * @extends AbstractRestClient
+ */
+export class ModelsRestClient extends AbstractRestClient {
+  public namespace: string = "models";
+
+  /**
+   * Retrieves a list of all available models.
+   *
+   * @param endpoint - (optional) The endpoint to request.
+   * @returns A promise that resolves with the response from the Deepgram API.
+   * @example
+   * ```typescript
+   * import { createClient } from "@deepgram/sdk";
+   *
+   * const deepgram = createClient(DEEPGRAM_API_KEY);
+   * const { result: models, error } = deepgram.models.getAll();
+   *
+   * if (error) {
+   *   console.error(error);
+   * } else {
+   *   console.log(models);
+   * }
+   * ```
+   */
+  async getAll(
+    endpoint = ":version/models",
+    options: GetModelsSchema = {}
+  ): Promise<DeepgramResponse<GetModelsResponse>> {
+    try {
+      const requestUrl = this.getRequestUrl(endpoint, {}, options);
+      const result: GetModelsResponse = await this.get(requestUrl).then((result) => result.json());
+
+      return { result, error: null };
+    } catch (error) {
+      if (isDeepgramError(error)) {
+        return { result: null, error };
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Retrieves information about a specific model.
+   *
+   * @param modelId - The UUID of the model to retrieve.
+   * @param endpoint - (optional) The endpoint to request.
+   * @returns A promise that resolves with the response from the Deepgram API.
+   * @example
+   * ```typescript
+   * import { createClient } from "@deepgram/sdk";
+   *
+   * const deepgram = createClient(DEEPGRAM_API_KEY);
+   * const { result: model, error } = deepgram.models.getModel("modelId");
+   *
+   * if (error) {
+   *   console.error(error);
+   * } else {
+   *   console.log(model);
+   * }
+   * ```
+   */
+  async getModel(
+    modelId: string,
+    endpoint = ":version/models/:modelId"
+  ): Promise<DeepgramResponse<GetModelResponse>> {
+    try {
+      const requestUrl = this.getRequestUrl(endpoint, { modelId });
+      const result: GetModelResponse = await this.get(requestUrl).then((result) => result.json());
+
+      return { result, error: null };
+    } catch (error) {
+      if (isDeepgramError(error)) {
+        return { result: null, error };
+      }
+
+      throw error;
+    }
+  }
+}

src/packages/index.ts

@@ -5,6 +5,7 @@ export * from "./ListenClient";
 export * from "./ListenLiveClient";
 export * from "./ListenRestClient";
 export * from "./ManageRestClient";
+export * from "./ModelsRestClient";
 export * from "./ReadRestClient";
 export * from "./SelfHostedRestClient";
 export * from "./SpeakRestClient";

test/manage_rest.test.ts

@@ -228,4 +228,23 @@ describe("making manage REST requests", () => {
     assert.isNotNull(result);
     assert.containsAllDeepKeys(result, ["balance_id"]);
   });
+
+  it("should retrieve a list of models", async () => {
+    const { result, error } = await deepgram.manage.getAllModels(faker.string.uuid());
+
+    assert.isNull(error);
+    assert.isNotNull(result);
+    assert.containsAllDeepKeys(result, ["stt", "tts"]);
+  });
+
+  it("should retrieve a model", async () => {
+    const { result, error } = await deepgram.manage.getModel(
+      faker.string.uuid(),
+      faker.string.uuid()
+    );
+
+    assert.isNull(error);
+    assert.isNotNull(result);
+    assert.containsAllDeepKeys(result, ["name", "canonical_name"]);
+  });
 });

test/models_rest.test.ts

@@ -0,0 +1,30 @@
+import { assert } from "chai";
+import { createClient } from "../src";
+import { faker } from "@faker-js/faker";
+import DeepgramClient from "../src/DeepgramClient";
+
+describe("making models REST requests", () => {
+  let deepgram: DeepgramClient;
+
+  beforeEach(() => {
+    deepgram = createClient(faker.string.alphanumeric(40), {
+      global: { url: "https://api.mock.deepgram.com" },
+    });
+  });
+
+  it("should retrieve a list of models", async () => {
+    const { result, error } = await deepgram.models.getAll();
+
+    assert.isNull(error);
+    assert.isNotNull(result);
+    assert.containsAllDeepKeys(result, ["stt", "tts"]);
+  });
+
+  it("should retrieve a model", async () => {
+    const { result, error } = await deepgram.models.getModel(faker.string.uuid());
+
+    assert.isNull(error);
+    assert.isNotNull(result);
+    assert.containsAllDeepKeys(result, ["name", "canonical_name"]);
+  });
+});