@charisol/plexo-mcp 1.0.9 → 1.0.11

package/src/commerceTools.ts

@@ -0,0 +1,538 @@
+import { PlexoClient } from "./client/plexoClient.js";
+
+const DIGITAL_PRODUCT_NOTE =
+  "For a DIGITAL product, digitalDeliveryMethod is required (FILE_DOWNLOAD, EXTERNAL_LINK, or ACCESS_LIST), plus the matching field: digitalFileUrl (FILE_DOWNLOAD — a URL already uploaded via the dashboard's file upload; this tool cannot itself accept raw file bytes), digitalExternalUrl (EXTERNAL_LINK), or digitalAccessInstructions (ACCESS_LIST, optionally with digitalAccessPassword).";
+
+export const COMMERCE_TOOL_DEFS = [
+  {
+    name: "list_commerce_products",
+    description: "Lists a site's Commerce products (physical, service, or digital), most recently created first.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        kind: { type: "string", enum: ["PHYSICAL", "SERVICE", "DIGITAL"], description: "Optional kind filter." },
+        activeOnly: { type: "boolean", description: "If true, only returns products that aren't soft-deleted/deactivated." },
+      },
+      required: ["templateId"],
+    },
+  },
+  {
+    name: "get_commerce_product",
+    description: "Fetches one Commerce product's full details by id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        productId: { type: "string" },
+      },
+      required: ["templateId", "productId"],
+    },
+  },
+  {
+    name: "create_commerce_product",
+    description: `Creates a Commerce product. ${DIGITAL_PRODUCT_NOTE}`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        name: { type: "string" },
+        description: { type: "string" },
+        kind: { type: "string", enum: ["PHYSICAL", "SERVICE", "DIGITAL"] },
+        priceMinor: { type: "number", description: "Price in the smallest currency unit (e.g. kobo/cents)." },
+        imageUrl: { type: "string" },
+        category: { type: "string", description: "Category name — created if it doesn't already exist." },
+        stockQuantity: { type: "number", description: "PHYSICAL only." },
+        durationMinutes: { type: "number", description: "SERVICE only." },
+        digitalDeliveryMethod: { type: "string", enum: ["FILE_DOWNLOAD", "EXTERNAL_LINK", "ACCESS_LIST"] },
+        digitalFileUrl: { type: "string" },
+        digitalFileName: { type: "string" },
+        digitalExternalUrl: { type: "string" },
+        digitalAccessInstructions: { type: "string" },
+        digitalAccessPassword: { type: "string" },
+        digitalMaxDownloads: { type: "number" },
+        digitalLinkExpiryDays: { type: "number" },
+      },
+      required: ["templateId", "name", "kind", "priceMinor"],
+    },
+  },
+  {
+    name: "update_commerce_product",
+    description: `Updates a Commerce product. Only the fields provided are changed. kind can't be changed after creation. ${DIGITAL_PRODUCT_NOTE}`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        productId: { type: "string" },
+        name: { type: "string" },
+        description: { type: "string" },
+        active: { type: "boolean" },
+        priceMinor: { type: "number" },
+        imageUrl: { type: "string" },
+        category: { type: "string" },
+        stockQuantity: { type: "number" },
+        durationMinutes: { type: "number" },
+        digitalDeliveryMethod: { type: "string", enum: ["FILE_DOWNLOAD", "EXTERNAL_LINK", "ACCESS_LIST"] },
+        digitalFileUrl: { type: "string" },
+        digitalFileName: { type: "string" },
+        digitalExternalUrl: { type: "string" },
+        digitalAccessInstructions: { type: "string" },
+        digitalAccessPassword: { type: "string" },
+        digitalMaxDownloads: { type: "number" },
+        digitalLinkExpiryDays: { type: "number" },
+      },
+      required: ["templateId", "productId"],
+    },
+  },
+  {
+    name: "delete_commerce_product",
+    description: "Soft-deletes (deactivates) a Commerce product.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        productId: { type: "string", description: "The product to deactivate." },
+      },
+      required: ["templateId", "productId"],
+    },
+  },
+  {
+    name: "get_commerce_settings",
+    description: "Fetches a site's Commerce settings: enabled state, storefront slug/URL, store currency, payment provider, Paystack/Stripe mode/keys (masked), MailDrip config, and notification email.",
+    inputSchema: {
+      type: "object",
+      properties: { templateId: { type: "string", description: "The site's home page template id." } },
+      required: ["templateId"],
+    },
+  },
+  {
+    name: "update_commerce_settings",
+    description: `Updates a site's Commerce settings. Only the fields provided are changed. paymentProvider: BYO_PAYSTACK (default — the site's own Paystack keys below), PLATFORM_PAYSTACK (Plexo's own Paystack account, no keys needed, proceeds credit the Commerce wallet), BYO_STRIPE (the site's own Stripe keys below), or PLATFORM_STRIPE (Plexo's own Stripe account — requires prior approval, see request_commerce_stripe_access/get_commerce_stripe_access_status). currency can't be changed once the site has any orders. Setting enabled:true auto-provisions a working storefront (shop grid, checkout, order confirmation, order tracking) at /store if one doesn't exist yet — rename its URL any time with storefrontSlug.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        enabled: { type: "boolean", description: "Master on/off switch for Commerce on this site." },
+        storefrontSlug: { type: "string", description: "Renames the auto-provisioned storefront page's URL segment (default \"store\", i.e. /store). Commerce must already be enabled. The order-confirmation and track-order pages are never renameable." },
+        currency: { type: "string", description: "Site-wide store currency (ISO 4217, e.g. NGN/USD/GBP/EUR/GHS/KES/ZAR). Set this before taking orders — it can't be changed afterward." },
+        paymentProvider: { type: "string", enum: ["BYO_PAYSTACK", "PLATFORM_PAYSTACK", "PLATFORM_STRIPE", "BYO_STRIPE"] },
+        paystackMode: { type: "string", enum: ["TEST", "LIVE"], description: "Which BYO Paystack key pair is active." },
+        paystackTestPublicKey: { type: "string" },
+        paystackTestSecretKey: { type: "string" },
+        paystackLivePublicKey: { type: "string" },
+        paystackLiveSecretKey: { type: "string" },
+        stripeMode: { type: "string", enum: ["TEST", "LIVE"], description: "Which BYO Stripe key pair is active." },
+        stripeTestPublishableKey: { type: "string" },
+        stripeTestSecretKey: { type: "string" },
+        stripeTestWebhookSecret: { type: "string" },
+        stripeLivePublishableKey: { type: "string" },
+        stripeLiveSecretKey: { type: "string" },
+        stripeLiveWebhookSecret: { type: "string" },
+        maildripApiKey: { type: "string" },
+        maildripPaidGroupId: { type: "string" },
+        maildripNewsletterGroupId: { type: "string" },
+        notificationEmail: { type: "string" },
+      },
+      required: ["templateId"],
+    },
+  },
+  {
+    name: "list_commerce_orders",
+    description: "Lists a site's Commerce orders (25 per page, most recent first), with optional status/search filters.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        status: { type: "string", enum: ["PENDING", "PAID", "FAILED", "REFUNDED", "CANCELLED"], description: "Optional status filter." },
+        q: { type: "string", description: "Optional search across order number, customer email, and customer name." },
+        page: { type: "number", description: "1-indexed page number." },
+      },
+      required: ["templateId"],
+    },
+  },
+  {
+    name: "get_commerce_order",
+    description: "Fetches one Commerce order's full details, including line items, booking (if a service), and digital deliveries (if any digital items).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        orderId: { type: "string" },
+      },
+      required: ["templateId", "orderId"],
+    },
+  },
+  {
+    name: "update_commerce_order",
+    description: "Updates an order's fulfillment status (UNFULFILLED/PROCESSING/READY_FOR_PICKUP/SHIPPED/COMPLETED). Payment status is never settable here — it only changes via the payment webhook or refund_commerce_order.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        orderId: { type: "string" },
+        fulfillmentStatus: { type: "string", enum: ["UNFULFILLED", "PROCESSING", "READY_FOR_PICKUP", "SHIPPED", "COMPLETED"] },
+      },
+      required: ["templateId", "orderId", "fulfillmentStatus"],
+    },
+  },
+  {
+    name: "refund_commerce_order",
+    description: "Refunds a PAID order through the Paystack account it was actually paid through. Paystack-only today — a PLATFORM_STRIPE-paid order will error, since that refund path doesn't exist yet. Does not restock inventory or free a booking slot; that's a separate deliberate decision.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        orderId: { type: "string" },
+      },
+      required: ["templateId", "orderId"],
+    },
+  },
+  {
+    name: "resend_digital_delivery",
+    description: "Re-sends a digital product's delivery email for an already-paid order, using its existing access link (never generates a new one). Use get_commerce_order first to find the deliveryId.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        orderId: { type: "string", description: "The order." },
+        deliveryId: { type: "string", description: "The digital delivery id (from get_commerce_order's digitalDeliveries)." },
+      },
+      required: ["templateId", "orderId", "deliveryId"],
+    },
+  },
+  {
+    name: "get_commerce_wallet",
+    description: "Fetches a site's (or its org's pooled) Commerce wallet balance and recent ledger — the withdrawable balance from Platform Paystack/Platform Stripe sales.",
+    inputSchema: {
+      type: "object",
+      properties: { templateId: { type: "string", description: "The site's home page template id." } },
+      required: ["templateId"],
+    },
+  },
+  {
+    name: "list_commerce_withdrawals",
+    description: "Lists the Commerce wallet's withdrawal requests and their status (PENDING/PROCESSED/REJECTED — processed manually by the Plexo team).",
+    inputSchema: {
+      type: "object",
+      properties: { templateId: { type: "string", description: "The site's home page template id." } },
+      required: ["templateId"],
+    },
+  },
+  {
+    name: "request_commerce_withdrawal",
+    description: "Requests a manual bank-transfer payout of the Commerce wallet balance. Reserves the amount immediately; processed manually by the Plexo team.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        amountCents: { type: "number", description: "Amount to withdraw, in the smallest currency unit." },
+        accountNumber: { type: "string" },
+        accountHolderName: { type: "string" },
+        bankName: { type: "string" },
+      },
+      required: ["templateId", "amountCents", "accountNumber", "accountHolderName", "bankName"],
+    },
+  },
+  {
+    name: "get_commerce_stripe_access_status",
+    description: "Reports the organization's current standing to use Platform Stripe for Commerce checkout (NONE/PENDING/APPROVED/REJECTED). Org-scoped, not per-site.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "request_commerce_stripe_access",
+    description: "Requests staff approval to route Commerce checkout through Plexo's own Stripe account for international payments. Org-scoped — approval covers every site in the organization once granted.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        reason: { type: "string", description: "Optional — why Stripe is needed." },
+        expectedVolume: { type: "string", description: "Optional — expected monthly volume." },
+      },
+    },
+  },
+  {
+    name: "list_commerce_delivery_methods",
+    description: "Lists a site's configured delivery/fulfillment methods (pickup and/or courier options with fees and country/state restrictions), sorted by their display order.",
+    inputSchema: {
+      type: "object",
+      properties: { templateId: { type: "string", description: "The site's home page template id." } },
+      required: ["templateId"],
+    },
+  },
+  {
+    name: "create_commerce_delivery_method",
+    description: "Creates a delivery/fulfillment method a customer can choose at checkout.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        name: { type: "string", description: "Shown to the customer at checkout, e.g. \"Store Pickup\" or \"Lagos Courier\"." },
+        type: { type: "string", enum: ["PICKUP", "COURIER"] },
+        feeMinor: { type: "number", description: "Fee in the smallest currency unit. Defaults to 0." },
+        description: { type: "string" },
+        countries: { type: "array", items: { type: "string" }, description: "ISO-3166-1 alpha-2 codes this method is restricted to. Omit/empty for worldwide." },
+        states: { type: "array", items: { type: "string" }, description: "State/region names this method is restricted to. Omit/empty for unrestricted." },
+        estimatedTimeLabel: { type: "string", description: "e.g. \"2-3 business days\"." },
+        sortOrder: { type: "number" },
+      },
+      required: ["templateId", "name", "type"],
+    },
+  },
+  {
+    name: "update_commerce_delivery_method",
+    description: "Updates a delivery method. Only the fields provided are changed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        deliveryMethodId: { type: "string" },
+        name: { type: "string" },
+        type: { type: "string", enum: ["PICKUP", "COURIER"] },
+        feeMinor: { type: "number" },
+        description: { type: "string", description: "Empty string clears it." },
+        countries: { type: "array", items: { type: "string" }, description: "Empty array clears the restriction (worldwide)." },
+        states: { type: "array", items: { type: "string" }, description: "Empty array clears the restriction." },
+        estimatedTimeLabel: { type: "string" },
+        status: { type: "string", enum: ["ACTIVE", "INACTIVE"] },
+        sortOrder: { type: "number" },
+      },
+      required: ["templateId", "deliveryMethodId"],
+    },
+  },
+  {
+    name: "delete_commerce_delivery_method",
+    description: "Permanently deletes a delivery method.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        deliveryMethodId: { type: "string" },
+      },
+      required: ["templateId", "deliveryMethodId"],
+    },
+  },
+  {
+    name: "resolve_bank_transfer_order",
+    description: "Confirms or rejects a bank-transfer order that's waiting for payment (status PENDING, paymentMethod BANK_TRANSFER). action \"confirm\" marks it PAID and runs the normal paid flow (customer confirmation email, digital delivery, booking confirmed) — only use it once the site owner says the money has actually arrived in their account. action \"reject\" cancels it, releases its stock/booking slot, and emails the customer (optional reason is included).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        orderId: { type: "string" },
+        action: { type: "string", enum: ["confirm", "reject"] },
+        reason: { type: "string", description: "Optional note to the customer when rejecting." },
+      },
+      required: ["templateId", "orderId", "action"],
+    },
+  },
+  {
+    name: "list_commerce_discounts",
+    description: "Lists a site's discount codes, most recently created first.",
+    inputSchema: {
+      type: "object",
+      properties: { templateId: { type: "string", description: "The site's home page template id." } },
+      required: ["templateId"],
+    },
+  },
+  {
+    name: "create_commerce_discount",
+    description: "Creates a discount code customers can redeem at checkout.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        code: { type: "string", description: "Case-insensitive; stored uppercased. Must be unique on this site." },
+        type: { type: "string", enum: ["PERCENT", "FIXED"] },
+        value: { type: "number", description: "A positive integer. For PERCENT, out of 100 (and can't exceed 100). For FIXED, the smallest currency unit." },
+        expiresAt: { type: "string", description: "Optional ISO 8601 date/time after which the code stops working." },
+        usageLimit: { type: "number", description: "Optional max number of redemptions." },
+      },
+      required: ["templateId", "code", "type", "value"],
+    },
+  },
+  {
+    name: "update_commerce_discount",
+    description: "Updates a discount code's active state, expiry, or usage limit. code/type/value can't be changed once created — delete and recreate instead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        discountId: { type: "string" },
+        active: { type: "boolean" },
+        expiresAt: { type: "string", description: "Empty string clears the expiry." },
+        usageLimit: { type: "number", description: "0 or omitted-as-empty clears the limit." },
+      },
+      required: ["templateId", "discountId"],
+    },
+  },
+  {
+    name: "delete_commerce_discount",
+    description: "Permanently deletes a discount code.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        discountId: { type: "string" },
+      },
+      required: ["templateId", "discountId"],
+    },
+  },
+  {
+    name: "list_commerce_customers",
+    description: "Lists everyone who's completed a paid order with this site, aggregated from its own orders (works for Stripe or Paystack, however the customer paid).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        templateId: { type: "string", description: "The site's home page template id." },
+        page: { type: "number", description: "1-indexed page number." },
+      },
+      required: ["templateId"],
+    },
+  },
+];
+
+export const COMMERCE_TOOL_NAMES = new Set(COMMERCE_TOOL_DEFS.map((t) => t.name));
+
+export async function handleCommerceToolCall(name: string, args: any, client: PlexoClient): Promise<any> {
+  const templateId = typeof args?.templateId === "string" ? args.templateId : "";
+
+  switch (name) {
+    case "list_commerce_products":
+      return await client.listCommerceProducts(templateId, { kind: args.kind, activeOnly: args.activeOnly });
+
+    case "get_commerce_product":
+      if (!args.productId) throw new Error("productId is required.");
+      return await client.getCommerceProduct(templateId, args.productId);
+
+    case "create_commerce_product": {
+      const { templateId: _t, ...payload } = args;
+      const result = await client.createCommerceProduct(templateId, payload);
+      return { success: true, product: result.product };
+    }
+
+    case "update_commerce_product": {
+      if (!args.productId) throw new Error("productId is required.");
+      const { templateId: _t, productId, ...payload } = args;
+      const result = await client.updateCommerceProduct(templateId, productId, payload);
+      return { success: true, product: result.product };
+    }
+
+    case "delete_commerce_product":
+      if (!args.productId) throw new Error("productId is required.");
+      await client.deleteCommerceProduct(templateId, args.productId);
+      return { success: true, deletedProductId: args.productId };
+
+    case "get_commerce_settings":
+      return await client.getCommerceSettings(templateId);
+
+    case "update_commerce_settings": {
+      const { templateId: _t, ...payload } = args;
+      return await client.updateCommerceSettings(templateId, payload);
+    }
+
+    case "list_commerce_orders":
+      return await client.listCommerceOrders(templateId, { status: args.status, q: args.q, page: args.page });
+
+    case "get_commerce_order":
+      if (!args.orderId) throw new Error("orderId is required.");
+      return await client.getCommerceOrder(templateId, args.orderId);
+
+    case "update_commerce_order": {
+      if (!args.orderId || !args.fulfillmentStatus) throw new Error("orderId and fulfillmentStatus are required.");
+      const result = await client.updateCommerceOrder(templateId, args.orderId, args.fulfillmentStatus);
+      return { success: true, order: result.order };
+    }
+
+    case "refund_commerce_order": {
+      if (!args.orderId) throw new Error("orderId is required.");
+      const result = await client.refundCommerceOrder(templateId, args.orderId);
+      return { success: true, order: result.order };
+    }
+
+    case "resend_digital_delivery":
+      if (!args.orderId || !args.deliveryId) throw new Error("orderId and deliveryId are required.");
+      return await client.resendDigitalDelivery(templateId, args.orderId, args.deliveryId);
+
+    case "get_commerce_wallet":
+      return await client.getCommerceWallet(templateId);
+
+    case "list_commerce_withdrawals":
+      return await client.listCommerceWithdrawals(templateId);
+
+    case "request_commerce_withdrawal": {
+      if (!args.amountCents || !args.accountNumber || !args.accountHolderName || !args.bankName) {
+        throw new Error("amountCents, accountNumber, accountHolderName, and bankName are required.");
+      }
+      const result = await client.requestCommerceWithdrawal(templateId, {
+        amountCents: args.amountCents,
+        accountNumber: args.accountNumber,
+        accountHolderName: args.accountHolderName,
+        bankName: args.bankName,
+      });
+      return { success: true, request: result.request };
+    }
+
+    case "get_commerce_stripe_access_status":
+      return await client.getCommerceStripeAccessStatus();
+
+    case "request_commerce_stripe_access":
+      return await client.requestCommerceStripeAccess({ reason: args.reason, expectedVolume: args.expectedVolume });
+
+    case "list_commerce_delivery_methods":
+      return await client.listCommerceDeliveryMethods(templateId);
+
+    case "create_commerce_delivery_method": {
+      if (!args.name || !args.type) throw new Error("name and type are required.");
+      const { templateId: _t, ...payload } = args;
+      const result = await client.createCommerceDeliveryMethod(templateId, payload);
+      return { success: true, method: result.method };
+    }
+
+    case "update_commerce_delivery_method": {
+      if (!args.deliveryMethodId) throw new Error("deliveryMethodId is required.");
+      const { templateId: _t, deliveryMethodId, ...payload } = args;
+      const result = await client.updateCommerceDeliveryMethod(templateId, deliveryMethodId, payload);
+      return { success: true, method: result.method };
+    }
+
+    case "delete_commerce_delivery_method":
+      if (!args.deliveryMethodId) throw new Error("deliveryMethodId is required.");
+      await client.deleteCommerceDeliveryMethod(templateId, args.deliveryMethodId);
+      return { success: true, deletedDeliveryMethodId: args.deliveryMethodId };
+
+    case "resolve_bank_transfer_order": {
+      const orderId = typeof args.orderId === "string" ? args.orderId.trim() : "";
+      if (!orderId) throw new Error("orderId is required.");
+      if (args.action !== "confirm" && args.action !== "reject") throw new Error('action must be "confirm" or "reject".');
+      const result = await client.resolveBankTransferOrder(templateId, orderId, args.action, typeof args.reason === "string" ? args.reason : undefined);
+      return { success: true, order: result.order };
+    }
+
+    case "list_commerce_discounts":
+      return await client.listCommerceDiscounts(templateId);
+
+    case "create_commerce_discount": {
+      if (!args.code || !args.type || !args.value) throw new Error("code, type, and value are required.");
+      const { templateId: _t, ...payload } = args;
+      const result = await client.createCommerceDiscount(templateId, payload);
+      return { success: true, discount: result.discount };
+    }
+
+    case "update_commerce_discount": {
+      if (!args.discountId) throw new Error("discountId is required.");
+      const { templateId: _t, discountId, ...payload } = args;
+      const result = await client.updateCommerceDiscount(templateId, discountId, payload);
+      return { success: true, discount: result.discount };
+    }
+
+    case "delete_commerce_discount":
+      if (!args.discountId) throw new Error("discountId is required.");
+      await client.deleteCommerceDiscount(templateId, args.discountId);
+      return { success: true, deletedDiscountId: args.discountId };
+
+    case "list_commerce_customers":
+      return await client.listCommerceCustomers(templateId, args.page);
+
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}

package/src/donationTools.ts

@@ -0,0 +1,98 @@
+import { PlexoClient } from "./client/plexoClient.js";
+
+// Plexo Donations — same tools, same descriptions as the live connector in plexo-web
+// (lib/mcp/donationTools.ts), executed through plexo-web's REST API. Amounts are in the
+// smallest currency unit, like every other Commerce tool.
+
+const CAMPAIGN_FIELDS = {
+  name: { type: "string", description: "What donors are giving to, e.g. 'Support our mission'." },
+  description: { type: "string", description: "Optional one-line description shown on the form." },
+  presetAmounts: {
+    type: "array",
+    description: "Suggested amounts in the smallest currency unit, optionally named — e.g. [{\"amountMinor\":2500,\"label\":\"Bronze\"},{\"amountMinor\":5000}].",
+    items: { type: "object", properties: { amountMinor: { type: "number" }, label: { type: "string" } }, required: ["amountMinor"] },
+  },
+  defaultPresetIndex: { type: "number", description: "Which suggested amount is pre-selected (0-based)." },
+  allowCustomAmount: { type: "boolean", description: "Let donors type their own amount (default true)." },
+  minAmountMinor: { type: "number", description: "Smallest custom amount, smallest currency unit (default 100)." },
+  allowMonthly: { type: "boolean", description: "Offer monthly giving (default true; needs Stripe or Paystack connected)." },
+  defaultFrequency: { type: "string", enum: ["ONCE", "MONTHLY"], description: "Which frequency is pre-selected." },
+  goalAmountMinor: { type: ["number", "null"], description: "Optional fundraising goal — shows a progress bar." },
+  thankYouMessage: { type: "string", description: "Shown after donating and in the receipt email." },
+  buttonLabel: { type: "string", description: "Donate button text (default 'Donate')." },
+};
+
+export const DONATION_TOOL_DEFS = [
+  {
+    name: "list_donations",
+    description:
+      "Shows a site's donations: totals (raised, donors, monthly donors), every donation form (campaign) with its amounts and progress, monthly donors, and recent gifts. Also says whether payments are connected yet (paymentsReady) — if not, tell the owner to connect Stripe/Paystack or add bank details in Commerce → Settings → Payments.",
+    inputSchema: { type: "object", properties: { templateId: { type: "string", description: "The site's home page id (see list_landing_pages)." } }, required: ["templateId"] },
+  },
+  {
+    name: "create_donation_campaign",
+    description:
+      "Creates a donation form (campaign) for a site — one-time and optional monthly giving — and switches on everything donations need (no shop is created). Returns the campaign id and the embed snippet `<div data-plexo-donation=\"<id>\"></div>`: add that HTML to any page (e.g. via update_landing_page_page or a raw HTML page) to show a working donate form styled to the site.",
+    inputSchema: { type: "object", properties: { templateId: { type: "string", description: "The site's home page id." }, ...CAMPAIGN_FIELDS }, required: ["templateId", "name", "presetAmounts"] },
+  },
+  {
+    name: "update_donation_campaign",
+    description: "Edits a donation campaign. Only the fields you pass change. Pass active:false to turn a form off (gifts history is kept).",
+    inputSchema: {
+      type: "object",
+      properties: { templateId: { type: "string" }, campaignId: { type: "string" }, active: { type: "boolean" }, ...CAMPAIGN_FIELDS },
+      required: ["templateId", "campaignId"],
+    },
+  },
+  {
+    name: "cancel_monthly_donation",
+    description: "Stops one donor's monthly gift (at Stripe/Paystack too) — they won't be charged again. Only do this when the owner asks; confirm the donor first using list_donations.",
+    inputSchema: { type: "object", properties: { templateId: { type: "string" }, subscriptionId: { type: "string", description: "From list_donations' monthlyDonors[].id." } }, required: ["templateId", "subscriptionId"] },
+  },
+  {
+    name: "adopt_monthly_donors",
+    description:
+      "Brings monthly donors over from a previous website: finds active monthly gifts on the site's connected Stripe/Paystack account that Plexo doesn't know yet and records them under a campaign, so every future charge is receipted and counted. Donors don't have to do anything. Requires the SAME payment account the old site used to be connected.",
+    inputSchema: { type: "object", properties: { templateId: { type: "string" }, campaignId: { type: "string" } }, required: ["templateId", "campaignId"] },
+  },
+];
+
+export const DONATION_TOOL_NAMES = new Set(DONATION_TOOL_DEFS.map((t) => t.name));
+
+export async function handleDonationToolCall(name: string, args: any, client: PlexoClient): Promise<any> {
+  const templateId = typeof args?.templateId === "string" ? args.templateId.trim() : "";
+  if (!templateId) throw new Error("templateId is required — pass the site's home page id (see list_landing_pages).");
+  const { templateId: _t, campaignId, subscriptionId, ...fields } = args ?? {};
+  switch (name) {
+    case "list_donations":
+      return await client.listDonations(templateId);
+
+    case "create_donation_campaign": {
+      const { campaign } = await client.createDonationCampaign(templateId, fields);
+      const overview = await client.listDonations(templateId);
+      return {
+        campaign,
+        embedHtml: `<div data-plexo-donation="${campaign.id}"></div>`,
+        paymentsReady: overview.paymentsReady,
+        next: overview.paymentsReady
+          ? "Add embedHtml to the page where donors should give."
+          : "Add embedHtml to a page, and ask the owner to connect Stripe/Paystack (or add bank details) in Commerce → Settings → Payments — the form shows 'being set up' until then.",
+      };
+    }
+
+    case "update_donation_campaign": {
+      if (!campaignId) throw new Error("campaignId is required — use list_donations for ids.");
+      const { campaign } = await client.updateDonationCampaign(templateId, String(campaignId), fields);
+      return { updated: true, campaign };
+    }
+
+    case "cancel_monthly_donation":
+      if (!subscriptionId) throw new Error("subscriptionId is required — use list_donations' monthlyDonors[].id.");
+      return await client.cancelMonthlyDonation(templateId, String(subscriptionId));
+
+    case "adopt_monthly_donors":
+      if (!campaignId) throw new Error("campaignId is required — use list_donations for ids.");
+      return await client.adoptMonthlyDonors(templateId, String(campaignId));
+  }
+  throw new Error(`Unknown tool: ${name}`);
+}