@puga-labs/x402-mantle-sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,446 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createPaymentClient: () => createPaymentClient,
+  createPaymentMiddleware: () => createPaymentMiddleware
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/shared/constants.ts
+var MANTLE_MAINNET_NETWORK_ID = "mantle-mainnet";
+var MANTLE_MAINNET_CHAIN_ID = 5e3;
+var MANTLE_MAINNET_USDC = {
+  symbol: "USDC",
+  address: "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9",
+  decimals: 6
+};
+function getDefaultAssetForNetwork(network) {
+  switch (network) {
+    case MANTLE_MAINNET_NETWORK_ID:
+    default:
+      return MANTLE_MAINNET_USDC;
+  }
+}
+function getChainIdForNetwork(network) {
+  switch (network) {
+    case MANTLE_MAINNET_NETWORK_ID:
+    default:
+      return MANTLE_MAINNET_CHAIN_ID;
+  }
+}
+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/paymentMiddleware.ts
+function getRouteKey(req) {
+  const method = (req.method || "GET").toUpperCase();
+  const path = req.path || "/";
+  return `${method} ${path}`;
+}
+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 createPaymentMiddleware(config) {
+  const { facilitatorUrl, receiverAddress, routes, onPaymentSettled } = config;
+  if (!facilitatorUrl) {
+    throw new Error("facilitatorUrl is required");
+  }
+  if (!receiverAddress) {
+    throw new Error("receiverAddress is required");
+  }
+  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 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");
+    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(),
+            paymentRequirements
+          };
+          onPaymentSettled(logEntry);
+        } 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
+      });
+      return;
+    }
+  };
+}
+
+// src/shared/utils.ts
+function encodeJsonToBase64(value) {
+  const json = JSON.stringify(value);
+  if (typeof btoa === "function") {
+    const bytes = new TextEncoder().encode(json);
+    const binString = Array.from(
+      bytes,
+      (byte) => String.fromCodePoint(byte)
+    ).join("");
+    return btoa(binString);
+  }
+  if (typeof globalThis.Buffer !== "undefined") {
+    return globalThis.Buffer.from(json, "utf8").toString("base64");
+  }
+  throw new Error("No base64 implementation found in this environment");
+}
+function randomBytes32Hex() {
+  if (typeof crypto !== "undefined" && "getRandomValues" in crypto) {
+    const arr = new Uint8Array(32);
+    crypto.getRandomValues(arr);
+    return "0x" + Array.from(arr).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  try {
+    const nodeCrypto = require("crypto");
+    const buf = nodeCrypto.randomBytes(32);
+    return "0x" + buf.toString("hex");
+  } catch {
+    throw new Error(
+      "No cryptographically secure random number generator found. This environment does not support crypto.getRandomValues or Node.js crypto module."
+    );
+  }
+}
+
+// src/client/paymentClient.ts
+function joinUrl(base, path) {
+  const normalizedBase = base.replace(/\/+$/, "");
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return `${normalizedBase}${normalizedPath}`;
+}
+async function getUserAddressFromProvider(provider) {
+  const p = provider;
+  if (!p || typeof p.request !== "function") {
+    throw new Error("provider must implement EIP-1193 request()");
+  }
+  const accounts = await p.request({
+    method: "eth_requestAccounts"
+  });
+  if (!accounts || accounts.length === 0) {
+    throw new Error("No accounts returned from provider");
+  }
+  return accounts[0];
+}
+function buildTypedDataForAuthorization(authorization, paymentRequirements) {
+  const chainId = getChainIdForNetwork(paymentRequirements.network);
+  const verifyingContract = paymentRequirements.asset;
+  const domain = {
+    name: "USD Coin",
+    version: "2",
+    chainId,
+    verifyingContract
+  };
+  const types = {
+    TransferWithAuthorization: [
+      { name: "from", type: "address" },
+      { name: "to", type: "address" },
+      { name: "value", type: "uint256" },
+      { name: "validAfter", type: "uint256" },
+      { name: "validBefore", type: "uint256" },
+      { name: "nonce", type: "bytes32" }
+    ]
+  };
+  return {
+    domain,
+    types,
+    primaryType: "TransferWithAuthorization",
+    message: authorization
+  };
+}
+async function signAuthorizationWithProvider(provider, address, authorization, paymentRequirements) {
+  const p = provider;
+  if (!p || typeof p.request !== "function") {
+    throw new Error("provider must implement EIP-1193 request()");
+  }
+  const typedData = buildTypedDataForAuthorization(
+    authorization,
+    paymentRequirements
+  );
+  const params = [address, JSON.stringify(typedData)];
+  const signature = await p.request({
+    method: "eth_signTypedData_v4",
+    params
+  });
+  if (typeof signature !== "string" || !signature.startsWith("0x")) {
+    throw new Error("Invalid signature returned from provider");
+  }
+  return signature;
+}
+function createPaymentClient(config) {
+  const {
+    resourceUrl,
+    facilitatorUrl,
+    provider,
+    userAddress: userAddressOverride
+  } = config;
+  if (!resourceUrl) {
+    throw new Error("resourceUrl is required");
+  }
+  if (!facilitatorUrl) {
+    throw new Error("facilitatorUrl is required");
+  }
+  if (!provider) {
+    throw new Error("provider is required (e.g. window.ethereum)");
+  }
+  return {
+    async callWithPayment(path, options) {
+      const method = options?.method ?? "GET";
+      const headers = {
+        ...options?.headers ?? {}
+      };
+      let body;
+      if (options?.body !== void 0) {
+        headers["Content-Type"] = headers["Content-Type"] ?? "application/json";
+        body = JSON.stringify(options.body);
+      }
+      const initialUrl = joinUrl(resourceUrl, path);
+      const initialRes = await fetch(initialUrl, {
+        method,
+        headers,
+        body
+      });
+      if (initialRes.status !== 402) {
+        const json = await initialRes.json().catch((err) => {
+          console.error("[x402] Failed to parse initial response JSON:", err);
+          return null;
+        });
+        return {
+          response: json,
+          paymentHeader: "",
+          paymentRequirements: {
+            scheme: "exact",
+            network: "mantle-mainnet",
+            asset: "",
+            maxAmountRequired: "0",
+            payTo: ""
+          },
+          txHash: void 0
+        };
+      }
+      const bodyJson = await initialRes.json();
+      const paymentRequirements = bodyJson.paymentRequirements;
+      if (!paymentRequirements) {
+        throw new Error(
+          "402 response did not include paymentRequirements field"
+        );
+      }
+      const fromAddress = userAddressOverride ?? await getUserAddressFromProvider(provider);
+      const nowSec = Math.floor(Date.now() / 1e3);
+      const validAfter = "0";
+      const validBefore = String(nowSec + 10 * 60);
+      const nonce = randomBytes32Hex();
+      const valueAtomic = options?.valueOverrideAtomic ?? paymentRequirements.maxAmountRequired;
+      const authorization = {
+        from: fromAddress,
+        to: paymentRequirements.payTo,
+        value: valueAtomic,
+        validAfter,
+        validBefore,
+        nonce
+      };
+      const signature = await signAuthorizationWithProvider(
+        provider,
+        fromAddress,
+        authorization,
+        paymentRequirements
+      );
+      const paymentHeaderObject = {
+        x402Version: 1,
+        scheme: paymentRequirements.scheme,
+        network: paymentRequirements.network,
+        payload: {
+          signature,
+          authorization
+        }
+      };
+      const paymentHeader = encodeJsonToBase64(paymentHeaderObject);
+      const settleUrl = joinUrl(facilitatorUrl, "/settle");
+      const settleRes = await fetch(settleUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          x402Version: 1,
+          paymentHeader,
+          paymentRequirements
+        })
+      });
+      if (!settleRes.ok) {
+        const text = await settleRes.text().catch((err) => {
+          console.error("[x402] Failed to read settle response text:", err);
+          return "";
+        });
+        throw new Error(
+          `Facilitator /settle failed with HTTP ${settleRes.status}: ${text}`
+        );
+      }
+      const settleJson = await settleRes.json();
+      if (!settleJson.success) {
+        throw new Error(
+          `Facilitator /settle returned error: ${settleJson.error ?? "unknown error"}`
+        );
+      }
+      const txHash = settleJson.txHash ?? void 0;
+      const retryHeaders = {
+        ...headers,
+        "X-PAYMENT": paymentHeader
+      };
+      const retryRes = await fetch(initialUrl, {
+        method,
+        headers: retryHeaders,
+        body
+      });
+      if (!retryRes.ok) {
+        const text = await retryRes.text().catch((err) => {
+          console.error("[x402] Failed to read retry response text:", err);
+          return "";
+        });
+        throw new Error(
+          `Protected request with X-PAYMENT failed: HTTP ${retryRes.status} ${text}`
+        );
+      }
+      const finalJson = await retryRes.json();
+      return {
+        response: finalJson,
+        txHash,
+        paymentHeader,
+        paymentRequirements
+      };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createPaymentClient,
+  createPaymentMiddleware
+});

package/dist/index.d.cts

@@ -0,0 +1,129 @@
+import { Request, Response, NextFunction } from 'express';
+
+/** Network identifier used in x402 paymentRequirements / paymentHeader. */
+type NetworkId = "mantle-mainnet" | (string & {});
+/** Basic ERC-20 asset config (e.g. USDC on Mantle). */
+interface AssetConfig {
+    symbol: string;
+    address: string;
+    decimals: number;
+}
+/** x402-style payment requirements (returned in 402 response). */
+interface PaymentRequirements {
+    scheme: "exact";
+    network: NetworkId;
+    asset: string;
+    maxAmountRequired: string;
+    payTo: string;
+    price?: string;
+    currency?: string;
+}
+/** EIP-3009 TransferWithAuthorization payload. */
+interface Authorization {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}
+/** Inner payload of x402-style payment header. */
+interface PaymentHeaderPayload {
+    signature: string;
+    authorization: Authorization;
+}
+/** Structured x402-style payment header (before base64 encoding). */
+interface PaymentHeaderObject {
+    x402Version: number;
+    scheme: "exact";
+    network: NetworkId;
+    payload: PaymentHeaderPayload;
+}
+/** Base64-encoded payment header, sent in X-PAYMENT. */
+type PaymentHeaderBase64 = string;
+
+/** Unique key for a protected route, e.g. "GET /api/protected". */
+type RouteKey = string;
+/** Pricing config for a single route. */
+interface RoutePricingConfig {
+    /** Price in USD cents, e.g. 1 => $0.01. */
+    priceUsdCents: number;
+    /** Network identifier (e.g. "mantle-mainnet"). */
+    network: NetworkId;
+}
+/** Map of route keys to pricing config. */
+type RoutesConfig = Record<RouteKey, RoutePricingConfig>;
+/** Log entry for a successfully settled payment. */
+interface PaymentLogEntry {
+    id: string;
+    from: string;
+    to: string;
+    valueAtomic: string;
+    network: NetworkId;
+    asset: string;
+    route?: RouteKey;
+    txHash?: string;
+    timestamp: number;
+    paymentRequirements?: PaymentRequirements;
+}
+/** Config for createPaymentMiddleware. */
+interface PaymentMiddlewareConfig {
+    /** Base URL of facilitator, e.g. https://facilitator.nosubs.ai */
+    facilitatorUrl: string;
+    /** Recipient address (developer). */
+    receiverAddress: string;
+    /** Map of protected routes and their pricing. */
+    routes: RoutesConfig;
+    /**
+     * Optional hook called whenever a payment is successfully settled.
+     * You can use this to push logs into your DB / analytics pipeline.
+     */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
+}
+
+declare function createPaymentMiddleware(config: PaymentMiddlewareConfig): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+/** Config for the client-side payment helper. */
+interface PaymentClientConfig {
+    /** Base URL of your protected resource server. */
+    resourceUrl: string;
+    /** Facilitator URL (hosted or self-hosted). */
+    facilitatorUrl: string;
+    /** EIP-1193 provider (window.ethereum) or similar. */
+    provider: unknown;
+    /** Optional user address override; otherwise derived from provider. */
+    userAddress?: string;
+}
+/** Result of a callWithPayment() client operation. */
+interface CallWithPaymentResult<TResponseBody = unknown> {
+    response: TResponseBody;
+    txHash?: string;
+    paymentHeader: PaymentHeaderBase64;
+    paymentRequirements: PaymentRequirements;
+}
+/** Shape of the client instance returned by createPaymentClient. */
+interface PaymentClient {
+    callWithPayment<TBody = unknown, TResp = unknown>(path: string, options?: {
+        method?: "GET" | "POST" | "PUT" | "DELETE";
+        body?: TBody;
+        headers?: Record<string, string>;
+        /**
+         * Optional override if you want to send less than maxAmountRequired.
+         * In most cases you won't need this and will just pay maxAmountRequired.
+         */
+        valueOverrideAtomic?: string;
+    }): Promise<CallWithPaymentResult<TResp>>;
+}
+
+/**
+ * Creates a high-level payment client that:
+ *  - makes an initial request
+ *  - if it receives 402 + paymentRequirements, builds & signs an authorization
+ *  - calls facilitator /settle
+ *  - retries the original request with X-PAYMENT header
+ *
+ * This logic is x402-like and tailored for Mantle + USDC.
+ */
+declare function createPaymentClient(config: PaymentClientConfig): PaymentClient;
+
+export { type AssetConfig, type Authorization, type CallWithPaymentResult, type NetworkId, type PaymentClient, type PaymentClientConfig, type PaymentHeaderBase64, type PaymentHeaderObject, type PaymentHeaderPayload, type PaymentLogEntry, type PaymentMiddlewareConfig, type PaymentRequirements, type RouteKey, type RoutePricingConfig, type RoutesConfig, createPaymentClient, createPaymentMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+import { Request, Response, NextFunction } from 'express';
+
+/** Network identifier used in x402 paymentRequirements / paymentHeader. */
+type NetworkId = "mantle-mainnet" | (string & {});
+/** Basic ERC-20 asset config (e.g. USDC on Mantle). */
+interface AssetConfig {
+    symbol: string;
+    address: string;
+    decimals: number;
+}
+/** x402-style payment requirements (returned in 402 response). */
+interface PaymentRequirements {
+    scheme: "exact";
+    network: NetworkId;
+    asset: string;
+    maxAmountRequired: string;
+    payTo: string;
+    price?: string;
+    currency?: string;
+}
+/** EIP-3009 TransferWithAuthorization payload. */
+interface Authorization {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}
+/** Inner payload of x402-style payment header. */
+interface PaymentHeaderPayload {
+    signature: string;
+    authorization: Authorization;
+}
+/** Structured x402-style payment header (before base64 encoding). */
+interface PaymentHeaderObject {
+    x402Version: number;
+    scheme: "exact";
+    network: NetworkId;
+    payload: PaymentHeaderPayload;
+}
+/** Base64-encoded payment header, sent in X-PAYMENT. */
+type PaymentHeaderBase64 = string;
+
+/** Unique key for a protected route, e.g. "GET /api/protected". */
+type RouteKey = string;
+/** Pricing config for a single route. */
+interface RoutePricingConfig {
+    /** Price in USD cents, e.g. 1 => $0.01. */
+    priceUsdCents: number;
+    /** Network identifier (e.g. "mantle-mainnet"). */
+    network: NetworkId;
+}
+/** Map of route keys to pricing config. */
+type RoutesConfig = Record<RouteKey, RoutePricingConfig>;
+/** Log entry for a successfully settled payment. */
+interface PaymentLogEntry {
+    id: string;
+    from: string;
+    to: string;
+    valueAtomic: string;
+    network: NetworkId;
+    asset: string;
+    route?: RouteKey;
+    txHash?: string;
+    timestamp: number;
+    paymentRequirements?: PaymentRequirements;
+}
+/** Config for createPaymentMiddleware. */
+interface PaymentMiddlewareConfig {
+    /** Base URL of facilitator, e.g. https://facilitator.nosubs.ai */
+    facilitatorUrl: string;
+    /** Recipient address (developer). */
+    receiverAddress: string;
+    /** Map of protected routes and their pricing. */
+    routes: RoutesConfig;
+    /**
+     * Optional hook called whenever a payment is successfully settled.
+     * You can use this to push logs into your DB / analytics pipeline.
+     */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
+}
+
+declare function createPaymentMiddleware(config: PaymentMiddlewareConfig): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+/** Config for the client-side payment helper. */
+interface PaymentClientConfig {
+    /** Base URL of your protected resource server. */
+    resourceUrl: string;
+    /** Facilitator URL (hosted or self-hosted). */
+    facilitatorUrl: string;
+    /** EIP-1193 provider (window.ethereum) or similar. */
+    provider: unknown;
+    /** Optional user address override; otherwise derived from provider. */
+    userAddress?: string;
+}
+/** Result of a callWithPayment() client operation. */
+interface CallWithPaymentResult<TResponseBody = unknown> {
+    response: TResponseBody;
+    txHash?: string;
+    paymentHeader: PaymentHeaderBase64;
+    paymentRequirements: PaymentRequirements;
+}
+/** Shape of the client instance returned by createPaymentClient. */
+interface PaymentClient {
+    callWithPayment<TBody = unknown, TResp = unknown>(path: string, options?: {
+        method?: "GET" | "POST" | "PUT" | "DELETE";
+        body?: TBody;
+        headers?: Record<string, string>;
+        /**
+         * Optional override if you want to send less than maxAmountRequired.
+         * In most cases you won't need this and will just pay maxAmountRequired.
+         */
+        valueOverrideAtomic?: string;
+    }): Promise<CallWithPaymentResult<TResp>>;
+}
+
+/**
+ * Creates a high-level payment client that:
+ *  - makes an initial request
+ *  - if it receives 402 + paymentRequirements, builds & signs an authorization
+ *  - calls facilitator /settle
+ *  - retries the original request with X-PAYMENT header
+ *
+ * This logic is x402-like and tailored for Mantle + USDC.
+ */
+declare function createPaymentClient(config: PaymentClientConfig): PaymentClient;
+
+export { type AssetConfig, type Authorization, type CallWithPaymentResult, type NetworkId, type PaymentClient, type PaymentClientConfig, type PaymentHeaderBase64, type PaymentHeaderObject, type PaymentHeaderPayload, type PaymentLogEntry, type PaymentMiddlewareConfig, type PaymentRequirements, type RouteKey, type RoutePricingConfig, type RoutesConfig, createPaymentClient, createPaymentMiddleware };

package/dist/index.js

@@ -0,0 +1,425 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/shared/constants.ts
+var MANTLE_MAINNET_NETWORK_ID = "mantle-mainnet";
+var MANTLE_MAINNET_CHAIN_ID = 5e3;
+var MANTLE_MAINNET_USDC = {
+  symbol: "USDC",
+  address: "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9",
+  decimals: 6
+};
+function getDefaultAssetForNetwork(network) {
+  switch (network) {
+    case MANTLE_MAINNET_NETWORK_ID:
+    default:
+      return MANTLE_MAINNET_USDC;
+  }
+}
+function getChainIdForNetwork(network) {
+  switch (network) {
+    case MANTLE_MAINNET_NETWORK_ID:
+    default:
+      return MANTLE_MAINNET_CHAIN_ID;
+  }
+}
+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/paymentMiddleware.ts
+function getRouteKey(req) {
+  const method = (req.method || "GET").toUpperCase();
+  const path = req.path || "/";
+  return `${method} ${path}`;
+}
+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 createPaymentMiddleware(config) {
+  const { facilitatorUrl, receiverAddress, routes, onPaymentSettled } = config;
+  if (!facilitatorUrl) {
+    throw new Error("facilitatorUrl is required");
+  }
+  if (!receiverAddress) {
+    throw new Error("receiverAddress is required");
+  }
+  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 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");
+    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(),
+            paymentRequirements
+          };
+          onPaymentSettled(logEntry);
+        } 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
+      });
+      return;
+    }
+  };
+}
+
+// src/shared/utils.ts
+function encodeJsonToBase64(value) {
+  const json = JSON.stringify(value);
+  if (typeof btoa === "function") {
+    const bytes = new TextEncoder().encode(json);
+    const binString = Array.from(
+      bytes,
+      (byte) => String.fromCodePoint(byte)
+    ).join("");
+    return btoa(binString);
+  }
+  if (typeof globalThis.Buffer !== "undefined") {
+    return globalThis.Buffer.from(json, "utf8").toString("base64");
+  }
+  throw new Error("No base64 implementation found in this environment");
+}
+function randomBytes32Hex() {
+  if (typeof crypto !== "undefined" && "getRandomValues" in crypto) {
+    const arr = new Uint8Array(32);
+    crypto.getRandomValues(arr);
+    return "0x" + Array.from(arr).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  try {
+    const nodeCrypto = __require("crypto");
+    const buf = nodeCrypto.randomBytes(32);
+    return "0x" + buf.toString("hex");
+  } catch {
+    throw new Error(
+      "No cryptographically secure random number generator found. This environment does not support crypto.getRandomValues or Node.js crypto module."
+    );
+  }
+}
+
+// src/client/paymentClient.ts
+function joinUrl(base, path) {
+  const normalizedBase = base.replace(/\/+$/, "");
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return `${normalizedBase}${normalizedPath}`;
+}
+async function getUserAddressFromProvider(provider) {
+  const p = provider;
+  if (!p || typeof p.request !== "function") {
+    throw new Error("provider must implement EIP-1193 request()");
+  }
+  const accounts = await p.request({
+    method: "eth_requestAccounts"
+  });
+  if (!accounts || accounts.length === 0) {
+    throw new Error("No accounts returned from provider");
+  }
+  return accounts[0];
+}
+function buildTypedDataForAuthorization(authorization, paymentRequirements) {
+  const chainId = getChainIdForNetwork(paymentRequirements.network);
+  const verifyingContract = paymentRequirements.asset;
+  const domain = {
+    name: "USD Coin",
+    version: "2",
+    chainId,
+    verifyingContract
+  };
+  const types = {
+    TransferWithAuthorization: [
+      { name: "from", type: "address" },
+      { name: "to", type: "address" },
+      { name: "value", type: "uint256" },
+      { name: "validAfter", type: "uint256" },
+      { name: "validBefore", type: "uint256" },
+      { name: "nonce", type: "bytes32" }
+    ]
+  };
+  return {
+    domain,
+    types,
+    primaryType: "TransferWithAuthorization",
+    message: authorization
+  };
+}
+async function signAuthorizationWithProvider(provider, address, authorization, paymentRequirements) {
+  const p = provider;
+  if (!p || typeof p.request !== "function") {
+    throw new Error("provider must implement EIP-1193 request()");
+  }
+  const typedData = buildTypedDataForAuthorization(
+    authorization,
+    paymentRequirements
+  );
+  const params = [address, JSON.stringify(typedData)];
+  const signature = await p.request({
+    method: "eth_signTypedData_v4",
+    params
+  });
+  if (typeof signature !== "string" || !signature.startsWith("0x")) {
+    throw new Error("Invalid signature returned from provider");
+  }
+  return signature;
+}
+function createPaymentClient(config) {
+  const {
+    resourceUrl,
+    facilitatorUrl,
+    provider,
+    userAddress: userAddressOverride
+  } = config;
+  if (!resourceUrl) {
+    throw new Error("resourceUrl is required");
+  }
+  if (!facilitatorUrl) {
+    throw new Error("facilitatorUrl is required");
+  }
+  if (!provider) {
+    throw new Error("provider is required (e.g. window.ethereum)");
+  }
+  return {
+    async callWithPayment(path, options) {
+      const method = options?.method ?? "GET";
+      const headers = {
+        ...options?.headers ?? {}
+      };
+      let body;
+      if (options?.body !== void 0) {
+        headers["Content-Type"] = headers["Content-Type"] ?? "application/json";
+        body = JSON.stringify(options.body);
+      }
+      const initialUrl = joinUrl(resourceUrl, path);
+      const initialRes = await fetch(initialUrl, {
+        method,
+        headers,
+        body
+      });
+      if (initialRes.status !== 402) {
+        const json = await initialRes.json().catch((err) => {
+          console.error("[x402] Failed to parse initial response JSON:", err);
+          return null;
+        });
+        return {
+          response: json,
+          paymentHeader: "",
+          paymentRequirements: {
+            scheme: "exact",
+            network: "mantle-mainnet",
+            asset: "",
+            maxAmountRequired: "0",
+            payTo: ""
+          },
+          txHash: void 0
+        };
+      }
+      const bodyJson = await initialRes.json();
+      const paymentRequirements = bodyJson.paymentRequirements;
+      if (!paymentRequirements) {
+        throw new Error(
+          "402 response did not include paymentRequirements field"
+        );
+      }
+      const fromAddress = userAddressOverride ?? await getUserAddressFromProvider(provider);
+      const nowSec = Math.floor(Date.now() / 1e3);
+      const validAfter = "0";
+      const validBefore = String(nowSec + 10 * 60);
+      const nonce = randomBytes32Hex();
+      const valueAtomic = options?.valueOverrideAtomic ?? paymentRequirements.maxAmountRequired;
+      const authorization = {
+        from: fromAddress,
+        to: paymentRequirements.payTo,
+        value: valueAtomic,
+        validAfter,
+        validBefore,
+        nonce
+      };
+      const signature = await signAuthorizationWithProvider(
+        provider,
+        fromAddress,
+        authorization,
+        paymentRequirements
+      );
+      const paymentHeaderObject = {
+        x402Version: 1,
+        scheme: paymentRequirements.scheme,
+        network: paymentRequirements.network,
+        payload: {
+          signature,
+          authorization
+        }
+      };
+      const paymentHeader = encodeJsonToBase64(paymentHeaderObject);
+      const settleUrl = joinUrl(facilitatorUrl, "/settle");
+      const settleRes = await fetch(settleUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          x402Version: 1,
+          paymentHeader,
+          paymentRequirements
+        })
+      });
+      if (!settleRes.ok) {
+        const text = await settleRes.text().catch((err) => {
+          console.error("[x402] Failed to read settle response text:", err);
+          return "";
+        });
+        throw new Error(
+          `Facilitator /settle failed with HTTP ${settleRes.status}: ${text}`
+        );
+      }
+      const settleJson = await settleRes.json();
+      if (!settleJson.success) {
+        throw new Error(
+          `Facilitator /settle returned error: ${settleJson.error ?? "unknown error"}`
+        );
+      }
+      const txHash = settleJson.txHash ?? void 0;
+      const retryHeaders = {
+        ...headers,
+        "X-PAYMENT": paymentHeader
+      };
+      const retryRes = await fetch(initialUrl, {
+        method,
+        headers: retryHeaders,
+        body
+      });
+      if (!retryRes.ok) {
+        const text = await retryRes.text().catch((err) => {
+          console.error("[x402] Failed to read retry response text:", err);
+          return "";
+        });
+        throw new Error(
+          `Protected request with X-PAYMENT failed: HTTP ${retryRes.status} ${text}`
+        );
+      }
+      const finalJson = await retryRes.json();
+      return {
+        response: finalJson,
+        txHash,
+        paymentHeader,
+        paymentRequirements
+      };
+    }
+  };
+}
+export {
+  createPaymentClient,
+  createPaymentMiddleware
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@puga-labs/x402-mantle-sdk",
+  "version": "0.1.0",
+  "description": "x402 payments SDK for Mantle (USDC, gasless, facilitator-based)",
+  "license": "MIT",
+  "author": "Evgenii Pugachev <cyprus.pugamuga@gmail.com>",
+  "homepage": "https://github.com/puga-labs/mantle-x402-kit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/puga-labs/mantle-x402-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/puga-labs/mantle-x402-kit/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "clean": "rimraf dist",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:security": "vitest run tests/security",
+    "test:coverage": "vitest run --coverage",
+    "test:ui": "vitest --ui",
+    "test:watch": "vitest watch"
+  },
+  "peerDependencies": {
+    "ethers": "^6.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.20.0",
+    "@typescript-eslint/parser": "^8.20.0",
+    "@vitest/coverage-v8": "^4.0.15",
+    "@vitest/ui": "^4.0.15",
+    "eslint": "^9.17.0",
+    "express": "^5.2.1",
+    "globals": "^15.14.0",
+    "msw": "^2.12.4",
+    "rimraf": "^6.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.0.15"
+  }
+}