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

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,
   };
 };
 

package/src/index.ts

@@ -247,6 +247,7 @@ export {
 export {
   useAuth,
   useTokens,
+  useTokenBalances,
   useTransactions,
   useTransactionSigner,
   SigningStatus,
@@ -270,6 +271,9 @@ export type { OnStatusUpdateFn, StatusUpdateData, SigningStatusType } from './ho
 // Re-export event types for convenience
 export type { EventsHook, PersEvent, EventHandler, EventFilter, Unsubscribe } from './hooks';
 
+// Re-export token balance types for convenience
+export type { TokenBalanceWithToken, UseTokenBalancesOptions, UseTokenBalancesResult } from './hooks';
+
 // ==============================================================================
 // PLATFORM ADAPTERS
 // ==============================================================================
@@ -420,31 +424,108 @@ export {
   buildTransferRequest,
   buildPOSTransferRequest,
   buildPOSBurnRequest,
-  buildSubmissionRequest
+  buildSubmissionRequest,
+  ClientTransactionType,
+  extractDeadlineFromSigningData,
+  buildPendingTransactionData
 } from '@explorins/pers-sdk/transaction';
 
-export type { POSAuthorizationOptions } from '@explorins/pers-sdk/transaction';
+export type { POSAuthorizationOptions, PendingTransactionParams } from '@explorins/pers-sdk/transaction';
 
 // ==============================================================================
 // ERROR CLASSES (for instanceof checks)
 // ==============================================================================
 
 /**
- * SDK Error classes for type checking in catch blocks
+ * Structured error handling for PERS SDK
+ * 
+ * The SDK provides comprehensive error classes and utilities for consistent error handling
+ * across all operations. Errors follow the StructuredError pattern from @explorins/pers-shared.
+ * 
+ * **Error Classes:**
+ * - `PersApiError` - API errors with structured backend details
+ * - `AuthenticationError` - Authentication/authorization failures (401)
+ * 
+ * **Error Utilities:**
+ * - `ErrorUtils.getMessage(error)` - Extract user-friendly message
+ * - `ErrorUtils.getStatus(error)` - Get HTTP status code
+ * - `ErrorUtils.isRetryable(error)` - Check if operation should be retried
+ * - `ErrorUtils.isTokenExpiredError(error)` - Detect token expiration
  * 
  * @example
+ * **Basic Error Handling:**
  * ```typescript
- * import { PersApiError } from '@explorins/pers-sdk-react-native';
+ * import { PersApiError, ErrorUtils } from '@explorins/pers-sdk-react-native';
  * 
  * try {
  *   await sdk.campaigns.claimCampaign({ campaignId });
  * } catch (error) {
  *   if (error instanceof PersApiError) {
- *     console.log(error.message);  // Clean backend message
- *     console.log(error.code);     // e.g., 'CAMPAIGN_BUSINESS_REQUIRED'
- *     console.log(error.status);   // e.g., 400
+ *     // Structured error with backend details
+ *     console.log('Error code:', error.code);        // 'CAMPAIGN_BUSINESS_REQUIRED'
+ *     console.log('Status:', error.status);          // 400
+ *     console.log('Message:', error.message);        // Backend error message
+ *     console.log('User message:', error.userMessage); // User-friendly message
+ *     console.log('Retryable:', error.retryable);    // false
+ *   } else {
+ *     // Generic error fallback
+ *     const message = ErrorUtils.getMessage(error);
+ *     console.error('Operation failed:', message);
  *   }
  * }
  * ```
+ * 
+ * @example
+ * **Error Utilities:**
+ * ```typescript
+ * import { ErrorUtils } from '@explorins/pers-sdk-react-native';
+ * 
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   const status = ErrorUtils.getStatus(error);      // Extract status code
+ *   const message = ErrorUtils.getMessage(error);    // Extract message
+ *   const retryable = ErrorUtils.isRetryable(error); // Check if retryable
+ *   
+ *   if (ErrorUtils.isTokenExpiredError(error)) {
+ *     // Handle token expiration
+ *     await refreshToken();
+ *   } else if (retryable) {
+ *     // Retry operation
+ *     await retry(someOperation);
+ *   } else {
+ *     // Show error to user
+ *     showError(message);
+ *   }
+ * }
+ * ```
+ * 
+ * @example
+ * **React Native Error Display:**
+ * ```typescript
+ * import { PersApiError, ErrorUtils } from '@explorins/pers-sdk-react-native';
+ * import { Alert } from 'react-native';
+ * 
+ * const handleError = (error: unknown) => {
+ *   if (error instanceof PersApiError) {
+ *     // Show structured error
+ *     Alert.alert(
+ *       'Error',
+ *       error.userMessage || error.message,
+ *       [
+ *         { text: 'OK' },
+ *         error.retryable && { text: 'Retry', onPress: retry }
+ *       ].filter(Boolean)
+ *     );
+ *   } else {
+ *     // Show generic error
+ *     Alert.alert('Error', ErrorUtils.getMessage(error));
+ *   }
+ * };
+ * ```
  */
-export { PersApiError, AuthenticationError } from '@explorins/pers-sdk/core';
+export { 
+  PersApiError, 
+  AuthenticationError,
+  ErrorUtils 
+} from '@explorins/pers-sdk/core';

package/src/providers/PersSDKProvider.tsx

@@ -1,5 +1,5 @@
 import React, { createContext, useContext, useState, ReactNode, useCallback, useRef, useEffect, useMemo } from 'react';
-import { Platform } from 'react-native';
+import { Platform, AppState, AppStateStatus } from 'react-native';
 import { PersSDK, PersConfig, DefaultAuthProvider } from '@explorins/pers-sdk/core';
 import { ReactNativeHttpClient } from './react-native-http-client';
 import { createReactNativeAuthProvider } from './react-native-auth-provider';
@@ -132,19 +132,37 @@ export const PersSDKProvider: React.FC<{
     }
   }, [isInitialized]);
 
+  const setAuthenticationState = useCallback((user: UserDTO | AdminDTO | null, isAuthenticated: boolean) => {
+    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: UserDTO | AdminDTO | null, isAuthenticated: boolean) => {
-    setUser(user);
-    setIsAuthenticated(isAuthenticated);
-  }, []);
+  }, [config, isInitialized, initialize, authProvider, sdk, setAuthenticationState]);
 
   const refreshUserData = useCallback(async (): Promise<void> => {
     if (!sdk || !isAuthenticated || !isInitialized) {
@@ -160,6 +178,86 @@ export const PersSDKProvider: React.FC<{
     }
   }, [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 as any).config;
+    if (!providerConfig) return;
+
+    // Set up auth status change handler
+    const originalHandler = providerConfig.onAuthStatusChange;
+    
+    const authStatusHandler = async (status: string) => {
+      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: AppStateStatus) => {
+      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: PersSDKContext = useMemo(() => ({
     // Main SDK instance
     sdk,

package/src/storage/async-storage-token-storage.ts

@@ -94,18 +94,23 @@ export class AsyncStorageTokenStorage implements TokenStorage {
 
   async set(key: string, value: string): Promise<void> {
     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: string): Promise<string | null> {
     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;
     }
   }
@@ -124,10 +129,14 @@ export class AsyncStorageTokenStorage implements TokenStorage {
       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/src/storage/rn-secure-storage.ts

@@ -117,22 +117,39 @@ export class ReactNativeSecureStorage implements TokenStorage {
   }
 
   async clear(): Promise<void> {
-    // Clear all known secure keys
+    const clearPromises: Promise<void>[] = [];
+    
+    // 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) });
-         }
-       } catch (e) {
-         console.warn(`[ReactNativeSecureStorage] Failed to clear keychain key ${key}`, e);
-       }
+      clearPromises.push(
+        (async () => {
+          try {
+            if (Keychain) {
+              await Keychain.resetGenericPassword({ service: this.getKeyName(key) });
+            }
+          } 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);
     }
   }