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

package/src/hooks/useRedemptions.ts

@@ -7,8 +7,13 @@ import type {
   RedemptionRedeemDTO, 
   RedemptionRedeemRequestResponseDTO,
   RedemptionTypeDTO,
-  PaginatedResponseDTO
+  PaginatedResponseDTO,
+  RedemptionRedeemIncludeRelation
 } from '@explorins/pers-shared';
+import type { RedemptionRedeemFilters } from '@explorins/pers-sdk/redemption';
+
+// Re-export for consumers
+export type { RedemptionRedeemFilters } from '@explorins/pers-sdk/redemption';
 
 export const useRedemptions = () => {
   const { sdk, isInitialized, isAuthenticated } = usePersSDK();
@@ -36,7 +41,25 @@ export const useRedemptions = () => {
     }
   }, [sdk, isInitialized]);
 
-  const getUserRedemptions = useCallback(async (): Promise<PaginatedResponseDTO<RedemptionRedeemDTO>> => {
+  /**
+   * 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?: RedemptionRedeemIncludeRelation[]
+  ): Promise<PaginatedResponseDTO<RedemptionRedeemDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
@@ -46,7 +69,7 @@ export const useRedemptions = () => {
     }
     
     try {
-      const result = await sdk.redemptions.getUserRedemptions();
+      const result = await sdk.redemptions.getUserRedemptions(undefined, include);
       return result;
     } catch (error) {
       console.error('Failed to fetch user redemptions:', error);
@@ -100,6 +123,45 @@ 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?: RedemptionRedeemFilters,
+    include?: RedemptionRedeemIncludeRelation[]
+  ): Promise<PaginatedResponseDTO<RedemptionRedeemDTO>> => {
+    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: RedemptionCreateRequestDTO): Promise<RedemptionDTO> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
@@ -161,6 +223,7 @@ export const useRedemptions = () => {
     getUserRedemptions,
     redeem,
     getRedemptionTypes,
+    getRedemptionRedeems,
     createRedemption,
     updateRedemption,
     toggleRedemptionStatus,

package/src/hooks/useTransactions.ts

@@ -5,10 +5,14 @@ import type {
   TransactionRequestDTO, 
   TransactionRequestResponseDTO, 
   TransactionDTO,
-  TransactionRole,
   TransactionPaginationRequestDTO,
-  PaginatedResponseDTO
+  PaginatedResponseDTO,
+  TransactionIncludeRelation
 } from '@explorins/pers-shared';
+import type { TransactionQueryOptions } from '@explorins/pers-sdk/transaction';
+
+// Re-export for consumers
+export type { TransactionQueryOptions } from '@explorins/pers-sdk/transaction';
 
 /**
  * React hook for transaction operations in the PERS SDK
@@ -124,26 +128,36 @@ export const useTransactions = () => {
   }, [sdk, isInitialized, signAndSubmitTransactionWithJWT, isSignerAvailable]);
 
   /**
-   * Retrieves a specific transaction by its ID
+   * Retrieves a specific transaction by its ID with optional include relations
    * 
    * @param transactionId - Unique identifier of the transaction
+   * @param include - Optional relations to include (sender, recipient, business) for enriched entity data
    * @returns Promise resolving to transaction data or null if not found
    * @throws Error if SDK is not initialized
    * 
    * @example
    * ```typescript
    * const { getTransactionById } = useTransactions();
+   * 
+   * // Basic retrieval
    * const transaction = await getTransactionById('txn-123');
-   * console.log('Transaction details:', transaction);
+   * 
+   * // With enriched sender/recipient data
+   * const enrichedTx = await getTransactionById('txn-123', ['sender', 'recipient', 'business']);
+   * console.log('Sender:', enrichedTx?.included?.sender);
+   * console.log('Business:', enrichedTx?.included?.engagedBusiness?.displayName);
    * ```
    */
-  const getTransactionById = useCallback(async (transactionId: string): Promise<TransactionDTO | null> => {
+  const getTransactionById = useCallback(async (
+    transactionId: string,
+    include?: TransactionIncludeRelation[]
+  ): Promise<TransactionDTO | null> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.transactions.getTransactionById(transactionId);
+      const result = await sdk.transactions.getTransactionById(transactionId, include);
       return result;
     } catch (error) {
       console.error('Failed to fetch transaction:', error);
@@ -152,27 +166,52 @@ export const useTransactions = () => {
   }, [sdk, isInitialized]);
 
   /**
-   * Retrieves transaction history for the authenticated user, filtered by role
+   * Retrieves transaction history for the authenticated user with comprehensive filtering
    * 
-   * @param role - Optional transaction role filter (TransactionRole.SENDER, TransactionRole.RECIPIENT)
-   * @returns Promise resolving to array of user's transactions
+   * Supports filtering by role, status, type, business, token, and more.
+   * Optionally enrich with related entities (sender, recipient, business).
+   * 
+   * @param options - Query options including filters, pagination, and include relations
+   * @returns Promise resolving to paginated array of user's transactions
    * @throws Error if SDK is not initialized
    * 
    * @example
    * ```typescript
    * const { getUserTransactionHistory } = useTransactions();
-   * const sentTransactions = await getUserTransactionHistory(TransactionRole.SENDER);
-   * const allTransactions = await getUserTransactionHistory(); // No filter
+   * 
+   * // Simple: Get all transactions
+   * const allTransactions = await getUserTransactionHistory();
+   * 
+   * // Filter by role (legacy support)
+   * const sentTransactions = await getUserTransactionHistory({ role: 'SENDER' });
+   * 
+   * // Advanced filtering with include relations
+   * const filtered = await getUserTransactionHistory({
+   *   role: 'SENDER',
+   *   status: 'COMPLETED',
+   *   engagedBusinessId: 'business-123',
+   *   include: ['recipient', 'business'],
+   *   page: 1,
+   *   limit: 20
+   * });
+   * 
+   * // Access enriched data
+   * filtered.data.forEach(tx => {
+   *   console.log('Recipient:', tx.included?.recipient);
+   *   console.log('Business:', tx.included?.engagedBusiness?.displayName);
+   * });
    * ```
    */
-  const getUserTransactionHistory = useCallback(async (role?: TransactionRole): Promise<PaginatedResponseDTO<TransactionDTO>> => {
+  const getUserTransactionHistory = useCallback(async (
+    options?: TransactionQueryOptions
+  ): Promise<PaginatedResponseDTO<TransactionDTO>> => {
     
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.transactions.getUserTransactionHistory(role);
+      const result = await sdk.transactions.getUserTransactionHistory(options);
       return result;
     } catch (error) {
       console.error('Failed to fetch transaction history:', error);
@@ -180,27 +219,44 @@ export const useTransactions = () => {
     }
   }, [sdk, isInitialized]);
 
-  const getTenantTransactions = useCallback(async (): Promise<PaginatedResponseDTO<TransactionDTO>> => {
-    if (!isInitialized || !sdk) {
-      throw new Error('SDK not initialized. Call initialize() first.');
-    }
-    
-    try {
-      const result = await sdk.transactions.getTenantTransactions();
-      return result;
-    } catch (error) {
-      console.error('Failed to fetch tenant transactions:', error);
-      throw error;
+  /**
+   * Admin: Get paginated transactions with optional include relations
+   * 
+   * @param params - Pagination and filtering parameters
+   * @param include - Optional relations to include for enriched entity data
+   * @returns Promise resolving to paginated transaction results
+   * @throws Error if SDK is not initialized
+   * 
+   * @example
+   * ```typescript
+   * const { getPaginatedTransactions } = useTransactions();
+   * 
+   * // Basic pagination
+   * const result = await getPaginatedTransactions({ page: 1, limit: 50 });
+   * 
+   * // With include relations
+   * const enrichedResult = await getPaginatedTransactions(
+   *   { page: 1, limit: 50, sortBy: 'createdAt', sortOrder: 'DESC' },
+   *   include: ['sender', 'recipient', 'business']
+   * });
+   * 
+   * enrichedResult.data.forEach(tx => {
+   *   console.log('From:', tx.included?.sender);
+   *   console.log('To:', tx.included?.recipient);
+   * });
+   * ```
+   */
+  const getPaginatedTransactions = useCallback(async (
+    options: TransactionPaginationRequestDTO & {
+      include?: TransactionIncludeRelation[];
     }
-  }, [sdk, isInitialized]);
-
-  const getPaginatedTransactions = useCallback(async (params: TransactionPaginationRequestDTO): Promise<any> => {
+  ): Promise<PaginatedResponseDTO<TransactionDTO>> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.transactions.getPaginatedTransactions(params);
+      const result = await sdk.transactions.getPaginatedTransactions(options);
       return result;
     } catch (error) {
       console.error('Failed to fetch paginated transactions:', error);
@@ -226,7 +282,6 @@ export const useTransactions = () => {
     createTransaction,
     getTransactionById,
     getUserTransactionHistory,
-    getTenantTransactions,
     getPaginatedTransactions,
     exportTransactionsCSV,
     isAvailable: isInitialized && !!sdk?.transactions,

package/src/hooks/useTriggerSources.ts

@@ -0,0 +1,301 @@
+import { useCallback } from 'react';
+import { usePersSDK } from '../providers/PersSDKProvider';
+import type { 
+  TriggerSourceDTO,
+  TriggerSourceCreateRequestDTO,
+  PaginatedResponseDTO
+} from '@explorins/pers-shared';
+import type { TriggerSourceQueryOptions } from '@explorins/pers-sdk/trigger-source';
+
+// Re-export for consumers
+export type { TriggerSourceQueryOptions } from '@explorins/pers-sdk/trigger-source';
+
+/**
+ * React hook for TriggerSource operations in the PERS SDK
+ * 
+ * Manages trigger sources which are physical or digital activation points for campaigns:
+ * - **QR_CODE**: Scannable QR codes at physical locations
+ * - **NFC_TAG**: NFC tap points for contactless interactions
+ * - **GPS_GEOFENCE**: Location-based triggers with radius detection
+ * - **API_WEBHOOK**: External system integration triggers
+ * - **TRANSACTION**: Purchase/payment based triggers
+ * 
+ * TriggerSources are standalone entities that can be created, managed, and then
+ * assigned to campaigns. This separation allows reuse across multiple campaigns.
+ * 
+ * **Admin Only**: All create, update, and delete operations require admin authentication.
+ * 
+ * @returns TriggerSource hook with CRUD operations
+ * 
+ * @example Basic TriggerSource Operations
+ * ```typescript
+ * function TriggerSourceManager() {
+ *   const { 
+ *     getAll, 
+ *     getById, 
+ *     create, 
+ *     update, 
+ *     remove 
+ *   } = useTriggerSources();
+ *   
+ *   // List all QR code trigger sources
+ *   const loadQRSources = async () => {
+ *     const { data: sources } = await getAll({ type: 'QR_CODE' });
+ *     console.log('QR Sources:', sources);
+ *   };
+ *   
+ *   // Create a new QR code for a store
+ *   const createStoreQR = async () => {
+ *     const source = await create({
+ *       type: 'QR_CODE',
+ *       name: 'Store Entrance QR',
+ *       description: 'Scan at the entrance',
+ *       businessId: 'business-123',
+ *       coordsLatitude: 47.6062,
+ *       coordsLongitude: -122.3321
+ *     });
+ *     console.log('Created:', source.id);
+ *   };
+ * }
+ * ```
+ * 
+ * @example GPS Geofence Trigger
+ * ```typescript
+ * const { create } = useTriggerSources();
+ * 
+ * // Create a GPS geofence around a location
+ * const geofence = await create({
+ *   type: 'GPS_GEOFENCE',
+ *   name: 'Downtown Area',
+ *   coordsLatitude: 47.6062,
+ *   coordsLongitude: -122.3321,
+ *   metadata: { radiusMeters: 100 }
+ * });
+ * ```
+ */
+export const useTriggerSources = () => {
+  const { sdk, isInitialized, isAuthenticated } = usePersSDK();
+
+  /**
+   * Get trigger sources with optional filters and pagination
+   * 
+   * Retrieves trigger sources (QR codes, NFC tags, GPS geofences, webhooks, etc.)
+   * that can be used to activate campaigns. Supports filtering by type, business,
+   * campaign association, and active status.
+   * 
+   * @param options - Filter and pagination options
+   * @returns Promise resolving to paginated trigger sources
+   * 
+   * @example
+   * ```typescript
+   * // Get all QR code trigger sources
+   * const { data: qrSources } = await getAll({ type: 'QR_CODE' });
+   * 
+   * // Get trigger sources for a specific business
+   * const { data: businessSources, pagination } = await getAll({
+   *   businessId: 'business-123',
+   *   active: true,
+   *   page: 1,
+   *   limit: 20
+   * });
+   * 
+   * // Get trigger sources assigned to a campaign
+   * const { data: campaignSources } = await getAll({
+   *   campaignId: 'campaign-456'
+   * });
+   * ```
+   */
+  const getAll = useCallback(async (
+    options?: TriggerSourceQueryOptions
+  ): Promise<PaginatedResponseDTO<TriggerSourceDTO>> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.triggerSources.getAll(options);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch trigger sources:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
+  /**
+   * Get trigger source by ID
+   * 
+   * Retrieves detailed information for a specific trigger source including
+   * its type, location, metadata, and configuration.
+   * 
+   * @param triggerSourceId - UUID of the trigger source
+   * @returns Promise resolving to trigger source details
+   * @throws {PersApiError} When trigger source with specified ID is not found
+   * 
+   * @example
+   * ```typescript
+   * const source = await getById('source-123');
+   * 
+   * console.log('Trigger Source:', source.name);
+   * console.log('Type:', source.type);
+   * console.log('Active:', source.isActive);
+   * 
+   * if (source.coordsLatitude && source.coordsLongitude) {
+   *   console.log('Location:', source.coordsLatitude, source.coordsLongitude);
+   * }
+   * ```
+   */
+  const getById = useCallback(async (
+    triggerSourceId: string
+  ): Promise<TriggerSourceDTO> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const result = await sdk.triggerSources.getById(triggerSourceId);
+      return result;
+    } catch (error) {
+      console.error('Failed to fetch trigger source:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized]);
+
+  /**
+   * Admin: Create a new trigger source
+   * 
+   * Creates a new trigger source (QR code, NFC tag, GPS geofence, webhook, or
+   * transaction-based trigger) that can be assigned to campaigns. Requires
+   * administrator privileges.
+   * 
+   * @param triggerSource - Trigger source creation data
+   * @returns Promise resolving to created trigger source
+   * @throws {PersApiError} When not authenticated as admin or validation fails
+   * 
+   * @example
+   * ```typescript
+   * // Create a QR code trigger source
+   * const qrSource = await create({
+   *   type: 'QR_CODE',
+   *   name: 'Store Entrance QR',
+   *   description: 'QR code at main entrance',
+   *   businessId: 'business-123',
+   *   coordsLatitude: 47.6062,
+   *   coordsLongitude: -122.3321
+   * });
+   * 
+   * // Create an NFC tag trigger source
+   * const nfcSource = await create({
+   *   type: 'NFC_TAG',
+   *   name: 'Product Display NFC',
+   *   metadata: { productId: 'SKU-12345' }
+   * });
+   * ```
+   */
+  const create = useCallback(async (
+    triggerSource: TriggerSourceCreateRequestDTO
+  ): Promise<TriggerSourceDTO> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    if (!isAuthenticated) {
+      throw new Error('SDK not authenticated. create requires admin authentication.');
+    }
+    
+    try {
+      const result = await sdk.triggerSources.create(triggerSource);
+      return result;
+    } catch (error) {
+      console.error('Failed to create trigger source:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized, isAuthenticated]);
+
+  /**
+   * Admin: Update a trigger source
+   * 
+   * Updates an existing trigger source's configuration. All fields are optional;
+   * only provided fields will be updated. Requires administrator privileges.
+   * 
+   * @param triggerSourceId - UUID of the trigger source to update
+   * @param triggerSource - Updated trigger source data (partial)
+   * @returns Promise resolving to updated trigger source
+   * @throws {PersApiError} When not authenticated as admin or trigger source not found
+   * 
+   * @example
+   * ```typescript
+   * // Update trigger source name and location
+   * const updated = await update('source-123', {
+   *   name: 'Updated Store Entrance QR',
+   *   description: 'New description',
+   *   coordsLatitude: 47.6063,
+   *   coordsLongitude: -122.3322
+   * });
+   * ```
+   */
+  const update = useCallback(async (
+    triggerSourceId: string,
+    triggerSource: Partial<TriggerSourceCreateRequestDTO>
+  ): Promise<TriggerSourceDTO> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    if (!isAuthenticated) {
+      throw new Error('SDK not authenticated. update requires admin authentication.');
+    }
+    
+    try {
+      const result = await sdk.triggerSources.update(triggerSourceId, triggerSource);
+      return result;
+    } catch (error) {
+      console.error('Failed to update trigger source:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized, isAuthenticated]);
+
+  /**
+   * Admin: Delete a trigger source
+   * 
+   * Soft deletes a trigger source, making it inactive. The trigger source will
+   * be removed from any campaigns it was assigned to. Requires administrator
+   * privileges.
+   * 
+   * @param triggerSourceId - UUID of the trigger source to delete
+   * @returns Promise resolving to success status
+   * @throws {PersApiError} When not authenticated as admin or trigger source not found
+   * 
+   * @example
+   * ```typescript
+   * const success = await remove('source-123');
+   * console.log('Trigger source deleted:', success);
+   * ```
+   */
+  const remove = useCallback(async (
+    triggerSourceId: string
+  ): Promise<boolean> => {
+    if (!isInitialized || !sdk) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    if (!isAuthenticated) {
+      throw new Error('SDK not authenticated. remove requires admin authentication.');
+    }
+    
+    try {
+      const result = await sdk.triggerSources.delete(triggerSourceId);
+      return result;
+    } catch (error) {
+      console.error('Failed to delete trigger source:', error);
+      throw error;
+    }
+  }, [sdk, isInitialized, isAuthenticated]);
+
+  return {
+    getAll,
+    getById,
+    create,
+    update,
+    remove,
+    isAvailable: isInitialized && !!sdk?.triggerSources,
+  };
+};
+
+export type TriggerSourceHook = ReturnType<typeof useTriggerSources>;

package/src/index.ts

@@ -262,11 +262,20 @@ export {
   useFiles,
   useAnalytics,
   useDonations,
-  useEvents
+  useEvents,
+  useTriggerSources
 } from './hooks';
 
 // Re-export signing status types for convenience
-export type { OnStatusUpdateFn, StatusUpdateData, SigningStatusType, TransactionSigningResult, SubmissionResult, AuthenticatedUser } from './hooks';
+export type { 
+  TransactionSignerHook,
+  OnStatusUpdateFn, 
+  StatusUpdateData, 
+  SigningStatusType, 
+  TransactionSigningResult, 
+  SubmissionResult, 
+  AuthenticatedUser 
+} from './hooks';
 
 // Re-export event types for convenience
 export type { EventsHook, PersEvent, EventHandler, EventFilter, Unsubscribe } from './hooks';
@@ -274,6 +283,21 @@ export type { EventsHook, PersEvent, EventHandler, EventFilter, Unsubscribe } fr
 // Re-export token balance types for convenience
 export type { TokenBalanceWithToken, UseTokenBalancesOptions, UseTokenBalancesResult } from './hooks';
 
+// Re-export campaign types for convenience
+export type { CampaignClaimFilters, CampaignHook } from './hooks';
+
+// Re-export redemption types for convenience
+export type { RedemptionRedeemFilters, RedemptionHook } from './hooks';
+
+// Re-export transaction types for convenience
+export type { TransactionQueryOptions, TransactionHook } from './hooks';
+
+// Re-export trigger source types for convenience
+export type { TriggerSourceQueryOptions, TriggerSourceHook } from './hooks';
+
+// Re-export analytics types for convenience
+export type { AnalyticsHook } from './hooks';
+
 // ==============================================================================
 // PLATFORM ADAPTERS
 // ==============================================================================
@@ -284,9 +308,15 @@ export type { TokenBalanceWithToken, UseTokenBalancesOptions, UseTokenBalancesRe
  * Provides platform-specific networking with proper error handling, timeout management,
  * and React Native compatibility. Automatically handles headers, authentication tokens,
  * and response parsing.
+ * 
+ * @see {@link ReactNativeHttpClient} - The HTTP client implementation
+ * @see {@link HttpClient} - The HTTP client interface
+ * @see {@link RequestOptions} - Request configuration options
  */
 export {
-  ReactNativeHttpClient
+  ReactNativeHttpClient,
+  type HttpClient,
+  type RequestOptions
 } from './providers/react-native-http-client';
 
 // ==============================================================================