@kreiseck/kasseneck-api 1.5.1 → 1.6.0

package/dist/cjs/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/cjs/inventory/schreiben.js

@@ -29,6 +29,11 @@
  * Probelauf (`previewGoodsReceipt`) bleiben `'rejected'`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.artikelAus = void 0;
+exports.anfrage = anfrage;
+exports.schluessel = schluessel;
+exports.ganz = ganz;
+exports.artikelZahlen = artikelZahlen;
 exports.createArticle = createArticle;
 exports.updateArticle = updateArticle;
 exports.deactivateArticle = deactivateArticle;
@@ -48,7 +53,7 @@ const endpunkte_js_1 = require("./endpunkte.js");
 const lesen_js_1 = require("./lesen.js");
 const vertrag_js_1 = require("./vertrag.js");
 // ---- Pruefung vor dem Senden ------------------------------------------------------
-/** Die Anfrage als flache Kopie ohne `undefined`; der Aufrufer behaelt sein Objekt. */
+/** Die Anfrage als flache Kopie ohne `undefined`; der Aufrufer behaelt sein Objekt. Paketintern, auch fuer `varianten.ts`. */
 function anfrage(name, request) {
     if (request === null || typeof request !== 'object' || Array.isArray(request)) {
         throw (0, endpunkte_js_1.anfragefehler)(name, 'Anfrage muss ein Objekt sein');
@@ -124,19 +129,23 @@ 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].`).
+ */
+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 (0, endpunkte_js_1.anfragefehler)(name, 'minStockByLocation muss ein Objekt { standort: Tausendstel } sein');
+        throw (0, endpunkte_js_1.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) => (0, lesen_js_1.artikel)({ name, pfad: 'article' }, (0, lesen_js_1.objekt)(daten)?.article);
+exports.artikelAus = artikelAus;
 /**
  * Legt einen Artikel an. Mit `ean` ein Fremdartikel mit diesem Code (gueltige
  * Pruefziffer, frei im Konto), sonst vergibt der Server den naechsten eigenen
@@ -147,7 +156,7 @@ async function createArticle(transport, request) {
     const p = anfrage(name, request);
     schluessel(name, p, { pflicht: true });
     artikelZahlen(name, p);
-    return artikelAus(name, await transport(name, p));
+    return (0, exports.artikelAus)(name, await transport(name, p));
 }
 /** Aendert nur die genannten Felder eines Artikels (siehe [UpdateArticleRequest]). */
 async function updateArticle(transport, request) {
@@ -159,7 +168,7 @@ async function updateArticle(transport, request) {
         throw (0, endpunkte_js_1.anfragefehler)(name, 'die Aenderung nennt kein Feld');
     }
     artikelZahlen(name, p);
-    return artikelAus(name, await transport(name, p));
+    return (0, exports.artikelAus)(name, await transport(name, p));
 }
 /** Legt einen Artikel still (`active: false`); Code und eigene Kennungen werden frei. */
 async function deactivateArticle(transport, request) {
@@ -167,7 +176,7 @@ async function deactivateArticle(transport, request) {
     const p = anfrage(name, request);
     schluessel(name, p, { pflicht: true });
     (0, endpunkte_js_1.kennung)(name, 'articleId', p.articleId);
-    return artikelAus(name, await transport(name, p));
+    return (0, exports.artikelAus)(name, await transport(name, p));
 }
 // ---- Buchen ------------------------------------------------------------------
 function eingangZahlen(name, p) {

package/dist/cjs/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/cjs/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/cjs/inventory/varianten.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVariantGroup = createVariantGroup;
+exports.updateVariantGroup = updateVariantGroup;
+exports.addVariant = addVariant;
+exports.getVariantGroup = getVariantGroup;
+exports.listVariantGroups = listVariantGroups;
+exports.iterateVariantGroups = iterateVariantGroups;
+const endpunkte_js_1 = require("./endpunkte.js");
+const lesen_js_1 = require("./lesen.js");
+const schreiben_js_1 = require("./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 (0, endpunkte_js_1.anfragefehler)(name, 'defaults muss ein Objekt oder null sein');
+    (0, schreiben_js_1.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 (0, endpunkte_js_1.anfragefehler)(name, `${stelle} muss ein Objekt sein`);
+    if (!istObjekt(w.variantAttributes)) {
+        throw (0, endpunkte_js_1.anfragefehler)(name, `${praefix}variantAttributes fehlt oder ist kein Objekt { merkmal: wert }`);
+    }
+    (0, schreiben_js_1.artikelZahlen)(name, w, praefix);
+}
+const gruppeAus = (name, daten) => (0, lesen_js_1.variantengruppe)({ name, pfad: 'variantGroup' }, (0, lesen_js_1.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].
+ */
+async function createVariantGroup(transport, request) {
+    const name = 'createVariantGroup';
+    const p = (0, schreiben_js_1.anfrage)(name, request);
+    (0, schreiben_js_1.schluessel)(name, p, { pflicht: true });
+    if (p.createMatrix === true && p.variants !== null && p.variants !== undefined) {
+        throw (0, endpunkte_js_1.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 (0, endpunkte_js_1.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`).
+ */
+async function updateVariantGroup(transport, request) {
+    const name = 'updateVariantGroup';
+    const p = (0, schreiben_js_1.anfrage)(name, request);
+    (0, schreiben_js_1.schluessel)(name, p, { pflicht: true });
+    (0, endpunkte_js_1.kennung)(name, 'variantGroupId', p.variantGroupId);
+    const aenderungen = ['name', 'defaults', 'addAttributeValues'].filter((k) => p[k] !== undefined);
+    if (p.active !== undefined) {
+        if (p.active !== false)
+            throw (0, endpunkte_js_1.anfragefehler)(name, 'active kennt nur false (stilllegen); eine stillgelegte Gruppe bleibt stillgelegt');
+        if (aenderungen.length)
+            throw (0, endpunkte_js_1.anfragefehler)(name, 'active: false steht allein, ohne weitere Aenderung');
+    }
+    else if (!aenderungen.length) {
+        throw (0, endpunkte_js_1.anfragefehler)(name, 'die Aenderung nennt kein Feld');
+    }
+    vorgabenZahlen(name, p.defaults);
+    if (p.addAttributeValues !== undefined && !istObjekt(p.addAttributeValues)) {
+        throw (0, endpunkte_js_1.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.
+ */
+async function addVariant(transport, request) {
+    const name = 'addVariant';
+    const p = (0, schreiben_js_1.anfrage)(name, request);
+    (0, schreiben_js_1.schluessel)(name, p, { pflicht: true });
+    (0, endpunkte_js_1.kennung)(name, 'variantGroupId', p.variantGroupId);
+    variante(name, p, '');
+    return (0, schreiben_js_1.artikelAus)(name, await transport(name, p));
+}
+/** Eine Variantengruppe mit ihren aktiven Varianten (eingefroren, wenn stillgelegt). */
+async function getVariantGroup(transport, variantGroupId) {
+    const name = 'getVariantGroup';
+    return gruppeAus(name, await transport(name, { variantGroupId: (0, endpunkte_js_1.kennung)(name, 'variantGroupId', variantGroupId) }));
+}
+/** Variantengruppen nach `updatedAt` aufsteigend; Filter `active` und `updatedSince` (inklusive). */
+async function listVariantGroups(transport, query) {
+    const name = 'listVariantGroups';
+    const daten = await transport(name, (0, endpunkte_js_1.abfrage)(name, query));
+    return { variantGroups: (0, lesen_js_1.liste)(name, daten, 'variantGroups', lesen_js_1.variantengruppe), nextCursor: (0, lesen_js_1.naechsterCursor)(name, daten) };
+}
+/** Alle Variantengruppen der Abfrage, Seite fuer Seite ueber `nextCursor`. */
+function iterateVariantGroups(transport, query) {
+    const { cursor, ...rest } = query ?? {};
+    return (0, endpunkte_js_1.seitenweise)('listVariantGroups', cursor, async (c) => {
+        const s = await listVariantGroups(transport, { ...rest, cursor: c });
+        return { eintraege: s.variantGroups, nextCursor: s.nextCursor };
+    });
+}

package/dist/cjs/inventory/vertrag.d.ts

@@ -1,6 +1,6 @@
 /**
  * Der Vertrag der Lager-API (Backend Stufe 5a lesen, 5b schreiben und
- * reservieren) als Daten: Endpunkte, Wertkataloge, Ereignisse, Fehler- und
+ * reservieren, 5c Varianten) als Daten: Endpunkte, Wertkataloge, Ereignisse, Fehler- und
  * Hinweiscodes, englisch wie am Draht `/v3`.
  *
  * Quelle ist der Vertrags-Export des Backends (`fixtures/v3/v3-vokabular.json`):
@@ -11,8 +11,8 @@
  * und `warningCodes.inventory`. `test/inventory.test.ts` haelt jede Liste
  * deckungsgleich mit dieser Datei; nichts hier wird geraten.
  */
-/** Die 27 Endpunkte (14 aus 5a, 13 aus 5b), in der Reihenfolge von `endpoints.public`. */
-export declare const INVENTORY_ENDPOINTS: readonly ["getArticle", "listArticles", "lookupArticleByCode", "listLocations", "getStock", "listStock", "listStockMovements", "createWebhook", "updateWebhook", "deleteWebhook", "listWebhooks", "sendWebhookTest", "rotateWebhookSecret", "listWebhookDeliveries", "createArticle", "updateArticle", "deactivateArticle", "receiveGoods", "transferStock", "recordStockLoss", "changeStockCondition", "reverseStockMovement", "createReservation", "extendReservation", "releaseReservation", "getReservation", "listReservations"];
+/** Die 32 Endpunkte (14 aus 5a, 13 aus 5b, 5 aus 5c), in der Reihenfolge von `endpoints.public`. */
+export declare const INVENTORY_ENDPOINTS: readonly ["getArticle", "listArticles", "lookupArticleByCode", "listLocations", "getStock", "listStock", "listStockMovements", "createWebhook", "updateWebhook", "deleteWebhook", "listWebhooks", "sendWebhookTest", "rotateWebhookSecret", "listWebhookDeliveries", "createArticle", "updateArticle", "deactivateArticle", "receiveGoods", "transferStock", "recordStockLoss", "changeStockCondition", "reverseStockMovement", "createReservation", "extendReservation", "releaseReservation", "getReservation", "listReservations", "createVariantGroup", "updateVariantGroup", "getVariantGroup", "listVariantGroups", "addVariant"];
 export type InventoryEndpoint = (typeof INVENTORY_ENDPOINTS)[number];
 /** Art eines Standorts (Katalog `STANDORT_TYP`). */
 export declare const LOCATION_TYPES: readonly ["warehouse", "store", "vehicle", "other"];
@@ -52,8 +52,12 @@ export type WebhookDeliveryStatus = (typeof WEBHOOK_DELIVERY_STATUSES)[number];
  * wie `getReservation`, mit dem Status danach: `reservation.released` und
  * `reservation.redeemed` kommen bei jeder wirksamen Freigabe bzw. Einloesung,
  * auch einer teilweisen (dann bleibt der Status `active`).
+ * `variant_group.created` und `variant_group.updated` (seit 1.6.0) tragen die
+ * Variantengruppe wie `getVariantGroup`; `updated` kommt nur bei einer aussen
+ * sichtbaren Aenderung (neuer Wert, neue oder stillgelegte Variante, Name,
+ * Vorgaben, Stilllegen der Gruppe).
  */
-export declare const INVENTORY_WEBHOOK_EVENTS: readonly ["stock.changed", "stock.below_minimum", "article.created", "article.updated", "article.deactivated", "reservation.expired", "reservation.released", "reservation.redeemed"];
+export declare const INVENTORY_WEBHOOK_EVENTS: readonly ["stock.changed", "stock.below_minimum", "article.created", "article.updated", "article.deactivated", "reservation.expired", "reservation.released", "reservation.redeemed", "variant_group.created", "variant_group.updated"];
 export type InventoryWebhookEventType = (typeof INVENTORY_WEBHOOK_EVENTS)[number];
 /**
  * Die Felder der Huelle jeder Zustellung, in der Reihenfolge am Draht. Statt
@@ -81,8 +85,21 @@ export declare const INVENTORY_LIST_LIMIT_MAX = 200;
  * [inventoryShortfalls]), `code_taken` und `external_id_taken` (mit `field` und
  * `articleId` des Artikels, dem der Code gehoert), `stock_kind_locked`,
  * `reservation_not_found`, `reservation_not_active` …
+ *
+ * Seit 1.6.0 dahinter die Codes der Variantengruppen: `variant_group_not_found`
+ * (unbekannte Kennung), `variant_already_exists` (die Kombination gibt es in der
+ * Gruppe schon, dann mit `articleId` der bestehenden Variante, oder sie steht
+ * zweimal in `variants[]`; jeweils mit `field`),
+ * `invalid_variant_attributes` (ein Merkmal fehlt, ist unbekannt oder sein Wert
+ * steht nicht in der Werteliste; `field` und `errors[]`),
+ * `variant_group_inactive` (stillgelegte Gruppe: kein `addVariant`, keine
+ * Aenderung ausser erneutem Stilllegen) und `variant_limit` (mehr als
+ * [VARIANT_GROUP_ACTIVE_MAX] aktive Varianten je Gruppe). Wiederverwendet:
+ * `too_many_positions` traegt bei Varianten `field` (`variants`,
+ * `createMatrix` bzw. `externalIds` bei `addVariant`): die Anfrage braeuchte
+ * mehr Schreibvorgaenge, als in einen Vorgang passen; geschrieben wurde nichts.
  */
-export declare const INVENTORY_ERROR_CODES: readonly ["validation", "invalid_cursor", "article_not_found", "webhook_not_found", "webhook_limit", "invalid_webhook_url", "event_not_subscribed", "webhook_inactive", "inventory_api_not_enabled", "module_inactive", "rate_limited", "server_error", "idempotency_key_required", "idempotency_conflict", "location_not_found", "location_inactive", "invalid_location", "invalid_locations", "invalid_transfer", "operation_not_found", "already_reversed", "reversal_not_possible", "reversal_not_supported", "exceeds_stock", "no_positions", "too_many_positions", "invalid_step", "invalid_quantity", "invalid_amount", "invalid_price", "negative_value", "invalid_reason", "note_required", "withdrawal_type_required", "invalid_method", "invalid_stock_kind", "invalid_minimum", "invalid_dimensions", "weight_missing", "invalid_landed_cost", "invalid_distribution", "landed_costs_mismatch", "return_totals_mismatch", "lot_not_found", "invalid_serial", "serial_required", "serial_not_allowed", "serial_already_exists", "serial_not_in_stock", "code_taken", "external_id_taken", "group_not_found", "revenue_group_not_found", "stock_kind_locked", "article_inactive", "invalid_position", "invalid_condition", "reason_required", "insufficient_available", "reservation_not_found", "reservation_not_active"];
+export declare const INVENTORY_ERROR_CODES: readonly ["validation", "invalid_cursor", "article_not_found", "webhook_not_found", "webhook_limit", "invalid_webhook_url", "event_not_subscribed", "webhook_inactive", "inventory_api_not_enabled", "module_inactive", "rate_limited", "server_error", "idempotency_key_required", "idempotency_conflict", "location_not_found", "location_inactive", "invalid_location", "invalid_locations", "invalid_transfer", "operation_not_found", "already_reversed", "reversal_not_possible", "reversal_not_supported", "exceeds_stock", "no_positions", "too_many_positions", "invalid_step", "invalid_quantity", "invalid_amount", "invalid_price", "negative_value", "invalid_reason", "note_required", "withdrawal_type_required", "invalid_method", "invalid_stock_kind", "invalid_minimum", "invalid_dimensions", "weight_missing", "invalid_landed_cost", "invalid_distribution", "landed_costs_mismatch", "return_totals_mismatch", "lot_not_found", "invalid_serial", "serial_required", "serial_not_allowed", "serial_already_exists", "serial_not_in_stock", "code_taken", "external_id_taken", "group_not_found", "revenue_group_not_found", "stock_kind_locked", "article_inactive", "invalid_position", "invalid_condition", "reason_required", "insufficient_available", "reservation_not_found", "reservation_not_active", "variant_group_not_found", "variant_already_exists", "invalid_variant_attributes", "variant_group_inactive", "variant_limit"];
 export type InventoryErrorCode = (typeof INVENTORY_ERROR_CODES)[number];
 /**
  * Codes, die Anmeldung und Rand auf jedem Lager-Aufruf erzeugen koennen,
@@ -134,3 +151,21 @@ export declare const INVENTORY_IDEMPOTENCY_KEY_MAX = 120;
 /** Kuerzeste und laengste Haltedauer einer Reservierung in Minuten (`expiresInMinutes`, 30 Tage). */
 export declare const RESERVATION_MINUTES_MIN = 5;
 export declare const RESERVATION_MINUTES_MAX = 43200;
+/**
+ * Grenzen einer Variantengruppe, wie das Backend sie prueft. Das Paket prueft
+ * sie **nicht** vor dem Senden: der Server darf sie anheben, ohne dass eine
+ * aeltere Paketversion dann faelschlich abweist. Wer darueber liegt, bekommt
+ * `validation` (Merkmale, Werte, Matrix, `variants[]`) bzw. `variant_limit`.
+ *
+ * - [VARIANT_ATTRIBUTES_MAX] Merkmale je Gruppe (Schluessel `^[a-z0-9_]{1,32}$`,
+ *   eindeutig; `__…__` ist reserviert),
+ * - [VARIANT_VALUES_MAX] Werte je Merkmal (je 1–30 Zeichen, eindeutig ohne
+ *   Gross/Klein),
+ * - [VARIANT_MATRIX_MAX] Kombinationen bei `createMatrix: true` und hoechstens
+ *   so viele Eintraege in `variants[]` je Anfrage,
+ * - [VARIANT_GROUP_ACTIVE_MAX] aktive Varianten je Gruppe.
+ */
+export declare const VARIANT_ATTRIBUTES_MAX = 3;
+export declare const VARIANT_VALUES_MAX = 30;
+export declare const VARIANT_MATRIX_MAX = 100;
+export declare const VARIANT_GROUP_ACTIVE_MAX = 250;