@solvapay/mcp-core 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1397 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_OAUTH_PATHS: () => DEFAULT_OAUTH_PATHS,
+  MCP_TOOL_NAMES: () => MCP_TOOL_NAMES,
+  McpBearerAuthError: () => McpBearerAuthError,
+  NARRATORS: () => NARRATORS,
+  OPEN_TOOL_FOR_VIEW: () => OPEN_TOOL_FOR_VIEW,
+  SOLVAPAY_DEFAULT_CSP: () => SOLVAPAY_DEFAULT_CSP,
+  SOLVAPAY_MCP_VIEW_KINDS: () => SOLVAPAY_MCP_VIEW_KINDS,
+  SOLVAPAY_OVERVIEW_MARKDOWN: () => SOLVAPAY_OVERVIEW_MARKDOWN,
+  SOLVAPAY_OVERVIEW_MIME_TYPE: () => SOLVAPAY_OVERVIEW_MIME_TYPE,
+  SOLVAPAY_OVERVIEW_URI: () => SOLVAPAY_OVERVIEW_URI,
+  TOOL_FOR_VIEW: () => TOOL_FOR_VIEW,
+  VIEW_FOR_OPEN_TOOL: () => VIEW_FOR_OPEN_TOOL,
+  VIEW_FOR_TOOL: () => VIEW_FOR_TOOL,
+  balanceSummary: () => balanceSummary,
+  buildAuthInfoFromBearer: () => buildAuthInfoFromBearer,
+  buildPayableHandler: () => buildPayableHandler,
+  buildPaywallUiMeta: () => buildPaywallUiMeta,
+  buildSolvaPayDescriptors: () => buildSolvaPayDescriptors,
+  buildSolvaPayPrompts: () => buildSolvaPayPrompts,
+  buildSolvaPayRequest: () => buildSolvaPayRequest,
+  createBuildBootstrapPayload: () => createBuildBootstrapPayload,
+  decodeJwtPayload: () => decodeJwtPayload,
+  defaultGetCustomerRef: () => defaultGetCustomerRef,
+  enrichPurchase: () => enrichPurchase,
+  extractBearerToken: () => extractBearerToken,
+  getCustomerRefFromBearerAuthHeader: () => getCustomerRefFromBearerAuthHeader,
+  getCustomerRefFromJwtPayload: () => getCustomerRefFromJwtPayload,
+  getOAuthAuthorizationServerResponse: () => getOAuthAuthorizationServerResponse,
+  getOAuthProtectedResourceResponse: () => getOAuthProtectedResourceResponse,
+  mergeCsp: () => mergeCsp,
+  narrateActivatePlan: () => narrateActivatePlan,
+  narrateManageAccount: () => narrateManageAccount,
+  narrateTopup: () => narrateTopup,
+  narrateUpgrade: () => narrateUpgrade,
+  narratedToolResult: () => narratedToolResult,
+  parseMode: () => parseMode,
+  paywallToolResult: () => paywallToolResult,
+  previewJson: () => previewJson,
+  resolveOAuthPaths: () => resolveOAuthPaths,
+  toolErrorResult: () => toolErrorResult,
+  toolResult: () => toolResult,
+  uiPlaceholder: () => uiPlaceholder,
+  withoutTrailingSlash: () => withoutTrailingSlash
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/tool-names.ts
+var MCP_TOOL_NAMES = {
+  createPayment: "create_payment_intent",
+  processPayment: "process_payment",
+  createTopupPayment: "create_topup_payment_intent",
+  cancelRenewal: "cancel_renewal",
+  reactivateRenewal: "reactivate_renewal",
+  activatePlan: "activate_plan",
+  createCheckoutSession: "create_checkout_session",
+  createCustomerSession: "create_customer_session",
+  upgrade: "upgrade",
+  manageAccount: "manage_account",
+  topup: "topup"
+};
+
+// src/types.ts
+var SOLVAPAY_MCP_VIEW_KINDS = [
+  "checkout",
+  "account",
+  "topup",
+  "paywall",
+  "nudge"
+];
+var TOOL_FOR_VIEW = {
+  checkout: "upgrade",
+  account: "manage_account",
+  topup: "topup"
+};
+var VIEW_FOR_TOOL = Object.fromEntries(
+  Object.entries(TOOL_FOR_VIEW).map(([view, tool]) => [
+    tool,
+    view
+  ])
+);
+var OPEN_TOOL_FOR_VIEW = TOOL_FOR_VIEW;
+var VIEW_FOR_OPEN_TOOL = VIEW_FOR_TOOL;
+
+// src/narrate.ts
+var ZERO_DECIMAL = /* @__PURE__ */ new Set(["bif", "clp", "djf", "gnf", "jpy", "kmf", "krw", "mga", "pyg", "rwf", "ugx", "vnd", "vuv", "xaf", "xof", "xpf"]);
+function formatMoney(amountMinor, currency) {
+  if (amountMinor == null || !currency) return null;
+  const zero = ZERO_DECIMAL.has(currency.toLowerCase());
+  const major = zero ? amountMinor : amountMinor / 100;
+  try {
+    return new Intl.NumberFormat("en-US", {
+      style: "currency",
+      currency: currency.toUpperCase(),
+      maximumFractionDigits: zero ? 0 : 2
+    }).format(major);
+  } catch {
+    return `${currency.toUpperCase()} ${major.toFixed(zero ? 0 : 2)}`;
+  }
+}
+function formatDate(iso) {
+  if (!iso) return null;
+  try {
+    return new Date(iso).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
+  } catch {
+    return null;
+  }
+}
+function activePurchase(customer) {
+  const list = customer?.purchase?.purchases ?? [];
+  return list[0] ?? null;
+}
+function productName(data) {
+  const name = data.product?.name;
+  return typeof name === "string" && name ? name : "SolvaPay";
+}
+function balanceSummary(customer) {
+  const row = balanceRow(customer);
+  if (!row) return null;
+  return row.replace(/^Balance:\s*/, "");
+}
+function balanceRow(customer) {
+  if (!customer?.balance) return null;
+  const credits = customer.balance.credits ?? 0;
+  if (!credits && credits !== 0) return null;
+  const currency = customer.balance.displayCurrency;
+  const rate = customer.balance.displayExchangeRate ?? 1;
+  const majorMinor = currency ? Math.round(credits / rate) : null;
+  const money = formatMoney(majorMinor, currency ?? null);
+  const fmt = new Intl.NumberFormat("en-US").format(credits);
+  return money ? `Balance: ${fmt} credits (~${money})` : `Balance: ${fmt} credits`;
+}
+function commandsLine(commands) {
+  return `Commands: ${commands.map((c) => `\`/${c}\``).join(" ")}`;
+}
+function plansListLines(plans) {
+  return plans.map((p) => {
+    const name = p.name ?? "Plan";
+    const price = formatMoney(p.price, p.currency);
+    const cycle = p.billingCycle ? `/${p.billingCycle}` : "";
+    const type = p.planType === "free" ? "no payment required" : p.planType === "usage-based" ? "pay as you go" : p.planType === "trial" ? "trial" : "recurring";
+    if (price && p.planType !== "free") {
+      return `${name} \xB7 ${type} \xB7 ${price}${cycle}`;
+    }
+    return `${name} \xB7 ${type}`;
+  });
+}
+function hostedPortalLink(data) {
+  const url = data.portalUrl;
+  if (typeof url === "string" && /^https?:\/\//i.test(url)) {
+    return { uri: url, name: "Open hosted portal" };
+  }
+  return null;
+}
+function narrateManageAccount(data) {
+  const lines = [];
+  const customer = data.customer;
+  const active = activePurchase(customer);
+  const name = productName(data);
+  if (!active) {
+    lines.push(`**Welcome to ${name}**`);
+    lines.push("");
+    const plans = data.plans ?? [];
+    if (plans.length > 0) {
+      lines.push("No active plan. Plans available:");
+      lines.push(...plansListLines(plans));
+    } else {
+      lines.push("No active plan.");
+    }
+    lines.push("");
+    lines.push(commandsLine(["activate_plan", "upgrade"]));
+  } else {
+    lines.push(`**${name} \u2014 your account**`);
+    lines.push("");
+    const plan = active.planSnapshot;
+    if (plan) {
+      const planName = plan.name ?? "Plan";
+      const price = formatMoney(plan.price, plan.currency);
+      const cycle = plan.billingCycle ? `/${plan.billingCycle}` : "";
+      const end = formatDate(active.endDate);
+      const parts = [planName];
+      if (price && plan.planType !== "free") parts.push(`${price}${cycle}`);
+      if (end) parts.push(`renews ${end}`);
+      lines.push(`Plan: ${parts.join(" \xB7 ")}`);
+    }
+    const bal = balanceRow(customer);
+    if (bal) lines.push(bal);
+    lines.push("");
+    lines.push(commandsLine(["topup", "upgrade"]));
+  }
+  const links = [];
+  const portal = hostedPortalLink(data);
+  if (portal) links.push(portal);
+  return { text: lines.join("\n"), links };
+}
+function narrateUpgrade(data) {
+  const lines = [];
+  lines.push(`**Upgrade \u2014 ${productName(data)}**`);
+  lines.push("");
+  const plans = (data.plans ?? []).filter((p) => p.planType !== "free");
+  if (plans.length > 0) {
+    lines.push("Plans available:");
+    lines.push(...plansListLines(plans));
+  } else {
+    lines.push("No paid plans are configured on this product yet.");
+  }
+  lines.push("");
+  lines.push(commandsLine(["manage_account", "topup"]));
+  return { text: lines.join("\n") };
+}
+function narrateTopup(data) {
+  const lines = [];
+  lines.push(`**Top up \u2014 ${productName(data)}**`);
+  lines.push("");
+  const bal = balanceRow(data.customer);
+  if (bal) lines.push(bal);
+  const currency = data.customer?.balance?.displayCurrency ?? "USD";
+  const presets = [1e3, 2500, 5e3, 1e4].map((m) => formatMoney(m, currency)).filter(Boolean).join(" \xB7 ");
+  if (presets) lines.push(`Top-up presets: ${presets}`);
+  lines.push("");
+  lines.push(commandsLine(["manage_account"]));
+  return { text: lines.join("\n") };
+}
+function narrateActivatePlan(data) {
+  const lines = [];
+  lines.push(`**Activate a plan \u2014 ${productName(data)}**`);
+  lines.push("");
+  const plans = data.plans ?? [];
+  if (plans.length > 0) {
+    lines.push("Plans available:");
+    lines.push(...plansListLines(plans));
+  } else {
+    lines.push("No plans are configured on this product yet.");
+  }
+  lines.push("");
+  lines.push(commandsLine(["manage_account", "topup"]));
+  return { text: lines.join("\n") };
+}
+var NARRATORS = {
+  upgrade: narrateUpgrade,
+  manage_account: narrateManageAccount,
+  topup: narrateTopup,
+  activate_plan: narrateActivatePlan
+};
+var UI_OPENED_VERB = {
+  topup: (p) => `Opened ${p} top-up.`,
+  upgrade: (p) => `Opened ${p} upgrade.`,
+  manage_account: (p) => `Opened your ${p} account.`,
+  activate_plan: (p) => `Opened ${p} plan picker.`
+};
+function uiPlaceholder(tool, data) {
+  const name = productName(data);
+  const opened = UI_OPENED_VERB[tool](name);
+  const balance = balanceSummary(data.customer);
+  const parts = [opened];
+  if (balance) parts.push(`Balance: ${balance}.`);
+  parts.push("Pass `mode: 'text'` for a markdown summary.");
+  return parts.join(" ");
+}
+
+// src/helpers.ts
+var ZERO_DECIMAL_CURRENCIES = /* @__PURE__ */ new Set([
+  "bif",
+  "clp",
+  "djf",
+  "gnf",
+  "jpy",
+  "kmf",
+  "krw",
+  "mga",
+  "pyg",
+  "rwf",
+  "ugx",
+  "vnd",
+  "vuv",
+  "xaf",
+  "xof",
+  "xpf"
+]);
+function formatMinorUnits(amountMinor, currency) {
+  if (amountMinor == null || !currency) return null;
+  const zeroDecimal = ZERO_DECIMAL_CURRENCIES.has(currency.toLowerCase());
+  const fractionDigits = zeroDecimal ? 0 : 2;
+  const major = zeroDecimal ? amountMinor : amountMinor / 100;
+  try {
+    return new Intl.NumberFormat("en-US", {
+      style: "currency",
+      currency: currency.toUpperCase(),
+      minimumFractionDigits: fractionDigits,
+      maximumFractionDigits: fractionDigits
+    }).format(major);
+  } catch {
+    return null;
+  }
+}
+function enrichPurchase(purchase) {
+  const amount = typeof purchase.amount === "number" ? purchase.amount : void 0;
+  const originalAmount = typeof purchase.originalAmount === "number" ? purchase.originalAmount : void 0;
+  const currency = typeof purchase.currency === "string" ? purchase.currency : void 0;
+  const priceDisplay = formatMinorUnits(originalAmount, currency) ?? formatMinorUnits(amount, "USD");
+  const priceUsdDisplay = currency && currency.toUpperCase() !== "USD" ? formatMinorUnits(amount, "USD") : null;
+  const planSnapshot = purchase.planSnapshot;
+  const enrichedPlanSnapshot = planSnapshot && typeof planSnapshot === "object" ? (() => {
+    const snap = planSnapshot;
+    const price = typeof snap.price === "number" ? snap.price : void 0;
+    const snapCurrency = typeof snap.currency === "string" ? snap.currency : void 0;
+    const snapPriceDisplay = formatMinorUnits(price, snapCurrency);
+    return snapPriceDisplay ? { ...snap, priceDisplay: snapPriceDisplay } : snap;
+  })() : planSnapshot;
+  return {
+    ...purchase,
+    ...priceDisplay ? { priceDisplay } : {},
+    ...priceUsdDisplay ? { priceUsdDisplay } : {},
+    ...enrichedPlanSnapshot !== void 0 ? { planSnapshot: enrichedPlanSnapshot } : {}
+  };
+}
+function defaultGetCustomerRef(extra) {
+  const fromExtra = extra?.authInfo?.extra?.customer_ref;
+  if (typeof fromExtra === "string" && fromExtra.trim()) {
+    return fromExtra.trim();
+  }
+  return null;
+}
+function buildSolvaPayRequest(extra, options = {}) {
+  const {
+    method = "GET",
+    query,
+    body,
+    getCustomerRef = defaultGetCustomerRef,
+    origin = "http://solvapay-mcp-server.local/"
+  } = options;
+  const url = new URL(origin);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== void 0) url.searchParams.set(key, value);
+    }
+  }
+  const headers = new Headers();
+  const customerRef = getCustomerRef(extra);
+  if (customerRef) {
+    headers.set("x-user-id", customerRef);
+  }
+  const init = { method, headers };
+  if (body !== void 0) {
+    headers.set("content-type", "application/json");
+    init.body = JSON.stringify(body);
+  }
+  return new Request(url, init);
+}
+function toolResult(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data) }],
+    structuredContent: data
+  };
+}
+function parseMode(raw) {
+  if (raw === "ui" || raw === "text" || raw === "auto") return raw;
+  return "ui";
+}
+function narratedToolResult(tool, data, mode = "ui", baseMeta = void 0) {
+  const narrator = NARRATORS[tool];
+  if (!narrator) {
+    const fallback = toolResult(data);
+    if (mode === "text" && baseMeta && "ui" in baseMeta) {
+      const { ui: _ui, ...rest } = baseMeta;
+      return { ...fallback, _meta: rest };
+    }
+    return baseMeta ? { ...fallback, _meta: baseMeta } : fallback;
+  }
+  const { text, links } = narrator(data);
+  const narratedBlock = {
+    type: "text",
+    text,
+    annotations: { audience: ["assistant"] }
+  };
+  const resourceLinkBlocks = (links ?? []).map((l) => ({
+    type: "resource_link",
+    uri: l.uri,
+    name: l.name,
+    annotations: { audience: ["user"] }
+    // `resource_link` isn't in the structural content union we use for
+    // `SolvaPayCallToolResult`, but the official SDK accepts it — we
+    // cast at the boundary to keep the local type narrow while still
+    // shipping the enrichment.
+  }));
+  const placeholderBlock = {
+    type: "text",
+    text: uiPlaceholder(tool, data)
+  };
+  const content = mode === "ui" ? [placeholderBlock] : mode === "text" ? [narratedBlock, ...resourceLinkBlocks] : [narratedBlock, ...resourceLinkBlocks];
+  const meta = mode === "text" && baseMeta && "ui" in baseMeta ? Object.fromEntries(Object.entries(baseMeta).filter(([k]) => k !== "ui")) : baseMeta;
+  return {
+    content,
+    structuredContent: data,
+    ...meta ? { _meta: meta } : {}
+  };
+}
+function toolErrorResult(error) {
+  return {
+    isError: true,
+    content: [{ type: "text", text: JSON.stringify(error) }],
+    structuredContent: error
+  };
+}
+function previewJson(value, max = 400) {
+  try {
+    const json = JSON.stringify(value);
+    if (!json) return String(value);
+    return json.length > max ? `${json.slice(0, max)}\u2026(+${json.length - max} chars)` : json;
+  } catch {
+    return String(value);
+  }
+}
+
+// src/paywall-meta.ts
+function buildPaywallUiMeta(input) {
+  return {
+    ui: {
+      resourceUri: input.resourceUri
+    }
+  };
+}
+
+// src/paywallToolResult.ts
+var import_server = require("@solvapay/server");
+async function paywallToolResult(errOrGate, ctx) {
+  const paywallContent = errOrGate instanceof import_server.PaywallError ? errOrGate.structuredContent : errOrGate;
+  const narrationText = errOrGate instanceof import_server.PaywallError ? errOrGate.message : paywallContent.message;
+  let structuredContent;
+  if (ctx.buildBootstrap) {
+    const bootstrap = await ctx.buildBootstrap("paywall", ctx.extra, {
+      paywall: paywallContent
+    });
+    structuredContent = bootstrap;
+  } else {
+    structuredContent = paywallContent;
+  }
+  return {
+    // Deliberately `false`: paywall is a user-actionable gate, not a
+    // tool failure. Hosts short-circuit on `isError: true` and render
+    // the error text instead of opening the UI resource advertised by
+    // `_meta.ui`, which meant the paywall widget never appeared on
+    // MCPJam / Claude Desktop / ChatGPT Apps. The `structuredContent`
+    // and `content[0].text` still carry the gate reason so the LLM
+    // can narrate it, while `_meta.ui` triggers the widget.
+    isError: false,
+    content: [{ type: "text", text: narrationText }],
+    structuredContent,
+    _meta: buildPaywallUiMeta({ resourceUri: ctx.resourceUri })
+  };
+}
+
+// src/csp.ts
+var SOLVAPAY_DEFAULT_CSP = {
+  resourceDomains: [
+    "https://js.stripe.com",
+    "https://*.stripe.com",
+    "https://b.stripecdn.com"
+  ],
+  connectDomains: [
+    "https://api.stripe.com",
+    "https://m.stripe.com",
+    "https://r.stripe.com",
+    "https://q.stripe.com",
+    "https://errors.stripe.com"
+  ],
+  frameDomains: ["https://js.stripe.com", "https://hooks.stripe.com"]
+};
+function mergeCsp(overrides) {
+  if (!overrides) return SOLVAPAY_DEFAULT_CSP;
+  const merge = (base, extra) => extra && extra.length ? Array.from(/* @__PURE__ */ new Set([...base, ...extra])) : base;
+  return {
+    resourceDomains: merge(SOLVAPAY_DEFAULT_CSP.resourceDomains, overrides.resourceDomains),
+    connectDomains: merge(SOLVAPAY_DEFAULT_CSP.connectDomains, overrides.connectDomains),
+    frameDomains: merge(SOLVAPAY_DEFAULT_CSP.frameDomains, overrides.frameDomains)
+  };
+}
+
+// src/descriptors.ts
+var import_server3 = require("@solvapay/server");
+var import_zod = require("zod");
+
+// src/bootstrap-payload.ts
+var import_server2 = require("@solvapay/server");
+var okOrNull = (result) => (0, import_server2.isErrorResult)(result) ? null : result;
+function createBuildBootstrapPayload(options) {
+  const {
+    solvaPay,
+    productRef,
+    publicBaseUrl,
+    getCustomerRef = defaultGetCustomerRef
+  } = options;
+  const fetchPublishableKey = async () => {
+    try {
+      const platform = await solvaPay.apiClient.getPlatformConfig?.();
+      return platform?.stripePublishableKey ?? null;
+    } catch {
+      return null;
+    }
+  };
+  const buildRequest = (extra) => buildSolvaPayRequest(extra, { getCustomerRef });
+  const productQueryRequest = () => buildSolvaPayRequest(void 0, { query: { productRef }, getCustomerRef: () => null });
+  return async (view, extra, extras = {}) => {
+    const customerRef = getCustomerRef(extra);
+    const wrapError = (promise) => promise.catch((err) => ({
+      error: err instanceof Error ? err.message : String(err),
+      status: 500
+    }));
+    const unauthenticated = () => Promise.resolve({ error: "unauthenticated", status: 401 });
+    const [
+      stripePublishableKey,
+      merchantResult,
+      productResult,
+      plansResult,
+      purchaseResult,
+      paymentMethodResult,
+      balanceResult,
+      usageResult
+    ] = await Promise.all([
+      fetchPublishableKey(),
+      (0, import_server2.getMerchantCore)(buildRequest(void 0), { solvaPay }),
+      (0, import_server2.getProductCore)(productQueryRequest(), { solvaPay }),
+      wrapError((0, import_server2.listPlansCore)(productQueryRequest(), { solvaPay })),
+      customerRef ? wrapError((0, import_server2.checkPurchaseCore)(buildRequest(extra), { solvaPay })) : unauthenticated(),
+      customerRef ? wrapError((0, import_server2.getPaymentMethodCore)(buildRequest(extra), { solvaPay })) : unauthenticated(),
+      customerRef ? wrapError((0, import_server2.getCustomerBalanceCore)(buildRequest(extra), { solvaPay })) : unauthenticated(),
+      customerRef ? wrapError((0, import_server2.getUsageCore)(buildRequest(extra), { solvaPay })) : unauthenticated()
+    ]);
+    if ((0, import_server2.isErrorResult)(merchantResult)) {
+      throw new Error(`bootstrap: merchant lookup failed: ${merchantResult.error}`);
+    }
+    if ((0, import_server2.isErrorResult)(productResult)) {
+      throw new Error(`bootstrap: product lookup failed: ${productResult.error}`);
+    }
+    const plans = (0, import_server2.isErrorResult)(plansResult) ? [] : plansResult.plans;
+    const purchase = okOrNull(purchaseResult);
+    const enrichedPurchase = purchase ? {
+      ...purchase,
+      purchases: purchase.purchases.map(
+        (p) => enrichPurchase(p)
+      )
+    } : null;
+    const customer = customerRef ? {
+      ref: customerRef,
+      purchase: enrichedPurchase,
+      paymentMethod: okOrNull(paymentMethodResult),
+      balance: okOrNull(balanceResult),
+      usage: okOrNull(usageResult)
+    } : null;
+    const payload = {
+      view,
+      productRef,
+      stripePublishableKey,
+      returnUrl: publicBaseUrl,
+      merchant: merchantResult,
+      product: productResult,
+      plans,
+      customer
+    };
+    if (extras.paywall) payload.paywall = extras.paywall;
+    return payload;
+  };
+}
+
+// src/resources/overview.ts
+var SOLVAPAY_OVERVIEW_URI = "docs://solvapay/overview.md";
+var SOLVAPAY_OVERVIEW_MIME_TYPE = "text/markdown";
+var SOLVAPAY_OVERVIEW_MARKDOWN = `# SolvaPay MCP server \u2014 overview
+
+This MCP server connects a SolvaPay-protected product to your host so users can
+manage their plan, usage, and billing **without leaving the chat**. It is
+dual-audience: every tool returns a UI bootstrap for hosts that render MCP UI
+resources (\`basic-host\`, Claude Desktop, ChatGPT, etc.) and a markdown summary
+with clickable URLs for text-only hosts.
+
+## What the user can do
+
+- **Upgrade** \u2014 start or change a paid plan. \`/upgrade\` opens the embedded
+  checkout (Stripe Elements inline) on UI hosts and returns a hosted-checkout
+  URL on text hosts.
+- **Manage account** \u2014 current plan, balance, usage, payment method, cancel
+  or reactivate auto-renewal. Credits + usage are folded inline into the
+  account view. \`/manage_account\`.
+- **Top up credits** \u2014 add SolvaPay credits for usage-based plans.
+  \`/topup\`.
+- **Activate plan** \u2014 pick a plan from the list or activate a specific plan
+  by \`planRef\`. Free plans activate immediately, usage-based plans activate
+  when balance covers the configured usage, paid plans return the embedded
+  checkout or a hosted-checkout URL. \`/activate_plan\`.
+
+## How it fits together
+
+Each intent tool returns a full \`BootstrapPayload\` (merchant + product + plans
++ customer snapshot) so the embedded UI never fires per-view read calls. When
+a paywalled data tool hits the usage limit, its response carries the same
+payload with \`view: "paywall"\`, letting the host open the UI directly on the
+paywall screen \u2014 no second tool call required.
+
+Auth is handled by the SolvaPay OAuth bridge (see \`createMcpOAuthBridge\`). The
+bridge injects \`customer_ref\` onto every authenticated request; tools that
+need an authenticated caller return \`Unauthorized\` when it is missing.
+
+## Also see
+
+- \`docs://solvapay/overview.md\` (this resource) \u2014 agent-facing narration.
+- \`ui://<app>/mcp-app.html\` \u2014 the embedded UI shell.
+- \`tools/list\` + \`prompts/list\` \u2014 programmatic discovery of the intent tools
+  and their slash-command shortcuts.
+- Documentation: https://docs.solvapay.com/sdks/typescript/guides/mcp-app.
+`;
+
+// src/descriptors.ts
+function deriveIcons(branding) {
+  if (!branding) return void 0;
+  const assets = [];
+  if (branding.iconUrl) {
+    assets.push({ src: branding.iconUrl, sizes: ["any", "512x512"] });
+  } else if (branding.logoUrl) {
+    assets.push({ src: branding.logoUrl });
+  }
+  return assets.length > 0 ? assets : void 0;
+}
+var solvapayTool = (hints) => ({ openWorldHint: true, ...hints });
+var INTENT_TOOL_ANNOTATIONS = {
+  account: solvapayTool({ readOnlyHint: true, idempotentHint: true }),
+  topup: solvapayTool({ destructiveHint: true }),
+  checkout: solvapayTool({ destructiveHint: true })
+};
+var DEFAULT_VIEWS = [...SOLVAPAY_MCP_VIEW_KINDS];
+function buildSolvaPayDescriptors(options) {
+  const {
+    solvaPay,
+    productRef,
+    resourceUri,
+    htmlPath,
+    readHtml,
+    publicBaseUrl,
+    views = DEFAULT_VIEWS,
+    csp,
+    getCustomerRef = defaultGetCustomerRef,
+    onToolCall,
+    onToolResult,
+    branding
+  } = options;
+  const toolIcons = deriveIcons(branding);
+  if (!/^https?:\/\//i.test(publicBaseUrl)) {
+    throw new Error(
+      "buildSolvaPayDescriptors: publicBaseUrl must be an http(s) URL (Stripe confirmPayment rejects `ui://`)."
+    );
+  }
+  if (!htmlPath && !readHtml) {
+    throw new Error(
+      "buildSolvaPayDescriptors: either `htmlPath` (node) or `readHtml` (edge) must be provided."
+    );
+  }
+  const toolMeta = { ui: { resourceUri } };
+  const uiToolMeta = { ...toolMeta, audience: "ui" };
+  const enabledViews = new Set(views);
+  const tools = [];
+  const pushTool = (descriptor) => {
+    tools.push(toolIcons ? { ...descriptor, icons: toolIcons } : descriptor);
+  };
+  const UI_ONLY_PREFIX = "UI-only; agents should prefer `upgrade` / `manage_account` / `activate_plan`. ";
+  const buildRequest = (extra, init = {}) => buildSolvaPayRequest(extra, { ...init, getCustomerRef });
+  const requireCustomerRef = (extra) => {
+    const ref = getCustomerRef(extra);
+    if (!ref) {
+      return toolErrorResult({
+        error: "Unauthorized",
+        status: 401,
+        details: "customer_ref missing from MCP auth context"
+      });
+    }
+    return ref;
+  };
+  const trace = async (name, args, extra, handler) => {
+    const started = Date.now();
+    onToolCall?.(name, args, extra);
+    try {
+      const result = await handler();
+      if (onToolResult) onToolResult(name, result, { durationMs: Date.now() - started });
+      return result;
+    } catch (err) {
+      const errorResult = toolErrorResult({
+        error: err instanceof Error ? err.message : String(err),
+        status: 500,
+        details: previewJson(err)
+      });
+      if (onToolResult) onToolResult(name, errorResult, { durationMs: Date.now() - started });
+      return errorResult;
+    }
+  };
+  const buildBootstrapPayload = createBuildBootstrapPayload({
+    solvaPay,
+    productRef,
+    publicBaseUrl,
+    getCustomerRef
+  });
+  const pushIntentTool = (view, title, description) => {
+    if (!enabledViews.has(view)) return;
+    const name = TOOL_FOR_VIEW[view];
+    pushTool({
+      name,
+      title,
+      description,
+      // Every intent tool accepts an optional `mode` so users /
+      // agents on any host can opt into text-only responses (or
+      // suppress the narrated markdown when they know the host is
+      // rendering the UI iframe). Default `'auto'` emits both.
+      inputSchema: { mode: import_zod.z.enum(["ui", "text", "auto"]).optional() },
+      meta: toolMeta,
+      annotations: INTENT_TOOL_ANNOTATIONS[view],
+      handler: async (args, extra) => trace(name, args, extra, async () => {
+        const mode = parseMode(args.mode);
+        const data = await buildBootstrapPayload(view, extra);
+        return narratedToolResult(name, data, mode, toolMeta);
+      })
+    });
+  };
+  const MODE_HINT = " By default renders the UI iframe with a one-line placeholder; pass `mode: 'text'` for a markdown-only summary on CLI / text-only hosts, or `mode: 'auto'` to include both.";
+  pushIntentTool(
+    "checkout",
+    "Upgrade plan",
+    "Start or change a paid plan for the current customer. On UI hosts this opens the embedded checkout; on text hosts returns a markdown summary with a checkout URL. Also available: manage_account (current plan + cancel/reactivate), activate_plan (pick or activate a specific plan), topup (add credits)." + MODE_HINT
+  );
+  pushIntentTool(
+    "account",
+    "Manage account",
+    "Show or manage the current customer's SolvaPay account: plan, balance, usage, payment method, cancel/reactivate auto-renewal. On UI hosts this opens the embedded account view; on text hosts returns a markdown summary. Also available: upgrade (start/change a paid plan), activate_plan (pick or activate), topup (add credits)." + MODE_HINT
+  );
+  pushIntentTool(
+    "topup",
+    "Top up credits",
+    "Add SolvaPay credits for the current customer. On UI hosts this opens the embedded top-up flow; on text hosts returns a markdown summary with a top-up URL. Also available: manage_account (current plan + balance + usage), upgrade (switch to a recurring plan)." + MODE_HINT
+  );
+  pushTool({
+    name: MCP_TOOL_NAMES.createCheckoutSession,
+    description: UI_ONLY_PREFIX + "Create a SolvaPay hosted checkout session and return its URL. The UI opens this URL in a new tab when Stripe Elements is blocked by the host sandbox.",
+    inputSchema: {
+      planRef: import_zod.z.string().optional(),
+      productRef: import_zod.z.string().optional()
+    },
+    meta: uiToolMeta,
+    annotations: solvapayTool({}),
+    handler: async (args, extra) => trace(MCP_TOOL_NAMES.createCheckoutSession, args, extra, async () => {
+      const auth = requireCustomerRef(extra);
+      if (typeof auth !== "string") return auth;
+      const effectiveProduct = typeof args.productRef === "string" && args.productRef ? args.productRef : productRef;
+      const planRef = typeof args.planRef === "string" && args.planRef ? args.planRef : void 0;
+      const result = await (0, import_server3.createCheckoutSessionCore)(
+        buildRequest(extra, { method: "POST" }),
+        { productRef: effectiveProduct, planRef },
+        { solvaPay }
+      );
+      if ((0, import_server3.isErrorResult)(result)) return toolErrorResult(result);
+      return toolResult(result);
+    })
+  });
+  pushTool({
+    name: MCP_TOOL_NAMES.createPayment,
+    description: UI_ONLY_PREFIX + "Create a Stripe payment intent for the authenticated customer to purchase a plan. Returns { clientSecret, publishableKey, accountId?, customerRef } for confirmation with Stripe Elements in the app UI.",
+    inputSchema: {
+      planRef: import_zod.z.string(),
+      productRef: import_zod.z.string()
+    },
+    meta: uiToolMeta,
+    annotations: solvapayTool({}),
+    handler: async (args, extra) => trace(MCP_TOOL_NAMES.createPayment, args, extra, async () => {
+      const auth = requireCustomerRef(extra);
+      if (typeof auth !== "string") return auth;
+      const planRef = typeof args.planRef === "string" ? args.planRef : "";
+      const effectiveProduct = typeof args.productRef === "string" && args.productRef ? args.productRef : productRef;
+      const result = await (0, import_server3.createPaymentIntentCore)(
+        buildRequest(extra, { method: "POST" }),
+        { planRef, productRef: effectiveProduct },
+        { solvaPay }
+      );
+      if ((0, import_server3.isErrorResult)(result)) return toolErrorResult(result);
+      return toolResult(result);
+    })
+  });
+  pushTool({
+    name: MCP_TOOL_NAMES.processPayment,
+    description: UI_ONLY_PREFIX + "Process a Stripe payment intent after client-side confirmation and create the SolvaPay purchase. Call after confirmPayment resolves to short-circuit webhook latency.",
+    inputSchema: {
+      paymentIntentId: import_zod.z.string(),
+      productRef: import_zod.z.string(),
+      planRef: import_zod.z.string().optional()
+    },
+    meta: uiToolMeta,
+    annotations: solvapayTool({ destructiveHint: true }),
+    handler: async (args, extra) => trace(MCP_TOOL_NAMES.processPayment, args, extra, async () => {
+      const auth = requireCustomerRef(extra);
+      if (typeof auth !== "string") return auth;
+      const paymentIntentId = typeof args.paymentIntentId === "string" ? args.paymentIntentId : "";
+      const effectiveProduct = typeof args.productRef === "string" && args.productRef ? args.productRef : productRef;
+      const planRef = typeof args.planRef === "string" && args.planRef ? args.planRef : void 0;
+      const result = await (0, import_server3.processPaymentIntentCore)(
+        buildRequest(extra, { method: "POST" }),
+        { paymentIntentId, productRef: effectiveProduct, planRef },
+        { solvaPay }
+      );
+      if ((0, import_server3.isErrorResult)(result)) return toolErrorResult(result);
+      return toolResult(result);
+    })
+  });
+  pushTool({
+    name: MCP_TOOL_NAMES.createCustomerSession,
+    description: UI_ONLY_PREFIX + "Create a SolvaPay hosted customer portal session and return its URL. Used to let a paid customer manage or cancel their purchase in a new tab.",
+    inputSchema: {},
+    meta: uiToolMeta,
+    annotations: solvapayTool({ readOnlyHint: true, idempotentHint: true }),
+    handler: async (args, extra) => trace(MCP_TOOL_NAMES.createCustomerSession, args, extra, async () => {
+      const auth = requireCustomerRef(extra);
+      if (typeof auth !== "string") return auth;
+      const result = await (0, import_server3.createCustomerSessionCore)(buildRequest(extra, { method: "POST" }), {
+        solvaPay
+      });
+      if ((0, import_server3.isErrorResult)(result)) return toolErrorResult(result);
+      return toolResult(result);
+    })
+  });
+  pushTool({
+    name: MCP_TOOL_NAMES.createTopupPayment,
+    description: UI_ONLY_PREFIX + "Create a Stripe payment intent for a credit top-up. Credits are recorded by the SolvaPay webhook after confirmation.",
+    inputSchema: {
+      amount: import_zod.z.number().int().positive(),
+      currency: import_zod.z.string(),
+      description: import_zod.z.string().optional()
+    },
+    meta: uiToolMeta,
+    annotations: solvapayTool({}),
+    handler: async (args, extra) => trace(MCP_TOOL_NAMES.createTopupPayment, args, extra, async () => {
+      const auth = requireCustomerRef(extra);
+      if (typeof auth !== "string") return auth;
+      const amount = typeof args.amount === "number" ? args.amount : 0;
+      const currency = typeof args.currency === "string" ? args.currency : "";
+      const description = typeof args.description === "string" ? args.description : void 0;
+      const result = await (0, import_server3.createTopupPaymentIntentCore)(
+        buildRequest(extra, { method: "POST" }),
+        { amount, currency, description },
+        { solvaPay }
+      );
+      if ((0, import_server3.isErrorResult)(result)) return toolErrorResult(result);
+      return toolResult(result);
+    })
+  });
+  pushTool({
+    name: MCP_TOOL_NAMES.cancelRenewal,
+    description: UI_ONLY_PREFIX + "Cancel the auto-renewal on an active purchase. Backend keeps access until the current period ends.",
+    inputSchema: {
+      purchaseRef: import_zod.z.string(),
+      reason: import_zod.z.string().optional()
+    },
+    meta: uiToolMeta,
+    annotations: solvapayTool({ destructiveHint: true, idempotentHint: true }),
+    handler: async (args, extra) => trace(MCP_TOOL_NAMES.cancelRenewal, args, extra, async () => {
+      const auth = requireCustomerRef(extra);
+      if (typeof auth !== "string") return auth;
+      const purchaseRef = typeof args.purchaseRef === "string" ? args.purchaseRef : "";
+      const reason = typeof args.reason === "string" ? args.reason : void 0;
+      const result = await (0, import_server3.cancelPurchaseCore)(
+        buildRequest(extra, { method: "POST" }),
+        { purchaseRef, reason },
+        { solvaPay }
+      );
+      if ((0, import_server3.isErrorResult)(result)) return toolErrorResult(result);
+      return toolResult(result);
+    })
+  });
+  pushTool({
+    name: MCP_TOOL_NAMES.reactivateRenewal,
+    description: UI_ONLY_PREFIX + "Undo a pending cancellation so auto-renewal resumes. Only valid while the purchase is still active and its end date hasn't passed.",
+    inputSchema: { purchaseRef: import_zod.z.string() },
+    meta: uiToolMeta,
+    annotations: solvapayTool({ idempotentHint: true }),
+    handler: async (args, extra) => trace(MCP_TOOL_NAMES.reactivateRenewal, args, extra, async () => {
+      const auth = requireCustomerRef(extra);
+      if (typeof auth !== "string") return auth;
+      const purchaseRef = typeof args.purchaseRef === "string" ? args.purchaseRef : "";
+      const result = await (0, import_server3.reactivatePurchaseCore)(
+        buildRequest(extra, { method: "POST" }),
+        { purchaseRef },
+        { solvaPay }
+      );
+      if ((0, import_server3.isErrorResult)(result)) return toolErrorResult(result);
+      return toolResult(result);
+    })
+  });
+  pushTool({
+    name: MCP_TOOL_NAMES.activatePlan,
+    title: "Activate plan",
+    description: "Activate a plan for the current customer. With a `planRef`: free plans activate immediately; usage-based plans activate when the balance covers the configured usage; paid plans return a markdown checkout link on text hosts or open the embedded checkout on UI hosts. Without a `planRef`: returns the available plans so the customer can pick \u2014 UI hosts render the embedded checkout picker, text hosts see a plans list. Also available: upgrade (direct to checkout), manage_account (current plan + usage), topup (add credits)." + MODE_HINT,
+    inputSchema: {
+      productRef: import_zod.z.string().optional(),
+      planRef: import_zod.z.string().optional(),
+      mode: import_zod.z.enum(["ui", "text", "auto"]).optional()
+    },
+    meta: toolMeta,
+    annotations: solvapayTool({}),
+    handler: async (args, extra) => trace(MCP_TOOL_NAMES.activatePlan, args, extra, async () => {
+      const effectiveProduct = typeof args.productRef === "string" && args.productRef ? args.productRef : productRef;
+      const planRef = typeof args.planRef === "string" && args.planRef ? args.planRef : void 0;
+      const mode = parseMode(args.mode);
+      if (!planRef) {
+        if (!enabledViews.has("checkout")) {
+          return toolErrorResult({
+            error: "activate_plan requires a planRef on this server",
+            status: 400,
+            details: 'The checkout view (where the plan picker lives) is not enabled on this server. Pass `planRef` to activate a specific plan, or re-enable the "checkout" view via the `views` option.'
+          });
+        }
+        return narratedToolResult(
+          MCP_TOOL_NAMES.activatePlan,
+          await buildBootstrapPayload("checkout", extra),
+          mode,
+          toolMeta
+        );
+      }
+      const auth = requireCustomerRef(extra);
+      if (typeof auth !== "string") return auth;
+      const result = await (0, import_server3.activatePlanCore)(
+        buildRequest(extra, { method: "POST" }),
+        { productRef: effectiveProduct, planRef },
+        { solvaPay }
+      );
+      if ((0, import_server3.isErrorResult)(result)) return toolErrorResult(result);
+      return toolResult(result);
+    })
+  });
+  const resolvedCsp = mergeCsp(csp);
+  const resource = {
+    uri: resourceUri,
+    mimeType: "text/html;profile=mcp-app",
+    csp: resolvedCsp,
+    readHtml: readHtml ? readHtml : async () => {
+      const fs = await import("fs/promises");
+      return fs.readFile(htmlPath, "utf-8");
+    }
+  };
+  const prompts = buildSolvaPayPrompts({ enabledViews });
+  const docsResources = [
+    {
+      uri: SOLVAPAY_OVERVIEW_URI,
+      name: "SolvaPay MCP \u2014 overview",
+      title: "SolvaPay overview",
+      description: 'Agent-facing "start here" doc \u2014 explains the five intent tools, dual-audience fallback, and auth model before any tool is called.',
+      mimeType: SOLVAPAY_OVERVIEW_MIME_TYPE,
+      readBody: () => SOLVAPAY_OVERVIEW_MARKDOWN
+    }
+  ];
+  return { tools, resource, prompts, docsResources, buildBootstrapPayload };
+}
+function buildSolvaPayPrompts(options = {}) {
+  const enabled = options.enabledViews ?? new Set(DEFAULT_VIEWS);
+  const prompts = [];
+  const userMessage = (text) => ({
+    messages: [{ role: "user", content: { type: "text", text } }]
+  });
+  if (enabled.has("checkout")) {
+    prompts.push({
+      name: MCP_TOOL_NAMES.upgrade,
+      title: "Upgrade plan",
+      description: "Start or change a paid plan for the current customer.",
+      argsSchema: { planRef: import_zod.z.string().optional() },
+      handler: async ({ planRef }) => userMessage(
+        typeof planRef === "string" && planRef ? `Activate plan ${planRef} for me.` : "Show me the upgrade options for my SolvaPay account."
+      )
+    });
+  }
+  if (enabled.has("account")) {
+    prompts.push({
+      name: MCP_TOOL_NAMES.manageAccount,
+      title: "Manage account",
+      description: "Show the current plan, balance, payment method, and cancel/reactivate controls for the current customer.",
+      handler: async () => userMessage("Show me my SolvaPay account.")
+    });
+  }
+  if (enabled.has("topup")) {
+    prompts.push({
+      name: MCP_TOOL_NAMES.topup,
+      title: "Top up credits",
+      description: "Add SolvaPay credits to the current customer.",
+      argsSchema: { amount: import_zod.z.string().optional() },
+      handler: async ({ amount }) => userMessage(
+        typeof amount === "string" && amount ? `Top up my SolvaPay credits by ${amount}.` : "I want to top up my SolvaPay credits."
+      )
+    });
+  }
+  if (enabled.has("checkout")) {
+    prompts.push({
+      name: MCP_TOOL_NAMES.activatePlan,
+      title: "Activate plan",
+      description: "Pick a plan to activate, or activate a specific plan by ref.",
+      argsSchema: { planRef: import_zod.z.string().optional() },
+      handler: async ({ planRef }) => userMessage(
+        typeof planRef === "string" && planRef ? `Activate plan ${planRef} on my SolvaPay account.` : "What plans can I activate on my SolvaPay account?"
+      )
+    });
+  }
+  return prompts;
+}
+
+// src/payable-handler.ts
+var import_server5 = require("@solvapay/server");
+
+// src/response-context.ts
+var import_server4 = require("@solvapay/server");
+
+// src/response-envelope.ts
+function isResponseResult(value) {
+  return typeof value === "object" && value !== null && value.__solvapayResponse === true;
+}
+function assertResponseResult(value) {
+  if (!isResponseResult(value)) {
+    throw new Error(
+      "SolvaPay: registerPayable handler returned a raw value. Handlers must return ctx.respond(data, options?). If you believe you did, this is an internal bug \u2014 please file an issue at https://github.com/solvapay/solvapay-sdk/issues."
+    );
+  }
+  return value;
+}
+function makeResponseResult(data, options, emittedBlocks) {
+  return {
+    __solvapayResponse: true,
+    data,
+    ...options !== void 0 ? { options } : {},
+    ...emittedBlocks.length > 0 ? { emittedBlocks: [...emittedBlocks] } : {}
+  };
+}
+
+// src/response-context.ts
+function synthesizePlanStub(limits) {
+  if (!limits?.plan) return null;
+  return { reference: limits.plan };
+}
+function snapshotFromLimits(params) {
+  const { customerRef, limits, plan, refresh } = params;
+  return {
+    ref: customerRef,
+    balance: limits?.creditBalance ?? 0,
+    remaining: limits?.remaining ?? null,
+    withinLimits: limits?.withinLimits ?? true,
+    plan,
+    fresh: refresh
+  };
+}
+function buildResponseContext(params) {
+  const { customerRef, limits, product, bootstrapProduct, solvaPay } = params;
+  const bootstrapPlan = params.bootstrapPlan ?? synthesizePlanStub(limits);
+  const emittedBlocks = [];
+  const abortController = new AbortController();
+  const freshSnapshot = async () => {
+    const freshLimits = await solvaPay.checkLimits({
+      customerRef,
+      productRef: product,
+      meterName: "requests"
+    });
+    return snapshotFromLimits({
+      customerRef,
+      limits: freshLimits,
+      plan: bootstrapPlan,
+      refresh: freshSnapshot
+    });
+  };
+  const customer = snapshotFromLimits({
+    customerRef,
+    limits,
+    plan: bootstrapPlan,
+    refresh: freshSnapshot
+  });
+  const product_ = bootstrapProduct ?? {
+    reference: product,
+    name: product
+  };
+  function respond(data, options) {
+    return makeResponseResult(data, options, emittedBlocks);
+  }
+  function gate(reason) {
+    const message = reason ?? "Payment required";
+    const structuredContent = {
+      kind: "payment_required",
+      product,
+      checkoutUrl: "",
+      message
+    };
+    throw new import_server4.PaywallError(message, structuredContent);
+  }
+  const ctx = {
+    customer,
+    product: product_,
+    respond,
+    gate,
+    // ——————————————————————————————————————————————————————————————
+    // Reserved surface — V1 stubs, V1.1 real.
+    // ——————————————————————————————————————————————————————————————
+    emit: async (block) => {
+      emittedBlocks.push(block);
+    },
+    progress: async () => {
+    },
+    progressRaw: async () => {
+    },
+    signal: abortController.signal
+  };
+  return { ctx, emittedBlocks };
+}
+
+// src/payable-handler.ts
+function buildPayableHandler(solvaPay, ctx, handler) {
+  const { product, resourceUri, buildBootstrap, getCustomerRef } = ctx;
+  const wrappedBusinessLogic = async (args, handlerContext) => {
+    const limits = handlerContext?.limits ?? null;
+    const customerRef = handlerContext?.customerRef ?? "";
+    const { ctx: responseCtx } = buildResponseContext({
+      customerRef,
+      limits,
+      product,
+      solvaPay
+    });
+    return handler(args, responseCtx);
+  };
+  const protectedHandler = solvaPay.payable({ product, getCustomerRef }).mcp(wrappedBusinessLogic);
+  return async (args, extra) => {
+    const result = await protectedHandler(args, extra);
+    if ((0, import_server5.isPaywallStructuredContent)(result.structuredContent)) {
+      const existingMeta = typeof result._meta === "object" && result._meta !== null ? result._meta : {};
+      const gateContent = result.structuredContent;
+      const structuredContent = buildBootstrap ? await buildBootstrap("paywall", extra, {
+        paywall: gateContent
+      }) : result.structuredContent;
+      return {
+        ...result,
+        isError: false,
+        structuredContent,
+        _meta: {
+          ...existingMeta,
+          ...buildPaywallUiMeta({ resourceUri })
+        }
+      };
+    }
+    if (result.isError) {
+      return result;
+    }
+    const envelope = assertResponseResult(result.structuredContent);
+    return unwrapResponseEnvelope(
+      result,
+      envelope,
+      resourceUri,
+      buildBootstrap,
+      extra
+    );
+  };
+}
+async function unwrapResponseEnvelope(adapterResult, envelope, resourceUri, buildBootstrap, extra) {
+  const { data, options, emittedBlocks } = envelope;
+  const textOverride = options?.text;
+  const nudge = options?.nudge;
+  const primaryText = typeof textOverride === "string" ? textOverride : JSON.stringify(data);
+  const content = [
+    ...emittedBlocks ?? [],
+    { type: "text", text: primaryText }
+  ];
+  const existingMeta = typeof adapterResult._meta === "object" && adapterResult._meta !== null ? adapterResult._meta : {};
+  if (nudge) {
+    const structuredContent = buildBootstrap ? {
+      ...await buildBootstrap("nudge", extra),
+      nudge,
+      data
+    } : data;
+    return {
+      ...adapterResult,
+      content,
+      structuredContent,
+      _meta: {
+        ...existingMeta,
+        ...buildNudgeUiMeta({ resourceUri, nudge })
+      }
+    };
+  }
+  return {
+    ...adapterResult,
+    content,
+    structuredContent: data,
+    ...Object.keys(existingMeta).length > 0 ? { _meta: existingMeta } : {}
+  };
+}
+function buildNudgeUiMeta(input) {
+  return { ui: { resourceUri: input.resourceUri, nudge: input.nudge } };
+}
+
+// src/oauth-discovery.ts
+var DEFAULT_OAUTH_PATHS = {
+  register: "/oauth/register",
+  authorize: "/oauth/authorize",
+  token: "/oauth/token",
+  revoke: "/oauth/revoke"
+};
+function withoutTrailingSlash(value) {
+  return value.replace(/\/$/, "");
+}
+function resolveOAuthPaths(paths = {}) {
+  return { ...DEFAULT_OAUTH_PATHS, ...paths };
+}
+function getOAuthProtectedResourceResponse(publicBaseUrl) {
+  const resource = withoutTrailingSlash(publicBaseUrl);
+  return {
+    resource,
+    authorization_servers: [resource],
+    scopes_supported: ["openid", "profile", "email"]
+  };
+}
+function getOAuthAuthorizationServerResponse({
+  publicBaseUrl,
+  paths
+}) {
+  const base = withoutTrailingSlash(publicBaseUrl);
+  const p = resolveOAuthPaths(paths);
+  return {
+    issuer: base,
+    authorization_endpoint: `${base}${p.authorize}`,
+    token_endpoint: `${base}${p.token}`,
+    registration_endpoint: `${base}${p.register}`,
+    revocation_endpoint: `${base}${p.revoke}`,
+    token_endpoint_auth_methods_supported: ["client_secret_basic", "client_secret_post"],
+    response_types_supported: ["code"],
+    grant_types_supported: ["authorization_code", "refresh_token"],
+    scopes_supported: ["openid", "profile", "email"],
+    code_challenge_methods_supported: ["S256"]
+  };
+}
+
+// src/bearer.ts
+var McpBearerAuthError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "McpBearerAuthError";
+  }
+};
+function base64UrlDecode(input) {
+  const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = normalized.padEnd(normalized.length + (4 - normalized.length % 4) % 4, "=");
+  const bytes = Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
+  return new TextDecoder().decode(bytes);
+}
+function extractBearerToken(authorization) {
+  if (!authorization) return null;
+  if (!authorization.startsWith("Bearer ")) return null;
+  return authorization.slice(7).trim() || null;
+}
+function decodeJwtPayload(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) {
+    throw new McpBearerAuthError("Invalid JWT format");
+  }
+  try {
+    const payloadText = base64UrlDecode(parts[1]);
+    const payload = JSON.parse(payloadText);
+    return payload;
+  } catch {
+    throw new McpBearerAuthError("Invalid JWT payload");
+  }
+}
+function getCustomerRefFromJwtPayload(payload, options = {}) {
+  const claimPriority = options.claimPriority || ["customerRef", "customer_ref", "sub"];
+  for (const claim of claimPriority) {
+    const value = payload[claim];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  throw new McpBearerAuthError(
+    `No customer reference claim found (checked: ${claimPriority.join(", ")})`
+  );
+}
+function getCustomerRefFromBearerAuthHeader(authorization, options = {}) {
+  const token = extractBearerToken(authorization);
+  if (!token) {
+    throw new McpBearerAuthError("Missing bearer token");
+  }
+  const payload = decodeJwtPayload(token);
+  return getCustomerRefFromJwtPayload(payload, options);
+}
+
+// src/auth-bridge.ts
+function getClientId(payload, explicitClientId) {
+  if (explicitClientId) return explicitClientId;
+  const payloadClientId = typeof payload.client_id === "string" && payload.client_id || typeof payload.azp === "string" && payload.azp || typeof payload.aud === "string" && payload.aud || null;
+  return payloadClientId || "solvapay-mcp-client";
+}
+function getScopes(payload, defaultScopes) {
+  if (Array.isArray(payload.scp)) {
+    return payload.scp.filter((scope) => typeof scope === "string");
+  }
+  if (typeof payload.scope === "string" && payload.scope.trim()) {
+    return payload.scope.split(/\s+/).map((scope) => scope.trim()).filter(Boolean);
+  }
+  return defaultScopes;
+}
+function getExpiresAt(payload) {
+  return typeof payload.exp === "number" ? payload.exp : void 0;
+}
+function buildAuthInfoFromBearer(authorization, options = {}) {
+  const token = extractBearerToken(authorization);
+  if (!token) return null;
+  const payload = decodeJwtPayload(token);
+  const customerRef = getCustomerRefFromJwtPayload(payload, options);
+  const clientId = getClientId(payload, options.clientId);
+  const scopes = getScopes(payload, options.defaultScopes || []);
+  const expiresAt = getExpiresAt(payload);
+  return {
+    token,
+    clientId,
+    scopes,
+    expiresAt,
+    extra: {
+      customer_ref: customerRef,
+      ...options.includePayload ? { payload } : {}
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_OAUTH_PATHS,
+  MCP_TOOL_NAMES,
+  McpBearerAuthError,
+  NARRATORS,
+  OPEN_TOOL_FOR_VIEW,
+  SOLVAPAY_DEFAULT_CSP,
+  SOLVAPAY_MCP_VIEW_KINDS,
+  SOLVAPAY_OVERVIEW_MARKDOWN,
+  SOLVAPAY_OVERVIEW_MIME_TYPE,
+  SOLVAPAY_OVERVIEW_URI,
+  TOOL_FOR_VIEW,
+  VIEW_FOR_OPEN_TOOL,
+  VIEW_FOR_TOOL,
+  balanceSummary,
+  buildAuthInfoFromBearer,
+  buildPayableHandler,
+  buildPaywallUiMeta,
+  buildSolvaPayDescriptors,
+  buildSolvaPayPrompts,
+  buildSolvaPayRequest,
+  createBuildBootstrapPayload,
+  decodeJwtPayload,
+  defaultGetCustomerRef,
+  enrichPurchase,
+  extractBearerToken,
+  getCustomerRefFromBearerAuthHeader,
+  getCustomerRefFromJwtPayload,
+  getOAuthAuthorizationServerResponse,
+  getOAuthProtectedResourceResponse,
+  mergeCsp,
+  narrateActivatePlan,
+  narrateManageAccount,
+  narrateTopup,
+  narrateUpgrade,
+  narratedToolResult,
+  parseMode,
+  paywallToolResult,
+  previewJson,
+  resolveOAuthPaths,
+  toolErrorResult,
+  toolResult,
+  uiPlaceholder,
+  withoutTrailingSlash
+});