@active-reach/web-sdk 1.27.3 → 1.28.0

package/README.md

@@ -477,27 +477,38 @@ Drop an empty element wherever you want the card to appear. Its `data-aegis-slot
 
 No per-slot script and no manual registration — `runtime.initialize()` scans for every `[data-aegis-slot]` element and fills it. It re-scans on each SSE/poll refresh and skips slots it has already filled.
 
-### Cart recovery (platform auto-detection)
+### Cart state — one store, fed the CEP-standard way
 
-For cart-abandonment campaigns the widget subsystem auto-detects cart data:
+Every cart-reactive surface — the **free-delivery progress card**, the standalone
+**progress bar**, cart-value **targeting rules**, and **cart-recovery** widgets —
+reads ONE cart store. You feed it the same way you'd feed WebEngage/CleverTap: by
+firing the **ecommerce events** you already fire. The SDK derives the live cart
+from them; no separate cart call.
+
+```typescript
+// 1) Wire the ecommerce tracker into the cart store, once at boot:
+runtime.bindEcommerce(aegis.ecommerce);
+
+// 2) Fire ecommerce events as the shopper shops — the cart is derived from these:
+aegis.ecommerce.addToCart({ product_id: 'p1', name: 'Cap', price: 499, quantity: 1 });
+aegis.ecommerce.cartViewed({ value: 998, currency: 'INR', products: [/* … */] }); // authoritative snapshot
+```
+
+**Platform installs need no event wiring** — the plugin does it for you. Carts are
+detected and fed into the same store automatically:
 
 | Platform | Detection method | Setup |
 |----------|-----------------|-------|
-| **Shopify** | `window.Shopify.checkout` / DOM `#cart-json` | None |
-| **WooCommerce** | `window.aegis_cart` (injected by plugin) | Install WP plugin |
-| **Magento 2** | `localStorage['mage-cache-storage']` | None |
-| **Custom / Mobile** | Manual | Call `setCartData()` |
+| **Shopify** | `/cart.js` poll + `cart:updated` (plugin) | Install the Shopify app |
+| **WooCommerce** | `aegis_cart` + WC Store API on cart events (plugin) | Install the WP plugin |
+| **Magento 2** | `localStorage['mage-cache-storage']` | Install the extension |
+| **Custom / headless / mobile** | Fire `aegis.ecommerce.*` (above) | `runtime.bindEcommerce(...)` |
+
+**Escape hatch** — a headless host that doesn't emit ecommerce events can push the
+cart directly; this writes the same one store:
 
 ```typescript
-// Custom platforms only — reach the widget subsystem via runtime.widgets
-runtime.widgets.setCartData({
-  cart_id: 'cart_123',
-  cart_total: 149.99,
-  cart_currency: 'INR',
-  cart_items: [
-    { product_id: 'prod_456', product_name: 'Premium Widget', quantity: 2, price: 74.99 }
-  ],
-});
+runtime.setCartState({ total: 149.99, itemCount: 2, currency: 'INR' });
 ```
 
 ---