epicmerch-mcp 1.0.0

package/src/resources/sdk-guide.md

@@ -0,0 +1,341 @@
+# EpicMerch SDK Integration Guide for Epic Threadz
+
+This document details how the **EpicMerch SDK** is integrated into the **Epic Threadz** storefront. It serves as a reference for developers to understand the interaction between the frontend application and the backend services.
+
+## 1. Installation & Initialization
+
+The SDK is imported and initialized in the main application entry point (`src/App.jsx`).
+
+### Initialization
+The `EpicMerch` class is instantiated with the API Key. For local development, the `baseUrl` can be overridden via environment variables.
+
+```javascript
+// src/App.jsx
+import EpicMerch from 'epicmerch';
+
+export const store = new EpicMerch({
+  apiKey: import.meta.env.VITE_API_KEY || 'your_public_key',
+  // Optional: Override for local development
+  ...(import.meta.env.VITE_API_URL && { baseUrl: import.meta.env.VITE_API_URL })
+});
+```
+
+The `store` instance is then exported and passed as a prop to child components or imported directly where needed.
+
+---
+
+## 2. Authentication
+
+The authentication flow uses OTP (One-Time Password) or Google OAuth. This is handled primarily in `src/pages/Login.jsx`.
+
+### Sending OTP
+```javascript
+// Send OTP to phone or email
+const response = await store.auth.sendOtp(identifier, 'phone'); // or 'email'
+// identifier: e.g., '+919876543210'
+```
+
+### Verifying OTP
+```javascript
+// Verify OTP and complete login/registration
+const result = await store.auth.verifyOtp(identifier, otpValue, {
+    name: 'User Name',
+    email: 'user@example.com', // optional profile data for new users
+    gender: 'Male'
+});
+
+// Result contains the authentication token
+if (result.token) {
+    store.setCustomerToken(result.token); // Store token in SDK for future requests
+    localStorage.setItem('customerInfo', JSON.stringify(result)); // Persist session
+}
+```
+
+### Google OAuth
+```javascript
+// Generate OAuth URL
+const authUrl = store.auth.getGoogleAuthUrl(window.location.origin + '/login');
+window.location.href = authUrl;
+
+// Handle Callback (on redirect page)
+const result = await store.auth.handleOAuthCallback();
+```
+
+---
+
+## 3. Product Catalog
+
+Product listing and searching are implemented in `src/App.jsx`.
+
+### Fetching Products
+```javascript
+const params = {
+  type: activeCategory, // e.g., 'Apparel' or undefined for all
+  page: 1,
+  limit: 12,
+  sort: 'newest',       // 'popularity', 'price_asc', 'price_desc'
+  keyword: searchQuery  // Optional search term
+};
+
+const data = await store.products.list(params);
+// Returns: { products: [...], total, pages }
+```
+
+---
+
+## 4. Shopping Cart
+
+Cart operations are managed in `src/App.jsx` and `src/components/CartSlider.jsx`.
+
+### Core Cart Operations
+```javascript
+// Get current cart
+const cartData = await store.cart.get();
+
+// Add item to cart
+await store.cart.add(productId, quantity, { type: 'Size', value: 'M' });
+
+// Update quantity
+await store.cart.update(productId, newQuantity);
+
+// Remove item
+await store.cart.remove(productId);
+
+// Clear cart
+await store.cart.clear();
+```
+
+---
+
+## 5. Checkout & Payments
+
+The checkout process (`src/pages/Checkout.jsx`) involves address management, order creation, and payment processing via Razorpay.
+
+### Address Management
+```javascript
+// List saved addresses
+const { addresses } = await store.addresses.list();
+
+// Add new address
+await store.addresses.add({
+    label: 'Home',
+    street: '123 Main St',
+    city: 'Mumbai',
+    state: 'MH',
+    postalCode: '400001',
+    country: 'India',
+    isDefault: true
+});
+```
+
+### Order Creation Flow
+1. **Create Order Record**:
+   ```javascript
+   const orderResult = await store.orders.create({
+       orderItems: [...],
+       shippingAddress: {...},
+       paymentMethod: 'Razorpay',
+       totalPrice: 1500
+   });
+   const { orderId } = orderResult;
+   ```
+
+2. **Initialize Payment**:
+   ```javascript
+   // Get Razorpay Config
+   const config = await store.payment.getConfig();
+
+   // Create Razorpay Order
+   const razorpayOrder = await store.payment.createOrder(amount, orderId);
+   ```
+
+3. **Verify Payment**:
+   After the Razorpay modal interaction:
+   ```javascript
+   const verifyResult = await store.payment.verify({
+       razorpay_order_id: response.razorpay_order_id,
+       razorpay_payment_id: response.razorpay_payment_id,
+       razorpay_signature: response.razorpay_signature,
+       orderId: orderId
+   });
+   ```
+
+### Saved Payment Methods
+The SDK supports "One-Click" checkout using saved tokens.
+
+```javascript
+// Get saved cards/UPI
+const methods = await store.payment.getSavedMethods();
+
+// Charge a saved method directly
+await store.payment.chargeSaved(methodId, amount, orderId);
+
+// Save a new method (after successful payment)
+await store.payment.saveMethod({
+    token: `tok_${paymentId}`,
+    type: 'card'
+});
+```
+
+---
+
+## 6. User Profile & Utilities
+
+### Newsletter
+```javascript
+await store.newsletter.subscribe('user@example.com');
+```
+
+### Profile Updates
+```javascript
+// Update phone number or profile info
+await store.customer.updateProfile({ phoneNumber: '+919999988888' });
+```
+
+---
+
+## 7. Configuration Reference
+
+The SDK is configured in `src/App.jsx`.
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `apiKey` | Public API Key for the merchant | Required |
+| `baseUrl`| API Server URL | Auto-detected (or `http://localhost:5001/api`) |
+
+---
+
+## 8. Idempotency (Duplicate Prevention)
+
+The SDK automatically handles idempotency for critical operations to prevent duplicate orders and payments.
+
+### How It Works
+- **Order Creation**: SDK generates an idempotency key based on cart contents
+- **Payment Verification**: Uses Razorpay payment ID as idempotency key (guaranteed unique)
+- **Saved Card Charges**: Uses order ID as idempotency key
+
+### Automatic Idempotency (Default Behavior)
+```javascript
+// The SDK automatically adds Idempotency-Key headers for critical operations
+const order = await store.orders.create(orderData);
+// ↑ Automatically generates key: payment_${orderId}
+
+await store.payment.verify(paymentData);
+// ↑ Automatically uses: verify_${razorpay_payment_id}
+```
+
+### Custom Idempotency Keys
+For checkout flows, provide a stable key to prevent double-click issues:
+
+```javascript
+// Generate a stable key once per checkout session
+const checkoutKey = `checkout_${userId}_${Date.now()}`;
+
+// Use the same key for the entire checkout
+const order = await store.orders.create(orderData, { 
+    idempotencyKey: checkoutKey 
+});
+```
+
+### Idempotent Response Detection
+```javascript
+const result = await store.orders.create(orderData, { idempotencyKey: 'my-key' });
+
+if (result._idempotent) {
+    // This is a cached response from a previous identical request
+    console.log('Order already created:', result.orderId);
+}
+```
+
+---
+
+## 9. Transactional APIs
+
+Critical operations (order creation, payment verification) are transactional:
+
+### Order Creation
+- ✅ Create order record
+- ✅ Reduce product stock
+- ✅ Update user (add order, clear cart)
+- ❌ If ANY step fails, ALL changes are rolled back
+
+### Payment Verification
+- ✅ Validates Razorpay signature
+- ✅ Atomically updates order status
+- ✅ Prevents double payment crediting
+- ✅ Returns `_alreadyVerified: true` for duplicate requests
+
+---
+
+## 10. Error Handling Best Practices
+
+```javascript
+try {
+    const order = await store.orders.create(orderData);
+    
+    if (order._idempotent) {
+        // Handle duplicate request gracefully
+        showSuccessMessage('Order already placed!');
+        return;
+    }
+    
+    // Proceed with payment
+    const razorpay = await store.payment.createOrder(amount, order.orderId);
+    
+} catch (error) {
+    if (error.response?.status === 409) {
+        // Conflict - request is being processed
+        showMessage('Your request is being processed. Please wait...');
+    } else if (error.response?.status === 429) {
+        // Rate limited
+        showError('Too many requests. Please try again later.');
+    } else {
+        showError(error.message || 'Something went wrong');
+    }
+}
+```
+
+---
+
+## 11. Checkout Page Best Practices
+
+### Editable Cart on Checkout
+The checkout page now supports inline cart editing:
+
+```javascript
+// Update quantity
+const handleUpdateQty = async (productId, newQty, variant) => {
+    await store.cart.update(productId, newQty, variant);
+    // Refresh cart state
+    const cartData = await store.cart.get();
+    setCart(cartData.cart);
+};
+
+// Remove item
+const handleRemoveItem = async (productId, variant) => {
+    await store.cart.remove(productId, variant);
+    // Refresh cart state
+    const cartData = await store.cart.get();
+    setCart(cartData.cart);
+};
+```
+
+### Success Modal Pattern
+Replace browser alerts with styled modals:
+
+```javascript
+const [successModal, setSuccessModal] = useState({ 
+    show: false, 
+    trackingNumber: '' 
+});
+
+// After payment verification
+setSuccessModal({ 
+    show: true, 
+    trackingNumber: orderResult.trackingNumber 
+});
+```
+
+---
+
+**Note**: All SDK methods return Promises. Use `async/await` and appropriate `try/catch` blocks for error handling.

package/src/status.js

@@ -0,0 +1,22 @@
+// src/status.js
+import { readTokenStore } from './token-store.js';
+
+export async function status() {
+  const data = readTokenStore();
+  if (!data || Object.keys(data.stores).length === 0) {
+    console.error('Not logged in. Run `npx epicmerch-mcp login` to set up OAuth.');
+    return;
+  }
+  console.error(`Default store: ${data.defaultStore}`);
+  for (const [name, entry] of Object.entries(data.stores)) {
+    const accessExp = new Date(entry.accessTokenExpiresAt);
+    const refreshExp = new Date(entry.refreshTokenExpiresAt);
+    const now = new Date();
+    const accessStatus  = accessExp  > now ? `valid until ${accessExp.toISOString()}`  : 'EXPIRED (will refresh)';
+    const refreshStatus = refreshExp > now ? `valid until ${refreshExp.toISOString()}` : 'EXPIRED — run `epicmerch-mcp login` again';
+    console.error(`\n  ${name}${name === data.defaultStore ? ' (default)' : ''}`);
+    console.error(`    Access token:  ${accessStatus}`);
+    console.error(`    Refresh token: ${refreshStatus}`);
+    console.error(`    Scope: ${entry.scope}`);
+  }
+}

package/src/token-store.js

@@ -0,0 +1,52 @@
+// src/token-store.js
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from 'fs';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+
+export function tokenPath() {
+  return join(homedir(), '.epicmerch', 'token.json');
+}
+
+export function readTokenStore() {
+  const p = tokenPath();
+  if (!existsSync(p)) return null;
+  let raw;
+  try { raw = readFileSync(p, 'utf-8'); }
+  catch (e) { throw new Error(`Could not read token file ${p}: ${e.message}`); }
+  try { return JSON.parse(raw); }
+  catch (e) { throw new Error(`Token file ${p} is corrupt JSON: ${e.message}. Delete it and run 'npx epicmerch-mcp login' again.`); }
+}
+
+export function writeTokenStore(data) {
+  const p = tokenPath();
+  const dir = dirname(p);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  writeFileSync(p, JSON.stringify(data, null, 2) + '\n');
+  try { chmodSync(p, 0o600); } catch (_) { /* Windows no-op */ }
+}
+
+export function upsertStore(name, entry) {
+  const data = readTokenStore() ?? { version: 1, defaultStore: null, stores: {} };
+  data.stores[name] = entry;
+  if (!data.defaultStore) data.defaultStore = name;
+  writeTokenStore(data);
+}
+
+export function removeStore(name) {
+  const data = readTokenStore();
+  if (!data) return;
+  delete data.stores[name];
+  if (data.defaultStore === name) {
+    const remaining = Object.keys(data.stores);
+    data.defaultStore = remaining[0] ?? null;
+  }
+  writeTokenStore(data);
+}
+
+export function getActiveEntry() {
+  const data = readTokenStore();
+  if (!data) return null;
+  const targetName = process.env.EPICMERCH_ACTIVE_STORE || data.defaultStore;
+  if (!targetName) return null;
+  return data.stores[targetName] ?? null;
+}