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

package/dist/index.js

@@ -31677,6 +31677,37 @@ class DonationManager {
  *
  * Provides a simplified API for common Web3 blockchain tasks while maintaining
  * access to the full Web3 SDK for advanced use cases.
+ *
+ * ## Supported Token Standards
+ *
+ * - **ERC-20**: Fungible tokens (credits, points). Query balance with `getTokenBalance()`.
+ * - **ERC-721**: Non-fungible tokens (unique NFTs). Supports enumeration - no tokenIds needed.
+ * - **ERC-1155**: Multi-token standard (rewards, collectibles). Requires specific tokenIds.
+ *
+ * ## Recommended: Use Helper Methods
+ *
+ * For most use cases, use `getAccountOwnedTokensFromContract()` which automatically
+ * handles token type detection and tokenId extraction:
+ *
+ * ```typescript
+ * const result = await sdk.web3.getAccountOwnedTokensFromContract(walletAddress, token);
+ * console.log(`Wallet owns ${result.totalOwned} tokens`);
+ * ```
+ *
+ * ## Manual Approach (Advanced)
+ *
+ * For ERC-1155 tokens, tokenIds are extracted from `token.metadata[].tokenMetadataIncrementalId`:
+ *
+ * ```typescript
+ * const tokenIds = token.metadata?.map(meta => meta.tokenMetadataIncrementalId.toString());
+ * const collection = await sdk.web3.getTokenCollection({
+ *   accountAddress: walletAddress,
+ *   contractAddress: token.contractAddress,
+ *   abi: token.abi,
+ *   chainId: token.chainId,
+ *   tokenIds  // Required for ERC-1155, optional for ERC-721
+ * });
+ * ```
  */
 class Web3Manager {
     constructor(apiClient) {
@@ -31764,6 +31795,132 @@ class Web3Manager {
     getWeb3ApplicationService() {
         return this.web3ApplicationService;
     }
+    // ==========================================
+    // HELPER METHODS
+    // ==========================================
+    /**
+     * 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
+     *
+     * @example Manual token collection request
+     * ```typescript
+     * const rewardToken = (await sdk.tokens.getRewardTokens())[0];
+     * const tokenIds = sdk.web3.extractTokenIds(rewardToken);
+     *
+     * if (tokenIds) {
+     *   const collection = await sdk.web3.getTokenCollection({
+     *     accountAddress: walletAddress,
+     *     contractAddress: rewardToken.contractAddress,
+     *     abi: rewardToken.abi,
+     *     chainId: rewardToken.chainId,
+     *     tokenIds
+     *   });
+     * }
+     * ```
+     *
+     * @see {@link getAccountOwnedTokensFromContract} - Recommended helper that handles this automatically
+     */
+    extractTokenIds(token) {
+        if (!token.metadata || token.metadata.length === 0) {
+            return undefined;
+        }
+        return token.metadata.map(meta => meta.tokenMetadataIncrementalId.toString());
+    }
+    /**
+     * 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 collection result with owned tokens
+     *
+     * @example Query user's wallet
+     * ```typescript
+     * const userWallet = user.wallets[0].address;
+     * const result = await sdk.web3.getAccountOwnedTokensFromContract(userWallet, rewardToken);
+     * console.log(`User owns ${result.totalOwned} tokens`);
+     * ```
+     *
+     * @example Query any external wallet
+     * ```typescript
+     * const externalWallet = '0x1234...abcd';
+     * const result = await sdk.web3.getAccountOwnedTokensFromContract(externalWallet, rewardToken);
+     * console.log(`Wallet owns ${result.totalOwned} tokens`);
+     * ```
+     *
+     * @see {@link extractTokenIds} - Low-level helper used internally for ERC-1155
+     * @see {@link buildCollectionRequest} - For manual request building
+     */
+    async getAccountOwnedTokensFromContract(accountAddress, token, maxTokens = 50) {
+        // For ERC-1155, extract tokenIds from metadata
+        const tokenIds = token.type === NativeTokenTypes.ERC1155 ? this.extractTokenIds(token) : undefined;
+        const collection = await this.getTokenCollection({
+            accountAddress: accountAddress,
+            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
+        };
+    }
+    /**
+     * 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.
+     *
+     * Works with any valid blockchain address - user wallets, external wallets, etc.
+     *
+     * @param accountAddress - Any valid blockchain address (wallet, contract, etc.)
+     * @param token - Token definition
+     * @param maxTokens - Maximum tokens to retrieve
+     * @returns TokenCollectionRequest ready for getTokenCollection()
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.web3.buildCollectionRequest(walletAddress, rewardToken);
+     * const collection = await sdk.web3.getTokenCollection(request);
+     * ```
+     */
+    buildCollectionRequest(accountAddress, token, maxTokens = 50) {
+        return {
+            accountAddress: accountAddress,
+            contractAddress: token.contractAddress,
+            abi: token.abi,
+            chainId: token.chainId,
+            tokenIds: token.type === NativeTokenTypes.ERC1155 ? this.extractTokenIds(token) : undefined,
+            maxTokens
+        };
+    }
 }
 
 /**
@@ -34456,48 +34613,9 @@ const useRedemptions = () => {
  *
  * 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();
@@ -34618,138 +34736,6 @@ 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 = react.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 = react.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 = react.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 = react.useCallback(async (url, chainId) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
@@ -34802,8 +34788,86 @@ 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 = react.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 = react.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 = react.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,
@@ -34811,11 +34875,10 @@ const useWeb3 = () => {
         fetchAndProcessMetadata,
         getChainDataById,
         getExplorerUrl,
-        // Helper methods for ERC-1155 tokens
+        // Helper methods
         extractTokenIds,
-        getUserOwnedTokensFromContract,
+        getAccountOwnedTokensFromContract,
         buildCollectionRequest,
-        // State
         isAvailable: isInitialized && !!sdk?.web3,
     };
 };