@explorins/pers-sdk-react-native 1.5.36 → 2.0.1

package/README.md

@@ -331,8 +331,189 @@ const {
 const {
   getDonationTypes
 } = useDonations();
+
+// Event subscriptions (notifications, logging)
+const {
+  subscribe,        // Subscribe to SDK events
+  once,             // One-time event listener
+  clear,            // Clear all subscriptions
+  isAvailable,      // Event system available
+  subscriberCount   // Active subscriber count
+} = useEvents();
 ```
 
+## Event System
+
+The `useEvents` hook provides access to SDK-wide events for showing notifications, logging, and reacting to SDK operations. All events include a `userMessage` field ready for UI display.
+
+### Basic Usage
+
+```typescript
+import { useEvents } from '@explorins/pers-sdk-react-native';
+import { useEffect } from 'react';
+
+function NotificationHandler() {
+  const { subscribe, isAvailable } = useEvents();
+  
+  useEffect(() => {
+    if (!isAvailable) return;
+    
+    // Subscribe to all events
+    const unsubscribe = subscribe((event) => {
+      showNotification(event.userMessage, event.level);
+    });
+    
+    return () => unsubscribe();  // Cleanup on unmount
+  }, [subscribe, isAvailable]);
+}
+```
+
+### Filtering Events
+
+```typescript
+// Only transaction successes
+subscribe(
+  (event) => {
+    playSuccessSound();
+    showConfetti();
+  },
+  { domain: 'transaction', level: 'success' }
+);
+
+// Only errors (for logging)
+subscribe(
+  (event) => {
+    logToSentry(event);
+  },
+  { level: 'error' }
+);
+
+// One-time event (auto-unsubscribes)
+once(
+  (event) => {
+    console.log('First transaction completed!');
+  },
+  { domain: 'transaction', level: 'success' }
+);
+```
+
+### Event Domains
+
+| Domain | Events |
+|--------|--------|
+| `auth` | Login, logout, token refresh |
+| `user` | Profile updates |
+| `transaction` | Created, completed, failed |
+| `campaign` | Claimed, activated |
+| `redemption` | Redeemed, expired |
+| `business` | Created, updated, membership |
+| `api` | Network errors, validation errors |
+
+### Event Structure
+
+```typescript
+interface PersEvent {
+  id: string;           // Unique event ID
+  timestamp: number;    // Unix timestamp (ms)
+  domain: string;       // Event domain (transaction, auth, etc.)
+  type: string;         // Event type within domain
+  level: 'success' | 'error';
+  userMessage: string;  // Ready for UI display
+  action?: string;      // Suggested action
+  details?: object;     // Additional data
+}
+```
+
+---
+
+## POS Transaction Flow
+
+For Point-of-Sale scenarios where a **business submits a transaction on behalf of a user**, use the `buildPOSTransferRequest` helper:
+
+```typescript
+import { 
+  useTransactions, 
+  buildPOSTransferRequest,
+  useEvents 
+} from '@explorins/pers-sdk-react-native';
+
+function POSScreen() {
+  const { createTransaction, signingStatus } = useTransactions();
+  const { subscribe, isAvailable } = useEvents();
+  
+  // Listen for transaction events
+  useEffect(() => {
+    if (!isAvailable) return;
+    
+    const unsubscribe = subscribe(
+      (event) => {
+        if (event.level === 'success') {
+          Alert.alert('Success', event.userMessage);
+        }
+      },
+      { domain: 'transaction' }
+    );
+    
+    return () => unsubscribe();
+  }, [subscribe, isAvailable]);
+  
+  const handlePOSTransaction = async (
+    userAccountId: string,
+    businessAccountId: string,
+    amount: number,
+    token: TokenDTO
+  ) => {
+    // Build POS transfer request
+    const request = buildPOSTransferRequest({
+      amount,
+      contractAddress: token.contractAddress,
+      chainId: token.chainId,
+      userAccountId,      // User sending tokens
+      businessAccountId   // Business receiving & authorized to submit
+    });
+    
+    // Create and sign transaction
+    const result = await createTransaction(request, (status, message) => {
+      console.log(`Signing: ${status} - ${message}`);
+    });
+    
+    console.log('Transaction created:', result.transaction?.id);
+  };
+}
+```
+
+### POS Authorization Fields
+
+The `buildPOSTransferRequest` helper automatically sets:
+
+| Field | Value | Purpose |
+|-------|-------|---------|
+| `engagedBusinessId` | Business ID | Business commercially involved (for reporting) |
+| `authorizedSubmitterId` | Business ID | Entity authorized to submit the signed tx |
+| `authorizedSubmitterType` | `BUSINESS` | Type of authorized submitter |
+
+For custom scenarios, use `buildTransferRequest` with manual POS fields:
+
+```typescript
+import { buildTransferRequest, AccountOwnerType } from '@explorins/pers-sdk-react-native';
+
+const request = buildTransferRequest({
+  amount: 100,
+  contractAddress: '0x...',
+  chainId: 137,
+  senderAccountId: 'user-123',
+  senderAccountType: AccountOwnerType.USER,
+  recipientAccountId: 'business-456',
+  recipientAccountType: AccountOwnerType.BUSINESS,
+  // POS authorization
+  engagedBusinessId: 'business-456',
+  authorizedSubmitterId: 'business-456',
+  authorizedSubmitterType: AccountOwnerType.BUSINESS
+});
+```
+
+---
+
 ## Token Collection Helper Methods
 
 The `useWeb3` hook includes helper methods for querying token balances from any blockchain address. These work with **all token standards** (ERC-20, ERC-721, ERC-1155).
@@ -598,6 +779,154 @@ function AnalyticsExample() {
 }
 ```
 
+## Migration Guide
+
+### v2.0.0 Breaking Changes - Pagination
+
+**Version 2.0.0 introduces standardized pagination** across all hooks that return lists. Previously, hooks returned raw arrays. Now they return `PaginatedResponseDTO<T>` with pagination metadata.
+
+#### What Changed
+
+All hooks returning lists now return paginated responses:
+
+```typescript
+// ❌ OLD (v1.x) - Direct array
+const businesses: BusinessDTO[] = await getActiveBusinesses();
+
+// ✅ NEW (v2.x) - Paginated response
+const response: PaginatedResponseDTO<BusinessDTO> = await getActiveBusinesses();
+const businesses: BusinessDTO[] = response.data;
+```
+
+#### Affected Hooks
+
+| Hook | Method | Return Type |
+|------|--------|-------------|
+| `useBusiness` | `getActiveBusinesses()` | `PaginatedResponseDTO<BusinessDTO>` |
+| `useBusiness` | `getBusinessTypes()` | `PaginatedResponseDTO<BusinessTypeDTO>` |
+| `useCampaigns` | `getActiveCampaigns()` | `PaginatedResponseDTO<CampaignDTO>` |
+| `useCampaigns` | `getUserClaims()` | `PaginatedResponseDTO<CampaignClaimDTO>` |
+| `useTokens` | `getTokens()` | `PaginatedResponseDTO<TokenDTO>` |
+| `useTokens` | `getRewardTokens()` | `PaginatedResponseDTO<TokenDTO>` |
+| `useTokens` | `getStatusTokens()` | `PaginatedResponseDTO<TokenDTO>` |
+| `useRedemptions` | `getActiveRedemptions()` | `PaginatedResponseDTO<RedemptionDTO>` |
+| `useRedemptions` | `getUserRedemptions()` | `PaginatedResponseDTO<RedemptionDTO>` |
+| `useTransactions` | `getUserTransactionHistory()` | `PaginatedResponseDTO<TransactionDTO>` |
+| `usePurchases` | `getAllUserPurchases()` | `PaginatedResponseDTO<PurchaseDTO>` |
+| `usePurchases` | `getActivePurchaseTokens()` | `PaginatedResponseDTO<PurchaseTokenDTO>` |
+| `useDonations` | `getDonationTypes()` | `PaginatedResponseDTO<DonationTypeDTO>` |
+
+#### PaginatedResponseDTO Structure
+
+```typescript
+import type { PaginatedResponseDTO } from '@explorins/pers-shared';
+
+interface PaginatedResponseDTO<T> {
+  data: T[];              // Array of results
+  pagination: {
+    currentPage: number;  // Current page number (1-indexed)
+    pageSize: number;     // Items per page
+    totalItems: number;   // Total number of items across all pages
+    totalPages: number;   // Total number of pages
+  };
+}
+```
+
+#### Migration Examples
+
+**Before (v1.x):**
+```typescript
+const businesses = await getActiveBusinesses();
+console.log('Business count:', businesses.length);
+businesses.forEach(b => console.log(b.name));
+```
+
+**After (v2.x):**
+```typescript
+const response = await getActiveBusinesses();
+console.log('Business count:', response.data.length);
+console.log('Total businesses:', response.pagination.totalItems);
+response.data.forEach(b => console.log(b.name));
+```
+
+**With Pagination Parameters:**
+```typescript
+// Fetch page 2 with 20 items per page
+const response = await getActiveBusinesses({ page: 2, pageSize: 20 });
+
+console.log(`Page ${response.pagination.currentPage} of ${response.pagination.totalPages}`);
+console.log(`Showing ${response.data.length} businesses`);
+```
+
+#### React Native Component Example
+
+```typescript
+import { useState, useEffect } from 'react';
+import { useBusiness } from '@explorins/pers-sdk-react-native';
+import { View, Text, FlatList, ActivityIndicator } from 'react-native';
+
+function BusinessListScreen() {
+  const { getActiveBusinesses } = useBusiness();
+  const [businesses, setBusinesses] = useState<BusinessDTO[]>([]);
+  const [pagination, setPagination] = useState(null);
+  const [loading, setLoading] = useState(true);
+  
+  useEffect(() => {
+    loadBusinesses();
+  }, []);
+  
+  const loadBusinesses = async (page = 1) => {
+    try {
+      setLoading(true);
+      const response = await getActiveBusinesses({ page, pageSize: 20 });
+      setBusinesses(response.data);
+      setPagination(response.pagination);
+    } catch (error) {
+      console.error('Failed to load businesses:', error);
+    } finally {
+      setLoading(false);
+    }
+  };
+  
+  if (loading) return <ActivityIndicator />;
+  
+  return (
+    <View>
+      <Text>
+        Showing {businesses.length} of {pagination?.totalItems} businesses
+      </Text>
+      <FlatList
+        data={businesses}
+        keyExtractor={(item) => item.id}
+        renderItem={({ item }) => <BusinessCard business={item} />}
+      />
+      <Text>Page {pagination?.currentPage} of {pagination?.totalPages}</Text>
+    </View>
+  );
+}
+```
+
+#### Quick Fix for Existing Code
+
+If you want minimal code changes, extract `.data` immediately:
+
+```typescript
+// Quick adaptation in your hooks
+const businesses = (await getActiveBusinesses()).data;
+const campaigns = (await getActiveCampaigns()).data;
+const tokens = (await getTokens()).data;
+```
+
+#### Benefits of Pagination
+
+- **Performance**: Load only what you need, not entire datasets
+- **Consistency**: All list endpoints follow the same pattern
+- **Metadata**: Access total counts without loading all items
+- **Better UX**: Build proper pagination UI components
+- **Memory Efficiency**: Reduced memory footprint for large datasets
+
+---
+
 ## Contributing
 
 We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

package/dist/hooks/index.d.ts

@@ -13,7 +13,9 @@ export { useUserStatus } from './useUserStatus';
 export { useFiles } from './useFiles';
 export { useAnalytics } from './useAnalytics';
 export { useDonations } from './useDonations';
+export { useEvents } from './useEvents';
 export type { RawUserData } from './useAuth';
 export type { TransactionSignerHook, SubmissionResult, AuthenticatedUser, TransactionSigningResult, StatusUpdateData, OnStatusUpdateFn, SigningStatus as SigningStatusType } from './useTransactionSigner';
 export type { AccountOwnedTokensResult, Web3Hook } from './useWeb3';
+export type { EventsHook, PersEvent, EventHandler, EventFilter, Unsubscribe } from './useEvents';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,IAAI,iBAAiB,EACnC,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,IAAI,iBAAiB,EACnC,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/hooks/index.js

@@ -14,3 +14,4 @@ export { useUserStatus } from './useUserStatus';
 export { useFiles } from './useFiles';
 export { useAnalytics } from './useAnalytics';
 export { useDonations } from './useDonations';
+export { useEvents } from './useEvents';

package/dist/hooks/useBusiness.d.ts

@@ -1,4 +1,4 @@
-import type { BusinessDTO, BusinessTypeDTO, BusinessUpdateRequestDTO, BusinessToggleActiveRequestDTO } from '@explorins/pers-shared';
+import type { BusinessDTO, BusinessTypeDTO, BusinessUpdateRequestDTO, BusinessToggleActiveRequestDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
 /**
  * React hook for business operations in the PERS SDK
  *
@@ -34,12 +34,12 @@ import type { BusinessDTO, BusinessTypeDTO, BusinessUpdateRequestDTO, BusinessTo
  * ```
  */
 export declare const useBusiness: () => {
-    getActiveBusinesses: () => Promise<BusinessDTO[]>;
-    getBusinessTypes: () => Promise<BusinessTypeDTO[]>;
-    getBusinesses: () => Promise<BusinessDTO[]>;
+    getActiveBusinesses: () => Promise<PaginatedResponseDTO<BusinessDTO>>;
+    getBusinessTypes: () => Promise<PaginatedResponseDTO<BusinessTypeDTO>>;
+    getBusinesses: () => Promise<PaginatedResponseDTO<BusinessDTO>>;
     getBusinessById: (businessId: string) => Promise<BusinessDTO | null>;
     getBusinessByAccount: (accountAddress: string) => Promise<BusinessDTO>;
-    getBusinessesByType: (typeId: string) => Promise<BusinessDTO[]>;
+    getBusinessesByType: (typeId: string) => Promise<PaginatedResponseDTO<BusinessDTO>>;
     createBusiness: (displayName: string) => Promise<BusinessDTO>;
     updateBusiness: (businessId: string, businessData: BusinessUpdateRequestDTO) => Promise<BusinessDTO>;
     toggleBusinessStatus: (businessId: string, toggleData: BusinessToggleActiveRequestDTO) => Promise<BusinessDTO>;

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

@@ -1 +1 @@
-{"version":3,"file":"useBusiness.d.ts","sourceRoot":"","sources":["../../src/hooks/useBusiness.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,wBAAwB,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAErI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,WAAW;+BAgB4B,QAAQ,WAAW,EAAE,CAAC;4BA2BzB,QAAQ,eAAe,EAAE,CAAC;yBA4B7B,QAAQ,WAAW,EAAE,CAAC;kCAdX,MAAM,KAAG,QAAQ,WAAW,GAAG,IAAI,CAAC;2CA4B3B,MAAM,KAAG,QAAQ,WAAW,CAAC;kCActC,MAAM,KAAG,QAAQ,WAAW,EAAE,CAAC;kCA6B/B,MAAM,KAAG,QAAQ,WAAW,CAAC;iCAc9B,MAAM,gBAAgB,wBAAwB,KAAG,QAAQ,WAAW,CAAC;uCAc/D,MAAM,cAAc,8BAA8B,KAAG,QAAQ,WAAW,CAAC;;CA0BtI,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC"}
+{"version":3,"file":"useBusiness.d.ts","sourceRoot":"","sources":["../../src/hooks/useBusiness.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,wBAAwB,EAAE,8BAA8B,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE3J;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,WAAW;+BAgB4B,QAAQ,qBAAqB,WAAW,CAAC,CAAC;4BA2B7C,QAAQ,qBAAqB,eAAe,CAAC,CAAC;yBA4BjD,QAAQ,qBAAqB,WAAW,CAAC,CAAC;kCAd/B,MAAM,KAAG,QAAQ,WAAW,GAAG,IAAI,CAAC;2CA4B3B,MAAM,KAAG,QAAQ,WAAW,CAAC;kCActC,MAAM,KAAG,QAAQ,qBAAqB,WAAW,CAAC,CAAC;kCA6BnD,MAAM,KAAG,QAAQ,WAAW,CAAC;iCAc9B,MAAM,gBAAgB,wBAAwB,KAAG,QAAQ,WAAW,CAAC;uCAc/D,MAAM,cAAc,8BAA8B,KAAG,QAAQ,WAAW,CAAC;;CA0BtI,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC"}

package/dist/hooks/useCampaigns.d.ts

@@ -1,14 +1,14 @@
-import type { CampaignClaimRequestDTO, CampaignDTO, CampaignClaimDTO, CampaignTriggerDTO } from '@explorins/pers-shared';
+import type { CampaignClaimRequestDTO, CampaignDTO, CampaignClaimDTO, CampaignTriggerDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
 export declare const useCampaigns: () => {
-    getActiveCampaigns: () => Promise<CampaignDTO[]>;
+    getActiveCampaigns: () => Promise<PaginatedResponseDTO<CampaignDTO>>;
     getCampaignById: (campaignId: string) => Promise<CampaignDTO | null>;
     claimCampaign: (request: CampaignClaimRequestDTO) => Promise<CampaignClaimDTO | null>;
-    getUserClaims: () => Promise<CampaignClaimDTO[]>;
-    getCampaignTriggers: () => Promise<CampaignTriggerDTO[]>;
-    getAllCampaigns: (active?: boolean) => Promise<CampaignDTO[]>;
-    getCampaignClaims: () => Promise<CampaignClaimDTO[]>;
-    getCampaignClaimsByUserId: (userId: string) => Promise<CampaignClaimDTO[]>;
-    getCampaignClaimsByBusinessId: (businessId: string) => Promise<CampaignClaimDTO[]>;
+    getUserClaims: () => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
+    getCampaignTriggers: () => Promise<PaginatedResponseDTO<CampaignTriggerDTO>>;
+    getAllCampaigns: (active?: boolean) => Promise<PaginatedResponseDTO<CampaignDTO>>;
+    getCampaignClaims: () => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
+    getCampaignClaimsByUserId: (userId: string) => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
+    getCampaignClaimsByBusinessId: (businessId: string) => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
     isAvailable: boolean;
 };
 export type CampaignHook = ReturnType<typeof useCampaigns>;

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

@@ -1 +1 @@
-{"version":3,"file":"useCampaigns.d.ts","sourceRoot":"","sources":["../../src/hooks/useCampaigns.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,uBAAuB,EACvB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAInB,MAAM,wBAAwB,CAAC;AAEhC,eAAO,MAAM,YAAY;8BAG0B,QAAQ,WAAW,EAAE,CAAC;kCAchB,MAAM,KAAG,QAAQ,WAAW,GAAG,IAAI,CAAC;6BAczC,uBAAuB,KAAG,QAAQ,gBAAgB,GAAG,IAAI,CAAC;yBAiBhE,QAAQ,gBAAgB,EAAE,CAAC;+BAkBrB,QAAQ,kBAAkB,EAAE,CAAC;+BAe3B,OAAO,KAAG,QAAQ,WAAW,EAAE,CAAC;6BAcpC,QAAQ,gBAAgB,EAAE,CAAC;wCAcd,MAAM,KAAG,QAAQ,gBAAgB,EAAE,CAAC;gDAc5B,MAAM,KAAG,QAAQ,gBAAgB,EAAE,CAAC;;CA0B1G,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC"}
+{"version":3,"file":"useCampaigns.d.ts","sourceRoot":"","sources":["../../src/hooks/useCampaigns.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,uBAAuB,EACvB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAIlB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC;AAEhC,eAAO,MAAM,YAAY;8BAG0B,QAAQ,qBAAqB,WAAW,CAAC,CAAC;kCAcpC,MAAM,KAAG,QAAQ,WAAW,GAAG,IAAI,CAAC;6BAczC,uBAAuB,KAAG,QAAQ,gBAAgB,GAAG,IAAI,CAAC;yBAiBhE,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;+BAkBzC,QAAQ,qBAAqB,kBAAkB,CAAC,CAAC;+BAe/C,OAAO,KAAG,QAAQ,qBAAqB,WAAW,CAAC,CAAC;6BAcxD,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;wCAclC,MAAM,KAAG,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;gDAchD,MAAM,KAAG,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;;CA0B9H,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC"}

package/dist/hooks/useCampaigns.js

@@ -7,7 +7,7 @@ export const useCampaigns = () => {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.campaigns.getActiveCampaigns();
+            const result = await sdk.campaigns.getCampaigns({ active: true });
             return result;
         }
         catch (error) {
@@ -50,7 +50,7 @@ export const useCampaigns = () => {
         }
         if (!isAuthenticated) {
             console.warn('SDK not authenticated. getUserClaims requires authentication.');
-            return [];
+            return { data: [], pagination: { page: 1, limit: 0, total: 0, pages: 0, hasNext: false, hasPrev: false } };
         }
         try {
             const result = await sdk.campaigns.getUserClaims();
@@ -80,7 +80,7 @@ export const useCampaigns = () => {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.campaigns.getAllCampaigns(active);
+            const result = await sdk.campaigns.getCampaigns({ active });
             return result;
         }
         catch (error) {

package/dist/hooks/useDonations.d.ts

@@ -1,4 +1,4 @@
-import type { DonationTypeDTO } from '@explorins/pers-shared';
+import type { DonationTypeDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
 /**
  * React hook for donation operations in the PERS SDK
  *
@@ -26,7 +26,7 @@ import type { DonationTypeDTO } from '@explorins/pers-shared';
  * ```
  */
 export declare const useDonations: () => {
-    getDonationTypes: () => Promise<DonationTypeDTO[]>;
+    getDonationTypes: () => Promise<PaginatedResponseDTO<DonationTypeDTO>>;
     isAvailable: boolean;
 };
 export type DonationHook = ReturnType<typeof useDonations>;

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

@@ -1 +1 @@
-{"version":3,"file":"useDonations.d.ts","sourceRoot":"","sources":["../../src/hooks/useDonations.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,YAAY;4BAgBwB,QAAQ,eAAe,EAAE,CAAC;;CAkB1E,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC"}
+{"version":3,"file":"useDonations.d.ts","sourceRoot":"","sources":["../../src/hooks/useDonations.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,YAAY;4BAgBwB,QAAQ,qBAAqB,eAAe,CAAC,CAAC;;CAkB9F,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC"}

package/dist/hooks/useEvents.d.ts

@@ -0,0 +1,178 @@
+import type { PersEvent, EventHandler, EventFilter, Unsubscribe } from '@explorins/pers-sdk/core';
+export type { PersEvent, EventHandler, EventFilter, Unsubscribe };
+/**
+ * Return interface for the useEvents hook
+ *
+ * Provides event subscription capabilities for the PERS SDK event system.
+ * Use this to display notifications, update UI, or trigger side effects.
+ *
+ * @interface EventsHook
+ * @property {Function} subscribe - Subscribe to SDK events with optional filtering
+ * @property {Function} once - Subscribe to a single event (auto-unsubscribes)
+ * @property {Function} clear - Clear all subscriptions
+ * @property {boolean} isAvailable - Whether the event system is available
+ * @property {number} subscriberCount - Current number of active subscribers
+ */
+export interface EventsHook {
+    subscribe: (handler: EventHandler, filter?: EventFilter) => Unsubscribe;
+    once: (handler: EventHandler, filter?: EventFilter) => Unsubscribe;
+    clear: () => void;
+    isAvailable: boolean;
+    subscriberCount: number;
+}
+/**
+ * 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.
+ *
+ * **Event Domains:**
+ * - `auth` - Authentication events (login, logout, token refresh)
+ * - `user` - User profile events (update, create)
+ * - `transaction` - Transaction events (created, completed, failed)
+ * - `campaign` - Campaign events (claimed, activated)
+ * - `redemption` - Redemption events (redeemed, expired)
+ * - `business` - Business events (created, updated, membership)
+ * - `api` - API error events (network, validation, server errors)
+ *
+ * **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
+ * the component unmounts, preventing memory leaks and stale event handlers.
+ *
+ * @returns {EventsHook} Hook interface with event subscription methods
+ *
+ * @example
+ * **Basic Usage - Show All Notifications**
+ * ```typescript
+ * import { useEvents } from '@explorins/pers-sdk-react-native';
+ *
+ * function NotificationComponent() {
+ *   const { subscribe, isAvailable } = useEvents();
+ *
+ *   useEffect(() => {
+ *     if (!isAvailable) return;
+ *
+ *     const unsubscribe = subscribe((event) => {
+ *       // userMessage is always present and UI-ready
+ *       showNotification(event.userMessage, event.level);
+ *     });
+ *
+ *     return () => unsubscribe();
+ *   }, [subscribe, isAvailable]);
+ *
+ *   return <View />;
+ * }
+ * ```
+ *
+ * @example
+ * **Filter by Domain and Level**
+ * ```typescript
+ * function TransactionListener() {
+ *   const { subscribe, isAvailable } = useEvents();
+ *
+ *   useEffect(() => {
+ *     if (!isAvailable) return;
+ *
+ *     // Only listen to successful transactions
+ *     const unsubscribe = subscribe(
+ *       (event) => {
+ *         if (event.level === 'success') {
+ *           playSuccessSound();
+ *           showConfetti();
+ *         }
+ *       },
+ *       { domain: 'transaction' }  // Filter
+ *     );
+ *
+ *     return () => unsubscribe();
+ *   }, [subscribe, isAvailable]);
+ * }
+ * ```
+ *
+ * @example
+ * **Filter Errors for Logging**
+ * ```typescript
+ * function ErrorLogger() {
+ *   const { subscribe, isAvailable } = useEvents();
+ *
+ *   useEffect(() => {
+ *     if (!isAvailable) return;
+ *
+ *     const unsubscribe = subscribe(
+ *       (event) => {
+ *         // Log errors to crash reporting
+ *         logToSentry({
+ *           message: event.userMessage,
+ *           domain: event.domain,
+ *           type: event.type,
+ *         });
+ *       },
+ *       { level: 'error' }  // Only errors
+ *     );
+ *
+ *     return () => unsubscribe();
+ *   }, [subscribe, isAvailable]);
+ * }
+ * ```
+ *
+ * @example
+ * **One-time Event**
+ * ```typescript
+ * function FirstTransactionHandler() {
+ *   const { once, isAvailable } = useEvents();
+ *
+ *   useEffect(() => {
+ *     if (!isAvailable) return;
+ *
+ *     // Auto-unsubscribe after first transaction event
+ *     const unsubscribe = once(
+ *       (event) => {
+ *         console.log('First transaction event:', event.type);
+ *         showOnboardingComplete();
+ *       },
+ *       { domain: 'transaction', level: 'success' }
+ *     );
+ *
+ *     return () => unsubscribe();
+ *   }, [once, isAvailable]);
+ * }
+ * ```
+ *
+ * @example
+ * **Combined Domain and Level Filter**
+ * ```typescript
+ * function AuthErrorHandler() {
+ *   const { subscribe, isAvailable } = useEvents();
+ *
+ *   useEffect(() => {
+ *     if (!isAvailable) return;
+ *
+ *     const unsubscribe = subscribe(
+ *       (event) => {
+ *         Alert.alert('Authentication Error', event.userMessage);
+ *         navigation.navigate('Login');
+ *       },
+ *       { domain: 'auth', level: 'error' }
+ *     );
+ *
+ *     return () => unsubscribe();
+ *   }, [subscribe, isAvailable]);
+ * }
+ * ```
+ *
+ * @see {@link PersEvent} for event structure
+ * @see {@link EventFilter} for filtering options
+ * @see {@link EventHandler} for handler function type
+ *
+ * @since 1.6.49
+ */
+export declare const useEvents: () => EventsHook;
+export type EventsHook_ = ReturnType<typeof useEvents>;
+//# sourceMappingURL=useEvents.d.ts.map

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

@@ -0,0 +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"}