Feat api versioning,deprecation and sunset for breaking stream contract changes

[TheDEV111]

Summary

closes #122

• app/lib/api-version.ts — core versioning library: detectVersion
  (URL path → header → default), isV1SunsetPassed, RFC 9745
  addV1DeprecationHeaders, sunsetResponse (410 Gone), and
  toV2Stream transformer for the three breaking shape changes
• middleware.ts — Next.js middleware rewrites /api/v1/* →
  /api/*, injects Deprecation + Sunset + Link headers on every
  v1 response, and short-circuits with 410 after 2026-12-31
• /api/v2/streams/ — v2 list/create/get/delete with the new
  response shape; action routes (start/pause/settle/withdraw) are
  tracked as child issues per the 96h framework scope
• 31 unit tests (api-version.test.ts) and 14 contract tests
  (v1-contract.test.ts) — the contract suite pins the v1 wire shape
  and includes a policy assertion that sunset ≥ 90 days after
  deprecation; run in CI for the full deprecation window
• CHANGELOG.md + docs/api-v2-migration.md +
  docs/deprecation-notice-template.md + README versioning
  section
• Fixed pre-existing merge-conflict corruption in db.ts, route.ts,
  [id]/route.ts, start/, pause/, and settle/ route files that
  were causing all tests importing those modules to fail at suite load

The three breaking changes (v1 → v2)

v1 field	v2 field	Reason
nextAction: string	allowed_actions: string[]	Soroban multi-sig may permit multiple actions; array is forward-compatible
createdAt / updatedAt	created_at / updated_at	Aligns with Stellar Horizon snake_case conventions
settlementTxHash?: string	settlement: {tx_hash, settled_at} | null	Always-present field eliminates absent-vs-removed ambiguity

Deprecation timeline

Date	Event
2026-04-28	v1 deprecated; Deprecation/Sunset headers on all v1 responses
2026-12-31	v1 sunset; /api/v1/* returns 410 Gone

245-day notice (minimum policy: 90 days).

Test plan

• npm test -- --testPathPattern="api-version|v1-contract|stream-lifecycle.e2e" — all 45 pass
• curl -i /api/v1/streams includes Deprecation, Sunset, Link response headers
• curl -i /api/v2/streams response body has allowed_actions, created_at, settlement: null
• After temporarily setting V1_SUNSET_DATE to a past date, /api/v1/streams returns 410 with API_VERSION_SUNSET body
• CHANGELOG.md and docs/api-v2-migration.md render correctly on GitHub

Security notes

No auth, key, PII, or money-movement paths changed. The middleware
operates on path prefix only. The v2 routes share the same in-memory
db and idempotency store as v1 — no new persistence surface.

[drips-wave]

@TheDEV111 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

[TheDEV111]

@greatest0fallt1me pls merge