docs: document the Idempotency-Key contract and cache semantics

[yunus-dev-codecrafter]

closes #353

Summary

Document the Idempotency-Key request-header contract and in-memory cache semantics for API consumers.

• docs/idempotency.md — New consumer-facing reference covering header name, accepted key length (1–200 chars), TTL (24 h default, configurable via IDEMPOTENCY_TTL_MS), replay semantics, 409 conflict conditions, the three guarded endpoints, and an explicit list of non-participating mutating routes.
• src/__tests__/idempotencyCache.test.ts — New dedicated test suite (11 tests) exercising key-boundary edge cases (empty, 1‑char, 200‑char, 201‑char, whitespace-only), non-participating endpoints (POST /pairs/bulk, PATCH /pairs/:s/:d/enabled), cache lifecycle (clearIdempotencyCache, TTL expiry), body-hash sensitivity (different JSON key ordering), and cross-endpoint isolation.

Related Issue

Closes #353

Validation

• npm run build (no build script configured; ts-jest compiles on test)
• npm run lint — clean
• npm test — 871/871 pass, coverage thresholds met (93.43% stmts, 87.22% branch, 95.38% funcs, 93.65% lines)

Checklist

• I kept the change focused on the linked issue.
• I added or updated tests for behavior changes.
• I updated documentation when commands, API behavior, or setup changed.
• I did not commit secrets, tokens, .env files, or private credentials.

Security Notes

N/A — docs-and-tests-only change. No production code was modified, no new dependencies added, no credentials exposed.

[mikewheeleer]

clean diff — shipping it 🚀