@kreiseck/kasseneck-api 1.3.0 → 1.5.0

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

@@ -0,0 +1,136 @@
+/**
+ * Der Vertrag der Lager-API (Backend Stufe 5a lesen, 5b schreiben und
+ * reservieren) 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`):
+ * `endpoints.public`, die Kataloge `STANDORT_TYP`, `BEWEGUNG_ART`,
+ * `BEWEGUNG_QUELLE`, `LAGER_ZUSTAND`, `LAGER_URSACHE`, `ZUSTELLUNG`,
+ * `LAGER_ABGANG_GRUND`, `LAGER_ENTNAHME_ART`, `LAGER_NEBENKOSTEN_ART`,
+ * `LAGER_VERTEILUNG`, `RESERVIERUNG_STATUS`, dazu `events`, `errorCodes.inventory`
+ * 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"];
+export type InventoryEndpoint = (typeof INVENTORY_ENDPOINTS)[number];
+/** Art eines Standorts (Katalog `STANDORT_TYP`). */
+export declare const LOCATION_TYPES: readonly ["warehouse", "store", "vehicle", "other"];
+export type LocationType = (typeof LOCATION_TYPES)[number];
+/**
+ * Art einer Lagerbewegung (Katalog `BEWEGUNG_ART`); zugleich der Filter `type`.
+ * `goods_receipt` ist der Wareneingang, `takeover` der uebernommene Anfangsbestand
+ * (auch per Import). `receipt` gibt es hier nicht: das ist der Kassenbeleg (Quelle).
+ * `reservation` (seit 1.5.0) aendert nur `reserved`: `quantityDelta` ist 0, die
+ * Menge steht in `reservedDelta`.
+ */
+export declare const STOCK_MOVEMENT_TYPES: readonly ["sale", "goods_receipt", "loss", "return", "transfer_out", "transfer_in", "condition_out", "condition_in", "stocktake", "adjustment", "takeover", "reversal", "revaluation", "method_change", "reservation"];
+export type StockMovementType = (typeof STOCK_MOVEMENT_TYPES)[number];
+/**
+ * Woher eine Bewegung kommt (Katalog `BEWEGUNG_QUELLE`); zugleich der Filter
+ * `source`. `receipt` ist der Kassenbeleg wie ueberall in der API (der
+ * Wareneingang ist die Bewegungsart `goods_receipt`).
+ */
+export declare const STOCK_MOVEMENT_SOURCES: readonly ["receipt", "invoice", "cancellation", "credit_note", "panel", "register", "api", "stocktake", "system"];
+export type StockMovementSource = (typeof STOCK_MOVEMENT_SOURCES)[number];
+/** Zustand der Ware an einer Bewegung (Katalog `LAGER_ZUSTAND`). */
+export declare const STOCK_CONDITIONS: readonly ["sellable", "defective"];
+export type StockCondition = (typeof STOCK_CONDITIONS)[number];
+/**
+ * Ursache eines `stock.changed` (Katalog `LAGER_URSACHE`), abgeleitet aus der
+ * juengsten Bewegung mit Mengenwirkung. `other`: keine Regel passt oder es
+ * gibt keine Bewegung (dann ist `movementId` `null`).
+ */
+export declare const STOCK_CHANGE_CAUSES: readonly ["sale", "invoice", "credit_note", "cancellation", "goods_receipt", "transfer", "loss", "condition", "reversal", "reservation", "stocktake", "takeover", "other"];
+export type StockChangeCause = (typeof STOCK_CHANGE_CAUSES)[number];
+/** Stand einer Zustellung (Katalog `ZUSTELLUNG`, derselbe wie bei Partner-Webhooks). */
+export declare const WEBHOOK_DELIVERY_STATUSES: readonly ["delivered", "pending", "failed", "dropped"];
+export type WebhookDeliveryStatus = (typeof WEBHOOK_DELIVERY_STATUSES)[number];
+/**
+ * Die Ereignisse, die ein Konto-Webhook abonnieren kann, in der Reihenfolge von
+ * `listWebhooks().events`. `reservation.*` (seit 1.5.0) tragen die Reservierung
+ * 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`).
+ */
+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 type InventoryWebhookEventType = (typeof INVENTORY_WEBHOOK_EVENTS)[number];
+/**
+ * Die Felder der Huelle jeder Zustellung, in der Reihenfolge am Draht. Statt
+ * `partnerId` (Partner-Webhooks) traegt sie `accountId`; `test` steht nur auf
+ * Probesendungen.
+ */
+export declare const INVENTORY_WEBHOOK_ENVELOPE_FIELDS: readonly ["id", "type", "createdAt", "accountId", "test", "data"];
+/** Hoechstzahl der Webhooks je Konto (`webhook_limit`, wie bei Partner-Webhooks). */
+export declare const INVENTORY_WEBHOOK_LIMIT = 5;
+/** Groesstes `limit` einer Liste; ohne Angabe liefert der Server 50. */
+export declare const INVENTORY_LIST_LIMIT_MAX = 200;
+/**
+ * Die Codes, die die Lager-Endpunkte selbst senden (`errorCodes.inventory`;
+ * `register_user_not_allowed` steht bei [INVENTORY_REQUEST_ERROR_CODES]).
+ * `validation` traegt `errors: [{ field, message }]`, `rate_limited` traegt
+ * `retryAfterSec` (dazu die Kopfzeile `Retry-After`) – auch bei
+ * `sendWebhookTest` nach 20 Probesendungen je Wiener Kalendertag (dann bis
+ * Mitternacht in Wien).
+ *
+ * Seit 1.5.0 hinten angehaengt, in der Reihenfolge des Vertrags: die Codes
+ * der schreibenden Endpunkte. `idempotency_key_required` (Schluessel fehlt),
+ * `idempotency_conflict` (derselbe Schluessel mit anderem Inhalt),
+ * `exceeds_stock` (Abgang, Umbuchung und Zustandswechsel ueberziehen nie),
+ * `insufficient_available` (Reservierung; `data.details[]`, siehe
+ * [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` …
+ */
+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 type InventoryErrorCode = (typeof INVENTORY_ERROR_CODES)[number];
+/**
+ * Codes, die Anmeldung und Rand auf jedem Lager-Aufruf erzeugen koennen,
+ * soweit sie nicht schon in [INVENTORY_ERROR_CODES] stehen: `errorCodes.auth`
+ * ohne die des Partner-Zugangs und `errorCodes.edge` (sortiert), zuletzt
+ * `route_missing` (Code des Pakets). Dieselbe Ableitung wie bei der
+ * Rechnungs-API.
+ */
+export declare const INVENTORY_REQUEST_ERROR_CODES: readonly ["account_not_found", "admin_required", "api_not_approved", "cashregister_not_assigned", "cashregister_not_found", "cashregister_token_invalid", "cashregister_token_missing", "dialect_mismatch", "internal_translation_error", "live_not_enabled", "method_not_allowed", "mfa_required", "not_found", "register_user_no_business", "register_user_not_allowed", "register_user_not_found", "response_translation_failed", "session_expired", "session_other_cashregister", "unauthorized", "user_disabled", "user_verification_failed", "route_missing"];
+export type InventoryRequestErrorCode = (typeof INVENTORY_REQUEST_ERROR_CODES)[number];
+/**
+ * Hinweise einer Buchung (`warnings[].code`, `warningCodes.inventory`). Sie sind
+ * keine Fehler: die Buchung hat gewirkt. `insufficient_stock` gibt es nur beim
+ * Verkauf (Abgang, Umbuchung und Zustandswechsel weisen mit `exceeds_stock` ab),
+ * `below_minimum` misst am verfuegbaren Bestand (`onHand − reserved`) gegen den
+ * Mindestbestand des Standorts, `reservation_exceeded` meldet eine Rechnung, die
+ * mehr verkauft als reserviert war.
+ */
+export declare const INVENTORY_WARNING_CODES: readonly ["insufficient_stock", "below_minimum", "return_exceeds_sale", "reservation_exceeded"];
+export type InventoryWarningCode = (typeof INVENTORY_WARNING_CODES)[number];
+/**
+ * Bestandsart eines Artikels (`stockKind`): `quantity` = Menge, `serial` =
+ * Einzelstueck mit Seriennummer. Kein Katalog des Vokabulars, der Server
+ * uebersetzt das Feld selbst; nach der ersten Bewegung fest (`stock_kind_locked`).
+ */
+export declare const STOCK_KINDS: readonly ["quantity", "serial"];
+export type StockKind = (typeof STOCK_KINDS)[number];
+/** Grund eines Abgangs (`recordStockLoss.reason`, Katalog `LAGER_ABGANG_GRUND`). `other` braucht `note`. */
+export declare const STOCK_LOSS_REASONS: readonly ["breakage", "shrinkage", "theft", "expired", "withdrawal", "disposal", "other"];
+export type StockLossReason = (typeof STOCK_LOSS_REASONS)[number];
+/** Art einer Entnahme (`withdrawalType`, Katalog `LAGER_ENTNAHME_ART`); Pflicht bei `reason: 'withdrawal'`, sonst nicht erlaubt. */
+export declare const WITHDRAWAL_TYPES: readonly ["private", "staff", "gift", "sample"];
+export type WithdrawalType = (typeof WITHDRAWAL_TYPES)[number];
+/** Art von Nebenkosten eines Wareneingangs (`landedCosts[].type`, Katalog `LAGER_NEBENKOSTEN_ART`). */
+export declare const LANDED_COST_TYPES: readonly ["freight", "customs", "insurance", "other", "discount", "cash_discount"];
+export type LandedCostType = (typeof LANDED_COST_TYPES)[number];
+/** Verteilung der Nebenkosten (`allocation`, Katalog `LAGER_VERTEILUNG`); Vorgabe des Servers `value`. */
+export declare const LANDED_COST_ALLOCATIONS: readonly ["value", "quantity", "weight", "manual"];
+export type LandedCostAllocation = (typeof LANDED_COST_ALLOCATIONS)[number];
+/**
+ * Stand einer Reservierung (Katalog `RESERVIERUNG_STATUS`). Nur `active` haelt
+ * Ware zurueck; die drei anderen sind endgueltig: `redeemed` (ueber eine
+ * Rechnung eingeloest), `released` (freigegeben), `expired` (abgelaufen).
+ */
+export declare const RESERVATION_STATUSES: readonly ["active", "redeemed", "released", "expired"];
+export type ReservationStatus = (typeof RESERVATION_STATUSES)[number];
+/** Laengster `idempotencyKey` (Zeichen); laenger weist der Server ab, er schneidet nie ab. */
+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;

package/dist/esm/inventory/vertrag.js

@@ -0,0 +1,288 @@
+/**
+ * Der Vertrag der Lager-API (Backend Stufe 5a lesen, 5b schreiben und
+ * reservieren) 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`):
+ * `endpoints.public`, die Kataloge `STANDORT_TYP`, `BEWEGUNG_ART`,
+ * `BEWEGUNG_QUELLE`, `LAGER_ZUSTAND`, `LAGER_URSACHE`, `ZUSTELLUNG`,
+ * `LAGER_ABGANG_GRUND`, `LAGER_ENTNAHME_ART`, `LAGER_NEBENKOSTEN_ART`,
+ * `LAGER_VERTEILUNG`, `RESERVIERUNG_STATUS`, dazu `events`, `errorCodes.inventory`
+ * 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 const INVENTORY_ENDPOINTS = [
+    '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',
+];
+/** Art eines Standorts (Katalog `STANDORT_TYP`). */
+export const LOCATION_TYPES = ['warehouse', 'store', 'vehicle', 'other'];
+/**
+ * Art einer Lagerbewegung (Katalog `BEWEGUNG_ART`); zugleich der Filter `type`.
+ * `goods_receipt` ist der Wareneingang, `takeover` der uebernommene Anfangsbestand
+ * (auch per Import). `receipt` gibt es hier nicht: das ist der Kassenbeleg (Quelle).
+ * `reservation` (seit 1.5.0) aendert nur `reserved`: `quantityDelta` ist 0, die
+ * Menge steht in `reservedDelta`.
+ */
+export const STOCK_MOVEMENT_TYPES = [
+    'sale',
+    'goods_receipt',
+    'loss',
+    'return',
+    'transfer_out',
+    'transfer_in',
+    'condition_out',
+    'condition_in',
+    'stocktake',
+    'adjustment',
+    'takeover',
+    'reversal',
+    'revaluation',
+    'method_change',
+    'reservation',
+];
+/**
+ * Woher eine Bewegung kommt (Katalog `BEWEGUNG_QUELLE`); zugleich der Filter
+ * `source`. `receipt` ist der Kassenbeleg wie ueberall in der API (der
+ * Wareneingang ist die Bewegungsart `goods_receipt`).
+ */
+export const STOCK_MOVEMENT_SOURCES = [
+    'receipt',
+    'invoice',
+    'cancellation',
+    'credit_note',
+    'panel',
+    'register',
+    'api',
+    'stocktake',
+    'system',
+];
+/** Zustand der Ware an einer Bewegung (Katalog `LAGER_ZUSTAND`). */
+export const STOCK_CONDITIONS = ['sellable', 'defective'];
+/**
+ * Ursache eines `stock.changed` (Katalog `LAGER_URSACHE`), abgeleitet aus der
+ * juengsten Bewegung mit Mengenwirkung. `other`: keine Regel passt oder es
+ * gibt keine Bewegung (dann ist `movementId` `null`).
+ */
+export const STOCK_CHANGE_CAUSES = [
+    'sale',
+    'invoice',
+    'credit_note',
+    'cancellation',
+    'goods_receipt',
+    'transfer',
+    'loss',
+    'condition',
+    'reversal',
+    'reservation',
+    'stocktake',
+    'takeover',
+    'other',
+];
+/** Stand einer Zustellung (Katalog `ZUSTELLUNG`, derselbe wie bei Partner-Webhooks). */
+export const WEBHOOK_DELIVERY_STATUSES = ['delivered', 'pending', 'failed', 'dropped'];
+/**
+ * Die Ereignisse, die ein Konto-Webhook abonnieren kann, in der Reihenfolge von
+ * `listWebhooks().events`. `reservation.*` (seit 1.5.0) tragen die Reservierung
+ * 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`).
+ */
+export const INVENTORY_WEBHOOK_EVENTS = [
+    'stock.changed',
+    'stock.below_minimum',
+    'article.created',
+    'article.updated',
+    'article.deactivated',
+    'reservation.expired',
+    'reservation.released',
+    'reservation.redeemed',
+];
+/**
+ * Die Felder der Huelle jeder Zustellung, in der Reihenfolge am Draht. Statt
+ * `partnerId` (Partner-Webhooks) traegt sie `accountId`; `test` steht nur auf
+ * Probesendungen.
+ */
+export const INVENTORY_WEBHOOK_ENVELOPE_FIELDS = ['id', 'type', 'createdAt', 'accountId', 'test', 'data'];
+/** Hoechstzahl der Webhooks je Konto (`webhook_limit`, wie bei Partner-Webhooks). */
+export const INVENTORY_WEBHOOK_LIMIT = 5;
+/** Groesstes `limit` einer Liste; ohne Angabe liefert der Server 50. */
+export const INVENTORY_LIST_LIMIT_MAX = 200;
+/**
+ * Die Codes, die die Lager-Endpunkte selbst senden (`errorCodes.inventory`;
+ * `register_user_not_allowed` steht bei [INVENTORY_REQUEST_ERROR_CODES]).
+ * `validation` traegt `errors: [{ field, message }]`, `rate_limited` traegt
+ * `retryAfterSec` (dazu die Kopfzeile `Retry-After`) – auch bei
+ * `sendWebhookTest` nach 20 Probesendungen je Wiener Kalendertag (dann bis
+ * Mitternacht in Wien).
+ *
+ * Seit 1.5.0 hinten angehaengt, in der Reihenfolge des Vertrags: die Codes
+ * der schreibenden Endpunkte. `idempotency_key_required` (Schluessel fehlt),
+ * `idempotency_conflict` (derselbe Schluessel mit anderem Inhalt),
+ * `exceeds_stock` (Abgang, Umbuchung und Zustandswechsel ueberziehen nie),
+ * `insufficient_available` (Reservierung; `data.details[]`, siehe
+ * [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` …
+ */
+export const INVENTORY_ERROR_CODES = [
+    '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',
+];
+/**
+ * Codes, die Anmeldung und Rand auf jedem Lager-Aufruf erzeugen koennen,
+ * soweit sie nicht schon in [INVENTORY_ERROR_CODES] stehen: `errorCodes.auth`
+ * ohne die des Partner-Zugangs und `errorCodes.edge` (sortiert), zuletzt
+ * `route_missing` (Code des Pakets). Dieselbe Ableitung wie bei der
+ * Rechnungs-API.
+ */
+export const INVENTORY_REQUEST_ERROR_CODES = [
+    'account_not_found',
+    'admin_required',
+    'api_not_approved',
+    'cashregister_not_assigned',
+    'cashregister_not_found',
+    'cashregister_token_invalid',
+    'cashregister_token_missing',
+    'dialect_mismatch',
+    'internal_translation_error',
+    'live_not_enabled',
+    'method_not_allowed',
+    'mfa_required',
+    'not_found',
+    'register_user_no_business',
+    'register_user_not_allowed',
+    'register_user_not_found',
+    'response_translation_failed',
+    'session_expired',
+    'session_other_cashregister',
+    'unauthorized',
+    'user_disabled',
+    'user_verification_failed',
+    'route_missing',
+];
+// ---- Schreiben und Reservierung (Backend Stufe 5b, seit 1.5.0) -----------------
+/**
+ * Hinweise einer Buchung (`warnings[].code`, `warningCodes.inventory`). Sie sind
+ * keine Fehler: die Buchung hat gewirkt. `insufficient_stock` gibt es nur beim
+ * Verkauf (Abgang, Umbuchung und Zustandswechsel weisen mit `exceeds_stock` ab),
+ * `below_minimum` misst am verfuegbaren Bestand (`onHand − reserved`) gegen den
+ * Mindestbestand des Standorts, `reservation_exceeded` meldet eine Rechnung, die
+ * mehr verkauft als reserviert war.
+ */
+export const INVENTORY_WARNING_CODES = [
+    'insufficient_stock',
+    'below_minimum',
+    'return_exceeds_sale',
+    'reservation_exceeded',
+];
+/**
+ * Bestandsart eines Artikels (`stockKind`): `quantity` = Menge, `serial` =
+ * Einzelstueck mit Seriennummer. Kein Katalog des Vokabulars, der Server
+ * uebersetzt das Feld selbst; nach der ersten Bewegung fest (`stock_kind_locked`).
+ */
+export const STOCK_KINDS = ['quantity', 'serial'];
+/** Grund eines Abgangs (`recordStockLoss.reason`, Katalog `LAGER_ABGANG_GRUND`). `other` braucht `note`. */
+export const STOCK_LOSS_REASONS = ['breakage', 'shrinkage', 'theft', 'expired', 'withdrawal', 'disposal', 'other'];
+/** Art einer Entnahme (`withdrawalType`, Katalog `LAGER_ENTNAHME_ART`); Pflicht bei `reason: 'withdrawal'`, sonst nicht erlaubt. */
+export const WITHDRAWAL_TYPES = ['private', 'staff', 'gift', 'sample'];
+/** Art von Nebenkosten eines Wareneingangs (`landedCosts[].type`, Katalog `LAGER_NEBENKOSTEN_ART`). */
+export const LANDED_COST_TYPES = ['freight', 'customs', 'insurance', 'other', 'discount', 'cash_discount'];
+/** Verteilung der Nebenkosten (`allocation`, Katalog `LAGER_VERTEILUNG`); Vorgabe des Servers `value`. */
+export const LANDED_COST_ALLOCATIONS = ['value', 'quantity', 'weight', 'manual'];
+/**
+ * Stand einer Reservierung (Katalog `RESERVIERUNG_STATUS`). Nur `active` haelt
+ * Ware zurueck; die drei anderen sind endgueltig: `redeemed` (ueber eine
+ * Rechnung eingeloest), `released` (freigegeben), `expired` (abgelaufen).
+ */
+export const RESERVATION_STATUSES = ['active', 'redeemed', 'released', 'expired'];
+/** Laengster `idempotencyKey` (Zeichen); laenger weist der Server ab, er schneidet nie ab. */
+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;

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

@@ -0,0 +1,52 @@
+/**
+ * Eingehende Konto-Webhooks der Lager-API: Signatur pruefen, Ereignis lesen.
+ *
+ * Dasselbe Verfahren wie bei Partner-Webhooks (Backend
+ * `gemeinsam/webhook-core.js`, `signaturKopf`/`pruefeSignatur`): Kopf
+ * `X-Kasseneck-Signature: t=<unix-sekunden>,v1=<hex>` mit
+ * `v1 = HMAC-SHA256(secret, "<t>.<roher Rumpf>")`, Zeitfenster 300 Sekunden in
+ * beide Richtungen, zeitkonstanter Vergleich, mehrere `v1=`-Anteile erlaubt.
+ * Die Pruefung selbst liegt in `partner/webhook-signatur.ts` und wird hier nur
+ * mit der Form `(secret, kopf, rumpf, optionen)` angeboten.
+ *
+ * Reihenfolge im Empfaenger: **erst pruefen, dann lesen**, und dabei den
+ * **rohen** Rumpf nehmen (in Express `express.raw({ type: '*\/*' })` vor jedem
+ * JSON-Parser).
+ */
+import type { InventoryWebhookEvent } from './typen.js';
+export { WEBHOOK_SIGNATURE_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_TOLERANCE_SEC, } from '../partner/webhook-signatur.js';
+export interface VerifyInventoryWebhookOptions {
+    /** Erlaubte Abweichung des Zeitstempels in Sekunden, in beide Richtungen; Vorgabe 300. */
+    toleranceSec?: number;
+    /** Jetzt: ein `Date` oder Millisekunden seit 1970 (wie `Date.now()`). Vorgabe: die Systemuhr. */
+    now?: Date | number;
+}
+/**
+ * Prueft die Signatur einer Zustellung. `true` nur, wenn Kopf, Zeitfenster
+ * und HMAC stimmen; jede schlechte Eingabe und jede Ausnahme ist `false`,
+ * nie ein Wurf.
+ *
+ * **Asynchron**, weil die Pruefung WebCrypto (`crypto.subtle`) benutzt: das
+ * Paket hat keine Laufzeitabhaengigkeit und laeuft auch im Browser.
+ *
+ * @param secret  das Secret aus `createWebhook`/`rotateWebhookSecret`; eine
+ *                Liste erlaubt den Wechsel (es reicht, wenn eines passt)
+ * @param header  der Wert von `X-Kasseneck-Signature`, unveraendert
+ * @param rawBody der **rohe** Rumpf (Text oder Bytes), nicht `JSON.parse` + `stringify`
+ */
+export declare function verifyInventoryWebhookSignature(secret: string | readonly string[], header: string | null | undefined, rawBody: string | Uint8Array, options?: VerifyInventoryWebhookOptions): Promise<boolean>;
+/**
+ * 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.
+ * - `reservation.expired|released|redeemed` tragen die Reservierung wie
+ *   `getReservation`, mit dem Status nach dem Vorgang (seit 1.5.0).
+ * - Ein Rumpf, der keine Huelle ist, oder eine Bruchzahl in einer Menge wirft
+ *   `KasseneckValidationError` (`scope: 'response'`).
+ *
+ * **Entdoppeln** auf `event.id`; **Stand statt Aenderung**: einen gespeicherten
+ * Bestand nur ueberschreiben, wenn `data.sequence` groesser ist.
+ */
+export declare function parseInventoryWebhookEvent(rawBody: string | Uint8Array): InventoryWebhookEvent | null;

package/dist/esm/inventory/webhook.js

@@ -0,0 +1,107 @@
+/**
+ * Eingehende Konto-Webhooks der Lager-API: Signatur pruefen, Ereignis lesen.
+ *
+ * Dasselbe Verfahren wie bei Partner-Webhooks (Backend
+ * `gemeinsam/webhook-core.js`, `signaturKopf`/`pruefeSignatur`): Kopf
+ * `X-Kasseneck-Signature: t=<unix-sekunden>,v1=<hex>` mit
+ * `v1 = HMAC-SHA256(secret, "<t>.<roher Rumpf>")`, Zeitfenster 300 Sekunden in
+ * beide Richtungen, zeitkonstanter Vergleich, mehrere `v1=`-Anteile erlaubt.
+ * Die Pruefung selbst liegt in `partner/webhook-signatur.ts` und wird hier nur
+ * mit der Form `(secret, kopf, rumpf, optionen)` angeboten.
+ *
+ * Reihenfolge im Empfaenger: **erst pruefen, dann lesen**, und dabei den
+ * **rohen** Rumpf nehmen (in Express `express.raw({ type: '*\/*' })` vor jedem
+ * JSON-Parser).
+ */
+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 { INVENTORY_WEBHOOK_EVENTS } from './vertrag.js';
+export { WEBHOOK_SIGNATURE_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_TOLERANCE_SEC, } from '../partner/webhook-signatur.js';
+/**
+ * Prueft die Signatur einer Zustellung. `true` nur, wenn Kopf, Zeitfenster
+ * und HMAC stimmen; jede schlechte Eingabe und jede Ausnahme ist `false`,
+ * nie ein Wurf.
+ *
+ * **Asynchron**, weil die Pruefung WebCrypto (`crypto.subtle`) benutzt: das
+ * Paket hat keine Laufzeitabhaengigkeit und laeuft auch im Browser.
+ *
+ * @param secret  das Secret aus `createWebhook`/`rotateWebhookSecret`; eine
+ *                Liste erlaubt den Wechsel (es reicht, wenn eines passt)
+ * @param header  der Wert von `X-Kasseneck-Signature`, unveraendert
+ * @param rawBody der **rohe** Rumpf (Text oder Bytes), nicht `JSON.parse` + `stringify`
+ */
+export async function verifyInventoryWebhookSignature(secret, header, rawBody, options = {}) {
+    try {
+        const jetzt = options.now instanceof Date ? options.now.getTime() : options.now;
+        const nowSec = typeof jetzt === 'number' && Number.isFinite(jetzt) ? Math.floor(jetzt / 1000) : undefined;
+        const r = await pruefeSignatur({
+            secret,
+            signatureHeader: header,
+            body: rawBody,
+            ...(nowSec === undefined ? {} : { nowSec }),
+            ...(options.toleranceSec === undefined ? {} : { toleranceSec: options.toleranceSec }),
+        });
+        return r.ok;
+    }
+    catch {
+        return false;
+    }
+}
+const BEKANNT = new Set(INVENTORY_WEBHOOK_EVENTS);
+function kaputt(grund) {
+    return new KasseneckValidationError('parseInventoryWebhookEvent', grund, 'response');
+}
+/**
+ * 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.
+ * - `reservation.expired|released|redeemed` tragen die Reservierung wie
+ *   `getReservation`, mit dem Status nach dem Vorgang (seit 1.5.0).
+ * - Ein Rumpf, der keine Huelle ist, oder eine Bruchzahl in einer Menge wirft
+ *   `KasseneckValidationError` (`scope: 'response'`).
+ *
+ * **Entdoppeln** auf `event.id`; **Stand statt Aenderung**: einen gespeicherten
+ * Bestand nur ueberschreiben, wenn `data.sequence` groesser ist.
+ */
+export function parseInventoryWebhookEvent(rawBody) {
+    const text = typeof rawBody === 'string' ? rawBody : new TextDecoder('utf-8').decode(rawBody);
+    let roh;
+    try {
+        roh = JSON.parse(text);
+    }
+    catch {
+        throw kaputt('Rumpf ist kein JSON');
+    }
+    const e = objekt(roh);
+    if (!e)
+        throw kaputt('Rumpf ist kein Ereignis (kein Objekt)');
+    const { id, type, createdAt, accountId, data } = e;
+    if (typeof id !== 'string' || id === '' || typeof type !== 'string' || type === '')
+        throw kaputt('Ereignis ohne id oder type');
+    if (typeof createdAt !== 'number' || !Number.isFinite(createdAt))
+        throw kaputt('Ereignis ohne createdAt');
+    if (typeof accountId !== 'string' || accountId === '')
+        throw kaputt('Ereignis ohne accountId');
+    if (!BEKANNT.has(type))
+        return null;
+    const ort = { name: 'parseInventoryWebhookEvent', pfad: 'data' };
+    if (!objekt(data))
+        throw kaputt('Ereignis ohne data');
+    // Nur ein ausdrueckliches `true` ist eine Probe; im Zweifel der Ernstfall.
+    const huelle = { id, type: type, createdAt, accountId, test: e.test === true };
+    switch (huelle.type) {
+        case 'stock.changed':
+            return { ...huelle, type: huelle.type, data: bestandGeaendert(ort, data) };
+        case 'stock.below_minimum':
+            return { ...huelle, type: huelle.type, data: unterMindestbestand(ort, data) };
+        case 'reservation.expired':
+        case 'reservation.released':
+        case 'reservation.redeemed':
+            return { ...huelle, type: huelle.type, data: reservierung(ort, data) };
+        default:
+            return { ...huelle, type: huelle.type, data: artikel(ort, data) };
+    }
+}

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

@@ -14,8 +14,8 @@ export { createInvoiceApi, type InvoiceApi, type InvoiceApiOptions } from './api
 export { invoiceKeyAuth, type InvoiceKeyAuthOptions } from './auth.js';
 export { isInvoiceError, isInvoiceErrorCode, invoiceErrorCode, invoiceFieldErrors, type InvoiceApiErrorCode, type InvoiceFieldError, } from './fehler.js';
 export { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoice, getInvoicePdf, getInvoiceSetupStatus, getInvoiceXml, issueInvoice, listBrands, listInvoices, previewInvoice, recordInvoicePayment, searchCustomers, updateCustomer, } from './endpunkte.js';
-export type { Brand, CancelInvoiceRequest, CancelResult, CreditNoteItemInput, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, EInvoiceStatus, Invoice, InvoiceDetail, InvoiceDetailPayment, InvoiceItem, InvoiceItemInput, InvoiceListQuery, InvoicePage, InvoiceRecipient, InvoiceSetupGap, InvoiceSetupStatus, InvoiceTotals, InvoiceXml, InvoiceNotice, InvoicePayment, InvoicePreview, InvoiceRateTotals, IssueInvoiceRequest, IssueResult, PaymentInput, PreviewResult, RecordPaymentRequest, RecordPaymentResult, } from './typen.js';
+export type { Brand, CancelInvoiceRequest, CancelResult, CreditNoteItemInput, CreditNoteRequest, CreditNoteResult, Customer, CustomerInput, CustomerPage, CustomerSearch, EInvoiceStatus, Invoice, InvoiceDetail, InvoiceDetailPayment, InvoiceItem, InvoiceItemInput, IssueInvoiceItemInput, InvoiceListQuery, InvoicePage, InvoiceRecipient, InvoiceSetupGap, InvoiceSetupStatus, InvoiceTotals, InvoiceXml, InvoiceNotice, InvoicePayment, InvoicePreview, InvoiceRateTotals, InvoiceVatIdProof, InvoiceVatIdRisk, IssueInvoiceRequest, IssueResult, PaymentInput, PreviewResult, RecordPaymentRequest, RecordPaymentResult, } from './typen.js';
 export { INVOICE_TEXTS, invoiceText, type InvoiceTextKey } from './texte.js';
 export { computeInvoiceTotals, ZERO_RATED_TAX_SCHEMES, type TotalsItem } from './summen.js';
 export { proratedPriceMicros, MAX_AMOUNT_CENTS, itemFromEuro, formatUnitPrice, CalcError, calculateInvoice, roundDiv, vatRateMapKey, formatVatRate, type CalcResult, type CalcErrorCode, type CalcOptions, type CalcItem, type RateTotal, type ItemConversion, type ConversionReason, type LineAmount, } from './calc.js';
-export { INVOICE_CONTRACT_VERSION, INVOICE_ENDPOINTS, INVOICE_ERROR_CODES, INVOICE_REQUEST_ERROR_CODES, CREDIT_NOTE_REASONS, TAX_SCHEMES, PRICE_MODES, VAT_RATES, CUSTOMER_TYPES, INVOICE_LIST_STATUS, DOC_TYPES, EINVOICE_FORMATS, EINVOICE_MISSING_CODES, WRITE_OFF_REASON_CODES, INVOICE_LANGUAGES, INVOICE_PAYMENT_METHODS, ITEM_KINDS, REVERSE_CHARGE_REASONS, INVOICE_NOTICE_CODES, INVOICE_UNITS, INVOICE_UNIT_CODES, INVOICE_SETUP_REQUIREMENTS, CUSTOMER_FIELDS, ITEM_FIELDS, CREDIT_NOTE_ITEM_FIELDS, RETURN_DISPOSITIONS, ITEM_PRICE_EXACTLY_ONE, INVOICE_REQUESTS, INVOICE_EXACTLY_ONE, INVOICE_AT_LEAST_ONE, type InvoiceEndpoint, type InvoiceErrorCode, type InvoiceRequestErrorCode, type CreditNoteReason, type ReturnDisposition, type TaxScheme, type PriceMode, type VatRatePercent, type CustomerType, type InvoiceListStatus, type DocType, type EInvoiceFormat, type EInvoiceMissingCode, type WriteOffReasonCode, type InvoiceLanguage, type InvoicePaymentMethod, type ItemKind, type ReverseChargeReason, type InvoiceNoticeCode, type InvoiceUnit, type InvoiceSetupRequirement, type FieldFormat, type Field, } from './vertrag.js';
+export { INVOICE_CONTRACT_VERSION, INVOICE_ENDPOINTS, INVOICE_ERROR_CODES, INVOICE_REQUEST_ERROR_CODES, CREDIT_NOTE_REASONS, TAX_SCHEMES, PRICE_MODES, VAT_RATES, CUSTOMER_TYPES, INVOICE_LIST_STATUS, DOC_TYPES, EINVOICE_FORMATS, EINVOICE_MISSING_CODES, WRITE_OFF_REASON_CODES, INVOICE_LANGUAGES, INVOICE_PAYMENT_METHODS, ITEM_KINDS, REVERSE_CHARGE_REASONS, INVOICE_NOTICE_CODES, INVOICE_UNITS, INVOICE_UNIT_CODES, INVOICE_SETUP_REQUIREMENTS, CUSTOMER_FIELDS, ITEM_FIELDS, INVOICE_ITEM_FIELDS, CREDIT_NOTE_ITEM_FIELDS, RETURN_DISPOSITIONS, ITEM_PRICE_EXACTLY_ONE, INVOICE_REQUESTS, INVOICE_EXACTLY_ONE, INVOICE_AT_LEAST_ONE, type InvoiceEndpoint, type InvoiceErrorCode, type InvoiceRequestErrorCode, type CreditNoteReason, type ReturnDisposition, type TaxScheme, type PriceMode, type VatRatePercent, type CustomerType, type InvoiceListStatus, type DocType, type EInvoiceFormat, type EInvoiceMissingCode, type WriteOffReasonCode, type InvoiceLanguage, type InvoicePaymentMethod, type ItemKind, type ReverseChargeReason, type InvoiceNoticeCode, type InvoiceUnit, type InvoiceSetupRequirement, type FieldFormat, type Field, } from './vertrag.js';

package/dist/esm/invoice/index.js

@@ -17,4 +17,4 @@ export { cancelInvoice, createCreditNote, createCustomer, getCustomer, getInvoic
 export { INVOICE_TEXTS, invoiceText } from './texte.js';
 export { computeInvoiceTotals, ZERO_RATED_TAX_SCHEMES } from './summen.js';
 export { proratedPriceMicros, MAX_AMOUNT_CENTS, itemFromEuro, formatUnitPrice, CalcError, calculateInvoice, roundDiv, vatRateMapKey, formatVatRate, } from './calc.js';
-export { INVOICE_CONTRACT_VERSION, INVOICE_ENDPOINTS, INVOICE_ERROR_CODES, INVOICE_REQUEST_ERROR_CODES, CREDIT_NOTE_REASONS, TAX_SCHEMES, PRICE_MODES, VAT_RATES, CUSTOMER_TYPES, INVOICE_LIST_STATUS, DOC_TYPES, EINVOICE_FORMATS, EINVOICE_MISSING_CODES, WRITE_OFF_REASON_CODES, INVOICE_LANGUAGES, INVOICE_PAYMENT_METHODS, ITEM_KINDS, REVERSE_CHARGE_REASONS, INVOICE_NOTICE_CODES, INVOICE_UNITS, INVOICE_UNIT_CODES, INVOICE_SETUP_REQUIREMENTS, CUSTOMER_FIELDS, ITEM_FIELDS, CREDIT_NOTE_ITEM_FIELDS, RETURN_DISPOSITIONS, ITEM_PRICE_EXACTLY_ONE, INVOICE_REQUESTS, INVOICE_EXACTLY_ONE, INVOICE_AT_LEAST_ONE, } from './vertrag.js';
+export { INVOICE_CONTRACT_VERSION, INVOICE_ENDPOINTS, INVOICE_ERROR_CODES, INVOICE_REQUEST_ERROR_CODES, CREDIT_NOTE_REASONS, TAX_SCHEMES, PRICE_MODES, VAT_RATES, CUSTOMER_TYPES, INVOICE_LIST_STATUS, DOC_TYPES, EINVOICE_FORMATS, EINVOICE_MISSING_CODES, WRITE_OFF_REASON_CODES, INVOICE_LANGUAGES, INVOICE_PAYMENT_METHODS, ITEM_KINDS, REVERSE_CHARGE_REASONS, INVOICE_NOTICE_CODES, INVOICE_UNITS, INVOICE_UNIT_CODES, INVOICE_SETUP_REQUIREMENTS, CUSTOMER_FIELDS, ITEM_FIELDS, INVOICE_ITEM_FIELDS, CREDIT_NOTE_ITEM_FIELDS, RETURN_DISPOSITIONS, ITEM_PRICE_EXACTLY_ONE, INVOICE_REQUESTS, INVOICE_EXACTLY_ONE, INVOICE_AT_LEAST_ONE, } from './vertrag.js';