@explorins/pers-sdk 2.1.2 → 2.1.4

package/dist/chunks/{pers-sdk-DnLw822h.js → pers-sdk-CAM0iQyK.js}

@@ -5,12 +5,12 @@ import { createUserStatusSDK } from '../user-status.js';
 import { a as TokenService, T as TokenApi } from './token-service-Bfj6C0yz.js';
 import { B as BusinessApi, b as BusinessService, a as BusinessMembershipApi, c as BusinessMembershipService } from './business-membership-service-D6vaVQTR.js';
 import { CampaignService, CampaignApi } from '../campaign.js';
-import { a as RedemptionService, R as RedemptionApi } from './redemption-service-D-hBqh42.js';
-import { a as TransactionService, T as TransactionApi } from './transaction-request.builder-C1vVVFto.js';
+import { a as RedemptionService, R as RedemptionApi } from './redemption-service-CQtTLdic.js';
+import { a as TransactionService, T as TransactionApi } from './transaction-request.builder-C8ahJYwi.js';
 import { a as PaymentService, P as PurchaseApi } from './payment-service-IvM6rryM.js';
 import { a as TenantService, T as TenantApi } from './tenant-service-CsRA3O2V.js';
 import { b as buildPaginationParams, n as normalizeToPaginated } from './pagination-utils-9vQ-Npkr.js';
-import { AnalyticsService, AnalyticsApi } from '../analytics.js';
+import { a as AnalyticsService, A as AnalyticsApi } from './analytics-service-B9IfG6ox.js';
 import { DonationService, DonationApi } from '../donation.js';
 
 /**
@@ -28,8 +28,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
@@ -339,8 +338,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);
         }
@@ -359,8 +362,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) {
@@ -371,6 +381,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) {
@@ -454,42 +472,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);
@@ -497,13 +550,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;
     }
@@ -731,6 +794,7 @@ class DPoPManager {
 class DefaultAuthProvider {
     constructor(config = {}) {
         this.config = config;
+        this.authTypeCache = null;
         this.authType = config.authType || AccountOwnerType.USER;
         const storage = config.storage || this.createStorage();
         this.tokenManager = new AuthTokenManager(storage);
@@ -791,6 +855,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);
@@ -800,16 +873,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;
+        }
+    }
 }
 
 /**
@@ -1004,13 +1112,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',
@@ -1973,26 +2083,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
@@ -3157,6 +3298,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
      *
@@ -3185,9 +3327,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
@@ -3332,6 +3482,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) {
@@ -3449,57 +3604,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
      *
@@ -3708,8 +3994,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
@@ -3744,8 +4030,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
@@ -3785,8 +4071,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
@@ -4170,8 +4527,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
@@ -4414,8 +4820,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();
@@ -4438,13 +4844,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);
@@ -4457,16 +4868,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
@@ -4479,8 +4893,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
@@ -4574,150 +4988,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
@@ -4781,9 +5107,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
@@ -6447,20 +6787,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
      * });
@@ -6540,6 +7053,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 = 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);
+    }
+}
+
+/**
+ * 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
  *
@@ -6653,78 +7520,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 === 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;
         }
     }
     /**
@@ -6813,6 +7673,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;
     }
     /**
@@ -6826,6 +7689,9 @@ class PersSDK {
      * ```
      */
     get users() {
+        if (!this._users) {
+            this._users = new UserManager(this.apiClient, this._events);
+        }
         return this._users;
     }
     /**
@@ -6839,6 +7705,9 @@ class PersSDK {
      * ```
      */
     get userStatus() {
+        if (!this._userStatus) {
+            this._userStatus = new UserStatusManager(this.apiClient);
+        }
         return this._userStatus;
     }
     /**
@@ -6852,6 +7721,9 @@ class PersSDK {
      * ```
      */
     get tokens() {
+        if (!this._tokens) {
+            this._tokens = new TokenManager(this.apiClient);
+        }
         return this._tokens;
     }
     /**
@@ -6865,6 +7737,9 @@ class PersSDK {
      * ```
      */
     get businesses() {
+        if (!this._businesses) {
+            this._businesses = new BusinessManager(this.apiClient, this._events);
+        }
         return this._businesses;
     }
     /**
@@ -6878,6 +7753,9 @@ class PersSDK {
      * ```
      */
     get campaigns() {
+        if (!this._campaigns) {
+            this._campaigns = new CampaignManager(this.apiClient, this._events);
+        }
         return this._campaigns;
     }
     /**
@@ -6891,6 +7769,9 @@ class PersSDK {
      * ```
      */
     get redemptions() {
+        if (!this._redemptions) {
+            this._redemptions = new RedemptionManager(this.apiClient, this._events);
+        }
         return this._redemptions;
     }
     /**
@@ -6904,6 +7785,9 @@ class PersSDK {
      * ```
      */
     get transactions() {
+        if (!this._transactions) {
+            this._transactions = new TransactionManager(this.apiClient, this._events);
+        }
         return this._transactions;
     }
     /**
@@ -6917,6 +7801,9 @@ class PersSDK {
      * ```
      */
     get purchases() {
+        if (!this._purchases) {
+            this._purchases = new PurchaseManager(this.apiClient);
+        }
         return this._purchases;
     }
     /**
@@ -6930,6 +7817,9 @@ class PersSDK {
      * ```
      */
     get files() {
+        if (!this._files) {
+            this._files = new FileManager(this.apiClient);
+        }
         return this._files;
     }
     /**
@@ -6943,6 +7833,9 @@ class PersSDK {
      * ```
      */
     get tenants() {
+        if (!this._tenants) {
+            this._tenants = new TenantManager(this.apiClient);
+        }
         return this._tenants;
     }
     /**
@@ -6967,6 +7860,9 @@ class PersSDK {
      * ```
      */
     get apiKeys() {
+        if (!this._apiKeys) {
+            this._apiKeys = new ApiKeyManager(this.apiClient);
+        }
         return this._apiKeys;
     }
     /**
@@ -6978,6 +7874,9 @@ class PersSDK {
      * ```
      */
     get analytics() {
+        if (!this._analytics) {
+            this._analytics = new AnalyticsManager(this.apiClient);
+        }
         return this._analytics;
     }
     /**
@@ -6989,8 +7888,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
      *
@@ -7040,5 +7976,5 @@ function createPersSDK(httpClient, config) {
     return new PersSDK(httpClient, config);
 }
 
-export { AuthStatus as A, BusinessManager as B, CampaignManager as C, DefaultAuthProvider as D, FileManager as F, LocalStorageTokenStorage as L, MemoryTokenStorage as M, PersSDK as P, RedemptionManager as R, SDK_NAME as S, TokenManager as T, UserManager as U, WebDPoPCryptoProvider as W, AuthTokenManager as a, AUTH_STORAGE_KEYS as b, createPersSDK as c, DPOP_STORAGE_KEYS as d, SDK_VERSION as e, SDK_USER_AGENT as f, PersApiClient as g, DEFAULT_PERS_CONFIG as h, buildApiRoot as i, StaticJwtAuthProvider as j, AuthApi as k, AuthService as l, mergeWithDefaults as m, DPoPManager as n, PersEventEmitter as o, AuthManager as p, UserStatusManager as q, TransactionManager as r, PurchaseManager as s, TenantManager as t, ApiKeyManager as u, AnalyticsManager as v, DonationManager as w, FileApi as x, FileService as y, ApiKeyApi as z };
-//# sourceMappingURL=pers-sdk-DnLw822h.js.map
+export { AuthStatus as A, BusinessManager as B, CampaignManager as C, DefaultAuthProvider as D, ApiKeyApi as E, FileManager as F, TriggerSourceApi as G, TriggerSourceService as H, LocalStorageTokenStorage as L, MemoryTokenStorage as M, PersSDK as P, RedemptionManager as R, SDK_NAME as S, TokenManager as T, UserManager as U, WebDPoPCryptoProvider as W, AuthTokenManager as a, AUTH_STORAGE_KEYS as b, createPersSDK as c, DPOP_STORAGE_KEYS as d, SDK_VERSION as e, SDK_USER_AGENT as f, PersApiClient as g, DEFAULT_PERS_CONFIG as h, buildApiRoot as i, StaticJwtAuthProvider as j, AuthApi as k, AuthService as l, mergeWithDefaults as m, DPoPManager as n, PersEventEmitter as o, AuthManager as p, UserStatusManager as q, TransactionManager as r, PurchaseManager as s, TenantManager as t, ApiKeyManager as u, AnalyticsManager as v, DonationManager as w, TriggerSourceManager as x, FileApi as y, FileService as z };
+//# sourceMappingURL=pers-sdk-CAM0iQyK.js.map