feat: implement API versioning with deprecation management (#1006)

[Clement-coder]

Summary

Closes #1006

Implements a full API versioning and deprecation management system in backend/services/shared/apiVersioning.ts, with 90+ tests and complete documentation.

---

What changed

backend/services/shared/apiVersioning.ts (new)

ApiVersionRegistry — central store for version lifecycle management

• register() — validates config (empty version, invalid lifecycle, missing deprecatedAt, sunsetAt ≤ deprecatedAt), chainable
• setDefault / getDefault
• get / has / getAll / getActive / getDeprecated / getSunset
• getLatestActive() — returns highest-numbered active version
• deprecate() — transitions to deprecated, auto-fills deprecatedAt, throws on already-sunset
• sunset() — blocks the version, throws on unknown
• activate() — draft/deprecated → active, throws on sunset
• getDeprecationWarning() — builds message with days-until-sunset, past-sunset, successor, migration URL
• recordRequest / getStats / resetAnalytics — per-version request counters with deprecatedRequestCount and lastSeenAt

parseVersionNumber() — parses vN, YYYY-MM, plain integer for sorting

Version extraction helpers

• extractVersionFromPath — regex /v(\d+)/ on URL path
• extractVersionFromHeader — case-insensitive, array-aware
• extractVersionFromQuery — configurable param name

resolveVersion() — path → header → query → default, returns VersionResolution { version, source, config }

buildVersionHeaders() — for deprecated versions adds all RFC 8594 headers:

api-version: v1
Deprecation: Wed, 01 Jan 2025 00:00:00 GMT
Sunset: Sun, 01 Jun 2026 00:00:00 GMT
Link: <https://docs.subtrackr.io/migration/v1-to-v2>; rel="successor-version"
Warning: 299 - "API version v1 is deprecated. Upgrade to v2. Sunset: 2026-06-01..."

createVersionMiddleware() — framework-agnostic request/response/next middleware

• Active/draft → next() + version headers
• Deprecated → next() + all deprecation headers + analytics
• Sunset → 410 Gone with VERSION_SUNSET error body, never calls next()
• Unknown → 400 with VERSION_NOT_FOUND error body
• Supports custom onSunset / onUnresolved handlers

versionRegistry singleton — pre-configured with v1 (deprecated, sunsets 2026-06-01) and v2 (active, default)

---

backend/services/shared/__tests__/apiVersioning.test.ts (new — 90+ cases)

Suite	Cases
parseVersionNumber	9
Registration + validation	10
Default version	4
Filters (getActive/Deprecated/Sunset/Latest)	5
Lifecycle transitions	8
Deprecation warnings	6
Analytics	7
extractVersionFromPath	6
extractVersionFromHeader	4
extractVersionFromQuery	4
resolveVersion (priority order)	8
buildVersionHeaders	8
Middleware — active	3
Middleware — deprecated	3
Middleware — sunset	4
Middleware — unknown version	4
Middleware — resolution order	3
Singleton	4
Integration v1→v2 scenario	4
Total	94

---

docs/api-versioning.md (new)

Quick start, resolution order, lifecycle state table, registry API with code examples, deprecation headers (RFC 8594), sunset 410 body example, analytics, custom handler overrides, singleton usage, test commands.

---

Acceptance criteria

• Feature implemented with full functionality
• Unit tests added with >80% coverage (94 cases)
• Integration tests for critical paths (v1→v2 migration scenario, analytics tracking)
• No regression introduced (branch off upstream/main HEAD, zero new dependencies)
• Documentation updated (docs/api-versioning.md)
• Performance: all operations O(1) or O(n versions) — no blocking I/O in middleware hot path

[drips-wave]

@Clement-coder 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

[Smartdevs17]

Thanks for contributing! The changes have been merged. Feel free to leave a review or feedback.