@solvapay/server 1.0.9-preview.1 → 1.0.9

package/dist/edge.js

@@ -1,5 +1,3 @@
-import "./chunk-MLKGABMK.js";
-
 // src/edge.ts
 import { SolvaPayError as SolvaPayError5 } from "@solvapay/core";
 
@@ -63,7 +61,27 @@ function createSolvaPayClient(opts) {
         throw new SolvaPayError(`Create customer failed (${res.status}): ${error}`);
       }
       const result = await res.json();
-      return result;
+      return {
+        customerRef: result.reference || result.customerRef
+      };
+    },
+    // PATCH: /v1/sdk/customers/{customerRef}
+    async updateCustomer(customerRef, params) {
+      const url = `${base}/v1/sdk/customers/${encodeURIComponent(customerRef)}`;
+      const res = await fetch(url, {
+        method: "PATCH",
+        headers,
+        body: JSON.stringify(params)
+      });
+      if (!res.ok) {
+        const error = await res.text();
+        log(`\u274C API Error: ${res.status} - ${error}`);
+        throw new SolvaPayError(`Update customer failed (${res.status}): ${error}`);
+      }
+      const result = await res.json();
+      return {
+        customerRef: result.reference || result.customerRef || customerRef
+      };
     },
     // GET: /v1/sdk/customers/{reference} or /v1/sdk/customers?externalRef={externalRef}|email={email}
     async getCustomer(params) {
@@ -109,6 +127,50 @@ 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/platform-config
+    async getPlatformConfig() {
+      const url = `${base}/v1/sdk/platform-config`;
+      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 platform config 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() {
@@ -519,10 +581,67 @@ function createSolvaPayClient(opts) {
         throw new SolvaPayError(`Activate plan failed (${res.status}): ${error}`);
       }
       return await res.json();
+    },
+    async getPaymentMethod(params) {
+      const url = new URL(`${base}/v1/sdk/payment-method`);
+      url.searchParams.set("customerRef", params.customerRef);
+      const res = await fetch(url.toString(), { method: "GET", headers });
+      if (!res.ok) {
+        const error = await res.text();
+        log(`\u274C API Error: ${res.status} - ${error}`);
+        throw new SolvaPayError(`Get payment method failed (${res.status}): ${error}`);
+      }
+      return await res.json();
     }
   };
 }
 
+// src/paywall-state.ts
+function classifyPaywallState(limits) {
+  if (!limits) return { kind: "upgrade_required" };
+  if (limits.activationRequired === true) {
+    return { kind: "activation_required" };
+  }
+  const activePlan = limits.plans?.find((p) => p.reference === limits.plan);
+  const isUsageBased = activePlan?.type === "usage-based" || limits.balance !== void 0;
+  const creditBalance = limits.balance?.creditBalance ?? limits.creditBalance;
+  if (isUsageBased) {
+    if (creditBalance === 0) return { kind: "topup_required" };
+    if (creditBalance === void 0 && limits.remaining === 0) {
+      return { kind: "topup_required" };
+    }
+  }
+  return { kind: "upgrade_required" };
+}
+function buildGateMessage(state, gate) {
+  const url = gate.checkoutUrl && gate.checkoutUrl.length > 0 ? gate.checkoutUrl : null;
+  const openClause = url ? `, or open ${url} in a browser` : "";
+  switch (state.kind) {
+    case "activation_required":
+      return `Your plan needs activation before you can use this tool. Call the \`activate_plan\` tool to activate it${openClause}.`;
+    case "topup_required":
+      return `You're out of credits. Call the \`topup\` tool to add more${openClause}.`;
+    case "upgrade_required":
+      return `You don't have an active plan for this tool. Call the \`upgrade\` tool to pick a plan${openClause}.`;
+    case "reactivation_required":
+      return `Your previous plan is no longer active. Call the \`manage_account\` tool to reactivate it, or the \`upgrade\` tool to pick a new plan.`;
+  }
+}
+function buildNudgeMessage(state, limits) {
+  const url = limits?.checkoutUrl && limits.checkoutUrl.length > 0 ? limits.checkoutUrl : null;
+  const visitClause = url ? `, or visit ${url}` : "";
+  switch (state.kind) {
+    case "topup_required":
+      return `Heads up \u2014 running low on credits. Call the \`topup\` tool to add more${visitClause}.`;
+    case "upgrade_required":
+      return `Heads up \u2014 approaching your plan's limit this period. Call the \`upgrade\` tool for more headroom${visitClause}.`;
+    case "activation_required":
+      return `Heads up \u2014 this plan still needs activation. Call the \`activate_plan\` tool${visitClause}.`;
+    case "reactivation_required":
+      return `Heads up \u2014 your plan is no longer active. Call the \`manage_account\` tool to reactivate it${visitClause}.`;
+  }
+}
+
 // src/utils.ts
 async function withRetry(fn, options = {}) {
   const {
@@ -574,7 +693,8 @@ function createRequestDeduplicator(options = {}) {
   const inFlightRequests = /* @__PURE__ */ new Map();
   const resultCache = /* @__PURE__ */ new Map();
   let _cleanupInterval = null;
-  if (cacheTTL > 0) {
+  function ensureCleanupInterval() {
+    if (_cleanupInterval || cacheTTL <= 0) return;
     _cleanupInterval = setInterval(
       () => {
         const now = Date.now();
@@ -601,6 +721,7 @@ function createRequestDeduplicator(options = {}) {
     );
   }
   const deduplicate = async (key, fn) => {
+    ensureCleanupInterval();
     if (cacheTTL > 0) {
       const cached = resultCache.get(key);
       if (cached && Date.now() - cached.timestamp < cacheTTL) {
@@ -689,6 +810,10 @@ function paywallErrorToClientPayload(error) {
     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;
+  } else {
+    base.kind = "payment_required";
+    if (sc.balance !== void 0) base.balance = sc.balance;
+    if (sc.productDetails !== void 0) base.productDetails = sc.productDetails;
   }
   return base;
 }
@@ -700,6 +825,7 @@ var sharedCustomerLookupDeduplicator = createRequestDeduplicator({
   cacheErrors: false
   // Don't cache errors - retry on next request
 });
+var EXTRA_FORWARD_KEY = "__solvapayExtra";
 var SolvaPayPaywall = class {
   constructor(apiClient, options = {}) {
     this.apiClient = apiClient;
@@ -725,136 +851,216 @@ var SolvaPayPaywall = class {
     return `solvapay_${timestamp}_${random}`;
   }
   /**
-   * Core protection method - works for both MCP and HTTP
+   * Pure decision routine — performs customer resolution, limits cache
+   * lookup / fresh `checkLimits` fetch, and returns a `PaywallDecision`
+   * describing whether the handler should run.
+   *
+   * Side effects kept in lockstep with the legacy `protect()` path:
+   *  - creates the backend customer on first use (`ensureCustomer`),
+   *  - updates the limits cache (consume-one-unit bookkeeping), and
+   *  - emits a `paywall` usage event on gate outcomes.
+   *
+   * `trackUsage` for the `success` / `fail` outcome is emitted by the
+   * caller (adapter or `protect()`) once it has actually invoked the
+   * handler — `decide()` never counts handler execution as usage.
+   *
+   * @since 1.1.0
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  async protect(handler, metadata = {}, getCustomerRef) {
+  async decide(args, metadata = {}, getCustomerRef) {
     const product = this.resolveProduct(metadata);
     const usageType = metadata.usageType || "requests";
-    return async (args) => {
-      const startTime = Date.now();
-      const requestId = this.generateRequestId();
-      const inputCustomerRef = getCustomerRef ? getCustomerRef(args) : args.auth?.customer_ref || "anonymous";
-      let backendCustomerRef;
-      if (inputCustomerRef.startsWith("cus_")) {
-        backendCustomerRef = inputCustomerRef;
+    const requestId = this.generateRequestId();
+    const startTime = Date.now();
+    const inputCustomerRef = getCustomerRef ? getCustomerRef(args) : args.auth?.customer_ref || "anonymous";
+    let backendCustomerRef;
+    if (inputCustomerRef.startsWith("cus_")) {
+      backendCustomerRef = inputCustomerRef;
+    } else {
+      backendCustomerRef = await this.ensureCustomer(inputCustomerRef, inputCustomerRef);
+    }
+    const limitsCacheKey = `${backendCustomerRef}:${product}:${usageType}`;
+    const cachedLimits = this.limitsCache.get(limitsCacheKey);
+    const now = Date.now();
+    let withinLimits;
+    let remaining;
+    let checkoutUrl;
+    let resolvedMeterName;
+    let lastLimitsCheck;
+    const hasFreshCachedLimits = cachedLimits && now - cachedLimits.timestamp < this.limitsCacheTTL;
+    if (hasFreshCachedLimits) {
+      checkoutUrl = cachedLimits.checkoutUrl;
+      resolvedMeterName = cachedLimits.meterName;
+      lastLimitsCheck = cachedLimits.limits;
+      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,
+        meterName: usageType
+      });
+      lastLimitsCheck = limitsCheck;
+      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,
+          limits: limitsCheck
+        });
+      }
+    }
+    if (!withinLimits) {
+      const latencyMs = Date.now() - startTime;
+      this.trackUsage(
+        backendCustomerRef,
+        product,
+        resolvedMeterName || usageType,
+        "paywall",
+        requestId,
+        latencyMs
+      );
+      const state = classifyPaywallState(lastLimitsCheck ?? null);
+      const preMessageGate = lastLimitsCheck?.activationRequired ? {
+        kind: "activation_required",
+        product,
+        message: "",
+        checkoutUrl: lastLimitsCheck.confirmationUrl || lastLimitsCheck.checkoutUrl || checkoutUrl || "",
+        ...lastLimitsCheck.confirmationUrl !== void 0 ? { confirmationUrl: lastLimitsCheck.confirmationUrl } : {},
+        ...lastLimitsCheck.plans !== void 0 ? { plans: lastLimitsCheck.plans } : {},
+        ...lastLimitsCheck.balance !== void 0 ? { balance: lastLimitsCheck.balance } : {},
+        ...lastLimitsCheck.product !== void 0 ? { productDetails: lastLimitsCheck.product } : {}
+      } : {
+        kind: "payment_required",
+        product,
+        checkoutUrl: checkoutUrl || "",
+        message: "",
+        ...lastLimitsCheck?.balance !== void 0 ? { balance: lastLimitsCheck.balance } : {},
+        ...lastLimitsCheck?.product !== void 0 ? { productDetails: lastLimitsCheck.product } : {}
+      };
+      const gate = {
+        ...preMessageGate,
+        message: buildGateMessage(state, preMessageGate)
+      };
+      return {
+        outcome: "gate",
+        gate,
+        limits: lastLimitsCheck ?? null,
+        customerRef: backendCustomerRef
+      };
+    }
+    return {
+      outcome: "allow",
+      args,
+      limits: lastLimitsCheck,
+      customerRef: backendCustomerRef
+    };
+  }
+  /**
+   * Execute the handler for an already-obtained `allow` decision and
+   * emit the post-handler `trackUsage('success' | 'fail', ...)` event.
+   *
+   * Exposed for adapter integration — the adapter layer drives the
+   * paywall through `decide()` + `runAllow()` so `formatGate` can own
+   * gate outcomes without routing through `PaywallError`. `protect()`
+   * continues to offer the self-contained throw-based surface for
+   * legacy consumers.
+   *
+   * `runAllow` intentionally does NOT re-throw `PaywallError` — if a
+   * handler calls `ctx.gate(reason)` and throws from deep code, the
+   * adapter catches that at the `formatGate` boundary instead.
+   *
+   * @since 1.1.0
+   */
+  async runAllow(decision, handler, metadata, args) {
+    const product = this.resolveProduct(metadata);
+    const usageType = metadata.usageType || "requests";
+    const requestId = this.generateRequestId();
+    const startTime = Date.now();
+    const forwardedExtra = args[EXTRA_FORWARD_KEY];
+    const handlerContext = {
+      customerRef: decision.customerRef,
+      limits: decision.limits,
+      ...forwardedExtra !== void 0 ? { extra: forwardedExtra } : {}
+    };
+    try {
+      const result = await handler(args, handlerContext);
+      const latencyMs = Date.now() - startTime;
+      this.trackUsage(
+        decision.customerRef,
+        product,
+        decision.limits.meterName || usageType,
+        "success",
+        requestId,
+        latencyMs
+      );
+      return result;
+    } catch (error) {
+      if (error instanceof Error) {
+        const errorType = error instanceof PaywallError ? "PaywallError" : "API Error";
+        this.log(`\u274C Error in paywall [${errorType}]: ${error.message}`);
       } else {
-        backendCustomerRef = await this.ensureCustomer(inputCustomerRef, inputCustomerRef);
+        this.log(`\u274C Error in paywall:`, error);
       }
-      let resolvedMeterName;
-      try {
-        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;
-          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,
-            meterName: usageType
-          });
-          lastLimitsCheck = limitsCheck;
-          withinLimits = limitsCheck.withinLimits;
-          remaining = limitsCheck.remaining;
-          checkoutUrl = limitsCheck.checkoutUrl;
-          resolvedMeterName = limitsCheck.meterName;
-          const consumedAllowance = withinLimits && remaining > 0;
-          if (consumedAllowance) {
-            remaining = Math.max(0, remaining - 1);
-          }
-          if (consumedAllowance) {
-            this.limitsCache.set(limitsCacheKey, {
-              remaining,
-              checkoutUrl,
-              meterName: resolvedMeterName,
-              timestamp: now
-            });
-          }
-        }
-        if (!withinLimits) {
-          const latencyMs2 = Date.now() - startTime;
-          this.trackUsage(
-            backendCustomerRef,
-            product,
-            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,
-            checkoutUrl: checkoutUrl || "",
-            message: `Purchase required. Remaining: ${remaining}`
-          });
-        }
-        const result = await handler(args);
+      if (!(error instanceof PaywallError)) {
         const latencyMs = Date.now() - startTime;
         this.trackUsage(
-          backendCustomerRef,
+          decision.customerRef,
           product,
-          resolvedMeterName || usageType,
-          "success",
+          decision.limits.meterName || usageType,
+          "fail",
           requestId,
           latencyMs
         );
-        return result;
-      } catch (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);
-        }
-        if (!(error instanceof PaywallError)) {
-          const latencyMs = Date.now() - startTime;
-          this.trackUsage(
-            backendCustomerRef,
-            product,
-            resolvedMeterName || usageType,
-            "fail",
-            requestId,
-            latencyMs
-          );
-        }
-        throw error;
       }
+      throw error;
+    }
+  }
+  /**
+   * Core protection method - works for both MCP and HTTP
+   *
+   * The `handler` may optionally declare a second positional argument
+   * of type `ProtectHandlerContext` to receive the resolved customer
+   * ref, the pre-check `LimitResponseWithPlan`, and an opaque `extra`
+   * bag threaded through from the adapter layer. One-arg handlers
+   * ignore the second argument and continue to work unchanged.
+   *
+   * Implemented on top of `decide()`: pre-check runs through the same
+   * decision routine, and gate outcomes are raised as a `PaywallError`
+   * to preserve the legacy throw-based signal for consumers that
+   * haven't migrated to adapter-level `formatGate` routing.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async protect(handler, metadata = {}, getCustomerRef) {
+    return async (args) => {
+      const decision = await this.decide(args, metadata, getCustomerRef);
+      if (decision.outcome === "gate") {
+        const message = decision.gate.kind === "activation_required" ? "Activation required" : "Payment required";
+        this.log(`\u274C Error in paywall [PaywallError]: ${message}`);
+        throw new PaywallError(message, decision.gate);
+      }
+      return this.runAllow(decision, handler, metadata, args);
     };
   }
   /**
@@ -957,6 +1163,16 @@ var SolvaPayPaywall = class {
                 this.log(
                   `\u26A0\uFE0F Resolved customer ${customerRef} by email after conflict; using existing customer ${byEmail.customerRef}`
                 );
+                if (!byEmail.externalRef && this.apiClient.updateCustomer) {
+                  try {
+                    await this.apiClient.updateCustomer(byEmail.customerRef, { externalRef });
+                  } catch (backfillError) {
+                    this.log(
+                      `\u26A0\uFE0F Failed to backfill externalRef on ${byEmail.customerRef}:`,
+                      backfillError instanceof Error ? backfillError.message : backfillError
+                    );
+                  }
+                }
                 return byEmail.customerRef;
               }
             } catch (emailLookupError) {
@@ -1033,6 +1249,7 @@ var SolvaPayPaywall = class {
 };
 
 // src/adapters/base.ts
+var EXTRA_FORWARD_KEY2 = "__solvapayExtra";
 var AdapterUtils = class {
   /**
    * Ensure customer reference is properly formatted
@@ -1048,7 +1265,7 @@ var AdapterUtils = class {
    */
   static async extractFromJWT(token, options) {
     try {
-      const { jwtVerify } = await import("./webapi-K5XBCEO6.js");
+      const { jwtVerify } = await import("jose");
       const jwtSecret = new TextEncoder().encode(
         options?.secret || process.env.OAUTH_JWKS_SECRET || "test-jwt-secret"
       );
@@ -1064,23 +1281,45 @@ 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, extra) => {
+    let args;
+    let customerRef;
     try {
-      const args = await adapter.extractArgs(context);
-      const customerRef = await adapter.getCustomerRef(context, extra);
+      args = await adapter.extractArgs(context);
+      customerRef = await adapter.getCustomerRef(context, extra);
       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) {
       return adapter.formatError(error, context);
     }
+    const decideGetCustomerRef = (args2) => args2.auth?.customer_ref || "anonymous";
+    try {
+      const decision = await paywall.decide(args, metadata, decideGetCustomerRef);
+      if (decision.outcome === "gate") {
+        return adapter.formatGate(decision.gate, context);
+      }
+      if (extra !== void 0) {
+        ;
+        args[EXTRA_FORWARD_KEY2] = extra;
+      }
+      try {
+        const result = await paywall.runAllow(decision, businessLogic, metadata, args);
+        return adapter.formatResponse(result, context);
+      } finally {
+        if (EXTRA_FORWARD_KEY2 in args) {
+          delete args[EXTRA_FORWARD_KEY2];
+        }
+      }
+    } catch (error) {
+      if (error instanceof PaywallError) {
+        return adapter.formatGate(error.structuredContent, context);
+      }
+      return adapter.formatError(error, context);
+    }
   };
 }
 
@@ -1128,24 +1367,25 @@ var HttpAdapter = class {
     }
     return result;
   }
-  formatError(error, [_req, reply]) {
-    if (error instanceof PaywallError) {
-      const errorResponse2 = {
-        success: false,
-        error: "Payment required",
-        product: error.structuredContent.product,
-        checkoutUrl: error.structuredContent.checkoutUrl,
-        message: error.structuredContent.message
-      };
-      if (reply && reply.status && typeof reply.json === "function") {
-        reply.status(402).json(errorResponse2);
-        return;
-      }
-      if (reply && reply.code) {
-        reply.code(402);
-      }
-      return errorResponse2;
+  /**
+   * Emit a 402 Payment Required response with the same JSON body shape
+   * REST consumers have always received (`{success:false, error, product,
+   * checkoutUrl, message, ...}`). The shape is reused via
+   * `paywallErrorToClientPayload` so HTTP / Next / hosted-proxy clients
+   * don't have to branch on an SDK version.
+   */
+  formatGate(gate, [_req, reply]) {
+    const errorResponse = paywallErrorToClientPayload(new PaywallError(gate.message, gate));
+    if (reply && reply.status && typeof reply.json === "function") {
+      reply.status(402).json(errorResponse);
+      return;
+    }
+    if (reply && reply.code) {
+      reply.code(402);
     }
+    return errorResponse;
+  }
+  formatError(error, [_req, reply]) {
     const errorResponse = {
       success: false,
       error: error instanceof Error ? error.message : "Internal server error"
@@ -1223,22 +1463,22 @@ var NextAdapter = class {
       headers: { "Content-Type": "application/json" }
     });
   }
+  /**
+   * Emit a 402 Payment Required `Response` with the same JSON body
+   * REST consumers have always received. Reuses
+   * `paywallErrorToClientPayload` so HTTP / Next / hosted-proxy
+   * clients don't have to branch on an SDK version.
+   */
+  formatGate(gate, _context) {
+    return new Response(
+      JSON.stringify(paywallErrorToClientPayload(new PaywallError(gate.message, gate))),
+      {
+        status: 402,
+        headers: { "Content-Type": "application/json" }
+      }
+    );
+  }
   formatError(error, _context) {
-    if (error instanceof PaywallError) {
-      return new Response(
-        JSON.stringify({
-          success: false,
-          error: "Payment required",
-          product: error.structuredContent.product,
-          checkoutUrl: error.structuredContent.checkoutUrl,
-          message: error.structuredContent.message
-        }),
-        {
-          status: 402,
-          headers: { "Content-Type": "application/json" }
-        }
-      );
-    }
     return new Response(
       JSON.stringify({
         success: false,
@@ -1286,19 +1526,27 @@ var McpAdapter = class {
     }
     return response;
   }
+  /**
+   * Emit a plain-narration paywall response — `content[0].text` carries
+   * the gate's human message (LLM-actionable), `structuredContent`
+   * carries the machine-readable gate payload, and `isError` stays
+   * `false` per the MCP spec's own `isError` definition (paywall is
+   * not a self-correctable tool execution error; it is a user-facing
+   * control transfer to the UI).
+   *
+   * Hosts that read widget metadata from `tools/list` or tool-result
+   * `_meta.ui` open the paywall iframe on top of this response;
+   * `buildPayableHandler` stamps the `_meta.ui.resourceUri` envelope
+   * before returning.
+   */
+  formatGate(gate, _context) {
+    return {
+      content: [{ type: "text", text: gate.message }],
+      isError: false,
+      structuredContent: gate
+    };
+  }
   formatError(error, _context) {
-    if (error instanceof PaywallError) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(paywallErrorToClientPayload(error), null, 2)
-          }
-        ],
-        isError: true,
-        structuredContent: error.structuredContent
-      };
-    }
     return {
       content: [
         {
@@ -1703,6 +1951,15 @@ function createSolvaPay(config) {
   };
 }
 
+// src/types/paywall.ts
+function isPaywallStructuredContent(value) {
+  if (typeof value !== "object" || value === null || !("kind" in value)) {
+    return false;
+  }
+  const kind = value.kind;
+  return kind === "payment_required" || kind === "activation_required";
+}
+
 // src/helpers/error.ts
 import { SolvaPayError as SolvaPayError3 } from "@solvapay/core";
 function isErrorResult(result) {
@@ -1728,26 +1985,128 @@ function handleRouteError(error, operationName, defaultMessage) {
 }
 
 // src/helpers/auth.ts
+function base64UrlDecode(input) {
+  const padded = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = padded.length % 4 === 0 ? "" : "=".repeat(4 - padded.length % 4);
+  const base64 = padded + padding;
+  if (typeof atob === "function") {
+    const binary = atob(base64);
+    let result = "";
+    for (let i = 0; i < binary.length; i++) {
+      result += String.fromCharCode(binary.charCodeAt(i));
+    }
+    try {
+      return decodeURIComponent(escape(result));
+    } catch {
+      return result;
+    }
+  }
+  const BufferCtor = globalThis.Buffer;
+  if (BufferCtor) {
+    return BufferCtor.from(base64, "base64").toString("utf-8");
+  }
+  throw new Error("No base64 decoder available in this runtime");
+}
+function decodeJwtUnverified(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  try {
+    const json = base64UrlDecode(parts[1]);
+    const payload = JSON.parse(json);
+    if (typeof payload !== "object" || payload === null) return null;
+    return payload;
+  } catch {
+    return null;
+  }
+}
+function extractBearerToken(request) {
+  const authHeader = request.headers.get("authorization");
+  if (!authHeader || !authHeader.toLowerCase().startsWith("bearer ")) return null;
+  const token = authHeader.slice(7).trim();
+  return token.length > 0 ? token : null;
+}
+function readEnv(name) {
+  const proc = globalThis.process;
+  return proc?.env?.[name];
+}
+function isStrictMode() {
+  return readEnv("SOLVAPAY_AUTH_STRICT") === "true";
+}
+function getConfiguredSecret() {
+  return readEnv("SOLVAPAY_JWT_SECRET") || readEnv("SUPABASE_JWT_SECRET");
+}
+async function verifyHs256(token, secret) {
+  try {
+    const { jwtVerify } = await import("jose");
+    const key = new TextEncoder().encode(secret);
+    const { payload } = await jwtVerify(token, key, { algorithms: ["HS256"] });
+    return payload;
+  } catch {
+    return null;
+  }
+}
+function pickName(payload) {
+  const metadataFullName = typeof payload.user_metadata?.full_name === "string" ? payload.user_metadata.full_name : null;
+  const metadataName = typeof payload.user_metadata?.name === "string" ? payload.user_metadata.name : null;
+  const claimName = typeof payload.name === "string" ? payload.name : null;
+  return metadataFullName || metadataName || claimName || null;
+}
+function pickEmail(payload) {
+  return typeof payload.email === "string" ? payload.email : null;
+}
+function unauthorized(details) {
+  return { error: "Unauthorized", status: 401, details };
+}
 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 includeEmail = options.includeEmail !== false;
+    const includeName = options.includeName !== false;
+    const headerUserId = request.headers.get("x-user-id");
+    if (headerUserId) {
+      let email = null;
+      let name = null;
+      if (includeEmail || includeName) {
+        const token2 = extractBearerToken(request);
+        if (token2) {
+          const secret2 = getConfiguredSecret();
+          const payload2 = secret2 ? await verifyHs256(token2, secret2) : isStrictMode() ? null : decodeJwtUnverified(token2);
+          if (payload2) {
+            if (includeEmail) email = pickEmail(payload2);
+            if (includeName) name = pickName(payload2);
+          }
+        }
+      }
+      return { userId: headerUserId, email, name };
+    }
+    const token = extractBearerToken(request);
+    if (!token) {
+      return unauthorized("User ID not found. Ensure middleware is configured.");
+    }
+    const secret = getConfiguredSecret();
+    let payload = null;
+    if (secret) {
+      payload = await verifyHs256(token, secret);
+      if (!payload) {
+        return unauthorized("Invalid or expired authentication token");
+      }
+    } else if (isStrictMode()) {
+      return unauthorized(
+        "Strict auth mode is enabled but no JWT secret is configured. Set SOLVAPAY_JWT_SECRET or SUPABASE_JWT_SECRET."
+      );
+    } else {
+      payload = decodeJwtUnverified(token);
+      if (!payload) {
+        return unauthorized("Malformed authentication token");
+      }
+    }
+    const userId = typeof payload.sub === "string" ? payload.sub : null;
+    if (!userId) {
+      return unauthorized("Authentication token missing subject (sub) claim");
     }
-    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
+      email: includeEmail ? pickEmail(payload) : null,
+      name: includeName ? pickName(payload) : null
     };
   } catch (error) {
     return handleRouteError(error, "Get authenticated user", "Authentication failed");
@@ -2140,9 +2499,34 @@ async function activatePlanCore(request, body, options = {}) {
   }
 }
 
+// src/helpers/payment-method.ts
+async function getPaymentMethodCore(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();
+    if (!solvaPay.apiClient.getPaymentMethod) {
+      return {
+        error: "getPaymentMethod is not implemented on this API client",
+        status: 500
+      };
+    }
+    return await solvaPay.apiClient.getPaymentMethod({ customerRef });
+  } catch (error) {
+    return handleRouteError(error, "Get payment method", "Failed to load payment method");
+  }
+}
+
 // 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");
@@ -2152,19 +2536,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",
@@ -2181,6 +2566,76 @@ 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 {
@@ -2238,6 +2693,37 @@ async function checkPurchaseCore(request, options = {}) {
 }
 
 // src/helpers/usage.ts
+async function getUsageCore(request, options = {}) {
+  const purchaseResult = await checkPurchaseCore(request, options);
+  if (isErrorResult(purchaseResult)) return purchaseResult;
+  const activePurchase = (purchaseResult.purchases ?? []).find((p) => p.status === "active");
+  if (!activePurchase) {
+    return {
+      meterRef: null,
+      total: null,
+      used: 0,
+      remaining: null,
+      percentUsed: null
+    };
+  }
+  const snap = activePurchase.planSnapshot;
+  const usage = activePurchase.usage;
+  const meterRef = snap?.meterRef ?? snap?.meterId ?? null;
+  const total = typeof snap?.limit === "number" ? snap.limit : null;
+  const used = typeof usage?.used === "number" ? usage.used : 0;
+  const remaining = total !== null ? Math.max(0, total - used) : null;
+  const percentUsed = total !== null && total > 0 ? Math.min(100, Math.round(used / total * 1e4) / 100) : null;
+  return {
+    meterRef,
+    total,
+    used,
+    remaining,
+    percentUsed,
+    ...usage?.periodStart ? { periodStart: usage.periodStart } : {},
+    ...usage?.periodEnd ? { periodEnd: usage.periodEnd } : {},
+    purchaseRef: activePurchase.reference
+  };
+}
 async function trackUsageCore(request, body, options = {}) {
   try {
     const userResult = await getAuthenticatedUserCore(request);
@@ -2319,8 +2805,11 @@ async function verifyWebhook({
 export {
   PaywallError,
   activatePlanCore,
+  buildGateMessage,
+  buildNudgeMessage,
   cancelPurchaseCore,
   checkPurchaseCore,
+  classifyPaywallState,
   createCheckoutSessionCore,
   createCustomerSessionCore,
   createPaymentIntentCore,
@@ -2329,8 +2818,13 @@ export {
   createTopupPaymentIntentCore,
   getAuthenticatedUserCore,
   getCustomerBalanceCore,
+  getMerchantCore,
+  getPaymentMethodCore,
+  getProductCore,
+  getUsageCore,
   handleRouteError,
   isErrorResult,
+  isPaywallStructuredContent,
   listPlansCore,
   paywallErrorToClientPayload,
   processPaymentIntentCore,