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.
This commit is contained in:
seb
@@ -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": [
|
||||
|
||||
Reference in New Issue
Block a user