feat: update the hooks action

Author: sf-tejas-nadkarni

packages/template-retail-react-app/app/components/_app/index.jsx

@@ -87,7 +87,7 @@ import Seo from '@salesforce/retail-react-app/app/components/seo'
 import ShopperAgent from '@salesforce/retail-react-app/app/components/shopper-agent'
 import {getPathWithLocale} from '@salesforce/retail-react-app/app/utils/url'
 import {getCommerceAgentConfig} from '@salesforce/retail-react-app/app/utils/config-utils'
-import {useOpenShopperAgent} from '@salesforce/retail-react-app/app/hooks/use-open-shopper-agent'
+import {useShopperAgent} from '@salesforce/retail-react-app/app/hooks/use-shopper-agent'
 
 const PlaceholderComponent = () => (
     <Center p="2">
@@ -286,7 +286,7 @@ const App = (props) => {
         history.push(path)
     }
 
-    const openShopperAgent = useOpenShopperAgent()
+    const {actions: shopperAgentActions} = useShopperAgent()
 
     const trackPage = () => {
         activeData.trackPage(site.id, locale.id, currency)
@@ -396,7 +396,7 @@ const App = (props) => {
                                                 onMyAccountClick={onAccountClick}
                                                 onWishlistClick={onWishlistClick}
                                                 onStoreLocatorClick={onOpenStoreLocator}
-                                                onAgentClick={openShopperAgent}
+                                                onAgentClick={shopperAgentActions.open}
                                             >
                                                 <HideOnDesktop>
                                                     <DrawerMenu

packages/template-retail-react-app/app/hooks/use-open-shopper-agent.test.js

@@ -8,15 +8,13 @@ import {useCallback} from 'react'
 import {launchChat} from '@salesforce/retail-react-app/app/utils/shopper-agent-utils'
 
 /**
- * React hook that returns a stable callback to open the shopper agent chat window.
- * Uses the embedded service bootstrap API to launch the chat.
- *
- * @returns {Function} openShopperAgent - Stable callback to open the shopper agent chat
+ * React hook that returns shopper agent actions.
+ * Uses the embedded service bootstrap API. Structured for future extension (e.g. close, sendMessage).
  */
-export function useOpenShopperAgent() {
-    const openShopperAgent = useCallback(() => {
+export function useShopperAgent() {
+    const open = useCallback(() => {
         launchChat()
     }, [])
 
-    return openShopperAgent
+    return {actions: {open}}
 }

…-app/app/hooks/use-open-shopper-agent.js …react-app/app/hooks/use-shopper-agent.jspackages/template-retail-react-app/app/hooks/use-open-shopper-agent.js renamed to packages/template-retail-react-app/app/hooks/use-shopper-agent.js packages/template-retail-react-app/app/hooks/use-open-shopper-agent.js renamed to packages/template-retail-react-app/app/hooks/use-shopper-agent.js

@@ -0,0 +1,59 @@
+/*
+ * 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 {renderHook, act} from '@testing-library/react'
+import {useShopperAgent} from '@salesforce/retail-react-app/app/hooks/use-shopper-agent'
+import {launchChat} from '@salesforce/retail-react-app/app/utils/shopper-agent-utils'
+
+jest.mock('@salesforce/retail-react-app/app/utils/shopper-agent-utils', () => ({
+    launchChat: jest.fn()
+}))
+
+describe('useShopperAgent', () => {
+    beforeEach(() => {
+        jest.clearAllMocks()
+    })
+
+    test('should return an object with actions', () => {
+        const {result} = renderHook(() => useShopperAgent())
+
+        expect(result.current).toEqual({actions: expect.any(Object)})
+        expect(result.current.actions).toHaveProperty('open')
+        expect(typeof result.current.actions.open).toBe('function')
+    })
+
+    test('should call launchChat when actions.open is invoked', () => {
+        const {result} = renderHook(() => useShopperAgent())
+
+        act(() => {
+            result.current.actions.open()
+        })
+
+        expect(launchChat).toHaveBeenCalledTimes(1)
+    })
+
+    test('should call launchChat each time actions.open is invoked', () => {
+        const {result} = renderHook(() => useShopperAgent())
+
+        act(() => {
+            result.current.actions.open()
+            result.current.actions.open()
+        })
+
+        expect(launchChat).toHaveBeenCalledTimes(2)
+    })
+
+    test('should return a stable open callback reference across re-renders', () => {
+        const {result, rerender} = renderHook(() => useShopperAgent())
+
+        const firstOpen = result.current.actions.open
+        rerender()
+        const secondOpen = result.current.actions.open
+
+        expect(firstOpen).toBe(secondOpen)
+    })
+})