seb/dashlibstorage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
af416246b421ee11f69fefa7c23ea6ced53fc131
dashlibstorage/API.article.md
seb af416246b4 feat(article): add article import with V/K compound linking 
Add article.importRows to create articles by SKU from CSV-style rows,
running in two passes so fatherSku links to rows later in the file still
resolve. Existing SKUs are skipped, duplicate EANs are dropped, prices and
taxes are ensured, brands are upserted by name, and parent categories are
resolved/created via breadcrumb path.

Also add:
- article.setFatherBySku to link/unlink a child to its father article
- category.ensureByPath to resolve or create categories by path (tx-aware)
- supporting SQL constants (GET_ID_BY_SKU, EAN_EXISTS, father-link helpers,
  GET_BY_PARENT_AND_NAME)
- regenerated API docs
2026-08-11 05:36:07 +02:00

491 lines
13 KiB
Markdown
Raw Blame History

# article
This document is auto-generated from the JSDoc comments in `src/store` by running `npm run api-doc`.
## `article.addImage`
*Source: `src/store/article/addImage.js`*
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 result = await store.article.addImage(42, 'SKU-1', imageBuffer);
// => { picId, sort, full: { w, h, size }, thumb: { w, h }, fullHash, thumbHash }
```
## `article.createUnderParent`
*Source: `src/store/article/createUnderParent.js`*
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 article = await store.article.createUnderParent({ googleAuthId: 42, parentId: 5, name: 'Cola' });
// => { id, parentId, name, sku }
```
## `article.delete`
*Source: `src/store/article/delete.js`*
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
await store.article.delete(42, 'SKU-1');
```
## `article.deleteImage`
*Source: `src/store/article/deleteImage.js`*
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
await store.article.deleteImage(42, 'SKU-1', 'abc123');
```
## `article.getBySku`
*Source: `src/store/article/getBySku.js`*
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 article = await store.article.getBySku(42, 'SKU-1');
// => { article: { id, sku, name, unit, brand, categoryIds, photos, eans, prices, ... } }
```
## `article.getHistoryBySku`
*Source: `src/store/article/getHistoryBySku.js`*
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 history = await store.article.getHistoryBySku(42, 'SKU-1');
// => [{ id, companyuserId, date, text }]
```
## `article.importRows`
*Source: `src/store/article/importRows.js`*
Imports article rows, creating articles by their SKU and returning per-row import, skip and error outcomes. The import runs in **two passes** so a `fatherSku` that references a row appearing later in the file still resolves. A row is **skipped** when its SKU already exists in the company (upsert mode is not applied), and an EAN is skipped when already used by another row.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `input` | `object` | The import input. |
| `input.googleAuthId` | `number` | The id of the Google auth user. |
| `input.rows` | `Array<object>` | The article rows to import. |
| `input.rows[].sku` | `string` | The article SKU. |
| `input.rows[].name` | `string` | The article name. |
| `[input.rows[].vk]` | `string` | `'V'` (father/compound) or `'K'` (variant) marker. |
| `[input.rows[].parentId]` | `number|string` | The id of the parent category. |
| `[input.rows[].parentCategory]` | `string` | The category breadcrumb path, e.g. `'Flowers | CBN'`. |
| `[input.rows[].brand]` | `string` | The brand name to upsert. |
| `[input.rows[].net]` | `number|string` | The POS net price (accepts German decimals). |
| `[input.rows[].tax]` | `number|string` | The tax rate in percent (e.g. `19`). |
| `[input.rows[].eans]` | `Array<string>|string` | The EANs to set. |
| `[input.rows[].fatherSku]` | `string` | The father article SKU for a V/K compound link. |
| `[input.rows[].deposit]` | `number|string` | The deposit (Pfand) value; currently ignored. |
**Returns**
`Promise<{imported: Array<object>, skipped: Array<object>, errors: Array<object>}>` — The import outcome.
**Example**
```js
const result = await store.article.importRows({
googleAuthId: 42,
rows: [
{ sku: '42001190-1', name: '420Strainz 1g', vk: 'K', parentCategory: 'Flowers | CBN', brand: 'Seedstockers', net: '11,00', tax: 19, eans: ['4262557690455'], fatherSku: '42001190' },
{ sku: '42001190', name: '420Strainz', vk: 'V', parentCategory: 'Flowers | CBN', brand: 'Seedstockers', net: '0,00', tax: 19 },
],
});
// => { imported: [...], skipped: [...], errors: [...] }
```
## `article.listExport`
*Source: `src/store/article/listExport.js`*
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 articles = await store.article.listExport(42, null);
// => [{ id, sku, name, slug, unitSi, net, taxRate, eans, categoryBreadcrumbs, fullHashes, ... }]
```
## `article.listSearchIndex`
*Source: `src/store/article/listSearchIndex.js`*
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 articles = await store.article.listSearchIndex(42);
// => [{ id, sku, name, eans, categoryIds }]
```
## `article.orderImages`
*Source: `src/store/article/orderImages.js`*
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 result = await store.article.orderImages(42, 'SKU-1', { fullHashes: ['a', 'b'] });
// => { fullHashes: ['a', 'b'] }
```
## `article.setBrandIdBySku`
*Source: `src/store/article/setBrandIdBySku.js`*
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 article = await store.article.setBrandIdBySku(42, 'SKU-1', 3);
// => { id, sku, name, ... }
```
## `article.setCategoryIdsBySku`
*Source: `src/store/article/setCategoryIdsBySku.js`*
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 article = await store.article.setCategoryIdsBySku(42, 'SKU-1', [5, 9]);
// => { id, sku, name, ... }
```
## `article.setEansBySku`
*Source: `src/store/article/setEansBySku.js`*
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 article = await store.article.setEansBySku(42, 'SKU-1', ['4001234567890']);
// => { id, sku, name, ... }
```
## `article.setFatherBySku`
*Source: `src/store/article/setFatherBySku.js`*
Links an article to a father article (V/K compound) by their SKUs.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The child article SKU. |
| `fatherSku` | `string|null` | The father article SKU, or `null` to unlink. |
**Returns**
`Promise<object>` — The updated child article.
**Throws**
`Error` — If the article or father is not found, or the link is invalid.
**Example**
```js
const article = await store.article.setFatherBySku(42, '42001190-1', '42001190');
// => { id, sku, name, fatherSku: '42001190', ... }
```
## `article.setPricesBySku`
*Source: `src/store/article/setPricesBySku.js`*
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 article = await store.article.setPricesBySku(42, 'SKU-1', [{ price: 1.5, tax: 19, minmultiplier: 1 }]);
// => { id, sku, name, ... }
```
## `article.setWeightBySku`
*Source: `src/store/article/setWeightBySku.js`*
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 article = await store.article.setWeightBySku(42, 'SKU-1', 1.5);
// => { id, sku, name, ... }
```
## `article.updateBySku`
*Source: `src/store/article/updateBySku.js`*
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 article = await store.article.updateBySku(42, 'SKU-1', { name: 'Cola 1L', unitSi: 'l', unitamount: 1 });
// => { id, sku, name, ... }
```
Reference in New Issue View Git Blame Copy Permalink