@bankofai/x402-core 1.0.0-beta.0

package/README.md

@@ -0,0 +1,294 @@
+# `@bankofai/x402-core` • [![npm version](https://img.shields.io/npm/v/%40bankofai%2Fx402-core.svg)](https://www.npmjs.com/package/@bankofai/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 @bankofai/x402-core
+```
+
+## Quick Start
+
+### Client Usage
+
+```typescript
+import { x402Client } from '@bankofai/x402-core/client';
+import { x402HTTPClient } from '@bankofai/x402-core/http';
+import { ExactEvmScheme } from '@bankofai/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 '@bankofai/x402-core/server';
+import { x402HTTPResourceServer } from '@bankofai/x402-core/http';
+import { ExactEvmScheme } from '@bankofai/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 '@bankofai/x402-core/facilitator';
+import { registerExactEvmScheme } from '@bankofai/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:
+
+- `@bankofai/x402-express` - Express.js middleware
+- `@bankofai/x402-hono` - Hono middleware  
+- `@bankofai/x402-next` - Next.js integration
+- `@bankofai/x402-axios` - Axios interceptor
+- `@bankofai/x402-fetch` - Fetch wrapper
+
+## Implementation Packages
+
+For blockchain-specific implementations:
+
+- `@bankofai/x402-evm` - Ethereum and EVM-compatible chains
+- `@bankofai/x402-svm` - Solana blockchain
+- `@bankofai/x402-avm` - Algorand blockchain
+
+## Examples
+
+See the [examples directory](https://github.com/x402-foundation/x402/tree/main/examples/typescript) for complete examples.
+
+## Contributing
+
+Contributions welcome! See [Contributing Guide](https://github.com/x402-foundation/x402/blob/main/CONTRIBUTING.md).

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

@@ -0,0 +1,149 @@
+import { c as PaymentRequired, ae as x402Client, P as PaymentPayload, S as SettleResponse } from '../x402Client-TQHctrG7.js';
+export { aj as AfterPaymentCreationHook, ai as BeforePaymentCreationHook, aq as ClientExtension, ao as ClientExtensionHooks, ap as ClientTransportExtensionHooks, ak as OnPaymentCreationFailureHook, am as OnPaymentResponseHook, ag as PaymentCreatedContext, af as PaymentCreationContext, ah as PaymentCreationFailureContext, ar as PaymentPolicy, al as PaymentResponseContext, as as SchemeRegistration, an as SelectPaymentRequirements, at as x402ClientConfig } from '../x402Client-TQHctrG7.js';
+
+/**
+ * Context provided to onPaymentRequired hooks.
+ */
+interface PaymentRequiredContext {
+    paymentRequired: PaymentRequired;
+}
+/**
+ * Hook called when a 402 response is received, before payment processing.
+ * Return headers to try before payment, or void to proceed directly to payment.
+ */
+type PaymentRequiredHook = (context: PaymentRequiredContext) => Promise<{
+    headers: Record<string, string>;
+} | void>;
+interface HTTPClientExtensionHooks {
+    onPaymentRequired?: (declaration: unknown, context: PaymentRequiredContext) => Promise<{
+        headers: Record<string, string>;
+    } | void>;
+}
+/**
+ * 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;
+    private paymentRequiredHooks;
+    /**
+     * Creates a new x402HTTPClient instance.
+     *
+     * @param client - The underlying x402Client for payment logic
+     */
+    constructor(client: x402Client);
+    /**
+     * Register a hook to handle 402 responses before payment.
+     * Hooks run in order; first to return headers wins.
+     *
+     * @param hook - The hook function to register
+     * @returns This instance for chaining
+     */
+    onPaymentRequired(hook: PaymentRequiredHook): this;
+    /**
+     * Run hooks and return headers if any hook provides them.
+     *
+     * @param paymentRequired - The payment required response from the server
+     * @returns Headers to use for retry, or null to proceed to payment
+     */
+    handlePaymentRequired(paymentRequired: PaymentRequired): Promise<Record<string, string> | null>;
+    /**
+     * 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>;
+    /**
+     * Parses response headers into protocol types, fires payment response hooks (v2 only),
+     * and returns whether a hook signaled recovery.
+     *
+     * Called by transport wrappers (fetch, axios) after the paid request completes.
+     *
+     * @param paymentPayload - The payload that was sent with the request
+     * @param getHeader - Function to retrieve a response header by name
+     * @param status - The HTTP status code of the response
+     * @returns Whether a hook recovered and the parsed settle response (if any)
+     */
+    processPaymentResult(paymentPayload: PaymentPayload, getHeader: (name: string) => string | null | undefined, status: number): Promise<{
+        recovered: boolean;
+        settleResponse?: SettleResponse;
+    }>;
+    /**
+     * Parses HTTP status, headers, and body into an `HTTPResourceResponse`.
+     *
+     * Decodes the x402 payment header into `header`: the `PAYMENT-RESPONSE`
+     * settlement if present, otherwise the `PAYMENT-REQUIRED` declaration on
+     * 402 responses (whose `error` field carries the server's failure reason).
+     *
+     * @param args - Normalized response inputs from any HTTP transport
+     * @param args.status - HTTP response status code
+     * @param args.getHeader - Callback to read response headers by name
+     * @param args.body - Response body payload
+     * @returns The parsed status, body, and decoded payment header
+     */
+    parsePaymentResult(args: {
+        status: number;
+        getHeader: (name: string) => string | null | undefined;
+        body: unknown;
+    }): HTTPResourceResponse;
+    /**
+     * Parses a fetch Response into an `HTTPResourceResponse` for app-level convenience.
+     *
+     * @param response - The fetch Response to process
+     * @returns The parsed status, body, and decoded payment header
+     */
+    processResponse(response: Response): Promise<HTTPResourceResponse>;
+    /**
+     * Manual HTTP hooks run before extension hooks scoped to the 402 response.
+     *
+     * @param paymentRequired - The payment required response from the server
+     * @returns Hooks in invocation order
+     */
+    private getPaymentRequiredHooks;
+}
+/**
+ * Parsed result of an HTTP request to an x402 resource.
+ */
+type HTTPResourceResponse = {
+    /** HTTP status code. */
+    status: number;
+    /** x402 payment outcome. */
+    paymentStatus: HTTPPaymentStatus;
+    /** Parsed response body. */
+    body: unknown;
+    /**
+     * Decoded x402 payment header, if present:
+     * - SettleResponse  (from PAYMENT-RESPONSE / X-PAYMENT-RESPONSE)
+     * - PaymentRequired (from PAYMENT-REQUIRED; its `error` carries the server reason)
+     */
+    header?: SettleResponse | PaymentRequired;
+};
+type HTTPPaymentStatus = "settled" | "settle_failed" | "payment_required" | "none";
+
+export { type HTTPClientExtensionHooks, type HTTPPaymentStatus, type HTTPResourceResponse, type PaymentRequiredContext, type PaymentRequiredHook, x402Client, x402HTTPClient };