Add article history by SKU and SSE update signals for live clients.

Expose getHistoryBySku as GET /article/:sku/history, and document mutation-emitted company signals via GET /events.

src/api/routes/events.js

@@ -0,0 +1,99 @@
+import { subscribe } from '../sse.js';
+
+/**
+ * Registers the SSE update-events stream (requires auth).
+ * @param {import('express').Application} app - Express app
+ * @param {string} [basePath=''] - Optional URL prefix for all routes in this module
+ */
+export function register(app, basePath = '') {
+    /**
+     * @openapi
+     * /events:
+     *   get:
+     *     tags: [Events]
+     *     summary: Subscribe to update signals (SSE)
+     *     description: |
+     *       Opens a Server-Sent Events stream for the authenticated user's
+     *       **selected company**. Clients receive named signals when another
+     *       request successfully mutates shared data for that company
+     *       (including the same browser's other tabs).
+     *
+     *       Use `EventSource` with credentials so the session cookie is sent:
+     *
+     *       ```js
+     *       const es = new EventSource('https://…/api/events', { withCredentials: true });
+     *       es.addEventListener('category', () => { refetchCategoryTree(); });
+     *       es.addEventListener('articles', () => { refetchArticleIndex(); });
+     *       es.addEventListener('article-42000045', () => { refetchArticle('42000045'); });
+     *       ```
+     *
+     *       Keep-alive comments (`: keepalive`) are sent roughly every 25s.
+     *       Reconnect after changing the selected company (the stream is bound
+     *       to the company at connect time).
+     *
+     *       ## Signals
+     *
+     *       | Signal | Emitted after successful |
+     *       |--------|--------------------------|
+     *       | `category` | `POST /category`, `PATCH /category/{id}`, `PUT /category/order`, `DELETE /category/{id}`, `POST /category/{id}/image`, `DELETE /category/{id}/image` |
+     *       | `articles` | `POST /article`, `PATCH /article/{sku}`, `DELETE /article/{sku}` |
+     *       | `article-<sku>` | `PUT /article/{sku}/weight`, `PUT /article/{sku}/prices`, `PUT /article/{sku}/eans`, `PUT /article/{sku}/categories`, `PUT /article/{sku}/brand`, `PUT /article/{sku}/images/order`, `POST /article/{sku}/image`, `DELETE /article/{sku}/image/{fullHash}` |
+     *
+     *       Signals are only sent when the mutation actually succeeds (2xx).
+     *       Failed or no-op validation errors do not emit. The `article-<sku>`
+     *       event name uses the concrete SKU (e.g. `article-42000045`).
+     *     security:
+     *       - cookieAuth: []
+     *     x-markdown: events.md
+     *     responses:
+     *       200:
+     *         description: |
+     *           SSE stream (`text/event-stream`). Each signal is an SSE event
+     *           whose name is the signal id and whose data is `{}`.
+     *         content:
+     *           text/event-stream:
+     *             schema:
+     *               type: string
+     *               example: |
+     *                 event: category
+     *                 data: {}
+     *
+     *                 event: articles
+     *                 data: {}
+     *
+     *                 event: article-42000045
+     *                 data: {}
+     *       400:
+     *         description: No company selected
+     *         content:
+     *           application/json:
+     *             schema:
+     *               $ref: '#/components/schemas/Error'
+     *       401:
+     *         description: Unauthorized
+     *         content:
+     *           application/json:
+     *             schema:
+     *               $ref: '#/components/schemas/Error'
+     */
+    app.get(`${basePath}/events`, (req, res) => {
+        const companyId = req.user.selectedCompanyId;
+        if (companyId == null) {
+            return res.status(400).json({ error: 'No company selected' });
+        }
+
+        req.socket.setTimeout(0);
+        res.setTimeout(0);
+
+        res.status(200);
+        res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
+        res.setHeader('Cache-Control', 'no-cache, no-transform');
+        res.setHeader('Connection', 'keep-alive');
+        res.setHeader('X-Accel-Buffering', 'no');
+        res.flushHeaders?.();
+
+        res.write(': connected\n\n');
+
+        subscribe(res, { companyId, userId: req.user.id });
+    });
+}