@explorins/pers-sdk 2.1.2 → 2.1.4

package/dist/chunks/{pers-sdk-D5lE9ZFW.cjs → pers-sdk-Di_R6AiT.cjs}

@@ -7,12 +7,12 @@ var userStatus = require('../user-status.cjs');
 var tokenService = require('./token-service-BlbXrxnS.cjs');
 var businessMembershipService = require('./business-membership-service-8KC_qRj7.cjs');
 var campaign = require('../campaign.cjs');
-var redemptionService = require('./redemption-service-rMB6T2W5.cjs');
-var transactionRequest_builder = require('./transaction-request.builder-BpgtuMMq.cjs');
+var redemptionService = require('./redemption-service-DsH7sRdv.cjs');
+var transactionRequest_builder = require('./transaction-request.builder-CkYd5bl6.cjs');
 var paymentService = require('./payment-service-Bkw7ZXev.cjs');
 var tenantService = require('./tenant-service-fj-pkXTw.cjs');
 var paginationUtils = require('./pagination-utils-B2jRHMSO.cjs');
-var analytics = require('../analytics.cjs');
+var analyticsService = require('./analytics-service-DwkeBB08.cjs');
 var donation = require('../donation.cjs');
 
 /**
@@ -30,8 +30,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
@@ -341,8 +340,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(exports.AuthStatus.AUTHENTICATED);
         }
@@ -361,8 +364,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) {
@@ -373,6 +383,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) {
@@ -456,42 +474,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);
@@ -499,13 +552,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;
     }
@@ -733,6 +796,7 @@ class DPoPManager {
 class DefaultAuthProvider {
     constructor(config = {}) {
         this.config = config;
+        this.authTypeCache = null;
         this.authType = config.authType || persShared.AccountOwnerType.USER;
         const storage = config.storage || this.createStorage();
         this.tokenManager = new AuthTokenManager(storage);
@@ -793,6 +857,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);
@@ -802,16 +875,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;
+        }
+    }
 }
 
 /**
@@ -1006,13 +1114,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',
@@ -1975,26 +2085,57 @@ 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 and sorting options
+     * @param options.page - Page number (1-based, default: 1)
+     * @param options.limit - Items per page (default: 50)
+     * @param options.sortBy - Sort by field. Supported fields:
+     *   - 'id', 'email', 'identifierEmail', 'firstName', 'lastName'
+     *   - 'externalId', 'accountAddress', 'isActive'
+     *   - 'createdAt', 'updatedAt'
+     *   - Default: 'createdAt'
+     * @param options.sortOrder - Sort order: SortOrder.ASC or SortOrder.DESC (default: DESC)
+     * @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
@@ -3159,6 +3300,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
      *
@@ -3187,9 +3329,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
@@ -3334,6 +3484,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) {
@@ -3451,57 +3606,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: 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()`.
+     *
+     * @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: Set campaign trigger
+     * Admin: Assign a trigger to a campaign
      *
-     * Associates a specific trigger mechanism with a campaign, enabling automatic
-     * campaign activation based on defined conditions. Requires administrator privileges.
+     * 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
      *
@@ -3710,8 +3996,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
@@ -3746,8 +4032,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
@@ -3787,8 +4073,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
@@ -4172,8 +4529,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
@@ -4416,8 +4822,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();
@@ -4440,13 +4846,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);
@@ -4459,16 +4870,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
@@ -4481,8 +4895,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
@@ -4576,150 +4990,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
@@ -4783,9 +5109,23 @@ 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 },
+     *   ['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(params, include) {
+        return this.transactionService.getPaginatedTransactions(params, include);
     }
     /**
      * Admin: Export transactions as CSV
@@ -6262,8 +6602,8 @@ class ApiKeyManager {
 class AnalyticsManager {
     constructor(apiClient) {
         this.apiClient = apiClient;
-        const analyticsApi = new analytics.AnalyticsApi(apiClient);
-        this.analyticsService = new analytics.AnalyticsService(analyticsApi);
+        const analyticsApi = new analyticsService.AnalyticsApi(apiClient);
+        this.analyticsService = new analyticsService.AnalyticsService(analyticsApi);
     }
     /**
      * Get transaction analytics
@@ -6449,20 +6789,193 @@ class AnalyticsManager {
         return this.analyticsService.getTransactionAnalytics(request);
     }
     /**
-     * Get the full analytics service for advanced operations
+     * Get campaign claim analytics with aggregation
      *
-     * Provides access to the complete AnalyticsService instance for advanced analytics
-     * operations, custom metrics, predictive analytics, cohort analysis, and
-     * operations not covered by the high-level manager methods.
+     * 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.
      *
-     * @returns AnalyticsService instance with full API access
+     * @param request - Analytics request with filters, groupBy, and metrics
+     * @returns Promise resolving to campaign claim analytics data
      *
-     * @example Advanced Analytics Operations
+     * @example Claims per campaign
      * ```typescript
-     * const analyticsService = sdk.analytics.getAnalyticsService();
+     * const analytics = await sdk.analytics.getCampaignClaimAnalytics({
+     *   filters: { status: 'COMPLETED' },
+     *   groupBy: ['campaignId'],
+     *   metrics: ['count'],
+     *   sortBy: 'count',
+     *   sortOrder: 'DESC',
+     *   limit: 10
+     * });
      *
-     * // Access user engagement analytics
-     * const engagementMetrics = await analyticsService.getUserEngagementMetrics({
+     * 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
+     *
+     * Provides access to the complete AnalyticsService instance for advanced analytics
+     * operations, custom metrics, predictive analytics, cohort analysis, and
+     * operations not covered by the high-level manager methods.
+     *
+     * @returns AnalyticsService instance with full API access
+     *
+     * @example Advanced Analytics Operations
+     * ```typescript
+     * const analyticsService = sdk.analytics.getAnalyticsService();
+     *
+     * // Access user engagement analytics
+     * const engagementMetrics = await analyticsService.getUserEngagementMetrics({
      *   timeframe: 'last-90-days',
      *   includeSegmentation: true
      * });
@@ -6542,6 +7055,360 @@ class DonationManager {
     }
 }
 
+/**
+ * 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 = paginationUtils.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 paginationUtils.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);
+    }
+}
+
+/**
+ * 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
  *
@@ -6655,78 +7522,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
+     *
+     * 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.
      *
-     * 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.
+     * **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 === persShared.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;
         }
     }
     /**
@@ -6815,6 +7675,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;
     }
     /**
@@ -6828,6 +7691,9 @@ class PersSDK {
      * ```
      */
     get users() {
+        if (!this._users) {
+            this._users = new UserManager(this.apiClient, this._events);
+        }
         return this._users;
     }
     /**
@@ -6841,6 +7707,9 @@ class PersSDK {
      * ```
      */
     get userStatus() {
+        if (!this._userStatus) {
+            this._userStatus = new UserStatusManager(this.apiClient);
+        }
         return this._userStatus;
     }
     /**
@@ -6854,6 +7723,9 @@ class PersSDK {
      * ```
      */
     get tokens() {
+        if (!this._tokens) {
+            this._tokens = new TokenManager(this.apiClient);
+        }
         return this._tokens;
     }
     /**
@@ -6867,6 +7739,9 @@ class PersSDK {
      * ```
      */
     get businesses() {
+        if (!this._businesses) {
+            this._businesses = new BusinessManager(this.apiClient, this._events);
+        }
         return this._businesses;
     }
     /**
@@ -6880,6 +7755,9 @@ class PersSDK {
      * ```
      */
     get campaigns() {
+        if (!this._campaigns) {
+            this._campaigns = new CampaignManager(this.apiClient, this._events);
+        }
         return this._campaigns;
     }
     /**
@@ -6893,6 +7771,9 @@ class PersSDK {
      * ```
      */
     get redemptions() {
+        if (!this._redemptions) {
+            this._redemptions = new RedemptionManager(this.apiClient, this._events);
+        }
         return this._redemptions;
     }
     /**
@@ -6906,6 +7787,9 @@ class PersSDK {
      * ```
      */
     get transactions() {
+        if (!this._transactions) {
+            this._transactions = new TransactionManager(this.apiClient, this._events);
+        }
         return this._transactions;
     }
     /**
@@ -6919,6 +7803,9 @@ class PersSDK {
      * ```
      */
     get purchases() {
+        if (!this._purchases) {
+            this._purchases = new PurchaseManager(this.apiClient);
+        }
         return this._purchases;
     }
     /**
@@ -6932,6 +7819,9 @@ class PersSDK {
      * ```
      */
     get files() {
+        if (!this._files) {
+            this._files = new FileManager(this.apiClient);
+        }
         return this._files;
     }
     /**
@@ -6945,6 +7835,9 @@ class PersSDK {
      * ```
      */
     get tenants() {
+        if (!this._tenants) {
+            this._tenants = new TenantManager(this.apiClient);
+        }
         return this._tenants;
     }
     /**
@@ -6969,6 +7862,9 @@ class PersSDK {
      * ```
      */
     get apiKeys() {
+        if (!this._apiKeys) {
+            this._apiKeys = new ApiKeyManager(this.apiClient);
+        }
         return this._apiKeys;
     }
     /**
@@ -6980,6 +7876,9 @@ class PersSDK {
      * ```
      */
     get analytics() {
+        if (!this._analytics) {
+            this._analytics = new AnalyticsManager(this.apiClient);
+        }
         return this._analytics;
     }
     /**
@@ -6991,8 +7890,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
      *
@@ -7074,10 +8010,13 @@ exports.StaticJwtAuthProvider = StaticJwtAuthProvider;
 exports.TenantManager = TenantManager;
 exports.TokenManager = TokenManager;
 exports.TransactionManager = TransactionManager;
+exports.TriggerSourceApi = TriggerSourceApi;
+exports.TriggerSourceManager = TriggerSourceManager;
+exports.TriggerSourceService = TriggerSourceService;
 exports.UserManager = UserManager;
 exports.UserStatusManager = UserStatusManager;
 exports.WebDPoPCryptoProvider = WebDPoPCryptoProvider;
 exports.buildApiRoot = buildApiRoot;
 exports.createPersSDK = createPersSDK;
 exports.mergeWithDefaults = mergeWithDefaults;
-//# sourceMappingURL=pers-sdk-D5lE9ZFW.cjs.map
+//# sourceMappingURL=pers-sdk-Di_R6AiT.cjs.map