libmodpm/dist/registry/RegistryClient.d.ts

Modrinth package manager library

import { HTTPClient } from "../HTTPClient.js";
import { RegistryPackage } from "./RegistryPackage.js";
import { RegistryReleaseChannel } from "./RegistryReleaseChannel.js";
import { RegistrySearchFacet } from "./RegistrySearchFacet.js";
import { RegistrySearchResults } from "./RegistrySearchResults.js";
import { RegistrySearchSort } from "./RegistrySearchSort.js";
import { RegistryVersion } from "./RegistryVersion.js";
/**
 * Represents an error returned by the registry API.
 *
 * @final
 */
declare class RegistryError extends Error {
    /**
     * Error code.
     */
    readonly code?: string;
    /**
     * Creates a new registry error.
     *
     * @param description Error description.
     * @param [code] Error code.
     */
    constructor(description: string, code?: string);
}
/**
 * Provides methods for interacting with the registry via its HTTP API.
 *
 * @final
 */
export declare class RegistryClient extends HTTPClient<RegistryError> {
    static readonly RegistryError: typeof RegistryError;
    /**
     * Base URL for HTTP requests.
     */
    private readonly baseUrl;
    /**
     * Creates a new registry client.
     *
     * @param userAgent User agent string used when making requests to the registry.
     * @param [token] API authentication token.
     * @param [baseUrl=new URL("https://api.modrinth.com/v2/")] API authentication token. Requires the following scopes:
     *  - `PROJECT_READ`
     *  - `VERSION_READ`
     *
     * Authentication is only needed for accessing private/draft packages and their versions.
     */
    constructor(userAgent: string, token?: string, baseUrl?: URL);
    /**
     * Catches 404 errors and returns null.
     *
     * @param error Error to try to catch.
     * @returns `null` if the error is a 404 error.
     * @throws {@link RegistryClient.RegistryError} If the error is not a 404 error.
     */
    static catch404(error: Error): null;
    /**
     * Retrieves the package associated with the specified ID.
     *
     * @param id Package ID.
     * @returns `null` if the package is not found.
     * @throws {@link RegistryClient.RegistryError} If the request fails.
     * @throws {@link !TypeError} If fetching fails.
     */
    getPackage(id: string): Promise<RegistryPackage | null>;
    /**
     * Retrieves the ID of the package associated with the specified slug.
     *
     * This method returns the ID even for private/draft packages, without requiring authentication.
     *
     * @param slug Package slug.
     * @returns `null` if the package is not found.
     * @throws {@link RegistryClient.RegistryError} If the request fails.
     * @throws {@link !TypeError} If fetching fails.
     */
    getPackageId(slug: string): Promise<string | null>;
    /**
     * Retrieves packages matching the specified search query and facet filters.
     *
     * @param [query] Search query.
     * @param [facets] Facets to filter by.
     * @param [sort] Sort order.
     * @param [offset] Offset into the search.
     * @param [limit] Maximum number of results to return.
     *
     * @see https://docs.modrinth.com/api/operations/searchprojects/ Search projects | Modrinth Documentation
     */
    search(query?: string, facets?: RegistrySearchFacet[][][] | RegistrySearchFacet[][], sort?: RegistrySearchSort, offset?: number, limit?: number): Promise<RegistrySearchResults>;
    /**
     * Retrieves the version associated with the specified version ID.
     *
     * @param id Version ID.
     * @returns `null` if the version is not found.
     * @throws {@link RegistryClient.RegistryError} If the request fails.
     * @throws {@link !TypeError} If fetching fails.
     */
    getVersion(id: string): Promise<RegistryVersion | null>;
    /**
     * Retrieves the versions associated with the specified package.
     *
     * Filters:
     *  - `loaders` — restricts versions to those compatible with the specified loaders.
     *  - `game_versions` — restricts versions to those compatible with the specified game versions.
     *  - `version_type` — restricts versions to those of the specified type (release channel).
     *
     * @param pkg Package ID.
     * @param [filters] Filters to apply.
     * @returns List of matching versions, sorted in descending order, with the latest version first.
     * @throws {@link RegistryClient.RegistryError} If the request fails.
     * @throws {@link !TypeError} If fetching fails.
     */
    listVersions(pkg: string, filters?: {
        loaders?: string[];
        game_versions?: string[];
        version_type?: RegistryReleaseChannel;
    }): Promise<RegistryVersion[] | null>;
    /**
     * Retrieves the packages associated with the specified IDs.
     *
     * @param ids Package IDs.
     * @throws {@link RegistryClient.RegistryError} If the request fails.
     * @throws {@link !TypeError} If fetching fails.
     */
    getPackages(ids: string[]): Promise<RegistryPackage[]>;
    /**
     * Retrieves the version associated with the specified file hash.
     *
     * @param hash SHA-512 hash of the file, encoded as a hex string.
     * @returns `null` if the version is not found.
     * @throws {@link RegistryClient.RegistryError} If the request fails.
     * @throws {@link !TypeError} If fetching fails.
     */
    getVersionByHash(hash: string): Promise<RegistryVersion | null>;
    /**
     * Retrieves the versions associated with the specified hashes.
     *
     * @param hashes SHA-512 hashes of the files, encoded as a hex strings.
     * @throws {@link RegistryClient.RegistryError} If the request fails.
     * @throws {@link !TypeError} If fetching fails.
     */
    getVersionsByHashes(hashes: string[]): Promise<RegistryVersion[]>;
    /**
     * Retrieves the versions associated with the specified version IDs.
     *
     * @param ids Version IDs.
     * @throws {@link RegistryClient.RegistryError} If the request fails.
     * @throws {@link !TypeError} If fetching fails.
     */
    getVersions(ids: string[]): Promise<RegistryVersion[]>;
    /**
     * Retrieves the version associated with the specified package and version number or ID.
     *
     * @param pkg Package ID.
     * @param version Version number or ID.
     * @returns `null` if the package or version is not found.
     * @throws {@link RegistryClient.RegistryError} If the request fails.
     * @throws {@link !TypeError} If fetching fails.
     */
    getVersionByNumber(pkg: string, version: string): Promise<RegistryVersion | null>;
    /**
     * Retrieves the latest versions associated with the specified hashes.
     *
     * Filters:
     *   - `loaders` — restricts versions to those compatible with the specified loaders.
     *   - `game_versions` — restricts versions to those compatible with the specified game versions.
     *   - `version_type` — restricts versions to those of the specified type (release channel).
     *
     * @param hashes SHA-512 hashes of the files, encoded as a hex strings.
     * @param [filters] Filters to apply.
     * @throws {@link RegistryClient.RegistryError} If the request fails.
     * @throws {@link !TypeError} If fetching fails.
     */
    getLatestVersions(hashes: string[], filters?: {
        loaders?: string[];
        game_versions?: string[];
        version_type?: RegistryReleaseChannel;
    }): Promise<Record<string, RegistryVersion>>;
    /**
     * Retrieves all loaders supported by the registry.
     *
     * @throws {@link RegistryClient.RegistryError} If the request fails.
     * @throws {@link !TypeError} If fetching fails.
     */
    getLoaders(): Promise<string[]>;
    createError(res: Response): Promise<RegistryError>;
    /**
     * Sends an HTTP request.
     *
     * @param path Relative path to the API endpoint.
     * @param [options] Request options.
     * @param [query] Query parameters.
     * @param [retries=3] Maximum number of retry attempts performed if the request fails.
     * @throws {@link RegistryClient.RegistryError} If the request fails with a permanent error, allowed retries
     *     already exceeded, or delay is more than 30 seconds.
     * @throws {@link !TypeError} If the request fails due to a native fetch error, like a network error, DNS error,
     *     timeout, etc.
     * @final
     */
    protected fetch(path: string[], options?: RequestInit, query?: URLSearchParams, retries?: number): Promise<Response>;
    /**
     * Sends an HTTP request.
     *
     * @param url Absolute URL.
     * @param [options] Request options.
     * @param [query] Query parameters.
     * @param [retries=3] Maximum number of retry attempts performed if the request fails.
     * @throws {@link RegistryClient.RegistryError} If the request fails with a permanent error, allowed retries
     *     already exceeded, or delay is more than 30 seconds.
     * @throws {@link !TypeError} If the request fails due to a native fetch error, like a network error, DNS error,
     *     timeout, etc.
     * @final
     */
    protected fetch(url: URL | string, options?: RequestInit, query?: URLSearchParams, retries?: number): Promise<Response>;
}
export {};