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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk-react-native",
-  "version": "1.5.34",
+  "version": "1.5.35",
   "description": "React Native SDK for PERS Platform - Tourism Loyalty System with Blockchain Transaction Signing and WebAuthn Authentication",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -38,7 +38,7 @@
   "license": "MIT",
   "dependencies": {
     "@explorins/pers-sdk": "^1.6.42",
-    "@explorins/pers-shared": "^2.1.52",
+    "@explorins/pers-shared": "^2.1.54",
     "@explorins/pers-signer": "^1.0.33",
     "@explorins/web3-ts": "^0.3.77",
     "buffer": "^6.0.3",

package/src/hooks/index.ts

@@ -25,4 +25,5 @@ export type {
   StatusUpdateData,
   OnStatusUpdateFn,
   SigningStatus as SigningStatusType
-} from './useTransactionSigner';
+} from './useTransactionSigner';
+export type { UserOwnedTokensResult, Web3Hook } from './useWeb3';

package/src/hooks/useWeb3.ts

@@ -8,6 +8,20 @@ import type {
   TokenMetadata
 } from '@explorins/pers-sdk/web3';
 import type { ChainData } from '@explorins/pers-sdk/web3-chain';
+import type { TokenDTO } from '@explorins/pers-shared';
+import { NativeTokenTypes } 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
@@ -18,9 +32,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();
@@ -146,6 +199,152 @@ export const useWeb3 = () => {
     }
   }, [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: TokenDTO): string[] | undefined => {
+    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: string,
+    token: TokenDTO,
+    maxTokens: number = 50
+  ): Promise<UserOwnedTokensResult> => {
+    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: string,
+    token: TokenDTO,
+    maxTokens: number = 50
+  ): TokenCollectionRequest => {
+    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: string, chainId: number): Promise<string> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
@@ -203,6 +402,7 @@ export const useWeb3 = () => {
   }, [sdk, isInitialized]);
 
   return {
+    // Core methods
     getTokenBalance,
     getTokenMetadata,
     getTokenCollection,
@@ -210,6 +410,11 @@ export const useWeb3 = () => {
     fetchAndProcessMetadata,
     getChainDataById,
     getExplorerUrl,
+    // Helper methods for ERC-1155 tokens
+    extractTokenIds,
+    getUserOwnedTokensFromContract,
+    buildCollectionRequest,
+    // State
     isAvailable: isInitialized && !!sdk?.web3,
   };
 };