feat(analytics): add auto-capture middleware for API requests

Express middleware that automatically tracks `api_request` events via
the analytics service. Uses `res.on('finish')` to capture response
metadata (status code, response time) after the response is sent.

- Captures distinctId from req.user._id (or 'anonymous')
- Captures organization group from req.organization._id
- Records endpoint, method, statusCode, and responseTime properties
- Skips health checks (/api/health), static assets, and favicon
- No-op when PostHog is not configured (analytics service short-circuits)
- Registered app-wide in analytics.init.js

Includes 13 unit tests covering all branches.

Closes #3295

Author: PierreBrisorgueil

modules/analytics/analytics.init.js

@@ -2,15 +2,17 @@
  * Module dependencies
  */
 import AnalyticsService from './services/analytics.service.js';
+import analyticsMiddleware from './middlewares/analytics.middleware.js';
 
 /**
  * Initialise the analytics module.
  * Called automatically by the Express init loop (matched via the
  * `modules/{name}/{name}.init.js` glob in config/assets.js).
- * @param {object} _app - Express application instance (unused)
+ * Registers the auto-capture middleware so every API request is tracked.
+ * @param {object} app - Express application instance
  * @returns {void}
  */
-// eslint-disable-next-line no-unused-vars
-export default (_app) => {
+export default (app) => {
   AnalyticsService.init();
+  app.use(analyticsMiddleware);
 };

modules/analytics/middlewares/analytics.middleware.js

@@ -0,0 +1,51 @@
+/**
+ * Module dependencies
+ */
+import AnalyticsService from '../services/analytics.service.js';
+
+/**
+ * Route prefixes to skip when auto-capturing API request events.
+ * Health checks and static assets generate high-frequency, low-value noise.
+ * @type {string[]}
+ */
+const SKIP_PREFIXES = ['/api/health', '/public', '/favicon'];
+
+/**
+ * Express middleware that auto-captures `api_request` events via the
+ * analytics service. Attaches a `res.on('finish')` listener so that the
+ * status code and response time are available when the event is recorded.
+ *
+ * The middleware is a no-op when PostHog is not configured because
+ * `AnalyticsService.track()` itself short-circuits without a client.
+ *
+ * @param {import('express').Request} req - Express request object
+ * @param {import('express').Response} res - Express response object
+ * @param {import('express').NextFunction} next - Express next callback
+ * @returns {void}
+ */
+const analyticsMiddleware = (req, res, next) => {
+  const url = req.originalUrl || req.url;
+
+  // Skip routes that produce high-frequency, low-value events
+  if (SKIP_PREFIXES.some((prefix) => url.startsWith(prefix))) {
+    return next();
+  }
+
+  const start = Date.now();
+
+  res.on('finish', () => {
+    const distinctId = req.user?._id ? String(req.user._id) : 'anonymous';
+    const groups = req.organization?._id ? { company: String(req.organization._id) } : undefined;
+
+    AnalyticsService.track(distinctId, 'api_request', {
+      endpoint: url,
+      method: req.method,
+      statusCode: res.statusCode,
+      responseTime: Date.now() - start,
+    }, groups);
+  });
+
+  return next();
+};
+
+export default analyticsMiddleware;

modules/analytics/tests/analytics.middleware.unit.tests.js

@@ -0,0 +1,196 @@
+/**
+ * Module dependencies.
+ */
+import { jest, beforeEach, afterEach, describe, test, expect } from '@jest/globals';
+
+/**
+ * Unit tests for analytics auto-capture middleware
+ */
+describe('Analytics middleware unit tests:', () => {
+  let analyticsMiddleware;
+  let mockTrack;
+
+  /** @type {import('express').Request} */
+  let req;
+  /** @type {import('express').Response & { _finishHandlers: Function[] }} */
+  let res;
+  /** @type {jest.Mock} */
+  let next;
+
+  beforeEach(async () => {
+    jest.resetModules();
+
+    mockTrack = jest.fn();
+
+    jest.unstable_mockModule('../services/analytics.service.js', () => ({
+      default: {
+        track: mockTrack,
+      },
+    }));
+
+    const mod = await import('../middlewares/analytics.middleware.js');
+    analyticsMiddleware = mod.default;
+
+    // Build minimal Express-like req/res mocks
+    req = {
+      originalUrl: '/api/tasks',
+      url: '/api/tasks',
+      method: 'GET',
+      user: { _id: 'user-123' },
+      organization: { _id: 'org-456' },
+    };
+
+    const finishHandlers = [];
+    res = {
+      statusCode: 200,
+      on: jest.fn((event, handler) => {
+        if (event === 'finish') finishHandlers.push(handler);
+      }),
+      _finishHandlers: finishHandlers,
+    };
+
+    next = jest.fn();
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  /**
+   * Helper — trigger all registered 'finish' handlers on res.
+   */
+  const triggerFinish = () => {
+    res._finishHandlers.forEach((fn) => fn());
+  };
+
+  test('should call next immediately', () => {
+    analyticsMiddleware(req, res, next);
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  test('should register a finish listener on res', () => {
+    analyticsMiddleware(req, res, next);
+    expect(res.on).toHaveBeenCalledWith('finish', expect.any(Function));
+  });
+
+  test('should track api_request with correct properties on finish', () => {
+    analyticsMiddleware(req, res, next);
+    triggerFinish();
+
+    expect(mockTrack).toHaveBeenCalledWith(
+      'user-123',
+      'api_request',
+      expect.objectContaining({
+        endpoint: '/api/tasks',
+        method: 'GET',
+        statusCode: 200,
+        responseTime: expect.any(Number),
+      }),
+      { company: 'org-456' },
+    );
+  });
+
+  test('should use "anonymous" when req.user is absent', () => {
+    req.user = undefined;
+    req.organization = undefined;
+    analyticsMiddleware(req, res, next);
+    triggerFinish();
+
+    expect(mockTrack).toHaveBeenCalledWith(
+      'anonymous',
+      'api_request',
+      expect.any(Object),
+      undefined,
+    );
+  });
+
+  test('should use "anonymous" when req.user._id is missing', () => {
+    req.user = {};
+    analyticsMiddleware(req, res, next);
+    triggerFinish();
+
+    expect(mockTrack).toHaveBeenCalledWith(
+      'anonymous',
+      'api_request',
+      expect.any(Object),
+      expect.anything(),
+    );
+  });
+
+  test('should omit groups when req.organization is absent', () => {
+    req.organization = undefined;
+    analyticsMiddleware(req, res, next);
+    triggerFinish();
+
+    expect(mockTrack).toHaveBeenCalledWith(
+      'user-123',
+      'api_request',
+      expect.any(Object),
+      undefined,
+    );
+  });
+
+  test('should skip /api/health routes', () => {
+    req.originalUrl = '/api/health';
+    analyticsMiddleware(req, res, next);
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(res.on).not.toHaveBeenCalled();
+  });
+
+  test('should skip /api/health sub-routes', () => {
+    req.originalUrl = '/api/health/ready';
+    analyticsMiddleware(req, res, next);
+
+    expect(res.on).not.toHaveBeenCalled();
+  });
+
+  test('should skip /public static assets', () => {
+    req.originalUrl = '/public/images/logo.png';
+    analyticsMiddleware(req, res, next);
+
+    expect(res.on).not.toHaveBeenCalled();
+  });
+
+  test('should skip /favicon requests', () => {
+    req.originalUrl = '/favicon.ico';
+    analyticsMiddleware(req, res, next);
+
+    expect(res.on).not.toHaveBeenCalled();
+  });
+
+  test('should capture correct statusCode from res on finish', () => {
+    analyticsMiddleware(req, res, next);
+    res.statusCode = 404;
+    triggerFinish();
+
+    expect(mockTrack).toHaveBeenCalledWith(
+      expect.any(String),
+      'api_request',
+      expect.objectContaining({ statusCode: 404 }),
+      expect.anything(),
+    );
+  });
+
+  test('should capture responseTime as a non-negative number', () => {
+    analyticsMiddleware(req, res, next);
+    triggerFinish();
+
+    const properties = mockTrack.mock.calls[0][2];
+    expect(properties.responseTime).toBeGreaterThanOrEqual(0);
+  });
+
+  test('should fall back to req.url when originalUrl is absent', () => {
+    req.originalUrl = undefined;
+    req.url = '/api/fallback';
+    analyticsMiddleware(req, res, next);
+    triggerFinish();
+
+    expect(mockTrack).toHaveBeenCalledWith(
+      expect.any(String),
+      'api_request',
+      expect.objectContaining({ endpoint: '/api/fallback' }),
+      expect.anything(),
+    );
+  });
+});