feat(ui): add checkout helper-signal fallback and recovery actions (#332)

Author: Cataldir

apps/ui/app/checkout/page.tsx

@@ -246,6 +246,7 @@ export default function CheckoutPage() {
   const [isPreparingCheckout, setIsPreparingCheckout] = useState(false);
   const [isFinalizingPayment, setIsFinalizingPayment] = useState(false);
   const [isOrderPaymentConfirmed, setIsOrderPaymentConfirmed] = useState(false);
+  const [continueWithoutHelperSignals, setContinueWithoutHelperSignals] = useState(false);
 
   const hasCompletedCheckoutRef = useRef(false);
   const reservationIdsRef = useRef<string[]>([]);
@@ -322,6 +323,13 @@ export default function CheckoutPage() {
   const hasReservationQueries = reservationOutcomeQueries.length > 0;
   const areReservationSignalsLoading = reservationOutcomeQueries.some((query) => query.isLoading);
   const areReservationSignalsFetching = reservationOutcomeQueries.some((query) => query.isFetching);
+  const hasHelperSignalsError = isInventoryHealthError || Boolean(reservationSignalsError);
+
+  useEffect(() => {
+    if (!hasHelperSignalsError) {
+      setContinueWithoutHelperSignals(false);
+    }
+  }, [hasHelperSignalsError]);
 
   const retryInventoryHealth = () => {
     void refetchInventoryHealth();
@@ -331,6 +339,18 @@ export default function CheckoutPage() {
     void Promise.allSettled(reservationOutcomeQueries.map((query) => query.refetch()));
   };
 
+  const retryHelperSignals = () => {
+    if (isInventoryHealthError) {
+      retryInventoryHealth();
+    }
+
+    if (reservationSignalsError) {
+      retryReservationOutcomes();
+    }
+
+    setContinueWithoutHelperSignals(false);
+  };
+
   const updateShippingField = (field: ShippingFieldKey, value: string) => {
     setShippingData((previous) => ({ ...previous, [field]: value }));
     setShippingFieldErrors((previous) => {
@@ -988,13 +1008,46 @@ export default function CheckoutPage() {
                 </p>
               ) : null}
 
+              {hasHelperSignalsError ? (
+                <div className="space-y-2" role="alert" aria-live="assertive">
+                  <p className="text-sm text-red-600 dark:text-red-400">
+                    Live inventory assistant signals are temporarily unavailable.
+                  </p>
+                  <div className="flex flex-wrap gap-2">
+                    <Button
+                      type="button"
+                      variant="outline"
+                      size="sm"
+                      onClick={retryHelperSignals}
+                      disabled={isInventoryHealthFetching || areReservationSignalsFetching}
+                    >
+                      Retry signal checks
+                    </Button>
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="sm"
+                      onClick={() => setContinueWithoutHelperSignals(true)}
+                    >
+                      Continue without live signals
+                    </Button>
+                  </div>
+                </div>
+              ) : null}
+
+              {continueWithoutHelperSignals ? (
+                <p className="text-sm text-gray-700 dark:text-gray-300" role="status" aria-live="polite">
+                  Continuing without live assistant signals. Checkout remains available.
+                </p>
+              ) : null}
+
               {isInventoryHealthLoading ? (
                 <p className="text-sm text-gray-600 dark:text-gray-400" role="status" aria-live="polite">
                   Checking inventory health signals…
                 </p>
               ) : null}
 
-              {isInventoryHealthError ? (
+              {isInventoryHealthError && !continueWithoutHelperSignals ? (
                 <div className="space-y-2" role="alert" aria-live="assertive">
                   <p className="text-sm text-red-600 dark:text-red-400">
                     Inventory health signals are temporarily unavailable. Retry to refresh current stock risk.
@@ -1013,7 +1066,7 @@ export default function CheckoutPage() {
                 </div>
               ) : null}
 
-              {reservationSignalsError ? (
+              {reservationSignalsError && !continueWithoutHelperSignals ? (
                 <div className="space-y-2" role="alert" aria-live="assertive">
                   <p className="text-sm text-red-600 dark:text-red-400">
                     Reservation outcomes are temporarily unavailable. Retry to confirm hold status before payment.

apps/ui/tests/unit/checkoutFlow.test.tsx

@@ -5,6 +5,8 @@ import checkoutService from '../../lib/services/checkoutService';
 import inventoryService from '../../lib/services/inventoryService';
 
 const push = jest.fn();
+const mockUseInventoryHealth = jest.fn();
+const mockUseReservationOutcomeQueries = jest.fn();
 
 jest.mock('next/navigation', () => ({
   useRouter: () => ({ push }),
@@ -29,18 +31,8 @@ jest.mock('../../lib/hooks/useCart', () => ({
 }));
 
 jest.mock('../../lib/hooks/useInventory', () => ({
-  useInventoryHealth: () => ({
-    data: {
-      total_skus: 1,
-      healthy: 1,
-      low_stock: 0,
-      out_of_stock: 0,
-      items: [],
-    },
-    isLoading: false,
-    isError: false,
-  }),
-  useReservationOutcomeQueries: () => [],
+  useInventoryHealth: (...args: unknown[]) => mockUseInventoryHealth(...args),
+  useReservationOutcomeQueries: (...args: unknown[]) => mockUseReservationOutcomeQueries(...args),
 }));
 
 jest.mock('../../lib/services/checkoutService', () => ({
@@ -77,6 +69,21 @@ function fillShippingForm(container: HTMLElement) {
 describe('CheckoutPage flow', () => {
   beforeEach(() => {
     jest.clearAllMocks();
+    mockUseInventoryHealth.mockReturnValue({
+      data: {
+        total_skus: 1,
+        healthy: 1,
+        low_stock: 0,
+        out_of_stock: 0,
+        items: [],
+      },
+      isLoading: false,
+      isError: false,
+      isFetching: false,
+      refetch: jest.fn(),
+    });
+    mockUseReservationOutcomeQueries.mockReturnValue([]);
+
     (inventoryService.createReservation as jest.Mock).mockResolvedValue({
       id: 'res-1',
       sku: 'sku-1',
@@ -253,6 +260,46 @@ describe('CheckoutPage flow', () => {
     });
   });
 
+  it('supports continue-without-helper-signals and retry recovery actions when helper data fails', () => {
+    const refetchInventoryHealth = jest.fn();
+    const refetchReservationOutcome = jest.fn();
+
+    mockUseInventoryHealth.mockReturnValue({
+      data: undefined,
+      isLoading: false,
+      isError: true,
+      isFetching: false,
+      refetch: refetchInventoryHealth,
+    });
+
+    mockUseReservationOutcomeQueries.mockReturnValue([
+      {
+        data: undefined,
+        isError: true,
+        error: new Error('reservation signal failure'),
+        isLoading: false,
+        isFetching: false,
+        refetch: refetchReservationOutcome,
+      },
+    ]);
+
+    render(<CheckoutPage />);
+
+    expect(screen.getByText('Live inventory assistant signals are temporarily unavailable.')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Continue to Payment' })).toBeEnabled();
+
+    fireEvent.click(screen.getByRole('button', { name: 'Continue without live signals' }));
+
+    expect(screen.getByText('Continuing without live assistant signals. Checkout remains available.')).toBeInTheDocument();
+    expect(screen.queryByText('Inventory health signals are temporarily unavailable. Retry to refresh current stock risk.')).not.toBeInTheDocument();
+    expect(screen.queryByText('Reservation outcomes are temporarily unavailable. Retry to confirm hold status before payment.')).not.toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole('button', { name: 'Retry signal checks' }));
+
+    expect(refetchInventoryHealth).toHaveBeenCalledTimes(1);
+    expect(refetchReservationOutcome).toHaveBeenCalledTimes(1);
+  });
+
   it('shows explicit required and optional semantics with phone rationale text', () => {
     render(<CheckoutPage />);