ci: Bump version to 0.0.26 [skip ci]

.gitea/workflows/deploy-to-prod.yml

@@ -47,6 +47,19 @@ jobs:
       - name: Install Dependencies
         run: npm ci
 
+      - name: Bump Minor Version and Push
+        run: |
+          # Configure git for the commit.
+          git config --global user.name 'Gitea Actions'
+          git config --global user.email 'actions@gitea.projectium.com'
+
+          # Bump the minor version number. This creates a new commit and a new tag.
+          # The commit message includes [skip ci] to prevent this push from triggering another workflow run.
+          npm version minor -m "ci: Bump version to %s for production release [skip ci]"
+
+          # Push the new commit and the new tag back to the main branch.
+          git push --follow-tags
+
       - name: Check for Production Database Schema Changes
         env:
           DB_HOST: ${{ secrets.DB_HOST }}
@@ -61,9 +74,10 @@ jobs:
           echo "--- Checking for production schema changes ---"
           CURRENT_HASH=$(cat sql/master_schema_rollup.sql | dos2unix | sha256sum | awk '{ print $1 }')
           echo "Current Git Schema Hash: $CURRENT_HASH"
-          DEPLOYED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'production';" -t -A || echo "none")
+          # The psql command will now fail the step if the query errors (e.g., column missing), preventing deployment on a bad schema.
+          DEPLOYED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'production';" -t -A)
           echo "Deployed DB Schema Hash: $DEPLOYED_HASH"
-          if [ "$DEPLOYED_HASH" = "none" ] || [ -z "$DEPLOYED_HASH" ]; then
+          if [ -z "$DEPLOYED_HASH" ]; then
             echo "WARNING: No schema hash found in the production database. This is expected for a first-time deployment."
           elif [ "$CURRENT_HASH" != "$DEPLOYED_HASH" ]; then
             echo "ERROR: Database schema mismatch detected! A manual database migration is required."

.gitea/workflows/deploy-to-test.yml

@@ -142,6 +142,11 @@ jobs:
           echo "--- Running Integration Tests ---"
           npm run test:integration -- --coverage --reporter=verbose --includeTaskLocation --testTimeout=10000 --silent=passed-only || true
 
+          echo "--- Running E2E Tests ---"
+          # Run E2E tests using the dedicated E2E config which inherits from integration config.
+          # We still pass --coverage to enable it, but directory and timeout are now in the config.
+          npx vitest run --config vitest.config.e2e.ts --coverage --reporter=verbose --no-file-parallelism || true
+
           # Re-enable secret masking for subsequent steps.
           echo "::secret-masking::"
 
@@ -156,6 +161,7 @@ jobs:
           echo "Checking for source coverage files..."
           ls -l .coverage/unit/coverage-final.json
           ls -l .coverage/integration/coverage-final.json
+          ls -l .coverage/e2e/coverage-final.json || echo "E2E coverage file not found"
 
           # --- V8 Coverage Processing for Backend Server ---
           # The integration tests start the server, which generates raw V8 coverage data.
@@ -187,6 +193,7 @@ jobs:
           # We give them unique names to be safe, though it's not strictly necessary.
           cp .coverage/unit/coverage-final.json "$NYC_SOURCE_DIR/unit-coverage.json"
           cp .coverage/integration/coverage-final.json "$NYC_SOURCE_DIR/integration-coverage.json"
+          cp .coverage/e2e/coverage-final.json "$NYC_SOURCE_DIR/e2e-coverage.json" || echo "E2E coverage file not found, skipping."
           # This file might not exist if integration tests fail early, so we add `|| true`
           cp .coverage/integration-server/coverage-final.json "$NYC_SOURCE_DIR/integration-server-coverage.json" || echo "Server coverage file not found, skipping."
           echo "Copied coverage files to source directory. Contents:"
@@ -257,16 +264,14 @@ jobs:
           # We normalize line endings to ensure the hash is consistent across different OS environments.
           CURRENT_HASH=$(cat sql/master_schema_rollup.sql | dos2unix | sha256sum | awk '{ print $1 }')
           echo "Current Git Schema Hash: $CURRENT_HASH"
-
           # Query the production database to get the hash of the deployed schema.
           # The `psql` command requires PGPASSWORD to be set.
           # `\t` sets tuples-only mode and `\A` unaligns output to get just the raw value.
-          # The `|| echo "none"` ensures the command doesn't fail if the table or row doesn't exist yet.          
-          DEPLOYED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'test';" -t -A || echo "none")
+          # The psql command will now fail the step if the query errors (e.g., column missing), preventing deployment on a bad schema.
+          DEPLOYED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'test';" -t -A)
           echo "Deployed DB Schema Hash: $DEPLOYED_HASH"
-
           # Check if the hash is "none" (command failed) OR if it's an empty string (table exists but is empty).
-          if [ "$DEPLOYED_HASH" = "none" ] || [ -z "$DEPLOYED_HASH" ]; then
+          if [ -z "$DEPLOYED_HASH" ]; then
             echo "WARNING: No schema hash found in the test database."
             echo "This is expected for a first-time deployment. The hash will be set after a successful deployment."
             # We allow the deployment to continue, but a manual schema update is required.

.gitea/workflows/manual-deploy-major.yml

@@ -0,0 +1,180 @@
+# .gitea/workflows/manual-deploy-major.yml
+#
+# This workflow provides a MANUAL trigger to perform a MAJOR version bump
+# and deploy the application to the PRODUCTION environment.
+name: Manual - Deploy Major Version to Production
+
+on:
+  workflow_dispatch:
+    inputs:
+      confirmation:
+        description: 'Type "deploy-major-to-prod" to confirm you want to deploy a new major version.'
+        required: true
+        default: 'do-not-run'
+      force_reload:
+        description: 'Force PM2 reload even if version matches (true/false).'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  deploy-production-major:
+    runs-on: projectium.com
+
+    steps:
+      - name: Verify Confirmation Phrase
+        run: |
+          if [ "${{ gitea.event.inputs.confirmation }}" != "deploy-major-to-prod" ]; then
+            echo "ERROR: Confirmation phrase did not match. Aborting deployment."
+            exit 1
+          fi
+          echo "✅ Confirmation accepted. Proceeding with major version production deployment."
+
+      - name: Checkout Code from 'main' branch
+        uses: actions/checkout@v3
+        with:
+          ref: 'main' # Explicitly check out the main branch for production deployment
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: '**/package-lock.json'
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Bump Major Version and Push
+        run: |
+          # Configure git for the commit.
+          git config --global user.name 'Gitea Actions'
+          git config --global user.email 'actions@gitea.projectium.com'
+
+          # Bump the major version number. This creates a new commit and a new tag.
+          # The commit message includes [skip ci] to prevent this push from triggering another workflow run.
+          npm version major -m "ci: Bump version to %s for major release [skip ci]"
+
+          # Push the new commit and the new tag back to the main branch.
+          git push --follow-tags
+
+      - name: Check for Production Database Schema Changes
+        env:
+          DB_HOST: ${{ secrets.DB_HOST }}
+          DB_USER: ${{ secrets.DB_USER }}
+          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
+          DB_NAME: ${{ secrets.DB_DATABASE_PROD }}
+        run: |
+          if [ -z "$DB_HOST" ] || [ -z "$DB_USER" ] || [ -z "$DB_PASSWORD" ] || [ -z "$DB_NAME" ]; then
+            echo "ERROR: One or more production database secrets (DB_HOST, DB_USER, DB_PASSWORD, DB_DATABASE_PROD) are not set."
+            exit 1
+          fi
+          echo "--- Checking for production schema changes ---"
+          CURRENT_HASH=$(cat sql/master_schema_rollup.sql | dos2unix | sha256sum | awk '{ print $1 }')
+          echo "Current Git Schema Hash: $CURRENT_HASH"
+          # The psql command will now fail the step if the query errors (e.g., column missing), preventing deployment on a bad schema.
+          DEPLOYED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'production';" -t -A)
+          echo "Deployed DB Schema Hash: $DEPLOYED_HASH"
+          if [ -z "$DEPLOYED_HASH" ]; then
+            echo "WARNING: No schema hash found in the production database. This is expected for a first-time deployment."
+          elif [ "$CURRENT_HASH" != "$DEPLOYED_HASH" ]; then
+            echo "ERROR: Database schema mismatch detected! A manual database migration is required."
+            exit 1
+          else
+            echo "✅ Schema is up to date. No changes detected."
+          fi
+
+      - name: Build React Application for Production
+        run: |
+          if [ -z "${{ secrets.VITE_GOOGLE_GENAI_API_KEY }}" ]; then
+            echo "ERROR: The VITE_GOOGLE_GENAI_API_KEY secret is not set."
+            exit 1
+          fi
+          GITEA_SERVER_URL="https://gitea.projectium.com"
+          COMMIT_MESSAGE=$(git log -1 --pretty=%s)
+          VITE_APP_VERSION="$(date +'%Y%m%d-%H%M'):$(git rev-parse --short HEAD)" \
+          VITE_APP_COMMIT_URL="$GITEA_SERVER_URL/${{ gitea.repository }}/commit/${{ gitea.sha }}" \
+          VITE_APP_COMMIT_MESSAGE="$COMMIT_MESSAGE" \
+          VITE_API_BASE_URL=/api VITE_API_KEY=${{ secrets.VITE_GOOGLE_GENAI_API_KEY }} npm run build
+
+      - name: Deploy Application to Production Server
+        run: |
+          echo "Deploying application files to /var/www/flyer-crawler.projectium.com..."
+          APP_PATH="/var/www/flyer-crawler.projectium.com"
+          mkdir -p "$APP_PATH"
+          mkdir -p "$APP_PATH/flyer-images/icons" "$APP_PATH/flyer-images/archive"
+          rsync -avz --delete --exclude 'node_modules' --exclude '.git' --exclude 'dist' --exclude 'flyer-images' ./ "$APP_PATH/"
+          rsync -avz dist/ "$APP_PATH"
+          echo "Application deployment complete."
+
+      - name: Install Backend Dependencies and Restart Production Server
+        env:
+          # --- Production Secrets Injection ---
+          DB_HOST: ${{ secrets.DB_HOST }}
+          DB_USER: ${{ secrets.DB_USER }}
+          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
+          DB_NAME: ${{ secrets.DB_DATABASE_PROD }}
+          REDIS_URL: 'redis://localhost:6379'
+          REDIS_PASSWORD: ${{ secrets.REDIS_PASSWORD_PROD }}
+          FRONTEND_URL: 'https://flyer-crawler.projectium.com'
+          JWT_SECRET: ${{ secrets.JWT_SECRET }}
+          GEMINI_API_KEY: ${{ secrets.VITE_GOOGLE_GENAI_API_KEY }}
+          GOOGLE_MAPS_API_KEY: ${{ secrets.GOOGLE_MAPS_API_KEY }}
+          SMTP_HOST: 'localhost'
+          SMTP_PORT: '1025'
+          SMTP_SECURE: 'false'
+          SMTP_USER: ''
+          SMTP_PASS: ''
+          SMTP_FROM_EMAIL: 'noreply@flyer-crawler.projectium.com'
+        run: |
+          if [ -z "$DB_HOST" ] || [ -z "$DB_USER" ] || [ -z "$DB_PASSWORD" ] || [ -z "$DB_NAME" ]; then
+            echo "ERROR: One or more production database secrets (DB_HOST, DB_USER, DB_PASSWORD, DB_DATABASE_PROD) are not set."
+            exit 1
+          fi
+          echo "Installing production dependencies and restarting server..."
+          cd /var/www/flyer-crawler.projectium.com
+          npm install --omit=dev
+
+          # --- Version Check Logic ---
+          # Get the version from the newly deployed package.json
+          NEW_VERSION=$(node -p "require('./package.json').version")
+          echo "Deployed Package Version: $NEW_VERSION"
+
+          # Get the running version from PM2 for the main API process
+          # We use a small node script to parse the JSON output from pm2 jlist
+          RUNNING_VERSION=$(pm2 jlist | node -e "try { const list = JSON.parse(require('fs').readFileSync(0, 'utf-8')); const app = list.find(p => p.name === 'flyer-crawler-api'); console.log(app ? app.pm2_env.version : ''); } catch(e) { console.log(''); }")
+          echo "Running PM2 Version: $RUNNING_VERSION"
+
+          if [ "${{ gitea.event.inputs.force_reload }}" == "true" ] || [ "$NEW_VERSION" != "$RUNNING_VERSION" ] || [ -z "$RUNNING_VERSION" ]; then
+            if [ "${{ gitea.event.inputs.force_reload }}" == "true" ]; then
+              echo "Force reload triggered by manual input. Reloading PM2..."
+            else
+              echo "Version mismatch (Running: $RUNNING_VERSION -> Deployed: $NEW_VERSION) or app not running. Reloading PM2..."
+            fi
+            pm2 startOrReload ecosystem.config.cjs --env production && pm2 save
+            echo "Production backend server reloaded successfully."
+          else
+            echo "Version $NEW_VERSION is already running. Skipping PM2 reload."
+          fi
+
+          echo "Updating schema hash in production database..."
+          CURRENT_HASH=$(cat sql/master_schema_rollup.sql | dos2unix | sha256sum | awk '{ print $1 }')
+          PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c \
+          "INSERT INTO public.schema_info (environment, schema_hash, deployed_at) VALUES ('production', '$CURRENT_HASH', NOW())
+           ON CONFLICT (environment) DO UPDATE SET schema_hash = EXCLUDED.schema_hash, deployed_at = NOW();"
+
+          UPDATED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'production';" -t -A)
+          if [ "$CURRENT_HASH" = "$UPDATED_HASH" ]; then
+            echo "✅ Schema hash successfully updated in the database to: $UPDATED_HASH"
+          else
+            echo "ERROR: Failed to update schema hash in the database."
+          fi
+
+      - name: Show PM2 Environment for Production
+        run: |
+          echo "--- Displaying recent PM2 logs for flyer-crawler-api ---"
+          sleep 5
+          pm2 describe flyer-crawler-api || echo "Could not find production pm2 process."
+          pm2 logs flyer-crawler-api --lines 20 --nostream || echo "Could not find production pm2 process."
+          pm2 env flyer-crawler-api || echo "Could not find production pm2 process."

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "flyer-crawler",
-  "version": "0.0.21",
+  "version": "0.0.26",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "flyer-crawler",
-      "version": "0.0.21",
+      "version": "0.0.26",
       "dependencies": {
         "@bull-board/api": "^6.14.2",
         "@bull-board/express": "^6.14.2",
@@ -42,7 +42,7 @@
         "recharts": "^3.4.1",
         "sharp": "^0.34.5",
         "tsx": "^4.20.6",
-        "zod": "^4.1.13",
+        "zod": "^4.2.1",
         "zxcvbn": "^4.4.2"
       },
       "devDependencies": {

package.json

@@ -1,7 +1,7 @@
 {
   "name": "flyer-crawler",
   "private": true,
-  "version": "0.0.21",
+  "version": "0.0.26",
   "type": "module",
   "scripts": {
     "dev": "concurrently \"npm:start:dev\" \"vite\"",
@@ -61,7 +61,7 @@
     "recharts": "^3.4.1",
     "sharp": "^0.34.5",
     "tsx": "^4.20.6",
-    "zod": "^4.1.13",
+    "zod": "^4.2.1",
     "zxcvbn": "^4.4.2"
   },
   "devDependencies": {

src/routes/admin.content.routes.test.ts

@@ -15,6 +15,11 @@ import { NotFoundError } from '../services/db/errors.db'; // This can stay, it's
 import { createTestApp } from '../tests/utils/createTestApp';
 import { mockLogger } from '../tests/utils/mockLogger';
 
+// Mock the file upload middleware to allow testing the controller's internal check
+vi.mock('../middleware/fileUpload.middleware', () => ({
+  requireFileUpload: () => (req: Request, res: Response, next: NextFunction) => next(),
+}));
+
 vi.mock('../lib/queue', () => ({
   serverAdapter: {
     getRouter: () => (req: Request, res: Response, next: NextFunction) => next(), // Return a dummy express handler
@@ -125,12 +130,6 @@ describe('Admin Content Management Routes (/api/admin)', () => {
     authenticatedUser: adminUser,
   });
 
-  // Add a basic error handler to capture errors passed to next(err) and return JSON.
-  // This prevents unhandled error crashes in tests and ensures we get the 500 response we expect.
-  app.use((err: any, req: any, res: any, next: any) => {
-    res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-  });
-
   beforeEach(() => {
     vi.clearAllMocks();
   });
@@ -262,7 +261,7 @@ describe('Admin Content Management Routes (/api/admin)', () => {
       const response = await supertest(app).post('/api/admin/brands/55/logo');
       expect(response.status).toBe(400);
       expect(response.body.message).toMatch(
-        /Logo image file is required|The request data is invalid/,
+        /Logo image file is required|The request data is invalid|Logo image file is missing./,
       );
     });
 

src/routes/admin.jobs.routes.test.ts

@@ -97,12 +97,6 @@ describe('Admin Job Trigger Routes (/api/admin/trigger)', () => {
     authenticatedUser: adminUser,
   });
 
-  // Add a basic error handler to capture errors passed to next(err) and return JSON.
-  // This prevents unhandled error crashes in tests and ensures we get the 500 response we expect.
-  app.use((err: any, req: any, res: any, next: any) => {
-    res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-  });
-
   beforeEach(() => {
     vi.clearAllMocks();
   });
@@ -248,6 +242,17 @@ describe('Admin Job Trigger Routes (/api/admin/trigger)', () => {
       expect(response.status).toBe(400);
     });
 
+    it('should return 404 if the queue name is valid but not in the retry map', async () => {
+      const queueName = 'weekly-analytics-reporting'; // This is in the Zod enum but not the queueMap
+      const jobId = 'some-job-id';
+
+      const response = await supertest(app).post(`/api/admin/jobs/${queueName}/${jobId}/retry`);
+
+      // The route throws a NotFoundError, which the error handler should convert to a 404.
+      expect(response.status).toBe(404);
+      expect(response.body.message).toBe(`Queue 'weekly-analytics-reporting' not found.`);
+    });
+
     it('should return 404 if the job ID is not found in the queue', async () => {
       vi.mocked(flyerQueue.getJob).mockResolvedValue(undefined);
       const response = await supertest(app).post(

src/routes/admin.monitoring.routes.test.ts

@@ -102,12 +102,6 @@ describe('Admin Monitoring Routes (/api/admin)', () => {
     authenticatedUser: adminUser,
   });
 
-  // Add a basic error handler to capture errors passed to next(err) and return JSON.
-  // This prevents unhandled error crashes in tests and ensures we get the 500 response we expect.
-  app.use((err: any, req: any, res: any, next: any) => {
-    res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-  });
-
   beforeEach(() => {
     vi.clearAllMocks();
   });

src/routes/admin.routes.ts

@@ -2,12 +2,11 @@
 import { Router, NextFunction, Request, Response } from 'express';
 import passport from './passport.routes';
 import { isAdmin } from './passport.routes'; // Correctly imported
-import multer from 'multer'; // --- Zod Schemas for Admin Routes (as per ADR-003) ---
+import multer from 'multer';
 import { z } from 'zod';
 
 import * as db from '../services/db/index.db';
-import { logger } from '../services/logger.server';
-import { UserProfile } from '../types';
+import type { UserProfile } from '../types';
 import { geocodingService } from '../services/geocodingService.server';
 import { requireFileUpload } from '../middleware/fileUpload.middleware'; // This was a duplicate, fixed.
 import { NotFoundError, ValidationError } from '../services/db/errors.db';
@@ -33,45 +32,27 @@ import {
   weeklyAnalyticsWorker,
 } from '../services/queueService.server'; // Import your queues
 import { getSimpleWeekAndYear } from '../utils/dateUtils';
+import {
+  requiredString,
+  numericIdParam,
+  uuidParamSchema,
+  optionalNumeric,
+} from '../utils/zodUtils';
+import { logger } from '../services/logger.server';
 
-// Helper for consistent required string validation (handles missing/null/empty)
-const requiredString = (message: string) =>
-  z.preprocess((val) => val ?? '', z.string().min(1, message));
-
-/**
- * A factory for creating a Zod schema that validates a UUID in the request parameters.
- * @param key The name of the parameter key (e.g., 'userId').
- * @param message A custom error message for invalid UUIDs.
- */
-const uuidParamSchema = (key: string, message = `Invalid UUID for parameter '${key}'.`) =>
-  z.object({
-    params: z.object({ [key]: z.string().uuid({ message }) }),
-  });
-
-/**
- * A factory for creating a Zod schema that validates a numeric ID in the request parameters.
- */
-const numericIdParamSchema = (
-  key: string,
-  message = `Invalid ID for parameter '${key}'. Must be a positive integer.`,
-) =>
-  z.object({
-    params: z.object({ [key]: z.coerce.number().int({ message }).positive({ message }) }),
-  });
-
-const updateCorrectionSchema = numericIdParamSchema('id').extend({
+const updateCorrectionSchema = numericIdParam('id').extend({
   body: z.object({
     suggested_value: requiredString('A new suggested_value is required.'),
   }),
 });
 
-const updateRecipeStatusSchema = numericIdParamSchema('id').extend({
+const updateRecipeStatusSchema = numericIdParam('id').extend({
   body: z.object({
     status: z.enum(['private', 'pending_review', 'public', 'rejected']),
   }),
 });
 
-const updateCommentStatusSchema = numericIdParamSchema('id').extend({
+const updateCommentStatusSchema = numericIdParam('id').extend({
   body: z.object({
     status: z.enum(['visible', 'hidden', 'reported']),
   }),
@@ -85,8 +66,8 @@ const updateUserRoleSchema = uuidParamSchema('id', 'A valid user ID is required.
 
 const activityLogSchema = z.object({
   query: z.object({
-    limit: z.coerce.number().int().positive().optional().default(50),
-    offset: z.coerce.number().int().nonnegative().optional().default(0),
+    limit: optionalNumeric({ default: 50, integer: true, positive: true }),
+    offset: optionalNumeric({ default: 0, integer: true, nonnegative: true }),
   }),
 });
 
@@ -187,10 +168,10 @@ router.get('/stats/daily', async (req, res, next: NextFunction) => {
 
 router.post(
   '/corrections/:id/approve',
-  validateRequest(numericIdParamSchema('id')),
+  validateRequest(numericIdParam('id')),
   async (req: Request, res: Response, next: NextFunction) => {
     // Apply ADR-003 pattern for type safety
-    const { params } = req as unknown as z.infer<ReturnType<typeof numericIdParamSchema>>;
+    const { params } = req as unknown as z.infer<ReturnType<typeof numericIdParam>>;
     try {
       await db.adminRepo.approveCorrection(params.id, req.log); // params.id is now safely typed as number
       res.status(200).json({ message: 'Correction approved successfully.' });
@@ -202,10 +183,10 @@ router.post(
 
 router.post(
   '/corrections/:id/reject',
-  validateRequest(numericIdParamSchema('id')),
+  validateRequest(numericIdParam('id')),
   async (req: Request, res: Response, next: NextFunction) => {
     // Apply ADR-003 pattern for type safety
-    const { params } = req as unknown as z.infer<ReturnType<typeof numericIdParamSchema>>;
+    const { params } = req as unknown as z.infer<ReturnType<typeof numericIdParam>>;
     try {
       await db.adminRepo.rejectCorrection(params.id, req.log); // params.id is now safely typed as number
       res.status(200).json({ message: 'Correction rejected successfully.' });
@@ -251,12 +232,12 @@ router.put(
 
 router.post(
   '/brands/:id/logo',
-  validateRequest(numericIdParamSchema('id')),
+  validateRequest(numericIdParam('id')),
   upload.single('logoImage'),
   requireFileUpload('logoImage'),
   async (req: Request, res: Response, next: NextFunction) => {
     // Apply ADR-003 pattern for type safety
-    const { params } = req as unknown as z.infer<ReturnType<typeof numericIdParamSchema>>;
+    const { params } = req as unknown as z.infer<ReturnType<typeof numericIdParam>>;
     try {
       // Although requireFileUpload middleware should ensure the file exists,
       // this check satisfies TypeScript and adds robustness.
@@ -288,11 +269,11 @@ router.get('/unmatched-items', async (req, res, next: NextFunction) => {
  */
 router.delete(
   '/recipes/:recipeId',
-  validateRequest(numericIdParamSchema('recipeId')),
+  validateRequest(numericIdParam('recipeId')),
   async (req: Request, res: Response, next: NextFunction) => {
     const userProfile = req.user as UserProfile;
     // Infer the type directly from the schema generator function. // This was a duplicate, fixed.
-    const { params } = req as unknown as z.infer<ReturnType<typeof numericIdParamSchema>>;
+    const { params } = req as unknown as z.infer<ReturnType<typeof numericIdParam>>;
     try {
       // The isAdmin flag bypasses the ownership check in the repository method.
       await db.recipeRepo.deleteRecipe(params.recipeId, userProfile.user.user_id, true, req.log);
@@ -308,10 +289,10 @@ router.delete(
  */
 router.delete(
   '/flyers/:flyerId',
-  validateRequest(numericIdParamSchema('flyerId')),
+  validateRequest(numericIdParam('flyerId')),
   async (req: Request, res: Response, next: NextFunction) => {
     // Infer the type directly from the schema generator function.
-    const { params } = req as unknown as z.infer<ReturnType<typeof numericIdParamSchema>>;
+    const { params } = req as unknown as z.infer<ReturnType<typeof numericIdParam>>;
     try {
       await db.flyerRepo.deleteFlyer(params.flyerId, req.log);
       res.status(204).send();
@@ -435,12 +416,10 @@ router.post(
       // We call the function but don't wait for it to finish (no `await`).
       // This is a "fire-and-forget" operation from the client's perspective.
       backgroundJobService.runDailyDealCheck();
-      res
-        .status(202)
-        .json({
-          message:
-            'Daily deal check job has been triggered successfully. It will run in the background.',
-        });
+      res.status(202).json({
+        message:
+          'Daily deal check job has been triggered successfully. It will run in the background.',
+      });
     } catch (error) {
       logger.error({ error }, '[Admin] Failed to trigger daily deal check job.');
       next(error);
@@ -467,11 +446,9 @@ router.post(
 
       const job = await analyticsQueue.add('generate-daily-report', { reportDate }, { jobId });
 
-      res
-        .status(202)
-        .json({
-          message: `Analytics report generation job has been enqueued successfully. Job ID: ${job.id}`,
-        });
+      res.status(202).json({
+        message: `Analytics report generation job has been enqueued successfully. Job ID: ${job.id}`,
+      });
     } catch (error) {
       logger.error({ error }, '[Admin] Failed to enqueue analytics report job.');
       next(error);
@@ -485,11 +462,11 @@ router.post(
  */
 router.post(
   '/flyers/:flyerId/cleanup',
-  validateRequest(numericIdParamSchema('flyerId')),
+  validateRequest(numericIdParam('flyerId')),
   async (req: Request, res: Response, next: NextFunction) => {
     const userProfile = req.user as UserProfile;
     // Infer type from the schema generator for type safety, as per ADR-003.
-    const { params } = req as unknown as z.infer<ReturnType<typeof numericIdParamSchema>>; // This was a duplicate, fixed.
+    const { params } = req as unknown as z.infer<ReturnType<typeof numericIdParam>>; // This was a duplicate, fixed.
     logger.info(
       `[Admin] Manual trigger for flyer file cleanup received from user: ${userProfile.user.user_id} for flyer ID: ${params.flyerId}`,
     );
@@ -541,11 +518,9 @@ router.post(
 
     try {
       const keysDeleted = await geocodingService.clearGeocodeCache(req.log);
-      res
-        .status(200)
-        .json({
-          message: `Successfully cleared the geocode cache. ${keysDeleted} keys were removed.`,
-        });
+      res.status(200).json({
+        message: `Successfully cleared the geocode cache. ${keysDeleted} keys were removed.`,
+      });
     } catch (error) {
       logger.error({ error }, '[Admin] Failed to clear geocode cache.');
       next(error);

src/routes/admin.stats.routes.test.ts

@@ -73,12 +73,6 @@ describe('Admin Stats Routes (/api/admin/stats)', () => {
     authenticatedUser: adminUser,
   });
 
-  // Add a basic error handler to capture errors passed to next(err) and return JSON.
-  // This prevents unhandled error crashes in tests and ensures we get the 500 response we expect.
-  app.use((err: any, req: any, res: any, next: any) => {
-    res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-  });
-
   beforeEach(() => {
     vi.clearAllMocks();
   });

src/routes/admin.system.routes.test.ts

@@ -79,12 +79,6 @@ describe('Admin System Routes (/api/admin/system)', () => {
     authenticatedUser: adminUser,
   });
 
-  // Add a basic error handler to capture errors passed to next(err) and return JSON.
-  // This prevents unhandled error crashes in tests and ensures we get the 500 response we expect.
-  app.use((err: any, req: any, res: any, next: any) => {
-    res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-  });
-
   beforeEach(() => {
     vi.clearAllMocks();
   });

src/routes/admin.users.routes.test.ts

@@ -83,12 +83,6 @@ describe('Admin User Management Routes (/api/admin/users)', () => {
     authenticatedUser: adminUser,
   });
 
-  // Add a basic error handler to capture errors passed to next(err) and return JSON.
-  // This prevents unhandled error crashes in tests and ensures we get the 500 response we expect.
-  app.use((err: any, req: any, res: any, next: any) => {
-    res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-  });
-
   beforeEach(() => {
     vi.clearAllMocks();
   });

src/routes/ai.routes.test.ts

@@ -78,6 +78,7 @@ describe('AI Routes (/api/ai)', () => {
     vi.mocked(mockLogger.info).mockImplementation(() => {});
     vi.mocked(mockLogger.error).mockImplementation(() => {});
     vi.mocked(mockLogger.warn).mockImplementation(() => {});
+    vi.mocked(mockLogger.debug).mockImplementation(() => {}); // Ensure debug is also mocked
   });
   const app = createTestApp({ router: aiRouter, basePath: '/api/ai' });
 
@@ -111,10 +112,55 @@ describe('AI Routes (/api/ai)', () => {
     });
   });
 
-  // Add a basic error handler to capture errors passed to next(err) and return JSON.
-  // This prevents unhandled error crashes in tests and ensures we get the 500 response we expect.
-  app.use((err: any, req: any, res: any, next: any) => {
-    res.status(err.status || 500).json({ message: err.message, errors: err.errors });
+  // New test to cover the router.use diagnostic middleware's catch block and errMsg branches
+  describe('Diagnostic Middleware Error Handling', () => {
+    it('should log an error if logger.debug throws an object with a message property', async () => {
+      const mockErrorObject = { message: 'Mock debug error' };
+      vi.mocked(mockLogger.debug).mockImplementationOnce(() => {
+        throw mockErrorObject;
+      });
+
+      // Make any request to trigger the middleware
+      const response = await supertest(app).get('/api/ai/jobs/job-123/status');
+
+      expect(mockLogger.error).toHaveBeenCalledWith(
+        { error: mockErrorObject.message }, // errMsg should extract the message
+        'Failed to log incoming AI request headers',
+      );
+      // The request should still proceed, but might fail later if the original flow was interrupted.
+      // Here, it will likely hit the 404 for job not found.
+      expect(response.status).toBe(404);
+    });
+
+    it('should log an error if logger.debug throws a primitive string', async () => {
+      const mockErrorString = 'Mock debug error string';
+      vi.mocked(mockLogger.debug).mockImplementationOnce(() => {
+        throw mockErrorString;
+      });
+
+      // Make any request to trigger the middleware
+      const response = await supertest(app).get('/api/ai/jobs/job-123/status');
+
+      expect(mockLogger.error).toHaveBeenCalledWith(
+        { error: mockErrorString }, // errMsg should convert to string
+        'Failed to log incoming AI request headers',
+      );
+      expect(response.status).toBe(404);
+    });
+
+    it('should log an error if logger.debug throws null/undefined', async () => {
+      vi.mocked(mockLogger.debug).mockImplementationOnce(() => {
+        throw null; // Simulate throwing null
+      });
+
+      const response = await supertest(app).get('/api/ai/jobs/job-123/status');
+
+      expect(mockLogger.error).toHaveBeenCalledWith(
+        { error: 'An unknown error occurred.' }, // errMsg should handle null/undefined
+        'Failed to log incoming AI request headers',
+      );
+      expect(response.status).toBe(404);
+    });
   });
 
   describe('POST /upload-and-process', () => {
@@ -423,6 +469,52 @@ describe('AI Routes (/api/ai)', () => {
       expect(mockedDb.createFlyerAndItems).toHaveBeenCalledTimes(1);
     });
 
+   it('should handle payload where extractedData is null', async () => {
+      const payloadWithNullExtractedData = {
+        checksum: 'null-extracted-data-checksum',
+        originalFileName: 'flyer-null.jpg',
+        extractedData: null,
+      };
+
+      const response = await supertest(app)
+        .post('/api/ai/flyers/process')
+        .field('data', JSON.stringify(payloadWithNullExtractedData))
+        .attach('flyerImage', imagePath);
+
+      expect(response.status).toBe(201);
+      expect(mockedDb.createFlyerAndItems).toHaveBeenCalledTimes(1);
+      // Verify that extractedData was correctly defaulted to an empty object
+      const flyerDataArg = vi.mocked(mockedDb.createFlyerAndItems).mock.calls[0][0];
+      expect(flyerDataArg.store_name).toContain('Unknown Store'); // Fallback should be used
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        { bodyData: expect.any(Object) },
+        'Missing extractedData in /api/ai/flyers/process payload.',
+      );
+    });
+
+    it('should handle payload where extractedData is a string', async () => {
+      const payloadWithStringExtractedData = {
+        checksum: 'string-extracted-data-checksum',
+        originalFileName: 'flyer-string.jpg',
+        extractedData: 'not-an-object',
+      };
+
+      const response = await supertest(app)
+        .post('/api/ai/flyers/process')
+        .field('data', JSON.stringify(payloadWithStringExtractedData))
+        .attach('flyerImage', imagePath);
+
+      expect(response.status).toBe(201);
+      expect(mockedDb.createFlyerAndItems).toHaveBeenCalledTimes(1);
+      // Verify that extractedData was correctly defaulted to an empty object
+      const flyerDataArg = vi.mocked(mockedDb.createFlyerAndItems).mock.calls[0][0];
+      expect(flyerDataArg.store_name).toContain('Unknown Store'); // Fallback should be used
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        { bodyData: expect.any(Object) },
+        'Missing extractedData in /api/ai/flyers/process payload.',
+      );
+    });
+
     it('should handle payload where extractedData is at the root of the body', async () => {
       // This simulates a client sending multipart fields for each property of extractedData
       const response = await supertest(app)
@@ -557,10 +649,11 @@ describe('AI Routes (/api/ai)', () => {
     const mockUser = createMockUserProfile({
       user: { user_id: 'user-123', email: 'user-123@test.com' },
     });
+    const authenticatedApp = createTestApp({ router: aiRouter, basePath: '/api/ai', authenticatedUser: mockUser });
 
     beforeEach(() => {
       // Inject an authenticated user for this test block
-      app.use((req, res, next) => {
+      authenticatedApp.use((req, res, next) => {
         req.user = mockUser;
         next();
       });
@@ -575,7 +668,7 @@ describe('AI Routes (/api/ai)', () => {
         .field('cropArea', JSON.stringify({ x: 10, y: 10, width: 50, height: 50 }))
         .field('extractionType', 'item_details')
         .attach('image', imagePath);
-
+      // Use the authenticatedApp instance for requests in this block
       expect(response.status).toBe(200);
       expect(response.body).toEqual(mockResult);
       expect(aiService.aiService.extractTextFromImageArea).toHaveBeenCalled();
@@ -586,7 +679,7 @@ describe('AI Routes (/api/ai)', () => {
         new Error('AI API is down'),
       );
 
-      const response = await supertest(app)
+      const response = await supertest(authenticatedApp)
         .post('/api/ai/rescan-area')
         .field('cropArea', JSON.stringify({ x: 10, y: 10, width: 50, height: 50 }))
         .field('extractionType', 'item_details')
@@ -602,15 +695,12 @@ describe('AI Routes (/api/ai)', () => {
     const mockUserProfile = createMockUserProfile({
       user: { user_id: 'user-123', email: 'user-123@test.com' },
     });
+    const authenticatedApp = createTestApp({ router: aiRouter, basePath: '/api/ai', authenticatedUser: mockUserProfile });
 
     beforeEach(() => {
-      // For this block, simulate an authenticated request by attaching the user.
-      app.use((req, res, next) => {
-        req.user = mockUserProfile;
-        next();
-      });
+      // The authenticatedApp instance is already set up with mockUserProfile
     });
-
+    
     it('POST /quick-insights should return the stubbed response', async () => {
       const response = await supertest(app)
         .post('/api/ai/quick-insights')

src/routes/ai.routes.ts

@@ -15,6 +15,7 @@ import { logger } from '../services/logger.server';
 import { UserProfile, ExtractedCoreData, ExtractedFlyerItem } from '../types';
 import { flyerQueue } from '../services/queueService.server';
 import { validateRequest } from '../middleware/validation.middleware';
+import { requiredString } from '../utils/zodUtils';
 
 const router = Router();
 
@@ -26,9 +27,6 @@ interface FlyerProcessPayload extends Partial<ExtractedCoreData> {
 }
 
 // --- Zod Schemas for AI Routes (as per ADR-003) ---
-// Helper for consistent required string validation (handles missing/null/empty)
-const requiredString = (message: string) =>
-  z.preprocess((val) => val ?? '', z.string().min(1, message));
 
 const uploadAndProcessSchema = z.object({
   body: z.object({

src/routes/auth.routes.ts

@@ -1,13 +1,12 @@
 // src/routes/auth.routes.ts
 import { Router, Request, Response, NextFunction } from 'express';
 import * as bcrypt from 'bcrypt';
-import zxcvbn from 'zxcvbn';
 import { z } from 'zod';
 import jwt from 'jsonwebtoken';
 import crypto from 'crypto';
 import rateLimit from 'express-rate-limit';
 
-import passport from './passport.routes'; // Corrected import path
+import passport from './passport.routes';
 import { userRepo, adminRepo } from '../services/db/index.db';
 import { UniqueConstraintError } from '../services/db/errors.db';
 import { getPool } from '../services/db/connection.db';
@@ -15,38 +14,13 @@ import { logger } from '../services/logger.server';
 import { sendPasswordResetEmail } from '../services/emailService.server';
 import { validateRequest } from '../middleware/validation.middleware';
 import type { UserProfile } from '../types';
+import { validatePasswordStrength } from '../utils/authUtils';
+import { requiredString } from '../utils/zodUtils';
 
 const router = Router();
 
 const JWT_SECRET = process.env.JWT_SECRET!;
 
-/**
- * Validates the strength of a password using zxcvbn.
- * @param password The password to check.
- * @returns An object with `isValid` and an optional `feedback` message.
- */
-const validatePasswordStrength = (password: string): { isValid: boolean; feedback?: string } => {
-  const MIN_PASSWORD_SCORE = 3; // Require a 'Good' or 'Strong' password (score 3 or 4)
-  const strength = zxcvbn(password);
-
-  if (strength.score < MIN_PASSWORD_SCORE) {
-    const feedbackMessage =
-      strength.feedback.warning ||
-      (strength.feedback.suggestions && strength.feedback.suggestions[0]);
-    return {
-      isValid: false,
-      feedback:
-        `Password is too weak. ${feedbackMessage || 'Please choose a stronger password.'}`.trim(),
-    };
-  }
-
-  return { isValid: true };
-};
-
-// Helper for consistent required string validation (handles missing/null/empty)
-const requiredString = (message: string) =>
-  z.preprocess((val) => val ?? '', z.string().min(1, message));
-
 // Conditionally disable rate limiting for the test environment
 const isTestEnv = process.env.NODE_ENV === 'test';
 
@@ -69,8 +43,6 @@ const resetPasswordLimiter = rateLimit({
   skip: () => isTestEnv, // Skip this middleware if in test environment
 });
 
-// --- Zod Schemas for Auth Routes (as per ADR-003) ---
-
 const registerSchema = z.object({
   body: z.object({
     email: z.string().email('A valid email is required.'),
@@ -213,7 +185,7 @@ router.post('/login', (req: Request, res: Response, next: NextFunction) => {
       const accessToken = jwt.sign(payload, JWT_SECRET, { expiresIn: '15m' });
 
       try {
-        const refreshToken = crypto.randomBytes(64).toString('hex'); // This was a duplicate, fixed.
+        const refreshToken = crypto.randomBytes(64).toString('hex');
         await userRepo.saveRefreshToken(userProfile.user.user_id, refreshToken, req.log);
         req.log.info(`JWT and refresh token issued for user: ${userProfile.user.email}`);
 

src/routes/budget.routes.test.ts

@@ -69,17 +69,7 @@ describe('Budget Routes (/api/budgets)', () => {
     vi.mocked(db.budgetRepo.getSpendingByCategory).mockResolvedValue([]);
   });
 
-  const app = createTestApp({
-    router: budgetRouter,
-    basePath: '/api/budgets',
-    authenticatedUser: mockUser,
-  });
-
-  // Add a basic error handler to capture errors passed to next(err) and return JSON.
-  // This prevents unhandled error crashes in tests and ensures we get the 500 response we expect.
-  app.use((err: any, req: any, res: any, next: any) => {
-    res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-  });
+  const app = createTestApp({ router: budgetRouter, basePath: '/api/budgets', authenticatedUser: mockUserProfile });
 
   describe('GET /', () => {
     it('should return a list of budgets for the user', async () => {

src/routes/budget.routes.ts

@@ -5,20 +5,12 @@ import passport from './passport.routes';
 import { budgetRepo } from '../services/db/index.db';
 import type { UserProfile } from '../types';
 import { validateRequest } from '../middleware/validation.middleware';
+import { requiredString, numericIdParam } from '../utils/zodUtils';
 
 const router = express.Router();
 
-// Helper for consistent required string validation (handles missing/null/empty)
-const requiredString = (message: string) =>
-  z.preprocess((val) => val ?? '', z.string().min(1, message));
-
 // --- Zod Schemas for Budget Routes (as per ADR-003) ---
-
-const budgetIdParamSchema = z.object({
-  params: z.object({
-    id: z.coerce.number().int().positive("Invalid ID for parameter 'id'. Must be a number."),
-  }),
-});
+const budgetIdParamSchema = numericIdParam('id', "Invalid ID for parameter 'id'. Must be a number.");
 
 const createBudgetSchema = z.object({
   body: z.object({

src/routes/deals.routes.test.ts

@@ -54,13 +54,6 @@ describe('Deals Routes (/api/users/deals)', () => {
     authenticatedUser: mockUser,
   });
   const unauthenticatedApp = createTestApp({ router: dealsRouter, basePath });
-  const errorHandler = (err: any, req: any, res: any, next: any) => {
-    res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-  };
-
-  // Apply the handler to both app instances
-  authenticatedApp.use(errorHandler);
-  unauthenticatedApp.use(errorHandler);
 
   beforeEach(() => {
     vi.clearAllMocks();

src/routes/flyer.routes.test.ts

@@ -40,12 +40,6 @@ describe('Flyer Routes (/api/flyers)', () => {
 
   const app = createTestApp({ router: flyerRouter, basePath: '/api/flyers' });
 
-  // Add a basic error handler to capture errors passed to next(err) and return JSON.
-  // This prevents unhandled error crashes in tests and ensures we get the 500 response we expect.
-  app.use((err: any, req: any, res: any, next: any) => {
-    res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-  });
-
   describe('GET /', () => {
     it('should return a list of flyers on success', async () => {
       const mockFlyers = [createMockFlyer({ flyer_id: 1 }), createMockFlyer({ flyer_id: 2 })];

src/routes/flyer.routes.ts

@@ -3,6 +3,7 @@ import { Router } from 'express';
 import * as db from '../services/db/index.db';
 import { z } from 'zod';
 import { validateRequest } from '../middleware/validation.middleware';
+import { optionalNumeric } from '../utils/zodUtils';
 
 const router = Router();
 
@@ -10,8 +11,8 @@ const router = Router();
 
 const getFlyersSchema = z.object({
   query: z.object({
-    limit: z.coerce.number().int().positive().optional().default(20),
-    offset: z.coerce.number().int().nonnegative().optional().default(0),
+    limit: optionalNumeric({ default: 20, integer: true, positive: true }),
+    offset: optionalNumeric({ default: 0, integer: true, nonnegative: true }),
   }),
 });
 

src/routes/gamification.routes.test.ts

@@ -86,12 +86,6 @@ describe('Gamification Routes (/api/achievements)', () => {
     basePath,
     authenticatedUser: mockAdminProfile,
   });
-  const errorHandler = (err: any, req: any, res: any, next: any) => {
-    res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-  };
-  unauthenticatedApp.use(errorHandler);
-  authenticatedApp.use(errorHandler);
-  adminApp.use(errorHandler);
 
   describe('GET /', () => {
     it('should return a list of all achievements (public endpoint)', async () => {

src/routes/gamification.routes.ts

@@ -7,19 +7,16 @@ import { logger } from '../services/logger.server';
 import { UserProfile } from '../types';
 import { ForeignKeyConstraintError } from '../services/db/errors.db';
 import { validateRequest } from '../middleware/validation.middleware';
+import { requiredString, optionalNumeric } from '../utils/zodUtils';
 
 const router = express.Router();
 const adminGamificationRouter = express.Router(); // Create a new router for admin-only routes.
 
-// Helper for consistent required string validation (handles missing/null/empty)
-const requiredString = (message: string) =>
-  z.preprocess((val) => val ?? '', z.string().min(1, message));
-
 // --- Zod Schemas for Gamification Routes (as per ADR-003) ---
 
 const leaderboardSchema = z.object({
   query: z.object({
-    limit: z.coerce.number().int().positive().max(50).optional().default(10),
+    limit: optionalNumeric({ default: 10, integer: true, positive: true, max: 50 }),
   }),
 });
 

src/routes/health.routes.test.ts

@@ -46,12 +46,6 @@ const { logger } = await import('../services/logger.server');
 // 2. Create a minimal Express app to host the router for testing.
 const app = createTestApp({ router: healthRouter, basePath: '/api/health' });
 
-// Add a basic error handler to capture errors passed to next(err) and return JSON.
-// This prevents unhandled error crashes in tests and ensures we get the 500 response we expect.
-app.use((err: any, req: any, res: any, next: any) => {
-  res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-});
-
 describe('Health Routes (/api/health)', () => {
   beforeEach(() => {
     // Clear mock history before each test to ensure isolation.

src/routes/personalization.routes.test.ts

@@ -30,12 +30,6 @@ vi.mock('../services/logger.server', () => ({
 describe('Personalization Routes (/api/personalization)', () => {
   const app = createTestApp({ router: personalizationRouter, basePath: '/api/personalization' });
 
-  // Add a basic error handler to capture errors passed to next(err) and return JSON.
-  // This prevents unhandled error crashes in tests and ensures we get the 500 response we expect.
-  app.use((err: any, req: any, res: any, next: any) => {
-    res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-  });
-
   beforeEach(() => {
     vi.clearAllMocks();
   });

src/routes/price.routes.test.ts

@@ -4,8 +4,21 @@ import supertest from 'supertest';
 import { createTestApp } from '../tests/utils/createTestApp';
 import { mockLogger } from '../tests/utils/mockLogger';
 
+// Mock the price repository
+vi.mock('../services/db/price.db', () => ({
+  priceRepo: {
+    getPriceHistory: vi.fn(),
+  },
+}));
+
+// Mock the logger to keep test output clean
+vi.mock('../services/logger.server', () => ({
+  logger: mockLogger,
+}));
+
 // Import the router AFTER other setup.
 import priceRouter from './price.routes';
+import { priceRepo } from '../services/db/price.db';
 
 describe('Price Routes (/api/price-history)', () => {
   const app = createTestApp({ router: priceRouter, basePath: '/api/price-history' });
@@ -14,32 +27,103 @@ describe('Price Routes (/api/price-history)', () => {
   });
 
   describe('POST /', () => {
-    it('should return 200 OK with an empty array for a valid request', async () => {
-      const masterItemIds = [1, 2, 3];
-      const response = await supertest(app).post('/api/price-history').send({ masterItemIds });
+    it('should return 200 OK with price history data for a valid request', async () => {
+      const mockHistory = [
+        { master_item_id: 1, price_in_cents: 199, date: '2024-01-01T00:00:00.000Z' },
+        { master_item_id: 2, price_in_cents: 299, date: '2024-01-08T00:00:00.000Z' },
+      ];
+      vi.mocked(priceRepo.getPriceHistory).mockResolvedValue(mockHistory);
+
+      const response = await supertest(app)
+        .post('/api/price-history')
+        .send({ masterItemIds: [1, 2] });
 
       expect(response.status).toBe(200);
-      expect(response.body).toEqual([]);
+      expect(response.body).toEqual(mockHistory);
+      expect(priceRepo.getPriceHistory).toHaveBeenCalledWith([1, 2], expect.any(Object), 1000, 0);
+    });
+
+    it('should pass limit and offset from the body to the repository', async () => {
+      vi.mocked(priceRepo.getPriceHistory).mockResolvedValue([]);
+      await supertest(app)
+        .post('/api/price-history')
+        .send({ masterItemIds: [1, 2, 3], limit: 50, offset: 10 });
+
+      expect(priceRepo.getPriceHistory).toHaveBeenCalledWith(
+        [1, 2, 3],
+        expect.any(Object),
+        50,
+        10,
+      );
+    });
+
+    it('should log the request info', async () => {
+      vi.mocked(priceRepo.getPriceHistory).mockResolvedValue([]);
+      await supertest(app)
+        .post('/api/price-history')
+        .send({ masterItemIds: [1, 2, 3], limit: 25, offset: 5 });
+
       expect(mockLogger.info).toHaveBeenCalledWith(
-        { itemCount: masterItemIds.length },
+        { itemCount: 3, limit: 25, offset: 5 },
         '[API /price-history] Received request for historical price data.',
       );
     });
 
+    it('should return 500 if the database call fails', async () => {
+      const dbError = new Error('Database connection failed');
+      vi.mocked(priceRepo.getPriceHistory).mockRejectedValue(dbError);
+
+      const response = await supertest(app)
+        .post('/api/price-history')
+        .send({ masterItemIds: [1, 2, 3] });
+
+      expect(response.status).toBe(500);
+      expect(response.body.message).toBe('Database connection failed');
+    });
+
+    it('should return 400 if masterItemIds is an empty array', async () => {
+      const response = await supertest(app).post('/api/price-history').send({ masterItemIds: [] });
+
+      expect(response.status).toBe(400);
+      expect(response.body.errors[0].message).toBe(
+        'masterItemIds must be a non-empty array of positive integers.',
+      );
+    });
+
     it('should return 400 if masterItemIds is not an array', async () => {
       const response = await supertest(app)
         .post('/api/price-history')
         .send({ masterItemIds: 'not-an-array' });
+
       expect(response.status).toBe(400);
-      expect(response.body.errors[0].message).toMatch(/Expected array, received string/i);
+      expect(response.body.errors[0].message).toContain('Expected array, received string');
     });
 
-    it('should return 400 if masterItemIds is an empty array', async () => {
-      const response = await supertest(app).post('/api/price-history').send({ masterItemIds: [] });
+    it('should return 400 if masterItemIds contains non-positive integers', async () => {
+      const response = await supertest(app)
+        .post('/api/price-history')
+        .send({ masterItemIds: [1, -2, 3] });
+
       expect(response.status).toBe(400);
-      expect(response.body.errors[0].message).toBe(
-        'masterItemIds must be a non-empty array of positive integers.',
-      );
+      expect(response.body.errors[0].message).toBe('Number must be greater than 0');
+    });
+
+    it('should return 400 if masterItemIds is missing', async () => {
+      const response = await supertest(app).post('/api/price-history').send({});
+
+      expect(response.status).toBe(400);
+      expect(response.body.errors[0].message).toBe('Required');
+    });
+
+    it('should return 400 for invalid limit and offset', async () => {
+      const response = await supertest(app)
+        .post('/api/price-history')
+        .send({ masterItemIds: [1], limit: -1, offset: 'abc' });
+
+      expect(response.status).toBe(400);
+      expect(response.body.errors).toHaveLength(2);
+      expect(response.body.errors[0].message).toBe('Number must be greater than 0');
+      expect(response.body.errors[1].message).toBe('Expected number, received string');
     });
   });
 });

src/routes/price.routes.ts

@@ -1,15 +1,21 @@
 // src/routes/price.routes.ts
-import { Router, Request, Response } from 'express';
+import { Router, Request, Response, NextFunction } from 'express';
 import { z } from 'zod';
 import { validateRequest } from '../middleware/validation.middleware';
+import { priceRepo } from '../services/db/price.db';
+import { optionalNumeric } from '../utils/zodUtils';
 
 const router = Router();
 
 const priceHistorySchema = z.object({
   body: z.object({
-    masterItemIds: z.array(z.number().int().positive()).nonempty({
-      message: 'masterItemIds must be a non-empty array of positive integers.',
-    }),
+    masterItemIds: z
+      .array(z.number().int().positive('Number must be greater than 0'))
+      .nonempty({
+        message: 'masterItemIds must be a non-empty array of positive integers.',
+      }),
+    limit: optionalNumeric({ default: 1000, integer: true, positive: true }),
+    offset: optionalNumeric({ default: 0, integer: true, nonnegative: true }),
   }),
 });
 
@@ -18,18 +24,23 @@ type PriceHistoryRequest = z.infer<typeof priceHistorySchema>;
 
 /**
  * POST /api/price-history - Fetches historical price data for a given list of master item IDs.
- * This is a placeholder implementation.
+ * This endpoint retrieves price points over time for specified master grocery items.
  */
-router.post('/', validateRequest(priceHistorySchema), async (req: Request, res: Response) => {
+router.post('/', validateRequest(priceHistorySchema), async (req: Request, res: Response, next: NextFunction) => {
   // Cast 'req' to the inferred type for full type safety.
   const {
-    body: { masterItemIds },
+    body: { masterItemIds, limit, offset },
   } = req as unknown as PriceHistoryRequest;
   req.log.info(
-    { itemCount: masterItemIds.length },
+    { itemCount: masterItemIds.length, limit, offset },
     '[API /price-history] Received request for historical price data.',
   );
-  res.status(200).json([]);
+  try {
+    const priceHistory = await priceRepo.getPriceHistory(masterItemIds, req.log, limit, offset);
+    res.status(200).json(priceHistory);
+  } catch (error) {
+    next(error);
+  }
 });
 
 export default router;

src/routes/recipe.routes.test.ts

@@ -35,12 +35,6 @@ const expectLogger = expect.objectContaining({
 describe('Recipe Routes (/api/recipes)', () => {
   const app = createTestApp({ router: recipeRouter, basePath: '/api/recipes' });
 
-  // Add a basic error handler to capture errors passed to next(err) and return JSON.
-  // This prevents unhandled error crashes in tests and ensures we get the 500 response we expect.
-  app.use((err: any, req: any, res: any, next: any) => {
-    res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-  });
-
   beforeEach(() => {
     vi.clearAllMocks();
   });

src/routes/recipe.routes.ts

@@ -3,24 +3,19 @@ import { Router } from 'express';
 import { z } from 'zod';
 import * as db from '../services/db/index.db';
 import { validateRequest } from '../middleware/validation.middleware';
+import { requiredString, numericIdParam, optionalNumeric } from '../utils/zodUtils';
 
 const router = Router();
 
-// Helper for consistent required string validation (handles missing/null/empty)
-const requiredString = (message: string) =>
-  z.preprocess((val) => val ?? '', z.string().min(1, message));
-
-// --- Zod Schemas for Recipe Routes (as per ADR-003) ---
-
 const bySalePercentageSchema = z.object({
   query: z.object({
-    minPercentage: z.coerce.number().min(0).max(100).optional().default(50),
+    minPercentage: optionalNumeric({ default: 50, min: 0, max: 100 }),
   }),
 });
 
 const bySaleIngredientsSchema = z.object({
   query: z.object({
-    minIngredients: z.coerce.number().int().positive().optional().default(3),
+    minIngredients: optionalNumeric({ default: 3, integer: true, positive: true }),
   }),
 });
 
@@ -31,11 +26,7 @@ const byIngredientAndTagSchema = z.object({
   }),
 });
 
-const recipeIdParamsSchema = z.object({
-  params: z.object({
-    recipeId: z.coerce.number().int().positive(),
-  }),
-});
+const recipeIdParamsSchema = numericIdParam('recipeId');
 
 /**
  * GET /api/recipes/by-sale-percentage - Get recipes based on the percentage of their ingredients on sale.
@@ -47,7 +38,7 @@ router.get(
     try {
       // Explicitly parse req.query to apply coercion (string -> number) and default values
       const { query } = bySalePercentageSchema.parse({ query: req.query });
-      const recipes = await db.recipeRepo.getRecipesBySalePercentage(query.minPercentage, req.log);
+      const recipes = await db.recipeRepo.getRecipesBySalePercentage(query.minPercentage!, req.log);
       res.json(recipes);
     } catch (error) {
       req.log.error({ error }, 'Error fetching recipes in /api/recipes/by-sale-percentage:');
@@ -67,7 +58,7 @@ router.get(
       // Explicitly parse req.query to apply coercion (string -> number) and default values
       const { query } = bySaleIngredientsSchema.parse({ query: req.query });
       const recipes = await db.recipeRepo.getRecipesByMinSaleIngredients(
-        query.minIngredients,
+        query.minIngredients!,
         req.log,
       );
       res.json(recipes);

src/routes/stats.routes.test.ts

@@ -28,12 +28,6 @@ const expectLogger = expect.objectContaining({
 describe('Stats Routes (/api/stats)', () => {
   const app = createTestApp({ router: statsRouter, basePath: '/api/stats' });
 
-  // Add a basic error handler to capture errors passed to next(err) and return JSON.
-  // This prevents unhandled error crashes in tests and ensures we get the 500 response we expect.
-  app.use((err: any, req: any, res: any, next: any) => {
-    res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-  });
-
   beforeEach(() => {
     vi.clearAllMocks();
   });

src/routes/stats.routes.ts

@@ -3,6 +3,7 @@ import { Router, Request, Response, NextFunction } from 'express';
 import { z } from 'zod';
 import * as db from '../services/db/index.db';
 import { validateRequest } from '../middleware/validation.middleware';
+import { optionalNumeric } from '../utils/zodUtils';
 
 const router = Router();
 
@@ -10,8 +11,8 @@ const router = Router();
 
 // Define the query schema separately so we can use it to parse req.query in the handler
 const statsQuerySchema = z.object({
-  days: z.coerce.number().int().min(1).max(365).optional().default(30),
-  limit: z.coerce.number().int().min(1).max(50).optional().default(10),
+  days: optionalNumeric({ default: 30, min: 1, max: 365, integer: true }),
+  limit: optionalNumeric({ default: 10, min: 1, max: 50, integer: true }),
 });
 
 const mostFrequentSalesSchema = z.object({
@@ -31,7 +32,7 @@ router.get(
       // Even though validateRequest checks validity, it may not mutate req.query with the parsed result.
       const { days, limit } = statsQuerySchema.parse(req.query);
 
-      const items = await db.adminRepo.getMostFrequentSaleItems(days, limit, req.log);
+      const items = await db.adminRepo.getMostFrequentSaleItems(days!, limit!, req.log);
       res.json(items);
     } catch (error) {
       req.log.error(

src/routes/system.routes.test.ts

@@ -42,11 +42,6 @@ vi.mock('../services/logger.server', () => ({
 describe('System Routes (/api/system)', () => {
   const app = createTestApp({ router: systemRouter, basePath: '/api/system' });
 
-  // Add a basic error handler to capture errors passed to next(err) and return JSON.
-  app.use((err: any, req: any, res: any, next: any) => {
-    res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-  });
-
   beforeEach(() => {
     // We cast here to get type-safe access to mock functions like .mockImplementation
     vi.clearAllMocks();

src/routes/system.routes.ts

@@ -5,13 +5,10 @@ import { z } from 'zod';
 import { logger } from '../services/logger.server';
 import { geocodingService } from '../services/geocodingService.server';
 import { validateRequest } from '../middleware/validation.middleware';
+import { requiredString } from '../utils/zodUtils';
 
 const router = Router();
 
-// Helper for consistent required string validation (handles missing/null/empty)
-const requiredString = (message: string) =>
-  z.preprocess((val) => val ?? '', z.string().min(1, message));
-
 const geocodeSchema = z.object({
   body: z.object({
     address: requiredString('An address string is required.'),

src/routes/user.routes.test.ts

@@ -173,12 +173,6 @@ describe('User Routes (/api/users)', () => {
     });
     const app = createTestApp({ router: userRouter, basePath, authenticatedUser: mockUserProfile });
 
-    // Add a basic error handler to capture errors passed to next(err) and return JSON.
-    // This prevents unhandled error crashes in tests and ensures we get the 500 response we expect.
-    app.use((err: any, req: any, res: any, next: any) => {
-      res.status(err.status || 500).json({ message: err.message, errors: err.errors });
-    });
-
     beforeEach(() => {
       // All tests in this block will use the authenticated app
     });
@@ -883,20 +877,41 @@ describe('User Routes (/api/users)', () => {
     });
 
     describe('Notification Routes', () => {
-      it('GET /notifications should return notifications for the user', async () => {
+      it('GET /notifications should return only unread notifications by default', async () => {
         const mockNotifications: Notification[] = [
           createMockNotification({ user_id: 'user-123', content: 'Test' }),
         ];
         vi.mocked(db.notificationRepo.getNotificationsForUser).mockResolvedValue(mockNotifications);
 
-        const response = await supertest(app).get('/api/users/notifications?limit=10&offset=0');
+        const response = await supertest(app).get('/api/users/notifications?limit=10');
 
         expect(response.status).toBe(200);
         expect(response.body).toEqual(mockNotifications);
         expect(db.notificationRepo.getNotificationsForUser).toHaveBeenCalledWith(
           'user-123',
           10,
-          0,
+          0, // default offset
+          false, // default includeRead
+          expectLogger,
+        );
+      });
+
+      it('GET /notifications?includeRead=true should return all notifications', async () => {
+        const mockNotifications: Notification[] = [
+          createMockNotification({ user_id: 'user-123', content: 'Read', is_read: true }),
+          createMockNotification({ user_id: 'user-123', content: 'Unread', is_read: false }),
+        ];
+        vi.mocked(db.notificationRepo.getNotificationsForUser).mockResolvedValue(mockNotifications);
+
+        const response = await supertest(app).get('/api/users/notifications?includeRead=true');
+
+        expect(response.status).toBe(200);
+        expect(response.body).toEqual(mockNotifications);
+        expect(db.notificationRepo.getNotificationsForUser).toHaveBeenCalledWith(
+          'user-123',
+          20, // default limit
+          0, // default offset
+          true, // includeRead from query param
           expectLogger,
         );
       });

src/routes/user.routes.ts

@@ -4,57 +4,24 @@ import passport from './passport.routes';
 import multer from 'multer';
 import path from 'path';
 import fs from 'node:fs/promises';
-import * as bcrypt from 'bcrypt';
-import zxcvbn from 'zxcvbn';
+import * as bcrypt from 'bcrypt'; // This was a duplicate, fixed.
 import { z } from 'zod';
-import * as db from '../services/db/index.db';
 import { logger } from '../services/logger.server';
 import { UserProfile } from '../types';
 import { userService } from '../services/userService';
 import { ForeignKeyConstraintError } from '../services/db/errors.db';
 import { validateRequest } from '../middleware/validation.middleware';
+import { validatePasswordStrength } from '../utils/authUtils';
+import {
+  requiredString,
+  numericIdParam,
+  optionalNumeric,
+  optionalBoolean,
+} from '../utils/zodUtils';
+import * as db from '../services/db/index.db';
 
 const router = express.Router();
 
-/**
- * Validates the strength of a password using zxcvbn.
- * @param password The password to check.
- * @returns An object with `isValid` and an optional `feedback` message.
- */
-const validatePasswordStrength = (password: string): { isValid: boolean; feedback?: string } => {
-  const MIN_PASSWORD_SCORE = 3; // Require a 'Good' or 'Strong' password (score 3 or 4)
-  const strength = zxcvbn(password);
-
-  if (strength.score < MIN_PASSWORD_SCORE) {
-    const feedbackMessage =
-      strength.feedback.warning ||
-      (strength.feedback.suggestions && strength.feedback.suggestions[0]);
-    return {
-      isValid: false,
-      feedback:
-        `Password is too weak. ${feedbackMessage || 'Please choose a stronger password.'}`.trim(),
-    };
-  }
-
-  return { isValid: true };
-};
-
-// Helper for consistent required string validation (handles missing/null/empty)
-const requiredString = (message: string) =>
-  z.preprocess((val) => val ?? '', z.string().min(1, message));
-
-// --- Zod Schemas for User Routes (as per ADR-003) ---
-
-const numericIdParam = (key: string) =>
-  z.object({
-    params: z.object({
-      [key]: z.coerce
-        .number()
-        .int()
-        .positive(`Invalid ID for parameter '${key}'. Must be a number.`),
-    }),
-  });
-
 const updateProfileSchema = z.object({
   body: z
     .object({ full_name: z.string().optional(), avatar_url: z.string().url().optional() })
@@ -93,8 +60,9 @@ const createShoppingListSchema = z.object({
 // Apply the JWT authentication middleware to all routes in this file.
 const notificationQuerySchema = z.object({
   query: z.object({
-    limit: z.coerce.number().int().positive().optional().default(20),
-    offset: z.coerce.number().int().nonnegative().optional().default(0),
+    limit: optionalNumeric({ default: 20, integer: true, positive: true }),
+    offset: optionalNumeric({ default: 0, integer: true, nonnegative: true }),
+    includeRead: optionalBoolean({ default: false }),
   }),
 });
 
@@ -173,13 +141,12 @@ router.get(
     // Apply ADR-003 pattern for type safety
     try {
       const { query } = req as unknown as GetNotificationsRequest;
-      // Explicitly convert to numbers to ensure the repo receives correct types
-      const limit = query.limit ? Number(query.limit) : 20;
-      const offset = query.offset ? Number(query.offset) : 0;
+      const parsedQuery = notificationQuerySchema.parse({ query: req.query }).query;
       const notifications = await db.notificationRepo.getNotificationsForUser(
         userProfile.user.user_id,
-        limit,
-        offset,
+        parsedQuery.limit!,
+        parsedQuery.offset!,
+        parsedQuery.includeRead!,
         req.log,
       );
       res.json(notifications);

src/services/db/notification.db.test.ts

@@ -32,7 +32,7 @@ describe('Notification DB Service', () => {
   });
 
   describe('getNotificationsForUser', () => {
-    it('should execute the correct query with limit and offset and return notifications', async () => {
+    it('should only return unread notifications by default', async () => {
       const mockNotifications: Notification[] = [
         createMockNotification({
           notification_id: 1,
@@ -43,30 +43,59 @@ describe('Notification DB Service', () => {
       ];
       mockPoolInstance.query.mockResolvedValue({ rows: mockNotifications });
 
-      const result = await notificationRepo.getNotificationsForUser('user-123', 10, 5, mockLogger);
+      const result = await notificationRepo.getNotificationsForUser(
+        'user-123',
+        10,
+        5,
+        false,
+        mockLogger,
+      );
 
       expect(mockPoolInstance.query).toHaveBeenCalledWith(
-        expect.stringContaining('SELECT * FROM public.notifications'),
+        expect.stringContaining('is_read = false'),
         ['user-123', 10, 5],
       );
       expect(result).toEqual(mockNotifications);
     });
 
+    it('should return all notifications when includeRead is true', async () => {
+      const mockNotifications: Notification[] = [
+        createMockNotification({ is_read: true }),
+        createMockNotification({ is_read: false }),
+      ];
+      mockPoolInstance.query.mockResolvedValue({ rows: mockNotifications });
+
+      await notificationRepo.getNotificationsForUser('user-123', 10, 0, true, mockLogger);
+
+      // The query should NOT contain the is_read filter
+      expect(mockPoolInstance.query.mock.calls[0][0]).not.toContain('is_read = false');
+      expect(mockPoolInstance.query).toHaveBeenCalledWith(expect.any(String), ['user-123', 10, 0]);
+    });
+
     it('should return an empty array if the user has no notifications', async () => {
       mockPoolInstance.query.mockResolvedValue({ rows: [] });
-      const result = await notificationRepo.getNotificationsForUser('user-456', 10, 0, mockLogger);
+      const result = await notificationRepo.getNotificationsForUser(
+        'user-456',
+        10,
+        0,
+        false,
+        mockLogger,
+      );
       expect(result).toEqual([]);
-      expect(mockPoolInstance.query).toHaveBeenCalledWith(expect.any(String), ['user-456', 10, 0]);
+      expect(mockPoolInstance.query).toHaveBeenCalledWith(
+        expect.stringContaining('is_read = false'),
+        ['user-456', 10, 0],
+      );
     });
 
     it('should throw an error if the database query fails', async () => {
       const dbError = new Error('DB Error');
       mockPoolInstance.query.mockRejectedValue(dbError);
       await expect(
-        notificationRepo.getNotificationsForUser('user-123', 10, 5, mockLogger),
+        notificationRepo.getNotificationsForUser('user-123', 10, 5, false, mockLogger),
       ).rejects.toThrow('Failed to retrieve notifications.');
       expect(mockLogger.error).toHaveBeenCalledWith(
-        { err: dbError, userId: 'user-123', limit: 10, offset: 5 },
+        { err: dbError, userId: 'user-123', limit: 10, offset: 5, includeRead: false },
         'Database error in getNotificationsForUser',
       );
     });

src/services/db/notification.db.ts

@@ -95,20 +95,24 @@ export class NotificationRepository {
     userId: string,
     limit: number,
     offset: number,
+    includeRead: boolean,
     logger: Logger,
   ): Promise<Notification[]> {
     try {
-      const res = await this.db.query<Notification>(
-        `SELECT * FROM public.notifications 
-                 WHERE user_id = $1 
-                 ORDER BY created_at DESC 
-                 LIMIT $2 OFFSET $3`,
-        [userId, limit, offset],
-      );
+      const params: (string | number)[] = [userId, limit, offset];
+      let query = `SELECT * FROM public.notifications WHERE user_id = $1`;
+
+      if (!includeRead) {
+        query += ` AND is_read = false`;
+      }
+
+      query += ` ORDER BY created_at DESC LIMIT $2 OFFSET $3`;
+
+      const res = await this.db.query<Notification>(query, params);
       return res.rows;
     } catch (error) {
       logger.error(
-        { err: error, userId, limit, offset },
+        { err: error, userId, limit, offset, includeRead },
         'Database error in getNotificationsForUser',
       );
       throw new Error('Failed to retrieve notifications.');

src/services/db/price.db.ts

@@ -0,0 +1,53 @@
+// src/services/db/price.db.ts
+import type { Logger } from 'pino';
+import type { PriceHistoryData } from '../../types';
+import { getPool } from './connection.db';
+
+/**
+ * Repository for fetching price-related data.
+ */
+export const priceRepo = {
+  /**
+   * Fetches the historical price data for a given list of master item IDs.
+   * It retrieves the price in cents and the start date of the flyer for each item.
+   *
+   * @param masterItemIds An array of master grocery item IDs.
+   * @param logger The pino logger instance.
+   * @param limit The maximum number of records to return.
+   * @param offset The number of records to skip.
+   * @returns A promise that resolves to an array of price history data points.
+   */
+  async getPriceHistory(
+    masterItemIds: number[],
+    logger: Logger,
+    limit: number = 1000,
+    offset: number = 0,
+  ): Promise<PriceHistoryData[]> {
+    if (masterItemIds.length === 0) {
+      return [];
+    }
+
+    const query = `
+      SELECT
+        fi.master_item_id,
+        fi.price_in_cents,
+        f.valid_from AS date
+      FROM public.flyer_items fi
+      JOIN public.flyers f ON fi.flyer_id = f.flyer_id
+      WHERE
+        fi.master_item_id = ANY($1::int[])
+        AND f.valid_from IS NOT NULL
+        AND fi.price_in_cents IS NOT NULL
+      ORDER BY
+        fi.master_item_id, f.valid_from ASC
+      LIMIT $2 OFFSET $3;
+    `;
+
+    const result = await getPool().query(query, [masterItemIds, limit, offset]);
+    logger.debug(
+      { count: result.rows.length, itemIds: masterItemIds.length, limit, offset },
+      'Fetched price history from database.',
+    );
+    return result.rows;
+  },
+};

src/tests/e2e/admin-dashboard.e2e.test.ts

@@ -0,0 +1,96 @@
+// src/tests/e2e/admin-dashboard.e2e.test.ts
+import { describe, it, expect, afterAll } from 'vitest';
+import supertest from 'supertest';
+import app from '../../../server';
+import { getPool } from '../../services/db/connection.db';
+
+/**
+ * @vitest-environment node
+ */
+
+const request = supertest(app);
+
+describe('E2E Admin Dashboard Flow', () => {
+  // Use a unique email for every run to avoid collisions
+  const uniqueId = Date.now();
+  const adminEmail = `e2e-admin-${uniqueId}@example.com`;
+  const adminPassword = 'StrongPassword123!';
+
+  let authToken: string;
+  let adminUserId: string | null = null;
+
+  afterAll(async () => {
+    // Safety cleanup: Ensure the user is deleted from the DB if the test fails mid-way.
+    if (adminUserId) {
+      try {
+        await getPool().query('DELETE FROM public.users WHERE user_id = $1', [adminUserId]);
+      } catch (err) {
+        console.error('Error cleaning up E2E admin user:', err);
+      }
+    }
+  });
+
+  it('should allow an admin to log in and access dashboard features', async () => {
+    // 1. Register a new user (initially a regular user)
+    const registerResponse = await request.post('/api/auth/register').send({
+      email: adminEmail,
+      password: adminPassword,
+      full_name: 'E2E Admin User',
+    });
+
+    expect(registerResponse.status).toBe(201);
+    const registeredUser = registerResponse.body.userprofile.user;
+    adminUserId = registeredUser.user_id;
+    expect(adminUserId).toBeDefined();
+
+    // 2. Promote the user to 'admin' via direct DB access
+    // (This simulates an existing admin or a manual promotion, as there is no public "register as admin" endpoint)
+    await getPool().query(`UPDATE public.profiles SET role = 'admin' WHERE user_id = $1`, [
+      adminUserId,
+    ]);
+
+    // 3. Login to get the access token (now with admin privileges)
+    const loginResponse = await request.post('/api/auth/login').send({
+      email: adminEmail,
+      password: adminPassword,
+    });
+
+    expect(loginResponse.status).toBe(200);
+    authToken = loginResponse.body.token;
+    expect(authToken).toBeDefined();
+    // Verify the role returned in the login response is now 'admin'
+    expect(loginResponse.body.userprofile.role).toBe('admin');
+
+    // 4. Fetch System Stats (Protected Admin Route)
+    const statsResponse = await request
+      .get('/api/admin/stats')
+      .set('Authorization', `Bearer ${authToken}`);
+
+    expect(statsResponse.status).toBe(200);
+    expect(statsResponse.body).toHaveProperty('userCount');
+    expect(statsResponse.body).toHaveProperty('flyerCount');
+
+    // 5. Fetch User List (Protected Admin Route)
+    const usersResponse = await request
+      .get('/api/admin/users')
+      .set('Authorization', `Bearer ${authToken}`);
+
+    expect(usersResponse.status).toBe(200);
+    expect(Array.isArray(usersResponse.body)).toBe(true);
+    // The list should contain the admin user we just created
+    const self = usersResponse.body.find((u: any) => u.user_id === adminUserId);
+    expect(self).toBeDefined();
+
+    // 6. Check Queue Status (Protected Admin Route)
+    const queueResponse = await request
+      .get('/api/admin/queues/status')
+      .set('Authorization', `Bearer ${authToken}`);
+
+    expect(queueResponse.status).toBe(200);
+    expect(Array.isArray(queueResponse.body)).toBe(true);
+    // Verify that the 'flyer-processing' queue is present in the status report
+    const flyerQueue = queueResponse.body.find((q: any) => q.name === 'flyer-processing');
+    expect(flyerQueue).toBeDefined();
+    expect(flyerQueue.counts).toBeDefined();
+  });
+});

src/tests/e2e/flyer-upload.e2e.test.ts

@@ -0,0 +1,110 @@
+// src/tests/e2e/flyer-upload.e2e.test.ts
+import { describe, it, expect, afterAll } from 'vitest';
+import supertest from 'supertest';
+import app from '../../../server';
+import { getPool } from '../../services/db/connection.db';
+import crypto from 'crypto';
+import path from 'path';
+import fs from 'fs';
+
+/**
+ * @vitest-environment node
+ */
+
+const request = supertest(app);
+
+describe('E2E Flyer Upload and Processing Workflow', () => {
+  const uniqueId = Date.now();
+  const userEmail = `e2e-uploader-${uniqueId}@example.com`;
+  const userPassword = 'StrongPassword123!';
+  
+  let authToken: string;
+  let userId: string | null = null;
+  let flyerId: number | null = null;
+
+  afterAll(async () => {
+    // Cleanup: Delete the flyer and user created during the test
+    const pool = getPool();
+    if (flyerId) {
+      await pool.query('DELETE FROM public.flyers WHERE flyer_id = $1', [flyerId]);
+    }
+    if (userId) {
+      await pool.query('DELETE FROM public.users WHERE user_id = $1', [userId]);
+    }
+  });
+
+  it('should allow a user to upload a flyer and wait for processing to complete', async () => {
+    // 1. Register a new user
+    const registerResponse = await request.post('/api/auth/register').send({
+      email: userEmail,
+      password: userPassword,
+      full_name: 'E2E Flyer Uploader',
+    });
+    expect(registerResponse.status).toBe(201);
+    
+    // 2. Login to get the access token
+    const loginResponse = await request.post('/api/auth/login').send({
+      email: userEmail,
+      password: userPassword,
+    });
+    expect(loginResponse.status).toBe(200);
+    authToken = loginResponse.body.token;
+    userId = loginResponse.body.userprofile.user.user_id;
+    expect(authToken).toBeDefined();
+
+    // 3. Prepare the flyer file
+    // We try to use the existing test asset if available, otherwise create a dummy buffer.
+    // Note: In a real E2E scenario against a live AI service, a valid image is required.
+    // If the AI service is mocked or stubbed in this environment, a dummy buffer might suffice.
+    let fileBuffer: Buffer;
+    let fileName = `e2e-test-flyer-${uniqueId}.jpg`;
+    
+    const assetPath = path.resolve(__dirname, '../assets/test-flyer-image.jpg');
+    if (fs.existsSync(assetPath)) {
+      const rawBuffer = fs.readFileSync(assetPath);
+      // Append unique ID to ensure unique checksum for every test run
+      fileBuffer = Buffer.concat([rawBuffer, Buffer.from(uniqueId.toString())]);
+    } else {
+      // Fallback to a minimal valid JPEG header + random data if asset is missing
+      // (This might fail if the backend does strict image validation/processing)
+      fileBuffer = Buffer.concat([
+        Buffer.from([0xff, 0xd8, 0xff, 0xe0]), // JPEG Start of Image
+        Buffer.from(uniqueId.toString())
+      ]);
+    }
+
+    // Calculate checksum (required by the API)
+    const checksum = crypto.createHash('sha256').update(fileBuffer).digest('hex');
+
+    // 4. Upload the flyer
+    const uploadResponse = await request
+      .post('/api/ai/upload-and-process')
+      .set('Authorization', `Bearer ${authToken}`)
+      .field('checksum', checksum)
+      .attach('flyerFile', fileBuffer, fileName);
+
+    expect(uploadResponse.status).toBe(202);
+    const jobId = uploadResponse.body.jobId;
+    expect(jobId).toBeDefined();
+
+    // 5. Poll for job completion
+    let jobStatus;
+    const maxRetries = 30; // Poll for up to 90 seconds
+    for (let i = 0; i < maxRetries; i++) {
+      await new Promise((resolve) => setTimeout(resolve, 3000)); // Wait 3s
+      
+      const statusResponse = await request
+        .get(`/api/ai/jobs/${jobId}/status`)
+        .set('Authorization', `Bearer ${authToken}`);
+      
+      jobStatus = statusResponse.body;
+      if (jobStatus.state === 'completed' || jobStatus.state === 'failed') {
+        break;
+      }
+    }
+
+    expect(jobStatus.state).toBe('completed');
+    flyerId = jobStatus.returnValue?.flyerId;
+    expect(flyerId).toBeTypeOf('number');
+  }, 120000); // Extended timeout for AI processing
+});

src/tests/e2e/user-journey.e2e.test.ts

@@ -0,0 +1,111 @@
+// src/tests/e2e/user-journey.e2e.test.ts
+import { describe, it, expect, afterAll } from 'vitest';
+import supertest from 'supertest';
+import app from '../../../server';
+import { getPool } from '../../services/db/connection.db';
+
+/**
+ * @vitest-environment node
+ */
+
+const request = supertest(app);
+
+describe('E2E User Journey', () => {
+  // Use a unique email for every run to avoid collisions
+  const uniqueId = Date.now();
+  const userEmail = `e2e-test-${uniqueId}@example.com`;
+  const userPassword = 'StrongPassword123!';
+  
+  let authToken: string;
+  let userId: string | null = null;
+  let shoppingListId: number;
+
+  afterAll(async () => {
+    // Safety cleanup: Ensure the user is deleted from the DB if the test fails mid-way.
+    // If the test succeeds, the user deletes their own account, so this acts as a fallback.
+    if (userId) {
+      try {
+        await getPool().query('DELETE FROM public.users WHERE user_id = $1', [userId]);
+      } catch (err) {
+        console.error('Error cleaning up E2E test user:', err);
+      }
+    }
+  });
+
+  it('should complete a full user lifecycle: Register -> Login -> Manage List -> Delete Account', async () => {
+    // 1. Register a new user
+    const registerResponse = await request.post('/api/auth/register').send({
+      email: userEmail,
+      password: userPassword,
+      full_name: 'E2E Traveler',
+    });
+
+    expect(registerResponse.status).toBe(201);
+    expect(registerResponse.body.message).toBe('User registered successfully!');
+    
+    // 2. Login to get the access token
+    const loginResponse = await request.post('/api/auth/login').send({
+      email: userEmail,
+      password: userPassword,
+    });
+
+    expect(loginResponse.status).toBe(200);
+    authToken = loginResponse.body.token;
+    userId = loginResponse.body.userprofile.user.user_id;
+    
+    expect(authToken).toBeDefined();
+    expect(userId).toBeDefined();
+
+    // 3. Create a Shopping List
+    const createListResponse = await request
+      .post('/api/users/shopping-lists')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ name: 'E2E Party List' });
+
+    expect(createListResponse.status).toBe(201);
+    shoppingListId = createListResponse.body.shopping_list_id;
+    expect(shoppingListId).toBeDefined();
+
+    // 4. Add an item to the list
+    const addItemResponse = await request
+      .post(`/api/users/shopping-lists/${shoppingListId}/items`)
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ customItemName: 'Chips' });
+
+    expect(addItemResponse.status).toBe(201);
+    expect(addItemResponse.body.custom_item_name).toBe('Chips');
+
+    // 5. Verify the list and item exist via GET
+    const getListsResponse = await request
+      .get('/api/users/shopping-lists')
+      .set('Authorization', `Bearer ${authToken}`);
+
+    expect(getListsResponse.status).toBe(200);
+    const myLists = getListsResponse.body;
+    const targetList = myLists.find((l: any) => l.shopping_list_id === shoppingListId);
+    
+    expect(targetList).toBeDefined();
+    expect(targetList.items).toHaveLength(1);
+    expect(targetList.items[0].custom_item_name).toBe('Chips');
+
+    // 6. Delete the User Account (Self-Service)
+    const deleteAccountResponse = await request
+      .delete('/api/users/account')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ password: userPassword });
+
+    expect(deleteAccountResponse.status).toBe(200);
+    expect(deleteAccountResponse.body.message).toBe('Account deleted successfully.');
+
+    // 7. Verify Login is no longer possible
+    const failLoginResponse = await request.post('/api/auth/login').send({
+      email: userEmail,
+      password: userPassword,
+    });
+
+    expect(failLoginResponse.status).toBe(401);
+    
+    // Mark userId as null so afterAll doesn't attempt to delete it again
+    userId = null;
+  });
+});

src/tests/integration/admin.integration.test.ts

@@ -1,10 +1,16 @@
 // src/tests/integration/admin.integration.test.ts
 import { describe, it, expect, beforeAll, beforeEach, afterAll } from 'vitest';
-import * as apiClient from '../../services/apiClient';
+import supertest from 'supertest';
+import app from '../../../server';
 import { getPool } from '../../services/db/connection.db';
 import type { UserProfile } from '../../types';
 import { createAndLoginUser } from '../utils/testHelpers';
 
+/**
+ * @vitest-environment node
+ */
+const request = supertest(app);
+
 describe('Admin API Routes Integration Tests', () => {
   let adminToken: string;
   let adminUser: UserProfile;
@@ -42,8 +48,10 @@ describe('Admin API Routes Integration Tests', () => {
 
   describe('GET /api/admin/stats', () => {
     it('should allow an admin to fetch application stats', async () => {
-      const response = await apiClient.getApplicationStats(adminToken);
-      const stats = await response.json();
+      const response = await request
+        .get('/api/admin/stats')
+        .set('Authorization', `Bearer ${adminToken}`);
+      const stats = response.body;
       expect(stats).toBeDefined();
       expect(stats).toHaveProperty('flyerCount');
       expect(stats).toHaveProperty('userCount');
@@ -51,18 +59,21 @@ describe('Admin API Routes Integration Tests', () => {
     });
 
     it('should forbid a regular user from fetching application stats', async () => {
-      const response = await apiClient.getApplicationStats(regularUserToken);
-      expect(response.ok).toBe(false);
+      const response = await request
+        .get('/api/admin/stats')
+        .set('Authorization', `Bearer ${regularUserToken}`);
       expect(response.status).toBe(403);
-      const errorData = await response.json();
+      const errorData = response.body;
       expect(errorData.message).toBe('Forbidden: Administrator access required.');
     });
   });
 
   describe('GET /api/admin/stats/daily', () => {
     it('should allow an admin to fetch daily stats', async () => {
-      const response = await apiClient.getDailyStats(adminToken);
-      const dailyStats = await response.json();
+      const response = await request
+        .get('/api/admin/stats/daily')
+        .set('Authorization', `Bearer ${adminToken}`);
+      const dailyStats = response.body;
       expect(dailyStats).toBeDefined();
       expect(Array.isArray(dailyStats)).toBe(true);
       // We just created users in beforeAll, so we should have data
@@ -73,10 +84,11 @@ describe('Admin API Routes Integration Tests', () => {
     });
 
     it('should forbid a regular user from fetching daily stats', async () => {
-      const response = await apiClient.getDailyStats(regularUserToken);
-      expect(response.ok).toBe(false);
+      const response = await request
+        .get('/api/admin/stats/daily')
+        .set('Authorization', `Bearer ${regularUserToken}`);
       expect(response.status).toBe(403);
-      const errorData = await response.json();
+      const errorData = response.body;
       expect(errorData.message).toBe('Forbidden: Administrator access required.');
     });
   });
@@ -85,25 +97,30 @@ describe('Admin API Routes Integration Tests', () => {
     it('should allow an admin to fetch suggested corrections', async () => {
       // This test just verifies access and correct response shape.
       // More detailed tests would require seeding corrections.
-      const response = await apiClient.getSuggestedCorrections(adminToken);
-      const corrections = await response.json();
+      const response = await request
+        .get('/api/admin/corrections')
+        .set('Authorization', `Bearer ${adminToken}`);
+      const corrections = response.body;
       expect(corrections).toBeDefined();
       expect(Array.isArray(corrections)).toBe(true);
     });
 
     it('should forbid a regular user from fetching suggested corrections', async () => {
-      const response = await apiClient.getSuggestedCorrections(regularUserToken);
-      expect(response.ok).toBe(false);
+      const response = await request
+        .get('/api/admin/corrections')
+        .set('Authorization', `Bearer ${regularUserToken}`);
       expect(response.status).toBe(403);
-      const errorData = await response.json();
+      const errorData = response.body;
       expect(errorData.message).toBe('Forbidden: Administrator access required.');
     });
   });
 
   describe('GET /api/admin/brands', () => {
     it('should allow an admin to fetch all brands', async () => {
-      const response = await apiClient.fetchAllBrands(adminToken);
-      const brands = await response.json();
+      const response = await request
+        .get('/api/admin/brands')
+        .set('Authorization', `Bearer ${adminToken}`);
+      const brands = response.body;
       expect(brands).toBeDefined();
       expect(Array.isArray(brands)).toBe(true);
       // Even if no brands exist, it should return an array.
@@ -112,10 +129,11 @@ describe('Admin API Routes Integration Tests', () => {
     });
 
     it('should forbid a regular user from fetching all brands', async () => {
-      const response = await apiClient.fetchAllBrands(regularUserToken);
-      expect(response.ok).toBe(false);
+      const response = await request
+        .get('/api/admin/brands')
+        .set('Authorization', `Bearer ${regularUserToken}`);
       expect(response.status).toBe(403);
-      const errorData = await response.json();
+      const errorData = response.body;
       expect(errorData.message).toBe('Forbidden: Administrator access required.');
     });
   });
@@ -170,8 +188,10 @@ describe('Admin API Routes Integration Tests', () => {
 
     it('should allow an admin to approve a correction', async () => {
       // Act: Approve the correction.
-      const response = await apiClient.approveCorrection(testCorrectionId, adminToken);
-      expect(response.ok).toBe(true);
+      const response = await request
+        .post(`/api/admin/corrections/${testCorrectionId}/approve`)
+        .set('Authorization', `Bearer ${adminToken}`);
+      expect(response.status).toBe(200);
 
       // Assert: Verify the flyer item's price was updated and the correction status changed.
       const { rows: itemRows } = await getPool().query(
@@ -189,8 +209,10 @@ describe('Admin API Routes Integration Tests', () => {
 
     it('should allow an admin to reject a correction', async () => {
       // Act: Reject the correction.
-      const response = await apiClient.rejectCorrection(testCorrectionId, adminToken);
-      expect(response.ok).toBe(true);
+      const response = await request
+        .post(`/api/admin/corrections/${testCorrectionId}/reject`)
+        .set('Authorization', `Bearer ${adminToken}`);
+      expect(response.status).toBe(200);
 
       // Assert: Verify the correction status changed.
       const { rows: correctionRows } = await getPool().query(
@@ -202,12 +224,11 @@ 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 apiClient.updateSuggestedCorrection(
-        testCorrectionId,
-        '300',
-        adminToken,
-      );
-      const updatedCorrection = await response.json();
+      const response = await request
+        .put(`/api/admin/corrections/${testCorrectionId}`)
+        .set('Authorization', `Bearer ${adminToken}`)
+        .send({ suggested_value: '300' });
+      const updatedCorrection = response.body;
 
       // Assert: Verify the API response and the database state.
       expect(updatedCorrection.suggested_value).toBe('300');
@@ -227,8 +248,11 @@ describe('Admin API Routes Integration Tests', () => {
       const recipeId = recipeRes.rows[0].recipe_id;
 
       // Act: Update the status to 'public'.
-      const response = await apiClient.updateRecipeStatus(recipeId, 'public', adminToken);
-      expect(response.ok).toBe(true);
+      const response = await request
+        .put(`/api/admin/recipes/${recipeId}/status`)
+        .set('Authorization', `Bearer ${adminToken}`)
+        .send({ status: 'public' });
+      expect(response.status).toBe(200);
 
       // Assert: Verify the status was updated in the database.
       const { rows: updatedRecipeRows } = await getPool().query(

src/tests/integration/ai.integration.test.ts

@@ -1,6 +1,7 @@
 // src/tests/integration/ai.integration.test.ts
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import * as aiApiClient from '../../services/aiApiClient';
+import supertest from 'supertest';
+import app from '../../../server';
 import fs from 'node:fs/promises';
 import path from 'path';
 import { createAndLoginUser } from '../utils/testHelpers';
@@ -9,6 +10,8 @@ import { createAndLoginUser } from '../utils/testHelpers';
  * @vitest-environment node
  */
 
+const request = supertest(app);
+
 interface TestGeolocationCoordinates {
   latitude: number;
   longitude: number;
@@ -44,46 +47,63 @@ describe('AI API Routes Integration Tests', () => {
   });
 
   it('POST /api/ai/check-flyer should return a boolean', async () => {
-    const mockImageFile = new File(['content'], 'test.jpg', { type: 'image/jpeg' });
-    const response = await aiApiClient.isImageAFlyer(mockImageFile, authToken);
-    const result = await response.json();
+    const response = await request
+      .post('/api/ai/check-flyer')
+      .set('Authorization', `Bearer ${authToken}`)
+      .attach('image', Buffer.from('content'), 'test.jpg');
+    const result = response.body;
+    expect(response.status).toBe(200);
     // The backend is stubbed to always return true for this check
     expect(result.is_flyer).toBe(true);
   });
 
   it('POST /api/ai/extract-address should return a stubbed address', async () => {
-    const mockImageFile = new File(['content'], 'test.jpg', { type: 'image/jpeg' });
-    const response = await aiApiClient.extractAddressFromImage(mockImageFile, authToken);
-    const result = await response.json();
+    const response = await request
+      .post('/api/ai/extract-address')
+      .set('Authorization', `Bearer ${authToken}`)
+      .attach('image', Buffer.from('content'), 'test.jpg');
+    const result = response.body;
+    expect(response.status).toBe(200);
     expect(result.address).toBe('not identified');
   });
 
   it('POST /api/ai/extract-logo should return a stubbed response', async () => {
-    const mockImageFile = new File(['content'], 'test.jpg', { type: 'image/jpeg' });
-    const response = await aiApiClient.extractLogoFromImage([mockImageFile], authToken);
-    const result = await response.json();
+    const response = await request
+      .post('/api/ai/extract-logo')
+      .set('Authorization', `Bearer ${authToken}`)
+      .attach('images', Buffer.from('content'), 'test.jpg');
+    const result = response.body;
+    expect(response.status).toBe(200);
     expect(result).toEqual({ store_logo_base_64: null });
   });
 
   it('POST /api/ai/quick-insights should return a stubbed insight', async () => {
-    const response = await aiApiClient.getQuickInsights([{ item: 'test' }], undefined, authToken);
-    const result = await response.json();
+    const response = await request
+      .post('/api/ai/quick-insights')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ items: [{ item: 'test' }] });
+    const result = response.body;
+    expect(response.status).toBe(200);
     expect(result.text).toBe('This is a server-generated quick insight: buy the cheap stuff!');
   });
 
   it('POST /api/ai/deep-dive should return a stubbed analysis', async () => {
-    const response = await aiApiClient.getDeepDiveAnalysis(
-      [{ item: 'test' }],
-      undefined,
-      authToken,
-    );
-    const result = await response.json();
+    const response = await request
+      .post('/api/ai/deep-dive')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ items: [{ item: 'test' }] });
+    const result = response.body;
+    expect(response.status).toBe(200);
     expect(result.text).toBe('This is a server-generated deep dive analysis. It is very detailed.');
   });
 
   it('POST /api/ai/search-web should return a stubbed search result', async () => {
-    const response = await aiApiClient.searchWeb('test query', undefined, authToken);
-    const result = await response.json();
+    const response = await request
+      .post('/api/ai/search-web')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ query: 'test query' });
+    const result = response.body;
+    expect(response.status).toBe(200);
     expect(result).toEqual({ text: 'The web says this is good.', sources: [] });
   });
 
@@ -116,36 +136,32 @@ describe('AI API Routes Integration Tests', () => {
       created_at: new Date().toISOString(),
       updated_at: new Date().toISOString(),
     };
-    const response = await aiApiClient.planTripWithMaps(
-      [],
-      mockStore,
-      mockLocation,
-      undefined,
-      authToken,
-    );
+    const response = await request
+      .post('/api/ai/plan-trip')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ items: [], store: mockStore, userLocation: mockLocation });
     // The service for this endpoint is disabled and throws an error, which results in a 500.
-    expect(response.ok).toBe(false);
     expect(response.status).toBe(500);
-    const errorResult = await response.json();
+    const errorResult = response.body;
     expect(errorResult.message).toContain('planTripWithMaps');
   });
 
   it('POST /api/ai/generate-image should reject because it is not implemented', async () => {
     // The backend for this is not stubbed and will throw an error.
     // This test confirms that the endpoint is protected and responds as expected to a failure.
-    const response = await aiApiClient.generateImageFromText('a test prompt', undefined, authToken);
-    expect(response.ok).toBe(false);
+    const response = await request
+      .post('/api/ai/generate-image')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ prompt: 'a test prompt' });
     expect(response.status).toBe(501);
   });
 
   it('POST /api/ai/generate-speech should reject because it is not implemented', async () => {
     // The backend for this is not stubbed and will throw an error.
-    const response = await aiApiClient.generateSpeechFromText(
-      'a test prompt',
-      undefined,
-      authToken,
-    );
-    expect(response.ok).toBe(false);
+    const response = await request
+      .post('/api/ai/generate-speech')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ text: 'a test prompt' });
     expect(response.status).toBe(501);
   });
 });

src/tests/integration/auth.integration.test.ts

@@ -1,6 +1,7 @@
 // src/tests/integration/auth.integration.test.ts
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { loginUser } from '../../services/apiClient';
+import supertest from 'supertest';
+import app from '../../../server';
 import { getPool } from '../../services/db/connection.db';
 import { createAndLoginUser, TEST_PASSWORD } from '../utils/testHelpers';
 import type { UserProfile } from '../../types';
@@ -9,6 +10,8 @@ import type { UserProfile } from '../../types';
  * @vitest-environment node
  */
 
+const request = supertest(app);
+
 /**
  * These are integration tests that verify the authentication flow against a running backend server.
  * Make sure your Express server is running before executing these tests.
@@ -16,30 +19,6 @@ import type { UserProfile } from '../../types';
  * To run only these tests: `vitest run src/tests/auth.integration.test.ts`
  */
 describe('Authentication API Integration', () => {
-  // --- START DEBUG LOGGING ---
-  // Query the DB from within the test file to see its state.
-  getPool()
-    .query(
-      'SELECT u.user_id, u.email, p.role FROM public.users u JOIN public.profiles p ON u.user_id = p.user_id',
-    )
-    .then((res) => {
-      console.log('\n--- [auth.integration.test.ts] Users found in DB from TEST perspective: ---');
-      console.table(res.rows);
-      console.log('--------------------------------------------------------------------------\n');
-    })
-    .catch((err) => console.error('--- [auth.integration.test.ts] DB QUERY FAILED ---', err));
-  // --- END DEBUG LOGGING ---
-
-  // --- START DEBUG LOGGING ---
-  // Log the database connection details as seen by an individual TEST FILE.
-  console.log('\n\n--- [AUTH.INTEGRATION.TEST LOG] DATABASE CONNECTION ---');
-  console.log(`  Host: ${process.env.DB_HOST}`);
-  console.log(`  Port: ${process.env.DB_PORT}`);
-  console.log(`  User: ${process.env.DB_USER}`);
-  console.log(`  Database: ${process.env.DB_NAME}`);
-  console.log('-----------------------------------------------------\n');
-  // --- END DEBUG LOGGING ---
-
   let testUserEmail: string;
   let testUser: UserProfile;
 
@@ -57,11 +36,14 @@ describe('Authentication API Integration', () => {
   // This test migrates the logic from the old DevTestRunner.tsx component.
   it('should successfully log in a registered user', async () => {
     // The `rememberMe` parameter is required. For a test, `false` is a safe default.
-    const response = await loginUser(testUserEmail, TEST_PASSWORD, false);
-    const data = await response.json();
+    const response = await request
+      .post('/api/auth/login')
+      .send({ email: testUserEmail, password: TEST_PASSWORD, rememberMe: false });
+    const data = response.body;
 
     // Assert that the API returns the expected structure
     expect(data).toBeDefined();
+    expect(response.status).toBe(200);
     expect(data.userprofile).toBeDefined();
     expect(data.userprofile.user.email).toBe(testUserEmail);
     expect(data.userprofile.user.user_id).toBeTypeOf('string');
@@ -74,9 +56,11 @@ describe('Authentication API Integration', () => {
     const wrongPassword = 'wrongpassword';
 
     // The loginUser function returns a Response object. We check its status.
-    const response = await loginUser(adminEmail, wrongPassword, false);
-    expect(response.ok).toBe(false);
-    const errorData = await response.json();
+    const response = await request
+      .post('/api/auth/login')
+      .send({ email: adminEmail, password: wrongPassword, rememberMe: false });
+    expect(response.status).toBe(401);
+    const errorData = response.body;
     expect(errorData.message).toBe('Incorrect email or password.');
   });
 
@@ -85,9 +69,11 @@ describe('Authentication API Integration', () => {
     const anyPassword = 'any-password';
 
     // The loginUser function returns a Response object. We check its status.
-    const response = await loginUser(nonExistentEmail, anyPassword, false);
-    expect(response.ok).toBe(false);
-    const errorData = await response.json();
+    const response = await request
+      .post('/api/auth/login')
+      .send({ email: nonExistentEmail, password: anyPassword, rememberMe: false });
+    expect(response.status).toBe(401);
+    const errorData = response.body;
     // Security best practice: the error message should be identical for wrong password and wrong email
     // to prevent user enumeration attacks.
     expect(errorData.message).toBe('Incorrect email or password.');
@@ -96,24 +82,21 @@ describe('Authentication API Integration', () => {
   it('should successfully refresh an access token using a refresh token cookie', async () => {
     // Arrange: Log in to get a fresh, valid refresh token cookie for this specific test.
     // This ensures the test is self-contained and not affected by other tests.
-    const loginResponse = await loginUser(testUserEmail, TEST_PASSWORD, true);
-    const setCookieHeader = loginResponse.headers.get('set-cookie');
-    const refreshTokenCookie = setCookieHeader?.split(';')[0];
+    const loginResponse = await request
+      .post('/api/auth/login')
+      .send({ email: testUserEmail, password: TEST_PASSWORD, rememberMe: true });
+    const refreshTokenCookie = loginResponse.headers['set-cookie'][0].split(';')[0];
 
     expect(refreshTokenCookie).toBeDefined();
 
     // Act: Make a request to the refresh-token endpoint, including the cookie.
-    const apiUrl = process.env.VITE_API_BASE_URL || 'http://localhost:3001/api';
-    const response = await fetch(`${apiUrl}/auth/refresh-token`, {
-      method: 'POST',
-      headers: {
-        Cookie: refreshTokenCookie!,
-      },
-    });
+    const response = await request
+      .post('/api/auth/refresh-token')
+      .set('Cookie', refreshTokenCookie!);
 
     // Assert: Check for a successful response and a new access token.
-    expect(response.ok).toBe(true);
-    const data = await response.json();
+    expect(response.status).toBe(200);
+    const data = response.body;
     expect(data.token).toBeTypeOf('string');
   });
 
@@ -122,40 +105,30 @@ describe('Authentication API Integration', () => {
     const invalidRefreshTokenCookie = 'refreshToken=this-is-not-a-valid-token';
 
     // Act: Make a request to the refresh-token endpoint with the invalid cookie.
-    const apiUrl = process.env.VITE_API_BASE_URL || 'http://localhost:3001/api';
-    const response = await fetch(`${apiUrl}/auth/refresh-token`, {
-      method: 'POST',
-      headers: {
-        Cookie: invalidRefreshTokenCookie,
-      },
-    });
+    const response = await request
+      .post('/api/auth/refresh-token')
+      .set('Cookie', invalidRefreshTokenCookie);
 
     // Assert: Check for a 403 Forbidden response.
-    expect(response.ok).toBe(false);
     expect(response.status).toBe(403);
-    const data = await response.json();
+    const data = response.body;
     expect(data.message).toBe('Invalid or expired refresh token.');
   });
 
   it('should successfully log out and clear the refresh token cookie', async () => {
     // Arrange: Log in to get a valid refresh token cookie.
-    const loginResponse = await loginUser(testUserEmail, TEST_PASSWORD, true);
-    const setCookieHeader = loginResponse.headers.get('set-cookie');
-    const refreshTokenCookie = setCookieHeader?.split(';')[0];
+    const loginResponse = await request
+      .post('/api/auth/login')
+      .send({ email: testUserEmail, password: TEST_PASSWORD, rememberMe: true });
+    const refreshTokenCookie = loginResponse.headers['set-cookie'][0].split(';')[0];
     expect(refreshTokenCookie).toBeDefined();
 
     // Act: Make a request to the new logout endpoint, including the cookie.
-    const apiUrl = process.env.VITE_API_BASE_URL || 'http://localhost:3001/api';
-    const response = await fetch(`${apiUrl}/auth/logout`, {
-      method: 'POST',
-      headers: {
-        Cookie: refreshTokenCookie!,
-      },
-    });
+    const response = await request.post('/api/auth/logout').set('Cookie', refreshTokenCookie!);
 
     // Assert: Check for a successful response and a cookie-clearing header.
-    expect(response.ok).toBe(true);
-    const logoutSetCookieHeader = response.headers.get('set-cookie');
+    expect(response.status).toBe(200);
+    const logoutSetCookieHeader = response.headers['set-cookie'][0];
     expect(logoutSetCookieHeader).toContain('refreshToken=;');
     expect(logoutSetCookieHeader).toContain('Max-Age=0');
   });

src/tests/integration/flyer-processing.integration.test.ts

@@ -1,8 +1,9 @@
 // src/tests/integration/flyer-processing.integration.test.ts
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import supertest from 'supertest';
+import app from '../../../server';
 import fs from 'node:fs/promises';
 import path from 'path';
-import * as aiApiClient from '../../services/aiApiClient';
 import * as db from '../../services/db/index.db';
 import { getPool } from '../../services/db/connection.db';
 import { generateFileChecksum } from '../../utils/checksum';
@@ -14,6 +15,8 @@ import { createAndLoginUser } from '../utils/testHelpers';
  * @vitest-environment node
  */
 
+const request = supertest(app);
+
 describe('Flyer Processing Background Job Integration Test', () => {
   const createdUserIds: string[] = [];
   const createdFlyerIds: number[] = [];
@@ -68,19 +71,30 @@ describe('Flyer Processing Background Job Integration Test', () => {
     const checksum = await generateFileChecksum(mockImageFile);
 
     // Act 1: Upload the file to start the background job.
-    const uploadResponse = await aiApiClient.uploadAndProcessFlyer(mockImageFile, checksum, token);
-    const { jobId } = await uploadResponse.json();
+    const uploadReq = request
+      .post('/api/ai/upload-and-process')
+      .field('checksum', checksum)
+      .attach('flyerFile', uniqueContent, uniqueFileName);
+    if (token) {
+      uploadReq.set('Authorization', `Bearer ${token}`);
+    }
+    const uploadResponse = await uploadReq;
+    const { jobId } = uploadResponse.body;
 
     // Assert 1: Check that a job ID was returned.
     expect(jobId).toBeTypeOf('string');
 
     // Act 2: Poll for the job status until it completes.
     let jobStatus;
-    const maxRetries = 20; // Poll for up to 60 seconds (20 * 3s)
+    const maxRetries = 30; // Poll for up to 90 seconds (30 * 3s)
     for (let i = 0; i < maxRetries; i++) {
       await new Promise((resolve) => setTimeout(resolve, 3000)); // Wait 3 seconds between polls
-      const statusResponse = await aiApiClient.getJobStatus(jobId, token);
-      jobStatus = await statusResponse.json();
+      const statusReq = request.get(`/api/ai/jobs/${jobId}/status`);
+      if (token) {
+        statusReq.set('Authorization', `Bearer ${token}`);
+      }
+      const statusResponse = await statusReq;
+      jobStatus = statusResponse.body;
       if (jobStatus.state === 'completed' || jobStatus.state === 'failed') {
         break;
       }

src/tests/integration/flyer.integration.test.ts

@@ -1,7 +1,8 @@
 // src/tests/integration/flyer.integration.test.ts
 import { describe, it, expect, beforeAll } from 'vitest';
-import * as apiClient from '../../services/apiClient';
+import supertest from 'supertest';
 import { getPool } from '../../services/db/connection.db';
+import app from '../../../server';
 import type { Flyer, FlyerItem } from '../../types';
 
 /**
@@ -10,6 +11,8 @@ import type { Flyer, FlyerItem } from '../../types';
 
 describe('Public Flyer API Routes Integration Tests', () => {
   let flyers: Flyer[] = [];
+  // Use a supertest instance for all requests in this file
+  const request = supertest(app);
   let createdFlyerId: number;
 
   // Fetch flyers once before all tests in this suite to use in subsequent tests.
@@ -34,18 +37,16 @@ describe('Public Flyer API Routes Integration Tests', () => {
       [createdFlyerId],
     );
 
-    const response = await apiClient.fetchFlyers();
-    flyers = await response.json();
+    const response = await request.get('/api/flyers');
+    flyers = response.body;
   });
 
   describe('GET /api/flyers', () => {
     it('should return a list of flyers', async () => {
       // Act: Call the API endpoint using the client function.
-      const response = await apiClient.fetchFlyers();
-      const flyers: Flyer[] = await response.json();
-
-      // Assert: Verify the response is successful and contains the expected data structure.
-      expect(response.ok).toBe(true);
+      const response = await request.get('/api/flyers');
+      const flyers: Flyer[] = response.body;
+      expect(response.status).toBe(200);
       expect(flyers).toBeInstanceOf(Array);
 
       // We created a flyer in beforeAll, so we expect the array not to be empty.
@@ -69,11 +70,10 @@ describe('Public Flyer API Routes Integration Tests', () => {
       const testFlyer = flyers[0];
 
       // Act: Fetch items for the first flyer.
-      const response = await apiClient.fetchFlyerItems(testFlyer.flyer_id);
-      const items: FlyerItem[] = await response.json();
+      const response = await request.get(`/api/flyers/${testFlyer.flyer_id}/items`);
+      const items: FlyerItem[] = response.body;
 
-      // Assert: Verify the response and data structure.
-      expect(response.ok).toBe(true);
+      expect(response.status).toBe(200);
       expect(items).toBeInstanceOf(Array);
 
       // If there are items, check the shape of the first one.
@@ -87,18 +87,16 @@ describe('Public Flyer API Routes Integration Tests', () => {
     });
   });
 
-  describe('POST /api/flyer-items/batch-fetch', () => {
+  describe('POST /api/flyers/items/batch-fetch', () => {
     it('should return items for multiple flyer IDs', async () => {
       // Arrange: Get IDs from the flyers fetched in beforeAll.
       const flyerIds = flyers.map((f) => f.flyer_id);
       expect(flyerIds.length).toBeGreaterThan(0);
 
       // Act: Fetch items for all available flyers.
-      const response = await apiClient.fetchFlyerItemsForFlyers(flyerIds);
-      const items: FlyerItem[] = await response.json();
-
-      // Assert
-      expect(response.ok).toBe(true);
+      const response = await request.post('/api/flyers/items/batch-fetch').send({ flyerIds });
+      const items: FlyerItem[] = response.body;
+      expect(response.status).toBe(200);
       expect(items).toBeInstanceOf(Array);
       // The total number of items should be greater than or equal to the number of flyers (assuming at least one item per flyer).
       if (items.length > 0) {
@@ -107,15 +105,15 @@ describe('Public Flyer API Routes Integration Tests', () => {
     });
   });
 
-  describe('POST /api/flyer-items/batch-count', () => {
+  describe('POST /api/flyers/items/batch-count', () => {
     it('should return the total count of items for multiple flyer IDs', async () => {
       // Arrange
       const flyerIds = flyers.map((f) => f.flyer_id);
       expect(flyerIds.length).toBeGreaterThan(0);
 
       // Act
-      const response = await apiClient.countFlyerItemsForFlyers(flyerIds);
-      const result = await response.json();
+      const response = await request.post('/api/flyers/items/batch-count').send({ flyerIds });
+      const result = response.body;
 
       // Assert
       expect(result.count).toBeTypeOf('number');

src/tests/integration/price.integration.test.ts

@@ -0,0 +1,141 @@
+// src/tests/integration/price.integration.test.ts
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import supertest from 'supertest';
+import app from '../../../server';
+import { getPool } from '../../services/db/connection.db';
+
+/**
+ * @vitest-environment node
+ */
+
+const request = supertest(app);
+
+describe('Price History API Integration Test (/api/price-history)', () => {
+  let masterItemId: number;
+  let storeId: number;
+  let flyerId1: number;
+  let flyerId2: number;
+  let flyerId3: number;
+
+  beforeAll(async () => {
+    const pool = getPool();
+
+    // 1. Create a master grocery item
+    const masterItemRes = await pool.query(
+      `INSERT INTO public.master_grocery_items (name, category_id) VALUES ('Integration Test Apples', (SELECT category_id FROM categories WHERE name = 'Fruits & Vegetables' LIMIT 1)) RETURNING master_grocery_item_id`,
+    );
+    masterItemId = masterItemRes.rows[0].master_grocery_item_id;
+
+    // 2. Create a store
+    const storeRes = await pool.query(
+      `INSERT INTO public.stores (name) VALUES ('Integration Price Test Store') RETURNING store_id`,
+    );
+    storeId = storeRes.rows[0].store_id;
+
+    // 3. Create two flyers with different dates
+    const flyerRes1 = await pool.query(
+      `INSERT INTO public.flyers (store_id, file_name, image_url, item_count, checksum, valid_from) 
+       VALUES ($1, 'price-test-1.jpg', 'http://test.com/price-1.jpg', 1, $2, '2025-01-01') RETURNING flyer_id`,
+      [storeId, `checksum-price-1-${Date.now()}`],
+    );
+    flyerId1 = flyerRes1.rows[0].flyer_id;
+
+    const flyerRes2 = await pool.query(
+      `INSERT INTO public.flyers (store_id, file_name, image_url, item_count, checksum, valid_from) 
+       VALUES ($1, 'price-test-2.jpg', 'http://test.com/price-2.jpg', 1, $2, '2025-01-08') RETURNING flyer_id`,
+      [storeId, `checksum-price-2-${Date.now()}`],
+    );
+    flyerId2 = flyerRes2.rows[0].flyer_id; // This was a duplicate, fixed.
+
+    const flyerRes3 = await pool.query(
+      `INSERT INTO public.flyers (store_id, file_name, image_url, item_count, checksum, valid_from) 
+       VALUES ($1, 'price-test-3.jpg', 'http://test.com/price-3.jpg', 1, $2, '2025-01-15') RETURNING flyer_id`,
+      [storeId, `checksum-price-3-${Date.now()}`],
+    );
+    flyerId3 = flyerRes3.rows[0].flyer_id;
+
+    // 4. Create flyer items linking the master item to the flyers with prices
+    await pool.query(
+      `INSERT INTO public.flyer_items (flyer_id, master_item_id, item, price_in_cents, price_display) VALUES ($1, $2, 'Apples', 199, '$1.99')`,
+      [flyerId1, masterItemId],
+    );
+    await pool.query(
+      `INSERT INTO public.flyer_items (flyer_id, master_item_id, item, price_in_cents, price_display) VALUES ($1, $2, 'Apples', 249, '$2.49')`,
+      [flyerId2, masterItemId],
+    );
+    await pool.query(
+      `INSERT INTO public.flyer_items (flyer_id, master_item_id, item, price_in_cents, price_display) VALUES ($1, $2, 'Apples', 299, '$2.99')`,
+      [flyerId3, masterItemId],
+    );
+  });
+
+  afterAll(async () => {
+    const pool = getPool();
+    // The CASCADE on the tables should handle flyer_items.
+    // We just need to delete the flyers, store, and master item.
+    const flyerIds = [flyerId1, flyerId2, flyerId3].filter(Boolean);
+    if (flyerIds.length > 0) {
+      await pool.query('DELETE FROM public.flyers WHERE flyer_id = ANY($1::int[])', [flyerIds]);
+    }
+    if (storeId) await pool.query('DELETE FROM public.stores WHERE store_id = $1', [storeId]);
+    if (masterItemId)
+      await pool.query('DELETE FROM public.master_grocery_items WHERE master_grocery_item_id = $1', [
+        masterItemId,
+      ]);
+  });
+
+  it('should return the correct price history for a given master item ID', async () => {
+    const response = await request.post('/api/price-history').send({ masterItemIds: [masterItemId] });
+
+    expect(response.status).toBe(200);
+    expect(response.body).toBeInstanceOf(Array);
+    expect(response.body).toHaveLength(3);
+
+    expect(response.body[0]).toMatchObject({ master_item_id: masterItemId, price_in_cents: 199 });
+    expect(response.body[1]).toMatchObject({ master_item_id: masterItemId, price_in_cents: 249 });
+    expect(response.body[2]).toMatchObject({ master_item_id: masterItemId, price_in_cents: 299 });
+  });
+
+  it('should respect the limit parameter', async () => {
+    const response = await request
+      .post('/api/price-history')
+      .send({ masterItemIds: [masterItemId], limit: 2 });
+
+    expect(response.status).toBe(200);
+    expect(response.body).toHaveLength(2);
+    expect(response.body[0].price_in_cents).toBe(199);
+    expect(response.body[1].price_in_cents).toBe(249);
+  });
+
+  it('should respect the offset parameter', async () => {
+    const response = await request
+      .post('/api/price-history')
+      .send({ masterItemIds: [masterItemId], limit: 2, offset: 1 });
+
+    expect(response.status).toBe(200);
+    expect(response.body).toHaveLength(2);
+    expect(response.body[0].price_in_cents).toBe(249);
+    expect(response.body[1].price_in_cents).toBe(299);
+  });
+
+  it('should return price history sorted by date in ascending order', async () => {
+    const response = await request.post('/api/price-history').send({ masterItemIds: [masterItemId] });
+
+    expect(response.status).toBe(200);
+    const history = response.body;
+    expect(history).toHaveLength(3);
+
+    const date1 = new Date(history[0].date).getTime();
+    const date2 = new Date(history[1].date).getTime();
+    const date3 = new Date(history[2].date).getTime();
+
+    expect(date1).toBeLessThan(date2);
+    expect(date2).toBeLessThan(date3);
+  });
+
+  it('should return an empty array for a master item ID with no price history', async () => {
+    const response = await request.post('/api/price-history').send({ masterItemIds: [999999] });
+    expect(response.status).toBe(200);
+    expect(response.body).toEqual([]);
+  });
+});

src/tests/integration/public.integration.test.ts

@@ -1,108 +0,0 @@
-// src/tests/integration/public.integration.test.ts
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import * as apiClient from '../../services/apiClient';
-import { getPool } from '../../services/db/connection.db';
-
-/**
- * @vitest-environment node
- */
-
-describe('Public API Routes Integration Tests', () => {
-  let createdFlyerId: number;
-  let createdMasterItemId: number;
-
-  beforeAll(async () => {
-    const pool = getPool();
-    // Create a store for the flyer
-    const storeRes = await pool.query(
-      `INSERT INTO public.stores (name) VALUES ('Public Test Store') RETURNING store_id`,
-    );
-    const storeId = storeRes.rows[0].store_id;
-
-    // Create a flyer
-    const flyerRes = await pool.query(
-      `INSERT INTO public.flyers (store_id, file_name, image_url, item_count, checksum) 
-       VALUES ($1, 'public-test.jpg', 'http://test.com/public.jpg', 0, $2) RETURNING flyer_id`,
-      [storeId, `checksum-public-${Date.now()}`],
-    );
-    createdFlyerId = flyerRes.rows[0].flyer_id;
-
-    // Create a master item. Assumes a category with ID 1 exists from static seeds.
-    const masterItemRes = await pool.query(
-      `INSERT INTO public.master_grocery_items (name, category_id) VALUES ('Public Test Item', 1) RETURNING master_grocery_item_id`,
-    );
-    createdMasterItemId = masterItemRes.rows[0].master_grocery_item_id;
-  });
-
-  afterAll(async () => {
-    const pool = getPool();
-    // Cleanup in reverse order of creation
-    if (createdMasterItemId) {
-      await pool.query(
-        'DELETE FROM public.master_grocery_items WHERE master_grocery_item_id = $1',
-        [createdMasterItemId],
-      );
-    }
-    if (createdFlyerId) {
-      await pool.query('DELETE FROM public.flyers WHERE flyer_id = $1', [createdFlyerId]);
-    }
-  });
-
-  describe('Health Check Endpoints', () => {
-    it('GET /api/health/ping should return "pong"', async () => {
-      const response = await apiClient.pingBackend();
-      expect(response.ok).toBe(true);
-      expect(await response.text()).toBe('pong');
-    });
-
-    it('GET /api/health/db-schema should return success', async () => {
-      const response = await apiClient.checkDbSchema();
-      const result = await response.json();
-      expect(result.success).toBe(true);
-      expect(result.message).toBe('All required database tables exist.');
-    });
-
-    it('GET /api/health/storage should return success', async () => {
-      // This assumes the STORAGE_PATH is correctly set up for the test environment
-      const response = await apiClient.checkStorage();
-      const result = await response.json();
-      expect(result.success).toBe(true);
-      expect(result.message).toContain('is accessible and writable');
-    });
-
-    it('GET /api/health/db-pool should return success', async () => {
-      const response = await apiClient.checkDbPoolHealth();
-      // The pingBackend function returns a boolean directly, so no .json() call is needed.
-      // However, checkDbPoolHealth returns a Response, so we need to parse it.
-      const result = await response.json();
-      expect(result.success).toBe(true);
-      expect(result.message).toContain('Pool Status:');
-    });
-  });
-
-  describe('Public Data Endpoints', () => {
-    it('GET /api/flyers should return a list of flyers', async () => {
-      const response = await apiClient.fetchFlyers();
-      const flyers = await response.json();
-      expect(flyers).toBeInstanceOf(Array);
-      // We created a flyer, so we expect it to be in the list.
-      expect(flyers.length).toBeGreaterThan(0);
-      const foundFlyer = flyers.find((f: { flyer_id: number }) => f.flyer_id === createdFlyerId);
-      expect(foundFlyer).toBeDefined();
-      expect(foundFlyer).toHaveProperty('store');
-    });
-
-    it('GET /api/master-items should return a list of master items', async () => {
-      const response = await apiClient.fetchMasterItems();
-      const masterItems = await response.json();
-      expect(masterItems).toBeInstanceOf(Array);
-      // We created a master item, so we expect it to be in the list.
-      expect(masterItems.length).toBeGreaterThan(0);
-      const foundItem = masterItems.find(
-        (i: { master_grocery_item_id: number }) => i.master_grocery_item_id === createdMasterItemId,
-      );
-      expect(foundItem).toBeDefined();
-      expect(foundItem).toHaveProperty('category_name');
-    });
-  });
-});

src/tests/integration/public.routes.integration.test.ts

@@ -1,6 +1,7 @@
 // src/tests/integration/public.routes.integration.test.ts
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import supertest from 'supertest';
+import app from '../../../server';
 import type {
   Flyer,
   FlyerItem,
@@ -13,8 +14,11 @@ import type {
 import { getPool } from '../../services/db/connection.db';
 import { createAndLoginUser } from '../utils/testHelpers';
 
-const API_URL = process.env.VITE_API_BASE_URL || 'http://localhost:3001/api';
-const request = supertest(API_URL.replace('/api', '')); // supertest needs the server's base URL
+/**
+ * @vitest-environment node
+ */
+
+const request = supertest(app);
 
 describe('Public API Routes Integration Tests', () => {
   // Shared state for tests
@@ -97,17 +101,17 @@ describe('Public API Routes Integration Tests', () => {
       expect(response.status).toBe(200);
       expect(response.body.success).toBe(true);
     });
-  });
 
-  describe('Public Data Endpoints', () => {
-    it('GET /api/time should return the server time', async () => {
-      const response = await request.get('/api/time');
+    it('GET /api/health/time should return the server time', async () => {
+      const response = await request.get('/api/health/time');
       expect(response.status).toBe(200);
       expect(response.body).toHaveProperty('currentTime');
       expect(response.body).toHaveProperty('year');
       expect(response.body).toHaveProperty('week');
     });
+  });
 
+  describe('Public Data Endpoints', () => {
     it('GET /api/flyers should return a list of flyers', async () => {
       const response = await request.get('/api/flyers');
       const flyers: Flyer[] = response.body;
@@ -126,25 +130,25 @@ describe('Public API Routes Integration Tests', () => {
       expect(items[0].flyer_id).toBe(testFlyer.flyer_id);
     });
 
-    it('POST /api/flyer-items/batch-fetch should return items for multiple flyers', async () => {
+    it('POST /api/flyers/items/batch-fetch should return items for multiple flyers', async () => {
       const flyerIds = [testFlyer.flyer_id];
-      const response = await request.post('/api/flyer-items/batch-fetch').send({ flyerIds });
+      const response = await request.post('/api/flyers/items/batch-fetch').send({ flyerIds });
       const items: FlyerItem[] = response.body;
       expect(response.status).toBe(200);
       expect(items).toBeInstanceOf(Array);
       expect(items.length).toBeGreaterThan(0);
     });
 
-    it('POST /api/flyer-items/batch-count should return a count for multiple flyers', async () => {
+    it('POST /api/flyers/items/batch-count should return a count for multiple flyers', async () => {
       const flyerIds = [testFlyer.flyer_id];
-      const response = await request.post('/api/flyer-items/batch-count').send({ flyerIds });
+      const response = await request.post('/api/flyers/items/batch-count').send({ flyerIds });
       expect(response.status).toBe(200);
       expect(response.body.count).toBeTypeOf('number');
       expect(response.body.count).toBeGreaterThan(0);
     });
 
-    it('GET /api/master-items should return a list of master grocery items', async () => {
-      const response = await request.get('/api/master-items');
+    it('GET /api/personalization/master-items should return a list of master grocery items', async () => {
+      const response = await request.get('/api/personalization/master-items');
       const masterItems = response.body;
       expect(response.status).toBe(200);
       expect(masterItems).toBeInstanceOf(Array);
@@ -190,9 +194,9 @@ describe('Public API Routes Integration Tests', () => {
       expect(items).toBeInstanceOf(Array);
     });
 
-    it('GET /api/dietary-restrictions should return a list of restrictions', async () => {
+    it('GET /api/personalization/dietary-restrictions should return a list of restrictions', async () => {
       // This test relies on static seed data for a lookup table, which is acceptable.
-      const response = await request.get('/api/dietary-restrictions');
+      const response = await request.get('/api/personalization/dietary-restrictions');
       const restrictions: DietaryRestriction[] = response.body;
       expect(response.status).toBe(200);
       expect(restrictions).toBeInstanceOf(Array);
@@ -200,8 +204,8 @@ describe('Public API Routes Integration Tests', () => {
       expect(restrictions[0]).toHaveProperty('dietary_restriction_id');
     });
 
-    it('GET /api/appliances should return a list of appliances', async () => {
-      const response = await request.get('/api/appliances');
+    it('GET /api/personalization/appliances should return a list of appliances', async () => {
+      const response = await request.get('/api/personalization/appliances');
       const appliances: Appliance[] = response.body;
       expect(response.status).toBe(200);
       expect(appliances).toBeInstanceOf(Array);

src/tests/integration/system.integration.test.ts

@@ -1,6 +1,7 @@
 // src/tests/integration/system.integration.test.ts
 import { describe, it, expect } from 'vitest';
-import * as apiClient from '../../services/apiClient';
+import supertest from 'supertest';
+import app from '../../../server';
 
 /**
  * @vitest-environment node
@@ -9,15 +10,16 @@ import * as apiClient from '../../services/apiClient';
 describe('System API Routes Integration Tests', () => {
   describe('GET /api/system/pm2-status', () => {
     it('should return a status for PM2', async () => {
+      const request = supertest(app);
       // In a typical CI environment without PM2, this will fail gracefully.
       // The test verifies that the endpoint responds correctly, even if PM2 isn't running.
-      const response = await apiClient.checkPm2Status();
-      const result = await response.json();
+      const response = await request.get('/api/system/pm2-status');
+      const result = response.body;
       expect(result).toBeDefined();
       expect(result).toHaveProperty('message');
       // If the response is successful (200 OK), it must have a 'success' property.
       // If it's an error (e.g., 500 because pm2 command not found), it will only have 'message'.
-      if (response.ok) {
+      if (response.status === 200) {
         expect(result).toHaveProperty('success');
       }
     });

src/tests/integration/user.integration.test.ts

@@ -1,6 +1,7 @@
 // src/tests/integration/user.integration.test.ts
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import * as apiClient from '../../services/apiClient';
+import supertest from 'supertest';
+import app from '../../../server';
 import { logger } from '../../services/logger.server';
 import { getPool } from '../../services/db/connection.db';
 import type { UserProfile, MasterGroceryItem, ShoppingList } from '../../types';
@@ -10,25 +11,12 @@ import { createAndLoginUser, TEST_PASSWORD } from '../utils/testHelpers';
  * @vitest-environment node
  */
 
+const request = supertest(app);
+
 describe('User API Routes Integration Tests', () => {
   let testUser: UserProfile;
   let authToken: string;
 
-  // --- START DEBUG LOGGING ---
-  // Query the DB from within the test file to see its state.
-  beforeAll(async () => {
-    const res = await getPool().query(
-      'SELECT u.user_id, u.email, p.role FROM public.users u JOIN public.profiles p ON u.user_id = p.user_id',
-    );
-    console.log(
-      '\n--- [user.integration.test.ts] Users found in DB from TEST perspective (beforeAll): ---',
-    );
-    console.table(res.rows);
-    console.log(
-      '-------------------------------------------------------------------------------------\n',
-    );
-  });
-  // --- END DEBUG LOGGING ---
   // Before any tests run, create a new user and log them in.
   // The token will be used for all subsequent API calls in this test suite.
   beforeAll(async () => {
@@ -62,11 +50,13 @@ describe('User API Routes Integration Tests', () => {
 
   it('should fetch the authenticated user profile via GET /api/users/profile', async () => {
     // Act: Call the API endpoint using the authenticated token.
-    const response = await apiClient.getAuthenticatedUserProfile({ tokenOverride: authToken });
-    const profile = await response.json();
+    const response = await request
+      .get('/api/users/profile')
+      .set('Authorization', `Bearer ${authToken}`);
+    const profile = response.body;
 
     // Assert: Verify the profile data matches the created user.
-    expect(profile).toBeDefined();
+    expect(response.status).toBe(200);
     expect(profile.user.user_id).toBe(testUser.user.user_id);
     expect(profile.user.email).toBe(testUser.user.email); // This was already correct
     expect(profile.full_name).toBe('Test User');
@@ -80,20 +70,21 @@ describe('User API Routes Integration Tests', () => {
     };
 
     // Act: Call the update endpoint with the new data and the auth token.
-    const response = await apiClient.updateUserProfile(profileUpdates, {
-      tokenOverride: authToken,
-    });
-    const updatedProfile = await response.json();
+    const response = await request
+      .put('/api/users/profile')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send(profileUpdates);
+    const updatedProfile = response.body;
 
     // Assert: Check that the returned profile reflects the changes.
-    expect(updatedProfile).toBeDefined();
+    expect(response.status).toBe(200);
     expect(updatedProfile.full_name).toBe('Updated Test User');
 
     // Also, fetch the profile again to ensure the change was persisted.
-    const refetchResponse = await apiClient.getAuthenticatedUserProfile({
-      tokenOverride: authToken,
-    });
-    const refetchedProfile = await refetchResponse.json();
+    const refetchResponse = await request
+      .get('/api/users/profile')
+      .set('Authorization', `Bearer ${authToken}`);
+    const refetchedProfile = refetchResponse.body;
     expect(refetchedProfile.full_name).toBe('Updated Test User');
   });
 
@@ -104,14 +95,14 @@ describe('User API Routes Integration Tests', () => {
     };
 
     // Act: Call the update endpoint.
-    const response = await apiClient.updateUserPreferences(preferenceUpdates, {
-      tokenOverride: authToken,
-    });
-    const updatedProfile = await response.json();
+    const response = await request
+      .put('/api/users/profile/preferences')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send(preferenceUpdates);
+    const updatedProfile = response.body;
 
     // Assert: Check that the preferences object in the returned profile is updated.
-    expect(updatedProfile).toBeDefined();
-    expect(updatedProfile.preferences).toBeDefined();
+    expect(response.status).toBe(200);
     expect(updatedProfile.preferences?.darkMode).toBe(true);
   });
 
@@ -122,9 +113,14 @@ describe('User API Routes Integration Tests', () => {
 
     // Act & Assert: Attempt to register and expect the promise to reject
     // with an error message indicating the password is too weak.
-    const response = await apiClient.registerUser(email, weakPassword, 'Weak Password User');
-    expect(response.ok).toBe(false);
-    const errorData = (await response.json()) as { message: string; errors: { message: string }[] };
+    const response = await request.post('/api/auth/register').send({
+      email,
+      password: weakPassword,
+      full_name: 'Weak Password User',
+    });
+
+    expect(response.status).toBe(400);
+    const errorData = response.body as { message: string; errors: { message: string }[] };
     // For validation errors, the detailed messages are in the `errors` array.
     // We join them to check for the specific feedback from the password strength checker.
     const detailedErrorMessage = errorData.errors?.map((e) => e.message).join(' ');
@@ -137,18 +133,22 @@ describe('User API Routes Integration Tests', () => {
     const { token: deletionToken } = await createAndLoginUser({ email: deletionEmail });
 
     // Act: Call the delete endpoint with the correct password and token.
-    const response = await apiClient.deleteUserAccount(TEST_PASSWORD, {
-      tokenOverride: deletionToken,
-    });
-    const deleteResponse = await response.json();
+    const response = await request
+      .delete('/api/users/account')
+      .set('Authorization', `Bearer ${deletionToken}`)
+      .send({ password: TEST_PASSWORD });
+    const deleteResponse = response.body;
 
     // Assert: Check for a successful deletion message.
+    expect(response.status).toBe(200);
     expect(deleteResponse.message).toBe('Account deleted successfully.');
 
     // Assert (Verification): Attempting to log in again with the same credentials should now fail.
-    const loginResponse = await apiClient.loginUser(deletionEmail, TEST_PASSWORD, false);
-    expect(loginResponse.ok).toBe(false);
-    const errorData = await loginResponse.json();
+    const loginResponse = await request
+      .post('/api/auth/login')
+      .send({ email: deletionEmail, password: TEST_PASSWORD });
+    expect(loginResponse.status).toBe(401);
+    const errorData = loginResponse.body;
     expect(errorData.message).toBe('Incorrect email or password.');
   });
 
@@ -158,12 +158,14 @@ describe('User API Routes Integration Tests', () => {
     const { user: resetUser } = await createAndLoginUser({ email: resetEmail });
 
     // Act 1: Request a password reset. In our test environment, the token is returned in the response.
-    const resetRequestRawResponse = await apiClient.requestPasswordReset(resetEmail);
-    if (!resetRequestRawResponse.ok) {
-      const errorData = await resetRequestRawResponse.json();
+    const resetRequestRawResponse = await request
+      .post('/api/auth/forgot-password')
+      .send({ email: resetEmail });
+    if (resetRequestRawResponse.status !== 200) {
+      const errorData = resetRequestRawResponse.body;
       throw new Error(errorData.message || 'Password reset request failed');
     }
-    const resetRequestResponse = await resetRequestRawResponse.json();
+    const resetRequestResponse = resetRequestRawResponse.body;
     const resetToken = resetRequestResponse.token;
 
     // Assert 1: Check that we received a token.
@@ -172,19 +174,23 @@ describe('User API Routes Integration Tests', () => {
 
     // Act 2: Use the token to set a new password.
     const newPassword = 'my-new-secure-password-!@#$';
-    const resetRawResponse = await apiClient.resetPassword(resetToken!, newPassword);
-    if (!resetRawResponse.ok) {
-      const errorData = await resetRawResponse.json();
+    const resetRawResponse = await request
+      .post('/api/auth/reset-password')
+      .send({ token: resetToken!, newPassword });
+    if (resetRawResponse.status !== 200) {
+      const errorData = resetRawResponse.body;
       throw new Error(errorData.message || 'Password reset failed');
     }
-    const resetResponse = await resetRawResponse.json();
+    const resetResponse = resetRawResponse.body;
 
     // Assert 2: Check for a successful password reset message.
     expect(resetResponse.message).toBe('Password has been reset successfully.');
 
     // Act 3 & Assert 3 (Verification): Log in with the NEW password to confirm the change.
-    const loginResponse = await apiClient.loginUser(resetEmail, newPassword, false);
-    const loginData = await loginResponse.json();
+    const loginResponse = await request
+      .post('/api/auth/login')
+      .send({ email: resetEmail, password: newPassword });
+    const loginData = loginResponse.body;
     expect(loginData.userprofile).toBeDefined();
     expect(loginData.userprofile.user.user_id).toBe(resetUser.user.user_id);
   });
@@ -192,20 +198,21 @@ describe('User API Routes Integration Tests', () => {
   describe('User Data Routes (Watched Items & Shopping Lists)', () => {
     it('should allow a user to add and remove a watched item', async () => {
       // Act 1: Add a new watched item. The API returns the created master item.
-      const addResponse = await apiClient.addWatchedItem(
-        'Integration Test Item',
-        'Other/Miscellaneous',
-        authToken,
-      );
-      const newItem = await addResponse.json();
+      const addResponse = await request
+        .post('/api/users/watched-items')
+        .set('Authorization', `Bearer ${authToken}`)
+        .send({ itemName: 'Integration Test Item', category: 'Other/Miscellaneous' });
+      const newItem = addResponse.body;
 
       // Assert 1: Check that the item was created correctly.
-      expect(newItem).toBeDefined();
+      expect(addResponse.status).toBe(201);
       expect(newItem.name).toBe('Integration Test Item');
 
       // Act 2: Fetch all watched items for the user.
-      const watchedItemsResponse = await apiClient.fetchWatchedItems(authToken);
-      const watchedItems = await watchedItemsResponse.json();
+      const watchedItemsResponse = await request
+        .get('/api/users/watched-items')
+        .set('Authorization', `Bearer ${authToken}`);
+      const watchedItems = watchedItemsResponse.body;
 
       // Assert 2: Verify the new item is in the user's watched list.
       expect(
@@ -216,11 +223,16 @@ describe('User API Routes Integration Tests', () => {
       ).toBe(true);
 
       // Act 3: Remove the watched item.
-      await apiClient.removeWatchedItem(newItem.master_grocery_item_id, authToken);
+      const removeResponse = await request
+        .delete(`/api/users/watched-items/${newItem.master_grocery_item_id}`)
+        .set('Authorization', `Bearer ${authToken}`);
+      expect(removeResponse.status).toBe(204);
 
       // Assert 3: Fetch again and verify the item is gone.
-      const finalWatchedItemsResponse = await apiClient.fetchWatchedItems(authToken);
-      const finalWatchedItems = await finalWatchedItemsResponse.json();
+      const finalWatchedItemsResponse = await request
+        .get('/api/users/watched-items')
+        .set('Authorization', `Bearer ${authToken}`);
+      const finalWatchedItems = finalWatchedItemsResponse.body;
       expect(
         finalWatchedItems.some(
           (item: MasterGroceryItem) =>
@@ -231,31 +243,33 @@ describe('User API Routes Integration Tests', () => {
 
     it('should allow a user to manage a shopping list', async () => {
       // Act 1: Create a new shopping list.
-      const createListResponse = await apiClient.createShoppingList(
-        'My Integration Test List',
-        authToken,
-      );
-      const newList = await createListResponse.json();
+      const createListResponse = await request
+        .post('/api/users/shopping-lists')
+        .set('Authorization', `Bearer ${authToken}`)
+        .send({ name: 'My Integration Test List' });
+      const newList = createListResponse.body;
 
       // Assert 1: Check that the list was created.
-      expect(newList).toBeDefined();
+      expect(createListResponse.status).toBe(201);
       expect(newList.name).toBe('My Integration Test List');
 
       // Act 2: Add an item to the new list.
-      const addItemResponse = await apiClient.addShoppingListItem(
-        newList.shopping_list_id,
-        { customItemName: 'Custom Test Item' },
-        authToken,
-      );
-      const addedItem = await addItemResponse.json();
+      const addItemResponse = await request
+        .post(`/api/users/shopping-lists/${newList.shopping_list_id}/items`)
+        .set('Authorization', `Bearer ${authToken}`)
+        .send({ customItemName: 'Custom Test Item' });
+      const addedItem = addItemResponse.body;
 
       // Assert 2: Check that the item was added.
-      expect(addedItem).toBeDefined();
+      expect(addItemResponse.status).toBe(201);
       expect(addedItem.custom_item_name).toBe('Custom Test Item');
 
       // Assert 3: Fetch all lists and verify the new item is present in the correct list.
-      const fetchResponse = await apiClient.fetchShoppingLists(authToken);
-      const lists = await fetchResponse.json();
+      const fetchResponse = await request
+        .get('/api/users/shopping-lists')
+        .set('Authorization', `Bearer ${authToken}`);
+      const lists = fetchResponse.body;
+      expect(fetchResponse.status).toBe(200);
       const updatedList = lists.find(
         (l: ShoppingList) => l.shopping_list_id === newList.shopping_list_id,
       );

src/tests/integration/user.routes.integration.test.ts

@@ -1,42 +1,30 @@
 // src/tests/integration/user.routes.integration.test.ts
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import supertest from 'supertest';
+import app from '../../../server';
 import { getPool } from '../../services/db/connection.db';
 import type { UserProfile } from '../../types';
+import { createAndLoginUser } from '../utils/testHelpers';
 
-const API_URL = process.env.VITE_API_BASE_URL || 'http://localhost:3001/api';
-const request = supertest(API_URL.replace('/api', '')); // supertest needs the server's base URL
+/**
+ * @vitest-environment node
+ */
+
+const request = supertest(app);
 
 let authToken = '';
 let createdListId: number;
 let testUser: UserProfile;
-const testPassword = 'password-for-user-routes-test';
 
 describe('User Routes Integration Tests (/api/users)', () => {
   // Authenticate once before all tests in this suite to get a JWT.
   beforeAll(async () => {
-    // Create a new user for this test suite to avoid dependency on seeded data
-    const testEmail = `user-routes-test-${Date.now()}@example.com`;
-
-    // 1. Register the user
-    const registerResponse = await request
-      .post('/api/auth/register')
-      .send({ email: testEmail, password: testPassword, full_name: 'User Routes Test User' });
-    expect(registerResponse.status).toBe(201);
-
-    // 2. Log in as the new user
-    const loginResponse = await request
-      .post('/api/auth/login')
-      .send({ email: testEmail, password: testPassword });
-
-    if (loginResponse.status !== 200) {
-      console.error('Login failed in beforeAll hook:', loginResponse.body);
-    }
-
-    expect(loginResponse.status).toBe(200);
-    expect(loginResponse.body.token).toBeDefined();
-    authToken = loginResponse.body.token;
-    testUser = loginResponse.body.userprofile;
+    // Use the helper to create and log in a user in one step.
+    const { user, token } = await createAndLoginUser({
+      fullName: 'User Routes Test User',
+    });
+    testUser = user;
+    authToken = token;
   });
 
   afterAll(async () => {

src/types.ts

@@ -955,3 +955,9 @@ export interface AdminUserView {
   full_name: string | null;
   avatar_url: string | null;
 }
+
+export interface PriceHistoryData {
+  master_item_id: number;
+  price_in_cents: number;
+  date: string; // ISO date string
+}

src/utils/authUtils.ts

@@ -0,0 +1,20 @@
+// src/utils/authUtils.ts
+import zxcvbn from 'zxcvbn';
+
+/**
+ * Validates the strength of a password using zxcvbn.
+ * @param password The password to validate.
+ * @returns An object with `isValid` and a feedback message.
+ */
+export function validatePasswordStrength(password: string): {
+  isValid: boolean;
+  feedback: string;
+} {
+  const result = zxcvbn(password);
+  // Score: 0-4. We require at least 3.
+  if (result.score < 3) {
+    const suggestions = result.feedback.suggestions.join(' ');
+    return { isValid: false, feedback: `Password is too weak. ${suggestions}` };
+  }
+  return { isValid: true, feedback: '' };
+}

src/utils/zodUtils.test.ts

@@ -0,0 +1,387 @@
+// src/utils/zodUtils.test.ts
+import { describe, it, expect } from 'vitest';
+import {
+  requiredString,
+  numericIdParam,
+  uuidParamSchema,
+  optionalBoolean,
+  optionalNumeric,
+  optionalDate,
+} from './zodUtils';
+
+describe('Zod Utilities', () => {
+  describe('requiredString', () => {
+    const customMessage = 'This field is required and cannot be empty.';
+    const schema = requiredString(customMessage);
+
+    it('should pass for a valid non-empty string', () => {
+      const result = schema.safeParse('hello world');
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toBe('hello world');
+      }
+    });
+
+    it('should fail for an empty string with the custom message', () => {
+      const result = schema.safeParse('');
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toBe(customMessage);
+      }
+    });
+
+    it('should fail for a null value with the custom message', () => {
+      const result = schema.safeParse(null);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toBe(customMessage);
+      }
+    });
+
+    it('should fail for an undefined value with the custom message', () => {
+      const result = schema.safeParse(undefined);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toBe(customMessage);
+      }
+    });
+
+    it('should pass for a string containing only whitespace', () => {
+      const result = schema.safeParse('   ');
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toBe('   ');
+      }
+    });
+
+    it('should fail for a non-string value like a number with a Zod type error', () => {
+      const result = schema.safeParse(123);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        // z.string() will throw its own error message before min(1) is checked.
+        expect(result.error.issues[0].message).toBe('Expected string, received number');
+      }
+    });
+
+    it('should fail for a non-string value like an object with a Zod type error', () => {
+      const result = schema.safeParse({ a: 1 });
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toBe('Expected string, received object');
+      }
+    });
+  });
+
+  describe('numericIdParam', () => {
+    const schema = numericIdParam('id');
+
+    it('should pass for a valid numeric string in params', () => {
+      const result = schema.safeParse({ params: { id: '123' } });
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.params.id).toBe(123);
+      }
+    });
+
+    it('should pass for a valid number in params', () => {
+      const result = schema.safeParse({ params: { id: 456 } });
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.params.id).toBe(456);
+      }
+    });
+
+    it('should fail for a non-numeric string', () => {
+      const result = schema.safeParse({ params: { id: 'abc' } });
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toContain('Expected number, received nan');
+      }
+    });
+
+    it('should fail for a negative number', () => {
+      const result = schema.safeParse({ params: { id: -1 } });
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toContain('Must be a number');
+      }
+    });
+
+    it('should fail for a floating point number', () => {
+      const result = schema.safeParse({ params: { id: 1.5 } });
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toContain('Must be a number');
+      }
+    });
+
+    it('should fail for zero', () => {
+      const result = schema.safeParse({ params: { id: 0 } });
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toContain('Must be a number');
+      }
+    });
+
+    it('should use a custom error message if provided', () => {
+      const customMessage = 'A valid numeric ID is required.';
+      const customSchema = numericIdParam('id', customMessage);
+      const result = customSchema.safeParse({ params: { id: -5 } });
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toBe(customMessage);
+      }
+    });
+  });
+
+  describe('uuidParamSchema', () => {
+    const customMessage = 'A valid UUID is required for the user ID.';
+    const schema = uuidParamSchema('userId', customMessage);
+
+    it('should pass for a valid UUID string', () => {
+      const validUuid = '123e4567-e89b-12d3-a456-426614174000';
+      const result = schema.safeParse({ params: { userId: validUuid } });
+      expect(result.success).toBe(true);
+    });
+
+    it('should fail for an invalid UUID string', () => {
+      const invalidUuid = 'not-a-uuid';
+      const result = schema.safeParse({ params: { userId: invalidUuid } });
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].message).toBe(customMessage);
+      }
+    });
+
+    it('should fail for a non-string value', () => {
+      const result = schema.safeParse({ params: { userId: 12345 } });
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('optionalNumeric', () => {
+    it('should return the default value if input is undefined', () => {
+      const schema = optionalNumeric({ default: 10 });
+      const result = schema.safeParse(undefined);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toBe(10);
+      }
+    });
+
+    it('should parse a valid numeric string', () => {
+      const schema = optionalNumeric();
+      const result = schema.safeParse('123.45');
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toBe(123.45);
+      }
+    });
+
+    it('should parse an empty string as 0', () => {
+      const schema = optionalNumeric();
+      const result = schema.safeParse('');
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toBe(0);
+      }
+    });
+
+    it('should parse a whitespace string as 0', () => {
+      const schema = optionalNumeric();
+      const result = schema.safeParse('   ');
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toBe(0);
+      }
+    });
+
+    it('should treat null as undefined, returning default value or undefined', () => {
+      const schemaWithDefault = optionalNumeric({ default: 99 });
+      const resultWithDefault = schemaWithDefault.safeParse(null);
+      expect(resultWithDefault.success).toBe(true);
+      if (resultWithDefault.success) {
+        expect(resultWithDefault.data).toBe(99);
+      }
+
+      const schemaWithoutDefault = optionalNumeric();
+      const resultWithoutDefault = schemaWithoutDefault.safeParse(null);
+      expect(resultWithoutDefault.success).toBe(true);
+      if (resultWithoutDefault.success) {
+        expect(resultWithoutDefault.data).toBeUndefined();
+      }
+    });
+
+    it('should fail for a non-numeric string', () => {
+      const schema = optionalNumeric();
+      const result = schema.safeParse('abc');
+      expect(result.success).toBe(false);
+    });
+
+    it('should enforce integer constraint', () => {
+      const schema = optionalNumeric({ integer: true });
+      expect(schema.safeParse('123').success).toBe(true);
+      const floatResult = schema.safeParse('123.45');
+      expect(floatResult.success).toBe(false);
+      if (!floatResult.success) {
+        expect(floatResult.error.issues[0].message).toBe('Expected integer, received float');
+      }
+    });
+
+    it('should enforce positive constraint', () => {
+      const schema = optionalNumeric({ positive: true });
+      expect(schema.safeParse('1').success).toBe(true);
+      const zeroResult = schema.safeParse('0');
+      expect(zeroResult.success).toBe(false);
+      if (!zeroResult.success) {
+        expect(zeroResult.error.issues[0].message).toBe('Number must be greater than 0');
+      }
+    });
+
+    it('should enforce non-negative constraint', () => {
+      const schema = optionalNumeric({ nonnegative: true });
+      expect(schema.safeParse('0').success).toBe(true);
+      const negativeResult = schema.safeParse('-1');
+      expect(negativeResult.success).toBe(false);
+      if (!negativeResult.success) {
+        expect(negativeResult.error.issues[0].message).toBe('Number must be greater than or equal to 0');
+      }
+    });
+
+    it('should enforce min and max constraints', () => {
+      const schema = optionalNumeric({ min: 10, max: 20 });
+      expect(schema.safeParse('15').success).toBe(true);
+      const tooSmallResult = schema.safeParse('9');
+      expect(tooSmallResult.success).toBe(false);
+      if (!tooSmallResult.success) {
+        expect(tooSmallResult.error.issues[0].message).toBe('Number must be greater than or equal to 10');
+      }
+      const tooLargeResult = schema.safeParse('21');
+      expect(tooLargeResult.success).toBe(false);
+      if (!tooLargeResult.success) {
+        expect(tooLargeResult.error.issues[0].message).toBe('Number must be less than or equal to 20');
+      }
+    });
+  });
+
+  describe('optionalDate', () => {
+    const schema = optionalDate('Invalid date format');
+
+    it('should pass for a valid YYYY-MM-DD date string', () => {
+      const result = schema.safeParse('2023-12-25');
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toBe('2023-12-25');
+      }
+    });
+
+    it('should pass for undefined (optional)', () => {
+      expect(schema.safeParse(undefined).success).toBe(true);
+    });
+
+    it('should fail for an invalid date string', () => {
+      expect(schema.safeParse('not-a-date').success).toBe(false);
+    });
+  });
+
+  describe('optionalBoolean', () => {
+    it('should return the default value if input is undefined', () => {
+      const schema = optionalBoolean({ default: true });
+      const result = schema.safeParse(undefined);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toBe(true);
+      }
+    });
+
+    it('should return undefined if input is undefined and no default is set', () => {
+      const schema = optionalBoolean();
+      const result = schema.safeParse(undefined);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toBeUndefined();
+      }
+    });
+
+    it('should parse "true" string as true', () => {
+      const schema = optionalBoolean();
+      const result = schema.safeParse('true');
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toBe(true);
+      }
+    });
+
+    it('should parse "false" string as false', () => {
+      const schema = optionalBoolean();
+      const result = schema.safeParse('false');
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toBe(false);
+      }
+    });
+
+    it('should parse "1" as true', () => {
+      const schema = optionalBoolean();
+      const result = schema.safeParse('1');
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toBe(true);
+      }
+    });
+
+    it('should parse "0" as false', () => {
+      const schema = optionalBoolean();
+      const result = schema.safeParse('0');
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toBe(false);
+      }
+    });
+
+    it('should fail for other strings', () => {
+      const schema = optionalBoolean();
+      const result = schema.safeParse('not-a-boolean');
+      expect(result.success).toBe(false);
+    });
+
+    it('should handle null input, returning default or undefined', () => {
+      const schemaWithDefault = optionalBoolean({ default: false });
+      const resultWithDefault = schemaWithDefault.safeParse(null);
+      expect(resultWithDefault.success).toBe(true);
+      if (resultWithDefault.success) {
+        expect(resultWithDefault.data).toBe(false);
+      }
+
+      const schemaWithoutDefault = optionalBoolean();
+      const resultWithoutDefault = schemaWithoutDefault.safeParse(null);
+      expect(resultWithoutDefault.success).toBe(true);
+      if (resultWithoutDefault.success) {
+        expect(resultWithoutDefault.data).toBeUndefined();
+      }
+    });
+
+    it('should handle empty string input, returning default or undefined', () => {
+      const schemaWithDefault = optionalBoolean({ default: true });
+      const resultWithDefault = schemaWithDefault.safeParse('');
+      expect(resultWithDefault.success).toBe(true);
+      if (resultWithDefault.success) {
+        expect(resultWithDefault.data).toBe(true);
+      }
+
+      const schemaWithoutDefault = optionalBoolean();
+      const resultWithoutDefault = schemaWithoutDefault.safeParse('');
+      expect(resultWithoutDefault.success).toBe(true);
+      if (resultWithoutDefault.success) {
+        expect(resultWithoutDefault.data).toBeUndefined();
+      }
+    });
+
+    it('should pass for an actual boolean value', () => {
+      const schema = optionalBoolean();
+      expect(schema.safeParse(true).success).toBe(true);
+      expect(schema.safeParse(false).success).toBe(true);
+    });
+  });
+
+});

src/utils/zodUtils.ts

@@ -0,0 +1,107 @@
+// src/utils/zodUtils.ts
+import { z } from 'zod';
+
+/**
+ * A Zod schema for a required, non-empty string.
+ * @param message The error message to display if the string is empty or missing.
+ * @returns A Zod string schema.
+ */
+export const requiredString = (message: string) =>
+  z.preprocess(
+    // If the value is null or undefined, preprocess it to an empty string.
+    // This ensures that the subsequent `.min(1)` check will catch missing required fields.
+    (val) => val ?? '',
+    // Now, validate that the (potentially preprocessed) value is a string with at least 1 character.
+    z.string().min(1, message),
+  );
+
+/**
+ * Creates a Zod schema for a numeric ID in request parameters.
+ * @param paramName The name of the parameter (e.g., 'id').
+ * @param message The error message for invalid input.
+ * @returns A Zod object schema for the params.
+ */
+export const numericIdParam = (
+  paramName: string,
+  message = `Invalid ID for parameter '${paramName}'. Must be a number.`,
+) =>
+  z.object({
+    params: z.object({
+      [paramName]: z.coerce.number().int(message).positive(message),
+    }),
+  });
+
+/**
+ * Creates a Zod schema for a UUID in request parameters.
+ * @param paramName The name of the parameter (e.g., 'id').
+ * @param message The error message for invalid input.
+ * @returns A Zod object schema for the params.
+ */
+export const uuidParamSchema = (paramName: string, message: string) =>
+  z.object({
+    params: z.object({
+      [paramName]: z.string().uuid(message),
+    }),
+  });
+
+/**
+ * Creates a Zod schema for an optional, numeric query parameter that is coerced from a string.
+ * @param options Configuration for the validation like default value, min/max, and integer constraints.
+ * @returns A Zod schema for the number.
+ */
+export const optionalNumeric = (
+  options: {
+    default?: number;
+    min?: number;
+    max?: number;
+    integer?: boolean;
+    positive?: boolean;
+    nonnegative?: boolean;
+  } = {},
+) => {
+  let schema = z.coerce.number();
+
+  if (options.integer) schema = schema.int();
+  if (options.positive) schema = schema.positive();
+  else if (options.nonnegative) schema = schema.nonnegative();
+
+  if (options.min !== undefined) schema = schema.min(options.min);
+  if (options.max !== undefined) schema = schema.max(options.max);
+
+  if (options.default !== undefined) return schema.optional().default(options.default);
+
+  return schema.optional();
+};
+
+/**
+ * Creates a Zod schema for an optional date string in YYYY-MM-DD format.
+ * @param message Optional custom error message.
+ * @returns A Zod schema for the date string.
+ */
+export const optionalDate = (message?: string) => z.string().date(message).optional();
+
+
+/**
+ * Creates a Zod schema for an optional boolean query parameter that is coerced from a string.
+ * Handles 'true', '1' as true and 'false', '0' as false.
+ * @param options Configuration for the validation like default value.
+ * @returns A Zod schema for the boolean.
+ */
+export const optionalBoolean = (
+  options: {
+    default?: boolean;
+  } = {},
+) => {
+  const schema = z.preprocess((val) => {
+    if (val === 'true' || val === '1') return true;
+    if (val === 'false' || val === '0') return false;
+    if (val === '' || val === null) return undefined; // Treat empty string and null as not present
+    return val;
+  }, z.boolean().optional());
+
+  if (options.default !== undefined) {
+    return schema.default(options.default);
+  }
+
+  return schema;
+};

vitest.config.e2e.ts

@@ -0,0 +1,26 @@
+import { defineConfig, mergeConfig } from 'vitest/config';
+import integrationConfig from './vitest.config.integration';
+
+const e2eConfig = mergeConfig(
+  integrationConfig,
+  defineConfig({
+    test: {
+      name: 'e2e',
+      // Point specifically to E2E tests
+      include: ['src/tests/e2e/**/*.e2e.test.ts'],
+      // Increase timeout for E2E flows that involve AI or full API chains
+      testTimeout: 120000,
+      coverage: {
+        reportsDirectory: '.coverage/e2e',
+      },
+    },
+  }),
+);
+
+// Explicitly override the include array to ensure we don't inherit integration tests
+// (mergeConfig might concatenate arrays by default)
+if (e2eConfig.test) {
+  e2eConfig.test.include = ['src/tests/e2e/**/*.e2e.test.ts'];
+}
+
+export default e2eConfig;