/** * Query: GetEntityAnalyticsQuery * * Retrieves analytics data for an entity (league, driver, team, race). * Returns metrics formatted for display to sponsors and admins. */ import type { IPageViewRepository } from '../../domain/repositories/IPageViewRepository'; import type { IEngagementRepository } from '../../domain/repositories/IEngagementRepository'; import type { IAnalyticsSnapshotRepository } from '../../domain/repositories/IAnalyticsSnapshotRepository'; import type { EntityType } from '../../domain/entities/PageView'; import type { SnapshotPeriod } from '../../domain/entities/AnalyticsSnapshot'; export interface GetEntityAnalyticsInput { entityType: EntityType; entityId: string; period?: SnapshotPeriod; since?: Date; } export interface EntityAnalyticsOutput { entityType: EntityType; entityId: string; summary: { totalPageViews: number; uniqueVisitors: number; sponsorClicks: number; engagementScore: number; trustIndicator: 'high' | 'medium' | 'low'; exposureValue: number; }; trends: { pageViewsChange: number; uniqueVisitorsChange: number; engagementChange: number; }; period: { start: Date; end: Date; label: string; }; } export class GetEntityAnalyticsQuery { constructor( private readonly pageViewRepository: IPageViewRepository, private readonly engagementRepository: IEngagementRepository, private readonly snapshotRepository: IAnalyticsSnapshotRepository ) {} async execute(input: GetEntityAnalyticsInput): Promise { const period = input.period ?? 'weekly'; const now = new Date(); const since = input.since ?? this.getPeriodStartDate(now, period); // Get current metrics const totalPageViews = await this.pageViewRepository.countByEntityId( input.entityType, input.entityId, since ); const uniqueVisitors = await this.pageViewRepository.countUniqueVisitors( input.entityType, input.entityId, since ); const sponsorClicks = await this.engagementRepository.getSponsorClicksForEntity( input.entityId, since ); // Calculate engagement score (weighted sum of actions) const engagementScore = await this.calculateEngagementScore(input.entityId, since); // Determine trust indicator const trustIndicator = this.determineTrustIndicator(totalPageViews, uniqueVisitors, engagementScore); // Calculate exposure value (for sponsor ROI) const exposureValue = this.calculateExposureValue(totalPageViews, uniqueVisitors, sponsorClicks); // Get previous period for trends const previousPeriodStart = this.getPreviousPeriodStart(since, period); const previousPageViews = await this.pageViewRepository.countByEntityId( input.entityType, input.entityId, previousPeriodStart ) - totalPageViews; const previousUniqueVisitors = await this.pageViewRepository.countUniqueVisitors( input.entityType, input.entityId, previousPeriodStart ) - uniqueVisitors; return { entityType: input.entityType, entityId: input.entityId, summary: { totalPageViews, uniqueVisitors, sponsorClicks, engagementScore, trustIndicator, exposureValue, }, trends: { pageViewsChange: this.calculatePercentageChange(previousPageViews, totalPageViews), uniqueVisitorsChange: this.calculatePercentageChange(previousUniqueVisitors, uniqueVisitors), engagementChange: 0, // Would need historical engagement data }, period: { start: since, end: now, label: this.formatPeriodLabel(since, now), }, }; } private getPeriodStartDate(now: Date, period: SnapshotPeriod): Date { const start = new Date(now); switch (period) { case 'daily': start.setDate(start.getDate() - 1); break; case 'weekly': start.setDate(start.getDate() - 7); break; case 'monthly': start.setMonth(start.getMonth() - 1); break; } return start; } private getPreviousPeriodStart(currentStart: Date, period: SnapshotPeriod): Date { const start = new Date(currentStart); switch (period) { case 'daily': start.setDate(start.getDate() - 1); break; case 'weekly': start.setDate(start.getDate() - 7); break; case 'monthly': start.setMonth(start.getMonth() - 1); break; } return start; } private async calculateEngagementScore(entityId: string, since: Date): Promise { // Base engagement from sponsor interactions const sponsorClicks = await this.engagementRepository.getSponsorClicksForEntity(entityId, since); return sponsorClicks * 10; // Weighted score } private determineTrustIndicator( pageViews: number, uniqueVisitors: number, engagementScore: number ): 'high' | 'medium' | 'low' { const engagementRate = pageViews > 0 ? engagementScore / pageViews : 0; const returningVisitorRate = pageViews > 0 ? (pageViews - uniqueVisitors) / pageViews : 0; if (engagementRate > 0.1 && returningVisitorRate > 0.3) { return 'high'; } if (engagementRate > 0.05 || returningVisitorRate > 0.1) { return 'medium'; } return 'low'; } private calculateExposureValue( pageViews: number, uniqueVisitors: number, sponsorClicks: number ): number { // Simple exposure value calculation (could be monetized) return (pageViews * 0.01) + (uniqueVisitors * 0.05) + (sponsorClicks * 0.50); } private calculatePercentageChange(previous: number, current: number): number { if (previous === 0) return current > 0 ? 100 : 0; return Math.round(((current - previous) / previous) * 100); } private formatPeriodLabel(start: Date, end: Date): string { const formatter = new Intl.DateTimeFormat('en-US', { month: 'short', day: 'numeric', }); return `${formatter.format(start)} - ${formatter.format(end)}`; } }