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

package/dist/providers/PersSDKProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PersSDKProvider.d.ts","sourceRoot":"","sources":["../../src/providers/PersSDKProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAuC,SAAS,EAA2C,MAAM,OAAO,CAAC;AAEvH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAIpF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAG3D,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,MAAM,WAAW,cAAc;IAE7B,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAGpB,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,eAAe,GAAG,IAAI,CAAC;IACnC,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAClC,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACtC,YAAY,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAClC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACnC,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAGlC,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAGzC,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC;IAGhC,UAAU,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,sBAAsB,EAAE,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,EAAE,eAAe,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5F,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAMD,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC;IACrC,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB,CAwNA,CAAC;AAGF,eAAO,MAAM,UAAU,QAAO,cAQ7B,CAAC"}
+{"version":3,"file":"PersSDKProvider.d.ts","sourceRoot":"","sources":["../../src/providers/PersSDKProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAuC,SAAS,EAA2C,MAAM,OAAO,CAAC;AAEvH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAIpF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAG3D,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,MAAM,WAAW,cAAc;IAE7B,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAGpB,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,eAAe,GAAG,IAAI,CAAC;IACnC,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAClC,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACtC,YAAY,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAClC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACnC,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAGlC,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAGzC,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC;IAGhC,UAAU,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,sBAAsB,EAAE,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,EAAE,eAAe,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5F,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAMD,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC;IACrC,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB,CAiPA,CAAC;AAGF,eAAO,MAAM,UAAU,QAAO,cAQ7B,CAAC"}

package/dist/providers/PersSDKProvider.js

@@ -68,18 +68,37 @@ export const PersSDKProvider = ({ children, config }) => {
             initializingRef.current = false;
         }
     }, [isInitialized]);
+    const setAuthenticationState = useCallback((user, isAuthenticated) => {
+        setUser(user);
+        setIsAuthenticated(isAuthenticated);
+    }, []);
     // Auto-initialize if config is provided
     useEffect(() => {
         if (config && !isInitialized && !initializingRef.current) {
-            initialize(config).catch(err => {
+            initialize(config).then(async () => {
+                // Validate stored tokens on startup
+                // SDK's initialize() already calls ensureValidToken() which handles expired tokens
+                // This provides an additional safety layer for missing/corrupted tokens
+                if (authProvider && sdk) {
+                    try {
+                        const hasToken = await sdk.auth.hasValidAuth();
+                        if (!hasToken) {
+                            console.log('[PersSDK] No tokens found on startup, ensuring clean state');
+                            await authProvider.clearTokens();
+                            setAuthenticationState(null, false);
+                        }
+                        // Note: Token expiration validation happens automatically in SDK's initialize()
+                        // which calls ensureValidToken() → checks expiration → triggers AUTH_FAILED if needed
+                    }
+                    catch (error) {
+                        console.warn('[PersSDK] Token validation on startup failed:', error);
+                    }
+                }
+            }).catch(err => {
                 console.error('Auto-initialization failed:', err);
             });
         }
-    }, [config, isInitialized, initialize]);
-    const setAuthenticationState = useCallback((user, isAuthenticated) => {
-        setUser(user);
-        setIsAuthenticated(isAuthenticated);
-    }, []);
+    }, [config, isInitialized, initialize, authProvider, sdk, setAuthenticationState]);
     const refreshUserData = useCallback(async () => {
         if (!sdk || !isAuthenticated || !isInitialized) {
             throw new Error('SDK not initialized or not authenticated. Cannot refresh user data.');
@@ -120,8 +139,13 @@ export const PersSDKProvider = ({ children, config }) => {
                 }
             }
             // If authentication failed, clear state
+            // Frontend app can observe isAuthenticated state change to show custom UI
             if (status === 'auth_failed') {
-                console.log('[PersSDK] Authentication failed, clearing state');
+                console.log('[PersSDK] Authentication failed - session expired');
+                // Note: Token clearing already handled by SDK's handleAuthFailure()
+                // which calls authProvider.clearTokens() with robust retry logic
+                // Clear React state to sync with SDK
+                // This triggers re-render, allowing app to show login screen
                 setAuthenticationState(null, false);
             }
         };

package/dist/storage/rn-secure-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rn-secure-storage.d.ts","sourceRoot":"","sources":["../../src/storage/rn-secure-storage.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EAGb,MAAM,0BAA0B,CAAC;AAalC;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,YAAY;IAc/C,OAAO,CAAC,SAAS;IAZ7B,QAAQ,CAAC,eAAe,SAAS;IAGjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAKzB;IAEH,OAAO,CAAC,eAAe,CAA2B;gBAE9B,SAAS,GAAE,MAAuB;IAIhD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B/C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAkCzC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB5B,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,QAAQ;CAOjB"}
+{"version":3,"file":"rn-secure-storage.d.ts","sourceRoot":"","sources":["../../src/storage/rn-secure-storage.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EAGb,MAAM,0BAA0B,CAAC;AAalC;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,YAAY;IAc/C,OAAO,CAAC,SAAS;IAZ7B,QAAQ,CAAC,eAAe,SAAS;IAGjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAKzB;IAEH,OAAO,CAAC,eAAe,CAA2B;gBAE9B,SAAS,GAAE,MAAuB;IAIhD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B/C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAkCzC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqC5B,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,QAAQ;CAOjB"}

package/dist/storage/rn-secure-storage.js

@@ -110,23 +110,37 @@ export class ReactNativeSecureStorage {
         }
     }
     async clear() {
-        // Clear all known secure keys
+        const clearPromises = [];
+        // Clear all known secure keys with retry logic
         for (const key of this.SECURE_KEYS) {
-            try {
-                if (Keychain) {
-                    await Keychain.resetGenericPassword({ service: this.getKeyName(key) });
+            clearPromises.push((async () => {
+                try {
+                    if (Keychain) {
+                        await Keychain.resetGenericPassword({ service: this.getKeyName(key) });
+                    }
                 }
-            }
-            catch (e) {
-                console.warn(`[ReactNativeSecureStorage] Failed to clear keychain key ${key}`, e);
-            }
+                catch (e) {
+                    console.warn(`[ReactNativeSecureStorage] Retry clearing ${key}`);
+                    // Retry once
+                    try {
+                        if (Keychain) {
+                            await Keychain.resetGenericPassword({ service: this.getKeyName(key) });
+                        }
+                    }
+                    catch (retryError) {
+                        console.error(`[ReactNativeSecureStorage] Failed to clear ${key} after retry:`, retryError);
+                    }
+                }
+            })());
         }
-        // Clear AsyncStorage keys related to PERS
+        // Wait for all Keychain clearing to complete (or fail)
+        await Promise.allSettled(clearPromises);
+        // Always clear AsyncStorage fallback
         try {
             await this.fallbackStorage.clear();
         }
         catch (e) {
-            console.warn('[ReactNativeSecureStorage] Failed to clear AsyncStorage', e);
+            console.error('[ReactNativeSecureStorage] Failed to clear AsyncStorage:', e);
         }
     }
     getKeyName(key) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk-react-native",
-  "version": "2.0.5",
+  "version": "2.1.1",
   "description": "React Native SDK for PERS Platform - Tourism Loyalty System with Blockchain Transaction Signing and WebAuthn Authentication",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -37,10 +37,8 @@
   "author": "eXplorins",
   "license": "MIT",
   "dependencies": {
-    "@explorins/pers-sdk": "^2.0.6",
-    "@explorins/pers-shared": "^2.1.64",
+    "@explorins/pers-sdk": "^2.1.1",
     "@explorins/pers-signer": "^1.0.33",
-    "@explorins/web3-ts": "^0.3.77",
     "buffer": "^6.0.3",
     "ethers": "^6.15.0",
     "react-native-get-random-values": "^2.0.0",

package/src/hooks/index.ts

@@ -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';
@@ -28,4 +29,9 @@ export type {
   SigningStatus as SigningStatusType
 } from './useTransactionSigner';
 export type { AccountOwnedTokensResult, Web3Hook } from './useWeb3';
-export type { EventsHook, PersEvent, EventHandler, EventFilter, Unsubscribe } from './useEvents';
+export type { EventsHook, PersEvent, EventHandler, EventFilter, Unsubscribe } from './useEvents';
+export type { 
+  TokenBalanceWithToken, 
+  UseTokenBalancesOptions, 
+  UseTokenBalancesResult 
+} from './useTokenBalances';

package/src/hooks/useTokenBalances.ts

@@ -0,0 +1,290 @@
+import { useCallback, useEffect, useState } from 'react';
+import { usePersSDK } from '../providers/PersSDKProvider';
+import { useWeb3 } from './useWeb3';
+import { NativeTokenTypes, type TokenDTO } from '@explorins/pers-shared';
+import type { TokenBalance, TokenBalanceRequest } 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 function useTokenBalances(options: UseTokenBalancesOptions): UseTokenBalancesResult {
+  const {
+    accountAddress,
+    availableTokens = [],
+    autoLoad = true,
+    refreshInterval = 0
+  } = options;
+
+  const { isAuthenticated } = usePersSDK();
+  const web3 = useWeb3();
+  
+  const [tokenBalances, setTokenBalances] = useState<TokenBalanceWithToken[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(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: TokenDTO): Promise<TokenBalanceWithToken | null> => {
+    if (!web3.getTokenBalance || !accountAddress) return null;
+    
+    try {
+      const request: TokenBalanceRequest = {
+        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: TokenDTO): Promise<TokenBalanceWithToken[]> => {
+    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()
+      ] as TokenBalanceWithToken[];
+      
+      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/src/hooks/useWeb3.ts

@@ -1,18 +1,19 @@
-import { useCallback } from 'react';
+import { useCallback, useMemo } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
+import { Web3Manager } from '@explorins/pers-sdk/web3';
 import type { 
   TokenBalance, 
   TokenBalanceRequest, 
   TokenCollectionRequest, 
   TokenCollection,
-  TokenMetadata
+  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';
 
 // Re-export for convenience
-export type { AccountOwnedTokensResult } from '@explorins/pers-sdk';
+export type { AccountOwnedTokensResult } from '@explorins/pers-sdk/web3';
 
 /**
  * React hook for Web3 operations in the PERS SDK
@@ -71,6 +72,15 @@ export const useWeb3 = () => {
     console.warn('SDK not authenticated. Some web3 operations may fail.');
   }
 
+  /**
+   * Create Web3Manager instance lazily
+   * Web3Manager is now separate from PersSDK since v2.0.11+
+   */
+  const web3 = useMemo(() => {
+    if (!sdk) return null;
+    return new Web3Manager(sdk.api());
+  }, [sdk]);
+
   /**
    * Retrieves token balance for a specific wallet and contract
    * 
@@ -91,18 +101,18 @@ export const useWeb3 = () => {
    * ```
    */
   const getTokenBalance = useCallback(async (request: TokenBalanceRequest): Promise<TokenBalance> => {
-    if (!isInitialized || !sdk) {
+    if (!isInitialized || !web3) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.web3.getTokenBalance(request);
+      const result = await web3.getTokenBalance(request);
       return result;
     } catch (error) {
       console.error('Failed to fetch token balance:', error);
       throw error;
     }
-  }, [sdk, isInitialized]);
+  }, [web3, isInitialized]);
 
   /**
    * Retrieves metadata for a specific token (useful for NFTs)
@@ -124,88 +134,88 @@ export const useWeb3 = () => {
    * ```
    */
   const getTokenMetadata = useCallback(async (request: TokenBalanceRequest): Promise<TokenMetadata | null> => {
-    if (!isInitialized || !sdk) {
+    if (!isInitialized || !web3) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.web3.getTokenMetadata(request);
+      const result = await web3.getTokenMetadata(request);
       return result;
     } catch (error) {
       console.error('Failed to fetch token metadata:', error);
       throw error;
     }
-  }, [sdk, isInitialized]);
+  }, [web3, isInitialized]);
 
   const getTokenCollection = useCallback(async (request: TokenCollectionRequest): Promise<TokenCollection> => {
-    if (!isInitialized || !sdk) {
+    if (!isInitialized || !web3) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.web3.getTokenCollection(request);
+      const result = await web3.getTokenCollection(request);
       return result;
     } catch (error) {
       console.error('Failed to fetch token collection:', error);
       throw error;
     }
-  }, [sdk, isInitialized]);
+  }, [web3, isInitialized]);
 
   const resolveIPFSUrl = useCallback(async (url: string, chainId: number): Promise<string> => {
-    if (!isInitialized || !sdk) {
+    if (!isInitialized || !web3) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.web3.resolveIPFSUrl(url, chainId);
+      const result = await web3.resolveIPFSUrl(url, chainId);
       return result;
     } catch (error) {
       console.error('Failed to resolve IPFS URL:', error);
       throw error;
     }
-  }, [sdk, isInitialized]);
+  }, [web3, isInitialized]);
 
   const fetchAndProcessMetadata = useCallback(async (tokenUri: string, chainId: number): Promise<TokenMetadata | null> => {
-    if (!isInitialized || !sdk) {
+    if (!isInitialized || !web3) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.web3.fetchAndProcessMetadata(tokenUri, chainId);
+      const result = await web3.fetchAndProcessMetadata(tokenUri, chainId);
       return result;
     } catch (error) {
       console.error('Failed to fetch and process metadata:', error);
       throw error;
     }
-  }, [sdk, isInitialized]);
+  }, [web3, isInitialized]);
 
   const getChainDataById = useCallback(async (chainId: number): Promise<ChainData | null> => {
-    if (!isInitialized || !sdk) {
+    if (!isInitialized || !web3) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.web3.getChainDataById(chainId);
+      const result = await web3.getChainDataById(chainId);
       return result;
     } catch (error) {
       console.error('Failed to fetch chain data:', error);
       throw error;
     }
-  }, [sdk, isInitialized]);
+  }, [web3, isInitialized]);
 
   const getExplorerUrl = useCallback(async (chainId: number, address: string, type: 'address' | 'tx'): Promise<string> => {
-    if (!isInitialized || !sdk) {
+    if (!isInitialized || !web3) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.web3.getExplorerUrl(chainId, address, type);
+      const result = await web3.getExplorerUrl(chainId, address, type);
       return result;
     } catch (error) {
       console.error('Failed to generate explorer URL:', error);
       throw error;
     }
-  }, [sdk, isInitialized]);
+  }, [web3, isInitialized]);
 
   // ==========================================
   // HELPER METHODS (delegating to core SDK)
@@ -227,9 +237,9 @@ export const useWeb3 = () => {
    * @see {@link getAccountOwnedTokensFromContract} - Recommended helper that handles this automatically
    */
   const extractTokenIds = useCallback((token: TokenDTO): string[] | undefined => {
-    // Pure function - delegates to core SDK (no initialization required)
-    return sdk?.web3.extractTokenIds(token);
-  }, [sdk]);
+    // Pure function - delegates to Web3Manager (no initialization required)
+    return web3?.extractTokenIds(token);
+  }, [web3]);
 
   /**
    * Get owned tokens from a specific token contract for any blockchain address.
@@ -269,12 +279,12 @@ export const useWeb3 = () => {
     token: TokenDTO,
     maxTokens: number = 50
   ): Promise<AccountOwnedTokensResult> => {
-    if (!isInitialized || !sdk) {
+    if (!isInitialized || !web3) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
 
-    return sdk.web3.getAccountOwnedTokensFromContract(accountAddress, token, maxTokens);
-  }, [sdk, isInitialized]);
+    return web3.getAccountOwnedTokensFromContract(accountAddress, token, maxTokens);
+  }, [web3, isInitialized]);
 
   /**
    * Build a TokenCollectionRequest from a TokenDTO.
@@ -293,11 +303,11 @@ export const useWeb3 = () => {
     token: TokenDTO,
     maxTokens: number = 50
   ): TokenCollectionRequest => {
-    if (!sdk) {
+    if (!web3) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
-    return sdk.web3.buildCollectionRequest(accountAddress, token, maxTokens);
-  }, [sdk]);
+    return web3.buildCollectionRequest(accountAddress, token, maxTokens);
+  }, [web3]);
 
   return {
     getTokenBalance,
@@ -311,7 +321,7 @@ export const useWeb3 = () => {
     extractTokenIds,
     getAccountOwnedTokensFromContract,
     buildCollectionRequest,
-    isAvailable: isInitialized && !!sdk?.web3,
+    isAvailable: isInitialized && !!web3,
   };
 };