chargeback-guard 2.0.0

package/src/dispute/detector.ts

@@ -0,0 +1,239 @@
+// ============================================================
+//  CHARGEBACK GUARD — Dispute Detector
+//  Parses incoming webhook events and identifies disputes
+// ============================================================
+
+import { createLogger } from '../utils/logger';
+import {
+  Dispute,
+  DisputeReason,
+  DisputeStatus,
+  PaymentProvider,
+  WebhookEvent,
+} from '../types';
+
+const log = createLogger('DisputeDetector');
+
+// ────────────────────────────────────────────────────────────
+//  STRIPE REASON MAP
+// ────────────────────────────────────────────────────────────
+
+const STRIPE_REASON_MAP: Record<string, DisputeReason> = {
+  'product_not_received':        DisputeReason.PRODUCT_NOT_RECEIVED,
+  'product_unacceptable':        DisputeReason.PRODUCT_UNACCEPTABLE,
+  'fraudulent':                  DisputeReason.FRAUDULENT,
+  'unrecognized':                DisputeReason.UNAUTHORIZED_TRANSACTION,
+  'duplicate':                   DisputeReason.DUPLICATE_TRANSACTION,
+  'credit_not_processed':        DisputeReason.CREDIT_NOT_PROCESSED,
+  'subscription_canceled':       DisputeReason.SUBSCRIPTION_CANCELLED,
+  'general':                     DisputeReason.GENERAL,
+};
+
+const STRIPE_STATUS_MAP: Record<string, DisputeStatus> = {
+  'needs_response':              DisputeStatus.NEEDS_RESPONSE,
+  'under_review':                DisputeStatus.UNDER_REVIEW,
+  'charge_refunded':             DisputeStatus.CHARGE_REFUNDED,
+  'won':                         DisputeStatus.WON,
+  'lost':                        DisputeStatus.LOST,
+  'warning_needs_response':      DisputeStatus.WARNING_NEEDS_RESPONSE,
+  'warning_under_review':        DisputeStatus.WARNING_UNDER_REVIEW,
+  'warning_closed':              DisputeStatus.WARNING_CLOSED,
+};
+
+// ────────────────────────────────────────────────────────────
+//  PAYPAL REASON MAP
+// ────────────────────────────────────────────────────────────
+
+const PAYPAL_REASON_MAP: Record<string, DisputeReason> = {
+  'MERCHANDISE_OR_SERVICE_NOT_RECEIVED': DisputeReason.PRODUCT_NOT_RECEIVED,
+  'MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED': DisputeReason.PRODUCT_UNACCEPTABLE,
+  'UNAUTHORISED':                        DisputeReason.UNAUTHORIZED_TRANSACTION,
+  'CREDIT_NOT_PROCESSED':                DisputeReason.CREDIT_NOT_PROCESSED,
+  'DUPLICATE_TRANSACTION':               DisputeReason.DUPLICATE_TRANSACTION,
+  'INCORRECT_AMOUNT':                    DisputeReason.GENERAL,
+  'PAYMENT_BY_OTHER_MEANS':              DisputeReason.GENERAL,
+  'CANCELED_RECURRING_BILLING':          DisputeReason.SUBSCRIPTION_CANCELLED,
+  'PROBLEM_WITH_REMITTANCE':             DisputeReason.GENERAL,
+  'OTHER':                               DisputeReason.GENERAL,
+};
+
+// ────────────────────────────────────────────────────────────
+//  DISPUTE DETECTOR
+// ────────────────────────────────────────────────────────────
+
+export class DisputeDetector {
+
+  // ──────────────────────────────────────────
+  //  DETECT FROM WEBHOOK EVENT
+  // ──────────────────────────────────────────
+
+  detect(event: WebhookEvent): Dispute | null {
+    log.debug(`Detecting dispute from event: ${event.type}`);
+
+    switch (event.provider) {
+      case PaymentProvider.STRIPE:
+        return this._detectStripe(event);
+      case PaymentProvider.PAYPAL:
+        return this._detectPayPal(event);
+      default:
+        log.warn(`Unsupported provider for dispute detection: ${event.provider}`);
+        return null;
+    }
+  }
+
+  // ──────────────────────────────────────────
+  //  STRIPE DETECTION
+  // ──────────────────────────────────────────
+
+  private _detectStripe(event: WebhookEvent): Dispute | null {
+    const disputeEventTypes = [
+      'charge.dispute.created',
+      'charge.dispute.updated',
+      'charge.dispute.closed',
+      'charge.dispute.funds_withdrawn',
+      'charge.dispute.funds_reinstated',
+    ];
+
+    if (!disputeEventTypes.includes(event.type)) {
+      return null;
+    }
+
+    const obj = event.data.object as Record<string, unknown>;
+
+    const rawReason  = (obj['reason'] as string) ?? 'general';
+    const rawStatus  = (obj['status'] as string) ?? 'needs_response';
+    const orderId    = (obj['metadata'] as Record<string, string>)?.['order_id']
+                    ?? (obj['metadata'] as Record<string, string>)?.['orderId']
+                    ?? undefined;
+
+    const dispute: Dispute = {
+      id: obj['id'] as string,
+      orderId,
+      amount: (obj['amount'] as number) ?? 0,
+      currency: (obj['currency'] as string) ?? 'usd',
+      reason: STRIPE_REASON_MAP[rawReason] ?? DisputeReason.GENERAL,
+      status: STRIPE_STATUS_MAP[rawStatus] ?? DisputeStatus.NEEDS_RESPONSE,
+      provider: PaymentProvider.STRIPE,
+      evidenceDueBy: obj['evidence_due_by']
+        ? new Date((obj['evidence_due_by'] as number) * 1000).toISOString()
+        : undefined,
+      createdAt: new Date((obj['created'] as number) * 1000).toISOString(),
+      metadata: obj['metadata'] as Record<string, unknown>,
+      evidence: obj['evidence'] as Record<string, unknown>,
+    };
+
+    log.info(`Stripe dispute detected: ${dispute.id}`, {
+      reason: dispute.reason,
+      status: dispute.status,
+      amount: dispute.amount,
+    });
+
+    return dispute;
+  }
+
+  // ──────────────────────────────────────────
+  //  PAYPAL DETECTION
+  // ──────────────────────────────────────────
+
+  private _detectPayPal(event: WebhookEvent): Dispute | null {
+    const disputeEventTypes = [
+      'CUSTOMER.DISPUTE.CREATED',
+      'CUSTOMER.DISPUTE.UPDATED',
+      'CUSTOMER.DISPUTE.RESOLVED',
+    ];
+
+    if (!disputeEventTypes.includes(event.type)) {
+      return null;
+    }
+
+    const resource = event.data.object as Record<string, unknown>;
+    const disputeInfo = (resource['dispute'] as Record<string, unknown>) ?? resource;
+
+    const rawReason = (disputeInfo['reason'] as string) ?? 'OTHER';
+    const rawStatus = (disputeInfo['status'] as string) ?? 'OPEN';
+
+    const dispute: Dispute = {
+      id: disputeInfo['dispute_id'] as string ?? event.id,
+      orderId: this._extractPayPalOrderId(disputeInfo),
+      amount: this._extractPayPalAmount(disputeInfo),
+      currency: 'USD',
+      reason: PAYPAL_REASON_MAP[rawReason] ?? DisputeReason.GENERAL,
+      status: this._mapPayPalStatus(rawStatus),
+      provider: PaymentProvider.PAYPAL,
+      createdAt: (disputeInfo['create_time'] as string) ?? new Date().toISOString(),
+      metadata: { raw: disputeInfo },
+    };
+
+    log.info(`PayPal dispute detected: ${dispute.id}`, {
+      reason: dispute.reason,
+      amount: dispute.amount,
+    });
+
+    return dispute;
+  }
+
+  // ──────────────────────────────────────────
+  //  HELPERS
+  // ──────────────────────────────────────────
+
+  private _extractPayPalOrderId(resource: Record<string, unknown>): string | undefined {
+    const transactions = resource['disputed_transactions'] as Array<Record<string, unknown>>;
+    if (transactions?.length) {
+      return transactions[0]['seller_transaction_id'] as string;
+    }
+    return undefined;
+  }
+
+  private _extractPayPalAmount(resource: Record<string, unknown>): number {
+    const amount = (resource['dispute_amount'] as Record<string, string>)?.['value'];
+    return amount ? parseFloat(amount) * 100 : 0; // convert to cents
+  }
+
+  private _mapPayPalStatus(status: string): DisputeStatus {
+    const map: Record<string, DisputeStatus> = {
+      'OPEN':          DisputeStatus.NEEDS_RESPONSE,
+      'WAITING_FOR_BUYER_RESPONSE': DisputeStatus.UNDER_REVIEW,
+      'WAITING_FOR_SELLER_RESPONSE': DisputeStatus.NEEDS_RESPONSE,
+      'UNDER_REVIEW':  DisputeStatus.UNDER_REVIEW,
+      'RESOLVED':      DisputeStatus.CHARGE_REFUNDED,
+      'OTHER':         DisputeStatus.NEEDS_RESPONSE,
+    };
+    return map[status] ?? DisputeStatus.NEEDS_RESPONSE;
+  }
+
+  // ──────────────────────────────────────────
+  //  IS DISPUTE EVENT
+  // ──────────────────────────────────────────
+
+  isDisputeEvent(event: WebhookEvent): boolean {
+    return this.detect(event) !== null;
+  }
+
+  // ──────────────────────────────────────────
+  //  IS ACTIONABLE
+  // ──────────────────────────────────────────
+
+  isActionable(dispute: Dispute): boolean {
+    return (
+      dispute.status === DisputeStatus.NEEDS_RESPONSE ||
+      dispute.status === DisputeStatus.WARNING_NEEDS_RESPONSE
+    );
+  }
+
+  // ──────────────────────────────────────────
+  //  IS DEADLINE CLOSE
+  // ──────────────────────────────────────────
+
+  isDeadlineClose(dispute: Dispute, hoursThreshold = 48): boolean {
+    if (!dispute.evidenceDueBy) { return false; }
+    const dueMs = new Date(dispute.evidenceDueBy).getTime();
+    const remaining = dueMs - Date.now();
+    return remaining > 0 && remaining < hoursThreshold * 3600000;
+  }
+
+  getRemainingHours(dispute: Dispute): number | null {
+    if (!dispute.evidenceDueBy) { return null; }
+    const remaining = new Date(dispute.evidenceDueBy).getTime() - Date.now();
+    return Math.max(0, Math.floor(remaining / 3600000));
+  }
+}

package/src/dispute/responseEngine.ts

@@ -0,0 +1,440 @@
+// ============================================================
+//  CHARGEBACK GUARD — Response Engine
+//  Builds the bank submission package for each dispute type
+// ============================================================
+
+import { createLogger } from '../utils/logger';
+import {
+  Dispute,
+  DisputeAnalysis,
+  Evidence,
+  DisputeReply,
+  EvidenceItem,
+  ReplySummary,
+  BankReplyFormat,
+  Attachment,
+  DisputeReason,
+  EvidenceType,
+  ConfidenceLevel,
+} from '../types';
+
+const log = createLogger('ResponseEngine');
+
+// ────────────────────────────────────────────────────────────
+//  RESPONSE ENGINE
+// ────────────────────────────────────────────────────────────
+
+export class ResponseEngine {
+
+  async generateReply(ctx: {
+    dispute: Dispute;
+    evidence: Evidence | null;
+    analysis: DisputeAnalysis;
+  }): Promise<DisputeReply> {
+    const { dispute, evidence, analysis } = ctx;
+    log.debug(`Generating reply for dispute: ${dispute.id}`, { reason: dispute.reason });
+
+    const evidenceItems = this._buildEvidenceItems(dispute, evidence);
+    const summary       = this._buildSummary(evidence, analysis);
+    const caseArgument  = this._buildCaseArgument(dispute, evidence, analysis);
+    const attachments   = this._prepareAttachments(evidenceItems);
+
+    const reply: DisputeReply = {
+      disputeId: dispute.id,
+      orderId:   dispute.orderId,
+      generatedAt: new Date().toISOString(),
+      evidenceItems,
+      summary,
+      caseArgument,
+      attachments,
+      bankFormat: this._formatForBank(dispute, evidenceItems, caseArgument, reply as DisputeReply),
+    };
+
+    log.info(`Reply generated: ${dispute.id}`, {
+      evidenceItems: evidenceItems.length,
+      confidenceLevel: summary.confidenceLevel,
+    });
+
+    return reply;
+  }
+
+  // ──────────────────────────────────────────
+  //  BUILD EVIDENCE ITEMS BY DISPUTE TYPE
+  // ──────────────────────────────────────────
+
+  private _buildEvidenceItems(dispute: Dispute, ev: Evidence | null): EvidenceItem[] {
+    const items: EvidenceItem[] = [];
+
+    // Common items for all dispute types
+    items.push(...this._commonItems(ev));
+
+    // Type-specific items
+    switch (dispute.reason) {
+      case DisputeReason.PRODUCT_NOT_RECEIVED:
+        items.push(...this._deliveryProofItems(ev));
+        break;
+
+      case DisputeReason.UNAUTHORIZED_TRANSACTION:
+      case DisputeReason.FRAUDULENT:
+        items.push(...this._unauthorizedItems(ev));
+        break;
+
+      case DisputeReason.DUPLICATE_TRANSACTION:
+        items.push(...this._duplicateItems(ev));
+        break;
+
+      case DisputeReason.PRODUCT_UNACCEPTABLE:
+        items.push(...this._productQualityItems(ev));
+        break;
+
+      case DisputeReason.CREDIT_NOT_PROCESSED:
+        items.push(...this._creditItems(ev));
+        break;
+
+      case DisputeReason.SUBSCRIPTION_CANCELLED:
+        items.push(...this._subscriptionItems(ev));
+        break;
+
+      default:
+        items.push(...this._generalItems(ev));
+        break;
+    }
+
+    // Sort by weight descending
+    return items.sort((a, b) => (b.weight ?? 0) - (a.weight ?? 0));
+  }
+
+  // ──────────────────────────────────────────
+  //  COMMON ITEMS (always included)
+  // ──────────────────────────────────────────
+
+  private _commonItems(ev: Evidence | null): EvidenceItem[] {
+    const items: EvidenceItem[] = [];
+
+    if (!ev) { return items; }
+
+    // Transaction log
+    items.push({
+      type: EvidenceType.TRANSACTION_LOG,
+      description: 'Detailed transaction record showing the charge is legitimate',
+      weight: 0.5,
+      data: {
+        orderId:       ev.orderId,
+        amount:        ev.data?.transactionData?.amount,
+        currency:      ev.data?.transactionData?.currency,
+        paymentMethod: ev.data?.transactionData?.paymentMethod,
+        cardLastFour:  ev.data?.transactionData?.cardLastFour,
+        timestamp:     ev.data?.transactionData?.timestamp,
+        transactionId: ev.data?.transactionData?.transactionId,
+      },
+    });
+
+    // Customer communication (email)
+    const emailConf = ev.data?.emailConfirmation;
+    if (emailConf?.sentTo) {
+      items.push({
+        type: EvidenceType.EMAIL_CONFIRMATION,
+        description: 'Email order confirmation was sent to customer email',
+        weight: 0.4,
+        data: {
+          sentTo:       emailConf.sentTo,
+          sentAt:       emailConf.sentAt,
+          opened:       emailConf.opened,
+          openedAt:     emailConf.openedAt,
+          clickedLinks: emailConf.clickedLinks,
+        },
+      });
+    }
+
+    return items;
+  }
+
+  // ──────────────────────────────────────────
+  //  DELIVERY PROOF ITEMS
+  // ──────────────────────────────────────────
+
+  private _deliveryProofItems(ev: Evidence | null): EvidenceItem[] {
+    const items: EvidenceItem[] = [];
+    const shipping = ev?.data?.shippingData;
+
+    items.push({
+      type: EvidenceType.DELIVERY_PROOF,
+      description: 'Shipping documentation and delivery confirmation',
+      weight: 0.95,
+      data: {
+        trackingNumber:  shipping?.trackingNumber ?? 'Not available',
+        carrier:         (shipping as Record<string, unknown>)?.['carrier'] ?? 'N/A',
+        shippedAt:       (shipping as Record<string, unknown>)?.['shippingDate'],
+        deliveredAt:     shipping?.deliveryDate,
+        signature:       shipping?.signature ?? false,
+        gpsCoordinates:  shipping?.gpsCoordinates,
+        shippingAddress: shipping?.address,
+      },
+    });
+
+    return items;
+  }
+
+  // ──────────────────────────────────────────
+  //  UNAUTHORIZED ITEMS
+  // ──────────────────────────────────────────
+
+  private _unauthorizedItems(ev: Evidence | null): EvidenceItem[] {
+    const items: EvidenceItem[] = [];
+
+    // Device fingerprint
+    items.push({
+      type: EvidenceType.DEVICE_FINGERPRINT,
+      description: 'Device fingerprint and IP consistency proving authorized access',
+      weight: 0.90,
+      data: {
+        ipAddress:        ev?.data?.customerData?.ipAddress,
+        userAgent:        ev?.data?.customerData?.userAgent,
+        deviceId:         ev?.data?.customerData?.deviceId,
+        fingerprint:      ev?.data?.deviceFingerprint?.fingerprint,
+        screenResolution: ev?.data?.deviceFingerprint?.screenResolution,
+        timezone:         ev?.data?.deviceFingerprint?.timezone,
+        language:         ev?.data?.deviceFingerprint?.language,
+      },
+    });
+
+    // Behavior analysis
+    const interaction = ev?.data?.interactionData;
+    items.push({
+      type: EvidenceType.BEHAVIOR_ANALYSIS,
+      description: 'User behavior analysis showing natural browsing and checkout patterns',
+      weight: 0.80,
+      data: {
+        sessionDuration:  interaction?.sessionDuration,
+        pageViews:        interaction?.pageViews?.length,
+        timeOnCheckout:   interaction?.timeOnCheckout,
+        formInteractions: interaction?.formInteractions?.length,
+        scrollDepth:      interaction?.scrollDepth,
+      },
+    });
+
+    // Customer history
+    const history = ev?.data?.customerHistory;
+    items.push({
+      type: EvidenceType.CUSTOMER_HISTORY,
+      description: 'Customer account history and reputation score',
+      weight: 0.75,
+      data: {
+        accountCreatedAt:  history?.accountCreatedAt,
+        accountAgeDays:    history?.accountAge,
+        previousPurchases: history?.previousPurchases,
+        previousDisputes:  history?.previousDisputes,
+        riskScore:         history?.riskScore,
+        trustScore:        history?.trustScore,
+      },
+    });
+
+    // Geolocation
+    const geo = ev?.data?.geolocation;
+    if (geo) {
+      items.push({
+        type: EvidenceType.GEOLOCATION,
+        description: 'IP geolocation matches customer registered location',
+        weight: 0.65,
+        data: {
+          ip:       geo.ip,
+          country:  geo.country,
+          city:     geo.city,
+          timezone: geo.timezone,
+          isp:      geo.isp,
+        },
+      });
+    }
+
+    return items;
+  }
+
+  // ──────────────────────────────────────────
+  //  DUPLICATE ITEMS
+  // ──────────────────────────────────────────
+
+  private _duplicateItems(ev: Evidence | null): EvidenceItem[] {
+    return [{
+      type: EvidenceType.PAYMENT_LOG,
+      description: 'Payment log proving this was a single unique transaction',
+      weight: 0.95,
+      data: {
+        attempts:    ev?.data?.paymentLog?.attempts,
+        successful:  ev?.data?.paymentLog?.successful,
+        failed:      ev?.data?.paymentLog?.failed,
+        lastAttempt: ev?.data?.paymentLog?.lastAttemptAt,
+        conclusion:  'Only one successful charge was made for this order',
+      },
+    }];
+  }
+
+  // ──────────────────────────────────────────
+  //  PRODUCT QUALITY ITEMS
+  // ──────────────────────────────────────────
+
+  private _productQualityItems(ev: Evidence | null): EvidenceItem[] {
+    return [{
+      type: 'product_description',
+      description: 'Product description and specifications at time of purchase',
+      weight: 0.80,
+      data: {
+        orderId: ev?.orderId,
+        note: 'Product was delivered as described per order confirmation',
+      },
+    }];
+  }
+
+  // ──────────────────────────────────────────
+  //  CREDIT NOT PROCESSED ITEMS
+  // ──────────────────────────────────────────
+
+  private _creditItems(ev: Evidence | null): EvidenceItem[] {
+    return [{
+      type: 'refund_policy',
+      description: 'Merchant refund policy and credit processing timeline',
+      weight: 0.85,
+      data: {
+        policy: 'Refund policy was clearly disclosed at time of purchase',
+        note: 'If a refund was agreed, see attached credit documentation',
+        orderId: ev?.orderId,
+      },
+    }];
+  }
+
+  // ──────────────────────────────────────────
+  //  SUBSCRIPTION ITEMS
+  // ──────────────────────────────────────────
+
+  private _subscriptionItems(ev: Evidence | null): EvidenceItem[] {
+    return [{
+      type: 'subscription_terms',
+      description: 'Subscription terms and cancellation policy accepted by customer',
+      weight: 0.85,
+      data: {
+        note: 'Customer agreed to subscription terms during signup',
+        cancellationPolicy: 'Cancel anytime — no active cancellation request was received',
+        orderId: ev?.orderId,
+      },
+    }];
+  }
+
+  // ──────────────────────────────────────────
+  //  GENERAL ITEMS
+  // ──────────────────────────────────────────
+
+  private _generalItems(ev: Evidence | null): EvidenceItem[] {
+    return [{
+      type: 'general_rebuttal',
+      description: 'General rebuttal with all available supporting evidence',
+      weight: 0.60,
+      data: {
+        note: 'All available evidence has been submitted. The charge is valid and service/product was delivered.',
+        orderId: ev?.orderId,
+        trustScore: ev?.trustScore,
+      },
+    }];
+  }
+
+  // ──────────────────────────────────────────
+  //  SUMMARY
+  // ──────────────────────────────────────────
+
+  private _buildSummary(ev: Evidence | null, analysis: DisputeAnalysis): ReplySummary {
+    const confidenceLevel = this._scoreToConfidence(analysis.confidenceScore);
+
+    return {
+      trustScore: ev?.trustScore ?? 0,
+      confidenceLevel,
+      recommendation: 'APPROVE_CUSTOMER_CHARGE',
+      keyPoints: analysis.analysisReasons,
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  CASE ARGUMENT
+  // ──────────────────────────────────────────
+
+  private _buildCaseArgument(
+    dispute: Dispute,
+    ev: Evidence | null,
+    analysis: DisputeAnalysis
+  ): string {
+    const lines = [
+      '─────────────────────────────────────────────────',
+      'MERCHANT REBUTTAL — CHARGEBACK DEFENSE SUBMISSION',
+      '─────────────────────────────────────────────────',
+      '',
+      `Dispute ID   : ${dispute.id}`,
+      `Order ID     : ${dispute.orderId ?? 'N/A'}`,
+      `Dispute Type : ${dispute.reason}`,
+      `Amount       : ${(dispute.amount / 100).toFixed(2)} ${(dispute.currency ?? 'USD').toUpperCase()}`,
+      `Generated At : ${new Date().toISOString()}`,
+      '',
+      'EXECUTIVE SUMMARY',
+      '─────────────────',
+      'This chargeback is invalid. The attached evidence conclusively demonstrates',
+      'that the transaction was authorized by the cardholder and the order was',
+      'fulfilled per the original purchase agreement.',
+      '',
+    ];
+
+    analysis.analysisReasons.forEach((reason, i) => {
+      lines.push(`${i + 1}. ${reason}`);
+    });
+
+    lines.push('');
+    lines.push(`Evidence Confidence Score : ${(analysis.confidenceScore * 100).toFixed(1)}%`);
+    lines.push(`Fraud Probability         : ${(analysis.fraudProbability * 100).toFixed(1)}%`);
+    lines.push('');
+    lines.push('Based on all submitted evidence, we respectfully request that this');
+    lines.push('chargeback be ruled in favor of the merchant.');
+    lines.push('');
+    lines.push('─── GENERATED BY CHARGEBACKGUARD v2.0 ───');
+
+    return lines.join('\n');
+  }
+
+  // ──────────────────────────────────────────
+  //  ATTACHMENTS
+  // ──────────────────────────────────────────
+
+  private _prepareAttachments(items: EvidenceItem[]): Attachment[] {
+    return items.map((item, i) => ({
+      type: item.type as string,
+      name: `evidence_${String(i + 1).padStart(2, '0')}_${item.type}.pdf`,
+      mimeType: 'application/pdf',
+      description: item.description,
+    }));
+  }
+
+  // ──────────────────────────────────────────
+  //  BANK FORMAT
+  // ──────────────────────────────────────────
+
+  private _formatForBank(
+    dispute: Dispute,
+    evidenceItems: EvidenceItem[],
+    caseArgument: string,
+    reply: DisputeReply
+  ): BankReplyFormat {
+    return {
+      dispute_id:         dispute.id,
+      merchant_reference: dispute.orderId ?? '',
+      submitted_at:       new Date().toISOString(),
+      evidence_items:     evidenceItems,
+      case_argument:      caseArgument,
+      attachment_files:   reply.attachments,
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  HELPERS
+  // ──────────────────────────────────────────
+
+  private _scoreToConfidence(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;
+  }
+}