lean-claudient-core 0.1.0

package/src/metrics/revenueProjection.ts

@@ -0,0 +1,319 @@
+/**
+ * Revenue Projection Engine
+ * Forecasts revenue per lead and portfolio-level projections
+ * Phase 8A Task 2
+ */
+
+import { z } from 'zod';
+import { EnrichedLead } from '../intelligence/leadEnrichmentTypes.js';
+import {
+  RevenueProjection,
+  ProjectionFactors,
+  PortfolioForecast,
+  ProjectionConfig,
+} from './revenueTypes.js';
+
+/**
+ * Validation schemas
+ */
+const ProjectionFactorsSchema = z.object({
+  baseValue: z.number().nonnegative(),
+  threatMultiplier: z.number().min(0.0).max(1.0),
+  signalBoost: z.number().min(1.0).max(1.2),
+  confidenceScore: z.number().min(0).max(100),
+});
+
+const RevenueProjectionSchema = z.object({
+  leadId: z.string().min(1),
+  projectedRevenue: z.number().nonnegative(),
+  confidence: z.number().min(0).max(100),
+  factors: ProjectionFactorsSchema,
+  acv: z.number().positive(),
+  conversionRate: z.number().min(0).max(1),
+  calculatedAt: z.string().datetime(),
+});
+
+const PortfolioForecastSchema = z.object({
+  totalProjectedRevenue: z.number().nonnegative(),
+  leadCount: z.number().nonnegative(),
+  avgRevenuePerLead: z.number().nonnegative(),
+  confidenceLevel: z.number().min(0).max(100),
+  byThreatLevel: z.record(
+    z.object({
+      count: z.number().nonnegative(),
+      projectedRevenue: z.number().nonnegative(),
+      avgConfidence: z.number().min(0).max(100),
+    })
+  ),
+  bySource: z.record(
+    z.object({
+      count: z.number().nonnegative(),
+      projectedRevenue: z.number().nonnegative(),
+      avgConfidence: z.number().min(0).max(100),
+    })
+  ),
+  topLeads: z.array(
+    z.object({
+      leadId: z.string(),
+      name: z.string(),
+      company: z.string(),
+      projectedRevenue: z.number().nonnegative(),
+    })
+  ),
+  generatedAt: z.string().datetime(),
+});
+
+/**
+ * Revenue Projector class
+ */
+export class RevenueProjector {
+  private config: Required<ProjectionConfig>;
+
+  constructor(config: ProjectionConfig = {}) {
+    this.config = {
+      defaultACV: config.defaultACV ?? 50000,
+      defaultConversionRate: config.defaultConversionRate ?? 0.15,
+      threatReductionFactor: config.threatReductionFactor ?? 0.3,
+      signalBoostFactor: config.signalBoostFactor ?? 0.2,
+    };
+  }
+
+  /**
+   * Project revenue for a single enriched lead
+   */
+  projectLead(
+    enrichedLead: EnrichedLead,
+    acv?: number,
+    conversionRate?: number
+  ): RevenueProjection {
+    const usedAcv = acv ?? this.config.defaultACV;
+    const usedConversionRate = conversionRate ?? this.config.defaultConversionRate;
+
+    // Calculate base value
+    const leadQuality = Math.min(enrichedLead.score / 100, 1.0);
+    const baseValue = leadQuality * usedConversionRate * usedAcv;
+
+    // Calculate threat multiplier
+    const threatScore = enrichedLead.competitorThreat?.threatScore ?? 0;
+    const threatMultiplier = 1 - (threatScore / 100) * this.config.threatReductionFactor;
+
+    // Calculate signal boost
+    const signalBoost = 1 + (enrichedLead.signalCount / 10) * this.config.signalBoostFactor;
+
+    // Calculate confidence
+    const confidence = this.calculateConfidence(enrichedLead, threatMultiplier, signalBoost);
+
+    // Calculate projected revenue
+    const projectedRevenue = baseValue * threatMultiplier * signalBoost;
+
+    const factors: ProjectionFactors = {
+      baseValue,
+      threatMultiplier,
+      signalBoost,
+      confidenceScore: confidence,
+    };
+
+    const projection: RevenueProjection = {
+      leadId: enrichedLead.id,
+      projectedRevenue,
+      confidence,
+      factors,
+      acv: usedAcv,
+      conversionRate: usedConversionRate,
+      calculatedAt: new Date().toISOString(),
+    };
+
+    // Validate output
+    try {
+      RevenueProjectionSchema.parse(projection);
+    } catch (error) {
+      throw new Error(`Revenue projection validation failed for lead ${enrichedLead.id}: ${error}`);
+    }
+
+    return projection;
+  }
+
+  /**
+   * Project portfolio revenue across multiple leads
+   */
+  projectPortfolio(
+    enrichedLeads: EnrichedLead[],
+    acv?: number,
+    conversionRate?: number
+  ): PortfolioForecast {
+    if (enrichedLeads.length === 0) {
+      return this.emptyForecast();
+    }
+
+    const projections = enrichedLeads.map((lead) =>
+      this.projectLead(lead, acv, conversionRate)
+    );
+
+    // Aggregate by threat level
+    const byThreatLevel: Record<string, { count: number; projectedRevenue: number; confidences: number[] }> = {};
+    enrichedLeads.forEach((lead, idx) => {
+      const threatLevel = lead.threatLevel;
+      if (!byThreatLevel[threatLevel]) {
+        byThreatLevel[threatLevel] = { count: 0, projectedRevenue: 0, confidences: [] };
+      }
+      byThreatLevel[threatLevel].count += 1;
+      byThreatLevel[threatLevel].projectedRevenue += projections[idx].projectedRevenue;
+      byThreatLevel[threatLevel].confidences.push(projections[idx].confidence);
+    });
+
+    // Aggregate by source
+    const bySource: Record<string, { count: number; projectedRevenue: number; confidences: number[] }> = {};
+    enrichedLeads.forEach((lead, idx) => {
+      const source = lead.source;
+      if (!bySource[source]) {
+        bySource[source] = { count: 0, projectedRevenue: 0, confidences: [] };
+      }
+      bySource[source].count += 1;
+      bySource[source].projectedRevenue += projections[idx].projectedRevenue;
+      bySource[source].confidences.push(projections[idx].confidence);
+    });
+
+    // Find top leads
+    const topLeads = projections
+      .map((proj, idx) => ({
+        ...proj,
+        name: enrichedLeads[idx].name,
+        company: enrichedLeads[idx].company || 'Unknown',
+      }))
+      .sort((a, b) => b.projectedRevenue - a.projectedRevenue)
+      .slice(0, 10)
+      .map((p) => ({
+        leadId: p.leadId,
+        name: p.name,
+        company: p.company,
+        projectedRevenue: p.projectedRevenue,
+      }));
+
+    // Calculate aggregates
+    const totalProjectedRevenue = projections.reduce((sum, p) => sum + p.projectedRevenue, 0);
+    const avgRevenuePerLead = totalProjectedRevenue / enrichedLeads.length;
+    const avgConfidence =
+      projections.reduce((sum, p) => sum + p.confidence, 0) / projections.length;
+
+    // Format by threat and source
+    const formattedByThreatLevel: Record<string, { count: number; projectedRevenue: number; avgConfidence: number }> =
+      {};
+    Object.entries(byThreatLevel).forEach(([level, data]) => {
+      formattedByThreatLevel[level] = {
+        count: data.count,
+        projectedRevenue: data.projectedRevenue,
+        avgConfidence: data.confidences.reduce((a, b) => a + b, 0) / data.confidences.length,
+      };
+    });
+
+    const formattedBySource: Record<string, { count: number; projectedRevenue: number; avgConfidence: number }> = {};
+    Object.entries(bySource).forEach(([src, data]) => {
+      formattedBySource[src] = {
+        count: data.count,
+        projectedRevenue: data.projectedRevenue,
+        avgConfidence: data.confidences.reduce((a, b) => a + b, 0) / data.confidences.length,
+      };
+    });
+
+    const forecast: PortfolioForecast = {
+      totalProjectedRevenue,
+      leadCount: enrichedLeads.length,
+      avgRevenuePerLead,
+      confidenceLevel: avgConfidence,
+      byThreatLevel: formattedByThreatLevel,
+      bySource: formattedBySource,
+      topLeads,
+      generatedAt: new Date().toISOString(),
+    };
+
+    // Validate output
+    try {
+      PortfolioForecastSchema.parse(forecast);
+    } catch (error) {
+      throw new Error(`Portfolio forecast validation failed: ${error}`);
+    }
+
+    return forecast;
+  }
+
+  /**
+   * Calculate confidence score based on enrichment quality
+   */
+  private calculateConfidence(
+    enrichedLead: EnrichedLead,
+    threatMultiplier: number,
+    signalBoost: number
+  ): number {
+    let confidence = 50; // Base confidence
+
+    // More signals increase confidence
+    confidence += enrichedLead.signalCount * 5;
+
+    // High lead score increases confidence
+    confidence += Math.min(enrichedLead.score, 50);
+
+    // Threat context increases confidence (more info = more confidence)
+    if (enrichedLead.competitorThreat) {
+      confidence += 10;
+    }
+
+    // Cap at 100
+    return Math.min(confidence, 100);
+  }
+
+  /**
+   * Empty forecast for edge case
+   */
+  private emptyForecast(): PortfolioForecast {
+    return {
+      totalProjectedRevenue: 0,
+      leadCount: 0,
+      avgRevenuePerLead: 0,
+      confidenceLevel: 0,
+      byThreatLevel: {},
+      bySource: {},
+      topLeads: [],
+      generatedAt: new Date().toISOString(),
+    };
+  }
+}
+
+/**
+ * Factory function for creating projector instances
+ */
+export function createRevenueProjector(
+  config?: ProjectionConfig
+): RevenueProjector {
+  return new RevenueProjector(config);
+}
+
+/**
+ * Convenience function for single lead projection
+ */
+export function projectLeadRevenue(
+  enrichedLead: EnrichedLead,
+  acv?: number,
+  conversionRate?: number
+): RevenueProjection {
+  const projector = new RevenueProjector();
+  return projector.projectLead(enrichedLead, acv, conversionRate);
+}
+
+/**
+ * Convenience function for portfolio projection
+ */
+export function projectPortfolioRevenue(
+  enrichedLeads: EnrichedLead[],
+  acv?: number,
+  conversionRate?: number
+): PortfolioForecast {
+  const projector = new RevenueProjector();
+  return projector.projectPortfolio(enrichedLeads, acv, conversionRate);
+}
+
+export {
+  RevenueProjection,
+  ProjectionFactors,
+  PortfolioForecast,
+  ProjectionConfig,
+};

package/src/metrics/revenueTypes.ts

@@ -0,0 +1,67 @@
+/**
+ * Revenue Projection Type Definitions
+ * Structures for revenue forecasting and portfolio analytics
+ * Phase 8A Task 2
+ */
+
+import { EnrichedLead } from '../intelligence/leadEnrichmentTypes.js';
+
+/**
+ * Individual factors affecting revenue projection
+ */
+export interface ProjectionFactors {
+  baseValue: number; // Lead quality × Conversion rate × ACV
+  threatMultiplier: number; // 1 - (competitorThreat / 100 × 0.3)
+  signalBoost: number; // 1 + (signalCount / 10 × 0.2)
+  confidenceScore: number; // 0-100
+}
+
+/**
+ * Revenue projection for individual lead
+ */
+export interface RevenueProjection {
+  leadId: string;
+  projectedRevenue: number; // In dollars
+  confidence: number; // 0-100
+  factors: ProjectionFactors;
+  acv: number; // Average Contract Value
+  conversionRate: number; // 0-1
+  calculatedAt: string;
+}
+
+/**
+ * Portfolio-level revenue forecast
+ */
+export interface PortfolioForecast {
+  totalProjectedRevenue: number;
+  leadCount: number;
+  avgRevenuePerLead: number;
+  confidenceLevel: number; // Average confidence
+  byThreatLevel: Record<string, {
+    count: number;
+    projectedRevenue: number;
+    avgConfidence: number;
+  }>;
+  bySource: Record<string, {
+    count: number;
+    projectedRevenue: number;
+    avgConfidence: number;
+  }>;
+  topLeads: Array<{
+    leadId: string;
+    name: string;
+    company: string;
+    projectedRevenue: number;
+  }>;
+  generatedAt: string;
+}
+
+/**
+ * Revenue projection configuration
+ */
+export interface ProjectionConfig {
+  defaultACV?: number; // Default: $50,000
+  defaultConversionRate?: number; // Default: 0.15 (15%)
+  threatReductionFactor?: number; // Default: 0.3 (30% max reduction)
+  signalBoostFactor?: number; // Default: 0.2 (20% max boost)
+}

package/src/metrics/roiCalculator.ts

@@ -0,0 +1,199 @@
+/**
+ * ROI & Financial Model Calculator
+ * Estimates revenue potential and return on investment
+ */
+
+export interface ROIInput {
+  leadsIdentified: number;
+  conversionRate?: number; // 0-1, default 0.02 (2%)
+  avgDealSize?: number; // in dollars, default 50000
+  salesCycleDays?: number; // default 90
+  developmentCostUSD?: number; // total dev cost, default 0
+  licensingCostMonthly?: number; // monthly licensing, default 0
+}
+
+export interface ROIOutput {
+  // Revenue projection
+  revenuePotential: number;
+  revenueConservative: number; // 0.5x multiplier for risk
+  revenueOptimistic: number; // 1.5x multiplier
+
+  // Costs
+  totalCosts: number;
+  costBreakdown: {
+    development: number;
+    licensing: number; // annual
+  };
+
+  // ROI metrics
+  roiPercentage: number;
+  paybackPeriodDays: number;
+  paybackPeriodWeeks: string;
+  profitMargin: number;
+
+  // Additional metrics
+  revenuePerLead: number;
+  costPerLead: number;
+  breakEvenLeads: number;
+
+  // Assumptions used
+  assumptions: {
+    conversionRate: number;
+    avgDealSize: number;
+    salesCycleDays: number;
+  };
+}
+
+export function calculateROI(input: ROIInput): ROIOutput {
+  const {
+    leadsIdentified,
+    conversionRate = 0.02,
+    avgDealSize = 50000,
+    salesCycleDays = 90,
+    developmentCostUSD = 0,
+    licensingCostMonthly = 0,
+  } = input;
+
+  // Revenue calculations
+  const convertedLeads = leadsIdentified * conversionRate;
+  const revenuePotential = convertedLeads * avgDealSize;
+  const revenueConservative = revenuePotential * 0.5;
+  const revenueOptimistic = revenuePotential * 1.5;
+
+  // Cost calculations (annualized)
+  const annualLicensingCost = licensingCostMonthly * 12;
+  const totalCosts = developmentCostUSD + annualLicensingCost;
+
+  // ROI metrics
+  const roiPercentage = totalCosts > 0 ? ((revenuePotential - totalCosts) / totalCosts) * 100 : 100;
+  const profitMargin = revenuePotential > 0 ? ((revenuePotential - totalCosts) / revenuePotential) * 100 : 0;
+
+  // Payback period
+  const monthlyRevenue = revenuePotential / 12;
+  const monthlyLicensingCost = licensingCostMonthly;
+  const monthlyProfit = monthlyRevenue - monthlyLicensingCost;
+  const paybackPeriodMonths = monthlyProfit > 0 ? developmentCostUSD / monthlyProfit : 999;
+  const paybackPeriodDays = Math.ceil(paybackPeriodMonths * 30);
+  const paybackPeriodWeeks = paybackPeriodMonths > 0 ? `${Math.round(paybackPeriodMonths * 4.33)} weeks` : 'N/A';
+
+  // Per-lead metrics
+  const revenuePerLead = leadsIdentified > 0 ? revenuePotential / leadsIdentified : 0;
+  const costPerLead = leadsIdentified > 0 ? totalCosts / leadsIdentified : 0;
+  const breakEvenLeads = avgDealSize > 0 ? Math.ceil(totalCosts / (avgDealSize * conversionRate)) : 0;
+
+  return {
+    revenuePotential: Math.round(revenuePotential),
+    revenueConservative: Math.round(revenueConservative),
+    revenueOptimistic: Math.round(revenueOptimistic),
+
+    totalCosts,
+    costBreakdown: {
+      development: developmentCostUSD,
+      licensing: annualLicensingCost,
+    },
+
+    roiPercentage: Math.round(roiPercentage * 100) / 100,
+    paybackPeriodDays,
+    paybackPeriodWeeks,
+    profitMargin: Math.round(profitMargin * 100) / 100,
+
+    revenuePerLead: Math.round(revenuePerLead),
+    costPerLead: Math.round(costPerLead),
+    breakEvenLeads,
+
+    assumptions: {
+      conversionRate,
+      avgDealSize,
+      salesCycleDays,
+    },
+  };
+}
+
+export function formatROI(roi: ROIOutput): string {
+  const lines = [
+    '=== ROI Analysis ===',
+    '',
+    'Revenue Projections:',
+    `  Potential:    $${roi.revenuePotential.toLocaleString()}`,
+    `  Conservative: $${roi.revenueConservative.toLocaleString()} (50% scenario)`,
+    `  Optimistic:   $${roi.revenueOptimistic.toLocaleString()} (150% scenario)`,
+    '',
+    'Costs:',
+    `  Development: $${roi.costBreakdown.development.toLocaleString()}`,
+    `  Licensing:   $${roi.costBreakdown.licensing.toLocaleString()} (annual)`,
+    `  Total:       $${roi.totalCosts.toLocaleString()}`,
+    '',
+    'Key Metrics:',
+    `  ROI:              ${roi.roiPercentage}%`,
+    `  Payback Period:   ${roi.paybackPeriodWeeks}`,
+    `  Profit Margin:    ${roi.profitMargin}%`,
+    `  Revenue/Lead:     $${roi.revenuePerLead.toLocaleString()}`,
+    `  Cost/Lead:        $${roi.costPerLead.toLocaleString()}`,
+    `  Break-Even Leads: ${roi.breakEvenLeads}`,
+    '',
+    'Assumptions:',
+    `  Conversion Rate: ${(roi.assumptions.conversionRate * 100).toFixed(2)}%`,
+    `  Avg Deal Size:   $${roi.assumptions.avgDealSize.toLocaleString()}`,
+    `  Sales Cycle:     ${roi.assumptions.salesCycleDays} days`,
+  ];
+
+  return lines.join('\n');
+}
+
+export function compareScenarios(baseCase: ROIOutput, scenarios: Record<string, ROIOutput>): string {
+  const lines = [
+    '=== ROI Scenario Comparison ===',
+    '',
+    'Base Case:',
+    `  Revenue: $${baseCase.revenuePotential.toLocaleString()}`,
+    `  ROI: ${baseCase.roiPercentage}%`,
+    `  Payback: ${baseCase.paybackPeriodWeeks}`,
+    '',
+  ];
+
+  Object.entries(scenarios).forEach(([name, scenario]) => {
+    const roiDiff = scenario.roiPercentage - baseCase.roiPercentage;
+    const revenueDiff = scenario.revenuePotential - baseCase.revenuePotential;
+    lines.push(`${name}:`);
+    lines.push(`  Revenue: $${scenario.revenuePotential.toLocaleString()} (${revenueDiff > 0 ? '+' : ''}$${revenueDiff.toLocaleString()})`);
+    lines.push(`  ROI: ${scenario.roiPercentage}% (${roiDiff > 0 ? '+' : ''}${roiDiff}%)`);
+    lines.push(`  Payback: ${scenario.paybackPeriodWeeks}`);
+    lines.push('');
+  });
+
+  return lines.join('\n');
+}
+
+export function sensitivity(
+  baselineROI: ROIOutput,
+  baselineInput: ROIInput
+): Record<string, Record<string, number>> {
+  const sensitivities: Record<string, Record<string, number>> = {
+    conversionRate: {},
+    avgDealSize: {},
+    leadsIdentified: {},
+  };
+
+  // Conversion rate sensitivity (-50% to +50%)
+  [-50, -25, 0, 25, 50].forEach(change => {
+    const newRate = baselineInput.conversionRate! * (1 + change / 100);
+    const result = calculateROI({ ...baselineInput, conversionRate: newRate });
+    sensitivities.conversionRate[`${change > 0 ? '+' : ''}${change}%`] = result.roiPercentage;
+  });
+
+  // Deal size sensitivity
+  [-50, -25, 0, 25, 50].forEach(change => {
+    const newSize = baselineInput.avgDealSize! * (1 + change / 100);
+    const result = calculateROI({ ...baselineInput, avgDealSize: newSize });
+    sensitivities.avgDealSize[`${change > 0 ? '+' : ''}${change}%`] = result.roiPercentage;
+  });
+
+  // Leads identified sensitivity
+  [-50, -25, 0, 25, 50].forEach(change => {
+    const newLeads = Math.ceil(baselineInput.leadsIdentified * (1 + change / 100));
+    const result = calculateROI({ ...baselineInput, leadsIdentified: newLeads });
+    sensitivities.leadsIdentified[`${change > 0 ? '+' : ''}${change}%`] = result.roiPercentage;
+  });
+
+  return sensitivities;
+}