@active-reach/web-sdk 1.0.0 → 1.1.0

package/README.md

@@ -247,6 +247,109 @@ await aegis.flush();
 
 ---
 
+## E-Commerce Tracking
+
+Built-in helpers for standardized e-commerce events via `aegis.ecommerce`:
+
+```typescript
+import aegis from '@active-reach/web-sdk';
+
+// Product discovery
+aegis.ecommerce.productViewed({
+  product_id: 'SKU-123',
+  name: 'Leather Jacket',
+  price: 4999,
+  currency: 'INR',
+  category: 'Outerwear',
+  brand: 'Acme',
+  variant_id: 'black_xl',
+  variant_label: 'Black XL',
+});
+
+aegis.ecommerce.productListViewed({
+  list_name: 'New Arrivals',
+  category: 'Outerwear',
+  products: [{ product_id: 'SKU-123', name: 'Leather Jacket', price: 4999 }],
+});
+
+aegis.ecommerce.searchPerformed({ query: 'leather jacket', results_count: 12 });
+
+// Cart
+aegis.ecommerce.addToCart({
+  product_id: 'SKU-123',
+  name: 'Leather Jacket',
+  price: 4999,
+  quantity: 1,
+});
+
+aegis.ecommerce.removeFromCart({ product_id: 'SKU-123', name: 'Leather Jacket', price: 4999 });
+
+aegis.ecommerce.cartViewed({
+  cart_id: 'cart_456',
+  value: 4999,
+  products: [{ product_id: 'SKU-123', name: 'Leather Jacket', price: 4999, quantity: 1 }],
+});
+
+// Checkout
+aegis.ecommerce.checkoutStarted({
+  value: 4999,
+  products: [{ product_id: 'SKU-123', name: 'Leather Jacket', price: 4999, quantity: 1 }],
+  coupon: 'WELCOME10',
+  shipping: 99,
+  tax: 450,
+});
+
+aegis.ecommerce.checkoutStep(2, { payment_method: 'UPI' });
+
+// Order
+aegis.ecommerce.orderCompleted({
+  order_id: 'ORD-789',
+  value: 5548,
+  revenue: 4999,
+  shipping: 99,
+  tax: 450,
+  payment_method: 'UPI',
+  products: [{ product_id: 'SKU-123', name: 'Leather Jacket', price: 4999, quantity: 1 }],
+});
+
+aegis.ecommerce.orderRefunded('ORD-789', 4999);
+
+// Coupons
+aegis.ecommerce.couponApplied({ coupon_code: 'WELCOME10', discount_value: 500, discount_type: 'fixed' });
+aegis.ecommerce.couponRemoved({ coupon_code: 'WELCOME10' });
+
+// Wishlist
+aegis.ecommerce.wishlistItemAdded({
+  product: { product_id: 'SKU-123', name: 'Leather Jacket', price: 4999 },
+});
+
+// Promotions
+aegis.ecommerce.promotionViewed({ name: 'Summer Sale', promotion_id: 'promo_1', creative: 'banner_hero' });
+aegis.ecommerce.promotionClicked({ name: 'Summer Sale', promotion_id: 'promo_1' });
+```
+
+### All E-Commerce Methods
+
+| Method | Event Name | Description |
+|--------|-----------|-------------|
+| `productViewed(product)` | `product_viewed` | User views a product page |
+| `productListViewed(list)` | `product_list_viewed` | User views a category/collection |
+| `searchPerformed(search)` | `search_performed` | User searches the catalog |
+| `addToCart(product)` | `cart_item_added` | Item added to cart |
+| `removeFromCart(product)` | `cart_item_removed` | Item removed from cart |
+| `cartViewed(cart)` | `cart_viewed` | User views their cart |
+| `checkoutStarted(checkout)` | `checkout_started` | Checkout flow begins |
+| `checkoutStep(step, options?)` | `checkout_step` | Checkout step completed |
+| `orderCompleted(order)` | `order_completed` | Purchase completed |
+| `orderRefunded(orderId, value?, products?)` | `order_refunded` | Order refunded |
+| `couponApplied(coupon)` | `coupon_applied` | Coupon/discount applied |
+| `couponRemoved(coupon)` | `coupon_removed` | Coupon removed |
+| `wishlistItemAdded(wishlist)` | `wishlist_item_added` | Item added to wishlist |
+| `promotionViewed(promo)` | `promotion_viewed` | Promotion impression |
+| `promotionClicked(promo)` | `promotion_clicked` | Promotion clicked |
+
+---
+
 ## React Hooks
 
 Import from `@active-reach/web-sdk/react`: