bc-api-client 0.1.0-beta.1 → 0.1.0-beta.10

package/README.md

@@ -2,7 +2,7 @@
 
 <span style="color:orange">BETA VERSION - Use at your own risk</span>
 
-An opinionated and minimalistic client focusing on simplicity and performance.
+An opinionated and minimalistic client focusing on simplicity and concurrent performance.
 Features (or antifeatures - depends on your opinion)
 - Node 20+ LTS, ESM
 - Bring Your Own Types
@@ -12,6 +12,19 @@ Features (or antifeatures - depends on your opinion)
 - Rate limit handling
 - App authenticator module. Request token and verify JWT.
 
+⚠️ **Disclaimer**: This library provides concurrent request capabilities. BigCommerce has strict rate limits that vary by plan and endpoint. The author is not responsible for any issues arising from improper API usage. Use at your own risk.
+
+## Table of Contents
+- [Installation](#installation)
+- [Usage](#usage)
+  - [API Client](#api-client)
+  - [Authentication](#authentication)
+- [API](#api)
+  - [BigCommerceClient](#bigcommerceclient)
+  - [BigCommerceAuth](#bigcommerceauth)
+- [Tips](#tips)
+- [License](#license)
+
 ## Installation
 
 ```bash
@@ -45,8 +58,7 @@ const client = new BigCommerceClient({
 });
 
 // Basic GET request
-const products = await client.get<V3Response<MyProduct[]>>({
-  endpoint: bc.products.path,
+const products = await client.get<V3Response<MyProduct[]>>(bc.products.path, {
   query: { 'include_fields': fields },
 });
 
@@ -63,8 +75,7 @@ const results = await client.concurrent<never, V3Response<MyProduct>>(
 );
 
 // Collect all pages from v3 endpoint
-const allProducts = await client.collect<MyProduct>({
-  endpoint: bc.products.path,
+const allProducts = await client.collect<MyProduct>(bc.products.path, {
   query: {
     include_fields: fields,
   },
@@ -78,8 +89,7 @@ type MyOrder = {
     status: string;
 }
 
-const orders = await client.collectV2<MyOrder>({
-  endpoint: bc.orders.v2.path,
+const orders = await client.collectV2<MyOrder>(bc.orders.v2.path, {
   query: {
     limit: '5',
   },
@@ -91,8 +101,7 @@ const orders = await client.collectV2<MyOrder>({
 // Note: productIds would be a large array of IDs in a real scenario
 const productIds = [1, 2, 3, 4, 5]; // Example IDs
 
-const filteredProducts = await client.query<MyProduct>({
-  endpoint: bc.products.path,
+const filteredProducts = await client.query<MyProduct>(bc.products.path, {
   key: 'id:in',
   values: productIds,
   query: {
@@ -112,60 +121,114 @@ const auth = new BigCommerceAuth({
   clientId: 'your-client-id',
   secret: 'your-client-secret',
   redirectUri: 'your-redirect-uri',
-  storeHash: 'your-store-hash'
 });
 
 // Request token
 const token = await auth.requestToken(authQuery);
 
 // Verify JWT
-const claims = await auth.verify(jwtPayload);
+const claims = await auth.verify(jwtPayload, 'your-store-hash');
 ```
 
 ## API
 
 ### BigCommerceClient
 
-#### `get<R>(options: GetOptions): Promise<R>`
+#### Constructor
+```typescript
+new BigCommerceClient(config: {
+    storeHash: string;
+    accessToken: string;
+    maxRetries?: number;      // default: 5
+    maxDelay?: number;        // default: 60000 (1 minute)
+    concurrency?: number;     // default: 10
+    skipErrors?: boolean;     // default: false
+    logger?: Logger;          // optional
+})
+```
+
+#### `get<R>(endpoint: string, options?: GetOptions): Promise<R>`
 Makes a GET request to the BigCommerce API.
+- `endpoint`: The API endpoint to request
+- `options.query`: Query parameters to include in the request
+- `options.version`: API version to use (v2 or v3, default: v3)
 
-#### `post<T, R>(options: PostOptions<T>): Promise<R>`
+#### `post<T, R>(endpoint: string, options?: PostOptions<T>): Promise<R>`
 Makes a POST request to the BigCommerce API.
+- `endpoint`: The API endpoint to request
+- `options.query`: Query parameters to include in the request
+- `options.version`: API version to use (v2 or v3, default: v3)
+- `options.body`: Request body data of type `T`
 
-#### `put<T, R>(options: PostOptions<T>): Promise<R>`
+#### `put<T, R>(endpoint: string, options?: PostOptions<T>): Promise<R>`
 Makes a PUT request to the BigCommerce API.
+- `endpoint`: The API endpoint to request
+- `options.query`: Query parameters to include in the request
+- `options.version`: API version to use (v2 or v3, default: v3)
+- `options.body`: Request body data of type `T`
 
-#### `delete<R>(endpoint: string): Promise<void>`
+#### `delete<R>(endpoint: string, options?: Pick<GetOptions, 'version'>): Promise<void>`
 Makes a DELETE request to the BigCommerce API.
-
-#### `concurrent<T, R>(requests: RequestOptions<T>[], options: ConcurrencyOptions): Promise<R[]>`
-Executes multiple requests concurrently with rate limit handling. Options:
-- `concurrency`: number of concurrent requests (default: 10)
-- `skipErrors`: whether to skip failed requests instead of throwing (default: false)
-
-#### `collect<T>(options: Omit<GetOptions, 'version'> & ConcurrencyOptions): Promise<T[]>`
-Automatically fetches all pages of a paginated v3 endpoint. Supports the same concurrency options as `concurrent`.
-
-#### `collectV2<T>(options: Omit<GetOptions, 'version'> & ConcurrencyOptions): Promise<T[]>`
-Automatically fetches all pages of a paginated v2 endpoint. Supports the same concurrency options as `concurrent`.
-
-#### `query<T>(options: QueryOptions): Promise<T[]>`
-Executes a query with multiple filter values, automatically handling large value sets by chunking them into smaller requests. Options:
-- `endpoint`: API endpoint to query
-- `key`: Filter key (e.g. 'id:in')
-- `values`: Array of values to filter by
-- `query`: Additional query parameters
-- `concurrency`: number of concurrent requests (default: 10)
-- `skipErrors`: whether to skip failed requests instead of throwing (default: false)
+- `endpoint`: The API endpoint to delete
+- `options.version`: API version to use (v2 or v3, default: v3)
+
+#### `concurrent<T, R>(requests: RequestOptions<T>[], options?: ConcurrencyOptions): Promise<R[]>`
+Executes multiple requests concurrently with rate limit handling.
+- `requests`: Array of request options to execute
+- `options.concurrency`: Maximum number of concurrent requests (default: 10)
+- `options.skipErrors`: Whether to skip errors and continue processing (default: false)
+
+#### `collect<T>(endpoint: string, options: Omit<GetOptions, 'version'> & ConcurrencyOptions): Promise<T[]>`
+Automatically fetches all pages of a paginated v3 endpoint. Pulls the first page and uses pagination meta to collect remaining pages concurrently.
+- `endpoint`: The API endpoint to request
+- `options.query`: Query parameters to include in the request (limit defaults to 250)
+- `options.concurrency`: Maximum number of concurrent requests (default: 10)
+- `options.skipErrors`: Whether to skip errors and continue processing (default: false)
+
+#### `collectV2<T>(endpoint: string, options: Omit<GetOptions, 'version'> & ConcurrencyOptions): Promise<T[]>`
+Automatically fetches all pages of a paginated v2 endpoint. Pulls all pages concurrently until a 204 is returned.
+- `endpoint`: The API endpoint to request
+- `options.query`: Query parameters to include in the request (limit defaults to 250)
+- `options.concurrency`: Maximum number of concurrent requests (default: 10)
+- `options.skipErrors`: Whether to skip errors and continue processing (default: false)
+
+#### `query<T>(endpoint: string, options: QueryOptions): 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.
+- `endpoint`: The API endpoint to request
+- `options.key`: The field name to query against (e.g. 'id:in')
+- `options.values`: Array of values to query for
+- `options.query`: Additional query parameters (limit defaults to 250)
+- `options.concurrency`: Maximum number of concurrent requests (default: 10)
+- `options.skipErrors`: Whether to skip errors and continue processing (default: false)
 
 ### BigCommerceAuth
 
-#### `requestToken(data: string | AuthQuery): Promise<TokenResponse>`
+#### Constructor
+```typescript
+new BigCommerceAuth(config: {
+    clientId: string;
+    secret: string;
+    redirectUri: string;
+    scopes?: string[];        // optional
+    logger?: Logger;          // optional
+})
+```
+
+#### `requestToken(data: string | UrlSearchParams | AuthQuery): Promise<TokenResponse>`
 Requests an access token from BigCommerce OAuth.
 
-#### `verify(jwtPayload: string): Promise<Claims>`
+#### `verify(jwtPayload: string, storeHash: string): Promise<Claims>`
 Verifies a JWT payload from BigCommerce.
 
+## Tips
+
+- I made this library based on my experience of building real-time integrations. It might not be the best choice if you just need to make simple requests or want built-in types. Also, if you're not on enterprise - you can't realistically get much benefit from concurrency, so this library can offer zero to negative (getting throttled) benefit. Check out [this client](https://github.com/kzhang-dsg/bigcommerce-api-client) for a more extensive solution with much better DX. You can also use that library as a source of types and this one for concurrency if you don't mind having two installed.
+- Be careful with concurrent methods as they might get you flagged, especially if you are not working with enterprise stores (which I mostly do). Also, some endpoints have explicit concurrency limits. Check the documentation.
+- Utilize `include_fields` when available and make simplified types to include only the properties you need. This will increase the speed and efficiency of the requests significantly and improve DX as your autocomplete won't be cluttered.
+- Use `query` if you need to fetch, for example, customers from a list of emails, or products from a list of SKUs.
+- This library will not wait for a rate limit longer than 60 seconds by default. I mostly work on real-time applications, so it doesn't make sense to wait longer for me. If you need a longer timeout, pass `maxDelay` to the `BigCommerceClient` constructor.
+- Be careful with endpoints. I populated them manually from the docs and ran them through Claude as a double-check. You can make an issue if something throws a 404, and use the string meanwhile. Also, some may be missing - always check the documentation for your request.
+
 ## License
 
 MIT

package/dist/auth.d.ts

@@ -1,3 +1,4 @@
+import { Logger } from './core';
 /**
  * Configuration options for BigCommerce authentication
  */
@@ -8,10 +9,10 @@ type Config = {
     secret: string;
     /** The redirect URI registered with BigCommerce */
     redirectUri: string;
-    /** The store hash for the BigCommerce store */
-    storeHash: string;
     /** Optional array of scopes to validate during auth callback */
     scopes?: string[];
+    /** Optional logger instance */
+    logger?: Logger;
 };
 /**
  * Query parameters received from BigCommerce auth callback
@@ -94,24 +95,30 @@ export type Claims = {
 export declare class BigCommerceAuth {
     private readonly config;
     /**
-     * Creates a new BigCommerceAuth instance
+     * 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 or AuthQuery object containing auth callback data
+     * @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): Promise<TokenResponse>;
+    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): Promise<Claims>;
+    verify(jwtPayload: string, storeHash: string): Promise<Claims>;
     /**
      * Parses and validates a query string from BigCommerce auth callback
      * @param queryString - The query string to parse

package/dist/client.d.ts

@@ -1,30 +1,139 @@
+import { Logger } from './core';
 import { RateLimitOptions, RequestOptions, StoreOptions } from './net';
+/**
+ * Options for GET requests to the BigCommerce API
+ */
 export type GetOptions = {
-    endpoint: string;
+    /** 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)[];
 };
-export type Config = StoreOptions & RateLimitOptions;
+/**
+ * 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);
-    get<R>(options: GetOptions): Promise<R>;
-    post<T, R>(options: PostOptions<T>): Promise<R>;
-    put<T, R>(options: PostOptions<T>): Promise<R>;
-    delete<R>(endpoint: string): Promise<void>;
-    concurrent<T, R>(requests: RequestOptions<T>[], options: ConcurrencyOptions): Promise<R[]>;
-    collect<T>(options: Omit<GetOptions, 'version'> & ConcurrencyOptions): Promise<T[]>;
-    collectV2<T>(options: Omit<GetOptions, 'version'> & ConcurrencyOptions): Promise<T[]>;
-    query<T>(options: QueryOptions): Promise<T[]>;
+    /**
+     * 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, 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[]>;
+    /**
+     * 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, 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, 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, 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

@@ -16,3 +16,12 @@ export type V3Resource<T> = {
         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;
+}