@dcentralab/d402-client 0.2.0 → 0.2.2

package/README.md

@@ -2,9 +2,11 @@
 
 **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.
+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.
 
-Port of Python IATP package to TypeScript with 1:1 API compatibility.
+Part of the iatp-js monorepo. Future packages will add MCP and A2A protocol support.
+
+Built by Dcentralab.
 
 ## 🚀 Installation
 
@@ -27,76 +29,143 @@ yarn add @dcentralab/d402-client viem wagmi
 
 ## 📖 Quick Start (React/Next.js)
 
-### Usage in React Component
+## 💡 Complete React Example (Recommended Pattern)
 
-**No special configuration needed!** ✨ Uses native browser APIs (TextEncoder, TextDecoder, Web Crypto).
+### Custom Hook with Automatic Wallet Management
 
 ```typescript
 'use client'
 
-import { D402Client } from '@dcentralab/d402-client'
+import { useMutation } from '@tanstack/react-query'
 import { useWalletClient } from 'wagmi'
-import { useState } from 'react'
+import { 
+  createIATPWallet, 
+  D402Client, 
+  getWalletsByOwner 
+} from '@dcentralab/d402-client'
 
-export default function AnalyzeButton() {
-  const { data: walletClient } = useWalletClient()
-  const [result, setResult] = useState(null)
-  const [loading, setLoading] = useState(false)
+interface PaymentParams {
+  endpoint: string
+  payload: Record<string, unknown>
+  maxValue: bigint
+  network?: 'sepolia'
+}
 
-  async function analyzeWithPayment() {
-    if (!walletClient) {
-      alert('Connect your wallet first!')
-      return
-    }
+export function useD402Payment() {
+  const { data: walletClient } = useWalletClient()
 
-    setLoading(true)
+  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
+      })
 
-    try {
-      // Create D402 client with user's wallet
+      // 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: '0xUserIATPWallet...', // User's IATPWallet
-        maxValue: 1000000n  // 1 USDC max
+        iatpWalletAddress,
+        maxValue
       })
 
-      // Call 402-protected API directly from browser
-      const response = await client.fetch('https://sentiment-api.com/analyze', {
+      // Call 402-protected API
+      const response = await client.fetch(endpoint, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ text: 'Bitcoin looks bullish' })
+        body: JSON.stringify(payload)
       })
 
-      const data = await response.json()
-      setResult(data)
-
-    } catch (error) {
-      console.error('Payment failed:', error)
-    } finally {
-      setLoading(false)
+      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={analyzeWithPayment} disabled={loading || !walletClient}>
-        {loading ? 'Processing...' : 'Analyze (0.01 USDC)'}
+      <button onClick={handleAnalyze} disabled={isLoading}>
+        {isLoading ? 'Processing...' : 'Analyze Sentiment (≈0.01 USDC)'}
       </button>
-      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
+      
+      {error && (
+        <div className="error">
+          Error: {error.message}
+        </div>
+      )}
+      
+      {result && (
+        <div className="success">
+          <pre>{JSON.stringify(result, null, 2)}</pre>
+        </div>
+      )}
     </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
+**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
 
-**All in browser!** No backend or polyfills needed.
+---
 
 ## 🏗️ Features
 
@@ -117,16 +186,17 @@ const result = await createIATPWallet({
   rpcUrl: 'https://ethereum-sepolia-rpc.publicnode.com'
 })
 
-console.log('Wallet:', result.iatpWalletAddress)
-console.log('Operator key:', result.operatorPrivateKey) // Store securely!
+console.log('Wallet:', result.walletAddress)
+console.log('Owner:', result.ownerAddress)
 ```
 
 **Returns:**
-- `iatpWalletAddress` - IATPWallet contract address
-- `operatorAddress` - Operator's address
-- `operatorPrivateKey` - Operator's private key (store securely!)
+- `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
 
@@ -137,8 +207,8 @@ const client = new D402Client({
   operatorAccount,
   iatpWalletAddress: '0xYourWallet...',
   maxValue: 1000000n,
-  networkFilter: 'base-mainnet',  // Only Base network
-  schemeFilter: 'exact'           // Only exact payments
+  networkFilter: 'sepolia',  // Only Sepolia network
+  schemeFilter: 'exact'      // Only exact payments
 })
 
 // Client automatically:
@@ -242,10 +312,9 @@ Get maximum payment limit.
 Create new IATPWallet contract on-chain.
 
 **Parameters:**
-- `ownerAccount: Account` - Owner's viem account
-- `network?: 'sepolia' | 'localhost'` - Network (default: sepolia)
+- `ownerAccount: Account` - Owner's viem account (will also be the operator)
+- `network?: 'sepolia'` - Network (default: sepolia)
 - `rpcUrl?: string` - Custom RPC URL
-- `operatorPrivateKey?: 0x${string}` - Use specific operator key
 
 **`parsePaymentRequirement(response): Promise<PaymentRequirement>`**
 
@@ -382,27 +451,19 @@ const response = await fetch('/api/analyze', {
 })
 ```
 
-**Flow:** Browser → Your Backend → D402Client → External 402 API
-
-**Pros:**
-- ✅ Simpler frontend (no wallet needed)
-- ✅ 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` |
+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
 
@@ -544,7 +605,6 @@ Part of the IATP-JS monorepo:
 
 ## 🔗 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