x402-core-mantle 2.1.1-mantle

package/README.md

@@ -0,0 +1,293 @@
+# @x402/core
+
+Core implementation of the x402 payment protocol for TypeScript/JavaScript applications. Provides transport-agnostic client, server and facilitator components.
+
+## Installation
+
+```bash
+pnpm install @x402/core
+```
+
+## Quick Start
+
+### Client Usage
+
+```typescript
+import { x402Client } from '@x402/core/client';
+import { x402HTTPClient } from '@x402/core/http';
+import { ExactEvmScheme } from '@x402/evm/exact/client';
+
+// Create core client and register payment schemes
+const coreClient = new x402Client()
+  .register('eip155:*', new ExactEvmScheme(evmSigner));
+
+// Wrap with HTTP client for header encoding/decoding
+const client = new x402HTTPClient(coreClient);
+
+// Make a request
+const response = await fetch('https://api.example.com/protected');
+
+if (response.status === 402) {
+  // Extract payment requirements from response
+  const paymentRequired = client.getPaymentRequiredResponse(
+    (name) => response.headers.get(name),
+    await response.json()
+  );
+  
+  // Create and send payment
+  const paymentPayload = await client.createPaymentPayload(paymentRequired);
+  
+  const paidResponse = await fetch('https://api.example.com/protected', {
+    headers: client.encodePaymentSignatureHeader(paymentPayload),
+  });
+  
+  // Get settlement confirmation
+  const settlement = client.getPaymentSettleResponse(
+    (name) => paidResponse.headers.get(name)
+  );
+  console.log('Transaction:', settlement.transaction);
+}
+```
+
+### Server Usage
+
+```typescript
+import { x402ResourceServer, HTTPFacilitatorClient } from '@x402/core/server';
+import { x402HTTPResourceServer } from '@x402/core/http';
+import { ExactEvmScheme } from '@x402/evm/exact/server';
+
+// Connect to facilitator
+const facilitatorClient = new HTTPFacilitatorClient({
+  url: 'https://x402.org/facilitator',
+});
+
+// Create resource server with payment schemes
+const resourceServer = new x402ResourceServer(facilitatorClient)
+  .register('eip155:*', new ExactEvmScheme());
+
+// Initialize (fetches supported kinds from facilitator)
+await resourceServer.initialize();
+
+// Configure routes with payment requirements
+const routes = {
+  'GET /api/data': {
+    accepts: {
+      scheme: 'exact',
+      network: 'eip155:8453',
+      payTo: '0xYourAddress',
+      price: '$0.01',
+    },
+    description: 'Premium data access',
+    mimeType: 'application/json',
+  },
+};
+
+// Create HTTP server wrapper
+const httpServer = new x402HTTPResourceServer(resourceServer, routes);
+```
+
+### Facilitator Usage
+
+```typescript
+import { x402Facilitator } from '@x402/core/facilitator';
+import { registerExactEvmScheme } from '@x402/evm/exact/facilitator';
+
+const facilitator = new x402Facilitator();
+
+// Register scheme implementations using helper
+registerExactEvmScheme(facilitator, {
+  signer: evmSigner,
+  networks: 'eip155:84532',
+});
+
+// Verify payment
+const verifyResult = await facilitator.verify(paymentPayload, paymentRequirements);
+
+if (verifyResult.isValid) {
+  // Settle payment
+  const settleResult = await facilitator.settle(paymentPayload, paymentRequirements);
+  console.log('Transaction:', settleResult.transaction);
+}
+```
+
+## Route Configuration
+
+Routes use the `accepts` field to define payment options:
+
+```typescript
+const routes = {
+  // Single payment option
+  'GET /api/data': {
+    accepts: {
+      scheme: 'exact',
+      network: 'eip155:8453',
+      payTo: '0xAddress',
+      price: '$0.01',
+    },
+    description: 'Data endpoint',
+    mimeType: 'application/json',
+  },
+  
+  // Multiple payment options (EVM + SVM)
+  'POST /api/*': {
+    accepts: [
+      {
+        scheme: 'exact',
+        network: 'eip155:8453',
+        payTo: evmAddress,
+        price: '$0.05',
+      },
+      {
+        scheme: 'exact',
+        network: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+        payTo: svmAddress,
+        price: '$0.05',
+      },
+    ],
+  },
+};
+```
+
+## Client Configuration
+
+Use `fromConfig()` for declarative setup:
+
+```typescript
+const client = x402Client.fromConfig({
+  schemes: [
+    { network: 'eip155:8453', client: new ExactEvmScheme(evmSigner) },
+    { network: 'solana:mainnet', client: new ExactSvmScheme(svmSigner) },
+  ],
+  policies: [
+    // Filter by max price
+    (version, reqs) => reqs.filter(r => BigInt(r.amount) < BigInt('1000000')),
+  ],
+});
+```
+
+## Lifecycle Hooks
+
+### Client Hooks
+
+```typescript
+client
+  .onBeforePaymentCreation(async (ctx) => {
+    console.log('Creating payment for:', ctx.selectedRequirements.network);
+    // Return { abort: true, reason: '...' } to cancel
+  })
+  .onAfterPaymentCreation(async (ctx) => {
+    console.log('Payment created:', ctx.paymentPayload);
+  })
+  .onPaymentCreationFailure(async (ctx) => {
+    console.error('Payment failed:', ctx.error);
+    // Return { recovered: true, payload: ... } to recover
+  });
+```
+
+### Server Hooks
+
+```typescript
+resourceServer
+  .onBeforeVerify(async (ctx) => { /* ... */ })
+  .onAfterVerify(async (ctx) => { /* ... */ })
+  .onBeforeSettle(async (ctx) => { /* ... */ })
+  .onAfterSettle(async (ctx) => { /* ... */ });
+```
+
+### Facilitator Hooks
+
+```typescript
+facilitator
+  .onBeforeVerify(async (ctx) => { console.log('Before verify', ctx); })
+  .onAfterVerify(async (ctx) => { console.log('After verify', ctx); })
+  .onVerifyFailure(async (ctx) => { console.log('Verify failure', ctx); })
+  .onBeforeSettle(async (ctx) => { console.log('Before settle', ctx); })
+  .onAfterSettle(async (ctx) => { console.log('After settle', ctx); })
+  .onSettleFailure(async (ctx) => { console.log('Settle failure', ctx); });
+```
+
+## HTTP Headers
+
+### v2 Protocol (Current)
+
+| Header | Description |
+|--------|-------------|
+| `PAYMENT-SIGNATURE` | Base64-encoded payment payload |
+| `PAYMENT-REQUIRED` | Base64-encoded payment requirements |
+| `PAYMENT-RESPONSE` | Base64-encoded settlement response |
+
+### v1 Protocol (Legacy)
+
+| Header | Description |
+|--------|-------------|
+| `X-PAYMENT` | Base64-encoded payment payload |
+| `X-PAYMENT-RESPONSE` | Base64-encoded settlement response |
+
+## Network Pattern Matching
+
+Register handlers for network families using wildcards:
+
+```typescript
+// All EVM networks
+server.register('eip155:*', new ExactEvmScheme());
+
+// Specific network takes precedence
+server.register('eip155:8453', new ExactEvmScheme());
+```
+
+## Types
+
+```typescript
+type Network = `${string}:${string}`; // e.g., "eip155:8453"
+
+type PaymentRequirements = {
+  scheme: string;
+  network: Network;
+  asset: string;
+  amount: string;
+  payTo: string;
+  maxTimeoutSeconds: number;
+  extra: Record<string, unknown>;
+};
+
+type PaymentPayload = {
+  x402Version: number;
+  resource: ResourceInfo;
+  accepted: PaymentRequirements;
+  payload: Record<string, unknown>;
+  extensions?: Record<string, unknown>;
+};
+
+type PaymentRequired = {
+  x402Version: number;
+  error?: string;
+  resource: ResourceInfo;
+  accepts: PaymentRequirements[];
+  extensions?: Record<string, unknown>;
+};
+```
+
+## Framework Integration
+
+For framework-specific middleware, use:
+
+- `@x402/express` - Express.js middleware
+- `@x402/hono` - Hono middleware  
+- `@x402/next` - Next.js integration
+- `@x402/axios` - Axios interceptor
+- `@x402/fetch` - Fetch wrapper
+
+## Implementation Packages
+
+For blockchain-specific implementations:
+
+- `@x402/evm` - Ethereum and EVM-compatible chains
+- `@x402/svm` - Solana blockchain
+
+## Examples
+
+See the [examples directory](https://github.com/coinbase/x402/tree/main/examples/typescript) for complete examples.
+
+## Contributing
+
+Contributions welcome! See [Contributing Guide](https://github.com/coinbase/x402/blob/main/CONTRIBUTING.md).

package/dist/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 };