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

package/README.md

@@ -224,11 +224,10 @@ const {
 const { 
   createTransaction,
   getTransactionById,
-  getUserTransactionHistory,
-  getTenantTransactions,      // Admin
-  getPaginatedTransactions,   // Admin
-  exportTransactionsCSV,      // Admin
-  signingStatus,              // UI feedback during blockchain signing
+  getUserTransactionHistory,    // With TransactionQueryOptions (includes pagination + filters + include)
+  getPaginatedTransactions,     // Admin - single options object with include
+  exportTransactionsCSV,        // Admin
+  signingStatus,                // UI feedback during blockchain signing
   signingStatusMessage
 } = useTransactions();
 
@@ -261,12 +260,13 @@ const {
 // Campaign management
 const { 
   getActiveCampaigns,
+  getCampaigns,                 // With options: { active?, businessId?, sortBy?, include?, page?, limit? }
   getCampaignById,
   claimCampaign,
-  getUserClaims,
+  getUserClaims,                // With options: { page?, limit?, include? }
   getCampaignTriggers,
   getAllCampaigns,              // Admin
-  getCampaignClaims,            // Admin
+  getCampaignClaims,            // Admin - with options object
   getCampaignClaimsByUserId,    // Admin
   getCampaignClaimsByBusinessId // Admin
 } = useCampaigns();

package/dist/hooks/index.d.ts

@@ -15,9 +15,15 @@ export { useFiles } from './useFiles';
 export { useAnalytics } from './useAnalytics';
 export { useDonations } from './useDonations';
 export { useEvents } from './useEvents';
+export { useTriggerSources } from './useTriggerSources';
 export type { RawUserData } from './useAuth';
 export type { TransactionSignerHook, SubmissionResult, AuthenticatedUser, TransactionSigningResult, StatusUpdateData, OnStatusUpdateFn, SigningStatus as SigningStatusType } from './useTransactionSigner';
 export type { AccountOwnedTokensResult, Web3Hook } from './useWeb3';
 export type { EventsHook, PersEvent, EventHandler, EventFilter, Unsubscribe } from './useEvents';
 export type { TokenBalanceWithToken, UseTokenBalancesOptions, UseTokenBalancesResult } from './useTokenBalances';
+export type { CampaignClaimFilters, CampaignHook } from './useCampaigns';
+export type { RedemptionRedeemFilters, RedemptionHook } from './useRedemptions';
+export type { TransactionQueryOptions, TransactionHook } from './useTransactions';
+export type { TriggerSourceQueryOptions, TriggerSourceHook } from './useTriggerSources';
+export type { AnalyticsHook } from './useAnalytics';
 //# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,IAAI,iBAAiB,EACnC,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACjG,YAAY,EACV,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,IAAI,iBAAiB,EACnC,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACjG,YAAY,EACV,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGzE,YAAY,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGhF,YAAY,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGlF,YAAY,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxF,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/hooks/index.js

@@ -16,3 +16,4 @@ export { useFiles } from './useFiles';
 export { useAnalytics } from './useAnalytics';
 export { useDonations } from './useDonations';
 export { useEvents } from './useEvents';
+export { useTriggerSources } from './useTriggerSources';

package/dist/hooks/useAnalytics.d.ts

@@ -1,35 +1,58 @@
-import { TransactionAnalyticsRequestDTO, TransactionAnalyticsResponseDTO } from '@explorins/pers-shared';
+import { TransactionAnalyticsRequestDTO, 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`);
+ *     });
+ *   };
  * }
  * ```
  */
 export declare const useAnalytics: () => {
     getTransactionAnalytics: (request: TransactionAnalyticsRequestDTO) => Promise<TransactionAnalyticsResponseDTO>;
+    getCampaignClaimAnalytics: (request: CampaignClaimAnalyticsRequestDTO) => Promise<CampaignClaimAnalyticsResponseDTO>;
+    getUserAnalytics: (request?: UserAnalyticsRequestDTO) => Promise<UserAnalyticsResponseDTO>;
+    getUserRanking: (request?: UserRankingAnalyticsRequestDTO) => Promise<UserRankingAnalyticsResponseDTO>;
+    getBusinessRanking: (request?: BusinessRankingAnalyticsRequestDTO) => Promise<BusinessRankingAnalyticsResponseDTO>;
+    getRetentionAnalytics: (request?: RetentionAnalyticsRequestDTO) => Promise<RetentionAnalyticsResponseDTO>;
     isAvailable: boolean;
 };
 export type AnalyticsHook = ReturnType<typeof useAnalytics>;

package/dist/hooks/useAnalytics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAnalytics.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnalytics.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,8BAA8B,EAC9B,+BAA+B,EAChC,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,YAAY;uCAwBqC,8BAA8B,KAAG,QAAQ,+BAA+B,CAAC;;CAkBtI,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC"}
+{"version":3,"file":"useAnalytics.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnalytics.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,8BAA8B,EAC9B,+BAA+B,EAC/B,gCAAgC,EAChC,iCAAiC,EACjC,uBAAuB,EACvB,wBAAwB,EACxB,8BAA8B,EAC9B,+BAA+B,EAC/B,kCAAkC,EAClC,mCAAmC,EACnC,4BAA4B,EAC5B,6BAA6B,EAC9B,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,YAAY;uCAqBZ,8BAA8B,KACtC,QAAQ,+BAA+B,CAAC;yCAoChC,gCAAgC,KACxC,QAAQ,iCAAiC,CAAC;iCA+ClC,uBAAuB,KAC/B,QAAQ,wBAAwB,CAAC;+BAkDzB,8BAA8B,KACtC,QAAQ,+BAA+B,CAAC;mCAuChC,kCAAkC,KAC1C,QAAQ,mCAAmC,CAAC;sCAuCpC,4BAA4B,KACpC,QAAQ,6BAA6B,CAAC;;CAuB1C,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC"}

package/dist/hooks/useAnalytics.js

@@ -3,29 +3,47 @@ import { usePersSDK } from '../providers/PersSDKProvider';
 /**
  * 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);
  *   };
+ * }
+ * ```
+ *
+ * @example User Leaderboard
+ * ```typescript
+ * function LeaderboardScreen() {
+ *   const { getUserRanking } = useAnalytics();
  *
- *   return <button onClick={loadAnalytics}>Load Analytics</button>;
+ *   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`);
+ *     });
+ *   };
  * }
  * ```
  */
@@ -40,16 +58,12 @@ 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) => {
@@ -65,8 +79,214 @@ export const useAnalytics = () => {
             throw error;
         }
     }, [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) => {
+        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 = {}) => {
+        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 = {}) => {
+        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 = {}) => {
+        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 = {}) => {
+        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/dist/hooks/useCampaigns.d.ts

@@ -1,14 +1,22 @@
-import type { CampaignClaimRequestDTO, CampaignDTO, CampaignClaimDTO, CampaignTriggerDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
+import type { CampaignClaimRequestDTO, CampaignDTO, CampaignClaimDTO, CampaignTriggerDTO, PaginatedResponseDTO, CampaignClaimIncludeRelation, CampaignIncludeRelation } from '@explorins/pers-shared';
+import type { CampaignClaimFilters } from '@explorins/pers-sdk/campaign';
+export type { CampaignClaimFilters } from '@explorins/pers-sdk/campaign';
 export declare const useCampaigns: () => {
     getActiveCampaigns: () => Promise<PaginatedResponseDTO<CampaignDTO>>;
-    getCampaignById: (campaignId: string) => Promise<CampaignDTO | null>;
+    getCampaignById: (campaignId: string, include?: CampaignIncludeRelation[]) => Promise<CampaignDTO | null>;
     claimCampaign: (request: CampaignClaimRequestDTO) => Promise<CampaignClaimDTO | null>;
-    getUserClaims: () => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
+    getUserClaims: (options?: {
+        page?: number;
+        limit?: number;
+        include?: CampaignClaimIncludeRelation[];
+    }) => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
     getCampaignTriggers: () => Promise<PaginatedResponseDTO<CampaignTriggerDTO>>;
     getAllCampaigns: (active?: boolean) => Promise<PaginatedResponseDTO<CampaignDTO>>;
-    getCampaignClaims: () => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
-    getCampaignClaimsByUserId: (userId: string) => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
-    getCampaignClaimsByBusinessId: (businessId: string) => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
+    getCampaignClaims: (filters?: CampaignClaimFilters, include?: CampaignClaimIncludeRelation[]) => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
+    getCampaignClaimsByUserId: (userId: string, include?: CampaignClaimIncludeRelation[]) => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
+    getCampaignClaimsByBusinessId: (businessId: string, include?: CampaignClaimIncludeRelation[]) => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
+    assignTriggerSource: (campaignId: string, triggerSourceId: string) => Promise<CampaignDTO>;
+    removeTriggerSource: (campaignId: string, triggerSourceId: string) => Promise<CampaignDTO>;
     isAvailable: boolean;
 };
 export type CampaignHook = ReturnType<typeof useCampaigns>;

package/dist/hooks/useCampaigns.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCampaigns.d.ts","sourceRoot":"","sources":["../../src/hooks/useCampaigns.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,uBAAuB,EACvB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAIlB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC;AAEhC,eAAO,MAAM,YAAY;8BAG0B,QAAQ,qBAAqB,WAAW,CAAC,CAAC;kCAcpC,MAAM,KAAG,QAAQ,WAAW,GAAG,IAAI,CAAC;6BAczC,uBAAuB,KAAG,QAAQ,gBAAgB,GAAG,IAAI,CAAC;yBAiBhE,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;+BAkBzC,QAAQ,qBAAqB,kBAAkB,CAAC,CAAC;+BAe/C,OAAO,KAAG,QAAQ,qBAAqB,WAAW,CAAC,CAAC;6BAcxD,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;wCAclC,MAAM,KAAG,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;gDAchD,MAAM,KAAG,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;;CA0B9H,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC"}
+{"version":3,"file":"useCampaigns.d.ts","sourceRoot":"","sources":["../../src/hooks/useCampaigns.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,uBAAuB,EACvB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,4BAA4B,EAC5B,uBAAuB,EACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAGzE,YAAY,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEzE,eAAO,MAAM,YAAY;8BAG0B,QAAQ,qBAAqB,WAAW,CAAC,CAAC;kCA6B7E,MAAM,YACR,uBAAuB,EAAE,KAClC,QAAQ,WAAW,GAAG,IAAI,CAAC;6BAcoB,uBAAuB,KAAG,QAAQ,gBAAgB,GAAG,IAAI,CAAC;8BAmCzD;QACjD,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,4BAA4B,EAAE,CAAC;KAC1C,KAAG,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;+BAkBD,QAAQ,qBAAqB,kBAAkB,CAAC,CAAC;+BAe/C,OAAO,KAAG,QAAQ,qBAAqB,WAAW,CAAC,CAAC;kCA+B5F,oBAAoB,YACpB,4BAA4B,EAAE,KACvC,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;wCAsBxC,MAAM,YACJ,4BAA4B,EAAE,KACvC,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;gDAsBpC,MAAM,YACR,4BAA4B,EAAE,KACvC,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;sCA4CpC,MAAM,mBACD,MAAM,KACtB,QAAQ,WAAW,CAAC;sCA4BT,MAAM,mBACD,MAAM,KACtB,QAAQ,WAAW,CAAC;;CA+BxB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC"}