Merge pull request #5 from aligent/feature/dual-package-output

ESM + CJS output, export function to modify inbuilt client

Author: Torbjorn van Heeswijck

.gitignore

@@ -1,5 +1,8 @@
 node_modules
 .vscode
-lib
 .yarn
-.tmp-generate
+
+# Build Artifacts
+.tmp-generate
+dist
+.tshy

README.md

@@ -87,10 +87,10 @@ MIT
 
 ## Under development
 
-- [ ] Providing a different base URL (or custom fetch client) is unnecessarily difficult
+- [x] Easier customisation of fetch client
 - [ ] Expose the storefront API paths properly
 - [ ] Regular rebuild and publish schedule to keep up with BigCommerce API schema changes
 - [ ] Migrate generation code to Typescript
-- [ ] Properly publish ESM and CJS exports
+- [x] Properly publish ESM and CJS exports
 - [ ] Audit eslint/typescript ignore comments
 - [ ] Audit type narrowing and parameter types (especially in v2)

eslint.config.js

@@ -2,5 +2,5 @@ import { eslintConfigs } from '@aligent/ts-code-standards';
 
 export default [
     ...eslintConfigs.base,
-    { ignores: ['**/*.{js,mjs}', '**/generated', '**/lib'] },
+    { ignores: ['**/*.{js,mjs}', '**/generated', '**/dist'] },
 ];

package.json

@@ -1,22 +1,41 @@
 {
   "name": "@aligent/bigcommerce-api",
-  "version": "0.0.2",
-  "description": "Fully typed BigCommerce API client generated from documentation schemas",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
+  "version": "0.0.1-alpha.1",
   "type": "module",
-  "files": [
-    "lib"
-  ],
   "scripts": {
-    "build": "tsc --project tsconfig.publish.json",
     "test": "tsd",
     "lint": "eslint .",
-    "clean": "rimraf lib",
-    "build-file-list": "node src/internal/reference/list-files",
-    "build-reference-types": "node src/internal/reference/generate",
-    "build:clean": "npm run clean && npm run build-file-list && npm run build-reference-types && npm run build"
+    "build:file-list": "node src/internal/reference/list-files",
+    "build:reference-types": "node src/internal/reference/generate",
+    "build:clean": "rimraf dist && npm run build:file-list && npm run build:reference-types && npm run build",
+    "build": "tshy"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/index.d.ts",
+        "default": "./dist/commonjs/index.js"
+      }
+    }
   },
+  "tshy": {
+    "exports": {
+      "./package.json": "./package.json",
+      ".": "./src/index.ts"
+    }
+  },
+  "main": "./dist/commonjs/index.js",
+  "types": "./dist/commonjs/index.d.ts",
+  "module": "./dist/esm/index.js",
+  "description": "Fully typed BigCommerce API client generated from documentation schemas",
+  "files": [
+    "dist"
+  ],
   "engines": {
     "node": ">=14"
   },
@@ -36,6 +55,7 @@
     "temp-dir": "^3.0.0",
     "ts-morph": "^25.0.1",
     "tsd": "^0.32.0",
+    "tshy": "^3.0.2",
     "typescript": "^5.8.2",
     "uuid": "^11.1.0"
   },

src/index.ts

@@ -1 +1,2 @@
+export { fetchTransport } from './internal/operation.js';
 export * as Management from './management/index.js';

src/management/README.md

@@ -30,11 +30,11 @@ To use the BigCommerce Management API you first need to [obtain the store hash a
 You can use es6 imports with the Management API:
 
 ```js
-import { Management } from "@aligent/bigcommerce-api";
+import { Management } from '@aligent/bigcommerce-api';
 
 const bigCommerce = new Management.Client({
-  storeHash: "your store hash here",
-  accessToken: "your access token here",
+  storeHash: 'your store hash here',
+  accessToken: 'your access token here',
 });
 ```
 
@@ -43,26 +43,26 @@ const bigCommerce = new Management.Client({
 The following code snippet will fetch store information from the V2 API and dump it to the console:
 
 ```js
-import { Management } from "@aligent/bigcommerce-api";
+import { Management } from '@aligent/bigcommerce-api';
 
 const bigCommerce = new Management.Client({
-  storeHash: "your store hash here",
-  accessToken: "your access token here",
+  storeHash: 'your store hash here',
+  accessToken: 'your access token here',
 });
 
-bigCommerce.v2.get("/store").then(console.dir);
+bigCommerce.v2.get('/store').then(console.dir);
 ```
 
 ## How-to guides
 
 Start by instantiating a client instance:
 
 ```js
-import { Management } from "@aligent/bigcommerce-api";
+import { Management } from '@aligent/bigcommerce-api';
 
 const bigCommerce = new Management.Client({
-  storeHash: "your store hash here",
-  accessToken: "your access token here",
+  storeHash: 'your store hash here',
+  accessToken: 'your access token here',
 });
 ```
 
@@ -104,7 +104,7 @@ bigCommerce.v3.get('/catalog/products/{product_id}', {
 ```js
 async function printAllProducts() {
   // list() sends one HTTP request at a time and only sends requests as the iterator is consumed
-  const products = bigCommerce.v3.list("/catalog/products", { query: { include: ["images"] } });
+  const products = bigCommerce.v3.list('/catalog/products', { query: { include: ['images'] } });
   for await (const product of products) {
     console.dir(product);
   }
@@ -191,6 +191,41 @@ Your BigCommerce Management API access token.
 
 Provide a node HTTP agent to override things like keepalive and connection pool size.
 
+### Overriding the internal client
+
+You can provide your own fetch implementation to the clients.
+
+For light modifications like custom headers or baseUrl, re-use the `fetchTransport` function
+
+```typescript
+const v2 = new Management.V2.Client(
+  import { Management, fetchTransport } from "@aligent/bigcommerce-api";
+  import { Agent } from "node:http";
+
+  fetchTransport({
+    baseUrl: 'http://custom.url/v2',
+    headers: {
+      "customer-header": "..."
+    }
+  })
+);
+
+const v3 = new Management.V3.Client(
+  fetchTransport({
+    baseUrl: 'http://custom.url/v3',
+    headers: {
+      "customer-header": "..."
+    }
+  })
+);
+```
+
+For more control, provide a custom implementation matching the Transport interface to the clients
+
+```typescript
+type Transport = (requestLine: string, params?: Parameters) => Promise<Response>;
+```
+
 ### V2 API client
 
 See the [V2 readme](v2/README.md) for more detail on the Management V2 client methods.

src/management/index.ts

@@ -12,25 +12,46 @@ export type Config = {
 };
 
 /**
- * If you need to use a path which is not part if the spec, you can pass it
- * into the client via a type parameter to avoid TypeScript errors, e.g.:
+ * The main client for interacting with the BigCommerce Management API.
+ * It provides access to both V2 and V3 API endpoints through dedicated
+ * versioned clients.
  *
- *   type MyExtraEndpoints =
- *     | 'GET /v3/foo/bar'
- *     | 'POST /v3/foo/bar'
- *     | 'GET /v2/foo/baz'
- *   ;
+ * @template CustomEndpoints - A string literal type representing custom API paths
+ *   that are not part of the official BigCommerce API specification. This allows
+ *   type-safe access to non-standard endpoints.
  *
- *   bigCommerce = new Client<MyExtraEndpoints>(config)
+ * @example
+ * // Define custom endpoints
+ * type MyExtraEndpoints =
+ *   | 'GET /v3/foo/bar'
+ *   | 'POST /v3/foo/bar'
+ *   | 'GET /v2/foo/baz';
+ *
+ * // Instantiate the client with custom endpoints
+ * const config: Config = { storeHash: '...', accessToken: '...' };
+ * const bigCommerce = new Client<MyExtraEndpoints>(config);
+ *
+ * // Access standard and custom endpoints
+ * await bigCommerce.v3.get('/catalog/products');
+ * await bigCommerce.v3.get('/foo/bar'); // Custom endpoint accepted by typescript
  */
-
 export class Client<CustomEndpoints extends string = never> {
+    /**
+     * Initializes the API client with configuration options.
+     * @param config - The configuration object containing store hash, access token, and optional agent.
+     */
     constructor(private readonly config: Config) {
         this.v2 = new V2.Client<ExtractSubpaths<'/v2', CustomEndpoints>>(this.config);
         this.v3 = new V3.Client<ExtractSubpaths<'/v3', CustomEndpoints>>(this.config);
     }
 
+    /**
+     * Client instance for interacting with V2 Management API endpoints.
+     */
     readonly v2: V2.Client<ExtractSubpaths<'/v2', CustomEndpoints>>;
+    /**
+     * Client instance for interacting with V3 Management API endpoints.
+     */
     readonly v3: V3.Client<ExtractSubpaths<'/v3', CustomEndpoints>>;
 }
 

src/management/v2/index.ts

@@ -1,6 +1,5 @@
 // TECH DEBT: Work out if these eslint rules are reasonable in this context
 /* eslint-disable @typescript-eslint/no-explicit-any */
-/* eslint-disable @typescript-eslint/no-empty-object-type */
 import {
     fetchTransport,
     FetchTransportOptions,

tsconfig.base.json

@@ -2,7 +2,7 @@
     "extends": "@aligent/ts-code-standards/tsconfigs-base",
     "compileOnSave": false,
     "compilerOptions": {
-        "outDir": "lib",
+        "outDir": "dist",
         "declaration": true,
         "checkJs": false
     }

tsconfig.json

@@ -1,5 +1,5 @@
 {
     "extends": "./tsconfig.base.json",
     "include": ["src"],
-    "exclude": ["node_modules", "lib"]
+    "exclude": ["node_modules", "dist"]
 }