Feat: Expose a way to pass in custom fetch function (@W-19973347@) (#246)

joeluong-sfcc · web-flow · commit dad19746fdfa · 2025-11-04T14:00:46.000-05:00
* expose way to pass in custom fetch function

* add unit test

* update README

* update CHANGELOG.md

* remove unused import

* bump size

* update fetch implementation

* fix unit test

* update tests
diff --git a/.github/workflows/publish-preview.yml b/.github/workflows/publish-preview.yml
@@ -22,7 +22,7 @@ jobs:
         run: |
           BASE_VERSION=$(node -p "require('./package.json').version.split('-')[0]")
           DATE=$(date -u +%Y%m%d%H%M%S)
-          NEW_VERSION="$BASE_VERSION-nightly-$DATE"
+          NEW_VERSION="$BASE_VERSION-unstable-$DATE"
           echo "NEW_VERSION=$NEW_VERSION" >> $GITHUB_ENV
           npm version --no-git-tag-version "$NEW_VERSION"
       - run: yarn run renderTemplates
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,7 +4,7 @@
 
 ### Enhancements
 
-- Use native node fetch available in node 18+ instead of `node-fetch` polyfill [#214](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic/pull/214)
+- Allow developers to pass in custom fetch implementation via `clientConfig` [#246](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic/pull/246)
 - Support subpath imports for individual APIs and named imports [#219](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic/pull/219)
 
 ### Bug Fixes
diff --git a/README.md b/README.md
@@ -149,6 +149,45 @@ const helpers = require('commerce-sdk-isomorphic/helpers');
 
 **Note:** While subpath imports reduce initial bundle size, using them for all APIs will result in a larger total bundle size due to duplicated dependencies required for standalone operation.
 
+#### Custom Fetch function
+
+You can provide your own custom fetch function to intercept, log, or modify all SDK requests. This is useful for:
+- **Request/Response Logging**: Track all API calls for debugging and monitoring
+- **Request Interception**: Add custom headers, modify request URLs, or implement custom retry logic
+- **Error Handling**: Add custom error processing or transformation before responses reach your application
+- **Performance Monitoring**: Measure request/response times and track API performance metrics
+
+**Example with Logging:**
+```javascript
+// Custom fetch function with detailed logging
+const customFetch = async (url, options) => {
+  console.log(`[SDK Request] ${options?.method || 'GET'} ${url}`);
+  console.log('[SDK Request Headers]', options?.headers);
+  if (options?.body) {
+    console.log('[SDK Request Body]', options.body);
+  }
+  
+  const startTime = Date.now();
+  const response = await fetch(url, options);
+  const duration = Date.now() - startTime;
+  
+  console.log(`[SDK Response] ${response.status} ${response.statusText} (${duration}ms)`);
+  console.log('[SDK Response Headers]', Object.fromEntries(response.headers.entries()));
+  
+  return response;
+};
+
+const config = {
+  parameters: {
+    clientId: '<your-client-id>',
+    organizationId: '<your-org-id>',
+    shortCode: '<your-short-code>',
+    siteId: '<your-site-id>',
+  },
+  fetch: customFetch,
+};
+```
+
 #### Fetch Options
 
 You can configure how the SDK makes requests using the `fetchOptions` parameter. It is passed to [node-fetch](https://github.com/node-fetch/node-fetch/1#api) on the server and [whatwg-fetch](https://github.github.io/fetch/) on browser.
@@ -340,6 +379,24 @@ console.log("categoriesResult: ", categoriesResult);
 
 **NOTE: In the next major version release, path parameters will be single encoded by default**
 
+## Unstable Releases
+
+**⚠️ Important: Unstable/preview releases are experimental and not officially supported.**
+
+Preview releases (e.g., preview, unstable, or pre-release versions) are provided for experimental purposes and early testing of upcoming features. These releases:
+
+- **Are not intended for production use** - Do not use unstable releases in production environments
+- **May contain breaking changes** - API signatures, behavior, and structure may change without notice
+- **Are not officially supported** - No support, bug fixes, or security patches are guaranteed
+- **May have incomplete features** - Functionality may be partially implemented or subject to change
+
+**Use stable releases for production applications.** Only use unstable releases for:
+- Testing upcoming features in development environments
+- Providing feedback on new functionality before official release
+- Experimental integrations that are not mission-critical
+
+For production deployments, always use the latest stable release version available on npm.
+
 ## License Information
 
 The Commerce SDK Isomorphic is licensed under BSD-3-Clause license. See the [license](./LICENSE.txt) for details.
diff --git a/jest.config.js b/jest.config.js
@@ -14,7 +14,7 @@ module.exports = {
     '!scripts/generateFileList.ts',
     '!scripts/updateApis.ts',
     '!scripts/generateVersionTable.ts',
-    '!src/static/fileList.ts',
+    '!scripts/fileList.ts',
     '!<rootDir>/node_modules/',
   ],
   coverageReporters: ['text'],
diff --git a/package.json b/package.json
@@ -167,6 +167,7 @@
   },
   "dependencies": {
     "nanoid": "^3.3.8",
+    "node-fetch": "2.6.13",
     "seedrandom": "^3.0.5"
   },
   "devDependencies": {
@@ -209,7 +210,6 @@
     "jest-environment-jsdom-sixteen": "1.0.3",
     "lint-staged": "10.5.4",
     "nock": "^13.2.8",
-    "node-fetch": "2.6.13",
     "npm-pack-all": "^1.12.7",
     "postcss-preset-env": "6.7.1",
     "prettier": "^2.7.1",
@@ -250,7 +250,7 @@
     },
     {
       "path": "commerce-sdk-isomorphic-with-deps.tgz",
-      "maxSize": "2.42 MB"
+      "maxSize": "2.5 MB"
     }
   ],
   "proxy": "https://SHORTCODE.api.commercecloud.salesforce.com"
diff --git a/scripts/utils.test.ts b/scripts/utils.test.ts
@@ -30,4 +30,11 @@ describe('test downloadLatestApis script', () => {
       downloadLatestApis('category:Visibility = "External"', '/tmp')
     ).rejects.toThrow('Failed to download API specs: It failed.');
   });
+
+  it('rejects with non-Error when download fails', async () => {
+    jest.spyOn(download, 'downloadRestApis').mockRejectedValue('It failed.');
+    await expect(
+      downloadLatestApis('category:Visibility = "External"', '/tmp')
+    ).rejects.toBe('It failed.');
+  });
 });
diff --git a/src/static/clientConfig.test.ts b/src/static/clientConfig.test.ts
@@ -5,7 +5,7 @@
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 import {BaseUriParameters} from 'lib/helpers';
-import ClientConfig, {ClientConfigInit} from './clientConfig';
+import ClientConfig, {ClientConfigInit, FetchFunction} from './clientConfig';
 
 describe('ClientConfig constructor', () => {
   test('will throw if missing shortCode parameter', () => {
@@ -26,6 +26,7 @@ describe('ClientConfig constructor', () => {
       proxy: 'https://proxy.com',
       transformRequest: ClientConfig.defaults.transformRequest,
       throwOnBadResponse: false,
+      fetch: fetch as FetchFunction,
     };
     expect(new ClientConfig(init)).toEqual({...init});
   });
diff --git a/src/static/clientConfig.ts b/src/static/clientConfig.ts
@@ -18,6 +18,11 @@ type BrowserRequestInit = RequestInit;
  */
 export type FetchOptions = NodeRequestInit & BrowserRequestInit;
 
+export type FetchFunction = (
+  input: RequestInfo,
+  init?: FetchOptions | undefined
+) => Promise<Response>;
+
 /**
  * Base options that can be passed to the `ClientConfig` class.
  */
@@ -27,18 +32,14 @@ export interface ClientConfigInit<Params extends BaseUriParameters> {
   headers?: {[key: string]: string};
   parameters: Params;
   fetchOptions?: FetchOptions;
+  fetch?: FetchFunction;
   transformRequest?: (
     data: unknown,
     headers: {[key: string]: string}
   ) => Required<FetchOptions>['body'];
   throwOnBadResponse?: boolean;
 }
 
-export type FetchFunction = (
-  input: RequestInfo,
-  init?: FetchOptions | undefined
-) => Promise<Response>;
-
 /**
  * Configuration parameters common to Commerce SDK clients
  */
@@ -55,6 +56,8 @@ export default class ClientConfig<Params extends BaseUriParameters>
 
   public fetchOptions: FetchOptions;
 
+  public fetch?: FetchFunction;
+
   public transformRequest: NonNullable<
     ClientConfigInit<Params>['transformRequest']
   >;
@@ -75,6 +78,8 @@ export default class ClientConfig<Params extends BaseUriParameters>
     this.transformRequest =
       config.transformRequest || ClientConfig.defaults.transformRequest;
 
+    this.fetch = config.fetch;
+
     // Optional properties
     if (config.baseUri) {
       this.baseUri = config.baseUri;
diff --git a/src/static/helpers/customApi.ts b/src/static/helpers/customApi.ts
@@ -148,7 +148,9 @@ export const callCustomEndpoint = async (args: {
   // The resulting endpointPath will be: "actions/categories/Special%2CSummer"
   if (currentEndpointPath.includes('/')) {
     // Normalize endpoint path by removing multiple consecutive slashes
-    const segments = currentEndpointPath.split('/').filter(segment => segment !== '');
+    const segments = currentEndpointPath
+      .split('/')
+      .filter(segment => segment !== '');
     newEndpointPath = '';
     segments.forEach((segment: string, index: number) => {
       const key = `endpointPathSegment${index}`;
diff --git a/src/static/helpers/environment.test.ts b/src/static/helpers/environment.test.ts
@@ -4,22 +4,43 @@
  * SPDX-License-Identifier: BSD-3-Clause
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
-
 import nodeFetch from 'node-fetch';
 import {isNode, fetch} from './environment';
 
 const TIMEOUT = 7000; // 7 seconds
 
-/* Just testing the node environment, testing the browser environment is too complex within the test cases. */
+jest.mock('node-fetch', () => {
+  const actual = jest.requireActual<typeof import('node-fetch')>('node-fetch');
+  const impl = (actual.default ?? actual) as (
+    ...args: unknown[]
+  ) => Promise<unknown>;
+  const mock = jest.fn((...args: unknown[]) => impl(...args));
+  return Object.assign(mock, {default: mock});
+});
 
+/* Just testing the node environment, testing the browser environment is too complex within the test cases. */
 describe('Fetch', () => {
-  test('Runs node-fetch if node', () => {
+  const nodeFetchMock = nodeFetch as unknown as jest.Mock;
+
+  beforeEach(() => {
+    nodeFetchMock.mockClear();
+  });
+
+  test('delegates to node-fetch in node environments', async () => {
     expect(isNode).toBe(true);
-    expect(fetch).toBe(nodeFetch);
+    await fetch('https://example.com');
+    expect(nodeFetchMock).toHaveBeenCalled();
   });
   test('Make sure the fetch that is imported is actually a function and not an object', () => {
     expect(typeof fetch).toBe('function');
   });
+  test('reuses the resolved polyfill after the first call', async () => {
+    await fetch('https://example.com?first');
+    expect(nodeFetchMock).toHaveBeenCalledTimes(1);
+
+    await fetch('https://example.com?second');
+    expect(nodeFetchMock).toHaveBeenCalledTimes(2);
+  });
   test(
     'fetch actually works',
     () => {
diff --git a/src/static/helpers/environment.ts b/src/static/helpers/environment.ts
@@ -1,17 +1,11 @@
 /*
- * Copyright (c) 2023, Salesforce, Inc.
+ * Copyright (c) 2025, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: BSD-3-Clause
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 import type {FetchFunction} from '../clientConfig';
 
-/*
- * Copyright (c) 2022, Salesforce, Inc.
- * All rights reserved.
- * SPDX-License-Identifier: BSD-3-Clause
- * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
- */
 export const isBrowser =
   typeof window === 'object' && typeof window.document === 'object';
 
@@ -24,14 +18,56 @@ export const globalObject = isBrowser ? window : globalThis;
 
 export const hasFetchAvailable = typeof globalObject.fetch === 'function';
 
-// TODO: Remove this function in the next major version
-// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-export const fetch: FetchFunction = (() => {
-  // Difficult to test in node environment
-  /* istanbul ignore next */
-  if (!hasFetchAvailable) {
-    throw new Error('Please use Node.js 18+ for native fetch support.');
+// We used to synchronously `require('node-fetch')` here, but that breaks the
+// generated ESM bundle (`lib/index.esm.js`). Modern Node runtimes refuse to load
+// files that contain `require()` alongside ESM syntax (error: ERR_AMBIGUOUS_MODULE_SYNTAX).
+// To keep a single source that works for both CommonJS and ESM consumers, we
+// lazily import the polyfill the first time `fetch` is called when running in
+// Node. Browsers (and Node 18+ with native fetch) still hit the global fetch.
+let cachedFetch: FetchFunction | undefined;
+let loadingPromise: Promise<FetchFunction> | undefined;
+
+// TODO: Adopt native fetch in the next major version.
+// Using the built-in fetch (Node 18+) caused downstream unit tests that rely on
+// `nock` to fail because `nock` hooks into the core HTTP/HTTPS modules, while
+// the native fetch implementation leverages undici instead. Until we can roll
+// out a coordinated breaking change, we continue to use the node-fetch
+// polyfill so existing tests keep passing.
+export const fetch: FetchFunction = ((...args: Parameters<FetchFunction>) => {
+  if (cachedFetch) {
+    // Polyfill already resolved once; delegate immediately.
+    return cachedFetch(...args);
+  }
+
+  if (!loadingPromise) {
+    loadingPromise = (async () => {
+      if (isNode) {
+        // Running in Node without a cached polyfill. Dynamically import
+        // `node-fetch` so bundlers emit an ESM-friendly `import()` call
+        // (CommonJS outputs still rewrite this into a deferred require).
+        const mod = await import('node-fetch');
+        // Older node-fetch versions export the function as default; newer ones
+        // may export it as the module value. Handle both cases.
+        const nodeFetch = (mod.default ?? mod) as unknown as FetchFunction;
+        cachedFetch = nodeFetch;
+        return nodeFetch;
+      }
+
+      // Browser (or any environment with a native fetch). If fetch is missing
+      // we surface the same runtime error that existed before.
+      // Difficult to test this path in the Node-based test environment, so exclude it from coverage
+      /* istanbul ignore next */
+      if (!hasFetchAvailable)
+        throw new Error(
+          'Bad environment: it is not a node environment but fetch is not defined'
+        );
+
+      // Bind to preserve the expected `this` (global) when fetch executes.
+      cachedFetch = globalObject.fetch.bind(globalObject) as FetchFunction;
+      return cachedFetch;
+    })();
   }
 
-  return globalObject.fetch;
-})();
+  // First invocation: wait for the async loader before delegating to the real fetch.
+  return loadingPromise.then(fn => fn(...args));
+}) as FetchFunction;
diff --git a/src/static/helpers/fetchHelper.test.ts b/src/static/helpers/fetchHelper.test.ts
@@ -80,7 +80,7 @@ describe('doFetch', () => {
       .query({siteId: 'site_id'})
       .reply(200, responseBody);
 
-    const spy = jest.spyOn(global, 'fetch');
+    const spy = jest.spyOn(environment, 'fetch');
 
     const response = await doFetch(url, copyOptions, copyClientConfig);
     expect(response).toEqual(responseBody);
@@ -130,14 +130,32 @@ describe('doFetch', () => {
   test('passes on fetchOptions from clientConfig to fetch call', async () => {
     nock(basePath).post(endpointPath).query(true).reply(200, responseBody);
 
-    const spy = jest.spyOn(global, 'fetch');
+    const spy = jest.spyOn(environment, 'fetch');
     await doFetch(url, options, clientConfig, false);
     expect(spy).toBeCalledTimes(1);
     expect(spy).toBeCalledWith(
       expect.any(String),
       expect.objectContaining(clientConfig.fetchOptions)
     );
   });
+
+  test('uses fetch from clientConfig if provided', async () => {
+    nock(basePath).post(endpointPath).query(true).reply(200, responseBody);
+
+    const spy = jest.spyOn(global, 'fetch');
+
+    const clientConfigCopy = {
+      ...clientConfig,
+      fetch,
+    };
+
+    await doFetch(url, options, clientConfigCopy, false);
+    expect(spy).toBeCalledTimes(1);
+    expect(spy).toBeCalledWith(
+      expect.any(String),
+      expect.objectContaining(clientConfig.fetchOptions)
+    );
+  });
 });
 
 describe('encodeSCAPISpecialCharacters', () => {
diff --git a/src/static/helpers/fetchHelper.ts b/src/static/helpers/fetchHelper.ts
diff --git a/templates/index.ts.hbs b/templates/index.ts.hbs
