chargeback-guard 2.0.0

package/src/integrations/stripe.ts

@@ -0,0 +1,280 @@
+// ============================================================
+//  CHARGEBACK GUARD — Stripe Integration (Full)
+// ============================================================
+
+import Stripe from 'stripe';
+import { createLogger } from '../utils/logger';
+import { stripeConfig } from '../config';
+import {
+  Dispute,
+  DisputeReply,
+  DisputeStatus,
+  DisputeReason,
+  PaymentProvider,
+} from '../types';
+
+const log = createLogger('StripeIntegration');
+
+// ────────────────────────────────────────────────────────────
+//  DISPUTE STATUS / REASON MAPS
+// ────────────────────────────────────────────────────────────
+
+const 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,
+};
+
+const 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,
+};
+
+// ────────────────────────────────────────────────────────────
+//  STRIPE INTEGRATION CLASS
+// ────────────────────────────────────────────────────────────
+
+export class StripeIntegration {
+  private readonly client: Stripe;
+
+  constructor(apiKey?: string) {
+    const key = apiKey ?? stripeConfig.secretKey;
+    if (!key) {
+      throw new Error('Stripe API key is required');
+    }
+    this.client = new Stripe(key, {
+      apiVersion: '2023-10-16' as Stripe.LatestApiVersion,
+      typescript: true,
+      maxNetworkRetries: 3,
+    });
+    log.debug('Stripe client initialized');
+  }
+
+  // ──────────────────────────────────────────
+  //  WEBHOOK VERIFICATION
+  // ──────────────────────────────────────────
+
+  verifyWebhookSignature(payload: string | Buffer, signature: string): Stripe.Event {
+    return this.client.webhooks.constructEvent(
+      payload,
+      signature,
+      stripeConfig.webhookSecret
+    );
+  }
+
+  // ──────────────────────────────────────────
+  //  GET DISPUTE
+  // ──────────────────────────────────────────
+
+  async getDispute(disputeId: string): Promise<Dispute> {
+    log.debug(`Fetching dispute: ${disputeId}`);
+    const d = await this.client.disputes.retrieve(disputeId);
+
+    return {
+      id: d.id,
+      orderId: (d.metadata as Record<string, string>)['order_id']
+            ?? (d.metadata as Record<string, string>)['orderId']
+            ?? undefined,
+      amount: d.amount,
+      currency: d.currency,
+      reason: REASON_MAP[d.reason] ?? DisputeReason.GENERAL,
+      status: STATUS_MAP[d.status] ?? DisputeStatus.NEEDS_RESPONSE,
+      provider: PaymentProvider.STRIPE,
+      evidenceDueBy: d.evidence_due_by
+        ? new Date(d.evidence_due_by * 1000).toISOString()
+        : undefined,
+      createdAt: new Date(d.created * 1000).toISOString(),
+      metadata: d.metadata as Record<string, unknown>,
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  LIST DISPUTES
+  // ──────────────────────────────────────────
+
+  async listDisputes(params?: {
+    status?: string;
+    limit?: number;
+    startingAfter?: string;
+  }): Promise<Dispute[]> {
+    const list = await this.client.disputes.list({
+      limit: params?.limit ?? 100,
+      starting_after: params?.startingAfter,
+    });
+
+    return list.data.map(d => ({
+      id: d.id,
+      orderId: (d.metadata as Record<string, string>)['order_id'] ?? undefined,
+      amount: d.amount,
+      currency: d.currency,
+      reason: REASON_MAP[d.reason] ?? DisputeReason.GENERAL,
+      status: STATUS_MAP[d.status] ?? DisputeStatus.NEEDS_RESPONSE,
+      provider: PaymentProvider.STRIPE,
+      evidenceDueBy: d.evidence_due_by
+        ? new Date(d.evidence_due_by * 1000).toISOString()
+        : undefined,
+      createdAt: new Date(d.created * 1000).toISOString(),
+      metadata: d.metadata as Record<string, unknown>,
+    }));
+  }
+
+  // ──────────────────────────────────────────
+  //  LIST ACTIONABLE DISPUTES
+  // ──────────────────────────────────────────
+
+  async listActionableDisputes(): Promise<Dispute[]> {
+    const [needs, warning] = await Promise.all([
+      this.listDisputes({ status: 'needs_response', limit: 100 }),
+      this.listDisputes({ status: 'warning_needs_response', limit: 100 }),
+    ]);
+    return [...needs, ...warning];
+  }
+
+  // ──────────────────────────────────────────
+  //  SUBMIT EVIDENCE
+  // ──────────────────────────────────────────
+
+  async submitDisputeEvidence(disputeId: string, reply: DisputeReply): Promise<Stripe.Dispute> {
+    log.info(`Submitting evidence for dispute: ${disputeId}`);
+
+    const evidencePayload = this._buildEvidencePayload(reply);
+
+    const result = await this.client.disputes.update(disputeId, {
+      evidence: evidencePayload,
+      submit: true,
+    });
+
+    log.info(`Evidence submitted for dispute: ${disputeId}`, { status: result.status });
+    return result;
+  }
+
+  // ──────────────────────────────────────────
+  //  UPDATE DISPUTE METADATA
+  // ──────────────────────────────────────────
+
+  async updateDisputeMetadata(
+    disputeId: string,
+    metadata: Record<string, string>
+  ): Promise<void> {
+    await this.client.disputes.update(disputeId, { metadata });
+  }
+
+  // ──────────────────────────────────────────
+  //  GET DISPUTE STATS
+  // ──────────────────────────────────────────
+
+  async getDisputeStats(): Promise<{
+    total: number;
+    byStatus: Record<string, number>;
+    byReason: Record<string, number>;
+    totalAmount: number;
+  }> {
+    const all = await this.client.disputes.list({ limit: 100 });
+
+    const stats = {
+      total: 0,
+      byStatus: {} as Record<string, number>,
+      byReason: {} as Record<string, number>,
+      totalAmount: 0,
+    };
+
+    for (const d of all.data) {
+      stats.total++;
+      stats.totalAmount += d.amount;
+      stats.byStatus[d.status] = (stats.byStatus[d.status] ?? 0) + 1;
+      stats.byReason[d.reason] = (stats.byReason[d.reason] ?? 0) + 1;
+    }
+
+    return stats;
+  }
+
+  // ──────────────────────────────────────────
+  //  RETRIEVE CHARGE
+  // ──────────────────────────────────────────
+
+  async getCharge(chargeId: string): Promise<Stripe.Charge> {
+    return this.client.charges.retrieve(chargeId);
+  }
+
+  // ──────────────────────────────────────────
+  //  RETRIEVE PAYMENT INTENT
+  // ──────────────────────────────────────────
+
+  async getPaymentIntent(piId: string): Promise<Stripe.PaymentIntent> {
+    return this.client.paymentIntents.retrieve(piId, {
+      expand: ['payment_method', 'latest_charge'],
+    });
+  }
+
+  // ──────────────────────────────────────────
+  //  EVIDENCE PAYLOAD BUILDER
+  // ──────────────────────────────────────────
+
+  private _buildEvidencePayload(reply: DisputeReply): Stripe.DisputeUpdateParams.Evidence {
+    const payload: Stripe.DisputeUpdateParams.Evidence = {
+      uncategorized_text: reply.caseArgument,
+    };
+
+    for (const item of reply.evidenceItems) {
+      const d = item.data;
+      switch (item.type) {
+        case 'delivery_proof':
+          if (d['trackingNumber']) {
+            payload.shipping_tracking_number = String(d['trackingNumber']);
+          }
+          if (d['shippingAddress']) {
+            payload.shipping_address = JSON.stringify(d['shippingAddress']);
+          }
+          if (d['shippedAt']) {
+            payload.shipping_date = String(d['shippedAt']);
+          }
+          payload.shipping_documentation = JSON.stringify(d);
+          break;
+
+        case 'device_fingerprint':
+        case 'behavior_analysis':
+          payload.access_activity_log = JSON.stringify(d);
+          break;
+
+        case 'customer_communication':
+        case 'email_confirmation':
+          if (d['sentTo']) {
+            payload.customer_email_address = String(d['sentTo']);
+          }
+          payload.customer_communication = JSON.stringify(d);
+          break;
+
+        case 'customer_history':
+          payload.customer_name = String(d['customerId'] ?? '');
+          break;
+
+        case 'payment_log':
+          payload.duplicate_charge_explanation = JSON.stringify(d);
+          break;
+
+        case 'refund_policy':
+          payload.refund_policy = String(d['policy'] ?? '');
+          payload.refund_policy_disclosure = String(d['note'] ?? '');
+          break;
+
+        case 'subscription_terms':
+          payload.cancellation_policy = String(d['cancellationPolicy'] ?? '');
+          payload.cancellation_policy_disclosure = String(d['note'] ?? '');
+          break;
+      }
+    }
+
+    return payload;
+  }
+}

package/src/integrations/webhook.ts

@@ -0,0 +1,332 @@
+// ============================================================
+//  CHARGEBACK GUARD — Webhook Handler (Stripe + PayPal)
+// ============================================================
+
+import { Request, Response } from 'express';
+import { createLogger } from '../utils/logger';
+import { stripeConfig, paypalConfig } from '../config';
+import {
+  WebhookEvent,
+  ProcessedWebhookResult,
+  PaymentProvider,
+  Dispute,
+  DisputeStatus,
+  NotificationEvent,
+} from '../types';
+import { verifySignature } from '../evidence/encryption';
+
+const log = createLogger('WebhookHandler');
+
+// ────────────────────────────────────────────────────────────
+//  EVENT PROCESSING CALLBACK TYPE
+// ────────────────────────────────────────────────────────────
+
+export type DisputeCallback = (dispute: Dispute) => Promise<void>;
+export type DisputeResolvedCallback = (
+  disputeId: string,
+  status: DisputeStatus,
+  provider: PaymentProvider
+) => Promise<void>;
+
+// ────────────────────────────────────────────────────────────
+//  WEBHOOK HANDLER
+// ────────────────────────────────────────────────────────────
+
+export class WebhookHandler {
+  private disputeCallbacks: DisputeCallback[] = [];
+  private resolvedCallbacks: DisputeResolvedCallback[] = [];
+  private processedEventIds = new Set<string>();
+
+  // ──────────────────────────────────────────
+  //  CALLBACK REGISTRATION
+  // ──────────────────────────────────────────
+
+  onDisputeDetected(cb: DisputeCallback): void {
+    this.disputeCallbacks.push(cb);
+  }
+
+  onDisputeResolved(cb: DisputeResolvedCallback): void {
+    this.resolvedCallbacks.push(cb);
+  }
+
+  // ──────────────────────────────────────────
+  //  STRIPE WEBHOOK HANDLER (Express middleware)
+  // ──────────────────────────────────────────
+
+  handleStripe(): (req: Request, res: Response) => Promise<void> {
+    return async (req: Request, res: Response) => {
+      const signature = req.headers['stripe-signature'] as string;
+      const rawBody   = (req as Request & { rawBody?: Buffer }).rawBody ?? req.body;
+
+      if (!signature) {
+        res.status(400).json({ error: 'Missing stripe-signature header' });
+        return;
+      }
+
+      let event: import('stripe').Stripe.Event;
+      try {
+        const { StripeIntegration } = await import('./stripe');
+        const stripe = new StripeIntegration();
+        event = stripe.verifyWebhookSignature(rawBody, signature);
+      } catch (err) {
+        log.warn('Stripe webhook signature verification failed', {
+          error: err instanceof Error ? err.message : String(err),
+        });
+        res.status(400).json({ error: 'Invalid signature' });
+        return;
+      }
+
+      // Idempotency check
+      if (this.processedEventIds.has(event.id)) {
+        log.debug(`Duplicate event ignored: ${event.id}`);
+        res.status(200).json({ received: true, duplicate: true });
+        return;
+      }
+      this.processedEventIds.add(event.id);
+      if (this.processedEventIds.size > 10000) {
+        // Keep memory bounded
+        const oldest = this.processedEventIds.values().next().value;
+        if (oldest) { this.processedEventIds.delete(oldest); }
+      }
+
+      const result = await this._processStripeEvent(event);
+      res.status(200).json(result);
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  PAYPAL WEBHOOK HANDLER
+  // ──────────────────────────────────────────
+
+  handlePayPal(): (req: Request, res: Response) => Promise<void> {
+    return async (req: Request, res: Response) => {
+      const body = typeof req.body === 'string' ? req.body : JSON.stringify(req.body);
+
+      // Verify PayPal signature
+      try {
+        const { PayPalIntegration } = await import('./paypal');
+        const paypal = new PayPalIntegration();
+        const valid = await paypal.verifyWebhookSignature(
+          req.headers as Record<string, string>,
+          body
+        );
+        if (!valid) {
+          res.status(400).json({ error: 'Invalid PayPal signature' });
+          return;
+        }
+      } catch (err) {
+        log.warn('PayPal webhook verification failed', {
+          error: err instanceof Error ? err.message : String(err),
+        });
+        // Allow in development
+        if (process.env.NODE_ENV === 'production') {
+          res.status(400).json({ error: 'Signature verification failed' });
+          return;
+        }
+      }
+
+      const result = await this._processPayPalEvent(req.body as Record<string, unknown>);
+      res.status(200).json(result);
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  PROCESS STRIPE EVENT
+  // ──────────────────────────────────────────
+
+  private async _processStripeEvent(
+    event: import('stripe').Stripe.Event
+  ): Promise<ProcessedWebhookResult> {
+    log.info(`Processing Stripe event: ${event.type} (${event.id})`);
+
+    const obj = event.data.object as Record<string, unknown>;
+
+    switch (event.type) {
+      case 'charge.dispute.created': {
+        const dispute = this._parseStripeDispute(obj, DisputeStatus.NEEDS_RESPONSE);
+        await this._fireDisputeCallbacks(dispute);
+        return this._result(event.id, event.type, 'dispute_detected');
+      }
+
+      case 'charge.dispute.updated': {
+        const dispute = this._parseStripeDispute(obj);
+        await this._fireDisputeCallbacks(dispute);
+        return this._result(event.id, event.type, 'dispute_updated');
+      }
+
+      case 'charge.dispute.closed': {
+        const disputeId = obj['id'] as string;
+        const status    = obj['status'] as string;
+        const resolved  = this._mapStripeStatus(status);
+        await this._fireResolvedCallbacks(disputeId, resolved, PaymentProvider.STRIPE);
+
+        if (resolved === DisputeStatus.WON) {
+          log.info(`🏆 Dispute WON: ${disputeId}`);
+        } else if (resolved === DisputeStatus.LOST) {
+          log.warn(`❌ Dispute LOST: ${disputeId}`);
+        }
+
+        return this._result(event.id, event.type, `dispute_${status}`);
+      }
+
+      case 'charge.dispute.funds_withdrawn':
+        log.warn(`💸 Funds withdrawn for dispute: ${obj['id']}`);
+        return this._result(event.id, event.type, 'funds_withdrawn');
+
+      case 'charge.dispute.funds_reinstated':
+        log.info(`💰 Funds reinstated for dispute: ${obj['id']}`);
+        return this._result(event.id, event.type, 'funds_reinstated');
+
+      default:
+        log.debug(`Unhandled Stripe event: ${event.type}`);
+        return this._result(event.id, event.type, 'unhandled');
+    }
+  }
+
+  // ──────────────────────────────────────────
+  //  PROCESS PAYPAL EVENT
+  // ──────────────────────────────────────────
+
+  private async _processPayPalEvent(
+    body: Record<string, unknown>
+  ): Promise<ProcessedWebhookResult> {
+    const eventType = String(body['event_type'] ?? '');
+    const eventId   = String(body['id'] ?? Date.now());
+    const resource  = (body['resource'] as Record<string, unknown>) ?? {};
+
+    log.info(`Processing PayPal event: ${eventType} (${eventId})`);
+
+    switch (eventType) {
+      case 'CUSTOMER.DISPUTE.CREATED': {
+        const dispute = this._parsePayPalDispute(resource, DisputeStatus.NEEDS_RESPONSE);
+        await this._fireDisputeCallbacks(dispute);
+        return this._result(eventId, eventType, 'dispute_detected');
+      }
+
+      case 'CUSTOMER.DISPUTE.UPDATED': {
+        const dispute = this._parsePayPalDispute(resource);
+        await this._fireDisputeCallbacks(dispute);
+        return this._result(eventId, eventType, 'dispute_updated');
+      }
+
+      case 'CUSTOMER.DISPUTE.RESOLVED': {
+        const disputeId = String(resource['dispute_id'] ?? '');
+        const status    = String(resource['status'] ?? 'RESOLVED');
+        await this._fireResolvedCallbacks(
+          disputeId,
+          DisputeStatus.CHARGE_REFUNDED,
+          PaymentProvider.PAYPAL
+        );
+        return this._result(eventId, eventType, `dispute_${status.toLowerCase()}`);
+      }
+
+      default:
+        return this._result(eventId, eventType, 'unhandled');
+    }
+  }
+
+  // ──────────────────────────────────────────
+  //  FIRE CALLBACKS
+  // ──────────────────────────────────────────
+
+  private async _fireDisputeCallbacks(dispute: Dispute): Promise<void> {
+    for (const cb of this.disputeCallbacks) {
+      try { await cb(dispute); }
+      catch (err) {
+        log.error('Dispute callback error', {
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  }
+
+  private async _fireResolvedCallbacks(
+    disputeId: string,
+    status: DisputeStatus,
+    provider: PaymentProvider
+  ): Promise<void> {
+    for (const cb of this.resolvedCallbacks) {
+      try { await cb(disputeId, status, provider); }
+      catch (err) {
+        log.error('Resolved callback error', {
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  }
+
+  // ──────────────────────────────────────────
+  //  PARSERS
+  // ──────────────────────────────────────────
+
+  private _parseStripeDispute(
+    obj: Record<string, unknown>,
+    forceStatus?: DisputeStatus
+  ): Dispute {
+    return {
+      id: String(obj['id'] ?? ''),
+      orderId: ((obj['metadata'] as Record<string, string>)?.['order_id']) ?? undefined,
+      amount: Number(obj['amount'] ?? 0),
+      currency: String(obj['currency'] ?? 'usd'),
+      reason: String(obj['reason'] ?? 'general') as Dispute['reason'],
+      status: forceStatus ?? this._mapStripeStatus(String(obj['status'] ?? 'needs_response')),
+      provider: PaymentProvider.STRIPE,
+      evidenceDueBy: obj['evidence_due_by']
+        ? new Date(Number(obj['evidence_due_by']) * 1000).toISOString()
+        : undefined,
+      createdAt: new Date(Number(obj['created'] ?? Date.now() / 1000) * 1000).toISOString(),
+      metadata: (obj['metadata'] as Record<string, unknown>) ?? {},
+    };
+  }
+
+  private _parsePayPalDispute(
+    resource: Record<string, unknown>,
+    forceStatus?: DisputeStatus
+  ): Dispute {
+    const amt = (resource['dispute_amount'] as Record<string, string> | undefined);
+    return {
+      id: String(resource['dispute_id'] ?? ''),
+      amount: Math.round(parseFloat(amt?.['value'] ?? '0') * 100),
+      currency: amt?.['currency_code'] ?? 'USD',
+      reason: String(resource['reason'] ?? 'OTHER') as Dispute['reason'],
+      status: forceStatus ?? DisputeStatus.NEEDS_RESPONSE,
+      provider: PaymentProvider.PAYPAL,
+      createdAt: String(resource['create_time'] ?? new Date().toISOString()),
+      metadata: { raw: resource },
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  HELPERS
+  // ──────────────────────────────────────────
+
+  private _mapStripeStatus(status: string): DisputeStatus {
+    const 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,
+    };
+    return map[status] ?? DisputeStatus.NEEDS_RESPONSE;
+  }
+
+  private _result(
+    eventId: string,
+    type: string,
+    action: string
+  ): ProcessedWebhookResult {
+    return {
+      eventId,
+      type,
+      processed: true,
+      action,
+      processedAt: new Date().toISOString(),
+    };
+  }
+}
+
+export const webhookHandler = new WebhookHandler();