(SP: 1) [Shop] Harden cart rehydrate: typed API error parsing + safe self-heal on PRICE_CONFIG_ERROR (no crash, no console)

Author: liudmylasovetovs

frontend/app/api/shop/cart/rehydrate/route.ts

@@ -29,26 +29,34 @@ function normalizeCartPayload(body: unknown) {
   };
 }
 
+function jsonError(
+  status: number,
+  code: string,
+  message: string,
+  details?: unknown
+) {
+  return NextResponse.json(
+    { error: { code, message, ...(details ? { details } : {}) } },
+    { status }
+  );
+}
+
 export async function POST(request: NextRequest) {
   let body: unknown;
 
   try {
     body = await request.json();
   } catch {
-    return NextResponse.json(
-      { error: 'Unable to process cart data.' },
-      { status: 400 }
-    );
+    return jsonError(400, 'INVALID_PAYLOAD', 'Unable to process cart data.');
   }
 
   const normalizedBody = normalizeCartPayload(body);
   const parsedPayload = cartRehydratePayloadSchema.safeParse(normalizedBody);
 
   if (!parsedPayload.success) {
-    return NextResponse.json(
-      { error: 'Invalid cart payload', details: parsedPayload.error.format() },
-      { status: 400 }
-    );
+    return jsonError(400, 'INVALID_PAYLOAD', 'Invalid cart payload', {
+      issues: parsedPayload.error.format(),
+    });
   }
 
   const { currency } = resolveLocaleAndCurrency(request);
@@ -60,41 +68,33 @@ export async function POST(request: NextRequest) {
   } catch (error) {
     logError('cart_rehydrate_failed', error);
 
+    // Missing price for locale currency is a CONTRACT error, not a 422.
     if (error instanceof PriceConfigError) {
-      return NextResponse.json(
-        {
-          code: error.code,
-          message: error.message,
-          details: { productId: error.productId, currency: error.currency },
-        },
-        { status: 422 }
-      );
+      return jsonError(400, error.code, error.message, {
+        productId: error.productId,
+        currency: error.currency,
+      });
     }
+
+    // DB misconfiguration / invalid stored money: treat as 500 (server fault),
+    // but keep stable code for diagnostics.
     if (error instanceof MoneyValueError) {
-      return NextResponse.json(
+      return jsonError(
+        500,
+        'PRICE_CONFIG_ERROR',
+        'Invalid price configuration for one or more products.',
         {
-          code: 'PRICE_CONFIG_ERROR',
-          message: 'Invalid price configuration for one or more products.',
-          details: {
-            productId: error.productId,
-            field: error.field,
-            rawValue: error.rawValue,
-          },
-        },
-        { status: 500 }
+          productId: error.productId,
+          field: error.field,
+          rawValue: error.rawValue,
+        }
       );
     }
 
     if (error instanceof InvalidPayloadError) {
-      return NextResponse.json(
-        { code: error.code, message: error.message },
-        { status: 400 }
-      );
+      return jsonError(400, error.code, error.message);
     }
 
-    return NextResponse.json(
-      { error: 'Unable to rehydrate cart.' },
-      { status: 500 }
-    );
+    return jsonError(500, 'INTERNAL_ERROR', 'Unable to rehydrate cart.');
   }
 }

frontend/components/shop/cart-provider.tsx

@@ -13,6 +13,7 @@ import {
 import {
   type Cart,
   type CartClientItem,
+  type CartRehydrateError,
   createCartItemKey,
   capQuantityByStock,
   getStoredCartItems,
@@ -22,6 +23,7 @@ import {
   emptyCart,
 } from '@/lib/cart';
 import type { ShopProduct } from '@/lib/shop/data';
+import { logWarn } from '@/lib/logging';
 
 interface CartContextType {
   cart: Cart;
@@ -53,16 +55,89 @@ const CartContext = createContext<CartContextType>({
   clearCart: () => {},
 });
 
+function getErrorInfo(error: unknown): {
+  code: string;
+  message: string;
+  details?: unknown;
+} {
+  const e = error as Partial<CartRehydrateError> & {
+    code?: unknown;
+    details?: unknown;
+    message?: unknown;
+  };
+
+  return {
+    code: typeof e?.code === 'string' ? e.code : 'UNKNOWN_ERROR',
+    message: typeof e?.message === 'string' ? e.message : 'Cart rehydrate failed',
+    details: e?.details,
+  };
+}
+
 export function CartProvider({ children }: { children: React.ReactNode }) {
   const [cart, setCart] = useState<Cart>(emptyCart);
 
   const syncCartWithServer = useCallback(async (items: CartClientItem[]) => {
     persistCartItems(items);
+
     try {
       const nextCart = await rehydrateCart(items);
       setCart(nextCart);
+      return;
     } catch (error) {
-      console.error('Failed to rehydrate cart', error);
+      const info = getErrorInfo(error);
+
+      // Self-heal: missing price for locale currency (e.g., uk => UAH) should not crash UI.
+      if (info.code === 'PRICE_CONFIG_ERROR') {
+        const productId =
+          typeof (info.details as any)?.productId === 'string'
+            ? String((info.details as any).productId)
+            : '';
+
+        // Best-effort: remove only the problematic product (if identified), retry once.
+        if (productId) {
+          const filtered = items.filter(i => i.productId !== productId);
+
+          if (filtered.length !== items.length) {
+            persistCartItems(filtered);
+
+            try {
+              const retriedCart = await rehydrateCart(filtered);
+              setCart(retriedCart);
+
+              logWarn('cart_rehydrate_recovered_by_removing_item', {
+                code: info.code,
+                removedProductId: productId,
+              });
+
+              return;
+            } catch (retryError) {
+              const retryInfo = getErrorInfo(retryError);
+              logWarn('cart_rehydrate_retry_failed', {
+                code: retryInfo.code,
+                message: retryInfo.message,
+              });
+            }
+          }
+        }
+
+        // Fallback: clear cart to unblock the user.
+        clearStoredCart();
+        setCart(emptyCart);
+
+        logWarn('cart_cleared_due_to_rehydrate_error', {
+          code: info.code,
+          message: info.message,
+          details: info.details,
+        });
+
+        return;
+      }
+
+      // Non-blocking: keep current cart state (avoid crashing the page).
+      logWarn('cart_rehydrate_failed_client', {
+        code: info.code,
+        message: info.message,
+      });
     }
   }, []);
 

frontend/lib/cart.ts

@@ -106,9 +106,7 @@ export function persistCartItems(items: CartClientItem[]): void {
   }
 }
 
-function normalizeItemsForStorage(
-  items: CartRehydrateItem[]
-): CartClientItem[] {
+function normalizeItemsForStorage(items: CartRehydrateItem[]): CartClientItem[] {
   return items.map(item => ({
     productId: item.productId,
     quantity: item.quantity,
@@ -121,9 +119,7 @@ function normalizeItemsForStorage(
  * IMPORTANT:
  * Cart money fields are MINOR UNITS (integers).
  */
-export function computeSummaryFromItems(
-  items: CartRehydrateItem[]
-): CartSummary {
+export function computeSummaryFromItems(items: CartRehydrateItem[]): CartSummary {
   if (!items.length) {
     return {
       totalAmountMinor: 0,
@@ -158,6 +154,79 @@ export function computeSummaryFromItems(
   };
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function extractApiError(data: unknown): {
+  code: string;
+  message: string;
+  details?: unknown;
+} {
+  // legacy: { error: "..." }
+  if (isRecord(data) && typeof data.error === 'string') {
+    return { code: 'UNKNOWN_ERROR', message: data.error };
+  }
+
+  // preferred: { error: { code, message, details } }
+  if (isRecord(data) && isRecord(data.error)) {
+    const errObj = data.error;
+    const code =
+      typeof errObj.code === 'string' && errObj.code.trim().length > 0
+        ? errObj.code
+        : 'UNKNOWN_ERROR';
+    const message =
+      typeof errObj.message === 'string' && errObj.message.trim().length > 0
+        ? errObj.message
+        : 'Request failed';
+    return { code, message, details: errObj.details };
+  }
+
+  // fallback: { code, message, details }
+  if (isRecord(data)) {
+    const code =
+      typeof data.code === 'string' && data.code.trim().length > 0
+        ? data.code
+        : 'UNKNOWN_ERROR';
+    const message =
+      typeof data.message === 'string' && data.message.trim().length > 0
+        ? data.message
+        : 'Request failed';
+    if (typeof data.code === 'string' || typeof data.message === 'string') {
+      return { code, message, details: data.details };
+    }
+  }
+
+  return { code: 'UNKNOWN_ERROR', message: 'Unable to rehydrate cart' };
+}
+
+export class CartRehydrateError extends Error {
+  public readonly code: string;
+  public readonly status: number;
+  public readonly details?: unknown;
+
+  constructor(args: {
+    code: string;
+    message: string;
+    status: number;
+    details?: unknown;
+  }) {
+    super(args.message);
+    this.name = 'CartRehydrateError';
+    this.code = args.code;
+    this.status = args.status;
+    this.details = args.details;
+  }
+}
+
+async function readJsonSafe(response: Response): Promise<unknown> {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
 export async function rehydrateCart(items: CartClientItem[]): Promise<Cart> {
   if (!items.length) {
     persistCartItems([]);
@@ -170,10 +239,16 @@ export async function rehydrateCart(items: CartClientItem[]): Promise<Cart> {
     body: JSON.stringify({ items }),
   });
 
-  const data = await response.json();
+  const data = await readJsonSafe(response);
 
   if (!response.ok) {
-    throw new Error(data?.error ?? 'Unable to rehydrate cart');
+    const apiErr = extractApiError(data);
+    throw new CartRehydrateError({
+      code: apiErr.code,
+      message: apiErr.message || `Unable to rehydrate cart (HTTP ${response.status})`,
+      status: response.status,
+      details: apiErr.details,
+    });
   }
 
   const parsed = cartRehydrateResultSchema.parse(data);