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

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,
@@ -265,11 +266,14 @@ export {
 } from './hooks';
 
 // Re-export signing status types for convenience
-export type { OnStatusUpdateFn, StatusUpdateData, SigningStatusType } from './hooks';
+export type { OnStatusUpdateFn, StatusUpdateData, SigningStatusType, TransactionSigningResult, SubmissionResult, AuthenticatedUser } from './hooks';
 
 // 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

@@ -132,6 +132,11 @@ 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) {
@@ -141,11 +146,6 @@ export const PersSDKProvider: React.FC<{
     }
   }, [config, isInitialized, initialize]);
 
-  const setAuthenticationState = useCallback((user: UserDTO | AdminDTO | null, isAuthenticated: boolean) => {
-    setUser(user);
-    setIsAuthenticated(isAuthenticated);
-  }, []);
-
   const refreshUserData = useCallback(async (): Promise<void> => {
     if (!sdk || !isAuthenticated || !isInitialized) {
       throw new Error('SDK not initialized or not authenticated. Cannot refresh user data.');
@@ -159,53 +159,38 @@ export const PersSDKProvider: React.FC<{
       throw error;
     }
   }, [sdk, isAuthenticated, isInitialized]);
-
-  // Listen for authentication status changes and refresh user data when tokens are renewed
+  // Listen for authentication events from core SDK
+  // Set up immediately when SDK is created (don't wait for isInitialized)
+  // to catch session_restored events that fire during SDK initialization
   useEffect(() => {
-    if (!authProvider || !isInitialized) return;
+    if (!sdk) return;
 
-    // Access the config object with proper type safety
-    const providerConfig = (authProvider as any).config;
-    if (!providerConfig) return;
+    const unsubscribe = sdk.events.subscribe((event) => {
+      if (event.domain !== 'authentication') 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);
+      // Session restored successfully - sync React state
+      if (event.type === 'session_restored') {
+        console.log('[PersSDK] Session restoration event received, syncing state...');
+        sdk.users.getCurrentUser()
+          .then(userData => {
+            setAuthenticationState(userData, true);
+          })
+          .catch(error => {
+            console.error('[PersSDK] Failed to sync restored session:', error);
+          });
       }
-      
-      // 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
-      if (status === 'auth_failed') {
-        console.log('[PersSDK] Authentication failed, clearing state');
+
+      // Session restoration failed or auth error - clear React state
+      if (event.type === 'session_restoration_failed' || event.code === 'AUTH_FAILED') {
+        console.log('[PersSDK] Authentication failed - clearing session');
         setAuthenticationState(null, false);
       }
-    };
-    
-    // Inject our handler into the auth provider config
-    providerConfig.onAuthStatusChange = authStatusHandler;
-    
-    // Cleanup
+    }, { domains: ['authentication'] });
+
     return () => {
-      if (originalHandler) {
-        providerConfig.onAuthStatusChange = originalHandler;
-      }
+      unsubscribe();
     };
-  }, [authProvider, isInitialized, isAuthenticated, sdk, refreshUserData, setAuthenticationState]);
+  }, [sdk, setAuthenticationState]);
 
   // iOS/Android: Monitor app state and validate tokens when app becomes active
   useEffect(() => {

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