lean-claudient-core 0.1.0

package/src/automation/alertSystem.ts

@@ -0,0 +1,402 @@
+/**
+ * Real-Time Alert System
+ * Detects and queues alerts for business events
+ * No autonomous execution - human approval required (Composio integration)
+ * Phase 8B Task 5
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import { AuditLogger } from '../core/auditLogger.js';
+import { EnrichedLead } from '../intelligence/leadEnrichmentTypes.js';
+import { RevenueProjection, PortfolioForecast } from '../metrics/revenueTypes.js';
+import {
+  AlertThresholds,
+  DEFAULT_THRESHOLDS,
+  validateThresholds,
+  ALERT_SEVERITY_MAP,
+  AlertSeverity,
+} from './alertRules.js';
+
+/**
+ * Alert object structure
+ */
+export interface Alert {
+  id: string;
+  type: 'high-quality-lead' | 'threat-escalation' | 'revenue-milestone' | 'market-trend-urgent';
+  severity: AlertSeverity;
+  message: string;
+  queuedAt: string;
+  action: {
+    tool: string; // 'slack', 'gmail'
+    payload: Record<string, any>;
+  };
+  context?: Record<string, any>;
+}
+
+/**
+ * Threat score history for escalation detection
+ */
+interface ThreatScoreHistory {
+  leadId: string;
+  previousScore: number;
+  previousLevel: string;
+}
+
+/**
+ * Alert System class
+ */
+export class AlertSystem {
+  private thresholds: AlertThresholds;
+  private auditLogger: AuditLogger;
+  private alertQueue: Alert[] = [];
+  private threatHistory: Map<string, ThreatScoreHistory> = new Map();
+  private revenueCheckpoint: number = 0;
+
+  constructor(thresholds?: Partial<AlertThresholds>) {
+    this.thresholds = validateThresholds(thresholds || {});
+    this.auditLogger = new AuditLogger();
+  }
+
+  /**
+   * Check if a lead qualifies as high-quality
+   */
+  checkLeadQuality(enrichedLead: EnrichedLead): Alert | null {
+    if (
+      enrichedLead.score >= this.thresholds.highQualityLeadThreshold &&
+      enrichedLead.signalCount >= this.thresholds.highQualityMinSignals
+    ) {
+      const alert: Alert = {
+        id: uuidv4(),
+        type: 'high-quality-lead',
+        severity: 'info',
+        message: `🎯 Hot lead: ${enrichedLead.company || enrichedLead.name} (${enrichedLead.score}%) – ${enrichedLead.signalCount} signals – Revenue: $${
+          enrichedLead.score * 500
+        }k`,
+        queuedAt: new Date().toISOString(),
+        action: {
+          tool: 'slack',
+          payload: {
+            channel: '#leads',
+            text: `🎯 Hot lead: ${enrichedLead.company || enrichedLead.name} (${Math.round(enrichedLead.score)}%) – ${enrichedLead.signalCount} signals – Revenue: $${Math.round(enrichedLead.score * 500)}k`,
+          },
+        },
+        context: {
+          leadId: enrichedLead.id,
+          company: enrichedLead.company,
+          quality: enrichedLead.score,
+          signals: enrichedLead.signalCount,
+        },
+      };
+
+      this.auditLogger.log({
+        event: 'alert:high-quality-lead',
+        alertId: alert.id,
+        leadId: enrichedLead.id,
+        quality: enrichedLead.score,
+        signals: enrichedLead.signalCount,
+      });
+
+      return alert;
+    }
+
+    return null;
+  }
+
+  /**
+   * Check for threat escalation
+   */
+  checkThreatEscalation(
+    leadId: string,
+    newScore: number,
+    threatLevel: string,
+    company?: string
+  ): Alert | null {
+    const history = this.threatHistory.get(leadId);
+
+    // Determine threat level from score
+    const levels = this.thresholds.threatEscalationLevels;
+    const oldLevel = history?.previousLevel || 'NONE';
+
+    // Check if escalation occurred
+    const escalated = this.isEscalation(oldLevel, threatLevel);
+
+    if (escalated && history) {
+      const alert: Alert = {
+        id: uuidv4(),
+        type: 'threat-escalation',
+        severity: 'critical',
+        message: `⚠️ THREAT ESCALATION: ${company || 'Lead'} now ${threatLevel} (was ${oldLevel}) – Score: ${Math.round(newScore)}/100`,
+        queuedAt: new Date().toISOString(),
+        action: {
+          tool: 'slack',
+          payload: {
+            channel: '#security',
+            text: `⚠️ THREAT ESCALATION: ${company || 'Lead'} now ${threatLevel} (was ${oldLevel}) – Score: ${Math.round(newScore)}/100`,
+          },
+        },
+        context: {
+          leadId,
+          company,
+          oldLevel,
+          newLevel: threatLevel,
+          newScore,
+        },
+      };
+
+      this.auditLogger.log({
+        event: 'alert:threat-escalation',
+        alertId: alert.id,
+        leadId,
+        fromLevel: oldLevel,
+        toLevel: threatLevel,
+        score: newScore,
+      });
+
+      return alert;
+    }
+
+    // Update history
+    this.threatHistory.set(leadId, {
+      leadId,
+      previousScore: newScore,
+      previousLevel: threatLevel,
+    });
+
+    return null;
+  }
+
+  /**
+   * Check for revenue milestones
+   */
+  checkRevenueMilestones(portfolio: PortfolioForecast): Alert[] {
+    const alerts: Alert[] = [];
+    const currentRevenue = portfolio.totalProjectedRevenue;
+
+    for (const milestone of this.thresholds.revenueMilestones) {
+      // Check if we've crossed this milestone
+      if (currentRevenue >= milestone && this.revenueCheckpoint < milestone) {
+        const alert: Alert = {
+          id: uuidv4(),
+          type: 'revenue-milestone',
+          severity: 'info',
+          message: `💰 Revenue milestone unlocked: $${(milestone / 1000).toFixed(0)}k projected from ${portfolio.leadCount} leads`,
+          queuedAt: new Date().toISOString(),
+          action: {
+            tool: 'slack',
+            payload: {
+              channel: '#revenue',
+              text: `💰 Revenue milestone unlocked: $${(milestone / 1000).toFixed(0)}k projected from ${portfolio.leadCount} leads`,
+            },
+          },
+          context: {
+            milestone,
+            currentRevenue,
+            leadCount: portfolio.leadCount,
+          },
+        };
+
+        this.auditLogger.log({
+          event: 'alert:revenue-milestone',
+          alertId: alert.id,
+          milestone,
+          currentRevenue,
+        });
+
+        alerts.push(alert);
+      }
+    }
+
+    // Update checkpoint
+    if (currentRevenue > this.revenueCheckpoint) {
+      this.revenueCheckpoint = currentRevenue;
+    }
+
+    return alerts;
+  }
+
+  /**
+   * Check for market trend urgency
+   */
+  checkMarketTrends(
+    trends: Array<{
+      trend: string;
+      velocity: number; // mentions/week
+      confidence: number; // 0-100
+    }>
+  ): Alert[] {
+    const alerts: Alert[] = [];
+
+    trends.forEach((trend) => {
+      if (
+        trend.velocity >= this.thresholds.marketTrendVelocityThreshold &&
+        trend.confidence >= this.thresholds.marketTrendConfidenceThreshold
+      ) {
+        const alert: Alert = {
+          id: uuidv4(),
+          type: 'market-trend-urgent',
+          severity: 'warning',
+          message: `📈 Trending: ${trend.trend} – ${Math.round(trend.velocity)} mentions/week – ${Math.round(trend.confidence)}% confidence`,
+          queuedAt: new Date().toISOString(),
+          action: {
+            tool: 'slack',
+            payload: {
+              channel: '#intelligence',
+              text: `📈 Trending: ${trend.trend} – ${Math.round(trend.velocity)} mentions/week – ${Math.round(trend.confidence)}% confidence`,
+            },
+          },
+          context: {
+            trend: trend.trend,
+            velocity: trend.velocity,
+            confidence: trend.confidence,
+          },
+        };
+
+        this.auditLogger.log({
+          event: 'alert:market-trend-urgent',
+          alertId: alert.id,
+          trend: trend.trend,
+          velocity: trend.velocity,
+          confidence: trend.confidence,
+        });
+
+        alerts.push(alert);
+      }
+    });
+
+    return alerts;
+  }
+
+  /**
+   * Queue an alert (no immediate execution, human approval required)
+   */
+  queueAlert(alert: Alert): Alert {
+    this.alertQueue.push(alert);
+
+    this.auditLogger.log({
+      event: 'alert:queued',
+      alertId: alert.id,
+      type: alert.type,
+      severity: alert.severity,
+      timestamp: alert.queuedAt,
+    });
+
+    return alert;
+  }
+
+  /**
+   * Get all pending alerts
+   */
+  getPendingAlerts(): Alert[] {
+    return [...this.alertQueue];
+  }
+
+  /**
+   * Clear all alerts (after processing)
+   */
+  clearAlerts(): void {
+    const count = this.alertQueue.length;
+    this.alertQueue = [];
+
+    this.auditLogger.log({
+      event: 'alerts:cleared',
+      count,
+    });
+  }
+
+  /**
+   * Get alert by ID
+   */
+  getAlert(id: string): Alert | undefined {
+    return this.alertQueue.find((a) => a.id === id);
+  }
+
+  /**
+   * Remove alert from queue
+   */
+  removeAlert(id: string): boolean {
+    const idx = this.alertQueue.findIndex((a) => a.id === id);
+    if (idx >= 0) {
+      this.alertQueue.splice(idx, 1);
+      this.auditLogger.log({
+        event: 'alert:removed',
+        alertId: id,
+      });
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get alerts by type
+   */
+  getAlertsByType(type: Alert['type']): Alert[] {
+    return this.alertQueue.filter((a) => a.type === type);
+  }
+
+  /**
+   * Get alerts by severity
+   */
+  getAlertsBySeverity(severity: AlertSeverity): Alert[] {
+    return this.alertQueue.filter((a) => a.severity === severity);
+  }
+
+  /**
+   * Update thresholds
+   */
+  updateThresholds(thresholds: Partial<AlertThresholds>): void {
+    this.thresholds = validateThresholds(thresholds);
+    this.auditLogger.log({
+      event: 'alert:thresholds-updated',
+      thresholds: this.thresholds,
+    });
+  }
+
+  /**
+   * Get current thresholds
+   */
+  getThresholds(): AlertThresholds {
+    return { ...this.thresholds };
+  }
+
+  /**
+   * Helper: Check if threat escalated
+   */
+  private isEscalation(oldLevel: string, newLevel: string): boolean {
+    const levels = ['NONE', 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
+    const oldIdx = levels.indexOf(oldLevel);
+    const newIdx = levels.indexOf(newLevel);
+    return newIdx > oldIdx;
+  }
+
+  /**
+   * Get summary statistics
+   */
+  getSummaryStats(): {
+    totalQueued: number;
+    byType: Record<string, number>;
+    bySeverity: Record<AlertSeverity, number>;
+  } {
+    const byType: Record<string, number> = {};
+    const bySeverity: Record<AlertSeverity, number> = { info: 0, warning: 0, critical: 0 };
+
+    this.alertQueue.forEach((alert) => {
+      byType[alert.type] = (byType[alert.type] || 0) + 1;
+      bySeverity[alert.severity]++;
+    });
+
+    return {
+      totalQueued: this.alertQueue.length,
+      byType,
+      bySeverity,
+    };
+  }
+}
+
+/**
+ * Factory function
+ */
+export function createAlertSystem(thresholds?: Partial<AlertThresholds>): AlertSystem {
+  return new AlertSystem(thresholds);
+}
+
+export default AlertSystem;