@solvapay/server 2.3.1 → 2.4.0-preview-11dbbe603cd1b9a44cc41b5eee3686bc4000f97f

package/dist/index.js

@@ -762,6 +762,8 @@ function createSolvaPayClient(opts) {
 }
 
 // src/paywall-state.ts
+var CHECKOUT_SESSION_TTL_MINUTES = 15;
+var DOCS_HINT = "See docs://solvapay/overview.md.";
 function classifyPaywallState(limits) {
   if (!limits) return { kind: "upgrade_required" };
   if (limits.activationRequired === true) {
@@ -782,34 +784,77 @@ function classifyPaywallState(limits) {
       return { kind: "topup_required" };
     }
   }
+  if (limits.plan.length > 0 && limits.remaining <= 0) {
+    return { kind: "limit_reached" };
+  }
   return { kind: "upgrade_required" };
 }
+function formatMinor(amountMinor, currency) {
+  const major = amountMinor / 100;
+  try {
+    return new Intl.NumberFormat("en-US", {
+      style: "currency",
+      currency: currency.toUpperCase(),
+      minimumFractionDigits: 2,
+      maximumFractionDigits: 2
+    }).format(major);
+  } catch {
+    return `${currency.toUpperCase()} ${major.toFixed(2)}`;
+  }
+}
+function meterLabel(gate) {
+  if (!gate.meterName) return "units";
+  return gate.meterName.replace(/_/g, " ");
+}
+function namedCheckoutMarkdown(url) {
+  return `[Open checkout](${url})`;
+}
+var VIEWER_TOOL = "account";
+function callViewer(view) {
+  return view ? `call the \`${VIEWER_TOOL}\` tool with view: '${view}'` : `call the \`${VIEWER_TOOL}\` tool`;
+}
+function recoverClause(url, verb, view) {
+  if (url) {
+    return ` ${namedCheckoutMarkdown(url)} to ${verb} (expires in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer(view)}.`;
+  }
+  return ` ${callViewer(view).replace(/^c/, "C")}.`;
+}
 function buildGateMessage(state, gate) {
   const url = gate.checkoutUrl && gate.checkoutUrl.length > 0 ? gate.checkoutUrl : null;
-  const openClause = url ? `, or open ${url} in a browser` : "";
   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}`;
+    }
     case "activation_required":
-      return `Your plan needs activation before you can use this tool. Call the \`activate_plan\` tool to activate it${openClause}.`;
-    case "topup_required":
-      return `You're out of credits. Call the \`topup\` tool to add more${openClause}.`;
+      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":
-      return `You don't have an active plan for this tool. Call the \`upgrade\` tool to pick a plan${openClause}.`;
+      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. Call the \`manage_account\` tool to reactivate it, or the \`upgrade\` tool to pick a new plan.`;
+      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}`;
   }
 }
 function buildNudgeMessage(state, limits) {
   const url = limits?.checkoutUrl && limits.checkoutUrl.length > 0 ? limits.checkoutUrl : null;
-  const visitClause = url ? `, or visit ${url}` : "";
+  const visitClause = url ? `, or ${namedCheckoutMarkdown(url)}` : "";
   switch (state.kind) {
     case "topup_required":
-      return `Heads up \u2014 running low on credits. Call the \`topup\` tool to add more${visitClause}.`;
+      return `Heads up \u2014 running low on credits. ${callViewer("topup").replace(/^c/, "C")} to add more${visitClause}.`;
     case "upgrade_required":
-      return `Heads up \u2014 approaching your plan's limit this period. Call the \`upgrade\` tool for more headroom${visitClause}.`;
+    case "limit_reached":
+      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${visitClause}.`;
+      return `Heads up \u2014 this plan still needs activation. Call the \`activate_plan\` tool with a \`planRef\`${visitClause}.`;
     case "reactivation_required":
-      return `Heads up \u2014 your plan is no longer active. Call the \`manage_account\` tool to reactivate it${visitClause}.`;
+      return `Heads up \u2014 your plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it${visitClause}.`;
   }
 }
 
@@ -820,26 +865,55 @@ function allPaidPlansArePayg(plans) {
   if (paidPlans.length === 0) return false;
   return paidPlans.every((p) => p.type === "usage-based" || p.type === "hybrid");
 }
+function activePlanOf(limits) {
+  if (!limits.plan) return void 0;
+  return limits.plans?.find((p) => p.reference === limits.plan);
+}
+function includedFromLimits(limits) {
+  const total = activePlanOf(limits)?.freeUnits;
+  if (total == null || total === 0) return void 0;
+  const remaining = limits.remaining;
+  return {
+    total,
+    used: Math.max(0, total - remaining),
+    remaining
+  };
+}
+function recoveryFields(limits) {
+  const plan = activePlanOf(limits);
+  const included = includedFromLimits(limits);
+  const creditBalance = limits.balance?.creditBalance ?? limits.creditBalance;
+  return {
+    ...limits.plan ? { planRef: limits.plan } : {},
+    ...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 } : {}
+  };
+}
 function buildPaywallGate(productRef, limits) {
   const checkoutUrl = limits.checkoutUrl;
   const state = classifyPaywallState({ ...limits, plan: limits.plan ?? "" });
   const useActivationForTopup = !limits.activationRequired && state.kind === "topup_required" && allPaidPlansArePayg(limits.plans);
+  const recovery = recoveryFields(limits);
   const preMessage = limits.activationRequired || useActivationForTopup ? {
     kind: "activation_required",
     product: productRef,
     message: "",
     checkoutUrl: limits.confirmationUrl || checkoutUrl || "",
     ...limits.confirmationUrl !== void 0 ? { confirmationUrl: limits.confirmationUrl } : {},
-    ...limits.plans !== void 0 ? { plans: limits.plans } : {},
     ...limits.balance !== void 0 ? { balance: limits.balance } : {},
-    ...limits.product !== void 0 ? { productDetails: limits.product } : {}
+    ...limits.product !== void 0 ? { productDetails: limits.product } : {},
+    ...recovery
   } : {
     kind: "payment_required",
     product: productRef,
     checkoutUrl: checkoutUrl || "",
     message: "",
     ...limits.balance !== void 0 ? { balance: limits.balance } : {},
-    ...limits.product !== void 0 ? { productDetails: limits.product } : {}
+    ...limits.product !== void 0 ? { productDetails: limits.product } : {},
+    ...recovery
   };
   return { ...preMessage, message: buildGateMessage(state, preMessage) };
 }
@@ -1947,34 +2021,34 @@ function isJsonSchemaObject(value) {
   return Boolean(value && typeof value === "object");
 }
 function toZodSchema(property) {
-  const z = getZod();
+  const z2 = getZod();
   if (Array.isArray(property.enum) && property.enum.length > 0) {
     if (property.enum.every((value) => typeof value === "string")) {
       const [first, ...rest] = property.enum;
-      return z.enum([first, ...rest]);
+      return z2.enum([first, ...rest]);
     }
     if (property.enum.length === 1) {
-      return z.literal(property.enum[0]);
+      return z2.literal(property.enum[0]);
     }
-    return z.union(property.enum.map((value) => z.literal(value)));
+    return z2.union(property.enum.map((value) => z2.literal(value)));
   }
   switch (property.type) {
     case "string":
-      return z.string();
+      return z2.string();
     case "number":
-      return z.number();
+      return z2.number();
     case "integer":
-      return z.number().int();
+      return z2.number().int();
     case "boolean":
-      return z.boolean();
+      return z2.boolean();
     case "array":
-      return z.array(
-        isJsonSchemaObject(property.items) ? toZodSchema(property.items) : z.any()
+      return z2.array(
+        isJsonSchemaObject(property.items) ? toZodSchema(property.items) : z2.any()
       );
     case "object":
-      return z.object(jsonSchemaToZodRawShape(property.properties || {}));
+      return z2.object(jsonSchemaToZodRawShape(property.properties || {}));
     default:
-      return z.any();
+      return z2.any();
   }
 }
 function jsonSchemaToZodRawShape(properties, required = []) {
@@ -2009,12 +2083,12 @@ function registerVirtualToolsMcpImpl(server, apiClient, options) {
     if (filter && !filter(toolDefinition)) continue;
     const mappedDefinition = mapDefinition ? mapDefinition(toolDefinition) : toolDefinition;
     const wrappedHandler = wrapHandler ? wrapHandler(mappedDefinition.handler, mappedDefinition) : mappedDefinition.handler;
-    const z = getZod();
+    const z2 = getZod();
     server.registerTool(
       mappedDefinition.name,
       {
         description: mappedDefinition.description,
-        inputSchema: z.object(
+        inputSchema: z2.object(
           jsonSchemaToZodRawShape(
             mappedDefinition.inputSchema.properties,
             mappedDefinition.inputSchema.required || []
@@ -2337,6 +2411,42 @@ function isPaywallStructuredContent(value) {
   return kind === "payment_required" || kind === "activation_required";
 }
 
+// src/types/paywall-schema.ts
+import { z } from "zod";
+var includedSchema = z.object({
+  total: z.number(),
+  used: z.number(),
+  remaining: z.number()
+});
+var recoveryFields2 = {
+  planRef: z.string().optional(),
+  plans: z.array(z.record(z.string(), z.unknown())).optional(),
+  meterName: z.string().optional(),
+  unitPriceMinor: z.number().optional(),
+  currency: z.string().optional(),
+  included: includedSchema.optional(),
+  creditBalance: z.number().optional(),
+  balance: z.record(z.string(), z.unknown()).optional(),
+  productDetails: z.record(z.string(), z.unknown()).optional()
+};
+var PaywallStructuredContentSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("payment_required"),
+    product: z.string(),
+    checkoutUrl: z.string(),
+    message: z.string(),
+    ...recoveryFields2
+  }),
+  z.object({
+    kind: z.literal("activation_required"),
+    product: z.string(),
+    checkoutUrl: z.string(),
+    message: z.string(),
+    confirmationUrl: z.string().optional(),
+    ...recoveryFields2
+  })
+]);
+
 // src/helpers/error.ts
 import { SolvaPayError as SolvaPayError5 } from "@solvapay/core";
 function isErrorResult(result) {
@@ -3399,6 +3509,7 @@ function verifyWebhook({
 export {
   BALANCE_RECONCILE_DELAYS_MS,
   PaywallError,
+  PaywallStructuredContentSchema,
   TOPUP_BALANCE_POLL_DELAYS_MS,
   VIRTUAL_TOOL_DEFINITIONS,
   activatePlanCore,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solvapay/server",
-  "version": "2.3.1",
+  "version": "2.4.0-preview-11dbbe603cd1b9a44cc41b5eee3686bc4000f97f",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -42,7 +42,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@solvapay/core": "1.6.0"
+    "@solvapay/core": "1.6.0-preview-11dbbe603cd1b9a44cc41b5eee3686bc4000f97f"
   },
   "peerDependencies": {
     "zod": "^4.2.0",