@dcentralab/d402-client 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Traia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,594 @@
+# @iatp/d402-client
+
+**D402 Payment Protocol Client** for TypeScript/JavaScript
+
+Complete TypeScript implementation of the D402 payment protocol for HTTP 402 (Payment Required) responses. Designed for **React/Next.js frontends** to call 402-protected APIs directly from the browser with wallet-based payments.
+
+Port of Python IATP package to TypeScript with 1:1 API compatibility.
+
+## 🚀 Installation
+
+```bash
+npm install @iatp/d402-client viem wagmi
+# or
+pnpm add @iatp/d402-client viem wagmi
+# or
+yarn add @iatp/d402-client viem wagmi
+```
+
+**Requirements:**
+- React/Next.js app
+- viem ^2.21.0
+- wagmi (for wallet connection)
+- User with Web3 wallet (MetaMask, WalletConnect, etc.)
+
+## 📖 Quick Start (React/Next.js)
+
+### Step 1: Configure Next.js Polyfills
+
+**File:** `next.config.js`
+
+```javascript
+module.exports = {
+  webpack: (config, { isServer }) => {
+    if (!isServer) {
+      config.resolve.fallback = {
+        ...config.resolve.fallback,
+        buffer: require.resolve('buffer/'),
+        crypto: require.resolve('crypto-browserify'),
+        stream: require.resolve('stream-browserify'),
+        process: require.resolve('process/browser')
+      }
+
+      const webpack = require('webpack')
+      config.plugins.push(
+        new webpack.ProvidePlugin({
+          Buffer: ['buffer', 'Buffer'],
+          process: 'process/browser'
+        })
+      )
+    }
+    return config
+  }
+}
+```
+
+**Install polyfills:**
+```bash
+pnpm add buffer process crypto-browserify stream-browserify
+```
+
+### Step 2: Use in React Component
+
+```typescript
+'use client'
+
+import { D402Client } from '@iatp/d402-client'
+import { useWalletClient } from 'wagmi'
+import { useState } from 'react'
+
+export default function AnalyzeButton() {
+  const { data: walletClient } = useWalletClient()
+  const [result, setResult] = useState(null)
+  const [loading, setLoading] = useState(false)
+
+  async function analyzeWithPayment() {
+    if (!walletClient) {
+      alert('Connect your wallet first!')
+      return
+    }
+
+    setLoading(true)
+
+    try {
+      // Create D402 client with user's wallet
+      const client = new D402Client({
+        operatorAccount: walletClient.account,
+        walletAddress: '0xUserIATPWallet...', // User's IATPWallet
+        maxValue: 1000000n  // 1 USDC max
+      })
+
+      // Call 402-protected API directly from browser
+      const response = await client.fetch('https://sentiment-api.com/analyze', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ text: 'Bitcoin looks bullish' })
+      })
+
+      const data = await response.json()
+      setResult(data)
+
+    } catch (error) {
+      console.error('Payment failed:', error)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <div>
+      <button onClick={analyzeWithPayment} disabled={loading || !walletClient}>
+        {loading ? 'Processing...' : 'Analyze (0.01 USDC)'}
+      </button>
+      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
+    </div>
+  )
+}
+```
+
+**What happens:**
+1. User clicks button
+2. D402Client makes request to external API
+3. API returns 402
+4. Client signs payment with user's wallet
+5. Client retries with payment
+6. API returns data
+7. User sees result
+
+**All in browser!** No backend needed.
+
+## 🏗️ Features
+
+### 1. IATPWallet Creation
+
+Create on-chain wallet with owner/operator separation:
+
+```typescript
+import { createIATPWallet } from '@iatp/d402-client'
+import { privateKeyToAccount } from 'viem/accounts'
+
+// Owner creates wallet (one-time setup)
+const ownerAccount = privateKeyToAccount('0x...')
+
+const result = await createIATPWallet({
+  ownerAccount,
+  network: 'sepolia',
+  rpcUrl: 'https://ethereum-sepolia-rpc.publicnode.com'
+})
+
+console.log('Wallet:', result.walletAddress)
+console.log('Operator key:', result.operatorPrivateKey) // Store securely!
+```
+
+**Returns:**
+- `walletAddress` - IATPWallet contract address
+- `operatorAddress` - Operator's address
+- `operatorPrivateKey` - Operator's private key (store securely!)
+- `transactionHash` - Creation transaction
+- `blockNumber` - Block where wallet was created
+
+### 2. Automatic 402 Payment Handling
+
+```typescript
+import { D402Client } from '@iatp/d402-client'
+
+const client = new D402Client({
+  operatorAccount,
+  walletAddress: '0xYourWallet...',
+  maxValue: 1000000n,
+  networkFilter: 'base-mainnet',  // Only Base network
+  schemeFilter: 'exact'           // Only exact payments
+})
+
+// Client automatically:
+// 1. Detects 402 responses
+// 2. Parses payment requirements
+// 3. Signs with EIP-712
+// 4. Retries with payment
+const response = await client.fetch('https://paid-api.com/endpoint')
+```
+
+### 3. Manual Payment Flow (Low-Level)
+
+```typescript
+import {
+  parsePaymentRequirement,
+  signD402Payment,
+  encodePayment
+} from '@iatp/d402-client'
+
+// 1. Make request
+const response = await fetch('https://api.example.com')
+
+if (response.status === 402) {
+  // 2. Parse payment requirement
+  const requirement = await parsePaymentRequirement(response)
+  
+  // 3. Sign payment
+  const signedPayment = await signD402Payment({
+    operatorAccount,
+    paymentRequirement: requirement,
+    walletAddress: '0xYourWallet...'
+  })
+  
+  // 4. Encode for header
+  const paymentHeader = encodePayment(signedPayment)
+  
+  // 5. Retry with payment
+  const paidResponse = await fetch('https://api.example.com', {
+    headers: { 'X-Payment': paymentHeader }
+  })
+}
+```
+
+## 🔧 API Reference
+
+### D402Client
+
+Main class for automatic 402 payment handling.
+
+#### Constructor
+
+```typescript
+new D402Client(config: D402ClientConfig)
+```
+
+**Config Options:**
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `operatorAccount` | `Account` | ✅ | Viem account for signing payments (EOA) |
+| `walletAddress` | `0x${string}` | ❌ | IATPWallet contract address (uses operator address if not provided) |
+| `maxValue` | `bigint` | ❌ | Max payment in base units (wei). Safety limit to prevent overpaying. |
+| `networkFilter` | `string` | ❌ | Only select requirements matching this network |
+| `schemeFilter` | `string` | ❌ | Payment scheme filter (default: "exact") |
+| `paymentRequirementsSelector` | `PaymentSelector` | ❌ | Custom payment selection logic |
+
+#### Methods
+
+**`fetch(url, init?): Promise<Response>`**
+
+Fetch with automatic 402 payment handling. Same API as native fetch.
+
+```typescript
+const response = await client.fetch(url, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(data)
+})
+```
+
+**`selectPaymentRequirement(requirements): PaymentRequirement`**
+
+Select payment requirement from list based on filters.
+
+**`getWalletAddress(): 0x${string}`**
+
+Get configured wallet address.
+
+**`getOperatorAccount(): Account`**
+
+Get operator account.
+
+**`getMaxValue(): bigint | undefined`**
+
+Get maximum payment limit.
+
+### Functions
+
+**`createIATPWallet(params): Promise<WalletCreationResult>`**
+
+Create new IATPWallet contract on-chain.
+
+**Parameters:**
+- `ownerAccount: Account` - Owner's viem account
+- `network?: 'sepolia' | 'localhost'` - Network (default: sepolia)
+- `rpcUrl?: string` - Custom RPC URL
+- `operatorPrivateKey?: 0x${string}` - Use specific operator key
+
+**`parsePaymentRequirement(response): Promise<PaymentRequirement>`**
+
+Parse first payment requirement from 402 response.
+
+**`parseAllPaymentRequirements(response): Promise<PaymentRequirement[]>`**
+
+Parse all payment requirements from 402 response.
+
+**`signD402Payment(params): Promise<SignedPayment>`**
+
+Sign payment with EIP-712.
+
+**`encodePayment(payment): string`**
+
+Encode signed payment to base64 for X-Payment header.
+
+**`decodePayment(encoded): SignedPayment`**
+
+Decode base64 payment header.
+
+### Contract Functions
+
+**`getContractAddress(name, network): string | null`**
+
+Get contract address for network.
+
+**`getContractAbi(name, network): any[] | null`**
+
+Get contract ABI for network.
+
+**`getContractConfig(name, network): { address, abi } | null`**
+
+Get both address and ABI.
+
+### Utility Functions
+
+**`parseMoney(amount, decimals): bigint`**
+
+Convert money string to atomic units.
+
+**`usdToUsdc(amount): bigint`**
+
+Convert USD to USDC wei (6 decimals).
+
+**`generateNonce(): 0x${string}`**
+
+Generate random 32-byte nonce.
+
+**`getChainId(network): number`**
+
+Get chain ID for network name.
+
+## 💡 Usage Patterns
+
+### Pattern 1: Frontend Direct (Recommended for Web3 Apps)
+
+**React component calls 402 API directly:**
+
+```typescript
+'use client'
+
+import { D402Client } from '@iatp/d402-client'
+import { useWalletClient } from 'wagmi'
+
+export default function PaymentComponent() {
+  const { data: walletClient } = useWalletClient()
+
+  async function callPaidAPI() {
+    if (!walletClient) return
+
+    // User's wallet signs payments
+    const client = new D402Client({
+      operatorAccount: walletClient.account,
+      walletAddress: '0xUserIATPWallet...',
+      maxValue: 1000000n
+    })
+
+    // Calls external 402 API directly
+    const response = await client.fetch('https://sentiment-api.com/analyze', {
+      method: 'POST',
+      body: JSON.stringify({ text: 'Bitcoin sentiment' })
+    })
+
+    return await response.json()
+  }
+}
+```
+
+**Flow:** Browser → D402Client → External 402 API
+
+**Pros:**
+- ✅ User pays from their wallet
+- ✅ Fully decentralized
+- ✅ No backend needed
+
+**Cons:**
+- ⚠️ Requires wallet connection
+- ⚠️ Needs Next.js polyfill config
+- ⚠️ User approves each payment
+
+### Pattern 2: Backend Proxy (Alternative)
+
+**Backend handles 402 calls, frontend just calls your API:**
+
+**Backend (Node.js):**
+```typescript
+import { D402Client } from '@iatp/d402-client'
+import { privateKeyToAccount } from 'viem/accounts'
+
+const operatorAccount = privateKeyToAccount(process.env.OPERATOR_KEY!)
+
+app.post('/api/analyze', async (req, res) => {
+  const client = new D402Client({
+    operatorAccount,
+    walletAddress: req.user.iatpWallet,
+    maxValue: 1000000n
+  })
+  
+  const response = await client.fetch('https://sentiment-api.com/analyze', {
+    method: 'POST',
+    body: JSON.stringify(req.body)
+  })
+  
+  res.json(await response.json())
+})
+```
+
+**Frontend (simpler):**
+```typescript
+// Just call YOUR backend
+const response = await fetch('/api/analyze', {
+  method: 'POST',
+  body: JSON.stringify({ text: 'Analyze this' })
+})
+```
+
+**Flow:** Browser → Your Backend → D402Client → External 402 API
+
+**Pros:**
+- ✅ Simpler frontend (no wallet needed)
+- ✅ No polyfills needed in frontend
+- ✅ Smooth UX (no wallet popups)
+
+**Cons:**
+- ⚠️ Backend controls payments
+- ⚠️ More centralized
+
+## 🌐 Supported Networks
+
+| Network | Chain ID | USDC Address |
+|---------|----------|--------------|
+| Ethereum Mainnet | 1 | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` |
+| Sepolia Testnet | 11155111 | `0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238` |
+| Base | 8453 | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
+| Base Sepolia | 84532 | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
+| Polygon | 137 | `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` |
+| Arbitrum One | 42161 | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` |
+| Arbitrum Sepolia | 421614 | `0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d` |
+
+## 📦 Package Exports
+
+```typescript
+// Main client
+export { D402Client } from '@iatp/d402-client'
+
+// Wallet management
+export { createIATPWallet } from '@iatp/d402-client'
+
+// Payment functions
+export {
+  parsePaymentRequirement,
+  parseAllPaymentRequirements,
+  signD402Payment,
+  encodePayment,
+  decodePayment
+} from '@iatp/d402-client'
+
+// Contract access
+export {
+  ContractName,
+  getContractAddress,
+  getContractAbi,
+  getContractConfig
+} from '@iatp/d402-client'
+
+// Utilities
+export {
+  parseMoney,
+  usdToUsdc,
+  generateNonce,
+  getChainId
+} from '@iatp/d402-client'
+
+// Error classes
+export {
+  PaymentError,
+  PaymentAmountExceededError,
+  UnsupportedSchemeError,
+  Invalid402ResponseError
+} from '@iatp/d402-client'
+
+// Types
+export type {
+  D402ClientConfig,
+  PaymentRequirement,
+  SignedPayment,
+  WalletCreationResult
+} from '@iatp/d402-client'
+```
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+pnpm test
+
+# Run specific test file
+pnpm test client.test.ts
+
+# Run with coverage
+pnpm test --coverage
+
+# Watch mode
+pnpm test --watch
+```
+
+**Test Coverage:**
+- ✅ 17 encoder/decoder tests
+- ✅ 19 parser tests  
+- ✅ 29 contracts tests
+- ✅ 24 signer tests
+- ✅ 14 wallet tests
+- ✅ 19 client constructor tests
+- ✅ 22 integration tests
+
+**Total: 144 tests**
+
+## 🔒 Security
+
+### Private Key Handling
+
+**✅ Safe (Backend):**
+```typescript
+// Store operator key in environment variable
+const operatorAccount = privateKeyToAccount(process.env.OPERATOR_KEY!)
+```
+
+**❌ Unsafe (Frontend):**
+```typescript
+// Never hardcode private keys in frontend code
+const account = privateKeyToAccount('0xHARDCODED') // DON'T DO THIS!
+```
+
+**✅ Safe (Frontend with Wallet):**
+```typescript
+// Use wallet client from wagmi/viem
+const { data: walletClient } = useWalletClient()
+const client = new D402Client({
+  operatorAccount: walletClient.account
+})
+```
+
+### Payment Security
+
+- ✅ EIP-712 typed signatures prevent tampering
+- ✅ Nonce prevents replay attacks  
+- ✅ Timestamp bounds (validAfter/validBefore)
+- ✅ Amount verification
+- ✅ Destination address verification
+- ✅ maxValue safety limit
+
+## 🛠️ Development
+
+### Build
+
+```bash
+pnpm build
+```
+
+Outputs:
+- `dist/index.js` - CommonJS
+- `dist/index.mjs` - ES Module
+- `dist/index.d.ts` - TypeScript types
+
+### Type Checking
+
+```bash
+pnpm typecheck
+```
+
+## 📝 Related Packages
+
+Part of the IATP-JS monorepo:
+- `@iatp/d402-client` - D402 payment protocol (this package)
+- `@iatp/mcp-client` - MCP integration (planned)
+- `@iatp/a2a-client` - A2A protocol (planned)
+
+## 🔗 Related Projects
+
+- [IATP Python](https://github.com/Traia-IO/IATP) - Python implementation
+- [Viem](https://viem.sh) - TypeScript Web3 library
+- [D402 Protocol](https://docs.cdp.coinbase.com/x402) - HTTP 402 specification
+
+## 📄 License
+
+MIT
+
+## 💬 Support
+
+- GitHub Issues: [iatp-js/issues](https://github.com/Traia-IO/iatp-js/issues)
+- Email: support@traia.io
+
+---
+
+**Made with ❤️ by the Traia Team**
+