@explorins/pers-sdk-react-native 2.0.5 → 2.1.1

package/dist/hooks/useWeb3.js

@@ -1,5 +1,6 @@
-import { useCallback } from 'react';
+import { useCallback, useMemo } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
+import { Web3Manager } from '@explorins/pers-sdk/web3';
 /**
  * React hook for Web3 operations in the PERS SDK
  *
@@ -55,6 +56,15 @@ export const useWeb3 = () => {
     if (!isAuthenticated && isInitialized) {
         console.warn('SDK not authenticated. Some web3 operations may fail.');
     }
+    /**
+     * Create Web3Manager instance lazily
+     * Web3Manager is now separate from PersSDK since v2.0.11+
+     */
+    const web3 = useMemo(() => {
+        if (!sdk)
+            return null;
+        return new Web3Manager(sdk.api());
+    }, [sdk]);
     /**
      * Retrieves token balance for a specific wallet and contract
      *
@@ -75,18 +85,18 @@ export const useWeb3 = () => {
      * ```
      */
     const getTokenBalance = useCallback(async (request) => {
-        if (!isInitialized || !sdk) {
+        if (!isInitialized || !web3) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.web3.getTokenBalance(request);
+            const result = await web3.getTokenBalance(request);
             return result;
         }
         catch (error) {
             console.error('Failed to fetch token balance:', error);
             throw error;
         }
-    }, [sdk, isInitialized]);
+    }, [web3, isInitialized]);
     /**
      * Retrieves metadata for a specific token (useful for NFTs)
      *
@@ -107,83 +117,83 @@ export const useWeb3 = () => {
      * ```
      */
     const getTokenMetadata = useCallback(async (request) => {
-        if (!isInitialized || !sdk) {
+        if (!isInitialized || !web3) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.web3.getTokenMetadata(request);
+            const result = await web3.getTokenMetadata(request);
             return result;
         }
         catch (error) {
             console.error('Failed to fetch token metadata:', error);
             throw error;
         }
-    }, [sdk, isInitialized]);
+    }, [web3, isInitialized]);
     const getTokenCollection = useCallback(async (request) => {
-        if (!isInitialized || !sdk) {
+        if (!isInitialized || !web3) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.web3.getTokenCollection(request);
+            const result = await web3.getTokenCollection(request);
             return result;
         }
         catch (error) {
             console.error('Failed to fetch token collection:', error);
             throw error;
         }
-    }, [sdk, isInitialized]);
+    }, [web3, isInitialized]);
     const resolveIPFSUrl = useCallback(async (url, chainId) => {
-        if (!isInitialized || !sdk) {
+        if (!isInitialized || !web3) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.web3.resolveIPFSUrl(url, chainId);
+            const result = await web3.resolveIPFSUrl(url, chainId);
             return result;
         }
         catch (error) {
             console.error('Failed to resolve IPFS URL:', error);
             throw error;
         }
-    }, [sdk, isInitialized]);
+    }, [web3, isInitialized]);
     const fetchAndProcessMetadata = useCallback(async (tokenUri, chainId) => {
-        if (!isInitialized || !sdk) {
+        if (!isInitialized || !web3) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.web3.fetchAndProcessMetadata(tokenUri, chainId);
+            const result = await web3.fetchAndProcessMetadata(tokenUri, chainId);
             return result;
         }
         catch (error) {
             console.error('Failed to fetch and process metadata:', error);
             throw error;
         }
-    }, [sdk, isInitialized]);
+    }, [web3, isInitialized]);
     const getChainDataById = useCallback(async (chainId) => {
-        if (!isInitialized || !sdk) {
+        if (!isInitialized || !web3) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.web3.getChainDataById(chainId);
+            const result = await web3.getChainDataById(chainId);
             return result;
         }
         catch (error) {
             console.error('Failed to fetch chain data:', error);
             throw error;
         }
-    }, [sdk, isInitialized]);
+    }, [web3, isInitialized]);
     const getExplorerUrl = useCallback(async (chainId, address, type) => {
-        if (!isInitialized || !sdk) {
+        if (!isInitialized || !web3) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.web3.getExplorerUrl(chainId, address, type);
+            const result = await web3.getExplorerUrl(chainId, address, type);
             return result;
         }
         catch (error) {
             console.error('Failed to generate explorer URL:', error);
             throw error;
         }
-    }, [sdk, isInitialized]);
+    }, [web3, isInitialized]);
     // ==========================================
     // HELPER METHODS (delegating to core SDK)
     // ==========================================
@@ -203,9 +213,9 @@ export const useWeb3 = () => {
      * @see {@link getAccountOwnedTokensFromContract} - Recommended helper that handles this automatically
      */
     const extractTokenIds = useCallback((token) => {
-        // Pure function - delegates to core SDK (no initialization required)
-        return sdk?.web3.extractTokenIds(token);
-    }, [sdk]);
+        // Pure function - delegates to Web3Manager (no initialization required)
+        return web3?.extractTokenIds(token);
+    }, [web3]);
     /**
      * Get owned tokens from a specific token contract for any blockchain address.
      *
@@ -240,11 +250,11 @@ export const useWeb3 = () => {
      * @see {@link buildCollectionRequest} - For manual request building
      */
     const getAccountOwnedTokensFromContract = useCallback(async (accountAddress, token, maxTokens = 50) => {
-        if (!isInitialized || !sdk) {
+        if (!isInitialized || !web3) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
-        return sdk.web3.getAccountOwnedTokensFromContract(accountAddress, token, maxTokens);
-    }, [sdk, isInitialized]);
+        return web3.getAccountOwnedTokensFromContract(accountAddress, token, maxTokens);
+    }, [web3, isInitialized]);
     /**
      * Build a TokenCollectionRequest from a TokenDTO.
      *
@@ -258,11 +268,11 @@ export const useWeb3 = () => {
      * @returns TokenCollectionRequest ready for getTokenCollection()
      */
     const buildCollectionRequest = useCallback((accountAddress, token, maxTokens = 50) => {
-        if (!sdk) {
+        if (!web3) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
-        return sdk.web3.buildCollectionRequest(accountAddress, token, maxTokens);
-    }, [sdk]);
+        return web3.buildCollectionRequest(accountAddress, token, maxTokens);
+    }, [web3]);
     return {
         getTokenBalance,
         getTokenMetadata,
@@ -275,6 +285,6 @@ export const useWeb3 = () => {
         extractTokenIds,
         getAccountOwnedTokensFromContract,
         buildCollectionRequest,
-        isAvailable: isInitialized && !!sdk?.web3,
+        isAvailable: isInitialized && !!web3,
     };
 };

package/dist/index.d.ts

@@ -206,9 +206,10 @@ export { PersSDKProvider, usePersSDK, type PersConfig, type PersSDKContext } fro
  * }
  * ```
  */
-export { useAuth, useTokens, useTransactions, useTransactionSigner, SigningStatus, useBusiness, useCampaigns, useRedemptions, useWeb3, usePurchases, useTenants, useUsers, useUserStatus, useFiles, useAnalytics, useDonations, useEvents } from './hooks';
+export { useAuth, useTokens, useTokenBalances, useTransactions, useTransactionSigner, SigningStatus, useBusiness, useCampaigns, useRedemptions, useWeb3, usePurchases, useTenants, useUsers, useUserStatus, useFiles, useAnalytics, useDonations, useEvents } from './hooks';
 export type { OnStatusUpdateFn, StatusUpdateData, SigningStatusType } from './hooks';
 export type { EventsHook, PersEvent, EventHandler, EventFilter, Unsubscribe } from './hooks';
+export type { TokenBalanceWithToken, UseTokenBalancesOptions, UseTokenBalancesResult } from './hooks';
 /**
  * React Native-optimized HTTP client with automatic request/response handling
  *
@@ -310,25 +311,95 @@ export type { TokenBalanceRequest, TokenBalance, TokenMetadata, TokenCollection,
  * @see {@link buildPOSBurnRequest} - Create POS burn requests (business submits burn on behalf of user)
  * @see {@link buildSubmissionRequest} - Create submission requests from QR/signature data
  */
-export { buildMintRequest, buildBurnRequest, buildTransferRequest, buildPOSTransferRequest, buildPOSBurnRequest, buildSubmissionRequest } from '@explorins/pers-sdk/transaction';
-export type { POSAuthorizationOptions } from '@explorins/pers-sdk/transaction';
+export { buildMintRequest, buildBurnRequest, buildTransferRequest, buildPOSTransferRequest, buildPOSBurnRequest, buildSubmissionRequest, ClientTransactionType, extractDeadlineFromSigningData, buildPendingTransactionData } from '@explorins/pers-sdk/transaction';
+export type { POSAuthorizationOptions, PendingTransactionParams } from '@explorins/pers-sdk/transaction';
 /**
- * SDK Error classes for type checking in catch blocks
+ * Structured error handling for PERS SDK
+ *
+ * The SDK provides comprehensive error classes and utilities for consistent error handling
+ * across all operations. Errors follow the StructuredError pattern from @explorins/pers-shared.
+ *
+ * **Error Classes:**
+ * - `PersApiError` - API errors with structured backend details
+ * - `AuthenticationError` - Authentication/authorization failures (401)
+ *
+ * **Error Utilities:**
+ * - `ErrorUtils.getMessage(error)` - Extract user-friendly message
+ * - `ErrorUtils.getStatus(error)` - Get HTTP status code
+ * - `ErrorUtils.isRetryable(error)` - Check if operation should be retried
+ * - `ErrorUtils.isTokenExpiredError(error)` - Detect token expiration
  *
  * @example
+ * **Basic Error Handling:**
  * ```typescript
- * import { PersApiError } from '@explorins/pers-sdk-react-native';
+ * import { PersApiError, ErrorUtils } from '@explorins/pers-sdk-react-native';
  *
  * try {
  *   await sdk.campaigns.claimCampaign({ campaignId });
  * } catch (error) {
  *   if (error instanceof PersApiError) {
- *     console.log(error.message);  // Clean backend message
- *     console.log(error.code);     // e.g., 'CAMPAIGN_BUSINESS_REQUIRED'
- *     console.log(error.status);   // e.g., 400
+ *     // Structured error with backend details
+ *     console.log('Error code:', error.code);        // 'CAMPAIGN_BUSINESS_REQUIRED'
+ *     console.log('Status:', error.status);          // 400
+ *     console.log('Message:', error.message);        // Backend error message
+ *     console.log('User message:', error.userMessage); // User-friendly message
+ *     console.log('Retryable:', error.retryable);    // false
+ *   } else {
+ *     // Generic error fallback
+ *     const message = ErrorUtils.getMessage(error);
+ *     console.error('Operation failed:', message);
  *   }
  * }
  * ```
+ *
+ * @example
+ * **Error Utilities:**
+ * ```typescript
+ * import { ErrorUtils } from '@explorins/pers-sdk-react-native';
+ *
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   const status = ErrorUtils.getStatus(error);      // Extract status code
+ *   const message = ErrorUtils.getMessage(error);    // Extract message
+ *   const retryable = ErrorUtils.isRetryable(error); // Check if retryable
+ *
+ *   if (ErrorUtils.isTokenExpiredError(error)) {
+ *     // Handle token expiration
+ *     await refreshToken();
+ *   } else if (retryable) {
+ *     // Retry operation
+ *     await retry(someOperation);
+ *   } else {
+ *     // Show error to user
+ *     showError(message);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **React Native Error Display:**
+ * ```typescript
+ * import { PersApiError, ErrorUtils } from '@explorins/pers-sdk-react-native';
+ * import { Alert } from 'react-native';
+ *
+ * const handleError = (error: unknown) => {
+ *   if (error instanceof PersApiError) {
+ *     // Show structured error
+ *     Alert.alert(
+ *       'Error',
+ *       error.userMessage || error.message,
+ *       [
+ *         { text: 'OK' },
+ *         error.retryable && { text: 'Retry', onPress: retry }
+ *       ].filter(Boolean)
+ *     );
+ *   } else {
+ *     // Show generic error
+ *     Alert.alert('Error', ErrorUtils.getMessage(error));
+ *   }
+ * };
+ * ```
  */
-export { PersApiError, AuthenticationError } from '@explorins/pers-sdk/core';
+export { PersApiError, AuthenticationError, ErrorUtils } from '@explorins/pers-sdk/core';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,aAAa,CAAC;AAMrB;;;;;;;;GAQG;AACH,OAAO,EACL,6BAA6B,EAC7B,KAAK,qBAAqB,EAC3B,MAAM,wCAAwC,CAAC;AAMhD;;;;;;;;;;GAUG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;;;;;;GAQG;AACH,OAAO,EACL,wBAAwB,GACzB,MAAM,uCAAuC,CAAC;AAM/C;;;GAGG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAMvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EACL,eAAe,EACf,UAAU,EACV,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,6BAA6B,CAAC;AAMrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,cAAc,EACd,OAAO,EACP,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,SAAS,EACV,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGrF,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM7F;;;;;;GAMG;AACH,OAAO,EACL,qBAAqB,EACtB,MAAM,sCAAsC,CAAC;AAM9C;;;;;;;;GAQG;AACH,OAAO,EACL,8BAA8B,EAC/B,MAAM,aAAa,CAAC;AAMrB;;;;;;;;;;;;;;;;GAgBG;AACH,cAAc,wBAAwB,CAAC;AAEvC;;;;GAIG;AACH,OAAO,EAAE,gCAAgC,EAAE,MAAM,2BAA2B,CAAC;AAE7E;;;;;GAKG;AACH,OAAO,EAEL,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;GAWG;AACH,YAAY,EACV,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAMlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAM/E;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,aAAa,CAAC;AAMrB;;;;;;;;GAQG;AACH,OAAO,EACL,6BAA6B,EAC7B,KAAK,qBAAqB,EAC3B,MAAM,wCAAwC,CAAC;AAMhD;;;;;;;;;;GAUG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;;;;;;GAQG;AACH,OAAO,EACL,wBAAwB,GACzB,MAAM,uCAAuC,CAAC;AAM/C;;;GAGG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAMvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EACL,eAAe,EACf,UAAU,EACV,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,6BAA6B,CAAC;AAMrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,cAAc,EACd,OAAO,EACP,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,SAAS,EACV,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGrF,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG7F,YAAY,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAMtG;;;;;;GAMG;AACH,OAAO,EACL,qBAAqB,EACtB,MAAM,sCAAsC,CAAC;AAM9C;;;;;;;;GAQG;AACH,OAAO,EACL,8BAA8B,EAC/B,MAAM,aAAa,CAAC;AAMrB;;;;;;;;;;;;;;;;GAgBG;AACH,cAAc,wBAAwB,CAAC;AAEvC;;;;GAIG;AACH,OAAO,EAAE,gCAAgC,EAAE,MAAM,2BAA2B,CAAC;AAE7E;;;;;GAKG;AACH,OAAO,EAEL,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;GAWG;AACH,YAAY,EACV,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAMlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,8BAA8B,EAC9B,2BAA2B,EAC5B,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAMzG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACX,MAAM,0BAA0B,CAAC"}