@solvapay/mcp-core 0.4.2 → 0.4.3

package/dist/index.cjs

@@ -38,9 +38,11 @@ __export(index_exports, {
   McpBearerAuthError: () => McpBearerAuthError,
   NARRATORS: () => NARRATORS,
   OPEN_TOOL_FOR_VIEW: () => OPEN_TOOL_FOR_VIEW,
+  PORTAL_AUTO_RECHARGE_QUERY: () => PORTAL_AUTO_RECHARGE_QUERY,
   SOLVAPAY_BOOTSTRAP_MIME_TYPE: () => SOLVAPAY_BOOTSTRAP_MIME_TYPE,
   SOLVAPAY_BOOTSTRAP_URI: () => SOLVAPAY_BOOTSTRAP_URI,
   SOLVAPAY_DEFAULT_CSP: () => SOLVAPAY_DEFAULT_CSP,
+  SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS: () => SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS,
   SOLVAPAY_MCP_VIEW_KINDS: () => SOLVAPAY_MCP_VIEW_KINDS,
   SOLVAPAY_OVERVIEW_MARKDOWN: () => SOLVAPAY_OVERVIEW_MARKDOWN,
   SOLVAPAY_OVERVIEW_MIME_TYPE: () => SOLVAPAY_OVERVIEW_MIME_TYPE,
@@ -53,6 +55,7 @@ __export(index_exports, {
   VIEW_FOR_TOOL: () => VIEW_FOR_TOOL,
   applyHideToolsByAudience: () => applyHideToolsByAudience,
   assertValidProductRef: () => import_core3.assertValidProductRef,
+  autoRechargeUrlFrom: () => autoRechargeUrlFrom,
   balanceSummary: () => balanceSummary,
   buildAuthInfoFromBearer: () => buildAuthInfoFromBearer,
   buildPayableHandler: () => buildPayableHandler,
@@ -120,10 +123,13 @@ var MCP_PROMPT_NAMES = {
 };
 
 // src/types.ts
-var SOLVAPAY_MCP_VIEW_KINDS = [
+var SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS = [
   "checkout",
   "account",
-  "topup",
+  "topup"
+];
+var SOLVAPAY_MCP_VIEW_KINDS = [
+  ...SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS,
   "auto-recharge"
 ];
 var TOOL_FOR_VIEW = {
@@ -756,6 +762,9 @@ function narrateTopup(data) {
   lines.push(recoveryLine(["account"]));
   return withCheckout(data, lines);
 }
+function autoRechargePortalUrl(data) {
+  return httpsUrl(data.autoRechargeUrl) ?? httpsUrl(data.portalUrl);
+}
 function narrateAutoRecharge(data) {
   const lines = [];
   lines.push(`**Auto-recharge \u2014 ${productName(data)}**`);
@@ -764,16 +773,27 @@ function narrateAutoRecharge(data) {
   const bal = balanceRow(customer);
   if (bal) lines.push(bal);
   const enabled = customer?.autoRecharge?.enabled === true;
-  lines.push(
-    enabled ? "Auto-recharge is on. It tops your balance up automatically so calls do not fail." : "Auto-recharge is off. Turn it on from the account page \u2014 it stores a card and tops your balance up automatically so calls do not fail."
-  );
-  const manage = manageRow(data);
-  if (manage) lines.push(manage);
+  const failed = customer?.autoRecharge?.status === "failed";
+  if (failed) {
+    lines.push("Auto-recharge failed \u2014 update your card to resume");
+  } else {
+    lines.push(
+      enabled ? "Auto-recharge is on. It tops your balance up automatically so calls do not fail." : "Auto-recharge is off. Turn it on from the link below \u2014 it stores a card and tops your balance up automatically so calls do not fail."
+    );
+  }
+  const manageUrl = autoRechargePortalUrl(data);
+  if (manageUrl) {
+    lines.push(`Manage: ${namedManageMarkdown(manageUrl)} (${CHECKOUT_TTL})`);
+  }
   lines.push("");
   lines.push(recoveryLine(["account"]));
   const links = [];
-  const portal = hostedPortalLink(data);
-  if (portal) links.push({ ...portal, name: enabled ? "Manage auto-recharge" : "Turn on auto-recharge" });
+  if (manageUrl) {
+    links.push({
+      uri: manageUrl,
+      name: enabled ? "Manage auto-recharge" : "Turn on auto-recharge"
+    });
+  }
   return { text: lines.join("\n"), links };
 }
 var NARRATORS = {
@@ -1000,7 +1020,8 @@ var BootstrapPayloadSchema = import_zod2.z.object({
   plans: import_zod2.z.array(import_zod2.z.record(import_zod2.z.string(), import_zod2.z.unknown())),
   customer: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.unknown()).nullable(),
   checkoutUrl: import_zod2.z.string().nullable().optional(),
-  portalUrl: import_zod2.z.string().nullable().optional()
+  portalUrl: import_zod2.z.string().nullable().optional(),
+  autoRechargeUrl: import_zod2.z.string().nullable().optional()
 }).passthrough();
 
 // src/derive-view.ts
@@ -1012,7 +1033,7 @@ function isOutOfCredits(customer) {
   const credits = customer?.balance?.credits;
   return credits === 0;
 }
-function deriveDefaultView(data, enabledViews = new Set(SOLVAPAY_MCP_VIEW_KINDS)) {
+function deriveDefaultView(data, enabledViews = new Set(SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS)) {
   const customer = data.customer;
   const preferred = !hasActivePlan(customer, data.productRef) ? "checkout" : isOutOfCredits(customer) ? "topup" : "account";
   if (enabledViews.has(preferred)) return preferred;
@@ -1181,6 +1202,18 @@ function resetMcpConfigLogForTests() {
 
 // src/bootstrap-payload.ts
 var import_server3 = require("@solvapay/server");
+
+// src/portal-links.ts
+var PORTAL_AUTO_RECHARGE_QUERY = "tab=credits&intent=autorecharge";
+function autoRechargeUrlFrom(customerUrl) {
+  if (typeof customerUrl !== "string" || !/^https?:\/\//i.test(customerUrl)) {
+    return null;
+  }
+  const separator = customerUrl.includes("?") ? "&" : "?";
+  return `${customerUrl}${separator}${PORTAL_AUTO_RECHARGE_QUERY}`;
+}
+
+// src/bootstrap-payload.ts
 var okOrNull = (result) => (0, import_server3.isErrorResult)(result) ? null : result;
 var buildProviderNotFoundMessage = () => [
   "Provider account not found on this SolvaPay deployment.",
@@ -1220,7 +1253,10 @@ function createBuildBootstrapPayload(options) {
     try {
       const platform = await solvaPay.apiClient.getPlatformConfig?.();
       return platform?.stripePublishableKey ?? null;
-    } catch {
+    } catch (err) {
+      console.warn("[solvapay] bootstrap: getPlatformConfig failed; stripePublishableKey omitted", {
+        error: err instanceof Error ? err.message : String(err)
+      });
       return null;
     }
   };
@@ -1286,6 +1322,12 @@ function createBuildBootstrapPayload(options) {
     if ((0, import_server3.isErrorResult)(productResult)) {
       throw createBootstrapProductError(productResult);
     }
+    if ((0, import_server3.isErrorResult)(plansResult)) {
+      console.warn("[solvapay] bootstrap: listPlans failed; plans omitted from payload", {
+        error: plansResult.error,
+        status: plansResult.status
+      });
+    }
     const plans = (0, import_server3.isErrorResult)(plansResult) ? [] : plansResult.plans;
     const purchase = okOrNull(resolvedPurchaseResult);
     const enrichedPurchase = purchase ? {
@@ -1333,7 +1375,8 @@ function createBuildBootstrapPayload(options) {
       plans,
       customer,
       checkoutUrl: checkout?.checkoutUrl ?? null,
-      portalUrl: portal?.customerUrl ?? null
+      portalUrl: portal?.customerUrl ?? null,
+      autoRechargeUrl: autoRechargeUrlFrom(portal?.customerUrl)
     };
   };
 }
@@ -1411,7 +1454,13 @@ var VIEWER_DESCRIPTION = 'Call when the user says "upgrade", "change plan", "buy
 var INTENT_MODE_SCHEMA = import_zod3.z.enum(["ui", "text", "auto"]).optional().describe(
   "Default `mode: 'auto'` returns a self-sufficient text summary (plan, price, https checkout URL) and still opens the iframe on UI hosts. Pass `mode: 'text'` to strip the iframe, or `mode: 'ui'` for a one-line placeholder that still includes the checkout URL."
 );
-var DEFAULT_VIEWS = [...SOLVAPAY_MCP_VIEW_KINDS];
+var DEFAULT_VIEWS = [...SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS];
+function readAutoRechargeArg(value) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  return value;
+}
 function buildSolvaPayDescriptors(options) {
   const {
     solvaPay,
@@ -1505,9 +1554,17 @@ function buildSolvaPayDescriptors(options) {
     publicBaseUrl,
     getCustomerRef
   });
-  const enabledViewList = SOLVAPAY_MCP_VIEW_KINDS.filter((view) => enabledViews.has(view));
-  if (enabledViewList.length > 0) {
-    const viewEnum = import_zod3.z.enum(enabledViewList).optional().describe(VIEW_PARAM_DESCRIPTION);
+  const advertisedViewList = SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS.filter(
+    (view) => enabledViews.has(view)
+  );
+  if (advertisedViewList.length > 0) {
+    const advertisedEnum = import_zod3.z.enum(
+      advertisedViewList
+    );
+    const viewEnum = import_zod3.z.preprocess(
+      (value) => value === "auto-recharge" ? "account" : value,
+      advertisedEnum
+    ).optional().describe(VIEW_PARAM_DESCRIPTION);
     pushTool({
       name: VIEWER_TOOL_NAME,
       title: "Account",
@@ -1518,11 +1575,11 @@ function buildSolvaPayDescriptors(options) {
       annotations: VIEWER_ANNOTATIONS,
       handler: async (args, extra) => trace(VIEWER_TOOL_NAME, args, extra, async () => {
         const requested = args.view === "checkout" || args.view === "account" || args.view === "topup" || args.view === "auto-recharge" ? args.view : void 0;
-        if (requested !== void 0 && !enabledViews.has(requested)) {
+        if (requested !== void 0 && requested !== "auto-recharge" && !enabledViews.has(requested)) {
           return toolErrorResult({
             error: `view '${requested}' is not enabled on this server`,
             status: 400,
-            details: `Enabled views: ${enabledViewList.join(", ")}. Pass one of those, or omit view to let the server pick.`
+            details: `Enabled views: ${advertisedViewList.join(", ")}. Pass one of those, or omit view to let the server pick.`
           });
         }
         const mode = parseMode(args.mode);
@@ -1577,14 +1634,22 @@ function buildSolvaPayDescriptors(options) {
   });
   pushTool({
     name: MCP_TOOL_NAMES.createPayment,
-    description: UI_ONLY_PREFIX + 'Create a Stripe payment intent for the authenticated customer. Pass purpose: "plan" to purchase a plan (returns { clientSecret, publishableKey, accountId?, customerRef }) or purpose: "topup" for a credit top-up (credits are recorded by webhook after confirmation).',
+    description: UI_ONLY_PREFIX + 'Create a Stripe payment intent for the authenticated customer. Pass purpose: "plan" to purchase a plan (returns { clientSecret, publishableKey, accountId?, customerRef }) or purpose: "topup" for a credit top-up (credits are recorded by webhook after confirmation). A topup may carry autoRecharge so the card entered for the top-up is saved as the auto-recharge funding source.',
     inputSchema: {
       purpose: import_zod3.z.enum(["plan", "topup"]).describe('"plan" for plan checkout; "topup" for credit top-up.'),
       planRef: import_zod3.z.string().optional(),
       productRef: import_zod3.z.string().optional(),
       currency: import_zod3.z.string().optional(),
       amount: import_zod3.z.number().int().positive().optional(),
-      description: import_zod3.z.string().optional()
+      description: import_zod3.z.string().optional(),
+      autoRecharge: import_zod3.z.object({
+        enabled: import_zod3.z.boolean(),
+        triggerType: import_zod3.z.literal("balance"),
+        thresholdAmountMajor: import_zod3.z.number().positive().optional(),
+        topupAmountMajor: import_zod3.z.number().positive().optional(),
+        maxMonthlySpendMajor: import_zod3.z.number().positive().optional(),
+        currency: import_zod3.z.string().length(3)
+      }).optional()
     },
     meta: uiToolMeta,
     annotations: solvapayTool({ readOnlyHint: false, destructiveHint: false }),
@@ -1599,6 +1664,14 @@ function buildSolvaPayDescriptors(options) {
           details: 'Pass purpose: "plan" or purpose: "topup".'
         });
       }
+      const autoRecharge = readAutoRechargeArg(args.autoRecharge);
+      if (purpose === "plan" && autoRecharge) {
+        return toolErrorResult({
+          error: "create_payment_intent plan does not accept autoRecharge",
+          status: 400,
+          details: 'autoRecharge is only honoured on purpose: "topup".'
+        });
+      }
       if (purpose === "topup") {
         const amount = typeof args.amount === "number" ? args.amount : 0;
         const currency2 = typeof args.currency === "string" ? args.currency : "";
@@ -1612,7 +1685,7 @@ function buildSolvaPayDescriptors(options) {
         }
         const result2 = await (0, import_server4.createTopupPaymentIntentCore)(
           buildRequest(extra, { method: "POST" }),
-          { amount, currency: currency2, description },
+          { amount, currency: currency2, description, ...autoRecharge ? { autoRecharge } : {} },
           { solvaPay }
         );
         if ((0, import_server4.isErrorResult)(result2)) return toolErrorResult(result2);
@@ -2261,9 +2334,11 @@ function buildAuthInfoFromBearer(authorization, options = {}) {
   McpBearerAuthError,
   NARRATORS,
   OPEN_TOOL_FOR_VIEW,
+  PORTAL_AUTO_RECHARGE_QUERY,
   SOLVAPAY_BOOTSTRAP_MIME_TYPE,
   SOLVAPAY_BOOTSTRAP_URI,
   SOLVAPAY_DEFAULT_CSP,
+  SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS,
   SOLVAPAY_MCP_VIEW_KINDS,
   SOLVAPAY_OVERVIEW_MARKDOWN,
   SOLVAPAY_OVERVIEW_MIME_TYPE,
@@ -2276,6 +2351,7 @@ function buildAuthInfoFromBearer(authorization, options = {}) {
   VIEW_FOR_TOOL,
   applyHideToolsByAudience,
   assertValidProductRef,
+  autoRechargeUrlFrom,
   balanceSummary,
   buildAuthInfoFromBearer,
   buildPayableHandler,

package/dist/index.d.cts

@@ -201,14 +201,14 @@ interface PaywallToolResult {
 /**
  * Which view a SolvaPay MCP server knows how to bootstrap.
  *
- * Each kind is a landing screen on the single `account` viewer:
- * `checkout`, `account`, `topup`, plus `auto-recharge` which is
- * reached by intent only (never a default). There is no `paywall` or `nudge`
- * view — those
- * responses are plain text narrations per the text-only paywall
- * refactor (merchant paywall / nudge tool results ship
- * `content[0].text` + `structuredContent = gate` and never open the
- * iframe).
+ * Advertised landings on the `account` viewer are `checkout`,
+ * `account`, and `topup`. `'auto-recharge'` is a deprecated leftover
+ * stamp: the tool schema does not offer it, but a leftover argument
+ * still opens the account surface (status row + portal link). There is
+ * no `paywall` or `nudge` view — those responses are plain text
+ * narrations per the text-only paywall refactor (merchant paywall /
+ * nudge tool results ship `content[0].text` + `structuredContent =
+ * gate` and never open the iframe).
  *
  * The legacy `'about'`, `'activate'`, and `'usage'` surfaces were
  * dropped earlier — About is served by tool descriptions + docs
@@ -216,7 +216,9 @@ interface PaywallToolResult {
  * `PlanActivationDispatcher`, and Usage folds inline into the account
  * view.
  */
-type SolvaPayMcpViewKind = 'checkout' | 'account' | 'topup' | 'auto-recharge';
+type SolvaPayMcpAdvertisedViewKind = 'checkout' | 'account' | 'topup';
+type SolvaPayMcpViewKind = SolvaPayMcpAdvertisedViewKind | 'auto-recharge';
+declare const SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS: readonly ["checkout", "account", "topup"];
 declare const SOLVAPAY_MCP_VIEW_KINDS: readonly ["checkout", "account", "topup", "auto-recharge"];
 /**
  * Payload returned by every `open_*` bootstrap tool and consumed by the
@@ -249,6 +251,12 @@ interface BootstrapPayload {
     checkoutUrl?: string | null;
     /** Customer portal URL for the current customer, when one could be minted. */
     portalUrl?: string | null;
+    /**
+     * Hosted portal URL that opens the auto-recharge form (`tab=credits&intent=autorecharge`).
+     * Null when no portal session could be minted. Suffixed in `@solvapay/mcp-core`
+     * from the same `customerUrl` as `portalUrl`.
+     */
+    autoRechargeUrl?: string | null;
 }
 /**
  * Content Security Policy allow-list inputs merged with the Stripe
@@ -844,6 +852,7 @@ declare const BootstrapPayloadSchema: z.ZodObject<{
     customer: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     checkoutUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     portalUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    autoRechargeUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$loose>;
 
 /**
@@ -1410,6 +1419,31 @@ declare const SOLVAPAY_OVERVIEW_URI = "docs://solvapay/overview.md";
 declare const SOLVAPAY_OVERVIEW_MIME_TYPE = "text/markdown";
 declare const SOLVAPAY_OVERVIEW_MARKDOWN = "# SolvaPay MCP server \u2014 overview\n\nThis MCP server connects a SolvaPay-protected product to your host so users can\nmanage their plan, usage, and billing **without leaving the chat**. It is\ndual-audience: every tool returns a UI bootstrap for hosts that render MCP UI\nresources (`basic-host`, Claude Desktop, ChatGPT, etc.) and a markdown summary\nwith clickable URLs for text-only hosts.\n\n## What the user can do\n\n- **Account** \u2014 one read-only viewer for every billing surface. Pass `view`:\n  `checkout` (upgrade / change plan / buy / subscribe), `account` (current\n  plan, cancel, billing), or `topup` (add credits). Omit `view` and the\n  server picks (no plan \u2192 checkout, out of credits \u2192 topup, else account).\n  Slash commands `/upgrade`, `/manage_account`, and `/topup` remap onto\n  this tool. `account`.\n- **Activate plan** \u2014 activate a specific plan by `planRef`. Free plans\n  activate immediately, usage-based plans activate when balance covers the\n  configured usage, paid plans return checkout. Requires `planRef` \u2014 to list\n  plans, call `account` with `view: \"checkout\"`. `/activate_plan`.\n\n## How it fits together\n\nThe viewer returns a full `BootstrapPayload` (merchant + product + plans\n+ customer snapshot) so the embedded UI never fires per-view read calls. When\na paywalled data tool hits the usage limit, its response is plain text: the\n`content[0].text` narration names the recovery tool (`account`, or\n`activate_plan` when a specific planRef is known) and inlines\n`gate.checkoutUrl` for terminal-first hosts. The structured gate rides on\n`structuredContent` for programmatic consumers. No widget iframe opens for a\ngate \u2014 the LLM reads the narration and, if the user agrees, calls the named\ntool which mounts the checkout / topup / account surface.\n\nAuth is handled by the SolvaPay OAuth bridge (see `createMcpOAuthBridge`). The\nbridge injects `customer_ref` onto every authenticated request; tools that\nneed an authenticated caller return `Unauthorized` when it is missing.\n\n## Also see\n\n- `docs://solvapay/overview.md` (this resource) \u2014 agent-facing narration.\n- `ui://<app>/mcp-app.html` \u2014 the embedded UI shell.\n- `tools/list` + `prompts/list` \u2014 programmatic discovery of the intent tools\n  and their slash-command shortcuts.\n";
 
+/**
+ * Hosted-portal deep links minted from a customer session URL.
+ *
+ * Phase 1 suffixes the already-minted `customerUrl` in the SDK so the
+ * MCP widget can land on the auto-recharge form without a new network
+ * call or a platform deploy. The query params are the same ones the
+ * customer-app manage page already parses (`tab=credits&intent=autorecharge`).
+ *
+ * Keep this constant in lockstep with
+ * `apps/customer-app/src/pages/customer/manage/index.tsx`. A rename
+ * there without a matching change here degrades to the Credits tab
+ * without the form open — not a dead link, but not the intended
+ * destination either.
+ */
+declare const PORTAL_AUTO_RECHARGE_QUERY = "tab=credits&intent=autorecharge";
+/**
+ * Suffix a minted customer-portal URL so it opens the auto-recharge
+ * form (or the Credits summary when auto-recharge is already on).
+ *
+ * Returns `null` for a missing or non-http URL — the same guard
+ * `narrate.ts` uses. No silent default: a missing portal URL yields
+ * `null` and the widget renders status without an action.
+ */
+declare function autoRechargeUrlFrom(customerUrl: string | null | undefined): string | null;
+
 /**
  * `buildPayableHandler(solvaPay, ctx, handler)` — framework-neutral
  * wrapper that produces an MCP tool handler enforcing the SolvaPay
@@ -1607,4 +1641,4 @@ interface BuildAuthInfoFromBearerOptions extends McpBearerCustomerRefOptions {
 }
 declare function buildAuthInfoFromBearer(authorization?: string | null, options?: BuildAuthInfoFromBearerOptions): McpToolExtra['authInfo'] | null;
 
-export { type ActivePlanPurchaseLike, type ApplyHideToolsByAudienceContext, type ApplyHideToolsByAudienceExtra, type ApplyHideToolsByAudienceOptions, type BootstrapCustomer, type BootstrapMerchant, type BootstrapPayload, BootstrapPayloadSchema, type BootstrapPlan, type BootstrapProduct, type BuildAuthInfoFromBearerOptions, type BuildBootstrapPayloadFn, type BuildPayableHandlerContext, type BuildSolvaPayDescriptorsOptions, type BuildSolvaPayRequestOptions, type ContentBlock, type CreateBuildBootstrapPayloadOptions, type CustomerSnapshot, DEFAULT_OAUTH_PATHS, type DcrFailureDiagnosticInput, type HideToolsByAudienceBypass, INTENT_TOOL_NAMES, type IntentToolName, MCP_PROMPT_NAMES, MCP_TOOL_NAMES, type McpAdapterOptions, McpBearerAuthError, type McpBearerCustomerRefOptions, type McpConfigLogInput, type McpPromptName, type McpToolExtra, type McpToolName, NARRATORS, type NarratorOutput, type NudgeSpec, type OAuthAuthorizationServerOptions, type OAuthBridgePaths, OPEN_TOOL_FOR_VIEW, type PayableHandler, type PaywallToolResult, type PaywallToolResultContext, type ResponseContext, type ResponseOptions, type ResponseResult, SOLVAPAY_BOOTSTRAP_MIME_TYPE, SOLVAPAY_BOOTSTRAP_URI, SOLVAPAY_DEFAULT_CSP, SOLVAPAY_MCP_VIEW_KINDS, SOLVAPAY_OVERVIEW_MARKDOWN, SOLVAPAY_OVERVIEW_MIME_TYPE, SOLVAPAY_OVERVIEW_URI, type SolvaPayBootstrapResourceDescriptor, type SolvaPayCallToolResult, type SolvaPayDescriptorBundle, type SolvaPayDocsResourceDescriptor, type SolvaPayMcpCsp, type SolvaPayMcpViewKind, type SolvaPayMerchantBranding, type SolvaPayPromptDescriptor, type SolvaPayPromptResult, type SolvaPayResourceDescriptor, type SolvaPayToolAnnotations, type SolvaPayToolDescriptor, type SolvaPayToolIcon, type SolvaPayToolMode, TOOL_FOR_VIEW, ToolErrorEnvelopeSchema, VIEWER_TOOL_NAME, VIEW_FOR_OPEN_TOOL, VIEW_FOR_TOOL, applyHideToolsByAudience, balanceSummary, buildAuthInfoFromBearer, buildPayableHandler, buildSolvaPayDescriptors, buildSolvaPayPrompts, buildSolvaPayRequest, createBuildBootstrapPayload, decodeJwtPayload, defaultGetCustomerRef, defaultIsChatGptRequest, deriveDefaultView, deriveIcons, enrichPurchase, extractBearerToken, getCustomerRefFromBearerAuthHeader, getCustomerRefFromJwtPayload, getOAuthAuthorizationServerResponse, getOAuthProtectedResourceResponse, isPlanPurchase, logDcrFailureDiagnostic, logMcpConfigOnce, mergeCsp, narrateActivatePlan, narrateAlreadyActive, narrateAutoRecharge, narrateManageAccount, narrateTopup, narrateUpgrade, narratedToolResult, parseMode, paywallToolResult, previewJson, resetMcpConfigLogForTests, resolveOAuthPaths, selectActivePlanPurchase, toolErrorResult, toolResult, uiPlaceholder, withoutTrailingSlash };
+export { type ActivePlanPurchaseLike, type ApplyHideToolsByAudienceContext, type ApplyHideToolsByAudienceExtra, type ApplyHideToolsByAudienceOptions, type BootstrapCustomer, type BootstrapMerchant, type BootstrapPayload, BootstrapPayloadSchema, type BootstrapPlan, type BootstrapProduct, type BuildAuthInfoFromBearerOptions, type BuildBootstrapPayloadFn, type BuildPayableHandlerContext, type BuildSolvaPayDescriptorsOptions, type BuildSolvaPayRequestOptions, type ContentBlock, type CreateBuildBootstrapPayloadOptions, type CustomerSnapshot, DEFAULT_OAUTH_PATHS, type DcrFailureDiagnosticInput, type HideToolsByAudienceBypass, INTENT_TOOL_NAMES, type IntentToolName, MCP_PROMPT_NAMES, MCP_TOOL_NAMES, type McpAdapterOptions, McpBearerAuthError, type McpBearerCustomerRefOptions, type McpConfigLogInput, type McpPromptName, type McpToolExtra, type McpToolName, NARRATORS, type NarratorOutput, type NudgeSpec, type OAuthAuthorizationServerOptions, type OAuthBridgePaths, OPEN_TOOL_FOR_VIEW, PORTAL_AUTO_RECHARGE_QUERY, type PayableHandler, type PaywallToolResult, type PaywallToolResultContext, type ResponseContext, type ResponseOptions, type ResponseResult, SOLVAPAY_BOOTSTRAP_MIME_TYPE, SOLVAPAY_BOOTSTRAP_URI, SOLVAPAY_DEFAULT_CSP, SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS, SOLVAPAY_MCP_VIEW_KINDS, SOLVAPAY_OVERVIEW_MARKDOWN, SOLVAPAY_OVERVIEW_MIME_TYPE, SOLVAPAY_OVERVIEW_URI, type SolvaPayBootstrapResourceDescriptor, type SolvaPayCallToolResult, type SolvaPayDescriptorBundle, type SolvaPayDocsResourceDescriptor, type SolvaPayMcpAdvertisedViewKind, type SolvaPayMcpCsp, type SolvaPayMcpViewKind, type SolvaPayMerchantBranding, type SolvaPayPromptDescriptor, type SolvaPayPromptResult, type SolvaPayResourceDescriptor, type SolvaPayToolAnnotations, type SolvaPayToolDescriptor, type SolvaPayToolIcon, type SolvaPayToolMode, TOOL_FOR_VIEW, ToolErrorEnvelopeSchema, VIEWER_TOOL_NAME, VIEW_FOR_OPEN_TOOL, VIEW_FOR_TOOL, applyHideToolsByAudience, autoRechargeUrlFrom, balanceSummary, buildAuthInfoFromBearer, buildPayableHandler, buildSolvaPayDescriptors, buildSolvaPayPrompts, buildSolvaPayRequest, createBuildBootstrapPayload, decodeJwtPayload, defaultGetCustomerRef, defaultIsChatGptRequest, deriveDefaultView, deriveIcons, enrichPurchase, extractBearerToken, getCustomerRefFromBearerAuthHeader, getCustomerRefFromJwtPayload, getOAuthAuthorizationServerResponse, getOAuthProtectedResourceResponse, isPlanPurchase, logDcrFailureDiagnostic, logMcpConfigOnce, mergeCsp, narrateActivatePlan, narrateAlreadyActive, narrateAutoRecharge, narrateManageAccount, narrateTopup, narrateUpgrade, narratedToolResult, parseMode, paywallToolResult, previewJson, resetMcpConfigLogForTests, resolveOAuthPaths, selectActivePlanPurchase, toolErrorResult, toolResult, uiPlaceholder, withoutTrailingSlash };

package/dist/index.d.ts

@@ -201,14 +201,14 @@ interface PaywallToolResult {
 /**
  * Which view a SolvaPay MCP server knows how to bootstrap.
  *
- * Each kind is a landing screen on the single `account` viewer:
- * `checkout`, `account`, `topup`, plus `auto-recharge` which is
- * reached by intent only (never a default). There is no `paywall` or `nudge`
- * view — those
- * responses are plain text narrations per the text-only paywall
- * refactor (merchant paywall / nudge tool results ship
- * `content[0].text` + `structuredContent = gate` and never open the
- * iframe).
+ * Advertised landings on the `account` viewer are `checkout`,
+ * `account`, and `topup`. `'auto-recharge'` is a deprecated leftover
+ * stamp: the tool schema does not offer it, but a leftover argument
+ * still opens the account surface (status row + portal link). There is
+ * no `paywall` or `nudge` view — those responses are plain text
+ * narrations per the text-only paywall refactor (merchant paywall /
+ * nudge tool results ship `content[0].text` + `structuredContent =
+ * gate` and never open the iframe).
  *
  * The legacy `'about'`, `'activate'`, and `'usage'` surfaces were
  * dropped earlier — About is served by tool descriptions + docs
@@ -216,7 +216,9 @@ interface PaywallToolResult {
  * `PlanActivationDispatcher`, and Usage folds inline into the account
  * view.
  */
-type SolvaPayMcpViewKind = 'checkout' | 'account' | 'topup' | 'auto-recharge';
+type SolvaPayMcpAdvertisedViewKind = 'checkout' | 'account' | 'topup';
+type SolvaPayMcpViewKind = SolvaPayMcpAdvertisedViewKind | 'auto-recharge';
+declare const SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS: readonly ["checkout", "account", "topup"];
 declare const SOLVAPAY_MCP_VIEW_KINDS: readonly ["checkout", "account", "topup", "auto-recharge"];
 /**
  * Payload returned by every `open_*` bootstrap tool and consumed by the
@@ -249,6 +251,12 @@ interface BootstrapPayload {
     checkoutUrl?: string | null;
     /** Customer portal URL for the current customer, when one could be minted. */
     portalUrl?: string | null;
+    /**
+     * Hosted portal URL that opens the auto-recharge form (`tab=credits&intent=autorecharge`).
+     * Null when no portal session could be minted. Suffixed in `@solvapay/mcp-core`
+     * from the same `customerUrl` as `portalUrl`.
+     */
+    autoRechargeUrl?: string | null;
 }
 /**
  * Content Security Policy allow-list inputs merged with the Stripe
@@ -844,6 +852,7 @@ declare const BootstrapPayloadSchema: z.ZodObject<{
     customer: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     checkoutUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     portalUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    autoRechargeUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$loose>;
 
 /**
@@ -1410,6 +1419,31 @@ declare const SOLVAPAY_OVERVIEW_URI = "docs://solvapay/overview.md";
 declare const SOLVAPAY_OVERVIEW_MIME_TYPE = "text/markdown";
 declare const SOLVAPAY_OVERVIEW_MARKDOWN = "# SolvaPay MCP server \u2014 overview\n\nThis MCP server connects a SolvaPay-protected product to your host so users can\nmanage their plan, usage, and billing **without leaving the chat**. It is\ndual-audience: every tool returns a UI bootstrap for hosts that render MCP UI\nresources (`basic-host`, Claude Desktop, ChatGPT, etc.) and a markdown summary\nwith clickable URLs for text-only hosts.\n\n## What the user can do\n\n- **Account** \u2014 one read-only viewer for every billing surface. Pass `view`:\n  `checkout` (upgrade / change plan / buy / subscribe), `account` (current\n  plan, cancel, billing), or `topup` (add credits). Omit `view` and the\n  server picks (no plan \u2192 checkout, out of credits \u2192 topup, else account).\n  Slash commands `/upgrade`, `/manage_account`, and `/topup` remap onto\n  this tool. `account`.\n- **Activate plan** \u2014 activate a specific plan by `planRef`. Free plans\n  activate immediately, usage-based plans activate when balance covers the\n  configured usage, paid plans return checkout. Requires `planRef` \u2014 to list\n  plans, call `account` with `view: \"checkout\"`. `/activate_plan`.\n\n## How it fits together\n\nThe viewer returns a full `BootstrapPayload` (merchant + product + plans\n+ customer snapshot) so the embedded UI never fires per-view read calls. When\na paywalled data tool hits the usage limit, its response is plain text: the\n`content[0].text` narration names the recovery tool (`account`, or\n`activate_plan` when a specific planRef is known) and inlines\n`gate.checkoutUrl` for terminal-first hosts. The structured gate rides on\n`structuredContent` for programmatic consumers. No widget iframe opens for a\ngate \u2014 the LLM reads the narration and, if the user agrees, calls the named\ntool which mounts the checkout / topup / account surface.\n\nAuth is handled by the SolvaPay OAuth bridge (see `createMcpOAuthBridge`). The\nbridge injects `customer_ref` onto every authenticated request; tools that\nneed an authenticated caller return `Unauthorized` when it is missing.\n\n## Also see\n\n- `docs://solvapay/overview.md` (this resource) \u2014 agent-facing narration.\n- `ui://<app>/mcp-app.html` \u2014 the embedded UI shell.\n- `tools/list` + `prompts/list` \u2014 programmatic discovery of the intent tools\n  and their slash-command shortcuts.\n";
 
+/**
+ * Hosted-portal deep links minted from a customer session URL.
+ *
+ * Phase 1 suffixes the already-minted `customerUrl` in the SDK so the
+ * MCP widget can land on the auto-recharge form without a new network
+ * call or a platform deploy. The query params are the same ones the
+ * customer-app manage page already parses (`tab=credits&intent=autorecharge`).
+ *
+ * Keep this constant in lockstep with
+ * `apps/customer-app/src/pages/customer/manage/index.tsx`. A rename
+ * there without a matching change here degrades to the Credits tab
+ * without the form open — not a dead link, but not the intended
+ * destination either.
+ */
+declare const PORTAL_AUTO_RECHARGE_QUERY = "tab=credits&intent=autorecharge";
+/**
+ * Suffix a minted customer-portal URL so it opens the auto-recharge
+ * form (or the Credits summary when auto-recharge is already on).
+ *
+ * Returns `null` for a missing or non-http URL — the same guard
+ * `narrate.ts` uses. No silent default: a missing portal URL yields
+ * `null` and the widget renders status without an action.
+ */
+declare function autoRechargeUrlFrom(customerUrl: string | null | undefined): string | null;
+
 /**
  * `buildPayableHandler(solvaPay, ctx, handler)` — framework-neutral
  * wrapper that produces an MCP tool handler enforcing the SolvaPay
@@ -1607,4 +1641,4 @@ interface BuildAuthInfoFromBearerOptions extends McpBearerCustomerRefOptions {
 }
 declare function buildAuthInfoFromBearer(authorization?: string | null, options?: BuildAuthInfoFromBearerOptions): McpToolExtra['authInfo'] | null;
 
-export { type ActivePlanPurchaseLike, type ApplyHideToolsByAudienceContext, type ApplyHideToolsByAudienceExtra, type ApplyHideToolsByAudienceOptions, type BootstrapCustomer, type BootstrapMerchant, type BootstrapPayload, BootstrapPayloadSchema, type BootstrapPlan, type BootstrapProduct, type BuildAuthInfoFromBearerOptions, type BuildBootstrapPayloadFn, type BuildPayableHandlerContext, type BuildSolvaPayDescriptorsOptions, type BuildSolvaPayRequestOptions, type ContentBlock, type CreateBuildBootstrapPayloadOptions, type CustomerSnapshot, DEFAULT_OAUTH_PATHS, type DcrFailureDiagnosticInput, type HideToolsByAudienceBypass, INTENT_TOOL_NAMES, type IntentToolName, MCP_PROMPT_NAMES, MCP_TOOL_NAMES, type McpAdapterOptions, McpBearerAuthError, type McpBearerCustomerRefOptions, type McpConfigLogInput, type McpPromptName, type McpToolExtra, type McpToolName, NARRATORS, type NarratorOutput, type NudgeSpec, type OAuthAuthorizationServerOptions, type OAuthBridgePaths, OPEN_TOOL_FOR_VIEW, type PayableHandler, type PaywallToolResult, type PaywallToolResultContext, type ResponseContext, type ResponseOptions, type ResponseResult, SOLVAPAY_BOOTSTRAP_MIME_TYPE, SOLVAPAY_BOOTSTRAP_URI, SOLVAPAY_DEFAULT_CSP, SOLVAPAY_MCP_VIEW_KINDS, SOLVAPAY_OVERVIEW_MARKDOWN, SOLVAPAY_OVERVIEW_MIME_TYPE, SOLVAPAY_OVERVIEW_URI, type SolvaPayBootstrapResourceDescriptor, type SolvaPayCallToolResult, type SolvaPayDescriptorBundle, type SolvaPayDocsResourceDescriptor, type SolvaPayMcpCsp, type SolvaPayMcpViewKind, type SolvaPayMerchantBranding, type SolvaPayPromptDescriptor, type SolvaPayPromptResult, type SolvaPayResourceDescriptor, type SolvaPayToolAnnotations, type SolvaPayToolDescriptor, type SolvaPayToolIcon, type SolvaPayToolMode, TOOL_FOR_VIEW, ToolErrorEnvelopeSchema, VIEWER_TOOL_NAME, VIEW_FOR_OPEN_TOOL, VIEW_FOR_TOOL, applyHideToolsByAudience, balanceSummary, buildAuthInfoFromBearer, buildPayableHandler, buildSolvaPayDescriptors, buildSolvaPayPrompts, buildSolvaPayRequest, createBuildBootstrapPayload, decodeJwtPayload, defaultGetCustomerRef, defaultIsChatGptRequest, deriveDefaultView, deriveIcons, enrichPurchase, extractBearerToken, getCustomerRefFromBearerAuthHeader, getCustomerRefFromJwtPayload, getOAuthAuthorizationServerResponse, getOAuthProtectedResourceResponse, isPlanPurchase, logDcrFailureDiagnostic, logMcpConfigOnce, mergeCsp, narrateActivatePlan, narrateAlreadyActive, narrateAutoRecharge, narrateManageAccount, narrateTopup, narrateUpgrade, narratedToolResult, parseMode, paywallToolResult, previewJson, resetMcpConfigLogForTests, resolveOAuthPaths, selectActivePlanPurchase, toolErrorResult, toolResult, uiPlaceholder, withoutTrailingSlash };
+export { type ActivePlanPurchaseLike, type ApplyHideToolsByAudienceContext, type ApplyHideToolsByAudienceExtra, type ApplyHideToolsByAudienceOptions, type BootstrapCustomer, type BootstrapMerchant, type BootstrapPayload, BootstrapPayloadSchema, type BootstrapPlan, type BootstrapProduct, type BuildAuthInfoFromBearerOptions, type BuildBootstrapPayloadFn, type BuildPayableHandlerContext, type BuildSolvaPayDescriptorsOptions, type BuildSolvaPayRequestOptions, type ContentBlock, type CreateBuildBootstrapPayloadOptions, type CustomerSnapshot, DEFAULT_OAUTH_PATHS, type DcrFailureDiagnosticInput, type HideToolsByAudienceBypass, INTENT_TOOL_NAMES, type IntentToolName, MCP_PROMPT_NAMES, MCP_TOOL_NAMES, type McpAdapterOptions, McpBearerAuthError, type McpBearerCustomerRefOptions, type McpConfigLogInput, type McpPromptName, type McpToolExtra, type McpToolName, NARRATORS, type NarratorOutput, type NudgeSpec, type OAuthAuthorizationServerOptions, type OAuthBridgePaths, OPEN_TOOL_FOR_VIEW, PORTAL_AUTO_RECHARGE_QUERY, type PayableHandler, type PaywallToolResult, type PaywallToolResultContext, type ResponseContext, type ResponseOptions, type ResponseResult, SOLVAPAY_BOOTSTRAP_MIME_TYPE, SOLVAPAY_BOOTSTRAP_URI, SOLVAPAY_DEFAULT_CSP, SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS, SOLVAPAY_MCP_VIEW_KINDS, SOLVAPAY_OVERVIEW_MARKDOWN, SOLVAPAY_OVERVIEW_MIME_TYPE, SOLVAPAY_OVERVIEW_URI, type SolvaPayBootstrapResourceDescriptor, type SolvaPayCallToolResult, type SolvaPayDescriptorBundle, type SolvaPayDocsResourceDescriptor, type SolvaPayMcpAdvertisedViewKind, type SolvaPayMcpCsp, type SolvaPayMcpViewKind, type SolvaPayMerchantBranding, type SolvaPayPromptDescriptor, type SolvaPayPromptResult, type SolvaPayResourceDescriptor, type SolvaPayToolAnnotations, type SolvaPayToolDescriptor, type SolvaPayToolIcon, type SolvaPayToolMode, TOOL_FOR_VIEW, ToolErrorEnvelopeSchema, VIEWER_TOOL_NAME, VIEW_FOR_OPEN_TOOL, VIEW_FOR_TOOL, applyHideToolsByAudience, autoRechargeUrlFrom, balanceSummary, buildAuthInfoFromBearer, buildPayableHandler, buildSolvaPayDescriptors, buildSolvaPayPrompts, buildSolvaPayRequest, createBuildBootstrapPayload, decodeJwtPayload, defaultGetCustomerRef, defaultIsChatGptRequest, deriveDefaultView, deriveIcons, enrichPurchase, extractBearerToken, getCustomerRefFromBearerAuthHeader, getCustomerRefFromJwtPayload, getOAuthAuthorizationServerResponse, getOAuthProtectedResourceResponse, isPlanPurchase, logDcrFailureDiagnostic, logMcpConfigOnce, mergeCsp, narrateActivatePlan, narrateAlreadyActive, narrateAutoRecharge, narrateManageAccount, narrateTopup, narrateUpgrade, narratedToolResult, parseMode, paywallToolResult, previewJson, resetMcpConfigLogForTests, resolveOAuthPaths, selectActivePlanPurchase, toolErrorResult, toolResult, uiPlaceholder, withoutTrailingSlash };

package/dist/index.js

@@ -19,10 +19,13 @@ var MCP_PROMPT_NAMES = {
 };
 
 // src/types.ts
-var SOLVAPAY_MCP_VIEW_KINDS = [
+var SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS = [
   "checkout",
   "account",
-  "topup",
+  "topup"
+];
+var SOLVAPAY_MCP_VIEW_KINDS = [
+  ...SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS,
   "auto-recharge"
 ];
 var TOOL_FOR_VIEW = {
@@ -668,6 +671,9 @@ function narrateTopup(data) {
   lines.push(recoveryLine(["account"]));
   return withCheckout(data, lines);
 }
+function autoRechargePortalUrl(data) {
+  return httpsUrl(data.autoRechargeUrl) ?? httpsUrl(data.portalUrl);
+}
 function narrateAutoRecharge(data) {
   const lines = [];
   lines.push(`**Auto-recharge \u2014 ${productName(data)}**`);
@@ -676,16 +682,27 @@ function narrateAutoRecharge(data) {
   const bal = balanceRow(customer);
   if (bal) lines.push(bal);
   const enabled = customer?.autoRecharge?.enabled === true;
-  lines.push(
-    enabled ? "Auto-recharge is on. It tops your balance up automatically so calls do not fail." : "Auto-recharge is off. Turn it on from the account page \u2014 it stores a card and tops your balance up automatically so calls do not fail."
-  );
-  const manage = manageRow(data);
-  if (manage) lines.push(manage);
+  const failed = customer?.autoRecharge?.status === "failed";
+  if (failed) {
+    lines.push("Auto-recharge failed \u2014 update your card to resume");
+  } else {
+    lines.push(
+      enabled ? "Auto-recharge is on. It tops your balance up automatically so calls do not fail." : "Auto-recharge is off. Turn it on from the link below \u2014 it stores a card and tops your balance up automatically so calls do not fail."
+    );
+  }
+  const manageUrl = autoRechargePortalUrl(data);
+  if (manageUrl) {
+    lines.push(`Manage: ${namedManageMarkdown(manageUrl)} (${CHECKOUT_TTL})`);
+  }
   lines.push("");
   lines.push(recoveryLine(["account"]));
   const links = [];
-  const portal = hostedPortalLink(data);
-  if (portal) links.push({ ...portal, name: enabled ? "Manage auto-recharge" : "Turn on auto-recharge" });
+  if (manageUrl) {
+    links.push({
+      uri: manageUrl,
+      name: enabled ? "Manage auto-recharge" : "Turn on auto-recharge"
+    });
+  }
   return { text: lines.join("\n"), links };
 }
 var NARRATORS = {
@@ -919,7 +936,8 @@ var BootstrapPayloadSchema = z2.object({
   plans: z2.array(z2.record(z2.string(), z2.unknown())),
   customer: z2.record(z2.string(), z2.unknown()).nullable(),
   checkoutUrl: z2.string().nullable().optional(),
-  portalUrl: z2.string().nullable().optional()
+  portalUrl: z2.string().nullable().optional(),
+  autoRechargeUrl: z2.string().nullable().optional()
 }).passthrough();
 
 // src/derive-view.ts
@@ -931,7 +949,7 @@ function isOutOfCredits(customer) {
   const credits = customer?.balance?.credits;
   return credits === 0;
 }
-function deriveDefaultView(data, enabledViews = new Set(SOLVAPAY_MCP_VIEW_KINDS)) {
+function deriveDefaultView(data, enabledViews = new Set(SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS)) {
   const customer = data.customer;
   const preferred = !hasActivePlan(customer, data.productRef) ? "checkout" : isOutOfCredits(customer) ? "topup" : "account";
   if (enabledViews.has(preferred)) return preferred;
@@ -1128,6 +1146,18 @@ import {
   listPlansCore,
   nextActionFor
 } from "@solvapay/server";
+
+// src/portal-links.ts
+var PORTAL_AUTO_RECHARGE_QUERY = "tab=credits&intent=autorecharge";
+function autoRechargeUrlFrom(customerUrl) {
+  if (typeof customerUrl !== "string" || !/^https?:\/\//i.test(customerUrl)) {
+    return null;
+  }
+  const separator = customerUrl.includes("?") ? "&" : "?";
+  return `${customerUrl}${separator}${PORTAL_AUTO_RECHARGE_QUERY}`;
+}
+
+// src/bootstrap-payload.ts
 var okOrNull = (result) => isErrorResult(result) ? null : result;
 var buildProviderNotFoundMessage = () => [
   "Provider account not found on this SolvaPay deployment.",
@@ -1167,7 +1197,10 @@ function createBuildBootstrapPayload(options) {
     try {
       const platform = await solvaPay.apiClient.getPlatformConfig?.();
       return platform?.stripePublishableKey ?? null;
-    } catch {
+    } catch (err) {
+      console.warn("[solvapay] bootstrap: getPlatformConfig failed; stripePublishableKey omitted", {
+        error: err instanceof Error ? err.message : String(err)
+      });
       return null;
     }
   };
@@ -1233,6 +1266,12 @@ function createBuildBootstrapPayload(options) {
     if (isErrorResult(productResult)) {
       throw createBootstrapProductError(productResult);
     }
+    if (isErrorResult(plansResult)) {
+      console.warn("[solvapay] bootstrap: listPlans failed; plans omitted from payload", {
+        error: plansResult.error,
+        status: plansResult.status
+      });
+    }
     const plans = isErrorResult(plansResult) ? [] : plansResult.plans;
     const purchase = okOrNull(resolvedPurchaseResult);
     const enrichedPurchase = purchase ? {
@@ -1280,7 +1319,8 @@ function createBuildBootstrapPayload(options) {
       plans,
       customer,
       checkoutUrl: checkout?.checkoutUrl ?? null,
-      portalUrl: portal?.customerUrl ?? null
+      portalUrl: portal?.customerUrl ?? null,
+      autoRechargeUrl: autoRechargeUrlFrom(portal?.customerUrl)
     };
   };
 }
@@ -1358,7 +1398,13 @@ var VIEWER_DESCRIPTION = 'Call when the user says "upgrade", "change plan", "buy
 var INTENT_MODE_SCHEMA = z3.enum(["ui", "text", "auto"]).optional().describe(
   "Default `mode: 'auto'` returns a self-sufficient text summary (plan, price, https checkout URL) and still opens the iframe on UI hosts. Pass `mode: 'text'` to strip the iframe, or `mode: 'ui'` for a one-line placeholder that still includes the checkout URL."
 );
-var DEFAULT_VIEWS = [...SOLVAPAY_MCP_VIEW_KINDS];
+var DEFAULT_VIEWS = [...SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS];
+function readAutoRechargeArg(value) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  return value;
+}
 function buildSolvaPayDescriptors(options) {
   const {
     solvaPay,
@@ -1452,9 +1498,17 @@ function buildSolvaPayDescriptors(options) {
     publicBaseUrl,
     getCustomerRef
   });
-  const enabledViewList = SOLVAPAY_MCP_VIEW_KINDS.filter((view) => enabledViews.has(view));
-  if (enabledViewList.length > 0) {
-    const viewEnum = z3.enum(enabledViewList).optional().describe(VIEW_PARAM_DESCRIPTION);
+  const advertisedViewList = SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS.filter(
+    (view) => enabledViews.has(view)
+  );
+  if (advertisedViewList.length > 0) {
+    const advertisedEnum = z3.enum(
+      advertisedViewList
+    );
+    const viewEnum = z3.preprocess(
+      (value) => value === "auto-recharge" ? "account" : value,
+      advertisedEnum
+    ).optional().describe(VIEW_PARAM_DESCRIPTION);
     pushTool({
       name: VIEWER_TOOL_NAME,
       title: "Account",
@@ -1465,11 +1519,11 @@ function buildSolvaPayDescriptors(options) {
       annotations: VIEWER_ANNOTATIONS,
       handler: async (args, extra) => trace(VIEWER_TOOL_NAME, args, extra, async () => {
         const requested = args.view === "checkout" || args.view === "account" || args.view === "topup" || args.view === "auto-recharge" ? args.view : void 0;
-        if (requested !== void 0 && !enabledViews.has(requested)) {
+        if (requested !== void 0 && requested !== "auto-recharge" && !enabledViews.has(requested)) {
           return toolErrorResult({
             error: `view '${requested}' is not enabled on this server`,
             status: 400,
-            details: `Enabled views: ${enabledViewList.join(", ")}. Pass one of those, or omit view to let the server pick.`
+            details: `Enabled views: ${advertisedViewList.join(", ")}. Pass one of those, or omit view to let the server pick.`
           });
         }
         const mode = parseMode(args.mode);
@@ -1524,14 +1578,22 @@ function buildSolvaPayDescriptors(options) {
   });
   pushTool({
     name: MCP_TOOL_NAMES.createPayment,
-    description: UI_ONLY_PREFIX + 'Create a Stripe payment intent for the authenticated customer. Pass purpose: "plan" to purchase a plan (returns { clientSecret, publishableKey, accountId?, customerRef }) or purpose: "topup" for a credit top-up (credits are recorded by webhook after confirmation).',
+    description: UI_ONLY_PREFIX + 'Create a Stripe payment intent for the authenticated customer. Pass purpose: "plan" to purchase a plan (returns { clientSecret, publishableKey, accountId?, customerRef }) or purpose: "topup" for a credit top-up (credits are recorded by webhook after confirmation). A topup may carry autoRecharge so the card entered for the top-up is saved as the auto-recharge funding source.',
     inputSchema: {
       purpose: z3.enum(["plan", "topup"]).describe('"plan" for plan checkout; "topup" for credit top-up.'),
       planRef: z3.string().optional(),
       productRef: z3.string().optional(),
       currency: z3.string().optional(),
       amount: z3.number().int().positive().optional(),
-      description: z3.string().optional()
+      description: z3.string().optional(),
+      autoRecharge: z3.object({
+        enabled: z3.boolean(),
+        triggerType: z3.literal("balance"),
+        thresholdAmountMajor: z3.number().positive().optional(),
+        topupAmountMajor: z3.number().positive().optional(),
+        maxMonthlySpendMajor: z3.number().positive().optional(),
+        currency: z3.string().length(3)
+      }).optional()
     },
     meta: uiToolMeta,
     annotations: solvapayTool({ readOnlyHint: false, destructiveHint: false }),
@@ -1546,6 +1608,14 @@ function buildSolvaPayDescriptors(options) {
           details: 'Pass purpose: "plan" or purpose: "topup".'
         });
       }
+      const autoRecharge = readAutoRechargeArg(args.autoRecharge);
+      if (purpose === "plan" && autoRecharge) {
+        return toolErrorResult({
+          error: "create_payment_intent plan does not accept autoRecharge",
+          status: 400,
+          details: 'autoRecharge is only honoured on purpose: "topup".'
+        });
+      }
       if (purpose === "topup") {
         const amount = typeof args.amount === "number" ? args.amount : 0;
         const currency2 = typeof args.currency === "string" ? args.currency : "";
@@ -1559,7 +1629,7 @@ function buildSolvaPayDescriptors(options) {
         }
         const result2 = await createTopupPaymentIntentCore(
           buildRequest(extra, { method: "POST" }),
-          { amount, currency: currency2, description },
+          { amount, currency: currency2, description, ...autoRecharge ? { autoRecharge } : {} },
           { solvaPay }
         );
         if (isErrorResult2(result2)) return toolErrorResult(result2);
@@ -2207,9 +2277,11 @@ export {
   McpBearerAuthError,
   NARRATORS,
   OPEN_TOOL_FOR_VIEW,
+  PORTAL_AUTO_RECHARGE_QUERY,
   SOLVAPAY_BOOTSTRAP_MIME_TYPE,
   SOLVAPAY_BOOTSTRAP_URI,
   SOLVAPAY_DEFAULT_CSP,
+  SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS,
   SOLVAPAY_MCP_VIEW_KINDS,
   SOLVAPAY_OVERVIEW_MARKDOWN,
   SOLVAPAY_OVERVIEW_MIME_TYPE,
@@ -2222,6 +2294,7 @@ export {
   VIEW_FOR_TOOL,
   applyHideToolsByAudience,
   assertValidProductRef2 as assertValidProductRef,
+  autoRechargeUrlFrom,
   balanceSummary,
   buildAuthInfoFromBearer,
   buildPayableHandler,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solvapay/mcp-core",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Framework-neutral MCP contracts for the SolvaPay SDK (tool names, descriptors, payable handler, paywall meta, CSP, bootstrap payload, OAuth discovery JSON builders, bearer/JWT helpers).",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -41,7 +41,7 @@
     "typescript": "^5.9.3",
     "vitest": "^4.1.2",
     "zod": "^4.3.6",
-    "@solvapay/server": "2.6.0",
+    "@solvapay/server": "2.7.0",
     "@solvapay/test-utils": "^0.0.0"
   },
   "scripts": {