epicmerch-mcp 1.0.0

package/src/tools/merchant.js

@@ -0,0 +1,618 @@
+// src/tools/merchant.js
+import { v4 as uuidv4 } from 'uuid';
+import { createRequire } from 'module';
+import { withExamples } from './_examples.js';
+const _require = createRequire(import.meta.url);
+
+const ok = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] });
+const err = (msg) => ({ isError: true, content: [{ type: 'text', text: msg }] });
+
+// In-memory session store for Shopify migration (scoped to MCP process lifetime)
+const migrationSessions = new Map();
+
+export function merchantTools(client, session) {
+  const requireAuth = () => {
+    // OAuth mode (sub-project A): access token travels via Authorization: Bearer
+    // header — no JWT needed locally. The Client class handles header selection
+    // based on session.getAuthMode(). The token's mere presence is enough proof
+    // of auth; the server-side bearerTokenMiddleware will reject it if invalid.
+    if (session.getAuthMode?.() === 'oauth' && session.getActiveTokenEntry?.()) return;
+    // Legacy JWT path is retained for tests/internal callers that pre-set a JWT via
+    // session.setJwt(...), but there is no longer a tool that collects credentials
+    // in chat — merchants must authenticate via the browser OAuth flow.
+    if (!session.getActiveJwt()) {
+      throw new Error(
+        'Not authenticated. Tell the user to run `npx epicmerch-mcp login` in a ' +
+        'terminal — it opens a browser and saves a token locally (no credentials ' +
+        'pass through this chat). Once they confirm, retry the tool call.'
+      );
+    }
+  };
+
+  return {
+    // --- PRODUCTS ---
+    async merchant_list_products({ page, limit, keyword } = {}) {
+      requireAuth();
+      const p = new URLSearchParams();
+      if (page) p.set('page', page);
+      if (limit) p.set('limit', limit);
+      if (keyword) p.set('keyword', keyword);
+      const qs = p.toString();
+      return ok(await client.authGet(`/products${qs ? `?${qs}` : ''}`));
+    },
+    async merchant_get_product({ id }) {
+      requireAuth();
+      return ok(await client.authGet(`/products/${id}`));
+    },
+    async merchant_create_product(body) {
+      requireAuth();
+      return ok(await client.authPost('/products', body));
+    },
+    async merchant_update_product({ id, ...body }) {
+      requireAuth();
+      return ok(await client.authPut(`/products/${id}`, body));
+    },
+    async merchant_delete_product({ id }) {
+      requireAuth();
+      return ok(await client.authDelete(`/products/${id}`));
+    },
+    async merchant_generate_product_description({ productId, name, category }) {
+      requireAuth();
+      return ok(await client.authPost('/ai/generate-description', { productId, name, category }));
+    },
+    async merchant_get_product_recommendations(_args) {
+      requireAuth();
+      return ok(await client.authGet('/ai/recommendations'));
+    },
+
+    // --- CATEGORIES ---
+    async merchant_list_categories(_args) {
+      requireAuth();
+      return ok(await client.authGet('/categories'));
+    },
+    async merchant_create_category({ name, visible }) {
+      requireAuth();
+      return ok(await client.authPost('/categories', { name, visible }));
+    },
+    async merchant_update_category({ id, ...body }) {
+      requireAuth();
+      return ok(await client.authPut(`/categories/${id}`, body));
+    },
+    async merchant_delete_category({ id }) {
+      requireAuth();
+      return ok(await client.authDelete(`/categories/${id}`));
+    },
+    async merchant_toggle_category_visibility({ id }) {
+      requireAuth();
+      return ok(await client.authPatch(`/categories/${id}/toggle`, {}));
+    },
+
+    // --- ORDERS ---
+    async merchant_list_orders({ page, limit, status } = {}) {
+      requireAuth();
+      const p = new URLSearchParams();
+      if (page) p.set('page', page);
+      if (limit) p.set('limit', limit);
+      if (status) p.set('status', status);
+      const qs = p.toString();
+      return ok(await client.authGet(`/orders${qs ? `?${qs}` : ''}`));
+    },
+    async merchant_get_order({ id }) {
+      requireAuth();
+      return ok(await client.authGet(`/orders/${id}`));
+    },
+    async merchant_update_order_status({ id, status }) {
+      requireAuth();
+      return ok(await client.authPut(`/orders/${id}/status`, { status }));
+    },
+    async merchant_update_payment_status({ id, isPaid }) {
+      requireAuth();
+      return ok(await client.authPut(`/orders/${id}/paystatus`, { isPaid }));
+    },
+
+    // --- CUSTOMERS ---
+    async merchant_list_customers(_args) {
+      requireAuth();
+      return ok(await client.authGet('/users'));
+    },
+    async merchant_get_customer({ id }) {
+      requireAuth();
+      return ok(await client.authGet(`/users/${id}`));
+    },
+    async merchant_delete_customer({ id }) {
+      requireAuth();
+      return ok(await client.authDelete(`/users/${id}`));
+    },
+
+    // --- ANALYTICS ---
+    async merchant_get_analytics_stats(_args) { requireAuth(); return ok(await client.authGet('/analytics/stats')); },
+    async merchant_get_sales_trend({ period } = {}) { requireAuth(); return ok(await client.authGet(`/analytics/sales-trend${period ? `?period=${period}` : ''}`)); },
+    async merchant_get_top_products(_args) { requireAuth(); return ok(await client.authGet('/analytics/top-products')); },
+    async merchant_get_traffic(_args) { requireAuth(); return ok(await client.authGet('/analytics/traffic')); },
+    async merchant_get_revenue_by_category(_args) { requireAuth(); return ok(await client.authGet('/analytics/revenue-by-category')); },
+    async merchant_get_order_status_distribution(_args) { requireAuth(); return ok(await client.authGet('/analytics/order-status')); },
+    async merchant_get_peak_hours(_args) { requireAuth(); return ok(await client.authGet('/analytics/peak-hours')); },
+    async merchant_get_geographic_distribution(_args) { requireAuth(); return ok(await client.authGet('/analytics/geographic')); },
+    async merchant_get_period_comparison({ period } = {}) { requireAuth(); return ok(await client.authGet(`/analytics/comparison${period ? `?period=${period}` : ''}`)); },
+    async merchant_get_cart_abandonment(_args) { requireAuth(); return ok(await client.authGet('/analytics/cart-abandonment')); },
+    async merchant_get_ai_insights(body) { requireAuth(); return ok(await client.authPost('/ai/analytics-insights', body)); },
+
+    // --- NOTIFICATIONS ---
+    async merchant_list_subscribers(_args) { requireAuth(); return ok(await client.authGet('/notifications/subscribers')); },
+    async merchant_send_notification(body) { requireAuth(); return ok(await client.authPost('/notifications/send', body)); },
+    async merchant_send_to_user(body) { requireAuth(); return ok(await client.authPost('/notifications/send-to-user', body)); },
+    async merchant_get_abandoned_carts({ hours } = {}) { requireAuth(); return ok(await client.authGet(`/notifications/abandoned-carts${hours ? `?hours=${hours}` : ''}`)); },
+    async merchant_get_notification_history(_args) { requireAuth(); return ok(await client.authGet('/notifications/history')); },
+    async merchant_get_notification_stats(_args) { requireAuth(); return ok(await client.authGet('/notifications/stats')); },
+
+    // --- SETTINGS ---
+    async merchant_get_settings(_args) { requireAuth(); return ok(await client.authGet('/users/settings')); },
+    async merchant_update_currency({ currency }) { requireAuth(); return ok(await client.authPut('/users/currency', { currency })); },
+    async merchant_get_email_settings(_args) { requireAuth(); return ok(await client.authGet('/users/email-settings')); },
+    async merchant_update_email_settings(body) { requireAuth(); return ok(await client.authPut('/users/email-settings', body)); },
+    async merchant_get_logistics_settings(_args) { requireAuth(); return ok(await client.authGet('/users/logistics-settings')); },
+    async merchant_update_logistics_settings(body) { requireAuth(); return ok(await client.authPut('/users/logistics-settings', body)); },
+    async merchant_get_checkout_settings(_args) { requireAuth(); return ok(await client.authGet('/users/checkout-settings')); },
+    async merchant_update_checkout_settings(body) { requireAuth(); return ok(await client.authPut('/users/checkout-settings', body)); },
+    async merchant_get_security_settings(_args) { requireAuth(); return ok(await client.authGet('/users/security-settings')); },
+    async merchant_add_allowed_domain({ domain }) { requireAuth(); return ok(await client.authPost('/users/security-settings/domains', { domain })); },
+    async merchant_remove_allowed_domain({ domain }) { requireAuth(); return ok(await client.authDelete(`/users/security-settings/domains/${domain}`)); },
+
+    // --- API KEYS ---
+    async merchant_list_api_keys(_args) { requireAuth(); return ok(await client.authGet('/keys')); },
+    async merchant_generate_api_key({ name }) { requireAuth(); return ok(await client.authPost('/keys', { name })); },
+    async merchant_delete_api_key({ id }) { requireAuth(); return ok(await client.authDelete(`/keys/${id}`)); },
+
+    // --- STOREFRONT GENERATION ---
+    async merchant_list_storefront_templates(_args) { requireAuth(); return ok(await client.authGet('/storefront/templates')); },
+    async merchant_generate_storefront_from_prompt(body) { requireAuth(); return ok(await client.authPost('/storefront/generate-from-prompt', body)); },
+    async merchant_get_deploy_options(_args) { requireAuth(); return ok(await client.authGet('/storefront/deploy-options')); },
+
+    // --- GITHUB ---
+    async merchant_get_github_status(_args) { requireAuth(); return ok(await client.authGet('/github/status')); },
+    async merchant_list_github_repos(_args) { requireAuth(); return ok(await client.authGet('/github/repos')); },
+    async merchant_push_to_github(body) { requireAuth(); return ok(await client.authPost('/github/push-code', body)); },
+
+    // --- LOGISTICS ---
+    async merchant_get_shipping_rates(body) { return ok(await client.post('/logistics/rates', body)); },
+    async merchant_create_shipment(body) { requireAuth(); return ok(await client.authPost('/logistics/shipment', body)); },
+    async merchant_track_shipment({ trackingId }) { return ok(await client.get(`/logistics/track/${trackingId}`)); },
+
+    // --- FINANCE ---
+    async merchant_get_consolidation_report(_args) { requireAuth(); return ok(await client.authGet('/consolidation/report')); },
+
+    // --- SHIPROCKET ---
+    async merchant_list_sr_orders(body) { requireAuth(); return ok(await client.authPost('/sr-checkout/order-list', body)); },
+    async merchant_initiate_refund({ orderId, amount }) { requireAuth(); return ok(await client.authPost('/sr-checkout/refund', { order_id: orderId, amount })); },
+    async merchant_sync_product_to_sr({ productId }) { requireAuth(); return ok(await client.authPost('/sr-checkout/catalog/sync-product', { productId })); },
+
+    // --- SHOPIFY MIGRATION ---
+    async merchant_shopify_migrate({ stage, shopifyStore, shopifyKey, sessionId }) {
+      requireAuth();
+      const epicmerchUrl = session.getApiUrl();
+      const epicmerchKey = session.getApiKey();
+
+      if (stage === 'extract') {
+        const { runExtract } = _require('../../epicmerch-migrate/src/stages/extract');
+        const { runTransform } = _require('../../epicmerch-migrate/src/stages/transform');
+        const { runPreview } = _require('../../epicmerch-migrate/src/stages/preview');
+
+        const raw = await runExtract({ source: 'api', credentials: { shopifyStore, shopifyKey } });
+        const transformed = runTransform(raw);
+        const diff = await runPreview({ transformed, epicmerchUrl, epicmerchKey });
+
+        const sid = uuidv4();
+        migrationSessions.set(sid, { diff, epicmerchUrl, epicmerchKey });
+
+        const summary = {
+          products: `${diff.products.new.length} new, ${diff.products.updated.length} updated, ${diff.products.unchanged.length} unchanged`,
+          customers: `${diff.customers.new.length} new`,
+          orders: `${diff.orders.new.length} new`,
+          categories: `${diff.categories.new.length} new`,
+        };
+        return { content: [{ type: 'text', text: `Preview ready (sessionId: ${sid}):\n${JSON.stringify(summary, null, 2)}\n\nCall merchant_shopify_migrate with stage="import" and sessionId="${sid}" to proceed.` }] };
+      }
+
+      if (stage === 'import') {
+        if (!sessionId || !migrationSessions.has(sessionId)) {
+          return { content: [{ type: 'text', text: 'Invalid or expired sessionId. Run stage="extract" first.' }] };
+        }
+        const sess = migrationSessions.get(sessionId);
+        const { runImport } = _require('../../epicmerch-migrate/src/stages/import');
+        const { reuploadImages } = _require('../../epicmerch-migrate/src/stages/image-upload');
+
+        const result = await runImport({ diff: sess.diff, epicmerchUrl: sess.epicmerchUrl, epicmerchKey: sess.epicmerchKey });
+        reuploadImages({ pendingImages: result.pendingImages, epicmerchUrl: sess.epicmerchUrl, epicmerchKey: sess.epicmerchKey }).catch(() => {});
+        migrationSessions.delete(sessionId);
+
+        return { content: [{ type: 'text', text: `Migration complete!\nProducts: ${result.products.created} created, ${result.products.updated} updated\nCustomers: ${result.customers.created} created\nOrders: ${result.orders.created} created\n\nImages are re-uploading in the background.` }] };
+      }
+
+      return { content: [{ type: 'text', text: 'Unknown stage. Use "extract" or "import".' }] };
+    },
+
+    // --- QUICK SETUP ---
+    async merchant_quick_setup({ email, password, storeName, currency, shopifyStore, shopifyKey }) {
+      // Best-effort pipeline: each step is independently caught. Steps after a failure
+      // continue running unless the failure is signup (which is the precondition for all
+      // subsequent steps).
+      const skipped = { status: 'skipped' };
+      const result = {
+        signup: skipped, currency: skipped, apiKey: skipped,
+        sampleProduct: skipped, sampleCategory: skipped,
+        paymentSetup: skipped, migration: skipped,
+      };
+
+      // --- Step 1: signup ---
+      try {
+        const data = await client.post('/users', {
+          name: storeName ?? email,
+          email,
+          password,
+        });
+        if (!data.token) throw new Error('Signup succeeded but no token returned');
+        session.setJwt(session.activeStore(), data.token);
+        result.signup = { status: 'ok', userId: data.user?._id ?? data.user?.id ?? null };
+      } catch (e) {
+        result.signup = { status: 'failed', reason: e.message || String(e) };
+        return ok(result); // every other step depends on having an auth token
+      }
+
+      // --- Step 2: currency ---
+      try {
+        const value = currency ?? 'USD';
+        await client.authPut('/users/currency', { currency: value });
+        result.currency = { status: 'ok', value };
+      } catch (e) {
+        result.currency = { status: 'failed', reason: e.message || String(e) };
+      }
+
+      // --- Step 3: API key ---
+      try {
+        const data = await client.authPost('/keys', { name: 'default' });
+        result.apiKey = { status: 'ok', key: data.key ?? data.apiKey ?? null, id: data.id ?? data._id ?? null };
+      } catch (e) {
+        result.apiKey = { status: 'failed', reason: e.message || String(e) };
+      }
+
+      // --- Step 4: sample product ---
+      try {
+        const data = await client.authPost('/products', {
+          name: 'Welcome to EpicMerch',
+          price: 1.0,
+          description: 'A sample product to get you started. Delete or edit me anytime.',
+          type: 'physical',
+        });
+        result.sampleProduct = { status: 'ok', productId: data._id ?? data.id ?? null };
+      } catch (e) {
+        result.sampleProduct = { status: 'failed', reason: e.message || String(e) };
+      }
+
+      // --- Step 5: sample category ---
+      try {
+        const data = await client.authPost('/categories', { name: 'Featured', visible: true });
+        result.sampleCategory = { status: 'ok', categoryId: data._id ?? data.id ?? null };
+      } catch (e) {
+        result.sampleCategory = { status: 'failed', reason: e.message || String(e) };
+      }
+
+      // --- Step 6: payment setup status (read-only) ---
+      try {
+        const checkout = await client.authGet('/users/checkout-settings');
+        result.paymentSetup = {
+          status: 'pending',
+          currentType: checkout?.checkoutType ?? null,
+          link: '/settings/payment',
+        };
+      } catch (e) {
+        result.paymentSetup = { status: 'failed', reason: e.message || String(e) };
+      }
+
+      // --- Step 7: optional Shopify migration preview ---
+      if (shopifyStore && shopifyKey) {
+        try {
+          const epicmerchUrl = session.getApiUrl();
+          const epicmerchKey = result.apiKey?.key ?? session.getApiKey();
+          const { runExtract } = _require('../../epicmerch-migrate/src/stages/extract');
+          const { runTransform } = _require('../../epicmerch-migrate/src/stages/transform');
+          const { runPreview } = _require('../../epicmerch-migrate/src/stages/preview');
+
+          const raw = await runExtract({ source: 'api', credentials: { shopifyStore, shopifyKey } });
+          const transformed = runTransform(raw);
+          const diff = await runPreview({ transformed, epicmerchUrl, epicmerchKey });
+
+          const sid = uuidv4();
+          migrationSessions.set(sid, { diff, epicmerchUrl, epicmerchKey });
+
+          result.migration = {
+            status: 'preview_ready',
+            sessionId: sid,
+            diff: {
+              products:   `${diff.products.new.length} new, ${diff.products.updated.length} updated, ${diff.products.unchanged.length} unchanged`,
+              customers:  `${diff.customers.new.length} new`,
+              orders:     `${diff.orders.new.length} new`,
+              categories: `${diff.categories.new.length} new`,
+            },
+          };
+        } catch (e) {
+          result.migration = { status: 'failed', reason: e.message || String(e) };
+        }
+      }
+
+      return ok(result);
+    },
+
+    // --- STRIPE CONFIGURATION ---
+    async merchant_configure_stripe({ publishableKey, secretKey, webhookSecret }) {
+      requireAuth();
+      const body = {};
+      if (publishableKey !== undefined) body.stripePublishableKey = publishableKey;
+      if (secretKey !== undefined)      body.stripeSecretKey      = secretKey;
+      if (webhookSecret !== undefined)  body.stripeWebhookSecret  = webhookSecret;
+      return ok(await client.authPut('/users/checkout-settings', body));
+    },
+
+    async merchant_test_stripe_connection() {
+      requireAuth();
+      return ok(await client.authGet('/users/stripe/test'));
+    },
+
+    async merchant_set_checkout_type({ type }) {
+      requireAuth();
+      const valid = ['epicmerch', 'stripe', 'shiprocket'];
+      if (!valid.includes(type)) {
+        throw new Error(`checkoutType must be one of: ${valid.join(', ')}`);
+      }
+      return ok(await client.authPut('/users/checkout-settings', { checkoutType: type }));
+    },
+
+    // --- DIAGNOSE ---
+    async merchant_diagnose() {
+      requireAuth();
+
+      // Each section is fetched independently; one failure does not abort the others.
+      const safeGet = async (path) => {
+        try { return { ok: true, data: await client.authGet(path) }; }
+        catch (e) { return { ok: false, error: e.message || String(e) }; }
+      };
+
+      const [profileR, productsR, categoriesR, checkoutR, keysR] = await Promise.all([
+        safeGet('/users/profile'),
+        safeGet('/products'),
+        safeGet('/categories'),
+        safeGet('/users/checkout-settings'),
+        safeGet('/keys'),
+      ]);
+
+      // Tolerate API shape drift: profile may be { user: {...} } or {...}; products may be
+      // an array or { products: [...] }.
+      const unwrap = (r, fallback) => (r.ok ? (r.data ?? fallback) : null);
+      const unwrapList = (r) => {
+        if (!r.ok) return null;
+        if (Array.isArray(r.data)) return r.data;
+        if (Array.isArray(r.data?.products)) return r.data.products;
+        if (Array.isArray(r.data?.categories)) return r.data.categories;
+        if (Array.isArray(r.data?.keys)) return r.data.keys;
+        return [];
+      };
+      const profile  = unwrap(profileR, null);
+      const products = unwrapList(productsR);
+      const cats     = unwrapList(categoriesR);
+      const checkout = unwrap(checkoutR, null);
+      const keys     = unwrapList(keysR);
+
+      // Build each section, returning { error } if its fetch failed.
+      const store = profileR.ok ? {
+        name:      profile?.name ?? profile?.user?.name ?? null,
+        currency:  profile?.currency ?? profile?.user?.currency ?? null,
+        hasDomain: Boolean(profile?.domain ?? profile?.user?.domain),
+        hasLogo:   Boolean(profile?.logo ?? profile?.user?.logo),
+      } : { error: profileR.error };
+
+      const catalog = productsR.ok && categoriesR.ok ? {
+        productCount:    products.length,
+        categoryCount:   cats.length,
+        outOfStockCount: products.filter((p) => (p.countInStock ?? 0) === 0).length,
+      } : { error: (productsR.error || categoriesR.error) };
+
+      const payment = checkoutR.ok ? {
+        razorpayConfigured: Boolean(checkout?.razorpayKeyId && checkout?.razorpayKeySecretIsSet),
+        stripeConfigured:   Boolean(checkout?.stripeSecretKeyIsSet),  // future-proofed for sub-project E
+        checkoutType:       checkout?.checkoutType ?? null,
+      } : { error: checkoutR.error };
+
+      const logistics = checkoutR.ok ? {
+        shiprocketConfigured: Boolean(checkout?.shiprocketEmail && checkout?.shiprocketPasswordIsSet),
+      } : { error: checkoutR.error };
+
+      const apiKeys = keysR.ok ? {
+        count:      keys.length,
+        lastUsedAt: keys
+          .map((k) => k.lastUsedAt)
+          .filter(Boolean)
+          .sort()
+          .reverse()[0] ?? null,
+      } : { error: keysR.error };
+
+      // --- Readiness score (max 100) ---
+      let score = 0;
+      const nextSteps = [];
+
+      if (!payment.error) {
+        if (payment.razorpayConfigured || payment.stripeConfigured) score += 40;
+        else nextSteps.push('Configure payment at /settings/payment (Razorpay or Stripe)');
+      }
+
+      if (!catalog.error) {
+        const productPoints = Math.min(catalog.productCount, 3) * 8; // 8 pts/product, capped at 24
+        const productMax = catalog.productCount >= 3 ? 25 : productPoints;
+        score += productMax;
+        if (catalog.productCount < 3) nextSteps.push('Add at least 3 products to your catalog');
+        if (catalog.outOfStockCount > 0) nextSteps.push(`Restock ${catalog.outOfStockCount} out-of-stock product(s)`);
+      }
+
+      if (!logistics.error) {
+        if (logistics.shiprocketConfigured) score += 15;
+        else nextSteps.push('Connect Shiprocket at /settings/logistics');
+      }
+
+      if (!store.error) {
+        if (store.hasDomain) score += 10;
+        else nextSteps.push('Set a custom domain at /settings/profile');
+        if (store.hasLogo) score += 10;
+        else nextSteps.push('Add a store logo at /settings/profile');
+      }
+
+      return ok({
+        store,
+        catalog,
+        payment,
+        logistics,
+        apiKeys,
+        readinessScore: score,
+        nextSteps,
+      });
+    },
+  };
+}
+
+const _baseMerchantToolDefs = [
+  // NOTE: merchant_login was deliberately removed in favour of the browser OAuth
+  // flow (`npx epicmerch-mcp login`). We do NOT expose a chat-callable tool that
+  // accepts credentials. See requireAuth() above for the error message merchants
+  // see when they call other tools without an active session.
+  { name: 'merchant_list_products', description: 'List all products in the merchant dashboard.', schema: { page: { type: 'number' }, limit: { type: 'number' }, keyword: { type: 'string' } } },
+  { name: 'merchant_get_product', description: 'Get a single product by ID.', schema: { id: { type: 'string' } } },
+  {
+    name: 'merchant_create_product',
+    description: 'Create a new product. Server currently creates with placeholder values then expects a follow-up merchant_update_product to set real data; pass all known fields here and a chained update may be needed.',
+    schema: {
+      name: { type: 'string' },
+      price: { type: 'number' },
+      salePrice: { type: 'number' },
+      discountPercent: { type: 'number' },
+      description: { type: 'string' },
+      type: { type: 'string' },
+      stock: { type: 'number' },
+      image: { type: 'string' },
+    },
+  },
+  {
+    name: 'merchant_update_product',
+    description: 'Update a product by ID. Pass any subset of fields to change.',
+    schema: {
+      id: { type: 'string' },
+      name: { type: 'string' },
+      price: { type: 'number' },
+      salePrice: { type: 'number' },
+      discountPercent: { type: 'number' },
+      description: { type: 'string' },
+      type: { type: 'string' },
+      stock: { type: 'number' },
+      image: { type: 'string' },
+    },
+  },
+  { name: 'merchant_delete_product', description: 'Delete a product by ID.', schema: { id: { type: 'string' } } },
+  { name: 'merchant_generate_product_description', description: 'Use AI to generate a product description.', schema: { productId: { type: 'string' }, name: { type: 'string' }, category: { type: 'string' } } },
+  { name: 'merchant_get_product_recommendations', description: 'Get AI product recommendations.', schema: {} },
+  { name: 'merchant_list_categories', description: 'List all categories.', schema: {} },
+  { name: 'merchant_create_category', description: 'Create a category.', schema: { name: { type: 'string' }, visible: { type: 'boolean' } } },
+  { name: 'merchant_update_category', description: 'Update a category.', schema: { id: { type: 'string' } } },
+  { name: 'merchant_delete_category', description: 'Delete a category.', schema: { id: { type: 'string' } } },
+  { name: 'merchant_toggle_category_visibility', description: 'Toggle a category visible/hidden.', schema: { id: { type: 'string' } } },
+  { name: 'merchant_list_orders', description: 'List orders with optional filters.', schema: { page: { type: 'number' }, limit: { type: 'number' }, status: { type: 'string' } } },
+  { name: 'merchant_get_order', description: 'Get order details by ID.', schema: { id: { type: 'string' } } },
+  { name: 'merchant_update_order_status', description: 'Update order fulfilment status.', schema: { id: { type: 'string' }, status: { type: 'string' } } },
+  { name: 'merchant_update_payment_status', description: 'Mark an order as paid/unpaid.', schema: { id: { type: 'string' }, isPaid: { type: 'boolean' } } },
+  { name: 'merchant_list_customers', description: 'List all customers.', schema: {} },
+  { name: 'merchant_get_customer', description: 'Get customer by ID.', schema: { id: { type: 'string' } } },
+  { name: 'merchant_delete_customer', description: 'Delete a customer.', schema: { id: { type: 'string' } } },
+  { name: 'merchant_get_analytics_stats', description: 'Get overall store stats (revenue, orders, customers).', schema: {} },
+  { name: 'merchant_get_sales_trend', description: 'Get sales over time.', schema: { period: { type: 'string' } } },
+  { name: 'merchant_get_top_products', description: 'Get best-selling products.', schema: {} },
+  { name: 'merchant_get_traffic', description: 'Get storefront traffic stats.', schema: {} },
+  { name: 'merchant_get_revenue_by_category', description: 'Revenue breakdown by product category.', schema: {} },
+  { name: 'merchant_get_order_status_distribution', description: 'Order status breakdown.', schema: {} },
+  { name: 'merchant_get_peak_hours', description: 'Peak order/traffic hours.', schema: {} },
+  { name: 'merchant_get_geographic_distribution', description: 'Order geographic breakdown.', schema: {} },
+  { name: 'merchant_get_period_comparison', description: 'Compare current vs previous period.', schema: { period: { type: 'string' } } },
+  { name: 'merchant_get_cart_abandonment', description: 'Cart abandonment rate stats.', schema: {} },
+  { name: 'merchant_get_ai_insights', description: 'Get AI-powered analytics insights.', schema: {} },
+  { name: 'merchant_list_subscribers', description: 'List newsletter subscribers.', schema: {} },
+  { name: 'merchant_send_notification', description: 'Send email or WhatsApp notification.', schema: { to: { type: 'string' }, subject: { type: 'string' }, message: { type: 'string' }, type: { type: 'string' } } },
+  { name: 'merchant_send_to_user', description: 'Send notification to a specific user.', schema: { userId: { type: 'string' }, subject: { type: 'string' }, message: { type: 'string' } } },
+  { name: 'merchant_get_abandoned_carts', description: 'List customers with abandoned carts.', schema: { hours: { type: 'number' } } },
+  { name: 'merchant_get_notification_history', description: 'Get notification send history.', schema: {} },
+  { name: 'merchant_get_notification_stats', description: 'Get notification open/click stats.', schema: {} },
+  { name: 'merchant_get_settings', description: 'Get all merchant settings.', schema: {} },
+  { name: 'merchant_update_currency', description: 'Update store currency.', schema: { currency: { type: 'string' } } },
+  { name: 'merchant_get_email_settings', description: 'Get email settings.', schema: {} },
+  { name: 'merchant_update_email_settings', description: 'Update email settings.', schema: {} },
+  { name: 'merchant_get_logistics_settings', description: 'Get logistics/shipping settings.', schema: {} },
+  { name: 'merchant_update_logistics_settings', description: 'Update logistics settings.', schema: {} },
+  { name: 'merchant_get_checkout_settings', description: 'Get checkout settings.', schema: {} },
+  { name: 'merchant_update_checkout_settings', description: 'Update checkout settings.', schema: {} },
+  { name: 'merchant_get_security_settings', description: 'Get security settings and allowed domains.', schema: {} },
+  { name: 'merchant_add_allowed_domain', description: 'Add an allowed CORS domain.', schema: { domain: { type: 'string' } } },
+  { name: 'merchant_remove_allowed_domain', description: 'Remove an allowed CORS domain.', schema: { domain: { type: 'string' } } },
+  { name: 'merchant_list_api_keys', description: 'List all API keys.', schema: {} },
+  { name: 'merchant_generate_api_key', description: 'Generate a new API key.', schema: { name: { type: 'string' } } },
+  { name: 'merchant_delete_api_key', description: 'Delete an API key.', schema: { id: { type: 'string' } } },
+  { name: 'merchant_list_storefront_templates', description: 'List available storefront templates.', schema: {} },
+  { name: 'merchant_generate_storefront_from_prompt', description: 'Generate a storefront from an AI prompt.', schema: { prompt: { type: 'string' } } },
+  { name: 'merchant_get_deploy_options', description: 'Get available deployment options.', schema: {} },
+  { name: 'merchant_get_github_status', description: 'Get GitHub connection status.', schema: {} },
+  { name: 'merchant_list_github_repos', description: 'List connected GitHub repositories.', schema: {} },
+  { name: 'merchant_push_to_github', description: 'Push storefront code to a GitHub repo.', schema: { repo: { type: 'string' }, message: { type: 'string' } } },
+  { name: 'merchant_get_shipping_rates', description: 'Get shipping rates for an order.', schema: {} },
+  { name: 'merchant_create_shipment', description: 'Create a shipment for an order.', schema: { orderId: { type: 'string' } } },
+  { name: 'merchant_track_shipment', description: 'Track a shipment by tracking ID.', schema: { trackingId: { type: 'string' } } },
+  { name: 'merchant_get_consolidation_report', description: 'Get financial consolidation report.', schema: {} },
+  { name: 'merchant_list_sr_orders', description: 'List Shiprocket orders.', schema: {} },
+  { name: 'merchant_initiate_refund', description: 'Initiate a Shiprocket refund.', schema: { orderId: { type: 'string' }, amount: { type: 'number' } } },
+  { name: 'merchant_sync_product_to_sr', description: 'Sync a product to Shiprocket catalog.', schema: { productId: { type: 'string' } } },
+  {
+    name: 'merchant_quick_setup',
+    description: 'White-glove onboarding for a new merchant. Creates an account, sets currency, generates an API key, creates a sample product and category, reports payment configuration status, and (if shopifyStore + shopifyKey are provided) returns a Shopify migration preview. Each step is independently caught; the structured return reports per-step status.',
+    schema: {
+      email:        { type: 'string' },
+      password:     { type: 'string' },
+      storeName:    { type: 'string' },
+      currency:     { type: 'string' },
+      shopifyStore: { type: 'string' },
+      shopifyKey:   { type: 'string' },
+    },
+  },
+  { name: 'merchant_diagnose', description: 'Check overall store health: configuration status, product/category counts, payment + logistics setup, API keys, and a 0-100 readiness score with a prioritised list of next steps.', schema: {} },
+  {
+    name: 'merchant_configure_stripe',
+    description: 'Configure Stripe payment processing for the merchant: stores publishable key, secret key, and webhook signing secret. Pair with merchant_set_checkout_type({type:"stripe"}) to activate.',
+    schema: {
+      publishableKey: { type: 'string' },
+      secretKey:      { type: 'string' },
+      webhookSecret:  { type: 'string' },
+    },
+  },
+  {
+    name: 'merchant_test_stripe_connection',
+    description: 'Verify the merchant\'s Stripe keys work by fetching their Stripe account. Returns accountId, country, and charges-enabled status.',
+    schema: {},
+  },
+  {
+    name: 'merchant_set_checkout_type',
+    description: 'Set which checkout flow the merchant\'s storefront uses. Must be one of: "epicmerch" (Razorpay + Shiprocket), "stripe" (Stripe + Shiprocket), or "shiprocket" (full SR Checkout).',
+    schema: { type: { type: 'string' } },
+  },
+  {
+    name: 'merchant_shopify_migrate',
+    description: 'Migrate a Shopify store to EpicMerch. stage="extract" fetches Shopify data and returns a preview diff + sessionId. stage="import" runs the actual import for an approved sessionId.',
+    schema: {
+      stage: { type: 'string' },
+      shopifyStore: { type: 'string' },
+      shopifyKey: { type: 'string' },
+      sessionId: { type: 'string' },
+    },
+  },
+];
+
+export const merchantToolDefs = withExamples(_baseMerchantToolDefs);