@kreiseck/kasseneck-api 1.5.0 → 1.6.0

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 };
+    });
+}

package/dist/esm/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;

package/dist/esm/inventory/vertrag.js

@@ -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,7 +11,7 @@
  * 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`. */
+/** Die 32 Endpunkte (14 aus 5a, 13 aus 5b, 5 aus 5c), in der Reihenfolge von `endpoints.public`. */
 export const INVENTORY_ENDPOINTS = [
     'getArticle',
     'listArticles',
@@ -40,6 +40,11 @@ export const INVENTORY_ENDPOINTS = [
     'releaseReservation',
     'getReservation',
     'listReservations',
+    'createVariantGroup',
+    'updateVariantGroup',
+    'getVariantGroup',
+    'listVariantGroups',
+    'addVariant',
 ];
 /** Art eines Standorts (Katalog `STANDORT_TYP`). */
 export const LOCATION_TYPES = ['warehouse', 'store', 'vehicle', 'other'];
@@ -113,6 +118,10 @@ export const WEBHOOK_DELIVERY_STATUSES = ['delivered', 'pending', 'failed', 'dro
  * 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 const INVENTORY_WEBHOOK_EVENTS = [
     'stock.changed',
@@ -123,6 +132,8 @@ export const INVENTORY_WEBHOOK_EVENTS = [
     'reservation.expired',
     'reservation.released',
     'reservation.redeemed',
+    'variant_group.created',
+    'variant_group.updated',
 ];
 /**
  * Die Felder der Huelle jeder Zustellung, in der Reihenfolge am Draht. Statt
@@ -150,6 +161,19 @@ export 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 const INVENTORY_ERROR_CODES = [
     'validation',
@@ -213,6 +237,11 @@ export const INVENTORY_ERROR_CODES = [
     'insufficient_available',
     'reservation_not_found',
     'reservation_not_active',
+    'variant_group_not_found',
+    'variant_already_exists',
+    'invalid_variant_attributes',
+    'variant_group_inactive',
+    'variant_limit',
 ];
 /**
  * Codes, die Anmeldung und Rand auf jedem Lager-Aufruf erzeugen koennen,
@@ -286,3 +315,22 @@ export const INVENTORY_IDEMPOTENCY_KEY_MAX = 120;
 /** Kuerzeste und laengste Haltedauer einer Reservierung in Minuten (`expiresInMinutes`, 30 Tage). */
 export const RESERVATION_MINUTES_MIN = 5;
 export const RESERVATION_MINUTES_MAX = 43_200;
+// ---- Varianten (Backend Stufe 5c, seit 1.6.0) -----------------------------------
+/**
+ * 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 const VARIANT_ATTRIBUTES_MAX = 3;
+export const VARIANT_VALUES_MAX = 30;
+export const VARIANT_MATRIX_MAX = 100;
+export const VARIANT_GROUP_ACTIVE_MAX = 250;

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

@@ -39,10 +39,13 @@ export declare function verifyInventoryWebhookSignature(secret: string | readonl
  * Liest eine Zustellung als typisiertes Ereignis. Vorher die Signatur pruefen
  * ([verifyInventoryWebhookSignature]).
  *
- * - Ein Ereignis, das diese Paketversion nicht kennt (etwa `variant_group.*`
- *   einer spaeteren Stufe), ergibt `null`: mit 2xx antworten und uebergehen.
+ * - Ein Ereignis, das diese Paketversion nicht kennt (eines einer spaeteren
+ *   Stufe), ergibt `null`: mit 2xx antworten und uebergehen.
  * - `reservation.expired|released|redeemed` tragen die Reservierung wie
  *   `getReservation`, mit dem Status nach dem Vorgang (seit 1.5.0).
+ * - `variant_group.created|updated` tragen die Gruppe wie `getVariantGroup`
+ *   (seit 1.6.0). Zwei Zustellungen koennen sich ueberholen: den Stand nur
+ *   uebernehmen, wenn `data.updatedAt` neuer ist als der gespeicherte.
  * - Ein Rumpf, der keine Huelle ist, oder eine Bruchzahl in einer Menge wirft
  *   `KasseneckValidationError` (`scope: 'response'`).
  *

package/dist/esm/inventory/webhook.js

@@ -15,7 +15,7 @@
  */
 import { KasseneckValidationError } from '../client/errors.js';
 import { verifyWebhookSignature as pruefeSignatur } from '../partner/webhook-signatur.js';
-import { artikel, bestandGeaendert, objekt, reservierung, unterMindestbestand } from './lesen.js';
+import { artikel, bestandGeaendert, objekt, reservierung, unterMindestbestand, variantengruppe } from './lesen.js';
 import { INVENTORY_WEBHOOK_EVENTS } from './vertrag.js';
 export { WEBHOOK_SIGNATURE_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_TOLERANCE_SEC, } from '../partner/webhook-signatur.js';
 /**
@@ -56,10 +56,13 @@ function kaputt(grund) {
  * Liest eine Zustellung als typisiertes Ereignis. Vorher die Signatur pruefen
  * ([verifyInventoryWebhookSignature]).
  *
- * - Ein Ereignis, das diese Paketversion nicht kennt (etwa `variant_group.*`
- *   einer spaeteren Stufe), ergibt `null`: mit 2xx antworten und uebergehen.
+ * - Ein Ereignis, das diese Paketversion nicht kennt (eines einer spaeteren
+ *   Stufe), ergibt `null`: mit 2xx antworten und uebergehen.
  * - `reservation.expired|released|redeemed` tragen die Reservierung wie
  *   `getReservation`, mit dem Status nach dem Vorgang (seit 1.5.0).
+ * - `variant_group.created|updated` tragen die Gruppe wie `getVariantGroup`
+ *   (seit 1.6.0). Zwei Zustellungen koennen sich ueberholen: den Stand nur
+ *   uebernehmen, wenn `data.updatedAt` neuer ist als der gespeicherte.
  * - Ein Rumpf, der keine Huelle ist, oder eine Bruchzahl in einer Menge wirft
  *   `KasseneckValidationError` (`scope: 'response'`).
  *
@@ -101,6 +104,9 @@ export function parseInventoryWebhookEvent(rawBody) {
         case 'reservation.released':
         case 'reservation.redeemed':
             return { ...huelle, type: huelle.type, data: reservierung(ort, data) };
+        case 'variant_group.created':
+        case 'variant_group.updated':
+            return { ...huelle, type: huelle.type, data: variantengruppe(ort, data) };
         default:
             return { ...huelle, type: huelle.type, data: artikel(ort, data) };
     }

package/dist/esm/invoice/endpunkte.d.ts

@@ -12,6 +12,12 @@
  * **Nicht automatisch wiederholen.** Wer nach einem Zeitlimit erneut
  * ausstellt, tut das mit **demselben** `idempotencyKey`: dann kommt die schon
  * ausgestellte Rechnung zurueck (`replayed: true`) statt einer zweiten.
+ * Jeder Aufruf mit Wirkung (ausstellen, stornieren, gutschreiben, Zahlung
+ * nachtragen, Kunde anlegen oder aendern) meldet nach Zeitlimit, Netzfehler,
+ * HTTP 5xx oder unlesbarer Antwort `outcome: 'unknown'`: er kann gewirkt
+ * haben. Mit Schluessel denselben Schluessel erneut senden, ohne Schluessel
+ * (`updateCustomer`, `createCustomer` ohne) erst nachlesen. Lesen und der
+ * Probelauf (`previewInvoice`) bleiben `'rejected'`.
  *
  * Nach dem Senden wird nichts hart gecastet: fehlt ein zugesagtes Feld, wirft
  * der Aufruf `KasseneckValidationError` mit `scope:'response'`.