@explorins/pers-sdk-react-native 2.0.5 → 2.1.1

package/README.md

@@ -208,6 +208,18 @@ const {
   getTokenByContract
 } = useTokens();
 
+// Token balance loading (NEW in v2.1.1)
+const {
+  tokenBalances,      // Array of balances with token metadata
+  isLoading,          // Loading state
+  error,              // Error state
+  refresh             // Manual refresh function
+} = useTokenBalances({
+  availableTokens,    // From useTokens()
+  autoLoad: true,     // Auto-load on mount
+  refreshInterval: 30000  // Optional: refresh every 30s
+});
+
 // Transaction history
 const { 
   createTransaction,
@@ -458,8 +470,8 @@ function POSScreen() {
   }, [subscribe, isAvailable]);
   
   const handlePOSTransaction = async (
-    userAccountId: string,
-    businessAccountId: string,
+    userId: string,
+    businessId: string,
     amount: number,
     token: TokenDTO
   ) => {
@@ -468,8 +480,8 @@ function POSScreen() {
       amount,
       contractAddress: token.contractAddress,
       chainId: token.chainId,
-      userAccountId,      // User sending tokens
-      businessAccountId   // Business receiving & authorized to submit
+      userId,      // User sending tokens
+      businessId   // Business receiving & authorized to submit
     });
     
     // Create and sign transaction
@@ -653,7 +665,93 @@ function BlockchainRedemption() {
   );
 }
 ```
+### Error Handling
+
+The SDK provides comprehensive structured error handling with utilities for consistent error management:
+
+```typescript
+import { 
+  PersApiError, 
+  ErrorUtils 
+} from '@explorins/pers-sdk-react-native';
+import { Alert } from 'react-native';
+
+// Structured error handling
+try {
+  await sdk.campaigns.claimCampaign({ campaignId });
+} catch (error) {
+  if (error instanceof PersApiError) {
+    // Structured error with backend details
+    console.log('Error code:', error.code);        // 'CAMPAIGN_BUSINESS_REQUIRED'
+    console.log('Status:', error.status);          // 400
+    console.log('User message:', error.userMessage); // User-friendly message
+    
+    // Show user-friendly error
+    Alert.alert('Error', error.userMessage || error.message);
+    
+    // Check if retryable
+    if (error.retryable) {
+      Alert.alert('Error', error.message, [
+        { text: 'Cancel' },
+        { text: 'Retry', onPress: () => retry() }
+      ]);
+    }
+  } else {
+    // Generic error fallback with ErrorUtils
+    const message = ErrorUtils.getMessage(error);
+    Alert.alert('Error', message);
+  }
+}
+
+// Error utilities for any error type
+const status = ErrorUtils.getStatus(error);         // Extract HTTP status
+const message = ErrorUtils.getMessage(error);       // Extract user message
+const retryable = ErrorUtils.isRetryable(error);    // Check if retryable
+const tokenExpired = ErrorUtils.isTokenExpiredError(error); // Detect token expiration
+```
+
+### Transaction Helpers
 
+**NEW in v2.1.1:** Factory functions for client-side transaction workflows:
+
+```typescript
+import {
+  ClientTransactionType,
+  buildPendingTransactionData,
+  extractDeadlineFromSigningData,
+  type PendingTransactionParams
+} from '@explorins/pers-sdk-react-native';
+
+// Build pending transaction data for QR codes, NFC, deep links, etc.
+const qrData = buildPendingTransactionData(
+  signingResult.transactionId,
+  signingResult.signature,
+  'EIP-712' // Default format
+);
+
+console.log(qrData);
+// {
+//   transactionId: '...',
+//   signature: '0x...',
+//   transactionFormat: 'EIP-712',
+//   txType: 'PENDING_SUBMISSION'
+// }
+
+// Serialize for transfer (QR code, NFC, etc.)
+const qrCodeValue = JSON.stringify(qrData);
+
+// Extract deadline from EIP-712 signing data
+const deadline = extractDeadlineFromSigningData(signingResult.signingData);
+if (deadline) {
+  const expiryTime = new Date(deadline * 1000);
+  console.log('Transaction expires at:', expiryTime);
+}
+
+// Client transaction types
+if (transaction.txType === ClientTransactionType.PENDING_SUBMISSION) {
+  // Handle pending submission flow
+}
+```
 ## Security Features
 
 ### WebAuthn Authentication
@@ -927,6 +1025,21 @@ const tokens = (await getTokens()).data;
 
 ---
 
+## Documentation
+
+### Core Guides
+- **[AUTH_STATE_HANDLING.md](./docs/AUTH_STATE_HANDLING.md)** - Comprehensive guide for handling authentication state changes
+  - Pattern examples for observing `isAuthenticated` state
+  - Custom UI for session expiration
+  - Platform-specific details (iOS Keychain, Android Keystore, Web)
+  - Best practices for auth state observation
+
+### Setup & Configuration
+- **[REACT_NATIVE_PASSKEY_SETUP.md](./REACT_NATIVE_PASSKEY_SETUP.md)** - Required setup for WebAuthn/Passkey authentication
+- **[DPOP_IMPLEMENTATION_GUIDE.md](./DPOP_IMPLEMENTATION_GUIDE.md)** - DPoP security implementation details
+
+---
+
 ## Contributing
 
 We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

package/dist/hooks/index.d.ts

@@ -1,5 +1,6 @@
 export { useAuth } from './useAuth';
 export { useTokens } from './useTokens';
+export { useTokenBalances } from './useTokenBalances';
 export { useTransactions } from './useTransactions';
 export { useTransactionSigner, SigningStatus } from './useTransactionSigner';
 export { useBusiness } from './useBusiness';
@@ -18,4 +19,5 @@ export type { RawUserData } from './useAuth';
 export type { TransactionSignerHook, SubmissionResult, AuthenticatedUser, TransactionSigningResult, StatusUpdateData, OnStatusUpdateFn, SigningStatus as SigningStatusType } from './useTransactionSigner';
 export type { AccountOwnedTokensResult, Web3Hook } from './useWeb3';
 export type { EventsHook, PersEvent, EventHandler, EventFilter, Unsubscribe } from './useEvents';
+export type { TokenBalanceWithToken, UseTokenBalancesOptions, UseTokenBalancesResult } from './useTokenBalances';
 //# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,IAAI,iBAAiB,EACnC,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,IAAI,iBAAiB,EACnC,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACjG,YAAY,EACV,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,oBAAoB,CAAC"}

package/dist/hooks/index.js

@@ -1,6 +1,7 @@
 // Export all hooks (only hooks, no providers to avoid circular dependency)
 export { useAuth } from './useAuth';
 export { useTokens } from './useTokens';
+export { useTokenBalances } from './useTokenBalances';
 export { useTransactions } from './useTransactions';
 export { useTransactionSigner, SigningStatus } from './useTransactionSigner';
 export { useBusiness } from './useBusiness';

package/dist/hooks/useTokenBalances.d.ts

@@ -0,0 +1,140 @@
+import { type TokenDTO } from '@explorins/pers-shared';
+import type { TokenBalance } from '@explorins/pers-sdk/web3';
+/**
+ * Token balance with associated token information for display
+ *
+ * This composite type combines blockchain balance data with token metadata,
+ * making it easy to display token information in UI components without
+ * needing to join data from multiple sources.
+ */
+export interface TokenBalanceWithToken {
+    /** The balance data from blockchain */
+    tokenBalance: TokenBalance;
+    /** The token definition (contract, symbol, metadata, etc.) */
+    token: TokenDTO;
+    /** Human-readable formatted balance string (e.g., "100 XPL" or "3 stamps") */
+    balanceFormatted: string;
+}
+/**
+ * Configuration options for useTokenBalances hook
+ */
+export interface UseTokenBalancesOptions {
+    /**
+     * Wallet address to check balances for (REQUIRED)
+     * Apps must explicitly provide the wallet address - no automatic selection
+     * Get from: user.wallets[selectedIndex].address
+     */
+    accountAddress: string;
+    /** Available tokens to check balances for (from SDK or filtered list) */
+    availableTokens?: TokenDTO[];
+    /** Whether to automatically load balances on mount/auth/token changes */
+    autoLoad?: boolean;
+    /** Optional refresh interval in milliseconds (0 = disabled) */
+    refreshInterval?: number;
+}
+/**
+ * Token balance loading hook return value
+ */
+export interface UseTokenBalancesResult {
+    /** Array of token balances with formatted display data */
+    tokenBalances: TokenBalanceWithToken[];
+    /** Whether balances are currently loading */
+    isLoading: boolean;
+    /** Error message if loading failed */
+    error: string | null;
+    /** Manually trigger balance refresh */
+    refresh: () => Promise<void>;
+    /** Whether the hook is available (SDK initialized, user authenticated, has wallet) */
+    isAvailable: boolean;
+    /** User's wallet address being queried */
+    userAccountAddress: string | null;
+}
+/**
+ * React hook for loading and managing token balances
+ *
+ * Automatically handles:
+ * - Loading balances for ERC20 (fungible tokens/points)
+ * - Loading collections for ERC721 (unique NFTs/stamps)
+ * - Loading collections for ERC1155 (semi-fungible tokens/rewards)
+ * - Parallel loading with error resilience
+ * - Auto-refresh on authentication or token list changes
+ * - Formatted balance strings for display
+ *
+ * This hook consolidates complex token balance loading logic that would otherwise
+ * need to be duplicated across every app. It handles the differences between
+ * fungible and non-fungible tokens, parallel loading, error handling, and
+ * provides formatted display strings.
+ *
+ * @param options - Configuration options
+ * @returns Token balances state and actions
+ *
+ * @example
+ * **Basic Usage:**
+ * ```typescript
+ * import { useTokenBalances, useTokens, usePersSDK } from '@explorins/pers-sdk-react-native';
+ *
+ * function TokenBalancesScreen() {
+ *   const { user } = usePersSDK();
+ *   const { availableTokens } = useTokens();
+ *
+ *   // App explicitly selects which wallet to use
+ *   const walletAddress = user?.wallets?.[0]?.address;
+ *
+ *   const {
+ *     tokenBalances,
+ *     isLoading,
+ *     error,
+ *     refresh
+ *   } = useTokenBalances({
+ *     accountAddress: walletAddress!,
+ *     availableTokens,
+ *     autoLoad: true
+ *   });
+ *
+ *   if (isLoading) return <Text>Loading balances...</Text>;
+ *   if (error) return <Text>Error: {error}</Text>;
+ *
+ *   return (
+ *     <View>
+ *       {tokenBalances.map(({ token, balanceFormatted }) => (
+ *         <View key={token.id}>
+ *           <Text>{token.name}: {balanceFormatted}</Text>
+ *         </View>
+ *       ))}
+ *       <Button onPress={refresh} title="Refresh" />
+ *     </View>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * **With Auto-Refresh:**
+ * ```typescript
+ * const { tokenBalances, isLoading } = useTokenBalances({
+ *   accountAddress: walletAddress!,
+ *   availableTokens,
+ *   autoLoad: true,
+ *   refreshInterval: 30000 // Refresh every 30 seconds
+ * });
+ * ```
+ *
+ * @example
+ * **Multi-Wallet Support:**
+ * ```typescript
+ * function MultiWalletBalances() {
+ *   const { user } = usePersSDK();
+ *   const [selectedWalletIndex, setSelectedWalletIndex] = useState(0);
+ *
+ *   const walletAddress = user?.wallets?.[selectedWalletIndex]?.address;
+ *
+ *   const { tokenBalances } = useTokenBalances({
+ *     accountAddress: walletAddress!,
+ *     availableTokens
+ *   });
+ *
+ *   // UI lets user switch between wallets
+ * }
+ * ```
+ */
+export declare function useTokenBalances(options: UseTokenBalancesOptions): UseTokenBalancesResult;
+//# sourceMappingURL=useTokenBalances.d.ts.map

package/dist/hooks/useTokenBalances.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTokenBalances.d.ts","sourceRoot":"","sources":["../../src/hooks/useTokenBalances.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,0BAA0B,CAAC;AAElF;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,uCAAuC;IACvC,YAAY,EAAE,YAAY,CAAC;IAC3B,8DAA8D;IAC9D,KAAK,EAAE,QAAQ,CAAC;IAChB,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,eAAe,CAAC,EAAE,QAAQ,EAAE,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,0DAA0D;IAC1D,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uCAAuC;IACvC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,sFAAsF;IACtF,WAAW,EAAE,OAAO,CAAC;IACrB,0CAA0C;IAC1C,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,sBAAsB,CAgJzF"}

package/dist/hooks/useTokenBalances.js

@@ -0,0 +1,213 @@
+import { useCallback, useEffect, useState } from 'react';
+import { usePersSDK } from '../providers/PersSDKProvider';
+import { useWeb3 } from './useWeb3';
+import { NativeTokenTypes } from '@explorins/pers-shared';
+/**
+ * React hook for loading and managing token balances
+ *
+ * Automatically handles:
+ * - Loading balances for ERC20 (fungible tokens/points)
+ * - Loading collections for ERC721 (unique NFTs/stamps)
+ * - Loading collections for ERC1155 (semi-fungible tokens/rewards)
+ * - Parallel loading with error resilience
+ * - Auto-refresh on authentication or token list changes
+ * - Formatted balance strings for display
+ *
+ * This hook consolidates complex token balance loading logic that would otherwise
+ * need to be duplicated across every app. It handles the differences between
+ * fungible and non-fungible tokens, parallel loading, error handling, and
+ * provides formatted display strings.
+ *
+ * @param options - Configuration options
+ * @returns Token balances state and actions
+ *
+ * @example
+ * **Basic Usage:**
+ * ```typescript
+ * import { useTokenBalances, useTokens, usePersSDK } from '@explorins/pers-sdk-react-native';
+ *
+ * function TokenBalancesScreen() {
+ *   const { user } = usePersSDK();
+ *   const { availableTokens } = useTokens();
+ *
+ *   // App explicitly selects which wallet to use
+ *   const walletAddress = user?.wallets?.[0]?.address;
+ *
+ *   const {
+ *     tokenBalances,
+ *     isLoading,
+ *     error,
+ *     refresh
+ *   } = useTokenBalances({
+ *     accountAddress: walletAddress!,
+ *     availableTokens,
+ *     autoLoad: true
+ *   });
+ *
+ *   if (isLoading) return <Text>Loading balances...</Text>;
+ *   if (error) return <Text>Error: {error}</Text>;
+ *
+ *   return (
+ *     <View>
+ *       {tokenBalances.map(({ token, balanceFormatted }) => (
+ *         <View key={token.id}>
+ *           <Text>{token.name}: {balanceFormatted}</Text>
+ *         </View>
+ *       ))}
+ *       <Button onPress={refresh} title="Refresh" />
+ *     </View>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * **With Auto-Refresh:**
+ * ```typescript
+ * const { tokenBalances, isLoading } = useTokenBalances({
+ *   accountAddress: walletAddress!,
+ *   availableTokens,
+ *   autoLoad: true,
+ *   refreshInterval: 30000 // Refresh every 30 seconds
+ * });
+ * ```
+ *
+ * @example
+ * **Multi-Wallet Support:**
+ * ```typescript
+ * function MultiWalletBalances() {
+ *   const { user } = usePersSDK();
+ *   const [selectedWalletIndex, setSelectedWalletIndex] = useState(0);
+ *
+ *   const walletAddress = user?.wallets?.[selectedWalletIndex]?.address;
+ *
+ *   const { tokenBalances } = useTokenBalances({
+ *     accountAddress: walletAddress!,
+ *     availableTokens
+ *   });
+ *
+ *   // UI lets user switch between wallets
+ * }
+ * ```
+ */
+export function useTokenBalances(options) {
+    const { accountAddress, availableTokens = [], autoLoad = true, refreshInterval = 0 } = options;
+    const { isAuthenticated } = usePersSDK();
+    const web3 = useWeb3();
+    const [tokenBalances, setTokenBalances] = useState([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    // Check if the hook is available for use
+    const isAvailable = web3.isAvailable && isAuthenticated && !!accountAddress;
+    /**
+     * Process balance for ERC20 fungible tokens (points/credits)
+     */
+    const processPointsBalance = useCallback(async (token) => {
+        if (!web3.getTokenBalance || !accountAddress)
+            return null;
+        try {
+            const request = {
+                accountAddress,
+                contractAddress: token.contractAddress,
+                abi: token.abi,
+                tokenId: '',
+                chainId: token.chainId
+            };
+            const balanceResult = await web3.getTokenBalance(request);
+            if (!balanceResult || !balanceResult.hasBalance)
+                return null;
+            return {
+                tokenBalance: balanceResult,
+                token,
+                balanceFormatted: `${balanceResult.balance} ${token.symbol || 'tokens'}`
+            };
+        }
+        catch (err) {
+            console.warn(`[useTokenBalances] Failed to load balance for ${token.symbol}:`, err);
+            return null;
+        }
+    }, [web3.getTokenBalance, accountAddress]);
+    /**
+     * Process collection for ERC721/ERC1155 non-fungible tokens (stamps/rewards)
+     */
+    const processRewardsBalance = useCallback(async (token) => {
+        if (!web3.getAccountOwnedTokensFromContract || !accountAddress)
+            return [];
+        try {
+            const result = await web3.getAccountOwnedTokensFromContract(accountAddress, token);
+            if (result.totalOwned === 0)
+                return [];
+            const balanceUnit = token.type === NativeTokenTypes.ERC1155 ? 'reward' : 'stamp';
+            // Return one item per tokenId (for individual display in lists)
+            return result.ownedTokens.map(ownedToken => ({
+                tokenBalance: ownedToken,
+                token,
+                balanceFormatted: `${ownedToken.balance} ${balanceUnit}${ownedToken.balance !== 1 ? 's' : ''}`
+            }));
+        }
+        catch (err) {
+            console.warn(`[useTokenBalances] Failed to load collection for ${token.symbol}:`, err);
+            return [];
+        }
+    }, [web3.getAccountOwnedTokensFromContract, accountAddress]);
+    /**
+     * Load all token balances
+     */
+    const loadBalances = useCallback(async () => {
+        if (!isAvailable || availableTokens.length === 0) {
+            return;
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            // Split by category: points (fungible credits) vs rewards (stamps/collectibles)
+            const points = availableTokens.filter(t => t.type === NativeTokenTypes.ERC20);
+            const rewards = availableTokens.filter(t => t.type === NativeTokenTypes.ERC721 || t.type === NativeTokenTypes.ERC1155);
+            // Load all balances in parallel (individual errors handled per-token)
+            const [pointsResults, rewardsResults] = await Promise.all([
+                Promise.all(points.map(processPointsBalance)),
+                Promise.all(rewards.map(processRewardsBalance))
+            ]);
+            // Combine results, filtering out nulls (failed loads return null/empty)
+            const allBalances = [
+                ...pointsResults.filter(Boolean),
+                ...rewardsResults.flat()
+            ];
+            setTokenBalances(allBalances);
+            // Set error only if no balances loaded at all
+            if (allBalances.length === 0 && availableTokens.length > 0) {
+                setError('No token balances could be loaded');
+            }
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : 'Failed to load balances';
+            setError(errorMessage);
+            console.error('[useTokenBalances] Error loading balances:', err);
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [isAvailable, availableTokens, processPointsBalance, processRewardsBalance]);
+    // Auto-load balances when dependencies change
+    useEffect(() => {
+        if (autoLoad && isAvailable && availableTokens.length > 0) {
+            loadBalances();
+        }
+    }, [autoLoad, isAvailable, availableTokens.length, loadBalances]);
+    // Optional auto-refresh interval
+    useEffect(() => {
+        if (refreshInterval > 0 && isAvailable && availableTokens.length > 0) {
+            const intervalId = setInterval(() => {
+                loadBalances();
+            }, refreshInterval);
+            return () => clearInterval(intervalId);
+        }
+    }, [refreshInterval, isAvailable, availableTokens.length, loadBalances]);
+    return {
+        tokenBalances,
+        isLoading,
+        error,
+        refresh: loadBalances,
+        isAvailable,
+        userAccountAddress: accountAddress
+    };
+}

package/dist/hooks/useWeb3.d.ts

@@ -1,8 +1,7 @@
-import type { TokenBalance, TokenBalanceRequest, TokenCollectionRequest, TokenCollection, TokenMetadata } from '@explorins/pers-sdk/web3';
+import type { TokenBalance, TokenBalanceRequest, TokenCollectionRequest, TokenCollection, TokenMetadata, AccountOwnedTokensResult } from '@explorins/pers-sdk/web3';
 import type { ChainData } from '@explorins/pers-sdk/web3-chain';
 import type { TokenDTO } from '@explorins/pers-shared';
-import type { AccountOwnedTokensResult } from '@explorins/pers-sdk';
-export type { AccountOwnedTokensResult } from '@explorins/pers-sdk';
+export type { AccountOwnedTokensResult } from '@explorins/pers-sdk/web3';
 /**
  * React hook for Web3 operations in the PERS SDK
  *

package/dist/hooks/useWeb3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useWeb3.d.ts","sourceRoot":"","sources":["../../src/hooks/useWeb3.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,aAAa,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAGpE,YAAY,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,OAAO;+BA0BkC,mBAAmB,KAAG,QAAQ,YAAY,CAAC;gCAiC1C,mBAAmB,KAAG,QAAQ,aAAa,GAAG,IAAI,CAAC;kCAcjD,sBAAsB,KAAG,QAAQ,eAAe,CAAC;0BAczD,MAAM,WAAW,MAAM,KAAG,QAAQ,MAAM,CAAC;wCAc3B,MAAM,WAAW,MAAM,KAAG,QAAQ,aAAa,GAAG,IAAI,CAAC;gCAc/D,MAAM,KAAG,QAAQ,SAAS,GAAG,IAAI,CAAC;8BAcpC,MAAM,WAAW,MAAM,QAAQ,SAAS,GAAG,IAAI,KAAG,QAAQ,MAAM,CAAC;6BAiCxE,QAAQ,KAAG,MAAM,EAAE,GAAG,SAAS;wDAuCzD,MAAM,SACf,QAAQ,cACJ,MAAM,KAChB,QAAQ,wBAAwB,CAAC;6CAqBlB,MAAM,SACf,QAAQ,cACJ,MAAM,KAChB,sBAAsB;;CAqB1B,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC"}
+{"version":3,"file":"useWeb3.d.ts","sourceRoot":"","sources":["../../src/hooks/useWeb3.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,aAAa,EACb,wBAAwB,EACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGvD,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,OAAO;+BAmCkC,mBAAmB,KAAG,QAAQ,YAAY,CAAC;gCAiC1C,mBAAmB,KAAG,QAAQ,aAAa,GAAG,IAAI,CAAC;kCAcjD,sBAAsB,KAAG,QAAQ,eAAe,CAAC;0BAczD,MAAM,WAAW,MAAM,KAAG,QAAQ,MAAM,CAAC;wCAc3B,MAAM,WAAW,MAAM,KAAG,QAAQ,aAAa,GAAG,IAAI,CAAC;gCAc/D,MAAM,KAAG,QAAQ,SAAS,GAAG,IAAI,CAAC;8BAcpC,MAAM,WAAW,MAAM,QAAQ,SAAS,GAAG,IAAI,KAAG,QAAQ,MAAM,CAAC;6BAiCxE,QAAQ,KAAG,MAAM,EAAE,GAAG,SAAS;wDAuCzD,MAAM,SACf,QAAQ,cACJ,MAAM,KAChB,QAAQ,wBAAwB,CAAC;6CAqBlB,MAAM,SACf,QAAQ,cACJ,MAAM,KAChB,sBAAsB;;CAqB1B,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC"}