@explorins/pers-sdk 2.1.2 → 2.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/analytics/api/analytics-api.d.ts +175 -1
- package/dist/analytics/api/analytics-api.d.ts.map +1 -1
- package/dist/analytics/models/index.d.ts +2 -5
- package/dist/analytics/models/index.d.ts.map +1 -1
- package/dist/analytics/services/analytics-service.d.ts +32 -1
- package/dist/analytics/services/analytics-service.d.ts.map +1 -1
- package/dist/analytics.cjs +9 -44
- package/dist/analytics.cjs.map +1 -1
- package/dist/analytics.js +2 -45
- package/dist/analytics.js.map +1 -1
- package/dist/campaign/api/campaign-api.d.ts +59 -4
- package/dist/campaign/api/campaign-api.d.ts.map +1 -1
- package/dist/campaign/services/campaign-service.d.ts +49 -7
- package/dist/campaign/services/campaign-service.d.ts.map +1 -1
- package/dist/campaign.cjs +150 -14
- package/dist/campaign.cjs.map +1 -1
- package/dist/campaign.js +150 -14
- package/dist/campaign.js.map +1 -1
- package/dist/chunks/analytics-service-B9IfG6ox.js +271 -0
- package/dist/chunks/analytics-service-B9IfG6ox.js.map +1 -0
- package/dist/chunks/analytics-service-DwkeBB08.cjs +274 -0
- package/dist/chunks/analytics-service-DwkeBB08.cjs.map +1 -0
- package/dist/chunks/{pers-sdk-DnLw822h.js → pers-sdk-CAM0iQyK.js} +1203 -267
- package/dist/chunks/pers-sdk-CAM0iQyK.js.map +1 -0
- package/dist/chunks/{pers-sdk-D5lE9ZFW.cjs → pers-sdk-Di_R6AiT.cjs} +1207 -268
- package/dist/chunks/pers-sdk-Di_R6AiT.cjs.map +1 -0
- package/dist/chunks/{redemption-service-D-hBqh42.js → redemption-service-CQtTLdic.js} +32 -10
- package/dist/chunks/redemption-service-CQtTLdic.js.map +1 -0
- package/dist/chunks/{redemption-service-rMB6T2W5.cjs → redemption-service-DsH7sRdv.cjs} +32 -10
- package/dist/chunks/redemption-service-DsH7sRdv.cjs.map +1 -0
- package/dist/chunks/{transaction-request.builder-C1vVVFto.js → transaction-request.builder-C8ahJYwi.js} +122 -70
- package/dist/chunks/transaction-request.builder-C8ahJYwi.js.map +1 -0
- package/dist/chunks/{transaction-request.builder-BpgtuMMq.cjs → transaction-request.builder-CkYd5bl6.cjs} +122 -70
- package/dist/chunks/transaction-request.builder-CkYd5bl6.cjs.map +1 -0
- package/dist/core/auth/auth-provider.interface.d.ts +1 -0
- package/dist/core/auth/auth-provider.interface.d.ts.map +1 -1
- package/dist/core/auth/default-auth-provider.d.ts +2 -0
- package/dist/core/auth/default-auth-provider.d.ts.map +1 -1
- package/dist/core/auth/refresh-manager.d.ts +2 -0
- package/dist/core/auth/refresh-manager.d.ts.map +1 -1
- package/dist/core/auth/services/auth-service.d.ts.map +1 -1
- package/dist/core/auth/token-storage.d.ts +2 -1
- package/dist/core/auth/token-storage.d.ts.map +1 -1
- package/dist/core/pers-api-client.d.ts.map +1 -1
- package/dist/core/pers-config.d.ts +0 -18
- package/dist/core/pers-config.d.ts.map +1 -1
- package/dist/core.cjs +5 -4
- package/dist/core.cjs.map +1 -1
- package/dist/core.js +4 -4
- package/dist/index.cjs +13 -6
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -5
- package/dist/managers/analytics-manager.d.ts +165 -2
- package/dist/managers/analytics-manager.d.ts.map +1 -1
- package/dist/managers/campaign-manager.d.ts +180 -30
- package/dist/managers/campaign-manager.d.ts.map +1 -1
- package/dist/managers/index.d.ts +1 -0
- package/dist/managers/index.d.ts.map +1 -1
- package/dist/managers/redemption-manager.d.ts +52 -2
- package/dist/managers/redemption-manager.d.ts.map +1 -1
- package/dist/managers/transaction-manager.d.ts +66 -131
- package/dist/managers/transaction-manager.d.ts.map +1 -1
- package/dist/managers/trigger-source-manager.d.ts +194 -0
- package/dist/managers/trigger-source-manager.d.ts.map +1 -0
- package/dist/managers/user-manager.d.ts +38 -7
- package/dist/managers/user-manager.d.ts.map +1 -1
- package/dist/node.cjs +4 -4
- package/dist/node.js +4 -4
- package/dist/package.json +2 -2
- package/dist/pers-sdk.d.ts +68 -23
- package/dist/pers-sdk.d.ts.map +1 -1
- package/dist/redemption/api/redemption-api.d.ts +8 -4
- package/dist/redemption/api/redemption-api.d.ts.map +1 -1
- package/dist/redemption/services/redemption-service.d.ts +7 -3
- package/dist/redemption/services/redemption-service.d.ts.map +1 -1
- package/dist/redemption.cjs +1 -1
- package/dist/redemption.js +1 -1
- package/dist/transaction/api/transaction-api.d.ts +37 -42
- package/dist/transaction/api/transaction-api.d.ts.map +1 -1
- package/dist/transaction/models/index.d.ts +21 -0
- package/dist/transaction/models/index.d.ts.map +1 -1
- package/dist/transaction/services/transaction-service.d.ts +10 -15
- package/dist/transaction/services/transaction-service.d.ts.map +1 -1
- package/dist/transaction.cjs +1 -1
- package/dist/transaction.js +1 -1
- package/dist/trigger-source/api/trigger-source-api.d.ts +86 -0
- package/dist/trigger-source/api/trigger-source-api.d.ts.map +1 -0
- package/dist/trigger-source/index.d.ts +9 -0
- package/dist/trigger-source/index.d.ts.map +1 -0
- package/dist/trigger-source/services/trigger-source-service.d.ts +42 -0
- package/dist/trigger-source/services/trigger-source-service.d.ts.map +1 -0
- package/dist/user/api/user-api.d.ts +26 -1
- package/dist/user/api/user-api.d.ts.map +1 -1
- package/dist/user/services/user-service.d.ts +3 -1
- package/dist/user/services/user-service.d.ts.map +1 -1
- package/dist/user.cjs +34 -4
- package/dist/user.cjs.map +1 -1
- package/dist/user.js +34 -4
- package/dist/user.js.map +1 -1
- package/package.json +2 -2
- package/dist/chunks/pers-sdk-D5lE9ZFW.cjs.map +0 -1
- package/dist/chunks/pers-sdk-DnLw822h.js.map +0 -1
- package/dist/chunks/redemption-service-D-hBqh42.js.map +0 -1
- package/dist/chunks/redemption-service-rMB6T2W5.cjs.map +0 -1
- package/dist/chunks/transaction-request.builder-BpgtuMMq.cjs.map +0 -1
- package/dist/chunks/transaction-request.builder-C1vVVFto.js.map +0 -1
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Platform-Agnostic Analytics API Client
|
|
3
|
+
*
|
|
4
|
+
* Handles analytics operations using the PERS backend.
|
|
5
|
+
* Uses @explorins/pers-shared DTOs for consistency with backend.
|
|
6
|
+
*/
|
|
7
|
+
class AnalyticsApi {
|
|
8
|
+
constructor(apiClient) {
|
|
9
|
+
this.apiClient = apiClient;
|
|
10
|
+
}
|
|
11
|
+
// ==========================================
|
|
12
|
+
// ADMIN OPERATIONS
|
|
13
|
+
// ==========================================
|
|
14
|
+
/**
|
|
15
|
+
* ADMIN: Get transaction analytics with filtering and aggregation
|
|
16
|
+
*/
|
|
17
|
+
async getTransactionAnalytics(request) {
|
|
18
|
+
return this.apiClient.post('/analytics/transactions', request);
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* ADMIN: Get campaign claim analytics with aggregation (charts, metrics, grouping)
|
|
22
|
+
*
|
|
23
|
+
* This endpoint is for aggregated analytics only (groupBy/metrics).
|
|
24
|
+
* For enriched list data with nested objects, use campaign.getClaims() instead.
|
|
25
|
+
*
|
|
26
|
+
* @example Claims per campaign
|
|
27
|
+
* ```typescript
|
|
28
|
+
* const response = await analyticsApi.getCampaignClaimAnalytics({
|
|
29
|
+
* filters: { status: 'COMPLETED' },
|
|
30
|
+
* groupBy: ['campaignId'],
|
|
31
|
+
* metrics: ['count'],
|
|
32
|
+
* sortBy: 'count',
|
|
33
|
+
* sortOrder: SortOrder.DESC,
|
|
34
|
+
* limit: 10
|
|
35
|
+
* });
|
|
36
|
+
* ```
|
|
37
|
+
*
|
|
38
|
+
* @example Claims over time by status
|
|
39
|
+
* ```typescript
|
|
40
|
+
* const response = await analyticsApi.getCampaignClaimAnalytics({
|
|
41
|
+
* groupBy: ['month', 'status'],
|
|
42
|
+
* metrics: ['count'],
|
|
43
|
+
* sortBy: 'month',
|
|
44
|
+
* sortOrder: SortOrder.DESC,
|
|
45
|
+
* startDate: new Date('2026-01-01'),
|
|
46
|
+
* endDate: new Date('2026-12-31')
|
|
47
|
+
* });
|
|
48
|
+
* ```
|
|
49
|
+
*/
|
|
50
|
+
async getCampaignClaimAnalytics(request) {
|
|
51
|
+
return this.apiClient.post('/analytics/campaign-claims', request);
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* ADMIN: Get user analytics with engagement metrics
|
|
55
|
+
*
|
|
56
|
+
* Returns aggregated user statistics including engagement rate, active users,
|
|
57
|
+
* transaction metrics, and per-active-user averages (more accurate than all-user averages).
|
|
58
|
+
*
|
|
59
|
+
* Request structure matches TransactionAnalytics and CampaignClaimAnalytics for consistency:
|
|
60
|
+
* - filters object for business-specific scoping
|
|
61
|
+
* - startDate/endDate at root level for date range filtering
|
|
62
|
+
*
|
|
63
|
+
* @param request - Analytics request with optional filters and date range
|
|
64
|
+
* @returns Aggregated user metrics with per-user and per-active-user averages
|
|
65
|
+
*
|
|
66
|
+
* @example Basic user analytics (all time, all businesses)
|
|
67
|
+
* ```typescript
|
|
68
|
+
* const analytics = await analyticsApi.getUserAnalytics({});
|
|
69
|
+
* console.log(`Total users: ${analytics.totalUsers}`);
|
|
70
|
+
* console.log(`Active users: ${analytics.activeUsers}`);
|
|
71
|
+
* console.log(`Engagement rate: ${analytics.engagementRate}%`);
|
|
72
|
+
*
|
|
73
|
+
* // Per-user averages (includes inactive users)
|
|
74
|
+
* console.log(`Avg transactions per user: ${analytics.averageTransactionsPerUser}`);
|
|
75
|
+
*
|
|
76
|
+
* // Per-active-user averages (only engaged users - more useful!)
|
|
77
|
+
* console.log(`Avg transactions per active user: ${analytics.averageTransactionsPerActiveUser}`);
|
|
78
|
+
* ```
|
|
79
|
+
*
|
|
80
|
+
* @example Filtered by date range
|
|
81
|
+
* ```typescript
|
|
82
|
+
* const analytics = await analyticsApi.getUserAnalytics({
|
|
83
|
+
* startDate: new Date('2026-01-01'),
|
|
84
|
+
* endDate: new Date('2026-01-31')
|
|
85
|
+
* });
|
|
86
|
+
* console.log(`January metrics:`);
|
|
87
|
+
* console.log(`Active users: ${analytics.activeUsers}`);
|
|
88
|
+
* console.log(`New users: ${analytics.newUsers}`);
|
|
89
|
+
* console.log(`Date range applied: ${analytics.metadata.dateRange?.startDate} - ${analytics.metadata.dateRange?.endDate}`);
|
|
90
|
+
* ```
|
|
91
|
+
*
|
|
92
|
+
* @example Business-specific analytics with filters
|
|
93
|
+
* ```typescript
|
|
94
|
+
* const analytics = await analyticsApi.getUserAnalytics({
|
|
95
|
+
* filters: { businessId: 'biz-123' },
|
|
96
|
+
* startDate: new Date('2026-01-01'),
|
|
97
|
+
* endDate: new Date('2026-12-31')
|
|
98
|
+
* });
|
|
99
|
+
* console.log(`Business customer engagement in 2026:`);
|
|
100
|
+
* console.log(`Active customers: ${analytics.activeUsers}`);
|
|
101
|
+
* console.log(`Avg claims per active customer: ${analytics.averageClaimsPerActiveUser.toFixed(2)}`);
|
|
102
|
+
* console.log(`Customer engagement rate: ${analytics.engagementRate.toFixed(1)}%`);
|
|
103
|
+
* ```
|
|
104
|
+
*/
|
|
105
|
+
async getUserAnalytics(request = {}) {
|
|
106
|
+
return this.apiClient.post('/analytics/users', request);
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* ADMIN: Get user transaction ranking with enriched user data
|
|
110
|
+
*
|
|
111
|
+
* Returns ranked list of users with full user details and transaction metrics.
|
|
112
|
+
* Data enrichment happens via efficient SQL JOINs + UNION (handles legacy transactions).
|
|
113
|
+
*
|
|
114
|
+
* Use Cases:
|
|
115
|
+
* - Admin leaderboards showing top users by activity
|
|
116
|
+
* - User engagement analysis with full user context
|
|
117
|
+
* - Identifying power users for campaigns
|
|
118
|
+
*
|
|
119
|
+
* @param request - Ranking request with filters, sorting, and limit
|
|
120
|
+
* @returns Ranked list with user details (email, externalUserId) and transaction metrics
|
|
121
|
+
*
|
|
122
|
+
* @example Top 50 users by transaction count
|
|
123
|
+
* ```typescript
|
|
124
|
+
* const ranking = await analyticsApi.getUserRanking({
|
|
125
|
+
* sortBy: 'totalTransactions',
|
|
126
|
+
* sortOrder: SortOrder.DESC,
|
|
127
|
+
* limit: 50
|
|
128
|
+
* });
|
|
129
|
+
*
|
|
130
|
+
* ranking.results.forEach((user, index) => {
|
|
131
|
+
* console.log(`#${index + 1}: ${user.email || user.externalUserId} - ${user.totalTransactions} transactions`);
|
|
132
|
+
* });
|
|
133
|
+
* ```
|
|
134
|
+
*
|
|
135
|
+
* @example Top users by STAMP spending
|
|
136
|
+
* ```typescript
|
|
137
|
+
* const ranking = await analyticsApi.getUserRanking({
|
|
138
|
+
* filters: { tokenType: 'STAMP' },
|
|
139
|
+
* sortBy: 'tokenSpent',
|
|
140
|
+
* sortOrder: SortOrder.DESC,
|
|
141
|
+
* limit: 20
|
|
142
|
+
* });
|
|
143
|
+
* ```
|
|
144
|
+
*
|
|
145
|
+
* @example Business-specific leaderboard with date range
|
|
146
|
+
* ```typescript
|
|
147
|
+
* const ranking = await analyticsApi.getUserRanking({
|
|
148
|
+
* filters: {
|
|
149
|
+
* businessId: 'business-uuid-here',
|
|
150
|
+
* tokenType: 'CREDIT'
|
|
151
|
+
* },
|
|
152
|
+
* sortBy: 'totalTransactions',
|
|
153
|
+
* sortOrder: SortOrder.DESC,
|
|
154
|
+
* limit: 100,
|
|
155
|
+
* startDate: new Date('2026-01-01'),
|
|
156
|
+
* endDate: new Date('2026-12-31')
|
|
157
|
+
* });
|
|
158
|
+
* console.log(`Top ${ranking.totalUsers} users for business in 2026`);
|
|
159
|
+
* ```
|
|
160
|
+
*/
|
|
161
|
+
async getUserRanking(request = {}) {
|
|
162
|
+
return this.apiClient.post('/analytics/users/ranking', request);
|
|
163
|
+
}
|
|
164
|
+
/**
|
|
165
|
+
* ADMIN: Get business transaction ranking with enriched business data
|
|
166
|
+
*
|
|
167
|
+
* Returns ranked list of businesses with full business details and transaction metrics.
|
|
168
|
+
* Data enrichment happens via efficient SQL JOINs + UNION (handles legacy transactions).
|
|
169
|
+
*
|
|
170
|
+
* @param request - Ranking request with filters, sorting, and limit
|
|
171
|
+
* @returns Ranked list with business details and transaction metrics
|
|
172
|
+
*
|
|
173
|
+
* @example Top 50 businesses by transaction count
|
|
174
|
+
* ```typescript
|
|
175
|
+
* const ranking = await analyticsApi.getBusinessRanking({
|
|
176
|
+
* sortBy: 'totalTransactions',
|
|
177
|
+
* sortOrder: SortOrder.DESC,
|
|
178
|
+
* limit: 50
|
|
179
|
+
* });
|
|
180
|
+
* ```
|
|
181
|
+
*/
|
|
182
|
+
async getBusinessRanking(request = {}) {
|
|
183
|
+
return this.apiClient.post('/analytics/businesses/ranking', request);
|
|
184
|
+
}
|
|
185
|
+
/**
|
|
186
|
+
* ADMIN: Get monthly user retention analytics
|
|
187
|
+
*
|
|
188
|
+
* Returns monthly retention data with active/new/returning users and retention rates.
|
|
189
|
+
* Replaces 13 separate API calls with 1 efficient recursive CTE query.
|
|
190
|
+
*
|
|
191
|
+
* @param request - Retention analytics request with monthsBack and filters
|
|
192
|
+
* @returns Monthly retention data with user metrics and retention rates
|
|
193
|
+
*
|
|
194
|
+
* @example Last 13 months retention
|
|
195
|
+
* ```typescript
|
|
196
|
+
* const retention = await analyticsApi.getRetentionAnalytics({
|
|
197
|
+
* monthsBack: 13
|
|
198
|
+
* });
|
|
199
|
+
* ```
|
|
200
|
+
*/
|
|
201
|
+
async getRetentionAnalytics(request = {}) {
|
|
202
|
+
return this.apiClient.post('/analytics/users/retention', request);
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
/**
|
|
207
|
+
* Platform-Agnostic Analytics Service
|
|
208
|
+
*
|
|
209
|
+
* Contains analytics business logic and operations that work across platforms.
|
|
210
|
+
* No framework dependencies - pure TypeScript business logic.
|
|
211
|
+
*
|
|
212
|
+
* Focuses only on actual backend capabilities.
|
|
213
|
+
*/
|
|
214
|
+
class AnalyticsService {
|
|
215
|
+
constructor(analyticsApi) {
|
|
216
|
+
this.analyticsApi = analyticsApi;
|
|
217
|
+
}
|
|
218
|
+
// ==========================================
|
|
219
|
+
// ADMIN OPERATIONS
|
|
220
|
+
// ==========================================
|
|
221
|
+
/**
|
|
222
|
+
* ADMIN: Get transaction analytics with filtering and aggregation
|
|
223
|
+
*/
|
|
224
|
+
async getTransactionAnalytics(request) {
|
|
225
|
+
return this.analyticsApi.getTransactionAnalytics(request);
|
|
226
|
+
}
|
|
227
|
+
/**
|
|
228
|
+
* ADMIN: Get campaign claim analytics with aggregation
|
|
229
|
+
*/
|
|
230
|
+
async getCampaignClaimAnalytics(request) {
|
|
231
|
+
return this.analyticsApi.getCampaignClaimAnalytics(request);
|
|
232
|
+
}
|
|
233
|
+
/**
|
|
234
|
+
* ADMIN: Get user analytics with engagement metrics
|
|
235
|
+
*
|
|
236
|
+
* Returns aggregated user statistics including engagement rate, active users,
|
|
237
|
+
* transaction metrics, and claims/redemption averages.
|
|
238
|
+
*/
|
|
239
|
+
async getUserAnalytics(request = {}) {
|
|
240
|
+
return this.analyticsApi.getUserAnalytics(request);
|
|
241
|
+
}
|
|
242
|
+
/**
|
|
243
|
+
* ADMIN: Get user transaction ranking with enriched user data
|
|
244
|
+
*
|
|
245
|
+
* Returns ranked list of users with full user details (email, externalUserId)
|
|
246
|
+
* and transaction metrics. Efficient data enrichment via SQL JOINs + UNION.
|
|
247
|
+
*/
|
|
248
|
+
async getUserRanking(request = {}) {
|
|
249
|
+
return this.analyticsApi.getUserRanking(request);
|
|
250
|
+
}
|
|
251
|
+
/**
|
|
252
|
+
* ADMIN: Get business transaction ranking with enriched business data
|
|
253
|
+
*
|
|
254
|
+
* Returns ranked list of businesses with full business details and transaction metrics.
|
|
255
|
+
*/
|
|
256
|
+
async getBusinessRanking(request = {}) {
|
|
257
|
+
return this.analyticsApi.getBusinessRanking(request);
|
|
258
|
+
}
|
|
259
|
+
/**
|
|
260
|
+
* ADMIN: Get monthly user retention analytics
|
|
261
|
+
*
|
|
262
|
+
* Returns monthly retention data with user metrics and retention rates.
|
|
263
|
+
* Replaces 13 separate API calls with 1 efficient query.
|
|
264
|
+
*/
|
|
265
|
+
async getRetentionAnalytics(request = {}) {
|
|
266
|
+
return this.analyticsApi.getRetentionAnalytics(request);
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
export { AnalyticsApi as A, AnalyticsService as a };
|
|
271
|
+
//# sourceMappingURL=analytics-service-B9IfG6ox.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"analytics-service-B9IfG6ox.js","sources":["../../src/analytics/api/analytics-api.ts","../../src/analytics/services/analytics-service.ts"],"sourcesContent":[null,null],"names":[],"mappings":"AAiBA;;;;;AAKG;MACU,YAAY,CAAA;AACvB,IAAA,WAAA,CAAoB,SAAwB,EAAA;QAAxB,IAAA,CAAA,SAAS,GAAT,SAAS;IAAkB;;;;AAM/C;;AAEG;IACH,MAAM,uBAAuB,CAAC,OAAuC,EAAA;QACnE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAkC,yBAAyB,EAAE,OAAO,CAAC;IACjG;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BG;IACH,MAAM,yBAAyB,CAAC,OAAyC,EAAA;QACvE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAoC,4BAA4B,EAAE,OAAO,CAAC;IACtG;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDG;AACH,IAAA,MAAM,gBAAgB,CAAC,OAAA,GAAmC,EAAE,EAAA;QAC1D,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAA2B,kBAAkB,EAAE,OAAO,CAAC;IACnF;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDG;AACH,IAAA,MAAM,cAAc,CAAC,OAAA,GAA0C,EAAE,EAAA;QAC/D,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAkC,0BAA0B,EAAE,OAAO,CAAC;IAClG;AAEA;;;;;;;;;;;;;;;;;AAiBG;AACH,IAAA,MAAM,kBAAkB,CAAC,OAAA,GAA8C,EAAE,EAAA;QACvE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAsC,+BAA+B,EAAE,OAAO,CAAC;IAC3G;AAEA;;;;;;;;;;;;;;;AAeG;AACH,IAAA,MAAM,qBAAqB,CAAC,OAAA,GAAwC,EAAE,EAAA;QACpE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAgC,4BAA4B,EAAE,OAAO,CAAC;IAClG;AACD;;ACjND;;;;;;;AAOG;MACU,gBAAgB,CAAA;AAC3B,IAAA,WAAA,CAAoB,YAA0B,EAAA;QAA1B,IAAA,CAAA,YAAY,GAAZ,YAAY;IAAiB;;;;AAMjD;;AAEG;IACH,MAAM,uBAAuB,CAAC,OAAuC,EAAA;QACnE,OAAO,IAAI,CAAC,YAAY,CAAC,uBAAuB,CAAC,OAAO,CAAC;IAC3D;AAEA;;AAEG;IACH,MAAM,yBAAyB,CAAC,OAAyC,EAAA;QACvE,OAAO,IAAI,CAAC,YAAY,CAAC,yBAAyB,CAAC,OAAO,CAAC;IAC7D;AAEA;;;;;AAKG;AACH,IAAA,MAAM,gBAAgB,CAAC,OAAA,GAAmC,EAAE,EAAA;QAC1D,OAAO,IAAI,CAAC,YAAY,CAAC,gBAAgB,CAAC,OAAO,CAAC;IACpD;AAEA;;;;;AAKG;AACH,IAAA,MAAM,cAAc,CAAC,OAAA,GAA0C,EAAE,EAAA;QAC/D,OAAO,IAAI,CAAC,YAAY,CAAC,cAAc,CAAC,OAAO,CAAC;IAClD;AAEA;;;;AAIG;AACH,IAAA,MAAM,kBAAkB,CAAC,OAAA,GAA8C,EAAE,EAAA;QACvE,OAAO,IAAI,CAAC,YAAY,CAAC,kBAAkB,CAAC,OAAO,CAAC;IACtD;AAEA;;;;;AAKG;AACH,IAAA,MAAM,qBAAqB,CAAC,OAAA,GAAwC,EAAE,EAAA;QACpE,OAAO,IAAI,CAAC,YAAY,CAAC,qBAAqB,CAAC,OAAO,CAAC;IACzD;AACD;;;;"}
|
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Platform-Agnostic Analytics API Client
|
|
5
|
+
*
|
|
6
|
+
* Handles analytics operations using the PERS backend.
|
|
7
|
+
* Uses @explorins/pers-shared DTOs for consistency with backend.
|
|
8
|
+
*/
|
|
9
|
+
class AnalyticsApi {
|
|
10
|
+
constructor(apiClient) {
|
|
11
|
+
this.apiClient = apiClient;
|
|
12
|
+
}
|
|
13
|
+
// ==========================================
|
|
14
|
+
// ADMIN OPERATIONS
|
|
15
|
+
// ==========================================
|
|
16
|
+
/**
|
|
17
|
+
* ADMIN: Get transaction analytics with filtering and aggregation
|
|
18
|
+
*/
|
|
19
|
+
async getTransactionAnalytics(request) {
|
|
20
|
+
return this.apiClient.post('/analytics/transactions', request);
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* ADMIN: Get campaign claim analytics with aggregation (charts, metrics, grouping)
|
|
24
|
+
*
|
|
25
|
+
* This endpoint is for aggregated analytics only (groupBy/metrics).
|
|
26
|
+
* For enriched list data with nested objects, use campaign.getClaims() instead.
|
|
27
|
+
*
|
|
28
|
+
* @example Claims per campaign
|
|
29
|
+
* ```typescript
|
|
30
|
+
* const response = await analyticsApi.getCampaignClaimAnalytics({
|
|
31
|
+
* filters: { status: 'COMPLETED' },
|
|
32
|
+
* groupBy: ['campaignId'],
|
|
33
|
+
* metrics: ['count'],
|
|
34
|
+
* sortBy: 'count',
|
|
35
|
+
* sortOrder: SortOrder.DESC,
|
|
36
|
+
* limit: 10
|
|
37
|
+
* });
|
|
38
|
+
* ```
|
|
39
|
+
*
|
|
40
|
+
* @example Claims over time by status
|
|
41
|
+
* ```typescript
|
|
42
|
+
* const response = await analyticsApi.getCampaignClaimAnalytics({
|
|
43
|
+
* groupBy: ['month', 'status'],
|
|
44
|
+
* metrics: ['count'],
|
|
45
|
+
* sortBy: 'month',
|
|
46
|
+
* sortOrder: SortOrder.DESC,
|
|
47
|
+
* startDate: new Date('2026-01-01'),
|
|
48
|
+
* endDate: new Date('2026-12-31')
|
|
49
|
+
* });
|
|
50
|
+
* ```
|
|
51
|
+
*/
|
|
52
|
+
async getCampaignClaimAnalytics(request) {
|
|
53
|
+
return this.apiClient.post('/analytics/campaign-claims', request);
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* ADMIN: Get user analytics with engagement metrics
|
|
57
|
+
*
|
|
58
|
+
* Returns aggregated user statistics including engagement rate, active users,
|
|
59
|
+
* transaction metrics, and per-active-user averages (more accurate than all-user averages).
|
|
60
|
+
*
|
|
61
|
+
* Request structure matches TransactionAnalytics and CampaignClaimAnalytics for consistency:
|
|
62
|
+
* - filters object for business-specific scoping
|
|
63
|
+
* - startDate/endDate at root level for date range filtering
|
|
64
|
+
*
|
|
65
|
+
* @param request - Analytics request with optional filters and date range
|
|
66
|
+
* @returns Aggregated user metrics with per-user and per-active-user averages
|
|
67
|
+
*
|
|
68
|
+
* @example Basic user analytics (all time, all businesses)
|
|
69
|
+
* ```typescript
|
|
70
|
+
* const analytics = await analyticsApi.getUserAnalytics({});
|
|
71
|
+
* console.log(`Total users: ${analytics.totalUsers}`);
|
|
72
|
+
* console.log(`Active users: ${analytics.activeUsers}`);
|
|
73
|
+
* console.log(`Engagement rate: ${analytics.engagementRate}%`);
|
|
74
|
+
*
|
|
75
|
+
* // Per-user averages (includes inactive users)
|
|
76
|
+
* console.log(`Avg transactions per user: ${analytics.averageTransactionsPerUser}`);
|
|
77
|
+
*
|
|
78
|
+
* // Per-active-user averages (only engaged users - more useful!)
|
|
79
|
+
* console.log(`Avg transactions per active user: ${analytics.averageTransactionsPerActiveUser}`);
|
|
80
|
+
* ```
|
|
81
|
+
*
|
|
82
|
+
* @example Filtered by date range
|
|
83
|
+
* ```typescript
|
|
84
|
+
* const analytics = await analyticsApi.getUserAnalytics({
|
|
85
|
+
* startDate: new Date('2026-01-01'),
|
|
86
|
+
* endDate: new Date('2026-01-31')
|
|
87
|
+
* });
|
|
88
|
+
* console.log(`January metrics:`);
|
|
89
|
+
* console.log(`Active users: ${analytics.activeUsers}`);
|
|
90
|
+
* console.log(`New users: ${analytics.newUsers}`);
|
|
91
|
+
* console.log(`Date range applied: ${analytics.metadata.dateRange?.startDate} - ${analytics.metadata.dateRange?.endDate}`);
|
|
92
|
+
* ```
|
|
93
|
+
*
|
|
94
|
+
* @example Business-specific analytics with filters
|
|
95
|
+
* ```typescript
|
|
96
|
+
* const analytics = await analyticsApi.getUserAnalytics({
|
|
97
|
+
* filters: { businessId: 'biz-123' },
|
|
98
|
+
* startDate: new Date('2026-01-01'),
|
|
99
|
+
* endDate: new Date('2026-12-31')
|
|
100
|
+
* });
|
|
101
|
+
* console.log(`Business customer engagement in 2026:`);
|
|
102
|
+
* console.log(`Active customers: ${analytics.activeUsers}`);
|
|
103
|
+
* console.log(`Avg claims per active customer: ${analytics.averageClaimsPerActiveUser.toFixed(2)}`);
|
|
104
|
+
* console.log(`Customer engagement rate: ${analytics.engagementRate.toFixed(1)}%`);
|
|
105
|
+
* ```
|
|
106
|
+
*/
|
|
107
|
+
async getUserAnalytics(request = {}) {
|
|
108
|
+
return this.apiClient.post('/analytics/users', request);
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* ADMIN: Get user transaction ranking with enriched user data
|
|
112
|
+
*
|
|
113
|
+
* Returns ranked list of users with full user details and transaction metrics.
|
|
114
|
+
* Data enrichment happens via efficient SQL JOINs + UNION (handles legacy transactions).
|
|
115
|
+
*
|
|
116
|
+
* Use Cases:
|
|
117
|
+
* - Admin leaderboards showing top users by activity
|
|
118
|
+
* - User engagement analysis with full user context
|
|
119
|
+
* - Identifying power users for campaigns
|
|
120
|
+
*
|
|
121
|
+
* @param request - Ranking request with filters, sorting, and limit
|
|
122
|
+
* @returns Ranked list with user details (email, externalUserId) and transaction metrics
|
|
123
|
+
*
|
|
124
|
+
* @example Top 50 users by transaction count
|
|
125
|
+
* ```typescript
|
|
126
|
+
* const ranking = await analyticsApi.getUserRanking({
|
|
127
|
+
* sortBy: 'totalTransactions',
|
|
128
|
+
* sortOrder: SortOrder.DESC,
|
|
129
|
+
* limit: 50
|
|
130
|
+
* });
|
|
131
|
+
*
|
|
132
|
+
* ranking.results.forEach((user, index) => {
|
|
133
|
+
* console.log(`#${index + 1}: ${user.email || user.externalUserId} - ${user.totalTransactions} transactions`);
|
|
134
|
+
* });
|
|
135
|
+
* ```
|
|
136
|
+
*
|
|
137
|
+
* @example Top users by STAMP spending
|
|
138
|
+
* ```typescript
|
|
139
|
+
* const ranking = await analyticsApi.getUserRanking({
|
|
140
|
+
* filters: { tokenType: 'STAMP' },
|
|
141
|
+
* sortBy: 'tokenSpent',
|
|
142
|
+
* sortOrder: SortOrder.DESC,
|
|
143
|
+
* limit: 20
|
|
144
|
+
* });
|
|
145
|
+
* ```
|
|
146
|
+
*
|
|
147
|
+
* @example Business-specific leaderboard with date range
|
|
148
|
+
* ```typescript
|
|
149
|
+
* const ranking = await analyticsApi.getUserRanking({
|
|
150
|
+
* filters: {
|
|
151
|
+
* businessId: 'business-uuid-here',
|
|
152
|
+
* tokenType: 'CREDIT'
|
|
153
|
+
* },
|
|
154
|
+
* sortBy: 'totalTransactions',
|
|
155
|
+
* sortOrder: SortOrder.DESC,
|
|
156
|
+
* limit: 100,
|
|
157
|
+
* startDate: new Date('2026-01-01'),
|
|
158
|
+
* endDate: new Date('2026-12-31')
|
|
159
|
+
* });
|
|
160
|
+
* console.log(`Top ${ranking.totalUsers} users for business in 2026`);
|
|
161
|
+
* ```
|
|
162
|
+
*/
|
|
163
|
+
async getUserRanking(request = {}) {
|
|
164
|
+
return this.apiClient.post('/analytics/users/ranking', request);
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* ADMIN: Get business transaction ranking with enriched business data
|
|
168
|
+
*
|
|
169
|
+
* Returns ranked list of businesses with full business details and transaction metrics.
|
|
170
|
+
* Data enrichment happens via efficient SQL JOINs + UNION (handles legacy transactions).
|
|
171
|
+
*
|
|
172
|
+
* @param request - Ranking request with filters, sorting, and limit
|
|
173
|
+
* @returns Ranked list with business details and transaction metrics
|
|
174
|
+
*
|
|
175
|
+
* @example Top 50 businesses by transaction count
|
|
176
|
+
* ```typescript
|
|
177
|
+
* const ranking = await analyticsApi.getBusinessRanking({
|
|
178
|
+
* sortBy: 'totalTransactions',
|
|
179
|
+
* sortOrder: SortOrder.DESC,
|
|
180
|
+
* limit: 50
|
|
181
|
+
* });
|
|
182
|
+
* ```
|
|
183
|
+
*/
|
|
184
|
+
async getBusinessRanking(request = {}) {
|
|
185
|
+
return this.apiClient.post('/analytics/businesses/ranking', request);
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* ADMIN: Get monthly user retention analytics
|
|
189
|
+
*
|
|
190
|
+
* Returns monthly retention data with active/new/returning users and retention rates.
|
|
191
|
+
* Replaces 13 separate API calls with 1 efficient recursive CTE query.
|
|
192
|
+
*
|
|
193
|
+
* @param request - Retention analytics request with monthsBack and filters
|
|
194
|
+
* @returns Monthly retention data with user metrics and retention rates
|
|
195
|
+
*
|
|
196
|
+
* @example Last 13 months retention
|
|
197
|
+
* ```typescript
|
|
198
|
+
* const retention = await analyticsApi.getRetentionAnalytics({
|
|
199
|
+
* monthsBack: 13
|
|
200
|
+
* });
|
|
201
|
+
* ```
|
|
202
|
+
*/
|
|
203
|
+
async getRetentionAnalytics(request = {}) {
|
|
204
|
+
return this.apiClient.post('/analytics/users/retention', request);
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Platform-Agnostic Analytics Service
|
|
210
|
+
*
|
|
211
|
+
* Contains analytics business logic and operations that work across platforms.
|
|
212
|
+
* No framework dependencies - pure TypeScript business logic.
|
|
213
|
+
*
|
|
214
|
+
* Focuses only on actual backend capabilities.
|
|
215
|
+
*/
|
|
216
|
+
class AnalyticsService {
|
|
217
|
+
constructor(analyticsApi) {
|
|
218
|
+
this.analyticsApi = analyticsApi;
|
|
219
|
+
}
|
|
220
|
+
// ==========================================
|
|
221
|
+
// ADMIN OPERATIONS
|
|
222
|
+
// ==========================================
|
|
223
|
+
/**
|
|
224
|
+
* ADMIN: Get transaction analytics with filtering and aggregation
|
|
225
|
+
*/
|
|
226
|
+
async getTransactionAnalytics(request) {
|
|
227
|
+
return this.analyticsApi.getTransactionAnalytics(request);
|
|
228
|
+
}
|
|
229
|
+
/**
|
|
230
|
+
* ADMIN: Get campaign claim analytics with aggregation
|
|
231
|
+
*/
|
|
232
|
+
async getCampaignClaimAnalytics(request) {
|
|
233
|
+
return this.analyticsApi.getCampaignClaimAnalytics(request);
|
|
234
|
+
}
|
|
235
|
+
/**
|
|
236
|
+
* ADMIN: Get user analytics with engagement metrics
|
|
237
|
+
*
|
|
238
|
+
* Returns aggregated user statistics including engagement rate, active users,
|
|
239
|
+
* transaction metrics, and claims/redemption averages.
|
|
240
|
+
*/
|
|
241
|
+
async getUserAnalytics(request = {}) {
|
|
242
|
+
return this.analyticsApi.getUserAnalytics(request);
|
|
243
|
+
}
|
|
244
|
+
/**
|
|
245
|
+
* ADMIN: Get user transaction ranking with enriched user data
|
|
246
|
+
*
|
|
247
|
+
* Returns ranked list of users with full user details (email, externalUserId)
|
|
248
|
+
* and transaction metrics. Efficient data enrichment via SQL JOINs + UNION.
|
|
249
|
+
*/
|
|
250
|
+
async getUserRanking(request = {}) {
|
|
251
|
+
return this.analyticsApi.getUserRanking(request);
|
|
252
|
+
}
|
|
253
|
+
/**
|
|
254
|
+
* ADMIN: Get business transaction ranking with enriched business data
|
|
255
|
+
*
|
|
256
|
+
* Returns ranked list of businesses with full business details and transaction metrics.
|
|
257
|
+
*/
|
|
258
|
+
async getBusinessRanking(request = {}) {
|
|
259
|
+
return this.analyticsApi.getBusinessRanking(request);
|
|
260
|
+
}
|
|
261
|
+
/**
|
|
262
|
+
* ADMIN: Get monthly user retention analytics
|
|
263
|
+
*
|
|
264
|
+
* Returns monthly retention data with user metrics and retention rates.
|
|
265
|
+
* Replaces 13 separate API calls with 1 efficient query.
|
|
266
|
+
*/
|
|
267
|
+
async getRetentionAnalytics(request = {}) {
|
|
268
|
+
return this.analyticsApi.getRetentionAnalytics(request);
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
exports.AnalyticsApi = AnalyticsApi;
|
|
273
|
+
exports.AnalyticsService = AnalyticsService;
|
|
274
|
+
//# sourceMappingURL=analytics-service-DwkeBB08.cjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"analytics-service-DwkeBB08.cjs","sources":["../../src/analytics/api/analytics-api.ts","../../src/analytics/services/analytics-service.ts"],"sourcesContent":[null,null],"names":[],"mappings":";;AAiBA;;;;;AAKG;MACU,YAAY,CAAA;AACvB,IAAA,WAAA,CAAoB,SAAwB,EAAA;QAAxB,IAAA,CAAA,SAAS,GAAT,SAAS;IAAkB;;;;AAM/C;;AAEG;IACH,MAAM,uBAAuB,CAAC,OAAuC,EAAA;QACnE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAkC,yBAAyB,EAAE,OAAO,CAAC;IACjG;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BG;IACH,MAAM,yBAAyB,CAAC,OAAyC,EAAA;QACvE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAoC,4BAA4B,EAAE,OAAO,CAAC;IACtG;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDG;AACH,IAAA,MAAM,gBAAgB,CAAC,OAAA,GAAmC,EAAE,EAAA;QAC1D,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAA2B,kBAAkB,EAAE,OAAO,CAAC;IACnF;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDG;AACH,IAAA,MAAM,cAAc,CAAC,OAAA,GAA0C,EAAE,EAAA;QAC/D,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAkC,0BAA0B,EAAE,OAAO,CAAC;IAClG;AAEA;;;;;;;;;;;;;;;;;AAiBG;AACH,IAAA,MAAM,kBAAkB,CAAC,OAAA,GAA8C,EAAE,EAAA;QACvE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAsC,+BAA+B,EAAE,OAAO,CAAC;IAC3G;AAEA;;;;;;;;;;;;;;;AAeG;AACH,IAAA,MAAM,qBAAqB,CAAC,OAAA,GAAwC,EAAE,EAAA;QACpE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAgC,4BAA4B,EAAE,OAAO,CAAC;IAClG;AACD;;ACjND;;;;;;;AAOG;MACU,gBAAgB,CAAA;AAC3B,IAAA,WAAA,CAAoB,YAA0B,EAAA;QAA1B,IAAA,CAAA,YAAY,GAAZ,YAAY;IAAiB;;;;AAMjD;;AAEG;IACH,MAAM,uBAAuB,CAAC,OAAuC,EAAA;QACnE,OAAO,IAAI,CAAC,YAAY,CAAC,uBAAuB,CAAC,OAAO,CAAC;IAC3D;AAEA;;AAEG;IACH,MAAM,yBAAyB,CAAC,OAAyC,EAAA;QACvE,OAAO,IAAI,CAAC,YAAY,CAAC,yBAAyB,CAAC,OAAO,CAAC;IAC7D;AAEA;;;;;AAKG;AACH,IAAA,MAAM,gBAAgB,CAAC,OAAA,GAAmC,EAAE,EAAA;QAC1D,OAAO,IAAI,CAAC,YAAY,CAAC,gBAAgB,CAAC,OAAO,CAAC;IACpD;AAEA;;;;;AAKG;AACH,IAAA,MAAM,cAAc,CAAC,OAAA,GAA0C,EAAE,EAAA;QAC/D,OAAO,IAAI,CAAC,YAAY,CAAC,cAAc,CAAC,OAAO,CAAC;IAClD;AAEA;;;;AAIG;AACH,IAAA,MAAM,kBAAkB,CAAC,OAAA,GAA8C,EAAE,EAAA;QACvE,OAAO,IAAI,CAAC,YAAY,CAAC,kBAAkB,CAAC,OAAO,CAAC;IACtD;AAEA;;;;;AAKG;AACH,IAAA,MAAM,qBAAqB,CAAC,OAAA,GAAwC,EAAE,EAAA;QACpE,OAAO,IAAI,CAAC,YAAY,CAAC,qBAAqB,CAAC,OAAO,CAAC;IACzD;AACD;;;;;"}
|