@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.
Files changed (108) hide show
  1. package/dist/analytics/api/analytics-api.d.ts +175 -1
  2. package/dist/analytics/api/analytics-api.d.ts.map +1 -1
  3. package/dist/analytics/models/index.d.ts +2 -5
  4. package/dist/analytics/models/index.d.ts.map +1 -1
  5. package/dist/analytics/services/analytics-service.d.ts +32 -1
  6. package/dist/analytics/services/analytics-service.d.ts.map +1 -1
  7. package/dist/analytics.cjs +9 -44
  8. package/dist/analytics.cjs.map +1 -1
  9. package/dist/analytics.js +2 -45
  10. package/dist/analytics.js.map +1 -1
  11. package/dist/campaign/api/campaign-api.d.ts +59 -4
  12. package/dist/campaign/api/campaign-api.d.ts.map +1 -1
  13. package/dist/campaign/services/campaign-service.d.ts +49 -7
  14. package/dist/campaign/services/campaign-service.d.ts.map +1 -1
  15. package/dist/campaign.cjs +150 -14
  16. package/dist/campaign.cjs.map +1 -1
  17. package/dist/campaign.js +150 -14
  18. package/dist/campaign.js.map +1 -1
  19. package/dist/chunks/analytics-service-B9IfG6ox.js +271 -0
  20. package/dist/chunks/analytics-service-B9IfG6ox.js.map +1 -0
  21. package/dist/chunks/analytics-service-DwkeBB08.cjs +274 -0
  22. package/dist/chunks/analytics-service-DwkeBB08.cjs.map +1 -0
  23. package/dist/chunks/{pers-sdk-DnLw822h.js → pers-sdk-CAM0iQyK.js} +1203 -267
  24. package/dist/chunks/pers-sdk-CAM0iQyK.js.map +1 -0
  25. package/dist/chunks/{pers-sdk-D5lE9ZFW.cjs → pers-sdk-Di_R6AiT.cjs} +1207 -268
  26. package/dist/chunks/pers-sdk-Di_R6AiT.cjs.map +1 -0
  27. package/dist/chunks/{redemption-service-D-hBqh42.js → redemption-service-CQtTLdic.js} +32 -10
  28. package/dist/chunks/redemption-service-CQtTLdic.js.map +1 -0
  29. package/dist/chunks/{redemption-service-rMB6T2W5.cjs → redemption-service-DsH7sRdv.cjs} +32 -10
  30. package/dist/chunks/redemption-service-DsH7sRdv.cjs.map +1 -0
  31. package/dist/chunks/{transaction-request.builder-C1vVVFto.js → transaction-request.builder-C8ahJYwi.js} +122 -70
  32. package/dist/chunks/transaction-request.builder-C8ahJYwi.js.map +1 -0
  33. package/dist/chunks/{transaction-request.builder-BpgtuMMq.cjs → transaction-request.builder-CkYd5bl6.cjs} +122 -70
  34. package/dist/chunks/transaction-request.builder-CkYd5bl6.cjs.map +1 -0
  35. package/dist/core/auth/auth-provider.interface.d.ts +1 -0
  36. package/dist/core/auth/auth-provider.interface.d.ts.map +1 -1
  37. package/dist/core/auth/default-auth-provider.d.ts +2 -0
  38. package/dist/core/auth/default-auth-provider.d.ts.map +1 -1
  39. package/dist/core/auth/refresh-manager.d.ts +2 -0
  40. package/dist/core/auth/refresh-manager.d.ts.map +1 -1
  41. package/dist/core/auth/services/auth-service.d.ts.map +1 -1
  42. package/dist/core/auth/token-storage.d.ts +2 -1
  43. package/dist/core/auth/token-storage.d.ts.map +1 -1
  44. package/dist/core/pers-api-client.d.ts.map +1 -1
  45. package/dist/core/pers-config.d.ts +0 -18
  46. package/dist/core/pers-config.d.ts.map +1 -1
  47. package/dist/core.cjs +5 -4
  48. package/dist/core.cjs.map +1 -1
  49. package/dist/core.js +4 -4
  50. package/dist/index.cjs +13 -6
  51. package/dist/index.cjs.map +1 -1
  52. package/dist/index.d.ts +1 -0
  53. package/dist/index.d.ts.map +1 -1
  54. package/dist/index.js +5 -5
  55. package/dist/managers/analytics-manager.d.ts +165 -2
  56. package/dist/managers/analytics-manager.d.ts.map +1 -1
  57. package/dist/managers/campaign-manager.d.ts +180 -30
  58. package/dist/managers/campaign-manager.d.ts.map +1 -1
  59. package/dist/managers/index.d.ts +1 -0
  60. package/dist/managers/index.d.ts.map +1 -1
  61. package/dist/managers/redemption-manager.d.ts +52 -2
  62. package/dist/managers/redemption-manager.d.ts.map +1 -1
  63. package/dist/managers/transaction-manager.d.ts +66 -131
  64. package/dist/managers/transaction-manager.d.ts.map +1 -1
  65. package/dist/managers/trigger-source-manager.d.ts +194 -0
  66. package/dist/managers/trigger-source-manager.d.ts.map +1 -0
  67. package/dist/managers/user-manager.d.ts +38 -7
  68. package/dist/managers/user-manager.d.ts.map +1 -1
  69. package/dist/node.cjs +4 -4
  70. package/dist/node.js +4 -4
  71. package/dist/package.json +2 -2
  72. package/dist/pers-sdk.d.ts +68 -23
  73. package/dist/pers-sdk.d.ts.map +1 -1
  74. package/dist/redemption/api/redemption-api.d.ts +8 -4
  75. package/dist/redemption/api/redemption-api.d.ts.map +1 -1
  76. package/dist/redemption/services/redemption-service.d.ts +7 -3
  77. package/dist/redemption/services/redemption-service.d.ts.map +1 -1
  78. package/dist/redemption.cjs +1 -1
  79. package/dist/redemption.js +1 -1
  80. package/dist/transaction/api/transaction-api.d.ts +37 -42
  81. package/dist/transaction/api/transaction-api.d.ts.map +1 -1
  82. package/dist/transaction/models/index.d.ts +21 -0
  83. package/dist/transaction/models/index.d.ts.map +1 -1
  84. package/dist/transaction/services/transaction-service.d.ts +10 -15
  85. package/dist/transaction/services/transaction-service.d.ts.map +1 -1
  86. package/dist/transaction.cjs +1 -1
  87. package/dist/transaction.js +1 -1
  88. package/dist/trigger-source/api/trigger-source-api.d.ts +86 -0
  89. package/dist/trigger-source/api/trigger-source-api.d.ts.map +1 -0
  90. package/dist/trigger-source/index.d.ts +9 -0
  91. package/dist/trigger-source/index.d.ts.map +1 -0
  92. package/dist/trigger-source/services/trigger-source-service.d.ts +42 -0
  93. package/dist/trigger-source/services/trigger-source-service.d.ts.map +1 -0
  94. package/dist/user/api/user-api.d.ts +26 -1
  95. package/dist/user/api/user-api.d.ts.map +1 -1
  96. package/dist/user/services/user-service.d.ts +3 -1
  97. package/dist/user/services/user-service.d.ts.map +1 -1
  98. package/dist/user.cjs +34 -4
  99. package/dist/user.cjs.map +1 -1
  100. package/dist/user.js +34 -4
  101. package/dist/user.js.map +1 -1
  102. package/package.json +2 -2
  103. package/dist/chunks/pers-sdk-D5lE9ZFW.cjs.map +0 -1
  104. package/dist/chunks/pers-sdk-DnLw822h.js.map +0 -1
  105. package/dist/chunks/redemption-service-D-hBqh42.js.map +0 -1
  106. package/dist/chunks/redemption-service-rMB6T2W5.cjs.map +0 -1
  107. package/dist/chunks/transaction-request.builder-BpgtuMMq.cjs.map +0 -1
  108. 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;;;;;"}