@explorins/pers-sdk-react-native 1.5.35 → 2.0.0

package/src/hooks/useTokens.ts

@@ -1,6 +1,6 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
-import type { TokenDTO } from '@explorins/pers-shared';
+import type { TokenDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
 
 /**
  * React hook for token operations in the PERS SDK
@@ -50,7 +50,7 @@ export const useTokens = () => {
    * console.log('Available tokens:', tokens);
    * ```
    */
-  const getTokens = useCallback(async (): Promise<TokenDTO[]> => {
+  const getTokens = useCallback(async (): Promise<PaginatedResponseDTO<TokenDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
@@ -104,7 +104,7 @@ export const useTokens = () => {
    * console.log('Reward tokens:', rewardTokens);
    * ```
    */
-  const getRewardTokens = useCallback(async (): Promise<TokenDTO[]> => {
+  const getRewardTokens = useCallback(async (): Promise<PaginatedResponseDTO<TokenDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
@@ -158,7 +158,7 @@ export const useTokens = () => {
    * console.log('Status tokens:', statusTokens);
    * ```
    */
-  const getStatusTokens = useCallback(async (): Promise<TokenDTO[]> => {
+  const getStatusTokens = useCallback(async (): Promise<PaginatedResponseDTO<TokenDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }

package/src/hooks/useTransactionSigner.ts

@@ -38,6 +38,7 @@ try {
  * 
  * @interface TransactionSignerHook
  * @property {Function} signAndSubmitTransactionWithJWT - Main method to sign and submit transactions
+ * @property {Function} signPersTransaction - Sign transaction without submitting (for POS flows)
  * @property {boolean} isSignerInitialized - Whether the signer SDK has been initialized
  * @property {boolean} isSignerAvailable - Whether signing functionality is fully available
  * @property {SigningStatus | null} currentStatus - Current signing status for UI feedback
@@ -45,6 +46,7 @@ try {
  */
 export interface TransactionSignerHook {
   signAndSubmitTransactionWithJWT: (jwt: string, onStatusUpdate?: OnStatusUpdateFn) => Promise<SubmissionResult>;
+  signPersTransaction: (jwt: string, onStatusUpdate?: OnStatusUpdateFn) => Promise<TransactionSigningResult>;
   isSignerInitialized: boolean;
   isSignerAvailable: boolean;
   currentStatus: SigningStatus | null;
@@ -386,6 +388,65 @@ export const useTransactionSigner = (): TransactionSignerHook => {
     }
   }, [isSignerInitialized]);
 
+  /**
+   * Sign a PERS transaction without submitting (for POS flows with QR codes)
+   * 
+   * This method signs the transaction but does NOT submit it to the blockchain.
+   * Instead, it returns the signature which can be displayed as a QR code for
+   * the business to scan and submit.
+   * 
+   * **Use Case:** Point-of-Sale (POS) flows where:
+   * 1. User signs the transaction
+   * 2. App generates QR code with signature
+   * 3. Business scans QR code
+   * 4. Business submits transaction to blockchain
+   * 
+   * @param {string} jwt - JWT token with transaction and user data
+   * @param {StatusCallback} [onStatusUpdate] - Optional callback for status updates
+   * @returns {Promise<TransactionSigningResult>} Signing result with signature for QR code
+   * 
+   * @example
+   * ```typescript
+   * const { signPersTransaction } = useTransactionSigner();
+   * 
+   * const result = await signPersTransaction(jwtToken);
+   * if (result.success) {
+   *   const qrData = {
+   *     transactionId: result.transactionId,
+   *     signature: result.signature,
+   *     transactionFormat: result.signingData.format,
+   *     txType: 'PENDING_SUBMISSION'
+   *   };
+   *   // Display QR code with qrData
+   * }
+   * ```
+   */
+  const signPersTransaction = useCallback(async (jwt: string, onStatusUpdate?: OnStatusUpdateFn): Promise<TransactionSigningResult> => {
+    if (!isSignerInitialized || !signerSDKRef.current) {
+      throw new Error('Signer SDK not initialized');
+    }
+
+    // Create status callback wrapper
+    const statusCallback: StatusCallback = {
+      onStatusUpdate: (status: SigningStatus, message: string, data?: StatusUpdateData) => {
+        setCurrentStatus(status);
+        setStatusMessage(message);
+        onStatusUpdate?.(status, message, data);
+      }
+    };
+
+    try {
+      // Use the SDK's sign-only method
+      const signingResult = await signerSDKRef.current.signPersTransaction(jwt, statusCallback);
+      return signingResult;
+    } catch (error) {
+      console.error('[useTransactionSigner] Sign-only transaction failed:', error);
+      setCurrentStatus(SigningStatus.ERROR);
+      setStatusMessage(error instanceof Error ? error.message : 'Signing failed');
+      throw error;
+    }
+  }, [isSignerInitialized]);
+
   return {
     /**
      * Sign and submit a blockchain transaction using JWT token
@@ -398,6 +459,18 @@ export const useTransactionSigner = (): TransactionSignerHook => {
      * @returns {Promise<SubmissionResult>} Transaction result with hash and status
      */
     signAndSubmitTransactionWithJWT,
+
+    /**
+     * Sign a transaction without submitting (for POS flows)
+     * 
+     * Signs the transaction and returns the signature without submitting to blockchain.
+     * Use this for Point-of-Sale flows where the business scans a QR code and submits.
+     * 
+     * @param {string} jwt - JWT token with transaction and user data
+     * @param {StatusCallback} [onStatusUpdate] - Optional callback for status updates
+     * @returns {Promise<TransactionSigningResult>} Signing result with signature for QR code
+     */
+    signPersTransaction,
     
     /**
      * Whether the transaction signer SDK has been successfully initialized

package/src/hooks/useTransactions.ts

@@ -6,7 +6,8 @@ import type {
   TransactionRequestResponseDTO, 
   TransactionDTO,
   TransactionRole,
-  TransactionPaginationRequestDTO
+  TransactionPaginationRequestDTO,
+  PaginatedResponseDTO
 } from '@explorins/pers-shared';
 
 /**
@@ -164,7 +165,7 @@ export const useTransactions = () => {
    * const allTransactions = await getUserTransactionHistory(); // No filter
    * ```
    */
-  const getUserTransactionHistory = useCallback(async (role?: TransactionRole): Promise<TransactionDTO[]> => {
+  const getUserTransactionHistory = useCallback(async (role?: TransactionRole): Promise<PaginatedResponseDTO<TransactionDTO>> => {
     
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
@@ -179,7 +180,7 @@ export const useTransactions = () => {
     }
   }, [sdk, isInitialized]);
 
-  const getTenantTransactions = useCallback(async (): Promise<TransactionDTO[]> => {
+  const getTenantTransactions = useCallback(async (): Promise<PaginatedResponseDTO<TransactionDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }

package/src/hooks/useUserStatus.ts

@@ -1,11 +1,11 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
-import type { UserStatusTypeDTO } from '@explorins/pers-shared';
+import type { UserStatusTypeDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
 
 export const useUserStatus = () => {
   const { sdk, isInitialized, isAuthenticated } = usePersSDK();
 
-  const getUserStatusTypes = useCallback(async (): Promise<UserStatusTypeDTO[]> => {
+  const getUserStatusTypes = useCallback(async (): Promise<PaginatedResponseDTO<UserStatusTypeDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
@@ -19,7 +19,7 @@ export const useUserStatus = () => {
     }
   }, [sdk, isInitialized]);
 
-  const getEarnedUserStatus = useCallback(async (): Promise<UserStatusTypeDTO[]> => {
+  const getEarnedUserStatus = useCallback(async (): Promise<PaginatedResponseDTO<UserStatusTypeDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }

package/src/hooks/useUsers.ts

@@ -1,6 +1,6 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
-import type { UserDTO, UserCreateRequestDTO } from '@explorins/pers-shared';
+import type { UserDTO, UserCreateRequestDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
 import type { UserPublicProfileDTO } from '@explorins/pers-sdk/user';
 
 export const useUsers = () => {
@@ -54,7 +54,7 @@ export const useUsers = () => {
     }
   }, [sdk, isInitialized]);
 
-  const getAllUsersPublic = useCallback(async (filter?: { key: string; value: string }): Promise<UserPublicProfileDTO[]> => {
+  const getAllUsersPublic = useCallback(async (filter?: { key: string; value: string }): Promise<PaginatedResponseDTO<UserPublicProfileDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
@@ -69,7 +69,7 @@ export const useUsers = () => {
   }, [sdk, isInitialized]);
 
   // Admin methods
-  const getAllUsers = useCallback(async (): Promise<UserDTO[]> => {
+  const getAllUsers = useCallback(async (): Promise<PaginatedResponseDTO<UserDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }

package/src/hooks/useWeb3.ts

@@ -9,19 +9,10 @@ import type {
 } from '@explorins/pers-sdk/web3';
 import type { ChainData } from '@explorins/pers-sdk/web3-chain';
 import type { TokenDTO } from '@explorins/pers-shared';
-import { NativeTokenTypes } from '@explorins/pers-shared';
+import type { AccountOwnedTokensResult } from '@explorins/pers-sdk';
 
-/**
- * Result of getting user's owned tokens from a contract
- */
-export interface UserOwnedTokensResult {
-  /** The token definition (contains contract info, ABI, metadata definitions) */
-  token: TokenDTO;
-  /** Array of token balances the user owns (filtered to hasBalance: true) */
-  ownedTokens: readonly TokenBalance[];
-  /** Total count of owned tokens */
-  totalOwned: number;
-}
+// Re-export for convenience
+export type { AccountOwnedTokensResult } from '@explorins/pers-sdk';
 
 /**
  * React hook for Web3 operations in the PERS SDK
@@ -32,48 +23,9 @@ export interface UserOwnedTokensResult {
  * 
  * Note: Wallet addresses should be obtained from `user.wallets` via `usePersSDK()`.
  * 
- * ## ERC-1155 Token Handling
- * 
- * **IMPORTANT**: ERC-1155 tokens require specific `tokenIds` to query balances.
- * Unlike ERC-721, you cannot enumerate owned tokens - you must know which tokenId to check.
- * 
- * The tokenIds come from `TokenDTO.metadata[].tokenMetadataIncrementalId`.
- * 
- * ### Option 1: Use the helper method (Recommended)
- * ```typescript
- * const { getUserOwnedTokensFromContract } = useWeb3();
- * const { getRewardTokens } = useTokens();
- * 
- * const rewardTokens = await getRewardTokens();
- * const result = await getUserOwnedTokensFromContract(walletAddress, rewardTokens[0]);
- * console.log('Owned rewards:', result.ownedTokens);
- * ```
- * 
- * ### Option 2: Manual tokenIds extraction
- * ```typescript
- * const { getTokenCollection, extractTokenIds } = useWeb3();
- * const { getRewardTokens } = useTokens();
- * 
- * const rewardTokens = await getRewardTokens();
- * const rewardToken = rewardTokens[0];
- * 
- * // Extract tokenIds for ERC-1155
- * const tokenIds = extractTokenIds(rewardToken);
- * 
- * const collection = await getTokenCollection({
- *   accountAddress: walletAddress,
- *   contractAddress: rewardToken.contractAddress,
- *   abi: rewardToken.abi,
- *   chainId: rewardToken.chainId,
- *   tokenIds: tokenIds  // Required for ERC-1155!
- * });
- * 
- * const ownedTokens = collection.tokens.filter(t => t.hasBalance);
- * ```
- * 
  * @returns Web3 hook with methods for blockchain operations
  * 
- * @example Basic Usage
+ * @example
  * ```typescript
  * function Web3Component() {
  *   const { user } = usePersSDK();
@@ -199,152 +151,6 @@ export const useWeb3 = () => {
     }
   }, [sdk, isInitialized]);
 
-  /**
-   * Extract tokenIds from a TokenDTO for use with ERC-1155 contracts.
-   * 
-   * ERC-1155 tokens require specific tokenIds to query balances. This helper
-   * extracts the `tokenMetadataIncrementalId` from each metadata entry.
-   * 
-   * @param token - Token definition containing metadata array
-   * @returns Array of tokenId strings, or undefined if no metadata
-   * 
-   * @example
-   * ```typescript
-   * const { extractTokenIds, getTokenCollection } = useWeb3();
-   * const { getRewardTokens } = useTokens();
-   * 
-   * const rewardToken = (await getRewardTokens())[0];
-   * const tokenIds = extractTokenIds(rewardToken);
-   * 
-   * if (tokenIds) {
-   *   const collection = await getTokenCollection({
-   *     accountAddress: walletAddress,
-   *     contractAddress: rewardToken.contractAddress,
-   *     abi: rewardToken.abi,
-   *     chainId: rewardToken.chainId,
-   *     tokenIds: tokenIds
-   *   });
-   * }
-   * ```
-   */
-  const extractTokenIds = useCallback((token: TokenDTO): string[] | undefined => {
-    if (!token.metadata || token.metadata.length === 0) {
-      return undefined;
-    }
-    return token.metadata.map(meta => meta.tokenMetadataIncrementalId.toString());
-  }, []);
-
-  /**
-   * Get user's owned tokens from a specific token contract.
-   * 
-   * This is a convenience method that automatically handles:
-   * - ERC-1155 tokenId extraction from metadata
-   * - Building the collection request
-   * - Filtering to only tokens with balance > 0
-   * 
-   * **This is the recommended way to get user's owned reward/status tokens.**
-   * 
-   * @param walletAddress - User's wallet address
-   * @param token - Token definition (from getRewardTokens, getStatusTokens, etc.)
-   * @param maxTokens - Maximum tokens to retrieve (default: 50)
-   * @returns Promise resolving to result with owned tokens
-   * @throws Error if SDK is not initialized
-   * 
-   * @example Get User's Owned Rewards
-   * ```typescript
-   * const { user } = usePersSDK();
-   * const { getRewardTokens } = useTokens();
-   * const { getUserOwnedTokensFromContract } = useWeb3();
-   * 
-   * const walletAddress = user?.wallets?.[0]?.address;
-   * const rewardTokens = await getRewardTokens();
-   * 
-   * for (const token of rewardTokens) {
-   *   const result = await getUserOwnedTokensFromContract(walletAddress, token);
-   *   
-   *   console.log(`${token.name}: ${result.totalOwned} owned`);
-   *   result.ownedTokens.forEach(owned => {
-   *     console.log(`  - TokenId ${owned.tokenId}: ${owned.balance}`);
-   *     console.log(`    Name: ${owned.metadata?.name}`);
-   *     console.log(`    Image: ${owned.metadata?.imageUrl}`);
-   *   });
-   * }
-   * ```
-   */
-  const getUserOwnedTokensFromContract = useCallback(async (
-    walletAddress: string,
-    token: TokenDTO,
-    maxTokens: number = 50
-  ): Promise<UserOwnedTokensResult> => {
-    if (!isInitialized || !sdk) {
-      throw new Error('SDK not initialized. Call initialize() first.');
-    }
-
-    try {
-      // For ERC-1155, extract tokenIds from metadata
-      const tokenIds = token.type === NativeTokenTypes.ERC1155 ? extractTokenIds(token) : undefined;
-
-      const collection = await sdk.web3.getTokenCollection({
-        accountAddress: walletAddress,
-        contractAddress: token.contractAddress,
-        abi: token.abi,
-        chainId: token.chainId,
-        tokenIds,
-        maxTokens
-      });
-
-      // Filter to only owned tokens (hasBalance: true)
-      // For ERC721, include all since they're enumerated
-      const ownedTokens = token.type === NativeTokenTypes.ERC721
-        ? collection.tokens
-        : collection.tokens.filter(t => t.hasBalance);
-
-      return {
-        token,
-        ownedTokens,
-        totalOwned: ownedTokens.length
-      };
-    } catch (error) {
-      console.error('Failed to get user owned tokens:', error);
-      throw error;
-    }
-  }, [sdk, isInitialized, extractTokenIds]);
-
-  /**
-   * Build a TokenCollectionRequest from a TokenDTO.
-   * 
-   * Automatically handles ERC-1155 tokenId extraction from metadata.
-   * Use this when you need more control over the request than 
-   * `getUserOwnedTokensFromContract` provides.
-   * 
-   * @param walletAddress - User's wallet address
-   * @param token - Token definition
-   * @param maxTokens - Maximum tokens to retrieve (default: 50)
-   * @returns TokenCollectionRequest ready for getTokenCollection()
-   * 
-   * @example
-   * ```typescript
-   * const { buildCollectionRequest, getTokenCollection } = useWeb3();
-   * 
-   * const request = buildCollectionRequest(walletAddress, rewardToken);
-   * const collection = await getTokenCollection(request);
-   * ```
-   */
-  const buildCollectionRequest = useCallback((
-    walletAddress: string,
-    token: TokenDTO,
-    maxTokens: number = 50
-  ): TokenCollectionRequest => {
-    return {
-      accountAddress: walletAddress,
-      contractAddress: token.contractAddress,
-      abi: token.abi,
-      chainId: token.chainId,
-      tokenIds: token.type === NativeTokenTypes.ERC1155 ? extractTokenIds(token) : undefined,
-      maxTokens
-    };
-  }, [extractTokenIds]);
-
   const resolveIPFSUrl = useCallback(async (url: string, chainId: number): Promise<string> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
@@ -401,8 +207,99 @@ export const useWeb3 = () => {
     }
   }, [sdk, isInitialized]);
 
+  // ==========================================
+  // HELPER METHODS (delegating to core SDK)
+  // ==========================================
+
+  /**
+   * Extract tokenIds from a TokenDTO's metadata.
+   * 
+   * Extracts `tokenMetadataIncrementalId` from each metadata entry. This is
+   * particularly useful for ERC-1155 tokens which require specific tokenIds
+   * to query balances, but works with any token that has metadata.
+   * 
+   * **Note:** For most use cases, prefer `getAccountOwnedTokensFromContract()`
+   * which handles tokenId extraction automatically.
+   * 
+   * @param token - Token definition containing metadata array
+   * @returns Array of tokenId strings, or undefined if no metadata
+   * 
+   * @see {@link getAccountOwnedTokensFromContract} - Recommended helper that handles this automatically
+   */
+  const extractTokenIds = useCallback((token: TokenDTO): string[] | undefined => {
+    // Pure function - delegates to core SDK (no initialization required)
+    return sdk?.web3.extractTokenIds(token);
+  }, [sdk]);
+
+  /**
+   * Get owned tokens from a specific token contract for any blockchain address.
+   * 
+   * **Recommended method** for querying token balances. Automatically handles:
+   * - Token type detection (ERC-20, ERC-721, ERC-1155)
+   * - TokenId extraction from metadata (uses `extractTokenIds()` internally for ERC-1155)
+   * - Building the collection request
+   * - Filtering to only tokens with balance > 0
+   * 
+   * Works with any valid blockchain address - can query user wallets, external
+   * wallets, contract addresses, or any other address holding tokens.
+   * 
+   * @param accountAddress - Any valid blockchain address (wallet, contract, etc.)
+   * @param token - Token definition (from getRewardTokens, getStatusTokens, etc.)
+   * @param maxTokens - Maximum tokens to retrieve (default: 50)
+   * @returns Promise resolving to result with owned tokens
+   * @throws Error if SDK is not initialized
+   * 
+   * @example Query user's wallet
+   * ```typescript
+   * const { user } = usePersSDK();
+   * const { getAccountOwnedTokensFromContract } = useWeb3();
+   * const { getRewardTokens } = useTokens();
+   * 
+   * const userWallet = user?.wallets?.[0]?.address;
+   * const rewardTokens = await getRewardTokens();
+   * const result = await getAccountOwnedTokensFromContract(userWallet, rewardTokens[0]);
+   * console.log(`User owns ${result.totalOwned} tokens`);
+   * ```
+   * 
+   * @see {@link extractTokenIds} - Low-level helper used internally for ERC-1155
+   * @see {@link buildCollectionRequest} - For manual request building
+   */
+  const getAccountOwnedTokensFromContract = useCallback(async (
+    accountAddress: string,
+    token: TokenDTO,
+    maxTokens: number = 50
+  ): Promise<AccountOwnedTokensResult> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+
+    return sdk.web3.getAccountOwnedTokensFromContract(accountAddress, token, maxTokens);
+  }, [sdk, isInitialized]);
+
+  /**
+   * Build a TokenCollectionRequest from a TokenDTO.
+   * 
+   * Automatically handles ERC-1155 tokenId extraction from metadata.
+   * Use this when you need more control over the request than 
+   * `getAccountOwnedTokensFromContract` provides.
+   * 
+   * @param accountAddress - Any valid blockchain address (wallet, contract, etc.)
+   * @param token - Token definition
+   * @param maxTokens - Maximum tokens to retrieve (default: 50)
+   * @returns TokenCollectionRequest ready for getTokenCollection()
+   */
+  const buildCollectionRequest = useCallback((
+    accountAddress: string,
+    token: TokenDTO,
+    maxTokens: number = 50
+  ): TokenCollectionRequest => {
+    if (!sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    return sdk.web3.buildCollectionRequest(accountAddress, token, maxTokens);
+  }, [sdk]);
+
   return {
-    // Core methods
     getTokenBalance,
     getTokenMetadata,
     getTokenCollection,
@@ -410,11 +307,10 @@ export const useWeb3 = () => {
     fetchAndProcessMetadata,
     getChainDataById,
     getExplorerUrl,
-    // Helper methods for ERC-1155 tokens
+    // Helper methods
     extractTokenIds,
-    getUserOwnedTokensFromContract,
+    getAccountOwnedTokensFromContract,
     buildCollectionRequest,
-    // State
     isAvailable: isInitialized && !!sdk?.web3,
   };
 };

package/src/index.ts

@@ -182,6 +182,7 @@ export {
  * - `useAnalytics` - Usage analytics and reporting
  * - `useFiles` - File upload and management
  * - `useWeb3` - Blockchain integration and wallet operations
+ * - `useEvents` - ** SDK event subscriptions for notifications**
  * 
  * @example
  * **Token Operations:**
@@ -222,6 +223,26 @@ export {
  *   };
  * }
  * ```
+ * 
+ * @example
+ * **Event Subscriptions:**
+ * ```typescript
+ * import { useEvents, useEffect } from '@explorins/pers-sdk-react-native';
+ * 
+ * function NotificationHandler() {
+ *   const { subscribe, isAvailable } = useEvents();
+ *   
+ *   useEffect(() => {
+ *     if (!isAvailable) return;
+ *     
+ *     const unsubscribe = subscribe((event) => {
+ *       showNotification(event.userMessage, event.level);
+ *     });
+ *     
+ *     return () => unsubscribe();
+ *   }, [subscribe, isAvailable]);
+ * }
+ * ```
  */
 export {
   useAuth,
@@ -239,12 +260,16 @@ export {
   useUserStatus,
   useFiles,
   useAnalytics,
-  useDonations
+  useDonations,
+  useEvents
 } from './hooks';
 
 // Re-export signing status types for convenience
 export type { OnStatusUpdateFn, StatusUpdateData, SigningStatusType } from './hooks';
 
+// Re-export event types for convenience
+export type { EventsHook, PersEvent, EventHandler, EventFilter, Unsubscribe } from './hooks';
+
 // ==============================================================================
 // PLATFORM ADAPTERS
 // ==============================================================================
@@ -317,4 +342,82 @@ export type {
   TokenMetadata, 
   TokenCollection,
   TokenCollectionRequest
-} from '@explorins/pers-sdk/web3';
+} from '@explorins/pers-sdk/web3';
+
+// ==============================================================================
+// TRANSACTION REQUEST FACTORY FUNCTIONS
+// ==============================================================================
+
+/**
+ * Transaction Request Factory Functions
+ * 
+ * Factory functions for creating properly structured transaction DTOs.
+ * Prioritizes accountId/accountType over raw addresses for security and consistency.
+ * 
+ * @example
+ * ```typescript
+ * import { 
+ *   buildMintRequest, 
+ *   buildTransferRequest, 
+ *   buildBurnRequest,
+ *   useTransactions,
+ *   AccountOwnerType 
+ * } from '@explorins/pers-sdk-react-native';
+ * 
+ * function TokenOperations() {
+ *   const { createTransaction } = useTransactions();
+ * 
+ *   const handleMint = async () => {
+ *     const request = buildMintRequest({
+ *       amount: 100,
+ *       contractAddress: '0x...',
+ *       chainId: 137,
+ *       recipientAccountType: AccountOwnerType.USER,
+ *       recipientAccountId: 'user-123'
+ *     });
+ *     await createTransaction(request);
+ *   };
+ * }
+ * ```
+ * 
+ * @see {@link buildMintRequest} - Create mint transaction requests
+ * @see {@link buildBurnRequest} - Create burn transaction requests  
+ * @see {@link buildTransferRequest} - Create transfer transaction requests
+ * @see {@link buildPOSTransferRequest} - Create POS transfer requests (business submits on behalf of user)
+ * @see {@link buildPOSBurnRequest} - Create POS burn requests (business submits burn on behalf of user)
+ * @see {@link buildSubmissionRequest} - Create submission requests from QR/signature data
+ */
+export {
+  buildMintRequest,
+  buildBurnRequest,
+  buildTransferRequest,
+  buildPOSTransferRequest,
+  buildPOSBurnRequest,
+  buildSubmissionRequest
+} from '@explorins/pers-sdk/transaction';
+
+export type { POSAuthorizationOptions } from '@explorins/pers-sdk/transaction';
+
+// ==============================================================================
+// ERROR CLASSES (for instanceof checks)
+// ==============================================================================
+
+/**
+ * SDK Error classes for type checking in catch blocks
+ * 
+ * @example
+ * ```typescript
+ * import { PersApiError } from '@explorins/pers-sdk-react-native';
+ * 
+ * try {
+ *   await sdk.campaigns.claimCampaign({ campaignId });
+ * } catch (error) {
+ *   if (error instanceof PersApiError) {
+ *     console.log(error.message);  // Clean backend message
+ *     console.log(error.code);     // e.g., 'CAMPAIGN_BUSINESS_REQUIRED'
+ *     console.log(error.status);   // e.g., 400
+ *   }
+ * }
+ * ```
+ */
+export { PersApiError, AuthenticationError } from '@explorins/pers-sdk/core';