@explorins/pers-sdk-react-native 2.1.5 → 2.1.6

package/dist/providers/PersSDKProvider.d.ts

@@ -2,6 +2,15 @@ import React, { ReactNode } from 'react';
 import { PersSDK, PersConfig, DefaultAuthProvider } from '@explorins/pers-sdk/core';
 import { UserDTO, AdminDTO } from '@explorins/pers-shared';
 export type { PersConfig } from '@explorins/pers-sdk/core';
+/**
+ * Context interface for PERS SDK React Native integration
+ *
+ * @property sdk - Main SDK instance (null until initialized)
+ * @property authProvider - Platform-specific auth provider
+ * @property isInitialized - Whether SDK has been initialized
+ * @property isAuthenticated - Whether user is currently authenticated
+ * @property user - Current user data (null if not authenticated)
+ */
 export interface PersSDKContext {
     sdk: PersSDK | null;
     authProvider: DefaultAuthProvider | null;
@@ -13,6 +22,35 @@ export interface PersSDKContext {
     refreshUserData: () => Promise<void>;
     restoreSession: () => Promise<UserDTO | null>;
 }
+/**
+ * PERS SDK Provider for React Native
+ *
+ * Wraps your app to provide SDK context to all child components.
+ * Handles platform-specific initialization (DPoP, storage, etc.).
+ *
+ * @param config - SDK configuration (see PersConfig)
+ * @param config.apiProjectKey - Your PERS project key (required)
+ * @param config.environment - 'staging' | 'production' (default: 'staging')
+ * @param config.captureWalletEvents - Enable real-time blockchain events (default: true)
+ * @param config.dpop - DPoP configuration for enhanced security
+ *
+ * @example Basic usage
+ * ```tsx
+ * <PersSDKProvider config={{ apiProjectKey: 'my-project' }}>
+ *   <App />
+ * </PersSDKProvider>
+ * ```
+ *
+ * @example Disable wallet events
+ * ```tsx
+ * <PersSDKProvider config={{
+ *   apiProjectKey: 'my-project',
+ *   captureWalletEvents: false  // Disable auto-connect to blockchain events
+ * }}>
+ *   <App />
+ * </PersSDKProvider>
+ * ```
+ */
 export declare const PersSDKProvider: React.FC<{
     children: ReactNode;
     config?: PersConfig;

package/dist/providers/PersSDKProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PersSDKProvider.d.ts","sourceRoot":"","sources":["../../src/providers/PersSDKProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAuC,SAAS,EAA2C,MAAM,OAAO,CAAC;AAEvH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAIpF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAkB3D,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,MAAM,WAAW,cAAc;IAE7B,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAGpB,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAGzC,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC;IAGhC,UAAU,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,sBAAsB,EAAE,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,EAAE,eAAe,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5F,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,cAAc,EAAE,MAAM,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CAC/C;AAMD,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC;IACrC,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB,CAwOA,CAAC;AAGF,eAAO,MAAM,UAAU,QAAO,cAQ7B,CAAC"}
+{"version":3,"file":"PersSDKProvider.d.ts","sourceRoot":"","sources":["../../src/providers/PersSDKProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAuC,SAAS,EAA2C,MAAM,OAAO,CAAC;AAEvH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAIpF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAkB3D,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAE7B,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAGpB,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAGzC,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC;IAGhC,UAAU,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,sBAAsB,EAAE,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,EAAE,eAAe,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5F,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,cAAc,EAAE,MAAM,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CAC/C;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC;IACrC,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB,CAwOA,CAAC;AAGF,eAAO,MAAM,UAAU,QAAO,cAQ7B,CAAC"}

package/dist/providers/PersSDKProvider.js

@@ -7,7 +7,35 @@ import { createReactNativeAuthProvider } from './react-native-auth-provider';
 import { ReactNativeDPoPProvider } from './rn-dpop-provider';
 // Create the context
 const SDKContext = createContext(null);
-// Provider component
+/**
+ * PERS SDK Provider for React Native
+ *
+ * Wraps your app to provide SDK context to all child components.
+ * Handles platform-specific initialization (DPoP, storage, etc.).
+ *
+ * @param config - SDK configuration (see PersConfig)
+ * @param config.apiProjectKey - Your PERS project key (required)
+ * @param config.environment - 'staging' | 'production' (default: 'staging')
+ * @param config.captureWalletEvents - Enable real-time blockchain events (default: true)
+ * @param config.dpop - DPoP configuration for enhanced security
+ *
+ * @example Basic usage
+ * ```tsx
+ * <PersSDKProvider config={{ apiProjectKey: 'my-project' }}>
+ *   <App />
+ * </PersSDKProvider>
+ * ```
+ *
+ * @example Disable wallet events
+ * ```tsx
+ * <PersSDKProvider config={{
+ *   apiProjectKey: 'my-project',
+ *   captureWalletEvents: false  // Disable auto-connect to blockchain events
+ * }}>
+ *   <App />
+ * </PersSDKProvider>
+ * ```
+ */
 export const PersSDKProvider = ({ children, config }) => {
     const initializingRef = useRef(false);
     // State refs for stable functions to read current values

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk-react-native",
-  "version": "2.1.5",
+  "version": "2.1.6",
   "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": "^2.1.6",
+    "@explorins/pers-sdk": "^2.1.14",
     "@explorins/pers-signer": "^1.0.33",
     "buffer": "^6.0.3",
     "ethers": "^6.15.0",
@@ -155,6 +155,7 @@
     "@ethersproject/scrypt": false
   },
   "devDependencies": {
+    "@explorins/pers-shared": "^2.1.117",
     "@rollup/plugin-commonjs": "^25.0.7",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^15.2.3",

package/src/hooks/useEvents.ts

@@ -35,23 +35,35 @@ export interface EventsHook {
  * React Native hook for PERS SDK event system
  * 
  * This hook provides access to the platform-agnostic event system for subscribing to
- * transaction, authentication, campaign, and system events. All events include a 
- * `userMessage` field ready for display to end users.
+ * transaction, authentication, campaign, blockchain, and system events. All events 
+ * include a `userMessage` field ready for display to end users.
  * 
  * **Event Domains:**
  * - `auth` - Authentication events (login, logout, token refresh)
  * - `user` - User profile events (update, create)
- * - `transaction` - Transaction events (created, completed, failed)
+ * - `transaction` - Transaction events (created, submitted, confirmed)
  * - `campaign` - Campaign events (claimed, activated)
  * - `redemption` - Redemption events (redeemed, expired)
  * - `business` - Business events (created, updated, membership)
+ * - `wallet` - Real-time blockchain events (Transfer, Approval, etc.) - Auto-enabled on auth
  * - `api` - API error events (network, validation, server errors)
  * 
+ * **Blockchain Events (Wallet Domain):**
+ * When `sdk.connectWalletEvents()` is called (or auto-enabled via `captureWalletEvents: true`),
+ * real-time blockchain events are automatically routed through the same event system:
+ * ```typescript
+ * const { subscribe } = useEvents();
+ * 
+ * subscribe((event) => {
+ *   if (event.domain === 'wallet') {
+ *     console.log('Blockchain event:', event.type); // wallet_transfer, wallet_approval, etc.
+ *   }
+ * });
+ * ```
+ * 
  * **Notification Levels:**
  * - `success` - Operation completed successfully
  * - `error` - Operation failed
- * - `warning` - Operation completed with warnings
- * - `info` - Informational event
  * 
  * **Cleanup:**
  * All subscriptions created through this hook are automatically cleaned up when

package/src/hooks/useTokenBalances.ts

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useState, useRef } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
 import { useWeb3 } from './useWeb3';
 import { NativeTokenTypes, type TokenDTO } from '@explorins/pers-shared';
@@ -36,6 +36,18 @@ export interface UseTokenBalancesOptions {
   autoLoad?: boolean;
   /** Optional refresh interval in milliseconds (0 = disabled) */
   refreshInterval?: number;
+  /** 
+   * Auto-refresh balances when wallet events are received (Transfer, Approval, etc.)
+   * Requires `captureWalletEvents: true` in SDK config (default)
+   * @default true
+   */
+  refreshOnWalletEvents?: boolean;
+  /**
+   * Debounce time for wallet event-triggered refreshes (milliseconds)
+   * Prevents rapid refresh calls during batch transfers
+   * @default 1000
+   */
+  walletEventDebounceMs?: number;
 }
 
 /**
@@ -126,6 +138,18 @@ export interface UseTokenBalancesResult {
  * ```
  * 
  * @example
+ * **With Wallet Events (Real-time):**
+ * ```typescript
+ * // Auto-refresh on Transfer, Approval, and other blockchain events
+ * const { tokenBalances } = useTokenBalances({
+ *   accountAddress: walletAddress!,
+ *   availableTokens,
+ *   refreshOnWalletEvents: true,    // Enable real-time refresh (default: true)
+ *   walletEventDebounceMs: 1000     // Debounce rapid events (default: 1000ms)
+ * });
+ * ```
+ * 
+ * @example
  * **Multi-Wallet Support:**
  * ```typescript
  * function MultiWalletBalances() {
@@ -148,7 +172,9 @@ export function useTokenBalances(options: UseTokenBalancesOptions): UseTokenBala
     accountAddress,
     availableTokens = [],
     autoLoad = true,
-    refreshInterval = 0
+    refreshInterval = 0,
+    refreshOnWalletEvents = true,
+    walletEventDebounceMs = 1000
   } = options;
 
   const { isAuthenticated, sdk } = usePersSDK();
@@ -157,6 +183,9 @@ export function useTokenBalances(options: UseTokenBalancesOptions): UseTokenBala
   const [tokenBalances, setTokenBalances] = useState<TokenBalanceWithToken[]>([]);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  
+  // Debounce ref for wallet events
+  const walletEventDebounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   // Check if the hook is available for use
   const isAvailable = web3.isAvailable && isAuthenticated && !!accountAddress;
@@ -293,6 +322,35 @@ export function useTokenBalances(options: UseTokenBalancesOptions): UseTokenBala
     };
   }, [sdk, refreshInterval, isAvailable, loadBalances]);
 
+  // Wallet events refresh: listen for real-time blockchain events
+  // Refreshes on ANY wallet domain event (Transfer, TransferSingle, etc.)
+  // Debouncing prevents excessive API calls during rapid events
+  useEffect(() => {
+    if (!sdk || !refreshOnWalletEvents || !isAvailable) return;
+
+    const unsubscribe = sdk.events.subscribe((event) => {
+      if (event.domain === 'wallet') {
+        // Debounce rapid events (batch transfers, etc.)
+        if (walletEventDebounceRef.current) {
+          clearTimeout(walletEventDebounceRef.current);
+        }
+        
+        walletEventDebounceRef.current = setTimeout(() => {
+          console.log(`[useTokenBalances] Wallet event (${event.type}), refreshing balances...`);
+          loadBalances();
+          walletEventDebounceRef.current = null;
+        }, walletEventDebounceMs);
+      }
+    }, { domains: ['wallet'] });
+
+    return () => {
+      unsubscribe();
+      if (walletEventDebounceRef.current) {
+        clearTimeout(walletEventDebounceRef.current);
+      }
+    };
+  }, [sdk, refreshOnWalletEvents, walletEventDebounceMs, isAvailable, loadBalances]);
+
   return {
     tokenBalances,
     isLoading,

package/src/hooks/useUsers.ts

@@ -1,12 +1,31 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
 import type { UserDTO, UserCreateRequestDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
-import type { UserPublicProfileDTO } from '@explorins/pers-sdk/user';
+import type { UserPublicProfileDTO, UserQueryOptions } from '@explorins/pers-sdk/user';
+
+// Re-export for consumers
+export type { UserQueryOptions } from '@explorins/pers-sdk/user';
 
 export const useUsers = () => {
   const { sdk, isInitialized, isAuthenticated } = usePersSDK();
 
-  const getCurrentUser = useCallback(async (): Promise<UserDTO> => {
+  /**
+   * Get the current authenticated user with optional include relations
+   * 
+   * @param options - Query options including include relations
+   * @returns Current user data
+   * 
+   * @example
+   * ```typescript
+   * // Basic
+   * const user = await getCurrentUser();
+   * 
+   * // With wallets included
+   * const userWithWallets = await getCurrentUser({ include: ['wallets'] });
+   * console.log('Wallets:', userWithWallets.included?.wallets);
+   * ```
+   */
+  const getCurrentUser = useCallback(async (options?: UserQueryOptions): Promise<UserDTO> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
@@ -15,7 +34,7 @@ export const useUsers = () => {
     }
     
     try {
-      const result = await sdk.users.getCurrentUser();
+      const result = await sdk.users.getCurrentUser(options);
       return result;
     } catch (error) {
       console.error('Failed to fetch current user:', error);
@@ -40,13 +59,29 @@ export const useUsers = () => {
     }
   }, [sdk, isInitialized, isAuthenticated]);
 
-  const getUserById = useCallback(async (userId: string): Promise<UserDTO> => {
+  /**
+   * Get user by ID with optional include relations
+   * 
+   * @param userId - User identifier (id, email, externalId, etc.)
+   * @param options - Query options including include relations
+   * @returns User data
+   * 
+   * @example
+   * ```typescript
+   * // Basic
+   * const user = await getUserById('user-123');
+   * 
+   * // With wallets included
+   * const userWithWallets = await getUserById('user-123', { include: ['wallets'] });
+   * ```
+   */
+  const getUserById = useCallback(async (userId: string, options?: UserQueryOptions): Promise<UserDTO> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.users.getUserById(userId);
+      const result = await sdk.users.getUserById(userId, options);
       return result;
     } catch (error) {
       console.error('Failed to fetch user:', error);
@@ -97,16 +132,23 @@ export const useUsers = () => {
     }
   }, [sdk, isInitialized]);
 
-  const toggleUserStatus = useCallback(async (user: UserDTO): Promise<UserDTO> => {
+  /**
+   * Toggle or set a user's active status (admin only)
+   * 
+   * @param userId - User ID to update
+   * @param isActive - Optional explicit status. If omitted, toggles current status.
+   * @returns Updated user
+   */
+  const setUserActiveStatus = useCallback(async (userId: string, isActive?: boolean): Promise<UserDTO> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.users.toggleUserStatus(user);
+      const result = await sdk.users.setUserActiveStatus(userId, isActive);
       return result;
     } catch (error) {
-      console.error('Failed to toggle user status:', error);
+      console.error('Failed to set user active status:', error);
       throw error;
     }
   }, [sdk, isInitialized]);
@@ -118,7 +160,7 @@ export const useUsers = () => {
     getAllUsersPublic,
     getAllUsers,
     updateUser,
-    toggleUserStatus,
+    setUserActiveStatus,
     isAvailable: isInitialized && !!sdk?.users,
   };
 };

package/src/hooks/useWeb3.ts

@@ -9,8 +9,10 @@ import type {
   TokenMetadata,
   AccountOwnedTokensResult
 } from '@explorins/pers-sdk/web3';
-import type { ChainData } from '@explorins/pers-sdk/web3-chain';
-import type { TokenDTO } from '@explorins/pers-shared';
+import type { TokenDTO } from '@explorins/pers-sdk/token';
+
+// ChainData type - matches what Web3Manager.getChainDataById returns
+type ChainData = Awaited<ReturnType<Web3Manager['getChainDataById']>>;
 
 // Re-export for convenience
 export type { AccountOwnedTokensResult } from '@explorins/pers-sdk/web3';
@@ -161,27 +163,40 @@ export const useWeb3 = () => {
     }
   }, [web3, isInitialized]);
 
-  const resolveIPFSUrl = useCallback(async (url: string, chainId: number): Promise<string> => {
-    if (!isInitialized || !web3) {
+  /**
+   * Resolve IPFS URL to HTTP gateway URL
+   * 
+   * @deprecated Use `sdk.tenant.resolveIPFSUrl()` directly - IPFS is chain-agnostic
+   * @param url - IPFS URL to resolve (ipfs://...)
+   * @returns Promise resolving to HTTP gateway URL
+   */
+  const resolveIPFSUrl = useCallback(async (url: string): Promise<string> => {
+    if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await web3.resolveIPFSUrl(url, chainId);
+      const result = await sdk.tenants.resolveIPFSUrl(url);
       return result;
     } catch (error) {
       console.error('Failed to resolve IPFS URL:', error);
       throw error;
     }
-  }, [web3, isInitialized]);
+  }, [sdk, isInitialized]);
 
-  const fetchAndProcessMetadata = useCallback(async (tokenUri: string, chainId: number): Promise<TokenMetadata | null> => {
+  /**
+   * Fetch and process token metadata from a URI
+   * 
+   * @param tokenUri - Token URI to fetch metadata from
+   * @returns Promise resolving to processed metadata or null
+   */
+  const fetchAndProcessMetadata = useCallback(async (tokenUri: string): Promise<TokenMetadata | null> => {
     if (!isInitialized || !web3) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await web3.fetchAndProcessMetadata(tokenUri, chainId);
+      const result = await web3.fetchAndProcessMetadata(tokenUri);
       return result;
     } catch (error) {
       console.error('Failed to fetch and process metadata:', error);
@@ -189,7 +204,7 @@ export const useWeb3 = () => {
     }
   }, [web3, isInitialized]);
 
-  const getChainDataById = useCallback(async (chainId: number): Promise<ChainData | null> => {
+  const getChainDataById = useCallback(async (chainId: number): Promise<ChainData> => {
     if (!isInitialized || !web3) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
@@ -255,7 +270,7 @@ export const useWeb3 = () => {
    * 
    * @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)
+   * @param maxTokens - Maximum tokens to retrieve (default: 100, max: 100)
    * @returns Promise resolving to result with owned tokens
    * @throws Error if SDK is not initialized
    * 
@@ -277,7 +292,7 @@ export const useWeb3 = () => {
   const getAccountOwnedTokensFromContract = useCallback(async (
     accountAddress: string,
     token: TokenDTO,
-    maxTokens: number = 50
+    maxTokens: number = 100
   ): Promise<AccountOwnedTokensResult> => {
     if (!isInitialized || !web3) {
       throw new Error('SDK not initialized. Call initialize() first.');
@@ -295,13 +310,13 @@ export const useWeb3 = () => {
    * 
    * @param accountAddress - Any valid blockchain address (wallet, contract, etc.)
    * @param token - Token definition
-   * @param maxTokens - Maximum tokens to retrieve (default: 50)
+   * @param maxTokens - Maximum tokens to retrieve (default: 100, max: 100)
    * @returns TokenCollectionRequest ready for getTokenCollection()
    */
   const buildCollectionRequest = useCallback((
     accountAddress: string,
     token: TokenDTO,
-    maxTokens: number = 50
+    maxTokens: number = 100
   ): TokenCollectionRequest => {
     if (!web3) {
       throw new Error('SDK not initialized. Call initialize() first.');

package/src/providers/PersSDKProvider.tsx

@@ -24,6 +24,15 @@ import type {
 // Re-export PersConfig for external use
 export type { PersConfig } from '@explorins/pers-sdk/core';
 
+/**
+ * Context interface for PERS SDK React Native integration
+ * 
+ * @property sdk - Main SDK instance (null until initialized)
+ * @property authProvider - Platform-specific auth provider
+ * @property isInitialized - Whether SDK has been initialized
+ * @property isAuthenticated - Whether user is currently authenticated
+ * @property user - Current user data (null if not authenticated)
+ */
 export interface PersSDKContext {
   // Main SDK instance
   sdk: PersSDK | null;
@@ -46,7 +55,35 @@ export interface PersSDKContext {
 // Create the context
 const SDKContext = createContext<PersSDKContext | null>(null);
 
-// Provider component
+/**
+ * PERS SDK Provider for React Native
+ * 
+ * Wraps your app to provide SDK context to all child components.
+ * Handles platform-specific initialization (DPoP, storage, etc.).
+ * 
+ * @param config - SDK configuration (see PersConfig)
+ * @param config.apiProjectKey - Your PERS project key (required)
+ * @param config.environment - 'staging' | 'production' (default: 'staging')
+ * @param config.captureWalletEvents - Enable real-time blockchain events (default: true)
+ * @param config.dpop - DPoP configuration for enhanced security
+ * 
+ * @example Basic usage
+ * ```tsx
+ * <PersSDKProvider config={{ apiProjectKey: 'my-project' }}>
+ *   <App />
+ * </PersSDKProvider>
+ * ```
+ * 
+ * @example Disable wallet events
+ * ```tsx
+ * <PersSDKProvider config={{ 
+ *   apiProjectKey: 'my-project',
+ *   captureWalletEvents: false  // Disable auto-connect to blockchain events
+ * }}>
+ *   <App />
+ * </PersSDKProvider>
+ * ```
+ */
 export const PersSDKProvider: React.FC<{
   children: ReactNode;
   config?: PersConfig;