bc-api-client 0.1.0-beta.8 → 0.1.3

package/README.md

@@ -4,6 +4,7 @@
 
 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
 - Basic API methods (get, post, put, delete)
@@ -15,13 +16,14 @@ Features (or antifeatures - depends on your opinion)
 ⚠️ **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 Client](#api-client)
+    - [Authentication](#authentication)
 - [API](#api)
-  - [BigCommerceClient](#bigcommerceclient)
-  - [BigCommerceAuth](#bigcommerceauth)
+    - [BigCommerceClient](#bigcommerceclient)
+    - [BigCommerceAuth](#bigcommerceauth)
 - [Tips](#tips)
 - [License](#license)
 
@@ -48,53 +50,53 @@ type MyProduct = {
     name: string;
     sku: string;
     inventory_level: number;
-}
+};
 
 const fields = 'id,name,sku,inventory_level';
 
 const client = new BigCommerceClient({
-  storeHash: 'your-store-hash',
-  accessToken: 'your-access-token'
+    storeHash: 'your-store-hash',
+    accessToken: 'your-access-token',
 });
 
 // Basic GET request
 const products = await client.get<V3Response<MyProduct[]>>(bc.products.path, {
-  query: { 'include_fields': fields },
+    query: { include_fields: fields },
 });
 
 // Low level concurrent requests with error handling
 const results = await client.concurrent<never, V3Response<MyProduct>>(
-  [
-    { method: 'GET', endpoint: bc.products.byId(1), query: { include_fields: fields }},
-    { method: 'GET', endpoint: bc.products.byId(2), query: { include_fields: fields }},
-  ],
-  { 
-    concurrency: 10,
-    skipErrors: true // Optional: skip failed requests instead of throwing
-  }
+    [
+        { method: 'GET', endpoint: bc.products.byId(1), query: { include_fields: fields } },
+        { method: 'GET', endpoint: bc.products.byId(2), query: { include_fields: fields } },
+    ],
+    {
+        concurrency: 10,
+        skipErrors: true, // Optional: skip failed requests instead of throwing
+    },
 );
 
 // Collect all pages from v3 endpoint
 const allProducts = await client.collect<MyProduct>(bc.products.path, {
-  query: {
-    include_fields: fields,
-  },
-  concurrency: 10, // Optional: control concurrent requests
-  skipErrors: true // Optional: skip failed requests
+    query: {
+        include_fields: fields,
+    },
+    concurrency: 10, // Optional: control concurrent requests
+    skipErrors: true, // Optional: skip failed requests
 });
 
 // Collect all pages from v2 endpoint
 type MyOrder = {
     id: number;
     status: string;
-}
+};
 
 const orders = await client.collectV2<MyOrder>(bc.orders.v2.path, {
-  query: {
-    limit: '5',
-  },
-  concurrency: 10, // Optional: control concurrent requests
-  skipErrors: true // Optional: skip failed requests
+    query: {
+        limit: '5',
+    },
+    concurrency: 10, // Optional: control concurrent requests
+    skipErrors: true, // Optional: skip failed requests
 });
 
 // Query with multiple filter values
@@ -102,13 +104,13 @@ const orders = await client.collectV2<MyOrder>(bc.orders.v2.path, {
 const productIds = [1, 2, 3, 4, 5]; // Example IDs
 
 const filteredProducts = await client.query<MyProduct>(bc.products.path, {
-  key: 'id:in',
-  values: productIds,
-  query: {
-    include_fields: fields,
-  },
-  concurrency: 10, // Optional: control concurrent requests
-  skipErrors: true // Optional: skip failed requests
+    key: 'id:in',
+    values: productIds,
+    query: {
+        include_fields: fields,
+    },
+    concurrency: 10, // Optional: control concurrent requests
+    skipErrors: true, // Optional: skip failed requests
 });
 ```
 
@@ -118,70 +120,106 @@ const filteredProducts = await client.query<MyProduct>(bc.products.path, {
 import { BigCommerceAuth } from 'bigcommerce-client';
 
 const auth = new BigCommerceAuth({
-  clientId: 'your-client-id',
-  secret: 'your-client-secret',
-  redirectUri: 'your-redirect-uri',
-  storeHash: 'your-store-hash'
+    clientId: 'your-client-id',
+    secret: 'your-client-secret',
+    redirectUri: 'your-redirect-uri',
 });
 
 // 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
 
+#### 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>(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>(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, options?: Pick<GetOptions, 'version'>): Promise<void>`
+
 Makes a DELETE request to the BigCommerce API.
+
 - `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 (the errors will be logged if logger is provided), default: false)
+
+#### `concurrentSettled<T, R>(requests: RequestOptions<T>[], options?: Pick<ConcurrencyOptions, 'concurrency'>): Promise<PromiseSettledResult<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.
+
 - `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
@@ -191,10 +229,24 @@ Queries multiple values against a single field using the v3 API. If the URL + qu
 
 ### 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
@@ -209,4 +261,3 @@ Verifies a JWT payload from BigCommerce.
 ## License
 
 MIT
-

package/package.json

@@ -1,70 +1,71 @@
 {
-  "name": "bc-api-client",
-  "version": "0.1.0-beta.8",
-  "description": "A client for the BigCommerce management API and app authentication",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "type": "module",
-  "exports": {
-    ".": "./dist/index.js",
-    "./endpoints": "./dist/endpoints.js",
-    "./package.json": "./package.json"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/kernelpanic99/bc-api-client"
-  },
-  "homepage": "https://github.com/kernelpanic99/bc-api-client",
-  "bugs": {
-    "url": "https://github.com/kernelpanic99/bc-api-client/issues"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "keywords": [
-    "bigcommerce",
-    "api",
-    "client",
-    "typescript",
-    "jwt",
-    "authentication"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "author": "Arthur Nikolaienko",
-  "license": "MIT",
-  "devDependencies": {
-    "@eslint/js": "^9.25.1",
-    "@types/jsonwebtoken": "^9.0.9",
-    "@types/node": "^22.15.3",
-    "dotenv": "^16.5.0",
-    "esbuild": "^0.25.3",
-    "esbuild-plugin-d.ts": "^1.3.1",
-    "eslint": "^9.25.1",
-    "eslint-config-prettier": "^10.1.2",
-    "pino": "^9.6.0",
-    "prettier": "^3.5.3",
-    "typescript": "^5.8.3",
-    "typescript-eslint": "^8.31.1",
-    "vitest": "^3.1.2"
-  },
-  "dependencies": {
-    "jose": "^5.2.2",
-    "ky": "^1.1.0"
-  },
-  "scripts": {
-    "test": "vitest",
-    "lint": "eslint . --fix",
-    "format": "prettier --write .",
-    "build": "pnpm lint && node build.mjs",
-    "prepublish": "pnpm build",
-    "version": "git add -A src",
-    "postversion": "git push && git push --tags"
-  }
-}
+    "name": "bc-api-client",
+    "version": "0.1.3",
+    "description": "A client for the BigCommerce management API and app authentication",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "type": "module",
+    "exports": {
+        ".": "./dist/index.js",
+        "./endpoints": "./dist/endpoints.js",
+        "./package.json": "./package.json"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/kernelpanic99/bc-api-client"
+    },
+    "homepage": "https://github.com/kernelpanic99/bc-api-client",
+    "bugs": {
+        "url": "https://github.com/kernelpanic99/bc-api-client/issues"
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "scripts": {
+        "test": "vitest",
+        "lint": "eslint . --fix",
+        "format": "prettier --write .",
+        "build": "pnpm lint && node build.mjs",
+        "prepublish": "pnpm build",
+        "version": "git add -A src",
+        "postversion": "git push && git push --tags"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "keywords": [
+        "bigcommerce",
+        "api",
+        "client",
+        "typescript",
+        "jwt",
+        "authentication"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "author": "Arthur Nikolaienko",
+    "license": "MIT",
+    "packageManager": "pnpm@10.10.0",
+    "devDependencies": {
+        "@eslint/js": "^9.25.1",
+        "@types/jsonwebtoken": "^9.0.9",
+        "@types/node": "^22.15.3",
+        "dotenv": "^16.5.0",
+        "esbuild": "^0.25.3",
+        "esbuild-plugin-d.ts": "^1.3.1",
+        "eslint": "^9.25.1",
+        "eslint-config-prettier": "^10.1.2",
+        "pino": "^9.6.0",
+        "prettier": "^3.5.3",
+        "typescript": "^5.8.3",
+        "typescript-eslint": "^8.31.1",
+        "vitest": "^3.1.2"
+    },
+    "dependencies": {
+        "jose": "^5.2.2",
+        "ky": "^1.1.0"
+    }
+}

package/dist/auth.d.ts

@@ -1,132 +0,0 @@
-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;
-    /** 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
- */
-type AuthQuery = {
-    /** The BigCommerce account UUID */
-    account_uuid: string;
-    /** 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
-     * @param config - Configuration options for BigCommerce authentication
-     * @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
-     * @returns Promise resolving to the token response
-     */
-    requestToken(data: string | AuthQuery): Promise<TokenResponse>;
-    /**
-     * Verifies a JWT payload from BigCommerce
-     * @param jwtPayload - The JWT string to verify
-     * @returns Promise resolving to the verified JWT claims
-     * @throws {Error} If the JWT is invalid
-     */
-    verify(jwtPayload: 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 {};