@usethrottle/mcp 0.1.1 → 0.2.1

package/dist/lib.cjs

@@ -0,0 +1,3328 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib.ts
+var lib_exports = {};
+__export(lib_exports, {
+  ThrottleClient: () => ThrottleClient,
+  VERSION: () => VERSION,
+  buildInstructions: () => buildInstructions,
+  createServer: () => createServer,
+  loadContractIndex: () => loadContractIndex,
+  loadDocsIndex: () => loadDocsIndex,
+  registerableActions: () => registerableActions
+});
+module.exports = __toCommonJS(lib_exports);
+
+// src/server.ts
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_types = require("@modelcontextprotocol/sdk/types.js");
+
+// ../core-scopes/src/scopes.ts
+function hasScope(granted, required) {
+  if (granted.includes("*")) return true;
+  if (granted.includes(required)) return true;
+  const sep = required.lastIndexOf(":");
+  if (sep === -1) return false;
+  const resource = required.slice(0, sep);
+  const action = required.slice(sep + 1);
+  if (action === "read" && granted.includes(`${resource}:write`)) return true;
+  return false;
+}
+var REG = {};
+function add(group, resource, actions, labels, opts = {}) {
+  const hasRead = actions.includes("read");
+  for (const action of actions) {
+    const id = `${resource}:${action}`;
+    const implies = action === "write" && hasRead ? [`${resource}:read`] : [];
+    REG[id] = {
+      id,
+      resource,
+      action,
+      group,
+      label: (action === "read" ? labels.read : labels.write) ?? `${action} ${resource}`,
+      sensitive: opts.sensitive ?? false,
+      staffOnly: opts.staffOnly ?? false,
+      // publishable defaults false; only the curated set below is true
+      publishableAllowed: opts.publishableAllowed ?? false,
+      // publishableOnly defaults false; only customer_accounts:write sets it
+      publishableOnly: opts.publishableOnly ?? false,
+      // extension default true for commerce scopes; Taxonomy B passes false
+      extensionAllowed: opts.extensionAllowed ?? true,
+      implies
+    };
+  }
+}
+add("Orders", "orders", ["read", "write"], { read: "View orders", write: "Manage orders" });
+add("Quotes", "quotes", ["read", "write"], { read: "View quotes", write: "Manage quotes" });
+add("Orders", "order_cancellations", ["write"], { write: "Cancel orders" });
+add("Orders", "order_returns", ["read", "write"], { read: "View returns", write: "Process returns" });
+add("Orders", "order_comps", ["write"], { write: "Comp orders (write off the balance)" }, { sensitive: true });
+add("Orders", "order_holds", ["write"], { write: "Freeze and unfreeze orders" });
+add(
+  "Imports",
+  "imports",
+  ["read", "write"],
+  { read: "View data imports", write: "Run and undo data imports" },
+  { extensionAllowed: false }
+);
+add("Payments", "payments", ["read", "write"], { read: "View payments", write: "Create payments" });
+add("Payments", "payment_authorizations", ["write"], { write: "Authorize payments" });
+add("Payments", "payment_captures", ["write"], { write: "Capture payments" });
+add("Payments", "payment_refunds", ["read", "write"], { read: "View refunds", write: "Refund payments" }, { sensitive: true });
+add("Payments", "payment_voids", ["write"], { write: "Void payments" }, { sensitive: true });
+add("Payments", "payment_records", ["write"], { write: "Record payments received outside Throttle" }, { sensitive: true });
+add("Payments", "payment_disputes", ["read", "write"], { read: "View disputes", write: "Handle disputes" }, { sensitive: true });
+add("Payments", "payment_methods", ["read", "write"], { read: "View payment methods", write: "Tokenize payment methods" }, { sensitive: true });
+add("Customers", "customers", ["read", "write"], { read: "View customers", write: "Manage customers" });
+add("Customers", "customer_pii", ["read"], { read: "View customer PII" }, { sensitive: true });
+add("Customers", "customer_addresses", ["read", "write"], { read: "View addresses", write: "Manage addresses" });
+add("Customers", "customer_payment_methods", ["read", "write"], { read: "View stored cards", write: "Manage stored cards" }, { sensitive: true });
+add(
+  "Customer accounts",
+  "customer_accounts",
+  ["write"],
+  { write: "Let shoppers register, sign in and manage their account" },
+  { publishableAllowed: true, publishableOnly: true, extensionAllowed: false }
+);
+add("Carts", "carts", ["read", "write"], { read: "View carts", write: "Manage carts" });
+add("Carts", "cart_items", ["write"], { write: "Manage line items" });
+add("Carts", "checkout_sessions", ["read", "write"], { read: "View checkout sessions", write: "Manage checkout sessions" });
+add("Discounts", "discounts", ["read", "write"], { read: "View discounts", write: "Manage discounts" });
+add("Subscriptions", "subscriptions", ["read", "write"], { read: "View subscriptions", write: "Manage subscriptions" });
+add("Subscriptions", "subscription_pauses", ["write"], { write: "Pause/resume subscriptions" });
+add("Subscriptions", "subscription_cancellations", ["write"], { write: "Cancel subscriptions" });
+add("Subscriptions", "subscription_usage", ["read", "write"], { read: "View subscription usage", write: "Report subscription usage" }, { extensionAllowed: false });
+add("Fulfillments", "fulfillments", ["read", "write"], { read: "View fulfillments", write: "Manage fulfillments" });
+add("Fulfillments", "fulfillment_shipments", ["write"], { write: "Update shipments" });
+add("Fulfillments", "fulfillment_digital", ["read", "write"], { read: "View digital delivery", write: "Manage digital delivery" });
+add("Fulfillments", "fulfillment_access", ["write"], { write: "Manage access credentials" });
+add("Fulfillments", "fulfillment_services", ["write"], { write: "Manage service fulfillment" });
+add("Invoices / AR", "invoices", ["read"], { read: "View invoices & aging" });
+add("Invoices / AR", "invoice_payments", ["write"], { write: "Mark invoices paid" }, { sensitive: true });
+add("Invoices / AR", "invoice_dunning", ["write"], { write: "Send dunning notices" });
+add("Shipping & Tax", "shipping_tax", ["read", "write"], { read: "View shipping/tax config", write: "Edit shipping/tax config" });
+add("Shipping & Tax", "shipping_tax_publications", ["write"], { write: "Publish shipping/tax config" });
+add("Shipping & Tax", "shipping_quotes", ["write"], { write: "Request shipping quotes" }, { publishableAllowed: true });
+add("Shipping & Tax", "tax_calculations", ["write"], { write: "Calculate tax" }, { publishableAllowed: true });
+add("Shipping & Tax", "shipping_tax_quote_tokens", ["read", "write"], { read: "View quote tokens", write: "Manage quote tokens" });
+add("Shipping & Tax", "shipping_tax_snapshots", ["write"], { write: "Accept external snapshots" });
+add(
+  "Scripts",
+  "storefront_scripts",
+  ["read", "write"],
+  {
+    read: "Load storefront scripts",
+    // `write` covers exactly one thing: reporting a script's own load outcome
+    // from the merchant's storefront, so the health panel stops being
+    // hosted-checkout-only. On checkout the session id in the URL is the
+    // capability that scopes that write; a storefront page has no session, so
+    // the pk it already holds is what scopes it instead. It writes nothing but
+    // load telemetry — authoring stays on `application_scripts:write`, which
+    // is not publishable-allowed.
+    write: "Report storefront script load outcomes"
+  },
+  { publishableAllowed: true }
+);
+add("Scripts", "application_scripts", ["read", "write"], {
+  read: "View merchant-authored scripts",
+  write: "Create, edit and disable merchant-authored scripts"
+}, { extensionAllowed: false });
+add("Scripts", "extension_scripts", ["read", "write"], {
+  read: "View an extension's buyer-facing scripts",
+  write: "Create, edit and delete an extension's buyer-facing scripts"
+}, { extensionAllowed: false });
+add("Connectors", "connectors", ["read", "write"], { read: "View connectors", write: "Manage connectors" });
+add("Webhooks & Events", "webhooks", ["read", "write"], { read: "View webhooks", write: "Manage webhooks" });
+add("Webhooks & Events", "webhook_deliveries", ["read", "write"], { read: "View deliveries", write: "Retry deliveries" });
+add("Webhooks & Events", "events", ["read"], { read: "View events" });
+add("Webhooks & Events", "audit_logs", ["read"], { read: "View audit log" });
+add("Applications", "applications", ["read", "write"], { read: "View applications", write: "Manage applications" });
+add("Workspace", "merchant", ["read", "write"], { read: "View workspace settings", write: "Edit workspace settings" });
+add("Workspace", "embed_config", ["read", "write"], { read: "View embed config", write: "Edit embed config" });
+add("Workspace", "branding", ["write"], { write: "Upload branding assets" });
+var HUMAN = { extensionAllowed: false };
+add("Team", "team_members", ["read", "write"], { read: "View members", write: "Manage members" }, HUMAN);
+add("Team", "team_invites", ["read", "write"], { read: "View invites", write: "Manage invites" }, HUMAN);
+add("Platform billing", "billing", ["read", "write"], { read: "View billing", write: "Manage subscription" }, HUMAN);
+add("Platform billing", "billing_payment_methods", ["read", "write"], { read: "View billing cards", write: "Manage billing cards" }, HUMAN);
+add("Email", "email_templates", ["read", "write"], { read: "View email templates", write: "Edit email templates" }, HUMAN);
+add("Email", "email_settings", ["read", "write"], { read: "View email settings", write: "Edit email settings" }, HUMAN);
+add("Go-live", "go_live", ["write"], { write: "Submit go-live" }, HUMAN);
+add("Partner", "partner", ["read", "write"], { read: "View partner profile", write: "Edit partner profile" }, HUMAN);
+add("Partner", "affiliates", ["read", "write"], { read: "View affiliates", write: "Manage affiliates" }, HUMAN);
+add("Notifications", "notifications", ["write"], { write: "Send notifications" }, HUMAN);
+add("Notifications", "preferences", ["read", "write"], { read: "View preferences", write: "Edit preferences" }, HUMAN);
+add("Integrations", "integrations", ["read", "write"], { read: "View integrations", write: "Manage integrations" }, HUMAN);
+add("Support", "support", ["read", "write"], { read: "View support tickets", write: "Manage support tickets" }, HUMAN);
+add("Admin (staff)", "admin", ["read", "write"], { read: "View admin data", write: "Perform admin actions" }, { sensitive: true, staffOnly: true, extensionAllowed: false });
+add(
+  "Extensions",
+  "extensions",
+  ["read", "write"],
+  { read: "View extensions & installs", write: "Author, version & publish extensions" },
+  HUMAN
+);
+REG["extensions:install"] = {
+  id: "extensions:install",
+  resource: "extensions",
+  action: "install",
+  group: "Extensions",
+  label: "Install, configure & manage extensions",
+  sensitive: false,
+  staffOnly: false,
+  publishableAllowed: false,
+  publishableOnly: false,
+  extensionAllowed: false,
+  implies: []
+};
+REG["*"] = {
+  id: "*",
+  resource: "*",
+  action: "write",
+  group: "Global",
+  label: "Full access",
+  sensitive: true,
+  staffOnly: false,
+  publishableAllowed: false,
+  publishableOnly: false,
+  extensionAllowed: false,
+  implies: []
+};
+var SCOPE_REGISTRY = REG;
+var ALL_SCOPE_IDS = Object.keys(REG);
+var SCOPE_GROUPS = (() => {
+  const out = {};
+  for (const def of Object.values(REG)) {
+    if (def.id === "*") continue;
+    (out[def.group] ??= []).push(def.id);
+  }
+  return out;
+})();
+
+// ../core-scopes/src/events.ts
+var EVENT_SCOPE_OVERRIDES = {
+  "payment.refunded": "payment_refunds:read",
+  "payment.partially_refunded": "payment_refunds:read",
+  "payment.refund_failed": "payment_refunds:read",
+  // Money returned, so it belongs with the other refund events rather than
+  // behind the broad subscriptions:read the `subscription.` prefix would give.
+  "subscription.invoice_refunded": "payment_refunds:read",
+  "payment.disputed": "payment_disputes:read",
+  "payment.dispute_cleared": "payment_disputes:read",
+  "fulfillment.digital.delivered": "fulfillment_digital:read"
+};
+var PREFIX_RULES = [
+  ["checkout.session.", "carts:read"],
+  ["cart.", "carts:read"],
+  ["order.", "orders:read"],
+  ["quote.", "quotes:read"],
+  ["return.", "order_returns:read"],
+  ["payment.", "payments:read"],
+  ["customer.", "customers:read"],
+  ["subscription.", "subscriptions:read"],
+  ["fulfillment.", "fulfillments:read"],
+  ["discount.", "discounts:read"],
+  ["invoice.", "invoices:read"],
+  ["import.", "imports:read"],
+  ["shipping_tax.", "shipping_tax:read"],
+  ["workspace.", "billing:read"],
+  // `extensions:read` is a human scope (extensions must never watch other
+  // extensions), so only a workspace endpoint can SUBSCRIBE to this family.
+  // The uninstalled installation's own endpoint is addressed directly by the
+  // uninstall path and needs no subscription at all.
+  ["extension.", "extensions:read"],
+  // Subscribing to script outcomes needs script read — the payload names the
+  // script key and its hash, which is the merchant's script inventory.
+  ["script.", "application_scripts:read"]
+];
+function eventReadScope(type) {
+  if (EVENT_SCOPE_OVERRIDES[type]) return EVENT_SCOPE_OVERRIDES[type];
+  for (const [prefix, scope] of PREFIX_RULES) {
+    if (type.startsWith(prefix)) return scope;
+  }
+  throw new Error(`Unknown event type: ${type}`);
+}
+
+// ../core-scopes/src/issuance.ts
+var PUBLISHABLE_SCOPES = Object.values(SCOPE_REGISTRY).filter((d) => d.publishableAllowed).map((d) => d.id);
+var CONNECTOR_GRANTABLE_SENSITIVE_SCOPES = ["customer_pii:read"];
+function validateScopesForOAuth(scopes, opts = {}) {
+  const invalid = [];
+  for (const id of scopes) {
+    if (id === "*") {
+      invalid.push(id);
+      continue;
+    }
+    const def = SCOPE_REGISTRY[id];
+    if (!def || def.staffOnly) {
+      invalid.push(id);
+      continue;
+    }
+    if (def.sensitive && !(opts.connector && CONNECTOR_GRANTABLE_SENSITIVE_SCOPES.includes(id))) invalid.push(id);
+  }
+  return { ok: invalid.length === 0, invalid };
+}
+
+// ../core-scopes/src/shopper-pii.ts
+var PERSON_KEYS = /* @__PURE__ */ new Set([
+  "email",
+  "customerEmail",
+  "billingEmail",
+  "buyerEmail",
+  "authorEmail",
+  "authorName",
+  "phone",
+  "firstName",
+  "lastName",
+  "addressLine1",
+  "addressLine2",
+  "billingAddressLines",
+  "processorResponse",
+  "shareToken",
+  "company",
+  "externalId",
+  "externalCustomerId",
+  // Free-form: contents cannot be inspected for a person, so the field goes.
+  "metadata",
+  "notes",
+  "internalNotes",
+  "buyerNote",
+  "buyerReference",
+  "changeSummary",
+  "declinedReason",
+  "compReason",
+  "holdReason",
+  "body",
+  "acceptance",
+  "acceptanceSelections",
+  "clientContext",
+  "ipAddress",
+  "userAgent",
+  "vatNumber",
+  "buyerVatNumber",
+  "taxExemptionNumber"
+]);
+var PERSON_CONTAINERS = /* @__PURE__ */ new Set(["customer", "buyer"]);
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function walk(value, parentKey, depth) {
+  if (depth > 32) return value;
+  if (Array.isArray(value)) return value.map((item) => walk(item, parentKey, depth + 1));
+  if (!isPlainObject(value)) return value;
+  const out = {};
+  const isPerson = parentKey !== null && PERSON_CONTAINERS.has(parentKey);
+  for (const [key, child] of Object.entries(value)) {
+    if (PERSON_KEYS.has(key) || isPerson && key === "name") {
+      out[key] = child === void 0 ? child : null;
+    } else {
+      out[key] = walk(child, key, depth + 1);
+    }
+  }
+  return out;
+}
+function redactShopperPii(value) {
+  return walk(value, null, 0);
+}
+
+// ../action-catalog/src/actions.ts
+var OAUTH_WITHHELD = "Over an OAuth connection (ChatGPT, Claude) these are withheld, because a buyer can type them: line-item and quote-item names, SKUs and reference ids; company; every address line except the country; the merchant's external ids; notes, messages, reasons and metadata. Describe items by quantity and amount, and say the rest is withheld rather than missing.";
+var ACTIONS = [
+  // ---------------------------------------------------------------- identity
+  {
+    id: "whoami",
+    title: "Identify the connected credential",
+    description: "Report which workspace, application and environment this credential is pinned to, and what it is allowed to do. Call this first when you need to know whether you are talking to production or a sandbox.",
+    kind: "read",
+    scopes: [],
+    input: [],
+    requests: [{ method: "GET", path: "/api/v1/whoami" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  // ------------------------------------------------------- local (no API call)
+  {
+    id: "search_docs",
+    title: "Search the Throttle developer docs",
+    description: "Full-text search over the Throttle developer documentation. Returns titles, canonical usethrottle.dev/docs URLs, and matching excerpts. Prefer this over recalling API details from memory.",
+    kind: "read",
+    scopes: [],
+    input: [
+      { name: "query", type: "string", required: true, description: "What to search for." },
+      { name: "limit", type: "number", required: false, description: "Maximum results." }
+    ],
+    requests: [],
+    channels: ["mcp"]
+  },
+  {
+    id: "describe_endpoint",
+    title: "Describe an API endpoint",
+    description: "Return the canonical request and response shape of a Throttle API endpoint from the published OpenAPI contract: path parameters, request body fields, required scope. Use before writing any integration code.",
+    kind: "read",
+    scopes: [],
+    input: [
+      {
+        name: "path",
+        type: "string",
+        required: true,
+        description: 'Endpoint path or fragment, e.g. "/api/v1/carts" or "carts".'
+      },
+      {
+        name: "method",
+        type: "string",
+        required: false,
+        description: "Narrow to one HTTP method.",
+        enum: ["GET", "POST", "PATCH", "PUT", "DELETE"]
+      }
+    ],
+    requests: [],
+    channels: ["mcp"]
+  },
+  {
+    id: "validate_payload",
+    title: "Validate a request body against the API contract",
+    description: "Check a request body against the published contract before sending it. Names every unsupported field and gives its canonical replacement \u2014 Throttle is strict camelCase and rejects retired aliases such as line_items, unit_price, customer_id and storeId. Full reference: https://usethrottle.dev/docs/developers/api-reference.",
+    kind: "read",
+    scopes: [],
+    input: [
+      { name: "method", type: "string", required: true, description: "HTTP method." },
+      { name: "path", type: "string", required: true, description: "Endpoint path." },
+      { name: "body", type: "object", required: true, description: "The request body to check." }
+    ],
+    requests: [],
+    channels: ["mcp"]
+  },
+  // ------------------------------------------------------------ generic reads
+  {
+    id: "api_get",
+    title: "Read any Throttle API endpoint",
+    description: "Escape hatch for reads the curated tools do not cover: performs a GET against any /api/v1 path and returns the response. Cannot write. Confirm the path with describe_endpoint first if unsure. Full reference: https://usethrottle.dev/docs/developers/api-reference.",
+    kind: "read",
+    scopes: [],
+    credentialScoped: true,
+    input: [
+      {
+        name: "path",
+        type: "string",
+        required: true,
+        description: "Path beginning with /api/v1, query string included."
+      },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [],
+    channels: ["mcp"],
+    guardrails: [
+      "GET only \u2014 reject any other method.",
+      "Reject paths outside /api/v1 so the tool cannot be pointed at another host or a non-versioned surface.",
+      "Server-side scope enforcement still applies; surface a 403 insufficient_scopes verbatim rather than retrying."
+    ]
+  },
+  // ------------------------------------------------------------------- orders
+  {
+    id: "search_orders",
+    title: "Search orders",
+    description: "List orders, newest first, with optional free-text and status filters.",
+    kind: "read",
+    scopes: ["orders:read"],
+    input: [
+      { name: "q", type: "string", required: false, description: "Free-text search." },
+      { name: "status", type: "string", required: false, description: "Order status filter." },
+      { name: "paymentStatus", type: "string", required: false, description: "Payment status filter." },
+      {
+        name: "createdAfter",
+        type: "string",
+        required: false,
+        description: "ISO 8601 lower bound on creation time, exclusive. For a single day, pass that day's midnight and the next day's midnight."
+      },
+      {
+        name: "createdBefore",
+        type: "string",
+        required: false,
+        description: "ISO 8601 upper bound on creation time, exclusive."
+      },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/orders" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      OAUTH_WITHHELD,
+      "Over an OAuth connection, q matches the order id, order number and status fields only."
+    ]
+  },
+  {
+    id: "get_order",
+    title: "Get one order with its returns and fulfillments",
+    description: "Full picture of a single order: the order itself plus its payments, returns and fulfillments in one response.",
+    kind: "read",
+    scopes: ["orders:read"],
+    sectionScopes: ["payments:read", "order_returns:read", "fulfillments:read"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Order id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [
+      { method: "GET", path: "/api/v1/orders/:id" },
+      { method: "GET", path: "/api/v1/orders/:id/payments" },
+      { method: "GET", path: "/api/v1/orders/:id/returns" },
+      { method: "GET", path: "/api/v1/orders/:orderId/fulfillments" }
+    ],
+    channels: ["mcp"],
+    guardrails: [
+      "Sub-reads need their own scopes (payments:read, order_returns:read, fulfillments:read). Skip a section the credential cannot read and say so in the result rather than failing the whole call.",
+      OAUTH_WITHHELD
+    ]
+  },
+  // ---------------------------------------------------------------- customers
+  {
+    id: "search_customers",
+    title: "Search customers",
+    description: "Find customers by name, email or external id, or list them by creation date. Over an OAuth connection (ChatGPT, Claude) text search is not available \u2014 list by date instead \u2014 because every field it could match is withheld there.",
+    kind: "read",
+    scopes: ["customers:read"],
+    input: [
+      { name: "q", type: "string", required: false, description: "Free-text search." },
+      {
+        name: "createdAfter",
+        type: "string",
+        required: false,
+        description: "ISO 8601 lower bound on creation time, exclusive. For a single day, pass that day's midnight and the next day's midnight."
+      },
+      {
+        name: "createdBefore",
+        type: "string",
+        required: false,
+        description: "ISO 8601 upper bound on creation time, exclusive."
+      },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/customers" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      'email, phone, firstName, lastName, name and metadata are withheld (null, or absent from the result) unless the credential holds customer_pii:read, which OAuth connections cannot hold. Over an OAuth connection company, externalId and externalCustomerId are withheld too, and q is refused. Do not describe a missing name/email as "no name on file"; say it is withheld.'
+    ]
+  },
+  {
+    id: "get_customer",
+    title: "Get one customer with subscriptions and addresses",
+    description: "Full picture of a single customer: the record plus their subscriptions and addresses in one response.",
+    kind: "read",
+    scopes: ["customers:read"],
+    sectionScopes: ["customer_addresses:read", "subscriptions:read"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Customer id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [
+      { method: "GET", path: "/api/v1/customers/:id" },
+      { method: "GET", path: "/api/v1/customers/:id/addresses" },
+      { method: "GET", path: "/api/v1/subscriptions" }
+    ],
+    channels: ["mcp"],
+    guardrails: [
+      "Sub-reads need customer_addresses:read / subscriptions:read. Omit a section the credential cannot read instead of failing.",
+      "email, phone, firstName, lastName, name and metadata on the customer record are withheld (null, or absent from the result) unless the credential holds customer_pii:read, which OAuth connections cannot hold. Say PII is redacted rather than reporting the buyer as anonymous.",
+      OAUTH_WITHHELD
+    ]
+  },
+  // ------------------------------------------------------------- subscriptions
+  {
+    id: "list_subscriptions",
+    title: "List subscriptions",
+    description: "List subscriptions with optional customer and status filters.",
+    kind: "read",
+    scopes: ["subscriptions:read"],
+    input: [
+      { name: "customerId", type: "string", required: false, description: "Filter by customer." },
+      { name: "status", type: "string", required: false, description: "Filter by status." },
+      {
+        name: "createdAfter",
+        type: "string",
+        required: false,
+        description: "ISO 8601 lower bound on creation time, exclusive. For a single day, pass that day's midnight and the next day's midnight."
+      },
+      {
+        name: "createdBefore",
+        type: "string",
+        required: false,
+        description: "ISO 8601 upper bound on creation time, exclusive."
+      },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/subscriptions" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  {
+    id: "get_subscription",
+    title: "Get one subscription",
+    description: "Read a single subscription including its current period and pending changes.",
+    kind: "read",
+    scopes: ["subscriptions:read"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Subscription id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/subscriptions/:id" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  // ------------------------------------------------------------------- quotes
+  {
+    id: "search_quotes",
+    title: "Search quotes",
+    description: 'List quotes with optional status filter \u2014 useful for "which quotes expire soon".',
+    kind: "read",
+    scopes: ["quotes:read"],
+    input: [
+      { name: "status", type: "string", required: false, description: "Filter by quote status." },
+      {
+        name: "createdAfter",
+        type: "string",
+        required: false,
+        description: "ISO 8601 lower bound on creation time, exclusive. For a single day, pass that day's midnight and the next day's midnight."
+      },
+      {
+        name: "createdBefore",
+        type: "string",
+        required: false,
+        description: "ISO 8601 upper bound on creation time, exclusive."
+      },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/quotes" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  {
+    id: "get_quote",
+    title: "Get one quote",
+    description: "Read a single quote: status, totals, and each revision with its line items and payment terms.",
+    kind: "read",
+    scopes: ["quotes:read"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Quote id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/quotes/:id" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [OAUTH_WITHHELD]
+  },
+  // ----------------------------------------------------------------- invoices
+  {
+    id: "list_invoices",
+    title: "List invoices",
+    description: "List issued invoices with optional status filter.",
+    kind: "read",
+    scopes: ["invoices:read"],
+    input: [
+      { name: "status", type: "string", required: false, description: "Filter by invoice status." },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/invoices" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [OAUTH_WITHHELD]
+  },
+  {
+    id: "receivables_aging",
+    title: "Receivables aging",
+    description: 'Outstanding receivables bucketed by age \u2014 answers "what is overdue and by how long".',
+    kind: "read",
+    scopes: ["invoices:read"],
+    input: [
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/invoices/aging" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  // --------------------------------------------------------------- discounts
+  {
+    id: "search_discounts",
+    title: "Search discounts",
+    description: "List discount codes with optional filters \u2014 type, active state, and creation date range.",
+    kind: "read",
+    scopes: ["discounts:read"],
+    input: [
+      { name: "q", type: "string", required: false, description: "Free-text search." },
+      { name: "code", type: "string", required: false, description: "Exact code match." },
+      {
+        name: "type",
+        type: "string",
+        required: false,
+        description: "Filter by discount type.",
+        enum: ["percentage", "fixed_amount"]
+      },
+      { name: "isActive", type: "boolean", required: false, description: "Filter by active state." },
+      { name: "createdAfter", type: "string", required: false, description: "ISO 8601 date lower bound." },
+      { name: "createdBefore", type: "string", required: false, description: "ISO 8601 date upper bound." },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/discounts" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  {
+    id: "get_discount",
+    title: "Get one discount",
+    description: "Read a single discount code: value, conditions, usage limits and redemption count.",
+    kind: "read",
+    scopes: ["discounts:read"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Discount id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/discounts/:id" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  // ---------------------------------------------------------------- payments
+  {
+    id: "search_payments",
+    title: "Search payments",
+    description: "List payments with optional filters \u2014 method, status, order, amount range, or a Net-N overdue bucket. Today payments are only reachable nested inside get_order; this is the standalone entry point.",
+    kind: "read",
+    scopes: ["payments:read"],
+    input: [
+      { name: "method", type: "string", required: false, description: "Filter by payment method." },
+      { name: "status", type: "string", required: false, description: "Filter by payment status." },
+      { name: "orderId", type: "string", required: false, description: "Filter to one order." },
+      {
+        name: "aging",
+        type: "string",
+        required: false,
+        description: "Overdue bucket filter, Net-N payments only.",
+        enum: ["0_30", "31_60", "61_90", "90_plus"]
+      },
+      { name: "dueFrom", type: "string", required: false, description: "Due-date range start, YYYY-MM-DD." },
+      { name: "dueTo", type: "string", required: false, description: "Due-date range end, YYYY-MM-DD." },
+      { name: "amountMin", type: "number", required: false, description: "Minimum amount, minor units." },
+      { name: "amountMax", type: "number", required: false, description: "Maximum amount, minor units." },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/payments" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  {
+    id: "get_payment",
+    title: "Get one payment with its transactions",
+    description: "Read a single payment plus its full transaction history (authorize/capture/refund/void attempts).",
+    kind: "read",
+    scopes: ["payments:read"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Payment id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [
+      { method: "GET", path: "/api/v1/payments/:id" },
+      { method: "GET", path: "/api/v1/payments/:id/transactions" }
+    ],
+    channels: ["mcp"],
+    guardrails: [
+      "The transactions sub-read needs its own read of the same payment scope; report it as unavailable rather than failing the whole call if the underlying request errors."
+    ]
+  },
+  // ---------------------------------------------------------------- invoices
+  {
+    id: "get_invoice",
+    title: "Get one invoice",
+    description: "Read a single issued invoice: line items, totals, status and the billing snapshot at issue time.",
+    kind: "read",
+    scopes: ["invoices:read"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Invoice id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/invoices/:id" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [OAUTH_WITHHELD]
+  },
+  // ------------------------------------------------------------------ carts
+  {
+    id: "list_abandoned_carts",
+    title: "List abandoned carts",
+    description: "Carts that were started but never finalized, with recovery status \u2014 the abandoned-cart recovery list.",
+    kind: "read",
+    scopes: ["carts:read"],
+    input: [
+      { name: "sinceDays", type: "number", required: false, description: "How many days back to look." },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [
+      { method: "GET", path: "/api/v1/abandoned-carts" },
+      { method: "GET", path: "/api/v1/abandoned-carts/summary" }
+    ],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: ["Report the summary as unavailable rather than failing the whole call if that sub-read errors."]
+  },
+  // ---------------------------------------------------------------- debugging
+  {
+    id: "search_events",
+    title: "Search the event log",
+    description: "Search the immutable event log by type or entity. The first stop when asking what actually happened to an order, cart or subscription.",
+    kind: "read",
+    scopes: ["events:read"],
+    input: [
+      { name: "type", type: "string", required: false, description: "Event type, e.g. order.created." },
+      { name: "entityType", type: "string", required: false, description: "Entity type filter." },
+      { name: "entityId", type: "string", required: false, description: "Entity id filter." },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/events" }],
+    channels: ["mcp", "n8n"]
+  },
+  {
+    id: "list_webhook_deliveries",
+    title: "List webhook deliveries",
+    description: "Recent outbound webhook deliveries, filterable by endpoint, status and event type.",
+    kind: "read",
+    scopes: ["webhook_deliveries:read"],
+    input: [
+      { name: "endpointId", type: "string", required: false, description: "Filter by endpoint." },
+      {
+        name: "status",
+        type: "string",
+        required: false,
+        description: "Filter by delivery status: pending, delivered, failed or dead_letter."
+      },
+      {
+        name: "eventType",
+        type: "string",
+        required: false,
+        description: "Filter by exact event type, e.g. payment.failed."
+      },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/webhook-deliveries" }],
+    channels: ["mcp", "n8n"]
+  },
+  {
+    id: "get_webhook_delivery",
+    title: "Get one webhook delivery",
+    description: "Full delivery record: the signed payload we sent, the response we got back, and every attempt.",
+    kind: "read",
+    scopes: ["webhook_deliveries:read"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Delivery id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/webhook-deliveries/:id" }],
+    channels: ["mcp", "n8n"]
+  },
+  {
+    id: "explain_checkout_failure",
+    title: "Explain why a checkout failed",
+    description: "Diagnose a failing checkout in one call: session state, its cart, the events it emitted, and any webhook deliveries that followed. Use this before asking the user to reproduce anything.",
+    kind: "read",
+    scopes: ["checkout_sessions:read"],
+    sectionScopes: ["events:read", "webhook_deliveries:read"],
+    input: [
+      {
+        name: "id",
+        type: "string",
+        required: true,
+        description: "Checkout session id (or cart id \u2014 the tool resolves the session)."
+      },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [
+      { method: "GET", path: "/api/v1/checkout-sessions/:id" },
+      { method: "GET", path: "/api/v1/checkout-sessions/:id/cart" },
+      { method: "GET", path: "/api/v1/events" },
+      { method: "GET", path: "/api/v1/webhook-deliveries" }
+    ],
+    channels: ["mcp"],
+    guardrails: [
+      "Report which sections were unavailable rather than failing the call when a sub-read is unscoped.",
+      OAUTH_WITHHELD
+    ]
+  },
+  // ------------------------------------------------------------- extensions
+  {
+    id: "list_extension_installations",
+    title: "List installed extensions",
+    description: "Extensions installed on this application, with status and configuration.",
+    kind: "read",
+    scopes: ["extensions:read"],
+    input: [
+      {
+        name: "status",
+        type: "string",
+        required: false,
+        description: "Filter by installation status.",
+        enum: ["active", "suspended", "uninstalled"]
+      },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/installations" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  // ------------------------------------------------------------- connectors
+  {
+    id: "get_connector_routing",
+    title: "Payment routing and decline rules",
+    description: "Read the payment-routing cascade, active routing connectors, and card/other decline rules \u2014 what determines which processor handles a payment and what happens on a decline.",
+    kind: "read",
+    scopes: ["connectors:read"],
+    input: [
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [
+      { method: "GET", path: "/api/v1/payment-routing" },
+      { method: "GET", path: "/api/v1/routing-connectors" },
+      { method: "GET", path: "/api/v1/card-decline" },
+      { method: "GET", path: "/api/v1/other-decline" }
+    ],
+    channels: ["mcp"],
+    guardrails: [
+      "Every sub-read proxies live to the payment provider's routing API and none are guaranteed to succeed together; report any that fail as unavailable rather than failing the whole call."
+    ]
+  },
+  {
+    id: "get_integration_status",
+    title: "Integration readiness",
+    description: 'Answers "am I ready to go live?" \u2014 active connectors, webhook endpoints and their recent delivery health, and the environment this credential is pinned to.',
+    kind: "read",
+    scopes: [],
+    sectionScopes: ["connectors:read", "webhooks:read"],
+    input: [
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [
+      { method: "GET", path: "/api/v1/whoami" },
+      { method: "GET", path: "/api/v1/connectors" },
+      { method: "GET", path: "/api/v1/webhook-endpoints" },
+      { method: "GET", path: "/api/v1/webhook-endpoints/coverage" }
+    ],
+    channels: ["mcp"],
+    guardrails: [
+      'Each section needs its own scope (connectors:read, webhooks:read). Report a section as "not readable with this credential" instead of failing.'
+    ]
+  },
+  // --------------------------------------------------------------- workspace
+  {
+    id: "get_workspace_settings",
+    title: "Get workspace settings",
+    description: "Read this workspace's identity: name, slug, branding and onboarding state. Payment terms are set per application and environment, not here.",
+    kind: "read",
+    scopes: ["merchant:read"],
+    input: [],
+    requests: [{ method: "GET", path: "/api/v1/merchants/me" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  {
+    id: "get_audit_log",
+    title: "Get the workspace audit log",
+    description: "Recent admin actions taken on this workspace \u2014 invites, billing changes, key rotation, suspensions.",
+    kind: "read",
+    scopes: ["audit_logs:read"],
+    input: [
+      { name: "limit", type: "number", required: false, description: "Maximum entries (1-200).", default: 100 }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/audit-log" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  {
+    id: "list_applications",
+    title: "List applications in this workspace",
+    description: 'List every application in this workspace you have access to, so you can pass one of their ids as applicationId on other read and analytics tools. Note: the underlying route is the legacy-named /v1/stores (kept for contract stability) \u2014 the resource it returns is applications, not a separate "stores" concept.',
+    kind: "read",
+    scopes: ["applications:read"],
+    input: [],
+    requests: [{ method: "GET", path: "/api/v1/stores" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  {
+    id: "get_sales_timeseries",
+    title: "Sales over time",
+    description: `Order count and gross revenue bucketed by day, week or month over any date range, in the merchant's timezone, optionally compared to the previous period or the same range last year. Use this for "how much did we sell on/last/between\u2026" instead of paging search_orders and adding it up.`,
+    kind: "read",
+    scopes: ["orders:read"],
+    input: [
+      { name: "from", type: "string", required: false, description: 'ISO 8601 start of range, exclusive. Defaults to 30 days before "to".' },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range, exclusive. Defaults to now." },
+      { name: "groupBy", type: "string", required: false, description: "Bucket size.", enum: ["day", "week", "month"], default: "day" },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for bucket boundaries, e.g. America/New_York. Defaults to UTC \u2014 ask the user rather than assuming UTC when the answer depends on day boundaries." },
+      { name: "compareTo", type: "string", required: false, description: "Add a comparison total.", enum: ["previous_period", "previous_year", "none"], default: "none" },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/orders-timeseries" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "Revenue is GROSS. Refunds are not deducted, because that needs payment_refunds:read, which OAuth connections cannot hold. Never describe the figure as net."
+    ]
+  },
+  {
+    id: "get_business_summary",
+    title: "Business summary",
+    description: "How are we doing? Orders/revenue, subscription MRR, receivables and quotes pipeline over a date range, compared to the immediately preceding window of equal length. Note: period=week|month|quarter means the TRAILING 7/30/90 days, not a calendar period \u2014 pass from/to for calendar months.",
+    kind: "read",
+    scopes: [],
+    sectionScopes: ["orders:read", "subscriptions:read", "invoices:read", "quotes:read"],
+    input: [
+      {
+        name: "period",
+        type: "string",
+        required: false,
+        description: "Reporting window.",
+        enum: ["week", "month", "quarter"],
+        default: "month"
+      },
+      { name: "from", type: "string", required: false, description: "ISO 8601 start of range. Overrides period." },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range. Defaults to now." },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for period boundaries. Defaults to UTC." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/business-summary" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "Each section needs its own scope (orders:read, subscriptions:read, invoices:read, quotes:read). A section without its scope is reported as omitted rather than failing the whole call."
+    ]
+  },
+  {
+    id: "get_top_products",
+    title: "Top products",
+    description: "Best-selling products over a date range, by revenue or units sold. Line items come from the merchant's own cart payload, so a product is identified by its external reference id when present and by name otherwise. The response carries both the top-N rows (by the chosen sort) and range-wide totals across every matching product, so you can compute what share of total revenue/units the top N represent.",
+    kind: "read",
+    scopes: ["orders:read"],
+    input: [
+      { name: "from", type: "string", required: false, description: 'ISO 8601 start of range, exclusive. Defaults to 30 days before "to".' },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range, exclusive. Defaults to now." },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for range boundaries. Defaults to UTC." },
+      { name: "by", type: "string", required: false, description: "Sort key.", enum: ["revenue", "units"], default: "revenue" },
+      { name: "limit", type: "number", required: false, description: "Max rows to return (1-100). Defaults to 20." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/products" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "Revenue is GROSS. Refunds are not deducted, because that needs payment_refunds:read, which OAuth connections cannot hold. Never describe the figure as net."
+    ]
+  },
+  {
+    id: "get_attention_digest",
+    title: "Attention digest",
+    description: "What needs attention right now? Open disputes, subscriptions in dunning, overdue Net-N invoices, and webhooks with degraded delivery health \u2014 a point-in-time snapshot, not a time range.",
+    kind: "read",
+    scopes: [],
+    sectionScopes: ["payment_disputes:read", "subscriptions:read", "invoices:read", "webhook_deliveries:read"],
+    input: [
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/attention-digest" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "Each section needs its own scope (payment_disputes:read, subscriptions:read, invoices:read, webhook_deliveries:read). A section without its scope is reported as omitted rather than failing the whole call."
+    ]
+  },
+  {
+    id: "get_customer_growth",
+    title: "Customer growth",
+    description: "Customer growth over a date range: signups per day/week/month, how many orders came from first-time versus returning customers, and the highest-value customers in the window.",
+    kind: "read",
+    scopes: ["customers:read"],
+    input: [
+      { name: "from", type: "string", required: false, description: 'ISO 8601 start of range, exclusive. Defaults to 30 days before "to".' },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range, exclusive. Defaults to now." },
+      { name: "groupBy", type: "string", required: false, description: "Signup series bucket size.", enum: ["day", "week", "month"], default: "day" },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for bucket boundaries. Defaults to UTC." },
+      { name: "topBy", type: "string", required: false, description: "Sort key for top customers.", enum: ["revenue", "orders"], default: "revenue" },
+      { name: "topLimit", type: "number", required: false, description: "Max top-customers rows to return (1-50). Defaults to 10." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/customers" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "Revenue is GROSS. Refunds are not deducted, because that needs payment_refunds:read, which OAuth connections cannot hold. Never describe the figure as net.",
+      "topCustomers is a top-N list; use the accompanying totals for range-wide customer/order/revenue counts instead of summing the returned rows.",
+      "topCustomers[].email and .name come back null unless the credential holds customer_pii:read, which OAuth connections cannot hold. Identify a top customer by id, not by a null name."
+    ]
+  },
+  {
+    id: "get_revenue_breakdown",
+    title: "Revenue breakdown",
+    description: "Revenue split by one dimension over a date range \u2014 payment method, order source, or currency. Amounts are gross; refunds are not deducted.",
+    kind: "read",
+    scopes: ["orders:read"],
+    input: [
+      {
+        name: "dimension",
+        type: "string",
+        required: true,
+        description: "Breakdown dimension.",
+        enum: ["paymentMethod", "source", "currency"]
+      },
+      { name: "from", type: "string", required: false, description: 'ISO 8601 start of range, exclusive. Defaults to 30 days before "to".' },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range, exclusive. Defaults to now." },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for range boundaries. Defaults to UTC." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/revenue-breakdown" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "Revenue is GROSS. Refunds are not deducted, because that needs payment_refunds:read, which OAuth connections cannot hold. Never describe the figure as net.",
+      "dimension is required; it is never defaulted, so omitting it fails the call instead of silently picking a dimension.",
+      "For dimension=paymentMethod, an order paid via more than one method can appear in more than one row, so rows can sum to more than totals (a separate whole-range aggregate over orders alone)."
+    ]
+  },
+  {
+    id: "get_funnel_conversion",
+    title: "Checkout funnel",
+    description: "Checkout funnel over a date range: carts created, checkout sessions started, orders completed, with the drop-off between each stage.",
+    kind: "read",
+    scopes: ["carts:read"],
+    input: [
+      { name: "from", type: "string", required: false, description: 'ISO 8601 start of range, exclusive. Defaults to 30 days before "to".' },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range, exclusive. Defaults to now." },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for range boundaries. Defaults to UTC." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/funnel" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "Each stage needs its own scope (carts:read, checkout_sessions:read, orders:read), checked independently \u2014 an OAuth grant carries literal scopes with no legacy expansion, so a credential can hold carts:read without the other two. An omitted stage is reported as such rather than failing the whole call.",
+      "conversionRate and dropOff[].ratePct are null (unknown) when a stage they depend on is omitted, and 0 only when the stage was readable with a true zero count. Never treat a null here as 0.",
+      'dropOff[].ratePct is the percentage of "from" that did NOT reach "to" (loss), not a conversion rate. The step-conversion rate is 100 - ratePct.'
+    ]
+  },
+  {
+    id: "get_subscription_movement",
+    title: "Subscription movement",
+    description: "Subscription movement over a date range: new subscriptions, cancellations and net MRR change per day/week/month. Figures are reconstructed from subscription timestamps, not a stored historical snapshot.",
+    kind: "read",
+    scopes: ["subscriptions:read"],
+    input: [
+      { name: "from", type: "string", required: false, description: 'ISO 8601 start of range, exclusive. Defaults to 30 days before "to".' },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range, exclusive. Defaults to now." },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for bucket boundaries. Defaults to UTC." },
+      { name: "groupBy", type: "string", required: false, description: "Bucket size.", enum: ["day", "week", "month"], default: "day" },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/subscriptions" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "newSubscriptions, churnedSubscriptions and mrrDeltaCents are reconstructed per bucket from subscription created_at/cancelled_at timestamps, not a stored historical MRR snapshot \u2014 never present this series as an audited historical MRR ledger.",
+      "mrrDeltaCents for a bucket only credits subscriptions created in that bucket that are still active right now, and only debits subscriptions cancelled in that bucket that already existed when it started. A subscription created AND cancelled inside the same bucket still counts toward both newSubscriptions and churnedSubscriptions but contributes 0 to mrrDeltaCents.",
+      "totals is the sum over the full series (the series is never truncated), so totals.newSubscriptions/.churnedSubscriptions/.netMrrDeltaCents always equal the corresponding sums of series[]."
+    ]
+  },
+  {
+    id: "get_discount_performance",
+    title: "Discount performance",
+    description: "Discount code performance over a date range: redemption count, revenue on discounted orders, and total discount given per code.",
+    kind: "read",
+    scopes: ["discounts:read"],
+    input: [
+      { name: "from", type: "string", required: false, description: 'ISO 8601 start of range, exclusive. Defaults to 30 days before "to".' },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range, exclusive. Defaults to now." },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for range boundaries. Defaults to UTC." },
+      { name: "limit", type: "number", required: false, description: "Max rows to return. Defaults to 20." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/discounts" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      'discountedRevenueCents and discountGivenCents are DIFFERENT measures: discountedRevenueCents is the gross order total on orders that redeemed the code; discountGivenCents is the discount amount taken off those same orders. Never describe discountedRevenueCents as "given away" or discountGivenCents as revenue.',
+      "Only orders with status <> draft and a gross-eligible payment_status are counted; refunds are not deducted from discountedRevenueCents, because that needs payment_refunds:read.",
+      "rows are the top N codes by discount given; totals is a SEPARATE whole-range aggregate (not a reduction over rows), so totals.redemptions / totals.discountGivenCents stay valid even when rows is truncated by limit."
+    ]
+  },
+  // ------------------------------------------------------------ sandbox write
+  {
+    id: "seed_test_data",
+    title: "Seed test data (non-production only)",
+    description: "Create a realistic customer, cart, line items and a finalized draft order so an integration has something to read. Refuses to run against production.",
+    kind: "write",
+    scopes: ["customers:write", "carts:write", "cart_items:write"],
+    input: [
+      { name: "customerEmail", type: "string", required: false, description: "Email for the seeded customer." },
+      { name: "lineItems", type: "array", required: false, description: "Line items; a sensible default set is used when omitted." }
+    ],
+    requests: [
+      { method: "POST", path: "/api/v1/customers" },
+      { method: "POST", path: "/api/v1/carts" },
+      { method: "POST", path: "/api/v1/carts/:id/items" },
+      { method: "POST", path: "/api/v1/carts/:id/finalize" }
+    ],
+    channels: ["mcp"],
+    sandboxOnly: true,
+    idempotent: true,
+    guardrails: [
+      "Hard-refuse when the credential resolves to a production environment, regardless of any allow-writes flag.",
+      "Seeds a finalized DRAFT order \u2014 it does not capture a payment, which needs a browser-side tokenised payment method."
+    ]
+  },
+  // ---------------------------------------------------------- inbound writes
+  // The no-code channels are mostly used in the "something happened elsewhere,
+  // put it into Throttle" direction — a form submission, a new CRM contact, a
+  // spreadsheet row. These three are that direction.
+  {
+    id: "create_customer",
+    title: "Create a customer",
+    description: "Create a customer record. Use search_customers first if the buyer may already exist \u2014 this does not de-duplicate by email.",
+    kind: "write",
+    scopes: ["customers:write"],
+    input: [
+      { name: "email", type: "string", required: true, description: "The buyer's email address." },
+      { name: "firstName", type: "string", required: false, description: "Given name." },
+      { name: "lastName", type: "string", required: false, description: "Family name." },
+      { name: "phone", type: "string", required: false, description: "Contact phone number." },
+      { name: "company", type: "string", required: false, description: "The buyer's company." },
+      {
+        name: "externalId",
+        type: "string",
+        required: false,
+        description: "This customer's id in your own system. Resolvable later via get_customer."
+      },
+      {
+        name: "netN",
+        type: "number",
+        required: false,
+        description: "Invoice terms in days for this customer specifically, 0-365. Omit to use the workspace default; 0 means due on issue."
+      },
+      {
+        name: "acceptsMarketing",
+        type: "boolean",
+        required: false,
+        description: "Whether the buyer opted into marketing email.",
+        default: false
+      }
+    ],
+    requests: [{ method: "POST", path: "/api/v1/customers" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    idempotent: true,
+    guardrails: [
+      "The created record is echoed back with email, phone, firstName, lastName and name nulled unless the credential holds customer_pii:read, which OAuth connections cannot hold \u2014 the customer is still created with the values sent, only the response is redacted."
+    ]
+  },
+  {
+    id: "update_customer",
+    title: "Update a customer",
+    description: "Change fields on an existing customer. Only the fields supplied are touched; everything else is left alone.",
+    kind: "write",
+    scopes: ["customers:write"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Customer id." },
+      { name: "email", type: "string", required: false, description: "The buyer's email address." },
+      { name: "firstName", type: "string", required: false, description: "Given name." },
+      { name: "lastName", type: "string", required: false, description: "Family name." },
+      { name: "phone", type: "string", required: false, description: "Contact phone number." },
+      { name: "company", type: "string", required: false, description: "The buyer's company." },
+      {
+        name: "externalId",
+        type: "string",
+        required: false,
+        description: "This customer's id in your own system. Pass null to clear it."
+      },
+      {
+        name: "netN",
+        type: "number",
+        required: false,
+        description: "Invoice terms in days for this customer specifically, 0-365."
+      },
+      {
+        name: "acceptsMarketing",
+        type: "boolean",
+        required: false,
+        description: "Whether the buyer opted into marketing email."
+      }
+    ],
+    requests: [{ method: "PATCH", path: "/api/v1/customers/:id" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    idempotent: true,
+    guardrails: [
+      "The updated record is echoed back with email, phone, firstName, lastName and name nulled unless the credential holds customer_pii:read, which OAuth connections cannot hold \u2014 the update still applied, only the response is redacted."
+    ]
+  },
+  {
+    id: "create_checkout_link",
+    title: "Create a checkout link",
+    description: "Build a cart from line items and return a hosted checkout URL the buyer can pay at. Prices are in minor units (2500 = $25.00).",
+    kind: "write",
+    scopes: ["carts:write", "cart_items:write", "checkout_sessions:write"],
+    input: [
+      {
+        name: "lineItems",
+        type: "array",
+        required: true,
+        description: "What the buyer is paying for: { name, unitPrice, quantity }. unitPrice is an integer in minor units."
+      },
+      {
+        name: "returnUrl",
+        type: "string",
+        required: true,
+        description: "Absolute URL the buyer lands on after paying."
+      },
+      {
+        name: "cancelUrl",
+        type: "string",
+        required: true,
+        description: "Absolute URL the buyer lands on if they abandon checkout."
+      },
+      {
+        name: "customerId",
+        type: "string",
+        required: false,
+        description: "Attach the cart to an existing customer."
+      },
+      {
+        name: "customerEmail",
+        type: "string",
+        required: false,
+        description: "Pre-fill the buyer email without needing a customer record."
+      },
+      {
+        name: "discountCode",
+        type: "string",
+        required: false,
+        description: "Discount code to apply to the session."
+      },
+      {
+        name: "netN",
+        type: "number",
+        required: false,
+        description: "Invoice terms in days for this cart, 0-365. Omit to pay in full at checkout."
+      }
+    ],
+    // Three calls: the API has no single "checkout link" endpoint, and a
+    // checkout session requires a cart that already holds its line items.
+    requests: [
+      { method: "POST", path: "/api/v1/carts" },
+      { method: "POST", path: "/api/v1/carts/:id/items" },
+      { method: "POST", path: "/api/v1/checkout/sessions" }
+    ],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    idempotent: true,
+    guardrails: [
+      "The returned URL is buyer-facing and takes real payment in a production environment."
+    ]
+  },
+  // -------------------------------------------------------------- money/mail
+  {
+    id: "create_quote",
+    title: "Create a quote",
+    description: "Draft a quote for a customer with line items and terms. Does not send it \u2014 use send_quote.",
+    kind: "write",
+    scopes: ["quotes:write"],
+    input: [
+      { name: "customerId", type: "string", required: true, description: "Customer the quote is for." },
+      { name: "items", type: "array", required: true, description: "Quote line items: { name, unitPrice, quantity }." },
+      { name: "expiresAt", type: "string", required: false, description: "ISO 8601 expiry." },
+      { name: "netN", type: "number", required: false, description: "Payment terms in days. Omit for pay-in-full." },
+      { name: "notes", type: "string", required: false, description: "Buyer-visible notes." }
+    ],
+    requests: [{ method: "POST", path: "/api/v1/quotes" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    idempotent: true
+  },
+  {
+    id: "send_quote",
+    title: "Issue and send a quote",
+    description: "Issue a draft quote and email the buyer their quote link. This is buyer-visible \u2014 confirm with the user before calling it.",
+    kind: "write",
+    scopes: ["quotes:write"],
+    input: [{ name: "id", type: "string", required: true, description: "Quote id." }],
+    requests: [{ method: "POST", path: "/api/v1/quotes/:id/issue" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    idempotent: true,
+    guardrails: ['Sends mail to a real buyer. Never call it speculatively or to "check" a quote.'],
+    destructive: true
+  },
+  {
+    id: "refund_payment",
+    title: "Refund a payment",
+    description: "Refund a captured payment. The amount is required \u2014 never infer a full refund from an unspecified amount.",
+    kind: "write",
+    scopes: ["payment_refunds:write"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Payment id." },
+      {
+        name: "amount",
+        type: "number",
+        required: true,
+        description: "Amount to refund in minor units. Required \u2014 omitting it would refund the whole payment."
+      },
+      { name: "reason", type: "string", required: false, description: "Reason recorded on the refund." }
+    ],
+    requests: [{ method: "POST", path: "/api/v1/payments/:id/refund" }],
+    // NOT zapier/make. `payment_refunds:write` is `sensitive` in the scope
+    // registry, and `validateScopesForOAuth` rejects every sensitive scope — so
+    // an OAuth grant, which is the only credential a public Zapier or Make app
+    // can hold, can never carry it. Listing the action on those channels would
+    // ship a connector action that 403s on every call. MCP and n8n keep it:
+    // both authenticate with an `sk_` key, which CAN hold the scope.
+    // `oauth-grantable-scopes` in the catalog tests enforces this.
+    channels: ["mcp", "n8n"],
+    idempotent: true,
+    guardrails: [
+      "Moves money and is irreversible. Confirm with the user first.",
+      "The API treats an omitted amount as a FULL refund, so this action requires it explicitly."
+    ],
+    destructive: true
+  },
+  {
+    id: "manage_subscription",
+    title: "Pause or resume a subscription",
+    description: "Pause or resume an active subscription.",
+    kind: "write",
+    scopes: ["subscription_pauses:write"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Subscription id." },
+      {
+        name: "action",
+        type: "string",
+        required: true,
+        description: "What to do.",
+        enum: ["pause", "resume"]
+      }
+    ],
+    requests: [
+      { method: "POST", path: "/api/v1/subscriptions/:id/pause" },
+      { method: "POST", path: "/api/v1/subscriptions/:id/resume" }
+    ],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    idempotent: true
+  },
+  {
+    id: "cancel_subscription",
+    title: "Cancel a subscription",
+    description: "Cancel a subscription. Separate from pause/resume because it needs its own scope.",
+    kind: "write",
+    scopes: ["subscription_cancellations:write"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Subscription id." },
+      {
+        name: "atPeriodEnd",
+        type: "boolean",
+        required: false,
+        description: "Cancel at the end of the current period instead of immediately."
+      }
+    ],
+    requests: [{ method: "POST", path: "/api/v1/subscriptions/:id/cancel" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    idempotent: true,
+    guardrails: ["Ends billing for a paying customer. Confirm with the user first."],
+    destructive: true
+  },
+  {
+    id: "replay_webhook_delivery",
+    title: "Replay a webhook delivery",
+    description: "Re-send a past webhook delivery to its endpoint \u2014 useful after fixing a broken handler.",
+    kind: "write",
+    scopes: ["webhook_deliveries:write"],
+    input: [{ name: "id", type: "string", required: true, description: "Delivery id." }],
+    requests: [{ method: "POST", path: "/api/v1/webhook-deliveries/:id/replay" }],
+    channels: ["mcp", "n8n"],
+    idempotent: true,
+    guardrails: ["The receiving system will process the event again. Confirm it is idempotent first."],
+    destructive: true
+  },
+  {
+    id: "send_test_webhook",
+    title: "Send a test webhook",
+    description: "Send a synthetic signed event to a webhook endpoint to verify signature handling and reachability.",
+    kind: "write",
+    scopes: ["webhooks:write"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Endpoint id." },
+      { name: "eventType", type: "string", required: false, description: "Event type to simulate." }
+    ],
+    requests: [{ method: "POST", path: "/api/v1/webhook-endpoints/:id/test" }],
+    channels: ["mcp", "n8n"],
+    idempotent: true,
+    destructive: true
+  }
+];
+
+// ../action-catalog/src/triggers.ts
+var NO_CODE = ["zapier", "make", "n8n"];
+function trigger(id, title, eventType, description) {
+  return { id, title, eventType, description, scope: eventReadScope(eventType), channels: NO_CODE };
+}
+var TRIGGERS = [
+  trigger("new_order", "New order", "order.created", "Fires when an order is created."),
+  trigger(
+    "payment_captured",
+    "Payment captured",
+    "payment.captured",
+    "Fires when a payment is successfully captured."
+  ),
+  trigger(
+    "payment_failed",
+    "Payment failed",
+    "payment.failed",
+    "Fires when a payment attempt fails."
+  ),
+  trigger(
+    "new_subscription",
+    "New subscription",
+    "subscription.created",
+    "Fires when a subscription is created."
+  ),
+  trigger(
+    "subscription_cancelled",
+    "Subscription cancelled",
+    "subscription.cancelled",
+    "Fires when a subscription is cancelled."
+  ),
+  trigger(
+    "quote_accepted",
+    "Quote accepted",
+    "quote.accepted",
+    "Fires when a buyer accepts a quote."
+  ),
+  trigger(
+    "cart_abandoned",
+    "Cart abandoned",
+    "cart.abandoned",
+    "Fires when a cart is marked abandoned."
+  ),
+  trigger(
+    "invoice_past_due",
+    "Invoice past due",
+    "invoice.past_due",
+    "Fires when an invoice passes its due date unpaid."
+  )
+];
+
+// ../action-catalog/src/index.ts
+function actionsForChannel(channel) {
+  return ACTIONS.filter((a) => a.channels.includes(channel));
+}
+function canRunAction(granted, action) {
+  return action.scopes.every((required) => hasScope(granted, required));
+}
+
+// src/format.ts
+var MAX_CHARS = 24e3;
+function prune(value) {
+  if (Array.isArray(value)) return value.map(prune);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, inner] of Object.entries(value)) {
+      if (inner === void 0 || inner === null) continue;
+      out[key] = prune(inner);
+    }
+    return out;
+  }
+  return value;
+}
+function formatResult(value) {
+  const text = JSON.stringify(prune(value), null, 2) ?? "null";
+  if (text.length <= MAX_CHARS) return text;
+  return `${text.slice(0, MAX_CHARS)}
+
+\u2026 truncated at ${MAX_CHARS} characters. Narrow the query (lower "limit", add a filter) or fetch a single record.`;
+}
+function formatError(error) {
+  const e = error;
+  if (e?.code && e?.message) {
+    const detail = e.details ? `
+
+details: ${JSON.stringify(e.details)}` : "";
+    return `Throttle API error ${e.code}${e.statusCode ? ` (HTTP ${e.statusCode})` : ""}: ${e.message}${detail}`;
+  }
+  return `Error: ${e?.message ?? String(error)}`;
+}
+
+// ../errors/dist/index.js
+var ThrottleError = class extends Error {
+  code;
+  statusCode;
+  details;
+  body;
+  constructor(args) {
+    super(args.message);
+    this.name = "ThrottleError";
+    this.code = args.code;
+    this.statusCode = args.statusCode;
+    this.details = args.details;
+    this.body = args.body;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/client.ts
+var ThrottleApiError = class extends ThrottleError {
+  constructor(code, message, statusCode, details) {
+    super({ code, message, statusCode, details });
+    this.name = "ThrottleApiError";
+  }
+};
+function buildQuery(query) {
+  if (!query) return "";
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === null || value === "") continue;
+    params.set(key, String(value));
+  }
+  const qs = params.toString();
+  return qs ? `?${qs}` : "";
+}
+var API_KEY_PREFIX_RE = /^(sk_|pk_)/;
+var ThrottleClient = class {
+  constructor(auth, fetchImpl = fetch) {
+    this.auth = auth;
+    this.fetchImpl = fetchImpl;
+  }
+  /**
+   * Swap the credential every later request is sent with. The hosted remote
+   * server builds one client per MCP session at `initialize`, but an OAuth
+   * access token lives one hour and the MCP client refreshes it underneath
+   * the session — each request then arrives with a newer bearer than the one
+   * the session was opened with. Without this, the session keeps calling the
+   * REST API with the token it was born with and every tool fails with a 401
+   * the moment that first token expires, even though the caller is still
+   * perfectly authenticated.
+   */
+  setApiKey(apiKey) {
+    this.auth = { ...this.auth, apiKey };
+  }
+  async requestJson(method, path, options = {}) {
+    const url = `${this.auth.apiBaseUrl.replace(/\/$/, "")}${path}${buildQuery(options.query)}`;
+    const headers = {
+      "content-type": "application/json",
+      "x-api-key": this.auth.apiKey,
+      // Also sent as Authorization: Bearer — required for an OAuth access
+      // token (the remote server's oauth_token sessions), which the auth
+      // middleware only ever recognizes via this header (peeked by issuer),
+      // never via x-api-key. For an sk_/pk_ key this is a no-op: the
+      // middleware already treats `Authorization: Bearer sk_.../pk_...`
+      // identically to `X-API-Key`, so existing stdio-CLI callers are
+      // unaffected.
+      Authorization: `Bearer ${this.auth.apiKey}`
+    };
+    if (options.idempotencyKey) headers["idempotency-key"] = options.idempotencyKey;
+    if (options.applicationId && !API_KEY_PREFIX_RE.test(this.auth.apiKey)) {
+      headers["x-throttle-application-id"] = options.applicationId;
+    }
+    const sendsBody = method === "POST" || method === "PATCH" || method === "PUT";
+    const body = options.body !== void 0 ? JSON.stringify(options.body) : sendsBody ? "{}" : void 0;
+    const res = await this.fetchImpl(url, { method, headers, body });
+    const text = await res.text();
+    let parsed = {};
+    try {
+      parsed = text ? JSON.parse(text) : {};
+    } catch {
+    }
+    if (!res.ok) {
+      const err = parsed.error;
+      throw new ThrottleApiError(
+        err?.code ?? `http_${res.status}`,
+        err?.message ?? `Request failed (${res.status}): ${text.slice(0, 200)}`,
+        res.status,
+        err?.details
+      );
+    }
+    return parsed;
+  }
+  /** Unwraps the `{ data }` envelope. Key presence, not `??` — `{data: null}` unwraps to null. */
+  async get(path, query, options) {
+    const body = await this.requestJson("GET", path, { query, applicationId: options?.applicationId });
+    return body && typeof body === "object" && "data" in body ? body.data : body;
+  }
+  async list(path, query, options) {
+    const body = await this.requestJson("GET", path, { query, applicationId: options?.applicationId });
+    const data = "data" in body ? body.data : body;
+    const meta = body.meta;
+    return { data: Array.isArray(data) ? data : [], pagination: meta?.pagination ?? null };
+  }
+  async post(path, options = {}) {
+    const body = await this.requestJson("POST", path, options);
+    return body && typeof body === "object" && "data" in body ? body.data : body;
+  }
+  async patch(path, options = {}) {
+    const body = await this.requestJson("PATCH", path, options);
+    return body && typeof body === "object" && "data" in body ? body.data : body;
+  }
+};
+async function optional(load) {
+  try {
+    return { ok: true, value: await load() };
+  } catch (error) {
+    const e = error;
+    const code = e?.code ?? "error";
+    const reason = code === "insufficient_scopes" ? "not readable with this credential (missing scope)" : code === "not_found" ? "not found" : `unavailable (${code})`;
+    return { ok: false, unavailable: reason };
+  }
+}
+
+// src/contract.ts
+var RETIRED_FIELDS = {
+  storeId: "applicationId",
+  store_id: "applicationId",
+  merchantId: "workspaceId",
+  merchant_id: "workspaceId",
+  customer_id: "customerId",
+  line_items: "lineItems",
+  unit_price: "unitPrice",
+  external_id: "externalId",
+  payment_method_id: "paymentMethodId",
+  first_name: "firstName",
+  last_name: "lastName",
+  net_n: "netN",
+  hosted_url: "hostedUrl",
+  embed_url: "embedUrl",
+  checkout_url: "checkoutUrl",
+  order_number: "orderNumber",
+  payment_status: "paymentStatus",
+  allowed_origins: "allowedOrigins",
+  enabled_events: "enabledEvents",
+  template_key: "templateKey",
+  request_id: "requestId",
+  signing_secret: "signingSecret (returned once at creation; not accepted as input)"
+};
+function snakeToCamel(name) {
+  return name.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+function normalizePath(path) {
+  return path.replace(/\{[^}]+\}/g, "{}").replace(/:[A-Za-z0-9_]+/g, "{}").replace(/\/$/, "");
+}
+function segmentsOf(path) {
+  return path.split("?")[0].replace(/\/$/, "").split("/").filter(Boolean);
+}
+function isParamSegment(segment) {
+  return /^\{[^}]+\}$/.test(segment) || /^:[A-Za-z0-9_]+$/.test(segment);
+}
+function pathMatches(template, candidate) {
+  const t = segmentsOf(template);
+  const c = segmentsOf(candidate);
+  if (t.length !== c.length) return false;
+  return t.every((segment, i) => isParamSegment(segment) || isParamSegment(c[i]) || segment === c[i]);
+}
+function paramCount(path) {
+  return segmentsOf(path).filter(isParamSegment).length;
+}
+function findOperations(index, query) {
+  const method = query.method?.toUpperCase();
+  const wanted = query.path.trim();
+  const byMethod = (op) => !method || op.method === method;
+  const matched = index.operations.filter((op) => byMethod(op) && pathMatches(op.path, wanted)).sort((a, b) => paramCount(a.path) - paramCount(b.path));
+  if (matched.length > 0) return matched;
+  const needle = normalizePath(wanted).replace(/^\/+/, "");
+  return index.operations.filter((op) => byMethod(op) && normalizePath(op.path).includes(needle));
+}
+function validatePayload(index, input) {
+  const errors = [];
+  const warnings = [];
+  const keys = Object.keys(input.body ?? {});
+  for (const key of keys) {
+    const retired = RETIRED_FIELDS[key];
+    if (retired) {
+      errors.push({
+        field: key,
+        problem: "retired public field name \u2014 the API rejects it",
+        suggestion: `use "${retired}"`
+      });
+      continue;
+    }
+    if (key.includes("_")) {
+      errors.push({
+        field: key,
+        problem: "snake_case is not accepted on public request bodies",
+        suggestion: `use "${snakeToCamel(key)}"`
+      });
+    }
+  }
+  const matches = findOperations(index, { path: input.path, method: input.method });
+  const operation = matches[0];
+  if (!operation) {
+    return {
+      ok: false,
+      matched: null,
+      errors: [
+        ...errors,
+        {
+          field: input.path,
+          problem: `no ${input.method.toUpperCase()} operation matches this path in the published contract`,
+          suggestion: "call describe_endpoint to find the right path"
+        }
+      ],
+      warnings
+    };
+  }
+  if (!operation.bodyFields) {
+    return {
+      ok: errors.length === 0,
+      matched: `${operation.method} ${operation.path}`,
+      errors,
+      warnings,
+      note: "The contract publishes no request-body schema for this operation, so field-level checks beyond naming could not run."
+    };
+  }
+  const known = new Map(operation.bodyFields.map((f) => [f.name, f]));
+  for (const key of keys) {
+    if (RETIRED_FIELDS[key] || key.includes("_")) continue;
+    if (!known.has(key)) {
+      warnings.push({
+        field: key,
+        problem: "not documented on this operation \u2014 it will be rejected if the route validates strictly"
+      });
+    }
+  }
+  for (const field of operation.bodyFields) {
+    const value = (input.body ?? {})[field.name];
+    if (value === void 0) {
+      if (field.required) errors.push({ field: field.name, problem: "required field is missing" });
+      continue;
+    }
+    if (field.enum && field.enum.length > 0 && typeof value === "string" && !field.enum.includes(value)) {
+      errors.push({
+        field: field.name,
+        problem: `value "${value}" is not allowed`,
+        suggestion: `one of: ${field.enum.join(", ")}`
+      });
+    }
+  }
+  return {
+    ok: errors.length === 0,
+    matched: `${operation.method} ${operation.path}`,
+    errors,
+    warnings
+  };
+}
+
+// src/docs.ts
+var DOCS_ORIGIN = "https://usethrottle.dev/docs";
+function excerptAround(text, needle, radius = 160) {
+  const at = text.toLowerCase().indexOf(needle.toLowerCase());
+  if (at < 0) return text.slice(0, radius * 2).trim();
+  const start = Math.max(0, at - radius);
+  const end = Math.min(text.length, at + needle.length + radius);
+  return `${start > 0 ? "\u2026" : ""}${text.slice(start, end).trim()}${end < text.length ? "\u2026" : ""}`;
+}
+function searchDocs(index, query, limit = 5) {
+  const phrase = query.trim().toLowerCase();
+  if (!phrase) return [];
+  const terms = phrase.split(/\s+/).filter((t) => t.length > 1);
+  const scored = index.entries.map((entry) => {
+    const title = entry.title.toLowerCase();
+    const headings = entry.headings.join(" \0 ").toLowerCase();
+    const body = entry.text.toLowerCase();
+    let score = 0;
+    if (title === phrase) score += 100;
+    else if (title.startsWith(phrase)) score += 60;
+    else if (title.includes(phrase)) score += 40;
+    if (headings.includes(phrase)) score += 25;
+    if (body.includes(phrase)) score += 15;
+    for (const term of terms) {
+      if (title.includes(term)) score += 8;
+      if (headings.includes(term)) score += 4;
+      if (body.includes(term)) score += 1;
+    }
+    return { entry, score };
+  });
+  return scored.filter((s) => s.score > 0).sort((a, b) => b.score - a.score || a.entry.route.localeCompare(b.entry.route)).slice(0, Math.max(1, limit)).map(({ entry, score }) => ({
+    title: entry.title,
+    url: `${DOCS_ORIGIN}${entry.route}`,
+    score,
+    excerpt: excerptAround(entry.text, phrase)
+  }));
+}
+
+// src/handlers.ts
+function coveringAction(operation) {
+  const target = normalizePath(operation.path);
+  for (const action of ACTIONS) {
+    const hit = action.requests.some(
+      (r) => r.method === operation.method && normalizePath(r.path) === target
+    );
+    if (hit) return { tool: action.id, requiredScopes: action.scopes };
+  }
+  return {};
+}
+var page = (args) => ({ limit: args.limit, cursor: args.cursor });
+var HANDLERS = {
+  // ---------------------------------------------------------------- identity
+  whoami: async (ctx) => ({
+    ...ctx.identity,
+    note: ctx.identity.environment.providerEnvironment === "production" ? "This credential is pinned to PRODUCTION. Reads return live data." : "This credential is pinned to a non-production environment. Nothing here is live data."
+  }),
+  // ------------------------------------------------------- docs and contract
+  search_docs: async (ctx, args) => {
+    const hits = searchDocs(ctx.docs, String(args.query ?? ""), Number(args.limit ?? 5));
+    return hits.length > 0 ? { hits } : { hits: [], note: "No documentation matched. Try fewer or more general terms." };
+  },
+  describe_endpoint: async (ctx, args) => {
+    const operations = findOperations(ctx.contract, {
+      path: String(args.path ?? ""),
+      method: args.method ? String(args.method) : void 0
+    });
+    if (operations.length === 0) {
+      return {
+        operations: [],
+        note: 'No operation matched. Paths look like /api/v1/orders; try a shorter fragment such as "orders".'
+      };
+    }
+    return {
+      operations: operations.slice(0, 8).map((op) => ({ ...op, ...coveringAction(op) })),
+      truncated: operations.length > 8 ? operations.length - 8 : void 0
+    };
+  },
+  validate_payload: async (ctx, args) => validatePayload(ctx.contract, {
+    method: String(args.method ?? "POST"),
+    path: String(args.path ?? ""),
+    body: args.body ?? {}
+  }),
+  // ------------------------------------------------------------- generic read
+  api_get: async (ctx, args) => {
+    const path = String(args.path ?? "");
+    const resolved = new URL(path, "https://throttle.invalid").pathname;
+    if (!path.startsWith("/api/v1/") || !resolved.startsWith("/api/v1/") || /(^|[\/\\])\.(\.)?([\/\\?#]|$)|%2e/i.test(path)) {
+      throw new Error(
+        `Refusing to call "${path}". api_get only reads paths beginning with /api/v1/ on the configured Throttle host.`
+      );
+    }
+    return ctx.client.get(path, void 0, { applicationId: args.applicationId });
+  },
+  // ------------------------------------------------------------------ orders
+  search_orders: async (ctx, args) => ctx.client.list(
+    "/api/v1/orders",
+    {
+      q: args.q,
+      status: args.status,
+      paymentStatus: args.paymentStatus,
+      createdAfter: args.createdAfter,
+      createdBefore: args.createdBefore,
+      ...page(args)
+    },
+    { applicationId: args.applicationId }
+  ),
+  get_order: async (ctx, args) => {
+    const id = String(args.id);
+    const opts = { applicationId: args.applicationId };
+    const order = await ctx.client.get(`/api/v1/orders/${id}`, void 0, opts);
+    const [payments, returns, fulfillments] = await Promise.all([
+      optional(() => ctx.client.list(`/api/v1/orders/${id}/payments`, void 0, opts)),
+      optional(() => ctx.client.list(`/api/v1/orders/${id}/returns`, void 0, opts)),
+      optional(() => ctx.client.list(`/api/v1/orders/${id}/fulfillments`, void 0, opts))
+    ]);
+    return {
+      order,
+      payments: payments.ok ? payments.value.data : payments.unavailable,
+      returns: returns.ok ? returns.value.data : returns.unavailable,
+      fulfillments: fulfillments.ok ? fulfillments.value.data : fulfillments.unavailable
+    };
+  },
+  // --------------------------------------------------------------- customers
+  search_customers: async (ctx, args) => ctx.client.list(
+    "/api/v1/customers",
+    {
+      q: args.q,
+      createdAfter: args.createdAfter,
+      createdBefore: args.createdBefore,
+      ...page(args)
+    },
+    { applicationId: args.applicationId }
+  ),
+  get_customer: async (ctx, args) => {
+    const id = String(args.id);
+    const opts = { applicationId: args.applicationId };
+    const customer = await ctx.client.get(`/api/v1/customers/${id}`, void 0, opts);
+    const [addresses, subscriptions] = await Promise.all([
+      optional(() => ctx.client.list(`/api/v1/customers/${id}/addresses`, void 0, opts)),
+      optional(() => ctx.client.list("/api/v1/subscriptions", { customerId: id }, opts))
+    ]);
+    return {
+      customer,
+      addresses: addresses.ok ? addresses.value.data : addresses.unavailable,
+      subscriptions: subscriptions.ok ? subscriptions.value.data : subscriptions.unavailable
+    };
+  },
+  // ----------------------------------------------------------- subscriptions
+  list_subscriptions: async (ctx, args) => ctx.client.list(
+    "/api/v1/subscriptions",
+    {
+      customerId: args.customerId,
+      status: args.status,
+      createdAfter: args.createdAfter,
+      createdBefore: args.createdBefore,
+      ...page(args)
+    },
+    { applicationId: args.applicationId }
+  ),
+  get_subscription: async (ctx, args) => ctx.client.get(`/api/v1/subscriptions/${String(args.id)}`, void 0, {
+    applicationId: args.applicationId
+  }),
+  // ------------------------------------------------------------------ quotes
+  search_quotes: async (ctx, args) => ctx.client.list(
+    "/api/v1/quotes",
+    {
+      status: args.status,
+      createdAfter: args.createdAfter,
+      createdBefore: args.createdBefore,
+      ...page(args)
+    },
+    { applicationId: args.applicationId }
+  ),
+  get_quote: async (ctx, args) => ctx.client.get(`/api/v1/quotes/${String(args.id)}`, void 0, {
+    applicationId: args.applicationId
+  }),
+  // ---------------------------------------------------------------- invoices
+  list_invoices: async (ctx, args) => ctx.client.list(
+    "/api/v1/invoices",
+    { status: args.status, ...page(args) },
+    { applicationId: args.applicationId }
+  ),
+  receivables_aging: async (ctx, args) => ctx.client.get("/api/v1/invoices/aging", void 0, { applicationId: args.applicationId }),
+  // --------------------------------------------------------------- discounts
+  search_discounts: async (ctx, args) => ctx.client.list(
+    "/api/v1/discounts",
+    {
+      q: args.q,
+      code: args.code,
+      type: args.type,
+      isActive: args.isActive,
+      createdAfter: args.createdAfter,
+      createdBefore: args.createdBefore,
+      ...page(args)
+    },
+    { applicationId: args.applicationId }
+  ),
+  get_discount: async (ctx, args) => ctx.client.get(`/api/v1/discounts/${String(args.id)}`, void 0, {
+    applicationId: args.applicationId
+  }),
+  // ---------------------------------------------------------------- payments
+  search_payments: async (ctx, args) => ctx.client.list(
+    "/api/v1/payments",
+    {
+      method: args.method,
+      status: args.status,
+      // The route only accepts these as snake_case query params -- confirmed
+      // by reading its querystring schema directly, not assumed from the
+      // platform's usual camelCase convention.
+      order_id: args.orderId,
+      aging: args.aging,
+      due_from: args.dueFrom,
+      due_to: args.dueTo,
+      amount_min: args.amountMin,
+      amount_max: args.amountMax,
+      ...page(args)
+    },
+    { applicationId: args.applicationId }
+  ),
+  get_payment: async (ctx, args) => {
+    const id = String(args.id);
+    const opts = { applicationId: args.applicationId };
+    const payment = await ctx.client.get(`/api/v1/payments/${id}`, void 0, opts);
+    const transactions = await optional(
+      () => ctx.client.list(`/api/v1/payments/${id}/transactions`, void 0, opts)
+    );
+    return {
+      payment,
+      transactions: transactions.ok ? transactions.value.data : transactions.unavailable
+    };
+  },
+  // ---------------------------------------------------------------- invoices
+  get_invoice: async (ctx, args) => ctx.client.get(`/api/v1/invoices/${String(args.id)}`, void 0, {
+    applicationId: args.applicationId
+  }),
+  // ------------------------------------------------------------------ carts
+  list_abandoned_carts: async (ctx, args) => {
+    const opts = { applicationId: args.applicationId };
+    const [carts, summary] = await Promise.all([
+      optional(() => ctx.client.list("/api/v1/abandoned-carts", { ...page(args) }, opts)),
+      optional(
+        () => ctx.client.get("/api/v1/abandoned-carts/summary", { sinceDays: args.sinceDays }, opts)
+      )
+    ]);
+    return {
+      carts: carts.ok ? carts.value.data : carts.unavailable,
+      summary: summary.ok ? summary.value : summary.unavailable
+    };
+  },
+  // --------------------------------------------------------------- debugging
+  search_events: async (ctx, args) => ctx.client.list(
+    "/api/v1/events",
+    {
+      type: args.type,
+      entityType: args.entityType,
+      entityId: args.entityId,
+      ...page(args)
+    },
+    { applicationId: args.applicationId }
+  ),
+  list_webhook_deliveries: async (ctx, args) => ctx.client.list(
+    "/api/v1/webhook-deliveries",
+    {
+      endpointId: args.endpointId,
+      status: args.status,
+      eventType: args.eventType,
+      limit: args.limit
+    },
+    { applicationId: args.applicationId }
+  ),
+  get_webhook_delivery: async (ctx, args) => ctx.client.get(`/api/v1/webhook-deliveries/${String(args.id)}`, void 0, {
+    applicationId: args.applicationId
+  }),
+  send_test_webhook: async (ctx, args) => ctx.client.post(`/api/v1/webhook-endpoints/${String(args.id)}/test`, {
+    body: { eventType: args.eventType },
+    idempotencyKey: `mcp-send-test-webhook-${String(args.id)}-${Date.now()}`
+  }),
+  replay_webhook_delivery: async (ctx, args) => ctx.client.post(`/api/v1/webhook-deliveries/${String(args.id)}/replay`, {
+    idempotencyKey: `mcp-replay-webhook-delivery-${String(args.id)}-${Date.now()}`
+  }),
+  explain_checkout_failure: async (ctx, args) => {
+    const id = String(args.id);
+    const opts = { applicationId: args.applicationId };
+    const session = await optional(
+      () => ctx.client.get(`/api/v1/checkout-sessions/${id}`, void 0, opts)
+    );
+    if (!session.ok) {
+      return {
+        note: `No checkout session ${id} (${session.unavailable}). If this is a cart id, use search_events for its activity (or read /api/v1/carts/${id} with api_get, where that tool is available).`
+      };
+    }
+    const cartId = session.value?.cartId ?? void 0;
+    const [cart, sessionEvents, cartEvents, deliveries] = await Promise.all([
+      optional(() => ctx.client.get(`/api/v1/checkout-sessions/${id}/cart`, void 0, opts)),
+      optional(() => ctx.client.list("/api/v1/events", { entityId: id, limit: 25 }, opts)),
+      cartId ? optional(() => ctx.client.list("/api/v1/events", { entityId: cartId, limit: 25 }, opts)) : Promise.resolve({ ok: true, value: { data: [], pagination: null } }),
+      optional(() => ctx.client.list("/api/v1/webhook-deliveries", { limit: 15 }, opts))
+    ]);
+    return {
+      session: session.value,
+      cart: cart.ok ? cart.value : cart.unavailable,
+      events: [
+        ...sessionEvents.ok ? sessionEvents.value.data : [],
+        ...cartEvents.ok ? cartEvents.value.data : []
+      ],
+      eventsUnavailable: sessionEvents.ok ? void 0 : sessionEvents.unavailable,
+      recentWebhookDeliveries: deliveries.ok ? deliveries.value.data : deliveries.unavailable,
+      hint: "Compare the session state against the events: a session that never emitted checkout_started usually means the browser SDK failed before submitting, not a payment decline."
+    };
+  },
+  // ------------------------------------------------------------ sandbox seed
+  seed_test_data: async (ctx, args) => {
+    if (ctx.identity.environment.providerEnvironment === "production") {
+      throw new Error(
+        "seed_test_data refuses to run against a production environment. Use a non-production API key."
+      );
+    }
+    const stamp = Date.now();
+    const customer = await ctx.client.post("/api/v1/customers", {
+      body: {
+        email: String(args.customerEmail ?? `mcp-seed-${stamp}@example.test`),
+        firstName: "Seed",
+        lastName: "Customer"
+      },
+      idempotencyKey: `mcp-seed-customer-${stamp}`
+    });
+    const cart = await ctx.client.post("/api/v1/carts", {
+      // Unlike /api/v1/customers, cart creation requires applicationId
+      // explicitly in the body (it's cross-checked against the caller's own
+      // authenticated application, not inferred) -- omitting it is a real
+      // 400 missing_application_id from the live API, not a hypothetical.
+      body: { applicationId: ctx.identity.application?.id, customerId: customer?.id },
+      idempotencyKey: `mcp-seed-cart-${stamp}`
+    });
+    const requested = Array.isArray(args.lineItems) && args.lineItems.length > 0 ? args.lineItems : [{ name: "Seed widget", unitPrice: 2500, quantity: 2 }];
+    const items = [];
+    for (const [index, item] of requested.entries()) {
+      items.push(
+        await ctx.client.post(`/api/v1/carts/${cart?.id}/items`, {
+          body: item,
+          idempotencyKey: `mcp-seed-item-${stamp}-${index}`
+        })
+      );
+    }
+    const order = await ctx.client.post(`/api/v1/carts/${cart?.id}/finalize`, {
+      idempotencyKey: `mcp-seed-finalize-${stamp}`
+    });
+    return {
+      environment: ctx.identity.environment.slug,
+      customer,
+      cart,
+      lineItems: items,
+      order,
+      note: "Seeded a finalized DRAFT order. No payment was captured \u2014 that needs a browser-tokenised payment method, which a server-side key cannot produce."
+    };
+  },
+  // ---------------------------------------------------------- inbound writes
+  create_customer: async (ctx, args) => ctx.client.post("/api/v1/customers", {
+    // `createCustomerBody` is `.strict()`, so only fields it declares may be
+    // sent; `undefined` values drop out at JSON.stringify.
+    body: {
+      email: args.email,
+      firstName: args.firstName,
+      lastName: args.lastName,
+      phone: args.phone,
+      company: args.company,
+      externalId: args.externalId,
+      netN: args.netN,
+      acceptsMarketing: args.acceptsMarketing
+    },
+    idempotencyKey: `mcp-create-customer-${String(args.email)}-${Date.now()}`
+  }),
+  update_customer: async (ctx, args) => ctx.client.patch(`/api/v1/customers/${String(args.id)}`, {
+    // `id` is the path parameter, not a body field — `updateCustomerBody` is
+    // `.strict()` and would reject it. A null `externalId` is meaningful
+    // (it clears the value), so only `undefined` is dropped.
+    body: {
+      email: args.email,
+      firstName: args.firstName,
+      lastName: args.lastName,
+      phone: args.phone,
+      company: args.company,
+      externalId: args.externalId,
+      netN: args.netN,
+      acceptsMarketing: args.acceptsMarketing
+    },
+    idempotencyKey: `mcp-update-customer-${String(args.id)}-${Date.now()}`
+  }),
+  create_checkout_link: async (ctx, args) => {
+    const lineItems = Array.isArray(args.lineItems) ? args.lineItems : [];
+    if (lineItems.length === 0) {
+      throw new Error("create_checkout_link: lineItems must contain at least one item.");
+    }
+    const stamp = Date.now();
+    const applicationId = ctx.identity.application?.id;
+    const cart = await ctx.client.post("/api/v1/carts", {
+      body: {
+        applicationId,
+        customerId: args.customerId,
+        customerEmail: args.customerEmail,
+        netN: args.netN
+      },
+      idempotencyKey: `mcp-checkout-link-cart-${stamp}`
+    });
+    for (const [index, item] of lineItems.entries()) {
+      await ctx.client.post(`/api/v1/carts/${cart?.id}/items`, {
+        body: item,
+        idempotencyKey: `mcp-checkout-link-item-${stamp}-${index}`
+      });
+    }
+    const session = await ctx.client.post("/api/v1/checkout/sessions", {
+      body: {
+        applicationId,
+        cartId: cart?.id,
+        returnUrl: args.returnUrl,
+        cancelUrl: args.cancelUrl,
+        customerEmail: args.customerEmail,
+        discountCode: args.discountCode
+      },
+      idempotencyKey: `mcp-checkout-link-session-${stamp}`
+    });
+    return { cartId: cart?.id, ...session };
+  },
+  // -------------------------------------------------------------- money/mail
+  manage_subscription: async (ctx, args) => {
+    const id = String(args.id);
+    const action = String(args.action);
+    if (action !== "pause" && action !== "resume") {
+      throw new Error(`manage_subscription: action must be "pause" or "resume", got "${action}".`);
+    }
+    return ctx.client.post(`/api/v1/subscriptions/${id}/${action}`, {
+      idempotencyKey: `mcp-manage-subscription-${id}-${action}-${Date.now()}`
+    });
+  },
+  create_quote: async (ctx, args) => (
+    // The real route's body shape differs from this tool's flatter,
+    // model-facing input: line items are "items" (not "lineItems"), Net-N
+    // terms are nested under paymentTerms.netN with an explicit mode (not a
+    // flat "netN"), and the buyer-visible note field is "buyerNote" (not
+    // "notes"). Confirmed against packages/platform-api/src/validation/quotes.ts's
+    // actual zod schema after a live call 400'd with unrecognized_keys.
+    ctx.client.post("/api/v1/quotes", {
+      body: {
+        customerId: args.customerId,
+        items: args.items,
+        expiresAt: args.expiresAt,
+        paymentTerms: args.netN !== void 0 ? { mode: "net_terms", netN: args.netN } : void 0,
+        buyerNote: args.notes
+      },
+      idempotencyKey: `mcp-create-quote-${String(args.customerId)}-${Date.now()}`
+    })
+  ),
+  get_sales_timeseries: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/orders-timeseries",
+    {
+      from: args.from,
+      to: args.to,
+      groupBy: args.groupBy,
+      timezone: args.timezone,
+      compareTo: args.compareTo
+    },
+    { applicationId: args.applicationId }
+  ),
+  get_business_summary: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/business-summary",
+    {
+      period: args.period,
+      from: args.from,
+      to: args.to,
+      timezone: args.timezone
+    },
+    { applicationId: args.applicationId }
+  ),
+  get_attention_digest: async (ctx, args) => ctx.client.get("/api/v1/analytics/attention-digest", void 0, {
+    applicationId: args.applicationId
+  }),
+  get_top_products: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/products",
+    {
+      from: args.from,
+      to: args.to,
+      timezone: args.timezone,
+      by: args.by,
+      limit: args.limit
+    },
+    { applicationId: args.applicationId }
+  ),
+  // `.get()`, not `.list()` — the response is a single object (`{ data: {
+  // range, signups, ordersByCustomerType, topCustomers, totals } }`), and
+  // `.list()` only unwraps arrays: it would silently return an empty list
+  // instead of the real payload.
+  get_customer_growth: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/customers",
+    {
+      from: args.from,
+      to: args.to,
+      groupBy: args.groupBy,
+      timezone: args.timezone,
+      topBy: args.topBy,
+      topLimit: args.topLimit
+    },
+    { applicationId: args.applicationId }
+  ),
+  // `.get()`, not `.list()` — the response is a single object (`{ data: {
+  // range, dimension, rows, totals, note } }`), not a paginated array.
+  get_revenue_breakdown: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/revenue-breakdown",
+    {
+      dimension: args.dimension,
+      from: args.from,
+      to: args.to,
+      timezone: args.timezone
+    },
+    { applicationId: args.applicationId }
+  ),
+  // `.get()`, not `.list()` — the response is a single object (`{ data: {
+  // range, stages, conversionRate, dropOff, note } }`), not a paginated array.
+  get_funnel_conversion: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/funnel",
+    {
+      from: args.from,
+      to: args.to,
+      timezone: args.timezone
+    },
+    { applicationId: args.applicationId }
+  ),
+  // `.get()`, not `.list()` — the response is a single object (`{ data: {
+  // range, series, totals, note } }`), not a paginated array.
+  get_subscription_movement: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/subscriptions",
+    {
+      from: args.from,
+      to: args.to,
+      timezone: args.timezone,
+      groupBy: args.groupBy
+    },
+    { applicationId: args.applicationId }
+  ),
+  // `.get()`, not `.list()` — the response is a single object (`{ data: {
+  // range, rows, totals, note } }`), not a paginated array.
+  get_discount_performance: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/discounts",
+    {
+      from: args.from,
+      to: args.to,
+      timezone: args.timezone,
+      limit: args.limit
+    },
+    { applicationId: args.applicationId }
+  ),
+  // ------------------------------------------------------------- extensions
+  list_extension_installations: async (ctx, args) => ctx.client.list(
+    "/api/v1/installations",
+    { status: args.status, ...page(args) },
+    { applicationId: args.applicationId }
+  ),
+  // ------------------------------------------------------------- connectors
+  get_connector_routing: async (ctx, args) => {
+    const opts = { applicationId: args.applicationId };
+    const [paymentRouting, routingConnectors, cardDecline, otherDecline] = await Promise.all([
+      optional(() => ctx.client.get("/api/v1/payment-routing", void 0, opts)),
+      optional(() => ctx.client.get("/api/v1/routing-connectors", void 0, opts)),
+      optional(() => ctx.client.get("/api/v1/card-decline", void 0, opts)),
+      optional(() => ctx.client.get("/api/v1/other-decline", void 0, opts))
+    ]);
+    return {
+      paymentRouting: paymentRouting.ok ? paymentRouting.value : paymentRouting.unavailable,
+      routingConnectors: routingConnectors.ok ? routingConnectors.value : routingConnectors.unavailable,
+      cardDecline: cardDecline.ok ? cardDecline.value : cardDecline.unavailable,
+      otherDecline: otherDecline.ok ? otherDecline.value : otherDecline.unavailable
+    };
+  },
+  get_integration_status: async (ctx, args) => {
+    const opts = { applicationId: args.applicationId };
+    const [connectors, endpoints, coverage] = await Promise.all([
+      optional(() => ctx.client.list("/api/v1/connectors", void 0, opts)),
+      optional(() => ctx.client.list("/api/v1/webhook-endpoints", void 0, opts)),
+      optional(() => ctx.client.get("/api/v1/webhook-endpoints/coverage", void 0, opts))
+    ]);
+    const overridden = Boolean(args.applicationId) && args.applicationId !== ctx.identity.application?.id;
+    return {
+      environment: ctx.identity.environment,
+      workspace: ctx.identity.workspace,
+      applicationId: args.applicationId ?? ctx.identity.application?.id ?? null,
+      application: overridden ? void 0 : ctx.identity.application,
+      connectors: connectors.ok ? connectors.value.data : connectors.unavailable,
+      webhookEndpoints: endpoints.ok ? endpoints.value.data : endpoints.unavailable,
+      unsubscribedEvents: coverage.ok ? coverage.value : coverage.unavailable
+    };
+  },
+  // --------------------------------------------------------------- workspace
+  // No applicationId forwarding here: /api/v1/merchants/me is workspace-only
+  // (`WHERE workspace_id = ...`, never reads auth.applicationId) — an
+  // applicationId field on this tool would be a silent no-op affordance.
+  get_workspace_settings: async (ctx) => ctx.client.get("/api/v1/merchants/me"),
+  // No applicationId forwarding here either: /api/v1/audit-log filters by
+  // workspaceId (and optionally environmentId), never applicationId.
+  get_audit_log: async (ctx, args) => ctx.client.list("/api/v1/audit-log", { limit: args.limit }),
+  // --------------------------------------------------------- applications
+  // `.get()`, not `.list()` — the legacy /v1/stores route returns a bare
+  // array with no `meta.pagination`, and the brief calls for `.get()` here
+  // specifically.
+  list_applications: async (ctx) => ctx.client.get("/api/v1/stores")
+};
+
+// src/input.ts
+var import_zod = require("zod");
+function fieldsToZodShape(fields) {
+  const shape = {};
+  for (const field of fields) {
+    shape[field.name] = applyModifiers(field, baseType(field));
+  }
+  return shape;
+}
+function baseType(field) {
+  if (field.enum && field.enum.length > 0) {
+    return import_zod.z.enum([...field.enum]);
+  }
+  switch (field.type) {
+    case "string":
+      return import_zod.z.string();
+    case "number":
+      return import_zod.z.number();
+    case "boolean":
+      return import_zod.z.boolean();
+    case "array":
+      return import_zod.z.array(import_zod.z.unknown());
+    case "object":
+      return import_zod.z.record(import_zod.z.unknown());
+  }
+}
+function applyModifiers(field, type) {
+  const described = type.describe(field.description);
+  if (field.required) return described;
+  return field.default === void 0 ? described.optional() : described.default(field.default);
+}
+
+// src/projection.ts
+var S = "scalar";
+var T = "text";
+var PASS = "pass";
+var section = (shape) => ({ __section: shape });
+var oneOf = (values) => ({ __oneOf: new Set(values) });
+function isPrimitive(value) {
+  return value === null || ["string", "number", "boolean"].includes(typeof value);
+}
+var TOKEN = /^[^\s@]{0,200}$/;
+var OMITTED = { omitted: S, grantable: T, reason: T };
+var UNAVAILABLE = /^(not readable with this credential \(missing scope\)|not found|unavailable \([^\s@]{0,100}\))$/;
+function project(value, shape) {
+  if (value === void 0) return void 0;
+  if (shape === PASS) return value;
+  if (shape === S) {
+    if (!isPrimitive(value)) return void 0;
+    return typeof value === "string" && !TOKEN.test(value) ? null : value;
+  }
+  if (shape === T) return isPrimitive(value) ? value : void 0;
+  if ("__oneOf" in shape) {
+    if (!isPrimitive(value)) return void 0;
+    return typeof value === "string" && !shape.__oneOf.has(value) ? null : value;
+  }
+  if (Array.isArray(shape)) {
+    return Array.isArray(value) ? value.map((item) => project(item, shape[0])) : void 0;
+  }
+  if ("__section" in shape) {
+    if (typeof value === "string") return UNAVAILABLE.test(value) ? value : null;
+    if (value && typeof value === "object" && value.omitted === true) {
+      return project(value, OMITTED);
+    }
+    return project(value, shape.__section);
+  }
+  if (value === null) return null;
+  if (typeof value !== "object" || Array.isArray(value)) return void 0;
+  const out = {};
+  for (const [key, child] of Object.entries(shape)) {
+    const projected = project(value[key], child);
+    if (projected !== void 0) out[key] = projected;
+  }
+  return out;
+}
+var PAGINATION = { cursor: S, nextCursor: S, hasMore: S };
+var page2 = (row) => ({ data: [row], pagination: PAGINATION });
+var ADDRESS = { countryCode: S };
+var CUSTOMER_REF = { id: S };
+var APPLICATION = { id: S, name: T, slug: S };
+var LIFECYCLE_LABELS = ["Draft", "Pending", "Processing", "Partially fulfilled", "Fulfilled", "Cancelled", "Closed"];
+var DISPLAY_QUALIFIERS = [
+  "Comped",
+  "Awaiting payment",
+  "Authorized",
+  "Partially paid",
+  "Partially refunded",
+  "Refunded",
+  "Payment failed",
+  "Voided",
+  "Payment processing",
+  "Disputed",
+  "Authorization expired",
+  "Returned",
+  "Partially returned",
+  "Delivered",
+  "In transit"
+];
+var ORDER_DISPLAY_STATUSES = new Set(
+  LIFECYCLE_LABELS.flatMap((l) => [l, ...DISPLAY_QUALIFIERS.map((q) => `${l} \xB7 ${q}`)])
+);
+var DISPLAY_STATUS = oneOf(ORDER_DISPLAY_STATUSES);
+var RANGE = { from: S, to: S, timezone: S, groupBy: S };
+var LINE_ITEM = {
+  id: S,
+  type: S,
+  quantity: S,
+  unitPrice: S,
+  subtotal: S,
+  discountAmount: S,
+  taxAmount: S,
+  total: S,
+  recurring: S
+};
+var ORDER = {
+  id: S,
+  orderNumber: S,
+  status: S,
+  displayStatus: DISPLAY_STATUS,
+  paymentStatus: S,
+  type: S,
+  source: S,
+  currency: S,
+  subtotal: S,
+  discountTotal: S,
+  shippingTotal: S,
+  taxTotal: S,
+  total: S,
+  capturedAmount: S,
+  refundedAmount: S,
+  compAmount: S,
+  onHold: S,
+  taxReverseCharge: S,
+  customerId: S,
+  customer: CUSTOMER_REF,
+  subscriptionId: S,
+  shippingAddress: ADDRESS,
+  billingAddress: ADDRESS,
+  fulfillmentSummary: { itemsFulfilled: S, itemsRemaining: S, itemsTotal: S },
+  lineItems: [LINE_ITEM],
+  createdAt: S,
+  completedAt: S,
+  cancelledAt: S,
+  closedAt: S
+};
+var PAYMENT = {
+  id: S,
+  orderId: S,
+  status: S,
+  method: S,
+  processor: S,
+  amount: S,
+  capturedAmount: S,
+  currency: S,
+  cardBrand: S,
+  disputed: S,
+  disputeOpenedAt: S,
+  errorCode: S,
+  netN: S,
+  netNSource: S,
+  authorizedAt: S,
+  capturedAt: S,
+  voidedAt: S,
+  createdAt: S
+};
+var RETURN = {
+  id: S,
+  orderId: S,
+  status: S,
+  restock: S,
+  refundAmount: S,
+  refundPaymentId: S,
+  createdAt: S,
+  items: [{ lineItemId: S, quantity: S }]
+};
+var FULFILLMENT = {
+  id: S,
+  orderId: S,
+  type: S,
+  status: S,
+  createdAt: S,
+  lineItems: [{ lineItemId: S, quantity: S }],
+  detail: { carrier: T, serviceLevel: T, trackingNumber: T, trackingUrl: T, shippedAt: S, estimatedDelivery: S, actualDelivery: S }
+};
+var CUSTOMER = { id: S, netN: S, acceptsMarketing: S, createdAt: S };
+var SUBSCRIPTION = {
+  id: S,
+  status: S,
+  planName: T,
+  planReference: T,
+  amount: S,
+  currency: S,
+  interval: S,
+  quantity: S,
+  intervalUnit: S,
+  intervalCount: S,
+  totalPayments: S,
+  paymentsMade: S,
+  completedAt: S,
+  customerId: S,
+  customer: CUSTOMER_REF,
+  currentPeriodStart: S,
+  currentPeriodEnd: S,
+  billingAnchorAt: S,
+  cancelAtPeriodEnd: S,
+  trialEnd: S,
+  pausedAt: S,
+  cancelledAt: S,
+  lastPaymentAt: S,
+  failureCount: S,
+  pendingPlanName: T,
+  pendingPlanReference: T,
+  pendingAmount: S,
+  pendingInterval: S,
+  pendingQuantity: S,
+  pendingIntervalUnit: S,
+  pendingIntervalCount: S,
+  createdAt: S
+};
+var QUOTE_SUMMARY = {
+  id: S,
+  quoteNumber: S,
+  status: S,
+  source: S,
+  currency: S,
+  total: S,
+  customerId: S,
+  orderId: S,
+  expiresAt: S,
+  acceptedAt: S,
+  declinedAt: S,
+  createdAt: S
+};
+var QUOTE = {
+  ...QUOTE_SUMMARY,
+  revisions: [{
+    id: S,
+    revisionNumber: S,
+    state: S,
+    subtotal: S,
+    discountTotal: S,
+    shippingTotal: S,
+    taxTotal: S,
+    total: S,
+    depositAmount: S,
+    shippingMode: S,
+    issuedAt: S,
+    expiresAt: S,
+    paymentTerms: { mode: S, netN: S, balanceNetN: S, deposit: { type: S, value: S } },
+    items: [{
+      type: S,
+      quantity: S,
+      unitPrice: S,
+      subtotal: S,
+      discountAmount: S,
+      taxAmount: S,
+      total: S,
+      optional: S,
+      optionalSelected: S
+    }]
+  }],
+  // Who commented and when, never what they wrote.
+  comments: [{ authorType: S, visibility: S, createdAt: S }],
+  timeline: [{ type: S, actorType: S, createdAt: S }]
+};
+var INVOICE = {
+  id: S,
+  number: S,
+  status: S,
+  sourceType: S,
+  sourceId: S,
+  customerId: S,
+  currency: S,
+  subtotal: S,
+  discountTotal: S,
+  shippingTotal: S,
+  taxTotal: S,
+  total: S,
+  amountRefunded: S,
+  issuedAt: S,
+  dueAt: S,
+  periodStart: S,
+  periodEnd: S,
+  createdAt: S,
+  billingSnapshot: {
+    planName: T,
+    period: { start: S, end: S },
+    lineItems: [{ quantity: S, unitPrice: S, discountAmount: S, taxAmount: S, total: S }],
+    totals: { currency: S, subtotal: S, discountTotal: S, shippingTotal: S, taxTotal: S, total: S },
+    payment: { method: S, brand: S, status: S }
+  }
+};
+var DISCOUNT = {
+  id: S,
+  code: T,
+  name: T,
+  type: S,
+  value: S,
+  isActive: S,
+  startsAt: S,
+  endsAt: S,
+  usageCount: S,
+  usageLimit: S,
+  maxRedemptionsPerCustomer: S,
+  createdAt: S
+};
+var EVENT = {
+  id: S,
+  type: S,
+  entityType: S,
+  entityId: S,
+  createdAt: S,
+  data: {
+    status: S,
+    previousStatus: S,
+    action: S,
+    amount: S,
+    currency: S,
+    attempt: S,
+    orderId: S,
+    paymentId: S,
+    order: { id: S, orderNumber: S, status: S, paymentStatus: S, currency: S, total: S },
+    payment: { id: S, orderId: S, status: S, method: S, amount: S, currency: S },
+    subscription: { id: S, status: S, planName: T, amount: S, currency: S, interval: S },
+    fulfillment: { id: S, orderId: S, type: S, status: S }
+  }
+};
+var DELIVERY = {
+  id: S,
+  endpointId: S,
+  eventId: S,
+  eventType: S,
+  status: S,
+  attemptCount: S,
+  lastStatus: S,
+  deliveredAt: S,
+  nextRetryAt: S,
+  createdAt: S,
+  replayOf: S
+};
+var MONEY_COUNT = { count: S, totalCents: S };
+var ORDER_PERIOD = { orderCount: S, grossCents: S, netCents: S, refundsCents: S, avgOrderCents: S };
+var OAUTH_PROJECTIONS = {
+  whoami: {
+    type: S,
+    workspace: { name: T, slug: S },
+    application: APPLICATION,
+    environment: { slug: S, kind: S, providerEnvironment: S },
+    note: T
+  },
+  search_docs: PASS,
+  describe_endpoint: PASS,
+  validate_payload: PASS,
+  search_orders: page2(ORDER),
+  get_order: {
+    order: ORDER,
+    payments: section([PAYMENT]),
+    returns: section([RETURN]),
+    fulfillments: section([FULFILLMENT])
+  },
+  search_customers: page2(CUSTOMER),
+  get_customer: {
+    customer: CUSTOMER,
+    addresses: section([{ id: S, isDefault: S, ...ADDRESS }]),
+    subscriptions: section([SUBSCRIPTION])
+  },
+  list_subscriptions: page2(SUBSCRIPTION),
+  get_subscription: SUBSCRIPTION,
+  search_quotes: page2(QUOTE_SUMMARY),
+  get_quote: QUOTE,
+  list_invoices: page2(INVOICE),
+  get_invoice: INVOICE,
+  receivables_aging: {
+    buckets: [{ key: S, label: T, count: S, total_amount: S }],
+    total_outstanding_amount: S,
+    total_outstanding_count: S
+  },
+  search_discounts: page2(DISCOUNT),
+  get_discount: DISCOUNT,
+  search_payments: page2(PAYMENT),
+  get_payment: {
+    payment: PAYMENT,
+    transactions: section([{ id: S, type: S, status: S, amount: S, currency: S, createdAt: S }])
+  },
+  list_abandoned_carts: {
+    carts: section([{
+      id: S,
+      abandonedAt: S,
+      currency: S,
+      itemCount: S,
+      recoveryStatus: S,
+      total: S,
+      customer: { id: S }
+    }]),
+    summary: section({ abandonedCount: S, abandonedValue: S, recoveryEmailsSent: S, sinceDays: S })
+  },
+  search_events: page2(EVENT),
+  list_webhook_deliveries: page2(DELIVERY),
+  get_webhook_delivery: DELIVERY,
+  explain_checkout_failure: {
+    note: T,
+    hint: T,
+    session: {
+      id: S,
+      status: S,
+      cartId: S,
+      customerId: S,
+      expiresAt: S,
+      completedAt: S,
+      allowedMethods: [S],
+      collect: { shippingAddress: S, billingAddress: S, vatNumber: S },
+      shippingAddress: ADDRESS,
+      billingAddress: ADDRESS,
+      recurringTerms: {
+        interval: S,
+        intervalUnit: S,
+        intervalCount: S,
+        totalPayments: S,
+        taxApplies: S,
+        planChargedToday: S,
+        planName: T,
+        trialDays: S,
+        currency: S,
+        firstChargeAmountMinor: S
+      }
+    },
+    cart: section({
+      id: S,
+      status: S,
+      currency: S,
+      subtotal: S,
+      discountTotal: S,
+      shippingTotal: S,
+      taxTotal: S,
+      total: S,
+      itemCount: S,
+      items: [LINE_ITEM],
+      lineItems: [LINE_ITEM]
+    }),
+    events: [EVENT],
+    eventsUnavailable: T,
+    recentWebhookDeliveries: section([DELIVERY])
+  },
+  list_extension_installations: page2({
+    id: S,
+    extensionId: S,
+    extensionName: T,
+    extensionSlug: S,
+    versionId: S,
+    status: S,
+    environmentSlug: S,
+    installedAt: S,
+    uninstalledAt: S
+  }),
+  get_connector_routing: {
+    paymentRouting: section({
+      defaultCascade: [S],
+      rules: [{ cascade: [S], conditions: [{ type: S, op: S, currency: S, min: S, max: S, values: [S] }] }]
+    }),
+    cardDecline: section({ rules: [{ errorCode: S, conditions: [{ type: S, op: S, values: [S] }] }] }),
+    otherDecline: section({ rules: [{ errorCode: S, conditions: [{ type: S, op: S, values: [S] }] }] }),
+    routingConnectors: section([{ id: S, displayName: T, method: S }])
+  },
+  get_integration_status: {
+    environment: { slug: S, kind: S, providerEnvironment: S },
+    workspace: { name: T, slug: S },
+    applicationId: S,
+    application: APPLICATION,
+    connectors: section([{
+      id: S,
+      displayName: T,
+      method: S,
+      type: S,
+      status: S,
+      active: S,
+      position: S,
+      acceptedCountries: [S],
+      acceptedCurrencies: [S],
+      threeDSecureEnabled: S,
+      createdAt: S
+    }]),
+    webhookEndpoints: section([{ id: S, isActive: S, enabledEvents: [S], createdAt: S }]),
+    unsubscribedEvents: section({ windowDays: S, unsubscribed: [{ type: S, count: S, lastEmittedAt: S }] })
+  },
+  get_workspace_settings: { name: T, slug: S, brandColor: S, logoUrl: T, onboardingCompletedAt: S },
+  // What happened and to which record; not which team member did it.
+  get_audit_log: page2({ id: S, action: S, resourceType: S, resourceId: S, createdAt: S }),
+  list_applications: [{ id: S, name: T, slug: S, currency: S, isActive: S }],
+  // Analytics: computed aggregates, listed field by field all the same.
+  get_business_summary: {
+    period: S,
+    range: RANGE,
+    orders: section({ current: ORDER_PERIOD, previous: ORDER_PERIOD, deltaPct: S }),
+    subscriptions: section({
+      mrr: { currentCents: S, periodStartCents: S, deltaPct: S },
+      newSubscriptions: S,
+      cancelledSubscriptions: S,
+      churnRate: S,
+      note: T
+    }),
+    receivables: section({ outstandingCents: S, outstandingCount: S }),
+    quotes: section({ sent: MONEY_COUNT, accepted: MONEY_COUNT, declined: MONEY_COUNT, expired: MONEY_COUNT })
+  },
+  get_attention_digest: {
+    disputes: section({ open: S, totalCents: S }),
+    subscriptionsInDunning: section(S),
+    overdueInvoices: section(MONEY_COUNT),
+    unhealthyWebhooks: section([{ endpointId: S, failureRate: S, attempts7d: S }])
+  },
+  get_sales_timeseries: {
+    application: APPLICATION,
+    range: RANGE,
+    currency: S,
+    days: S,
+    note: T,
+    series: [{ date: S, grossCents: S, orders: S }],
+    totalGrossCents: S,
+    totalOrders: S
+  },
+  // get_top_products has no entry, so it is not offered over OAuth: it ranks
+  // products by line-item reference id or name, which a buyer can type.
+  get_customer_growth: {
+    application: APPLICATION,
+    range: RANGE,
+    note: T,
+    topBy: S,
+    signups: { total: S, series: [{ date: S, signups: S }] },
+    ordersByCustomerType: { newCustomerOrders: S, returningCustomerOrders: S },
+    // The ranking, by id: a top customer's name and email stay behind.
+    topCustomers: [{ customerId: S, orderCount: S, revenueCents: S }],
+    totals: { customerCount: S, orderCount: S, revenueCents: S }
+  },
+  get_revenue_breakdown: {
+    application: APPLICATION,
+    range: RANGE,
+    dimension: S,
+    note: T,
+    rows: [{ key: S, orderCount: S, grossCents: S }],
+    totals: { orderCount: S, grossCents: S }
+  },
+  get_funnel_conversion: {
+    application: APPLICATION,
+    range: RANGE,
+    note: T,
+    conversionRate: S,
+    stages: [{ name: S, count: S }],
+    dropOff: [{ from: S, to: S, ratePct: S }]
+  },
+  get_subscription_movement: {
+    application: APPLICATION,
+    range: RANGE,
+    note: T,
+    series: [{ date: S, newSubscriptions: S, churnedSubscriptions: S, mrrDeltaCents: S }],
+    totals: { newSubscriptions: S, churnedSubscriptions: S, netMrrDeltaCents: S }
+  },
+  get_discount_performance: {
+    application: APPLICATION,
+    range: RANGE,
+    note: T,
+    rows: [{ discountId: S, code: T, redemptions: S, discountedRevenueCents: S, discountGivenCents: S }],
+    totals: { redemptions: S, discountedRevenueCents: S, discountGivenCents: S }
+  }
+};
+
+// src/server.ts
+var VERSION = true ? "0.2.1" : "0.0.0-dev";
+function registerableActions(policy) {
+  const isProduction = policy.identity.environment.providerEnvironment === "production";
+  return actionsForChannel("mcp").filter((action) => {
+    if (!HANDLERS[action.id]) return false;
+    if (action.credentialScoped && policy.allowCredentialScoped === false) return false;
+    if (!canRunAction(policy.identity.scopes, action)) return false;
+    if (action.kind === "read") return true;
+    if (action.sandboxOnly) return !isProduction && (policy.allowSandboxWrites ?? true);
+    if (!policy.allowWrites) return false;
+    return !isProduction || policy.allowLiveWrites;
+  });
+}
+function buildInstructions(identity, actions, policy) {
+  const isProduction = identity.environment.providerEnvironment === "production";
+  const where = [
+    identity.workspace?.name ?? identity.workspace?.slug ?? "unknown workspace",
+    identity.application?.name ?? identity.application?.slug ?? null
+  ].filter(Boolean).join(" / ");
+  const liveWrites = actions.filter((a) => a.kind === "write" && !a.sandboxOnly);
+  const sandboxWrites = actions.filter((a) => a.kind === "write" && a.sandboxOnly);
+  const lines = [
+    `Throttle MCP ${VERSION}. Connected to ${where}, environment "${identity.environment.slug}" (${isProduction ? "PRODUCTION \u2014 live data" : "non-production \u2014 not live data"}).`,
+    "",
+    "Conventions:",
+    "- The workspace and environment are fixed for this session and cannot be switched from inside a tool call. Call whoami if you need to state where you are.",
+    '- The application can vary per call: pass "applicationId" on a read or analytics tool to reach a different application in this workspace, and call list_applications to see which ones this connection can reach. Omitting applicationId uses the application this connection was authorized for.',
+    "- Every analytics result covers exactly ONE application and names it in `application`. Say which application a figure describes. If the user asks about their business as a whole and this connection reaches more than one application, do not answer from the default alone \u2014 call list_applications, then query each and add them up, or ask which application they mean.",
+    '- List tools return { data, pagination }. When pagination.hasMore is true, pass pagination.cursor back as "cursor" rather than raising "limit".',
+    "- Amounts are integer minor units (2500 = $25.00).",
+    "- Throttle rejects snake_case on public request bodies. Before writing integration code, confirm shapes with describe_endpoint and check bodies with validate_payload instead of guessing field names.",
+    "- API errors come back as text with a stable code. On insufficient_scopes, tell the user which scope to add \u2014 do not retry.",
+    "- Analytics results may mark a section `omitted`. That means UNKNOWN, never zero. When `grantable` is false the data cannot be read over this connection at all \u2014 say so rather than reporting an absence."
+  ];
+  if (liveWrites.length === 0) {
+    lines.push(
+      `- This session is READ-ONLY for real data${policy.allowWrites ? " (no write tools are available to this credential)" : " \u2014 writes were not enabled"}. Say so plainly if asked to change something.`
+    );
+    if (sandboxWrites.length > 0) {
+      lines.push(
+        `- ${sandboxWrites.map((a) => a.id).join(", ")} may create data, but only in this non-production environment.`
+      );
+    }
+  } else {
+    lines.push(
+      `- Write tools are enabled (${liveWrites.map((a) => a.id).join(", ")}). They are irreversible and some are buyer-visible. Confirm with the user before calling one.`
+    );
+  }
+  return lines.join("\n");
+}
+function declareSecuritySchemes(server, actions) {
+  const inner = server.server;
+  const handlers = inner._requestHandlers;
+  const original = handlers?.get("tools/list");
+  if (!original) return;
+  const schemes = new Map(
+    actions.map((a) => [
+      a.id,
+      [{
+        type: "oauth2",
+        scopes: [.../* @__PURE__ */ new Set([...a.scopes, ...a.sectionScopes ?? []])].filter((scope) => validateScopesForOAuth([scope]).ok)
+      }]
+    ])
+  );
+  inner.setRequestHandler(import_types.ListToolsRequestSchema, async (request, extra) => {
+    const result = await original(request, extra);
+    return {
+      ...result,
+      tools: result.tools.map((tool) => ({ ...tool, securitySchemes: schemes.get(tool.name) ?? [{ type: "oauth2", scopes: [] }] }))
+    };
+  });
+}
+function createServer(options) {
+  const redactPii = options.identity.type === "oauth_token" && !hasScope(options.identity.scopes, "customer_pii:read");
+  const actions = registerableActions(options).filter((a) => !redactPii || OAUTH_PROJECTIONS[a.id] !== void 0);
+  const server = new import_mcp.McpServer(
+    { name: "throttle", version: VERSION },
+    { instructions: buildInstructions(options.identity, actions, options) }
+  );
+  const ctx = {
+    client: options.client,
+    identity: options.identity,
+    contract: options.contract,
+    docs: options.docs
+  };
+  for (const action of actions) {
+    const handler = HANDLERS[action.id];
+    server.registerTool(
+      action.id,
+      {
+        title: action.title,
+        description: describeForModel(action),
+        inputSchema: fieldsToZodShape(action.input),
+        // Every hint is an explicit boolean: directory reviews (OpenAI's in
+        // particular) read a missing value as "unknown", not as false.
+        annotations: {
+          title: action.title,
+          readOnlyHint: action.kind === "read",
+          destructiveHint: action.kind === "write" && Boolean(action.destructive),
+          idempotentHint: Boolean(action.idempotent),
+          // Every tool is bounded to the connected workspace; none reaches the
+          // public internet or an open-ended set of external entities.
+          openWorldHint: false
+        }
+      },
+      async (args) => {
+        try {
+          if (redactPii && action.id === "search_customers" && typeof args?.q === "string" && args.q.trim() !== "") {
+            return {
+              content: [{ type: "text", text: "Customer text search is not available over this connection, because names, emails, phone numbers and external ids are withheld. List customers by creation date (createdAfter/createdBefore), or open one by its Throttle id from an order, quote or subscription." }],
+              isError: true
+            };
+          }
+          const result = await handler(ctx, args ?? {});
+          const shown = redactPii ? redactShopperPii(project(result, OAUTH_PROJECTIONS[action.id])) : result;
+          return { content: [{ type: "text", text: formatResult(shown) }] };
+        } catch (error) {
+          return {
+            content: [{ type: "text", text: formatError(error) }],
+            isError: true,
+            ...options.authChallenge && isCredentialRejection(error) ? {
+              _meta: {
+                "mcp/www_authenticate": [
+                  `${options.authChallenge}, error="invalid_token", error_description="The connected credential was rejected. Sign in again to continue."`
+                ]
+              }
+            } : {}
+          };
+        }
+      }
+    );
+  }
+  if (options.authChallenge) declareSecuritySchemes(server, actions);
+  return server;
+}
+function isCredentialRejection(error) {
+  return error?.statusCode === 401;
+}
+function describeForModel(action) {
+  const parts = [action.description];
+  if (action.guardrails && action.guardrails.length > 0) {
+    parts.push(`Constraints: ${action.guardrails.join(" ")}`);
+  }
+  return parts.join(" ");
+}
+
+// src/indexes.ts
+var import_node_fs = require("fs");
+var import_meta = {};
+function loadIndex(file, empty, label) {
+  try {
+    return JSON.parse((0, import_node_fs.readFileSync)(new URL(`./${file}`, import_meta.url), "utf8"));
+  } catch {
+    process.stderr.write(
+      `throttle-mcp: ${label} index missing (${file}); that tool will return no results. Run "pnpm --filter @usethrottle/mcp build:indexes".
+`
+    );
+    return empty;
+  }
+}
+function loadDocsIndex() {
+  return loadIndex("docs-index.json", { generatedAt: "", entries: [] }, "docs");
+}
+function loadContractIndex() {
+  return loadIndex("contract-index.json", { generatedAt: "", operations: [] }, "contract");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ThrottleClient,
+  VERSION,
+  buildInstructions,
+  createServer,
+  loadContractIndex,
+  loadDocsIndex,
+  registerableActions
+});
+//# sourceMappingURL=lib.cjs.map