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

package/README.md

@@ -0,0 +1,478 @@
+# @puga-labs/x402-mantle-sdk
+
+[![npm version](https://img.shields.io/npm/v/@puga-labs/x402-mantle-sdk.svg)](https://www.npmjs.com/package/@puga-labs/x402-mantle-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+SDK for x402 payments on Mantle blockchain. Protect your APIs with USDC payments using a simple middleware.
+
+## Installation
+
+```bash
+npm install @puga-labs/x402-mantle-sdk
+```
+
+## Features
+
+- React hooks (`useMantleX402`, `useEthersWallet`)
+- Vanilla JS client (`createMantleClient`)
+- Server middleware for Express, Next.js, Hono, Cloudflare Workers, Deno
+- Full TypeScript support
+- Automatic payment flow handling
+- Analytics & telemetry integration
+
+---
+
+## Client-Side Usage
+
+### React (Recommended)
+
+```tsx
+import { useMantleX402 } from '@puga-labs/x402-mantle-sdk/react';
+
+function PaymentButton() {
+  const { postWithPayment } = useMantleX402({
+    facilitatorUrl: 'https://facilitator.x402mantlesdk.xyz'
+  });
+
+  const handlePay = async () => {
+    try {
+      const { response, txHash } = await postWithPayment('/api/generate', {
+        prompt: 'Hello world'
+      });
+
+      console.log('Result:', response);
+      console.log('Transaction:', txHash);
+    } catch (error) {
+      console.error('Payment failed:', error);
+    }
+  };
+
+  return <button onClick={handlePay}>Generate ($0.01)</button>;
+}
+```
+
+### Wallet Hook
+
+Separate hook for wallet management:
+
+```tsx
+import { useEthersWallet } from '@puga-labs/x402-mantle-sdk/react';
+
+function WalletConnect() {
+  const {
+    address,
+    isConnected,
+    chainId,
+    connect,
+    disconnect,
+    error
+  } = useEthersWallet({ autoConnect: false });
+
+  if (isConnected) {
+    return (
+      <div>
+        <p>Connected: {address}</p>
+        <p>Chain ID: {chainId}</p>
+        <button onClick={disconnect}>Disconnect</button>
+      </div>
+    );
+  }
+
+  return <button onClick={connect}>Connect Wallet</button>;
+}
+```
+
+### Vanilla JavaScript
+
+```typescript
+import { createMantleClient } from '@puga-labs/x402-mantle-sdk/client';
+
+// Create client
+const client = createMantleClient({
+  facilitatorUrl: 'https://facilitator.x402mantlesdk.xyz',
+  resourceUrl: 'https://your-api.com',
+  getProvider: () => window.ethereum,
+  getAccount: () => userAddress
+});
+
+// Make paid request
+const { response, txHash } = await client.postWithPayment('/api/generate', {
+  prompt: 'Hello world'
+});
+```
+
+### Low-Level Payment Client
+
+For full control over the payment flow:
+
+```typescript
+import { createPaymentClient } from '@puga-labs/x402-mantle-sdk/client';
+
+const paymentClient = createPaymentClient({
+  resourceUrl: 'https://your-api.com',
+  facilitatorUrl: 'https://facilitator.x402mantlesdk.xyz',
+  provider: window.ethereum,
+  userAddress: '0x...' // Optional
+});
+
+const result = await paymentClient.callWithPayment('/api/endpoint', {
+  data: 'payload'
+});
+```
+
+---
+
+## Server-Side Usage
+
+### Express.js
+
+```typescript
+import express from 'express';
+import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/express';
+
+const app = express();
+app.use(express.json());
+
+// Create paywall middleware
+const pay = mantlePaywall({
+  priceUsd: 0.01,
+  payTo: '0xYourWalletAddress',
+  facilitatorUrl: 'https://facilitator.x402mantlesdk.xyz'
+});
+
+// Protected route
+app.post('/api/generate', pay, async (req, res) => {
+  const { prompt } = req.body;
+  // Your logic here - only runs after payment
+  res.json({ result: 'Generated content' });
+});
+
+// Unprotected route
+app.get('/api/health', (req, res) => {
+  res.json({ status: 'ok' });
+});
+
+app.listen(3000);
+```
+
+### Next.js (App Router)
+
+```typescript
+// app/api/generate/route.ts
+import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/nextjs';
+import { NextRequest, NextResponse } from 'next/server';
+
+const pay = mantlePaywall({
+  priceUsd: 0.01,
+  payTo: '0xYourWalletAddress',
+  facilitatorUrl: 'https://facilitator.x402mantlesdk.xyz'
+});
+
+export const POST = pay(async (req: NextRequest) => {
+  const { prompt } = await req.json();
+  // Your logic here
+  return NextResponse.json({ result: 'Generated content' });
+});
+```
+
+### Hono
+
+```typescript
+import { Hono } from 'hono';
+import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/web';
+
+const app = new Hono();
+
+const pay = mantlePaywall({
+  priceUsd: 0.01,
+  payTo: '0xYourWalletAddress',
+  facilitatorUrl: 'https://facilitator.x402mantlesdk.xyz'
+});
+
+app.post('/api/generate', pay(async (c) => {
+  const { prompt } = await c.req.json();
+  return c.json({ result: 'Generated content' });
+}));
+
+export default app;
+```
+
+### Cloudflare Workers
+
+```typescript
+import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/web';
+
+const pay = mantlePaywall({
+  priceUsd: 0.01,
+  payTo: '0xYourWalletAddress',
+  facilitatorUrl: 'https://facilitator.x402mantlesdk.xyz'
+});
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    if (request.method === 'POST') {
+      return pay(async (req) => {
+        const body = await req.json();
+        return new Response(JSON.stringify({ result: 'success' }), {
+          headers: { 'Content-Type': 'application/json' }
+        });
+      })(request);
+    }
+    return new Response('Method not allowed', { status: 405 });
+  }
+};
+```
+
+### Deno
+
+```typescript
+import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/web';
+
+const pay = mantlePaywall({
+  priceUsd: 0.01,
+  payTo: '0xYourWalletAddress',
+  facilitatorUrl: 'https://facilitator.x402mantlesdk.xyz'
+});
+
+Deno.serve(pay(async (req) => {
+  const body = await req.json();
+  return new Response(JSON.stringify({ result: 'success' }), {
+    headers: { 'Content-Type': 'application/json' }
+  });
+}));
+```
+
+---
+
+## Configuration
+
+### Client Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `facilitatorUrl` | `string` | `http://localhost:8080` | Facilitator service URL |
+| `resourceUrl` | `string` | `window.location.origin` | Your API base URL |
+| `projectKey` | `string` | - | Project key for hosted facilitator billing |
+| `getProvider` | `() => EIP1193Provider` | - | Function returning wallet provider |
+| `getAccount` | `() => string` | - | Function returning user address |
+
+### Server Options (mantlePaywall)
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `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 |
+| `network` | `string` | No | Network ID (default: `mantle-mainnet`) |
+| `onPaymentSettled` | `function` | No | Callback when payment is verified |
+| `telemetry` | `object` | No | Analytics configuration |
+
+---
+
+## Hosted vs Self-Hosted Facilitator
+
+### Hosted Facilitator (Recommended)
+
+Use our managed facilitator service:
+
+```typescript
+const pay = mantlePaywall({
+  priceUsd: 0.01,
+  payTo: '0xYourWallet',
+  facilitatorUrl: 'https://facilitator.x402mantlesdk.xyz',
+  apiKey: 'your-api-key' // Get from dashboard
+});
+```
+
+Get your API key from [Dashboard](https://x402mantlesdk.xyz/dashboard).
+
+### Self-Hosted Facilitator
+
+Run your own facilitator:
+
+```typescript
+const pay = mantlePaywall({
+  priceUsd: 0.01,
+  payTo: '0xYourWallet',
+  facilitatorUrl: 'https://your-facilitator.com'
+  // No apiKey needed for self-hosted
+});
+```
+
+Create a facilitator with:
+```bash
+npx create-mantle-facilitator my-facilitator
+```
+
+---
+
+## Analytics & Telemetry
+
+Track payments with built-in analytics:
+
+```typescript
+const pay = mantlePaywall({
+  priceUsd: 0.01,
+  payTo: '0x...',
+  facilitatorUrl: 'https://facilitator.x402mantlesdk.xyz',
+
+  // Analytics configuration
+  telemetry: {
+    projectKey: 'pk_xxx',  // Get from dashboard
+    debug: true            // Enable console logging
+  },
+
+  // Callback on each successful payment
+  onPaymentSettled: (entry) => {
+    console.log('Payment received!');
+    console.log('Amount:', entry.valueAtomic);
+    console.log('From:', entry.from);
+    console.log('To:', entry.to);
+    console.log('TxHash:', entry.txHash);
+    console.log('Route:', entry.route);
+  }
+});
+```
+
+### PaymentLogEntry Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique payment identifier (nonce) |
+| `from` | `string` | Payer's wallet address |
+| `to` | `string` | Recipient's wallet address |
+| `valueAtomic` | `string` | Amount in atomic units |
+| `network` | `string` | Network ID |
+| `asset` | `string` | Token contract address |
+| `route` | `string` | API route (e.g., `POST /api/generate`) |
+| `txHash` | `string` | Blockchain transaction hash |
+| `timestamp` | `number` | Unix timestamp (ms) |
+
+---
+
+## TypeScript Types
+
+```typescript
+import type {
+  // Shared types
+  PaymentRequirements,
+  Authorization,
+  PaymentHeaderObject,
+  NetworkId,
+
+  // Client types
+  MantleClient,
+  MantleClientConfig,
+  PaymentClient,
+  PaymentClientConfig,
+  CallWithPaymentResult,
+
+  // Server types
+  PaymentLogEntry,
+  TelemetryConfig,
+  MinimalPaywallOptions,
+
+  // React types
+  UseMantleX402Options,
+  UseEthersWalletOptions,
+  UseEthersWalletReturn
+} from '@puga-labs/x402-mantle-sdk';
+```
+
+---
+
+## Import Paths
+
+```typescript
+// Main exports (types + constants)
+import { MANTLE_DEFAULTS } from '@puga-labs/x402-mantle-sdk';
+
+// Client
+import { createMantleClient, createPaymentClient } from '@puga-labs/x402-mantle-sdk/client';
+
+// React hooks
+import { useMantleX402, useEthersWallet } from '@puga-labs/x402-mantle-sdk/react';
+
+// Server - Express
+import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/express';
+
+// Server - Next.js
+import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/nextjs';
+
+// Server - Web Standards (Hono, CF Workers, Deno)
+import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/web';
+```
+
+---
+
+## Network Configuration
+
+| Network | Chain ID | USDC Address | Decimals |
+|---------|----------|--------------|----------|
+| Mantle Mainnet | 5000 | `0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9` | 6 |
+
+### Price Conversion
+
+- `priceUsd: 0.01` = 1 cent = 10,000 atomic units
+- Formula: `atomicUnits = priceUsd * 10^6`
+
+---
+
+## Error Handling
+
+### Client-Side Errors
+
+```typescript
+try {
+  const { response, txHash } = await postWithPayment('/api/generate', data);
+} catch (error) {
+  if (error.code === 4001) {
+    // User rejected the transaction
+    console.log('User cancelled');
+  } else if (error.code === -32603) {
+    // Internal error (insufficient funds, etc.)
+    console.log('Transaction failed:', error.message);
+  } else {
+    // Network or facilitator error
+    console.log('Error:', error.message);
+  }
+}
+```
+
+### Server-Side Error Responses
+
+```typescript
+// 402 Payment Required
+{
+  "error": "Payment Required",
+  "paymentRequirements": {
+    "scheme": "exact",
+    "network": "mantle-mainnet",
+    "asset": "0x09Bc4E0D...",
+    "maxAmountRequired": "10000",
+    "payTo": "0x...",
+    "price": "$0.01",
+    "currency": "USD"
+  }
+}
+
+// 400 Invalid Payment
+{
+  "error": "Invalid payment",
+  "invalidReason": "Payment amount too low"
+}
+```
+
+---
+
+## Links
+
+- [Full Documentation](https://x402mantlesdk.xyz/docs)
+- [Dashboard](https://x402mantlesdk.xyz/dashboard)
+- [GitHub](https://github.com/puga-labs/x402-mantle-sdk)
+- [Facilitator Kit](../create-mantle-facilitator)
+
+## License
+
+MIT

package/dist/chunk-3DGAB7HD.js

@@ -0,0 +1,126 @@
+import {
+  buildRouteKey,
+  checkPayment,
+  validateAddress
+} from "./chunk-UVYA6H32.js";
+import {
+  MANTLE_DEFAULTS,
+  __export,
+  getDefaultAssetForNetwork,
+  usdCentsToAtomic
+} from "./chunk-HEZZ74SI.js";
+
+// src/server/adapters/express.ts
+var express_exports = {};
+__export(express_exports, {
+  createPaymentMiddleware: () => createPaymentMiddleware,
+  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 createPaymentMiddleware(config) {
+  const { facilitatorUrl, receiverAddress, routes, apiKey, 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,
+      apiKey,
+      routeKey,
+      network,
+      asset: assetConfig.address,
+      telemetry,
+      onPaymentSettled
+    });
+    if (!result.isValid) {
+      res.status(result.statusCode).json(result.responseBody);
+      return;
+    }
+    debugLog(telemetry, "handler", "\u25B6\uFE0F Handler execution started (Express middleware)");
+    if (result.sendTelemetryAfterResponse) {
+      res.on("finish", () => {
+        const statusCode = res.statusCode;
+        debugLog(telemetry, "handler", `\u2705 Handler completed: ${statusCode}`);
+        const errorMessage = statusCode >= 400 ? `Handler returned ${statusCode}` : void 0;
+        debugLog(telemetry, "callback", `\u{1F4E4} Calling telemetry callback with status ${statusCode}`);
+        result.sendTelemetryAfterResponse(statusCode, errorMessage);
+      });
+      res.on("close", () => {
+        if (!res.writableEnded) {
+          debugLog(telemetry, "handler", "\u274C Response closed without finishing");
+          debugLog(telemetry, "callback", "\u{1F4E4} Calling telemetry callback with error");
+          result.sendTelemetryAfterResponse(500, "Response closed without finishing");
+        }
+      });
+    } else {
+      debugLog(telemetry, "callback", "\u26A0\uFE0F No telemetry callback to call");
+    }
+    next();
+  };
+}
+function mantlePaywall(opts) {
+  const { priceUsd, payTo, facilitatorUrl, apiKey, 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
+        }
+      },
+      apiKey,
+      telemetry,
+      onPaymentSettled
+    });
+    return middleware(req, res, next);
+  };
+}
+
+export {
+  createPaymentMiddleware,
+  mantlePaywall,
+  express_exports
+};

package/dist/chunk-3YIQEQDT.js

@@ -0,0 +1,96 @@
+import {
+  buildRouteKey,
+  checkPayment,
+  validateAddress
+} from "./chunk-NWWXJFJ4.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, apiKey, telemetry, onPaymentSettled } = opts;
+  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,
+        apiKey,
+        routeKey,
+        network,
+        asset: assetConfig.address,
+        telemetry,
+        onPaymentSettled
+      });
+      if (!result.isValid) {
+        return new Response(JSON.stringify(result.responseBody), {
+          status: result.statusCode,
+          headers: {
+            "Content-Type": "application/json"
+          }
+        });
+      }
+      try {
+        debugLog(telemetry, "handler", "Handler execution started");
+        const response = await handler(request);
+        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;
+      }
+    };
+  };
+}
+
+export {
+  mantlePaywall,
+  web_standards_exports
+};