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

package/dist/providers/PersSDKProvider.d.ts

@@ -1,21 +1,9 @@
 import React, { ReactNode } from 'react';
 import { PersSDK, PersConfig, DefaultAuthProvider } from '@explorins/pers-sdk/core';
 import { UserDTO, AdminDTO } from '@explorins/pers-shared';
-import type { AuthManager, UserManager, TokenManager, BusinessManager, CampaignManager, RedemptionManager, TransactionManager, PurchaseManager, TenantManager, AnalyticsManager, DonationManager } from '@explorins/pers-sdk/core';
 export type { PersConfig } from '@explorins/pers-sdk/core';
 export interface PersSDKContext {
     sdk: PersSDK | null;
-    auth: AuthManager | null;
-    users: UserManager | null;
-    tokens: TokenManager | null;
-    businesses: BusinessManager | null;
-    campaigns: CampaignManager | null;
-    redemptions: RedemptionManager | null;
-    transactions: TransactionManager | null;
-    purchases: PurchaseManager | null;
-    tenants: TenantManager | null;
-    analytics: AnalyticsManager | null;
-    donations: DonationManager | null;
     authProvider: DefaultAuthProvider | null;
     isInitialized: boolean;
     isAuthenticated: boolean;
@@ -23,6 +11,7 @@ export interface PersSDKContext {
     initialize: (config: PersConfig) => Promise<void>;
     setAuthenticationState: (user: UserDTO | AdminDTO | null, isAuthenticated: boolean) => void;
     refreshUserData: () => Promise<void>;
+    restoreSession: () => Promise<UserDTO | null>;
 }
 export declare const PersSDKProvider: React.FC<{
     children: ReactNode;

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

@@ -1 +1 @@
-{"version":3,"file":"PersSDKProvider.d.ts","sourceRoot":"","sources":["../../src/providers/PersSDKProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAuC,SAAS,EAA2C,MAAM,OAAO,CAAC;AAEvH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAIpF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAG3D,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,MAAM,WAAW,cAAc;IAE7B,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAGpB,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,eAAe,GAAG,IAAI,CAAC;IACnC,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAClC,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACtC,YAAY,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAClC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACnC,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAGlC,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAGzC,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC;IAGhC,UAAU,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,sBAAsB,EAAE,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,EAAE,eAAe,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5F,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAMD,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC;IACrC,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB,CAyMA,CAAC;AAGF,eAAO,MAAM,UAAU,QAAO,cAQ7B,CAAC"}
+{"version":3,"file":"PersSDKProvider.d.ts","sourceRoot":"","sources":["../../src/providers/PersSDKProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAuC,SAAS,EAA2C,MAAM,OAAO,CAAC;AAEvH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAIpF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAkB3D,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,MAAM,WAAW,cAAc;IAE7B,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAGpB,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAGzC,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC;IAGhC,UAAU,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,sBAAsB,EAAE,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,EAAE,eAAe,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5F,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,cAAc,EAAE,MAAM,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CAC/C;AAMD,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC;IACrC,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB,CAwOA,CAAC;AAGF,eAAO,MAAM,UAAU,QAAO,cAQ7B,CAAC"}

package/dist/providers/PersSDKProvider.js

@@ -10,11 +10,19 @@ const SDKContext = createContext(null);
 // Provider component
 export const PersSDKProvider = ({ children, config }) => {
     const initializingRef = useRef(false);
+    // State refs for stable functions to read current values
+    const sdkRef = useRef(null);
+    const isInitializedRef = useRef(false);
+    const isAuthenticatedRef = useRef(false);
     const [sdk, setSdk] = useState(null);
     const [authProvider, setAuthProvider] = useState(null);
     const [isInitialized, setIsInitialized] = useState(false);
     const [isAuthenticated, setIsAuthenticated] = useState(false);
     const [user, setUser] = useState(null);
+    // Keep state refs in sync immediately (not in useEffect to avoid race conditions)
+    sdkRef.current = sdk;
+    isInitializedRef.current = isInitialized;
+    isAuthenticatedRef.current = isAuthenticated;
     const initialize = useCallback(async (config) => {
         // Prevent multiple initializations
         if (isInitialized || initializingRef.current) {
@@ -81,18 +89,40 @@ export const PersSDKProvider = ({ children, config }) => {
         }
     }, [config, isInitialized, initialize]);
     const refreshUserData = useCallback(async () => {
-        if (!sdk || !isAuthenticated || !isInitialized) {
-            throw new Error('SDK not initialized or not authenticated. Cannot refresh user data.');
+        // Read from refs to get current values
+        const currentSdk = sdkRef.current;
+        const currentIsInitialized = isInitializedRef.current;
+        if (!currentSdk || !currentIsInitialized) {
+            throw new Error('SDK not initialized. Cannot refresh user data.');
         }
         try {
-            const freshUserData = await sdk.users.getCurrentUser();
+            const freshUserData = await currentSdk.users.getCurrentUser();
             setUser(freshUserData);
         }
         catch (error) {
             console.error('Failed to refresh user data:', error);
             throw error;
         }
-    }, [sdk, isAuthenticated, isInitialized]);
+    }, []); // No dependencies - reads from refs
+    const restoreSession = useCallback(async () => {
+        // Read from refs to get current values
+        const currentSdk = sdkRef.current;
+        const currentIsInitialized = isInitializedRef.current;
+        if (!currentSdk || !currentIsInitialized) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        try {
+            const userData = await currentSdk.restoreSession();
+            if (userData) {
+                setAuthenticationState(userData, true);
+            }
+            return userData;
+        }
+        catch (error) {
+            console.error('[PersSDK] Failed to restore session:', error);
+            throw error;
+        }
+    }, [setAuthenticationState]); // Depends on setAuthenticationState
     // Listen for authentication events from core SDK
     // Set up immediately when SDK is created (don't wait for isInitialized)
     // to catch session_restored events that fire during SDK initialization
@@ -105,13 +135,18 @@ export const PersSDKProvider = ({ children, config }) => {
             // Session restored successfully - sync React state
             if (event.type === 'session_restored') {
                 console.log('[PersSDK] Session restoration event received, syncing state...');
-                sdk.users.getCurrentUser()
-                    .then(userData => {
-                    setAuthenticationState(userData, true);
-                })
-                    .catch(error => {
-                    console.error('[PersSDK] Failed to sync restored session:', error);
-                });
+                // Read user from event details if available, otherwise fetch
+                const userId = event.details?.userId;
+                if (userId) {
+                    // User ID available, fetch user data
+                    sdk.users.getCurrentUser()
+                        .then(userData => {
+                        setAuthenticationState(userData, true);
+                    })
+                        .catch(error => {
+                        console.error('[PersSDK] Failed to sync restored session:', error);
+                    });
+                }
             }
             // Session restoration failed or auth error - clear React state
             if (event.type === 'session_restoration_failed' || event.code === 'AUTH_FAILED') {
@@ -149,28 +184,17 @@ export const PersSDKProvider = ({ children, config }) => {
     const contextValue = useMemo(() => ({
         // Main SDK instance
         sdk,
-        // Manager shortcuts for convenience
-        auth: sdk?.auth || null,
-        users: sdk?.users || null,
-        tokens: sdk?.tokens || null,
-        businesses: sdk?.businesses || null,
-        campaigns: sdk?.campaigns || null,
-        redemptions: sdk?.redemptions || null,
-        transactions: sdk?.transactions || null,
-        purchases: sdk?.purchases || null,
-        tenants: sdk?.tenants || null,
-        analytics: sdk?.analytics || null,
-        donations: sdk?.donations || null,
         // Platform-specific providers
         authProvider,
         // State
         isInitialized,
         isAuthenticated,
         user,
-        // Methods
+        // Methods - expose functions directly, not through refs
         initialize,
         setAuthenticationState,
         refreshUserData,
+        restoreSession,
     }), [
         sdk,
         authProvider,
@@ -179,7 +203,8 @@ export const PersSDKProvider = ({ children, config }) => {
         user,
         initialize,
         setAuthenticationState,
-        refreshUserData
+        refreshUserData,
+        restoreSession
     ]);
     return (_jsx(SDKContext.Provider, { value: contextValue, children: children }));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk-react-native",
-  "version": "2.1.2",
+  "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.2",
+    "@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,
   };
 };