epicmerch-mcp 1.3.21 → 1.3.22

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "epicmerch",
   "description": "Run your EpicMerch store from chat — products, orders, analytics, Shopify migration, Stripe setup. Auto-installs the MCP + slash commands + browser OAuth.",
-  "version": "1.0.0",
+  "version": "1.3.22",
   "author": {
     "name": "Aditya Patel",
     "email": "aditya141312@gmail.com",

package/package.json

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

package/skills/epicmerch-storefront.md

@@ -1,123 +1,608 @@
 ---
 name: epicmerch-storefront
-description: EpicMerch storefront scaffold — skeleton from the deterministic store_scaffold_full tool (SDK + Login + ProductCard + ProductList + Cart + Checkout + OrderHistory + .env), then a themed style pass and optional custom pages. The "do everything" route under /epicmerch, and the home for single-slice integration (auth-only, products-only, orders-only). Fast by design: the boilerplate is emitted by a tool (zero hand-writing), so generation is minutes, not an hour.
+description: EpicMerch storefront scaffold — SDK + Login + ProductCard + ProductList + Cart + Checkout + OrderHistory + .env with auto-generated API key. The "do everything" route under /epicmerch, and also the home for single-slice integration (auth-only, products-only, or orders-only).
 ---
 
-# EpicMerch Storefront Scaffold (tiered)
+# EpicMerch Full Storefront Scaffold
 
-Build the storefront in tiers, fast: lay down the **standard skeleton from the
-`store_scaffold_full` tool** (instant — do NOT hand-write those files), apply a
-**theme delta**, and only LLM-generate genuinely custom pages (in parallel).
+You are integrating EpicMerch into this project. EpicMerch is a complete e-commerce backend that handles auth, inventory, orders, and payments. Follow every step below in order without asking for confirmation unless a step explicitly says to ask.
 
-**Idempotency rule (throughout):** before writing any file, check if it already
-exists. If it does, SKIP it and tell the user "X already exists — keeping it".
-Never overwrite a merchant's existing file.
+## Scope — full storefront, or just one slice
 
-## Phase 0 — Survey the project
+This skill scaffolds the **full** storefront by default. It also absorbs the former `/epicmerch-auth`, `/epicmerch-products`, and `/epicmerch-orders` skills — if the merchant asked for only one slice, run just that subset. **Steps 0–3 always apply** (survey, detect framework, install SDK, write `src/lib/epicmerch.js`); then:
 
-- Read `package.json`. Determine the framework + env prefix:
-  - `react` or `vite` in deps → framework `react`, env prefix `VITE_`
-  - `next` in deps → framework `react`, env prefix `NEXT_PUBLIC_`
-  - `vue` in deps → framework `react`, env prefix `VITE_`; tell the user "Vue isn't natively supported — installing React templates."
-  - none / no `package.json` → tell the user "No frontend project detected here — run me from inside a React/Vite/Next project." STOP.
-- List which scaffold targets already exist (so Phase 1 can skip them):
-  `src/lib/epicmerch.js`, `src/components/{Login,ProductCard,ProductList,Cart,Checkout,OrderHistory}.jsx`, `.env`, `.env.example`.
-- Briefly tell the user which exist (will be kept) vs which will be created.
+- **"add login / OTP / sign-in"** → also Step 4 (Login.jsx).
+- **"add a product catalog / product list / search"** → also Step 5 (+5b) (ProductCard + ProductList, including the keep-existing-card adapter path).
+- **"add a cart / checkout / order history"** → also Step 6 (Cart + Checkout + OrderHistory).
+- **"set up everything" / unsure** → the whole checklist.
 
-## Phase 1 — Skeleton (instant, via the scaffold tool)
+Step 7 (API key + `.env`) and Step 8 (next steps) run in every mode. The components and contracts are identical across modes — only which files you write changes.
 
-Do NOT hand-write the standard components — that is the slow path. Call the tool:
+**Idempotency rule (apply throughout):** Before writing any file in the scaffold steps below, check if it already exists. If it does, SKIP that file and tell the user "X already exists — keeping it". Never overwrite existing files. The merchant may already have a polished version of any of these components; preserving their work is more important than completing the scaffold.
 
+## Checklist
+
+- [ ] **Step 0: Survey the project**
+
+List which of the scaffold target files already exist in this project:
+- `src/lib/epicmerch.js`
+- `src/components/Login.jsx`
+- `src/components/ProductCard.jsx`
+- `src/components/ProductList.jsx`
+- `src/components/Cart.jsx`
+- `src/components/Checkout.jsx`
+- `src/components/OrderHistory.jsx`
+- `.env.example`
+- `.env`
+
+Briefly tell the user which already exist (those will be skipped) and which will be created. Then proceed.
+
+- [ ] **Step 1: Detect framework**
+
+Read `package.json`. Determine the framework:
+- If `"react"` or `"vite"` in dependencies → framework = `react`, envPrefix = `VITE_`
+- If `"next"` in dependencies → framework = `react`, envPrefix = `NEXT_PUBLIC_`
+- If `"vue"` in dependencies → framework = `react`, envPrefix = `VITE_`; tell the user: "Vue is not yet natively supported — installing React templates instead."
+- Otherwise → framework = `react`, envPrefix = `VITE_`
+
+Tell the user: "Detected [framework]. Installing EpicMerch SDK..."
+
+- [ ] **Step 2: Install the SDK**
+
+Check `package.json` first. If `"epicmerch"` is already in `dependencies`, skip the install and tell the user "epicmerch SDK already installed". Otherwise:
+
+Run: `npm install epicmerch`
+
+- [ ] **Step 3: Create SDK initializer**
+
+**If `src/lib/epicmerch.js` already exists, skip this step entirely** and tell the user "src/lib/epicmerch.js already exists — keeping it". Otherwise, write `src/lib/epicmerch.js` using the `envPrefix` detected in Step 1 to substitute the env var names:
+
+- For `VITE_` prefix (Vite / React):
+```js
+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 }),
+});
+
+// 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):
+```js
+import EpicMerch from 'epicmerch';
+
+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**
+
+**If `src/components/Login.jsx` already exists, skip this step** and tell the user "Login.jsx already exists — keeping it". Otherwise write `src/components/Login.jsx`:
+
+```jsx
+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 [error, setError] = useState('');
+
+  const sendOtp = async () => {
+    setError('');
+    try {
+      await store.auth.sendOtp(phone, 'phone');
+      setStep('otp');
+    } catch (e) {
+      // e.g. invalid number, or OTP_RATE_LIMIT_EXCEEDED (5/hour).
+      setError(e?.message || 'Could not send OTP. Check the number and try again.');
+    }
+  };
+
+  const verify = async () => {
+    setError('');
+    try {
+      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);
+      }
+    } catch (e) {
+      // e.g. "Invalid OTP" / "OTP expired" — let them retry.
+      setError(e?.message || 'Invalid or expired OTP. Try again.');
+      setOtp('');
+    }
+  };
+
+  return (
+    <div>
+      {step === 'phone' ? (
+        <>
+          <input
+            type="tel"
+            value={phone}
+            onChange={e => setPhone(e.target.value)}
+            placeholder="+919876543210"
+            autoComplete="tel"
+          />
+          <button onClick={sendOtp}>Send OTP</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>
+        </>
+      )}
+      {error && <p style={{ color: 'crimson' }}>{error}</p>}
+    </div>
+  );
+}
+```
+
+- [ ] **Step 5: Scaffold product catalog**
+
+For each of the two files in this step, check existence individually. If a file already exists, skip writing it and tell the user "X already exists — keeping it". Otherwise write it.
+
+**Special case — `ProductCard.jsx` already exists:** don't just skip it. The merchant has a card UI that's probably showing placeholder data. KEEP their card, but make sure it gets fed REAL products: (1) read the existing card to note the field names it expects (`name`/`title`, `price`/`cost`, `image`/`images[0]`/`thumbnail`, single `product` prop vs destructured); (2) when you write/keep `ProductList.jsx` below, have it call `store.products.list()` and map each API product onto the shape the existing card expects (an adapter — see the ProductList note below). Tell the user "ProductCard.jsx already exists — keeping your design and wiring it to live product data."
+
+Write `src/components/ProductCard.jsx`:
+
+```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={image} alt={product.name} />
+      <h3>{product.name}</h3>
+      <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>
+  );
+}
+```
+
+Write `src/components/ProductList.jsx`:
+
+```jsx
+import { useEffect, useState } from 'react';
+import { store } from '../lib/epicmerch';
+import ProductCard from './ProductCard';
+
+export default function ProductList() {
+  const [products, setProducts] = useState([]);
+  const [categories, setCategories] = useState([]);
+  const [category, setCategory] = useState(undefined);
+  const [query, setQuery] = useState('');
+  // products.list/search return { products, page, pages, total } — track
+  // page + pages for "Load more" so a catalog (or result set) larger than
+  // `limit` isn't silently truncated to the first page.
+  const [page, setPage] = useState(1);
+  const [pages, setPages] = useState(1);
+
+  useEffect(() => { store.categories.list().then(setCategories); }, []);
+
+  useEffect(() => {
+    const req = query.trim()
+      ? store.products.search(query, { page, limit: 12 })
+      : store.products.list({ type: category, page, limit: 12 });
+    req.then(d => {
+      setPages(d.pages ?? 1);
+      // Page 1 replaces (new filter); later pages append (Load more).
+      setProducts(prev => (page === 1 ? (d.products ?? d) : [...prev, ...(d.products ?? d)]));
+    });
+  }, [query, category, page]);
+
+  // Reset to page 1 whenever the filter changes.
+  const changeQuery = (q) => { setPage(1); setQuery(q); };
+  const changeCategory = (c) => { setPage(1); setQuery(''); setCategory(c === 'All' ? undefined : c); };
+
+  // `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>
+      <input
+        placeholder="Search products..."
+        value={query}
+        onChange={e => changeQuery(e.target.value)}
+      />
+      <div>
+        {categories.map(c => (
+          <button key={c} onClick={() => changeCategory(c)}>{c}</button>
+        ))}
+      </div>
+      <div className="product-grid">
+        {products.map(p => <ProductCard key={p._id} product={p} onAddToCart={addToCart} />)}
+      </div>
+      {page < pages && (
+        <button onClick={() => setPage(p => p + 1)}>Load more</button>
+      )}
+    </div>
+  );
+}
+```
+
+**If you KEPT an existing `ProductCard` (it already existed):** the API returns each product as `{ _id, name, price, salePrice, image, images, variants, ... }`. If the merchant's card reads different field names, don't change the card — adapt the data in the `.map()` so live products populate their existing design:
+
+```jsx
+// e.g. existing card expects { title, cost, thumbnail }:
+{products.map(p => (
+  <ProductCard
+    key={p._id}
+    product={{ ...p, title: p.name, cost: p.salePrice ?? p.price, thumbnail: p.images?.[0] || p.image }}
+    onAddToCart={addToCart}
+  />
+))}
+```
+
+Match the adapter keys to whatever the existing card actually reads (you noted that when you decided to keep it). The cards keep the merchant's look but show **real products fetched via `store.products.list()`**.
+
+- [ ] **Step 5b: Wire up an existing search bar (only if `ProductList.jsx` was skipped)**
+
+If you wrote a fresh `ProductList.jsx` in Step 5, skip this step — the canonical scaffold already has search wired.
+
+If `ProductList.jsx` was SKIPPED because it already existed, the merchant has their own UI. They may have a search bar somewhere — in a `Navbar`, a `Header`, a dedicated `SearchBar.jsx`, a search page, etc. — that isn't currently calling EpicMerch's search API. Detect and offer to wire it up.
+
+**Detection.** Look through `src/` for files containing any of these signals (case-insensitive):
+- `<input` whose `placeholder` mentions `search`
+- A state variable named `query`, `search`, `searchTerm`, `searchQuery`, or `keyword`
+- A handler named `onSearch`, `handleSearch`, `onQueryChange`, or similar
+
+For each match, check whether the file already calls `store.products.search(`. If yes, it's wired — skip silently.
+
+**For each unwired match:** show the merchant the file path and the snippet you found, then say:
+
+> "I noticed a search input in `<path>` that doesn't call EpicMerch's search yet. The one-line wire-up is:
+>
+> ```js
+> import { store } from '../lib/epicmerch';  // add at top if missing
+>
+> // inside the search handler / useEffect:
+> store.products.search(query).then(d => setProducts(d.products ?? d));
+> ```
+>
+> Want me to apply this to your component? (yes / no — I'll leave it alone if no.)"
+
+**WAIT for an explicit yes before editing.** If the merchant declines, move on without changing the file.
+
+If you find no search bar anywhere in `src/`, skip this step silently — don't tell the merchant "no search bar found", just continue to Step 6.
+
+- [ ] **Step 6: Scaffold cart + orders**
+
+For each of the three files in this step (Cart.jsx, Checkout.jsx, OrderHistory.jsx), check existence individually. If a file already exists, skip writing it and tell the user "X already exists — keeping it". Otherwise write it.
+
+Write `src/components/Cart.jsx`:
+
+```jsx
+import { useEffect, useState } from 'react';
+import { store } from '../lib/epicmerch';
+
+export default function Cart({ onCheckout }) {
+  // 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, 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>
+  );
+}
+```
+
+Write `src/components/Checkout.jsx`:
+
+```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);
+    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 [error, setError] = useState('');
+
+  const placeOrder = async () => {
+    setError('');
+    await loadRazorpay();
+
+    // 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.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.
+    let orderResult;
+    try {
+      orderResult = await store.orders.create({
+        orderItems,
+        shippingAddress: address,
+        paymentMethod: 'Razorpay',
+        totalPrice: total,
+      });
+    } catch (e) {
+      // The API returns a structured error and the SDK throws it:
+      // INSUFFICIENT_STOCK ("Halden 3-Seat Sofa: need 1, have 0"),
+      // INVALID_ORDER_ITEM, PAYMENT_NOT_CONFIGURED, etc. Surface the message.
+      setError(e?.message || 'Could not place the order. Please try again.');
+      return;
+    }
+
+    // COD / fully-discounted orders return NO Razorpay session
+    // (razorpayOrderId is null) — the order is already placed, nothing to pay.
+    if (!orderResult.razorpayOrderId) {
+      await store.cart.clear();
+      onSuccess(orderResult.orderId);
+      return;
+    }
+
+    const rzp = new window.Razorpay({
+      key:      orderResult.razorpayKeyId,
+      order_id: orderResult.razorpayOrderId,
+      amount:   orderResult.amount,        // already in paise
+      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 }))} />
+      {error && <p style={{ color: 'crimson' }}>{error}</p>}
+      <button onClick={placeOrder}>Place Order</button>
+    </div>
+  );
+}
 ```
-store_scaffold_full({ framework: "react" })
+
+**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.
+
+Write `src/components/OrderHistory.jsx`:
+
+```jsx
+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>
+      <h2>Your Orders</h2>
+      {orders.map(order => (
+        <div key={order._id}>
+          <span>Order #{order._id.slice(-6)}</span>
+          <span> — ₹{order.totalPrice}</span>
+          <span> — {order.status}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
 ```
 
-It returns `content[0].text` = a JSON string of `[{ path, content }]` for 8 files:
-`src/lib/epicmerch.js`, `src/components/Login.jsx`, `ProductCard.jsx`,
-`ProductList.jsx`, `Cart.jsx`, `Checkout.jsx`, `OrderHistory.jsx`, `.env.example`.
+- [ ] **Step 7: Generate API key via MCP + write `.env`**
+
+This step has two parts: write `.env.example` (the template), then generate a real API key and write a working `.env`.
+
+**Part A — `.env.example`:** If `.env.example` already exists, skip writing it and tell the user ".env.example already exists — keeping it". Otherwise write `.env.example`:
 
-Parse it and **write each file whose path does NOT already exist** (Phase 0
-skip-existing rule). Report `✓ wrote <n> files (kept <m> existing)`.
+```
+VITE_API_KEY=your_epicmerch_api_key_here
+# VITE_API_URL is OPTIONAL — only set it for local development.
+# Production: leave it unset; the SDK defaults to https://api.epicmerch.in/api
+# Local dev: VITE_API_URL=http://localhost:5002/api
+```
 
-These files are contract-tested (cart.cart shape, `productId`, `v.variant`,
-session-restore, COD guard, pagination) — they are correct by construction, which
-is why we use the tool instead of writing them by hand.
+Check `.gitignore` — if `.env` is not listed, append `.env` to `.gitignore` before any `.env` file is written.
 
-> If the merchant only wants ONE slice (auth-only / products-only / orders-only),
-> call the narrower tool instead: `store_scaffold_auth`, `store_scaffold_products`,
-> or `store_scaffold_orders` (same `{framework}` arg, same `[{path,content}]`
-> return). Phases 0, 2, 3, 5 still apply.
+**Part B — generate a real API key + write `.env`:**
 
-## Phase 2 — API key + `.env`
+First, read `.env` if it exists. If it already contains a `VITE_API_KEY=` line whose value is NOT the placeholder string `your_epicmerch_api_key_here` (i.e. there's already a real key), skip Part B entirely and tell the user "Existing API key in .env — keeping it".
 
-`store_scaffold_full` emits `.env.example`; now create the real `.env`:
+Otherwise, the merchant is authenticated via the EpicMerch MCP (this skill assumes the MCP is connected — that's how it was invoked). Generate a key by calling the MCP tool:
 
-1. If `.env` already has a real `VITE_API_KEY` (not the `your_epicmerch_api_key_here`
-   placeholder), keep it — tell the user "Existing API key in .env — keeping it."
-2. Otherwise call `merchant_generate_api_key({ name: "Storefront" })`, take the
-   returned key, and write `.env`:
-   - Production (default): just `VITE_API_KEY=<key>` (the SDK defaults to
-     `https://api.epicmerch.in/api`).
-   - Local dev (only if the merchant is clearly on a local server): also add
-     `VITE_API_URL=http://localhost:5001/api`.
-   - For Next.js, use `NEXT_PUBLIC_API_KEY` / `NEXT_PUBLIC_API_URL`.
-3. Ensure `.env` is gitignored — if `.gitignore` lacks `.env`, append it BEFORE
-   writing `.env`.
-4. Fallback: if `merchant_generate_api_key` is unavailable, tell the user to grab a
-   key from `https://epicmerch.in/dashboard → API Keys` and add it to `.env`. Do NOT
-   abort — continue to Phase 3.
+```
+merchant_generate_api_key({ name: "Storefront" })
+```
 
-## Phase 3 — Theme delta (the only standard-tier LLM work)
+The response will include the new key. Extract it (the field is typically `key` or `apiKey` — check the response shape). Then write/update `.env`.
 
-Ask ONE vibe question:
+**Production (default).** Write only the key — the SDK already knows the prod URL:
 
-> "Quick — what's the vibe of your store?
-> 1) Editorial Funk (bold typography, big imagery, asymmetric layouts)
-> 2) Minimal Mono (clean, monochrome, lots of whitespace)
-> 3) Vibrant Pop (colourful, rounded corners, playful)
-> 4) Skip — functional unstyled scaffolds, I'll polish later"
+```
+VITE_API_KEY=<the generated key from the MCP response>
+```
 
-- Options 1–3: do a BOUNDED Tailwind pass — add 5–10 well-chosen utility classes
-  per scaffolded component (typography, spacing, colour) matching the vibe. This is
-  a class edit, NOT a rewrite — do not regenerate the components.
-- Option 4: skip the pass.
-- Either way, confirm `src/lib/epicmerch.js` contains the **session-restore block**
-  (`localStorage.getItem('customerInfo') → setCustomerToken`). The tool includes it
-  by default; if a pre-existing file was kept and lacks it, add it manually — without
-  it, OTP login silently doesn't survive a page reload (the #1 storefront bug).
-- Recap `✓ Storefront scaffolded + styled (<vibe>)` or `✓ ... (unstyled)`.
+**Local development.** Only if the merchant is clearly running against a local EpicMerch server (e.g. they explicitly said so, or their existing `.env` already had a `localhost` URL, or the MCP was wired with `EPICMERCH_API_URL=http://localhost:...`), ALSO write the override:
 
-## Phase 4 — Custom pages (opt-in, parallel)
+```
+VITE_API_KEY=<the generated key from the MCP response>
+VITE_API_URL=http://localhost:5002/api
+```
 
-Ask: *"Want any custom pages beyond the standard store (e.g. an About page, a
-lookbook, a size guide, a blog)? Name them, or say 'no' to finish."*
+When in doubt, default to the production form (no `VITE_API_URL` line). Don't ask the merchant — guess from context.
 
-- "no" → skip to Phase 5.
-- Otherwise build a manifest: one entry per custom file (path + a one-line spec).
-  Then generate them — **in parallel if your client supports subagents** (e.g.
-  Claude Code's Task/Agent tool: dispatch one agent per file in a single batch);
-  otherwise generate them **sequentially** (still far faster than the old flow,
-  since the whole skeleton was free). Each generation gets: the SDK usage (import
-  `store` from `src/lib/epicmerch.js`; products via `store.products.list()`; the
-  cart/checkout contracts), the chosen vibe, and that one file's spec.
-- After the custom files exist, do ONE small assembly pass: wire routes/nav so the
-  new pages are reachable. Preserve existing routing.
+**Fallback if MCP isn't available:** If the `merchant_generate_api_key` tool fails or isn't connected, tell the user: "MCP tool unavailable. Generate a key manually at https://epicmerch.in/dashboard → API Keys and add it to .env." Do NOT fail the whole flow — continue to Step 8.
 
-## Phase 5 — Verify (the Definition-of-Done gate)
+- [ ] **Step 8: Tell the user what to do next**
 
-Run `/epicmerch-verify` (Deep mode) — the full product→cart→order pipeline against
-the live API; on pass it stamps server-side verification. Do not tell the merchant
-"your store is set up" until this is green. If it fails, route to `/epicmerch-debug`,
-fix, and re-run.
+Print a summary using the actual state of the project:
 
-## Wrap-up
+- List the files you CREATED in this run (skip the ones that were already present).
+- If you skipped any, briefly mention them as "kept as-is".
+- If Step 5b wired up a search bar in an existing component, mention which file you edited and that it now calls `store.products.search()`.
+- If the API key was generated automatically, mention that ".env now has a working VITE_API_KEY — your storefront should load real product data on next refresh."
+- Then output the next-steps block exactly:
 
-Print what was created (skeleton files written vs kept, theme applied, any custom
-pages, verify result), then:
+```
+Next steps:
+1. (API key auto-generated and saved to .env — if not, get one at https://epicmerch.in/dashboard → API Keys)
+2. Restart your dev server (npm run dev) to pick up the .env changes
+3. Import the new components into your App.jsx where you need them
 
-```
-Next:
-1. Restart your dev server (npm run dev) to pick up .env.
-2. Import the components where you need them.
-Need payments, analytics, or a Buy Now button? Just ask.
+Need help with payments, analytics, or notifications? Ask me!
 ```

package/skills/epicmerch.md

@@ -120,13 +120,10 @@ There is no hard "skip" here: `complete` requires a non-empty catalog. If the me
 
 Remember the answer as `visualStyle`.
 
-**4b — Scaffold + style.** Run `/epicmerch-storefront`, passing along the chosen
-`visualStyle`. It runs the tiered flow: it lays the standard skeleton from the
-`store_scaffold_full` tool (instant — no hand-writing), applies the matching Tailwind
-theme pass (or leaves it unstyled on "skip"), confirms the session-restore block, and
-ends on the `/epicmerch-verify` gate. You don't style files here — the leaf skill owns
-the theme pass. Recap what it reports (`✓ Storefront scaffolded + styled (<visualStyle>)`
-or `unstyled`).
+**4b — Scaffold + style.** Run `/epicmerch-storefront`. After it finishes:
+- If `visualStyle` ≠ skip, do a quick styling pass: 5-10 well-chosen Tailwind utility classes per component (typography, spacing, colour) matching `visualStyle`. Don't overdo it.
+- Confirm `src/lib/epicmerch.js` contains the **session-restore block** (the `localStorage.getItem('customerInfo') → setCustomerToken` snippet). Without it, OTP login appears to work but doesn't survive a page reload — the #1 silent storefront bug. The 1.3.4+ scaffold includes it by default; add it manually if missing.
+- Recap `✓ Storefront scaffolded + styled (<visualStyle>)` (or `unstyled`).
 
 **Optional add-on (not gated):** once the storefront exists, you may offer a 1-click Buy Now button — *"Want a 1-click 'Buy Now' button? Razorpay's Magic Checkout lets customers buy without a cart screen."* → `/epicmerch-magic-checkout` (it verifies Razorpay first). This is optional and does NOT affect `complete`; the merchant can add it anytime by saying *"add a Buy Now button"*. Then re-loop.
 

package/src/adapters/mcp.js

@@ -11,6 +11,7 @@ import { developerTools, developerToolDefs } from '../tools/developer.js';
 import { scaffoldTools, scaffoldToolDefs } from '../tools/scaffold.js';
 import { merchantTools, merchantToolDefs } from '../tools/merchant.js';
 import { prompts } from '../prompts/index.js';
+import { VERSION } from '../version.js';
 
 const __dir = dirname(fileURLToPath(import.meta.url));
 const readResource = (rel) => readFileSync(join(__dir, '../resources', rel), 'utf-8');
@@ -27,7 +28,7 @@ function buildZodSchema(schemaDef) {
 }
 
 export async function startMcpAdapter(session, client) {
-  const server = new McpServer({ name: 'epicmerch', version: '1.0.0' });
+  const server = new McpServer({ name: 'epicmerch', version: VERSION });
 
   const allToolDefs = [...sessionToolDefs, ...developerToolDefs, ...scaffoldToolDefs, ...merchantToolDefs];
   const allHandlers = {

package/src/adapters/openapi.js

@@ -6,6 +6,7 @@ import { sessionTools, sessionToolDefs } from '../tools/session.js';
 import { developerTools, developerToolDefs } from '../tools/developer.js';
 import { scaffoldTools, scaffoldToolDefs } from '../tools/scaffold.js';
 import { merchantTools, merchantToolDefs } from '../tools/merchant.js';
+import { VERSION } from '../version.js';
 
 const ALL_TOOL_DEFS = [...sessionToolDefs, ...developerToolDefs, ...scaffoldToolDefs, ...merchantToolDefs];
 
@@ -46,7 +47,7 @@ function buildOpenApiSpec(serverUrl) {
 
   return {
     openapi: '3.1.0',
-    info: { title: 'EpicMerch MCP Tools', version: '1.0.0', description: 'EpicMerch tools for Claude and ChatGPT' },
+    info: { title: 'EpicMerch MCP Tools', version: VERSION, description: 'EpicMerch tools for Claude and ChatGPT' },
     servers: [{ url: serverUrl || 'https://mcp.epicmerch.in' }],
     paths,
     components: {

package/src/version.js

@@ -0,0 +1,13 @@
+// src/version.js
+// Single source of the package version, read from package.json at runtime — so
+// the MCP serverInfo handshake, the OpenAPI spec, etc. always match the published
+// version instead of drifting from a hardcoded literal. Works in local dev, the
+// npm tarball, and the staged .dxt (package.json sits at ../ from src/ in all three).
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+export const VERSION = JSON.parse(
+  readFileSync(join(__dir, '..', 'package.json'), 'utf-8')
+).version;