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

package/src/hooks/useTransactions.ts

@@ -1,9 +1,11 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
+import { useTransactionSigner } from './useTransactionSigner';
 import type { 
   TransactionRequestDTO, 
   TransactionRequestResponseDTO, 
-  TransactionDTO
+  TransactionDTO,
+  TransactionRole
 } from '@explorins/pers-shared';
 import type { TransactionPaginationParams } from '@explorins/pers-sdk/transaction';
 
@@ -45,6 +47,7 @@ import type { TransactionPaginationParams } from '@explorins/pers-sdk/transactio
  */
 export const useTransactions = () => {
   const { sdk, isInitialized, isAuthenticated } = usePersSDK();
+  const { signAndSubmitTransactionWithJWT, isSignerAvailable } = useTransactionSigner();
 
   if (!isAuthenticated && isInitialized) {
     console.warn('SDK not authenticated. Some transaction operations may fail.');
@@ -80,15 +83,45 @@ export const useTransactions = () => {
     try {
       const result = await sdk.transactions.createTransaction(request);
       
-      // Cross-platform: Dont handle signature URLs here, leave to caller
-      
       console.log('Transaction created successfully:', result);
+      
+      // Check if transaction requires signing (contains actionable authToken)
+      // Type assertion needed as TransactionRequestResponseDTO type may not include all dynamic properties
+      const txToken = result?.actionable?.authToken;
+      if (txToken) {
+        console.log('[useTransactions] Transaction requires signing, attempting automatic signature...');
+        
+        try {
+          if (!isSignerAvailable) {
+            console.warn('[useTransactions] Transaction signer not available, skipping automatic signing');
+            return result;
+          }
+
+          // Automatically sign the transaction using the authToken
+          const signingResult = await signAndSubmitTransactionWithJWT(txToken);
+          
+          if (signingResult.success) {
+            console.log('[useTransactions] Transaction signed successfully:', signingResult.transactionHash);
+            // Return the original result - the transaction is now signed and will be processed
+            return result;
+          } else {
+            console.error('[useTransactions] Transaction signing failed:', signingResult.error);
+            // Don't throw error - return the original result so caller can handle signature URL manually
+            return result;
+          }
+        } catch (signingError) {
+          console.error('[useTransactions] Blockchain signing error:', signingError);
+          // Don't throw error - return the original result so caller can handle signature URL manually
+          return result;
+        }
+      }
+      
       return result;
     } catch (error) {
       console.error('Failed to create transaction:', error);
       throw error;
     }
-  }, [sdk, isInitialized]);
+  }, [sdk, isInitialized, signAndSubmitTransactionWithJWT, isSignerAvailable]);
 
   /**
    * Retrieves a specific transaction by its ID
@@ -120,26 +153,27 @@ export const useTransactions = () => {
   }, [sdk, isInitialized]);
 
   /**
-   * Retrieves transaction history for the authenticated user, filtered by type
+   * Retrieves transaction history for the authenticated user, filtered by role
    * 
-   * @param type - Transaction type filter (defaults to 'all')
+   * @param role - Optional transaction role filter (TransactionRole.SENDER, TransactionRole.RECIPIENT)
    * @returns Promise resolving to array of user's transactions
    * @throws Error if SDK is not initialized
    * 
    * @example
    * ```typescript
    * const { getUserTransactionHistory } = useTransactions();
-   * const transactions = await getUserTransactionHistory('credit');
-   * console.log('Credit transactions:', transactions);
+   * const sentTransactions = await getUserTransactionHistory(TransactionRole.SENDER);
+   * const allTransactions = await getUserTransactionHistory(); // No filter
    * ```
    */
-  const getUserTransactionHistory = useCallback(async (type: string = 'all'): Promise<TransactionDTO[]> => {
+  const getUserTransactionHistory = useCallback(async (role?: TransactionRole): Promise<TransactionDTO[]> => {
+    
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.transactions.getUserTransactionHistory(type);
+      const result = await sdk.transactions.getUserTransactionHistory(role);
       console.log('Transaction history fetched successfully:', result);
       return result;
     } catch (error) {
@@ -155,7 +189,6 @@ export const useTransactions = () => {
     
     try {
       const result = await sdk.transactions.getTenantTransactions();
-      console.log('Tenant transactions fetched successfully:', result);
       return result;
     } catch (error) {
       console.error('Failed to fetch tenant transactions:', error);

package/src/index.ts

@@ -1,13 +1,123 @@
+/**
+ * @fileoverview PERS SDK for React Native - Tourism Loyalty System
+ * 
+ * A comprehensive React Native SDK for integrating with the PERS (Phygital Experience Rewards System)
+ * platform. Provides complete functionality for tourism loyalty applications including user management,
+ * token operations, business integrations, campaign management, and blockchain transaction signing.
+ * 
+ * **Key Features:**
+ * - Secure authentication with React Native Keychain integration
+ * - Token management (earn, redeem, transfer, balance checking)
+ * - Business and campaign management
+ * - Blockchain transaction signing with WebAuthn
+ * - React Native optimized with automatic polyfills
+ * - Type-safe interfaces with comprehensive TypeScript support
+ * - Analytics and reporting capabilities
+ * - Donation and charitable giving features
+ * 
+ * @example
+ * **Quick Start:**
+ * ```typescript
+ * import { PersSDKProvider, usePersSDK, useTransactionSigner } from '@explorins/pers-sdk-react-native';
+ * 
+ * // 1. Wrap your app with the provider
+ * function App() {
+ *   return (
+ *     <PersSDKProvider config={{ apiUrl: 'https://api.pers.ninja' }}>
+ *       <YourApp />
+ *     </PersSDKProvider>
+ *   );
+ * }
+ * 
+ * // 2. Use hooks in your components
+ * function RewardScreen() {
+ *   const { user, isAuthenticated, earnTokens } = usePersSDK();
+ *   const { signAndSubmitTransactionWithJWT } = useTransactionSigner();
+ *   
+ *   // Your reward logic here...
+ * }
+ * ```
+ * 
+ * @version 1.5.19
+ * @author eXplorins
+ * @license MIT
+ */
+
 // Initialize React Native polyfills automatically
 import './polyfills';
 
-// Export React Native specific providers (FIRST - break circular dependency)
+// ==============================================================================
+// AUTHENTICATION PROVIDERS
+// ==============================================================================
+
+/**
+ * React Native-specific authentication provider with secure keychain integration
+ * 
+ * Provides secure token storage using React Native Keychain, biometric authentication,
+ * and automatic token refresh capabilities.
+ * 
+ * @see {@link createReactNativeAuthProvider} - Factory function for auth provider
+ * @see {@link ReactNativeAuthConfig} - Configuration interface
+ */
 export {
-  ReactNativeAuthProvider,
+  createReactNativeAuthProvider,
   type ReactNativeAuthConfig
 } from './providers/react-native-auth-provider';
 
-// Export Provider and Context directly (avoid circular import through hooks)
+// ==============================================================================
+// SECURE STORAGE
+// ==============================================================================
+
+/**
+ * Secure token storage using React Native AsyncStorage
+ * 
+ * Provides encrypted token storage with automatic cleanup and secure key management.
+ * Integrates with React Native Keychain for enhanced security on supported devices.
+ * 
+ * @see {@link AsyncStorageTokenStorage} - Secure storage implementation
+ */
+export {
+  AsyncStorageTokenStorage,
+} from './storage/async-storage-token-storage';
+
+// ==============================================================================
+// CORE PROVIDER & CONTEXT
+// ==============================================================================
+
+/**
+ * Main PERS SDK provider and context for React Native applications
+ * 
+ * The PersSDKProvider should wrap your entire app to provide PERS functionality
+ * throughout your component tree. Use usePersSDK hook to access SDK features.
+ * 
+ * @example
+ * ```typescript
+ * import { PersSDKProvider, usePersSDK } from '@explorins/pers-sdk-react-native';
+ * 
+ * function App() {
+ *   return (
+ *     <PersSDKProvider config={{ 
+ *       apiUrl: 'https://api.pers.ninja',
+ *       tenantId: 'your-tenant-id'
+ *     }}>
+ *       <NavigationContainer>
+ *         <YourAppContent />
+ *       </NavigationContainer>
+ *     </PersSDKProvider>
+ *   );
+ * }
+ * 
+ * function YourComponent() {
+ *   const { user, isAuthenticated, earnTokens } = usePersSDK();
+ *   // Use PERS functionality here...
+ * }
+ * ```
+ * 
+ * @see {@link PersSDKProvider} - Main provider component
+ * @see {@link usePersSDK} - Hook to access SDK functionality
+ * @see {@link PersConfig} - Provider configuration interface
+ * @see {@link PersSDKContext} - Context type definition
+ */
 export {
   PersSDKProvider,
   usePersSDK,
@@ -15,7 +125,80 @@ export {
   type PersSDKContext
 } from './providers/PersSDKProvider';
 
-// Export hooks (Primary Interface)
+// ==============================================================================
+// REACT HOOKS (Primary Interface)
+// ==============================================================================
+
+/**
+ * Comprehensive React hooks for PERS platform integration
+ * 
+ * These hooks provide the primary interface for interacting with the PERS platform
+ * in React Native applications. Each hook is optimized for specific functionality
+ * and includes automatic error handling, loading states, and real-time updates.
+ * 
+ * **Authentication & User Management:**
+ * - `useAuth` - User authentication, login, logout, registration
+ * - `useUsers` - User profile management and data operations
+ * - `useUserStatus` - Real-time user status and activity monitoring
+ * 
+ * **Token & Financial Operations:**
+ * - `useTokens` - Token balance, earning, and management
+ * - `useTransactions` - Transaction history and monitoring
+ * - `useTransactionSigner` - **⭐ Blockchain transaction signing**
+ * - `usePurchases` - Purchase history and payment processing
+ * - `useDonations` - Charitable giving and donation management
+ * 
+ * **Business & Campaign Management:**
+ * - `useBusiness` - Business profile and operations
+ * - `useCampaigns` - Marketing campaigns and promotions
+ * - `useRedemptions` - Reward redemption and fulfillment
+ * 
+ * **Platform & Analytics:**
+ * - `useTenants` - Multi-tenant configuration and management
+ * - `useAnalytics` - Usage analytics and reporting
+ * - `useFiles` - File upload and management
+ * - `useWeb3` - Blockchain integration and wallet operations
+ * 
+ * @example
+ * **Token Operations:**
+ * ```typescript
+ * import { useTokens, useTransactionSigner } from '@explorins/pers-sdk-react-native';
+ * 
+ * function TokenScreen() {
+ *   const { balance, earnTokens, redeemTokens } = useTokens();
+ *   const { signAndSubmitTransactionWithJWT } = useTransactionSigner();
+ *   
+ *   const handleEarn = async (amount: number) => {
+ *     const result = await earnTokens({ amount, source: 'reward' });
+ *     console.log('Earned tokens:', result);
+ *   };
+ *   
+ *   const handleRedeem = async (amount: number) => {
+ *     const redemption = await redeemTokens({ amount });
+ *     const txResult = await signAndSubmitTransactionWithJWT(redemption.jwtToken);
+ *     console.log('Redemption completed:', txResult.transactionHash);
+ *   };
+ * }
+ * ```
+ * 
+ * @example
+ * **Campaign Integration:**
+ * ```typescript
+ * import { useCampaigns, useAuth } from '@explorins/pers-sdk-react-native';
+ * 
+ * function CampaignScreen() {
+ *   const { activeCampaigns, participateInCampaign } = useCampaigns();
+ *   const { user } = useAuth();
+ *   
+ *   const handleParticipate = async (campaignId: string) => {
+ *     const result = await participateInCampaign(campaignId, {
+ *       userId: user?.id,
+ *       participationData: { source: 'mobile_app' }
+ *     });
+ *   };
+ * }
+ * ```
+ */
 export {
   useAuth,
   useTokens,
@@ -34,19 +217,72 @@ export {
   useDonations
 } from './hooks';
 
+// ==============================================================================
+// PLATFORM ADAPTERS
+// ==============================================================================
+
+/**
+ * React Native-optimized HTTP client with automatic request/response handling
+ * 
+ * Provides platform-specific networking with proper error handling, timeout management,
+ * and React Native compatibility. Automatically handles headers, authentication tokens,
+ * and response parsing.
+ */
 export {
   ReactNativeHttpClient
 } from './providers/react-native-http-client';
 
-// Export polyfill utilities for advanced usage
+// ==============================================================================
+// POLYFILLS & COMPATIBILITY
+// ==============================================================================
+
+/**
+ * React Native polyfill utilities for web compatibility
+ * 
+ * Automatically initializes required polyfills for crypto, URL, and other web APIs
+ * that may not be available in React Native environments. These are typically
+ * loaded automatically, but manual initialization is available for advanced use cases.
+ * 
+ * @see {@link initializeReactNativePolyfills} - Manual polyfill initialization
+ */
 export {
   initializeReactNativePolyfills
 } from './polyfills';
 
-// Re-export all types and utilities from @explorins/pers-shared
+// ==============================================================================
+// TYPE DEFINITIONS & SHARED UTILITIES
+// ==============================================================================
+
+/**
+ * Re-export all types and utilities from the shared PERS library
+ * 
+ * This includes all core types, DTOs, enums, and utility functions used across
+ * the PERS platform. These types ensure consistency between different SDK versions
+ * and platform implementations.
+ * 
+ * **Included Types:**
+ * - User and authentication types (UserDTO, AuthenticationResult, etc.)
+ * - Token and transaction types (TokenDTO, TransactionDTO, etc.)
+ * - Business and campaign types (BusinessDTO, CampaignDTO, etc.)
+ * - API request/response types for all endpoints
+ * - Error types and status enums
+ * 
+ * @see {@link https://github.com/eXplorins/pers-shared} - Shared library documentation
+ */
 export * from '@explorins/pers-shared';
 
-// Re-export Web3 types from base SDK
+/**
+ * Re-export Web3 and blockchain-related types from base SDK
+ * 
+ * Provides TypeScript definitions for Web3 operations, token management,
+ * and blockchain interactions. These types are used by the transaction
+ * signing hooks and Web3 integration features.
+ * 
+ * @see {@link TokenBalanceRequest} - Request structure for token balance queries
+ * @see {@link TokenBalance} - Token balance response data
+ * @see {@link TokenMetadata} - Token metadata and details
+ * @see {@link TokenCollection} - Collection of tokens for batch operations
+ */
 export type { 
   TokenBalanceRequest, 
   TokenBalance, 

package/src/providers/PersSDKProvider.tsx

@@ -1,7 +1,7 @@
 import React, { createContext, useContext, useState, ReactNode, useCallback, useRef } from 'react';
-import { PersSDK, PersConfig, createAuthProvider } from '@explorins/pers-sdk/core';
+import { PersSDK, PersConfig, DefaultAuthProvider } from '@explorins/pers-sdk/core';
 import { ReactNativeHttpClient } from './react-native-http-client';
-import { ReactNativeAuthProvider } from './react-native-auth-provider';
+import { createReactNativeAuthProvider } from './react-native-auth-provider';
 import { UserDTO, AdminDTO } from '@explorins/pers-shared';
 
 // Import manager types for TypeScript
@@ -42,8 +42,8 @@ export interface PersSDKContext {
   // Legacy support (deprecated but kept for backward compatibility)
   business: BusinessManager | null;
   
-  // Platform-specific providers
-  authProvider: ReactNativeSDKAuthProvider | null;
+  // Platform-specific providers - now uses unified auth provider
+  authProvider: DefaultAuthProvider | null;
   
   // State
   isInitialized: boolean;
@@ -60,34 +60,13 @@ export interface PersSDKContext {
 // Create the context
 const SDKContext = createContext<PersSDKContext | null>(null);
 
-// Simple wrapper for SDK integration
-class ReactNativeSDKAuthProvider extends ReactNativeAuthProvider {
-  constructor(projectKey: string) {
-    super(projectKey, { debug: true });
-  }
-
-  // Override setAccessToken to provide backward compatibility
-  async setToken(token: string | null): Promise<void> {
-    if (token) {
-      await this.setAccessToken(token);
-    } else {
-      await this.clearTokens();
-    }
-  }
-
-  // Override getToken for backward compatibility
-  async getToken(): Promise<string | null> {
-    return await super.getToken();
-  }
-}
-
 // Provider component
 export const PersSDKProvider: React.FC<{
   children: ReactNode;
 }> = ({ children }) => {
   const initializingRef = useRef(false);
   const [sdk, setSdk] = useState<PersSDK | null>(null);
-  const [authProvider, setAuthProvider] = useState<ReactNativeSDKAuthProvider | null>(null);
+  const [authProvider, setAuthProvider] = useState<DefaultAuthProvider | null>(null);
   
   const [isInitialized, setIsInitialized] = useState(false);
   const [isAuthenticated, setIsAuthenticated] = useState(false);
@@ -97,34 +76,38 @@ export const PersSDKProvider: React.FC<{
   const initialize = useCallback(async (config: PersConfig) => {
     // Prevent multiple initializations
     if (isInitialized || initializingRef.current) {
-      console.log('SDK already initialized or initializing, skipping...');
       return;
     }
     
     initializingRef.current = true;
     
     try {
-      console.log('Initializing PERS SDK with config:', config);
-      
-      // Create React Native auth provider
-      const auth = new ReactNativeSDKAuthProvider(config.apiProjectKey || 'default-project');
-      setAuthProvider(auth);
-      
       // Create HTTP client
       const httpClient = new ReactNativeHttpClient();
       
-      // Create config with auth provider - use the ReactNative auth provider directly
+      // Create platform-aware auth provider if not provided
+      let authProvider: DefaultAuthProvider;
+      if (config.authProvider) {
+        authProvider = config.authProvider as DefaultAuthProvider;
+      } else {
+        // Use our platform-aware auth provider that automatically selects LocalStorage (web) or AsyncStorage (mobile)
+        authProvider = createReactNativeAuthProvider(config.apiProjectKey || 'default-project', {
+          debug: false
+        });
+      }
+      
+      // Enhanced config with platform-appropriate auth provider
       const sdkConfig: PersConfig = {
         ...config,
-        authProvider: auth
+        authProvider
       };
       
-      // Initialize PersSDK with manager pattern
+      // Initialize PersSDK with platform-aware auth provider
       const sdkInstance = new PersSDK(httpClient, sdkConfig);
+      
+      setAuthProvider(authProvider);
       setSdk(sdkInstance);
       setIsInitialized(true);
-      
-      console.log('PERS SDK initialized successfully');
     } catch (error) {
       console.error('Failed to initialize PERS SDK:', error);
       initializingRef.current = false;
@@ -146,10 +129,8 @@ export const PersSDKProvider: React.FC<{
     }
     
     try {
-      console.log('Refreshing user data from remote server...');
       const freshUserData = await sdk.users.getCurrentUser();
       setUser(freshUserData);
-      console.log('User data refreshed successfully:', freshUserData);
     } catch (error) {
       console.error('Failed to refresh user data:', error);
       throw error;