epicmerch-mcp 1.3.2 → 1.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "epicmerch-mcp",
-  "version": "1.3.2",
+  "version": "1.3.6",
   "description": "MCP server for EpicMerch — integrates e-commerce into Claude and ChatGPT",
   "type": "module",
   "main": "src/index.js",

package/skills/epicmerch-auth.md

@@ -22,9 +22,23 @@ export const store = new EpicMerch({
   apiKey: import.meta.env.VITE_API_KEY,
   ...(import.meta.env.VITE_API_URL && { baseUrl: import.meta.env.VITE_API_URL }),
 });
+
+// Restore the customer session on page load — CRITICAL for OTP login to
+// actually stick. Without this, the merchant logs in successfully, the
+// token gets saved to localStorage, but the SDK in memory stays
+// unauthenticated. The very next render shows them as logged-out again.
+if (typeof window !== 'undefined') {
+  try {
+    const saved = localStorage.getItem('customerInfo');
+    if (saved) {
+      const parsed = JSON.parse(saved);
+      if (parsed?.token) store.setCustomerToken(parsed.token);
+    }
+  } catch (_) { /* localStorage unavailable — silent fallback */ }
+}
 ```
 
-(For Next.js projects use `process.env.NEXT_PUBLIC_API_KEY` / `NEXT_PUBLIC_API_URL` instead.)
+(For Next.js projects use `process.env.NEXT_PUBLIC_API_KEY` / `NEXT_PUBLIC_API_URL` instead. The session-restore block stays the same — the `typeof window !== 'undefined'` guard prevents SSR crashes.)
 
 ## Step 3: Login component
 
@@ -47,6 +61,8 @@ export default function Login({ onLogin }) {
   const verify = async () => {
     const result = await store.auth.verifyOtp(phone, otp, {});
     if (result.token) {
+      // SDK already sets the token internally during verifyOtp; mirror to
+      // localStorage so src/lib/epicmerch.js can restore on next page load.
       store.setCustomerToken(result.token);
       localStorage.setItem('customerInfo', JSON.stringify(result));
       onLogin(result);
@@ -57,13 +73,31 @@ export default function Login({ onLogin }) {
     <div>
       {step === 'phone' ? (
         <>
-          <input value={phone} onChange={e => setPhone(e.target.value)} placeholder="+919876543210" />
+          <input
+            type="tel"
+            value={phone}
+            onChange={e => setPhone(e.target.value)}
+            placeholder="+919876543210"
+            autoComplete="tel"
+          />
           <button onClick={sendOtp}>Send OTP</button>
         </>
       ) : (
         <>
-          <input value={otp} onChange={e => setOtp(e.target.value)} placeholder="Enter OTP" />
-          <button onClick={verify}>Verify</button>
+          {/* EpicMerch OTPs are 4 digits. inputMode='numeric' pops the
+              numeric keypad on mobile; autoComplete='one-time-code' lets
+              iOS auto-fill from SMS without leaving the page. */}
+          <input
+            type="tel"
+            inputMode="numeric"
+            maxLength={4}
+            autoComplete="one-time-code"
+            value={otp}
+            onChange={e => setOtp(e.target.value.replace(/\D/g, '').slice(0, 4))}
+            placeholder="4-digit OTP"
+            autoFocus
+          />
+          <button onClick={verify} disabled={otp.length !== 4}>Verify</button>
         </>
       )}
     </div>

package/skills/epicmerch-debug.md

@@ -0,0 +1,217 @@
+---
+name: epicmerch-debug
+description: Diagnose and fix a broken EpicMerch storefront. Walks through the four most common failure modes — OTP login that "works" but doesn't stick across reloads, products not loading on the site, cart returns 401, INSUFFICIENT_STOCK on checkout — runs targeted checks, and routes to a specific fix.
+---
+
+# EpicMerch Debug
+
+You are debugging a storefront that isn't behaving. Don't ask the merchant
+to describe what's wrong in detail — most issues map to a known failure
+mode. Walk through the four checks below in order. The first one that
+hits is almost always the root cause.
+
+## Pre-flight: gather context
+
+Before checking anything, get the basics in one parallel batch:
+
+1. Read the project's `.env` (or `.env.local`) and grab `VITE_API_KEY` /
+   `NEXT_PUBLIC_API_KEY`. If neither exists, that's the first problem —
+   route to `/epicmerch` step 1 to generate one.
+2. Read `src/lib/epicmerch.js` (or wherever the SDK is initialised). Note
+   whether it has the `setCustomerToken` restoration block from
+   localStorage (see Check 1 below — if it's missing, that's the cause).
+3. Call `merchant_get_settings` to confirm the merchant's session is still
+   live and the API key actually belongs to this merchant.
+4. Call `merchant_get_checkout_settings` to confirm a payment processor
+   is configured.
+
+Print a 4-line summary, then dive into the relevant check.
+
+---
+
+## Check 1 — "I logged in but nothing happened" / "OTP works but doesn't persist"
+
+**Symptom.** Merchant enters phone, gets OTP, types OTP, the success
+state briefly flashes — then on next page render OR after a page reload,
+the storefront thinks they're logged out again. Cart returns 401. Order
+button is disabled. They re-login, same thing.
+
+**Cause.** The EpicMerch SDK holds the customer token in memory only.
+`store.auth.verifyOtp()` calls `store.setCustomerToken()` internally,
+which is why the first session works — but the token isn't restored from
+localStorage on subsequent SDK initialisations. Login.jsx writes
+`customerInfo` to localStorage; the SDK never reads it back.
+
+**Diagnosis.** Read `src/lib/epicmerch.js`. If you do NOT see a block
+like this somewhere after the `new EpicMerch(...)` call:
+
+```js
+if (typeof window !== 'undefined') {
+  try {
+    const saved = localStorage.getItem('customerInfo');
+    if (saved) {
+      const parsed = JSON.parse(saved);
+      if (parsed?.token) store.setCustomerToken(parsed.token);
+    }
+  } catch (_) {}
+}
+```
+
+…that's the bug. Confirm by asking the merchant to open DevTools →
+Application → Local Storage, expand their site origin, and check that
+`customerInfo` IS there (it should be — Login.jsx writes it). If the
+key exists but the SDK doesn't know about it, it's this exact bug.
+
+**Fix.** Patch `src/lib/epicmerch.js` to add the restoration block
+(verbatim from above, right after `export const store = ...`). Tell the
+merchant to refresh — they should still be logged in from their previous
+session.
+
+If they want to log out properly, the matching cleanup is:
+
+```js
+store.clearCustomerToken();
+localStorage.removeItem('customerInfo');
+```
+
+---
+
+## Check 2 — Products don't load on the site
+
+**Symptom.** Storefront renders, but the product grid is empty.
+DevTools → Network shows the call to `/api/products` either 401-ing,
+403-ing, or returning an empty array.
+
+**Cause.** One of three:
+- **401**: invalid or revoked API key — `VITE_API_KEY` in `.env` doesn't
+  match any active key on the server.
+- **403**: domain isn't in `merchant.allowedDomains` — the CORS / origin
+  check is rejecting the request.
+- **200 with empty `products` array**: API key is fine, but the
+  merchant's catalog is genuinely empty.
+
+**Diagnosis.**
+
+1. Open DevTools → Network, filter for `/products`, click the request.
+   Note the response status.
+2. Compare the `x-api-key` header value to the merchant's actual key:
+   `merchant_list_api_keys()` returns the canonical list. If it's masked,
+   generate a fresh one with `merchant_generate_api_key({ name: "Debug" })`
+   and use that value in `.env`.
+3. Note `window.location.origin`. Call `merchant_get_settings()` and
+   compare against `merchant.allowedDomains`. If the storefront's origin
+   isn't listed, that's the 403.
+4. Call `merchant_list_products({ limit: 1 })` to confirm the catalog
+   actually has products.
+
+**Fix.**
+- **Bad API key**: regenerate via `merchant_generate_api_key`, paste the
+  new value into `.env`, restart the dev server (`npm run dev`) so Vite
+  picks up the new env var.
+- **Domain not allowed**: `merchant_add_allowed_domain({ domain: '<origin>' })`,
+  then refresh.
+- **Empty catalog**: route to `/epicmerch` step 3 to add products.
+
+---
+
+## Check 3 — "INSUFFICIENT_STOCK: undefined: need 1, have 0" on checkout
+
+**Symptom.** Adding to cart works. Cart shows items. Place Order returns
+HTTP 400 with `{ code: 'INSUFFICIENT_STOCK', message: 'undefined: need 1, have 0' }`.
+
+**Cause.** Almost always one of these mismatches between what the
+storefront sends and what the server expects in `orderItems[]`:
+
+- The line item uses `productId` field but it resolves to `undefined`
+  (variant lookup fails because the size string in `orderItems[].variant`
+  doesn't match any row in `product_variants`).
+- The product genuinely has 0 stock for that variant.
+- An old scaffold (pre-1.3.3) sent `orderItems[].productId` as
+  `undefined` because it read `v.size` on a variant object where the
+  field is actually named `v.variant`.
+
+**Diagnosis.**
+
+1. Read `src/components/ProductCard.jsx`. Look for either:
+   - `availableSizes.map(v => v.size)` — old, broken (returns undefined)
+   - `availableVariants.map(v => v.variant)` — correct
+2. Read `src/components/Checkout.jsx`. Look at the `orderItems` map. The
+   product field should be `productId: i.product._id` (canonical) and
+   the variant field should be `variant: i.variant` (a string).
+3. From the merchant's perspective, open Cart, note the variant
+   labels visible. Open DevTools → Application → Local Storage →
+   `customerInfo`. Try `store.cart.get()` in the console and inspect
+   the result — every line item should have a `variant` string that
+   matches an entry in the product's `product_variants` table.
+
+**Fix.**
+- If ProductCard reads `v.size` → re-run `/epicmerch-storefront` to
+  refresh the scaffold from the 1.3.3+ contract.
+- If Checkout sends `product:` instead of `productId:` in orderItems
+  → same, re-scaffold.
+- If the variant truly isn't in the database → the product has stock=0
+  for that size, or the variant was never created. Have the merchant
+  call `merchant_get_product({ id })` and inspect `.variants`. If
+  needed, `merchant_update_product({ id, variants: [...] })` to fix.
+
+---
+
+## Check 4 — Add to cart returns 401 / 403
+
+**Symptom.** Customer is "logged in" (UI shows their phone/name), but
+clicking Add to Cart fails. Network shows 401 or 403 on POST `/customer/cart`.
+
+**Cause.** The Authorization header isn't being sent. Either:
+- Token was never restored on this page load (Check 1).
+- Token expired (30-minute lifetime by default; SDK can refresh, but the
+  merchant might have been idle).
+- Login.jsx didn't actually save the token (look for typo).
+
+**Diagnosis.**
+
+1. In the console: `localStorage.getItem('customerInfo')` — is it
+   present? Is the `token` field a non-empty string?
+2. In the console: `store.getCustomerToken?.()` (if exposed) or check
+   that subsequent API calls include the Authorization header.
+3. Call `store.auth.getSession()` — if it returns null, the token has
+   expired or wasn't restored. `store.auth.refreshToken()` can extend it.
+
+**Fix.**
+- If localStorage is empty: merchant needs to log in again.
+- If the token is there but the SDK doesn't have it: apply Check 1's
+  restoration block.
+- If `getSession()` returns null: `store.auth.refreshToken()` — if
+  that fails, log out (clear customerInfo) and log in again.
+
+---
+
+## Wrap-up
+
+After running through the four checks, print a one-line summary:
+
+```
+✓ Check 1 — Session restore     localStorage block present in src/lib/epicmerch.js
+✗ Check 2 — Products load        API key in .env didn't match any active key — regenerated
+- Check 3 — Order shape          skipped (cart works)
+- Check 4 — Cart auth            skipped (cart works)
+
+Fix applied: rewrote .env with the new API key. Restart `npm run dev`
+to pick up the change.
+```
+
+If everything checks out and the merchant still has an issue, ask them
+to paste the EXACT error message + the response body from DevTools →
+Network. That usually pins it. Don't speculate — get the literal error.
+
+## When to escalate
+
+If none of the 4 checks fit the symptom, fall through to
+`merchant_diagnose` for a server-side health snapshot, then route based
+on what it reports:
+
+- "Razorpay not configured" → `/epicmerch-razorpay`
+- "No products" → `/epicmerch` step 3 or `/epicmerch-migrate`
+- "No API key" → `/epicmerch` step 1
+- "Domain not allowed" → `merchant_add_allowed_domain`
+- Anything else → surface the diagnostic output to the merchant
+  verbatim and let them decide.

package/skills/epicmerch-orders.md

@@ -33,9 +33,12 @@ import { useEffect, useState } from 'react';
 import { store } from '../lib/epicmerch';
 
 export default function Cart({ onCheckout }) {
-  // store.cart.get() returns { cart, cartCount, cartTotal } — the cart line
-  // items are on `cart.cart`, NOT `cart.items`. Each line item is shaped
-  // { product: { _id, name, price, salePrice, images, ... }, qty, variant }.
+  // store.cart.get() returns { cart: [...] } — JUST one field. The SDK
+  // README mentions cartCount/cartTotal but those aren't actually sent by
+  // the server; compute them locally. Each line item is shaped
+  // { product: { _id, name, price, originalPrice, salePrice, image, type },
+  // qty, variant }. Note `product.price` on cart items is ALREADY the
+  // effective price (sale if on sale, else regular).
   const [cart, setCart] = useState({ cart: [] });
 
   useEffect(() => { store.cart.get().then(setCart); }, []);
@@ -105,20 +108,23 @@ export default function Checkout({ cart, onSuccess }) {
     await loadRazorpay();
 
     // Map cart line items to the orderItems shape the API expects.
-    // Critical fields per the SDK README:
-    //   - `product` (NOT `productId`) — the product _id
+    // Critical fields per the SDK contract:
+    //   - `productId` — the product _id (same field name as cart.add,
+    //                   magic-checkout-init, analytics.track; consistent
+    //                   across every endpoint). Server still accepts the
+    //                   legacy `product` field but `productId` is canonical.
     //   - `name`, `image` — required, the server doesn't re-fetch them
     //   - `variant` — the size STRING, must match what was added to cart
     //                  or the variant lookup returns undefined and you'll
     //                  see "INSUFFICIENT_STOCK: undefined: need 1, have 0"
     const items = cart.cart || [];
     const orderItems = items.map(i => ({
-      product: i.product._id,
-      name:    i.product.name,
-      image:   i.product.images?.[0] || i.product.image,
-      qty:     i.qty,
-      price:   i.product.salePrice ?? i.product.price,
-      variant: i.variant,
+      productId: i.product._id,
+      name:      i.product.name,
+      image:     i.product.images?.[0] || i.product.image,
+      qty:       i.qty,
+      price:     i.product.salePrice ?? i.product.price,
+      variant:   i.variant,
     }));
     const total = orderItems.reduce((s, i) => s + i.price * i.qty, 0);
 

package/skills/epicmerch-products.md

@@ -32,40 +32,42 @@ If `src/components/ProductCard.jsx` already exists, skip. Otherwise write:
 import { useState } from 'react';
 
 export default function ProductCard({ product, onAddToCart }) {
-  // Variants are stock-tracked per-size. Only show sizes that are in stock —
-  // the API will reject orders for out-of-stock variants with
-  // "INSUFFICIENT_STOCK: <size>: need N, have 0".
-  const availableSizes = (product.variants || []).filter(v => v.stock > 0);
-  const [size, setSize] = useState(availableSizes[0]?.size);
+  // ProductVariant rows are { variant: String, stock: Int } — note the field
+  // is named `variant`, NOT `size`. The "variant" string is whatever the
+  // merchant configured (typically a size like 'S'/'M'/'L', but could be
+  // a color or material). Only show in-stock options — out-of-stock orders
+  // are rejected with "INSUFFICIENT_STOCK: <variant>: need N, have 0".
+  const availableVariants = (product.variants || []).filter(v => v.stock > 0);
+  const [variant, setVariant] = useState(availableVariants[0]?.variant);
 
   // Products on sale return both `price` (original) and `salePrice` (current).
   // Always display the current price the customer will actually pay.
   const price = product.salePrice ?? product.price;
   const image = product.images?.[0] || product.image;
-  const needsSize = availableSizes.length > 0;
+  const hasVariants = availableVariants.length > 0;
 
   return (
     <div className="product-card">
       <img src={image} alt={product.name} />
       <h3>{product.name}</h3>
       <p>₹{price}</p>
-      {needsSize && (
-        <div className="size-picker">
-          {availableSizes.map(v => (
+      {hasVariants && (
+        <div className="variant-picker">
+          {availableVariants.map(v => (
             <button
-              key={v.size}
+              key={v.variant}
               type="button"
-              onClick={() => setSize(v.size)}
-              className={size === v.size ? 'selected' : ''}
+              onClick={() => setVariant(v.variant)}
+              className={variant === v.variant ? 'selected' : ''}
             >
-              {v.size}
+              {v.variant}
             </button>
           ))}
         </div>
       )}
       <button
-        onClick={() => onAddToCart(product._id, size)}
-        disabled={needsSize && !size}
+        onClick={() => onAddToCart(product._id, variant)}
+        disabled={hasVariants && !variant}
       >
         Add to Cart
       </button>

package/skills/epicmerch-storefront.md

@@ -54,6 +54,20 @@ export const store = new EpicMerch({
   apiKey: import.meta.env.VITE_API_KEY,
   ...(import.meta.env.VITE_API_URL && { baseUrl: import.meta.env.VITE_API_URL }),
 });
+
+// Restore the customer session on page load. Without this, OTP login
+// appears to "work" (token gets saved to localStorage) but the SDK
+// stays unauthenticated until something calls setCustomerToken — so
+// the merchant logs in, the page reloads, and they're logged out again.
+if (typeof window !== 'undefined') {
+  try {
+    const saved = localStorage.getItem('customerInfo');
+    if (saved) {
+      const parsed = JSON.parse(saved);
+      if (parsed?.token) store.setCustomerToken(parsed.token);
+    }
+  } catch (_) { /* localStorage unavailable — silent fallback */ }
+}
 ```
 
 - For `NEXT_PUBLIC_` prefix (Next.js):
@@ -64,6 +78,19 @@ export const store = new EpicMerch({
   apiKey: process.env.NEXT_PUBLIC_API_KEY,
   ...(process.env.NEXT_PUBLIC_API_URL && { baseUrl: process.env.NEXT_PUBLIC_API_URL }),
 });
+
+// Restore customer session on page load (same as Vite — without this,
+// OTP login looks like it works but doesn't survive a page reload).
+// Guard the localStorage call so server-rendered pages don't crash.
+if (typeof window !== 'undefined') {
+  try {
+    const saved = localStorage.getItem('customerInfo');
+    if (saved) {
+      const parsed = JSON.parse(saved);
+      if (parsed?.token) store.setCustomerToken(parsed.token);
+    }
+  } catch (_) { /* localStorage unavailable */ }
+}
 ```
 
 - [ ] **Step 4: Scaffold auth**
@@ -87,6 +114,8 @@ export default function Login({ onLogin }) {
   const verify = async () => {
     const result = await store.auth.verifyOtp(phone, otp, {});
     if (result.token) {
+      // SDK already sets the token internally during verifyOtp; mirror to
+      // localStorage so src/lib/epicmerch.js can restore on next page load.
       store.setCustomerToken(result.token);
       localStorage.setItem('customerInfo', JSON.stringify(result));
       onLogin(result);
@@ -97,13 +126,31 @@ export default function Login({ onLogin }) {
     <div>
       {step === 'phone' ? (
         <>
-          <input value={phone} onChange={e => setPhone(e.target.value)} placeholder="+919876543210" />
+          <input
+            type="tel"
+            value={phone}
+            onChange={e => setPhone(e.target.value)}
+            placeholder="+919876543210"
+            autoComplete="tel"
+          />
           <button onClick={sendOtp}>Send OTP</button>
         </>
       ) : (
         <>
-          <input value={otp} onChange={e => setOtp(e.target.value)} placeholder="Enter OTP" />
-          <button onClick={verify}>Verify</button>
+          {/* EpicMerch OTPs are 4 digits. inputMode='numeric' pops the
+              numeric keypad on mobile; autoComplete='one-time-code' lets
+              iOS auto-fill from SMS without leaving the page. */}
+          <input
+            type="tel"
+            inputMode="numeric"
+            maxLength={4}
+            autoComplete="one-time-code"
+            value={otp}
+            onChange={e => setOtp(e.target.value.replace(/\D/g, '').slice(0, 4))}
+            placeholder="4-digit OTP"
+            autoFocus
+          />
+          <button onClick={verify} disabled={otp.length !== 4}>Verify</button>
         </>
       )}
     </div>
@@ -121,40 +168,42 @@ Write `src/components/ProductCard.jsx`:
 import { useState } from 'react';
 
 export default function ProductCard({ product, onAddToCart }) {
-  // Variants are stock-tracked per-size. Only show sizes that are in stock —
-  // the API will reject orders for out-of-stock variants with
-  // "INSUFFICIENT_STOCK: <size>: need N, have 0".
-  const availableSizes = (product.variants || []).filter(v => v.stock > 0);
-  const [size, setSize] = useState(availableSizes[0]?.size);
+  // ProductVariant rows are { variant: String, stock: Int } — note the field
+  // is named `variant`, NOT `size`. The "variant" string is whatever the
+  // merchant configured (typically a size like 'S'/'M'/'L', but could be
+  // a color or material). Only show in-stock options — out-of-stock orders
+  // are rejected with "INSUFFICIENT_STOCK: <variant>: need N, have 0".
+  const availableVariants = (product.variants || []).filter(v => v.stock > 0);
+  const [variant, setVariant] = useState(availableVariants[0]?.variant);
 
   // Products on sale return both `price` (original) and `salePrice` (current).
   // Always display the current price the customer will actually pay.
   const price = product.salePrice ?? product.price;
   const image = product.images?.[0] || product.image;
-  const needsSize = availableSizes.length > 0;
+  const hasVariants = availableVariants.length > 0;
 
   return (
     <div className="product-card">
       <img src={image} alt={product.name} />
       <h3>{product.name}</h3>
       <p>₹{price}</p>
-      {needsSize && (
-        <div className="size-picker">
-          {availableSizes.map(v => (
+      {hasVariants && (
+        <div className="variant-picker">
+          {availableVariants.map(v => (
             <button
-              key={v.size}
+              key={v.variant}
               type="button"
-              onClick={() => setSize(v.size)}
-              className={size === v.size ? 'selected' : ''}
+              onClick={() => setVariant(v.variant)}
+              className={variant === v.variant ? 'selected' : ''}
             >
-              {v.size}
+              {v.variant}
             </button>
           ))}
         </div>
       )}
       <button
-        onClick={() => onAddToCart(product._id, size)}
-        disabled={needsSize && !size}
+        onClick={() => onAddToCart(product._id, variant)}
+        disabled={hasVariants && !variant}
       >
         Add to Cart
       </button>
@@ -252,9 +301,12 @@ import { useEffect, useState } from 'react';
 import { store } from '../lib/epicmerch';
 
 export default function Cart({ onCheckout }) {
-  // store.cart.get() returns { cart, cartCount, cartTotal } — the cart line
-  // items are on `cart.cart`, NOT `cart.items`. Each line item is shaped
-  // { product: { _id, name, price, salePrice, images, ... }, qty, variant }.
+  // store.cart.get() returns { cart: [...] } — JUST one field. The SDK
+  // README mentions cartCount/cartTotal but those aren't actually sent by
+  // the server; compute them locally. Each line item is shaped
+  // { product: { _id, name, price, originalPrice, salePrice, image, type },
+  // qty, variant }. Note `product.price` on cart items is ALREADY the
+  // effective price (sale if on sale, else regular).
   const [cart, setCart] = useState({ cart: [] });
 
   useEffect(() => { store.cart.get().then(setCart); }, []);
@@ -324,20 +376,23 @@ export default function Checkout({ cart, onSuccess }) {
     await loadRazorpay();
 
     // Map cart line items to the orderItems shape the API expects.
-    // Critical fields per the SDK README:
-    //   - `product` (NOT `productId`) — the product _id
+    // Critical fields per the SDK contract:
+    //   - `productId` — the product _id (same field name as cart.add,
+    //                   magic-checkout-init, analytics.track; consistent
+    //                   across every endpoint). Server still accepts the
+    //                   legacy `product` field but `productId` is canonical.
     //   - `name`, `image` — required, the server doesn't re-fetch them
     //   - `variant` — the size STRING, must match what was added to cart
     //                  or the variant lookup returns undefined and you'll
     //                  see "INSUFFICIENT_STOCK: undefined: need 1, have 0"
     const items = cart.cart || [];
     const orderItems = items.map(i => ({
-      product: i.product._id,
-      name:    i.product.name,
-      image:   i.product.images?.[0] || i.product.image,
-      qty:     i.qty,
-      price:   i.product.salePrice ?? i.product.price,
-      variant: i.variant,
+      productId: i.product._id,
+      name:      i.product.name,
+      image:     i.product.images?.[0] || i.product.image,
+      qty:       i.qty,
+      price:     i.product.salePrice ?? i.product.price,
+      variant:   i.variant,
     }));
     const total = orderItems.reduce((s, i) => s + i.price * i.qty, 0);
 
@@ -381,7 +436,7 @@ export default function Checkout({ cart, onSuccess }) {
 }
 ```
 
-**If the merchant has a top-level `App.jsx` (or similar) that maintains a `refreshCartCount` or `handleAddToCart`, also update it:** `cart.get()` returns `{ cart, cartCount, cartTotal }`, so `refreshCartCount` should read `c?.cart?.length` (or just `c?.cartCount`), NOT `c?.items?.length`; and `handleAddToCart` should accept a `variant` arg and forward it: `store.cart.add(productId, 1, variant)`.
+**If the merchant has a top-level `App.jsx` (or similar) that maintains a `refreshCartCount` or `handleAddToCart`, also update it:** `cart.get()` returns `{ cart: [...] }`, so `refreshCartCount` should read `c?.cart?.length` (NOT `c?.items?.length` and NOT `c?.cartCount` — that field doesn't come back from the server, despite what the SDK README says); and `handleAddToCart` should accept a `variant` arg and forward it: `store.cart.add(productId, 1, variant)`. Bonus: `store.cart.add` itself returns `{ message, cartCount }`, so you can update the badge from THAT response without a separate `cart.get()` round-trip.
 
 Do NOT add any Razorpay script tag to `index.html` — the script loads dynamically only when the user clicks Place Order.