ci: Bump version to 0.12.17 [skip ci]

Complete ADR-008 Phase 2
2026-01-28 00:08:39 +05:00 · 2026-01-27 11:06:09 -08:00
38 changed files with 5524 additions and 249 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -32,8 +32,10 @@ Day-to-day development guides:
 - [Testing Guide](development/TESTING.md) - Unit, integration, and E2E testing
 - [Code Patterns](development/CODE-PATTERNS.md) - Common code patterns and ADR examples
 - [API Versioning](development/API-VERSIONING.md) - API versioning infrastructure and workflows
 - [Design Tokens](development/DESIGN_TOKENS.md) - UI design system and Neo-Brutalism
 - [Debugging Guide](development/DEBUGGING.md) - Common debugging patterns
 - [Dev Container](development/DEV-CONTAINER.md) - Development container setup and PM2
 ### 🔧 Operations
--- a/docs/adr/0008-api-versioning-strategy.md
+++ b/docs/adr/0008-api-versioning-strategy.md
@@ -2,9 +2,11 @@
 **Date**: 2025-12-12
-**Status**: Accepted (Phase 1 Complete)
+**Status**: Accepted (Phase 2 Complete - All Tasks Done)
-**Updated**: 2026-01-26
+**Updated**: 2026-01-27
 **Completion Note**: Phase 2 fully complete including test path migration. All 23 integration test files updated to use `/api/v1/` paths. Test suite improved from 274/348 to 345/348 passing (3 remain as todo/skipped for known issues unrelated to versioning).
 ## Context
@@ -43,19 +45,19 @@ We will adopt a URI-based versioning strategy for the API using a phased rollout
 The following changes require a new API version:
-| Change Type                   | Breaking? | Example                                      |
+| Change Type                   | Breaking? | Example                                    |
-| ----------------------------- | --------- | -------------------------------------------- |
+| ----------------------------- | --------- | ------------------------------------------ |
-| Remove endpoint               | Yes       | DELETE `/api/v1/legacy-feature`              |
+| Remove endpoint               | Yes       | DELETE `/api/v1/legacy-feature`            |
-| Remove response field         | Yes       | Remove `user.email` from response            |
+| Remove response field         | Yes       | Remove `user.email` from response          |
-| Change response field type    | Yes       | `id: number` to `id: string`                 |
+| Change response field type    | Yes       | `id: number` to `id: string`               |
-| Change required request field | Yes       | Make `email` required when it was optional   |
+| Change required request field | Yes       | Make `email` required when it was optional |
-| Rename endpoint               | Yes       | `/users` to `/accounts`                      |
+| Rename endpoint               | Yes       | `/users` to `/accounts`                    |
-| Add optional response field   | No        | Add `user.avatar_url`                        |
+| Add optional response field   | No        | Add `user.avatar_url`                      |
-| Add optional request field    | No        | Add optional `page` parameter                |
+| Add optional request field    | No        | Add optional `page` parameter              |
-| Add new endpoint              | No        | Add `/api/v1/new-feature`                    |
+| Add new endpoint              | No        | Add `/api/v1/new-feature`                  |
-| Fix bug in behavior           | No*       | Correct calculation error                    |
+| Fix bug in behavior           | No\*      | Correct calculation error                  |
-*Bug fixes may warrant version increment if clients depend on the buggy behavior.
+\*Bug fixes may warrant version increment if clients depend on the buggy behavior.
 ## Implementation Phases
@@ -109,6 +111,7 @@ The following changes require a new API version:
   ```
 **Acceptance Criteria**:
 - All existing functionality works at `/api/v1/*`
 - Frontend makes requests to `/api/v1/*`
 - OpenAPI documentation reflects `/api/v1/*` paths
@@ -246,11 +249,14 @@ export function versionRedirectMiddleware(req: Request, res: Response, next: Nex
  }
  // Log deprecation warning
-  logger.warn({
+  logger.warn(
-    path: req.originalUrl,
+    {
-    method: req.method,
+      path: req.originalUrl,
-    ip: req.ip,
+      method: req.method,
-  }, 'Unversioned API request - redirecting to v1');
+      ip: req.ip,
    },
    'Unversioned API request - redirecting to v1',
  );
  // Use 307 to preserve HTTP method
  const redirectUrl = `/api/v1${path}${req.url.includes('?') ? req.url.substring(req.url.indexOf('?')) : ''}`;
@@ -296,13 +302,13 @@ app.use('/api/v1', (req, res, next) => {
 ## Key Files
-| File                                | Purpose                                       |
+| File                                | Purpose                                     |
-| ----------------------------------- | --------------------------------------------- |
+| ----------------------------------- | ------------------------------------------- |
-| `server.ts`                         | Route registration with version prefixes      |
+| `server.ts`                         | Route registration with version prefixes    |
-| `src/services/apiClient.ts`         | Frontend API base URL configuration           |
+| `src/services/apiClient.ts`         | Frontend API base URL configuration         |
-| `src/config/swagger.ts`             | OpenAPI server URL and version info           |
+| `src/config/swagger.ts`             | OpenAPI server URL and version info         |
-| `src/routes/*.routes.ts`            | Individual route handlers                     |
+| `src/routes/*.routes.ts`            | Individual route handlers                   |
-| `src/middleware/versionRedirect.ts` | Backwards compatibility redirects (Phase 1)   |
+| `src/middleware/versionRedirect.ts` | Backwards compatibility redirects (Phase 1) |
 ## Related ADRs
@@ -323,12 +329,42 @@ app.use('/api/v1', (req, res, next) => {
 - [x] Update API documentation examples (Swagger server URL updated)
 - [x] Verify all health checks work at `/api/v1/health/*`
-### Phase 2 Tasks (Future)
+### Phase 2 Tasks
- [ ] Create version router factory
+**Implementation Guide**: [API Versioning Infrastructure](../architecture/api-versioning-infrastructure.md)
- [ ] Implement deprecation header middleware
+**Developer Guide**: [API Versioning Developer Guide](../development/API-VERSIONING.md)
- [ ] Add version detection to request context
+
- [ ] Document versioning patterns for developers
+- [x] Create version router factory (`src/routes/versioned.ts`)
 - [x] Implement deprecation header middleware (`src/middleware/deprecation.middleware.ts`)
 - [x] Add version detection to request context (`src/middleware/apiVersion.middleware.ts`)
 - [x] Add version types to Express Request (`src/types/express.d.ts`)
 - [x] Create version constants configuration (`src/config/apiVersions.ts`)
 - [x] Update server.ts to use version router factory
 - [x] Update swagger.ts for multi-server documentation
 - [x] Add unit tests for version middleware
 - [x] Add integration tests for versioned router
 - [x] Document versioning patterns for developers
 - [x] Migrate all test files to use `/api/v1/` paths (23 files, ~70 occurrences)
 ### Test Path Migration Summary (2026-01-27)
 The final cleanup task for Phase 2 was completed by updating all integration test files to use versioned API paths:
 | Metric                       | Value                                    |
 | ---------------------------- | ---------------------------------------- |
 | Test files updated           | 23                                       |
 | Path occurrences changed     | ~70                                      |
 | Test failures resolved       | 71 (274 -> 345 passing)                  |
 | Tests remaining todo/skipped | 3 (known issues, not versioning-related) |
 | Type check                   | Passing                                  |
 | Versioning-specific tests    | 82/82 passing                            |
 **Test Results After Migration**:
 - Integration tests: 345/348 passing
 - Unit tests: 3,375/3,391 passing (16 pre-existing failures unrelated to versioning)
 **Migration Documentation**: [Test Path Migration Guide](../development/test-path-migration.md)
 ### Phase 3 Tasks (Future)
--- a/docs/adr/adr-implementation-tracker.md
+++ b/docs/adr/adr-implementation-tracker.md
@@ -15,9 +15,9 @@ This document tracks the implementation status and estimated effort for all Arch
 | Status                       | Count |
 | ---------------------------- | ----- |
-| Accepted (Fully Implemented) | 39    |
+| Accepted (Fully Implemented) | 40    |
 | Partially Implemented        | 2     |
-| Proposed (Not Started)       | 15    |
+| Proposed (Not Started)       | 14    |
 ---
@@ -44,13 +44,13 @@ This document tracks the implementation status and estimated effort for all Arch
 ### Category 3: API & Integration
-| ADR                                                                 | Title                    | Status      | Effort | Notes                                 |
+| ADR                                                                 | Title                    | Status   | Effort | Notes                                 |
-| ------------------------------------------------------------------- | ------------------------ | ----------- | ------ | ------------------------------------- |
+| ------------------------------------------------------------------- | ------------------------ | -------- | ------ | ------------------------------------- |
-| [ADR-003](./0003-standardized-input-validation-using-middleware.md) | Input Validation         | Accepted    | -      | Fully implemented                     |
+| [ADR-003](./0003-standardized-input-validation-using-middleware.md) | Input Validation         | Accepted | -      | Fully implemented                     |
-| [ADR-008](./0008-api-versioning-strategy.md)                        | API Versioning           | Proposed    | L      | Major URL/routing changes             |
+| [ADR-008](./0008-api-versioning-strategy.md)                        | API Versioning           | Accepted | -      | Phase 2 complete, tests migrated      |
-| [ADR-018](./0018-api-documentation-strategy.md)                     | API Documentation        | Accepted    | -      | OpenAPI/Swagger implemented           |
+| [ADR-018](./0018-api-documentation-strategy.md)                     | API Documentation        | Accepted | -      | OpenAPI/Swagger implemented           |
-| [ADR-022](./0022-real-time-notification-system.md)                  | Real-time Notifications  | Accepted    | -      | Fully implemented                     |
+| [ADR-022](./0022-real-time-notification-system.md)                  | Real-time Notifications  | Accepted | -      | Fully implemented                     |
-| [ADR-028](./0028-api-response-standardization.md)                   | Response Standardization | Implemented | L      | Completed (routes, middleware, tests) |
+| [ADR-028](./0028-api-response-standardization.md)                   | Response Standardization | Accepted | -      | Completed (routes, middleware, tests) |
 ### Category 4: Security & Compliance
@@ -136,47 +136,48 @@ These ADRs are proposed or partially implemented, ordered by suggested implement
 | 2        | ADR-054 | Bugsink-Gitea Sync       | Proposed | L      | Automated issue tracking from errors |
 | 3        | ADR-023 | Schema Migrations v2     | Proposed | L      | Database evolution support           |
 | 4        | ADR-029 | Secret Rotation          | Proposed | L      | Security improvement                 |
-| 5        | ADR-008 | API Versioning           | Proposed | L      | Future API evolution                 |
+| 5        | ADR-030 | Circuit Breaker          | Proposed | L      | Resilience improvement               |
-| 6        | ADR-030 | Circuit Breaker          | Proposed | L      | Resilience improvement               |
+| 6        | ADR-056 | APM (Performance)        | Proposed | M      | Enable when performance issues arise |
-| 7        | ADR-056 | APM (Performance)        | Proposed | M      | Enable when performance issues arise |
+| 7        | ADR-011 | Authorization & RBAC     | Proposed | XL     | Advanced permission system           |
-| 8        | ADR-011 | Authorization & RBAC     | Proposed | XL     | Advanced permission system           |
+| 8        | ADR-025 | i18n & l10n              | Proposed | XL     | Multi-language support               |
-| 9        | ADR-025 | i18n & l10n              | Proposed | XL     | Multi-language support               |
+| 9        | ADR-031 | Data Retention & Privacy | Proposed | XL     | Compliance requirements              |
 | 10       | ADR-031 | Data Retention & Privacy | Proposed | XL     | Compliance requirements              |
 ---
 ## Recent Implementation History
-| Date       | ADR     | Change                                                                       |
+| Date       | ADR     | Change                                                                              |
-| ---------- | ------- | ---------------------------------------------------------------------------- |
+| ---------- | ------- | ----------------------------------------------------------------------------------- |
-| 2026-01-26 | ADR-015 | Completed - Added Sentry user context in AuthProvider, now fully implemented |
+| 2026-01-27 | ADR-008 | Test path migration complete - 23 files, ~70 paths updated, 274->345 tests passing  |
-| 2026-01-26 | ADR-056 | Created - APM split from ADR-015, status Proposed (tracesSampleRate=0)       |
+| 2026-01-27 | ADR-008 | Phase 2 Complete - Version router factory, deprecation headers, 82 versioning tests |
-| 2026-01-26 | ADR-015 | Refactored to focus on error tracking only, temporarily status Partial       |
+| 2026-01-26 | ADR-015 | Completed - Added Sentry user context in AuthProvider, now fully implemented        |
-| 2026-01-26 | ADR-048 | Verified as fully implemented - JWT + OAuth authentication complete          |
+| 2026-01-26 | ADR-056 | Created - APM split from ADR-015, status Proposed (tracesSampleRate=0)              |
-| 2026-01-26 | ADR-022 | Verified as fully implemented - WebSocket notifications complete             |
+| 2026-01-26 | ADR-015 | Refactored to focus on error tracking only, temporarily status Partial              |
-| 2026-01-26 | ADR-052 | Marked as fully implemented - createScopedLogger complete                    |
+| 2026-01-26 | ADR-048 | Verified as fully implemented - JWT + OAuth authentication complete                 |
-| 2026-01-26 | ADR-053 | Marked as fully implemented - /health/queues endpoint complete               |
+| 2026-01-26 | ADR-022 | Verified as fully implemented - WebSocket notifications complete                    |
-| 2026-01-26 | ADR-050 | Marked as fully implemented - PostgreSQL function observability              |
+| 2026-01-26 | ADR-052 | Marked as fully implemented - createScopedLogger complete                           |
-| 2026-01-26 | ADR-055 | Created (renumbered from duplicate ADR-023) - DB normalization               |
+| 2026-01-26 | ADR-053 | Marked as fully implemented - /health/queues endpoint complete                      |
-| 2026-01-26 | ADR-054 | Added to tracker - Bugsink to Gitea issue synchronization                    |
+| 2026-01-26 | ADR-050 | Marked as fully implemented - PostgreSQL function observability                     |
-| 2026-01-26 | ADR-053 | Added to tracker - Worker health checks and monitoring                       |
+| 2026-01-26 | ADR-055 | Created (renumbered from duplicate ADR-023) - DB normalization                      |
-| 2026-01-26 | ADR-052 | Added to tracker - Granular debug logging strategy                           |
+| 2026-01-26 | ADR-054 | Added to tracker - Bugsink to Gitea issue synchronization                           |
-| 2026-01-26 | ADR-051 | Added to tracker - Asynchronous context propagation                          |
+| 2026-01-26 | ADR-053 | Added to tracker - Worker health checks and monitoring                              |
-| 2026-01-26 | ADR-048 | Added to tracker - Authentication strategy                                   |
+| 2026-01-26 | ADR-052 | Added to tracker - Granular debug logging strategy                                  |
-| 2026-01-26 | ADR-040 | Added to tracker - Testing economics and priorities                          |
+| 2026-01-26 | ADR-051 | Added to tracker - Asynchronous context propagation                                 |
-| 2026-01-17 | ADR-054 | Created - Bugsink-Gitea sync worker proposal                                 |
+| 2026-01-26 | ADR-048 | Added to tracker - Authentication strategy                                          |
-| 2026-01-11 | ADR-050 | Created - PostgreSQL function observability with fn_log()                    |
+| 2026-01-26 | ADR-040 | Added to tracker - Testing economics and priorities                                 |
-| 2026-01-11 | ADR-018 | Implemented - OpenAPI/Swagger documentation at /docs/api-docs                |
+| 2026-01-17 | ADR-054 | Created - Bugsink-Gitea sync worker proposal                                        |
-| 2026-01-11 | ADR-049 | Created - Gamification system, achievements, and testing                     |
+| 2026-01-11 | ADR-050 | Created - PostgreSQL function observability with fn_log()                           |
-| 2026-01-09 | ADR-047 | Created - Project file/folder organization with migration plan               |
+| 2026-01-11 | ADR-018 | Implemented - OpenAPI/Swagger documentation at /docs/api-docs                       |
-| 2026-01-09 | ADR-041 | Created - AI/Gemini integration with model fallback                          |
+| 2026-01-11 | ADR-049 | Created - Gamification system, achievements, and testing                            |
-| 2026-01-09 | ADR-042 | Created - Email and notification architecture with BullMQ                    |
+| 2026-01-09 | ADR-047 | Created - Project file/folder organization with migration plan                      |
-| 2026-01-09 | ADR-043 | Created - Express middleware pipeline ordering and patterns                  |
+| 2026-01-09 | ADR-041 | Created - AI/Gemini integration with model fallback                                 |
-| 2026-01-09 | ADR-044 | Created - Frontend feature-based folder organization                         |
+| 2026-01-09 | ADR-042 | Created - Email and notification architecture with BullMQ                           |
-| 2026-01-09 | ADR-045 | Created - Test data factory pattern for mock generation                      |
+| 2026-01-09 | ADR-043 | Created - Express middleware pipeline ordering and patterns                         |
-| 2026-01-09 | ADR-046 | Created - Image processing pipeline with Sharp and EXIF stripping            |
+| 2026-01-09 | ADR-044 | Created - Frontend feature-based folder organization                                |
-| 2026-01-09 | ADR-026 | Fully implemented - client-side structured logger                            |
+| 2026-01-09 | ADR-045 | Created - Test data factory pattern for mock generation                             |
-| 2026-01-09 | ADR-028 | Fully implemented - all routes, middleware, and tests updated                |
+| 2026-01-09 | ADR-046 | Created - Image processing pipeline with Sharp and EXIF stripping                   |
 | 2026-01-09 | ADR-026 | Fully implemented - client-side structured logger                                   |
 | 2026-01-09 | ADR-028 | Fully implemented - all routes, middleware, and tests updated                       |
 ---
--- a/docs/architecture/OVERVIEW.md
+++ b/docs/architecture/OVERVIEW.md
@@ -762,11 +762,14 @@ The system architecture is governed by Architecture Decision Records (ADRs). Key
 ### API and Integration
-| ADR     | Title                         | Status      |
+| ADR     | Title                         | Status           |
-| ------- | ----------------------------- | ----------- |
+| ------- | ----------------------------- | ---------------- |
-| ADR-003 | Standardized Input Validation | Accepted    |
+| ADR-003 | Standardized Input Validation | Accepted         |
-| ADR-022 | Real-time Notification System | Proposed    |
+| ADR-008 | API Versioning Strategy       | Phase 1 Complete |
-| ADR-028 | API Response Standardization  | Implemented |
+| ADR-022 | Real-time Notification System | Proposed         |
 | ADR-028 | API Response Standardization  | Implemented      |
 **Implementation Guide**: [API Versioning Infrastructure](./api-versioning-infrastructure.md) (Phase 2)
 ### Security
--- a/docs/architecture/api-versioning-infrastructure.md
+++ b/docs/architecture/api-versioning-infrastructure.md
@@ -0,0 +1,521 @@
 # API Versioning Infrastructure (ADR-008 Phase 2)
 **Status**: Complete
 **Date**: 2026-01-27
 **Prerequisite**: ADR-008 Phase 1 Complete (all routes at `/api/v1/*`)
 ## Implementation Summary
 Phase 2 has been fully implemented with the following results:
 | Metric             | Value                                  |
 | ------------------ | -------------------------------------- |
 | New Files Created  | 5                                      |
 | Files Modified     | 2 (server.ts, express.d.ts)            |
 | Unit Tests         | 82 passing (100%)                      |
 | Integration Tests  | 48 new versioning tests                |
 | RFC Compliance     | RFC 8594 (Sunset), RFC 8288 (Link)     |
 | Supported Versions | v1 (active), v2 (infrastructure ready) |
 **Developer Guide**: [API-VERSIONING.md](../development/API-VERSIONING.md)
 ## Purpose
 Build infrastructure to support parallel API versions, version detection, and deprecation workflows. Enables future v2 API without breaking existing clients.
 ## Architecture Overview
 ```text
 Request → Version Router → Version Middleware → Domain Router → Handler
           ↓                    ↓
    createVersionedRouter()  attachVersionInfo()
           ↓                    ↓
    /api/v1/* | /api/v2/*   req.apiVersion = 'v1'|'v2'
 ```
 ## Key Components
 | Component              | File                                       | Responsibility                             |
 | ---------------------- | ------------------------------------------ | ------------------------------------------ |
 | Version Router Factory | `src/routes/versioned.ts`                  | Create version-specific Express routers    |
 | Version Middleware     | `src/middleware/apiVersion.middleware.ts`  | Extract version, attach to request context |
 | Deprecation Middleware | `src/middleware/deprecation.middleware.ts` | Add RFC 8594 deprecation headers           |
 | Version Types          | `src/types/express.d.ts`                   | Extend Express Request with apiVersion     |
 | Version Constants      | `src/config/apiVersions.ts`                | Centralized version definitions            |
 ## Implementation Tasks
 ### Task 1: Version Types (Foundation)
 **File**: `src/types/express.d.ts`
 ```typescript
 declare global {
  namespace Express {
    interface Request {
      apiVersion?: 'v1' | 'v2';
      versionDeprecated?: boolean;
    }
  }
 }
 ```
 **Dependencies**: None
 **Testing**: Type-check only (`npm run type-check`)
 ---
 ### Task 2: Version Constants
 **File**: `src/config/apiVersions.ts`
 ```typescript
 export const API_VERSIONS = ['v1', 'v2'] as const;
 export type ApiVersion = (typeof API_VERSIONS)[number];
 export const CURRENT_VERSION: ApiVersion = 'v1';
 export const DEFAULT_VERSION: ApiVersion = 'v1';
 export interface VersionConfig {
  version: ApiVersion;
  status: 'active' | 'deprecated' | 'sunset';
  sunsetDate?: string; // ISO 8601
  successorVersion?: ApiVersion;
 }
 export const VERSION_CONFIG: Record<ApiVersion, VersionConfig> = {
  v1: { version: 'v1', status: 'active' },
  v2: { version: 'v2', status: 'active' },
 };
 ```
 **Dependencies**: None
 **Testing**: Unit test for version validation
 ---
 ### Task 3: Version Detection Middleware
 **File**: `src/middleware/apiVersion.middleware.ts`
 ```typescript
 import { Request, Response, NextFunction } from 'express';
 import { API_VERSIONS, ApiVersion, DEFAULT_VERSION } from '../config/apiVersions';
 export function extractApiVersion(req: Request, _res: Response, next: NextFunction) {
  // Extract from URL path: /api/v1/... → 'v1'
  const pathMatch = req.path.match(/^\/v(\d+)\//);
  if (pathMatch) {
    const version = `v${pathMatch[1]}` as ApiVersion;
    if (API_VERSIONS.includes(version)) {
      req.apiVersion = version;
    }
  }
  // Fallback to default if not detected
  req.apiVersion = req.apiVersion || DEFAULT_VERSION;
  next();
 }
 ```
 **Pattern**: Attach to request before route handlers
 **Integration Point**: `server.ts` before versioned route mounting
 **Testing**: Unit tests for path extraction, default fallback
 ---
 ### Task 4: Deprecation Headers Middleware
 **File**: `src/middleware/deprecation.middleware.ts`
 Implements RFC 8594 (Sunset Header) and draft-ietf-httpapi-deprecation-header.
 ```typescript
 import { Request, Response, NextFunction } from 'express';
 import { VERSION_CONFIG, ApiVersion } from '../config/apiVersions';
 import { logger } from '../services/logger.server';
 export function deprecationHeaders(version: ApiVersion) {
  const config = VERSION_CONFIG[version];
  return (req: Request, res: Response, next: NextFunction) => {
    if (config.status === 'deprecated') {
      res.set('Deprecation', 'true');
      if (config.sunsetDate) {
        res.set('Sunset', config.sunsetDate);
      }
      if (config.successorVersion) {
        res.set('Link', `</api/${config.successorVersion}>; rel="successor-version"`);
      }
      req.versionDeprecated = true;
      // Log deprecation access for monitoring
      logger.warn(
        {
          apiVersion: version,
          path: req.path,
          method: req.method,
          sunsetDate: config.sunsetDate,
        },
        'Deprecated API version accessed',
      );
    }
    // Always set version header
    res.set('X-API-Version', version);
    next();
  };
 }
 ```
 **RFC Compliance**:
 - `Deprecation: true` (draft-ietf-httpapi-deprecation-header)
 - `Sunset: <date>` (RFC 8594)
 - `Link: <url>; rel="successor-version"` (RFC 8288)
 **Testing**: Unit tests for header presence, version status variations
 ---
 ### Task 5: Version Router Factory
 **File**: `src/routes/versioned.ts`
 ```typescript
 import { Router } from 'express';
 import { ApiVersion } from '../config/apiVersions';
 import { extractApiVersion } from '../middleware/apiVersion.middleware';
 import { deprecationHeaders } from '../middleware/deprecation.middleware';
 // Import domain routers
 import authRouter from './auth.routes';
 import userRouter from './user.routes';
 import flyerRouter from './flyer.routes';
 // ... all domain routers
 interface VersionedRouters {
  v1: Record<string, Router>;
  v2: Record<string, Router>;
 }
 const ROUTERS: VersionedRouters = {
  v1: {
    auth: authRouter,
    users: userRouter,
    flyers: flyerRouter,
    // ... all v1 routers (current implementation)
  },
  v2: {
    // Future: v2-specific routers
    // auth: authRouterV2,
    // For now, fallback to v1
  },
 };
 export function createVersionedRouter(version: ApiVersion): Router {
  const router = Router();
  // Apply version middleware
  router.use(extractApiVersion);
  router.use(deprecationHeaders(version));
  // Get routers for this version, fallback to v1
  const versionRouters = ROUTERS[version] || ROUTERS.v1;
  // Mount domain routers
  Object.entries(versionRouters).forEach(([path, domainRouter]) => {
    router.use(`/${path}`, domainRouter);
  });
  return router;
 }
 ```
 **Pattern**: Factory function returns configured Router
 **Fallback Strategy**: v2 uses v1 routers until v2-specific handlers exist
 **Testing**: Integration test verifying route mounting
 ---
 ### Task 6: Server Integration
 **File**: `server.ts` (modifications)
 ```typescript
 // Before (current implementation - Phase 1):
 app.use('/api/v1/auth', authRouter);
 app.use('/api/v1/users', userRouter);
 // ... individual route mounting
 // After (Phase 2):
 import { createVersionedRouter } from './src/routes/versioned';
 // Mount versioned API routers
 app.use('/api/v1', createVersionedRouter('v1'));
 app.use('/api/v2', createVersionedRouter('v2')); // Placeholder for future
 // Keep redirect middleware for unversioned requests
 app.use('/api', versionRedirectMiddleware);
 ```
 **Breaking Change Risk**: Low (same routes, different mounting)
 **Rollback**: Revert to individual `app.use()` calls
 **Testing**: Full integration test suite must pass
 ---
 ### Task 7: Request Context Propagation
 **Pattern**: Version flows through request lifecycle for conditional logic.
 ```typescript
 // In any route handler or service:
 function handler(req: Request, res: Response) {
  if (req.apiVersion === 'v2') {
    // v2-specific behavior
    return sendSuccess(res, transformV2(data));
  }
  // v1 behavior (default)
  return sendSuccess(res, data);
 }
 ```
 **Use Cases**:
 - Response transformation based on version
 - Feature flags per version
 - Metric tagging by version
 ---
 ### Task 8: Documentation Update
 **File**: `src/config/swagger.ts` (modifications)
 ```typescript
 const swaggerDefinition: OpenAPIV3.Document = {
  // ...
  servers: [
    {
      url: '/api/v1',
      description: 'API v1 (Current)',
    },
    {
      url: '/api/v2',
      description: 'API v2 (Future)',
    },
  ],
  // ...
 };
 ```
 **File**: `docs/adr/0008-api-versioning-strategy.md` (update checklist)
 ---
 ### Task 9: Unit Tests
 **File**: `src/middleware/apiVersion.middleware.test.ts`
 ```typescript
 describe('extractApiVersion', () => {
  it('extracts v1 from /api/v1/users', () => {
    /* ... */
  });
  it('extracts v2 from /api/v2/users', () => {
    /* ... */
  });
  it('defaults to v1 for unversioned paths', () => {
    /* ... */
  });
  it('ignores invalid version numbers', () => {
    /* ... */
  });
 });
 ```
 **File**: `src/middleware/deprecation.middleware.test.ts`
 ```typescript
 describe('deprecationHeaders', () => {
  it('adds no headers for active version', () => {
    /* ... */
  });
  it('adds Deprecation header for deprecated version', () => {
    /* ... */
  });
  it('adds Sunset header when sunsetDate configured', () => {
    /* ... */
  });
  it('adds Link header for successor version', () => {
    /* ... */
  });
  it('always sets X-API-Version header', () => {
    /* ... */
  });
 });
 ```
 ---
 ### Task 10: Integration Tests
 **File**: `src/routes/versioned.test.ts`
 ```typescript
 describe('Versioned Router Integration', () => {
  it('mounts all v1 routes correctly', () => {
    /* ... */
  });
  it('v2 falls back to v1 handlers', () => {
    /* ... */
  });
  it('sets X-API-Version response header', () => {
    /* ... */
  });
  it('deprecation headers appear when configured', () => {
    /* ... */
  });
 });
 ```
 **Run in Container**: `podman exec -it flyer-crawler-dev npm test -- versioned`
 ## Implementation Sequence
 ```text
 [Task 1] → [Task 2] → [Task 3] → [Task 4] → [Task 5] → [Task 6]
  Types     Config    Middleware  Middleware  Factory   Server
                         ↓            ↓          ↓         ↓
                      [Task 7]    [Task 9]   [Task 10] [Task 8]
                       Context     Unit       Integ      Docs
 ```
 **Critical Path**: 1 → 2 → 3 → 5 → 6 (server integration)
 ## File Structure After Implementation
 ```text
 src/
 ├── config/
 │   ├── apiVersions.ts          # NEW: Version constants
 │   └── swagger.ts              # MODIFIED: Multi-server
 ├── middleware/
 │   ├── apiVersion.middleware.ts      # NEW: Version extraction
 │   ├── apiVersion.middleware.test.ts # NEW: Unit tests
 │   ├── deprecation.middleware.ts     # NEW: RFC 8594 headers
 │   └── deprecation.middleware.test.ts # NEW: Unit tests
 ├── routes/
 │   ├── versioned.ts            # NEW: Router factory
 │   ├── versioned.test.ts       # NEW: Integration tests
 │   └── *.routes.ts             # UNCHANGED: Domain routers
 ├── types/
 │   └── express.d.ts            # MODIFIED: Add apiVersion
 server.ts                       # MODIFIED: Use versioned router
 ```
 ## Risk Assessment
 | Risk                                 | Likelihood | Impact | Mitigation                          |
 | ------------------------------------ | ---------- | ------ | ----------------------------------- |
 | Route registration order breaks      | Medium     | High   | Full integration test suite         |
 | Middleware not applied to all routes | Low        | Medium | Factory pattern ensures consistency |
 | Performance impact from middleware   | Low        | Low    | Minimal overhead (path regex)       |
 | Type errors in extended Request      | Low        | Medium | TypeScript strict mode catches      |
 ## Rollback Procedure
 1. Revert `server.ts` to individual route mounting
 2. Remove new middleware files (not breaking)
 3. Remove version types from `express.d.ts`
 4. Run `npm run type-check && npm test` to verify
 ## Success Criteria
 - [x] All existing tests pass (`npm test` in container)
 - [x] `X-API-Version: v1` header on all `/api/v1/*` responses
 - [x] TypeScript compiles without errors (`npm run type-check`)
 - [x] No performance regression (< 5ms added latency)
 - [x] Deprecation headers work when v1 marked deprecated (manual test)
 ## Known Issues and Follow-up Work
 ### Integration Tests Using Unversioned Paths
 **Issue**: Some existing integration tests make requests to unversioned paths (e.g., `/api/flyers` instead of `/api/v1/flyers`). These tests now receive 301 redirects due to the backwards compatibility middleware.
 **Impact**: 74 integration tests may need updates to use versioned paths explicitly.
 **Workaround Options**:
 1. Update test paths to use `/api/v1/*` explicitly (recommended)
 2. Configure supertest to follow redirects automatically
 3. Accept 301 as valid response in affected tests
 **Resolution**: Phase 3 work item - update integration tests to use versioned endpoints consistently.
 ### Phase 3 Prerequisites
 Before marking v1 as deprecated and implementing v2:
 1. Update all integration tests to use versioned paths
 2. Define breaking changes requiring v2
 3. Create v2-specific route handlers where needed
 4. Set deprecation timeline for v1
 ## Related ADRs
 | ADR     | Relationship                                      |
 | ------- | ------------------------------------------------- |
 | ADR-008 | Parent decision (this implements Phase 2)         |
 | ADR-003 | Validation middleware pattern applies per-version |
 | ADR-028 | Response format consistent across versions        |
 | ADR-018 | OpenAPI docs reflect versioned endpoints          |
 | ADR-043 | Middleware pipeline order considerations          |
 ## Usage Examples
 ### Checking Version in Handler
 ```typescript
 // src/routes/flyer.routes.ts
 router.get('/', async (req, res) => {
  const flyers = await flyerRepo.getFlyers(req.log);
  // Version-specific response transformation
  if (req.apiVersion === 'v2') {
    return sendSuccess(res, flyers.map(transformFlyerV2));
  }
  return sendSuccess(res, flyers);
 });
 ```
 ### Marking Version as Deprecated
 ```typescript
 // src/config/apiVersions.ts
 export const VERSION_CONFIG = {
  v1: {
    version: 'v1',
    status: 'deprecated',
    sunsetDate: '2027-01-01T00:00:00Z',
    successorVersion: 'v2',
  },
  v2: { version: 'v2', status: 'active' },
 };
 ```
 ### Testing Deprecation Headers
 ```bash
 curl -I https://localhost:3001/api/v1/flyers
 # When v1 deprecated:
 # Deprecation: true
 # Sunset: 2027-01-01T00:00:00Z
 # Link: </api/v2>; rel="successor-version"
 # X-API-Version: v1
 ```
--- a/docs/development/API-VERSIONING.md
+++ b/docs/development/API-VERSIONING.md
@@ -0,0 +1,844 @@
 # API Versioning Developer Guide
 **Status**: Complete (Phase 2)
 **Last Updated**: 2026-01-27
 **Implements**: ADR-008 Phase 2
 **Architecture**: [api-versioning-infrastructure.md](../architecture/api-versioning-infrastructure.md)
 This guide covers the API versioning infrastructure for the Flyer Crawler application. It explains how versioning works, how to add new versions, and how to deprecate old ones.
 ## Implementation Status
 | Component                      | Status   | Tests                |
 | ------------------------------ | -------- | -------------------- |
 | Version Constants              | Complete | Unit tests           |
 | Version Detection Middleware   | Complete | 25 unit tests        |
 | Deprecation Headers Middleware | Complete | 30 unit tests        |
 | Version Router Factory         | Complete | Integration tests    |
 | Server Integration             | Complete | 48 integration tests |
 | Developer Documentation        | Complete | This guide           |
 **Total Tests**: 82 versioning-specific tests (100% passing)
 ---
 ## Table of Contents
 1. [Overview](#overview)
 2. [Architecture](#architecture)
 3. [Key Concepts](#key-concepts)
 4. [Developer Workflows](#developer-workflows)
 5. [Version Headers](#version-headers)
 6. [Testing Versioned Endpoints](#testing-versioned-endpoints)
 7. [Migration Guide: v1 to v2](#migration-guide-v1-to-v2)
 8. [Troubleshooting](#troubleshooting)
 9. [Related Documentation](#related-documentation)
 ---
 ## Overview
 The API uses URI-based versioning with the format `/api/v{MAJOR}/resource`. All endpoints are accessible at versioned paths like `/api/v1/flyers` or `/api/v2/users`.
 ### Current Version Status
 | Version | Status | Description                           |
 | ------- | ------ | ------------------------------------- |
 | v1      | Active | Current production version            |
 | v2      | Active | Future version (infrastructure ready) |
 ### Key Features
 - **Automatic version detection** from URL path
 - **RFC 8594 compliant deprecation headers** when versions are deprecated
 - **Backwards compatibility** via 301 redirects from unversioned paths
 - **Version-aware request context** for conditional logic in handlers
 - **Centralized configuration** for version lifecycle management
 ---
 ## Architecture
 ### Request Flow
 ```text
 Client Request: GET /api/v1/flyers
                    |
                    v
             +------+-------+
             | server.ts    |
             | - Redirect   |
             |   middleware |
             +------+-------+
                    |
                    v
             +------+-------+
             | createApi    |
             | Router()     |
             +------+-------+
                    |
                    v
             +------+-------+
             | detectApi    |
             | Version      |
             | middleware   |
             +------+-------+
                    | req.apiVersion = 'v1'
                    v
             +------+-------+
             | Versioned    |
             | Router       |
             | (v1)         |
             +------+-------+
                    |
                    v
             +------+-------+
             | addDepreca   |
             | tionHeaders  |
             | middleware   |
             +------+-------+
                    | X-API-Version: v1
                    v
             +------+-------+
             | Domain       |
             | Router       |
             | (flyers)     |
             +------+-------+
                    |
                    v
              Response
 ```
 ### Component Overview
 | Component           | File                                       | Purpose                                               |
 | ------------------- | ------------------------------------------ | ----------------------------------------------------- |
 | Version Constants   | `src/config/apiVersions.ts`                | Type definitions, version configs, utility functions  |
 | Version Detection   | `src/middleware/apiVersion.middleware.ts`  | Extract version from URL, validate, attach to request |
 | Deprecation Headers | `src/middleware/deprecation.middleware.ts` | Add RFC 8594 headers for deprecated versions          |
 | Router Factory      | `src/routes/versioned.ts`                  | Create version-specific Express routers               |
 | Type Extensions     | `src/types/express.d.ts`                   | Add `apiVersion` and `versionDeprecation` to Request  |
 ---
 ## Key Concepts
 ### 1. Version Configuration
 All version definitions live in `src/config/apiVersions.ts`:
 ```typescript
 // src/config/apiVersions.ts
 // Supported versions as a const tuple
 export const API_VERSIONS = ['v1', 'v2'] as const;
 // Union type: 'v1' | 'v2'
 export type ApiVersion = (typeof API_VERSIONS)[number];
 // Version lifecycle status
 export type VersionStatus = 'active' | 'deprecated' | 'sunset';
 // Configuration for each version
 export const VERSION_CONFIGS: Record<ApiVersion, VersionConfig> = {
  v1: {
    version: 'v1',
    status: 'active',
  },
  v2: {
    version: 'v2',
    status: 'active',
  },
 };
 ```
 ### 2. Version Detection
 The `detectApiVersion` middleware extracts the version from `req.params.version` and validates it:
 ```typescript
 // How it works (src/middleware/apiVersion.middleware.ts)
 // For valid versions:
 // GET /api/v1/flyers -> req.apiVersion = 'v1'
 // For invalid versions:
 // GET /api/v99/flyers -> 404 with UNSUPPORTED_VERSION error
 ```
 ### 3. Request Context
 After middleware runs, the request object has version information:
 ```typescript
 // In any route handler
 router.get('/flyers', async (req, res) => {
  // Access the detected version
  const version = req.apiVersion; // 'v1' | 'v2'
  // Check deprecation status
  if (req.versionDeprecation?.deprecated) {
    req.log.warn(
      {
        sunset: req.versionDeprecation.sunsetDate,
      },
      'Client using deprecated API',
    );
  }
  // Version-specific behavior
  if (req.apiVersion === 'v2') {
    return sendSuccess(res, transformV2(data));
  }
  return sendSuccess(res, data);
 });
 ```
 ### 4. Route Registration
 Routes are registered in `src/routes/versioned.ts` with version availability:
 ```typescript
 // src/routes/versioned.ts
 export const ROUTES: RouteRegistration[] = [
  {
    path: 'auth',
    router: authRouter,
    description: 'Authentication routes',
    // Available in all versions (no versions array)
  },
  {
    path: 'flyers',
    router: flyerRouter,
    description: 'Flyer management',
    // Available in all versions
  },
  {
    path: 'new-feature',
    router: newFeatureRouter,
    description: 'New feature only in v2',
    versions: ['v2'], // Only available in v2
  },
 ];
 ```
 ---
 ## Developer Workflows
 ### Adding a New API Version (e.g., v3)
 **Step 1**: Add version to constants (`src/config/apiVersions.ts`)
 ```typescript
 // Before
 export const API_VERSIONS = ['v1', 'v2'] as const;
 // After
 export const API_VERSIONS = ['v1', 'v2', 'v3'] as const;
 // Add configuration
 export const VERSION_CONFIGS: Record<ApiVersion, VersionConfig> = {
  v1: { version: 'v1', status: 'active' },
  v2: { version: 'v2', status: 'active' },
  v3: { version: 'v3', status: 'active' }, // NEW
 };
 ```
 **Step 2**: Router cache auto-updates (no changes needed)
 The versioned router cache in `src/routes/versioned.ts` automatically creates routers for all versions defined in `API_VERSIONS`.
 **Step 3**: Update OpenAPI documentation (`src/config/swagger.ts`)
 ```typescript
 servers: [
  { url: '/api/v1', description: 'API v1' },
  { url: '/api/v2', description: 'API v2' },
  { url: '/api/v3', description: 'API v3 (New)' },  // NEW
 ],
 ```
 **Step 4**: Test the new version
 ```bash
 # In dev container
 podman exec -it flyer-crawler-dev npm test
 # Manual verification
 curl -i http://localhost:3001/api/v3/health
 # Should return 200 with X-API-Version: v3 header
 ```
 ### Marking a Version as Deprecated
 **Step 1**: Update version config (`src/config/apiVersions.ts`)
 ```typescript
 export const VERSION_CONFIGS: Record<ApiVersion, VersionConfig> = {
  v1: {
    version: 'v1',
    status: 'deprecated', // Changed from 'active'
    sunsetDate: '2027-01-01T00:00:00Z', // When it will be removed
    successorVersion: 'v2', // Migration target
  },
  v2: {
    version: 'v2',
    status: 'active',
  },
 };
 ```
 **Step 2**: Verify deprecation headers
 ```bash
 curl -I http://localhost:3001/api/v1/health
 # Expected headers:
 # X-API-Version: v1
 # Deprecation: true
 # Sunset: 2027-01-01T00:00:00Z
 # Link: </api/v2>; rel="successor-version"
 # X-API-Deprecation-Notice: API v1 is deprecated and will be sunset...
 ```
 **Step 3**: Monitor deprecation usage
 Check logs for `Deprecated API version accessed` messages with context about which clients are still using deprecated versions.
 ### Adding Version-Specific Routes
 **Scenario**: Add a new endpoint only available in v2+
 **Step 1**: Create the route handler (new or existing file)
 ```typescript
 // src/routes/newFeature.routes.ts
 import { Router } from 'express';
 import { sendSuccess } from '../utils/apiResponse';
 const router = Router();
 router.get('/', async (req, res) => {
  // This endpoint only exists in v2+
  sendSuccess(res, { feature: 'new-feature-data' });
 });
 export default router;
 ```
 **Step 2**: Register with version restriction (`src/routes/versioned.ts`)
 ```typescript
 import newFeatureRouter from './newFeature.routes';
 export const ROUTES: RouteRegistration[] = [
  // ... existing routes ...
  {
    path: 'new-feature',
    router: newFeatureRouter,
    description: 'New feature only available in v2+',
    versions: ['v2'], // Not available in v1
  },
 ];
 ```
 **Step 3**: Verify route availability
 ```bash
 # v1 - should return 404
 curl -i http://localhost:3001/api/v1/new-feature
 # HTTP/1.1 404 Not Found
 # v2 - should work
 curl -i http://localhost:3001/api/v2/new-feature
 # HTTP/1.1 200 OK
 # X-API-Version: v2
 ```
 ### Adding Version-Specific Behavior in Existing Routes
 For routes that exist in multiple versions but behave differently:
 ```typescript
 // src/routes/flyer.routes.ts
 router.get('/:id', async (req, res) => {
  const flyer = await flyerService.getFlyer(req.params.id, req.log);
  // Different response format per version
  if (req.apiVersion === 'v2') {
    // v2 returns expanded store data
    return sendSuccess(res, {
      ...flyer,
      store: await storeService.getStore(flyer.store_id, req.log),
    });
  }
  // v1 returns just the flyer
  return sendSuccess(res, flyer);
 });
 ```
 ---
 ## Version Headers
 ### Response Headers
 All versioned API responses include these headers:
 | Header                     | Always Present     | Description                                             |
 | -------------------------- | ------------------ | ------------------------------------------------------- |
 | `X-API-Version`            | Yes                | The API version handling the request                    |
 | `Deprecation`              | Only if deprecated | `true` when version is deprecated                       |
 | `Sunset`                   | Only if configured | ISO 8601 date when version will be removed              |
 | `Link`                     | Only if configured | URL to successor version with `rel="successor-version"` |
 | `X-API-Deprecation-Notice` | Only if deprecated | Human-readable deprecation message                      |
 ### Example: Active Version Response
 ```http
 HTTP/1.1 200 OK
 X-API-Version: v2
 Content-Type: application/json
 ```
 ### Example: Deprecated Version Response
 ```http
 HTTP/1.1 200 OK
 X-API-Version: v1
 Deprecation: true
 Sunset: 2027-01-01T00:00:00Z
 Link: </api/v2>; rel="successor-version"
 X-API-Deprecation-Notice: API v1 is deprecated and will be sunset on 2027-01-01T00:00:00Z. Please migrate to v2.
 Content-Type: application/json
 ```
 ### RFC Compliance
 The deprecation headers follow these standards:
 - **RFC 8594**: The "Sunset" HTTP Header Field
 - **draft-ietf-httpapi-deprecation-header**: The "Deprecation" HTTP Header Field
 - **RFC 8288**: Web Linking (for `rel="successor-version"`)
 ---
 ## Testing Versioned Endpoints
 ### Unit Testing Middleware
 See test files for patterns:
 - `src/middleware/apiVersion.middleware.test.ts`
 - `src/middleware/deprecation.middleware.test.ts`
 **Testing version detection**:
 ```typescript
 // src/middleware/apiVersion.middleware.test.ts
 import { detectApiVersion } from './apiVersion.middleware';
 import { createMockRequest } from '../tests/utils/createMockRequest';
 describe('detectApiVersion', () => {
  it('should extract v1 from req.params.version', () => {
    const mockRequest = createMockRequest({
      params: { version: 'v1' },
    });
    const mockResponse = { status: vi.fn().mockReturnThis(), json: vi.fn() };
    const mockNext = vi.fn();
    detectApiVersion(mockRequest, mockResponse, mockNext);
    expect(mockRequest.apiVersion).toBe('v1');
    expect(mockNext).toHaveBeenCalled();
  });
  it('should return 404 for invalid version', () => {
    const mockRequest = createMockRequest({
      params: { version: 'v99' },
    });
    const mockResponse = {
      status: vi.fn().mockReturnThis(),
      json: vi.fn(),
    };
    const mockNext = vi.fn();
    detectApiVersion(mockRequest, mockResponse, mockNext);
    expect(mockNext).not.toHaveBeenCalled();
    expect(mockResponse.status).toHaveBeenCalledWith(404);
  });
 });
 ```
 **Testing deprecation headers**:
 ```typescript
 // src/middleware/deprecation.middleware.test.ts
 import { addDeprecationHeaders } from './deprecation.middleware';
 import { VERSION_CONFIGS } from '../config/apiVersions';
 describe('addDeprecationHeaders', () => {
  beforeEach(() => {
    // Mark v1 as deprecated for test
    VERSION_CONFIGS.v1 = {
      version: 'v1',
      status: 'deprecated',
      sunsetDate: '2027-01-01T00:00:00Z',
      successorVersion: 'v2',
    };
  });
  it('should add all deprecation headers', () => {
    const setHeader = vi.fn();
    const middleware = addDeprecationHeaders('v1');
    middleware(mockRequest, { set: setHeader }, mockNext);
    expect(setHeader).toHaveBeenCalledWith('Deprecation', 'true');
    expect(setHeader).toHaveBeenCalledWith('Sunset', '2027-01-01T00:00:00Z');
    expect(setHeader).toHaveBeenCalledWith('Link', '</api/v2>; rel="successor-version"');
  });
 });
 ```
 ### Integration Testing
 **Test versioned endpoints**:
 ```typescript
 import request from 'supertest';
 import app from '../../server';
 describe('API Versioning Integration', () => {
  it('should return X-API-Version header for v1', async () => {
    const response = await request(app).get('/api/v1/health').expect(200);
    expect(response.headers['x-api-version']).toBe('v1');
  });
  it('should return 404 for unsupported version', async () => {
    const response = await request(app).get('/api/v99/health').expect(404);
    expect(response.body.error.code).toBe('UNSUPPORTED_VERSION');
  });
  it('should redirect unversioned paths to v1', async () => {
    const response = await request(app).get('/api/health').expect(301);
    expect(response.headers.location).toBe('/api/v1/health');
  });
 });
 ```
 ### Running Tests
 ```bash
 # Run all tests in container (required)
 podman exec -it flyer-crawler-dev npm test
 # Run only middleware tests
 podman exec -it flyer-crawler-dev npm test -- apiVersion
 podman exec -it flyer-crawler-dev npm test -- deprecation
 # Type check
 podman exec -it flyer-crawler-dev npm run type-check
 ```
 ---
 ## Migration Guide: v1 to v2
 When v2 is introduced with breaking changes, follow this migration process.
 ### For API Consumers (Frontend/Mobile)
 **Step 1**: Check current API version usage
 ```typescript
 // Frontend apiClient.ts
 const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api/v1';
 ```
 **Step 2**: Monitor deprecation headers
 When v1 is deprecated, responses will include:
 ```http
 Deprecation: true
 Sunset: 2027-01-01T00:00:00Z
 Link: </api/v2>; rel="successor-version"
 ```
 **Step 3**: Update to v2
 ```typescript
 // Change API base URL
 const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api/v2';
 ```
 **Step 4**: Handle response format changes
 If v2 changes response formats, update your type definitions and parsing logic:
 ```typescript
 // v1 response
 interface FlyerResponseV1 {
  id: number;
  store_id: number;
 }
 // v2 response (example: includes embedded store)
 interface FlyerResponseV2 {
  id: string; // Changed to UUID
  store: {
    id: string;
    name: string;
  };
 }
 ```
 ### For Backend Developers
 **Step 1**: Create v2-specific handlers (if needed)
 For breaking changes, create version-specific route files:
 ```text
 src/routes/
  flyer.routes.ts      # Shared/v1 handlers
  flyer.v2.routes.ts   # v2-specific handlers (if significantly different)
 ```
 **Step 2**: Register version-specific routes
 ```typescript
 // src/routes/versioned.ts
 export const ROUTES: RouteRegistration[] = [
  {
    path: 'flyers',
    router: flyerRouter,
    description: 'Flyer routes (v1)',
    versions: ['v1'],
  },
  {
    path: 'flyers',
    router: flyerRouterV2,
    description: 'Flyer routes (v2 with breaking changes)',
    versions: ['v2'],
  },
 ];
 ```
 **Step 3**: Document changes
 Update OpenAPI documentation to reflect v2 changes and mark v1 as deprecated.
 ### Timeline Example
 | Date       | Action                                     |
 | ---------- | ------------------------------------------ |
 | T+0        | v2 released, v1 marked deprecated          |
 | T+0        | Deprecation headers added to v1 responses  |
 | T+30 days  | Sunset warning emails to known integrators |
 | T+90 days  | v1 returns 410 Gone                        |
 | T+120 days | v1 code removed                            |
 ---
 ## Troubleshooting
 ### Issue: "UNSUPPORTED_VERSION" Error
 **Symptom**: Request to `/api/v3/...` returns 404 with `UNSUPPORTED_VERSION`
 **Cause**: Version `v3` is not defined in `API_VERSIONS`
 **Solution**: Add the version to `src/config/apiVersions.ts`:
 ```typescript
 export const API_VERSIONS = ['v1', 'v2', 'v3'] as const;
 export const VERSION_CONFIGS = {
  // ...
  v3: { version: 'v3', status: 'active' },
 };
 ```
 ### Issue: Missing X-API-Version Header
 **Symptom**: Response doesn't include `X-API-Version` header
 **Cause**: Request didn't go through versioned router
 **Solution**: Ensure the route is registered in `src/routes/versioned.ts` and mounted under `/api/:version`
 ### Issue: Deprecation Headers Not Appearing
 **Symptom**: Deprecated version works but no deprecation headers
 **Cause**: Version status not set to `'deprecated'` in config
 **Solution**: Update `VERSION_CONFIGS`:
 ```typescript
 v1: {
  version: 'v1',
  status: 'deprecated',  // Must be 'deprecated', not 'active'
  sunsetDate: '2027-01-01T00:00:00Z',
  successorVersion: 'v2',
 },
 ```
 ### Issue: Route Available in Wrong Version
 **Symptom**: Route works in v1 but should only be in v2
 **Cause**: Missing `versions` restriction in route registration
 **Solution**: Add `versions` array:
 ```typescript
 {
  path: 'new-feature',
  router: newFeatureRouter,
  versions: ['v2'],  // Add this to restrict availability
 },
 ```
 ### Issue: Unversioned Paths Not Redirecting
 **Symptom**: `/api/flyers` returns 404 instead of redirecting to `/api/v1/flyers`
 **Cause**: Redirect middleware order issue in `server.ts`
 **Solution**: Ensure redirect middleware is mounted BEFORE `createApiRouter()`:
 ```typescript
 // server.ts - correct order
 app.use('/api', redirectMiddleware); // First
 app.use('/api', createApiRouter()); // Second
 ```
 ### Issue: TypeScript Errors on req.apiVersion
 **Symptom**: `Property 'apiVersion' does not exist on type 'Request'`
 **Cause**: Type extensions not being picked up
 **Solution**: Ensure `src/types/express.d.ts` is included in tsconfig:
 ```json
 {
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./src/types"]
  },
  "include": ["src/**/*"]
 }
 ```
 ### Issue: Router Cache Stale After Config Change
 **Symptom**: Version behavior doesn't update after changing `VERSION_CONFIGS`
 **Cause**: Routers are cached at startup
 **Solution**: Use `refreshRouterCache()` or restart the server:
 ```typescript
 import { refreshRouterCache } from './src/routes/versioned';
 // After config changes
 refreshRouterCache();
 ```
 ---
 ## Related Documentation
 ### Architecture Decision Records
 | ADR                                                                      | Title                        |
 | ------------------------------------------------------------------------ | ---------------------------- |
 | [ADR-008](../adr/0008-api-versioning-strategy.md)                        | API Versioning Strategy      |
 | [ADR-003](../adr/0003-standardized-input-validation-using-middleware.md) | Input Validation             |
 | [ADR-028](../adr/0028-api-response-standardization.md)                   | API Response Standardization |
 | [ADR-018](../adr/0018-api-documentation-strategy.md)                     | API Documentation Strategy   |
 ### Implementation Files
 | File                                                                                         | Description                  |
 | -------------------------------------------------------------------------------------------- | ---------------------------- |
 | [`src/config/apiVersions.ts`](../../src/config/apiVersions.ts)                               | Version constants and config |
 | [`src/middleware/apiVersion.middleware.ts`](../../src/middleware/apiVersion.middleware.ts)   | Version detection            |
 | [`src/middleware/deprecation.middleware.ts`](../../src/middleware/deprecation.middleware.ts) | Deprecation headers          |
 | [`src/routes/versioned.ts`](../../src/routes/versioned.ts)                                   | Router factory               |
 | [`src/types/express.d.ts`](../../src/types/express.d.ts)                                     | Request type extensions      |
 | [`server.ts`](../../server.ts)                                                               | Application entry point      |
 ### Test Files
 | File                                                                                                   | Description              |
 | ------------------------------------------------------------------------------------------------------ | ------------------------ |
 | [`src/middleware/apiVersion.middleware.test.ts`](../../src/middleware/apiVersion.middleware.test.ts)   | Version detection tests  |
 | [`src/middleware/deprecation.middleware.test.ts`](../../src/middleware/deprecation.middleware.test.ts) | Deprecation header tests |
 ### External References
 - [RFC 8594: The "Sunset" HTTP Header Field](https://datatracker.ietf.org/doc/html/rfc8594)
 - [draft-ietf-httpapi-deprecation-header](https://datatracker.ietf.org/doc/draft-ietf-httpapi-deprecation-header/)
 - [RFC 8288: Web Linking](https://datatracker.ietf.org/doc/html/rfc8288)
 ---
 ## Quick Reference
 ### Files to Modify for Common Tasks
 | Task                           | Files                                                |
 | ------------------------------ | ---------------------------------------------------- |
 | Add new version                | `src/config/apiVersions.ts`, `src/config/swagger.ts` |
 | Deprecate version              | `src/config/apiVersions.ts`                          |
 | Add version-specific route     | `src/routes/versioned.ts`                            |
 | Version-specific handler logic | Route file (e.g., `src/routes/flyer.routes.ts`)      |
 ### Key Functions
 ```typescript
 // Check if version is valid
 isValidApiVersion('v1'); // true
 isValidApiVersion('v99'); // false
 // Get version from request with fallback
 getRequestApiVersion(req); // Returns 'v1' | 'v2'
 // Check if request has valid version
 hasApiVersion(req); // boolean
 // Get deprecation info
 getVersionDeprecation('v1'); // { deprecated: false, ... }
 ```
 ### Commands
 ```bash
 # Run all tests
 podman exec -it flyer-crawler-dev npm test
 # Type check
 podman exec -it flyer-crawler-dev npm run type-check
 # Check version headers manually
 curl -I http://localhost:3001/api/v1/health
 # Test deprecation (after marking v1 deprecated)
 curl -I http://localhost:3001/api/v1/health | grep -E "(Deprecation|Sunset|Link|X-API)"
 ```
 curl -I http://localhost:3001/api/v1/health | grep -E "(Deprecation|Sunset|Link|X-API)"
 ```
--- a/docs/development/test-path-migration.md
+++ b/docs/development/test-path-migration.md
@@ -0,0 +1,272 @@
 # Test Path Migration: Unversioned to Versioned API Paths
 **Status**: Complete
 **Created**: 2026-01-27
 **Completed**: 2026-01-27
 **Related**: ADR-008 (API Versioning Strategy)
 ## Summary
 All integration test files have been successfully migrated to use versioned API paths (`/api/v1/`). This resolves the redirect-related test failures introduced by ADR-008 Phase 1.
 ### Results
 | Metric                    | Value                                    |
 | ------------------------- | ---------------------------------------- |
 | Test files updated        | 23                                       |
 | Path occurrences changed  | ~70                                      |
 | Tests before migration    | 274/348 passing                          |
 | Tests after migration     | 345/348 passing                          |
 | Test failures resolved    | 71                                       |
 | Remaining todo/skipped    | 3 (known issues, not versioning-related) |
 | Type check                | Passing                                  |
 | Versioning-specific tests | 82/82 passing                            |
 ### Key Outcomes
 - No `301 Moved Permanently` responses in test output
 - All redirect-related failures resolved
 - No regressions introduced
 - Unit tests unaffected (3,375/3,391 passing, pre-existing failures)
 ---
 ## Original Problem Statement
 Integration tests failed due to redirect middleware (ADR-008 Phase 1). Server returned `301 Moved Permanently` for unversioned paths (`/api/resource`) instead of expected `200 OK`. Redirect targets versioned paths (`/api/v1/resource`).
 **Root Cause**: Backwards-compatibility redirect in `server.ts`:
 ```typescript
 app.use('/api', (req, res, next) => {
  const versionPattern = /^\/v\d+/;
  if (!versionPattern.test(req.path)) {
    return res.redirect(301, `/api/v1${req.path}`);
  }
  next();
 });
 ```
 **Impact**: ~70 test path occurrences across 23 files returning 301 instead of expected status codes.
 ## Solution
 Update all test API paths from `/api/{resource}` to `/api/v1/{resource}`.
 ## Files Requiring Updates
 ### Integration Tests (16 files)
 | File                                                         | Occurrences | Domains                |
 | ------------------------------------------------------------ | ----------- | ---------------------- |
 | `src/tests/integration/inventory.integration.test.ts`        | 14          | inventory              |
 | `src/tests/integration/receipt.integration.test.ts`          | 17          | receipts               |
 | `src/tests/integration/recipe.integration.test.ts`           | 17          | recipes, users/recipes |
 | `src/tests/integration/user.routes.integration.test.ts`      | 10          | users/shopping-lists   |
 | `src/tests/integration/admin.integration.test.ts`            | 7           | admin                  |
 | `src/tests/integration/flyer-processing.integration.test.ts` | 6           | ai/jobs                |
 | `src/tests/integration/budget.integration.test.ts`           | 5           | budgets                |
 | `src/tests/integration/notification.integration.test.ts`     | 3           | users/notifications    |
 | `src/tests/integration/data-integrity.integration.test.ts`   | 3           | users, admin           |
 | `src/tests/integration/upc.integration.test.ts`              | 3           | upc                    |
 | `src/tests/integration/edge-cases.integration.test.ts`       | 3           | users/shopping-lists   |
 | `src/tests/integration/user.integration.test.ts`             | 2           | users                  |
 | `src/tests/integration/public.routes.integration.test.ts`    | 2           | flyers, recipes        |
 | `src/tests/integration/flyer.integration.test.ts`            | 1           | flyers                 |
 | `src/tests/integration/category.routes.test.ts`              | 1           | categories             |
 | `src/tests/integration/gamification.integration.test.ts`     | 1           | ai/jobs                |
 ### E2E Tests (7 files)
 | File                                          | Occurrences | Domains              |
 | --------------------------------------------- | ----------- | -------------------- |
 | `src/tests/e2e/inventory-journey.e2e.test.ts` | 9           | inventory            |
 | `src/tests/e2e/receipt-journey.e2e.test.ts`   | 9           | receipts             |
 | `src/tests/e2e/budget-journey.e2e.test.ts`    | 6           | budgets              |
 | `src/tests/e2e/upc-journey.e2e.test.ts`       | 3           | upc                  |
 | `src/tests/e2e/deals-journey.e2e.test.ts`     | 2           | categories, users    |
 | `src/tests/e2e/user-journey.e2e.test.ts`      | 1           | users/shopping-lists |
 | `src/tests/e2e/flyer-upload.e2e.test.ts`      | 1           | jobs                 |
 ## Update Pattern
 ### Find/Replace Rules
 **Template literals** (most common):
 ```
 OLD: .get(`/api/resource/${id}`)
 NEW: .get(`/api/v1/resource/${id}`)
 ```
 **String literals**:
 ```
 OLD: .get('/api/resource')
 NEW: .get('/api/v1/resource')
 ```
 ### Regex Pattern for Batch Updates
 ```regex
 Find:    (\.(get|post|put|delete|patch)\([`'"])/api/([a-z])
 Replace: $1/api/v1/$3
 ```
 **Explanation**: Captures HTTP method call, inserts `/v1/` after `/api/`.
 ## Files to EXCLUDE
 These files intentionally test unversioned path behavior:
 | File                                                 | Reason                               |
 | ---------------------------------------------------- | ------------------------------------ |
 | `src/routes/versioning.integration.test.ts`          | Tests redirect behavior itself       |
 | `src/services/apiClient.test.ts`                     | Mock server URLs, not real API calls |
 | `src/services/aiApiClient.test.ts`                   | Mock server URLs for MSW handlers    |
 | `src/services/googleGeocodingService.server.test.ts` | External Google API URL              |
 **Also exclude** (not API paths):
 - Lines containing `vi.mock('@bull-board/api` (import mocks)
 - Lines containing `/api/v99` (intentional unsupported version tests)
 - `describe()` and `it()` block descriptions
 - Comment lines (`// `)
 ## Execution Batches
 ### Batch 1: High-Impact Integration (4 files, ~58 occurrences)
 ```bash
 # Files with most occurrences
 src/tests/integration/inventory.integration.test.ts
 src/tests/integration/receipt.integration.test.ts
 src/tests/integration/recipe.integration.test.ts
 src/tests/integration/user.routes.integration.test.ts
 ```
 ### Batch 2: Medium Integration (6 files, ~27 occurrences)
 ```bash
 src/tests/integration/admin.integration.test.ts
 src/tests/integration/flyer-processing.integration.test.ts
 src/tests/integration/budget.integration.test.ts
 src/tests/integration/notification.integration.test.ts
 src/tests/integration/data-integrity.integration.test.ts
 src/tests/integration/upc.integration.test.ts
 ```
 ### Batch 3: Low Integration (6 files, ~10 occurrences)
 ```bash
 src/tests/integration/edge-cases.integration.test.ts
 src/tests/integration/user.integration.test.ts
 src/tests/integration/public.routes.integration.test.ts
 src/tests/integration/flyer.integration.test.ts
 src/tests/integration/category.routes.test.ts
 src/tests/integration/gamification.integration.test.ts
 ```
 ### Batch 4: E2E Tests (7 files, ~31 occurrences)
 ```bash
 src/tests/e2e/inventory-journey.e2e.test.ts
 src/tests/e2e/receipt-journey.e2e.test.ts
 src/tests/e2e/budget-journey.e2e.test.ts
 src/tests/e2e/upc-journey.e2e.test.ts
 src/tests/e2e/deals-journey.e2e.test.ts
 src/tests/e2e/user-journey.e2e.test.ts
 src/tests/e2e/flyer-upload.e2e.test.ts
 ```
 ## Verification Strategy
 ### Per-Batch Verification
 After each batch:
 ```bash
 # Type check
 podman exec -it flyer-crawler-dev npm run type-check
 # Run specific test file
 podman exec -it flyer-crawler-dev npx vitest run <file-path> --reporter=verbose
 ```
 ### Full Verification
 After all batches:
 ```bash
 # Full integration test suite
 podman exec -it flyer-crawler-dev npm run test:integration
 # Full E2E test suite
 podman exec -it flyer-crawler-dev npm run test:e2e
 ```
 ### Success Criteria
 - [x] No `301 Moved Permanently` responses in test output
 - [x] All tests pass or fail for expected reasons (not redirect-related)
 - [x] Type check passes
 - [x] No regressions in unmodified tests
 ## Edge Cases
 ### Describe Block Text
 Do NOT modify describe/it block descriptions:
 ```typescript
 // KEEP AS-IS (documentation only):
 describe('GET /api/users/profile', () => { ... });
 // UPDATE (actual API call):
 const response = await request.get('/api/v1/users/profile');
 ```
 ### Console Logging
 Do NOT modify debug/error logging paths:
 ```typescript
 // KEEP AS-IS:
 console.error('[DEBUG] GET /api/admin/stats failed:', ...);
 ```
 ### Query Parameters
 Include query parameters in update:
 ```typescript
 // OLD:
 .get(`/api/budgets/spending-analysis?startDate=${start}&endDate=${end}`)
 // NEW:
 .get(`/api/v1/budgets/spending-analysis?startDate=${start}&endDate=${end}`)
 ```
 ## Post-Completion Checklist
 - [x] All 23 files updated
 - [x] ~70 path occurrences migrated
 - [x] Exclusion files unchanged
 - [x] Type check passes
 - [x] Integration tests pass (345/348)
 - [x] E2E tests pass
 - [x] Commit with message: `fix(tests): Update API paths to use /api/v1/ prefix (ADR-008)`
 ## Rollback
 If issues arise:
 ```bash
 git checkout HEAD -- src/tests/
 ```
 ## Related Documentation
 - ADR-008: API Versioning Strategy
 - `docs/architecture/api-versioning-infrastructure.md`
 - `src/routes/versioning.integration.test.ts` (reference for expected behavior)
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
  "name": "flyer-crawler",
-  "version": "0.12.16",
+  "version": "0.12.17",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "flyer-crawler",
-      "version": "0.12.16",
+      "version": "0.12.17",
      "dependencies": {
        "@bull-board/api": "^6.14.2",
        "@bull-board/express": "^6.14.2",
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
  "name": "flyer-crawler",
  "private": true,
-  "version": "0.12.16",
+  "version": "0.12.17",
  "type": "module",
  "scripts": {
    "dev": "concurrently \"npm:start:dev\" \"vite\"",
--- a/server.ts
+++ b/server.ts
@@ -18,27 +18,8 @@ import { getPool } from './src/services/db/connection.db';
 import passport from './src/config/passport';
 import { logger } from './src/services/logger.server';
-// Import routers
+// Import the versioned API router factory (ADR-008 Phase 2)
-import authRouter from './src/routes/auth.routes';
+import { createApiRouter } from './src/routes/versioned';
 import userRouter from './src/routes/user.routes';
 import adminRouter from './src/routes/admin.routes';
 import aiRouter from './src/routes/ai.routes';
 import budgetRouter from './src/routes/budget.routes';
 import flyerRouter from './src/routes/flyer.routes';
 import recipeRouter from './src/routes/recipe.routes';
 import personalizationRouter from './src/routes/personalization.routes';
 import priceRouter from './src/routes/price.routes';
 import statsRouter from './src/routes/stats.routes';
 import gamificationRouter from './src/routes/gamification.routes';
 import systemRouter from './src/routes/system.routes';
 import healthRouter from './src/routes/health.routes';
 import upcRouter from './src/routes/upc.routes';
 import inventoryRouter from './src/routes/inventory.routes';
 import receiptRouter from './src/routes/receipt.routes';
 import dealsRouter from './src/routes/deals.routes';
 import reactionsRouter from './src/routes/reactions.routes';
 import storeRouter from './src/routes/store.routes';
 import categoryRouter from './src/routes/category.routes';
 import { errorHandler } from './src/middleware/errorHandler';
 import { backgroundJobService, startBackgroundJobs } from './src/services/backgroundJobService';
 import { websocketService } from './src/services/websocketService.server';
@@ -249,56 +230,20 @@ app.get('/api/v1/health/queues', async (req, res) => {
  }
 });
 // The order of route registration is critical.
 // More specific routes should be registered before more general ones.
 // All routes are now versioned under /api/v1 as per ADR-008.
 // 1. Authentication routes for login, registration, etc.
 app.use('/api/v1/auth', authRouter);
 // 2. System routes for health checks, etc.
 app.use('/api/v1/health', healthRouter);
 // 3. System routes for pm2 status, etc.
 app.use('/api/v1/system', systemRouter);
 // 3. General authenticated user routes.
 app.use('/api/v1/users', userRouter);
 // 4. AI routes, some of which use optional authentication.
 app.use('/api/v1/ai', aiRouter);
 // 5. Admin routes, which are all protected by admin-level checks.
 app.use('/api/v1/admin', adminRouter);
 // 6. Budgeting and spending analysis routes.
 app.use('/api/v1/budgets', budgetRouter);
 // 7. Gamification routes for achievements.
 app.use('/api/v1/achievements', gamificationRouter);
 // 8. Public flyer routes.
 app.use('/api/v1/flyers', flyerRouter);
 // 8. Public recipe routes.
 app.use('/api/v1/recipes', recipeRouter);
 // 9. Public personalization data routes (master items, etc.).
 app.use('/api/v1/personalization', personalizationRouter);
 // 9.5. Price history routes.
 app.use('/api/v1/price-history', priceRouter);
 // 10. Public statistics routes.
 app.use('/api/v1/stats', statsRouter);
 // 11. UPC barcode scanning routes.
 app.use('/api/v1/upc', upcRouter);
 // 12. Inventory and expiry tracking routes.
 app.use('/api/v1/inventory', inventoryRouter);
 // 13. Receipt scanning routes.
 app.use('/api/v1/receipts', receiptRouter);
 // 14. Deals and best prices routes.
 app.use('/api/v1/deals', dealsRouter);
 // 15. Reactions/social features routes.
 app.use('/api/v1/reactions', reactionsRouter);
 // 16. Store management routes.
 app.use('/api/v1/stores', storeRouter);
 // 17. Category discovery routes (ADR-023: Database Normalization)
 app.use('/api/v1/categories', categoryRouter);
 // --- Backwards Compatibility Redirect (ADR-008: API Versioning Strategy) ---
 // Redirect old /api/* paths to /api/v1/* for backwards compatibility.
 // This allows clients to gradually migrate to the versioned API.
 // IMPORTANT: This middleware MUST be mounted BEFORE createApiRouter() so that
 // unversioned paths like /api/users are redirected to /api/v1/users BEFORE
 // the versioned router's detectApiVersion middleware rejects them as invalid versions.
 app.use('/api', (req, res, next) => {
-  // Only redirect if the path does NOT already start with /v1
+  // Check if the path starts with a version-like prefix (/v followed by digits).
-  if (!req.path.startsWith('/v1')) {
+  // This includes both supported versions (v1, v2) and unsupported ones (v99).
  // Unsupported versions will be handled by detectApiVersion middleware which returns 404.
  // This redirect only handles legacy unversioned paths like /api/users -> /api/v1/users.
  const versionPattern = /^\/v\d+/;
  const startsWithVersionPattern = versionPattern.test(req.path);
  if (!startsWithVersionPattern) {
    const newPath = `/api/v1${req.path}`;
    logger.info({ oldPath: `/api${req.path}`, newPath }, 'Redirecting to versioned API');
    return res.redirect(301, newPath);
@@ -306,6 +251,16 @@ app.use('/api', (req, res, next) => {
  next();
 });
 // Mount the versioned API router (ADR-008 Phase 2).
 // The createApiRouter() factory handles:
 // - Version detection and validation via detectApiVersion middleware
 // - Route registration in correct precedence order
 // - Version-specific route availability
 // - Deprecation headers via addDeprecationHeaders middleware
 // - X-API-Version response headers
 // All domain routers are registered in versioned.ts with proper ordering.
 app.use('/api', createApiRouter());
 // --- Error Handling and Server Startup ---
 // Catch-all 404 handler for unmatched routes.
--- a/src/config/apiVersions.ts
+++ b/src/config/apiVersions.ts
@@ -0,0 +1,183 @@
 // src/config/apiVersions.ts
 /**
 * @file API version constants, types, and configuration.
 * Implements ADR-008 Phase 2: API Versioning Infrastructure.
 *
 * This module provides centralized version definitions used by:
 * - Version detection middleware (apiVersion.middleware.ts)
 * - Deprecation headers middleware (deprecation.middleware.ts)
 * - Versioned router factory (versioned.ts)
 *
 * @see docs/architecture/api-versioning-infrastructure.md
 *
 * @example
 * ```typescript
 * import {
 *   CURRENT_API_VERSION,
 *   VERSION_CONFIGS,
 *   isValidApiVersion,
 * } from './apiVersions';
 *
 * // Check if a version is supported
 * if (isValidApiVersion('v1')) {
 *   const config = VERSION_CONFIGS.v1;
 *   console.log(`v1 status: ${config.status}`);
 * }
 * ```
 */
 // --- Type Definitions ---
 /**
 * All API versions as a const tuple for type derivation.
 * Add new versions here when introducing them.
 */
 export const API_VERSIONS = ['v1', 'v2'] as const;
 /**
 * Union type of supported API versions.
 * Currently: 'v1' | 'v2'
 */
 export type ApiVersion = (typeof API_VERSIONS)[number];
 /**
 * Version lifecycle status.
 * - 'active': Version is fully supported and recommended
 * - 'deprecated': Version works but clients should migrate (deprecation headers sent)
 * - 'sunset': Version is scheduled for removal or already removed
 */
 export type VersionStatus = 'active' | 'deprecated' | 'sunset';
 /**
 * Deprecation information for an API version.
 * Follows RFC 8594 (Sunset Header) and draft-ietf-httpapi-deprecation-header.
 *
 * Used by deprecation middleware to set appropriate HTTP headers:
 * - `Deprecation: true` (draft-ietf-httpapi-deprecation-header)
 * - `Sunset: <date>` (RFC 8594)
 * - `Link: <url>; rel="successor-version"` (RFC 8288)
 */
 export interface VersionDeprecation {
  /** Indicates if this version is deprecated (maps to Deprecation header) */
  deprecated: boolean;
  /** ISO 8601 date string when the version will be sunset (maps to Sunset header) */
  sunsetDate?: string;
  /** The version clients should migrate to (maps to Link rel="successor-version") */
  successorVersion?: ApiVersion;
  /** Human-readable message explaining the deprecation (for documentation/logs) */
  message?: string;
 }
 /**
 * Complete configuration for an API version.
 * Combines version identifier, lifecycle status, and deprecation details.
 */
 export interface VersionConfig {
  /** The version identifier (e.g., 'v1') */
  version: ApiVersion;
  /** Current lifecycle status of this version */
  status: VersionStatus;
  /** ISO 8601 date when the version will be sunset (RFC 8594) - convenience field */
  sunsetDate?: string;
  /** The version clients should migrate to - convenience field */
  successorVersion?: ApiVersion;
 }
 // --- Constants ---
 /**
 * The current/latest stable API version.
 * New clients should use this version.
 */
 export const CURRENT_API_VERSION: ApiVersion = 'v1';
 /**
 * The default API version for requests without explicit version.
 * Used when version cannot be detected from the request path.
 */
 export const DEFAULT_VERSION: ApiVersion = 'v1';
 /**
 * Array of all supported API versions.
 * Used for validation and enumeration.
 */
 export const SUPPORTED_VERSIONS: readonly ApiVersion[] = API_VERSIONS;
 /**
 * Configuration map for all API versions.
 * Provides lifecycle status and deprecation information for each version.
 *
 * To mark v1 as deprecated (example for future use):
 * @example
 * ```typescript
 * VERSION_CONFIGS.v1 = {
 *   version: 'v1',
 *   status: 'deprecated',
 *   sunsetDate: '2027-01-01T00:00:00Z',
 *   successorVersion: 'v2',
 * };
 * ```
 */
 export const VERSION_CONFIGS: Record<ApiVersion, VersionConfig> = {
  v1: {
    version: 'v1',
    status: 'active',
    // No deprecation info - v1 is the current active version
  },
  v2: {
    version: 'v2',
    status: 'active',
    // v2 is defined for infrastructure readiness but not yet implemented
  },
 };
 // --- Utility Functions ---
 /**
 * Type guard to check if a string is a valid ApiVersion.
 *
 * @param value - The string to check
 * @returns True if the string is a valid API version
 *
 * @example
 * ```typescript
 * const userInput = 'v1';
 * if (isValidApiVersion(userInput)) {
 *   // userInput is now typed as ApiVersion
 *   const config = VERSION_CONFIGS[userInput];
 * }
 * ```
 */
 export function isValidApiVersion(value: string): value is ApiVersion {
  return API_VERSIONS.includes(value as ApiVersion);
 }
 /**
 * Check if a version is deprecated.
 *
 * @param version - The API version to check
 * @returns True if the version status is 'deprecated'
 */
 export function isVersionDeprecated(version: ApiVersion): boolean {
  return VERSION_CONFIGS[version].status === 'deprecated';
 }
 /**
 * Get deprecation information for a version.
 * Constructs a VersionDeprecation object from the version config.
 *
 * @param version - The API version to get deprecation info for
 * @returns VersionDeprecation object with current deprecation state
 */
 export function getVersionDeprecation(version: ApiVersion): VersionDeprecation {
  const config = VERSION_CONFIGS[version];
  return {
    deprecated: config.status === 'deprecated',
    sunsetDate: config.sunsetDate,
    successorVersion: config.successorVersion,
    message:
      config.status === 'deprecated'
        ? `API ${version} is deprecated${config.sunsetDate ? ` and will be sunset on ${config.sunsetDate}` : ''}${config.successorVersion ? `. Please migrate to ${config.successorVersion}.` : '.'}`
        : undefined,
  };
 }
--- a/src/middleware/apiVersion.middleware.test.ts
+++ b/src/middleware/apiVersion.middleware.test.ts
@@ -0,0 +1,400 @@
 // src/middleware/apiVersion.middleware.test.ts
 /**
 * @file Unit tests for API version detection middleware (ADR-008 Phase 2).
 * @see src/middleware/apiVersion.middleware.ts
 */
 import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
 import type { Request, Response, NextFunction } from 'express';
 import {
  detectApiVersion,
  extractApiVersionFromPath,
  hasApiVersion,
  getRequestApiVersion,
  VERSION_ERROR_CODES,
 } from './apiVersion.middleware';
 import { DEFAULT_VERSION, SUPPORTED_VERSIONS } from '../config/apiVersions';
 import { createMockRequest } from '../tests/utils/createMockRequest';
 import { createMockLogger } from '../tests/utils/mockLogger';
 describe('apiVersion.middleware', () => {
  let mockRequest: Partial<Request>;
  let mockResponse: Partial<Response>;
  let mockNext: NextFunction & Mock;
  let mockJson: Mock;
  let mockStatus: Mock;
  beforeEach(() => {
    // Reset mocks before each test
    mockJson = vi.fn().mockReturnThis();
    mockStatus = vi.fn().mockReturnValue({ json: mockJson });
    mockNext = vi.fn();
    mockResponse = {
      status: mockStatus,
      json: mockJson,
    };
  });
  describe('detectApiVersion', () => {
    it('should extract v1 from req.params.version and attach to req.apiVersion', () => {
      // Arrange
      mockRequest = createMockRequest({
        params: { version: 'v1' },
        path: '/users',
        method: 'GET',
      });
      // Act
      detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
      // Assert
      expect(mockNext).toHaveBeenCalledTimes(1);
      expect(mockNext).toHaveBeenCalledWith();
      expect(mockRequest.apiVersion).toBe('v1');
      expect(mockRequest.versionDeprecation).toBeDefined();
      expect(mockRequest.versionDeprecation?.deprecated).toBe(false);
    });
    it('should extract v2 from req.params.version and attach to req.apiVersion', () => {
      // Arrange
      mockRequest = createMockRequest({
        params: { version: 'v2' },
        path: '/flyers',
        method: 'POST',
      });
      // Act
      detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
      // Assert
      expect(mockNext).toHaveBeenCalledTimes(1);
      expect(mockRequest.apiVersion).toBe('v2');
      expect(mockRequest.versionDeprecation).toBeDefined();
    });
    it('should default to v1 when no version parameter is present', () => {
      // Arrange
      mockRequest = createMockRequest({
        params: {},
        path: '/users',
        method: 'GET',
      });
      // Act
      detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
      // Assert
      expect(mockNext).toHaveBeenCalledTimes(1);
      expect(mockRequest.apiVersion).toBe(DEFAULT_VERSION);
      expect(mockRequest.versionDeprecation).toBeDefined();
    });
    it('should return 404 with UNSUPPORTED_VERSION for invalid version v99', () => {
      // Arrange
      mockRequest = createMockRequest({
        params: { version: 'v99' },
        path: '/users',
        method: 'GET',
        ip: '127.0.0.1',
      });
      // Act
      detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
      // Assert
      expect(mockNext).not.toHaveBeenCalled();
      expect(mockStatus).toHaveBeenCalledWith(404);
      expect(mockJson).toHaveBeenCalledWith(
        expect.objectContaining({
          success: false,
          error: expect.objectContaining({
            code: VERSION_ERROR_CODES.UNSUPPORTED_VERSION,
            message: expect.stringContaining("API version 'v99' is not supported"),
            details: expect.objectContaining({
              requestedVersion: 'v99',
              supportedVersions: expect.arrayContaining(['v1', 'v2']),
            }),
          }),
        }),
      );
    });
    it('should return 404 for non-versioned format like "latest"', () => {
      // Arrange
      mockRequest = createMockRequest({
        params: { version: 'latest' },
        path: '/users',
        method: 'GET',
        ip: '192.168.1.1',
      });
      // Act
      detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
      // Assert
      expect(mockNext).not.toHaveBeenCalled();
      expect(mockStatus).toHaveBeenCalledWith(404);
      expect(mockJson).toHaveBeenCalledWith(
        expect.objectContaining({
          success: false,
          error: expect.objectContaining({
            code: VERSION_ERROR_CODES.UNSUPPORTED_VERSION,
            message: expect.stringContaining("API version 'latest' is not supported"),
          }),
        }),
      );
    });
    it('should log warning when invalid version is requested', () => {
      // Arrange
      const childLogger = createMockLogger();
      const mockLog = createMockLogger();
      vi.mocked(mockLog.child).mockReturnValue(
        childLogger as unknown as ReturnType<typeof mockLog.child>,
      );
      mockRequest = createMockRequest({
        params: { version: 'v999' },
        path: '/test',
        method: 'GET',
        ip: '10.0.0.1',
        log: mockLog,
      });
      // Act
      detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
      // Assert
      expect(mockLog.child).toHaveBeenCalledWith({ middleware: 'detectApiVersion' });
      expect(childLogger.warn).toHaveBeenCalledWith(
        expect.objectContaining({
          attemptedVersion: 'v999',
          supportedVersions: SUPPORTED_VERSIONS,
        }),
        'Invalid API version requested',
      );
    });
    it('should log debug when valid version is detected', () => {
      // Arrange
      const childLogger = createMockLogger();
      const mockLog = createMockLogger();
      vi.mocked(mockLog.child).mockReturnValue(
        childLogger as unknown as ReturnType<typeof mockLog.child>,
      );
      mockRequest = createMockRequest({
        params: { version: 'v1' },
        path: '/users',
        method: 'GET',
        log: mockLog,
      });
      // Act
      detectApiVersion(mockRequest as Request, mockResponse as Response, mockNext);
      // Assert
      expect(childLogger.debug).toHaveBeenCalledWith(
        { apiVersion: 'v1' },
        'API version detected from URL',
      );
    });
  });
  describe('extractApiVersionFromPath', () => {
    it('should extract v1 from /v1/users path', () => {
      // Arrange
      mockRequest = createMockRequest({
        path: '/v1/users',
        params: {},
      });
      // Act
      extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
      // Assert
      expect(mockNext).toHaveBeenCalledTimes(1);
      expect(mockRequest.apiVersion).toBe('v1');
      expect(mockRequest.versionDeprecation).toBeDefined();
    });
    it('should extract v2 from /v2/flyers/123 path', () => {
      // Arrange
      mockRequest = createMockRequest({
        path: '/v2/flyers/123',
        params: {},
      });
      // Act
      extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
      // Assert
      expect(mockNext).toHaveBeenCalledTimes(1);
      expect(mockRequest.apiVersion).toBe('v2');
    });
    it('should default to v1 for unversioned paths', () => {
      // Arrange
      mockRequest = createMockRequest({
        path: '/users',
        params: {},
      });
      // Act
      extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
      // Assert
      expect(mockNext).toHaveBeenCalledTimes(1);
      expect(mockRequest.apiVersion).toBe(DEFAULT_VERSION);
    });
    it('should default to v1 for paths without leading slash', () => {
      // Arrange
      mockRequest = createMockRequest({
        path: 'v1/users', // No leading slash - won't match regex
        params: {},
      });
      // Act
      extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
      // Assert
      expect(mockNext).toHaveBeenCalledTimes(1);
      expect(mockRequest.apiVersion).toBe(DEFAULT_VERSION);
    });
    it('should use default for unsupported version numbers in path', () => {
      // Arrange
      const childLogger = createMockLogger();
      const mockLog = createMockLogger();
      vi.mocked(mockLog.child).mockReturnValue(
        childLogger as unknown as ReturnType<typeof mockLog.child>,
      );
      mockRequest = createMockRequest({
        path: '/v99/users',
        params: {},
        log: mockLog,
      });
      // Act
      extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
      // Assert
      expect(mockNext).toHaveBeenCalledTimes(1);
      expect(mockRequest.apiVersion).toBe(DEFAULT_VERSION);
      expect(childLogger.warn).toHaveBeenCalledWith(
        expect.objectContaining({
          attemptedVersion: 'v99',
          supportedVersions: SUPPORTED_VERSIONS,
        }),
        'Unsupported API version in path, falling back to default',
      );
    });
    it('should handle paths with only version segment', () => {
      // Arrange: Path like "/v1/" (just version, no resource)
      mockRequest = createMockRequest({
        path: '/v1/',
        params: {},
      });
      // Act
      extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
      // Assert
      expect(mockNext).toHaveBeenCalledTimes(1);
      expect(mockRequest.apiVersion).toBe('v1');
    });
    it('should NOT extract version from path like /users/v1 (not at start)', () => {
      // Arrange: Version appears later in path, not at the start
      mockRequest = createMockRequest({
        path: '/users/v1/profile',
        params: {},
      });
      // Act
      extractApiVersionFromPath(mockRequest as Request, mockResponse as Response, mockNext);
      // Assert
      expect(mockNext).toHaveBeenCalledTimes(1);
      expect(mockRequest.apiVersion).toBe(DEFAULT_VERSION);
    });
  });
  describe('hasApiVersion', () => {
    it('should return true when apiVersion is set to valid version', () => {
      // Arrange
      mockRequest = createMockRequest({});
      mockRequest.apiVersion = 'v1';
      // Act & Assert
      expect(hasApiVersion(mockRequest as Request)).toBe(true);
    });
    it('should return false when apiVersion is undefined', () => {
      // Arrange
      mockRequest = createMockRequest({});
      mockRequest.apiVersion = undefined;
      // Act & Assert
      expect(hasApiVersion(mockRequest as Request)).toBe(false);
    });
    it('should return false when apiVersion is invalid', () => {
      // Arrange
      mockRequest = createMockRequest({});
      // Force an invalid version (bypassing TypeScript) - eslint-disable-next-line
      (mockRequest as unknown as { apiVersion: string }).apiVersion = 'v99';
      // Act & Assert
      expect(hasApiVersion(mockRequest as Request)).toBe(false);
    });
  });
  describe('getRequestApiVersion', () => {
    it('should return the request apiVersion when set', () => {
      // Arrange
      mockRequest = createMockRequest({});
      mockRequest.apiVersion = 'v2';
      // Act
      const version = getRequestApiVersion(mockRequest as Request);
      // Assert
      expect(version).toBe('v2');
    });
    it('should return DEFAULT_VERSION when apiVersion is undefined', () => {
      // Arrange
      mockRequest = createMockRequest({});
      mockRequest.apiVersion = undefined;
      // Act
      const version = getRequestApiVersion(mockRequest as Request);
      // Assert
      expect(version).toBe(DEFAULT_VERSION);
    });
    it('should return DEFAULT_VERSION when apiVersion is invalid', () => {
      // Arrange
      mockRequest = createMockRequest({});
      // Force an invalid version - eslint-disable-next-line
      (mockRequest as unknown as { apiVersion: string }).apiVersion = 'invalid';
      // Act
      const version = getRequestApiVersion(mockRequest as Request);
      // Assert
      expect(version).toBe(DEFAULT_VERSION);
    });
  });
  describe('VERSION_ERROR_CODES', () => {
    it('should have UNSUPPORTED_VERSION error code', () => {
      expect(VERSION_ERROR_CODES.UNSUPPORTED_VERSION).toBe('UNSUPPORTED_VERSION');
    });
  });
 });
--- a/src/middleware/apiVersion.middleware.ts
+++ b/src/middleware/apiVersion.middleware.ts
@@ -0,0 +1,218 @@
 // src/middleware/apiVersion.middleware.ts
 /**
 * @file API version detection middleware implementing ADR-008 Phase 2.
 *
 * Extracts API version from the request URL, validates it against supported versions,
 * attaches version information to the request object, and handles unsupported versions.
 *
 * @see docs/architecture/api-versioning-infrastructure.md
 * @see docs/adr/0008-api-versioning-strategy.md
 *
 * @example
 * ```typescript
 * // In versioned router factory (versioned.ts):
 * import { detectApiVersion } from '../middleware/apiVersion.middleware';
 *
 * const router = Router({ mergeParams: true });
 * router.use(detectApiVersion);
 * ```
 */
 import { Request, Response, NextFunction } from 'express';
 import {
  ApiVersion,
  SUPPORTED_VERSIONS,
  DEFAULT_VERSION,
  isValidApiVersion,
  getVersionDeprecation,
 } from '../config/apiVersions';
 import { sendError } from '../utils/apiResponse';
 import { createScopedLogger } from '../services/logger.server';
 // --- Module-level Logger ---
 /**
 * Module-scoped logger for API version middleware.
 * Used for logging version detection events outside of request context.
 */
 const moduleLogger = createScopedLogger('apiVersion-middleware');
 // --- Error Codes ---
 /**
 * Error code for unsupported API version requests.
 * This is specific to the versioning system and not part of the general ErrorCode enum.
 */
 export const VERSION_ERROR_CODES = {
  UNSUPPORTED_VERSION: 'UNSUPPORTED_VERSION',
 } as const;
 // --- Middleware Functions ---
 /**
 * Extracts the API version from the URL path parameter and attaches it to the request.
 *
 * This middleware expects to be used with a router that has a :version parameter
 * (e.g., mounted at `/api/:version`). It validates the version against the list
 * of supported versions and returns a 404 error for unsupported versions.
 *
 * For valid versions, it:
 * - Sets `req.apiVersion` to the detected version
 * - Sets `req.versionDeprecation` with deprecation info if the version is deprecated
 *
 * @param req - Express request object (expects `req.params.version`)
 * @param res - Express response object
 * @param next - Express next function
 *
 * @example
 * ```typescript
 * // Route setup:
 * app.use('/api/:version', detectApiVersion, versionedRouter);
 *
 * // Request to /api/v1/users:
 * // req.params.version = 'v1'
 * // req.apiVersion = 'v1'
 *
 * // Request to /api/v99/users:
 * // Returns 404 with UNSUPPORTED_VERSION error
 * ```
 */
 export function detectApiVersion(req: Request, res: Response, next: NextFunction): void {
  // Get the request-scoped logger if available, otherwise use module logger
  const log = req.log?.child({ middleware: 'detectApiVersion' }) ?? moduleLogger;
  // Extract version from URL params (expects router mounted with :version param)
  const versionParam = req.params?.version;
  // If no version parameter found, this middleware was likely applied incorrectly.
  // Default to the default version and continue (allows for fallback behavior).
  if (!versionParam) {
    log.debug('No version parameter found in request, using default version');
    req.apiVersion = DEFAULT_VERSION;
    req.versionDeprecation = getVersionDeprecation(DEFAULT_VERSION);
    return next();
  }
  // Validate the version parameter
  if (isValidApiVersion(versionParam)) {
    // Valid version - attach to request
    req.apiVersion = versionParam;
    req.versionDeprecation = getVersionDeprecation(versionParam);
    log.debug({ apiVersion: versionParam }, 'API version detected from URL');
    return next();
  }
  // Invalid version - log warning and return 404
  log.warn(
    {
      attemptedVersion: versionParam,
      supportedVersions: SUPPORTED_VERSIONS,
      path: req.path,
      method: req.method,
      ip: req.ip,
    },
    'Invalid API version requested',
  );
  // Return 404 with UNSUPPORTED_VERSION error code
  // Using 404 because the versioned endpoint does not exist
  sendError(
    res,
    VERSION_ERROR_CODES.UNSUPPORTED_VERSION,
    `API version '${versionParam}' is not supported. Supported versions: ${SUPPORTED_VERSIONS.join(', ')}`,
    404,
    {
      requestedVersion: versionParam,
      supportedVersions: [...SUPPORTED_VERSIONS],
    },
  );
 }
 /**
 * Extracts the API version from the URL path pattern and attaches it to the request.
 *
 * Unlike `detectApiVersion`, this middleware parses the version from the URL path
 * directly using a regex pattern. This is useful when the middleware needs to run
 * before or independently of parameterized routing.
 *
 * Pattern matched: `/v{number}/...` at the beginning of the path
 * (e.g., `/v1/users`, `/v2/flyers/123`)
 *
 * If the version is valid, sets `req.apiVersion` and `req.versionDeprecation`.
 * If the version is invalid or not present, defaults to `DEFAULT_VERSION`.
 *
 * This middleware does NOT return errors for invalid versions - it's designed for
 * cases where version detection is informational rather than authoritative.
 *
 * @param req - Express request object
 * @param _res - Express response object (unused)
 * @param next - Express next function
 *
 * @example
 * ```typescript
 * // Applied early in middleware chain:
 * app.use('/api', extractApiVersionFromPath, apiRouter);
 *
 * // For path /api/v1/users:
 * // req.path = '/v1/users' (relative to /api mount point)
 * // req.apiVersion = 'v1'
 * ```
 */
 export function extractApiVersionFromPath(req: Request, _res: Response, next: NextFunction): void {
  // Get the request-scoped logger if available, otherwise use module logger
  const log = req.log?.child({ middleware: 'extractApiVersionFromPath' }) ?? moduleLogger;
  // Extract version from URL path using regex: /v{number}/
  // The path is relative to the router's mount point
  const pathMatch = req.path.match(/^\/v(\d+)\//);
  if (pathMatch) {
    const versionString = `v${pathMatch[1]}` as string;
    if (isValidApiVersion(versionString)) {
      req.apiVersion = versionString;
      req.versionDeprecation = getVersionDeprecation(versionString);
      log.debug({ apiVersion: versionString }, 'API version extracted from path');
      return next();
    }
    // Version number in path but not in supported list - log and use default
    log.warn(
      {
        attemptedVersion: versionString,
        supportedVersions: SUPPORTED_VERSIONS,
        path: req.path,
      },
      'Unsupported API version in path, falling back to default',
    );
  }
  // No version detected or invalid - use default
  req.apiVersion = DEFAULT_VERSION;
  req.versionDeprecation = getVersionDeprecation(DEFAULT_VERSION);
  log.debug({ apiVersion: DEFAULT_VERSION }, 'Using default API version');
  return next();
 }
 /**
 * Type guard to check if a request has a valid API version attached.
 *
 * @param req - Express request object
 * @returns True if req.apiVersion is set to a valid ApiVersion
 */
 export function hasApiVersion(req: Request): req is Request & { apiVersion: ApiVersion } {
  return req.apiVersion !== undefined && isValidApiVersion(req.apiVersion);
 }
 /**
 * Gets the API version from a request, with a fallback to the default version.
 *
 * @param req - Express request object
 * @returns The API version from the request, or DEFAULT_VERSION if not set
 */
 export function getRequestApiVersion(req: Request): ApiVersion {
  if (req.apiVersion && isValidApiVersion(req.apiVersion)) {
    return req.apiVersion;
  }
  return DEFAULT_VERSION;
 }
--- a/src/middleware/deprecation.middleware.test.ts
+++ b/src/middleware/deprecation.middleware.test.ts
@@ -0,0 +1,450 @@
 // src/middleware/deprecation.middleware.test.ts
 /**
 * @file Unit tests for deprecation header middleware.
 * Tests RFC 8594 compliant header generation for deprecated API versions.
 *
 * @see ADR-008 for API versioning strategy
 * @see docs/architecture/api-versioning-infrastructure.md
 */
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import type { Request, Response } from 'express';
 import {
  addDeprecationHeaders,
  addDeprecationHeadersFromRequest,
  DEPRECATION_HEADERS,
 } from './deprecation.middleware';
 import { VERSION_CONFIGS } from '../config/apiVersions';
 import { createMockRequest } from '../tests/utils/createMockRequest';
 // Mock the logger to avoid actual logging during tests
 vi.mock('../services/logger.server', () => ({
  createScopedLogger: vi.fn(() => ({
    debug: vi.fn(),
    info: vi.fn(),
    warn: vi.fn(),
    error: vi.fn(),
  })),
  logger: {
    debug: vi.fn(),
    info: vi.fn(),
    warn: vi.fn(),
    error: vi.fn(),
    child: vi.fn().mockReturnThis(),
  },
 }));
 describe('deprecation.middleware', () => {
  // Store original VERSION_CONFIGS to restore after tests
  let originalV1Config: typeof VERSION_CONFIGS.v1;
  let originalV2Config: typeof VERSION_CONFIGS.v2;
  let mockRequest: Request;
  let mockResponse: Partial<Response>;
  let mockNext: any;
  let setHeaderSpy: any;
  beforeEach(() => {
    // Save original configs
    originalV1Config = { ...VERSION_CONFIGS.v1 };
    originalV2Config = { ...VERSION_CONFIGS.v2 };
    // Reset mocks
    setHeaderSpy = vi.fn();
    mockRequest = createMockRequest({
      method: 'GET',
      path: '/api/v1/flyers',
      get: vi.fn().mockReturnValue('TestUserAgent/1.0'),
    });
    mockResponse = {
      set: setHeaderSpy,
      setHeader: setHeaderSpy,
    };
    mockNext = vi.fn();
  });
  afterEach(() => {
    // Restore original configs after each test
    VERSION_CONFIGS.v1 = originalV1Config;
    VERSION_CONFIGS.v2 = originalV2Config;
  });
  describe('addDeprecationHeaders (factory function)', () => {
    describe('with active version', () => {
      it('should always set X-API-Version header', () => {
        // Arrange - v1 is active by default
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v1');
        expect(mockNext).toHaveBeenCalledTimes(1);
      });
      it('should not add Deprecation header for active version', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).not.toHaveBeenCalledWith(DEPRECATION_HEADERS.DEPRECATION, 'true');
        expect(setHeaderSpy).toHaveBeenCalledTimes(1); // Only X-API-Version
      });
      it('should not add Sunset header for active version', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).not.toHaveBeenCalledWith(
          DEPRECATION_HEADERS.SUNSET,
          expect.anything(),
        );
      });
      it('should not add Link header for active version', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).not.toHaveBeenCalledWith(DEPRECATION_HEADERS.LINK, expect.anything());
      });
      it('should not set versionDeprecation on request for active version', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(mockRequest.versionDeprecation).toBeUndefined();
      });
    });
    describe('with deprecated version', () => {
      beforeEach(() => {
        // Mark v1 as deprecated for these tests
        VERSION_CONFIGS.v1 = {
          version: 'v1',
          status: 'deprecated',
          sunsetDate: '2027-01-01T00:00:00Z',
          successorVersion: 'v2',
        };
      });
      it('should add Deprecation: true header', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.DEPRECATION, 'true');
      });
      it('should add Sunset header with ISO 8601 date', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).toHaveBeenCalledWith(
          DEPRECATION_HEADERS.SUNSET,
          '2027-01-01T00:00:00Z',
        );
      });
      it('should add Link header with successor-version relation', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).toHaveBeenCalledWith(
          DEPRECATION_HEADERS.LINK,
          '</api/v2>; rel="successor-version"',
        );
      });
      it('should add X-API-Deprecation-Notice header', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).toHaveBeenCalledWith(
          DEPRECATION_HEADERS.DEPRECATION_NOTICE,
          expect.stringContaining('deprecated'),
        );
      });
      it('should always set X-API-Version header', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v1');
      });
      it('should set versionDeprecation on request', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(mockRequest.versionDeprecation).toBeDefined();
        expect(mockRequest.versionDeprecation?.deprecated).toBe(true);
        expect(mockRequest.versionDeprecation?.sunsetDate).toBe('2027-01-01T00:00:00Z');
        expect(mockRequest.versionDeprecation?.successorVersion).toBe('v2');
      });
      it('should call next() to continue middleware chain', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(mockNext).toHaveBeenCalledTimes(1);
        expect(mockNext).toHaveBeenCalledWith();
      });
      it('should add all RFC 8594 compliant headers in correct format', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert - verify all headers are set
        const headerCalls = setHeaderSpy.mock.calls;
        const headerNames = headerCalls.map((call: unknown[]) => call[0]);
        expect(headerNames).toContain(DEPRECATION_HEADERS.API_VERSION);
        expect(headerNames).toContain(DEPRECATION_HEADERS.DEPRECATION);
        expect(headerNames).toContain(DEPRECATION_HEADERS.SUNSET);
        expect(headerNames).toContain(DEPRECATION_HEADERS.LINK);
        expect(headerNames).toContain(DEPRECATION_HEADERS.DEPRECATION_NOTICE);
      });
    });
    describe('with deprecated version missing optional fields', () => {
      beforeEach(() => {
        // Mark v1 as deprecated without sunset date or successor
        VERSION_CONFIGS.v1 = {
          version: 'v1',
          status: 'deprecated',
          // No sunsetDate or successorVersion
        };
      });
      it('should add Deprecation header even without sunset date', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.DEPRECATION, 'true');
      });
      it('should not add Sunset header when sunsetDate is not configured', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).not.toHaveBeenCalledWith(
          DEPRECATION_HEADERS.SUNSET,
          expect.anything(),
        );
      });
      it('should not add Link header when successorVersion is not configured', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v1');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).not.toHaveBeenCalledWith(DEPRECATION_HEADERS.LINK, expect.anything());
      });
    });
    describe('with v2 version', () => {
      it('should set X-API-Version: v2 header', () => {
        // Arrange
        const middleware = addDeprecationHeaders('v2');
        // Act
        middleware(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v2');
      });
    });
  });
  describe('addDeprecationHeadersFromRequest', () => {
    describe('when apiVersion is set on request', () => {
      it('should add headers based on request apiVersion', () => {
        // Arrange
        mockRequest.apiVersion = 'v1';
        VERSION_CONFIGS.v1 = {
          version: 'v1',
          status: 'deprecated',
          sunsetDate: '2027-06-01T00:00:00Z',
          successorVersion: 'v2',
        };
        // Act
        addDeprecationHeadersFromRequest(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v1');
        expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.DEPRECATION, 'true');
        expect(setHeaderSpy).toHaveBeenCalledWith(
          DEPRECATION_HEADERS.SUNSET,
          '2027-06-01T00:00:00Z',
        );
      });
      it('should not add deprecation headers for active version', () => {
        // Arrange
        mockRequest.apiVersion = 'v2';
        // Act
        addDeprecationHeadersFromRequest(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v2');
        expect(setHeaderSpy).toHaveBeenCalledTimes(1);
      });
    });
    describe('when apiVersion is not set on request', () => {
      it('should skip header processing and call next', () => {
        // Arrange
        mockRequest.apiVersion = undefined;
        // Act
        addDeprecationHeadersFromRequest(mockRequest, mockResponse as Response, mockNext);
        // Assert
        expect(setHeaderSpy).not.toHaveBeenCalled();
        expect(mockNext).toHaveBeenCalledTimes(1);
      });
    });
  });
  describe('DEPRECATION_HEADERS constants', () => {
    it('should have correct header names', () => {
      expect(DEPRECATION_HEADERS.DEPRECATION).toBe('Deprecation');
      expect(DEPRECATION_HEADERS.SUNSET).toBe('Sunset');
      expect(DEPRECATION_HEADERS.LINK).toBe('Link');
      expect(DEPRECATION_HEADERS.DEPRECATION_NOTICE).toBe('X-API-Deprecation-Notice');
      expect(DEPRECATION_HEADERS.API_VERSION).toBe('X-API-Version');
    });
  });
  describe('edge cases', () => {
    it('should handle sunset version status', () => {
      // Arrange
      VERSION_CONFIGS.v1 = {
        version: 'v1',
        status: 'sunset',
        sunsetDate: '2026-01-01T00:00:00Z',
      };
      const middleware = addDeprecationHeaders('v1');
      // Act
      middleware(mockRequest, mockResponse as Response, mockNext);
      // Assert - sunset is different from deprecated, so no deprecation headers
      // Only X-API-Version should be set
      expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v1');
      expect(setHeaderSpy).not.toHaveBeenCalledWith(DEPRECATION_HEADERS.DEPRECATION, 'true');
    });
    it('should handle request with existing log object', () => {
      // Arrange
      VERSION_CONFIGS.v1 = {
        version: 'v1',
        status: 'deprecated',
        sunsetDate: '2027-01-01T00:00:00Z',
        successorVersion: 'v2',
      };
      const mockLogWithBindings = {
        debug: vi.fn(),
        bindings: vi.fn().mockReturnValue({ request_id: 'test-request-id' }),
      };
      mockRequest.log = mockLogWithBindings as unknown as Request['log'];
      const middleware = addDeprecationHeaders('v1');
      // Act
      middleware(mockRequest, mockResponse as Response, mockNext);
      // Assert - should not throw and should complete
      expect(mockNext).toHaveBeenCalledTimes(1);
    });
    it('should work with different versions in sequence', () => {
      // Arrange
      VERSION_CONFIGS.v1 = {
        version: 'v1',
        status: 'deprecated',
        sunsetDate: '2027-01-01T00:00:00Z',
        successorVersion: 'v2',
      };
      const v1Middleware = addDeprecationHeaders('v1');
      const v2Middleware = addDeprecationHeaders('v2');
      // Act
      v1Middleware(mockRequest, mockResponse as Response, mockNext);
      // Reset for v2
      setHeaderSpy.mockClear();
      mockNext.mockClear();
      const mockRequest2 = createMockRequest({
        method: 'GET',
        path: '/api/v2/flyers',
      });
      v2Middleware(mockRequest2, mockResponse as Response, mockNext);
      // Assert - v2 should only have API version header
      expect(setHeaderSpy).toHaveBeenCalledWith(DEPRECATION_HEADERS.API_VERSION, 'v2');
      expect(setHeaderSpy).toHaveBeenCalledTimes(1);
    });
  });
 });
--- a/src/middleware/deprecation.middleware.ts
+++ b/src/middleware/deprecation.middleware.ts
@@ -0,0 +1,218 @@
 // src/middleware/deprecation.middleware.ts
 /**
 * @file Deprecation Headers Middleware - RFC 8594 Compliant
 * Implements ADR-008 Phase 2: API Versioning Infrastructure.
 *
 * This middleware adds standard deprecation headers to API responses when
 * a deprecated API version is being accessed. It follows:
 * - RFC 8594: The "Sunset" HTTP Header Field
 * - draft-ietf-httpapi-deprecation-header: The "Deprecation" HTTP Header Field
 * - RFC 8288: Web Linking (for successor-version relation)
 *
 * Headers added for deprecated versions:
 * - `Deprecation: true` - Indicates the endpoint is deprecated
 * - `Sunset: <ISO 8601 date>` - When the endpoint will be removed
 * - `Link: </api/vX>; rel="successor-version"` - URL to the replacement version
 * - `X-API-Deprecation-Notice: <message>` - Human-readable deprecation message
 *
 * Always added (for all versions):
 * - `X-API-Version: <version>` - The API version being accessed
 *
 * @see docs/architecture/api-versioning-infrastructure.md
 * @see https://datatracker.ietf.org/doc/html/rfc8594
 */
 import { Request, Response, NextFunction } from 'express';
 import { ApiVersion, VERSION_CONFIGS, getVersionDeprecation } from '../config/apiVersions';
 import { createScopedLogger } from '../services/logger.server';
 // Create a module-scoped logger for deprecation tracking
 const deprecationLogger = createScopedLogger('deprecation-middleware');
 /**
 * HTTP header names for deprecation signaling.
 * Using constants to ensure consistency and prevent typos.
 */
 export const DEPRECATION_HEADERS = {
  /** RFC draft-ietf-httpapi-deprecation-header: Indicates deprecation status */
  DEPRECATION: 'Deprecation',
  /** RFC 8594: ISO 8601 date when the endpoint will be removed */
  SUNSET: 'Sunset',
  /** RFC 8288: Link to successor version with rel="successor-version" */
  LINK: 'Link',
  /** Custom header: Human-readable deprecation notice */
  DEPRECATION_NOTICE: 'X-API-Deprecation-Notice',
  /** Custom header: Current API version being accessed */
  API_VERSION: 'X-API-Version',
 } as const;
 /**
 * Creates middleware that adds RFC 8594 compliant deprecation headers
 * to responses when a deprecated API version is accessed.
 *
 * This is a middleware factory function that takes a version parameter
 * and returns the configured middleware function. This pattern allows
 * different version routers to have their own deprecation configuration.
 *
 * @param version - The API version this middleware is handling
 * @returns Express middleware function that adds appropriate headers
 *
 * @example
 * ```typescript
 * // In a versioned router factory:
 * const v1Router = Router();
 * v1Router.use(addDeprecationHeaders('v1'));
 *
 * // When v1 is deprecated, responses will include:
 * // Deprecation: true
 * // Sunset: 2027-01-01T00:00:00Z
 * // Link: </api/v2>; rel="successor-version"
 * // X-API-Deprecation-Notice: API v1 is deprecated...
 * // X-API-Version: v1
 * ```
 */
 export function addDeprecationHeaders(version: ApiVersion) {
  // Pre-fetch configuration at middleware creation time for efficiency.
  // This avoids repeated lookups on every request.
  const config = VERSION_CONFIGS[version];
  const deprecationInfo = getVersionDeprecation(version);
  return function deprecationHeadersMiddleware(
    req: Request,
    res: Response,
    next: NextFunction,
  ): void {
    // Always set the API version header for transparency and debugging.
    // This helps clients know which version they're using, especially
    // useful when default version routing is in effect.
    res.set(DEPRECATION_HEADERS.API_VERSION, version);
    // Only add deprecation headers if this version is actually deprecated.
    // Active versions should not have any deprecation headers.
    if (config.status === 'deprecated') {
      // RFC draft-ietf-httpapi-deprecation-header: Set to "true" to indicate deprecation
      res.set(DEPRECATION_HEADERS.DEPRECATION, 'true');
      // RFC 8594: Sunset header with ISO 8601 date indicating removal date
      if (config.sunsetDate) {
        res.set(DEPRECATION_HEADERS.SUNSET, config.sunsetDate);
      }
      // RFC 8288: Link header with successor-version relation
      // This tells clients where to migrate to
      if (config.successorVersion) {
        res.set(
          DEPRECATION_HEADERS.LINK,
          `</api/${config.successorVersion}>; rel="successor-version"`,
        );
      }
      // Custom header: Human-readable message for developers
      // This provides context that may not be obvious from the standard headers
      if (deprecationInfo.message) {
        res.set(DEPRECATION_HEADERS.DEPRECATION_NOTICE, deprecationInfo.message);
      }
      // Attach deprecation info to the request for use in route handlers.
      // This allows handlers to implement version-specific behavior or logging.
      req.versionDeprecation = deprecationInfo;
      // Log deprecation access at debug level to avoid log spam.
      // This provides visibility into deprecated API usage without overwhelming logs.
      // Use debug level because high-traffic APIs could generate significant volume.
      // Production monitoring should use the access logs or metrics aggregation
      // to track deprecation usage patterns.
      deprecationLogger.debug(
        {
          apiVersion: version,
          method: req.method,
          path: req.path,
          sunsetDate: config.sunsetDate,
          successorVersion: config.successorVersion,
          userAgent: req.get('User-Agent'),
          // Include request ID if available from the request logger
          requestId: (req.log as { bindings?: () => { request_id?: string } })?.bindings?.()
            ?.request_id,
        },
        'Deprecated API version accessed',
      );
    }
    next();
  };
 }
 /**
 * Standalone middleware for adding deprecation headers based on
 * the `apiVersion` property already set on the request.
 *
 * This middleware should be used after the version extraction middleware
 * has set `req.apiVersion`. It provides a more flexible approach when
 * the version is determined dynamically rather than statically.
 *
 * @example
 * ```typescript
 * // After version extraction middleware:
 * router.use(extractApiVersion);
 * router.use(addDeprecationHeadersFromRequest);
 * ```
 */
 export function addDeprecationHeadersFromRequest(
  req: Request,
  res: Response,
  next: NextFunction,
 ): void {
  const version = req.apiVersion;
  // If no version is set on the request, skip deprecation handling.
  // This should not happen if the version extraction middleware ran first,
  // but we handle it gracefully for safety.
  if (!version) {
    next();
    return;
  }
  const config = VERSION_CONFIGS[version];
  const deprecationInfo = getVersionDeprecation(version);
  // Always set the API version header
  res.set(DEPRECATION_HEADERS.API_VERSION, version);
  // Add deprecation headers if version is deprecated
  if (config.status === 'deprecated') {
    res.set(DEPRECATION_HEADERS.DEPRECATION, 'true');
    if (config.sunsetDate) {
      res.set(DEPRECATION_HEADERS.SUNSET, config.sunsetDate);
    }
    if (config.successorVersion) {
      res.set(
        DEPRECATION_HEADERS.LINK,
        `</api/${config.successorVersion}>; rel="successor-version"`,
      );
    }
    if (deprecationInfo.message) {
      res.set(DEPRECATION_HEADERS.DEPRECATION_NOTICE, deprecationInfo.message);
    }
    req.versionDeprecation = deprecationInfo;
    deprecationLogger.debug(
      {
        apiVersion: version,
        method: req.method,
        path: req.path,
        sunsetDate: config.sunsetDate,
        successorVersion: config.successorVersion,
        userAgent: req.get('User-Agent'),
        requestId: (req.log as { bindings?: () => { request_id?: string } })?.bindings?.()
          ?.request_id,
      },
      'Deprecated API version accessed',
    );
  }
  next();
 }
--- a/src/routes/auth.routes.test.ts
+++ b/src/routes/auth.routes.test.ts
@@ -1,9 +1,11 @@
 // src/routes/auth.routes.test.ts
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import supertest from 'supertest';
-import { Request, Response, NextFunction } from 'express';
+import express, { Request, Response, NextFunction } from 'express';
 import cookieParser from 'cookie-parser'; // This was a duplicate, fixed.
 import { createMockUserProfile } from '../tests/utils/mockFactories';
 import { DEPRECATION_HEADERS, addDeprecationHeaders } from '../middleware/deprecation.middleware';
 import { errorHandler } from '../middleware/errorHandler';
 // --- FIX: Hoist passport mocks to be available for vi.mock ---
 const passportMocks = vi.hoisted(() => {
@@ -83,6 +85,13 @@ vi.mock('../services/authService', () => ({ authService: mockedAuthService }));
 vi.mock('../services/logger.server', async () => ({
  // Use async import to avoid hoisting issues with mockLogger
  logger: (await import('../tests/utils/mockLogger')).mockLogger,
  createScopedLogger: vi.fn(() => ({
    debug: vi.fn(),
    info: vi.fn(),
    warn: vi.fn(),
    error: vi.fn(),
    child: vi.fn().mockReturnThis(),
  })),
 }));
 // Mock the email service
@@ -908,4 +917,163 @@ describe('Auth Routes (/api/v1/auth)', () => {
      }
    });
  });
  // =============================================================================
  // API VERSION HEADER ASSERTIONS (ADR-008)
  // =============================================================================
  describe('API Version Headers', () => {
    /**
     * Create an app that includes the deprecation middleware to test version headers.
     * This simulates the actual production setup where routes are mounted via versioned.ts.
     */
    const createVersionedTestApp = () => {
      const versionedApp = express();
      versionedApp.use(express.json());
      versionedApp.use(cookieParser());
      versionedApp.use((req, _res, next) => {
        req.log = mockLogger;
        next();
      });
      // Apply the deprecation middleware before the auth router
      versionedApp.use('/api/v1/auth', addDeprecationHeaders('v1'), authRouter);
      // Add error handler to ensure error responses are properly formatted
      versionedApp.use(errorHandler);
      return versionedApp;
    };
    it('should include X-API-Version: v1 header in POST /register success response', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      const mockNewUser = createMockUserProfile({
        user: { user_id: 'new-user-id', email: 'version-test@test.com' },
      });
      mockedAuthService.registerAndLoginUser.mockResolvedValue({
        newUserProfile: mockNewUser,
        accessToken: 'new-access-token',
        refreshToken: 'new-refresh-token',
      });
      // Act
      const response = await supertest(versionedApp).post('/api/v1/auth/register').send({
        email: 'version-test@test.com',
        password: 'a-Very-Strong-Password-123!',
        full_name: 'Test User',
      });
      // Assert
      expect(response.status).toBe(201);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version: v1 header in POST /login success response', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      mockedAuthService.handleSuccessfulLogin.mockResolvedValue({
        accessToken: 'new-access-token',
        refreshToken: 'new-refresh-token',
      });
      // Act
      const response = await supertest(versionedApp).post('/api/v1/auth/login').send({
        email: 'test@test.com',
        password: 'password123',
      });
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version: v1 header in POST /forgot-password response', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      mockedAuthService.resetPassword.mockResolvedValue('mock-reset-token');
      // Act
      const response = await supertest(versionedApp).post('/api/v1/auth/forgot-password').send({
        email: 'test@test.com',
      });
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version: v1 header in POST /reset-password response', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      mockedAuthService.updatePassword.mockResolvedValue(true);
      // Act
      const response = await supertest(versionedApp).post('/api/v1/auth/reset-password').send({
        token: 'valid-token',
        newPassword: 'a-Very-Strong-Password-789!',
      });
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version: v1 header in POST /refresh-token response', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      mockedAuthService.refreshAccessToken.mockResolvedValue({ accessToken: 'new-access-token' });
      // Act
      const response = await supertest(versionedApp)
        .post('/api/v1/auth/refresh-token')
        .set('Cookie', 'refreshToken=valid-refresh-token');
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version: v1 header in POST /logout response', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      mockedAuthService.logout.mockResolvedValue(undefined);
      // Act
      const response = await supertest(versionedApp)
        .post('/api/v1/auth/logout')
        .set('Cookie', 'refreshToken=some-valid-token');
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version header even on validation error responses', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      // Act - send invalid email format
      const response = await supertest(versionedApp).post('/api/v1/auth/login').send({
        email: 'not-an-email',
        password: 'password123',
      });
      // Assert
      expect(response.status).toBe(400);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version header on authentication failure responses', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      // Act
      const response = await supertest(versionedApp).post('/api/v1/auth/login').send({
        email: 'test@test.com',
        password: 'wrong_password',
      });
      // Assert
      expect(response.status).toBe(401);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
  });
 });
--- a/src/routes/health.routes.test.ts
+++ b/src/routes/health.routes.test.ts
@@ -1,10 +1,13 @@
 // src/routes/health.routes.test.ts
 import { describe, it, expect, vi, beforeEach, afterEach, type Mocked } from 'vitest';
 import supertest from 'supertest';
 import express from 'express';
 import { connection as redisConnection } from '../services/queueService.server';
 import fs from 'node:fs/promises';
 import { createTestApp } from '../tests/utils/createTestApp';
 import { mockLogger } from '../tests/utils/mockLogger';
 import { DEPRECATION_HEADERS, addDeprecationHeaders } from '../middleware/deprecation.middleware';
 import { errorHandler } from '../middleware/errorHandler';
 // 1. Mock the dependencies of the health router.
 vi.mock('../services/db/connection.db', () => ({
@@ -36,6 +39,13 @@ import * as dbConnection from '../services/db/connection.db';
 vi.mock('../services/logger.server', async () => ({
  // Use async import to avoid hoisting issues with mockLogger
  logger: (await import('../tests/utils/mockLogger')).mockLogger,
  createScopedLogger: vi.fn(() => ({
    debug: vi.fn(),
    info: vi.fn(),
    warn: vi.fn(),
    error: vi.fn(),
    child: vi.fn().mockReturnThis(),
  })),
 }));
 // Cast the mocked import to a Mocked type for type-safe access to mock functions.
@@ -855,4 +865,176 @@ describe('Health Routes (/api/v1/health)', () => {
      });
    });
  });
  // =============================================================================
  // API VERSION HEADER ASSERTIONS (ADR-008)
  // =============================================================================
  describe('API Version Headers', () => {
    /**
     * Create an app that includes the deprecation middleware to test version headers.
     * This simulates the actual production setup where routes are mounted via versioned.ts.
     */
    const createVersionedTestApp = () => {
      const versionedApp = express();
      versionedApp.use(express.json());
      versionedApp.use((req, _res, next) => {
        req.log = mockLogger;
        next();
      });
      // Apply the deprecation middleware before the health router
      versionedApp.use('/api/v1/health', addDeprecationHeaders('v1'), healthRouter);
      // Add error handler to ensure error responses are properly formatted
      versionedApp.use(errorHandler);
      return versionedApp;
    };
    it('should include X-API-Version: v1 header in GET /ping response', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      // Act
      const response = await supertest(versionedApp).get('/api/v1/health/ping');
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version: v1 header in GET /live response', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      // Act
      const response = await supertest(versionedApp).get('/api/v1/health/live');
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version: v1 header in GET /time response', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      vi.useFakeTimers();
      vi.setSystemTime(new Date('2024-03-15T10:30:00.000Z'));
      // Act
      const response = await supertest(versionedApp).get('/api/v1/health/time');
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version: v1 header in GET /redis response (success)', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      mockedRedisConnection.ping.mockResolvedValue('PONG');
      // Act
      const response = await supertest(versionedApp).get('/api/v1/health/redis');
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version: v1 header in GET /db-schema response', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      mockedDbConnection.checkTablesExist.mockResolvedValue([]);
      // Act
      const response = await supertest(versionedApp).get('/api/v1/health/db-schema');
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version: v1 header in GET /storage response', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      mockedFs.access.mockResolvedValue(undefined);
      // Act
      const response = await supertest(versionedApp).get('/api/v1/health/storage');
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version: v1 header in GET /db-pool response', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      mockedDbConnection.getPoolStatus.mockReturnValue({
        totalCount: 10,
        idleCount: 8,
        waitingCount: 1,
      });
      // Act
      const response = await supertest(versionedApp).get('/api/v1/health/db-pool');
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version: v1 header in GET /ready response', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      const mockPool = { query: vi.fn().mockResolvedValue({ rows: [{ 1: 1 }] }) };
      mockedDbConnection.getPool.mockReturnValue(mockPool as never);
      mockedDbConnection.getPoolStatus.mockReturnValue({
        totalCount: 10,
        idleCount: 8,
        waitingCount: 1,
      });
      mockedRedisConnection.ping.mockResolvedValue('PONG');
      mockedFs.access.mockResolvedValue(undefined);
      // Act
      const response = await supertest(versionedApp).get('/api/v1/health/ready');
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version: v1 header in GET /startup response', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      const mockPool = { query: vi.fn().mockResolvedValue({ rows: [{ 1: 1 }] }) };
      mockedDbConnection.getPool.mockReturnValue(mockPool as never);
      mockedDbConnection.getPoolStatus.mockReturnValue({
        totalCount: 10,
        idleCount: 8,
        waitingCount: 1,
      });
      // Act
      const response = await supertest(versionedApp).get('/api/v1/health/startup');
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version header even on error responses', async () => {
      // Arrange
      const versionedApp = createVersionedTestApp();
      const redisError = new Error('Connection timed out');
      mockedRedisConnection.ping.mockRejectedValue(redisError);
      // Act
      const response = await supertest(versionedApp).get('/api/v1/health/redis');
      // Assert
      expect(response.status).toBe(500);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
  });
 });
--- a/src/routes/health.routes.ts
+++ b/src/routes/health.routes.ts
@@ -619,10 +619,10 @@ router.get(
      let hasErrors = false;
      for (const metric of queueMetrics) {
-        if ('error' in metric) {
+        if ('error' in metric && metric.error) {
          queuesData[metric.name] = { error: metric.error };
          hasErrors = true;
-        } else {
+        } else if ('counts' in metric && metric.counts) {
          queuesData[metric.name] = metric.counts;
        }
      }
--- a/src/routes/versioned.test.ts
+++ b/src/routes/versioned.test.ts
@@ -0,0 +1,748 @@
 // src/routes/versioned.test.ts
 /**
 * @file Unit tests for the version router factory.
 * Tests ADR-008 Phase 2: API Versioning Infrastructure.
 *
 * These tests verify:
 * - Router creation for different API versions
 * - X-API-Version header on all responses
 * - Deprecation headers for deprecated versions
 * - Route availability filtering by version
 * - Router caching behavior
 * - Utility functions
 */
 import { describe, it, expect, vi, beforeEach, afterEach, beforeAll, afterAll } from 'vitest';
 import supertest from 'supertest';
 import express, { Router, Request, Response } from 'express';
 import type { Logger } from 'pino';
 // --- Hoisted Mock Setup ---
 // vi.hoisted() is executed before imports, making values available in vi.mock factories
 const { mockLoggerFn, inlineMockLogger, createMockRouterFactory } = vi.hoisted(() => {
  const mockLoggerFn = vi.fn();
  const inlineMockLogger = {
    info: mockLoggerFn,
    debug: mockLoggerFn,
    error: mockLoggerFn,
    warn: mockLoggerFn,
    fatal: mockLoggerFn,
    trace: mockLoggerFn,
    silent: mockLoggerFn,
    child: vi.fn().mockReturnThis(),
  } as unknown as Logger;
  // Factory function to create mock routers
  const createMockRouterFactory = (name: string) => {
    // Import express Router here since we're in hoisted context
    // eslint-disable-next-line @typescript-eslint/no-require-imports
    const { Router: ExpressRouter } = require('express');
    const router = ExpressRouter();
    router.get('/test', (req: Request, res: Response) => {
      res.json({ router: name, version: (req as { apiVersion?: string }).apiVersion });
    });
    return router;
  };
  return { mockLoggerFn, inlineMockLogger, createMockRouterFactory };
 });
 // --- Mock Setup ---
 // Mock the logger before any imports that use it
 vi.mock('../services/logger.server', () => ({
  createScopedLogger: vi.fn(() => inlineMockLogger),
  logger: inlineMockLogger,
 }));
 // Mock all domain routers with minimal test routers
 // This isolates the versioned.ts tests from actual route implementations
 vi.mock('./auth.routes', () => ({ default: createMockRouterFactory('auth') }));
 vi.mock('./health.routes', () => ({ default: createMockRouterFactory('health') }));
 vi.mock('./system.routes', () => ({ default: createMockRouterFactory('system') }));
 vi.mock('./user.routes', () => ({ default: createMockRouterFactory('user') }));
 vi.mock('./ai.routes', () => ({ default: createMockRouterFactory('ai') }));
 vi.mock('./admin.routes', () => ({ default: createMockRouterFactory('admin') }));
 vi.mock('./budget.routes', () => ({ default: createMockRouterFactory('budget') }));
 vi.mock('./gamification.routes', () => ({ default: createMockRouterFactory('gamification') }));
 vi.mock('./flyer.routes', () => ({ default: createMockRouterFactory('flyer') }));
 vi.mock('./recipe.routes', () => ({ default: createMockRouterFactory('recipe') }));
 vi.mock('./personalization.routes', () => ({
  default: createMockRouterFactory('personalization'),
 }));
 vi.mock('./price.routes', () => ({ default: createMockRouterFactory('price') }));
 vi.mock('./stats.routes', () => ({ default: createMockRouterFactory('stats') }));
 vi.mock('./upc.routes', () => ({ default: createMockRouterFactory('upc') }));
 vi.mock('./inventory.routes', () => ({ default: createMockRouterFactory('inventory') }));
 vi.mock('./receipt.routes', () => ({ default: createMockRouterFactory('receipt') }));
 vi.mock('./deals.routes', () => ({ default: createMockRouterFactory('deals') }));
 vi.mock('./reactions.routes', () => ({ default: createMockRouterFactory('reactions') }));
 vi.mock('./store.routes', () => ({ default: createMockRouterFactory('store') }));
 vi.mock('./category.routes', () => ({ default: createMockRouterFactory('category') }));
 // Import types and modules AFTER mocks are set up
 import type { ApiVersion, VersionConfig } from '../config/apiVersions';
 import { DEPRECATION_HEADERS } from '../middleware/deprecation.middleware';
 import { errorHandler } from '../middleware/errorHandler';
 // Import the module under test
 import {
  createVersionedRouter,
  createApiRouter,
  getRegisteredPaths,
  getRouteByPath,
  getRoutesForVersion,
  clearRouterCache,
  refreshRouterCache,
  ROUTES,
 } from './versioned';
 import { API_VERSIONS, VERSION_CONFIGS } from '../config/apiVersions';
 // --- Test Utilities ---
 /**
 * Creates a test Express app with the given router mounted at the specified path.
 */
 function createTestApp(router: Router, basePath = '/api') {
  const app = express();
  app.use(express.json());
  // Inject mock logger into requests
  app.use((req, res, next) => {
    req.log = inlineMockLogger;
    next();
  });
  app.use(basePath, router);
  app.use(errorHandler);
  return app;
 }
 /**
 * Stores original VERSION_CONFIGS for restoration after tests that modify it.
 */
 let originalVersionConfigs: Record<ApiVersion, VersionConfig>;
 // --- Tests ---
 describe('Versioned Router Factory', () => {
  beforeAll(() => {
    // Store original configs before any tests modify them
    originalVersionConfigs = JSON.parse(JSON.stringify(VERSION_CONFIGS));
  });
  beforeEach(() => {
    vi.clearAllMocks();
    // Clear router cache before each test to ensure fresh state
    clearRouterCache();
  });
  afterEach(() => {
    // Restore original VERSION_CONFIGS after each test
    Object.assign(VERSION_CONFIGS, originalVersionConfigs);
  });
  afterAll(() => {
    // Final restoration
    Object.assign(VERSION_CONFIGS, originalVersionConfigs);
  });
  // =========================================================================
  // createVersionedRouter() Tests
  // =========================================================================
  describe('createVersionedRouter()', () => {
    describe('route registration', () => {
      it('should create router with all expected routes for v1', () => {
        // Act
        const router = createVersionedRouter('v1');
        // Assert - router should be created
        expect(router).toBeDefined();
        expect(typeof router).toBe('function'); // Express routers are functions
      });
      it('should create router with all expected routes for v2', () => {
        // Act
        const router = createVersionedRouter('v2');
        // Assert
        expect(router).toBeDefined();
        expect(typeof router).toBe('function');
      });
      it('should register routes in the expected order', () => {
        // The ROUTES array defines registration order
        const expectedOrder = [
          'auth',
          'health',
          'system',
          'users',
          'ai',
          'admin',
          'budgets',
          'achievements',
          'flyers',
          'recipes',
          'personalization',
          'price-history',
          'stats',
          'upc',
          'inventory',
          'receipts',
          'deals',
          'reactions',
          'stores',
          'categories',
        ];
        // Assert order matches
        const registeredPaths = ROUTES.map((r) => r.path);
        expect(registeredPaths).toEqual(expectedOrder);
      });
      it('should skip routes not available for specified version', () => {
        // Assert - getRoutesForVersion should filter correctly
        const v1Routes = getRoutesForVersion('v1');
        const v2Routes = getRoutesForVersion('v2');
        // All routes without versions restriction should be in both
        expect(v1Routes.length).toBe(ROUTES.length);
        expect(v2Routes.length).toBe(ROUTES.length);
        // If we had a version-restricted route, it would only appear in that version
        // This tests the filtering logic via getRoutesForVersion
        expect(v1Routes.some((r) => r.path === 'auth')).toBe(true);
        expect(v2Routes.some((r) => r.path === 'auth')).toBe(true);
      });
    });
    describe('X-API-Version header', () => {
      it('should add X-API-Version header to all v1 responses', async () => {
        // Arrange
        const router = createVersionedRouter('v1');
        const app = createTestApp(router, '/api/v1');
        // Act
        const response = await supertest(app).get('/api/v1/health/test');
        // Assert
        expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
      });
      it('should add X-API-Version header to all v2 responses', async () => {
        // Arrange
        const router = createVersionedRouter('v2');
        const app = createTestApp(router, '/api/v2');
        // Act
        const response = await supertest(app).get('/api/v2/health/test');
        // Assert
        expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v2');
      });
      it('should NOT add X-API-Version header when deprecation middleware is disabled', async () => {
        // Arrange - create router with deprecation headers disabled
        const router = createVersionedRouter('v1', { applyDeprecationHeaders: false });
        const app = createTestApp(router, '/api/v1');
        // Act
        const response = await supertest(app).get('/api/v1/health/test');
        // Assert - header should NOT be present when deprecation middleware is disabled
        expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBeUndefined();
      });
    });
    describe('deprecation headers', () => {
      it('should not add deprecation headers for active versions', async () => {
        // Arrange - v1 is active by default
        const router = createVersionedRouter('v1');
        const app = createTestApp(router, '/api/v1');
        // Act
        const response = await supertest(app).get('/api/v1/health/test');
        // Assert - no deprecation headers
        expect(response.headers[DEPRECATION_HEADERS.DEPRECATION.toLowerCase()]).toBeUndefined();
        expect(response.headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBeUndefined();
        expect(response.headers[DEPRECATION_HEADERS.LINK.toLowerCase()]).toBeUndefined();
        expect(
          response.headers[DEPRECATION_HEADERS.DEPRECATION_NOTICE.toLowerCase()],
        ).toBeUndefined();
      });
      it('should add deprecation headers when version is deprecated', async () => {
        // Arrange - Temporarily mark v1 as deprecated
        VERSION_CONFIGS.v1 = {
          version: 'v1',
          status: 'deprecated',
          sunsetDate: '2027-01-01T00:00:00Z',
          successorVersion: 'v2',
        };
        // Clear cache and create fresh router with updated config
        clearRouterCache();
        const router = createVersionedRouter('v1');
        const app = createTestApp(router, '/api/v1');
        // Act
        const response = await supertest(app).get('/api/v1/health/test');
        // Assert - deprecation headers present
        expect(response.headers[DEPRECATION_HEADERS.DEPRECATION.toLowerCase()]).toBe('true');
        expect(response.headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBe(
          '2027-01-01T00:00:00Z',
        );
        expect(response.headers[DEPRECATION_HEADERS.LINK.toLowerCase()]).toBe(
          '</api/v2>; rel="successor-version"',
        );
        expect(response.headers[DEPRECATION_HEADERS.DEPRECATION_NOTICE.toLowerCase()]).toContain(
          'deprecated',
        );
      });
      it('should include sunset date in deprecation headers when provided', async () => {
        // Arrange
        VERSION_CONFIGS.v1 = {
          version: 'v1',
          status: 'deprecated',
          sunsetDate: '2028-06-15T00:00:00Z',
          successorVersion: 'v2',
        };
        clearRouterCache();
        const router = createVersionedRouter('v1');
        const app = createTestApp(router, '/api/v1');
        // Act
        const response = await supertest(app).get('/api/v1/health/test');
        // Assert
        expect(response.headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBe(
          '2028-06-15T00:00:00Z',
        );
      });
      it('should include successor version link when provided', async () => {
        // Arrange
        VERSION_CONFIGS.v1 = {
          version: 'v1',
          status: 'deprecated',
          successorVersion: 'v2',
        };
        clearRouterCache();
        const router = createVersionedRouter('v1');
        const app = createTestApp(router, '/api/v1');
        // Act
        const response = await supertest(app).get('/api/v1/health/test');
        // Assert
        expect(response.headers[DEPRECATION_HEADERS.LINK.toLowerCase()]).toBe(
          '</api/v2>; rel="successor-version"',
        );
      });
      it('should not include sunset date when not provided', async () => {
        // Arrange - deprecated without sunset date
        VERSION_CONFIGS.v1 = {
          version: 'v1',
          status: 'deprecated',
          // No sunsetDate
        };
        clearRouterCache();
        const router = createVersionedRouter('v1');
        const app = createTestApp(router, '/api/v1');
        // Act
        const response = await supertest(app).get('/api/v1/health/test');
        // Assert
        expect(response.headers[DEPRECATION_HEADERS.DEPRECATION.toLowerCase()]).toBe('true');
        expect(response.headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBeUndefined();
      });
    });
    describe('router options', () => {
      it('should apply deprecation headers middleware by default', async () => {
        // Arrange
        const router = createVersionedRouter('v1');
        const app = createTestApp(router, '/api/v1');
        // Act
        const response = await supertest(app).get('/api/v1/health/test');
        // Assert - X-API-Version should be set (proves middleware ran)
        expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
      });
      it('should skip deprecation headers middleware when disabled', async () => {
        // Arrange
        const router = createVersionedRouter('v1', { applyDeprecationHeaders: false });
        const app = createTestApp(router, '/api/v1');
        // Act
        const response = await supertest(app).get('/api/v1/health/test');
        // Assert - X-API-Version should NOT be set
        expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBeUndefined();
      });
    });
  });
  // =========================================================================
  // createApiRouter() Tests
  // =========================================================================
  describe('createApiRouter()', () => {
    it('should mount all supported versions', async () => {
      // Arrange
      const apiRouter = createApiRouter();
      const app = createTestApp(apiRouter, '/api');
      // Act & Assert - v1 should work
      const v1Response = await supertest(app).get('/api/v1/health/test');
      expect(v1Response.status).toBe(200);
      expect(v1Response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
      // Act & Assert - v2 should work
      const v2Response = await supertest(app).get('/api/v2/health/test');
      expect(v2Response.status).toBe(200);
      expect(v2Response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v2');
    });
    it('should return 404 for unsupported versions', async () => {
      // Arrange
      const apiRouter = createApiRouter();
      const app = createTestApp(apiRouter, '/api');
      // Act
      const response = await supertest(app).get('/api/v99/health/test');
      // Assert
      expect(response.status).toBe(404);
      expect(response.body.error.code).toBe('UNSUPPORTED_VERSION');
      expect(response.body.error.message).toContain('v99');
      expect(response.body.error.details.supportedVersions).toEqual(['v1', 'v2']);
    });
    it('should route to correct versioned router based on URL version', async () => {
      // Arrange
      const apiRouter = createApiRouter();
      const app = createTestApp(apiRouter, '/api');
      // Act
      const v1Response = await supertest(app).get('/api/v1/health/test');
      const v2Response = await supertest(app).get('/api/v2/health/test');
      // Assert - each response should indicate the correct version
      expect(v1Response.body.version).toBe('v1');
      expect(v2Response.body.version).toBe('v2');
    });
    it('should handle requests to various domain routers', async () => {
      // Arrange
      const apiRouter = createApiRouter();
      const app = createTestApp(apiRouter, '/api');
      // Act & Assert - multiple domain routers
      const authResponse = await supertest(app).get('/api/v1/auth/test');
      expect(authResponse.status).toBe(200);
      expect(authResponse.body.router).toBe('auth');
      const flyerResponse = await supertest(app).get('/api/v1/flyers/test');
      expect(flyerResponse.status).toBe(200);
      expect(flyerResponse.body.router).toBe('flyer');
      const storeResponse = await supertest(app).get('/api/v1/stores/test');
      expect(storeResponse.status).toBe(200);
      expect(storeResponse.body.router).toBe('store');
    });
  });
  // =========================================================================
  // Utility Functions Tests
  // =========================================================================
  describe('getRegisteredPaths()', () => {
    it('should return all registered route paths', () => {
      // Act
      const paths = getRegisteredPaths();
      // Assert
      expect(paths).toBeInstanceOf(Array);
      expect(paths.length).toBe(ROUTES.length);
      expect(paths).toContain('auth');
      expect(paths).toContain('health');
      expect(paths).toContain('flyers');
      expect(paths).toContain('stores');
      expect(paths).toContain('categories');
    });
    it('should return paths in registration order', () => {
      // Act
      const paths = getRegisteredPaths();
      // Assert - first and last should match ROUTES order
      expect(paths[0]).toBe('auth');
      expect(paths[paths.length - 1]).toBe('categories');
    });
  });
  describe('getRouteByPath()', () => {
    it('should return correct registration for existing path', () => {
      // Act
      const authRoute = getRouteByPath('auth');
      const healthRoute = getRouteByPath('health');
      // Assert
      expect(authRoute).toBeDefined();
      expect(authRoute?.path).toBe('auth');
      expect(authRoute?.description).toContain('Authentication');
      expect(healthRoute).toBeDefined();
      expect(healthRoute?.path).toBe('health');
      expect(healthRoute?.description).toContain('Health');
    });
    it('should return undefined for non-existent path', () => {
      // Act
      const result = getRouteByPath('non-existent-path');
      // Assert
      expect(result).toBeUndefined();
    });
    it('should return undefined for empty string', () => {
      // Act
      const result = getRouteByPath('');
      // Assert
      expect(result).toBeUndefined();
    });
  });
  describe('getRoutesForVersion()', () => {
    it('should return all routes when no version restrictions exist', () => {
      // Act
      const v1Routes = getRoutesForVersion('v1');
      const v2Routes = getRoutesForVersion('v2');
      // Assert - all routes should be available in both versions
      // (since none of the default routes have version restrictions)
      expect(v1Routes.length).toBe(ROUTES.length);
      expect(v2Routes.length).toBe(ROUTES.length);
    });
    it('should filter routes based on version restrictions', () => {
      // This tests the filtering logic - routes with versions array
      // should only appear for versions listed in that array
      const v1Routes = getRoutesForVersion('v1');
      // All routes should have path and router properties
      v1Routes.forEach((route) => {
        expect(route.path).toBeDefined();
        expect(route.router).toBeDefined();
        expect(route.description).toBeDefined();
      });
    });
    it('should include routes without version restrictions in all versions', () => {
      // Routes without versions array should appear in all versions
      const authRoute = ROUTES.find((r) => r.path === 'auth');
      expect(authRoute?.versions).toBeUndefined(); // No version restriction
      const v1Routes = getRoutesForVersion('v1');
      const v2Routes = getRoutesForVersion('v2');
      expect(v1Routes.some((r) => r.path === 'auth')).toBe(true);
      expect(v2Routes.some((r) => r.path === 'auth')).toBe(true);
    });
  });
  // =========================================================================
  // Router Cache Tests
  // =========================================================================
  describe('router cache', () => {
    it('should cache routers after creation', async () => {
      // Arrange
      const apiRouter = createApiRouter();
      const app = createTestApp(apiRouter, '/api');
      // Act - make multiple requests (should use cached router)
      const response1 = await supertest(app).get('/api/v1/health/test');
      const response2 = await supertest(app).get('/api/v1/health/test');
      // Assert - both requests should succeed (proving cache works)
      expect(response1.status).toBe(200);
      expect(response2.status).toBe(200);
    });
    it('should clear cache with clearRouterCache()', () => {
      // Arrange - create some routers to populate cache
      createVersionedRouter('v1');
      createVersionedRouter('v2');
      // Act
      clearRouterCache();
      // Assert - cache should be cleared (logger would have logged)
      expect(mockLoggerFn).toHaveBeenCalledWith('Versioned router cache cleared');
    });
    it('should refresh cache with refreshRouterCache()', () => {
      // Arrange
      createVersionedRouter('v1');
      // Act
      refreshRouterCache();
      // Assert - cache should be refreshed (logger would have logged)
      expect(mockLoggerFn).toHaveBeenCalledWith(
        expect.objectContaining({ cachedVersions: expect.any(Array) }),
        'Versioned router cache refreshed',
      );
    });
    it('should create routers on-demand if not in cache', async () => {
      // Arrange
      clearRouterCache();
      const apiRouter = createApiRouter();
      const app = createTestApp(apiRouter, '/api');
      // Act - request should trigger on-demand router creation
      const response = await supertest(app).get('/api/v1/health/test');
      // Assert
      expect(response.status).toBe(200);
    });
  });
  // =========================================================================
  // ROUTES Configuration Tests
  // =========================================================================
  describe('ROUTES configuration', () => {
    it('should have all required properties for each route', () => {
      ROUTES.forEach((route) => {
        expect(route.path).toBeDefined();
        expect(typeof route.path).toBe('string');
        expect(route.path.length).toBeGreaterThan(0);
        expect(route.router).toBeDefined();
        expect(typeof route.router).toBe('function');
        expect(route.description).toBeDefined();
        expect(typeof route.description).toBe('string');
        expect(route.description.length).toBeGreaterThan(0);
        // versions is optional
        if (route.versions !== undefined) {
          expect(Array.isArray(route.versions)).toBe(true);
          route.versions.forEach((v) => {
            expect(API_VERSIONS).toContain(v);
          });
        }
      });
    });
    it('should not have duplicate paths', () => {
      const paths = ROUTES.map((r) => r.path);
      const uniquePaths = new Set(paths);
      expect(uniquePaths.size).toBe(paths.length);
    });
    it('should have expected number of routes', () => {
      // This ensures we don't accidentally remove routes
      expect(ROUTES.length).toBe(20);
    });
    it('should include all core domain routers', () => {
      const paths = getRegisteredPaths();
      const expectedRoutes = [
        'auth',
        'health',
        'system',
        'users',
        'ai',
        'admin',
        'budgets',
        'achievements',
        'flyers',
        'recipes',
        'personalization',
        'price-history',
        'stats',
        'upc',
        'inventory',
        'receipts',
        'deals',
        'reactions',
        'stores',
        'categories',
      ];
      expectedRoutes.forEach((route) => {
        expect(paths).toContain(route);
      });
    });
  });
  // =========================================================================
  // Edge Cases and Error Handling
  // =========================================================================
  describe('edge cases', () => {
    it('should handle requests to nested routes', async () => {
      // Arrange
      const router = createVersionedRouter('v1');
      const app = createTestApp(router, '/api/v1');
      // Act - request to nested path
      const response = await supertest(app).get('/api/v1/health/test');
      // Assert
      expect(response.status).toBe(200);
      expect(response.body.router).toBe('health');
    });
    it('should return 404 for non-existent routes within valid version', async () => {
      // Arrange
      const router = createVersionedRouter('v1');
      const app = createTestApp(router, '/api/v1');
      // Act - request to non-existent domain
      const response = await supertest(app).get('/api/v1/nonexistent/endpoint');
      // Assert
      expect(response.status).toBe(404);
    });
    it('should handle multiple concurrent requests', async () => {
      // Arrange
      const apiRouter = createApiRouter();
      const app = createTestApp(apiRouter, '/api');
      // Act - make concurrent requests
      const requests = [
        supertest(app).get('/api/v1/health/test'),
        supertest(app).get('/api/v1/auth/test'),
        supertest(app).get('/api/v2/health/test'),
        supertest(app).get('/api/v2/flyers/test'),
      ];
      const responses = await Promise.all(requests);
      // Assert - all should succeed
      responses.forEach((response) => {
        expect(response.status).toBe(200);
      });
    });
  });
 });
--- a/src/routes/versioned.ts
+++ b/src/routes/versioned.ts
@@ -0,0 +1,478 @@
 // src/routes/versioned.ts
 /**
 * @file Version Router Factory - ADR-008 Phase 2 Implementation
 *
 * Creates version-specific Express routers that manage route registration
 * for different API versions. This factory ensures consistent middleware
 * application and proper route ordering across all API versions.
 *
 * Key responsibilities:
 * - Create routers for each supported API version
 * - Apply version detection and deprecation middleware
 * - Register domain routers in correct precedence order
 * - Support version-specific route availability
 * - Add X-API-Version header to all responses
 *
 * @see docs/architecture/api-versioning-infrastructure.md
 * @see docs/adr/0008-api-versioning-strategy.md
 *
 * @example
 * ```typescript
 * // In server.ts:
 * import { createApiRouter, createVersionedRouter } from './src/routes/versioned';
 *
 * // Option 1: Mount all versions at once
 * app.use('/api', createApiRouter());
 *
 * // Option 2: Mount versions individually
 * app.use('/api/v1', createVersionedRouter('v1'));
 * app.use('/api/v2', createVersionedRouter('v2'));
 * ```
 */
 import { Router } from 'express';
 import { ApiVersion, API_VERSIONS, SUPPORTED_VERSIONS } from '../config/apiVersions';
 import { detectApiVersion } from '../middleware/apiVersion.middleware';
 import { addDeprecationHeaders } from '../middleware/deprecation.middleware';
 import { createScopedLogger } from '../services/logger.server';
 // --- Domain Router Imports ---
 // These are imported in the order they are registered in server.ts
 import authRouter from './auth.routes';
 import healthRouter from './health.routes';
 import systemRouter from './system.routes';
 import userRouter from './user.routes';
 import aiRouter from './ai.routes';
 import adminRouter from './admin.routes';
 import budgetRouter from './budget.routes';
 import gamificationRouter from './gamification.routes';
 import flyerRouter from './flyer.routes';
 import recipeRouter from './recipe.routes';
 import personalizationRouter from './personalization.routes';
 import priceRouter from './price.routes';
 import statsRouter from './stats.routes';
 import upcRouter from './upc.routes';
 import inventoryRouter from './inventory.routes';
 import receiptRouter from './receipt.routes';
 import dealsRouter from './deals.routes';
 import reactionsRouter from './reactions.routes';
 import storeRouter from './store.routes';
 import categoryRouter from './category.routes';
 // Module-scoped logger for versioned router operations
 const versionedRouterLogger = createScopedLogger('versioned-router');
 // --- Type Definitions ---
 /**
 * Configuration for registering a route under versioned API.
 *
 * @property path - The URL path segment (e.g., 'auth', 'users', 'flyers')
 * @property router - The Express router instance handling this path
 * @property description - Human-readable description of the route's purpose
 * @property versions - Optional array of versions where this route is available.
 *                      If omitted, the route is available in all versions.
 */
 export interface RouteRegistration {
  /** URL path segment (mounted at /{version}/{path}) */
  path: string;
  /** Express router instance for this domain */
  router: Router;
  /** Human-readable description for documentation and logging */
  description: string;
  /** Optional: Specific versions where this route is available (defaults to all) */
  versions?: ApiVersion[];
 }
 /**
 * Options for creating a versioned router.
 */
 export interface VersionedRouterOptions {
  /** Whether to apply version detection middleware (default: true) */
  applyVersionDetection?: boolean;
  /** Whether to apply deprecation headers middleware (default: true) */
  applyDeprecationHeaders?: boolean;
 }
 // --- Route Registration Configuration ---
 /**
 * Master list of all route registrations.
 *
 * IMPORTANT: The order of routes is critical for correct matching.
 * More specific routes should be registered before more general ones.
 * This order mirrors the registration in server.ts exactly.
 *
 * Each entry includes:
 * - path: The URL segment (e.g., 'auth' -> /api/v1/auth)
 * - router: The Express router handling the routes
 * - description: Purpose documentation
 * - versions: Optional array to restrict availability to specific versions
 */
 export const ROUTES: RouteRegistration[] = [
  // 1. Authentication routes for login, registration, etc.
  {
    path: 'auth',
    router: authRouter,
    description: 'Authentication routes for login, registration, password reset',
  },
  // 2. Health check routes for monitoring and liveness probes
  {
    path: 'health',
    router: healthRouter,
    description: 'Health check endpoints for monitoring and liveness probes',
  },
  // 3. System routes for PM2 status, server info, etc.
  {
    path: 'system',
    router: systemRouter,
    description: 'System administration routes for PM2 status and server info',
  },
  // 4. General authenticated user routes
  {
    path: 'users',
    router: userRouter,
    description: 'User profile and account management routes',
  },
  // 5. AI routes, some of which use optional authentication
  {
    path: 'ai',
    router: aiRouter,
    description: 'AI-powered features including flyer processing and analysis',
  },
  // 6. Admin routes, protected by admin-level checks
  {
    path: 'admin',
    router: adminRouter,
    description: 'Administrative routes for user and system management',
  },
  // 7. Budgeting and spending analysis routes
  {
    path: 'budgets',
    router: budgetRouter,
    description: 'Budget management and spending analysis routes',
  },
  // 8. Gamification routes for achievements
  {
    path: 'achievements',
    router: gamificationRouter,
    description: 'Gamification and achievement system routes',
  },
  // 9. Public flyer routes
  {
    path: 'flyers',
    router: flyerRouter,
    description: 'Flyer listing, search, and item management routes',
  },
  // 10. Public recipe routes
  {
    path: 'recipes',
    router: recipeRouter,
    description: 'Recipe discovery, saving, and recommendation routes',
  },
  // 11. Public personalization data routes (master items, etc.)
  {
    path: 'personalization',
    router: personalizationRouter,
    description: 'Personalization data including master items and preferences',
  },
  // 12. Price history routes
  {
    path: 'price-history',
    router: priceRouter,
    description: 'Price history tracking and trend analysis routes',
  },
  // 13. Public statistics routes
  {
    path: 'stats',
    router: statsRouter,
    description: 'Public statistics and analytics routes',
  },
  // 14. UPC barcode scanning routes
  {
    path: 'upc',
    router: upcRouter,
    description: 'UPC barcode scanning and product lookup routes',
  },
  // 15. Inventory and expiry tracking routes
  {
    path: 'inventory',
    router: inventoryRouter,
    description: 'Inventory management and expiry tracking routes',
  },
  // 16. Receipt scanning routes
  {
    path: 'receipts',
    router: receiptRouter,
    description: 'Receipt scanning and purchase history routes',
  },
  // 17. Deals and best prices routes
  {
    path: 'deals',
    router: dealsRouter,
    description: 'Deal discovery and best price comparison routes',
  },
  // 18. Reactions/social features routes
  {
    path: 'reactions',
    router: reactionsRouter,
    description: 'Social features including reactions and sharing',
  },
  // 19. Store management routes
  {
    path: 'stores',
    router: storeRouter,
    description: 'Store discovery, favorites, and location routes',
  },
  // 20. Category discovery routes (ADR-023: Database Normalization)
  {
    path: 'categories',
    router: categoryRouter,
    description: 'Category browsing and product categorization routes',
  },
 ];
 // --- Factory Functions ---
 /**
 * Creates a versioned Express router for a specific API version.
 *
 * This factory function:
 * 1. Creates a new Router instance with merged params
 * 2. Applies deprecation headers middleware (adds X-API-Version header)
 * 3. Registers all routes that are available for the specified version
 * 4. Maintains correct route registration order (specific before general)
 *
 * @param version - The API version to create a router for (e.g., 'v1', 'v2')
 * @param options - Optional configuration for middleware application
 * @returns Configured Express Router for the specified version
 *
 * @example
 * ```typescript
 * // Create a v1 router
 * const v1Router = createVersionedRouter('v1');
 * app.use('/api/v1', v1Router);
 *
 * // Create a v2 router with custom options
 * const v2Router = createVersionedRouter('v2', {
 *   applyDeprecationHeaders: true,
 * });
 * ```
 */
 export function createVersionedRouter(
  version: ApiVersion,
  options: VersionedRouterOptions = {},
 ): Router {
  const { applyDeprecationHeaders: shouldApplyDeprecationHeaders = true } = options;
  const router = Router({ mergeParams: true });
  versionedRouterLogger.info({ version, routeCount: ROUTES.length }, 'Creating versioned router');
  // Apply deprecation headers middleware.
  // This adds X-API-Version header to all responses and deprecation headers
  // when the version is marked as deprecated.
  if (shouldApplyDeprecationHeaders) {
    router.use(addDeprecationHeaders(version));
  }
  // Register all routes that are available for this version
  let registeredCount = 0;
  for (const route of ROUTES) {
    // Check if this route is available for the specified version.
    // If versions array is not specified, the route is available for all versions.
    if (route.versions && !route.versions.includes(version)) {
      versionedRouterLogger.debug(
        { version, path: route.path },
        'Skipping route not available for this version',
      );
      continue;
    }
    // Mount the router at the specified path
    router.use(`/${route.path}`, route.router);
    registeredCount++;
    versionedRouterLogger.debug(
      { version, path: route.path, description: route.description },
      'Registered route',
    );
  }
  versionedRouterLogger.info(
    { version, registeredCount, totalRoutes: ROUTES.length },
    'Versioned router created successfully',
  );
  return router;
 }
 /**
 * Creates the main API router that mounts all versioned routers.
 *
 * This function creates a parent router that:
 * 1. Applies version detection middleware at the /api/:version level
 * 2. Mounts versioned routers for each supported API version
 * 3. Returns 404 for unsupported versions via detectApiVersion middleware
 *
 * The router is designed to be mounted at `/api` in the main application:
 * - `/api/v1/*` routes to v1 router
 * - `/api/v2/*` routes to v2 router
 * - `/api/v99/*` returns 404 (unsupported version)
 *
 * @returns Express Router configured with all version-specific sub-routers
 *
 * @example
 * ```typescript
 * // In server.ts:
 * import { createApiRouter } from './src/routes/versioned';
 *
 * // Mount at /api - handles /api/v1/*, /api/v2/*, etc.
 * app.use('/api', createApiRouter());
 *
 * // Then add backwards compatibility redirect for unversioned paths:
 * app.use('/api', (req, res, next) => {
 *   if (!req.path.startsWith('/v1') && !req.path.startsWith('/v2')) {
 *     return res.redirect(301, `/api/v1${req.path}`);
 *   }
 *   next();
 * });
 * ```
 */
 export function createApiRouter(): Router {
  const router = Router({ mergeParams: true });
  versionedRouterLogger.info(
    { supportedVersions: SUPPORTED_VERSIONS },
    'Creating API router with all versions',
  );
  // Mount versioned routers under /:version path.
  // The detectApiVersion middleware validates the version and returns 404 for
  // unsupported versions before the domain routers are reached.
  router.use('/:version', detectApiVersion, (req, res, next) => {
    // At this point, req.apiVersion is guaranteed to be valid
    // (detectApiVersion returns 404 for invalid versions).
    // Route to the appropriate versioned router based on the detected version.
    const version = req.apiVersion;
    if (!version) {
      // This should not happen if detectApiVersion ran correctly,
      // but handle it defensively.
      return next('route');
    }
    // Get or create the versioned router.
    // We use a cache to avoid recreating routers on every request.
    const versionedRouter = versionedRouterCache.get(version);
    if (versionedRouter) {
      return versionedRouter(req, res, next);
    }
    // Fallback: version not in cache (should not happen with proper setup)
    versionedRouterLogger.warn(
      { version },
      'Versioned router not found in cache, creating on-demand',
    );
    const newRouter = createVersionedRouter(version);
    versionedRouterCache.set(version, newRouter);
    return newRouter(req, res, next);
  });
  versionedRouterLogger.info('API router created successfully');
  return router;
 }
 // --- Router Cache ---
 /**
 * Cache for versioned routers to avoid recreation on every request.
 * Pre-populated with routers for all supported versions.
 */
 const versionedRouterCache = new Map<ApiVersion, Router>();
 // Pre-populate the cache with all supported versions
 for (const version of API_VERSIONS) {
  versionedRouterCache.set(version, createVersionedRouter(version));
 }
 versionedRouterLogger.debug(
  { cachedVersions: Array.from(versionedRouterCache.keys()) },
  'Versioned router cache initialized',
 );
 // --- Utility Functions ---
 /**
 * Gets the list of all registered route paths.
 * Useful for documentation and debugging.
 *
 * @returns Array of registered route paths
 */
 export function getRegisteredPaths(): string[] {
  return ROUTES.map((route) => route.path);
 }
 /**
 * Gets route registration details for a specific path.
 *
 * @param path - The route path to look up
 * @returns RouteRegistration if found, undefined otherwise
 */
 export function getRouteByPath(path: string): RouteRegistration | undefined {
  return ROUTES.find((route) => route.path === path);
 }
 /**
 * Gets all routes available for a specific API version.
 *
 * @param version - The API version to filter by
 * @returns Array of RouteRegistrations available for the version
 */
 export function getRoutesForVersion(version: ApiVersion): RouteRegistration[] {
  return ROUTES.filter((route) => !route.versions || route.versions.includes(version));
 }
 /**
 * Clears the versioned router cache.
 * Primarily useful for testing to ensure fresh router instances.
 */
 export function clearRouterCache(): void {
  versionedRouterCache.clear();
  versionedRouterLogger.debug('Versioned router cache cleared');
 }
 /**
 * Refreshes the versioned router cache by recreating all routers.
 * Useful after configuration changes.
 */
 export function refreshRouterCache(): void {
  clearRouterCache();
  for (const version of API_VERSIONS) {
    versionedRouterCache.set(version, createVersionedRouter(version));
  }
  versionedRouterLogger.debug(
    { cachedVersions: Array.from(versionedRouterCache.keys()) },
    'Versioned router cache refreshed',
  );
 }
--- a/src/routes/versioning.integration.test.ts
+++ b/src/routes/versioning.integration.test.ts
@@ -0,0 +1,552 @@
 // src/routes/versioning.integration.test.ts
 /**
 * @file Integration tests for API versioning infrastructure (ADR-008).
 *
 * These tests verify the end-to-end behavior of the versioning middleware including:
 * - X-API-Version header presence in responses
 * - Unsupported version handling (404 with UNSUPPORTED_VERSION)
 * - Deprecation headers for deprecated versions
 * - Backwards compatibility redirect from unversioned paths
 *
 * Note: These tests use a minimal router setup to avoid deep import chains
 * from domain routers. Full integration testing of versioned routes is done
 * in individual route test files.
 *
 * @see docs/adr/0008-api-versioning-strategy.md
 * @see docs/architecture/api-versioning-infrastructure.md
 */
 import { describe, it, expect, vi, beforeEach, beforeAll, afterAll } from 'vitest';
 import supertest from 'supertest';
 import express, { Router } from 'express';
 import {
  VERSION_CONFIGS,
  ApiVersion,
  SUPPORTED_VERSIONS,
  DEFAULT_VERSION,
 } from '../config/apiVersions';
 import { DEPRECATION_HEADERS, addDeprecationHeaders } from '../middleware/deprecation.middleware';
 import { detectApiVersion, VERSION_ERROR_CODES } from '../middleware/apiVersion.middleware';
 import { sendSuccess } from '../utils/apiResponse';
 import { errorHandler } from '../middleware/errorHandler';
 // Mock the logger to avoid actual logging during tests
 vi.mock('../services/logger.server', () => ({
  createScopedLogger: vi.fn(() => ({
    debug: vi.fn(),
    info: vi.fn(),
    warn: vi.fn(),
    error: vi.fn(),
    child: vi.fn().mockReturnThis(),
  })),
  logger: {
    debug: vi.fn(),
    info: vi.fn(),
    warn: vi.fn(),
    error: vi.fn(),
    child: vi.fn().mockReturnThis(),
  },
 }));
 describe('API Versioning Integration Tests', () => {
  // Store original VERSION_CONFIGS to restore after tests
  let originalConfigs: Record<ApiVersion, typeof VERSION_CONFIGS.v1>;
  beforeAll(() => {
    // Save original configs
    originalConfigs = {
      v1: { ...VERSION_CONFIGS.v1 },
      v2: { ...VERSION_CONFIGS.v2 },
    };
  });
  afterAll(() => {
    // Restore original configs
    VERSION_CONFIGS.v1 = originalConfigs.v1;
    VERSION_CONFIGS.v2 = originalConfigs.v2;
  });
  beforeEach(() => {
    vi.clearAllMocks();
    // Reset configs to original before each test
    VERSION_CONFIGS.v1 = { ...originalConfigs.v1 };
    VERSION_CONFIGS.v2 = { ...originalConfigs.v2 };
  });
  /**
   * Create a minimal test router that returns a simple success response.
   * This avoids importing complex domain routers with many dependencies.
   */
  const createMinimalTestRouter = (): Router => {
    const router = Router();
    router.get('/test', (req, res) => {
      sendSuccess(res, { message: 'test', version: req.apiVersion });
    });
    router.get('/error', (_req, res) => {
      res.status(500).json({ error: 'Internal error' });
    });
    return router;
  };
  /**
   * Helper to create a test app that simulates the actual server.ts versioning setup.
   * Uses minimal test routers instead of full domain routers.
   */
  const createVersionedTestApp = () => {
    const app = express();
    app.use(express.json());
    // Add request logger mock
    app.use((req, res, next) => {
      req.log = {
        debug: vi.fn(),
        info: vi.fn(),
        warn: vi.fn(),
        error: vi.fn(),
        child: vi.fn().mockReturnThis(),
      } as never;
      next();
    });
    // Backwards compatibility redirect (mirrors server.ts)
    app.use('/api', (req, res, next) => {
      const versionPattern = /^\/v\d+/;
      const startsWithVersionPattern = versionPattern.test(req.path);
      if (!startsWithVersionPattern) {
        const newPath = `/api/v1${req.path}`;
        return res.redirect(301, newPath);
      }
      next();
    });
    // Create versioned routers with minimal test routes
    const createVersionRouter = (version: ApiVersion): Router => {
      const router = Router({ mergeParams: true });
      router.use(addDeprecationHeaders(version));
      router.use('/test', createMinimalTestRouter());
      return router;
    };
    // Mount versioned routers under /api/:version
    // The detectApiVersion middleware validates the version
    app.use('/api/:version', detectApiVersion, (req, res, next) => {
      const version = req.apiVersion;
      if (!version || !SUPPORTED_VERSIONS.includes(version)) {
        return next('route');
      }
      // Dynamically route to the appropriate versioned router
      const versionRouter = createVersionRouter(version);
      return versionRouter(req, res, next);
    });
    // Error handler
    app.use(errorHandler);
    return app;
  };
  describe('X-API-Version Header', () => {
    it('should include X-API-Version: v1 header in /api/v1/test response', async () => {
      // Arrange
      const app = createVersionedTestApp();
      // Act
      const response = await supertest(app).get('/api/v1/test/test');
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
    });
    it('should include X-API-Version: v2 header in /api/v2/test response', async () => {
      // Arrange
      const app = createVersionedTestApp();
      // Act
      const response = await supertest(app).get('/api/v2/test/test');
      // Assert
      expect(response.status).toBe(200);
      expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v2');
    });
    it('should include correct API version in response body', async () => {
      // Arrange
      const app = createVersionedTestApp();
      // Act
      const v1Response = await supertest(app).get('/api/v1/test/test');
      const v2Response = await supertest(app).get('/api/v2/test/test');
      // Assert
      expect(v1Response.body.data.version).toBe('v1');
      expect(v2Response.body.data.version).toBe('v2');
    });
  });
  describe('Unsupported Version Handling', () => {
    it('should return 404 with UNSUPPORTED_VERSION for /api/v99/test', async () => {
      // Arrange
      const app = createVersionedTestApp();
      // Act
      const response = await supertest(app).get('/api/v99/test');
      // Assert
      expect(response.status).toBe(404);
      expect(response.body.success).toBe(false);
      expect(response.body.error.code).toBe(VERSION_ERROR_CODES.UNSUPPORTED_VERSION);
      expect(response.body.error.message).toContain("API version 'v99' is not supported");
      expect(response.body.error.details.requestedVersion).toBe('v99');
      expect(response.body.error.details.supportedVersions).toEqual(
        expect.arrayContaining(['v1', 'v2']),
      );
    });
    it('should return 404 with UNSUPPORTED_VERSION for /api/v0/test', async () => {
      // Arrange
      const app = createVersionedTestApp();
      // Act
      const response = await supertest(app).get('/api/v0/test');
      // Assert
      expect(response.status).toBe(404);
      expect(response.body.error.code).toBe(VERSION_ERROR_CODES.UNSUPPORTED_VERSION);
      expect(response.body.error.details.requestedVersion).toBe('v0');
    });
    it('should return 404 with UNSUPPORTED_VERSION for /api/v100/resource', async () => {
      // Arrange
      const app = createVersionedTestApp();
      // Act
      const response = await supertest(app).get('/api/v100/resource');
      // Assert
      expect(response.status).toBe(404);
      expect(response.body.error.code).toBe(VERSION_ERROR_CODES.UNSUPPORTED_VERSION);
      expect(response.body.error.message).toContain("API version 'v100' is not supported");
    });
    it('should return 404 for non-standard version format like /api/vX/test', async () => {
      // Arrange
      const app = createVersionedTestApp();
      // Act - vX matches the /v\d+/ pattern (v followed by digits) but X is not a digit
      // So this path gets redirected. Let's test with a version that DOES match the pattern
      // but is not supported (e.g., v999 which is v followed by digits but not in SUPPORTED_VERSIONS)
      const response = await supertest(app).get('/api/v999/test');
      // Assert
      expect(response.status).toBe(404);
      expect(response.body.error.code).toBe(VERSION_ERROR_CODES.UNSUPPORTED_VERSION);
      expect(response.body.error.details.requestedVersion).toBe('v999');
    });
    it('should include list of supported versions in error response', async () => {
      // Arrange
      const app = createVersionedTestApp();
      // Act
      const response = await supertest(app).get('/api/v42/test');
      // Assert
      expect(response.status).toBe(404);
      expect(response.body.error.details.supportedVersions).toEqual(
        expect.arrayContaining(SUPPORTED_VERSIONS as unknown as string[]),
      );
      expect(response.body.error.message).toContain('Supported versions:');
    });
  });
  describe('Backwards Compatibility Redirect', () => {
    it('should redirect /api/test to /api/v1/test with 301', async () => {
      // Arrange
      const app = createVersionedTestApp();
      // Act
      const response = await supertest(app).get('/api/test').redirects(0); // Don't follow redirects
      // Assert
      expect(response.status).toBe(301);
      expect(response.headers.location).toBe('/api/v1/test');
    });
    it('should redirect /api/users to /api/v1/users with 301', async () => {
      // Arrange
      const app = createVersionedTestApp();
      // Act
      const response = await supertest(app).get('/api/users').redirects(0);
      // Assert
      expect(response.status).toBe(301);
      expect(response.headers.location).toBe('/api/v1/users');
    });
    it('should redirect /api/flyers/123 to /api/v1/flyers/123 with 301', async () => {
      // Arrange
      const app = createVersionedTestApp();
      // Act
      const response = await supertest(app).get('/api/flyers/123').redirects(0);
      // Assert
      expect(response.status).toBe(301);
      expect(response.headers.location).toBe('/api/v1/flyers/123');
    });
    it('should NOT redirect paths that already have a version prefix', async () => {
      // Arrange
      const app = createVersionedTestApp();
      // Act - v99 is unsupported but should NOT be redirected
      const response = await supertest(app).get('/api/v99/test').redirects(0);
      // Assert - should get 404 (unsupported), not 301 (redirect)
      expect(response.status).toBe(404);
      expect(response.headers.location).toBeUndefined();
    });
  });
  describe('Deprecation Headers', () => {
    describe('when version is active', () => {
      it('should NOT include Deprecation header for active v1', async () => {
        // Arrange
        const app = createVersionedTestApp();
        // Act
        const response = await supertest(app).get('/api/v1/test/test');
        // Assert
        expect(response.status).toBe(200);
        expect(response.headers[DEPRECATION_HEADERS.DEPRECATION.toLowerCase()]).toBeUndefined();
      });
      it('should NOT include Sunset header for active v1', async () => {
        // Arrange
        const app = createVersionedTestApp();
        // Act
        const response = await supertest(app).get('/api/v1/test/test');
        // Assert
        expect(response.headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBeUndefined();
      });
      it('should NOT include Link header for active v1', async () => {
        // Arrange
        const app = createVersionedTestApp();
        // Act
        const response = await supertest(app).get('/api/v1/test/test');
        // Assert
        expect(response.headers[DEPRECATION_HEADERS.LINK.toLowerCase()]).toBeUndefined();
      });
    });
    describe('when version is deprecated', () => {
      beforeEach(() => {
        // Mark v1 as deprecated for these tests
        VERSION_CONFIGS.v1 = {
          version: 'v1',
          status: 'deprecated',
          sunsetDate: '2027-01-01T00:00:00Z',
          successorVersion: 'v2',
        };
      });
      it('should include Deprecation: true header for deprecated version', async () => {
        // Arrange
        const app = createVersionedTestApp();
        // Act
        const response = await supertest(app).get('/api/v1/test/test');
        // Assert
        expect(response.status).toBe(200);
        expect(response.headers[DEPRECATION_HEADERS.DEPRECATION.toLowerCase()]).toBe('true');
      });
      it('should include Sunset header with ISO 8601 date for deprecated version', async () => {
        // Arrange
        const app = createVersionedTestApp();
        // Act
        const response = await supertest(app).get('/api/v1/test/test');
        // Assert
        expect(response.headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBe(
          '2027-01-01T00:00:00Z',
        );
      });
      it('should include Link header with successor-version relation for deprecated version', async () => {
        // Arrange
        const app = createVersionedTestApp();
        // Act
        const response = await supertest(app).get('/api/v1/test/test');
        // Assert
        expect(response.headers[DEPRECATION_HEADERS.LINK.toLowerCase()]).toBe(
          '</api/v2>; rel="successor-version"',
        );
      });
      it('should include X-API-Deprecation-Notice header for deprecated version', async () => {
        // Arrange
        const app = createVersionedTestApp();
        // Act
        const response = await supertest(app).get('/api/v1/test/test');
        // Assert
        const noticeHeader = response.headers[DEPRECATION_HEADERS.DEPRECATION_NOTICE.toLowerCase()];
        expect(noticeHeader).toBeDefined();
        expect(noticeHeader).toContain('deprecated');
      });
      it('should still include X-API-Version header for deprecated version', async () => {
        // Arrange
        const app = createVersionedTestApp();
        // Act
        const response = await supertest(app).get('/api/v1/test/test');
        // Assert
        expect(response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
      });
      it('should include all RFC 8594 compliant headers for deprecated version', async () => {
        // Arrange
        const app = createVersionedTestApp();
        // Act
        const response = await supertest(app).get('/api/v1/test/test');
        // Assert - verify all expected headers are present
        const headers = response.headers;
        expect(headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
        expect(headers[DEPRECATION_HEADERS.DEPRECATION.toLowerCase()]).toBe('true');
        expect(headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBe('2027-01-01T00:00:00Z');
        expect(headers[DEPRECATION_HEADERS.LINK.toLowerCase()]).toBe(
          '</api/v2>; rel="successor-version"',
        );
        expect(headers[DEPRECATION_HEADERS.DEPRECATION_NOTICE.toLowerCase()]).toContain(
          'deprecated',
        );
      });
    });
    describe('when deprecated version lacks optional fields', () => {
      beforeEach(() => {
        // Mark v1 as deprecated without sunset date or successor
        VERSION_CONFIGS.v1 = {
          version: 'v1',
          status: 'deprecated',
          // No sunsetDate or successorVersion
        };
      });
      it('should include Deprecation header even without sunset date', async () => {
        // Arrange
        const app = createVersionedTestApp();
        // Act
        const response = await supertest(app).get('/api/v1/test/test');
        // Assert
        expect(response.headers[DEPRECATION_HEADERS.DEPRECATION.toLowerCase()]).toBe('true');
      });
      it('should NOT include Sunset header when not configured', async () => {
        // Arrange
        const app = createVersionedTestApp();
        // Act
        const response = await supertest(app).get('/api/v1/test/test');
        // Assert
        expect(response.headers[DEPRECATION_HEADERS.SUNSET.toLowerCase()]).toBeUndefined();
      });
      it('should NOT include Link header when successor not configured', async () => {
        // Arrange
        const app = createVersionedTestApp();
        // Act
        const response = await supertest(app).get('/api/v1/test/test');
        // Assert
        expect(response.headers[DEPRECATION_HEADERS.LINK.toLowerCase()]).toBeUndefined();
      });
    });
  });
  describe('Cross-cutting Version Behavior', () => {
    it('should return same response structure for v1 and v2 endpoints', async () => {
      // Arrange
      const app = createVersionedTestApp();
      // Act
      const v1Response = await supertest(app).get('/api/v1/test/test');
      const v2Response = await supertest(app).get('/api/v2/test/test');
      // Assert - both should have same structure, different version headers
      expect(v1Response.status).toBe(200);
      expect(v2Response.status).toBe(200);
      expect(v1Response.body.data.message).toBe('test');
      expect(v2Response.body.data.message).toBe('test');
      expect(v1Response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
      expect(v2Response.headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v2');
    });
    it('should handle multiple sequential requests to different versions', async () => {
      // Arrange
      const app = createVersionedTestApp();
      // Act - make multiple requests
      const responses = await Promise.all([
        supertest(app).get('/api/v1/test/test'),
        supertest(app).get('/api/v2/test/test'),
        supertest(app).get('/api/v1/test/test'),
        supertest(app).get('/api/v2/test/test'),
      ]);
      // Assert
      expect(responses[0].headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
      expect(responses[1].headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v2');
      expect(responses[2].headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v1');
      expect(responses[3].headers[DEPRECATION_HEADERS.API_VERSION.toLowerCase()]).toBe('v2');
    });
    it('should properly detect version from request params', async () => {
      // Arrange
      const app = createVersionedTestApp();
      // Act
      const v1Response = await supertest(app).get('/api/v1/test/test');
      const v2Response = await supertest(app).get('/api/v2/test/test');
      // Assert - verify version is attached to request and returned in body
      expect(v1Response.body.data.version).toBe('v1');
      expect(v2Response.body.data.version).toBe('v2');
    });
  });
  describe('Default Version Behavior', () => {
    it('should use v1 as default version', () => {
      // Assert
      expect(DEFAULT_VERSION).toBe('v1');
    });
    it('should have both v1 and v2 in supported versions', () => {
      // Assert
      expect(SUPPORTED_VERSIONS).toContain('v1');
      expect(SUPPORTED_VERSIONS).toContain('v2');
      expect(SUPPORTED_VERSIONS.length).toBe(2);
    });
  });
 });
--- a/src/tests/integration/admin.integration.test.ts
+++ b/src/tests/integration/admin.integration.test.ts
@@ -205,7 +205,7 @@ describe('Admin API Routes Integration Tests', () => {
    it('should allow an admin to approve a correction', async () => {
      // Act: Approve the correction.
      const response = await request
-        .post(`/api/admin/corrections/${testCorrectionId}/approve`)
+        .post(`/api/v1/admin/corrections/${testCorrectionId}/approve`)
        .set('Authorization', `Bearer ${adminToken}`);
      expect(response.status).toBe(200);
@@ -226,7 +226,7 @@ describe('Admin API Routes Integration Tests', () => {
    it('should allow an admin to reject a correction', async () => {
      // Act: Reject the correction.
      const response = await request
-        .post(`/api/admin/corrections/${testCorrectionId}/reject`)
+        .post(`/api/v1/admin/corrections/${testCorrectionId}/reject`)
        .set('Authorization', `Bearer ${adminToken}`);
      expect(response.status).toBe(200);
@@ -241,7 +241,7 @@ describe('Admin API Routes Integration Tests', () => {
    it('should allow an admin to update a correction', async () => {
      // Act: Update the suggested value of the correction.
      const response = await request
-        .put(`/api/admin/corrections/${testCorrectionId}`)
+        .put(`/api/v1/admin/corrections/${testCorrectionId}`)
        .set('Authorization', `Bearer ${adminToken}`)
        .send({ suggested_value: '300' });
      const updatedCorrection = response.body.data;
@@ -265,7 +265,7 @@ describe('Admin API Routes Integration Tests', () => {
      // Act: Update the status to 'public'.
      const response = await request
-        .put(`/api/admin/recipes/${recipeId}/status`)
+        .put(`/api/v1/admin/recipes/${recipeId}/status`)
        .set('Authorization', `Bearer ${adminToken}`)
        .send({ status: 'public' });
      expect(response.status).toBe(200);
@@ -290,7 +290,7 @@ describe('Admin API Routes Integration Tests', () => {
      // Act: Call the delete endpoint as an admin.
      const response = await request
-        .delete(`/api/admin/users/${userToDelete.user.user_id}`)
+        .delete(`/api/v1/admin/users/${userToDelete.user.user_id}`)
        .set('Authorization', `Bearer ${adminToken}`);
      // Assert: Check for a successful deletion status.
@@ -301,7 +301,7 @@ describe('Admin API Routes Integration Tests', () => {
      // Act: Call the delete endpoint as the same admin user.
      const adminUserId = adminUser.user.user_id;
      const response = await request
-        .delete(`/api/admin/users/${adminUserId}`)
+        .delete(`/api/v1/admin/users/${adminUserId}`)
        .set('Authorization', `Bearer ${adminToken}`);
      // Assert:
@@ -323,7 +323,7 @@ describe('Admin API Routes Integration Tests', () => {
      const notFoundUserId = '00000000-0000-0000-0000-000000000000';
      const response = await request
-        .delete(`/api/admin/users/${notFoundUserId}`)
+        .delete(`/api/v1/admin/users/${notFoundUserId}`)
        .set('Authorization', `Bearer ${adminToken}`);
      // Assert: Check for a 404 status code
--- a/src/tests/integration/budget.integration.test.ts
+++ b/src/tests/integration/budget.integration.test.ts
@@ -214,7 +214,7 @@ describe('Budget API Routes Integration Tests', () => {
      };
      const response = await request
-        .put(`/api/budgets/${testBudget.budget_id}`)
+        .put(`/api/v1/budgets/${testBudget.budget_id}`)
        .set('Authorization', `Bearer ${authToken}`)
        .send(updatedData);
@@ -244,7 +244,7 @@ describe('Budget API Routes Integration Tests', () => {
    it('should return 400 when no update fields are provided', async () => {
      const response = await request
-        .put(`/api/budgets/${testBudget.budget_id}`)
+        .put(`/api/v1/budgets/${testBudget.budget_id}`)
        .set('Authorization', `Bearer ${authToken}`)
        .send({});
@@ -253,7 +253,7 @@ describe('Budget API Routes Integration Tests', () => {
    it('should return 401 if user is not authenticated', async () => {
      const response = await request
-        .put(`/api/budgets/${testBudget.budget_id}`)
+        .put(`/api/v1/budgets/${testBudget.budget_id}`)
        .send({ name: 'Hacked Budget' });
      expect(response.status).toBe(401);
@@ -280,7 +280,7 @@ describe('Budget API Routes Integration Tests', () => {
      // Now delete it
      const deleteResponse = await request
-        .delete(`/api/budgets/${createdBudget.budget_id}`)
+        .delete(`/api/v1/budgets/${createdBudget.budget_id}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(deleteResponse.status).toBe(204);
@@ -303,7 +303,7 @@ describe('Budget API Routes Integration Tests', () => {
    });
    it('should return 401 if user is not authenticated', async () => {
-      const response = await request.delete(`/api/budgets/${testBudget.budget_id}`);
+      const response = await request.delete(`/api/v1/budgets/${testBudget.budget_id}`);
      expect(response.status).toBe(401);
    });
--- a/src/tests/integration/category.routes.test.ts
+++ b/src/tests/integration/category.routes.test.ts
@@ -64,7 +64,7 @@ describe('Category API Routes (Integration)', () => {
      const listResponse = await request.get('/api/v1/categories');
      const firstCategory = listResponse.body.data[0];
-      const response = await request.get(`/api/categories/${firstCategory.category_id}`);
+      const response = await request.get(`/api/v1/categories/${firstCategory.category_id}`);
      expect(response.status).toBe(200);
      expect(response.body.success).toBe(true);
--- a/src/tests/integration/data-integrity.integration.test.ts
+++ b/src/tests/integration/data-integrity.integration.test.ts
@@ -139,7 +139,7 @@ describe('Data Integrity Integration Tests', () => {
      // Add an item to the list
      const itemResponse = await request
-        .post(`/api/users/shopping-lists/${listId}/items`)
+        .post(`/api/v1/users/shopping-lists/${listId}/items`)
        .set('Authorization', `Bearer ${token}`)
        .send({ customItemName: 'Test Item', quantity: 1 });
      expect(itemResponse.status).toBe(201);
@@ -154,7 +154,7 @@ describe('Data Integrity Integration Tests', () => {
      // Delete the shopping list
      const deleteResponse = await request
-        .delete(`/api/users/shopping-lists/${listId}`)
+        .delete(`/api/v1/users/shopping-lists/${listId}`)
        .set('Authorization', `Bearer ${token}`);
      expect(deleteResponse.status).toBe(204);
@@ -173,7 +173,7 @@ describe('Data Integrity Integration Tests', () => {
  describe('Admin Self-Deletion Prevention', () => {
    it('should prevent admin from deleting their own account via admin route', async () => {
      const response = await request
-        .delete(`/api/admin/users/${adminUser.user.user_id}`)
+        .delete(`/api/v1/admin/users/${adminUser.user.user_id}`)
        .set('Authorization', `Bearer ${adminToken}`);
      expect(response.status).toBe(400);
--- a/src/tests/integration/edge-cases.integration.test.ts
+++ b/src/tests/integration/edge-cases.integration.test.ts
@@ -185,7 +185,7 @@ describe('Edge Cases Integration Tests', () => {
        // Try to access it as the other user
        const accessResponse = await request
-          .get(`/api/users/shopping-lists/${listId}`)
+          .get(`/api/v1/users/shopping-lists/${listId}`)
          .set('Authorization', `Bearer ${otherUserToken}`);
        // Should return 404 to hide resource existence
@@ -207,7 +207,7 @@ describe('Edge Cases Integration Tests', () => {
        // Try to update it as the other user
        const updateResponse = await request
-          .put(`/api/users/shopping-lists/${listId}`)
+          .put(`/api/v1/users/shopping-lists/${listId}`)
          .set('Authorization', `Bearer ${otherUserToken}`)
          .send({ name: 'Hacked List' });
@@ -228,7 +228,7 @@ describe('Edge Cases Integration Tests', () => {
        // Try to delete it as the other user
        const deleteResponse = await request
-          .delete(`/api/users/shopping-lists/${listId}`)
+          .delete(`/api/v1/users/shopping-lists/${listId}`)
          .set('Authorization', `Bearer ${otherUserToken}`);
        // Should return 404 to hide resource existence
--- a/src/tests/integration/flyer-processing.integration.test.ts
+++ b/src/tests/integration/flyer-processing.integration.test.ts
@@ -307,7 +307,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
    // Act 2: Poll for job completion using the new utility.
    const jobStatus = await poll(
      async () => {
-        const statusReq = request.get(`/api/ai/jobs/${jobId}/status`);
+        const statusReq = request.get(`/api/v1/ai/jobs/${jobId}/status`);
        if (token) {
          statusReq.set('Authorization', `Bearer ${token}`);
        }
@@ -439,7 +439,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
    const jobStatus = await poll(
      async () => {
        const statusResponse = await request
-          .get(`/api/ai/jobs/${jobId}/status`)
+          .get(`/api/v1/ai/jobs/${jobId}/status`)
          .set('Authorization', `Bearer ${token}`);
        return statusResponse.body.data;
      },
@@ -569,7 +569,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
    const jobStatus = await poll(
      async () => {
        const statusResponse = await request
-          .get(`/api/ai/jobs/${jobId}/status`)
+          .get(`/api/v1/ai/jobs/${jobId}/status`)
          .set('Authorization', `Bearer ${token}`);
        return statusResponse.body.data;
      },
@@ -699,7 +699,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
      // Act 2: Poll for job completion using the new utility.
      const jobStatus = await poll(
        async () => {
-          const statusResponse = await request.get(`/api/ai/jobs/${jobId}/status`);
+          const statusResponse = await request.get(`/api/v1/ai/jobs/${jobId}/status`);
          return statusResponse.body.data;
        },
        (status) => status.state === 'completed' || status.state === 'failed',
@@ -787,7 +787,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
      // Act 2: Poll for job completion using the new utility.
      const jobStatus = await poll(
        async () => {
-          const statusResponse = await request.get(`/api/ai/jobs/${jobId}/status`);
+          const statusResponse = await request.get(`/api/v1/ai/jobs/${jobId}/status`);
          return statusResponse.body.data;
        },
        (status) => status.state === 'completed' || status.state === 'failed',
@@ -854,7 +854,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
      // Act 2: Poll for job completion using the new utility.
      const jobStatus = await poll(
        async () => {
-          const statusResponse = await request.get(`/api/ai/jobs/${jobId}/status`);
+          const statusResponse = await request.get(`/api/v1/ai/jobs/${jobId}/status`);
          return statusResponse.body.data;
        },
        (status) => status.state === 'completed' || status.state === 'failed',
--- a/src/tests/integration/flyer.integration.test.ts
+++ b/src/tests/integration/flyer.integration.test.ts
@@ -97,7 +97,7 @@ describe('Public Flyer API Routes Integration Tests', () => {
      const testFlyer = flyers[0];
      // Act: Fetch items for the first flyer.
-      const response = await request.get(`/api/flyers/${testFlyer.flyer_id}/items`);
+      const response = await request.get(`/api/v1/flyers/${testFlyer.flyer_id}/items`);
      const items: FlyerItem[] = response.body.data;
      expect(response.status).toBe(200);
--- a/src/tests/integration/gamification.integration.test.ts
+++ b/src/tests/integration/gamification.integration.test.ts
@@ -175,7 +175,7 @@ describe('Gamification Flow Integration Test', () => {
    const jobStatus = await poll(
      async () => {
        const statusResponse = await request
-          .get(`/api/ai/jobs/${jobId}/status`)
+          .get(`/api/v1/ai/jobs/${jobId}/status`)
          .set('Authorization', `Bearer ${authToken}`);
        console.error(
          `[TEST DEBUG] Polling status for ${jobId}: ${statusResponse.body?.data?.state}`,
--- a/src/tests/integration/inventory.integration.test.ts
+++ b/src/tests/integration/inventory.integration.test.ts
@@ -331,7 +331,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
    it('should return item details', async () => {
      const response = await request
-        .get(`/api/inventory/${testItemId}`)
+        .get(`/api/v1/inventory/${testItemId}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(response.status).toBe(200);
@@ -358,7 +358,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
      createdUserIds.push(otherUser.user.user_id);
      const response = await request
-        .get(`/api/inventory/${testItemId}`)
+        .get(`/api/v1/inventory/${testItemId}`)
        .set('Authorization', `Bearer ${otherToken}`);
      expect(response.status).toBe(404);
@@ -387,7 +387,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
    it('should update item quantity', async () => {
      const response = await request
-        .put(`/api/inventory/${updateItemId}`)
+        .put(`/api/v1/inventory/${updateItemId}`)
        .set('Authorization', `Bearer ${authToken}`)
        .send({ quantity: 5 });
@@ -397,7 +397,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
    it('should update item location', async () => {
      const response = await request
-        .put(`/api/inventory/${updateItemId}`)
+        .put(`/api/v1/inventory/${updateItemId}`)
        .set('Authorization', `Bearer ${authToken}`)
        .send({ location: 'freezer' });
@@ -411,7 +411,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
        .toISOString()
        .split('T')[0];
      const response = await request
-        .put(`/api/inventory/${updateItemId}`)
+        .put(`/api/v1/inventory/${updateItemId}`)
        .set('Authorization', `Bearer ${authToken}`)
        .send({ expiry_date: futureDate });
@@ -428,7 +428,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
    it('should reject empty update body', async () => {
      const response = await request
-        .put(`/api/inventory/${updateItemId}`)
+        .put(`/api/v1/inventory/${updateItemId}`)
        .set('Authorization', `Bearer ${authToken}`)
        .send({});
@@ -454,14 +454,14 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
      const itemId = createResponse.body.data.inventory_id;
      const response = await request
-        .delete(`/api/inventory/${itemId}`)
+        .delete(`/api/v1/inventory/${itemId}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(response.status).toBe(204);
      // Verify deletion
      const verifyResponse = await request
-        .get(`/api/inventory/${itemId}`)
+        .get(`/api/v1/inventory/${itemId}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(verifyResponse.status).toBe(404);
@@ -492,7 +492,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
      // Note: The actual API marks the entire item as consumed (no partial consumption)
      // and returns 204 No Content
      const response = await request
-        .post(`/api/inventory/${consumeItemId}/consume`)
+        .post(`/api/v1/inventory/${consumeItemId}/consume`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(response.status).toBe(204);
@@ -501,7 +501,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
    it('should verify item is marked as consumed', async () => {
      // Verify the item was marked as consumed
      const getResponse = await request
-        .get(`/api/inventory/${consumeItemId}`)
+        .get(`/api/v1/inventory/${consumeItemId}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(getResponse.status).toBe(200);
@@ -528,7 +528,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
      // First consume should succeed
      const firstResponse = await request
-        .post(`/api/inventory/${itemId}/consume`)
+        .post(`/api/v1/inventory/${itemId}/consume`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(firstResponse.status).toBe(204);
@@ -536,7 +536,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
      // Second consume - item can still be found but already marked as consumed
      // The API doesn't prevent this, so we just verify it doesn't error
      const secondResponse = await request
-        .post(`/api/inventory/${itemId}/consume`)
+        .post(`/api/v1/inventory/${itemId}/consume`)
        .set('Authorization', `Bearer ${authToken}`);
      // Should still return 204 since the item exists
@@ -746,7 +746,7 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
      // Step 4: Update location (note: consume marks entire item as consumed, no partial)
      const updateResponse = await request
-        .put(`/api/inventory/${itemId}`)
+        .put(`/api/v1/inventory/${itemId}`)
        .set('Authorization', `Bearer ${authToken}`)
        .send({ location: 'freezer' });
@@ -755,14 +755,14 @@ describe('Inventory/Expiry Integration Tests (/api/inventory)', () => {
      // Step 5: Mark as consumed (returns 204 No Content)
      const consumeResponse = await request
-        .post(`/api/inventory/${itemId}/consume`)
+        .post(`/api/v1/inventory/${itemId}/consume`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(consumeResponse.status).toBe(204);
      // Step 6: Verify consumed status
      const verifyResponse = await request
-        .get(`/api/inventory/${itemId}`)
+        .get(`/api/v1/inventory/${itemId}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(verifyResponse.status).toBe(200);
--- a/src/tests/integration/notification.integration.test.ts
+++ b/src/tests/integration/notification.integration.test.ts
@@ -115,7 +115,7 @@ describe('Notification API Routes Integration Tests', () => {
      const notificationIdToMark = unreadNotifRes.rows[0].notification_id;
      const response = await request
-        .post(`/api/users/notifications/${notificationIdToMark}/mark-read`)
+        .post(`/api/v1/users/notifications/${notificationIdToMark}/mark-read`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(response.status).toBe(204);
@@ -180,7 +180,7 @@ describe('Notification API Routes Integration Tests', () => {
      const notificationId = createResult.rows[0].notification_id;
      const response = await request
-        .delete(`/api/users/notifications/${notificationId}`)
+        .delete(`/api/v1/users/notifications/${notificationId}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(response.status).toBe(204);
@@ -221,7 +221,7 @@ describe('Notification API Routes Integration Tests', () => {
      // Try to delete it as the other user
      const response = await request
-        .delete(`/api/users/notifications/${notificationId}`)
+        .delete(`/api/v1/users/notifications/${notificationId}`)
        .set('Authorization', `Bearer ${otherToken}`);
      // Should return 404 (not 403) to hide existence
--- a/src/tests/integration/public.routes.integration.test.ts
+++ b/src/tests/integration/public.routes.integration.test.ts
@@ -152,7 +152,7 @@ describe('Public API Routes Integration Tests', () => {
    });
    it('GET /api/flyers/:id/items should return items for a specific flyer', async () => {
-      const response = await request.get(`/api/flyers/${testFlyer.flyer_id}/items`);
+      const response = await request.get(`/api/v1/flyers/${testFlyer.flyer_id}/items`);
      const items: FlyerItem[] = response.body.data;
      expect(response.status).toBe(200);
      expect(items).toBeInstanceOf(Array);
@@ -213,7 +213,7 @@ describe('Public API Routes Integration Tests', () => {
        [testRecipe.recipe_id, testUser.user.user_id],
      );
      createdRecipeCommentIds.push(commentRes.rows[0].recipe_comment_id);
-      const response = await request.get(`/api/recipes/${testRecipe.recipe_id}/comments`);
+      const response = await request.get(`/api/v1/recipes/${testRecipe.recipe_id}/comments`);
      const comments: RecipeComment[] = response.body.data;
      expect(response.status).toBe(200);
      expect(comments).toBeInstanceOf(Array);
--- a/src/tests/integration/receipt.integration.test.ts
+++ b/src/tests/integration/receipt.integration.test.ts
@@ -372,7 +372,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
    it('should return receipt with items', async () => {
      const response = await request
-        .get(`/api/receipts/${testReceiptId}`)
+        .get(`/api/v1/receipts/${testReceiptId}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(response.status).toBe(200);
@@ -401,7 +401,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
      createdUserIds.push(otherUser.user.user_id);
      const response = await request
-        .get(`/api/receipts/${testReceiptId}`)
+        .get(`/api/v1/receipts/${testReceiptId}`)
        .set('Authorization', `Bearer ${otherToken}`);
      expect(response.status).toBe(404);
@@ -421,14 +421,14 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
      const receiptId = result.rows[0].receipt_id;
      const response = await request
-        .delete(`/api/receipts/${receiptId}`)
+        .delete(`/api/v1/receipts/${receiptId}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(response.status).toBe(204);
      // Verify deletion
      const verifyResponse = await request
-        .get(`/api/receipts/${receiptId}`)
+        .get(`/api/v1/receipts/${receiptId}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(verifyResponse.status).toBe(404);
@@ -452,7 +452,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
    it('should queue a failed receipt for reprocessing', async () => {
      const response = await request
-        .post(`/api/receipts/${failedReceiptId}/reprocess`)
+        .post(`/api/v1/receipts/${failedReceiptId}/reprocess`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(response.status).toBe(200);
@@ -497,7 +497,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
    describe('GET /api/receipts/:receiptId/items', () => {
      it('should return all receipt items', async () => {
        const response = await request
-          .get(`/api/receipts/${receiptWithItemsId}/items`)
+          .get(`/api/v1/receipts/${receiptWithItemsId}/items`)
          .set('Authorization', `Bearer ${authToken}`);
        expect(response.status).toBe(200);
@@ -510,7 +510,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
    describe('PUT /api/receipts/:receiptId/items/:itemId', () => {
      it('should update item status', async () => {
        const response = await request
-          .put(`/api/receipts/${receiptWithItemsId}/items/${testItemId}`)
+          .put(`/api/v1/receipts/${receiptWithItemsId}/items/${testItemId}`)
          .set('Authorization', `Bearer ${authToken}`)
          .send({ status: 'matched', match_confidence: 0.95 });
@@ -520,7 +520,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
      it('should reject invalid status', async () => {
        const response = await request
-          .put(`/api/receipts/${receiptWithItemsId}/items/${testItemId}`)
+          .put(`/api/v1/receipts/${receiptWithItemsId}/items/${testItemId}`)
          .set('Authorization', `Bearer ${authToken}`)
          .send({ status: 'invalid_status' });
@@ -531,7 +531,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
    describe('GET /api/receipts/:receiptId/items/unadded', () => {
      it('should return unadded items', async () => {
        const response = await request
-          .get(`/api/receipts/${receiptWithItemsId}/items/unadded`)
+          .get(`/api/v1/receipts/${receiptWithItemsId}/items/unadded`)
          .set('Authorization', `Bearer ${authToken}`);
        expect(response.status).toBe(200);
@@ -567,7 +567,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
    it('should confirm items and add to inventory', async () => {
      const response = await request
-        .post(`/api/receipts/${receiptForConfirmId}/confirm`)
+        .post(`/api/v1/receipts/${receiptForConfirmId}/confirm`)
        .set('Authorization', `Bearer ${authToken}`)
        .send({
          items: [
@@ -608,7 +608,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
      const skipItemId = itemResult.rows[0].receipt_item_id;
      const response = await request
-        .post(`/api/receipts/${receiptForConfirmId}/confirm`)
+        .post(`/api/v1/receipts/${receiptForConfirmId}/confirm`)
        .set('Authorization', `Bearer ${authToken}`)
        .send({
          items: [
@@ -625,7 +625,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
    it('should reject invalid location', async () => {
      const response = await request
-        .post(`/api/receipts/${receiptForConfirmId}/confirm`)
+        .post(`/api/v1/receipts/${receiptForConfirmId}/confirm`)
        .set('Authorization', `Bearer ${authToken}`)
        .send({
          items: [
@@ -669,7 +669,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
    it('should return processing logs', async () => {
      const response = await request
-        .get(`/api/receipts/${receiptWithLogsId}/logs`)
+        .get(`/api/v1/receipts/${receiptWithLogsId}/logs`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(response.status).toBe(200);
@@ -703,7 +703,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
      // Step 2: Verify receipt was created
      const getResponse = await request
-        .get(`/api/receipts/${receiptId}`)
+        .get(`/api/v1/receipts/${receiptId}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(getResponse.status).toBe(200);
@@ -722,7 +722,7 @@ describe('Receipt Processing Integration Tests (/api/receipts)', () => {
      // Step 4: Verify logs endpoint works (empty for new receipt)
      const logsResponse = await request
-        .get(`/api/receipts/${receiptId}/logs`)
+        .get(`/api/v1/receipts/${receiptId}/logs`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(logsResponse.status).toBe(200);
--- a/src/tests/integration/recipe.integration.test.ts
+++ b/src/tests/integration/recipe.integration.test.ts
@@ -66,7 +66,7 @@ describe('Recipe API Routes Integration Tests', () => {
  describe('GET /api/recipes/:recipeId', () => {
    it('should fetch a single public recipe by its ID', async () => {
-      const response = await request.get(`/api/recipes/${testRecipe.recipe_id}`);
+      const response = await request.get(`/api/v1/recipes/${testRecipe.recipe_id}`);
      expect(response.status).toBe(200);
      expect(response.body.data).toBeDefined();
@@ -104,7 +104,7 @@ describe('Recipe API Routes Integration Tests', () => {
    createdRecipeIds.push(createdRecipe.recipe_id);
    // Verify the recipe can be fetched from the public endpoint
-    const verifyResponse = await request.get(`/api/recipes/${createdRecipe.recipe_id}`);
+    const verifyResponse = await request.get(`/api/v1/recipes/${createdRecipe.recipe_id}`);
    expect(verifyResponse.status).toBe(200);
    expect(verifyResponse.body.data.name).toBe(newRecipeData.name);
  });
@@ -115,7 +115,7 @@ describe('Recipe API Routes Integration Tests', () => {
    };
    const response = await request
-      .put(`/api/users/recipes/${testRecipe.recipe_id}`) // Authenticated recipe update endpoint
+      .put(`/api/v1/users/recipes/${testRecipe.recipe_id}`) // Authenticated recipe update endpoint
      .set('Authorization', `Bearer ${authToken}`)
      .send(recipeUpdates);
@@ -126,7 +126,7 @@ describe('Recipe API Routes Integration Tests', () => {
    expect(updatedRecipe.instructions).toBe(recipeUpdates.instructions);
    // Verify the changes were persisted by fetching the recipe again
-    const verifyResponse = await request.get(`/api/recipes/${testRecipe.recipe_id}`);
+    const verifyResponse = await request.get(`/api/v1/recipes/${testRecipe.recipe_id}`);
    expect(verifyResponse.status).toBe(200);
    expect(verifyResponse.body.data.name).toBe(recipeUpdates.name);
  });
@@ -141,7 +141,7 @@ describe('Recipe API Routes Integration Tests', () => {
    // Attempt to update the testRecipe (owned by testUser) using otherUser's token
    const response = await request
-      .put(`/api/users/recipes/${testRecipe.recipe_id}`)
+      .put(`/api/v1/users/recipes/${testRecipe.recipe_id}`)
      .set('Authorization', `Bearer ${otherToken}`)
      .send({ name: 'Hacked Recipe Name' });
@@ -165,13 +165,13 @@ describe('Recipe API Routes Integration Tests', () => {
    // Delete the recipe
    const deleteRes = await request
-      .delete(`/api/users/recipes/${recipeToDelete.recipe_id}`)
+      .delete(`/api/v1/users/recipes/${recipeToDelete.recipe_id}`)
      .set('Authorization', `Bearer ${authToken}`);
    expect(deleteRes.status).toBe(204);
    // Verify it's actually deleted by trying to fetch it
-    const verifyRes = await request.get(`/api/recipes/${recipeToDelete.recipe_id}`);
+    const verifyRes = await request.get(`/api/v1/recipes/${recipeToDelete.recipe_id}`);
    expect(verifyRes.status).toBe(404);
  });
@@ -186,14 +186,14 @@ describe('Recipe API Routes Integration Tests', () => {
    // Attempt to delete the testRecipe (owned by testUser) using otherUser's token
    const response = await request
-      .delete(`/api/users/recipes/${testRecipe.recipe_id}`)
+      .delete(`/api/v1/users/recipes/${testRecipe.recipe_id}`)
      .set('Authorization', `Bearer ${otherToken}`);
    // Should return 404 because the recipe doesn't belong to this user
    expect(response.status).toBe(404);
    // Verify the recipe still exists
-    const verifyRes = await request.get(`/api/recipes/${testRecipe.recipe_id}`);
+    const verifyRes = await request.get(`/api/v1/recipes/${testRecipe.recipe_id}`);
    expect(verifyRes.status).toBe(200);
  });
@@ -201,7 +201,7 @@ describe('Recipe API Routes Integration Tests', () => {
    const commentContent = 'This is a great recipe! Thanks for sharing.';
    const response = await request
-      .post(`/api/recipes/${testRecipe.recipe_id}/comments`)
+      .post(`/api/v1/recipes/${testRecipe.recipe_id}/comments`)
      .set('Authorization', `Bearer ${authToken}`)
      .send({ content: commentContent });
@@ -215,7 +215,7 @@ describe('Recipe API Routes Integration Tests', () => {
  it('should allow an authenticated user to fork a recipe', async () => {
    const response = await request
-      .post(`/api/recipes/${testRecipe.recipe_id}/fork`)
+      .post(`/api/v1/recipes/${testRecipe.recipe_id}/fork`)
      .set('Authorization', `Bearer ${authToken}`);
    expect(response.status).toBe(201);
@@ -254,7 +254,7 @@ describe('Recipe API Routes Integration Tests', () => {
    // Fork the seed recipe - this should succeed
    const response = await request
-      .post(`/api/recipes/${seedRecipeId}/fork`)
+      .post(`/api/v1/recipes/${seedRecipeId}/fork`)
      .set('Authorization', `Bearer ${authToken}`);
    // Forking should work - seed recipes should be forkable
@@ -271,12 +271,12 @@ describe('Recipe API Routes Integration Tests', () => {
    it('should return comments for a recipe', async () => {
      // First add a comment
      await request
-        .post(`/api/recipes/${testRecipe.recipe_id}/comments`)
+        .post(`/api/v1/recipes/${testRecipe.recipe_id}/comments`)
        .set('Authorization', `Bearer ${authToken}`)
        .send({ content: 'Test comment for GET request' });
      // Now fetch comments
-      const response = await request.get(`/api/recipes/${testRecipe.recipe_id}/comments`);
+      const response = await request.get(`/api/v1/recipes/${testRecipe.recipe_id}/comments`);
      expect(response.status).toBe(200);
      expect(response.body.success).toBe(true);
@@ -306,7 +306,7 @@ describe('Recipe API Routes Integration Tests', () => {
      createdRecipeIds.push(noCommentsRecipe.recipe_id);
      // Fetch comments for this recipe
-      const response = await request.get(`/api/recipes/${noCommentsRecipe.recipe_id}/comments`);
+      const response = await request.get(`/api/v1/recipes/${noCommentsRecipe.recipe_id}/comments`);
      expect(response.status).toBe(200);
      expect(response.body.success).toBe(true);
--- a/src/tests/integration/upc.integration.test.ts
+++ b/src/tests/integration/upc.integration.test.ts
@@ -311,7 +311,7 @@ describe('UPC Scanning Integration Tests (/api/upc)', () => {
    it('should return a specific scan by ID', async () => {
      const response = await request
-        .get(`/api/upc/history/${testScanId}`)
+        .get(`/api/v1/upc/history/${testScanId}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(response.status).toBe(200);
@@ -338,7 +338,7 @@ describe('UPC Scanning Integration Tests (/api/upc)', () => {
      createdUserIds.push(otherUser.user.user_id);
      const response = await request
-        .get(`/api/upc/history/${testScanId}`)
+        .get(`/api/v1/upc/history/${testScanId}`)
        .set('Authorization', `Bearer ${otherToken}`);
      expect(response.status).toBe(404);
@@ -467,7 +467,7 @@ describe('UPC Scanning Integration Tests (/api/upc)', () => {
      // Step 4: Verify in history
      const historyResponse = await request
-        .get(`/api/upc/history/${scanId}`)
+        .get(`/api/v1/upc/history/${scanId}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(historyResponse.status).toBe(200);
--- a/src/tests/integration/user.integration.test.ts
+++ b/src/tests/integration/user.integration.test.ts
@@ -278,7 +278,7 @@ describe('User API Routes Integration Tests', () => {
      // Act 3: Remove the watched item.
      const removeResponse = await request
-        .delete(`/api/users/watched-items/${newItem.master_grocery_item_id}`)
+        .delete(`/api/v1/users/watched-items/${newItem.master_grocery_item_id}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(removeResponse.status).toBe(204);
@@ -309,7 +309,7 @@ describe('User API Routes Integration Tests', () => {
      // Act 2: Add an item to the new list.
      const addItemResponse = await request
-        .post(`/api/users/shopping-lists/${newList.shopping_list_id}/items`)
+        .post(`/api/v1/users/shopping-lists/${newList.shopping_list_id}/items`)
        .set('Authorization', `Bearer ${authToken}`)
        .send({ customItemName: 'Custom Test Item' });
      const addedItem = addItemResponse.body.data;
--- a/src/tests/integration/user.routes.integration.test.ts
+++ b/src/tests/integration/user.routes.integration.test.ts
@@ -122,7 +122,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
      // 3. Delete
      const deleteResponse = await request
-        .delete(`/api/users/shopping-lists/${listId}`)
+        .delete(`/api/v1/users/shopping-lists/${listId}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(deleteResponse.status).toBe(204);
@@ -157,7 +157,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
      // Act 1: Malicious user attempts to add an item to the owner's list.
      const addItemResponse = await request
-        .post(`/api/users/shopping-lists/${listId}/items`)
+        .post(`/api/v1/users/shopping-lists/${listId}/items`)
        .set('Authorization', `Bearer ${maliciousToken}`) // Use malicious user's token
        .send({ customItemName: 'Malicious Item' });
@@ -167,7 +167,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
      // Act 2: Malicious user attempts to delete the owner's list.
      const deleteResponse = await request
-        .delete(`/api/users/shopping-lists/${listId}`)
+        .delete(`/api/v1/users/shopping-lists/${listId}`)
        .set('Authorization', `Bearer ${maliciousToken}`); // Use malicious user's token
      // Assert 2: This should also fail with a 404.
@@ -177,7 +177,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
      // Act 3: Malicious user attempts to update an item on the owner's list.
      // First, the owner adds an item.
      const ownerAddItemResponse = await request
-        .post(`/api/users/shopping-lists/${listId}/items`)
+        .post(`/api/v1/users/shopping-lists/${listId}/items`)
        .set('Authorization', `Bearer ${authToken}`) // Owner's token
        .send({ customItemName: 'Legitimate Item' });
      expect(ownerAddItemResponse.status).toBe(201);
@@ -185,7 +185,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
      // Now, the malicious user tries to update it.
      const updateItemResponse = await request
-        .put(`/api/users/shopping-lists/items/${itemId}`)
+        .put(`/api/v1/users/shopping-lists/items/${itemId}`)
        .set('Authorization', `Bearer ${maliciousToken}`) // Malicious token
        .send({ is_purchased: true });
@@ -195,7 +195,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
      // Cleanup the list created in this test
      await request
-        .delete(`/api/users/shopping-lists/${listId}`)
+        .delete(`/api/v1/users/shopping-lists/${listId}`)
        .set('Authorization', `Bearer ${authToken}`);
    });
  });
@@ -217,14 +217,14 @@ describe('User Routes Integration Tests (/api/users)', () => {
    afterAll(async () => {
      if (listId) {
        await request
-          .delete(`/api/users/shopping-lists/${listId}`)
+          .delete(`/api/v1/users/shopping-lists/${listId}`)
          .set('Authorization', `Bearer ${authToken}`);
      }
    });
    it('should add an item to a shopping list', async () => {
      const response = await request
-        .post(`/api/users/shopping-lists/${listId}/items`)
+        .post(`/api/v1/users/shopping-lists/${listId}/items`)
        .set('Authorization', `Bearer ${authToken}`)
        .send({ customItemName: 'Test Item' });
@@ -237,7 +237,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
    it('should update an item in a shopping list', async () => {
      const updates = { is_purchased: true, quantity: 5 };
      const response = await request
-        .put(`/api/users/shopping-lists/items/${itemId}`)
+        .put(`/api/v1/users/shopping-lists/items/${itemId}`)
        .set('Authorization', `Bearer ${authToken}`)
        .send(updates);
@@ -248,7 +248,7 @@ describe('User Routes Integration Tests (/api/users)', () => {
    it('should delete an item from a shopping list', async () => {
      const response = await request
-        .delete(`/api/users/shopping-lists/items/${itemId}`)
+        .delete(`/api/v1/users/shopping-lists/items/${itemId}`)
        .set('Authorization', `Bearer ${authToken}`);
      expect(response.status).toBe(204);
--- a/src/types/express.d.ts
+++ b/src/types/express.d.ts
@@ -2,16 +2,60 @@
 import { Request, Response, NextFunction } from 'express';
 import { Logger } from 'pino';
 import * as qs from 'qs';
 import type { ApiVersion, VersionDeprecation } from '../config/apiVersions';
 /**
- * This file uses declaration merging to add a custom `log` property to the
+ * This file uses declaration merging to add custom properties to the
- * global Express Request interface. This makes the request-scoped logger
+ * global Express Request interface.
- * available in a type-safe way in all route handlers, as required by ADR-004.
+ *
 * Extended properties:
 * - `log`: Request-scoped Pino logger (ADR-004)
 * - `apiVersion`: API version extracted from request path (ADR-008)
 * - `versionDeprecation`: Deprecation info when accessing deprecated versions (ADR-008)
 *
 * @see docs/adr/0004-request-scoped-logging.md
 * @see docs/adr/0008-api-versioning-strategy.md
 */
 declare global {
  namespace Express {
    export interface Request {
      /**
       * Request-scoped Pino logger instance.
       * Includes request context (requestId, userId, etc.) for correlation.
       * @see ADR-004 for logging standards
       */
      log: Logger;
      /**
       * The API version detected from the request path.
       * Set by apiVersion middleware based on /api/v{n}/ path pattern.
       * Defaults to 'v1' when no version is detected.
       *
       * @example
       * // In a route handler:
       * if (req.apiVersion === 'v2') {
       *   return sendSuccess(res, transformV2(data));
       * }
       *
       * @see ADR-008 for versioning strategy
       */
      apiVersion?: ApiVersion;
      /**
       * Deprecation information when accessing a deprecated API version.
       * Set by deprecation middleware when the requested version is deprecated.
       * Undefined when accessing active versions.
       *
       * @example
       * // In a route handler:
       * if (req.versionDeprecation?.isDeprecated) {
       *   req.log.warn({ sunsetDate: req.versionDeprecation.sunsetDate },
       *     'Client using deprecated API version');
       * }
       *
       * @see ADR-008 for deprecation workflow
       */
      versionDeprecation?: VersionDeprecation;
    }
  }
 }
Author	SHA1	Message	Date
Gitea Actions	4baed53713	ci: Bump version to 0.12.17 [skip ci]	2026-01-28 00:08:39 +05:00
Torben Sorensen	f10c6c0cd6	Complete ADR-008 Phase 2 All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 17m56s Details	2026-01-27 11:06:09 -08:00