bc-api-client/dist/client.d.ts

A client for the BigCommerce management API and app authentication

import { Logger } from './core';
import { RateLimitOptions, RequestOptions, StoreOptions } from './net';
/**
 * Options for GET requests to the BigCommerce API
 */
export type GetOptions = {
    /** Query parameters to include in the request */
    query?: Record<string, string>;
    /** API version to use (v2 or v3) */
    version?: 'v2' | 'v3';
};
/**
 * Options for POST/PUT requests to the BigCommerce API
 */
export type PostOptions<T> = GetOptions & {
    /** Request body data */
    body: T;
};
/**
 * Options for controlling concurrent request behavior
 */
export type ConcurrencyOptions = {
    /** Maximum number of concurrent requests (default: 10) */
    concurrency?: number;
    /** Whether to skip errors and continue processing (default: false) */
    skipErrors?: boolean;
};
/**
 * Options for querying multiple values against a single filter field
 */
export type QueryOptions = Omit<GetOptions, 'version'> & ConcurrencyOptions & {
    /** The field name to query against */
    key: string;
    /** Array of values to query for */
    values: (string | number)[];
};
/**
 * Configuration options for the BigCommerce client
 */
export type Config = StoreOptions & RateLimitOptions & ConcurrencyOptions & {
    /** Logger instance */
    logger?: Logger;
};
/**
 * Client for interacting with the BigCommerce API
 *
 * This client provides methods for making HTTP requests to the BigCommerce API,
 * with support for both v2 and v3 endpoints, pagination, and concurrent requests.
 */
export declare class BigCommerceClient {
    private readonly config;
    /**
     * Creates a new BigCommerce client instance
     * @param config - Configuration options for the client
     * @param config.storeHash - The store hash to use for the client
     * @param config.accessToken - The API access token to use for the client
     * @param config.maxRetries - The maximum number of retries for rate limit errors (default: 5)
     * @param config.maxDelay - Maximum time to wait to retry in case of rate limit errors in milliseconds (default: 60000 - 1 minute). If `X-Rate-Limit-Time-Reset-Ms` header is higher than `maxDelay`, the request will fail immediately.
     * @param config.concurrency - The default concurrency for concurrent methods (default: 10)
     * @param config.skipErrors - Whether to skip errors during concurrent requests (default: false)
     * @param config.logger - Optional logger instance for debugging and error tracking
     */
    constructor(config: Config);
    /**
     * Makes a GET request to the BigCommerce API
     * @param endpoint - The API endpoint to request
     * @param options.query - Query parameters to include in the request
     * @param options.version - API version to use (v2 or v3) (default: v3)
     * @returns Promise resolving to the response data of type `R`
     */
    get<R>(endpoint: string, options?: GetOptions): Promise<R>;
    /**
     * Makes a POST request to the BigCommerce API
     * @param endpoint - The API endpoint to request
     * @param options.query - Query parameters to include in the request
     * @param options.version - API version to use (v2 or v3) (default: v3)
     * @param options.body - Request body data of type `T`
     * @returns Promise resolving to the response data of type `R`
     */
    post<T, R>(endpoint: string, options?: PostOptions<T>): Promise<R>;
    /**
     * Makes a PUT request to the BigCommerce API
     * @param endpoint - The API endpoint to request
     * @param options.query - Query parameters to include in the request
     * @param options.version - API version to use (v2 or v3) (default: v3)
     * @param options.body - Request body data of type `T`
     * @returns Promise resolving to the response data of type `R`
     */
    put<T, R>(endpoint: string, options?: PostOptions<T>): Promise<R>;
    /**
     * Makes a DELETE request to the BigCommerce API
     * @param endpoint - The API endpoint to delete
     * @param options.version - API version to use (v2 or v3) (default: v3)
     * @returns Promise resolving to void
     */
    delete<R>(endpoint: string, options?: Pick<GetOptions, 'version'>): Promise<void>;
    /**
     * Executes multiple requests concurrently with controlled concurrency
     * @param requests - Array of request options to execute
     * @param options.concurrency - Maximum number of concurrent requests, overrides the client's concurrency setting (default: 10)
     * @param options.skipErrors - Whether to skip errors and continue processing (the errors will be logged if logger is provided), overrides the client's skipErrors setting (default: false)
     * @returns Promise resolving to array of response data
     */
    concurrent<T, R>(requests: RequestOptions<T>[], options?: ConcurrencyOptions): Promise<R[]>;
    /**
     * Lowest level concurrent request method.
     * This method executes requests in chunks and returns bare PromiseSettledResult objects.
     * Use this method if you need to handle errors in a custom way.
     * @param requests - Array of request options to execute
     * @param options.concurrency - Maximum number of concurrent requests, overrides the client's concurrency setting (default: 10)
     * @returns Promise resolving to array of PromiseSettledResult containing both successful and failed requests
     */
    concurrentSettled<T, R>(requests: RequestOptions<T>[], options?: Pick<ConcurrencyOptions, 'concurrency'>): Promise<PromiseSettledResult<R>[]>;
    /**
     * Collects all pages of data from a paginated v3 API endpoint.
     * This method pulls the first page and uses pagination meta to collect the remaining pages concurrently.
     * @param endpoint - The API endpoint to request
     * @param options.query - Query parameters to include in the request
     * @param options.concurrency - Maximum number of concurrent requests, overrides the client's concurrency setting (default: 10)
     * @param options.skipErrors - Whether to skip errors and continue processing (the errors will be logged if logger is provided), overrides the client's skipErrors setting (default: false)
     * @returns Promise resolving to array of all items across all pages
     */
    collect<T>(endpoint: string, options?: Omit<GetOptions, 'version'> & ConcurrencyOptions): Promise<T[]>;
    /**
     * Collects all pages of data from a paginated v2 API endpoint.
     * This method simply pulls all pages concurrently until a 204 is returned in a batch.
     * @param endpoint - The API endpoint to request
     * @param options.query - Query parameters to include in the request
     * @param options.concurrency - Maximum number of concurrent requests, overrides the client's concurrency setting (default: 10)
     * @param options.skipErrors - Whether to skip errors and continue processing (the errors will be logged if logger is provided), overrides the client's skipErrors setting (default: false)
     * @returns Promise resolving to array of all items across all pages
     */
    collectV2<T>(endpoint: string, options?: Omit<GetOptions, 'version'> & ConcurrencyOptions): Promise<T[]>;
    /**
     * Queries multiple values against a single field using the v3 API.
     * If the url + query params are too long, the query will be chunked. Otherwise, this method acts like `collect`.
     * This method does not check for uniqueness of the `values` array.
     *
     * @param endpoint - The API endpoint to request
     * @param options.key - The field name to query against e.g. `sku:in`
     * @param options.values - Array of values to query for e.g. `['123', '456', ...]`
     * @param options.query - Additional query parameters
     * @param options.concurrency - Maximum number of concurrent requests, overrides the client's concurrency setting (default: 10)
     * @param options.skipErrors - Whether to skip errors and continue processing (the errors will be logged if logger is provided), overrides the client's skipErrors setting (default: false)
     * @returns Promise resolving to array of matching items
     */
    query<T>(endpoint: string, options: QueryOptions): Promise<T[]>;
}