lean-claudient-core 0.1.0

package/src/automation/competitorResponse.ts

@@ -0,0 +1,511 @@
+/**
+ * Competitor Response Strategy Engine
+ * Auto-generates response actions for competitor threat escalations
+ * Phase 8C Task 11
+ */
+
+import { z } from 'zod';
+import { v4 as uuidv4 } from 'uuid';
+
+/**
+ * Response action types
+ */
+export type ResponseActionType = 'email' | 'jira' | 'log';
+export type ResponseActionStatus =
+  | 'queued'
+  | 'approved'
+  | 'executed'
+  | 'rejected'
+  | 'failed';
+export type ThreatLevel = 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
+
+/**
+ * Response action
+ */
+export interface ResponseAction {
+  id: string;
+  competitorId: string;
+  competitorName: string;
+  threatLevel: ThreatLevel;
+  type: ResponseActionType;
+  target: 'sales' | 'product' | 'marketing' | 'leadership';
+  subject?: string;
+  content: string;
+  affectedLeadIds: string[];
+  affectedLeadCount: number;
+  createdAt: string;
+  approvedAt?: string;
+  executedAt?: string;
+  status: ResponseActionStatus;
+  approvedBy?: string;
+  executionResult?: string;
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Threat escalation event
+ */
+export interface ThreatEscalation {
+  competitorId: string;
+  competitorName: string;
+  oldScore: number;
+  newScore: number;
+  escalationType: 'MEDIUM_TO_HIGH' | 'HIGH_TO_CRITICAL' | 'JUMP';
+  affectedLeadIds: string[];
+  affectedLeadCount: number;
+  escalatedAt: string;
+}
+
+/**
+ * Validation schemas
+ */
+const ResponseActionSchema = z.object({
+  id: z.string().min(1),
+  competitorId: z.string().min(1),
+  competitorName: z.string().min(1),
+  threatLevel: z.enum(['CRITICAL', 'HIGH', 'MEDIUM', 'LOW']),
+  type: z.enum(['email', 'jira', 'log']),
+  target: z.enum(['sales', 'product', 'marketing', 'leadership']),
+  subject: z.string().optional(),
+  content: z.string().min(1),
+  affectedLeadIds: z.array(z.string()),
+  affectedLeadCount: z.number().nonnegative(),
+  createdAt: z.string().datetime(),
+  approvedAt: z.string().datetime().optional(),
+  executedAt: z.string().datetime().optional(),
+  status: z.enum(['queued', 'approved', 'executed', 'rejected', 'failed']),
+  approvedBy: z.string().optional(),
+  executionResult: z.string().optional(),
+  metadata: z.record(z.any()).optional(),
+});
+
+/**
+ * CompetitorResponseEngine class
+ */
+export class CompetitorResponseEngine {
+  private responseHistory: ResponseAction[] = [];
+  private threatThresholds = {
+    MEDIUM: 25,
+    HIGH: 50,
+    CRITICAL: 75,
+  };
+
+  /**
+   * Handle threat escalation and generate response actions
+   */
+  onThreatEscalation(
+    competitorId: string,
+    competitorName: string,
+    oldScore: number,
+    newScore: number,
+    affectedLeadIds: string[]
+  ): ResponseAction[] {
+    const escalationType = this.determineEscalationType(oldScore, newScore);
+    const threatLevel = this.getThreatLevel(newScore);
+    const actions: ResponseAction[] = [];
+
+    // CRITICAL threat (75-100)
+    if (newScore >= this.threatThresholds.CRITICAL) {
+      // Generate email
+      const emailAction = this.generateSalesEmail(
+        competitorId,
+        competitorName,
+        threatLevel,
+        affectedLeadIds
+      );
+      actions.push(emailAction);
+
+      // Generate Jira epic
+      const jiraAction = this.generateJiraEpic(
+        competitorId,
+        competitorName,
+        threatLevel,
+        affectedLeadIds
+      );
+      actions.push(jiraAction);
+    }
+    // HIGH threat (50-74)
+    else if (newScore >= this.threatThresholds.HIGH) {
+      // Generate email
+      const emailAction = this.generateSalesEmail(
+        competitorId,
+        competitorName,
+        threatLevel,
+        affectedLeadIds
+      );
+      actions.push(emailAction);
+
+      // Generate market analysis log
+      const logAction = this.generateMarketAnalysisLog(
+        competitorId,
+        competitorName,
+        threatLevel,
+        affectedLeadIds
+      );
+      actions.push(logAction);
+    }
+    // MEDIUM threat (25-49)
+    else if (newScore >= this.threatThresholds.MEDIUM) {
+      // Log only
+      const logAction = this.generateMarketAnalysisLog(
+        competitorId,
+        competitorName,
+        threatLevel,
+        affectedLeadIds
+      );
+      actions.push(logAction);
+    }
+
+    // Store all actions
+    actions.forEach((action) => {
+      ResponseActionSchema.parse(action);
+      this.responseHistory.push(action);
+    });
+
+    return actions;
+  }
+
+  /**
+   * Generate sales email template
+   */
+  generateSalesEmail(
+    competitorId: string,
+    competitorName: string,
+    threatLevel: ThreatLevel,
+    affectedLeadIds: string[]
+  ): ResponseAction {
+    const subject =
+      threatLevel === 'CRITICAL'
+        ? `URGENT: ${competitorName} Threat Response Required`
+        : `${competitorName} Competitive Intelligence Update`;
+
+    const content = this.formatEmailTemplate(
+      competitorName,
+      threatLevel,
+      affectedLeadIds
+    );
+
+    return {
+      id: uuidv4(),
+      competitorId,
+      competitorName,
+      threatLevel,
+      type: 'email',
+      target: 'sales',
+      subject,
+      content,
+      affectedLeadIds,
+      affectedLeadCount: affectedLeadIds.length,
+      createdAt: new Date().toISOString(),
+      status: 'queued',
+      metadata: {
+        priority:
+          threatLevel === 'CRITICAL'
+            ? 'urgent'
+            : threatLevel === 'HIGH'
+              ? 'high'
+              : 'normal',
+        accountCount: affectedLeadIds.length,
+      },
+    };
+  }
+
+  /**
+   * Generate Jira epic template
+   */
+  generateJiraEpic(
+    competitorId: string,
+    competitorName: string,
+    threatLevel: ThreatLevel,
+    affectedLeadIds: string[]
+  ): ResponseAction {
+    const content = this.formatJiraTemplate(
+      competitorName,
+      threatLevel,
+      affectedLeadIds
+    );
+
+    const storyPoints =
+      threatLevel === 'CRITICAL' ? 21 : threatLevel === 'HIGH' ? 13 : 8;
+
+    return {
+      id: uuidv4(),
+      competitorId,
+      competitorName,
+      threatLevel,
+      type: 'jira',
+      target: 'product',
+      content,
+      affectedLeadIds,
+      affectedLeadCount: affectedLeadIds.length,
+      createdAt: new Date().toISOString(),
+      status: 'queued',
+      metadata: {
+        epicKey: `COMP-${competitorId.toUpperCase().substring(0, 5)}`,
+        storyPoints,
+        labels: [
+          'competitor-response',
+          threatLevel === 'CRITICAL' ? 'urgent' : 'standard',
+        ],
+        priority:
+          threatLevel === 'CRITICAL'
+            ? 'Highest'
+            : threatLevel === 'HIGH'
+              ? 'High'
+              : 'Medium',
+      },
+    };
+  }
+
+  /**
+   * Generate market analysis log entry
+   */
+  generateMarketAnalysisLog(
+    competitorId: string,
+    competitorName: string,
+    threatLevel: ThreatLevel,
+    affectedLeadIds: string[]
+  ): ResponseAction {
+    const timestamp = new Date().toISOString();
+    const content = `[${timestamp}] MARKET ANALYSIS: ${competitorName} (${threatLevel}) detected affecting ${affectedLeadIds.length} leads`;
+
+    return {
+      id: uuidv4(),
+      competitorId,
+      competitorName,
+      threatLevel,
+      type: 'log',
+      target: 'leadership',
+      content,
+      affectedLeadIds,
+      affectedLeadCount: affectedLeadIds.length,
+      createdAt: timestamp,
+      status: 'queued',
+      metadata: {
+        logLevel: threatLevel === 'CRITICAL' ? 'ERROR' : 'WARN',
+      },
+    };
+  }
+
+  /**
+   * Queue response action via Composio (human approval gate)
+   */
+  queueResponse(action: ResponseAction): {
+    queued: boolean;
+    actionId: string;
+    message: string;
+  } {
+    // Validate action
+    ResponseActionSchema.parse(action);
+
+    // Mark as queued
+    action.status = 'queued';
+    this.responseHistory.push(action);
+
+    return {
+      queued: true,
+      actionId: action.id,
+      message: `Response action queued for approval: ${action.type} to ${action.target}`,
+    };
+  }
+
+  /**
+   * Approve response action
+   */
+  approveResponse(
+    actionId: string,
+    approvedBy: string
+  ): ResponseAction | null {
+    const action = this.responseHistory.find((a) => a.id === actionId);
+    if (!action) return null;
+
+    action.status = 'approved';
+    action.approvedAt = new Date().toISOString();
+    action.approvedBy = approvedBy;
+
+    return action;
+  }
+
+  /**
+   * Reject response action
+   */
+  rejectResponse(actionId: string, approvedBy?: string): ResponseAction | null {
+    const action = this.responseHistory.find((a) => a.id === actionId);
+    if (!action) return null;
+
+    action.status = 'rejected';
+    action.approvedBy = approvedBy;
+
+    return action;
+  }
+
+  /**
+   * Execute response action (mark as executed)
+   */
+  executeResponse(
+    actionId: string,
+    result?: string
+  ): ResponseAction | null {
+    const action = this.responseHistory.find((a) => a.id === actionId);
+    if (!action) return null;
+
+    action.status = 'executed';
+    action.executedAt = new Date().toISOString();
+    action.executionResult = result;
+
+    return action;
+  }
+
+  /**
+   * Get response history
+   */
+  getResponseHistory(
+    competitorId?: string,
+    status?: ResponseActionStatus,
+    limit?: number
+  ): ResponseAction[] {
+    let results = this.responseHistory;
+
+    if (competitorId) {
+      results = results.filter((a) => a.competitorId === competitorId);
+    }
+
+    if (status) {
+      results = results.filter((a) => a.status === status);
+    }
+
+    if (limit) {
+      results = results.slice(-limit);
+    }
+
+    return results;
+  }
+
+  /**
+   * Get pending actions requiring approval
+   */
+  getPendingActions(): ResponseAction[] {
+    return this.responseHistory.filter((a) => a.status === 'queued');
+  }
+
+  /**
+   * Get action by ID
+   */
+  getAction(actionId: string): ResponseAction | null {
+    return this.responseHistory.find((a) => a.id === actionId) || null;
+  }
+
+  /**
+   * Private helper: Determine threat escalation type
+   */
+  private determineEscalationType(
+    oldScore: number,
+    newScore: number
+  ): 'MEDIUM_TO_HIGH' | 'HIGH_TO_CRITICAL' | 'JUMP' {
+    if (
+      oldScore < this.threatThresholds.HIGH &&
+      newScore >= this.threatThresholds.HIGH &&
+      newScore < this.threatThresholds.CRITICAL
+    ) {
+      return 'MEDIUM_TO_HIGH';
+    }
+    if (
+      oldScore < this.threatThresholds.CRITICAL &&
+      newScore >= this.threatThresholds.CRITICAL
+    ) {
+      return 'HIGH_TO_CRITICAL';
+    }
+    return 'JUMP';
+  }
+
+  /**
+   * Private helper: Get threat level
+   */
+  private getThreatLevel(score: number): ThreatLevel {
+    if (score >= this.threatThresholds.CRITICAL) return 'CRITICAL';
+    if (score >= this.threatThresholds.HIGH) return 'HIGH';
+    if (score >= this.threatThresholds.MEDIUM) return 'MEDIUM';
+    return 'LOW';
+  }
+
+  /**
+   * Private helper: Format email template
+   */
+  private formatEmailTemplate(
+    competitorName: string,
+    threatLevel: ThreatLevel,
+    affectedLeadIds: string[]
+  ): string {
+    return `
+Subject: Competitive Response Required - ${competitorName}
+
+Dear Sales Team,
+
+We have detected a ${threatLevel} threat from ${competitorName} in our pipeline.
+
+THREAT SUMMARY:
+- Competitor: ${competitorName}
+- Severity: ${threatLevel}
+- Affected Accounts: ${affectedLeadIds.length}
+- Lead IDs: ${affectedLeadIds.slice(0, 5).join(', ')}${affectedLeadIds.length > 5 ? ` (+${affectedLeadIds.length - 5} more)` : ''}
+
+RECOMMENDED ACTIONS:
+1. Review ${competitorName}'s latest features and positioning
+2. Identify and document our key competitive advantages
+3. Schedule calls with affected accounts to address concerns
+4. Prepare differentiation messaging for your conversations
+
+PRIORITY: ${threatLevel === 'CRITICAL' ? 'URGENT - Handle within 24 hours' : 'Handle within 48-72 hours'}
+
+For detailed analysis, please review the attached market intelligence.
+
+Best regards,
+Intelligence Team
+`;
+  }
+
+  /**
+   * Private helper: Format Jira template
+   */
+  private formatJiraTemplate(
+    competitorName: string,
+    threatLevel: ThreatLevel,
+    affectedLeadIds: string[]
+  ): string {
+    return `
+Title: Counter ${competitorName} ${threatLevel} Threat
+
+Description:
+h2. Threat Assessment
+- Competitor: ${competitorName}
+- Threat Level: ${threatLevel}
+- Affected Leads: ${affectedLeadIds.length}
+
+h2. Market Impact
+${competitorName} is gaining traction and poses a ${threatLevel} threat to our market position. Urgent product and marketing response required.
+
+h2. Feature Gaps to Address
+- Evaluate competitive features missing from our roadmap
+- Identify quick wins vs. long-term investments
+- Assess customer impact and priority
+
+h2. Acceptance Criteria
+- [ ] Competitive analysis completed
+- [ ] Feature gap assessment documented
+- [ ] Roadmap impact assessed
+- [ ] Response plan created
+- [ ] Sales team briefed on differentiation
+
+h2. Labels
+competitor-response, ${threatLevel === 'CRITICAL' ? 'urgent' : 'standard'}
+
+h2. Priority
+${threatLevel === 'CRITICAL' ? 'Highest' : threatLevel === 'HIGH' ? 'High' : 'Medium'}
+`;
+  }
+}
+
+// Export factory function
+export function createCompetitorResponseEngine(): CompetitorResponseEngine {
+  return new CompetitorResponseEngine();
+}