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

u

Browse Source
This commit is contained in:
seb
2026-10-12 13:11:28 +02:00
parent 4429294d8b
commit 1f09e620e3
8 changed files with 233 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/api/README.md
View File

@@ -206,7 +206,8 @@ Generated from `@openapi` annotations in [`src/api/routes/`](../../src/api/route
| [`routes/quote/update.md`](routes/quote/update.md) | `PATCH /quote/{id}` |
| [`routes/serper/image.md`](routes/serper/image.md) | `POST /serper/image` |
| [`routes/serper/images.md`](routes/serper/images.md) | `POST /serper/images` |
| [`routes/shipping/_id.md`](routes/shipping/_id.md) | `DELETE /shipping/{id}` |
| [`routes/shipping/_id.delete.md`](routes/shipping/_id.delete.md) | `DELETE /shipping/{id}` |
| [`routes/shipping/_id.patch.md`](routes/shipping/_id.patch.md) | `PATCH /shipping/{id}` |
| [`routes/shipping/_id/package.get.md`](routes/shipping/_id/package.get.md) | `GET /shipping/{id}/package` |
| [`routes/shipping/_id/package.post.md`](routes/shipping/_id/package.post.md) | `POST /shipping/{id}/package` |
| [`routes/smallthumb/get.md`](routes/smallthumb/get.md) | `GET /smallthumb/{fullHash}` |

7
docs/api/routes-all.md
View File

@@ -1,6 +1,6 @@
# Dash API Routes Overview (All)
Overview of all 209 API endpoints across all modules.
Overview of all 210 API endpoints across all modules.
### Notation
@@ -563,7 +563,7 @@ _none_
- Params: `id: int`
- Returns: `200 { shippings: T39[] }`
#### Create shipping for an order — `POST /order/{id}/shipping`
- Params: `id: int, body: { type: str, state: str }`
- Params: `id: int, body: { type: str, state: str, warehouseId?: int }`
- Returns: `201 { shipping: T39 }`
### Section: /package
@@ -700,6 +700,9 @@ _none_
#### Delete shipping — `DELETE /shipping/{id}`
- Params: `id: int`
- Returns: `204 void`
#### Update shipping — `PATCH /shipping/{id}`
- Params: `id: int, body: { type?: str, state?: str, warehouseId?: int }`
- Returns: `200 { shipping: T39 }`
#### List packages of a shipping — `GET /shipping/{id}/package`
- Params: `id: int`
- Returns: `200 { packages: { id: int, shippingId: int, entityaddressId: int, number: str, type: str, state: str, details?: str|null }[] }`

7
docs/api/routes.md
View File

@@ -1,6 +1,6 @@
# Dash API Routes Overview
Overview of all 162 API endpoints across all modules.
Overview of all 163 API endpoints across all modules.
### Notation
@@ -464,7 +464,7 @@ _none_
- Params: `id: int`
- Returns: `200 { shippings: T35[] }`
#### Create shipping for an order — `POST /order/{id}/shipping`
- Params: `id: int, body: { type: str, state: str }`
- Params: `id: int, body: { type: str, state: str, warehouseId?: int }`
- Returns: `201 { shipping: T35 }`
### Section: /package
@@ -544,6 +544,9 @@ _none_
#### Delete shipping — `DELETE /shipping/{id}`
- Params: `id: int`
- Returns: `204 void`
#### Update shipping — `PATCH /shipping/{id}`
- Params: `id: int, body: { type?: str, state?: str, warehouseId?: int }`
- Returns: `200 { shipping: T35 }`
#### List packages of a shipping — `GET /shipping/{id}/package`
- Params: `id: int`
- Returns: `200 { packages: { id: int, shippingId: int, entityaddressId: int, number: str, type: str, state: str, details?: str|null }[] }`

8
docs/api/routes/order/_id/shipping.post.md
View File

@@ -6,6 +6,7 @@ Create shipping for an order
Creates a shipping for the order. The shipping number is allocated from the
`shipping` number sequence (prefix and counter from the numbers API).
If `state` is `shipped`, stock is adjusted via the ledger and article history is written.
## Path parameters
@@ -20,11 +21,13 @@ Creates a shipping for the order. The shipping number is allocated from the
|-------|----------|------|-------------|
| `type` | yes | string | |
| `state` | yes | string | |
| `warehouseId` | no | integer | Optional warehouse ID for stock deduction when state is shipped |
```json
{
"type": "…",
"state": "…"
"state": "…",
"warehouseId": 1
}
```
@@ -51,7 +54,8 @@ Created shipping
| 400 | Validation error or no company selected — `{"error":"…"}` |
| 401 | Unauthorized — `{"error":"…"}` |
| 403 | Not authorized — `{"error":"…"}` |
| 404 | Order not found — `{"error":"…"}` |
| 404 | Order or warehouse not found — `{"error":"…"}` |
| 409 | Order already shipped — `{"error":"…"}` |
---

4
docs/api/routes/shipping/_id.md → docs/api/routes/shipping/_id.delete.md
View File

@@ -5,6 +5,8 @@ Protected. Requires a valid session cookie (`credentials: 'include'`).
Delete shipping
Deletes a shipping of the selected company. Its packages are removed as well.
Shipped shippings cannot be deleted because stock movements have been ledgered.
## Path parameters
@@ -25,6 +27,8 @@ _No content_
| 400 | Invalid ID or no company selected — `{"error":"…"}` |
| 401 | Unauthorized — `{"error":"…"}` |
| 403 | Not authorized — `{"error":"…"}` |
| 404 | Shipping not found — `{"error":"…"}` |
| 409 | Shipped shipping cannot be deleted — `{"error":"…"}` |
---

61
docs/api/routes/shipping/_id.patch.md Normal file
View File

@@ -0,0 +1,61 @@
# `PATCH /shipping/{id}`
Protected. Requires a valid session cookie (`credentials: 'include'`).
Update shipping
Updates a shipping record. If transitioned to `shipped`, stock is adjusted
via ledger and article history is written. Once shipped, it cannot be undone.
## Path parameters
| Param | Required | Type | Description |
|-------|----------|------|-------------|
| `id` | yes | integer | Shipping ID |
## Body (JSON)
| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `type` | no | string | |
| `state` | no | string | |
| `warehouseId` | no | integer | Warehouse ID for stock deduction when transitioning to shipped |
```json
{
"type": "…",
"state": "…",
"warehouseId": 1
}
```
## Response `200`
Updated shipping
```json
{
"shipping": {
"id": 1,
"manifestId": 1,
"number": "…",
"type": "…",
"state": "…"
}
}
```
## Errors
| Status | Description |
|--------|-------------|
| 400 | Validation error or no company selected — `{"error":"…"}` |
| 401 | Unauthorized — `{"error":"…"}` |
| 403 | Not authorized — `{"error":"…"}` |
| 404 | Shipping or warehouse not found — `{"error":"…"}` |
| 409 | Shipped shipping cannot be undone, or order already shipped — `{"error":"…"}` |
---
_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._

147
src/api/routes/shipping.js
View File

@@ -1,4 +1,5 @@
import * as db from '../../db/shipping.js';
import { emit } from '../sse.js';
// #region Helpers
@@ -23,9 +24,23 @@ function shippingErrorStatus(error) {
if (error.message === 'Not authorized') return 403;
if (error.message?.endsWith(' not found')) return 404;
if (error.message?.endsWith(' required')) return 400;
if (
error.message?.includes('cannot be deleted') ||
error.message?.includes('cannot be undone') ||
error.message?.includes('already shipped')
) {
return 409;
}
return 500;
}
function emitShippingEvents(companyId) {
emit('stock', { companyId });
emit('ledger', { companyId });
emit('articles', { companyId });
emit('order', { companyId });
}
// #endregion
/**
@@ -115,6 +130,7 @@ export function register(app, basePath = '') {
* description: |
* Creates a shipping for the order. The shipping number is allocated from the
* `shipping` number sequence (prefix and counter from the numbers API).
* If `state` is `shipped`, stock is adjusted via the ledger and article history is written.
* security:
* - cookieAuth: []
* parameters:
@@ -136,6 +152,9 @@ export function register(app, basePath = '') {
* type: string
* state:
* type: string
* warehouseId:
* type: integer
* description: Optional warehouse ID for stock deduction when state is shipped
* responses:
* 201:
* description: Created shipping
@@ -165,7 +184,13 @@ export function register(app, basePath = '') {
* schema:
* $ref: '#/components/schemas/Error'
* 404:
* description: Order not found
* description: Order or warehouse not found
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Error'
* 409:
* description: Order already shipped
* content:
* application/json:
* schema:
@@ -189,6 +214,9 @@ export function register(app, basePath = '') {
...(req.body ?? {}),
manifestId: parsedId.id,
});
if (String(shipping.state || '').trim().toLowerCase() === 'shipped') {
emitShippingEvents(selected.companyId);
}
res.status(201).json({ shipping });
} catch (error) {
const status = shippingErrorStatus(error);
@@ -199,13 +227,116 @@ export function register(app, basePath = '') {
// #endregion
/**
* @openapi
* /shipping/{id}:
* patch:
* tags: [Shipping]
* summary: Update shipping
* description: |
* Updates a shipping record. If transitioned to `shipped`, stock is adjusted
* via ledger and article history is written. Once shipped, it cannot be undone.
* security:
* - cookieAuth: []
* parameters:
* - in: path
* name: id
* required: true
* schema:
* type: integer
* description: Shipping ID
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* type:
* type: string
* state:
* type: string
* warehouseId:
* type: integer
* description: Warehouse ID for stock deduction when transitioning to shipped
* responses:
* 200:
* description: Updated shipping
* content:
* application/json:
* schema:
* type: object
* properties:
* shipping:
* $ref: '#/components/schemas/Shipping'
* 400:
* description: Validation error 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: Shipping or warehouse not found
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Error'
* 409:
* description: Shipped shipping cannot be undone, or order already shipped
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Error'
*/
// #region PATCH /shipping/:id
app.patch(`${basePath}/shipping/:id`, async (req, res) => {
const selected = requireSelectedCompany(req);
if (selected.error) {
return res.status(400).json({ error: selected.error });
}
const parsedId = parsePositiveInt(req.params.id, 'id');
if (parsedId.error) {
return res.status(400).json({ error: parsedId.error });
}
try {
const shipping = await db.update(req.user.id, parsedId.id, req.body ?? {});
if (String(shipping.state || '').trim().toLowerCase() === 'shipped') {
emitShippingEvents(selected.companyId);
}
res.status(200).json({ shipping });
} catch (error) {
const status = shippingErrorStatus(error);
if (status === 500) console.error('Update shipping failed:', error);
res.status(status).json({ error: error.message });
}
});
// #endregion
/**
* @openapi
* /shipping/{id}:
* delete:
* tags: [Shipping]
* summary: Delete shipping
* description: Deletes a shipping of the selected company. Its packages are removed as well.
* description: |
* Deletes a shipping of the selected company. Its packages are removed as well.
* Shipped shippings cannot be deleted because stock movements have been ledgered.
* security:
* - cookieAuth: []
* parameters:
@@ -236,6 +367,18 @@ export function register(app, basePath = '') {
* application/json:
* schema:
* $ref: '#/components/schemas/Error'
* 404:
* description: Shipping not found
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Error'
* 409:
* description: Shipped shipping cannot be deleted
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Error'
*/
// #region DELETE /shipping/:id

5
src/db/shipping.js
View File

@@ -10,6 +10,11 @@ export async function create(googleAuthId, data) {
return store.shipping.create(googleAuthId, data);
}
export async function update(googleAuthId, id, patch) {
const store = await getStore();
return store.shipping.update(googleAuthId, id, patch);
}
export async function remove(googleAuthId, id) {
const store = await getStore();
return store.shipping.delete(googleAuthId, id);