x402-express-mantle 1.0.0

package/README.md

@@ -0,0 +1,155 @@
+# x402-express-mantle
+
+Complete x402 Express middleware SDK with built-in Mantle testnet support and USDC Token configurations.
+
+## Features
+
+- ✅ **Bundled SDK**: No external dependencies on @x402 packages
+- ✅ **Mantle Testnet Ready**: Pre-configured for `eip155:5003` with USDC Token support
+- ✅ **EIP-712 Compatible**: Uses "USDC Token" name and version "1" for Mantle contracts
+- ✅ **Express Integration**: Seamless Express.js middleware
+- ✅ **Zero Configuration**: Works out-of-the-box for Mantle development
+- ✅ **TypeScript Support**: Full type definitions included
+
+## Installation
+
+```bash
+npm install x402-express-mantle
+```
+
+## Quick Start
+
+```javascript
+import express from 'express';
+import { paymentMiddlewareFromConfig } from 'x402-express-mantle';
+import { ExactEvmScheme } from 'x402-express-mantle';
+import { HTTPFacilitatorClient } from 'x402-express-mantle';
+
+const app = express();
+
+// Connect to your Mantle facilitator
+const facilitatorClient = new HTTPFacilitatorClient({ 
+  url: 'https://your-mantle-facilitator.com' 
+});
+
+// Routes with automatic Mantle payment processing
+const routes = {
+  'GET /premium-data': {
+    accepts: [{
+      scheme: 'exact',
+      price: '$0.001',
+      network: 'eip155:5003', // Mantle testnet (pre-configured)
+      payTo: '0xYourMantleWalletAddress'
+    }],
+    description: 'Premium data access'
+  }
+};
+
+// Configure payment schemes (Mantle support built-in)
+const schemes = [{
+  network: 'eip155:5003', // Mantle testnet
+  server: new ExactEvmScheme()
+}];
+
+// Add payment middleware
+app.use(paymentMiddlewareFromConfig(
+  routes,
+  facilitatorClient,
+  schemes
+));
+
+// Your protected route
+app.get('/premium-data', (req, res) => {
+  res.json({
+    data: 'Premium Mantle content!',
+    network: 'Mantle Testnet'
+  });
+});
+
+app.listen(3000);
+```
+
+## Mantle Testnet Configuration
+
+This SDK includes pre-built configurations for Mantle testnet:
+
+- **Network**: `eip155:5003`
+- **USDC Contract**: `0x3D884Eca2a1E65A41Cd54b1CF55537dAe35d7BDC`
+- **Token Name**: `USDC Token` (EIP-712 domain name)
+- **Version**: `1` (EIP-712 domain version)
+- **RPC**: Uses official Mantle testnet endpoints
+
+## API Reference
+
+### `paymentMiddleware(routes, server, paywallConfig?, paywall?, syncFacilitatorOnStart?)`
+
+Direct middleware function using a pre-configured server instance.
+
+### `paymentMiddlewareFromConfig(routes, facilitatorClients?, schemes?, paywallConfig?, paywall?, syncFacilitatorOnStart?)`
+
+Configuration-based middleware that creates the server internally.
+
+### Core Classes
+- `x402ResourceServer` - Resource server for advanced configurations
+- `x402HTTPResourceServer` - HTTP resource server
+- `HTTPFacilitatorClient` - Client for connecting to facilitators
+- `ExactEvmScheme` - EVM payment scheme (Mantle-compatible)
+
+## Environment Variables
+
+```bash
+# Your facilitator URL (required)
+FACILITATOR_URL=https://your-facilitator.com
+
+# Wallet address for receiving payments (required for routes)
+EVM_ADDRESS=0xYourMantleWalletAddress
+```
+
+## Supported Networks
+
+- **Mantle Testnet** (`eip155:5003`) - Primary support with full configurations
+- **Other EVM Networks** - Via standard x402 mechanisms
+- **Solana Networks** - Via standard x402 mechanisms
+
+## Examples
+
+Check the `examples/` directory for complete working examples:
+
+```bash
+cd node_modules/x402-express-mantle/examples
+npm install
+npm start
+```
+
+## Built-in Mantle Features
+
+This SDK includes custom Mantle configurations:
+
+1. **USDC Token Support**: Pre-configured with correct contract address and EIP-712 parameters
+2. **Network Definitions**: Mantle testnet properly defined with chain ID 5003
+3. **RPC Endpoints**: Official Mantle testnet RPC configurations
+4. **Scheme Support**: EVM exact scheme configured for Mantle
+
+## Deployment
+
+### Vercel
+
+```bash
+npm install x402-express-mantle
+# Deploy to Vercel with your environment variables
+```
+
+### Other Platforms
+
+Works with any Node.js platform supporting Express.js.
+
+## Why This Package?
+
+- **No External Dependencies**: Bundled with all x402 functionality
+- **Mantle Optimized**: Custom configurations for Mantle ecosystem
+- **Developer Friendly**: Zero configuration for Mantle development
+- **Production Ready**: Includes all necessary type definitions and examples
+
+## License
+
+Apache-2.0

package/lib/cjs/client/index.d.ts

@@ -0,0 +1,243 @@
+import { c as PaymentRequired, a as PaymentRequirements, P as PaymentPayload, N as Network, d as SchemeNetworkClient, S as SettleResponse } from '../mechanisms-CzuGzYsS.js';
+
+/**
+ * Client Hook Context Interfaces
+ */
+interface PaymentCreationContext {
+    paymentRequired: PaymentRequired;
+    selectedRequirements: PaymentRequirements;
+}
+interface PaymentCreatedContext extends PaymentCreationContext {
+    paymentPayload: PaymentPayload;
+}
+interface PaymentCreationFailureContext extends PaymentCreationContext {
+    error: Error;
+}
+/**
+ * Client Hook Type Definitions
+ */
+type BeforePaymentCreationHook = (context: PaymentCreationContext) => Promise<void | {
+    abort: true;
+    reason: string;
+}>;
+type AfterPaymentCreationHook = (context: PaymentCreatedContext) => Promise<void>;
+type OnPaymentCreationFailureHook = (context: PaymentCreationFailureContext) => Promise<void | {
+    recovered: true;
+    payload: PaymentPayload;
+}>;
+type SelectPaymentRequirements = (x402Version: number, paymentRequirements: PaymentRequirements[]) => PaymentRequirements;
+/**
+ * A policy function that filters or transforms payment requirements.
+ * Policies are applied in order before the selector chooses the final option.
+ *
+ * @param x402Version - The x402 protocol version
+ * @param paymentRequirements - Array of payment requirements to filter/transform
+ * @returns Filtered array of payment requirements
+ */
+type PaymentPolicy = (x402Version: number, paymentRequirements: PaymentRequirements[]) => PaymentRequirements[];
+/**
+ * Configuration for registering a payment scheme with a specific network
+ */
+interface SchemeRegistration {
+    /**
+     * The network identifier (e.g., 'eip155:8453', 'solana:mainnet')
+     */
+    network: Network;
+    /**
+     * The scheme client implementation for this network
+     */
+    client: SchemeNetworkClient;
+    /**
+     * The x402 protocol version to use for this scheme
+     *
+     * @default 2
+     */
+    x402Version?: number;
+}
+/**
+ * Configuration options for the fetch wrapper
+ */
+interface x402ClientConfig {
+    /**
+     * Array of scheme registrations defining which payment methods are supported
+     */
+    schemes: SchemeRegistration[];
+    /**
+     * Policies to apply to the client
+     */
+    policies?: PaymentPolicy[];
+    /**
+     * Custom payment requirements selector function
+     * If not provided, uses the default selector (first available option)
+     */
+    paymentRequirementsSelector?: SelectPaymentRequirements;
+}
+/**
+ * Core client for managing x402 payment schemes and creating payment payloads.
+ *
+ * Handles registration of payment schemes, policy-based filtering of payment requirements,
+ * and creation of payment payloads based on server requirements.
+ */
+declare class x402Client {
+    private readonly paymentRequirementsSelector;
+    private readonly registeredClientSchemes;
+    private readonly policies;
+    private beforePaymentCreationHooks;
+    private afterPaymentCreationHooks;
+    private onPaymentCreationFailureHooks;
+    /**
+     * Creates a new x402Client instance.
+     *
+     * @param paymentRequirementsSelector - Function to select payment requirements from available options
+     */
+    constructor(paymentRequirementsSelector?: SelectPaymentRequirements);
+    /**
+     * Creates a new x402Client instance from a configuration object.
+     *
+     * @param config - The client configuration including schemes, policies, and payment requirements selector
+     * @returns A configured x402Client instance
+     */
+    static fromConfig(config: x402ClientConfig): x402Client;
+    /**
+     * Registers a scheme client for the current x402 version.
+     *
+     * @param network - The network to register the client for
+     * @param client - The scheme network client to register
+     * @returns The x402Client instance for chaining
+     */
+    register(network: Network, client: SchemeNetworkClient): x402Client;
+    /**
+     * Registers a scheme client for x402 version 1.
+     *
+     * @param network - The v1 network identifier (e.g., 'base-sepolia', 'solana-devnet')
+     * @param client - The scheme network client to register
+     * @returns The x402Client instance for chaining
+     */
+    registerV1(network: string, client: SchemeNetworkClient): x402Client;
+    /**
+     * Registers a policy to filter or transform payment requirements.
+     *
+     * Policies are applied in order after filtering by registered schemes
+     * and before the selector chooses the final payment requirement.
+     *
+     * @param policy - Function to filter/transform payment requirements
+     * @returns The x402Client instance for chaining
+     *
+     * @example
+     * ```typescript
+     * // Prefer cheaper options
+     * client.registerPolicy((version, reqs) =>
+     *   reqs.filter(r => BigInt(r.value) < BigInt('1000000'))
+     * );
+     *
+     * // Prefer specific networks
+     * client.registerPolicy((version, reqs) =>
+     *   reqs.filter(r => r.network.startsWith('eip155:'))
+     * );
+     * ```
+     */
+    registerPolicy(policy: PaymentPolicy): x402Client;
+    /**
+     * Register a hook to execute before payment payload creation.
+     * Can abort creation by returning { abort: true, reason: string }
+     *
+     * @param hook - The hook function to register
+     * @returns The x402Client instance for chaining
+     */
+    onBeforePaymentCreation(hook: BeforePaymentCreationHook): x402Client;
+    /**
+     * Register a hook to execute after successful payment payload creation.
+     *
+     * @param hook - The hook function to register
+     * @returns The x402Client instance for chaining
+     */
+    onAfterPaymentCreation(hook: AfterPaymentCreationHook): x402Client;
+    /**
+     * Register a hook to execute when payment payload creation fails.
+     * Can recover from failure by returning { recovered: true, payload: PaymentPayload }
+     *
+     * @param hook - The hook function to register
+     * @returns The x402Client instance for chaining
+     */
+    onPaymentCreationFailure(hook: OnPaymentCreationFailureHook): x402Client;
+    /**
+     * Creates a payment payload based on a PaymentRequired response.
+     *
+     * Automatically extracts x402Version, resource, and extensions from the PaymentRequired
+     * response and constructs a complete PaymentPayload with the accepted requirements.
+     *
+     * @param paymentRequired - The PaymentRequired response from the server
+     * @returns Promise resolving to the complete payment payload
+     */
+    createPaymentPayload(paymentRequired: PaymentRequired): Promise<PaymentPayload>;
+    /**
+     * Selects appropriate payment requirements based on registered clients and policies.
+     *
+     * Selection process:
+     * 1. Filter by registered schemes (network + scheme support)
+     * 2. Apply all registered policies in order
+     * 3. Use selector to choose final requirement
+     *
+     * @param x402Version - The x402 protocol version
+     * @param paymentRequirements - Array of available payment requirements
+     * @returns The selected payment requirements
+     */
+    private selectPaymentRequirements;
+    /**
+     * Internal method to register a scheme client.
+     *
+     * @param x402Version - The x402 protocol version
+     * @param network - The network to register the client for
+     * @param client - The scheme network client to register
+     * @returns The x402Client instance for chaining
+     */
+    private _registerScheme;
+}
+
+/**
+ * HTTP-specific client for handling x402 payment protocol over HTTP.
+ *
+ * Wraps a x402Client to provide HTTP-specific encoding/decoding functionality
+ * for payment headers and responses while maintaining the builder pattern.
+ */
+declare class x402HTTPClient {
+    private readonly client;
+    /**
+     * Creates a new x402HTTPClient instance.
+     *
+     * @param client - The underlying x402Client for payment logic
+     */
+    constructor(client: x402Client);
+    /**
+     * Encodes a payment payload into appropriate HTTP headers based on version.
+     *
+     * @param paymentPayload - The payment payload to encode
+     * @returns HTTP headers containing the encoded payment signature
+     */
+    encodePaymentSignatureHeader(paymentPayload: PaymentPayload): Record<string, string>;
+    /**
+     * Extracts payment required information from HTTP response.
+     *
+     * @param getHeader - Function to retrieve header value by name (case-insensitive)
+     * @param body - Optional response body for v1 compatibility
+     * @returns The payment required object
+     */
+    getPaymentRequiredResponse(getHeader: (name: string) => string | null | undefined, body?: unknown): PaymentRequired;
+    /**
+     * Extracts payment settlement response from HTTP headers.
+     *
+     * @param getHeader - Function to retrieve header value by name (case-insensitive)
+     * @returns The settlement response object
+     */
+    getPaymentSettleResponse(getHeader: (name: string) => string | null | undefined): SettleResponse;
+    /**
+     * Creates a payment payload for the given payment requirements.
+     * Delegates to the underlying x402Client.
+     *
+     * @param paymentRequired - The payment required response from the server
+     * @returns Promise resolving to the payment payload
+     */
+    createPaymentPayload(paymentRequired: PaymentRequired): Promise<PaymentPayload>;
+}
+
+export { type AfterPaymentCreationHook, type BeforePaymentCreationHook, type OnPaymentCreationFailureHook, type PaymentCreatedContext, type PaymentCreationContext, type PaymentCreationFailureContext, type PaymentPolicy, type SchemeRegistration, type SelectPaymentRequirements, x402Client, type x402ClientConfig, x402HTTPClient };