seb/dashlibstorage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
796f6a32724ff2b937617644300a5f386b657f0f
dashlibstorage/API.article.md
seb 796f6a3272 u
2026-10-16 12:35:07 +02:00

690 lines
21 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.addChild`
*Source: `src/store/article/addChild.js`*
Adds a child article to a parent article (creates and attaches with auto-generated SKU).
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `parentSku` | `string` | The parent article SKU. |
| `options` | `object` | |
| `[options.attach=false]` | `boolean` | If true, attaches an existing article instead of creating. |
| `[options.attributeValueId]` | `number` | Existing attribute value ID for parent's attribute. |
| `[options.value]` | `string` | String value to find or create under parent's attribute. |
| `[options.name]` | `string` | Custom name for child article (defaults to parent name + value). |
| `[options.unitamount]` | `number` | Optional unitamount override. |
| `[options.weight]` | `number` | Optional weight override. |
| `[options.track_stock]` | `boolean|number` | Optional track_stock override. |
| `[tx]` | `object` | Optional transaction. |
**Returns**
`Promise<object>` — The created child article detail.
## `article.addImage`
*Source: `src/store/article/addImage.js`*
Adds an image to an article by its SKU, processing full, thumb, and 32px-edge small-thumb 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. |
| `[tx]` | `object` | Optional transaction to run within. |
**Returns**
`Promise<{picId: number, sort: number, full: {w: number, h: number, size: number}, thumb: {w: number, h: number}, smallThumb: {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 }, smallThumb: { w, h }, fullHash, thumbHash }
```
## `article.attachChild`
*Source: `src/store/article/attachChild.js`*
Attaches an existing article as a child to a parent article.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `parentSku` | `string` | The parent article SKU. |
| `options` | `object` | |
| `options.sku` | `string` | The child article SKU to attach. |
| `[options.childSku]` | `string` | Alias for options.sku. |
| `[options.attributeValueId]` | `number` | Existing attribute value ID for parent's attribute. |
| `[options.value]` | `string` | String value to find or create under parent's attribute. |
| `[options.reparent=false]` | `boolean` | Whether to allow re-parenting if child belongs to another parent. |
| `[options.unitamount]` | `number` | Optional unitamount override. |
| `[options.weight]` | `number` | Optional weight override. |
| `[options.track_stock]` | `boolean|number` | Optional track_stock override. |
| `[tx]` | `object` | Optional transaction. |
**Returns**
`Promise<{article: object, children: Array<object>}>`
## `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. |
| `[input.desc]` | `string` | The article description text/HTML. |
| `[input.seo]` | `string` | The article SEO text. |
| `[input.track_stock=false]` | `boolean|number` | Whether inventory stock is tracked. |
| `[tx]` | `object` | Optional transaction to run within. |
**Returns**
`Promise<{id: number, parentId: number, name: string, sku: string, track_stock: boolean}>` — The created article.
**Example**
```js
const article = await store.article.createUnderParent({ googleAuthId: 42, parentId: 5, name: 'Cola' });
// => { id, parentId, name, sku, track_stock }
```
## `article.delete`
*Source: `src/store/article/delete.js`*
Deletes an article by its SKU, refusing when it still has children unless cascade is true.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The article SKU. |
| `[optionsOrTx]` | `object|*` | Options object ({ cascade?: boolean }) or optional transaction. |
| `[maybeTx]` | `object` | Optional transaction if options was passed. |
**Returns**
`Promise<void>`
**Throws**
`Error` — If the article has children (when cascade=false) or is not found.
**Example**
```js
await store.article.delete(42, 'SKU-1');
await store.article.delete(42, 'SKU-1', { cascade: true });
```
## `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. |
| `[tx]` | `object` | Optional transaction. |
**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. |
| `[tx]` | `object` | Optional transaction. |
**Returns**
`Promise<{article: {id: number, sku: string, name: string, slug: string, desc: string|null, seo: string|null, unitamount: number|null, weight: number|null, track_stock: boolean, unit: {si: string|null, basesi: string|null, basesifactor: number|null, symbol: string|null, name: string|null}, brand: {id: number|null, name: string, fullHash: string|null, thumbW: number|null, thumbH: number|null, thumbHash: string|null}|null, categoryIds: number[], photos: Array<{sort: number, fullHash: string, fullW: number, fullH: number, fullSize: number, thumbW: number, thumbH: number, thumbHash: string}>, eans: string[], prices: Array<{minmultiplier: number, net: number, taxRate: number, customergroupId: number}>, suppliers: Array<{id: number, articleId: number, entityId: number, supplierName: string|null, sku: string|null, pu: number, stock: number|null, sort: number, price: {net: number, taxId: number, taxRate?: number}|null}>, optionsCount: number, articleListCount: number, childCount: number, parentArticleId: number|null, parentSku: string|null}}>` — 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. |
| `[opts]` | `object` | Optional options. |
| `[opts.limit]` | `number` | Maximum number of entries to return (newest first). |
| `[tx]` | `object` | Optional transaction. |
**Returns**
`Promise<Array<{id: number, companyuserId: number|null, date: string, text: string, meta: string|null}>>` — The article history entries.
**Example**
```js
const history = await store.article.getHistoryBySku(42, 'SKU-1');
// => [{ id, companyuserId, date, text, meta }]
const recent = await store.article.getHistoryBySku(42, 'SKU-1', { limit: 5 });
// => up to 5 most recent entries
```
## `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 `parentSku` 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'` (parent/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[].track_stock=false]` | `boolean|number` | Whether inventory stock is tracked. |
| `[input.rows[].parentSku]` | `string` | The parent article SKU for a V/K compound link. |
| `[input.rows[].deposit]` | `number|string` | The deposit (Pfand) value; currently ignored. |
| `[tx]` | `object` | Optional transaction. |
**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'], parentSku: '42001190' },
{ sku: '42001190', name: '420Strainz', vk: 'V', parentCategory: 'Flowers | CBN', brand: 'Seedstockers', net: '0,00', tax: 19 },
],
});
// => { imported: [...], skipped: [...], errors: [...] }
```
## `article.listChildren`
*Source: `src/store/article/listChildren.js`*
Lists all children of a parent article.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `parentSku` | `string` | The parent article SKU. |
| `[tx]` | `object` | Optional transaction. |
**Returns**
`Promise<Array<{id: number, sku: string, parentsort: number, trackStock: boolean, unitamount: number, weight: number, name: string|null, slug: string|null, attributeValueId: number|null, attributeValue: string|null}>>`
## `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. |
| `[tx]` | `object` | Optional transaction. |
**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. |
| `[tx]` | `object` | Optional transaction. |
**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. |
| `[tx]` | `object` | Optional transaction to run within. |
**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.removeChild`
*Source: `src/store/article/removeChild.js`*
Removes a child article from a parent article, either by unlinking or deleting it.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `parentSku` | `string` | The parent article SKU. |
| `childSku` | `string` | The child article SKU. |
| `[options]` | `object` | |
| `[options.deleteArticle=false]` | `boolean` | Whether to delete the child article entity entirely. |
| `[options.cascade=true]` | `boolean` | Whether to cascade delete child subtrees when deleteArticle is true. |
| `[tx]` | `object` | Optional transaction. |
**Returns**
`Promise<{success: boolean, parentSku: string, childSku: string, deleted: boolean}>`
## `article.resolveUniqueSlug`
*Source: `src/store/article/resolveUniqueSlug.js`*
Resolves a company- and language-unique slug for an article. Disambiguates duplicate slugs with a numeric suffix (-2, -3, ...).
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `runner` | `object` | DB runner or tx. |
| `params` | `object` | |
| `params.companyId` | `number` | The company ID. |
| `params.languageId` | `number` | The language ID. |
| `params.name` | `string` | The article name. |
| `[params.excludeArticleId]` | `number` | Optional article ID to exclude (e.g. for updates). |
**Returns**
`Promise<string>` — The unique slug.
## `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. |
| `[tx]` | `object` | Optional transaction. |
**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). |
| `[tx]` | `object` | Optional transaction to run within. |
**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). |
| `[tx]` | `object` | Optional transaction to run within. |
**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.setParentBySku`
*Source: `src/store/article/setParentBySku.js`*
Links an article to a parent 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. |
| `parentSku` | `string|null` | The parent article SKU, or `null` to unlink. |
| `[tx]` | `object` | Optional transaction to run within. |
**Returns**
`Promise<object>` — The updated child article.
**Throws**
`Error` — If the article or parent is not found, or the link is invalid.
**Example**
```js
const article = await store.article.setParentBySku(42, '42001190-1', '42001190');
// => { id, sku, name, parentSku: '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<{net?: number, gross?: number, price?: number, taxRate?: number, tax?: number, minmultiplier?: number}>` | The price entries (net or gross, taxRate or tax percentage, minmultiplier defaults to 1). |
| `[tx]` | `object` | Optional transaction to run within. |
**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', [{ net: 10.0, taxRate: 19, minmultiplier: 1 }]);
// or with gross:
const article = await store.article.setPricesBySku(42, 'SKU-1', [{ gross: 11.9, taxRate: 19 }]);
// => { id, sku, name, ... }
```
## `article.setTrackStockBySku`
*Source: `src/store/article/setTrackStockBySku.js`*
Sets the track_stock flag of an article by its SKU.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The article SKU. |
| `trackStock` | `boolean|number` | Whether stock tracking is enabled. |
| `[tx]` | `object` | Optional transaction. |
**Returns**
`Promise<object>` — The updated article.
**Throws**
`Error` — If trackStock is invalid, article not found, or no warehouse exists when enabling.
**Example**
```js
const article = await store.article.setTrackStockBySku(42, 'SKU-1', true);
// => { id, sku, name, track_stock, ... }
```
## `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). |
| `[tx]` | `object` | Optional transaction. |
**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.toggleParent`
*Source: `src/store/article/toggleParent.js`*
Toggles an article into or out of parent mode.
**Parameters**
| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `sku` | `string` | The article SKU. |
| `options` | `object` | |
| `options.isParent` | `boolean` | Whether the article should be a parent article. |
| `[options.attributeNameId]` | `number` | The attribute name id required when enabling parent mode. |
| `[options.parentAttributeNameId]` | `number` | Alias for attributeNameId. |
| `[tx]` | `object` | Optional transaction. |
**Returns**
`Promise<object>` — The updated article detail.
## `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.desc]` | `string` | The article description text/HTML. |
| `[patch.seo]` | `string` | The article SEO text. |
| `[patch.unitSi]` | `string` | The new unit SI code. |
| `[patch.unitamount]` | `number` | The new unit amount (must be > 0). |
| `[patch.track_stock]` | `boolean|number` | Whether inventory stock is tracked. |
| `[tx]` | `object` | Optional transaction to run within. |
**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, track_stock: true });
// => { id, sku, name, ... }
```
Reference in New Issue View Git Blame Copy Permalink