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

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

Browse Source 
- 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
Download Patch File Download Diff File Expand all files Collapse all files

300
API.article.md
View File

@@ -8,9 +8,22 @@ This document is auto-generated from the JSDoc comments in `src/store` by runnin
Adds an image to an article by its SKU, processing it into AVIF variants.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The article SKU. |
| `image` | `Buffer` | The source image buffer. |
**Returns**
`Promise<{picId: number, sort: number, full: {w: number, h: number, size: number}, thumb: {w: number, h: number}, fullHash: string, thumbHash: string}>` — The added image info.
**Example**
```js
const fn = addImage(pool);
const result = await fn(42, 'SKU-1', imageBuffer);
const result = await store.article.addImage(42, 'SKU-1', imageBuffer);
// => { picId, sort, full: { w, h, size }, thumb: { w, h }, fullHash, thumbHash }
```
@@ -20,9 +33,23 @@ const result = await fn(42, 'SKU-1', imageBuffer);
Creates a new article under a given parent category, allocating a SKU and a default unit.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `input` | `object` | The article 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 article name. |
**Returns**
`Promise<{id: number, parentId: number, name: string, sku: string}>` — The created article.
**Example**
```js
const fn = createUnderParent(pool);
const article = await fn({ googleAuthId: 42, parentId: 5, name: 'Cola' });
const article = await store.article.createUnderParent({ googleAuthId: 42, parentId: 5, name: 'Cola' });
// => { id, parentId, name, sku }
```
@@ -32,9 +59,25 @@ const article = await fn({ googleAuthId: 42, parentId: 5, name: 'Cola' });
Deletes an article by its SKU, refusing when it still has children.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The article SKU. |
**Returns**
`Promise<void>`
**Throws**
`Error` — If the article has children or is not found.
**Example**
```js
const fn = del(pool);
await fn(42, 'SKU-1');
await store.article.delete(42, 'SKU-1');
```
## `article.deleteImage`
@@ -43,9 +86,26 @@ await fn(42, 'SKU-1');
Deletes an image from an article by its SKU and full image hash.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The article SKU. |
| `fullHash` | `string` | The full image hash to delete. |
**Returns**
`Promise<void>`
**Throws**
`Error` — If the image is not found.
**Example**
```js
const fn = deleteImage(pool);
await fn(42, 'SKU-1', 'abc123');
await store.article.deleteImage(42, 'SKU-1', 'abc123');
```
## `article.getBySku`
@@ -54,9 +114,25 @@ await fn(42, 'SKU-1', 'abc123');
Returns the full detail of an article by its SKU, including unit, brand, categories, photos, EANs and prices.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The article SKU. |
**Returns**
`Promise<{article: object}>` — The full article detail.
**Throws**
`Error` — If the article is not found or the user is not authorized.
**Example**
```js
const fn = getBySku(pool);
const article = await fn(42, 'SKU-1');
const article = await store.article.getBySku(42, 'SKU-1');
// => { article: { id, sku, name, unit, brand, categoryIds, photos, eans, prices, ... } }
```
@@ -66,9 +142,21 @@ const article = await fn(42, 'SKU-1');
Returns the change history of an article by its SKU.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The article SKU. |
**Returns**
`Promise<Array<{id: number, companyuserId: number|null, date: string, text: string}>>` — The article history entries.
**Example**
```js
const fn = getHistoryBySku(pool);
const history = await fn(42, 'SKU-1');
const history = await store.article.getHistoryBySku(42, 'SKU-1');
// => [{ id, companyuserId, date, text }]
```
@@ -78,9 +166,25 @@ const history = await fn(42, 'SKU-1');
Returns articles for export, optionally scoped to a category, including category breadcrumbs and image hashes.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `[categoryId]` | `number|null` | Optional category id to scope the export to; defaults to the company root. |
**Returns**
`Promise<Array<object>>` — The articles for export.
**Throws**
`Error` — If the category is not reachable from the selected company.
**Example**
```js
const fn = listExport(pool);
const articles = await fn(42, null);
const articles = await store.article.listExport(42, null);
// => [{ id, sku, name, slug, unitSi, net, taxRate, eans, categoryBreadcrumbs, fullHashes, ... }]
```
@@ -88,11 +192,22 @@ const articles = await fn(42, null);
*Source: `src/store/article/listSearchIndex.js`*
Returns a lightweight search index of all articles for a company.
Returns a lightweight search index of all articles for the user's selected company.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
**Returns**
`Promise<Array<{id: number, sku: string, name: string, eans: Array<string>, categoryIds: Array<number>}>>` — The article search index.
**Example**
```js
const fn = listSearchIndex(pool);
const articles = await fn(42);
const articles = await store.article.listSearchIndex(42);
// => [{ id, sku, name, eans, categoryIds }]
```
@@ -102,9 +217,27 @@ const articles = await fn(42);
Reorders the images of an article by its SKU.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The article SKU. |
| `input` | `object` | The reorder input. |
| `input.fullHashes` | `Array<string>` | The full image hashes in their new order. |
**Returns**
`Promise<{fullHashes: Array<string>}>` — The applied order.
**Throws**
`Error` — If the order is invalid.
**Example**
```js
const fn = orderImages(pool);
const result = await fn(42, 'SKU-1', { fullHashes: ['a', 'b'] });
const result = await store.article.orderImages(42, 'SKU-1', { fullHashes: ['a', 'b'] });
// => { fullHashes: ['a', 'b'] }
```
@@ -114,9 +247,26 @@ const result = await fn(42, 'SKU-1', { fullHashes: ['a', 'b'] });
Sets (or clears) the brand of an article by its SKU.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The article SKU. |
| `brandId` | `number|null` | The brand id, or `null` to clear the brand. |
**Returns**
`Promise<object>` — The updated article.
**Throws**
`Error` — If the brand or article is not found.
**Example**
```js
const fn = setBrandIdBySku(pool);
const article = await fn(42, 'SKU-1', 3);
const article = await store.article.setBrandIdBySku(42, 'SKU-1', 3);
// => { id, sku, name, ... }
```
@@ -126,9 +276,26 @@ const article = await fn(42, 'SKU-1', 3);
Replaces the category membership of an article by its SKU.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The article SKU. |
| `categoryIds` | `Array<number>` | The category ids the article should belong to (at least one). |
**Returns**
`Promise<object>` — The updated article.
**Throws**
`Error` — If the category ids are invalid or the article is not found.
**Example**
```js
const fn = setCategoryIdsBySku(pool);
const article = await fn(42, 'SKU-1', [5, 9]);
const article = await store.article.setCategoryIdsBySku(42, 'SKU-1', [5, 9]);
// => { id, sku, name, ... }
```
@@ -138,9 +305,26 @@ const article = await fn(42, 'SKU-1', [5, 9]);
Replaces the EAN list of an article by its SKU.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The article SKU. |
| `eans` | `Array<string>` | The EANs to set (must be unique, non-empty strings). |
**Returns**
`Promise<object>` — The updated article.
**Throws**
`Error` — If the EANs are invalid or the article is not found.
**Example**
```js
const fn = setEansBySku(pool);
const article = await fn(42, 'SKU-1', ['4001234567890']);
const article = await store.article.setEansBySku(42, 'SKU-1', ['4001234567890']);
// => { id, sku, name, ... }
```
@@ -150,9 +334,26 @@ const article = await fn(42, 'SKU-1', ['4001234567890']);
Replaces the price list of an article by its SKU.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The article SKU. |
| `prices` | `Array<{price: number, tax: number, minmultiplier?: number}>` | The price entries (minmultiplier defaults to 1). |
**Returns**
`Promise<object>` — The updated article.
**Throws**
`Error` — If the prices are invalid or the article is not found.
**Example**
```js
const fn = setPricesBySku(pool);
const article = await fn(42, 'SKU-1', [{ price: 1.5, tax: 19, minmultiplier: 1 }]);
const article = await store.article.setPricesBySku(42, 'SKU-1', [{ price: 1.5, tax: 19, minmultiplier: 1 }]);
// => { id, sku, name, ... }
```
@@ -162,9 +363,26 @@ const article = await fn(42, 'SKU-1', [{ price: 1.5, tax: 19, minmultiplier: 1 }
Sets the weight of an article by its SKU.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The article SKU. |
| `weight` | `number` | The weight (must be >= 0). |
**Returns**
`Promise<object>` — The updated article.
**Throws**
`Error` — If the weight is invalid or the article is not found.
**Example**
```js
const fn = setWeightBySku(pool);
const article = await fn(42, 'SKU-1', 1.5);
const article = await store.article.setWeightBySku(42, 'SKU-1', 1.5);
// => { id, sku, name, ... }
```
@@ -174,8 +392,28 @@ const article = await fn(42, 'SKU-1', 1.5);
Updates an article's name and/or unit (SI and amount), recording history.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The article SKU. |
| `patch` | `object` | The update patch. |
| `[patch.name]` | `string` | The new article name. |
| `[patch.unitSi]` | `string` | The new unit SI code. |
| `[patch.unitamount]` | `number` | The new unit amount (must be > 0). |
**Returns**
`Promise<object>` — The updated article.
**Throws**
`Error` — If no valid field is provided or the article is not found.
**Example**
```js
const fn = updateBySku(pool);
const article = await fn(42, 'SKU-1', { name: 'Cola 1L', unitSi: 'l', unitamount: 1 });
const article = await store.article.updateBySku(42, 'SKU-1', { name: 'Cola 1L', unitSi: 'l', unitamount: 1 });
// => { id, sku, name, ... }
```