@explorins/pers-sdk-react-native 1.5.36 → 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/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';