Rewrite store JSDoc, split quote/order into modules, and generate typed API docs

- Rewrite JSDoc across all store methods to document the actual async
  methods (real params, returns, throws) instead of the internal wrappers
- Split quote/order into individual module files backed by shared
  manifestDoc helpers; remove the createStore factory and thin wrappers
- Deduplicate manifest line helpers into src/store/manifestLines.js
- Extend generate-api-doc.js to render parameter/return/throws types and
  emit per-namespace API.<module>.md files with an API.md index
- Regenerate all API docs
This commit is contained in:
seb
2026-08-07 06:23:17 +02:00
parent 396389457f
commit aefd97a171
127 changed files with 3956 additions and 1684 deletions

View File

@@ -8,9 +8,22 @@ This document is auto-generated from the JSDoc comments in `src/store` by runnin
Adds an image to a category, processing it into AVIF full and thumb variants.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `categoryId` | `number` | The id of the category. |
| `image` | `Buffer` | The source image buffer. |
**Returns**
`Promise<{id: number, fullHash: string, thumbW: number, thumbH: number, thumbHash: string}>` — The added image info.
**Example**
```js
const fn = addImage(pool);
const result = await fn(42, 5, imageBuffer);
const result = await store.category.addImage(42, 5, imageBuffer);
// => { id, fullHash, thumbW, thumbH, thumbHash }
```
@@ -20,9 +33,23 @@ const result = await fn(42, 5, imageBuffer);
Creates a new category under a given parent category.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `input` | `object` | The category creation input. |
| `input.googleAuthId` | `number` | The id of the Google auth user. |
| `input.parentId` | `number` | The id of the parent category. |
| `input.name` | `string` | The category name. |
**Returns**
`Promise<{id: number, parentId: number, sort: number, name: string, slug: string}>` — The created category.
**Example**
```js
const fn = createUnderParent(pool);
const category = await fn({ googleAuthId: 42, parentId: 5, name: 'Drinks' });
const category = await store.category.createUnderParent({ googleAuthId: 42, parentId: 5, name: 'Drinks' });
// => { id, parentId, sort, name, slug }
```
@@ -32,9 +59,26 @@ const category = await fn({ googleAuthId: 42, parentId: 5, name: 'Drinks' });
Deletes a category, refusing to delete the company's root category.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `input` | `object` | The delete input. |
| `input.googleAuthId` | `number` | The id of the Google auth user. |
| `input.id` | `number` | The id of the category to delete. |
**Returns**
`Promise<void>`
**Throws**
`Error` — If the category is the root category.
**Example**
```js
const fn = del(pool);
await fn({ googleAuthId: 42, id: 5 });
await store.category.delete({ googleAuthId: 42, id: 5 });
```
## `category.deleteImage`
@@ -43,10 +87,26 @@ await fn({ googleAuthId: 42, id: 5 });
Deletes the image of a category.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `categoryId` | `number` | The id of the category. |
**Returns**
`Promise<{id: number, thumbW: null, thumbH: null, thumbHash: null}>` — The cleared image info.
**Throws**
`Error` — If the image is not found.
**Example**
```js
const fn = deleteImage(pool);
const result = await fn(42, 5);
// => { id, thumbW: null, thumbH: null, thumbHash: null }
const result = await store.category.deleteImage(42, 5);
// => { id: 5, thumbW: null, thumbH: null, thumbHash: null }
```
## `category.getCategoryArticles`
@@ -55,9 +115,21 @@ const result = await fn(42, 5);
Returns the articles belonging to a single category.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `categoryId` | `number` | The id of the category. |
**Returns**
`Promise<Array<object>>` — The articles in the category.
**Example**
```js
const fn = getCategoryArticles(pool);
const articles = await fn(42, 5);
const articles = await store.category.getCategoryArticles(42, 5);
// => [{ id, sku, name, ... }]
```
@@ -65,11 +137,22 @@ const articles = await fn(42, 5);
*Source: `src/store/category/getTreeForCompany.js`*
Returns the full category tree for a company together with its articles and the posterminal ids assigned to each category.
Returns the full category tree for the user's selected company together with its articles and the posterminal ids assigned to each category.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
**Returns**
`Promise<{languageId: number, tree: Array<object>, articles: Array<object>}>` — The category tree, articles and language.
**Example**
```js
const fn = getTreeForCompany(pool);
const tree = await fn(42);
const tree = await store.category.getTreeForCompany(42);
// => { languageId, tree: [{ id, posterminalIds, ... }], articles: [...] }
```
@@ -79,9 +162,27 @@ const tree = await fn(42);
Moves a category to a new parent, preventing cycles and cross-company moves.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `input` | `object` | The move input. |
| `input.googleAuthId` | `number` | The id of the Google auth user. |
| `input.id` | `number` | The id of the category to move. |
| `input.parentId` | `number` | The id of the new parent category. |
**Returns**
`Promise<{id: number, parentId: number, sort: number}>` — The moved category.
**Throws**
`Error` — If the move would create a cycle or cross companies.
**Example**
```js
const fn = move(pool);
const result = await fn({ googleAuthId: 42, id: 5, parentId: 9 });
const result = await store.category.move({ googleAuthId: 42, id: 5, parentId: 9 });
// => { id, parentId, sort }
```
@@ -91,9 +192,27 @@ const result = await fn({ googleAuthId: 42, id: 5, parentId: 9 });
Reorders the child categories of a given parent.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `input` | `object` | The reorder input. |
| `input.googleAuthId` | `number` | The id of the Google auth user. |
| `input.parentId` | `number` | The id of the parent category. |
| `input.categoryIds` | `Array<number>` | The child category ids in their new order. |
**Returns**
`Promise<{categoryIds: Array<number>}>` — The applied order.
**Throws**
`Error` — If the order is invalid.
**Example**
```js
const fn = order(pool);
const result = await fn({ googleAuthId: 42, parentId: 5, categoryIds: [3, 1, 2] });
const result = await store.category.order({ googleAuthId: 42, parentId: 5, categoryIds: [3, 1, 2] });
// => { categoryIds: [3, 1, 2] }
```
@@ -103,8 +222,26 @@ const result = await fn({ googleAuthId: 42, parentId: 5, categoryIds: [3, 1, 2]
Renames a category and updates its slug.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `input` | `object` | The rename input. |
| `input.googleAuthId` | `number` | The id of the Google auth user. |
| `input.id` | `number` | The id of the category to rename. |
| `input.name` | `string` | The new category name. |
**Returns**
`Promise<{id: number, name: string, slug: string}>` — The renamed category.
**Throws**
`Error` — If the name is empty or the category is not found.
**Example**
```js
const fn = rename(pool);
const result = await fn({ googleAuthId: 42, id: 5, name: 'Soft Drinks' });
const result = await store.category.rename({ googleAuthId: 42, id: 5, name: 'Soft Drinks' });
// => { id, name, slug }
```