docs: add JSDoc headers to all externally exported store functions

src/store/article/addImage.js

@@ -5,6 +5,17 @@ import newFullHash from '../../util/newFullHash.js';
 import request from '../request.js';
 import resolveArticleBySku from './resolveArticleBySku.js';
 
+/**
+ * Adds an image to an article by its SKU, processing it into AVIF variants.
+ *
+ * @param {object} pool - The mssql connection pool.
+ * @returns {Function} An async function that adds an article image.
+ *
+ * @example
+ * const fn = addImage(pool);
+ * const result = await fn(42, 'SKU-1', imageBuffer);
+ * // => { picId, sort, full: { w, h, size }, thumb: { w, h }, fullHash, thumbHash }
+ */
 export default function addImage(pool) {
   const resolve = resolveArticleBySku(pool);
 

src/store/article/createUnderParent.js

@@ -7,6 +7,18 @@ import nextSku from '../numbers/nextSku.js';
 import request from '../request.js';
 import slugify from '../slugify.js';
 
+/**
+ * Creates a new article under a given parent category, allocating a SKU and
+ * a default unit.
+ *
+ * @param {object} pool - The mssql connection pool.
+ * @returns {Function} An async function that creates an article.
+ *
+ * @example
+ * const fn = createUnderParent(pool);
+ * const article = await fn({ googleAuthId: 42, parentId: 5, name: 'Cola' });
+ * // => { id, parentId, name, sku }
+ */
 export default function createUnderParent(pool) {
   const access = resolveCategoryAccess(pool);
   const ensureUnit = ensureDefaultUnit(pool);

src/store/article/delete.js

@@ -11,6 +11,16 @@ import {
 import resolveArticleBySku from './resolveArticleBySku.js';
 import request from '../request.js';
 
+/**
+ * Deletes an article by its SKU, refusing when it still has children.
+ *
+ * @param {object} pool - The mssql connection pool.
+ * @returns {Function} An async function that deletes an article.
+ *
+ * @example
+ * const fn = del(pool);
+ * await fn(42, 'SKU-1');
+ */
 export default function del(pool) {
   const resolve = resolveArticleBySku(pool);
 

src/store/article/deleteImage.js

@@ -1,6 +1,16 @@
 import { DELETE_BY_ARTICLE_AND_HASH } from '../../sql/pic.js';
 import resolveArticleBySku from './resolveArticleBySku.js';
 
+/**
+ * Deletes an image from an article by its SKU and full image hash.
+ *
+ * @param {object} pool - The mssql connection pool.
+ * @returns {Function} An async function that deletes an article image.
+ *
+ * @example
+ * const fn = deleteImage(pool);
+ * await fn(42, 'SKU-1', 'abc123');
+ */
 export default function deleteImage(pool) {
   const resolve = resolveArticleBySku(pool);
 

src/store/article/getBySku.js

@@ -6,6 +6,18 @@ function parseJsonArray(raw) {
   return Array.isArray(arr) ? arr : [];
 }
 
+/**
+ * Returns the full detail of an article by its SKU, including unit, brand,
+ * categories, photos, EANs and prices.
+ *
+ * @param {object} pool - The mssql connection pool.
+ * @returns {Function} An async function that fetches an article by SKU.
+ *
+ * @example
+ * const fn = getBySku(pool);
+ * const article = await fn(42, 'SKU-1');
+ * // => { article: { id, sku, name, unit, brand, categoryIds, photos, eans, prices, ... } }
+ */
 export default function getBySku(pool) {
   return async (googleAuthId, sku) => {
     const t0 = performance.now();

src/store/article/getHistoryBySku.js

@@ -1,6 +1,17 @@
 import { LIST_BY_ARTICLE_ID } from '../../sql/articlehistory.js';
 import resolveArticleBySku from './resolveArticleBySku.js';
 
+/**
+ * Returns the change history of an article by its SKU.
+ *
+ * @param {object} pool - The mssql connection pool.
+ * @returns {Function} An async function that fetches the article history.
+ *
+ * @example
+ * const fn = getHistoryBySku(pool);
+ * const history = await fn(42, 'SKU-1');
+ * // => [{ id, companyuserId, date, text }]
+ */
 export default function getHistoryBySku(pool) {
   const resolve = resolveArticleBySku(pool);
 

src/store/article/listExport.js

@@ -10,6 +10,18 @@ function parseJsonArray(raw) {
   return Array.isArray(arr) ? arr : [];
 }
 
+/**
+ * Returns articles for export, optionally scoped to a category, including
+ * category breadcrumbs and image hashes.
+ *
+ * @param {object} pool - The mssql connection pool.
+ * @returns {Function} An async function that lists articles for export.
+ *
+ * @example
+ * const fn = listExport(pool);
+ * const articles = await fn(42, 1, null);
+ * // => [{ id, sku, name, slug, unitSi, net, taxRate, eans, categoryBreadcrumbs, fullHashes, ... }]
+ */
 export default function listExport(pool) {
   const companyAccess = resolveCompanyAccess(pool);
   const categoryAccess = resolveCategoryAccess(pool);

src/store/article/listSearchIndex.js

@@ -1,6 +1,17 @@
 import { SEARCH_ARTICLES } from '../../sql/article.js';
 import resolveCompanyAccess from '../companyuser/resolveCompanyAccess.js';
 
+/**
+ * Returns a lightweight search index of all articles for a company.
+ *
+ * @param {object} pool - The mssql connection pool.
+ * @returns {Function} An async function that lists the article search index.
+ *
+ * @example
+ * const fn = listSearchIndex(pool);
+ * const articles = await fn(42, 1);
+ * // => [{ id, sku, name, eans, categoryIds }]
+ */
 export default function listSearchIndex(pool) {
   const access = resolveCompanyAccess(pool);
 

src/store/article/orderImages.js

@@ -6,6 +6,17 @@ import {
 import resolveArticleBySku from './resolveArticleBySku.js';
 import request from '../request.js';
 
+/**
+ * Reorders the images of an article by its SKU.
+ *
+ * @param {object} pool - The mssql connection pool.
+ * @returns {Function} An async function that reorders article images.
+ *
+ * @example
+ * const fn = orderImages(pool);
+ * const result = await fn(42, 'SKU-1', { fullHashes: ['a', 'b'] });
+ * // => { fullHashes: ['a', 'b'] }
+ */
 export default function orderImages(pool) {
   const resolve = resolveArticleBySku(pool);
 

src/store/article/setBrandIdBySku.js

@@ -5,6 +5,17 @@ import {
 import queryBySku from './queryBySku.js';
 import resolveArticleBySku from './resolveArticleBySku.js';
 
+/**
+ * Sets (or clears) the brand of an article by its SKU.
+ *
+ * @param {object} pool - The mssql connection pool.
+ * @returns {Function} An async function that sets the article brand.
+ *
+ * @example
+ * const fn = setBrandIdBySku(pool);
+ * const article = await fn(42, 'SKU-1', 3);
+ * // => { id, sku, name, ... }
+ */
 export default function setBrandIdBySku(pool) {
   const resolve = resolveArticleBySku(pool);
   const load = queryBySku(pool);

src/store/article/setCategoryIdsBySku.js

@@ -7,6 +7,17 @@ import resolveCategoryAccess from '../category/resolveCategoryAccess.js';
 import queryBySku from './queryBySku.js';
 import resolveArticleBySku from './resolveArticleBySku.js';
 
+/**
+ * Replaces the category membership of an article by its SKU.
+ *
+ * @param {object} pool - The mssql connection pool.
+ * @returns {Function} An async function that sets the article categories.
+ *
+ * @example
+ * const fn = setCategoryIdsBySku(pool);
+ * const article = await fn(42, 'SKU-1', [5, 9]);
+ * // => { id, sku, name, ... }
+ */
 export default function setCategoryIdsBySku(pool) {
   const resolve = resolveArticleBySku(pool);
   const categoryAccess = resolveCategoryAccess(pool);

src/store/article/setEansBySku.js

@@ -6,6 +6,17 @@ import request from '../request.js';
 import queryBySku from './queryBySku.js';
 import resolveArticleBySku from './resolveArticleBySku.js';
 
+/**
+ * Replaces the EAN list of an article by its SKU.
+ *
+ * @param {object} pool - The mssql connection pool.
+ * @returns {Function} An async function that sets article EANs.
+ *
+ * @example
+ * const fn = setEansBySku(pool);
+ * const article = await fn(42, 'SKU-1', ['4001234567890']);
+ * // => { id, sku, name, ... }
+ */
 export default function setEansBySku(pool) {
   const resolve = resolveArticleBySku(pool);
   const load = queryBySku(pool);

src/store/article/setPricesBySku.js

@@ -42,6 +42,17 @@ function normalizePrices(prices) {
   return normalized;
 }
 
+/**
+ * Replaces the price list of an article by its SKU.
+ *
+ * @param {object} pool - The mssql connection pool.
+ * @returns {Function} An async function that sets article prices.
+ *
+ * @example
+ * const fn = setPricesBySku(pool);
+ * const article = await fn(42, 'SKU-1', [{ price: 1.5, tax: 19, minmultiplier: 1 }]);
+ * // => { id, sku, name, ... }
+ */
 export default function setPricesBySku(pool) {
   const resolve = resolveArticleBySku(pool);
   const ensureTax = taxEnsure(pool);

src/store/article/setWeightBySku.js

@@ -2,6 +2,17 @@ import { UPDATE_WEIGHT } from '../../sql/article.js';
 import queryBySku from './queryBySku.js';
 import resolveArticleBySku from './resolveArticleBySku.js';
 
+/**
+ * Sets the weight of an article by its SKU.
+ *
+ * @param {object} pool - The mssql connection pool.
+ * @returns {Function} An async function that sets the article weight.
+ *
+ * @example
+ * const fn = setWeightBySku(pool);
+ * const article = await fn(42, 'SKU-1', 1.5);
+ * // => { id, sku, name, ... }
+ */
 export default function setWeightBySku(pool) {
   const resolve = resolveArticleBySku(pool);
   const load = queryBySku(pool);

src/store/article/updateBySku.js

@@ -20,6 +20,17 @@ function formatUnitLabel(amount, symbol) {
   return `${Number(amount)}${sym}`;
 }
 
+/**
+ * Updates an article's name and/or unit (SI and amount), recording history.
+ *
+ * @param {object} pool - The mssql connection pool.
+ * @returns {Function} An async function that updates an article by SKU.
+ *
+ * @example
+ * const fn = updateBySku(pool);
+ * const article = await fn(42, 'SKU-1', { name: 'Cola 1L', unitSi: 'l', unitamount: 1 });
+ * // => { id, sku, name, ... }
+ */
 export default function updateBySku(pool) {
   const resolve = resolveArticleBySku(pool);
   const load = queryBySku(pool);