Make API clients injectable in commerce-sdk-react (CommerceApiProvider)

packages/commerce-sdk-react/CHANGELOG.md

@@ -1,6 +1,8 @@
 ## v3.4.0-dev.0 (May 23, 2025)
 - Now compatible with either React 17 and 18 [#2506](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2506)
 
+- Refactor commerce-sdk-react to allow injecting ApiClients [#2519](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2519)
+
 ## v3.3.0 (May 22, 2025)
 
 - Fix inconsistency between dwsid and access token for guest login when hybrid authentication is enabled [#2397](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2397)

packages/commerce-sdk-react/src/hooks/types.ts

@@ -20,6 +20,7 @@ import {
     ShopperStores
 } from 'commerce-sdk-isomorphic'
 import {helpers} from 'commerce-sdk-isomorphic'
+import {CommerceApiProviderProps} from '../provider'
 
 // --- GENERAL UTILITIES --- //
 
@@ -226,3 +227,17 @@ export type TMutationVariables = {
     parameters?: {[key: string]: string | number | boolean | string[] | number[]}
     headers?: {[key: string]: string}
 } | void
+
+export type SDKClientTransformer<T> = (
+    params: T,
+    methodName: string,
+    options: any
+) => any | Promise<any>
+
+export type ErrorCallback<TParams> = (methodName: string, error: any, params: TParams) => void
+
+export interface SDKClientTransformConfig<TParams = Record<string, any>> {
+    props: Omit<CommerceApiProviderProps, 'children'>
+    transformer?: SDKClientTransformer<TParams>
+    onError?: ErrorCallback<TParams>
+}

packages/commerce-sdk-react/src/hooks/useConfig.ts

@@ -11,7 +11,7 @@ import {ConfigContext, CommerceApiProviderProps} from '../provider'
 /**
  * @Internal
  */
-const useConfig = (): Omit<CommerceApiProviderProps, 'children'> => {
+const useConfig = (): Omit<CommerceApiProviderProps, 'children' | 'apiClients'> => {
     return React.useContext(ConfigContext)
 }
 

packages/commerce-sdk-react/src/provider.tsx

@@ -5,6 +5,15 @@
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 import React, {ReactElement, useEffect, useMemo} from 'react'
+import Auth from './auth'
+import {ApiClientConfigParams, ApiClients, SDKClientTransformer} from './hooks/types'
+import {Logger} from './types'
+import {
+    DWSID_COOKIE_NAME,
+    MOBIFY_PATH,
+    SERVER_AFFINITY_HEADER_KEY,
+    SLAS_PRIVATE_PROXY_PATH
+} from './constant'
 import {
     ShopperBaskets,
     ShopperContexts,
@@ -20,15 +29,8 @@ import {
     ShopperBasketsTypes,
     ShopperStores
 } from 'commerce-sdk-isomorphic'
-import Auth from './auth'
-import {ApiClientConfigParams, ApiClients} from './hooks/types'
-import {Logger} from './types'
-import {
-    DWSID_COOKIE_NAME,
-    MOBIFY_PATH,
-    SERVER_AFFINITY_HEADER_KEY,
-    SLAS_PRIVATE_PROXY_PATH
-} from './constant'
+import {transformSDKClient} from './utils'
+
 export interface CommerceApiProviderProps extends ApiClientConfigParams {
     children: React.ReactNode
     proxy: string
@@ -46,6 +48,7 @@ export interface CommerceApiProviderProps extends ApiClientConfigParams {
     passwordlessLoginCallbackURI?: string
     refreshTokenRegisteredCookieTTL?: number
     refreshTokenGuestCookieTTL?: number
+    apiClients?: ApiClients
 }
 
 /**
@@ -56,7 +59,9 @@ export const CommerceApiContext = React.createContext({} as ApiClients)
 /**
  * @internal
  */
-export const ConfigContext = React.createContext({} as Omit<CommerceApiProviderProps, 'children'>)
+export const ConfigContext = React.createContext(
+    {} as Omit<CommerceApiProviderProps, 'children' | 'apiClients'>
+)
 
 /**
  * @internal
@@ -126,7 +131,8 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
         defaultDnt,
         passwordlessLoginCallbackURI,
         refreshTokenRegisteredCookieTTL,
-        refreshTokenGuestCookieTTL
+        refreshTokenGuestCookieTTL,
+        apiClients
     } = props
 
     // Set the logger based on provided configuration, or default to the console object if no logger is provided
@@ -167,7 +173,8 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
         defaultDnt,
         passwordlessLoginCallbackURI,
         refreshTokenRegisteredCookieTTL,
-        refreshTokenGuestCookieTTL
+        refreshTokenGuestCookieTTL,
+        apiClients
     ])
 
     const dwsid = auth.get(DWSID_COOKIE_NAME)
@@ -176,28 +183,62 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
         serverAffinityHeader[SERVER_AFFINITY_HEADER_KEY] = dwsid
     }
 
-    const config = {
-        proxy,
-        headers: {
-            ...headers,
-            ...serverAffinityHeader
-        },
-        parameters: {
-            clientId,
-            organizationId,
-            shortCode,
-            siteId,
-            locale,
-            currency
-        },
-        throwOnBadResponse: true,
-        fetchOptions
+    const _defaultTransformer: SDKClientTransformer<Record<string, any>> = (_, _$, options) => {
+        return {
+            ...options,
+            headers: {
+                ...options.headers,
+                ...serverAffinityHeader
+            },
+            throwOnBadResponse: true,
+            fetchOptions: {
+                ...options.fetchOptions,
+                ...fetchOptions
+            }
+        }
     }
 
-    const baseUrl = config.proxy.split(MOBIFY_PATH)[0]
-    const privateClientEndpoint = `${baseUrl}${SLAS_PRIVATE_PROXY_PATH}`
+    const updatedClients: ApiClients = useMemo(() => {
+        if (apiClients) {
+            const clients: Record<string, any> = {}
+
+            // transformSDKClient is simply a utility function that wraps the SDK Client instance
+            // in a Proxy that allows us to transform the method arguments and modify headers, parameters, and other options.
+            // We don't really need to pass in the children prop to the transformer function, so we'll just pass in the rest of the props.
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const {children, ...restProps} = props
+
+            Object.entries(apiClients ?? {}).forEach(([key, apiClient]) => {
+                clients[key] = transformSDKClient(apiClient, {
+                    props: restProps,
+                    transformer: _defaultTransformer
+                })
+            })
+
+            return clients as ApiClients
+        }
+
+        const config = {
+            proxy,
+            headers: {
+                ...headers,
+                ...serverAffinityHeader
+            },
+            parameters: {
+                clientId,
+                organizationId,
+                shortCode,
+                siteId,
+                locale,
+                currency
+            },
+            throwOnBadResponse: true,
+            fetchOptions
+        }
+
+        const baseUrl = config.proxy.split(MOBIFY_PATH)[0]
+        const privateClientEndpoint = `${baseUrl}${SLAS_PRIVATE_PROXY_PATH}`
 
-    const apiClients = useMemo(() => {
         return {
             shopperBaskets: new ShopperBaskets(config),
             shopperContexts: new ShopperContexts(config),
@@ -224,7 +265,8 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
         fetchOptions,
         locale,
         currency,
-        headers?.['correlation-id']
+        headers?.['correlation-id'],
+        apiClients
     ])
 
     // Initialize the session
@@ -251,7 +293,7 @@ const CommerceApiProvider = (props: CommerceApiProviderProps): ReactElement => {
                 refreshTokenGuestCookieTTL
             }}
         >
-            <CommerceApiContext.Provider value={apiClients}>
+            <CommerceApiContext.Provider value={updatedClients}>
                 <AuthContext.Provider value={auth}>{children}</AuthContext.Provider>
             </CommerceApiContext.Provider>
         </ConfigContext.Provider>