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

package/src/hooks/useTransactionSigner.ts

@@ -1,53 +1,40 @@
 import { useCallback, useState, useRef, useEffect } from 'react';
-import { usePersSDK } from '../providers/PersSDKProvider';
+// import { usePersSDK } from '../providers/PersSDKProvider';
+import { PersSignerConfig } from '@explorins/pers-signer';
+
+// Import actual SDK types from the React Native-specific export
+type PersSignerSDK = import('@explorins/pers-signer/react-native').PersSignerSDK;
+type SubmissionResult = import('@explorins/pers-signer/react-native').SubmissionResult;
+type AuthenticatedUser = import('@explorins/pers-signer/react-native').AuthenticatedUser;
+type TransactionSigningResult = import('@explorins/pers-signer/react-native').TransactionSigningResult;
+
 
 // Dynamic import the signer SDK to avoid build issues with static dependencies
-let createPersSignerSDK: ((config: PersSignerConfig) => Promise<PersSignerSDKInstance>) | null = null;
+let createPersSignerSDK: ((config: PersSignerConfig) => Promise<PersSignerSDK>) | 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');
 }
 
-// Simplified configuration matching web frontend
-interface PersSignerConfig {
-  ethersProviderUrl?: string;     // Custom blockchain provider
-}
-
-// Simplified SDK interface matching web frontend
-interface PersSignerSDKInstance {
-  authenticateWithJWT: (searchParams: URLSearchParams) => Promise<AuthenticationResult | null>;
-  authenticateUser: (identifier: string) => Promise<SignerAuthenticatedUser>;
-  signPersTransaction: (user: SignerAuthenticatedUser, transactionId: string) => Promise<SigningResult>;
-}
-
-// Types matching web frontend
-interface AuthenticationResult {
-  user: SignerAuthenticatedUser;
-  isExpired: boolean;
-}
 
-interface SignerAuthenticatedUser {
-  identifier: string;
-  signerAuthToken: string;
-  persAccessToken: string;
-}
-
-interface SigningResult {
-  success: boolean;
-  transactionHash?: string;
-  error?: string;
-}
-
-// Define our own result type that's compatible with both SDK and our usage
-interface TransactionSigningResult {
-  success: boolean;
-  transactionHash?: string;
-  signature?: string;
-  error?: string;
+/**
+ * Return interface for the useTransactionSigner hook
+ * 
+ * Provides secure transaction signing capabilities for EVM blockchain interactions
+ * and error handling for React Native applications.
+ * 
+ * @interface TransactionSignerHook
+ * @property {Function} signAndSubmitTransactionWithJWT - Main method to sign and submit transactions
+ * @property {boolean} isSignerInitialized - Whether the signer SDK has been initialized
+ * @property {boolean} isSignerAvailable - Whether signing functionality is fully available
+ */
+export interface TransactionSignerHook {
+  signAndSubmitTransactionWithJWT: (jwt: string) => Promise<SubmissionResult>;
+  isSignerInitialized: boolean;
+  isSignerAvailable: boolean;
 }
 
 // Constants - TODO: Move to environment config later
@@ -56,42 +43,187 @@ const DEFAULT_ETHERS_PROVIDER = "https://sepolia.infura.io/v3/2781b4b5242343d5b0
 /**
  * React Native hook for blockchain transaction signing using PERS Signer SDK
  * 
- * Simplified interface matching web frontend - uses high-level SDK methods
- * that handle all complexity internally (tenant setup, project keys, etc.).
+ * This hook provides a complete blockchain transaction signing solution for React Native
+ * applications, integrating with the PERS ecosystem for tourism loyalty and reward systems.
+ * It automatically handles WebAuthn authentication, transaction preparation, signing, and
+ * blockchain submission in a single convenient interface.
+ * 
+ * **Features:**
+ * - Automatic WebAuthn provider initialization for React Native
+ * - 5-minute authentication caching to reduce repeated logins
+ * - Complete transaction lifecycle management (sign + submit)
+ * - Comprehensive error handling with detailed error messages
+ * - Real-time status monitoring for UI feedback
+ * - Automatic retry logic for network failures
+ * 
+ * **Underlying SDK Methods:**
+ * The hook uses the PERS Signer SDK which provides 5 core methods:
+ * 1. `loginUser(jwtToken)` - Authenticate user with 5-minute caching
+ * 2. `signTransaction(signingData, jwtToken)` - Sign transactions with auto-login
+ * 3. `submitTransaction(signingResult, jwtToken)` - Submit signed transactions
+ * 4. `signPersTransaction(jwtToken)` - Legacy one-liner for backward compatibility
+ * 5. `signAndSubmitPersTransaction(jwtToken)` - Complete sign + submit flow (used by this hook)
+ * 
+ * **Security:**
+ * - WebAuthn-based secure authentication (no passwords stored)
+ * - JWT token validation and expiration checking
+ * - Secure transaction signing using device biometrics/PIN
+ * - No sensitive data stored locally
+ * 
+ * @returns {TransactionSignerHook} Hook interface with signing methods and status
  * 
  * @example
+ * **Basic Usage:**
  * ```typescript
- * function TransactionComponent() {
- *   const { signTransactionWithJWT, isSignerAvailable } = useTransactionSigner();
+ * import { useTransactionSigner } from '@explorins/pers-sdk-react-native';
+ * 
+ * function TransactionScreen() {
+ *   const { 
+ *     signAndSubmitTransactionWithJWT, 
+ *     isSignerAvailable,
+ *     isSignerInitialized 
+ *   } = useTransactionSigner();
  *   
  *   const handleSign = async (jwtFromRedemption: string) => {
+ *     if (!isSignerAvailable) {
+ *       console.error('Signer not available');
+ *       return;
+ *     }
+ *     
  *     try {
- *       const result = await signTransactionWithJWT(jwtFromRedemption);
+ *       const result = await signAndSubmitTransactionWithJWT(jwtFromRedemption);
  *       if (result.success) {
- *         console.log('Transaction signed:', result.transactionHash);
+ *         console.log('Transaction completed:', result.transactionHash);
+ *         // Handle successful transaction
+ *         if (result.shouldRedirect && result.redirectUrl) {
+ *           // Navigate to success page or external URL
+ *         }
  *       }
  *     } catch (error) {
- *       console.error('Signing failed:', error);
+ *       console.error('Transaction failed:', error.message);
+ *       // Handle error (show user-friendly message)
  *     }
  *   };
  *   
  *   return (
- *     <button onClick={handleSign} disabled={!isSignerAvailable}>
- *       Sign Transaction
- *     </button>
+ *     <View style={styles.container}>
+ *       <TouchableOpacity 
+ *         onPress={() => handleSign(redeemJWT)} 
+ *         disabled={!isSignerAvailable}
+ *         style={[styles.button, !isSignerAvailable && styles.disabled]}
+ *       >
+ *         <Text style={styles.buttonText}>
+ *           {isSignerInitialized ? 'Sign Transaction' : 'Initializing...'}
+ *         </Text>
+ *       </TouchableOpacity>
+ *     </View>
  *   );
  * }
  * ```
+ * 
+ * @example
+ * **Advanced Usage with Error Handling:**
+ * ```typescript
+ * function AdvancedTransactionComponent() {
+ *   const [isLoading, setIsLoading] = useState(false);
+ *   const [error, setError] = useState<string | null>(null);
+ *   const { signAndSubmitTransactionWithJWT, isSignerAvailable } = useTransactionSigner();
+ *   
+ *   const handleTransaction = async (jwt: string) => {
+ *     setIsLoading(true);
+ *     setError(null);
+ *     
+ *     try {
+ *       const result = await signAndSubmitTransactionWithJWT(jwt);
+ *       
+ *       if (result.success) {
+ *         // Success handling
+ *         Alert.alert(
+ *           'Success',
+ *           `Transaction completed!\nHash: ${result.transactionHash}`
+ *         );
+ *       } else {
+ *         throw new Error(result.error || 'Transaction failed');
+ *       }
+ *     } catch (err) {
+ *       const errorMessage = err instanceof Error ? err.message : 'Unknown error';
+ *       setError(errorMessage);
+ *       
+ *       // Different error handling based on error type
+ *       if (errorMessage.includes('expired')) {
+ *         Alert.alert('Session Expired', 'Please log in again');
+ *       } else if (errorMessage.includes('network')) {
+ *         Alert.alert('Network Error', 'Please check your connection');
+ *       } else {
+ *         Alert.alert('Transaction Failed', errorMessage);
+ *       }
+ *     } finally {
+ *       setIsLoading(false);
+ *     }
+ *   };
+ *   
+ *   return (
+ *     <View>
+ *       {error && (
+ *         <Text style={styles.errorText}>{error}</Text>
+ *       )}
+ *       <TouchableOpacity 
+ *         onPress={() => handleTransaction(jwtToken)}
+ *         disabled={!isSignerAvailable || isLoading}
+ *       >
+ *         <Text>
+ *           {isLoading ? 'Processing...' : 'Sign & Submit Transaction'}
+ *         </Text>
+ *       </TouchableOpacity>
+ *     </View>
+ *   );
+ * }
+ * ```
+ * 
+ * @example
+ * **Integration with PERS SDK:**
+ * ```typescript
+ * import { usePersSDK } from '@explorins/pers-sdk-react-native';
+ * import { useTransactionSigner } from '@explorins/pers-sdk-react-native';
+ * 
+ * function RedemptionFlow() {
+ *   const { user, redeemTokens } = usePersSDK();
+ *   const { signAndSubmitTransactionWithJWT } = useTransactionSigner();
+ *   
+ *   const handleRedemption = async (tokenAmount: number) => {
+ *     try {
+ *       // Step 1: Create redemption with PERS SDK
+ *       const redemption = await redeemTokens({
+ *         tokenAmount,
+ *         destinationAddress: user?.walletAddress
+ *       });
+ *       
+ *       // Step 2: Sign and submit transaction
+ *       const txResult = await signAndSubmitTransactionWithJWT(redemption.jwtToken);
+ *       
+ *       if (txResult.success) {
+ *         console.log('Redemption completed:', txResult.transactionHash);
+ *       }
+ *     } catch (error) {
+ *       console.error('Redemption failed:', error);
+ *     }
+ *   };
+ * }
+ * ```
+ * 
+ * @see {@link SubmissionResult} for transaction result structure
+ * @see {@link TransactionSigningResult} for signing result details
+ * @see {@link AuthenticatedUser} for user authentication data
+ * 
+ * @since 1.5.0
  */
-export const useTransactionSigner = () => {
-  const { isInitialized, isAuthenticated, user } = usePersSDK();
+export const useTransactionSigner = (): TransactionSignerHook => {
+  // const { isInitialized, isAuthenticated, user } = usePersSDK();
   const [isSignerInitialized, setIsSignerInitialized] = useState(false);
-  const signerSDKRef = useRef<PersSignerSDKInstance | null>(null);
+  const signerSDKRef = useRef<PersSignerSDK | null>(null);
 
   // Auto-initialize signer SDK when PERS SDK is ready
   useEffect(() => {
-    console.log('[useTransactionSigner] Auto-initializing signer SDK...');
-    
     const initializeSignerSDK = async () => {
       if (!createPersSignerSDK) {
         console.warn('[useTransactionSigner] Signer SDK not available');
@@ -99,14 +231,14 @@ export const useTransactionSigner = () => {
       }
 
       try {
-        console.log('[useTransactionSigner] Creating PERS Signer SDK...');
+        // React Native createPersSignerSDK automatically includes WebAuthn provider
         const signerSDK = await createPersSignerSDK({
-          ethersProviderUrl: DEFAULT_ETHERS_PROVIDER
+          ethersProviderUrl: DEFAULT_ETHERS_PROVIDER,
+          relyingPartyName: 'PERS React Native App'
         });
         
         signerSDKRef.current = signerSDK;
         setIsSignerInitialized(true);
-        console.log('[useTransactionSigner] PERS Signer SDK initialized successfully');
         
       } catch (error) {
         console.error('[useTransactionSigner] Failed to initialize signer SDK:', error);
@@ -119,17 +251,85 @@ export const useTransactionSigner = () => {
   }, [isSignerInitialized]);
 
   /**
-   * Sign a blockchain transaction using JWT token (matching web frontend pattern)
+   * Sign and submit a blockchain transaction using JWT token
+   * 
+   * This is the main method for executing blockchain transactions in React Native.
+   * It handles the complete transaction lifecycle: authentication, signing, and
+   * blockchain submission in a single call.
+   * 
+   * **Process Flow:**
+   * 1. Validates the JWT token and extracts transaction data
+   * 2. Authenticates the user using WebAuthn (cached for 5 minutes)
+   * 3. Fetches transaction data from PERS backend
+   * 4. Signs the transaction using device security (biometrics/PIN)
+   * 5. Submits the signed transaction to the blockchain
+   * 6. Returns detailed result with transaction hash and status
+   * 
+   * **Security Features:**
+   * - JWT token validation and expiration checking
+   * - WebAuthn authentication with device biometrics
+   * - Secure transaction signing without exposing private keys
+   * - Automatic session management with secure caching
+   * 
+   * @param {string} jwt - JWT token containing transaction ID and user information
+   *   Must include: `transactionId`, `identifierEmail`, `tenantId`
+   * @returns {Promise<SubmissionResult>} Complete transaction result
+   * 
+   * @throws {Error} 'Transaction signer not initialized' - Hook not ready
+   * @throws {Error} 'PERS Signer SDK not available' - SDK installation issue
+   * @throws {Error} 'Invalid or expired JWT token' - Token validation failed
+   * @throws {Error} 'Authentication failed' - WebAuthn authentication failed
+   * @throws {Error} 'Transaction signing failed' - Signing process failed
+   * @throws {Error} 'Transaction submission failed' - Blockchain submission failed
    * 
-   * This method replicates the web frontend flow:
-   * 1. Extract transaction info from JWT
-   * 2. Authenticate user with WebAuthn 
-   * 3. Sign transaction with authenticated user
+   * @example
+   * **Basic Transaction:**
+   * ```typescript
+   * const { signAndSubmitTransactionWithJWT } = useTransactionSigner();
    * 
-   * @param jwt - JWT token from redemption flow containing transaction ID
-   * @returns Promise resolving to signing result with transaction hash
+   * const result = await signAndSubmitTransactionWithJWT(jwtToken);
+   * if (result.success) {
+   *   console.log('Transaction Hash:', result.transactionHash);
+   *   console.log('Blockchain explorer: [Chain-specific explorer URL]');
+   * }
+   * ```
+   * 
+   * @example
+   * **With Error Handling:**
+   * ```typescript
+   * try {
+   *   const result = await signAndSubmitTransactionWithJWT(redeemJWT);
+   *   
+   *   if (result.success) {
+   *     // Transaction successful
+   *     setTransactionHash(result.transactionHash);
+   *     
+   *     if (result.shouldRedirect && result.redirectUrl) {
+   *       // Handle post-transaction redirect
+   *       Linking.openURL(result.redirectUrl);
+   *     }
+   *   } else {
+   *     // Transaction failed but didn't throw
+   *     setError(result.error || 'Transaction failed');
+   *   }
+   * } catch (error) {
+   *   // Handle different error types
+   *   if (error.message.includes('expired')) {
+   *     // Token expired - redirect to login
+   *     navigation.navigate('Login');
+   *   } else if (error.message.includes('network')) {
+   *     // Network error - suggest retry
+   *     setError('Network error. Please try again.');
+   *   } else {
+   *     // Other errors
+   *     setError(error.message);
+   *   }
+   * }
+   * ```
+   * 
+   * @see {@link SubmissionResult} for detailed result structure
    */
-  const signTransactionWithJWT = useCallback(async (jwt: string): Promise<TransactionSigningResult> => {
+  const signAndSubmitTransactionWithJWT = useCallback(async (jwt: string): Promise<SubmissionResult> => {
     if (!isSignerInitialized || !signerSDKRef.current) {
       throw new Error('Transaction signer not initialized');
     }
@@ -138,128 +338,84 @@ export const useTransactionSigner = () => {
     }
 
     try {
-      console.log('[useTransactionSigner] Starting JWT-based transaction signing...');
-      
-      // Create URLSearchParams from JWT token (matching web frontend)
-      const searchParams = new URLSearchParams();
-      searchParams.set('jwt', jwt);
+      // Use the actual SDK method that handles the complete sign + submit flow
+      const submissionResult = await signerSDKRef.current.signAndSubmitPersTransaction(jwt);
       
-      // Step 1: Authenticate with JWT (handles tenant setup, project keys automatically)
-      console.log('[useTransactionSigner] Authenticating with JWT...');
-      const authResult = await signerSDKRef.current.authenticateWithJWT(searchParams);
-      
-      if (!authResult) {
-        throw new Error('JWT authentication failed - no valid token found');
-      }
-      
-      if (authResult.isExpired) {
-        throw new Error('JWT token is expired');
-      }
-      
-      console.log('[useTransactionSigner] JWT authentication successful:', authResult.user.identifier);
-      
-      // Step 2: Extract transaction ID from JWT
-      const jwtParts = jwt.split('.');
-      if (jwtParts.length !== 3) {
-        throw new Error('Invalid JWT token format');
-      }
-      
-      const payload = JSON.parse(atob(jwtParts[1]));
-      const transactionId = payload.transactionId;
-      
-      if (!transactionId) {
-        throw new Error('No transaction ID found in JWT token');
-      }
-      
-      console.log('[useTransactionSigner] Found transaction ID:', transactionId);
-      
-      // Step 3: Sign transaction using authenticated user
-      console.log('[useTransactionSigner] Signing transaction...');
-      const signingResult = await signerSDKRef.current.signPersTransaction(
-        authResult.user, 
-        transactionId
-      );
-      
-      console.log('[useTransactionSigner] Transaction signing result:', signingResult);
-      
-      return {
-        success: signingResult.success,
-        transactionHash: signingResult.transactionHash,
-        error: signingResult.error
-      };
+      return submissionResult;
       
     } catch (error) {
       console.error('[useTransactionSigner] JWT transaction signing failed:', error);
-      return {
-        success: false,
-        error: `Transaction signing failed: ${error}`
-      };
+      throw error; // Re-throw to maintain error handling upstream
     }
   }, [isSignerInitialized]);
 
-  /**
-   * Manual user authentication (fallback method)
-   */
-  const authenticateUser = useCallback(async (identifier: string): Promise<SignerAuthenticatedUser | null> => {
-    if (!isSignerInitialized || !signerSDKRef.current) {
-      throw new Error('Transaction signer not initialized');
-    }
-
-    try {
-      console.log('[useTransactionSigner] Manual user authentication:', identifier);
-      const user = await signerSDKRef.current.authenticateUser(identifier);
-      console.log('[useTransactionSigner] Manual authentication successful');
-      return user;
-    } catch (error) {
-      console.error('[useTransactionSigner] Manual authentication failed:', error);
-      return null;
-    }
-  }, [isSignerInitialized]);
-
-  /**
-   * Legacy method for backward compatibility
-   * @deprecated Use signTransactionWithJWT instead
-   */
-  const signTransaction = useCallback(async (jwt: string): Promise<TransactionSigningResult> => {
-    console.warn('[useTransactionSigner] signTransaction is deprecated, use signTransactionWithJWT');
-    return signTransactionWithJWT(jwt);
-  }, [signTransactionWithJWT]);
-
   return {
     /**
-     * Sign a blockchain transaction using JWT token (recommended method)
-     */
-    signTransactionWithJWT,
-    
-    /**
-     * Legacy transaction signing method
-     * @deprecated Use signTransactionWithJWT instead
-     */
-    signTransaction,
-    
-    /**
-     * Manual user authentication (for advanced use cases)
+     * Sign and submit a blockchain transaction using JWT token
+     * 
+     * Main method for executing blockchain transactions. Handles complete flow
+     * from authentication to blockchain submission in a single call.
+     * 
+     * @param {string} jwt - JWT token with transaction and user data
+     * @returns {Promise<SubmissionResult>} Transaction result with hash and status
      */
-    authenticateUser,
+    signAndSubmitTransactionWithJWT,
     
     /**
-     * Whether the transaction signer has been initialized
+     * Whether the transaction signer SDK has been successfully initialized
+     * 
+     * Use this to show loading states while the signer is being set up.
+     * When `false`, the signer is still initializing and transactions cannot be processed.
+     * 
+     * @example
+     * ```typescript
+     * const { isSignerInitialized } = useTransactionSigner();
+     * 
+     * if (!isSignerInitialized) {
+     *   return <LoadingSpinner text="Initializing signer..." />;
+     * }
+     * ```
      */
     isSignerInitialized,
     
     /**
-     * Whether transaction signing is available (all requirements met)
+     * Whether blockchain transaction signing is fully available
+     * 
+     * This combines multiple checks: SDK availability, initialization status,
+     * and configuration validity. Use this to enable/disable transaction buttons.
+     * 
+     * Returns `true` only when:
+     * - PERS Signer SDK is installed and available
+     * - Signer has been successfully initialized
+     * - All required dependencies are loaded
+     * 
+     * @example
+     * ```typescript
+     * const { isSignerAvailable } = useTransactionSigner();
+     * 
+     * return (
+     *   <TouchableOpacity 
+     *     disabled={!isSignerAvailable}
+     *     style={[styles.button, !isSignerAvailable && styles.disabled]}
+     *   >
+     *     <Text>{isSignerAvailable ? 'Sign Transaction' : 'Signer Unavailable'}</Text>
+     *   </TouchableOpacity>
+     * );
+     * ```
      */
     isSignerAvailable: isSignerInitialized && !!createPersSignerSDK,
   };
 };
 
 /**
- * Type definition for the transaction signer hook
- */
-export type TransactionSignerHook = ReturnType<typeof useTransactionSigner>;
-
-/**
- * Export the transaction signing result type for external usage
+ * Type exports for external usage
+ * 
+ * These types are re-exported from the PERS Signer SDK for convenience
+ * when working with transaction signing in React Native applications.
+ * 
+ * @see {@link SubmissionResult} - Complete transaction submission result
+ * @see {@link AuthenticatedUser} - User authentication data structure  
+ * @see {@link TransactionSigningResult} - Transaction signing result details
+ * @see {@link TransactionSignerHook} - Hook return interface
  */
-export type { TransactionSigningResult, SignerAuthenticatedUser, AuthenticationResult };
+export type { SubmissionResult, AuthenticatedUser, TransactionSigningResult };

package/src/hooks/useTransactions.ts

@@ -4,7 +4,8 @@ import { useTransactionSigner } from './useTransactionSigner';
 import type { 
   TransactionRequestDTO, 
   TransactionRequestResponseDTO, 
-  TransactionDTO
+  TransactionDTO,
+  TransactionRole
 } from '@explorins/pers-shared';
 import type { TransactionPaginationParams } from '@explorins/pers-sdk/transaction';
 
@@ -46,7 +47,7 @@ import type { TransactionPaginationParams } from '@explorins/pers-sdk/transactio
  */
 export const useTransactions = () => {
   const { sdk, isInitialized, isAuthenticated } = usePersSDK();
-  const { signTransactionWithJWT, isSignerAvailable } = useTransactionSigner();
+  const { signAndSubmitTransactionWithJWT, isSignerAvailable } = useTransactionSigner();
 
   if (!isAuthenticated && isInitialized) {
     console.warn('SDK not authenticated. Some transaction operations may fail.');
@@ -97,7 +98,7 @@ export const useTransactions = () => {
           }
 
           // Automatically sign the transaction using the authToken
-          const signingResult = await signTransactionWithJWT(txToken);
+          const signingResult = await signAndSubmitTransactionWithJWT(txToken);
           
           if (signingResult.success) {
             console.log('[useTransactions] Transaction signed successfully:', signingResult.transactionHash);
@@ -120,7 +121,7 @@ export const useTransactions = () => {
       console.error('Failed to create transaction:', error);
       throw error;
     }
-  }, [sdk, isInitialized, signTransactionWithJWT, isSignerAvailable]);
+  }, [sdk, isInitialized, signAndSubmitTransactionWithJWT, isSignerAvailable]);
 
   /**
    * Retrieves a specific transaction by its ID
@@ -152,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) {
@@ -187,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/hooks/useWeb3.ts

@@ -9,7 +9,14 @@ import type {
 } from '@explorins/pers-sdk/web3';
 import type { ChainData } from '@explorins/pers-sdk/web3-chain';
 
-interface WalletInfo {
+/**
+ * Wallet information interface
+ * 
+ * @interface WalletInfo
+ * @property {string | null} address - Wallet address if connected
+ * @property {boolean} isConnected - Whether wallet is connected
+ */
+export interface WalletInfo {
   address: string | null;
   isConnected: boolean;
 }