@W-18895609: 🚀 Shopper Agent Experience v3.0 (#2658)

* feat: shopper agent experience v3.0

* fix: enabling streaming (#2911)

Author: sf-avinash-kasipathy

packages/pwa-kit-create-app/assets/bootstrap/js/config/default.js.hbs

@@ -6,8 +6,16 @@
  */
 /* eslint-disable @typescript-eslint/no-var-requires */
 const sites = require('./sites.js')
+const {parseCommerceAgentSettings} = require('./utils.js')
+
 module.exports = {
     app: {
+        // Commerce shopping agent configuration for embedded messaging service
+        // This enables an agentic shopping experience in the application
+        // This property accepts either a JSON string or a plain JavaScript object.
+        // The value is set from the COMMERCE_AGENT_SETTINGS environment variable.
+        // If the COMMERCE_AGENT_SETTINGS environment variable is not set, the feature is disabled.
+        commerceAgent: parseCommerceAgentSettings(process.env.COMMERCE_AGENT_SETTINGS),
         // Customize how your 'site' and 'locale' are displayed in the url.
         url: {
             {{#if answers.project.demo.enableDemoSettings}}

packages/pwa-kit-create-app/assets/bootstrap/js/config/utils.js.hbs

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2021, salesforce.com, 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
+ */
+
+/**
+ * Safely parses commerce agent settings from either a JSON string or object
+ * @param {string|object} settings - The commerce agent settings
+ * @returns {object} Parsed commerce agent settings object
+ */
+function parseCommerceAgentSettings(settings) {
+    // Default configuration when no settings are provided
+    const defaultConfig = {
+        enabled: 'false',
+        askAgentOnSearch: 'false',
+        embeddedServiceName: '',
+        embeddedServiceEndpoint: '',
+        scriptSourceUrl: '',
+        scrt2Url: '',
+        salesforceOrgId: '',
+        commerceOrgId: '',
+        siteId: ''
+    }
+
+    // If settings is already an object, return it
+    if (typeof settings === 'object' && settings !== null) {
+        return settings
+    }
+
+    // If settings is a string, try to parse it
+    if (typeof settings === 'string') {
+        try {
+            return JSON.parse(settings)
+        } catch (error) {
+            console.warn('Invalid COMMERCE_AGENT_SETTINGS format, using defaults:', error.message)
+            return defaultConfig
+        }
+    }
+
+    // If settings is undefined/null, return defaults
+    return defaultConfig
+}
+
+module.exports = {
+    parseCommerceAgentSettings
+}

packages/pwa-kit-create-app/assets/bootstrap/js/overrides/app/ssr.js.hbs

@@ -301,6 +301,9 @@ const {handler} = runtime.createHandler(options, (app) => {
                         'api.cquotient.com',
                         '*.c360a.salesforce.com'
                     ]
+                },
+                referrerPolicy: {
+                    policy: 'strict-origin-when-cross-origin'
                 }
             }
         })

packages/pwa-kit-create-app/assets/templates/@salesforce/retail-react-app/app/ssr.js.hbs

@@ -300,6 +300,9 @@ const {handler} = runtime.createHandler(options, (app) => {
                         'api.cquotient.com',
                         '*.c360a.salesforce.com'
                     ]
+                },
+                referrerPolicy: {
+                    policy: 'strict-origin-when-cross-origin'
                 }
             }
         })

packages/pwa-kit-create-app/assets/templates/@salesforce/retail-react-app/config/default.js.hbs

@@ -6,8 +6,16 @@
  */
 /* eslint-disable @typescript-eslint/no-var-requires */
 const sites = require('./sites.js')
+const {parseCommerceAgentSettings} = require('./utils.js')
+
 module.exports = {
     app: {
+        // Commerce shopping agent configuration for embedded messaging service
+        // This enables an agentic shopping experience in the application
+        // This property accepts either a JSON string or a plain JavaScript object.
+        // The value is set from the COMMERCE_AGENT_SETTINGS environment variable.
+        // If the COMMERCE_AGENT_SETTINGS environment variable is not set, the feature is disabled.
+        commerceAgent: parseCommerceAgentSettings(process.env.COMMERCE_AGENT_SETTINGS),
         // Customize settings for your url
         url: {
             {{#if answers.project.demo.enableDemoSettings}}

packages/pwa-kit-create-app/assets/templates/@salesforce/retail-react-app/config/utils.js.hbs

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2021, salesforce.com, 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
+ */
+
+/**
+ * Safely parses commerce agent settings from either a JSON string or object
+ * @param {string|object} settings - The commerce agent settings
+ * @returns {object} Parsed commerce agent settings object
+ */
+function parseCommerceAgentSettings(settings) {
+    // Default configuration when no settings are provided
+    const defaultConfig = {
+        enabled: 'false',
+        askAgentOnSearch: 'false',
+        embeddedServiceName: '',
+        embeddedServiceEndpoint: '',
+        scriptSourceUrl: '',
+        scrt2Url: '',
+        salesforceOrgId: '',
+        commerceOrgId: '',
+        siteId: ''
+    }
+
+    // If settings is already an object, return it
+    if (typeof settings === 'object' && settings !== null) {
+        return settings
+    }
+
+    // If settings is a string, try to parse it
+    if (typeof settings === 'string') {
+        try {
+            return JSON.parse(settings)
+        } catch (error) {
+            console.warn('Invalid COMMERCE_AGENT_SETTINGS format, using defaults:', error.message)
+            return defaultConfig
+        }
+    }
+
+    // If settings is undefined/null, return defaults
+    return defaultConfig
+}
+
+module.exports = {
+    parseCommerceAgentSettings
+}

packages/pwa-kit-runtime/CHANGELOG.md

@@ -1,4 +1,6 @@
-## v3.12.0-dev (Jul 22, 2025)
+## v3.12.0-dev (Jul 28, 2025)
+- This feature introduces an AI-powered shopping assistant that integrates Salesforce Embedded Messaging Service with PWA Kit applications. The shopper agent provides real-time chat support, search assistance, and personalized shopping guidance directly within the e-commerce experience. [#2658](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2658)
+
 ## v3.11.0 (Jul 22, 2025)
 - Fix the logger so that it will now print out details of the given Error object [#2486](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2486)
 - Only allow requests for `/shopper/auth/` through the SLAS private client proxy. Also stop the proxy from swallowing SLAS errors [#2608](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2608)