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

package/dist/hooks/useTransactionSigner.js

@@ -338,6 +338,63 @@ export const useTransactionSigner = () => {
             throw error; // Re-throw to maintain error handling upstream
         }
     }, [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, onStatusUpdate) => {
+        if (!isSignerInitialized || !signerSDKRef.current) {
+            throw new Error('Signer SDK not initialized');
+        }
+        // Create status callback wrapper
+        const statusCallback = {
+            onStatusUpdate: (status, message, data) => {
+                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
@@ -350,6 +407,17 @@ export const useTransactionSigner = () => {
          * @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/dist/hooks/useTransactions.d.ts

@@ -1,5 +1,5 @@
 import { OnStatusUpdateFn } from './useTransactionSigner';
-import type { TransactionRequestDTO, TransactionRequestResponseDTO, TransactionDTO, TransactionRole, TransactionPaginationRequestDTO } from '@explorins/pers-shared';
+import type { TransactionRequestDTO, TransactionRequestResponseDTO, TransactionDTO, TransactionRole, TransactionPaginationRequestDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
 /**
  * React hook for transaction operations in the PERS SDK
  *
@@ -39,8 +39,8 @@ import type { TransactionRequestDTO, TransactionRequestResponseDTO, TransactionD
 export declare const useTransactions: () => {
     createTransaction: (request: TransactionRequestDTO, onStatusUpdate?: OnStatusUpdateFn) => Promise<TransactionRequestResponseDTO>;
     getTransactionById: (transactionId: string) => Promise<TransactionDTO | null>;
-    getUserTransactionHistory: (role?: TransactionRole) => Promise<TransactionDTO[]>;
-    getTenantTransactions: () => Promise<TransactionDTO[]>;
+    getUserTransactionHistory: (role?: TransactionRole) => Promise<PaginatedResponseDTO<TransactionDTO>>;
+    getTenantTransactions: () => Promise<PaginatedResponseDTO<TransactionDTO>>;
     getPaginatedTransactions: (params: TransactionPaginationRequestDTO) => Promise<any>;
     exportTransactionsCSV: () => Promise<Blob>;
     isAvailable: boolean;

package/dist/hooks/useTransactions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTransactions.d.ts","sourceRoot":"","sources":["../../src/hooks/useTransactions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwB,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,KAAK,EACV,qBAAqB,EACrB,6BAA6B,EAC7B,cAAc,EACd,eAAe,EACf,+BAA+B,EAChC,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,eAAe;iCAgC4B,qBAAqB,mBAAmB,gBAAgB,KAAG,QAAQ,6BAA6B,CAAC;wCA2D1F,MAAM,KAAG,QAAQ,cAAc,GAAG,IAAI,CAAC;uCA4BxC,eAAe,KAAG,QAAQ,cAAc,EAAE,CAAC;iCAenD,QAAQ,cAAc,EAAE,CAAC;uCAcjB,+BAA+B,KAAG,QAAQ,GAAG,CAAC;iCActD,QAAQ,IAAI,CAAC;;;;CA0BlE,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC"}
+{"version":3,"file":"useTransactions.d.ts","sourceRoot":"","sources":["../../src/hooks/useTransactions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwB,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,KAAK,EACV,qBAAqB,EACrB,6BAA6B,EAC7B,cAAc,EACd,eAAe,EACf,+BAA+B,EAC/B,oBAAoB,EACrB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,eAAe;iCAgC4B,qBAAqB,mBAAmB,gBAAgB,KAAG,QAAQ,6BAA6B,CAAC;wCA2D1F,MAAM,KAAG,QAAQ,cAAc,GAAG,IAAI,CAAC;uCA4BxC,eAAe,KAAG,QAAQ,qBAAqB,cAAc,CAAC,CAAC;iCAevE,QAAQ,qBAAqB,cAAc,CAAC,CAAC;uCAcrC,+BAA+B,KAAG,QAAQ,GAAG,CAAC;iCActD,QAAQ,IAAI,CAAC;;;;CA0BlE,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/hooks/useUserStatus.d.ts

@@ -1,7 +1,7 @@
-import type { UserStatusTypeDTO } from '@explorins/pers-shared';
+import type { UserStatusTypeDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
 export declare const useUserStatus: () => {
-    getUserStatusTypes: () => Promise<UserStatusTypeDTO[]>;
-    getEarnedUserStatus: () => Promise<UserStatusTypeDTO[]>;
+    getUserStatusTypes: () => Promise<PaginatedResponseDTO<UserStatusTypeDTO>>;
+    getEarnedUserStatus: () => Promise<PaginatedResponseDTO<UserStatusTypeDTO>>;
     createUserStatusType: (userStatusType: UserStatusTypeDTO) => Promise<UserStatusTypeDTO>;
     isAvailable: boolean;
 };

package/dist/hooks/useUserStatus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useUserStatus.d.ts","sourceRoot":"","sources":["../../src/hooks/useUserStatus.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,eAAO,MAAM,aAAa;8BAGyB,QAAQ,iBAAiB,EAAE,CAAC;+BAc3B,QAAQ,iBAAiB,EAAE,CAAC;2CAkBd,iBAAiB,KAAG,QAAQ,iBAAiB,CAAC;;CAoB/G,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC"}
+{"version":3,"file":"useUserStatus.d.ts","sourceRoot":"","sources":["../../src/hooks/useUserStatus.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEtF,eAAO,MAAM,aAAa;8BAGyB,QAAQ,qBAAqB,iBAAiB,CAAC,CAAC;+BAc/C,QAAQ,qBAAqB,iBAAiB,CAAC,CAAC;2CAkBlC,iBAAiB,KAAG,QAAQ,iBAAiB,CAAC;;CAoB/G,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/hooks/useUsers.d.ts

@@ -1,4 +1,4 @@
-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 declare const useUsers: () => {
     getCurrentUser: () => Promise<UserDTO>;
@@ -7,8 +7,8 @@ export declare const useUsers: () => {
     getAllUsersPublic: (filter?: {
         key: string;
         value: string;
-    }) => Promise<UserPublicProfileDTO[]>;
-    getAllUsers: () => Promise<UserDTO[]>;
+    }) => Promise<PaginatedResponseDTO<UserPublicProfileDTO>>;
+    getAllUsers: () => Promise<PaginatedResponseDTO<UserDTO>>;
     updateUser: (userId: string, userData: UserCreateRequestDTO) => Promise<UserDTO>;
     toggleUserStatus: (user: UserDTO) => Promise<UserDTO>;
     isAvailable: boolean;

package/dist/hooks/useUsers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useUsers.d.ts","sourceRoot":"","sources":["../../src/hooks/useUsers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAErE,eAAO,MAAM,QAAQ;0BAG0B,QAAQ,OAAO,CAAC;kCAiBN,oBAAoB,KAAG,QAAQ,OAAO,CAAC;0BAiB/C,MAAM,KAAG,QAAQ,OAAO,CAAC;iCAclB;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAG,QAAQ,oBAAoB,EAAE,CAAC;uBAe5E,QAAQ,OAAO,EAAE,CAAC;yBAcd,MAAM,YAAY,oBAAoB,KAAG,QAAQ,OAAO,CAAC;6BAcrD,OAAO,KAAG,QAAQ,OAAO,CAAC;;CAwB7E,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC"}
+{"version":3,"file":"useUsers.d.ts","sourceRoot":"","sources":["../../src/hooks/useUsers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAClG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAErE,eAAO,MAAM,QAAQ;0BAG0B,QAAQ,OAAO,CAAC;kCAiBN,oBAAoB,KAAG,QAAQ,OAAO,CAAC;0BAiB/C,MAAM,KAAG,QAAQ,OAAO,CAAC;iCAclB;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAG,QAAQ,qBAAqB,oBAAoB,CAAC,CAAC;uBAehG,QAAQ,qBAAqB,OAAO,CAAC,CAAC;yBAclC,MAAM,YAAY,oBAAoB,KAAG,QAAQ,OAAO,CAAC;6BAcrD,OAAO,KAAG,QAAQ,OAAO,CAAC;;CAwB7E,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC"}

package/dist/hooks/useWeb3.d.ts

@@ -1,17 +1,8 @@
 import type { TokenBalance, TokenBalanceRequest, TokenCollectionRequest, TokenCollection, TokenMetadata } from '@explorins/pers-sdk/web3';
 import type { ChainData } from '@explorins/pers-sdk/web3-chain';
 import type { TokenDTO } from '@explorins/pers-shared';
-/**
- * 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;
-}
+import type { AccountOwnedTokensResult } from '@explorins/pers-sdk';
+export type { AccountOwnedTokensResult } from '@explorins/pers-sdk';
 /**
  * React hook for Web3 operations in the PERS SDK
  *
@@ -21,48 +12,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();
@@ -110,8 +62,8 @@ export declare const useWeb3: () => {
     getChainDataById: (chainId: number) => Promise<ChainData | null>;
     getExplorerUrl: (chainId: number, address: string, type: 'address' | 'tx') => Promise<string>;
     extractTokenIds: (token: TokenDTO) => string[] | undefined;
-    getUserOwnedTokensFromContract: (walletAddress: string, token: TokenDTO, maxTokens?: number) => Promise<UserOwnedTokensResult>;
-    buildCollectionRequest: (walletAddress: string, token: TokenDTO, maxTokens?: number) => TokenCollectionRequest;
+    getAccountOwnedTokensFromContract: (accountAddress: string, token: TokenDTO, maxTokens?: number) => Promise<AccountOwnedTokensResult>;
+    buildCollectionRequest: (accountAddress: string, token: TokenDTO, maxTokens?: number) => TokenCollectionRequest;
     isAvailable: boolean;
 };
 export type Web3Hook = ReturnType<typeof useWeb3>;

package/dist/hooks/useWeb3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useWeb3.d.ts","sourceRoot":"","sources":["../../src/hooks/useWeb3.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,aAAa,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGvD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,KAAK,EAAE,QAAQ,CAAC;IAChB,2EAA2E;IAC3E,WAAW,EAAE,SAAS,YAAY,EAAE,CAAC;IACrC,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,eAAO,MAAM,OAAO;+BA0BkC,mBAAmB,KAAG,QAAQ,YAAY,CAAC;gCAiC1C,mBAAmB,KAAG,QAAQ,aAAa,GAAG,IAAI,CAAC;kCAcjD,sBAAsB,KAAG,QAAQ,eAAe,CAAC;0BAgKzD,MAAM,WAAW,MAAM,KAAG,QAAQ,MAAM,CAAC;wCAc3B,MAAM,WAAW,MAAM,KAAG,QAAQ,aAAa,GAAG,IAAI,CAAC;gCAc/D,MAAM,KAAG,QAAQ,SAAS,GAAG,IAAI,CAAC;8BAcpC,MAAM,WAAW,MAAM,QAAQ,SAAS,GAAG,IAAI,KAAG,QAAQ,MAAM,CAAC;6BAhKxE,QAAQ,KAAG,MAAM,EAAE,GAAG,SAAS;oDA6C1D,MAAM,SACd,QAAQ,cACJ,MAAM,KAChB,QAAQ,qBAAqB,CAAC;4CAwDhB,MAAM,SACd,QAAQ,cACJ,MAAM,KAChB,sBAAsB;;CAmF1B,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC"}
+{"version":3,"file":"useWeb3.d.ts","sourceRoot":"","sources":["../../src/hooks/useWeb3.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,aAAa,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAGpE,YAAY,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,OAAO;+BA0BkC,mBAAmB,KAAG,QAAQ,YAAY,CAAC;gCAiC1C,mBAAmB,KAAG,QAAQ,aAAa,GAAG,IAAI,CAAC;kCAcjD,sBAAsB,KAAG,QAAQ,eAAe,CAAC;0BAczD,MAAM,WAAW,MAAM,KAAG,QAAQ,MAAM,CAAC;wCAc3B,MAAM,WAAW,MAAM,KAAG,QAAQ,aAAa,GAAG,IAAI,CAAC;gCAc/D,MAAM,KAAG,QAAQ,SAAS,GAAG,IAAI,CAAC;8BAcpC,MAAM,WAAW,MAAM,QAAQ,SAAS,GAAG,IAAI,KAAG,QAAQ,MAAM,CAAC;6BAiCxE,QAAQ,KAAG,MAAM,EAAE,GAAG,SAAS;wDAuCzD,MAAM,SACf,QAAQ,cACJ,MAAM,KAChB,QAAQ,wBAAwB,CAAC;6CAqBlB,MAAM,SACf,QAAQ,cACJ,MAAM,KAChB,sBAAsB;;CAqB1B,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC"}

package/dist/hooks/useWeb3.js

@@ -1,6 +1,5 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
-import { NativeTokenTypes } from '@explorins/pers-shared';
 /**
  * React hook for Web3 operations in the PERS SDK
  *
@@ -10,48 +9,9 @@ import { NativeTokenTypes } from '@explorins/pers-shared';
  *
  * 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();
@@ -172,138 +132,6 @@ export const useWeb3 = () => {
             throw error;
         }
     }, [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) => {
-        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, token, maxTokens = 50) => {
-        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, token, maxTokens = 50) => {
-        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, chainId) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
@@ -356,8 +184,86 @@ export const useWeb3 = () => {
             throw error;
         }
     }, [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) => {
+        // 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, token, maxTokens = 50) => {
+        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, token, maxTokens = 50) => {
+        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,
@@ -365,11 +271,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/dist/index.d.ts

@@ -144,6 +144,7 @@ export { PersSDKProvider, usePersSDK, type PersConfig, type PersSDKContext } fro
  * - `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:**
@@ -184,9 +185,30 @@ export { PersSDKProvider, usePersSDK, type PersConfig, type PersSDKContext } fro
  *   };
  * }
  * ```
+ *
+ * @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, useTokens, useTransactions, useTransactionSigner, SigningStatus, useBusiness, useCampaigns, useRedemptions, useWeb3, usePurchases, useTenants, useUsers, useUserStatus, useFiles, useAnalytics, useDonations } from './hooks';
+export { useAuth, useTokens, useTransactions, useTransactionSigner, SigningStatus, useBusiness, useCampaigns, useRedemptions, useWeb3, usePurchases, useTenants, useUsers, useUserStatus, useFiles, useAnalytics, useDonations, useEvents } from './hooks';
 export type { OnStatusUpdateFn, StatusUpdateData, SigningStatusType } from './hooks';
+export type { EventsHook, PersEvent, EventHandler, EventFilter, Unsubscribe } from './hooks';
 /**
  * React Native-optimized HTTP client with automatic request/response handling
  *
@@ -235,4 +257,64 @@ export * from '@explorins/pers-shared';
  * @see {@link TokenCollection} - Collection of tokens for batch operations
  */
 export type { TokenBalanceRequest, TokenBalance, TokenMetadata, TokenCollection, TokenCollectionRequest } from '@explorins/pers-sdk/web3';
+/**
+ * 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';
+/**
+ * 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';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,aAAa,CAAC;AAMrB;;;;;;;;GAQG;AACH,OAAO,EACL,6BAA6B,EAC7B,KAAK,qBAAqB,EAC3B,MAAM,wCAAwC,CAAC;AAMhD;;;;;;;;;;GAUG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;;;;;;GAQG;AACH,OAAO,EACL,wBAAwB,GACzB,MAAM,uCAAuC,CAAC;AAM/C;;;GAGG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAMvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EACL,eAAe,EACf,UAAU,EACV,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,6BAA6B,CAAC;AAMrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,cAAc,EACd,OAAO,EACP,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,YAAY,EACb,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAMrF;;;;;;GAMG;AACH,OAAO,EACL,qBAAqB,EACtB,MAAM,sCAAsC,CAAC;AAM9C;;;;;;;;GAQG;AACH,OAAO,EACL,8BAA8B,EAC/B,MAAM,aAAa,CAAC;AAMrB;;;;;;;;;;;;;;;GAeG;AACH,cAAc,wBAAwB,CAAC;AAEvC;;;;;;;;;;;GAWG;AACH,YAAY,EACV,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,sBAAsB,EACvB,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,aAAa,CAAC;AAMrB;;;;;;;;GAQG;AACH,OAAO,EACL,6BAA6B,EAC7B,KAAK,qBAAqB,EAC3B,MAAM,wCAAwC,CAAC;AAMhD;;;;;;;;;;GAUG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;;;;;;GAQG;AACH,OAAO,EACL,wBAAwB,GACzB,MAAM,uCAAuC,CAAC;AAM/C;;;GAGG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAMvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EACL,eAAe,EACf,UAAU,EACV,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,6BAA6B,CAAC;AAMrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,cAAc,EACd,OAAO,EACP,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,SAAS,EACV,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGrF,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM7F;;;;;;GAMG;AACH,OAAO,EACL,qBAAqB,EACtB,MAAM,sCAAsC,CAAC;AAM9C;;;;;;;;GAQG;AACH,OAAO,EACL,8BAA8B,EAC/B,MAAM,aAAa,CAAC;AAMrB;;;;;;;;;;;;;;;GAeG;AACH,cAAc,wBAAwB,CAAC;AAEvC;;;;;;;;;;;GAWG;AACH,YAAY,EACV,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAMlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAM/E;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}