@solvapay/server 2.7.0 → 2.8.0

package/dist/fetch/index.js

@@ -825,6 +825,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" };
   }
@@ -888,9 +891,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})`;
@@ -926,6 +932,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}.` : "";
@@ -1228,6 +1240,7 @@ function createRequestDeduplicator(options = {}) {
 }
 
 // src/paywall.ts
+import { SolvaPayError as SolvaPayError4 } from "@solvapay/core";
 var PaywallError = class extends Error {
   /**
    * Creates a new PaywallError instance.
@@ -1278,6 +1291,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;
@@ -1337,10 +1359,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 SolvaPayError4("identity required", {
+          status: 401,
+          code: "identity_required"
+        });
+      }
+    }
     let backendCustomerRef;
     if (inputCustomerRef.startsWith("cus_")) {
       backendCustomerRef = inputCustomerRef;
@@ -1391,7 +1422,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 } : {}
           });
         }
       );
@@ -1435,7 +1467,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,
@@ -1482,7 +1515,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];
@@ -1501,7 +1534,8 @@ var SolvaPayPaywall = class {
         "success",
         requestId,
         latencyMs,
-        metadata.toolName
+        metadata.toolName,
+        trackUsageExtra(metadata, "success", decision.consequence)
       ).catch(() => void 0);
       return result;
     } catch (error) {
@@ -1520,7 +1554,8 @@ var SolvaPayPaywall = class {
           "fail",
           requestId,
           latencyMs,
-          metadata.toolName
+          metadata.toolName,
+          trackUsageExtra(metadata, "fail")
         ).catch(() => void 0);
       }
       throw error;
@@ -1711,7 +1746,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,
@@ -1724,7 +1759,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()
       }),
@@ -2064,7 +2101,7 @@ var McpAdapter = class {
 };
 
 // src/factory.ts
-import { SolvaPayError as SolvaPayError4, getSolvaPayConfig } from "@solvapay/core";
+import { SolvaPayError as SolvaPayError5, getSolvaPayConfig } from "@solvapay/core";
 
 // src/virtual-tools.ts
 var TOOL_GET_USER_INFO = {
@@ -2341,25 +2378,25 @@ function createSolvaPay(config) {
     },
     createPaymentIntent(params) {
       if (!apiClient.createPaymentIntent) {
-        throw new SolvaPayError4("createPaymentIntent is not available on this API client");
+        throw new SolvaPayError5("createPaymentIntent is not available on this API client");
       }
       return apiClient.createPaymentIntent(params);
     },
     createTopupPaymentIntent(params) {
       if (!apiClient.createTopupPaymentIntent) {
-        throw new SolvaPayError4("createTopupPaymentIntent is not available on this API client");
+        throw new SolvaPayError5("createTopupPaymentIntent is not available on this API client");
       }
       return apiClient.createTopupPaymentIntent(params);
     },
     processPaymentIntent(params) {
       if (!apiClient.processPaymentIntent) {
-        throw new SolvaPayError4("processPaymentIntent is not available on this API client");
+        throw new SolvaPayError5("processPaymentIntent is not available on this API client");
       }
       return apiClient.processPaymentIntent(params);
     },
     attachBusinessDetails(params) {
       if (!apiClient.attachBusinessDetails) {
-        throw new SolvaPayError4("attachBusinessDetails is not available on this API client");
+        throw new SolvaPayError5("attachBusinessDetails is not available on this API client");
       }
       return apiClient.attachBusinessDetails(params);
     },
@@ -2371,13 +2408,13 @@ function createSolvaPay(config) {
     },
     trackUsageBulk(params) {
       if (!apiClient.trackUsageBulk) {
-        throw new SolvaPayError4("trackUsageBulk is not available on this API client");
+        throw new SolvaPayError5("trackUsageBulk is not available on this API client");
       }
       return apiClient.trackUsageBulk(params);
     },
     createCustomer(params) {
       if (!apiClient.createCustomer) {
-        throw new SolvaPayError4("createCustomer is not available on this API client");
+        throw new SolvaPayError5("createCustomer is not available on this API client");
       }
       return apiClient.createCustomer({ ...params, metadata: params.metadata ?? {} });
     },
@@ -2386,13 +2423,13 @@ function createSolvaPay(config) {
     },
     assignCredits(params) {
       if (!apiClient.assignCredits) {
-        throw new SolvaPayError4("assignCredits is not available on this API client");
+        throw new SolvaPayError5("assignCredits is not available on this API client");
       }
       return apiClient.assignCredits(params);
     },
     getCustomerBalance(params) {
       if (!apiClient.getCustomerBalance) {
-        throw new SolvaPayError4("getCustomerBalance is not available on this API client");
+        throw new SolvaPayError5("getCustomerBalance is not available on this API client");
       }
       return apiClient.getCustomerBalance(params);
     },
@@ -2410,19 +2447,19 @@ function createSolvaPay(config) {
     },
     activatePlan(params) {
       if (!apiClient.activatePlan) {
-        throw new SolvaPayError4("activatePlan is not available on this API client");
+        throw new SolvaPayError5("activatePlan is not available on this API client");
       }
       return apiClient.activatePlan(params);
     },
     bootstrapMcpProduct(params) {
       if (!apiClient.bootstrapMcpProduct) {
-        throw new SolvaPayError4("bootstrapMcpProduct is not available on this API client");
+        throw new SolvaPayError5("bootstrapMcpProduct is not available on this API client");
       }
       return apiClient.bootstrapMcpProduct(params);
     },
     configureMcpPlans(productRef, params) {
       if (!apiClient.configureMcpPlans) {
-        throw new SolvaPayError4("configureMcpPlans is not available on this API client");
+        throw new SolvaPayError5("configureMcpPlans is not available on this API client");
       }
       return apiClient.configureMcpPlans(productRef, params);
     },
@@ -2435,12 +2472,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
@@ -2529,6 +2567,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,
@@ -2541,6 +2581,8 @@ function createSolvaPay(config) {
                 action: meterName,
                 requestId,
                 ...decideMetadata.toolName ? { toolName: decideMetadata.toolName } : {},
+                ...isFree && decideMetadata.freeLimit ? { meterName: decideMetadata.freeLimit.meter } : {},
+                ...usageClass ? { usageClass } : {},
                 ...errMeta,
                 ...opts?.metadata ?? {}
               },
@@ -2798,7 +2840,7 @@ async function createCustomerSessionCore(request, options = {}) {
 }
 
 // src/helpers/renewal.ts
-import { SolvaPayError as SolvaPayError5 } from "@solvapay/core";
+import { SolvaPayError as SolvaPayError6 } from "@solvapay/core";
 async function cancelPurchaseCore(request, body, options = {}) {
   try {
     if (!body.purchaseRef) {
@@ -2844,7 +2886,7 @@ async function cancelPurchaseCore(request, body, options = {}) {
     await new Promise((resolve) => setTimeout(resolve, 500));
     return cancelledPurchase;
   } catch (error) {
-    if (error instanceof SolvaPayError5) {
+    if (error instanceof SolvaPayError6) {
       const errorMessage = error.message;
       if (errorMessage.includes("not found")) {
         return {
@@ -2912,7 +2954,7 @@ async function reactivatePurchaseCore(request, body, options = {}) {
     await new Promise((resolve) => setTimeout(resolve, 500));
     return reactivatedPurchase;
   } catch (error) {
-    if (error instanceof SolvaPayError5) {
+    if (error instanceof SolvaPayError6) {
       const errorMessage = error.message;
       if (errorMessage.includes("not found")) {
         return {
@@ -3231,7 +3273,7 @@ async function trackUsageCore(request, body, options = {}) {
 }
 
 // src/edge.ts
-import { SolvaPayError as SolvaPayError6 } from "@solvapay/core";
+import { SolvaPayError as SolvaPayError7 } from "@solvapay/core";
 function timingSafeEqual(a, b) {
   if (a.length !== b.length) return false;
   let mismatch = 0;
@@ -3246,22 +3288,22 @@ async function verifyWebhook({
   secret
 }) {
   const toleranceSec = 300;
-  if (!signature) throw new SolvaPayError6("Missing webhook signature");
+  if (!signature) throw new SolvaPayError7("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 SolvaPayError6("Malformed webhook signature");
+    throw new SolvaPayError7("Malformed webhook signature");
   }
   const timestamp = parseInt(tPart.slice(2), 10);
   const receivedHmac = v1Part.slice(3);
   if (Number.isNaN(timestamp) || !receivedHmac) {
-    throw new SolvaPayError6("Malformed webhook signature");
+    throw new SolvaPayError7("Malformed webhook signature");
   }
   if (toleranceSec > 0) {
     const age = Math.abs(Math.floor(Date.now() / 1e3) - timestamp);
     if (age > toleranceSec) {
-      throw new SolvaPayError6("Webhook signature timestamp too old");
+      throw new SolvaPayError7("Webhook signature timestamp too old");
     }
   }
   const enc = new TextEncoder();
@@ -3275,12 +3317,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 SolvaPayError6("Invalid webhook signature");
+    throw new SolvaPayError7("Invalid webhook signature");
   }
   try {
     return JSON.parse(body);
   } catch {
-    throw new SolvaPayError6("Invalid webhook payload: body is not valid JSON");
+    throw new SolvaPayError7("Invalid webhook payload: body is not valid JSON");
   }
 }