@solvapay/server 2.7.0 → 2.8.0

package/dist/index.cjs

@@ -85,7 +85,7 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 var import_node_crypto = __toESM(require("crypto"), 1);
-var import_core13 = require("@solvapay/core");
+var import_core14 = require("@solvapay/core");
 
 // src/client.ts
 var import_core = require("@solvapay/core");
@@ -760,6 +760,9 @@ function classifyPaywallState(limits) {
   if (limits.activationRequired === true || limits.paywallReason === "activation_required") {
     return { kind: "activation_required" };
   }
+  if (limits.paywallReason === "limit_reached") {
+    return { kind: "limit_reached" };
+  }
   if (limits.paywallReason === "topup_required") {
     return { kind: "topup_required" };
   }
@@ -823,9 +826,12 @@ function formatCreditsWithMoney(credits, gate) {
   }
   return `${amount} credits`;
 }
+function isFreeMeter(name) {
+  return typeof name === "string" && name.startsWith("free-");
+}
 function meterLabel(gate) {
   if (!gate.meterName) return "units";
-  return gate.meterName.replace(/_/g, " ");
+  return gate.meterName.replace(/[_-]/g, " ");
 }
 function namedCheckoutMarkdown(url, label = "Open checkout") {
   return `[${label}](${url})`;
@@ -861,6 +867,12 @@ function buildGateMessage(state, gate) {
   switch (state.kind) {
     case "limit_reached": {
       const included = gate.included;
+      if (isFreeMeter(gate.meterName)) {
+        const total = included?.total;
+        const usedLine2 = total !== void 0 ? `You've used all ${total} ${meterLabel(gate)} for this period.` : `You've used all ${meterLabel(gate)} for this period.`;
+        const switchLine2 = ladder ? ` Pick a plan to keep going: ${ladder}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.` : recoverClause(url, "keep going", "checkout");
+        return `${usedLine2}${switchLine2}`;
+      }
       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}.` : "";
@@ -1187,6 +1199,7 @@ function createRequestDeduplicator(options = {}) {
 }
 
 // src/paywall.ts
+var import_core4 = require("@solvapay/core");
 var PaywallError = class extends Error {
   /**
    * Creates a new PaywallError instance.
@@ -1237,6 +1250,15 @@ var sharedLimitsFetchDeduplicator = createRequestDeduplicator({
 });
 var sharedLimitsFetchClaims = /* @__PURE__ */ new Map();
 var EXTRA_FORWARD_KEY = "__solvapayExtra";
+function trackUsageExtra(metadata, outcome, consequence) {
+  if (metadata.freeLimit) {
+    return { meterName: metadata.freeLimit.meter };
+  }
+  if (outcome === "success") {
+    return { usageClass: consequence === "overage" ? "overage" : "included" };
+  }
+  return void 0;
+}
 var SolvaPayPaywall = class {
   constructor(apiClient, options = {}) {
     this.apiClient = apiClient;
@@ -1296,10 +1318,19 @@ var SolvaPayPaywall = class {
    */
   async decide(args, metadata = {}, getCustomerRef) {
     const product = this.resolveProduct(metadata);
-    const usageType = metadata.meterName || metadata.usageType || "requests";
+    const usageType = metadata.freeLimit?.meter || metadata.meterName || metadata.usageType || "requests";
     const requestId = this.generateRequestId();
     const startTime = Date.now();
     const inputCustomerRef = getCustomerRef ? getCustomerRef(args) : args.auth?.customer_ref || "anonymous";
+    if (metadata.freeLimit) {
+      const resolved = typeof inputCustomerRef === "string" ? inputCustomerRef.trim() : "";
+      if (!resolved || resolved === "anonymous") {
+        throw new import_core4.SolvaPayError("identity required", {
+          status: 401,
+          code: "identity_required"
+        });
+      }
+    }
     let backendCustomerRef;
     if (inputCustomerRef.startsWith("cus_")) {
       backendCustomerRef = inputCustomerRef;
@@ -1350,7 +1381,8 @@ var SolvaPayPaywall = class {
             // `checkLimitsCore`, which powers the React `useLimits` hook)
             // leave this unset and the backend skips the session-creation
             // side effect.
-            includeCheckoutSession: true
+            includeCheckoutSession: true,
+            ...metadata.freeLimit ? { freeAllowance: metadata.freeLimit } : {}
           });
         }
       );
@@ -1394,7 +1426,8 @@ var SolvaPayPaywall = class {
         "paywall",
         requestId,
         latencyMs,
-        metadata.toolName
+        metadata.toolName,
+        metadata.freeLimit ? { meterName: metadata.freeLimit.meter } : void 0
       ).catch(() => void 0);
       const gate = buildPaywallGate(
         product,
@@ -1441,7 +1474,7 @@ var SolvaPayPaywall = class {
    */
   async runAllow(decision, handler, metadata, args) {
     const product = this.resolveProduct(metadata);
-    const usageType = metadata.meterName || metadata.usageType || "requests";
+    const usageType = metadata.freeLimit?.meter || metadata.meterName || metadata.usageType || "requests";
     const requestId = decision.requestId;
     const startTime = Date.now();
     const forwardedExtra = args[EXTRA_FORWARD_KEY];
@@ -1460,7 +1493,8 @@ var SolvaPayPaywall = class {
         "success",
         requestId,
         latencyMs,
-        metadata.toolName
+        metadata.toolName,
+        trackUsageExtra(metadata, "success", decision.consequence)
       ).catch(() => void 0);
       return result;
     } catch (error) {
@@ -1479,7 +1513,8 @@ var SolvaPayPaywall = class {
           "fail",
           requestId,
           latencyMs,
-          metadata.toolName
+          metadata.toolName,
+          trackUsageExtra(metadata, "fail")
         ).catch(() => void 0);
       }
       throw error;
@@ -1670,7 +1705,7 @@ var SolvaPayPaywall = class {
     }
     return backendRef;
   }
-  async trackUsage(customerRef, productRef, action, outcome, requestId, actionDuration, toolName) {
+  async trackUsage(customerRef, productRef, action, outcome, requestId, actionDuration, toolName, extra) {
     await withRetry(
       () => this.apiClient.trackUsage({
         customerRef,
@@ -1683,7 +1718,9 @@ var SolvaPayPaywall = class {
         metadata: {
           action: action || "api_requests",
           requestId,
-          ...toolName ? { toolName } : {}
+          ...toolName ? { toolName } : {},
+          ...extra?.meterName ? { meterName: extra.meterName } : {},
+          ...extra?.usageClass ? { usageClass: extra.usageClass } : {}
         },
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       }),
@@ -2023,7 +2060,7 @@ var McpAdapter = class {
 };
 
 // src/factory.ts
-var import_core4 = require("@solvapay/core");
+var import_core5 = require("@solvapay/core");
 
 // src/virtual-tools.ts
 var TOOL_GET_USER_INFO = {
@@ -2265,7 +2302,7 @@ function registerVirtualToolsMcpImpl(server, apiClient, options) {
 function createSolvaPay(config) {
   let resolvedConfig;
   if (!config) {
-    const envConfig = (0, import_core4.getSolvaPayConfig)();
+    const envConfig = (0, import_core5.getSolvaPayConfig)();
     resolvedConfig = {
       apiKey: envConfig.apiKey,
       apiBaseUrl: envConfig.apiBaseUrl
@@ -2301,25 +2338,25 @@ function createSolvaPay(config) {
     },
     createPaymentIntent(params) {
       if (!apiClient.createPaymentIntent) {
-        throw new import_core4.SolvaPayError("createPaymentIntent is not available on this API client");
+        throw new import_core5.SolvaPayError("createPaymentIntent is not available on this API client");
       }
       return apiClient.createPaymentIntent(params);
     },
     createTopupPaymentIntent(params) {
       if (!apiClient.createTopupPaymentIntent) {
-        throw new import_core4.SolvaPayError("createTopupPaymentIntent is not available on this API client");
+        throw new import_core5.SolvaPayError("createTopupPaymentIntent is not available on this API client");
       }
       return apiClient.createTopupPaymentIntent(params);
     },
     processPaymentIntent(params) {
       if (!apiClient.processPaymentIntent) {
-        throw new import_core4.SolvaPayError("processPaymentIntent is not available on this API client");
+        throw new import_core5.SolvaPayError("processPaymentIntent is not available on this API client");
       }
       return apiClient.processPaymentIntent(params);
     },
     attachBusinessDetails(params) {
       if (!apiClient.attachBusinessDetails) {
-        throw new import_core4.SolvaPayError("attachBusinessDetails is not available on this API client");
+        throw new import_core5.SolvaPayError("attachBusinessDetails is not available on this API client");
       }
       return apiClient.attachBusinessDetails(params);
     },
@@ -2331,13 +2368,13 @@ function createSolvaPay(config) {
     },
     trackUsageBulk(params) {
       if (!apiClient.trackUsageBulk) {
-        throw new import_core4.SolvaPayError("trackUsageBulk is not available on this API client");
+        throw new import_core5.SolvaPayError("trackUsageBulk is not available on this API client");
       }
       return apiClient.trackUsageBulk(params);
     },
     createCustomer(params) {
       if (!apiClient.createCustomer) {
-        throw new import_core4.SolvaPayError("createCustomer is not available on this API client");
+        throw new import_core5.SolvaPayError("createCustomer is not available on this API client");
       }
       return apiClient.createCustomer({ ...params, metadata: params.metadata ?? {} });
     },
@@ -2346,13 +2383,13 @@ function createSolvaPay(config) {
     },
     assignCredits(params) {
       if (!apiClient.assignCredits) {
-        throw new import_core4.SolvaPayError("assignCredits is not available on this API client");
+        throw new import_core5.SolvaPayError("assignCredits is not available on this API client");
       }
       return apiClient.assignCredits(params);
     },
     getCustomerBalance(params) {
       if (!apiClient.getCustomerBalance) {
-        throw new import_core4.SolvaPayError("getCustomerBalance is not available on this API client");
+        throw new import_core5.SolvaPayError("getCustomerBalance is not available on this API client");
       }
       return apiClient.getCustomerBalance(params);
     },
@@ -2370,19 +2407,19 @@ function createSolvaPay(config) {
     },
     activatePlan(params) {
       if (!apiClient.activatePlan) {
-        throw new import_core4.SolvaPayError("activatePlan is not available on this API client");
+        throw new import_core5.SolvaPayError("activatePlan is not available on this API client");
       }
       return apiClient.activatePlan(params);
     },
     bootstrapMcpProduct(params) {
       if (!apiClient.bootstrapMcpProduct) {
-        throw new import_core4.SolvaPayError("bootstrapMcpProduct is not available on this API client");
+        throw new import_core5.SolvaPayError("bootstrapMcpProduct is not available on this API client");
       }
       return apiClient.bootstrapMcpProduct(params);
     },
     configureMcpPlans(productRef, params) {
       if (!apiClient.configureMcpPlans) {
-        throw new import_core4.SolvaPayError("configureMcpPlans is not available on this API client");
+        throw new import_core5.SolvaPayError("configureMcpPlans is not available on this API client");
       }
       return apiClient.configureMcpPlans(productRef, params);
     },
@@ -2395,12 +2432,13 @@ function createSolvaPay(config) {
     // Payable API for framework-specific handlers
     payable(options = {}) {
       const product = resolveProductRef(options.productRef || options.product);
-      const usageType = options.meterName || options.usageType || "requests";
+      const usageType = options.freeLimit?.meter || options.meterName || options.usageType || "requests";
       const metadata = {
         product,
         meterName: usageType,
         usageType,
-        ...options.toolName ? { toolName: options.toolName } : {}
+        ...options.toolName ? { toolName: options.toolName } : {},
+        ...options.freeLimit ? { freeLimit: options.freeLimit } : {}
       };
       return {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -2489,6 +2527,8 @@ function createSolvaPay(config) {
             const errMeta = opts?.error !== void 0 ? {
               error: opts.error instanceof Error ? opts.error.message : String(opts.error)
             } : {};
+            const isFree = Boolean(decideMetadata.freeLimit);
+            const usageClass = !isFree && outcome === "success" ? decision.consequence === "overage" ? "overage" : "included" : void 0;
             const trackPromise = apiClient.trackUsage({
               customerRef,
               productRef,
@@ -2501,6 +2541,8 @@ function createSolvaPay(config) {
                 action: meterName,
                 requestId,
                 ...decideMetadata.toolName ? { toolName: decideMetadata.toolName } : {},
+                ...isFree && decideMetadata.freeLimit ? { meterName: decideMetadata.freeLimit.meter } : {},
+                ...usageClass ? { usageClass } : {},
                 ...errMeta,
                 ...opts?.metadata ?? {}
               },
@@ -2533,7 +2575,7 @@ async function resolveCustomerRefFromRequest(req, options) {
 }
 
 // src/verify-product-configuration.ts
-var import_core5 = require("@solvapay/core");
+var import_core6 = require("@solvapay/core");
 async function verifyProductConfiguration(options) {
   const { apiClient, productRef } = options;
   const apiBaseUrl = options.apiBaseUrl ?? "(unknown API base URL)";
@@ -2544,7 +2586,7 @@ async function verifyProductConfiguration(options) {
   }
   try {
     const product = await apiClient.getProduct(productRef);
-    const readiness = (0, import_core5.evaluateProductReadiness)({
+    const readiness = (0, import_core6.evaluateProductReadiness)({
       status: product.status,
       plans: product.plans
     });
@@ -2557,8 +2599,8 @@ async function verifyProductConfiguration(options) {
       issues: readiness.issues
     };
   } catch (error) {
-    const status = error instanceof import_core5.SolvaPayError ? error.status : void 0;
-    const code = error instanceof import_core5.SolvaPayError ? error.code : void 0;
+    const status = error instanceof import_core6.SolvaPayError ? error.status : void 0;
+    const code = error instanceof import_core6.SolvaPayError ? 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.`
@@ -2655,13 +2697,13 @@ var PaywallStructuredContentSchema = import_zod.z.discriminatedUnion("kind", [
 ]);
 
 // src/helpers/error.ts
-var import_core6 = require("@solvapay/core");
+var import_core7 = require("@solvapay/core");
 function isErrorResult(result) {
   return typeof result === "object" && result !== null && "error" in result && "status" in result;
 }
 function handleRouteError(error, operationName, defaultMessage) {
   console.error(`[${operationName}] Error:`, error);
-  if (error instanceof import_core6.SolvaPayError) {
+  if (error instanceof import_core7.SolvaPayError) {
     const errorMessage2 = error.message;
     return {
       error: errorMessage2,
@@ -2849,7 +2891,7 @@ async function getCustomerBalanceCore(request, options = {}) {
 }
 
 // src/helpers/payment.ts
-var import_core7 = require("@solvapay/core");
+var import_core8 = require("@solvapay/core");
 
 // src/helpers/balance-poll.ts
 var TOPUP_BALANCE_POLL_DELAYS_MS = [500, 1e3, 2e3, 4e3];
@@ -2991,7 +3033,7 @@ async function attachBusinessDetailsCore(request, body, options = {}) {
         status: 400
       };
     }
-    const validation = (0, import_core7.validateBusinessDetails)({
+    const validation = (0, import_core8.validateBusinessDetails)({
       isBusiness: body.isBusiness,
       businessName: body.businessName,
       country: body.country,
@@ -3158,7 +3200,7 @@ async function createCustomerSessionCore(request, options = {}) {
 }
 
 // src/helpers/renewal.ts
-var import_core8 = require("@solvapay/core");
+var import_core9 = require("@solvapay/core");
 async function cancelPurchaseCore(request, body, options = {}) {
   try {
     if (!body.purchaseRef) {
@@ -3204,7 +3246,7 @@ async function cancelPurchaseCore(request, body, options = {}) {
     await new Promise((resolve) => setTimeout(resolve, 500));
     return cancelledPurchase;
   } catch (error) {
-    if (error instanceof import_core8.SolvaPayError) {
+    if (error instanceof import_core9.SolvaPayError) {
       const errorMessage = error.message;
       if (errorMessage.includes("not found")) {
         return {
@@ -3272,7 +3314,7 @@ async function reactivatePurchaseCore(request, body, options = {}) {
     await new Promise((resolve) => setTimeout(resolve, 500));
     return reactivatedPurchase;
   } catch (error) {
-    if (error instanceof import_core8.SolvaPayError) {
+    if (error instanceof import_core9.SolvaPayError) {
       const errorMessage = error.message;
       if (errorMessage.includes("not found")) {
         return {
@@ -3442,7 +3484,7 @@ async function getHistoryCore(request, input, options = {}) {
 }
 
 // src/helpers/plans.ts
-var import_core9 = require("@solvapay/core");
+var import_core10 = require("@solvapay/core");
 async function listPlansCore(request, options = {}) {
   try {
     const url = new URL(request.url);
@@ -3454,7 +3496,7 @@ async function listPlansCore(request, options = {}) {
       };
     }
     const apiClient = options.solvaPay?.apiClient ?? (() => {
-      const config = (0, import_core9.getSolvaPayConfig)();
+      const config = (0, import_core10.getSolvaPayConfig)();
       if (!config.apiKey) return null;
       return createSolvaPayClient({
         apiKey: config.apiKey,
@@ -3517,11 +3559,11 @@ async function checkLimitsCore(request, options = {}) {
 }
 
 // src/helpers/merchant.ts
-var import_core10 = require("@solvapay/core");
+var import_core11 = require("@solvapay/core");
 async function getMerchantCore(_request, options = {}) {
   try {
     const apiClient = options.solvaPay?.apiClient ?? (() => {
-      const config = (0, import_core10.getSolvaPayConfig)();
+      const config = (0, import_core11.getSolvaPayConfig)();
       if (!config.apiKey) return null;
       return createSolvaPayClient({
         apiKey: config.apiKey,
@@ -3548,7 +3590,7 @@ async function getMerchantCore(_request, options = {}) {
 }
 
 // src/helpers/product.ts
-var import_core11 = require("@solvapay/core");
+var import_core12 = require("@solvapay/core");
 async function getProductCore(request, options = {}) {
   try {
     const url = new URL(request.url);
@@ -3560,7 +3602,7 @@ async function getProductCore(request, options = {}) {
       };
     }
     const apiClient = options.solvaPay?.apiClient ?? (() => {
-      const config = (0, import_core11.getSolvaPayConfig)();
+      const config = (0, import_core12.getSolvaPayConfig)();
       if (!config.apiKey) return null;
       return createSolvaPayClient({
         apiKey: config.apiKey,
@@ -3643,7 +3685,7 @@ async function checkPurchaseCore(request, options = {}) {
 }
 
 // src/helpers/usage.ts
-var import_core12 = require("@solvapay/core");
+var import_core13 = require("@solvapay/core");
 function deriveUsageSnapshot(input) {
   const period = {
     ...input.periodStart ? { periodStart: input.periodStart } : {},
@@ -3693,7 +3735,7 @@ async function getUsageCore(request, options = {}) {
   if ("limits" in options) {
     return deriveUsageSnapshot({ used, ...period, limits: options.limits ?? null });
   }
-  const usageCounted = (0, import_core12.countsUsage)(activePurchase.planSnapshot) || activePurchase.planSnapshot?.isMetered === true;
+  const usageCounted = (0, import_core13.countsUsage)(activePurchase.planSnapshot) || activePurchase.planSnapshot?.isMetered === true;
   if (!usageCounted || !activePurchase.productRef) {
     return deriveUsageSnapshot({ used, ...period, limits: null });
   }
@@ -3738,34 +3780,34 @@ function verifyWebhook({
   secret
 }) {
   const toleranceSec = 300;
-  if (!signature) throw new import_core13.SolvaPayError("Missing webhook signature");
+  if (!signature) throw new import_core14.SolvaPayError("Missing webhook signature");
   const parts = signature.split(",");
   const tPart = parts.find((p) => p.startsWith("t="));
   const v1Part = parts.find((p) => p.startsWith("v1="));
   if (!tPart || !v1Part) {
-    throw new import_core13.SolvaPayError("Malformed webhook signature");
+    throw new import_core14.SolvaPayError("Malformed webhook signature");
   }
   const timestamp = parseInt(tPart.slice(2), 10);
   const receivedHmac = v1Part.slice(3);
   if (Number.isNaN(timestamp) || !receivedHmac) {
-    throw new import_core13.SolvaPayError("Malformed webhook signature");
+    throw new import_core14.SolvaPayError("Malformed webhook signature");
   }
   if (toleranceSec > 0) {
     const age = Math.abs(Math.floor(Date.now() / 1e3) - timestamp);
     if (age > toleranceSec) {
-      throw new import_core13.SolvaPayError("Webhook signature timestamp too old");
+      throw new import_core14.SolvaPayError("Webhook signature timestamp too old");
     }
   }
   const expectedHmac = import_node_crypto.default.createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
   if (receivedHmac.length !== expectedHmac.length) {
-    throw new import_core13.SolvaPayError("Invalid webhook signature");
+    throw new import_core14.SolvaPayError("Invalid webhook signature");
   }
   const ok = import_node_crypto.default.timingSafeEqual(Buffer.from(expectedHmac), Buffer.from(receivedHmac));
-  if (!ok) throw new import_core13.SolvaPayError("Invalid webhook signature");
+  if (!ok) throw new import_core14.SolvaPayError("Invalid webhook signature");
   try {
     return JSON.parse(body);
   } catch {
-    throw new import_core13.SolvaPayError("Invalid webhook payload: body is not valid JSON");
+    throw new import_core14.SolvaPayError("Invalid webhook payload: body is not valid JSON");
   }
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.d.cts

@@ -254,6 +254,15 @@ interface components {
         };
         CheckLimitRequest: {
             customerRef: string;
+            /** @description SDK-only free-tool allowance. Authenticated by the provider secret key, so `cap` is the provider's own declaration, not customer input. */
+            freeAllowance?: {
+                cap?: number;
+                /** @description Free meter name. Must match `/^free-[a-z0-9-]+$/`. */
+                meter?: string;
+                /** @enum {string} */
+                scope?: 'rolling_window' | 'lifetime';
+                windowDays?: number;
+            };
             includeCheckoutSession?: boolean;
             meterName?: string;
             productRef: string;
@@ -909,7 +918,7 @@ interface components {
              * Authoritative paywall classification shared with Managed MCP. Present on denial responses only.
              * @enum {string}
              */
-            paywallReason?: 'activation_required' | 'topup_required' | 'payment_required';
+            paywallReason?: 'activation_required' | 'topup_required' | 'payment_required' | 'limit_reached';
             /** @description Display name of the active or default plan */
             planName?: string;
             /** @description Active plan reference when the customer already holds a purchase */
@@ -3919,6 +3928,16 @@ type AttachBusinessDetailsParams = {
 } & components['schemas']['BusinessDetailsDto'];
 type AttachBusinessDetailsResult = components['schemas']['AttachBusinessDetailsResponse'];
 type CheckLimitsRequest = components['schemas']['CheckLimitRequest'];
+/**
+ * Per-customer cap declared in code on a `registerFree` tool. Not a
+ * registered `Meter` — the name must match `/^free-[a-z0-9-]+$/`.
+ *
+ * Derived from `CheckLimitRequest.freeAllowance`. nestjs-zod omits
+ * nested `required`, so OpenAPI marks every property optional; the
+ * object schema only treats `windowDays` as optional.
+ */
+type GeneratedFreeAllowance = NonNullable<CheckLimitsRequest['freeAllowance']>;
+type FreeLimit = Required<Omit<GeneratedFreeAllowance, 'windowDays'>> & Pick<GeneratedFreeAllowance, 'windowDays'>;
 /**
  * `LimitResponse` plus a deprecated SDK-only `plan` alias.
  *
@@ -4242,6 +4261,11 @@ interface PaywallMetadata {
      * attributable. Set by `registerPayable` / `buildPayableHandler`.
      */
     toolName?: string;
+    /**
+     * SDK-only free-tool allowance. When set, `decide()` sends this as
+     * `freeAllowance` and the free meter wins over `meterName`.
+     */
+    freeLimit?: FreeLimit;
 }
 /**
  * Structured content for paywall errors (MCP structuredContent and manual handling).
@@ -4278,9 +4302,9 @@ type PaywallGateRecoveryFields = {
     creditBalance?: number;
     /**
      * `PaywallState.kind` — same vocabulary as the classifier, not a third enum.
-     * `upgrade_required` / `limit_reached` / `reactivation_required` are
-     * SDK-only; the backend's `paywallReason` is a smaller set
-     * (`activation_required` / `topup_required` / `payment_required`).
+     * `upgrade_required` / `reactivation_required` are SDK-only. The
+     * backend's `paywallReason` covers `activation_required` /
+     * `topup_required` / `payment_required` / `limit_reached`.
      */
     reason?: PaywallReason;
     /** Single primary recovery the agent should take. */
@@ -4404,6 +4428,7 @@ type PaywallDecision<T> = {
  * Types for configuring various aspects of the SDK including retry behavior,
  * payable protection, and framework adapters.
  */
+
 /**
  * Retry configuration options
  */
@@ -4482,6 +4507,11 @@ interface PayableOptions {
      * Product reference (alias for product, preferred for consistency with backend API)
      */
     productRef?: string;
+    /**
+     * SDK-only free-tool allowance. When set, this meter's name wins over
+     * `meterName` / `usageType`, and `checkLimits` sends a `freeAllowance` block.
+     */
+    freeLimit?: FreeLimit;
     /**
      * Meter to charge against (defaults to `requests`).
      */
@@ -5042,14 +5072,7 @@ interface SolvaPay {
      * }
      * ```
      */
-    checkLimits(params: {
-        customerRef: string;
-        productRef: string;
-        planRef?: string;
-        meterName?: string;
-        /** @deprecated Use `meterName`. */
-        usageType?: string;
-    }): Promise<LimitResponseWithPlan>;
+    checkLimits(params: CheckLimitsRequest): Promise<LimitResponseWithPlan>;
     /**
      * Track usage for a customer action.
      *
@@ -5597,8 +5620,8 @@ declare const PaywallStructuredContentSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         topup_required: "topup_required";
         payment_required: "payment_required";
         activation_required: "activation_required";
-        upgrade_required: "upgrade_required";
         limit_reached: "limit_reached";
+        upgrade_required: "upgrade_required";
         reactivation_required: "reactivation_required";
     }>>;
     nextAction: z.ZodOptional<z.ZodEnum<{
@@ -5646,8 +5669,8 @@ declare const PaywallStructuredContentSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         topup_required: "topup_required";
         payment_required: "payment_required";
         activation_required: "activation_required";
-        upgrade_required: "upgrade_required";
         limit_reached: "limit_reached";
+        upgrade_required: "upgrade_required";
         reactivation_required: "reactivation_required";
     }>>;
     nextAction: z.ZodOptional<z.ZodEnum<{
@@ -5728,7 +5751,9 @@ declare function nextActionFor(state: PaywallState): PaywallNextAction;
  *
  * Precedence:
  *  1. `activationRequired` / `paywallReason === 'activation_required'`.
- *  2. `paywallReason === 'topup_required'` — backend stays authoritative
+ *  2. `paywallReason === 'limit_reached'` — free-allowance exhaustion
+ *     (no purchaseRef / planRef) must not fall through to upgrade_required.
+ *  3. `paywallReason === 'topup_required'` — backend stays authoritative
  *     for credit-based denials (same rule as Managed MCP).
  *  3. Authoritative `needsTopUp` / `needsUpgrade` flags from `decideLimit`.
  *  4. Credit-field presence + a real shortfall (`balance < cost`).
@@ -6555,4 +6580,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 CreditActivityEntry, type CreditActivityResult, type CreditActivityType, type CreditDebitResult, type CreditDebitSkipReason, type CreditDisplayBlock, type CreditSignals, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type GetHistoryResult, type GetUsageResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitAutoRechargeDto, 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 PaywallNextAction, type PaywallReason, 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, type UsageLimitsInput, 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, creditSignals, deriveUsageSnapshot, disableAutoRechargeCore, getAuthenticatedUserCore, getAutoRechargeCore, getCustomerBalanceCore, getHistoryCore, getMerchantCore, getPaymentMethodCore, getProductCore, getUsageCore, handleRouteError, isErrorResult, isPaywallStructuredContent, jsonSchemaToZodRawShape, linkLabel, listPlansCore, nextActionFor, paywallErrorToClientPayload, planLadder, 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 CreditActivityEntry, type CreditActivityResult, type CreditActivityType, type CreditDebitResult, type CreditDebitSkipReason, type CreditDisplayBlock, type CreditSignals, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type FreeLimit, type GetHistoryResult, type GetUsageResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitAutoRechargeDto, 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 PaywallNextAction, type PaywallReason, 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, type UsageLimitsInput, 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, creditSignals, deriveUsageSnapshot, disableAutoRechargeCore, getAuthenticatedUserCore, getAutoRechargeCore, getCustomerBalanceCore, getHistoryCore, getMerchantCore, getPaymentMethodCore, getProductCore, getUsageCore, handleRouteError, isErrorResult, isPaywallStructuredContent, jsonSchemaToZodRawShape, linkLabel, listPlansCore, nextActionFor, paywallErrorToClientPayload, planLadder, pollBalanceUntilIncreased, processPaymentIntentCore, processTopupPaymentIntentCore, reactivatePurchaseCore, registerVirtualToolsMcpImpl, saveAutoRechargeCore, syncCustomerCore, trackUsageCore, verifyProductConfiguration, verifyWebhook, withRetry };