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

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

@@ -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) {
@@ -190,8 +208,15 @@ export const PersSDKProvider: React.FC<{
       }
       
       // 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/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);
     }
   }