cmc-api
Version:
CoinMarketCap RESTful API Wrapper
133 lines (132 loc) • 6.38 kB
TypeScript
import type { CmcStatusResponse } from "../responses/status.response";
/**
* The `Client` class provides methods to interact with the CoinMarketCap API.
* It allows sending HTTP GET requests, setting API keys, and handling errors.
*
* @remarks
* This class includes methods for generating URIs with query parameters,
* generating HTTP headers, and handling various error codes returned by the API.
*
* @example
* ```typescript
* import { CoinMarketCapApi } from "..";
*
* const apikey = process.env.COINMARKETCAP_APIKEY;
* const cmc = new CoinMarketCapApi(apikey);
*
* const data = await cmc.client.req('/v1/cryptocurrency/map');
* console.log(data);
* ```
*/
export declare class Client {
/**
* Represents the status of the CMC response.
*/
status: CmcStatusResponse;
/**
* Callback function to handle errors that occur during a request.
*
* @param request - The URL of the request that caused the error.
* @param response - The response object associated with the error.
*/
onError: (request: URL, response: unknown) => void;
/**
* Initializes a new instance of the `Client` class.
* The constructor sets the base URL to the Pro API by default.
*/
constructor();
/**
* Send an HTTP GET request to the specified endpoint with optional query parameters and headers.
*
* @template TData - The expected type of the response data.
* @template TQuery - The type of the query parameters, defaults to `Record<string, string | number | (string | number)[] | boolean>`.
* @param {string} endpoint - The API endpoint to send the request to.
* @param {TQuery} [query] - Optional query parameters to include in the request.
* @param {Record<string, string>} [headers] - Optional headers to include in the request.
* @returns {Promise<TData>} - A promise that resolves to the response data of type `TData`.
* @throws {CmcErrorClass} Will throw an error if the response status indicates an error.
*/
req<TData = unknown, TQuery = Record<string, string | number | (string | number)[] | boolean>>(endpoint: string, query?: TQuery, headers?: Record<string, string>): Promise<TData>;
/**
* Set the API key for the client.
*
* @param apiKey - The API key to be set.
* @returns The client instance with the API key set.
* @example
* ```typescript
* const apikey = process.env.COINMARKETCAP_APIKEY;
* const cmc = new CoinMarketCapApi(apikey);
* cmc.client.setApiKey('dfa3195f-f1d4-f1c1-a1fa-83461b5f42eb');
* ```
*/
setApiKey(apiKey: string): Client;
/**
* Set the base URL for the client.
*
* @param {string} baseUrl - The base URL to be set.
* @returns The client instance with the base URL set.
* @example
* ```typescript
* const apikey = process.env.COINMARKETCAP_APIKEY;
* const cmc = new CoinMarketCapApi(apikey);
* cmc.client.setBaseUrl('https://sandbox-api.coinmarketcap.com');
* ```
*/
setBaseUrl(baseUrl: string): Client;
/**
* Converts an array of strings into a single comma-separated string.
* If the input is already a string, it returns the input as is.
*
* @template TValue - The type of the input value, defaults to `string | number | (string | number)[]`.
* @param {TValue} value - The input which can be either a string or an array of strings.
* @returns A comma-separated string if the input is an array, otherwise the input string.
*/
commaSeparate<TValue = string | number | (string | number)[]>(value: TValue): string;
/**
* Set up the client to use the CoinMarketCap API sandbox environment.
* This method sets the API key to the sandbox key and the base URL to the sandbox URL.
* @returns The client instance with the sandbox environment set.
*/
sandbox(): Client;
/**
* Generates a complete URI with query parameters.
*
* @template TQuery - The type of the query parameters, defaults to `Record<string, string | number | (string | number)[] | boolean>`.
* @param {string} endpoint - The endpoint to append to the base URL.
* @param {TQuery} [query] - An optional object containing query parameters as key-value pairs.
* @returns {URL} - The generated URL with the provided endpoint and query parameters.
*/
private genUri;
/**
* Generates HTTP headers for the API request.
*
* @param additionHeaders - An object containing additional headers to be included in the request.
* @returns A Headers object with the API key and any additional headers appended.
*
* @see {@link Headers}
*/
private genHeaders;
/**
* Handles errors based on the provided {@link CmcStatusResponse} and returns an appropriate {@link CmcErrorClass} instance.
*
* @param {CmcStatusResponse} status - The status object containing the error code and other relevant information.
* @param {any} data - Optional additional data related to the error.
* @returns An instance of a class extending {@link CmcErrorClass} that corresponds to the specific error code.
*
* The method maps the following error codes to their respective error classes:
* - {@link CmcErrorCode.ApikeyInvalid} for {@link CmcInvalidError}
* - {@link CmcErrorCode.ApikeyMissing} for {@link CmcMissingError}
* - {@link CmcErrorCode.ApikeyPlanRequiresPayment} for {@link CmcPaymentRequiredError}
* - {@link CmcErrorCode.ApikeyPlanPaymentExpired} for {@link CmcPaymentExpiredError}
* - {@link CmcErrorCode.ApikeyRequired} for {@link CmcApikeyRequiredError}
* - {@link CmcErrorCode.ApikeyPlanNotAuthorized} for {@link CmcPlanUnauthorizeError}
* - {@link CmcErrorCode.ApikeyDisable} for {@link CmcApikeyDisabledError}
* - {@link CmcErrorCode.ApikeyPlanMinuteRateLimitReached} for {@link CmcMinuteRateLimitError}
* - {@link CmcErrorCode.ApikeyPlanDailyRateLimitReached} for {@link CmcDailyRateLimitError}
* - {@link CmcErrorCode.ApikeyPlanMonthlyRateLimitReached} for {@link CmcMonthlyRateLimitError}
* - {@link CmcErrorCode.IpRateLimitReached} for {@link CmcIpRateLimitError}
*
* If the error code does not match any of the above, a generic {@link CmcRequestError} is returned.
*/
private error;
}