@puga-labs/x402-mantle-sdk 0.3.1 → 0.3.3

package/dist/index.cjs

@@ -82,6 +82,54 @@ function usdCentsToAtomic(cents, decimals) {
   return BigInt(cents) * base;
 }
 
+// src/server/core/utils.ts
+function validateAddress(address, paramName = "address") {
+  if (!address) {
+    throw new Error(`${paramName} is required`);
+  }
+  if (typeof address !== "string") {
+    throw new Error(`${paramName} must be a string, got ${typeof address}`);
+  }
+  if (!address.startsWith("0x")) {
+    const preview = address.length > 10 ? `${address.substring(0, 10)}...` : address;
+    throw new Error(
+      `${paramName} must start with "0x", got: ${preview}`
+    );
+  }
+  if (address.length !== 42) {
+    throw new Error(
+      `${paramName} must be 42 characters (0x + 40 hex), got ${address.length} characters`
+    );
+  }
+  const hexPart = address.slice(2);
+  if (!/^[0-9a-fA-F]{40}$/.test(hexPart)) {
+    throw new Error(
+      `${paramName} must contain only hexadecimal characters (0-9, a-f, A-F) after "0x"`
+    );
+  }
+}
+function decodePaymentHeader(paymentHeaderBase64) {
+  try {
+    if (typeof Buffer !== "undefined") {
+      const json = Buffer.from(paymentHeaderBase64, "base64").toString("utf8");
+      return JSON.parse(json);
+    }
+    if (typeof atob === "function") {
+      const json = atob(paymentHeaderBase64);
+      return JSON.parse(json);
+    }
+    throw new Error("No base64 decoding available in this environment");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "Unknown error";
+    throw new Error(`Failed to decode paymentHeader: ${msg}`);
+  }
+}
+function buildRouteKey(method, path) {
+  const normalizedMethod = (method || "GET").toUpperCase();
+  const normalizedPath = path || "/";
+  return `${normalizedMethod} ${normalizedPath}`;
+}
+
 // src/server/constants.ts
 var DEFAULT_TELEMETRY_ENDPOINT = void 0;
 
@@ -135,28 +183,130 @@ async function sendTelemetry(event, endpoint) {
   }
 }
 
-// src/server/paymentMiddleware.ts
-function getRouteKey(req) {
-  const method = (req.method || "GET").toUpperCase();
-  const path = req.path || "/";
-  return `${method} ${path}`;
-}
-function decodePaymentHeader(paymentHeaderBase64) {
+// src/server/core/verifyPayment.ts
+async function checkPayment(input) {
+  const {
+    paymentHeader,
+    paymentRequirements,
+    facilitatorUrl,
+    routeKey,
+    network,
+    asset,
+    telemetry,
+    onPaymentSettled
+  } = input;
+  if (!paymentHeader || paymentHeader.trim() === "") {
+    return {
+      status: "require_payment",
+      statusCode: 402,
+      responseBody: {
+        error: "Payment Required",
+        paymentRequirements,
+        paymentHeader: null
+      },
+      isValid: false
+    };
+  }
   try {
-    if (typeof Buffer !== "undefined") {
-      const json = Buffer.from(paymentHeaderBase64, "base64").toString("utf8");
-      return JSON.parse(json);
+    const verifyUrl = `${facilitatorUrl.replace(/\/+$/, "")}/verify`;
+    const verifyRes = await fetch(verifyUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        x402Version: 1,
+        paymentHeader,
+        paymentRequirements
+      })
+    });
+    if (!verifyRes.ok) {
+      const text = await verifyRes.text().catch(() => "");
+      console.error(
+        "[x402-mantle-sdk] Facilitator /verify returned non-OK:",
+        verifyRes.status,
+        text
+      );
+      return {
+        status: "verification_error",
+        statusCode: 500,
+        responseBody: {
+          error: "Payment verification error",
+          details: `Facilitator responded with HTTP ${verifyRes.status}`
+        },
+        isValid: false
+      };
     }
-    if (typeof atob === "function") {
-      const json = atob(paymentHeaderBase64);
-      return JSON.parse(json);
+    const verifyJson = await verifyRes.json();
+    if (!verifyJson.isValid) {
+      return {
+        status: "invalid_payment",
+        statusCode: 402,
+        responseBody: {
+          error: "Payment verification failed",
+          invalidReason: verifyJson.invalidReason ?? null,
+          paymentRequirements,
+          paymentHeader: null
+        },
+        isValid: false
+      };
     }
-    throw new Error("No base64 decoding available in this environment");
+    if (onPaymentSettled) {
+      try {
+        const headerObj = decodePaymentHeader(paymentHeader);
+        const { authorization } = headerObj.payload;
+        const assetConfig = getDefaultAssetForNetwork(network);
+        const logEntry = {
+          id: authorization.nonce,
+          from: authorization.from,
+          to: authorization.to,
+          valueAtomic: authorization.value,
+          network,
+          asset,
+          route: routeKey,
+          timestamp: Date.now(),
+          facilitatorUrl,
+          paymentRequirements
+        };
+        onPaymentSettled(logEntry);
+        if (telemetry) {
+          const event = createTelemetryEvent(logEntry, telemetry);
+          sendTelemetry(event, telemetry.endpoint).catch(
+            (err) => console.error("[x402-telemetry] Async send failed:", err)
+          );
+        }
+      } catch (err) {
+        console.error(
+          "[x402-mantle-sdk] Error calling onPaymentSettled hook:",
+          err
+        );
+      }
+    }
+    return {
+      status: "verified",
+      statusCode: 200,
+      responseBody: null,
+      isValid: true
+    };
   } catch (err) {
-    const msg = err instanceof Error ? err.message : "Unknown error";
-    throw new Error(`Failed to decode paymentHeader: ${msg}`);
+    console.error(
+      "[x402-mantle-sdk] Error while calling facilitator /verify:",
+      err
+    );
+    const message = err instanceof Error ? err.message : "Unknown verification error";
+    return {
+      status: "verification_error",
+      statusCode: 500,
+      responseBody: {
+        error: "Payment verification error",
+        details: message
+      },
+      isValid: false
+    };
   }
 }
+
+// src/server/adapters/express.ts
 function createPaymentMiddleware(config) {
   const { facilitatorUrl, receiverAddress, routes, onPaymentSettled, telemetry } = config;
   if (!facilitatorUrl) {
@@ -165,11 +315,12 @@ function createPaymentMiddleware(config) {
   if (!receiverAddress) {
     throw new Error("receiverAddress is required");
   }
+  validateAddress(receiverAddress, "receiverAddress");
   if (!routes || Object.keys(routes).length === 0) {
     throw new Error("routes config must not be empty");
   }
   return async function paymentMiddleware(req, res, next) {
-    const routeKey = getRouteKey(req);
+    const routeKey = buildRouteKey(req.method, req.path);
     const routeConfig = routes[routeKey];
     if (!routeConfig) {
       next();
@@ -190,102 +341,27 @@ function createPaymentMiddleware(config) {
       price: `$${(priceUsdCents / 100).toFixed(2)}`,
       currency: "USD"
     };
-    const paymentHeader = req.header("X-PAYMENT") ?? req.header("x-payment");
-    if (!paymentHeader) {
-      res.status(402).json({
-        error: "Payment Required",
-        paymentRequirements,
-        paymentHeader: null
-      });
-      return;
-    }
-    try {
-      const verifyUrl = `${facilitatorUrl.replace(/\/+$/, "")}/verify`;
-      const verifyRes = await fetch(verifyUrl, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({
-          x402Version: 1,
-          paymentHeader,
-          paymentRequirements
-        })
-      });
-      if (!verifyRes.ok) {
-        const text = await verifyRes.text().catch(() => "");
-        console.error(
-          "[x402-mantle-sdk] Facilitator /verify returned non-OK:",
-          verifyRes.status,
-          text
-        );
-        res.status(500).json({
-          error: "Payment verification error",
-          details: `Facilitator responded with HTTP ${verifyRes.status}`
-        });
-        return;
-      }
-      const verifyJson = await verifyRes.json();
-      if (!verifyJson.isValid) {
-        res.status(402).json({
-          error: "Payment verification failed",
-          invalidReason: verifyJson.invalidReason ?? null,
-          paymentRequirements,
-          paymentHeader: null
-        });
-        return;
-      }
-      if (onPaymentSettled) {
-        try {
-          const headerObj = decodePaymentHeader(paymentHeader);
-          const { authorization } = headerObj.payload;
-          const logEntry = {
-            id: authorization.nonce,
-            from: authorization.from,
-            to: authorization.to,
-            valueAtomic: authorization.value,
-            network,
-            asset: assetConfig.address,
-            route: routeKey,
-            timestamp: Date.now(),
-            facilitatorUrl,
-            // Pass from config closure
-            paymentRequirements
-          };
-          onPaymentSettled(logEntry);
-          if (telemetry) {
-            const event = createTelemetryEvent(logEntry, telemetry);
-            sendTelemetry(event, telemetry.endpoint).catch(
-              (err) => console.error("[x402-telemetry] Async send failed:", err)
-            );
-          }
-        } catch (err) {
-          console.error(
-            "[x402-mantle-sdk] Error calling onPaymentSettled hook:",
-            err
-          );
-        }
-      }
-      next();
-      return;
-    } catch (err) {
-      console.error(
-        "[x402-mantle-sdk] Error while calling facilitator /verify:",
-        err
-      );
-      const message = err instanceof Error ? err.message : "Unknown verification error";
-      res.status(500).json({
-        error: "Payment verification error",
-        details: message
-      });
+    const paymentHeader = req.header("X-PAYMENT") || req.header("x-payment") || null;
+    const result = await checkPayment({
+      paymentHeader,
+      paymentRequirements,
+      facilitatorUrl,
+      routeKey,
+      network,
+      asset: assetConfig.address,
+      telemetry,
+      onPaymentSettled
+    });
+    if (!result.isValid) {
+      res.status(result.statusCode).json(result.responseBody);
       return;
     }
+    next();
   };
 }
-
-// src/server/mantlePaywall.ts
 function mantlePaywall(opts) {
   const { priceUsd, payTo, facilitatorUrl, telemetry, onPaymentSettled } = opts;
+  validateAddress(payTo, "payTo");
   const priceUsdCents = Math.round(priceUsd * 100);
   return async (req, res, next) => {
     const method = (req.method || "GET").toUpperCase();
@@ -658,13 +734,14 @@ function useEthersWallet(options) {
       }
     };
   }, []);
+  const shouldAutoConnect = options?.autoConnect !== false;
   (0, import_react.useEffect)(() => {
-    if (options?.autoConnect) {
+    if (shouldAutoConnect) {
       connect().catch((err) => {
         console.warn("[useEthersWallet] Auto-connect failed:", err);
       });
     }
-  }, [options?.autoConnect, connect]);
+  }, [shouldAutoConnect, connect]);
   return {
     address,
     isConnected,

package/dist/index.d.cts

@@ -1,8 +1,10 @@
-export { A as AssetConfig, a as Authorization, E as EIP1193Provider, N as NetworkId, d as PaymentHeaderBase64, c as PaymentHeaderObject, b as PaymentHeaderPayload, P as PaymentRequirements } from './types-2zqbJvcz.cjs';
-export { M as MANTLE_DEFAULTS } from './constants-DzCGK0Q3.cjs';
-export { MantleMiddleware, MinimalPaywallOptions, PaymentLogEntry, PaymentMiddlewareConfig, RouteKey, RoutePricingConfig, RoutesConfig, TelemetryConfig, TelemetryEvent, createPaymentMiddleware, mantlePaywall } from './server.cjs';
-export { C as CallWithPaymentResult, M as MantleClient, a as MantleClientConfig, b as PaymentClient, P as PaymentClientConfig, c as createMantleClient } from './createMantleClient-NN0Nitp9.cjs';
+export { A as AssetConfig, a as Authorization, E as EIP1193Provider, N as NetworkId, d as PaymentHeaderBase64, c as PaymentHeaderObject, b as PaymentHeaderPayload, P as PaymentRequirements } from './types-BFUqKBBO.cjs';
+export { M as MANTLE_DEFAULTS } from './constants-CsIL25uQ.cjs';
+export { M as MantleMiddleware, e as MinimalPaywallOptions, P as PaymentLogEntry, d as PaymentMiddlewareConfig, R as RouteKey, a as RoutePricingConfig, b as RoutesConfig, T as TelemetryConfig, c as TelemetryEvent } from './types-CoOdbZSp.cjs';
+export { c as createPaymentMiddleware, m as mantlePaywall } from './express-eQOPxfnI.cjs';
+export { C as CallWithPaymentResult, M as MantleClient, a as MantleClientConfig, b as PaymentClient, P as PaymentClientConfig, c as createMantleClient } from './createMantleClient-CO0uWPb-.cjs';
 export { createPaymentClient } from './client.cjs';
 export { UseEthersWalletOptions, UseEthersWalletReturn, UseMantleX402Options, useEthersWallet, useMantleX402 } from './react.cjs';
 import 'express';
+import './types-CrOsOHcX.cjs';
 import 'ethers';

package/dist/index.d.ts

@@ -1,8 +1,10 @@
-export { A as AssetConfig, a as Authorization, E as EIP1193Provider, N as NetworkId, d as PaymentHeaderBase64, c as PaymentHeaderObject, b as PaymentHeaderPayload, P as PaymentRequirements } from './types-2zqbJvcz.js';
-export { M as MANTLE_DEFAULTS } from './constants-CVFF0ray.js';
-export { MantleMiddleware, MinimalPaywallOptions, PaymentLogEntry, PaymentMiddlewareConfig, RouteKey, RoutePricingConfig, RoutesConfig, TelemetryConfig, TelemetryEvent, createPaymentMiddleware, mantlePaywall } from './server.js';
-export { C as CallWithPaymentResult, M as MantleClient, a as MantleClientConfig, b as PaymentClient, P as PaymentClientConfig, c as createMantleClient } from './createMantleClient-DVFkbBfS.js';
+export { A as AssetConfig, a as Authorization, E as EIP1193Provider, N as NetworkId, d as PaymentHeaderBase64, c as PaymentHeaderObject, b as PaymentHeaderPayload, P as PaymentRequirements } from './types-BFUqKBBO.js';
+export { M as MANTLE_DEFAULTS } from './constants-0ncqvV_O.js';
+export { M as MantleMiddleware, e as MinimalPaywallOptions, P as PaymentLogEntry, d as PaymentMiddlewareConfig, R as RouteKey, a as RoutePricingConfig, b as RoutesConfig, T as TelemetryConfig, c as TelemetryEvent } from './types-DTzov_EE.js';
+export { c as createPaymentMiddleware, m as mantlePaywall } from './express-D8EwEcOL.js';
+export { C as CallWithPaymentResult, M as MantleClient, a as MantleClientConfig, b as PaymentClient, P as PaymentClientConfig, c as createMantleClient } from './createMantleClient-CuiPsTa6.js';
 export { createPaymentClient } from './client.js';
 export { UseEthersWalletOptions, UseEthersWalletReturn, UseMantleX402Options, useEthersWallet, useMantleX402 } from './react.js';
 import 'express';
+import './types-CqQ6OgRi.js';
 import 'ethers';

package/dist/index.js

@@ -1,18 +1,20 @@
 import {
   useEthersWallet,
   useMantleX402
-} from "./chunk-T5DRYLNB.js";
+} from "./chunk-23QNUJIB.js";
 import {
   createMantleClient,
   createPaymentClient
-} from "./chunk-CTI5CRDY.js";
+} from "./chunk-E46A7I6B.js";
+import "./chunk-WO2MYZXT.js";
 import {
   createPaymentMiddleware,
   mantlePaywall
-} from "./chunk-Q6SPMEIW.js";
+} from "./chunk-QWQUSRLY.js";
+import "./chunk-ZLCKBFVJ.js";
 import {
   MANTLE_DEFAULTS
-} from "./chunk-XAQGMFSR.js";
+} from "./chunk-HEZZ74SI.js";
 export {
   MANTLE_DEFAULTS,
   createMantleClient,

package/dist/nextjs-Duecps0q.d.cts

@@ -0,0 +1,45 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { M as MinimalPaywallOptions } from './types-CrOsOHcX.cjs';
+
+/**
+ * Next.js App Router route handler type.
+ */
+type NextJSHandler<T = any> = (req: NextRequest) => Promise<NextResponse<T>>;
+/**
+ * Wrapper function that adds x402 payment verification to Next.js route handler.
+ */
+type NextJSPaywallWrapper = <T>(handler: NextJSHandler<T>) => NextJSHandler<T>;
+/**
+ * Create Next.js App Router middleware for x402 payment verification.
+ * Uses Mantle mainnet defaults (USDC, exact scheme, etc.).
+ *
+ * @example
+ * ```typescript
+ * // app/api/generate-image/route.ts
+ * import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/nextjs'
+ *
+ * const pay = mantlePaywall({
+ *   priceUsd: 0.01,
+ *   payTo: process.env.PAY_TO!,
+ * });
+ *
+ * export const POST = pay(async (req: NextRequest) => {
+ *   const { prompt } = await req.json();
+ *   // Your handler code here
+ *   return NextResponse.json({ success: true });
+ * });
+ * ```
+ *
+ * @param opts - Minimal configuration (price, payTo, optional facilitator/telemetry).
+ * @returns Function that wraps Next.js route handlers with payment verification.
+ */
+declare function mantlePaywall(opts: MinimalPaywallOptions): NextJSPaywallWrapper;
+
+type nextjs_NextJSHandler<T = any> = NextJSHandler<T>;
+type nextjs_NextJSPaywallWrapper = NextJSPaywallWrapper;
+declare const nextjs_mantlePaywall: typeof mantlePaywall;
+declare namespace nextjs {
+  export { type nextjs_NextJSHandler as NextJSHandler, type nextjs_NextJSPaywallWrapper as NextJSPaywallWrapper, nextjs_mantlePaywall as mantlePaywall };
+}
+
+export { type NextJSHandler as N, type NextJSPaywallWrapper as a, mantlePaywall as m, nextjs as n };

package/dist/nextjs-TFhFiQuL.d.ts

@@ -0,0 +1,45 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { M as MinimalPaywallOptions } from './types-CqQ6OgRi.js';
+
+/**
+ * Next.js App Router route handler type.
+ */
+type NextJSHandler<T = any> = (req: NextRequest) => Promise<NextResponse<T>>;
+/**
+ * Wrapper function that adds x402 payment verification to Next.js route handler.
+ */
+type NextJSPaywallWrapper = <T>(handler: NextJSHandler<T>) => NextJSHandler<T>;
+/**
+ * Create Next.js App Router middleware for x402 payment verification.
+ * Uses Mantle mainnet defaults (USDC, exact scheme, etc.).
+ *
+ * @example
+ * ```typescript
+ * // app/api/generate-image/route.ts
+ * import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/nextjs'
+ *
+ * const pay = mantlePaywall({
+ *   priceUsd: 0.01,
+ *   payTo: process.env.PAY_TO!,
+ * });
+ *
+ * export const POST = pay(async (req: NextRequest) => {
+ *   const { prompt } = await req.json();
+ *   // Your handler code here
+ *   return NextResponse.json({ success: true });
+ * });
+ * ```
+ *
+ * @param opts - Minimal configuration (price, payTo, optional facilitator/telemetry).
+ * @returns Function that wraps Next.js route handlers with payment verification.
+ */
+declare function mantlePaywall(opts: MinimalPaywallOptions): NextJSPaywallWrapper;
+
+type nextjs_NextJSHandler<T = any> = NextJSHandler<T>;
+type nextjs_NextJSPaywallWrapper = NextJSPaywallWrapper;
+declare const nextjs_mantlePaywall: typeof mantlePaywall;
+declare namespace nextjs {
+  export { type nextjs_NextJSHandler as NextJSHandler, type nextjs_NextJSPaywallWrapper as NextJSPaywallWrapper, nextjs_mantlePaywall as mantlePaywall };
+}
+
+export { type NextJSHandler as N, type NextJSPaywallWrapper as a, mantlePaywall as m, nextjs as n };

package/dist/react.cjs

@@ -121,13 +121,14 @@ function useEthersWallet(options) {
       }
     };
   }, []);
+  const shouldAutoConnect = options?.autoConnect !== false;
   (0, import_react.useEffect)(() => {
-    if (options?.autoConnect) {
+    if (shouldAutoConnect) {
       connect().catch((err) => {
         console.warn("[useEthersWallet] Auto-connect failed:", err);
       });
     }
-  }, [options?.autoConnect, connect]);
+  }, [shouldAutoConnect, connect]);
   return {
     address,
     isConnected,

package/dist/react.d.cts

@@ -1,7 +1,7 @@
-import { M as MantleClient } from './createMantleClient-NN0Nitp9.cjs';
-export { a as MantleClientConfig } from './createMantleClient-NN0Nitp9.cjs';
+import { M as MantleClient } from './createMantleClient-CO0uWPb-.cjs';
+export { a as MantleClientConfig } from './createMantleClient-CO0uWPb-.cjs';
 import { ethers } from 'ethers';
-import './types-2zqbJvcz.cjs';
+import './types-BFUqKBBO.cjs';
 
 /**
  * Options for useMantleX402 React hook.
@@ -42,7 +42,10 @@ declare function useMantleX402(opts?: UseMantleX402Options): MantleClient;
  * Options for useEthersWallet hook.
  */
 interface UseEthersWalletOptions {
-    /** Auto-connect to wallet on mount (default: false). */
+    /**
+     * Auto-connect to existing MetaMask connection on mount.
+     * @default true
+     */
     autoConnect?: boolean;
 }
 /**

package/dist/react.d.ts

@@ -1,7 +1,7 @@
-import { M as MantleClient } from './createMantleClient-DVFkbBfS.js';
-export { a as MantleClientConfig } from './createMantleClient-DVFkbBfS.js';
+import { M as MantleClient } from './createMantleClient-CuiPsTa6.js';
+export { a as MantleClientConfig } from './createMantleClient-CuiPsTa6.js';
 import { ethers } from 'ethers';
-import './types-2zqbJvcz.js';
+import './types-BFUqKBBO.js';
 
 /**
  * Options for useMantleX402 React hook.
@@ -42,7 +42,10 @@ declare function useMantleX402(opts?: UseMantleX402Options): MantleClient;
  * Options for useEthersWallet hook.
  */
 interface UseEthersWalletOptions {
-    /** Auto-connect to wallet on mount (default: false). */
+    /**
+     * Auto-connect to existing MetaMask connection on mount.
+     * @default true
+     */
     autoConnect?: boolean;
 }
 /**

package/dist/react.js

@@ -1,9 +1,9 @@
 import {
   useEthersWallet,
   useMantleX402
-} from "./chunk-T5DRYLNB.js";
-import "./chunk-CTI5CRDY.js";
-import "./chunk-XAQGMFSR.js";
+} from "./chunk-23QNUJIB.js";
+import "./chunk-E46A7I6B.js";
+import "./chunk-HEZZ74SI.js";
 export {
   useEthersWallet,
   useMantleX402