@okxweb3/app-x402-core 0.1.2

package/README.md

@@ -0,0 +1,267 @@
+# @okxweb3/app-x402-core
+
+Core implementation of the x402 payment protocol for TypeScript/JavaScript applications. Provides transport-agnostic client, server, and facilitator components for EVM-based payment flows.
+
+## Installation
+
+```bash
+pnpm install @okxweb3/app-x402-core
+```
+
+## Quick Start
+
+### Client Usage
+
+```typescript
+import { x402Client } from '@okxweb3/app-x402-core/client';
+import { x402HTTPClient } from '@okxweb3/app-x402-core/http';
+import { ExactEvmScheme } from '@okxweb3/app-x402-evm/exact/client';
+
+// Create core client and register EVM payment scheme
+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 } from '@okxweb3/app-x402-core/server';
+import { x402HTTPResourceServer } from '@okxweb3/app-x402-core/http';
+import { OKXFacilitatorClient } from '@okxweb3/app-x402-core';
+import { ExactEvmScheme } from '@okxweb3/app-x402-evm/exact/server';
+
+// Connect to OKX facilitator
+const facilitatorClient = new OKXFacilitatorClient({
+  apiKey: 'YOUR_API_KEY',
+  secretKey: 'YOUR_SECRET_KEY',
+  passphrase: 'YOUR_PASSPHRASE',
+});
+
+// Create resource server with EVM payment scheme
+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:196',
+      payTo: '0xYourAddress',
+      price: '$0.01',
+    },
+    description: 'Premium data access',
+    mimeType: 'application/json',
+  },
+};
+
+// Create HTTP server wrapper
+const httpServer = new x402HTTPResourceServer(resourceServer, routes);
+```
+
+## OKXFacilitatorClient
+
+The `OKXFacilitatorClient` connects to the OKX facilitator service using HMAC-SHA256 authentication.
+
+```typescript
+import { OKXFacilitatorClient } from '@okxweb3/app-x402-core';
+import type { OKXConfig } from '@okxweb3/app-x402-core';
+
+const config: OKXConfig = {
+  apiKey: 'YOUR_API_KEY',
+  secretKey: 'YOUR_SECRET_KEY',
+  passphrase: 'YOUR_PASSPHRASE',
+  baseUrl: 'https://www.okx.com',   // optional, defaults to https://www.okx.com
+  syncSettle: false,                  // optional, when true the facilitator waits for on-chain confirmation
+};
+
+const client = new OKXFacilitatorClient(config);
+```
+
+## 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:196',
+      payTo: '0xAddress',
+      price: '$0.01',
+    },
+    description: 'Data endpoint',
+    mimeType: 'application/json',
+  },
+
+  // XLayer payment option
+  'POST /api/*': {
+    accepts: [
+      {
+        scheme: 'exact',
+        network: 'eip155:196',
+        payTo: '0xAddress',
+        price: '$0.05',
+      },
+    ],
+  },
+};
+```
+
+## Client Configuration
+
+Use `fromConfig()` for declarative setup:
+
+```typescript
+const client = x402Client.fromConfig({
+  schemes: [
+    { network: 'eip155:196', client: new ExactEvmScheme(evmSigner) },
+  ],
+  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
+
+| Header | Description |
+|--------|-------------|
+| `PAYMENT-SIGNATURE` | Base64-encoded payment payload |
+| `PAYMENT-REQUIRED` | Base64-encoded payment requirements |
+| `PAYMENT-RESPONSE` | Base64-encoded settlement response |
+
+## Network Pattern Matching
+
+Register handlers for EVM network families using wildcards:
+
+```typescript
+// All EVM networks
+server.register('eip155:*', new ExactEvmScheme());
+
+// Specific network takes precedence
+server.register('eip155:196', new ExactEvmScheme());
+```
+
+## Types
+
+```typescript
+type Network = `${string}:${string}`; // e.g., "eip155:196"
+
+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>;
+};
+```
+
+## Subpath Exports
+
+| Path | Description |
+|------|-------------|
+| `@okxweb3/app-x402-core` | Main entry: `x402Version`, `OKXFacilitatorClient`, `OKXConfig` |
+| `@okxweb3/app-x402-core/client` | Client: `x402Client`, `x402HTTPClient` |
+| `@okxweb3/app-x402-core/server` | Server: `x402ResourceServer`, `x402HTTPResourceServer`, `HTTPFacilitatorClient` |
+| `@okxweb3/app-x402-core/facilitator` | Facilitator: `x402Facilitator`, `OKXFacilitatorClient` |
+| `@okxweb3/app-x402-core/http` | HTTP utilities: encoding/decoding helpers, `x402HTTPResourceServer`, `x402HTTPClient` |
+| `@okxweb3/app-x402-core/types` | Shared type definitions |
+| `@okxweb3/app-x402-core/schemas` | Zod validation schemas |
+| `@okxweb3/app-x402-core/utils` | Utility functions |
+
+## License
+
+Apache-2.0

package/dist/cjs/OKXFacilitatorClient-BvyQB1QM.d.ts

@@ -0,0 +1,59 @@
+import { d as FacilitatorClient, h as SupportedResponse, P as PaymentPayload, a as PaymentRequirements, V as VerifyResponse, S as SettleResponse, i as SettleStatusResponse } from './mechanisms-sojpSwWW.js';
+
+interface OKXConfig {
+    apiKey: string;
+    secretKey: string;
+    passphrase: string;
+    baseUrl?: string;
+    /**
+     * OKX exact-scheme extension: when true, the settle call tells the facilitator to
+     * wait for on-chain confirmation before responding (syncSettle=true in request body).
+     * The facilitator then returns status="success" directly (no polling needed).
+     * When false (default), the facilitator responds with status="pending" immediately.
+     */
+    syncSettle?: boolean;
+}
+/**
+ * OKX facilitator client implementing the FacilitatorClient interface.
+ * Uses HMAC-SHA256 signing per OKX REST API authentication spec.
+ */
+declare class OKXFacilitatorClient implements FacilitatorClient {
+    private config;
+    /**
+     *
+     * @param config
+     */
+    constructor(config: OKXConfig);
+    /**
+     *
+     * @param method
+     * @param path
+     * @param body
+     */
+    private createHeaders;
+    /**
+     *
+     */
+    getSupported(): Promise<SupportedResponse>;
+    /**
+     *
+     * @param payload
+     * @param requirements
+     */
+    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     *
+     * @param payload
+     * @param requirements
+     */
+    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+    /**
+     * Query on-chain settlement status by transaction hash.
+     *
+     * @param txHash - The transaction hash to query
+     * @returns Settlement status response
+     */
+    getSettleStatus(txHash: string): Promise<SettleStatusResponse>;
+}
+
+export { type OKXConfig as O, OKXFacilitatorClient as a };

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

@@ -0,0 +1,320 @@
+import { c as PaymentRequired, a as PaymentRequirements, P as PaymentPayload, N as Network, j as SchemeNetworkClient, S as SettleResponse } from '../mechanisms-sojpSwWW.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;
+/**
+ * Extension that can enrich payment payloads on the client side.
+ *
+ * Client extensions are invoked after the scheme creates the base payment payload
+ * but before it is returned. This allows mechanism-specific logic (e.g., EVM EIP-2612
+ * permit signing) to enrich the payload's extensions data.
+ */
+interface ClientExtension {
+    /**
+     * Unique key identifying this extension (e.g., "eip2612GasSponsoring").
+     * Must match the extension key used in PaymentRequired.extensions.
+     */
+    key: string;
+    /**
+     * Called after payload creation when the extension key is present in
+     * paymentRequired.extensions. Allows the extension to enrich the payload
+     * with extension-specific data (e.g., signing an EIP-2612 permit).
+     *
+     * @param paymentPayload - The payment payload to enrich
+     * @param paymentRequired - The original PaymentRequired response
+     * @returns The enriched payment payload
+     */
+    enrichPaymentPayload?: (paymentPayload: PaymentPayload, paymentRequired: PaymentRequired) => Promise<PaymentPayload>;
+}
+/**
+ * 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:196', 'eip155:196')
+     */
+    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 readonly registeredExtensions;
+    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 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;
+    /**
+     * Registers a client extension that can enrich payment payloads.
+     *
+     * Extensions are invoked after the scheme creates the base payload and the
+     * payload is wrapped with extensions/resource/accepted data. If the extension's
+     * key is present in `paymentRequired.extensions`, the extension's
+     * `enrichPaymentPayload` hook is called to modify the payload.
+     *
+     * @param extension - The client extension to register
+     * @returns The x402Client instance for chaining
+     */
+    registerExtension(extension: ClientExtension): 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>;
+    /**
+     * Merges server-declared extensions with scheme-provided extensions.
+     * Scheme extensions overlay on top of server extensions at each key,
+     * preserving server-provided schema while overlaying scheme-provided info.
+     *
+     * @param serverExtensions - Extensions declared by the server in the 402 response
+     * @param schemeExtensions - Extensions provided by the scheme client (e.g. EIP-2612)
+     * @returns The merged extensions object, or undefined if both inputs are undefined
+     */
+    private mergeExtensions;
+    /**
+     * Enriches a payment payload by calling registered extension hooks.
+     * For each extension key present in the PaymentRequired response,
+     * invokes the corresponding extension's enrichPaymentPayload callback.
+     *
+     * @param paymentPayload - The payment payload to enrich with extension data
+     * @param paymentRequired - The PaymentRequired response containing extension declarations
+     * @returns The enriched payment payload with extension data applied
+     */
+    private enrichPaymentPayloadWithExtensions;
+    /**
+     * 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;
+}
+
+/**
+ * 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>;
+/**
+ * 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)
+     * @returns The payment required object
+     */
+    getPaymentRequiredResponse(getHeader: (name: string) => string | null | undefined): 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 ClientExtension, type OnPaymentCreationFailureHook, type PaymentCreatedContext, type PaymentCreationContext, type PaymentCreationFailureContext, type PaymentPolicy, type PaymentRequiredContext, type PaymentRequiredHook, type SchemeRegistration, type SelectPaymentRequirements, x402Client, type x402ClientConfig, x402HTTPClient };