@solvapay/server 1.0.0-preview.1 → 1.0.0-preview.10

package/dist/edge.js

@@ -3,7 +3,7 @@ import {
 } from "./chunk-R5U7XKVJ.js";
 
 // src/edge.ts
-import { SolvaPayError as SolvaPayError3 } from "@solvapay/core";
+import { SolvaPayError as SolvaPayError5 } from "@solvapay/core";
 
 // src/client.ts
 import { SolvaPayError } from "@solvapay/core";
@@ -14,15 +14,16 @@ function createSolvaPayClient(opts) {
     "Content-Type": "application/json",
     "Authorization": `Bearer ${opts.apiKey}`
   };
-  console.log(`\u{1F50C} SolvaPay API Client initialized`);
-  console.log(`   Backend URL: ${base}`);
-  console.log(`   API Key: ${opts.apiKey.substring(0, 10)}...`);
+  const debug = process.env.SOLVAPAY_DEBUG === "true";
+  const log = (...args) => {
+    if (debug) {
+      console.log(...args);
+    }
+  };
   return {
     // POST: /v1/sdk/limits
     async checkLimits(params) {
       const url = `${base}/v1/sdk/limits`;
-      console.log(`\u{1F4E1} API Request: POST ${url}`);
-      console.log(`   Params:`, JSON.stringify(params, null, 2));
       const res = await fetch(url, {
         method: "POST",
         headers,
@@ -30,24 +31,15 @@ function createSolvaPayClient(opts) {
       });
       if (!res.ok) {
         const error = await res.text();
-        console.error(`\u274C API Error: ${res.status} - ${error}`);
+        log(`\u274C API Error: ${res.status} - ${error}`);
         throw new SolvaPayError(`Check limits failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      console.log(`\u2705 API Response:`, JSON.stringify(result, null, 2));
-      console.log(`\u{1F50D} DEBUG - checkLimits breakdown:`);
-      console.log(`   - withinLimits: ${result.withinLimits}`);
-      console.log(`   - remaining: ${result.remaining}`);
-      console.log(`   - plan: ${result.plan || "N/A"}`);
-      console.log(`   - checkoutUrl: ${result.checkoutUrl || "N/A"}`);
-      console.log(`   - Full response keys:`, Object.keys(result));
       return result;
     },
     // POST: /v1/sdk/usages
     async trackUsage(params) {
       const url = `${base}/v1/sdk/usages`;
-      console.log(`\u{1F4E1} API Request: POST ${url}`);
-      console.log(`   Params:`, JSON.stringify(params, null, 2));
       const res = await fetch(url, {
         method: "POST",
         headers,
@@ -55,16 +47,13 @@ function createSolvaPayClient(opts) {
       });
       if (!res.ok) {
         const error = await res.text();
-        console.error(`\u274C API Error: ${res.status} - ${error}`);
+        log(`\u274C API Error: ${res.status} - ${error}`);
         throw new SolvaPayError(`Track usage failed (${res.status}): ${error}`);
       }
-      console.log(`\u2705 Usage tracked successfully`);
     },
     // POST: /v1/sdk/customers
     async createCustomer(params) {
       const url = `${base}/v1/sdk/customers`;
-      console.log(`\u{1F4E1} API Request: POST ${url}`);
-      console.log(`   Params:`, JSON.stringify(params, null, 2));
       const res = await fetch(url, {
         method: "POST",
         headers,
@@ -72,51 +61,69 @@ function createSolvaPayClient(opts) {
       });
       if (!res.ok) {
         const error = await res.text();
-        console.error(`\u274C API Error: ${res.status} - ${error}`);
+        log(`\u274C API Error: ${res.status} - ${error}`);
         throw new SolvaPayError(`Create customer failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      console.log(`\u2705 API Response:`, JSON.stringify(result, null, 2));
-      console.log(`\u{1F50D} DEBUG - createCustomer response:`);
-      console.log(`   - reference/customerRef: ${result.reference || result.customerRef}`);
-      console.log(`   - Has plan info: ${result.plan ? "YES" : "NO"}`);
-      console.log(`   - Has subscription info: ${result.subscription ? "YES" : "NO"}`);
-      console.log(`   - Full response keys:`, Object.keys(result));
       return result;
     },
     // GET: /v1/sdk/customers/{reference}
     async getCustomer(params) {
       const url = `${base}/v1/sdk/customers/${params.customerRef}`;
-      console.log(`\u{1F4E1} API Request: GET ${url}`);
       const res = await fetch(url, {
         method: "GET",
         headers
       });
       if (!res.ok) {
         const error = await res.text();
-        console.error(`\u274C API Error: ${res.status} - ${error}`);
+        log(`\u274C API Error: ${res.status} - ${error}`);
         throw new SolvaPayError(`Get customer failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      console.log(`\u2705 API Response:`, JSON.stringify(result, null, 2));
-      return result;
+      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}`);
+      }
+      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 || []
+      };
     },
     // Management methods (primarily for integration tests)
     // GET: /v1/sdk/agents
     async listAgents() {
       const url = `${base}/v1/sdk/agents`;
-      console.log(`\u{1F4E1} API Request: GET ${url}`);
       const res = await fetch(url, {
         method: "GET",
         headers
       });
       if (!res.ok) {
         const error = await res.text();
-        console.error(`\u274C API Error: ${res.status} - ${error}`);
+        log(`\u274C API Error: ${res.status} - ${error}`);
         throw new SolvaPayError(`List agents failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      console.log(`\u2705 API Response:`, JSON.stringify(result, null, 2));
       const agents = Array.isArray(result) ? result : result.agents || [];
       return agents.map((agent) => ({
         ...agent,
@@ -126,8 +133,6 @@ function createSolvaPayClient(opts) {
     // POST: /v1/sdk/agents
     async createAgent(params) {
       const url = `${base}/v1/sdk/agents`;
-      console.log(`\u{1F4E1} API Request: POST ${url}`);
-      console.log(`   Params:`, JSON.stringify(params, null, 2));
       const res = await fetch(url, {
         method: "POST",
         headers,
@@ -135,54 +140,54 @@ function createSolvaPayClient(opts) {
       });
       if (!res.ok) {
         const error = await res.text();
-        console.error(`\u274C API Error: ${res.status} - ${error}`);
+        log(`\u274C API Error: ${res.status} - ${error}`);
         throw new SolvaPayError(`Create agent failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      console.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}`;
-      console.log(`\u{1F4E1} API Request: DELETE ${url}`);
       const res = await fetch(url, {
         method: "DELETE",
         headers
       });
       if (!res.ok && res.status !== 404) {
         const error = await res.text();
-        console.error(`\u274C API Error: ${res.status} - ${error}`);
+        log(`\u274C API Error: ${res.status} - ${error}`);
         throw new SolvaPayError(`Delete agent failed (${res.status}): ${error}`);
       }
-      console.log(`\u2705 Agent deleted successfully`);
     },
     // GET: /v1/sdk/agents/{agentRef}/plans
     async listPlans(agentRef) {
       const url = `${base}/v1/sdk/agents/${agentRef}/plans`;
-      console.log(`\u{1F4E1} API Request: GET ${url}`);
       const res = await fetch(url, {
         method: "GET",
         headers
       });
       if (!res.ok) {
         const error = await res.text();
-        console.error(`\u274C API Error: ${res.status} - ${error}`);
+        log(`\u274C API Error: ${res.status} - ${error}`);
         throw new SolvaPayError(`List plans failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      console.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 price = plan.price ?? plan.data?.price;
+        const unwrapped = {
+          ...plan.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
     async createPlan(params) {
       const url = `${base}/v1/sdk/agents/${params.agentRef}/plans`;
-      console.log(`\u{1F4E1} API Request: POST ${url}`);
-      console.log(`   Params:`, JSON.stringify(params, null, 2));
       const res = await fetch(url, {
         method: "POST",
         headers,
@@ -190,37 +195,29 @@ function createSolvaPayClient(opts) {
       });
       if (!res.ok) {
         const error = await res.text();
-        console.error(`\u274C API Error: ${res.status} - ${error}`);
+        log(`\u274C API Error: ${res.status} - ${error}`);
         throw new SolvaPayError(`Create plan failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      console.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}`;
-      console.log(`\u{1F4E1} API Request: DELETE ${url}`);
       const res = await fetch(url, {
         method: "DELETE",
         headers
       });
       if (!res.ok && res.status !== 404) {
         const error = await res.text();
-        console.error(`\u274C API Error: ${res.status} - ${error}`);
+        log(`\u274C API Error: ${res.status} - ${error}`);
         throw new SolvaPayError(`Delete plan failed (${res.status}): ${error}`);
       }
-      console.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`;
-      console.log(`\u{1F4E1} API Request: POST ${url}`);
-      console.log(`   Agent Ref: ${params.agentRef}`);
-      console.log(`   Plan Ref: ${params.planRef}`);
-      console.log(`   Customer Ref: ${params.customerRef}`);
-      console.log(`   Idempotency Key: ${idempotencyKey}`);
       const res = await fetch(url, {
         method: "POST",
         headers: {
@@ -235,16 +232,113 @@ function createSolvaPayClient(opts) {
       });
       if (!res.ok) {
         const error = await res.text();
-        console.error(`\u274C API Error: ${res.status} - ${error}`);
+        log(`\u274C API Error: ${res.status} - ${error}`);
         throw new SolvaPayError(`Create payment intent failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      console.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 processPayment(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({
+          agentRef: params.agentRef,
+          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/subscriptions/{subscriptionRef}/cancel
+    async cancelSubscription(params) {
+      const url = `${base}/v1/sdk/subscriptions/${params.subscriptionRef}/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(`Subscription not found: ${error}`);
+        }
+        if (res.status === 400) {
+          throw new SolvaPayError(`Subscription cannot be cancelled or does not belong to provider: ${error}`);
+        }
+        throw new SolvaPayError(`Cancel subscription 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 subscription 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`);
+      }
+      let result;
+      if (responseData.subscription && typeof responseData.subscription === "object") {
+        result = responseData.subscription;
+      } else if (responseData.reference) {
+        result = responseData;
+      } else {
+        result = responseData.subscription || 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`);
+      }
+      return result;
+    },
+    // 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;
     }
   };
@@ -296,6 +390,95 @@ 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 {
@@ -305,10 +488,18 @@ var PaywallError = class extends Error {
     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";
   }
   customerCreationAttempts = /* @__PURE__ */ new Set();
   customerRefMapping = /* @__PURE__ */ new Map();
@@ -348,15 +539,12 @@ var SolvaPayPaywall = class {
       const backendCustomerRef = await this.ensureCustomer(inputCustomerRef);
       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 latencyMs2 = Date.now() - startTime;
-          this.log(`\u{1F6AB} Paywall triggered - tracking usage`);
           await this.trackUsage(backendCustomerRef, agent, planRef, toolName, "paywall", requestId, latencyMs2);
           throw new PaywallError("Payment required", {
             kind: "payment_required",
@@ -365,16 +553,17 @@ var SolvaPayPaywall = class {
             message: `Plan subscription required. Remaining: ${limitsCheck.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`);
         return result;
       } catch (error) {
-        this.log(`\u274C Error in paywall:`, error);
+        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);
+        }
         const latencyMs = Date.now() - startTime;
         const outcome = error instanceof PaywallError ? "paywall" : "fail";
         const planRef = metadata.plan || toolName;
@@ -388,41 +577,80 @@ 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)) {
-      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 && this.apiClient.getCustomerByExternalRef) {
+          try {
+            const existingCustomer = await this.apiClient.getCustomerByExternalRef({ 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}@auto-created.local`
+          };
+          if (options?.name) {
+            createParams.name = options.name;
+          }
+          if (externalRef) {
+            createParams.externalRef = externalRef;
+          }
+          const result = await this.apiClient.createCustomer(createParams);
+          const ref = result.customerRef || result.reference || customerRef;
+          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;
+        }
+      }
+    );
+    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) {
     await withRetry(
@@ -714,11 +942,21 @@ var McpAdapter = class {
 };
 
 // src/factory.ts
-import { SolvaPayError as SolvaPayError2 } from "@solvapay/core";
+import { SolvaPayError as SolvaPayError2, getSolvaPayConfig } from "@solvapay/core";
 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"
@@ -727,8 +965,8 @@ function createSolvaPay(config) {
     // 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) {
@@ -736,6 +974,12 @@ function createSolvaPay(config) {
       }
       return apiClient.createPaymentIntent(params);
     },
+    processPayment(params) {
+      if (!apiClient.processPayment) {
+        throw new SolvaPayError2("processPayment is not available on this API client");
+      }
+      return apiClient.processPayment(params);
+    },
     checkLimits(params) {
       return apiClient.checkLimits(params);
     },
@@ -754,6 +998,12 @@ function createSolvaPay(config) {
       }
       return apiClient.getCustomer(params);
     },
+    createCheckoutSession(params) {
+      return apiClient.createCheckoutSession(params);
+    },
+    createCustomerSession(params) {
+      return apiClient.createCustomerSession(params);
+    },
     // Payable API for framework-specific handlers
     payable(options = {}) {
       const agent = options.agentRef || options.agent || process.env.SOLVAPAY_AGENT || getPackageJsonName() || "default-agent";
@@ -817,6 +1067,314 @@ function getPackageJsonName() {
   }
 }
 
+// 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) {
+    return {
+      error: error.message,
+      status: 500,
+      details: error.message
+    };
+  }
+  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.agentRef) {
+      return {
+        error: "Missing required parameters: planRef and agentRef 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({
+      agentRef: body.agentRef,
+      planRef: body.planRef,
+      customerRef
+    });
+    return {
+      id: paymentIntent.id,
+      clientSecret: paymentIntent.clientSecret,
+      publishableKey: paymentIntent.publishableKey,
+      accountId: paymentIntent.accountId,
+      customerRef
+      // Return the backend customer reference
+    };
+  } catch (error) {
+    return handleRouteError(error, "Create payment intent", "Payment intent creation failed");
+  }
+}
+async function processPaymentCore(request, body, options = {}) {
+  try {
+    if (!body.paymentIntentId || !body.agentRef) {
+      return {
+        error: "paymentIntentId and agentRef 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.processPayment({
+      paymentIntentId: body.paymentIntentId,
+      agentRef: body.agentRef,
+      customerRef,
+      planRef: body.planRef
+    });
+    return result;
+  } catch (error) {
+    return handleRouteError(error, "Process payment", "Payment processing failed");
+  }
+}
+
+// src/helpers/checkout.ts
+async function createCheckoutSessionCore(request, body, options = {}) {
+  try {
+    if (!body.agentRef) {
+      return {
+        error: "Missing required parameter: agentRef 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;
+    const solvaPay = options.solvaPay || createSolvaPay();
+    const session = await solvaPay.createCheckoutSession({
+      agentRef: body.agentRef,
+      customerRef,
+      planRef: body.planRef || void 0
+    });
+    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/subscription.ts
+import { SolvaPayError as SolvaPayError4 } from "@solvapay/core";
+async function cancelSubscriptionCore(request, body, options = {}) {
+  try {
+    const userResult = await getAuthenticatedUserCore(request);
+    if (isErrorResult(userResult)) {
+      return userResult;
+    }
+    const { userId } = userResult;
+    if (!body.subscriptionRef) {
+      return {
+        error: "Missing required parameter: subscriptionRef is required",
+        status: 400
+      };
+    }
+    const solvaPay = options.solvaPay || createSolvaPay();
+    if (!solvaPay.apiClient.cancelSubscription) {
+      return {
+        error: "Cancel subscription method not available on SDK client",
+        status: 500
+      };
+    }
+    let cancelledSubscription = await solvaPay.apiClient.cancelSubscription({
+      subscriptionRef: body.subscriptionRef,
+      reason: body.reason
+    });
+    if (!cancelledSubscription || typeof cancelledSubscription !== "object") {
+      return {
+        error: "Invalid response from cancel subscription endpoint",
+        status: 500
+      };
+    }
+    const responseAny = cancelledSubscription;
+    if (responseAny.subscription && typeof responseAny.subscription === "object") {
+      cancelledSubscription = responseAny.subscription;
+    }
+    if (!cancelledSubscription.reference) {
+      return {
+        error: "Cancel subscription response missing required fields",
+        status: 500
+      };
+    }
+    const isCancelled = cancelledSubscription.status === "cancelled" || cancelledSubscription.cancelledAt;
+    if (!isCancelled) {
+      return {
+        error: `Subscription cancellation failed: backend returned status '${cancelledSubscription.status}' without cancelledAt timestamp`,
+        status: 500
+      };
+    }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    return cancelledSubscription;
+  } catch (error) {
+    if (error instanceof SolvaPayError4) {
+      const errorMessage = error.message;
+      if (errorMessage.includes("Subscription not found")) {
+        return {
+          error: "Subscription not found",
+          status: 404,
+          details: errorMessage
+        };
+      }
+      if (errorMessage.includes("cannot be cancelled") || errorMessage.includes("does not belong to provider")) {
+        return {
+          error: "Subscription cannot be cancelled or does not belong to provider",
+          status: 400,
+          details: errorMessage
+        };
+      }
+      return {
+        error: errorMessage,
+        status: 500,
+        details: errorMessage
+      };
+    }
+    return handleRouteError(error, "Cancel subscription", "Failed to cancel subscription");
+  }
+}
+
+// src/helpers/plans.ts
+import { getSolvaPayConfig as getSolvaPayConfig2 } from "@solvapay/core";
+async function listPlansCore(request) {
+  try {
+    const url = new URL(request.url);
+    const agentRef = url.searchParams.get("agentRef");
+    if (!agentRef) {
+      return {
+        error: "Missing required parameter: agentRef",
+        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(agentRef);
+    return {
+      plans: plans || [],
+      agentRef
+    };
+  } catch (error) {
+    return handleRouteError(error, "List plans", "Failed to fetch plans");
+  }
+}
+
 // src/edge.ts
 async function verifyWebhook({
   body,
@@ -834,14 +1392,24 @@ async function verifyWebhook({
   const sigBuf = await crypto.subtle.sign("HMAC", key, enc.encode(body));
   const hex = Array.from(new Uint8Array(sigBuf)).map((b) => b.toString(16).padStart(2, "0")).join("");
   if (hex !== signature) {
-    throw new SolvaPayError3("Invalid webhook signature");
+    throw new SolvaPayError5("Invalid webhook signature");
   }
   return JSON.parse(body);
 }
 export {
   PaywallError,
+  cancelSubscriptionCore,
+  createCheckoutSessionCore,
+  createCustomerSessionCore,
+  createPaymentIntentCore,
   createSolvaPay,
   createSolvaPayClient,
+  getAuthenticatedUserCore,
+  handleRouteError,
+  isErrorResult,
+  listPlansCore,
+  processPaymentCore,
+  syncCustomerCore,
   verifyWebhook,
   withRetry
 };