@explorins/pers-sdk-react-native 2.0.4 → 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,CA+IA,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

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext, useState, useCallback, useRef, useEffect, useMemo } from 'react';
-import { Platform } from 'react-native';
+import { Platform, AppState } from 'react-native';
 import { PersSDK } from '@explorins/pers-sdk/core';
 import { ReactNativeHttpClient } from './react-native-http-client';
 import { createReactNativeAuthProvider } from './react-native-auth-provider';
@@ -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.');
@@ -93,6 +112,75 @@ export const PersSDKProvider = ({ children, config }) => {
             throw error;
         }
     }, [sdk, isAuthenticated, isInitialized]);
+    // Listen for authentication status changes and refresh user data when tokens are renewed
+    useEffect(() => {
+        if (!authProvider || !isInitialized)
+            return;
+        // Access the config object with proper type safety
+        const providerConfig = authProvider.config;
+        if (!providerConfig)
+            return;
+        // Set up auth status change handler
+        const originalHandler = providerConfig.onAuthStatusChange;
+        const authStatusHandler = async (status) => {
+            console.log('[PersSDK] Auth status changed:', status);
+            // Call original handler first if it exists
+            if (originalHandler) {
+                await originalHandler(status);
+            }
+            // If token was refreshed successfully and user is authenticated, reload user data
+            if (status === 'authenticated' && isAuthenticated && sdk) {
+                try {
+                    console.log('[PersSDK] Token refreshed, reloading user data...');
+                    await refreshUserData();
+                }
+                catch (error) {
+                    console.error('[PersSDK] Failed to refresh user data after token renewal:', error);
+                }
+            }
+            // 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 - 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);
+            }
+        };
+        // Inject our handler into the auth provider config
+        providerConfig.onAuthStatusChange = authStatusHandler;
+        // Cleanup
+        return () => {
+            if (originalHandler) {
+                providerConfig.onAuthStatusChange = originalHandler;
+            }
+        };
+    }, [authProvider, isInitialized, isAuthenticated, sdk, refreshUserData, setAuthenticationState]);
+    // iOS/Android: Monitor app state and validate tokens when app becomes active
+    useEffect(() => {
+        if (!sdk || Platform.OS === 'web') {
+            return;
+        }
+        const handleAppStateChange = async (nextAppState) => {
+            if (nextAppState === 'active' && isAuthenticated) {
+                console.log('[PersSDK] App became active - validating tokens');
+                try {
+                    // Trigger token validation when app resumes from background
+                    // This ensures tokens are checked after extended inactivity
+                    await sdk.auth.ensureValidToken();
+                }
+                catch (error) {
+                    console.warn('[PersSDK] Token validation failed on app resume:', error);
+                }
+            }
+        };
+        const subscription = AppState.addEventListener('change', handleAppStateChange);
+        return () => {
+            subscription?.remove();
+        };
+    }, [sdk, isAuthenticated]);
     const contextValue = useMemo(() => ({
         // Main SDK instance
         sdk,

package/dist/storage/async-storage-token-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async-storage-token-storage.d.ts","sourceRoot":"","sources":["../../src/storage/async-storage-token-storage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AA8D7D;;;;;GAKG;AACH,qBAAa,wBAAyB,YAAW,YAAY;IAC3D,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAA8B;gBAEtC,SAAS,GAAE,MAAuB;IAexC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IASxC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAY7B"}
+{"version":3,"file":"async-storage-token-storage.d.ts","sourceRoot":"","sources":["../../src/storage/async-storage-token-storage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AA8D7D;;;;;GAKG;AACH,qBAAa,wBAAyB,YAAW,YAAY;IAC3D,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAA8B;gBAEtC,SAAS,GAAE,MAAuB;IAexC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAYxC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAgB7B"}

package/dist/storage/async-storage-token-storage.js

@@ -74,19 +74,24 @@ export class AsyncStorageTokenStorage {
     }
     async set(key, value) {
         try {
-            await this.asyncStorage.setItem(`${this.keyPrefix}${key}`, value);
+            const fullKey = `${this.keyPrefix}${key}`;
+            await this.asyncStorage.setItem(fullKey, value);
+            console.log(`[AsyncStorage] Token stored: ${key}`);
         }
         catch (error) {
-            console.error(`Failed to store token ${key}:`, error);
+            console.error(`[AsyncStorage] Failed to store token ${key}:`, error);
             throw new Error(`Token storage failed: ${error}`);
         }
     }
     async get(key) {
         try {
-            return await this.asyncStorage.getItem(`${this.keyPrefix}${key}`);
+            const fullKey = `${this.keyPrefix}${key}`;
+            const value = await this.asyncStorage.getItem(fullKey);
+            console.log(`[AsyncStorage] Token retrieved: ${key} - ${value ? 'exists' : 'null'}`);
+            return value;
         }
         catch (error) {
-            console.error(`Failed to retrieve token ${key}:`, error);
+            console.error(`[AsyncStorage] Failed to retrieve token ${key}:`, error);
             return null;
         }
     }
@@ -103,11 +108,16 @@ export class AsyncStorageTokenStorage {
             const allKeys = await this.asyncStorage.getAllKeys();
             const ourKeys = allKeys.filter(key => key.startsWith(this.keyPrefix));
             if (ourKeys.length > 0) {
+                console.log(`[AsyncStorage] Clearing ${ourKeys.length} token(s):`, ourKeys);
                 await this.asyncStorage.multiRemove(ourKeys);
+                console.log('[AsyncStorage] All tokens cleared successfully');
+            }
+            else {
+                console.log('[AsyncStorage] No tokens to clear');
             }
         }
         catch (error) {
-            console.error('Failed to clear token storage:', error);
+            console.error('[AsyncStorage] Failed to clear token storage:', error);
         }
     }
 }

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.4",
+  "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.5",
-    "@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
+  };
+}