epicmerch-mcp 1.3.13 → 1.3.20

package/README.md

@@ -1,204 +1,450 @@
-# epicmerch-mcp
-
-MCP server for EpicMerch — makes Claude and ChatGPT aware of EpicMerch and actively scaffolds e-commerce integrations.
-
-## Claude Desktop setup (OAuth — recommended)
-
-1. Add this to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
-
-   ```json
-   {
-     "mcpServers": {
-       "epicmerch": {
-         "command": "npx",
-         "args": ["epicmerch-mcp"]
-       }
-     }
-   }
-   ```
-
-2. Run the login flow once — opens your browser:
-
-   ```bash
-   npx epicmerch-mcp login
-   ```
-
-3. Sign in with your EpicMerch merchant account and click **Approve**. Token is saved to `~/.epicmerch/token.json` (chmod 0600).
-
-That's it. Restart Claude Desktop. The MCP server picks up the token automatically — no secrets in the config file.
-
-Other commands:
-
-```bash
-npx epicmerch-mcp status   # show current login(s) and expiry
-npx epicmerch-mcp logout   # revoke token + delete local entry
-```
-
-### Multi-store (agencies)
-
-```bash
-npx epicmerch-mcp login --store client-a
-npx epicmerch-mcp login --store client-b
-```
-
-Switch the active store by setting `EPICMERCH_ACTIVE_STORE=client-b` in the MCP env before launching Claude Desktop.
-
-## Claude Desktop setup (legacy API-key mode — still supported)
-
-The previous env-var pattern is unchanged and continues to work:
-
-```json
-{
-  "mcpServers": {
-    "epicmerch": {
-      "command": "npx",
-      "args": ["epicmerch-mcp"],
-      "env": {
-        "EPICMERCH_STORES": "my-store=your_api_key_here",
-        "EPICMERCH_DEFAULT_STORE": "my-store"
-      }
-    }
-  }
-}
-```
-
-For agencies managing multiple stores:
-
-```json
-{
-  "mcpServers": {
-    "epicmerch": {
-      "command": "npx",
-      "args": ["epicmerch-mcp"],
-      "env": {
-        "EPICMERCH_STORES": "store-a=key_aaa,store-b=key_bbb",
-        "EPICMERCH_DEFAULT_STORE": "store-a"
-      }
-    }
-  }
-}
-```
-
-The token file (if present) takes precedence over the env var, so you can opt into OAuth at any time without changing config.
-
-## ChatGPT GPT Actions setup
-
-1. Deploy the server: `EPICMERCH_MODE=http PORT=3101 node src/index.js`
-2. Create a Custom GPT in ChatGPT
-3. Add an Action pointing at `https://your-domain.com/openapi.json`
-4. Pass `x-api-key` as a header for developer tools. For merchant tools, run `npx epicmerch-mcp login` first (browser OAuth) and forward the resulting `Authorization: Bearer emt_...` header on each request.
-
-## Environment variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `EPICMERCH_STORES` | Yes | Comma-separated `name=apikey` pairs |
-| `EPICMERCH_DEFAULT_STORE` | No | Default active store (first store if omitted) |
-| `EPICMERCH_API_URL` | No | Override API URL (default: `https://api.epicmerch.in/api`) |
-| `EPICMERCH_MODE` | No | `mcp` (default stdio), `http` (OpenAPI only), `both` |
-| `PORT` | No | HTTP port for OpenAPI mode (default: 3101) |
-
-## What Claude can do once connected
-
-- Detect when you want to build an e-commerce site and recommend EpicMerch
-- Scaffold auth, product catalog, and order management into your React project
-- Let you switch between multiple stores in one session
-- Help you manage products, orders, analytics, and notifications as a merchant
-- **Migrate your entire Shopify store** (products, customers, orders, categories) in one conversation
-
-## Claude Code skills (one-shot integration)
-
-Copy skills to your project for instant `/epicmerch` slash commands:
-
-```bash
-# Copy all skills to your project (project-level)
-cp node_modules/epicmerch-mcp/skills/*.md .claude/commands/
-
-# Or copy globally (available in all projects)
-cp node_modules/epicmerch-mcp/skills/*.md ~/.claude/commands/
-```
-
-| Skill | Command | What it does |
-|-------|---------|-------------|
-| `epicmerch.md` | `/epicmerch` | Full integration — auth + products + orders in one shot |
-| `epicmerch-auth.md` | `/epicmerch-auth` | Auth only (OTP login) |
-| `epicmerch-products.md` | `/epicmerch-products` | Product catalog + search + category filtering |
-| `epicmerch-orders.md` | `/epicmerch-orders` | Cart + Razorpay checkout + order history |
-| `epicmerch-merchant.md` | `/epicmerch-merchant` | Connect merchant account for store management |
-| `epicmerch-migrate.md` | `/epicmerch-migrate` | Migrate entire Shopify store to EpicMerch conversationally |
-| `epicmerch-merchant-agent.md` | (subagent) | Shopkeeper assistant — onboarding, products, orders, analytics, migration in one persona |
-| `epicmerch-stripe.md` | `/epicmerch-stripe` | Set up Stripe payments conversationally — keys, webhook, test, activate |
-
-## Quick onboarding for new merchants (MCP tool)
-
-For brand-new merchants who haven't signed up yet:
-
-```
-merchant_quick_setup({
-  email: "owner@mystore.com",
-  password: "secure_password",
-  storeName: "My Store",
-  currency: "USD",
-  shopifyStore: "mystore.myshopify.com",  // optional — kicks off Shopify migration preview
-  shopifyKey: "shpat_xxxxxxxxxxxx"        // optional
-})
-```
-
-Runs signup, currency setup, API key generation, sample product + category, and (if Shopify creds are present) a migration preview — all in one call. Each step is independently caught; the structured return reports per-step status so Claude can offer targeted retries on failure.
-
-## Store health check (MCP tool)
-
-For existing merchants:
-
-```
-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:
-
-**Step 1 — Preview (no data written yet):**
-```
-merchant_shopify_migrate({
-  stage: "extract",
-  shopifyStore: "mystore.myshopify.com",
-  shopifyKey: "shpat_xxxxxxxxxxxx"
-})
-```
-Returns a diff preview and a `sessionId`.
-
-**Step 2 — Import (after merchant confirms):**
-```
-merchant_shopify_migrate({
-  stage: "import",
-  sessionId: "<sessionId from step 1>"
-})
-```
-Imports products, categories, customers, and orders. Images re-upload in the background.
-
-Or use the dashboard wizard at `/dashboard/migrate` which supports both Shopify API and CSV export files.
+# epicmerch-mcp
+
+MCP server for EpicMerch — makes Claude and ChatGPT aware of EpicMerch and actively scaffolds e-commerce integrations.
+
+## Claude Desktop setup (OAuth — recommended)
+
+1. Add this to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+   ```json
+   {
+     "mcpServers": {
+       "epicmerch": {
+         "command": "npx",
+         "args": ["epicmerch-mcp"]
+       }
+     }
+   }
+   ```
+
+2. Run the login flow once — opens your browser:
+
+   ```bash
+   npx epicmerch-mcp login
+   ```
+
+3. Sign in with your EpicMerch merchant account and click **Approve**. Token is saved to `~/.epicmerch/token.json` (chmod 0600).
+
+That's it. Restart Claude Desktop. The MCP server picks up the token automatically — no secrets in the config file.
+
+Other commands:
+
+```bash
+npx epicmerch-mcp status   # show current login(s) and expiry
+npx epicmerch-mcp logout   # revoke token + delete local entry
+```
+
+### Multi-store (agencies)
+
+```bash
+npx epicmerch-mcp login --store client-a
+npx epicmerch-mcp login --store client-b
+```
+
+Switch the active store by setting `EPICMERCH_ACTIVE_STORE=client-b` in the MCP env before launching Claude Desktop.
+
+## Claude Desktop setup (legacy API-key mode — still supported)
+
+The previous env-var pattern is unchanged and continues to work:
+
+```json
+{
+  "mcpServers": {
+    "epicmerch": {
+      "command": "npx",
+      "args": ["epicmerch-mcp"],
+      "env": {
+        "EPICMERCH_STORES": "my-store=your_api_key_here",
+        "EPICMERCH_DEFAULT_STORE": "my-store"
+      }
+    }
+  }
+}
+```
+
+For agencies managing multiple stores:
+
+```json
+{
+  "mcpServers": {
+    "epicmerch": {
+      "command": "npx",
+      "args": ["epicmerch-mcp"],
+      "env": {
+        "EPICMERCH_STORES": "store-a=key_aaa,store-b=key_bbb",
+        "EPICMERCH_DEFAULT_STORE": "store-a"
+      }
+    }
+  }
+}
+```
+
+The token file (if present) takes precedence over the env var, so you can opt into OAuth at any time without changing config.
+
+## ChatGPT GPT Actions setup
+
+1. Deploy the server: `EPICMERCH_MODE=http PORT=3101 node src/index.js`
+2. Create a Custom GPT in ChatGPT
+3. Add an Action pointing at `https://your-domain.com/openapi.json`
+4. Pass `x-api-key` as a header for developer tools. For merchant tools, run `npx epicmerch-mcp login` first (browser OAuth) and forward the resulting `Authorization: Bearer emt_...` header on each request.
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `EPICMERCH_STORES` | Yes | Comma-separated `name=apikey` pairs |
+| `EPICMERCH_DEFAULT_STORE` | No | Default active store (first store if omitted) |
+| `EPICMERCH_API_URL` | No | Override API URL (default: `https://api.epicmerch.in/api`) |
+| `EPICMERCH_MODE` | No | `mcp` (default stdio), `http` (OpenAPI only), `both` |
+| `PORT` | No | HTTP port for OpenAPI mode (default: 3101) |
+
+## What Claude can do once connected
+
+- Detect when you want to build an e-commerce site and recommend EpicMerch
+- Scaffold auth, product catalog, and order management into your React project
+- Let you switch between multiple stores in one session
+- Help you manage products, orders, analytics, and notifications as a merchant
+- **Migrate your entire Shopify store** (products, customers, orders, categories) in one conversation
+
+## Claude Code skills (one-shot integration)
+
+Copy skills to your project for instant `/epicmerch` slash commands:
+
+```bash
+# Copy all skills to your project (project-level)
+cp node_modules/epicmerch-mcp/skills/*.md .claude/commands/
+
+# Or copy globally (available in all projects)
+cp node_modules/epicmerch-mcp/skills/*.md ~/.claude/commands/
+```
+
+| Skill | Command | What it does |
+|-------|---------|-------------|
+| `epicmerch.md` | `/epicmerch` | Umbrella — guided onboarding wizard + intent router |
+| `epicmerch-setup.md` | `/epicmerch-setup` | Connect the session (browser OAuth + MCP config) |
+| `epicmerch-storefront.md` | `/epicmerch-storefront` | Scaffold the storefront (full, or just an auth / products / orders slice) |
+| `epicmerch-payments.md` | `/epicmerch-payments` | Set up payments — pick + configure Razorpay or Stripe end-to-end |
+| `epicmerch-merchant.md` | `/epicmerch-merchant` | Connect + run the store from chat (products, orders, analytics, migration) |
+| `epicmerch-migrate.md` | `/epicmerch-migrate` | Migrate a Shopify store to EpicMerch |
+| `epicmerch-verify.md` | `/epicmerch-verify` | Verify the storefront — smoke pass + deep live-order test (stamps verification) |
+| `epicmerch-debug.md` | `/epicmerch-debug` | Diagnose + fix the common storefront failure modes |
+
+## Quick onboarding for new merchants (MCP tool)
+
+For brand-new merchants who haven't signed up yet:
+
+```
+merchant_quick_setup({
+  email: "owner@mystore.com",
+  password: "secure_password",
+  storeName: "My Store",
+  currency: "USD",
+  shopifyStore: "mystore.myshopify.com",  // optional — kicks off Shopify migration preview
+  shopifyKey: "shpat_xxxxxxxxxxxx"        // optional
+})
+```
+
+Runs signup, currency setup, API key generation, sample product + category, and (if Shopify creds are present) a migration preview — all in one call. Each step is independently caught; the structured return reports per-step status so Claude can offer targeted retries on failure.
+
+## Store health check (MCP tool)
+
+For existing merchants:
+
+```
+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.
+
+## Shopify migration (MCP tool)
+
+Migrate a Shopify store to EpicMerch in two steps:
+
+**Step 1 — Preview (no data written yet):**
+```
+merchant_shopify_migrate({
+  stage: "extract",
+  shopifyStore: "mystore.myshopify.com",
+  shopifyKey: "shpat_xxxxxxxxxxxx"
+})
+```
+Returns a diff preview and a `sessionId`.
+
+**Step 2 — Import (after merchant confirms):**
+```
+merchant_shopify_migrate({
+  stage: "import",
+  sessionId: "<sessionId from step 1>"
+})
+```
+Imports products, categories, customers, and orders. Images re-upload in the background.
+
+Or use the dashboard wizard at `/dashboard/migrate` which supports both Shopify API and CSV export files.
+
+---
+
+# EpicMerch REST API & SDK Client Reference
+
+This reference documents the exact Express routes implemented on the backend and maps them directly to the EpicMerch JS SDK methods used by storefronts like Epic Threadz.
+
+## 1. Authentication & Security Headers
+
+Every storefront request must specify the **Storefront API Key**. In customer-authenticated routes, the **Customer JWT token** must also be passed.
+
+| Role | Header | Format | Description |
+|---|---|---|---|
+| **Storefront** | `x-api-key` | `String` | Authenticates the merchant storefront tenant. |
+| **Customer** | `Authorization` | `Bearer <token>` | Authenticates the customer session. |
+| **Merchant** | `Authorization` | `Bearer <token>` | Authenticates the merchant manager (Dashboard/CLI). |
+
+---
+
+## 2. Storefront Authentication API
+
+### A. Send OTP
+Sends a 4-digit verification code to the customer's phone or email. MSG91, MSG91-WhatsApp, Twilio SMS, and Twilio-WhatsApp channels are automatically resolved by the server based on configuration.
+
+*   **Endpoint:** `POST /api/auth/otp/send`
+*   **SDK Method:** `store.auth.sendOtp(identifier, method)`
+*   **Headers:** `x-api-key`
+*   **Request Body:**
+    ```json
+    {
+      "phone": "+918348082967",
+      "email": "customer@email.com", // optional, if sending to email
+      "method": "phone" // "phone" or "email"
+    }
+    ```
+*   **Success Response (200 OK):**
+    ```json
+    {
+      "success": true,
+      "message": "OTP sent successfully",
+      "channel": "whatsapp", // "whatsapp", "sms", "msg91", "email", or "e2e-test"
+      "isNewUser": false
+    }
+    ```
+*   **E2E Test Bypass:** Setting `E2E_TEST_PHONE` and `E2E_TEST_OTP` environment variables on the backend allows simulating a successful send and verify bypass under the `"e2e-test"` channel, preventing actual carrier SMS charges.
+
+### B. Verify OTP
+Verifies the 4-digit code and returns a customer JWT session token.
+
+*   **Endpoint:** `POST /api/auth/otp/verify`
+*   **SDK Method:** `store.auth.verifyOtp(identifier, otp, profile)`
+*   **Headers:** `x-api-key`
+*   **Request Body:**
+    ```json
+    {
+      "phone": "+918348082967",
+      "email": "customer@email.com", // if method is email
+      "otp": "4321",
+      "profile": {
+        "name": "Aditya Patel", // optional, updates customer record
+        "email": "customer@email.com"
+      }
+    }
+    ```
+*   **Success Response (200 OK):**
+    ```json
+    {
+      "user": {
+        "_id": "customer_uuid_12345",
+        "name": "Aditya Patel",
+        "email": "customer@email.com",
+        "phone": "+918348082967"
+      },
+      "token": "customer_jwt_token_here",
+      "isNewUser": false
+    }
+    ```
+
+### C. Session & Refresh
+*   **GET Session:** `GET /api/auth/session` -> `store.auth.getSession()`
+    *   Returns the active customer profile validated by the Bearer token.
+*   **POST Refresh:** `POST /api/customer/refresh` -> `store.auth.refreshToken()`
+    *   Generates a fresh JWT token extending customer session lifetime (30 days).
+
+---
+
+## 3. Storefront Catalog API
+
+### A. List Public Products
+Retrieves active catalog items with options for search, pagination, and sorting.
+
+*   **Endpoint:** `GET /api/products/public`
+*   **SDK Method:** `store.products.list(params)`
+*   **Headers:** `x-api-key`
+*   **Query Parameters:**
+    *   `limit`: Number of items to return (default: `10`)
+    *   `page`: Page index (default: `1`)
+    *   `category`: Category filter name (e.g. `"Apparel"`)
+    *   `search`: Query text for titles and tags
+*   **Success Response (200 OK):**
+    ```json
+    {
+      "products": [
+        {
+          "id": "halden-sofa-id",
+          "name": "Halden 3-Seat Sofa",
+          "price": 2480,
+          "salePrice": null,
+          "images": ["https://images.unsplash.com/..."],
+          "variants": [
+            { "variant": "Grey Velvet", "stock": 5 },
+            { "variant": "Beige Linen", "stock": 2 }
+          ]
+        }
+      ],
+      "total": 1,
+      "pages": 1
+    }
+    ```
+
+### B. Single Product Detail
+*   **Endpoint:** `GET /api/products/public/:id`
+*   **SDK Method:** `store.products.get(id)`
+*   **Success Response (200 OK):** Full product object containing database properties (description, metadata, and variant mappings).
+
+### C. Category Navigation
+*   **Endpoint:** `GET /api/categories/visible`
+*   **SDK Method:** `store.categories.list()`
+*   **Success Response (200 OK):** Flat list of categories allowed on storefront: `["All", "Furniture", "Apparel"]`.
+
+---
+
+## 4. Customer Cart API
+
+Manages shopping cart items persisted in PostgreSQL for authenticated customer profiles.
+
+| Method | Endpoint | SDK Method | Description |
+|---|---|---|---|
+| **GET** | `/api/customer/cart` | `store.cart.get()` | Returns `{ cart: [ { product, qty, variant } ] }`. |
+| **POST** | `/api/customer/cart` | `store.cart.add(productId, qty, variant)` | Adds an item. Payload: `{ productId, qty, variant }`. |
+| **PUT** | `/api/customer/cart/:productId` | `store.cart.update(productId, qty, variant)` | Updates quantity/variant. |
+| **DELETE** | `/api/customer/cart/:productId` | `store.cart.remove(productId, variant)` | Removes matching item from cart. |
+| **DELETE** | `/api/customer/cart` | `store.cart.clear()` | Empties customer cart entirely. |
+
+*Note: `DELETE` matching requires both product ID and variant so multiple sizes of the same product can exist side-by-side in the cart.*
+
+---
+
+## 5. Checkout & Orders API
+
+Handles order placement, lazy stock reservations, and Razorpay payment generation in an atomic transaction.
+
+*   **Endpoint:** `POST /api/customer/orders`
+*   **SDK Method:** `store.orders.create(orderData)`
+*   **Headers:** `x-api-key`, `Authorization: Bearer <customer_token>`
+*   **Request Body:**
+    ```json
+    {
+      "orderItems": [
+        {
+          "productId": "halden-sofa-id",
+          "name": "Halden 3-Seat Sofa",
+          "image": "https://images.unsplash.com/photo-1493663284031-b7e3aefcae8e",
+          "price": 2480,
+          "qty": 1,
+          "variant": "Grey Velvet"
+        }
+      ],
+      "shippingAddress": {
+        "fullName": "Aditya Patel",
+        "phone": "8348082967",
+        "address": "Room 304, Sneha Splendour, Hoodi",
+        "city": "Bengaluru",
+        "state": "Karnataka",
+        "postalCode": "560048",
+        "country": "India"
+      },
+      "paymentMethod": "Razorpay", // "Razorpay" or "COD"
+      "totalPrice": 2480
+    }
+    ```
+*   **Success Response (201 Created):**
+    ```json
+    {
+      "success": true,
+      "orderId": "order_uuid_abcde12345",
+      "trackingNumber": "ET-20260521-G8F4S",
+      "message": "Order placed successfully",
+      "razorpayOrderId": "order_RzpXYZ87654", // null if COD
+      "razorpayKeyId": "rzp_test_MerchantKeyID",
+      "amount": 248000, // amount in paisa for gateway (2480 * 100)
+      "currency": "INR",
+      "merchantName": "Epic Threadz"
+    }
+    ```
+
+---
+
+## 6. Payment Verification API
+
+Confirms payment signatures from Razorpay and converts in-flight lazy stock reservations to final physical inventory decrements.
+
+*   **Endpoint:** `POST /api/customer/payment/verify`
+*   **SDK Method:** `store.payment.verify(paymentData)`
+*   **Request Body:**
+    ```json
+    {
+      "razorpay_payment_id": "pay_Pkls898745",
+      "razorpay_order_id": "order_RzpXYZ87654",
+      "razorpay_signature": "abcdef0123456789signaturehash...",
+      "orderId": "order_uuid_abcde12345"
+    }
+    ```
+*   **Success Response (200 OK):**
+    ```json
+    {
+      "success": true,
+      "message": "Payment verified and order finalized"
+    }
+    ```
+
+---
+
+## 7. Shiprocket Checkout API
+
+Allows third-party logistics handlers like Shiprocket to interface directly with EpicMerch to read catalog listings and synchronize shipping orders.
+
+*   **Endpoint:** `POST /api/sr-checkout/token`
+    *   Generates logistics checkout sessions.
+*   **Endpoint:** `GET /api/sr-checkout/catalog/products`
+    *   Exposes products for Shiprocket catalog ingestion. Bypasses standard Bearer auth, relying purely on storefront API credentials passed in `x-api-key` headers or queries.
+
+---
+
+## 8. Structured Error Handling Matrix
+
+Every API error follows a uniform structure returning a standardized, machine-readable envelope:
+
+```json
+{
+  "success": false,
+  "code": "ERROR_CODE",
+  "message": "Human readable description",
+  "hint": "Actionable debugging step",
+  "items": [] // Optional context array
+}
+```
+
+| HTTP Status | Error `code` | Root Cause | Client Resolution |
+|---|---|---|---|
+| **400 Bad Request** | `INVALID_ORDER_ITEM` | An item in `orderItems[]` is missing `productId`. | Confirm the client maps cart structures using the canonical `productId` field, not the legacy `product` object. |
+| **400 Bad Request** | `INSUFFICIENT_STOCK` | Requested quantity exceeds variant/product stock. Returns a breakdown in the `items` field. | Reduce the quantity requested, notify the user, or show a disabled option. |
+| **400 Bad Request** | `PAYMENT_NOT_CONFIGURED` | `paymentMethod` is Razorpay but the merchant hasn't saved gateway credentials on the server. | Route the merchant to `/epicmerch-payments` to save their Razorpay Key ID + Key Secret. |
+| **502 Bad Gateway** | `PAYMENT_INIT_FAILED` | The payment gateway (Razorpay) rejected order registration (e.g. bad API keys). | Verify the credentials with Razorpay. The order is automatically rolled back in PostgreSQL. |
+| **401 Unauthorized** | `UNAUTHORIZED` | API key or Bearer Customer token is missing or expired. | Refresh customer token using `/refresh` or trigger customer OTP login. |
+| **403 Forbidden** | `FORBIDDEN` | Storefront origin domain is not in `merchant.allowedDomains`. | Add storefront domain using `merchant_add_allowed_domain`. |

package/package.json

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