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

package/README.md

@@ -176,17 +176,29 @@ function RewardScreen() {
 ```typescript
 // Authentication management
 const { 
+  isInitialized,
   isAuthenticated, 
   user, 
-  login, 
-  logout 
+  login,
+  loginWithRawData,
+  logout,
+  refreshUserData,
+  getCurrentUser,
+  checkIsAuthenticated,
+  refreshTokens,
+  clearAuth,
+  hasValidAuth
 } = useAuth();
 
 // User profile operations  
 const { 
-  getUserProfile,
-  updateUserProfile,
-  getUserPublicData 
+  getCurrentUser,
+  updateCurrentUser,
+  getUserById,
+  getAllUsersPublic,
+  getAllUsers,        // Admin
+  updateUser,         // Admin
+  toggleUserStatus    // Admin
 } = useUsers();
 ```
 
@@ -198,21 +210,30 @@ const {
   getTokens,
   getActiveCreditToken,
   getRewardTokens,
+  getTokenTypes,
+  getStatusTokens,
   getTokenByContract
 } = useTokens();
 
 // Transaction history
 const { 
-  getUserTransactionHistory,
+  createTransaction,
   getTransactionById,
-  createTransaction
+  getUserTransactionHistory,
+  getTenantTransactions,      // Admin
+  getPaginatedTransactions,   // Admin
+  exportTransactionsCSV,      // Admin
+  signingStatus,              // UI feedback during blockchain signing
+  signingStatusMessage
 } = useTransactions();
 
 // Blockchain transaction signing
 const { 
   signAndSubmitTransactionWithJWT,
   isSignerAvailable,
-  isSignerInitialized
+  isSignerInitialized,
+  currentStatus,
+  statusMessage
 } = useTransactionSigner();
 ```
 
@@ -221,23 +242,42 @@ const {
 ```typescript
 // Business operations
 const { 
-  getBusinessProfile,
-  updateBusinessProfile,
-  getBusinessTypes
+  getActiveBusinesses,
+  getBusinessTypes,
+  getBusinesses,
+  getBusinessById,
+  getBusinessByAccount,
+  getBusinessesByType,
+  createBusiness,       // Admin
+  updateBusiness,       // Admin
+  toggleBusinessStatus  // Admin
 } = useBusiness();
 
 // Campaign management
 const { 
   getActiveCampaigns,
-  participateInCampaign,
-  claimCampaignReward
+  getCampaignById,
+  claimCampaign,
+  getUserClaims,
+  getCampaignTriggers,
+  getAllCampaigns,              // Admin
+  getCampaignClaims,            // Admin
+  getCampaignClaimsByUserId,    // Admin
+  getCampaignClaimsByBusinessId // Admin
 } = useCampaigns();
 
 // Redemption system
 const { 
-  redeem,
+  getActiveRedemptions,
   getUserRedemptions,
-  getActiveRedemptions
+  redeem,
+  getRedemptionTypes,
+  signingStatus,           // UI feedback during blockchain signing
+  signingStatusMessage,
+  createRedemption,        // Admin
+  getAllRedemptions,       // Admin
+  updateRedemption,        // Admin
+  toggleRedemptionStatus   // Admin
 } = useRedemptions();
 ```
 
@@ -246,31 +286,54 @@ const {
 ```typescript
 // Purchase processing
 const { 
-  createPurchase,
-  getUserPurchases,
-  processPayment
+  createPaymentIntent,
+  getActivePurchaseTokens,
+  getAllUserPurchases
 } = usePurchases();
 
 // Multi-tenant support
 const { 
-  getTenantConfig,
-  updateTenantConfig,
-  getTenantAdmins
+  getTenantInfo,
+  getClientConfig,
+  getLoginToken,
+  getAdmins
 } = useTenants();
 
 // Analytics & reporting
 const { 
-  getTransactionAnalytics,
-  getUserAnalytics,
-  getBusinessAnalytics
+  getTransactionAnalytics
 } = useAnalytics();
 
-// Web3 & blockchain
+// Web3 & blockchain (wallet addresses from user.wallets)
 const { 
-  getWalletBalance,
-  createWallet,
-  getTransactionHistory
+  getTokenBalance,
+  getTokenMetadata,
+  getTokenCollection,
+  resolveIPFSUrl,
+  fetchAndProcessMetadata,
+  getChainDataById,
+  getExplorerUrl
 } = useWeb3();
+
+// User status & achievements
+const {
+  getUserStatusTypes,
+  getEarnedUserStatus,
+  createUserStatusType  // Admin
+} = useUserStatus();
+
+// File management
+const {
+  getSignedPutUrl,
+  getSignedGetUrl,
+  getSignedUrl,
+  optimizeMedia
+} = useFiles();
+
+// Donations
+const {
+  getDonationTypes
+} = useDonations();
 ```
 
 ## EVM Blockchain Transaction Signing
@@ -455,25 +518,22 @@ function ErrorHandlingExample() {
 import { useAnalytics } from '@explorins/pers-sdk-react-native';
 
 function AnalyticsExample() {
-  const { 
-    getTransactionAnalytics,
-    getUserAnalytics,
-    trackEvent
-  } = useAnalytics();
+  const { getTransactionAnalytics } = useAnalytics();
 
   const loadAnalytics = async () => {
-    const txAnalytics = await getTransactionAnalytics({
-      dateRange: { start: '2023-01-01', end: '2023-12-31' }
-    });
-    
-    const userAnalytics = await getUserAnalytics();
-    
-    // Track custom events
-    await trackEvent('reward_claimed', {
-      amount: 100,
-      type: 'discount_voucher',
-      timestamp: new Date().toISOString()
-    });
+    try {
+      const txAnalytics = await getTransactionAnalytics({
+        groupBy: ['day'],
+        metrics: ['count', 'sum'],
+        startDate: '2023-01-01',
+        endDate: '2023-12-31'
+      });
+      
+      console.log('Transaction analytics:', txAnalytics.results);
+      console.log('Execution time:', txAnalytics.metadata?.executionTime);
+    } catch (error) {
+      console.error('Failed to load analytics:', error);
+    }
   };
 }
 ```

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 { UserOwnedTokensResult, 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,qBAAqB,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC"}

package/dist/hooks/useWeb3.d.ts

@@ -1,5 +1,17 @@
 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;
+}
 /**
  * React hook for Web3 operations in the PERS SDK
  *
@@ -9,9 +21,48 @@ import type { ChainData } from '@explorins/pers-sdk/web3-chain';
  *
  * 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
+ * @example Basic Usage
  * ```typescript
  * function Web3Component() {
  *   const { user } = usePersSDK();
@@ -58,6 +109,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;
+    getUserOwnedTokensFromContract: (walletAddress: string, token: TokenDTO, maxTokens?: number) => Promise<UserOwnedTokensResult>;
+    buildCollectionRequest: (walletAddress: 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;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"}

package/dist/hooks/useWeb3.js

@@ -1,5 +1,6 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
+import { NativeTokenTypes } from '@explorins/pers-shared';
 /**
  * React hook for Web3 operations in the PERS SDK
  *
@@ -9,9 +10,48 @@ import { usePersSDK } from '../providers/PersSDKProvider';
  *
  * 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
+ * @example Basic Usage
  * ```typescript
  * function Web3Component() {
  *   const { user } = usePersSDK();
@@ -132,6 +172,138 @@ 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.');
@@ -185,6 +357,7 @@ export const useWeb3 = () => {
         }
     }, [sdk, isInitialized]);
     return {
+        // Core methods
         getTokenBalance,
         getTokenMetadata,
         getTokenCollection,
@@ -192,6 +365,11 @@ export const useWeb3 = () => {
         fetchAndProcessMetadata,
         getChainDataById,
         getExplorerUrl,
+        // Helper methods for ERC-1155 tokens
+        extractTokenIds,
+        getUserOwnedTokensFromContract,
+        buildCollectionRequest,
+        // State
         isAvailable: isInitialized && !!sdk?.web3,
     };
 };