@solvapay/server 2.5.0 → 2.6.0-preview-09731417a0a7b4fd3afb4783fdf20b5ad293f63d

package/dist/edge.d.ts

@@ -831,6 +831,10 @@ interface components {
             currency: string;
             /** @description How many metered items the credit balance still covers (`balance / creditsPerUnit`) */
             remainingUnits?: number;
+            /** @description Credits per minor unit of `currency` (typically 100) */
+            creditsPerMinorUnit?: number;
+            /** @description USD → display-currency rate used with creditsPerMinorUnit */
+            displayExchangeRate?: number;
         };
         LimitPlanItemDto: {
             /** @description Derived billing cycle */
@@ -4291,6 +4295,10 @@ type PaywallGateRecoveryFields = {
     shortfallCredits?: number;
     /** How many calls the current allowance or wallet still covers. */
     remainingCalls?: number;
+    /** Credits per minor currency unit, from the limits balance peg. */
+    creditsPerMinorUnit?: number;
+    /** USD → display-currency rate used with `creditsPerMinorUnit`. */
+    displayExchangeRate?: number;
     /** Active purchase reference when the customer already holds a purchase. */
     purchaseRef?: string;
     /** Purchase/plan status when the backend sent one. */
@@ -5354,6 +5362,12 @@ interface SolvaPay {
      */
     paywall: {
         decide<TArgs extends PaywallArgs>(args: TArgs, metadata?: PaywallMetadata, getCustomerRef?: (args: TArgs) => string): Promise<PaywallDecision<TArgs>>;
+        /**
+         * Drop cached `checkLimits` snapshots for this customer (optionally
+         * scoped to one product). Call after `activate_plan`, a completed
+         * checkout, or a top-up so the next payable call refetches.
+         */
+        invalidateLimits(customerRef: string, product?: string): void;
     };
     /**
      * Direct access to the API client for advanced operations.
@@ -6144,7 +6158,13 @@ declare function processTopupPaymentIntentCore(request: Request, body: {
 declare function createCheckoutSessionCore(request: Request, body: {
     productRef: string;
     planRef?: string;
-    returnUrl?: string;
+    /**
+     * URL to send the customer back to after payment. Pass `null` to omit
+     * the field entirely — skips `options.returnUrl` and the request-origin
+     * fallback. Use this when the caller has no browsable page to return to
+     * (MCP servers whose public URL is an API endpoint, not a website).
+     */
+    returnUrl?: string | null;
     purpose?: 'credit_topup';
 }, options?: {
     solvaPay?: SolvaPay;

package/dist/edge.js

@@ -683,9 +683,8 @@ async function verifyProductConfiguration(options) {
 }
 
 // src/paywall-state.ts
-import { minorUnitsPerMajor } from "@solvapay/core";
+import { creditsToDisplayMinorUnits, minorUnitsPerMajor } from "@solvapay/core";
 var CHECKOUT_SESSION_TTL_MINUTES = 15;
-var DOCS_HINT = "See docs://solvapay/overview.md.";
 function creditSignals(limits) {
   if (!limits) return { isCreditBased: false };
   const creditBalance = limits.balance?.creditBalance ?? limits.creditBalance;
@@ -769,6 +768,24 @@ function formatMinor(amountMinor, currency) {
 function formatCredits(value) {
   return value.toLocaleString("en-US");
 }
+function formatCreditsWithMoney(credits, gate) {
+  const amount = formatCredits(credits);
+  const peg = gate.creditsPerMinorUnit;
+  const currency = gate.currency;
+  const rate = gate.displayExchangeRate;
+  if (peg && peg > 0 && currency && rate != null && rate > 0) {
+    const minor = creditsToDisplayMinorUnits({
+      credits,
+      creditsPerMinorUnit: peg,
+      displayExchangeRate: rate,
+      displayCurrency: currency
+    });
+    if (minor != null) {
+      return `${amount} credits (~${formatMinor(minor, currency)})`;
+    }
+  }
+  return `${amount} credits`;
+}
 function meterLabel(gate) {
   if (!gate.meterName) return "units";
   return gate.meterName.replace(/_/g, " ");
@@ -812,49 +829,51 @@ function buildGateMessage(state, gate) {
       const nextLine = price ? ` The next call is ${price}.` : "";
       const planName = gate.planName ?? "This plan";
       const antiTrap = gate.creditBalance !== void 0 && gate.creditBalance > 0 && (gate.creditsPerCall === void 0 || gate.creditsPerCall === 0) ? ` Adding credits will not help, because ${planName} does not spend them.` : "";
-      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : recoverClause(url, "continue", "checkout");
-      return `${usedLine}${nextLine}${antiTrap}${switchLine} ${DOCS_HINT}`;
+      const switchLine = ladder ? ` Or switch plan: ${ladder}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.` : recoverClause(url, "continue", "checkout");
+      return `${usedLine}${nextLine}${antiTrap}${switchLine}`;
     }
     case "activation_required":
-      return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`. ${DOCS_HINT}`;
+      return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`.`;
     case "topup_required": {
       const balance = gate.creditBalance;
       const cost = gate.creditsPerCall;
       const shortfall = gate.shortfallCredits;
       let lead;
       if (balance !== void 0 && cost !== void 0 && shortfall !== void 0) {
-        lead = `Out of credits for this call. Balance ${formatCredits(balance)} credits; this call costs ${formatCredits(cost)} credits \u2014 ${formatCredits(shortfall)} short.`;
+        lead = `Out of credits for this call. Balance ${formatCreditsWithMoney(balance, gate)}; this call costs ${formatCreditsWithMoney(cost, gate)} \u2014 ${formatCredits(shortfall)} short.`;
       } else {
         lead = "Included usage is exhausted.";
       }
       const topup = recoverClause(url, "add credits", "topup", "Add credits");
-      const auto = autoRechargeDisabled(gate) ? " Auto-recharge is off \u2014 turn it on from the account tool to avoid this next time." : "";
-      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : "";
-      return `${lead}${topup}${auto}${switchLine} ${DOCS_HINT}`;
+      const auto = autoRechargeDisabled(gate) ? ` Auto-recharge is off \u2014 ${callViewer("account")} to turn it on and avoid this next time.` : "";
+      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : hasActivePlan(gate) ? "" : ` Or ${callViewer("checkout")} to pick a plan.`;
+      return `${lead}${topup}${auto}${switchLine}`;
     }
     case "upgrade_required": {
       if (hasActivePlan(gate)) {
         const planName = gate.planName ?? "This plan";
         const lead = `${planName} is active but its included usage is exhausted, and the automatic switch to the next plan did not complete.`;
         if (ladder) {
-          return `${lead} Switch here: ${ladder}. ${DOCS_HINT}`;
+          return `${lead} Switch here: ${ladder}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.`;
         }
-        return `${lead}${recoverClause(url, "switch plan", "checkout")} ${DOCS_HINT}`;
+        return `${lead}${recoverClause(url, "switch plan", "checkout")}`;
       }
       if (ladder) {
-        return `You don't have an active plan for this tool. Pick a plan to use this tool: ${ladder} (links expire in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer("checkout")}. ${DOCS_HINT}`;
+        return `You don't have an active plan for this tool. Pick a plan to use this tool: ${ladder} (links expire in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer("checkout")}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.`;
       }
-      return `You don't have an active plan for this tool.${recoverClause(url, "pick a plan", "checkout")} ${DOCS_HINT}`;
+      return `You don't have an active plan for this tool.${recoverClause(url, "pick a plan", "checkout")}`;
     }
     case "reactivation_required":
-      return `Your previous plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it, or ${callViewer("checkout")} to pick a new plan. ${DOCS_HINT}`;
+      return `Your previous plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it, or ${callViewer("checkout")} to pick a new plan.`;
   }
 }
 function buildNudgeMessage(state, limits) {
   const url = limits?.checkoutUrl && limits.checkoutUrl.length > 0 ? limits.checkoutUrl : null;
   const visitClause = url ? `, or ${namedCheckoutMarkdown(url)}` : "";
-  const remaining = creditSignals(limits).remainingCalls;
-  switch (state.kind) {
+  const signals = creditSignals(limits);
+  const remaining = signals.remainingCalls;
+  const kind = state.kind === "topup_required" && limits && !signals.isCreditBased ? "limit_reached" : state.kind;
+  switch (kind) {
     case "topup_required":
       if (remaining === 0) {
         return `Heads up \u2014 0 calls left \u2014 the next call needs a top-up. ${callViewer("topup").replace(/^c/, "C")} to add more${visitClause}.`;
@@ -939,6 +958,8 @@ function recoveryFields(limits, state) {
     ...signals.creditsPerCall !== void 0 ? { creditsPerCall: signals.creditsPerCall } : {},
     ...signals.shortfallCredits !== void 0 ? { shortfallCredits: signals.shortfallCredits } : {},
     ...signals.remainingCalls !== void 0 ? { remainingCalls: signals.remainingCalls } : {},
+    ...limits.balance?.creditsPerMinorUnit !== void 0 ? { creditsPerMinorUnit: limits.balance.creditsPerMinorUnit } : {},
+    ...limits.balance?.displayExchangeRate !== void 0 ? { displayExchangeRate: limits.balance.displayExchangeRate } : {},
     ...limits.purchaseRef !== void 0 ? { purchaseRef: limits.purchaseRef } : {},
     ...limits.autoRecharge !== void 0 ? { autoRecharge: limits.autoRecharge } : {},
     ...links ? { links } : {}
@@ -1195,6 +1216,23 @@ var SolvaPayPaywall = class {
       console.log(...args);
     }
   }
+  /**
+   * Drop cached limits for `customerRef`. When `product` is omitted every
+   * meter/product entry for that customer is removed. Matches both the
+   * backend `cus_…` ref and an unmapped external ref used as a cache key.
+   */
+  invalidateLimits(customerRef, product) {
+    const aliases = /* @__PURE__ */ new Set([customerRef]);
+    const mapped = this.customerRefMapping.get(customerRef);
+    if (mapped) aliases.add(mapped);
+    if (!customerRef.startsWith("cus_")) aliases.add(`cus_${customerRef}`);
+    for (const key of [...this.limitsCache.keys()]) {
+      const [ref, prod] = key.split(":");
+      if (!ref || !aliases.has(ref)) continue;
+      if (product && prod !== product) continue;
+      this.limitsCache.delete(key);
+    }
+  }
   resolveProduct(metadata) {
     return requireProductRef(metadata.product);
   }
@@ -2214,6 +2252,9 @@ function createSolvaPay(config) {
     paywall: {
       decide(args, metadata, getCustomerRef) {
         return paywall.decide(args, metadata, getCustomerRef);
+      },
+      invalidateLimits(customerRef, product) {
+        paywall.invalidateLimits(customerRef, product);
       }
     },
     // Common API methods exposed directly for convenience
@@ -2282,7 +2323,7 @@ function createSolvaPay(config) {
         customerRef: params.customerRef,
         productRef: params.productRef,
         planRef: params.planRef,
-        returnUrl: params.returnUrl,
+        ...params.returnUrl ? { returnUrl: params.returnUrl } : {},
         ...params.purpose ? { purpose: params.purpose } : {}
       });
     },
@@ -2981,12 +3022,15 @@ async function createCheckoutSessionCore(request, body, options = {}) {
       return customerResult;
     }
     const customerRef = customerResult;
-    let returnUrl = body.returnUrl || options.returnUrl;
-    if (!returnUrl) {
-      try {
-        const url = new URL(request.url);
-        returnUrl = url.origin;
-      } catch {
+    let returnUrl;
+    if (body.returnUrl !== null) {
+      returnUrl = body.returnUrl || options.returnUrl;
+      if (!returnUrl) {
+        try {
+          const url = new URL(request.url);
+          returnUrl = url.origin;
+        } catch {
+        }
       }
     }
     const solvaPay = options.solvaPay || createSolvaPay();
@@ -2994,7 +3038,7 @@ async function createCheckoutSessionCore(request, body, options = {}) {
       productRef: body.productRef,
       customerRef,
       planRef: body.planRef || void 0,
-      returnUrl,
+      ...returnUrl ? { returnUrl } : {},
       ...body.purpose ? { purpose: body.purpose } : {}
     });
     return {

package/dist/fetch/index.cjs

@@ -841,7 +841,6 @@ function createSolvaPayClient(opts) {
 // src/paywall-state.ts
 var import_core3 = require("@solvapay/core");
 var CHECKOUT_SESSION_TTL_MINUTES = 15;
-var DOCS_HINT = "See docs://solvapay/overview.md.";
 function creditSignals(limits) {
   if (!limits) return { isCreditBased: false };
   const creditBalance = limits.balance?.creditBalance ?? limits.creditBalance;
@@ -925,6 +924,24 @@ function formatMinor(amountMinor, currency) {
 function formatCredits(value) {
   return value.toLocaleString("en-US");
 }
+function formatCreditsWithMoney(credits, gate) {
+  const amount = formatCredits(credits);
+  const peg = gate.creditsPerMinorUnit;
+  const currency = gate.currency;
+  const rate = gate.displayExchangeRate;
+  if (peg && peg > 0 && currency && rate != null && rate > 0) {
+    const minor = (0, import_core3.creditsToDisplayMinorUnits)({
+      credits,
+      creditsPerMinorUnit: peg,
+      displayExchangeRate: rate,
+      displayCurrency: currency
+    });
+    if (minor != null) {
+      return `${amount} credits (~${formatMinor(minor, currency)})`;
+    }
+  }
+  return `${amount} credits`;
+}
 function meterLabel(gate) {
   if (!gate.meterName) return "units";
   return gate.meterName.replace(/_/g, " ");
@@ -968,42 +985,42 @@ function buildGateMessage(state, gate) {
       const nextLine = price ? ` The next call is ${price}.` : "";
       const planName = gate.planName ?? "This plan";
       const antiTrap = gate.creditBalance !== void 0 && gate.creditBalance > 0 && (gate.creditsPerCall === void 0 || gate.creditsPerCall === 0) ? ` Adding credits will not help, because ${planName} does not spend them.` : "";
-      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : recoverClause(url, "continue", "checkout");
-      return `${usedLine}${nextLine}${antiTrap}${switchLine} ${DOCS_HINT}`;
+      const switchLine = ladder ? ` Or switch plan: ${ladder}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.` : recoverClause(url, "continue", "checkout");
+      return `${usedLine}${nextLine}${antiTrap}${switchLine}`;
     }
     case "activation_required":
-      return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`. ${DOCS_HINT}`;
+      return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`.`;
     case "topup_required": {
       const balance = gate.creditBalance;
       const cost = gate.creditsPerCall;
       const shortfall = gate.shortfallCredits;
       let lead;
       if (balance !== void 0 && cost !== void 0 && shortfall !== void 0) {
-        lead = `Out of credits for this call. Balance ${formatCredits(balance)} credits; this call costs ${formatCredits(cost)} credits \u2014 ${formatCredits(shortfall)} short.`;
+        lead = `Out of credits for this call. Balance ${formatCreditsWithMoney(balance, gate)}; this call costs ${formatCreditsWithMoney(cost, gate)} \u2014 ${formatCredits(shortfall)} short.`;
       } else {
         lead = "Included usage is exhausted.";
       }
       const topup = recoverClause(url, "add credits", "topup", "Add credits");
-      const auto = autoRechargeDisabled(gate) ? " Auto-recharge is off \u2014 turn it on from the account tool to avoid this next time." : "";
-      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : "";
-      return `${lead}${topup}${auto}${switchLine} ${DOCS_HINT}`;
+      const auto = autoRechargeDisabled(gate) ? ` Auto-recharge is off \u2014 ${callViewer("account")} to turn it on and avoid this next time.` : "";
+      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : hasActivePlan(gate) ? "" : ` Or ${callViewer("checkout")} to pick a plan.`;
+      return `${lead}${topup}${auto}${switchLine}`;
     }
     case "upgrade_required": {
       if (hasActivePlan(gate)) {
         const planName = gate.planName ?? "This plan";
         const lead = `${planName} is active but its included usage is exhausted, and the automatic switch to the next plan did not complete.`;
         if (ladder) {
-          return `${lead} Switch here: ${ladder}. ${DOCS_HINT}`;
+          return `${lead} Switch here: ${ladder}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.`;
         }
-        return `${lead}${recoverClause(url, "switch plan", "checkout")} ${DOCS_HINT}`;
+        return `${lead}${recoverClause(url, "switch plan", "checkout")}`;
       }
       if (ladder) {
-        return `You don't have an active plan for this tool. Pick a plan to use this tool: ${ladder} (links expire in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer("checkout")}. ${DOCS_HINT}`;
+        return `You don't have an active plan for this tool. Pick a plan to use this tool: ${ladder} (links expire in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer("checkout")}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.`;
       }
-      return `You don't have an active plan for this tool.${recoverClause(url, "pick a plan", "checkout")} ${DOCS_HINT}`;
+      return `You don't have an active plan for this tool.${recoverClause(url, "pick a plan", "checkout")}`;
     }
     case "reactivation_required":
-      return `Your previous plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it, or ${callViewer("checkout")} to pick a new plan. ${DOCS_HINT}`;
+      return `Your previous plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it, or ${callViewer("checkout")} to pick a new plan.`;
   }
 }
 
@@ -1073,6 +1090,8 @@ function recoveryFields(limits, state) {
     ...signals.creditsPerCall !== void 0 ? { creditsPerCall: signals.creditsPerCall } : {},
     ...signals.shortfallCredits !== void 0 ? { shortfallCredits: signals.shortfallCredits } : {},
     ...signals.remainingCalls !== void 0 ? { remainingCalls: signals.remainingCalls } : {},
+    ...limits.balance?.creditsPerMinorUnit !== void 0 ? { creditsPerMinorUnit: limits.balance.creditsPerMinorUnit } : {},
+    ...limits.balance?.displayExchangeRate !== void 0 ? { displayExchangeRate: limits.balance.displayExchangeRate } : {},
     ...limits.purchaseRef !== void 0 ? { purchaseRef: limits.purchaseRef } : {},
     ...limits.autoRecharge !== void 0 ? { autoRecharge: limits.autoRecharge } : {},
     ...links ? { links } : {}
@@ -1329,6 +1348,23 @@ var SolvaPayPaywall = class {
       console.log(...args);
     }
   }
+  /**
+   * Drop cached limits for `customerRef`. When `product` is omitted every
+   * meter/product entry for that customer is removed. Matches both the
+   * backend `cus_…` ref and an unmapped external ref used as a cache key.
+   */
+  invalidateLimits(customerRef, product) {
+    const aliases = /* @__PURE__ */ new Set([customerRef]);
+    const mapped = this.customerRefMapping.get(customerRef);
+    if (mapped) aliases.add(mapped);
+    if (!customerRef.startsWith("cus_")) aliases.add(`cus_${customerRef}`);
+    for (const key of [...this.limitsCache.keys()]) {
+      const [ref, prod] = key.split(":");
+      if (!ref || !aliases.has(ref)) continue;
+      if (product && prod !== product) continue;
+      this.limitsCache.delete(key);
+    }
+  }
   resolveProduct(metadata) {
     return requireProductRef(metadata.product);
   }
@@ -2348,6 +2384,9 @@ function createSolvaPay(config) {
     paywall: {
       decide(args, metadata, getCustomerRef) {
         return paywall.decide(args, metadata, getCustomerRef);
+      },
+      invalidateLimits(customerRef, product) {
+        paywall.invalidateLimits(customerRef, product);
       }
     },
     // Common API methods exposed directly for convenience
@@ -2416,7 +2455,7 @@ function createSolvaPay(config) {
         customerRef: params.customerRef,
         productRef: params.productRef,
         planRef: params.planRef,
-        returnUrl: params.returnUrl,
+        ...params.returnUrl ? { returnUrl: params.returnUrl } : {},
         ...params.purpose ? { purpose: params.purpose } : {}
       });
     },
@@ -2762,12 +2801,15 @@ async function createCheckoutSessionCore(request, body, options = {}) {
       return customerResult;
     }
     const customerRef = customerResult;
-    let returnUrl = body.returnUrl || options.returnUrl;
-    if (!returnUrl) {
-      try {
-        const url = new URL(request.url);
-        returnUrl = url.origin;
-      } catch {
+    let returnUrl;
+    if (body.returnUrl !== null) {
+      returnUrl = body.returnUrl || options.returnUrl;
+      if (!returnUrl) {
+        try {
+          const url = new URL(request.url);
+          returnUrl = url.origin;
+        } catch {
+        }
       }
     }
     const solvaPay = options.solvaPay || createSolvaPay();
@@ -2775,7 +2817,7 @@ async function createCheckoutSessionCore(request, body, options = {}) {
       productRef: body.productRef,
       customerRef,
       planRef: body.planRef || void 0,
-      returnUrl,
+      ...returnUrl ? { returnUrl } : {},
       ...body.purpose ? { purpose: body.purpose } : {}
     });
     return {

package/dist/fetch/index.d.cts

@@ -828,6 +828,10 @@ interface components {
             currency: string;
             /** @description How many metered items the credit balance still covers (`balance / creditsPerUnit`) */
             remainingUnits?: number;
+            /** @description Credits per minor unit of `currency` (typically 100) */
+            creditsPerMinorUnit?: number;
+            /** @description USD → display-currency rate used with creditsPerMinorUnit */
+            displayExchangeRate?: number;
         };
         LimitPlanItemDto: {
             /** @description Derived billing cycle */

package/dist/fetch/index.d.ts

@@ -828,6 +828,10 @@ interface components {
             currency: string;
             /** @description How many metered items the credit balance still covers (`balance / creditsPerUnit`) */
             remainingUnits?: number;
+            /** @description Credits per minor unit of `currency` (typically 100) */
+            creditsPerMinorUnit?: number;
+            /** @description USD → display-currency rate used with creditsPerMinorUnit */
+            displayExchangeRate?: number;
         };
         LimitPlanItemDto: {
             /** @description Derived billing cycle */

package/dist/fetch/index.js

@@ -785,9 +785,8 @@ function createSolvaPayClient(opts) {
 }
 
 // src/paywall-state.ts
-import { minorUnitsPerMajor } from "@solvapay/core";
+import { creditsToDisplayMinorUnits, minorUnitsPerMajor } from "@solvapay/core";
 var CHECKOUT_SESSION_TTL_MINUTES = 15;
-var DOCS_HINT = "See docs://solvapay/overview.md.";
 function creditSignals(limits) {
   if (!limits) return { isCreditBased: false };
   const creditBalance = limits.balance?.creditBalance ?? limits.creditBalance;
@@ -871,6 +870,24 @@ function formatMinor(amountMinor, currency) {
 function formatCredits(value) {
   return value.toLocaleString("en-US");
 }
+function formatCreditsWithMoney(credits, gate) {
+  const amount = formatCredits(credits);
+  const peg = gate.creditsPerMinorUnit;
+  const currency = gate.currency;
+  const rate = gate.displayExchangeRate;
+  if (peg && peg > 0 && currency && rate != null && rate > 0) {
+    const minor = creditsToDisplayMinorUnits({
+      credits,
+      creditsPerMinorUnit: peg,
+      displayExchangeRate: rate,
+      displayCurrency: currency
+    });
+    if (minor != null) {
+      return `${amount} credits (~${formatMinor(minor, currency)})`;
+    }
+  }
+  return `${amount} credits`;
+}
 function meterLabel(gate) {
   if (!gate.meterName) return "units";
   return gate.meterName.replace(/_/g, " ");
@@ -914,42 +931,42 @@ function buildGateMessage(state, gate) {
       const nextLine = price ? ` The next call is ${price}.` : "";
       const planName = gate.planName ?? "This plan";
       const antiTrap = gate.creditBalance !== void 0 && gate.creditBalance > 0 && (gate.creditsPerCall === void 0 || gate.creditsPerCall === 0) ? ` Adding credits will not help, because ${planName} does not spend them.` : "";
-      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : recoverClause(url, "continue", "checkout");
-      return `${usedLine}${nextLine}${antiTrap}${switchLine} ${DOCS_HINT}`;
+      const switchLine = ladder ? ` Or switch plan: ${ladder}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.` : recoverClause(url, "continue", "checkout");
+      return `${usedLine}${nextLine}${antiTrap}${switchLine}`;
     }
     case "activation_required":
-      return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`. ${DOCS_HINT}`;
+      return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`.`;
     case "topup_required": {
       const balance = gate.creditBalance;
       const cost = gate.creditsPerCall;
       const shortfall = gate.shortfallCredits;
       let lead;
       if (balance !== void 0 && cost !== void 0 && shortfall !== void 0) {
-        lead = `Out of credits for this call. Balance ${formatCredits(balance)} credits; this call costs ${formatCredits(cost)} credits \u2014 ${formatCredits(shortfall)} short.`;
+        lead = `Out of credits for this call. Balance ${formatCreditsWithMoney(balance, gate)}; this call costs ${formatCreditsWithMoney(cost, gate)} \u2014 ${formatCredits(shortfall)} short.`;
       } else {
         lead = "Included usage is exhausted.";
       }
       const topup = recoverClause(url, "add credits", "topup", "Add credits");
-      const auto = autoRechargeDisabled(gate) ? " Auto-recharge is off \u2014 turn it on from the account tool to avoid this next time." : "";
-      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : "";
-      return `${lead}${topup}${auto}${switchLine} ${DOCS_HINT}`;
+      const auto = autoRechargeDisabled(gate) ? ` Auto-recharge is off \u2014 ${callViewer("account")} to turn it on and avoid this next time.` : "";
+      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : hasActivePlan(gate) ? "" : ` Or ${callViewer("checkout")} to pick a plan.`;
+      return `${lead}${topup}${auto}${switchLine}`;
     }
     case "upgrade_required": {
       if (hasActivePlan(gate)) {
         const planName = gate.planName ?? "This plan";
         const lead = `${planName} is active but its included usage is exhausted, and the automatic switch to the next plan did not complete.`;
         if (ladder) {
-          return `${lead} Switch here: ${ladder}. ${DOCS_HINT}`;
+          return `${lead} Switch here: ${ladder}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.`;
         }
-        return `${lead}${recoverClause(url, "switch plan", "checkout")} ${DOCS_HINT}`;
+        return `${lead}${recoverClause(url, "switch plan", "checkout")}`;
       }
       if (ladder) {
-        return `You don't have an active plan for this tool. Pick a plan to use this tool: ${ladder} (links expire in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer("checkout")}. ${DOCS_HINT}`;
+        return `You don't have an active plan for this tool. Pick a plan to use this tool: ${ladder} (links expire in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer("checkout")}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.`;
       }
-      return `You don't have an active plan for this tool.${recoverClause(url, "pick a plan", "checkout")} ${DOCS_HINT}`;
+      return `You don't have an active plan for this tool.${recoverClause(url, "pick a plan", "checkout")}`;
     }
     case "reactivation_required":
-      return `Your previous plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it, or ${callViewer("checkout")} to pick a new plan. ${DOCS_HINT}`;
+      return `Your previous plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it, or ${callViewer("checkout")} to pick a new plan.`;
   }
 }
 
@@ -1019,6 +1036,8 @@ function recoveryFields(limits, state) {
     ...signals.creditsPerCall !== void 0 ? { creditsPerCall: signals.creditsPerCall } : {},
     ...signals.shortfallCredits !== void 0 ? { shortfallCredits: signals.shortfallCredits } : {},
     ...signals.remainingCalls !== void 0 ? { remainingCalls: signals.remainingCalls } : {},
+    ...limits.balance?.creditsPerMinorUnit !== void 0 ? { creditsPerMinorUnit: limits.balance.creditsPerMinorUnit } : {},
+    ...limits.balance?.displayExchangeRate !== void 0 ? { displayExchangeRate: limits.balance.displayExchangeRate } : {},
     ...limits.purchaseRef !== void 0 ? { purchaseRef: limits.purchaseRef } : {},
     ...limits.autoRecharge !== void 0 ? { autoRecharge: limits.autoRecharge } : {},
     ...links ? { links } : {}
@@ -1275,6 +1294,23 @@ var SolvaPayPaywall = class {
       console.log(...args);
     }
   }
+  /**
+   * Drop cached limits for `customerRef`. When `product` is omitted every
+   * meter/product entry for that customer is removed. Matches both the
+   * backend `cus_…` ref and an unmapped external ref used as a cache key.
+   */
+  invalidateLimits(customerRef, product) {
+    const aliases = /* @__PURE__ */ new Set([customerRef]);
+    const mapped = this.customerRefMapping.get(customerRef);
+    if (mapped) aliases.add(mapped);
+    if (!customerRef.startsWith("cus_")) aliases.add(`cus_${customerRef}`);
+    for (const key of [...this.limitsCache.keys()]) {
+      const [ref, prod] = key.split(":");
+      if (!ref || !aliases.has(ref)) continue;
+      if (product && prod !== product) continue;
+      this.limitsCache.delete(key);
+    }
+  }
   resolveProduct(metadata) {
     return requireProductRef(metadata.product);
   }
@@ -2294,6 +2330,9 @@ function createSolvaPay(config) {
     paywall: {
       decide(args, metadata, getCustomerRef) {
         return paywall.decide(args, metadata, getCustomerRef);
+      },
+      invalidateLimits(customerRef, product) {
+        paywall.invalidateLimits(customerRef, product);
       }
     },
     // Common API methods exposed directly for convenience
@@ -2362,7 +2401,7 @@ function createSolvaPay(config) {
         customerRef: params.customerRef,
         productRef: params.productRef,
         planRef: params.planRef,
-        returnUrl: params.returnUrl,
+        ...params.returnUrl ? { returnUrl: params.returnUrl } : {},
         ...params.purpose ? { purpose: params.purpose } : {}
       });
     },
@@ -2710,12 +2749,15 @@ async function createCheckoutSessionCore(request, body, options = {}) {
       return customerResult;
     }
     const customerRef = customerResult;
-    let returnUrl = body.returnUrl || options.returnUrl;
-    if (!returnUrl) {
-      try {
-        const url = new URL(request.url);
-        returnUrl = url.origin;
-      } catch {
+    let returnUrl;
+    if (body.returnUrl !== null) {
+      returnUrl = body.returnUrl || options.returnUrl;
+      if (!returnUrl) {
+        try {
+          const url = new URL(request.url);
+          returnUrl = url.origin;
+        } catch {
+        }
       }
     }
     const solvaPay = options.solvaPay || createSolvaPay();
@@ -2723,7 +2765,7 @@ async function createCheckoutSessionCore(request, body, options = {}) {
       productRef: body.productRef,
       customerRef,
       planRef: body.planRef || void 0,
-      returnUrl,
+      ...returnUrl ? { returnUrl } : {},
       ...body.purpose ? { purpose: body.purpose } : {}
     });
     return {

package/dist/index.cjs

@@ -722,7 +722,6 @@ function createSolvaPayClient(opts) {
 // src/paywall-state.ts
 var import_core2 = require("@solvapay/core");
 var CHECKOUT_SESSION_TTL_MINUTES = 15;
-var DOCS_HINT = "See docs://solvapay/overview.md.";
 function creditSignals(limits) {
   if (!limits) return { isCreditBased: false };
   const creditBalance = limits.balance?.creditBalance ?? limits.creditBalance;
@@ -806,6 +805,24 @@ function formatMinor(amountMinor, currency) {
 function formatCredits(value) {
   return value.toLocaleString("en-US");
 }
+function formatCreditsWithMoney(credits, gate) {
+  const amount = formatCredits(credits);
+  const peg = gate.creditsPerMinorUnit;
+  const currency = gate.currency;
+  const rate = gate.displayExchangeRate;
+  if (peg && peg > 0 && currency && rate != null && rate > 0) {
+    const minor = (0, import_core2.creditsToDisplayMinorUnits)({
+      credits,
+      creditsPerMinorUnit: peg,
+      displayExchangeRate: rate,
+      displayCurrency: currency
+    });
+    if (minor != null) {
+      return `${amount} credits (~${formatMinor(minor, currency)})`;
+    }
+  }
+  return `${amount} credits`;
+}
 function meterLabel(gate) {
   if (!gate.meterName) return "units";
   return gate.meterName.replace(/_/g, " ");
@@ -849,49 +866,51 @@ function buildGateMessage(state, gate) {
       const nextLine = price ? ` The next call is ${price}.` : "";
       const planName = gate.planName ?? "This plan";
       const antiTrap = gate.creditBalance !== void 0 && gate.creditBalance > 0 && (gate.creditsPerCall === void 0 || gate.creditsPerCall === 0) ? ` Adding credits will not help, because ${planName} does not spend them.` : "";
-      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : recoverClause(url, "continue", "checkout");
-      return `${usedLine}${nextLine}${antiTrap}${switchLine} ${DOCS_HINT}`;
+      const switchLine = ladder ? ` Or switch plan: ${ladder}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.` : recoverClause(url, "continue", "checkout");
+      return `${usedLine}${nextLine}${antiTrap}${switchLine}`;
     }
     case "activation_required":
-      return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`. ${DOCS_HINT}`;
+      return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`.`;
     case "topup_required": {
       const balance = gate.creditBalance;
       const cost = gate.creditsPerCall;
       const shortfall = gate.shortfallCredits;
       let lead;
       if (balance !== void 0 && cost !== void 0 && shortfall !== void 0) {
-        lead = `Out of credits for this call. Balance ${formatCredits(balance)} credits; this call costs ${formatCredits(cost)} credits \u2014 ${formatCredits(shortfall)} short.`;
+        lead = `Out of credits for this call. Balance ${formatCreditsWithMoney(balance, gate)}; this call costs ${formatCreditsWithMoney(cost, gate)} \u2014 ${formatCredits(shortfall)} short.`;
       } else {
         lead = "Included usage is exhausted.";
       }
       const topup = recoverClause(url, "add credits", "topup", "Add credits");
-      const auto = autoRechargeDisabled(gate) ? " Auto-recharge is off \u2014 turn it on from the account tool to avoid this next time." : "";
-      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : "";
-      return `${lead}${topup}${auto}${switchLine} ${DOCS_HINT}`;
+      const auto = autoRechargeDisabled(gate) ? ` Auto-recharge is off \u2014 ${callViewer("account")} to turn it on and avoid this next time.` : "";
+      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : hasActivePlan(gate) ? "" : ` Or ${callViewer("checkout")} to pick a plan.`;
+      return `${lead}${topup}${auto}${switchLine}`;
     }
     case "upgrade_required": {
       if (hasActivePlan(gate)) {
         const planName = gate.planName ?? "This plan";
         const lead = `${planName} is active but its included usage is exhausted, and the automatic switch to the next plan did not complete.`;
         if (ladder) {
-          return `${lead} Switch here: ${ladder}. ${DOCS_HINT}`;
+          return `${lead} Switch here: ${ladder}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.`;
         }
-        return `${lead}${recoverClause(url, "switch plan", "checkout")} ${DOCS_HINT}`;
+        return `${lead}${recoverClause(url, "switch plan", "checkout")}`;
       }
       if (ladder) {
-        return `You don't have an active plan for this tool. Pick a plan to use this tool: ${ladder} (links expire in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer("checkout")}. ${DOCS_HINT}`;
+        return `You don't have an active plan for this tool. Pick a plan to use this tool: ${ladder} (links expire in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer("checkout")}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.`;
       }
-      return `You don't have an active plan for this tool.${recoverClause(url, "pick a plan", "checkout")} ${DOCS_HINT}`;
+      return `You don't have an active plan for this tool.${recoverClause(url, "pick a plan", "checkout")}`;
     }
     case "reactivation_required":
-      return `Your previous plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it, or ${callViewer("checkout")} to pick a new plan. ${DOCS_HINT}`;
+      return `Your previous plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it, or ${callViewer("checkout")} to pick a new plan.`;
   }
 }
 function buildNudgeMessage(state, limits) {
   const url = limits?.checkoutUrl && limits.checkoutUrl.length > 0 ? limits.checkoutUrl : null;
   const visitClause = url ? `, or ${namedCheckoutMarkdown(url)}` : "";
-  const remaining = creditSignals(limits).remainingCalls;
-  switch (state.kind) {
+  const signals = creditSignals(limits);
+  const remaining = signals.remainingCalls;
+  const kind = state.kind === "topup_required" && limits && !signals.isCreditBased ? "limit_reached" : state.kind;
+  switch (kind) {
     case "topup_required":
       if (remaining === 0) {
         return `Heads up \u2014 0 calls left \u2014 the next call needs a top-up. ${callViewer("topup").replace(/^c/, "C")} to add more${visitClause}.`;
@@ -976,6 +995,8 @@ function recoveryFields(limits, state) {
     ...signals.creditsPerCall !== void 0 ? { creditsPerCall: signals.creditsPerCall } : {},
     ...signals.shortfallCredits !== void 0 ? { shortfallCredits: signals.shortfallCredits } : {},
     ...signals.remainingCalls !== void 0 ? { remainingCalls: signals.remainingCalls } : {},
+    ...limits.balance?.creditsPerMinorUnit !== void 0 ? { creditsPerMinorUnit: limits.balance.creditsPerMinorUnit } : {},
+    ...limits.balance?.displayExchangeRate !== void 0 ? { displayExchangeRate: limits.balance.displayExchangeRate } : {},
     ...limits.purchaseRef !== void 0 ? { purchaseRef: limits.purchaseRef } : {},
     ...limits.autoRecharge !== void 0 ? { autoRecharge: limits.autoRecharge } : {},
     ...links ? { links } : {}
@@ -1232,6 +1253,23 @@ var SolvaPayPaywall = class {
       console.log(...args);
     }
   }
+  /**
+   * Drop cached limits for `customerRef`. When `product` is omitted every
+   * meter/product entry for that customer is removed. Matches both the
+   * backend `cus_…` ref and an unmapped external ref used as a cache key.
+   */
+  invalidateLimits(customerRef, product) {
+    const aliases = /* @__PURE__ */ new Set([customerRef]);
+    const mapped = this.customerRefMapping.get(customerRef);
+    if (mapped) aliases.add(mapped);
+    if (!customerRef.startsWith("cus_")) aliases.add(`cus_${customerRef}`);
+    for (const key of [...this.limitsCache.keys()]) {
+      const [ref, prod] = key.split(":");
+      if (!ref || !aliases.has(ref)) continue;
+      if (product && prod !== product) continue;
+      this.limitsCache.delete(key);
+    }
+  }
   resolveProduct(metadata) {
     return requireProductRef(metadata.product);
   }
@@ -2252,6 +2290,9 @@ function createSolvaPay(config) {
     paywall: {
       decide(args, metadata, getCustomerRef) {
         return paywall.decide(args, metadata, getCustomerRef);
+      },
+      invalidateLimits(customerRef, product) {
+        paywall.invalidateLimits(customerRef, product);
       }
     },
     // Common API methods exposed directly for convenience
@@ -2320,7 +2361,7 @@ function createSolvaPay(config) {
         customerRef: params.customerRef,
         productRef: params.productRef,
         planRef: params.planRef,
-        returnUrl: params.returnUrl,
+        ...params.returnUrl ? { returnUrl: params.returnUrl } : {},
         ...params.purpose ? { purpose: params.purpose } : {}
       });
     },
@@ -3066,12 +3107,15 @@ async function createCheckoutSessionCore(request, body, options = {}) {
       return customerResult;
     }
     const customerRef = customerResult;
-    let returnUrl = body.returnUrl || options.returnUrl;
-    if (!returnUrl) {
-      try {
-        const url = new URL(request.url);
-        returnUrl = url.origin;
-      } catch {
+    let returnUrl;
+    if (body.returnUrl !== null) {
+      returnUrl = body.returnUrl || options.returnUrl;
+      if (!returnUrl) {
+        try {
+          const url = new URL(request.url);
+          returnUrl = url.origin;
+        } catch {
+        }
       }
     }
     const solvaPay = options.solvaPay || createSolvaPay();
@@ -3079,7 +3123,7 @@ async function createCheckoutSessionCore(request, body, options = {}) {
       productRef: body.productRef,
       customerRef,
       planRef: body.planRef || void 0,
-      returnUrl,
+      ...returnUrl ? { returnUrl } : {},
       ...body.purpose ? { purpose: body.purpose } : {}
     });
     return {

package/dist/index.d.cts

@@ -831,6 +831,10 @@ interface components {
             currency: string;
             /** @description How many metered items the credit balance still covers (`balance / creditsPerUnit`) */
             remainingUnits?: number;
+            /** @description Credits per minor unit of `currency` (typically 100) */
+            creditsPerMinorUnit?: number;
+            /** @description USD → display-currency rate used with creditsPerMinorUnit */
+            displayExchangeRate?: number;
         };
         LimitPlanItemDto: {
             /** @description Derived billing cycle */
@@ -4309,6 +4313,10 @@ type PaywallGateRecoveryFields = {
     shortfallCredits?: number;
     /** How many calls the current allowance or wallet still covers. */
     remainingCalls?: number;
+    /** Credits per minor currency unit, from the limits balance peg. */
+    creditsPerMinorUnit?: number;
+    /** USD → display-currency rate used with `creditsPerMinorUnit`. */
+    displayExchangeRate?: number;
     /** Active purchase reference when the customer already holds a purchase. */
     purchaseRef?: string;
     /** Purchase/plan status when the backend sent one. */
@@ -5300,6 +5308,12 @@ interface SolvaPay {
      */
     paywall: {
         decide<TArgs extends PaywallArgs>(args: TArgs, metadata?: PaywallMetadata, getCustomerRef?: (args: TArgs) => string): Promise<PaywallDecision<TArgs>>;
+        /**
+         * Drop cached `checkLimits` snapshots for this customer (optionally
+         * scoped to one product). Call after `activate_plan`, a completed
+         * checkout, or a top-up so the next payable call refetches.
+         */
+        invalidateLimits(customerRef: string, product?: string): void;
     };
     /**
      * Direct access to the API client for advanced operations.
@@ -6209,7 +6223,13 @@ declare function processTopupPaymentIntentCore(request: Request, body: {
 declare function createCheckoutSessionCore(request: Request, body: {
     productRef: string;
     planRef?: string;
-    returnUrl?: string;
+    /**
+     * URL to send the customer back to after payment. Pass `null` to omit
+     * the field entirely — skips `options.returnUrl` and the request-origin
+     * fallback. Use this when the caller has no browsable page to return to
+     * (MCP servers whose public URL is an API endpoint, not a website).
+     */
+    returnUrl?: string | null;
     purpose?: 'credit_topup';
 }, options?: {
     solvaPay?: SolvaPay;

package/dist/index.d.ts

@@ -831,6 +831,10 @@ interface components {
             currency: string;
             /** @description How many metered items the credit balance still covers (`balance / creditsPerUnit`) */
             remainingUnits?: number;
+            /** @description Credits per minor unit of `currency` (typically 100) */
+            creditsPerMinorUnit?: number;
+            /** @description USD → display-currency rate used with creditsPerMinorUnit */
+            displayExchangeRate?: number;
         };
         LimitPlanItemDto: {
             /** @description Derived billing cycle */
@@ -4309,6 +4313,10 @@ type PaywallGateRecoveryFields = {
     shortfallCredits?: number;
     /** How many calls the current allowance or wallet still covers. */
     remainingCalls?: number;
+    /** Credits per minor currency unit, from the limits balance peg. */
+    creditsPerMinorUnit?: number;
+    /** USD → display-currency rate used with `creditsPerMinorUnit`. */
+    displayExchangeRate?: number;
     /** Active purchase reference when the customer already holds a purchase. */
     purchaseRef?: string;
     /** Purchase/plan status when the backend sent one. */
@@ -5300,6 +5308,12 @@ interface SolvaPay {
      */
     paywall: {
         decide<TArgs extends PaywallArgs>(args: TArgs, metadata?: PaywallMetadata, getCustomerRef?: (args: TArgs) => string): Promise<PaywallDecision<TArgs>>;
+        /**
+         * Drop cached `checkLimits` snapshots for this customer (optionally
+         * scoped to one product). Call after `activate_plan`, a completed
+         * checkout, or a top-up so the next payable call refetches.
+         */
+        invalidateLimits(customerRef: string, product?: string): void;
     };
     /**
      * Direct access to the API client for advanced operations.
@@ -6209,7 +6223,13 @@ declare function processTopupPaymentIntentCore(request: Request, body: {
 declare function createCheckoutSessionCore(request: Request, body: {
     productRef: string;
     planRef?: string;
-    returnUrl?: string;
+    /**
+     * URL to send the customer back to after payment. Pass `null` to omit
+     * the field entirely — skips `options.returnUrl` and the request-origin
+     * fallback. Use this when the caller has no browsable page to return to
+     * (MCP servers whose public URL is an API endpoint, not a website).
+     */
+    returnUrl?: string | null;
     purpose?: 'credit_topup';
 }, options?: {
     solvaPay?: SolvaPay;

package/dist/index.js

@@ -635,9 +635,8 @@ function createSolvaPayClient(opts) {
 }
 
 // src/paywall-state.ts
-import { minorUnitsPerMajor } from "@solvapay/core";
+import { creditsToDisplayMinorUnits, minorUnitsPerMajor } from "@solvapay/core";
 var CHECKOUT_SESSION_TTL_MINUTES = 15;
-var DOCS_HINT = "See docs://solvapay/overview.md.";
 function creditSignals(limits) {
   if (!limits) return { isCreditBased: false };
   const creditBalance = limits.balance?.creditBalance ?? limits.creditBalance;
@@ -721,6 +720,24 @@ function formatMinor(amountMinor, currency) {
 function formatCredits(value) {
   return value.toLocaleString("en-US");
 }
+function formatCreditsWithMoney(credits, gate) {
+  const amount = formatCredits(credits);
+  const peg = gate.creditsPerMinorUnit;
+  const currency = gate.currency;
+  const rate = gate.displayExchangeRate;
+  if (peg && peg > 0 && currency && rate != null && rate > 0) {
+    const minor = creditsToDisplayMinorUnits({
+      credits,
+      creditsPerMinorUnit: peg,
+      displayExchangeRate: rate,
+      displayCurrency: currency
+    });
+    if (minor != null) {
+      return `${amount} credits (~${formatMinor(minor, currency)})`;
+    }
+  }
+  return `${amount} credits`;
+}
 function meterLabel(gate) {
   if (!gate.meterName) return "units";
   return gate.meterName.replace(/_/g, " ");
@@ -764,49 +781,51 @@ function buildGateMessage(state, gate) {
       const nextLine = price ? ` The next call is ${price}.` : "";
       const planName = gate.planName ?? "This plan";
       const antiTrap = gate.creditBalance !== void 0 && gate.creditBalance > 0 && (gate.creditsPerCall === void 0 || gate.creditsPerCall === 0) ? ` Adding credits will not help, because ${planName} does not spend them.` : "";
-      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : recoverClause(url, "continue", "checkout");
-      return `${usedLine}${nextLine}${antiTrap}${switchLine} ${DOCS_HINT}`;
+      const switchLine = ladder ? ` Or switch plan: ${ladder}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.` : recoverClause(url, "continue", "checkout");
+      return `${usedLine}${nextLine}${antiTrap}${switchLine}`;
     }
     case "activation_required":
-      return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`. ${DOCS_HINT}`;
+      return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`.`;
     case "topup_required": {
       const balance = gate.creditBalance;
       const cost = gate.creditsPerCall;
       const shortfall = gate.shortfallCredits;
       let lead;
       if (balance !== void 0 && cost !== void 0 && shortfall !== void 0) {
-        lead = `Out of credits for this call. Balance ${formatCredits(balance)} credits; this call costs ${formatCredits(cost)} credits \u2014 ${formatCredits(shortfall)} short.`;
+        lead = `Out of credits for this call. Balance ${formatCreditsWithMoney(balance, gate)}; this call costs ${formatCreditsWithMoney(cost, gate)} \u2014 ${formatCredits(shortfall)} short.`;
       } else {
         lead = "Included usage is exhausted.";
       }
       const topup = recoverClause(url, "add credits", "topup", "Add credits");
-      const auto = autoRechargeDisabled(gate) ? " Auto-recharge is off \u2014 turn it on from the account tool to avoid this next time." : "";
-      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : "";
-      return `${lead}${topup}${auto}${switchLine} ${DOCS_HINT}`;
+      const auto = autoRechargeDisabled(gate) ? ` Auto-recharge is off \u2014 ${callViewer("account")} to turn it on and avoid this next time.` : "";
+      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : hasActivePlan(gate) ? "" : ` Or ${callViewer("checkout")} to pick a plan.`;
+      return `${lead}${topup}${auto}${switchLine}`;
     }
     case "upgrade_required": {
       if (hasActivePlan(gate)) {
         const planName = gate.planName ?? "This plan";
         const lead = `${planName} is active but its included usage is exhausted, and the automatic switch to the next plan did not complete.`;
         if (ladder) {
-          return `${lead} Switch here: ${ladder}. ${DOCS_HINT}`;
+          return `${lead} Switch here: ${ladder}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.`;
         }
-        return `${lead}${recoverClause(url, "switch plan", "checkout")} ${DOCS_HINT}`;
+        return `${lead}${recoverClause(url, "switch plan", "checkout")}`;
       }
       if (ladder) {
-        return `You don't have an active plan for this tool. Pick a plan to use this tool: ${ladder} (links expire in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer("checkout")}. ${DOCS_HINT}`;
+        return `You don't have an active plan for this tool. Pick a plan to use this tool: ${ladder} (links expire in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer("checkout")}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.`;
       }
-      return `You don't have an active plan for this tool.${recoverClause(url, "pick a plan", "checkout")} ${DOCS_HINT}`;
+      return `You don't have an active plan for this tool.${recoverClause(url, "pick a plan", "checkout")}`;
     }
     case "reactivation_required":
-      return `Your previous plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it, or ${callViewer("checkout")} to pick a new plan. ${DOCS_HINT}`;
+      return `Your previous plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it, or ${callViewer("checkout")} to pick a new plan.`;
   }
 }
 function buildNudgeMessage(state, limits) {
   const url = limits?.checkoutUrl && limits.checkoutUrl.length > 0 ? limits.checkoutUrl : null;
   const visitClause = url ? `, or ${namedCheckoutMarkdown(url)}` : "";
-  const remaining = creditSignals(limits).remainingCalls;
-  switch (state.kind) {
+  const signals = creditSignals(limits);
+  const remaining = signals.remainingCalls;
+  const kind = state.kind === "topup_required" && limits && !signals.isCreditBased ? "limit_reached" : state.kind;
+  switch (kind) {
     case "topup_required":
       if (remaining === 0) {
         return `Heads up \u2014 0 calls left \u2014 the next call needs a top-up. ${callViewer("topup").replace(/^c/, "C")} to add more${visitClause}.`;
@@ -891,6 +910,8 @@ function recoveryFields(limits, state) {
     ...signals.creditsPerCall !== void 0 ? { creditsPerCall: signals.creditsPerCall } : {},
     ...signals.shortfallCredits !== void 0 ? { shortfallCredits: signals.shortfallCredits } : {},
     ...signals.remainingCalls !== void 0 ? { remainingCalls: signals.remainingCalls } : {},
+    ...limits.balance?.creditsPerMinorUnit !== void 0 ? { creditsPerMinorUnit: limits.balance.creditsPerMinorUnit } : {},
+    ...limits.balance?.displayExchangeRate !== void 0 ? { displayExchangeRate: limits.balance.displayExchangeRate } : {},
     ...limits.purchaseRef !== void 0 ? { purchaseRef: limits.purchaseRef } : {},
     ...limits.autoRecharge !== void 0 ? { autoRecharge: limits.autoRecharge } : {},
     ...links ? { links } : {}
@@ -1147,6 +1168,23 @@ var SolvaPayPaywall = class {
       console.log(...args);
     }
   }
+  /**
+   * Drop cached limits for `customerRef`. When `product` is omitted every
+   * meter/product entry for that customer is removed. Matches both the
+   * backend `cus_…` ref and an unmapped external ref used as a cache key.
+   */
+  invalidateLimits(customerRef, product) {
+    const aliases = /* @__PURE__ */ new Set([customerRef]);
+    const mapped = this.customerRefMapping.get(customerRef);
+    if (mapped) aliases.add(mapped);
+    if (!customerRef.startsWith("cus_")) aliases.add(`cus_${customerRef}`);
+    for (const key of [...this.limitsCache.keys()]) {
+      const [ref, prod] = key.split(":");
+      if (!ref || !aliases.has(ref)) continue;
+      if (product && prod !== product) continue;
+      this.limitsCache.delete(key);
+    }
+  }
   resolveProduct(metadata) {
     return requireProductRef(metadata.product);
   }
@@ -2167,6 +2205,9 @@ function createSolvaPay(config) {
     paywall: {
       decide(args, metadata, getCustomerRef) {
         return paywall.decide(args, metadata, getCustomerRef);
+      },
+      invalidateLimits(customerRef, product) {
+        paywall.invalidateLimits(customerRef, product);
       }
     },
     // Common API methods exposed directly for convenience
@@ -2235,7 +2276,7 @@ function createSolvaPay(config) {
         customerRef: params.customerRef,
         productRef: params.productRef,
         planRef: params.planRef,
-        returnUrl: params.returnUrl,
+        ...params.returnUrl ? { returnUrl: params.returnUrl } : {},
         ...params.purpose ? { purpose: params.purpose } : {}
       });
     },
@@ -2983,12 +3024,15 @@ async function createCheckoutSessionCore(request, body, options = {}) {
       return customerResult;
     }
     const customerRef = customerResult;
-    let returnUrl = body.returnUrl || options.returnUrl;
-    if (!returnUrl) {
-      try {
-        const url = new URL(request.url);
-        returnUrl = url.origin;
-      } catch {
+    let returnUrl;
+    if (body.returnUrl !== null) {
+      returnUrl = body.returnUrl || options.returnUrl;
+      if (!returnUrl) {
+        try {
+          const url = new URL(request.url);
+          returnUrl = url.origin;
+        } catch {
+        }
       }
     }
     const solvaPay = options.solvaPay || createSolvaPay();
@@ -2996,7 +3040,7 @@ async function createCheckoutSessionCore(request, body, options = {}) {
       productRef: body.productRef,
       customerRef,
       planRef: body.planRef || void 0,
-      returnUrl,
+      ...returnUrl ? { returnUrl } : {},
       ...body.purpose ? { purpose: body.purpose } : {}
     });
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solvapay/server",
-  "version": "2.5.0",
+  "version": "2.6.0-preview-09731417a0a7b4fd3afb4783fdf20b5ad293f63d",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -70,8 +70,8 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "generate:types": "tsx scripts/generate-types.ts",
-    "test": "vitest run __tests__/paywall.unit.test.ts __tests__/paywall-state.unit.test.ts __tests__/paywall-gate.unit.test.ts __tests__/payable-gate.unit.test.ts __tests__/bootstrap-mcp.unit.test.ts __tests__/verify-webhook.unit.test.ts __tests__/edge-exports.unit.test.ts __tests__/credits-usage.unit.test.ts __tests__/limit-outcome-flags.unit.test.ts __tests__/client-error.unit.test.ts src/__tests__/edge-exports.test.ts src/helpers/payment.test.ts src/helpers/usage.test.ts src/resolve-product-ref.test.ts src/verify-product-configuration.test.ts __tests__/auth-core.unit.test.ts __tests__/ensure-customer.unit.test.ts __tests__/create-customer.unit.test.ts __tests__/fetch/cors.test.ts __tests__/fetch/handlers.test.ts __tests__/fetch/utils.test.ts",
-    "test:unit": "vitest run __tests__/paywall.unit.test.ts __tests__/paywall-state.unit.test.ts __tests__/paywall-gate.unit.test.ts __tests__/payable-gate.unit.test.ts __tests__/bootstrap-mcp.unit.test.ts __tests__/verify-webhook.unit.test.ts __tests__/edge-exports.unit.test.ts __tests__/credits-usage.unit.test.ts __tests__/limit-outcome-flags.unit.test.ts __tests__/client-error.unit.test.ts src/__tests__/edge-exports.test.ts src/helpers/payment.test.ts src/helpers/usage.test.ts src/resolve-product-ref.test.ts src/verify-product-configuration.test.ts __tests__/auth-core.unit.test.ts __tests__/ensure-customer.unit.test.ts __tests__/create-customer.unit.test.ts __tests__/fetch/cors.test.ts __tests__/fetch/handlers.test.ts __tests__/fetch/utils.test.ts",
+    "test": "vitest run __tests__/paywall.unit.test.ts __tests__/paywall-state.unit.test.ts __tests__/paywall-gate.unit.test.ts __tests__/payable-gate.unit.test.ts __tests__/bootstrap-mcp.unit.test.ts __tests__/verify-webhook.unit.test.ts __tests__/edge-exports.unit.test.ts __tests__/credits-usage.unit.test.ts __tests__/limit-outcome-flags.unit.test.ts __tests__/client-error.unit.test.ts __tests__/checkout-core.unit.test.ts src/__tests__/edge-exports.test.ts src/helpers/payment.test.ts src/helpers/usage.test.ts src/resolve-product-ref.test.ts src/verify-product-configuration.test.ts __tests__/auth-core.unit.test.ts __tests__/ensure-customer.unit.test.ts __tests__/create-customer.unit.test.ts __tests__/fetch/cors.test.ts __tests__/fetch/handlers.test.ts __tests__/fetch/utils.test.ts",
+    "test:unit": "vitest run __tests__/paywall.unit.test.ts __tests__/paywall-state.unit.test.ts __tests__/paywall-gate.unit.test.ts __tests__/payable-gate.unit.test.ts __tests__/bootstrap-mcp.unit.test.ts __tests__/verify-webhook.unit.test.ts __tests__/edge-exports.unit.test.ts __tests__/credits-usage.unit.test.ts __tests__/limit-outcome-flags.unit.test.ts __tests__/client-error.unit.test.ts __tests__/checkout-core.unit.test.ts src/__tests__/edge-exports.test.ts src/helpers/payment.test.ts src/helpers/usage.test.ts src/resolve-product-ref.test.ts src/verify-product-configuration.test.ts __tests__/auth-core.unit.test.ts __tests__/ensure-customer.unit.test.ts __tests__/create-customer.unit.test.ts __tests__/fetch/cors.test.ts __tests__/fetch/handlers.test.ts __tests__/fetch/utils.test.ts",
     "test:integration": "vitest run --no-file-parallelism __tests__/backend.integration.test.ts __tests__/customer-update.integration.test.ts __tests__/multi-currency-plans.integration.test.ts",
     "test:integration:backend": "vitest run __tests__/backend.integration.test.ts",
     "test:integration:customer": "vitest run __tests__/customer-update.integration.test.ts",