@t402/core 2.0.0

package/README.md

@@ -0,0 +1,293 @@
+# @t402/core
+
+Core implementation of the t402 payment protocol for TypeScript/JavaScript applications. Provides transport-agnostic client, server and facilitator components.
+
+## Installation
+
+```bash
+pnpm install @t402/core
+```
+
+## Quick Start
+
+### Client Usage
+
+```typescript
+import { t402Client } from '@t402/core/client';
+import { t402HTTPClient } from '@t402/core/http';
+import { ExactEvmScheme } from '@t402/evm/exact/client';
+
+// Create core client and register payment schemes
+const coreClient = new t402Client()
+  .register('eip155:*', new ExactEvmScheme(evmSigner));
+
+// Wrap with HTTP client for header encoding/decoding
+const client = new t402HTTPClient(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 { t402ResourceServer, HTTPFacilitatorClient } from '@t402/core/server';
+import { t402HTTPResourceServer } from '@t402/core/http';
+import { ExactEvmScheme } from '@t402/evm/exact/server';
+
+// Connect to facilitator
+const facilitatorClient = new HTTPFacilitatorClient({
+  url: 'https://t402.org/facilitator',
+});
+
+// Create resource server with payment schemes
+const resourceServer = new t402ResourceServer(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 t402HTTPResourceServer(resourceServer, routes);
+```
+
+### Facilitator Usage
+
+```typescript
+import { t402Facilitator } from '@t402/core/facilitator';
+import { registerExactEvmScheme } from '@t402/evm/exact/facilitator';
+
+const facilitator = new t402Facilitator();
+
+// 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 = t402Client.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 = {
+  t402Version: number;
+  resource: ResourceInfo;
+  accepted: PaymentRequirements;
+  payload: Record<string, unknown>;
+  extensions?: Record<string, unknown>;
+};
+
+type PaymentRequired = {
+  t402Version: number;
+  error?: string;
+  resource: ResourceInfo;
+  accepts: PaymentRequirements[];
+  extensions?: Record<string, unknown>;
+};
+```
+
+## Framework Integration
+
+For framework-specific middleware, use:
+
+- `@t402/express` - Express.js middleware
+- `@t402/hono` - Hono middleware  
+- `@t402/next` - Next.js integration
+- `@t402/axios` - Axios interceptor
+- `@t402/fetch` - Fetch wrapper
+
+## Implementation Packages
+
+For blockchain-specific implementations:
+
+- `@t402/evm` - Ethereum and EVM-compatible chains
+- `@t402/svm` - Solana blockchain
+
+## Examples
+
+See the [examples directory](https://github.com/t402-io/t402/tree/main/examples/typescript) for complete examples.
+
+## Contributing
+
+Contributions welcome! See [Contributing Guide](https://github.com/t402-io/t402/blob/main/CONTRIBUTING.md).

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

@@ -0,0 +1,103 @@
+export { A as AfterPaymentCreationHook, B as BeforePaymentCreationHook, O as OnPaymentCreationFailureHook, a as PaymentCreatedContext, P as PaymentCreationContext, b as PaymentCreationFailureContext, c as PaymentPolicy, d as SchemeRegistration, S as SelectPaymentRequirements, e as t402Client, t as t402ClientConfig, f as t402HTTPClient } from '../t402HTTPClient-m6cjzTek.js';
+import { P as PaymentRequirements } from '../mechanisms-CmrqNl1M.js';
+
+/**
+ * Token Selector Utility for T402 Clients
+ *
+ * Helps clients select the best payment method from available payment requirements.
+ * Prioritizes tokens based on:
+ * 1. User token balances
+ * 2. Token priority (USDT0 > USDC > legacy tokens)
+ * 3. Network gas costs
+ */
+
+/**
+ * User token balance information
+ */
+interface UserTokenBalance {
+    /** Token contract address */
+    asset: string;
+    /** Network in CAIP-2 format (e.g., "eip155:42161") */
+    network: string;
+    /** Token balance in smallest units */
+    amount: string;
+    /** Token symbol (optional, for display) */
+    symbol?: string;
+}
+/**
+ * Token priority configuration
+ * Lower number = higher priority
+ */
+declare const DEFAULT_TOKEN_PRIORITY: Record<string, number>;
+/**
+ * Options for token selection
+ */
+interface TokenSelectionOptions {
+    /** Custom token priorities (overrides defaults) */
+    tokenPriority?: Record<string, number>;
+    /** Preferred networks (will be prioritized) */
+    preferredNetworks?: string[];
+    /** Only consider tokens the user has sufficient balance for */
+    requireSufficientBalance?: boolean;
+}
+/**
+ * Result of token selection
+ */
+interface TokenSelectionResult {
+    /** The selected payment requirements */
+    selected: PaymentRequirements | null;
+    /** All valid payment options sorted by priority */
+    alternatives: PaymentRequirements[];
+    /** Reason if no payment method was selected */
+    reason?: string;
+}
+/**
+ * Select the best payment method from available requirements
+ *
+ * @param requirements - Array of payment requirements from the server
+ * @param userBalances - Array of user's token balances
+ * @param options - Selection options
+ * @returns The best payment requirement and alternatives
+ *
+ * @example
+ * ```typescript
+ * const result = selectBestPaymentMethod(
+ *   paymentRequirements,
+ *   [
+ *     { asset: "0x...", network: "eip155:42161", amount: "1000000000" },
+ *   ],
+ *   { requireSufficientBalance: true }
+ * );
+ *
+ * if (result.selected) {
+ *   // Use result.selected for payment
+ * }
+ * ```
+ */
+declare function selectBestPaymentMethod(requirements: PaymentRequirements[], userBalances: UserTokenBalance[], options?: TokenSelectionOptions): TokenSelectionResult;
+/**
+ * Check if a payment requirement uses a gasless token (EIP-3009)
+ */
+declare function isGaslessPayment(requirement: PaymentRequirements): boolean;
+/**
+ * Check if a payment requirement is for USDT0
+ */
+declare function isUsdt0Payment(requirement: PaymentRequirements): boolean;
+/**
+ * Get payment requirements for a specific token
+ */
+declare function filterByToken(requirements: PaymentRequirements[], symbol: string): PaymentRequirements[];
+/**
+ * Get payment requirements for a specific network
+ */
+declare function filterByNetwork(requirements: PaymentRequirements[], network: string): PaymentRequirements[];
+/**
+ * Get all unique networks from payment requirements
+ */
+declare function getAvailableNetworks(requirements: PaymentRequirements[]): string[];
+/**
+ * Get all unique tokens from payment requirements
+ */
+declare function getAvailableTokens(requirements: PaymentRequirements[]): string[];
+
+export { DEFAULT_TOKEN_PRIORITY, type TokenSelectionOptions, type TokenSelectionResult, type UserTokenBalance, filterByNetwork, filterByToken, getAvailableNetworks, getAvailableTokens, isGaslessPayment, isUsdt0Payment, selectBestPaymentMethod };