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

package/dist/edge.d.ts

@@ -4085,7 +4085,36 @@ interface PaywallMetadata {
 /**
  * Structured content for paywall errors (MCP structuredContent and manual handling).
  */
-type PaywallStructuredContent = {
+/**
+ * Fields shared by every `PaywallStructuredContent` kind so a text-only
+ * host can recover from a gate without a second tool call. Every field
+ * other than `kind` / `product` / `checkoutUrl` / `message` is omitted
+ * when the backend did not send it — never defaulted.
+ */
+type PaywallGateRecoveryFields = {
+    /** Active plan reference from `limits.plan`. */
+    planRef?: string;
+    /** Product plans from `checkLimits` (activation already had this). */
+    plans?: LimitPlanSummary[];
+    /** Meter the gated call was charged against. */
+    meterName?: string;
+    /** Per-unit charge of the active plan, in minor currency units. */
+    unitPriceMinor?: number;
+    /** ISO 4217 currency for `unitPriceMinor`. */
+    currency?: string;
+    /**
+     * Included-usage counters. Omitted when `freeUnits` is absent or `0`
+     * (the unlimited sentinel) so we never emit misleading zeros.
+     */
+    included?: {
+        total: number;
+        used: number;
+        remaining: number;
+    };
+    /** Prepaid credit balance, coalesced from nested or top-level fields. */
+    creditBalance?: number;
+};
+type PaywallStructuredContent = ({
     kind: 'payment_required';
     /** Product ref from paywall metadata (or env default) */
     product: string;
@@ -4100,7 +4129,7 @@ type PaywallStructuredContent = {
     balance?: LimitActivationBalance;
     /** Rich product context from checkLimits (name, ref, provider slug/id) */
     productDetails?: LimitActivationProduct;
-} | {
+} & PaywallGateRecoveryFields) | ({
     kind: 'activation_required';
     /** Product ref from paywall metadata (or env default) */
     product: string;
@@ -4110,11 +4139,10 @@ type PaywallStructuredContent = {
      */
     checkoutUrl: string;
     confirmationUrl?: string;
-    plans?: LimitPlanSummary[];
     balance?: LimitActivationBalance;
     /** Rich product context from checkLimits (name, ref, provider slug/id) */
     productDetails?: LimitActivationProduct;
-};
+} & PaywallGateRecoveryFields);
 /**
  * Runtime type guard for `PaywallStructuredContent`.
  *
@@ -5281,6 +5309,8 @@ type PaywallState = {
     kind: 'topup_required';
 } | {
     kind: 'upgrade_required';
+} | {
+    kind: 'limit_reached';
 } | {
     kind: 'reactivation_required';
 };
@@ -5302,10 +5332,12 @@ type PaywallState = {
  *     `creditBalance === 0` field, or `remaining === 0` as a
  *     fallback for older backend responses that omit both credit
  *     fields on usage-based plans.
- *  4. Everything else → `upgrade_required`, including:
+ *  4. Active plan at included cap (`plan` is a non-empty ref and
+ *     `remaining <= 0`) → `limit_reached`. This is the "on Free, used
+ *     3 of 3" case — not "no plan".
+ *  5. Everything else → `upgrade_required`, including:
  *     - `limits === null` (defensive),
- *     - no active plan on the product,
- *     - recurring plan at period cap (`remaining <= 0`).
+ *     - no active plan on the product.
  *
  * `reactivation_required` is deferred — it needs a distinct backend
  * signal (future `LimitResponse.inactivePurchaseRef`) which isn't
@@ -5315,12 +5347,13 @@ type PaywallState = {
  */
 declare function classifyPaywallState(limits: LimitResponseWithPlan | null): PaywallState;
 /**
- * Produce the terminal-friendly gate message. Names exactly one
- * recovery tool (`upgrade` / `topup` / `activate_plan`), except for
- * the rare `reactivation_required` path which names two alternatives
- * (`manage_account` / `upgrade`). Inlines `gate.checkoutUrl` when
- * present so terminal-only MCP hosts (Claude Code, CLI clients) can
- * open a browser directly.
+ * Produce the terminal-friendly gate message. Names the `account`
+ * viewer (with a `view` hint when the landing screen matters) or
+ * `activate_plan` when a specific plan needs activating. Inlines
+ * `gate.checkoutUrl` when present so terminal-only MCP hosts (Claude
+ * Code, CLI clients) can open a browser directly. States the
+ * 15-minute session lifetime inline — the URL is a bearer credential,
+ * not a durable link.
  *
  * Kept as a pure string so the adapter layer can concatenate it with
  * an optional narrator prefix without parsing structured copy.
@@ -5333,10 +5366,10 @@ declare function buildGateMessage(state: PaywallState, gate: PaywallStructuredCo
  * like a softer version of the same text-only nudge path.
  *
  * Receives the `PaywallState` the classifier would have produced if
- * the customer had tripped the gate. `upgrade_required` and
- * `topup_required` are the only kinds that currently produce nudge
- * copy; the others are no-ops (shouldn't happen — nudges only fire
- * on successful calls).
+ * the customer had tripped the gate. `upgrade_required`,
+ * `limit_reached`, and `topup_required` are the kinds that currently
+ * produce nudge copy; the others are no-ops (shouldn't happen —
+ * nudges only fire on successful calls).
  */
 declare function buildNudgeMessage(state: PaywallState, limits: LimitResponseWithPlan | null): string;
 

package/dist/edge.js

@@ -804,6 +804,8 @@ async function verifyProductConfiguration(options) {
 }
 
 // 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) {
@@ -824,34 +826,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}.`;
   }
 }
 
@@ -862,26 +907,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) };
 }

package/dist/fetch/index.cjs

@@ -965,6 +965,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) {
@@ -985,20 +987,62 @@ 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}`;
   }
 }
 
@@ -1009,26 +1053,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) };
 }

package/dist/fetch/index.js

@@ -912,6 +912,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) {
@@ -932,20 +934,62 @@ 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}`;
   }
 }
 
@@ -956,26 +1000,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) };
 }