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

package/README.md

@@ -51,19 +51,12 @@ npm install react-native-url-polyfill
 
 ## Critical Setup Requirement: Passkeys
 
-To enable Passkey authentication (WebAuthn) on iOS and Android, you **must** register your app's bundle information with the PERS backend.
+To enable Passkey authentication (WebAuthn) on iOS and Android, you **must** complete the setup in **[REACT_NATIVE_PASSKEY_SETUP.md](./REACT_NATIVE_PASSKEY_SETUP.md)**.
 
-**Please send the following information to the PERS Team (support@explorins.com):**
-
-1.  **iOS Bundle Identifier**: e.g., `com.yourcompany.app`
-2.  **Apple Team ID**: Your 10-character Apple Team ID (e.g., `R553XYJPW7`)
-3.  **Android Package Name**: e.g., `com.yourcompany.app`
-4.  **Android SHA-256 Certificate Fingerprint**:
-    *   **Development**: The fingerprint from your local keystore or Expo development build.
-    *   **Production**: The fingerprint from your Google Play Console signing key.
-
-**Why is this required?**
-The PERS Signer server must host an `apple-app-site-association` file (for iOS) and an `assetlinks.json` file (for Android) that explicitly trusts your application. Without this, the operating system will reject Passkey creation requests.
+This includes:
+- Registering your app with the PERS backend (required for OS trust)
+- Native configuration (Info.plist, AndroidManifest.xml)
+- Expo/development build setup
 
 ## Quick Start
 
@@ -312,7 +305,11 @@ const {
   resolveIPFSUrl,
   fetchAndProcessMetadata,
   getChainDataById,
-  getExplorerUrl
+  getExplorerUrl,
+  // Helper methods for token collections
+  extractTokenIds,                    // Extract tokenIds from TokenDTO metadata
+  getAccountOwnedTokensFromContract,  // Recommended: Get owned tokens automatically
+  buildCollectionRequest              // Build request for getTokenCollection
 } = useWeb3();
 
 // User status & achievements
@@ -336,6 +333,69 @@ const {
 } = useDonations();
 ```
 
+## Token Collection Helper Methods
+
+The `useWeb3` hook includes helper methods for querying token balances from any blockchain address. These work with **all token standards** (ERC-20, ERC-721, ERC-1155).
+
+### Recommended: getAccountOwnedTokensFromContract
+
+A unified API to get all tokens owned by any blockchain address:
+
+```typescript
+import { useWeb3, useTokens, usePersSDK } from '@explorins/pers-sdk-react-native';
+
+function RewardTokensScreen() {
+  const { user } = usePersSDK();
+  const { getRewardTokens } = useTokens();
+  const { getAccountOwnedTokensFromContract } = useWeb3();
+
+  const loadUserRewards = async () => {
+    const walletAddress = user?.wallets?.[0]?.address;
+    if (!walletAddress) return;
+
+    const rewardTokens = await getRewardTokens();
+    
+    for (const token of rewardTokens) {
+      // Works with ERC-20, ERC-721, and ERC-1155 automatically
+      const result = await getAccountOwnedTokensFromContract(walletAddress, token);
+      
+      console.log(`Token: ${token.symbol}`);
+      console.log(`Owned: ${result.totalOwned}`);
+      
+      result.ownedTokens.forEach(owned => {
+        console.log(`  - ${owned.metadata?.name}: ${owned.balance}`);
+      });
+    }
+  };
+
+  return (
+    <TouchableOpacity onPress={loadUserRewards}>
+      <Text>Load My Rewards</Text>
+    </TouchableOpacity>
+  );
+}
+```
+
+### How It Handles Each Token Standard
+
+| Token Type | What It Does |
+|------------|--------------|
+| **ERC-20** | Returns balance for fungible tokens |
+| **ERC-721** | Enumerates all owned NFTs |
+| **ERC-1155** | Extracts tokenIds from metadata, queries balances |
+
+The helper abstracts away the complexity - especially for ERC-1155 which requires specific `tokenIds` that the helper extracts from `token.metadata[].tokenMetadataIncrementalId`.
+
+### Return Type
+
+```typescript
+interface AccountOwnedTokensResult {
+  token: TokenDTO;           // The token definition
+  ownedTokens: TokenBalance[]; // Tokens with balance > 0
+  totalOwned: number;        // Count of owned tokens
+}
+```
+
 ## EVM Blockchain Transaction Signing
 
 The `useTransactionSigner` hook provides secure EVM blockchain transaction signing:

package/dist/hooks/index.d.ts

@@ -15,4 +15,5 @@ export { useAnalytics } from './useAnalytics';
 export { useDonations } from './useDonations';
 export type { RawUserData } from './useAuth';
 export type { TransactionSignerHook, SubmissionResult, AuthenticatedUser, TransactionSigningResult, StatusUpdateData, OnStatusUpdateFn, SigningStatus as SigningStatusType } from './useTransactionSigner';
+export type { AccountOwnedTokensResult, Web3Hook } from './useWeb3';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,IAAI,iBAAiB,EACnC,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,IAAI,iBAAiB,EACnC,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC"}

package/dist/hooks/useWeb3.d.ts

@@ -1,5 +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';
+import type { AccountOwnedTokensResult } from '@explorins/pers-sdk';
+export type { AccountOwnedTokensResult } from '@explorins/pers-sdk';
 /**
  * React hook for Web3 operations in the PERS SDK
  *
@@ -58,6 +61,9 @@ export declare const useWeb3: () => {
     fetchAndProcessMetadata: (tokenUri: string, chainId: number) => Promise<TokenMetadata | null>;
     getChainDataById: (chainId: number) => Promise<ChainData | null>;
     getExplorerUrl: (chainId: number, address: string, type: 'address' | 'tx') => Promise<string>;
+    extractTokenIds: (token: TokenDTO) => string[] | undefined;
+    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;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;;CAwBrH,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

@@ -184,6 +184,85 @@ 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 {
         getTokenBalance,
         getTokenMetadata,
@@ -192,6 +271,10 @@ export const useWeb3 = () => {
         fetchAndProcessMetadata,
         getChainDataById,
         getExplorerUrl,
+        // Helper methods
+        extractTokenIds,
+        getAccountOwnedTokensFromContract,
+        buildCollectionRequest,
         isAvailable: isInitialized && !!sdk?.web3,
     };
 };

package/dist/index.js

@@ -2629,6 +2629,8 @@ exports.ApiKeyType = void 0;
     ApiKeyType["ADMIN_JWT_REFRESH_TOKEN"] = "ADMIN_JWT_REFRESH_TOKEN";
     ApiKeyType["USER_JWT_ACCESS_TOKEN"] = "USER_JWT_ACCESS_TOKEN";
     ApiKeyType["USER_JWT_REFRESH_TOKEN"] = "USER_JWT_REFRESH_TOKEN";
+    ApiKeyType["BUSINESS_JWT_ACCESS_TOKEN"] = "BUSINESS_JWT_ACCESS_TOKEN";
+    ApiKeyType["BUSINESS_JWT_REFRESH_TOKEN"] = "BUSINESS_JWT_REFRESH_TOKEN";
     ApiKeyType["BLOCKCHAIN_WRITER_JWT"] = "BLOCKCHAIN_WRITER_JWT";
     ApiKeyType["BLOCKCHAIN_READER_JWT"] = "BLOCKCHAIN_READER_JWT";
     ApiKeyType["TRANSACTION_JWT_ACCESS_TOKEN"] = "TRANSACTION_JWT_ACCESS_TOKEN";
@@ -31675,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) {
@@ -31762,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
+        };
+    }
 }
 
 /**
@@ -34629,6 +34788,85 @@ 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 {
         getTokenBalance,
         getTokenMetadata,
@@ -34637,6 +34875,10 @@ const useWeb3 = () => {
         fetchAndProcessMetadata,
         getChainDataById,
         getExplorerUrl,
+        // Helper methods
+        extractTokenIds,
+        getAccountOwnedTokensFromContract,
+        buildCollectionRequest,
         isAvailable: isInitialized && !!sdk?.web3,
     };
 };