Merge pull request #94 from AdaBliss/feat/indexer-disputes

feat(indexer): sync dispute_opened and dispute_resolved on-chain events

Author: Tybravo

src/config/env.ts

@@ -14,15 +14,7 @@ interface EnvConfig {
   CORS_ORIGIN: string;
   RATE_LIMIT_WINDOW_MS: number;
   RATE_LIMIT_MAX_REQUESTS: number;
-  APP_BASE_URL: string;
-  UPLOAD_STORAGE_DRIVER: 'local' | 's3';
-  UPLOAD_LOCAL_DIR: string;
-  UPLOAD_MAX_FILE_SIZE_MB: number;
-  AWS_REGION: string;
-  AWS_ACCESS_KEY_ID: string;
-  AWS_SECRET_ACCESS_KEY: string;
-  AWS_S3_BUCKET: string;
-  AWS_S3_SIGNED_URL_EXPIRES_SECONDS: number;
+  DISPUTE_NOTIFICATION_WEBHOOK_URL: string;
 }
 
 const envSchema = z.object({
@@ -36,15 +28,7 @@ const envSchema = z.object({
   CORS_ORIGIN: z.string().default('*'),
   RATE_LIMIT_WINDOW_MS: z.coerce.number().int().min(1000).default(900000),
   RATE_LIMIT_MAX_REQUESTS: z.coerce.number().int().min(1).default(100),
-  APP_BASE_URL: z.string().default('http://localhost:3000'),
-  UPLOAD_STORAGE_DRIVER: z.enum(['local', 's3']).default('local'),
-  UPLOAD_LOCAL_DIR: z.string().default('uploads'),
-  UPLOAD_MAX_FILE_SIZE_MB: z.coerce.number().int().min(1).max(100).default(10),
-  AWS_REGION: z.string().default('us-east-1'),
-  AWS_ACCESS_KEY_ID: z.string().default(''),
-  AWS_SECRET_ACCESS_KEY: z.string().default(''),
-  AWS_S3_BUCKET: z.string().default(''),
-  AWS_S3_SIGNED_URL_EXPIRES_SECONDS: z.coerce.number().int().min(60).default(3600),
+  DISPUTE_NOTIFICATION_WEBHOOK_URL: z.string().default(''),
 });
 
 let env: EnvConfig;

src/indexer/disputeHandlers.ts

@@ -0,0 +1,104 @@
+import logger from '../config/logger';
+import { disputeService } from '../services/disputeService';
+
+/**
+ * Parsed representation of a `dispute_opened` event emitted by the
+ * SwiftChain Soroban contract.
+ * Contract topics: [event_type, dispute_id, delivery_id]
+ * Contract data:   { opened_by: address, reason?: string }
+ */
+export interface DisputeOpenedEvent {
+  disputeId: string;
+  deliveryId: string;
+  openedBy: string;
+  reason?: string;
+  ledgerSequence: number;
+}
+
+/**
+ * Parsed representation of a `dispute_resolved` event emitted by the
+ * SwiftChain Soroban contract.
+ * Contract topics: [event_type, dispute_id]
+ * Contract data:   { resolution?: string }
+ */
+export interface DisputeResolvedEvent {
+  disputeId: string;
+  resolution?: string;
+  ledgerSequence: number;
+}
+
+/**
+ * Handle a `dispute_opened` event: creates the local Dispute record and
+ * fires a notification so support staff can act on it.
+ */
+export async function handleDisputeOpened(event: DisputeOpenedEvent): Promise<void> {
+  if (!event.disputeId || !event.deliveryId || !event.openedBy) {
+    logger.warn('[disputeHandlers] dispute_opened: invalid event payload', { event });
+    return;
+  }
+
+  try {
+    await disputeService.openDispute({
+      disputeId: event.disputeId,
+      deliveryId: event.deliveryId,
+      openedBy: event.openedBy,
+      reason: event.reason,
+      ledgerSequence: event.ledgerSequence,
+    });
+  } catch (err) {
+    logger.error('[disputeHandlers] dispute_opened: failed to persist dispute', {
+      disputeId: event.disputeId,
+      ledgerSequence: event.ledgerSequence,
+      error: err,
+    });
+    throw err;
+  }
+}
+
+/**
+ * Handle a `dispute_resolved` event: updates the local Dispute status and
+ * fires a notification. A resolution for an unknown dispute is treated as a
+ * data-ordering anomaly (logged, not thrown) rather than an error, since
+ * the indexer may observe events out of strict ledger order.
+ */
+export async function handleDisputeResolved(event: DisputeResolvedEvent): Promise<void> {
+  if (!event.disputeId) {
+    logger.warn('[disputeHandlers] dispute_resolved: invalid event payload', { event });
+    return;
+  }
+
+  try {
+    await disputeService.resolveDispute({
+      disputeId: event.disputeId,
+      resolution: event.resolution,
+      ledgerSequence: event.ledgerSequence,
+    });
+  } catch (err) {
+    logger.error('[disputeHandlers] dispute_resolved: failed to update dispute', {
+      disputeId: event.disputeId,
+      ledgerSequence: event.ledgerSequence,
+      error: err,
+    });
+    throw err;
+  }
+}
+
+/**
+ * Route an incoming dispute event by its type string to the correct
+ * handler. Unknown event types are logged and ignored.
+ */
+export async function dispatchDisputeEvent(
+  eventType: string,
+  event: DisputeOpenedEvent | DisputeResolvedEvent,
+): Promise<void> {
+  switch (eventType) {
+    case 'dispute_opened':
+      await handleDisputeOpened(event as DisputeOpenedEvent);
+      break;
+    case 'dispute_resolved':
+      await handleDisputeResolved(event as DisputeResolvedEvent);
+      break;
+    default:
+      logger.warn('[disputeHandlers] unknown event type, ignoring', { eventType });
+  }
+}

tests/disputeHandlers.test.ts

@@ -0,0 +1,222 @@
+/**
+ * Unit/integration tests for disputeService + disputeHandlers.
+ *
+ * Uses an in-memory MongoDB for persistence (project convention). The
+ * outbound notification webhook is mocked via axios.
+ */
+
+import mongoose from 'mongoose';
+import { MongoMemoryServer } from 'mongodb-memory-server';
+import axios from 'axios';
+
+jest.mock('../src/config/logger', () => ({
+  info: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+  debug: jest.fn(),
+}));
+
+jest.mock('axios');
+
+import { Dispute, DisputeStatus } from '../src/models/Dispute';
+import { disputeService } from '../src/services/disputeService';
+import {
+  handleDisputeOpened,
+  handleDisputeResolved,
+  dispatchDisputeEvent,
+} from '../src/indexer/disputeHandlers';
+import env from '../src/config/env';
+
+const mockedAxiosPost = axios.post as jest.Mock;
+
+let mongoServer: MongoMemoryServer;
+const SETUP_TIMEOUT = 120_000;
+
+beforeAll(async () => {
+  mongoServer = await MongoMemoryServer.create();
+  await mongoose.connect(mongoServer.getUri());
+}, SETUP_TIMEOUT);
+
+afterEach(async () => {
+  jest.clearAllMocks();
+  const collections = mongoose.connection.collections;
+  for (const key in collections) {
+    await collections[key].deleteMany({});
+  }
+});
+
+afterAll(async () => {
+  await mongoose.disconnect();
+  await mongoServer.stop();
+}, 15_000);
+
+describe('handleDisputeOpened', () => {
+  it('creates a local Dispute record from the on-chain event', async () => {
+    await handleDisputeOpened({
+      disputeId: 'dispute-1',
+      deliveryId: 'delivery-1',
+      openedBy: 'GABC...OPENER',
+      reason: 'Package damaged',
+      ledgerSequence: 1000,
+    });
+
+    const dispute = await Dispute.findOne({ disputeId: 'dispute-1' });
+    expect(dispute).not.toBeNull();
+    expect(dispute?.status).toBe(DisputeStatus.OPEN);
+    expect(dispute?.deliveryId).toBe('delivery-1');
+    expect(dispute?.openedLedger).toBe(1000);
+  });
+
+  it('is idempotent when the same disputeId is processed twice', async () => {
+    const input = {
+      disputeId: 'dispute-2',
+      deliveryId: 'delivery-2',
+      openedBy: 'GABC...OPENER',
+      ledgerSequence: 500,
+    };
+
+    await handleDisputeOpened(input);
+    await handleDisputeOpened(input);
+
+    const count = await Dispute.countDocuments({ disputeId: 'dispute-2' });
+    expect(count).toBe(1);
+  });
+
+  it('ignores a malformed payload without throwing', async () => {
+    await expect(
+      handleDisputeOpened({
+        disputeId: '',
+        deliveryId: 'delivery-3',
+        openedBy: 'GABC',
+        ledgerSequence: 1,
+      }),
+    ).resolves.not.toThrow();
+
+    const count = await Dispute.countDocuments();
+    expect(count).toBe(0);
+  });
+});
+
+describe('handleDisputeResolved', () => {
+  it('marks an existing dispute resolved', async () => {
+    await Dispute.create({
+      disputeId: 'dispute-4',
+      deliveryId: 'delivery-4',
+      openedBy: 'GABC...OPENER',
+      status: DisputeStatus.OPEN,
+      openedLedger: 100,
+    });
+
+    await handleDisputeResolved({
+      disputeId: 'dispute-4',
+      resolution: 'Refund issued',
+      ledgerSequence: 200,
+    });
+
+    const dispute = await Dispute.findOne({ disputeId: 'dispute-4' });
+    expect(dispute?.status).toBe(DisputeStatus.RESOLVED);
+    expect(dispute?.resolution).toBe('Refund issued');
+    expect(dispute?.resolvedLedger).toBe(200);
+    expect(dispute?.resolvedAt).toBeInstanceOf(Date);
+  });
+
+  it('does not throw when resolving a dispute that was never opened locally', async () => {
+    await expect(
+      handleDisputeResolved({
+        disputeId: 'unknown-dispute',
+        resolution: 'n/a',
+        ledgerSequence: 1,
+      }),
+    ).resolves.not.toThrow();
+  });
+
+  it('notifies the configured webhook on resolution', async () => {
+    const originalWebhookUrl = env.DISPUTE_NOTIFICATION_WEBHOOK_URL;
+    (env as { DISPUTE_NOTIFICATION_WEBHOOK_URL: string }).DISPUTE_NOTIFICATION_WEBHOOK_URL =
+      'https://example.com/dispute-webhook';
+    mockedAxiosPost.mockResolvedValue({ status: 200 });
+
+    try {
+      await Dispute.create({
+        disputeId: 'dispute-5',
+        deliveryId: 'delivery-5',
+        openedBy: 'GABC...OPENER',
+        status: DisputeStatus.OPEN,
+        openedLedger: 100,
+      });
+
+      await handleDisputeResolved({
+        disputeId: 'dispute-5',
+        resolution: 'Refund issued',
+        ledgerSequence: 200,
+      });
+
+      expect(mockedAxiosPost).toHaveBeenCalledWith(
+        'https://example.com/dispute-webhook',
+        expect.objectContaining({ event: 'dispute_resolved', disputeId: 'dispute-5' }),
+      );
+    } finally {
+      (env as { DISPUTE_NOTIFICATION_WEBHOOK_URL: string }).DISPUTE_NOTIFICATION_WEBHOOK_URL =
+        originalWebhookUrl;
+    }
+  });
+});
+
+describe('dispatchDisputeEvent', () => {
+  it('routes dispute_opened to handleDisputeOpened', async () => {
+    await dispatchDisputeEvent('dispute_opened', {
+      disputeId: 'dispute-6',
+      deliveryId: 'delivery-6',
+      openedBy: 'GABC',
+      ledgerSequence: 1,
+    });
+
+    const dispute = await Dispute.findOne({ disputeId: 'dispute-6' });
+    expect(dispute).not.toBeNull();
+  });
+
+  it('ignores unknown event types', async () => {
+    await expect(
+      dispatchDisputeEvent('something_else', {
+        disputeId: 'dispute-7',
+        deliveryId: 'delivery-7',
+        openedBy: 'GABC',
+        ledgerSequence: 1,
+      }),
+    ).resolves.not.toThrow();
+
+    const count = await Dispute.countDocuments({ disputeId: 'dispute-7' });
+    expect(count).toBe(0);
+  });
+});
+
+describe('disputeService.listDisputes / getDisputeById', () => {
+  it('paginates and filters by status', async () => {
+    await Dispute.create([
+      {
+        disputeId: 'a',
+        deliveryId: 'd1',
+        openedBy: 'G1',
+        status: DisputeStatus.OPEN,
+        openedLedger: 1,
+      },
+      {
+        disputeId: 'b',
+        deliveryId: 'd2',
+        openedBy: 'G2',
+        status: DisputeStatus.RESOLVED,
+        openedLedger: 2,
+        resolvedLedger: 3,
+      },
+    ]);
+
+    const openOnly = await disputeService.listDisputes(1, 20, DisputeStatus.OPEN);
+    expect(openOnly.data).toHaveLength(1);
+    expect(openOnly.data[0].disputeId).toBe('a');
+    expect(openOnly.pagination.total).toBe(1);
+  });
+
+  it('throws a not-found error for an unknown disputeId', async () => {
+    await expect(disputeService.getDisputeById('does-not-exist')).rejects.toThrow(/not found/i);
+  });
+});