@explorins/pers-shared 2.1.79 → 2.1.81

package/dist/cjs/shared-lib/dto/analytics/base-analytics.dto.d.ts

@@ -0,0 +1,38 @@
+/**
+ * BASE ANALYTICS REQUEST
+ *
+ * Common date range filtering for all analytics endpoints.
+ * Extend this for consistent API patterns across analytics.
+ */
+export declare abstract class BaseAnalyticsRequestDTO {
+    startDate?: Date;
+    endDate?: Date;
+}
+/**
+ * BASE ANALYTICS RESPONSE METADATA
+ *
+ * Common metadata structure for all analytics responses.
+ * Shows applied filters for transparency.
+ *
+ * Note: Execution time removed - client can measure total request time using performance.now()
+ * which includes network latency and is more relevant for UX monitoring.
+ */
+export interface BaseAnalyticsMetadata {
+    /**
+     * Applied date range filter (only present if startDate or endDate was provided in request)
+     */
+    dateRange?: {
+        startDate: Date;
+        endDate: Date;
+    };
+}
+/**
+ * BASE ANALYTICS RESPONSE
+ *
+ * Common response structure for analytics endpoints.
+ * All analytics responses should include metadata with timing and filter info.
+ */
+export declare abstract class BaseAnalyticsResponseDTO {
+    abstract metadata: BaseAnalyticsMetadata;
+}
+//# sourceMappingURL=base-analytics.dto.d.ts.map

package/dist/cjs/shared-lib/dto/analytics/base-analytics.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-analytics.dto.d.ts","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/base-analytics.dto.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,8BAAsB,uBAAuB;IAO3C,SAAS,CAAC,EAAE,IAAI,CAAC;IAQjB,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,SAAS,CAAC,EAAE;QACV,SAAS,EAAE,IAAI,CAAC;QAChB,OAAO,EAAE,IAAI,CAAC;KACf,CAAC;CACH;AAED;;;;;GAKG;AACH,8BAAsB,wBAAwB;IAC5C,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;CAC1C"}

package/dist/cjs/shared-lib/dto/analytics/base-analytics.dto.js

@@ -0,0 +1,53 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseAnalyticsResponseDTO = exports.BaseAnalyticsRequestDTO = void 0;
+const swagger_1 = require("@nestjs/swagger");
+const class_validator_1 = require("class-validator");
+/**
+ * BASE ANALYTICS REQUEST
+ *
+ * Common date range filtering for all analytics endpoints.
+ * Extend this for consistent API patterns across analytics.
+ */
+class BaseAnalyticsRequestDTO {
+    startDate;
+    endDate;
+}
+exports.BaseAnalyticsRequestDTO = BaseAnalyticsRequestDTO;
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Start date for filtering (ISO 8601 format). Filters records with createdAt >= startDate.',
+        example: '2024-01-01T00:00:00.000Z'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", Date)
+], BaseAnalyticsRequestDTO.prototype, "startDate", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'End date for filtering (ISO 8601 format). Filters records with createdAt <= endDate.',
+        example: '2024-12-31T23:59:59.999Z'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", Date)
+], BaseAnalyticsRequestDTO.prototype, "endDate", void 0);
+/**
+ * BASE ANALYTICS RESPONSE
+ *
+ * Common response structure for analytics endpoints.
+ * All analytics responses should include metadata with timing and filter info.
+ */
+class BaseAnalyticsResponseDTO {
+}
+exports.BaseAnalyticsResponseDTO = BaseAnalyticsResponseDTO;
+//# sourceMappingURL=base-analytics.dto.js.map

package/dist/cjs/shared-lib/dto/analytics/base-analytics.dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-analytics.dto.js","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/base-analytics.dto.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,6CAAsD;AACtD,qDAA2D;AAE3D;;;;;GAKG;AACH,MAAsB,uBAAuB;IAO3C,SAAS,CAAQ;IAQjB,OAAO,CAAQ;CAChB;AAhBD,0DAgBC;AATC;IANC,IAAA,6BAAmB,EAAC;QACnB,WAAW,EAAE,0FAA0F;QACvG,OAAO,EAAE,0BAA0B;KACpC,CAAC;IACD,IAAA,4BAAU,GAAE;IACZ,IAAA,8BAAY,GAAE;8BACH,IAAI;0DAAC;AAQjB;IANC,IAAA,6BAAmB,EAAC;QACnB,WAAW,EAAE,sFAAsF;QACnG,OAAO,EAAE,0BAA0B;KACpC,CAAC;IACD,IAAA,4BAAU,GAAE;IACZ,IAAA,8BAAY,GAAE;8BACL,IAAI;wDAAC;AAsBjB;;;;;GAKG;AACH,MAAsB,wBAAwB;CAE7C;AAFD,4DAEC"}

package/dist/cjs/shared-lib/dto/{campaign → analytics}/campaign-claim-analytics.dto.d.ts

@@ -1,8 +1,8 @@
 import { ProcessRecordStatus } from "../../enum";
 import { UserDTO } from "../user.dto";
-import { CampaignDTO } from "./campaign.dto";
+import { CampaignDTO } from "../campaign/campaign.dto";
 import { BusinessDTO } from "../business/business.dto";
-import { TriggerSourceDTO } from "./trigger-source.dto";
+import { TriggerSourceDTO } from "../campaign/trigger-source.dto";
 /**
  * Campaign Claim Analytics DTO
  *

package/dist/cjs/shared-lib/dto/analytics/campaign-claim-analytics.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"campaign-claim-analytics.dto.d.ts","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/campaign-claim-analytics.dto.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,qBAAa,yBAAyB;IAKpC,EAAE,EAAE,MAAM,CAAM;IAMhB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAQ;IAQ9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAQ;IAQ7B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAQ;IAQjC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAQ;IAQjC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAQ;IAOtC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAQ;IAO5B,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAQ;IAOpC,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAO9B,aAAa,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAOxC,MAAM,EAAE,mBAAmB,CAA+B;IAQ1D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAQ;IAQtC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAQ/B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAOhC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB"}

package/dist/cjs/shared-lib/dto/{campaign → analytics}/campaign-claim-analytics.dto.js

@@ -13,9 +13,9 @@ exports.CampaignClaimAnalyticsDTO = void 0;
 const swagger_1 = require("@nestjs/swagger");
 const enum_1 = require("../../enum");
 const user_dto_1 = require("../user.dto");
-const campaign_dto_1 = require("./campaign.dto");
+const campaign_dto_1 = require("../campaign/campaign.dto");
 const business_dto_1 = require("../business/business.dto");
-const trigger_source_dto_1 = require("./trigger-source.dto");
+const trigger_source_dto_1 = require("../campaign/trigger-source.dto");
 /**
  * Campaign Claim Analytics DTO
  *
@@ -50,21 +50,21 @@ class CampaignClaimAnalyticsDTO {
 exports.CampaignClaimAnalyticsDTO = CampaignClaimAnalyticsDTO;
 __decorate([
     (0, swagger_1.ApiProperty)({
-        description: 'Unique claim ID',
+        description: 'Unique claim ID (UUID) - primary identifier for this claim record',
         example: 'claim-uuid-123'
     }),
     __metadata("design:type", String)
 ], CampaignClaimAnalyticsDTO.prototype, "id", void 0);
 __decorate([
     (0, swagger_1.ApiProperty)({
-        description: 'Timestamp when claim was created',
+        description: 'Timestamp when claim was created (ISO 8601 format). Used for time-based analytics and filtering.',
         type: Date
     }),
     __metadata("design:type", Object)
 ], CampaignClaimAnalyticsDTO.prototype, "createdAt", void 0);
 __decorate([
     (0, swagger_1.ApiPropertyOptional)({
-        description: 'User ID - foreign key for groupBy operations',
+        description: 'User ID (UUID) who made the claim - foreign key reference. Use for user-based grouping and aggregations.',
         type: String,
         nullable: true,
         example: 'user-uuid-123'
@@ -73,7 +73,7 @@ __decorate([
 ], CampaignClaimAnalyticsDTO.prototype, "userId", void 0);
 __decorate([
     (0, swagger_1.ApiPropertyOptional)({
-        description: 'Campaign ID - foreign key for groupBy operations',
+        description: 'Campaign ID (UUID) that was claimed - foreign key reference. Use for campaign performance analytics and grouping.',
         type: String,
         nullable: true,
         example: 'campaign-uuid-456'
@@ -82,7 +82,7 @@ __decorate([
 ], CampaignClaimAnalyticsDTO.prototype, "campaignId", void 0);
 __decorate([
     (0, swagger_1.ApiPropertyOptional)({
-        description: 'Business ID - foreign key for groupBy operations',
+        description: 'Business ID (UUID) associated with the claim - foreign key reference. Use for business-level analytics and grouping.',
         type: String,
         nullable: true,
         example: 'business-uuid-789'
@@ -91,7 +91,7 @@ __decorate([
 ], CampaignClaimAnalyticsDTO.prototype, "businessId", void 0);
 __decorate([
     (0, swagger_1.ApiPropertyOptional)({
-        description: 'Trigger Source ID - foreign key for groupBy operations',
+        description: 'Trigger Source ID (UUID) - the specific trigger (QR code, geofence, etc.) that initiated the claim. Use for trigger effectiveness analytics.',
         type: String,
         nullable: true,
         example: 'trigger-uuid-101'
@@ -100,7 +100,7 @@ __decorate([
 ], CampaignClaimAnalyticsDTO.prototype, "triggerSourceId", void 0);
 __decorate([
     (0, swagger_1.ApiPropertyOptional)({
-        description: 'User who claimed the campaign (full object for analytics)',
+        description: 'Full user object (enriched data) - includes email, wallet address, public profile. Only populated when "include=user" query parameter is provided. NULL if not requested to optimize response size.',
         type: () => user_dto_1.UserDTO,
         nullable: true
     }),
@@ -108,7 +108,7 @@ __decorate([
 ], CampaignClaimAnalyticsDTO.prototype, "user", void 0);
 __decorate([
     (0, swagger_1.ApiPropertyOptional)({
-        description: 'Campaign that was claimed (full object for analytics)',
+        description: 'Full campaign object (enriched data) - includes name, description, token rewards. Only populated when "include=campaign" query parameter is provided. NULL if not requested to optimize response size.',
         type: () => campaign_dto_1.CampaignDTO,
         nullable: true
     }),
@@ -116,7 +116,7 @@ __decorate([
 ], CampaignClaimAnalyticsDTO.prototype, "campaign", void 0);
 __decorate([
     (0, swagger_1.ApiPropertyOptional)({
-        description: 'Business associated with claim (full object for analytics)',
+        description: 'Full business object (enriched data) - includes business name, location, logo. Only populated when "include=business" query parameter is provided. NULL if not requested to optimize response size.',
         type: () => business_dto_1.BusinessDTO,
         nullable: true
     }),
@@ -124,7 +124,7 @@ __decorate([
 ], CampaignClaimAnalyticsDTO.prototype, "business", void 0);
 __decorate([
     (0, swagger_1.ApiPropertyOptional)({
-        description: 'Trigger source used for claim (full object for analytics)',
+        description: 'Full trigger source object (enriched data) - includes trigger type, location, configuration. Only populated when "include=triggerSource" query parameter is provided. NULL if not requested to optimize response size.',
         type: () => trigger_source_dto_1.TriggerSourceDTO,
         nullable: true
     }),
@@ -132,7 +132,7 @@ __decorate([
 ], CampaignClaimAnalyticsDTO.prototype, "triggerSource", void 0);
 __decorate([
     (0, swagger_1.ApiProperty)({
-        description: 'Processing status of the claim',
+        description: 'Processing status of the claim lifecycle: PENDING (created, awaiting blockchain), PROCESSING (blockchain transaction in progress), COMPLETED (tokens delivered successfully), FAILED (error occurred). Filter by COMPLETED for successful claims in analytics.',
         enum: enum_1.ProcessRecordStatus,
         example: enum_1.ProcessRecordStatus.COMPLETED
     }),
@@ -140,7 +140,7 @@ __decorate([
 ], CampaignClaimAnalyticsDTO.prototype, "status", void 0);
 __decorate([
     (0, swagger_1.ApiPropertyOptional)({
-        description: 'Country code of user at time of claim',
+        description: 'ISO 3166-1 alpha-2 country code of the user at time of claim (derived from IP geolocation). Used for geographic analytics and compliance reporting.',
         type: String,
         nullable: true,
         example: 'US'
@@ -149,7 +149,7 @@ __decorate([
 ], CampaignClaimAnalyticsDTO.prototype, "userCountryCode", void 0);
 __decorate([
     (0, swagger_1.ApiPropertyOptional)({
-        description: 'Latitude coordinate of claim location',
+        description: 'Latitude coordinate (decimal degrees) of claim location. Combined with longitude for geospatial analytics, heatmaps, and location-based insights. NULL if location not available.',
         type: Number,
         nullable: true,
         example: 47.6062
@@ -158,7 +158,7 @@ __decorate([
 ], CampaignClaimAnalyticsDTO.prototype, "latitude", void 0);
 __decorate([
     (0, swagger_1.ApiPropertyOptional)({
-        description: 'Longitude coordinate of claim location',
+        description: 'Longitude coordinate (decimal degrees) of claim location. Combined with latitude for geospatial analytics, heatmaps, and location-based insights. NULL if location not available.',
         type: Number,
         nullable: true,
         example: -122.3321

package/dist/cjs/shared-lib/dto/analytics/campaign-claim-analytics.dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"campaign-claim-analytics.dto.js","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/campaign-claim-analytics.dto.ts"],"names":[],"mappings":"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"}

package/dist/{esm/shared-lib/dto/transaction → cjs/shared-lib/dto/analytics}/transaction-analytics.request.dto.d.ts

@@ -1,7 +1,7 @@
-import { TransactionDTO } from './transaction.dto';
+import { TransactionDTO } from '../transaction/transaction.dto';
 import { SortOrder } from '../../enum';
 import { AnalyticsGroupByType, AnalyticsMetricType, AnalyticsResultItem } from '../../types/analytics.type';
-import { GroupByExpressionDTO } from '../analytics/group-by-expression.dto';
+import { GroupByExpressionDTO } from './group-by-expression.dto';
 declare const TransactionAnalyticsFiltersDTO_base: import("@nestjs/common").Type<Partial<Omit<TransactionDTO, "createdAt" | "updatedAt">>>;
 /**
  * Type-safe filters for transaction analytics
@@ -36,7 +36,10 @@ export declare class TransactionAnalyticsResponseDTO {
     results: TransactionAnalyticsResultItem[];
     totalGroups: number;
     metadata: {
-        executionTime: string;
+        dateRange?: {
+            startDate: Date;
+            endDate: Date;
+        };
     };
 }
 export type TransactionAnalyticsResultItem = AnalyticsResultItem & {

package/dist/cjs/shared-lib/dto/analytics/transaction-analytics.request.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-analytics.request.dto.d.ts","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/transaction-analytics.request.dto.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,SAAS,EAAoB,MAAM,YAAY,CAAC;AACzD,OAAO,EAA0B,oBAAoB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACpI,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;;AAEjE;;;;GAIG;AACH,qBAAa,8BAA+B,SAAQ,mCAEnD;CAAG;AAEJ;;;GAGG;AACH,qBAAa,8BAA8B;IAkBzC,OAAO,CAAC,EAAE,8BAA8B,CAAC;IAUzC,OAAO,CAAC,EAAE,+BAA+B,EAAE,CAAC;IAkB5C,kBAAkB,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAW5C,OAAO,EAAE,mBAAmB,EAAE,CAAa;IAU3C,MAAM,CAAC,EAAE,mBAAmB,GAAG,+BAA+B,GAAG,MAAM,CAAW;IASlF,SAAS,CAAC,EAAE,SAAS,CAAkB;IAcvC,KAAK,CAAC,EAAE,MAAM,CAAM;IASpB,SAAS,CAAC,EAAE,IAAI,CAAC;IAQjB,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,+BAA+B,GACzC,oBAAoB,GAClB,MAAM,IAAI,CAAC,cAAc,EACrB,WAAW,GAAG,WAAW,GACzB,IAAI,GACJ,iBAAiB,CACpB,CAAC;AAEN;;GAEG;AACH,qBAAa,+BAA+B;IAU1C,OAAO,EAAE,8BAA8B,EAAE,CAAM;IAM/C,WAAW,EAAE,MAAM,CAAK;IAWxB,QAAQ,EAAE;QACR,SAAS,CAAC,EAAE;YACV,SAAS,EAAE,IAAI,CAAC;YAChB,OAAO,EAAE,IAAI,CAAC;SACf,CAAC;KACH,CAAM;CACR;AAED,MAAM,MAAM,8BAA8B,GAAG,mBAAmB,GAAG;KAEhE,CAAC,IAAI,MAAM,IAAI,CAAC,cAAc,EAC3B,IAAI,GACJ,WAAW,GAAG,WAAW,GACzB,iBAAiB,CACpB,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC;CACvB,CAAC"}

package/dist/cjs/shared-lib/dto/{transaction → analytics}/transaction-analytics.request.dto.js

@@ -13,10 +13,10 @@ exports.TransactionAnalyticsResponseDTO = exports.TransactionAnalyticsRequestDTO
 const class_validator_1 = require("class-validator");
 const class_transformer_1 = require("class-transformer");
 const swagger_1 = require("@nestjs/swagger");
-const transaction_dto_1 = require("./transaction.dto");
+const transaction_dto_1 = require("../transaction/transaction.dto");
 const enum_1 = require("../../enum");
 const analytics_type_1 = require("../../types/analytics.type");
-const group_by_expression_dto_1 = require("../analytics/group-by-expression.dto");
+const group_by_expression_dto_1 = require("./group-by-expression.dto");
 /**
  * Type-safe filters for transaction analytics
  * All fields optional via PartialType
@@ -163,9 +163,7 @@ __decorate([
 class TransactionAnalyticsResponseDTO {
     results = [];
     totalGroups = 0;
-    metadata = {
-        executionTime: '0ms'
-    };
+    metadata = {};
 }
 exports.TransactionAnalyticsResponseDTO = TransactionAnalyticsResponseDTO;
 __decorate([
@@ -189,8 +187,13 @@ __decorate([
 ], TransactionAnalyticsResponseDTO.prototype, "totalGroups", void 0);
 __decorate([
     (0, swagger_1.ApiProperty)({
-        description: 'Query execution metadata',
-        example: { executionTime: '45ms' }
+        description: 'Query metadata showing applied filters',
+        example: {
+            dateRange: {
+                startDate: '2024-01-01T00:00:00.000Z',
+                endDate: '2024-12-31T23:59:59.999Z'
+            }
+        }
     }),
     __metadata("design:type", Object)
 ], TransactionAnalyticsResponseDTO.prototype, "metadata", void 0);

package/dist/cjs/shared-lib/dto/analytics/transaction-analytics.request.dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-analytics.request.dto.js","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/transaction-analytics.request.dto.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,qDAA0I;AAC1I,yDAAoD;AACpD,6CAA0F;AAC1F,oEAAgE;AAChE,qCAAyD;AACzD,+DAAoI;AACpI,uEAAiE;AAEjE;;;;GAIG;AACH,MAAa,8BAA+B,SAAQ,IAAA,qBAAW,EAC7D,IAAA,kBAAQ,EAAC,gCAAc,EAAE,CAAC,WAAW,EAAE,WAAW,CAAU,CAAC,CAC9D;CAAG;AAFJ,wEAEI;AAEJ;;;GAGG;AACH,MAAa,8BAA8B;IAEzC,mDAAmD;IAgBnD,OAAO,CAAkC;IAEzC,0CAA0C;IAQ1C,OAAO,CAAqC;IAE5C,+CAA+C;IAgB/C,kBAAkB,CAA0B;IAE5C,kBAAkB;IASlB,OAAO,GAA0B,CAAC,OAAO,CAAC,CAAC;IAE3C,mBAAmB;IAQnB,MAAM,GAAoE,OAAO,CAAC;IASlF,SAAS,GAAe,gBAAS,CAAC,IAAI,CAAC;IAEvC,gBAAgB;IAYhB,KAAK,GAAY,EAAE,CAAC;IAEpB,qBAAqB;IAOrB,SAAS,CAAQ;IAQjB,OAAO,CAAQ;CAChB;AA5GD,wEA4GC;AA1FC;IAfC,IAAA,6BAAmB,EAAC;QACnB,WAAW,EAAE,mFAAmF;QAChG,IAAI,EAAE,8BAA8B;QACpC,OAAO,EAAE;YACP,MAAM,EAAE,WAAW;YACnB,SAAS,EAAE,OAAO;YAClB,kBAAkB,EAAE,MAAM;YAC1B,QAAQ,EAAE,YAAY;YACtB,OAAO,EAAE,CAAC;SACX;KACF,CAAC;IACD,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;IACV,IAAA,gCAAc,GAAE;IAChB,IAAA,wBAAI,EAAC,GAAG,EAAE,CAAC,8BAA8B,CAAC;8BACjC,8BAA8B;+DAAC;AAUzC;IAPC,IAAA,6BAAmB,EAAC;QACnB,WAAW,EAAE,yEAAyE;QACtF,IAAI,EAAE,CAAC,MAAM,CAAC;QACd,OAAO,EAAE,CAAC,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC;KACrD,CAAC;IACD,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,EAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;;+DACmB;AAkB5C;IAfC,IAAA,6BAAmB,EAAC;QACnB,WAAW,EAAE,+DAA+D;QAC5E,IAAI,EAAE,CAAC,8CAAoB,CAAC;QAC5B,OAAO,EAAE;YACP;gBACE,UAAU,EAAE,+BAA+B,uBAAgB,CAAC,IAAI,4CAA4C,uBAAgB,CAAC,IAAI,uBAAuB;gBACxJ,KAAK,EAAE,QAAQ;gBACf,KAAK,EAAE,SAAS;aACjB;SACF;KACF,CAAC;IACD,IAAA,4BAAU,GAAE;IACZ,IAAA,yBAAO,GAAE;IACT,IAAA,gCAAc,EAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC9B,IAAA,wBAAI,EAAC,GAAG,EAAE,CAAC,8CAAoB,CAAC;;0EACW;AAW5C;IARC,IAAA,6BAAmB,EAAC;QACnB,WAAW,EAAE,sBAAsB;QACnC,IAAI,EAAE,uCAAsB;QAC5B,OAAO,EAAE,CAAC,OAAO,CAAC;KACnB,CAAC;IACD,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,EAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACxB,IAAA,sBAAI,EAAC,uCAAsB,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;;+DACF;AAU3C;IAPC,IAAA,6BAAmB,EAAC;QACnB,WAAW,EAAE,yDAAyD;QACtE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,GAAG,uCAAsB,EAAE,WAAW,CAAC,EAAE,CAAC;QAC/E,OAAO,EAAE,OAAO;KACjB,CAAC;IACD,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;;8DACuE;AASlF;IAPC,IAAA,6BAAmB,EAAC;QACnB,WAAW,EAAE,iBAAiB;QAC9B,IAAI,EAAE,gBAAS;QACf,OAAO,EAAE,gBAAS,CAAC,IAAI;KACxB,CAAC;IACD,IAAA,4BAAU,GAAE;IACZ,IAAA,wBAAM,EAAC,gBAAS,CAAC;;iEACqB;AAcvC;IAXC,IAAA,6BAAmB,EAAC;QACnB,WAAW,EAAE,qCAAqC;QAClD,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,GAAG;QACZ,OAAO,EAAE,EAAE;KACZ,CAAC;IACD,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;IACV,IAAA,qBAAG,EAAC,CAAC,CAAC;IACN,IAAA,qBAAG,EAAC,GAAG,CAAC;IACR,IAAA,6BAAS,EAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;;6DACtB;AASpB;IANC,IAAA,6BAAmB,EAAC;QACnB,WAAW,EAAE,uCAAuC;QACpD,OAAO,EAAE,0BAA0B;KACpC,CAAC;IACD,IAAA,4BAAU,GAAE;IACZ,IAAA,8BAAY,GAAE;8BACH,IAAI;iEAAC;AAQjB;IANC,IAAA,6BAAmB,EAAC;QACnB,WAAW,EAAE,qCAAqC;QAClD,OAAO,EAAE,0BAA0B;KACpC,CAAC;IACD,IAAA,4BAAU,GAAE;IACZ,IAAA,8BAAY,GAAE;8BACL,IAAI;+DAAC;AAcjB;;GAEG;AACH,MAAa,+BAA+B;IAU1C,OAAO,GAAqC,EAAE,CAAC;IAM/C,WAAW,GAAW,CAAC,CAAC;IAWxB,QAAQ,GAKJ,EAAE,CAAC;CACR;AAjCD,0EAiCC;AAvBC;IATC,IAAA,qBAAW,EAAC;QACX,WAAW,EAAE,oEAAoE;QACjF,IAAI,EAAE,OAAO;QACb,OAAO,EAAE;YACP,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,EAAE;YACjC,EAAE,WAAW,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,EAAE;YACzC,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,0BAA0B,EAAE;SACtE;KACF,CAAC;;gEAC6C;AAM/C;IAJC,IAAA,qBAAW,EAAC;QACX,WAAW,EAAE,+BAA+B;QAC5C,OAAO,EAAE,CAAC;KACX,CAAC;;oEACsB;AAWxB;IATC,IAAA,qBAAW,EAAC;QACX,WAAW,EAAE,wCAAwC;QACrD,OAAO,EAAE;YACP,SAAS,EAAE;gBACT,SAAS,EAAE,0BAA0B;gBACrC,OAAO,EAAE,0BAA0B;aACpC;SACF;KACF,CAAC;;iEAMK"}

package/dist/cjs/shared-lib/dto/{user-analytics.dto.d.ts → analytics/user-analytics.dto.d.ts}

@@ -1,13 +1,24 @@
+/**
+ * USER ANALYTICS FILTERS DTO
+ *
+ * Filters to scope user analytics aggregations.
+ * Determines which users/activity to include in calculations.
+ */
+export declare class UserAnalyticsFiltersDTO {
+    businessId?: string;
+}
 /**
  * USER ANALYTICS REQUEST DTO
  *
- * Filters for user analytics queries.
- * Supports date range filtering and business-specific analytics.
+ * Request structure for user engagement analytics.
+ * Supports date range filtering and business-specific scoping.
+ *
+ * Pattern matches TransactionAnalyticsRequestDTO and CampaignClaimAnalyticsRequestDTO for consistency.
  */
 export declare class UserAnalyticsRequestDTO {
+    filters?: UserAnalyticsFiltersDTO;
     startDate?: Date;
     endDate?: Date;
-    businessId?: string;
 }
 /**
  * USER ANALYTICS RESPONSE DTO
@@ -26,6 +37,9 @@ export declare class UserAnalyticsResponseDTO {
     totalTransactionVolume: number;
     averageClaimsPerUser: number;
     averageRedemptionsPerUser: number;
+    averageTransactionsPerActiveUser: number;
+    averageClaimsPerActiveUser: number;
+    averageRedemptionsPerActiveUser: number;
     engagementRate: number;
     periodBreakdown?: {
         date: string;
@@ -33,7 +47,6 @@ export declare class UserAnalyticsResponseDTO {
         newUsers: number;
     }[];
     metadata: {
-        executionTimeMs: number;
         dateRange?: {
             startDate: Date;
             endDate: Date;

package/dist/cjs/shared-lib/dto/analytics/user-analytics.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-analytics.dto.d.ts","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/user-analytics.dto.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,qBAAa,uBAAuB;IASlC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,qBAAa,uBAAuB;IAWlC,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAQlC,SAAS,CAAC,EAAE,IAAI,CAAC;IAQjB,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,qBAAa,wBAAwB;IAKnC,UAAU,EAAE,MAAM,CAAK;IAMvB,WAAW,EAAE,MAAM,CAAK;IAMxB,QAAQ,EAAE,MAAM,CAAK;IAMrB,0BAA0B,EAAE,MAAM,CAAK;IAMvC,wBAAwB,EAAE,MAAM,CAAK;IAMrC,sBAAsB,EAAE,MAAM,CAAK;IAMnC,oBAAoB,EAAE,MAAM,CAAK;IAMjC,yBAAyB,EAAE,MAAM,CAAK;IAMtC,gCAAgC,EAAE,MAAM,CAAK;IAM7C,0BAA0B,EAAE,MAAM,CAAK;IAMvC,+BAA+B,EAAE,MAAM,CAAK;IAO5C,cAAc,EAAE,MAAM,CAAK;IAc3B,eAAe,CAAC,EAAE;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;KAClB,EAAE,CAAC;IAgBJ,QAAQ,EAAE;QACR,SAAS,CAAC,EAAE;YACV,SAAS,EAAE,IAAI,CAAC;YAChB,OAAO,EAAE,IAAI,CAAC;SACf,CAAC;KACH,CAAM;CACR"}

package/dist/cjs/shared-lib/dto/analytics/user-analytics.dto.js

@@ -0,0 +1,224 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserAnalyticsResponseDTO = exports.UserAnalyticsRequestDTO = exports.UserAnalyticsFiltersDTO = void 0;
+const swagger_1 = require("@nestjs/swagger");
+const class_validator_1 = require("class-validator");
+const class_transformer_1 = require("class-transformer");
+/**
+ * USER ANALYTICS FILTERS DTO
+ *
+ * Filters to scope user analytics aggregations.
+ * Determines which users/activity to include in calculations.
+ */
+class UserAnalyticsFiltersDTO {
+    businessId;
+}
+exports.UserAnalyticsFiltersDTO = UserAnalyticsFiltersDTO;
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Filter analytics to specific business (filters transactions, claims, redemptions by businessId)',
+        type: String,
+        format: 'uuid',
+        example: 'biz-uuid-123'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], UserAnalyticsFiltersDTO.prototype, "businessId", void 0);
+/**
+ * USER ANALYTICS REQUEST DTO
+ *
+ * Request structure for user engagement analytics.
+ * Supports date range filtering and business-specific scoping.
+ *
+ * Pattern matches TransactionAnalyticsRequestDTO and CampaignClaimAnalyticsRequestDTO for consistency.
+ */
+class UserAnalyticsRequestDTO {
+    filters;
+    startDate;
+    endDate;
+}
+exports.UserAnalyticsRequestDTO = UserAnalyticsRequestDTO;
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Filters to scope which users/activity to include in analytics',
+        type: UserAnalyticsFiltersDTO,
+        example: {
+            businessId: 'biz-uuid-123'
+        }
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.ValidateNested)(),
+    (0, class_transformer_1.Type)(() => UserAnalyticsFiltersDTO),
+    __metadata("design:type", UserAnalyticsFiltersDTO)
+], UserAnalyticsRequestDTO.prototype, "filters", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Start date for filtering activity and new users (ISO 8601 format). Filters transactions, claims, redemptions, and user creation dates.',
+        example: '2024-01-01T00:00:00Z'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", Date)
+], UserAnalyticsRequestDTO.prototype, "startDate", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'End date for filtering activity and new users (ISO 8601 format). Filters transactions, claims, redemptions, and user creation dates.',
+        example: '2024-12-31T23:59:59Z'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", Date)
+], UserAnalyticsRequestDTO.prototype, "endDate", void 0);
+/**
+ * USER ANALYTICS RESPONSE DTO
+ *
+ * Aggregated user statistics and metrics.
+ * Uses ONLY database-stored data (user, transaction, campaign_user_claim tables).
+ *
+ * NOTE: Does NOT include blockchain balance data (fetched on-demand via Web3, not stored in DB).
+ */
+class UserAnalyticsResponseDTO {
+    totalUsers = 0;
+    activeUsers = 0;
+    newUsers = 0;
+    averageTransactionsPerUser = 0;
+    averageTransactionAmount = 0;
+    totalTransactionVolume = 0;
+    averageClaimsPerUser = 0;
+    averageRedemptionsPerUser = 0;
+    averageTransactionsPerActiveUser = 0;
+    averageClaimsPerActiveUser = 0;
+    averageRedemptionsPerActiveUser = 0;
+    engagementRate = 0;
+    periodBreakdown;
+    metadata = {};
+}
+exports.UserAnalyticsResponseDTO = UserAnalyticsResponseDTO;
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Total number of registered users (all-time, no date filter applied). Includes all non-deleted users regardless of activity.',
+        example: 10523
+    }),
+    __metadata("design:type", Number)
+], UserAnalyticsResponseDTO.prototype, "totalUsers", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Number of active users - users with ≥1 successful transaction (status=succeeded), completed claim (status=COMPLETED), or completed redemption (status=COMPLETED) within the specified date range. If no date range provided, counts users with any activity ever.',
+        example: 3241
+    }),
+    __metadata("design:type", Number)
+], UserAnalyticsResponseDTO.prototype, "activeUsers", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Number of new users created within the specified date range (filtered by user.createdAt). If no date range provided, equals totalUsers.',
+        example: 156
+    }),
+    __metadata("design:type", Number)
+], UserAnalyticsResponseDTO.prototype, "newUsers", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Average transactions per user across entire user base (total successful transactions in date range ÷ total users). Only counts transactions with status=succeeded, excludes REDEMPTION_SPEND and REDEMPTION_RECEIVE types to prevent double-counting.',
+        example: 12.5
+    }),
+    __metadata("design:type", Number)
+], UserAnalyticsResponseDTO.prototype, "averageTransactionsPerUser", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Average amount per transaction (total transaction volume ÷ transaction count). Only includes successful transactions (status=succeeded) in date range.',
+        example: 45.67
+    }),
+    __metadata("design:type", Number)
+], UserAnalyticsResponseDTO.prototype, "averageTransactionAmount", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Total transaction volume - sum of all successful transaction amounts (status=succeeded) in date range. Excludes REDEMPTION_SPEND and REDEMPTION_RECEIVE types.',
+        example: 56789.12
+    }),
+    __metadata("design:type", Number)
+], UserAnalyticsResponseDTO.prototype, "totalTransactionVolume", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Average claims per user across entire user base (total completed claims in date range ÷ total users). Only counts claims with status=COMPLETED.',
+        example: 3.2
+    }),
+    __metadata("design:type", Number)
+], UserAnalyticsResponseDTO.prototype, "averageClaimsPerUser", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Average redemptions per user across entire user base (total completed redemptions in date range ÷ total users). Only counts redemptions with status=COMPLETED.',
+        example: 1.8
+    }),
+    __metadata("design:type", Number)
+], UserAnalyticsResponseDTO.prototype, "averageRedemptionsPerUser", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Average transactions per active user (total successful transactions in date range ÷ active users in date range). Provides more accurate engagement metric than averageTransactionsPerUser by excluding inactive users.',
+        example: 15.3
+    }),
+    __metadata("design:type", Number)
+], UserAnalyticsResponseDTO.prototype, "averageTransactionsPerActiveUser", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Average claims per active user (total completed claims in date range ÷ active users in date range). Shows claim activity concentrated among engaged users.',
+        example: 4.7
+    }),
+    __metadata("design:type", Number)
+], UserAnalyticsResponseDTO.prototype, "averageClaimsPerActiveUser", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Average redemptions per active user (total completed redemptions in date range ÷ active users in date range). Shows redemption activity concentrated among engaged users.',
+        example: 2.1
+    }),
+    __metadata("design:type", Number)
+], UserAnalyticsResponseDTO.prototype, "averageRedemptionsPerActiveUser", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'User engagement rate as percentage (activeUsers ÷ totalUsers × 100). Indicates what percentage of all registered users had activity in the date range.',
+        example: 30.79,
+        type: 'number'
+    }),
+    __metadata("design:type", Number)
+], UserAnalyticsResponseDTO.prototype, "engagementRate", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Breakdown by time period (if requested)',
+        type: 'array',
+        items: {
+            type: 'object',
+            properties: {
+                date: { type: 'string', example: '2024-01-01' },
+                activeUsers: { type: 'number', example: 245 },
+                newUsers: { type: 'number', example: 12 }
+            }
+        }
+    }),
+    __metadata("design:type", Array)
+], UserAnalyticsResponseDTO.prototype, "periodBreakdown", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Query metadata showing applied filters',
+        type: 'object',
+        properties: {
+            dateRange: {
+                type: 'object',
+                properties: {
+                    startDate: { type: 'string', format: 'date-time' },
+                    endDate: { type: 'string', format: 'date-time' }
+                },
+                description: 'Applied date range filter (only present if startDate or endDate was provided)'
+            }
+        }
+    }),
+    __metadata("design:type", Object)
+], UserAnalyticsResponseDTO.prototype, "metadata", void 0);
+//# sourceMappingURL=user-analytics.dto.js.map

package/dist/cjs/shared-lib/dto/analytics/user-analytics.dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-analytics.dto.js","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/user-analytics.dto.ts"],"names":[],"mappings":"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"}

package/dist/cjs/shared-lib/dto/campaign/campaign-claim-analytics-request.dto.d.ts

@@ -1,4 +1,4 @@
-import { CampaignClaimAnalyticsDTO } from './campaign-claim-analytics.dto';
+import { CampaignClaimAnalyticsDTO } from '../analytics/campaign-claim-analytics.dto';
 import { SortOrder } from '../../enum';
 import { AnalyticsGroupByType, AnalyticsMetricType, AnalyticsResultItem } from '../../types/analytics.type';
 import { GroupByExpressionDTO } from '../analytics/group-by-expression.dto';
@@ -57,7 +57,10 @@ export declare class CampaignClaimAnalyticsResponseDTO {
     results: CampaignClaimAnalyticsResultItem[];
     totalGroups: number;
     metadata: {
-        executionTime: string;
+        dateRange?: {
+            startDate: Date;
+            endDate: Date;
+        };
     };
 }
 export type CampaignClaimAnalyticsResultItem = AnalyticsResultItem & {