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

* 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

* fix(analytics): strip query strings, configurable prefixes, add integration tests

- Strip query strings from endpoint before sending to analytics (prevents PII leak)
- Make skip prefixes configurable via createAnalyticsMiddleware(options) factory
- Export SKIP_PREFIXES and createAnalyticsMiddleware as named exports
- Add integration test suite with supertest (9 tests covering real HTTP lifecycle)
- Tighten groups assertion in unit test for anonymous user with org
- Document lazy identity resolution in JSDoc (req.user/req.organization read at finish time)

Author: PierreBrisorgueil

modules/analytics/analytics.init.js

@@ -2,15 +2,22 @@
  * 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.
+ * The middleware reads identity context (`req.user`, `req.organization`)
+ * lazily inside the `res.on('finish')` handler, so it is safe to mount
+ * here — before route-level auth middleware is wired.
+ *
+ * @param {object} app - Express application instance
  * @returns {Promise<void>}
  */
-// eslint-disable-next-line no-unused-vars
-export default async (_app) => {
+export default async (app) => {
   await AnalyticsService.init();
+  app.use(analyticsMiddleware);
 };

modules/analytics/middlewares/analytics.middleware.js

@@ -0,0 +1,66 @@
+/**
+ * Module dependencies
+ */
+import AnalyticsService from '../services/analytics.service.js';
+
+/**
+ * Default 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'];
+
+/**
+ * Create an 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.
+ *
+ * Identity context (`req.user`, `req.organization`) is read lazily inside the
+ * `finish` handler — not at middleware execution time — so the middleware can
+ * safely be mounted before auth/org resolution.
+ *
+ * The middleware is a no-op when PostHog is not configured because
+ * `AnalyticsService.track()` itself short-circuits without a client.
+ *
+ * @param {Object} [options] - Configuration options
+ * @param {string[]} [options.skipPrefixes] - Route prefixes to skip (defaults to SKIP_PREFIXES)
+ * @returns {import('express').RequestHandler}
+ */
+const createAnalyticsMiddleware = (options = {}) => {
+  const prefixes = options.skipPrefixes || SKIP_PREFIXES;
+
+  return (req, res, next) => {
+    const rawUrl = req.originalUrl || req.url;
+    const endpoint = (rawUrl || '').split('?')[0] || '/';
+
+    // Skip routes that produce high-frequency, low-value events
+    if (prefixes.some((prefix) => endpoint.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,
+        method: req.method,
+        statusCode: res.statusCode,
+        responseTime: Date.now() - start,
+      }, groups);
+    });
+
+    return next();
+  };
+};
+
+/**
+ * Pre-built middleware instance using default options.
+ * @type {import('express').RequestHandler}
+ */
+const analyticsMiddleware = createAnalyticsMiddleware();
+
+export { createAnalyticsMiddleware, SKIP_PREFIXES };
+export default analyticsMiddleware;

modules/analytics/tests/analytics.middleware.integration.tests.js

@@ -0,0 +1,162 @@
+/**
+ * Module dependencies.
+ */
+import { jest, beforeAll, afterAll, beforeEach, describe, test, expect } from '@jest/globals';
+import express from 'express';
+import request from 'supertest';
+
+/**
+ * Integration tests for analytics auto-capture middleware.
+ * Boots a minimal Express app with the middleware mounted to validate
+ * real HTTP request/response lifecycle behaviour.
+ */
+describe('Analytics middleware integration tests:', () => {
+  let app;
+  let mockTrack;
+
+  beforeAll(async () => {
+    jest.resetModules();
+
+    mockTrack = jest.fn();
+
+    jest.unstable_mockModule('../services/analytics.service.js', () => ({
+      default: {
+        track: mockTrack,
+      },
+    }));
+
+    const { createAnalyticsMiddleware } = await import('../middlewares/analytics.middleware.js');
+
+    app = express();
+    app.use(createAnalyticsMiddleware());
+
+    // Simulate auth middleware populating req.user / req.organization
+    app.use((req, _res, next) => {
+      if (req.headers['x-test-user']) {
+        req.user = { _id: req.headers['x-test-user'] };
+      }
+      if (req.headers['x-test-org']) {
+        req.organization = { _id: req.headers['x-test-org'] };
+      }
+      next();
+    });
+
+    app.get('/api/tasks', (_req, res) => res.json({ ok: true }));
+    app.get('/api/health', (_req, res) => res.json({ status: 'ok' }));
+    app.get('/public/logo.png', (_req, res) => res.send('img'));
+    app.get('/favicon.ico', (_req, res) => res.send('ico'));
+    app.get('/api/error', (_req, res) => res.status(500).json({ error: true }));
+  });
+
+  beforeEach(() => {
+    mockTrack.mockClear();
+  });
+
+  afterAll(() => {
+    jest.restoreAllMocks();
+  });
+
+  test('should track a normal API request with user and org', async () => {
+    await request(app)
+      .get('/api/tasks')
+      .set('x-test-user', 'user-abc')
+      .set('x-test-org', 'org-xyz')
+      .expect(200);
+
+    expect(mockTrack).toHaveBeenCalledTimes(1);
+    expect(mockTrack).toHaveBeenCalledWith(
+      'user-abc',
+      'api_request',
+      expect.objectContaining({
+        endpoint: '/api/tasks',
+        method: 'GET',
+        statusCode: 200,
+        responseTime: expect.any(Number),
+      }),
+      { company: 'org-xyz' },
+    );
+  });
+
+  test('should use "anonymous" when no user header is set', async () => {
+    await request(app)
+      .get('/api/tasks')
+      .expect(200);
+
+    expect(mockTrack).toHaveBeenCalledTimes(1);
+    expect(mockTrack).toHaveBeenCalledWith(
+      'anonymous',
+      'api_request',
+      expect.any(Object),
+      undefined,
+    );
+  });
+
+  test('should omit groups when no org header is set', async () => {
+    await request(app)
+      .get('/api/tasks')
+      .set('x-test-user', 'user-abc')
+      .expect(200);
+
+    expect(mockTrack).toHaveBeenCalledTimes(1);
+    const groups = mockTrack.mock.calls[0][3];
+    expect(groups).toBeUndefined();
+  });
+
+  test('should not track /api/health requests', async () => {
+    await request(app)
+      .get('/api/health')
+      .expect(200);
+
+    expect(mockTrack).not.toHaveBeenCalled();
+  });
+
+  test('should not track /public requests', async () => {
+    await request(app)
+      .get('/public/logo.png')
+      .expect(200);
+
+    expect(mockTrack).not.toHaveBeenCalled();
+  });
+
+  test('should not track /favicon requests', async () => {
+    await request(app)
+      .get('/favicon.ico')
+      .expect(200);
+
+    expect(mockTrack).not.toHaveBeenCalled();
+  });
+
+  test('should capture real status code for error responses', async () => {
+    await request(app)
+      .get('/api/error')
+      .set('x-test-user', 'user-abc')
+      .expect(500);
+
+    expect(mockTrack).toHaveBeenCalledTimes(1);
+    expect(mockTrack).toHaveBeenCalledWith(
+      'user-abc',
+      'api_request',
+      expect.objectContaining({ statusCode: 500 }),
+      undefined,
+    );
+  });
+
+  test('should capture positive responseTime', async () => {
+    await request(app)
+      .get('/api/tasks')
+      .expect(200);
+
+    const properties = mockTrack.mock.calls[0][2];
+    expect(properties.responseTime).toBeGreaterThanOrEqual(0);
+  });
+
+  test('should strip query strings from endpoint', async () => {
+    await request(app)
+      .get('/api/tasks?page=1&token=secret')
+      .expect(200);
+
+    expect(mockTrack).toHaveBeenCalledTimes(1);
+    const properties = mockTrack.mock.calls[0][2];
+    expect(properties.endpoint).toBe('/api/tasks');
+  });
+});