epicmerch-mcp 1.3.2 → 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.2",
+  "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-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,228 @@
+---
+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.
+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.
+- 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-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-orders.md

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

package/skills/epicmerch-products.md

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