feat(disputes): add soft-delete and restore

[Habeeb-100]

Overview

This PR adds soft-delete, restore, and retention-window purge support for disputes. Deletes mark records with deletedAt (not hard-purged), default reads hide soft-deleted rows, restore works within a configurable retention window, and a maintenance purge removes expired soft-deleted records.

Related Issue

Closes #867

Changes

Soft-delete for disputes

• [ADD] src/utils/softDelete.ts

  • Shared retention helpers (parseRetentionDays, window checks, filterNotDeleted, SoftDeleteRetentionError → HTTP 410).

• [MODIFY] src/services/disputes.service.ts

  • DisputeRecord.deletedAt, createDispute, listDisputes, softDeleteDispute, restoreDispute, purgeExpiredDisputes.
  • Retention via DISPUTES_SOFT_DELETE_RETENTION_DAYS (default 30).
  • runDisputesSoftDeletePurge() maintenance entrypoint.

• [MODIFY] src/routes/disputes.routes.ts

  • Wire list/get/create/patch/delete to the service (soft-delete on DELETE).
  • POST /api/v1/disputes/:id/restore within retention window.

• [MODIFY] src/modules/disputes/dto/dispute.dto.ts — export DisputeStatus / batch payload types used by the service.

• [MODIFY] docs/disputes.md — soft-delete / restore / purge contract.

• [ADD] Comprehensive unit + route tests (≥95% on impacted soft-delete modules).

Verification Results

npm test -- --coverageThreshold='{}' \
  src/utils/softDelete.test.ts \
  src/services/disputes.softdelete.test.ts \
  src/routes/disputes.softdelete.test.ts

PASS src/utils/softDelete.test.ts
PASS src/services/disputes.softdelete.test.ts
PASS src/routes/disputes.softdelete.test.ts

Test Suites: 3 passed, 3 total
Tests:       29 passed, 29 total

Coverage (impacted):
  softDelete.ts       | 100% stmts / 100% lines
  disputes.service.ts | ~98% stmts / ~98% lines

Acceptance Criteria	Status
Soft-delete hides disputes from default reads	✅ covered
Restore within retention window	✅ covered
Expiry rejects restore (410) and purge hard-deletes	✅ covered
≥95% coverage on soft-delete helpers / service	✅

Timeline

• Habeeb-100 committed

Made with Cursor

[drips-wave]

@Habeeb-100 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits