@explorins/pers-sdk-react-native 2.2.0-beta.1 → 2.2.1

package/src/hooks/useTokenBalances.ts

@@ -10,9 +10,42 @@ import type { TokenBalance, TokenBalanceRequest } from '@explorins/pers-sdk/web3
  * This composite type combines blockchain balance data with token metadata,
  * making it easy to display token information in UI components without
  * needing to join data from multiple sources.
+ * 
+ * ## CRITICAL: Token ID for Transactions
+ * 
+ * For ERC721 (stamps) and ERC1155 (rewards), use `tokenBalance.tokenId` as the
+ * `contractTokenId` when creating transactions. This is the **on-chain token ID**
+ * assigned by the blockchain, NOT the metadata definition ID.
+ * 
+ * | Token Type | tokenId meaning | Example |
+ * |------------|-----------------|---------|
+ * | ERC20      | `null` or `""`  | N/A (fungible points) |
+ * | ERC721     | NFT instance ID | `"46"` (on-chain ID) |
+ * | ERC1155    | Token type ID   | `"16"` (semi-fungible type) |
+ * 
+ * @example Correct usage for token burn transaction
+ * ```typescript
+ * const stampBalance = tokenBalances.find(b => b.token.type === 'ERC721');
+ * 
+ * const request = buildPOSBurnRequest({
+ *   amount: 1,
+ *   contractAddress: stampBalance.token.contractAddress,
+ *   contractTokenId: stampBalance.tokenBalance.tokenId, // ✅ Correct
+ *   chainId: stampBalance.token.chainId,
+ *   userId: userId,
+ *   businessId: businessId
+ * });
+ * ```
+ * 
+ * @see {@link https://docs.explorins.com/pers-sdk/troubleshooting#stamp-voucher-transaction-fails | Troubleshooting: Stamp Transaction Fails}
  */
 export interface TokenBalanceWithToken {
-  /** The balance data from blockchain */
+  /** 
+   * The balance data from blockchain
+   * 
+   * **Important:** For NFT operations, use `tokenBalance.tokenId` as the `contractTokenId`
+   * in transaction requests. This is the actual on-chain ID, not the metadata definition.
+   */
   tokenBalance: TokenBalance;
   /** The token definition (contract, symbol, metadata, etc.) */
   token: TokenDTO;

package/src/hooks/useTokens.ts

@@ -1,6 +1,6 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
-import type { TokenDTO, PaginatedResponseDTO } from '@explorins/pers-sdk';
+import type { TokenDTO, TokenMetadataDTO, PaginatedResponseDTO, TokenMetadataFilterOptions, RewardsFilterOptions, StampsFilterOptions } from '@explorins/pers-sdk';
 
 /**
  * React hook for token operations in the PERS SDK
@@ -201,6 +201,102 @@ export const useTokens = () => {
     }
   }, [sdk, isInitialized]);
 
+  /**
+   * Get all token metadata with filtering and pagination
+   * 
+   * Retrieves token metadata (rewards/stamps) with server-side filtering.
+   * Use tokenType: 'ERC1155' for rewards, 'ERC721' for stamps.
+   * 
+   * @param options - Filter and pagination options
+   * @returns Promise resolving to paginated token metadata
+   * @throws Error if SDK is not initialized
+   * 
+   * @example
+   * ```typescript
+   * const { getTokenMetadata } = useTokens();
+   * const rewards = await getTokenMetadata({ 
+   *   tokenType: 'ERC1155', 
+   *   active: true,
+   *   limit: 10 
+   * });
+   * ```
+   */
+  const getTokenMetadata = useCallback(async (options?: TokenMetadataFilterOptions): Promise<PaginatedResponseDTO<TokenMetadataDTO>> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.tokens.getTokenMetadata(options);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch token metadata:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
+  /**
+   * Get rewards (ERC1155 token metadata) with filtering and pagination
+   * 
+   * Convenience method for fetching reward metadata. Rewards are ERC1155 tokens
+   * that represent collectible items, vouchers, or other redeemable rewards.
+   * 
+   * @param options - Filter and pagination options
+   * @returns Promise resolving to paginated reward metadata
+   * @throws Error if SDK is not initialized
+   * 
+   * @example
+   * ```typescript
+   * const { getRewards } = useTokens();
+   * const rewards = await getRewards({ active: true, limit: 10 });
+   * console.log(`Found ${rewards.pagination.total} rewards`);
+   * ```
+   */
+  const getRewards = useCallback(async (options?: RewardsFilterOptions): Promise<PaginatedResponseDTO<TokenMetadataDTO>> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.tokens.getRewards(options);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch rewards:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
+  /**
+   * Get stamps (ERC721 token metadata) with filtering and pagination
+   * 
+   * Convenience method for fetching stamp metadata. Stamps are ERC721 tokens
+   * that represent achievements, badges, or collectible status markers.
+   * 
+   * @param options - Filter and pagination options
+   * @returns Promise resolving to paginated stamp metadata
+   * @throws Error if SDK is not initialized
+   * 
+   * @example
+   * ```typescript
+   * const { getStamps } = useTokens();
+   * const stamps = await getStamps({ active: true, limit: 10 });
+   * console.log(`Found ${stamps.pagination.total} stamps`);
+   * ```
+   */
+  const getStamps = useCallback(async (options?: StampsFilterOptions): Promise<PaginatedResponseDTO<TokenMetadataDTO>> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.tokens.getStamps(options);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch stamps:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
   return {
     getTokens,
     getActiveCreditToken,
@@ -208,6 +304,9 @@ export const useTokens = () => {
     getTokenTypes,
     getStatusTokens,
     getTokenByContract,
+    getTokenMetadata,
+    getRewards,
+    getStamps,
     isAvailable: isInitialized && !!sdk?.tokens,
   };
 };

package/src/providers/PersSDKProvider.tsx

@@ -27,11 +27,45 @@ export type { PersConfig } from '@explorins/pers-sdk/core';
 /**
  * Context interface for PERS SDK React Native integration
  * 
+ * ## Session Restoration Behavior
+ * 
+ * Session restoration is **asynchronous**. When the app starts:
+ * 1. `isInitialized` becomes `true` when SDK is ready
+ * 2. Session restoration happens automatically
+ * 3. `isAuthenticated` and `user` update when restoration completes
+ * 
+ * **Always check `isInitialized` AND `isAuthenticated` before using `user`:**
+ * 
+ * ```tsx
+ * const { user, isInitialized, isAuthenticated } = usePersSDK();
+ * 
+ * if (!isInitialized) return <LoadingSpinner />;
+ * if (!isAuthenticated || !user) return <LoginScreen />;
+ * return <WalletContent user={user} />;
+ * ```
+ * 
+ * **Why `user` might be null on app restart:**
+ * - Access tokens expire after 1 hour (auto-refreshed if app is active)
+ * - Refresh tokens expire after 30 days (user must re-login)
+ * - Session restoration is in progress
+ * 
+ * Listen for auth events to debug:
+ * ```typescript
+ * sdk.events.subscribe((event) => {
+ *   console.log('[Auth Event]', event.type, event.details);
+ * }, { domains: ['authentication'], replay: true });
+ * ```
+ * 
+ * | Event | Meaning |
+ * |-------|---------|
+ * | `session_restored` | Tokens valid, user logged in |
+ * | `session_restoration_failed` | Tokens expired, needs re-login |
+ * 
  * @property sdk - Main SDK instance (null until initialized)
  * @property authProvider - Platform-specific auth provider
- * @property isInitialized - Whether SDK has been initialized
+ * @property isInitialized - Whether SDK has been initialized (not whether user is authenticated!)
  * @property isAuthenticated - Whether user is currently authenticated
- * @property user - Current user data (null if not authenticated)
+ * @property user - Current user data (null if not authenticated OR restoration in progress)
  */
 export interface PersSDKContext {
   // Main SDK instance
@@ -168,7 +202,7 @@ export const PersSDKProvider: React.FC<{
           }
         }
 
-        if (event.type === 'logout_success' || event.type === 'session_restoration_failed' || event.code === 'AUTH_FAILED') {
+        if (event.type === 'logout_success' || event.type === 'session_restoration_failed') {
           setUser(null);
           setIsAuthenticated(false);
         }