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

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;

package/src/providers/react-native-auth-provider.ts

@@ -1,189 +1,71 @@
-import type { PersAuthProvider } from '@explorins/pers-sdk/core';
-import AsyncStorage from '@react-native-async-storage/async-storage';
+/**
+ * React Native Unified Auth Provider
+ * 
+ * Creates a platform-specific auth provider that automatically selects the appropriate storage:
+ * - Web: Uses LocalStorageTokenStorage from core SDK
+ * - Mobile: Uses AsyncStorage-based storage
+ */
+
+import { Platform } from 'react-native';
+import { DefaultAuthProvider, AuthApi, AuthType, LocalStorageTokenStorage } from '@explorins/pers-sdk/core';
+import { AsyncStorageTokenStorage } from '../storage/async-storage-token-storage';
+import type { TokenStorage } from '@explorins/pers-sdk/core';
+
+// Use React Native's built-in platform detection
+const isWebPlatform = Platform.OS === 'web';
 
 /**
- * Configuration options for React Native Auth Provider
+ * Configuration for React Native Auth Provider
  */
 export interface ReactNativeAuthConfig {
-  /** Use secure storage (Keychain) for tokens when available */
-  useSecureStorage?: boolean;
-  /** Custom key prefix for storage */
+  /** Custom storage key prefix */
   keyPrefix?: string;
   /** Enable debug logging */
   debug?: boolean;
+  /** Custom token storage implementation */
+  customStorage?: TokenStorage;
+  /** Authentication type (default: 'user') */
+  authType?: AuthType;
 }
 
 /**
- * React Native Authentication Provider
+ * Create a React Native auth provider with platform-appropriate storage
+ * 
+ * Automatically selects storage implementation:
+ * - Web: Uses LocalStorageTokenStorage (from core SDK)
+ * - Mobile: Uses AsyncStorageTokenStorage (React Native specific)
  * 
- * Simple, unified implementation for React Native apps with:
- * - AsyncStorage for basic token storage
- * - Keychain integration for secure storage (when available)
- * - Automatic fallback to AsyncStorage if Keychain is unavailable
- * - Cross-platform compatibility (iOS/Android/Expo)
+ * @param projectKey - PERS project key
+ * @param config - Configuration options
+ * @returns DefaultAuthProvider configured for the current platform
  */
-export class ReactNativeAuthProvider implements PersAuthProvider {
-  readonly authType: 'user' = 'user';
-  
-  private readonly config: Required<ReactNativeAuthConfig>;
-  private readonly ACCESS_TOKEN_KEY: string;
-  private readonly REFRESH_TOKEN_KEY: string;
-  private readonly projectKey: string;
-  
-  // In-memory fallback storage
-  private memoryStorage: Map<string, string> = new Map();
-
-  constructor(
-    projectKey: string,
-    config: ReactNativeAuthConfig = {}
-  ) {
-    if (!projectKey || typeof projectKey !== 'string') {
-      throw new Error('ReactNativeAuthProvider: projectKey is required and must be a string');
-    }
-
-    this.projectKey = projectKey;
-    
-    // Set default configuration
-    this.config = {
-      useSecureStorage: true, // Default to secure storage when available
-      keyPrefix: `pers_${projectKey.slice(0, 8)}`,
-      debug: false,
-      ...config
-    };
-
-    // Create storage keys
-    this.ACCESS_TOKEN_KEY = `${this.config.keyPrefix}_access_token`;
-    this.REFRESH_TOKEN_KEY = `${this.config.keyPrefix}_refresh_token`;
-
-    if (this.config.debug) {
-      console.log('ReactNativeAuthProvider initialized:', { 
-        projectKey: projectKey.slice(0, 8) + '...', 
-        useSecureStorage: this.config.useSecureStorage 
-      });
-    }
-  }
-
-  async getProjectKey(): Promise<string | null> {
-    return this.projectKey;
-  }
-
-  async getToken(): Promise<string | null> {
-    return this.getStoredValue(this.ACCESS_TOKEN_KEY);
-  }
-
-  async setAccessToken(token: string): Promise<void> {
-    await this.storeValue(this.ACCESS_TOKEN_KEY, token);
-    if (this.config.debug) {
-      console.log('Access token stored securely');
-    }
-  }
-
-  async setRefreshToken(token: string): Promise<void> {
-    await this.storeValue(this.REFRESH_TOKEN_KEY, token);
-    if (this.config.debug) {
-      console.log('Refresh token stored securely');
-    }
-  }
-
-  async getRefreshToken(): Promise<string | null> {
-    return this.getStoredValue(this.REFRESH_TOKEN_KEY);
-  }
-
-  async clearTokens(): Promise<void> {
-    await Promise.all([
-      this.removeStoredValue(this.ACCESS_TOKEN_KEY),
-      this.removeStoredValue(this.REFRESH_TOKEN_KEY)
-    ]);
-    
-    if (this.config.debug) {
-      console.log('All tokens cleared from storage');
-    }
-  }
-
-  async onTokenExpired(): Promise<void> {
-    if (this.config.debug) {
-      console.warn('ReactNativeAuthProvider: Token expired - implement refresh logic in your app');
-    }
-    // Clear expired tokens
-    await this.clearTokens();
-  }
-
-  // Token validation methods
-  hasValidToken(): boolean {
-    return true; // Actual validation happens in getToken()
-  }
-
-  hasRefreshToken(): boolean {
-    return true; // Actual validation happens in getRefreshToken()
-  }
-
-  // Storage implementation methods
-  private async storeValue(key: string, value: string): Promise<void> {
-    try {
-      if (this.config.useSecureStorage && await this.isKeychainAvailable()) {
-        await this.storeInKeychain(key, value);
-      } else {
-        await AsyncStorage.setItem(key, value);
-      }
-    } catch (error) {
-      console.error(`Failed to store value for key ${key}:`, error);
-      // Fallback to memory storage
-      this.memoryStorage.set(key, value);
-    }
-  }
-
-  private async getStoredValue(key: string): Promise<string | null> {
-    try {
-      if (this.config.useSecureStorage && await this.isKeychainAvailable()) {
-        return await this.getFromKeychain(key);
-      } else {
-        return await AsyncStorage.getItem(key);
-      }
-    } catch (error) {
-      console.warn(`Failed to get value for key ${key}:`, error);
-      // Fallback to memory storage
-      return this.memoryStorage.get(key) || null;
-    }
-  }
-
-  private async removeStoredValue(key: string): Promise<void> {
-    try {
-      if (this.config.useSecureStorage && await this.isKeychainAvailable()) {
-        await this.removeFromKeychain(key);
-      } else {
-        await AsyncStorage.removeItem(key);
-      }
-    } catch (error) {
-      console.error(`Failed to remove value for key ${key}:`, error);
-    }
-    
-    // Ensure memory fallback is also cleared
-    this.memoryStorage.delete(key);
-  }
-
-  // Keychain helper methods
-  private async isKeychainAvailable(): Promise<boolean> {
-    try {
-      const Keychain = require('react-native-keychain');
-      return !!Keychain && typeof Keychain.setInternetCredentials === 'function';
-    } catch {
-      return false;
-    }
-  }
-
-  private async storeInKeychain(key: string, value: string): Promise<void> {
-    const Keychain = require('react-native-keychain');
-    await Keychain.setInternetCredentials(key, 'pers-token', value);
-  }
-
-  private async getFromKeychain(key: string): Promise<string | null> {
-    const Keychain = require('react-native-keychain');
-    const credentials = await Keychain.getInternetCredentials(key);
-    return credentials ? credentials.password : null;
-  }
+export function createReactNativeAuthProvider(
+  projectKey: string,
+  config: ReactNativeAuthConfig = {}
+): DefaultAuthProvider {
+  if (!projectKey || typeof projectKey !== 'string') {
+    throw new Error('createReactNativeAuthProvider: projectKey is required and must be a string');
+  }
+
+  const {
+    keyPrefix = `pers_${projectKey.slice(0, 8)}_`,
+    debug = false,
+    customStorage,
+    authType = 'user'
+  } = config;
+
+  // Platform-specific storage selection
+  const tokenStorage = customStorage || (
+    isWebPlatform 
+      ? new LocalStorageTokenStorage()
+      : new AsyncStorageTokenStorage(keyPrefix)
+  );
+
+  // Return DefaultAuthProvider configured with platform-appropriate storage
+  return new DefaultAuthProvider({
+    authType,
+    projectKey,
+    storage: tokenStorage
+  });
+}
 
-  private async removeFromKeychain(key: string): Promise<void> {
-    const Keychain = require('react-native-keychain');
-    await Keychain.resetInternetCredentials(key);
-  }
-}

package/src/providers/react-native-http-client.ts

@@ -5,6 +5,15 @@
  * and uses fetch API which is available in React Native.
  */
 
+/**
+ * Request options for HTTP client operations
+ * 
+ * @interface RequestOptions
+ * @property {Record<string, string>} [headers] - HTTP headers to include
+ * @property {Record<string, string>} [params] - URL parameters
+ * @property {number} [timeout] - Request timeout in milliseconds
+ * @property {'json' | 'blob' | 'text' | 'arraybuffer'} [responseType] - Expected response type
+ */
 export interface RequestOptions {
   headers?: Record<string, string>;
   params?: Record<string, string>;
@@ -12,6 +21,12 @@ export interface RequestOptions {
   responseType?: 'json' | 'blob' | 'text' | 'arraybuffer'; 
 }
 
+/**
+ * HTTP Client interface for React Native
+ * 
+ * @interface HttpClient
+ * @template T - Response type
+ */
 export interface HttpClient {
   get<T>(url: string, options?: RequestOptions): Promise<T>;
   post<T>(url: string, body: any, options?: RequestOptions): Promise<T>;