@explorins/pers-sdk-react-native 2.1.8 → 2.1.11

package/dist/hooks/useCampaigns.d.ts

@@ -1,8 +1,27 @@
-import type { CampaignClaimRequestDTO, CampaignDTO, CampaignClaimDTO, CampaignTriggerDTO, PaginatedResponseDTO, CampaignClaimIncludeRelation, CampaignIncludeRelation } from '@explorins/pers-shared';
+import type { CampaignClaimRequestDTO, CampaignDTO, CampaignClaimDTO, CampaignTriggerDTO, PaginatedResponseDTO, CampaignClaimIncludeRelation, CampaignIncludeRelation, SortOrder } from '@explorins/pers-shared';
 import type { CampaignClaimFilters } from '@explorins/pers-sdk/campaign';
 export type { CampaignClaimFilters } from '@explorins/pers-sdk/campaign';
+/**
+ * Options for fetching campaigns
+ */
+export interface GetCampaignsOptions {
+    /** Filter by tag */
+    tag?: string;
+    /** Filter by business ID */
+    businessId?: string;
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Items per page */
+    limit?: number;
+    /** Sort field */
+    sortBy?: 'name' | 'createdAt' | 'startDate';
+    /** Sort order */
+    sortOrder?: SortOrder;
+    /** Relations to include: 'triggerSources', 'businesses' */
+    include?: CampaignIncludeRelation[];
+}
 export declare const useCampaigns: () => {
-    getActiveCampaigns: () => Promise<PaginatedResponseDTO<CampaignDTO>>;
+    getActiveCampaigns: (options?: GetCampaignsOptions) => Promise<PaginatedResponseDTO<CampaignDTO>>;
     getCampaignById: (campaignId: string, include?: CampaignIncludeRelation[]) => Promise<CampaignDTO | null>;
     claimCampaign: (request: CampaignClaimRequestDTO) => Promise<CampaignClaimDTO | null>;
     getUserClaims: (options?: {
@@ -11,7 +30,9 @@ export declare const useCampaigns: () => {
         include?: CampaignClaimIncludeRelation[];
     }) => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
     getCampaignTriggers: () => Promise<PaginatedResponseDTO<CampaignTriggerDTO>>;
-    getAllCampaigns: (active?: boolean) => Promise<PaginatedResponseDTO<CampaignDTO>>;
+    getAllCampaigns: (options?: GetCampaignsOptions & {
+        active?: boolean;
+    }) => Promise<PaginatedResponseDTO<CampaignDTO>>;
     getCampaignClaims: (filters?: CampaignClaimFilters, include?: CampaignClaimIncludeRelation[]) => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
     getCampaignClaimsByUserId: (userId: string, include?: CampaignClaimIncludeRelation[]) => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
     getCampaignClaimsByBusinessId: (businessId: string, include?: CampaignClaimIncludeRelation[]) => Promise<PaginatedResponseDTO<CampaignClaimDTO>>;

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,EAClB,oBAAoB,EACpB,4BAA4B,EAC5B,uBAAuB,EACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAGzE,YAAY,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEzE,eAAO,MAAM,YAAY;8BAG0B,QAAQ,qBAAqB,WAAW,CAAC,CAAC;kCA6B7E,MAAM,YACR,uBAAuB,EAAE,KAClC,QAAQ,WAAW,GAAG,IAAI,CAAC;6BAcoB,uBAAuB,KAAG,QAAQ,gBAAgB,GAAG,IAAI,CAAC;8BAmCzD;QACjD,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,4BAA4B,EAAE,CAAC;KAC1C,KAAG,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;+BAkBD,QAAQ,qBAAqB,kBAAkB,CAAC,CAAC;+BAe/C,OAAO,KAAG,QAAQ,qBAAqB,WAAW,CAAC,CAAC;kCA+B5F,oBAAoB,YACpB,4BAA4B,EAAE,KACvC,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;wCAsBxC,MAAM,YACJ,4BAA4B,EAAE,KACvC,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;gDAsBpC,MAAM,YACR,4BAA4B,EAAE,KACvC,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;sCA4CpC,MAAM,mBACD,MAAM,KACtB,QAAQ,WAAW,CAAC;sCA4BT,MAAM,mBACD,MAAM,KACtB,QAAQ,WAAW,CAAC;;CA+BxB,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,EAClB,oBAAoB,EACpB,4BAA4B,EAC5B,uBAAuB,EACvB,SAAS,EACV,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAGzE,YAAY,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,oBAAoB;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,WAAW,CAAC;IAC5C,iBAAiB;IACjB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,uBAAuB,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,YAAY;mCA6BX,mBAAmB,KAC5B,QAAQ,qBAAqB,WAAW,CAAC,CAAC;kCAgC/B,MAAM,YACR,uBAAuB,EAAE,KAClC,QAAQ,WAAW,GAAG,IAAI,CAAC;6BAcoB,uBAAuB,KAAG,QAAQ,gBAAgB,GAAG,IAAI,CAAC;8BAmCzD;QACjD,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,4BAA4B,EAAE,CAAC;KAC1C,KAAG,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;+BAkBD,QAAQ,qBAAqB,kBAAkB,CAAC,CAAC;gCA0CvF,mBAAmB,GAAG;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,KACnD,QAAQ,qBAAqB,WAAW,CAAC,CAAC;kCA+BjC,oBAAoB,YACpB,4BAA4B,EAAE,KACvC,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;wCAsBxC,MAAM,YACJ,4BAA4B,EAAE,KACvC,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;gDAsBpC,MAAM,YACR,4BAA4B,EAAE,KACvC,QAAQ,qBAAqB,gBAAgB,CAAC,CAAC;sCA4CpC,MAAM,mBACD,MAAM,KACtB,QAAQ,WAAW,CAAC;sCA4BT,MAAM,mBACD,MAAM,KACtB,QAAQ,WAAW,CAAC;;CA+BxB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC"}

package/dist/hooks/useCampaigns.js

@@ -2,12 +2,40 @@ import { useCallback } from 'react';
 import { usePersSDK } from '../providers/PersSDKProvider';
 export const useCampaigns = () => {
     const { sdk, isInitialized, isAuthenticated } = usePersSDK();
-    const getActiveCampaigns = useCallback(async () => {
+    /**
+     * Get active campaigns with optional filters and include relations
+     *
+     * @param options - Filter, pagination, and include options
+     * @returns Promise resolving to paginated active campaigns
+     *
+     * @example
+     * ```typescript
+     * // Simple: get active campaigns with trigger sources
+     * const { data: campaigns } = await getActiveCampaigns({ include: ['triggerSources'] });
+     *
+     * // With pagination
+     * const { data, pagination } = await getActiveCampaigns({
+     *   page: 1,
+     *   limit: 10,
+     *   include: ['triggerSources', 'businesses']
+     * });
+     *
+     * // Filter by tag
+     * const { data } = await getActiveCampaigns({ tag: 'summer-promo' });
+     *
+     * // Filter by business
+     * const { data } = await getActiveCampaigns({ businessId: 'business-123' });
+     * ```
+     */
+    const getActiveCampaigns = useCallback(async (options) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.campaigns.getCampaigns({ active: true });
+            const result = await sdk.campaigns.getCampaigns({
+                active: true,
+                ...options
+            });
             return result;
         }
         catch (error) {
@@ -107,12 +135,38 @@ export const useCampaigns = () => {
         }
     }, [sdk, isInitialized]);
     // Admin methods
-    const getAllCampaigns = useCallback(async (active) => {
+    /**
+     * Admin: Get all campaigns with optional filters and include relations
+     *
+     * @param options - Filter, pagination, and include options (same as getActiveCampaigns but active is optional)
+     * @returns Promise resolving to paginated campaigns
+     *
+     * @example
+     * ```typescript
+     * // Get all campaigns
+     * const { data } = await getAllCampaigns();
+     *
+     * // Get only active campaigns with trigger sources
+     * const { data } = await getAllCampaigns({ active: true, include: ['triggerSources'] });
+     *
+     * // Get inactive campaigns
+     * const { data } = await getAllCampaigns({ active: false });
+     *
+     * // With pagination and sorting
+     * const { data } = await getAllCampaigns({
+     *   page: 1,
+     *   limit: 20,
+     *   sortBy: 'createdAt',
+     *   sortOrder: 'DESC'
+     * });
+     * ```
+     */
+    const getAllCampaigns = useCallback(async (options) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.campaigns.getCampaigns({ active });
+            const result = await sdk.campaigns.getCampaigns(options);
             return result;
         }
         catch (error) {

package/dist/index.js

@@ -2933,15 +2933,42 @@ exports.PurchaseCurrency = void 0;
 })(exports.PurchaseCurrency || (exports.PurchaseCurrency = {}));
 
 /**
- * Trigger Source Types
- * Defines the different types of triggers that can activate a campaign flow
+ * Trigger Source Types - HOW a claim is triggered (the touchpoint mechanism)
+ *
+ * This defines the physical/digital interaction method for triggering claims.
+ * NOT to be confused with CampaignTriggerType which defines WHO can claim.
+ *
+ * Relationship:
+ * - campaign.trigger.triggerType → WHO can claim (CLAIM_BY_USER, CLAIM_BY_BUSINESS, CLAIM_BY_SYSTEM)
+ * - campaign.triggerSources[].type → HOW to claim (QR_CODE, NFC_TAG, GPS_GEOFENCE, etc.)
+ *
+ * Access via: campaign.included?.triggerSources?.map(ts => ts.type)
+ *
+ * App Integration Guide:
+ * - QR_CODE: Open camera/scanner, decode QR, extract triggerSourceId
+ * - NFC_TAG: Activate NFC reader, read tag data, extract triggerSourceId
+ * - GPS_GEOFENCE: Get user location, send latitude/longitude with claim
+ * - API_WEBHOOK: Server-to-server, external system triggers claim
+ * - TRANSACTION: Triggered by purchase events (Stripe, POS, etc.)
+ *
+ * NOTE: A campaign can have MULTIPLE trigger sources of different types.
+ * Example: Same campaign claimable via QR_CODE OR NFC_TAG at different locations.
+ *
  * Using const object pattern for better extensibility without requiring deploys
+ *
+ * @see CampaignTriggerType for WHO can initiate claims
+ * @see CampaignClaimRequestDTO for the claim payload structure
  */
 const TRIGGER_SOURCE_TYPES = {
+    /** Physical QR code scan. App opens camera, decodes QR, extracts triggerSourceId */
     QR_CODE: 'QR_CODE',
+    /** NFC tag tap. App activates NFC reader, reads tag data, extracts triggerSourceId */
     NFC_TAG: 'NFC_TAG',
+    /** Server-to-server webhook. External system triggers claim via API */
     API_WEBHOOK: 'API_WEBHOOK',
+    /** GPS-based geofence entry. App sends user coordinates for proximity validation */
     GPS_GEOFENCE: 'GPS_GEOFENCE',
+    /** Purchase/transaction triggered. Claim activated by payment events */
     TRANSACTION: 'TRANSACTION',
 };
 // Export values array for validation
@@ -2967,10 +2994,46 @@ exports.CampaignConditionType = void 0;
     CampaignConditionType["IS_PART_OF"] = "IS_PART_OF";
 })(exports.CampaignConditionType || (exports.CampaignConditionType = {}));
 
+/**
+ * Campaign Trigger Type - WHO can initiate a claim
+ *
+ * This defines the authentication/authorization context for claiming rewards.
+ * NOT to be confused with TriggerSourceType which defines HOW to claim (QR, NFC, etc.)
+ *
+ * Relationship:
+ * - campaign.trigger.triggerType → WHO can claim (CLAIM_BY_USER, CLAIM_BY_BUSINESS, CLAIM_BY_SYSTEM)
+ * - campaign.triggerSources[].type → HOW to claim (QR_CODE, NFC_TAG, GPS_GEOFENCE, etc.)
+ *
+ * Example Flow:
+ * 1. Campaign has triggerType=CLAIM_BY_USER (users initiate claims)
+ * 2. Campaign has triggerSources with type=QR_CODE (via QR scan)
+ * 3. User scans QR code → App calls claimCampaign with triggerSourceId
+ *
+ * @see TriggerSourceType for HOW claims are triggered
+ * @see CampaignClaimRequestDTO for the claim payload structure
+ */
 exports.CampaignTriggerType = void 0;
 (function (CampaignTriggerType) {
+    /**
+     * User-initiated claims. The end user triggers the claim action.
+     * App determines HOW via campaign.triggerSources[].type:
+     * - QR_CODE: Open camera/scanner
+     * - NFC_TAG: Activate NFC reader
+     * - GPS_GEOFENCE: Send user location
+     * - TRANSACTION: Triggered by purchase
+     */
     CampaignTriggerType["CLAIM_BY_USER"] = "CLAIM_BY_USER";
+    /**
+     * System/server-initiated claims. Automated processes trigger claims.
+     * Use cases: webhooks, scheduled jobs, backend integrations.
+     * Requires tenant API key authentication.
+     */
     CampaignTriggerType["CLAIM_BY_SYSTEM"] = "CLAIM_BY_SYSTEM";
+    /**
+     * Business-initiated claims. A business claims on behalf of users.
+     * Use cases: POS systems, staff-assisted redemptions, kiosks.
+     * Requires business authentication + user identifier.
+     */
     CampaignTriggerType["CLAIM_BY_BUSINESS"] = "CLAIM_BY_BUSINESS";
 })(exports.CampaignTriggerType || (exports.CampaignTriggerType = {}));
 
@@ -7703,15 +7766,26 @@ class TenantApi {
     // ==========================================
     // PUBLIC OPERATIONS
     // ==========================================
+    /**
+     * API KEY + ADMIN JWT: Get full tenant information including sensitive config
+     * Uses /tenants/me endpoint with Admin JWT authentication
+     *
+     * Requires: X-API-Key header + Authorization Bearer token (Admin JWT)
+     * Returns: Full tenant information including allowedTokenIssuers and sensitive config
+     */
+    async getRemoteTenant() {
+        const timestamp = Date.now().toString();
+        const url = `${this.basePath}/me?date=${timestamp}`;
+        return this.apiClient.get(url);
+    }
     /**
      * API KEY: Get current tenant public information
-     * UPDATED: Uses /tenants/me endpoint with API key authentication
+     * Uses /tenants/me endpoint with API key authentication
      *
      * Requires: X-API-Key header (handled by PersApiClient)
-     * Returns: Enhanced public tenant information for the authenticated project
+     * Returns: Public tenant information (no sensitive config)
      */
-    async getRemoteTenant() {
-        // Remove cache busting - not needed for authenticated endpoint
+    async getRemoteTenantPublic() {
         const timestamp = Date.now().toString();
         const url = `${this.basePath}/me?date=${timestamp}`;
         return this.apiClient.get(url);
@@ -7748,7 +7822,8 @@ class TenantApi {
     // ==========================================
     /**
      * ADMIN: Update tenant information
-     *  UPDATED: Uses PUT /tenants (admin endpoint)
+     * UPDATED: Uses PUT /tenants (admin endpoint)
+     * Returns full TenantDTO including sensitive config
      */
     async updateRemoteTenant(tenantData) {
         return this.apiClient.put(`${this.basePath}`, tenantData);
@@ -7793,11 +7868,17 @@ class TenantService {
     // PUBLIC OPERATIONS
     // ==========================================
     /**
-     * PUBLIC: Get tenant public information
+     * Get full tenant information (Admin JWT required)
      */
     async getRemoteTenant() {
         return this.tenantApi.getRemoteTenant();
     }
+    /**
+     * PUBLIC: Get tenant public information (API key only)
+     */
+    async getRemoteTenantPublic() {
+        return this.tenantApi.getRemoteTenantPublic();
+    }
     /**
      * PUBLIC: Get remote login token
      */
@@ -7815,7 +7896,7 @@ class TenantService {
     // ==========================================
     /**
      * ADMIN: Update tenant information
-     * ✅ FIXED: Uses TenantPublicDTO directly like framework
+     * Returns full TenantDTO including sensitive config
      */
     async updateRemoteTenant(tenantData) {
         return this.tenantApi.updateRemoteTenant(tenantData);
@@ -7859,9 +7940,20 @@ class TenantManager {
         this.tenantService = new TenantService(tenantApi);
     }
     /**
-     * Get current tenant information
+     * Get current tenant public information (API key only)
+     *
+     * @returns Promise resolving to public tenant data
+     */
+    async getTenantPublicInfo() {
+        return this.tenantService.getRemoteTenantPublic();
+    }
+    /**
+     * Get full tenant information including sensitive config (Admin JWT required)
+     *
+     * Returns additional fields like allowedTokenIssuers that are only
+     * available to authenticated tenant admins.
      *
-     * @returns Promise resolving to tenant data
+     * @returns Promise resolving to full tenant data
      */
     async getTenantInfo() {
         return this.tenantService.getRemoteTenant();
@@ -7944,7 +8036,7 @@ class TenantManager {
      * Admin: Update tenant data
      *
      * @param tenantData - Updated tenant data
-     * @returns Promise resolving to updated tenant
+     * @returns Promise resolving to full updated tenant (includes sensitive config)
      */
     async updateTenant(tenantData) {
         return this.tenantService.updateRemoteTenant(tenantData);
@@ -41248,12 +41340,40 @@ const useBusiness = () => {
 
 const useCampaigns = () => {
     const { sdk, isInitialized, isAuthenticated } = usePersSDK();
-    const getActiveCampaigns = react.useCallback(async () => {
+    /**
+     * Get active campaigns with optional filters and include relations
+     *
+     * @param options - Filter, pagination, and include options
+     * @returns Promise resolving to paginated active campaigns
+     *
+     * @example
+     * ```typescript
+     * // Simple: get active campaigns with trigger sources
+     * const { data: campaigns } = await getActiveCampaigns({ include: ['triggerSources'] });
+     *
+     * // With pagination
+     * const { data, pagination } = await getActiveCampaigns({
+     *   page: 1,
+     *   limit: 10,
+     *   include: ['triggerSources', 'businesses']
+     * });
+     *
+     * // Filter by tag
+     * const { data } = await getActiveCampaigns({ tag: 'summer-promo' });
+     *
+     * // Filter by business
+     * const { data } = await getActiveCampaigns({ businessId: 'business-123' });
+     * ```
+     */
+    const getActiveCampaigns = react.useCallback(async (options) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.campaigns.getCampaigns({ active: true });
+            const result = await sdk.campaigns.getCampaigns({
+                active: true,
+                ...options
+            });
             return result;
         }
         catch (error) {
@@ -41353,12 +41473,38 @@ const useCampaigns = () => {
         }
     }, [sdk, isInitialized]);
     // Admin methods
-    const getAllCampaigns = react.useCallback(async (active) => {
+    /**
+     * Admin: Get all campaigns with optional filters and include relations
+     *
+     * @param options - Filter, pagination, and include options (same as getActiveCampaigns but active is optional)
+     * @returns Promise resolving to paginated campaigns
+     *
+     * @example
+     * ```typescript
+     * // Get all campaigns
+     * const { data } = await getAllCampaigns();
+     *
+     * // Get only active campaigns with trigger sources
+     * const { data } = await getAllCampaigns({ active: true, include: ['triggerSources'] });
+     *
+     * // Get inactive campaigns
+     * const { data } = await getAllCampaigns({ active: false });
+     *
+     * // With pagination and sorting
+     * const { data } = await getAllCampaigns({
+     *   page: 1,
+     *   limit: 20,
+     *   sortBy: 'createdAt',
+     *   sortOrder: 'DESC'
+     * });
+     * ```
+     */
+    const getAllCampaigns = react.useCallback(async (options) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.campaigns.getCampaigns({ active });
+            const result = await sdk.campaigns.getCampaigns(options);
             return result;
         }
         catch (error) {