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

package/src/hooks/useCampaigns.ts

@@ -5,11 +5,14 @@ import type {
   CampaignDTO, 
   CampaignClaimDTO, 
   CampaignTriggerDTO,
-  CampaignCreateRequestDTO,
-  TokenUnitCreateRequestDTO,
-  CampaignBusinessEngagementCreateRequestDTO,
-  PaginatedResponseDTO
+  PaginatedResponseDTO,
+  CampaignClaimIncludeRelation,
+  CampaignIncludeRelation
 } from '@explorins/pers-shared';
+import type { CampaignClaimFilters } from '@explorins/pers-sdk/campaign';
+
+// Re-export for consumers
+export type { CampaignClaimFilters } from '@explorins/pers-sdk/campaign';
 
 export const useCampaigns = () => {
   const { sdk, isInitialized, isAuthenticated } = usePersSDK();
@@ -28,13 +31,30 @@ export const useCampaigns = () => {
     }
   }, [sdk, isInitialized]);
 
-  const getCampaignById = useCallback(async (campaignId: string): Promise<CampaignDTO | null> => {
+  /**
+   * Get campaign by ID with optional include relations
+   * 
+   * @param campaignId - The campaign ID
+   * @param include - Relations to include: 'triggerSources', 'businesses'
+   * @returns Promise resolving to campaign data
+   * 
+   * @example
+   * ```typescript
+   * // Get campaign with all related data
+   * const campaign = await getCampaignById('campaign-123', ['triggerSources', 'businesses']);
+   * console.log('Trigger sources:', campaign.included?.triggerSources);
+   * ```
+   */
+  const getCampaignById = useCallback(async (
+    campaignId: string,
+    include?: CampaignIncludeRelation[]
+  ): Promise<CampaignDTO | null> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.campaigns.getCampaignById(campaignId);
+      const result = await sdk.campaigns.getCampaignById(campaignId, include);
       return result;
     } catch (error) {
       console.error('Failed to fetch campaign:', error);
@@ -59,7 +79,29 @@ export const useCampaigns = () => {
     }
   }, [sdk, isInitialized, isAuthenticated]);
 
-  const getUserClaims = useCallback(async (): Promise<PaginatedResponseDTO<CampaignClaimDTO>> => {
+  /**
+   * Get user's campaign claims with optional pagination and include relations
+   * 
+   * @param options - Optional options including pagination and include relations
+   * @returns Promise resolving to paginated campaign claims
+   * 
+   * @example
+   * ```typescript
+   * // Get user's claims with campaign details
+   * const { data: claims } = await getUserClaims({ include: ['campaign', 'business'] });
+   * claims.forEach(claim => {
+   *   console.log('Campaign:', claim.included?.campaign?.title);
+   * });
+   * 
+   * // With pagination
+   * const { data } = await getUserClaims({ page: 1, limit: 10, include: ['campaign'] });
+   * ```
+   */
+  const getUserClaims = useCallback(async (options?: {
+    page?: number;
+    limit?: number;
+    include?: CampaignClaimIncludeRelation[];
+  }): Promise<PaginatedResponseDTO<CampaignClaimDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
@@ -69,7 +111,7 @@ export const useCampaigns = () => {
     }
     
     try {
-      const result = await sdk.campaigns.getUserClaims();
+      const result = await sdk.campaigns.getUserClaims(options);
       return result;
     } catch (error) {
       console.error('Failed to fetch user claims:', error);
@@ -106,13 +148,32 @@ export const useCampaigns = () => {
     }
   }, [sdk, isInitialized]);
 
-  const getCampaignClaims = useCallback(async (): Promise<PaginatedResponseDTO<CampaignClaimDTO>> => {
+  /**
+   * Admin: Get campaign claims with optional filters and include relations
+   * 
+   * @param filters - Optional filters for campaign, user, or business
+   * @param include - Relations to include: 'campaign', 'user', 'business'
+   * @returns Promise resolving to paginated campaign claims
+   * 
+   * @example
+   * ```typescript
+   * // Get all claims with user details
+   * const { data: claims } = await getCampaignClaims({}, ['user']);
+   * 
+   * // Get claims for a specific campaign
+   * const { data } = await getCampaignClaims({ campaignId: 'campaign-123' }, ['user', 'business']);
+   * ```
+   */
+  const getCampaignClaims = useCallback(async (
+    filters?: CampaignClaimFilters,
+    include?: CampaignClaimIncludeRelation[]
+  ): Promise<PaginatedResponseDTO<CampaignClaimDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.campaigns.getCampaignClaims();
+      const result = await sdk.campaigns.getCampaignClaims(filters, include);
       return result;
     } catch (error) {
       console.error('Failed to fetch campaign claims:', error);
@@ -120,13 +181,23 @@ export const useCampaigns = () => {
     }
   }, [sdk, isInitialized]);
 
-  const getCampaignClaimsByUserId = useCallback(async (userId: string): Promise<PaginatedResponseDTO<CampaignClaimDTO>> => {
+  /**
+   * Admin: Get campaign claims by user ID with optional include relations
+   * 
+   * @param userId - The user ID
+   * @param include - Relations to include: 'campaign', 'user', 'business'
+   * @returns Promise resolving to paginated campaign claims
+   */
+  const getCampaignClaimsByUserId = useCallback(async (
+    userId: string,
+    include?: CampaignClaimIncludeRelation[]
+  ): Promise<PaginatedResponseDTO<CampaignClaimDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.campaigns.getCampaignClaimsByUserId(userId);
+      const result = await sdk.campaigns.getCampaignClaimsByUserId(userId, undefined, include);
       return result;
     } catch (error) {
       console.error('Failed to fetch campaign claims by user ID:', error);
@@ -134,13 +205,23 @@ export const useCampaigns = () => {
     }
   }, [sdk, isInitialized]);
 
-  const getCampaignClaimsByBusinessId = useCallback(async (businessId: string): Promise<PaginatedResponseDTO<CampaignClaimDTO>> => {
+  /**
+   * Admin: Get campaign claims by business ID with optional include relations
+   * 
+   * @param businessId - The business ID
+   * @param include - Relations to include: 'campaign', 'user', 'business'
+   * @returns Promise resolving to paginated campaign claims
+   */
+  const getCampaignClaimsByBusinessId = useCallback(async (
+    businessId: string,
+    include?: CampaignClaimIncludeRelation[]
+  ): Promise<PaginatedResponseDTO<CampaignClaimDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.campaigns.getCampaignClaimsByBusinessId(businessId);
+      const result = await sdk.campaigns.getCampaignClaimsByBusinessId(businessId, undefined, include);
       return result;
     } catch (error) {
       console.error('Failed to fetch campaign claims by business ID:', error);
@@ -148,6 +229,85 @@ export const useCampaigns = () => {
     }
   }, [sdk, isInitialized]);
 
+  // ==========================================
+  // TRIGGER SOURCE ASSIGNMENT (Admin)
+  // Note: TriggerSource CRUD is in useTriggerSources hook
+  // ==========================================
+
+  /**
+   * Admin: Assign a trigger source to a campaign
+   * 
+   * Associates a trigger source (QR code, NFC tag, etc.) with a campaign.
+   * A campaign can have multiple trigger sources.
+   * 
+   * Note: To create/update/delete trigger sources, use `useTriggerSources` hook.
+   * 
+   * @param campaignId - Campaign UUID
+   * @param triggerSourceId - Trigger source UUID
+   * @returns Promise resolving to updated campaign
+   * 
+   * @example
+   * ```typescript
+   * const { create } = useTriggerSources();
+   * const { assignTriggerSource } = useCampaigns();
+   * 
+   * // Create trigger source first
+   * const source = await create({ type: 'QR_CODE', name: 'Store QR' });
+   * 
+   * // Then assign to campaign
+   * const updated = await assignTriggerSource('campaign-123', source.id);
+   * ```
+   */
+  const assignTriggerSource = useCallback(async (
+    campaignId: string,
+    triggerSourceId: string
+  ): Promise<CampaignDTO> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    if (!isAuthenticated) {
+      throw new Error('SDK not authenticated. assignTriggerSource requires admin authentication.');
+    }
+    
+    try {
+      const result = await sdk.campaigns.assignTriggerSource(campaignId, triggerSourceId);
+      return result;
+    } catch (error) {
+      console.error('Failed to assign trigger source:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized, isAuthenticated]);
+
+  /**
+   * Admin: Remove a trigger source from a campaign
+   * 
+   * Removes the association between a trigger source and a campaign.
+   * The trigger source itself is not deleted.
+   * 
+   * @param campaignId - Campaign UUID
+   * @param triggerSourceId - Trigger source UUID
+   * @returns Promise resolving to updated campaign
+   */
+  const removeTriggerSource = useCallback(async (
+    campaignId: string,
+    triggerSourceId: string
+  ): Promise<CampaignDTO> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    if (!isAuthenticated) {
+      throw new Error('SDK not authenticated. removeTriggerSource requires admin authentication.');
+    }
+    
+    try {
+      const result = await sdk.campaigns.removeTriggerSource(campaignId, triggerSourceId);
+      return result;
+    } catch (error) {
+      console.error('Failed to remove trigger source:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized, isAuthenticated]);
+
   return {
     getActiveCampaigns,
     getCampaignById,
@@ -158,6 +318,8 @@ export const useCampaigns = () => {
     getCampaignClaims,
     getCampaignClaimsByUserId,
     getCampaignClaimsByBusinessId,
+    assignTriggerSource,
+    removeTriggerSource,
     isAvailable: isInitialized && !!sdk?.campaigns,
   };
 };

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/useRedemptions.ts

@@ -7,8 +7,13 @@ import type {
   RedemptionRedeemDTO, 
   RedemptionRedeemRequestResponseDTO,
   RedemptionTypeDTO,
-  PaginatedResponseDTO
+  PaginatedResponseDTO,
+  RedemptionRedeemIncludeRelation
 } from '@explorins/pers-shared';
+import type { RedemptionRedeemFilters } from '@explorins/pers-sdk/redemption';
+
+// Re-export for consumers
+export type { RedemptionRedeemFilters } from '@explorins/pers-sdk/redemption';
 
 export const useRedemptions = () => {
   const { sdk, isInitialized, isAuthenticated } = usePersSDK();
@@ -36,7 +41,25 @@ export const useRedemptions = () => {
     }
   }, [sdk, isInitialized]);
 
-  const getUserRedemptions = useCallback(async (): Promise<PaginatedResponseDTO<RedemptionRedeemDTO>> => {
+  /**
+   * Get user's redemption history with optional include relations
+   * 
+   * @param include - Relations to include: 'redemption', 'user', 'business'
+   * @returns Promise resolving to paginated redemption history
+   * 
+   * @example
+   * ```typescript
+   * // Get user redemptions with full redemption details
+   * const { data: redeems } = await getUserRedemptions(['redemption', 'business']);
+   * redeems.forEach(redeem => {
+   *   console.log('Redemption:', redeem.included?.redemption?.title);
+   *   console.log('Business:', redeem.included?.business?.displayName);
+   * });
+   * ```
+   */
+  const getUserRedemptions = useCallback(async (
+    include?: RedemptionRedeemIncludeRelation[]
+  ): Promise<PaginatedResponseDTO<RedemptionRedeemDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
@@ -46,7 +69,7 @@ export const useRedemptions = () => {
     }
     
     try {
-      const result = await sdk.redemptions.getUserRedemptions();
+      const result = await sdk.redemptions.getUserRedemptions(undefined, include);
       return result;
     } catch (error) {
       console.error('Failed to fetch user redemptions:', error);
@@ -100,6 +123,45 @@ export const useRedemptions = () => {
   }, [sdk, isInitialized, isAuthenticated, signAndSubmitTransactionWithJWT, isSignerAvailable]);
 
   // Admin methods
+
+  /**
+   * Admin: Get all redemption redeems with filters and include relations
+   * 
+   * Retrieves all redemption redeems across the platform with filtering.
+   * 
+   * @param filters - Optional filters for user, redemption, and pagination
+   * @param include - Relations to include: 'redemption', 'user', 'business'
+   * @returns Promise resolving to paginated redemption redeems
+   * 
+   * @example
+   * ```typescript
+   * // Get all redeems with user details
+   * const { data: redeems } = await getRedemptionRedeems({}, ['user', 'redemption']);
+   * 
+   * // Filter by specific user
+   * const { data: userRedeems } = await getRedemptionRedeems(
+   *   { userId: 'user-123' },
+   *   ['redemption']
+   * );
+   * ```
+   */
+  const getRedemptionRedeems = useCallback(async (
+    filters?: RedemptionRedeemFilters,
+    include?: RedemptionRedeemIncludeRelation[]
+  ): Promise<PaginatedResponseDTO<RedemptionRedeemDTO>> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.redemptions.getRedemptionRedeems(filters, include);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch redemption redeems:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
   const createRedemption = useCallback(async (redemptionData: RedemptionCreateRequestDTO): Promise<RedemptionDTO> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
@@ -161,6 +223,7 @@ export const useRedemptions = () => {
     getUserRedemptions,
     redeem,
     getRedemptionTypes,
+    getRedemptionRedeems,
     createRedemption,
     updateRedemption,
     toggleRedemptionStatus,

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,