Add RFC 8594 API deprecation headers and sunset policy

[Vicistar-V]

Summary

API consumers currently have no advance warning before endpoints are removed, so breaking changes surprise integrators. This adds an RFC 8594 compliant deprecation mechanism: a middleware that advertises upcoming removals via standard HTTP headers, backed by a config-driven registry, and surfaces usage in server logs.

Changes

• src/middleware/deprecation.js (new) — Express middleware that, for any request matching a registered endpoint, sets:
  • Deprecation — HTTP-date the endpoint became deprecated (falls back to true)
  • Sunset — HTTP-date the endpoint will be removed
  • Link — rel="deprecation" pointing at migration docs
  • Warning — 299 stale/deprecation notice for older clients
  • Emits a throttled server-side warn log per endpoint so operators can track reliance without flooding logs.
• src/config/deprecations.js (new) — central registry. Each entry supports method, path (with * wildcard), deprecatedSince, sunset, replacement, and documentation. Three example endpoints are pre-registered (/api/v1/lookup, /api/v1/stats, /api/v1/payments/bulk); adjust dates/targets to real planned removals.
• server.js — deprecationMiddleware() mounted before the routers so headers apply to every versioned request.
• deprecation.test.js (new) — 11 unit tests covering header attachment, wildcard matching, method * matching, logging throttle, and date formatting.

Acceptance criteria

• Deprecation middleware created
• Config file for deprecated endpoints with sunset dates
• Deprecated endpoints return Deprecation and Sunset headers
• Deprecation warnings logged server-side

Example response

HTTP/1.1 200 OK
Deprecation: Sat, 29 Aug 2026 00:00:00 GMT
Sunset: Sun, 28 Feb 2027 00:00:00 GMT
Link: https://docs.stellar-tags.example/deprecations/lookup; rel="deprecation"
Warning: 299 - "Deprecated API endpoint, scheduled for removal Sun, 28 Feb 2027 00:00:00 GMT"

Notes for reviewers

• The registry entries are illustrative — confirm the actual sunset dates and replacement endpoints before merging.
• Header names preserve RFC 8594 casing (Deprecation, Sunset).
• Logging is throttled to once per process per endpoint to avoid noise on high-traffic routes.

Closes #592

[drips-wave]

@Vicistar-V 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

[vercel]

@Vicistar-V is attempting to deploy a commit to the Abdulazeem's projects Team on Vercel.

A member of the Team first needs to authorize it.