@kreiseck/kasseneck-api 1.5.1 → 1.7.0

package/dist/esm/inventory/index.js

@@ -2,7 +2,8 @@
  * `@kreiseck/kasseneck-api/inventory` – die Lager-API: Artikel, Standorte,
  * Bestand und Lagerprotokoll lesen, Konto-Webhooks verwalten und eingehende
  * Zustellungen pruefen (Backend Stufe 5a); Artikel anlegen und aendern,
- * Bestand buchen und Ware reservieren (Stufe 5b, seit 1.5.0).
+ * Bestand buchen und Ware reservieren (Stufe 5b, seit 1.5.0);
+ * Variantengruppen (Stufe 5c, seit 1.6.0).
  *
  * Ein eigener Unterpfad wie `invoice`: der `api_key` eines Kontos gehoert auf
  * einen **Server** (etwa das Backend eines Online-Shops) und soll nicht
@@ -16,5 +17,6 @@ export { inventoryKeyAuth } from './auth.js';
 export { isInventoryError, isInventoryErrorCode, inventoryErrorCode, inventoryFieldErrors, inventoryRetryAfterSec, inventoryShortfalls, isInventoryWarningCode, } from './fehler.js';
 export { createWebhook, deleteWebhook, getArticle, getStock, iterateArticles, iterateStock, iterateStockMovements, listArticles, listLocations, listStock, listStockMovements, listWebhookDeliveries, listWebhooks, lookupArticleByCode, rotateWebhookSecret, sendWebhookTest, updateWebhook, } from './endpunkte.js';
 export { changeStockCondition, createArticle, createReservation, deactivateArticle, extendReservation, getReservation, iterateReservations, listReservations, previewGoodsReceipt, receiveGoods, recordStockLoss, releaseReservation, reverseStockMovement, transferStock, updateArticle, } from './schreiben.js';
+export { addVariant, createVariantGroup, getVariantGroup, iterateVariantGroups, listVariantGroups, updateVariantGroup, } from './varianten.js';
 export { verifyInventoryWebhookSignature, parseInventoryWebhookEvent, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_TOLERANCE_SEC, } from './webhook.js';
-export { INVENTORY_ENDPOINTS, INVENTORY_ERROR_CODES, INVENTORY_REQUEST_ERROR_CODES, INVENTORY_WEBHOOK_EVENTS, INVENTORY_WEBHOOK_ENVELOPE_FIELDS, INVENTORY_WEBHOOK_LIMIT, INVENTORY_LIST_LIMIT_MAX, LOCATION_TYPES, STOCK_MOVEMENT_TYPES, STOCK_MOVEMENT_SOURCES, STOCK_CONDITIONS, STOCK_CHANGE_CAUSES, WEBHOOK_DELIVERY_STATUSES, INVENTORY_WARNING_CODES, STOCK_KINDS, STOCK_LOSS_REASONS, WITHDRAWAL_TYPES, LANDED_COST_TYPES, LANDED_COST_ALLOCATIONS, RESERVATION_STATUSES, INVENTORY_IDEMPOTENCY_KEY_MAX, RESERVATION_MINUTES_MIN, RESERVATION_MINUTES_MAX, } from './vertrag.js';
+export { INVENTORY_ENDPOINTS, INVENTORY_ERROR_CODES, INVENTORY_REQUEST_ERROR_CODES, INVENTORY_WEBHOOK_EVENTS, INVENTORY_WEBHOOK_ENVELOPE_FIELDS, INVENTORY_WEBHOOK_LIMIT, INVENTORY_LIST_LIMIT_MAX, LOCATION_TYPES, STOCK_MOVEMENT_TYPES, STOCK_MOVEMENT_SOURCES, STOCK_CONDITIONS, STOCK_CHANGE_CAUSES, WEBHOOK_DELIVERY_STATUSES, INVENTORY_WARNING_CODES, STOCK_KINDS, STOCK_LOSS_REASONS, WITHDRAWAL_TYPES, LANDED_COST_TYPES, LANDED_COST_ALLOCATIONS, RESERVATION_STATUSES, INVENTORY_IDEMPOTENCY_KEY_MAX, RESERVATION_MINUTES_MIN, RESERVATION_MINUTES_MAX, VARIANT_ATTRIBUTES_MAX, VARIANT_VALUES_MAX, VARIANT_MATRIX_MAX, VARIANT_GROUP_ACTIVE_MAX, } from './vertrag.js';

package/dist/esm/inventory/lesen.d.ts

@@ -12,7 +12,7 @@
  * wenn der Server sie sendet: „fehlt“ heisst dort „kein Recht“, nicht „leer“.
  */
 import { KasseneckValidationError } from '../client/errors.js';
-import type { Article, GoodsReceiptPreviewLine, InventoryShortfall, InventoryWebhook, InventoryWebhookDelivery, InventoryWebhookTestDelivery, Location, Reservation, StockBelowMinimumEventData, StockChangedEventData, StockLevel, StockMovement, StockOperation, StockValue } from './typen.js';
+import type { Article, GoodsReceiptPreviewLine, InventoryShortfall, InventoryWebhook, InventoryWebhookDelivery, InventoryWebhookTestDelivery, Location, Reservation, StockBelowMinimumEventData, StockChangedEventData, StockLevel, StockMovement, StockOperation, StockValue, VariantGroup } from './typen.js';
 type Roh = Record<string, unknown>;
 /** Ein Leser bekommt den Vorgang (fuer die Meldung) und den Pfad im Rumpf. */
 export interface Ort {
@@ -38,6 +38,12 @@ export declare function vorschauZeile(ort: Ort, w: unknown): GoodsReceiptPreview
 export declare function reservierung(ort: Ort, w: unknown): Reservation;
 /** Die fehlenden Positionen aus `insufficient_available` (`data.details[]`); ein kaputter Eintrag faellt weg. */
 export declare function fehlmengen(roh: unknown): InventoryShortfall[];
+/**
+ * Eine Variantengruppe. `attributes` und `variants` sind zugesagte Listen:
+ * fehlen sie, ist die Antwort kaputt (eine leere Liste hiesse „keine Merkmale“
+ * bzw. „keine Varianten“).
+ */
+export declare function variantengruppe(ort: Ort, w: unknown): VariantGroup;
 /** Eine zugesagte Liste `data.<feld>`, Eintrag fuer Eintrag gelesen. */
 export declare function liste<T>(name: string, daten: unknown, feld: string, lesen: (ort: Ort, e: unknown) => T): T[];
 /** Der Cursor der naechsten Seite; `null` am Ende. Etwas anderes als Text oder `null` ist kaputt. */

package/dist/esm/inventory/lesen.js

@@ -381,6 +381,80 @@ export function fehlmengen(roh) {
     }
     return raus;
 }
+// ---- Varianten (Stufe 5c) ------------------------------------------------------------
+/** Eine Liste von Texten (Werte eines Merkmals); etwas anderes ist kaputt. */
+function textliste(ort, feld, w) {
+    if (!Array.isArray(w) || !w.every((x) => typeof x === 'string')) {
+        throw antwortfehler(ort.name, `Antwort ist unbrauchbar (data.${ort.pfad}.${feld} ist keine Liste von Texten)`);
+    }
+    return [...w];
+}
+function merkmal(ort, w) {
+    const m = eintrag(ort, w);
+    return { key: kennung(ort, 'key', m.key), label: typeof m.label === 'string' ? m.label : '', values: textliste(ort, 'values', m.values) };
+}
+/**
+ * Vorgaben einer Gruppe: nur die Felder, die der Server sendet. Ein Preis als
+ * Bruchzahl ist kaputt (er fuellte sonst jede neue Variante falsch), ein Feld
+ * mit fremdem Typ ebenso.
+ */
+function vorgaben(ort, w) {
+    if (w === undefined || w === null)
+        return {};
+    const v = objekt(w);
+    const vOrt = { name: ort.name, pfad: `${ort.pfad}.defaults` };
+    if (!v)
+        throw antwortfehler(ort.name, `Antwort ist unbrauchbar (data.${vOrt.pfad} ist kein Objekt)`);
+    const raus = {};
+    if (v.unitPriceCents !== undefined && v.unitPriceCents !== null)
+        raus.unitPriceCents = ganzzahl(vOrt, 'unitPriceCents', v.unitPriceCents);
+    if (v.vatRate !== undefined && v.vatRate !== null) {
+        if (typeof v.vatRate !== 'number' || !Number.isFinite(v.vatRate))
+            throw antwortfehler(ort.name, `Antwort enthaelt keinen USt-Satz (data.${vOrt.pfad}.vatRate)`);
+        raus.vatRate = v.vatRate;
+    }
+    for (const feld of ['unit', 'groupId']) {
+        const t = v[feld];
+        if (t === undefined || t === null)
+            continue;
+        if (typeof t !== 'string')
+            throw antwortfehler(ort.name, `Antwort ist unbrauchbar (data.${vOrt.pfad}.${feld} ist kein Text)`);
+        raus[feld] = t;
+    }
+    if (v.stockTracked !== undefined && v.stockTracked !== null) {
+        if (typeof v.stockTracked !== 'boolean')
+            throw antwortfehler(ort.name, `Antwort ist unbrauchbar (data.${vOrt.pfad}.stockTracked ist kein Wahrheitswert)`);
+        raus.stockTracked = v.stockTracked;
+    }
+    return raus;
+}
+function mitglied(ort, w) {
+    const x = eintrag(ort, w);
+    return { articleId: kennung(ort, 'articleId', x.articleId), variantAttributes: textAbbildung(x.variantAttributes) ?? {} };
+}
+/**
+ * Eine Variantengruppe. `attributes` und `variants` sind zugesagte Listen:
+ * fehlen sie, ist die Antwort kaputt (eine leere Liste hiesse „keine Merkmale“
+ * bzw. „keine Varianten“).
+ */
+export function variantengruppe(ort, w) {
+    const g = eintrag(ort, w);
+    for (const feld of ['attributes', 'variants']) {
+        if (!Array.isArray(g[feld]))
+            throw antwortfehler(ort.name, `Antwort ist unbrauchbar (data.${ort.pfad}.${feld} ist keine Liste)`);
+    }
+    const unter = (feld, i) => ({ name: ort.name, pfad: `${ort.pfad}.${feld}[${i}]` });
+    return {
+        id: kennung(ort, 'id', g.id),
+        name: text(g.name),
+        attributes: g.attributes.map((m, i) => merkmal(unter('attributes', i), m)),
+        defaults: vorgaben(ort, g.defaults),
+        active: g.active !== false,
+        variants: g.variants.map((x, i) => mitglied(unter('variants', i), x)),
+        createdAt: text(g.createdAt),
+        updatedAt: text(g.updatedAt),
+    };
+}
 // ---- Listen ------------------------------------------------------------------
 /** Eine zugesagte Liste `data.<feld>`, Eintrag fuer Eintrag gelesen. */
 export function liste(name, daten, feld, lesen) {

package/dist/esm/inventory/schreiben.d.ts

@@ -27,8 +27,29 @@
  * unlesbare Antwort) `outcome: 'unknown'`, nie `'rejected'`. Lesen und der
  * Probelauf (`previewGoodsReceipt`) bleiben `'rejected'`.
  */
-import type { InternerTransport } from '../client/aufrufe.js';
+import type { ApiCall, InternerTransport } from '../client/aufrufe.js';
 import type { Article, ChangeStockConditionRequest, CreateArticleRequest, CreateReservationRequest, DeactivateArticleRequest, ExtendReservationRequest, GoodsReceiptPreview, GoodsReceiptPreviewRequest, ReceiveGoodsRequest, RecordStockLossRequest, ReleaseReservationRequest, Reservation, ReservationListQuery, ReservationPage, ReverseStockMovementRequest, StockOperation, TransferStockRequest, UpdateArticleRequest } from './typen.js';
+type Params = Record<string, unknown>;
+/** Die Anfrage als flache Kopie ohne `undefined`; der Aufrufer behaelt sein Objekt. Paketintern, auch fuer `varianten.ts`. */
+export declare function anfrage(name: ApiCall, request: unknown): Params;
+/**
+ * `idempotencyKey`: Text mit 1–120 Zeichen, nicht nur Leerraum. Er wird nie
+ * getrimmt oder gekuerzt: ein veraenderter Schluessel waere ein anderer.
+ */
+export declare function schluessel(name: ApiCall, p: Params, { pflicht }: {
+    pflicht: boolean;
+}): void;
+/** Eine Ganzzahl (Tausendstel, Cent, Mikro-Euro); fehlt sie, nur wenn sie darf. `null` nur, wo es leert. */
+export declare function ganz(name: ApiCall, feld: string, w: unknown, { pflicht, leerbar }?: {
+    pflicht?: boolean | undefined;
+    leerbar?: boolean | undefined;
+}): void;
+/**
+ * Zahlenfelder eines Artikels; `null` leert sie (bzw. heisst bei der Anlage
+ * „nicht angegeben“). `praefix` nennt die Stelle in der Anfrage (`variants[2].`).
+ */
+export declare function artikelZahlen(name: ApiCall, p: Params, praefix?: string): void;
+export declare const artikelAus: (name: ApiCall, daten: unknown) => Article;
 /**
  * Legt einen Artikel an. Mit `ean` ein Fremdartikel mit diesem Code (gueltige
  * Pruefziffer, frei im Konto), sonst vergibt der Server den naechsten eigenen
@@ -84,3 +105,4 @@ export declare function getReservation(transport: InternerTransport, reservation
 export declare function listReservations(transport: InternerTransport, query?: ReservationListQuery): Promise<ReservationPage>;
 /** Alle Reservierungen der Abfrage, Seite fuer Seite ueber `nextCursor`. */
 export declare function iterateReservations(transport: InternerTransport, query?: ReservationListQuery): AsyncGenerator<Reservation, void, undefined>;
+export {};

package/dist/esm/inventory/schreiben.js

@@ -31,8 +31,8 @@ import { abfrage, anfragefehler, kennung, seitenweise } from './endpunkte.js';
 import { artikel, liste, naechsterCursor, objekt, reservierung, vorgang, vorschauZeile } from './lesen.js';
 import { INVENTORY_IDEMPOTENCY_KEY_MAX, RESERVATION_MINUTES_MAX, RESERVATION_MINUTES_MIN } from './vertrag.js';
 // ---- Pruefung vor dem Senden ------------------------------------------------------
-/** Die Anfrage als flache Kopie ohne `undefined`; der Aufrufer behaelt sein Objekt. */
-function anfrage(name, request) {
+/** Die Anfrage als flache Kopie ohne `undefined`; der Aufrufer behaelt sein Objekt. Paketintern, auch fuer `varianten.ts`. */
+export function anfrage(name, request) {
     if (request === null || typeof request !== 'object' || Array.isArray(request)) {
         throw anfragefehler(name, 'Anfrage muss ein Objekt sein');
     }
@@ -46,7 +46,7 @@ function anfrage(name, request) {
  * `idempotencyKey`: Text mit 1–120 Zeichen, nicht nur Leerraum. Er wird nie
  * getrimmt oder gekuerzt: ein veraenderter Schluessel waere ein anderer.
  */
-function schluessel(name, p, { pflicht }) {
+export function schluessel(name, p, { pflicht }) {
     const w = p.idempotencyKey;
     if (w === undefined || w === null) {
         if (pflicht) {
@@ -61,7 +61,7 @@ function schluessel(name, p, { pflicht }) {
     }
 }
 /** Eine Ganzzahl (Tausendstel, Cent, Mikro-Euro); fehlt sie, nur wenn sie darf. `null` nur, wo es leert. */
-function ganz(name, feld, w, { pflicht = false, leerbar = false } = {}) {
+export function ganz(name, feld, w, { pflicht = false, leerbar = false } = {}) {
     if (w === undefined || (w === null && leerbar)) {
         if (pflicht)
             throw anfragefehler(name, `${feld} fehlt`);
@@ -107,19 +107,22 @@ function positionen(name, w, { pflicht, menge }, weiter = () => { }) {
     });
 }
 // ---- Artikel ------------------------------------------------------------------
-/** Zahlenfelder eines Artikels; `null` leert sie (bzw. heisst bei der Anlage „nicht angegeben“). */
-function artikelZahlen(name, p) {
+/**
+ * Zahlenfelder eines Artikels; `null` leert sie (bzw. heisst bei der Anlage
+ * „nicht angegeben“). `praefix` nennt die Stelle in der Anfrage (`variants[2].`).
+ */
+export function artikelZahlen(name, p, praefix = '') {
     for (const feld of ['unitPriceCents', 'minStock', 'purchasePriceMicros'])
-        ganz(name, feld, p[feld], { leerbar: true });
+        ganz(name, `${praefix}${feld}`, p[feld], { leerbar: true });
     const jeStandort = p.minStockByLocation;
     if (jeStandort === undefined || jeStandort === null)
         return;
     if (typeof jeStandort !== 'object' || Array.isArray(jeStandort))
-        throw anfragefehler(name, 'minStockByLocation muss ein Objekt { standort: Tausendstel } sein');
+        throw anfragefehler(name, `${praefix}minStockByLocation muss ein Objekt { standort: Tausendstel } sein`);
     for (const [standort, w] of Object.entries(jeStandort))
-        ganz(name, `minStockByLocation.${standort}`, w, { leerbar: true });
+        ganz(name, `${praefix}minStockByLocation.${standort}`, w, { leerbar: true });
 }
-const artikelAus = (name, daten) => artikel({ name, pfad: 'article' }, objekt(daten)?.article);
+export const artikelAus = (name, daten) => artikel({ name, pfad: 'article' }, objekt(daten)?.article);
 /**
  * Legt einen Artikel an. Mit `ean` ein Fremdartikel mit diesem Code (gueltige
  * Pruefziffer, frei im Konto), sonst vergibt der Server den naechsten eigenen

package/dist/esm/inventory/typen.d.ts

@@ -19,7 +19,7 @@ import type { InventoryWarningCode, InventoryWebhookEventType, LandedCostAllocat
  * `purchasePriceMicros` nur mit dem Recht `costs` (Konto-Schalter
  * `lagerApi.kosten`, sonst fehlt das Feld, nicht `null`), `externalIds`,
  * `metadata`, `variantGroupId` und `variantAttributes` nur, wenn der Artikel
- * sie traegt.
+ * sie traegt (eine Variante, siehe [VariantGroup]).
  */
 export interface Article {
     id: string;
@@ -59,7 +59,14 @@ export interface Article {
     active: boolean;
     externalIds?: Record<string, string>;
     metadata?: Record<string, string>;
+    /** Nur an einer Variante: die Variantengruppe. Gesetzt nur ueber `createVariantGroup`/`addVariant`, nie umgehaengt. */
     variantGroupId?: string;
+    /**
+     * Nur an einer Variante: je Merkmal der Gruppe genau ein Wert
+     * (`{ farbe: 'rot', groesse: 'S' }`). Die Schluessel kommen nach Codepunkt
+     * sortiert, nicht in der Merkmalsreihenfolge der Gruppe; die steht in
+     * [VariantGroup.attributes].
+     */
     variantAttributes?: Record<string, string>;
     createdAt: string | null;
     updatedAt: string | null;
@@ -78,6 +85,12 @@ export interface ArticleListQuery {
      */
     updatedSince?: string | Date;
     groupId?: string;
+    /**
+     * Nur die Varianten dieser Gruppe (Backend ab Stufe 5c), wie ohne Filter
+     * nach `updatedAt` aufsteigend; mit `updatedSince` der Abgleich
+     * einer Gruppe. Die Artikel einer neuen Gruppe liest man so, die Antwort von
+     * `createVariantGroup` traegt nur ihre Kennungen.
+     */
     variantGroupId?: string;
     active?: boolean;
     stockTracked?: boolean;
@@ -342,7 +355,7 @@ export interface InventoryWebhookEnvelope<T extends InventoryWebhookEventType, D
     test: boolean;
     data: D;
 }
-export type InventoryWebhookEvent = InventoryWebhookEnvelope<'stock.changed', StockChangedEventData> | InventoryWebhookEnvelope<'stock.below_minimum', StockBelowMinimumEventData> | InventoryWebhookEnvelope<'article.created', Article> | InventoryWebhookEnvelope<'article.updated', Article> | InventoryWebhookEnvelope<'article.deactivated', Article> | InventoryWebhookEnvelope<'reservation.expired', Reservation> | InventoryWebhookEnvelope<'reservation.released', Reservation> | InventoryWebhookEnvelope<'reservation.redeemed', Reservation>;
+export type InventoryWebhookEvent = InventoryWebhookEnvelope<'stock.changed', StockChangedEventData> | InventoryWebhookEnvelope<'stock.below_minimum', StockBelowMinimumEventData> | InventoryWebhookEnvelope<'article.created', Article> | InventoryWebhookEnvelope<'article.updated', Article> | InventoryWebhookEnvelope<'article.deactivated', Article> | InventoryWebhookEnvelope<'reservation.expired', Reservation> | InventoryWebhookEnvelope<'reservation.released', Reservation> | InventoryWebhookEnvelope<'reservation.redeemed', Reservation> | InventoryWebhookEnvelope<'variant_group.created', VariantGroup> | InventoryWebhookEnvelope<'variant_group.updated', VariantGroup>;
 /**
  * Die Felder eines Artikels beim Anlegen. Bei der Anlage heisst `null` „nicht
  * angegeben“ (ausser bei `name`, der Pflicht ist).
@@ -677,3 +690,144 @@ export interface InventoryShortfall {
     /** Verfuegbar (`onHand − reserved`), Tausendstel; darf negativ sein. */
     available: number;
 }
+/** Ein Merkmal einer Variantengruppe mit seinen Werten, in der Reihenfolge der Gruppe. */
+export interface VariantAttribute {
+    /** `^[a-z0-9_]{1,32}$`, eindeutig in der Gruppe; Schluessel in `variantAttributes`. */
+    key: string;
+    /** Beschriftung, 1–40 Zeichen, z. B. „Größe“. */
+    label: string;
+    /**
+     * 1–30 Werte zu je 1–30 Zeichen, eindeutig ohne Gross/Klein, getrimmt und in
+     * Unicode-NFC gespeichert. Werte kommen nur dazu (`addAttributeValues`), nie weg.
+     */
+    values: string[];
+}
+/**
+ * Vorgaben einer Gruppe: sie fuellen bei der **Anlage** einer Variante die
+ * Felder, die die Variante nicht selbst nennt. Ein spaeteres Aendern der
+ * Vorgaben aendert keine bestehende Variante (dafuer `updateArticle`).
+ * Ein Feld ohne Vorgabe fehlt.
+ */
+export interface VariantGroupDefaults {
+    unitPriceCents?: number;
+    vatRate?: number;
+    unit?: string;
+    groupId?: string;
+    /** Ohne Vorgabe gilt wie bei `createArticle` `false` (dann nicht reservierbar). */
+    stockTracked?: boolean;
+}
+/** Eine Variante in der Liste ihrer Gruppe. */
+export interface VariantGroupMember {
+    articleId: string;
+    /** Je Merkmal ein Wert, Schluessel nach Codepunkt sortiert. */
+    variantAttributes: Record<string, string>;
+}
+/**
+ * Eine Variantengruppe, wie `getVariantGroup`, `listVariantGroups`, die
+ * schreibenden Gruppenaufrufe und die Ereignisse `variant_group.*` sie senden.
+ */
+export interface VariantGroup {
+    id: string;
+    /** 1–100 Zeichen; Standardname einer Variante: „<Gruppe> <Wert1> <Wert2>“. */
+    name: string | null;
+    /** 1–3 Merkmale in der Reihenfolge der Gruppe (sie bestimmt den Standardnamen). */
+    attributes: VariantAttribute[];
+    defaults: VariantGroupDefaults;
+    /** `false` = stillgelegt: alle Varianten stillgelegt, kein `addVariant`, endgueltig. */
+    active: boolean;
+    /**
+     * Die aktiven Varianten einer aktiven Gruppe; eine einzeln stillgelegte
+     * Variante faellt heraus (ihre Kombination ist dann wieder frei). Beim
+     * Stilllegen der Gruppe wird die Liste eingefroren. Die Artikel selbst
+     * liest `listArticles({ variantGroupId })`.
+     */
+    variants: VariantGroupMember[];
+    createdAt: string | null;
+    updatedAt: string | null;
+}
+/** Vorgaben in einer Anfrage. Bei der Anlage heisst `null` „nicht angegeben“, bei einer Aenderung „leeren“. */
+export interface VariantGroupDefaultsInput {
+    unitPriceCents?: number | null;
+    vatRate?: number | null;
+    unit?: string | null;
+    /** Artikelgruppe; unbekannt = `group_not_found` (bei einer Variante mit `field: 'defaults.groupId'`). */
+    groupId?: string | null;
+    stockTracked?: boolean | null;
+}
+/**
+ * Eine neue Variante: ihre Merkmalswerte und die Felder eines Artikels wie bei
+ * `createArticle`. Was fehlt (oder `null` ist), fuellen die Vorgaben der
+ * Gruppe; ohne `name` heisst sie „<Gruppe> <Wert1> <Wert2>“ in
+ * Merkmalsreihenfolge. Mit `ean` wird sie ein Fremdartikel, sonst vergibt der
+ * Server den naechsten eigenen Code.
+ */
+export interface VariantInput extends Omit<ArticleInput, 'name'> {
+    /**
+     * Jedes Merkmal der Gruppe genau einmal, Wert exakt aus der Werteliste
+     * (Gross/Klein und Leerraum werden nicht angeglichen), sonst
+     * `invalid_variant_attributes` mit `field`.
+     */
+    variantAttributes: Record<string, string>;
+    /** 1–200 Zeichen; ohne Angabe der Standardname. */
+    name?: string | null;
+}
+/**
+ * Legt eine Variantengruppe an, mit `createMatrix: true` samt allen
+ * Kombinationen (hoechstens 100) oder mit den genannten `variants[]`
+ * (hoechstens 100), nie beides. Ohne beides entsteht die Gruppe ohne Variante.
+ * Die Antwort traegt die Gruppe mit `variants[]` (Kennungen und Merkmale),
+ * nicht die Artikel.
+ */
+export interface CreateVariantGroupRequest {
+    idempotencyKey: string;
+    /** 1–100 Zeichen. */
+    name: string;
+    /** 1–3 Merkmale; ihre Reihenfolge bestimmt Standardnamen und Matrix (das erste laeuft aussen). */
+    attributes: VariantAttribute[];
+    defaults?: VariantGroupDefaultsInput | null;
+    /** `true`: alle Kombinationen der Werte als Varianten. Schliesst `variants` aus. */
+    createMatrix?: boolean;
+    variants?: VariantInput[];
+}
+/**
+ * Aendert eine aktive Gruppe: nur die genannten Felder, mindestens eines.
+ * `defaults` ist ein Teil-Update (`null` je Feld leert es, `defaults: null`
+ * alle). `addAttributeValues` haengt Werte an bestehende Merkmale an und
+ * uebergeht still, was es schon gibt (auch in anderer Gross-/Kleinschreibung):
+ * der Shop darf immer alle seine Werte senden. Werte entfernen und Merkmale
+ * ergaenzen gibt es nicht.
+ *
+ * `active: false` legt die Gruppe und alle ihre Varianten still, steht allein
+ * und ist endgueltig (`true` gibt es nicht). Eine stillgelegte Gruppe ergibt
+ * bei jeder anderen Aenderung `variant_group_inactive`.
+ */
+export interface UpdateVariantGroupRequest {
+    idempotencyKey: string;
+    variantGroupId: string;
+    name?: string;
+    defaults?: VariantGroupDefaultsInput | null;
+    /** `{ groesse: ['XL'] }`: hoechstens 30 Werte je Merkmal danach. */
+    addAttributeValues?: Record<string, string[]>;
+    active?: false;
+}
+/** Legt eine Variante in einer aktiven Gruppe an. Antwort: der Artikel wie `createArticle`. */
+export interface AddVariantRequest extends VariantInput {
+    idempotencyKey: string;
+    variantGroupId: string;
+}
+export interface VariantGroupListQuery {
+    active?: boolean;
+    /**
+     * Nur Gruppen, die seitdem geaendert wurden (inklusive). Die Liste ist nach
+     * `updatedAt` aufsteigend sortiert, gleiche Zeit nach Kennung.
+     */
+    updatedSince?: string | Date;
+    /** 1–200, Vorgabe des Servers 50. */
+    limit?: number;
+    cursor?: string;
+}
+export interface VariantGroupPage {
+    variantGroups: VariantGroup[];
+    /** `null` = letzte Seite. */
+    nextCursor: string | null;
+}

package/dist/esm/inventory/varianten.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Variantengruppen der Lager-API (Backend Stufe 5c): Gruppe anlegen (mit
+ * Matrix oder genannten Varianten), aendern oder stilllegen, eine Variante
+ * ergaenzen, Gruppen lesen.
+ *
+ * Eine Variante ist ein gewoehnlicher Artikel mit `variantGroupId` und
+ * `variantAttributes`; gelesen, gebucht und reserviert wird sie wie jeder
+ * Artikel. Die Gruppenantworten tragen nur die Kennungen der Varianten, die
+ * Artikel selbst liefert `listArticles({ variantGroupId })`.
+ *
+ * Wie in `schreiben.ts` geht die Anfrage flach hinaus, genau mit den Feldern,
+ * die der Aufrufer nennt (`undefined` faellt weg, `null` bleibt).
+ *
+ * **Vor dem Senden geprueft wird nur, was ohne Netz sicher falsch ist:**
+ * - `idempotencyKey` fehlt, ist leer oder laenger als 120 Zeichen (die drei
+ *   schreibenden Aufrufe);
+ * - `variantGroupId` fehlt oder ist leer;
+ * - `createMatrix: true` zusammen mit `variants` (schliessen sich aus);
+ * - `variants` ist keine Liste, ein Eintrag kein Objekt, `variantAttributes`
+ *   einer Variante fehlt oder ist kein Objekt;
+ * - ein Preis, eine Menge oder ein Einkaufspreis (auch in `defaults`) ist
+ *   keine Ganzzahl;
+ * - eine Aenderung nennt kein Feld, `active` ist nicht `false` oder steht
+ *   nicht allein, `addAttributeValues` ist kein Objekt.
+ * Die Grenzen (Merkmale, Werte, Matrix, aktive Varianten) prueft der Server:
+ * er darf sie anheben, ohne dass diese Paketversion dann falsch abweist.
+ *
+ * **Wiederholen** wie bei jedem Schreiben: nach `outcome: 'unknown'` denselben
+ * Aufruf mit **demselben** `idempotencyKey`; er wirkt genau einmal und liefert
+ * die gespeicherte Antwort. Ein neuer Schluessel legte die Gruppe ein zweites
+ * Mal an. Ein abgebrochenes Stilllegen vollendet jede Wiederholung von
+ * `updateVariantGroup({ active: false })`, auch mit neuem Schluessel.
+ */
+import type { InternerTransport } from '../client/aufrufe.js';
+import type { AddVariantRequest, Article, CreateVariantGroupRequest, UpdateVariantGroupRequest, VariantGroup, VariantGroupListQuery, VariantGroupPage } from './typen.js';
+/**
+ * Legt eine Variantengruppe an: mit `createMatrix: true` alle Kombinationen der
+ * Werte (hoechstens 100), sonst die genannten `variants[]` (hoechstens 100),
+ * ohne beides nur die Gruppe. Jede Variante entsteht als Artikel mit den
+ * Feldern wie bei `createArticle`; was sie nicht nennt, fuellen die Vorgaben.
+ * Antwort: die Gruppe mit `variants[]` (Kennung und Merkmale je Variante).
+ *
+ * Braucht die Anlage mehr Schreibvorgaenge, als in einen Vorgang passen,
+ * kommt `too_many_positions` mit `field` (`variants` bzw. `createMatrix`) und
+ * nichts ist geschrieben: weniger Varianten senden, den Rest per [addVariant].
+ */
+export declare function createVariantGroup(transport: InternerTransport, request: CreateVariantGroupRequest): Promise<VariantGroup>;
+/**
+ * Aendert eine aktive Gruppe (Name, Vorgaben, neue Werte) oder legt sie mit
+ * `active: false` still: die Gruppe und alle ihre Varianten, endgueltig. Die
+ * Antwort kommt erst, wenn alle Varianten stillgelegt sind. Bestehende
+ * Varianten aendern Name und Vorgaben nicht (dafuer `updateArticle`).
+ */
+export declare function updateVariantGroup(transport: InternerTransport, request: UpdateVariantGroupRequest): Promise<VariantGroup>;
+/**
+ * Legt eine Variante in einer aktiven Gruppe an. Antwort: der Artikel wie
+ * `createArticle`. Gibt es die Kombination schon, kommt
+ * `variant_already_exists` mit `articleId` der bestehenden Variante; nach dem
+ * Stilllegen einer Variante ist ihre Kombination wieder frei.
+ */
+export declare function addVariant(transport: InternerTransport, request: AddVariantRequest): Promise<Article>;
+/** Eine Variantengruppe mit ihren aktiven Varianten (eingefroren, wenn stillgelegt). */
+export declare function getVariantGroup(transport: InternerTransport, variantGroupId: string): Promise<VariantGroup>;
+/** Variantengruppen nach `updatedAt` aufsteigend; Filter `active` und `updatedSince` (inklusive). */
+export declare function listVariantGroups(transport: InternerTransport, query?: VariantGroupListQuery): Promise<VariantGroupPage>;
+/** Alle Variantengruppen der Abfrage, Seite fuer Seite ueber `nextCursor`. */
+export declare function iterateVariantGroups(transport: InternerTransport, query?: VariantGroupListQuery): AsyncGenerator<VariantGroup, void, undefined>;

package/dist/esm/inventory/varianten.js

@@ -0,0 +1,142 @@
+/**
+ * Variantengruppen der Lager-API (Backend Stufe 5c): Gruppe anlegen (mit
+ * Matrix oder genannten Varianten), aendern oder stilllegen, eine Variante
+ * ergaenzen, Gruppen lesen.
+ *
+ * Eine Variante ist ein gewoehnlicher Artikel mit `variantGroupId` und
+ * `variantAttributes`; gelesen, gebucht und reserviert wird sie wie jeder
+ * Artikel. Die Gruppenantworten tragen nur die Kennungen der Varianten, die
+ * Artikel selbst liefert `listArticles({ variantGroupId })`.
+ *
+ * Wie in `schreiben.ts` geht die Anfrage flach hinaus, genau mit den Feldern,
+ * die der Aufrufer nennt (`undefined` faellt weg, `null` bleibt).
+ *
+ * **Vor dem Senden geprueft wird nur, was ohne Netz sicher falsch ist:**
+ * - `idempotencyKey` fehlt, ist leer oder laenger als 120 Zeichen (die drei
+ *   schreibenden Aufrufe);
+ * - `variantGroupId` fehlt oder ist leer;
+ * - `createMatrix: true` zusammen mit `variants` (schliessen sich aus);
+ * - `variants` ist keine Liste, ein Eintrag kein Objekt, `variantAttributes`
+ *   einer Variante fehlt oder ist kein Objekt;
+ * - ein Preis, eine Menge oder ein Einkaufspreis (auch in `defaults`) ist
+ *   keine Ganzzahl;
+ * - eine Aenderung nennt kein Feld, `active` ist nicht `false` oder steht
+ *   nicht allein, `addAttributeValues` ist kein Objekt.
+ * Die Grenzen (Merkmale, Werte, Matrix, aktive Varianten) prueft der Server:
+ * er darf sie anheben, ohne dass diese Paketversion dann falsch abweist.
+ *
+ * **Wiederholen** wie bei jedem Schreiben: nach `outcome: 'unknown'` denselben
+ * Aufruf mit **demselben** `idempotencyKey`; er wirkt genau einmal und liefert
+ * die gespeicherte Antwort. Ein neuer Schluessel legte die Gruppe ein zweites
+ * Mal an. Ein abgebrochenes Stilllegen vollendet jede Wiederholung von
+ * `updateVariantGroup({ active: false })`, auch mit neuem Schluessel.
+ */
+import { abfrage, anfragefehler, kennung, seitenweise } from './endpunkte.js';
+import { liste, naechsterCursor, objekt, variantengruppe } from './lesen.js';
+import { anfrage, artikelAus, artikelZahlen, ganz, schluessel } from './schreiben.js';
+const istObjekt = (w) => w !== null && typeof w === 'object' && !Array.isArray(w);
+/** Vorgaben: nur der Preis ist eine Zahl mit Skala (Cent); `null` leert bzw. heisst „nicht angegeben“. */
+function vorgabenZahlen(name, w) {
+    if (w === undefined || w === null)
+        return;
+    if (!istObjekt(w))
+        throw anfragefehler(name, 'defaults muss ein Objekt oder null sein');
+    ganz(name, 'defaults.unitPriceCents', w.unitPriceCents, { leerbar: true });
+}
+/** Eine Variante der Anfrage: Merkmale als Objekt, Zahlen ganzzahlig. */
+function variante(name, w, praefix) {
+    const stelle = praefix ? praefix.slice(0, -1) : 'Anfrage';
+    if (!istObjekt(w))
+        throw anfragefehler(name, `${stelle} muss ein Objekt sein`);
+    if (!istObjekt(w.variantAttributes)) {
+        throw anfragefehler(name, `${praefix}variantAttributes fehlt oder ist kein Objekt { merkmal: wert }`);
+    }
+    artikelZahlen(name, w, praefix);
+}
+const gruppeAus = (name, daten) => variantengruppe({ name, pfad: 'variantGroup' }, objekt(daten)?.variantGroup);
+/**
+ * Legt eine Variantengruppe an: mit `createMatrix: true` alle Kombinationen der
+ * Werte (hoechstens 100), sonst die genannten `variants[]` (hoechstens 100),
+ * ohne beides nur die Gruppe. Jede Variante entsteht als Artikel mit den
+ * Feldern wie bei `createArticle`; was sie nicht nennt, fuellen die Vorgaben.
+ * Antwort: die Gruppe mit `variants[]` (Kennung und Merkmale je Variante).
+ *
+ * Braucht die Anlage mehr Schreibvorgaenge, als in einen Vorgang passen,
+ * kommt `too_many_positions` mit `field` (`variants` bzw. `createMatrix`) und
+ * nichts ist geschrieben: weniger Varianten senden, den Rest per [addVariant].
+ */
+export async function createVariantGroup(transport, request) {
+    const name = 'createVariantGroup';
+    const p = anfrage(name, request);
+    schluessel(name, p, { pflicht: true });
+    if (p.createMatrix === true && p.variants !== null && p.variants !== undefined) {
+        throw anfragefehler(name, 'createMatrix und variants schliessen sich aus: entweder alle Kombinationen oder die genannten Varianten');
+    }
+    vorgabenZahlen(name, p.defaults);
+    if (p.variants !== null && p.variants !== undefined) {
+        if (!Array.isArray(p.variants))
+            throw anfragefehler(name, 'variants muss eine Liste sein');
+        p.variants.forEach((x, i) => variante(name, x, `variants[${i}].`));
+    }
+    return gruppeAus(name, await transport(name, p));
+}
+/**
+ * Aendert eine aktive Gruppe (Name, Vorgaben, neue Werte) oder legt sie mit
+ * `active: false` still: die Gruppe und alle ihre Varianten, endgueltig. Die
+ * Antwort kommt erst, wenn alle Varianten stillgelegt sind. Bestehende
+ * Varianten aendern Name und Vorgaben nicht (dafuer `updateArticle`).
+ */
+export async function updateVariantGroup(transport, request) {
+    const name = 'updateVariantGroup';
+    const p = anfrage(name, request);
+    schluessel(name, p, { pflicht: true });
+    kennung(name, 'variantGroupId', p.variantGroupId);
+    const aenderungen = ['name', 'defaults', 'addAttributeValues'].filter((k) => p[k] !== undefined);
+    if (p.active !== undefined) {
+        if (p.active !== false)
+            throw anfragefehler(name, 'active kennt nur false (stilllegen); eine stillgelegte Gruppe bleibt stillgelegt');
+        if (aenderungen.length)
+            throw anfragefehler(name, 'active: false steht allein, ohne weitere Aenderung');
+    }
+    else if (!aenderungen.length) {
+        throw anfragefehler(name, 'die Aenderung nennt kein Feld');
+    }
+    vorgabenZahlen(name, p.defaults);
+    if (p.addAttributeValues !== undefined && !istObjekt(p.addAttributeValues)) {
+        throw anfragefehler(name, 'addAttributeValues muss ein Objekt { merkmal: [werte] } sein');
+    }
+    return gruppeAus(name, await transport(name, p));
+}
+/**
+ * Legt eine Variante in einer aktiven Gruppe an. Antwort: der Artikel wie
+ * `createArticle`. Gibt es die Kombination schon, kommt
+ * `variant_already_exists` mit `articleId` der bestehenden Variante; nach dem
+ * Stilllegen einer Variante ist ihre Kombination wieder frei.
+ */
+export async function addVariant(transport, request) {
+    const name = 'addVariant';
+    const p = anfrage(name, request);
+    schluessel(name, p, { pflicht: true });
+    kennung(name, 'variantGroupId', p.variantGroupId);
+    variante(name, p, '');
+    return artikelAus(name, await transport(name, p));
+}
+/** Eine Variantengruppe mit ihren aktiven Varianten (eingefroren, wenn stillgelegt). */
+export async function getVariantGroup(transport, variantGroupId) {
+    const name = 'getVariantGroup';
+    return gruppeAus(name, await transport(name, { variantGroupId: kennung(name, 'variantGroupId', variantGroupId) }));
+}
+/** Variantengruppen nach `updatedAt` aufsteigend; Filter `active` und `updatedSince` (inklusive). */
+export async function listVariantGroups(transport, query) {
+    const name = 'listVariantGroups';
+    const daten = await transport(name, abfrage(name, query));
+    return { variantGroups: liste(name, daten, 'variantGroups', variantengruppe), nextCursor: naechsterCursor(name, daten) };
+}
+/** Alle Variantengruppen der Abfrage, Seite fuer Seite ueber `nextCursor`. */
+export function iterateVariantGroups(transport, query) {
+    const { cursor, ...rest } = query ?? {};
+    return seitenweise('listVariantGroups', cursor, async (c) => {
+        const s = await listVariantGroups(transport, { ...rest, cursor: c });
+        return { eintraege: s.variantGroups, nextCursor: s.nextCursor };
+    });
+}