@solvapay/server 1.0.0-preview.9 → 1.0.1-preview.2

package/dist/index.js

@@ -1,19 +1,17 @@
-import {
-  __require
-} from "./chunk-R5U7XKVJ.js";
+import "./chunk-MLKGABMK.js";
 
 // src/index.ts
 import crypto from "crypto";
-import { SolvaPayError as SolvaPayError3 } from "@solvapay/core";
+import { SolvaPayError as SolvaPayError5 } from "@solvapay/core";
 
 // src/client.ts
 import { SolvaPayError } from "@solvapay/core";
 function createSolvaPayClient(opts) {
-  const base = opts.apiBaseUrl ?? "https://api-dev.solvapay.com";
+  const base = opts.apiBaseUrl ?? "https://api.solvapay.com";
   if (!opts.apiKey) throw new SolvaPayError("Missing apiKey");
   const headers = {
     "Content-Type": "application/json",
-    "Authorization": `Bearer ${opts.apiKey}`
+    Authorization: `Bearer ${opts.apiKey}`
   };
   const debug = process.env.SOLVAPAY_DEBUG === "true";
   const log = (...args) => {
@@ -41,10 +39,12 @@ function createSolvaPayClient(opts) {
     // POST: /v1/sdk/usages
     async trackUsage(params) {
       const url = `${base}/v1/sdk/usages`;
+      const { customerRef, ...rest } = params;
+      const body = { ...rest, customerId: customerRef };
       const res = await fetch(url, {
         method: "POST",
         headers,
-        body: JSON.stringify(params)
+        body: JSON.stringify(body)
       });
       if (!res.ok) {
         const error = await res.text();
@@ -68,9 +68,22 @@ function createSolvaPayClient(opts) {
       const result = await res.json();
       return result;
     },
-    // GET: /v1/sdk/customers/{reference}
+    // GET: /v1/sdk/customers/{reference} or /v1/sdk/customers?externalRef={externalRef}|email={email}
     async getCustomer(params) {
-      const url = `${base}/v1/sdk/customers/${params.customerRef}`;
+      let url;
+      let isByExternalRef = false;
+      let isByEmail = false;
+      if (params.externalRef) {
+        url = `${base}/v1/sdk/customers?externalRef=${encodeURIComponent(params.externalRef)}`;
+        isByExternalRef = true;
+      } else if (params.email) {
+        url = `${base}/v1/sdk/customers?email=${encodeURIComponent(params.email)}`;
+        isByEmail = true;
+      } else if (params.customerRef) {
+        url = `${base}/v1/sdk/customers/${params.customerRef}`;
+      } else {
+        throw new SolvaPayError("One of customerRef, externalRef, or email must be provided");
+      }
       const res = await fetch(url, {
         method: "GET",
         headers
@@ -81,40 +94,28 @@ function createSolvaPayClient(opts) {
         throw new SolvaPayError(`Get customer failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      return {
-        customerRef: result.reference || result.customerRef,
-        email: result.email,
-        name: result.name,
-        externalRef: result.externalRef,
-        subscriptions: result.subscriptions || []
-      };
-    },
-    // GET: /v1/sdk/customers?externalRef={externalRef}
-    async getCustomerByExternalRef(params) {
-      const url = `${base}/v1/sdk/customers?externalRef=${encodeURIComponent(params.externalRef)}`;
-      const res = await fetch(url, {
-        method: "GET",
-        headers
-      });
-      if (!res.ok) {
-        const error = await res.text();
-        log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Get customer by externalRef failed (${res.status}): ${error}`);
+      let customer = result;
+      if (isByExternalRef || isByEmail) {
+        const directCustomer = result && typeof result === "object" && (result.reference || result.customerRef || result.externalRef) ? result : void 0;
+        const wrappedCustomer = result && typeof result === "object" && result.customer ? result.customer : void 0;
+        const customers = Array.isArray(result) ? result : result && typeof result === "object" && Array.isArray(result.customers) ? result.customers : [];
+        customer = directCustomer || wrappedCustomer || customers[0];
+        if (!customer) {
+          throw new SolvaPayError(`No customer found with externalRef: ${params.externalRef}`);
+        }
       }
-      const result = await res.json();
-      const customer = Array.isArray(result) ? result[0] : result;
       return {
         customerRef: customer.reference || customer.customerRef,
         email: customer.email,
         name: customer.name,
         externalRef: customer.externalRef,
-        subscriptions: customer.subscriptions || []
+        purchases: customer.purchases || []
       };
     },
-    // Management methods (primarily for integration tests)
-    // GET: /v1/sdk/agents
-    async listAgents() {
-      const url = `${base}/v1/sdk/agents`;
+    // Product management methods (primarily for integration tests)
+    // GET: /v1/sdk/products
+    async listProducts() {
+      const url = `${base}/v1/sdk/products`;
       const res = await fetch(url, {
         method: "GET",
         headers
@@ -122,18 +123,18 @@ function createSolvaPayClient(opts) {
       if (!res.ok) {
         const error = await res.text();
         log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`List agents failed (${res.status}): ${error}`);
+        throw new SolvaPayError(`List products failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      const agents = Array.isArray(result) ? result : result.agents || [];
-      return agents.map((agent) => ({
-        ...agent,
-        ...agent.data || {}
+      const products = Array.isArray(result) ? result : result.products || [];
+      return products.map((product) => ({
+        ...product,
+        ...product.data || {}
       }));
     },
-    // POST: /v1/sdk/agents
-    async createAgent(params) {
-      const url = `${base}/v1/sdk/agents`;
+    // POST: /v1/sdk/products
+    async createProduct(params) {
+      const url = `${base}/v1/sdk/products`;
       const res = await fetch(url, {
         method: "POST",
         headers,
@@ -142,14 +143,29 @@ function createSolvaPayClient(opts) {
       if (!res.ok) {
         const error = await res.text();
         log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Create agent failed (${res.status}): ${error}`);
+        throw new SolvaPayError(`Create product failed (${res.status}): ${error}`);
       }
       const result = await res.json();
       return result;
     },
-    // DELETE: /v1/sdk/agents/{agentRef}
-    async deleteAgent(agentRef) {
-      const url = `${base}/v1/sdk/agents/${agentRef}`;
+    // POST: /v1/sdk/products/mcp/bootstrap
+    async bootstrapMcpProduct(params) {
+      const url = `${base}/v1/sdk/products/mcp/bootstrap`;
+      const res = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(params)
+      });
+      if (!res.ok) {
+        const error = await res.text();
+        log(`\u274C API Error: ${res.status} - ${error}`);
+        throw new SolvaPayError(`Bootstrap MCP product failed (${res.status}): ${error}`);
+      }
+      return await res.json();
+    },
+    // DELETE: /v1/sdk/products/{productRef}
+    async deleteProduct(productRef) {
+      const url = `${base}/v1/sdk/products/${productRef}`;
       const res = await fetch(url, {
         method: "DELETE",
         headers
@@ -157,12 +173,27 @@ function createSolvaPayClient(opts) {
       if (!res.ok && res.status !== 404) {
         const error = await res.text();
         log(`\u274C API Error: ${res.status} - ${error}`);
-        throw new SolvaPayError(`Delete agent failed (${res.status}): ${error}`);
+        throw new SolvaPayError(`Delete product failed (${res.status}): ${error}`);
       }
     },
-    // GET: /v1/sdk/agents/{agentRef}/plans
-    async listPlans(agentRef) {
-      const url = `${base}/v1/sdk/agents/${agentRef}/plans`;
+    // POST: /v1/sdk/products/{productRef}/clone
+    async cloneProduct(productRef, overrides) {
+      const url = `${base}/v1/sdk/products/${productRef}/clone`;
+      const res = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(overrides || {})
+      });
+      if (!res.ok) {
+        const error = await res.text();
+        log(`\u274C API Error: ${res.status} - ${error}`);
+        throw new SolvaPayError(`Clone product failed (${res.status}): ${error}`);
+      }
+      return await res.json();
+    },
+    // GET: /v1/sdk/products/{productRef}/plans
+    async listPlans(productRef) {
+      const url = `${base}/v1/sdk/products/${productRef}/plans`;
       const res = await fetch(url, {
         method: "GET",
         headers
@@ -175,20 +206,20 @@ function createSolvaPayClient(opts) {
       const result = await res.json();
       const plans = Array.isArray(result) ? result : result.plans || [];
       return plans.map((plan) => {
-        const price = plan.price ?? plan.data?.price;
+        const data = plan.data || {};
+        const price = plan.price ?? data.price;
         const unwrapped = {
-          ...plan.data || {},
+          ...data,
           ...plan,
-          // Explicitly preserve price field to ensure it's not lost
           ...price !== void 0 && { price }
         };
         delete unwrapped.data;
         return unwrapped;
       });
     },
-    // POST: /v1/sdk/agents/{agentRef}/plans
+    // POST: /v1/sdk/products/{productRef}/plans
     async createPlan(params) {
-      const url = `${base}/v1/sdk/agents/${params.agentRef}/plans`;
+      const url = `${base}/v1/sdk/products/${params.productRef}/plans`;
       const res = await fetch(url, {
         method: "POST",
         headers,
@@ -202,9 +233,24 @@ function createSolvaPayClient(opts) {
       const result = await res.json();
       return result;
     },
-    // DELETE: /v1/sdk/agents/{agentRef}/plans/{planRef}
-    async deletePlan(agentRef, planRef) {
-      const url = `${base}/v1/sdk/agents/${agentRef}/plans/${planRef}`;
+    // PUT: /v1/sdk/products/{productRef}/plans/{planRef}
+    async updatePlan(productRef, planRef, params) {
+      const url = `${base}/v1/sdk/products/${productRef}/plans/${planRef}`;
+      const res = await fetch(url, {
+        method: "PUT",
+        headers,
+        body: JSON.stringify(params)
+      });
+      if (!res.ok) {
+        const error = await res.text();
+        log(`\u274C API Error: ${res.status} - ${error}`);
+        throw new SolvaPayError(`Update plan failed (${res.status}): ${error}`);
+      }
+      return await res.json();
+    },
+    // DELETE: /v1/sdk/products/{productRef}/plans/{planRef}
+    async deletePlan(productRef, planRef) {
+      const url = `${base}/v1/sdk/products/${productRef}/plans/${planRef}`;
       const res = await fetch(url, {
         method: "DELETE",
         headers
@@ -226,7 +272,7 @@ function createSolvaPayClient(opts) {
           "Idempotency-Key": idempotencyKey
         },
         body: JSON.stringify({
-          agentRef: params.agentRef,
+          productRef: params.productRef,
           planRef: params.planRef,
           customerReference: params.customerRef
         })
@@ -240,7 +286,7 @@ function createSolvaPayClient(opts) {
       return result;
     },
     // POST: /v1/sdk/payment-intents/{paymentIntentId}/process
-    async processPayment(params) {
+    async processPaymentIntent(params) {
       const url = `${base}/v1/sdk/payment-intents/${params.paymentIntentId}/process`;
       const res = await fetch(url, {
         method: "POST",
@@ -249,7 +295,7 @@ function createSolvaPayClient(opts) {
           "Content-Type": "application/json"
         },
         body: JSON.stringify({
-          agentRef: params.agentRef,
+          productRef: params.productRef,
           customerRef: params.customerRef,
           planRef: params.planRef
         })
@@ -262,9 +308,9 @@ function createSolvaPayClient(opts) {
       const result = await res.json();
       return result;
     },
-    // POST: /v1/sdk/subscriptions/{subscriptionRef}/cancel
-    async cancelSubscription(params) {
-      const url = `${base}/v1/sdk/subscriptions/${params.subscriptionRef}/cancel`;
+    // POST: /v1/sdk/purchases/{purchaseRef}/cancel
+    async cancelPurchase(params) {
+      const url = `${base}/v1/sdk/purchases/${params.purchaseRef}/cancel`;
       const requestOptions = {
         method: "POST",
         headers
@@ -277,12 +323,14 @@ function createSolvaPayClient(opts) {
         const error = await res.text();
         log(`\u274C API Error: ${res.status} - ${error}`);
         if (res.status === 404) {
-          throw new SolvaPayError(`Subscription not found: ${error}`);
+          throw new SolvaPayError(`Purchase not found: ${error}`);
         }
         if (res.status === 400) {
-          throw new SolvaPayError(`Subscription cannot be cancelled or does not belong to provider: ${error}`);
+          throw new SolvaPayError(
+            `Purchase cannot be cancelled or does not belong to provider: ${error}`
+          );
         }
-        throw new SolvaPayError(`Cancel subscription failed (${res.status}): ${error}`);
+        throw new SolvaPayError(`Cancel purchase failed (${res.status}): ${error}`);
       }
       const responseText = await res.text();
       let responseData;
@@ -290,26 +338,43 @@ function createSolvaPayClient(opts) {
         responseData = JSON.parse(responseText);
       } catch (parseError) {
         log(`\u274C Failed to parse response as JSON: ${parseError}`);
-        throw new SolvaPayError(`Invalid JSON response from cancel subscription endpoint: ${responseText.substring(0, 200)}`);
+        throw new SolvaPayError(
+          `Invalid JSON response from cancel purchase endpoint: ${responseText.substring(0, 200)}`
+        );
       }
       if (!responseData || typeof responseData !== "object") {
         log(`\u274C Invalid response structure: ${JSON.stringify(responseData)}`);
-        throw new SolvaPayError(`Invalid response structure from cancel subscription endpoint`);
+        throw new SolvaPayError(`Invalid response structure from cancel purchase endpoint`);
       }
       let result;
-      if (responseData.subscription && typeof responseData.subscription === "object") {
-        result = responseData.subscription;
+      if (responseData.purchase && typeof responseData.purchase === "object") {
+        result = responseData.purchase;
       } else if (responseData.reference) {
         result = responseData;
       } else {
-        result = responseData.subscription || responseData;
+        result = responseData.purchase || responseData;
       }
       if (!result || typeof result !== "object") {
-        log(`\u274C Invalid subscription data in response. Full response:`, responseData);
-        throw new SolvaPayError(`Invalid subscription data in cancel subscription response`);
+        log(`\u274C Invalid purchase data in response. Full response:`, responseData);
+        throw new SolvaPayError(`Invalid purchase data in cancel purchase response`);
       }
       return result;
     },
+    // POST: /v1/sdk/user-info
+    async getUserInfo(params) {
+      const url = `${base}/v1/sdk/user-info`;
+      const res = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(params)
+      });
+      if (!res.ok) {
+        const error = await res.text();
+        log(`\u274C API Error: ${res.status} - ${error}`);
+        throw new SolvaPayError(`Get user info failed (${res.status}): ${error}`);
+      }
+      return await res.json();
+    },
     // POST: /v1/sdk/checkout-sessions
     async createCheckoutSession(params) {
       const url = `${base}/v1/sdk/checkout-sessions`;
@@ -392,34 +457,35 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function createRequestDeduplicator(options = {}) {
-  const {
-    cacheTTL = 2e3,
-    maxCacheSize = 1e3,
-    cacheErrors = true
-  } = options;
+  const { cacheTTL = 2e3, maxCacheSize = 1e3, cacheErrors = true } = options;
   const inFlightRequests = /* @__PURE__ */ new Map();
   const resultCache = /* @__PURE__ */ new Map();
-  let cleanupInterval = null;
+  let _cleanupInterval = null;
   if (cacheTTL > 0) {
-    cleanupInterval = setInterval(() => {
-      const now = Date.now();
-      const entriesToDelete = [];
-      for (const [key, cached] of resultCache.entries()) {
-        if (now - cached.timestamp >= cacheTTL) {
-          entriesToDelete.push(key);
+    _cleanupInterval = setInterval(
+      () => {
+        const now = Date.now();
+        const entriesToDelete = [];
+        for (const [key, cached] of resultCache.entries()) {
+          if (now - cached.timestamp >= cacheTTL) {
+            entriesToDelete.push(key);
+          }
         }
-      }
-      for (const key of entriesToDelete) {
-        resultCache.delete(key);
-      }
-      if (resultCache.size > maxCacheSize) {
-        const sortedEntries = Array.from(resultCache.entries()).sort((a, b) => a[1].timestamp - b[1].timestamp);
-        const toRemove = sortedEntries.slice(0, resultCache.size - maxCacheSize);
-        for (const [key] of toRemove) {
+        for (const key of entriesToDelete) {
           resultCache.delete(key);
         }
-      }
-    }, Math.min(cacheTTL, 1e3));
+        if (resultCache.size > maxCacheSize) {
+          const sortedEntries = Array.from(resultCache.entries()).sort(
+            (a, b) => a[1].timestamp - b[1].timestamp
+          );
+          const toRemove = sortedEntries.slice(0, resultCache.size - maxCacheSize);
+          for (const [key] of toRemove) {
+            resultCache.delete(key);
+          }
+        }
+      },
+      Math.min(cacheTTL, 1e3)
+    );
   }
   const deduplicate = async (key, fn) => {
     if (cacheTTL > 0) {
@@ -483,6 +549,12 @@ function createRequestDeduplicator(options = {}) {
 
 // src/paywall.ts
 var PaywallError = class extends Error {
+  /**
+   * Creates a new PaywallError instance.
+   *
+   * @param message - Error message
+   * @param structuredContent - Structured content with checkout URLs and metadata
+   */
   constructor(message, structuredContent) {
     super(message);
     this.structuredContent = structuredContent;
@@ -490,8 +562,8 @@ var PaywallError = class extends Error {
   }
 };
 var sharedCustomerLookupDeduplicator = createRequestDeduplicator({
-  cacheTTL: 5e3,
-  // Cache results for 5 seconds (sufficient for concurrent requests)
+  cacheTTL: 6e4,
+  // Cache results for 60 seconds (reduces API calls significantly)
   maxCacheSize: 1e3,
   // Maximum cache entries
   cacheErrors: false
@@ -501,26 +573,20 @@ var SolvaPayPaywall = class {
   constructor(apiClient, options = {}) {
     this.apiClient = apiClient;
     this.debug = options.debug ?? process.env.SOLVAPAY_DEBUG === "true";
+    this.limitsCacheTTL = options.limitsCacheTTL ?? 1e4;
   }
   customerCreationAttempts = /* @__PURE__ */ new Set();
   customerRefMapping = /* @__PURE__ */ new Map();
-  // input ref -> backend ref
   debug;
+  limitsCache = /* @__PURE__ */ new Map();
+  limitsCacheTTL;
   log(...args) {
     if (this.debug) {
       console.log(...args);
     }
   }
-  resolveAgent(metadata) {
-    return metadata.agent || process.env.SOLVAPAY_AGENT || this.getPackageJsonName() || "default-agent";
-  }
-  getPackageJsonName() {
-    try {
-      const pkg = __require(process.cwd() + "/package.json");
-      return pkg.name;
-    } catch {
-      return void 0;
-    }
+  resolveProduct(metadata) {
+    return metadata.product || process.env.SOLVAPAY_PRODUCT || "default-product";
   }
   generateRequestId() {
     const timestamp = Date.now();
@@ -530,40 +596,102 @@ var SolvaPayPaywall = class {
   /**
    * Core protection method - works for both MCP and HTTP
    */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   async protect(handler, metadata = {}, getCustomerRef) {
-    const agent = this.resolveAgent(metadata);
-    const toolName = handler.name || "anonymous";
+    const product = this.resolveProduct(metadata);
+    const configuredPlanRef = metadata.plan?.trim();
+    const usagePlanRef = configuredPlanRef || "unspecified";
+    const usageType = metadata.usageType || "requests";
     return async (args) => {
       const startTime = Date.now();
       const requestId = this.generateRequestId();
       const inputCustomerRef = getCustomerRef ? getCustomerRef(args) : args.auth?.customer_ref || "anonymous";
-      const backendCustomerRef = await this.ensureCustomer(inputCustomerRef);
+      let backendCustomerRef;
+      if (inputCustomerRef.startsWith("cus_")) {
+        backendCustomerRef = inputCustomerRef;
+      } else {
+        backendCustomerRef = await this.ensureCustomer(inputCustomerRef, inputCustomerRef);
+      }
+      let resolvedMeterName;
       try {
-        const planRef = metadata.plan || toolName;
-        this.log(`\u{1F50D} Checking limits for customer: ${backendCustomerRef}, agent: ${agent}, plan: ${planRef}`);
-        const limitsCheck = await this.apiClient.checkLimits({
-          customerRef: backendCustomerRef,
-          agentRef: agent
-        });
-        this.log(`\u2713 Limits check passed:`, limitsCheck);
-        if (!limitsCheck.withinLimits) {
+        const limitsCacheKey = `${backendCustomerRef}:${product}:${configuredPlanRef || ""}:${usageType}`;
+        const cachedLimits = this.limitsCache.get(limitsCacheKey);
+        const now = Date.now();
+        let withinLimits;
+        let remaining;
+        let checkoutUrl;
+        const hasFreshCachedLimits = cachedLimits && now - cachedLimits.timestamp < this.limitsCacheTTL;
+        if (hasFreshCachedLimits) {
+          checkoutUrl = cachedLimits.checkoutUrl;
+          resolvedMeterName = cachedLimits.meterName;
+          if (cachedLimits.remaining > 0) {
+            cachedLimits.remaining--;
+            if (cachedLimits.remaining <= 0) {
+              this.limitsCache.delete(limitsCacheKey);
+            }
+            withinLimits = true;
+            remaining = cachedLimits.remaining;
+          } else {
+            withinLimits = false;
+            remaining = 0;
+            this.limitsCache.delete(limitsCacheKey);
+          }
+        } else {
+          if (cachedLimits) {
+            this.limitsCache.delete(limitsCacheKey);
+          }
+          const limitsCheck = await this.apiClient.checkLimits({
+            customerRef: backendCustomerRef,
+            productRef: product,
+            ...configuredPlanRef ? { planRef: configuredPlanRef } : {},
+            meterName: usageType
+          });
+          withinLimits = limitsCheck.withinLimits;
+          remaining = limitsCheck.remaining;
+          checkoutUrl = limitsCheck.checkoutUrl;
+          resolvedMeterName = limitsCheck.meterName;
+          const consumedAllowance = withinLimits && remaining > 0;
+          if (consumedAllowance) {
+            remaining = Math.max(0, remaining - 1);
+          }
+          if (consumedAllowance) {
+            this.limitsCache.set(limitsCacheKey, {
+              remaining,
+              checkoutUrl,
+              meterName: resolvedMeterName,
+              timestamp: now
+            });
+          }
+        }
+        if (!withinLimits) {
           const latencyMs2 = Date.now() - startTime;
-          this.log(`\u{1F6AB} Paywall triggered - tracking usage`);
-          await this.trackUsage(backendCustomerRef, agent, planRef, toolName, "paywall", requestId, latencyMs2);
+          this.trackUsage(
+            backendCustomerRef,
+            product,
+            usagePlanRef,
+            resolvedMeterName || usageType,
+            "paywall",
+            requestId,
+            latencyMs2
+          );
           throw new PaywallError("Payment required", {
             kind: "payment_required",
-            agent,
-            checkoutUrl: limitsCheck.checkoutUrl || "",
-            message: `Plan subscription required. Remaining: ${limitsCheck.remaining}`
+            product,
+            checkoutUrl: checkoutUrl || "",
+            message: `Purchase required. Remaining: ${remaining}`
           });
         }
-        this.log(`\u26A1 Executing handler: ${toolName}`);
         const result = await handler(args);
-        this.log(`\u2713 Handler completed successfully`);
         const latencyMs = Date.now() - startTime;
-        this.log(`\u{1F4CA} Tracking successful usage`);
-        await this.trackUsage(backendCustomerRef, agent, planRef, toolName, "success", requestId, latencyMs);
-        this.log(`\u2705 Request completed successfully`);
+        this.trackUsage(
+          backendCustomerRef,
+          product,
+          usagePlanRef,
+          resolvedMeterName || usageType,
+          "success",
+          requestId,
+          latencyMs
+        );
         return result;
       } catch (error) {
         if (error instanceof Error) {
@@ -572,10 +700,18 @@ var SolvaPayPaywall = class {
         } else {
           this.log(`\u274C Error in paywall:`, error);
         }
-        const latencyMs = Date.now() - startTime;
-        const outcome = error instanceof PaywallError ? "paywall" : "fail";
-        const planRef = metadata.plan || toolName;
-        await this.trackUsage(backendCustomerRef, agent, planRef, toolName, outcome, requestId, latencyMs);
+        if (!(error instanceof PaywallError)) {
+          const latencyMs = Date.now() - startTime;
+          this.trackUsage(
+            backendCustomerRef,
+            product,
+            usagePlanRef,
+            resolvedMeterName || usageType,
+            "fail",
+            requestId,
+            latencyMs
+          );
+        }
         throw error;
       }
     };
@@ -585,10 +721,11 @@ var SolvaPayPaywall = class {
    * This is a public helper for testing, pre-creating customers, and internal use.
    * Only attempts creation once per customer (idempotent).
    * Returns the backend customer reference to use in API calls.
-   * 
-   * @param customerRef - The customer reference (e.g., Supabase user ID)
+   *
+   * @param customerRef - The customer reference used as a cache key (e.g., Supabase user ID)
    * @param externalRef - Optional external reference for backend lookup (e.g., Supabase user ID)
-   *   If provided, will lookup existing customer by externalRef before creating new one
+   *   If provided, will lookup existing customer by externalRef before creating new one.
+   *   The externalRef is stored on the SolvaPay backend for customer lookup.
    * @param options - Optional customer details (email, name) for customer creation
    */
   async ensureCustomer(customerRef, externalRef, options) {
@@ -598,97 +735,148 @@ var SolvaPayPaywall = class {
     if (customerRef === "anonymous") {
       return customerRef;
     }
+    if (customerRef.startsWith("cus_")) {
+      return customerRef;
+    }
     const cacheKey = externalRef || customerRef;
     if (this.customerRefMapping.has(customerRef)) {
       const cached = this.customerRefMapping.get(customerRef);
-      this.log(`\u2705 [PER-INSTANCE CACHE HIT] Using cached customer lookup: ${customerRef} -> ${cached}`);
       return cached;
     }
-    const hadPerInstanceCache = this.customerRefMapping.has(customerRef);
-    const backendRef = await sharedCustomerLookupDeduplicator.deduplicate(
-      cacheKey,
-      async () => {
-        if (externalRef && this.apiClient.getCustomerByExternalRef) {
-          try {
-            this.log(`\u{1F50D} Looking up customer by externalRef: ${externalRef}`);
-            const existingCustomer = await this.apiClient.getCustomerByExternalRef({ externalRef });
-            if (existingCustomer && existingCustomer.customerRef) {
-              const ref = existingCustomer.customerRef;
-              this.log(`\u2705 Found existing customer by externalRef: ${externalRef} -> ${ref}`);
-              this.customerRefMapping.set(customerRef, ref);
-              this.customerCreationAttempts.add(customerRef);
-              if (externalRef !== customerRef) {
-                this.customerCreationAttempts.add(externalRef);
-              }
-              return ref;
-            }
-          } catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            if (errorMessage.includes("404") || errorMessage.includes("not found")) {
-              this.log(`\u{1F50D} Customer not found by externalRef, will create new: ${externalRef}`);
-            } else {
-              this.log(`\u26A0\uFE0F  Error looking up customer by externalRef: ${errorMessage}`);
+    const backendRef = await sharedCustomerLookupDeduplicator.deduplicate(cacheKey, async () => {
+      if (externalRef) {
+        try {
+          const existingCustomer = await this.apiClient.getCustomer({ externalRef });
+          if (existingCustomer && existingCustomer.customerRef) {
+            const ref = existingCustomer.customerRef;
+            this.customerRefMapping.set(customerRef, ref);
+            this.customerCreationAttempts.add(customerRef);
+            if (externalRef !== customerRef) {
+              this.customerCreationAttempts.add(externalRef);
             }
+            return ref;
+          }
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          if (!errorMessage.includes("404") && !errorMessage.includes("not found")) {
+            this.log(`\u26A0\uFE0F  Error looking up customer by externalRef: ${errorMessage}`);
           }
         }
-        if (this.customerCreationAttempts.has(customerRef) || externalRef && this.customerCreationAttempts.has(externalRef)) {
-          const mappedRef = this.customerRefMapping.get(customerRef);
-          return mappedRef || customerRef;
+      }
+      if (this.customerCreationAttempts.has(customerRef) || externalRef && this.customerCreationAttempts.has(externalRef)) {
+        const mappedRef = this.customerRefMapping.get(customerRef);
+        return mappedRef || customerRef;
+      }
+      if (!this.apiClient.createCustomer) {
+        console.warn(
+          `\u26A0\uFE0F  Cannot auto-create customer ${customerRef}: createCustomer method not available on API client`
+        );
+        return customerRef;
+      }
+      this.customerCreationAttempts.add(customerRef);
+      try {
+        const createParams = {
+          email: options?.email || `${customerRef}-${Date.now()}@auto-created.local`
+        };
+        if (options?.name) {
+          createParams.name = options.name;
         }
-        if (!this.apiClient.createCustomer) {
-          console.warn(`\u26A0\uFE0F  Cannot auto-create customer ${customerRef}: createCustomer method not available on API client`);
-          return customerRef;
+        if (externalRef) {
+          createParams.externalRef = externalRef;
         }
-        this.customerCreationAttempts.add(customerRef);
-        try {
-          this.log(`\u{1F527} Auto-creating customer: ${customerRef}${externalRef ? ` (externalRef: ${externalRef})` : ""}`);
-          const createParams = {
-            email: options?.email || `${customerRef}@auto-created.local`,
-            name: options?.name || customerRef
-          };
+        const result = await this.apiClient.createCustomer(createParams);
+        const resultObj = result;
+        const ref = resultObj.customerRef || resultObj.reference || customerRef;
+        this.customerRefMapping.set(customerRef, ref);
+        return ref;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (errorMessage.includes("409") || errorMessage.includes("already exists")) {
           if (externalRef) {
-            createParams.externalRef = externalRef;
+            try {
+              const searchResult = await this.apiClient.getCustomer({ externalRef });
+              if (searchResult && searchResult.customerRef) {
+                this.customerRefMapping.set(customerRef, searchResult.customerRef);
+                return searchResult.customerRef;
+              }
+            } catch (lookupError) {
+              this.log(`\u26A0\uFE0F Failed to lookup existing customer by externalRef after 409:`, lookupError instanceof Error ? lookupError.message : lookupError);
+            }
           }
-          const result = await this.apiClient.createCustomer(createParams);
-          const ref = result.customerRef || result.reference || customerRef;
-          this.log(`\u2705 Successfully created customer: ${customerRef} -> ${ref}`, result);
-          this.log(`\u{1F50D} DEBUG - ensureCustomer analysis:`);
-          this.log(`   - Input customerRef: ${customerRef}`);
-          this.log(`   - ExternalRef: ${externalRef || "none"}`);
-          this.log(`   - Backend customerRef: ${ref}`);
-          this.log(`   - Has plan in response: ${result.plan ? "YES - " + result.plan : "NO"}`);
-          this.log(`   - Has subscription in response: ${result.subscription ? "YES" : "NO"}`);
-          this.customerRefMapping.set(customerRef, ref);
-          return ref;
-        } catch (error) {
-          this.log(`\u274C Failed to auto-create customer ${customerRef}:`, error instanceof Error ? error.message : error);
-          return customerRef;
+          const isEmailConflict = errorMessage.includes("email") || errorMessage.includes("identifier email");
+          if (externalRef && isEmailConflict && options?.email) {
+            try {
+              const byEmail = await this.apiClient.getCustomer({ email: options.email });
+              if (byEmail && byEmail.customerRef) {
+                this.customerRefMapping.set(customerRef, byEmail.customerRef);
+                this.log(
+                  `\u26A0\uFE0F Resolved customer ${customerRef} by email after conflict; using existing customer ${byEmail.customerRef}`
+                );
+                return byEmail.customerRef;
+              }
+            } catch (emailLookupError) {
+              this.log(
+                `\u26A0\uFE0F Email lookup failed after customer conflict for ${customerRef}:`,
+                emailLookupError instanceof Error ? emailLookupError.message : emailLookupError
+              );
+            }
+            try {
+              const retryParams = {
+                email: `${customerRef}-${Date.now()}@auto-created.local`,
+                externalRef
+              };
+              if (options?.name) {
+                retryParams.name = options.name;
+              }
+              const retryResult = await this.apiClient.createCustomer(retryParams);
+              const retryObj = retryResult;
+              const retryRef = retryObj.customerRef || retryObj.reference || customerRef;
+              this.customerRefMapping.set(customerRef, retryRef);
+              this.log(
+                `\u26A0\uFE0F Retried customer creation for ${customerRef} with generated email after email conflict`
+              );
+              return retryRef;
+            } catch (retryError) {
+              this.log(
+                `\u26A0\uFE0F Retry create customer with generated email failed for ${customerRef}:`,
+                retryError instanceof Error ? retryError.message : retryError
+              );
+            }
+          }
+          const unresolvedMessage = errorMessage || "Customer already exists but could not be resolved";
+          throw new Error(
+            `Failed to resolve existing customer for ${customerRef} after conflict: ${unresolvedMessage}. Ensure the existing customer is linked to this externalRef.`
+          );
         }
+        this.log(
+          `\u274C Failed to auto-create customer ${customerRef}:`,
+          error instanceof Error ? error.message : error
+        );
+        throw error;
       }
-    );
+    });
     if (backendRef !== customerRef) {
       this.customerRefMapping.set(customerRef, backendRef);
     }
     return backendRef;
   }
-  async trackUsage(customerRef, agentRef, planRef, toolName, outcome, requestId, actionDuration) {
+  async trackUsage(customerRef, _productRef, _planRef, action, outcome, requestId, actionDuration) {
     await withRetry(
       () => this.apiClient.trackUsage({
         customerRef,
-        agentRef,
-        planRef,
+        actionType: "api_call",
+        units: 1,
         outcome,
-        action: toolName,
-        requestId,
-        actionDuration,
+        productReference: _productRef,
+        duration: actionDuration,
+        metadata: { action: action || "api_requests", requestId },
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       }),
       {
         maxRetries: 2,
         initialDelay: 500,
         shouldRetry: (error) => error.message.includes("Customer not found"),
-        // TODO: review if this is needed and what to check for 
-        onRetry: (error, attempt) => {
+        onRetry: (_error, attempt) => {
           console.warn(`\u26A0\uFE0F  Customer not found (attempt ${attempt + 1}/3), retrying in 500ms...`);
         }
       }
@@ -707,9 +895,6 @@ var AdapterUtils = class {
     if (!customerRef || customerRef === "anonymous") {
       return "anonymous";
     }
-    if (!customerRef.startsWith("customer_") && !customerRef.startsWith("demo_")) {
-      return `customer_${customerRef.replace(/[^a-zA-Z0-9]/g, "_")}`;
-    }
     return customerRef;
   }
   /**
@@ -717,7 +902,7 @@ var AdapterUtils = class {
    */
   static async extractFromJWT(token, options) {
     try {
-      const { jwtVerify } = await import("./esm-5GYCIXIY.js");
+      const { jwtVerify } = await import("./webapi-K5XBCEO6.js");
       const jwtSecret = new TextEncoder().encode(
         options?.secret || process.env.OAUTH_JWKS_SECRET || "test-jwt-secret"
       );
@@ -726,19 +911,25 @@ var AdapterUtils = class {
         audience: options?.audience || process.env.OAUTH_CLIENT_ID || "test-client-id"
       });
       return payload.sub || null;
-    } catch (error) {
+    } catch {
       return null;
     }
   }
 };
 async function createAdapterHandler(adapter, paywall, metadata, businessLogic) {
+  const backendRefCache = /* @__PURE__ */ new Map();
+  const getCustomerRef = (args) => args.auth?.customer_ref || "anonymous";
+  const protectedHandler = await paywall.protect(businessLogic, metadata, getCustomerRef);
   return async (context) => {
     try {
       const args = await adapter.extractArgs(context);
       const customerRef = await adapter.getCustomerRef(context);
-      args.auth = { customer_ref: customerRef };
-      const getCustomerRef = (args2) => args2.auth.customer_ref;
-      const protectedHandler = await paywall.protect(businessLogic, metadata, getCustomerRef);
+      let backendRef = backendRefCache.get(customerRef);
+      if (!backendRef) {
+        backendRef = await paywall.ensureCustomer(customerRef, customerRef);
+        backendRefCache.set(customerRef, backendRef);
+      }
+      args.auth = { customer_ref: backendRef };
       const result = await protectedHandler(args);
       return adapter.formatResponse(result, context);
     } catch (error) {
@@ -796,7 +987,7 @@ var HttpAdapter = class {
       const errorResponse2 = {
         success: false,
         error: "Payment required",
-        agent: error.structuredContent.agent,
+        product: error.structuredContent.product,
         checkoutUrl: error.structuredContent.checkoutUrl,
         message: error.structuredContent.message
       };
@@ -840,7 +1031,7 @@ var NextAdapter = class {
       if (request.method !== "GET" && request.headers.get("content-type")?.includes("application/json")) {
         body = await request.json();
       }
-    } catch (error) {
+    } catch {
     }
     let routeParams = {};
     if (context?.params) {
@@ -869,6 +1060,10 @@ var NextAdapter = class {
         return AdapterUtils.ensureCustomerRef(jwtSub);
       }
     }
+    const userId = request.headers.get("x-user-id");
+    if (userId) {
+      return AdapterUtils.ensureCustomerRef(userId);
+    }
     const headerRef = request.headers.get("x-customer-ref");
     if (headerRef) {
       return AdapterUtils.ensureCustomerRef(headerRef);
@@ -884,24 +1079,30 @@ var NextAdapter = class {
   }
   formatError(error, _context) {
     if (error instanceof PaywallError) {
-      return new Response(JSON.stringify({
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: "Payment required",
+          product: error.structuredContent.product,
+          checkoutUrl: error.structuredContent.checkoutUrl,
+          message: error.structuredContent.message
+        }),
+        {
+          status: 402,
+          headers: { "Content-Type": "application/json" }
+        }
+      );
+    }
+    return new Response(
+      JSON.stringify({
         success: false,
-        error: "Payment required",
-        agent: error.structuredContent.agent,
-        checkoutUrl: error.structuredContent.checkoutUrl,
-        message: error.structuredContent.message
-      }), {
-        status: 402,
+        error: error instanceof Error ? error.message : "Internal server error"
+      }),
+      {
+        status: 500,
         headers: { "Content-Type": "application/json" }
-      });
-    }
-    return new Response(JSON.stringify({
-      success: false,
-      error: error instanceof Error ? error.message : "Internal server error"
-    }), {
-      status: 500,
-      headers: { "Content-Type": "application/json" }
-    });
+      }
+    );
   }
 };
 
@@ -918,43 +1119,58 @@ var McpAdapter = class {
       const ref = await this.options.getCustomerRef(args);
       return AdapterUtils.ensureCustomerRef(ref);
     }
-    const customerRef = args?.auth?.customer_ref || "anonymous";
+    const auth = args?.auth;
+    const customerRef = auth?.customer_ref || "anonymous";
     return AdapterUtils.ensureCustomerRef(customerRef);
   }
   formatResponse(result, _context) {
     const transformed = this.options.transformResponse ? this.options.transformResponse(result) : result;
     return {
-      content: [{
-        type: "text",
-        text: JSON.stringify(transformed, null, 2)
-      }]
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(transformed, null, 2)
+        }
+      ]
     };
   }
   formatError(error, _context) {
     if (error instanceof PaywallError) {
       return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            success: false,
-            error: "Payment required",
-            agent: error.structuredContent.agent,
-            checkoutUrl: error.structuredContent.checkoutUrl,
-            message: error.structuredContent.message
-          }, null, 2)
-        }],
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                success: false,
+                error: "Payment required",
+                product: error.structuredContent.product,
+                checkoutUrl: error.structuredContent.checkoutUrl,
+                message: error.structuredContent.message
+              },
+              null,
+              2
+            )
+          }
+        ],
         isError: true,
         structuredContent: error.structuredContent
       };
     }
     return {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          success: false,
-          error: error instanceof Error ? error.message : "Unknown error occurred"
-        }, null, 2)
-      }],
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              success: false,
+              error: error instanceof Error ? error.message : "Unknown error occurred"
+            },
+            null,
+            2
+          )
+        }
+      ],
       isError: true
     };
   }
@@ -962,6 +1178,141 @@ var McpAdapter = class {
 
 // src/factory.ts
 import { SolvaPayError as SolvaPayError2, getSolvaPayConfig } from "@solvapay/core";
+
+// src/virtual-tools.ts
+var TOOL_GET_USER_INFO = {
+  name: "get_user_info",
+  description: "Get information about the current user and their purchase status for this MCP server. Returns user profile (reference, name, email) and active purchase details including product name, type, dates, and usage limit if applicable.",
+  inputSchema: {
+    type: "object",
+    properties: {},
+    required: []
+  }
+};
+var TOOL_UPGRADE = {
+  name: "upgrade",
+  description: "Get available pricing options and checkout URLs for upgrading. Returns a list of available pricing options with their details (price, features) and checkout URLs. Users can click on a checkout URL to purchase. If a specific planRef is provided, returns only the checkout URL for that pricing option.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      planRef: {
+        type: "string",
+        description: 'Optional pricing reference (e.g., "pln_abc123") to get a checkout URL for a specific option. If not provided, returns all available pricing options with their checkout URLs.'
+      }
+    },
+    required: []
+  }
+};
+var TOOL_MANAGE_ACCOUNT = {
+  name: "manage_account",
+  description: "Get a URL to the customer portal where users can view and manage their account. The portal shows current account status, billing history, and allows subscription changes. Returns a secure, time-limited URL that the user can click to access their account management page.",
+  inputSchema: {
+    type: "object",
+    properties: {},
+    required: []
+  }
+};
+var VIRTUAL_TOOL_DEFINITIONS = [TOOL_GET_USER_INFO, TOOL_UPGRADE, TOOL_MANAGE_ACCOUNT];
+function mcpTextResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+function mcpErrorResult(message) {
+  return { content: [{ type: "text", text: JSON.stringify({ error: message }) }], isError: true };
+}
+function createGetUserInfoHandler(apiClient, productRef, getCustomerRef) {
+  return async (args) => {
+    const customerRef = getCustomerRef(args);
+    try {
+      if (!apiClient.getUserInfo) {
+        return mcpErrorResult("getUserInfo is not available on this API client");
+      }
+      const userInfo = await apiClient.getUserInfo({ customerRef, productRef });
+      return mcpTextResult(JSON.stringify(userInfo, null, 2));
+    } catch (error) {
+      return mcpErrorResult(
+        `Failed to retrieve user information: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  };
+}
+function createUpgradeHandler(apiClient, productRef, getCustomerRef) {
+  return async (args) => {
+    const customerRef = getCustomerRef(args);
+    const planRef = typeof args.planRef === "string" ? args.planRef : void 0;
+    try {
+      const result = await apiClient.createCheckoutSession({
+        customerReference: customerRef,
+        productRef,
+        ...planRef && { planRef }
+      });
+      const checkoutUrl = result.checkoutUrl;
+      if (planRef) {
+        const responseText2 = `## Upgrade
+
+**[Click here to upgrade \u2192](${checkoutUrl})**
+
+After completing the checkout, your purchase will be activated immediately.`;
+        return mcpTextResult(responseText2);
+      }
+      const responseText = `## Upgrade Your Subscription
+
+**[Click here to view pricing options and upgrade \u2192](${checkoutUrl})**
+
+You'll be able to compare options and select the one that's right for you.`;
+      return mcpTextResult(responseText);
+    } catch (error) {
+      return mcpErrorResult(
+        `Failed to create checkout session: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  };
+}
+function createManageAccountHandler(apiClient, productRef, getCustomerRef) {
+  return async (args) => {
+    const customerRef = getCustomerRef(args);
+    try {
+      const session = await apiClient.createCustomerSession({ customerRef, productRef });
+      const portalUrl = session.customerUrl;
+      const responseText = `## Manage Your Account
+
+Access your account management portal to:
+- View your current account status
+- See billing history and invoices
+- Update payment methods
+- Cancel or modify your subscription
+
+**[Open Account Portal \u2192](${portalUrl})**
+
+This link is secure and will expire after a short period.`;
+      return mcpTextResult(responseText);
+    } catch (error) {
+      return mcpErrorResult(
+        `Failed to create customer portal session: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  };
+}
+function createVirtualTools(apiClient, options) {
+  const { product, getCustomerRef, exclude = [] } = options;
+  const excludeSet = new Set(exclude);
+  const allTools = [
+    {
+      ...TOOL_GET_USER_INFO,
+      handler: createGetUserInfoHandler(apiClient, product, getCustomerRef)
+    },
+    {
+      ...TOOL_UPGRADE,
+      handler: createUpgradeHandler(apiClient, product, getCustomerRef)
+    },
+    {
+      ...TOOL_MANAGE_ACCOUNT,
+      handler: createManageAccountHandler(apiClient, product, getCustomerRef)
+    }
+  ];
+  return allTools.filter((t) => !excludeSet.has(t.name));
+}
+
+// src/factory.ts
 function createSolvaPay(config) {
   let resolvedConfig;
   if (!config) {
@@ -978,7 +1329,8 @@ function createSolvaPay(config) {
     apiBaseUrl: resolvedConfig.apiBaseUrl
   });
   const paywall = new SolvaPayPaywall(apiClient, {
-    debug: process.env.SOLVAPAY_DEBUG !== "false"
+    debug: process.env.SOLVAPAY_DEBUG !== "false",
+    limitsCacheTTL: resolvedConfig.limitsCacheTTL
   });
   return {
     // Direct access to API client for advanced operations
@@ -993,11 +1345,11 @@ function createSolvaPay(config) {
       }
       return apiClient.createPaymentIntent(params);
     },
-    processPayment(params) {
-      if (!apiClient.processPayment) {
-        throw new SolvaPayError2("processPayment is not available on this API client");
+    processPaymentIntent(params) {
+      if (!apiClient.processPaymentIntent) {
+        throw new SolvaPayError2("processPaymentIntent is not available on this API client");
       }
-      return apiClient.processPayment(params);
+      return apiClient.processPaymentIntent(params);
     },
     checkLimits(params) {
       return apiClient.checkLimits(params);
@@ -1012,91 +1364,507 @@ function createSolvaPay(config) {
       return apiClient.createCustomer(params);
     },
     getCustomer(params) {
-      if (!apiClient.getCustomer) {
-        throw new SolvaPayError2("getCustomer is not available on this API client");
-      }
       return apiClient.getCustomer(params);
     },
     createCheckoutSession(params) {
-      return apiClient.createCheckoutSession(params);
+      return apiClient.createCheckoutSession({
+        customerReference: params.customerRef,
+        productRef: params.productRef,
+        planRef: params.planRef
+      });
     },
     createCustomerSession(params) {
       return apiClient.createCustomerSession(params);
     },
+    bootstrapMcpProduct(params) {
+      if (!apiClient.bootstrapMcpProduct) {
+        throw new SolvaPayError2("bootstrapMcpProduct is not available on this API client");
+      }
+      return apiClient.bootstrapMcpProduct(params);
+    },
+    getVirtualTools(options) {
+      return createVirtualTools(apiClient, options);
+    },
     // Payable API for framework-specific handlers
     payable(options = {}) {
-      const agent = options.agentRef || options.agent || process.env.SOLVAPAY_AGENT || getPackageJsonName() || "default-agent";
-      const plan = options.planRef || options.plan || agent;
-      const metadata = { agent, plan };
+      const product = options.productRef || options.product || process.env.SOLVAPAY_PRODUCT || "default-product";
+      const plan = options.planRef || options.plan;
+      const usageType = options.usageType || "requests";
+      const metadata = { product, plan, usageType };
       return {
-        // HTTP adapter for Express/Fastify
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         http(businessLogic, adapterOptions) {
-          const adapter = new HttpAdapter(adapterOptions);
+          const adapter = new HttpAdapter({
+            ...adapterOptions,
+            getCustomerRef: adapterOptions?.getCustomerRef || options.getCustomerRef
+          });
+          const handlerPromise = createAdapterHandler(adapter, paywall, metadata, businessLogic);
           return async (req, reply) => {
-            const handler = await createAdapterHandler(
-              adapter,
-              paywall,
-              metadata,
-              businessLogic
-            );
+            const handler = await handlerPromise;
             return handler([req, reply]);
           };
         },
-        // Next.js adapter for App Router
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         next(businessLogic, adapterOptions) {
-          const adapter = new NextAdapter(adapterOptions);
+          const adapter = new NextAdapter({
+            ...adapterOptions,
+            getCustomerRef: adapterOptions?.getCustomerRef || options.getCustomerRef
+          });
+          const handlerPromise = createAdapterHandler(adapter, paywall, metadata, businessLogic);
           return async (request, context) => {
-            const handler = await createAdapterHandler(
-              adapter,
-              paywall,
-              metadata,
-              businessLogic
-            );
+            const handler = await handlerPromise;
             return handler([request, context]);
           };
         },
-        // MCP adapter for Model Context Protocol
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         mcp(businessLogic, adapterOptions) {
-          const adapter = new McpAdapter(adapterOptions);
+          const adapter = new McpAdapter({
+            ...adapterOptions,
+            getCustomerRef: adapterOptions?.getCustomerRef || options.getCustomerRef
+          });
+          const handlerPromise = createAdapterHandler(adapter, paywall, metadata, businessLogic);
           return async (args) => {
-            const handler = await createAdapterHandler(
-              adapter,
-              paywall,
-              metadata,
-              businessLogic
-            );
+            const handler = await handlerPromise;
             return handler(args);
           };
         },
-        // Pure function adapter for direct protection
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         async function(businessLogic) {
-          const getCustomerRef = (args) => args.auth?.customer_ref || "anonymous";
+          const getCustomerRef = (args) => {
+            const configuredRef = options.getCustomerRef?.(args);
+            if (typeof configuredRef === "string") {
+              return configuredRef;
+            }
+            return args.auth?.customer_ref || "anonymous";
+          };
           return paywall.protect(businessLogic, metadata, getCustomerRef);
         }
       };
     }
   };
 }
-function getPackageJsonName() {
+
+// src/mcp-auth.ts
+var McpBearerAuthError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "McpBearerAuthError";
+  }
+};
+function base64UrlDecode(input) {
+  const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = normalized.padEnd(normalized.length + (4 - normalized.length % 4) % 4, "=");
+  return Buffer.from(padded, "base64").toString("utf8");
+}
+function extractBearerToken(authorization) {
+  if (!authorization) return null;
+  if (!authorization.startsWith("Bearer ")) return null;
+  return authorization.slice(7).trim() || null;
+}
+function decodeJwtPayload(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) {
+    throw new McpBearerAuthError("Invalid JWT format");
+  }
   try {
-    const pkg = __require(process.cwd() + "/package.json");
-    return pkg.name;
+    const payloadText = base64UrlDecode(parts[1]);
+    const payload = JSON.parse(payloadText);
+    return payload;
   } catch {
-    return void 0;
+    throw new McpBearerAuthError("Invalid JWT payload");
+  }
+}
+function getCustomerRefFromJwtPayload(payload, options = {}) {
+  const claimPriority = options.claimPriority || ["customerRef", "customer_ref", "sub"];
+  for (const claim of claimPriority) {
+    const value = payload[claim];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  throw new McpBearerAuthError(
+    `No customer reference claim found (checked: ${claimPriority.join(", ")})`
+  );
+}
+function getCustomerRefFromBearerAuthHeader(authorization, options = {}) {
+  const token = extractBearerToken(authorization);
+  if (!token) {
+    throw new McpBearerAuthError("Missing bearer token");
+  }
+  const payload = decodeJwtPayload(token);
+  return getCustomerRefFromJwtPayload(payload, options);
+}
+
+// src/helpers/error.ts
+import { SolvaPayError as SolvaPayError3 } 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 SolvaPayError3) {
+    const errorMessage2 = error.message;
+    return {
+      error: errorMessage2,
+      status: 500,
+      details: errorMessage2
+    };
+  }
+  const errorMessage = error instanceof Error ? error.message : "Unknown error";
+  const message = defaultMessage || `${operationName} failed`;
+  return {
+    error: message,
+    status: 500,
+    details: errorMessage
+  };
+}
+
+// src/helpers/auth.ts
+async function getAuthenticatedUserCore(request, options = {}) {
+  try {
+    const { requireUserId, getUserEmailFromRequest, getUserNameFromRequest } = await import("@solvapay/auth");
+    const userIdOrError = requireUserId(request);
+    if (userIdOrError instanceof Response) {
+      const clonedResponse = userIdOrError.clone();
+      const body = await clonedResponse.json().catch(() => ({ error: "Unauthorized" }));
+      return {
+        error: body.error || "Unauthorized",
+        status: userIdOrError.status,
+        details: body.error || "Unauthorized"
+      };
+    }
+    const userId = userIdOrError;
+    const email = options.includeEmail !== false ? await getUserEmailFromRequest(request) : null;
+    const name = options.includeName !== false ? await getUserNameFromRequest(request) : null;
+    return {
+      userId,
+      email,
+      name
+    };
+  } catch (error) {
+    return handleRouteError(error, "Get authenticated user", "Authentication failed");
+  }
+}
+
+// src/helpers/customer.ts
+async function syncCustomerCore(request, options = {}) {
+  try {
+    const userResult = await getAuthenticatedUserCore(request, {
+      includeEmail: options.includeEmail,
+      includeName: options.includeName
+    });
+    if (isErrorResult(userResult)) {
+      return userResult;
+    }
+    const { userId, email, name } = userResult;
+    const solvaPay = options.solvaPay || createSolvaPay();
+    const customerRef = await solvaPay.ensureCustomer(userId, userId, {
+      email: email || void 0,
+      name: name || void 0
+    });
+    return customerRef;
+  } catch (error) {
+    return handleRouteError(error, "Sync customer", "Failed to sync customer");
+  }
+}
+
+// src/helpers/payment.ts
+async function createPaymentIntentCore(request, body, options = {}) {
+  try {
+    if (!body.planRef || !body.productRef) {
+      return {
+        error: "Missing required parameters: planRef and productRef are required",
+        status: 400
+      };
+    }
+    const customerResult = await syncCustomerCore(request, {
+      solvaPay: options.solvaPay,
+      includeEmail: options.includeEmail,
+      includeName: options.includeName
+    });
+    if (isErrorResult(customerResult)) {
+      return customerResult;
+    }
+    const customerRef = customerResult;
+    const solvaPay = options.solvaPay || createSolvaPay();
+    const paymentIntent = await solvaPay.createPaymentIntent({
+      productRef: body.productRef,
+      planRef: body.planRef,
+      customerRef
+    });
+    return {
+      id: paymentIntent.id,
+      clientSecret: paymentIntent.clientSecret,
+      publishableKey: paymentIntent.publishableKey,
+      accountId: paymentIntent.accountId,
+      customerRef
+    };
+  } catch (error) {
+    return handleRouteError(error, "Create payment intent", "Payment intent creation failed");
+  }
+}
+async function processPaymentIntentCore(request, body, options = {}) {
+  try {
+    if (!body.paymentIntentId || !body.productRef) {
+      return {
+        error: "paymentIntentId and productRef are required",
+        status: 400
+      };
+    }
+    const customerResult = await syncCustomerCore(request, {
+      solvaPay: options.solvaPay
+    });
+    if (isErrorResult(customerResult)) {
+      return customerResult;
+    }
+    const customerRef = customerResult;
+    const solvaPay = options.solvaPay || createSolvaPay();
+    const result = await solvaPay.processPaymentIntent({
+      paymentIntentId: body.paymentIntentId,
+      productRef: body.productRef,
+      customerRef,
+      planRef: body.planRef
+    });
+    return result;
+  } catch (error) {
+    return handleRouteError(error, "Process payment intent", "Payment processing failed");
+  }
+}
+
+// src/helpers/checkout.ts
+async function createCheckoutSessionCore(request, body, options = {}) {
+  try {
+    if (!body.productRef) {
+      return {
+        error: "Missing required parameter: productRef is required",
+        status: 400
+      };
+    }
+    const customerResult = await syncCustomerCore(request, {
+      solvaPay: options.solvaPay,
+      includeEmail: options.includeEmail,
+      includeName: options.includeName
+    });
+    if (isErrorResult(customerResult)) {
+      return customerResult;
+    }
+    const customerRef = customerResult;
+    let returnUrl = body.returnUrl || options.returnUrl;
+    if (!returnUrl) {
+      try {
+        const url = new URL(request.url);
+        returnUrl = url.origin;
+      } catch {
+      }
+    }
+    const solvaPay = options.solvaPay || createSolvaPay();
+    const session = await solvaPay.createCheckoutSession({
+      productRef: body.productRef,
+      customerRef,
+      planRef: body.planRef || void 0,
+      returnUrl
+    });
+    return {
+      sessionId: session.sessionId,
+      checkoutUrl: session.checkoutUrl
+    };
+  } catch (error) {
+    return handleRouteError(error, "Create checkout session", "Checkout session creation failed");
+  }
+}
+async function createCustomerSessionCore(request, options = {}) {
+  try {
+    const customerResult = await syncCustomerCore(request, {
+      solvaPay: options.solvaPay,
+      includeEmail: options.includeEmail,
+      includeName: options.includeName
+    });
+    if (isErrorResult(customerResult)) {
+      return customerResult;
+    }
+    const customerRef = customerResult;
+    const solvaPay = options.solvaPay || createSolvaPay();
+    const session = await solvaPay.createCustomerSession({
+      customerRef
+    });
+    return session;
+  } catch (error) {
+    return handleRouteError(error, "Create customer session", "Customer session creation failed");
+  }
+}
+
+// src/helpers/renewal.ts
+import { SolvaPayError as SolvaPayError4 } from "@solvapay/core";
+async function cancelPurchaseCore(request, body, options = {}) {
+  try {
+    if (!body.purchaseRef) {
+      return {
+        error: "Missing required parameter: purchaseRef is required",
+        status: 400
+      };
+    }
+    const solvaPay = options.solvaPay || createSolvaPay();
+    if (!solvaPay.apiClient.cancelPurchase) {
+      return {
+        error: "Cancel purchase method not available on SDK client",
+        status: 500
+      };
+    }
+    let cancelledPurchase = await solvaPay.apiClient.cancelPurchase({
+      purchaseRef: body.purchaseRef,
+      reason: body.reason
+    });
+    if (!cancelledPurchase || typeof cancelledPurchase !== "object") {
+      return {
+        error: "Invalid response from cancel purchase endpoint",
+        status: 500
+      };
+    }
+    const responseObj = cancelledPurchase;
+    if (responseObj.purchase && typeof responseObj.purchase === "object") {
+      cancelledPurchase = responseObj.purchase;
+    }
+    if (!cancelledPurchase.reference) {
+      return {
+        error: "Cancel purchase response missing required fields",
+        status: 500
+      };
+    }
+    const isCancelled = cancelledPurchase.status === "cancelled" || cancelledPurchase.cancelledAt;
+    if (!isCancelled) {
+      return {
+        error: `Purchase cancellation failed: backend returned status '${cancelledPurchase.status}' without cancelledAt timestamp`,
+        status: 500
+      };
+    }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    return cancelledPurchase;
+  } catch (error) {
+    if (error instanceof SolvaPayError4) {
+      const errorMessage = error.message;
+      if (errorMessage.includes("not found")) {
+        return {
+          error: "Purchase not found",
+          status: 404,
+          details: errorMessage
+        };
+      }
+      if (errorMessage.includes("cannot be cancelled") || errorMessage.includes("does not belong to provider")) {
+        return {
+          error: "Purchase cannot be cancelled or does not belong to provider",
+          status: 400,
+          details: errorMessage
+        };
+      }
+      return {
+        error: errorMessage,
+        status: 500,
+        details: errorMessage
+      };
+    }
+    return handleRouteError(error, "Cancel purchase", "Failed to cancel purchase");
+  }
+}
+
+// src/helpers/plans.ts
+import { getSolvaPayConfig as getSolvaPayConfig2 } from "@solvapay/core";
+async function listPlansCore(request) {
+  try {
+    const url = new URL(request.url);
+    const productRef = url.searchParams.get("productRef");
+    if (!productRef) {
+      return {
+        error: "Missing required parameter: productRef",
+        status: 400
+      };
+    }
+    const config = getSolvaPayConfig2();
+    const solvapaySecretKey = config.apiKey;
+    const solvapayApiBaseUrl = config.apiBaseUrl;
+    if (!solvapaySecretKey) {
+      return {
+        error: "Server configuration error: SolvaPay secret key not configured",
+        status: 500
+      };
+    }
+    const apiClient = createSolvaPayClient({
+      apiKey: solvapaySecretKey,
+      apiBaseUrl: solvapayApiBaseUrl
+    });
+    if (!apiClient.listPlans) {
+      return {
+        error: "List plans method not available",
+        status: 500
+      };
+    }
+    const plans = await apiClient.listPlans(productRef);
+    return {
+      plans: plans || [],
+      productRef
+    };
+  } catch (error) {
+    return handleRouteError(error, "List plans", "Failed to fetch plans");
   }
 }
 
 // src/index.ts
-function verifyWebhook({ body, signature, secret }) {
-  const hmac = crypto.createHmac("sha256", secret).update(body).digest("hex");
-  const ok = crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(signature));
-  if (!ok) throw new SolvaPayError3("Invalid webhook signature");
-  return JSON.parse(body);
+function verifyWebhook({
+  body,
+  signature,
+  secret
+}) {
+  const toleranceSec = 300;
+  if (!signature) throw new SolvaPayError5("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 SolvaPayError5("Malformed webhook signature");
+  }
+  const timestamp = parseInt(tPart.slice(2), 10);
+  const receivedHmac = v1Part.slice(3);
+  if (Number.isNaN(timestamp) || !receivedHmac) {
+    throw new SolvaPayError5("Malformed webhook signature");
+  }
+  if (toleranceSec > 0) {
+    const age = Math.abs(Math.floor(Date.now() / 1e3) - timestamp);
+    if (age > toleranceSec) {
+      throw new SolvaPayError5("Webhook signature timestamp too old");
+    }
+  }
+  const expectedHmac = crypto.createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
+  if (receivedHmac.length !== expectedHmac.length) {
+    throw new SolvaPayError5("Invalid webhook signature");
+  }
+  const ok = crypto.timingSafeEqual(Buffer.from(expectedHmac), Buffer.from(receivedHmac));
+  if (!ok) throw new SolvaPayError5("Invalid webhook signature");
+  try {
+    return JSON.parse(body);
+  } catch {
+    throw new SolvaPayError5("Invalid webhook payload: body is not valid JSON");
+  }
 }
 export {
+  McpBearerAuthError,
   PaywallError,
+  VIRTUAL_TOOL_DEFINITIONS,
+  cancelPurchaseCore,
+  createCheckoutSessionCore,
+  createCustomerSessionCore,
+  createPaymentIntentCore,
   createSolvaPay,
   createSolvaPayClient,
+  createVirtualTools,
+  decodeJwtPayload,
+  extractBearerToken,
+  getAuthenticatedUserCore,
+  getCustomerRefFromBearerAuthHeader,
+  getCustomerRefFromJwtPayload,
+  handleRouteError,
+  isErrorResult,
+  listPlansCore,
+  processPaymentIntentCore,
+  syncCustomerCore,
   verifyWebhook,
   withRetry
 };