@explorins/pers-shared 2.1.84 → 2.1.86

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

@@ -0,0 +1,57 @@
+import { SortOrder } from '../../..';
+import type { NativeTokenType } from '../../types/native-token.type';
+import { BaseAnalyticsMetadata } from './base-analytics.dto';
+/**
+ * BUSINESS RANKING ANALYTICS DTOs
+ *
+ * Domain: Analytics (Cross-Domain Query)
+ * Purpose: Server-side aggregation of business transaction rankings
+ *
+ * Replaces:
+ * - Dual queries (modern + legacy business transactions)
+ * - Client-side merging logic in business-balances.component.ts
+ *
+ * Performance Impact:
+ * - 2 API calls → 1 API call (50% reduction)
+ * - ~60 lines removed from frontend
+ * - Server-side JOIN optimization
+ */
+export declare class BusinessRankingFiltersDTO {
+    businessId?: string;
+    tokenType?: NativeTokenType;
+}
+export declare class BusinessRankingAnalyticsRequestDTO {
+    filters?: BusinessRankingFiltersDTO;
+    sortBy?: 'totalTransactions' | 'tokenReceived' | 'businessId' | 'businessName';
+    sortOrder?: SortOrder;
+    limit?: number;
+    startDate?: Date;
+    endDate?: Date;
+}
+export declare class BusinessRankingResultItemDTO {
+    businessId: string | null;
+    businessName: string | null;
+    displayName: string | null;
+    accountAddress: string | null;
+    totalTransactions: number;
+    tokenReceived: number;
+    hasLegacyTransactions?: boolean;
+}
+export declare class BusinessRankingAnalyticsResponseDTO {
+    results: BusinessRankingResultItemDTO[];
+    totalBusinesses: number;
+    metadata: BaseAnalyticsMetadata & {
+        /**
+         * Token type used for filtering (if provided in request)
+         */
+        tokenType?: NativeTokenType;
+        /**
+         * Sort configuration applied
+         */
+        sorting?: {
+            sortBy: string;
+            sortOrder: SortOrder;
+        };
+    };
+}
+//# sourceMappingURL=business-ranking-analytics.dto.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"business-ranking-analytics.dto.d.ts","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/business-ranking-analytics.dto.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAErE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;;;;;;GAcG;AAIH,qBAAa,yBAAyB;IASpC,UAAU,CAAC,EAAE,MAAM,CAAC;IASpB,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAID,qBAAa,kCAAkC;IAQ7C,OAAO,CAAC,EAAE,yBAAyB,CAAC;IAUpC,MAAM,CAAC,EAAE,mBAAmB,GAAG,eAAe,GAAG,YAAY,GAAG,cAAc,CAAC;IAU/E,SAAS,CAAC,EAAE,SAAS,CAAC;IAatB,KAAK,CAAC,EAAE,MAAM,CAAC;IAQf,SAAS,CAAC,EAAE,IAAI,CAAC;IAQjB,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAID,qBAAa,4BAA4B;IAMvC,UAAU,EAAG,MAAM,GAAG,IAAI,CAAC;IAO3B,YAAY,EAAG,MAAM,GAAG,IAAI,CAAC;IAO7B,WAAW,EAAG,MAAM,GAAG,IAAI,CAAC;IAO5B,cAAc,EAAG,MAAM,GAAG,IAAI,CAAC;IAM/B,iBAAiB,EAAG,MAAM,CAAC;IAM3B,aAAa,EAAG,MAAM,CAAC;IAMvB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAID,qBAAa,mCAAmC;IAK9C,OAAO,EAAG,4BAA4B,EAAE,CAAC;IAMzC,eAAe,EAAG,MAAM,CAAC;IAMzB,QAAQ,EAAG,qBAAqB,GAAG;QACjC;;WAEG;QACH,SAAS,CAAC,EAAE,eAAe,CAAC;QAE5B;;WAEG;QACH,OAAO,CAAC,EAAE;YACR,MAAM,EAAE,MAAM,CAAC;YACf,SAAS,EAAE,SAAS,CAAC;SACtB,CAAC;KACH,CAAC;CACH"}

package/dist/cjs/shared-lib/dto/analytics/business-ranking-analytics.dto.js

@@ -0,0 +1,226 @@
+"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.BusinessRankingAnalyticsResponseDTO = exports.BusinessRankingResultItemDTO = exports.BusinessRankingAnalyticsRequestDTO = exports.BusinessRankingFiltersDTO = void 0;
+const class_validator_1 = require("class-validator");
+const class_transformer_1 = require("class-transformer");
+const swagger_1 = require("@nestjs/swagger");
+const __1 = require("../../..");
+const native_token_type_1 = require("../../types/native-token.type");
+/**
+ * BUSINESS RANKING ANALYTICS DTOs
+ *
+ * Domain: Analytics (Cross-Domain Query)
+ * Purpose: Server-side aggregation of business transaction rankings
+ *
+ * Replaces:
+ * - Dual queries (modern + legacy business transactions)
+ * - Client-side merging logic in business-balances.component.ts
+ *
+ * Performance Impact:
+ * - 2 API calls → 1 API call (50% reduction)
+ * - ~60 lines removed from frontend
+ * - Server-side JOIN optimization
+ */
+// ========== FILTERS ==========
+class BusinessRankingFiltersDTO {
+    businessId;
+    tokenType;
+}
+exports.BusinessRankingFiltersDTO = BusinessRankingFiltersDTO;
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Filter to specific business by ID',
+        type: String,
+        format: 'uuid',
+        example: 'biz-uuid-123'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], BusinessRankingFiltersDTO.prototype, "businessId", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Filter by specific token type',
+        enum: native_token_type_1.NativeTokenTypes,
+        example: native_token_type_1.NativeTokenTypes.ERC721
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(native_token_type_1.NativeTokenTypes),
+    __metadata("design:type", String)
+], BusinessRankingFiltersDTO.prototype, "tokenType", void 0);
+// ========== REQUEST ==========
+class BusinessRankingAnalyticsRequestDTO {
+    filters;
+    sortBy;
+    sortOrder;
+    limit;
+    startDate;
+    endDate;
+}
+exports.BusinessRankingAnalyticsRequestDTO = BusinessRankingAnalyticsRequestDTO;
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Filters for business ranking query',
+        type: BusinessRankingFiltersDTO
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.ValidateNested)(),
+    (0, class_transformer_1.Type)(() => BusinessRankingFiltersDTO),
+    __metadata("design:type", BusinessRankingFiltersDTO)
+], BusinessRankingAnalyticsRequestDTO.prototype, "filters", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Field to sort results by',
+        enum: ['totalTransactions', 'tokenReceived', 'businessId', 'businessName'],
+        default: 'totalTransactions',
+        example: 'totalTransactions'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], BusinessRankingAnalyticsRequestDTO.prototype, "sortBy", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Sort order (ASC or DESC)',
+        enum: __1.SortOrder,
+        default: __1.SortOrder.DESC,
+        example: __1.SortOrder.DESC
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(__1.SortOrder),
+    __metadata("design:type", String)
+], BusinessRankingAnalyticsRequestDTO.prototype, "sortOrder", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Maximum number of results to return',
+        minimum: 1,
+        maximum: 1000,
+        default: 50,
+        example: 50
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(1000),
+    __metadata("design:type", Number)
+], BusinessRankingAnalyticsRequestDTO.prototype, "limit", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Start date for filtering transactions (ISO 8601)',
+        example: '2026-01-01T00:00:00Z'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", Date)
+], BusinessRankingAnalyticsRequestDTO.prototype, "startDate", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'End date for filtering transactions (ISO 8601)',
+        example: '2026-02-01T00:00:00Z'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", Date)
+], BusinessRankingAnalyticsRequestDTO.prototype, "endDate", void 0);
+// ========== RESULT ITEM ==========
+class BusinessRankingResultItemDTO {
+    businessId;
+    businessName;
+    displayName;
+    accountAddress;
+    totalTransactions;
+    tokenReceived;
+    hasLegacyTransactions;
+}
+exports.BusinessRankingResultItemDTO = BusinessRankingResultItemDTO;
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Business UUID (null for unidentified businesses)',
+        nullable: true,
+        example: '123e4567-e89b-12d3-a456-426614174000'
+    }),
+    __metadata("design:type", Object)
+], BusinessRankingResultItemDTO.prototype, "businessId", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Business name',
+        nullable: true,
+        example: 'Acme Coffee Shop'
+    }),
+    __metadata("design:type", Object)
+], BusinessRankingResultItemDTO.prototype, "businessName", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Business display name',
+        nullable: true,
+        example: 'Acme Coffee'
+    }),
+    __metadata("design:type", Object)
+], BusinessRankingResultItemDTO.prototype, "displayName", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Business blockchain account address',
+        nullable: true,
+        example: '0x1234567890abcdef...'
+    }),
+    __metadata("design:type", Object)
+], BusinessRankingResultItemDTO.prototype, "accountAddress", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Total number of successful transactions received',
+        example: 150
+    }),
+    __metadata("design:type", Number)
+], BusinessRankingResultItemDTO.prototype, "totalTransactions", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Total token amount received',
+        example: 1500.50
+    }),
+    __metadata("design:type", Number)
+], BusinessRankingResultItemDTO.prototype, "tokenReceived", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Whether this business has legacy transactions (address-based)',
+        example: false
+    }),
+    __metadata("design:type", Boolean)
+], BusinessRankingResultItemDTO.prototype, "hasLegacyTransactions", void 0);
+// ========== RESPONSE ==========
+class BusinessRankingAnalyticsResponseDTO {
+    results;
+    totalBusinesses;
+    metadata;
+}
+exports.BusinessRankingAnalyticsResponseDTO = BusinessRankingAnalyticsResponseDTO;
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Array of business ranking results',
+        type: [BusinessRankingResultItemDTO]
+    }),
+    __metadata("design:type", Array)
+], BusinessRankingAnalyticsResponseDTO.prototype, "results", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Total number of businesses in results',
+        example: 25
+    }),
+    __metadata("design:type", Number)
+], BusinessRankingAnalyticsResponseDTO.prototype, "totalBusinesses", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Query metadata',
+        type: 'object'
+    }),
+    __metadata("design:type", Object)
+], BusinessRankingAnalyticsResponseDTO.prototype, "metadata", void 0);
+//# sourceMappingURL=business-ranking-analytics.dto.js.map

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

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

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

@@ -1,5 +1,7 @@
 export * from './base-analytics.dto';
+export * from './business-ranking-analytics.dto';
 export * from './group-by-expression.dto';
+export * from './retention-analytics.dto';
 export * from './usage-analytics.dto';
 export * from './user-ranking-analytics.dto';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/index.ts"],"names":[],"mappings":"AAEA,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/index.ts"],"names":[],"mappings":"AAEA,cAAc,sBAAsB,CAAC;AACrC,cAAc,kCAAkC,CAAC;AACjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC"}

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

@@ -15,7 +15,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./base-analytics.dto"), exports);
+__exportStar(require("./business-ranking-analytics.dto"), exports);
 __exportStar(require("./group-by-expression.dto"), exports);
+__exportStar(require("./retention-analytics.dto"), exports);
 __exportStar(require("./usage-analytics.dto"), exports);
 __exportStar(require("./user-ranking-analytics.dto"), exports);
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAEA,uDAAqC;AACrC,4DAA0C;AAC1C,wDAAsC;AACtC,+DAA6C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAEA,uDAAqC;AACrC,mEAAiD;AACjD,4DAA0C;AAC1C,4DAA0C;AAC1C,wDAAsC;AACtC,+DAA6C"}

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

@@ -0,0 +1,65 @@
+import type { NativeTokenType } from '../../types/native-token.type';
+import { BaseAnalyticsMetadata } from './base-analytics.dto';
+/**
+ * RETENTION ANALYTICS DTOs
+ *
+ * Domain: Analytics (Cross-Domain Query)
+ * Purpose: Server-side monthly retention calculations
+ *
+ * Replaces:
+ * - 13 separate API calls (one per month)
+ * - Client-side forkJoin aggregation
+ * - Manual month generation logic
+ *
+ * Performance Impact:
+ * - 13 API calls → 1 API call (92% reduction)
+ * - ~1350ms → ~105ms load time (92% faster)
+ * - ~260KB → ~40KB payload (85% smaller)
+ */
+export declare class RetentionAnalyticsFiltersDTO {
+    tokenType?: NativeTokenType;
+    triggerProcessType?: string;
+}
+export declare class RetentionAnalyticsRequestDTO {
+    startMonth?: Date;
+    monthsBack?: number;
+    filters?: RetentionAnalyticsFiltersDTO;
+}
+/**
+ * Retention data for a month offset within a cohort
+ * Tracks how many users from the original cohort are still active
+ */
+export declare class CohortRetentionMonthDTO {
+    retainedUsers: number;
+    retentionRate: number;
+}
+/**
+ * Cohort retention result for a single month
+ * Contains the cohort (new users in month) and their retention over subsequent months
+ */
+export declare class RetentionMonthResultDTO {
+    monthKey: string;
+    startDate: Date;
+    endDate: Date;
+    cohortSize: number;
+    monthlyRetention: {
+        [monthOffset: string]: CohortRetentionMonthDTO;
+    };
+    byTriggerType?: {
+        [key: string]: {
+            count: number;
+            uniqueUsers: number;
+        };
+    };
+}
+export declare class RetentionAnalyticsResponseDTO {
+    results: RetentionMonthResultDTO[];
+    totalMonths: number;
+    metadata: BaseAnalyticsMetadata & {
+        /**
+         * Calculation method used for retention analysis
+         */
+        calculationMethod: 'monthly-cohort';
+    };
+}
+//# sourceMappingURL=retention-analytics.dto.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retention-analytics.dto.d.ts","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/retention-analytics.dto.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAErE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AAIH,qBAAa,4BAA4B;IAQvC,SAAS,CAAC,EAAE,eAAe,CAAC;IAQ5B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID,qBAAa,4BAA4B;IAOvC,UAAU,CAAC,EAAE,IAAI,CAAC;IAalB,UAAU,CAAC,EAAE,MAAM,CAAC;IASpB,OAAO,CAAC,EAAE,4BAA4B,CAAC;CACxC;AAID;;;GAGG;AACH,qBAAa,uBAAuB;IAKlC,aAAa,EAAG,MAAM,CAAC;IAMvB,aAAa,EAAG,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,qBAAa,uBAAuB;IAKlC,QAAQ,EAAG,MAAM,CAAC;IAMlB,SAAS,EAAG,IAAI,CAAC;IAMjB,OAAO,EAAG,IAAI,CAAC;IAMf,UAAU,EAAG,MAAM,CAAC;IAWpB,gBAAgB,EAAG;QACjB,CAAC,WAAW,EAAE,MAAM,GAAG,uBAAuB,CAAC;KAChD,CAAC;IASF,aAAa,CAAC,EAAE;QACd,CAAC,GAAG,EAAE,MAAM,GAAG;YACb,KAAK,EAAE,MAAM,CAAC;YACd,WAAW,EAAE,MAAM,CAAC;SACrB,CAAC;KACH,CAAC;CACH;AAID,qBAAa,6BAA6B;IAKxC,OAAO,EAAG,uBAAuB,EAAE,CAAC;IAMpC,WAAW,EAAG,MAAM,CAAC;IAMrB,QAAQ,EAAG,qBAAqB,GAAG;QACjC;;WAEG;QACH,iBAAiB,EAAE,gBAAgB,CAAC;KACrC,CAAC;CACH"}

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

@@ -0,0 +1,213 @@
+"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.RetentionAnalyticsResponseDTO = exports.RetentionMonthResultDTO = exports.CohortRetentionMonthDTO = exports.RetentionAnalyticsRequestDTO = exports.RetentionAnalyticsFiltersDTO = void 0;
+const class_validator_1 = require("class-validator");
+const class_transformer_1 = require("class-transformer");
+const swagger_1 = require("@nestjs/swagger");
+const native_token_type_1 = require("../../types/native-token.type");
+/**
+ * RETENTION ANALYTICS DTOs
+ *
+ * Domain: Analytics (Cross-Domain Query)
+ * Purpose: Server-side monthly retention calculations
+ *
+ * Replaces:
+ * - 13 separate API calls (one per month)
+ * - Client-side forkJoin aggregation
+ * - Manual month generation logic
+ *
+ * Performance Impact:
+ * - 13 API calls → 1 API call (92% reduction)
+ * - ~1350ms → ~105ms load time (92% faster)
+ * - ~260KB → ~40KB payload (85% smaller)
+ */
+// ========== REQUEST FILTERS ==========
+class RetentionAnalyticsFiltersDTO {
+    tokenType;
+    triggerProcessType;
+}
+exports.RetentionAnalyticsFiltersDTO = RetentionAnalyticsFiltersDTO;
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Filter by specific token type',
+        enum: native_token_type_1.NativeTokenTypes,
+        example: native_token_type_1.NativeTokenTypes.ERC721
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(native_token_type_1.NativeTokenTypes),
+    __metadata("design:type", String)
+], RetentionAnalyticsFiltersDTO.prototype, "tokenType", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Filter by trigger process type',
+        example: 'PURCHASE'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], RetentionAnalyticsFiltersDTO.prototype, "triggerProcessType", void 0);
+// ========== REQUEST ==========
+class RetentionAnalyticsRequestDTO {
+    startMonth;
+    monthsBack;
+    filters;
+}
+exports.RetentionAnalyticsRequestDTO = RetentionAnalyticsRequestDTO;
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Starting month for retention analysis (defaults to current month)',
+        example: '2026-02-01T00:00:00Z'
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsDateString)(),
+    __metadata("design:type", Date)
+], RetentionAnalyticsRequestDTO.prototype, "startMonth", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Number of months to analyze (looking backwards)',
+        minimum: 1,
+        maximum: 24,
+        default: 13,
+        example: 13
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    (0, class_validator_1.Max)(24),
+    __metadata("design:type", Number)
+], RetentionAnalyticsRequestDTO.prototype, "monthsBack", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Optional filters for retention query',
+        type: RetentionAnalyticsFiltersDTO
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.ValidateNested)(),
+    (0, class_transformer_1.Type)(() => RetentionAnalyticsFiltersDTO),
+    __metadata("design:type", RetentionAnalyticsFiltersDTO)
+], RetentionAnalyticsRequestDTO.prototype, "filters", void 0);
+// ========== MONTH RESULT ==========
+/**
+ * Retention data for a month offset within a cohort
+ * Tracks how many users from the original cohort are still active
+ */
+class CohortRetentionMonthDTO {
+    retainedUsers;
+    retentionRate;
+}
+exports.CohortRetentionMonthDTO = CohortRetentionMonthDTO;
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Number of users from original cohort still active in this month offset',
+        example: 85
+    }),
+    __metadata("design:type", Number)
+], CohortRetentionMonthDTO.prototype, "retainedUsers", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Retention rate: (retainedUsers / cohortSize) * 100',
+        example: 70.8
+    }),
+    __metadata("design:type", Number)
+], CohortRetentionMonthDTO.prototype, "retentionRate", void 0);
+/**
+ * Cohort retention result for a single month
+ * Contains the cohort (new users in month) and their retention over subsequent months
+ */
+class RetentionMonthResultDTO {
+    monthKey;
+    startDate;
+    endDate;
+    cohortSize;
+    monthlyRetention;
+    byTriggerType;
+}
+exports.RetentionMonthResultDTO = RetentionMonthResultDTO;
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Month identifier in YYYY-MM format',
+        example: '2026-02'
+    }),
+    __metadata("design:type", String)
+], RetentionMonthResultDTO.prototype, "monthKey", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Start date of the month',
+        example: '2026-02-01T00:00:00Z'
+    }),
+    __metadata("design:type", Date)
+], RetentionMonthResultDTO.prototype, "startDate", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'End date of the month',
+        example: '2026-03-01T00:00:00Z'
+    }),
+    __metadata("design:type", Date)
+], RetentionMonthResultDTO.prototype, "endDate", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Number of users who made their first transaction in this month (cohort size)',
+        example: 120
+    }),
+    __metadata("design:type", Number)
+], RetentionMonthResultDTO.prototype, "cohortSize", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Retention data for this cohort over subsequent months. Key is month offset (0=same month, 1=next month, 2=2 months later, etc.)',
+        type: 'object',
+        example: {
+            '0': { retainedUsers: 120, retentionRate: 100 },
+            '1': { retainedUsers: 85, retentionRate: 70.8 },
+            '2': { retainedUsers: 65, retentionRate: 54.2 }
+        }
+    }),
+    __metadata("design:type", Object)
+], RetentionMonthResultDTO.prototype, "monthlyRetention", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Breakdown of transactions by trigger type',
+        example: {
+            PURCHASE: { count: 800, uniqueUsers: 300 },
+            REWARD: { count: 450, uniqueUsers: 200 }
+        }
+    }),
+    __metadata("design:type", Object)
+], RetentionMonthResultDTO.prototype, "byTriggerType", void 0);
+// ========== RESPONSE ==========
+class RetentionAnalyticsResponseDTO {
+    results;
+    totalMonths;
+    metadata;
+}
+exports.RetentionAnalyticsResponseDTO = RetentionAnalyticsResponseDTO;
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Array of monthly retention results (ordered chronologically)',
+        type: [RetentionMonthResultDTO]
+    }),
+    __metadata("design:type", Array)
+], RetentionAnalyticsResponseDTO.prototype, "results", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Total number of months analyzed',
+        example: 13
+    }),
+    __metadata("design:type", Number)
+], RetentionAnalyticsResponseDTO.prototype, "totalMonths", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Query metadata',
+        type: 'object'
+    }),
+    __metadata("design:type", Object)
+], RetentionAnalyticsResponseDTO.prototype, "metadata", void 0);
+//# sourceMappingURL=retention-analytics.dto.js.map

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

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

package/dist/esm/shared-lib/dto/analytics/business-ranking-analytics.dto.d.ts

@@ -0,0 +1,57 @@
+import { SortOrder } from '../../..';
+import type { NativeTokenType } from '../../types/native-token.type';
+import { BaseAnalyticsMetadata } from './base-analytics.dto';
+/**
+ * BUSINESS RANKING ANALYTICS DTOs
+ *
+ * Domain: Analytics (Cross-Domain Query)
+ * Purpose: Server-side aggregation of business transaction rankings
+ *
+ * Replaces:
+ * - Dual queries (modern + legacy business transactions)
+ * - Client-side merging logic in business-balances.component.ts
+ *
+ * Performance Impact:
+ * - 2 API calls → 1 API call (50% reduction)
+ * - ~60 lines removed from frontend
+ * - Server-side JOIN optimization
+ */
+export declare class BusinessRankingFiltersDTO {
+    businessId?: string;
+    tokenType?: NativeTokenType;
+}
+export declare class BusinessRankingAnalyticsRequestDTO {
+    filters?: BusinessRankingFiltersDTO;
+    sortBy?: 'totalTransactions' | 'tokenReceived' | 'businessId' | 'businessName';
+    sortOrder?: SortOrder;
+    limit?: number;
+    startDate?: Date;
+    endDate?: Date;
+}
+export declare class BusinessRankingResultItemDTO {
+    businessId: string | null;
+    businessName: string | null;
+    displayName: string | null;
+    accountAddress: string | null;
+    totalTransactions: number;
+    tokenReceived: number;
+    hasLegacyTransactions?: boolean;
+}
+export declare class BusinessRankingAnalyticsResponseDTO {
+    results: BusinessRankingResultItemDTO[];
+    totalBusinesses: number;
+    metadata: BaseAnalyticsMetadata & {
+        /**
+         * Token type used for filtering (if provided in request)
+         */
+        tokenType?: NativeTokenType;
+        /**
+         * Sort configuration applied
+         */
+        sorting?: {
+            sortBy: string;
+            sortOrder: SortOrder;
+        };
+    };
+}
+//# sourceMappingURL=business-ranking-analytics.dto.d.ts.map

package/dist/esm/shared-lib/dto/analytics/business-ranking-analytics.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"business-ranking-analytics.dto.d.ts","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/business-ranking-analytics.dto.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAErE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;;;;;;GAcG;AAIH,qBAAa,yBAAyB;IASpC,UAAU,CAAC,EAAE,MAAM,CAAC;IASpB,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAID,qBAAa,kCAAkC;IAQ7C,OAAO,CAAC,EAAE,yBAAyB,CAAC;IAUpC,MAAM,CAAC,EAAE,mBAAmB,GAAG,eAAe,GAAG,YAAY,GAAG,cAAc,CAAC;IAU/E,SAAS,CAAC,EAAE,SAAS,CAAC;IAatB,KAAK,CAAC,EAAE,MAAM,CAAC;IAQf,SAAS,CAAC,EAAE,IAAI,CAAC;IAQjB,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAID,qBAAa,4BAA4B;IAMvC,UAAU,EAAG,MAAM,GAAG,IAAI,CAAC;IAO3B,YAAY,EAAG,MAAM,GAAG,IAAI,CAAC;IAO7B,WAAW,EAAG,MAAM,GAAG,IAAI,CAAC;IAO5B,cAAc,EAAG,MAAM,GAAG,IAAI,CAAC;IAM/B,iBAAiB,EAAG,MAAM,CAAC;IAM3B,aAAa,EAAG,MAAM,CAAC;IAMvB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAID,qBAAa,mCAAmC;IAK9C,OAAO,EAAG,4BAA4B,EAAE,CAAC;IAMzC,eAAe,EAAG,MAAM,CAAC;IAMzB,QAAQ,EAAG,qBAAqB,GAAG;QACjC;;WAEG;QACH,SAAS,CAAC,EAAE,eAAe,CAAC;QAE5B;;WAEG;QACH,OAAO,CAAC,EAAE;YACR,MAAM,EAAE,MAAM,CAAC;YACf,SAAS,EAAE,SAAS,CAAC;SACtB,CAAC;KACH,CAAC;CACH"}

package/dist/esm/shared-lib/dto/analytics/business-ranking-analytics.dto.js

@@ -0,0 +1,198 @@
+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;
+};
+import { IsOptional, IsEnum, IsInt, Min, Max, IsDateString, ValidateNested, IsString } from 'class-validator';
+import { Type } from 'class-transformer';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { SortOrder } from '../../../index.js';
+import { NativeTokenTypes } from '../../types/native-token.type.js';
+/**
+ * BUSINESS RANKING ANALYTICS DTOs
+ *
+ * Domain: Analytics (Cross-Domain Query)
+ * Purpose: Server-side aggregation of business transaction rankings
+ *
+ * Replaces:
+ * - Dual queries (modern + legacy business transactions)
+ * - Client-side merging logic in business-balances.component.ts
+ *
+ * Performance Impact:
+ * - 2 API calls → 1 API call (50% reduction)
+ * - ~60 lines removed from frontend
+ * - Server-side JOIN optimization
+ */
+// ========== FILTERS ==========
+export class BusinessRankingFiltersDTO {
+    businessId;
+    tokenType;
+}
+__decorate([
+    ApiPropertyOptional({
+        description: 'Filter to specific business by ID',
+        type: String,
+        format: 'uuid',
+        example: 'biz-uuid-123'
+    }),
+    IsOptional(),
+    IsString()
+], BusinessRankingFiltersDTO.prototype, "businessId", void 0);
+__decorate([
+    ApiPropertyOptional({
+        description: 'Filter by specific token type',
+        enum: NativeTokenTypes,
+        example: NativeTokenTypes.ERC721
+    }),
+    IsOptional(),
+    IsEnum(NativeTokenTypes)
+], BusinessRankingFiltersDTO.prototype, "tokenType", void 0);
+// ========== REQUEST ==========
+export class BusinessRankingAnalyticsRequestDTO {
+    filters;
+    sortBy;
+    sortOrder;
+    limit;
+    startDate;
+    endDate;
+}
+__decorate([
+    ApiPropertyOptional({
+        description: 'Filters for business ranking query',
+        type: BusinessRankingFiltersDTO
+    }),
+    IsOptional(),
+    ValidateNested(),
+    Type(() => BusinessRankingFiltersDTO)
+], BusinessRankingAnalyticsRequestDTO.prototype, "filters", void 0);
+__decorate([
+    ApiPropertyOptional({
+        description: 'Field to sort results by',
+        enum: ['totalTransactions', 'tokenReceived', 'businessId', 'businessName'],
+        default: 'totalTransactions',
+        example: 'totalTransactions'
+    }),
+    IsOptional(),
+    IsString()
+], BusinessRankingAnalyticsRequestDTO.prototype, "sortBy", void 0);
+__decorate([
+    ApiPropertyOptional({
+        description: 'Sort order (ASC or DESC)',
+        enum: SortOrder,
+        default: SortOrder.DESC,
+        example: SortOrder.DESC
+    }),
+    IsOptional(),
+    IsEnum(SortOrder)
+], BusinessRankingAnalyticsRequestDTO.prototype, "sortOrder", void 0);
+__decorate([
+    ApiPropertyOptional({
+        description: 'Maximum number of results to return',
+        minimum: 1,
+        maximum: 1000,
+        default: 50,
+        example: 50
+    }),
+    IsOptional(),
+    IsInt(),
+    Min(1),
+    Max(1000)
+], BusinessRankingAnalyticsRequestDTO.prototype, "limit", void 0);
+__decorate([
+    ApiPropertyOptional({
+        description: 'Start date for filtering transactions (ISO 8601)',
+        example: '2026-01-01T00:00:00Z'
+    }),
+    IsOptional(),
+    IsDateString()
+], BusinessRankingAnalyticsRequestDTO.prototype, "startDate", void 0);
+__decorate([
+    ApiPropertyOptional({
+        description: 'End date for filtering transactions (ISO 8601)',
+        example: '2026-02-01T00:00:00Z'
+    }),
+    IsOptional(),
+    IsDateString()
+], BusinessRankingAnalyticsRequestDTO.prototype, "endDate", void 0);
+// ========== RESULT ITEM ==========
+export class BusinessRankingResultItemDTO {
+    businessId;
+    businessName;
+    displayName;
+    accountAddress;
+    totalTransactions;
+    tokenReceived;
+    hasLegacyTransactions;
+}
+__decorate([
+    ApiProperty({
+        description: 'Business UUID (null for unidentified businesses)',
+        nullable: true,
+        example: '123e4567-e89b-12d3-a456-426614174000'
+    })
+], BusinessRankingResultItemDTO.prototype, "businessId", void 0);
+__decorate([
+    ApiProperty({
+        description: 'Business name',
+        nullable: true,
+        example: 'Acme Coffee Shop'
+    })
+], BusinessRankingResultItemDTO.prototype, "businessName", void 0);
+__decorate([
+    ApiProperty({
+        description: 'Business display name',
+        nullable: true,
+        example: 'Acme Coffee'
+    })
+], BusinessRankingResultItemDTO.prototype, "displayName", void 0);
+__decorate([
+    ApiProperty({
+        description: 'Business blockchain account address',
+        nullable: true,
+        example: '0x1234567890abcdef...'
+    })
+], BusinessRankingResultItemDTO.prototype, "accountAddress", void 0);
+__decorate([
+    ApiProperty({
+        description: 'Total number of successful transactions received',
+        example: 150
+    })
+], BusinessRankingResultItemDTO.prototype, "totalTransactions", void 0);
+__decorate([
+    ApiProperty({
+        description: 'Total token amount received',
+        example: 1500.50
+    })
+], BusinessRankingResultItemDTO.prototype, "tokenReceived", void 0);
+__decorate([
+    ApiPropertyOptional({
+        description: 'Whether this business has legacy transactions (address-based)',
+        example: false
+    })
+], BusinessRankingResultItemDTO.prototype, "hasLegacyTransactions", void 0);
+// ========== RESPONSE ==========
+export class BusinessRankingAnalyticsResponseDTO {
+    results;
+    totalBusinesses;
+    metadata;
+}
+__decorate([
+    ApiProperty({
+        description: 'Array of business ranking results',
+        type: [BusinessRankingResultItemDTO]
+    })
+], BusinessRankingAnalyticsResponseDTO.prototype, "results", void 0);
+__decorate([
+    ApiProperty({
+        description: 'Total number of businesses in results',
+        example: 25
+    })
+], BusinessRankingAnalyticsResponseDTO.prototype, "totalBusinesses", void 0);
+__decorate([
+    ApiProperty({
+        description: 'Query metadata',
+        type: 'object'
+    })
+], BusinessRankingAnalyticsResponseDTO.prototype, "metadata", void 0);
+//# sourceMappingURL=business-ranking-analytics.dto.js.map

package/dist/esm/shared-lib/dto/analytics/business-ranking-analytics.dto.js.map

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

package/dist/esm/shared-lib/dto/analytics/index.d.ts

@@ -1,5 +1,7 @@
 export * from './base-analytics.dto';
+export * from './business-ranking-analytics.dto';
 export * from './group-by-expression.dto';
+export * from './retention-analytics.dto';
 export * from './usage-analytics.dto';
 export * from './user-ranking-analytics.dto';
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/shared-lib/dto/analytics/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/index.ts"],"names":[],"mappings":"AAEA,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/index.ts"],"names":[],"mappings":"AAEA,cAAc,sBAAsB,CAAC;AACrC,cAAc,kCAAkC,CAAC;AACjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC"}

package/dist/esm/shared-lib/dto/analytics/index.js

@@ -1,5 +1,7 @@
 export * from './base-analytics.dto.js';
+export * from './business-ranking-analytics.dto.js';
 export * from './group-by-expression.dto.js';
+export * from './retention-analytics.dto.js';
 export * from './usage-analytics.dto.js';
 export * from './user-ranking-analytics.dto.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/shared-lib/dto/analytics/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/index.ts"],"names":[],"mappings":"AAEA,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/index.ts"],"names":[],"mappings":"AAEA,cAAc,sBAAsB,CAAC;AACrC,cAAc,kCAAkC,CAAC;AACjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC"}

package/dist/esm/shared-lib/dto/analytics/retention-analytics.dto.d.ts

@@ -0,0 +1,65 @@
+import type { NativeTokenType } from '../../types/native-token.type';
+import { BaseAnalyticsMetadata } from './base-analytics.dto';
+/**
+ * RETENTION ANALYTICS DTOs
+ *
+ * Domain: Analytics (Cross-Domain Query)
+ * Purpose: Server-side monthly retention calculations
+ *
+ * Replaces:
+ * - 13 separate API calls (one per month)
+ * - Client-side forkJoin aggregation
+ * - Manual month generation logic
+ *
+ * Performance Impact:
+ * - 13 API calls → 1 API call (92% reduction)
+ * - ~1350ms → ~105ms load time (92% faster)
+ * - ~260KB → ~40KB payload (85% smaller)
+ */
+export declare class RetentionAnalyticsFiltersDTO {
+    tokenType?: NativeTokenType;
+    triggerProcessType?: string;
+}
+export declare class RetentionAnalyticsRequestDTO {
+    startMonth?: Date;
+    monthsBack?: number;
+    filters?: RetentionAnalyticsFiltersDTO;
+}
+/**
+ * Retention data for a month offset within a cohort
+ * Tracks how many users from the original cohort are still active
+ */
+export declare class CohortRetentionMonthDTO {
+    retainedUsers: number;
+    retentionRate: number;
+}
+/**
+ * Cohort retention result for a single month
+ * Contains the cohort (new users in month) and their retention over subsequent months
+ */
+export declare class RetentionMonthResultDTO {
+    monthKey: string;
+    startDate: Date;
+    endDate: Date;
+    cohortSize: number;
+    monthlyRetention: {
+        [monthOffset: string]: CohortRetentionMonthDTO;
+    };
+    byTriggerType?: {
+        [key: string]: {
+            count: number;
+            uniqueUsers: number;
+        };
+    };
+}
+export declare class RetentionAnalyticsResponseDTO {
+    results: RetentionMonthResultDTO[];
+    totalMonths: number;
+    metadata: BaseAnalyticsMetadata & {
+        /**
+         * Calculation method used for retention analysis
+         */
+        calculationMethod: 'monthly-cohort';
+    };
+}
+//# sourceMappingURL=retention-analytics.dto.d.ts.map

package/dist/esm/shared-lib/dto/analytics/retention-analytics.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention-analytics.dto.d.ts","sourceRoot":"","sources":["../../../../../src/shared-lib/dto/analytics/retention-analytics.dto.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAErE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AAIH,qBAAa,4BAA4B;IAQvC,SAAS,CAAC,EAAE,eAAe,CAAC;IAQ5B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID,qBAAa,4BAA4B;IAOvC,UAAU,CAAC,EAAE,IAAI,CAAC;IAalB,UAAU,CAAC,EAAE,MAAM,CAAC;IASpB,OAAO,CAAC,EAAE,4BAA4B,CAAC;CACxC;AAID;;;GAGG;AACH,qBAAa,uBAAuB;IAKlC,aAAa,EAAG,MAAM,CAAC;IAMvB,aAAa,EAAG,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,qBAAa,uBAAuB;IAKlC,QAAQ,EAAG,MAAM,CAAC;IAMlB,SAAS,EAAG,IAAI,CAAC;IAMjB,OAAO,EAAG,IAAI,CAAC;IAMf,UAAU,EAAG,MAAM,CAAC;IAWpB,gBAAgB,EAAG;QACjB,CAAC,WAAW,EAAE,MAAM,GAAG,uBAAuB,CAAC;KAChD,CAAC;IASF,aAAa,CAAC,EAAE;QACd,CAAC,GAAG,EAAE,MAAM,GAAG;YACb,KAAK,EAAE,MAAM,CAAC;YACd,WAAW,EAAE,MAAM,CAAC;SACrB,CAAC;KACH,CAAC;CACH;AAID,qBAAa,6BAA6B;IAKxC,OAAO,EAAG,uBAAuB,EAAE,CAAC;IAMpC,WAAW,EAAG,MAAM,CAAC;IAMrB,QAAQ,EAAG,qBAAqB,GAAG;QACjC;;WAEG;QACH,iBAAiB,EAAE,gBAAgB,CAAC;KACrC,CAAC;CACH"}

package/dist/esm/shared-lib/dto/analytics/retention-analytics.dto.js

@@ -0,0 +1,186 @@
+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;
+};
+import { IsOptional, IsEnum, IsInt, Min, Max, IsDateString, ValidateNested, IsString } from 'class-validator';
+import { Type } from 'class-transformer';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { NativeTokenTypes } from '../../types/native-token.type.js';
+/**
+ * RETENTION ANALYTICS DTOs
+ *
+ * Domain: Analytics (Cross-Domain Query)
+ * Purpose: Server-side monthly retention calculations
+ *
+ * Replaces:
+ * - 13 separate API calls (one per month)
+ * - Client-side forkJoin aggregation
+ * - Manual month generation logic
+ *
+ * Performance Impact:
+ * - 13 API calls → 1 API call (92% reduction)
+ * - ~1350ms → ~105ms load time (92% faster)
+ * - ~260KB → ~40KB payload (85% smaller)
+ */
+// ========== REQUEST FILTERS ==========
+export class RetentionAnalyticsFiltersDTO {
+    tokenType;
+    triggerProcessType;
+}
+__decorate([
+    ApiPropertyOptional({
+        description: 'Filter by specific token type',
+        enum: NativeTokenTypes,
+        example: NativeTokenTypes.ERC721
+    }),
+    IsOptional(),
+    IsEnum(NativeTokenTypes)
+], RetentionAnalyticsFiltersDTO.prototype, "tokenType", void 0);
+__decorate([
+    ApiPropertyOptional({
+        description: 'Filter by trigger process type',
+        example: 'PURCHASE'
+    }),
+    IsOptional(),
+    IsString()
+], RetentionAnalyticsFiltersDTO.prototype, "triggerProcessType", void 0);
+// ========== REQUEST ==========
+export class RetentionAnalyticsRequestDTO {
+    startMonth;
+    monthsBack;
+    filters;
+}
+__decorate([
+    ApiPropertyOptional({
+        description: 'Starting month for retention analysis (defaults to current month)',
+        example: '2026-02-01T00:00:00Z'
+    }),
+    IsOptional(),
+    IsDateString()
+], RetentionAnalyticsRequestDTO.prototype, "startMonth", void 0);
+__decorate([
+    ApiPropertyOptional({
+        description: 'Number of months to analyze (looking backwards)',
+        minimum: 1,
+        maximum: 24,
+        default: 13,
+        example: 13
+    }),
+    IsOptional(),
+    IsInt(),
+    Min(1),
+    Max(24)
+], RetentionAnalyticsRequestDTO.prototype, "monthsBack", void 0);
+__decorate([
+    ApiPropertyOptional({
+        description: 'Optional filters for retention query',
+        type: RetentionAnalyticsFiltersDTO
+    }),
+    IsOptional(),
+    ValidateNested(),
+    Type(() => RetentionAnalyticsFiltersDTO)
+], RetentionAnalyticsRequestDTO.prototype, "filters", void 0);
+// ========== MONTH RESULT ==========
+/**
+ * Retention data for a month offset within a cohort
+ * Tracks how many users from the original cohort are still active
+ */
+export class CohortRetentionMonthDTO {
+    retainedUsers;
+    retentionRate;
+}
+__decorate([
+    ApiProperty({
+        description: 'Number of users from original cohort still active in this month offset',
+        example: 85
+    })
+], CohortRetentionMonthDTO.prototype, "retainedUsers", void 0);
+__decorate([
+    ApiProperty({
+        description: 'Retention rate: (retainedUsers / cohortSize) * 100',
+        example: 70.8
+    })
+], CohortRetentionMonthDTO.prototype, "retentionRate", void 0);
+/**
+ * Cohort retention result for a single month
+ * Contains the cohort (new users in month) and their retention over subsequent months
+ */
+export class RetentionMonthResultDTO {
+    monthKey;
+    startDate;
+    endDate;
+    cohortSize;
+    monthlyRetention;
+    byTriggerType;
+}
+__decorate([
+    ApiProperty({
+        description: 'Month identifier in YYYY-MM format',
+        example: '2026-02'
+    })
+], RetentionMonthResultDTO.prototype, "monthKey", void 0);
+__decorate([
+    ApiProperty({
+        description: 'Start date of the month',
+        example: '2026-02-01T00:00:00Z'
+    })
+], RetentionMonthResultDTO.prototype, "startDate", void 0);
+__decorate([
+    ApiProperty({
+        description: 'End date of the month',
+        example: '2026-03-01T00:00:00Z'
+    })
+], RetentionMonthResultDTO.prototype, "endDate", void 0);
+__decorate([
+    ApiProperty({
+        description: 'Number of users who made their first transaction in this month (cohort size)',
+        example: 120
+    })
+], RetentionMonthResultDTO.prototype, "cohortSize", void 0);
+__decorate([
+    ApiProperty({
+        description: 'Retention data for this cohort over subsequent months. Key is month offset (0=same month, 1=next month, 2=2 months later, etc.)',
+        type: 'object',
+        example: {
+            '0': { retainedUsers: 120, retentionRate: 100 },
+            '1': { retainedUsers: 85, retentionRate: 70.8 },
+            '2': { retainedUsers: 65, retentionRate: 54.2 }
+        }
+    })
+], RetentionMonthResultDTO.prototype, "monthlyRetention", void 0);
+__decorate([
+    ApiPropertyOptional({
+        description: 'Breakdown of transactions by trigger type',
+        example: {
+            PURCHASE: { count: 800, uniqueUsers: 300 },
+            REWARD: { count: 450, uniqueUsers: 200 }
+        }
+    })
+], RetentionMonthResultDTO.prototype, "byTriggerType", void 0);
+// ========== RESPONSE ==========
+export class RetentionAnalyticsResponseDTO {
+    results;
+    totalMonths;
+    metadata;
+}
+__decorate([
+    ApiProperty({
+        description: 'Array of monthly retention results (ordered chronologically)',
+        type: [RetentionMonthResultDTO]
+    })
+], RetentionAnalyticsResponseDTO.prototype, "results", void 0);
+__decorate([
+    ApiProperty({
+        description: 'Total number of months analyzed',
+        example: 13
+    })
+], RetentionAnalyticsResponseDTO.prototype, "totalMonths", void 0);
+__decorate([
+    ApiProperty({
+        description: 'Query metadata',
+        type: 'object'
+    })
+], RetentionAnalyticsResponseDTO.prototype, "metadata", void 0);
+//# sourceMappingURL=retention-analytics.dto.js.map

package/dist/esm/shared-lib/dto/analytics/retention-analytics.dto.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-shared",
-  "version": "2.1.84",
+  "version": "2.1.86",
   "scripts": {
     "clean": "find dist -type f -delete 2>/dev/null || true",
     "build:esm": "tsc -p tsconfig.esm.json && node scripts/add-js-extensions.js",