@dcentralab/d402-client 0.2.1 → 0.2.3

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 import { Account } from 'viem/accounts';
-import { Hash, Address } from 'viem';
+import { PublicClient, WalletClient, Hash, Address } from 'viem';
 
 /**
  * Type definitions for D402 payment protocol
  */
 
 /**
- * Supported blockchain networks
+ * Supported blockchain networks (where IATP contracts are deployed)
  */
-type SupportedNetwork = 'mainnet' | 'sepolia' | 'base' | 'polygon';
+type SupportedNetwork = 'sepolia';
 /**
  * D402 Client configuration
  */
@@ -34,9 +34,9 @@ interface EIP712Domain {
     verifyingContract: `0x${string}`;
 }
 /**
- * Payment requirement from 402 response
+ * Payment requirement from 402 response.
  *
- * Matches Python: PaymentRequirements (types.py lines 97-108)
+ * Describes the payment details required by a 402-protected API.
  */
 interface PaymentRequirement {
     /** D402 protocol version */
@@ -128,7 +128,7 @@ interface PaymentSelectorOptions {
 /**
  * Select payment requirement from a list based on filters and preferences
  *
- * This function implements the same logic as Python's default_payment_requirements_selector
+ * This function implements the same logic as
  *
  * @param requirements - List of accepted payment requirements from 402 response
  * @param options - Selection options and filters
@@ -177,22 +177,24 @@ declare function sortPaymentRequirements(requirements: PaymentRequirement[], pre
 /**
  * D402 Client - Main client class for handling HTTP 402 payments
  *
- * Matches Python implementation: IATP/src/traia_iatp/d402/clients/base.py d402Client
  */
 
 /**
  * D402 Client configuration.
  *
- * Matches Python: d402Client.__init__ parameters (base.py lines 66-72)
+ * The client uses the user's wallet to sign payment authorizations for 402-protected APIs.
  */
 interface D402ClientConfig {
-    /** Operator account with private key for signing payments (EOA) */
+    /**
+     * User's account for signing payments.
+     * Typically from wagmi: `walletClient.account`
+     */
     operatorAccount: Account;
     /**
      * IATPWallet contract address.
-     * If not provided, uses operatorAccount.address for testing.
+     * Get from `createIATPWallet()` or `getWalletsByOwner()`.
      */
-    iatpWalletAddress?: `0x${string}`;
+    iatpWalletAddress: `0x${string}`;
     /**
      * Optional safety limit for maximum payment amount per request in base units.
      *
@@ -227,8 +229,6 @@ interface D402ClientConfig {
 /**
  * D402 Client for handling HTTP 402 Payment Required responses.
  *
- * Matches Python: d402Client class (base.py lines 63-219)
- *
  * This client automatically:
  * 1. Detects HTTP 402 responses
  * 2. Parses payment requirements
@@ -267,15 +267,23 @@ declare class D402Client {
     /**
      * Create a new D402 Client.
      *
-     * Matches Python: d402Client.__init__ (base.py lines 66-95)
-     *
      * @param config - Client configuration
+     *
+     * @example
+     * ```ts
+     * const client = new D402Client({
+     *   operatorAccount: walletClient.account,  // User's wallet from wagmi
+     *   iatpWalletAddress: userWallet,          // From createIATPWallet() or getWalletsByOwner()
+     *   maxValue: 1000000n                       // Safety limit: 1 USDC max
+     * })
+     * ```
      */
     constructor(config: D402ClientConfig);
     /**
      * Select payment requirement from list of options.
      *
-     * Matches Python: select_payment_requirements (base.py lines 152-174)
+     * Applies configured filters (network, scheme, maxValue) to choose
+     * the appropriate payment option from the server's requirements list.
      *
      * @param requirements - List of payment requirements from 402 response
      * @returns Selected payment requirement
@@ -284,13 +292,13 @@ declare class D402Client {
     /**
      * Get the IATP wallet address used for payments.
      *
-     * @returns IATPWallet contract address or operator EOA address
+     * @returns IATPWallet contract address, or user's EOA address if no wallet configured
      */
     getIATPWalletAddress(): `0x${string}`;
     /**
-     * Get the operator account used for signing.
+     * Get the user's account used for signing payments.
      *
-     * @returns Operator account
+     * @returns User's wallet account
      */
     getOperatorAccount(): Account;
     /**
@@ -299,10 +307,44 @@ declare class D402Client {
      * @returns Maximum value in base units, or undefined if no limit
      */
     getMaxValue(): bigint | undefined;
+    /**
+     * Get available balance for a token in the IATP wallet.
+     *
+     * @param publicClient - Viem PublicClient (from wagmi usePublicClient)
+     * @param tokenAddress - Token contract address
+     * @returns Available balance in token's base units (wei)
+     */
+    getAvailableBalance(publicClient: PublicClient, tokenAddress: `0x${string}`): Promise<bigint>;
+    /**
+     * Get withdrawal request for a token.
+     *
+     * @param publicClient - Viem PublicClient
+     * @param tokenAddress - Token contract address
+     * @returns Withdrawal request: [amount, unlockTimestamp] or null if no request exists
+     */
+    getWithdrawalRequest(publicClient: PublicClient, tokenAddress: `0x${string}`): Promise<[bigint, bigint] | null>;
+    /**
+     * Request a withdrawal from the IATP wallet.
+     *
+     * @param walletClient - Viem WalletClient (from wagmi useWalletClient)
+     * @param publicClient - Viem PublicClient (from wagmi usePublicClient)
+     * @param tokenAddress - Token contract address
+     * @param amount - Amount in token's base units (wei)
+     * @returns Transaction hash
+     */
+    requestWithdrawal(walletClient: WalletClient, publicClient: PublicClient, tokenAddress: `0x${string}`, amount: bigint): Promise<Hash>;
+    /**
+     * Execute a withdrawal for a token (after unlock period).
+     *
+     * @param walletClient - Viem WalletClient
+     * @param publicClient - Viem PublicClient
+     * @param tokenAddress - Token contract address
+     * @returns Transaction hash
+     */
+    executeWithdrawal(walletClient: WalletClient, publicClient: PublicClient, tokenAddress: `0x${string}`): Promise<Hash>;
     /**
      * Fetch with automatic 402 payment handling.
      *
-     * Matches Python: HttpxHooks.on_response() (httpx.py lines 33-117)
      *
      * Flow:
      * 1. Make request without payment
@@ -334,34 +376,37 @@ declare class D402Client {
 
 /**
  * EIP-712 payment signing utilities
- *
- * Matches Python implementation: IATP/src/traia_iatp/d402/payment_signing.py
  */
 
 /**
  * Sign a D402 payment using EIP-712 signature.
  *
- * Matches Python: sign_payment_header(operator_account, payment_requirements, header, wallet_address, request_path)
- * (payment_signing.py lines 54-155)
+ * Signs a payment authorization with the user's wallet (MetaMask/WalletConnect).
+ * This creates a PullFundsForSettlement signature that authorizes the payment.
  *
- * This creates a PullFundsForSettlement signature that matches IATPWallet.sol validation.
+ * The user will see a MetaMask popup to approve the signature.
  *
  * @param params - Signing parameters
- * @param params.operatorAccount - Operator account with private key for signing (EOA)
+ * @param params.operatorAccount - User's account for signing (from wagmi walletClient)
  * @param params.paymentRequirement - Payment requirements from 402 response
- * @param params.iatpWalletAddress - IATPWallet contract address (optional, uses operator address if not provided)
+ * @param params.iatpWalletAddress - IATPWallet contract address (optional)
  * @param params.requestPath - API request path (optional, uses payment_requirements.resource if not provided)
  * @returns Signed payment ready to encode and send
  *
  * @example
  * ```ts
+ * // Get payment requirement from 402 response
  * const requirement = await parsePaymentRequirement(response)
+ *
+ * // User signs payment (MetaMask popup appears)
  * const signedPayment = await signD402Payment({
- *   operatorAccount: account,
+ *   operatorAccount: walletClient.account,  // User's wallet
  *   paymentRequirement: requirement,
- *   iatpWalletAddress: '0xUserWallet...'
+ *   iatpWalletAddress: '0xUserIATPWallet...'
  * })
- * const encoded = encodePayment(signedPayment)
+ *
+ * // Encode for X-Payment header
+ * const paymentHeader = encodePayment(signedPayment)
  * ```
  */
 declare function signD402Payment(params: {
@@ -374,30 +419,27 @@ declare function signD402Payment(params: {
 
 /**
  * Parse 402 payment requirements from HTTP responses
- *
- * Matches Python implementation: IATP/src/traia_iatp/d402/clients/httpx.py lines 64-66
- * Response structure from: IATP/src/traia_iatp/d402/types.py d402PaymentRequiredResponse
  */
 
 /**
  * Parse payment requirements from HTTP 402 response.
  *
- * Matches Python:
- *   data = response.json()
- *   payment_response = d402PaymentRequiredResponse(**data)
- *
- * The 402 response body contains payment requirements in camelCase JSON format.
+ * When an API returns 402 "Payment Required", this function extracts
+ * the payment details (amount, token, network) from the response body.
  *
  * @param response - HTTP Response object with status 402
- * @returns First payment requirement from accepts array
+ * @returns First payment requirement from the response
  * @throws {Invalid402ResponseError} If response is not valid 402 or malformed
  *
  * @example
  * ```ts
- * const response = await fetch('http://api.example.com')
+ * const response = await fetch('https://sentiment-api.com/analyze')
+ *
  * if (response.status === 402) {
  *   const requirement = await parsePaymentRequirement(response)
- *   console.log(requirement.maxAmountRequired) // "10000"
+ *   console.log('Payment required:', requirement.maxAmountRequired, 'wei')
+ *   console.log('Token:', requirement.asset)
+ *   console.log('Network:', requirement.network)
  * }
  * ```
  */
@@ -405,32 +447,32 @@ declare function parsePaymentRequirement(response: Response): Promise<PaymentReq
 
 /**
  * Base64 encoding/decoding for payment payloads
- *
- * Matches Python implementation: IATP/src/traia_iatp/d402/encoding.py
  */
 
 /**
- * Encode a payment object to base64 string.
+ * Encode a signed payment to base64 string for X-Payment header.
  *
- * This combines JSON serialization with base64 encoding.
- * Matches Python: encode_payment(payment_payload: Dict[str, Any]) -> str
+ * Takes a signed payment object and encodes it to base64 format
+ * that can be sent in the X-Payment HTTP header.
  *
- * @param payment - Payment object to encode
- * @returns Base64 encoded payment string suitable for X-Payment header
+ * @param payment - Signed payment object (from signD402Payment)
+ * @returns Base64 encoded string ready for X-Payment header
  *
  * @example
  * ```ts
- * const payment = { d402Version: 1, scheme: 'exact', payload: {...} }
- * const encoded = encodePayment(payment)
- * // Use in header: { 'X-Payment': encoded }
+ * const signedPayment = await signD402Payment({...})
+ * const encoded = encodePayment(signedPayment)
+ *
+ * // Send in HTTP request
+ * fetch(url, {
+ *   headers: { 'X-Payment': encoded }
+ * })
  * ```
  */
 declare function encodePayment(payment: SignedPayment): string;
 /**
  * Decode a base64 encoded payment string back to payment object.
  *
- * Matches Python: decode_payment(encoded_payment: str) -> Dict[str, Any]
- *
  * @param encodedPayment - Base64 encoded payment string
  * @returns Decoded payment object
  *
@@ -481,9 +523,12 @@ declare function getUsdcAddress(network: SupportedNetwork): `0x${string}`;
 /**
  * Get chain ID for a given network.
  *
- * Matches Python: get_chain_id(network: str) -> str (chains.py lines 10-21)
+ * This function maps network names to chain IDs for parsing 402 payment requirements
+ * from external APIs. It supports many networks that may appear in 402 responses,
+ * even if IATP contracts are not deployed on those networks.
  *
- * Supports both network names and numeric chain IDs as strings.
+ * Note: IATP contracts are currently only deployed on Sepolia. This function exists
+ * to handle 402 responses from any API that might support other networks.
  *
  * @param network - Network name or chain ID as string
  * @returns Chain ID as number
@@ -494,7 +539,7 @@ declare function getUsdcAddress(network: SupportedNetwork): `0x${string}`;
  * ```ts
  * getChainId('sepolia')    // Returns 11155111
  * getChainId('11155111')   // Returns 11155111 (passthrough)
- * getChainId('base')       // Returns 8453
+ * getChainId('base')       // Returns 8453 (for parsing 402 responses)
  * ```
  */
 declare function getChainId(network: string): number;
@@ -675,16 +720,13 @@ declare const EIP712_TYPES: {
 };
 
 /**
- * Contract configuration and utilities for IATP.
- *
- * Matches Python implementation: IATP/src/traia_iatp/contracts/config.py
+ * Contract configuration and utilities.
  *
- * Bundles contract ABIs and addresses directly in the package for reliable access.
+ * Provides access to IATPWallet contract ABIs and deployed addresses.
+ * Contract data is bundled directly in the package for reliability.
  */
 /**
  * Supported contract names.
- *
- * Matches Python: ContractName enum (config.py lines 16-21)
  */
 declare enum ContractName {
     IATP_WALLET = "IATPWallet",
@@ -694,16 +736,11 @@ declare enum ContractName {
 }
 /**
  * Supported networks for contract deployments.
- *
- * Matches Python: SUPPORTED_NETWORKS (config.py line 25)
  */
-type SupportedContractNetwork = 'sepolia' | 'localhost';
+type SupportedContractNetwork = 'sepolia';
 /**
  * Get contract address for a given network.
  *
- * Matches Python: get_contract_address(contract_name: str, network: str) -> Optional[str]
- * (config.py lines 77-118)
- *
  * @param contractName - Name of the contract (use ContractName enum)
  * @param network - Network name (default: "sepolia")
  * @param useProxy - Use proxy address if true, implementation if false (default: true)
@@ -719,9 +756,6 @@ declare function getContractAddress(contractName: string | ContractName, network
 /**
  * Get contract ABI for a given network.
  *
- * Matches Python: get_contract_abi(contract_name: str, network: str) -> Optional[List[dict]]
- * (config.py lines 121-156)
- *
  * @param contractName - Name of the contract (use ContractName enum)
  * @param network - Network name (default: "sepolia")
  * @returns Contract ABI as array of objects, or null if not found
@@ -736,8 +770,6 @@ declare function getContractAbi(contractName: string | ContractName, network?: S
 /**
  * Get contract configuration (address and ABI) for a network.
  *
- * Matches Python: get_contract_config(network: str) from wallet_creator.py
- *
  * @param contractName - Name of the contract
  * @param network - Network name (default: "sepolia")
  * @returns Object with address and abi, or null if not found
@@ -787,23 +819,16 @@ declare function isContractDeployed(contractName: string | ContractName, network
 /**
  * IATPWallet creation and management
  *
- * Matches Python implementation: IATP/src/traia_iatp/scripts/create_wallet.py
  */
 
 /**
  * Result of wallet creation.
- *
- * Matches Python: create_wallet() return type (lines 138-147)
  */
 interface WalletCreationResult {
     /** Address of the created IATPWallet contract */
     walletAddress: `0x${string}`;
-    /** Owner address (who created it) */
+    /** Owner address (who created it, also the operator) */
     ownerAddress: `0x${string}`;
-    /** Operator address (can sign payments) */
-    operatorAddress: `0x${string}`;
-    /** Operator private key (store securely!) */
-    operatorPrivateKey: `0x${string}`;
     /** Transaction hash */
     transactionHash: Hash;
     /** Block number where wallet was created */
@@ -816,15 +841,15 @@ interface WalletCreationResult {
 /**
  * Create a new IATPWallet using IATPWalletFactory.
  *
- * Matches Python: create_wallet(owner_private_key, network, wait_confirmations)
- * (create_wallet.py lines 37-149)
+ * Creates an on-chain smart contract wallet where the user is both owner and operator.
+ * The user signs all payments themselves with their wallet (MetaMask/WalletConnect).
  *
  * This function:
- * 1. Generates a new operator keypair
- * 2. Calls IATPWalletFactory.createWallet(operatorAddress)
+ * 1. Calls IATPWalletFactory.createWallet(ownerAddress)
+ * 2. Sets owner as operator (user signs all payments)
  * 3. Waits for transaction confirmation
  * 4. Extracts wallet address from WalletCreated event
- * 5. Returns wallet info including operator keys
+ * 5. Returns wallet address and transaction info
  *
  * @param params - Creation parameters
  * @param params.ownerAccount - Owner's account (will own the wallet)
@@ -851,9 +876,8 @@ interface WalletCreationResult {
  */
 declare function createIATPWallet(params: {
     ownerAccount: Account;
-    network?: 'sepolia' | 'localhost';
+    network?: 'sepolia';
     rpcUrl?: string;
-    operatorPrivateKey?: `0x${string}`;
 }): Promise<WalletCreationResult>;
 /**
  * Get all IATPWallet addresses owned by a user.
@@ -861,30 +885,145 @@ declare function createIATPWallet(params: {
  * Queries the IATPWalletFactory contract to retrieve all wallets
  * where the specified address is the owner.
  *
+ * Use this to check if a user already has a wallet before calling createIATPWallet().
+ *
  * @param params - Query parameters
- * @param params.ownerAddress - Owner's address to query
+ * @param params.ownerAddress - User's wallet address (from MetaMask)
  * @param params.network - Network to query (default: "sepolia")
  * @param params.rpcUrl - Custom RPC URL (optional)
- * @returns Array of IATPWallet contract addresses
+ * @returns Array of IATPWallet contract addresses (empty if user has no wallets)
  *
  * @example
  * ```ts
  * import { getWalletsByOwner } from '@dcentralab/d402-client'
+ * import { useAccount } from 'wagmi'
  *
- * // Get user's wallets
+ * const { address } = useAccount()
+ *
+ * // Check if user has any wallets
  * const wallets = await getWalletsByOwner({
- *   ownerAddress: '0xUserAddress...',
+ *   ownerAddress: address,
  *   network: 'sepolia'
  * })
  *
- * console.log(`User has ${wallets.length} wallets`)
- * wallets.forEach(addr => console.log('Wallet:', addr))
+ * if (wallets.length === 0) {
+ *   // Show "Create Wallet" button
+ * } else {
+ *   // Use existing wallet: wallets[0]
+ * }
  * ```
  */
 declare function getWalletsByOwner(params: {
     ownerAddress: Address;
-    network?: 'sepolia' | 'localhost';
+    network?: 'sepolia';
     rpcUrl?: string;
 }): Promise<Address[]>;
+/**
+ * Get available balance for a specific token in an IATPWallet.
+ *
+ * Queries the IATPWallet contract's getAvailableBalance function to retrieve
+ * the available balance for a given token.
+ *
+ * @param params - Query parameters
+ * @param params.publicClient - Viem PublicClient (from wagmi usePublicClient)
+ * @param params.walletAddress - IATPWallet contract address
+ * @param params.tokenAddress - Token contract address (e.g., USDC)
+ * @param params.network - Network to query (default: "sepolia")
+ * @returns Available balance in token's base units (wei)
+ *
+ * @example
+ * ```ts
+ * import { getAvailableBalance } from '@dcentralab/d402-client'
+ * import { usePublicClient } from 'wagmi'
+ *
+ * const publicClient = usePublicClient()
+ *
+ * const balance = await getAvailableBalance({
+ *   publicClient,
+ *   walletAddress: '0xUserIATPWallet...',
+ *   tokenAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238', // USDC on Sepolia
+ * })
+ *
+ * console.log('Available balance:', balance) // 1000000n (1 USDC)
+ * ```
+ */
+declare function getAvailableBalance(params: {
+    publicClient: PublicClient;
+    walletAddress: Address;
+    tokenAddress: Address;
+    network?: 'sepolia';
+}): Promise<bigint>;
+
+/**
+ * IATPSettlementLayer contract operations
+ *
+ * Functions for providers (utility agents) to query settlement balances,
+ * epochs, and manage withdrawals from the settlement layer.
+ */
+
+/**
+ * Get locked balance for a provider across unreleased epochs.
+ *
+ * This is the balance that's locked in the settlement layer and cannot
+ * be withdrawn yet (still within the release delay period).
+ *
+ * @param params - Query parameters
+ * @param params.publicClient - Viem PublicClient (from wagmi usePublicClient)
+ * @param params.settlementLayerAddress - IATPSettlementLayer contract address
+ * @param params.providerAddress - Provider (utility agent) address
+ * @param params.network - Network (default: "sepolia")
+ * @returns Locked balance in base units (wei)
+ *
+ * @example
+ * ```ts
+ * import { getLockedBalanceForProvider } from '@dcentralab/d402-client'
+ *
+ * const locked = await getLockedBalanceForProvider({
+ *   publicClient,
+ *   settlementLayerAddress: '0x...',
+ *   providerAddress: '0xUtilityAgent...',
+ * })
+ *
+ * console.log('Locked balance:', locked)
+ * ```
+ */
+declare function getLockedBalanceForProvider(params: {
+    publicClient: PublicClient;
+    settlementLayerAddress: Address;
+    providerAddress: Address;
+    network?: 'sepolia';
+}): Promise<bigint>;
+/**
+ * Get unlocked balance for a provider across released epochs.
+ *
+ * This is the balance that's available for withdrawal (epochs have passed
+ * the release delay and haven't been withdrawn yet).
+ *
+ * @param params - Query parameters
+ * @param params.publicClient - Viem PublicClient (from wagmi usePublicClient)
+ * @param params.settlementLayerAddress - IATPSettlementLayer contract address
+ * @param params.providerAddress - Provider (utility agent) address
+ * @param params.network - Network (default: "sepolia")
+ * @returns Unlocked balance in base units (wei)
+ *
+ * @example
+ * ```ts
+ * import { getUnlockedBalanceForProvider } from '@dcentralab/d402-client'
+ *
+ * const unlocked = await getUnlockedBalanceForProvider({
+ *   publicClient,
+ *   settlementLayerAddress: '0x...',
+ *   providerAddress: '0xUtilityAgent...',
+ * })
+ *
+ * console.log('Unlocked balance:', unlocked)
+ * ```
+ */
+declare function getUnlockedBalanceForProvider(params: {
+    publicClient: PublicClient;
+    settlementLayerAddress: Address;
+    providerAddress: Address;
+    network?: 'sepolia';
+}): Promise<bigint>;
 
-export { CHAIN_IDS, ContractName, D402Client, type D402ClientConfig, type D402Config, DEFAULT_VALIDITY_WINDOW_SECONDS, type EIP712Domain, EIP712_TYPES, Invalid402ResponseError, MissingRequestConfigError, NETWORKS, PaymentAlreadyAttemptedError, PaymentAmountExceededError, type PaymentAuthorization, PaymentError, type PaymentRequirement, type PaymentSelector, type PaymentSelectorOptions, PaymentVerificationError, type SignedPayment, type SupportedContractNetwork, type SupportedNetwork, TOKEN_ADDRESSES, UnsupportedNetworkError, UnsupportedSchemeError, type WalletCreationResult, createIATPWallet, createPaymentSelector, decodePayment, decodePaymentResponse, encodePayment, findMatchingPaymentRequirement, formatMoney, generateNonce, getAllContractAddresses, getChainId, getContractAbi, getContractAddress, getContractConfig, getCurrentTimestamp, getUsdcAddress, getWalletsByOwner, isContractDeployed, isValidAddress, normalizeAddress, parseMoney, parsePaymentRequirement, selectPaymentRequirement, signD402Payment, sortPaymentRequirements, usdToUsdc };
+export { CHAIN_IDS, ContractName, D402Client, type D402ClientConfig, type D402Config, DEFAULT_VALIDITY_WINDOW_SECONDS, type EIP712Domain, EIP712_TYPES, Invalid402ResponseError, MissingRequestConfigError, NETWORKS, PaymentAlreadyAttemptedError, PaymentAmountExceededError, type PaymentAuthorization, PaymentError, type PaymentRequirement, type PaymentSelector, type PaymentSelectorOptions, PaymentVerificationError, type SignedPayment, type SupportedContractNetwork, type SupportedNetwork, TOKEN_ADDRESSES, UnsupportedNetworkError, UnsupportedSchemeError, type WalletCreationResult, createIATPWallet, createPaymentSelector, decodePayment, decodePaymentResponse, encodePayment, findMatchingPaymentRequirement, formatMoney, generateNonce, getAllContractAddresses, getAvailableBalance, getChainId, getContractAbi, getContractAddress, getContractConfig, getCurrentTimestamp, getLockedBalanceForProvider, getUnlockedBalanceForProvider, getUsdcAddress, getWalletsByOwner, isContractDeployed, isValidAddress, normalizeAddress, parseMoney, parsePaymentRequirement, selectPaymentRequirement, signD402Payment, sortPaymentRequirements, usdToUsdc };