lean-claudient-core 0.1.0

package/src/metrics/businessMetricsAgg.ts

@@ -0,0 +1,554 @@
+/**
+ * Business Metrics Aggregator
+ * Centralizes KPI tracking: funnels, revenue, threats, signals
+ * Phase 8B Task 4
+ */
+
+import { writeFileSync, mkdirSync } from 'fs';
+import { resolve } from 'path';
+import { v4 as uuidv4 } from 'uuid';
+import { AuditLogger } from '../core/auditLogger.js';
+import { EnrichedLead } from '../intelligence/leadEnrichmentTypes.js';
+import { RevenueProjection, PortfolioForecast } from './revenueTypes.js';
+import {
+  DashboardMetrics,
+  FunnelMetrics,
+  FunnelStage,
+  RevenueBySource,
+  RevenueByStage,
+  ThreatDistribution,
+  SignalEffectiveness,
+  MetricsCSVRow,
+} from './metricsTypes.js';
+
+/**
+ * Business Metrics Aggregator class
+ */
+export class BusinessMetrics {
+  private auditLogger: AuditLogger;
+  private enrichedLeads: Map<string, EnrichedLead> = new Map();
+  private projections: Map<string, RevenueProjection> = new Map();
+  private qualifiedLeadsByStage: Map<FunnelStage, Set<string>> = new Map([
+    ['cold', new Set()],
+    ['warm', new Set()],
+    ['hot', new Set()],
+    ['sales-ready', new Set()],
+  ]);
+
+  constructor() {
+    this.auditLogger = new AuditLogger();
+  }
+
+  /**
+   * Load enriched leads
+   */
+  loadEnrichedLeads(leads: EnrichedLead[]): void {
+    leads.forEach((lead) => {
+      this.enrichedLeads.set(lead.id, lead);
+    });
+    this.auditLogger.log({
+      event: 'metrics:loaded-enriched-leads',
+      count: leads.length,
+    });
+  }
+
+  /**
+   * Load revenue projections
+   */
+  loadProjections(projections: RevenueProjection[]): void {
+    projections.forEach((proj) => {
+      this.projections.set(proj.leadId, proj);
+    });
+    this.auditLogger.log({
+      event: 'metrics:loaded-projections',
+      count: projections.length,
+    });
+  }
+
+  /**
+   * Assign leads to qualification stages
+   */
+  assignQualificationStages(
+    stageMap: Map<string, FunnelStage>
+  ): void {
+    this.qualifiedLeadsByStage.forEach((set) => set.clear());
+
+    stageMap.forEach((stage, leadId) => {
+      const stageSet = this.qualifiedLeadsByStage.get(stage);
+      if (stageSet) {
+        stageSet.add(leadId);
+      }
+    });
+
+    this.auditLogger.log({
+      event: 'metrics:assigned-stages',
+      cold: this.qualifiedLeadsByStage.get('cold')!.size,
+      warm: this.qualifiedLeadsByStage.get('warm')!.size,
+      hot: this.qualifiedLeadsByStage.get('hot')!.size,
+      salesReady: this.qualifiedLeadsByStage.get('sales-ready')!.size,
+    });
+  }
+
+  /**
+   * Calculate funnel metrics
+   */
+  calculateFunnel(): { stages: FunnelMetrics[]; coldToSalesReady: number } {
+    const stages: FunnelMetrics[] = [];
+    const stageOrder: FunnelStage[] = ['cold', 'warm', 'hot', 'sales-ready'];
+    const stageCounts: Record<FunnelStage, number> = {
+      cold: this.qualifiedLeadsByStage.get('cold')!.size,
+      warm: this.qualifiedLeadsByStage.get('warm')!.size,
+      hot: this.qualifiedLeadsByStage.get('hot')!.size,
+      'sales-ready': this.qualifiedLeadsByStage.get('sales-ready')!.size,
+    };
+
+    const totalLeads = Object.values(stageCounts).reduce((a, b) => a + b, 0);
+
+    for (let i = 0; i < stageOrder.length; i++) {
+      const stage = stageOrder[i];
+      const count = stageCounts[stage];
+      const percentage = totalLeads > 0 ? (count / totalLeads) * 100 : 0;
+
+      // Conversion rate to next stage
+      const nextStageCount =
+        i < stageOrder.length - 1 ? stageCounts[stageOrder[i + 1]] : 0;
+      const conversionRate = count > 0 ? nextStageCount / count : 0;
+
+      // Calculate average quality and revenue for stage
+      const stageLeads = Array.from(
+        this.qualifiedLeadsByStage.get(stage)!
+      ).map((leadId) => this.enrichedLeads.get(leadId)!);
+
+      const avgQuality =
+        stageLeads.length > 0
+          ? stageLeads.reduce((sum, lead) => sum + (lead.score || 0), 0) /
+            stageLeads.length
+          : 0;
+
+      const avgRevenue =
+        stageLeads.length > 0
+          ? stageLeads.reduce(
+              (sum, lead) =>
+                sum + (this.projections.get(lead.id)?.projectedRevenue || 0),
+              0
+            ) / stageLeads.length
+          : 0;
+
+      stages.push({
+        stage,
+        count,
+        percentage,
+        conversionRate,
+        avgQuality,
+        avgRevenue,
+      });
+    }
+
+    // Calculate overall cold-to-sales-ready conversion
+    const coldCount = stageCounts.cold;
+    const salesReadyCount = stageCounts['sales-ready'];
+    const coldToSalesReady = coldCount > 0 ? salesReadyCount / coldCount : 0;
+
+    return { stages, coldToSalesReady };
+  }
+
+  /**
+   * Aggregate revenue by dimension
+   */
+  aggregateRevenue(dimension: 'source' | 'stage'): {
+    bySource?: RevenueBySource[];
+    byStage?: RevenueByStage[];
+    total: number;
+  } {
+    if (dimension === 'source') {
+      const bySourceMap: Map<
+        string,
+        {
+          totalRevenue: number;
+          leads: string[];
+          confidences: number[];
+        }
+      > = new Map();
+
+      this.enrichedLeads.forEach((lead) => {
+        const source = lead.source || 'unknown';
+        if (!bySourceMap.has(source)) {
+          bySourceMap.set(source, {
+            totalRevenue: 0,
+            leads: [],
+            confidences: [],
+          });
+        }
+
+        const data = bySourceMap.get(source)!;
+        const projection = this.projections.get(lead.id);
+        if (projection) {
+          data.totalRevenue += projection.projectedRevenue;
+          data.confidences.push(projection.confidence);
+        }
+        data.leads.push(lead.id);
+      });
+
+      const bySource: RevenueBySource[] = Array.from(bySourceMap.entries()).map(
+        ([source, data]) => ({
+          source,
+          totalRevenue: data.totalRevenue,
+          leadCount: data.leads.length,
+          avgRevenue:
+            data.leads.length > 0 ? data.totalRevenue / data.leads.length : 0,
+          confidence:
+            data.confidences.length > 0
+              ? data.confidences.reduce((a, b) => a + b, 0) /
+                data.confidences.length
+              : 0,
+        })
+      );
+
+      const total = bySource.reduce((sum, item) => sum + item.totalRevenue, 0);
+      return { bySource, total };
+    } else {
+      // By stage
+      const byStageData: Record<FunnelStage, {
+        totalRevenue: number;
+        leads: string[];
+        confidences: number[];
+      }> = {
+        cold: { totalRevenue: 0, leads: [], confidences: [] },
+        warm: { totalRevenue: 0, leads: [], confidences: [] },
+        hot: { totalRevenue: 0, leads: [], confidences: [] },
+        'sales-ready': { totalRevenue: 0, leads: [], confidences: [] },
+      };
+
+      this.qualifiedLeadsByStage.forEach((leadSet, stage) => {
+        leadSet.forEach((leadId) => {
+          const projection = this.projections.get(leadId);
+          if (projection) {
+            byStageData[stage].totalRevenue += projection.projectedRevenue;
+            byStageData[stage].confidences.push(projection.confidence);
+          }
+          byStageData[stage].leads.push(leadId);
+        });
+      });
+
+      const byStage: RevenueByStage[] = Object.entries(byStageData).map(
+        ([stage, data]) => ({
+          stage: stage as FunnelStage,
+          totalRevenue: data.totalRevenue,
+          leadCount: data.leads.length,
+          avgRevenue:
+            data.leads.length > 0 ? data.totalRevenue / data.leads.length : 0,
+          confidence:
+            data.confidences.length > 0
+              ? data.confidences.reduce((a, b) => a + b, 0) /
+                data.confidences.length
+              : 0,
+        })
+      );
+
+      const total = byStage.reduce((sum, item) => sum + item.totalRevenue, 0);
+      return { byStage, total };
+    }
+  }
+
+  /**
+   * Get competitor threat distribution
+   */
+  getCompetitorThreatDistribution(): ThreatDistribution {
+    const distribution: ThreatDistribution = {
+      CRITICAL: 0,
+      HIGH: 0,
+      MEDIUM: 0,
+      LOW: 0,
+      NONE: 0,
+    };
+
+    this.enrichedLeads.forEach((lead) => {
+      const threatLevel = lead.threatLevel || 'NONE';
+      if (threatLevel in distribution) {
+        distribution[threatLevel as keyof ThreatDistribution]++;
+      }
+    });
+
+    return distribution;
+  }
+
+  /**
+   * Calculate signal effectiveness
+   */
+  getSignalEffectiveness(): SignalEffectiveness[] {
+    const signalMap: Map<
+      string,
+      {
+        matches: Set<string>;
+        qualityScores: number[];
+        revenues: number[];
+      }
+    > = new Map();
+
+    this.enrichedLeads.forEach((lead) => {
+      if (!lead.marketSignals) return;
+
+      lead.marketSignals.forEach((signal) => {
+        const signalKey = signal.trend;
+        if (!signalMap.has(signalKey)) {
+          signalMap.set(signalKey, {
+            matches: new Set(),
+            qualityScores: [],
+            revenues: [],
+          });
+        }
+
+        const data = signalMap.get(signalKey)!;
+        data.matches.add(lead.id);
+        data.qualityScores.push(lead.score || 0);
+
+        const projection = this.projections.get(lead.id);
+        if (projection) {
+          data.revenues.push(projection.projectedRevenue);
+        }
+      });
+    });
+
+    const signals: SignalEffectiveness[] = Array.from(
+      signalMap.entries()
+    ).map(([signal, data]) => {
+      const avgQuality =
+        data.qualityScores.length > 0
+          ? data.qualityScores.reduce((a, b) => a + b, 0) /
+            data.qualityScores.length
+          : 0;
+
+      const totalRevenue =
+        data.revenues.length > 0
+          ? data.revenues.reduce((a, b) => a + b, 0)
+          : 0;
+
+      const avgRevenue =
+        data.revenues.length > 0 ? totalRevenue / data.revenues.length : 0;
+
+      // Rough ROI: revenue / effort (signal matches)
+      const roi = data.matches.size > 0 ? totalRevenue / data.matches.size : 0;
+
+      // Conversion rate: salesReady / matches
+      const salesReadyMatches = Array.from(data.matches).filter((leadId) =>
+        this.qualifiedLeadsByStage.get('sales-ready')!.has(leadId)
+      );
+      const conversionRate =
+        data.matches.size > 0 ? salesReadyMatches.length / data.matches.size : 0;
+
+      return {
+        signal,
+        matchCount: data.matches.size,
+        conversionRate,
+        avgQuality,
+        avgRevenue,
+        roi,
+      };
+    });
+
+    return signals.sort((a, b) => b.roi - a.roi);
+  }
+
+  /**
+   * Generate complete dashboard data
+   */
+  generateDashboardData(portfolio: PortfolioForecast): DashboardMetrics {
+    const funnelData = this.calculateFunnel();
+    const revenueBySource = this.aggregateRevenue('source').bySource || [];
+    const revenueByStage = this.aggregateRevenue('stage').byStage || [];
+    const threatDistribution = this.getCompetitorThreatDistribution();
+    const signals = this.getSignalEffectiveness();
+
+    // Calculate threat percentages
+    const totalLeads = this.enrichedLeads.size;
+    const criticalCount = threatDistribution.CRITICAL;
+    const highCount = threatDistribution.HIGH;
+
+    // Top leads
+    const topLeads = Array.from(this.enrichedLeads.values())
+      .map((lead) => ({
+        leadId: lead.id,
+        name: lead.name,
+        company: lead.company || 'Unknown',
+        projectedRevenue: this.projections.get(lead.id)?.projectedRevenue || 0,
+        quality: lead.score || 0,
+        stage: this.getLeadStage(lead.id),
+      }))
+      .sort((a, b) => b.projectedRevenue - a.projectedRevenue)
+      .slice(0, 10);
+
+    const dashboard: DashboardMetrics = {
+      generatedAt: new Date().toISOString(),
+      totalLeads,
+      totalProjectedRevenue: portfolio.totalProjectedRevenue,
+
+      funnel: {
+        stages: funnelData.stages,
+        coldToSalesReady: funnelData.coldToSalesReady,
+      },
+
+      revenue: {
+        bySource: revenueBySource,
+        byStage: revenueByStage,
+        topLeads,
+      },
+
+      threats: {
+        distribution: threatDistribution,
+        percentByCritical: totalLeads > 0 ? (criticalCount / totalLeads) * 100 : 0,
+        percentByHigh: totalLeads > 0 ? (highCount / totalLeads) * 100 : 0,
+      },
+
+      signals: {
+        effectiveness: signals,
+        topPerforming: signals.slice(0, 5),
+        totalSignalMatches: Array.from(this.enrichedLeads.values()).reduce(
+          (sum, lead) => sum + (lead.signalCount || 0),
+          0
+        ),
+      },
+
+      timeline: {
+        avgDaysColdToSalesReady: undefined, // Requires transition history
+        estimatedTimeToConversion: undefined,
+      },
+
+      portfolio,
+    };
+
+    this.auditLogger.log({
+      event: 'metrics:dashboard-generated',
+      totalLeads,
+      totalRevenue: portfolio.totalProjectedRevenue,
+      timestamp: dashboard.generatedAt,
+    });
+
+    return dashboard;
+  }
+
+  /**
+   * Export metrics to JSON
+   */
+  exportJSON(metrics: DashboardMetrics, outputPath: string): string {
+    const dir = resolve(outputPath, '..');
+    mkdirSync(dir, { recursive: true });
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const filePath = resolve(outputPath, `dashboard-${timestamp}.json`);
+
+    writeFileSync(filePath, JSON.stringify(metrics, null, 2), 'utf-8');
+
+    this.auditLogger.log({
+      event: 'metrics:exported-json',
+      path: filePath,
+    });
+
+    return filePath;
+  }
+
+  /**
+   * Export metrics to CSV
+   */
+  exportCSV(outputPath: string): string {
+    const dir = resolve(outputPath, '..');
+    mkdirSync(dir, { recursive: true });
+
+    const rows: MetricsCSVRow[] = Array.from(this.enrichedLeads.values()).map(
+      (lead) => ({
+        leadId: lead.id,
+        name: lead.name,
+        company: lead.company || 'Unknown',
+        quality: lead.score || 0,
+        stage: this.getLeadStage(lead.id),
+        projectedRevenue: this.projections.get(lead.id)?.projectedRevenue || 0,
+        threatLevel: lead.threatLevel || 'NONE',
+        signalCount: lead.signalCount || 0,
+        source: lead.source || 'unknown',
+        enrichedAt: lead.enrichedAt || '',
+      })
+    );
+
+    const headers = Object.keys(rows[0] || {});
+    const csvContent = [
+      headers.join(','),
+      ...rows.map((row) =>
+        headers
+          .map((header) => {
+            const value = (row as any)[header];
+            if (typeof value === 'string' && value.includes(',')) {
+              return `"${value}"`;
+            }
+            return value;
+          })
+          .join(',')
+      ),
+    ].join('\n');
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const filePath = resolve(outputPath, `metrics-${timestamp}.csv`);
+
+    writeFileSync(filePath, csvContent, 'utf-8');
+
+    this.auditLogger.log({
+      event: 'metrics:exported-csv',
+      path: filePath,
+      rowCount: rows.length,
+    });
+
+    return filePath;
+  }
+
+  /**
+   * Get lead's current stage
+   */
+  private getLeadStage(leadId: string): FunnelStage {
+    for (const [stage, leadSet] of this.qualifiedLeadsByStage.entries()) {
+      if (leadSet.has(leadId)) {
+        return stage;
+      }
+    }
+    return 'cold';
+  }
+
+  /**
+   * Get summary statistics
+   */
+  getSummaryStats(): {
+    totalLeads: number;
+    totalRevenue: number;
+    avgLeadQuality: number;
+    avgSignalCount: number;
+    threatCriticalCount: number;
+  } {
+    const threats = this.getCompetitorThreatDistribution();
+    const leads = Array.from(this.enrichedLeads.values());
+
+    return {
+      totalLeads: leads.length,
+      totalRevenue: Array.from(this.projections.values()).reduce(
+        (sum, proj) => sum + proj.projectedRevenue,
+        0
+      ),
+      avgLeadQuality:
+        leads.length > 0
+          ? leads.reduce((sum, lead) => sum + (lead.score || 0), 0) /
+            leads.length
+          : 0,
+      avgSignalCount:
+        leads.length > 0
+          ? leads.reduce((sum, lead) => sum + (lead.signalCount || 0), 0) /
+            leads.length
+          : 0,
+      threatCriticalCount: threats.CRITICAL,
+    };
+  }
+}
+
+/**
+ * Factory function
+ */
+export function createBusinessMetrics(): BusinessMetrics {
+  return new BusinessMetrics();
+}
+
+export default BusinessMetrics;