@solvapay/server 2.7.0 → 2.8.0

package/dist/fetch/index.cjs

@@ -879,6 +879,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" };
   }
@@ -942,9 +945,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})`;
@@ -980,6 +986,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}.` : "";
@@ -1282,6 +1294,7 @@ function createRequestDeduplicator(options = {}) {
 }
 
 // src/paywall.ts
+var import_core5 = require("@solvapay/core");
 var PaywallError = class extends Error {
   /**
    * Creates a new PaywallError instance.
@@ -1332,6 +1345,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;
@@ -1391,10 +1413,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_core5.SolvaPayError("identity required", {
+          status: 401,
+          code: "identity_required"
+        });
+      }
+    }
     let backendCustomerRef;
     if (inputCustomerRef.startsWith("cus_")) {
       backendCustomerRef = inputCustomerRef;
@@ -1445,7 +1476,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 } : {}
           });
         }
       );
@@ -1489,7 +1521,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,
@@ -1536,7 +1569,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];
@@ -1555,7 +1588,8 @@ var SolvaPayPaywall = class {
         "success",
         requestId,
         latencyMs,
-        metadata.toolName
+        metadata.toolName,
+        trackUsageExtra(metadata, "success", decision.consequence)
       ).catch(() => void 0);
       return result;
     } catch (error) {
@@ -1574,7 +1608,8 @@ var SolvaPayPaywall = class {
           "fail",
           requestId,
           latencyMs,
-          metadata.toolName
+          metadata.toolName,
+          trackUsageExtra(metadata, "fail")
         ).catch(() => void 0);
       }
       throw error;
@@ -1765,7 +1800,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,
@@ -1778,7 +1813,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()
       }),
@@ -2118,7 +2155,7 @@ var McpAdapter = class {
 };
 
 // src/factory.ts
-var import_core5 = require("@solvapay/core");
+var import_core6 = require("@solvapay/core");
 
 // src/virtual-tools.ts
 var TOOL_GET_USER_INFO = {
@@ -2359,7 +2396,7 @@ function registerVirtualToolsMcpImpl(server, apiClient, options) {
 function createSolvaPay(config) {
   let resolvedConfig;
   if (!config) {
-    const envConfig = (0, import_core5.getSolvaPayConfig)();
+    const envConfig = (0, import_core6.getSolvaPayConfig)();
     resolvedConfig = {
       apiKey: envConfig.apiKey,
       apiBaseUrl: envConfig.apiBaseUrl
@@ -2395,25 +2432,25 @@ function createSolvaPay(config) {
     },
     createPaymentIntent(params) {
       if (!apiClient.createPaymentIntent) {
-        throw new import_core5.SolvaPayError("createPaymentIntent is not available on this API client");
+        throw new import_core6.SolvaPayError("createPaymentIntent is not available on this API client");
       }
       return apiClient.createPaymentIntent(params);
     },
     createTopupPaymentIntent(params) {
       if (!apiClient.createTopupPaymentIntent) {
-        throw new import_core5.SolvaPayError("createTopupPaymentIntent is not available on this API client");
+        throw new import_core6.SolvaPayError("createTopupPaymentIntent is not available on this API client");
       }
       return apiClient.createTopupPaymentIntent(params);
     },
     processPaymentIntent(params) {
       if (!apiClient.processPaymentIntent) {
-        throw new import_core5.SolvaPayError("processPaymentIntent is not available on this API client");
+        throw new import_core6.SolvaPayError("processPaymentIntent is not available on this API client");
       }
       return apiClient.processPaymentIntent(params);
     },
     attachBusinessDetails(params) {
       if (!apiClient.attachBusinessDetails) {
-        throw new import_core5.SolvaPayError("attachBusinessDetails is not available on this API client");
+        throw new import_core6.SolvaPayError("attachBusinessDetails is not available on this API client");
       }
       return apiClient.attachBusinessDetails(params);
     },
@@ -2425,13 +2462,13 @@ function createSolvaPay(config) {
     },
     trackUsageBulk(params) {
       if (!apiClient.trackUsageBulk) {
-        throw new import_core5.SolvaPayError("trackUsageBulk is not available on this API client");
+        throw new import_core6.SolvaPayError("trackUsageBulk is not available on this API client");
       }
       return apiClient.trackUsageBulk(params);
     },
     createCustomer(params) {
       if (!apiClient.createCustomer) {
-        throw new import_core5.SolvaPayError("createCustomer is not available on this API client");
+        throw new import_core6.SolvaPayError("createCustomer is not available on this API client");
       }
       return apiClient.createCustomer({ ...params, metadata: params.metadata ?? {} });
     },
@@ -2440,13 +2477,13 @@ function createSolvaPay(config) {
     },
     assignCredits(params) {
       if (!apiClient.assignCredits) {
-        throw new import_core5.SolvaPayError("assignCredits is not available on this API client");
+        throw new import_core6.SolvaPayError("assignCredits is not available on this API client");
       }
       return apiClient.assignCredits(params);
     },
     getCustomerBalance(params) {
       if (!apiClient.getCustomerBalance) {
-        throw new import_core5.SolvaPayError("getCustomerBalance is not available on this API client");
+        throw new import_core6.SolvaPayError("getCustomerBalance is not available on this API client");
       }
       return apiClient.getCustomerBalance(params);
     },
@@ -2464,19 +2501,19 @@ function createSolvaPay(config) {
     },
     activatePlan(params) {
       if (!apiClient.activatePlan) {
-        throw new import_core5.SolvaPayError("activatePlan is not available on this API client");
+        throw new import_core6.SolvaPayError("activatePlan is not available on this API client");
       }
       return apiClient.activatePlan(params);
     },
     bootstrapMcpProduct(params) {
       if (!apiClient.bootstrapMcpProduct) {
-        throw new import_core5.SolvaPayError("bootstrapMcpProduct is not available on this API client");
+        throw new import_core6.SolvaPayError("bootstrapMcpProduct is not available on this API client");
       }
       return apiClient.bootstrapMcpProduct(params);
     },
     configureMcpPlans(productRef, params) {
       if (!apiClient.configureMcpPlans) {
-        throw new import_core5.SolvaPayError("configureMcpPlans is not available on this API client");
+        throw new import_core6.SolvaPayError("configureMcpPlans is not available on this API client");
       }
       return apiClient.configureMcpPlans(productRef, params);
     },
@@ -2489,12 +2526,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
@@ -2583,6 +2621,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,
@@ -2595,6 +2635,8 @@ function createSolvaPay(config) {
                 action: meterName,
                 requestId,
                 ...decideMetadata.toolName ? { toolName: decideMetadata.toolName } : {},
+                ...isFree && decideMetadata.freeLimit ? { meterName: decideMetadata.freeLimit.meter } : {},
+                ...usageClass ? { usageClass } : {},
                 ...errMeta,
                 ...opts?.metadata ?? {}
               },
@@ -2667,7 +2709,7 @@ async function getCustomerBalanceCore(request, options = {}) {
 }
 
 // src/helpers/payment.ts
-var import_core6 = require("@solvapay/core");
+var import_core7 = require("@solvapay/core");
 async function createPaymentIntentCore(request, body, options = {}) {
   try {
     if (!body.planRef || !body.productRef) {
@@ -2850,7 +2892,7 @@ async function createCustomerSessionCore(request, options = {}) {
 }
 
 // src/helpers/renewal.ts
-var import_core7 = require("@solvapay/core");
+var import_core8 = require("@solvapay/core");
 async function cancelPurchaseCore(request, body, options = {}) {
   try {
     if (!body.purchaseRef) {
@@ -2896,7 +2938,7 @@ async function cancelPurchaseCore(request, body, options = {}) {
     await new Promise((resolve) => setTimeout(resolve, 500));
     return cancelledPurchase;
   } catch (error) {
-    if (error instanceof import_core7.SolvaPayError) {
+    if (error instanceof import_core8.SolvaPayError) {
       const errorMessage = error.message;
       if (errorMessage.includes("not found")) {
         return {
@@ -2964,7 +3006,7 @@ async function reactivatePurchaseCore(request, body, options = {}) {
     await new Promise((resolve) => setTimeout(resolve, 500));
     return reactivatedPurchase;
   } catch (error) {
-    if (error instanceof import_core7.SolvaPayError) {
+    if (error instanceof import_core8.SolvaPayError) {
       const errorMessage = error.message;
       if (errorMessage.includes("not found")) {
         return {
@@ -3086,7 +3128,7 @@ async function getHistoryCore(request, input, options = {}) {
 }
 
 // src/helpers/plans.ts
-var import_core8 = require("@solvapay/core");
+var import_core9 = require("@solvapay/core");
 async function listPlansCore(request, options = {}) {
   try {
     const url = new URL(request.url);
@@ -3098,7 +3140,7 @@ async function listPlansCore(request, options = {}) {
       };
     }
     const apiClient = options.solvaPay?.apiClient ?? (() => {
-      const config = (0, import_core8.getSolvaPayConfig)();
+      const config = (0, import_core9.getSolvaPayConfig)();
       if (!config.apiKey) return null;
       return createSolvaPayClient({
         apiKey: config.apiKey,
@@ -3128,11 +3170,11 @@ async function listPlansCore(request, options = {}) {
 }
 
 // src/helpers/merchant.ts
-var import_core9 = require("@solvapay/core");
+var import_core10 = require("@solvapay/core");
 async function getMerchantCore(_request, options = {}) {
   try {
     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,
@@ -3159,7 +3201,7 @@ async function getMerchantCore(_request, options = {}) {
 }
 
 // src/helpers/product.ts
-var import_core10 = require("@solvapay/core");
+var import_core11 = require("@solvapay/core");
 async function getProductCore(request, options = {}) {
   try {
     const url = new URL(request.url);
@@ -3171,7 +3213,7 @@ async function getProductCore(request, options = {}) {
       };
     }
     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,
@@ -3254,7 +3296,7 @@ async function checkPurchaseCore(request, options = {}) {
 }
 
 // src/helpers/usage.ts
-var import_core11 = require("@solvapay/core");
+var import_core12 = require("@solvapay/core");
 async function trackUsageCore(request, body, options = {}) {
   try {
     const userResult = await getAuthenticatedUserCore(request);
@@ -3283,7 +3325,7 @@ async function trackUsageCore(request, body, options = {}) {
 }
 
 // src/edge.ts
-var import_core12 = require("@solvapay/core");
+var import_core13 = require("@solvapay/core");
 function timingSafeEqual(a, b) {
   if (a.length !== b.length) return false;
   let mismatch = 0;
@@ -3298,22 +3340,22 @@ async function verifyWebhook({
   secret
 }) {
   const toleranceSec = 300;
-  if (!signature) throw new import_core12.SolvaPayError("Missing webhook signature");
+  if (!signature) throw new import_core13.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_core12.SolvaPayError("Malformed webhook signature");
+    throw new import_core13.SolvaPayError("Malformed webhook signature");
   }
   const timestamp = parseInt(tPart.slice(2), 10);
   const receivedHmac = v1Part.slice(3);
   if (Number.isNaN(timestamp) || !receivedHmac) {
-    throw new import_core12.SolvaPayError("Malformed webhook signature");
+    throw new import_core13.SolvaPayError("Malformed webhook signature");
   }
   if (toleranceSec > 0) {
     const age = Math.abs(Math.floor(Date.now() / 1e3) - timestamp);
     if (age > toleranceSec) {
-      throw new import_core12.SolvaPayError("Webhook signature timestamp too old");
+      throw new import_core13.SolvaPayError("Webhook signature timestamp too old");
     }
   }
   const enc = new TextEncoder();
@@ -3327,12 +3369,12 @@ async function verifyWebhook({
   const sigBuf = await crypto.subtle.sign("HMAC", key, enc.encode(`${timestamp}.${body}`));
   const expectedHmac = Array.from(new Uint8Array(sigBuf)).map((b) => b.toString(16).padStart(2, "0")).join("");
   if (!timingSafeEqual(expectedHmac, receivedHmac)) {
-    throw new import_core12.SolvaPayError("Invalid webhook signature");
+    throw new import_core13.SolvaPayError("Invalid webhook signature");
   }
   try {
     return JSON.parse(body);
   } catch {
-    throw new import_core12.SolvaPayError("Invalid webhook payload: body is not valid JSON");
+    throw new import_core13.SolvaPayError("Invalid webhook payload: body is not valid JSON");
   }
 }
 

package/dist/fetch/index.d.cts

@@ -251,6 +251,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;
@@ -906,7 +915,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 */

package/dist/fetch/index.d.ts

@@ -251,6 +251,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;
@@ -906,7 +915,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 */