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

package/dist/hooks/useCampaigns.js

@@ -15,12 +15,26 @@ export const useCampaigns = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
-    const getCampaignById = useCallback(async (campaignId) => {
+    /**
+     * Get campaign by ID with optional include relations
+     *
+     * @param campaignId - The campaign ID
+     * @param include - Relations to include: 'triggerSources', 'businesses'
+     * @returns Promise resolving to campaign data
+     *
+     * @example
+     * ```typescript
+     * // Get campaign with all related data
+     * const campaign = await getCampaignById('campaign-123', ['triggerSources', 'businesses']);
+     * console.log('Trigger sources:', campaign.included?.triggerSources);
+     * ```
+     */
+    const getCampaignById = useCallback(async (campaignId, include) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.campaigns.getCampaignById(campaignId);
+            const result = await sdk.campaigns.getCampaignById(campaignId, include);
             return result;
         }
         catch (error) {
@@ -44,7 +58,25 @@ export const useCampaigns = () => {
             throw error;
         }
     }, [sdk, isInitialized, isAuthenticated]);
-    const getUserClaims = useCallback(async () => {
+    /**
+     * Get user's campaign claims with optional pagination and include relations
+     *
+     * @param options - Optional options including pagination and include relations
+     * @returns Promise resolving to paginated campaign claims
+     *
+     * @example
+     * ```typescript
+     * // Get user's claims with campaign details
+     * const { data: claims } = await getUserClaims({ include: ['campaign', 'business'] });
+     * claims.forEach(claim => {
+     *   console.log('Campaign:', claim.included?.campaign?.title);
+     * });
+     *
+     * // With pagination
+     * const { data } = await getUserClaims({ page: 1, limit: 10, include: ['campaign'] });
+     * ```
+     */
+    const getUserClaims = useCallback(async (options) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
@@ -53,7 +85,7 @@ export const useCampaigns = () => {
             return { data: [], pagination: { page: 1, limit: 0, total: 0, pages: 0, hasNext: false, hasPrev: false } };
         }
         try {
-            const result = await sdk.campaigns.getUserClaims();
+            const result = await sdk.campaigns.getUserClaims(options);
             return result;
         }
         catch (error) {
@@ -88,12 +120,28 @@ export const useCampaigns = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
-    const getCampaignClaims = useCallback(async () => {
+    /**
+     * Admin: Get campaign claims with optional filters and include relations
+     *
+     * @param filters - Optional filters for campaign, user, or business
+     * @param include - Relations to include: 'campaign', 'user', 'business'
+     * @returns Promise resolving to paginated campaign claims
+     *
+     * @example
+     * ```typescript
+     * // Get all claims with user details
+     * const { data: claims } = await getCampaignClaims({}, ['user']);
+     *
+     * // Get claims for a specific campaign
+     * const { data } = await getCampaignClaims({ campaignId: 'campaign-123' }, ['user', 'business']);
+     * ```
+     */
+    const getCampaignClaims = useCallback(async (filters, include) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.campaigns.getCampaignClaims();
+            const result = await sdk.campaigns.getCampaignClaims(filters, include);
             return result;
         }
         catch (error) {
@@ -101,12 +149,19 @@ export const useCampaigns = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
-    const getCampaignClaimsByUserId = useCallback(async (userId) => {
+    /**
+     * Admin: Get campaign claims by user ID with optional include relations
+     *
+     * @param userId - The user ID
+     * @param include - Relations to include: 'campaign', 'user', 'business'
+     * @returns Promise resolving to paginated campaign claims
+     */
+    const getCampaignClaimsByUserId = useCallback(async (userId, include) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.campaigns.getCampaignClaimsByUserId(userId);
+            const result = await sdk.campaigns.getCampaignClaimsByUserId(userId, undefined, include);
             return result;
         }
         catch (error) {
@@ -114,12 +169,19 @@ export const useCampaigns = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
-    const getCampaignClaimsByBusinessId = useCallback(async (businessId) => {
+    /**
+     * Admin: Get campaign claims by business ID with optional include relations
+     *
+     * @param businessId - The business ID
+     * @param include - Relations to include: 'campaign', 'user', 'business'
+     * @returns Promise resolving to paginated campaign claims
+     */
+    const getCampaignClaimsByBusinessId = useCallback(async (businessId, include) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.campaigns.getCampaignClaimsByBusinessId(businessId);
+            const result = await sdk.campaigns.getCampaignClaimsByBusinessId(businessId, undefined, include);
             return result;
         }
         catch (error) {
@@ -127,6 +189,76 @@ export const useCampaigns = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
+    // ==========================================
+    // TRIGGER SOURCE ASSIGNMENT (Admin)
+    // Note: TriggerSource CRUD is in useTriggerSources hook
+    // ==========================================
+    /**
+     * Admin: Assign a trigger source to a campaign
+     *
+     * Associates a trigger source (QR code, NFC tag, etc.) with a campaign.
+     * A campaign can have multiple trigger sources.
+     *
+     * Note: To create/update/delete trigger sources, use `useTriggerSources` hook.
+     *
+     * @param campaignId - Campaign UUID
+     * @param triggerSourceId - Trigger source UUID
+     * @returns Promise resolving to updated campaign
+     *
+     * @example
+     * ```typescript
+     * const { create } = useTriggerSources();
+     * const { assignTriggerSource } = useCampaigns();
+     *
+     * // Create trigger source first
+     * const source = await create({ type: 'QR_CODE', name: 'Store QR' });
+     *
+     * // Then assign to campaign
+     * const updated = await assignTriggerSource('campaign-123', source.id);
+     * ```
+     */
+    const assignTriggerSource = useCallback(async (campaignId, triggerSourceId) => {
+        if (!isInitialized || !sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        if (!isAuthenticated) {
+            throw new Error('SDK not authenticated. assignTriggerSource requires admin authentication.');
+        }
+        try {
+            const result = await sdk.campaigns.assignTriggerSource(campaignId, triggerSourceId);
+            return result;
+        }
+        catch (error) {
+            console.error('Failed to assign trigger source:', error);
+            throw error;
+        }
+    }, [sdk, isInitialized, isAuthenticated]);
+    /**
+     * Admin: Remove a trigger source from a campaign
+     *
+     * Removes the association between a trigger source and a campaign.
+     * The trigger source itself is not deleted.
+     *
+     * @param campaignId - Campaign UUID
+     * @param triggerSourceId - Trigger source UUID
+     * @returns Promise resolving to updated campaign
+     */
+    const removeTriggerSource = useCallback(async (campaignId, triggerSourceId) => {
+        if (!isInitialized || !sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        if (!isAuthenticated) {
+            throw new Error('SDK not authenticated. removeTriggerSource requires admin authentication.');
+        }
+        try {
+            const result = await sdk.campaigns.removeTriggerSource(campaignId, triggerSourceId);
+            return result;
+        }
+        catch (error) {
+            console.error('Failed to remove trigger source:', error);
+            throw error;
+        }
+    }, [sdk, isInitialized, isAuthenticated]);
     return {
         getActiveCampaigns,
         getCampaignById,
@@ -137,6 +269,8 @@ export const useCampaigns = () => {
         getCampaignClaims,
         getCampaignClaimsByUserId,
         getCampaignClaimsByBusinessId,
+        assignTriggerSource,
+        removeTriggerSource,
         isAvailable: isInitialized && !!sdk?.campaigns,
     };
 };

package/dist/hooks/useEvents.d.ts

@@ -24,23 +24,35 @@ export interface EventsHook {
  * React Native hook for PERS SDK event system
  *
  * This hook provides access to the platform-agnostic event system for subscribing to
- * transaction, authentication, campaign, and system events. All events include a
- * `userMessage` field ready for display to end users.
+ * transaction, authentication, campaign, blockchain, and system events. All events
+ * include a `userMessage` field ready for display to end users.
  *
  * **Event Domains:**
  * - `auth` - Authentication events (login, logout, token refresh)
  * - `user` - User profile events (update, create)
- * - `transaction` - Transaction events (created, completed, failed)
+ * - `transaction` - Transaction events (created, submitted, confirmed)
  * - `campaign` - Campaign events (claimed, activated)
  * - `redemption` - Redemption events (redeemed, expired)
  * - `business` - Business events (created, updated, membership)
+ * - `wallet` - Real-time blockchain events (Transfer, Approval, etc.) - Auto-enabled on auth
  * - `api` - API error events (network, validation, server errors)
  *
+ * **Blockchain Events (Wallet Domain):**
+ * When `sdk.connectWalletEvents()` is called (or auto-enabled via `captureWalletEvents: true`),
+ * real-time blockchain events are automatically routed through the same event system:
+ * ```typescript
+ * const { subscribe } = useEvents();
+ *
+ * subscribe((event) => {
+ *   if (event.domain === 'wallet') {
+ *     console.log('Blockchain event:', event.type); // wallet_transfer, wallet_approval, etc.
+ *   }
+ * });
+ * ```
+ *
  * **Notification Levels:**
  * - `success` - Operation completed successfully
  * - `error` - Operation failed
- * - `warning` - Operation completed with warnings
- * - `info` - Informational event
  *
  * **Cleanup:**
  * All subscriptions created through this hook are automatically cleaned up when

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

@@ -1 +1 @@
-{"version":3,"file":"useEvents.d.ts","sourceRoot":"","sources":["../../src/hooks/useEvents.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;AAElE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,WAAW,CAAC;IACxE,IAAI,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,WAAW,CAAC;IACnE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwJG;AACH,eAAO,MAAM,SAAS,QAAO,UA2K5B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC"}
+{"version":3,"file":"useEvents.d.ts","sourceRoot":"","sources":["../../src/hooks/useEvents.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;AAElE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,WAAW,CAAC;IACxE,IAAI,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,WAAW,CAAC;IACnE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoKG;AACH,eAAO,MAAM,SAAS,QAAO,UA2K5B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC"}

package/dist/hooks/useEvents.js

@@ -4,23 +4,35 @@ import { usePersSDK } from '../providers/PersSDKProvider';
  * React Native hook for PERS SDK event system
  *
  * This hook provides access to the platform-agnostic event system for subscribing to
- * transaction, authentication, campaign, and system events. All events include a
- * `userMessage` field ready for display to end users.
+ * transaction, authentication, campaign, blockchain, and system events. All events
+ * include a `userMessage` field ready for display to end users.
  *
  * **Event Domains:**
  * - `auth` - Authentication events (login, logout, token refresh)
  * - `user` - User profile events (update, create)
- * - `transaction` - Transaction events (created, completed, failed)
+ * - `transaction` - Transaction events (created, submitted, confirmed)
  * - `campaign` - Campaign events (claimed, activated)
  * - `redemption` - Redemption events (redeemed, expired)
  * - `business` - Business events (created, updated, membership)
+ * - `wallet` - Real-time blockchain events (Transfer, Approval, etc.) - Auto-enabled on auth
  * - `api` - API error events (network, validation, server errors)
  *
+ * **Blockchain Events (Wallet Domain):**
+ * When `sdk.connectWalletEvents()` is called (or auto-enabled via `captureWalletEvents: true`),
+ * real-time blockchain events are automatically routed through the same event system:
+ * ```typescript
+ * const { subscribe } = useEvents();
+ *
+ * subscribe((event) => {
+ *   if (event.domain === 'wallet') {
+ *     console.log('Blockchain event:', event.type); // wallet_transfer, wallet_approval, etc.
+ *   }
+ * });
+ * ```
+ *
  * **Notification Levels:**
  * - `success` - Operation completed successfully
  * - `error` - Operation failed
- * - `warning` - Operation completed with warnings
- * - `info` - Informational event
  *
  * **Cleanup:**
  * All subscriptions created through this hook are automatically cleaned up when

package/dist/hooks/useRedemptions.d.ts

@@ -1,12 +1,15 @@
 import { OnStatusUpdateFn } from './useTransactionSigner';
-import type { RedemptionCreateRequestDTO, RedemptionDTO, RedemptionRedeemDTO, RedemptionRedeemRequestResponseDTO, RedemptionTypeDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
+import type { RedemptionCreateRequestDTO, RedemptionDTO, RedemptionRedeemDTO, RedemptionRedeemRequestResponseDTO, RedemptionTypeDTO, PaginatedResponseDTO, RedemptionRedeemIncludeRelation } from '@explorins/pers-shared';
+import type { RedemptionRedeemFilters } from '@explorins/pers-sdk/redemption';
+export type { RedemptionRedeemFilters } from '@explorins/pers-sdk/redemption';
 export declare const useRedemptions: () => {
     getRedemptions: (options?: {
         active?: boolean;
     }) => Promise<PaginatedResponseDTO<RedemptionDTO>>;
-    getUserRedemptions: () => Promise<PaginatedResponseDTO<RedemptionRedeemDTO>>;
+    getUserRedemptions: (include?: RedemptionRedeemIncludeRelation[]) => Promise<PaginatedResponseDTO<RedemptionRedeemDTO>>;
     redeem: (redemptionId: string, onStatusUpdate?: OnStatusUpdateFn) => Promise<RedemptionRedeemRequestResponseDTO>;
     getRedemptionTypes: () => Promise<PaginatedResponseDTO<RedemptionTypeDTO>>;
+    getRedemptionRedeems: (filters?: RedemptionRedeemFilters, include?: RedemptionRedeemIncludeRelation[]) => Promise<PaginatedResponseDTO<RedemptionRedeemDTO>>;
     createRedemption: (redemptionData: RedemptionCreateRequestDTO) => Promise<RedemptionDTO>;
     updateRedemption: (redemptionId: string, redemptionData: RedemptionCreateRequestDTO) => Promise<RedemptionDTO>;
     toggleRedemptionStatus: (redemptionId: string) => Promise<RedemptionDTO>;

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

@@ -1 +1 @@
-{"version":3,"file":"useRedemptions.d.ts","sourceRoot":"","sources":["../../src/hooks/useRedemptions.ts"],"names":[],"mappings":"AAEA,OAAO,EAA0C,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAClG,OAAO,KAAK,EACV,0BAA0B,EAC1B,aAAa,EACb,mBAAmB,EACnB,kCAAkC,EAClC,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC;AAEhC,eAAO,MAAM,cAAc;+BAY2B;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,KAAG,QAAQ,qBAAqB,aAAa,CAAC,CAAC;8BActE,QAAQ,qBAAqB,mBAAmB,CAAC,CAAC;2BAkBnD,MAAM,mBAAmB,gBAAgB,KAAG,QAAQ,kCAAkC,CAAC;8BA4DtF,QAAQ,qBAAqB,iBAAiB,CAAC,CAAC;uCAdrC,0BAA0B,KAAG,QAAQ,aAAa,CAAC;qCA4BrD,MAAM,kBAAkB,0BAA0B,KAAG,QAAQ,aAAa,CAAC;2CAcrE,MAAM,KAAG,QAAQ,aAAa,CAAC;;;;CA2BhG,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC"}
+{"version":3,"file":"useRedemptions.d.ts","sourceRoot":"","sources":["../../src/hooks/useRedemptions.ts"],"names":[],"mappings":"AAEA,OAAO,EAA0C,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAClG,OAAO,KAAK,EACV,0BAA0B,EAC1B,aAAa,EACb,mBAAmB,EACnB,kCAAkC,EAClC,iBAAiB,EACjB,oBAAoB,EACpB,+BAA+B,EAChC,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAG9E,YAAY,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E,eAAO,MAAM,cAAc;+BAY2B;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,KAAG,QAAQ,qBAAqB,aAAa,CAAC,CAAC;mCA+B3G,+BAA+B,EAAE,KAC1C,QAAQ,qBAAqB,mBAAmB,CAAC,CAAC;2BAkBL,MAAM,mBAAmB,gBAAgB,KAAG,QAAQ,kCAAkC,CAAC;8BAmGtF,QAAQ,qBAAqB,iBAAiB,CAAC,CAAC;qCA9BrF,uBAAuB,YACvB,+BAA+B,EAAE,KAC1C,QAAQ,qBAAqB,mBAAmB,CAAC,CAAC;uCAcO,0BAA0B,KAAG,QAAQ,aAAa,CAAC;qCA4BrD,MAAM,kBAAkB,0BAA0B,KAAG,QAAQ,aAAa,CAAC;2CAcrE,MAAM,KAAG,QAAQ,aAAa,CAAC;;;;CA4BhG,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/hooks/useRedemptions.js

@@ -25,7 +25,23 @@ export const useRedemptions = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
-    const getUserRedemptions = useCallback(async () => {
+    /**
+     * Get user's redemption history with optional include relations
+     *
+     * @param include - Relations to include: 'redemption', 'user', 'business'
+     * @returns Promise resolving to paginated redemption history
+     *
+     * @example
+     * ```typescript
+     * // Get user redemptions with full redemption details
+     * const { data: redeems } = await getUserRedemptions(['redemption', 'business']);
+     * redeems.forEach(redeem => {
+     *   console.log('Redemption:', redeem.included?.redemption?.title);
+     *   console.log('Business:', redeem.included?.business?.displayName);
+     * });
+     * ```
+     */
+    const getUserRedemptions = useCallback(async (include) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
@@ -34,7 +50,7 @@ export const useRedemptions = () => {
             return { data: [], pagination: { page: 1, limit: 0, total: 0, pages: 0, hasNext: false, hasPrev: false } };
         }
         try {
-            const result = await sdk.redemptions.getUserRedemptions();
+            const result = await sdk.redemptions.getUserRedemptions(undefined, include);
             return result;
         }
         catch (error) {
@@ -88,6 +104,40 @@ export const useRedemptions = () => {
         }
     }, [sdk, isInitialized, isAuthenticated, signAndSubmitTransactionWithJWT, isSignerAvailable]);
     // Admin methods
+    /**
+     * Admin: Get all redemption redeems with filters and include relations
+     *
+     * Retrieves all redemption redeems across the platform with filtering.
+     *
+     * @param filters - Optional filters for user, redemption, and pagination
+     * @param include - Relations to include: 'redemption', 'user', 'business'
+     * @returns Promise resolving to paginated redemption redeems
+     *
+     * @example
+     * ```typescript
+     * // Get all redeems with user details
+     * const { data: redeems } = await getRedemptionRedeems({}, ['user', 'redemption']);
+     *
+     * // Filter by specific user
+     * const { data: userRedeems } = await getRedemptionRedeems(
+     *   { userId: 'user-123' },
+     *   ['redemption']
+     * );
+     * ```
+     */
+    const getRedemptionRedeems = useCallback(async (filters, include) => {
+        if (!isInitialized || !sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        try {
+            const result = await sdk.redemptions.getRedemptionRedeems(filters, include);
+            return result;
+        }
+        catch (error) {
+            console.error('Failed to fetch redemption redeems:', error);
+            throw error;
+        }
+    }, [sdk, isInitialized]);
     const createRedemption = useCallback(async (redemptionData) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
@@ -145,6 +195,7 @@ export const useRedemptions = () => {
         getUserRedemptions,
         redeem,
         getRedemptionTypes,
+        getRedemptionRedeems,
         createRedemption,
         updateRedemption,
         toggleRedemptionStatus,

package/dist/hooks/useTokenBalances.d.ts

@@ -31,6 +31,18 @@ export interface UseTokenBalancesOptions {
     autoLoad?: boolean;
     /** Optional refresh interval in milliseconds (0 = disabled) */
     refreshInterval?: number;
+    /**
+     * Auto-refresh balances when wallet events are received (Transfer, Approval, etc.)
+     * Requires `captureWalletEvents: true` in SDK config (default)
+     * @default true
+     */
+    refreshOnWalletEvents?: boolean;
+    /**
+     * Debounce time for wallet event-triggered refreshes (milliseconds)
+     * Prevents rapid refresh calls during batch transfers
+     * @default 1000
+     */
+    walletEventDebounceMs?: number;
 }
 /**
  * Token balance loading hook return value
@@ -119,6 +131,18 @@ export interface UseTokenBalancesResult {
  * ```
  *
  * @example
+ * **With Wallet Events (Real-time):**
+ * ```typescript
+ * // Auto-refresh on Transfer, Approval, and other blockchain events
+ * const { tokenBalances } = useTokenBalances({
+ *   accountAddress: walletAddress!,
+ *   availableTokens,
+ *   refreshOnWalletEvents: true,    // Enable real-time refresh (default: true)
+ *   walletEventDebounceMs: 1000     // Debounce rapid events (default: 1000ms)
+ * });
+ * ```
+ *
+ * @example
  * **Multi-Wallet Support:**
  * ```typescript
  * function MultiWalletBalances() {

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

@@ -1 +1 @@
-{"version":3,"file":"useTokenBalances.d.ts","sourceRoot":"","sources":["../../src/hooks/useTokenBalances.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,0BAA0B,CAAC;AAElF;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,uCAAuC;IACvC,YAAY,EAAE,YAAY,CAAC;IAC3B,8DAA8D;IAC9D,KAAK,EAAE,QAAQ,CAAC;IAChB,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,eAAe,CAAC,EAAE,QAAQ,EAAE,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,0DAA0D;IAC1D,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uCAAuC;IACvC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,sFAAsF;IACtF,WAAW,EAAE,OAAO,CAAC;IACrB,0CAA0C;IAC1C,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,sBAAsB,CA8JzF"}
+{"version":3,"file":"useTokenBalances.d.ts","sourceRoot":"","sources":["../../src/hooks/useTokenBalances.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,0BAA0B,CAAC;AAElF;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,uCAAuC;IACvC,YAAY,EAAE,YAAY,CAAC;IAC3B,8DAA8D;IAC9D,KAAK,EAAE,QAAQ,CAAC;IAChB,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,eAAe,CAAC,EAAE,QAAQ,EAAE,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,0DAA0D;IAC1D,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uCAAuC;IACvC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,sFAAsF;IACtF,WAAW,EAAE,OAAO,CAAC;IACrB,0CAA0C;IAC1C,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,sBAAsB,CAgMzF"}

package/dist/hooks/useTokenBalances.js

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useState, useRef } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
 import { useWeb3 } from './useWeb3';
 import { NativeTokenTypes } from '@explorins/pers-shared';
@@ -72,6 +72,18 @@ import { NativeTokenTypes } from '@explorins/pers-shared';
  * ```
  *
  * @example
+ * **With Wallet Events (Real-time):**
+ * ```typescript
+ * // Auto-refresh on Transfer, Approval, and other blockchain events
+ * const { tokenBalances } = useTokenBalances({
+ *   accountAddress: walletAddress!,
+ *   availableTokens,
+ *   refreshOnWalletEvents: true,    // Enable real-time refresh (default: true)
+ *   walletEventDebounceMs: 1000     // Debounce rapid events (default: 1000ms)
+ * });
+ * ```
+ *
+ * @example
  * **Multi-Wallet Support:**
  * ```typescript
  * function MultiWalletBalances() {
@@ -90,12 +102,14 @@ import { NativeTokenTypes } from '@explorins/pers-shared';
  * ```
  */
 export function useTokenBalances(options) {
-    const { accountAddress, availableTokens = [], autoLoad = true, refreshInterval = 0 } = options;
+    const { accountAddress, availableTokens = [], autoLoad = true, refreshInterval = 0, refreshOnWalletEvents = true, walletEventDebounceMs = 1000 } = options;
     const { isAuthenticated, sdk } = usePersSDK();
     const web3 = useWeb3();
     const [tokenBalances, setTokenBalances] = useState([]);
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
+    // Debounce ref for wallet events
+    const walletEventDebounceRef = useRef(null);
     // Check if the hook is available for use
     const isAvailable = web3.isAvailable && isAuthenticated && !!accountAddress;
     /**
@@ -215,6 +229,32 @@ export function useTokenBalances(options) {
             clearInterval(intervalId);
         };
     }, [sdk, refreshInterval, isAvailable, loadBalances]);
+    // Wallet events refresh: listen for real-time blockchain events
+    // Refreshes on ANY wallet domain event (Transfer, TransferSingle, etc.)
+    // Debouncing prevents excessive API calls during rapid events
+    useEffect(() => {
+        if (!sdk || !refreshOnWalletEvents || !isAvailable)
+            return;
+        const unsubscribe = sdk.events.subscribe((event) => {
+            if (event.domain === 'wallet') {
+                // Debounce rapid events (batch transfers, etc.)
+                if (walletEventDebounceRef.current) {
+                    clearTimeout(walletEventDebounceRef.current);
+                }
+                walletEventDebounceRef.current = setTimeout(() => {
+                    console.log(`[useTokenBalances] Wallet event (${event.type}), refreshing balances...`);
+                    loadBalances();
+                    walletEventDebounceRef.current = null;
+                }, walletEventDebounceMs);
+            }
+        }, { domains: ['wallet'] });
+        return () => {
+            unsubscribe();
+            if (walletEventDebounceRef.current) {
+                clearTimeout(walletEventDebounceRef.current);
+            }
+        };
+    }, [sdk, refreshOnWalletEvents, walletEventDebounceMs, isAvailable, loadBalances]);
     return {
         tokenBalances,
         isLoading,

package/dist/hooks/useTransactions.d.ts

@@ -1,5 +1,7 @@
 import { OnStatusUpdateFn } from './useTransactionSigner';
-import type { TransactionRequestDTO, TransactionRequestResponseDTO, TransactionDTO, TransactionRole, TransactionPaginationRequestDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
+import type { TransactionRequestDTO, TransactionRequestResponseDTO, TransactionDTO, TransactionPaginationRequestDTO, PaginatedResponseDTO, TransactionIncludeRelation } from '@explorins/pers-shared';
+import type { TransactionQueryOptions } from '@explorins/pers-sdk/transaction';
+export type { TransactionQueryOptions } from '@explorins/pers-sdk/transaction';
 /**
  * React hook for transaction operations in the PERS SDK
  *
@@ -38,10 +40,11 @@ import type { TransactionRequestDTO, TransactionRequestResponseDTO, TransactionD
  */
 export declare const useTransactions: () => {
     createTransaction: (request: TransactionRequestDTO, onStatusUpdate?: OnStatusUpdateFn) => Promise<TransactionRequestResponseDTO>;
-    getTransactionById: (transactionId: string) => Promise<TransactionDTO | null>;
-    getUserTransactionHistory: (role?: TransactionRole) => Promise<PaginatedResponseDTO<TransactionDTO>>;
-    getTenantTransactions: () => Promise<PaginatedResponseDTO<TransactionDTO>>;
-    getPaginatedTransactions: (params: TransactionPaginationRequestDTO) => Promise<any>;
+    getTransactionById: (transactionId: string, include?: TransactionIncludeRelation[]) => Promise<TransactionDTO | null>;
+    getUserTransactionHistory: (options?: TransactionQueryOptions) => Promise<PaginatedResponseDTO<TransactionDTO>>;
+    getPaginatedTransactions: (options: TransactionPaginationRequestDTO & {
+        include?: TransactionIncludeRelation[];
+    }) => Promise<PaginatedResponseDTO<TransactionDTO>>;
     exportTransactionsCSV: () => Promise<Blob>;
     isAvailable: boolean;
     signingStatus: import("@explorins/pers-signer").SigningStatus | null;

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

@@ -1 +1 @@
-{"version":3,"file":"useTransactions.d.ts","sourceRoot":"","sources":["../../src/hooks/useTransactions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwB,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,KAAK,EACV,qBAAqB,EACrB,6BAA6B,EAC7B,cAAc,EACd,eAAe,EACf,+BAA+B,EAC/B,oBAAoB,EACrB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,eAAe;iCAgC4B,qBAAqB,mBAAmB,gBAAgB,KAAG,QAAQ,6BAA6B,CAAC;wCA2D1F,MAAM,KAAG,QAAQ,cAAc,GAAG,IAAI,CAAC;uCA4BxC,eAAe,KAAG,QAAQ,qBAAqB,cAAc,CAAC,CAAC;iCAevE,QAAQ,qBAAqB,cAAc,CAAC,CAAC;uCAcrC,+BAA+B,KAAG,QAAQ,GAAG,CAAC;iCActD,QAAQ,IAAI,CAAC;;;;CA0BlE,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC"}
+{"version":3,"file":"useTransactions.d.ts","sourceRoot":"","sources":["../../src/hooks/useTransactions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwB,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,KAAK,EACV,qBAAqB,EACrB,6BAA6B,EAC7B,cAAc,EACd,+BAA+B,EAC/B,oBAAoB,EACpB,0BAA0B,EAC3B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAG/E,YAAY,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,eAAe;iCAgC4B,qBAAqB,mBAAmB,gBAAgB,KAAG,QAAQ,6BAA6B,CAAC;wCAmEtI,MAAM,YACX,0BAA0B,EAAE,KACrC,QAAQ,cAAc,GAAG,IAAI,CAAC;0CAoDrB,uBAAuB,KAChC,QAAQ,qBAAqB,cAAc,CAAC,CAAC;wCA2CrC,+BAA+B,GAAG;QACzC,OAAO,CAAC,EAAE,0BAA0B,EAAE,CAAC;KACxC,KACA,QAAQ,qBAAqB,cAAc,CAAC,CAAC;iCAcI,QAAQ,IAAI,CAAC;;;;CAyBlE,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC"}