Merge branch 'main' into feature/subpath-import-and-fetch

Author: joeluong-sfcc

CHANGELOG.md

@@ -1,14 +1,42 @@
 # CHANGELOG
 
-## v4.1.0
+## v4.2.0
+
+### API Versions
+
+New APIs:
+- Shopper Configurations
+
+| API Name | API Version |
+|----------|-------------|
+| shopper-baskets | 1.9.1 |
+| shopper-baskets | 2.1.1 |
+| shopper-configurations | 1.0.0 |
+| shopper-consents | 1.1.2 |
+| shopper-context | 1.1.2 |
+| shopper-customers | 1.1.2 |
+| shopper-experience | 1.0.9 |
+| shopper-gift-certificates | 1.0.27 |
+| shopper-login | 1.40.0 |
+| shopper-orders | 1.5.1 |
+| shopper-products | 1.0.39 |
+| shopper-promotions | 1.0.37 |
+| shopper-search | 1.5.1 |
+| shopper-seo | 1.0.14 |
+| shopper-stores | 1.0.18 |
+
+## v4.1.0 (DEPRECATED)
 
 ### Enhancements
 
-- Allow developers to pass in custom fetch implementation via `clientConfig` [#246](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic/pull/246)
+- Use native node fetch available in node 18+ instead of `node-fetch` polyfill [#214](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic/pull/214)
 - Support subpath imports for individual APIs and named imports [#219](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic/pull/219)
 
-### Bug Fixes
+NOTE: This release is deprecated. The features introduced in v4.1.0 were experimental and were removed in v4.2.0
 
+## v4.0.1
+
+### Bug Fixes
 - Fix incorrect encoding of multi-segment endpoint paths in `callCustomEndpoint` [#246](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic/pull/246)
 
 ## v4.0.0

README.md

@@ -65,17 +65,7 @@ yarn install commerce-sdk-isomorphic
 ### Usage
 
 ```javascript
-import ocapi from 'commerce-sdk-isomorphic';
-const { helpers, ShopperLogin, ShopperSearch } = ocapi;
-
-// Named imports also work
-// import {helpers, ShopperLogin, ShopperSearch} from 'commerce-sdk-isomorphic';
-
-// Alternatively, you can use subpath imports to import a single API at a time instead of the entire SDK
-// Useful for when you want a slimmer bundle size and only need a single API
-// import * as helpers from 'commerce-sdk-isomorphic/helpers'
-// import { ShopperProducts } from 'commerce-sdk-isomorphic/shopperProducts';
-// import { ShopperSearch } from 'commerce-sdk-isomorphic/shopperSearch';
+import {helpers, ShopperLogin, ShopperSearch} from 'commerce-sdk-isomorphic';
 
 const config = {
   // SCAPI does not support CORS, so client side requests must use a reverse proxy.
@@ -103,91 +93,6 @@ const searchResult = await shopperSearch.productSearch({
 });
 ```
 
-#### Import Strategies
-
-The SDK supports multiple import patterns to accommodate different use cases:
-
-**Default Import (Full SDK)**
-```javascript
-import ocapi from 'commerce-sdk-isomorphic';
-const { helpers, ShopperLogin, ShopperSearch } = ocapi;
-```
-
-**Named Imports (Full SDK)**
-```javascript
-import { helpers, ShopperLogin, ShopperSearch } from 'commerce-sdk-isomorphic';
-```
-
-**Subpath Imports (Individual APIs and Common dependencies)**
-
-*ESM (ES Modules):*
-```javascript
-import { ShopperLogin } from 'commerce-sdk-isomorphic/shopperLogin';
-import * as helpers from 'commerce-sdk-isomorphic/helpers';
-```
-
-*CommonJS:*
-```javascript
-const { ShopperLogin } = require('commerce-sdk-isomorphic/shopperLogin');
-const helpers = require('commerce-sdk-isomorphic/helpers');
-```
-
-#### Choosing the Right Import Strategy
-
-**Use Default/Named Imports when:**
-- You need multiple APIs from the SDK
-- You want the smallest overall bundle size for comprehensive usage
-- The entire SDK is optimized and maximally compressed as a single bundle
-
-**Note:** Default and named imports load the entire SDK, including all APIs, helpers, and dependencies.
-
-**Use Subpath Imports when:**
-- You only need specific APIs
-- You want to minimize initial bundle size
-- You're implementing dynamic loading for better page performance
-- You need granular control over which APIs are loaded
-
-**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.
@@ -379,24 +284,6 @@ 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.

apis/shopper-baskets-oas-1.9.0/.metadata.json

@@ -3,7 +3,7 @@
   "name": "Shopper Baskets OAS",
   "groupId": "893f605e-10e2-423a-bdb4-f952f56eb6d8",
   "assetId": "shopper-baskets-oas",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "classifier": "oas",
   "tags": [],
   "descriptorVersion": "1.0.0",

…/shopper-baskets-oas-1.9.0/exchange.json …/shopper-baskets-oas-1.9.1/exchange.jsonapis/shopper-baskets-oas-1.9.0/exchange.json renamed to apis/shopper-baskets-oas-1.9.1/exchange.json apis/shopper-baskets-oas-1.9.0/exchange.json renamed to apis/shopper-baskets-oas-1.9.1/exchange.json

@@ -1,8 +1,12 @@
 openapi: 3.0.3
 info:
+  x-api-type: Shopper
+  x-api-family: Checkout
   title: Shopper Baskets
-  version: v1
+  version: 1.9.1
   description: |-
+    [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-baskets/shopper-baskets-oas-v1-public.yaml)
+
     # API Overview
 
     Use the Shopper Baskets API to create a basket in the B2C Commerce system and populate it with all the data required to ready the basket for checkout.
@@ -161,6 +165,8 @@ paths:
           description: Thrown if the shipment with the given shipment ID is unknown.
           content:
             application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
               examples:
                 ShipmentNotFound:
                   $ref: '#/components/examples/ShipmentNotFound'
@@ -184,30 +190,37 @@ paths:
       description: |-
         Transfer the previous shopper's basket to the current shopper by updating the basket's owner. No other values change. You must obtain the shopper authorization token via SLAS and you must provide the ‘guest usid‘ in both the ‘/oauth2/login‘ and ‘/oauth2/token‘ calls while fetching the registered user JWT token.
 
-        A success response contains the transferred basket.
+        This endpoint provides different methods for handling the scenario in which both a previous guest shopper and the current registered shopper have an active basket attached, and utilizes the `merge` parameter as follows:
+        - `true` (recommended): Triggers a merge hook for graceful handling and prevents 409 status returns. For more information, refer to the `merge` parameter documentation.
+        - `false`: Either overrides the basket of the current registered shopper or returns a 409 response, and allows you to choose between the options explained below.
 
-        If the current shopper has an active basket, and the `overrideExisting` request parameter is `false`, then the transfer request returns a BasketTransferException (HTTP status 409). You can proceed with one of these options:
+        If you call the endpoint with `merge=false` and the current shopper has an active basket, you have two options using the `overrideExisting` parameter. Setting it to `true` deletes the registered user's basket, while setting it to `false` returns a `BasketTransferException` (HTTP status 409), after which you can choose how to proceed:
         - Keep the current shopper's active basket.
-        - Merge the previous and current shoppers' baskets by calling the `baskets/merge` endpoint.
-        - Force the transfer by calling the `baskets/transfer` endpoint again, with the parameter `overrideExisting=true`. Forcing the transfer deletes the current shopper's active basket.
+        - Merge the previous and current shoppers' baskets by calling the `baskets/actions/merge` endpoint.
+        - Force the transfer by calling the `baskets/actions/transfer` endpoint again, with the parameter `overrideExisting=true`. Forcing the transfer deletes the current shopper's active basket.
+
+        A successful response provides the transferred (and merged) current basket. However, if neither the previous nor current shopper had an active basket, a 204 (No Content) response is returned.
       operationId: transferBasket
       summary: Transfer an existing basket.
       security:
         - ShopperToken:
             - sfcc.shopper-baskets-orders.rw
       parameters:
         - $ref: '#/components/parameters/overrideExisting'
+        - $ref: '#/components/parameters/merge'
         - $ref: '#/components/parameters/locale'
       responses:
         '200':
-          description: The transferred basket.
+          description: The current basket.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Basket'
               examples:
                 BasketPost:
                   $ref: '#/components/examples/examples-BasketPost'
+        '204':
+          description: The operation was successful. No current basket was returned because neither the previous nor current shopper had an active basket attached that could be transferred.
         '403':
           description: The call returns this error if no SLAS token for a registered shopper is available.
           content:
@@ -219,9 +232,9 @@ paths:
                   $ref: '#/components/examples/ForbiddenMissingPrevCustomerInfo'
         '409':
           description: |-
-            The call returns this response in either of these cases:
+            The call returns this response when the `merge` request parameter is set to `false` and one of the following cases applies:
             - The previous shopper has no active basket.
-            - The current shopper has an active basket and the `overrideExisting` query parameter was `false` (default value).
+            - The current shopper has an active basket and the `overrideExisting` query parameter is set to `false` (default value).
           content:
             application/json:
               schema:
@@ -239,6 +252,8 @@ paths:
       operationId: mergeBasket
       summary: Merge baskets.
       description: |-
+        ( DEPRECATED ) Instead of using this endpoint, we recommend using the `/baskets/actions/transfer` endpoint with the `merge=true` parameter, because the transfer endpoint offers greater customization by invoking a hook, allowing for adjustments if the default implementation does not process the merge as expected.
+
         Merge data from the previous shopper's basket into the current shopper's active basket and delete the previous shopper's basket. This endpoint doesn't merge Personally Identifiable Information (PII). You must obtain the shopper authorization token via SLAS and you must provide the ‘guest usid‘ in both the ‘/oauth2/login‘ and ‘/oauth2/token‘ calls while fetching the registered user JWT token. After the merge, all basket amounts are recalculated and totaled, including lookups for prices, taxes, shipping, and promotions, unless hooks are enabled.
 
         The following information is merged:
@@ -3901,6 +3916,14 @@ components:
         default: false
         type: boolean
         example: false
+    merge:
+      name: merge
+      in: query
+      description: "This parameter controls the behavior:\n    - `false` (default): Transfers the basket or returns a 409 response with the appropriate message (taking `overrideExisting` in consideration).\n    - `true`: (recommended): Executes the dw.order.mergeBasket hook if at least one basket exists.\n\nThe hook dw.order.mergeBasket default implementation merges a source basket into the current basket. This behavior can be customized, as shown \nin this [sample implementation](https://gist.github.com/sf-thomas-loesche/3446c7d71a97e559bf1caee96ae56d9f).\n\nThere are four possible use cases:\n\na) Guest basket and registered basket exist\nThe guest basket becomes the current basket for the registered shopper by updating the basket's owner (no personal data is removed). The hook \ndw.order.mergeBasket is called with the source basket (former registered shopper basket) and the transferred current basket (former guest basket).\n\nb) Guest basket exists but no registered basket exists\nThe guest basket becomes the current basket for the registered shopper by updating the basket's owner (no personal data is removed). The hook \ndw.order.mergeBasket is called without the source basket (null passed to the hook) and the transferred current basket (former guest basket).\n\nc) No guest basket exists but a registered basket exists\nThe registered basket is retained. The hook dw.order.mergeBasket is called with the retained current basket but without the source basket (null \npassed to the hook).\n\nd) Neither basket exists\nThe hook dw.order.mergeBasket is not called.\n\nThe API returns the current basket (after executing dw.order.mergeBasket)."
+      schema:
+        default: false
+        type: boolean
+        example: false
     createDestinationBasket:
       name: createDestinationBasket
       in: query

…1.9.0/shopper-baskets-oas-v1-public.yaml …1.9.1/shopper-baskets-oas-v1-public.yamlapis/shopper-baskets-oas-1.9.0/shopper-baskets-oas-v1-public.yaml renamed to apis/shopper-baskets-oas-1.9.1/shopper-baskets-oas-v1-public.yaml apis/shopper-baskets-oas-1.9.0/shopper-baskets-oas-v1-public.yaml renamed to apis/shopper-baskets-oas-1.9.1/shopper-baskets-oas-v1-public.yaml

@@ -3,7 +3,7 @@
   "name": "Shopper Baskets OAS",
   "groupId": "893f605e-10e2-423a-bdb4-f952f56eb6d8",
   "assetId": "shopper-baskets-oas",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "classifier": "oas",
   "tags": [],
   "descriptorVersion": "1.0.0",