@dcentralab/d402-client 0.2.2 → 0.2.4

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { Account } from 'viem/accounts';
-import { Hash, Address } from 'viem';
+import { PublicClient, WalletClient, Hash, Address } from 'viem';
 
 /**
  * Type definitions for D402 payment protocol
@@ -191,11 +191,10 @@ interface D402ClientConfig {
      */
     operatorAccount: Account;
     /**
-     * IATPWallet contract address (optional).
-     * If not provided, uses operatorAccount.address directly.
+     * IATPWallet contract address.
      * Get from `createIATPWallet()` or `getWalletsByOwner()`.
      */
-    iatpWalletAddress?: `0x${string}`;
+    iatpWalletAddress: `0x${string}`;
     /**
      * Optional safety limit for maximum payment amount per request in base units.
      *
@@ -308,6 +307,41 @@ 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.
      *
@@ -884,5 +918,118 @@ declare function getWalletsByOwner(params: {
     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.tokenAddress - Token contract 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...',
+ *   tokenAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238', // USDC
+ * })
+ *
+ * console.log('Locked balance:', locked)
+ * ```
+ */
+declare function getLockedBalanceForProvider(params: {
+    publicClient: PublicClient;
+    settlementLayerAddress: Address;
+    providerAddress: Address;
+    tokenAddress: 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.tokenAddress - Token contract 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...',
+ *   tokenAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238', // USDC
+ * })
+ *
+ * console.log('Unlocked balance:', unlocked)
+ * ```
+ */
+declare function getUnlockedBalanceForProvider(params: {
+    publicClient: PublicClient;
+    settlementLayerAddress: Address;
+    providerAddress: Address;
+    tokenAddress: 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 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Account } from 'viem/accounts';
-import { Hash, Address } from 'viem';
+import { PublicClient, WalletClient, Hash, Address } from 'viem';
 
 /**
  * Type definitions for D402 payment protocol
@@ -191,11 +191,10 @@ interface D402ClientConfig {
      */
     operatorAccount: Account;
     /**
-     * IATPWallet contract address (optional).
-     * If not provided, uses operatorAccount.address directly.
+     * IATPWallet contract address.
      * Get from `createIATPWallet()` or `getWalletsByOwner()`.
      */
-    iatpWalletAddress?: `0x${string}`;
+    iatpWalletAddress: `0x${string}`;
     /**
      * Optional safety limit for maximum payment amount per request in base units.
      *
@@ -308,6 +307,41 @@ 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.
      *
@@ -884,5 +918,118 @@ declare function getWalletsByOwner(params: {
     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.tokenAddress - Token contract 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...',
+ *   tokenAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238', // USDC
+ * })
+ *
+ * console.log('Locked balance:', locked)
+ * ```
+ */
+declare function getLockedBalanceForProvider(params: {
+    publicClient: PublicClient;
+    settlementLayerAddress: Address;
+    providerAddress: Address;
+    tokenAddress: 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.tokenAddress - Token contract 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...',
+ *   tokenAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238', // USDC
+ * })
+ *
+ * console.log('Unlocked balance:', unlocked)
+ * ```
+ */
+declare function getUnlockedBalanceForProvider(params: {
+    publicClient: PublicClient;
+    settlementLayerAddress: Address;
+    providerAddress: Address;
+    tokenAddress: 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 };