feat(analytics): implement extensible reporting and dashboard architecture

- add centralized analytics ingestion pipeline via background proxy
- introduce subscription policy engine with plans, capabilities, and limits
- add formatter and reporting layers for clean UI-facing analytics
- implement dashboard analytics cards with trends and session metrics
- refactor session tracking to use continuous heartbeat updates
- decouple analytics reporting from UI and storage internals
- add formatter unit tests and subscription-aware service tests

Author: YazanAmmar

src/adapters/chrome/proxy-analytics.ts

@@ -0,0 +1,13 @@
+import { AnalyticsRepository } from '../../core/interfaces/analytics-repository';
+import { AnalyticsRecord, AnalyticsQueryFilter } from '../../core/analytics/types';
+import { AppAction } from '../../types';
+
+export class ChromeProxyAnalyticsRepository implements AnalyticsRepository {
+  public async saveRecord(record: AnalyticsRecord): Promise<void> {
+    chrome.runtime.sendMessage({ action: AppAction.SAVE_ANALYTICS, record }).catch(() => {});
+  }
+  public async queryRecords(_filter: AnalyticsQueryFilter): Promise<AnalyticsRecord[]> {
+    return [];
+  }
+  public async clearRecordsOlderThan(_timestamp: number): Promise<void> {}
+}

src/background.ts

@@ -1,11 +1,12 @@
 import { StorageFacade } from './core/storage/index';
 import { ChromeStorageDriver } from './adapters/chrome/storage-driver';
-import { PlatformId, PLATFORMS_CONFIG } from './types';
+import { PlatformId, PLATFORMS_CONFIG, AppAction } from './types';
 import { ChromeAlarmManager } from './adapters/chrome/alarm-manager';
 import { ChromeTabManager } from './adapters/chrome/tab-manager';
 import { ChromeMessageBus } from './adapters/chrome/message-bus';
 import { BackgroundOrchestrator } from './core/background-orchestrator';
 import { IndexedDbAnalyticsRepository } from './adapters/browser/indexeddb-analytics';
+import { AnalyticsRecord } from './core/analytics/types';
 
 const alarmManager = new ChromeAlarmManager();
 const tabManager = new ChromeTabManager();
@@ -95,7 +96,15 @@ chrome.runtime.onInstalled.addListener(async () => {
 chrome.alarms.onAlarm.addListener(async (alarm) => {
   if (alarm.name === GC_ALARM_NAME) {
     if (storage.analyticsService) {
-      await storage.analyticsService.performGarbageCollection(7);
+      await storage.analyticsService.performGarbageCollection();
+    }
+  }
+});
+
+chrome.runtime.onMessage.addListener((message) => {
+  if (message.action === AppAction.SAVE_ANALYTICS && message.record) {
+    if (storage.analyticsService) {
+      void storage.analyticsService.saveRecord(message.record as AnalyticsRecord);
     }
   }
 });

src/content.ts

@@ -5,7 +5,7 @@ import { ChromeMessageBus } from './adapters/chrome/message-bus';
 import { ChromeConnectionManager } from './adapters/chrome/connection-manager';
 import { ChromeStorageDriver } from './adapters/chrome/storage-driver';
 import { StorageFacade } from './core/storage/index';
-import { IndexedDbAnalyticsRepository } from './adapters/browser/indexeddb-analytics';
+import { ChromeProxyAnalyticsRepository } from './adapters/chrome/proxy-analytics';
 
 declare global {
   interface Window {
@@ -20,7 +20,7 @@ if (!window.__LIMITRA_INJECTED__) {
     const storageDriver = new ChromeStorageDriver();
     const storage = new StorageFacade(storageDriver);
 
-    storage.setAnalyticsRepository(new IndexedDbAnalyticsRepository());
+    storage.setAnalyticsRepository(new ChromeProxyAnalyticsRepository());
 
     const messageBus = new ChromeMessageBus();
     const connectionManager = new ChromeConnectionManager();

src/core/analytics/aggregator.ts

@@ -34,4 +34,12 @@ export class AnalyticsAggregator {
     }
     return grouped;
   }
+
+  /**
+   * Abstracting the session calculation logic to protect us in case
+   * the definition of a session changes in the future
+   */
+  public static calculateSessionCount(records: AnalyticsRecord[]): number {
+    return records.length;
+  }
 }

src/core/analytics/formatter.ts

@@ -0,0 +1,44 @@
+export interface TimeTranslations {
+  hours: string;
+  minutes: string;
+}
+
+export class AnalyticsFormatter {
+  /**
+   * Convert milliseconds to a readable format (e.g., 2h 15m or 45m)
+   */
+  public static msToReadable(
+    ms: number,
+    t: TimeTranslations = { hours: 'h', minutes: 'm' },
+  ): string {
+    const totalMinutes = Math.floor(ms / (1000 * 60));
+    if (totalMinutes < 1) return `0${t.minutes}`;
+
+    const hours = Math.floor(totalMinutes / 60);
+    const mins = totalMinutes % 60;
+
+    if (hours > 0) {
+      return mins > 0 ? `${hours}${t.hours} ${mins}${t.minutes}` : `${hours}${t.hours}`;
+    }
+    return `${mins}${t.minutes}`;
+  }
+
+  /**
+   * Calculate the percentage change between two periods (e.g., today compared to yesterday)
+   * A positive result indicates an increase in usage, and a negative one indicates a decrease (improvement).
+   */
+  public static calculateTrendPercent(oldMs: number, newMs: number): number {
+    if (oldMs === 0) return newMs > 0 ? 100 : 0;
+    const difference = newMs - oldMs;
+    return Math.round((difference / oldMs) * 100);
+  }
+
+  /**
+   * Convert percentage to a formatted string with a sign (e.g., +15% or -32%)
+   */
+  public static formatTrend(trendPercent: number): string {
+    if (trendPercent > 0) return `+${trendPercent}%`;
+    if (trendPercent < 0) return `${trendPercent}%`;
+    return '0%';
+  }
+}

src/core/analytics/reports/dashboard-report.ts

@@ -0,0 +1,64 @@
+import { AnalyticsRepository } from '../../interfaces/analytics-repository';
+import { AnalyticsAggregator } from '../aggregator';
+import { AnalyticsFormatter, TimeTranslations } from '../formatter';
+
+export interface DashboardReportResult {
+  raw: {
+    todayMs: number;
+    yesterdayMs: number;
+    todaySessions: number;
+  };
+  formatted: {
+    todayReadable: string;
+    trendText: string;
+    isImproving: boolean;
+  };
+}
+
+export class DashboardReportGenerator {
+  constructor(private repo: AnalyticsRepository) {}
+
+  private async getUsageForDay(platformId: string, startOfDayMs: number) {
+    const endOfDayMs = startOfDayMs + 24 * 60 * 60 * 1000 - 1;
+    const records = await this.repo.queryRecords({
+      platformId: platformId,
+      fromTime: startOfDayMs,
+      toTime: endOfDayMs,
+    });
+
+    return {
+      duration: AnalyticsAggregator.calculateTotalDuration(records),
+      sessions: AnalyticsAggregator.calculateSessionCount(records),
+    };
+  }
+
+  public async generate(
+    platformId: string,
+    translations: TimeTranslations,
+  ): Promise<DashboardReportResult> {
+    const now = new Date();
+    const todayStart = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+    const yesterdayStart = todayStart - 24 * 60 * 60 * 1000;
+
+    const todayData = await this.getUsageForDay(platformId, todayStart);
+    const yesterdayData = await this.getUsageForDay(platformId, yesterdayStart);
+
+    const trendPercent = AnalyticsFormatter.calculateTrendPercent(
+      yesterdayData.duration,
+      todayData.duration,
+    );
+
+    return {
+      raw: {
+        todayMs: todayData.duration,
+        yesterdayMs: yesterdayData.duration,
+        todaySessions: todayData.sessions,
+      },
+      formatted: {
+        todayReadable: AnalyticsFormatter.msToReadable(todayData.duration, translations),
+        trendText: AnalyticsFormatter.formatTrend(trendPercent),
+        isImproving: trendPercent <= 0,
+      },
+    };
+  }
+}

src/core/analytics/service.ts

@@ -1,8 +1,19 @@
-import { AnalyticsRepository } from '../interfaces/analytics-repository';
 import { AnalyticsAggregator } from './aggregator';
+import { AnalyticsRepository } from '../interfaces/analytics-repository';
+import { SubscriptionService } from '../subscription/service';
+import { LimitType } from '../subscription/limits';
+import { DashboardReportGenerator } from './reports/dashboard-report';
+import { TimeTranslations } from './formatter';
 
 export class AnalyticsService {
-  constructor(private repo: AnalyticsRepository) {}
+  private dashboardReport: DashboardReportGenerator;
+
+  constructor(
+    private repo: AnalyticsRepository,
+    private subscriptionService: SubscriptionService,
+  ) {
+    this.dashboardReport = new DashboardReportGenerator(this.repo);
+  }
 
   /**
    * Retrieves the total usage time for the current day
@@ -81,7 +92,9 @@ export class AnalyticsService {
    * Removes old analytics data to save storage space (Garbage Collection).
    * By default, records older than 7 days will be deleted.
    */
-  public async performGarbageCollection(retentionDays: number = 7): Promise<void> {
+  public async performGarbageCollection(): Promise<void> {
+    const retentionDays = this.subscriptionService.getLimit(LimitType.ANALYTICS_RETENTION_DAYS);
+
     const cutoffTime = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
 
     await this.repo.clearRecordsOlderThan(cutoffTime);
@@ -90,4 +103,15 @@ export class AnalyticsService {
       `[Limitra Analytics] Garbage collection completed. Cleared records older than ${retentionDays} days.`,
     );
   }
+
+  /**
+   * Delegate dashboard report generation to the reporting layer
+   */
+  public async getDashboardReport(platformId: string, translations: TimeTranslations) {
+    return this.dashboardReport.generate(platformId, translations);
+  }
+
+  public async saveRecord(record: import('./types').AnalyticsRecord): Promise<void> {
+    return this.repo.saveRecord(record);
+  }
 }

src/core/session.ts

@@ -8,7 +8,6 @@ export class SessionManager {
   private adapter: PlatformAdapter;
   private lastActivityTime = Date.now();
   private lastHeartbeat = Date.now();
-  private lastSyncTime = Date.now();
   private isTracking = false;
   private isBlocked = false;
   private heartbeatId: ReturnType<typeof window.setInterval> | null = null;
@@ -84,27 +83,14 @@ export class SessionManager {
 
       if (now - this.lastHeartbeat > 5000 && this.isTracking) {
         console.warn('[Limitra] Sleep detected. Erasing time gap.');
-        await this.storage.startSession(this.adapter.id);
         this.lastHeartbeat = now;
-        this.lastSyncTime = now;
         return;
       }
 
       this.lastHeartbeat = now;
 
-      if (this.isTracking && now - this.lastSyncTime >= 10000) {
-        await this.storage.endSession(this.adapter.id);
-        await this.storage.startSession(this.adapter.id);
-        this.lastSyncTime = now;
-      }
-
-      if (document.hidden) return;
-
-      const isTimeEnabled = await this.storage.getEnableTime(this.adapter.id);
-      const timeLimit = await this.storage.getTimeLimit(this.adapter.id);
-
-      if (!isTimeEnabled || timeLimit <= 0) {
-        await this.stopTracking();
+      if (document.hidden) {
+        if (this.isTracking) await this.stopTracking();
         return;
       }
 
@@ -117,8 +103,15 @@ export class SessionManager {
       else if (mode === 'playing_only') shouldTrack = isPlaying;
       else if (mode === 'smart') shouldTrack = isPlaying || !isIdle;
 
-      if (shouldTrack) await this.startTracking();
-      else await this.stopTracking();
+      if (shouldTrack) {
+        if (!this.isTracking) {
+          await this.startTracking();
+        } else {
+          await this.storage.updateSessionTime(this.adapter.id);
+        }
+      } else {
+        if (this.isTracking) await this.stopTracking();
+      }
     }, 2000);
   }
 

src/core/storage/index.ts

@@ -6,19 +6,22 @@ import { SecurityStorage } from './security';
 import { PlatformId, PLATFORMS_CONFIG } from '../../types';
 import { AnalyticsRepository } from '../interfaces/analytics-repository';
 import { AnalyticsService } from '../analytics/service';
+import { SubscriptionService } from '../subscription/service';
 
 export class StorageFacade {
   public settings: SettingsStorage;
   public stats: StatsStorage;
   public session: SessionStorage;
   public security: SecurityStorage;
   public analyticsService?: AnalyticsService;
+  public subscriptionService: SubscriptionService;
 
   constructor(public driver: StorageDriver) {
     this.settings = new SettingsStorage(this.driver);
     this.stats = new StatsStorage(this.driver);
     this.session = new SessionStorage(this.driver, this.stats);
     this.security = new SecurityStorage(this.driver, this.stats);
+    this.subscriptionService = new SubscriptionService();
   }
 
   /**
@@ -205,7 +208,7 @@ export class StorageFacade {
   // Analytics & Dependencies
   public setAnalyticsRepository(repo: AnalyticsRepository): void {
     this.session.setAnalyticsRepository(repo);
-    this.analyticsService = new AnalyticsService(repo);
+    this.analyticsService = new AnalyticsService(repo, this.subscriptionService);
   }
 
   // Sessions
@@ -226,6 +229,9 @@ export class StorageFacade {
   async getNextResetTime() {
     return this.session.getNextResetTime();
   }
+  async updateSessionTime(platform: PlatformId) {
+    return this.session.updateSessionTime(platform);
+  }
 
   // Security
   async detectBypass(platform: PlatformId) {

src/core/storage/session.ts

@@ -89,21 +89,19 @@ export class SessionStorage {
             })
             .catch(() => {});
         }
-      }, 60000);
-
+      }, 5000);
       this.activeSessions.get(platform)!.interval = interval;
     }
   }
 
   async endSession(platform: PlatformId): Promise<number> {
     const key = `limitra_${platform}_last_active`;
     const last = await this.driver.get<number>(key);
-
     const activeSession = this.activeSessions.get(platform);
+
     if (activeSession) {
       if (activeSession.interval) clearInterval(activeSession.interval);
-
-      if (this.analyticsRepo && last && last !== 0) {
+      if (this.analyticsRepo) {
         const currentTime = Date.now();
         await this.analyticsRepo
           .saveRecord({
@@ -123,6 +121,7 @@ export class SessionStorage {
     const delta = Date.now() - last;
     await this.stats.addTime(platform, delta);
     await this.driver.set<number>(key, 0);
+
     return delta;
   }
 
@@ -134,4 +133,16 @@ export class SessionStorage {
     const intervalMs = await this.getDurationMs();
     return lastReset + intervalMs;
   }
+
+  async updateSessionTime(platform: PlatformId): Promise<void> {
+    const key = `limitra_${platform}_last_active`;
+    const last = await this.driver.get<number>(key);
+    if (!last || last === 0) return;
+
+    const now = Date.now();
+    const delta = now - last;
+
+    await this.stats.addTime(platform, delta);
+    await this.driver.set<number>(key, now);
+  }
 }