@solvapay/mcp-core 0.4.6 → 0.4.7

package/dist/index.cjs

@@ -238,6 +238,9 @@ function limitsAsSignals(limits) {
   if (!limits) return null;
   return limits;
 }
+function creditsUnused(customer) {
+  return !(0, import_server.creditSignals)(limitsAsSignals(customer?.limits)).isCreditBased;
+}
 function preferLimitsPlan(purchase, limits) {
   const limitsRef = limits?.planRef;
   if (!limitsRef) return false;
@@ -252,6 +255,12 @@ function balanceSummary(customer) {
   if (!row) return null;
   return row.replace(/^Balance:\s*/, "");
 }
+function identityRow(customer) {
+  const ref = customer?.ref?.trim();
+  if (!ref) return null;
+  const email = customer?.email?.trim();
+  return email ? `Signed in as: ${email} \xB7 ${ref}` : `Signed in as: ${ref}`;
+}
 function balanceRow(customer) {
   if (!customer?.balance) return null;
   const credits = customer.balance.credits ?? 0;
@@ -593,8 +602,7 @@ function narrateAccountBody(input) {
     } else {
       position = "After your first call";
     }
-    const creditsUnused = !(0, import_server.creditSignals)(limitsAsSignals(customer?.limits)).isCreditBased;
-    return `${product} is on ${planName}${priceBit}. ${position}. ` + (creditsUnused ? `Credits are not used on this plan. Call \`${VIEWER_TOOL_NAME}\` with view: 'checkout' to switch.` : `Call \`${VIEWER_TOOL_NAME}\` with view: 'checkout' to switch.`);
+    return `${product} is on ${planName}${priceBit}. ${position}. ` + (creditsUnused(customer) ? `Credits are not used on this plan. Call \`${VIEWER_TOOL_NAME}\` with view: 'checkout' to switch.` : `Call \`${VIEWER_TOOL_NAME}\` with view: 'checkout' to switch.`);
   }
   if (state === "E") {
     const left2 = remainingOfTotal(usage);
@@ -617,7 +625,7 @@ function narrateAccountBody(input) {
       return otherShape !== "free" && otherShape !== "trial";
     });
     const carryOn = others.length > 0 ? ` ${joinOr(others.map((item) => carryOnFragment(item, customer)))}.` : "";
-    const antiTrap = credits > 0 && planShape !== "usage-based" ? ` Adding credits will not help, because ${planName} does not spend them.` : "";
+    const antiTrap = creditsUnused(customer) ? ` Adding credits will not help, because ${planName} does not spend them.` : "";
     const priceBit = planPriceBit(plan);
     return `${product} is on ${planName}${priceBit}. ${capBit}.${consequence}.${antiTrap}${carryOn} Call \`${VIEWER_TOOL_NAME}\` with view: 'checkout' to switch plan.`;
   }
@@ -704,6 +712,8 @@ function narrateManageAccount(data, options) {
       now
     })
   );
+  const identity = identityRow(customer);
+  if (identity) lines.push(identity);
   if (state === "A" || state === "H") {
     const bal = balanceRow(customer);
     if (bal) lines.push(bal);
@@ -904,6 +914,15 @@ function enrichPurchase(purchase) {
     ...enrichedPlanSnapshot !== void 0 ? { planSnapshot: enrichedPlanSnapshot } : {}
   };
 }
+function signedInCustomerRefOnly(getCustomerRef) {
+  return (extra) => {
+    const ref = getCustomerRef(extra);
+    if (typeof ref !== "string") return null;
+    const trimmed = ref.trim();
+    if (!trimmed || trimmed === "anonymous") return null;
+    return trimmed;
+  };
+}
 function defaultGetCustomerRef(extra) {
   const candidates = [
     extra?.http?.authInfo?.extra?.customer_ref,
@@ -1029,13 +1048,9 @@ var VIEW_PRIORITY = ["checkout", "topup", "account"];
 function hasActivePlan(customer, productRef) {
   return selectActivePlanPurchase(customer?.purchase?.purchases, productRef) !== null;
 }
-function isOutOfCredits(customer) {
-  const credits = customer?.balance?.credits;
-  return credits === 0;
-}
 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";
+  const preferred = !hasActivePlan(customer, data.productRef) ? "checkout" : customer?.nextAction === "topup" ? "topup" : "account";
   if (enabledViews.has(preferred)) return preferred;
   for (const view of VIEW_PRIORITY) {
     if (enabledViews.has(view)) return view;
@@ -1251,12 +1266,10 @@ var createBootstrapProductError = (productResult) => {
   return err;
 };
 function createBuildBootstrapPayload(options) {
-  const {
-    solvaPay,
-    productRef,
-    publicBaseUrl,
-    getCustomerRef = defaultGetCustomerRef
-  } = options;
+  const { solvaPay, productRef, publicBaseUrl } = options;
+  const getCustomerRef = signedInCustomerRefOnly(
+    options.getCustomerRef ?? defaultGetCustomerRef
+  );
   const fetchPublishableKey = async () => {
     try {
       const platform = await solvaPay.apiClient.getPlatformConfig?.();
@@ -1311,18 +1324,16 @@ function createBuildBootstrapPayload(options) {
       }
     }
     const checkoutPurpose = view === "topup" || view !== "checkout" && view !== "auto-recharge" && limits?.paywallReason === "topup_required" ? "credit_topup" : void 0;
-    const checkoutResult = await wrapError(
+    const checkoutResult = customerRef ? await wrapError(
       createMcpCheckoutSession(
-        buildSolvaPayRequest(extra, {
-          getCustomerRef: () => customerRef ?? "anonymous"
-        }),
+        buildRequest(extra),
         {
           productRef,
           ...checkoutPurpose ? { purpose: checkoutPurpose } : {}
         },
         { solvaPay }
       )
-    );
+    ) : await unauthenticated();
     if ((0, import_server4.isErrorResult)(merchantResult)) {
       throw createBootstrapMerchantError(merchantResult);
     }
@@ -1345,19 +1356,16 @@ function createBuildBootstrapPayload(options) {
     } : null;
     const activePurchase2 = selectActivePlanPurchase(enrichedPurchase?.purchases, productRef);
     const usage = customerRef ? (0, import_server4.deriveUsageSnapshot)({
-      // Consumption comes from `limits.used` (or `limit - remaining`)
-      // inside `deriveUsageSnapshot`. `purchase.usage.used` is only
-      // ever reset to zero by the backend and must not be the source.
-      used: 0,
       periodStart: activePurchase2?.usage?.periodStart,
       periodEnd: activePurchase2?.usage?.periodEnd,
       purchaseRef: activePurchase2?.reference,
       limits
     }) : null;
     const signals = limits ? (0, import_server4.creditSignals)(limits) : null;
-    const state = limits ? (0, import_server4.classifyPaywallState)(limits) : null;
     const customer = customerRef ? {
       ref: customerRef,
+      email: purchase?.email?.trim() ? purchase.email.trim() : null,
+      name: purchase?.name?.trim() ? purchase.name.trim() : null,
       purchase: enrichedPurchase,
       paymentMethod: okOrNull(paymentMethodResult),
       balance: okOrNull(balanceResult),
@@ -1367,8 +1375,9 @@ function createBuildBootstrapPayload(options) {
       ...signals?.remainingCalls !== void 0 ? { remainingCalls: signals.remainingCalls } : {},
       ...signals?.creditsPerCall !== void 0 ? { creditsPerCall: signals.creditsPerCall } : {},
       ...signals?.shortfallCredits !== void 0 ? { shortfallCredits: signals.shortfallCredits } : {},
+      ...signals ? { isCreditBased: signals.isCreditBased } : {},
       ...limits?.autoRecharge !== void 0 ? { autoRecharge: limits.autoRecharge } : {},
-      ...state ? { nextAction: (0, import_server4.nextActionFor)(state) } : {}
+      ...limits?.withinLimits === false ? { nextAction: (0, import_server4.nextActionFor)((0, import_server4.classifyPaywallState)(limits)) } : {}
     } : null;
     const checkout = okOrNull(checkoutResult);
     const portal = okOrNull(portalResult);
@@ -1479,11 +1488,13 @@ function buildSolvaPayDescriptors(options) {
     views = DEFAULT_VIEWS,
     csp,
     apiBaseUrl,
-    getCustomerRef = defaultGetCustomerRef,
     onToolCall,
     onToolResult,
     branding
   } = options;
+  const getCustomerRef = signedInCustomerRefOnly(
+    options.getCustomerRef ?? defaultGetCustomerRef
+  );
   const toolIcons = deriveIcons(branding);
   if (!/^https?:\/\//i.test(publicBaseUrl)) {
     throw new Error(
@@ -1561,6 +1572,11 @@ function buildSolvaPayDescriptors(options) {
     publicBaseUrl,
     getCustomerRef
   });
+  const buildDefaultBootstrapPayload = async (extra) => {
+    const data = await buildBootstrapPayload("account", extra);
+    data.view = deriveDefaultView(data, enabledViews);
+    return data;
+  };
   const advertisedViewList = SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS.filter(
     (view) => enabledViews.has(view)
   );
@@ -1590,10 +1606,9 @@ function buildSolvaPayDescriptors(options) {
           });
         }
         const mode = parseMode(args.mode);
-        const data = await buildBootstrapPayload(requested ?? "account", extra);
-        const view = requested ?? deriveDefaultView(data, enabledViews);
-        data.view = view;
-        return narratedToolResult(view, data, mode, {
+        const data = requested === void 0 ? await buildDefaultBootstrapPayload(extra) : await buildBootstrapPayload(requested, extra);
+        if (requested !== void 0) data.view = requested;
+        return narratedToolResult(data.view, data, mode, {
           ...toolMeta,
           "openai/widgetSessionId": crypto.randomUUID()
         });
@@ -1950,10 +1965,11 @@ function buildSolvaPayDescriptors(options) {
     title: "SolvaPay bootstrap",
     description: "Current merchant/product/plans/customer snapshot for the embedded UI. Widgets read this idempotently when the host scrubs structuredContent from tool results.",
     mimeType: SOLVAPAY_BOOTSTRAP_MIME_TYPE,
-    // View is an echoed routing label — the widget resolves the actual
-    // surface from host context (`inferViewFromHost`), so any view kind
-    // produces identical merchant/product/plans/customer data.
-    readPayload: (extra) => buildBootstrapPayload("account", extra)
+    // View is the server's default for this customer (checkout with no
+    // active plan, topup on a top-up gate, account otherwise) — the same
+    // choice the viewer makes when `view` is omitted. The widget trusts
+    // this field; it does not resolve the surface from host context.
+    readPayload: (extra) => buildDefaultBootstrapPayload(extra)
   };
   return { tools, resource, prompts, docsResources, bootstrapResource, buildBootstrapPayload };
 }

package/dist/index.d.cts

@@ -82,6 +82,14 @@ type BootstrapPlan = components['schemas']['Plan'];
  */
 interface BootstrapCustomer {
     ref: string;
+    /**
+     * Signed-in identity from the customer record. Projected off the
+     * purchase-check result, which carries them only because that helper
+     * looks the customer up. Null when that sub-read returned none.
+     * The whole `customer` is null for an anonymous caller.
+     */
+    email: string | null;
+    name: string | null;
     purchase: PurchaseCheckResult | null;
     paymentMethod: PaymentMethodInfo | null;
     balance: CustomerBalanceResult | null;
@@ -101,9 +109,14 @@ interface BootstrapCustomer {
     creditsPerCall?: number;
     /** `max(0, creditsPerCall - balance)` when both are known. */
     shortfallCredits?: number;
+    /**
+     * True when the limits response carries credit-balance fields.
+     * False means the plan does not spend credits.
+     */
+    isCreditBased?: boolean;
     /** Per-provider auto-recharge snapshot from the limits response. */
     autoRecharge?: LimitAutoRechargeDto;
-    /** Same next action the gate would name for this limits result. */
+    /** Present only when the latest `checkLimits` blocked the call. */
     nextAction?: PaywallNextAction;
 }
 /**
@@ -725,16 +738,6 @@ declare const ToolErrorEnvelopeSchema: z.ZodObject<{
  * programmatic consumers (e.g. the React transport).
  */
 declare function enrichPurchase(purchase: Record<string, unknown>): Record<string, unknown>;
-/**
- * Default extractor for `customer_ref` out of the MCP OAuth bridge
- * (what `auth-bridge.ts` populates), trimmed. Returns `null` when no
- * ref is present.
- *
- * Checks `extra.http.authInfo` first — the official SDK v2 location —
- * then falls back to the flat v1 `extra.authInfo` still emitted by some
- * third-party adapters. Reading only the flat location silently
- * de-authenticated every tool call under SDK v2.
- */
 declare function defaultGetCustomerRef(extra?: McpToolExtra): string | null;
 interface BuildSolvaPayRequestOptions {
     method?: string;
@@ -911,7 +914,7 @@ interface PurchaseShape {
     };
 }
 interface UsageShape {
-    used?: number;
+    used?: number | null;
     total?: number | null;
     remaining?: number | null;
     periodEnd?: string;
@@ -934,7 +937,9 @@ interface LimitsShape {
     };
 }
 interface CustomerShape {
-    ref?: string;
+    ref?: string | null;
+    email?: string | null;
+    name?: string | null;
     balance?: {
         credits?: number | null;
         displayCurrency?: string;
@@ -984,7 +989,7 @@ declare function uiPlaceholder(view: SolvaPayMcpViewKind, data: BootstrapPayload
  * The three surfaces share one payload; omitting `view` must still land
  * somewhere useful instead of failing. Rule:
  *   - no active plan → checkout (plans)
- *   - active plan and zero credits → topup
+ *   - active plan and blocked by a top-up gate → topup
  *   - otherwise → account
  *
  * When the preferred view is disabled on this server, fall through the

package/dist/index.d.ts

@@ -82,6 +82,14 @@ type BootstrapPlan = components['schemas']['Plan'];
  */
 interface BootstrapCustomer {
     ref: string;
+    /**
+     * Signed-in identity from the customer record. Projected off the
+     * purchase-check result, which carries them only because that helper
+     * looks the customer up. Null when that sub-read returned none.
+     * The whole `customer` is null for an anonymous caller.
+     */
+    email: string | null;
+    name: string | null;
     purchase: PurchaseCheckResult | null;
     paymentMethod: PaymentMethodInfo | null;
     balance: CustomerBalanceResult | null;
@@ -101,9 +109,14 @@ interface BootstrapCustomer {
     creditsPerCall?: number;
     /** `max(0, creditsPerCall - balance)` when both are known. */
     shortfallCredits?: number;
+    /**
+     * True when the limits response carries credit-balance fields.
+     * False means the plan does not spend credits.
+     */
+    isCreditBased?: boolean;
     /** Per-provider auto-recharge snapshot from the limits response. */
     autoRecharge?: LimitAutoRechargeDto;
-    /** Same next action the gate would name for this limits result. */
+    /** Present only when the latest `checkLimits` blocked the call. */
     nextAction?: PaywallNextAction;
 }
 /**
@@ -725,16 +738,6 @@ declare const ToolErrorEnvelopeSchema: z.ZodObject<{
  * programmatic consumers (e.g. the React transport).
  */
 declare function enrichPurchase(purchase: Record<string, unknown>): Record<string, unknown>;
-/**
- * Default extractor for `customer_ref` out of the MCP OAuth bridge
- * (what `auth-bridge.ts` populates), trimmed. Returns `null` when no
- * ref is present.
- *
- * Checks `extra.http.authInfo` first — the official SDK v2 location —
- * then falls back to the flat v1 `extra.authInfo` still emitted by some
- * third-party adapters. Reading only the flat location silently
- * de-authenticated every tool call under SDK v2.
- */
 declare function defaultGetCustomerRef(extra?: McpToolExtra): string | null;
 interface BuildSolvaPayRequestOptions {
     method?: string;
@@ -911,7 +914,7 @@ interface PurchaseShape {
     };
 }
 interface UsageShape {
-    used?: number;
+    used?: number | null;
     total?: number | null;
     remaining?: number | null;
     periodEnd?: string;
@@ -934,7 +937,9 @@ interface LimitsShape {
     };
 }
 interface CustomerShape {
-    ref?: string;
+    ref?: string | null;
+    email?: string | null;
+    name?: string | null;
     balance?: {
         credits?: number | null;
         displayCurrency?: string;
@@ -984,7 +989,7 @@ declare function uiPlaceholder(view: SolvaPayMcpViewKind, data: BootstrapPayload
  * The three surfaces share one payload; omitting `view` must still land
  * somewhere useful instead of failing. Rule:
  *   - no active plan → checkout (plans)
- *   - active plan and zero credits → topup
+ *   - active plan and blocked by a top-up gate → topup
  *   - otherwise → account
  *
  * When the preferred view is disabled on this server, fall through the

package/dist/index.js

@@ -147,6 +147,9 @@ function limitsAsSignals(limits) {
   if (!limits) return null;
   return limits;
 }
+function creditsUnused(customer) {
+  return !creditSignals(limitsAsSignals(customer?.limits)).isCreditBased;
+}
 function preferLimitsPlan(purchase, limits) {
   const limitsRef = limits?.planRef;
   if (!limitsRef) return false;
@@ -161,6 +164,12 @@ function balanceSummary(customer) {
   if (!row) return null;
   return row.replace(/^Balance:\s*/, "");
 }
+function identityRow(customer) {
+  const ref = customer?.ref?.trim();
+  if (!ref) return null;
+  const email = customer?.email?.trim();
+  return email ? `Signed in as: ${email} \xB7 ${ref}` : `Signed in as: ${ref}`;
+}
 function balanceRow(customer) {
   if (!customer?.balance) return null;
   const credits = customer.balance.credits ?? 0;
@@ -502,8 +511,7 @@ function narrateAccountBody(input) {
     } else {
       position = "After your first call";
     }
-    const creditsUnused = !creditSignals(limitsAsSignals(customer?.limits)).isCreditBased;
-    return `${product} is on ${planName}${priceBit}. ${position}. ` + (creditsUnused ? `Credits are not used on this plan. Call \`${VIEWER_TOOL_NAME}\` with view: 'checkout' to switch.` : `Call \`${VIEWER_TOOL_NAME}\` with view: 'checkout' to switch.`);
+    return `${product} is on ${planName}${priceBit}. ${position}. ` + (creditsUnused(customer) ? `Credits are not used on this plan. Call \`${VIEWER_TOOL_NAME}\` with view: 'checkout' to switch.` : `Call \`${VIEWER_TOOL_NAME}\` with view: 'checkout' to switch.`);
   }
   if (state === "E") {
     const left2 = remainingOfTotal(usage);
@@ -526,7 +534,7 @@ function narrateAccountBody(input) {
       return otherShape !== "free" && otherShape !== "trial";
     });
     const carryOn = others.length > 0 ? ` ${joinOr(others.map((item) => carryOnFragment(item, customer)))}.` : "";
-    const antiTrap = credits > 0 && planShape !== "usage-based" ? ` Adding credits will not help, because ${planName} does not spend them.` : "";
+    const antiTrap = creditsUnused(customer) ? ` Adding credits will not help, because ${planName} does not spend them.` : "";
     const priceBit = planPriceBit(plan);
     return `${product} is on ${planName}${priceBit}. ${capBit}.${consequence}.${antiTrap}${carryOn} Call \`${VIEWER_TOOL_NAME}\` with view: 'checkout' to switch plan.`;
   }
@@ -613,6 +621,8 @@ function narrateManageAccount(data, options) {
       now
     })
   );
+  const identity = identityRow(customer);
+  if (identity) lines.push(identity);
   if (state === "A" || state === "H") {
     const bal = balanceRow(customer);
     if (bal) lines.push(bal);
@@ -813,6 +823,15 @@ function enrichPurchase(purchase) {
     ...enrichedPlanSnapshot !== void 0 ? { planSnapshot: enrichedPlanSnapshot } : {}
   };
 }
+function signedInCustomerRefOnly(getCustomerRef) {
+  return (extra) => {
+    const ref = getCustomerRef(extra);
+    if (typeof ref !== "string") return null;
+    const trimmed = ref.trim();
+    if (!trimmed || trimmed === "anonymous") return null;
+    return trimmed;
+  };
+}
 function defaultGetCustomerRef(extra) {
   const candidates = [
     extra?.http?.authInfo?.extra?.customer_ref,
@@ -945,13 +964,9 @@ var VIEW_PRIORITY = ["checkout", "topup", "account"];
 function hasActivePlan(customer, productRef) {
   return selectActivePlanPurchase(customer?.purchase?.purchases, productRef) !== null;
 }
-function isOutOfCredits(customer) {
-  const credits = customer?.balance?.credits;
-  return credits === 0;
-}
 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";
+  const preferred = !hasActivePlan(customer, data.productRef) ? "checkout" : customer?.nextAction === "topup" ? "topup" : "account";
   if (enabledViews.has(preferred)) return preferred;
   for (const view of VIEW_PRIORITY) {
     if (enabledViews.has(view)) return view;
@@ -1193,12 +1208,10 @@ var createBootstrapProductError = (productResult) => {
   return err;
 };
 function createBuildBootstrapPayload(options) {
-  const {
-    solvaPay,
-    productRef,
-    publicBaseUrl,
-    getCustomerRef = defaultGetCustomerRef
-  } = options;
+  const { solvaPay, productRef, publicBaseUrl } = options;
+  const getCustomerRef = signedInCustomerRefOnly(
+    options.getCustomerRef ?? defaultGetCustomerRef
+  );
   const fetchPublishableKey = async () => {
     try {
       const platform = await solvaPay.apiClient.getPlatformConfig?.();
@@ -1253,18 +1266,16 @@ function createBuildBootstrapPayload(options) {
       }
     }
     const checkoutPurpose = view === "topup" || view !== "checkout" && view !== "auto-recharge" && limits?.paywallReason === "topup_required" ? "credit_topup" : void 0;
-    const checkoutResult = await wrapError(
+    const checkoutResult = customerRef ? await wrapError(
       createMcpCheckoutSession(
-        buildSolvaPayRequest(extra, {
-          getCustomerRef: () => customerRef ?? "anonymous"
-        }),
+        buildRequest(extra),
         {
           productRef,
           ...checkoutPurpose ? { purpose: checkoutPurpose } : {}
         },
         { solvaPay }
       )
-    );
+    ) : await unauthenticated();
     if (isErrorResult(merchantResult)) {
       throw createBootstrapMerchantError(merchantResult);
     }
@@ -1287,19 +1298,16 @@ function createBuildBootstrapPayload(options) {
     } : null;
     const activePurchase2 = selectActivePlanPurchase(enrichedPurchase?.purchases, productRef);
     const usage = customerRef ? deriveUsageSnapshot({
-      // Consumption comes from `limits.used` (or `limit - remaining`)
-      // inside `deriveUsageSnapshot`. `purchase.usage.used` is only
-      // ever reset to zero by the backend and must not be the source.
-      used: 0,
       periodStart: activePurchase2?.usage?.periodStart,
       periodEnd: activePurchase2?.usage?.periodEnd,
       purchaseRef: activePurchase2?.reference,
       limits
     }) : null;
     const signals = limits ? creditSignals2(limits) : null;
-    const state = limits ? classifyPaywallState(limits) : null;
     const customer = customerRef ? {
       ref: customerRef,
+      email: purchase?.email?.trim() ? purchase.email.trim() : null,
+      name: purchase?.name?.trim() ? purchase.name.trim() : null,
       purchase: enrichedPurchase,
       paymentMethod: okOrNull(paymentMethodResult),
       balance: okOrNull(balanceResult),
@@ -1309,8 +1317,9 @@ function createBuildBootstrapPayload(options) {
       ...signals?.remainingCalls !== void 0 ? { remainingCalls: signals.remainingCalls } : {},
       ...signals?.creditsPerCall !== void 0 ? { creditsPerCall: signals.creditsPerCall } : {},
       ...signals?.shortfallCredits !== void 0 ? { shortfallCredits: signals.shortfallCredits } : {},
+      ...signals ? { isCreditBased: signals.isCreditBased } : {},
       ...limits?.autoRecharge !== void 0 ? { autoRecharge: limits.autoRecharge } : {},
-      ...state ? { nextAction: nextActionFor(state) } : {}
+      ...limits?.withinLimits === false ? { nextAction: nextActionFor(classifyPaywallState(limits)) } : {}
     } : null;
     const checkout = okOrNull(checkoutResult);
     const portal = okOrNull(portalResult);
@@ -1421,11 +1430,13 @@ function buildSolvaPayDescriptors(options) {
     views = DEFAULT_VIEWS,
     csp,
     apiBaseUrl,
-    getCustomerRef = defaultGetCustomerRef,
     onToolCall,
     onToolResult,
     branding
   } = options;
+  const getCustomerRef = signedInCustomerRefOnly(
+    options.getCustomerRef ?? defaultGetCustomerRef
+  );
   const toolIcons = deriveIcons(branding);
   if (!/^https?:\/\//i.test(publicBaseUrl)) {
     throw new Error(
@@ -1503,6 +1514,11 @@ function buildSolvaPayDescriptors(options) {
     publicBaseUrl,
     getCustomerRef
   });
+  const buildDefaultBootstrapPayload = async (extra) => {
+    const data = await buildBootstrapPayload("account", extra);
+    data.view = deriveDefaultView(data, enabledViews);
+    return data;
+  };
   const advertisedViewList = SOLVAPAY_MCP_ADVERTISED_VIEW_KINDS.filter(
     (view) => enabledViews.has(view)
   );
@@ -1532,10 +1548,9 @@ function buildSolvaPayDescriptors(options) {
           });
         }
         const mode = parseMode(args.mode);
-        const data = await buildBootstrapPayload(requested ?? "account", extra);
-        const view = requested ?? deriveDefaultView(data, enabledViews);
-        data.view = view;
-        return narratedToolResult(view, data, mode, {
+        const data = requested === void 0 ? await buildDefaultBootstrapPayload(extra) : await buildBootstrapPayload(requested, extra);
+        if (requested !== void 0) data.view = requested;
+        return narratedToolResult(data.view, data, mode, {
           ...toolMeta,
           "openai/widgetSessionId": crypto.randomUUID()
         });
@@ -1892,10 +1907,11 @@ function buildSolvaPayDescriptors(options) {
     title: "SolvaPay bootstrap",
     description: "Current merchant/product/plans/customer snapshot for the embedded UI. Widgets read this idempotently when the host scrubs structuredContent from tool results.",
     mimeType: SOLVAPAY_BOOTSTRAP_MIME_TYPE,
-    // View is an echoed routing label — the widget resolves the actual
-    // surface from host context (`inferViewFromHost`), so any view kind
-    // produces identical merchant/product/plans/customer data.
-    readPayload: (extra) => buildBootstrapPayload("account", extra)
+    // View is the server's default for this customer (checkout with no
+    // active plan, topup on a top-up gate, account otherwise) — the same
+    // choice the viewer makes when `view` is omitted. The widget trusts
+    // this field; it does not resolve the surface from host context.
+    readPayload: (extra) => buildDefaultBootstrapPayload(extra)
   };
   return { tools, resource, prompts, docsResources, bootstrapResource, buildBootstrapPayload };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solvapay/mcp-core",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "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.9.0",
+    "@solvapay/server": "2.10.0",
     "@solvapay/test-utils": "^0.0.0"
   },
   "scripts": {