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

package/dist/index.cjs

@@ -4254,14 +4254,21 @@ var init_esm = __esm({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  McpBearerAuthError: () => McpBearerAuthError,
   PaywallError: () => PaywallError,
+  VIRTUAL_TOOL_DEFINITIONS: () => VIRTUAL_TOOL_DEFINITIONS,
   cancelPurchaseCore: () => cancelPurchaseCore,
   createCheckoutSessionCore: () => createCheckoutSessionCore,
   createCustomerSessionCore: () => createCustomerSessionCore,
   createPaymentIntentCore: () => createPaymentIntentCore,
   createSolvaPay: () => createSolvaPay,
   createSolvaPayClient: () => createSolvaPayClient,
+  createVirtualTools: () => createVirtualTools,
+  decodeJwtPayload: () => decodeJwtPayload,
+  extractBearerToken: () => extractBearerToken,
   getAuthenticatedUserCore: () => getAuthenticatedUserCore,
+  getCustomerRefFromBearerAuthHeader: () => getCustomerRefFromBearerAuthHeader,
+  getCustomerRefFromJwtPayload: () => getCustomerRefFromJwtPayload,
   handleRouteError: () => handleRouteError,
   isErrorResult: () => isErrorResult,
   listPlansCore: () => listPlansCore,
@@ -4309,10 +4316,12 @@ function createSolvaPayClient(opts) {
     // POST: /v1/sdk/usages
     async trackUsage(params) {
       const url = `${base}/v1/sdk/usages`;
+      const { customerRef, ...rest } = params;
+      const body = { ...rest, customerId: customerRef };
       const res = await fetch(url, {
         method: "POST",
         headers,
-        body: JSON.stringify(params)
+        body: JSON.stringify(body)
       });
       if (!res.ok) {
         const error = await res.text();
@@ -4416,6 +4425,21 @@ function createSolvaPayClient(opts) {
       const result = await res.json();
       return result;
     },
+    // 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 import_core.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}`;
@@ -4429,6 +4453,21 @@ function createSolvaPayClient(opts) {
         throw new import_core.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 import_core.SolvaPayError(`Clone product failed (${res.status}): ${error}`);
+      }
+      return await res.json();
+    },
     // GET: /v1/sdk/products/{productRef}/plans
     async listPlans(productRef) {
       const url = `${base}/v1/sdk/products/${productRef}/plans`;
@@ -4471,6 +4510,21 @@ function createSolvaPayClient(opts) {
       const result = await res.json();
       return result;
     },
+    // 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 import_core.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}`;
@@ -4583,6 +4637,21 @@ function createSolvaPayClient(opts) {
       }
       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 import_core.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`;
@@ -4781,11 +4850,13 @@ var SolvaPayPaywall = class {
   constructor(apiClient, options = {}) {
     this.apiClient = apiClient;
     this.debug = options.debug ?? process.env.SOLVAPAY_DEBUG === "true";
+    this.limitsCacheTTL = options.limitsCacheTTL ?? 1e4;
   }
   customerCreationAttempts = /* @__PURE__ */ new Set();
   customerRefMapping = /* @__PURE__ */ new Map();
-  // input ref -> backend ref
   debug;
+  limitsCache = /* @__PURE__ */ new Map();
+  limitsCacheTTL;
   log(...args) {
     if (this.debug) {
       console.log(...args);
@@ -4805,7 +4876,9 @@ var SolvaPayPaywall = class {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   async protect(handler, metadata = {}, getCustomerRef) {
     const product = this.resolveProduct(metadata);
-    const toolName = handler.name || "anonymous";
+    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();
@@ -4816,19 +4889,64 @@ var SolvaPayPaywall = class {
       } else {
         backendCustomerRef = await this.ensureCustomer(inputCustomerRef, inputCustomerRef);
       }
+      let resolvedMeterName;
       try {
-        const planRef = metadata.plan || toolName;
-        const limitsCheck = await this.apiClient.checkLimits({
-          customerRef: backendCustomerRef,
-          productRef: product
-        });
-        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;
-          await this.trackUsage(
+          this.trackUsage(
             backendCustomerRef,
             product,
-            planRef,
-            toolName,
+            usagePlanRef,
+            resolvedMeterName || usageType,
             "paywall",
             requestId,
             latencyMs2
@@ -4836,17 +4954,17 @@ var SolvaPayPaywall = class {
           throw new PaywallError("Payment required", {
             kind: "payment_required",
             product,
-            checkoutUrl: limitsCheck.checkoutUrl || "",
-            message: `Plan purchase required. Remaining: ${limitsCheck.remaining}`
+            checkoutUrl: checkoutUrl || "",
+            message: `Purchase required. Remaining: ${remaining}`
           });
         }
         const result = await handler(args);
         const latencyMs = Date.now() - startTime;
-        await this.trackUsage(
+        this.trackUsage(
           backendCustomerRef,
           product,
-          planRef,
-          toolName,
+          usagePlanRef,
+          resolvedMeterName || usageType,
           "success",
           requestId,
           latencyMs
@@ -4859,18 +4977,18 @@ var SolvaPayPaywall = class {
         } else {
           this.log(`\u274C Error in paywall:`, error);
         }
-        const latencyMs = Date.now() - startTime;
-        const outcome = error instanceof PaywallError ? "paywall" : "fail";
-        const planRef = metadata.plan || toolName;
-        await this.trackUsage(
-          backendCustomerRef,
-          product,
-          planRef,
-          toolName,
-          outcome,
-          requestId,
-          latencyMs
-        );
+        if (!(error instanceof PaywallError)) {
+          const latencyMs = Date.now() - startTime;
+          this.trackUsage(
+            backendCustomerRef,
+            product,
+            usagePlanRef,
+            resolvedMeterName || usageType,
+            "fail",
+            requestId,
+            latencyMs
+          );
+        }
         throw error;
       }
     };
@@ -5019,24 +5137,23 @@ var SolvaPayPaywall = class {
     }
     return backendRef;
   }
-  async trackUsage(customerRef, productRef, planRef, toolName, outcome, requestId, actionDuration) {
+  async trackUsage(customerRef, _productRef, _planRef, action, outcome, requestId, actionDuration) {
     await withRetry(
       () => this.apiClient.trackUsage({
         customerRef,
-        productRef,
-        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...`);
         }
       }
@@ -5077,13 +5194,19 @@ var AdapterUtils = class {
   }
 };
 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 || "anonymous";
-      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) {
@@ -5332,6 +5455,141 @@ var McpAdapter = class {
 
 // src/factory.ts
 var import_core2 = require("@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(message2) {
+  return { content: [{ type: "text", text: JSON.stringify({ error: message2 }) }], isError: true };
+}
+function createGetUserInfoHandler(apiClient, productRef, getCustomerRef) {
+  return async (args) => {
+    const customerRef = getCustomerRef(args);
+    try {
+      if (!apiClient.getUserInfo) {
+        return mcpErrorResult("getUserInfo is not available on this API client");
+      }
+      const userInfo = await apiClient.getUserInfo({ customerRef, productRef });
+      return mcpTextResult(JSON.stringify(userInfo, null, 2));
+    } catch (error) {
+      return mcpErrorResult(
+        `Failed to retrieve user information: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  };
+}
+function createUpgradeHandler(apiClient, productRef, getCustomerRef) {
+  return async (args) => {
+    const customerRef = getCustomerRef(args);
+    const planRef = typeof args.planRef === "string" ? args.planRef : void 0;
+    try {
+      const result = await apiClient.createCheckoutSession({
+        customerReference: customerRef,
+        productRef,
+        ...planRef && { planRef }
+      });
+      const checkoutUrl = result.checkoutUrl;
+      if (planRef) {
+        const responseText2 = `## Upgrade
+
+**[Click here to upgrade \u2192](${checkoutUrl})**
+
+After completing the checkout, your purchase will be activated immediately.`;
+        return mcpTextResult(responseText2);
+      }
+      const responseText = `## Upgrade Your Subscription
+
+**[Click here to view pricing options and upgrade \u2192](${checkoutUrl})**
+
+You'll be able to compare options and select the one that's right for you.`;
+      return mcpTextResult(responseText);
+    } catch (error) {
+      return mcpErrorResult(
+        `Failed to create checkout session: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  };
+}
+function createManageAccountHandler(apiClient, productRef, getCustomerRef) {
+  return async (args) => {
+    const customerRef = getCustomerRef(args);
+    try {
+      const session = await apiClient.createCustomerSession({ customerRef, productRef });
+      const portalUrl = session.customerUrl;
+      const responseText = `## Manage Your Account
+
+Access your account management portal to:
+- View your current account status
+- See billing history and invoices
+- Update payment methods
+- Cancel or modify your subscription
+
+**[Open Account Portal \u2192](${portalUrl})**
+
+This link is secure and will expire after a short period.`;
+      return mcpTextResult(responseText);
+    } catch (error) {
+      return mcpErrorResult(
+        `Failed to create customer portal session: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  };
+}
+function createVirtualTools(apiClient, options) {
+  const { product, getCustomerRef, exclude = [] } = options;
+  const excludeSet = new Set(exclude);
+  const allTools = [
+    {
+      ...TOOL_GET_USER_INFO,
+      handler: createGetUserInfoHandler(apiClient, product, getCustomerRef)
+    },
+    {
+      ...TOOL_UPGRADE,
+      handler: createUpgradeHandler(apiClient, product, getCustomerRef)
+    },
+    {
+      ...TOOL_MANAGE_ACCOUNT,
+      handler: createManageAccountHandler(apiClient, product, getCustomerRef)
+    }
+  ];
+  return allTools.filter((t) => !excludeSet.has(t.name));
+}
+
+// src/factory.ts
 function createSolvaPay(config) {
   let resolvedConfig;
   if (!config) {
@@ -5348,7 +5606,8 @@ function createSolvaPay(config) {
     apiBaseUrl: resolvedConfig.apiBaseUrl
   });
   const paywall = new SolvaPayPaywall(apiClient, {
-    debug: process.env.SOLVAPAY_DEBUG !== "false"
+    debug: process.env.SOLVAPAY_DEBUG !== "false",
+    limitsCacheTTL: resolvedConfig.limitsCacheTTL
   });
   return {
     // Direct access to API client for advanced operations
@@ -5394,39 +5653,67 @@ function createSolvaPay(config) {
     createCustomerSession(params) {
       return apiClient.createCustomerSession(params);
     },
+    bootstrapMcpProduct(params) {
+      if (!apiClient.bootstrapMcpProduct) {
+        throw new import_core2.SolvaPayError("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 product = options.productRef || options.product || process.env.SOLVAPAY_PRODUCT || "default-product";
-      const plan = options.planRef || options.plan || product;
-      const metadata = { product, plan };
+      const plan = options.planRef || options.plan;
+      const usageType = options.usageType || "requests";
+      const metadata = { product, plan, usageType };
       return {
         // 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]);
           };
         },
         // 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]);
           };
         },
         // 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);
           };
         },
         // 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);
         }
       };
@@ -5434,6 +5721,57 @@ function createSolvaPay(config) {
   };
 }
 
+// src/mcp-auth.ts
+var McpBearerAuthError = class extends Error {
+  constructor(message2) {
+    super(message2);
+    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 payloadText = base64UrlDecode(parts[1]);
+    const payload = JSON.parse(payloadText);
+    return payload;
+  } catch {
+    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
 var import_core3 = require("@solvapay/core");
 function isErrorResult(result) {
@@ -5759,14 +6097,21 @@ function verifyWebhook({
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  McpBearerAuthError,
   PaywallError,
+  VIRTUAL_TOOL_DEFINITIONS,
   cancelPurchaseCore,
   createCheckoutSessionCore,
   createCustomerSessionCore,
   createPaymentIntentCore,
   createSolvaPay,
   createSolvaPayClient,
+  createVirtualTools,
+  decodeJwtPayload,
+  extractBearerToken,
   getAuthenticatedUserCore,
+  getCustomerRefFromBearerAuthHeader,
+  getCustomerRefFromJwtPayload,
   handleRouteError,
   isErrorResult,
   listPlansCore,