@salesforce/commerce-sdk-react 4.0.0-extensibility-preview.0 → 4.0.0-nightly-20250826080215

package/CHANGELOG.md

@@ -1,21 +1,43 @@
-## v3.2.0-extensibility-preview.4 (Feb 12, 2025)
-- Add `ServerContext` type for `useServerContext` hook [#2239](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2239)
-
-## v3.2.0-preview.3 (Feb 12, 2025)
-## v3.1.1-preview.3 (Dec 13, 2024)
-## v3.1.1-preview.3 (Dec 13, 2024)
-## v3.1.1-preview.2 (Dec 09, 2024)
-## v3.1.1-preview.1 (Dec 09, 2024)
-## v4.0.0-extensibility-preview.2 (Dec 09, 2024)
-## v3.1.1-preview.1 (Dec 09, 2024)
-## v3.1.1-preview.0 (Dec 02, 2024)
-
-## v3.2.0-dev (Oct 29, 2024)
+## v4.0.0-nightly-20250826080215 (Aug 26, 2025)
+## v4.0.0-dev (Aug 26, 2025)
+## v3.12.0-nightly-20250826080215 (Aug 26, 2025)
+## v4.0.0-dev (Aug 18, 2025)
+- Upgrade to commerce-sdk-isomorphic v4.0.0 [2879](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2879)
+- Add support for environment level base paths on /mobify routes [#2892](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2892)
+- Update USID expiry to match SLAS refresh token expiry[#2854](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2854)
+- [Bugfix] Skip deleting dwsid on shopper login if hybrid auth is enabled for current site. [#3151](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3151)
+- Remove deprecated properties in commerce-sdk-react [#3177](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3177)
+
+## v3.4.0 (Jul 22, 2025)
+
+- Optionally disable auth init in CommerceApiProvider [#2629](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2629)
+- Now compatible with either React 17 and 18 [#2506](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2506)
+- Gracefully handle missing SDK Clients in CommerceApiProvider [#2539](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2539)
+- Refactor commerce-sdk-react to allow injecting ApiClients [#2519](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2519)
+- Upgrade to commerce-sdk-isomorphic v3.4.0 [#2866](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2866)
+
+
+## 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)
+- Invalidate cache instead of removing cache when triggering logout [#2323](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2323)
+- Fix dependencies vulnerabilities [#2338](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2338)
+- Allow custom parameters/body to be passed to SLAS authorize/authenticate calls via commerce-sdk-react auth helpers [#2358](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2358)
+
+## v3.2.1 (Mar 05, 2025)
+- Update PWA-Kit SDKs to v3.9.1 [#2301](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2301)
+
+## v3.2.0 (Feb 18, 2025)
+
 - Allow cookies for ShopperLogin API [#2190](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2190
 - Fix refresh token TTL warning from firing when override is not provided [#2114](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2114)
-
+- Readme updates for private clients [#2212](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2212)
 - Update CacheUpdateMatrix for mergeBasket mutation [#2138](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2092)
 - Clear auth state if session has been invalidated by a password change [#2092](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2092)
+- DNT interface improvement [#2203](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2203)
+- Support Node 22 [#2218](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2218)
+- Add `authorizeIDP`, `loginIDPUser`, `authorizePasswordless`, `getPasswordLessAccessToken`, `getPasswordResetToken`, and `resetPassword` wrapper functions to support Social Login, Passwordless Login, and Password Reset [#2079] (https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2079)
+
 
 ## v3.1.0 (Oct 28, 2024)
 

package/README.md

@@ -1,6 +1,6 @@
 :loudspeaker: Hey there, Salesforce Commerce Cloud community!
 
-We’re excited to hear your thoughts on your developer experience with PWA Kit and the Composable Storefront generally! Your feedback is incredibly valuable in helping us guide our roadmap and improve our offering.
+We're excited to hear your thoughts on your developer experience with PWA Kit and the Composable Storefront generally! Your feedback is incredibly valuable in helping us guide our roadmap and improve our offering.
 
 :clipboard: Take our quick survey here: [Survey](https://forms.gle/bUZNxQ3QKUcrjhV18) 
 
@@ -43,7 +43,7 @@ In practice, we recommend:
 npm install @salesforce/commerce-sdk-react @tanstack/react-query
 ```
 
-## ⚡️ Quickstart (PWA Kit v2.3.0+)
+## ⚡️ Quickstart (PWA Kit v3.0+)
 
 To integrate this library with your PWA Kit application you can use the `CommerceApiProvider` directly assuming that you use the `withReactQuery` higher order component to wrap your `AppConfig` component. Below is a snippet of how this is accomplished.
 
@@ -54,6 +54,10 @@ import {CommerceApiProvider} from '@salesforce/commerce-sdk-react'
 import {withReactQuery} from '@salesforce/pwa-kit-react-sdk/ssr/universal/components/with-react-query'
 
 const AppConfig = ({children}) => {
+    const headers = {
+        'correlation-id': correlationId
+    }
+
     return (
         <CommerceApiProvider
             clientId="12345678-1234-1234-1234-123412341234"
@@ -64,6 +68,11 @@ const AppConfig = ({children}) => {
             shortCode="12345678"
             locale="en-US"
             currency="USD"
+            headers={headers}
+            // Uncomment 'enablePWAKitPrivateClient' to use SLAS private client login flows.
+            // Make sure to also enable useSLASPrivateClient in ssr.js when enabling this setting.
+            // enablePWAKitPrivateClient={true}
+            logger={createLogger({packageName: 'commerce-sdk-react'})}
         >
             {children}
         </CommerceApiProvider>
@@ -125,68 +134,10 @@ export default App
 
 _💡 This section assumes you have read and completed the [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) guide._
 
-To help reduce boilerplate code for managing shopper authentication, by default, this library automatically initializes shopper session and manages the tokens for developers. Currently, the library supports the [Public Client login flow](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html).
-
-Commerce-react-sdk supports both public and private flow of the [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) guide._
-You can choose to use either public or private slas to login. By default, public flow is enabled.
-
-#### How private SLAS works
-This section assumes you read and understand how [private SLAS](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) flow works
-
-To enable private slas flow, you need to pass your secret into the CommercerProvider via clientSecret prop.
-**Note** You should only use private slas if you know you can secure your secret since commercer-sdk-react runs isomorphically.
-
-```js
-// app/components/_app-config/index.jsx
-
-import {CommerceApiProvider} from '@salesforce/commerce-sdk-react'
-import {withReactQuery} from '@salesforce/pwa-kit-react-sdk/ssr/universal/components/with-react-query'
-
-const AppConfig = ({children}) => {
-    return (
-        <CommerceApiProvider
-            clientId="12345678-1234-1234-1234-123412341234"
-            organizationId="f_ecom_aaaa_001"
-            proxy="localhost:3000/mobify/proxy/api"
-            redirectURI="localhost:3000/callback"
-            siteId="RefArch"
-            shortCode="12345678"
-            locale="en-US"
-            currency="USD"
-            clientSecret="<your-slas-private-secret>"
-        >
-            {children}
-        </CommerceApiProvider>
-    )
-}
-```
-#### Disable slas private warnings 
-By default, a warning as below will be displayed on client side to remind developers to always keep their secret safe and secured.
-```js
-'You are potentially exposing SLAS secret on browser. Make sure to keep it safe and secure!'
-```
-You can disable this warning by using CommerceProvider prop `silenceWarnings`
+To help reduce boilerplate code for managing shopper authentication, by default, this library automatically initializes shopper session and manages the tokens for developers. Commerce-sdk-react supports both the [SLAS Public Client login flow](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [SLAS Private Client login flow](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html). Authorization using a private client is supported in PWA Kit 3.5 and later, and is the recommended authorization workflow.
 
-```js
-const AppConfig = ({children}) => {
-    return (
-        <CommerceApiProvider
-            clientId="12345678-1234-1234-1234-123412341234"
-            organizationId="f_ecom_aaaa_001"
-            proxy="localhost:3000/mobify/proxy/api"
-            redirectURI="localhost:3000/callback"
-            siteId="RefArch"
-            shortCode="12345678"
-            locale="en-US"
-            currency="USD"
-            clientSecret="<your-slas-private-secret>"
-            silenceWarnings={true}
-        >
-            {children}
-        </CommerceApiProvider>
-    )
-}
-```
+#### Using a private SLAS client
+To enable a private client, see [Use a SLAS Private Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.html).
 
 ### Shopper Session Initialization
 
@@ -209,9 +160,27 @@ const Example = () => {
     const login = useAuthHelper(AuthHelpers.LoginRegisteredUserB2C)
     const logout = useAuthHelper(AuthHelpers.LogOut)
 
-    return <button onClick={() => {
-        login.mutate({username: 'kevin', password: 'pa$$word'})
-    }}>
+    return (
+        <div>
+            {/* Simple login */}
+            <button onClick={() => {
+                login.mutate({username: 'kevin', password: 'pa$$word'})
+            }}>
+                Login
+            </button>
+            
+            {/* Login with custom parameters */}
+            <button onClick={() => {
+                login.mutate({
+                    username: 'kevin', 
+                    password: 'pa$$word',
+                    customParameters: {c_customField: 'customValue'}
+                })
+            }}>
+                Login with Custom Parameters
+            </button>
+        </div>
+    )
 }
 ```
 
@@ -532,6 +501,109 @@ useEncUserId() => {encUserId: String, getEncUserIdWhenReady: Promise}
 useUsid() => {usid: String, getUsidWhenReady: Promise}
 ```
 
+## Advanced: Customizing SDK Clients with `transformSDKClient`
+
+To support advanced use cases, such as integrating with older templates or customizing API client behavior, `commerce-sdk-react` provides a utility called `transformSDKClient`. This utility wraps any Commerce SDK client instance in a JavaScript Proxy, enabling you to intercept and transform method arguments, headers, parameters, and other options before each SDK call is made.
+
+This is especially useful for:
+-   Adapting SDK clients for legacy or custom templates.
+-   Removing references to unused SDK clients.
+
+### How It Works
+
+`transformSDKClient` takes an SDK client instance and a configuration object. The configuration can include:
+-   `props`: Arbitrary props you want to pass to your transformer.
+-   `transformer`: A function that receives the props, method name, and options, and returns the transformed options.
+-   `onError`: (Optional) A function to handle errors thrown by SDK methods.
+
+Every method call on the proxied client passes through your transformer before being executed.
+
+#### Example: Passing Custom SDK Clients to the Provider
+
+You can use this utility to pass in your own SDK clients to the `CommerceApiProvider` via the `apiClients` prop, and apply custom transformations globally.
+
+```js
+import {CommerceApiProvider} from '@salesforce/commerce-sdk-react'
+import {ShopperProducts} from 'commerce-sdk-isomorphic'
+
+// Create your SDK client instances as usual
+const myShopperProductsClient = new ShopperProducts({
+    // ...your config
+})
+
+// Pass your client(s) in the apiClients prop
+const apiClients = {
+    shopperProducts: myShopperProductsClient
+    // ...add other clients as needed
+}
+
+const App = ({children}) => (
+    <CommerceApiProvider
+        // ...other required props
+        apiClients={apiClients}
+        // You can also pass custom headers, fetchOptions, etc.
+    >
+        {children}
+    </CommerceApiProvider>
+)
+```
+
+> **Note:** The `CommerceApiProvider` will automatically wrap each client in `apiClients` with `transformSDKClient`, using a default transformer that injects headers and fetch options from the provider props. You must use props passed to `CommerceApiProvider` for setting custom headers and fetch options. `transformSDKClient` merges headers and options passed in as props with the default values.
+
+### API Reference
+
+```ts
+transformSDKClient<T>(
+    client: T,
+    config: {
+        props?: any,
+        transformer?: (props, methodName: string, options: any) => any,
+        onError?: (methodName: string, error: any, options: any) => void
+    }
+): T
+```
+
+- **client**: The SDK client instance to wrap.
+- **config**:
+  - **props**: Any extra data you want to pass to your transformer.
+  - **transformer**: Function to transform method arguments before each SDK call.
+  - **onError**: (Optional) Function to handle errors from SDK methods.
+
+
+> **Note:** If you choose to pass the `apiClients` prop, you are responsible for providing all SDK clients you intend to use in your application. Any hooks or features that rely on a missing client will throw an error at runtime. This allows for customization, but requires you to explicitly include each client you need.
+
+### Handling Missing SDK Clients
+
+With the introduction of the optional `apiClients` prop and support for custom SDK client injection, `commerce-sdk-react` now provides robust error handling for missing clients. If you attempt to use a query or mutation hook for a client that was not initialized or passed to the `CommerceApiProvider`, a clear error will be thrown.
+
+For example, if you call a hook like `useShopperProducts` but did not provide a `shopperProducts` client in your `apiClients` prop, you will see an error message similar to this error.
+
+```text
+Missing required client: shopperProducts. Please initialize shopperProducts class and provide it in CommerceApiProvider's apiClients prop.
+```
+
+This ensures that your application fails fast and provides actionable feedback, making it easier to debug configuration issues—especially when integrating with older templates or customizing your SDK client setup.
+
+### Disabling Automatic Auth Initialization
+
+By default, `CommerceApiProvider` automatically initializes authentication by calling `auth.ready()` as soon as the provider renders. This is the standard and recommended behavior for most applications.
+
+**New in v3.4.0:** You can now optionally disable this automatic initialization by passing the `disableAuthInit` prop:
+
+```jsx
+<CommerceApiProvider
+    // ...other required props
+    disableAuthInit={true}
+>
+    {children}
+</CommerceApiProvider>
+```
+
+- **Default:** `disableAuthInit` is `false` (auth is initialized automatically).
+- **When to use:** Set `disableAuthInit` to `true` if you are initializing authentication outside of the provider (for example, in legacy PWA Kit templates or when using SSR with `getProps`). This prevents duplicate initialization and potential issues with tokens or customer information.
+
+> **Note:** For most modern PWA Kit and React Query-based apps, you do **not** need to set this prop.
+
 ## Roadmap
 
 -   Optimistic update support
@@ -550,3 +622,4 @@ useUsid() => {usid: String, getUsidWhenReady: Promise}
 -   [Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/routing.html)
 -   [Phased Headless Rollouts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html)
 -   [Launch Your Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.html)
+