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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk-react-native",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "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.3",
+    "@explorins/pers-sdk": "^2.1.6",
     "@explorins/pers-signer": "^1.0.33",
     "buffer": "^6.0.3",
     "ethers": "^6.15.0",

package/src/hooks/index.ts

@@ -16,6 +16,7 @@ export { useFiles } from './useFiles';
 export { useAnalytics } from './useAnalytics';
 export { useDonations } from './useDonations';
 export { useEvents } from './useEvents';
+export { useTriggerSources } from './useTriggerSources';
 
 // Re-export auth-related types for convenience
 export type { RawUserData } from './useAuth';
@@ -34,4 +35,19 @@ export type {
   TokenBalanceWithToken, 
   UseTokenBalancesOptions, 
   UseTokenBalancesResult 
-} from './useTokenBalances';
+} from './useTokenBalances';
+
+// Export campaign-related types
+export type { CampaignClaimFilters, CampaignHook } from './useCampaigns';
+
+// Export redemption-related types
+export type { RedemptionRedeemFilters, RedemptionHook } from './useRedemptions';
+
+// Export transaction-related types
+export type { TransactionQueryOptions, TransactionHook } from './useTransactions';
+
+// Export trigger source-related types
+export type { TriggerSourceQueryOptions, TriggerSourceHook } from './useTriggerSources';
+
+// Export analytics-related types
+export type { AnalyticsHook } from './useAnalytics';

package/src/hooks/useAnalytics.ts

@@ -2,35 +2,63 @@ import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
 import { 
   TransactionAnalyticsRequestDTO, 
-  TransactionAnalyticsResponseDTO 
+  TransactionAnalyticsResponseDTO,
+  CampaignClaimAnalyticsRequestDTO,
+  CampaignClaimAnalyticsResponseDTO,
+  UserAnalyticsRequestDTO,
+  UserAnalyticsResponseDTO,
+  UserRankingAnalyticsRequestDTO,
+  UserRankingAnalyticsResponseDTO,
+  BusinessRankingAnalyticsRequestDTO,
+  BusinessRankingAnalyticsResponseDTO,
+  RetentionAnalyticsRequestDTO,
+  RetentionAnalyticsResponseDTO
 } from '@explorins/pers-shared';
 
 /**
  * React hook for analytics operations in the PERS SDK
  * 
- * Provides methods for retrieving transaction analytics and insights.
- * Supports various analytics queries for business intelligence and reporting.
+ * Provides comprehensive analytics and business intelligence capabilities:
+ * - **Transaction Analytics**: Volume, trends, business performance
+ * - **Campaign Claim Analytics**: Campaign performance and claim patterns
+ * - **User Analytics**: Engagement metrics with per-active-user averages
+ * - **User Ranking**: Leaderboards with full user details
+ * - **Business Ranking**: Business performance rankings
+ * - **Retention Analytics**: Monthly retention metrics
  * 
  * @returns Analytics hook with methods for data analysis
  * 
- * @example
+ * @example Basic Transaction Analytics
  * ```typescript
  * function AnalyticsComponent() {
  *   const { getTransactionAnalytics } = useAnalytics();
  *   
  *   const loadAnalytics = async () => {
- *     try {
- *       const analytics = await getTransactionAnalytics({
- *         timeRange: 'last_30_days',
- *         groupBy: 'day'
- *       });
- *       console.log('Transaction analytics:', analytics);
- *     } catch (error) {
- *       console.error('Failed to load analytics:', error);
- *     }
+ *     const analytics = await getTransactionAnalytics({
+ *       startDate: '2024-01-01',
+ *       endDate: '2024-01-31',
+ *       groupBy: 'day'
+ *     });
+ *     console.log('Transaction analytics:', analytics);
  *   };
+ * }
+ * ```
  * 
- *   return <button onClick={loadAnalytics}>Load Analytics</button>;
+ * @example User Leaderboard
+ * ```typescript
+ * function LeaderboardScreen() {
+ *   const { getUserRanking } = useAnalytics();
+ *   
+ *   const loadLeaderboard = async () => {
+ *     const ranking = await getUserRanking({
+ *       sortBy: 'totalTransactions',
+ *       sortOrder: 'DESC',
+ *       limit: 50
+ *     });
+ *     ranking.results.forEach((user, i) => {
+ *       console.log(`#${i + 1}: ${user.email} - ${user.totalTransactions} txns`);
+ *     });
+ *   };
  * }
  * ```
  */
@@ -46,19 +74,17 @@ export const useAnalytics = () => {
    * 
    * @example
    * ```typescript
-   * const { getTransactionAnalytics } = useAnalytics();
    * const analytics = await getTransactionAnalytics({
-   *   groupBy: ['day'],
-   *   metrics: ['count', 'sum'],
    *   startDate: '2024-01-01',
    *   endDate: '2024-01-31',
-   *   filters: { status: 'completed' }
+   *   groupBy: 'day',
+   *   metrics: ['count', 'sum']
    * });
-   * console.log('Daily transaction analytics:', analytics.results);
-   * console.log('Execution time:', analytics.metadata.executionTime);
    * ```
    */
-  const getTransactionAnalytics = useCallback(async (request: TransactionAnalyticsRequestDTO): Promise<TransactionAnalyticsResponseDTO> => {
+  const getTransactionAnalytics = useCallback(async (
+    request: TransactionAnalyticsRequestDTO
+  ): Promise<TransactionAnalyticsResponseDTO> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
@@ -72,8 +98,229 @@ export const useAnalytics = () => {
     }
   }, [sdk, isInitialized]);
 
+  /**
+   * Retrieves campaign claim analytics with aggregation
+   * 
+   * Provides insights into campaign performance, claim patterns, and user engagement.
+   * 
+   * @param request - Analytics request with filters, groupBy, and metrics
+   * @returns Promise resolving to campaign claim analytics data
+   * 
+   * @example Claims per campaign
+   * ```typescript
+   * const analytics = await getCampaignClaimAnalytics({
+   *   filters: { status: 'COMPLETED' },
+   *   groupBy: ['campaignId'],
+   *   metrics: ['count'],
+   *   sortBy: 'count',
+   *   sortOrder: 'DESC',
+   *   limit: 10
+   * });
+   * console.log('Top campaigns:', analytics.results);
+   * ```
+   */
+  const getCampaignClaimAnalytics = useCallback(async (
+    request: CampaignClaimAnalyticsRequestDTO
+  ): Promise<CampaignClaimAnalyticsResponseDTO> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.analytics.getCampaignClaimAnalytics(request);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch campaign claim analytics:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
+  /**
+   * Retrieves user analytics with engagement metrics
+   * 
+   * Includes both per-user and per-active-user metrics for accurate engagement insights.
+   * Per-active-user metrics show concentrated engagement among active users.
+   * 
+   * @param request - Analytics request with optional filters and date range
+   * @returns Promise resolving to user analytics data
+   * 
+   * @example Compare per-user vs per-active-user metrics
+   * ```typescript
+   * const analytics = await getUserAnalytics({
+   *   startDate: new Date('2026-02-01'),
+   *   endDate: new Date('2026-02-28')
+   * });
+   * 
+   * console.log(`Active users: ${analytics.activeUsers} / ${analytics.totalUsers}`);
+   * console.log(`Engagement rate: ${analytics.engagementRate.toFixed(1)}%`);
+   * 
+   * // Per-active-user metrics (more meaningful)
+   * console.log(`Avg transactions per active user: ${analytics.averageTransactionsPerActiveUser}`);
+   * ```
+   * 
+   * @example Business-specific analytics
+   * ```typescript
+   * const analytics = await getUserAnalytics({
+   *   filters: { businessId: 'business-123' },
+   *   startDate: new Date('2026-01-01'),
+   *   endDate: new Date('2026-12-31')
+   * });
+   * ```
+   */
+  const getUserAnalytics = useCallback(async (
+    request: UserAnalyticsRequestDTO = {}
+  ): Promise<UserAnalyticsResponseDTO> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.analytics.getUserAnalytics(request);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch user analytics:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
+  /**
+   * Retrieves user transaction ranking with enriched user data
+   * 
+   * Returns ranked list of users with full user details (email, externalUserId)
+   * and transaction metrics. Ideal for leaderboards, engagement analysis,
+   * and identifying power users.
+   * 
+   * @param request - Ranking request with filters, sorting, and limit
+   * @returns Promise resolving to ranked user list with transaction metrics
+   * 
+   * @example Top 50 users by transaction count
+   * ```typescript
+   * const ranking = await getUserRanking({
+   *   sortBy: 'totalTransactions',
+   *   sortOrder: 'DESC',
+   *   limit: 50
+   * });
+   * 
+   * ranking.results.forEach((user, index) => {
+   *   console.log(`#${index + 1}: ${user.email || user.externalUserId}`);
+   *   console.log(`  Transactions: ${user.totalTransactions}`);
+   *   console.log(`  Token spent: ${user.tokenSpent}`);
+   * });
+   * ```
+   * 
+   * @example Top STAMP spenders
+   * ```typescript
+   * const ranking = await getUserRanking({
+   *   filters: { tokenType: 'STAMP' },
+   *   sortBy: 'tokenSpent',
+   *   sortOrder: 'DESC',
+   *   limit: 20
+   * });
+   * ```
+   */
+  const getUserRanking = useCallback(async (
+    request: UserRankingAnalyticsRequestDTO = {}
+  ): Promise<UserRankingAnalyticsResponseDTO> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.analytics.getUserRanking(request);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch user ranking:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
+  /**
+   * Retrieves business transaction ranking with enriched business data
+   * 
+   * Returns ranked list of businesses with transaction metrics for
+   * partner analytics and performance dashboards.
+   * 
+   * @param request - Ranking request with filters, sorting, and limit
+   * @returns Promise resolving to ranked business list
+   * 
+   * @example Top businesses by transaction count
+   * ```typescript
+   * const ranking = await getBusinessRanking({
+   *   sortBy: 'totalTransactions',
+   *   sortOrder: 'DESC',
+   *   limit: 20
+   * });
+   * 
+   * ranking.results.forEach((business, index) => {
+   *   console.log(`#${index + 1}: ${business.businessId}`);
+   *   console.log(`  Transactions: ${business.totalTransactions}`);
+   *   console.log(`  Token spent: ${business.tokenSpent}`);
+   * });
+   * ```
+   */
+  const getBusinessRanking = useCallback(async (
+    request: BusinessRankingAnalyticsRequestDTO = {}
+  ): Promise<BusinessRankingAnalyticsResponseDTO> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.analytics.getBusinessRanking(request);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch business ranking:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
+  /**
+   * Retrieves monthly user retention analytics
+   * 
+   * Returns monthly retention data with active, new, and returning users
+   * along with retention rates. Useful for churn analysis and engagement trends.
+   * 
+   * @param request - Retention request with monthsBack and filters
+   * @returns Promise resolving to monthly retention data
+   * 
+   * @example Get 12 months of retention data
+   * ```typescript
+   * const retention = await getRetentionAnalytics({
+   *   monthsBack: 12
+   * });
+   * 
+   * retention.results.forEach(month => {
+   *   console.log(`${month.month}:`);
+   *   console.log(`  Active: ${month.activeUsers}`);
+   *   console.log(`  New: ${month.newUsers}`);
+   *   console.log(`  Returning: ${month.returningUsers}`);
+   *   console.log(`  Retention Rate: ${month.retentionRate.toFixed(1)}%`);
+   * });
+   * ```
+   */
+  const getRetentionAnalytics = useCallback(async (
+    request: RetentionAnalyticsRequestDTO = {}
+  ): Promise<RetentionAnalyticsResponseDTO> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.analytics.getRetentionAnalytics(request);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch retention analytics:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
   return {
     getTransactionAnalytics,
+    getCampaignClaimAnalytics,
+    getUserAnalytics,
+    getUserRanking,
+    getBusinessRanking,
+    getRetentionAnalytics,
     isAvailable: isInitialized && !!sdk?.analytics,
   };
 };

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,
   };
 };