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

package/dist/hooks/useTriggerSources.js

@@ -0,0 +1,272 @@
+import { useCallback } from 'react';
+import { usePersSDK } from '../providers/PersSDKProvider';
+/**
+ * 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) => {
+        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) => {
+        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) => {
+        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, triggerSource) => {
+        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) => {
+        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,
+    };
+};

package/dist/index.d.ts

@@ -206,18 +206,27 @@ export { PersSDKProvider, usePersSDK, type PersConfig, type PersSDKContext } fro
  * }
  * ```
  */
-export { useAuth, useTokens, useTokenBalances, useTransactions, useTransactionSigner, SigningStatus, useBusiness, useCampaigns, useRedemptions, useWeb3, usePurchases, useTenants, useUsers, useUserStatus, useFiles, useAnalytics, useDonations, useEvents } from './hooks';
-export type { OnStatusUpdateFn, StatusUpdateData, SigningStatusType, TransactionSigningResult, SubmissionResult, AuthenticatedUser } from './hooks';
+export { useAuth, useTokens, useTokenBalances, useTransactions, useTransactionSigner, SigningStatus, useBusiness, useCampaigns, useRedemptions, useWeb3, usePurchases, useTenants, useUsers, useUserStatus, useFiles, useAnalytics, useDonations, useEvents, useTriggerSources } from './hooks';
+export type { TransactionSignerHook, OnStatusUpdateFn, StatusUpdateData, SigningStatusType, TransactionSigningResult, SubmissionResult, AuthenticatedUser } from './hooks';
 export type { EventsHook, PersEvent, EventHandler, EventFilter, Unsubscribe } from './hooks';
 export type { TokenBalanceWithToken, UseTokenBalancesOptions, UseTokenBalancesResult } from './hooks';
+export type { CampaignClaimFilters, CampaignHook } from './hooks';
+export type { RedemptionRedeemFilters, RedemptionHook } from './hooks';
+export type { TransactionQueryOptions, TransactionHook } from './hooks';
+export type { TriggerSourceQueryOptions, TriggerSourceHook } from './hooks';
+export type { AnalyticsHook } from './hooks';
 /**
  * React Native-optimized HTTP client with automatic request/response handling
  *
  * 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 } from './providers/react-native-http-client';
+export { ReactNativeHttpClient, type HttpClient, type RequestOptions } from './providers/react-native-http-client';
 /**
  * React Native polyfill utilities for web compatibility
  *

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,aAAa,CAAC;AAMrB;;;;;;;;GAQG;AACH,OAAO,EACL,6BAA6B,EAC7B,KAAK,qBAAqB,EAC3B,MAAM,wCAAwC,CAAC;AAMhD;;;;;;;;;;GAUG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;;;;;;GAQG;AACH,OAAO,EACL,wBAAwB,GACzB,MAAM,uCAAuC,CAAC;AAM/C;;;GAGG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAMvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EACL,eAAe,EACf,UAAU,EACV,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,6BAA6B,CAAC;AAMrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,cAAc,EACd,OAAO,EACP,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,SAAS,EACV,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGpJ,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG7F,YAAY,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAMtG;;;;;;GAMG;AACH,OAAO,EACL,qBAAqB,EACtB,MAAM,sCAAsC,CAAC;AAM9C;;;;;;;;GAQG;AACH,OAAO,EACL,8BAA8B,EAC/B,MAAM,aAAa,CAAC;AAMrB;;;;;;;;;;;;;;;;GAgBG;AACH,cAAc,wBAAwB,CAAC;AAEvC;;;;GAIG;AACH,OAAO,EAAE,gCAAgC,EAAE,MAAM,2BAA2B,CAAC;AAE7E;;;;;GAKG;AACH,OAAO,EAEL,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;GAWG;AACH,YAAY,EACV,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAMlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,8BAA8B,EAC9B,2BAA2B,EAC5B,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAMzG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACX,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,aAAa,CAAC;AAMrB;;;;;;;;GAQG;AACH,OAAO,EACL,6BAA6B,EAC7B,KAAK,qBAAqB,EAC3B,MAAM,wCAAwC,CAAC;AAMhD;;;;;;;;;;GAUG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;;;;;;GAQG;AACH,OAAO,EACL,wBAAwB,GACzB,MAAM,uCAAuC,CAAC;AAM/C;;;GAGG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAMvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EACL,eAAe,EACf,UAAU,EACV,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,6BAA6B,CAAC;AAMrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,cAAc,EACd,OAAO,EACP,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG7F,YAAY,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAGtG,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGlE,YAAY,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGvE,YAAY,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAGxE,YAAY,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAG5E,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAM7C;;;;;;;;;;GAUG;AACH,OAAO,EACL,qBAAqB,EACrB,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,sCAAsC,CAAC;AAM9C;;;;;;;;GAQG;AACH,OAAO,EACL,8BAA8B,EAC/B,MAAM,aAAa,CAAC;AAMrB;;;;;;;;;;;;;;;;GAgBG;AACH,cAAc,wBAAwB,CAAC;AAEvC;;;;GAIG;AACH,OAAO,EAAE,gCAAgC,EAAE,MAAM,2BAA2B,CAAC;AAE7E;;;;;GAKG;AACH,OAAO,EAEL,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;GAWG;AACH,YAAY,EACV,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAMlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,8BAA8B,EAC9B,2BAA2B,EAC5B,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAMzG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACX,MAAM,0BAA0B,CAAC"}