epicmerch-mcp 1.3.0 → 1.3.2

package/package.json

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

package/skills/epicmerch-orders.md

@@ -33,27 +33,46 @@ import { useEffect, useState } from 'react';
 import { store } from '../lib/epicmerch';
 
 export default function Cart({ onCheckout }) {
-  const [cart, setCart] = useState({ items: [] });
+  // 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 }.
+  const [cart, setCart] = useState({ cart: [] });
 
   useEffect(() => { store.cart.get().then(setCart); }, []);
 
-  const remove = async (productId) => {
-    await store.cart.remove(productId);
-    // Optimistic local update — no need to re-fetch the whole cart.
-    setCart(c => ({ ...c, items: (c.items || []).filter(i => i.productId !== productId) }));
+  const remove = async (productId, variant) => {
+    await store.cart.remove(productId, variant);
+    // Optimistic local update — match on BOTH productId AND variant so we
+    // don't accidentally remove a different size of the same product.
+    setCart(c => ({
+      ...c,
+      cart: (c.cart || []).filter(
+        i => !(i.product._id === productId && i.variant === variant),
+      ),
+    }));
   };
 
-  const total = cart.items?.reduce((s, i) => s + i.price * i.qty, 0) ?? 0;
+  const items = cart.cart || [];
+  const total = items.reduce((sum, i) => {
+    const price = i.product.salePrice ?? i.product.price;
+    return sum + price * i.qty;
+  }, 0);
 
   return (
     <div>
-      {cart.items?.map(item => (
-        <div key={item.productId}>
-          <span>{item.name} x{item.qty}</span>
-          <span>₹{item.price * item.qty}</span>
-          <button onClick={() => remove(item.productId)}>Remove</button>
-        </div>
-      ))}
+      {items.map((item, idx) => {
+        const price = item.product.salePrice ?? item.product.price;
+        return (
+          <div key={`${item.product._id}-${item.variant || 'novariant'}-${idx}`}>
+            <span>
+              {item.product.name} x{item.qty}
+              {item.variant ? ` (${item.variant})` : ''}
+            </span>
+            <span>₹{price * item.qty}</span>
+            <button onClick={() => remove(item.product._id, item.variant)}>Remove</button>
+          </div>
+        );
+      })}
       <p>Total: ₹{total}</p>
       <button onClick={onCheckout}>Checkout</button>
     </div>
@@ -84,15 +103,33 @@ export default function Checkout({ cart, onSuccess }) {
 
   const placeOrder = async () => {
     await loadRazorpay();
-    const total = cart.items.reduce((s, i) => s + i.price * i.qty, 0);
+
+    // Map cart line items to the orderItems shape the API expects.
+    // Critical fields per the SDK README:
+    //   - `product` (NOT `productId`) — the product _id
+    //   - `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,
+    }));
+    const total = orderItems.reduce((s, i) => s + i.price * i.qty, 0);
 
     // ONE call to /customer/orders is enough — the server creates the
     // EpicMerch order AND the Razorpay order in a single transaction and
     // returns both back. Do NOT separately call store.payment.createOrder
-    // here; doing so creates an orphan second Razorpay order AND can
-    // trigger an idempotency-key collision against /customer/orders.
+    // or store.payment.getConfig here; doing so creates an orphan second
+    // Razorpay order AND can trigger an idempotency-key collision against
+    // /customer/orders.
     const orderResult = await store.orders.create({
-      orderItems: cart.items.map(i => ({ productId: i.productId, qty: i.qty, price: i.price })),
+      orderItems,
       shippingAddress: address,
       paymentMethod: 'Razorpay',
       totalPrice: total,

package/skills/epicmerch-products.md

@@ -29,13 +29,46 @@ export const store = new EpicMerch({
 If `src/components/ProductCard.jsx` already exists, skip. Otherwise write:
 
 ```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);
+
+  // 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;
+
   return (
     <div className="product-card">
-      <img src={product.images?.[0]} alt={product.name} />
+      <img src={image} alt={product.name} />
       <h3>{product.name}</h3>
-      <p>₹{product.price}</p>
-      <button onClick={() => onAddToCart(product._id)}>Add to Cart</button>
+      <p>₹{price}</p>
+      {needsSize && (
+        <div className="size-picker">
+          {availableSizes.map(v => (
+            <button
+              key={v.size}
+              type="button"
+              onClick={() => setSize(v.size)}
+              className={size === v.size ? 'selected' : ''}
+            >
+              {v.size}
+            </button>
+          ))}
+        </div>
+      )}
+      <button
+        onClick={() => onAddToCart(product._id, size)}
+        disabled={needsSize && !size}
+      >
+        Add to Cart
+      </button>
     </div>
   );
 }
@@ -66,7 +99,10 @@ export default function ProductList() {
     }
   }, [query, category]);
 
-  const addToCart = (productId) => store.cart.add(productId, 1);
+  // `variant` is the size STRING (e.g. 'L'), per the SDK signature
+  // store.cart.add(productId, qty, variant). Products without variants
+  // pass undefined and the SDK accepts that.
+  const addToCart = (productId, variant) => store.cart.add(productId, 1, variant);
 
   return (
     <div>

package/skills/epicmerch-storefront.md

@@ -118,13 +118,46 @@ For each of the two files in this step, check existence individually. If a file
 Write `src/components/ProductCard.jsx`:
 
 ```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);
+
+  // 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;
+
   return (
     <div className="product-card">
-      <img src={product.images?.[0]} alt={product.name} />
+      <img src={image} alt={product.name} />
       <h3>{product.name}</h3>
-      <p>₹{product.price}</p>
-      <button onClick={() => onAddToCart(product._id)}>Add to Cart</button>
+      <p>₹{price}</p>
+      {needsSize && (
+        <div className="size-picker">
+          {availableSizes.map(v => (
+            <button
+              key={v.size}
+              type="button"
+              onClick={() => setSize(v.size)}
+              className={size === v.size ? 'selected' : ''}
+            >
+              {v.size}
+            </button>
+          ))}
+        </div>
+      )}
+      <button
+        onClick={() => onAddToCart(product._id, size)}
+        disabled={needsSize && !size}
+      >
+        Add to Cart
+      </button>
     </div>
   );
 }
@@ -153,7 +186,10 @@ export default function ProductList() {
     }
   }, [query, category]);
 
-  const addToCart = (productId) => store.cart.add(productId, 1);
+  // `variant` is the size STRING (e.g. 'L'), per the SDK signature
+  // store.cart.add(productId, qty, variant). Products without variants
+  // pass undefined and the SDK accepts that.
+  const addToCart = (productId, variant) => store.cart.add(productId, 1, variant);
 
   return (
     <div>
@@ -216,26 +252,46 @@ import { useEffect, useState } from 'react';
 import { store } from '../lib/epicmerch';
 
 export default function Cart({ onCheckout }) {
-  const [cart, setCart] = useState({ items: [] });
+  // 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 }.
+  const [cart, setCart] = useState({ cart: [] });
 
   useEffect(() => { store.cart.get().then(setCart); }, []);
 
-  const remove = async (productId) => {
-    await store.cart.remove(productId);
-    store.cart.get().then(setCart);
+  const remove = async (productId, variant) => {
+    await store.cart.remove(productId, variant);
+    // Optimistic local update — match on BOTH productId AND variant so we
+    // don't accidentally remove a different size of the same product.
+    setCart(c => ({
+      ...c,
+      cart: (c.cart || []).filter(
+        i => !(i.product._id === productId && i.variant === variant),
+      ),
+    }));
   };
 
-  const total = cart.items?.reduce((s, i) => s + i.price * i.qty, 0) ?? 0;
+  const items = cart.cart || [];
+  const total = items.reduce((sum, i) => {
+    const price = i.product.salePrice ?? i.product.price;
+    return sum + price * i.qty;
+  }, 0);
 
   return (
     <div>
-      {cart.items?.map(item => (
-        <div key={item.productId}>
-          <span>{item.name} x{item.qty}</span>
-          <span>₹{item.price * item.qty}</span>
-          <button onClick={() => remove(item.productId)}>Remove</button>
-        </div>
-      ))}
+      {items.map((item, idx) => {
+        const price = item.product.salePrice ?? item.product.price;
+        return (
+          <div key={`${item.product._id}-${item.variant || 'novariant'}-${idx}`}>
+            <span>
+              {item.product.name} x{item.qty}
+              {item.variant ? ` (${item.variant})` : ''}
+            </span>
+            <span>₹{price * item.qty}</span>
+            <button onClick={() => remove(item.product._id, item.variant)}>Remove</button>
+          </div>
+        );
+      })}
       <p>Total: ₹{total}</p>
       <button onClick={onCheckout}>Checkout</button>
     </div>
@@ -249,6 +305,8 @@ Write `src/components/Checkout.jsx`:
 import { useState } from 'react';
 import { store } from '../lib/epicmerch';
 
+// Razorpay's checkout.js is heavy — load it lazily on the first Place Order
+// click instead of blocking initial page render.
 const loadRazorpay = () =>
   new Promise((resolve) => {
     if (window.Razorpay) return resolve(true);
@@ -264,23 +322,49 @@ export default function Checkout({ cart, onSuccess }) {
 
   const placeOrder = async () => {
     await loadRazorpay();
-    const total = cart.items.reduce((s, i) => s + i.price * i.qty, 0);
-    const { orderId } = await store.orders.create({
-      orderItems: cart.items.map(i => ({ productId: i.productId, qty: i.qty, price: i.price })),
+
+    // Map cart line items to the orderItems shape the API expects.
+    // Critical fields per the SDK README:
+    //   - `product` (NOT `productId`) — the product _id
+    //   - `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,
+    }));
+    const total = orderItems.reduce((s, i) => s + i.price * i.qty, 0);
+
+    // ONE call to /customer/orders is enough — the server creates the
+    // EpicMerch order AND the Razorpay order in a single transaction and
+    // returns both back. Do NOT separately call store.payment.getConfig()
+    // or store.payment.createOrder() — orderResult already includes
+    // razorpayKeyId, razorpayOrderId, amount, currency, merchantName.
+    // Calling them again creates an orphan second Razorpay order AND can
+    // trigger an idempotency-key collision against /customer/orders.
+    const orderResult = await store.orders.create({
+      orderItems,
       shippingAddress: address,
       paymentMethod: 'Razorpay',
       totalPrice: total,
     });
-    const config = await store.payment.getConfig();
-    const { razorpayOrderId } = await store.payment.createOrder(total * 100, orderId);
+
     const rzp = new window.Razorpay({
-      key: config.razorpayKeyId,
-      order_id: razorpayOrderId,
-      amount: total * 100,
+      key:      orderResult.razorpayKeyId,
+      order_id: orderResult.razorpayOrderId,
+      amount:   orderResult.amount,
+      currency: orderResult.currency,
+      name:     orderResult.merchantName,
       handler: async (response) => {
-        await store.payment.verify({ ...response, orderId });
+        await store.payment.verify({ ...response, orderId: orderResult.orderId });
         await store.cart.clear();
-        onSuccess(orderId);
+        onSuccess(orderResult.orderId);
       },
     });
     rzp.open();
@@ -297,6 +381,8 @@ 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)`.
+
 Do NOT add any Razorpay script tag to `index.html` — the script loads dynamically only when the user clicks Place Order.
 
 Write `src/components/OrderHistory.jsx`:

package/src/index.js

@@ -36,7 +36,15 @@ async function main() {
   }
 
   if (cmd === 'setup') {
-    const code = await setup({ storeName });
+    const flagSet = new Set(argv);
+    const code = await setup({
+      storeName,
+      // --force / --reset: re-login even if a valid token exists AND
+      // overwrite any existing MCP config + skill files. Use this for
+      // a clean from-scratch reinstall (e.g. when testing a fresh
+      // merchant onboarding flow).
+      force: flagSet.has('--force') || flagSet.has('--reset'),
+    });
     process.exit(code);
     return;
   }

package/src/install.js

@@ -344,7 +344,10 @@ export async function install(opts = {}) {
  * (MCP config + slash commands). The merchant-friendly path; no
  * filesystem knowledge required.
  *
- * @param {{ storeName?: string, force?: boolean }} opts
+ * @param {{ storeName?: string, force?: boolean }} opts - `force` re-runs
+ *   the browser login even if a valid token already exists, AND overwrites
+ *   any existing MCP config + skill files. Useful for from-scratch
+ *   reinstalls or testing the onboarding flow as a new merchant.
  * @returns {Promise<number>} exit code
  */
 export async function setup(opts = {}) {
@@ -352,20 +355,32 @@ export async function setup(opts = {}) {
   console.error('━━━ EpicMerch setup ━━━');
   console.error('');
 
-  // --- Step 1: Login (skipped if a valid token already exists) ---
+  // --- Step 1: Login (skipped if a valid token already exists, UNLESS --force) ---
   // ESM dynamic import of an ESM-mocked token-store needs the same module specifier
   // as the test mocks; the helper above uses createRequire under the hood when needed.
-  const skipLogin = await import('./token-store.js').then(async (m) => {
+  const tokenStore = await import('./token-store.js');
+  const hasValidToken = (() => {
     try {
-      const data = m.readTokenStore();
+      const data = tokenStore.readTokenStore();
       const entry = data?.stores?.[data?.defaultStore];
       return entry && new Date(entry.refreshTokenExpiresAt) > new Date();
     } catch (_) { return false; }
-  });
+  })();
+  const skipLogin = hasValidToken && !opts.force;
 
   if (skipLogin) {
     console.error('Step 1/2: ✓ Already authenticated (skipping browser login).');
+    console.error('         Pass --force to re-login.');
   } else {
+    if (hasValidToken && opts.force) {
+      // --force on an authenticated session: revoke + remove the stored
+      // token first so the next login is genuinely fresh (and the server
+      // sees a new device row, not a renewed one).
+      try {
+        const { logout } = await import('./logout.js');
+        await logout({ storeName });
+      } catch (_) { /* don't block setup if revoke fails */ }
+    }
     console.error('Step 1/2: Authenticating via browser…');
     console.error('');
     try {

package/src/tools/scaffold.js

@@ -1,285 +1,372 @@
-// src/tools/scaffold.js
-const TEMPLATES = {
-  react: {
-    auth: [
-      {
-        path: 'src/lib/epicmerch.js',
-        content: `import EpicMerch from 'epicmerch';
-
-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 }),
-});
-`,
-      },
-      {
-        path: 'src/components/Login.jsx',
-        content: `import { useState } from 'react';
-import { store } from '../lib/epicmerch';
-
-export default function Login({ onLogin }) {
-  const [phone, setPhone] = useState('');
-  const [otp, setOtp] = useState('');
-  const [step, setStep] = useState('phone');
-
-  const sendOtp = async () => {
-    await store.auth.sendOtp(phone, 'phone');
-    setStep('otp');
-  };
-
-  const verify = async () => {
-    const result = await store.auth.verifyOtp(phone, otp, {});
-    if (result.token) {
-      store.setCustomerToken(result.token);
-      localStorage.setItem('customerInfo', JSON.stringify(result));
-      onLogin(result);
-    }
-  };
-
-  return (
-    <div>
-      {step === 'phone' ? (
-        <>
-          <input value={phone} onChange={e => setPhone(e.target.value)} placeholder="+919876543210" />
-          <button onClick={sendOtp}>Send OTP</button>
-        </>
-      ) : (
-        <>
-          <input value={otp} onChange={e => setOtp(e.target.value)} placeholder="Enter OTP" />
-          <button onClick={verify}>Verify</button>
-        </>
-      )}
-    </div>
-  );
-}
-`,
-      },
-    ],
-
-    products: [
-      {
-        path: 'src/components/ProductCard.jsx',
-        content: `export default function ProductCard({ product, onAddToCart }) {
-  return (
-    <div className="product-card">
-      <img src={product.images?.[0]} alt={product.name} />
-      <h3>{product.name}</h3>
-      <p>₹{product.price}</p>
-      <button onClick={() => onAddToCart(product._id)}>Add to Cart</button>
-    </div>
-  );
-}
-`,
-      },
-      {
-        path: 'src/components/ProductList.jsx',
-        content: `import { useEffect, useState } from 'react';
-import { store } from '../lib/epicmerch';
-import ProductCard from './ProductCard';
-
-export default function ProductList() {
-  const [products, setProducts] = useState([]);
-  const [category, setCategory] = useState(undefined);
-  const [categories, setCategories] = useState([]);
-
-  useEffect(() => {
-    store.categories.list().then(setCategories);
-  }, []);
-
-  useEffect(() => {
-    store.products.list({ type: category, limit: 12 }).then(d => setProducts(d.products));
-  }, [category]);
-
-  const addToCart = async (productId) => {
-    await store.cart.add(productId, 1);
-  };
-
-  return (
-    <div>
-      <div>
-        {categories.map(c => (
-          <button key={c} onClick={() => setCategory(c === 'All' ? undefined : c)}>{c}</button>
-        ))}
-      </div>
-      <div className="product-grid">
-        {products.map(p => <ProductCard key={p._id} product={p} onAddToCart={addToCart} />)}
-      </div>
-    </div>
-  );
-}
-`,
-      },
-    ],
-
-    orders: [
-      {
-        path: 'src/components/Cart.jsx',
-        content: `import { useEffect, useState } from 'react';
-import { store } from '../lib/epicmerch';
-
-export default function Cart({ onCheckout }) {
-  const [cart, setCart] = useState({ items: [] });
-
-  useEffect(() => { store.cart.get().then(setCart); }, []);
-
-  const remove = async (productId) => {
-    await store.cart.remove(productId);
-    // Optimistic local update — no need to re-fetch the whole cart from the
-    // server. We already know which item was removed.
-    setCart(c => ({ ...c, items: (c.items || []).filter(i => i.productId !== productId) }));
-  };
-
-  const total = cart.items?.reduce((sum, i) => sum + i.price * i.qty, 0) ?? 0;
-
-  return (
-    <div>
-      {cart.items?.map(item => (
-        <div key={item.productId}>
-          <span>{item.name} x{item.qty}</span>
-          <span>₹{item.price * item.qty}</span>
-          <button onClick={() => remove(item.productId)}>Remove</button>
-        </div>
-      ))}
-      <p>Total: ₹{total}</p>
-      <button onClick={onCheckout}>Checkout</button>
-    </div>
-  );
-}
-`,
-      },
-      {
-        path: 'src/components/Checkout.jsx',
-        content: `import { useState } from 'react';
-import { store } from '../lib/epicmerch';
-
-export default function Checkout({ cart, onSuccess }) {
-  const [address, setAddress] = useState({ street: '', city: '', postalCode: '', country: 'India' });
-
-  const placeOrder = async () => {
-    const total = cart.items.reduce((s, i) => s + i.price * i.qty, 0);
-
-    // ONE call to /customer/orders. The server creates the EpicMerch order
-    // AND the Razorpay order in a single transaction and returns both in
-    // the response. A separate payment.createOrder() call would create an
-    // orphan second Razorpay order AND trigger an idempotency collision
-    // against this same response cache.
-    const orderResult = await store.orders.create({
-      orderItems: cart.items.map(i => ({ productId: i.productId, qty: i.qty, price: i.price })),
-      shippingAddress: address,
-      paymentMethod: 'Razorpay',
-      totalPrice: total,
-    });
-
-    const rzp = new window.Razorpay({
-      key:       orderResult.razorpayKeyId,
-      order_id:  orderResult.razorpayOrderId,
-      amount:    orderResult.amount,
-      currency:  orderResult.currency,
-      name:      orderResult.merchantName,
-      handler: async (response) => {
-        await store.payment.verify({ ...response, orderId: orderResult.orderId });
-        await store.cart.clear();
-        onSuccess(orderResult.orderId);
-      },
-    });
-    rzp.open();
-  };
-
-  return (
-    <div>
-      <input placeholder="Street" onChange={e => setAddress(a => ({ ...a, street: e.target.value }))} />
-      <input placeholder="City" onChange={e => setAddress(a => ({ ...a, city: e.target.value }))} />
-      <input placeholder="Postal Code" onChange={e => setAddress(a => ({ ...a, postalCode: e.target.value }))} />
-      <button onClick={placeOrder}>Place Order</button>
-    </div>
-  );
-}
-`,
-      },
-      {
-        path: 'src/components/OrderHistory.jsx',
-        content: `import { useEffect, useState } from 'react';
-import { store } from '../lib/epicmerch';
-
-export default function OrderHistory() {
-  const [orders, setOrders] = useState([]);
-
-  useEffect(() => { store.orders.list().then(setOrders); }, []);
-
-  return (
-    <div>
-      {orders.map(order => (
-        <div key={order._id}>
-          <span>Order #{order._id.slice(-6)}</span>
-          <span>{order.status}</span>
-          <span>₹{order.totalPrice}</span>
-        </div>
-      ))}
-    </div>
-  );
-}
-`,
-      },
-    ],
-
-    envExample: {
-      path: '.env.example',
-      content: `VITE_API_KEY=your_epicmerch_api_key_here\n# VITE_API_URL=http://localhost:5001/api\n`,
-    },
-  },
-};
-
-function getFrameworkTemplates(framework) {
-  if (!TEMPLATES[framework]) {
-    throw new Error(`Framework "${framework}" not supported. Supported: ${Object.keys(TEMPLATES).join(', ')}`);
-  }
-  return TEMPLATES[framework];
-}
-
-export function scaffoldTools() {
-  return {
-    async store_scaffold_auth({ framework = 'react' } = {}) {
-      try {
-        const t = getFrameworkTemplates(framework);
-        return { content: [{ type: 'text', text: JSON.stringify(t.auth, null, 2) }] };
-      } catch (err) {
-        return { isError: true, content: [{ type: 'text', text: err.message }] };
-      }
-    },
-
-    async store_scaffold_products({ framework = 'react' } = {}) {
-      try {
-        const t = getFrameworkTemplates(framework);
-        return { content: [{ type: 'text', text: JSON.stringify(t.products, null, 2) }] };
-      } catch (err) {
-        return { isError: true, content: [{ type: 'text', text: err.message }] };
-      }
-    },
-
-    async store_scaffold_orders({ framework = 'react' } = {}) {
-      try {
-        const t = getFrameworkTemplates(framework);
-        return { content: [{ type: 'text', text: JSON.stringify(t.orders, null, 2) }] };
-      } catch (err) {
-        return { isError: true, content: [{ type: 'text', text: err.message }] };
-      }
-    },
-
-    async store_scaffold_full({ framework = 'react' } = {}) {
-      try {
-        const t = getFrameworkTemplates(framework);
-        const files = [...t.auth, ...t.products, ...t.orders, t.envExample];
-        return { content: [{ type: 'text', text: JSON.stringify(files, null, 2) }] };
-      } catch (err) {
-        return { isError: true, content: [{ type: 'text', text: err.message }] };
-      }
-    },
-  };
-}
-
-export const scaffoldToolDefs = [
-  { name: 'store_scaffold_auth', description: 'Generate auth integration files (SDK init + Login component) for a framework. Returns [{path, content}] — write these files to the project.', schema: { framework: { type: 'string', description: 'react (default)' } } },
-  { name: 'store_scaffold_products', description: 'Generate product catalog components (ProductList, ProductCard) for a framework.', schema: { framework: { type: 'string' } } },
-  { name: 'store_scaffold_orders', description: 'Generate cart + order management components (Cart, Checkout, OrderHistory) for a framework.', schema: { framework: { type: 'string' } } },
-  { name: 'store_scaffold_full', description: 'Generate a complete EpicMerch-integrated storefront scaffold (auth + products + orders + .env.example).', schema: { framework: { type: 'string' } } },
-];
+// src/tools/scaffold.js
+const TEMPLATES = {
+  react: {
+    auth: [
+      {
+        path: 'src/lib/epicmerch.js',
+        content: `import EpicMerch from 'epicmerch';
+
+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 }),
+});
+`,
+      },
+      {
+        path: 'src/components/Login.jsx',
+        content: `import { useState } from 'react';
+import { store } from '../lib/epicmerch';
+
+export default function Login({ onLogin }) {
+  const [phone, setPhone] = useState('');
+  const [otp, setOtp] = useState('');
+  const [step, setStep] = useState('phone');
+
+  const sendOtp = async () => {
+    await store.auth.sendOtp(phone, 'phone');
+    setStep('otp');
+  };
+
+  const verify = async () => {
+    const result = await store.auth.verifyOtp(phone, otp, {});
+    if (result.token) {
+      store.setCustomerToken(result.token);
+      localStorage.setItem('customerInfo', JSON.stringify(result));
+      onLogin(result);
+    }
+  };
+
+  return (
+    <div>
+      {step === 'phone' ? (
+        <>
+          <input value={phone} onChange={e => setPhone(e.target.value)} placeholder="+919876543210" />
+          <button onClick={sendOtp}>Send OTP</button>
+        </>
+      ) : (
+        <>
+          <input value={otp} onChange={e => setOtp(e.target.value)} placeholder="Enter OTP" />
+          <button onClick={verify}>Verify</button>
+        </>
+      )}
+    </div>
+  );
+}
+`,
+      },
+    ],
+
+    products: [
+      {
+        path: 'src/components/ProductCard.jsx',
+        content: `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);
+
+  // 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;
+
+  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 => (
+            <button
+              key={v.size}
+              type="button"
+              onClick={() => setSize(v.size)}
+              className={size === v.size ? 'selected' : ''}
+            >
+              {v.size}
+            </button>
+          ))}
+        </div>
+      )}
+      <button
+        onClick={() => onAddToCart(product._id, size)}
+        disabled={needsSize && !size}
+      >
+        Add to Cart
+      </button>
+    </div>
+  );
+}
+`,
+      },
+      {
+        path: 'src/components/ProductList.jsx',
+        content: `import { useEffect, useState } from 'react';
+import { store } from '../lib/epicmerch';
+import ProductCard from './ProductCard';
+
+export default function ProductList() {
+  const [products, setProducts] = useState([]);
+  const [category, setCategory] = useState(undefined);
+  const [categories, setCategories] = useState([]);
+
+  useEffect(() => {
+    store.categories.list().then(setCategories);
+  }, []);
+
+  useEffect(() => {
+    store.products.list({ type: category, limit: 12 }).then(d => setProducts(d.products ?? d));
+  }, [category]);
+
+  // \`variant\` is the size STRING (e.g. 'L'), per the SDK signature
+  // store.cart.add(productId, qty, variant). Products without variants
+  // pass undefined and the SDK accepts that.
+  const addToCart = async (productId, variant) => {
+    await store.cart.add(productId, 1, variant);
+  };
+
+  return (
+    <div>
+      <div>
+        {categories.map(c => (
+          <button key={c} onClick={() => setCategory(c === 'All' ? undefined : c)}>{c}</button>
+        ))}
+      </div>
+      <div className="product-grid">
+        {products.map(p => <ProductCard key={p._id} product={p} onAddToCart={addToCart} />)}
+      </div>
+    </div>
+  );
+}
+`,
+      },
+    ],
+
+    orders: [
+      {
+        path: 'src/components/Cart.jsx',
+        content: `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 }.
+  const [cart, setCart] = useState({ cart: [] });
+
+  useEffect(() => { store.cart.get().then(setCart); }, []);
+
+  const remove = async (productId, variant) => {
+    await store.cart.remove(productId, variant);
+    // Optimistic local update — match on BOTH productId and variant so we
+    // don't accidentally remove a different size of the same product.
+    setCart(c => ({
+      ...c,
+      cart: (c.cart || []).filter(
+        i => !(i.product._id === productId && i.variant === variant),
+      ),
+    }));
+  };
+
+  const items = cart.cart || [];
+  const total = items.reduce((sum, i) => {
+    const price = i.product.salePrice ?? i.product.price;
+    return sum + price * i.qty;
+  }, 0);
+
+  return (
+    <div>
+      {items.map((item, idx) => {
+        const price = item.product.salePrice ?? item.product.price;
+        return (
+          <div key={\`\${item.product._id}-\${item.variant || 'novariant'}-\${idx}\`}>
+            <span>
+              {item.product.name} x{item.qty}
+              {item.variant ? \` (\${item.variant})\` : ''}
+            </span>
+            <span>₹{price * item.qty}</span>
+            <button onClick={() => remove(item.product._id, item.variant)}>Remove</button>
+          </div>
+        );
+      })}
+      <p>Total: ₹{total}</p>
+      <button onClick={onCheckout}>Checkout</button>
+    </div>
+  );
+}
+`,
+      },
+      {
+        path: 'src/components/Checkout.jsx',
+        content: `import { useState } from 'react';
+import { store } from '../lib/epicmerch';
+
+// Razorpay's checkout.js is heavy — load it lazily on the first Place Order
+// click instead of blocking initial page render. window.Razorpay sticks
+// around after first load, so subsequent clicks skip the network round-trip.
+const loadRazorpay = () =>
+  new Promise((resolve) => {
+    if (window.Razorpay) return resolve(true);
+    const script = document.createElement('script');
+    script.src = 'https://checkout.razorpay.com/v1/checkout.js';
+    script.onload = () => resolve(true);
+    script.onerror = () => resolve(false);
+    document.body.appendChild(script);
+  });
+
+export default function Checkout({ cart, onSuccess }) {
+  const [address, setAddress] = useState({ street: '', city: '', postalCode: '', country: 'India' });
+
+  const placeOrder = async () => {
+    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
+    //   - \`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,
+    }));
+    const total = orderItems.reduce((s, i) => s + i.price * i.qty, 0);
+
+    // ONE call to /customer/orders. The server creates the EpicMerch order
+    // AND the Razorpay order in a single transaction and returns both in
+    // the response. Do NOT separately call payment.getConfig() or
+    // payment.createOrder() — orderResult already includes razorpayKeyId,
+    // razorpayOrderId, amount, currency, and merchantName. Calling them
+    // again creates an orphan second Razorpay order AND triggers an
+    // idempotency-key collision against this same response cache.
+    const orderResult = await store.orders.create({
+      orderItems,
+      shippingAddress: address,
+      paymentMethod: 'Razorpay',
+      totalPrice: total,
+    });
+
+    const rzp = new window.Razorpay({
+      key:      orderResult.razorpayKeyId,
+      order_id: orderResult.razorpayOrderId,
+      amount:   orderResult.amount,
+      currency: orderResult.currency,
+      name:     orderResult.merchantName,
+      handler: async (response) => {
+        await store.payment.verify({ ...response, orderId: orderResult.orderId });
+        await store.cart.clear();
+        onSuccess(orderResult.orderId);
+      },
+    });
+    rzp.open();
+  };
+
+  return (
+    <div>
+      <input placeholder="Street" onChange={e => setAddress(a => ({ ...a, street: e.target.value }))} />
+      <input placeholder="City" onChange={e => setAddress(a => ({ ...a, city: e.target.value }))} />
+      <input placeholder="Postal Code" onChange={e => setAddress(a => ({ ...a, postalCode: e.target.value }))} />
+      <button onClick={placeOrder}>Place Order</button>
+    </div>
+  );
+}
+`,
+      },
+      {
+        path: 'src/components/OrderHistory.jsx',
+        content: `import { useEffect, useState } from 'react';
+import { store } from '../lib/epicmerch';
+
+export default function OrderHistory() {
+  const [orders, setOrders] = useState([]);
+
+  useEffect(() => { store.orders.list().then(setOrders); }, []);
+
+  return (
+    <div>
+      {orders.map(order => (
+        <div key={order._id}>
+          <span>Order #{order._id.slice(-6)}</span>
+          <span>{order.status}</span>
+          <span>₹{order.totalPrice}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+`,
+      },
+    ],
+
+    envExample: {
+      path: '.env.example',
+      content: `VITE_API_KEY=your_epicmerch_api_key_here\n# VITE_API_URL=http://localhost:5001/api\n`,
+    },
+  },
+};
+
+function getFrameworkTemplates(framework) {
+  if (!TEMPLATES[framework]) {
+    throw new Error(`Framework "${framework}" not supported. Supported: ${Object.keys(TEMPLATES).join(', ')}`);
+  }
+  return TEMPLATES[framework];
+}
+
+export function scaffoldTools() {
+  return {
+    async store_scaffold_auth({ framework = 'react' } = {}) {
+      try {
+        const t = getFrameworkTemplates(framework);
+        return { content: [{ type: 'text', text: JSON.stringify(t.auth, null, 2) }] };
+      } catch (err) {
+        return { isError: true, content: [{ type: 'text', text: err.message }] };
+      }
+    },
+
+    async store_scaffold_products({ framework = 'react' } = {}) {
+      try {
+        const t = getFrameworkTemplates(framework);
+        return { content: [{ type: 'text', text: JSON.stringify(t.products, null, 2) }] };
+      } catch (err) {
+        return { isError: true, content: [{ type: 'text', text: err.message }] };
+      }
+    },
+
+    async store_scaffold_orders({ framework = 'react' } = {}) {
+      try {
+        const t = getFrameworkTemplates(framework);
+        return { content: [{ type: 'text', text: JSON.stringify(t.orders, null, 2) }] };
+      } catch (err) {
+        return { isError: true, content: [{ type: 'text', text: err.message }] };
+      }
+    },
+
+    async store_scaffold_full({ framework = 'react' } = {}) {
+      try {
+        const t = getFrameworkTemplates(framework);
+        const files = [...t.auth, ...t.products, ...t.orders, t.envExample];
+        return { content: [{ type: 'text', text: JSON.stringify(files, null, 2) }] };
+      } catch (err) {
+        return { isError: true, content: [{ type: 'text', text: err.message }] };
+      }
+    },
+  };
+}
+
+export const scaffoldToolDefs = [
+  { name: 'store_scaffold_auth', description: 'Generate auth integration files (SDK init + Login component) for a framework. Returns [{path, content}] — write these files to the project.', schema: { framework: { type: 'string', description: 'react (default)' } } },
+  { name: 'store_scaffold_products', description: 'Generate product catalog components (ProductList, ProductCard with size picker) for a framework.', schema: { framework: { type: 'string' } } },
+  { name: 'store_scaffold_orders', description: 'Generate cart + order management components (Cart, Checkout, OrderHistory) for a framework. Cart reads the {cart, cartCount, cartTotal} shape returned by store.cart.get(); Checkout uses the orderItems shape {product, name, image, qty, price, variant} required by the API.', schema: { framework: { type: 'string' } } },
+  { name: 'store_scaffold_full', description: 'Generate a complete EpicMerch-integrated storefront scaffold (auth + products + orders + .env.example).', schema: { framework: { type: 'string' } } },
+];