chargeback-guard 2.0.0

package/src/dispute/analyzer.ts

@@ -0,0 +1,317 @@
+// ============================================================
+//  CHARGEBACK GUARD — Dispute Analyzer
+//  Scores a dispute and recommends action
+// ============================================================
+
+import { createLogger } from '../utils/logger';
+import {
+  Dispute,
+  DisputeAnalysis,
+  Evidence,
+  DisputeReason,
+  RiskLevel,
+  ConfidenceLevel,
+} from '../types';
+
+const log = createLogger('DisputeAnalyzer');
+
+// ────────────────────────────────────────────────────────────
+//  ANALYSIS WEIGHTS
+// ────────────────────────────────────────────────────────────
+
+const WEIGHTS = {
+  deliveryProof:         0.30,
+  deviceConsistency:     0.20,
+  customerReputation:    0.20,
+  transactionNormality:  0.15,
+  evidenceCompleteness:  0.15,
+};
+
+// ────────────────────────────────────────────────────────────
+//  DISPUTE ANALYZER
+// ────────────────────────────────────────────────────────────
+
+export class DisputeAnalyzer {
+
+  async analyze(dispute: Dispute, evidence?: Evidence): Promise<DisputeAnalysis> {
+    log.debug(`Analyzing dispute: ${dispute.id}`);
+
+    const deliveryProof        = this._scoreDeliveryProof(dispute, evidence);
+    const deviceConsistency    = this._scoreDeviceConsistency(evidence);
+    const customerReputation   = this._scoreCustomerReputation(evidence);
+    const transactionNormality = this._scoreTransactionNormality(dispute, evidence);
+    const evidenceCompleteness = this._scoreEvidenceCompleteness(evidence);
+
+    const confidenceScore =
+      deliveryProof        * WEIGHTS.deliveryProof +
+      deviceConsistency    * WEIGHTS.deviceConsistency +
+      customerReputation   * WEIGHTS.customerReputation +
+      transactionNormality * WEIGHTS.transactionNormality +
+      evidenceCompleteness * WEIGHTS.evidenceCompleteness;
+
+    const riskLevel            = this._confidenceToRisk(confidenceScore);
+    const fraudProbability     = this._estimateFraudProbability(dispute, evidence);
+    const recommendedAction    = this._recommendAction(confidenceScore, fraudProbability, dispute);
+    const analysisReasons      = this._generateReasons(
+      dispute,
+      evidence,
+      { deliveryProof, deviceConsistency, customerReputation, transactionNormality }
+    );
+
+    const analysis: DisputeAnalysis = {
+      disputeId:             dispute.id,
+      riskLevel,
+      confidenceScore:       parseFloat(confidenceScore.toFixed(4)),
+      deliveryProofStrength: deliveryProof,
+      deviceConsistency,
+      customerReputationScore: customerReputation,
+      transactionNormality,
+      fraudProbability,
+      recommendedAction,
+      analysisReasons,
+      analyzedAt: new Date().toISOString(),
+    };
+
+    log.info(`Dispute analysis complete: ${dispute.id}`, {
+      confidenceScore: analysis.confidenceScore,
+      riskLevel,
+      recommendation: recommendedAction,
+    });
+
+    return analysis;
+  }
+
+  // ──────────────────────────────────────────
+  //  SCORING: Delivery Proof
+  // ──────────────────────────────────────────
+
+  private _scoreDeliveryProof(dispute: Dispute, evidence?: Evidence): number {
+    if (dispute.reason !== DisputeReason.PRODUCT_NOT_RECEIVED) {
+      return 0.85; // delivery proof not the core issue
+    }
+
+    let score = 0.2; // baseline
+
+    const shipping = evidence?.data?.shippingData;
+    if (!shipping) { return score; }
+
+    if (shipping.trackingNumber) { score += 0.35; }
+    if (shipping.deliveryDate)   { score += 0.20; }
+    if (shipping.signature)      { score += 0.15; }
+    if (shipping.gpsCoordinates) { score += 0.10; }
+
+    return Math.min(1.0, score);
+  }
+
+  // ──────────────────────────────────────────
+  //  SCORING: Device Consistency
+  // ──────────────────────────────────────────
+
+  private _scoreDeviceConsistency(evidence?: Evidence): number {
+    if (!evidence?.data) { return 0.3; }
+
+    let score = 0.3; // baseline
+
+    const cd = evidence.data.customerData;
+    if (cd?.ipAddress && cd.ipAddress !== '0.0.0.0') { score += 0.15; }
+    if (cd?.userAgent && cd.userAgent !== 'Unknown')  { score += 0.10; }
+    if (cd?.deviceId)                                  { score += 0.15; }
+
+    const fp = evidence.data.deviceFingerprint;
+    if (fp?.fingerprint)    { score += 0.15; }
+    if (fp?.screenResolution) { score += 0.05; }
+    if (fp?.timezone)         { score += 0.05; }
+    if (fp?.language)         { score += 0.05; }
+
+    return Math.min(1.0, score);
+  }
+
+  // ──────────────────────────────────────────
+  //  SCORING: Customer Reputation
+  // ──────────────────────────────────────────
+
+  private _scoreCustomerReputation(evidence?: Evidence): number {
+    const history = evidence?.data?.customerHistory;
+    if (!history) { return 0.5; }
+
+    let score = 0.4; // baseline
+
+    if (history.accountAge > 365)   { score += 0.20; }
+    else if (history.accountAge > 90) { score += 0.10; }
+    else if (history.accountAge > 30) { score += 0.05; }
+
+    if (history.previousPurchases >= 10) { score += 0.20; }
+    else if (history.previousPurchases >= 3) { score += 0.10; }
+
+    if (history.previousDisputes === 0)  { score += 0.20; }
+    else if (history.previousDisputes === 1) { score -= 0.10; }
+    else { score -= 0.30; }
+
+    if (history.trustScore > 0.8) { score += 0.10; }
+
+    return Math.max(0, Math.min(1.0, score));
+  }
+
+  // ──────────────────────────────────────────
+  //  SCORING: Transaction Normality
+  // ──────────────────────────────────────────
+
+  private _scoreTransactionNormality(dispute: Dispute, evidence?: Evidence): number {
+    let score = 0.5; // baseline
+
+    const interaction = evidence?.data?.interactionData;
+    if (interaction) {
+      if (interaction.sessionDuration > 120) { score += 0.15; }
+      if (interaction.pageViews?.length > 3)  { score += 0.10; }
+      if (interaction.timeOnCheckout > 30)    { score += 0.10; }
+      if (interaction.formInteractions?.length > 0) { score += 0.05; }
+    }
+
+    const paymentLog = evidence?.data?.paymentLog;
+    if (paymentLog) {
+      if (paymentLog.attempts === 1)   { score += 0.10; }
+      else if (paymentLog.failed > 3)  { score -= 0.20; }
+    }
+
+    // Unusual amount warning
+    if (dispute.amount > 100000) { score -= 0.10; } // > $1000
+
+    // IP reputation
+    const ipRep = evidence?.data?.customerData?.ipReputation;
+    if (ipRep !== undefined) {
+      if (ipRep < 0.3)      { score -= 0.30; }
+      else if (ipRep < 0.5) { score -= 0.15; }
+      else if (ipRep > 0.8) { score += 0.10; }
+    }
+
+    return Math.max(0, Math.min(1.0, score));
+  }
+
+  // ──────────────────────────────────────────
+  //  SCORING: Evidence Completeness
+  // ──────────────────────────────────────────
+
+  private _scoreEvidenceCompleteness(evidence?: Evidence): number {
+    if (!evidence) { return 0.1; }
+
+    const checks = [
+      !!evidence.data.customerData?.ipAddress,
+      !!evidence.data.customerData?.userAgent,
+      !!evidence.data.customerData?.deviceId,
+      !!evidence.data.transactionData?.timestamp,
+      !!evidence.data.transactionData?.transactionId,
+      !!evidence.data.shippingData?.trackingNumber,
+      !!evidence.data.shippingData?.address,
+      !!evidence.data.interactionData?.sessionDuration,
+      !!evidence.data.emailConfirmation?.sentTo,
+      !!evidence.data.customerHistory?.accountCreatedAt,
+    ];
+
+    const passed = checks.filter(Boolean).length;
+    return passed / checks.length;
+  }
+
+  // ──────────────────────────────────────────
+  //  FRAUD PROBABILITY
+  // ──────────────────────────────────────────
+
+  private _estimateFraudProbability(dispute: Dispute, evidence?: Evidence): number {
+    let probability = 0.1;
+
+    if (dispute.reason === DisputeReason.FRAUDULENT ||
+        dispute.reason === DisputeReason.UNAUTHORIZED_TRANSACTION) {
+      probability += 0.3;
+    }
+
+    const ipRep = evidence?.data?.customerData?.ipReputation;
+    if (ipRep !== undefined && ipRep < 0.4) {
+      probability += 0.25;
+    }
+
+    const history = evidence?.data?.customerHistory;
+    if (history?.previousDisputes && history.previousDisputes > 2) {
+      probability += 0.2;
+    }
+
+    if (dispute.amount > 50000) { probability += 0.1; } // > $500
+
+    return Math.min(1.0, parseFloat(probability.toFixed(4)));
+  }
+
+  // ──────────────────────────────────────────
+  //  RECOMMENDATION
+  // ──────────────────────────────────────────
+
+  private _recommendAction(
+    confidence: number,
+    fraudProb: number,
+    dispute: Dispute
+  ): 'fight' | 'accept' | 'review' {
+    // If confidence is very high → fight
+    if (confidence >= 0.75 && fraudProb < 0.4) { return 'fight'; }
+
+    // If confidence is very low → accept
+    if (confidence < 0.30) { return 'accept'; }
+
+    // Needs manual review
+    return 'review';
+  }
+
+  // ──────────────────────────────────────────
+  //  HUMAN-READABLE REASONS
+  // ──────────────────────────────────────────
+
+  private _generateReasons(
+    dispute: Dispute,
+    evidence: Evidence | undefined,
+    scores: Record<string, number>
+  ): string[] {
+    const reasons: string[] = [];
+
+    if (scores['deliveryProof'] > 0.7) {
+      reasons.push('Strong delivery proof with tracking and/or signature available');
+    } else if (scores['deliveryProof'] < 0.4) {
+      reasons.push('Weak delivery proof — tracking number missing');
+    }
+
+    if (scores['deviceConsistency'] > 0.7) {
+      reasons.push('Device fingerprint and IP are consistent across the session');
+    }
+
+    if (scores['customerReputation'] > 0.7) {
+      reasons.push('Customer has a clean purchase history with no prior disputes');
+    } else if (scores['customerReputation'] < 0.4) {
+      reasons.push('Customer has previous disputes on record');
+    }
+
+    const interaction = evidence?.data?.interactionData;
+    if (interaction?.sessionDuration && interaction.sessionDuration > 120) {
+      reasons.push(`Long engaged session (${interaction.sessionDuration}s) — indicates genuine purchase`);
+    }
+
+    if (dispute.reason === DisputeReason.FRAUDULENT) {
+      reasons.push('Dispute claims fraud — device fingerprint comparison is critical evidence');
+    }
+
+    return reasons;
+  }
+
+  // ──────────────────────────────────────────
+  //  CONVERTERS
+  // ──────────────────────────────────────────
+
+  private _confidenceToRisk(confidence: number): RiskLevel {
+    if (confidence >= 0.85) { return RiskLevel.VERY_LOW; }
+    if (confidence >= 0.70) { return RiskLevel.LOW; }
+    if (confidence >= 0.50) { return RiskLevel.MEDIUM; }
+    if (confidence >= 0.30) { return RiskLevel.HIGH; }
+    return RiskLevel.CRITICAL;
+  }
+
+  confidenceToLevel(score: number): ConfidenceLevel {
+    if (score >= 0.85) { return ConfidenceLevel.VERY_HIGH; }
+    if (score >= 0.65) { return ConfidenceLevel.HIGH; }
+    if (score >= 0.45) { return ConfidenceLevel.MEDIUM; }
+    return ConfidenceLevel.LOW;
+  }
+}

package/src/dispute/bankIntegration.ts

@@ -0,0 +1,274 @@
+// ============================================================
+//  CHARGEBACK GUARD — Bank Integration Abstraction
+//  Unified interface over Stripe / PayPal dispute submission
+// ============================================================
+
+import { createLogger } from '../utils/logger';
+import {
+  Dispute,
+  DisputeReply,
+  PaymentProvider,
+} from '../types';
+
+const log = createLogger('BankIntegration');
+
+// ────────────────────────────────────────────────────────────
+//  SUBMISSION RESULT
+// ────────────────────────────────────────────────────────────
+
+export interface SubmissionResult {
+  success: boolean;
+  disputeId: string;
+  status: string;
+  submittedAt: string;
+  trackingId?: string;
+  providerResponse?: unknown;
+  error?: string;
+}
+
+// ────────────────────────────────────────────────────────────
+//  ABSTRACT BANK ADAPTER
+// ────────────────────────────────────────────────────────────
+
+export abstract class BankAdapter {
+  abstract getProvider(): PaymentProvider;
+  abstract submitEvidence(dispute: Dispute, reply: DisputeReply): Promise<SubmissionResult>;
+  abstract getDisputeStatus(disputeId: string): Promise<string>;
+}
+
+// ────────────────────────────────────────────────────────────
+//  BANK INTEGRATION (provider dispatcher)
+// ────────────────────────────────────────────────────────────
+
+export class BankIntegration {
+  private adapters: Map<PaymentProvider, BankAdapter> = new Map();
+
+  registerAdapter(adapter: BankAdapter): void {
+    this.adapters.set(adapter.getProvider(), adapter);
+    log.debug(`Bank adapter registered: ${adapter.getProvider()}`);
+  }
+
+  async submitEvidence(dispute: Dispute, reply: DisputeReply): Promise<SubmissionResult> {
+    const adapter = this.adapters.get(dispute.provider);
+
+    if (!adapter) {
+      log.warn(`No adapter for provider: ${dispute.provider}`);
+      return {
+        success: false,
+        disputeId: dispute.id,
+        status: 'no_adapter',
+        submittedAt: new Date().toISOString(),
+        error: `No bank adapter registered for provider: ${dispute.provider}`,
+      };
+    }
+
+    log.info(`Submitting evidence via ${dispute.provider}: ${dispute.id}`);
+
+    try {
+      const result = await adapter.submitEvidence(dispute, reply);
+      log.info(`Evidence submitted: ${dispute.id}`, { status: result.status });
+      return result;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error(`Evidence submission failed: ${dispute.id}`, { error: message });
+      return {
+        success: false,
+        disputeId: dispute.id,
+        status: 'submission_failed',
+        submittedAt: new Date().toISOString(),
+        error: message,
+      };
+    }
+  }
+
+  async getDisputeStatus(
+    disputeId: string,
+    provider: PaymentProvider
+  ): Promise<string> {
+    const adapter = this.adapters.get(provider);
+    if (!adapter) {
+      throw new Error(`No adapter for provider: ${provider}`);
+    }
+    return adapter.getDisputeStatus(disputeId);
+  }
+
+  hasAdapter(provider: PaymentProvider): boolean {
+    return this.adapters.has(provider);
+  }
+
+  getSupportedProviders(): PaymentProvider[] {
+    return Array.from(this.adapters.keys());
+  }
+}
+
+// ────────────────────────────────────────────────────────────
+//  STRIPE BANK ADAPTER
+// ────────────────────────────────────────────────────────────
+
+export class StripeBankAdapter extends BankAdapter {
+  private stripe: unknown;
+
+  constructor(stripeSecretKey: string) {
+    super();
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const Stripe = require('stripe');
+    this.stripe = Stripe(stripeSecretKey);
+  }
+
+  getProvider(): PaymentProvider {
+    return PaymentProvider.STRIPE;
+  }
+
+  async submitEvidence(dispute: Dispute, reply: DisputeReply): Promise<SubmissionResult> {
+    const stripeEvidence = this._mapToStripeEvidence(reply);
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const response = await (this.stripe as any).disputes.submitEvidence(
+      dispute.id,
+      { evidence: stripeEvidence }
+    );
+
+    return {
+      success: true,
+      disputeId: response.id,
+      status: response.status,
+      submittedAt: new Date().toISOString(),
+      trackingId: `stripe-${response.id}-${Date.now()}`,
+      providerResponse: response,
+    };
+  }
+
+  async getDisputeStatus(disputeId: string): Promise<string> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const dispute = await (this.stripe as any).disputes.retrieve(disputeId);
+    return dispute.status as string;
+  }
+
+  private _mapToStripeEvidence(reply: DisputeReply): Record<string, unknown> {
+    const evidence: Record<string, unknown> = {
+      uncategorized_text: reply.caseArgument,
+    };
+
+    for (const item of reply.evidenceItems) {
+      const data = item.data;
+      switch (item.type) {
+        case 'delivery_proof':
+          evidence['shipping_documentation'] = JSON.stringify(data);
+          evidence['shipping_tracking_number'] = data['trackingNumber'] ?? '';
+          evidence['shipping_date'] = data['shippedAt'] ?? '';
+          break;
+        case 'device_fingerprint':
+          evidence['access_activity_log'] = JSON.stringify(data);
+          break;
+        case 'customer_communication':
+          evidence['customer_communication'] = JSON.stringify(data);
+          break;
+        case 'email_confirmation':
+          evidence['customer_email_address'] = data['sentTo'] ?? '';
+          evidence['customer_communication'] = JSON.stringify(data);
+          break;
+        case 'payment_log':
+          evidence['duplicate_charge_documentation'] = JSON.stringify(data);
+          break;
+      }
+    }
+
+    return evidence;
+  }
+}
+
+// ────────────────────────────────────────────────────────────
+//  PAYPAL BANK ADAPTER
+// ────────────────────────────────────────────────────────────
+
+export class PayPalBankAdapter extends BankAdapter {
+  private clientId: string;
+  private clientSecret: string;
+  private mode: string;
+  private accessToken: string | null = null;
+  private tokenExpiry: number = 0;
+
+  constructor(clientId: string, clientSecret: string, mode = 'sandbox') {
+    super();
+    this.clientId     = clientId;
+    this.clientSecret = clientSecret;
+    this.mode         = mode;
+  }
+
+  getProvider(): PaymentProvider {
+    return PaymentProvider.PAYPAL;
+  }
+
+  async submitEvidence(dispute: Dispute, reply: DisputeReply): Promise<SubmissionResult> {
+    const token  = await this._getAccessToken();
+    const baseUrl = this.mode === 'live'
+      ? 'https://api.paypal.com'
+      : 'https://api.sandbox.paypal.com';
+
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const axios = require('axios');
+    const response = await axios.post(
+      `${baseUrl}/v1/customer/disputes/${dispute.id}/provide-evidence`,
+      {
+        evidences: [{
+          evidence_type: 'PROOF_OF_FULFILLMENT',
+          notes: reply.caseArgument,
+        }],
+      },
+      {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          'Content-Type': 'application/json',
+        },
+      }
+    );
+
+    return {
+      success: true,
+      disputeId: dispute.id,
+      status: 'submitted',
+      submittedAt: new Date().toISOString(),
+      providerResponse: response.data,
+    };
+  }
+
+  async getDisputeStatus(disputeId: string): Promise<string> {
+    const token   = await this._getAccessToken();
+    const baseUrl = this.mode === 'live'
+      ? 'https://api.paypal.com'
+      : 'https://api.sandbox.paypal.com';
+
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const axios = require('axios');
+    const response = await axios.get(
+      `${baseUrl}/v1/customer/disputes/${disputeId}`,
+      { headers: { Authorization: `Bearer ${token}` } }
+    );
+    return (response.data as Record<string, string>)['status'] ?? 'unknown';
+  }
+
+  private async _getAccessToken(): Promise<string> {
+    if (this.accessToken && Date.now() < this.tokenExpiry) {
+      return this.accessToken;
+    }
+
+    const baseUrl = this.mode === 'live'
+      ? 'https://api.paypal.com'
+      : 'https://api.sandbox.paypal.com';
+
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const axios = require('axios');
+    const response = await axios.post(
+      `${baseUrl}/v1/oauth2/token`,
+      'grant_type=client_credentials',
+      {
+        auth: { username: this.clientId, password: this.clientSecret },
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      }
+    );
+
+    this.accessToken = (response.data as Record<string, string>)['access_token'];
+    this.tokenExpiry = Date.now() + ((response.data as Record<string, number>)['expires_in'] - 60) * 1000;
+    return this.accessToken!;
+  }
+}