wip

packages/analytics/domain/entities/AnalyticsSnapshot.ts

@@ -0,0 +1,162 @@
+/**
+ * Domain Entity: AnalyticsSnapshot
+ * 
+ * Aggregated analytics data for a specific entity over a time period.
+ * Pre-calculated metrics for sponsor dashboard and entity analytics.
+ */
+
+export type SnapshotPeriod = 'daily' | 'weekly' | 'monthly';
+export type SnapshotEntityType = 'league' | 'driver' | 'team' | 'race' | 'sponsor';
+
+export interface AnalyticsMetrics {
+  pageViews: number;
+  uniqueVisitors: number;
+  avgSessionDuration: number;
+  bounceRate: number;
+  engagementScore: number;
+  sponsorClicks: number;
+  sponsorUrlClicks: number;
+  socialShares: number;
+  leagueJoins: number;
+  raceRegistrations: number;
+  exposureValue: number;
+}
+
+export interface AnalyticsSnapshotProps {
+  id: string;
+  entityType: SnapshotEntityType;
+  entityId: string;
+  period: SnapshotPeriod;
+  startDate: Date;
+  endDate: Date;
+  metrics: AnalyticsMetrics;
+  createdAt: Date;
+}
+
+export class AnalyticsSnapshot {
+  readonly id: string;
+  readonly entityType: SnapshotEntityType;
+  readonly entityId: string;
+  readonly period: SnapshotPeriod;
+  readonly startDate: Date;
+  readonly endDate: Date;
+  readonly metrics: AnalyticsMetrics;
+  readonly createdAt: Date;
+
+  private constructor(props: AnalyticsSnapshotProps) {
+    this.id = props.id;
+    this.entityType = props.entityType;
+    this.entityId = props.entityId;
+    this.period = props.period;
+    this.startDate = props.startDate;
+    this.endDate = props.endDate;
+    this.metrics = props.metrics;
+    this.createdAt = props.createdAt;
+  }
+
+  static create(props: Omit<AnalyticsSnapshotProps, 'createdAt'> & { createdAt?: Date }): AnalyticsSnapshot {
+    this.validate(props);
+
+    return new AnalyticsSnapshot({
+      ...props,
+      createdAt: props.createdAt ?? new Date(),
+    });
+  }
+
+  static createEmpty(
+    id: string,
+    entityType: SnapshotEntityType,
+    entityId: string,
+    period: SnapshotPeriod,
+    startDate: Date,
+    endDate: Date
+  ): AnalyticsSnapshot {
+    return new AnalyticsSnapshot({
+      id,
+      entityType,
+      entityId,
+      period,
+      startDate,
+      endDate,
+      metrics: {
+        pageViews: 0,
+        uniqueVisitors: 0,
+        avgSessionDuration: 0,
+        bounceRate: 0,
+        engagementScore: 0,
+        sponsorClicks: 0,
+        sponsorUrlClicks: 0,
+        socialShares: 0,
+        leagueJoins: 0,
+        raceRegistrations: 0,
+        exposureValue: 0,
+      },
+      createdAt: new Date(),
+    });
+  }
+
+  private static validate(props: Omit<AnalyticsSnapshotProps, 'createdAt'>): void {
+    if (!props.id || props.id.trim().length === 0) {
+      throw new Error('AnalyticsSnapshot ID is required');
+    }
+
+    if (!props.entityType) {
+      throw new Error('AnalyticsSnapshot entityType is required');
+    }
+
+    if (!props.entityId || props.entityId.trim().length === 0) {
+      throw new Error('AnalyticsSnapshot entityId is required');
+    }
+
+    if (!props.period) {
+      throw new Error('AnalyticsSnapshot period is required');
+    }
+
+    if (props.endDate < props.startDate) {
+      throw new Error('AnalyticsSnapshot endDate must be after startDate');
+    }
+  }
+
+  /**
+   * Calculate exposure score for sponsors (weighted combination of metrics)
+   */
+  calculateExposureScore(): number {
+    const { pageViews, uniqueVisitors, sponsorClicks, sponsorUrlClicks, socialShares } = this.metrics;
+    
+    return (
+      pageViews * 1 +
+      uniqueVisitors * 2 +
+      sponsorClicks * 10 +
+      sponsorUrlClicks * 25 +
+      socialShares * 5
+    );
+  }
+
+  /**
+   * Calculate trust indicator based on engagement quality
+   */
+  getTrustIndicator(): 'high' | 'medium' | 'low' {
+    const { bounceRate, avgSessionDuration, engagementScore } = this.metrics;
+    
+    if (bounceRate < 30 && avgSessionDuration > 120000 && engagementScore > 50) {
+      return 'high';
+    }
+    if (bounceRate < 60 && avgSessionDuration > 30000 && engagementScore > 20) {
+      return 'medium';
+    }
+    return 'low';
+  }
+
+  /**
+   * Get period comparison label
+   */
+  getPeriodLabel(): string {
+    const formatter = new Intl.DateTimeFormat('en-US', { 
+      month: 'short', 
+      day: 'numeric',
+      year: this.period === 'monthly' ? 'numeric' : undefined 
+    });
+    
+    return `${formatter.format(this.startDate)} - ${formatter.format(this.endDate)}`;
+  }
+}

packages/analytics/domain/entities/EngagementEvent.ts

@@ -0,0 +1,121 @@
+/**
+ * Domain Entity: EngagementEvent
+ * 
+ * Represents user interactions beyond page views.
+ * Tracks clicks, downloads, sign-ups, and other engagement actions.
+ */
+
+export type EngagementAction = 
+  | 'click_sponsor_logo'
+  | 'click_sponsor_url'
+  | 'download_livery_pack'
+  | 'join_league'
+  | 'register_race'
+  | 'view_standings'
+  | 'view_schedule'
+  | 'share_social'
+  | 'contact_sponsor';
+
+export type EngagementEntityType = 'league' | 'driver' | 'team' | 'race' | 'sponsor' | 'sponsorship';
+
+export interface EngagementEventProps {
+  id: string;
+  action: EngagementAction;
+  entityType: EngagementEntityType;
+  entityId: string;
+  actorId?: string;
+  actorType: 'anonymous' | 'driver' | 'sponsor';
+  sessionId: string;
+  metadata?: Record<string, string | number | boolean>;
+  timestamp: Date;
+}
+
+export class EngagementEvent {
+  readonly id: string;
+  readonly action: EngagementAction;
+  readonly entityType: EngagementEntityType;
+  readonly entityId: string;
+  readonly actorId?: string;
+  readonly actorType: 'anonymous' | 'driver' | 'sponsor';
+  readonly sessionId: string;
+  readonly metadata?: Record<string, string | number | boolean>;
+  readonly timestamp: Date;
+
+  private constructor(props: EngagementEventProps) {
+    this.id = props.id;
+    this.action = props.action;
+    this.entityType = props.entityType;
+    this.entityId = props.entityId;
+    this.actorId = props.actorId;
+    this.actorType = props.actorType;
+    this.sessionId = props.sessionId;
+    this.metadata = props.metadata;
+    this.timestamp = props.timestamp;
+  }
+
+  static create(props: Omit<EngagementEventProps, 'timestamp'> & { timestamp?: Date }): EngagementEvent {
+    this.validate(props);
+
+    return new EngagementEvent({
+      ...props,
+      timestamp: props.timestamp ?? new Date(),
+    });
+  }
+
+  private static validate(props: Omit<EngagementEventProps, 'timestamp'>): void {
+    if (!props.id || props.id.trim().length === 0) {
+      throw new Error('EngagementEvent ID is required');
+    }
+
+    if (!props.action) {
+      throw new Error('EngagementEvent action is required');
+    }
+
+    if (!props.entityType) {
+      throw new Error('EngagementEvent entityType is required');
+    }
+
+    if (!props.entityId || props.entityId.trim().length === 0) {
+      throw new Error('EngagementEvent entityId is required');
+    }
+
+    if (!props.sessionId || props.sessionId.trim().length === 0) {
+      throw new Error('EngagementEvent sessionId is required');
+    }
+  }
+
+  /**
+   * Check if this is a sponsor-related engagement
+   */
+  isSponsorEngagement(): boolean {
+    return this.action.startsWith('click_sponsor') || 
+           this.action === 'contact_sponsor' ||
+           this.entityType === 'sponsor' ||
+           this.entityType === 'sponsorship';
+  }
+
+  /**
+   * Check if this is a conversion event (high-value action)
+   */
+  isConversionEvent(): boolean {
+    return ['join_league', 'register_race', 'click_sponsor_url', 'contact_sponsor'].includes(this.action);
+  }
+
+  /**
+   * Get engagement weight for analytics calculations
+   */
+  getEngagementWeight(): number {
+    const weights: Record<EngagementAction, number> = {
+      'click_sponsor_logo': 2,
+      'click_sponsor_url': 5,
+      'download_livery_pack': 3,
+      'join_league': 10,
+      'register_race': 8,
+      'view_standings': 1,
+      'view_schedule': 1,
+      'share_social': 4,
+      'contact_sponsor': 15,
+    };
+    return weights[this.action] || 1;
+  }
+}

packages/analytics/domain/entities/PageView.ts

@@ -0,0 +1,107 @@
+/**
+ * Domain Entity: PageView
+ * 
+ * Represents a single page view event for analytics tracking.
+ * Captures visitor interactions with leagues, drivers, teams, races.
+ */
+
+export type EntityType = 'league' | 'driver' | 'team' | 'race' | 'sponsor';
+export type VisitorType = 'anonymous' | 'driver' | 'sponsor';
+
+export interface PageViewProps {
+  id: string;
+  entityType: EntityType;
+  entityId: string;
+  visitorId?: string;
+  visitorType: VisitorType;
+  sessionId: string;
+  referrer?: string;
+  userAgent?: string;
+  country?: string;
+  timestamp: Date;
+  durationMs?: number;
+}
+
+export class PageView {
+  readonly id: string;
+  readonly entityType: EntityType;
+  readonly entityId: string;
+  readonly visitorId?: string;
+  readonly visitorType: VisitorType;
+  readonly sessionId: string;
+  readonly referrer?: string;
+  readonly userAgent?: string;
+  readonly country?: string;
+  readonly timestamp: Date;
+  readonly durationMs?: number;
+
+  private constructor(props: PageViewProps) {
+    this.id = props.id;
+    this.entityType = props.entityType;
+    this.entityId = props.entityId;
+    this.visitorId = props.visitorId;
+    this.visitorType = props.visitorType;
+    this.sessionId = props.sessionId;
+    this.referrer = props.referrer;
+    this.userAgent = props.userAgent;
+    this.country = props.country;
+    this.timestamp = props.timestamp;
+    this.durationMs = props.durationMs;
+  }
+
+  static create(props: Omit<PageViewProps, 'timestamp'> & { timestamp?: Date }): PageView {
+    this.validate(props);
+
+    return new PageView({
+      ...props,
+      timestamp: props.timestamp ?? new Date(),
+    });
+  }
+
+  private static validate(props: Omit<PageViewProps, 'timestamp'>): void {
+    if (!props.id || props.id.trim().length === 0) {
+      throw new Error('PageView ID is required');
+    }
+
+    if (!props.entityType) {
+      throw new Error('PageView entityType is required');
+    }
+
+    if (!props.entityId || props.entityId.trim().length === 0) {
+      throw new Error('PageView entityId is required');
+    }
+
+    if (!props.sessionId || props.sessionId.trim().length === 0) {
+      throw new Error('PageView sessionId is required');
+    }
+  }
+
+  /**
+   * Update duration when visitor leaves page
+   */
+  withDuration(durationMs: number): PageView {
+    if (durationMs < 0) {
+      throw new Error('Duration must be non-negative');
+    }
+
+    return new PageView({
+      ...this,
+      durationMs,
+    });
+  }
+
+  /**
+   * Check if this is a meaningful view (not a bounce)
+   */
+  isMeaningfulView(): boolean {
+    return this.durationMs !== undefined && this.durationMs >= 5000; // 5+ seconds
+  }
+
+  /**
+   * Check if view came from external source
+   */
+  isExternalReferral(): boolean {
+    if (!this.referrer) return false;
+    return !this.referrer.includes('gridpilot');
+  }
+}

packages/analytics/domain/repositories/IAnalyticsSnapshotRepository.ts

@@ -0,0 +1,27 @@
+/**
+ * Repository Interface: IAnalyticsSnapshotRepository
+ * 
+ * Defines persistence operations for AnalyticsSnapshot entities.
+ */
+
+import type { AnalyticsSnapshot, SnapshotPeriod, SnapshotEntityType } from '../entities/AnalyticsSnapshot';
+
+export interface IAnalyticsSnapshotRepository {
+  save(snapshot: AnalyticsSnapshot): Promise<void>;
+  findById(id: string): Promise<AnalyticsSnapshot | null>;
+  findByEntity(entityType: SnapshotEntityType, entityId: string): Promise<AnalyticsSnapshot[]>;
+  findByPeriod(
+    entityType: SnapshotEntityType,
+    entityId: string,
+    period: SnapshotPeriod,
+    startDate: Date,
+    endDate: Date
+  ): Promise<AnalyticsSnapshot | null>;
+  findLatest(entityType: SnapshotEntityType, entityId: string, period: SnapshotPeriod): Promise<AnalyticsSnapshot | null>;
+  getHistoricalSnapshots(
+    entityType: SnapshotEntityType,
+    entityId: string,
+    period: SnapshotPeriod,
+    limit: number
+  ): Promise<AnalyticsSnapshot[]>;
+}

packages/analytics/domain/repositories/IEngagementRepository.ts

@@ -0,0 +1,17 @@
+/**
+ * Repository Interface: IEngagementRepository
+ * 
+ * Defines persistence operations for EngagementEvent entities.
+ */
+
+import type { EngagementEvent, EngagementAction, EngagementEntityType } from '../entities/EngagementEvent';
+
+export interface IEngagementRepository {
+  save(event: EngagementEvent): Promise<void>;
+  findById(id: string): Promise<EngagementEvent | null>;
+  findByEntityId(entityType: EngagementEntityType, entityId: string): Promise<EngagementEvent[]>;
+  findByAction(action: EngagementAction): Promise<EngagementEvent[]>;
+  findByDateRange(startDate: Date, endDate: Date): Promise<EngagementEvent[]>;
+  countByAction(action: EngagementAction, entityId?: string, since?: Date): Promise<number>;
+  getSponsorClicksForEntity(entityId: string, since?: Date): Promise<number>;
+}

packages/analytics/domain/repositories/IPageViewRepository.ts

@@ -0,0 +1,17 @@
+/**
+ * Repository Interface: IPageViewRepository
+ * 
+ * Defines persistence operations for PageView entities.
+ */
+
+import type { PageView, EntityType } from '../entities/PageView';
+
+export interface IPageViewRepository {
+  save(pageView: PageView): Promise<void>;
+  findById(id: string): Promise<PageView | null>;
+  findByEntityId(entityType: EntityType, entityId: string): Promise<PageView[]>;
+  findByDateRange(startDate: Date, endDate: Date): Promise<PageView[]>;
+  findBySession(sessionId: string): Promise<PageView[]>;
+  countByEntityId(entityType: EntityType, entityId: string, since?: Date): Promise<number>;
+  countUniqueVisitors(entityType: EntityType, entityId: string, since?: Date): Promise<number>;
+}