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

feat(api): implement articlesupplier endpoints, sort reordering, and openapi docs

Browse Source
This commit is contained in:
seb
2026-09-17 12:38:16 +02:00
parent 49efd5f8a1
commit fe8fa55fbb
9 changed files with 336 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/api/README.md
View File

@@ -45,6 +45,7 @@ Generated from `@openapi` annotations in [`src/api/routes/`](../../src/api/route
| [`routes/article/set-prices.md`](routes/article/set-prices.md) | `PUT /article/{sku}/prices` |
| [`routes/article/supplier/list.md`](routes/article/supplier/list.md) | `GET /article/{sku}/supplier` |
| [`routes/article/supplier/create.md`](routes/article/supplier/create.md) | `POST /article/{sku}/supplier` |
| [`routes/article/supplier/order.md`](routes/article/supplier/order.md) | `PUT /article/{sku}/supplier/order` |
| [`routes/article/supplier/delete.md`](routes/article/supplier/delete.md) | `DELETE /article/{sku}/supplier/{id}` |
| [`routes/article/supplier/update.md`](routes/article/supplier/update.md) | `PATCH /article/{sku}/supplier/{id}` |
| [`routes/article/set-weight.md`](routes/article/set-weight.md) | `PUT /article/{sku}/weight` |
@@ -136,7 +137,7 @@ Clients subscribe via [`GET /events`](routes/events.md) (`text/event-stream`). A
| 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`, `POST /article/{sku}/supplier`, `DELETE /article/{sku}/supplier/{id}`, `PATCH /article/{sku}/supplier/{id}`, `PUT /article/{sku}/weight` |
| `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`, `POST /article/{sku}/supplier`, `PUT /article/{sku}/supplier/order`, `DELETE /article/{sku}/supplier/{id}`, `PATCH /article/{sku}/supplier/{id}`, `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` |

135
docs/api/openapi.json
View File

@@ -6875,6 +6875,11 @@
"nullable": true,
"description": "Supplier stock"
},
"sort": {
"type": "integer",
"nullable": true,
"description": "Display sort order (defaults to next sort)"
},
"netPrice": {
"type": "number",
"nullable": true,
@@ -6896,6 +6901,7 @@
"sku": "MET-44910",
"pu": 1,
"stock": 140,
"sort": 0,
"netPrice": 4.2,
"taxId": 1
}
@@ -7026,6 +7032,10 @@
"type": "number",
"nullable": true
},
"sort": {
"type": "integer",
"description": "Display sort order"
},
"netPrice": {
"type": "number",
"nullable": true
@@ -7189,6 +7199,124 @@
}
}
},
"/article/{sku}/supplier/order": {
"put": {
"tags": [
"Article"
],
"summary": "Reorder article suppliers",
"description": "Sets the display sort order of supplier assignments for an article.\nExpects an array of all assigned `articlesupplier` IDs in the desired order.\n",
"security": [
{
"cookieAuth": []
}
],
"x-signals": [
"article-<sku>"
],
"x-markdown": "article/supplier/order.md",
"parameters": [
{
"in": "path",
"name": "sku",
"required": true,
"schema": {
"type": "string"
},
"description": "Article SKU"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ids"
],
"properties": {
"ids": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Full list of articlesupplier ids in their new order"
}
},
"example": {
"ids": [
12,
10,
15
]
}
}
}
}
},
"responses": {
"200": {
"description": "New order applied",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "integer"
}
}
}
}
}
}
},
"400": {
"description": "Invalid supplier order, ids is required, or no company selected",
"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 or company not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/article": {
"post": {
"tags": [
@@ -9162,7 +9290,8 @@
"id",
"articleId",
"entityId",
"pu"
"pu",
"sort"
],
"properties": {
"id": {
@@ -9192,6 +9321,10 @@
"nullable": true,
"description": "Supplier stock"
},
"sort": {
"type": "integer",
"description": "Display sort order"
},
"priceId": {
"type": "integer",
"nullable": true

2
docs/api/routes/article/supplier/create.md
View File

@@ -21,6 +21,7 @@ Assigns a supplier to an article with optional purchase price, stock, and suppli
"sku": "MET-44910",
"pu": 1,
"stock": 140,
"sort": 0,
"netPrice": 4.2,
"taxId": 1
}
@@ -44,6 +45,7 @@ Created supplier assignment
"sku": "…",
"pu": 1,
"stock": 1,
"sort": 1,
"priceId": 1,
"price": {
"net": 1,

1
docs/api/routes/article/supplier/list.md
View File

@@ -27,6 +27,7 @@ List of suppliers linked to the article
"sku": "…",
"pu": 1,
"stock": 1,
"sort": 1,
"priceId": 1,
"price": {
"net": 1,

56
docs/api/routes/article/supplier/order.md Normal file
View File

@@ -0,0 +1,56 @@
# `PUT /article/{sku}/supplier/order`
Protected. Requires a valid session cookie (`credentials: 'include'`).
Reorder article suppliers
Sets the display sort order of supplier assignments for an article.
Expects an array of all assigned `articlesupplier` IDs in the desired order.
## Path parameters
| Param | Required | Type | Description |
|-------|----------|------|-------------|
| `sku` | yes | string | Article SKU |
## Body (JSON)
```json
{
"ids": [
12,
10,
15
]
}
```
## Signals
On success, emits SSE signal: `article-<sku>` (see [`GET /events`](../events.md)).
## Response `200`
New order applied
```json
{
"ids": [
1
]
}
```
## Errors
| Status | Description |
|--------|-------------|
| 400 | Invalid supplier order, ids is required, or no company selected — `{"error":"…"}` |
| 401 | Unauthorized — `{"error":"…"}` |
| 403 | Not authorized — `{"error":"…"}` |
| 404 | Article or company not found — `{"error":"…"}` |
---
_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._

1
docs/api/routes/article/supplier/update.md
View File

@@ -43,6 +43,7 @@ Updated supplier assignment
"sku": "…",
"pu": 1,
"stock": 1,
"sort": 1,
"priceId": 1,
"price": {
"net": 1,

5
src/api/openapi.js
View File

@@ -124,7 +124,7 @@
* description: Tax rate in percent
* ArticleSupplier:
* type: object
* required: [id, articleId, entityId, pu]
* required: [id, articleId, entityId, pu, sort]
* properties:
* id:
* type: integer
@@ -146,6 +146,9 @@
* type: number
* nullable: true
* description: Supplier stock
* sort:
* type: integer
* description: Display sort order
* priceId:
* type: integer
* nullable: true

131
src/api/routes/articlesupplier.js
View File

@@ -40,9 +40,12 @@ function articleSupplierErrorStatus(error) {
if (error.message === 'Supplier required' || error.message === 'entityId is required') return 400;
if (error.message === 'Invalid pu' || error.message === 'pu must be greater than 0') return 400;
if (error.message === 'Invalid stock') return 400;
if (error.message === 'Invalid sort') return 400;
if (error.message === 'Invalid supplier order') return 400;
if (error.message === 'Invalid price') return 400;
if (error.message === 'sku is required') return 400;
if (error.message === 'id is required') return 400;
if (error.message === 'ids is required') return 400;
return 500;
}
@@ -144,6 +147,10 @@ export function register(app, basePath = '') {
* type: number
* nullable: true
* description: Supplier stock
* sort:
* type: integer
* nullable: true
* description: Display sort order (defaults to next sort)
* netPrice:
* type: number
* nullable: true
@@ -161,6 +168,7 @@ export function register(app, basePath = '') {
* sku: MET-44910
* pu: 1
* stock: 140
* sort: 0
* netPrice: 4.20
* taxId: 1
* responses:
@@ -236,7 +244,7 @@ export function register(app, basePath = '') {
return res.status(400).json({ error: skuParsed.error });
}
const { entityId, sku: supplierSku, pu, stock, netPrice, taxId, taxRate } = req.body ?? {};
const { entityId, sku: supplierSku, pu, stock, sort, netPrice, taxId, taxRate } = req.body ?? {};
if (entityId == null || !Number.isFinite(entityId)) {
return res.status(400).json({ error: 'entityId is required' });
}
@@ -246,6 +254,9 @@ export function register(app, basePath = '') {
if (stock !== undefined && stock !== null && !Number.isFinite(stock)) {
return res.status(400).json({ error: 'Invalid stock' });
}
if (sort !== undefined && sort !== null && (!Number.isInteger(sort) || sort < 0)) {
return res.status(400).json({ error: 'Invalid sort' });
}
if (netPrice !== undefined && netPrice !== null && !Number.isFinite(netPrice)) {
return res.status(400).json({ error: 'Invalid price' });
}
@@ -256,6 +267,7 @@ export function register(app, basePath = '') {
sku: supplierSku,
pu,
stock,
sort,
netPrice,
taxId,
taxRate,
@@ -309,6 +321,9 @@ export function register(app, basePath = '') {
* stock:
* type: number
* nullable: true
* sort:
* type: integer
* description: Display sort order
* netPrice:
* type: number
* nullable: true
@@ -438,6 +453,12 @@ export function register(app, basePath = '') {
}
patch.stock = body.stock;
}
if (body.sort !== undefined) {
if (body.sort === null || !Number.isInteger(body.sort) || body.sort < 0) {
return res.status(400).json({ error: 'Invalid sort' });
}
patch.sort = body.sort;
}
if (body.netPrice !== undefined) {
if (body.netPrice !== null && !Number.isFinite(body.netPrice)) {
return res.status(400).json({ error: 'Invalid price' });
@@ -484,4 +505,112 @@ export function register(app, basePath = '') {
res.status(status).json({ error: error.message });
}
});
/**
* @openapi
* /article/{sku}/supplier/order:
* put:
* tags: [Article]
* summary: Reorder article suppliers
* description: |
* Sets the display sort order of supplier assignments for an article.
* Expects an array of all assigned `articlesupplier` IDs in the desired order.
* security:
* - cookieAuth: []
* x-signals: [article-<sku>]
* x-markdown: article/supplier/order.md
* parameters:
* - in: path
* name: sku
* required: true
* schema:
* type: string
* description: Article SKU
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required: [ids]
* properties:
* ids:
* type: array
* items:
* type: integer
* description: Full list of articlesupplier ids in their new order
* example:
* ids: [12, 10, 15]
* responses:
* 200:
* description: New order applied
* content:
* application/json:
* schema:
* type: object
* properties:
* ids:
* type: array
* items:
* type: integer
* 400:
* description: Invalid supplier order, ids is required, or no company selected
* 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 or company not found
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Error'
*/
app.put(`${basePath}/article/:sku/supplier/order`, async (req, res) => {
const selected = requireSelectedCompany(req);
if (selected.error) {
return res.status(400).json({ error: selected.error });
}
const skuParsed = parseSku(req.params.sku);
if (skuParsed.error) {
return res.status(400).json({ error: skuParsed.error });
}
const rawIds = req.body?.ids;
if (!Array.isArray(rawIds)) {
return res.status(400).json({ error: 'ids is required' });
}
const ids = [];
for (const value of rawIds) {
const id = Number(value);
if (!Number.isInteger(id) || id <= 0) {
return res.status(400).json({ error: 'Invalid supplier order' });
}
ids.push(id);
}
try {
const result = await db.order(req.user.id, skuParsed.sku, { ids });
emitArticleSignal(req, skuParsed.sku);
res.status(200).json(result);
} catch (error) {
const status = articleSupplierErrorStatus(error);
if (status === 500) console.error('Order article suppliers failed:', error);
res.status(status).json({ error: error.message });
}
});
}

6
src/db/articlesupplier.js
View File

@@ -19,3 +19,9 @@ export async function remove(googleAuthId, sku, id) {
const store = await getStore();
return store.articlesupplier.delete(googleAuthId, sku, id);
}
export async function order(googleAuthId, sku, data) {
const store = await getStore();
return store.articlesupplier.order(googleAuthId, sku, data);
}