Feat: Expose a way to pass in custom fetch (@W-21293162@) (#272)

* expose a way to pass in custom fetch via client config

* update changelog

Author: joeluong-sfcc

CHANGELOG.md

@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## v5.1.0
+
+### Enchancements
+
+- Allow developers to pass in custom fetch implementation via `clientConfig` [#272](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic/pull/272)
+
 ## v5.0.0
 
 ### API Versions

README.md

@@ -223,6 +223,45 @@ await helpers.callCustomEndpoint({
 
 For more documentation about this helper function, please refer to the [commerce-sdk-isomorphic docs](https://salesforcecommercecloud.github.io/commerce-sdk-isomorphic/modules/helpers.html).
 
+#### 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,
+};
+```
+
 #### Encoding special characters
 
 The SDK currently single encodes special characters for query parameters in UTF-8 format based on SCAPI guidelines. However, the SDK does NOT encode path parameters, and will require the developer to encode any path parameters with special characters.

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});
   });

src/static/clientConfig.ts

@@ -18,6 +18,14 @@ type BrowserRequestInit = RequestInit;
  */
 export type FetchOptions = NodeRequestInit & BrowserRequestInit;
 
+/**
+ * A function that can be used to fetch data from an API
+ */
+export type FetchFunction = (
+  input: RequestInfo,
+  init?: FetchOptions | undefined
+) => Promise<Response>;
+
 /**
  * Base options that can be passed to the `ClientConfig` class.
  */
@@ -27,18 +35,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 +59,8 @@ export default class ClientConfig<Params extends BaseUriParameters>
 
   public fetchOptions: FetchOptions;
 
+  public fetch?: FetchFunction;
+
   public transformRequest: NonNullable<
     ClientConfigInit<Params>['transformRequest']
   >;
@@ -83,6 +89,8 @@ export default class ClientConfig<Params extends BaseUriParameters>
       this.proxy = config.proxy;
     }
     this.throwOnBadResponse = !!config.throwOnBadResponse;
+
+    this.fetch = config.fetch;
   }
 
   static readonly defaults: Pick<

src/static/helpers/fetchHelper.test.ts

@@ -138,6 +138,26 @@ describe('doFetch', () => {
       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 environmentFetchSpy = jest.spyOn(environment, 'fetch');
+
+    const clientConfigCopy = {
+      ...clientConfig,
+      fetch,
+    };
+
+    await doFetch(url, options, clientConfigCopy, false);
+    expect(spy).toBeCalledTimes(1);
+    expect(environmentFetchSpy).not.toBeCalled();
+    expect(spy).toBeCalledWith(
+      expect.any(String),
+      expect.objectContaining(clientConfig.fetchOptions)
+    );
+  });
 });
 
 describe('encodeSCAPISpecialCharacters', () => {

src/static/helpers/fetchHelper.ts

@@ -51,7 +51,10 @@ export const doFetch = async <Params extends BaseUriParameters>(
     method: options?.method ?? 'GET',
   };
 
-  const response = await fetch(url, requestOptions);
+  // Use fetch from clientConfig, otherwise fallback to fetch implementation in environment.ts
+  const fetcher = clientConfig?.fetch || fetch;
+
+  const response = await fetcher(url, requestOptions);
   if (rawResponse) {
     return response;
   }