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

/**
 * Query: GetEntityAnalyticsQuery
 *
 * Retrieves analytics data for an entity (league, driver, team, race).
 * Returns metrics formatted for display to sponsors and admins.
 */

import type { AsyncUseCase } from '@gridpilot/shared/application';
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/types/PageView';
import type { SnapshotPeriod } from '../../domain/types/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
  implements AsyncUseCase<GetEntityAnalyticsInput, EntityAnalyticsOutput> {
  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)}`;
  }
}