@solvapay/server 1.0.1-preview.2 → 1.0.1-preview.4

package/dist/index.js

@@ -163,6 +163,21 @@ function createSolvaPayClient(opts) {
       }
       return await res.json();
     },
+    // PUT: /v1/sdk/products/{productRef}/mcp/plans
+    async configureMcpPlans(productRef, params) {
+      const url = `${base}/v1/sdk/products/${productRef}/mcp/plans`;
+      const res = await fetch(url, {
+        method: "PUT",
+        headers,
+        body: JSON.stringify(params)
+      });
+      if (!res.ok) {
+        const error = await res.text();
+        log(`\u274C API Error: ${res.status} - ${error}`);
+        throw new SolvaPayError(`Configure MCP plans failed (${res.status}): ${error}`);
+      }
+      return await res.json();
+    },
     // DELETE: /v1/sdk/products/{productRef}
     async deleteProduct(productRef) {
       const url = `${base}/v1/sdk/products/${productRef}`;
@@ -561,6 +576,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)
@@ -620,6 +653,7 @@ var SolvaPayPaywall = class {
         let withinLimits;
         let remaining;
         let checkoutUrl;
+        let lastLimitsCheck;
         const hasFreshCachedLimits = cachedLimits && now - cachedLimits.timestamp < this.limitsCacheTTL;
         if (hasFreshCachedLimits) {
           checkoutUrl = cachedLimits.checkoutUrl;
@@ -646,6 +680,7 @@ var SolvaPayPaywall = class {
             ...configuredPlanRef ? { planRef: configuredPlanRef } : {},
             meterName: usageType
           });
+          lastLimitsCheck = limitsCheck;
           withinLimits = limitsCheck.withinLimits;
           remaining = limitsCheck.remaining;
           checkoutUrl = limitsCheck.checkoutUrl;
@@ -674,6 +709,20 @@ var SolvaPayPaywall = class {
             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,
@@ -776,7 +825,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;
@@ -800,7 +850,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");
@@ -823,7 +876,8 @@ var SolvaPayPaywall = class {
             try {
               const retryParams = {
                 email: `${customerRef}-${Date.now()}@auto-created.local`,
-                externalRef
+                externalRef,
+                metadata: {}
               };
               if (options?.name) {
                 retryParams.name = options.name;
@@ -920,10 +974,10 @@ 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) => {
+  return async (context, extra) => {
     try {
       const args = await adapter.extractArgs(context);
-      const customerRef = await adapter.getCustomerRef(context);
+      const customerRef = await adapter.getCustomerRef(context, extra);
       let backendRef = backendRefCache.get(customerRef);
       if (!backendRef) {
         backendRef = await paywall.ensureCustomer(customerRef, customerRef);
@@ -1114,18 +1168,18 @@ var McpAdapter = class {
   extractArgs(args) {
     return args;
   }
-  async getCustomerRef(args) {
+  async getCustomerRef(args, extra) {
     if (this.options.getCustomerRef) {
-      const ref = await this.options.getCustomerRef(args);
+      const ref = await this.options.getCustomerRef(args, extra);
       return AdapterUtils.ensureCustomerRef(ref);
     }
-    const auth = args?.auth;
-    const customerRef = auth?.customer_ref || "anonymous";
+    const customerRefFromExtra = extra?.authInfo?.extra?.customer_ref;
+    const customerRef = typeof customerRefFromExtra === "string" && customerRefFromExtra.trim() ? customerRefFromExtra.trim() : "anonymous";
     return AdapterUtils.ensureCustomerRef(customerRef);
   }
   formatResponse(result, _context) {
     const transformed = this.options.transformResponse ? this.options.transformResponse(result) : result;
-    return {
+    const response = {
       content: [
         {
           type: "text",
@@ -1133,6 +1187,10 @@ var McpAdapter = class {
         }
       ]
     };
+    if (transformed && typeof transformed === "object" && !Array.isArray(transformed)) {
+      response.structuredContent = transformed;
+    }
+    return response;
   }
   formatError(error, _context) {
     if (error instanceof PaywallError) {
@@ -1140,17 +1198,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,
@@ -1220,8 +1268,8 @@ function mcpErrorResult(message) {
   return { content: [{ type: "text", text: JSON.stringify({ error: message }) }], isError: true };
 }
 function createGetUserInfoHandler(apiClient, productRef, getCustomerRef) {
-  return async (args) => {
-    const customerRef = getCustomerRef(args);
+  return async (args, extra) => {
+    const customerRef = getCustomerRef(args, extra);
     try {
       if (!apiClient.getUserInfo) {
         return mcpErrorResult("getUserInfo is not available on this API client");
@@ -1236,12 +1284,12 @@ function createGetUserInfoHandler(apiClient, productRef, getCustomerRef) {
   };
 }
 function createUpgradeHandler(apiClient, productRef, getCustomerRef) {
-  return async (args) => {
-    const customerRef = getCustomerRef(args);
+  return async (args, extra) => {
+    const customerRef = getCustomerRef(args, extra);
     const planRef = typeof args.planRef === "string" ? args.planRef : void 0;
     try {
       const result = await apiClient.createCheckoutSession({
-        customerReference: customerRef,
+        customerRef,
         productRef,
         ...planRef && { planRef }
       });
@@ -1268,8 +1316,8 @@ You'll be able to compare options and select the one that's right for you.`;
   };
 }
 function createManageAccountHandler(apiClient, productRef, getCustomerRef) {
-  return async (args) => {
-    const customerRef = getCustomerRef(args);
+  return async (args, extra) => {
+    const customerRef = getCustomerRef(args, extra);
     try {
       const session = await apiClient.createCustomerSession({ customerRef, productRef });
       const portalUrl = session.customerUrl;
@@ -1312,6 +1360,98 @@ function createVirtualTools(apiClient, options) {
   return allTools.filter((t) => !excludeSet.has(t.name));
 }
 
+// src/register-virtual-tools-mcp.ts
+import { createRequire } from "module";
+function getNodeRequire() {
+  try {
+    return (0, eval)("require");
+  } catch {
+    return createRequire(`${process.cwd()}/package.json`);
+  }
+}
+var nodeRequire = getNodeRequire();
+function getZod() {
+  try {
+    const zodModule = nodeRequire("zod");
+    return zodModule.z ?? zodModule;
+  } catch {
+    throw new Error(
+      "zod is required to use registerVirtualToolsMcp(). Install it as a dependency in your MCP server project."
+    );
+  }
+}
+function isJsonSchemaObject(value) {
+  return Boolean(value && typeof value === "object");
+}
+function toZodSchema(property) {
+  const z = getZod();
+  if (Array.isArray(property.enum) && property.enum.length > 0) {
+    if (property.enum.every((value) => typeof value === "string")) {
+      const [first, ...rest] = property.enum;
+      return z.enum([first, ...rest]);
+    }
+    if (property.enum.length === 1) {
+      return z.literal(property.enum[0]);
+    }
+    return z.union(property.enum.map((value) => z.literal(value)));
+  }
+  switch (property.type) {
+    case "string":
+      return z.string();
+    case "number":
+      return z.number();
+    case "integer":
+      return z.number().int();
+    case "boolean":
+      return z.boolean();
+    case "array":
+      return z.array(
+        isJsonSchemaObject(property.items) ? toZodSchema(property.items) : z.any()
+      );
+    case "object":
+      return z.object(jsonSchemaToZodRawShape(property.properties || {}));
+    default:
+      return z.any();
+  }
+}
+function jsonSchemaToZodRawShape(properties, required = []) {
+  const requiredSet = new Set(required);
+  return Object.fromEntries(
+    Object.entries(properties).map(([name, property]) => {
+      const schema = toZodSchema(property);
+      const finalSchema = requiredSet.has(name) ? schema : schema.optional();
+      return [name, finalSchema];
+    })
+  );
+}
+function defaultGetCustomerRef(_args, extra) {
+  const fromExtra = extra?.authInfo?.extra?.customer_ref;
+  return typeof fromExtra === "string" && fromExtra.trim() ? fromExtra.trim() : "anonymous";
+}
+function registerVirtualToolsMcpImpl(server, apiClient, options) {
+  const { filter, mapDefinition, wrapHandler, getCustomerRef, ...virtualToolsOptions } = options;
+  const virtualTools = createVirtualTools(apiClient, {
+    ...virtualToolsOptions,
+    getCustomerRef: getCustomerRef || defaultGetCustomerRef
+  });
+  for (const toolDefinition of virtualTools) {
+    if (filter && !filter(toolDefinition)) continue;
+    const mappedDefinition = mapDefinition ? mapDefinition(toolDefinition) : toolDefinition;
+    const wrappedHandler = wrapHandler ? wrapHandler(mappedDefinition.handler, mappedDefinition) : mappedDefinition.handler;
+    server.registerTool(
+      mappedDefinition.name,
+      {
+        description: mappedDefinition.description,
+        inputSchema: jsonSchemaToZodRawShape(
+          mappedDefinition.inputSchema.properties,
+          mappedDefinition.inputSchema.required || []
+        )
+      },
+      wrappedHandler
+    );
+  }
+}
+
 // src/factory.ts
 function createSolvaPay(config) {
   let resolvedConfig;
@@ -1361,14 +1501,14 @@ 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);
     },
     createCheckoutSession(params) {
       return apiClient.createCheckoutSession({
-        customerReference: params.customerRef,
+        customerRef: params.customerRef,
         productRef: params.productRef,
         planRef: params.planRef
       });
@@ -1382,9 +1522,18 @@ function createSolvaPay(config) {
       }
       return apiClient.bootstrapMcpProduct(params);
     },
+    configureMcpPlans(productRef, params) {
+      if (!apiClient.configureMcpPlans) {
+        throw new SolvaPayError2("configureMcpPlans is not available on this API client");
+      }
+      return apiClient.configureMcpPlans(productRef, params);
+    },
     getVirtualTools(options) {
       return createVirtualTools(apiClient, options);
     },
+    async registerVirtualToolsMcp(server, options) {
+      await registerVirtualToolsMcpImpl(server, apiClient, options);
+    },
     // Payable API for framework-specific handlers
     payable(options = {}) {
       const product = options.productRef || options.product || process.env.SOLVAPAY_PRODUCT || "default-product";
@@ -1423,9 +1572,9 @@ function createSolvaPay(config) {
             getCustomerRef: adapterOptions?.getCustomerRef || options.getCustomerRef
           });
           const handlerPromise = createAdapterHandler(adapter, paywall, metadata, businessLogic);
-          return async (args) => {
+          return async (args, extra) => {
             const handler = await handlerPromise;
-            return handler(args);
+            return handler(args, extra);
           };
         },
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -1495,6 +1644,167 @@ function getCustomerRefFromBearerAuthHeader(authorization, options = {}) {
   return getCustomerRefFromJwtPayload(payload, options);
 }
 
+// src/mcp/auth-bridge.ts
+function getClientId(payload, explicitClientId) {
+  if (explicitClientId) return explicitClientId;
+  const payloadClientId = typeof payload.client_id === "string" && payload.client_id || typeof payload.azp === "string" && payload.azp || typeof payload.aud === "string" && payload.aud || null;
+  return payloadClientId || "solvapay-mcp-client";
+}
+function getScopes(payload, defaultScopes) {
+  if (Array.isArray(payload.scp)) {
+    return payload.scp.filter((scope) => typeof scope === "string");
+  }
+  if (typeof payload.scope === "string" && payload.scope.trim()) {
+    return payload.scope.split(/\s+/).map((scope) => scope.trim()).filter(Boolean);
+  }
+  return defaultScopes;
+}
+function getExpiresAt(payload) {
+  return typeof payload.exp === "number" ? payload.exp : void 0;
+}
+function buildAuthInfoFromBearer(authorization, options = {}) {
+  const token = extractBearerToken(authorization);
+  if (!token) return null;
+  const payload = decodeJwtPayload(token);
+  const customerRef = getCustomerRefFromJwtPayload(payload, options);
+  const clientId = getClientId(payload, options.clientId);
+  const scopes = getScopes(payload, options.defaultScopes || []);
+  const expiresAt = getExpiresAt(payload);
+  return {
+    token,
+    clientId,
+    scopes,
+    expiresAt,
+    extra: {
+      customer_ref: customerRef,
+      ...options.includePayload ? { payload } : {}
+    }
+  };
+}
+
+// src/mcp/oauth-bridge.ts
+function withoutTrailingSlash(value) {
+  return value.replace(/\/$/, "");
+}
+function getRequestAuthHeader(req) {
+  const header = req.headers?.authorization;
+  if (typeof header === "string") return header;
+  if (Array.isArray(header)) return header[0] || null;
+  return null;
+}
+function getRequestJsonRpcId(body) {
+  if (body && typeof body === "object" && "id" in body) {
+    const id = body.id;
+    return id ?? null;
+  }
+  return null;
+}
+function makeUnauthorizedJsonRpc(id) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code: -32001,
+      message: "Unauthorized"
+    }
+  };
+}
+function setMcpChallengeHeader(res, publicBaseUrl, protectedResourcePath) {
+  res.setHeader(
+    "WWW-Authenticate",
+    `Bearer resource_metadata="${withoutTrailingSlash(publicBaseUrl)}${protectedResourcePath}"`
+  );
+}
+function getOAuthProtectedResourceResponse(publicBaseUrl) {
+  const resource = withoutTrailingSlash(publicBaseUrl);
+  return {
+    resource,
+    authorization_servers: [resource],
+    scopes_supported: ["openid", "profile", "email"]
+  };
+}
+function getOAuthAuthorizationServerResponse({
+  apiBaseUrl,
+  productRef
+}) {
+  const normalizedApiBaseUrl = withoutTrailingSlash(apiBaseUrl);
+  const registrationEndpoint = `${normalizedApiBaseUrl}/v1/customer/auth/register?product_ref=${encodeURIComponent(productRef)}`;
+  return {
+    issuer: normalizedApiBaseUrl,
+    authorization_endpoint: `${normalizedApiBaseUrl}/v1/customer/auth/authorize`,
+    token_endpoint: `${normalizedApiBaseUrl}/v1/customer/auth/token`,
+    registration_endpoint: registrationEndpoint,
+    token_endpoint_auth_methods_supported: ["client_secret_basic", "client_secret_post"],
+    response_types_supported: ["code"],
+    grant_types_supported: ["authorization_code", "refresh_token"],
+    scopes_supported: ["openid", "profile", "email"],
+    code_challenge_methods_supported: ["S256"]
+  };
+}
+function createMcpOAuthBridge(options) {
+  const {
+    publicBaseUrl,
+    apiBaseUrl,
+    productRef,
+    mcpPath = "/mcp",
+    requireAuth = true,
+    authInfo,
+    protectedResourcePath = "/.well-known/oauth-protected-resource",
+    authorizationServerPath = "/.well-known/oauth-authorization-server"
+  } = options;
+  const protectedResourceMiddleware = (req, res, next) => {
+    if (req.method !== "GET" || req.path !== protectedResourcePath) {
+      next();
+      return;
+    }
+    res.json(getOAuthProtectedResourceResponse(publicBaseUrl));
+  };
+  const authorizationServerMiddleware = (req, res, next) => {
+    if (req.method !== "GET" || req.path !== authorizationServerPath) {
+      next();
+      return;
+    }
+    if (!productRef) {
+      res.status(500).json({ error: "SOLVAPAY_PRODUCT_REF missing" });
+      return;
+    }
+    res.json(
+      getOAuthAuthorizationServerResponse({
+        apiBaseUrl,
+        productRef
+      })
+    );
+  };
+  const mcpAuthMiddleware = (req, res, next) => {
+    if (req.path !== mcpPath) {
+      next();
+      return;
+    }
+    const authHeader = getRequestAuthHeader(req);
+    const id = getRequestJsonRpcId(req.body);
+    if (!authHeader && !requireAuth) {
+      next();
+      return;
+    }
+    try {
+      const auth = buildAuthInfoFromBearer(authHeader, authInfo);
+      if (!auth) {
+        throw new McpBearerAuthError("Missing bearer token");
+      }
+      req.auth = auth;
+      next();
+    } catch {
+      setMcpChallengeHeader(res, publicBaseUrl, protectedResourcePath);
+      if (req.method === "POST") {
+        res.status(401).json(makeUnauthorizedJsonRpc(id));
+        return;
+      }
+      res.status(401).json({ error: "Unauthorized" });
+    }
+  };
+  return [protectedResourceMiddleware, authorizationServerMiddleware, mcpAuthMiddleware];
+}
+
 // src/helpers/error.ts
 import { SolvaPayError as SolvaPayError3 } from "@solvapay/core";
 function isErrorResult(result) {
@@ -1848,9 +2158,11 @@ export {
   McpBearerAuthError,
   PaywallError,
   VIRTUAL_TOOL_DEFINITIONS,
+  buildAuthInfoFromBearer,
   cancelPurchaseCore,
   createCheckoutSessionCore,
   createCustomerSessionCore,
+  createMcpOAuthBridge,
   createPaymentIntentCore,
   createSolvaPay,
   createSolvaPayClient,
@@ -1860,10 +2172,15 @@ export {
   getAuthenticatedUserCore,
   getCustomerRefFromBearerAuthHeader,
   getCustomerRefFromJwtPayload,
+  getOAuthAuthorizationServerResponse,
+  getOAuthProtectedResourceResponse,
   handleRouteError,
   isErrorResult,
+  jsonSchemaToZodRawShape,
   listPlansCore,
+  paywallErrorToClientPayload,
   processPaymentIntentCore,
+  registerVirtualToolsMcpImpl,
   syncCustomerCore,
   verifyWebhook,
   withRetry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solvapay/server",
-  "version": "1.0.1-preview.2",
+  "version": "1.0.1-preview.4",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -37,10 +37,20 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@solvapay/core": "1.0.1-preview.2"
+    "@solvapay/core": "1.0.1-preview.4"
   },
   "peerDependencies": {
-    "@solvapay/auth": "1.0.1-preview.2"
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "zod": "^3.25.0 || ^4.0.0",
+    "@solvapay/auth": "1.0.1-preview.4"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "dotenv": "^17.3.1",
@@ -50,7 +60,7 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.2",
-    "@solvapay/auth": "1.0.1-preview.2",
+    "@solvapay/auth": "1.0.1-preview.4",
     "@solvapay/demo-services": "0.0.0",
     "@solvapay/test-utils": "^0.0.0"
   },