@solvapay/server 2.7.0 → 2.8.0

package/dist/edge.d.ts

@@ -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.
  *
@@ -4224,6 +4243,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).
@@ -4260,9 +4284,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. */
@@ -4386,6 +4410,7 @@ type PaywallDecision<T> = {
  * Types for configuring various aspects of the SDK including retry behavior,
  * payable protection, and framework adapters.
  */
+
 /**
  * Retry configuration options
  */
@@ -4464,6 +4489,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`).
      */
@@ -5096,14 +5126,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.
      *
@@ -5509,8 +5532,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<{
@@ -5558,8 +5581,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<{
@@ -5640,7 +5663,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`).

package/dist/edge.js

@@ -1,5 +1,5 @@
 // src/edge.ts
-import { SolvaPayError as SolvaPayError7 } from "@solvapay/core";
+import { SolvaPayError as SolvaPayError8 } from "@solvapay/core";
 
 // src/client.ts
 import { SolvaPayError } from "@solvapay/core";
@@ -723,6 +723,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" };
   }
@@ -786,9 +789,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})`;
@@ -824,6 +830,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}.` : "";
@@ -1150,6 +1162,7 @@ function createRequestDeduplicator(options = {}) {
 }
 
 // src/paywall.ts
+import { SolvaPayError as SolvaPayError4 } from "@solvapay/core";
 var PaywallError = class extends Error {
   /**
    * Creates a new PaywallError instance.
@@ -1200,6 +1213,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;
@@ -1259,10 +1281,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;
@@ -1313,7 +1344,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 } : {}
           });
         }
       );
@@ -1357,7 +1389,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,
@@ -1404,7 +1437,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];
@@ -1423,7 +1456,8 @@ var SolvaPayPaywall = class {
         "success",
         requestId,
         latencyMs,
-        metadata.toolName
+        metadata.toolName,
+        trackUsageExtra(metadata, "success", decision.consequence)
       ).catch(() => void 0);
       return result;
     } catch (error) {
@@ -1442,7 +1476,8 @@ var SolvaPayPaywall = class {
           "fail",
           requestId,
           latencyMs,
-          metadata.toolName
+          metadata.toolName,
+          trackUsageExtra(metadata, "fail")
         ).catch(() => void 0);
       }
       throw error;
@@ -1633,7 +1668,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,
@@ -1646,7 +1681,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()
       }),
@@ -1986,7 +2023,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 = {
@@ -2263,25 +2300,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);
     },
@@ -2293,13 +2330,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 ?? {} });
     },
@@ -2308,13 +2345,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);
     },
@@ -2332,19 +2369,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);
     },
@@ -2357,12 +2394,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
@@ -2451,6 +2489,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,
@@ -2463,6 +2503,8 @@ function createSolvaPay(config) {
                 action: meterName,
                 requestId,
                 ...decideMetadata.toolName ? { toolName: decideMetadata.toolName } : {},
+                ...isFree && decideMetadata.freeLimit ? { meterName: decideMetadata.freeLimit.meter } : {},
+                ...usageClass ? { usageClass } : {},
                 ...errMeta,
                 ...opts?.metadata ?? {}
               },
@@ -2568,13 +2610,13 @@ var PaywallStructuredContentSchema = z.discriminatedUnion("kind", [
 ]);
 
 // src/helpers/error.ts
-import { SolvaPayError as SolvaPayError5 } from "@solvapay/core";
+import { SolvaPayError as SolvaPayError6 } from "@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 SolvaPayError5) {
+  if (error instanceof SolvaPayError6) {
     const errorMessage2 = error.message;
     return {
       error: errorMessage2,
@@ -3073,7 +3115,7 @@ async function createCustomerSessionCore(request, options = {}) {
 }
 
 // src/helpers/renewal.ts
-import { SolvaPayError as SolvaPayError6 } from "@solvapay/core";
+import { SolvaPayError as SolvaPayError7 } from "@solvapay/core";
 async function cancelPurchaseCore(request, body, options = {}) {
   try {
     if (!body.purchaseRef) {
@@ -3119,7 +3161,7 @@ async function cancelPurchaseCore(request, body, options = {}) {
     await new Promise((resolve) => setTimeout(resolve, 500));
     return cancelledPurchase;
   } catch (error) {
-    if (error instanceof SolvaPayError6) {
+    if (error instanceof SolvaPayError7) {
       const errorMessage = error.message;
       if (errorMessage.includes("not found")) {
         return {
@@ -3187,7 +3229,7 @@ async function reactivatePurchaseCore(request, body, options = {}) {
     await new Promise((resolve) => setTimeout(resolve, 500));
     return reactivatedPurchase;
   } catch (error) {
-    if (error instanceof SolvaPayError6) {
+    if (error instanceof SolvaPayError7) {
       const errorMessage = error.message;
       if (errorMessage.includes("not found")) {
         return {
@@ -3661,22 +3703,22 @@ async function verifyWebhook({
   secret
 }) {
   const toleranceSec = 300;
-  if (!signature) throw new SolvaPayError7("Missing webhook signature");
+  if (!signature) throw new SolvaPayError8("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 SolvaPayError7("Malformed webhook signature");
+    throw new SolvaPayError8("Malformed webhook signature");
   }
   const timestamp = parseInt(tPart.slice(2), 10);
   const receivedHmac = v1Part.slice(3);
   if (Number.isNaN(timestamp) || !receivedHmac) {
-    throw new SolvaPayError7("Malformed webhook signature");
+    throw new SolvaPayError8("Malformed webhook signature");
   }
   if (toleranceSec > 0) {
     const age = Math.abs(Math.floor(Date.now() / 1e3) - timestamp);
     if (age > toleranceSec) {
-      throw new SolvaPayError7("Webhook signature timestamp too old");
+      throw new SolvaPayError8("Webhook signature timestamp too old");
     }
   }
   const enc = new TextEncoder();
@@ -3690,12 +3732,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 SolvaPayError7("Invalid webhook signature");
+    throw new SolvaPayError8("Invalid webhook signature");
   }
   try {
     return JSON.parse(body);
   } catch {
-    throw new SolvaPayError7("Invalid webhook payload: body is not valid JSON");
+    throw new SolvaPayError8("Invalid webhook payload: body is not valid JSON");
   }
 }
 export {