lean-claudient-core 0.1.0

package/src/automation/jobQueue.ts

@@ -0,0 +1,278 @@
+/**
+ * Job Queue for Background Tasks
+ * In-memory queue for pending jobs with execution logging
+ * Phase 8C Task 7
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import { AuditLogger } from '../core/auditLogger.js';
+
+/**
+ * Queued job
+ */
+export interface QueuedJob {
+  id: string;
+  name: string;
+  priority: 'high' | 'normal' | 'low';
+  payload?: Record<string, any>;
+  fn: () => Promise<void> | void;
+  createdAt: number;
+  executedAt?: number;
+  status: 'pending' | 'executing' | 'completed' | 'failed';
+  error?: string;
+  retryCount: number;
+  maxRetries: number;
+}
+
+/**
+ * Job queue statistics
+ */
+export interface QueueStats {
+  total: number;
+  pending: number;
+  executing: number;
+  completed: number;
+  failed: number;
+  avgExecutionTime: number;
+}
+
+/**
+ * Job Queue: Manages pending job execution
+ */
+export class JobQueue {
+  private queue: Map<string, QueuedJob> = new Map();
+  private executingJobs: Set<string> = new Set();
+  private completedJobs: Map<string, QueuedJob> = new Map();
+  private failedJobs: Map<string, QueuedJob> = new Map();
+  private auditLogger: AuditLogger;
+  private executionTimes: number[] = [];
+
+  constructor() {
+    this.auditLogger = new AuditLogger();
+  }
+
+  /**
+   * Enqueue a new job
+   */
+  enqueue(
+    name: string,
+    fn: () => Promise<void> | void,
+    options?: {
+      priority?: 'high' | 'normal' | 'low';
+      payload?: Record<string, any>;
+      maxRetries?: number;
+    }
+  ): string {
+    const jobId = uuidv4();
+    const job: QueuedJob = {
+      id: jobId,
+      name,
+      priority: options?.priority || 'normal',
+      payload: options?.payload,
+      fn,
+      createdAt: Date.now(),
+      status: 'pending',
+      retryCount: 0,
+      maxRetries: options?.maxRetries || 3,
+    };
+
+    this.queue.set(jobId, job);
+
+    this.auditLogger.log({
+      event: 'job:enqueued',
+      jobId,
+      name,
+      priority: job.priority,
+    });
+
+    return jobId;
+  }
+
+  /**
+   * Dequeue and execute the next job
+   */
+  async dequeue(): Promise<string | null> {
+    // Find next job by priority
+    let nextJobId: string | null = null;
+    let nextPriority: 'high' | 'normal' | 'low' | null = null;
+
+    for (const [id, job] of this.queue) {
+      if (job.status !== 'pending') continue;
+
+      const priority = job.priority;
+      if (!nextPriority || priority === 'high' || (priority === 'normal' && nextPriority === 'low')) {
+        nextJobId = id;
+        nextPriority = priority;
+      }
+    }
+
+    if (!nextJobId) return null;
+
+    const job = this.queue.get(nextJobId)!;
+    job.status = 'executing';
+    this.executingJobs.add(nextJobId);
+
+    const startTime = Date.now();
+
+    try {
+      this.auditLogger.log({
+        event: 'job:executing',
+        jobId: nextJobId,
+        name: job.name,
+      });
+
+      await Promise.resolve(job.fn());
+
+      const executionTime = Date.now() - startTime;
+      this.executionTimes.push(executionTime);
+
+      // Trim execution times to last 100
+      if (this.executionTimes.length > 100) {
+        this.executionTimes.shift();
+      }
+
+      job.status = 'completed';
+      job.executedAt = Date.now();
+      this.executingJobs.delete(nextJobId);
+      this.completedJobs.set(nextJobId, job);
+
+      this.auditLogger.log({
+        event: 'job:completed',
+        jobId: nextJobId,
+        name: job.name,
+        executionTime,
+      });
+
+      // Remove from queue
+      this.queue.delete(nextJobId);
+      return nextJobId;
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      job.retryCount++;
+
+      if (job.retryCount < job.maxRetries) {
+        job.status = 'pending';
+        this.auditLogger.log({
+          event: 'job:retry',
+          jobId: nextJobId,
+          name: job.name,
+          retryCount: job.retryCount,
+          error: errorMsg,
+        });
+      } else {
+        job.status = 'failed';
+        job.error = errorMsg;
+        this.executingJobs.delete(nextJobId);
+        this.failedJobs.set(nextJobId, job);
+        this.queue.delete(nextJobId);
+
+        this.auditLogger.log({
+          event: 'job:failed',
+          jobId: nextJobId,
+          name: job.name,
+          retryCount: job.retryCount,
+          error: errorMsg,
+        });
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Get queue size by status
+   */
+  getQueueSize(): { total: number; pending: number; executing: number } {
+    const pending = Array.from(this.queue.values()).filter((j) => j.status === 'pending').length;
+    const executing = this.executingJobs.size;
+    const total = this.queue.size;
+
+    return { total, pending, executing };
+  }
+
+  /**
+   * Get queue statistics
+   */
+  getStats(): QueueStats {
+    const avgExecutionTime =
+      this.executionTimes.length > 0
+        ? this.executionTimes.reduce((a, b) => a + b, 0) / this.executionTimes.length
+        : 0;
+
+    return {
+      total: this.queue.size + this.completedJobs.size + this.failedJobs.size,
+      pending: Array.from(this.queue.values()).filter((j) => j.status === 'pending').length,
+      executing: this.executingJobs.size,
+      completed: this.completedJobs.size,
+      failed: this.failedJobs.size,
+      avgExecutionTime,
+    };
+  }
+
+  /**
+   * Get job by ID
+   */
+  getJob(jobId: string): QueuedJob | undefined {
+    return this.queue.get(jobId) || this.completedJobs.get(jobId) || this.failedJobs.get(jobId);
+  }
+
+  /**
+   * Clear all completed jobs
+   */
+  clearCompleted(): number {
+    const count = this.completedJobs.size;
+    this.completedJobs.clear();
+    return count;
+  }
+
+  /**
+   * Clear all failed jobs
+   */
+  clearFailed(): number {
+    const count = this.failedJobs.size;
+    this.failedJobs.clear();
+    return count;
+  }
+
+  /**
+   * Cancel a pending job
+   */
+  cancel(jobId: string): boolean {
+    const job = this.queue.get(jobId);
+    if (!job || job.status !== 'pending') {
+      return false;
+    }
+
+    this.queue.delete(jobId);
+    this.auditLogger.log({
+      event: 'job:cancelled',
+      jobId,
+      name: job.name,
+    });
+
+    return true;
+  }
+
+  /**
+   * Is job executing
+   */
+  isExecuting(jobId: string): boolean {
+    return this.executingJobs.has(jobId);
+  }
+
+  /**
+   * Get all completed jobs
+   */
+  getCompleted(): QueuedJob[] {
+    return Array.from(this.completedJobs.values());
+  }
+
+  /**
+   * Get all failed jobs
+   */
+  getFailed(): QueuedJob[] {
+    return Array.from(this.failedJobs.values());
+  }
+}
+
+export default JobQueue;

package/src/automation/leadQualification.ts

@@ -0,0 +1,270 @@
+/**
+ * Lead Qualification Workflow
+ * Automated stage transitions (cold → warm → hot → sales-ready)
+ * Composio integration for CRM export with human approval gate
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import { AuditLogger } from '../core/auditLogger.js';
+import ComposioClient from './composioClient.js';
+import {
+  QualificationStage,
+  EnrichedLead,
+  RevenueProjection,
+  QualificationResult,
+  StageTransition,
+  evaluateStage,
+  calculateConfidence,
+  getNextAction,
+  identifyBlockers,
+  getComposioActionsForTransition,
+  isValidTransition,
+  getTransitionReason,
+  stageDefinitions,
+} from './qualificationRules.js';
+
+/**
+ * Lead Qualifier: Main qualification engine
+ */
+export class LeadQualifier {
+  private auditLogger: AuditLogger;
+  private composioClient?: ComposioClient;
+  private transitions: Map<string, StageTransition> = new Map();
+
+  constructor(composioApiKey?: string) {
+    this.auditLogger = new AuditLogger();
+
+    if (composioApiKey) {
+      this.composioClient = new ComposioClient({
+        apiKey: composioApiKey,
+        baseUrl: 'https://api.composio.dev/api/v1',
+      });
+    }
+  }
+
+  /**
+   * Qualify a single lead
+   */
+  qualifyLead(
+    enrichedLead: EnrichedLead,
+    projection?: RevenueProjection
+  ): QualificationResult {
+    const blockers = identifyBlockers(enrichedLead, projection);
+    const stage = evaluateStage(enrichedLead, projection, blockers);
+    const confidence = calculateConfidence(enrichedLead, stage);
+    const nextAction = getNextAction(stage);
+
+    const result: QualificationResult = {
+      leadId: enrichedLead.id,
+      stage,
+      confidence,
+      nextAction,
+      signals: enrichedLead.signals?.map((s) => s.type) || [],
+      blockers: blockers.length > 0 ? blockers : undefined,
+    };
+
+    // Log qualification
+    this.auditLogger.log({
+      event: 'lead:qualified',
+      leadId: enrichedLead.id,
+      stage,
+      confidence,
+      signalCount: enrichedLead.signalCount,
+      quality: enrichedLead.quality,
+      competitorThreat: enrichedLead.competitorThreat,
+      blockers,
+      nextAction,
+    });
+
+    return result;
+  }
+
+  /**
+   * Batch qualify multiple leads
+   */
+  batchQualify(
+    enrichedLeads: EnrichedLead[],
+    projections?: Map<string, RevenueProjection>
+  ): QualificationResult[] {
+    return enrichedLeads.map((lead) => {
+      const projection = projections?.get(lead.id);
+      return this.qualifyLead(lead, projection);
+    });
+  }
+
+  /**
+   * Transition a lead to a new stage with validation
+   */
+  async transitionLead(
+    leadId: string,
+    fromStage: QualificationStage,
+    toStage: QualificationStage,
+    lead: EnrichedLead,
+    reason?: string
+  ): Promise<{ success: boolean; transition?: StageTransition; error?: string }> {
+    // Validate transition
+    if (!isValidTransition(fromStage, toStage)) {
+      const error = `Invalid transition from ${fromStage} to ${toStage}`;
+      this.auditLogger.log({
+        event: 'lead:transition-failed',
+        leadId,
+        fromStage,
+        toStage,
+        reason: error,
+      });
+      return { success: false, error };
+    }
+
+    // Create transition record
+    const transition: StageTransition = {
+      leadId,
+      fromStage,
+      toStage,
+      timestamp: new Date().toISOString(),
+      reason: reason || getTransitionReason(lead, fromStage, toStage),
+      composioActionsQueued: [],
+    };
+
+    try {
+      // Queue Composio actions if transitioning to hot or sales-ready
+      if (toStage === 'hot' || toStage === 'sales-ready') {
+        const actions = getComposioActionsForTransition(fromStage, toStage, lead);
+        transition.composioActionsQueued = actions;
+
+        if (this.composioClient && toStage === 'sales-ready') {
+          // Queue CRM export (no autonomous execution - human gate)
+          await this.queueComposioActions(leadId, actions, lead);
+        }
+      }
+
+      // Store transition
+      this.transitions.set(leadId, transition);
+
+      // Log transition
+      this.auditLogger.log({
+        event: 'lead:transitioned',
+        leadId,
+        fromStage,
+        toStage,
+        reason: transition.reason,
+        composioActionsQueued: transition.composioActionsQueued,
+        timestamp: transition.timestamp,
+      });
+
+      return { success: true, transition };
+    } catch (error) {
+      const errorMsg = (error as Error).message;
+      this.auditLogger.log({
+        event: 'lead:transition-error',
+        leadId,
+        fromStage,
+        toStage,
+        error: errorMsg,
+      });
+      return { success: false, error: errorMsg };
+    }
+  }
+
+  /**
+   * Queue Composio actions for a lead (no execution, human approval required)
+   */
+  private async queueComposioActions(
+    leadId: string,
+    actions: string[],
+    lead: EnrichedLead
+  ): Promise<void> {
+    if (!this.composioClient) {
+      throw new Error('Composio client not configured');
+    }
+
+    for (const action of actions) {
+      if (action.startsWith('composio:')) {
+        const actionType = action.replace('composio:', '');
+
+        this.auditLogger.log({
+          event: 'composio:action-queued',
+          leadId,
+          actionType,
+          leadName: lead.name,
+          leadEmail: lead.email,
+          status: 'pending-approval',
+          timestamp: new Date().toISOString(),
+        });
+      }
+    }
+  }
+
+  /**
+   * Get transition history for a lead
+   */
+  getTransitionHistory(leadId: string): StageTransition | undefined {
+    return this.transitions.get(leadId);
+  }
+
+  /**
+   * Get all transition records
+   */
+  getAllTransitions(): StageTransition[] {
+    return Array.from(this.transitions.values());
+  }
+
+  /**
+   * Get stage definition metadata
+   */
+  getStageDefinition(stage: QualificationStage): typeof stageDefinitions[QualificationStage] {
+    return stageDefinitions[stage];
+  }
+
+  /**
+   * Get summary of qualification stats
+   */
+  getQualificationStats(results: QualificationResult[]): {
+    total: number;
+    byStageCounts: Record<QualificationStage, number>;
+    averageConfidence: number;
+    withBlockers: number;
+  } {
+    const byStageCounts: Record<QualificationStage, number> = {
+      cold: 0,
+      warm: 0,
+      hot: 0,
+      'sales-ready': 0,
+    };
+
+    let totalConfidence = 0;
+    let withBlockers = 0;
+
+    results.forEach((result) => {
+      byStageCounts[result.stage]++;
+      totalConfidence += result.confidence;
+      if (result.blockers && result.blockers.length > 0) {
+        withBlockers++;
+      }
+    });
+
+    return {
+      total: results.length,
+      byStageCounts,
+      averageConfidence: results.length > 0 ? totalConfidence / results.length : 0,
+      withBlockers,
+    };
+  }
+}
+
+/**
+ * Export singleton instance
+ */
+let qualifierInstance: LeadQualifier | null = null;
+
+export function getLeadQualifier(composioApiKey?: string): LeadQualifier {
+  if (!qualifierInstance) {
+    qualifierInstance = new LeadQualifier(composioApiKey);
+  }
+  return qualifierInstance;
+}
+
+export function resetLeadQualifier(): void {
+  qualifierInstance = null;
+}
+
+export default LeadQualifier;