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

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/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

@@ -151,7 +151,7 @@ export function useTokenBalances(options: UseTokenBalancesOptions): UseTokenBala
     refreshInterval = 0
   } = options;
 
-  const { isAuthenticated } = usePersSDK();
+  const { isAuthenticated, sdk } = usePersSDK();
   const web3 = useWeb3();
   
   const [tokenBalances, setTokenBalances] = useState<TokenBalanceWithToken[]>([]);
@@ -268,16 +268,30 @@ export function useTokenBalances(options: UseTokenBalancesOptions): UseTokenBala
     }
   }, [autoLoad, isAvailable, availableTokens.length, loadBalances]);
 
-  // Optional auto-refresh interval
+  // Event-driven refresh: listen for transaction events instead of polling
   useEffect(() => {
-    if (refreshInterval > 0 && isAvailable && availableTokens.length > 0) {
-      const intervalId = setInterval(() => {
+    if (!sdk || refreshInterval <= 0 || !isAvailable) return;
+
+    // Subscribe to transaction domain events
+    const unsubscribe = sdk.events.subscribe((event) => {
+      if (event.domain === 'transaction' && event.type === 'transaction_completed') {
+        console.log('[useTokenBalances] Transaction completed, refreshing balances...');
         loadBalances();
-      }, refreshInterval);
-      
-      return () => clearInterval(intervalId);
-    }
-  }, [refreshInterval, isAvailable, availableTokens.length, loadBalances]);
+      }
+    }, { domains: ['transaction'] });
+
+    // Also set up a fallback polling interval (much longer than before)
+    // This handles cases where events might be missed
+    const fallbackInterval = Math.max(refreshInterval, 60000); // Minimum 1 minute
+    const intervalId = setInterval(() => {
+      loadBalances();
+    }, fallbackInterval);
+
+    return () => {
+      unsubscribe();
+      clearInterval(intervalId);
+    };
+  }, [sdk, refreshInterval, isAvailable, loadBalances]);
 
   return {
     tokenBalances,

package/src/hooks/useTransactions.ts

@@ -5,10 +5,14 @@ import type {
   TransactionRequestDTO, 
   TransactionRequestResponseDTO, 
   TransactionDTO,
-  TransactionRole,
   TransactionPaginationRequestDTO,
-  PaginatedResponseDTO
+  PaginatedResponseDTO,
+  TransactionIncludeRelation
 } from '@explorins/pers-shared';
+import type { TransactionQueryOptions } from '@explorins/pers-sdk/transaction';
+
+// Re-export for consumers
+export type { TransactionQueryOptions } from '@explorins/pers-sdk/transaction';
 
 /**
  * React hook for transaction operations in the PERS SDK
@@ -124,26 +128,36 @@ export const useTransactions = () => {
   }, [sdk, isInitialized, signAndSubmitTransactionWithJWT, isSignerAvailable]);
 
   /**
-   * Retrieves a specific transaction by its ID
+   * Retrieves a specific transaction by its ID with optional include relations
    * 
    * @param transactionId - Unique identifier of the transaction
+   * @param include - Optional relations to include (sender, recipient, business) for enriched entity data
    * @returns Promise resolving to transaction data or null if not found
    * @throws Error if SDK is not initialized
    * 
    * @example
    * ```typescript
    * const { getTransactionById } = useTransactions();
+   * 
+   * // Basic retrieval
    * const transaction = await getTransactionById('txn-123');
-   * console.log('Transaction details:', transaction);
+   * 
+   * // With enriched sender/recipient data
+   * const enrichedTx = await getTransactionById('txn-123', ['sender', 'recipient', 'business']);
+   * console.log('Sender:', enrichedTx?.included?.sender);
+   * console.log('Business:', enrichedTx?.included?.engagedBusiness?.displayName);
    * ```
    */
-  const getTransactionById = useCallback(async (transactionId: string): Promise<TransactionDTO | null> => {
+  const getTransactionById = useCallback(async (
+    transactionId: string,
+    include?: TransactionIncludeRelation[]
+  ): Promise<TransactionDTO | null> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.transactions.getTransactionById(transactionId);
+      const result = await sdk.transactions.getTransactionById(transactionId, include);
       return result;
     } catch (error) {
       console.error('Failed to fetch transaction:', error);
@@ -152,27 +166,52 @@ export const useTransactions = () => {
   }, [sdk, isInitialized]);
 
   /**
-   * Retrieves transaction history for the authenticated user, filtered by role
+   * Retrieves transaction history for the authenticated user with comprehensive filtering
    * 
-   * @param role - Optional transaction role filter (TransactionRole.SENDER, TransactionRole.RECIPIENT)
-   * @returns Promise resolving to array of user's transactions
+   * Supports filtering by role, status, type, business, token, and more.
+   * Optionally enrich with related entities (sender, recipient, business).
+   * 
+   * @param options - Query options including filters, pagination, and include relations
+   * @returns Promise resolving to paginated array of user's transactions
    * @throws Error if SDK is not initialized
    * 
    * @example
    * ```typescript
    * const { getUserTransactionHistory } = useTransactions();
-   * const sentTransactions = await getUserTransactionHistory(TransactionRole.SENDER);
-   * const allTransactions = await getUserTransactionHistory(); // No filter
+   * 
+   * // Simple: Get all transactions
+   * const allTransactions = await getUserTransactionHistory();
+   * 
+   * // Filter by role (legacy support)
+   * const sentTransactions = await getUserTransactionHistory({ role: 'SENDER' });
+   * 
+   * // Advanced filtering with include relations
+   * const filtered = await getUserTransactionHistory({
+   *   role: 'SENDER',
+   *   status: 'COMPLETED',
+   *   engagedBusinessId: 'business-123',
+   *   include: ['recipient', 'business'],
+   *   page: 1,
+   *   limit: 20
+   * });
+   * 
+   * // Access enriched data
+   * filtered.data.forEach(tx => {
+   *   console.log('Recipient:', tx.included?.recipient);
+   *   console.log('Business:', tx.included?.engagedBusiness?.displayName);
+   * });
    * ```
    */
-  const getUserTransactionHistory = useCallback(async (role?: TransactionRole): Promise<PaginatedResponseDTO<TransactionDTO>> => {
+  const getUserTransactionHistory = useCallback(async (
+    options?: TransactionQueryOptions
+  ): Promise<PaginatedResponseDTO<TransactionDTO>> => {
     
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.transactions.getUserTransactionHistory(role);
+      const result = await sdk.transactions.getUserTransactionHistory(options);
       return result;
     } catch (error) {
       console.error('Failed to fetch transaction history:', error);
@@ -180,27 +219,44 @@ export const useTransactions = () => {
     }
   }, [sdk, isInitialized]);
 
-  const getTenantTransactions = useCallback(async (): Promise<PaginatedResponseDTO<TransactionDTO>> => {
-    if (!isInitialized || !sdk) {
-      throw new Error('SDK not initialized. Call initialize() first.');
-    }
-    
-    try {
-      const result = await sdk.transactions.getTenantTransactions();
-      return result;
-    } catch (error) {
-      console.error('Failed to fetch tenant transactions:', error);
-      throw error;
+  /**
+   * Admin: Get paginated transactions with optional include relations
+   * 
+   * @param params - Pagination and filtering parameters
+   * @param include - Optional relations to include for enriched entity data
+   * @returns Promise resolving to paginated transaction results
+   * @throws Error if SDK is not initialized
+   * 
+   * @example
+   * ```typescript
+   * const { getPaginatedTransactions } = useTransactions();
+   * 
+   * // Basic pagination
+   * const result = await getPaginatedTransactions({ page: 1, limit: 50 });
+   * 
+   * // With include relations
+   * const enrichedResult = await getPaginatedTransactions(
+   *   { page: 1, limit: 50, sortBy: 'createdAt', sortOrder: 'DESC' },
+   *   include: ['sender', 'recipient', 'business']
+   * });
+   * 
+   * enrichedResult.data.forEach(tx => {
+   *   console.log('From:', tx.included?.sender);
+   *   console.log('To:', tx.included?.recipient);
+   * });
+   * ```
+   */
+  const getPaginatedTransactions = useCallback(async (
+    options: TransactionPaginationRequestDTO & {
+      include?: TransactionIncludeRelation[];
     }
-  }, [sdk, isInitialized]);
-
-  const getPaginatedTransactions = useCallback(async (params: TransactionPaginationRequestDTO): Promise<any> => {
+  ): Promise<PaginatedResponseDTO<TransactionDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.transactions.getPaginatedTransactions(params);
+      const result = await sdk.transactions.getPaginatedTransactions(options);
       return result;
     } catch (error) {
       console.error('Failed to fetch paginated transactions:', error);
@@ -226,7 +282,6 @@ export const useTransactions = () => {
     createTransaction,
     getTransactionById,
     getUserTransactionHistory,
-    getTenantTransactions,
     getPaginatedTransactions,
     exportTransactionsCSV,
     isAvailable: isInitialized && !!sdk?.transactions,