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

package/dist/index.cjs

@@ -32,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   BALANCE_RECONCILE_DELAYS_MS: () => BALANCE_RECONCILE_DELAYS_MS,
   PaywallError: () => PaywallError,
+  PaywallStructuredContentSchema: () => PaywallStructuredContentSchema,
   TOPUP_BALANCE_POLL_DELAYS_MS: () => TOPUP_BALANCE_POLL_DELAYS_MS,
   VIRTUAL_TOOL_DEFINITIONS: () => VIRTUAL_TOOL_DEFINITIONS,
   activatePlanCore: () => activatePlanCore,
@@ -840,6 +841,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) {
@@ -860,34 +863,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}.`;
   }
 }
 
@@ -898,26 +944,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) };
 }
@@ -2025,34 +2100,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 = []) {
@@ -2087,12 +2162,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 || []
@@ -2415,6 +2490,42 @@ function isPaywallStructuredContent(value) {
   return kind === "payment_required" || kind === "activation_required";
 }
 
+// src/types/paywall-schema.ts
+var import_zod = require("zod");
+var includedSchema = import_zod.z.object({
+  total: import_zod.z.number(),
+  used: import_zod.z.number(),
+  remaining: import_zod.z.number()
+});
+var recoveryFields2 = {
+  planRef: import_zod.z.string().optional(),
+  plans: import_zod.z.array(import_zod.z.record(import_zod.z.string(), import_zod.z.unknown())).optional(),
+  meterName: import_zod.z.string().optional(),
+  unitPriceMinor: import_zod.z.number().optional(),
+  currency: import_zod.z.string().optional(),
+  included: includedSchema.optional(),
+  creditBalance: import_zod.z.number().optional(),
+  balance: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional(),
+  productDetails: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional()
+};
+var PaywallStructuredContentSchema = import_zod.z.discriminatedUnion("kind", [
+  import_zod.z.object({
+    kind: import_zod.z.literal("payment_required"),
+    product: import_zod.z.string(),
+    checkoutUrl: import_zod.z.string(),
+    message: import_zod.z.string(),
+    ...recoveryFields2
+  }),
+  import_zod.z.object({
+    kind: import_zod.z.literal("activation_required"),
+    product: import_zod.z.string(),
+    checkoutUrl: import_zod.z.string(),
+    message: import_zod.z.string(),
+    confirmationUrl: import_zod.z.string().optional(),
+    ...recoveryFields2
+  })
+]);
+
 // src/helpers/error.ts
 var import_core5 = require("@solvapay/core");
 function isErrorResult(result) {
@@ -3476,6 +3587,7 @@ function verifyWebhook({
 0 && (module.exports = {
   BALANCE_RECONCILE_DELAYS_MS,
   PaywallError,
+  PaywallStructuredContentSchema,
   TOPUP_BALANCE_POLL_DELAYS_MS,
   VIRTUAL_TOOL_DEFINITIONS,
   activatePlanCore,

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 import { BusinessDetailsInput, TaxBreakdown } from '@solvapay/core';
 
 interface components {
@@ -4097,7 +4098,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;
@@ -4112,7 +4142,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;
@@ -4122,11 +4152,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`.
  *
@@ -5341,6 +5370,52 @@ type LimitsLike = Omit<LimitResponseWithPlan, 'plan'> & {
 };
 declare function buildPaywallGate(productRef: string, limits: LimitsLike): PaywallStructuredContent;
 
+/**
+ * Zod schemas for `PaywallStructuredContent`. Declared so MCP hosts can
+ * hydrate `structuredContent` and so we fail loud when a required field
+ * the narrator claims to print is missing. Every recovery field is
+ * optional — a default here would invent data the backend did not send.
+ */
+
+declare const PaywallStructuredContentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    planRef: z.ZodOptional<z.ZodString>;
+    plans: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    meterName: z.ZodOptional<z.ZodString>;
+    unitPriceMinor: z.ZodOptional<z.ZodNumber>;
+    currency: z.ZodOptional<z.ZodString>;
+    included: z.ZodOptional<z.ZodObject<{
+        total: z.ZodNumber;
+        used: z.ZodNumber;
+        remaining: z.ZodNumber;
+    }, z.core.$strip>>;
+    creditBalance: z.ZodOptional<z.ZodNumber>;
+    balance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    productDetails: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    kind: z.ZodLiteral<"payment_required">;
+    product: z.ZodString;
+    checkoutUrl: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    planRef: z.ZodOptional<z.ZodString>;
+    plans: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    meterName: z.ZodOptional<z.ZodString>;
+    unitPriceMinor: z.ZodOptional<z.ZodNumber>;
+    currency: z.ZodOptional<z.ZodString>;
+    included: z.ZodOptional<z.ZodObject<{
+        total: z.ZodNumber;
+        used: z.ZodNumber;
+        remaining: z.ZodNumber;
+    }, z.core.$strip>>;
+    creditBalance: z.ZodOptional<z.ZodNumber>;
+    balance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    productDetails: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    kind: z.ZodLiteral<"activation_required">;
+    product: z.ZodString;
+    checkoutUrl: z.ZodString;
+    message: z.ZodString;
+    confirmationUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "kind">;
+
 /**
  * Pure state engine that classifies a `LimitResponseWithPlan` into a
  * recovery-tool-specific `PaywallState`, and produces the human-readable
@@ -5366,6 +5441,8 @@ type PaywallState = {
     kind: 'topup_required';
 } | {
     kind: 'upgrade_required';
+} | {
+    kind: 'limit_reached';
 } | {
     kind: 'reactivation_required';
 };
@@ -5387,10 +5464,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
@@ -5400,12 +5479,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.
@@ -5418,10 +5498,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;
 
@@ -6154,4 +6234,4 @@ declare function verifyWebhook({ body, signature, secret, }: {
     secret: string;
 }): WebhookEvent;
 
-export { type ActivatePlanResult, type AssignCreditsRequest, type AssignCreditsResponse, type AttachBusinessDetailsParams, type AttachBusinessDetailsResult, type AuthenticatedUser, type AutoRechargeConfig, type AutoRechargeDisplayBlock, type AutoRechargeInput, type AutoRechargeResponse, BALANCE_RECONCILE_DELAYS_MS, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CreditDebitResult, type CreditDebitSkipReason, type CreditDisplayBlock, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type GetUsageResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type LimitResponseWithPlan, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableAllowResult, type PayableFunction, type PayableGateOptions, type PayableGateResult, type PayableOptions, type PayablePaywallResult, type PaymentMethodInfo, type PaywallArgs, type PaywallDecision, PaywallError, type PaywallMetadata, type PaywallState, type PaywallStructuredContent, type ProcessPaymentResult, type ProductConfigurationStatus, type ProtectHandlerContext, type PurchaseCheckResult, type PurchaseInfo, type RegisterVirtualToolsMcpOptions, type RetryOptions, type SaveAutoRechargeInput, type SaveAutoRechargeResponse, type SdkMerchantResponse, type SdkProductResponse, type ServerClientOptions, type SolvaPay, type SolvaPayClient, TOPUP_BALANCE_POLL_DELAYS_MS, type ToolPlanMappingInput, type TopupProcessResult, type TrackUsageBulkRequest, type TrackUsageBulkResponse, type TrackUsageRequest, type TrackUsageResponse, VIRTUAL_TOOL_DEFINITIONS, type VerifyProductConfigurationOptions, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, attachBusinessDetailsCore, buildGateMessage, buildNudgeMessage, buildPaywallGate, cancelPurchaseCore, checkLimitsCore, checkPurchaseCore, classifyPaywallState, type components, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, createVirtualTools, disableAutoRechargeCore, getAuthenticatedUserCore, getAutoRechargeCore, getCustomerBalanceCore, getMerchantCore, getPaymentMethodCore, getProductCore, getUsageCore, handleRouteError, isErrorResult, isPaywallStructuredContent, jsonSchemaToZodRawShape, listPlansCore, paywallErrorToClientPayload, pollBalanceUntilIncreased, processPaymentIntentCore, processTopupPaymentIntentCore, reactivatePurchaseCore, registerVirtualToolsMcpImpl, saveAutoRechargeCore, syncCustomerCore, trackUsageCore, verifyProductConfiguration, verifyWebhook, withRetry };
+export { type ActivatePlanResult, type AssignCreditsRequest, type AssignCreditsResponse, type AttachBusinessDetailsParams, type AttachBusinessDetailsResult, type AuthenticatedUser, type AutoRechargeConfig, type AutoRechargeDisplayBlock, type AutoRechargeInput, type AutoRechargeResponse, BALANCE_RECONCILE_DELAYS_MS, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CreditDebitResult, type CreditDebitSkipReason, type CreditDisplayBlock, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type GetUsageResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type LimitResponseWithPlan, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableAllowResult, type PayableFunction, type PayableGateOptions, type PayableGateResult, type PayableOptions, type PayablePaywallResult, type PaymentMethodInfo, type PaywallArgs, type PaywallDecision, PaywallError, type PaywallGateRecoveryFields, type PaywallMetadata, type PaywallState, type PaywallStructuredContent, PaywallStructuredContentSchema, type ProcessPaymentResult, type ProductConfigurationStatus, type ProtectHandlerContext, type PurchaseCheckResult, type PurchaseInfo, type RegisterVirtualToolsMcpOptions, type RetryOptions, type SaveAutoRechargeInput, type SaveAutoRechargeResponse, type SdkMerchantResponse, type SdkProductResponse, type ServerClientOptions, type SolvaPay, type SolvaPayClient, TOPUP_BALANCE_POLL_DELAYS_MS, type ToolPlanMappingInput, type TopupProcessResult, type TrackUsageBulkRequest, type TrackUsageBulkResponse, type TrackUsageRequest, type TrackUsageResponse, VIRTUAL_TOOL_DEFINITIONS, type VerifyProductConfigurationOptions, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, attachBusinessDetailsCore, buildGateMessage, buildNudgeMessage, buildPaywallGate, cancelPurchaseCore, checkLimitsCore, checkPurchaseCore, classifyPaywallState, type components, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, createVirtualTools, disableAutoRechargeCore, getAuthenticatedUserCore, getAutoRechargeCore, getCustomerBalanceCore, getMerchantCore, getPaymentMethodCore, getProductCore, getUsageCore, handleRouteError, isErrorResult, isPaywallStructuredContent, jsonSchemaToZodRawShape, listPlansCore, paywallErrorToClientPayload, pollBalanceUntilIncreased, processPaymentIntentCore, processTopupPaymentIntentCore, reactivatePurchaseCore, registerVirtualToolsMcpImpl, saveAutoRechargeCore, syncCustomerCore, trackUsageCore, verifyProductConfiguration, verifyWebhook, withRetry };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 import { BusinessDetailsInput, TaxBreakdown } from '@solvapay/core';
 
 interface components {
@@ -4097,7 +4098,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;
@@ -4112,7 +4142,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;
@@ -4122,11 +4152,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`.
  *
@@ -5341,6 +5370,52 @@ type LimitsLike = Omit<LimitResponseWithPlan, 'plan'> & {
 };
 declare function buildPaywallGate(productRef: string, limits: LimitsLike): PaywallStructuredContent;
 
+/**
+ * Zod schemas for `PaywallStructuredContent`. Declared so MCP hosts can
+ * hydrate `structuredContent` and so we fail loud when a required field
+ * the narrator claims to print is missing. Every recovery field is
+ * optional — a default here would invent data the backend did not send.
+ */
+
+declare const PaywallStructuredContentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    planRef: z.ZodOptional<z.ZodString>;
+    plans: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    meterName: z.ZodOptional<z.ZodString>;
+    unitPriceMinor: z.ZodOptional<z.ZodNumber>;
+    currency: z.ZodOptional<z.ZodString>;
+    included: z.ZodOptional<z.ZodObject<{
+        total: z.ZodNumber;
+        used: z.ZodNumber;
+        remaining: z.ZodNumber;
+    }, z.core.$strip>>;
+    creditBalance: z.ZodOptional<z.ZodNumber>;
+    balance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    productDetails: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    kind: z.ZodLiteral<"payment_required">;
+    product: z.ZodString;
+    checkoutUrl: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    planRef: z.ZodOptional<z.ZodString>;
+    plans: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    meterName: z.ZodOptional<z.ZodString>;
+    unitPriceMinor: z.ZodOptional<z.ZodNumber>;
+    currency: z.ZodOptional<z.ZodString>;
+    included: z.ZodOptional<z.ZodObject<{
+        total: z.ZodNumber;
+        used: z.ZodNumber;
+        remaining: z.ZodNumber;
+    }, z.core.$strip>>;
+    creditBalance: z.ZodOptional<z.ZodNumber>;
+    balance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    productDetails: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    kind: z.ZodLiteral<"activation_required">;
+    product: z.ZodString;
+    checkoutUrl: z.ZodString;
+    message: z.ZodString;
+    confirmationUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "kind">;
+
 /**
  * Pure state engine that classifies a `LimitResponseWithPlan` into a
  * recovery-tool-specific `PaywallState`, and produces the human-readable
@@ -5366,6 +5441,8 @@ type PaywallState = {
     kind: 'topup_required';
 } | {
     kind: 'upgrade_required';
+} | {
+    kind: 'limit_reached';
 } | {
     kind: 'reactivation_required';
 };
@@ -5387,10 +5464,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
@@ -5400,12 +5479,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.
@@ -5418,10 +5498,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;
 
@@ -6154,4 +6234,4 @@ declare function verifyWebhook({ body, signature, secret, }: {
     secret: string;
 }): WebhookEvent;
 
-export { type ActivatePlanResult, type AssignCreditsRequest, type AssignCreditsResponse, type AttachBusinessDetailsParams, type AttachBusinessDetailsResult, type AuthenticatedUser, type AutoRechargeConfig, type AutoRechargeDisplayBlock, type AutoRechargeInput, type AutoRechargeResponse, BALANCE_RECONCILE_DELAYS_MS, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CreditDebitResult, type CreditDebitSkipReason, type CreditDisplayBlock, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type GetUsageResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type LimitResponseWithPlan, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableAllowResult, type PayableFunction, type PayableGateOptions, type PayableGateResult, type PayableOptions, type PayablePaywallResult, type PaymentMethodInfo, type PaywallArgs, type PaywallDecision, PaywallError, type PaywallMetadata, type PaywallState, type PaywallStructuredContent, type ProcessPaymentResult, type ProductConfigurationStatus, type ProtectHandlerContext, type PurchaseCheckResult, type PurchaseInfo, type RegisterVirtualToolsMcpOptions, type RetryOptions, type SaveAutoRechargeInput, type SaveAutoRechargeResponse, type SdkMerchantResponse, type SdkProductResponse, type ServerClientOptions, type SolvaPay, type SolvaPayClient, TOPUP_BALANCE_POLL_DELAYS_MS, type ToolPlanMappingInput, type TopupProcessResult, type TrackUsageBulkRequest, type TrackUsageBulkResponse, type TrackUsageRequest, type TrackUsageResponse, VIRTUAL_TOOL_DEFINITIONS, type VerifyProductConfigurationOptions, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, attachBusinessDetailsCore, buildGateMessage, buildNudgeMessage, buildPaywallGate, cancelPurchaseCore, checkLimitsCore, checkPurchaseCore, classifyPaywallState, type components, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, createVirtualTools, disableAutoRechargeCore, getAuthenticatedUserCore, getAutoRechargeCore, getCustomerBalanceCore, getMerchantCore, getPaymentMethodCore, getProductCore, getUsageCore, handleRouteError, isErrorResult, isPaywallStructuredContent, jsonSchemaToZodRawShape, listPlansCore, paywallErrorToClientPayload, pollBalanceUntilIncreased, processPaymentIntentCore, processTopupPaymentIntentCore, reactivatePurchaseCore, registerVirtualToolsMcpImpl, saveAutoRechargeCore, syncCustomerCore, trackUsageCore, verifyProductConfiguration, verifyWebhook, withRetry };
+export { type ActivatePlanResult, type AssignCreditsRequest, type AssignCreditsResponse, type AttachBusinessDetailsParams, type AttachBusinessDetailsResult, type AuthenticatedUser, type AutoRechargeConfig, type AutoRechargeDisplayBlock, type AutoRechargeInput, type AutoRechargeResponse, BALANCE_RECONCILE_DELAYS_MS, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CreditDebitResult, type CreditDebitSkipReason, type CreditDisplayBlock, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type GetUsageResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type LimitResponseWithPlan, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableAllowResult, type PayableFunction, type PayableGateOptions, type PayableGateResult, type PayableOptions, type PayablePaywallResult, type PaymentMethodInfo, type PaywallArgs, type PaywallDecision, PaywallError, type PaywallGateRecoveryFields, type PaywallMetadata, type PaywallState, type PaywallStructuredContent, PaywallStructuredContentSchema, type ProcessPaymentResult, type ProductConfigurationStatus, type ProtectHandlerContext, type PurchaseCheckResult, type PurchaseInfo, type RegisterVirtualToolsMcpOptions, type RetryOptions, type SaveAutoRechargeInput, type SaveAutoRechargeResponse, type SdkMerchantResponse, type SdkProductResponse, type ServerClientOptions, type SolvaPay, type SolvaPayClient, TOPUP_BALANCE_POLL_DELAYS_MS, type ToolPlanMappingInput, type TopupProcessResult, type TrackUsageBulkRequest, type TrackUsageBulkResponse, type TrackUsageRequest, type TrackUsageResponse, VIRTUAL_TOOL_DEFINITIONS, type VerifyProductConfigurationOptions, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, attachBusinessDetailsCore, buildGateMessage, buildNudgeMessage, buildPaywallGate, cancelPurchaseCore, checkLimitsCore, checkPurchaseCore, classifyPaywallState, type components, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, createVirtualTools, disableAutoRechargeCore, getAuthenticatedUserCore, getAutoRechargeCore, getCustomerBalanceCore, getMerchantCore, getPaymentMethodCore, getProductCore, getUsageCore, handleRouteError, isErrorResult, isPaywallStructuredContent, jsonSchemaToZodRawShape, listPlansCore, paywallErrorToClientPayload, pollBalanceUntilIncreased, processPaymentIntentCore, processTopupPaymentIntentCore, reactivatePurchaseCore, registerVirtualToolsMcpImpl, saveAutoRechargeCore, syncCustomerCore, trackUsageCore, verifyProductConfiguration, verifyWebhook, withRetry };