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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk-react-native",
-  "version": "1.5.34",
+  "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,8 +37,8 @@
   "author": "eXplorins",
   "license": "MIT",
   "dependencies": {
-    "@explorins/pers-sdk": "^1.6.42",
-    "@explorins/pers-shared": "^2.1.52",
+    "@explorins/pers-sdk": "^1.6.45",
+    "@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 { AccountOwnedTokensResult, Web3Hook } from './useWeb3';

package/src/hooks/useWeb3.ts

@@ -8,6 +8,11 @@ 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 type { AccountOwnedTokensResult } from '@explorins/pers-sdk';
+
+// Re-export for convenience
+export type { AccountOwnedTokensResult } from '@explorins/pers-sdk';
 
 /**
  * React hook for Web3 operations in the PERS SDK
@@ -202,6 +207,98 @@ 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 {
     getTokenBalance,
     getTokenMetadata,
@@ -210,6 +307,10 @@ export const useWeb3 = () => {
     fetchAndProcessMetadata,
     getChainDataById,
     getExplorerUrl,
+    // Helper methods
+    extractTokenIds,
+    getAccountOwnedTokensFromContract,
+    buildCollectionRequest,
     isAvailable: isInitialized && !!sdk?.web3,
   };
 };