[Backend] Set X-Idempotent-Replayed response header from idempotency middleware

[ogazboiz]

Join the contributor Telegram: https://t.me/+DOylgFv1jyJlNzM0

Why this matters

/api/loans/:loanId/repay/build and similar write endpoints do not provide an idempotency cache hit response that tells the client "this was already processed". Today, when a client retries with the same Idempotency-Key, it does receive a cached result but without a clear X-Idempotent-Replayed: true header. Adding it lets the frontend distinguish "first success" from "retried" so the UI can de-duplicate toasts and avoid double-counting transactions.

Acceptance criteria

• In idempotencyMiddleware, when a cached entry is found, set response header X-Idempotent-Replayed: true before forwarding the cached body.
• On fresh execution, set X-Idempotent-Replayed: false.
• Add a Jest test asserting both header values across two sequential requests with the same key.
• Document the header in the docs/wiki/ or README for API consumers.

Files to touch

• backend/src/middleware/idempotency.ts
• backend/src/middleware/__tests__/idempotency.test.ts
• docs/wiki/api-idempotency.md (new) or short note in an existing wiki page

Out of scope

• Changing the cache backend or TTL.
• Replaying side effects (the current design is response-only replay, which is correct).

[DTech-Wiz1]

@DTech-Wiz1 has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Can I work on this issue, please?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @DTech-Wiz1 to this issue.

[artylobos]

Submitted PR #913 for this issue: #913

Scope:

• sets X-Idempotent-Replayed: false on fresh idempotent writes and true on cached replays
• exposes the replay/cache headers through CORS for browser clients
• adds regression coverage for fresh execution, sequential replay, and exposed headers
• documents the API idempotency header behavior

Validation:

• GitHub CI is green: CodeQL, supply-chain-audit, contracts, backend, frontend
• local focused Jest: 6 passed
• local backend build/typecheck/prettier checks passed
• local backend full Jest: 211 passed, 18 skipped

No secrets, private keys, wallet material, or deployment values included.

[Anuoluwapo25]

@Anuoluwapo25 has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hi, Please can i work on this issues

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Anuoluwapo25 to this issue.

[sanmipaul]

@sanmipaul has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

This is a great project I will love to work on this

ℹ️ Repo Maintainers: To accept this application, review their application or assign @sanmipaul to this issue.

[strngecloud]

@strngecloud has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

I will love to work on this issue please assign

ℹ️ Repo Maintainers: To accept this application, review their application or assign @strngecloud to this issue.

[drips-wave]

Congratulations, @Anuoluwapo25! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @Anuoluwapo25: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊