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

package/dist/providers/PersSDKProvider.d.ts

@@ -2,6 +2,15 @@ import React, { ReactNode } from 'react';
 import { PersSDK, PersConfig, DefaultAuthProvider } from '@explorins/pers-sdk/core';
 import { UserDTO, AdminDTO } from '@explorins/pers-shared';
 export type { PersConfig } from '@explorins/pers-sdk/core';
+/**
+ * Context interface for PERS SDK React Native integration
+ *
+ * @property sdk - Main SDK instance (null until initialized)
+ * @property authProvider - Platform-specific auth provider
+ * @property isInitialized - Whether SDK has been initialized
+ * @property isAuthenticated - Whether user is currently authenticated
+ * @property user - Current user data (null if not authenticated)
+ */
 export interface PersSDKContext {
     sdk: PersSDK | null;
     authProvider: DefaultAuthProvider | null;
@@ -13,6 +22,35 @@ export interface PersSDKContext {
     refreshUserData: () => Promise<void>;
     restoreSession: () => Promise<UserDTO | null>;
 }
+/**
+ * PERS SDK Provider for React Native
+ *
+ * Wraps your app to provide SDK context to all child components.
+ * Handles platform-specific initialization (DPoP, storage, etc.).
+ *
+ * @param config - SDK configuration (see PersConfig)
+ * @param config.apiProjectKey - Your PERS project key (required)
+ * @param config.environment - 'staging' | 'production' (default: 'staging')
+ * @param config.captureWalletEvents - Enable real-time blockchain events (default: true)
+ * @param config.dpop - DPoP configuration for enhanced security
+ *
+ * @example Basic usage
+ * ```tsx
+ * <PersSDKProvider config={{ apiProjectKey: 'my-project' }}>
+ *   <App />
+ * </PersSDKProvider>
+ * ```
+ *
+ * @example Disable wallet events
+ * ```tsx
+ * <PersSDKProvider config={{
+ *   apiProjectKey: 'my-project',
+ *   captureWalletEvents: false  // Disable auto-connect to blockchain events
+ * }}>
+ *   <App />
+ * </PersSDKProvider>
+ * ```
+ */
 export declare const PersSDKProvider: React.FC<{
     children: ReactNode;
     config?: PersConfig;

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;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"}
+{"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;;;;;;;;GAQG;AACH,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;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,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

@@ -7,7 +7,35 @@ import { createReactNativeAuthProvider } from './react-native-auth-provider';
 import { ReactNativeDPoPProvider } from './rn-dpop-provider';
 // Create the context
 const SDKContext = createContext(null);
-// Provider component
+/**
+ * PERS SDK Provider for React Native
+ *
+ * Wraps your app to provide SDK context to all child components.
+ * Handles platform-specific initialization (DPoP, storage, etc.).
+ *
+ * @param config - SDK configuration (see PersConfig)
+ * @param config.apiProjectKey - Your PERS project key (required)
+ * @param config.environment - 'staging' | 'production' (default: 'staging')
+ * @param config.captureWalletEvents - Enable real-time blockchain events (default: true)
+ * @param config.dpop - DPoP configuration for enhanced security
+ *
+ * @example Basic usage
+ * ```tsx
+ * <PersSDKProvider config={{ apiProjectKey: 'my-project' }}>
+ *   <App />
+ * </PersSDKProvider>
+ * ```
+ *
+ * @example Disable wallet events
+ * ```tsx
+ * <PersSDKProvider config={{
+ *   apiProjectKey: 'my-project',
+ *   captureWalletEvents: false  // Disable auto-connect to blockchain events
+ * }}>
+ *   <App />
+ * </PersSDKProvider>
+ * ```
+ */
 export const PersSDKProvider = ({ children, config }) => {
     const initializingRef = useRef(false);
     // State refs for stable functions to read current values

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk-react-native",
-  "version": "2.1.3",
+  "version": "2.1.6",
   "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.14",
     "@explorins/pers-signer": "^1.0.33",
     "buffer": "^6.0.3",
     "ethers": "^6.15.0",
@@ -155,6 +155,7 @@
     "@ethersproject/scrypt": false
   },
   "devDependencies": {
+    "@explorins/pers-shared": "^2.1.117",
     "@rollup/plugin-commonjs": "^25.0.7",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^15.2.3",

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