feat(backend): idempotency-key support for POST /api/donations (Stellar-IndigoPay#148)

- Add idempotency_keys table (migration 016, schema.sql)
- Add validateIdempotencyKey, lookupIdempotencyKey, storeIdempotencyKey
  helpers in donations.js; replay cached response within 24-hour window
- Add idempotencyCleanup.js pg-boss cron (IDEMPOTENCY_CLEANUP_CRON,
  default '5 * * * *') to purge rows older than 24h; 'disabled' to turn off
- Wire cleanup start + graceful-shutdown hook in server.js
- Update frontend/lib/api.ts recordDonation() to accept idempotencyKey
  and send as Idempotency-Key header
- Update DonateForm.tsx and bridge.tsx to generate crypto.randomUUID()
  per attempt
- Document Idempotency-Key header param and 200 replay response in
  docs/api/openapi.yaml
- Add 8 unit tests (idempotencyCleanup.test.js), 3 testcontainers
  integration tests, and 12 new idempotency cases in donations.test.js

Closes Stellar-IndigoPay#148

Author: scarface-dev1

CHANGELOG.md

@@ -2,13 +2,15 @@
 
 ### Features
 
-* **backend,frontend:** add Idempotency-Key support for donation recording (closes #148)
-  - Accept `Idempotency-Key` header (UUID v4) on `POST /api/donations`; store response and replay within 24 hours
-  - New `idempotency_keys` table via migration 016 with index on `created_at`
-  - Hourly pg-boss cleanup cron (`idempotencyCleanup`) purges expired keys (configurable via `IDEMPOTENCY_CLEANUP_CRON`)
-  - Frontend: `DonateForm` and `bridge` generate `crypto.randomUUID()` per donation attempt
-  - Documented in OpenAPI spec with 200 replay response
-  - 11 new tests: 5 unit (donations), 8 unit (cleanup), 3 integration (testcontainers)
+* **backend:** add `Idempotency-Key` header support to `POST /api/donations` (closes #148)
+  - Add `idempotency_keys` table (migration 016, schema.sql) storing key, response status, JSONB body, created_at
+  - Add `validateIdempotencyKey()`, `lookupIdempotencyKey()`, `storeIdempotencyKey()` helpers in `donations.js`; replays cached response within 24-hour window
+  - Add `idempotencyCleanup.js` service — hourly pg-boss cron (`IDEMPOTENCY_CLEANUP_CRON`, default `5 * * * *`) that deletes rows older than 24 h; set to `"disabled"` to turn off
+  - Wire cleanup start + graceful-shutdown hook in `server.js`
+  - Update `frontend/lib/api.ts` `recordDonation()` to accept optional `idempotencyKey` and send it as `Idempotency-Key` header
+  - Update `DonateForm.tsx` and `bridge.tsx` to generate `crypto.randomUUID()` per attempt
+  - Document header parameter and 200 replay response in `docs/api/openapi.yaml`
+  - Add 8 unit tests (`idempotencyCleanup.test.js`), 3 testcontainers integration tests (`idempotencyCleanup.integration.test.js`), and 12 new idempotency test cases in `donations.test.js`
 
 * **docs:** add CONTRIBUTORS.md to credit community work (GF-015, closes #64)
 

backend/src/db/schema.sql

@@ -263,3 +263,17 @@ CREATE INDEX IF NOT EXISTS verification_requests_status_idx
   ON verification_requests (status, submitted_at DESC);
 CREATE INDEX IF NOT EXISTS verification_requests_wallet_idx
   ON verification_requests (wallet_address);
+
+-- idempotency_keys: stores the cached HTTP response for each Idempotency-Key
+-- header value sent by clients to POST /api/donations.  Rows older than 24 h
+-- are pruned by the idempotencyCleanup cron service so that retried requests
+-- within the same window always receive the same response body and status code.
+CREATE TABLE IF NOT EXISTS idempotency_keys (
+  key              TEXT        PRIMARY KEY,
+  response_status  INTEGER     NOT NULL,
+  response_body    JSONB       NOT NULL,
+  created_at       TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idempotency_keys_created_at_idx
+  ON idempotency_keys (created_at);