@puga-labs/x402-mantle-sdk 0.3.11 → 0.4.0

package/README.md

@@ -250,12 +250,14 @@ Deno.serve(pay(async (req) => {
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `facilitatorUrl` | `string` | `http://localhost:8080` | Facilitator service URL |
+| `facilitatorUrl` | `string` | From 402 response | Facilitator service URL (auto-detected from backend) |
 | `resourceUrl` | `string` | `window.location.origin` | Your API base URL |
-| `projectKey` | `string` | - | Project key for hosted facilitator billing |
+| `projectKey` | `string` | From 402 response | Project key (auto-detected from backend) |
 | `getProvider` | `() => EIP1193Provider` | - | Function returning wallet provider |
 | `getAccount` | `() => string` | - | Function returning user address |
 
+**Note:** Both `facilitatorUrl` and `projectKey` are automatically passed from your backend via 402 responses, so clients typically don't need to configure them.
+
 ### Server Options (mantlePaywall)
 
 | Option | Type | Required | Description |
@@ -263,10 +265,11 @@ Deno.serve(pay(async (req) => {
 | `priceUsd` | `number` | Yes | Price in USD (e.g., `0.01` for 1 cent) |
 | `payTo` | `string` | Yes | Your wallet address to receive payments |
 | `facilitatorUrl` | `string` | No | Facilitator URL (default: localhost:8080) |
-| `apiKey` | `string` | No | API key for hosted facilitator |
+| `projectKey` | `string` | No | Project key from dashboard (for hosted facilitator + analytics) |
+| `facilitatorSecret` | `string` | For self-hosted | Shared secret with your facilitator (required for self-hosted) |
 | `network` | `string` | No | Network ID (default: `mantle-mainnet`) |
 | `onPaymentSettled` | `function` | No | Callback when payment is verified |
-| `telemetry` | `object` | No | Analytics configuration |
+| `telemetry` | `object` | No | Analytics configuration (auto-uses projectKey if not set) |
 
 ---
 
@@ -281,30 +284,37 @@ const pay = mantlePaywall({
   priceUsd: 0.01,
   payTo: '0xYourWallet',
   facilitatorUrl: 'https://facilitator.x402mantlesdk.xyz',
-  apiKey: 'your-api-key' // Get from dashboard
+  projectKey: 'pk_xxx' // Get from dashboard (used for billing + analytics)
 });
 ```
 
-Get your API key from [Dashboard](https://x402mantlesdk.xyz/dashboard).
+Get your project key from [Dashboard](https://x402mantlesdk.xyz/dashboard).
+
+**Note:** `projectKey` is automatically passed to clients via 402 responses, so they don't need to configure it separately.
 
 ### Self-Hosted Facilitator
 
-Run your own facilitator:
+Run your own facilitator for full control and cost savings:
 
 ```typescript
 const pay = mantlePaywall({
   priceUsd: 0.01,
   payTo: '0xYourWallet',
-  facilitatorUrl: 'https://your-facilitator.com'
-  // No apiKey needed for self-hosted
+  facilitatorUrl: 'https://your-facilitator.com',
+  // REQUIRED: Must match FACILITATOR_SECRET in your facilitator's .env
+  facilitatorSecret: process.env.FACILITATOR_SECRET
 });
 ```
 
+The `facilitatorSecret` is **required** for self-hosted facilitators to prevent unauthorized usage of your facilitator by third parties.
+
 Create a facilitator with:
 ```bash
 npx create-mantle-facilitator my-facilitator
 ```
 
+After setup, copy `FACILITATOR_SECRET` from the generated `.env` file to your backend's environment variables.
+
 ---
 
 ## Analytics & Telemetry
@@ -316,11 +326,11 @@ const pay = mantlePaywall({
   priceUsd: 0.01,
   payTo: '0x...',
   facilitatorUrl: 'https://facilitator.x402mantlesdk.xyz',
+  projectKey: 'pk_xxx',  // Get from dashboard - used for both billing AND analytics
 
-  // Analytics configuration
+  // Optional: Advanced telemetry config
   telemetry: {
-    projectKey: 'pk_xxx',  // Get from dashboard
-    debug: true            // Enable console logging
+    debug: true  // Enable console logging (projectKey auto-derived from above)
   },
 
   // Callback on each successful payment

package/dist/chunk-2IGT3ZXX.js

@@ -0,0 +1,179 @@
+import {
+  createMantleClient
+} from "./chunk-RVPI6FMV.js";
+
+// src/client/react/useEthersWallet.ts
+import { useState, useEffect, useCallback } from "react";
+import { ethers } from "ethers";
+function useEthersWallet(options) {
+  const [address, setAddress] = useState(void 0);
+  const [isConnected, setIsConnected] = useState(false);
+  const [provider, setProvider] = useState(
+    void 0
+  );
+  const [chainId, setChainId] = useState(void 0);
+  const [error, setError] = useState(void 0);
+  const setProviderAndChain = useCallback(async () => {
+    if (typeof window === "undefined" || !window.ethereum) return;
+    const browserProvider = new ethers.BrowserProvider(
+      window.ethereum
+    );
+    setProvider(browserProvider);
+    const network = await browserProvider.getNetwork();
+    setChainId(Number(network.chainId));
+  }, []);
+  const hydrateFromPermissions = useCallback(async () => {
+    if (typeof window === "undefined" || !window.ethereum) return;
+    try {
+      const accounts = await window.ethereum.request({
+        method: "eth_accounts"
+      });
+      if (accounts && accounts.length > 0) {
+        const userAddress = accounts[0];
+        setAddress(userAddress);
+        setIsConnected(true);
+        await setProviderAndChain();
+      }
+    } catch (err) {
+      console.warn("[useEthersWallet] Failed to hydrate from permissions:", err);
+    }
+  }, [setProviderAndChain]);
+  const connect = useCallback(async () => {
+    try {
+      setError(void 0);
+      if (typeof window === "undefined" || !window.ethereum) {
+        throw new Error(
+          "No Ethereum wallet detected. Please install MetaMask or another wallet."
+        );
+      }
+      const browserProvider = new ethers.BrowserProvider(
+        window.ethereum
+      );
+      setProvider(browserProvider);
+      const accounts = await window.ethereum.request({
+        method: "eth_requestAccounts"
+      });
+      if (!accounts || accounts.length === 0) {
+        throw new Error("No accounts returned from wallet");
+      }
+      const userAddress = accounts[0];
+      setAddress(userAddress);
+      setIsConnected(true);
+      const network = await browserProvider.getNetwork();
+      setChainId(Number(network.chainId));
+    } catch (err) {
+      const errorObj = err instanceof Error ? err : new Error(String(err));
+      setError(errorObj);
+      setIsConnected(false);
+      setAddress(void 0);
+      setChainId(void 0);
+      throw errorObj;
+    }
+  }, []);
+  const disconnect = useCallback(() => {
+    setAddress(void 0);
+    setIsConnected(false);
+    setChainId(void 0);
+    setError(void 0);
+  }, []);
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.ethereum) return;
+    const ethereum = window.ethereum;
+    const handleAccountsChanged = (accounts) => {
+      const accountsArray = accounts;
+      if (!accountsArray || accountsArray.length === 0) {
+        disconnect();
+      } else {
+        setAddress(accountsArray[0]);
+        setIsConnected(true);
+        void setProviderAndChain();
+      }
+    };
+    if (ethereum.on) {
+      ethereum.on("accountsChanged", handleAccountsChanged);
+    }
+    return () => {
+      if (ethereum.removeListener) {
+        ethereum.removeListener("accountsChanged", handleAccountsChanged);
+      }
+    };
+  }, [disconnect, setProviderAndChain]);
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.ethereum) return;
+    const ethereum = window.ethereum;
+    const handleConnect = () => {
+      void hydrateFromPermissions();
+    };
+    if (ethereum.on) {
+      ethereum.on("connect", handleConnect);
+    }
+    return () => {
+      if (ethereum.removeListener) {
+        ethereum.removeListener("connect", handleConnect);
+      }
+    };
+  }, [hydrateFromPermissions]);
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.ethereum) return;
+    const ethereum = window.ethereum;
+    const handleChainChanged = (chainIdHex) => {
+      const newChainId = parseInt(chainIdHex, 16);
+      setChainId(newChainId);
+    };
+    if (ethereum.on) {
+      ethereum.on("chainChanged", handleChainChanged);
+    }
+    return () => {
+      if (ethereum.removeListener) {
+        ethereum.removeListener("chainChanged", handleChainChanged);
+      }
+    };
+  }, []);
+  useEffect(() => {
+    void hydrateFromPermissions();
+  }, [hydrateFromPermissions]);
+  useEffect(() => {
+    if (options?.autoConnect) {
+      connect().catch((err) => {
+        console.warn("[useEthersWallet] Auto-connect failed:", err);
+      });
+    }
+  }, [options?.autoConnect, connect]);
+  return {
+    address,
+    isConnected,
+    provider,
+    chainId,
+    connect,
+    disconnect,
+    error
+  };
+}
+
+// src/client/react/useMantleX402.ts
+function useMantleX402(opts) {
+  const { address, isConnected } = useEthersWallet({
+    autoConnect: opts?.autoConnect ?? false
+  });
+  const client = createMantleClient({
+    facilitatorUrl: opts?.facilitatorUrl,
+    resourceUrl: opts?.resourceUrl,
+    projectKey: opts?.projectKey,
+    getAccount: () => {
+      if (!isConnected || !address) return void 0;
+      return address;
+    },
+    getProvider: () => {
+      if (typeof window !== "undefined" && window.ethereum) {
+        return window.ethereum;
+      }
+      return void 0;
+    }
+  });
+  return client;
+}
+
+export {
+  useEthersWallet,
+  useMantleX402
+};

package/dist/chunk-4BUJR6G5.js

@@ -0,0 +1,100 @@
+import {
+  buildRouteKey,
+  checkPayment,
+  validateAddress
+} from "./chunk-HUKLI4UV.js";
+import {
+  MANTLE_DEFAULTS,
+  __export,
+  getDefaultAssetForNetwork,
+  usdCentsToAtomic
+} from "./chunk-HEZZ74SI.js";
+
+// src/server/adapters/nextjs.ts
+var nextjs_exports = {};
+__export(nextjs_exports, {
+  isPaywallErrorResponse: () => isPaywallErrorResponse,
+  mantlePaywall: () => mantlePaywall
+});
+import { NextResponse } from "next/server";
+function debugLog(config, prefix, message, data) {
+  if (config?.debug) {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    console.log(`[${timestamp}] [x402-debug:${prefix}]`, message, data || "");
+  }
+}
+function mantlePaywall(opts) {
+  const { priceUsd, payTo, facilitatorUrl, apiKey, telemetry, onPaymentSettled, facilitatorSecret } = opts;
+  validateAddress(payTo, "payTo");
+  const priceUsdCents = Math.round(priceUsd * 100);
+  return function(handler) {
+    return async (req) => {
+      const url = new URL(req.url);
+      const method = req.method;
+      const path = url.pathname;
+      const routeKey = buildRouteKey(method, path);
+      const network = MANTLE_DEFAULTS.NETWORK;
+      const assetConfig = getDefaultAssetForNetwork(network);
+      const maxAmountRequiredBigInt = usdCentsToAtomic(
+        priceUsdCents,
+        assetConfig.decimals
+      );
+      const paymentRequirements = {
+        scheme: "exact",
+        network,
+        asset: assetConfig.address,
+        maxAmountRequired: maxAmountRequiredBigInt.toString(),
+        payTo,
+        price: `$${(priceUsdCents / 100).toFixed(2)}`,
+        currency: "USD"
+      };
+      const paymentHeader = req.headers.get("X-PAYMENT") || req.headers.get("x-payment") || null;
+      const result = await checkPayment({
+        paymentHeader,
+        paymentRequirements,
+        facilitatorUrl: facilitatorUrl || MANTLE_DEFAULTS.FACILITATOR_URL,
+        apiKey,
+        routeKey,
+        network,
+        asset: assetConfig.address,
+        telemetry,
+        onPaymentSettled,
+        facilitatorSecret
+      });
+      if (!result.isValid) {
+        return NextResponse.json(result.responseBody, {
+          status: result.statusCode
+        });
+      }
+      try {
+        debugLog(telemetry, "handler", "Handler execution started");
+        const response = await handler(req);
+        debugLog(telemetry, "handler", `Handler completed: ${response.status}`);
+        if (result.sendTelemetryAfterResponse) {
+          debugLog(telemetry, "callback", `Calling telemetry callback with status ${response.status}`);
+          result.sendTelemetryAfterResponse(response.status);
+        } else {
+          debugLog(telemetry, "callback", "WARNING: No telemetry callback to call");
+        }
+        return response;
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : "Unknown error";
+        debugLog(telemetry, "handler", `ERROR: Handler error: ${errorMessage}`);
+        if (result.sendTelemetryAfterResponse) {
+          debugLog(telemetry, "callback", "Calling telemetry callback with error");
+          result.sendTelemetryAfterResponse(500, errorMessage);
+        }
+        throw err;
+      }
+    };
+  };
+}
+function isPaywallErrorResponse(response) {
+  return typeof response === "object" && response !== null && "error" in response && typeof response.error === "string";
+}
+
+export {
+  mantlePaywall,
+  isPaywallErrorResponse,
+  nextjs_exports
+};

package/dist/chunk-5WQRPHQL.js

@@ -0,0 +1,108 @@
+import {
+  buildRouteKey,
+  checkPayment,
+  validateAddress
+} from "./chunk-6IR4GUG7.js";
+import {
+  MANTLE_DEFAULTS,
+  __export,
+  getDefaultAssetForNetwork,
+  usdCentsToAtomic
+} from "./chunk-HEZZ74SI.js";
+
+// src/server/adapters/web-standards.ts
+var web_standards_exports = {};
+__export(web_standards_exports, {
+  mantlePaywall: () => mantlePaywall
+});
+function debugLog(config, prefix, message, data) {
+  if (config?.debug) {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    console.log(`[${timestamp}] [x402-debug:${prefix}]`, message, data || "");
+  }
+}
+function mantlePaywall(opts) {
+  const {
+    priceUsd,
+    payTo,
+    facilitatorUrl,
+    projectKey: inputProjectKey,
+    apiKey,
+    telemetry,
+    onPaymentSettled,
+    facilitatorSecret
+  } = opts;
+  const projectKey = inputProjectKey ?? apiKey;
+  const effectiveTelemetry = telemetry ? { ...telemetry, projectKey: telemetry.projectKey ?? projectKey ?? "" } : projectKey ? { projectKey } : void 0;
+  validateAddress(payTo, "payTo");
+  const priceUsdCents = Math.round(priceUsd * 100);
+  return function(handler) {
+    return async (request) => {
+      const url = new URL(request.url);
+      const method = request.method;
+      const path = url.pathname;
+      const routeKey = buildRouteKey(method, path);
+      const network = MANTLE_DEFAULTS.NETWORK;
+      const assetConfig = getDefaultAssetForNetwork(network);
+      const maxAmountRequiredBigInt = usdCentsToAtomic(
+        priceUsdCents,
+        assetConfig.decimals
+      );
+      const paymentRequirements = {
+        scheme: "exact",
+        network,
+        asset: assetConfig.address,
+        maxAmountRequired: maxAmountRequiredBigInt.toString(),
+        payTo,
+        price: `$${(priceUsdCents / 100).toFixed(2)}`,
+        currency: "USD"
+      };
+      const paymentHeader = request.headers.get("X-PAYMENT") || request.headers.get("x-payment") || null;
+      const result = await checkPayment({
+        paymentHeader,
+        paymentRequirements,
+        facilitatorUrl: facilitatorUrl || MANTLE_DEFAULTS.FACILITATOR_URL,
+        projectKey,
+        routeKey,
+        network,
+        asset: assetConfig.address,
+        telemetry: effectiveTelemetry,
+        onPaymentSettled,
+        facilitatorSecret
+      });
+      if (!result.isValid) {
+        return new Response(JSON.stringify(result.responseBody), {
+          status: result.statusCode,
+          headers: {
+            "Content-Type": "application/json"
+          }
+        });
+      }
+      try {
+        debugLog(effectiveTelemetry, "handler", "Handler execution started");
+        const response = await handler(request);
+        debugLog(effectiveTelemetry, "handler", `Handler completed: ${response.status}`);
+        if (result.sendTelemetryAfterResponse) {
+          debugLog(effectiveTelemetry, "callback", `Calling telemetry callback with status ${response.status}`);
+          result.sendTelemetryAfterResponse(response.status);
+        } else {
+          debugLog(effectiveTelemetry, "callback", "WARNING: No telemetry callback to call");
+        }
+        return response;
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : "Unknown error";
+        debugLog(effectiveTelemetry, "handler", `ERROR: Handler error: ${errorMessage}`);
+        if (result.sendTelemetryAfterResponse) {
+          debugLog(effectiveTelemetry, "callback", "Calling telemetry callback with error");
+          result.sendTelemetryAfterResponse(500, errorMessage);
+        }
+        throw err;
+      }
+    };
+  };
+}
+
+export {
+  mantlePaywall,
+  web_standards_exports
+};