@explorins/pers-sdk-react-native 2.1.14-beta.0 → 2.1.18

package/src/hooks/useCampaigns.ts

@@ -9,23 +9,30 @@ import type {
   CampaignClaimIncludeRelation,
   CampaignIncludeRelation,
   SortOrder,
+  CampaignFilterOptions,
   // DynamicContext
-} from '@explorins/pers-shared';
+} from '@explorins/pers-sdk';
 import type { CampaignClaimFilters } from '@explorins/pers-sdk/campaign';
 
 // Re-export for consumers
 export type { CampaignClaimFilters } from '@explorins/pers-sdk/campaign';
+export type { CampaignFilterOptions } from '@explorins/pers-sdk';
 
 /**
  * Options for fetching campaigns
+ * @deprecated Use CampaignFilterOptions from '@explorins/pers-sdk/campaign' instead
  */
 export interface GetCampaignsOptions {
-  /** Filter by tag */
-  tag?: string;
+  /** Filter by tag(s) - single tag or array for OR match */
+  tags?: string | string[];
   /** Free text search across name and description (case-insensitive) */
   search?: string;
   /** Filter by business ID */
   businessId?: string;
+  /** Filter campaigns starting on or after this date */
+  startDate?: Date | string;
+  /** Filter campaigns ending on or before this date */
+  endDate?: Date | string;
   /** Page number (1-indexed) */
   page?: number;
   /** Items per page */
@@ -34,7 +41,7 @@ export interface GetCampaignsOptions {
   sortBy?: 'name' | 'createdAt' | 'startDate';
   /** Sort order */
   sortOrder?: SortOrder;
-  /** Relations to include: 'triggerSources', 'businesses' */
+  /** Relations to include: 'triggerSources', 'businesses', 'claimCount' */
   include?: CampaignIncludeRelation[];
 }
 
@@ -59,11 +66,15 @@ export const useCampaigns = () => {
    *   include: ['triggerSources', 'businesses'] 
    * });
    * 
-   * // Filter by tag
-   * const { data } = await getActiveCampaigns({ tag: 'summer-promo' });
+   * // Filter by date range
+   * const { data } = await getActiveCampaigns({ 
+   *   startDate: '2026-05-01', 
+   *   endDate: '2026-12-31' 
+   * });
    * 
-   * // Filter by business
-   * const { data } = await getActiveCampaigns({ businessId: 'business-123' });
+   * // Get campaigns with claim count
+   * const { data } = await getActiveCampaigns({ include: ['claimCount'] });
+   * data.forEach(c => console.log(`${c.name}: ${c.claimCount} claims`));
    * ```
    */
   const getActiveCampaigns = useCallback(async (
@@ -89,7 +100,7 @@ export const useCampaigns = () => {
    * Get campaign by ID with optional include relations
    * 
    * @param campaignId - The campaign ID
-   * @param include - Relations to include: 'triggerSources', 'businesses'
+   * @param include - Relations to include: 'triggerSources', 'businesses', 'claimCount'
    * @returns Promise resolving to campaign data
    * 
    * @example
@@ -97,6 +108,10 @@ export const useCampaigns = () => {
    * // Get campaign with all related data
    * const campaign = await getCampaignById('campaign-123', ['triggerSources', 'businesses']);
    * console.log('Trigger sources:', campaign.included?.triggerSources);
+   * 
+   * // Get campaign with claim count
+   * const campaign = await getCampaignById('campaign-123', ['claimCount']);
+   * console.log('Total claims:', campaign.claimCount);
    * ```
    */
   const getCampaignById = useCallback(async (
@@ -259,8 +274,13 @@ export const useCampaigns = () => {
    * // Get only active campaigns with trigger sources
    * const { data } = await getAllCampaigns({ active: true, include: ['triggerSources'] });
    * 
-   * // Get inactive campaigns
-   * const { data } = await getAllCampaigns({ active: false });
+   * // Filter by date range with claim count
+   * const { data } = await getAllCampaigns({ 
+   *   startDate: '2026-05-01', 
+   *   endDate: '2026-12-31',
+   *   include: ['claimCount']
+   * });
+   * data.forEach(c => console.log(`${c.name}: ${c.claimCount} claims`));
    * 
    * // With pagination and sorting
    * const { data } = await getAllCampaigns({ 
@@ -290,7 +310,16 @@ export const useCampaigns = () => {
   /**
    * Admin: Get campaign claims with optional filters and include relations
    * 
-   * @param filters - Optional filters for campaign, user, or business
+   * @param filters - Optional filters for campaign, user, business, and date range
+   * @param filters.campaignId - Filter by specific campaign ID
+   * @param filters.userId - Filter by user ID
+   * @param filters.businessId - Filter by business ID
+   * @param filters.dateFrom - Filter claims created on or after this date (ISO 8601 format)
+   * @param filters.dateTo - Filter claims created on or before this date (ISO 8601 format)
+   * @param filters.page - Page number (1-indexed)
+   * @param filters.limit - Items per page
+   * @param filters.sortBy - Field to sort by
+   * @param filters.sortOrder - Sort direction
    * @param include - Relations to include: 'campaign', 'user', 'business'
    * @returns Promise resolving to paginated campaign claims
    * 
@@ -301,6 +330,12 @@ export const useCampaigns = () => {
    * 
    * // Get claims for a specific campaign
    * const { data } = await getCampaignClaims({ campaignId: 'campaign-123' }, ['user', 'business']);
+   * 
+   * // Filter by date range
+   * const { data } = await getCampaignClaims({ 
+   *   dateFrom: '2026-01-01',
+   *   dateTo: '2026-03-31'
+   * }, ['campaign']);
    * ```
    */
   const getCampaignClaims = useCallback(async (

package/src/hooks/useDonations.ts

@@ -1,6 +1,6 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
-import type { DonationTypeDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
+import type { DonationTypeDTO, PaginatedResponseDTO } from '@explorins/pers-sdk';
 
 /**
  * React hook for donation operations in the PERS SDK

package/src/hooks/usePurchases.ts

@@ -1,6 +1,6 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
-import type { PurchaseTokenDTO, PurchaseDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
+import type { PurchaseTokenDTO, PurchaseDTO, PaginatedResponseDTO } from '@explorins/pers-sdk';
 
 export const usePurchases = () => {
   const { sdk, isInitialized, isAuthenticated } = usePersSDK();

package/src/hooks/useRedemptions.ts

@@ -9,10 +9,11 @@ import type {
   RedemptionTypeDTO,
   PaginatedResponseDTO,
   RedemptionRedeemIncludeRelation,
+  RedemptionIncludeRelation,
   ProcessRecordStatus,
   DynamicContext,
   SortOrder
-} from '@explorins/pers-shared';
+} from '@explorins/pers-sdk';
 import type { RedemptionRedeemFilters, RedemptionFilterOptions } from '@explorins/pers-sdk/redemption';
 import type { PaginationOptions } from '@explorins/pers-sdk';
 
@@ -27,12 +28,20 @@ export interface GetRedemptionsOptions {
   active?: boolean;
   /** Free text search across name, description, tags (case-insensitive) */
   search?: string;
+  /** Filter by tag(s) - single tag or array for OR match */
+  tags?: string | string[];
+  /** Filter redemptions starting on or after this date */
+  startDate?: Date | string;
+  /** Filter redemptions ending on or before this date */
+  endDate?: Date | string;
+  /** Relations to include: 'redeemCount' */
+  include?: RedemptionIncludeRelation[];
   /** Page number (1-indexed) */
   page?: number;
   /** Results per page */
   limit?: number;
   /** Field to sort by */
-  sortBy?: 'name' | 'createdAt';
+  sortBy?: 'name' | 'createdAt' | 'startDate';
   /** Sort direction */
   sortOrder?: SortOrder;
 }
@@ -52,6 +61,9 @@ export const useRedemptions = () => {
    * @param options - Filter and pagination options
    * @param options.active - Filter by active status (Admin only)
    * @param options.search - Free text search across name, description, tags
+   * @param options.startDate - Filter redemptions starting on or after this date
+   * @param options.endDate - Filter redemptions ending on or before this date
+   * @param options.include - Relations to include: 'redeemCount'
    * @param options.page - Page number (1-indexed)
    * @param options.limit - Results per page
    * @param options.sortBy - Field to sort by ('name' | 'createdAt')
@@ -62,12 +74,21 @@ export const useRedemptions = () => {
    * const { data: offers } = await getRedemptions();
    * ```
    * 
-   * @example Search redemptions
+   * @example Filter by date range
    * ```typescript
-   * const { data: coffeeOffers } = await getRedemptions({ search: 'coffee' });
+   * const { data: dateFiltered } = await getRedemptions({ 
+   *   startDate: '2026-05-01', 
+   *   endDate: '2026-06-30' 
+   * });
    * ```
    * 
-   * @example With pagination and sorting
+   * @example Get redemptions with redeem count
+   * ```typescript
+   * const { data: offers } = await getRedemptions({ include: ['redeemCount'] });
+   * offers.forEach(o => console.log(`${o.name}: ${o.redeemCount} redeems`));
+   * ```
+   * 
+   * @example Search with pagination
    * ```typescript
    * const { data, pagination } = await getRedemptions({ 
    *   search: 'discount',
@@ -242,7 +263,17 @@ export const useRedemptions = () => {
    * 
    * Retrieves all redemption redeems across the platform with filtering.
    * 
-   * @param filters - Optional filters for user, redemption, and pagination
+   * @param filters - Optional filters for user, redemption, date range, and pagination
+   * @param filters.userId - Filter by user ID
+   * @param filters.redemptionId - Filter by redemption offer ID
+   * @param filters.businessId - Filter by business ID (admin only)
+   * @param filters.status - Filter by processing status (PENDING, PROCESSING, COMPLETED, FAILED)
+   * @param filters.dateFrom - Filter redeems created on or after this date (ISO 8601 format)
+   * @param filters.dateTo - Filter redeems created on or before this date (ISO 8601 format)
+   * @param filters.page - Page number (1-indexed)
+   * @param filters.limit - Items per page
+   * @param filters.sortBy - Field to sort by
+   * @param filters.sortOrder - Sort direction
    * @param include - Relations to include: 'redemption', 'user', 'business'
    * @returns Promise resolving to paginated redemption redeems
    * 
@@ -256,6 +287,12 @@ export const useRedemptions = () => {
    *   { userId: 'user-123' },
    *   ['redemption']
    * );
+   * 
+   * // Filter by date range
+   * const { data } = await getRedemptionRedeems({
+   *   dateFrom: '2026-01-01',
+   *   dateTo: '2026-03-31'
+   * }, ['user', 'redemption']);
    * ```
    */
   const getRedemptionRedeems = useCallback(async (

package/src/hooks/useTenants.ts

@@ -1,6 +1,6 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
-import type { TenantPublicDTO, TenantClientConfigDTO, AdminDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
+import type { TenantPublicDTO, TenantClientConfigDTO, AdminDTO, PaginatedResponseDTO } from '@explorins/pers-sdk';
 
 export const useTenants = () => {
   const { sdk, isInitialized } = usePersSDK();

package/src/hooks/useTokenBalances.ts

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useState, useRef } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
 import { useWeb3 } from './useWeb3';
-import { NativeTokenTypes, type TokenDTO } from '@explorins/pers-shared';
+import { NativeTokenTypes, type TokenDTO } from '@explorins/pers-sdk';
 import type { TokenBalance, TokenBalanceRequest } from '@explorins/pers-sdk/web3';
 
 /**

package/src/hooks/useTokens.ts

@@ -1,6 +1,6 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
-import type { TokenDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
+import type { TokenDTO, PaginatedResponseDTO } from '@explorins/pers-sdk';
 
 /**
  * React hook for token operations in the PERS SDK

package/src/hooks/useTransactions.ts

@@ -8,7 +8,7 @@ import type {
   TransactionPaginationRequestDTO,
   PaginatedResponseDTO,
   TransactionIncludeRelation
-} from '@explorins/pers-shared';
+} from '@explorins/pers-sdk';
 import type { TransactionQueryOptions } from '@explorins/pers-sdk/transaction';
 
 // Re-export for consumers

package/src/hooks/useTriggerSources.ts

@@ -4,7 +4,7 @@ import type {
   TriggerSourceDTO,
   TriggerSourceCreateRequestDTO,
   PaginatedResponseDTO
-} from '@explorins/pers-shared';
+} from '@explorins/pers-sdk';
 import type { TriggerSourceQueryOptions } from '@explorins/pers-sdk/trigger-source';
 
 // Re-export for consumers

package/src/hooks/useUserStatus.ts

@@ -1,6 +1,6 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
-import type { UserStatusTypeDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
+import type { UserStatusTypeDTO, PaginatedResponseDTO } from '@explorins/pers-sdk';
 
 export const useUserStatus = () => {
   const { sdk, isInitialized, isAuthenticated } = usePersSDK();

package/src/hooks/useUsers.ts

@@ -1,6 +1,6 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
-import type { UserDTO, UserCreateRequestDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
+import type { UserDTO, UserCreateRequestDTO, PaginatedResponseDTO } from '@explorins/pers-sdk';
 import type { UserPublicProfileDTO, UserQueryOptions } from '@explorins/pers-sdk/user';
 
 // Re-export for consumers

package/src/index.ts

@@ -284,10 +284,13 @@ export type { EventsHook, PersEvent, EventHandler, EventFilter, Unsubscribe } fr
 export type { TokenBalanceWithToken, UseTokenBalancesOptions, UseTokenBalancesResult } from './hooks';
 
 // Re-export campaign types for convenience
-export type { CampaignClaimFilters, CampaignHook, GetCampaignsOptions } from './hooks';
+export type { CampaignClaimFilters, CampaignFilterOptions, CampaignHook, GetCampaignsOptions } from './hooks';
 
 // Re-export redemption types for convenience
-export type { RedemptionRedeemFilters, RedemptionHook } from './hooks';
+export type { RedemptionRedeemFilters, RedemptionFilterOptions, RedemptionHook, GetRedemptionsOptions } from './hooks';
+
+// Re-export business types for convenience
+export type { BusinessFilterOptions, BusinessHook } from './hooks';
 
 // Re-export transaction types for convenience
 export type { TransactionQueryOptions, TransactionHook } from './hooks';
@@ -357,7 +360,7 @@ export {
  * 
  * @see {@link https://github.com/eXplorins/pers-shared} - Shared library documentation
  */
-export * from '@explorins/pers-shared';
+export * from '@explorins/pers-sdk';
 
 /**
  * Token utilities re-exported from token module

package/src/providers/PersSDKProvider.tsx

@@ -89,6 +89,7 @@ export const PersSDKProvider: React.FC<{
   config?: PersConfig;
 }> = ({ children, config }) => {
   const initializingRef = useRef(false);
+  const eventUnsubscribeRef = useRef<(() => void) | null>(null);
   
   // State refs for stable functions to read current values
   const sdkRef = useRef<PersSDK | null>(null);
@@ -156,6 +157,23 @@ export const PersSDKProvider: React.FC<{
       // Initialize PersSDK with platform-aware auth provider
       const sdkInstance = new PersSDK(httpClient, sdkConfig);
       
+      // Subscribe to auth events BEFORE exposing SDK to consumers
+      // This ensures no events are missed due to React timing
+      eventUnsubscribeRef.current = sdkInstance.events.subscribe((event) => {
+        if (event.type === 'session_restored' || event.type === 'login_success') {
+          const details = event.details as { user?: UserDTO | AdminDTO };
+          if (details?.user) {
+            setUser(details.user);
+            setIsAuthenticated(true);
+          }
+        }
+
+        if (event.type === 'logout_success' || event.type === 'session_restoration_failed' || event.code === 'AUTH_FAILED') {
+          setUser(null);
+          setIsAuthenticated(false);
+        }
+      }, { domains: ['authentication'], replay: true });
+      
       setAuthProvider(authProvider);
       setSdk(sdkInstance);
       setIsInitialized(true);
@@ -167,6 +185,16 @@ export const PersSDKProvider: React.FC<{
       initializingRef.current = false;
     }
   }, [isInitialized]);
+  
+  // Cleanup subscription on unmount
+  useEffect(() => {
+    return () => {
+      if (eventUnsubscribeRef.current) {
+        eventUnsubscribeRef.current();
+        eventUnsubscribeRef.current = null;
+      }
+    };
+  }, []);
 
   const setAuthenticationState = useCallback((user: UserDTO | AdminDTO | null, isAuthenticated: boolean) => {
     setUser(user);
@@ -219,45 +247,7 @@ export const PersSDKProvider: React.FC<{
       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
-  useEffect(() => {
-    if (!sdk) return;
-
-    const unsubscribe = sdk.events.subscribe((event) => {
-      if (event.domain !== 'authentication') return;
-
-      // Session restored successfully - sync React state
-      if (event.type === 'session_restored') {
-        console.log('[PersSDK] Session restoration event received, syncing state...');
-        // 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') {
-        console.log('[PersSDK] Authentication failed - clearing session');
-        setAuthenticationState(null, false);
-      }
-    }, { domains: ['authentication'] });
-
-    return () => {
-      unsubscribe();
-    };
-  }, [sdk, setAuthenticationState]);
+  }, [setAuthenticationState]);
 
   // iOS/Android: Monitor app state and validate tokens when app becomes active
   useEffect(() => {
@@ -267,7 +257,6 @@ export const PersSDKProvider: React.FC<{
 
     const handleAppStateChange = async (nextAppState: AppStateStatus) => {
       if (nextAppState === 'active' && isAuthenticated) {
-        console.log('[PersSDK] App became active - validating tokens');
         try {
           // Trigger token validation when app resumes from background
           // This ensures tokens are checked after extended inactivity