@solvapay/server 2.4.1 → 2.5.0-preview-4dcf60c628500a6210ba69edbf7ae56ee47fbb3a

package/dist/edge.js

@@ -3,6 +3,32 @@ import { SolvaPayError as SolvaPayError7 } from "@solvapay/core";
 
 // src/client.ts
 import { SolvaPayError } from "@solvapay/core";
+var API_ERROR_BODY_MAX = 240;
+function apiDebugLog(...args) {
+  if (process.env.SOLVAPAY_DEBUG === "true") {
+    console.log(...args);
+  }
+}
+function isNonJsonResponseBody(body, contentType) {
+  const ct = contentType?.split(";")[0]?.trim().toLowerCase() ?? "";
+  if (ct.includes("json")) return false;
+  const trimmed = body.trimStart();
+  if (trimmed.startsWith("<")) return true;
+  if (ct && !ct.includes("json")) return true;
+  return false;
+}
+async function throwApiError(operation, res) {
+  const body = await res.text();
+  const contentType = res.headers.get("content-type");
+  const nonJson = isNonJsonResponseBody(body, contentType);
+  const snippet = body.length > API_ERROR_BODY_MAX ? `${body.slice(0, API_ERROR_BODY_MAX)}\u2026` : body;
+  const detail = nonJson ? `non-JSON response (${contentType ?? "unknown content-type"}) \u2014 the API may not have been reached. Body: ${snippet}` : snippet;
+  apiDebugLog(`\u274C API Error: ${res.status} - ${detail}`);
+  throw new SolvaPayError(`${operation} failed (${res.status}): ${detail}`, {
+    status: res.status,
+    code: nonJson ? "non_json_response" : void 0
+  });
+}
 function createSolvaPayClient(opts) {
   const base = opts.apiBaseUrl ?? "https://api.solvapay.com";
   if (!opts.apiKey) throw new SolvaPayError("Missing apiKey");
@@ -10,12 +36,6 @@ function createSolvaPayClient(opts) {
     "Content-Type": "application/json",
     Authorization: `Bearer ${opts.apiKey}`
   };
-  const debug = process.env.SOLVAPAY_DEBUG === "true";
-  const log = (...args) => {
-    if (debug) {
-      console.log(...args);
-    }
-  };
   return {
     // POST: /v1/sdk/limits
     async checkLimits(params) {
@@ -26,11 +46,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(params)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Check limits failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Check limits", res);
       }
       const result = await res.json();
       return result;
@@ -44,11 +60,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(params)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Track usage failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Track usage", res);
       }
       return await res.json();
     },
@@ -61,11 +73,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(params)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Track usage bulk failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Track usage bulk", res);
       }
       return await res.json();
     },
@@ -78,11 +86,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(params)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Create customer failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Create customer", res);
       }
       const result = await res.json();
       return {
@@ -98,11 +102,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(params)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Update customer failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Update customer", res);
       }
       const result = await res.json();
       return {
@@ -130,11 +130,7 @@ function createSolvaPayClient(opts) {
         headers
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Get customer failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Get customer", res);
       }
       const result = await res.json();
       let customer = result;
@@ -168,11 +164,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(body)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Assign credits failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Assign credits", res);
       }
       return await res.json();
     },
@@ -184,11 +176,7 @@ function createSolvaPayClient(opts) {
         headers
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Get merchant failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Get merchant", res);
       }
       return res.json();
     },
@@ -200,11 +188,7 @@ function createSolvaPayClient(opts) {
         headers
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Get platform config failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Get platform config", res);
       }
       return res.json();
     },
@@ -216,11 +200,7 @@ function createSolvaPayClient(opts) {
         headers
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Get product failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Get product", res);
       }
       const result = await res.json();
       const data = result.data || {};
@@ -235,11 +215,7 @@ function createSolvaPayClient(opts) {
         headers
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`List products failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("List products", res);
       }
       const result = await res.json();
       const products = Array.isArray(result) ? result : result.products || [];
@@ -257,11 +233,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(params)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Create product failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Create product", res);
       }
       const result = await res.json();
       return result;
@@ -275,11 +247,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(params)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Bootstrap MCP product failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Bootstrap MCP product", res);
       }
       return await res.json();
     },
@@ -292,11 +260,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(params)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Configure MCP plans failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Configure MCP plans", res);
       }
       return await res.json();
     },
@@ -308,11 +272,7 @@ function createSolvaPayClient(opts) {
         headers
       });
       if (!res.ok && res.status !== 404) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Delete product failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Delete product", res);
       }
     },
     // POST: /v1/sdk/products/{productRef}/clone
@@ -324,11 +284,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(overrides || {})
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Clone product failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Clone product", res);
       }
       return await res.json();
     },
@@ -340,11 +296,7 @@ function createSolvaPayClient(opts) {
         headers
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`List plans failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("List plans", res);
       }
       const result = await res.json();
       const plans = Array.isArray(result) ? result : result.plans || [];
@@ -369,11 +321,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(params)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Create plan failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Create plan", res);
       }
       const result = await res.json();
       return result;
@@ -387,11 +335,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(params)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Update plan failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Update plan", res);
       }
       return await res.json();
     },
@@ -403,11 +347,7 @@ function createSolvaPayClient(opts) {
         headers
       });
       if (!res.ok && res.status !== 404) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Delete plan failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Delete plan", res);
       }
     },
     // POST: /payment-intents
@@ -428,11 +368,7 @@ function createSolvaPayClient(opts) {
         })
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Create payment intent failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Create payment intent", res);
       }
       return await res.json();
     },
@@ -456,11 +392,7 @@ function createSolvaPayClient(opts) {
         })
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Create topup payment intent failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Create topup payment intent", res);
       }
       return await res.json();
     },
@@ -480,11 +412,7 @@ function createSolvaPayClient(opts) {
         })
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Process payment failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Process payment", res);
       }
       const result = await res.json();
       return result;
@@ -505,54 +433,20 @@ function createSolvaPayClient(opts) {
         })
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(
-          `Attach business details failed (${res.status}): ${error}`,
-          { status: res.status }
-        );
-      }
-      return await res.json();
-    },
-    // POST: /v1/sdk/purchases/{purchaseRef}/cancel
-    async cancelPurchase(params) {
-      const url = `${base}/v1/sdk/purchases/${params.purchaseRef}/cancel`;
-      const requestOptions = {
-        method: "POST",
-        headers
-      };
-      if (params.reason) {
-        requestOptions.body = JSON.stringify({ reason: params.reason });
-      }
-      const res = await fetch(url, requestOptions);
-      if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        if (res.status === 404) {
-          throw new SolvaPayError(`Purchase not found: ${error}`, { status: 404 });
-        }
-        if (res.status === 400) {
-          throw new SolvaPayError(
-            `Purchase cannot be cancelled or does not belong to provider: ${error}`,
-            { status: 400 }
-          );
-        }
-        throw new SolvaPayError(`Cancel purchase failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Cancel purchase", res);
       }
       const responseText = await res.text();
       let responseData;
       try {
         responseData = JSON.parse(responseText);
       } catch (parseError) {
-        log(`\u274C Failed to parse response as JSON: ${parseError}`);
+        apiDebugLog(`\u274C Failed to parse response as JSON: ${parseError}`);
         throw new SolvaPayError(
           `Invalid JSON response from cancel purchase endpoint: ${responseText.substring(0, 200)}`
         );
       }
       if (!responseData || typeof responseData !== "object") {
-        log(`\u274C Invalid response structure: ${JSON.stringify(responseData)}`);
+        apiDebugLog(`\u274C Invalid response structure: ${JSON.stringify(responseData)}`);
         throw new SolvaPayError(`Invalid response structure from cancel purchase endpoint`);
       }
       let result;
@@ -564,7 +458,7 @@ function createSolvaPayClient(opts) {
         result = responseData.purchase || responseData;
       }
       if (!result || typeof result !== "object") {
-        log(`\u274C Invalid purchase data in response. Full response:`, responseData);
+        apiDebugLog(`\u274C Invalid purchase data in response. Full response:`, responseData);
         throw new SolvaPayError(`Invalid purchase data in cancel purchase response`);
       }
       return result;
@@ -577,30 +471,20 @@ function createSolvaPayClient(opts) {
         headers
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        if (res.status === 404) {
-          throw new SolvaPayError(`Purchase not found: ${error}`, { status: 404 });
-        }
-        if (res.status === 400) {
-          throw new SolvaPayError(`Purchase cannot be reactivated: ${error}`, { status: 400 });
-        }
-        throw new SolvaPayError(`Reactivate purchase failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Reactivate purchase", res);
       }
       const responseText = await res.text();
       let responseData;
       try {
         responseData = JSON.parse(responseText);
       } catch (parseError) {
-        log(`\u274C Failed to parse response as JSON: ${parseError}`);
+        apiDebugLog(`\u274C Failed to parse response as JSON: ${parseError}`);
         throw new SolvaPayError(
           `Invalid JSON response from reactivate purchase endpoint: ${responseText.substring(0, 200)}`
         );
       }
       if (!responseData || typeof responseData !== "object") {
-        log(`\u274C Invalid response structure: ${JSON.stringify(responseData)}`);
+        apiDebugLog(`\u274C Invalid response structure: ${JSON.stringify(responseData)}`);
         throw new SolvaPayError(`Invalid response structure from reactivate purchase endpoint`);
       }
       let result;
@@ -612,7 +496,7 @@ function createSolvaPayClient(opts) {
         result = responseData.purchase || responseData;
       }
       if (!result || typeof result !== "object") {
-        log(`\u274C Invalid purchase data in response. Full response:`, responseData);
+        apiDebugLog(`\u274C Invalid purchase data in response. Full response:`, responseData);
         throw new SolvaPayError(`Invalid purchase data in reactivate purchase response`);
       }
       return result;
@@ -626,11 +510,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(params)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Get user info failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Get user info", res);
       }
       return await res.json();
     },
@@ -642,11 +522,7 @@ function createSolvaPayClient(opts) {
         headers
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Get customer balance failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Get customer balance", res);
       }
       return await res.json();
     },
@@ -659,11 +535,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(params)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Create checkout session failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Create checkout session", res);
       }
       const result = await res.json();
       return result;
@@ -677,11 +549,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(params)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Create customer session failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Create customer session", res);
       }
       const result = await res.json();
       return result;
@@ -695,11 +563,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(params)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Activate plan failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Activate plan", res);
       }
       return await res.json();
     },
@@ -708,11 +572,7 @@ function createSolvaPayClient(opts) {
       url.searchParams.set("customerRef", params.customerRef);
       const res = await fetch(url.toString(), { method: "GET", headers });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Get payment method failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Get payment method", res);
       }
       return await res.json();
     },
@@ -721,11 +581,7 @@ function createSolvaPayClient(opts) {
       url.searchParams.set("customerRef", params.customerRef);
       const res = await fetch(url.toString(), { method: "GET", headers });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Get auto-recharge failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Get auto-recharge", res);
       }
       return await res.json();
     },
@@ -736,11 +592,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify(params)
       });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Save auto-recharge failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Save auto-recharge", res);
       }
       return await res.json();
     },
@@ -749,11 +601,7 @@ function createSolvaPayClient(opts) {
       url.searchParams.set("customerRef", params.customerRef);
       const res = await fetch(url.toString(), { method: "DELETE", headers });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Disable auto-recharge failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Disable auto-recharge", res);
       }
       return await res.json();
     },
@@ -767,11 +615,7 @@ function createSolvaPayClient(opts) {
       }
       const res = await fetch(url.toString(), { method: "GET", headers });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`List purchases failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("List purchases", res);
       }
       const data = await res.json();
       return { purchases: data.purchases ?? [] };
@@ -782,11 +626,7 @@ function createSolvaPayClient(opts) {
       if (params.limit !== void 0) url.searchParams.set("limit", String(params.limit));
       const res = await fetch(url.toString(), { method: "GET", headers });
       if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Get credit activity failed (${res.status}): ${error}`, {
-          status: res.status
-        });
+        await throwApiError("Get credit activity", res);
       }
       return await res.json();
     }
@@ -819,6 +659,12 @@ async function verifyProductConfiguration(options) {
     };
   } catch (error) {
     const status = error instanceof SolvaPayError2 ? error.status : void 0;
+    const code = error instanceof SolvaPayError2 ? error.code : void 0;
+    if (status === 404 && code === "non_json_response") {
+      throw new Error(
+        `Could not reach ${apiBaseUrl} while verifying SOLVAPAY_PRODUCT_REF "${productRef}": the server returned a non-JSON response (often an offline ngrok tunnel or proxy error page). Check SOLVAPAY_API_BASE_URL and that the API tunnel is running.`
+      );
+    }
     if (status === 404) {
       throw new Error(
         `SOLVAPAY_PRODUCT_REF "${productRef}" does not exist on ${apiBaseUrl}. OAuth dynamic client registration resolves the provider from this ref, so every connection attempt would fail with a 400 "Invalid identifier" and no MCP host could connect. Point SOLVAPAY_PRODUCT_REF at a product that exists on this account (SolvaPay Console \u2192 Products, or \`npx solvapay init\` / \`npx solvapay doctor\`), and check SOLVAPAY_API_BASE_URL is the environment you created the product in.`
@@ -837,46 +683,92 @@ async function verifyProductConfiguration(options) {
 }
 
 // src/paywall-state.ts
+import { 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;
+  const creditsPerCall = limits.balance?.creditsPerUnit ?? limits.creditsPerUnit;
+  const isCreditBased = creditBalance !== void 0 || creditsPerCall !== void 0;
+  const shortfallCredits = creditBalance !== void 0 && creditsPerCall !== void 0 ? Math.max(0, creditsPerCall - creditBalance) : void 0;
+  let remainingCalls;
+  if (limits.balance?.remainingUnits !== void 0) {
+    remainingCalls = limits.balance.remainingUnits;
+  } else if (creditBalance !== void 0 && creditsPerCall !== void 0 && creditsPerCall > 0) {
+    remainingCalls = Math.floor(creditBalance / creditsPerCall);
+  } else if (limits.remaining >= 0) {
+    remainingCalls = limits.remaining;
+  }
+  return { creditBalance, creditsPerCall, shortfallCredits, remainingCalls, isCreditBased };
+}
+function nextActionFor(state) {
+  switch (state.kind) {
+    case "activation_required":
+      return "activate";
+    case "topup_required":
+      return "topup";
+    case "upgrade_required":
+    case "limit_reached":
+      return "checkout";
+    case "reactivation_required":
+      return "account";
+  }
+}
+function activePlanRefOf(limits) {
+  const ref = limits.planRef ?? limits.plan;
+  return ref && ref.length > 0 ? ref : void 0;
+}
 function classifyPaywallState(limits) {
   if (!limits) return { kind: "upgrade_required" };
-  if (limits.activationRequired === true) {
+  if (limits.activationRequired === true || limits.paywallReason === "activation_required") {
     return { kind: "activation_required" };
   }
+  if (limits.paywallReason === "topup_required") {
+    return { kind: "topup_required" };
+  }
   if (limits.needsTopUp === true) {
     return { kind: "topup_required" };
   }
   if (limits.needsUpgrade === true) {
     return { kind: "upgrade_required" };
   }
-  const activePlan = limits.plans?.find((p) => p.reference === limits.plan);
-  const isUsageBased = activePlan?.type === "usage-based" || limits.balance !== void 0;
-  const creditBalance = limits.balance?.creditBalance ?? limits.creditBalance;
-  if (isUsageBased) {
-    if (creditBalance === 0) return { kind: "topup_required" };
-    if (creditBalance === void 0 && limits.remaining === 0) {
+  const signals = creditSignals(limits);
+  if (signals.isCreditBased) {
+    if (signals.creditBalance !== void 0 && signals.creditsPerCall !== void 0 && signals.creditBalance < signals.creditsPerCall) {
+      return { kind: "topup_required" };
+    }
+    if (signals.creditBalance === 0) return { kind: "topup_required" };
+    if (signals.creditsPerCall === void 0 && limits.remaining === 0) {
       return { kind: "topup_required" };
     }
   }
-  if (limits.plan.length > 0 && limits.remaining <= 0) {
+  const activeRef = activePlanRefOf(limits);
+  if ((limits.purchaseRef || activeRef) && limits.remaining <= 0) {
     return { kind: "limit_reached" };
   }
+  if (signals.isCreditBased) return { kind: "topup_required" };
+  if (limits.purchaseRef) return { kind: "limit_reached" };
   return { kind: "upgrade_required" };
 }
 function formatMinor(amountMinor, currency) {
-  const major = amountMinor / 100;
+  const divisor = minorUnitsPerMajor(currency);
+  const major = amountMinor / divisor;
+  const fractionDigits = divisor === 1 ? 0 : 2;
   try {
     return new Intl.NumberFormat("en-US", {
       style: "currency",
       currency: currency.toUpperCase(),
-      minimumFractionDigits: 2,
-      maximumFractionDigits: 2
+      minimumFractionDigits: fractionDigits,
+      maximumFractionDigits: fractionDigits
     }).format(major);
   } catch {
-    return `${currency.toUpperCase()} ${major.toFixed(2)}`;
+    return `${currency.toUpperCase()} ${divisor === 1 ? String(Math.round(major)) : major.toFixed(2)}`;
   }
 }
+function formatCredits(value) {
+  return value.toLocaleString("en-US");
+}
 function meterLabel(gate) {
   if (!gate.meterName) return "units";
   return gate.meterName.replace(/_/g, " ");
@@ -884,6 +776,14 @@ function meterLabel(gate) {
 function namedCheckoutMarkdown(url) {
   return `[Open checkout](${url})`;
 }
+function linkLabel(name) {
+  return name.replace(/([[\]])/g, "\\$1");
+}
+function planLadder(gate) {
+  const linkable = (gate.plans ?? []).filter((p) => typeof p.checkoutUrl === "string" && p.checkoutUrl.length > 0).filter((p) => p.reference !== gate.planRef).sort((a, b) => a.price - b.price).slice(0, 4);
+  if (linkable.length === 0) return null;
+  return linkable.map((p) => `[${linkLabel(p.name ?? p.reference)}](${p.checkoutUrl})`).join(" \xB7 ");
+}
 var VIEWER_TOOL = "account";
 function callViewer(view) {
   return view ? `call the \`${VIEWER_TOOL}\` tool with view: '${view}'` : `call the \`${VIEWER_TOOL}\` tool`;
@@ -894,25 +794,57 @@ function recoverClause(url, verb, view) {
   }
   return ` ${callViewer(view).replace(/^c/, "C")}.`;
 }
+function hasActivePlan(gate) {
+  return Boolean(gate.purchaseRef || gate.planRef && gate.planRef.length > 0);
+}
+function autoRechargeDisabled(gate) {
+  return gate.autoRecharge?.enabled === false;
+}
 function buildGateMessage(state, gate) {
   const url = gate.checkoutUrl && gate.checkoutUrl.length > 0 ? gate.checkoutUrl : null;
+  const ladder = planLadder(gate);
   switch (state.kind) {
     case "limit_reached": {
       const included = gate.included;
       const price = gate.unitPriceMinor != null && gate.currency ? formatMinor(gate.unitPriceMinor, gate.currency) : null;
       const usedLine = included ? `You've used ${included.used} of ${included.total} included ${meterLabel(gate)} this period.` : `You've reached the included usage for this period.`;
       const nextLine = price ? ` The next call is ${price}.` : "";
-      return `${usedLine}${nextLine}${recoverClause(url, "continue", "checkout")} ${DOCS_HINT}`;
+      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}`;
     }
     case "activation_required":
       return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`. ${DOCS_HINT}`;
     case "topup_required": {
-      const currency = gate.currency ?? gate.balance?.currency ?? "USD";
-      const presets = [1e3, 2500, 5e3, 1e4].map((m) => formatMinor(m, currency)).join(" \xB7 ");
-      return `You're out of credits. Top up first (${presets}).${recoverClause(url, "add credits", "topup")} ${DOCS_HINT}`;
-    }
-    case "upgrade_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.`;
+      } else {
+        lead = "Included usage is exhausted.";
+      }
+      const topup = recoverClause(url, "add credits", "topup");
+      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}`;
+    }
+    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}${recoverClause(url, "switch plan", "checkout")} ${DOCS_HINT}`;
+      }
+      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.${recoverClause(url, "pick a plan", "checkout")} ${DOCS_HINT}`;
+    }
     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}`;
   }
@@ -920,11 +852,18 @@ function buildGateMessage(state, gate) {
 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) {
     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}.`;
+      }
       return `Heads up \u2014 running low on credits. ${callViewer("topup").replace(/^c/, "C")} to add more${visitClause}.`;
     case "upgrade_required":
     case "limit_reached":
+      if (remaining === 0) {
+        return `Heads up \u2014 0 calls left \u2014 the next call needs a top-up. ${callViewer("checkout").replace(/^c/, "C")} for more headroom${visitClause}.`;
+      }
       return `Heads up \u2014 approaching your plan's limit this period. ${callViewer("checkout").replace(/^c/, "C")} for more headroom${visitClause}.`;
     case "activation_required":
       return `Heads up \u2014 this plan still needs activation. Call the \`activate_plan\` tool with a \`planRef\`${visitClause}.`;
@@ -940,11 +879,23 @@ function allPaidPlansArePayg(plans) {
   if (paidPlans.length === 0) return false;
   return paidPlans.every((p) => p.type === "usage-based" || p.type === "hybrid");
 }
+function activePlanRefOf2(limits) {
+  const ref = limits.planRef ?? limits.plan;
+  return ref && ref.length > 0 ? ref : void 0;
+}
 function activePlanOf(limits) {
-  if (!limits.plan) return void 0;
-  return limits.plans?.find((p) => p.reference === limits.plan);
+  const ref = activePlanRefOf2(limits);
+  if (!ref) return void 0;
+  return limits.plans?.find((p) => p.reference === ref);
 }
 function includedFromLimits(limits) {
+  if (limits.used !== void 0 && limits.limit !== void 0) {
+    return {
+      total: limits.limit,
+      used: limits.used,
+      remaining: limits.remaining
+    };
+  }
   const total = activePlanOf(limits)?.freeUnits;
   if (total == null || total === 0) return void 0;
   const remaining = limits.remaining;
@@ -954,24 +905,49 @@ function includedFromLimits(limits) {
     remaining
   };
 }
-function recoveryFields(limits) {
+function recoveryLinks(limits) {
+  const links = {};
+  if (limits.checkoutUrl) {
+    if (limits.checkoutUrl.includes("/topup")) {
+      links.topup = limits.checkoutUrl;
+    } else {
+      links.checkout = limits.checkoutUrl;
+    }
+  }
+  if (limits.confirmationUrl) {
+    links.manage = limits.confirmationUrl;
+  }
+  return Object.keys(links).length > 0 ? links : void 0;
+}
+function recoveryFields(limits, state) {
   const plan = activePlanOf(limits);
   const included = includedFromLimits(limits);
-  const creditBalance = limits.balance?.creditBalance ?? limits.creditBalance;
+  const signals = creditSignals(limits);
+  const planRef = activePlanRefOf2(limits);
+  const links = recoveryLinks(limits);
   return {
-    ...limits.plan ? { planRef: limits.plan } : {},
+    ...planRef ? { planRef } : {},
+    ...limits.planName !== void 0 ? { planName: limits.planName } : {},
     ...limits.plans !== void 0 ? { plans: limits.plans } : {},
     ...limits.meterName !== void 0 ? { meterName: limits.meterName } : {},
     ...plan?.perUnitChargeMinor != null ? { unitPriceMinor: plan.perUnitChargeMinor, currency: plan.currency } : limits.currency ? { currency: limits.currency } : {},
     ...included ? { included } : {},
-    ...creditBalance !== void 0 ? { creditBalance } : {}
+    ...signals.creditBalance !== void 0 ? { creditBalance: signals.creditBalance } : {},
+    reason: state.kind,
+    nextAction: nextActionFor(state),
+    ...signals.creditsPerCall !== void 0 ? { creditsPerCall: signals.creditsPerCall } : {},
+    ...signals.shortfallCredits !== void 0 ? { shortfallCredits: signals.shortfallCredits } : {},
+    ...signals.remainingCalls !== void 0 ? { remainingCalls: signals.remainingCalls } : {},
+    ...limits.purchaseRef !== void 0 ? { purchaseRef: limits.purchaseRef } : {},
+    ...limits.autoRecharge !== void 0 ? { autoRecharge: limits.autoRecharge } : {},
+    ...links ? { links } : {}
   };
 }
 function buildPaywallGate(productRef, limits) {
   const checkoutUrl = limits.checkoutUrl;
-  const state = classifyPaywallState({ ...limits, plan: limits.plan ?? "" });
+  const state = classifyPaywallState(limits);
   const useActivationForTopup = !limits.activationRequired && state.kind === "topup_required" && allPaidPlansArePayg(limits.plans);
-  const recovery = recoveryFields(limits);
+  const recovery = recoveryFields(limits, state);
   const preMessage = limits.activationRequired || useActivationForTopup ? {
     kind: "activation_required",
     product: productRef,
@@ -2475,6 +2451,15 @@ async function resolveCustomerRefFromRequest(req, options) {
 }
 
 // src/types/paywall.ts
+var PAYWALL_REASONS = [
+  "activation_required",
+  "topup_required",
+  "payment_required",
+  "upgrade_required",
+  "limit_reached",
+  "reactivation_required"
+];
+var PAYWALL_NEXT_ACTIONS = ["topup", "checkout", "activate", "account"];
 function isPaywallStructuredContent(value) {
   if (typeof value !== "object" || value === null || !("kind" in value)) {
     return false;
@@ -2492,6 +2477,7 @@ var includedSchema = z.object({
 });
 var recoveryFields2 = {
   planRef: z.string().optional(),
+  planName: z.string().optional(),
   plans: z.array(z.record(z.string(), z.unknown())).optional(),
   meterName: z.string().optional(),
   unitPriceMinor: z.number().optional(),
@@ -2499,7 +2485,23 @@ var recoveryFields2 = {
   included: includedSchema.optional(),
   creditBalance: z.number().optional(),
   balance: z.record(z.string(), z.unknown()).optional(),
-  productDetails: z.record(z.string(), z.unknown()).optional()
+  productDetails: z.record(z.string(), z.unknown()).optional(),
+  reason: z.enum(PAYWALL_REASONS).optional(),
+  nextAction: z.enum(PAYWALL_NEXT_ACTIONS).optional(),
+  creditsPerCall: z.number().optional(),
+  shortfallCredits: z.number().optional(),
+  remainingCalls: z.number().optional(),
+  purchaseRef: z.string().optional(),
+  planStatus: z.string().optional(),
+  autoRecharge: z.object({
+    enabled: z.boolean(),
+    status: z.string().optional()
+  }).optional(),
+  links: z.object({
+    topup: z.string().optional(),
+    checkout: z.string().optional(),
+    manage: z.string().optional()
+  }).optional()
 };
 var PaywallStructuredContentSchema = z.discriminatedUnion("kind", [
   z.object({
@@ -3664,6 +3666,7 @@ export {
   createSolvaPay,
   createSolvaPayClient,
   createTopupPaymentIntentCore,
+  creditSignals,
   deriveUsageSnapshot,
   disableAutoRechargeCore,
   getAuthenticatedUserCore,
@@ -3677,8 +3680,11 @@ export {
   handleRouteError,
   isErrorResult,
   isPaywallStructuredContent,
+  linkLabel,
   listPlansCore,
+  nextActionFor,
   paywallErrorToClientPayload,
+  planLadder,
   processPaymentIntentCore,
   processTopupPaymentIntentCore,
   reactivatePurchaseCore,