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

package/dist/index.js

@@ -2828,6 +2828,28 @@ exports.SortOrder = void 0;
     SortOrder["DESC"] = "DESC";
 })(exports.SortOrder || (exports.SortOrder = {}));
 
+/**
+ * ProcessRecordStatus - Status for business process records that create blockchain transactions
+ *
+ * Used for tracking the lifecycle of business operations (campaigns, redemptions) that
+ * trigger blockchain transactions. This is distinct from TransactionStatus which tracks
+ * the blockchain transaction itself.
+ *
+ * Usage:
+ * - Campaign Claims (user claims rewards via blockchain transactions)
+ * - Redemption Redeems (user redeems items via blockchain transactions)
+ * - Any business process creating blockchain transactions that need status tracking
+ *
+ * NOT for blockchain transactions themselves - use TransactionStatus instead.
+ */
+exports.ProcessRecordStatus = void 0;
+(function (ProcessRecordStatus) {
+    ProcessRecordStatus["PENDING"] = "PENDING";
+    ProcessRecordStatus["PROCESSING"] = "PROCESSING";
+    ProcessRecordStatus["COMPLETED"] = "COMPLETED";
+    ProcessRecordStatus["FAILED"] = "FAILED"; // Transaction processing failed (blockchain or validation error)
+})(exports.ProcessRecordStatus || (exports.ProcessRecordStatus = {}));
+
 exports.PurchaseStatus = void 0;
 (function (PurchaseStatus) {
     // after creation of payment and before payment is done by user
@@ -2847,35 +2869,30 @@ exports.PurchaseCurrency = void 0;
     PurchaseCurrency["EUR"] = "eur";
 })(exports.PurchaseCurrency || (exports.PurchaseCurrency = {}));
 
-exports.RedemptionRedeemStatus = void 0;
-(function (RedemptionRedeemStatus) {
-    RedemptionRedeemStatus["PENDING"] = "PENDING";
-    RedemptionRedeemStatus["PROCESSING"] = "PROCESSING";
-    RedemptionRedeemStatus["COMPLETED"] = "COMPLETED";
-    RedemptionRedeemStatus["FAILED"] = "FAILED"; // Processing failed
-})(exports.RedemptionRedeemStatus || (exports.RedemptionRedeemStatus = {}));
-
 /**
  * Trigger Source Types
  * Defines the different types of triggers that can activate a campaign flow
- */
-exports.TriggerSourceType = void 0;
-(function (TriggerSourceType) {
-    TriggerSourceType["QR_CODE"] = "QR_CODE";
-    // NFC_TAG = 'NFC_TAG', 
-    TriggerSourceType["API_WEBHOOK"] = "API_WEBHOOK";
-    // TRANSACTION = 'TRANSACTION',
-})(exports.TriggerSourceType || (exports.TriggerSourceType = {}));
+ * Using const object pattern for better extensibility without requiring deploys
+ */
+const TRIGGER_SOURCE_TYPES = {
+    QR_CODE: 'QR_CODE',
+    NFC_TAG: 'NFC_TAG',
+    API_WEBHOOK: 'API_WEBHOOK',
+    GPS_GEOFENCE: 'GPS_GEOFENCE',
+    TRANSACTION: 'TRANSACTION',
+};
+// Export values array for validation
+const TRIGGER_SOURCE_TYPE_VALUES = Object.values(TRIGGER_SOURCE_TYPES);
 /**
  * Source Logic Types
  * Defines how multiple trigger sources combine to activate a flow
  * Currently only ANY (OR logic) is implemented
  */
-exports.SourceLogicType = void 0;
-(function (SourceLogicType) {
-    SourceLogicType["ANY"] = "any";
-    // Future: ALL = 'all', SEQUENCE = 'sequence', WEIGHTED = 'weighted'
-})(exports.SourceLogicType || (exports.SourceLogicType = {}));
+const SOURCE_LOGIC_TYPES = {
+    ANY: 'any'
+    // Future: ALL: 'all', SEQUENCE: 'sequence', WEIGHTED: 'weighted'
+};
+const SOURCE_LOGIC_TYPE_VALUES = Object.values(SOURCE_LOGIC_TYPES);
 
 exports.CampaignConditionType = void 0;
 (function (CampaignConditionType) {
@@ -3104,6 +3121,103 @@ const Domains = {
     AUDIT: 'audit',
 };
 
+/**
+ * SQL operator mapping for query operators
+ * Maps abstract query operators to SQL equivalents
+ */
+const QUERY_OPERATOR_SQL_MAP = {
+    eq: '=',
+    ne: '!=',
+    gt: '>',
+    gte: '>=',
+    lt: '<',
+    lte: '<=',
+    in: 'IN',
+    nin: 'NOT IN'
+};
+
+/**
+ * Helper to validate includes array at runtime
+ */
+const VALID_RELATIONS = ['user', 'campaign', 'business', 'triggerSource'];
+function isValidRelation(value) {
+    return VALID_RELATIONS.includes(value);
+}
+
+/**
+ * Valid transaction relations for runtime validation
+ */
+const VALID_TRANSACTION_RELATIONS = [
+    'sender',
+    'recipient',
+    'business'
+];
+/**
+ * Type guard to validate relation strings at runtime
+ */
+function isValidTransactionRelation(value) {
+    return VALID_TRANSACTION_RELATIONS.includes(value);
+}
+
+/**
+ * Array of all valid campaign include relations
+ * Used for runtime validation
+ */
+const VALID_CAMPAIGN_RELATIONS = [
+    'triggerSources',
+    'businesses'
+];
+/**
+ * Type guard to validate campaign include relation at runtime
+ *
+ * @param value - String to validate
+ * @returns True if value is a valid CampaignIncludeRelation
+ */
+function isValidCampaignRelation(value) {
+    return VALID_CAMPAIGN_RELATIONS.includes(value);
+}
+
+/**
+ * Array of all valid campaign claim include relations
+ * Used for runtime validation
+ */
+const VALID_CAMPAIGN_CLAIM_RELATIONS = [
+    'campaign',
+    'user',
+    'business',
+    'triggerSource',
+    'transactions'
+];
+/**
+ * Type guard to validate campaign claim include relation at runtime
+ *
+ * @param value - String to validate
+ * @returns True if value is a valid CampaignClaimIncludeRelation
+ */
+function isValidCampaignClaimRelation(value) {
+    return VALID_CAMPAIGN_CLAIM_RELATIONS.includes(value);
+}
+
+/**
+ * Array of all valid redemption redeem include relations
+ * Used for runtime validation
+ */
+const VALID_REDEMPTION_REDEEM_RELATIONS = [
+    'redemption',
+    'user',
+    'business',
+    'transactions'
+];
+/**
+ * Type guard to validate redemption redeem include relation at runtime
+ *
+ * @param value - String to validate
+ * @returns True if value is a valid RedemptionRedeemIncludeRelation
+ */
+function isValidRedemptionRedeemRelation(value) {
+    return VALID_REDEMPTION_REDEEM_RELATIONS.includes(value);
+}
+
 /**
  * Transaction format constants for Ethereum and EVM-compatible chains
  * Using const assertions for zero runtime overhead
@@ -3642,10 +3756,30 @@ class UserApi {
      * ADMIN: Get all remote users with query parameters
      * Uses new RESTful /users endpoint with role-based access
      * Note: Admin users get full data, non-admin users get public profiles only
+     *
+     * @param options - Pagination options (page, limit, sortBy, sortOrder)
+     * @param search - Optional search query to filter users
+     *
+     * @example
+     * ```typescript
+     * // Get users sorted by email
+     * const users = await sdk.users.getAllUsers({
+     *   page: 1,
+     *   limit: 10,
+     *   sortBy: 'email',
+     *   sortOrder: SortOrder.ASC
+     * });
+     *
+     * // Search for users
+     * const searchResults = await sdk.users.getAllUsers({ page: 1, limit: 10 }, 'john');
+     * ```
      */
-    async getAllRemoteUsers(options) {
+    async getAllRemoteUsers(options, search) {
         const params = buildPaginationParams(options);
-        const url = `${this.basePath}?merge=soft${params ? '&' + params.toString() : ''}`;
+        if (search) {
+            params.set('search', search);
+        }
+        const url = `${this.basePath}?merge=soft&${params.toString()}`;
         const response = await this.apiClient.get(url);
         return normalizeToPaginated(response);
     }
@@ -3740,9 +3874,11 @@ class UserService {
     /**
      * ADMIN: Get all remote users
      * ✅ FIXED: Matches API method signature (no parameters needed)
+     * @param options - Pagination options
+     * @param search - Optional search query
      */
-    async getAllRemoteUsers(options) {
-        return this.userApi.getAllRemoteUsers(options);
+    async getAllRemoteUsers(options, search) {
+        return this.userApi.getAllRemoteUsers(options, search);
     }
     /**
      * ADMIN: Update user as admin
@@ -4913,6 +5049,19 @@ class CampaignApi {
      * Get campaigns with pagination support
      * Returns paginated response with metadata (total, page, limit, hasMore)
      * Intelligent access: Public gets active only, Business gets own campaigns, Admin gets all
+     *
+     * @param options - Filter, pagination, and include options
+     * @param options.include - Relations to include: 'triggerSources', 'businesses'
+     *
+     * @example
+     * ```typescript
+     * // Get campaigns with trigger sources included
+     * const campaigns = await api.getCampaigns({ include: ['triggerSources'] });
+     * campaigns.data.forEach(c => console.log(c.included?.triggerSources));
+     *
+     * // Get campaigns with both relations
+     * const full = await api.getCampaigns({ include: ['triggerSources', 'businesses'] });
+     * ```
      */
     async getCampaigns(options) {
         const params = [];
@@ -4929,14 +5078,28 @@ class CampaignApi {
             params.push(`sortBy=${options.sortBy}`);
         if (options?.sortOrder)
             params.push(`sortOrder=${options.sortOrder}`);
+        if (options?.include?.length)
+            params.push(`include=${options.include.join(',')}`);
         return this.apiClient.get(`/campaigns?${params.join('&')}`);
     }
     /**
      * PUBLIC: Get campaign by ID
      * NEW: /campaigns/{id}
+     *
+     * @param id - Campaign UUID
+     * @param include - Relations to include: 'triggerSources', 'businesses'
+     *
+     * @example
+     * ```typescript
+     * // Get campaign with all relations
+     * const campaign = await api.getCampaignById('123', ['triggerSources', 'businesses']);
+     * console.log(campaign.included?.triggerSources);
+     * console.log(campaign.included?.businesses);
+     * ```
      */
-    async getCampaignById(id) {
-        return this.apiClient.get(`/campaigns/${id}`);
+    async getCampaignById(id, include) {
+        const params = include?.length ? `?include=${include.join(',')}` : '';
+        return this.apiClient.get(`/campaigns/${id}${params}`);
     }
     /**
      * ADMIN: Create campaign
@@ -5055,6 +5218,16 @@ class CampaignApi {
         const response = await this.apiClient.get(`/campaign-triggers?${params.toString()}`);
         return normalizeToPaginated(response);
     }
+    /**
+     * PUBLIC: Get campaign trigger by ID
+     * NEW: GET /campaign-triggers/{id}
+     *
+     * @param triggerId - Campaign trigger UUID
+     * @returns Campaign trigger details
+     */
+    async getCampaignTriggerById(triggerId) {
+        return this.apiClient.get(`/campaign-triggers/${triggerId}`);
+    }
     /**
      * ADMIN: Create campaign trigger
      * NEW: POST /campaign-triggers
@@ -5083,6 +5256,13 @@ class CampaignApi {
     async setCampaignTrigger(campaignId, triggerId) {
         return this.apiClient.put(`/campaign-triggers/${triggerId}/assign/${campaignId}`, {});
     }
+    /**
+     * ADMIN: Remove trigger from campaign (unassign)
+     * NEW: DELETE /campaign-triggers/{triggerId}/assign/{campaignId}
+     */
+    async removeCampaignTrigger(campaignId, triggerId) {
+        return this.apiClient.delete(`/campaign-triggers/${triggerId}/assign/${campaignId}`);
+    }
     /**
      * ADMIN: Add/Remove condition to trigger
      * NEW: PUT /campaign-triggers/{triggerId}/conditions/{conditionId}
@@ -5154,7 +5334,7 @@ class CampaignApi {
      * });
      * ```
      */
-    async getClaims(filters) {
+    async getClaims(filters, include) {
         const params = buildPaginationParams(filters);
         // Add filter parameters
         if (filters?.campaignId)
@@ -5163,6 +5343,10 @@ class CampaignApi {
             params.set('userId', filters.userId);
         if (filters?.businessId)
             params.set('businessId', filters.businessId);
+        // Add include parameter
+        if (include && include.length > 0) {
+            include.forEach(relation => params.append('include', relation));
+        }
         const endpoint = `/campaigns/claims?${params.toString()}`;
         const response = await this.apiClient.get(endpoint);
         return normalizeToPaginated(response);
@@ -5172,13 +5356,42 @@ class CampaignApi {
      * Uses /me endpoint for authenticated user context
      *
      * @param options - Pagination options
+     * @param include - Optional relations to include (campaign, user, business)
      * @returns Paginated list of user's claims
      */
-    async getClaimsLoggedUser(options) {
+    async getClaimsLoggedUser(options, include) {
         const params = buildPaginationParams(options);
+        // Add include parameter
+        if (include && include.length > 0) {
+            include.forEach(relation => params.append('include', relation));
+        }
         const response = await this.apiClient.get(`/campaigns/claims/me?${params.toString()}`);
         return normalizeToPaginated(response);
     }
+    // ==========================================
+    // TRIGGER SOURCE ASSIGNMENT (/campaigns/{id}/trigger-sources)
+    // Note: TriggerSource CRUD is in TriggerSourceApi
+    // ==========================================
+    /**
+     * ADMIN: Assign a trigger source to a campaign
+     *
+     * @param campaignId - Campaign UUID
+     * @param triggerSourceId - Trigger source UUID
+     * @returns Updated campaign with trigger source assigned
+     */
+    async assignTriggerSourceToCampaign(campaignId, triggerSourceId) {
+        return this.apiClient.put(`/campaigns/${campaignId}/trigger-sources/${triggerSourceId}`, {});
+    }
+    /**
+     * ADMIN: Remove a trigger source from a campaign
+     *
+     * @param campaignId - Campaign UUID
+     * @param triggerSourceId - Trigger source UUID
+     * @returns Updated campaign with trigger source removed
+     */
+    async removeTriggerSourceFromCampaign(campaignId, triggerSourceId) {
+        return this.apiClient.delete(`/campaigns/${campaignId}/trigger-sources/${triggerSourceId}`);
+    }
 }
 
 /**
@@ -5198,9 +5411,11 @@ class CampaignService {
     // ==========================================
     /**
      * PUBLIC: Get campaign by ID
+     * @param id - Campaign UUID
+     * @param include - Relations to include: 'triggerSources', 'businesses'
      */
-    async getCampaignById(id) {
-        return this.campaignApi.getCampaignById(id);
+    async getCampaignById(id, include) {
+        return this.campaignApi.getCampaignById(id, include);
     }
     // ==========================================
     // AUTHENTICATED OPERATIONS
@@ -5213,9 +5428,11 @@ class CampaignService {
     }
     /**
      * AUTH: Get claims for logged user with pagination
+     * @param options - Pagination options
+     * @param include - Optional relations to include (campaign, user, business)
      */
-    async getClaimsForLoggedUser(options) {
-        return this.campaignApi.getClaimsLoggedUser(options);
+    async getClaimsForLoggedUser(options, include) {
+        return this.campaignApi.getClaimsLoggedUser(options, include);
     }
     // ==========================================
     // CAMPAIGN OPERATIONS (Paginated)
@@ -5229,6 +5446,7 @@ class CampaignService {
      * @param options.limit - Items per page (default: 50)
      * @param options.sortBy - Sort field
      * @param options.sortOrder - Sort direction
+     * @param options.include - Relations to include: 'triggerSources', 'businesses'
      */
     async getCampaigns(options) {
         return this.campaignApi.getCampaigns(options);
@@ -5239,6 +5457,30 @@ class CampaignService {
     async getCampaignTriggers(options) {
         return this.campaignApi.getCampaignTriggers(options);
     }
+    /**
+     * ADMIN: Get campaign trigger by ID
+     */
+    async getCampaignTriggerById(triggerId) {
+        return this.campaignApi.getCampaignTriggerById(triggerId);
+    }
+    /**
+     * ADMIN: Create campaign trigger
+     */
+    async createCampaignTrigger(data) {
+        return this.campaignApi.createCampaignTrigger(data);
+    }
+    /**
+     * ADMIN: Update campaign trigger
+     */
+    async updateCampaignTrigger(triggerId, data) {
+        return this.campaignApi.updateCampaignTrigger(triggerId, data);
+    }
+    /**
+     * ADMIN: Delete campaign trigger
+     */
+    async deleteCampaignTrigger(triggerId) {
+        return this.campaignApi.deleteCampaignTrigger(triggerId);
+    }
     /**
      * ADMIN: Toggle campaign active status
      */
@@ -5263,6 +5505,12 @@ class CampaignService {
     async setCampaignTrigger(campaignId, triggerId) {
         return this.campaignApi.setCampaignTrigger(campaignId, triggerId);
     }
+    /**
+     * ADMIN: Remove trigger from campaign (unassign)
+     */
+    async removeCampaignTrigger(campaignId, triggerId) {
+        return this.campaignApi.removeCampaignTrigger(campaignId, triggerId);
+    }
     /**
      * ADMIN: Update campaign
      */
@@ -5298,21 +5546,45 @@ class CampaignService {
     }
     /**
      * ADMIN: Get campaign claims with optional filters and pagination
+     * @param filters - Filter and pagination options
+     * @param include - Optional relations to include (campaign, user, business)
      */
-    async getCampaignClaims(filters) {
-        return this.campaignApi.getClaims(filters);
+    async getCampaignClaims(filters, include) {
+        return this.campaignApi.getClaims(filters, include);
     }
     /**
      * ADMIN: Get campaign claims by user ID with pagination
+     * @param userId - User ID to filter by
+     * @param options - Pagination options
+     * @param include - Optional relations to include (campaign, user, business)
      */
-    async getCampaignClaimsByUserId(userId, options) {
-        return this.campaignApi.getClaims({ userId, ...options });
+    async getCampaignClaimsByUserId(userId, options, include) {
+        return this.campaignApi.getClaims({ userId, ...options }, include);
     }
     /**
      * ADMIN: Get campaign claims by business ID with pagination
+     * @param businessId - Business ID to filter by
+     * @param options - Pagination options
+     * @param include - Optional relations to include (campaign, user, business)
+     */
+    async getCampaignClaimsByBusinessId(businessId, options, include) {
+        return this.campaignApi.getClaims({ businessId, ...options }, include);
+    }
+    // ==========================================
+    // TRIGGER SOURCE ASSIGNMENT
+    // Note: TriggerSource CRUD is in TriggerSourceService
+    // ==========================================
+    /**
+     * ADMIN: Assign a trigger source to a campaign
      */
-    async getCampaignClaimsByBusinessId(businessId, options) {
-        return this.campaignApi.getClaims({ businessId, ...options });
+    async assignTriggerSourceToCampaign(campaignId, triggerSourceId) {
+        return this.campaignApi.assignTriggerSourceToCampaign(campaignId, triggerSourceId);
+    }
+    /**
+     * ADMIN: Remove a trigger source from a campaign
+     */
+    async removeTriggerSourceFromCampaign(campaignId, triggerSourceId) {
+        return this.campaignApi.removeTriggerSourceFromCampaign(campaignId, triggerSourceId);
     }
 }
 
@@ -5344,12 +5616,7 @@ class RedemptionApi {
      * - Public users: Get active redemptions only
      * - Admin users: Get all redemptions with optional filtering
      *
-     * @param options.active - Filter by active status (undefined = all for admins/active for public)
-     * @param options.adminAccess - Force admin access (requires admin auth)
-     * @param options.page - Page number (default: 1)
-     * @param options.limit - Items per page (default: 50)
-     * @param options.sortBy - Sort field
-     * @param options.sortOrder - Sort order (asc/desc)
+     * @param options - Filter and pagination options (active, adminAccess, page, limit, sortBy, sortOrder)
      * @returns Paginated response with redemptions
      */
     async getRedemptions(options) {
@@ -5416,17 +5683,11 @@ class RedemptionApi {
      * - Users: See only their own redeems (userId/businessId filters ignored)
      * - Admins: Can filter by userId, businessId, or redemptionId
      *
-     * @param filters.redemptionId - Filter by specific redemption
-     * @param filters.userId - Admin only: Filter by user ID
-     * @param filters.businessId - Admin only: Filter by business ID
-     * @param filters.myRedeems - Force user's own redeems (uses /me endpoint)
-     * @param filters.page - Page number (default: 1)
-     * @param filters.limit - Items per page (default: 50)
-     * @param filters.sortBy - Sort field
-     * @param filters.sortOrder - Sort order (asc/desc)
+     * @param filters - Filter and pagination options (redemptionId, userId, businessId, myRedeems, page, limit, sortBy, sortOrder)
+     * @param include - Optional relations to include (redemption, user, business)
      * @returns Paginated response with redemption redeems
      */
-    async getRedemptionRedeems(filters) {
+    async getRedemptionRedeems(filters, include) {
         let url = `${this.basePath}/redeems`;
         const params = buildPaginationParams(filters);
         // Use convenience endpoint for user's own redeems
@@ -5435,6 +5696,10 @@ class RedemptionApi {
             if (filters?.redemptionId) {
                 params.append('redemptionId', filters.redemptionId);
             }
+            // Add include parameter
+            if (include && include.length > 0) {
+                include.forEach(relation => params.append('include', relation));
+            }
             const response = await this.apiClient.get(`${url}?${params.toString()}`);
             return normalizeToPaginated(response);
         }
@@ -5445,14 +5710,26 @@ class RedemptionApi {
             params.append('userId', filters.userId);
         if (filters?.businessId)
             params.append('businessId', filters.businessId);
+        // Add include parameter
+        if (include && include.length > 0) {
+            include.forEach(relation => params.append('include', relation));
+        }
         const response = await this.apiClient.get(`${url}?${params.toString()}`);
         return normalizeToPaginated(response);
     }
     /**
      * UNIFIED: Get specific redemption redeem by ID
+     * @param id - Redemption redeem ID
+     * @param include - Optional relations to include (redemption, user, business)
      */
-    async getRedemptionRedeemById(id) {
-        return this.apiClient.get(`${this.basePath}/redeems/${id}`);
+    async getRedemptionRedeemById(id, include) {
+        const params = new URLSearchParams();
+        // Add include parameter
+        if (include && include.length > 0) {
+            include.forEach(relation => params.append('include', relation));
+        }
+        const url = `${this.basePath}/redeems/${id}${params.toString() ? `?${params.toString()}` : ''}`;
+        return this.apiClient.get(url);
     }
     // ==========================================
     // USER OPERATIONS (JWT + Project Key)
@@ -5463,10 +5740,11 @@ class RedemptionApi {
      * Uses convenience endpoint /redemption-redeems/me with optional filtering
      * @param redemptionId - Optional filter by specific redemption
      * @param options - Pagination options (page, limit, sortBy, sortOrder)
+     * @param include - Optional relations to include (redemption, user, business)
      * @returns Paginated response with user's redemption redeems
      */
-    async getUserRedeems(redemptionId, options) {
-        return this.getRedemptionRedeems({ myRedeems: true, redemptionId, ...options });
+    async getUserRedeems(redemptionId, options, include) {
+        return this.getRedemptionRedeems({ myRedeems: true, redemptionId, ...options }, include);
     }
     // ==========================================
     // ADMIN OPERATIONS (Tenant Admin JWT)
@@ -5599,15 +5877,19 @@ class RedemptionService {
     }
     /**
      * UNIFIED: Get redemption redeems with filtering and pagination
+     * @param filters - Filter options
+     * @param include - Optional relations to include (redemption, user, business)
      */
-    async getRedemptionRedeems(filters) {
-        return this.redemptionApi.getRedemptionRedeems(filters);
+    async getRedemptionRedeems(filters, include) {
+        return this.redemptionApi.getRedemptionRedeems(filters, include);
     }
     /**
      * Convenience: Get user redemptions with pagination
+     * @param options - Pagination options
+     * @param include - Optional relations to include (redemption, user, business)
      */
-    async getUserRedeems(options) {
-        return this.redemptionApi.getUserRedeems(undefined, options);
+    async getUserRedeems(options, include) {
+        return this.redemptionApi.getUserRedeems(undefined, options, include);
     }
     // ==========================================
     // ADMIN OPERATIONS
@@ -5672,9 +5954,19 @@ class TransactionApi {
      * Get transaction by ID (public endpoint)
      *
      * UPDATED: /transaction/{id} → /transactions/{id}
+     * UPDATED: Added support for include parameter to enrich with sender/recipient/business entities
+     *
+     * @param transactionId - Transaction ID
+     * @param include - Optional relations to include (sender, recipient, business)
      */
-    async getTransactionById(transactionId) {
-        return this.apiClient.get(`${this.basePath}/${transactionId}`);
+    async getTransactionById(transactionId, include) {
+        let url = `${this.basePath}/${transactionId}`;
+        if (include && include.length > 0) {
+            const params = new URLSearchParams();
+            include.forEach(relation => params.append('include', relation));
+            url += `?${params.toString()}`;
+        }
+        return this.apiClient.get(url);
     }
     /**
      * Unique method to create a transaction
@@ -5688,13 +5980,78 @@ class TransactionApi {
     // ==========================================
     // AUTHENTICATED USER OPERATIONS
     // ==========================================
+    /**
+     * Helper to build query params from TransactionQueryOptions
+     * Handles all filter options and include parameter
+     */
+    buildTransactionQueryParams(options) {
+        const params = buildPaginationParams(options);
+        if (!options)
+            return params;
+        // Search and identification filters
+        if (options.search)
+            params.append('search', options.search);
+        if (options.participantId)
+            params.append('participantId', options.participantId);
+        if (options.participantAddress)
+            params.append('participantAddress', options.participantAddress);
+        // Business and process filters
+        if (options.engagedBusinessId)
+            params.append('engagedBusinessId', options.engagedBusinessId);
+        if (options.businessScopeId)
+            params.append('businessScopeId', options.businessScopeId);
+        if (options.triggerProcessId)
+            params.append('triggerProcessId', options.triggerProcessId);
+        // Token filters
+        if (options.tokenAddress)
+            params.append('tokenAddress', options.tokenAddress);
+        if (options.tokenType) {
+            if (Array.isArray(options.tokenType)) {
+                options.tokenType.forEach(type => params.append('tokenType', type));
+            }
+            else {
+                params.append('tokenType', options.tokenType);
+            }
+        }
+        // Transaction classification filters (arrays or single values)
+        if (options.role) {
+            if (Array.isArray(options.role)) {
+                options.role.forEach(role => params.append('role', role));
+            }
+            else {
+                params.append('role', options.role);
+            }
+        }
+        if (options.status) {
+            if (Array.isArray(options.status)) {
+                options.status.forEach(status => params.append('status', status));
+            }
+            else {
+                params.append('status', options.status);
+            }
+        }
+        if (options.type) {
+            if (Array.isArray(options.type)) {
+                options.type.forEach(type => params.append('type', type));
+            }
+            else {
+                params.append('type', options.type);
+            }
+        }
+        // Include relations for entity enrichment
+        if (options.include && options.include.length > 0) {
+            options.include.forEach(relation => params.append('include', relation));
+        }
+        return params;
+    }
     /**
      * AUTH: Get user transaction history with role-based filtering and pagination
      *
-     * UPDATED: Uses consolidated /transactions/me endpoint with role parameter
-     * FIXED: Now correctly returns paginated response (was incorrectly unwrapping to array)
+     * UPDATED: Uses consolidated /transactions/me endpoint with all filter options
+     * UPDATED: Added support for include parameter to enrich with sender/recipient/business entities
+     * UPDATED: Now supports all TransactionFiltersDTO filters (triggerProcessId, status, type, etc.)
      *
-     * @param options - Pagination and filter options
+     * @param options - Pagination, filter, and include options
      * @returns Paginated list of user's transactions
      *
      * @example
@@ -5702,24 +6059,30 @@ class TransactionApi {
      * // Get first page of all transactions
      * const page1 = await transactionApi.getUserTransactionHistory();
      *
-     * // Filter by role
-     * const sent = await transactionApi.getUserTransactionHistory({
+     * // Filter by role and status
+     * const completed = await transactionApi.getUserTransactionHistory({
      *   role: TransactionRole.SENDER,
+     *   status: TransactionStatus.COMPLETED,
      *   page: 1,
      *   limit: 50
      * });
      *
-     * // Access data and pagination
-     * console.log(`Showing ${page1.data.length} of ${page1.pagination.total} transactions`);
+     * // Filter by trigger process (e.g., from campaign claim or redemption)
+     * const claimTransactions = await transactionApi.getUserTransactionHistory({
+     *   triggerProcessId: 'claim-abc123',
+     *   include: ['sender', 'recipient', 'business']
+     * });
+     *
+     * // Access included entities
+     * claimTransactions.data.forEach(tx => {
+     *   if (tx.included?.engagedBusiness) {
+     *     console.log('Business:', tx.included.engagedBusiness.displayName);
+     *   }
+     * });
      * ```
      */
     async getUserTransactionHistory(options) {
-        const params = buildPaginationParams(options);
-        // Add role parameter if specified
-        if (options?.role) {
-            params.set('role', options.role);
-        }
-        // Backend already returns PaginatedResponseDTO - return it directly
+        const params = this.buildTransactionQueryParams(options);
         return this.apiClient.get(`${this.basePath}/me?${params.toString()}`);
     }
     /**
@@ -5769,45 +6132,17 @@ class TransactionApi {
     async prepareClientSignedTransaction(request) {
         return this.apiClient.post(`${this.basePath}`, request);
     }
-    /**
-     * ADMIN: Get all tenant transactions with pagination and filtering
-     *
-     * UPDATED: /transaction/admin → /transactions
-     * FIXED: Now correctly returns paginated response (was incorrectly unwrapping to array)
-     *
-     * @param options - Pagination and filter options
-     * @returns Paginated list of tenant transactions
-     *
-     * @example
-     * ```typescript
-     * // Get first page
-     * const page1 = await transactionApi.getTenantTransactions();
-     *
-     * // Get specific page with custom limit
-     * const page2 = await transactionApi.getTenantTransactions({
-     *   page: 2,
-     *   limit: 100
-     * });
-     *
-     * // Access data
-     * page1.data.forEach(tx => console.log(tx.id));
-     * ```
-     *
-     * @deprecated Consider using getPaginatedTransactions() for more advanced filtering
-     */
-    async getTenantTransactions(options) {
-        const params = buildPaginationParams(options);
-        // Backend already returns PaginatedResponseDTO - return it directly
-        return this.apiClient.get(`${this.basePath}?${params.toString()}`);
-    }
     /**
      * ADMIN: Get paginated transactions with filtering and sorting
      *
      * UPDATED: /transaction/admin → /transactions (same endpoint, better structure)
+     *
+     * @param options - Pagination request with filters and optional include relations
      */
-    async getPaginatedTransactions(params) {
-        const queryString = this.buildQueryParams(params).toString();
-        return this.apiClient.get(`${this.basePath}?${queryString}`);
+    async getPaginatedTransactions(options) {
+        const queryString = this.buildQueryParams(options).toString();
+        const fullUrl = `${this.basePath}?${queryString}`;
+        return this.apiClient.get(fullUrl);
     }
     /**
      * ADMIN: Export transactions to CSV
@@ -5861,7 +6196,7 @@ class TransactionApi {
     }
     /**
      * Helper to convert DTO object to URLSearchParams
-     * Handles nested 'filters' object and arrays correctly.
+     * Handles nested 'filters' object, arrays, and include parameter correctly.
      */
     buildQueryParams(params) {
         const query = new URLSearchParams();
@@ -5874,7 +6209,11 @@ class TransactionApi {
             query.append('sortBy', params.sortBy);
         if (params.sortOrder)
             query.append('sortOrder', params.sortOrder);
-        // 2. Handle Nested Filters
+        // 2. Handle Include Relations (root level)
+        if (params.include && params.include.length > 0) {
+            params.include.forEach((relation) => query.append('include', relation));
+        }
+        // 3. Handle Nested Filters
         if (params.filters) {
             Object.entries(params.filters).forEach(([key, value]) => {
                 // Skip undefined/null values
@@ -5912,9 +6251,12 @@ class TransactionService {
     }
     /**
      * Get transaction by ID
+     *
+     * @param transactionId - Transaction ID
+     * @param include - Optional relations to include (sender, recipient, business)
      */
-    async getTransactionById(transactionId) {
-        return this.transactionApi.getTransactionById(transactionId);
+    async getTransactionById(transactionId, include) {
+        return this.transactionApi.getTransactionById(transactionId, include);
     }
     // ==========================================
     // AUTHENTICATED OPERATIONS
@@ -5932,14 +6274,13 @@ class TransactionService {
         return this.transactionApi.submitSignedTransaction(signedTxData);
     }
     /**
-     * AUTH: Get user transaction history by type with pagination
+     * AUTH: Get user transaction history with comprehensive filtering
      *
-     * @param role - Optional transaction role filter
-     * @param options - Pagination options
+     * @param options - Query options including filters, pagination, and include relations
      * @returns Paginated transaction history
      */
-    async getUserTransactionHistory(role, options) {
-        return this.transactionApi.getUserTransactionHistory({ role, ...options });
+    async getUserTransactionHistory(options) {
+        return this.transactionApi.getUserTransactionHistory(options);
     }
     /**
      * AUTH: Prepare existing transaction for client-side signing
@@ -5971,20 +6312,11 @@ class TransactionService {
     /* async createAdminTransaction(request: TransactionRequestDTO): Promise<TransactionRequestResponseDTO> {
       return this.transactionApi.createAdminTransaction(request);
     } */
-    /**
-     * ADMIN: Get all tenant transactions with pagination
-     *
-     * @param options - Pagination options
-     * @returns Paginated tenant transactions
-     */
-    async getTenantTransactions(options) {
-        return this.transactionApi.getTenantTransactions(options || {});
-    }
     /**
      * ADMIN: Get paginated transactions with filtering and sorting
      */
-    async getPaginatedTransactions(params) {
-        return this.transactionApi.getPaginatedTransactions(params);
+    async getPaginatedTransactions(options) {
+        return this.transactionApi.getPaginatedTransactions(options);
     }
     /**
      * ADMIN: Export transactions to CSV
@@ -6739,7 +7071,191 @@ class AnalyticsApi {
      * ADMIN: Get transaction analytics with filtering and aggregation
      */
     async getTransactionAnalytics(request) {
-        return this.apiClient.post('/transactions/analytics', request);
+        return this.apiClient.post('/analytics/transactions', request);
+    }
+    /**
+     * ADMIN: Get campaign claim analytics with aggregation (charts, metrics, grouping)
+     *
+     * This endpoint is for aggregated analytics only (groupBy/metrics).
+     * For enriched list data with nested objects, use campaign.getClaims() instead.
+     *
+     * @example Claims per campaign
+     * ```typescript
+     * const response = await analyticsApi.getCampaignClaimAnalytics({
+     *   filters: { status: 'COMPLETED' },
+     *   groupBy: ['campaignId'],
+     *   metrics: ['count'],
+     *   sortBy: 'count',
+     *   sortOrder: SortOrder.DESC,
+     *   limit: 10
+     * });
+     * ```
+     *
+     * @example Claims over time by status
+     * ```typescript
+     * const response = await analyticsApi.getCampaignClaimAnalytics({
+     *   groupBy: ['month', 'status'],
+     *   metrics: ['count'],
+     *   sortBy: 'month',
+     *   sortOrder: SortOrder.DESC,
+     *   startDate: new Date('2026-01-01'),
+     *   endDate: new Date('2026-12-31')
+     * });
+     * ```
+     */
+    async getCampaignClaimAnalytics(request) {
+        return this.apiClient.post('/analytics/campaign-claims', request);
+    }
+    /**
+     * ADMIN: Get user analytics with engagement metrics
+     *
+     * Returns aggregated user statistics including engagement rate, active users,
+     * transaction metrics, and per-active-user averages (more accurate than all-user averages).
+     *
+     * Request structure matches TransactionAnalytics and CampaignClaimAnalytics for consistency:
+     * - filters object for business-specific scoping
+     * - startDate/endDate at root level for date range filtering
+     *
+     * @param request - Analytics request with optional filters and date range
+     * @returns Aggregated user metrics with per-user and per-active-user averages
+     *
+     * @example Basic user analytics (all time, all businesses)
+     * ```typescript
+     * const analytics = await analyticsApi.getUserAnalytics({});
+     * console.log(`Total users: ${analytics.totalUsers}`);
+     * console.log(`Active users: ${analytics.activeUsers}`);
+     * console.log(`Engagement rate: ${analytics.engagementRate}%`);
+     *
+     * // Per-user averages (includes inactive users)
+     * console.log(`Avg transactions per user: ${analytics.averageTransactionsPerUser}`);
+     *
+     * // Per-active-user averages (only engaged users - more useful!)
+     * console.log(`Avg transactions per active user: ${analytics.averageTransactionsPerActiveUser}`);
+     * ```
+     *
+     * @example Filtered by date range
+     * ```typescript
+     * const analytics = await analyticsApi.getUserAnalytics({
+     *   startDate: new Date('2026-01-01'),
+     *   endDate: new Date('2026-01-31')
+     * });
+     * console.log(`January metrics:`);
+     * console.log(`Active users: ${analytics.activeUsers}`);
+     * console.log(`New users: ${analytics.newUsers}`);
+     * console.log(`Date range applied: ${analytics.metadata.dateRange?.startDate} - ${analytics.metadata.dateRange?.endDate}`);
+     * ```
+     *
+     * @example Business-specific analytics with filters
+     * ```typescript
+     * const analytics = await analyticsApi.getUserAnalytics({
+     *   filters: { businessId: 'biz-123' },
+     *   startDate: new Date('2026-01-01'),
+     *   endDate: new Date('2026-12-31')
+     * });
+     * console.log(`Business customer engagement in 2026:`);
+     * console.log(`Active customers: ${analytics.activeUsers}`);
+     * console.log(`Avg claims per active customer: ${analytics.averageClaimsPerActiveUser.toFixed(2)}`);
+     * console.log(`Customer engagement rate: ${analytics.engagementRate.toFixed(1)}%`);
+     * ```
+     */
+    async getUserAnalytics(request = {}) {
+        return this.apiClient.post('/analytics/users', request);
+    }
+    /**
+     * ADMIN: Get user transaction ranking with enriched user data
+     *
+     * Returns ranked list of users with full user details and transaction metrics.
+     * Data enrichment happens via efficient SQL JOINs + UNION (handles legacy transactions).
+     *
+     * Use Cases:
+     * - Admin leaderboards showing top users by activity
+     * - User engagement analysis with full user context
+     * - Identifying power users for campaigns
+     *
+     * @param request - Ranking request with filters, sorting, and limit
+     * @returns Ranked list with user details (email, externalUserId) and transaction metrics
+     *
+     * @example Top 50 users by transaction count
+     * ```typescript
+     * const ranking = await analyticsApi.getUserRanking({
+     *   sortBy: 'totalTransactions',
+     *   sortOrder: SortOrder.DESC,
+     *   limit: 50
+     * });
+     *
+     * ranking.results.forEach((user, index) => {
+     *   console.log(`#${index + 1}: ${user.email || user.externalUserId} - ${user.totalTransactions} transactions`);
+     * });
+     * ```
+     *
+     * @example Top users by STAMP spending
+     * ```typescript
+     * const ranking = await analyticsApi.getUserRanking({
+     *   filters: { tokenType: 'STAMP' },
+     *   sortBy: 'tokenSpent',
+     *   sortOrder: SortOrder.DESC,
+     *   limit: 20
+     * });
+     * ```
+     *
+     * @example Business-specific leaderboard with date range
+     * ```typescript
+     * const ranking = await analyticsApi.getUserRanking({
+     *   filters: {
+     *     businessId: 'business-uuid-here',
+     *     tokenType: 'CREDIT'
+     *   },
+     *   sortBy: 'totalTransactions',
+     *   sortOrder: SortOrder.DESC,
+     *   limit: 100,
+     *   startDate: new Date('2026-01-01'),
+     *   endDate: new Date('2026-12-31')
+     * });
+     * console.log(`Top ${ranking.totalUsers} users for business in 2026`);
+     * ```
+     */
+    async getUserRanking(request = {}) {
+        return this.apiClient.post('/analytics/users/ranking', request);
+    }
+    /**
+     * ADMIN: Get business transaction ranking with enriched business data
+     *
+     * Returns ranked list of businesses with full business details and transaction metrics.
+     * Data enrichment happens via efficient SQL JOINs + UNION (handles legacy transactions).
+     *
+     * @param request - Ranking request with filters, sorting, and limit
+     * @returns Ranked list with business details and transaction metrics
+     *
+     * @example Top 50 businesses by transaction count
+     * ```typescript
+     * const ranking = await analyticsApi.getBusinessRanking({
+     *   sortBy: 'totalTransactions',
+     *   sortOrder: SortOrder.DESC,
+     *   limit: 50
+     * });
+     * ```
+     */
+    async getBusinessRanking(request = {}) {
+        return this.apiClient.post('/analytics/businesses/ranking', request);
+    }
+    /**
+     * ADMIN: Get monthly user retention analytics
+     *
+     * Returns monthly retention data with active/new/returning users and retention rates.
+     * Replaces 13 separate API calls with 1 efficient recursive CTE query.
+     *
+     * @param request - Retention analytics request with monthsBack and filters
+     * @returns Monthly retention data with user metrics and retention rates
+     *
+     * @example Last 13 months retention
+     * ```typescript
+     * const retention = await analyticsApi.getRetentionAnalytics({
+     *   monthsBack: 13
+     * });
+     * ```
+     */
+    async getRetentionAnalytics(request = {}) {
+        return this.apiClient.post('/analytics/users/retention', request);
     }
 }
 
@@ -6764,6 +7280,47 @@ class AnalyticsService {
     async getTransactionAnalytics(request) {
         return this.analyticsApi.getTransactionAnalytics(request);
     }
+    /**
+     * ADMIN: Get campaign claim analytics with aggregation
+     */
+    async getCampaignClaimAnalytics(request) {
+        return this.analyticsApi.getCampaignClaimAnalytics(request);
+    }
+    /**
+     * ADMIN: Get user analytics with engagement metrics
+     *
+     * Returns aggregated user statistics including engagement rate, active users,
+     * transaction metrics, and claims/redemption averages.
+     */
+    async getUserAnalytics(request = {}) {
+        return this.analyticsApi.getUserAnalytics(request);
+    }
+    /**
+     * ADMIN: Get user transaction ranking with enriched user data
+     *
+     * Returns ranked list of users with full user details (email, externalUserId)
+     * and transaction metrics. Efficient data enrichment via SQL JOINs + UNION.
+     */
+    async getUserRanking(request = {}) {
+        return this.analyticsApi.getUserRanking(request);
+    }
+    /**
+     * ADMIN: Get business transaction ranking with enriched business data
+     *
+     * Returns ranked list of businesses with full business details and transaction metrics.
+     */
+    async getBusinessRanking(request = {}) {
+        return this.analyticsApi.getBusinessRanking(request);
+    }
+    /**
+     * ADMIN: Get monthly user retention analytics
+     *
+     * Returns monthly retention data with user metrics and retention rates.
+     * Replaces 13 separate API calls with 1 efficient query.
+     */
+    async getRetentionAnalytics(request = {}) {
+        return this.analyticsApi.getRetentionAnalytics(request);
+    }
 }
 
 /**
@@ -6813,6 +7370,144 @@ class DonationService {
     }
 }
 
+/**
+ * Platform-Agnostic TriggerSource API Client
+ *
+ * Handles all trigger source operations:
+ * - CRUD operations for trigger sources (QR codes, NFC tags, GPS geofences, webhooks, etc.)
+ * - Trigger sources are independent entities that can be assigned to campaigns
+ *
+ * Uses @explorins/pers-shared DTOs for consistency with backend.
+ */
+class TriggerSourceApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    /**
+     * PUBLIC: Get trigger sources with optional filters and pagination
+     *
+     * @param options - Filter and pagination options
+     * @returns Paginated list of trigger sources
+     *
+     * @example
+     * ```typescript
+     * // Get all QR code trigger sources
+     * const qrSources = await triggerSourceApi.getTriggerSources({ type: 'QR_CODE' });
+     *
+     * // Get trigger sources for a specific campaign
+     * const campaignSources = await triggerSourceApi.getTriggerSources({
+     *   campaignId: 'campaign-123',
+     *   page: 1,
+     *   limit: 20
+     * });
+     * ```
+     */
+    async getTriggerSources(options) {
+        const params = buildPaginationParams(options);
+        if (options?.type)
+            params.set('type', options.type);
+        if (options?.businessId)
+            params.set('businessId', options.businessId);
+        if (options?.campaignId)
+            params.set('campaignId', options.campaignId);
+        if (options?.active !== undefined)
+            params.set('active', String(options.active));
+        const response = await this.apiClient.get(`/trigger-sources?${params.toString()}`);
+        return normalizeToPaginated(response);
+    }
+    /**
+     * PUBLIC: Get trigger source by ID
+     *
+     * @param triggerSourceId - UUID of the trigger source
+     * @returns Trigger source details
+     */
+    async getTriggerSourceById(triggerSourceId) {
+        return this.apiClient.get(`/trigger-sources/${triggerSourceId}`);
+    }
+    /**
+     * ADMIN: Create a new trigger source
+     *
+     * @param triggerSource - Trigger source creation data
+     * @returns Created trigger source
+     *
+     * @example
+     * ```typescript
+     * const qrSource = await triggerSourceApi.createTriggerSource({
+     *   type: 'QR_CODE',
+     *   name: 'Store Entrance QR',
+     *   description: 'QR code at main entrance',
+     *   businessId: 'business-123',
+     *   coordsLatitude: 47.6062,
+     *   coordsLongitude: -122.3321
+     * });
+     * ```
+     */
+    async createTriggerSource(triggerSource) {
+        return this.apiClient.post('/trigger-sources', triggerSource);
+    }
+    /**
+     * ADMIN: Update a trigger source
+     *
+     * @param triggerSourceId - UUID of the trigger source to update
+     * @param triggerSource - Updated trigger source data (partial)
+     * @returns Updated trigger source
+     */
+    async updateTriggerSource(triggerSourceId, triggerSource) {
+        return this.apiClient.put(`/trigger-sources/${triggerSourceId}`, triggerSource);
+    }
+    /**
+     * ADMIN: Delete (soft delete) a trigger source
+     *
+     * @param triggerSourceId - UUID of the trigger source to delete
+     * @returns Success status
+     */
+    async deleteTriggerSource(triggerSourceId) {
+        return this.apiClient.delete(`/trigger-sources/${triggerSourceId}`);
+    }
+}
+
+/**
+ * Platform-Agnostic TriggerSource Service
+ *
+ * Contains trigger source business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ */
+class TriggerSourceService {
+    constructor(triggerSourceApi) {
+        this.triggerSourceApi = triggerSourceApi;
+    }
+    /**
+     * Get trigger sources with optional filters
+     */
+    async getTriggerSources(options) {
+        return this.triggerSourceApi.getTriggerSources(options);
+    }
+    /**
+     * Get trigger source by ID
+     */
+    async getTriggerSourceById(triggerSourceId) {
+        return this.triggerSourceApi.getTriggerSourceById(triggerSourceId);
+    }
+    /**
+     * ADMIN: Create a new trigger source
+     */
+    async createTriggerSource(triggerSource) {
+        return this.triggerSourceApi.createTriggerSource(triggerSource);
+    }
+    /**
+     * ADMIN: Update a trigger source
+     */
+    async updateTriggerSource(triggerSourceId, triggerSource) {
+        return this.triggerSourceApi.updateTriggerSource(triggerSourceId, triggerSource);
+    }
+    /**
+     * ADMIN: Delete a trigger source
+     */
+    async deleteTriggerSource(triggerSourceId) {
+        return this.triggerSourceApi.deleteTriggerSource(triggerSourceId);
+    }
+}
+
 /**
  * PERS SDK Configuration interfaces and utilities
  *
@@ -6828,8 +7523,7 @@ const DEFAULT_PERS_CONFIG = {
     timeout: 30000,
     retries: 3,
     tokenRefreshMargin: 60, // Refresh tokens 60 seconds before expiry
-    backgroundRefreshThreshold: 30, // Use background refresh if >30s remaining
-    autoRestoreSession: true // Automatically restore session on initialization
+    backgroundRefreshThreshold: 30 // Use background refresh if >30s remaining
 };
 /**
  * Internal function to construct API root from environment
@@ -6897,10 +7591,7 @@ class AuthApi {
      * Authenticates a user in a business context with role included in JWT.
      *
      * @param jwt - Authentication token (passkey or Firebase JWT)
-     * @param options - Business authentication options
-     * @param options.businessId - The business ID to authenticate as
-     *   - If user has single business membership, auto-selected
-     *   - If user has multiple memberships without businessId, throws MULTIPLE_CONTEXT_SELECTION_REQUIRED
+     * @param options - Business authentication options (businessId for multi-business users, auto-selected if single membership)
      * @returns Session response with business context and role in JWT
      * @throws MultipleContextSelectionError when businessId is required but not provided
      *
@@ -7019,10 +7710,7 @@ class AuthService {
      * the user's role within that business.
      *
      * @param jwt - Authentication token (passkey or Firebase JWT)
-     * @param options - Business authentication options
-     * @param options.businessId - The business ID to authenticate as
-     *   - If user has single business membership, auto-selected
-     *   - If user has multiple memberships without businessId, throws MULTIPLE_CONTEXT_SELECTION_REQUIRED
+     * @param options - Business authentication options (businessId for multi-business users)
      * @returns Session response with business context and role baked into JWT
      * @throws MultipleContextSelectionRequiredError when businessId is required but not provided
      *
@@ -7139,8 +7827,12 @@ class AuthService {
                 await extendedProvider.setProviderToken(providerToken);
             }
             if (authType && extendedProvider.setAuthType) {
+                console.log('[AuthService] Storing auth type:', authType);
                 await extendedProvider.setAuthType(authType);
             }
+            else {
+                console.warn('[AuthService] Auth type not stored - authType:', authType, 'has setAuthType:', !!extendedProvider.setAuthType);
+            }
             // Emit authenticated status on successful token storage
             await this.emitAuthStatus(AuthStatus.AUTHENTICATED);
         }
@@ -7159,8 +7851,15 @@ class TokenRefreshManager {
         this.authService = authService;
         this.authProvider = authProvider;
         this.tokenRefreshMarginSeconds = 120; // 2 minutes
+        this.lastValidationTime = 0;
+        this.validationCacheDurationMs = 30000; // 30 seconds
     }
     async ensureValidToken() {
+        const now = Date.now();
+        // Skip validation if we checked recently (within cache duration)
+        if (now - this.lastValidationTime < this.validationCacheDurationMs) {
+            return;
+        }
         try {
             const token = await this.authProvider.getToken();
             if (!token) {
@@ -7171,6 +7870,14 @@ class TokenRefreshManager {
                 if (!refreshSuccess) {
                     await this.authService.handleAuthFailure();
                 }
+                else {
+                    // Update validation time on successful refresh
+                    this.lastValidationTime = now;
+                }
+            }
+            else {
+                // Token is valid, update validation time
+                this.lastValidationTime = now;
             }
         }
         catch (error) {
@@ -7254,42 +7961,77 @@ class MemoryTokenStorage {
     }
 }
 /**
- * Token manager for authentication tokens
+ * Token manager for authentication tokens with memory caching
  */
 class AuthTokenManager {
     constructor(storage = new LocalStorageTokenStorage()) {
         this.storage = storage;
+        this.cache = {};
     }
     async getAccessToken() {
+        // Return cached value if available
+        if (this.cache.accessToken !== undefined) {
+            return this.cache.accessToken;
+        }
         const val = await this.storage.get(AUTH_STORAGE_KEYS.ACCESS_TOKEN);
         // Ensure we return string for tokens
-        return typeof val === 'string' ? val : null;
+        const token = typeof val === 'string' ? val : null;
+        this.cache.accessToken = token;
+        return token;
     }
     async setAccessToken(token) {
+        this.cache.accessToken = token;
         await this.storage.set(AUTH_STORAGE_KEYS.ACCESS_TOKEN, token);
     }
     async getRefreshToken() {
+        // Return cached value if available
+        if (this.cache.refreshToken !== undefined) {
+            return this.cache.refreshToken;
+        }
         const val = await this.storage.get(AUTH_STORAGE_KEYS.REFRESH_TOKEN);
-        return typeof val === 'string' ? val : null;
+        const token = typeof val === 'string' ? val : null;
+        this.cache.refreshToken = token;
+        return token;
     }
     async setRefreshToken(token) {
+        this.cache.refreshToken = token;
         await this.storage.set(AUTH_STORAGE_KEYS.REFRESH_TOKEN, token);
     }
     async getProviderToken() {
+        // Return cached value if available
+        if (this.cache.providerToken !== undefined) {
+            return this.cache.providerToken;
+        }
         const val = await this.storage.get(AUTH_STORAGE_KEYS.PROVIDER_TOKEN);
-        return typeof val === 'string' ? val : null;
+        const token = typeof val === 'string' ? val : null;
+        this.cache.providerToken = token;
+        return token;
     }
     async setProviderToken(token) {
+        this.cache.providerToken = token;
         await this.storage.set(AUTH_STORAGE_KEYS.PROVIDER_TOKEN, token);
     }
     async getAuthType() {
+        // Return cached value if available
+        if (this.cache.authType !== undefined) {
+            return this.cache.authType;
+        }
         const authType = await this.storage.get(AUTH_STORAGE_KEYS.AUTH_TYPE);
-        return typeof authType === 'string' ? authType : null;
+        const type = typeof authType === 'string' ? authType : null;
+        this.cache.authType = type;
+        return type;
     }
     async setAuthType(authType) {
+        this.cache.authType = authType;
         await this.storage.set(AUTH_STORAGE_KEYS.AUTH_TYPE, authType);
     }
     async setTokens(accessToken, refreshToken, providerToken) {
+        // Update cache for all tokens
+        this.cache.accessToken = accessToken;
+        if (refreshToken)
+            this.cache.refreshToken = refreshToken;
+        if (providerToken)
+            this.cache.providerToken = providerToken;
         await this.setAccessToken(accessToken);
         if (refreshToken)
             await this.setRefreshToken(refreshToken);
@@ -7297,13 +8039,23 @@ class AuthTokenManager {
             await this.setProviderToken(providerToken);
     }
     async clearAllTokens() {
+        // Clear cache
+        this.cache = {};
         await this.storage.clear();
     }
     async hasAccessToken() {
+        // Use cached value if available to avoid storage read
+        if (this.cache.accessToken !== undefined) {
+            return !!this.cache.accessToken;
+        }
         const token = await this.getAccessToken();
         return !!token;
     }
     async hasRefreshToken() {
+        // Use cached value if available to avoid storage read
+        if (this.cache.refreshToken !== undefined) {
+            return !!this.cache.refreshToken;
+        }
         const token = await this.getRefreshToken();
         return !!token;
     }
@@ -7531,6 +8283,7 @@ class DPoPManager {
 class DefaultAuthProvider {
     constructor(config = {}) {
         this.config = config;
+        this.authTypeCache = null;
         this.authType = config.authType || exports.AccountOwnerType.USER;
         const storage = config.storage || this.createStorage();
         this.tokenManager = new AuthTokenManager(storage);
@@ -7591,6 +8344,15 @@ class DefaultAuthProvider {
     }
     async setAccessToken(token) {
         await this.tokenManager.setAccessToken(token);
+        // Invalidate cache when token changes
+        this.authTypeCache = null;
+        // Eager DPoP key generation after login
+        if (this.dpopManager) {
+            // Fire and forget - generate keys in background
+            this.dpopManager.ensureKeyPair().catch(err => {
+                console.warn('[DefaultAuthProvider] DPoP key generation failed:', err);
+            });
+        }
     }
     async setRefreshToken(token) {
         await this.tokenManager.setRefreshToken(token);
@@ -7600,16 +8362,51 @@ class DefaultAuthProvider {
     }
     async clearTokens() {
         await this.tokenManager.clearAllTokens();
+        // Invalidate cache on clear
+        this.authTypeCache = null;
         if (this.dpopManager) {
             await this.dpopManager.clearKeys();
         }
     }
     async setTokens(accessToken, refreshToken, providerToken) {
         await this.tokenManager.setTokens(accessToken, refreshToken, providerToken);
+        // Invalidate cache when tokens change
+        this.authTypeCache = null;
     }
     async hasValidToken() {
         return this.tokenManager.hasAccessToken();
     }
+    async getAuthType() {
+        // Read from JWT instead of separate storage for single source of truth
+        const token = await this.tokenManager.getAccessToken();
+        if (!token) {
+            this.authTypeCache = null;
+            return null;
+        }
+        // Return cached result if token hasn't changed
+        if (this.authTypeCache && this.authTypeCache.token === token) {
+            return this.authTypeCache.type;
+        }
+        try {
+            // Decode JWT payload (without verification - we just need to read the claim)
+            const parts = token.split('.');
+            if (parts.length !== 3) {
+                console.warn('[DefaultAuthProvider] Invalid JWT format');
+                return null;
+            }
+            const payloadJson = atob(parts[1]);
+            const payload = JSON.parse(payloadJson);
+            // Use accountOwnerType from AuthJWTPayload interface
+            const authType = payload.accountType || null;
+            // Cache result with token signature
+            this.authTypeCache = { token, type: authType };
+            return authType;
+        }
+        catch (error) {
+            console.warn('[DefaultAuthProvider] Failed to parse auth type from JWT:', error);
+            return null;
+        }
+    }
 }
 
 /**
@@ -7804,13 +8601,15 @@ class PersApiClient {
      * @internal
      */
     emitErrorEvent(errorDetails, errorMessage, endpoint, method, status, error) {
-        console.log('[PersApiClient] emitErrorEvent called', {
-            hasEvents: !!this._events,
-            instanceId: this._events?.instanceId ?? 'none',
-            subscriberCount: this._events?.subscriberCount ?? 0,
-            domain: errorDetails.domain,
-            message: errorDetails.message || errorMessage
-        });
+        /* console.log('[PersApiClient] emitErrorEvent called', {
+          hasEvents: !!this._events,
+          instanceId: this._events?.instanceId ?? 'none',
+          subscriberCount: this._events?.subscriberCount ?? 0,
+          domain: errorDetails.domain,
+          code: errorDetails.code,
+          status: status,
+          message: errorDetails.message || errorMessage
+        }); */
         this._events?.emitError({
             domain: errorDetails.domain || 'external',
             type: errorDetails.code || 'API_ERROR',
@@ -8243,8 +9042,7 @@ class AuthManager {
      *   throws `MULTIPLE_CONTEXT_SELECTION_REQUIRED` error with available options
      *
      * @param jwtToken - JWT token from auth provider (passkey, Firebase, etc.)
-     * @param options - Business authentication options
-     * @param options.businessId - The business ID to authenticate as (required for multi-business users)
+     * @param options - Business authentication options (businessId for multi-business users)
      * @returns Promise resolving to authentication response with business context and role in JWT
      * @throws Error with code `MULTIPLE_CONTEXT_SELECTION_REQUIRED` when businessId is needed
      *
@@ -8671,26 +9469,49 @@ class UserManager {
      * requires administrator privileges and returns full user profiles including
      * private information.
      *
-     * @returns Promise resolving to array of all users with complete data
+     * @param options - Pagination options (page, limit, sortBy, sortOrder)
+     * @param search - Optional search query to filter users
+     * @returns Promise resolving to paginated users with complete data
      * @throws {PersApiError} When not authenticated as admin
      *
-     * @example
+     * @example Basic Usage
      * ```typescript
      * // Admin operation - requires admin authentication
      * try {
-     *   const allUsers = await sdk.users.getAllUsers();
-     *   console.log(`Total users: ${allUsers.length}`);
+     *   const result = await sdk.users.getAllUsers();
+     *   console.log(`Total users: ${result.pagination.total}`);
      *
-     *   allUsers.forEach(user => {
-     *     console.log(`${user.name} - ${user.email} - Active: ${user.isActive}`);
+     *   result.data.forEach(user => {
+     *     console.log(`${user.firstName} - ${user.email} - Active: ${user.isActive}`);
      *   });
      * } catch (error) {
      *   console.log('Admin access required');
      * }
      * ```
+     *
+     * @example With Sorting
+     * ```typescript
+     * import { SortOrder } from '@explorins/pers-sdk';
+     *
+     * // Get users sorted by email ascending
+     * const result = await sdk.users.getAllUsers({
+     *   page: 1,
+     *   limit: 20,
+     *   sortBy: 'email',
+     *   sortOrder: SortOrder.ASC
+     * });
+     *
+     * // Get users sorted by creation date (newest first)
+     * const recent = await sdk.users.getAllUsers({
+     *   page: 1,
+     *   limit: 10,
+     *   sortBy: 'createdAt',
+     *   sortOrder: SortOrder.DESC
+     * });
+     * ```
      */
-    async getAllUsers(options) {
-        return this.userService.getAllRemoteUsers(options);
+    async getAllUsers(options, search) {
+        return this.userService.getAllRemoteUsers(options, search);
     }
     /**
      * Business/Admin: Create or update a user
@@ -9855,6 +10676,7 @@ class CampaignManager {
      * business partnerships, eligibility criteria, and claiming requirements.
      *
      * @param campaignId - Unique campaign identifier
+     * @param include - Relations to include: 'triggerSources', 'businesses'
      * @returns Promise resolving to campaign data with complete details
      * @throws {PersApiError} When campaign with specified ID is not found
      *
@@ -9883,9 +10705,17 @@ class CampaignManager {
      *   console.log('Campaign not found:', error.message);
      * }
      * ```
+     *
+     * @example With Include Relations
+     * ```typescript
+     * // Get campaign with trigger sources and businesses included
+     * const campaign = await sdk.campaigns.getCampaignById('campaign-123', ['triggerSources', 'businesses']);
+     * console.log('Trigger sources:', campaign.included?.triggerSources);
+     * console.log('Businesses:', campaign.included?.businesses);
+     * ```
      */
-    async getCampaignById(campaignId) {
-        return this.campaignService.getCampaignById(campaignId);
+    async getCampaignById(campaignId, include) {
+        return this.campaignService.getCampaignById(campaignId, include);
     }
     /**
      * Claim a campaign reward
@@ -9991,7 +10821,8 @@ class CampaignManager {
      * ```
      */
     async getUserClaims(options) {
-        return this.campaignService.getClaimsForLoggedUser(options);
+        const { include, ...paginationOptions } = options || {};
+        return this.campaignService.getClaimsForLoggedUser(paginationOptions, include);
     }
     /**
      * Get campaigns with pagination support
@@ -9999,13 +10830,7 @@ class CampaignManager {
      * Returns campaigns with pagination metadata for efficient data loading.
      * Intelligent access: Public gets active only, Business gets own campaigns, Admin gets all.
      *
-     * @param options - Pagination and filter options
-     * @param options.active - Filter by active status (true/false/undefined for all)
-     * @param options.businessId - Filter by business engagement
-     * @param options.page - Page number (1-based, default: 1)
-     * @param options.limit - Items per page (default: 50)
-     * @param options.sortBy - Sort field ('name', 'createdAt', 'startDate')
-     * @param options.sortOrder - Sort direction ('ASC' or 'DESC')
+     * @param options - Pagination and filter options (page, limit, sortBy, sortOrder, active, businessId, include)
      * @returns Promise resolving to paginated campaigns with metadata
      *
      * @example
@@ -10030,6 +10855,11 @@ class CampaignManager {
      *   page: 1,
      *   limit: 25
      * });
+     *
+     * // Include related data (trigger sources and businesses)
+     * const campaignsWithRelations = await sdk.campaigns.getCampaigns({
+     *   include: ['triggerSources', 'businesses']
+     * });
      * ```
      */
     async getCampaigns(options) {
@@ -10147,57 +10977,188 @@ class CampaignManager {
     async toggleCampaignTestnet(campaignId) {
         return this.campaignService.toggleCampaignTestnet(campaignId);
     }
+    // ==========================================
+    // CAMPAIGN TRIGGER OPERATIONS
+    // Rules & limits for campaign activation
+    // ==========================================
     /**
-     * Admin: Get campaign triggers
+     * Admin: Get all campaign triggers (paginated)
      *
-     * Retrieves all available campaign trigger mechanisms that can be used to
-     * automatically activate campaigns based on user actions or system events.
-     * Requires administrator privileges.
+     * Retrieves all campaign trigger rules that define rate limits, geo-validation,
+     * conditions, and trigger types for campaign activation.
      *
-     * @returns Promise resolving to array of campaign trigger definitions
+     * @param options - Pagination options
+     * @returns Promise resolving to paginated list of campaign triggers
      *
      * @example
      * ```typescript
-     * // Admin operation - view available triggers
-     * const triggers = await sdk.campaigns.getCampaignTriggers();
-     *
-     * console.log('Available Campaign Triggers:');
-     * triggers.forEach(trigger => {
-     *   console.log(`- ${trigger.name}: ${trigger.description}`);
-     *   console.log(`  Type: ${trigger.type}`);
-     *   console.log(`  Parameters: ${JSON.stringify(trigger.parameters)}`);
+     * const triggers = await sdk.campaigns.getCampaignTriggers({ page: 1, limit: 20 });
+     * console.log(`Found ${triggers.total} triggers`);
+     * triggers.data.forEach(trigger => {
+     *   console.log(`- ${trigger.name}: max ${trigger.maxPerDayPerUser}/day`);
      * });
      * ```
      */
     async getCampaignTriggers(options) {
-        return this.campaignService.getCampaignTriggers();
+        return this.campaignService.getCampaignTriggers(options);
+    }
+    /**
+     * Admin: Get campaign trigger by ID
+     *
+     * @param triggerId - The campaign trigger ID
+     * @returns Promise resolving to the campaign trigger
+     *
+     * @example
+     * ```typescript
+     * const trigger = await sdk.campaigns.getCampaignTriggerById('trigger-123');
+     * console.log('Max per day:', trigger.maxPerDayPerUser);
+     * ```
+     */
+    async getCampaignTriggerById(triggerId) {
+        return this.campaignService.getCampaignTriggerById(triggerId);
     }
     /**
-     * Admin: Set campaign trigger
+     * Admin: Create a new campaign trigger
+     *
+     * Creates a trigger rule that defines rate limits, geo-validation, and conditions
+     * for campaign activation. Triggers are created independently and then assigned
+     * to campaigns via `setCampaignTrigger()`.
      *
-     * Associates a specific trigger mechanism with a campaign, enabling automatic
-     * campaign activation based on defined conditions. Requires administrator privileges.
+     * @param data - Trigger configuration
+     * @returns Promise resolving to created trigger
+     *
+     * @example
+     * ```typescript
+     * const trigger = await sdk.campaigns.createCampaignTrigger({
+     *   name: 'Daily Check-in',
+     *   maxPerDayPerUser: 1,
+     *   maxPerUser: 100,
+     *   minCooldownSeconds: 3600,
+     *   maxGeoDistanceInMeters: 50,
+     *   triggerType: 'CLAIM_BY_USER'
+     * });
+     *
+     * // Then assign to campaign
+     * await sdk.campaigns.setCampaignTrigger(campaignId, trigger.id);
+     * ```
+     */
+    async createCampaignTrigger(data) {
+        const result = await this.campaignService.createCampaignTrigger(data);
+        this.events?.emitSuccess({
+            domain: 'campaign',
+            type: 'CAMPAIGN_TRIGGER_CREATED',
+            userMessage: `Trigger "${data.name}" created successfully`,
+            details: { triggerId: result.id, name: data.name }
+        });
+        return result;
+    }
+    /**
+     * Admin: Update an existing campaign trigger
+     *
+     * @param triggerId - The campaign trigger ID
+     * @param data - Updated trigger configuration (partial)
+     * @returns Promise resolving to updated trigger
+     *
+     * @example
+     * ```typescript
+     * const updated = await sdk.campaigns.updateCampaignTrigger('trigger-123', {
+     *   maxPerDayPerUser: 5,
+     *   minCooldownSeconds: 1800
+     * });
+     * ```
+     */
+    async updateCampaignTrigger(triggerId, data) {
+        const result = await this.campaignService.updateCampaignTrigger(triggerId, data);
+        this.events?.emitSuccess({
+            domain: 'campaign',
+            type: 'CAMPAIGN_TRIGGER_UPDATED',
+            userMessage: 'Trigger updated successfully',
+            details: { triggerId, updates: Object.keys(data) }
+        });
+        return result;
+    }
+    /**
+     * Admin: Delete a campaign trigger
+     *
+     * @param triggerId - The campaign trigger ID
+     * @returns Promise resolving to success status
+     *
+     * @example
+     * ```typescript
+     * await sdk.campaigns.deleteCampaignTrigger('trigger-123');
+     * ```
+     */
+    async deleteCampaignTrigger(triggerId) {
+        const result = await this.campaignService.deleteCampaignTrigger(triggerId);
+        this.events?.emitSuccess({
+            domain: 'campaign',
+            type: 'CAMPAIGN_TRIGGER_DELETED',
+            userMessage: 'Trigger deleted successfully',
+            details: { triggerId }
+        });
+        return result;
+    }
+    /**
+     * Admin: Assign a trigger to a campaign
+     *
+     * Associates a trigger rule with a campaign. A campaign can have only one trigger
+     * at a time. Assigning a new trigger replaces any existing trigger.
      *
      * @param campaignId - ID of the campaign
      * @param triggerId - ID of the trigger to associate
-     * @returns Promise resolving to updated campaign data
-     * @throws {PersApiError} When not authenticated as admin or entities not found
+     * @returns Promise resolving to updated campaign
      *
      * @example
      * ```typescript
-     * // Admin operation - set up automatic campaign trigger
      * const updated = await sdk.campaigns.setCampaignTrigger(
-     *   'new-user-welcome',
-     *   'user-registration-trigger'
+     *   'campaign-123',
+     *   'trigger-456'
      * );
-     *
-     * console.log('Trigger set for campaign:', updated.title);
-     * console.log('Trigger will activate on user registration');
+     * console.log('Trigger assigned:', updated.trigger?.name);
      * ```
      */
     async setCampaignTrigger(campaignId, triggerId) {
-        return this.campaignService.setCampaignTrigger(campaignId, triggerId);
+        const result = await this.campaignService.setCampaignTrigger(campaignId, triggerId);
+        this.events?.emitSuccess({
+            domain: 'campaign',
+            type: 'CAMPAIGN_TRIGGER_ASSIGNED',
+            userMessage: 'Trigger assigned to campaign',
+            details: { campaignId, triggerId }
+        });
+        return result;
+    }
+    /**
+     * Admin: Remove a trigger from a campaign
+     *
+     * Removes the trigger rule from a campaign. The trigger itself is not deleted
+     * and can be reassigned to other campaigns.
+     *
+     * @param campaignId - ID of the campaign
+     * @param triggerId - ID of the trigger to remove
+     * @returns Promise resolving to updated campaign
+     *
+     * @example
+     * ```typescript
+     * const updated = await sdk.campaigns.removeCampaignTrigger(
+     *   'campaign-123',
+     *   'trigger-456'
+     * );
+     * console.log('Trigger removed:', updated.trigger === null);
+     * ```
+     */
+    async removeCampaignTrigger(campaignId, triggerId) {
+        const result = await this.campaignService.removeCampaignTrigger(campaignId, triggerId);
+        this.events?.emitSuccess({
+            domain: 'campaign',
+            type: 'CAMPAIGN_TRIGGER_REMOVED',
+            userMessage: 'Trigger removed from campaign',
+            details: { campaignId, triggerId }
+        });
+        return result;
     }
+    // ==========================================
+    // TOKEN UNIT OPERATIONS
+    // ==========================================
     /**
      * Admin: Create campaign token unit
      *
@@ -10406,8 +11367,8 @@ class CampaignManager {
      * });
      * ```
      */
-    async getCampaignClaims(filters) {
-        return this.campaignService.getCampaignClaims(filters);
+    async getCampaignClaims(filters, include) {
+        return this.campaignService.getCampaignClaims(filters, include);
     }
     /**
      * Admin: Get campaign claims by user ID
@@ -10442,8 +11403,8 @@ class CampaignManager {
      * console.log(`\nTotal rewards earned: ${totalRewards}`);
      * ```
      */
-    async getCampaignClaimsByUserId(userId, options) {
-        return this.campaignService.getCampaignClaimsByUserId(userId);
+    async getCampaignClaimsByUserId(userId, options, include) {
+        return this.campaignService.getCampaignClaimsByUserId(userId, options, include);
     }
     /**
      * Admin: Get campaign claims by business ID
@@ -10483,8 +11444,79 @@ class CampaignManager {
      * console.log(`\nTotal rewards distributed: ${totalRewardsDistributed}`);
      * ```
      */
-    async getCampaignClaimsByBusinessId(businessId, options) {
-        return this.campaignService.getCampaignClaimsByBusinessId(businessId);
+    async getCampaignClaimsByBusinessId(businessId, options, include) {
+        return this.campaignService.getCampaignClaimsByBusinessId(businessId, options, include);
+    }
+    // ==========================================
+    // TRIGGER SOURCE ASSIGNMENT
+    // Note: TriggerSource CRUD is in TriggerSourceManager (sdk.triggerSources)
+    // ==========================================
+    /**
+     * Admin: Assign a trigger source to a campaign
+     *
+     * Associates a trigger source with a campaign, enabling the trigger source
+     * to activate campaign rewards when triggered. A campaign can have multiple
+     * trigger sources. Requires administrator privileges.
+     *
+     * Note: To create/update/delete trigger sources, use `sdk.triggerSources`.
+     *
+     * @param campaignId - Campaign UUID
+     * @param triggerSourceId - Trigger source UUID
+     * @returns Promise resolving to updated campaign with trigger source assigned
+     * @throws {PersApiError} When not authenticated as admin or entities not found
+     *
+     * @example
+     * ```typescript
+     * // Create trigger source first
+     * const source = await sdk.triggerSources.create({
+     *   type: 'QR_CODE',
+     *   name: 'Store Entrance QR'
+     * });
+     *
+     * // Then assign to campaign
+     * const updated = await sdk.campaigns.assignTriggerSource(
+     *   'campaign-123',
+     *   source.id
+     * );
+     *
+     * console.log('Trigger source assigned:', updated.triggerSourceIds.length);
+     * ```
+     */
+    async assignTriggerSource(campaignId, triggerSourceId) {
+        const result = await this.campaignService.assignTriggerSourceToCampaign(campaignId, triggerSourceId);
+        this.events?.emitSuccess({
+            domain: 'campaign',
+            type: 'TRIGGER_SOURCE_ASSIGNED',
+            userMessage: 'Trigger source assigned to campaign',
+            details: { campaignId, triggerSourceId }
+        });
+        return result;
+    }
+    /**
+     * Admin: Remove a trigger source from a campaign
+     *
+     * Removes the association between a trigger source and a campaign. The trigger
+     * source itself is not deleted and can be reassigned to other campaigns.
+     * Requires administrator privileges.
+     *
+     * @param campaignId - Campaign UUID
+     * @param triggerSourceId - Trigger source UUID
+     * @returns Promise resolving to updated campaign with trigger source removed
+     * @throws {PersApiError} When not authenticated as admin or entities not found
+     *
+     * @example
+     * ```typescript
+     * // Remove a trigger source from a campaign
+     * const updated = await sdk.campaigns.removeTriggerSource(
+     *   'campaign-123',
+     *   'source-456'
+     * );
+     *
+     * console.log('Remaining trigger source IDs:', updated.triggerSourceIds.length);
+     * ```
+     */
+    async removeTriggerSource(campaignId, triggerSourceId) {
+        return this.campaignService.removeTriggerSourceFromCampaign(campaignId, triggerSourceId);
     }
     /**
      * Get the full campaign service for advanced operations
@@ -10868,8 +11900,57 @@ class RedemptionManager {
      * });
      * ```
      */
-    async getUserRedemptions(options) {
-        return this.redemptionService.getUserRedeems(options);
+    async getUserRedemptions(options, include) {
+        return this.redemptionService.getUserRedeems(options, include);
+    }
+    /**
+     * Admin: Get all redemption redeems with filtering and enriched data
+     *
+     * Retrieves all redemption redeems across the platform with filtering capabilities.
+     * This is an admin-level operation that allows monitoring and analytics of redemption
+     * activity. Supports filtering by user, redemption offer, and enrichment of related entities.
+     *
+     * @param filters - Filter options (userId, redemptionId, pagination)
+     * @param include - Optional relations to include for enrichment
+     * @returns Promise resolving to paginated list of redemption redeems
+     * @throws {PersApiError} When not authenticated as admin
+     *
+     * @example Get All Redeems
+     * ```typescript
+     * // Admin operation - get all redemption redeems
+     * const { data: allRedeems, pagination } = await sdk.redemptions.getRedemptionRedeems();
+     *
+     * console.log(`Total redeems: ${pagination.total}`);
+     * console.log(`Page ${pagination.page} of ${pagination.pages}`);
+     * ```
+     *
+     * @example Filter by User
+     * ```typescript
+     * // Get redeems for specific user
+     * const { data: userRedeems } = await sdk.redemptions.getRedemptionRedeems({
+     *   userId: 'user-123',
+     *   limit: 50
+     * });
+     *
+     * console.log(`User has ${userRedeems.length} redemptions`);
+     * ```
+     *
+     * @example With Enriched Data
+     * ```typescript
+     * const { data: redeems } = await sdk.redemptions.getRedemptionRedeems(
+     *   { page: 1, limit: 20 },
+     *   ['redemption', 'user', 'business']
+     * );
+     *
+     * redeems.forEach(redeem => {
+     *   const redemptionName = redeem.included?.redemption?.name || 'Unknown';
+     *   const userEmail = redeem.included?.user?.email || redeem.userId;
+     *   console.log(`${redemptionName} - ${userEmail}`);
+     * });
+     * ```
+     */
+    async getRedemptionRedeems(filters, include) {
+        return this.redemptionService.getRedemptionRedeems(filters, include);
     }
     /**
      * Admin: Create new redemption offer
@@ -11112,8 +12193,8 @@ class RedemptionManager {
  *
  * @example Administrative Reporting
  * ```typescript
- * // Admin: Get all tenant transactions for analysis
- * const allTransactions = await sdk.transactions.getTenantTransactions();
+ * // Admin: Get paginated transactions for analysis
+ * const allTransactions = await sdk.transactions.getPaginatedTransactions({ page: 1, limit: 100 });
  *
  * // Export transaction data
  * const csvBlob = await sdk.transactions.exportTransactionsCSV();
@@ -11136,13 +12217,18 @@ class TransactionManager {
      * Provides complete transaction audit trail and verification data.
      *
      * @param transactionId - Unique transaction identifier
+     * @param include - Optional relations to include (sender, recipient, business) for enriched entity data
      * @returns Promise resolving to complete transaction data
      * @throws {PersApiError} When transaction with specified ID is not found or access denied
      *
      * @example
      * ```typescript
      * try {
-     *   const transaction = await sdk.transactions.getTransactionById('txn-abc123');
+     *   // Get transaction with enriched sender/recipient data
+     *   const transaction = await sdk.transactions.getTransactionById(
+     *     'txn-abc123',
+     *     ['sender', 'recipient', 'business']
+     *   );
      *
      *   console.log('Transaction Details:');
      *   console.log('ID:', transaction.id);
@@ -11155,16 +12241,19 @@ class TransactionManager {
      *     console.log('Description:', transaction.description);
      *   }
      *
-     *   if (transaction.business) {
-     *     console.log('Business:', transaction.business.displayName);
+     *   // Access enriched sender data
+     *   if (transaction.included?.sender) {
+     *     console.log('Sender:', transaction.included.sender);
      *   }
      *
-     *   // Show token movements
-     *   if (transaction.tokenTransfers?.length) {
-     *     console.log('\nToken Transfers:');
-     *     transaction.tokenTransfers.forEach(transfer => {
-     *       console.log(`${transfer.amount} ${transfer.token.symbol} ${transfer.direction}`);
-     *     });
+     *   // Access enriched recipient data
+     *   if (transaction.included?.recipient) {
+     *     console.log('Recipient:', transaction.included.recipient);
+     *   }
+     *
+     *   // Access enriched business data
+     *   if (transaction.included?.engagedBusiness) {
+     *     console.log('Business:', transaction.included.engagedBusiness.displayName);
      *   }
      *
      *   // Show blockchain confirmation
@@ -11177,8 +12266,8 @@ class TransactionManager {
      * }
      * ```
      */
-    async getTransactionById(transactionId) {
-        return this.transactionService.getTransactionById(transactionId);
+    async getTransactionById(transactionId, include) {
+        return this.transactionService.getTransactionById(transactionId, include);
     }
     /**
      * Create a new transaction
@@ -11272,150 +12361,62 @@ class TransactionManager {
     /**
      * Get user's transaction history
      *
-     * Retrieves transaction history for the authenticated user, filtered by
-     * transaction role. Provides chronological view of all user's loyalty
+     * Retrieves transaction history for the authenticated user with comprehensive
+     * filtering options. Provides chronological view of all user's loyalty
      * activities including purchases, rewards, redemptions, and transfers.
+     * Optionally enrich with related entities (sender, recipient, business).
      *
-     * @param role - Optional role filter (TransactionRole.SENDER, TransactionRole.RECIPIENT). If undefined, returns all user transactions
-     * @param limit - Maximum number of transactions to return (default: 1000)
-     * @returns Promise resolving to array of user's transactions
+     * @param options - Query options including filters, pagination, and include relations
+     * @returns Promise resolving to paginated transaction data with optional included entities
      *
      * @example All Transactions
      * ```typescript
-     * const allTransactions = await sdk.transactions.getUserTransactionHistory('ALL');
+     * const result = await sdk.transactions.getUserTransactionHistory();
      *
-     * console.log(` Transaction History (${allTransactions.length} transactions):`);
+     * console.log(`Transaction History (${result.data.length} of ${result.pagination.total} transactions)`);
      *
-     * allTransactions.forEach((transaction, index) => {
+     * result.data.forEach((transaction, index) => {
      *   const date = new Date(transaction.createdAt).toLocaleDateString();
      *   console.log(`\n${index + 1}. ${transaction.type} - ${date}`);
      *   console.log(`   ${transaction.description || 'No description'}`);
      *   console.log(`   Status: ${transaction.status}`);
-     *
-     *   if (transaction.amount && transaction.currency) {
-     *     console.log(`   Amount: ${transaction.amount} ${transaction.currency}`);
-     *   }
-     *
-     *   if (transaction.business) {
-     *     console.log(`   Business: ${transaction.business.displayName}`);
-     *   }
      * });
      * ```
      *
-     * @example Filtered by Type
+     * @example Filter by Role and Status
      * ```typescript
-     * // Get only purchase transactions
-     * const purchases = await sdk.transactions.getUserTransactionHistory('PURCHASE');
-     *
-     * let totalSpent = 0;
-     * let totalRewards = 0;
-     *
-     * purchases.forEach(purchase => {
-     *   if (purchase.amount) {
-     *     totalSpent += purchase.amount;
-     *   }
-     *
-     *   if (purchase.tokensEarned?.length) {
-     *     purchase.tokensEarned.forEach(reward => {
-     *       totalRewards += reward.amount;
-     *     });
-     *   }
+     * // Get only completed sent transactions
+     * const sent = await sdk.transactions.getUserTransactionHistory({
+     *   role: TransactionRole.SENDER,
+     *   status: TransactionStatus.COMPLETED,
+     *   include: ['recipient', 'business'],
+     *   page: 1,
+     *   limit: 50
      * });
      *
-     * console.log('Purchase Summary:');
-     * console.log(`Total purchases: ${purchases.length}`);
-     * console.log(`Total spent: $${totalSpent.toFixed(2)}`);
-     * console.log(`Total rewards earned: ${totalRewards} points`);
-     * ```
-     *
-     * @example Recent Activity
-     * ```typescript
-     * const recentTransactions = await sdk.transactions.getUserTransactionHistory('ALL');
-     *
-     * // Filter to last 30 days
-     * const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
-     * const recentActivity = recentTransactions.filter(t =>
-     *   new Date(t.createdAt) > thirtyDaysAgo
-     * );
-     *
-     * console.log(`Recent Activity (${recentActivity.length} transactions in last 30 days):`);
-     *
-     * // Group by type
-     * const activityByType = recentActivity.reduce((acc, t) => {
-     *   acc[t.type] = (acc[t.type] || 0) + 1;
-     *   return acc;
-     * }, {});
-     *
-     * Object.entries(activityByType).forEach(([type, count]) => {
-     *   console.log(`${type}: ${count} transactions`);
+     * sent.data.forEach(tx => {
+     *   console.log(`Sent to: ${tx.included?.recipient?.displayName || tx.recipientAddress}`);
      * });
      * ```
-     */
-    async getUserTransactionHistory(role, options) {
-        return this.transactionService.getUserTransactionHistory(role, options);
-    }
-    /**
-     * Admin: Get all tenant transactions
-     *
-     * Retrieves all transactions across the entire tenant/organization for
-     * comprehensive reporting and analysis. This operation requires administrator
-     * privileges and provides system-wide transaction visibility.
-     *
-     * @param limit - Maximum number of transactions to return (default: 1000)
-     * @returns Promise resolving to array of all tenant transactions
-     * @throws {PersApiError} When not authenticated as administrator
      *
-     * @example
+     * @example Filter by Trigger Process (Campaign/Redemption)
      * ```typescript
-     * // Admin operation - comprehensive transaction analysis
-     * const allTransactions = await sdk.transactions.getTenantTransactions();
-     *
-     * console.log(`Tenant Transaction Overview:`);
-     * console.log(`Total transactions: ${allTransactions.length}`);
-     *
-     * // Analyze by status
-     * const statusCounts = allTransactions.reduce((acc, t) => {
-     *   acc[t.status] = (acc[t.status] || 0) + 1;
-     *   return acc;
-     * }, {});
-     *
-     * console.log('\nBy status:');
-     * Object.entries(statusCounts).forEach(([status, count]) => {
-     *   console.log(`${status}: ${count} transactions`);
+     * // Get all transactions triggered by a specific campaign claim
+     * const claimTxs = await sdk.transactions.getUserTransactionHistory({
+     *   triggerProcessId: 'claim-abc123',
+     *   include: ['sender', 'recipient', 'business']
      * });
      *
-     * // Analyze by type
-     * const typeCounts = allTransactions.reduce((acc, t) => {
-     *   acc[t.type] = (acc[t.type] || 0) + 1;
-     *   return acc;
-     * }, {});
-     *
-     * console.log('\nBy type:');
-     * Object.entries(typeCounts).forEach(([type, count]) => {
-     *   console.log(`${type}: ${count} transactions`);
+     * claimTxs.data.forEach(tx => {
+     *   console.log('Transaction from claim:', tx.id);
+     *   if (tx.included?.engagedBusiness) {
+     *     console.log('Business:', tx.included.engagedBusiness.displayName);
+     *   }
      * });
-     *
-     * // Calculate volume metrics
-     * const totalVolume = allTransactions.reduce((sum, t) =>
-     *   sum + (t.amount || 0), 0
-     * );
-     *
-     * const avgTransactionSize = totalVolume / allTransactions.length;
-     *
-     * console.log('\nVolume metrics:');
-     * console.log(`Total volume: $${totalVolume.toFixed(2)}`);
-     * console.log(`Average transaction: $${avgTransactionSize.toFixed(2)}`);
-     *
-     * // Recent activity analysis
-     * const last24Hours = allTransactions.filter(t =>
-     *   new Date(t.createdAt) > new Date(Date.now() - 24 * 60 * 60 * 1000)
-     * );
-     *
-     * console.log(`\n⏰ Last 24 hours: ${last24Hours.length} transactions`);
      * ```
      */
-    async getTenantTransactions(options) {
-        return this.transactionService.getTenantTransactions(options);
+    async getUserTransactionHistory(options) {
+        return this.transactionService.getUserTransactionHistory(options);
     }
     /**
      * Admin: Get paginated transactions
@@ -11424,7 +12425,7 @@ class TransactionManager {
      * handling. This operation requires administrator privileges and is used for
      * detailed transaction analysis and reporting interfaces.
      *
-     * @param params - Pagination and filtering parameters
+     * @param options - Pagination, filtering parameters, and optional include relations
      * @returns Promise resolving to paginated transaction results with metadata
      * @throws {PersApiError} When not authenticated as administrator
      *
@@ -11479,9 +12480,24 @@ class TransactionManager {
      *   console.log(`$${transaction.amount} - ${transaction.business?.displayName}`);
      * });
      * ```
+     *
+     * @example With Included Relations
+     * ```typescript
+     * // Include sender and recipient entities
+     * const result = await sdk.transactions.getPaginatedTransactions({
+     *   page: 1,
+     *   limit: 50,
+     *   include: ['sender', 'recipient', 'business']
+     * });
+     *
+     * result.data.forEach(tx => {
+     *   if (tx.included?.sender) console.log('From:', tx.included.sender);
+     *   if (tx.included?.recipient) console.log('To:', tx.included.recipient);
+     * });
+     * ```
      */
-    async getPaginatedTransactions(params) {
-        return this.transactionService.getPaginatedTransactions(params);
+    async getPaginatedTransactions(options) {
+        return this.transactionService.getPaginatedTransactions(options);
     }
     /**
      * Admin: Export transactions as CSV
@@ -13144,6 +14160,179 @@ class AnalyticsManager {
     async getTransactionAnalytics(request) {
         return this.analyticsService.getTransactionAnalytics(request);
     }
+    /**
+     * Get campaign claim analytics with aggregation
+     *
+     * Retrieves aggregated analytics for campaign claims with flexible grouping,
+     * filtering, and metric selection. Provides insights into campaign performance,
+     * claim patterns, and user engagement across the loyalty ecosystem.
+     *
+     * @param request - Analytics request with filters, groupBy, and metrics
+     * @returns Promise resolving to campaign claim analytics data
+     *
+     * @example Claims per campaign
+     * ```typescript
+     * const analytics = await sdk.analytics.getCampaignClaimAnalytics({
+     *   filters: { status: 'COMPLETED' },
+     *   groupBy: ['campaignId'],
+     *   metrics: ['count'],
+     *   sortBy: 'count',
+     *   sortOrder: 'DESC',
+     *   limit: 10
+     * });
+     *
+     * console.log('Top campaigns:', analytics.results);
+     * ```
+     */
+    async getCampaignClaimAnalytics(request) {
+        return this.analyticsService.getCampaignClaimAnalytics(request);
+    }
+    /**
+     * Get user analytics with engagement metrics
+     *
+     * Retrieves aggregated user statistics including engagement rate, active users,
+     * transaction metrics, and per-active-user averages. Provides comprehensive
+     * insights into user behavior, engagement patterns, and platform adoption metrics.
+     *
+     * NEW: Added per-active-user metrics (averageTransactionsPerActiveUser, etc.) which
+     * show concentrated engagement among active users - more useful than diluted all-user averages.
+     *
+     * Request structure matches TransactionAnalytics and CampaignClaimAnalytics:
+     * - Use filters object for business-specific scoping
+     * - startDate/endDate at root level for date range filtering
+     *
+     * @param request - Analytics request with optional filters and date range
+     * @returns Promise resolving to user analytics data with per-user and per-active-user metrics
+     *
+     * @example Basic user analytics (compare per-user vs per-active-user)
+     * ```typescript
+     * const analytics = await sdk.analytics.getUserAnalytics({});
+     * console.log(`Total users: ${analytics.totalUsers}`);
+     * console.log(`Active users: ${analytics.activeUsers} (${analytics.engagementRate.toFixed(1)}%)`);
+     *
+     * // Per-user averages (includes inactive users - lower numbers)
+     * console.log(`\\nPer-User Averages (all users):`);
+     * console.log(`  Transactions: ${analytics.averageTransactionsPerUser.toFixed(2)}`);
+     * console.log(`  Claims: ${analytics.averageClaimsPerUser.toFixed(2)}`);
+     * console.log(`  Redemptions: ${analytics.averageRedemptionsPerUser.toFixed(2)}`);
+     *
+     * // Per-active-user averages (only engaged users - higher, more meaningful numbers)
+     * console.log(`\\nPer-Active-User Averages (engaged users only):`);
+     * console.log(`  Transactions: ${analytics.averageTransactionsPerActiveUser.toFixed(2)}`);
+     * console.log(`  Claims: ${analytics.averageClaimsPerActiveUser.toFixed(2)}`);
+     * console.log(`  Redemptions: ${analytics.averageRedemptionsPerActiveUser.toFixed(2)}`);
+     * ```
+     *
+     * @example Monthly user analytics with date range
+     * ```typescript
+     * const analytics = await sdk.analytics.getUserAnalytics({
+     *   startDate: new Date('2026-02-01'),
+     *   endDate: new Date('2026-02-28')
+     * });
+     *
+     * console.log('February 2026 User Metrics:');
+     * console.log(`Total users: ${analytics.totalUsers}`);
+     * console.log(`Active users: ${analytics.activeUsers}`);
+     * console.log(`New users: ${analytics.newUsers}`);
+     * console.log(`Engagement rate: ${analytics.engagementRate.toFixed(2)}%`);
+     * console.log(`Total transaction volume: $${analytics.totalTransactionVolume.toLocaleString()}`);
+     * console.log(`Avg transaction amount: $${analytics.averageTransactionAmount.toFixed(2)}`);
+     * console.log(`\\nFilters applied: ${analytics.metadata.dateRange?.startDate} to ${analytics.metadata.dateRange?.endDate}`);
+     * ```
+     *
+     * @example Business-specific user analytics with filters
+     * ```typescript
+     * const analytics = await sdk.analytics.getUserAnalytics({
+     *   filters: { businessId: 'business-123' },
+     *   startDate: new Date('2026-01-01'),
+     *   endDate: new Date('2026-12-31')
+     * });
+     *
+     * console.log(`Business customer metrics for 2026:`);
+     * console.log(`Active customers: ${analytics.activeUsers} / ${analytics.totalUsers}`);
+     * console.log(`Customer engagement: ${analytics.engagementRate.toFixed(1)}%`);
+     * console.log(`Avg spend per customer: $${analytics.averageTransactionAmount.toFixed(2)}`);
+     * console.log(`Avg spend per active customer: $${(analytics.totalTransactionVolume / analytics.activeUsers).toFixed(2)}`);
+     * console.log(`Avg claims per active customer: ${analytics.averageClaimsPerActiveUser.toFixed(2)}`);
+     * ```
+     */
+    async getUserAnalytics(request = {}) {
+        return this.analyticsService.getUserAnalytics(request);
+    }
+    /**
+     * Get user transaction ranking with enriched user data
+     *
+     * Retrieves ranked list of users with full user details (email, externalUserId)
+     * and transaction metrics. Data enrichment happens via efficient SQL JOINs + UNION
+     * (handles legacy transactions). Ideal for leaderboards, engagement analysis, and
+     * identifying power users for targeted campaigns.
+     *
+     * Use Cases:
+     * - Admin leaderboards showing top users by activity
+     * - User engagement analysis with full user context
+     * - Identifying power users for campaigns
+     * - Customer segmentation by transaction behavior
+     *
+     * @param request - Ranking request with filters, sorting, and limit
+     * @returns Promise resolving to ranked user list with transaction metrics
+     *
+     * @example Top 50 users by transaction count
+     * ```typescript
+     * const ranking = await sdk.analytics.getUserRanking({
+     *   sortBy: 'totalTransactions',
+     *   sortOrder: 'DESC',
+     *   limit: 50
+     * });
+     *
+     * console.log(`Top ${ranking.totalUsers} users:`);
+     * ranking.results.forEach((user, index) => {
+     *   console.log(`#${index + 1}: ${user.email || user.externalUserId}`);
+     *   console.log(`  Transactions: ${user.totalTransactions}`);
+     *   console.log(`  Token spent: ${user.tokenSpent}`);
+     * });
+     * ```
+     *
+     * @example Top users by STAMP spending
+     * ```typescript
+     * const ranking = await sdk.analytics.getUserRanking({
+     *   filters: { tokenType: 'STAMP' },
+     *   sortBy: 'tokenSpent',
+     *   sortOrder: 'DESC',
+     *   limit: 20
+     * });
+     *
+     * console.log('Top 20 STAMP spenders:');
+     * ranking.results.forEach((user, index) => {
+     *   const identifier = user.email || user.externalUserId || user.userId;
+     *   console.log(`${index + 1}. ${identifier} - ${user.tokenSpent} STAMP`);
+     * });
+     * ```
+     */
+    async getUserRanking(request = {}) {
+        return this.analyticsService.getUserRanking(request);
+    }
+    /**
+     * Get business transaction ranking with enriched business data
+     *
+     * Returns ranked list of businesses with full business details and transaction metrics.
+     *
+     * @param request - Ranking request with filters, sorting, and limit
+     * @returns Promise resolving to ranked business list
+     */
+    async getBusinessRanking(request = {}) {
+        return this.analyticsService.getBusinessRanking(request);
+    }
+    /**
+     * Get monthly user retention analytics
+     *
+     * Returns monthly retention data with user metrics and retention rates.
+     *
+     * @param request - Retention request with monthsBack and filters
+     * @returns Promise resolving to monthly retention data
+     */
+    async getRetentionAnalytics(request = {}) {
+        return this.analyticsService.getRetentionAnalytics(request);
+    }
     /**
      * Get the full analytics service for advanced operations
      *
@@ -13238,6 +14427,222 @@ class DonationManager {
     }
 }
 
+/**
+ * TriggerSource Manager - Clean, high-level interface for trigger source operations
+ *
+ * Manages trigger sources which are physical or digital activation points for campaigns:
+ * - QR_CODE: Scannable QR codes
+ * - NFC_TAG: NFC tap points
+ * - GPS_GEOFENCE: Location-based triggers
+ * - API_WEBHOOK: External system integration
+ * - TRANSACTION: Purchase/payment based triggers
+ *
+ * Trigger sources are independent entities that can be created, managed, and then
+ * assigned to campaigns. This separation allows reuse and flexible campaign configuration.
+ *
+ * @group Managers
+ * @category TriggerSource Management
+ *
+ * @example Basic TriggerSource Operations
+ * ```typescript
+ * // Get all QR code trigger sources
+ * const qrSources = await sdk.triggerSources.getAll({ type: 'QR_CODE' });
+ *
+ * // Create a new QR code trigger source
+ * const source = await sdk.triggerSources.create({
+ *   type: 'QR_CODE',
+ *   name: 'Store Entrance QR',
+ *   businessId: 'business-123'
+ * });
+ *
+ * // Assign to campaign (via CampaignManager)
+ * await sdk.campaigns.assignTriggerSource('campaign-456', source.id);
+ * ```
+ */
+class TriggerSourceManager {
+    constructor(apiClient, events) {
+        this.apiClient = apiClient;
+        this.events = events;
+        const triggerSourceApi = new TriggerSourceApi(apiClient);
+        this.triggerSourceService = new TriggerSourceService(triggerSourceApi);
+    }
+    /**
+     * 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 qrSources = await sdk.triggerSources.getAll({ type: 'QR_CODE' });
+     *
+     * // Get trigger sources for a specific business
+     * const businessSources = await sdk.triggerSources.getAll({
+     *   businessId: 'business-123',
+     *   active: true,
+     *   page: 1,
+     *   limit: 20
+     * });
+     *
+     * // Get trigger sources assigned to a campaign
+     * const campaignSources = await sdk.triggerSources.getAll({
+     *   campaignId: 'campaign-456'
+     * });
+     * ```
+     */
+    async getAll(options) {
+        return this.triggerSourceService.getTriggerSources(options);
+    }
+    /**
+     * Get trigger source by ID
+     *
+     * Retrieves detailed information for a specific trigger source including
+     * its type, location, metadata, and usage analytics.
+     *
+     * @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 sdk.triggerSources.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);
+     * }
+     * ```
+     */
+    async getById(triggerSourceId) {
+        return this.triggerSourceService.getTriggerSourceById(triggerSourceId);
+    }
+    /**
+     * 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 sdk.triggerSources.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 sdk.triggerSources.create({
+     *   type: 'NFC_TAG',
+     *   name: 'Product Display NFC',
+     *   metadata: { productId: 'SKU-12345' }
+     * });
+     *
+     * // Create a GPS geofence trigger source
+     * const geoSource = await sdk.triggerSources.create({
+     *   type: 'GPS_GEOFENCE',
+     *   name: 'Store Area',
+     *   coordsLatitude: 47.6062,
+     *   coordsLongitude: -122.3321,
+     *   metadata: { radiusMeters: 100 }
+     * });
+     * ```
+     */
+    async create(triggerSource) {
+        const result = await this.triggerSourceService.createTriggerSource(triggerSource);
+        this.events?.emitSuccess({
+            domain: 'trigger-source',
+            type: 'TRIGGER_SOURCE_CREATED',
+            userMessage: 'Trigger source created successfully',
+            details: { triggerSourceId: result.id, type: result.type }
+        });
+        return result;
+    }
+    /**
+     * 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 sdk.triggerSources.update('source-123', {
+     *   name: 'Updated Store Entrance QR',
+     *   description: 'New description',
+     *   coordsLatitude: 47.6063,
+     *   coordsLongitude: -122.3322
+     * });
+     * ```
+     */
+    async update(triggerSourceId, triggerSource) {
+        const result = await this.triggerSourceService.updateTriggerSource(triggerSourceId, triggerSource);
+        this.events?.emitSuccess({
+            domain: 'trigger-source',
+            type: 'TRIGGER_SOURCE_UPDATED',
+            userMessage: 'Trigger source updated successfully',
+            details: { triggerSourceId }
+        });
+        return result;
+    }
+    /**
+     * 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 sdk.triggerSources.delete('source-123');
+     * console.log('Trigger source deleted:', success);
+     * ```
+     */
+    async delete(triggerSourceId) {
+        const result = await this.triggerSourceService.deleteTriggerSource(triggerSourceId);
+        this.events?.emitSuccess({
+            domain: 'trigger-source',
+            type: 'TRIGGER_SOURCE_DELETED',
+            userMessage: 'Trigger source deleted successfully',
+            details: { triggerSourceId }
+        });
+        return result;
+    }
+    /**
+     * Get the full trigger source service for advanced operations
+     *
+     * @returns TriggerSourceService instance with full API access
+     */
+    getTriggerSourceService() {
+        return this.triggerSourceService;
+    }
+}
+
 /**
  * @fileoverview PERS SDK - Platform-agnostic TypeScript SDK with High-Level Managers
  *
@@ -13351,78 +14756,71 @@ class PersSDK {
         // Initialize event emitter and wire to API client for error events
         this._events = new PersEventEmitter();
         this.apiClient.setEvents(this._events);
-        // Initialize domain managers (pass events to managers that emit success events)
-        this._auth = new AuthManager(this.apiClient, this._events);
-        this._users = new UserManager(this.apiClient, this._events);
-        this._userStatus = new UserStatusManager(this.apiClient);
-        this._tokens = new TokenManager(this.apiClient);
-        this._businesses = new BusinessManager(this.apiClient, this._events);
-        this._campaigns = new CampaignManager(this.apiClient, this._events);
-        this._redemptions = new RedemptionManager(this.apiClient, this._events);
-        this._transactions = new TransactionManager(this.apiClient, this._events);
-        this._purchases = new PurchaseManager(this.apiClient);
-        this._files = new FileManager(this.apiClient);
-        this._tenants = new TenantManager(this.apiClient);
-        this._apiKeys = new ApiKeyManager(this.apiClient);
-        this._analytics = new AnalyticsManager(this.apiClient);
-        this._donations = new DonationManager(this.apiClient);
-        // Automatically restore session if enabled and tokens exist
-        if (config.autoRestoreSession !== false) {
-            this.restoreSessionIfTokensExist().catch(err => {
-                console.warn('[PersSDK] Failed to restore session on initialization:', err);
-            });
-        }
     }
     /**
-     * Restore user session if valid tokens exist in storage
+     * Restore user session from stored tokens
      *
-     * This method is called automatically during SDK initialization when
-     * `autoRestoreSession` is enabled (default). It checks for stored tokens
-     * and fetches user data to restore the authentication state.
+     * Call this method after SDK initialization to restore the user's session
+     * if valid tokens exist. This is useful for maintaining login state across
+     * app restarts.
+     *
+     * **Important:** Only works for USER and BUSINESS accounts. Admin/tenant
+     * accounts don't support user data fetching, so this will return null for them
+     * (though their tokens remain valid for API calls).
      *
      * Emits auth domain success event when session is restored.
      *
-     * @internal
-     * @returns Promise that resolves when session is restored or determined to be invalid
+     * @returns Promise resolving to User data if session restored, null if no session or admin account
+     * @throws {PersError} If token validation or user fetch fails
+     *
+     * @example
+     * ```typescript
+     * // Call after initial render for better perceived performance
+     * const user = await sdk.restoreSession();
+     * if (user) {
+     *   console.log('Welcome back,', user.name);
+     * }
+     * ```
      */
-    async restoreSessionIfTokensExist() {
-        try {
-            const hasToken = await this._auth.hasValidAuth();
-            if (hasToken) {
-                console.log('[PersSDK] Valid tokens found, restoring session...');
-                try {
-                    // Fetch user data to validate tokens and restore session
-                    const userData = await this._auth.getCurrentUser();
-                    console.log('[PersSDK] Session restored successfully');
-                    // Emit event through proper event emitter
-                    // Send minimal data (just userId) - consumers can fetch full user if needed
-                    this._events.emitSuccess({
-                        type: 'session_restored',
-                        domain: 'authentication',
-                        userMessage: 'Session restored successfully',
-                        details: { userId: userData.id }
-                    });
-                }
-                catch (error) {
-                    // Tokens exist but are invalid (expired, revoked, etc.)
-                    console.warn('[PersSDK] Failed to restore session, tokens may be invalid:', error);
-                    await this._auth.clearAuth();
-                    // Emit restoration failed event
-                    this._events.emitError({
-                        type: 'session_restoration_failed',
-                        domain: 'authentication',
-                        userMessage: 'Session restoration failed',
-                        code: 'SESSION_INVALID',
-                        details: { error }
-                    });
-                }
-            }
-            else {
-                console.log('[PersSDK] No valid tokens found');
+    async restoreSession() {
+        const hasToken = await this.auth.hasValidAuth();
+        if (!hasToken) {
+            return null;
+        }
+        // Check auth type - only restore session for user and business accounts
+        const authProvider = this.apiClient.getConfig().authProvider;
+        if (authProvider?.getAuthType) {
+            const authType = await authProvider.getAuthType();
+            if (authType === exports.AccountOwnerType.TENANT) {
+                // Admin sessions don't support getCurrentUser(), skip restoration
+                // Tokens are valid and will be used for API calls
+                return null;
             }
         }
+        try {
+            // Fetch user data to validate tokens and restore session
+            const userData = await this.auth.getCurrentUser();
+            // Emit event through proper event emitter
+            this._events.emitSuccess({
+                type: 'session_restored',
+                domain: 'authentication',
+                userMessage: 'Session restored successfully',
+                details: { userId: userData.id }
+            });
+            return userData;
+        }
         catch (error) {
-            console.warn('[PersSDK] Error during session restoration:', error);
+            // Tokens exist but are invalid (expired, revoked, etc.)
+            await this.auth.clearAuth();
+            // Emit restoration failed event
+            this._events.emitError({
+                type: 'session_restoration_failed',
+                domain: 'authentication',
+                userMessage: 'Session restoration failed',
+                code: 'SESSION_INVALID',
+                details: { error }
+            });
+            throw error;
         }
     }
     /**
@@ -13511,6 +14909,9 @@ class PersSDK {
      * @see {@link AuthManager} for detailed documentation
      */
     get auth() {
+        if (!this._auth) {
+            this._auth = new AuthManager(this.apiClient, this._events);
+        }
         return this._auth;
     }
     /**
@@ -13524,6 +14925,9 @@ class PersSDK {
      * ```
      */
     get users() {
+        if (!this._users) {
+            this._users = new UserManager(this.apiClient, this._events);
+        }
         return this._users;
     }
     /**
@@ -13537,6 +14941,9 @@ class PersSDK {
      * ```
      */
     get userStatus() {
+        if (!this._userStatus) {
+            this._userStatus = new UserStatusManager(this.apiClient);
+        }
         return this._userStatus;
     }
     /**
@@ -13550,6 +14957,9 @@ class PersSDK {
      * ```
      */
     get tokens() {
+        if (!this._tokens) {
+            this._tokens = new TokenManager(this.apiClient);
+        }
         return this._tokens;
     }
     /**
@@ -13563,6 +14973,9 @@ class PersSDK {
      * ```
      */
     get businesses() {
+        if (!this._businesses) {
+            this._businesses = new BusinessManager(this.apiClient, this._events);
+        }
         return this._businesses;
     }
     /**
@@ -13576,6 +14989,9 @@ class PersSDK {
      * ```
      */
     get campaigns() {
+        if (!this._campaigns) {
+            this._campaigns = new CampaignManager(this.apiClient, this._events);
+        }
         return this._campaigns;
     }
     /**
@@ -13589,6 +15005,9 @@ class PersSDK {
      * ```
      */
     get redemptions() {
+        if (!this._redemptions) {
+            this._redemptions = new RedemptionManager(this.apiClient, this._events);
+        }
         return this._redemptions;
     }
     /**
@@ -13602,6 +15021,9 @@ class PersSDK {
      * ```
      */
     get transactions() {
+        if (!this._transactions) {
+            this._transactions = new TransactionManager(this.apiClient, this._events);
+        }
         return this._transactions;
     }
     /**
@@ -13615,6 +15037,9 @@ class PersSDK {
      * ```
      */
     get purchases() {
+        if (!this._purchases) {
+            this._purchases = new PurchaseManager(this.apiClient);
+        }
         return this._purchases;
     }
     /**
@@ -13628,6 +15053,9 @@ class PersSDK {
      * ```
      */
     get files() {
+        if (!this._files) {
+            this._files = new FileManager(this.apiClient);
+        }
         return this._files;
     }
     /**
@@ -13641,6 +15069,9 @@ class PersSDK {
      * ```
      */
     get tenants() {
+        if (!this._tenants) {
+            this._tenants = new TenantManager(this.apiClient);
+        }
         return this._tenants;
     }
     /**
@@ -13665,6 +15096,9 @@ class PersSDK {
      * ```
      */
     get apiKeys() {
+        if (!this._apiKeys) {
+            this._apiKeys = new ApiKeyManager(this.apiClient);
+        }
         return this._apiKeys;
     }
     /**
@@ -13676,6 +15110,9 @@ class PersSDK {
      * ```
      */
     get analytics() {
+        if (!this._analytics) {
+            this._analytics = new AnalyticsManager(this.apiClient);
+        }
         return this._analytics;
     }
     /**
@@ -13687,8 +15124,45 @@ class PersSDK {
      * ```
      */
     get donations() {
+        if (!this._donations) {
+            this._donations = new DonationManager(this.apiClient);
+        }
         return this._donations;
     }
+    /**
+     * TriggerSource manager - High-level trigger source operations (Admin Only)
+     *
+     * Provides CRUD operations for managing trigger sources (QR codes, NFC tags,
+     * GPS geofences, API webhooks). TriggerSources are standalone entities that
+     * can be assigned to campaigns via the campaigns manager.
+     *
+     * @returns TriggerSourceManager instance
+     *
+     * @example TriggerSource Operations
+     * ```typescript
+     * // Create a QR code trigger source
+     * const qrSource = await sdk.triggerSources.create({
+     *   name: 'Store Entrance QR',
+     *   type: 'QR_CODE',
+     *   description: 'QR code at main entrance'
+     * });
+     *
+     * // Get all trigger sources
+     * const sources = await sdk.triggerSources.getAll();
+     *
+     * // Update trigger source
+     * await sdk.triggerSources.update(sourceId, { name: 'Updated Name' });
+     *
+     * // Assign to campaign (via campaigns manager)
+     * await sdk.campaigns.assignTriggerSource(campaignId, qrSource.id);
+     * ```
+     */
+    get triggerSources() {
+        if (!this._triggerSources) {
+            this._triggerSources = new TriggerSourceManager(this.apiClient, this._events);
+        }
+        return this._triggerSources;
+    }
     /**
      * Gets the API client for direct PERS API requests
      *
@@ -14581,11 +16055,19 @@ const SDKContext = react.createContext(null);
 // Provider component
 const PersSDKProvider = ({ children, config }) => {
     const initializingRef = react.useRef(false);
+    // State refs for stable functions to read current values
+    const sdkRef = react.useRef(null);
+    const isInitializedRef = react.useRef(false);
+    const isAuthenticatedRef = react.useRef(false);
     const [sdk, setSdk] = react.useState(null);
     const [authProvider, setAuthProvider] = react.useState(null);
     const [isInitialized, setIsInitialized] = react.useState(false);
     const [isAuthenticated, setIsAuthenticated] = react.useState(false);
     const [user, setUser] = react.useState(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 = react.useCallback(async (config) => {
         // Prevent multiple initializations
         if (isInitialized || initializingRef.current) {
@@ -14652,18 +16134,40 @@ const PersSDKProvider = ({ children, config }) => {
         }
     }, [config, isInitialized, initialize]);
     const refreshUserData = react.useCallback(async () => {
-        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 = react.useCallback(async () => {
+        // 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
@@ -14676,13 +16180,18 @@ const PersSDKProvider = ({ children, config }) => {
             // 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
             if (event.type === 'session_restoration_failed' || event.code === 'AUTH_FAILED') {
@@ -14720,28 +16229,17 @@ const PersSDKProvider = ({ children, config }) => {
     const contextValue = react.useMemo(() => ({
         // 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,
         // State
         isInitialized,
         isAuthenticated,
         user,
-        // Methods
+        // Methods - expose functions directly, not through refs
         initialize,
         setAuthenticationState,
         refreshUserData,
+        restoreSession,
     }), [
         sdk,
         authProvider,
@@ -14750,7 +16248,8 @@ const PersSDKProvider = ({ children, config }) => {
         user,
         initialize,
         setAuthenticationState,
-        refreshUserData
+        refreshUserData,
+        restoreSession
     ]);
     return (jsxRuntime.jsx(SDKContext.Provider, { value: contextValue, children: children }));
 };
@@ -36091,7 +37590,7 @@ const useWeb3 = () => {
  */
 function useTokenBalances(options) {
     const { accountAddress, availableTokens = [], autoLoad = true, refreshInterval = 0 } = options;
-    const { isAuthenticated } = usePersSDK();
+    const { isAuthenticated, sdk } = usePersSDK();
     const web3 = useWeb3();
     const [tokenBalances, setTokenBalances] = react.useState([]);
     const [isLoading, setIsLoading] = react.useState(false);
@@ -36193,15 +37692,28 @@ function useTokenBalances(options) {
             loadBalances();
         }
     }, [autoLoad, isAvailable, availableTokens.length, loadBalances]);
-    // Optional auto-refresh interval
+    // Event-driven refresh: listen for transaction events instead of polling
     react.useEffect(() => {
-        if (refreshInterval > 0 && isAvailable && availableTokens.length > 0) {
-            const intervalId = setInterval(() => {
+        if (!sdk || refreshInterval <= 0 || !isAvailable)
+            return;
+        // Subscribe to transaction domain events
+        const unsubscribe = sdk.events.subscribe((event) => {
+            if (event.domain === 'transaction' && event.type === 'transaction_completed') {
+                console.log('[useTokenBalances] Transaction completed, refreshing balances...');
                 loadBalances();
-            }, refreshInterval);
-            return () => clearInterval(intervalId);
-        }
-    }, [refreshInterval, isAvailable, availableTokens.length, loadBalances]);
+            }
+        }, { domains: ['transaction'] });
+        // Also set up a fallback polling interval (much longer than before)
+        // This handles cases where events might be missed
+        const fallbackInterval = Math.max(refreshInterval, 60000); // Minimum 1 minute
+        const intervalId = setInterval(() => {
+            loadBalances();
+        }, fallbackInterval);
+        return () => {
+            unsubscribe();
+            clearInterval(intervalId);
+        };
+    }, [sdk, refreshInterval, isAvailable, loadBalances]);
     return {
         tokenBalances,
         isLoading,
@@ -36849,25 +38361,32 @@ 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 = react.useCallback(async (transactionId) => {
+    const getTransactionById = react.useCallback(async (transactionId, include) => {
         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) {
@@ -36876,25 +38395,48 @@ 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 = react.useCallback(async (role) => {
+    const getUserTransactionHistory = react.useCallback(async (options) => {
         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) {
@@ -36902,25 +38444,39 @@ const useTransactions = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
-    const getTenantTransactions = react.useCallback(async () => {
-        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;
-        }
-    }, [sdk, isInitialized]);
-    const getPaginatedTransactions = react.useCallback(async (params) => {
+    /**
+     * 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 = react.useCallback(async (options) => {
         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) {
@@ -36945,7 +38501,6 @@ const useTransactions = () => {
         createTransaction,
         getTransactionById,
         getUserTransactionHistory,
-        getTenantTransactions,
         getPaginatedTransactions,
         exportTransactionsCSV,
         isAvailable: isInitialized && !!sdk?.transactions,
@@ -37178,12 +38733,26 @@ const useCampaigns = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
-    const getCampaignById = react.useCallback(async (campaignId) => {
+    /**
+     * Get campaign by ID with optional include relations
+     *
+     * @param campaignId - The campaign ID
+     * @param include - Relations to include: 'triggerSources', 'businesses'
+     * @returns Promise resolving to campaign data
+     *
+     * @example
+     * ```typescript
+     * // Get campaign with all related data
+     * const campaign = await getCampaignById('campaign-123', ['triggerSources', 'businesses']);
+     * console.log('Trigger sources:', campaign.included?.triggerSources);
+     * ```
+     */
+    const getCampaignById = react.useCallback(async (campaignId, include) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.campaigns.getCampaignById(campaignId);
+            const result = await sdk.campaigns.getCampaignById(campaignId, include);
             return result;
         }
         catch (error) {
@@ -37207,7 +38776,25 @@ const useCampaigns = () => {
             throw error;
         }
     }, [sdk, isInitialized, isAuthenticated]);
-    const getUserClaims = react.useCallback(async () => {
+    /**
+     * Get user's campaign claims with optional pagination and include relations
+     *
+     * @param options - Optional options including pagination and include relations
+     * @returns Promise resolving to paginated campaign claims
+     *
+     * @example
+     * ```typescript
+     * // Get user's claims with campaign details
+     * const { data: claims } = await getUserClaims({ include: ['campaign', 'business'] });
+     * claims.forEach(claim => {
+     *   console.log('Campaign:', claim.included?.campaign?.title);
+     * });
+     *
+     * // With pagination
+     * const { data } = await getUserClaims({ page: 1, limit: 10, include: ['campaign'] });
+     * ```
+     */
+    const getUserClaims = react.useCallback(async (options) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
@@ -37216,7 +38803,7 @@ const useCampaigns = () => {
             return { data: [], pagination: { page: 1, limit: 0, total: 0, pages: 0, hasNext: false, hasPrev: false } };
         }
         try {
-            const result = await sdk.campaigns.getUserClaims();
+            const result = await sdk.campaigns.getUserClaims(options);
             return result;
         }
         catch (error) {
@@ -37251,12 +38838,28 @@ const useCampaigns = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
-    const getCampaignClaims = react.useCallback(async () => {
+    /**
+     * Admin: Get campaign claims with optional filters and include relations
+     *
+     * @param filters - Optional filters for campaign, user, or business
+     * @param include - Relations to include: 'campaign', 'user', 'business'
+     * @returns Promise resolving to paginated campaign claims
+     *
+     * @example
+     * ```typescript
+     * // Get all claims with user details
+     * const { data: claims } = await getCampaignClaims({}, ['user']);
+     *
+     * // Get claims for a specific campaign
+     * const { data } = await getCampaignClaims({ campaignId: 'campaign-123' }, ['user', 'business']);
+     * ```
+     */
+    const getCampaignClaims = react.useCallback(async (filters, include) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.campaigns.getCampaignClaims();
+            const result = await sdk.campaigns.getCampaignClaims(filters, include);
             return result;
         }
         catch (error) {
@@ -37264,12 +38867,19 @@ const useCampaigns = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
-    const getCampaignClaimsByUserId = react.useCallback(async (userId) => {
+    /**
+     * Admin: Get campaign claims by user ID with optional include relations
+     *
+     * @param userId - The user ID
+     * @param include - Relations to include: 'campaign', 'user', 'business'
+     * @returns Promise resolving to paginated campaign claims
+     */
+    const getCampaignClaimsByUserId = react.useCallback(async (userId, include) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.campaigns.getCampaignClaimsByUserId(userId);
+            const result = await sdk.campaigns.getCampaignClaimsByUserId(userId, undefined, include);
             return result;
         }
         catch (error) {
@@ -37277,12 +38887,19 @@ const useCampaigns = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
-    const getCampaignClaimsByBusinessId = react.useCallback(async (businessId) => {
+    /**
+     * Admin: Get campaign claims by business ID with optional include relations
+     *
+     * @param businessId - The business ID
+     * @param include - Relations to include: 'campaign', 'user', 'business'
+     * @returns Promise resolving to paginated campaign claims
+     */
+    const getCampaignClaimsByBusinessId = react.useCallback(async (businessId, include) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.campaigns.getCampaignClaimsByBusinessId(businessId);
+            const result = await sdk.campaigns.getCampaignClaimsByBusinessId(businessId, undefined, include);
             return result;
         }
         catch (error) {
@@ -37290,6 +38907,76 @@ const useCampaigns = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
+    // ==========================================
+    // TRIGGER SOURCE ASSIGNMENT (Admin)
+    // Note: TriggerSource CRUD is in useTriggerSources hook
+    // ==========================================
+    /**
+     * Admin: Assign a trigger source to a campaign
+     *
+     * Associates a trigger source (QR code, NFC tag, etc.) with a campaign.
+     * A campaign can have multiple trigger sources.
+     *
+     * Note: To create/update/delete trigger sources, use `useTriggerSources` hook.
+     *
+     * @param campaignId - Campaign UUID
+     * @param triggerSourceId - Trigger source UUID
+     * @returns Promise resolving to updated campaign
+     *
+     * @example
+     * ```typescript
+     * const { create } = useTriggerSources();
+     * const { assignTriggerSource } = useCampaigns();
+     *
+     * // Create trigger source first
+     * const source = await create({ type: 'QR_CODE', name: 'Store QR' });
+     *
+     * // Then assign to campaign
+     * const updated = await assignTriggerSource('campaign-123', source.id);
+     * ```
+     */
+    const assignTriggerSource = react.useCallback(async (campaignId, triggerSourceId) => {
+        if (!isInitialized || !sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        if (!isAuthenticated) {
+            throw new Error('SDK not authenticated. assignTriggerSource requires admin authentication.');
+        }
+        try {
+            const result = await sdk.campaigns.assignTriggerSource(campaignId, triggerSourceId);
+            return result;
+        }
+        catch (error) {
+            console.error('Failed to assign trigger source:', error);
+            throw error;
+        }
+    }, [sdk, isInitialized, isAuthenticated]);
+    /**
+     * Admin: Remove a trigger source from a campaign
+     *
+     * Removes the association between a trigger source and a campaign.
+     * The trigger source itself is not deleted.
+     *
+     * @param campaignId - Campaign UUID
+     * @param triggerSourceId - Trigger source UUID
+     * @returns Promise resolving to updated campaign
+     */
+    const removeTriggerSource = react.useCallback(async (campaignId, triggerSourceId) => {
+        if (!isInitialized || !sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        if (!isAuthenticated) {
+            throw new Error('SDK not authenticated. removeTriggerSource requires admin authentication.');
+        }
+        try {
+            const result = await sdk.campaigns.removeTriggerSource(campaignId, triggerSourceId);
+            return result;
+        }
+        catch (error) {
+            console.error('Failed to remove trigger source:', error);
+            throw error;
+        }
+    }, [sdk, isInitialized, isAuthenticated]);
     return {
         getActiveCampaigns,
         getCampaignById,
@@ -37300,6 +38987,8 @@ const useCampaigns = () => {
         getCampaignClaims,
         getCampaignClaimsByUserId,
         getCampaignClaimsByBusinessId,
+        assignTriggerSource,
+        removeTriggerSource,
         isAvailable: isInitialized && !!sdk?.campaigns,
     };
 };
@@ -37328,7 +39017,23 @@ const useRedemptions = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
-    const getUserRedemptions = react.useCallback(async () => {
+    /**
+     * 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 = react.useCallback(async (include) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
@@ -37337,7 +39042,7 @@ const useRedemptions = () => {
             return { data: [], pagination: { page: 1, limit: 0, total: 0, pages: 0, hasNext: false, hasPrev: false } };
         }
         try {
-            const result = await sdk.redemptions.getUserRedemptions();
+            const result = await sdk.redemptions.getUserRedemptions(undefined, include);
             return result;
         }
         catch (error) {
@@ -37391,6 +39096,40 @@ 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 = react.useCallback(async (filters, include) => {
+        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 = react.useCallback(async (redemptionData) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
@@ -37448,6 +39187,7 @@ const useRedemptions = () => {
         getUserRedemptions,
         redeem,
         getRedemptionTypes,
+        getRedemptionRedeems,
         createRedemption,
         updateRedemption,
         toggleRedemptionStatus,
@@ -37876,29 +39616,47 @@ const useFiles = () => {
 /**
  * React hook for analytics operations in the PERS SDK
  *
- * Provides methods for retrieving transaction analytics and insights.
- * Supports various analytics queries for business intelligence and reporting.
+ * Provides comprehensive analytics and business intelligence capabilities:
+ * - **Transaction Analytics**: Volume, trends, business performance
+ * - **Campaign Claim Analytics**: Campaign performance and claim patterns
+ * - **User Analytics**: Engagement metrics with per-active-user averages
+ * - **User Ranking**: Leaderboards with full user details
+ * - **Business Ranking**: Business performance rankings
+ * - **Retention Analytics**: Monthly retention metrics
  *
  * @returns Analytics hook with methods for data analysis
  *
- * @example
+ * @example Basic Transaction Analytics
  * ```typescript
  * function AnalyticsComponent() {
  *   const { getTransactionAnalytics } = useAnalytics();
  *
  *   const loadAnalytics = async () => {
- *     try {
- *       const analytics = await getTransactionAnalytics({
- *         timeRange: 'last_30_days',
- *         groupBy: 'day'
- *       });
- *       console.log('Transaction analytics:', analytics);
- *     } catch (error) {
- *       console.error('Failed to load analytics:', error);
- *     }
+ *     const analytics = await getTransactionAnalytics({
+ *       startDate: '2024-01-01',
+ *       endDate: '2024-01-31',
+ *       groupBy: 'day'
+ *     });
+ *     console.log('Transaction analytics:', analytics);
  *   };
+ * }
+ * ```
  *
- *   return <button onClick={loadAnalytics}>Load Analytics</button>;
+ * @example User Leaderboard
+ * ```typescript
+ * function LeaderboardScreen() {
+ *   const { getUserRanking } = useAnalytics();
+ *
+ *   const loadLeaderboard = async () => {
+ *     const ranking = await getUserRanking({
+ *       sortBy: 'totalTransactions',
+ *       sortOrder: 'DESC',
+ *       limit: 50
+ *     });
+ *     ranking.results.forEach((user, i) => {
+ *       console.log(`#${i + 1}: ${user.email} - ${user.totalTransactions} txns`);
+ *     });
+ *   };
  * }
  * ```
  */
@@ -37913,16 +39671,12 @@ const useAnalytics = () => {
      *
      * @example
      * ```typescript
-     * const { getTransactionAnalytics } = useAnalytics();
      * const analytics = await getTransactionAnalytics({
-     *   groupBy: ['day'],
-     *   metrics: ['count', 'sum'],
      *   startDate: '2024-01-01',
      *   endDate: '2024-01-31',
-     *   filters: { status: 'completed' }
+     *   groupBy: 'day',
+     *   metrics: ['count', 'sum']
      * });
-     * console.log('Daily transaction analytics:', analytics.results);
-     * console.log('Execution time:', analytics.metadata.executionTime);
      * ```
      */
     const getTransactionAnalytics = react.useCallback(async (request) => {
@@ -37938,8 +39692,214 @@ const useAnalytics = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
+    /**
+     * Retrieves campaign claim analytics with aggregation
+     *
+     * Provides insights into campaign performance, claim patterns, and user engagement.
+     *
+     * @param request - Analytics request with filters, groupBy, and metrics
+     * @returns Promise resolving to campaign claim analytics data
+     *
+     * @example Claims per campaign
+     * ```typescript
+     * const analytics = await getCampaignClaimAnalytics({
+     *   filters: { status: 'COMPLETED' },
+     *   groupBy: ['campaignId'],
+     *   metrics: ['count'],
+     *   sortBy: 'count',
+     *   sortOrder: 'DESC',
+     *   limit: 10
+     * });
+     * console.log('Top campaigns:', analytics.results);
+     * ```
+     */
+    const getCampaignClaimAnalytics = react.useCallback(async (request) => {
+        if (!isInitialized || !sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        try {
+            const result = await sdk.analytics.getCampaignClaimAnalytics(request);
+            return result;
+        }
+        catch (error) {
+            console.error('Failed to fetch campaign claim analytics:', error);
+            throw error;
+        }
+    }, [sdk, isInitialized]);
+    /**
+     * Retrieves user analytics with engagement metrics
+     *
+     * Includes both per-user and per-active-user metrics for accurate engagement insights.
+     * Per-active-user metrics show concentrated engagement among active users.
+     *
+     * @param request - Analytics request with optional filters and date range
+     * @returns Promise resolving to user analytics data
+     *
+     * @example Compare per-user vs per-active-user metrics
+     * ```typescript
+     * const analytics = await getUserAnalytics({
+     *   startDate: new Date('2026-02-01'),
+     *   endDate: new Date('2026-02-28')
+     * });
+     *
+     * console.log(`Active users: ${analytics.activeUsers} / ${analytics.totalUsers}`);
+     * console.log(`Engagement rate: ${analytics.engagementRate.toFixed(1)}%`);
+     *
+     * // Per-active-user metrics (more meaningful)
+     * console.log(`Avg transactions per active user: ${analytics.averageTransactionsPerActiveUser}`);
+     * ```
+     *
+     * @example Business-specific analytics
+     * ```typescript
+     * const analytics = await getUserAnalytics({
+     *   filters: { businessId: 'business-123' },
+     *   startDate: new Date('2026-01-01'),
+     *   endDate: new Date('2026-12-31')
+     * });
+     * ```
+     */
+    const getUserAnalytics = react.useCallback(async (request = {}) => {
+        if (!isInitialized || !sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        try {
+            const result = await sdk.analytics.getUserAnalytics(request);
+            return result;
+        }
+        catch (error) {
+            console.error('Failed to fetch user analytics:', error);
+            throw error;
+        }
+    }, [sdk, isInitialized]);
+    /**
+     * Retrieves user transaction ranking with enriched user data
+     *
+     * Returns ranked list of users with full user details (email, externalUserId)
+     * and transaction metrics. Ideal for leaderboards, engagement analysis,
+     * and identifying power users.
+     *
+     * @param request - Ranking request with filters, sorting, and limit
+     * @returns Promise resolving to ranked user list with transaction metrics
+     *
+     * @example Top 50 users by transaction count
+     * ```typescript
+     * const ranking = await getUserRanking({
+     *   sortBy: 'totalTransactions',
+     *   sortOrder: 'DESC',
+     *   limit: 50
+     * });
+     *
+     * ranking.results.forEach((user, index) => {
+     *   console.log(`#${index + 1}: ${user.email || user.externalUserId}`);
+     *   console.log(`  Transactions: ${user.totalTransactions}`);
+     *   console.log(`  Token spent: ${user.tokenSpent}`);
+     * });
+     * ```
+     *
+     * @example Top STAMP spenders
+     * ```typescript
+     * const ranking = await getUserRanking({
+     *   filters: { tokenType: 'STAMP' },
+     *   sortBy: 'tokenSpent',
+     *   sortOrder: 'DESC',
+     *   limit: 20
+     * });
+     * ```
+     */
+    const getUserRanking = react.useCallback(async (request = {}) => {
+        if (!isInitialized || !sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        try {
+            const result = await sdk.analytics.getUserRanking(request);
+            return result;
+        }
+        catch (error) {
+            console.error('Failed to fetch user ranking:', error);
+            throw error;
+        }
+    }, [sdk, isInitialized]);
+    /**
+     * Retrieves business transaction ranking with enriched business data
+     *
+     * Returns ranked list of businesses with transaction metrics for
+     * partner analytics and performance dashboards.
+     *
+     * @param request - Ranking request with filters, sorting, and limit
+     * @returns Promise resolving to ranked business list
+     *
+     * @example Top businesses by transaction count
+     * ```typescript
+     * const ranking = await getBusinessRanking({
+     *   sortBy: 'totalTransactions',
+     *   sortOrder: 'DESC',
+     *   limit: 20
+     * });
+     *
+     * ranking.results.forEach((business, index) => {
+     *   console.log(`#${index + 1}: ${business.businessId}`);
+     *   console.log(`  Transactions: ${business.totalTransactions}`);
+     *   console.log(`  Token spent: ${business.tokenSpent}`);
+     * });
+     * ```
+     */
+    const getBusinessRanking = react.useCallback(async (request = {}) => {
+        if (!isInitialized || !sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        try {
+            const result = await sdk.analytics.getBusinessRanking(request);
+            return result;
+        }
+        catch (error) {
+            console.error('Failed to fetch business ranking:', error);
+            throw error;
+        }
+    }, [sdk, isInitialized]);
+    /**
+     * Retrieves monthly user retention analytics
+     *
+     * Returns monthly retention data with active, new, and returning users
+     * along with retention rates. Useful for churn analysis and engagement trends.
+     *
+     * @param request - Retention request with monthsBack and filters
+     * @returns Promise resolving to monthly retention data
+     *
+     * @example Get 12 months of retention data
+     * ```typescript
+     * const retention = await getRetentionAnalytics({
+     *   monthsBack: 12
+     * });
+     *
+     * retention.results.forEach(month => {
+     *   console.log(`${month.month}:`);
+     *   console.log(`  Active: ${month.activeUsers}`);
+     *   console.log(`  New: ${month.newUsers}`);
+     *   console.log(`  Returning: ${month.returningUsers}`);
+     *   console.log(`  Retention Rate: ${month.retentionRate.toFixed(1)}%`);
+     * });
+     * ```
+     */
+    const getRetentionAnalytics = react.useCallback(async (request = {}) => {
+        if (!isInitialized || !sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        try {
+            const result = await sdk.analytics.getRetentionAnalytics(request);
+            return result;
+        }
+        catch (error) {
+            console.error('Failed to fetch retention analytics:', error);
+            throw error;
+        }
+    }, [sdk, isInitialized]);
     return {
         getTransactionAnalytics,
+        getCampaignClaimAnalytics,
+        getUserAnalytics,
+        getUserRanking,
+        getBusinessRanking,
+        getRetentionAnalytics,
         isAvailable: isInitialized && !!sdk?.analytics,
     };
 };
@@ -38315,6 +40275,277 @@ const useEvents = () => {
     };
 };
 
+/**
+ * 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 }
+ * });
+ * ```
+ */
+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 = react.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 = react.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 = react.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 = react.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 = react.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,
+    };
+};
+
 // ==========================================
 // TOKEN UTILITY FUNCTIONS
 // ==========================================
@@ -38396,12 +40627,22 @@ exports.MEMBERSHIP_ROLE_HIERARCHY = MEMBERSHIP_ROLE_HIERARCHY;
 exports.NativeTokenTypes = NativeTokenTypes;
 exports.PersApiError = PersApiError;
 exports.PersSDKProvider = PersSDKProvider;
+exports.QUERY_OPERATOR_SQL_MAP = QUERY_OPERATOR_SQL_MAP;
 exports.ReactNativeDPoPProvider = ReactNativeDPoPProvider;
 exports.ReactNativeHttpClient = ReactNativeHttpClient;
 exports.ReactNativeSecureStorage = ReactNativeSecureStorage;
+exports.SOURCE_LOGIC_TYPES = SOURCE_LOGIC_TYPES;
+exports.SOURCE_LOGIC_TYPE_VALUES = SOURCE_LOGIC_TYPE_VALUES;
 exports.SigningStatus = SigningStatus;
 exports.TRANSACTION_FORMATS = TRANSACTION_FORMATS;
 exports.TRANSACTION_FORMAT_DESCRIPTIONS = TRANSACTION_FORMAT_DESCRIPTIONS;
+exports.TRIGGER_SOURCE_TYPES = TRIGGER_SOURCE_TYPES;
+exports.TRIGGER_SOURCE_TYPE_VALUES = TRIGGER_SOURCE_TYPE_VALUES;
+exports.VALID_CAMPAIGN_CLAIM_RELATIONS = VALID_CAMPAIGN_CLAIM_RELATIONS;
+exports.VALID_CAMPAIGN_RELATIONS = VALID_CAMPAIGN_RELATIONS;
+exports.VALID_REDEMPTION_REDEEM_RELATIONS = VALID_REDEMPTION_REDEEM_RELATIONS;
+exports.VALID_RELATIONS = VALID_RELATIONS;
+exports.VALID_TRANSACTION_RELATIONS = VALID_TRANSACTION_RELATIONS;
 exports.apiPublicKeyTestPrefix = apiPublicKeyTestPrefix;
 exports.buildBurnRequest = buildBurnRequest;
 exports.buildMintRequest = buildMintRequest;
@@ -38423,6 +40664,11 @@ exports.hasMinimumRole = hasMinimumRole;
 exports.initializeReactNativePolyfills = initializeReactNativePolyfills;
 exports.isPaginatedResponse = isPaginatedResponse;
 exports.isUserIdentifierObject = isUserIdentifierObject;
+exports.isValidCampaignClaimRelation = isValidCampaignClaimRelation;
+exports.isValidCampaignRelation = isValidCampaignRelation;
+exports.isValidRedemptionRedeemRelation = isValidRedemptionRedeemRelation;
+exports.isValidRelation = isValidRelation;
+exports.isValidTransactionRelation = isValidTransactionRelation;
 exports.normalizeToPaginated = normalizeToPaginated;
 exports.registerIdentifierType = registerIdentifierType;
 exports.testnetPrefix = testnetPrefix;
@@ -38443,6 +40689,7 @@ exports.useTokenBalances = useTokenBalances;
 exports.useTokens = useTokens;
 exports.useTransactionSigner = useTransactionSigner;
 exports.useTransactions = useTransactions;
+exports.useTriggerSources = useTriggerSources;
 exports.useUserStatus = useUserStatus;
 exports.useUsers = useUsers;
 exports.useWeb3 = useWeb3;