seb/dashback
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Expose getHistoryBySku as GET /article/:sku/history, and document mutation-emitted company signals via GET /events.
This commit is contained in:
seb
2026-08-05 09:54:56 +02:00
parent 4a9403bfd1
commit 782c49a680
28 changed files with 757 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/api/README.md
View File

@@ -38,6 +38,7 @@ Generated from `@openapi` annotations in [`src/api/routes/`](../../src/api/route
| [`routes/article/set-brand.md`](routes/article/set-brand.md) | `PUT /article/{sku}/brand` |
| [`routes/article/set-categories.md`](routes/article/set-categories.md) | `PUT /article/{sku}/categories` |
| [`routes/article/set-eans.md`](routes/article/set-eans.md) | `PUT /article/{sku}/eans` |
| [`routes/article/history.md`](routes/article/history.md) | `GET /article/{sku}/history` |
| [`routes/article/add-image.md`](routes/article/add-image.md) | `POST /article/{sku}/image` |
| [`routes/article/delete-image.md`](routes/article/delete-image.md) | `DELETE /article/{sku}/image/{fullHash}` |
| [`routes/article/order-images.md`](routes/article/order-images.md) | `PUT /article/{sku}/images/order` |
@@ -64,6 +65,7 @@ Generated from `@openapi` annotations in [`src/api/routes/`](../../src/api/route
| [`routes/company/create.md`](routes/company/create.md) | `POST /company` |
| [`routes/company/delete.md`](routes/company/delete.md) | `DELETE /company/{id}` |
| [`routes/company/update.md`](routes/company/update.md) | `PUT /company/{id}` |
| [`routes/events.md`](routes/events.md) | `GET /events` |
| [`routes/health.md`](routes/health.md) | `GET /health` |
| [`routes/image/get.md`](routes/image/get.md) | `GET /image/{fullHash}` |
| [`routes/posterminal/list.md`](routes/posterminal/list.md) | `GET /posterminal` |
@@ -80,6 +82,16 @@ Generated from `@openapi` annotations in [`src/api/routes/`](../../src/api/route
Machine-readable spec: [`openapi.json`](openapi.json).
## Signals (SSE)
Clients subscribe via [`GET /events`](routes/events.md) (`text/event-stream`). After a successful mutation, the API emits a named SSE event (signal) to subscribers of the same selected company.
| Signal | Emitted by |
|--------|------------|
| `article-<sku>` | `PUT /article/{sku}/brand`, `PUT /article/{sku}/categories`, `PUT /article/{sku}/eans`, `POST /article/{sku}/image`, `DELETE /article/{sku}/image/{fullHash}`, `PUT /article/{sku}/images/order`, `PUT /article/{sku}/prices`, `PUT /article/{sku}/weight` |
| `articles` | `POST /article`, `DELETE /article/{sku}`, `PATCH /article/{sku}` |
| `category` | `POST /category`, `PUT /category/order`, `DELETE /category/{id}`, `PATCH /category/{id}`, `DELETE /category/{id}/image`, `POST /category/{id}/image` |
## DESIGN
- for every route we have a file in /src/api/routes

226
docs/api/openapi.json
View File

@@ -20,6 +20,10 @@
"name": "Health",
"description": "Connectivity checks"
},
{
"name": "Events",
"description": "SSE update signals for live clients"
},
{
"name": "Article",
"description": "Articles under categories"
@@ -1150,6 +1154,54 @@
}
}
},
"/events": {
"get": {
"tags": [
"Events"
],
"summary": "Subscribe to update signals (SSE)",
"description": "Opens a Server-Sent Events stream for the authenticated user's\n**selected company**. Clients receive named signals when another\nrequest successfully mutates shared data for that company\n(including the same browser's other tabs).\n\nUse `EventSource` with credentials so the session cookie is sent:\n\n```js\nconst es = new EventSource('https://…/api/events', { withCredentials: true });\nes.addEventListener('category', () => { refetchCategoryTree(); });\nes.addEventListener('articles', () => { refetchArticleIndex(); });\nes.addEventListener('article-42000045', () => { refetchArticle('42000045'); });\n```\n\nKeep-alive comments (`: keepalive`) are sent roughly every 25s.\nReconnect after changing the selected company (the stream is bound\nto the company at connect time).\n\n## Signals\n\n| Signal | Emitted after successful |\n|--------|--------------------------|\n| `category` | `POST /category`, `PATCH /category/{id}`, `PUT /category/order`, `DELETE /category/{id}`, `POST /category/{id}/image`, `DELETE /category/{id}/image` |\n| `articles` | `POST /article`, `PATCH /article/{sku}`, `DELETE /article/{sku}` |\n| `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}` |\n\nSignals are only sent when the mutation actually succeeds (2xx).\nFailed or no-op validation errors do not emit. The `article-<sku>`\nevent name uses the concrete SKU (e.g. `article-42000045`).\n",
"security": [
{
"cookieAuth": []
}
],
"x-markdown": "events.md",
"responses": {
"200": {
"description": "SSE stream (`text/event-stream`). Each signal is an SSE event\nwhose name is the signal id and whose data is `{}`.\n",
"content": {
"text/event-stream": {
"schema": {
"type": "string",
"example": "event: category\ndata: {}\n\nevent: articles\ndata: {}\n\nevent: article-42000045\ndata: {}\n"
}
}
}
},
"400": {
"description": "No company selected",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/company": {
"get": {
"tags": [
@@ -1639,6 +1691,9 @@
"cookieAuth": []
}
],
"x-signals": [
"category"
],
"x-markdown": "category/create.md",
"requestBody": {
"required": true,
@@ -1814,6 +1869,9 @@
"cookieAuth": []
}
],
"x-signals": [
"category"
],
"x-markdown": "category/update.md",
"parameters": [
{
@@ -1941,6 +1999,9 @@
"cookieAuth": []
}
],
"x-signals": [
"category"
],
"x-markdown": "category/delete.md",
"parameters": [
{
@@ -2002,6 +2063,9 @@
"cookieAuth": []
}
],
"x-signals": [
"category"
],
"x-markdown": "category/order.md",
"requestBody": {
"required": true,
@@ -2112,6 +2176,9 @@
"cookieAuth": []
}
],
"x-signals": [
"category"
],
"x-markdown": "category/add-image.md",
"parameters": [
{
@@ -2218,6 +2285,9 @@
"cookieAuth": []
}
],
"x-signals": [
"category"
],
"x-markdown": "category/delete-image.md",
"parameters": [
{
@@ -2558,6 +2628,9 @@
"cookieAuth": []
}
],
"x-signals": [
"articles"
],
"x-markdown": "article/create.md",
"requestBody": {
"required": true,
@@ -2816,6 +2889,9 @@
"cookieAuth": []
}
],
"x-signals": [
"articles"
],
"x-markdown": "article/update.md",
"parameters": [
{
@@ -2924,6 +3000,9 @@
"cookieAuth": []
}
],
"x-signals": [
"articles"
],
"x-markdown": "article/delete.md",
"parameters": [
{
@@ -2983,6 +3062,109 @@
}
}
},
"/article/{sku}/history": {
"get": {
"tags": [
"Article"
],
"summary": "Get article history by SKU",
"description": "Returns `articlehistory` rows for the article, newest first (`date` DESC, `id` DESC).\nAuth like GET by SKU.\n",
"security": [
{
"cookieAuth": []
}
],
"x-markdown": "article/history.md",
"parameters": [
{
"in": "path",
"name": "sku",
"required": true,
"schema": {
"type": "string"
},
"description": "Article SKU"
}
],
"responses": {
"200": {
"description": "Article history (newest first)",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"history"
],
"properties": {
"history": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ArticleHistoryEntry"
}
}
},
"example": {
"history": [
{
"id": 42,
"date": "2026-08-05T07:15:00.000Z",
"text": "Name geändert von \"Tee\" auf \"Grüner Tee\"\nEinheit geändert von \"500g\" auf \"1kg\""
},
{
"id": 41,
"date": "2026-08-01T09:00:00.000Z",
"text": "Name geändert von \"\" auf \"Tee\""
}
]
}
}
}
}
},
"400": {
"description": "Missing sku",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Not authorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Article not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/article/{sku}/prices": {
"put": {
"tags": [
@@ -2995,6 +3177,9 @@
"cookieAuth": []
}
],
"x-signals": [
"article-<sku>"
],
"x-markdown": "article/set-prices.md",
"parameters": [
{
@@ -3129,6 +3314,9 @@
"cookieAuth": []
}
],
"x-signals": [
"article-<sku>"
],
"x-markdown": "article/add-image.md",
"parameters": [
{
@@ -3223,6 +3411,9 @@
"cookieAuth": []
}
],
"x-signals": [
"article-<sku>"
],
"x-markdown": "article/delete-image.md",
"parameters": [
{
@@ -3302,6 +3493,9 @@
"cookieAuth": []
}
],
"x-signals": [
"article-<sku>"
],
"x-markdown": "article/order-images.md",
"parameters": [
{
@@ -3415,6 +3609,9 @@
"cookieAuth": []
}
],
"x-signals": [
"article-<sku>"
],
"x-markdown": "article/set-eans.md",
"parameters": [
{
@@ -3523,6 +3720,9 @@
"cookieAuth": []
}
],
"x-signals": [
"article-<sku>"
],
"x-markdown": "article/set-brand.md",
"parameters": [
{
@@ -3627,6 +3827,9 @@
"cookieAuth": []
}
],
"x-signals": [
"article-<sku>"
],
"x-markdown": "article/set-weight.md",
"parameters": [
{
@@ -3730,6 +3933,9 @@
"cookieAuth": []
}
],
"x-signals": [
"article-<sku>"
],
"x-markdown": "article/set-categories.md",
"parameters": [
{
@@ -4319,6 +4525,26 @@
"description": "Full article payload (unit, brand, categoryIds, photos, eans, prices, …)",
"additionalProperties": true
},
"ArticleHistoryEntry": {
"type": "object",
"required": [
"id",
"date",
"text"
],
"properties": {
"id": {
"type": "integer"
},
"date": {
"type": "string",
"format": "date-time"
},
"text": {
"type": "string"
}
}
},
"Brand": {
"type": "object",
"required": [

4
docs/api/routes/article/add-image.md
View File

@@ -20,6 +20,10 @@ Auth like GET by SKU.
Raw binary (`image/avif`).
## Signals
On success, emits SSE signal: `article-<sku>` (see [`GET /events`](../events.md)).
## Response `201`
Image stored and linked

4
docs/api/routes/article/create.md
View File

@@ -15,6 +15,10 @@ Creates an article under an authorized category (`parentId`).
}
```
## Signals
On success, emits SSE signal: `articles` (see [`GET /events`](../events.md)).
## Response `201`
Created

4
docs/api/routes/article/delete-image.md
View File

@@ -13,6 +13,10 @@ Removes `articlepic` and the `pic` row for this article (`fullHash`). Auth like
| `sku` | yes | string | |
| `fullHash` | yes | string | |
## Signals
On success, emits SSE signal: `article-<sku>` (see [`GET /events`](../events.md)).
## Response `204`
Deleted

4
docs/api/routes/article/delete.md
View File

@@ -15,6 +15,10 @@ Auth like GET by SKU.
|-------|----------|------|-------------|
| `sku` | yes | string | Article SKU |
## Signals
On success, emits SSE signal: `articles` (see [`GET /events`](../events.md)).
## Response `204`
Deleted

49
docs/api/routes/article/history.md Normal file
View File

@@ -0,0 +1,49 @@
# `GET /article/{sku}/history`
Protected. Requires a valid session cookie (`credentials: 'include'`).
Get article history by SKU
Returns `articlehistory` rows for the article, newest first (`date` DESC, `id` DESC).
Auth like GET by SKU.
## Path parameters
| Param | Required | Type | Description |
|-------|----------|------|-------------|
| `sku` | yes | string | Article SKU |
## Response `200`
Article history (newest first)
```json
{
"history": [
{
"id": 42,
"date": "2026-08-05T07:15:00.000Z",
"text": "Name geändert von \"Tee\" auf \"Grüner Tee\"\nEinheit geändert von \"500g\" auf \"1kg\""
},
{
"id": 41,
"date": "2026-08-01T09:00:00.000Z",
"text": "Name geändert von \"\" auf \"Tee\""
}
]
}
```
## Errors
| Status | Description |
|--------|-------------|
| 400 | Missing sku — `{"error":"…"}` |
| 401 | Unauthorized — `{"error":"…"}` |
| 403 | Not authorized — `{"error":"…"}` |
| 404 | Article not found — `{"error":"…"}` |
---
_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._

4
docs/api/routes/article/order-images.md
View File

@@ -25,6 +25,10 @@ Sets `articlepic.sort` to `0..n-1` in the given order.
}
```
## Signals
On success, emits SSE signal: `article-<sku>` (see [`GET /events`](../events.md)).
## Response `200`
New order

4
docs/api/routes/article/set-brand.md
View File

@@ -22,6 +22,10 @@ Pass `null` to clear the brand. Returns the same shape as GET by SKU.
}
```
## Signals
On success, emits SSE signal: `article-<sku>` (see [`GET /events`](../events.md)).
## Response `200`
Updated article detail

4
docs/api/routes/article/set-categories.md
View File

@@ -26,6 +26,10 @@ article from all categories. Returns the same shape as GET by SKU.
}
```
## Signals
On success, emits SSE signal: `article-<sku>` (see [`GET /events`](../events.md)).
## Response `200`
Updated article detail

4
docs/api/routes/article/set-eans.md
View File

@@ -24,6 +24,10 @@ empty array clears all EANs. Returns the same shape as GET by SKU.
}
```
## Signals
On success, emits SSE signal: `article-<sku>` (see [`GET /events`](../events.md)).
## Response `200`
Updated article detail

4
docs/api/routes/article/set-prices.md
View File

@@ -33,6 +33,10 @@ Empty `prices` clears all POS prices. Returns the same shape as GET by SKU.
}
```
## Signals
On success, emits SSE signal: `article-<sku>` (see [`GET /events`](../events.md)).
## Response `200`
Updated article detail

4
docs/api/routes/article/set-weight.md
View File

@@ -22,6 +22,10 @@ Returns the same shape as GET by SKU.
}
```
## Signals
On success, emits SSE signal: `article-<sku>` (see [`GET /events`](../events.md)).
## Response `200`
Updated article detail

4
docs/api/routes/article/update.md
View File

@@ -23,6 +23,10 @@ Patches article fields. At least one of `name`, `unitamount`, `unitSi` required.
}
```
## Signals
On success, emits SSE signal: `articles` (see [`GET /events`](../events.md)).
## Response `200`
Updated article detail

4
docs/api/routes/category/add-image.md
View File

@@ -20,6 +20,10 @@ Auth like GET /category/tree — user must be authorized for the category's comp
Raw binary (`image/avif`).
## Signals
On success, emits SSE signal: `category` (see [`GET /events`](../events.md)).
## Response `201`
Image stored and linked

4
docs/api/routes/category/create.md
View File

@@ -15,6 +15,10 @@ Creates a category under an authorized parent.
}
```
## Signals
On success, emits SSE signal: `category` (see [`GET /events`](../events.md)).
## Response `201`
Created

4
docs/api/routes/category/delete-image.md
View File

@@ -14,6 +14,10 @@ Auth like GET /category/tree — user must be authorized for the category's comp
|-------|----------|------|-------------|
| `id` | yes | integer | Category id |
## Signals
On success, emits SSE signal: `category` (see [`GET /events`](../events.md)).
## Response `200`
Image removed

4
docs/api/routes/category/delete.md
View File

@@ -12,6 +12,10 @@ Deletes a category the user is authorized for (not the company root).
|-------|----------|------|-------------|
| `id` | yes | integer | Category id |
## Signals
On success, emits SSE signal: `category` (see [`GET /events`](../events.md)).
## Response `204`
Deleted

4
docs/api/routes/category/order.md
View File

@@ -24,6 +24,10 @@ to its index `0..n-1` in one transaction.
}
```
## Signals
On success, emits SSE signal: `category` (see [`GET /events`](../events.md)).
## Response `200`
New sibling order

4
docs/api/routes/category/update.md
View File

@@ -24,6 +24,10 @@ Either `name` or `parentId` (or both) is required.
}
```
## Signals
On success, emits SSE signal: `category` (see [`GET /events`](../events.md)).
## Response `200`
Updated category (renamed and/or moved)

53
docs/api/routes/events.md Normal file
View File

@@ -0,0 +1,53 @@
# `GET /events`
Protected. Requires a valid session cookie (`credentials: 'include'`).
Subscribe to update signals (SSE)
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`).
## Response `200`
SSE stream (`text/event-stream`). Each signal is an SSE event
whose name is the signal id and whose data is `{}`.
## Errors
| Status | Description |
|--------|-------------|
| 400 | No company selected — `{"error":"…"}` |
| 401 | Unauthorized — `{"error":"…"}` |
---
_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._