Client.ts

/**
 * This file was auto-generated by Fern from our API Definition.
 */

import * as environments from "./environments.js";
import * as core from "./core/index.js";
import { mergeHeaders, mergeOnlyDefinedHeaders } from "./core/headers.js";
import * as VoyageAI from "./api/index.js";
import * as errors from "./errors/index.js";

export declare namespace VoyageAIClient {
    export interface Options {
        environment?: core.Supplier<environments.VoyageAIEnvironment | string>;
        /** Specify a custom URL to connect the client to. */
        baseUrl?: core.Supplier<string>;
        apiKey?: core.Supplier<core.BearerToken | undefined>;
        /** Additional headers to include in requests. */
        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
        fetcher?: core.FetchFunction;
    }

    export interface RequestOptions {
        /** The maximum time to wait for a response in seconds. */
        timeoutInSeconds?: number;
        /** The number of times to retry the request. Defaults to 2. */
        maxRetries?: number;
        /** A hook to abort the request. */
        abortSignal?: AbortSignal;
        /** Additional query string parameters to include in the request. */
        queryParams?: Record<string, unknown>;
        /** Additional headers to include in the request. */
        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
    }
}

export class VoyageAIClient {
    protected readonly _options: VoyageAIClient.Options;

    constructor(_options: VoyageAIClient.Options = {}) {
        this._options = {
            ..._options,
            headers: mergeHeaders(
                {
                    "X-Fern-Language": "JavaScript",
                    "X-Fern-SDK-Name": "voyageai",
                    "X-Fern-SDK-Version": "0.0.0",
                    "User-Agent": "voyageai/0.0.0",
                    "X-Fern-Runtime": core.RUNTIME.type,
                    "X-Fern-Runtime-Version": core.RUNTIME.version,
                },
                _options?.headers,
            ),
        };
    }

    /**
     * Voyage embedding endpoint receives as input a string (or a list of strings) and other arguments such as the preferred model name, and returns a response containing a list of embeddings.
     *
     * @param {VoyageAI.EmbedRequest} request
     * @param {VoyageAIClient.RequestOptions} requestOptions - Request-specific configuration.
     *
     * @example
     *     await client.embed({
     *         input: "input",
     *         model: "model"
     *     })
     */
    public embed(
        request: VoyageAI.EmbedRequest,
        requestOptions?: VoyageAIClient.RequestOptions,
    ): core.HttpResponsePromise<VoyageAI.EmbedResponse> {
        return core.HttpResponsePromise.fromPromise(this.__embed(request, requestOptions));
    }

    private async __embed(
        request: VoyageAI.EmbedRequest,
        requestOptions?: VoyageAIClient.RequestOptions,
    ): Promise<core.WithRawResponse<VoyageAI.EmbedResponse>> {
        const _response = await (this._options.fetcher ?? core.fetcher)({
            url: core.url.join(
                (await core.Supplier.get(this._options.baseUrl)) ??
                    (await core.Supplier.get(this._options.environment)) ??
                    environments.VoyageAIEnvironment.Default,
                "embeddings",
            ),
            method: "POST",
            headers: mergeHeaders(
                this._options?.headers,
                mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
                requestOptions?.headers,
            ),
            contentType: "application/json",
            queryParameters: requestOptions?.queryParams,
            requestType: "json",
            body: request,
            timeoutMs: requestOptions?.timeoutInSeconds != null ? requestOptions.timeoutInSeconds * 1000 : 60000,
            maxRetries: requestOptions?.maxRetries,
            abortSignal: requestOptions?.abortSignal,
        });
        if (_response.ok) {
            return { data: _response.body as VoyageAI.EmbedResponse, rawResponse: _response.rawResponse };
        }

        if (_response.error.reason === "status-code") {
            throw new errors.VoyageAIError({
                statusCode: _response.error.statusCode,
                body: _response.error.body,
                rawResponse: _response.rawResponse,
            });
        }

        switch (_response.error.reason) {
            case "non-json":
                throw new errors.VoyageAIError({
                    statusCode: _response.error.statusCode,
                    body: _response.error.rawBody,
                    rawResponse: _response.rawResponse,
                });
            case "timeout":
                throw new errors.VoyageAITimeoutError("Timeout exceeded when calling POST /embeddings.");
            case "unknown":
                throw new errors.VoyageAIError({
                    message: _response.error.errorMessage,
                    rawResponse: _response.rawResponse,
                });
        }
    }

    /**
     * Voyage reranker endpoint receives as input a query, a list of documents, and other arguments such as the model name, and returns a response containing the reranking results.
     *
     * @param {VoyageAI.RerankRequest} request
     * @param {VoyageAIClient.RequestOptions} requestOptions - Request-specific configuration.
     *
     * @example
     *     await client.rerank({
     *         query: "query",
     *         documents: ["documents"],
     *         model: "model"
     *     })
     */
    public rerank(
        request: VoyageAI.RerankRequest,
        requestOptions?: VoyageAIClient.RequestOptions,
    ): core.HttpResponsePromise<VoyageAI.RerankResponse> {
        return core.HttpResponsePromise.fromPromise(this.__rerank(request, requestOptions));
    }

    private async __rerank(
        request: VoyageAI.RerankRequest,
        requestOptions?: VoyageAIClient.RequestOptions,
    ): Promise<core.WithRawResponse<VoyageAI.RerankResponse>> {
        const _response = await (this._options.fetcher ?? core.fetcher)({
            url: core.url.join(
                (await core.Supplier.get(this._options.baseUrl)) ??
                    (await core.Supplier.get(this._options.environment)) ??
                    environments.VoyageAIEnvironment.Default,
                "rerank",
            ),
            method: "POST",
            headers: mergeHeaders(
                this._options?.headers,
                mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
                requestOptions?.headers,
            ),
            contentType: "application/json",
            queryParameters: requestOptions?.queryParams,
            requestType: "json",
            body: request,
            timeoutMs: requestOptions?.timeoutInSeconds != null ? requestOptions.timeoutInSeconds * 1000 : 60000,
            maxRetries: requestOptions?.maxRetries,
            abortSignal: requestOptions?.abortSignal,
        });
        if (_response.ok) {
            return { data: _response.body as VoyageAI.RerankResponse, rawResponse: _response.rawResponse };
        }

        if (_response.error.reason === "status-code") {
            throw new errors.VoyageAIError({
                statusCode: _response.error.statusCode,
                body: _response.error.body,
                rawResponse: _response.rawResponse,
            });
        }

        switch (_response.error.reason) {
            case "non-json":
                throw new errors.VoyageAIError({
                    statusCode: _response.error.statusCode,
                    body: _response.error.rawBody,
                    rawResponse: _response.rawResponse,
                });
            case "timeout":
                throw new errors.VoyageAITimeoutError("Timeout exceeded when calling POST /rerank.");
            case "unknown":
                throw new errors.VoyageAIError({
                    message: _response.error.errorMessage,
                    rawResponse: _response.rawResponse,
                });
        }
    }

    /**
     * The Voyage multimodal embedding endpoint returns vector representations for a given list of multimodal inputs consisting of text, images, or an interleaving of both modalities.
     *
     * @param {VoyageAI.MultimodalEmbedRequest} request
     * @param {VoyageAIClient.RequestOptions} requestOptions - Request-specific configuration.
     *
     * @example
     *     await client.multimodalEmbed({
     *         inputs: [{}],
     *         model: "model"
     *     })
     */
    public multimodalEmbed(
        request: VoyageAI.MultimodalEmbedRequest,
        requestOptions?: VoyageAIClient.RequestOptions,
    ): core.HttpResponsePromise<VoyageAI.MultimodalEmbedResponse> {
        return core.HttpResponsePromise.fromPromise(this.__multimodalEmbed(request, requestOptions));
    }

    private async __multimodalEmbed(
        request: VoyageAI.MultimodalEmbedRequest,
        requestOptions?: VoyageAIClient.RequestOptions,
    ): Promise<core.WithRawResponse<VoyageAI.MultimodalEmbedResponse>> {
        const _response = await (this._options.fetcher ?? core.fetcher)({
            url: core.url.join(
                (await core.Supplier.get(this._options.baseUrl)) ??
                    (await core.Supplier.get(this._options.environment)) ??
                    environments.VoyageAIEnvironment.Default,
                "multimodalembeddings",
            ),
            method: "POST",
            headers: mergeHeaders(
                this._options?.headers,
                mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
                requestOptions?.headers,
            ),
            contentType: "application/json",
            queryParameters: requestOptions?.queryParams,
            requestType: "json",
            body: request,
            timeoutMs: requestOptions?.timeoutInSeconds != null ? requestOptions.timeoutInSeconds * 1000 : 60000,
            maxRetries: requestOptions?.maxRetries,
            abortSignal: requestOptions?.abortSignal,
        });
        if (_response.ok) {
            return { data: _response.body as VoyageAI.MultimodalEmbedResponse, rawResponse: _response.rawResponse };
        }

        if (_response.error.reason === "status-code") {
            throw new errors.VoyageAIError({
                statusCode: _response.error.statusCode,
                body: _response.error.body,
                rawResponse: _response.rawResponse,
            });
        }

        switch (_response.error.reason) {
            case "non-json":
                throw new errors.VoyageAIError({
                    statusCode: _response.error.statusCode,
                    body: _response.error.rawBody,
                    rawResponse: _response.rawResponse,
                });
            case "timeout":
                throw new errors.VoyageAITimeoutError("Timeout exceeded when calling POST /multimodalembeddings.");
            case "unknown":
                throw new errors.VoyageAIError({
                    message: _response.error.errorMessage,
                    rawResponse: _response.rawResponse,
                });
        }
    }

    /**
     * The Voyage contextualized embeddings endpoint receives as input a list of documents (each document is a list of chunks), and returns contextualized embeddings for each chunk. The embeddings capture both the local chunk content and the global document context, making them particularly effective for retrieval tasks where understanding document-level context is important.
     *
     * @param {VoyageAI.ContextualizedEmbedRequest} request
     * @param {VoyageAIClient.RequestOptions} requestOptions - Request-specific configuration.
     *
     * @example
     *     await client.contextualizedEmbed({
     *         inputs: [["inputs"]],
     *         model: "model"
     *     })
     */
    public contextualizedEmbed(
        request: VoyageAI.ContextualizedEmbedRequest,
        requestOptions?: VoyageAIClient.RequestOptions,
    ): core.HttpResponsePromise<VoyageAI.ContextualizedEmbedResponse> {
        return core.HttpResponsePromise.fromPromise(this.__contextualizedEmbed(request, requestOptions));
    }

    private async __contextualizedEmbed(
        request: VoyageAI.ContextualizedEmbedRequest,
        requestOptions?: VoyageAIClient.RequestOptions,
    ): Promise<core.WithRawResponse<VoyageAI.ContextualizedEmbedResponse>> {
        const _response = await (this._options.fetcher ?? core.fetcher)({
            url: core.url.join(
                (await core.Supplier.get(this._options.baseUrl)) ??
                    (await core.Supplier.get(this._options.environment)) ??
                    environments.VoyageAIEnvironment.Default,
                "contextualizedembeddings",
            ),
            method: "POST",
            headers: mergeHeaders(
                this._options?.headers,
                mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
                requestOptions?.headers,
            ),
            contentType: "application/json",
            queryParameters: requestOptions?.queryParams,
            requestType: "json",
            body: request,
            timeoutMs: requestOptions?.timeoutInSeconds != null ? requestOptions.timeoutInSeconds * 1000 : 60000,
            maxRetries: requestOptions?.maxRetries,
            abortSignal: requestOptions?.abortSignal,
        });
        if (_response.ok) {
            return { data: _response.body as VoyageAI.ContextualizedEmbedResponse, rawResponse: _response.rawResponse };
        }

        if (_response.error.reason === "status-code") {
            throw new errors.VoyageAIError({
                statusCode: _response.error.statusCode,
                body: _response.error.body,
                rawResponse: _response.rawResponse,
            });
        }

        switch (_response.error.reason) {
            case "non-json":
                throw new errors.VoyageAIError({
                    statusCode: _response.error.statusCode,
                    body: _response.error.rawBody,
                    rawResponse: _response.rawResponse,
                });
            case "timeout":
                throw new errors.VoyageAITimeoutError("Timeout exceeded when calling POST /contextualizedembeddings.");
            case "unknown":
                throw new errors.VoyageAIError({
                    message: _response.error.errorMessage,
                    rawResponse: _response.rawResponse,
                });
        }
    }

    protected async _getAuthorizationHeader(): Promise<string> {
        const bearer = (await core.Supplier.get(this._options.apiKey)) ?? process?.env["VOYAGE_API_KEY"];
        if (bearer == null) {
            throw new errors.VoyageAIError({
                message:
                    "Please specify a bearer by either passing it in to the constructor or initializing a VOYAGE_API_KEY environment variable",
            });
        }

        return `Bearer ${bearer}`;
    }
}