wip

packages/analytics/application/use-cases/GetEntityAnalyticsQuery.ts

@@ -0,0 +1,197 @@
+/**
+ * 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<EntityAnalyticsOutput> {
+    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<number> {
+    // 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)}`;
+  }
+}