bc-api-client 0.1.4 → 0.2.0

package/dist/auth.d.ts

@@ -0,0 +1,134 @@
+import { Logger } from './core';
+/**
+ * Configuration options for BigCommerce authentication
+ */
+type Config = {
+    /** The OAuth client ID from BigCommerce */
+    clientId: string;
+    /** The OAuth client secret from BigCommerce */
+    secret: string;
+    /** The redirect URI registered with BigCommerce */
+    redirectUri: string;
+    /** Optional array of scopes to validate during auth callback */
+    scopes?: string[];
+    /** Optional logger instance */
+    logger?: Logger;
+};
+/**
+ * Query parameters received from BigCommerce auth callback
+ */
+type AuthQuery = {
+    /** The authorization code from BigCommerce */
+    code: string;
+    /** The granted OAuth scopes */
+    scope: string;
+    /** The store context */
+    context: string;
+};
+/**
+ * User information returned from BigCommerce
+ */
+export type User = {
+    /** The user's ID */
+    id: number;
+    /** The user's username */
+    username: string;
+    /** The user's email address */
+    email: string;
+};
+/**
+ * Response from BigCommerce token endpoint
+ */
+export type TokenResponse = {
+    /** The OAuth access token */
+    access_token: string;
+    /** The granted OAuth scopes */
+    scope: string;
+    /** Information about the authenticated user */
+    user: User;
+    /** Information about the store owner */
+    owner: User;
+    /** The store context */
+    context: string;
+    /** The BigCommerce account UUID */
+    account_uuid: string;
+};
+/**
+ * JWT claims from BigCommerce
+ */
+export type Claims = {
+    /** JWT audience */
+    aud: string;
+    /** JWT issuer */
+    iss: string;
+    /** JWT issued at timestamp */
+    iat: number;
+    /** JWT not before timestamp */
+    nbf: number;
+    /** JWT expiration timestamp */
+    exp: number;
+    /** JWT unique identifier */
+    jti: string;
+    /** JWT subject */
+    sub: string;
+    /** Information about the authenticated user */
+    user: {
+        id: number;
+        email: string;
+        locale: string;
+    };
+    /** Information about the store owner */
+    owner: {
+        id: number;
+        email: string;
+    };
+    /** The store URL */
+    url: string;
+    /** The channel ID (if applicable) */
+    channel_id: number | null;
+};
+/**
+ * Handles authentication with BigCommerce OAuth
+ */
+export declare class BigCommerceAuth {
+    private readonly config;
+    /**
+     * Creates a new BigCommerceAuth instance for handling OAuth authentication
+     * @param config - Configuration options for BigCommerce authentication
+     * @param config.clientId - The OAuth client ID from BigCommerce
+     * @param config.secret - The OAuth client secret from BigCommerce
+     * @param config.redirectUri - The redirect URI registered with BigCommerce
+     * @param config.scopes - Optional array of scopes to validate during auth callback
+     * @param config.logger - Optional logger instance for debugging and error tracking
+     * @throws {Error} If the redirect URI is invalid
+     */
+    constructor(config: Config);
+    /**
+     * Requests an access token from BigCommerce
+     * @param data - Either a query string, URLSearchParams, or AuthQuery object containing auth callback data
+     * @returns Promise resolving to the token response
+     */
+    requestToken(data: string | AuthQuery | URLSearchParams): Promise<TokenResponse>;
+    /**
+     * Verifies a JWT payload from BigCommerce
+     * @param jwtPayload - The JWT string to verify
+     * @param storeHash - The store hash for the BigCommerce store
+     * @returns Promise resolving to the verified JWT claims
+     * @throws {Error} If the JWT is invalid
+     */
+    verify(jwtPayload: string, storeHash: string): Promise<Claims>;
+    /**
+     * Parses and validates a query string from BigCommerce auth callback
+     * @param queryString - The query string to parse
+     * @returns The parsed auth query parameters
+     * @throws {Error} If required parameters are missing or scopes are invalid
+     */
+    private parseQueryString;
+    /**
+     * Validates that the granted scopes match the expected scopes
+     * @param scopes - Space-separated list of granted scopes
+     * @throws {Error} If the scopes don't match the expected scopes
+     */
+    private validateScopes;
+}
+export {};

package/dist/client.d.ts

@@ -0,0 +1,149 @@
+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.baseUrl - The base URL to use for the client (default: https://api.bigcommerce.com)
+     * @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' | 'query'>): 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[]>;
+}

package/dist/core.d.ts

@@ -0,0 +1,27 @@
+export type Pagination = {
+    total: number;
+    count: number;
+    per_page: number;
+    current_page: number;
+    total_pages: number;
+    links: {
+        previous: string | null;
+        current: string;
+        next: string | null;
+    };
+};
+export type V3Resource<T> = {
+    data: T;
+    meta: {
+        pagination: Pagination;
+    };
+};
+/**
+ * Logger interface for logging messages and data, Pino compatible by default
+ */
+export interface Logger {
+    debug: (data: unknown, message?: string) => void;
+    info: (data: unknown, message?: string) => void;
+    warn: (data: unknown, message?: string) => void;
+    error: (data: unknown, message?: string) => void;
+}