@solvapay/server 1.0.6 → 1.0.8-preview.1

package/dist/index.js

@@ -39,12 +39,10 @@ function createSolvaPayClient(opts) {
     // POST: /v1/sdk/usages
     async trackUsage(params) {
       const url = `${base}/v1/sdk/usages`;
-      const { customerRef, ...rest } = params;
-      const body = { ...rest, customerId: customerRef };
       const res = await fetch(url, {
         method: "POST",
         headers,
-        body: JSON.stringify(body)
+        body: JSON.stringify(params)
       });
       if (!res.ok) {
         const error = await res.text();
@@ -112,6 +110,36 @@ function createSolvaPayClient(opts) {
         purchases: customer.purchases || []
       };
     },
+    // GET: /v1/sdk/merchant
+    async getMerchant() {
+      const url = `${base}/v1/sdk/merchant`;
+      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 merchant failed (${res.status}): ${error}`);
+      }
+      return res.json();
+    },
+    // GET: /v1/sdk/products/{productRef}
+    async getProduct(productRef) {
+      const url = `${base}/v1/sdk/products/${encodeURIComponent(productRef)}`;
+      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 product failed (${res.status}): ${error}`);
+      }
+      const result = await res.json();
+      const data = result.data || {};
+      return { ...data, ...result };
+    },
     // Product management methods (primarily for integration tests)
     // GET: /v1/sdk/products
     async listProducts() {
@@ -289,7 +317,7 @@ function createSolvaPayClient(opts) {
         body: JSON.stringify({
           productRef: params.productRef,
           planRef: params.planRef,
-          customerReference: params.customerRef
+          customerRef: params.customerRef
         })
       });
       if (!res.ok) {
@@ -297,8 +325,32 @@ function createSolvaPayClient(opts) {
         log(`\u274C API Error: ${res.status} - ${error}`);
         throw new SolvaPayError(`Create payment intent failed (${res.status}): ${error}`);
       }
-      const result = await res.json();
-      return result;
+      return await res.json();
+    },
+    // POST: /v1/sdk/payment-intents (purpose: credit_topup)
+    async createTopupPaymentIntent(params) {
+      const idempotencyKey = params.idempotencyKey || `topup-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+      const url = `${base}/v1/sdk/payment-intents`;
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          ...headers,
+          "Idempotency-Key": idempotencyKey
+        },
+        body: JSON.stringify({
+          customerRef: params.customerRef,
+          purpose: "credit_topup",
+          amount: params.amount,
+          currency: params.currency,
+          description: params.description
+        })
+      });
+      if (!res.ok) {
+        const error = await res.text();
+        log(`\u274C API Error: ${res.status} - ${error}`);
+        throw new SolvaPayError(`Create topup payment intent failed (${res.status}): ${error}`);
+      }
+      return await res.json();
     },
     // POST: /v1/sdk/payment-intents/{paymentIntentId}/process
     async processPaymentIntent(params) {
@@ -375,6 +427,54 @@ function createSolvaPayClient(opts) {
       }
       return result;
     },
+    // POST: /v1/sdk/purchases/{purchaseRef}/reactivate
+    async reactivatePurchase(params) {
+      const url = `${base}/v1/sdk/purchases/${params.purchaseRef}/reactivate`;
+      const res = await fetch(url, {
+        method: "POST",
+        headers
+      });
+      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 reactivated: ${error}`
+          );
+        }
+        throw new SolvaPayError(`Reactivate 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 reactivate 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 reactivate 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 reactivate purchase response`);
+      }
+      return result;
+    },
     // POST: /v1/sdk/user-info
     async getUserInfo(params) {
       const url = `${base}/v1/sdk/user-info`;
@@ -390,6 +490,20 @@ function createSolvaPayClient(opts) {
       }
       return await res.json();
     },
+    // GET: /v1/sdk/customers/:customerRef/balance
+    async getCustomerBalance(params) {
+      const url = `${base}/v1/sdk/customers/${params.customerRef}/balance`;
+      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 balance failed (${res.status}): ${error}`);
+      }
+      return await res.json();
+    },
     // POST: /v1/sdk/checkout-sessions
     async createCheckoutSession(params) {
       const url = `${base}/v1/sdk/checkout-sessions`;
@@ -421,6 +535,21 @@ function createSolvaPayClient(opts) {
       }
       const result = await res.json();
       return result;
+    },
+    // POST: /v1/sdk/activate
+    async activatePlan(params) {
+      const url = `${base}/v1/sdk/activate`;
+      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(`Activate plan failed (${res.status}): ${error}`);
+      }
+      return await res.json();
     }
   };
 }
@@ -576,6 +705,24 @@ var PaywallError = class extends Error {
     this.name = "PaywallError";
   }
 };
+function paywallErrorToClientPayload(error) {
+  const sc = error.structuredContent;
+  const base = {
+    success: false,
+    error: sc.kind === "activation_required" ? "Activation required" : "Payment required",
+    product: sc.product,
+    checkoutUrl: sc.checkoutUrl,
+    message: sc.message
+  };
+  if (sc.kind === "activation_required") {
+    base.kind = "activation_required";
+    if (sc.plans !== void 0) base.plans = sc.plans;
+    if (sc.balance !== void 0) base.balance = sc.balance;
+    if (sc.productDetails !== void 0) base.productDetails = sc.productDetails;
+    if (sc.confirmationUrl !== void 0) base.confirmationUrl = sc.confirmationUrl;
+  }
+  return base;
+}
 var sharedCustomerLookupDeduplicator = createRequestDeduplicator({
   cacheTTL: 6e4,
   // Cache results for 60 seconds (reduces API calls significantly)
@@ -614,8 +761,6 @@ var SolvaPayPaywall = class {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   async protect(handler, metadata = {}, getCustomerRef) {
     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();
@@ -629,12 +774,13 @@ var SolvaPayPaywall = class {
       }
       let resolvedMeterName;
       try {
-        const limitsCacheKey = `${backendCustomerRef}:${product}:${configuredPlanRef || ""}:${usageType}`;
+        const limitsCacheKey = `${backendCustomerRef}:${product}:${usageType}`;
         const cachedLimits = this.limitsCache.get(limitsCacheKey);
         const now = Date.now();
         let withinLimits;
         let remaining;
         let checkoutUrl;
+        let lastLimitsCheck;
         const hasFreshCachedLimits = cachedLimits && now - cachedLimits.timestamp < this.limitsCacheTTL;
         if (hasFreshCachedLimits) {
           checkoutUrl = cachedLimits.checkoutUrl;
@@ -658,9 +804,9 @@ var SolvaPayPaywall = class {
           const limitsCheck = await this.apiClient.checkLimits({
             customerRef: backendCustomerRef,
             productRef: product,
-            ...configuredPlanRef ? { planRef: configuredPlanRef } : {},
             meterName: usageType
           });
+          lastLimitsCheck = limitsCheck;
           withinLimits = limitsCheck.withinLimits;
           remaining = limitsCheck.remaining;
           checkoutUrl = limitsCheck.checkoutUrl;
@@ -683,12 +829,25 @@ var SolvaPayPaywall = class {
           this.trackUsage(
             backendCustomerRef,
             product,
-            usagePlanRef,
             resolvedMeterName || usageType,
             "paywall",
             requestId,
             latencyMs2
           );
+          if (lastLimitsCheck?.activationRequired) {
+            const confirmationUrl = lastLimitsCheck.confirmationUrl;
+            const payCheckoutUrl = confirmationUrl || lastLimitsCheck.checkoutUrl || checkoutUrl || "";
+            throw new PaywallError("Activation required", {
+              kind: "activation_required",
+              product,
+              message: "Product activation is required before this tool can be used.",
+              checkoutUrl: payCheckoutUrl,
+              confirmationUrl,
+              plans: lastLimitsCheck.plans,
+              balance: lastLimitsCheck.balance,
+              productDetails: lastLimitsCheck.product
+            });
+          }
           throw new PaywallError("Payment required", {
             kind: "payment_required",
             product,
@@ -701,7 +860,6 @@ var SolvaPayPaywall = class {
         this.trackUsage(
           backendCustomerRef,
           product,
-          usagePlanRef,
           resolvedMeterName || usageType,
           "success",
           requestId,
@@ -720,7 +878,6 @@ var SolvaPayPaywall = class {
           this.trackUsage(
             backendCustomerRef,
             product,
-            usagePlanRef,
             resolvedMeterName || usageType,
             "fail",
             requestId,
@@ -791,7 +948,8 @@ var SolvaPayPaywall = class {
       this.customerCreationAttempts.add(customerRef);
       try {
         const createParams = {
-          email: options?.email || `${customerRef}-${Date.now()}@auto-created.local`
+          email: options?.email || `${customerRef}-${Date.now()}@auto-created.local`,
+          metadata: {}
         };
         if (options?.name) {
           createParams.name = options.name;
@@ -815,7 +973,10 @@ var SolvaPayPaywall = class {
                 return searchResult.customerRef;
               }
             } catch (lookupError) {
-              this.log(`\u26A0\uFE0F Failed to lookup existing customer by externalRef after 409:`, lookupError instanceof Error ? lookupError.message : 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");
@@ -838,7 +999,8 @@ var SolvaPayPaywall = class {
             try {
               const retryParams = {
                 email: `${customerRef}-${Date.now()}@auto-created.local`,
-                externalRef
+                externalRef,
+                metadata: {}
               };
               if (options?.name) {
                 retryParams.name = options.name;
@@ -875,14 +1037,14 @@ var SolvaPayPaywall = class {
     }
     return backendRef;
   }
-  async trackUsage(customerRef, _productRef, _planRef, action, outcome, requestId, actionDuration) {
+  async trackUsage(customerRef, productRef, action, outcome, requestId, actionDuration) {
     await withRetry(
       () => this.apiClient.trackUsage({
         customerRef,
         actionType: "api_call",
         units: 1,
         outcome,
-        productReference: _productRef,
+        productRef,
         duration: actionDuration,
         metadata: { action: action || "api_requests", requestId },
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
@@ -1134,8 +1296,10 @@ var McpAdapter = class {
       const ref = await this.options.getCustomerRef(args, extra);
       return AdapterUtils.ensureCustomerRef(ref);
     }
-    const customerRefFromExtra = extra?.authInfo?.extra?.customer_ref;
-    const customerRef = typeof customerRefFromExtra === "string" && customerRefFromExtra.trim() ? customerRefFromExtra.trim() : "anonymous";
+    const customerRefFromExtra = typeof extra?.authInfo?.extra?.customer_ref === "string" ? String(extra.authInfo.extra.customer_ref) : void 0;
+    const customerRefFromArgs = typeof args.auth === "object" && args.auth !== null && typeof args.auth.customer_ref === "string" ? String(args.auth.customer_ref) : void 0;
+    const directCustomerRef = typeof args.customer_ref === "string" ? args.customer_ref : void 0;
+    const customerRef = (customerRefFromExtra || customerRefFromArgs || directCustomerRef || "anonymous").trim();
     return AdapterUtils.ensureCustomerRef(customerRef);
   }
   formatResponse(result, _context) {
@@ -1159,17 +1323,7 @@ var McpAdapter = class {
         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
-            )
+            text: JSON.stringify(paywallErrorToClientPayload(error), null, 2)
           }
         ],
         isError: true,
@@ -1456,6 +1610,12 @@ function createSolvaPay(config) {
       }
       return apiClient.createPaymentIntent(params);
     },
+    createTopupPaymentIntent(params) {
+      if (!apiClient.createTopupPaymentIntent) {
+        throw new SolvaPayError2("createTopupPaymentIntent is not available on this API client");
+      }
+      return apiClient.createTopupPaymentIntent(params);
+    },
     processPaymentIntent(params) {
       if (!apiClient.processPaymentIntent) {
         throw new SolvaPayError2("processPaymentIntent is not available on this API client");
@@ -1472,11 +1632,17 @@ function createSolvaPay(config) {
       if (!apiClient.createCustomer) {
         throw new SolvaPayError2("createCustomer is not available on this API client");
       }
-      return apiClient.createCustomer(params);
+      return apiClient.createCustomer({ ...params, metadata: params.metadata ?? {} });
     },
     getCustomer(params) {
       return apiClient.getCustomer(params);
     },
+    getCustomerBalance(params) {
+      if (!apiClient.getCustomerBalance) {
+        throw new SolvaPayError2("getCustomerBalance is not available on this API client");
+      }
+      return apiClient.getCustomerBalance(params);
+    },
     createCheckoutSession(params) {
       return apiClient.createCheckoutSession({
         customerRef: params.customerRef,
@@ -1487,6 +1653,12 @@ function createSolvaPay(config) {
     createCustomerSession(params) {
       return apiClient.createCustomerSession(params);
     },
+    activatePlan(params) {
+      if (!apiClient.activatePlan) {
+        throw new SolvaPayError2("activatePlan is not available on this API client");
+      }
+      return apiClient.activatePlan(params);
+    },
     bootstrapMcpProduct(params) {
       if (!apiClient.bootstrapMcpProduct) {
         throw new SolvaPayError2("bootstrapMcpProduct is not available on this API client");
@@ -1508,9 +1680,8 @@ function createSolvaPay(config) {
     // Payable API for framework-specific handlers
     payable(options = {}) {
       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 };
+      const metadata = { product, usageType };
       return {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         http(businessLogic, adapterOptions) {
@@ -1574,7 +1745,8 @@ var McpBearerAuthError = class extends Error {
 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");
+  const bytes = Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
+  return new TextDecoder().decode(bytes);
 }
 function extractBearerToken(authorization) {
   if (!authorization) return null;
@@ -1848,6 +2020,24 @@ async function syncCustomerCore(request, options = {}) {
     return handleRouteError(error, "Sync customer", "Failed to sync customer");
   }
 }
+async function getCustomerBalanceCore(request, options = {}) {
+  try {
+    const userResult = await getAuthenticatedUserCore(request);
+    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
+    });
+    const result = await solvaPay.getCustomerBalance({ customerRef });
+    return result;
+  } catch (error) {
+    return handleRouteError(error, "Get customer credits", "Failed to get customer credits");
+  }
+}
 
 // src/helpers/payment.ts
 async function createPaymentIntentCore(request, body, options = {}) {
@@ -1874,7 +2064,7 @@ async function createPaymentIntentCore(request, body, options = {}) {
       customerRef
     });
     return {
-      id: paymentIntent.id,
+      processorPaymentId: paymentIntent.processorPaymentId,
       clientSecret: paymentIntent.clientSecret,
       publishableKey: paymentIntent.publishableKey,
       accountId: paymentIntent.accountId,
@@ -1884,6 +2074,57 @@ async function createPaymentIntentCore(request, body, options = {}) {
     return handleRouteError(error, "Create payment intent", "Payment intent creation failed");
   }
 }
+async function createTopupPaymentIntentCore(request, body, options = {}) {
+  try {
+    if (!body.amount || body.amount <= 0) {
+      return {
+        error: "Missing or invalid amount: must be a positive number",
+        status: 400
+      };
+    }
+    if (!body.currency) {
+      return {
+        error: "Missing required parameter: currency",
+        status: 400
+      };
+    }
+    if (body.currency !== body.currency.toUpperCase()) {
+      return {
+        error: `Invalid currency "${body.currency}": must be an uppercase ISO 4217 code (e.g. "USD", "EUR")`,
+        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.createTopupPaymentIntent({
+      customerRef,
+      amount: body.amount,
+      currency: body.currency,
+      description: body.description
+    });
+    return {
+      processorPaymentId: paymentIntent.processorPaymentId,
+      clientSecret: paymentIntent.clientSecret,
+      publishableKey: paymentIntent.publishableKey,
+      accountId: paymentIntent.accountId,
+      customerRef
+    };
+  } catch (error) {
+    return handleRouteError(
+      error,
+      "Create topup payment intent",
+      "Topup payment intent creation failed"
+    );
+  }
+}
 async function processPaymentIntentCore(request, body, options = {}) {
   try {
     if (!body.paymentIntentId || !body.productRef) {
@@ -2046,10 +2287,107 @@ async function cancelPurchaseCore(request, body, options = {}) {
     return handleRouteError(error, "Cancel purchase", "Failed to cancel purchase");
   }
 }
+async function reactivatePurchaseCore(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.reactivatePurchase) {
+      return {
+        error: "Reactivate purchase method not available on SDK client",
+        status: 500
+      };
+    }
+    let reactivatedPurchase = await solvaPay.apiClient.reactivatePurchase({
+      purchaseRef: body.purchaseRef
+    });
+    if (!reactivatedPurchase || typeof reactivatedPurchase !== "object") {
+      return {
+        error: "Invalid response from reactivate purchase endpoint",
+        status: 500
+      };
+    }
+    const responseObj = reactivatedPurchase;
+    if (responseObj.purchase && typeof responseObj.purchase === "object") {
+      reactivatedPurchase = responseObj.purchase;
+    }
+    if (!reactivatedPurchase.reference) {
+      return {
+        error: "Reactivate purchase response missing required fields",
+        status: 500
+      };
+    }
+    if (reactivatedPurchase.cancelledAt) {
+      return {
+        error: `Purchase reactivation failed: cancelledAt is still set`,
+        status: 500
+      };
+    }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    return reactivatedPurchase;
+  } 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 reactivated") || errorMessage.includes("not pending cancellation") || errorMessage.includes("already been fully cancelled") || errorMessage.includes("already ended")) {
+        return {
+          error: "Purchase cannot be reactivated",
+          status: 400,
+          details: errorMessage
+        };
+      }
+      return {
+        error: errorMessage,
+        status: 500,
+        details: errorMessage
+      };
+    }
+    return handleRouteError(error, "Reactivate purchase", "Failed to reactivate purchase");
+  }
+}
+
+// src/helpers/activation.ts
+async function activatePlanCore(request, body, options = {}) {
+  try {
+    if (!body.productRef || !body.planRef) {
+      return {
+        error: "Missing required parameters: productRef and planRef 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();
+    return await solvaPay.activatePlan({
+      customerRef,
+      productRef: body.productRef,
+      planRef: body.planRef
+    });
+  } catch (error) {
+    return handleRouteError(error, "Activate plan", "Plan activation failed");
+  }
+}
 
 // src/helpers/plans.ts
 import { getSolvaPayConfig as getSolvaPayConfig2 } from "@solvapay/core";
-async function listPlansCore(request) {
+async function listPlansCore(request, options = {}) {
   try {
     const url = new URL(request.url);
     const productRef = url.searchParams.get("productRef");
@@ -2059,19 +2397,20 @@ async function listPlansCore(request) {
         status: 400
       };
     }
-    const config = getSolvaPayConfig2();
-    const solvapaySecretKey = config.apiKey;
-    const solvapayApiBaseUrl = config.apiBaseUrl;
-    if (!solvapaySecretKey) {
+    const apiClient = options.solvaPay?.apiClient ?? (() => {
+      const config = getSolvaPayConfig2();
+      if (!config.apiKey) return null;
+      return createSolvaPayClient({
+        apiKey: config.apiKey,
+        apiBaseUrl: config.apiBaseUrl
+      });
+    })();
+    if (!apiClient) {
       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",
@@ -2088,6 +2427,159 @@ async function listPlansCore(request) {
   }
 }
 
+// src/helpers/merchant.ts
+import { getSolvaPayConfig as getSolvaPayConfig3 } from "@solvapay/core";
+async function getMerchantCore(_request, options = {}) {
+  try {
+    const apiClient = options.solvaPay?.apiClient ?? (() => {
+      const config = getSolvaPayConfig3();
+      if (!config.apiKey) return null;
+      return createSolvaPayClient({
+        apiKey: config.apiKey,
+        apiBaseUrl: config.apiBaseUrl
+      });
+    })();
+    if (!apiClient) {
+      return {
+        error: "Server configuration error: SolvaPay secret key not configured",
+        status: 500
+      };
+    }
+    if (!apiClient.getMerchant) {
+      return {
+        error: "Get merchant method not available",
+        status: 500
+      };
+    }
+    const merchant = await apiClient.getMerchant();
+    return merchant;
+  } catch (error) {
+    return handleRouteError(error, "Get merchant", "Failed to fetch merchant");
+  }
+}
+
+// src/helpers/product.ts
+import { getSolvaPayConfig as getSolvaPayConfig4 } from "@solvapay/core";
+async function getProductCore(request, options = {}) {
+  try {
+    const url = new URL(request.url);
+    const productRef = url.searchParams.get("productRef");
+    if (!productRef) {
+      return {
+        error: "Missing required parameter: productRef",
+        status: 400
+      };
+    }
+    const apiClient = options.solvaPay?.apiClient ?? (() => {
+      const config = getSolvaPayConfig4();
+      if (!config.apiKey) return null;
+      return createSolvaPayClient({
+        apiKey: config.apiKey,
+        apiBaseUrl: config.apiBaseUrl
+      });
+    })();
+    if (!apiClient) {
+      return {
+        error: "Server configuration error: SolvaPay secret key not configured",
+        status: 500
+      };
+    }
+    if (!apiClient.getProduct) {
+      return {
+        error: "Get product method not available",
+        status: 500
+      };
+    }
+    const product = await apiClient.getProduct(productRef);
+    return product;
+  } catch (error) {
+    return handleRouteError(error, "Get product", "Failed to fetch product");
+  }
+}
+
+// src/helpers/purchase.ts
+async function checkPurchaseCore(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 cachedCustomerRef = request.headers.get("x-solvapay-customer-ref");
+    if (cachedCustomerRef) {
+      try {
+        const customer = await solvaPay.getCustomer({ customerRef: cachedCustomerRef });
+        if (customer && customer.customerRef) {
+          if (customer.externalRef && customer.externalRef === userId) {
+            const filteredPurchases = (customer.purchases || []).filter(
+              (p) => p.status === "active"
+            );
+            return {
+              customerRef: customer.customerRef,
+              email: customer.email,
+              name: customer.name,
+              purchases: filteredPurchases
+            };
+          }
+        }
+      } catch {
+      }
+    }
+    try {
+      const customerRef = await solvaPay.ensureCustomer(userId, userId, {
+        email: email || void 0,
+        name: name || void 0
+      });
+      const customer = await solvaPay.getCustomer({ customerRef });
+      const filteredPurchases = (customer.purchases || []).filter((p) => p.status === "active");
+      return {
+        customerRef: customer.customerRef || userId,
+        email: customer.email,
+        name: customer.name,
+        purchases: filteredPurchases
+      };
+    } catch {
+      return {
+        customerRef: userId,
+        purchases: []
+      };
+    }
+  } catch (error) {
+    return handleRouteError(error, "Check purchase", "Failed to check purchase");
+  }
+}
+
+// src/helpers/usage.ts
+async function trackUsageCore(request, body, options = {}) {
+  try {
+    const userResult = await getAuthenticatedUserCore(request);
+    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
+    });
+    await solvaPay.trackUsage({
+      customerRef,
+      actionType: body.actionType,
+      units: body.units,
+      productRef: body.productRef,
+      description: body.description,
+      metadata: body.metadata
+    });
+    return { success: true };
+  } catch (error) {
+    return handleRouteError(error, "Track usage", "Track usage failed");
+  }
+}
+
 // src/index.ts
 function verifyWebhook({
   body,
@@ -2129,29 +2621,38 @@ export {
   McpBearerAuthError,
   PaywallError,
   VIRTUAL_TOOL_DEFINITIONS,
+  activatePlanCore,
   buildAuthInfoFromBearer,
   cancelPurchaseCore,
+  checkPurchaseCore,
   createCheckoutSessionCore,
   createCustomerSessionCore,
   createMcpOAuthBridge,
   createPaymentIntentCore,
   createSolvaPay,
   createSolvaPayClient,
+  createTopupPaymentIntentCore,
   createVirtualTools,
   decodeJwtPayload,
   extractBearerToken,
   getAuthenticatedUserCore,
+  getCustomerBalanceCore,
   getCustomerRefFromBearerAuthHeader,
   getCustomerRefFromJwtPayload,
+  getMerchantCore,
   getOAuthAuthorizationServerResponse,
   getOAuthProtectedResourceResponse,
+  getProductCore,
   handleRouteError,
   isErrorResult,
   jsonSchemaToZodRawShape,
   listPlansCore,
+  paywallErrorToClientPayload,
   processPaymentIntentCore,
+  reactivatePurchaseCore,
   registerVirtualToolsMcpImpl,
   syncCustomerCore,
+  trackUsageCore,
   verifyWebhook,
   withRetry
 };