@explorins/pers-sdk-react-native 2.1.13 → 2.1.17

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;;;;;;;;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"}
+{"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,CA+NA,CAAC;AAGF,eAAO,MAAM,UAAU,QAAO,cAQ7B,CAAC"}

package/dist/providers/PersSDKProvider.js

@@ -158,22 +158,12 @@ export const PersSDKProvider = ({ children, config }) => {
         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);
-                    });
+            // Handle both session restoration and fresh login
+            if (event.type === 'session_restored' || event.type === 'login_success') {
+                const details = event.details;
+                if (details?.user) {
+                    console.log(`[PersSDK] ${event.type}: syncing user state`);
+                    setAuthenticationState(details.user, true);
                 }
             }
             // Session restoration failed or auth error - clear React state
@@ -181,7 +171,7 @@ export const PersSDKProvider = ({ children, config }) => {
                 console.log('[PersSDK] Authentication failed - clearing session');
                 setAuthenticationState(null, false);
             }
-        }, { domains: ['authentication'] });
+        }, { domains: ['authentication'], replay: true });
         return () => {
             unsubscribe();
         };

package/dist/providers/rn-dpop-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rn-dpop-provider.d.ts","sourceRoot":"","sources":["../../src/providers/rn-dpop-provider.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAiB3E,qBAAa,uBAAwB,YAAW,kBAAkB;IAChE;;;;;OAKG;IACG,eAAe,CAAC,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAqC1E,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAqD9E,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgB3D,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,eAAe;CAOxB"}
+{"version":3,"file":"rn-dpop-provider.d.ts","sourceRoot":"","sources":["../../src/providers/rn-dpop-provider.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAgD3E,qBAAa,uBAAwB,YAAW,kBAAkB;IAChE;;;;;OAKG;IACG,eAAe,CAAC,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IA0C1E,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IA0D9E,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqB3D,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,eAAe;CAOxB"}

package/dist/providers/rn-dpop-provider.js

@@ -1,20 +1,44 @@
 import { Platform } from 'react-native';
 import { Buffer } from 'buffer';
-// Conditionally require quick-crypto for Native platforms only
-let crypto;
-if (Platform.OS !== 'web') {
+// Lazy-loaded crypto module - initialized on first use to avoid native module timing issues
+let _crypto = null;
+let _cryptoInitialized = false;
+/**
+ * Lazily load the crypto module.
+ *
+ * Supports customer pre-initialization via global.__QuickCrypto for environments
+ * where native module timing is unpredictable (e.g., certain React Native setups).
+ *
+ * @returns The crypto module or null if unavailable
+ */
+function getCrypto() {
+    if (_cryptoInitialized) {
+        return _crypto;
+    }
+    _cryptoInitialized = true;
+    if (Platform.OS === 'web') {
+        // On Web, we shouldn't be using this provider (Core SDK has WebDPoPProvider)
+        _crypto = {
+            generateKeyPair: () => { throw new Error('ReactNativeDPoPProvider not supported on Web'); },
+            randomUUID: () => globalThis.crypto?.randomUUID?.() || `${Date.now()}-${Math.random()}`
+        };
+        return _crypto;
+    }
+    // Check for customer pre-initialized global (for native module timing issues)
+    if (typeof global !== 'undefined' && global.__QuickCrypto) {
+        _crypto = global.__QuickCrypto;
+        return _crypto;
+    }
+    // Standard lazy load
     try {
-        crypto = require('react-native-quick-crypto').default || require('react-native-quick-crypto');
+        _crypto = require('react-native-quick-crypto').default || require('react-native-quick-crypto');
     }
     catch (e) {
-        console.warn('ReactNativeDPoPProvider: Failed to load react-native-quick-crypto', e);
+        console.warn('ReactNativeDPoPProvider: Failed to load react-native-quick-crypto.', e);
+        console.warn('Tip: If you encounter timing issues, pre-initialize in index.js: global.__QuickCrypto = require("react-native-quick-crypto")');
+        _crypto = null;
     }
-}
-else {
-    // on Web, we shouldn't be using this provider anyway (Core SDK has WebDPoPProvider)
-    crypto = {
-        generateKeyPair: () => { throw new Error('ReactNativeDPoPProvider not supported on Web'); }
-    };
+    return _crypto;
 }
 export class ReactNativeDPoPProvider {
     /**
@@ -24,6 +48,10 @@ export class ReactNativeDPoPProvider {
      * Falls back to Node.js crypto API on iOS if needed.
      */
     async generateKeyPair(options) {
+        const crypto = getCrypto();
+        if (!crypto) {
+            throw new Error('Crypto module not available. Install react-native-quick-crypto or pre-initialize global.__QuickCrypto');
+        }
         // Try WebCrypto API first (works on both iOS and Android)
         if (crypto.subtle) {
             try {
@@ -57,6 +85,10 @@ export class ReactNativeDPoPProvider {
         });
     }
     async signProof(payload, keyPair) {
+        const crypto = getCrypto();
+        if (!crypto) {
+            throw new Error('Crypto module not available for signing');
+        }
         // 1. Construct Header
         const header = {
             typ: 'dpop+jwt',
@@ -67,7 +99,7 @@ export class ReactNativeDPoPProvider {
         const finalPayload = {
             ...payload,
             iat: payload.iat || Math.floor(Date.now() / 1000),
-            jti: payload.jti || crypto.randomUUID()
+            jti: payload.jti || (crypto.randomUUID?.() || `${Date.now()}-${Math.random()}`)
         };
         // 3. Encode
         const b64Header = this.base64Url(JSON.stringify(header));
@@ -93,6 +125,10 @@ export class ReactNativeDPoPProvider {
         return `${signingInput}.${this.base64UrlBuffer(signature)}`;
     }
     async hashAccessToken(accessToken) {
+        const crypto = getCrypto();
+        if (!crypto) {
+            throw new Error('Crypto module not available for hashing');
+        }
         // Try WebCrypto first
         if (crypto.subtle) {
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk-react-native",
-  "version": "2.1.13",
+  "version": "2.1.17",
   "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.20",
+    "@explorins/pers-sdk": "^2.1.24",
     "@explorins/pers-signer": "^1.0.33",
     "buffer": "^6.0.3",
     "ethers": "^6.15.0",
@@ -155,7 +155,7 @@
     "@ethersproject/scrypt": false
   },
   "devDependencies": {
-    "@explorins/pers-shared": "^2.1.123",
+    "@explorins/pers-shared": "^2.1.128",
     "@react-native-async-storage/async-storage": "^3.0.2",
     "@rollup/plugin-commonjs": "^25.0.7",
     "@rollup/plugin-json": "^6.1.0",

package/src/hooks/index.ts

@@ -38,10 +38,13 @@ export type {
 } from './useTokenBalances';
 
 // Export campaign-related types
-export type { CampaignClaimFilters, CampaignHook, GetCampaignsOptions } from './useCampaigns';
+export type { CampaignClaimFilters, CampaignFilterOptions, CampaignHook, GetCampaignsOptions } from './useCampaigns';
 
 // Export redemption-related types
-export type { RedemptionRedeemFilters, RedemptionHook } from './useRedemptions';
+export type { RedemptionRedeemFilters, RedemptionFilterOptions, RedemptionHook, GetRedemptionsOptions } from './useRedemptions';
+
+// Export business-related types
+export type { BusinessFilterOptions, BusinessHook } from './useBusiness';
 
 // Export transaction-related types
 export type { TransactionQueryOptions, TransactionHook } from './useTransactions';

package/src/hooks/useAnalytics.ts

@@ -13,7 +13,7 @@ import {
   BusinessRankingAnalyticsResponseDTO,
   RetentionAnalyticsRequestDTO,
   RetentionAnalyticsResponseDTO
-} from '@explorins/pers-shared';
+} from '@explorins/pers-sdk';
 
 /**
  * React hook for analytics operations in the PERS SDK

package/src/hooks/useAuth.ts

@@ -2,7 +2,7 @@ import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
 import type { RawUserData } from '@explorins/pers-sdk/core';
 import { AccountOwnerType } from '@explorins/pers-sdk/core';
-import type { UserDTO, AdminDTO, SessionAuthContextResponseDTO } from '@explorins/pers-shared';
+import type { UserDTO, SessionAuthContextResponseDTO } from '@explorins/pers-sdk';
 
 // Re-export RawUserData for convenience
 export type { RawUserData };
@@ -80,22 +80,15 @@ export const useAuth = () => {
       await authProvider.setAccessToken(jwtToken);
       
       // Perform login using the manager
+      // SDK emits login_success event with user data - PersSDKProvider handles state sync
       const result = await sdk.auth.loginWithToken(jwtToken, userType);
       
-      const userData = result.user || result.admin;
-      
-      if (userData) {
-        setAuthenticationState(userData, true);
-        
-        return result;
-      } else {
-        throw new Error('No user data returned from login');
-      }
+      return result;
     } catch (error) {
       console.error('Login failed:', error);
       throw error;
     }
-  }, [sdk, authProvider, setAuthenticationState]);
+  }, [sdk, authProvider]);
 
   /**
    * Logs in a user using raw user data (direct authentication bypass)
@@ -116,25 +109,18 @@ export const useAuth = () => {
 
     try {
       // Use the raw data login from the auth manager
+      // SDK emits login_success event with user data - PersSDKProvider handles state sync
       const result = await sdk.auth.loginWithRawData(rawUserData);
       
       // Set token from result
       if (result.accessToken) {
         await authProvider.setAccessToken(result.accessToken);
       }
-      
-      const userData = result.user;
-      
-      if (userData) {
-        setAuthenticationState(userData, true);
-      } else {
-        throw new Error('No user data returned from raw data login');
-      }
     } catch (error) {
       console.error('Raw data login failed:', error);
       throw error;
     }
-  }, [sdk, authProvider, setAuthenticationState]);
+  }, [sdk, authProvider]);
 
   /**
    * Logs out the current user and clears authentication state

package/src/hooks/useBusiness.ts

@@ -1,6 +1,9 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
-import type { BusinessDTO, BusinessTypeDTO, BusinessUpdateRequestDTO, BusinessToggleActiveRequestDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
+import type { BusinessDTO, BusinessTypeDTO, BusinessUpdateRequestDTO, BusinessToggleActiveRequestDTO, PaginatedResponseDTO, BusinessFilterOptions } from '@explorins/pers-sdk';
+
+// Re-export for consumers
+export type { BusinessFilterOptions } from '@explorins/pers-sdk';
 
 /**
  * React hook for business operations in the PERS SDK
@@ -107,13 +110,39 @@ export const useBusiness = () => {
     }
   }, [sdk, isInitialized]);
 
-  const getBusinesses = useCallback(async (): Promise<PaginatedResponseDTO<BusinessDTO>> => {
+  /**
+   * Admin: Get all businesses with optional filtering
+   * 
+   * @param options - Filter and pagination options
+   * @returns Promise resolving to paginated businesses
+   * 
+   * @example
+   * ```typescript
+   * // Get all businesses
+   * const { data } = await getBusinesses();
+   * 
+   * // Filter by tag
+   * const tagged = await getBusinesses({ tag: 'restaurant' });
+   * 
+   * // Multiple tags (OR match)
+   * const multiTag = await getBusinesses({ tag: ['restaurant', 'cafe'] });
+   * 
+   * // With search and pagination
+   * const filtered = await getBusinesses({ 
+   *   search: 'coffee', 
+   *   active: true,
+   *   page: 1, 
+   *   limit: 20 
+   * });
+   * ```
+   */
+  const getBusinesses = useCallback(async (options?: BusinessFilterOptions): Promise<PaginatedResponseDTO<BusinessDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.businesses.getBusinesses();
+      const result = await sdk.businesses.getBusinesses(options);
       return result;
     } catch (error) {
       console.error('Failed to fetch all businesses:', error);

package/src/hooks/useCampaigns.ts

@@ -9,21 +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 */
@@ -32,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[];
 }
 
@@ -57,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 (
@@ -87,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
@@ -95,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 (
@@ -257,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({ 
@@ -288,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
    * 
@@ -299,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,14 +9,42 @@ import type {
   RedemptionTypeDTO,
   PaginatedResponseDTO,
   RedemptionRedeemIncludeRelation,
+  RedemptionIncludeRelation,
   ProcessRecordStatus,
-  DynamicContext
-} from '@explorins/pers-shared';
-import type { RedemptionRedeemFilters } from '@explorins/pers-sdk/redemption';
+  DynamicContext,
+  SortOrder
+} from '@explorins/pers-sdk';
+import type { RedemptionRedeemFilters, RedemptionFilterOptions } from '@explorins/pers-sdk/redemption';
 import type { PaginationOptions } from '@explorins/pers-sdk';
 
 // Re-export for consumers
-export type { RedemptionRedeemFilters } from '@explorins/pers-sdk/redemption';
+export type { RedemptionRedeemFilters, RedemptionFilterOptions } from '@explorins/pers-sdk/redemption';
+
+/**
+ * Options for fetching redemptions with filtering and pagination
+ */
+export interface GetRedemptionsOptions {
+  /** Filter by active status (Admin only - regular users always see active offers) */
+  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' | 'startDate';
+  /** Sort direction */
+  sortOrder?: SortOrder;
+}
 
 export const useRedemptions = () => {
   const { sdk, isInitialized, isAuthenticated } = usePersSDK();
@@ -29,8 +57,49 @@ export const useRedemptions = () => {
    * **Administrators:** Can see all redemptions and filter by active/inactive status
    * 
    * The backend enforces permission-based filtering automatically.
+   * 
+   * @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')
+   * @param options.sortOrder - Sort direction ('ASC' | 'DESC')
+   * 
+   * @example Basic usage
+   * ```typescript
+   * const { data: offers } = await getRedemptions();
+   * ```
+   * 
+   * @example Filter by date range
+   * ```typescript
+   * const { data: dateFiltered } = await getRedemptions({ 
+   *   startDate: '2026-05-01', 
+   *   endDate: '2026-06-30' 
+   * });
+   * ```
+   * 
+   * @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',
+   *   page: 1, 
+   *   limit: 10,
+   *   sortBy: 'name',
+   *   sortOrder: 'ASC'
+   * });
+   * ```
    */
-  const getRedemptions = useCallback(async (options?: { active?: boolean }): Promise<PaginatedResponseDTO<RedemptionDTO>> => {
+  const getRedemptions = useCallback(async (options?: GetRedemptionsOptions): Promise<PaginatedResponseDTO<RedemptionDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
@@ -194,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
    * 
@@ -208,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