epicmerch-mcp 1.3.6 → 1.3.12

package/README.md

@@ -156,6 +156,28 @@ merchant_diagnose({})
 
 Returns store name + currency, product/category/out-of-stock counts, payment + logistics configuration status, API key info, a 0-100 readiness score, and a prioritised list of next steps. Use this to drive "what's still missing?" conversations.
 
+## Debugging a broken storefront
+
+Three layers, from quickest to deepest:
+
+| Tool | What it does | When to use |
+|------|--------------|-------------|
+| `merchant_diagnose({})` | Server-side health snapshot (above) | "Is my store set up correctly?" |
+| `/epicmerch-verify` skill | Smoke-tests every read path + validates the checkout payload shape against the live API, WITHOUT sending OTP or charging a card. Ends with a manual Razorpay-test-card recipe. | "Does my site actually load products / will checkout work?" — run after scaffolding |
+| `/epicmerch-debug` skill | Four-check playbook for the most common failures: (1) OTP login that doesn't persist across reloads, (2) products not loading, (3) `INSUFFICIENT_STOCK: undefined` on checkout, (4) cart returning 401. Diagnoses + applies the fix. | "Something's broken and I don't know why" |
+
+The wizard (`/epicmerch`) auto-runs `/epicmerch-verify` as its final step and auto-routes to `/epicmerch-debug` if any check fails — so most issues surface and get fixed before you ever see them.
+
+### Error responses are structured
+
+Every API error returns `{ success: false, code, message, hint?, items? }`.
+Branch on `code` (stable) rather than substring-matching `message` (human-readable, may change). The SDK README has the full code table + rate-limit table. The most useful for debugging:
+
+- `INVALID_ORDER_ITEM` — an `orderItems[]` entry is missing `productId`; the response's `received` field shows exactly what you sent.
+- `INSUFFICIENT_STOCK` — `items[]` lists each shortfall as `{ product, variant, requested, available }`.
+- `PRODUCT_NOT_FOUND` — the `productId` doesn't match any product in this store.
+- `PAYMENT_NOT_CONFIGURED` — no Razorpay keys yet (run `/epicmerch-razorpay`).
+
 ## Shopify migration (MCP tool)
 
 Migrate a Shopify store to EpicMerch in two steps:

package/package.json

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

package/skills/epicmerch-debug.md

@@ -175,6 +175,17 @@ clicking Add to Cart fails. Network shows 401 or 403 on POST `/customer/cart`.
    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.
+4. **Confirm against the live API.** Grab the token from
+   `localStorage.customerInfo.token` and the store's API key, then:
+   ```
+   store_cart_get({ apiKey: "<KEY>", customerToken: "<TOKEN>" })
+   ```
+   - `httpStatus: 200` → the token IS valid; the bug is purely client-side
+     (the SDK isn't restoring it — apply Check 1's fix to src/lib/epicmerch.js).
+   - `httpStatus: 401` → the token is expired or invalid; the customer
+     needs to log in again, or refreshToken() needs wiring.
+   This pins whether the problem is "token bad" vs "SDK not using a good
+   token" — the two have completely different fixes.
 
 **Fix.**
 - If localStorage is empty: merchant needs to log in again.

package/skills/epicmerch-e2e.md

@@ -0,0 +1,203 @@
+---
+name: epicmerch-e2e
+description: Full end-to-end smoke test against the LIVE EpicMerch API — creates a throwaway test product, adds it to a cart, creates an order (exercising stock reservation + Razorpay order creation), verifies every response shape, then cleans everything up. Proves the entire merchant→customer pipeline works without spending money or leaving junk data. The deepest verification available.
+---
+
+# EpicMerch End-to-End Smoke Test
+
+This runs the **complete pipeline** against the live API with real data:
+
+```
+create product → add to cart → get cart → create order → cancel order → delete product
+   (merchant)      (customer)    (customer)   (customer)    (customer)     (merchant)
+```
+
+If every step returns a good response, the whole store genuinely works —
+not just the read paths. Nothing is charged (the order is created UNPAID
+and cancelled), and nothing is left behind (the test product is deleted).
+
+Use this when a merchant wants real confidence ("does checkout actually
+work?"), or after any change to the order/cart/product APIs. It's heavier
+than `/epicmerch-verify` (it writes + deletes data), so it's opt-in.
+
+**Fully automated — no real SMS.** The customer session comes from the
+genuine OTP login flow against the server's configured test phone
+(`E2E_TEST_PHONE`), which skips the actual SMS and seeds a secret code
+(`E2E_TEST_OTP`). So the test exercises the REAL `/auth/otp/send` +
+`/auth/otp/verify` endpoints with zero SMS cost.
+
+## Prerequisites
+
+1. **Merchant MCP session** — you call `merchant_create_product` /
+   `merchant_delete_product` with the merchant's OAuth token (already
+   present if the MCP is connected).
+2. **A store API key** — `merchant_list_api_keys` (or generate a temp one
+   with `merchant_generate_api_key({ name: 'E2E test' })` and delete it
+   after).
+3. **A customer token** — obtained via the real OTP login flow against
+   the configured test phone (the server seeds the code, no SMS sent):
+
+   ```
+   store_auth_send_otp({ apiKey: "<KEY>", phone: "<E2E_TEST_PHONE>" })
+   store_auth_verify_otp({ apiKey: "<KEY>", phone: "<E2E_TEST_PHONE>", otp: "<E2E_TEST_OTP>" })
+   ```
+
+   `store_auth_verify_otp`'s `response.token` is your customer token —
+   call it `<CT>`. This exercises the genuine `/auth/otp/send` +
+   `/auth/otp/verify` endpoints, so it ALSO verifies that login works,
+   not just cart/order. `<E2E_TEST_PHONE>` and `<E2E_TEST_OTP>` are the
+   values the server admin configured in its environment.
+
+   If `store_auth_send_otp` returns a normal SMS channel (not the
+   `e2e-test` channel) it means this server doesn't have the test phone
+   configured — ask the operator to set `E2E_TEST_PHONE` / `E2E_TEST_OTP`,
+   or run `/epicmerch-verify` instead (no token needed).
+
+   Call the customer token `<CT>` and the API key `<KEY>` below.
+
+Confirm payments are configured first: `merchant_get_checkout_settings`.
+If Razorpay isn't set up, the order step will return
+`PAYMENT_NOT_CONFIGURED` — that's still a useful result (route to
+`/epicmerch-razorpay`), but tell the merchant up front.
+
+## The test
+
+Run these steps in order. STOP and report at the first failure — a later
+step depends on the earlier ones. Always run the cleanup steps (5, 6)
+even if an earlier step failed, so you don't leave a test product or a
+stuck reservation behind.
+
+### Step 1 — Create a throwaway test product
+
+```
+merchant_create_product({
+  name: "__E2E_TEST__ (safe to delete)",
+  type: "Test",
+  description: "Automated end-to-end test product. Delete if you see it.",
+  price: 1,
+  stock: 5,
+  variants: [{ variant: "TEST", stock: 5 }],
+  images: ["https://via.placeholder.com/300"]
+})
+```
+
+Grab the new product's `_id` (call it `<PID>`). Price ₹1 + a single
+`TEST` variant keeps it cheap and unambiguous.
+
+> ✓ Step 1 — test product created (`<PID>`)
+
+If the server only creates a placeholder and needs a follow-up update
+(some versions do), chain `merchant_update_product({ id: <PID>, ... })`
+with the same fields, then re-fetch with `merchant_get_product({ id: <PID> })`
+to confirm the variant + stock landed.
+
+### Step 2 — Add it to the cart
+
+```
+store_cart_add({ apiKey: "<KEY>", customerToken: "<CT>", productId: "<PID>", qty: 1, variant: "TEST" })
+```
+
+Expect `httpStatus: 200`, body `{ message: 'Added to cart', cartCount: N }`.
+
+> ✓ Step 2 — added to cart
+
+### Step 3 — Fetch the cart and verify the shape
+
+```
+store_cart_get({ apiKey: "<KEY>", customerToken: "<CT>" })
+```
+
+Confirm `response.cart` contains the test item shaped
+`{ product: { _id: "<PID>", name, price, image, ... }, qty: 1, variant: "TEST" }`.
+This is the authoritative cart shape — if the scaffolded `Cart.jsx`
+reads anything different, FIX the scaffold to match.
+
+> ✓ Step 3 — cart returns the item with the expected shape
+
+### Step 4 — Create the order (the real checkout pipeline)
+
+```
+store_order_create({
+  apiKey: "<KEY>",
+  customerToken: "<CT>",
+  orderItems: [{ productId: "<PID>", name: "__E2E_TEST__ (safe to delete)", image: "https://via.placeholder.com/300", qty: 1, price: 1, variant: "TEST" }],
+  shippingAddress: { fullName: "E2E Test", address: "1 Test St", city: "Mumbai", state: "MH", postalCode: "400001", country: "India", phone: "+919999999999" },
+  paymentMethod: "Razorpay",
+  totalPrice: 1
+})
+```
+
+This exercises the FULL pipeline: stock reservation (SELECT FOR UPDATE),
+order row creation, and Razorpay order creation. **It does not charge** —
+no payment is captured. Confirm `response` contains:
+- `orderId` (the EpicMerch order)
+- `razorpayOrderId` + `razorpayKeyId` + `amount` + `currency` + `merchantName`
+  (if Razorpay is configured)
+
+Grab `response.orderId` as `<OID>`.
+
+If you get `code: INSUFFICIENT_STOCK` here, the variant string in
+orderItems didn't match the cart/product variant — compare against
+Step 3's response. If `code: INVALID_ORDER_ITEM`, the orderItems shape
+is wrong (missing productId). If `code: PAYMENT_NOT_CONFIGURED`, route
+to `/epicmerch-razorpay`.
+
+> ✓ Step 4 — order created (`<OID>`), Razorpay order + key returned
+
+### Step 5 — Cancel the order (cleanup, releases the reservation)
+
+```
+store_order_cancel({ apiKey: "<KEY>", customerToken: "<CT>", orderId: "<OID>" })
+```
+
+This frees the stock reservation immediately (otherwise it'd auto-expire
+in ~15 min).
+
+> ✓ Step 5 — test order cancelled, stock released
+
+### Step 6 — Delete the test product
+
+```
+merchant_delete_product({ id: "<PID>" })
+```
+
+Also remove it from the cart if it lingers:
+`store_cart_remove({ apiKey, customerToken, productId: "<PID>", variant: "TEST" })`.
+
+If you generated a temp API key in prerequisites, delete it too:
+`merchant_delete_api_key({ id: "<temp_key_id>" })`.
+
+> ✓ Step 6 — test product + temp key deleted
+
+## Final report
+
+```
+EpicMerch End-to-End Test — <merchantEmail>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✓ 1. Create product       __E2E_TEST__ (₹1, variant TEST)
+✓ 2. Add to cart          cartCount: 1
+✓ 3. Get cart             shape matches Cart.jsx contract
+✓ 4. Create order         orderId + razorpayOrderId returned (UNPAID)
+✓ 5. Cancel order         reservation released
+✓ 6. Cleanup              product + temp key deleted
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Full pipeline verified. The only thing not exercised is the actual
+Razorpay card capture — test that once in a browser with test card
+4111 1111 1111 1111. Everything up to the charge is confirmed working.
+```
+
+If any step failed, the report should show ✗ on that step with the exact
+error code/message, and the cleanup steps should still have run. Never
+leave a `__E2E_TEST__` product in the merchant's live catalog.
+
+## Safety notes
+
+- The test product is named `__E2E_TEST__ (safe to delete)` so it's
+  obvious in the dashboard if cleanup ever fails.
+- Price ₹1 + stock 5 keeps it harmless even if a real customer somehow
+  saw it during the brief window it exists.
+- The order is never paid, so no money moves and no real fulfilment is
+  triggered.
+- Always cancel the order AND delete the product, even on partial
+  failure — orphaned reservations hold stock, orphaned test products
+  clutter the catalog.

package/skills/epicmerch-verify.md

@@ -105,6 +105,59 @@ merchant_delete_api_key({ id: "<temp_key_id>" })
 
 ---
 
+## Phase 2.5 — Live cart round-trip (the authoritative cart-shape check)
+
+**This is the most reliable way to get the cart contract right.** Instead
+of trusting docs or controller reads, actually add an item to a cart and
+fetch it back through the MCP, then read the REAL response shape. The
+scaffolded `Cart.jsx` must parse exactly what comes back here.
+
+This needs a **customer token** (a JWT from a storefront login), which
+costs one OTP. If the merchant can provide one, do this — it's worth it.
+If not, skip to Phase 3 (the structural check) and note the cart shape
+wasn't verified against a live session.
+
+Ask:
+
+> "To verify the cart end-to-end I need a customer token. Open your
+> storefront, log in once, then in DevTools → Application → Local Storage
+> copy the `token` value from `customerInfo`. Paste it here — or say
+> 'skip' and I'll validate the shape structurally instead."
+
+If they provide a token (call it `<CUSTOMER_TOKEN>`) and you have an API
+key from Phase 2 (`<KEY>`) plus a product id (`<FIRST_PRODUCT_ID>`) with
+an in-stock variant (`<VARIANT>`):
+
+1. **Add to cart:**
+   ```
+   store_cart_add({ apiKey: "<KEY>", customerToken: "<CUSTOMER_TOKEN>", productId: "<FIRST_PRODUCT_ID>", qty: 1, variant: "<VARIANT>" })
+   ```
+   Expect `httpStatus: 200` and a body like `{ message: 'Added to cart', cartCount: N }`. If you get 401 → the token is expired/wrong. If 404 → the productId is wrong.
+
+2. **Fetch the cart:**
+   ```
+   store_cart_get({ apiKey: "<KEY>", customerToken: "<CUSTOMER_TOKEN>" })
+   ```
+   Read `response.cart`. This is the AUTHORITATIVE shape. Confirm each line item is `{ product: { _id, name, price, originalPrice, salePrice, image, type }, qty, variant }`.
+
+3. **Cross-check against the scaffold.** Open the project's
+   `src/components/Cart.jsx` and confirm it reads:
+   - `cart.cart` (the array) — NOT `cart.items`
+   - `item.product._id`, `item.product.name`, `item.product.image`
+   - `item.product.salePrice ?? item.product.price`
+   - `item.variant`
+   If the scaffold reads anything the live response doesn't have, FIX the
+   scaffold to match the live shape — the live response wins, always.
+
+4. **Clean up** so you don't leave a junk item in the cart:
+   ```
+   store_cart_remove({ apiKey: "<KEY>", customerToken: "<CUSTOMER_TOKEN>", productId: "<FIRST_PRODUCT_ID>", variant: "<VARIANT>" })
+   ```
+
+Report: `✓ Live cart round-trip — add → get → shape matches Cart.jsx → cleaned up`.
+
+---
+
 ## Phase 3 — Checkout payload shape check (no actual order created)
 
 This catches the contract bugs that have historically caused live `INSUFFICIENT_STOCK: undefined` or `IDEMPOTENCY_KEY_MISMATCH` failures. We BUILD the orderItems payload that the scaffolded `Checkout.jsx` would build, then validate its shape against the API contract — without actually calling `orders.create`.

package/skills/epicmerch.md

@@ -197,6 +197,7 @@ The merchant said something specific. Match against the table below, pick the cl
 | "show me my store / products / orders / sales", "manage my store from chat" | `/epicmerch-merchant` (first-time) or `/epicmerch-merchant-agent` (ongoing) |
 | "migrate from Shopify", "import my Shopify catalog" | `/epicmerch-migrate` |
 | "my login isn't sticking", "products aren't loading", "checkout fails", "insufficient stock undefined", "something's broken" | `/epicmerch-debug` |
+| "test everything", "does checkout actually work", "full end-to-end test", "run a real order test" | `/epicmerch-e2e` |
 
 ### Hand-off (or inline)
 

package/src/prompts/index.js

@@ -218,6 +218,19 @@ export const prompts = [
   },
 
   // ─── Verification ──────────────────────────────────────────────────────
+  {
+    name: 'epicmerch-e2e',
+    description: 'Full end-to-end smoke test against the LIVE API — creates a throwaway test product, adds it to a cart, creates an order (exercises stock reservation + Razorpay order creation), verifies every response, then deletes the product + cancels the order. Proves the entire merchant→customer pipeline works without charging money or leaving junk data. Deeper than /epicmerch-verify; needs a customer token (one OTP).',
+    handler: async () => ({
+      messages: [{
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `Run the full EpicMerch end-to-end smoke test. Fetch https://api.epicmerch.in/api/skills/epicmerch-e2e.md if needed and follow every step: get a customer token via the real OTP login flow against the configured test phone (store_auth_send_otp + store_auth_verify_otp with E2E_TEST_PHONE / E2E_TEST_OTP — no SMS sent), create a throwaway test product (merchant_create_product), add it to cart (store_cart_add), get the cart and verify the shape (store_cart_get), create the order (store_order_create — exercises stock reservation + Razorpay order, does NOT charge), then ALWAYS clean up — cancel the order (store_order_cancel) and delete the test product (merchant_delete_product). Print the consolidated checklist at the end.`,
+        },
+      }],
+    }),
+  },
   {
     name: 'epicmerch-verify',
     description: 'Smoke-test every storefront API the merchant\'s site loads — confirms products / categories / search / single product / checkout payload shape all work against the live server, BEFORE a real customer hits a 422 at checkout. Skips OTP (costs money) and real Razorpay charges (covers with a manual test-card recipe).',

package/src/tools/developer.js

@@ -7,6 +7,34 @@ const __dir = dirname(fileURLToPath(import.meta.url));
 const readExample = (name) =>
   readFileSync(join(__dir, '../resources/examples', `${name}.md`), 'utf-8');
 
+// Base URL for direct customer-scoped calls (cart/order). These endpoints
+// need BOTH the store's x-api-key (identifies the merchant/tenant) AND a
+// customer JWT (identifies the shopper) — a different auth combo than the
+// MCP merchant session carries — so the cart tools below take those
+// explicitly and make a raw fetch. This hits the live endpoint EXACTLY as
+// the storefront does, so the response shape they return is the real,
+// authoritative one the scaffolded Cart.jsx / Checkout.jsx must match.
+const API_BASE = (process.env.EPICMERCH_API_URL || 'https://api.epicmerch.in/api').replace(/\/$/, '');
+
+async function customerCartFetch(path, { apiKey, customerToken, method = 'GET', body } = {}) {
+  const headers = { 'Content-Type': 'application/json' };
+  if (apiKey) headers['x-api-key'] = apiKey;
+  if (customerToken) headers['Authorization'] = `Bearer ${customerToken}`;
+  const res = await fetch(`${API_BASE}${path}`, {
+    method,
+    headers,
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  });
+  let parsed = null;
+  try { parsed = await res.json(); } catch (_) { /* non-JSON body */ }
+  // Return BOTH the HTTP status and the parsed body so the assistant can
+  // see exactly what the storefront would receive — status code AND shape.
+  return { httpStatus: res.status, ok: res.ok, response: parsed };
+}
+
+const CUSTOMER_TOKEN_HELP =
+  'Get a customer token from your storefront: log in once (one OTP), then in DevTools → Application → Local Storage read `customerInfo` and copy its `.token` value.';
+
 export function developerTools(client) {
   return {
     async store_get_config(_args) {
@@ -14,6 +42,97 @@ export function developerTools(client) {
       return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     },
 
+    // ── Live cart verification ──────────────────────────────────────────
+    // Use these to STOP GUESSING the cart contract. Add an item, fetch the
+    // cart, and read the real `response.cart` shape — then write Cart.jsx /
+    // Checkout.jsx to match it exactly. Returns { httpStatus, ok, response }.
+
+    async store_cart_add({ apiKey, customerToken, productId, qty = 1, variant } = {}) {
+      if (!apiKey || !customerToken || !productId) {
+        return { isError: true, content: [{ type: 'text', text: `store_cart_add needs apiKey + customerToken + productId. ${CUSTOMER_TOKEN_HELP}` }] };
+      }
+      const body = { productId, qty };
+      if (variant) body.variant = variant;
+      const result = await customerCartFetch('/customer/cart', { apiKey, customerToken, method: 'POST', body });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    },
+
+    async store_cart_get({ apiKey, customerToken } = {}) {
+      if (!apiKey || !customerToken) {
+        return { isError: true, content: [{ type: 'text', text: `store_cart_get needs apiKey + customerToken. ${CUSTOMER_TOKEN_HELP}` }] };
+      }
+      const result = await customerCartFetch('/customer/cart', { apiKey, customerToken });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    },
+
+    async store_cart_remove({ apiKey, customerToken, productId, variant } = {}) {
+      if (!apiKey || !customerToken || !productId) {
+        return { isError: true, content: [{ type: 'text', text: `store_cart_remove needs apiKey + customerToken + productId. ${CUSTOMER_TOKEN_HELP}` }] };
+      }
+      const qs = variant ? `?variant=${encodeURIComponent(variant)}` : '';
+      const result = await customerCartFetch(`/customer/cart/${productId}${qs}`, { apiKey, customerToken, method: 'DELETE' });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    },
+
+    // ── Live OTP login (for exercising the REAL auth flow) ──────────────
+    // These hit /auth/otp/send + /auth/otp/verify exactly as the storefront
+    // Login.jsx does. Pair with the server's env-gated E2E_TEST_PHONE bypass
+    // to get a customer token through the genuine login path (no SMS cost)
+    // — catches login-flow bugs that merchant_create_test_session skips.
+
+    async store_auth_send_otp({ apiKey, phone } = {}) {
+      if (!apiKey || !phone) {
+        return { isError: true, content: [{ type: 'text', text: 'store_auth_send_otp needs apiKey + phone. For automated tests, use the server-configured E2E_TEST_PHONE so no real SMS is sent.' }] };
+      }
+      const result = await customerCartFetch('/auth/otp/send', { apiKey, method: 'POST', body: { phone } });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    },
+
+    async store_auth_verify_otp({ apiKey, phone, otp, profile = {} } = {}) {
+      if (!apiKey || !phone || !otp) {
+        return { isError: true, content: [{ type: 'text', text: 'store_auth_verify_otp needs apiKey + phone + otp. Returns { token, user } on success — that token is the customer JWT for cart/order calls.' }] };
+      }
+      const result = await customerCartFetch('/auth/otp/verify', { apiKey, method: 'POST', body: { phone, otp, profile } });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    },
+
+    // ── Live order verification ─────────────────────────────────────────
+    // store_order_create exercises the FULL checkout pipeline against the
+    // live API: stock reservation + order row + Razorpay order creation.
+    // It does NOT charge — the Razorpay order is created but no payment is
+    // captured (that needs the hosted widget + a real card). So the order
+    // sits UNPAID; its stock reservation expires automatically, or you can
+    // release it immediately with store_order_cancel. Use this to confirm
+    // the orders.create response shape (razorpayOrderId/razorpayKeyId/
+    // amount/currency/merchantName) end-to-end without spending a rupee.
+
+    async store_order_create({ apiKey, customerToken, orderItems, shippingAddress, paymentMethod = 'Razorpay', totalPrice } = {}) {
+      if (!apiKey || !customerToken || !Array.isArray(orderItems) || orderItems.length === 0) {
+        return { isError: true, content: [{ type: 'text', text: `store_order_create needs apiKey + customerToken + a non-empty orderItems array. Each item: { productId, name, image, qty, price, variant }. ${CUSTOMER_TOKEN_HELP}` }] };
+      }
+      const body = { orderItems, shippingAddress, paymentMethod, totalPrice };
+      const result = await customerCartFetch('/customer/orders', { apiKey, customerToken, method: 'POST', body });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    },
+
+    async store_order_get({ apiKey, customerToken, orderId } = {}) {
+      if (!apiKey || !customerToken || !orderId) {
+        return { isError: true, content: [{ type: 'text', text: `store_order_get needs apiKey + customerToken + orderId. ${CUSTOMER_TOKEN_HELP}` }] };
+      }
+      const result = await customerCartFetch(`/customer/orders/${orderId}`, { apiKey, customerToken });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    },
+
+    async store_order_cancel({ apiKey, customerToken, orderId } = {}) {
+      if (!apiKey || !customerToken || !orderId) {
+        return { isError: true, content: [{ type: 'text', text: `store_order_cancel needs apiKey + customerToken + orderId. ${CUSTOMER_TOKEN_HELP}` }] };
+      }
+      // PUT /customer/orders/:id/cancel — releases the stock reservation
+      // on an unpaid order. Use this to clean up after an E2E test order.
+      const result = await customerCartFetch(`/customer/orders/${orderId}/cancel`, { apiKey, customerToken, method: 'PUT' });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    },
+
     async store_list_products({ category, keyword, sort, page, limit } = {}) {
       const p = new URLSearchParams();
       if (category) p.set('type', category);
@@ -62,4 +181,12 @@ export const developerToolDefs = [
   { name: 'store_search_products', description: 'Search products by keyword.', schema: { query: { type: 'string' }, category: { type: 'string' }, page: { type: 'number' }, limit: { type: 'number' } } },
   { name: 'store_list_categories', description: 'List all visible product categories.', schema: {} },
   { name: 'store_get_integration_guide', description: 'Get code examples for integrating a specific EpicMerch module. module: auth | products | orders | payments', schema: { module: { type: 'string' } } },
+  { name: 'store_cart_add', description: 'Add an item to a customer cart on the LIVE store, to verify the real cart contract before writing Cart.jsx/Checkout.jsx. Returns { httpStatus, ok, response }. Requires apiKey (store public key) + customerToken (a customer JWT from a storefront login — localStorage.customerInfo.token) + productId (+ optional qty, variant). Pair with store_cart_get to see how the added item comes back.', schema: { apiKey: { type: 'string' }, customerToken: { type: 'string' }, productId: { type: 'string' }, qty: { type: 'number' }, variant: { type: 'string' } } },
+  { name: 'store_cart_get', description: 'Fetch a customer cart from the LIVE store. Returns { httpStatus, ok, response }. Inspect response.cart to read the EXACT line-item shape your Cart.jsx must parse — { product: { _id, name, price, originalPrice, salePrice, image, type }, qty, variant }. Stops you guessing the shape from docs. Requires apiKey + customerToken.', schema: { apiKey: { type: 'string' }, customerToken: { type: 'string' } } },
+  { name: 'store_cart_remove', description: 'Remove an item from a customer cart on the LIVE store (clean up after a verification add). Requires apiKey + customerToken + productId (+ optional variant to disambiguate sizes).', schema: { apiKey: { type: 'string' }, customerToken: { type: 'string' }, productId: { type: 'string' }, variant: { type: 'string' } } },
+  { name: 'store_auth_send_otp', description: 'Send an OTP via the LIVE store auth flow (POST /auth/otp/send) — exercises the REAL login path. For automated tests, use a phone configured as the server\'s E2E_TEST_PHONE so no real SMS is sent (the server seeds the test code instead). Requires apiKey + phone.', schema: { apiKey: { type: 'string' }, phone: { type: 'string' } } },
+  { name: 'store_auth_verify_otp', description: 'Verify an OTP via the LIVE store auth flow (POST /auth/otp/verify) and get a customer token. Returns { httpStatus, ok, response } where response.token is the customer JWT to use with store_cart_* / store_order_*. With the E2E_TEST_PHONE bypass, pass the configured E2E_TEST_OTP. Requires apiKey + phone + otp.', schema: { apiKey: { type: 'string' }, phone: { type: 'string' }, otp: { type: 'string' }, profile: { type: 'object' } } },
+  { name: 'store_order_create', description: 'Create an order on the LIVE store to verify the full checkout pipeline (stock reservation + order + Razorpay order creation). Does NOT charge — the order is UNPAID and its reservation auto-expires (or cancel it with store_order_cancel). Returns { httpStatus, ok, response } — confirm response has orderId, razorpayOrderId, razorpayKeyId, amount, currency, merchantName. Requires apiKey + customerToken + orderItems [{ productId, name, image, qty, price, variant }] + shippingAddress + totalPrice.', schema: { apiKey: { type: 'string' }, customerToken: { type: 'string' }, orderItems: { type: 'array' }, shippingAddress: { type: 'object' }, paymentMethod: { type: 'string' }, totalPrice: { type: 'number' } } },
+  { name: 'store_order_get', description: 'Fetch a customer order by id from the LIVE store. Returns { httpStatus, ok, response }. Requires apiKey + customerToken + orderId.', schema: { apiKey: { type: 'string' }, customerToken: { type: 'string' }, orderId: { type: 'string' } } },
+  { name: 'store_order_cancel', description: 'Cancel an unpaid order on the LIVE store — releases its stock reservation. Use to clean up after an E2E test order. Requires apiKey + customerToken + orderId.', schema: { apiKey: { type: 'string' }, customerToken: { type: 'string' }, orderId: { type: 'string' } } },
 ];

package/src/tools/merchant.js

@@ -426,10 +426,24 @@ export function merchantTools(client, session) {
         hasLogo:   Boolean(profile?.logo ?? profile?.user?.logo),
       } : { error: profileR.error };
 
+      // Total available stock for a product. The Prisma API returns `stock`
+      // (NOT the legacy Mongo field `countInStock` — reading that made EVERY
+      // product look out-of-stock). For products with variants, the true
+      // availability is the sum of per-variant stock; the server derives
+      // `stock` from that on write, but we sum defensively in case the
+      // top-level value is stale. Falls back to countInStock only for very
+      // old API shapes.
+      const productStock = (p) => {
+        if (Array.isArray(p.variants) && p.variants.length > 0) {
+          return p.variants.reduce((sum, v) => sum + (Number(v.stock) || 0), 0);
+        }
+        return Number(p.stock ?? p.countInStock ?? 0) || 0;
+      };
+
       const catalog = productsR.ok && categoriesR.ok ? {
         productCount:    products.length,
         categoryCount:   cats.length,
-        outOfStockCount: products.filter((p) => (p.countInStock ?? 0) === 0).length,
+        outOfStockCount: products.filter((p) => productStock(p) === 0).length,
       } : { error: (productsR.error || categoriesR.error) };
 
       const payment = checkoutR.ok ? {