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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk-react-native",
-  "version": "1.5.35",
+  "version": "1.5.36",
   "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",
@@ -37,7 +37,7 @@
   "author": "eXplorins",
   "license": "MIT",
   "dependencies": {
-    "@explorins/pers-sdk": "^1.6.42",
+    "@explorins/pers-sdk": "^1.6.45",
     "@explorins/pers-shared": "^2.1.54",
     "@explorins/pers-signer": "^1.0.33",
     "@explorins/web3-ts": "^0.3.77",

package/src/hooks/index.ts

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

package/src/hooks/useWeb3.ts

@@ -9,19 +9,10 @@ import type {
 } 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';
+import type { AccountOwnedTokensResult } from '@explorins/pers-sdk';
 
-/**
- * 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;
-}
+// Re-export for convenience
+export type { AccountOwnedTokensResult } from '@explorins/pers-sdk';
 
 /**
  * React hook for Web3 operations in the PERS SDK
@@ -32,48 +23,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();
@@ -199,152 +151,6 @@ 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.');
@@ -401,8 +207,99 @@ export const useWeb3 = () => {
     }
   }, [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: TokenDTO): string[] | undefined => {
+    // 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: string,
+    token: TokenDTO,
+    maxTokens: number = 50
+  ): Promise<AccountOwnedTokensResult> => {
+    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: string,
+    token: TokenDTO,
+    maxTokens: number = 50
+  ): TokenCollectionRequest => {
+    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,
@@ -410,11 +307,10 @@ export const useWeb3 = () => {
     fetchAndProcessMetadata,
     getChainDataById,
     getExplorerUrl,
-    // Helper methods for ERC-1155 tokens
+    // Helper methods
     extractTokenIds,
-    getUserOwnedTokensFromContract,
+    getAccountOwnedTokensFromContract,
     buildCollectionRequest,
-    // State
     isAvailable: isInitialized && !!sdk?.web3,
   };
 };