@solvapay/server 1.0.0-preview.2 → 1.0.0-preview.21

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) => {
@@ -21,15 +19,10 @@ function createSolvaPayClient(opts) {
       console.log(...args);
     }
   };
-  log(`\u{1F50C} SolvaPay API Client initialized`);
-  log(`   Backend URL: ${base}`);
-  log(`   API Key: ${opts.apiKey.substring(0, 10)}...`);
   return {
     // POST: /v1/sdk/limits
     async checkLimits(params) {
       const url = `${base}/v1/sdk/limits`;
-      log(`\u{1F4E1} API Request: POST ${url}`);
-      log(`   Params:`, JSON.stringify(params, null, 2));
       const res = await fetch(url, {
         method: "POST",
         headers,
@@ -41,37 +34,27 @@ function createSolvaPayClient(opts) {
         throw new SolvaPayError(`Check limits failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      log(`\u2705 API Response:`, JSON.stringify(result, null, 2));
-      log(`\u{1F50D} DEBUG - checkLimits breakdown:`);
-      log(`   - withinLimits: ${result.withinLimits}`);
-      log(`   - remaining: ${result.remaining}`);
-      log(`   - plan: ${result.plan || "N/A"}`);
-      log(`   - checkoutUrl: ${result.checkoutUrl || "N/A"}`);
-      log(`   - Full response keys:`, Object.keys(result));
       return result;
     },
     // POST: /v1/sdk/usages
     async trackUsage(params) {
       const url = `${base}/v1/sdk/usages`;
-      log(`\u{1F4E1} API Request: POST ${url}`);
-      log(`   Params:`, JSON.stringify(params, null, 2));
+      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();
         log(`\u274C API Error: ${res.status} - ${error}`);
         throw new SolvaPayError(`Track usage failed (${res.status}): ${error}`);
       }
-      log(`\u2705 Usage tracked successfully`);
     },
     // POST: /v1/sdk/customers
     async createCustomer(params) {
       const url = `${base}/v1/sdk/customers`;
-      log(`\u{1F4E1} API Request: POST ${url}`);
-      log(`   Params:`, JSON.stringify(params, null, 2));
       const res = await fetch(url, {
         method: "POST",
         headers,
@@ -83,18 +66,24 @@ function createSolvaPayClient(opts) {
         throw new SolvaPayError(`Create customer failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      log(`\u2705 API Response:`, JSON.stringify(result, null, 2));
-      log(`\u{1F50D} DEBUG - createCustomer response:`);
-      log(`   - reference/customerRef: ${result.reference || result.customerRef}`);
-      log(`   - Has plan info: ${result.plan ? "YES" : "NO"}`);
-      log(`   - Has subscription info: ${result.subscription ? "YES" : "NO"}`);
-      log(`   - Full response keys:`, Object.keys(result));
       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}`;
-      log(`\u{1F4E1} API Request: GET ${url}`);
+      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
@@ -105,14 +94,28 @@ function createSolvaPayClient(opts) {
         throw new SolvaPayError(`Get customer failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      log(`\u2705 API Response:`, JSON.stringify(result, null, 2));
-      return result;
+      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}`);
+        }
+      }
+      return {
+        customerRef: customer.reference || customer.customerRef,
+        email: customer.email,
+        name: customer.name,
+        externalRef: customer.externalRef,
+        purchases: customer.purchases || []
+      };
     },
-    // Management methods (primarily for integration tests)
-    // GET: /v1/sdk/agents
-    async listAgents() {
-      const url = `${base}/v1/sdk/agents`;
-      log(`\u{1F4E1} API Request: GET ${url}`);
+    // 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
@@ -120,21 +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();
-      log(`\u2705 API Response:`, JSON.stringify(result, null, 2));
-      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`;
-      log(`\u{1F4E1} API Request: POST ${url}`);
-      log(`   Params:`, JSON.stringify(params, null, 2));
+    // POST: /v1/sdk/products
+    async createProduct(params) {
+      const url = `${base}/v1/sdk/products`;
       const res = await fetch(url, {
         method: "POST",
         headers,
@@ -143,16 +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();
-      log(`\u2705 API Response:`, JSON.stringify(result, null, 2));
       return result;
     },
-    // DELETE: /v1/sdk/agents/{agentRef}
-    async deleteAgent(agentRef) {
-      const url = `${base}/v1/sdk/agents/${agentRef}`;
-      log(`\u{1F4E1} API Request: DELETE ${url}`);
+    // 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
@@ -160,14 +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}`);
+      }
+    },
+    // 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}`);
       }
-      log(`\u2705 Agent deleted successfully`);
+      return await res.json();
     },
-    // GET: /v1/sdk/agents/{agentRef}/plans
-    async listPlans(agentRef) {
-      const url = `${base}/v1/sdk/agents/${agentRef}/plans`;
-      log(`\u{1F4E1} API Request: GET ${url}`);
+    // 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
@@ -178,18 +204,22 @@ function createSolvaPayClient(opts) {
         throw new SolvaPayError(`List plans failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      log(`\u2705 API Response:`, JSON.stringify(result, null, 2));
       const plans = Array.isArray(result) ? result : result.plans || [];
-      return plans.map((plan) => ({
-        ...plan,
-        ...plan.data || {}
-      }));
+      return plans.map((plan) => {
+        const data = plan.data || {};
+        const price = plan.price ?? data.price;
+        const unwrapped = {
+          ...data,
+          ...plan,
+          ...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`;
-      log(`\u{1F4E1} API Request: POST ${url}`);
-      log(`   Params:`, JSON.stringify(params, null, 2));
+      const url = `${base}/v1/sdk/products/${params.productRef}/plans`;
       const res = await fetch(url, {
         method: "POST",
         headers,
@@ -201,13 +231,26 @@ function createSolvaPayClient(opts) {
         throw new SolvaPayError(`Create plan failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      log(`\u2705 API Response:`, JSON.stringify(result, null, 2));
       return result;
     },
-    // DELETE: /v1/sdk/agents/{agentRef}/plans/{planRef}
-    async deletePlan(agentRef, planRef) {
-      const url = `${base}/v1/sdk/agents/${agentRef}/plans/${planRef}`;
-      log(`\u{1F4E1} API Request: DELETE ${url}`);
+    // 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
@@ -217,17 +260,11 @@ function createSolvaPayClient(opts) {
         log(`\u274C API Error: ${res.status} - ${error}`);
         throw new SolvaPayError(`Delete plan failed (${res.status}): ${error}`);
       }
-      log(`\u2705 Plan deleted successfully`);
     },
     // POST: /payment-intents
     async createPaymentIntent(params) {
       const idempotencyKey = params.idempotencyKey || `payment-${params.planRef}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
       const url = `${base}/v1/sdk/payment-intents`;
-      log(`\u{1F4E1} API Request: POST ${url}`);
-      log(`   Agent Ref: ${params.agentRef}`);
-      log(`   Plan Ref: ${params.planRef}`);
-      log(`   Customer Ref: ${params.customerRef}`);
-      log(`   Idempotency Key: ${idempotencyKey}`);
       const res = await fetch(url, {
         method: "POST",
         headers: {
@@ -235,7 +272,7 @@ function createSolvaPayClient(opts) {
           "Idempotency-Key": idempotencyKey
         },
         body: JSON.stringify({
-          agentRef: params.agentRef,
+          productRef: params.productRef,
           planRef: params.planRef,
           customerReference: params.customerRef
         })
@@ -246,12 +283,128 @@ function createSolvaPayClient(opts) {
         throw new SolvaPayError(`Create payment intent failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      log(`\u2705 Payment intent created:`, {
-        id: result.id,
-        hasClientSecret: !!result.clientSecret,
-        hasPublishableKey: !!result.publishableKey,
-        accountId: result.accountId
+      return result;
+    },
+    // POST: /v1/sdk/payment-intents/{paymentIntentId}/process
+    async processPaymentIntent(params) {
+      const url = `${base}/v1/sdk/payment-intents/${params.paymentIntentId}/process`;
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          ...headers,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          productRef: params.productRef,
+          customerRef: params.customerRef,
+          planRef: params.planRef
+        })
+      });
+      if (!res.ok) {
+        const error = await res.text();
+        log(`\u274C API Error: ${res.status} - ${error}`);
+        throw new SolvaPayError(`Process payment failed (${res.status}): ${error}`);
+      }
+      const result = await res.json();
+      return result;
+    },
+    // POST: /v1/sdk/purchases/{purchaseRef}/cancel
+    async cancelPurchase(params) {
+      const url = `${base}/v1/sdk/purchases/${params.purchaseRef}/cancel`;
+      const requestOptions = {
+        method: "POST",
+        headers
+      };
+      if (params.reason) {
+        requestOptions.body = JSON.stringify({ reason: params.reason });
+      }
+      const res = await fetch(url, requestOptions);
+      if (!res.ok) {
+        const error = await res.text();
+        log(`\u274C API Error: ${res.status} - ${error}`);
+        if (res.status === 404) {
+          throw new SolvaPayError(`Purchase not found: ${error}`);
+        }
+        if (res.status === 400) {
+          throw new SolvaPayError(
+            `Purchase cannot be cancelled or does not belong to provider: ${error}`
+          );
+        }
+        throw new SolvaPayError(`Cancel purchase failed (${res.status}): ${error}`);
+      }
+      const responseText = await res.text();
+      let responseData;
+      try {
+        responseData = JSON.parse(responseText);
+      } catch (parseError) {
+        log(`\u274C Failed to parse response as JSON: ${parseError}`);
+        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 purchase endpoint`);
+      }
+      let result;
+      if (responseData.purchase && typeof responseData.purchase === "object") {
+        result = responseData.purchase;
+      } else if (responseData.reference) {
+        result = responseData;
+      } else {
+        result = responseData.purchase || responseData;
+      }
+      if (!result || typeof result !== "object") {
+        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`;
+      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(`Create checkout session failed (${res.status}): ${error}`);
+      }
+      const result = await res.json();
+      return result;
+    },
+    // POST: /v1/sdk/customers/customer-sessions
+    async createCustomerSession(params) {
+      const url = `${base}/v1/sdk/customers/customer-sessions`;
+      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(`Create customer session failed (${res.status}): ${error}`);
+      }
+      const result = await res.json();
       return result;
     }
   };
@@ -303,39 +456,137 @@ function calculateDelay(initialDelay, attempt, strategy) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function createRequestDeduplicator(options = {}) {
+  const { cacheTTL = 2e3, maxCacheSize = 1e3, cacheErrors = true } = options;
+  const inFlightRequests = /* @__PURE__ */ new Map();
+  const resultCache = /* @__PURE__ */ new Map();
+  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);
+          }
+        }
+        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) {
+            resultCache.delete(key);
+          }
+        }
+      },
+      Math.min(cacheTTL, 1e3)
+    );
+  }
+  const deduplicate = async (key, fn) => {
+    if (cacheTTL > 0) {
+      const cached = resultCache.get(key);
+      if (cached && Date.now() - cached.timestamp < cacheTTL) {
+        return cached.data;
+      } else if (cached) {
+        resultCache.delete(key);
+      }
+    }
+    let requestPromise = inFlightRequests.get(key);
+    if (!requestPromise) {
+      requestPromise = (async () => {
+        try {
+          const result = await fn();
+          if (cacheTTL > 0) {
+            resultCache.set(key, {
+              data: result,
+              timestamp: Date.now()
+            });
+          }
+          return result;
+        } catch (error) {
+          if (cacheTTL > 0 && cacheErrors) {
+            resultCache.set(key, {
+              data: error,
+              timestamp: Date.now()
+            });
+          }
+          throw error;
+        } finally {
+          inFlightRequests.delete(key);
+        }
+      })();
+      const existingPromise = inFlightRequests.get(key);
+      if (existingPromise) {
+        requestPromise = existingPromise;
+      } else {
+        inFlightRequests.set(key, requestPromise);
+      }
+    }
+    return requestPromise;
+  };
+  const clearCache = (key) => {
+    resultCache.delete(key);
+  };
+  const clearAllCache = () => {
+    resultCache.clear();
+  };
+  const getStats = () => ({
+    inFlight: inFlightRequests.size,
+    cached: resultCache.size
+  });
+  return {
+    deduplicate,
+    clearCache,
+    clearAllCache,
+    getStats
+  };
+}
 
 // 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;
     this.name = "PaywallError";
   }
 };
+var sharedCustomerLookupDeduplicator = createRequestDeduplicator({
+  cacheTTL: 6e4,
+  // Cache results for 60 seconds (reduces API calls significantly)
+  maxCacheSize: 1e3,
+  // Maximum cache entries
+  cacheErrors: false
+  // Don't cache errors - retry on next request
+});
 var SolvaPayPaywall = class {
   constructor(apiClient, options = {}) {
     this.apiClient = apiClient;
-    this.debug = options.debug ?? process.env.SOLVAPAY_DEBUG !== "false";
+    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();
@@ -345,47 +596,122 @@ 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) {
-        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 Error) {
+          const errorType = error instanceof PaywallError ? "PaywallError" : "API Error";
+          this.log(`\u274C Error in paywall [${errorType}]: ${error.message}`);
+        } else {
+          this.log(`\u274C Error in paywall:`, error);
+        }
+        if (!(error instanceof PaywallError)) {
+          const latencyMs = Date.now() - startTime;
+          this.trackUsage(
+            backendCustomerRef,
+            product,
+            usagePlanRef,
+            resolvedMeterName || usageType,
+            "fail",
+            requestId,
+            latencyMs
+          );
+        }
         throw error;
       }
     };
@@ -395,60 +721,162 @@ 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 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.
+   *   The externalRef is stored on the SolvaPay backend for customer lookup.
+   * @param options - Optional customer details (email, name) for customer creation
    */
-  async ensureCustomer(customerRef) {
+  async ensureCustomer(customerRef, externalRef, options) {
     if (this.customerRefMapping.has(customerRef)) {
       return this.customerRefMapping.get(customerRef);
     }
     if (customerRef === "anonymous") {
       return customerRef;
     }
-    if (this.customerCreationAttempts.has(customerRef)) {
+    if (customerRef.startsWith("cus_")) {
       return customerRef;
     }
-    if (!this.apiClient.createCustomer) {
-      console.warn(`\u26A0\uFE0F  Cannot auto-create customer ${customerRef}: createCustomer method not available on API client`);
-      return customerRef;
+    const cacheKey = externalRef || customerRef;
+    if (this.customerRefMapping.has(customerRef)) {
+      const cached = this.customerRefMapping.get(customerRef);
+      return cached;
     }
-    this.customerCreationAttempts.add(customerRef);
-    try {
-      this.log(`\u{1F527} Auto-creating customer: ${customerRef}`);
-      const result = await this.apiClient.createCustomer({
-        email: `${customerRef}@auto-created.local`,
-        name: customerRef
-      });
-      const backendRef = result.customerRef || result.reference || customerRef;
-      this.log(`\u2705 Successfully created customer: ${customerRef} -> ${backendRef}`, result);
-      this.log(`\u{1F50D} DEBUG - ensureCustomer analysis:`);
-      this.log(`   - Input customerRef: ${customerRef}`);
-      this.log(`   - Backend customerRef: ${backendRef}`);
-      this.log(`   - Has plan in response: ${result.plan ? "YES - " + result.plan : "NO"}`);
-      this.log(`   - Has subscription in response: ${result.subscription ? "YES" : "NO"}`);
+    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.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 (externalRef) {
+          createParams.externalRef = externalRef;
+        }
+        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) {
+            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 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;
-    } catch (error) {
-      this.log(`\u274C Failed to auto-create customer ${customerRef}:`, error instanceof Error ? error.message : error);
-      return customerRef;
     }
+    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...`);
         }
       }
@@ -467,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;
   }
   /**
@@ -477,7 +902,7 @@ var AdapterUtils = class {
    */
   static async extractFromJWT(token, options) {
     try {
-      const { jwtVerify } = await import("./esm-5GYCIXIY.js");
+      const { jwtVerify } = await import("./esm-UW7WCMEK.js");
       const jwtSecret = new TextEncoder().encode(
         options?.secret || process.env.OAUTH_JWKS_SECRET || "test-jwt-secret"
       );
@@ -486,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) {
@@ -556,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
       };
@@ -600,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) {
@@ -629,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);
@@ -644,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" }
-    });
+      }
+    );
   }
 };
 
@@ -678,64 +1119,225 @@ 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
     };
   }
 };
 
 // src/factory.ts
-import { SolvaPayError as SolvaPayError2 } from "@solvapay/core";
+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) {
-  const apiClient = config.apiClient || createSolvaPayClient({
-    apiKey: config.apiKey,
-    apiBaseUrl: config.apiBaseUrl
+  let resolvedConfig;
+  if (!config) {
+    const envConfig = getSolvaPayConfig();
+    resolvedConfig = {
+      apiKey: envConfig.apiKey,
+      apiBaseUrl: envConfig.apiBaseUrl
+    };
+  } else {
+    resolvedConfig = config;
+  }
+  const apiClient = resolvedConfig.apiClient || createSolvaPayClient({
+    apiKey: resolvedConfig.apiKey,
+    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
     apiClient,
     // Common API methods exposed directly for convenience
-    ensureCustomer(customerRef) {
-      return paywall.ensureCustomer(customerRef);
+    ensureCustomer(customerRef, externalRef, options) {
+      return paywall.ensureCustomer(customerRef, externalRef, options);
     },
     createPaymentIntent(params) {
       if (!apiClient.createPaymentIntent) {
@@ -743,6 +1345,12 @@ function createSolvaPay(config) {
       }
       return apiClient.createPaymentIntent(params);
     },
+    processPaymentIntent(params) {
+      if (!apiClient.processPaymentIntent) {
+        throw new SolvaPayError2("processPaymentIntent is not available on this API client");
+      }
+      return apiClient.processPaymentIntent(params);
+    },
     checkLimits(params) {
       return apiClient.checkLimits(params);
     },
@@ -756,85 +1364,481 @@ 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({
+        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 }) {
+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");
+  if (!ok) throw new SolvaPayError5("Invalid webhook signature");
   return JSON.parse(body);
 }
 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
 };