epicmerch-mcp 1.3.1 → 1.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "epicmerch-mcp",
-  "version": "1.3.1",
+  "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,26 +33,49 @@ 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: [...] } — 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); }, []);
 
-  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>
@@ -83,15 +106,36 @@ 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 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 => ({
+      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);
 
     // 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,48 @@ 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 }) {
+  // 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 hasVariants = availableVariants.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>
+      {hasVariants && (
+        <div className="variant-picker">
+          {availableVariants.map(v => (
+            <button
+              key={v.variant}
+              type="button"
+              onClick={() => setVariant(v.variant)}
+              className={variant === v.variant ? 'selected' : ''}
+            >
+              {v.variant}
+            </button>
+          ))}
+        </div>
+      )}
+      <button
+        onClick={() => onAddToCart(product._id, variant)}
+        disabled={hasVariants && !variant}
+      >
+        Add to Cart
+      </button>
     </div>
   );
 }
@@ -66,7 +101,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>