diff --git a/src/DeepgramClient.ts b/src/DeepgramClient.ts index cffb6e1..63a0956 100644 --- a/src/DeepgramClient.ts +++ b/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. * diff --git a/src/lib/types/GetModelsResponse.ts b/src/lib/types/GetModelsResponse.ts new file mode 100644 index 0000000..eefe613 --- /dev/null +++ b/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[]; +}; diff --git a/src/lib/types/GetModelsSchema.ts b/src/lib/types/GetModelsSchema.ts new file mode 100644 index 0000000..b0f3498 --- /dev/null +++ b/src/lib/types/GetModelsSchema.ts @@ -0,0 +1,3 @@ +export interface GetModelsSchema extends Record { + include_outdated?: boolean; +} diff --git a/src/lib/types/index.ts b/src/lib/types/index.ts index 8d68f88..9dd0f7b 100644 --- a/src/lib/types/index.ts +++ b/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"; diff --git a/src/packages/ManageRestClient.ts b/src/packages/ManageRestClient.ts index 9ae3f96..249f7b0 100644 --- a/src/packages/ManageRestClient.ts +++ b/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> { + 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> { + 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 }; diff --git a/src/packages/ModelsRestClient.ts b/src/packages/ModelsRestClient.ts new file mode 100644 index 0000000..0038a9a --- /dev/null +++ b/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> { + 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> { + 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; + } + } +} diff --git a/src/packages/index.ts b/src/packages/index.ts index 92d7bdf..f0e8aeb 100644 --- a/src/packages/index.ts +++ b/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"; diff --git a/test/manage_rest.test.ts b/test/manage_rest.test.ts index be57446..234dd6f 100644 --- a/test/manage_rest.test.ts +++ b/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"]); + }); }); diff --git a/test/models_rest.test.ts b/test/models_rest.test.ts new file mode 100644 index 0000000..781be5c --- /dev/null +++ b/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"]); + }); +});