bc-api-client 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2025 Arthur Nikolaienko <kernelpanic99.npm@pm.me>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# Bigcommerce management API client and JWT authenticator
+
+<span style="color:orange">BETA VERSION - Use at your own risk</span>
+
+An opinionated and minimalistic client focusing on simplicity and performance.
+Features (or antifeatures - depends on your opinion)
+- Node 20+ LTS, ESM
+- Bring Your Own Types
+- Basic API methods (get, post, put, delete)
+- Advanced methods for concurrent querying and fetching
+- All methods are generic
+- Rate limit handling
+- App authenticator module. Request token and verify JWT.
+
+## Installation
+
+```bash
+npm install bc-api-client
+# or
+pnpm add bc-api-client
+# or
+yarn add bc-api-client
+```
+
+## Usage
+
+### API Client
+
+```typescript
+import { BigCommerceClient, V3Response } from 'bigcommerce-client';
+import { bc } from 'bigcommerce-client/endpoints';
+
+type MyProduct = {
+    id: number;
+    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'
+});
+
+// Basic GET request
+const products = await client.get<V3Response<MyProduct[]>>({
+  endpoint: bc.products.path,
+  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
+  }
+);
+
+// Collect all pages from v3 endpoint
+const allProducts = await client.collect<MyProduct>({
+  endpoint: bc.products.path,
+  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>({
+  endpoint: bc.orders.v2.path,
+  query: {
+    limit: '5',
+  },
+  concurrency: 10, // Optional: control concurrent requests
+  skipErrors: true // Optional: skip failed requests
+});
+
+// Query with multiple filter values
+// 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,
+  key: 'id:in',
+  values: productIds,
+  query: {
+    include_fields: fields,
+  },
+  concurrency: 10, // Optional: control concurrent requests
+  skipErrors: true // Optional: skip failed requests
+});
+```
+
+### Authentication
+
+```typescript
+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'
+});
+
+// Request token
+const token = await auth.requestToken(authQuery);
+
+// Verify JWT
+const claims = await auth.verify(jwtPayload);
+```
+
+## API
+
+### BigCommerceClient
+
+#### `get<R>(options: GetOptions): Promise<R>`
+Makes a GET request to the BigCommerce API.
+
+#### `post<T, R>(options: PostOptions<T>): Promise<R>`
+Makes a POST request to the BigCommerce API.
+
+#### `put<T, R>(options: PostOptions<T>): Promise<R>`
+Makes a PUT request to the BigCommerce API.
+
+#### `delete<R>(endpoint: string): 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)
+
+### BigCommerceAuth
+
+#### `requestToken(data: string | AuthQuery): Promise<TokenResponse>`
+Requests an access token from BigCommerce OAuth.
+
+#### `verify(jwtPayload: string): Promise<Claims>`
+Verifies a JWT payload from BigCommerce.
+
+## License
+
+MIT
+

package/dist/auth.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 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[];
+};
+/**
+ * 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 {};

package/dist/client.d.ts

@@ -0,0 +1,30 @@
+import { RateLimitOptions, RequestOptions, StoreOptions } from './net';
+export type GetOptions = {
+    endpoint: string;
+    query?: Record<string, string>;
+    version?: 'v2' | 'v3';
+};
+export type PostOptions<T> = GetOptions & {
+    body: T;
+};
+export type ConcurrencyOptions = {
+    concurrency?: number;
+    skipErrors?: boolean;
+};
+export type QueryOptions = Omit<GetOptions, 'version'> & ConcurrencyOptions & {
+    key: string;
+    values: (string | number)[];
+};
+export type Config = StoreOptions & RateLimitOptions;
+export declare class BigCommerceClient {
+    private readonly config;
+    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[]>;
+}

package/dist/core.d.ts

@@ -0,0 +1,18 @@
+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;
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './client';
+export * from './core';
+export * from './auth';