@puga-labs/x402-mantle-sdk 0.2.1 → 0.3.2

package/dist/react.d.cts

@@ -0,0 +1,93 @@
+import { M as MantleClient } from './createMantleClient-CO0uWPb-.cjs';
+export { a as MantleClientConfig } from './createMantleClient-CO0uWPb-.cjs';
+import { ethers } from 'ethers';
+import './types-BFUqKBBO.cjs';
+
+/**
+ * Options for useMantleX402 React hook.
+ */
+interface UseMantleX402Options {
+    /** Optional facilitator URL (auto-detects from NEXT_PUBLIC_FACILITATOR_URL). */
+    facilitatorUrl?: string;
+    /** Optional resource URL (defaults to current origin). */
+    resourceUrl?: string;
+    /** Optional project key for hosted facilitator billing. */
+    projectKey?: string;
+    /** Auto-connect to wallet on mount (default: false). */
+    autoConnect?: boolean;
+}
+/**
+ * React hook for simplified Mantle x402 payments with ethers.js integration.
+ *
+ * Automatically manages wallet connection and provides
+ * a clean API for making paid requests.
+ *
+ * Usage:
+ * ```typescript
+ * const { postWithPayment } = useMantleX402({
+ *   autoConnect: true
+ * });
+ *
+ * const data = await postWithPayment("/api/generate-image", {
+ *   prompt: "A beautiful sunset"
+ * });
+ * ```
+ *
+ * @param opts - Optional configuration (facilitatorUrl, resourceUrl, projectKey, autoConnect).
+ * @returns MantleClient instance with postWithPayment() method.
+ */
+declare function useMantleX402(opts?: UseMantleX402Options): MantleClient;
+
+/**
+ * Options for useEthersWallet hook.
+ */
+interface UseEthersWalletOptions {
+    /**
+     * Auto-connect to existing MetaMask connection on mount.
+     * @default true
+     */
+    autoConnect?: boolean;
+}
+/**
+ * Return type for useEthersWallet hook.
+ */
+interface UseEthersWalletReturn {
+    /** User's wallet address (undefined if not connected). */
+    address: string | undefined;
+    /** Whether wallet is connected. */
+    isConnected: boolean;
+    /** ethers.BrowserProvider instance (undefined if not available). */
+    provider: ethers.BrowserProvider | undefined;
+    /** Current chain ID (undefined if not connected). */
+    chainId: number | undefined;
+    /** Connect to wallet (prompts user for permission). */
+    connect: () => Promise<void>;
+    /** Disconnect from wallet (clears state). */
+    disconnect: () => void;
+    /** Error that occurred during connection or operation. */
+    error: Error | undefined;
+}
+/**
+ * React hook for managing Ethereum wallet connection using ethers.js.
+ *
+ * Works with any EIP-1193 compatible wallet provider (MetaMask, WalletConnect, etc.)
+ *
+ * Usage:
+ * ```typescript
+ * const { address, isConnected, connect, disconnect } = useEthersWallet({
+ *   autoConnect: true
+ * });
+ *
+ * if (!isConnected) {
+ *   return <button onClick={connect}>Connect Wallet</button>;
+ * }
+ *
+ * return <div>Connected: {address}</div>;
+ * ```
+ *
+ * @param options - Configuration options
+ * @returns Wallet state and methods
+ */
+declare function useEthersWallet(options?: UseEthersWalletOptions): UseEthersWalletReturn;
+
+export { MantleClient, type UseEthersWalletOptions, type UseEthersWalletReturn, type UseMantleX402Options, useEthersWallet, useMantleX402 };

package/dist/react.d.ts

@@ -0,0 +1,93 @@
+import { M as MantleClient } from './createMantleClient-CuiPsTa6.js';
+export { a as MantleClientConfig } from './createMantleClient-CuiPsTa6.js';
+import { ethers } from 'ethers';
+import './types-BFUqKBBO.js';
+
+/**
+ * Options for useMantleX402 React hook.
+ */
+interface UseMantleX402Options {
+    /** Optional facilitator URL (auto-detects from NEXT_PUBLIC_FACILITATOR_URL). */
+    facilitatorUrl?: string;
+    /** Optional resource URL (defaults to current origin). */
+    resourceUrl?: string;
+    /** Optional project key for hosted facilitator billing. */
+    projectKey?: string;
+    /** Auto-connect to wallet on mount (default: false). */
+    autoConnect?: boolean;
+}
+/**
+ * React hook for simplified Mantle x402 payments with ethers.js integration.
+ *
+ * Automatically manages wallet connection and provides
+ * a clean API for making paid requests.
+ *
+ * Usage:
+ * ```typescript
+ * const { postWithPayment } = useMantleX402({
+ *   autoConnect: true
+ * });
+ *
+ * const data = await postWithPayment("/api/generate-image", {
+ *   prompt: "A beautiful sunset"
+ * });
+ * ```
+ *
+ * @param opts - Optional configuration (facilitatorUrl, resourceUrl, projectKey, autoConnect).
+ * @returns MantleClient instance with postWithPayment() method.
+ */
+declare function useMantleX402(opts?: UseMantleX402Options): MantleClient;
+
+/**
+ * Options for useEthersWallet hook.
+ */
+interface UseEthersWalletOptions {
+    /**
+     * Auto-connect to existing MetaMask connection on mount.
+     * @default true
+     */
+    autoConnect?: boolean;
+}
+/**
+ * Return type for useEthersWallet hook.
+ */
+interface UseEthersWalletReturn {
+    /** User's wallet address (undefined if not connected). */
+    address: string | undefined;
+    /** Whether wallet is connected. */
+    isConnected: boolean;
+    /** ethers.BrowserProvider instance (undefined if not available). */
+    provider: ethers.BrowserProvider | undefined;
+    /** Current chain ID (undefined if not connected). */
+    chainId: number | undefined;
+    /** Connect to wallet (prompts user for permission). */
+    connect: () => Promise<void>;
+    /** Disconnect from wallet (clears state). */
+    disconnect: () => void;
+    /** Error that occurred during connection or operation. */
+    error: Error | undefined;
+}
+/**
+ * React hook for managing Ethereum wallet connection using ethers.js.
+ *
+ * Works with any EIP-1193 compatible wallet provider (MetaMask, WalletConnect, etc.)
+ *
+ * Usage:
+ * ```typescript
+ * const { address, isConnected, connect, disconnect } = useEthersWallet({
+ *   autoConnect: true
+ * });
+ *
+ * if (!isConnected) {
+ *   return <button onClick={connect}>Connect Wallet</button>;
+ * }
+ *
+ * return <div>Connected: {address}</div>;
+ * ```
+ *
+ * @param options - Configuration options
+ * @returns Wallet state and methods
+ */
+declare function useEthersWallet(options?: UseEthersWalletOptions): UseEthersWalletReturn;
+
+export { MantleClient, type UseEthersWalletOptions, type UseEthersWalletReturn, type UseMantleX402Options, useEthersWallet, useMantleX402 };

package/dist/react.js

@@ -0,0 +1,10 @@
+import {
+  useEthersWallet,
+  useMantleX402
+} from "./chunk-23QNUJIB.js";
+import "./chunk-E46A7I6B.js";
+import "./chunk-HEZZ74SI.js";
+export {
+  useEthersWallet,
+  useMantleX402
+};

package/dist/server-express.cjs

@@ -0,0 +1,368 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server-express.ts
+var server_express_exports = {};
+__export(server_express_exports, {
+  MANTLE_DEFAULTS: () => MANTLE_DEFAULTS,
+  createPaymentMiddleware: () => createPaymentMiddleware,
+  mantlePaywall: () => mantlePaywall
+});
+module.exports = __toCommonJS(server_express_exports);
+
+// 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/shared/constants.ts
+var MANTLE_MAINNET_NETWORK_ID = "mantle-mainnet";
+var MANTLE_MAINNET_USDC = {
+  symbol: "USDC",
+  address: "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9",
+  decimals: 6
+};
+var MANTLE_DEFAULTS = {
+  NETWORK: "mantle-mainnet",
+  CHAIN_ID: 5e3,
+  USDC_ADDRESS: "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9",
+  USDC_DECIMALS: 6,
+  CURRENCY: "USD",
+  SCHEME: "exact",
+  FACILITATOR_URL: (typeof process !== "undefined" ? process.env?.NEXT_PUBLIC_FACILITATOR_URL : void 0) || "http://localhost:8080"
+};
+function getDefaultAssetForNetwork(network) {
+  switch (network) {
+    case MANTLE_MAINNET_NETWORK_ID:
+    default:
+      return MANTLE_MAINNET_USDC;
+  }
+}
+function usdCentsToAtomic(cents, decimals) {
+  if (cents < 0) {
+    throw new Error("priceUsdCents must be non-negative");
+  }
+  if (decimals < 2) {
+    throw new Error("token decimals must be >= 2 for USD cent conversion");
+  }
+  const base = BigInt(10) ** BigInt(decimals - 2);
+  return BigInt(cents) * base;
+}
+
+// src/server/constants.ts
+var DEFAULT_TELEMETRY_ENDPOINT = void 0;
+
+// src/server/telemetry.ts
+function createTelemetryEvent(entry, config) {
+  const assetConfig = getDefaultAssetForNetwork(entry.network);
+  return {
+    event: "payment_verified",
+    ts: entry.timestamp,
+    projectKey: config.projectKey,
+    network: entry.network,
+    buyer: entry.from,
+    payTo: entry.to,
+    amountAtomic: entry.valueAtomic,
+    asset: entry.asset,
+    decimals: assetConfig.decimals,
+    nonce: entry.id,
+    route: entry.route ?? "unknown",
+    // Facilitator metadata
+    facilitatorType: "hosted",
+    // SDK always uses hosted mode
+    facilitatorUrl: entry.facilitatorUrl,
+    // From PaymentLogEntry
+    // facilitatorAddress is undefined for SDK (not available)
+    // Optional metadata
+    txHash: entry.txHash,
+    priceUsd: entry.paymentRequirements?.price
+  };
+}
+async function sendTelemetry(event, endpoint) {
+  const targetEndpoint = endpoint ?? DEFAULT_TELEMETRY_ENDPOINT;
+  if (!targetEndpoint) {
+    return;
+  }
+  try {
+    const response = await fetch(targetEndpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${event.projectKey}`
+      },
+      body: JSON.stringify(event)
+    });
+    if (!response.ok) {
+      console.warn(
+        `[x402-telemetry] Failed to send event: HTTP ${response.status}`
+      );
+    }
+  } catch (err) {
+    console.error("[x402-telemetry] Error sending telemetry:", err);
+  }
+}
+
+// src/server/core/verifyPayment.ts
+async function checkPayment(input) {
+  const {
+    paymentHeader,
+    paymentRequirements,
+    facilitatorUrl,
+    routeKey,
+    network,
+    asset,
+    telemetry,
+    onPaymentSettled
+  } = input;
+  if (!paymentHeader) {
+    return {
+      status: "require_payment",
+      statusCode: 402,
+      responseBody: {
+        error: "Payment Required",
+        paymentRequirements,
+        paymentHeader: null
+      },
+      isValid: false
+    };
+  }
+  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
+      );
+      return {
+        status: "verification_error",
+        statusCode: 500,
+        responseBody: {
+          error: "Payment verification error",
+          details: `Facilitator responded with HTTP ${verifyRes.status}`
+        },
+        isValid: false
+      };
+    }
+    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
+      };
+    }
+    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) {
+    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) {
+    throw new Error("facilitatorUrl is required");
+  }
+  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 = buildRouteKey(req.method, req.path);
+    const routeConfig = routes[routeKey];
+    if (!routeConfig) {
+      next();
+      return;
+    }
+    const { priceUsdCents, network } = routeConfig;
+    const assetConfig = getDefaultAssetForNetwork(network);
+    const maxAmountRequiredBigInt = usdCentsToAtomic(
+      priceUsdCents,
+      assetConfig.decimals
+    );
+    const paymentRequirements = {
+      scheme: "exact",
+      network,
+      asset: assetConfig.address,
+      maxAmountRequired: maxAmountRequiredBigInt.toString(),
+      payTo: receiverAddress,
+      price: `$${(priceUsdCents / 100).toFixed(2)}`,
+      currency: "USD"
+    };
+    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();
+  };
+}
+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();
+    const path = req.path || "/";
+    const routeKey = `${method} ${path}`;
+    const middleware = createPaymentMiddleware({
+      facilitatorUrl: facilitatorUrl || MANTLE_DEFAULTS.FACILITATOR_URL,
+      receiverAddress: payTo,
+      routes: {
+        [routeKey]: {
+          priceUsdCents,
+          network: MANTLE_DEFAULTS.NETWORK
+        }
+      },
+      telemetry,
+      onPaymentSettled
+    });
+    return middleware(req, res, next);
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MANTLE_DEFAULTS,
+  createPaymentMiddleware,
+  mantlePaywall
+});

package/dist/server-express.d.cts

@@ -0,0 +1,5 @@
+export { M as MantleMiddleware, P as PaymentMiddlewareConfig, c as createPaymentMiddleware, m as mantlePaywall } from './express-eQOPxfnI.cjs';
+export { M as MinimalPaywallOptions, c as PaymentCheckInput, d as PaymentCheckResult, P as PaymentLogEntry, R as RouteKey, a as RoutePricingConfig, b as RoutesConfig, T as TelemetryConfig } from './types-CrOsOHcX.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';
+import 'express';

package/dist/server-express.d.ts

@@ -0,0 +1,5 @@
+export { M as MantleMiddleware, P as PaymentMiddlewareConfig, c as createPaymentMiddleware, m as mantlePaywall } from './express-D8EwEcOL.js';
+export { M as MinimalPaywallOptions, c as PaymentCheckInput, d as PaymentCheckResult, P as PaymentLogEntry, R as RouteKey, a as RoutePricingConfig, b as RoutesConfig, T as TelemetryConfig } from './types-CqQ6OgRi.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';
+import 'express';

package/dist/server-express.js

@@ -0,0 +1,13 @@
+import {
+  createPaymentMiddleware,
+  mantlePaywall
+} from "./chunk-PPVS3X5Z.js";
+import "./chunk-U73CZU3X.js";
+import {
+  MANTLE_DEFAULTS
+} from "./chunk-HEZZ74SI.js";
+export {
+  MANTLE_DEFAULTS,
+  createPaymentMiddleware,
+  mantlePaywall
+};