@kreiseck/kasseneck-api 1.3.0 → 1.5.0

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

@@ -0,0 +1,61 @@
+/**
+ * Fassade ueber den Aufrufen der Lager-API (lesen, Webhooks, schreiben,
+ * reservieren): Schluessel einmal binden, dann rufen. Wie [createInvoiceApi] bewusst keine Klasse; die Aufrufe sind freie
+ * Funktionen (endpunkte.ts) und bleiben einzeln importierbar.
+ */
+import { type FetchLike } from '../client/transport.js';
+import type { Article, ChangeStockConditionRequest, CreateArticleRequest, CreateReservationRequest, DeactivateArticleRequest, ExtendReservationRequest, GoodsReceiptPreview, GoodsReceiptPreviewRequest, ReceiveGoodsRequest, RecordStockLossRequest, ReleaseReservationRequest, Reservation, ReservationListQuery, ReservationPage, ReverseStockMovementRequest, StockOperation, TransferStockRequest, UpdateArticleRequest, ArticleListQuery, ArticleLookup, ArticlePage, CreateInventoryWebhookOptions, InventoryWebhook, InventoryWebhookDelivery, InventoryWebhookList, InventoryWebhookPatch, InventoryWebhookTestResult, InventoryWebhookWithSecret, Location, StockLevel, StockListQuery, StockMovement, StockMovementPage, StockMovementQuery, StockPage, StockResult } from './typen.js';
+import type { InventoryWebhookEventType } from './vertrag.js';
+export interface InventoryClientOptions {
+    /** `api_key` des Kontos (`kr_live_…` / `kr_test_…`). Gehoert auf einen Server. */
+    apiKey: string;
+    /** Abweichende Basis-URL (eigener Proxy); muss auf `/v3` enden. Vorgabe `https://api.kasseneck.at/v3`. */
+    baseUrl?: string;
+    /** Zeitlimit je Aufruf in Millisekunden. */
+    timeoutMs?: number;
+    /** Eigene `fetch`-Umsetzung (Tests, Proxys). */
+    fetch?: FetchLike;
+}
+export interface InventoryClient {
+    getArticle(articleId: string): Promise<Article>;
+    listArticles(query?: ArticleListQuery): Promise<ArticlePage>;
+    /** Alle Artikel der Abfrage ueber `nextCursor`: `for await (const a of client.iterateArticles())`. */
+    iterateArticles(query?: ArticleListQuery): AsyncGenerator<Article, void, undefined>;
+    lookupArticleByCode(lookup: ArticleLookup): Promise<Article>;
+    listLocations(): Promise<Location[]>;
+    getStock(articleId: string): Promise<StockResult>;
+    listStock(query?: StockListQuery): Promise<StockPage>;
+    iterateStock(query?: StockListQuery): AsyncGenerator<StockLevel, void, undefined>;
+    listStockMovements(query?: StockMovementQuery): Promise<StockMovementPage>;
+    iterateStockMovements(query?: StockMovementQuery): AsyncGenerator<StockMovement, void, undefined>;
+    createWebhook(options: CreateInventoryWebhookOptions): Promise<InventoryWebhookWithSecret>;
+    updateWebhook(webhookId: string, patch: InventoryWebhookPatch): Promise<InventoryWebhook>;
+    deleteWebhook(webhookId: string): Promise<{
+        webhookId: string;
+        deleted: boolean;
+    }>;
+    listWebhooks(): Promise<InventoryWebhookList>;
+    sendWebhookTest(webhookId: string, event: InventoryWebhookEventType | (string & {})): Promise<InventoryWebhookTestResult>;
+    rotateWebhookSecret(webhookId: string): Promise<InventoryWebhookWithSecret>;
+    listWebhookDeliveries(options?: {
+        webhookId?: string;
+        limit?: number;
+    }): Promise<InventoryWebhookDelivery[]>;
+    createArticle(request: CreateArticleRequest): Promise<Article>;
+    updateArticle(request: UpdateArticleRequest): Promise<Article>;
+    deactivateArticle(request: DeactivateArticleRequest): Promise<Article>;
+    receiveGoods(request: ReceiveGoodsRequest): Promise<StockOperation>;
+    /** `receiveGoods` mit `dryRun: true`: rechnet, schreibt nichts, Schluessel freigestellt. */
+    previewGoodsReceipt(request: GoodsReceiptPreviewRequest): Promise<GoodsReceiptPreview>;
+    transferStock(request: TransferStockRequest): Promise<StockOperation>;
+    recordStockLoss(request: RecordStockLossRequest): Promise<StockOperation>;
+    changeStockCondition(request: ChangeStockConditionRequest): Promise<StockOperation>;
+    reverseStockMovement(request: ReverseStockMovementRequest): Promise<StockOperation>;
+    createReservation(request: CreateReservationRequest): Promise<Reservation>;
+    extendReservation(request: ExtendReservationRequest): Promise<Reservation>;
+    releaseReservation(request: ReleaseReservationRequest): Promise<Reservation>;
+    getReservation(reservationId: string): Promise<Reservation>;
+    listReservations(query?: ReservationListQuery): Promise<ReservationPage>;
+    iterateReservations(query?: ReservationListQuery): AsyncGenerator<Reservation, void, undefined>;
+}
+export declare function createInventoryClient(options: InventoryClientOptions): InventoryClient;

package/dist/cjs/inventory/api.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Fassade ueber den Aufrufen der Lager-API (lesen, Webhooks, schreiben,
+ * reservieren): Schluessel einmal binden, dann rufen. Wie [createInvoiceApi] bewusst keine Klasse; die Aufrufe sind freie
+ * Funktionen (endpunkte.ts) und bleiben einzeln importierbar.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInventoryClient = createInventoryClient;
+const transport_js_1 = require("../client/transport.js");
+const auth_js_1 = require("./auth.js");
+const endpunkte_js_1 = require("./endpunkte.js");
+const schreiben_js_1 = require("./schreiben.js");
+function createInventoryClient(options) {
+    const rufen = (0, transport_js_1.createTransport)({
+        auth: (0, auth_js_1.inventoryKeyAuth)({ apiKey: options.apiKey }),
+        baseUrl: options.baseUrl,
+        timeoutMs: options.timeoutMs,
+        fetch: options.fetch,
+    });
+    return {
+        getArticle: (id) => (0, endpunkte_js_1.getArticle)(rufen, id),
+        listArticles: (q) => (0, endpunkte_js_1.listArticles)(rufen, q),
+        iterateArticles: (q) => (0, endpunkte_js_1.iterateArticles)(rufen, q),
+        lookupArticleByCode: (l) => (0, endpunkte_js_1.lookupArticleByCode)(rufen, l),
+        listLocations: () => (0, endpunkte_js_1.listLocations)(rufen),
+        getStock: (id) => (0, endpunkte_js_1.getStock)(rufen, id),
+        listStock: (q) => (0, endpunkte_js_1.listStock)(rufen, q),
+        iterateStock: (q) => (0, endpunkte_js_1.iterateStock)(rufen, q),
+        listStockMovements: (q) => (0, endpunkte_js_1.listStockMovements)(rufen, q),
+        iterateStockMovements: (q) => (0, endpunkte_js_1.iterateStockMovements)(rufen, q),
+        createWebhook: (o) => (0, endpunkte_js_1.createWebhook)(rufen, o),
+        updateWebhook: (id, patch) => (0, endpunkte_js_1.updateWebhook)(rufen, id, patch),
+        deleteWebhook: (id) => (0, endpunkte_js_1.deleteWebhook)(rufen, id),
+        listWebhooks: () => (0, endpunkte_js_1.listWebhooks)(rufen),
+        sendWebhookTest: (id, event) => (0, endpunkte_js_1.sendWebhookTest)(rufen, id, event),
+        rotateWebhookSecret: (id) => (0, endpunkte_js_1.rotateWebhookSecret)(rufen, id),
+        listWebhookDeliveries: (o) => (0, endpunkte_js_1.listWebhookDeliveries)(rufen, o),
+        createArticle: (r) => (0, schreiben_js_1.createArticle)(rufen, r),
+        updateArticle: (r) => (0, schreiben_js_1.updateArticle)(rufen, r),
+        deactivateArticle: (r) => (0, schreiben_js_1.deactivateArticle)(rufen, r),
+        receiveGoods: (r) => (0, schreiben_js_1.receiveGoods)(rufen, r),
+        previewGoodsReceipt: (r) => (0, schreiben_js_1.previewGoodsReceipt)(rufen, r),
+        transferStock: (r) => (0, schreiben_js_1.transferStock)(rufen, r),
+        recordStockLoss: (r) => (0, schreiben_js_1.recordStockLoss)(rufen, r),
+        changeStockCondition: (r) => (0, schreiben_js_1.changeStockCondition)(rufen, r),
+        reverseStockMovement: (r) => (0, schreiben_js_1.reverseStockMovement)(rufen, r),
+        createReservation: (r) => (0, schreiben_js_1.createReservation)(rufen, r),
+        extendReservation: (r) => (0, schreiben_js_1.extendReservation)(rufen, r),
+        releaseReservation: (r) => (0, schreiben_js_1.releaseReservation)(rufen, r),
+        getReservation: (id) => (0, schreiben_js_1.getReservation)(rufen, id),
+        listReservations: (q) => (0, schreiben_js_1.listReservations)(rufen, q),
+        iterateReservations: (q) => (0, schreiben_js_1.iterateReservations)(rufen, q),
+    };
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Anmeldung fuer die Lager-API: der `api_key` des Kontos als Bearer, ohne
+ * `cashregister-token` (gelesen wird am Konto, nicht an einer Kasse).
+ *
+ * **Der Schluessel gehoert auf einen Server**, etwa in das Backend eines
+ * Online-Shops, nie in ein Browser-Buendel.
+ *
+ * Geprueft wird nur, was ohne Netz sicher falsch ist: ein leerer Wert, ein
+ * Partner-Schluessel (`pk_…`) oder ein Kassen-Token (`cb_…`). Die Meldung
+ * nennt nie den Wert, nur seine Art.
+ */
+import type { KasseneckAuth } from '../client/auth.js';
+export interface InventoryKeyAuthOptions {
+    /** `api_key` des Kontos, z. B. `kr_live_…` oder `kr_test_…`. */
+    apiKey: string;
+}
+export declare function inventoryKeyAuth(options: InventoryKeyAuthOptions): KasseneckAuth;

package/dist/cjs/inventory/auth.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Anmeldung fuer die Lager-API: der `api_key` des Kontos als Bearer, ohne
+ * `cashregister-token` (gelesen wird am Konto, nicht an einer Kasse).
+ *
+ * **Der Schluessel gehoert auf einen Server**, etwa in das Backend eines
+ * Online-Shops, nie in ein Browser-Buendel.
+ *
+ * Geprueft wird nur, was ohne Netz sicher falsch ist: ein leerer Wert, ein
+ * Partner-Schluessel (`pk_…`) oder ein Kassen-Token (`cb_…`). Die Meldung
+ * nennt nie den Wert, nur seine Art.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inventoryKeyAuth = inventoryKeyAuth;
+const errors_js_1 = require("../client/errors.js");
+function inventoryKeyAuth(options) {
+    const schluessel = typeof options?.apiKey === 'string' ? options.apiKey.trim() : '';
+    if (!schluessel)
+        throw new errors_js_1.KasseneckAuthError('inventoryKeyAuth: apiKey fehlt');
+    if (/^pk_(live|test)_/i.test(schluessel)) {
+        throw new errors_js_1.KasseneckAuthError('inventoryKeyAuth: das ist ein Partner-Schluessel (pk_…); die Lager-API nimmt den api_key des Kontos (kr_…)');
+    }
+    if (/^cb_(live|test)_/i.test(schluessel)) {
+        throw new errors_js_1.KasseneckAuthError('inventoryKeyAuth: das ist ein Kassen-Token (cb_…); die Lager-API nimmt den api_key des Kontos (kr_…)');
+    }
+    return () => ({ headers: { Authorization: `Bearer ${schluessel}` }, params: {} });
+}

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

@@ -0,0 +1,91 @@
+/**
+ * Die Aufrufe der Lager-API: Artikel, Standorte, Bestand und Bewegungen
+ * lesen, Konto-Webhooks verwalten (Backend Stufe 5a). Die schreibenden
+ * Aufrufe (Stufe 5b) stehen in `schreiben.ts` und teilen die Helfer hier.
+ *
+ * Jede Funktion nimmt den Transport als ersten Parameter und ist einzeln
+ * importierbar; die Fassade [createInventoryClient] bindet ihn nur einmal.
+ *
+ * **Geprueft wird hier nur, was ohne Netz sicher falsch ist** (leere Kennung,
+ * `limit` ausserhalb 1–200, eine Aenderung ohne Feld). Alles Fachliche prueft
+ * der Server und meldet es als `validation` mit `errors[]`; zwei Pruefungen
+ * hiessen zwei Wahrheiten.
+ *
+ * Lesen hat keine Wirkung: nach einem Zeitlimit darf derselbe Aufruf
+ * wiederholt werden. Bei `rate_limited` vorher `retryAfterSec` warten
+ * ([inventoryRetryAfterSec]).
+ */
+import type { ApiCall, InternerTransport } from '../client/aufrufe.js';
+import { KasseneckValidationError } from '../client/errors.js';
+import type { Article, ArticleListQuery, ArticleLookup, ArticlePage, CreateInventoryWebhookOptions, InventoryWebhook, InventoryWebhookDelivery, InventoryWebhookList, InventoryWebhookPatch, InventoryWebhookTestResult, InventoryWebhookWithSecret, Location, StockLevel, StockListQuery, StockMovement, StockMovementPage, StockMovementQuery, StockPage, StockResult } from './typen.js';
+type Params = Record<string, unknown>;
+export declare function anfragefehler(name: ApiCall, grund: string): KasseneckValidationError;
+/** Eine Kennung, die gesendet werden muss: Text mit mindestens einem Zeichen ausser Leerraum. */
+export declare function kennung(name: ApiCall, feld: string, wert: unknown): string;
+/**
+ * Die Abfrage einer Liste als Parameter. Unbekannte Felder gehen unveraendert
+ * hinaus (der Server weist sie mit `validation` ab), `undefined` faellt weg.
+ */
+export declare function abfrage(name: ApiCall, query: object | undefined): Params;
+/**
+ * Blaettert ueber alle Seiten, Eintrag fuer Eintrag. Derselbe Cursor zweimal
+ * waere eine Endlosschleife: dann endet die Schleife mit einem Antwortfehler.
+ */
+export declare function seitenweise<T>(name: ApiCall, start: string | undefined, seite: (cursor: string | undefined) => Promise<{
+    eintraege: T[];
+    nextCursor: string | null;
+}>): AsyncGenerator<T, void, undefined>;
+export declare function getArticle(transport: InternerTransport, articleId: string): Promise<Article>;
+export declare function listArticles(transport: InternerTransport, query?: ArticleListQuery): Promise<ArticlePage>;
+/** Alle Artikel der Abfrage, Seite fuer Seite ueber `nextCursor`. */
+export declare function iterateArticles(transport: InternerTransport, query?: ArticleListQuery): AsyncGenerator<Article, void, undefined>;
+/**
+ * Ein aktiver Artikel per Code (`number`, `ean` oder `internalCode`) oder per
+ * eigener Kennung aus `externalIds` (`{ externalSystem: 'shop', externalId: '4711' }`).
+ * Ein stillgelegter Artikel gilt als nicht gefunden (`article_not_found`).
+ */
+export declare function lookupArticleByCode(transport: InternerTransport, lookup: ArticleLookup): Promise<Article>;
+/** Alle Standorte des Kontos, samt aufgeloesten (`active: false`) und dem Hauptstandort. */
+export declare function listLocations(transport: InternerTransport): Promise<Location[]>;
+/** Bestand eines Artikels je Standort. */
+export declare function getStock(transport: InternerTransport, articleId: string): Promise<StockResult>;
+export declare function listStock(transport: InternerTransport, query?: StockListQuery): Promise<StockPage>;
+/**
+ * Alle Bestandszeilen der Abfrage, Seite fuer Seite. Die Werte (`values`)
+ * stehen je Seite in [listStock]; der Iterator liefert nur die Zeilen.
+ */
+export declare function iterateStock(transport: InternerTransport, query?: StockListQuery): AsyncGenerator<StockLevel, void, undefined>;
+/** Das Lagerprotokoll, neueste zuerst. */
+export declare function listStockMovements(transport: InternerTransport, query?: StockMovementQuery): Promise<StockMovementPage>;
+export declare function iterateStockMovements(transport: InternerTransport, query?: StockMovementQuery): AsyncGenerator<StockMovement, void, undefined>;
+/**
+ * Legt einen Webhook an (hoechstens 5 je Konto, `webhook_limit`).
+ * **Das Secret in der Antwort kommt nur dieses eine Mal**; sofort dorthin
+ * schreiben, wo der Empfaenger es liest, nicht in ein Protokoll.
+ */
+export declare function createWebhook(transport: InternerTransport, options: CreateInventoryWebhookOptions): Promise<InventoryWebhookWithSecret>;
+/** Aendert nur die genannten Felder; `description: null` loescht die Beschreibung. */
+export declare function updateWebhook(transport: InternerTransport, webhookId: string, patch: InventoryWebhookPatch): Promise<InventoryWebhook>;
+export declare function deleteWebhook(transport: InternerTransport, webhookId: string): Promise<{
+    webhookId: string;
+    deleted: boolean;
+}>;
+/** Die Webhooks des Kontos und die Ereignisse, die es abonnieren kann. */
+export declare function listWebhooks(transport: InternerTransport): Promise<InventoryWebhookList>;
+/**
+ * Ein neues Secret fuer denselben Webhook. Ab der Antwort gilt nur noch das
+ * neue (keine Uebergangsfrist): erst speichern, dann weiterarbeiten.
+ */
+export declare function rotateWebhookSecret(transport: InternerTransport, webhookId: string): Promise<InventoryWebhookWithSecret>;
+/**
+ * Eine Probe genau dieses Ereignisses an genau diesen Webhook, mit erfundener
+ * Nutzlast und `test: true` in der Huelle. Der Webhook muss das Ereignis
+ * abonnieren (`event_not_subscribed`) und aktiv sein (`webhook_inactive`).
+ */
+export declare function sendWebhookTest(transport: InternerTransport, webhookId: string, event: string): Promise<InventoryWebhookTestResult>;
+/** Die letzten Zustellungen, neueste zuerst; mit `webhookId` nur die eines Webhooks. */
+export declare function listWebhookDeliveries(transport: InternerTransport, options?: {
+    webhookId?: string;
+    limit?: number;
+}): Promise<InventoryWebhookDelivery[]>;
+export {};

package/dist/cjs/inventory/endpunkte.js

@@ -0,0 +1,290 @@
+"use strict";
+/**
+ * Die Aufrufe der Lager-API: Artikel, Standorte, Bestand und Bewegungen
+ * lesen, Konto-Webhooks verwalten (Backend Stufe 5a). Die schreibenden
+ * Aufrufe (Stufe 5b) stehen in `schreiben.ts` und teilen die Helfer hier.
+ *
+ * Jede Funktion nimmt den Transport als ersten Parameter und ist einzeln
+ * importierbar; die Fassade [createInventoryClient] bindet ihn nur einmal.
+ *
+ * **Geprueft wird hier nur, was ohne Netz sicher falsch ist** (leere Kennung,
+ * `limit` ausserhalb 1–200, eine Aenderung ohne Feld). Alles Fachliche prueft
+ * der Server und meldet es als `validation` mit `errors[]`; zwei Pruefungen
+ * hiessen zwei Wahrheiten.
+ *
+ * Lesen hat keine Wirkung: nach einem Zeitlimit darf derselbe Aufruf
+ * wiederholt werden. Bei `rate_limited` vorher `retryAfterSec` warten
+ * ([inventoryRetryAfterSec]).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.anfragefehler = anfragefehler;
+exports.kennung = kennung;
+exports.abfrage = abfrage;
+exports.seitenweise = seitenweise;
+exports.getArticle = getArticle;
+exports.listArticles = listArticles;
+exports.iterateArticles = iterateArticles;
+exports.lookupArticleByCode = lookupArticleByCode;
+exports.listLocations = listLocations;
+exports.getStock = getStock;
+exports.listStock = listStock;
+exports.iterateStock = iterateStock;
+exports.listStockMovements = listStockMovements;
+exports.iterateStockMovements = iterateStockMovements;
+exports.createWebhook = createWebhook;
+exports.updateWebhook = updateWebhook;
+exports.deleteWebhook = deleteWebhook;
+exports.listWebhooks = listWebhooks;
+exports.rotateWebhookSecret = rotateWebhookSecret;
+exports.sendWebhookTest = sendWebhookTest;
+exports.listWebhookDeliveries = listWebhookDeliveries;
+const errors_js_1 = require("../client/errors.js");
+const lesen_js_1 = require("./lesen.js");
+const vertrag_js_1 = require("./vertrag.js");
+function anfragefehler(name, grund) {
+    return new errors_js_1.KasseneckValidationError(name, grund, 'request');
+}
+/** Eine Kennung, die gesendet werden muss: Text mit mindestens einem Zeichen ausser Leerraum. */
+function kennung(name, feld, wert) {
+    if (typeof wert !== 'string' || wert.trim() === '')
+        throw anfragefehler(name, `${feld} fehlt`);
+    return wert;
+}
+/** Felder, die einen Zeitpunkt tragen: ein `Date` geht als ISO 8601 UTC hinaus. */
+const ZEITFELDER = new Set(['updatedSince', 'changedSince', 'from', 'to']);
+/**
+ * Die Abfrage einer Liste als Parameter. Unbekannte Felder gehen unveraendert
+ * hinaus (der Server weist sie mit `validation` ab), `undefined` faellt weg.
+ */
+function abfrage(name, query) {
+    if (query === undefined || query === null)
+        return {};
+    if (typeof query !== 'object' || Array.isArray(query))
+        throw anfragefehler(name, 'Abfrage muss ein Objekt sein');
+    const raus = {};
+    for (const [feld, w] of Object.entries(query)) {
+        if (w === undefined)
+            continue;
+        if (ZEITFELDER.has(feld) && w instanceof Date) {
+            if (Number.isNaN(w.getTime()))
+                throw anfragefehler(name, `${feld} ist kein gueltiger Zeitpunkt`);
+            raus[feld] = w.toISOString();
+            continue;
+        }
+        raus[feld] = w;
+    }
+    if (raus.limit !== undefined) {
+        const limit = raus.limit;
+        if (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > vertrag_js_1.INVENTORY_LIST_LIMIT_MAX) {
+            throw anfragefehler(name, `limit muss eine ganze Zahl von 1 bis ${vertrag_js_1.INVENTORY_LIST_LIMIT_MAX} sein`);
+        }
+    }
+    if (raus.cursor !== undefined)
+        kennung(name, 'cursor', raus.cursor);
+    return raus;
+}
+/**
+ * Blaettert ueber alle Seiten, Eintrag fuer Eintrag. Derselbe Cursor zweimal
+ * waere eine Endlosschleife: dann endet die Schleife mit einem Antwortfehler.
+ */
+async function* seitenweise(name, start, seite) {
+    const gesehen = new Set();
+    // Auch der Startcursor zaehlt: nennt die erste Antwort ihn wieder, waere es dieselbe Seite.
+    if (start)
+        gesehen.add(start);
+    let cursor = start;
+    for (;;) {
+        const { eintraege, nextCursor } = await seite(cursor);
+        yield* eintraege;
+        if (nextCursor === null)
+            return;
+        if (gesehen.has(nextCursor))
+            throw (0, lesen_js_1.antwortfehler)(name, 'Antwort nennt denselben nextCursor zweimal');
+        gesehen.add(nextCursor);
+        cursor = nextCursor;
+    }
+}
+// ---- Artikel ------------------------------------------------------------------
+async function getArticle(transport, articleId) {
+    const name = 'getArticle';
+    const daten = await transport(name, { articleId: kennung(name, 'articleId', articleId) });
+    return (0, lesen_js_1.artikel)({ name, pfad: 'article' }, (0, lesen_js_1.objekt)(daten)?.article);
+}
+async function listArticles(transport, query) {
+    const name = 'listArticles';
+    const daten = await transport(name, abfrage(name, query));
+    return { articles: (0, lesen_js_1.liste)(name, daten, 'articles', lesen_js_1.artikel), nextCursor: (0, lesen_js_1.naechsterCursor)(name, daten) };
+}
+/** Alle Artikel der Abfrage, Seite fuer Seite ueber `nextCursor`. */
+function iterateArticles(transport, query) {
+    const { cursor, ...rest } = query ?? {};
+    return seitenweise('listArticles', cursor, async (c) => {
+        const s = await listArticles(transport, { ...rest, cursor: c });
+        return { eintraege: s.articles, nextCursor: s.nextCursor };
+    });
+}
+/**
+ * Ein aktiver Artikel per Code (`number`, `ean` oder `internalCode`) oder per
+ * eigener Kennung aus `externalIds` (`{ externalSystem: 'shop', externalId: '4711' }`).
+ * Ein stillgelegter Artikel gilt als nicht gefunden (`article_not_found`).
+ */
+async function lookupArticleByCode(transport, lookup) {
+    const name = 'lookupArticleByCode';
+    let params;
+    if (typeof lookup === 'string') {
+        params = { code: kennung(name, 'code', lookup) };
+    }
+    else if (lookup !== null && typeof lookup === 'object' && !Array.isArray(lookup)) {
+        const l = lookup;
+        const extern = l.externalSystem !== undefined || l.externalId !== undefined;
+        if (l.code !== undefined && extern)
+            throw anfragefehler(name, 'entweder code oder externalSystem mit externalId');
+        params = extern
+            ? { externalSystem: kennung(name, 'externalSystem', l.externalSystem), externalId: kennung(name, 'externalId', l.externalId) }
+            : { code: kennung(name, 'code', l.code) };
+    }
+    else {
+        throw anfragefehler(name, 'Code als Text oder { code } bzw. { externalSystem, externalId } erwartet');
+    }
+    const daten = await transport(name, params);
+    return (0, lesen_js_1.artikel)({ name, pfad: 'article' }, (0, lesen_js_1.objekt)(daten)?.article);
+}
+// ---- Standorte und Bestand -----------------------------------------------------------
+/** Alle Standorte des Kontos, samt aufgeloesten (`active: false`) und dem Hauptstandort. */
+async function listLocations(transport) {
+    const name = 'listLocations';
+    return (0, lesen_js_1.liste)(name, await transport(name, {}), 'locations', lesen_js_1.standort);
+}
+/** Die Werte (`values`): fehlt das Feld, fehlt das Recht `costs` -> `null`, nie `[]`. */
+function werte(name, daten) {
+    const roh = (0, lesen_js_1.objekt)(daten)?.values;
+    if (roh === undefined || roh === null)
+        return null;
+    return (0, lesen_js_1.liste)(name, daten, 'values', lesen_js_1.wert);
+}
+/** Bestand eines Artikels je Standort. */
+async function getStock(transport, articleId) {
+    const name = 'getStock';
+    const daten = await transport(name, { articleId: kennung(name, 'articleId', articleId) });
+    return { stock: (0, lesen_js_1.liste)(name, daten, 'stock', lesen_js_1.bestand), values: werte(name, daten) };
+}
+async function listStock(transport, query) {
+    const name = 'listStock';
+    const daten = await transport(name, abfrage(name, query));
+    return { stock: (0, lesen_js_1.liste)(name, daten, 'stock', lesen_js_1.bestand), values: werte(name, daten), nextCursor: (0, lesen_js_1.naechsterCursor)(name, daten) };
+}
+/**
+ * Alle Bestandszeilen der Abfrage, Seite fuer Seite. Die Werte (`values`)
+ * stehen je Seite in [listStock]; der Iterator liefert nur die Zeilen.
+ */
+function iterateStock(transport, query) {
+    const { cursor, ...rest } = query ?? {};
+    return seitenweise('listStock', cursor, async (c) => {
+        const s = await listStock(transport, { ...rest, cursor: c });
+        return { eintraege: s.stock, nextCursor: s.nextCursor };
+    });
+}
+/** Das Lagerprotokoll, neueste zuerst. */
+async function listStockMovements(transport, query) {
+    const name = 'listStockMovements';
+    const daten = await transport(name, abfrage(name, query));
+    return { movements: (0, lesen_js_1.liste)(name, daten, 'movements', lesen_js_1.bewegung), nextCursor: (0, lesen_js_1.naechsterCursor)(name, daten) };
+}
+function iterateStockMovements(transport, query) {
+    const { cursor, ...rest } = query ?? {};
+    return seitenweise('listStockMovements', cursor, async (c) => {
+        const s = await listStockMovements(transport, { ...rest, cursor: c });
+        return { eintraege: s.movements, nextCursor: s.nextCursor };
+    });
+}
+// ---- Webhooks ------------------------------------------------------------------
+function mitSecret(name, daten) {
+    const o = (0, lesen_js_1.objekt)(daten);
+    const secret = o?.secret;
+    if (typeof secret !== 'string' || secret === '') {
+        throw (0, lesen_js_1.antwortfehler)(name, 'Antwort enthaelt kein secret; ohne es laesst sich keine Zustellung pruefen');
+    }
+    return { webhook: (0, lesen_js_1.webhook)({ name, pfad: 'webhook' }, o?.webhook), secret };
+}
+/**
+ * Legt einen Webhook an (hoechstens 5 je Konto, `webhook_limit`).
+ * **Das Secret in der Antwort kommt nur dieses eine Mal**; sofort dorthin
+ * schreiben, wo der Empfaenger es liest, nicht in ein Protokoll.
+ */
+async function createWebhook(transport, options) {
+    const name = 'createWebhook';
+    const url = kennung(name, 'url', options?.url);
+    if (!Array.isArray(options.events) || options.events.length === 0) {
+        throw anfragefehler(name, 'events ist leer; ein Webhook ohne Ereignis bekaeme nie etwas');
+    }
+    const params = { url, events: options.events };
+    if (options.description !== undefined)
+        params.description = options.description;
+    return mitSecret(name, await transport(name, params));
+}
+/** Aendert nur die genannten Felder; `description: null` loescht die Beschreibung. */
+async function updateWebhook(transport, webhookId, patch) {
+    const name = 'updateWebhook';
+    const id = kennung(name, 'webhookId', webhookId);
+    if (patch === null || typeof patch !== 'object' || Array.isArray(patch))
+        throw anfragefehler(name, 'patch muss ein Objekt sein');
+    const params = { webhookId: id };
+    for (const [feld, w] of Object.entries(patch))
+        if (w !== undefined)
+            params[feld] = w;
+    if (Object.keys(params).length === 1)
+        throw anfragefehler(name, 'patch nennt keine Aenderung');
+    const daten = await transport(name, params);
+    return (0, lesen_js_1.webhook)({ name, pfad: 'webhook' }, (0, lesen_js_1.objekt)(daten)?.webhook);
+}
+async function deleteWebhook(transport, webhookId) {
+    const name = 'deleteWebhook';
+    const id = kennung(name, 'webhookId', webhookId);
+    const o = (0, lesen_js_1.objekt)(await transport(name, { webhookId: id }));
+    return { webhookId: typeof o?.webhookId === 'string' && o.webhookId ? o.webhookId : id, deleted: o?.deleted === true };
+}
+/** Die Webhooks des Kontos und die Ereignisse, die es abonnieren kann. */
+async function listWebhooks(transport) {
+    const name = 'listWebhooks';
+    const daten = await transport(name, {});
+    const ereignisse = (0, lesen_js_1.objekt)(daten)?.events;
+    return {
+        webhooks: (0, lesen_js_1.liste)(name, daten, 'webhooks', lesen_js_1.webhook),
+        events: Array.isArray(ereignisse) ? ereignisse.filter((e) => typeof e === 'string') : [],
+    };
+}
+/**
+ * Ein neues Secret fuer denselben Webhook. Ab der Antwort gilt nur noch das
+ * neue (keine Uebergangsfrist): erst speichern, dann weiterarbeiten.
+ */
+async function rotateWebhookSecret(transport, webhookId) {
+    const name = 'rotateWebhookSecret';
+    return mitSecret(name, await transport(name, { webhookId: kennung(name, 'webhookId', webhookId) }));
+}
+/**
+ * Eine Probe genau dieses Ereignisses an genau diesen Webhook, mit erfundener
+ * Nutzlast und `test: true` in der Huelle. Der Webhook muss das Ereignis
+ * abonnieren (`event_not_subscribed`) und aktiv sein (`webhook_inactive`).
+ */
+async function sendWebhookTest(transport, webhookId, event) {
+    const name = 'sendWebhookTest';
+    const id = kennung(name, 'webhookId', webhookId);
+    const ereignis = kennung(name, 'event', event);
+    const daten = await transport(name, { webhookId: id, event: ereignis });
+    const o = (0, lesen_js_1.objekt)(daten);
+    return {
+        eventId: typeof o?.eventId === 'string' ? o.eventId : '',
+        event: typeof o?.event === 'string' ? o.event : ereignis,
+        deliveries: (0, lesen_js_1.liste)(name, daten, 'deliveries', (ort, e) => (0, lesen_js_1.probeZustellung)(ort, e, id)),
+    };
+}
+/** Die letzten Zustellungen, neueste zuerst; mit `webhookId` nur die eines Webhooks. */
+async function listWebhookDeliveries(transport, options = {}) {
+    const name = 'listWebhookDeliveries';
+    const params = {};
+    if (options.webhookId !== undefined)
+        params.webhookId = kennung(name, 'webhookId', options.webhookId);
+    if (options.limit !== undefined)
+        Object.assign(params, abfrage(name, { limit: options.limit }));
+    return (0, lesen_js_1.liste)(name, await transport(name, params), 'deliveries', lesen_js_1.zustellung);
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Fehler der Lager-API auswerten: am Code, nie am Text.
+ *
+ * Es zaehlen die Codes der Lager-Endpunkte ([INVENTORY_ERROR_CODES]) und die,
+ * die Anmeldung und Rand auf jedem Aufruf erzeugen koennen
+ * ([INVENTORY_REQUEST_ERROR_CODES]). Ein fremder Code ist fuer diese Helfer
+ * kein Lager-Fehler: wer darauf verzweigt, tut es bewusst ueber
+ * `KasseneckApiError.code`.
+ */
+import type { KasseneckApiError } from '../client/errors.js';
+import type { InventoryShortfall } from './typen.js';
+import { type InventoryErrorCode, type InventoryRequestErrorCode, type InventoryWarningCode } from './vertrag.js';
+/** Ein Code, den ein Lager-Aufruf liefern kann. */
+export type InventoryApiErrorCode = InventoryErrorCode | InventoryRequestErrorCode;
+export declare function isInventoryErrorCode(value: unknown): value is InventoryApiErrorCode;
+/** Der Fehlercode eines geworfenen Fehlers; `undefined`, wenn es keiner der Lager-API ist. */
+export declare function inventoryErrorCode(error: unknown): InventoryApiErrorCode | undefined;
+/** Kurzform fuer `catch (e) { if (isInventoryError(e, 'article_not_found')) … }`. */
+export declare function isInventoryError(error: unknown, code?: InventoryApiErrorCode): error is KasseneckApiError;
+/** Ein Feldfehler aus `data.errors[]` einer `validation`-Antwort. */
+export interface InventoryFieldError {
+    /** Feld der gesendeten Anfrage, z. B. `limit` oder `events`. */
+    field: string;
+    message: string;
+}
+/** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
+export declare function inventoryFieldErrors(error: unknown): InventoryFieldError[];
+/**
+ * Wie lange `rate_limited` noch gilt, in Sekunden (`data.retryAfterSec`,
+ * dasselbe wie die Kopfzeile `Retry-After`). `undefined`, wenn der Fehler kein
+ * `rate_limited` ist oder der Server keine Angabe macht. Die Grenze gilt je
+ * Konto (etwa 20 Anfragen je Sekunde, kurze Spitzen bis 40).
+ */
+export declare function inventoryRetryAfterSec(error: unknown): number | undefined;
+/**
+ * Die Positionen, fuer die beim Reservieren der verfuegbare Bestand nicht
+ * reicht (`insufficient_available`, `data.details[]`): je Artikel und Standort
+ * angefragt und verfuegbar, in Tausendstel. Leer, wenn der Fehler ein anderer
+ * ist. Es fehlen nur diese Positionen; reserviert wurde nichts.
+ */
+export declare function inventoryShortfalls(error: unknown): InventoryShortfall[];
+/** `true` fuer einen Hinweis-Code einer Buchung (`warnings[].code`); Hinweise sind nie Fehler. */
+export declare function isInventoryWarningCode(value: unknown): value is InventoryWarningCode;

package/dist/cjs/inventory/fehler.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Fehler der Lager-API auswerten: am Code, nie am Text.
+ *
+ * Es zaehlen die Codes der Lager-Endpunkte ([INVENTORY_ERROR_CODES]) und die,
+ * die Anmeldung und Rand auf jedem Aufruf erzeugen koennen
+ * ([INVENTORY_REQUEST_ERROR_CODES]). Ein fremder Code ist fuer diese Helfer
+ * kein Lager-Fehler: wer darauf verzweigt, tut es bewusst ueber
+ * `KasseneckApiError.code`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInventoryErrorCode = isInventoryErrorCode;
+exports.inventoryErrorCode = inventoryErrorCode;
+exports.isInventoryError = isInventoryError;
+exports.inventoryFieldErrors = inventoryFieldErrors;
+exports.inventoryRetryAfterSec = inventoryRetryAfterSec;
+exports.inventoryShortfalls = inventoryShortfalls;
+exports.isInventoryWarningCode = isInventoryWarningCode;
+const fehlercodes_js_1 = require("../client/fehlercodes.js");
+const lesen_js_1 = require("./lesen.js");
+const vertrag_js_1 = require("./vertrag.js");
+const BEKANNT = new Set([...vertrag_js_1.INVENTORY_ERROR_CODES, ...vertrag_js_1.INVENTORY_REQUEST_ERROR_CODES]);
+function isInventoryErrorCode(value) {
+    return typeof value === 'string' && BEKANNT.has(value);
+}
+/** Der Fehlercode eines geworfenen Fehlers; `undefined`, wenn es keiner der Lager-API ist. */
+function inventoryErrorCode(error) {
+    return (0, fehlercodes_js_1.bekannterCode)(error, BEKANNT);
+}
+/** Kurzform fuer `catch (e) { if (isInventoryError(e, 'article_not_found')) … }`. */
+function isInventoryError(error, code) {
+    const gefunden = inventoryErrorCode(error);
+    return gefunden !== undefined && (code === undefined || gefunden === code);
+}
+/** Die Feldfehler einer `validation`-Antwort; leer, wenn es keine sind. */
+function inventoryFieldErrors(error) {
+    return (0, fehlercodes_js_1.feldfehlerVon)(error);
+}
+/**
+ * Wie lange `rate_limited` noch gilt, in Sekunden (`data.retryAfterSec`,
+ * dasselbe wie die Kopfzeile `Retry-After`). `undefined`, wenn der Fehler kein
+ * `rate_limited` ist oder der Server keine Angabe macht. Die Grenze gilt je
+ * Konto (etwa 20 Anfragen je Sekunde, kurze Spitzen bis 40).
+ */
+function inventoryRetryAfterSec(error) {
+    if (inventoryErrorCode(error) !== 'rate_limited')
+        return undefined;
+    const wert = error.details['retryAfterSec'];
+    return typeof wert === 'number' && Number.isFinite(wert) && wert >= 0 ? wert : undefined;
+}
+/**
+ * Die Positionen, fuer die beim Reservieren der verfuegbare Bestand nicht
+ * reicht (`insufficient_available`, `data.details[]`): je Artikel und Standort
+ * angefragt und verfuegbar, in Tausendstel. Leer, wenn der Fehler ein anderer
+ * ist. Es fehlen nur diese Positionen; reserviert wurde nichts.
+ */
+function inventoryShortfalls(error) {
+    if (inventoryErrorCode(error) !== 'insufficient_available')
+        return [];
+    return (0, lesen_js_1.fehlmengen)(error.details['details']);
+}
+const HINWEISE = new Set(vertrag_js_1.INVENTORY_WARNING_CODES);
+/** `true` fuer einen Hinweis-Code einer Buchung (`warnings[].code`); Hinweise sind nie Fehler. */
+function isInventoryWarningCode(value) {
+    return typeof value === 'string' && HINWEISE.has(value);
+}