# COMPATIBILITY.md

## Overview

This project provides a lightweight **Upsell UI** for BigCommerce. It runs in the storefront and shows handpicked product suggestions immediately after an item is added to the cart.

The implementation relies on:

* **BigCommerce Cart API** (`/remote/v1/cart/add`)
* **Proxy API** (for product details, images, and adding upsell items in bulk)
* **upsell-rules.json** configuration file
* **Custom events** (`cart-add`) to trigger the modal safely

---

## Dependencies

* Works with **BigCommerce Stencil themes**.
* Requires a **proxy API service** (Node.js package included in this repo) to handle product detail requests and bulk cart updates.
* Uses **localStorage** for lightweight caching of rules (5-minute expiry).

---

## upsell-rules.json

The `upsell-rules.json` file defines which upsell products are linked to a main SKU.
Example:

```json
{
  "ABS": [
    { "id": 111, "name": "Mattress Protector", "price": 49.99 },
    { "id": 112, "name": "Memory Foam Pillow", "price": 79.99 }
  ]
}
```

* Key (`"ABS"`) = main product SKU
* Value = array of upsell product objects (id, name, price)

When a product with SKU `"ABS"` is added to cart, the upsell modal will show these products.

---

## Data Flow

1. **Cart Add**

   * When a product is added to the cart, the app captures the event (`cart-add`).
   * The modal is triggered with upsell suggestions from `upsell-rules.json`.

2. **Fetching Product Data**

   * Product details and images are fetched from the **Proxy API**.
   * Results are cached in memory (`productCache`) for performance.

3. **Fetching Rules**

   * `upsell-rules.json` is loaded from the proxy endpoint (`/upsell-rules`).
   * Cached in `localStorage` with a **5-minute expiry**.

4. **Upsell Modal**

   * Suggests products defined in `upsell-rules.json`.
   * User can select multiple items.
   * On confirm, all selected products are added to the existing cart **in one request** via `/add-items-to-cart`.

5. **Analytics**

   * Pushes events into `window.dataLayer` for impression, add-to-cart, and dismiss actions.

---

## Accessibility

* Modal uses proper ARIA roles (`role="dialog"`).
* Focus is trapped inside the modal until closed.
* Keyboard support: `Tab`, `Shift+Tab`, `Escape`.

---

## Compatibility Notes

* Works with **all BigCommerce themes** that rely on `cart-add` events.
* Does not require overriding `window.fetch` if custom event dispatching is used.
* Node.js package is included for API proxying (fetching product details, images, and serving `upsell-rules.json`).

---

✅ With this setup:

* Rules are configurable via `upsell-rules.json`.
* Proxy API ensures compatibility with BigCommerce APIs.
* No conflicts with third-party scripts when using custom events.