W-19443266: Handle Failure use-cases in the UI (#3534)

* W-19443266:  Handle Failure use-cases by calling Fail Order where necessary.  Also refactor the client-secret retrieval since the response structure has changed.

Author: amittapalli

packages/commerce-sdk-react/src/hooks/ShopperOrders/cache.ts

@@ -47,5 +47,21 @@ export const cacheUpdateMatrix: CacheUpdateMatrix<Client> = {
     },
     createPaymentInstrumentForOrder: updateOrderQuery,
     updatePaymentInstrumentForOrder: updateOrderQuery,
-    removePaymentInstrumentFromOrder: updateOrderQuery
+    removePaymentInstrumentFromOrder: updateOrderQuery,
+    failOrder(customerId, {parameters}) {
+        // Exclude reopenBasket (not valid for getOrder) and pass only valid parameters
+        // to getOrder.queryKey, while preserving common params like organizationId, siteId
+        const {orderNo, reopenBasket, ...orderParams} = parameters
+        const invalidate: CacheUpdateInvalidate[] = [
+            {queryKey: getOrder.queryKey({...orderParams, orderNo})}
+        ]
+        // If reopenBasket is true, we should also invalidate customer baskets
+        // since a new basket may have been created
+        if (reopenBasket && customerId) {
+            invalidate.push({
+                queryKey: getCustomerBaskets.queryKey({...orderParams, customerId})
+            })
+        }
+        return {invalidate}
+    }
 }

packages/commerce-sdk-react/src/hooks/ShopperOrders/mutation.ts

@@ -46,7 +46,13 @@ The payment instrument is added with the provided details. The payment method mu
      * Updates a payment instrument of an order.
      * @returns A TanStack Query mutation hook for interacting with the Shopper Orders `updatePaymentInstrumentForOrder` endpoint.
      */
-    UpdatePaymentInstrumentForOrder: 'updatePaymentInstrumentForOrder'
+    UpdatePaymentInstrumentForOrder: 'updatePaymentInstrumentForOrder',
+    /**
+     * Fails an unplaced order and optionally reopens the basket when indicated.
+     * Creates a HistoryEntry in the failed Order with provided reasonCode.
+     * @returns A TanStack Query mutation hook for interacting with the Shopper Orders `failOrder` endpoint.
+     */
+    FailOrder: 'failOrder'
 } as const
 
 /**

packages/template-retail-react-app/app/components/sf-payments-express-buttons/index.jsx

@@ -13,6 +13,7 @@ import {
     EXPRESS_PAY_NOW,
     EXPRESS_BUY_NOW
 } from '@salesforce/retail-react-app/app/hooks/use-sf-payments'
+import {rest} from 'msw'
 
 // Mock getConfig to provide necessary configuration
 jest.mock('@salesforce/pwa-kit-runtime/utils/ssr-config', () => {
@@ -50,6 +51,60 @@ jest.mock('@salesforce/retail-react-app/app/hooks/use-sf-payments', () => {
     }
 })
 
+beforeEach(() => {
+    // Reset MSW handlers to avoid conflicts
+    global.server.resetHandlers()
+
+    // Add MSW handlers to mock API requests
+    global.server.use(
+        rest.get('*/api/configuration/shopper-configurations/*', (req, res, ctx) => {
+            return res(
+                ctx.delay(0),
+                ctx.status(200),
+                ctx.json({
+                    configurations: []
+                })
+            )
+        }),
+        rest.get(
+            '*/api/customer/shopper-customers/*/customers/*/product-lists',
+            (req, res, ctx) => {
+                return res(
+                    ctx.delay(0),
+                    ctx.status(200),
+                    ctx.json({
+                        data: [],
+                        total: 0
+                    })
+                )
+            }
+        ),
+        rest.get('*/api/payment-metadata', (req, res, ctx) => {
+            return res(
+                ctx.delay(0),
+                ctx.status(200),
+                ctx.json({
+                    apiKey: 'test-key',
+                    publishableKey: 'pk_test'
+                })
+            )
+        }),
+        rest.get('*/api/checkout/shopper-payments/*/payment-configuration', (req, res, ctx) => {
+            return res(
+                ctx.delay(0),
+                ctx.status(200),
+                ctx.json({
+                    paymentMethods: [
+                        {id: 'card', name: 'Card'},
+                        {id: 'paypal', name: 'PayPal'}
+                    ],
+                    paymentMethodSetAccounts: []
+                })
+            )
+        })
+    )
+})
+
 afterEach(() => {
     jest.clearAllMocks()
 })
@@ -175,3 +230,65 @@ describe('prepareBasket prop updates', () => {
         expect(screen.getByTestId('sf-payments-express')).toBeInTheDocument()
     })
 })
+
+describe('failOrder error handling', () => {
+    const mockFailOrder = jest.fn()
+    const mockCreateOrder = jest.fn()
+    const mockUpdatePaymentInstrument = jest.fn()
+    const mockToast = jest.fn()
+
+    beforeEach(() => {
+        jest.clearAllMocks()
+        mockFailOrder.mockResolvedValue({})
+    })
+
+    // Mock the mutations to verify they're available
+    jest.mock('@salesforce/commerce-sdk-react', () => {
+        const actual = jest.requireActual('@salesforce/commerce-sdk-react')
+        return {
+            ...actual,
+            useShopperOrdersMutation: (mutationKey) => {
+                if (mutationKey === 'failOrder') {
+                    return {mutateAsync: mockFailOrder}
+                }
+                if (mutationKey === 'createOrder') {
+                    return {mutateAsync: mockCreateOrder}
+                }
+                if (mutationKey === 'updatePaymentInstrumentForOrder') {
+                    return {mutateAsync: mockUpdatePaymentInstrument}
+                }
+                return {mutateAsync: jest.fn()}
+            },
+            usePaymentConfiguration: () => ({
+                data: {
+                    paymentMethods: [{id: 'card', name: 'Card'}],
+                    paymentMethodSetAccounts: []
+                }
+            }),
+            useShopperBasketsMutation: () => ({
+                mutateAsync: jest.fn()
+            }),
+            useShippingMethodsForShipment: () => ({
+                refetch: jest.fn()
+            })
+        }
+    })
+
+    jest.mock('@salesforce/retail-react-app/app/hooks/use-shopper-configuration', () => ({
+        useShopperConfiguration: () => 'default'
+    }))
+
+    jest.mock('@salesforce/retail-react-app/app/hooks/use-toast', () => ({
+        useToast: () => mockToast
+    }))
+
+    // It doesn't trigger the actual failOrder call (that requires the full payment flow), but it confirms the setup is correct.
+    // The actual failOrder call is better tested in integration/E2E tests.
+    test('failOrder mutation is available and error message constant is defined', () => {
+        renderWithProviders(<SFPaymentsExpressButtons {...defaultProps} />)
+
+        expect(screen.getByTestId('sf-payments-express')).toBeInTheDocument()
+        expect(mockFailOrder).toBeDefined()
+        expect(mockToast).toBeDefined()
+    })
+})

packages/template-retail-react-app/app/components/sf-payments-express-buttons/index.test.js

@@ -48,6 +48,8 @@ import {
     useSFPayments
 } from '@salesforce/retail-react-app/app/hooks/use-sf-payments'
 
+let persistedPaymentsError = null
+
 const Checkout = () => {
     const {formatMessage} = useIntl()
     const navigate = useNavigation()
@@ -95,6 +97,14 @@ const Checkout = () => {
         }
     }, [basket?.basketId])
 
+    // Restore error if component remounted after payments error causes a refresh
+    useEffect(() => {
+        if (persistedPaymentsError && !error) {
+            setError(persistedPaymentsError)
+            persistedPaymentsError = null // Clear it after restoring
+        }
+    }, [])
+
     // Callback to handle when payment method requires its own pay button
     const handleRequiresPayButtonChange = (requiresPayButton) => {
         setShouldHidePlaceOrderButton(requiresPayButton === false)
@@ -107,6 +117,7 @@ const Checkout = () => {
     }
 
     const handlePaymentError = (errorMessage) => {
+        persistedPaymentsError = errorMessage
         setError(errorMessage)
     }
 
@@ -121,11 +132,13 @@ const Checkout = () => {
             }
             navigate(`/checkout/confirmation/${order.orderNo}`)
         } catch (error) {
-            const message = formatMessage({
-                id: 'checkout.message.generic_error',
-                defaultMessage: 'An unexpected error occurred during checkout.'
-            })
-            setError(message)
+            if (!persistedPaymentsError) {
+                const message = formatMessage({
+                    id: 'checkout.message.generic_error',
+                    defaultMessage: 'An unexpected error occurred during checkout.'
+                })
+                setError(message)
+            }
         } finally {
             setIsLoading(false)
         }
@@ -151,7 +164,6 @@ const Checkout = () => {
                                     {error}
                                 </Alert>
                             )}
-
                             {sfPaymentsEnabled && (
                                 <Box
                                     layerStyle="card"