dashlibstorage/README.md

libdashstore

MSSQL schema + domain API for Dash. One class, methods mirror the file path under src/store/.

mssql is a peer dependency — the host app (e.g. dashback) owns ConnectionPool and import sql from 'mssql'. libdashstore store code uses only the passed pool (no own mssql install at runtime). Scripts here (init-schema, test-api, …) use mssql from devDependencies.

import sql from 'mssql';
import LibDashStore from 'libdashstore';

const pool = await sql.connect({ /* … */ });
const client = await new LibDashStore(pool); // runs initialize() (ensure schema, no purge)

SQL lives in src/sql/<table>.js. Schema DDL: src/schema.js / import 'libdashstore/schema'.

ID fields in the JS API use camelCase …Id (DB columns stay snake_case). googleAuthId is always google_auth.id (the logged-in user), not companyuser.id.

---

Schema

Kein Migrations-Code: Wir gehen von einer frischen DB aus (npm run reset-db). Schema nur in src/schema.js; Anpassungen an einer laufenden DB manuell per sqlcmd, nicht im Repo.

Method	Description
initialize()	Runs all SCHEMA_SCRIPTS (IF NOT EXISTS). Does not purge.
purge()	Drops all known tables + number procedure.

---

company

Method	Signature	Returns
create	({ iso639, name, taxrate, reducedtaxrate, googleAuthId })	{ id, rootCategoryId, languageId, taxrateId, reducedtaxrateId, taxfreerateId, posCustomerGroupId }
update	(id, { iso639, name, taxrate, reducedtaxrate })	{ id, rootCategoryId, languageId, taxrateId, reducedtaxrateId, taxfreerateId }
delete	(companyId)	void
list	(googleAuthId)	{ id, name, rootCategoryId, languageId, taxrate, reducedtaxrate, taxfreerate }[]

create (transaction)

For POST /api/company:

1. Fails if name is taken (Company name not available)
2. Ensures language by iso639 (get or create)
3. Ensures tax rows for taxrate, reducedtaxrate, and 0 → taxfreerateId
4. Creates root category (parentId = null)
5. Creates POS customergroup (name POS), then inserts company with poscustomergroup_id (NOT NULL), then links the group via customergroup.company_id
6. Links creator as companyuser (googleAuthId → company_id)

company.poscustomergroup_id is required (POS pricing in getTreeForCompany / category articles). Circular FK with customergroup.company_id: the group is inserted first with company_id null, then linked after the company row exists.

list

Returns only companies where googleAuthId has a companyuser row.

update (transaction)

For PATCH /api/company/:id:

1. Fails if company missing / name taken by another company
2. Ensures lang + tax rates
3. Updates name, default_language_id, taxrate, reducedtaxrate
   (taxfreerateId / root category unchanged)

---

google_auth

Method	Signature	Returns
add	(email)	id
getByEmail	(email)	{ id, email, picture, pictureBinary, sub, createdAt, selectedCompanyId } | undefined
getById	(googleAuthId)	{ id, email, picture, pictureBinary, sub, createdAt, selectedCompanyId } | undefined
listAllowedEmails	()	{ id, email, picture, sub, createdAt, selectedCompanyId }[] (no pictureBinary)
removeAllowedEmail	(email)	void
setSelectedCompany	(googleAuthId, companyId)	void
setProfile	(googleAuthId, { picture?: string | null, pictureBinary?: Buffer | null, sub?: string | null })	void

picture is the Google profile image URL (kept for change detection / re-fetch). picturebinary stores the downloaded image bytes (pictureBinary in JS, Buffer from mssql). sub is Google’s stable subject id (unique when set). setProfile overwrites picture, pictureBinary, and sub (pass null to clear). Non-Buffer pictureBinary → Invalid pictureBinary. Errors: User not found.

Backend mapping:

• Login: getByEmail(email) then download payload.picture → setProfile(id, { picture, pictureBinary, sub })
• /auth/me: getById(googleAuthId) → base64-encode pictureBinary for the response
• CLI user manager: listAllowedEmails() / removeAllowedEmail(email) / add(email)
• PUT /api/auth/selected-company: setSelectedCompany(googleAuthId, companyId)

---

companyuser

Method	Signature	Returns
add	(companyId, googleAuthId)	id
getByEmail	(email)	id[]
delete	(id)	void

---

lang

Method	Signature	Returns
create	(iso639)	id
getByIso639	(iso639)	{ id, iso639 } | undefined
ensure	(iso639, tx?)	id
list	()	{ id, iso639 }[]
delete	(id)	void

---

tax

Method	Signature	Returns
create	(rate)	id
getByRate	(rate)	{ id, rate } | undefined
ensure	(rate, tx?)	id
list	()	{ id, rate }[]

---

unit

Method	Signature	Returns
list	(googleAuthId, companyId)	{ si, basesi, basesifactor, symbol, name }[]
upsert	(googleAuthId, companyId, { si, basesi, basesifactor, symbol, name })	{ si, basesi, basesifactor, symbol, name }
delete	(googleAuthId, companyId, si)	void

Shape (überall):

{ si, basesi, basesifactor, symbol, name }

symbol / name come from unittext in the company default language (LEFT JOIN; missing → null). Sorted by symbol, name, si. Units are company-scoped (unit.company_id); Unique is (company_id, si).

list

Auth via resolveCompanyAccess (like getTreeForCompany). Returns only units of that company. Errors: Company not found, Not authorized.

upsert

Match key (companyId, si). Inserts unit + unittext, or updates basesi / basesifactor and upserts unittext for the company language. basesifactor must be finite and > 0. Errors: Company not found, Not authorized, Invalid unit.

Default article unit pc is ensured per company on article create (with unittext symbol/name pc / Piece for the company language).

delete

Deletes the unit for (companyId, si). Blocked by FK if any article still references it (Unit in use). Missing → Unit not found. Errors: Company not found, Not authorized, Unit not found, Unit in use.

---

companysetting

Company-scoped key/value settings. Auth via resolveCompanyAccess.

Method	Signature	Returns
list	(googleAuthId, companyId, { frontendOnly? })	{ key, value, frontend }[]
get	(googleAuthId, companyId, key, { frontendOnly? })	{ key, value, frontend } | undefined
set	(googleAuthId, companyId, { key, value, frontend? })	{ key, value, frontend }
delete	(googleAuthId, companyId, key)	void

• value is always a string (NVARCHAR(MAX)).
• frontend: true → readable by frontend routes (frontendOnly: true). Default on set is false (backend-only).
• With frontendOnly: true, backend-only keys are omitted / get returns undefined (no leak via error type beyond missing).

Errors: Company not found, Not authorized, Invalid setting, Setting not found.

---

brand

Company-scoped brands. Auth via resolveCompanyAccess.

Method	Signature	Returns
list	(googleAuthId, companyId)	{ id, name, gsprpinfo }[]
upsert	(googleAuthId, companyId, { name, gsprpinfo? })	{ id, name, gsprpinfo }
delete	(googleAuthId, companyId, id)	void

brand.company_id NOT NULL, unique (company_id, name). upsert matches by (companyId, name). delete blocked by FK if any article references it (Brand in use). Errors: Company not found, Not authorized, Invalid brand, Brand not found, Brand in use.

---

customergroup

Company-scoped customer groups. Auth via resolveCompanyAccess.

Method	Signature	Returns
list	(googleAuthId, companyId)	{ id, name }[]
create	(googleAuthId, companyId, { name })	{ id, name }
update	(googleAuthId, companyId, id, { name })	{ id, name }
delete	(googleAuthId, companyId, id)	void

Empty name → Name required. Deleting the POS group (or any group still referenced with NO ACTION) → Customer group in use. Cascades entities when the group is deleted. Errors: Company not found, Not authorized, Name required, Customer group not found, Customer group in use.

---

entity

Entities belong to a customergroup of the company. Auth via resolveCompanyAccess.

Method	Signature	Returns
list	(googleAuthId, companyId, { customergroupId?, role? })	Entity[]
getById	(googleAuthId, companyId, id)	Entity
create	(googleAuthId, companyId, { customergroupId, name, firstName? })	Entity
update	(googleAuthId, companyId, id, { name?, firstName? })	Entity
delete	(googleAuthId, companyId, id)	void

type Entity = {
  id: number,
  customergroupId: number,
  firstName: string | null,
  name: string,
  createdAt: Date,
  updatedAt: Date,
}

list optional filters: customergroupId (must belong to the company), or role: 'customer' (entities whose customergroup name is not Lieferanten and not POS — for quote/order pickers). role wins over customergroupId when both are set. Unknown role → Invalid role.

create / update write entityhistory (Erstellt, or name/firstName change lines). customergroupId must belong to the company. Errors: Company not found, Not authorized, Name required, Customer group not found, Entity not found, Invalid role.

---

entityaddress

Addresses for an entity. Auth via company + entity ownership.

Method	Signature	Returns
list	(googleAuthId, companyId, entityId)	EntityAddress[]
create	(googleAuthId, companyId, entityId, { addressType, firstName?, name?, street?, streetNumber?, zip?, city?, county?, sort? })	EntityAddress
update	(googleAuthId, companyId, entityId, id, patch)	EntityAddress
delete	(googleAuthId, companyId, entityId, id)	void

addressType required. sort defaults to next index for the entity (0…n). List ordered by sort, id. Errors: Company not found, Not authorized, Entity not found, Address type required, Address not found, Invalid sort.

---

entitycontact

Contacts for an entity (contactType e.g. email, phone). Auth via company + entity ownership.

Method	Signature	Returns
list	(googleAuthId, companyId, entityId)	{ id, entityId, contactType, contact, sort }[]
create	(googleAuthId, companyId, entityId, { contactType, contact, sort? })	row
update	(googleAuthId, companyId, entityId, id, { contactType?, contact?, sort? })	row
delete	(googleAuthId, companyId, entityId, id)	void

sort defaults to next index for the entity. List ordered by sort, id. Errors: Company not found, Not authorized, Entity not found, Contact required, Contact not found, Invalid sort.

---

supplier

Suppliers are entity rows in the company customergroup named Lieferanten (created implicitly on first supplier). Auth via resolveCompanyAccess.

Method	Signature	Returns
list	(googleAuthId, companyId)	{ id, name, createdAt, updatedAt }[]
create	(googleAuthId, companyId, { name })	{ id, name, createdAt, updatedAt }
update	(googleAuthId, companyId, id, { name })	{ id, name, createdAt, updatedAt }
delete	(googleAuthId, companyId, id)	void

create ensures customergroup Lieferanten for the company, inserts entity (name only; first_name null), writes entityhistory (Erstellt) with the auth companyuser_id. update renames and writes Name geändert von "…" auf "…" when the name actually changes; bumps updated_at. Empty name → Name required. delete removes the entity (entityhistory cascades; manifest.entity_id set null). Errors: Company not found, Not authorized, Name required, Supplier not found.

---

delivery

Company-scoped goods receipts on manifest / manifestarticle with fixed type = 'delivery'. Auth via resolveCompanyAccess. manifest.company_id scopes the list (ON DELETE NO ACTION — avoid SQL Server multiple cascade paths with entity_id).

Method	Signature	Returns
list	(googleAuthId, companyId)	DeliverySummary[]
getById	(googleAuthId, companyId, id)	Delivery
create	(googleAuthId, companyId, { number, date, supplierId?, lines })	Delivery
update	(googleAuthId, companyId, id, { number?, date?, supplierId?, lines? })	Delivery
delete	(googleAuthId, companyId, id)	void

type DeliverySummary = {
  id: number,
  number: string,
  type: 'delivery',
  supplierId: number | null,   // manifest.entity_id
  date: Date,
}

type DeliveryLine = {
  id: number,
  articleId: number | null,
  sku: string | null,
  amount: number,
  net: number,
  rebate: number,
  tax: number,                 // tax.rate
  comment: string | null,
}

type Delivery = DeliverySummary & { lines: DeliveryLine[] }

create inserts header + lines in one transaction. supplierId null or a Lieferanten entity of the company (else Supplier not found). Each line requires sku (resolved in the company category tree → Article not found), amount, net, tax (rate → tax.ensure); rebate defaults 0. Empty/invalid number or date → Invalid delivery; bad line payload → Invalid lines.

update patches header fields that are present. If lines is present, replace-all lines; if omitted, leave lines unchanged. Returns full Delivery.

delete removes the manifest (manifestarticle cascades). Errors: Company not found, Not authorized, Delivery not found, Supplier not found, Article not found, Invalid delivery, Invalid lines.

---

quote

Company-scoped quotes on manifest / manifestarticle with fixed type = 'quote'. Auth via resolveCompanyAccess. Same line shape as delivery (no transactedAmount — ledger owns movements). manifest.date is the document date; HTTP/OpenAPI may describe it as valid-until.

Method	Signature	Returns
list	(googleAuthId, companyId)	QuoteSummary[]
getById	(googleAuthId, companyId, id)	Quote
create	(googleAuthId, companyId, { number, date, entityId?, lines })	Quote
update	(googleAuthId, companyId, id, { number?, date?, entityId?, lines? })	Quote
delete	(googleAuthId, companyId, id)	void

type QuoteSummary = {
  id: number,
  number: string,
  type: 'quote',
  entityId: number | null,   // manifest.entity_id — customer
  date: Date,
}

type ManifestLine = {
  id: number,
  articleId: number | null,
  sku: string | null,
  amount: number,
  net: number,
  rebate: number,
  tax: number,                 // tax.rate
  comment: string | null,
}

type Quote = QuoteSummary & { lines: ManifestLine[] }

entityId null or a company entity whose customergroup is not named Lieferanten or POS (else Entity not found). Lines: sku (category tree → Article not found), amount, net, tax (tax.ensure); rebate defaults 0. Empty/invalid number or date → Invalid quote; bad lines → Invalid lines.

update: present fields only; lines present → replace-all. delete cascades lines. Errors: Company not found, Not authorized, Quote not found, Entity not found, Article not found, Invalid quote, Invalid lines.

---

order

Company-scoped orders on manifest / manifestarticle with fixed type = 'order'. Same API shape as quote (entityId customer, not Lieferanten/POS). manifest.date may be documented as expected delivery in HTTP docs.

Method	Signature	Returns
list	(googleAuthId, companyId)	OrderSummary[]
getById	(googleAuthId, companyId, id)	Order
create	(googleAuthId, companyId, { number, date, entityId?, lines })	Order
update	(googleAuthId, companyId, id, { number?, date?, entityId?, lines? })	Order
delete	(googleAuthId, companyId, id)	void

type OrderSummary = {
  id: number,
  number: string,
  type: 'order',
  entityId: number | null,
  date: Date,
}

type Order = OrderSummary & { lines: ManifestLine[] }  // ManifestLine as in quote

Errors: Company not found, Not authorized, Order not found, Entity not found, Article not found, Invalid order, Invalid lines.

---

ledger

Append-only SQL Server ledger table (WITH (LEDGER = ON (APPEND_ONLY = ON))). Rows cannot be updated or deleted. References manifestarticle with ON DELETE NO ACTION (a line with ledger entries cannot be removed). No store API yet — INSERT only via future store methods / direct SQL.

Column	Type	Notes
id	INT IDENTITY	PK
manifestarticle_id	INT	FK → manifestarticle
transaction_type	NVARCHAR(100)
amount	FLOAT
transaction_text	NVARCHAR(MAX)
hash_version	INT	hash algorithm / payload version
prev_hash	NVARCHAR(128)	nullable (genesis row)

Engine also maintains ledger_start_transaction_id / ledger_start_sequence_number. purge/reset-db soft-drops the table (MSSQL_DroppedLedgerTable_* remains; a new ledger can still be created).

---

posterminal

Company-scoped POS terminals. Auth via resolveCompanyAccess.

Method	Signature	Returns
list	(googleAuthId, companyId)	{ id, name, token, pairingpin }[]
upsert	(googleAuthId, companyId, { id?, name, token?, pairingpin })	{ id, name, token, pairingpin }
delete	(googleAuthId, companyId, id)	void
setOn	(googleAuthId, companyId, posterminalId, categoryId)	{ id, categoryIds[] }
setOff	(googleAuthId, companyId, posterminalId, categoryId)	{ id, categoryIds[] }
setOnAll	(googleAuthId, companyId, posterminalId)	{ id, categoryIds[] }
setOffAll	(googleAuthId, companyId, posterminalId)	{ id, categoryIds[] }
getCategoryPosterminalIds	(companyId)	{ [categoryId]: posterminalId[] } (internal, used by category tree)

posterminal.company_id NOT NULL. name is required. token is nullable and unique (pairing code assigned during setup). pairingpin is required.

upsert: if id is provided, updates the existing posterminal (must belong to company); otherwise creates a new one. Errors: Company not found, Not authorized, Invalid posterminal, Posterminal not found.

setOn / setOff: toggle a single category's visibility on a single terminal. setOn inserts the row (idempotent — no error if already present); setOff deletes it (idempotent). Both return the updated categoryIds for that terminal. Errors: Company not found, Not authorized, Posterminal not found, Invalid posterminal or category.

setOnAll / setOffAll: toggle all company categories on a single terminal. setOnAll walks the company's category tree and inserts any missing links; setOffAll removes all category links for the terminal. Both return the updated categoryIds for that terminal. Errors: Company not found, Not authorized, Posterminal not found, Invalid posterminal.

delete cascades to posterminalcategory. Errors: Company not found, Not authorized, Posterminal not found.

Category tree integration

getTreeForCompany returns a posterminalIds array on each tree node — the list of posterminal ids (of the current company) for which that category is visible. A category with an empty posterminalIds array is visible on all terminals (or has no terminal-specific filtering).

---

category

Method	Signature	Returns
createUnderParent	({ googleAuthId, parentId, name })	{ id, parentId, sort, name, slug }
rename	({ googleAuthId, id, name })	{ id, name, slug }
move	({ googleAuthId, id, parentId })	{ id, parentId, sort }
order	({ googleAuthId, parentId, categoryIds })	{ categoryIds }
delete	({ googleAuthId, id })	void — Category has children if child categories remain; FK categoryarticle also blocks deletion
getTreeForCompany	(googleAuthId, companyId)	{ languageId, tree, articles } — tree rows carry name + slug
getCategoryArticles	(googleAuthId, categoryId)	{ id, sku, name, slug, net, taxRate, optionsCount, articleListCount, childCount, fatherArticleId, fatherSku, fullHash, thumbW, thumbH, thumbHash }[]
addImage	(googleAuthId, categoryId, imageBuffer)	{ id, thumbW, thumbH, thumbHash }
deleteImage	(googleAuthId, categoryId)	{ id, thumbW: null, thumbH: null, thumbHash: null }

createUnderParent (transaction)

1. parentId exists, else Parent not found
2. Walk ancestors to root; find company with root_category_id = root
3. companyuser for (googleAuthId, companyId), else Not authorized
4. Insert category (next sibling sort) + categorytext (name, slugified slug, company default language); returns { id, parentId, sort, name, slug }

getTreeForCompany throws Not authorized if googleAuthId is not a companyuser of companyId, and Company not found if the company is missing, has no root_category_id, or no default_language_id.

rename updates the categorytext name (and re-slugifies slug) for the category in the company default language. Empty name → Name required. Auth via resolveCategoryAccess on the category (Parent not found / Not authorized). Missing text row → Category not found. Returns { id, name, slug }. For PATCH /api/category/:id.

order reorders the direct children of parentId to the given categoryIds order (each child's sort set to its index 0..n-1). Since a category can have multiple parents, parentId scopes which sibling list is reordered. categoryIds must be exactly the current children of parentId (same set, no dups) else Invalid category order. Auth via resolveCategoryAccess on parentId. Returns { categoryIds }. For PUT /api/category/order.

move moves a category to a new parent. Both id (source) and parentId (target) are validated via resolveCategoryAccess — the target must be a real category of the same authorized company, else Parent not found. Moving into itself or into a descendant (cycle) → Invalid parent. The moved category gets the next sibling sort under the new parent. Returns { id, parentId, sort }. For POST /api/category/:id/move.

addImage accepts a full-size AVIF Buffer. Full image: if already AVIF and ≤1000×1000, stored as-is; otherwise scaled to max 1000×1000 (pic.fullbinary). Thumb always scaled to max 200×200 (pic.thumbbinary) via sharp. Assigns random fullHash (pic.hash, unique), computes thumbhash, links categorypic. Auth via resolveCategoryAccess. Errors: Category not found, Not authorized.

addImage returns:

{
  id,           // category id
  thumbW,       // thumb width
  thumbH,       // thumb height
  thumbHash,    // base64 thumbhash of thumb preview
}

deleteImage removes all categorypic rows for the category. Returns { id, thumbW: null, thumbH: null, thumbHash: null }. Errors: Category not found, Image not found, Not authorized.

---

article

Method	Signature	Returns
listSearchIndex	(googleAuthId: string, companyId: number)	SearchIndexEntry[] (see below)
listExport	(googleAuthId: string, companyId: number, categoryId?: number)	ArticleExportEntry[] (see below)
createUnderParent	({ googleAuthId: string, parentId: number, name: string })	{ id: number, parentId: number, name: string, sku: string }
getBySku	(googleAuthId: string, sku: string)	ArticleDetail (see below)
getHistoryBySku	(googleAuthId: string, sku: string)	{ id: number, companyuserId: number | null, date: Date, text: string }[]
updateBySku	(googleAuthId: string, sku: string, { name?: string, unitamount?: number, unitSi?: string })	ArticleDetail
setPricesBySku	(googleAuthId: string, sku: string, PriceInput[])	ArticleDetail
setEansBySku	(googleAuthId: string, sku: string, string[])	ArticleDetail
setBrandIdBySku	(googleAuthId: string, sku: string, number | null)	ArticleDetail
setWeightBySku	(googleAuthId: string, sku: string, number)	ArticleDetail
setCategoryIdsBySku	(googleAuthId: string, sku: string, number[])	ArticleDetail
addImage	(googleAuthId: string, sku: string, Buffer)	ImageResult (see below)
deleteImage	(googleAuthId: string, sku: string, fullHash: string)	void
orderImages	(googleAuthId: string, sku: string, { fullHashes: string[] })	{ fullHashes: string[] }
delete	(googleAuthId: string, sku: string)	void

addImage accepts a full-size AVIF Buffer. Full image: if already AVIF and ≤1000×1000, stored as-is; otherwise scaled to max 1000×1000 (pic.fullbinary). Thumb always scaled to max 200×200 (pic.thumbbinary) via sharp. Assigns random fullHash (pic.hash, unique), computes thumbhash, links articlepic. Auth like getBySku. Errors: Article not found, Not authorized.

addImage returns ImageResult:

{
  picId: number,
  sort: number,
  full: { w: number, h: number, size: number },   // AVIF, max 1000×1000
  thumb: { w: number, h: number },                  // scaled AVIF, max 200×200
  fullHash: string,                                 // random 64-char hex, unique
  thumbHash: string,                                // base64 thumbhash of thumb
}

listSearchIndex returns every article in the company (reachable via the category tree). Designed for client-side search / autocomplete preload. Auth via resolveCompanyAccess. Errors: Company not found, Not authorized.

type SearchIndexEntry = {
  id: number,
  sku: string,
  name: string | null,            // null when articletext row is missing
  eans: string[],                 // all EANs, empty array when none
  categoryIds: number[],          // all category ids, at least one
}

listExport returns articles in a category subtree (root = company when categoryId omitted). categoryId must be reachable via the selected company's root category (else Not authorized). Auth via resolveCompanyAccess + resolveCategoryAccess. Errors: Company not found, Parent not found, Not authorized.

type ArticleExportEntry = {
  id: number,
  sku: string,
  name: string | null,            // null when articletext row is missing
  slug: string | null,
  unitSi: string | null,
  unitSymbol: string | null,
  unitamount: number,
  brandName: string | null,
  net: number | null,             // null when no POS price
  taxRate: number | null,         // null when no POS price
  eans: string[],                 // all EANs, empty array when none
  categoryIds: number[],          // all category ids, at least one
  categoryBreadcrumbs: string[],  // one middot-separated breadcrumb ("Home·Cat·Sub") per category
  fullHashes: string[],           // all photo fullHashes in sort order, empty when none
}

getBySku / updateBySku / setPricesBySku / setEansBySku / setBrandIdBySku / setWeightBySku / setCategoryIdsBySku all return ArticleDetail:

type ArticleDetail = {
  id: number,
  sku: string,
  name: string | null,            // null when articletext row is missing
  slug: string | null,
  unitamount: number,
  weight: number,
  unit: {
    si: string,                   // e.g. "pc"
    basesi: string,               // e.g. "pc"
    basesifactor: number,         // e.g. 1
    symbol: string | null,        // e.g. "Stk", null when unittext missing
    name: string | null,          // e.g. "Stück", null when unittext missing
  },
  brand: {
    name: string,
    thumbW: number,
    thumbH: number,
    thumbHash: string,
  } | null,                       // null when no brand assigned
  categoryIds: number[],          // at least one
  photos: {
    sort: number,
    fullHash: string,
    thumbW: number,
    thumbH: number,
    thumbHash: string,
  }[],                            // empty array when no photos
  eans: string[],                 // empty array when none
  prices: PriceEntry[],           // empty array when none
  optionsCount: number,           // 0 when no optionslist
  articleListCount: number,       // 0 when no articlelist
  childCount: number,             // 0 when no children
  fatherArticleId: number | null, // null when root article
  fatherSku: string | null,       // null when root article
}

type PriceEntry = {
  minmultiplier: number,
  net: number,
  taxRate: number,
  customergroupId: number,
}

getCategoryArticles / getTreeForCompany().articles[] return a flat list shape (net, taxRate, single fullHash/thumbW/thumbH/thumbHash).

parentId is the category id. Creates article + articletext (company default language) + categoryarticle in one transaction. Allocates sku via getnextnumberwithprefixandpadding (type sku; creates numbers row with empty prefix if missing). Default unit pc is ensured if missing (unitamount 1, weight 0). Auth via resolveCategoryAccess(googleAuthId, parentId) — Parent not found / Not authorized.

Auth via the article's categoryarticle category + resolveCategoryAccess. Errors: Article not found, Not authorized.

updateBySku patches article fields in a transaction. At least one of name, unitamount, unitSi required. name → articletext (slugified slug); empty name → Name required. unitSi → existing unit.si lookup (no silent ensure); unknown → Unit not found. unitamount must be finite and > 0 → Invalid unitamount. When name and/or unit (unitamount/unitSi) actually change, inserts one articlehistory row in the same transaction with companyuser_id set to the auth user (text lines joined by newline), e.g. Name geändert von "Alt" auf "Neu" / Einheit geändert von "500g" auf "1kg" (label = unitamount + unittext.symbol, fallback unit.si). Returns ArticleDetail. Errors: Article not found, Not authorized, Name required, Unit not found, Invalid unitamount.

getHistoryBySku returns articlehistory for the article, newest first (date DESC, id DESC). companyuserId is null when the user was deleted (ON DELETE SET NULL). Auth like getBySku. Errors: Article not found, Not authorized.

setPricesBySku replaces all price rows for the article’s company poscustomergroup_id in one transaction. Each entry: price → net, tax → tax rate (ensured via tax.ensure), minmultiplier defaults to 1. Empty array clears all POS prices. Returns ArticleDetail. Errors: Article not found, Not authorized, POS customer group required, Invalid prices.

setEansBySku replaces all articleean rows for the article in one transaction (replace-all semantics). EANs must be non-empty unique strings; empty array clears all EANs. Returns ArticleDetail (whose eans reflects the new list). Errors: Article not found, Not authorized, Invalid eans.

setBrandIdBySku sets the article’s brand_id. Pass null to clear the brand. Requires the brand to belong to the article’s company (else Brand not found). Non-null must be a finite id. Errors: Article not found, Not authorized, Brand not found.

setWeightBySku sets the article’s weight. Must be finite and >= 0 (else Invalid weight). Errors: Article not found, Not authorized, Invalid weight.

setCategoryIdsBySku replaces the article’s category list (categoryarticle) in one transaction. Each category must belong to the article’s company and ids must be unique (else Invalid categoryIds); empty array is rejected — an article must have at least one category (else Article must have at least one category). Returns ArticleDetail (whose categoryIds reflects the new list). Errors: Article not found, Not authorized, Invalid categoryIds, Article must have at least one category.

deleteImage removes articlepic and the pic row for this article (fullHash). Errors: Article not found, Image not found, Not authorized.

orderImages sets articlepic.sort to 0..n-1 in the given order. fullHashes must list every image of the article exactly once. Errors: Article not found, Invalid image order, Not authorized.

delete removes the article when it has no child articles (fatherarticle_id FK is ON DELETE NO ACTION). Cascades: articlehistory, articleean, categoryarticle, price, articletext, articlelistarticle, optionslistarticle, articlepic; deletes linked pic rows and owned articlelist / optionslist. manifestarticle.article_id is set to NULL and comment gets article <name> deleted appended. Errors: Article not found, Article has children, Not authorized.

---

pic

Lookup by pic.hash (fullHash from addImage.fullHash), not thumbhash. Random 64-char hex (crypto.randomBytes(32)), unique in DB.

Method	Signature	Returns
getImageByHash	(googleAuthId, fullHash)	{ buffer, w, h, size, contentType }
getThumbByHash	(googleAuthId, fullHash)	{ buffer, w, h, contentType }

Auth via articlepic → categoryarticle → resolveCategoryAccess. Errors: Image not found, Not authorized.

contentType is always image/avif.

// GET /api/image/:fullHash
const { buffer, contentType } = await store.pic.getImageByHash(req.user.id, fullHash);
res.set('Content-Type', contentType).send(buffer);

// GET /api/thumb/:fullHash
const thumb = await store.pic.getThumbByHash(req.user.id, fullHash);
res.set('Content-Type', thumb.contentType).send(thumb.buffer);

---

Backend route cheatsheet

Route	Store call
POST /api/company	company.create({ iso639, name, taxrate, reducedtaxrate, googleAuthId })
GET /api/company	company.list(googleAuthId)
PATCH /api/company/:id	company.update(id, { iso639, name, taxrate, reducedtaxrate })
DELETE /api/company/:id	company.delete(id)
PUT /api/auth/selected-company	google_auth.setSelectedCompany(googleAuthId, companyId)
GET /api/category/tree	category.getTreeForCompany(googleAuthId, companyId)
GET /api/category/export.zip	category.getTreeForCompany(googleAuthId, companyId) + pic.getImageByHash
POST /api/category	category.createUnderParent({ googleAuthId, parentId, name })
PATCH /api/category/:id	category.rename({ googleAuthId, id, name })
PUT /api/category/order	category.order({ googleAuthId, parentId, categoryIds })
POST /api/category/:id/move	category.move({ googleAuthId, id, parentId })
DELETE /api/category/:id	category.delete({ googleAuthId, id })
POST /api/category/:id/image	category.addImage(googleAuthId, categoryId, imageBuffer)
DELETE /api/category/:id/image	category.deleteImage(googleAuthId, categoryId)
GET /api/unit	unit.list(googleAuthId, companyId)
PUT /api/unit	unit.upsert(googleAuthId, companyId, { si, basesi, basesifactor, symbol, name })
DELETE /api/unit	unit.delete(googleAuthId, companyId, si)
GET /api/company/:id/settings	companysetting.list(googleAuthId, companyId, { frontendOnly: true })
PUT /api/company/:id/settings	companysetting.set(googleAuthId, companyId, { key, value, frontend? })
DELETE /api/company/:id/settings/:key	companysetting.delete(googleAuthId, companyId, key)
GET /api/brand	brand.list(googleAuthId, companyId)
PUT /api/brand	brand.upsert(googleAuthId, companyId, { name, gsprpinfo? })
DELETE /api/brand/:id	brand.delete(googleAuthId, companyId, id)
GET /api/customergroup	customergroup.list(googleAuthId, companyId)
POST /api/customergroup	customergroup.create(googleAuthId, companyId, { name })
PATCH /api/customergroup/:id	customergroup.update(googleAuthId, companyId, id, { name })
DELETE /api/customergroup/:id	customergroup.delete(googleAuthId, companyId, id)
GET /api/entity	entity.list(googleAuthId, companyId, { customergroupId?, role? })
GET /api/entity/:id	entity.getById(googleAuthId, companyId, id)
POST /api/entity	entity.create(googleAuthId, companyId, { customergroupId, name, firstName? })
PATCH /api/entity/:id	entity.update(googleAuthId, companyId, id, { name?, firstName? })
DELETE /api/entity/:id	entity.delete(googleAuthId, companyId, id)
GET /api/entity/:entityId/address	entityaddress.list(googleAuthId, companyId, entityId)
POST /api/entity/:entityId/address	entityaddress.create(googleAuthId, companyId, entityId, { addressType, … })
PATCH /api/entity/:entityId/address/:id	entityaddress.update(googleAuthId, companyId, entityId, id, patch)
DELETE /api/entity/:entityId/address/:id	entityaddress.delete(googleAuthId, companyId, entityId, id)
GET /api/entity/:entityId/contact	entitycontact.list(googleAuthId, companyId, entityId)
POST /api/entity/:entityId/contact	entitycontact.create(googleAuthId, companyId, entityId, { contactType, contact })
PATCH /api/entity/:entityId/contact/:id	entitycontact.update(googleAuthId, companyId, entityId, id, patch)
DELETE /api/entity/:entityId/contact/:id	entitycontact.delete(googleAuthId, companyId, entityId, id)
GET /api/supplier	supplier.list(googleAuthId, companyId)
POST /api/supplier	supplier.create(googleAuthId, companyId, { name })
PATCH /api/supplier/:id	supplier.update(googleAuthId, companyId, id, { name })
DELETE /api/supplier/:id	supplier.delete(googleAuthId, companyId, id)
GET /api/delivery	delivery.list(googleAuthId, companyId)
GET /api/delivery/:id	delivery.getById(googleAuthId, companyId, id)
POST /api/delivery	delivery.create(googleAuthId, companyId, { number, date, supplierId?, lines })
PATCH /api/delivery/:id	delivery.update(googleAuthId, companyId, id, { number?, date?, supplierId?, lines? })
DELETE /api/delivery/:id	delivery.delete(googleAuthId, companyId, id)
GET /api/quote	quote.list(googleAuthId, companyId)
GET /api/quote/:id	quote.getById(googleAuthId, companyId, id)
POST /api/quote	quote.create(googleAuthId, companyId, { number, date, entityId?, lines })
PATCH /api/quote/:id	quote.update(googleAuthId, companyId, id, { number?, date?, entityId?, lines? })
DELETE /api/quote/:id	quote.delete(googleAuthId, companyId, id)
GET /api/order	order.list(googleAuthId, companyId)
GET /api/order/:id	order.getById(googleAuthId, companyId, id)
POST /api/order	order.create(googleAuthId, companyId, { number, date, entityId?, lines })
PATCH /api/order/:id	order.update(googleAuthId, companyId, id, { number?, date?, entityId?, lines? })
DELETE /api/order/:id	order.delete(googleAuthId, companyId, id)
GET /api/posterminal	posterminal.list(googleAuthId, companyId)
PUT /api/posterminal	posterminal.upsert(googleAuthId, companyId, { id?, name, token?, pairingpin })
DELETE /api/posterminal/:id	posterminal.delete(googleAuthId, companyId, id)
PUT /api/posterminal/:id/category/:categoryId	posterminal.setOn(googleAuthId, companyId, id, categoryId)
DELETE /api/posterminal/:id/category/:categoryId	posterminal.setOff(googleAuthId, companyId, id, categoryId)
PUT /api/posterminal/:id/categories	posterminal.setOnAll(googleAuthId, companyId, id)
DELETE /api/posterminal/:id/categories	posterminal.setOffAll(googleAuthId, companyId, id)
POST /api/article	article.createUnderParent({ googleAuthId, parentId, name })
GET /api/article/:sku	article.getBySku(googleAuthId, sku)
GET /api/article/:sku/history	article.getHistoryBySku(googleAuthId, sku)
GET /api/articleIndex	article.listSearchIndex(googleAuthId, companyId)
GET /api/article/export.zip	article.listExport(googleAuthId, companyId, categoryId?)
PATCH /api/article/:sku	article.updateBySku(googleAuthId, sku, { name?, unitamount?, unitSi? })
PUT /api/article/:sku/prices	article.setPricesBySku(googleAuthId, sku, [{ price, tax, minmultiplier? }])
PUT /api/article/:sku/eans	article.setEansBySku(googleAuthId, sku, string[])
PUT /api/article/:sku/brand	article.setBrandIdBySku(googleAuthId, sku, brandId | null)
PUT /api/article/:sku/weight	article.setWeightBySku(googleAuthId, sku, weight)
PUT /api/article/:sku/categories	article.setCategoryIdsBySku(googleAuthId, sku, number[])
DELETE /api/article/:sku	article.delete(googleAuthId, sku)
POST /api/article/:sku/image	article.addImage(googleAuthId, sku, imageBuffer)
DELETE /api/article/:sku/image/:fullHash	article.deleteImage(googleAuthId, sku, fullHash)
PUT /api/article/:sku/images/order	article.orderImages(googleAuthId, sku, { fullHashes })
GET /api/image/:fullHash	pic.getImageByHash(googleAuthId, fullHash)
GET /api/thumb/:fullHash	pic.getThumbByHash(googleAuthId, fullHash)

---

Scripts

npm run purge-db      # drop all tables + procedure (wipe data)
npm run reset-db      # purge + init-schema (empty DB, fresh schema)
npm run init-schema   # ensure schema only (does NOT delete data)
npm run test:api      # interactive API tester
npm run schema-graph  # regenerate schema-graph.svg

Env: MSSQL_SERVER, MSSQL_DATABASE, MSSQL_USER, MSSQL_PASSWORD.