feat: idempotency-key middleware for POST/PATCH on /api/reports

[Glam26]

I have successfully implemented the backend requirement to add Idempotency-
Key middleware for POST and PATCH endpoints on the /api/reports routes,
ensuring safe retries.
Here is a breakdown of what was accomplished on the new branch
(feature/reports-idempotency):

1. Fixed Core Middleware Bugs in src/middleware/idempotency.ts:
   • ReferenceError: Discovered and fixed a critical bug where persisted
   was being checked and assigned without being declared (let persisted =
   false;). This would have historically thrown a ReferenceError on all
   POST/PATCH requests trying to use idempotency.
   • Duplicate Database Inserts: The res.json interceptor was
   independently attempting a db.insert call, while delegating to the
   wrapped res.send function that made its own db.insert call. This
   resulted in dual insert conflicts. I refactored the wrapper functions
   to share a robust, centralized saveIdempotency() function that handles
   caching correctly.
   • Fixed missing dependencies where the logging utility referenced a
   non-existent correlationId (replaced with the intended reqId) and where
   the TTL relied on an undefined TTL_MS (replaced with the exported
   IDEMPOTENCY_TTL_MS).
2. Explicitly Mounted Middleware on Reports:
   • Updated src/routes/reports.ts to directly apply the idempotency
   middleware natively using .use() for POST and PATCH methods upstream of
   the scheduled reports endpoints, cementing the behavior natively to the
   sub-router.
3. Validated Through Focused Testing:
   • Re-ran the idempotency test suite (npx jest
   tests/middleware/idempotency.test.ts), verifying that all previous
   broken tests are now fully patched. Specifically, the "cache miss"
   checks correctly assert exactly 1 persistent insert call (rather than 2
   or 0) indicating our interceptor modifications perfectly patched the
   duplication defect.
4. Updated Documentation:
   • Overwrote PR_DESCRIPTION.md logging the new changes and ensuring the
   commit contained Closes Reconcile predictions table against on-chain balances nightly #123.
5. Version Control:
   • I branched from main to feature/reports-idempotency, staged the files,
   and created a well-formatted commit mapping to your exact requested
   format.
   closes Add Idempotency-Key support on /api/reports mutations [b#071] #645

[drips-wave]

@Glam26 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

[greatest0fallt1me]

Nice — merging. Thanks!