@explorins/pers-sdk 2.1.3 → 2.1.4

package/dist/core.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var persSdk = require('./chunks/pers-sdk-BQw3QUWR.cjs');
+var persSdk = require('./chunks/pers-sdk-Di_R6AiT.cjs');
 var persShared = require('@explorins/pers-shared');
 var environment = require('./chunks/environment-C73snhIJ.cjs');
 var index = require('./chunks/index-B6-bbNnd.cjs');
@@ -11,11 +11,11 @@ require('./user-status.cjs');
 require('./chunks/token-service-BlbXrxnS.cjs');
 require('./chunks/business-membership-service-8KC_qRj7.cjs');
 require('./campaign.cjs');
-require('./chunks/redemption-service-rMB6T2W5.cjs');
-require('./chunks/transaction-request.builder-BpgtuMMq.cjs');
+require('./chunks/redemption-service-DsH7sRdv.cjs');
+require('./chunks/transaction-request.builder-CkYd5bl6.cjs');
 require('./chunks/payment-service-Bkw7ZXev.cjs');
 require('./chunks/tenant-service-fj-pkXTw.cjs');
-require('./analytics.cjs');
+require('./chunks/analytics-service-DwkeBB08.cjs');
 require('./donation.cjs');
 
 
@@ -49,6 +49,7 @@ exports.StaticJwtAuthProvider = persSdk.StaticJwtAuthProvider;
 exports.TenantManager = persSdk.TenantManager;
 exports.TokenManager = persSdk.TokenManager;
 exports.TransactionManager = persSdk.TransactionManager;
+exports.TriggerSourceManager = persSdk.TriggerSourceManager;
 exports.UserManager = persSdk.UserManager;
 exports.UserStatusManager = persSdk.UserStatusManager;
 exports.WebDPoPCryptoProvider = persSdk.WebDPoPCryptoProvider;

package/dist/core.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"core.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"core.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/core.js

@@ -1,4 +1,4 @@
-export { b as AUTH_STORAGE_KEYS, v as AnalyticsManager, u as ApiKeyManager, k as AuthApi, p as AuthManager, l as AuthService, a as AuthTokenManager, B as BusinessManager, C as CampaignManager, h as DEFAULT_PERS_CONFIG, d as DPOP_STORAGE_KEYS, n as DPoPManager, D as DefaultAuthProvider, w as DonationManager, F as FileManager, L as LocalStorageTokenStorage, M as MemoryTokenStorage, g as PersApiClient, o as PersEventEmitter, P as PersSDK, s as PurchaseManager, R as RedemptionManager, S as SDK_NAME, f as SDK_USER_AGENT, e as SDK_VERSION, j as StaticJwtAuthProvider, t as TenantManager, T as TokenManager, r as TransactionManager, U as UserManager, q as UserStatusManager, W as WebDPoPCryptoProvider, i as buildApiRoot, c as createPersSDK, m as mergeWithDefaults } from './chunks/pers-sdk-fWg-J3_h.js';
+export { b as AUTH_STORAGE_KEYS, v as AnalyticsManager, u as ApiKeyManager, k as AuthApi, p as AuthManager, l as AuthService, a as AuthTokenManager, B as BusinessManager, C as CampaignManager, h as DEFAULT_PERS_CONFIG, d as DPOP_STORAGE_KEYS, n as DPoPManager, D as DefaultAuthProvider, w as DonationManager, F as FileManager, L as LocalStorageTokenStorage, M as MemoryTokenStorage, g as PersApiClient, o as PersEventEmitter, P as PersSDK, s as PurchaseManager, R as RedemptionManager, S as SDK_NAME, f as SDK_USER_AGENT, e as SDK_VERSION, j as StaticJwtAuthProvider, t as TenantManager, T as TokenManager, r as TransactionManager, x as TriggerSourceManager, U as UserManager, q as UserStatusManager, W as WebDPoPCryptoProvider, i as buildApiRoot, c as createPersSDK, m as mergeWithDefaults } from './chunks/pers-sdk-CAM0iQyK.js';
 export { AccountOwnerType } from '@explorins/pers-shared';
 export { I as IndexedDBTokenStorage, d as detectEnvironment, e as environment, w as warnIfProblematicEnvironment } from './chunks/environment-CKVwRAEL.js';
 export { a as CacheService, C as CacheTTL, g as globalCacheService } from './chunks/index-DBLskLuH.js';
@@ -9,10 +9,10 @@ import './user-status.js';
 import './chunks/token-service-Bfj6C0yz.js';
 import './chunks/business-membership-service-D6vaVQTR.js';
 import './campaign.js';
-import './chunks/redemption-service-D-hBqh42.js';
-import './chunks/transaction-request.builder-C1vVVFto.js';
+import './chunks/redemption-service-CQtTLdic.js';
+import './chunks/transaction-request.builder-C8ahJYwi.js';
 import './chunks/payment-service-IvM6rryM.js';
 import './chunks/tenant-service-CsRA3O2V.js';
-import './analytics.js';
+import './chunks/analytics-service-B9IfG6ox.js';
 import './donation.js';
 //# sourceMappingURL=core.js.map

package/dist/index.cjs

@@ -1,18 +1,18 @@
 'use strict';
 
-var persSdk = require('./chunks/pers-sdk-BQw3QUWR.cjs');
+var persSdk = require('./chunks/pers-sdk-Di_R6AiT.cjs');
 var persShared = require('@explorins/pers-shared');
 var environment = require('./chunks/environment-C73snhIJ.cjs');
 var index = require('./chunks/index-B6-bbNnd.cjs');
 var index$1 = require('./chunks/index-B-g2JPVK.cjs');
 var paginationUtils = require('./chunks/pagination-utils-B2jRHMSO.cjs');
 var businessMembershipService = require('./chunks/business-membership-service-8KC_qRj7.cjs');
-var transactionRequest_builder = require('./chunks/transaction-request.builder-BpgtuMMq.cjs');
-var analytics = require('./analytics.cjs');
+var transactionRequest_builder = require('./chunks/transaction-request.builder-CkYd5bl6.cjs');
+var analyticsService = require('./chunks/analytics-service-DwkeBB08.cjs');
 var campaign = require('./campaign.cjs');
 var donation = require('./donation.cjs');
 var paymentService = require('./chunks/payment-service-Bkw7ZXev.cjs');
-var redemptionService = require('./chunks/redemption-service-rMB6T2W5.cjs');
+var redemptionService = require('./chunks/redemption-service-DsH7sRdv.cjs');
 var tenantService = require('./chunks/tenant-service-fj-pkXTw.cjs');
 var baseTokenService = require('./chunks/base-token-service-Pvja-ykj.cjs');
 var tokenService = require('./chunks/token-service-BlbXrxnS.cjs');
@@ -59,6 +59,9 @@ exports.StaticJwtAuthProvider = persSdk.StaticJwtAuthProvider;
 exports.TenantManager = persSdk.TenantManager;
 exports.TokenManager = persSdk.TokenManager;
 exports.TransactionManager = persSdk.TransactionManager;
+exports.TriggerSourceApi = persSdk.TriggerSourceApi;
+exports.TriggerSourceManager = persSdk.TriggerSourceManager;
+exports.TriggerSourceService = persSdk.TriggerSourceService;
 exports.UserManager = persSdk.UserManager;
 exports.UserStatusManager = persSdk.UserStatusManager;
 exports.WebDPoPCryptoProvider = persSdk.WebDPoPCryptoProvider;
@@ -69,6 +72,10 @@ Object.defineProperty(exports, "AccountOwnerType", {
 	enumerable: true,
 	get: function () { return persShared.AccountOwnerType; }
 });
+Object.defineProperty(exports, "SortOrder", {
+	enumerable: true,
+	get: function () { return persShared.SortOrder; }
+});
 exports.IndexedDBTokenStorage = environment.IndexedDBTokenStorage;
 exports.detectEnvironment = environment.detectEnvironment;
 exports.environment = environment.environment;
@@ -105,8 +112,8 @@ exports.buildPendingTransactionData = transactionRequest_builder.buildPendingTra
 exports.buildSubmissionRequest = transactionRequest_builder.buildSubmissionRequest;
 exports.buildTransferRequest = transactionRequest_builder.buildTransferRequest;
 exports.extractDeadlineFromSigningData = transactionRequest_builder.extractDeadlineFromSigningData;
-exports.AnalyticsApi = analytics.AnalyticsApi;
-exports.AnalyticsService = analytics.AnalyticsService;
+exports.AnalyticsApi = analyticsService.AnalyticsApi;
+exports.AnalyticsService = analyticsService.AnalyticsService;
 exports.CampaignApi = campaign.CampaignApi;
 exports.CampaignService = campaign.CampaignService;
 exports.DonationApi = donation.DonationApi;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export * from './token';
 export * from './user';
 export * from './user-status';
 export * from './api-key';
+export * from './trigger-source';
 export { PersSDK, createPersSDK } from './pers-sdk';
 export * from './platform-adapters';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,QAAQ,CAAA;AAGtB,cAAc,YAAY,CAAC;AAG3B,cAAc,UAAU,CAAC;AAGzB,cAAc,YAAY,CAAC;AAG3B,cAAc,eAAe,CAAC;AAG9B,cAAc,aAAa,CAAC;AAG5B,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAGrD,cAAc,YAAY,CAAC;AAG3B,cAAc,YAAY,CAAC;AAG3B,cAAc,WAAW,CAAC;AAG1B,cAAc,QAAQ,CAAC;AAGvB,cAAc,cAAc,CAAC;AAG7B,cAAc,UAAU,CAAC;AAGzB,cAAc,SAAS,CAAC;AAGxB,cAAc,QAAQ,CAAC;AAGvB,cAAc,eAAe,CAAC;AAG9B,cAAc,WAAW,CAAC;AAS1B,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGpD,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,QAAQ,CAAA;AAGtB,cAAc,YAAY,CAAC;AAG3B,cAAc,UAAU,CAAC;AAGzB,cAAc,YAAY,CAAC;AAG3B,cAAc,eAAe,CAAC;AAG9B,cAAc,aAAa,CAAC;AAG5B,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAGrD,cAAc,YAAY,CAAC;AAG3B,cAAc,YAAY,CAAC;AAG3B,cAAc,WAAW,CAAC;AAG1B,cAAc,QAAQ,CAAC;AAGvB,cAAc,cAAc,CAAC;AAG7B,cAAc,UAAU,CAAC;AAGzB,cAAc,SAAS,CAAC;AAGxB,cAAc,QAAQ,CAAC;AAGvB,cAAc,eAAe,CAAC;AAG9B,cAAc,WAAW,CAAC;AAG1B,cAAc,kBAAkB,CAAC;AASjC,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGpD,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,17 +1,17 @@
-export { b as AUTH_STORAGE_KEYS, v as AnalyticsManager, z as ApiKeyApi, u as ApiKeyManager, k as AuthApi, p as AuthManager, l as AuthService, A as AuthStatus, a as AuthTokenManager, B as BusinessManager, C as CampaignManager, h as DEFAULT_PERS_CONFIG, d as DPOP_STORAGE_KEYS, n as DPoPManager, D as DefaultAuthProvider, w as DonationManager, x as FileApi, F as FileManager, y as FileService, L as LocalStorageTokenStorage, M as MemoryTokenStorage, g as PersApiClient, o as PersEventEmitter, P as PersSDK, s as PurchaseManager, R as RedemptionManager, S as SDK_NAME, f as SDK_USER_AGENT, e as SDK_VERSION, j as StaticJwtAuthProvider, t as TenantManager, T as TokenManager, r as TransactionManager, U as UserManager, q as UserStatusManager, W as WebDPoPCryptoProvider, i as buildApiRoot, c as createPersSDK, m as mergeWithDefaults } from './chunks/pers-sdk-fWg-J3_h.js';
+export { b as AUTH_STORAGE_KEYS, v as AnalyticsManager, E as ApiKeyApi, u as ApiKeyManager, k as AuthApi, p as AuthManager, l as AuthService, A as AuthStatus, a as AuthTokenManager, B as BusinessManager, C as CampaignManager, h as DEFAULT_PERS_CONFIG, d as DPOP_STORAGE_KEYS, n as DPoPManager, D as DefaultAuthProvider, w as DonationManager, y as FileApi, F as FileManager, z as FileService, L as LocalStorageTokenStorage, M as MemoryTokenStorage, g as PersApiClient, o as PersEventEmitter, P as PersSDK, s as PurchaseManager, R as RedemptionManager, S as SDK_NAME, f as SDK_USER_AGENT, e as SDK_VERSION, j as StaticJwtAuthProvider, t as TenantManager, T as TokenManager, r as TransactionManager, G as TriggerSourceApi, x as TriggerSourceManager, H as TriggerSourceService, U as UserManager, q as UserStatusManager, W as WebDPoPCryptoProvider, i as buildApiRoot, c as createPersSDK, m as mergeWithDefaults } from './chunks/pers-sdk-CAM0iQyK.js';
 export * from '@explorins/pers-shared';
-export { AccountOwnerType } from '@explorins/pers-shared';
+export { AccountOwnerType, SortOrder } from '@explorins/pers-shared';
 export { I as IndexedDBTokenStorage, d as detectEnvironment, e as environment, w as warnIfProblematicEnvironment } from './chunks/environment-CKVwRAEL.js';
 export { a as CacheService, C as CacheTTL, g as globalCacheService } from './chunks/index-DBLskLuH.js';
 export { b as ApiErrorDetector, A as AuthenticationError, E as ErrorUtils, L as LogoutRequired, N as NetworkError, a as PersApiError, P as ProviderTokenRefreshNeeded, T as TokenRefreshNeeded } from './chunks/index-CKm_V5XE.js';
 export { b as buildPaginationParams, e as extractData, a as extractPagination, f as fetchAllPages, i as isPaginatedResponse, n as normalizeToPaginated } from './chunks/pagination-utils-9vQ-Npkr.js';
 export { B as BusinessApi, a as BusinessMembershipApi, c as BusinessMembershipService, b as BusinessService } from './chunks/business-membership-service-D6vaVQTR.js';
-export { C as ClientTransactionType, T as TransactionApi, a as TransactionService, d as buildBurnRequest, c as buildMintRequest, h as buildPOSBurnRequest, g as buildPOSTransferRequest, b as buildPendingTransactionData, i as buildSubmissionRequest, f as buildTransferRequest, e as extractDeadlineFromSigningData } from './chunks/transaction-request.builder-C1vVVFto.js';
-export { AnalyticsApi, AnalyticsService } from './analytics.js';
+export { C as ClientTransactionType, T as TransactionApi, a as TransactionService, d as buildBurnRequest, c as buildMintRequest, h as buildPOSBurnRequest, g as buildPOSTransferRequest, b as buildPendingTransactionData, i as buildSubmissionRequest, f as buildTransferRequest, e as extractDeadlineFromSigningData } from './chunks/transaction-request.builder-C8ahJYwi.js';
+export { A as AnalyticsApi, a as AnalyticsService } from './chunks/analytics-service-B9IfG6ox.js';
 export { CampaignApi, CampaignService } from './campaign.js';
 export { DonationApi, DonationService } from './donation.js';
 export { P as PaymentApi, a as PaymentService } from './chunks/payment-service-IvM6rryM.js';
-export { R as RedemptionApi, a as RedemptionService } from './chunks/redemption-service-D-hBqh42.js';
+export { R as RedemptionApi, a as RedemptionService } from './chunks/redemption-service-CQtTLdic.js';
 export { T as TenantApi, a as TenantService } from './chunks/tenant-service-CsRA3O2V.js';
 export { B as BaseTokenService, T as TokenSDK, g as getMetadataFromTokenUnitResponse } from './chunks/base-token-service-U3YzHxfd.js';
 export { T as TokenApi, a as TokenService } from './chunks/token-service-Bfj6C0yz.js';

package/dist/managers/analytics-manager.d.ts

@@ -1,6 +1,6 @@
 import { PersApiClient } from '../core/pers-api-client';
 import { AnalyticsService } from '../analytics';
-import type { TransactionAnalyticsRequestDTO } from '../analytics/models';
+import type { TransactionAnalyticsRequestDTO, CampaignClaimAnalyticsRequestDTO, UserAnalyticsRequestDTO, UserRankingAnalyticsRequestDTO, BusinessRankingAnalyticsRequestDTO, RetentionAnalyticsRequestDTO } from '../analytics/models';
 /**
  * Analytics Manager - Clean, high-level interface for analytics operations
  *
@@ -243,7 +243,170 @@ export declare class AnalyticsManager {
      * updateDashboard();
      * ```
      */
-    getTransactionAnalytics(request: TransactionAnalyticsRequestDTO): Promise<import("node_modules/@explorins/pers-shared/dist/cjs/shared-lib/dto/transaction/transaction-analytics.request.dto").TransactionAnalyticsResponseDTO>;
+    getTransactionAnalytics(request: TransactionAnalyticsRequestDTO): Promise<import("node_modules/@explorins/pers-shared/dist/cjs/shared-lib/dto/analytics/transaction-analytics.request.dto").TransactionAnalyticsResponseDTO>;
+    /**
+     * Get campaign claim analytics with aggregation
+     *
+     * Retrieves aggregated analytics for campaign claims with flexible grouping,
+     * filtering, and metric selection. Provides insights into campaign performance,
+     * claim patterns, and user engagement across the loyalty ecosystem.
+     *
+     * @param request - Analytics request with filters, groupBy, and metrics
+     * @returns Promise resolving to campaign claim analytics data
+     *
+     * @example Claims per campaign
+     * ```typescript
+     * const analytics = await sdk.analytics.getCampaignClaimAnalytics({
+     *   filters: { status: 'COMPLETED' },
+     *   groupBy: ['campaignId'],
+     *   metrics: ['count'],
+     *   sortBy: 'count',
+     *   sortOrder: 'DESC',
+     *   limit: 10
+     * });
+     *
+     * console.log('Top campaigns:', analytics.results);
+     * ```
+     */
+    getCampaignClaimAnalytics(request: CampaignClaimAnalyticsRequestDTO): Promise<import("node_modules/@explorins/pers-shared/dist/cjs/shared-lib/dto/analytics/campaign-claim-analytics-request.dto").CampaignClaimAnalyticsResponseDTO>;
+    /**
+     * 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)}`);
+     * ```
+     */
+    getUserAnalytics(request?: UserAnalyticsRequestDTO): Promise<import("node_modules/@explorins/pers-shared/dist/cjs/shared-lib/dto/analytics/user-analytics.dto").UserAnalyticsResponseDTO>;
+    /**
+     * 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`);
+     * });
+     * ```
+     */
+    getUserRanking(request?: UserRankingAnalyticsRequestDTO): Promise<import("node_modules/@explorins/pers-shared/dist/cjs/shared-lib/dto/analytics/user-ranking-analytics.dto").UserRankingAnalyticsResponseDTO>;
+    /**
+     * 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
+     */
+    getBusinessRanking(request?: BusinessRankingAnalyticsRequestDTO): Promise<import("node_modules/@explorins/pers-shared/dist/cjs/shared-lib/dto/analytics/business-ranking-analytics.dto").BusinessRankingAnalyticsResponseDTO>;
+    /**
+     * 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
+     */
+    getRetentionAnalytics(request?: RetentionAnalyticsRequestDTO): Promise<import("node_modules/@explorins/pers-shared/dist/cjs/shared-lib/dto/analytics/retention-analytics.dto").RetentionAnalyticsResponseDTO>;
     /**
      * Get the full analytics service for advanced operations
      *

package/dist/managers/analytics-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analytics-manager.d.ts","sourceRoot":"","sources":["../../src/managers/analytics-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAgB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,qBAAa,gBAAgB;IAGf,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,gBAAgB,CAAmB;gBAEvB,SAAS,EAAE,aAAa;IAK5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmLG;IACG,uBAAuB,CAAC,OAAO,EAAE,8BAA8B;IAIrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0DG;IACH,mBAAmB,IAAI,gBAAgB;CAGxC"}
+{"version":3,"file":"analytics-manager.d.ts","sourceRoot":"","sources":["../../src/managers/analytics-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAgB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,KAAK,EACV,8BAA8B,EAC9B,gCAAgC,EAChC,uBAAuB,EACvB,8BAA8B,EAC9B,kCAAkC,EAClC,4BAA4B,EAC7B,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,qBAAa,gBAAgB;IAGf,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,gBAAgB,CAAmB;gBAEvB,SAAS,EAAE,aAAa;IAK5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmLG;IACG,uBAAuB,CAAC,OAAO,EAAE,8BAA8B;IAIrE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,yBAAyB,CAAC,OAAO,EAAE,gCAAgC;IAIzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoEG;IACG,gBAAgB,CAAC,OAAO,GAAE,uBAA4B;IAI5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACG,cAAc,CAAC,OAAO,GAAE,8BAAmC;IAIjE;;;;;;;OAOG;IACG,kBAAkB,CAAC,OAAO,GAAE,kCAAuC;IAIzE;;;;;;;OAOG;IACG,qBAAqB,CAAC,OAAO,GAAE,4BAAiC;IAItE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0DG;IACH,mBAAmB,IAAI,gBAAgB;CAGxC"}

package/dist/managers/campaign-manager.d.ts

@@ -1,9 +1,9 @@
-import { PaginatedResponseDTO, SortOrder } from '@explorins/pers-shared';
+import { PaginatedResponseDTO, SortOrder, CampaignClaimIncludeRelation, CampaignIncludeRelation } from '@explorins/pers-shared';
 import { PersApiClient } from '../core/pers-api-client';
 import { PersEventEmitter } from '../core/events';
 import { CampaignService } from '../campaign';
 import { PaginationOptions } from '../shared/utils/pagination-utils';
-import type { CampaignDTO, CampaignCreateRequestDTO, CampaignClaimRequestDTO, CampaignClaimDTO, TokenUnitCreateRequestDTO, CampaignBusinessEngagementCreateRequestDTO, CampaignTriggerDTO } from '../shared/interfaces/pers-shared-lib.interfaces';
+import type { CampaignDTO, CampaignCreateRequestDTO, CampaignClaimRequestDTO, CampaignClaimDTO, TokenUnitCreateRequestDTO, CampaignBusinessEngagementCreateRequestDTO, CampaignTriggerDTO, CampaignTriggerCreateRequestDTO } from '../shared/interfaces/pers-shared-lib.interfaces';
 /**
  * Campaign Manager - Clean, high-level interface for campaign operations
  *
@@ -82,6 +82,7 @@ export declare 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
      *
@@ -110,8 +111,16 @@ export declare 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);
+     * ```
      */
-    getCampaignById(campaignId: string): Promise<CampaignDTO>;
+    getCampaignById(campaignId: string, include?: CampaignIncludeRelation[]): Promise<CampaignDTO>;
     /**
      * Claim a campaign reward
      *
@@ -244,6 +253,11 @@ export declare class CampaignManager {
      *   page: 1,
      *   limit: 25
      * });
+     *
+     * // Include related data (trigger sources and businesses)
+     * const campaignsWithRelations = await sdk.campaigns.getCampaigns({
+     *   include: ['triggerSources', 'businesses']
+     * });
      * ```
      */
     getCampaigns(options?: {
@@ -253,6 +267,7 @@ export declare class CampaignManager {
         limit?: number;
         sortBy?: 'name' | 'createdAt' | 'startDate';
         sortOrder?: SortOrder;
+        include?: CampaignIncludeRelation[];
     }): Promise<PaginatedResponseDTO<CampaignDTO>>;
     /**
      * Admin: Create new campaign
@@ -359,52 +374,131 @@ export declare class CampaignManager {
      */
     toggleCampaignTestnet(campaignId: string): Promise<CampaignDTO>;
     /**
-     * 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`);
      * });
      * ```
      */
     getCampaignTriggers(options?: PaginationOptions): Promise<PaginatedResponseDTO<CampaignTriggerDTO>>;
     /**
-     * Admin: Set campaign trigger
+     * 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);
+     * ```
+     */
+    getCampaignTriggerById(triggerId: string): Promise<CampaignTriggerDTO>;
+    /**
+     * 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
      *
-     * Associates a specific trigger mechanism with a campaign, enabling automatic
-     * campaign activation based on defined conditions. Requires administrator privileges.
+     * @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);
+     * ```
+     */
+    createCampaignTrigger(data: CampaignTriggerCreateRequestDTO): Promise<CampaignTriggerDTO>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    updateCampaignTrigger(triggerId: string, data: Partial<CampaignTriggerCreateRequestDTO>): Promise<CampaignTriggerDTO>;
+    /**
+     * 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');
+     * ```
+     */
+    deleteCampaignTrigger(triggerId: string): Promise<boolean>;
+    /**
+     * Admin: Assign a trigger to a campaign
+     *
+     * Associates a trigger rule with a campaign. A campaign can have only one trigger
+     * at a time. Assigning a new trigger replaces any existing trigger.
      *
      * @param campaignId - ID of the campaign
      * @param triggerId - ID of the trigger to associate
-     * @returns Promise resolving to updated campaign data
-     * @throws {PersApiError} When not authenticated as admin or entities not found
+     * @returns Promise resolving to updated campaign
      *
      * @example
      * ```typescript
-     * // Admin operation - set up automatic campaign trigger
      * const updated = await sdk.campaigns.setCampaignTrigger(
-     *   'new-user-welcome',
-     *   'user-registration-trigger'
+     *   'campaign-123',
+     *   'trigger-456'
      * );
-     *
-     * console.log('Trigger set for campaign:', updated.title);
-     * console.log('Trigger will activate on user registration');
+     * console.log('Trigger assigned:', updated.trigger?.name);
      * ```
      */
     setCampaignTrigger(campaignId: string, triggerId: string): Promise<CampaignDTO>;
+    /**
+     * 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);
+     * ```
+     */
+    removeCampaignTrigger(campaignId: string, triggerId: string): Promise<CampaignDTO>;
     /**
      * Admin: Create campaign token unit
      *
@@ -611,7 +705,7 @@ export declare class CampaignManager {
         limit?: number;
         sortBy?: string;
         sortOrder?: any;
-    }): Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
+    }, include?: CampaignClaimIncludeRelation[]): Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
     /**
      * Admin: Get campaign claims by user ID
      *
@@ -645,7 +739,7 @@ export declare class CampaignManager {
      * console.log(`\nTotal rewards earned: ${totalRewards}`);
      * ```
      */
-    getCampaignClaimsByUserId(userId: string, options?: PaginationOptions): Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
+    getCampaignClaimsByUserId(userId: string, options?: PaginationOptions, include?: CampaignClaimIncludeRelation[]): Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
     /**
      * Admin: Get campaign claims by business ID
      *
@@ -684,7 +778,63 @@ export declare class CampaignManager {
      * console.log(`\nTotal rewards distributed: ${totalRewardsDistributed}`);
      * ```
      */
-    getCampaignClaimsByBusinessId(businessId: string, options?: PaginationOptions): Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
+    getCampaignClaimsByBusinessId(businessId: string, options?: PaginationOptions, include?: CampaignClaimIncludeRelation[]): Promise<PaginatedResponseDTO<CampaignClaimDTO>>;
+    /**
+     * 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);
+     * ```
+     */
+    assignTriggerSource(campaignId: string, triggerSourceId: string): Promise<CampaignDTO>;
+    /**
+     * 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);
+     * ```
+     */
+    removeTriggerSource(campaignId: string, triggerSourceId: string): Promise<CampaignDTO>;
     /**
      * Get the full campaign service for advanced operations
      *