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

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';
 
 // ==============================================================================

package/src/providers/PersSDKProvider.tsx

@@ -28,19 +28,6 @@ export interface PersSDKContext {
   // Main SDK instance
   sdk: PersSDK | null;
   
-  // Manager shortcuts for convenience
-  auth: AuthManager | null;
-  users: UserManager | null;
-  tokens: TokenManager | null;
-  businesses: BusinessManager | null;
-  campaigns: CampaignManager | null;
-  redemptions: RedemptionManager | null;
-  transactions: TransactionManager | null;
-  purchases: PurchaseManager | null;
-  tenants: TenantManager | null;
-  analytics: AnalyticsManager | null;
-  donations: DonationManager | null;
-  
   // Platform-specific providers
   authProvider: DefaultAuthProvider | null;
   
@@ -53,6 +40,7 @@ export interface PersSDKContext {
   initialize: (config: PersConfig) => Promise<void>;
   setAuthenticationState: (user: UserDTO | AdminDTO | null, isAuthenticated: boolean) => void;
   refreshUserData: () => Promise<void>;
+  restoreSession: () => Promise<UserDTO | null>;
 }
 
 // Create the context
@@ -64,6 +52,12 @@ export const PersSDKProvider: React.FC<{
   config?: PersConfig;
 }> = ({ children, config }) => {
   const initializingRef = useRef(false);
+  
+  // State refs for stable functions to read current values
+  const sdkRef = useRef<PersSDK | null>(null);
+  const isInitializedRef = useRef(false);
+  const isAuthenticatedRef = useRef(false);
+  
   const [sdk, setSdk] = useState<PersSDK | null>(null);
   const [authProvider, setAuthProvider] = useState<DefaultAuthProvider | null>(null);
   
@@ -71,6 +65,11 @@ export const PersSDKProvider: React.FC<{
   const [isAuthenticated, setIsAuthenticated] = useState(false);
   const [user, setUser] = useState<UserDTO | AdminDTO | null>(null);
 
+  // Keep state refs in sync immediately (not in useEffect to avoid race conditions)
+  sdkRef.current = sdk;
+  isInitializedRef.current = isInitialized;
+  isAuthenticatedRef.current = isAuthenticated;
+
   const initialize = useCallback(async (config: PersConfig) => {
     // Prevent multiple initializations
     if (isInitialized || initializingRef.current) {
@@ -147,18 +146,44 @@ export const PersSDKProvider: React.FC<{
   }, [config, isInitialized, initialize]);
 
   const refreshUserData = useCallback(async (): Promise<void> => {
-    if (!sdk || !isAuthenticated || !isInitialized) {
-      throw new Error('SDK not initialized or not authenticated. Cannot refresh user data.');
+    // Read from refs to get current values
+    const currentSdk = sdkRef.current;
+    const currentIsInitialized = isInitializedRef.current;
+
+    if (!currentSdk || !currentIsInitialized) {
+      throw new Error('SDK not initialized. Cannot refresh user data.');
     }
     
     try {
-      const freshUserData = await sdk.users.getCurrentUser();
+      const freshUserData = await currentSdk.users.getCurrentUser();
       setUser(freshUserData);
     } catch (error) {
       console.error('Failed to refresh user data:', error);
       throw error;
     }
-  }, [sdk, isAuthenticated, isInitialized]);
+  }, []); // No dependencies - reads from refs
+
+  const restoreSession = useCallback(async (): Promise<UserDTO | null> => {
+    // Read from refs to get current values
+    const currentSdk = sdkRef.current;
+    const currentIsInitialized = isInitializedRef.current;
+
+    if (!currentSdk || !currentIsInitialized) {
+      throw new Error('SDK not initialized. Call initialize() first.');
+    }
+    
+    try {
+      const userData = await currentSdk.restoreSession();
+      if (userData) {
+        setAuthenticationState(userData, true);
+      }
+      return userData;
+    } catch (error) {
+      console.error('[PersSDK] Failed to restore session:', error);
+      throw error;
+    }
+  }, [setAuthenticationState]); // Depends on setAuthenticationState
+  
   // Listen for authentication events from core SDK
   // Set up immediately when SDK is created (don't wait for isInitialized)
   // to catch session_restored events that fire during SDK initialization
@@ -171,13 +196,18 @@ export const PersSDKProvider: React.FC<{
       // Session restored successfully - sync React state
       if (event.type === 'session_restored') {
         console.log('[PersSDK] Session restoration event received, syncing state...');
-        sdk.users.getCurrentUser()
-          .then(userData => {
-            setAuthenticationState(userData, true);
-          })
-          .catch(error => {
-            console.error('[PersSDK] Failed to sync restored session:', error);
-          });
+        // Read user from event details if available, otherwise fetch
+        const userId = event.details?.userId;
+        if (userId) {
+          // User ID available, fetch user data
+          sdk.users.getCurrentUser()
+            .then(userData => {
+              setAuthenticationState(userData, true);
+            })
+            .catch(error => {
+              console.error('[PersSDK] Failed to sync restored session:', error);
+            });
+        }
       }
 
       // Session restoration failed or auth error - clear React state
@@ -222,19 +252,6 @@ export const PersSDKProvider: React.FC<{
     // Main SDK instance
     sdk,
     
-    // Manager shortcuts for convenience
-    auth: sdk?.auth || null,
-    users: sdk?.users || null,
-    tokens: sdk?.tokens || null,
-    businesses: sdk?.businesses || null,
-    campaigns: sdk?.campaigns || null,
-    redemptions: sdk?.redemptions || null,
-    transactions: sdk?.transactions || null,
-    purchases: sdk?.purchases || null,
-    tenants: sdk?.tenants || null,
-    analytics: sdk?.analytics || null,
-    donations: sdk?.donations || null,
-    
     // Platform-specific providers
     authProvider,
     
@@ -243,10 +260,11 @@ export const PersSDKProvider: React.FC<{
     isAuthenticated,
     user,
     
-    // Methods
+    // Methods - expose functions directly, not through refs
     initialize,
     setAuthenticationState,
     refreshUserData,
+    restoreSession,
   }), [
     sdk,
     authProvider,
@@ -255,7 +273,8 @@ export const PersSDKProvider: React.FC<{
     user,
     initialize,
     setAuthenticationState,
-    refreshUserData
+    refreshUserData,
+    restoreSession
   ]);
 
   return (