@solvapay/server 1.0.7 → 1.0.8-preview.2

package/dist/index.cjs

@@ -4317,6 +4317,7 @@ __export(index_exports, {
   activatePlanCore: () => activatePlanCore,
   buildAuthInfoFromBearer: () => buildAuthInfoFromBearer,
   cancelPurchaseCore: () => cancelPurchaseCore,
+  checkPurchaseCore: () => checkPurchaseCore,
   createCheckoutSessionCore: () => createCheckoutSessionCore,
   createCustomerSessionCore: () => createCustomerSessionCore,
   createMcpOAuthBridge: () => createMcpOAuthBridge,
@@ -4331,8 +4332,10 @@ __export(index_exports, {
   getCustomerBalanceCore: () => getCustomerBalanceCore,
   getCustomerRefFromBearerAuthHeader: () => getCustomerRefFromBearerAuthHeader,
   getCustomerRefFromJwtPayload: () => getCustomerRefFromJwtPayload,
+  getMerchantCore: () => getMerchantCore,
   getOAuthAuthorizationServerResponse: () => getOAuthAuthorizationServerResponse,
   getOAuthProtectedResourceResponse: () => getOAuthProtectedResourceResponse,
+  getProductCore: () => getProductCore,
   handleRouteError: () => handleRouteError,
   isErrorResult: () => isErrorResult,
   jsonSchemaToZodRawShape: () => jsonSchemaToZodRawShape,
@@ -4342,12 +4345,13 @@ __export(index_exports, {
   reactivatePurchaseCore: () => reactivatePurchaseCore,
   registerVirtualToolsMcpImpl: () => registerVirtualToolsMcpImpl,
   syncCustomerCore: () => syncCustomerCore,
+  trackUsageCore: () => trackUsageCore,
   verifyWebhook: () => verifyWebhook,
   withRetry: () => withRetry
 });
 module.exports = __toCommonJS(index_exports);
 var import_node_crypto = __toESM(require("crypto"), 1);
-var import_core6 = require("@solvapay/core");
+var import_core8 = require("@solvapay/core");
 
 // src/client.ts
 var import_core = require("@solvapay/core");
@@ -4455,6 +4459,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 import_core.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 import_core.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() {
@@ -6060,7 +6094,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;
@@ -6701,7 +6736,7 @@ async function activatePlanCore(request, body, options = {}) {
 
 // src/helpers/plans.ts
 var import_core5 = require("@solvapay/core");
-async function listPlansCore(request) {
+async function listPlansCore(request, options = {}) {
   try {
     const url = new URL(request.url);
     const productRef = url.searchParams.get("productRef");
@@ -6711,19 +6746,20 @@ async function listPlansCore(request) {
         status: 400
       };
     }
-    const config = (0, import_core5.getSolvaPayConfig)();
-    const solvapaySecretKey = config.apiKey;
-    const solvapayApiBaseUrl = config.apiBaseUrl;
-    if (!solvapaySecretKey) {
+    const apiClient = options.solvaPay?.apiClient ?? (() => {
+      const config = (0, import_core5.getSolvaPayConfig)();
+      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",
@@ -6740,6 +6776,159 @@ async function listPlansCore(request) {
   }
 }
 
+// src/helpers/merchant.ts
+var import_core6 = require("@solvapay/core");
+async function getMerchantCore(_request, options = {}) {
+  try {
+    const apiClient = options.solvaPay?.apiClient ?? (() => {
+      const config = (0, import_core6.getSolvaPayConfig)();
+      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
+var import_core7 = require("@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 = (0, import_core7.getSolvaPayConfig)();
+      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,
@@ -6747,34 +6936,34 @@ function verifyWebhook({
   secret
 }) {
   const toleranceSec = 300;
-  if (!signature) throw new import_core6.SolvaPayError("Missing webhook signature");
+  if (!signature) throw new import_core8.SolvaPayError("Missing webhook signature");
   const parts = signature.split(",");
   const tPart = parts.find((p) => p.startsWith("t="));
   const v1Part = parts.find((p) => p.startsWith("v1="));
   if (!tPart || !v1Part) {
-    throw new import_core6.SolvaPayError("Malformed webhook signature");
+    throw new import_core8.SolvaPayError("Malformed webhook signature");
   }
   const timestamp = parseInt(tPart.slice(2), 10);
   const receivedHmac = v1Part.slice(3);
   if (Number.isNaN(timestamp) || !receivedHmac) {
-    throw new import_core6.SolvaPayError("Malformed webhook signature");
+    throw new import_core8.SolvaPayError("Malformed webhook signature");
   }
   if (toleranceSec > 0) {
     const age = Math.abs(Math.floor(Date.now() / 1e3) - timestamp);
     if (age > toleranceSec) {
-      throw new import_core6.SolvaPayError("Webhook signature timestamp too old");
+      throw new import_core8.SolvaPayError("Webhook signature timestamp too old");
     }
   }
   const expectedHmac = import_node_crypto.default.createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
   if (receivedHmac.length !== expectedHmac.length) {
-    throw new import_core6.SolvaPayError("Invalid webhook signature");
+    throw new import_core8.SolvaPayError("Invalid webhook signature");
   }
   const ok = import_node_crypto.default.timingSafeEqual(Buffer.from(expectedHmac), Buffer.from(receivedHmac));
-  if (!ok) throw new import_core6.SolvaPayError("Invalid webhook signature");
+  if (!ok) throw new import_core8.SolvaPayError("Invalid webhook signature");
   try {
     return JSON.parse(body);
   } catch {
-    throw new import_core6.SolvaPayError("Invalid webhook payload: body is not valid JSON");
+    throw new import_core8.SolvaPayError("Invalid webhook payload: body is not valid JSON");
   }
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -6785,6 +6974,7 @@ function verifyWebhook({
   activatePlanCore,
   buildAuthInfoFromBearer,
   cancelPurchaseCore,
+  checkPurchaseCore,
   createCheckoutSessionCore,
   createCustomerSessionCore,
   createMcpOAuthBridge,
@@ -6799,8 +6989,10 @@ function verifyWebhook({
   getCustomerBalanceCore,
   getCustomerRefFromBearerAuthHeader,
   getCustomerRefFromJwtPayload,
+  getMerchantCore,
   getOAuthAuthorizationServerResponse,
   getOAuthProtectedResourceResponse,
+  getProductCore,
   handleRouteError,
   isErrorResult,
   jsonSchemaToZodRawShape,
@@ -6810,6 +7002,7 @@ function verifyWebhook({
   reactivatePurchaseCore,
   registerVirtualToolsMcpImpl,
   syncCustomerCore,
+  trackUsageCore,
   verifyWebhook,
   withRetry
 });

package/dist/index.d.cts

@@ -2488,6 +2488,26 @@ interface ProcessPaymentResult {
     status: 'completed';
 }
 type ActivatePlanResult = components['schemas']['ActivatePlanResponseDto'];
+/**
+ * SDK-facing merchant identity (source: GET /v1/sdk/merchant).
+ *
+ * Hand-typed here until the OpenAPI generator picks up the new endpoint.
+ * Fields match `SdkMerchantResponseDto` on the backend.
+ */
+type SdkMerchantResponse = {
+    displayName: string;
+    legalName: string;
+    supportEmail?: string;
+    supportUrl?: string;
+    termsUrl?: string;
+    privacyUrl?: string;
+    country?: string;
+    defaultCurrency?: string;
+    statementDescriptor?: string;
+    logoUrl?: string;
+};
+/** SDK-facing product projection. Sourced from the existing OpenAPI spec. */
+type SdkProductResponse = components['schemas']['SdkProductResponse'];
 type McpBootstrapPlanInput = NonNullable<components['schemas']['McpBootstrapDto']['plans']>[number];
 type ToolPlanMappingInput = NonNullable<components['schemas']['McpBootstrapDto']['tools']>[number];
 type McpBootstrapRequest = components['schemas']['McpBootstrapDto'];
@@ -2556,6 +2576,13 @@ interface SolvaPayClient {
         externalRef?: string;
         email?: string;
     }): Promise<CustomerResponseMapped>;
+    /**
+     * SDK-facing merchant identity (GET /v1/sdk/merchant).
+     * Returns the subset of provider fields safe for browser consumption —
+     * used by `<MandateText>`, `<CheckoutSummary>`, and trust signals.
+     */
+    getMerchant?(): Promise<SdkMerchantResponse>;
+    getProduct?(productRef: string): Promise<SdkProductResponse>;
     listProducts?(): Promise<Array<{
         reference: string;
         name: string;
@@ -4116,13 +4143,85 @@ declare function activatePlanCore(request: Request, body: {
 
 type Plan = components['schemas']['Plan'];
 /**
- * List plans - core implementation
+ * List plans - core implementation.
+ *
+ * Pass `options.solvaPay` to route through a pre-configured SolvaPay instance
+ * (e.g. stub-backed in examples). When omitted, the helper reads
+ * `SOLVAPAY_SECRET_KEY` from environment and constructs a real API client.
  */
-declare function listPlansCore(request: Request): Promise<{
+declare function listPlansCore(request: Request, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<{
     plans: Plan[];
     productRef: string;
 } | ErrorResult>;
 
+/**
+ * Merchant Helper (Core)
+ *
+ * Generic helper for GET /api/merchant — returns the SDK-facing merchant
+ * identity used by `<MandateText>`, `<CheckoutSummary>`, and trust signals.
+ * Works with standard Web API Request (Express, Fastify, Next.js, Edge).
+ */
+
+declare function getMerchantCore(_request: Request, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<SdkMerchantResponse | ErrorResult>;
+
+/**
+ * Product Helper (Core)
+ *
+ * Generic helper for GET /api/get-product?productRef=...
+ * Returns a single product by reference, used by the `useProduct` React hook.
+ */
+
+declare function getProductCore(request: Request, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<SdkProductResponse | ErrorResult>;
+
+interface PurchaseCheckResult {
+    customerRef: string;
+    email?: string;
+    name?: string;
+    purchases: Array<{
+        reference: string;
+        productName?: string;
+        productRef?: string;
+        status?: string;
+        startDate?: string;
+        planSnapshot?: {
+            meterId?: string;
+            limit?: number;
+            freeUnits?: number;
+        };
+        usage?: {
+            used?: number;
+            overageUnits?: number;
+            overageCost?: number;
+            periodStart?: string;
+            periodEnd?: string;
+        };
+        [key: string]: unknown;
+    }>;
+}
+declare function checkPurchaseCore(request: Request, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<PurchaseCheckResult | ErrorResult>;
+
+declare function trackUsageCore(request: Request, body: {
+    actionType?: 'transaction' | 'api_call' | 'hour' | 'email' | 'storage' | 'custom';
+    units?: number;
+    productRef?: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<{
+    success: true;
+} | ErrorResult>;
+
 /**
  * SolvaPay Server SDK
  *
@@ -4178,4 +4277,4 @@ declare function verifyWebhook({ body, signature, secret, }: {
     secret: string;
 }): WebhookEvent;
 
-export { type ActivatePlanResult, type AuthenticatedUser, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type McpAdapterOptions, McpBearerAuthError, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolExtra, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableFunction, type PayableOptions, type PaywallArgs, PaywallError, type PaywallMetadata, type PaywallStructuredContent, type PaywallToolResult, type ProcessPaymentResult, type RegisterVirtualToolsMcpOptions, type RetryOptions, type ServerClientOptions, type SolvaPay, type SolvaPayClient, type ToolPlanMappingInput, VIRTUAL_TOOL_DEFINITIONS, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, buildAuthInfoFromBearer, cancelPurchaseCore, type components, createCheckoutSessionCore, createCustomerSessionCore, createMcpOAuthBridge, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, createVirtualTools, decodeJwtPayload, extractBearerToken, getAuthenticatedUserCore, getCustomerBalanceCore, getCustomerRefFromBearerAuthHeader, getCustomerRefFromJwtPayload, getOAuthAuthorizationServerResponse, getOAuthProtectedResourceResponse, handleRouteError, isErrorResult, jsonSchemaToZodRawShape, listPlansCore, paywallErrorToClientPayload, processPaymentIntentCore, reactivatePurchaseCore, registerVirtualToolsMcpImpl, syncCustomerCore, verifyWebhook, withRetry };
+export { type ActivatePlanResult, type AuthenticatedUser, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type McpAdapterOptions, McpBearerAuthError, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolExtra, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableFunction, type PayableOptions, type PaywallArgs, PaywallError, type PaywallMetadata, type PaywallStructuredContent, type PaywallToolResult, type ProcessPaymentResult, type PurchaseCheckResult, type RegisterVirtualToolsMcpOptions, type RetryOptions, type SdkMerchantResponse, type SdkProductResponse, type ServerClientOptions, type SolvaPay, type SolvaPayClient, type ToolPlanMappingInput, VIRTUAL_TOOL_DEFINITIONS, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, buildAuthInfoFromBearer, cancelPurchaseCore, checkPurchaseCore, type components, 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 };

package/dist/index.d.ts

@@ -2488,6 +2488,26 @@ interface ProcessPaymentResult {
     status: 'completed';
 }
 type ActivatePlanResult = components['schemas']['ActivatePlanResponseDto'];
+/**
+ * SDK-facing merchant identity (source: GET /v1/sdk/merchant).
+ *
+ * Hand-typed here until the OpenAPI generator picks up the new endpoint.
+ * Fields match `SdkMerchantResponseDto` on the backend.
+ */
+type SdkMerchantResponse = {
+    displayName: string;
+    legalName: string;
+    supportEmail?: string;
+    supportUrl?: string;
+    termsUrl?: string;
+    privacyUrl?: string;
+    country?: string;
+    defaultCurrency?: string;
+    statementDescriptor?: string;
+    logoUrl?: string;
+};
+/** SDK-facing product projection. Sourced from the existing OpenAPI spec. */
+type SdkProductResponse = components['schemas']['SdkProductResponse'];
 type McpBootstrapPlanInput = NonNullable<components['schemas']['McpBootstrapDto']['plans']>[number];
 type ToolPlanMappingInput = NonNullable<components['schemas']['McpBootstrapDto']['tools']>[number];
 type McpBootstrapRequest = components['schemas']['McpBootstrapDto'];
@@ -2556,6 +2576,13 @@ interface SolvaPayClient {
         externalRef?: string;
         email?: string;
     }): Promise<CustomerResponseMapped>;
+    /**
+     * SDK-facing merchant identity (GET /v1/sdk/merchant).
+     * Returns the subset of provider fields safe for browser consumption —
+     * used by `<MandateText>`, `<CheckoutSummary>`, and trust signals.
+     */
+    getMerchant?(): Promise<SdkMerchantResponse>;
+    getProduct?(productRef: string): Promise<SdkProductResponse>;
     listProducts?(): Promise<Array<{
         reference: string;
         name: string;
@@ -4116,13 +4143,85 @@ declare function activatePlanCore(request: Request, body: {
 
 type Plan = components['schemas']['Plan'];
 /**
- * List plans - core implementation
+ * List plans - core implementation.
+ *
+ * Pass `options.solvaPay` to route through a pre-configured SolvaPay instance
+ * (e.g. stub-backed in examples). When omitted, the helper reads
+ * `SOLVAPAY_SECRET_KEY` from environment and constructs a real API client.
  */
-declare function listPlansCore(request: Request): Promise<{
+declare function listPlansCore(request: Request, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<{
     plans: Plan[];
     productRef: string;
 } | ErrorResult>;
 
+/**
+ * Merchant Helper (Core)
+ *
+ * Generic helper for GET /api/merchant — returns the SDK-facing merchant
+ * identity used by `<MandateText>`, `<CheckoutSummary>`, and trust signals.
+ * Works with standard Web API Request (Express, Fastify, Next.js, Edge).
+ */
+
+declare function getMerchantCore(_request: Request, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<SdkMerchantResponse | ErrorResult>;
+
+/**
+ * Product Helper (Core)
+ *
+ * Generic helper for GET /api/get-product?productRef=...
+ * Returns a single product by reference, used by the `useProduct` React hook.
+ */
+
+declare function getProductCore(request: Request, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<SdkProductResponse | ErrorResult>;
+
+interface PurchaseCheckResult {
+    customerRef: string;
+    email?: string;
+    name?: string;
+    purchases: Array<{
+        reference: string;
+        productName?: string;
+        productRef?: string;
+        status?: string;
+        startDate?: string;
+        planSnapshot?: {
+            meterId?: string;
+            limit?: number;
+            freeUnits?: number;
+        };
+        usage?: {
+            used?: number;
+            overageUnits?: number;
+            overageCost?: number;
+            periodStart?: string;
+            periodEnd?: string;
+        };
+        [key: string]: unknown;
+    }>;
+}
+declare function checkPurchaseCore(request: Request, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<PurchaseCheckResult | ErrorResult>;
+
+declare function trackUsageCore(request: Request, body: {
+    actionType?: 'transaction' | 'api_call' | 'hour' | 'email' | 'storage' | 'custom';
+    units?: number;
+    productRef?: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<{
+    success: true;
+} | ErrorResult>;
+
 /**
  * SolvaPay Server SDK
  *
@@ -4178,4 +4277,4 @@ declare function verifyWebhook({ body, signature, secret, }: {
     secret: string;
 }): WebhookEvent;
 
-export { type ActivatePlanResult, type AuthenticatedUser, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type McpAdapterOptions, McpBearerAuthError, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolExtra, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableFunction, type PayableOptions, type PaywallArgs, PaywallError, type PaywallMetadata, type PaywallStructuredContent, type PaywallToolResult, type ProcessPaymentResult, type RegisterVirtualToolsMcpOptions, type RetryOptions, type ServerClientOptions, type SolvaPay, type SolvaPayClient, type ToolPlanMappingInput, VIRTUAL_TOOL_DEFINITIONS, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, buildAuthInfoFromBearer, cancelPurchaseCore, type components, createCheckoutSessionCore, createCustomerSessionCore, createMcpOAuthBridge, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, createVirtualTools, decodeJwtPayload, extractBearerToken, getAuthenticatedUserCore, getCustomerBalanceCore, getCustomerRefFromBearerAuthHeader, getCustomerRefFromJwtPayload, getOAuthAuthorizationServerResponse, getOAuthProtectedResourceResponse, handleRouteError, isErrorResult, jsonSchemaToZodRawShape, listPlansCore, paywallErrorToClientPayload, processPaymentIntentCore, reactivatePurchaseCore, registerVirtualToolsMcpImpl, syncCustomerCore, verifyWebhook, withRetry };
+export { type ActivatePlanResult, type AuthenticatedUser, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type McpAdapterOptions, McpBearerAuthError, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolExtra, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableFunction, type PayableOptions, type PaywallArgs, PaywallError, type PaywallMetadata, type PaywallStructuredContent, type PaywallToolResult, type ProcessPaymentResult, type PurchaseCheckResult, type RegisterVirtualToolsMcpOptions, type RetryOptions, type SdkMerchantResponse, type SdkProductResponse, type ServerClientOptions, type SolvaPay, type SolvaPayClient, type ToolPlanMappingInput, VIRTUAL_TOOL_DEFINITIONS, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, buildAuthInfoFromBearer, cancelPurchaseCore, checkPurchaseCore, type components, 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 };