diff --git a/packages/template-retail-react-app/app/components/search/index.jsx b/packages/template-retail-react-app/app/components/search/index.jsx
index 819e185a38..477eaaf244 100644
--- a/packages/template-retail-react-app/app/components/search/index.jsx
+++ b/packages/template-retail-react-app/app/components/search/index.jsx
@@ -41,6 +41,13 @@ import {
searchUrlBuilder,
categoryUrlBuilder
} from '@salesforce/retail-react-app/app/utils/url'
+import {getConfig} from '@salesforce/pwa-kit-runtime/utils/ssr-config'
+
+const onClient = typeof window !== 'undefined'
+
+function isAskAgentOnSearchEnabled(enabled, askAgentOnSearch) {
+ return enabled === 'true' && askAgentOnSearch === 'true' && onClient
+}
const formatSuggestions = (searchSuggestions, input) => {
return {
@@ -85,6 +92,9 @@ const formatSuggestions = (searchSuggestions, input) => {
* @return {React.ReactElement} - SearchInput component
*/
const Search = (props) => {
+ const config = getConfig()
+ const {enabled, askAgentOnSearch} = config.app.commerceAgent
+ const askAgentOnSearchEnabled = isAskAgentOnSearchEnabled(enabled, askAgentOnSearch)
const [isOpen, setIsOpen] = useState(false)
const [searchQuery, setSearchQuery] = useState('')
const navigate = useNavigation()
@@ -99,6 +109,10 @@ const Search = (props) => {
}
)
const searchInputRef = useRef()
+ const miawChatRef = useRef({
+ newChatLaunched: false,
+ hasFired: false
+ })
const recentSearches = getSessionJSONItem(RECENT_SEARCH_KEY)
const searchSuggestions = useMemo(
() => formatSuggestions(searchSuggestion.data, searchInputRef?.current?.value),
@@ -151,6 +165,46 @@ const Search = (props) => {
setIsOpen(false)
}
+ useEffect(() => {
+ const handleEmbeddedMessageSent = (e) => {
+ if (!miawChatRef.current.hasFired && miawChatRef.current.newChatLaunched) {
+ if (
+ e.detail.conversationEntry?.sender?.role === 'Chatbot' &&
+ searchInputRef?.current?.value
+ ) {
+ miawChatRef.current.hasFired = true
+ setTimeout(() => {
+ window.embeddedservice_bootstrap.utilAPI.sendTextMessage(
+ searchInputRef.current.value.trim()
+ )
+ }, 500)
+ }
+ }
+ }
+
+ window.addEventListener('onEmbeddedMessageSent', handleEmbeddedMessageSent)
+
+ return () => {
+ // Clean up
+ window.removeEventListener('onEmbeddedMessageSent', handleEmbeddedMessageSent)
+ }
+ }, [])
+ const launchChat = () => {
+ window.embeddedservice_bootstrap.utilAPI
+ .launchChat()
+ .then((successMessage) => {
+ /* TODO: With the Salesforce Winter '26 release, we will be able to use the
+ * onEmbeddedMessagingFirstBotMessageSent event instead, and get rid of this logic. */
+ if (successMessage.includes('Successfully initialized the messaging client')) {
+ miawChatRef.current.hasFired = false //We want the logic in onEmbeddedMessageSent to happen once per new conversation
+ miawChatRef.current.newChatLaunched = true
+ }
+ })
+ .catch((err) => {
+ console.error('launchChat error', err)
+ })
+ }
+
const onSubmitSearch = (e) => {
e.preventDefault()
// Avoid blank spaces to be searched
@@ -159,6 +213,25 @@ const Search = (props) => {
if (searchText.length < 1) {
return
}
+
+ if (askAgentOnSearchEnabled && window.embeddedservice_bootstrap) {
+ // Add a 500ms delay before sending the message to ensure the experience isn't jarring to the user
+ setTimeout(() => {
+ window.embeddedservice_bootstrap.utilAPI
+ .sendTextMessage(searchText)
+ .catch((err) => {
+ console.error(err)
+ if (
+ err.includes(
+ 'invoke API before the onEmbeddedMessagingConversationOpened event is fired'
+ )
+ ) {
+ launchChat()
+ }
+ })
+ }, 500)
+ }
+
saveRecentSearch(searchText)
clearInput()
navigate(searchUrlBuilder(searchText))
diff --git a/packages/template-retail-react-app/app/components/search/index.test.js b/packages/template-retail-react-app/app/components/search/index.test.js
index 1c224d8ff7..afcf88e9e7 100644
--- a/packages/template-retail-react-app/app/components/search/index.test.js
+++ b/packages/template-retail-react-app/app/components/search/index.test.js
@@ -24,6 +24,37 @@ import mockSearchResults from '@salesforce/retail-react-app/app/mocks/searchResu
import mockConfig from '@salesforce/retail-react-app/config/mocks/default'
import {rest} from 'msw'
import {mockCustomerBaskets} from '@salesforce/retail-react-app/app/mocks/mock-data'
+import {getConfig} from '@salesforce/pwa-kit-runtime/utils/ssr-config'
+
+jest.mock('@salesforce/pwa-kit-runtime/utils/ssr-config', () => {
+ const origin = jest.requireActual('@salesforce/pwa-kit-react-sdk/ssr/universal/utils')
+ return {
+ ...origin,
+ getConfig: jest.fn()
+ }
+})
+
+function getMockedConfigWithCommerceAgentSettings(mockConfig, enabled, askAgentOnSearch) {
+ const commerceAgentSettings = mockConfig.app.commerceAgent
+ const changedSettings = {
+ ...commerceAgentSettings,
+ enabled,
+ askAgentOnSearch
+ }
+ return {
+ ...mockConfig,
+ app: {
+ ...mockConfig.app,
+ commerceAgent: changedSettings
+ }
+ }
+}
+
+function setupUserEvent() {
+ return userEvent.setup({
+ advanceTimers: () => jest.runOnlyPendingTimers()
+ })
+}
beforeEach(() => {
clearSessionJSONItem(RECENT_SEARCH_KEY)
@@ -36,6 +67,8 @@ beforeEach(() => {
return res(ctx.delay(0), ctx.status(200), ctx.json(mockCustomerBaskets))
})
)
+ getConfig.mockImplementation(() => mockConfig)
+ jest.useFakeTimers()
})
test('renders SearchInput', () => {
@@ -45,7 +78,7 @@ test('renders SearchInput', () => {
})
test('changes url when enter is pressed', async () => {
- const user = userEvent.setup()
+ const user = setupUserEvent()
renderWithProviders(, {
wrapperProps: {siteAlias: 'uk', appConfig: mockConfig.app}
@@ -61,7 +94,7 @@ test('changes url when enter is pressed', async () => {
})
test('shows previously searched items when focused', async () => {
- const user = userEvent.setup()
+ const user = setupUserEvent()
setSessionJSONItem(RECENT_SEARCH_KEY, ['Dresses', 'Suits', 'Tops'])
renderWithProviders()
@@ -77,7 +110,8 @@ test('shows previously searched items when focused', async () => {
})
test('saves recent searches on submit', async () => {
- const user = userEvent.setup()
+ jest.useRealTimers()
+ const {user} = renderWithProviders()
setSessionJSONItem(RECENT_SEARCH_KEY, ['Dresses', 'Suits', 'Tops'])
renderWithProviders()
const searchInput = document.querySelector('input[type="search"]')
@@ -86,7 +120,8 @@ test('saves recent searches on submit', async () => {
})
test('limits number of saved recent searches', async () => {
- const user = userEvent.setup()
+ jest.useRealTimers()
+ const {user} = renderWithProviders()
setSessionJSONItem(RECENT_SEARCH_KEY, ['Dresses', 'Suits', 'Tops', 'Gloves', 'Bracelets'])
renderWithProviders()
@@ -96,12 +131,14 @@ test('limits number of saved recent searches', async () => {
})
test('suggestions render when there are some', async () => {
- const user = userEvent.setup()
- renderWithProviders()
+ jest.useRealTimers()
+ const {user} = renderWithProviders()
const searchInput = document.querySelector('input[type="search"]')
await user.type(searchInput, 'Dress')
+
expect(searchInput.value).toBe('Dress')
const suggestionPopoverEl = await screen.getByTestId('sf-suggestion-popover')
+
await waitFor(() => {
const suggestionsEl = within(suggestionPopoverEl).getByTestId('sf-suggestion')
expect(suggestionsEl.querySelector('button').textContent).toBe('Dresses')
@@ -109,7 +146,7 @@ test('suggestions render when there are some', async () => {
})
test('clicking clear searches clears recent searches', async () => {
- const user = userEvent.setup()
+ const user = setupUserEvent()
setSessionJSONItem(RECENT_SEARCH_KEY, ['Dresses', 'Suits', 'Tops'])
renderWithProviders()
const searchInput = document.querySelector('input[type="search"]')
@@ -125,3 +162,264 @@ test('passing undefined to Suggestions returns undefined', async () => {
)
expect(suggestions.innerHTML).toBeUndefined()
})
+
+test('when commerceAgent is disabled, chat functions are not called', async () => {
+ const user = setupUserEvent()
+
+ getConfig.mockImplementation(() =>
+ getMockedConfigWithCommerceAgentSettings(mockConfig, 'false', 'true')
+ )
+
+ // Create spies for chat functions
+ const sendTextMessageSpy = jest.fn()
+ const launchChatSpy = jest.fn()
+
+ // Mock window.embeddedservice_bootstrap
+ window.embeddedservice_bootstrap = {
+ utilAPI: {
+ sendTextMessage: sendTextMessageSpy,
+ launchChat: launchChatSpy
+ }
+ }
+
+ renderWithProviders()
+ const searchInput = document.querySelector('input[type="search"]')
+
+ // Perform a search
+ await user.type(searchInput, 'test search{enter}')
+
+ // Verify chat functions were not called
+ expect(sendTextMessageSpy).not.toHaveBeenCalled()
+ expect(launchChatSpy).not.toHaveBeenCalled()
+})
+
+test('when askAgentOnSearch is disabled, chat functions are not called', async () => {
+ const user = setupUserEvent()
+
+ getConfig.mockImplementation(() =>
+ getMockedConfigWithCommerceAgentSettings(mockConfig, 'false', 'true')
+ )
+
+ // Create spies for chat functions
+ const sendTextMessageSpy = jest.fn()
+ const launchChatSpy = jest.fn()
+
+ // Mock window.embeddedservice_bootstrap
+ window.embeddedservice_bootstrap = {
+ utilAPI: {
+ sendTextMessage: sendTextMessageSpy,
+ launchChat: launchChatSpy
+ }
+ }
+
+ renderWithProviders()
+ const searchInput = document.querySelector('input[type="search"]')
+
+ // Perform a search
+ await user.type(searchInput, 'test search{enter}')
+
+ // Verify chat functions were not called
+ expect(sendTextMessageSpy).not.toHaveBeenCalled()
+ expect(launchChatSpy).not.toHaveBeenCalled()
+})
+
+test('when askAgentOnSearch is enabled and sendTextMessage succeeds, launchChat is not called', async () => {
+ jest.useFakeTimers()
+ const user = setupUserEvent()
+
+ getConfig.mockImplementation(() =>
+ getMockedConfigWithCommerceAgentSettings(mockConfig, 'true', 'true')
+ )
+
+ // Create spies for chat functions
+ const sendTextMessageSpy = jest.fn().mockResolvedValue('success')
+ const launchChatSpy = jest.fn()
+
+ // Mock window.embeddedservice_bootstrap
+ window.embeddedservice_bootstrap = {
+ utilAPI: {
+ sendTextMessage: sendTextMessageSpy,
+ launchChat: launchChatSpy
+ }
+ }
+
+ renderWithProviders()
+ const searchInput = document.querySelector('input[type="search"]')
+
+ // Perform a search
+ await user.type(searchInput, 'test search{enter}')
+
+ // Wait for the setTimeout in onSubmitSearch
+ jest.advanceTimersByTime(500)
+
+ // Verify sendTextMessage was called but launchChat was not
+ expect(sendTextMessageSpy).toHaveBeenCalledWith('test search')
+ expect(launchChatSpy).not.toHaveBeenCalled()
+})
+
+test('when sendTextMessage fails and launchChat succeeds, sends message after bot response', async () => {
+ const user = setupUserEvent()
+
+ getConfig.mockImplementation(() =>
+ getMockedConfigWithCommerceAgentSettings(mockConfig, 'true', 'true')
+ )
+
+ // Create spies for chat functions
+ const sendTextMessageSpy = jest
+ .fn()
+ .mockRejectedValueOnce(
+ 'invoke API before the onEmbeddedMessagingConversationOpened event is fired'
+ )
+ .mockResolvedValue('success')
+ const launchChatSpy = jest
+ .fn()
+ .mockResolvedValue('Successfully initialized the messaging client')
+
+ // Mock window.embeddedservice_bootstrap
+ window.embeddedservice_bootstrap = {
+ utilAPI: {
+ sendTextMessage: sendTextMessageSpy,
+ launchChat: launchChatSpy
+ }
+ }
+
+ renderWithProviders()
+ const searchInput = document.querySelector('input[type="search"]')
+
+ // Perform a search
+ await user.type(searchInput, 'test search{enter}')
+
+ // Wait for the setTimeout in onSubmitSearch
+ jest.advanceTimersByTime(500)
+
+ // Verify first sendTextMessage failed and triggered launchChat
+ expect(sendTextMessageSpy).toHaveBeenCalledWith('test search')
+ expect(launchChatSpy).toHaveBeenCalled()
+
+ // Simulate bot response
+ window.dispatchEvent(
+ new CustomEvent('onEmbeddedMessageSent', {
+ detail: {
+ conversationEntry: {
+ sender: {
+ role: 'Chatbot'
+ }
+ }
+ }
+ })
+ )
+
+ // Wait for the setTimeout after bot message
+ jest.advanceTimersByTime(500)
+
+ // Verify second sendTextMessage was called
+ expect(sendTextMessageSpy).toHaveBeenCalledTimes(2)
+ expect(sendTextMessageSpy).toHaveBeenLastCalledWith('test search')
+
+ // Simulate bot response again
+ window.dispatchEvent(
+ new CustomEvent('onEmbeddedMessageSent', {
+ detail: {
+ conversationEntry: {
+ sender: {
+ role: 'Chatbot'
+ }
+ }
+ }
+ })
+ )
+
+ // Wait for the setTimeout after bot message
+ jest.advanceTimersByTime(500)
+
+ // Verify sendTextMessage was not called again
+ expect(sendTextMessageSpy).toHaveBeenCalledTimes(2)
+})
+
+test('when sendTextMessage fails and launchChat returns maximized message, no additional send text is triggered', async () => {
+ jest.useFakeTimers()
+ const user = setupUserEvent()
+
+ getConfig.mockImplementation(() =>
+ getMockedConfigWithCommerceAgentSettings(mockConfig, 'true', 'true')
+ )
+
+ // Create spies for chat functions
+ const sendTextMessageSpy = jest
+ .fn()
+ .mockRejectedValue(
+ 'invoke API before the onEmbeddedMessagingConversationOpened event is fired'
+ )
+ const launchChatSpy = jest.fn().mockResolvedValue('Successfully maximized the messaging client')
+
+ // Mock window.embeddedservice_bootstrap
+ window.embeddedservice_bootstrap = {
+ utilAPI: {
+ sendTextMessage: sendTextMessageSpy,
+ launchChat: launchChatSpy
+ }
+ }
+
+ renderWithProviders()
+ const searchInput = document.querySelector('input[type="search"]')
+
+ // Perform a search
+ await user.type(searchInput, 'test search{enter}')
+
+ // Wait for the setTimeout in onSubmitSearch
+ jest.advanceTimersByTime(500)
+
+ // Verify sendTextMessage was called and failed
+ expect(sendTextMessageSpy).toHaveBeenCalledWith('test search')
+ expect(launchChatSpy).toHaveBeenCalled()
+
+ // Wait for any potential setTimeout after launchChat
+ jest.advanceTimersByTime(500)
+
+ // Verify sendTextMessage was only called once
+ expect(sendTextMessageSpy).toHaveBeenCalledTimes(1)
+})
+
+test('when sendTextMessage and launchChat both fail, no additional send text is triggered', async () => {
+ jest.useFakeTimers()
+ const user = setupUserEvent()
+
+ getConfig.mockImplementation(() =>
+ getMockedConfigWithCommerceAgentSettings(mockConfig, 'true', 'true')
+ )
+
+ // Create spies for chat functions
+ const sendTextMessageSpy = jest
+ .fn()
+ .mockRejectedValue(
+ 'invoke API before the onEmbeddedMessagingConversationOpened event is fired'
+ )
+ const launchChatSpy = jest.fn().mockRejectedValue('Failed to launch chat')
+
+ // Mock window.embeddedservice_bootstrap
+ window.embeddedservice_bootstrap = {
+ utilAPI: {
+ sendTextMessage: sendTextMessageSpy,
+ launchChat: launchChatSpy
+ }
+ }
+
+ renderWithProviders()
+ const searchInput = document.querySelector('input[type="search"]')
+
+ // Perform a search
+ await user.type(searchInput, 'test search{enter}')
+
+ // Wait for the setTimeout in onSubmitSearch
+ jest.advanceTimersByTime(500)
+
+ // Verify sendTextMessage was called and failed
+ expect(sendTextMessageSpy).toHaveBeenCalledWith('test search')
+ expect(launchChatSpy).toHaveBeenCalled()
+
+ // Wait for any potential setTimeout after launchChat
+ jest.advanceTimersByTime(500)
+
+ // Verify sendTextMessage was only called once
+ expect(sendTextMessageSpy).toHaveBeenCalledTimes(1)
+})
diff --git a/packages/template-retail-react-app/app/components/shopper-agent/index.jsx b/packages/template-retail-react-app/app/components/shopper-agent/index.jsx
new file mode 100644
index 0000000000..b5c8c1ec6e
--- /dev/null
+++ b/packages/template-retail-react-app/app/components/shopper-agent/index.jsx
@@ -0,0 +1,227 @@
+/*
+ * Copyright (c) 2024, 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
+ */
+
+import React, {useEffect} from 'react'
+import useScript from '@salesforce/retail-react-app/app/hooks/use-script'
+import {useUsid} from '@salesforce/commerce-sdk-react'
+import PropTypes from 'prop-types'
+import {useTheme} from '@salesforce/retail-react-app/app/components/shared/ui'
+import useMiaw from '@salesforce/retail-react-app/app/hooks/use-miaw'
+
+const onClient = typeof window !== 'undefined'
+
+/**
+ * Validates that a URL is from a trusted Salesforce domain.
+ *
+ * @param {string} url - The URL to validate
+ * @returns {boolean} True if the URL is from a trusted Salesforce domain
+ */
+const validateSalesforceDomain = (url) => {
+ try {
+ const urlObj = new URL(url)
+ const hostname = urlObj.hostname
+
+ // Check for trusted Salesforce domains
+ return (
+ hostname.endsWith('.salesforce.com') ||
+ hostname.endsWith('.salesforce-scrt.com') ||
+ hostname.endsWith('pc-rnd.salesforce-scrt.com') ||
+ hostname.endsWith('.pc-rnd.site.com') ||
+ hostname.endsWith('.my.site.com')
+ )
+ } catch {
+ return false
+ }
+}
+
+/**
+ * Validates that all required commerce agent settings are present and of correct type.
+ *
+ * @param {Object} commerceAgent - Commerce agent configuration object
+ * @returns {boolean} True if all required fields are present and are strings
+ */
+const validateCommerceAgentSettings = (commerceAgent) => {
+ const requiredFields = [
+ 'enabled',
+ 'askAgentOnSearch',
+ 'embeddedServiceName',
+ 'embeddedServiceEndpoint',
+ 'scriptSourceUrl',
+ 'scrt2Url',
+ 'salesforceOrgId',
+ 'commerceOrgId',
+ 'siteId'
+ ]
+
+ const isValid = requiredFields.every((key) => typeof commerceAgent[key] === 'string')
+
+ if (!isValid) {
+ console.error('Invalid commerce agent settings.')
+ return false
+ }
+
+ // Add domain validation for script URL
+ if (commerceAgent.scriptSourceUrl) {
+ const isTrustedDomain = validateSalesforceDomain(commerceAgent.scriptSourceUrl)
+ if (!isTrustedDomain) {
+ console.error('Script URL must be from a trusted Salesforce domain.')
+ return false
+ }
+ }
+
+ return true
+}
+
+/**
+ * Checks if the shopper agent is enabled and running on client side.
+ *
+ * @param {string} enabled - String representation of enabled state
+ * @returns {boolean} True if enabled is 'true' and running on client
+ */
+const isEnabled = (enabled) => {
+ return enabled === 'true' && onClient
+}
+
+/**
+ * Internal component that renders the embedded messaging window.
+ * Handles event listeners for embedded messaging lifecycle events.
+ *
+ * @param {Object} props - Component props
+ * @param {Object} props.commerceAgentConfiguration - Commerce agent configuration
+ * @param {string} props.locale - The locale for the embedded messaging script
+ * @param {string} props.basketId - The basket ID for the embedded messaging script
+ * @returns {null} This component doesn't render any visible UI
+ */
+const ShopperAgentWindow = ({commerceAgentConfiguration, locale, basketId}) => {
+ const theme = useTheme()
+ const {
+ embeddedServiceName,
+ embeddedServiceEndpoint,
+ scriptSourceUrl,
+ scrt2Url,
+ salesforceOrgId,
+ commerceOrgId,
+ siteId
+ } = commerceAgentConfiguration
+
+ const {usid} = useUsid()
+
+ useEffect(() => {
+ const handleEmbeddedMessagingReady = () => {
+ window.embeddedservice_bootstrap.prechatAPI.setHiddenPrechatFields({
+ SiteId: siteId,
+ Locale: locale,
+ OrganizationId: commerceOrgId,
+ UsId: usid,
+ IsCartMgmtSupported: 'true'
+ })
+ }
+
+ const handleEmbeddedMessagingWindowMaximized = () => {
+ const zIndex = theme.zIndices.sticky + 1
+ const embeddedMessagingFrame = document.body.querySelector(
+ 'div.embedded-messaging iframe'
+ )
+ if (embeddedMessagingFrame) {
+ embeddedMessagingFrame.style.zIndex = zIndex
+ }
+ }
+
+ window.addEventListener('onEmbeddedMessagingReady', handleEmbeddedMessagingReady)
+ window.addEventListener(
+ 'onEmbeddedMessagingWindowMaximized',
+ handleEmbeddedMessagingWindowMaximized
+ )
+
+ // Cleanup function
+ return () => {
+ window.removeEventListener('onEmbeddedMessagingReady', handleEmbeddedMessagingReady)
+ window.removeEventListener(
+ 'onEmbeddedMessagingWindowMaximized',
+ handleEmbeddedMessagingWindowMaximized
+ )
+ }
+ }, [commerceAgentConfiguration, usid, theme.zIndices.sticky])
+
+ // whenever the basketId changes, update the hidden prechat fields
+ useEffect(() => {
+ const handleEmbeddedMessagingButtonClicked = () => {
+ window.embeddedservice_bootstrap.prechatAPI.setHiddenPrechatFields({
+ BasketId: basketId
+ })
+ }
+
+ window.addEventListener(
+ 'onEmbeddedMessagingButtonClicked',
+ handleEmbeddedMessagingButtonClicked
+ )
+
+ // Cleanup function
+ return () => {
+ window.removeEventListener(
+ 'onEmbeddedMessagingButtonClicked',
+ handleEmbeddedMessagingButtonClicked
+ )
+ }
+ }, [basketId])
+
+ // Load the embedded messaging script
+ const scriptLoadStatus = useScript(scriptSourceUrl)
+
+ // Initialize the embedded messaging service
+ useMiaw(
+ scriptLoadStatus,
+ salesforceOrgId,
+ embeddedServiceName,
+ embeddedServiceEndpoint,
+ scrt2Url,
+ locale
+ )
+
+ return null
+}
+
+ShopperAgentWindow.propTypes = {
+ commerceAgentConfiguration: PropTypes.object,
+ basketId: PropTypes.string,
+ locale: PropTypes.string
+}
+
+/**
+ * ShopperAgent component that initializes and manages the embedded messaging service.
+ * Conditionally renders the agent window based on configuration and loading state.
+ *
+ * @param {Object} props - Component props
+ * @param {Object} props.commerceAgentConfiguration - Commerce agent settings containing enabled, embeddedServiceName, etc.
+ * @param {string} props.basketId - The basket ID for the embedded messaging script
+ * @param {string} props.locale - The locale for the embedded messaging script
+ * @param {boolean} props.basketDoneLoading - Whether the basket has finished loading
+ * @returns {JSX.Element|null} The ShopperAgent component or null if conditions not met
+ */
+const ShopperAgent = ({commerceAgentConfiguration, basketId, locale, basketDoneLoading}) => {
+ const {enabled} = commerceAgentConfiguration
+ const isShopperAgentEnabled = isEnabled(enabled)
+
+ return isShopperAgentEnabled &&
+ basketDoneLoading &&
+ validateCommerceAgentSettings(commerceAgentConfiguration) ? (
+
+ ) : null
+}
+
+ShopperAgent.propTypes = {
+ commerceAgentConfiguration: PropTypes.object,
+ basketId: PropTypes.string,
+ locale: PropTypes.string,
+ basketDoneLoading: PropTypes.bool
+}
+
+export default ShopperAgent
diff --git a/packages/template-retail-react-app/app/components/shopper-agent/index.test.js b/packages/template-retail-react-app/app/components/shopper-agent/index.test.js
new file mode 100644
index 0000000000..bca1344538
--- /dev/null
+++ b/packages/template-retail-react-app/app/components/shopper-agent/index.test.js
@@ -0,0 +1,577 @@
+/*
+ * Copyright (c) 2024, 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
+ */
+
+import React from 'react'
+import {render, act} from '@testing-library/react'
+import ShopperAgent from '@salesforce/retail-react-app/app/components/shopper-agent/index'
+import useScript from '@salesforce/retail-react-app/app/hooks/use-script'
+
+// Mock the embeddedservice_bootstrap object
+const mockEmbeddedService = {
+ init: jest.fn(),
+ settings: {
+ language: '',
+ disableStreamingResponses: false
+ },
+ prechatAPI: {
+ setHiddenPrechatFields: jest.fn()
+ }
+}
+
+jest.mock('../../hooks/use-script', () => jest.fn().mockReturnValue({loaded: false, error: false}))
+
+jest.mock('@salesforce/commerce-sdk-react', () => {
+ const originalModule = jest.requireActual('@salesforce/commerce-sdk-react')
+ return {
+ ...originalModule,
+ useUsid: () => ({usid: 'test-usid'})
+ }
+})
+
+jest.mock('@salesforce/retail-react-app/app/components/shared/ui', () => {
+ const originalModule = jest.requireActual(
+ '@salesforce/retail-react-app/app/components/shared/ui'
+ )
+ return {
+ ...originalModule,
+ useTheme: jest.fn().mockReturnValue({
+ zIndices: {
+ sticky: 1100
+ }
+ })
+ }
+})
+
+const commerceAgentSettings = {
+ enabled: 'true',
+ askAgentOnSearch: 'true',
+ embeddedServiceName: 'MIAW_Guided_Shopper_production',
+ embeddedServiceEndpoint: 'https://myorg.salesforce.com/ESWMIAWGuidedShopper',
+ scriptSourceUrl: 'https://myorg.salesforce.com/ESWMIAWGuidedShopper/assets/js/bootstrap.min.js',
+ scrt2Url: 'https://myorg.salesforce.com-scrt.com',
+ salesforceOrgId: 'mock_salesforce_org_id',
+ commerceOrgId: 'mock_ecom_id',
+ siteId: 'RefArchGlobal'
+}
+
+describe('ShopperAgent Component', () => {
+ beforeEach(() => {
+ // Reset all mocks before each test
+ jest.clearAllMocks()
+
+ // Reset the mockEmbeddedService.init to not throw errors
+ mockEmbeddedService.init.mockImplementation(() => {})
+
+ // Mock the window.embeddedservice_bootstrap object
+ global.window.embeddedservice_bootstrap = mockEmbeddedService
+
+ useScript.mockReturnValue({loaded: false, error: false})
+
+ // Clear any existing scripts
+ const scripts = document.querySelectorAll('script[src]')
+ scripts.forEach((script) => script.remove())
+ })
+
+ afterEach(() => {
+ // Clean up the window.embeddedservice_bootstrap mock
+ delete global.window.embeddedservice_bootstrap
+ })
+
+ const defaultProps = {
+ commerceAgentConfiguration: commerceAgentSettings,
+ basketId: '4a67cda5b1b9325a29207854c1',
+ locale: 'en-US',
+ basketDoneLoading: true
+ }
+
+ test('should render nothing when enabled is false', () => {
+ const disabledSettings = {...commerceAgentSettings, enabled: 'false'}
+ const props = {...defaultProps, commerceAgentConfiguration: disabledSettings}
+ const {container} = render()
+
+ expect(container.firstChild).toBeNull()
+ })
+
+ test('should render nothing when basketDoneLoading is false', () => {
+ const props = {...defaultProps, basketDoneLoading: false}
+ const {container} = render()
+
+ expect(container.firstChild).toBeNull()
+ })
+
+ test('should not render anything when embeddedservice_bootstrap is not available', () => {
+ // Temporarily remove the mock for this test
+ const originalEmbeddedService = global.window.embeddedservice_bootstrap
+ delete global.window.embeddedservice_bootstrap
+ useScript.mockReturnValue({loaded: true, error: false})
+
+ render()
+
+ expect(mockEmbeddedService.init).not.toHaveBeenCalled()
+
+ // Restore the mock
+ global.window.embeddedservice_bootstrap = originalEmbeddedService
+ })
+
+ test('should initialize embedded service when all required props are provided', () => {
+ useScript.mockReturnValue({loaded: true, error: false})
+ render()
+ // Verify embedded service initialization
+ expect(mockEmbeddedService.init).toHaveBeenCalledWith(
+ commerceAgentSettings.salesforceOrgId,
+ commerceAgentSettings.embeddedServiceName,
+ commerceAgentSettings.embeddedServiceEndpoint,
+ {
+ scrt2URL: commerceAgentSettings.scrt2Url
+ }
+ )
+ })
+
+ test('should handle initialization error gracefully', () => {
+ // Mock console.error to avoid noise in test output
+ const consoleSpy = jest.spyOn(console, 'error').mockImplementation()
+ const errorMessage = 'Initialization failed'
+ useScript.mockReturnValue({loaded: true, error: false})
+ mockEmbeddedService.init.mockImplementation(() => {
+ throw new Error(errorMessage)
+ })
+
+ const {container} = render()
+
+ // Component should still render (error is caught in initEmbeddedMessaging)
+ expect(container.firstChild).toBeNull()
+
+ consoleSpy.mockRestore()
+ })
+
+ test('should not reinitialize embedded service when already initialized', () => {
+ // First render
+ const scriptLoadStatus = {loaded: true, error: false}
+ useScript.mockReturnValue(scriptLoadStatus)
+ const {rerender} = render()
+
+ expect(mockEmbeddedService.init).toHaveBeenCalled()
+
+ // Reset mock call counts
+ jest.clearAllMocks()
+
+ useScript.mockReturnValue(scriptLoadStatus)
+
+ // Re-render with same props
+ rerender()
+
+ // Should not call init again
+ expect(mockEmbeddedService.init).not.toHaveBeenCalled()
+ })
+
+ test('should reinitialize when commerce agent configuration changes', () => {
+ // First render
+ useScript.mockReturnValue({loaded: true, error: false})
+ const {rerender} = render()
+
+ expect(mockEmbeddedService.init).toHaveBeenCalledTimes(1)
+
+ // Reset mock call counts
+ jest.clearAllMocks()
+
+ // Re-render with different commerce agent configuration
+ const newCommerceAgentSettings = {
+ ...commerceAgentSettings,
+ salesforceOrgId: 'new_salesforce_org_id',
+ embeddedServiceName: 'NewService'
+ }
+ const newProps = {
+ ...defaultProps,
+ commerceAgentConfiguration: newCommerceAgentSettings
+ }
+
+ rerender()
+
+ // Should call init again with new configuration
+ expect(mockEmbeddedService.init).toHaveBeenCalledWith(
+ newCommerceAgentSettings.salesforceOrgId,
+ newCommerceAgentSettings.embeddedServiceName,
+ newCommerceAgentSettings.embeddedServiceEndpoint,
+ {
+ scrt2URL: newCommerceAgentSettings.scrt2Url
+ }
+ )
+ })
+
+ test('should set prechat fields correctly on different events', async () => {
+ useScript.mockReturnValue({loaded: true, error: false})
+ render()
+
+ // Test initial prechat fields set on ready event
+ await act(async () => {
+ window.dispatchEvent(new Event('onEmbeddedMessagingReady'))
+ })
+
+ expect(mockEmbeddedService.prechatAPI.setHiddenPrechatFields).toHaveBeenCalledWith({
+ SiteId: commerceAgentSettings.siteId,
+ Locale: defaultProps.locale,
+ OrganizationId: commerceAgentSettings.commerceOrgId,
+ UsId: 'test-usid',
+ IsCartMgmtSupported: 'true'
+ })
+
+ // Reset mock to test button click event
+ mockEmbeddedService.prechatAPI.setHiddenPrechatFields.mockClear()
+
+ // Test BasketId update when button is clicked
+ await act(async () => {
+ window.dispatchEvent(new Event('onEmbeddedMessagingButtonClicked'))
+ })
+
+ expect(mockEmbeddedService.prechatAPI.setHiddenPrechatFields).toHaveBeenCalledWith({
+ BasketId: defaultProps.basketId
+ })
+ })
+
+ test('should not render when commerce agent settings are invalid', () => {
+ const invalidCommerceAgentSettings = {
+ enabled: 'true',
+ // Missing required fields
+ embeddedServiceName: 'test-service',
+ scriptSourceUrl: 'https://test.com/script.js'
+ }
+ const props = {
+ ...defaultProps,
+ commerceAgentConfiguration: invalidCommerceAgentSettings
+ }
+
+ const consoleSpy = jest.spyOn(console, 'error').mockImplementation()
+ const {container} = render()
+
+ // Should log error about invalid settings
+ expect(consoleSpy).toHaveBeenCalledWith('Invalid commerce agent settings.')
+
+ // Component should not render anything
+ expect(container.firstChild).toBeNull()
+
+ consoleSpy.mockRestore()
+ })
+
+ test('should not load the script when the commerceAgent is disabled', () => {
+ const disabledSettings = {...commerceAgentSettings, enabled: 'false'}
+ const props = {...defaultProps, commerceAgentConfiguration: disabledSettings}
+
+ render()
+
+ // Component should not render anything when disabled
+ expect(useScript).not.toHaveBeenCalled()
+ })
+
+ test('should not render when script URL is from untrusted domain', () => {
+ const untrustedSettings = {
+ ...commerceAgentSettings,
+ scriptSourceUrl: 'https://malicious-site.com/script.js'
+ }
+ const props = {
+ ...defaultProps,
+ commerceAgentConfiguration: untrustedSettings
+ }
+
+ const consoleSpy = jest.spyOn(console, 'error').mockImplementation()
+ const {container} = render()
+
+ // Should log error about untrusted domain
+ expect(consoleSpy).toHaveBeenCalledWith(
+ expect.stringContaining('Script URL must be from a trusted Salesforce domain.')
+ )
+
+ // Component should not render anything
+ expect(container.firstChild).toBeNull()
+
+ consoleSpy.mockRestore()
+ })
+
+ test('should render when script URL is from trusted salesforce.com domain', () => {
+ const trustedSettings = {
+ ...commerceAgentSettings,
+ scriptSourceUrl:
+ 'https://myorg.salesforce.com/ESWMIAWGuidedShopper/assets/js/bootstrap.min.js'
+ }
+ const props = {
+ ...defaultProps,
+ commerceAgentConfiguration: trustedSettings,
+ basketDoneLoading: true
+ }
+
+ useScript.mockReturnValue({loaded: true, error: false})
+ render()
+
+ // Component should initialize when domain is trusted
+ expect(mockEmbeddedService.init).toHaveBeenCalled()
+ })
+
+ test('should render when script URL is from trusted salesforce-scrt.com domain', () => {
+ const trustedSettings = {
+ ...commerceAgentSettings,
+ scriptSourceUrl: 'https://myorg.salesforce-scrt.com/script.js'
+ }
+ const props = {
+ ...defaultProps,
+ commerceAgentConfiguration: trustedSettings,
+ basketDoneLoading: true
+ }
+
+ useScript.mockReturnValue({loaded: true, error: false})
+ render()
+
+ // Component should initialize when domain is trusted
+ expect(mockEmbeddedService.init).toHaveBeenCalled()
+ })
+
+ test('should render when script URL is from trusted pc-rnd.salesforce-scrt.com domain', () => {
+ const trustedSettings = {
+ ...commerceAgentSettings,
+ scriptSourceUrl: 'https://myorg.pc-rnd.salesforce-scrt.com/script.js'
+ }
+ const props = {
+ ...defaultProps,
+ commerceAgentConfiguration: trustedSettings,
+ basketDoneLoading: true
+ }
+
+ useScript.mockReturnValue({loaded: true, error: false})
+ render()
+
+ // Component should initialize when domain is trusted
+ expect(mockEmbeddedService.init).toHaveBeenCalled()
+ })
+
+ test('should render when script URL is from trusted pc-rnd.site.com domain', () => {
+ const trustedSettings = {
+ ...commerceAgentSettings,
+ scriptSourceUrl: 'https://orgfarm-1645fa246c.test1.my.pc-rnd.site.com/script.js'
+ }
+ const props = {
+ ...defaultProps,
+ commerceAgentConfiguration: trustedSettings,
+ basketDoneLoading: true
+ }
+
+ useScript.mockReturnValue({loaded: true, error: false})
+ render()
+
+ // Component should initialize when domain is trusted
+ expect(mockEmbeddedService.init).toHaveBeenCalled()
+ })
+
+ test('should not render when script URL is invalid', () => {
+ const invalidSettings = {
+ ...commerceAgentSettings,
+ scriptSourceUrl: 'not-a-valid-url'
+ }
+ const props = {
+ ...defaultProps,
+ commerceAgentConfiguration: invalidSettings
+ }
+
+ const consoleSpy = jest.spyOn(console, 'error').mockImplementation()
+ const {container} = render()
+
+ // Should log error about untrusted domain
+ expect(consoleSpy).toHaveBeenCalledWith(
+ expect.stringContaining('Script URL must be from a trusted Salesforce domain.')
+ )
+
+ // Component should not render anything
+ expect(container.firstChild).toBeNull()
+
+ consoleSpy.mockRestore()
+ })
+
+ test('should not render when script URL has subdomain of untrusted domain', () => {
+ const untrustedSettings = {
+ ...commerceAgentSettings,
+ scriptSourceUrl: 'https://subdomain.malicious-site.com/script.js'
+ }
+ const props = {
+ ...defaultProps,
+ commerceAgentConfiguration: untrustedSettings
+ }
+
+ const consoleSpy = jest.spyOn(console, 'error').mockImplementation()
+ const {container} = render()
+
+ // Should log error about untrusted domain
+ expect(consoleSpy).toHaveBeenCalledWith(
+ expect.stringContaining('Script URL must be from a trusted Salesforce domain.')
+ )
+
+ // Component should not render anything
+ expect(container.firstChild).toBeNull()
+
+ consoleSpy.mockRestore()
+ })
+
+ test('should set the z-index of the embedded messaging frame to the sticky z-index + 1 when the window is maximized', async () => {
+ const mockFrame = document.createElement('div')
+ mockFrame.style.zIndex = '0'
+
+ // Store original querySelector
+ const originalQuerySelector = document.body.querySelector
+
+ // Mock querySelector to return our mock frame
+ document.body.querySelector = jest.fn().mockImplementation((selector) => {
+ if (selector === 'div.embedded-messaging iframe') {
+ return mockFrame
+ }
+ return originalQuerySelector.call(document, selector)
+ })
+
+ useScript.mockReturnValue({loaded: true, error: false})
+ render()
+
+ // Simulate window maximize
+ await act(async () => {
+ window.dispatchEvent(new Event('onEmbeddedMessagingWindowMaximized'))
+ })
+
+ // Verify z-index was updated
+ expect(mockFrame.style.zIndex).toBe('1101') // sticky (1100) + 1
+
+ // Restore original querySelector
+ document.body.querySelector = originalQuerySelector
+ })
+
+ test('should update prechat fields when commerce agent configuration changes', async () => {
+ useScript.mockReturnValue({loaded: true, error: false})
+ const {rerender} = render()
+
+ // Trigger initial prechat fields setup
+ await act(async () => {
+ window.dispatchEvent(new Event('onEmbeddedMessagingReady'))
+ })
+
+ expect(mockEmbeddedService.prechatAPI.setHiddenPrechatFields).toHaveBeenCalledWith({
+ SiteId: commerceAgentSettings.siteId,
+ Locale: defaultProps.locale,
+ OrganizationId: commerceAgentSettings.commerceOrgId,
+ UsId: 'test-usid',
+ IsCartMgmtSupported: 'true'
+ })
+
+ // Reset mock
+ mockEmbeddedService.prechatAPI.setHiddenPrechatFields.mockClear()
+
+ // Re-render with different configuration
+ const newCommerceAgentSettings = {
+ ...commerceAgentSettings,
+ siteId: 'NewSiteId',
+ commerceOrgId: 'new_commerce_org_id'
+ }
+ const newProps = {
+ ...defaultProps,
+ commerceAgentConfiguration: newCommerceAgentSettings
+ }
+
+ rerender()
+
+ // Trigger prechat fields setup with new configuration
+ await act(async () => {
+ window.dispatchEvent(new Event('onEmbeddedMessagingReady'))
+ })
+
+ expect(mockEmbeddedService.prechatAPI.setHiddenPrechatFields).toHaveBeenCalledWith({
+ SiteId: newCommerceAgentSettings.siteId,
+ Locale: defaultProps.locale,
+ OrganizationId: newCommerceAgentSettings.commerceOrgId,
+ UsId: 'test-usid',
+ IsCartMgmtSupported: 'true'
+ })
+ })
+
+ describe('Event Listener Cleanup', () => {
+ let originalAddEventListener
+ let originalRemoveEventListener
+ const mockAddEventListener = jest.fn()
+ const mockRemoveEventListener = jest.fn()
+
+ const mockCommerceAgent = {
+ enabled: 'true',
+ askAgentOnSearch: 'true',
+ embeddedServiceName: 'TestService',
+ embeddedServiceEndpoint: 'https://test.endpoint.com',
+ scriptSourceUrl:
+ 'https://myorg.salesforce.com/ESWMIAWGuidedShopper/assets/js/bootstrap.min.js',
+ scrt2Url: 'https://myorg.salesforce.com-scrt.com',
+ salesforceOrgId: 'test-org-id',
+ commerceOrgId: 'test-commerce-id',
+ siteId: 'test-site-id'
+ }
+
+ beforeEach(() => {
+ originalAddEventListener = window.addEventListener
+ originalRemoveEventListener = window.removeEventListener
+ window.addEventListener = mockAddEventListener
+ window.removeEventListener = mockRemoveEventListener
+ })
+
+ afterEach(() => {
+ window.addEventListener = originalAddEventListener
+ window.removeEventListener = originalRemoveEventListener
+ })
+
+ test('should remove event listeners when component unmounts', () => {
+ useScript.mockReturnValue({loaded: true, error: false})
+ const props = {
+ ...defaultProps,
+ commerceAgentConfiguration: mockCommerceAgent,
+ basketDoneLoading: true
+ }
+
+ const {unmount} = render()
+
+ // Verify event listeners were added
+ expect(mockAddEventListener).toHaveBeenCalledWith(
+ 'onEmbeddedMessagingReady',
+ expect.any(Function)
+ )
+ expect(mockAddEventListener).toHaveBeenCalledWith(
+ 'onEmbeddedMessagingWindowMaximized',
+ expect.any(Function)
+ )
+ expect(mockAddEventListener).toHaveBeenCalledWith(
+ 'onEmbeddedMessagingButtonClicked',
+ expect.any(Function)
+ )
+
+ // Unmount the component
+ unmount()
+
+ // Verify event listeners were removed
+ expect(mockRemoveEventListener).toHaveBeenCalledWith(
+ 'onEmbeddedMessagingReady',
+ expect.any(Function)
+ )
+ expect(mockRemoveEventListener).toHaveBeenCalledWith(
+ 'onEmbeddedMessagingWindowMaximized',
+ expect.any(Function)
+ )
+ expect(mockRemoveEventListener).toHaveBeenCalledWith(
+ 'onEmbeddedMessagingButtonClicked',
+ expect.any(Function)
+ )
+ })
+
+ test('should not add event listeners when component is disabled', () => {
+ const disabledSettings = {...mockCommerceAgent, enabled: 'false'}
+ const props = {
+ ...defaultProps,
+ commerceAgentConfiguration: disabledSettings
+ }
+
+ render()
+
+ // Verify no event listeners were added
+ expect(mockAddEventListener).not.toHaveBeenCalled()
+ })
+ })
+})
diff --git a/packages/template-retail-react-app/app/hooks/use-miaw.js b/packages/template-retail-react-app/app/hooks/use-miaw.js
new file mode 100644
index 0000000000..f193944016
--- /dev/null
+++ b/packages/template-retail-react-app/app/hooks/use-miaw.js
@@ -0,0 +1,88 @@
+/*
+ * Copyright (c) 2024, 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
+ */
+
+import {useEffect} from 'react'
+
+const onClient = typeof window !== 'undefined'
+
+/**
+ * Initializes the embedded messaging service with the provided configuration.
+ *
+ * @param {string} salesforceOrgId - Salesforce organization ID
+ * @param {string} embeddedServiceDeploymentName - Name of the embedded service deployment
+ * @param {string} embeddedServiceDeploymentUrl - URL of the embedded service deployment
+ * @param {string} scrt2Url - SCRT2 URL for the embedded messaging service
+ * @param {string} locale - Locale for the embedded messaging service
+ */
+const initEmbeddedMessaging = (
+ salesforceOrgId,
+ embeddedServiceDeploymentName,
+ embeddedServiceDeploymentUrl,
+ scrt2Url,
+ locale
+) => {
+ try {
+ if (
+ onClient &&
+ window.embeddedservice_bootstrap &&
+ window.embeddedservice_bootstrap.settings
+ ) {
+ window.embeddedservice_bootstrap.settings.language = locale
+ window.embeddedservice_bootstrap.settings.disableStreamingResponses = true
+ window.embeddedservice_bootstrap.init(
+ salesforceOrgId,
+ embeddedServiceDeploymentName,
+ embeddedServiceDeploymentUrl,
+ {
+ scrt2URL: scrt2Url
+ }
+ )
+ }
+ } catch (err) {
+ console.error('Error initializing Embedded Messaging: ', err)
+ }
+}
+
+/**
+ * Custom hook that initializes embedded messaging when the script is loaded.
+ *
+ * @param {Object} scriptLoadStatus - Status of the embedded messaging script loading
+ * @param {string} salesforceOrgId - Salesforce organization ID
+ * @param {string} embeddedServiceDeploymentName - Name of the embedded service deployment
+ * @param {string} embeddedServiceDeploymentUrl - URL of the embedded service deployment
+ * @param {string} scrt2Url - SCRT2 URL for the embedded messaging service
+ * @param {string} locale - Locale for the embedded messaging service
+ */
+const useMiaw = (
+ scriptLoadStatus,
+ salesforceOrgId,
+ embeddedServiceDeploymentName,
+ embeddedServiceDeploymentUrl,
+ scrt2Url,
+ locale
+) => {
+ useEffect(() => {
+ if (scriptLoadStatus.loaded && !scriptLoadStatus.error) {
+ initEmbeddedMessaging(
+ salesforceOrgId,
+ embeddedServiceDeploymentName,
+ embeddedServiceDeploymentUrl,
+ scrt2Url,
+ locale
+ )
+ }
+ }, [
+ scriptLoadStatus,
+ salesforceOrgId,
+ embeddedServiceDeploymentName,
+ embeddedServiceDeploymentUrl,
+ scrt2Url,
+ locale
+ ])
+}
+
+export default useMiaw
diff --git a/packages/template-retail-react-app/app/hooks/use-script.js b/packages/template-retail-react-app/app/hooks/use-script.js
new file mode 100644
index 0000000000..5233bbc90a
--- /dev/null
+++ b/packages/template-retail-react-app/app/hooks/use-script.js
@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2024, 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
+ */
+
+import {useEffect, useState} from 'react'
+import PropTypes from 'prop-types'
+
+/**
+ * Custom hook to handle script loading
+ * @param {string} src - The source URL for the script
+ * @returns {Object} The script load status
+ */
+const useScript = (src) => {
+ const [scriptLoadStatus, setScriptLoadStatus] = useState({loaded: false, error: false})
+ // Effect to load and initialize the script
+ useEffect(() => {
+ if (!src) {
+ return
+ }
+
+ // Check if script already exists
+ const scriptAlreadyOnPage = document.querySelector(`script[src="${src}"]`)
+
+ if (!scriptAlreadyOnPage) {
+ const script = document.createElement('script')
+ script.src = src
+ script.defer = true
+ document.body.appendChild(script)
+
+ const onScriptLoad = (event) => {
+ const loadStatus = event.type === 'load' ? 'ready' : 'error'
+ setScriptLoadStatus({
+ loaded: loadStatus === 'ready',
+ error: loadStatus === 'error'
+ })
+ }
+
+ script.addEventListener('load', onScriptLoad)
+ script.addEventListener('error', onScriptLoad)
+ }
+ }, [src])
+
+ return scriptLoadStatus
+}
+
+useScript.propTypes = {
+ src: PropTypes.string
+}
+
+export default useScript
diff --git a/packages/template-retail-react-app/app/hooks/use-script.test.js b/packages/template-retail-react-app/app/hooks/use-script.test.js
new file mode 100644
index 0000000000..35859797f7
--- /dev/null
+++ b/packages/template-retail-react-app/app/hooks/use-script.test.js
@@ -0,0 +1,143 @@
+/*
+ * Copyright (c) 2024, 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
+ */
+
+import React from 'react'
+import {render, act} from '@testing-library/react'
+import useScript from '@salesforce/retail-react-app/app/hooks/use-script'
+import PropTypes from 'prop-types'
+// Test component that uses the hook
+const TestComponent = ({src}) => {
+ const scriptLoadStatus = useScript(src)
+
+ return {JSON.stringify(scriptLoadStatus)}
+}
+
+TestComponent.propTypes = {
+ src: PropTypes.string
+}
+
+describe('useScript hook', () => {
+ beforeEach(() => {
+ // Clear any existing scripts
+ const scripts = document.querySelectorAll('script[src]')
+ scripts.forEach((script) => script.remove())
+ })
+
+ test('should return initial state when no src is provided', () => {
+ const {getByTestId} = render()
+
+ expect(getByTestId('script-status').textContent).toBe(
+ JSON.stringify({loaded: false, error: false})
+ )
+ expect(document.querySelector('script[src]')).toBeNull()
+ })
+
+ test('should create and append script element when a script element does not exist', () => {
+ const src = 'https://test-script.js/'
+ render()
+
+ const script = document.querySelector(`script[src="${src}"]`)
+ expect(script).not.toBeNull()
+ expect(script.src).toBe(src)
+ expect(script.defer).toBe(true)
+ })
+
+ test('should not create a script element when a script element already exists', () => {
+ const src = 'https://test-script.js'
+
+ // Create an existing script
+ const existingScript = document.createElement('script')
+ existingScript.src = src
+ document.body.appendChild(existingScript)
+
+ const initialScriptCount = document.querySelectorAll(`script[src="${src}"]`).length
+
+ render()
+
+ const finalScriptCount = document.querySelectorAll(`script[src="${src}"]`).length
+ expect(finalScriptCount).toBe(initialScriptCount)
+ })
+
+ test('should update state to loaded when script loads successfully', () => {
+ const src = 'https://test-script.js'
+ const {getByTestId} = render()
+
+ const script = document.querySelector(`script[src="${src}"]`)
+
+ // Simulate script load event
+ act(() => {
+ script.dispatchEvent(new Event('load'))
+ })
+
+ expect(getByTestId('script-status').textContent).toBe(
+ JSON.stringify({loaded: true, error: false})
+ )
+ })
+
+ test('should update state to error when script fails to load', () => {
+ const src = 'https://test-script.js'
+ const {getByTestId} = render()
+
+ const script = document.querySelector(`script[src="${src}"]`)
+
+ // Simulate script error event
+ act(() => {
+ script.dispatchEvent(new Event('error'))
+ })
+
+ expect(getByTestId('script-status').textContent).toBe(
+ JSON.stringify({loaded: false, error: true})
+ )
+ })
+
+ test('should handle multiple script loads with the same src', () => {
+ const src = 'https://test-script.js'
+
+ // First render
+ const {getByTestId, rerender} = render()
+
+ const script = document.querySelector(`script[src="${src}"]`)
+
+ // Simulate first script load
+ act(() => {
+ script.dispatchEvent(new Event('load'))
+ })
+
+ const initialScriptCount = document.querySelectorAll(`script[src="${src}"]`).length
+
+ // Re-render with same src
+ rerender()
+
+ const finalScriptCount = document.querySelectorAll(`script[src="${src}"]`).length
+ expect(finalScriptCount).toBe(initialScriptCount)
+
+ // State should remain loaded
+ expect(getByTestId('script-status').textContent).toBe(
+ JSON.stringify({loaded: true, error: false})
+ )
+ })
+
+ test('should not load a new script when the src changes', () => {
+ const src1 = 'https://test-script-1.js/'
+ const src2 = 'https://test-script-2.js/'
+
+ const {rerender} = render()
+
+ const script1 = document.querySelector(`script[src="${src1}"]`)
+
+ // Simulate first script load
+ act(() => {
+ script1.dispatchEvent(new Event('load'))
+ })
+
+ // Re-render with different src
+ rerender()
+
+ const script2 = document.querySelector(`script[src="${src1}"]`)
+ expect(script2.src).toBe(src1)
+ })
+})
diff --git a/packages/template-retail-react-app/app/ssr.js b/packages/template-retail-react-app/app/ssr.js
index 52833a15cb..1864b169de 100644
--- a/packages/template-retail-react-app/app/ssr.js
+++ b/packages/template-retail-react-app/app/ssr.js
@@ -315,7 +315,13 @@ const {handler} = runtime.createHandler(options, (app) => {
// Connect to Einstein APIs
'api.cquotient.com',
// Connect to DataCloud APIs
- '*.c360a.salesforce.com'
+ '*.c360a.salesforce.com',
+ // Connect to SCRT2 URLs
+ '*.salesforce-scrt.com'
+ ],
+ 'frame-src': [
+ // Allow frames from Salesforce site.com (Needed for MIAW)
+ '*.site.com'
]
}
}
diff --git a/packages/template-retail-react-app/config/default.js b/packages/template-retail-react-app/config/default.js
index 3efeb8d8b8..8c50ea8ccb 100644
--- a/packages/template-retail-react-app/config/default.js
+++ b/packages/template-retail-react-app/config/default.js
@@ -6,9 +6,12 @@
*/
// eslint-disable-next-line @typescript-eslint/no-var-requires
const sites = require('./sites.js')
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const {parseCommerceAgentSettings} = require('./utils.js')
module.exports = {
app: {
+ commerceAgent: parseCommerceAgentSettings(process.env.COMMERCE_AGENT_SETTINGS),
url: {
site: 'path',
locale: 'path',
diff --git a/packages/template-retail-react-app/config/mocks/default.js b/packages/template-retail-react-app/config/mocks/default.js
index e3076c1ea9..1c90d27771 100644
--- a/packages/template-retail-react-app/config/mocks/default.js
+++ b/packages/template-retail-react-app/config/mocks/default.js
@@ -12,8 +12,21 @@
* To ensure that feature work correctly, we test our code with multi-site config in mind, so we created this mock config.
* A single-site, single-locale config is a special case of multi-site case.
*/
+const commerceAgentSettings = {
+ enabled: 'false',
+ askAgentOnSearch: 'false',
+ embeddedServiceName: 'MIAW_Guided_Shopper_production',
+ embeddedServiceEndpoint: 'https://myorg.salesforce.com/ESWMIAWGuidedShopper',
+ scriptSourceUrl: 'https://myorg.salesforce.com/ESWMIAWGuidedShopper/assets/js/bootstrap.min.js',
+ scrt2Url: 'https://myorg.salesforce.com-scrt.com',
+ salesforceOrgId: '00DSB00000MJ7YH',
+ commerceOrgId: 'f_ecom_zzeu_052',
+ siteId: 'RefArchGlobal'
+}
+
module.exports = {
app: {
+ commerceAgent: commerceAgentSettings,
url: {
locale: 'path',
site: 'path',
diff --git a/packages/template-retail-react-app/config/utils.js b/packages/template-retail-react-app/config/utils.js
new file mode 100644
index 0000000000..bfde4cd31d
--- /dev/null
+++ b/packages/template-retail-react-app/config/utils.js
@@ -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
+}
diff --git a/packages/template-retail-react-app/package.json b/packages/template-retail-react-app/package.json
index 31cc0e8e81..ada3599d8a 100644
--- a/packages/template-retail-react-app/package.json
+++ b/packages/template-retail-react-app/package.json
@@ -100,7 +100,7 @@
"bundlesize": [
{
"path": "build/main.js",
- "maxSize": "61 kB"
+ "maxSize": "62 kB"
},
{
"path": "build/vendor.js",
diff --git a/scripts/check-eslint-deps.js b/scripts/check-eslint-deps.js
new file mode 100644
index 0000000000..3ea00426ec
--- /dev/null
+++ b/scripts/check-eslint-deps.js
@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/*
+ * Copyright (c) 2025, Salesforce, 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
+ */
+/**
+ * Check if ESLint-related dependencies from pwa-kit-dev are present in root package.json devDependencies.
+ */
+const fs = require('fs')
+const path = require('path')
+const PWA_KIT_DEV_PKG = path.join(__dirname, '..', 'packages', 'pwa-kit-dev', 'package.json')
+const ROOT_PKG = path.join(__dirname, '..', 'package.json')
+
+const ESLINT_DEP_PATTERNS = [/^@typescript-eslint\//, /^eslint$/, /^eslint-/, /^prettier$/]
+
+function isESLintDependency(depName) {
+ return ESLINT_DEP_PATTERNS.some((pattern) => pattern.test(depName))
+}
+
+function checkESLintDependencies() {
+ const pwaKitDevPkg = JSON.parse(fs.readFileSync(PWA_KIT_DEV_PKG, 'utf8'))
+ const rootPkg = JSON.parse(fs.readFileSync(ROOT_PKG, 'utf8'))
+
+ const pwaKitDevESLintDeps = Object.keys(pwaKitDevPkg.dependencies || {}).filter((depName) =>
+ isESLintDependency(depName)
+ )
+ const rootESLintDeps = new Set(
+ Object.keys(rootPkg.devDependencies || {}).filter((depName) => isESLintDependency(depName))
+ )
+ const missingDeps = pwaKitDevESLintDeps.filter((dep) => !rootESLintDeps.has(dep))
+
+ if (missingDeps.length > 0) {
+ console.error(
+ `⚠️ The root package.json is missing these pwa-kit-dev's eslint dependencies: ${missingDeps.join(
+ ', '
+ )}`
+ )
+ console.error(
+ 'Due to our monorepo setup, those eslint dependencies are discoverable only if they are also at the root.'
+ )
+ process.exit(1)
+ }
+}
+
+if (require.main === module) {
+ checkESLintDependencies()
+}
+
+module.exports = {checkESLintDependencies}
+### 🖥️ From Cursor IDE
-3. Click **Tools & Integrations** > **MCP Tools** > **New MCP Server**.
+1. Open **Cursor**.
-
+2. Navigate to **Settings > Cursor Settings...**
+
-The `mcp.json` file opens. Add this definition to your `mcp.json` file and replace {{parent-dir-to-mcp}} and {{path-to-app-directory}} placeholders with correct values.
+3. Go to **Tools & Integrations > MCP Tools > New MCP Server**
+
+4. Update your `mcp.json` like this (edit the placeholders as needed):
```json
{
"mcpServers": {
- "pwa-kit-mcp": {
+ "pwa-kit": {
"command": "npx",
"args": ["-y", "@salesforce/pwa-kit-mcp"],
"env": {
@@ -70,136 +57,75 @@ The `mcp.json` file opens. Add this definition to your `mcp.json` file and repla
}
}
}
-}
+}
```
+_NOTE: Replace `{{path-to-app-directory}}` with the absolute path to your generated project's `app` subfolder. For example: `"/Users/username/mcp-server-folder/mystorefront/app"`._
-After you modify the `mcp.json` file, cursor will do these actions.
+Once saved, Cursor will:
-- Start the MCP server.
-- Connect to the MCP server as a client.
-- List available tools.
+* Launch the MCP server
+* Connect to it as a client
+* Display the available tools in the UI and how you can invoke them
-You can go back to MCP Tools and choose to enable/disable any MCP Server or tools.
+You can return to **MCP Tools** anytime to enable or disable specific tools or servers.
-### Method 2: Run MCP Server from Claude
+### 🧪 From Other MCP Clients
-#### Using Claude Desktop
+We currently only support Cursor IDE, but if you wish to try it out with your AI agent enabled IDE, you can manually run the server be following the below steps. **NOTE:** This server communicates via **stdio**, so it is important to ensure your IDE can communicate in this manner.
-1. In the Claude app menu, on the top menu bar, click **Developer** > **Edit Config**.
-The `claude_desktop_config.json` file opens.
+```bash
+cd {{dir-to-mcp}}
+npm run start
+```
-
+Then send JSON-RPC requests like:
-2. Add this server definition to your `claude_desktop_config.json` and replace {{path-to-node}}, {{parent-dir-to-mcp}} and {{path-to-app-directory}} placeholders with correct values.
+```json
+{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
+{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "create_new_component", "arguments": {}}}
+```
+
+---
+
+## 👩💻 Development
+If you are actively developing features for the MCP server and want to get immediate feedback during testing, follow the below steps.
+
+1. Update your Cursor IDE MCP server configuration so that you are referencing the local server. This can be done by opening the "View: Open MCP Settings"
+from the command pallet and editing your `pwa-kit` entry to look like the entry below.
```json
{
"mcpServers": {
- "pwa-kit-mcp": {
- "command": "npx",
- "args": ["-y", "@salesforce/pwa-kit-mcp"],
+ "pwa-kit": {
+ "command": "node",
+ "args": ["{{path-to-app-mono-repo}}/packages/pwa-kit-mcp/dist/server/server.js"],
"env": {
"PWA_STOREFRONT_APP_PATH": "{{path-to-app-directory}}"
}
}
}
-}
+}
```
-After you modify the `claude_desktop_config.json` file, Claude will do these actions.
-
-- Start the MCP server.
-- Connect to the MCP server as a client.
-- List available tools.
-
-
-
-You can also enable/disable any available tools from here.
-
-#### Using other MCP clients
-The server runs on stdio, so you can test it with any MCP-compatible client.
-
-### Method 3: Manually start MCP Server
-
-You can also manually start the server from command line and sending JSON-RPC messages:
-
+2. Ensure that your server is built and will rebuild whenever changes are made you by running the following command in the `/pwa-kit-mcp` folder:
```bash
-cd {{dir-to-mcp}}
-# Start the server
-npm run start
-
-# Then send JSON-RPC requests to stdin:
-{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
-{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "create_new_component", "arguments": {}}}
+npm run build:watch
```
-## Files
-
-- `server.js` - Main MCP server implementation
-- `mcp.json` - MCP configuration file for clients
-- `package.json` - Node.js dependencies and scripts
+The server logs to `stderr` and communicates using MCP via `stdio`. You can view these logs in the `Output` section (shift + command + U) and filtering
+the output on "MCP Logs".
-## Development
-To run the server in development mode:
-```bash
-npm start
-```
+### 🔹 File & Folder Overview
-The server outputs debug information to stderr and handle MCP protocol messages via stdio.
-
-# Project Structure
-
-```
-/ (root)
- - package.json
- - package-lock.json
- - README.md
- - CHANGELOG.md
- - mcp.json
- - claude_desktop_config.json
- - babel.config.js
- - jest.config.js
- - jest-setup.js
- - .eslintrc.js
- - .eslintignore
- /src
- /server
- - server.js
- - server.test.js
- /tools
- - index.js
- - developer-guideline.js
- - developer-guideline.test.js
- - create-app-guideline.js
- - create-app-guideline.test.js
- - create-new-component.js
- - create-new-component.test.js
- - site-test.js
- - site-test.test.js
- - site-test-accessibility.js
- - site-test-performance.js
- /utils
- - index.js
- - utils.js
- - utils.test.js
- /data
- - CategoryDocument.json
- - DocumentList.json
- - ProductDocument.json
- /docs
- /images
- - claude-config.png
- - claude-list-tools.png
- - cursor-mcp-tools.png
- - cursor-settings.png
- - cursor-integration-guide.md
- /dist
-```
+| Location | Purpose |
+| -------------- | --------------------------------------------------------------------- |
+| `package.json` | Node.js dependencies and project scripts |
+| `mcp.json` | MCP client configuration (used by Cursor or other IDEs) |
+| `src/server/` | Main server entry point (`server.js`) |
+| `src/tools/` | Contains all MCP tools like `create-app-guideline`, `site-test`, etc. |
+| `src/utils/` | Shared utility functions |
+| `src/data/` | Static documents (e.g., product/category data models) used by tools |
+| `docs/` | Documentation and images for integration guides |
+| `dist/` | Compiled output when building the package |
-- Server code is in `src/server/`.
-- MCP tools are in `src/tools/`.
-- Utilities are in `src/utils/`.
-- Data files are in `src/data/`.
-- Documentation is in `docs/`.
-- Built distribution files are in `dist/`.
diff --git a/packages/pwa-kit-mcp/src/server/server.js b/packages/pwa-kit-mcp/src/server/server.js
index 5820f1ef45..3e828a9aaa 100644
--- a/packages/pwa-kit-mcp/src/server/server.js
+++ b/packages/pwa-kit-mcp/src/server/server.js
@@ -13,7 +13,8 @@ import {
CreateAppGuidelinesTool,
CreateNewComponentTool,
DeveloperGuidelinesTool,
- TestWithPlaywrightTool
+ TestWithPlaywrightTool,
+ CreateNewPageTool
} from '../tools'
// NOTE: This is a workaround to import JSON files as ES modules.
@@ -87,6 +88,13 @@ class PwaStorefrontMCPServerHighLevel {
},
(args) => this.handleCreateNewSampleComponent(args)
)
+
+ this.server.tool(
+ CreateNewPageTool.name,
+ CreateNewPageTool.description,
+ CreateNewPageTool.inputSchema,
+ CreateNewPageTool.handler
+ )
}
/**
diff --git a/packages/pwa-kit-mcp/src/tools/create-new-component.js b/packages/pwa-kit-mcp/src/tools/create-new-component.js
index 14ae350abf..56f0d2bd0c 100644
--- a/packages/pwa-kit-mcp/src/tools/create-new-component.js
+++ b/packages/pwa-kit-mcp/src/tools/create-new-component.js
@@ -6,17 +6,7 @@
*/
import fs from 'fs/promises'
import path from 'path'
-import {toKebabCase, toPascalCase} from '../utils/utils'
-
-export const getCopyrightHeader = () => {
- const year = new Date().getFullYear()
- return `/*
- * Copyright (c) ${year}, Salesforce, 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
- */`
-}
+import {toKebabCase, toPascalCase, getCopyrightHeader} from '../utils'
// Utility to infer entity from component name
function inferEntityFromComponentName(componentName) {
diff --git a/packages/pwa-kit-mcp/src/tools/create-new-page-tool.js b/packages/pwa-kit-mcp/src/tools/create-new-page-tool.js
new file mode 100644
index 0000000000..5c63c148ad
--- /dev/null
+++ b/packages/pwa-kit-mcp/src/tools/create-new-page-tool.js
@@ -0,0 +1,303 @@
+/*
+ * Copyright (c) 2025, Salesforce, 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
+ */
+import fs from 'fs/promises'
+import path from 'path'
+import {toKebabCase, toPascalCase, logMCPMessage} from '../utils'
+import {z} from 'zod'
+
+const systemPromptForCreatePage = `You are a smart assistant that can use tools when needed. \
+ Please ask the user to provide following information **one at a time**, in a natural and conversational way. \
+ Do **not** ask all the questions at once. \
+ Do **not** assume the answers to the questions, especially the URL route. **Always** ask the user for the URL route. \
+ - What is the name of the new page to create? \
+ - List the components to include on the page, separated by commas (e.g., Image, ProductView) \
+ - What is the URL route for this page? (e.g., /new-home, /my-products) \
+ Collect answers to these questions, then call the tool with the collected information as input parameters.`
+
+const systemPromptForProductHook = `User have added the ProductView component to the new page. Please ask user: \
+ "To make it work, would you like to add the hook useProduct to your page?" \
+ If user answers yes, please make sure do do following: \
+ 1. add the useProduct with ALL parameters following product-detail's useProduct as example, \
+ 2. update ProductView tag to pass product and isProductLoading as props, \
+ 3. in routes.jsx, update the path for the new page with '/:productId'. \
+ 4. open the new page in the browser with URL: http://localhost:3000/{static-route-path}/25592300M \
+ If user answers no, skip above steps.`
+
+const systemPromptForImageComponent = `User has added the Image component to the new page. Please ask the user, after they have provided the URL route:
+ "To make it work, would you like to provide the full path of the image source to your page? Note that CORS (Cross-Origin Resource Sharing) restrictions may apply."
+
+ If the user answers yes, please do the following:
+ 1. Ask the user to provide the full path of the image source.
+ 2. If the image is from a URL from the internet, always check in the codebase if the domain of the image source is present in the CSP img-src allow list in ssr.js or related server files.
+ 3. When checking the allow list, also check for wildcard entries (e.g., '*.domain.com') that would cover the provided domain. If either the exact domain or a matching wildcard is present, inform the user that the image source is already allowed by the CSP and proceed.
+ 4. If neither the domain nor a matching wildcard is present in the allow list, inform the user and **do not** update the src of the Image component. Tell the user that the CSP img-src allow list needs to be updated manually, and do not proceed further until the domain is confirmed present in the codebase.
+ 5. **Do not** update the CSP img-src allow list in ssr.js yourself; always ask the user to update the CSP img-src allow list manually, even if the user requests it.
+ 6. Once the user confirms they have updated the CSP img-src allow list, check again in the codebase if the domain of the image source or a matching wildcard is part of the CSP img-src allow list. If yes, then proceed. If no, tell the user that the CSP img-src allow list needs to be updated manually, or ask the user to provide another image source.
+ 7. Only if the image from the internet is part of the CSP img-src allow list (either by exact domain or wildcard), then proceed.
+ 8. If the image source is an https URL, then use the image source directly in the Image component. If it's a local image, update the path inside getAssetUrl and use it in the Image component.
+ 9. Ask the user to provide the alt text for the image.
+ 10. Ask the user to provide the width and height of the image.
+ 11. Update the src, alt text, width, and height of the Image component in the newly created page once the user has provided them.
+ 12. Request the user to restart the front end server.
+ 13. Open the new page in the browser with URL: http://localhost:3000/{static-route-path}
+
+ If the user answers no, tell the user that the default image located at /static/img/hero.png is being displayed.
+
+ Note:
+ If the automation cannot detect the Image component but you know it exists and works as intended, proceed with the above steps as if the component is available. Do not block or alter the workflow due to the detection issue. Clearly communicate to the user that the Image component will be used, even if it was not detected by the automation.
+ `
+
+const systemPromptForUnfoundComponents = (unfoundComponents) =>
+ `The following components were not found: ${unfoundComponents.join(', ')}. \
+ If the component is not found, **Please** suggest changes to the newly generated page file based on the components not found.`
+
+class CreateNewPageTool {
+ constructor() {
+ this.name = 'create_sample_storefront_page'
+ this.description =
+ 'Create a sample PWA storefront page. Gather information from user for the MCP tool parameters **one at a time**, in a natural and conversational way. Do **not** ask all the questions at once.'
+ this.inputSchema = {
+ pageName: z.string().describe('The name of the new page to create?'),
+ componentList: z
+ .array(z.string())
+ .describe(
+ 'The existing components to include on the page, separated by commas (e.g., AddressDisplay, ProductView, Footer)'
+ ),
+ route: z
+ .string()
+ .describe('The URL route for this page? (e.g., /new-home, /my-product-view)')
+ }
+ this.unfoundComponents = []
+
+ this.handler = async (args) => {
+ logMCPMessage(`------- Calling CreateNewPageTool handler`)
+ if (!args || !args.pageName || !args.componentList || !args.route) {
+ return {
+ role: 'system',
+ content: [{type: 'text', text: systemPromptForCreatePage}]
+ }
+ }
+ return this.createPage(args.pageName, args.componentList, args.route)
+ }
+ }
+
+ async createPage(pageName, componentList, route) {
+ logMCPMessage(
+ `========== Creating page ${pageName} with components ${componentList} and route ${route}`
+ )
+ this.unfoundComponents = []
+ await logMCPMessage(
+ `Creating page ${pageName} with components ${componentList} and route ${route}`
+ )
+
+ try {
+ const messages = []
+ const pagesDir = path.join(process.env.PWA_STOREFRONT_APP_PATH, 'pages')
+ pageName = toPascalCase(pageName)
+ const pageDir = path.join(pagesDir, toKebabCase(pageName))
+ try {
+ await fs.access(pageDir)
+ throw new Error(`Page directory already exists: ${pageDir}`)
+ } catch (err) {
+ if (err.code !== 'ENOENT') throw err
+ }
+ await fs.mkdir(pageDir, {recursive: true})
+ if (componentList.length == 0) {
+ componentList.push(pageName)
+ }
+ const pageContent = await this.generatePageContent(pageName, componentList)
+ logMCPMessage(`!!!!!! \n pageContent: ${pageContent} \n !!!!!`)
+ const indexPath = path.join(pageDir, 'index.jsx')
+ await fs.writeFile(indexPath, pageContent, 'utf8')
+ await this.updateRoutes(pageName, route)
+ messages.push(`Created page ${pageName} at ${pageDir}`)
+ messages.push(`Added route ${route}`)
+ logMCPMessage(`componentList: ${componentList}`)
+ if (componentList.includes('ProductView')) {
+ messages.push(systemPromptForProductHook)
+ }
+ if (componentList.includes('Image')) {
+ messages.push(systemPromptForImageComponent)
+ }
+ logMCPMessage(`Unfound components: ${this.unfoundComponents}`)
+ if (this.unfoundComponents.length != 0) {
+ messages.push(systemPromptForUnfoundComponents(this.unfoundComponents))
+ }
+ logMCPMessage(messages.join('\n'))
+ return {
+ role: 'system',
+ content: [{type: 'text', text: messages.join('\n')}]
+ }
+ } catch (error) {
+ logMCPMessage(`Error creating page: ${error.message}`)
+ return {
+ role: 'developer',
+ content: [{type: 'text', text: `Error creating page: ${error.message}`}]
+ }
+ }
+ }
+
+ generatePageContent(pageName, componentList) {
+ const imports = [
+ `import React from 'react'`,
+ `import {Box} from '@salesforce/retail-react-app/app/components/shared/ui'`,
+ `import Seo from '@salesforce/retail-react-app/app/components/seo'`
+ ]
+
+ // Add component imports
+ const accessPromises = componentList.map(async (component) => {
+ component = toPascalCase(component)
+ const componentName = component.charAt(0).toUpperCase() + component.slice(1)
+ const componentDir = toKebabCase(componentName)
+ try {
+ await fs.access(
+ path.join(process.env.PWA_STOREFRONT_APP_PATH, 'components', componentDir)
+ )
+ } catch (err) {
+ if (err.code === 'ENOENT') {
+ this.unfoundComponents.push(component)
+ } else {
+ throw err
+ }
+ }
+ logMCPMessage(
+ `?????? importing ${componentName} from '@salesforce/retail-react-app/app/components/${componentDir}'`
+ )
+ imports.push(
+ `import {getAssetUrl} from '@salesforce/pwa-kit-react-sdk/ssr/universal/utils'`,
+ `import ${componentName} from '@salesforce/retail-react-app/app/components/${componentDir}'`
+ )
+ // Import getAssetUrl for displaying image source if Image component is used
+ if (componentName === 'Image') {
+ imports.push(
+ `import {getAssetUrl} from '@salesforce/pwa-kit-react-sdk/ssr/universal/utils'`
+ )
+ }
+ })
+
+ return Promise.all(accessPromises).then(() => {
+ logMCPMessage(`?????? imports ${imports.join('\n')}`)
+
+ const componentJsx = componentList
+ .map((component) => {
+ component = toPascalCase(component)
+ const componentName = component.charAt(0).toUpperCase() + component.slice(1)
+ if (componentName === 'Image') {
+ return `