chargeback-guard 2.0.0

package/src/core/chargebackGuard.ts

@@ -0,0 +1,616 @@
+// ============================================================
+//  CHARGEBACK GUARD — Main Core Engine (Ultra Pro)
+// ============================================================
+
+import { ChargebackEventEmitter } from './eventEmitter';
+import { LifecycleManager } from './lifecycle';
+import { createLogger } from '../utils/logger';
+import config, { defaultConfig } from '../config';
+import {
+  ChargebackGuardConfig,
+  PaymentData,
+  Dispute,
+  Evidence,
+  DisputeReply,
+  DisputeAnalysis,
+  ProtectionStats,
+  NotificationEvent,
+  RiskLevel,
+  DisputeStatus,
+  PaymentProvider,
+  ApiResponse,
+} from '../types';
+
+const log = createLogger('ChargebackGuard');
+
+// ────────────────────────────────────────────────────────────
+//  LAZY MODULE IMPORTS (to avoid circular deps)
+// ────────────────────────────────────────────────────────────
+
+/* eslint-disable @typescript-eslint/no-var-requires */
+const getEvidenceCollector = () => require('../evidence/collector').EvidenceCollector;
+const getEvidenceValidator = () => require('../evidence/validator').EvidenceValidator;
+const getEvidenceStorage  = () => require('../evidence/storage').EvidenceStorage;
+const getDisputeDetector  = () => require('../dispute/detector').DisputeDetector;
+const getDisputeAnalyzer  = () => require('../dispute/analyzer').DisputeAnalyzer;
+const getResponseEngine   = () => require('../dispute/responseEngine').ResponseEngine;
+const getFraudDetection   = () => require('../ai/fraudDetection').FraudDetection;
+const getDatabaseManager  = () => require('../database/schema').DatabaseManager;
+const getNotificationSvc  = () => require('../notifications/inApp').NotificationService;
+/* eslint-enable @typescript-eslint/no-var-requires */
+
+// ────────────────────────────────────────────────────────────
+//  REGISTRATION RESULT
+// ────────────────────────────────────────────────────────────
+
+export interface RegistrationResult {
+  success: boolean;
+  orderId: string;
+  protectionActive: boolean;
+  trustScore: number;
+  riskLevel: RiskLevel;
+  evidenceCollectionId?: string;
+  warnings?: string[];
+}
+
+export interface DisputeHandlingResult {
+  success: boolean;
+  disputeId: string;
+  orderId?: string;
+  actionTaken: 'auto-reply_submitted' | 'manual_review_required' | 'accepted' | 'skipped';
+  confidence?: number;
+  riskLevel?: RiskLevel;
+  replySubmitted: boolean;
+}
+
+// ────────────────────────────────────────────────────────────
+//  MAIN CLASS
+// ────────────────────────────────────────────────────────────
+
+export class ChargebackGuard {
+  public readonly events: ChargebackEventEmitter;
+  public readonly lifecycle: LifecycleManager;
+
+  private readonly cfg: ChargebackGuardConfig;
+  private evidenceCollector: unknown;
+  private evidenceValidator: unknown;
+  private evidenceStorage: unknown;
+  private disputeDetector: unknown;
+  private disputeAnalyzer: unknown;
+  private responseEngine: unknown;
+  private fraudDetection: unknown;
+  private db: unknown;
+  private notificationSvc: unknown;
+
+  constructor(options: Partial<ChargebackGuardConfig> = {}) {
+    this.cfg = { ...defaultConfig, ...options } as ChargebackGuardConfig;
+    this.events = new ChargebackEventEmitter();
+    this.lifecycle = new LifecycleManager();
+
+    this._registerLifecycleHooks();
+    this._registerDefaultEventHandlers();
+
+    log.info('ChargebackGuard instance created', {
+      environment: this.cfg.environment,
+      autoReply: this.cfg.autoReply,
+      evidenceCollection: this.cfg.evidenceCollection,
+    });
+  }
+
+  // ──────────────────────────────────────────
+  //  INITIALIZATION
+  // ──────────────────────────────────────────
+
+  async initialize(): Promise<void> {
+    await this.lifecycle.initialize();
+  }
+
+  async shutdown(): Promise<void> {
+    await this.lifecycle.shutdown();
+  }
+
+  // ──────────────────────────────────────────
+  //  CORE: REGISTER PAYMENT
+  // ──────────────────────────────────────────
+
+  /**
+   * Register a new payment for chargeback protection.
+   * Call this immediately after a successful charge.
+   */
+  async registerPayment(paymentData: PaymentData): Promise<RegistrationResult> {
+    const operationStart = Date.now();
+    log.info(`Registering payment: ${paymentData.orderId}`, {
+      amount: paymentData.amount,
+      currency: paymentData.currency,
+    });
+
+    try {
+      // ── 1. Validate input ──────────────────
+      this._validatePaymentData(paymentData);
+
+      // ── 2. Run fraud pre-check ─────────────
+      const fraudResult = await this._runFraudPreCheck(paymentData);
+      if (fraudResult.isFraud && fraudResult.probability > 0.95) {
+        this.events.emitEvent(NotificationEvent.FRAUD_DETECTED, {
+          orderId: paymentData.orderId,
+          probability: fraudResult.probability,
+        });
+        log.warn(`Potential fraud detected for order ${paymentData.orderId}`, {
+          probability: fraudResult.probability,
+        });
+      }
+
+      // ── 3. Store the order ─────────────────
+      const db = this._getDb();
+      await db.orders.create({
+        orderId: paymentData.orderId,
+        amount: paymentData.amount,
+        currency: paymentData.currency,
+        customerEmail: paymentData.customerEmail,
+        provider: paymentData.provider ?? PaymentProvider.STRIPE,
+        status: 'active',
+        registeredAt: new Date().toISOString(),
+      });
+
+      // ── 4. Collect evidence ────────────────
+      let evidence: Evidence | undefined;
+      let evidenceCollectionId: string | undefined;
+
+      if (this.cfg.evidenceCollection !== false) {
+        const collector = this._getEvidenceCollector();
+        const validator = this._getEvidenceValidator();
+        const storage   = this._getEvidenceStorage();
+
+        const rawEvidence = await collector.collect({
+          orderId: paymentData.orderId,
+          customerIp: paymentData.customerIp,
+          userAgent: paymentData.userAgent,
+          sessionData: paymentData.sessionData,
+          deviceFingerprint: paymentData.deviceFingerprint,
+          amount: paymentData.amount,
+          currency: paymentData.currency,
+          transactionId: paymentData.transactionId,
+          shippingAddress: paymentData.shippingAddress,
+          customerEmail: paymentData.customerEmail,
+        });
+
+        evidence = await validator.validate(rawEvidence);
+        evidenceCollectionId = await storage.store(evidence);
+      }
+
+      // ── 5. Emit success event ──────────────
+      const trustScore = evidence?.trustScore ?? 75;
+      const riskLevel  = this._scoreToRiskLevel(trustScore);
+
+      this.events.emitEvent(NotificationEvent.PAYMENT_REGISTERED, {
+        orderId: paymentData.orderId,
+        trustScore,
+        riskLevel,
+        durationMs: Date.now() - operationStart,
+      });
+
+      if (riskLevel === RiskLevel.HIGH || riskLevel === RiskLevel.CRITICAL) {
+        this.events.emitEvent(NotificationEvent.HIGH_RISK_TRANSACTION, {
+          orderId: paymentData.orderId,
+          riskLevel,
+          fraudProbability: fraudResult?.probability ?? 0,
+        });
+      }
+
+      const result: RegistrationResult = {
+        success: true,
+        orderId: paymentData.orderId,
+        protectionActive: true,
+        trustScore,
+        riskLevel,
+        evidenceCollectionId,
+      };
+
+      log.info(`Payment registered successfully: ${paymentData.orderId}`, {
+        trustScore,
+        riskLevel,
+        durationMs: Date.now() - operationStart,
+      });
+
+      return result;
+
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error(`Payment registration failed: ${paymentData.orderId}`, { error: message });
+      this.events.emitEvent(NotificationEvent.ERROR, {
+        type: 'payment_registration_failed',
+        orderId: paymentData.orderId,
+        error: message,
+      });
+      throw err;
+    }
+  }
+
+  // ──────────────────────────────────────────
+  //  CORE: HANDLE DISPUTE
+  // ──────────────────────────────────────────
+
+  /**
+   * Handle an incoming dispute/chargeback notification from the bank.
+   * This is the heart of the auto-reply engine.
+   */
+  async handleDispute(dispute: Dispute): Promise<DisputeHandlingResult> {
+    const operationStart = Date.now();
+    log.info(`Handling dispute: ${dispute.id}`, {
+      reason: dispute.reason,
+      amount: dispute.amount,
+      orderId: dispute.orderId,
+    });
+
+    this.events.emitEvent(NotificationEvent.DISPUTE_DETECTED, {
+      disputeId: dispute.id,
+      reason: dispute.reason,
+      amount: dispute.amount,
+    });
+
+    try {
+      // ── 1. Analyze the dispute ─────────────
+      const analyzer = this._getDisputeAnalyzer();
+      const analysis: DisputeAnalysis = await analyzer.analyze(dispute);
+
+      log.info(`Dispute analysis complete: ${dispute.id}`, {
+        riskLevel: analysis.riskLevel,
+        confidenceScore: analysis.confidenceScore,
+        recommendedAction: analysis.recommendedAction,
+      });
+
+      // ── 2. Load stored evidence ────────────
+      const storage = this._getEvidenceStorage();
+      const evidence: Evidence | null = dispute.orderId
+        ? await storage.findByOrderId(dispute.orderId)
+        : null;
+
+      if (!evidence) {
+        log.warn(`No evidence found for order: ${dispute.orderId}`);
+      }
+
+      // ── 3. Decide action ───────────────────
+      if (analysis.recommendedAction === 'accept') {
+        log.info(`Accepting dispute (low confidence): ${dispute.id}`);
+        await this._updateDisputeRecord(dispute.id, dispute.orderId, DisputeStatus.CHARGE_REFUNDED);
+        return {
+          success: true,
+          disputeId: dispute.id,
+          orderId: dispute.orderId,
+          actionTaken: 'accepted',
+          confidence: analysis.confidenceScore,
+          riskLevel: analysis.riskLevel,
+          replySubmitted: false,
+        };
+      }
+
+      // ── 4. Generate reply ──────────────────
+      const engine = this._getResponseEngine();
+      const reply: DisputeReply = await engine.generateReply({
+        dispute,
+        evidence,
+        analysis,
+      });
+
+      // ── 5. Submit to bank (auto-reply) ─────
+      let replySubmitted = false;
+      if (this.cfg.autoReply !== false) {
+        try {
+          await this._submitReplyToProvider(dispute, reply);
+          replySubmitted = true;
+          log.info(`Reply submitted to provider: ${dispute.id}`);
+        } catch (submitErr) {
+          const msg = submitErr instanceof Error ? submitErr.message : String(submitErr);
+          log.error(`Failed to submit reply: ${dispute.id}`, { error: msg });
+        }
+      }
+
+      // ── 6. Persist dispute record ──────────
+      await this._updateDisputeRecord(
+        dispute.id,
+        dispute.orderId,
+        replySubmitted ? DisputeStatus.UNDER_REVIEW : DisputeStatus.NEEDS_RESPONSE,
+        reply
+      );
+
+      // ── 7. Emit events ─────────────────────
+      this.events.emitEvent(NotificationEvent.DISPUTE_REPLIED, {
+        disputeId: dispute.id,
+        orderId: dispute.orderId,
+        replySubmitted,
+        confidenceScore: analysis.confidenceScore,
+        durationMs: Date.now() - operationStart,
+      });
+
+      return {
+        success: true,
+        disputeId: dispute.id,
+        orderId: dispute.orderId,
+        actionTaken: replySubmitted ? 'auto-reply_submitted' : 'manual_review_required',
+        confidence: analysis.confidenceScore,
+        riskLevel: analysis.riskLevel,
+        replySubmitted,
+      };
+
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error(`Dispute handling failed: ${dispute.id}`, { error: message });
+      this.events.emitEvent(NotificationEvent.ERROR, {
+        type: 'dispute_handling_failed',
+        disputeId: dispute.id,
+        error: message,
+      });
+      throw err;
+    }
+  }
+
+  // ──────────────────────────────────────────
+  //  STATS & ANALYTICS
+  // ──────────────────────────────────────────
+
+  async getProtectionStats(fromDate?: Date, toDate?: Date): Promise<ProtectionStats> {
+    const db = this._getDb();
+
+    const [totalOrders, totalDisputes, wonDisputes, lostDisputes, pendingDisputes] =
+      await Promise.all([
+        db.orders.count(fromDate, toDate),
+        db.disputes.count(fromDate, toDate),
+        db.disputes.countByStatus(DisputeStatus.WON, fromDate, toDate),
+        db.disputes.countByStatus(DisputeStatus.LOST, fromDate, toDate),
+        db.disputes.countByStatus(DisputeStatus.NEEDS_RESPONSE, fromDate, toDate),
+      ]);
+
+    const resolvedDisputes = wonDisputes + lostDisputes;
+    const winRate = totalDisputes > 0 ? (wonDisputes / totalDisputes) * 100 : 0;
+    const chargebackRate = totalOrders > 0 ? (totalDisputes / totalOrders) * 100 : 0;
+
+    const totalMoneyRecovered = await db.disputes.sumAmountByStatus(DisputeStatus.WON, fromDate, toDate);
+    const totalMoneyLost      = await db.disputes.sumAmountByStatus(DisputeStatus.LOST, fromDate, toDate);
+    const estimatedSavings    = totalMoneyRecovered * 1.25; // including avoided fees
+
+    const avgResolutionTime = await db.disputes.avgResolutionTime(fromDate, toDate);
+
+    return {
+      totalOrders,
+      totalDisputes,
+      resolvedDisputes,
+      wonDisputes,
+      lostDisputes,
+      pendingDisputes,
+      winRate: parseFloat(winRate.toFixed(2)),
+      totalMoneyRecovered,
+      totalMoneyLost,
+      averageResolutionTime: avgResolutionTime,
+      chargebackRate: parseFloat(chargebackRate.toFixed(4)),
+      estimatedSavings,
+    };
+  }
+
+  async getHealth(): Promise<ApiResponse<unknown>> {
+    const health = await this.lifecycle.getSystemHealth();
+    return {
+      success: health.status !== 'unhealthy',
+      data: health,
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  PRIVATE HELPERS
+  // ──────────────────────────────────────────
+
+  private _validatePaymentData(data: PaymentData): void {
+    if (!data.orderId?.trim()) { throw new Error('orderId is required'); }
+    if (!data.amount || data.amount <= 0) { throw new Error('amount must be positive'); }
+    if (!data.currency?.trim()) { throw new Error('currency is required'); }
+    if (!data.customerEmail?.trim()) { throw new Error('customerEmail is required'); }
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data.customerEmail)) {
+      throw new Error('customerEmail is invalid');
+    }
+  }
+
+  private async _runFraudPreCheck(data: PaymentData): Promise<{
+    isFraud: boolean;
+    probability: number;
+  }> {
+    try {
+      const fraud = this._getFraudDetection();
+      return await fraud.quickCheck(data);
+    } catch {
+      return { isFraud: false, probability: 0 };
+    }
+  }
+
+  private async _submitReplyToProvider(dispute: Dispute, reply: DisputeReply): Promise<void> {
+    // Dynamic import to avoid circular deps at module load time
+    if (dispute.provider === PaymentProvider.STRIPE) {
+      const { StripeIntegration } = require('../integrations/stripe');
+      const stripe = new StripeIntegration(config.stripe.secretKey);
+      await stripe.submitDisputeEvidence(dispute.id, reply);
+    } else if (dispute.provider === PaymentProvider.PAYPAL) {
+      const { PayPalIntegration } = require('../integrations/paypal');
+      const paypal = new PayPalIntegration(
+        config.paypal.clientId,
+        config.paypal.clientSecret,
+        config.paypal.mode
+      );
+      await paypal.submitDisputeEvidence(dispute.id, reply);
+    }
+  }
+
+  private async _updateDisputeRecord(
+    disputeId: string,
+    orderId: string | undefined,
+    status: DisputeStatus,
+    reply?: DisputeReply
+  ): Promise<void> {
+    try {
+      const db = this._getDb();
+      await db.disputes.upsert({
+        disputeId,
+        orderId: orderId ?? '',
+        status,
+        replyJson: reply ? JSON.stringify(reply) : undefined,
+        replySubmittedAt: reply ? new Date().toISOString() : undefined,
+      });
+    } catch (err) {
+      log.warn('Failed to update dispute record', {
+        disputeId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  private _scoreToRiskLevel(trustScore: number): RiskLevel {
+    if (trustScore >= 90) { return RiskLevel.VERY_LOW; }
+    if (trustScore >= 75) { return RiskLevel.LOW; }
+    if (trustScore >= 55) { return RiskLevel.MEDIUM; }
+    if (trustScore >= 35) { return RiskLevel.HIGH; }
+    return RiskLevel.CRITICAL;
+  }
+
+  // ──────────────────────────────────────────
+  //  LIFECYCLE HOOKS
+  // ──────────────────────────────────────────
+
+  private _registerLifecycleHooks(): void {
+    this.lifecycle.registerInitHook({
+      name: 'database',
+      fn: async () => {
+        const db = this._getDb();
+        await db.initialize();
+      },
+      timeout: 15000,
+    });
+
+    this.lifecycle.registerInitHook({
+      name: 'fraud-model',
+      fn: async () => {
+        const fraud = this._getFraudDetection();
+        await fraud.loadModel();
+      },
+      timeout: 30000,
+    });
+
+    this.lifecycle.registerShutdownHook({
+      name: 'database',
+      fn: async () => {
+        const db = this._getDb();
+        await db.destroy();
+      },
+    });
+
+    // Register health checkers
+    this.lifecycle.registerHealthChecker('database', async () => {
+      try {
+        const db = this._getDb();
+        await db.healthCheck();
+        return {
+          name: 'database',
+          status: 'healthy' as const,
+          checkedAt: new Date().toISOString(),
+        };
+      } catch (err) {
+        return {
+          name: 'database',
+          status: 'unhealthy' as const,
+          message: err instanceof Error ? err.message : String(err),
+          checkedAt: new Date().toISOString(),
+        };
+      }
+    });
+  }
+
+  // ──────────────────────────────────────────
+  //  DEFAULT EVENT HANDLERS
+  // ──────────────────────────────────────────
+
+  private _registerDefaultEventHandlers(): void {
+    this.events.on(NotificationEvent.PAYMENT_REGISTERED, ({ data }) => {
+      log.info(`✅ Payment registered: ${data['orderId']} | Trust: ${data['trustScore']} | Risk: ${data['riskLevel']}`);
+    });
+
+    this.events.on(NotificationEvent.DISPUTE_DETECTED, ({ data }) => {
+      log.warn(`🚨 Dispute detected: ${data['disputeId']} | Reason: ${data['reason']} | Amount: $${data['amount']}`);
+    });
+
+    this.events.on(NotificationEvent.DISPUTE_REPLIED, ({ data }) => {
+      log.info(`📤 Reply sent for: ${data['disputeId']} | Confidence: ${data['confidenceScore']}`);
+    });
+
+    this.events.on(NotificationEvent.DISPUTE_WON, ({ data }) => {
+      log.info(`🏆 Dispute WON: ${data['disputeId']} | Recovered: $${data['amount']}`);
+    });
+
+    this.events.on(NotificationEvent.DISPUTE_LOST, ({ data }) => {
+      log.warn(`❌ Dispute LOST: ${data['disputeId']} | Amount: $${data['amount']}`);
+    });
+
+    this.events.on(NotificationEvent.FRAUD_DETECTED, ({ data }) => {
+      log.warn(`🔴 FRAUD ALERT: Order ${data['orderId']} | Probability: ${data['probability']}`);
+    });
+
+    this.events.on(NotificationEvent.ERROR, ({ data }) => {
+      log.error(`❌ Error: ${data['type']}`, { error: data['error'] });
+    });
+  }
+
+  // ──────────────────────────────────────────
+  //  LAZY SERVICE GETTERS
+  // ──────────────────────────────────────────
+
+  private _getEvidenceCollector(): any { // eslint-disable-line @typescript-eslint/no-explicit-any
+    if (!this.evidenceCollector) {
+      const Cls = getEvidenceCollector();
+      this.evidenceCollector = new Cls();
+    }
+    return this.evidenceCollector;
+  }
+
+  private _getEvidenceValidator(): any { // eslint-disable-line @typescript-eslint/no-explicit-any
+    if (!this.evidenceValidator) {
+      const Cls = getEvidenceValidator();
+      this.evidenceValidator = new Cls();
+    }
+    return this.evidenceValidator;
+  }
+
+  private _getEvidenceStorage(): any { // eslint-disable-line @typescript-eslint/no-explicit-any
+    if (!this.evidenceStorage) {
+      const Cls = getEvidenceStorage();
+      this.evidenceStorage = new Cls();
+    }
+    return this.evidenceStorage;
+  }
+
+  private _getDisputeAnalyzer(): any { // eslint-disable-line @typescript-eslint/no-explicit-any
+    if (!this.disputeAnalyzer) {
+      const Cls = getDisputeAnalyzer();
+      this.disputeAnalyzer = new Cls();
+    }
+    return this.disputeAnalyzer;
+  }
+
+  private _getResponseEngine(): any { // eslint-disable-line @typescript-eslint/no-explicit-any
+    if (!this.responseEngine) {
+      const Cls = getResponseEngine();
+      this.responseEngine = new Cls();
+    }
+    return this.responseEngine;
+  }
+
+  private _getFraudDetection(): any { // eslint-disable-line @typescript-eslint/no-explicit-any
+    if (!this.fraudDetection) {
+      const Cls = getFraudDetection();
+      this.fraudDetection = new Cls(config.ai);
+    }
+    return this.fraudDetection;
+  }
+
+  private _getDb(): any { // eslint-disable-line @typescript-eslint/no-explicit-any
+    if (!this.db) {
+      const Cls = getDatabaseManager();
+      this.db = new Cls(config.db);
+    }
+    return this.db;
+  }
+}