@explorins/pers-sdk-react-native 1.5.18 → 1.5.20

package/README.md

@@ -1,24 +1,21 @@
 # PERS SDK React Native
 
-A comprehensive React Native SDK for the PERS (Personal Engagement & Reward System) platform, designed specifically for tourism loyalty applications with modern manager pattern architecture.
+A comprehensive React Native SDK for the PERS (Phygital Experience Rewards System) platform, designed specifically for tourism loyalty applications with blockchain transaction signing capabilities.
 
 ## Features
 
-- **🏗️ Modern Manager Pattern**: Clean, intuitive high-level APIs through domain managers
-- **🔐 Authentication Management**: Complete user authentication flow with secure providers
-- **💰 Token Operations**: Balance checking, transfers, and comprehensive token management
-- **📊 Transaction History**: Complete transaction tracking and analytics
-- **🏢 Business Integration**: Business data, types, and operations management
-- **🎯 Campaign Management**: Marketing campaigns, claims, and promotions
-- **🎁 Redemption System**: Comprehensive reward redemption functionality
-- **💳 Purchase Processing**: Payment intents, purchases, and transaction handling
-- **🏢 Tenant Management**: Multi-tenant configuration and admin operations
-- **📈 Analytics**: Transaction analytics and reporting capabilities
-- **💝 Donations**: Donation type and management system
-- **👥 User Management**: User profiles, public data, and admin operations
-- **🌐 Web3 Integration**: Blockchain operations and wallet management
-- **🔒 Secure Storage**: Multiple storage strategies for different security needs
-- **📱 Cross-Platform**: Full React Native support with optimized performance
+- **Secure Authentication**: WebAuthn-based authentication with device biometrics
+- **Blockchain Integration**: Complete transaction signing with PERS Signer SDK supporting EVM-compatible chains (Ethereum, Polygon, Camino, etc.)
+- **Token Operations**: Balance checking, earning, redeeming, and transfers
+- **Business Management**: Business profiles, campaigns, and operations
+- **Campaign System**: Marketing campaigns, participation, and rewards
+- **Redemption Engine**: Comprehensive reward redemption and fulfillment
+- **Analytics**: Real-time analytics and transaction monitoring
+- **Donations**: Charitable giving and donation management
+- **User Management**: Profile management and user operations
+- **Web3 Support**: EVM-compatible chain wallet operations and blockchain interactions
+- **Secure Storage**: Multiple storage strategies with React Native Keychain
+- **React Native Optimized**: Full platform support with automatic polyfills
 
 ## Installation
 
@@ -28,326 +25,431 @@ npm install @explorins/pers-sdk-react-native
 
 ### Required Dependencies
 
-The SDK requires AsyncStorage for persistence:
-
 ```bash
 npm install @react-native-async-storage/async-storage
 ```
 
-### Optional Dependencies
-
-For additional functionality, install these optional packages:
+### Optional Dependencies (Recommended)
 
 ```bash
-# For secure keychain storage (iOS/Android)
+# For secure keychain storage
 npm install react-native-keychain
 
-# For crypto polyfills (recommended for Web3 features)
+# For crypto operations  
 npm install react-native-get-random-values
 
-# For URL polyfills (if needed)
-npm install react-native-url-polyfill
-
-# For global polyfills (if needed)
-npm install react-native-polyfill-globals
+# For blockchain transaction signing
+npm install @explorins/pers-signer
 
-# For stream polyfills (if needed)
-npm install web-streams-polyfill
+# For URL polyfills
+npm install react-native-url-polyfill
 ```
 
 ## Quick Start
 
 ### 1. Setup the Provider
 
-Wrap your app with the `PersSDKProvider`:
-
 ```typescript
 import React from 'react';
 import { PersSDKProvider } from '@explorins/pers-sdk-react-native';
 
 export default function App() {
   return (
-    <PersSDKProvider>
-      {/* Your app components */}
+    <PersSDKProvider config={{
+      apiUrl: 'https://api.pers.ninja',
+      tenantId: 'your-tenant-id' // Optional
+    }}>
+      <NavigationContainer>
+        <YourAppContent />
+      </NavigationContainer>
     </PersSDKProvider>
   );
 }
 ```
 
-### 2. Initialize the SDK
-
-```typescript
-import { useAuth } from '@explorins/pers-sdk-react-native';
-
-function InitializeSDK() {
-  const { initialize, isInitialized } = useAuth();
-
-  useEffect(() => {
-    initialize({
-      apiProjectKey: 'your-project-key',
-      environment: 'production', // or 'development', 'staging'
-    });
-  }, []);
-
-  if (!isInitialized) {
-    return <Text>Initializing...</Text>;
-  }
-
-  return <YourMainComponent />;
-}
-```
-
-### 3. Authentication
+### 2. Authentication & Token Operations
 
 ```typescript
-import { useAuth } from '@explorins/pers-sdk-react-native';
-
-function LoginComponent() {
-  const { login, isAuthenticated, user } = useAuth();
+import { usePersSDK, useTransactionSigner } from '@explorins/pers-sdk-react-native';
+
+function RewardScreen() {
+  const { 
+    user, 
+    isAuthenticated, 
+    login,
+    earnTokens,
+    redeemTokens,
+    getTokenBalance 
+  } = usePersSDK();
+  
+  const { signAndSubmitTransactionWithJWT, isSignerAvailable } = useTransactionSigner();
 
   const handleLogin = async () => {
     try {
       await login('your-jwt-token');
-      console.log('Login successful');
+      console.log('Authenticated:', user?.identifier);
     } catch (error) {
       console.error('Login failed:', error);
     }
   };
 
+  const handleEarnTokens = async () => {
+    try {
+      const result = await earnTokens({
+        amount: 100,
+        source: 'activity_completion',
+        metadata: { activity: 'hotel_checkin' }
+      });
+      console.log('Earned tokens:', result);
+    } catch (error) {
+      console.error('Earn failed:', error);
+    }
+  };
+
+  const handleRedemption = async () => {
+    try {
+      // Step 1: Create redemption
+      const redemption = await redeemTokens({
+        amount: 50,
+        rewardType: 'discount_voucher'
+      });
+      
+      // Step 2: Sign blockchain transaction
+      if (redemption.requiresBlockchainSigning && isSignerAvailable) {
+        const txResult = await signAndSubmitTransactionWithJWT(redemption.jwtToken);
+        
+        if (txResult.success) {
+          console.log('Redemption completed!');
+          console.log('Transaction Hash:', txResult.transactionHash);
+          console.log('View on blockchain explorer: [Chain-specific URL]');
+        }
+      }
+    } catch (error) {
+      console.error('Redemption failed:', error);
+    }
+  };
+
   return (
-    <View>
-      {isAuthenticated ? (
-        <Text>Welcome, {user?.name}</Text>
+    <ScrollView style={styles.container}>
+      {!isAuthenticated ? (
+        <TouchableOpacity onPress={handleLogin} style={styles.loginButton}>
+          <Text style={styles.buttonText}>Login with PERS</Text>
+        </TouchableOpacity>
       ) : (
-        <Button title="Login" onPress={handleLogin} />
+        <View>
+          <Text style={styles.welcome}>Welcome, {user?.identifier}!</Text>
+          
+          <TouchableOpacity onPress={handleEarnTokens} style={styles.button}>
+            <Text style={styles.buttonText}>Earn 100 Tokens</Text>
+          </TouchableOpacity>
+          
+          <TouchableOpacity 
+            onPress={handleRedemption} 
+            disabled={!isSignerAvailable}
+            style={[styles.button, !isSignerAvailable && styles.disabled]}
+          >
+            <Text style={styles.buttonText}>
+              {isSignerAvailable ? 'Redeem Rewards' : 'Signer Loading...'}
+            </Text>
+          </TouchableOpacity>
+        </View>
       )}
-    </View>
+    </ScrollView>
   );
 }
 ```
 
-## Authentication Providers
-
-The SDK provides multiple authentication providers for different security needs:
-
-### BaseReactNativeAuthProvider
-Base class for all React Native authentication providers.
-
-### ReactNativeAuthProvider
-Standard authentication with AsyncStorage for persistence.
-
-```typescript
-import { ReactNativeAuthProvider } from '@explorins/pers-sdk-react-native';
-
-const authProvider = new ReactNativeAuthProvider('your-project-key');
-```
-
-### SecureReactNativeAuthProvider
-Secure keychain storage for sensitive data.
-
-```typescript
-import { SecureReactNativeAuthProvider } from '@explorins/pers-sdk-react-native';
-
-const authProvider = new SecureReactNativeAuthProvider('your-project-key');
-```
-
-## API Reference
-
-### Available Hooks
-
-The SDK provides comprehensive hooks for all PERS platform functionality through modern manager pattern:
-
-#### Core Hooks
-- **useAuth()** - Authentication state and operations (login, logout, user management)
-- **useUsers()** - User profile management and public user data
-- **useTokens()** - Token operations, balances, and credit/reward tokens
+## Core Hooks
 
-#### Business Logic Hooks  
-- **useBusiness()** - Business data, types, and operations management
-- **useCampaigns()** - Marketing campaigns, claims, and promotions
-- **useRedemptions()** - Reward redemption functionality and user redemptions
-- **useTransactions()** - Transaction history, creation, and analytics
-
-#### Platform Integration Hooks
-- **usePurchases()** - Payment intents, purchase tokens, and purchase processing  
-- **useTenants()** - Multi-tenant configuration and admin operations
-- **useWeb3()** - Web3 and blockchain functionality
-
-### Hook Examples
-
-#### useAuth()
-
-Handles authentication state and operations.
+### Authentication & Users
 
 ```typescript
-const {
-  isInitialized,
-  isAuthenticated,
-  user,
-  accountAddress,
-  login,
-  loginWithRawData,
-  logout
+// Authentication management
+const { 
+  isAuthenticated, 
+  user, 
+  login, 
+  logout 
 } = useAuth();
-```
-
-### Storage Strategies
 
-Configure different storage strategies based on your security requirements:
-
-```typescript
-// Available strategies from the auth providers:
-// ASYNC_STORAGE - Default AsyncStorage
-// KEYCHAIN - Secure keychain storage  
-// MEMORY - Memory-only (not persistent)
+// User profile operations  
+const { 
+  getUserProfile,
+  updateUserProfile,
+  getUserPublicData 
+} = useUsers();
 ```
 
-## Advanced Usage
-
-### Custom HTTP Client
+### Token & Financial Operations
 
 ```typescript
-import { ReactNativeHttpClient } from '@explorins/pers-sdk-react-native';
-
-const httpClient = new ReactNativeHttpClient();
+// Token management
+const { 
+  getTokenBalance,
+  earnTokens,
+  redeemTokens,
+  transferTokens
+} = useTokens();
+
+// Transaction history
+const { 
+  getTransactions,
+  getTransactionById,
+  createTransaction
+} = useTransactions();
+
+// 🌟 Blockchain transaction signing
+const { 
+  signAndSubmitTransactionWithJWT,
+  isSignerAvailable,
+  isSignerInitialized
+} = useTransactionSigner();
 ```
 
-### Direct SDK Access
-
-If you need direct access to individual SDKs:
+### Business & Campaign Management
 
 ```typescript
-import { usePersSDK } from '@explorins/pers-sdk-react-native';
-
-function MyComponent() {
-  const { tokens, transactions, business, campaigns, redemptions, web3 } = usePersSDK();
-  
-  // Direct SDK usage available through the provider
-}
+// Business operations
+const { 
+  getBusinessProfile,
+  updateBusinessProfile,
+  getBusinessTypes
+} = useBusiness();
+
+// Campaign management
+const { 
+  getActiveCampaigns,
+  participateInCampaign,
+  claimCampaignReward
+} = useCampaigns();
+
+// Redemption system
+const { 
+  createRedemption,
+  getUserRedemptions,
+  getRedemptionTypes
+} = useRedemptions();
 ```
 
-### Using Core SDK Components
-
-For advanced usage, you can import components from the core SDK:
+### Platform & Analytics
 
 ```typescript
-import { PersApiClient } from '@explorins/pers-sdk/core';
-import { ReactNativeHttpClient } from '@explorins/pers-sdk-react-native';
-
-const httpClient = new ReactNativeHttpClient();
-const apiClient = new PersApiClient('your-project-key', httpClient);
+// Purchase processing
+const { 
+  createPurchase,
+  getUserPurchases,
+  processPayment
+} = usePurchases();
+
+// Multi-tenant support
+const { 
+  getTenantConfig,
+  updateTenantConfig,
+  getTenantAdmins
+} = useTenants();
+
+// Analytics & reporting
+const { 
+  getTransactionAnalytics,
+  getUserAnalytics,
+  getBusinessAnalytics
+} = useAnalytics();
+
+// Web3 & blockchain
+const { 
+  getWalletBalance,
+  createWallet,
+  getTransactionHistory
+} = useWeb3();
 ```
 
-## Error Handling
+## 🔐 EVM Blockchain Transaction Signing
 
-```typescript
-import { useAuth } from '@explorins/pers-sdk-react-native';
+The `useTransactionSigner` hook provides secure EVM blockchain transaction signing:
 
-function MyComponent() {
-  const { login } = useAuth();
+```typescript
+import { useTransactionSigner } from '@explorins/pers-sdk-react-native';
+
+function BlockchainRedemption() {
+  const { 
+    signAndSubmitTransactionWithJWT, 
+    isSignerAvailable,
+    isSignerInitialized 
+  } = useTransactionSigner();
+
+  const handleBlockchainRedemption = async (jwtToken: string) => {
+    if (!isSignerAvailable) {
+      console.error('EVM blockchain signer not available');
+      return;
+    }
 
-  const handleLogin = async () => {
     try {
-      await login('jwt-token');
+      // This handles the complete flow:
+      // 1. User authentication via WebAuthn
+      // 2. Transaction data fetching from PERS backend  
+      // 3. Secure EVM transaction signing using device biometrics
+      // 4. EVM blockchain submission
+      const result = await signAndSubmitTransactionWithJWT(jwtToken);
+      
+      if (result.success) {
+        console.log('🎉 Transaction completed!');
+        console.log('📄 Hash:', result.transactionHash);
+        console.log('🔗 View on blockchain explorer: [Chain-specific URL]');
+        
+        // Handle post-transaction flow
+        if (result.shouldRedirect && result.redirectUrl) {
+          // Navigate to success page or external URL
+          Linking.openURL(result.redirectUrl);
+        }
+      }
     } catch (error) {
-      if (error.code === 'INVALID_TOKEN') {
-        // Handle invalid token
-      } else if (error.code === 'NETWORK_ERROR') {
-        // Handle network issues
+      if (error.message.includes('expired')) {
+        // JWT token expired - redirect to login
+        navigation.navigate('Login');
+      } else if (error.message.includes('cancelled')) {
+        // User cancelled WebAuthn authentication
+        console.log('User cancelled transaction');
       } else {
-        // Handle other errors
+        // Other errors
+        Alert.alert('Transaction Failed', error.message);
       }
     }
   };
-}
-```
-
-## Environment Configuration
 
-```typescript
-const config = {
-  apiProjectKey: 'your-project-key',
-  environment: 'production', // 'development' | 'staging' | 'production'
-  timeout: 30000, // Request timeout in milliseconds
-};
+  // Show loading state while signer initializes
+  if (!isSignerInitialized) {
+    return (
+      <View style={styles.loadingContainer}>
+        <ActivityIndicator size="large" />
+        <Text>Initializing EVM blockchain signer...</Text>
+      </View>
+    );
+  }
 
-await initialize(config);
+  return (
+    <TouchableOpacity 
+      onPress={() => handleBlockchainRedemption(redemptionJWT)}
+      disabled={!isSignerAvailable}
+      style={[styles.button, !isSignerAvailable && styles.disabled]}
+    >
+      <Text style={styles.buttonText}>
+        🔐 Sign & Submit Transaction
+      </Text>
+    </TouchableOpacity>
+  );
+}
 ```
 
-## TypeScript Support
+## 🛡️ Security Features
 
-The SDK is fully typed and provides comprehensive TypeScript support. Import types as needed for your implementation.
+### WebAuthn Authentication
+- Device biometric authentication (fingerprint, face ID, PIN)
+- No passwords or private keys stored locally
+- Secure hardware-backed authentication
 
-#### useTokens()
+### Token Storage
+- React Native Keychain integration for sensitive data
+- Automatic token refresh and expiration handling
+- Multiple storage strategies (AsyncStorage, Keychain, Memory)
 
-Manage token operations and balances.
+### Transaction Security
+- JWT token validation and expiration checking
+- Secure transaction signing without exposing private keys
+- Automatic session management with secure caching
 
-```typescript
-const { getTokens, getActiveCreditToken, getRewardTokens } = useTokens();
+## 📱 Platform Support
 
-// Get all tokens
-const tokens = await getTokens();
+- **iOS**: Full support with Keychain integration
+- **Android**: Full support with Keystore integration  
+- **Expo**: Compatible with Expo managed workflow
+- **Web**: React Native Web compatibility
 
-// Get active credit token
-const creditToken = await getActiveCreditToken();
+## 🔧 Advanced Configuration
 
-// Get reward tokens
-const rewardTokens = await getRewardTokens();
-```
-
-#### usePayments()
-
-Handle payment processing and purchase tokens.
+### Custom Authentication Provider
 
 ```typescript
-const { createPaymentIntent, getActivePurchaseTokens, getAllUserPurchases } = usePayments();
-
-// Create payment intent
-const paymentIntent = await createPaymentIntent(100, 'usd', 'user@example.com', 'Token purchase');
-
-// Get purchase tokens
-const purchaseTokens = await getActivePurchaseTokens();
+import { createReactNativeAuthProvider } from '@explorins/pers-sdk-react-native';
 
-// Get user purchase history
-const userPurchases = await getAllUserPurchases();
+const authProvider = createReactNativeAuthProvider({
+  projectKey: 'your-project-key',
+  storage: 'keychain', // 'asyncStorage' | 'keychain' | 'memory'
+  biometricPrompt: 'Authenticate to access your rewards'
+});
 ```
 
-#### useTenants()
-
-Multi-tenant configuration and management.
+### Error Handling Patterns
 
 ```typescript
-const { getTenantInfo, getClientConfig, getAdmins } = useTenants();
-
-// Get tenant configuration
-const tenantInfo = await getTenantInfo();
+import { usePersSDK } from '@explorins/pers-sdk-react-native';
 
-// Get client configuration
-const clientConfig = await getClientConfig();
+function ErrorHandlingExample() {
+  const { earnTokens } = usePersSDK();
+  const [error, setError] = useState<string | null>(null);
 
-// Get tenant admins (admin only)
-const admins = await getAdmins();
+  const handleEarnWithErrorHandling = async () => {
+    try {
+      setError(null);
+      await earnTokens({ amount: 100, source: 'activity' });
+    } catch (err) {
+      // Handle specific error types
+      if (err.code === 'NETWORK_ERROR') {
+        setError('Network connection required');
+      } else if (err.code === 'INVALID_TOKEN') {
+        setError('Please log in again');
+      } else if (err.code === 'INSUFFICIENT_BALANCE') {
+        setError('Insufficient balance for this operation');
+      } else {
+        setError(err.message || 'An unexpected error occurred');
+      }
+    }
+  };
+}
 ```
 
-## Troubleshooting
-
-### Metro Configuration
-
-If you encounter bundling issues, add polyfill configurations to your `metro.config.js` as needed.
-
-### Polyfill Setup
-
-Add to your root index file:
+## 📊 Analytics Integration
 
 ```typescript
-import 'react-native-get-random-values';
-import 'react-native-url-polyfill/auto';
+import { useAnalytics } from '@explorins/pers-sdk-react-native';
+
+function AnalyticsExample() {
+  const { 
+    getTransactionAnalytics,
+    getUserAnalytics,
+    trackEvent
+  } = useAnalytics();
+
+  const loadAnalytics = async () => {
+    const txAnalytics = await getTransactionAnalytics({
+      dateRange: { start: '2023-01-01', end: '2023-12-31' }
+    });
+    
+    const userAnalytics = await getUserAnalytics();
+    
+    // Track custom events
+    await trackEvent('reward_claimed', {
+      amount: 100,
+      type: 'discount_voucher',
+      timestamp: new Date().toISOString()
+    });
+  };
+}
 ```
 
 ## Contributing
 
-Please read our contributing guidelines before submitting pull requests.
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
 
 ## License
 
-MIT License - see LICENSE file for details.
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- Email: support@explorins.com
+- Documentation: [https://docs.pers.ninja](https://docs.pers.ninja)
+- Issues: [GitHub Issues](https://github.com/eXplorins/pers-sdk/issues)
+
+---
+
+Built with care by [eXplorins](https://explorins.com) for the tourism and loyalty industry.