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

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/hooks/useUsers.ts

@@ -1,12 +1,31 @@
 import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
 import type { UserDTO, UserCreateRequestDTO, PaginatedResponseDTO } from '@explorins/pers-shared';
-import type { UserPublicProfileDTO } from '@explorins/pers-sdk/user';
+import type { UserPublicProfileDTO, UserQueryOptions } from '@explorins/pers-sdk/user';
+
+// Re-export for consumers
+export type { UserQueryOptions } from '@explorins/pers-sdk/user';
 
 export const useUsers = () => {
   const { sdk, isInitialized, isAuthenticated } = usePersSDK();
 
-  const getCurrentUser = useCallback(async (): Promise<UserDTO> => {
+  /**
+   * Get the current authenticated user with optional include relations
+   * 
+   * @param options - Query options including include relations
+   * @returns Current user data
+   * 
+   * @example
+   * ```typescript
+   * // Basic
+   * const user = await getCurrentUser();
+   * 
+   * // With wallets included
+   * const userWithWallets = await getCurrentUser({ include: ['wallets'] });
+   * console.log('Wallets:', userWithWallets.included?.wallets);
+   * ```
+   */
+  const getCurrentUser = useCallback(async (options?: UserQueryOptions): Promise<UserDTO> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
@@ -15,7 +34,7 @@ export const useUsers = () => {
     }
     
     try {
-      const result = await sdk.users.getCurrentUser();
+      const result = await sdk.users.getCurrentUser(options);
       return result;
     } catch (error) {
       console.error('Failed to fetch current user:', error);
@@ -40,13 +59,29 @@ export const useUsers = () => {
     }
   }, [sdk, isInitialized, isAuthenticated]);
 
-  const getUserById = useCallback(async (userId: string): Promise<UserDTO> => {
+  /**
+   * Get user by ID with optional include relations
+   * 
+   * @param userId - User identifier (id, email, externalId, etc.)
+   * @param options - Query options including include relations
+   * @returns User data
+   * 
+   * @example
+   * ```typescript
+   * // Basic
+   * const user = await getUserById('user-123');
+   * 
+   * // With wallets included
+   * const userWithWallets = await getUserById('user-123', { include: ['wallets'] });
+   * ```
+   */
+  const getUserById = useCallback(async (userId: string, options?: UserQueryOptions): Promise<UserDTO> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.users.getUserById(userId);
+      const result = await sdk.users.getUserById(userId, options);
       return result;
     } catch (error) {
       console.error('Failed to fetch user:', error);
@@ -97,16 +132,23 @@ export const useUsers = () => {
     }
   }, [sdk, isInitialized]);
 
-  const toggleUserStatus = useCallback(async (user: UserDTO): Promise<UserDTO> => {
+  /**
+   * Toggle or set a user's active status (admin only)
+   * 
+   * @param userId - User ID to update
+   * @param isActive - Optional explicit status. If omitted, toggles current status.
+   * @returns Updated user
+   */
+  const setUserActiveStatus = useCallback(async (userId: string, isActive?: boolean): Promise<UserDTO> => {
     if (!isInitialized || !sdk) {
       throw new Error('SDK not initialized. Call initialize() first.');
     }
     
     try {
-      const result = await sdk.users.toggleUserStatus(user);
+      const result = await sdk.users.setUserActiveStatus(userId, isActive);
       return result;
     } catch (error) {
-      console.error('Failed to toggle user status:', error);
+      console.error('Failed to set user active status:', error);
       throw error;
     }
   }, [sdk, isInitialized]);
@@ -118,7 +160,7 @@ export const useUsers = () => {
     getAllUsersPublic,
     getAllUsers,
     updateUser,
-    toggleUserStatus,
+    setUserActiveStatus,
     isAvailable: isInitialized && !!sdk?.users,
   };
 };