@dcentralab/d402-client 0.2.7 → 0.3.2

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

@@ -4,517 +4,80 @@
 
 Implementation of the D402 payment protocol for HTTP 402 (Payment Required) responses. Works in any JavaScript environment (React, Next.js, Vue, Node.js, etc.) with automatic payment signing and retry.
 
-Part of the iatp-js monorepo. Future packages will add MCP and A2A protocol support.
+Part of the iatp-js monorepo. Built by Dcentralab.
 
-Built by Dcentralab.
+## 🚀 Quick Start
 
-## 🚀 Installation
+### Installation
 
 ```bash
 npm install @dcentralab/d402-client viem wagmi
-
-# or
-pnpm add @dcentralab/d402-client viem wagmi
-
-# or
-yarn add @dcentralab/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)
-
-## 💡 Complete React Example (Recommended Pattern)
+**Requirements:** React/Next.js app with viem ^2.21.0 and wagmi for wallet connection.
 
-### Custom Hook with Automatic Wallet Management
+### Your First Payment
 
 ```typescript
-'use client'
-
-import { useMutation } from '@tanstack/react-query'
+import { D402Client, createIATPWallet, getWalletsByOwner } from '@dcentralab/d402-client'
 import { useWalletClient } from 'wagmi'
-import { 
-  createIATPWallet, 
-  D402Client, 
-  getWalletsByOwner 
-} from '@dcentralab/d402-client'
-
-interface PaymentParams {
-  endpoint: string
-  payload: Record<string, unknown>
-  maxValue: bigint
-  network?: 'sepolia'
-}
-
-export function useD402Payment() {
-  const { data: walletClient } = useWalletClient()
-
-  const mutation = useMutation({
-    mutationFn: async ({ 
-      endpoint, 
-      payload, 
-      maxValue, 
-      network = 'sepolia' 
-    }: PaymentParams) => {
-      if (!walletClient) {
-        throw new Error('Please connect your wallet first')
-      }
-
-      // Check if user already has IATP wallet
-      const existingWallets = await getWalletsByOwner({
-        ownerAddress: walletClient.account.address,
-        network
-      })
-
-      // Get or create wallet
-      let iatpWalletAddress: `0x${string}`
-      
-      if (existingWallets.length === 0) {
-        // Create new wallet (one-time)
-        const newWallet = await createIATPWallet({
-          ownerAccount: walletClient.account,
-          network
-        })
-        iatpWalletAddress = newWallet.walletAddress
-      } else {
-        // Use existing wallet
-        iatpWalletAddress = existingWallets[0]
-      }
-
-      // Create D402 client
-      const client = new D402Client({
-        operatorAccount: walletClient.account,
-        iatpWalletAddress,
-        maxValue
-      })
-
-      // Call 402-protected API
-      const response = await client.fetch(endpoint, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(payload)
-      })
-
-      return await response.json()
-    }
-  })
-
-  return {
-    execute: mutation.mutateAsync,
-    isLoading: mutation.isPending,
-    result: mutation.data,
-    error: mutation.error,
-    isWalletConnected: !!walletClient
-  }
-}
-```
-
-### Use in Component
-
-```typescript
-'use client'
-
-import { useD402Payment } from '@/hooks/useD402Payment'
-
-export default function AnalyzeButton() {
-  const { execute, isLoading, result, error, isWalletConnected } = useD402Payment()
-
-  async function handleAnalyze() {
-    await execute({
-      endpoint: 'https://sentiment-api.com/analyze',
-      payload: { text: 'Bitcoin looks bullish today' },
-      maxValue: 1000000n  // 1 USDC max
-    })
-  }
-
-  if (!isWalletConnected) {
-    return <button disabled>Connect Wallet First</button>
-  }
-
-  return (
-    <div>
-      <button onClick={handleAnalyze} disabled={isLoading}>
-        {isLoading ? 'Processing...' : 'Analyze Sentiment (≈0.01 USDC)'}
-      </button>
-      
-      {error && (
-        <div className="error">
-          Error: {error.message}
-        </div>
-      )}
-      
-      {result && (
-        <div className="success">
-          <pre>{JSON.stringify(result, null, 2)}</pre>
-        </div>
-      )}
-    </div>
-  )
-}
-```
-
-**This pattern:**
-- ✅ Automatically checks for existing wallet
-- ✅ Creates wallet only if needed (one-time)
-- ✅ Reuses wallet for future calls
-- ✅ Handles loading and error states
-- ✅ Works with React Query for caching
-
----
-
-## 🏗️ Features
-
-### 1. IATPWallet Creation
-
-Create on-chain wallet with owner/operator separation:
-
-```typescript
-import { createIATPWallet } from '@dcentralab/d402-client'
-import { privateKeyToAccount } from 'viem/accounts'
 
-// Owner creates wallet (one-time setup)
-const ownerAccount = privateKeyToAccount('0x...')
+// In your React component
+const { data: walletClient } = useWalletClient()
 
-const result = await createIATPWallet({
-  ownerAccount,
-  network: 'sepolia',
-  rpcUrl: 'https://ethereum-sepolia-rpc.publicnode.com'
+// 1. Check if user has an IATP wallet
+const existingWallets = await getWalletsByOwner({
+  ownerAddress: walletClient.account.address,
+  network: 'sepolia'
 })
 
-console.log('Wallet:', result.walletAddress)
-console.log('Owner:', result.ownerAddress)
-```
-
-**Returns:**
-- `walletAddress` - IATPWallet contract address
-- `ownerAddress` - Owner's address (also the operator)
-- `transactionHash` - Creation transaction
-- `blockNumber` - Block where wallet was created
-- `network` - Network where deployed
-- `chainId` - Chain ID
-
-### 2. Automatic 402 Payment Handling
-
-```typescript
-import { D402Client } from '@dcentralab/d402-client'
+// 2. Create wallet if needed (one-time)
+const walletAddress = existingWallets.length === 0
+  ? (await createIATPWallet({ ownerAccount: walletClient.account })).walletAddress
+  : existingWallets[0]
 
+// 3. Create D402 client
 const client = new D402Client({
-  operatorAccount,
-  iatpWalletAddress: '0xYourWallet...',
-  maxValue: 1000000n,
-  networkFilter: 'sepolia',  // Only Sepolia network
-  schemeFilter: 'exact'      // Only exact payments
+  operatorAccount: walletClient.account,
+  iatpWalletAddress: walletAddress,
+  maxValue: 1000000n  // 1 USDC max
 })
 
-// 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 '@dcentralab/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,
-    iatpWalletAddress: '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) |
-| `iatpWalletAddress` | `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, {
+// 4. Call 402-protected API (automatic payment handling!)
+const response = await client.fetch('https://paid-api.com/analyze', {
   method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify(data)
+  body: JSON.stringify({ text: 'Bitcoin looks bullish' })
 })
 ```
 
-**`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 (will also be the operator)
-- `network?: 'sepolia'` - Network (default: sepolia)
-- `rpcUrl?: string` - Custom RPC URL
-
-**`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`**
+That's it! The client automatically handles 402 responses, payment signing, and retry.
 
-Convert money string to atomic units.
+## 📖 Documentation
 
-**`usdToUsdc(amount): bigint`**
+- **[Getting Started Guide](./docs/getting-started.md)** - Installation, setup, and first payment
+- **[API Reference](./docs/api-reference.md)** - Complete API documentation
+- **[Wallet Management](./docs/wallet-management.md)** - Creating and managing IATP wallets
+- **[Usage Patterns](./docs/usage-patterns.md)** - Frontend vs backend patterns
+- **[Examples](./docs/examples.md)** - Complete code examples
+- **[Security Guide](./docs/security.md)** - Best practices and security considerations
 
-Convert USD to USDC wei (6 decimals).
+## 🏗️ Key Features
 
-**`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 '@dcentralab/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,
-      iatpWalletAddress: '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
-- ⚠️ 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 '@dcentralab/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,
-    iatpWalletAddress: 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' })
-})
-```
-
-**Cons:**
-- ⚠️ Backend controls payments
-- ⚠️ More centralized
+- ✅ **Automatic 402 handling** - Detects, signs, and retries with payment
+- ✅ **EIP-712 signatures** - Secure, typed message signing
+- ✅ **Universal** - Works in browsers and Node.js
+- ✅ **Type-safe** - Full TypeScript support
+- ✅ **Well-tested** - 166 tests covering all functionality
 
 ## 🌐 Supported Networks
 
 IATP contracts are currently deployed on:
 
-| Network              | Type    | Chain ID   | USDC Address                                 | RPC URL                                           |
-|----------------------|---------|------------|----------------------------------------------|---------------------------------------------------|
-| **Sepolia Testnet**  | Testnet | `11155111` | `0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238` | [Chainlist](https://chainlist.org/chain/11155111) |
-
-> **Note:** Additional networks (mainnet, Base, Polygon, etc.) will be supported once IATP contracts are deployed on those chains.
-
-## 📦 Package Exports
-
-```typescript
-// Main client
-export { D402Client } from '@dcentralab/d402-client'
+| Network              | Chain ID   | USDC Address                                 |
+|----------------------|------------|----------------------------------------------|
+| **Sepolia Testnet**  | `11155111` | `0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238` |
 
-// Wallet management
-export { createIATPWallet } from '@dcentralab/d402-client'
-
-// Payment functions
-export {
-  parsePaymentRequirement,
-  parseAllPaymentRequirements,
-  signD402Payment,
-  encodePayment,
-  decodePayment
-} from '@dcentralab/d402-client'
-
-// Contract access
-export {
-  ContractName,
-  getContractAddress,
-  getContractAbi,
-  getContractConfig
-} from '@dcentralab/d402-client'
-
-// Utilities
-export {
-  parseMoney,
-  usdToUsdc,
-  generateNonce,
-  getChainId
-} from '@dcentralab/d402-client'
-
-// Error classes
-export {
-  PaymentError,
-  PaymentAmountExceededError,
-  UnsupportedSchemeError,
-  Invalid402ResponseError
-} from '@dcentralab/d402-client'
-
-// Types
-export type {
-  D402ClientConfig,
-  PaymentRequirement,
-  SignedPayment,
-  WalletCreationResult
-} from '@dcentralab/d402-client'
-```
+> Additional networks (mainnet, Base, Polygon, etc.) will be supported once IATP contracts are deployed.
 
 ## 🧪 Testing
 
@@ -522,102 +85,44 @@ export type {
 # 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
+# Type check
+pnpm typecheck
 ```
 
-**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
+**Test Coverage:** 166 tests covering client, wallet, payment, settlement, and integration scenarios.
 
-### 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!
-```
+## 📦 Package Exports
 
-**✅ 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
-```
+// Main client
+import { D402Client } from '@dcentralab/d402-client'
 
-Outputs:
-- `dist/index.js` - CommonJS
-- `dist/index.mjs` - ES Module
-- `dist/index.d.ts` - TypeScript types
+// Wallet management
+import { createIATPWallet, getWalletsByOwner, getAvailableBalance } from '@dcentralab/d402-client'
 
-### Type Checking
+// Payment functions
+import { signD402Payment, encodePayment, parsePaymentRequirement } from '@dcentralab/d402-client'
 
-```bash
-pnpm typecheck
+// All exports documented in API Reference
 ```
 
-## 📝 Related Packages
-
-Part of the IATP-JS monorepo:
-- `@dcentralab/d402-client` - D402 payment protocol (this package)
-- `@dcentralab/mcp-client` - MCP integration (planned)
-- `@dcentralab/a2a-client` - A2A protocol (planned)
+## 🤝 Contributing
 
-## 🔗 Related Projects
-
-- [Viem](https://viem.sh) - TypeScript Web3 library
-- [D402 Protocol](https://docs.cdp.coinbase.com/x402) - HTTP 402 specification
+We welcome contributions! See the [main Contributing Guide](../../docs/CONTRIBUTING.md).
 
 ## 📄 License
 
-MIT
+MIT License - see [LICENSE](../../LICENSE) file.
 
 ## 💬 Support
 
-- GitHub Issues: [iatp-js/issues](https://github.com/DcentraLab/iatp-js/issues)
-- Email: dev.support@d402.net
+- 📧 Email: dev.support@d402.net
+- 🐛 Issues: [GitHub Issues](https://github.com/DcentraLab/iatp-js/issues)
+- 📚 Docs: [Complete Documentation](./docs/)
 
 ---
 
 **Made with ❤️ by the DcentraLab Team**
-