@explorins/pers-sdk-react-native 1.3.2 → 1.5.2

package/src/hooks/useTransactionSigner.ts

@@ -0,0 +1,287 @@
+import { useCallback, useState, useRef, useEffect } from 'react';
+import { usePersSDK } from '../providers/PersSDKProvider';
+import type { UserDTO, AdminDTO } from '@explorins/pers-shared';
+
+// Dynamic import the signer SDK to avoid build issues with static dependencies
+let createPersSignerSDK: ((config: any) => Promise<any>) | null = null;
+try {
+  const signerModule = require('@explorins/pers-signer/react-native');
+  createPersSignerSDK = signerModule.createPersSignerSDK;
+  console.log('[useTransactionSigner] PERS Signer SDK loaded successfully');
+} catch (error: unknown) {
+  console.warn('[useTransactionSigner] PERS Signer SDK not available:', (error as Error).message);
+  console.warn('[useTransactionSigner] Real blockchain signing will not be available');
+}
+
+interface PersSignerSDKInstance {
+  authenticateUser: (userInfo: SignerUserInfo) => Promise<SignerAuthenticatedUser>;
+  signPersTransaction: (user: SignerAuthenticatedUser, jwt: string) => Promise<SigningResult>;
+}
+
+interface SignerUserInfo {
+  identifier: string;
+  email?: string;
+  id?: string;
+}
+
+interface SignerAuthenticatedUser {
+  identifier: string;
+  signerAuthToken: string;
+  persAccessToken: string;
+}
+
+interface SigningResult {
+  success: boolean;
+  transactionHash?: string;
+  signature?: string;
+  error?: string;
+}
+
+/**
+ * Utility to decode JWT and extract user information
+ * This will be used to extract user data for the signer
+ */
+const extractUserInfoFromJWT = async (jwt: string): Promise<{ userId?: string; email?: string; sub?: string }> => {
+  try {
+    // Dynamically import jwt-decode to avoid bundling issues
+    const { jwtDecode } = await import('jwt-decode');
+    const decoded = jwtDecode<{ 
+      sub?: string; 
+      email?: string; 
+      user_id?: string;
+      userId?: string;
+      uid?: string;
+    }>(jwt);
+    
+    return {
+      userId: decoded.user_id || decoded.userId || decoded.uid || decoded.sub,
+      email: decoded.email,
+      sub: decoded.sub
+    };
+  } catch (error) {
+    console.warn('[useTransactionSigner] Failed to decode JWT:', error);
+    return {};
+  }
+};
+
+// Define our own result type that's compatible with both SDK and our usage
+interface TransactionSigningResult {
+  success: boolean;
+  transactionHash?: string;
+  signature?: string;
+  error?: string;
+}
+
+// Constants - TODO: Move to environment config later
+const DEFAULT_ETHERS_PROVIDER = "https://sepolia.infura.io/v3/2781b4b5242343d5b0954c98f287b29e";
+
+/**
+ * React Native hook for blockchain transaction signing using PERS Signer SDK
+ * 
+ * Provides WebAuthn-based transaction signing capabilities integrated with PERS ecosystem.
+ * Automatically handles user authentication and transaction signing workflows.
+ * 
+ * @example
+ * ```typescript
+ * function TransactionComponent() {
+ *   const { signTransaction, initializeSigner, isSignerAvailable } = useTransactionSigner();
+ *   
+ *   useEffect(() => {
+ *     initializeSigner({
+ *       tenantId: 'my-tenant',
+ *       ethersProviderUrl: 'https://sepolia.infura.io/v3/...'
+ *     });
+ *   }, []);
+ *   
+ *   const handleSign = async () => {
+ *     try {
+ *       const result = await signTransaction('transaction-id-123');
+ *       if (result.success) {
+ *         console.log('Transaction signed:', result.transactionHash);
+ *       }
+ *     } catch (error) {
+ *       console.error('Signing failed:', error);
+ *     }
+ *   };
+ *   
+ *   return (
+ *     <button onClick={handleSign} disabled={!isSignerAvailable}>
+ *       Sign Transaction
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export const useTransactionSigner = () => {
+  const { sdk, isInitialized, isAuthenticated, user } = usePersSDK();
+  const [isSignerInitialized, setIsSignerInitialized] = useState(false);
+  const signerSDKRef = useRef<PersSignerSDKInstance | null>(null);
+
+  // Auto-initialize signer when user is authenticated and real SDK is available
+  useEffect(() => {
+    if (isInitialized && isAuthenticated && user && !isSignerInitialized) {
+      console.log('[useTransactionSigner] Auto-initializing PERS transaction signer...');
+      initializeSigner({
+        tenantId: 'auto-tenant', // TODO: Get from SDK config or environment
+        ethersProviderUrl: DEFAULT_ETHERS_PROVIDER
+      }).catch((error) => {
+        console.error('[useTransactionSigner] Auto-initialization failed:', error);
+      });
+    }
+  }, [isInitialized, isAuthenticated, user, isSignerInitialized, createPersSignerSDK]);
+
+  /**
+   * Initialize the blockchain signer with configuration
+   * 
+   * @param config - Signer configuration options
+   * @param config.tenantId - Multi-tenant identifier for the signer
+   * @param config.ethersProviderUrl - Custom blockchain provider URL
+   * 
+   * @example
+   * ```typescript
+   * await initializeSigner({
+   *   tenantId: 'my-tenant-id',
+   *   ethersProviderUrl: 'https://sepolia.infura.io/v3/your-key'
+   * });
+   * ```
+   */
+  const initializeSigner = useCallback(async (config?: { 
+    tenantId?: string; 
+    ethersProviderUrl?: string;
+  }) => {
+    if (!createPersSignerSDK) {
+      throw new Error('PERS Signer SDK not available. Please ensure dependencies are properly installed.');
+    }
+
+    try {
+      console.log('[useTransactionSigner] Initializing PERS transaction signer...');
+      
+      const signerSDK = await createPersSignerSDK({
+        tenantId: config?.tenantId,
+        ethersProviderUrl: config?.ethersProviderUrl || DEFAULT_ETHERS_PROVIDER
+      });
+      
+      signerSDKRef.current = signerSDK;
+      setIsSignerInitialized(true);
+      console.log('[useTransactionSigner] PERS Signer SDK initialized successfully');
+      
+    } catch (error) {
+      console.error('[useTransactionSigner] Failed to initialize transaction signer:', error);
+      throw new Error(`Signer initialization failed: ${error}`);
+    }
+  }, []);
+
+  /**
+   * Sign a blockchain transaction using WebAuthn authentication
+   * 
+   * @param jwt - JWT token containing transaction information and user context
+   * @returns Promise resolving to signing result with transaction hash
+   * 
+   * @throws {Error} When SDK not initialized, user not authenticated, or signer not initialized
+   * 
+   * @example
+   * ```typescript
+   * try {
+   *   const result = await signTransaction(jwtToken);
+   *   if (result.success) {
+   *     console.log('Signed transaction hash:', result.transactionHash);
+   *   } else {
+   *     console.error('Signing failed:', result.error);
+   *   }
+   * } catch (error) {
+   *   console.error('Signing error:', error);
+   * }
+   * ```
+   */
+  const signTransaction = useCallback(async (jwt: string): Promise<TransactionSigningResult> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    if (!isAuthenticated || !user) {
+      throw new Error('User must be authenticated to sign transactions.');
+    }
+    if (!isSignerInitialized || !signerSDKRef.current) {
+      throw new Error('Transaction signer not initialized. Call initializeSigner() first.');
+    }
+    if (!createPersSignerSDK) {
+      throw new Error('PERS Signer SDK not available. Blockchain signing is not supported.');
+    }
+
+    try {
+      console.log('[useTransactionSigner] Extracting user info from JWT for transaction signing...');
+      
+      // Extract user information from JWT
+      const jwtUserInfo = await extractUserInfoFromJWT(jwt);
+      
+      // Create user info for signer, prioritizing current user data
+      const currentUser = user as UserDTO;
+      const signerUserInfo: SignerUserInfo = {
+        identifier: currentUser.email || currentUser.id || jwtUserInfo.userId || jwtUserInfo.sub || `user-${Date.now()}`,
+        email: currentUser.email || jwtUserInfo.email,
+        id: currentUser.id || jwtUserInfo.userId
+      };
+      
+      // Authenticate user with blockchain signer
+      console.log('[useTransactionSigner] Authenticating user with signer:', signerUserInfo.identifier);
+      const signerUser = await signerSDKRef.current.authenticateUser(signerUserInfo);
+      
+      // Sign the PERS transaction using JWT
+      console.log('[useTransactionSigner] Signing PERS transaction with JWT containing transaction data');
+      const result = await signerSDKRef.current.signPersTransaction(signerUser, jwt);
+      
+      // Convert PERS SDK result to our format
+      const convertedResult: TransactionSigningResult = {
+        success: result.success || false,
+        transactionHash: result.transactionHash,
+        signature: result.signature,
+        error: result.error
+      };
+      
+      if (convertedResult.success) {
+        console.log('[useTransactionSigner] Transaction signed successfully:', convertedResult.transactionHash);
+      } else {
+        console.warn('[useTransactionSigner] Transaction signing completed with warnings:', convertedResult.error);
+      }
+      
+      return convertedResult;
+    } catch (error) {
+      console.error('[useTransactionSigner] Failed to sign transaction:', error);
+      return {
+        success: false,
+        error: `Transaction signing failed: ${error}`
+      };
+    }
+  }, [sdk, isInitialized, isAuthenticated, user, isSignerInitialized]);
+
+  return {
+    /**
+     * Sign a blockchain transaction with WebAuthn authentication
+     */
+    signTransaction,
+    
+    /**
+     * Initialize the transaction signer with configuration
+     */
+    initializeSigner,
+    
+    /**
+     * Whether the transaction signer has been initialized
+     */
+    isSignerInitialized,
+    
+    /**
+     * Whether transaction signing is available (all requirements met)
+     */
+    isSignerAvailable: isInitialized && isAuthenticated && isSignerInitialized,
+  };
+};
+
+/**
+ * Type definition for the transaction signer hook
+ */
+export type TransactionSignerHook = ReturnType<typeof useTransactionSigner>;
+
+/**
+ * Export the transaction signing result type for external usage
+ */
+export type { TransactionSigningResult };

package/src/hooks/useTransactions.ts

@@ -1,85 +1,207 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
+import type { 
+  TransactionRequestDTO, 
+  TransactionRequestResponseDTO, 
+  TransactionDTO
+} from '@explorins/pers-shared';
+import type { TransactionPaginationParams } from '@explorins/pers-sdk/transaction';
 
+/**
+ * React hook for transaction operations in the PERS SDK
+ * 
+ * Provides comprehensive transaction management including creation, retrieval, history,
+ * and administrative operations. Supports pagination and CSV export functionality.
+ * 
+ * @returns Transaction hook with methods for transaction management
+ * 
+ * @example
+ * ```typescript
+ * function TransactionsComponent() {
+ *   const { 
+ *     createTransaction, 
+ *     getUserTransactionHistory 
+ *   } = useTransactions();
+ *   
+ *   const handleCreateTransaction = async (request) => {
+ *     try {
+ *       const result = await createTransaction(request);
+ *       console.log('Transaction created:', result);
+ *       // Handle signature URL if returned
+ *     } catch (error) {
+ *       console.error('Transaction failed:', error);
+ *     }
+ *   };
+ * 
+ *   return (
+ *     <div>
+ *       <button onClick={() => handleCreateTransaction(transactionRequest)}>
+ *         Create Transaction
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export const useTransactions = () => {
-  const { transactions, isInitialized, isAuthenticated } = usePersSDK();
+  const { sdk, isInitialized, isAuthenticated } = usePersSDK();
 
   if (!isAuthenticated && isInitialized) {
     console.warn('SDK not authenticated. Some transaction operations may fail.');
   }
 
-  const createTransaction = useCallback(async (request: any) => {
-    if (!isInitialized) {
+  /**
+   * Creates a new transaction in the system
+   * 
+   * Automatically handles signature URLs by opening them in the device's browser.
+   * The transaction may require user approval through external wallet applications.
+   * 
+   * @param request - Transaction request data including amount, recipient, etc.
+   * @returns Promise resolving to transaction response with potential actionable items
+   * @throws Error if SDK is not initialized
+   * 
+   * @example
+   * ```typescript
+   * const { createTransaction } = useTransactions();
+   * const request = {
+   *   amount: '100',
+   *   recipient: '0x123...',
+   *   tokenId: 'token-123'
+   * };
+   * const result = await createTransaction(request);
+   * console.log('Transaction created:', result);
+   * ```
+   */
+  const createTransaction = useCallback(async (request: TransactionRequestDTO): Promise<TransactionRequestResponseDTO> => {
+    if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
-    if (!transactions?.createTransaction) {
-      throw new Error('createTransaction method not available');
-    }
     
     try {
-      console.log('🔄 Creating transaction with request:', request);
-      const result = await transactions.createTransaction(request);
+      const result = await sdk.transactions.createTransaction(request);
       
-      // React Native specific: Handle signature URLs
-      if (result?.actionable?.actionUrl) {
-        try {
-          const { Linking } = require('react-native');
-          console.log('🔗 Opening signature URL:', result.actionable.actionUrl);
-          await Linking.openURL(result.actionable.actionUrl);
-        } catch (linkingError) {
-          console.error('❌ Failed to open signature URL:', linkingError);
-        }
-      }
+      // Cross-platform: Dont handle signature URLs here, leave to caller
       
-      console.log('✅ Transaction created successfully:', result);
+      console.log('Transaction created successfully:', result);
       return result;
     } catch (error) {
-      console.error('❌ Failed to create transaction:', error);
+      console.error('Failed to create transaction:', error);
       throw error;
     }
-  }, [transactions]);
+  }, [sdk, isInitialized]);
 
-  const getTransactionById = useCallback(async (transactionId: string) => {
-    if (!isInitialized) {
+  /**
+   * Retrieves a specific transaction by its ID
+   * 
+   * @param transactionId - Unique identifier of the transaction
+   * @returns Promise resolving to transaction data or null if not found
+   * @throws Error if SDK is not initialized
+   * 
+   * @example
+   * ```typescript
+   * const { getTransactionById } = useTransactions();
+   * const transaction = await getTransactionById('txn-123');
+   * console.log('Transaction details:', transaction);
+   * ```
+   */
+  const getTransactionById = useCallback(async (transactionId: string): Promise<TransactionDTO | null> => {
+    if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
-    if (!transactions?.getTransactionById) {
-      throw new Error('getTransactionById method not available');
+    
+    try {
+      const result = await sdk.transactions.getTransactionById(transactionId);
+      console.log('Transaction fetched successfully:', result);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch transaction:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
+  /**
+   * Retrieves transaction history for the authenticated user, filtered by type
+   * 
+   * @param type - Transaction type filter (defaults to 'all')
+   * @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 getUserTransactionHistory = useCallback(async (type: string = 'all'): Promise<TransactionDTO[]> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await transactions.getTransactionById(transactionId);
-      console.log('✅ Transaction fetched successfully:', result);
+      const result = await sdk.transactions.getUserTransactionHistory(type);
+      console.log('Transaction history fetched successfully:', result);
       return result;
     } catch (error) {
-      console.error('❌ Failed to fetch transaction:', error);
+      console.error('Failed to fetch transaction history:', error);
       throw error;
     }
-  }, [transactions]);
+  }, [sdk, isInitialized]);
 
-  const getTransactionHistory = useCallback(async (filters?: any) => {
-    if (!isInitialized) {
+  const getTenantTransactions = useCallback(async (): Promise<TransactionDTO[]> => {
+    if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
-    if (!transactions?.getTransactionHistory) {
-      console.warn('getTransactionHistory method not available');
-      return [];
+    
+    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);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
+  const getPaginatedTransactions = useCallback(async (params: TransactionPaginationParams): Promise<any> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await transactions.getTransactionHistory(filters);
-      console.log('✅ Transaction history fetched successfully:', result);
+      const result = await sdk.transactions.getPaginatedTransactions(params);
+      console.log('Paginated transactions fetched successfully:', result);
       return result;
     } catch (error) {
-      console.error('❌ Failed to fetch transaction history:', error);
+      console.error('Failed to fetch paginated transactions:', error);
       throw error;
     }
-  }, [transactions]);
+  }, [sdk, isInitialized]);
+
+  const exportTransactionsCSV = useCallback(async (): Promise<Blob> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.transactions.exportTransactionsCSV();
+      console.log('Transactions CSV exported successfully');
+      return result;
+    } catch (error) {
+      console.error('Failed to export transactions CSV:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
 
   return {
     createTransaction,
     getTransactionById,
-    getTransactionHistory,
-    isAvailable: isInitialized && !!transactions,
+    getUserTransactionHistory,
+    getTenantTransactions,
+    getPaginatedTransactions,
+    exportTransactionsCSV,
+    isAvailable: isInitialized && !!sdk?.transactions,
   };
-};
+};
+
+export type TransactionHook = ReturnType<typeof useTransactions>;

package/src/hooks/useUserStatus.ts

@@ -0,0 +1,65 @@
+import { useCallback } from 'react';
+import { usePersSDK } from '../providers/PersSDKProvider';
+import type { UserStatusTypeDTO } from '@explorins/pers-shared';
+
+export const useUserStatus = () => {
+  const { sdk, isInitialized, isAuthenticated } = usePersSDK();
+
+  const getUserStatusTypes = useCallback(async (): Promise<UserStatusTypeDTO[]> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.userStatus.getUserStatusTypes();
+      console.log('User status types fetched successfully:', result);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch user status types:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
+  const getEarnedUserStatus = useCallback(async (): Promise<UserStatusTypeDTO[]> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    if (!isAuthenticated) {
+      throw new Error('SDK not authenticated. getEarnedUserStatus requires authentication.');
+    }
+    
+    try {
+      const result = await sdk.userStatus.getEarnedUserStatus();
+      console.log('Earned user status fetched successfully:', result);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch earned user status:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized, isAuthenticated]);
+
+  // Admin methods
+  const createUserStatusType = useCallback(async (userStatusType: UserStatusTypeDTO): Promise<UserStatusTypeDTO> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.userStatus.createUserStatusType(userStatusType);
+      console.log('User status type created successfully:', result);
+      return result;
+    } catch (error) {
+      console.error('Failed to create user status type:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
+  return {
+    getUserStatusTypes,
+    getEarnedUserStatus,
+    createUserStatusType,
+    isAvailable: isInitialized && !!sdk?.userStatus,
+  };
+};
+
+export type UserStatusHook = ReturnType<typeof useUserStatus>;