lean-claudient-core 0.1.0

package/src/intelligence/leadEnrichment.ts

@@ -0,0 +1,275 @@
+/**
+ * Lead Enrichment Pipeline
+ * Synthesizes market signals and competitor threats into enriched lead objects
+ * Phase 8A Task 1
+ */
+
+import { z } from 'zod';
+import { Lead, Signal, SIGNAL_TYPES } from '../database/leadsSchema.js';
+import { TrendResult, ScanResult } from './marketScanner.js';
+import { CompetitorIntelligence, CompetitorThreat } from './competitorTypes.js';
+import {
+  EnrichedLead,
+  LeadSignal,
+  ThreatContext,
+  EnrichmentConfig,
+} from './leadEnrichmentTypes.js';
+
+const ENRICHMENT_VERSION = '1.0.0';
+
+/**
+ * Validation schemas
+ */
+const LeadSignalSchema = z.object({
+  signalId: z.string().min(1),
+  trend: z.string().min(1),
+  relevanceScore: z.number().min(0).max(100),
+  source: z.enum(['reddit', 'hackernews', 'twitter', 'polymarket']),
+  strength: z.number().min(0).max(1),
+  tags: z.array(z.string()),
+  matchedAt: z.string().datetime(),
+});
+
+const ThreatContextSchema = z.object({
+  competitorId: z.string().min(1),
+  competitorName: z.string().min(1),
+  threatScore: z.number().min(0).max(100),
+  threatLevel: z.enum(['CRITICAL', 'HIGH', 'MEDIUM', 'LOW']),
+  keyStrengths: z.array(z.string()),
+  keyWeaknesses: z.array(z.string()),
+});
+
+const EnrichedLeadSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  company: z.string().optional(),
+  industry: z.string().optional(),
+  pain_point: z.string().optional(),
+  source: z.string(),
+  score: z.number(),
+  status: z.enum(['new', 'contacted', 'qualified', 'converted', 'rejected']),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+  marketSignals: z.array(LeadSignalSchema),
+  competitorThreat: ThreatContextSchema.optional(),
+  signalCount: z.number().min(0).max(10),
+  threatLevel: z.enum(['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'NONE']),
+  enrichedAt: z.string().datetime(),
+  enrichmentVersion: z.string(),
+});
+
+/**
+ * Lead Enricher class
+ */
+export class LeadEnricher {
+  private config: EnrichmentConfig;
+  private competitorMap: Map<string, CompetitorThreat> = new Map();
+
+  constructor(config: EnrichmentConfig = {}) {
+    this.config = {
+      minRelevanceScore: config.minRelevanceScore ?? 60,
+      maxSignalsPerLead: config.maxSignalsPerLead ?? 10,
+      includeThreatContext: config.includeThreatContext ?? true,
+    };
+  }
+
+  /**
+   * Load competitor threat data for lookup
+   */
+  loadCompetitorData(competitorIntelligence: CompetitorIntelligence[]): void {
+    competitorIntelligence.forEach((intel) => {
+      this.competitorMap.set(intel.competitor_id, intel.threat_assessment);
+    });
+  }
+
+  /**
+   * Enrich a single lead with market signals and threat context
+   */
+  enrichLead(
+    lead: Lead,
+    marketSignals: TrendResult[],
+    competitorThreats?: CompetitorThreat[]
+  ): EnrichedLead {
+    const enrichedAt = new Date().toISOString();
+
+    // Match market signals to lead
+    const matchedSignals = this.matchSignalsToLead(lead, marketSignals);
+    const filteredSignals = matchedSignals
+      .filter((s) => s.relevanceScore >= (this.config.minRelevanceScore ?? 60))
+      .slice(0, this.config.maxSignalsPerLead);
+
+    // Find closest competitor threat
+    const threat = this.findClosestThreat(lead, competitorThreats);
+    const threatLevel = this.deriveTheatLevel(threat);
+
+    // Build enriched lead
+    const enrichedLead: EnrichedLead = {
+      ...lead,
+      marketSignals: filteredSignals,
+      competitorThreat: threat,
+      signalCount: filteredSignals.length,
+      threatLevel,
+      enrichedAt,
+      enrichmentVersion: ENRICHMENT_VERSION,
+    };
+
+    // Validate output
+    try {
+      EnrichedLeadSchema.parse(enrichedLead);
+    } catch (error) {
+      throw new Error(`Enrichment validation failed for lead ${lead.id}: ${error}`);
+    }
+
+    return enrichedLead;
+  }
+
+  /**
+   * Enrich multiple leads in batch
+   */
+  enrichLeads(
+    leads: Lead[],
+    marketSignals: TrendResult[],
+    competitorThreats?: CompetitorThreat[]
+  ): EnrichedLead[] {
+    return leads.map((lead) =>
+      this.enrichLead(lead, marketSignals, competitorThreats)
+    );
+  }
+
+  /**
+   * Match market signals to lead based on company, industry, pain point
+   */
+  private matchSignalsToLead(lead: Lead, signals: TrendResult[]): LeadSignal[] {
+    const matched: LeadSignal[] = [];
+    const now = new Date().toISOString();
+
+    for (const signal of signals) {
+      // Check if signal is relevant to lead
+      const relevanceScore = this.calculateSignalRelevance(lead, signal);
+
+      if (relevanceScore > 0) {
+        const leadSignal: LeadSignal = {
+          signalId: `${lead.id}-${signal.trend.replace(/\s+/g, '-')}`,
+          trend: signal.trend,
+          relevanceScore,
+          source: this.inferSource(signal),
+          strength: signal.strength,
+          tags: signal.relatedKeywords || [],
+          matchedAt: now,
+        };
+
+        try {
+          LeadSignalSchema.parse(leadSignal);
+          matched.push(leadSignal);
+        } catch {
+          // Skip invalid signal
+        }
+      }
+    }
+
+    return matched;
+  }
+
+  /**
+   * Calculate relevance score between signal and lead (0-100)
+   */
+  private calculateSignalRelevance(lead: Lead, signal: TrendResult): number {
+    let score = 0;
+
+    // Always add base relevance from signal strength
+    score += Math.round(signal.strength * 40);
+
+    // Industry match (increase scoring)
+    if (lead.industry && signal.relatedKeywords) {
+      const industryMatch = signal.relatedKeywords.some((k) =>
+        k.toLowerCase().includes(lead.industry!.toLowerCase())
+      );
+      if (industryMatch) score += 35;
+    }
+
+    // Pain point alignment
+    if (lead.pain_point && signal.opportunities) {
+      const painMatch = signal.opportunities.some((o) =>
+        o.toLowerCase().includes(lead.pain_point!.toLowerCase())
+      );
+      if (painMatch) score += 25;
+    }
+
+    // Cap at 100
+    return Math.min(score, 100);
+  }
+
+  /**
+   * Infer signal source from trend analysis
+   */
+  private inferSource(
+    signal: TrendResult
+  ): 'reddit' | 'hackernews' | 'twitter' | 'polymarket' {
+    // In production, inspect signal.metadata or keywords for source hints
+    const sources = ['reddit', 'hackernews', 'twitter', 'polymarket'] as const;
+    return sources[Math.floor(Math.random() * sources.length)];
+  }
+
+  /**
+   * Find closest competitor threat to lead
+   */
+  private findClosestThreat(
+    lead: Lead,
+    competitorThreats?: CompetitorThreat[]
+  ): ThreatContext | undefined {
+    if (!competitorThreats || competitorThreats.length === 0) {
+      return undefined;
+    }
+
+    // Find competitor with highest threat score in lead's industry
+    const relevant = competitorThreats
+      .filter((t) => t.threat_level !== 'low')
+      .sort((a, b) => b.threat_score - a.threat_score);
+
+    if (relevant.length === 0) return undefined;
+
+    const threat = relevant[0];
+    return {
+      competitorId: threat.competitor_id,
+      competitorName: threat.competitor_name,
+      threatScore: threat.threat_score,
+      threatLevel: threat.threat_level.toUpperCase() as 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW',
+      keyStrengths: threat.strengths || [],
+      keyWeaknesses: threat.weaknesses || [],
+    };
+  }
+
+  /**
+   * Derive threat level from competitor context
+   */
+  private deriveTheatLevel(
+    threat: ThreatContext | undefined
+  ): 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'NONE' {
+    if (!threat) return 'NONE';
+    return threat.threatLevel;
+  }
+
+  /**
+   * Clear competitor cache
+   */
+  clearCache(): void {
+    this.competitorMap.clear();
+  }
+}
+
+/**
+ * Factory function for creating enricher instances
+ */
+export function createLeadEnricher(
+  config?: EnrichmentConfig
+): LeadEnricher {
+  return new LeadEnricher(config);
+}
+
+export {
+  EnrichedLead,
+  LeadSignal,
+  ThreatContext,
+  EnrichmentConfig,
+};

package/src/intelligence/leadEnrichmentTypes.ts

@@ -0,0 +1,54 @@
+/**
+ * Lead Enrichment Type Definitions
+ * Structures for enriched leads with market signals and competitive context
+ * Phase 8A Task 1
+ */
+
+import { Lead, Signal } from '../database/leadsSchema.js';
+
+/**
+ * Market signal matched to a lead
+ */
+export interface LeadSignal {
+  signalId: string;
+  trend: string;
+  relevanceScore: number; // 0-100
+  source: 'reddit' | 'hackernews' | 'twitter' | 'polymarket';
+  strength: number; // 0-1
+  tags: string[];
+  matchedAt: string;
+}
+
+/**
+ * Competitive threat context
+ */
+export interface ThreatContext {
+  competitorId: string;
+  competitorName: string;
+  threatScore: number; // 0-100
+  threatLevel: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
+  keyStrengths: string[];
+  keyWeaknesses: string[];
+}
+
+/**
+ * Enriched lead with market and competitive context
+ */
+export interface EnrichedLead extends Lead {
+  // Enrichment metadata
+  marketSignals: LeadSignal[];
+  competitorThreat?: ThreatContext;
+  signalCount: number;
+  threatLevel: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'NONE';
+  enrichedAt: string;
+  enrichmentVersion: string;
+}
+
+/**
+ * Lead enrichment configuration
+ */
+export interface EnrichmentConfig {
+  minRelevanceScore?: number; // Default: 60
+  maxSignalsPerLead?: number; // Default: 10
+  includeThreatContext?: boolean; // Default: true
+}

package/src/intelligence/marketScanner.ts

@@ -0,0 +1,285 @@
+import { v4 as uuidv4 } from 'uuid';
+import { scanReddit } from './redditScanner.js';
+import { scanHackerNews } from './hackerNewsScanner.js';
+import { scanTwitter } from './twitterScanner.js';
+import { scanPolymarket } from './polymarketScanner.js';
+import { analyzeTrends } from './trendAnalysis.js';
+import { aggregateSignals } from './signalAggregator.js';
+import {
+  Finding,
+  FindingSchema,
+  MarketScanResult,
+  MarketScanResultSchema,
+  ScanOptions,
+  ScannerConfig,
+  RedditPost,
+  HNStory,
+  TwitterTweet,
+  PolymarketMarket,
+} from './types.js';
+
+export class MarketScanner {
+  private config: ScannerConfig;
+
+  constructor(config?: Partial<ScannerConfig>) {
+    this.config = {
+      redditSubreddits: ['devops', 'programming', 'OpenAI', 'ClaudeAI'],
+      redditMinUpvotes: 10,
+      redditMinComments: 5,
+      hnMinPoints: 20,
+      twitterMinLikes: 100,
+      twitterVerifiedOnly: false,
+      polymarketMinVolume: 10000,
+      defaultDays: 30,
+      defaultTopN: 20,
+      defaultMinScore: 0.5,
+      ...config,
+    };
+  }
+
+  async scan(options: ScanOptions): Promise<MarketScanResult> {
+    const startTime = Date.now();
+    const days = options.days || this.config.defaultDays;
+    const topN = options.topN || this.config.defaultTopN;
+    const minScore = options.minScore || this.config.defaultMinScore;
+
+    const allFindings: Finding[] = [];
+
+    // Parallel scanning across platforms
+    const scanPromises = [];
+
+    if (options.platforms.includes('reddit')) {
+      scanPromises.push(
+        this.scanRedditPlatform(options.keywords, days)
+          .then((posts) => {
+            allFindings.push(...posts);
+          })
+          .catch((error) => console.warn('Reddit scan failed:', error))
+      );
+    }
+
+    if (options.platforms.includes('hackernews')) {
+      scanPromises.push(
+        this.scanHackerNewsPlatform(options.keywords, days)
+          .then((stories) => {
+            allFindings.push(...stories);
+          })
+          .catch((error) => console.warn('HackerNews scan failed:', error))
+      );
+    }
+
+    if (options.platforms.includes('twitter')) {
+      scanPromises.push(
+        this.scanTwitterPlatform(options.keywords, days)
+          .then((tweets) => {
+            allFindings.push(...tweets);
+          })
+          .catch((error) => console.warn('Twitter scan failed:', error))
+      );
+    }
+
+    if (options.platforms.includes('polymarket')) {
+      scanPromises.push(
+        this.scanPolymarketPlatform(options.keywords, days)
+          .then((markets) => {
+            allFindings.push(...markets);
+          })
+          .catch((error) => console.warn('Polymarket scan failed:', error))
+      );
+    }
+
+    await Promise.all(scanPromises);
+
+    // Filter by minimum score
+    const filteredFindings = allFindings.filter((f) => f.metrics.score >= minScore);
+
+    // Analyze trends
+    const trends = await analyzeTrends(filteredFindings);
+
+    // Aggregate top signals
+    const topSignals = await aggregateSignals(filteredFindings, topN);
+
+    const duration = Date.now() - startTime;
+
+    const result: MarketScanResult = {
+      timestamp: new Date(),
+      platforms: options.platforms,
+      keywords: options.keywords,
+      total_findings: filteredFindings.length,
+      top_signals: topSignals.slice(0, 10).map((f) => ({
+        trend: f.title,
+        strength: f.metrics.score,
+        category: this.categorizeSignal(f),
+        signal_count: 1,
+      })),
+      findings: topSignals,
+      trends: trends.sort((a, b) => b.strength - a.strength).slice(0, 10),
+      scan_duration_ms: duration,
+    };
+
+    return MarketScanResultSchema.parse(result);
+  }
+
+  private async scanRedditPlatform(keywords: string[], days: number): Promise<Finding[]> {
+    const posts = await scanReddit(keywords, {
+      subreddits: this.config.redditSubreddits,
+      minUpvotes: this.config.redditMinUpvotes,
+      minComments: this.config.redditMinComments,
+      days,
+    });
+
+    return posts.map((post) => this.redditPostToFinding(post));
+  }
+
+  private async scanHackerNewsPlatform(keywords: string[], days: number): Promise<Finding[]> {
+    const stories = await scanHackerNews(keywords, {
+      minPoints: this.config.hnMinPoints,
+      days,
+    });
+
+    return stories.map((story) => this.hnStoryToFinding(story));
+  }
+
+  private async scanTwitterPlatform(keywords: string[], days: number): Promise<Finding[]> {
+    const tweets = await scanTwitter(keywords, {
+      minLikes: this.config.twitterMinLikes,
+      verifiedOnly: this.config.twitterVerifiedOnly,
+      days,
+    });
+
+    return tweets.map((tweet) => this.tweetToFinding(tweet));
+  }
+
+  private async scanPolymarketPlatform(keywords: string[], days: number): Promise<Finding[]> {
+    const markets = await scanPolymarket(keywords, {
+      minVolume: this.config.polymarketMinVolume,
+      days,
+    });
+
+    return markets.map((market) => this.polymarketToFinding(market));
+  }
+
+  private redditPostToFinding(post: RedditPost): Finding {
+    const engagement = post.upvotes + post.comments * 2;
+    const score = Math.min(
+      (post.upvotes / 100 + post.comments / 50) / 2,
+      1.0
+    );
+
+    const finding: Finding = {
+      id: uuidv4(),
+      title: post.title,
+      url: post.url,
+      platform: 'reddit',
+      content: post.title,
+      metrics: {
+        engagement,
+        score,
+      },
+      keywords: this.extractKeywords(post.title),
+      timestamp: post.timestamp,
+      source: post.subreddit,
+      author: post.author,
+    };
+
+    return FindingSchema.parse(finding);
+  }
+
+  private hnStoryToFinding(story: HNStory): Finding {
+    const engagement = story.points + story.comments * 2;
+    const score = Math.min((story.points / 100 + story.comments / 50) / 2, 1.0);
+
+    const finding: Finding = {
+      id: uuidv4(),
+      title: story.title,
+      url: story.url,
+      platform: 'hackernews',
+      content: story.title,
+      metrics: {
+        engagement,
+        score,
+      },
+      keywords: this.extractKeywords(story.title),
+      timestamp: story.timestamp,
+      source: 'hackernews',
+      author: story.author,
+    };
+
+    return FindingSchema.parse(finding);
+  }
+
+  private tweetToFinding(tweet: TwitterTweet): Finding {
+    const engagement = tweet.likes + tweet.retweets * 2;
+    const score = Math.min((tweet.likes / 500 + tweet.retweets / 250) / 2, 1.0);
+
+    const finding: Finding = {
+      id: uuidv4(),
+      title: tweet.text.substring(0, 100),
+      url: tweet.url,
+      platform: 'twitter',
+      content: tweet.text,
+      metrics: {
+        engagement,
+        score,
+      },
+      keywords: [...tweet.hashtags, ...this.extractKeywords(tweet.text)],
+      timestamp: tweet.timestamp,
+      source: 'twitter',
+      author: tweet.author,
+    };
+
+    return FindingSchema.parse(finding);
+  }
+
+  private polymarketToFinding(market: PolymarketMarket): Finding {
+    // Higher volume and more extreme odds = stronger signal
+    const volumeScore = Math.min(market.volume / 100000, 1.0);
+    const oddScore = Math.abs(market.odds - 0.5) * 2; // 0-1, peaks at 0 or 1
+    const score = (volumeScore + oddScore) / 2;
+
+    const finding: Finding = {
+      id: uuidv4(),
+      title: market.title,
+      url: market.url,
+      platform: 'polymarket',
+      content: market.description || market.title,
+      metrics: {
+        engagement: market.volume,
+        score: Math.min(Math.max(score, 0), 1.0),
+      },
+      keywords: this.extractKeywords(market.title),
+      timestamp: market.timestamp,
+      source: 'polymarket',
+    };
+
+    return FindingSchema.parse(finding);
+  }
+
+  private extractKeywords(text: string): string[] {
+    // Simple keyword extraction: words > 3 chars, exclude common words
+    const stopWords = new Set([
+      'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for', 'of',
+      'with', 'by', 'from', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    ]);
+
+    return text
+      .toLowerCase()
+      .split(/\W+/)
+      .filter((word) => word.length > 3 && !stopWords.has(word))
+      .slice(0, 10);
+  }
+
+  private categorizeSignal(finding: Finding): string {
+    const content = `${finding.title} ${finding.content}`.toLowerCase();
+
+    if (/issue|bug|problem|break/i.test(content)) return 'pain_point';
+    if (/need|want|request|feature/i.test(content)) return 'feature_request';
+    if (/competitor|threat|better/i.test(content)) return 'competitive_threat';
+    return 'opportunity';
+  }
+}
+
+export async function scanMarkets(options: ScanOptions): Promise<MarketScanResult> {
+  const scanner = new MarketScanner();
+  return scanner.scan(options);
+}