@solvapay/server 2.7.0 → 2.8.0

package/dist/index.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.
  *
@@ -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 };

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
 import crypto from "crypto";
-import { SolvaPayError as SolvaPayError7 } from "@solvapay/core";
+import { SolvaPayError as SolvaPayError8 } from "@solvapay/core";
 
 // src/client.ts
 import { SolvaPayError } from "@solvapay/core";
@@ -675,6 +675,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" };
   }
@@ -738,9 +741,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})`;
@@ -776,6 +782,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}.` : "";
@@ -1102,6 +1114,7 @@ function createRequestDeduplicator(options = {}) {
 }
 
 // src/paywall.ts
+import { SolvaPayError as SolvaPayError3 } from "@solvapay/core";
 var PaywallError = class extends Error {
   /**
    * Creates a new PaywallError instance.
@@ -1152,6 +1165,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;
@@ -1211,10 +1233,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 SolvaPayError3("identity required", {
+          status: 401,
+          code: "identity_required"
+        });
+      }
+    }
     let backendCustomerRef;
     if (inputCustomerRef.startsWith("cus_")) {
       backendCustomerRef = inputCustomerRef;
@@ -1265,7 +1296,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 } : {}
           });
         }
       );
@@ -1309,7 +1341,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,
@@ -1356,7 +1389,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];
@@ -1375,7 +1408,8 @@ var SolvaPayPaywall = class {
         "success",
         requestId,
         latencyMs,
-        metadata.toolName
+        metadata.toolName,
+        trackUsageExtra(metadata, "success", decision.consequence)
       ).catch(() => void 0);
       return result;
     } catch (error) {
@@ -1394,7 +1428,8 @@ var SolvaPayPaywall = class {
           "fail",
           requestId,
           latencyMs,
-          metadata.toolName
+          metadata.toolName,
+          trackUsageExtra(metadata, "fail")
         ).catch(() => void 0);
       }
       throw error;
@@ -1585,7 +1620,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,
@@ -1598,7 +1633,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()
       }),
@@ -1938,7 +1975,7 @@ var McpAdapter = class {
 };
 
 // src/factory.ts
-import { SolvaPayError as SolvaPayError3, getSolvaPayConfig } from "@solvapay/core";
+import { SolvaPayError as SolvaPayError4, getSolvaPayConfig } from "@solvapay/core";
 
 // src/virtual-tools.ts
 var TOOL_GET_USER_INFO = {
@@ -2216,25 +2253,25 @@ function createSolvaPay(config) {
     },
     createPaymentIntent(params) {
       if (!apiClient.createPaymentIntent) {
-        throw new SolvaPayError3("createPaymentIntent is not available on this API client");
+        throw new SolvaPayError4("createPaymentIntent is not available on this API client");
       }
       return apiClient.createPaymentIntent(params);
     },
     createTopupPaymentIntent(params) {
       if (!apiClient.createTopupPaymentIntent) {
-        throw new SolvaPayError3("createTopupPaymentIntent is not available on this API client");
+        throw new SolvaPayError4("createTopupPaymentIntent is not available on this API client");
       }
       return apiClient.createTopupPaymentIntent(params);
     },
     processPaymentIntent(params) {
       if (!apiClient.processPaymentIntent) {
-        throw new SolvaPayError3("processPaymentIntent is not available on this API client");
+        throw new SolvaPayError4("processPaymentIntent is not available on this API client");
       }
       return apiClient.processPaymentIntent(params);
     },
     attachBusinessDetails(params) {
       if (!apiClient.attachBusinessDetails) {
-        throw new SolvaPayError3("attachBusinessDetails is not available on this API client");
+        throw new SolvaPayError4("attachBusinessDetails is not available on this API client");
       }
       return apiClient.attachBusinessDetails(params);
     },
@@ -2246,13 +2283,13 @@ function createSolvaPay(config) {
     },
     trackUsageBulk(params) {
       if (!apiClient.trackUsageBulk) {
-        throw new SolvaPayError3("trackUsageBulk is not available on this API client");
+        throw new SolvaPayError4("trackUsageBulk is not available on this API client");
       }
       return apiClient.trackUsageBulk(params);
     },
     createCustomer(params) {
       if (!apiClient.createCustomer) {
-        throw new SolvaPayError3("createCustomer is not available on this API client");
+        throw new SolvaPayError4("createCustomer is not available on this API client");
       }
       return apiClient.createCustomer({ ...params, metadata: params.metadata ?? {} });
     },
@@ -2261,13 +2298,13 @@ function createSolvaPay(config) {
     },
     assignCredits(params) {
       if (!apiClient.assignCredits) {
-        throw new SolvaPayError3("assignCredits is not available on this API client");
+        throw new SolvaPayError4("assignCredits is not available on this API client");
       }
       return apiClient.assignCredits(params);
     },
     getCustomerBalance(params) {
       if (!apiClient.getCustomerBalance) {
-        throw new SolvaPayError3("getCustomerBalance is not available on this API client");
+        throw new SolvaPayError4("getCustomerBalance is not available on this API client");
       }
       return apiClient.getCustomerBalance(params);
     },
@@ -2285,19 +2322,19 @@ function createSolvaPay(config) {
     },
     activatePlan(params) {
       if (!apiClient.activatePlan) {
-        throw new SolvaPayError3("activatePlan is not available on this API client");
+        throw new SolvaPayError4("activatePlan is not available on this API client");
       }
       return apiClient.activatePlan(params);
     },
     bootstrapMcpProduct(params) {
       if (!apiClient.bootstrapMcpProduct) {
-        throw new SolvaPayError3("bootstrapMcpProduct is not available on this API client");
+        throw new SolvaPayError4("bootstrapMcpProduct is not available on this API client");
       }
       return apiClient.bootstrapMcpProduct(params);
     },
     configureMcpPlans(productRef, params) {
       if (!apiClient.configureMcpPlans) {
-        throw new SolvaPayError3("configureMcpPlans is not available on this API client");
+        throw new SolvaPayError4("configureMcpPlans is not available on this API client");
       }
       return apiClient.configureMcpPlans(productRef, params);
     },
@@ -2310,12 +2347,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
@@ -2404,6 +2442,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,
@@ -2416,6 +2456,8 @@ function createSolvaPay(config) {
                 action: meterName,
                 requestId,
                 ...decideMetadata.toolName ? { toolName: decideMetadata.toolName } : {},
+                ...isFree && decideMetadata.freeLimit ? { meterName: decideMetadata.freeLimit.meter } : {},
+                ...usageClass ? { usageClass } : {},
                 ...errMeta,
                 ...opts?.metadata ?? {}
               },
@@ -2448,7 +2490,7 @@ async function resolveCustomerRefFromRequest(req, options) {
 }
 
 // src/verify-product-configuration.ts
-import { evaluateProductReadiness, SolvaPayError as SolvaPayError4 } from "@solvapay/core";
+import { evaluateProductReadiness, SolvaPayError as SolvaPayError5 } from "@solvapay/core";
 async function verifyProductConfiguration(options) {
   const { apiClient, productRef } = options;
   const apiBaseUrl = options.apiBaseUrl ?? "(unknown API base URL)";
@@ -2472,8 +2514,8 @@ async function verifyProductConfiguration(options) {
       issues: readiness.issues
     };
   } catch (error) {
-    const status = error instanceof SolvaPayError4 ? error.status : void 0;
-    const code = error instanceof SolvaPayError4 ? error.code : void 0;
+    const status = error instanceof SolvaPayError5 ? error.status : void 0;
+    const code = error instanceof SolvaPayError5 ? 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.`
@@ -2570,13 +2612,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,
@@ -3075,7 +3117,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) {
@@ -3121,7 +3163,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 {
@@ -3189,7 +3231,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 {
@@ -3655,34 +3697,34 @@ 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 expectedHmac = crypto.createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
   if (receivedHmac.length !== expectedHmac.length) {
-    throw new SolvaPayError7("Invalid webhook signature");
+    throw new SolvaPayError8("Invalid webhook signature");
   }
   const ok = crypto.timingSafeEqual(Buffer.from(expectedHmac), Buffer.from(receivedHmac));
-  if (!ok) throw new SolvaPayError7("Invalid webhook signature");
+  if (!ok) 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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solvapay/server",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -70,8 +70,8 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "generate:types": "tsx scripts/generate-types.ts",
-    "test": "vitest run __tests__/paywall.unit.test.ts __tests__/paywall-state.unit.test.ts __tests__/paywall-gate.unit.test.ts __tests__/payable-gate.unit.test.ts __tests__/bootstrap-mcp.unit.test.ts __tests__/verify-webhook.unit.test.ts __tests__/edge-exports.unit.test.ts __tests__/credits-usage.unit.test.ts __tests__/limit-outcome-flags.unit.test.ts __tests__/client-error.unit.test.ts __tests__/checkout-core.unit.test.ts src/__tests__/edge-exports.test.ts src/helpers/payment.test.ts src/helpers/usage.test.ts src/resolve-product-ref.test.ts src/verify-product-configuration.test.ts __tests__/auth-core.unit.test.ts __tests__/ensure-customer.unit.test.ts __tests__/create-customer.unit.test.ts __tests__/fetch/cors.test.ts __tests__/fetch/handlers.test.ts __tests__/fetch/utils.test.ts",
-    "test:unit": "vitest run __tests__/paywall.unit.test.ts __tests__/paywall-state.unit.test.ts __tests__/paywall-gate.unit.test.ts __tests__/payable-gate.unit.test.ts __tests__/bootstrap-mcp.unit.test.ts __tests__/verify-webhook.unit.test.ts __tests__/edge-exports.unit.test.ts __tests__/credits-usage.unit.test.ts __tests__/limit-outcome-flags.unit.test.ts __tests__/client-error.unit.test.ts __tests__/checkout-core.unit.test.ts src/__tests__/edge-exports.test.ts src/helpers/payment.test.ts src/helpers/usage.test.ts src/resolve-product-ref.test.ts src/verify-product-configuration.test.ts __tests__/auth-core.unit.test.ts __tests__/ensure-customer.unit.test.ts __tests__/create-customer.unit.test.ts __tests__/fetch/cors.test.ts __tests__/fetch/handlers.test.ts __tests__/fetch/utils.test.ts",
+    "test": "vitest run __tests__/paywall.unit.test.ts __tests__/paywall-state.unit.test.ts __tests__/free-limit.unit.test.ts __tests__/paywall-gate.unit.test.ts __tests__/payable-gate.unit.test.ts __tests__/bootstrap-mcp.unit.test.ts __tests__/verify-webhook.unit.test.ts __tests__/edge-exports.unit.test.ts __tests__/credits-usage.unit.test.ts __tests__/limit-outcome-flags.unit.test.ts __tests__/client-error.unit.test.ts __tests__/checkout-core.unit.test.ts src/__tests__/edge-exports.test.ts src/helpers/payment.test.ts src/helpers/usage.test.ts src/resolve-product-ref.test.ts src/verify-product-configuration.test.ts __tests__/auth-core.unit.test.ts __tests__/ensure-customer.unit.test.ts __tests__/create-customer.unit.test.ts __tests__/fetch/cors.test.ts __tests__/fetch/handlers.test.ts __tests__/fetch/utils.test.ts",
+    "test:unit": "vitest run __tests__/paywall.unit.test.ts __tests__/paywall-state.unit.test.ts __tests__/free-limit.unit.test.ts __tests__/paywall-gate.unit.test.ts __tests__/payable-gate.unit.test.ts __tests__/bootstrap-mcp.unit.test.ts __tests__/verify-webhook.unit.test.ts __tests__/edge-exports.unit.test.ts __tests__/credits-usage.unit.test.ts __tests__/limit-outcome-flags.unit.test.ts __tests__/client-error.unit.test.ts __tests__/checkout-core.unit.test.ts src/__tests__/edge-exports.test.ts src/helpers/payment.test.ts src/helpers/usage.test.ts src/resolve-product-ref.test.ts src/verify-product-configuration.test.ts __tests__/auth-core.unit.test.ts __tests__/ensure-customer.unit.test.ts __tests__/create-customer.unit.test.ts __tests__/fetch/cors.test.ts __tests__/fetch/handlers.test.ts __tests__/fetch/utils.test.ts",
     "test:integration": "vitest run --no-file-parallelism __tests__/backend.integration.test.ts __tests__/customer-update.integration.test.ts __tests__/multi-currency-plans.integration.test.ts",
     "test:integration:backend": "vitest run __tests__/backend.integration.test.ts",
     "test:integration:customer": "vitest run __tests__/customer-update.integration.test.ts",