PERS SDK - v2.3.26 / Exports / AnalyticsApi
Platform-Agnostic Analytics API Client
Handles analytics operations using the PERS backend. Uses @explorins/pers-shared DTOs for consistency with backend.
- getTransactionAnalytics
- getCampaignClaimAnalytics
- getRedemptionRedeemAnalytics
- getUserAnalytics
- getUserRanking
- getBusinessRanking
- getRetentionAnalytics
- getTagAnalytics
• new AnalyticsApi(apiClient): AnalyticsApi
| Name | Type |
|---|---|
apiClient | PersApiClient |
analytics/api/analytics-api.ts:29
▸ getTransactionAnalytics(request): Promise<TransactionAnalyticsResponseDTO>
ADMIN: Get transaction analytics with filtering and aggregation
| Name | Type |
|---|---|
request | TransactionAnalyticsRequestDTO |
Promise<TransactionAnalyticsResponseDTO>
analytics/api/analytics-api.ts:38
▸ getCampaignClaimAnalytics(request): Promise<CampaignClaimAnalyticsResponseDTO>
ADMIN: Get campaign claim analytics with aggregation (charts, metrics, grouping)
This endpoint is for aggregated analytics only (groupBy/metrics). For enriched list data with nested objects, use campaign.getClaims() instead.
| Name | Type |
|---|---|
request | CampaignClaimAnalyticsRequestDTO |
Promise<CampaignClaimAnalyticsResponseDTO>
Example
const response = await analyticsApi.getCampaignClaimAnalytics({
filters: { status: 'COMPLETED' },
groupBy: ['campaignId'],
metrics: ['count'],
sortBy: 'count',
sortOrder: SortOrder.DESC,
limit: 10
});Example
const response = await analyticsApi.getCampaignClaimAnalytics({
groupBy: ['month', 'status'],
metrics: ['count'],
sortBy: 'month',
sortOrder: SortOrder.DESC,
startDate: new Date('2026-01-01'),
endDate: new Date('2026-12-31')
});analytics/api/analytics-api.ts:72
▸ getRedemptionRedeemAnalytics(request): Promise<RedemptionRedeemAnalyticsResponseDTO>
ADMIN: Get redemption redeem analytics with aggregation (charts, metrics, grouping)
This endpoint is for aggregated analytics only (groupBy/metrics). For enriched list data with nested objects, use redemption.getRedeems() instead.
| Name | Type |
|---|---|
request | RedemptionRedeemAnalyticsRequestDTO |
Promise<RedemptionRedeemAnalyticsResponseDTO>
Example
const response = await analyticsApi.getRedemptionRedeemAnalytics({
groupBy: ['redemptionId'],
metrics: ['count'],
sortBy: 'count',
sortOrder: SortOrder.DESC,
limit: 10
});Example
const response = await analyticsApi.getRedemptionRedeemAnalytics({
groupBy: ['month', 'status'],
metrics: ['count'],
sortBy: 'month',
sortOrder: SortOrder.DESC,
startDate: new Date('2026-01-01'),
endDate: new Date('2026-12-31')
});Example
const response = await analyticsApi.getRedemptionRedeemAnalytics({
filters: { status: 'COMPLETED' },
groupBy: ['businessId'],
metrics: ['count'],
sortBy: 'count',
sortOrder: SortOrder.DESC
});analytics/api/analytics-api.ts:116
▸ getUserAnalytics(request?): Promise<UserAnalyticsResponseDTO>
ADMIN: Get user analytics with engagement metrics
Returns aggregated user statistics including engagement rate, active users, transaction metrics, and per-active-user averages (more accurate than all-user averages).
Request structure matches TransactionAnalytics and CampaignClaimAnalytics for consistency:
- filters object for business-specific scoping
- startDate/endDate at root level for date range filtering
| Name | Type | Description |
|---|---|---|
request | UserAnalyticsRequestDTO | Analytics request with optional filters and date range |
Promise<UserAnalyticsResponseDTO>
Aggregated user metrics with per-user and per-active-user averages
Example
const analytics = await analyticsApi.getUserAnalytics({});
console.log(`Total users: ${analytics.totalUsers}`);
console.log(`Active users: ${analytics.activeUsers}`);
console.log(`Engagement rate: ${analytics.engagementRate}%`);
// Per-user averages (includes inactive users)
console.log(`Avg transactions per user: ${analytics.averageTransactionsPerUser}`);
// Per-active-user averages (only engaged users - more useful!)
console.log(`Avg transactions per active user: ${analytics.averageTransactionsPerActiveUser}`);Example
const analytics = await analyticsApi.getUserAnalytics({
startDate: new Date('2026-01-01'),
endDate: new Date('2026-01-31')
});
console.log(`January metrics:`);
console.log(`Active users: ${analytics.activeUsers}`);
console.log(`New users: ${analytics.newUsers}`);
console.log(`Date range applied: ${analytics.metadata.dateRange?.startDate} - ${analytics.metadata.dateRange?.endDate}`);Example
const analytics = await analyticsApi.getUserAnalytics({
filters: { businessId: 'biz-123' },
startDate: new Date('2026-01-01'),
endDate: new Date('2026-12-31')
});
console.log(`Business customer engagement in 2026:`);
console.log(`Active customers: ${analytics.activeUsers}`);
console.log(`Avg claims per active customer: ${analytics.averageClaimsPerActiveUser.toFixed(2)}`);
console.log(`Customer engagement rate: ${analytics.engagementRate.toFixed(1)}%`);analytics/api/analytics-api.ts:172
▸ getUserRanking(request?): Promise<UserRankingAnalyticsResponseDTO>
ADMIN: Get user transaction ranking with enriched user data
Returns ranked list of users with full user details and transaction metrics. Data enrichment happens via efficient SQL JOINs + UNION (handles legacy transactions).
Use Cases:
- Admin leaderboards showing top users by activity
- User engagement analysis with full user context
- Identifying power users for campaigns
| Name | Type | Description |
|---|---|---|
request | UserRankingAnalyticsRequestDTO | Ranking request with filters, sorting, and limit |
Promise<UserRankingAnalyticsResponseDTO>
Ranked list with user details (email, externalUserId) and transaction metrics
Example
const ranking = await analyticsApi.getUserRanking({
sortBy: 'totalTransactions',
sortOrder: SortOrder.DESC,
limit: 50
});
ranking.results.forEach((user, index) => {
console.log(`#${index + 1}: ${user.email || user.externalUserId} - ${user.totalTransactions} transactions`);
});Example
const ranking = await analyticsApi.getUserRanking({
filters: { tokenType: 'STAMP' },
sortBy: 'tokenSpent',
sortOrder: SortOrder.DESC,
limit: 20
});Example
const ranking = await analyticsApi.getUserRanking({
filters: {
businessId: 'business-uuid-here',
tokenType: 'CREDIT'
},
sortBy: 'totalTransactions',
sortOrder: SortOrder.DESC,
limit: 100,
startDate: new Date('2026-01-01'),
endDate: new Date('2026-12-31')
});
console.log(`Top ${ranking.totalUsers} users for business in 2026`);analytics/api/analytics-api.ts:229
▸ getBusinessRanking(request?): Promise<BusinessRankingAnalyticsResponseDTO>
ADMIN: Get business transaction ranking with enriched business data
Returns ranked list of businesses with full business details and transaction metrics. Data enrichment happens via efficient SQL JOINs + UNION (handles legacy transactions).
| Name | Type | Description |
|---|---|---|
request | BusinessRankingAnalyticsRequestDTO | Ranking request with filters, sorting, and limit |
Promise<BusinessRankingAnalyticsResponseDTO>
Ranked list with business details and transaction metrics
Example
const ranking = await analyticsApi.getBusinessRanking({
sortBy: 'totalTransactions',
sortOrder: SortOrder.DESC,
limit: 50
});analytics/api/analytics-api.ts:251
▸ getRetentionAnalytics(request?): Promise<RetentionAnalyticsResponseDTO>
ADMIN: Get monthly user retention analytics
Returns monthly retention data with active/new/returning users and retention rates. Replaces 13 separate API calls with 1 efficient recursive CTE query.
| Name | Type | Description |
|---|---|---|
request | RetentionAnalyticsRequestDTO | Retention analytics request with monthsBack and filters |
Promise<RetentionAnalyticsResponseDTO>
Monthly retention data with user metrics and retention rates
Example
const retention = await analyticsApi.getRetentionAnalytics({
monthsBack: 13
});analytics/api/analytics-api.ts:271
▸ getTagAnalytics(request?): Promise<TagAnalyticsResponseDTO>
ADMIN: Get tag usage analytics across entities
Aggregates tag usage across all taggable entities (campaigns, redemptions, businesses, token metadata, user status types). Perfect for:
- Tag autocomplete/suggestions
- Tag management dashboards
- Usage analytics
| Name | Type | Description |
|---|---|---|
request | TagAnalyticsRequestDTO | Optional filters for entity types |
Promise<TagAnalyticsResponseDTO>
Aggregated tag usage with per-entity-type breakdown
Example
const allTags = await analyticsApi.getTagAnalytics();
console.log(`${allTags.totalTags} unique tags, ${allTags.totalUsage} total usages`);
// Use for autocomplete suggestions
const suggestions = allTags.tags.map(t => t.tag);Example
const filteredTags = await analyticsApi.getTagAnalytics({
entityTypes: [TaggableEntityType.CAMPAIGN, TaggableEntityType.BUSINESS]
});Example
const analytics = await analyticsApi.getTagAnalytics();
analytics.tags.forEach(({ tag, count, usageByEntityType }) => {
console.log(`${tag}: ${count} total`);
usageByEntityType.forEach(({ entityType, count }) => {
console.log(` - ${entityType}: ${count}`);
});
});