@kreiseck/kasseneck-api 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,114 @@ Was vor 0.7.0 geschah, steht in der Commit-Historie (`git log`); ab hier wird
 es hier geführt. Ein Eintrag nennt die Änderung **und ihren Grund** —
 nur der Grund überlebt den nächsten Umbau.
 
+## 1.5.0
+
+Inventory API, write side and reservations: `./inventory` gains the 13
+endpoints of backend stage 5b, and the invoice API learns `reservationId`.
+Reason: a shop that only reads stock still oversells. It has to hold the goods
+at checkout, book what arrives and leaves, keep its articles in sync, and turn
+the reservation into a sale when the order is invoiced, all with retries that
+never book twice. The invoice API also catches up with the VAT ID check of
+the backend (stage 4, in the 0.x line since 0.33.0).
+
+Additive, no breaking change; existing calls send the same bytes as in 1.4.0.
+New response fields are added to the models.
+
+- **Articles**: `createArticle`, `updateArticle`, `deactivateArticle`, each
+  answering with the article as `getArticle` returns it. Fields: `name`,
+  `description`, `unitPriceCents`, `vatRate`, `unit`, `number`, `ean` (with
+  `ean` a foreign article with that code, otherwise the server assigns the next
+  own code), `groupId`, `revenueGroupId`, `stockTracked`, `stockLocationIds`,
+  `minStockByLocation`, `minStock` (legacy, triggers nothing), `stockKind`,
+  `purchasePriceMicros` (only with the permission `costs`), `externalIds` and
+  `metadata`. In an update `null` clears an optional field; `externalIds` and
+  `metadata` are replaced, `minStockByLocation` is merged per location.
+- **Booking**: `receiveGoods`, `transferStock`, `recordStockLoss`,
+  `changeStockCondition`, `reverseStockMovement`, each answering with a
+  `StockOperation` (`operationId`, `movementIds`, `lotIds`, `warnings[]`).
+  `previewGoodsReceipt` is `receiveGoods` with `dryRun: true`: it books nothing,
+  needs no key (a `null` key counts as none and is not sent) and returns the
+  values only with the permission `costs`. `receiveGoods` with `dryRun: true`
+  is refused before sending: a preview answers without an operation, so it
+  goes through `previewGoodsReceipt`.
+  Transfers, losses and condition changes never overdraw (`exceeds_stock`).
+  Catalogs `STOCK_LOSS_REASONS`, `WITHDRAWAL_TYPES`, `LANDED_COST_TYPES`,
+  `LANDED_COST_ALLOCATIONS`; warnings `INVENTORY_WARNING_CODES`
+  (`insufficient_stock`, `below_minimum`, `return_exceeds_sale`,
+  `reservation_exceeded`) with `isInventoryWarningCode`. A warning is not an
+  error: the booking took effect.
+- **Reservations**: `createReservation` (all or nothing, measured against
+  `available`; `insufficient_available` lists the missing positions in
+  `inventoryShortfalls(error)`), `extendReservation`, `releaseReservation` (all,
+  or per position), `getReservation`, `listReservations` and
+  `iterateReservations`. `Reservation` carries `status` (`active`, `redeemed`,
+  `released`, `expired`; `RESERVATION_STATUSES`), `reference`, `items[]` with
+  `quantity`, `redeemed`, `released`, and `expiresAt`. `expiresInMinutes` is
+  5 to 43,200.
+- **Idempotency**: every write takes `idempotencyKey` (1 to 120 characters,
+  required in the type). The client refuses to send a write without a valid
+  key, because a write without one cannot be retried safely; it never trims or
+  shortens the key. Retry after a timeout with the **same** key: the call takes
+  effect once and returns the stored answer; the same key with other content
+  gives `idempotency_conflict`.
+- **Checked before sending**, nothing else: the key, required ids, integer
+  quantities, amounts and prices (`1.5` is never 1.5 pieces), the range of
+  `expiresInMinutes`, an update without a field, an empty release list,
+  `receiveGoods` with `dryRun: true` (use `previewGoodsReceipt`). All of
+  these throw `KasseneckValidationError` with `scope: 'request'`.
+- **Models**: `Article` gains `description`, `stockKind` and
+  `minStockByLocation` (missing on an older server: `null`, `null`, `{}`).
+  `StockMovement` gains `reservedDelta` (0 for every movement that is not a
+  reservation) and `stockAfter.reserved` (only on reservation movements,
+  otherwise `null`); the movement type `reservation` has `quantityDelta: 0`.
+  The minimum stock (`below_minimum`, `listStock({ belowMinimum })`,
+  `stock.below_minimum`) is now measured against `available = onHand −
+  reserved`, so a reservation alone can trigger it. A fractional value in any
+  of these fields throws `KasseneckValidationError` with `scope: 'response'`.
+- **Events**: `reservation.expired`, `reservation.released` and
+  `reservation.redeemed` in `INVENTORY_WEBHOOK_EVENTS` and
+  `parseInventoryWebhookEvent`, carrying the reservation with its status
+  afterwards. `released` and `redeemed` fire on every effective release or
+  redemption, also a partial one (status stays `active`).
+- **Errors**: `INVENTORY_ERROR_CODES` keeps its 12 codes in front and appends
+  the codes of the write side in contract order (`idempotency_key_required`,
+  `idempotency_conflict`, `exceeds_stock`, `code_taken`,
+  `external_id_taken`, `stock_kind_locked`, `article_inactive`,
+  `insufficient_available`, `reservation_not_found`,
+  `reservation_not_active` …).
+- **Invoice API, reservations**: `issueInvoice` items take `reservationId`
+  (`IssueInvoiceItemInput`, needs `articleId`; not on credit notes, where the
+  server rejects it). New codes at the end of `INVOICE_ERROR_CODES`:
+  `reservation_not_found`, `reservation_mismatch`, `reservation_not_active`;
+  new notice `reservation_expired` (with `reservationId`): the invoice is
+  issued anyway and sells without the reservation. Three new examples in
+  `fixtures/invoice-api-examples/`.
+- **Invoice API, VAT ID check**: an invoice without VAT that relies on the
+  customer's VAT ID (intra-Community supply, reverse charge) is only issued
+  with a result of the VAT ID check (FinanzOnline, otherwise VIES) on the day
+  of issue. Reason: the caller has to decide by the code whether to retry
+  later or not to issue at all.
+  - Codes `vat_id_invalid` and `vat_id_check_pending` in
+    `INVOICE_ERROR_CODES`, after `amount_too_large` and before the
+    reservation codes (the backend order). `vat_id_check_pending` carries
+    `details.retryAfter` (seconds until the next sensible attempt, with the
+    same `idempotencyKey`).
+  - `IssueInvoiceRequest.acceptVatIdRisk` (optional boolean): issues despite
+    a pending check, the issuer bears the risk. An invalid VAT ID blocks even
+    with it. It does not count towards the idempotency of the request.
+  - `Invoice.vatIdProof` (`InvoiceVatIdProof`: `checkedOn`, `source`
+    `finanzonline` | `vies`, `level` 1 | 2, `code`) and `Invoice.vatIdRisk`
+    (`InvoiceVatIdRisk`: `acceptedOn`), otherwise `null`.
+  - `fixtures/invoice-api.schema.json` regenerated (`acceptVatIdRisk`, the
+    two codes), two new examples `issue-vat-id-risk.json` and
+    `issue-error-vat-id-risk.json`.
+- **Contract**: `fixtures/v3/` pulled again from the backend (the 13 new
+  endpoints, catalogs, `warningCodes`, events and the 5b cases in
+  `antworten/lager.json`, the VAT ID cases in `antworten/rechnungen.json`);
+  `PUBLIC_CALLS` and `ALL_CALLS` gain the 13 names (87 public calls);
+  `surface.json` gains the new lists under `inventory` and the two invoice
+  codes.
+
 ## 1.4.0
 
 Inventory API, read side and account webhooks: new subpath `./inventory`.

package/README.md

@@ -212,7 +212,7 @@ adapter:
 | `…/stored` | Stored Firestore documents (inner form, German) as the same English models the `/v3` wire returns: receipts with company and layout, register settings, articles. For clients that read Firestore directly, such as the admin panel. |
 | `…/invoice` | Invoice API: create and search customers, issue finalised invoices, credit notes and cancellation, PDF and e-invoice XML, the contract as data. **Belongs on a server.** |
 | `…/invoice/calc` | Pure calculation core for invoice totals (integers, no transport, no dependency beyond types). Safe to run in the browser. |
-| `…/inventory` | Inventory API: read articles, locations, stock and the stock ledger, manage account webhooks, verify and parse incoming stock and article events. **Belongs on a server.** |
+| `…/inventory` | Inventory API: read articles, locations, stock and the stock ledger; create and update articles, book goods receipts, transfers and losses, reserve stock at checkout; manage account webhooks, verify and parse incoming stock, article and reservation events. **Belongs on a server.** |
 | `…/react` | Thin React adapter that renders a receipt layout or a receipt sheet. Needs React. |
 | `…/fixtures/*` | Golden receipts (JSON): inputs `receipts/<name>.json`, promised line output `expected/<name>.lines.json`, `manifest.json` with checksums. The backend, the browser register and the Flutter package check against the same files. |
 
@@ -1351,6 +1351,26 @@ was classified.
 `previewInvoice` and `recordInvoicePayment`. An intra-Community supply carries
 `recapitulative_statement_due` (recapitulative statement).
 
+**VAT ID check.** An invoice without VAT that relies on the customer's VAT ID
+(intra-Community supply, reverse charge) is only issued with a result of the
+VAT ID check (FinanzOnline, otherwise VIES) on the day of issue.
+`vat_id_invalid` blocks the invoice. `vat_id_check_pending` means there is no
+result yet: retry after `retryAfter` seconds with the same `idempotencyKey`,
+or send `acceptVatIdRisk: true` to issue anyway, at the issuer's risk. The
+invoice then carries `vatIdRisk` (`acceptedOn`), otherwise the frozen proof
+`vatIdProof` (`checkedOn`, `source`, `level`, `code`); both are `null` where
+nothing was checked.
+
+```ts
+try {
+  await invoices.issueInvoice(request);
+} catch (error) {
+  if (!isInvoiceError(error, 'vat_id_check_pending')) throw error;
+  const retryAfter = error.details['retryAfter'];           // seconds
+  // later: same request and key, or with acceptVatIdRisk: true
+}
+```
+
 **After a timeout, retry with the same `idempotencyKey`**, never with a new one:
 you then get the invoice that was already issued (`replayed: true`). The same
 key with different data gives `idempotency_conflict`.
@@ -1425,10 +1445,16 @@ the old formula: `fixtures/invoice-totals.json`.
 For online shops and other systems that show or mirror the stock of a
 Kasseneck account: read articles, locations, stock per location and the stock
 ledger, and get every stock change pushed by webhook within seconds, also the
-ones made at the register in the shop. Uses the `api_key` of the account and
-belongs on a **server**. Reading needs the module `lager`; purchase prices and
-stock values appear only when the account has the permission `costs`
-(otherwise the fields are absent, not `null`).
+ones made at the register in the shop. Since 1.5.0 also the write side:
+create and update articles, book goods receipts, transfers, losses and
+condition changes, and reserve stock at checkout (see
+[Shop: reserve and invoice](#shop-reserve-and-invoice)). Uses the `api_key` of
+the account and belongs on a **server**. Reading needs the module `lager`,
+writing additionally the account switch *Lager-API schreiben*, which Kasseneck
+turns on (always on in the test environment, `kr_test_…`; otherwise
+`inventory_api_not_enabled`). Purchase prices and stock values appear only when
+the account has the permission `costs` (otherwise the fields are absent, not
+`null`).
 
 **Integers with a fixed scale:** quantities in thousandths of the base unit
 (`1000` = 1 piece, `250` = 0.250 kg), money in cents, purchase prices in
@@ -1500,16 +1526,22 @@ app.post('/kasseneck-webhook', express.raw({ type: '*/*' }), async (req, res) =>
 - **Events.** `stock.changed` carries the current state of one article at one
   location (`onHand`, `reserved`, `available`, `defective`, `sequence`,
   `updatedAt`) plus `cause` (`sale`, `invoice`, `goods_receipt`, `transfer`,
-  `takeover` …) and `movementId`; changes within 10 seconds are combined into
-  one delivery. `stock.below_minimum` fires once when `onHand` drops below the
-  minimum stock set for the location; `minStock` in the payload is that
-  threshold. The article's own `minStock` never triggers it, and
+  `takeover`, `reservation` …) and `movementId`; changes within 10 seconds are
+  combined into one delivery. `stock.below_minimum` fires once when
+  `available` (`onHand − reserved`, so a reservation alone can trigger it)
+  drops below the minimum stock set for the location (`minStockByLocation` of
+  the article); `minStock` in the payload is that threshold. The article's own
+  `minStock` is a legacy field and never triggers it, and
   `listStock({ belowMinimum: true })` follows the same rule. In movements,
   `goods_receipt` is a goods receipt; `receipt` only ever means a sales receipt
   (`source.type`).
   `article.created`, `article.updated` and `article.deactivated` carry the
-  article as `getArticle` returns it, without purchase prices. Deduplicate on
-  `event.id`; deliveries are retried after 1 min, 5 min, 30 min, 2 h and 12 h.
+  article as `getArticle` returns it, without purchase prices.
+  `reservation.expired`, `reservation.released` and `reservation.redeemed`
+  carry the reservation as `getReservation` returns it, with its status after
+  the change; `released` and `redeemed` also fire for a partial release or
+  redemption (status still `active`). Deduplicate on `event.id`; deliveries
+  are retried after 1 min, 5 min, 30 min, 2 h and 12 h.
 - **Safety net without webhooks.** `listStock({ changedSince })` and
   `listArticles({ updatedSince })` are sorted by `updatedAt` ascending and
   include the boundary, so remembering the last `updatedAt` and asking again
@@ -1528,6 +1560,155 @@ app.post('/kasseneck-webhook', express.raw({ type: '*/*' }), async (req, res) =>
   `invalid_webhook_url`, `event_not_subscribed` and `webhook_inactive` are
   decided on the code with `isInventoryError(error, code)`.
 
+### Writing: articles and bookings
+
+Every write takes an `idempotencyKey` (1 to 120 characters). The same request
+with the same key takes effect exactly once; repeating it returns the stored
+answer of the first call, the same key with different content gives
+`idempotency_conflict`. After a timeout or a network error, repeat with the
+**same** key, never with a new one. The client refuses to send a write without
+a valid key, and checks before sending only what is certainly wrong without the
+network (required ids, integer quantities, amounts and prices, the range of
+`expiresInMinutes`); everything else the server decides and reports with its
+code.
+
+```ts
+import { createInventoryClient, isInventoryError, inventoryFieldErrors } from '@kreiseck/kasseneck-api/inventory';
+
+const inventory = createInventoryClient({ apiKey: process.env.KASSENECK_API_KEY! });
+
+// A foreign article with its EAN; without ean the server assigns an own code.
+const roll = await inventory.createArticle({
+  idempotencyKey: 'shop-article-1001',
+  name: 'Kaisersemmel',
+  ean: '9001234567896',
+  unitPriceCents: 65,
+  vatRate: 10,
+  stockTracked: true,
+  minStockByLocation: { haupt: 20000 },   // thousandths: warn below 20 pieces
+  externalIds: { shop: '1001' },          // lookupArticleByCode({ externalSystem: 'shop', externalId: '1001' })
+});
+
+// Goods receipt: 60 pieces at 0.38 EUR each, plus freight spread by value.
+const receipt = await inventory.receiveGoods({
+  idempotencyKey: 'shop-goods-receipt-118',
+  items: [{ articleId: roll.id, quantity: 60000, unitPriceMicros: 380000 }],
+  landedCosts: [{ type: 'freight', amountCents: 450 }],
+  reference: 'LS-2026-118',
+});
+// receipt: { operationId, movementIds, lotIds, warnings: [] }
+
+try {
+  await inventory.recordStockLoss({ idempotencyKey: 'shop-loss-7', reason: 'breakage', items: [{ articleId: roll.id, quantity: 2000 }] });
+} catch (error) {
+  if (isInventoryError(error, 'exceeds_stock')) { /* losses, transfers and condition changes never overdraw */ }
+  else if (isInventoryError(error, 'validation')) console.log(inventoryFieldErrors(error));
+  else throw error;
+}
+```
+
+- **Articles.** `updateArticle({ idempotencyKey, articleId, …fields })` changes
+  only the fields it names; `null` clears an optional one. `externalIds` and
+  `metadata` are replaced as a whole, `minStockByLocation` is merged per
+  location (`{ haupt: null }` removes just that one). `stockKind` is fixed after
+  the first movement (`stock_kind_locked`). `deactivateArticle` frees the code
+  and the external ids. `code_taken` and `external_id_taken` carry `field` and
+  the `articleId` that holds the code in `error.details`. `minStock` is a
+  legacy field without effect; use `minStockByLocation`.
+- **Bookings.** `receiveGoods`, `transferStock`, `recordStockLoss` (`reason`
+  from `STOCK_LOSS_REASONS`; `other` needs `note`, `withdrawal` needs
+  `withdrawalType`), `changeStockCondition` (`sellable` ↔ `defective`) and
+  `reverseStockMovement({ operationId, reason })` answer with a
+  `StockOperation`. `warnings[]` are notices from `INVENTORY_WARNING_CODES`,
+  never errors: the booking took effect. Prices may be sent without the
+  permission `costs`; values come back only in `previewGoodsReceipt`, which is
+  `receiveGoods` with `dryRun: true` (books nothing, needs no key; a `null`
+  key counts as none and is not sent). `receiveGoods` itself refuses
+  `dryRun: true` before sending (`KasseneckValidationError`, `scope:
+  'request'`): a preview is not a booking, call `previewGoodsReceipt`.
+
+### Shop: reserve and invoice
+
+Hold the goods while the customer pays, turn the reservation into a sale with
+the invoice, and let the server release what was never paid:
+
+```ts
+import { createInventoryClient, inventoryShortfalls, isInventoryError, parseInventoryWebhookEvent } from '@kreiseck/kasseneck-api/inventory';
+import { createInvoiceApi } from '@kreiseck/kasseneck-api/invoice';
+
+const inventory = createInventoryClient({ apiKey: process.env.KASSENECK_API_KEY! });
+const invoices = createInvoiceApi({ apiKey: process.env.KASSENECK_API_KEY! });
+
+// 1. Checkout: reserve everything or nothing, measured against `available`.
+async function checkout(order: Order) {
+  try {
+    return await inventory.createReservation({
+      idempotencyKey: `checkout-${order.id}`,   // the same key on every retry of this checkout
+      reference: `Bestellung ${order.number}`,
+      expiresInMinutes: 30,
+      items: [{ articleId: 'kaisersemmel', quantity: 6000 }],   // 6 pieces, at the default location
+    });
+  } catch (error) {
+    if (!isInventoryError(error, 'insufficient_available')) throw error;
+    // Nothing was reserved. Tell the customer what is short:
+    // [{ articleId, locationId, requested: 6000, available: 2000 }]
+    return showShortage(inventoryShortfalls(error));
+  }
+}
+
+// 2. Paid: issue the invoice; the position redeems the reservation.
+async function paid(order: Order, reservationId: string) {
+  const { invoice, notice } = await invoices.issueInvoice({
+    idempotencyKey: `invoice-${order.id}`,
+    priceMode: 'gross',
+    serviceStart: '2026-10-06',
+    orderReference: `Bestellung ${order.number}`,
+    items: [{
+      description: 'Kaisersemmel', quantity: 6, unitPriceCents: 65, vatRate: 10,
+      articleId: 'kaisersemmel', reservationId,
+    }],
+    payment: { method: 'online' },
+  });
+  // Expired before the invoice: no error, the invoice sells without it.
+  if (notice?.some((n) => n.code === 'reservation_expired')) log('sold without reservation', invoice.number);
+}
+
+// 3. Abandoned cart: give the goods back at once instead of waiting for expiry.
+async function abandoned(order: Order, reservationId: string) {
+  await inventory.releaseReservation({ idempotencyKey: `release-${order.id}`, reservationId });
+}
+
+// 4. Webhooks (subscribe to reservation.* with createWebhook, verify as above).
+function onDelivery(rawBody: Buffer) {
+  const event = parseInventoryWebhookEvent(rawBody);
+  if (event && !event.test && event.type === 'reservation.expired') {
+    return shop.cancelUnpaidOrder(event.data.reference);   // the stock is available again
+  }
+}
+```
+
+- **Redeeming.** A position with `reservationId` needs `articleId`. The server
+  checks it when the invoice is issued: `reservation_not_found` (unknown or
+  another account), `reservation_not_active` (already redeemed or released),
+  `reservation_mismatch` (no open quantity of this article at the invoice's
+  stock location, `stockLocationId` or the default location); nothing is issued
+  then. An expired reservation is no error but the notice `reservation_expired`
+  (with `reservationId`). The reservation is redeemed when the invoice is
+  booked into stock: selling less than reserved releases the rest, selling
+  more gives the warning `reservation_exceeded`. Credit notes take no
+  `reservationId`.
+- **Expiry.** Without `expiresInMinutes` the account's default applies (7 days);
+  5 to 43,200 minutes are allowed. `extendReservation` sets a new expiry from
+  now, only for an active reservation that is not yet due
+  (`reservation_not_active`). `releaseReservation` without `items` releases
+  everything, with `items` per position (without `quantity` the whole rest);
+  the status becomes `released` only when nothing is open.
+- **Events.** `reservation.expired`, `reservation.released` and
+  `reservation.redeemed` carry the reservation with its status afterwards.
+  `listReservations({ status: 'active' })` or `({ reference })` is the safety
+  net without webhooks; the stock ledger shows reservations as movements of
+  type `reservation` with `quantityDelta: 0` and the change in `reservedDelta`.
+
 ## Migrating from 0.x
 
 1.0 is one breaking step: the wire, the exported names and the contract files

package/dist/cjs/client/aufrufe.d.ts

@@ -13,7 +13,7 @@
  * umhuellt, muss ihn weiterhin absetzen koennen.
  */
 import type { TransportBodyFields } from './transport.js';
-export declare const ALL_CALLS: readonly ["activateCashregister", "cancelInvoice", "cancelReceipt", "createCreditNote", "createCustomer", "createCustomerCashregister", "createPartnerCustomer", "checkPartnerCustomerEmail", "createPartnerWebhook", "createPaymentLinkStripe", "createPrintJob", "createReceipt", "deletePartnerWebhook", "downloadDailyReport", "downloadReport", "endRegisterSession", "financeWebService", "generateFullReceiptId", "getCustomer", "getCustomerCredentials", "getCustomerSignatureStatus", "getFirstReceiptDate", "getInvoice", "getInvoicePdf", "getInvoiceSetupStatus", "getInvoiceXml", "getKasseSettings", "getPartnerCustomer", "getPartnerInfo", "getPrintJob", "getReceipt", "getReportV2", "hobexPayApi", "hobexRefundApi", "issueInvoice", "listCustomerCashregisters", "listInvoices", "listBrands", "listMyArticleGroups", "listMyArticles", "listMyCashregisters", "listMyPrinters", "listMyReceipts", "listMyStock", "listMyStockLocations", "listMyTipRecipients", "listPartnerCustomers", "listPartnerWebhookDeliveries", "listPartnerWebhooks", "listRegisterUsersForDevice", "listRegisterSessionsForDevice", "pairRegisterDevice", "recordInvoicePayment", "registerPinLogin", "registerUserLogin", "renewRegisterSession", "reportCustomerContract", "requestCustomerSignature", "searchCustomers", "sendPartnerCustomerFonLink", "sendPartnerWebhookTest", "sendReceiptEmail", "setMyCashregisterStockLocation", "setMyKasseLogo", "setMyKasseSettings", "setMyRegisterDeviceSettings", "stripeCaptureIntent", "unpairRegisterDevice", "rotatePartnerWebhookSecret", "updateCustomer", "updatePartnerWebhook", "getArticle", "listArticles", "lookupArticleByCode", "listLocations", "getStock", "listStock", "listStockMovements", "createWebhook", "updateWebhook", "deleteWebhook", "listWebhooks", "sendWebhookTest", "rotateWebhookSecret", "listWebhookDeliveries"];
+export declare const ALL_CALLS: readonly ["activateCashregister", "cancelInvoice", "cancelReceipt", "createCreditNote", "createCustomer", "createCustomerCashregister", "createPartnerCustomer", "checkPartnerCustomerEmail", "createPartnerWebhook", "createPaymentLinkStripe", "createPrintJob", "createReceipt", "deletePartnerWebhook", "downloadDailyReport", "downloadReport", "endRegisterSession", "financeWebService", "generateFullReceiptId", "getCustomer", "getCustomerCredentials", "getCustomerSignatureStatus", "getFirstReceiptDate", "getInvoice", "getInvoicePdf", "getInvoiceSetupStatus", "getInvoiceXml", "getKasseSettings", "getPartnerCustomer", "getPartnerInfo", "getPrintJob", "getReceipt", "getReportV2", "hobexPayApi", "hobexRefundApi", "issueInvoice", "listCustomerCashregisters", "listInvoices", "listBrands", "listMyArticleGroups", "listMyArticles", "listMyCashregisters", "listMyPrinters", "listMyReceipts", "listMyStock", "listMyStockLocations", "listMyTipRecipients", "listPartnerCustomers", "listPartnerWebhookDeliveries", "listPartnerWebhooks", "listRegisterUsersForDevice", "listRegisterSessionsForDevice", "pairRegisterDevice", "recordInvoicePayment", "registerPinLogin", "registerUserLogin", "renewRegisterSession", "reportCustomerContract", "requestCustomerSignature", "searchCustomers", "sendPartnerCustomerFonLink", "sendPartnerWebhookTest", "sendReceiptEmail", "setMyCashregisterStockLocation", "setMyKasseLogo", "setMyKasseSettings", "setMyRegisterDeviceSettings", "stripeCaptureIntent", "unpairRegisterDevice", "rotatePartnerWebhookSecret", "updateCustomer", "updatePartnerWebhook", "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 ApiCall = typeof ALL_CALLS[number];
 /**
  * Die oeffentlichen Endpunkte unter `/v3` (`https://api.kasseneck.at/v3/<name>`),
@@ -21,7 +21,7 @@ export type ApiCall = typeof ALL_CALLS[number];
  * (`fixtures/v3/v3-vokabular.json`, `endpoints.public`, umbenannt nach
  * `names`). Ein Test haelt beide Listen deckungsgleich.
  */
-export declare const PUBLIC_CALLS: readonly ["createReceipt", "getReceipt", "cancelReceipt", "sendReceiptEmail", "generateFullReceiptId", "downloadReceipt", "getFirstReceiptDate", "getReportV2", "downloadReport", "downloadDailyReport", "createPaymentLinkStripe", "stripeCaptureIntent", "hobexPayApi", "hobexRefundApi", "hobexGetStatus", "financeWebService", "listMyTipRecipients", "getPartnerInfo", "createPartnerCustomer", "checkPartnerCustomerEmail", "listPartnerCustomers", "getPartnerCustomer", "sendPartnerCustomerFonLink", "createPartnerWebhook", "updatePartnerWebhook", "deletePartnerWebhook", "listPartnerWebhooks", "sendPartnerWebhookTest", "rotatePartnerWebhookSecret", "listPartnerWebhookDeliveries", "requestCustomerSignature", "getCustomerSignatureStatus", "createCustomerCashregister", "activateCashregister", "listCustomerCashregisters", "getCustomerCredentials", "reportCustomerContract", "getPartnerBilling", "getPartnerBillingMonth", "createCustomer", "getCustomer", "updateCustomer", "searchCustomers", "issueInvoice", "cancelInvoice", "createCreditNote", "getInvoice", "listInvoices", "getInvoicePdf", "getInvoiceXml", "getInvoiceSetupStatus", "listBrands", "recordInvoicePayment", "createInvoiceItem", "updateInvoiceItem", "withdrawInvoiceItem", "getInvoiceItem", "listInvoiceItems", "setCustomerMandate", "revokeCustomerMandate", "getArticle", "listArticles", "lookupArticleByCode", "listLocations", "getStock", "listStock", "listStockMovements", "createWebhook", "updateWebhook", "deleteWebhook", "listWebhooks", "sendWebhookTest", "rotateWebhookSecret", "listWebhookDeliveries"];
+export declare const PUBLIC_CALLS: readonly ["createReceipt", "getReceipt", "cancelReceipt", "sendReceiptEmail", "generateFullReceiptId", "downloadReceipt", "getFirstReceiptDate", "getReportV2", "downloadReport", "downloadDailyReport", "createPaymentLinkStripe", "stripeCaptureIntent", "hobexPayApi", "hobexRefundApi", "hobexGetStatus", "financeWebService", "listMyTipRecipients", "getPartnerInfo", "createPartnerCustomer", "checkPartnerCustomerEmail", "listPartnerCustomers", "getPartnerCustomer", "sendPartnerCustomerFonLink", "createPartnerWebhook", "updatePartnerWebhook", "deletePartnerWebhook", "listPartnerWebhooks", "sendPartnerWebhookTest", "rotatePartnerWebhookSecret", "listPartnerWebhookDeliveries", "requestCustomerSignature", "getCustomerSignatureStatus", "createCustomerCashregister", "activateCashregister", "listCustomerCashregisters", "getCustomerCredentials", "reportCustomerContract", "getPartnerBilling", "getPartnerBillingMonth", "createCustomer", "getCustomer", "updateCustomer", "searchCustomers", "issueInvoice", "cancelInvoice", "createCreditNote", "getInvoice", "listInvoices", "getInvoicePdf", "getInvoiceXml", "getInvoiceSetupStatus", "listBrands", "recordInvoicePayment", "createInvoiceItem", "updateInvoiceItem", "withdrawInvoiceItem", "getInvoiceItem", "listInvoiceItems", "setCustomerMandate", "revokeCustomerMandate", "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 Endpunkte des Kassenwegs (`https://kasse.kasseneck.at/api/v3/<name>`,
  * Web-Kasse: gleicher Ursprung `/api/v3`), in der Reihenfolge von

package/dist/cjs/client/aufrufe.js

@@ -90,6 +90,20 @@ exports.ALL_CALLS = [
     'sendWebhookTest',
     'rotateWebhookSecret',
     'listWebhookDeliveries',
+    // Lager-API schreiben und Reservierung (Stufe 5b, ./inventory)
+    'createArticle',
+    'updateArticle',
+    'deactivateArticle',
+    'receiveGoods',
+    'transferStock',
+    'recordStockLoss',
+    'changeStockCondition',
+    'reverseStockMovement',
+    'createReservation',
+    'extendReservation',
+    'releaseReservation',
+    'getReservation',
+    'listReservations',
 ];
 /**
  * Die oeffentlichen Endpunkte unter `/v3` (`https://api.kasseneck.at/v3/<name>`),
@@ -176,6 +190,20 @@ exports.PUBLIC_CALLS = [
     'sendWebhookTest',
     'rotateWebhookSecret',
     'listWebhookDeliveries',
+    // Lager-API schreiben und Reservierung (Backend Stufe 5b), umhuellt in `./inventory`.
+    'createArticle',
+    'updateArticle',
+    'deactivateArticle',
+    'receiveGoods',
+    'transferStock',
+    'recordStockLoss',
+    'changeStockCondition',
+    'reverseStockMovement',
+    'createReservation',
+    'extendReservation',
+    'releaseReservation',
+    'getReservation',
+    'listReservations',
 ];
 /**
  * Die Endpunkte des Kassenwegs (`https://kasse.kasseneck.at/api/v3/<name>`,

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

@@ -1,10 +1,10 @@
 /**
- * Fassade ueber den Aufrufen der Lager-API: Schluessel einmal binden, dann
- * rufen. Wie [createInvoiceApi] bewusst keine Klasse; die Aufrufe sind freie
+ * 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, ArticleListQuery, ArticleLookup, ArticlePage, CreateInventoryWebhookOptions, InventoryWebhook, InventoryWebhookDelivery, InventoryWebhookList, InventoryWebhookPatch, InventoryWebhookTestResult, InventoryWebhookWithSecret, Location, StockLevel, StockListQuery, StockMovement, StockMovementPage, StockMovementQuery, StockPage, StockResult } from './typen.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. */
@@ -41,5 +41,21 @@ export interface InventoryClient {
         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

@@ -1,7 +1,7 @@
 "use strict";
 /**
- * Fassade ueber den Aufrufen der Lager-API: Schluessel einmal binden, dann
- * rufen. Wie [createInvoiceApi] bewusst keine Klasse; die Aufrufe sind freie
+ * 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 });
@@ -9,6 +9,7 @@ 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 }),
@@ -34,5 +35,20 @@ function createInventoryClient(options) {
         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/endpunkte.d.ts

@@ -1,6 +1,7 @@
 /**
  * Die Aufrufe der Lager-API: Artikel, Standorte, Bestand und Bewegungen
- * lesen, Konto-Webhooks verwalten (Backend Stufe 5a).
+ * 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.
@@ -14,8 +15,26 @@
  * wiederholt werden. Bei `rate_limited` vorher `retryAfterSec` warten
  * ([inventoryRetryAfterSec]).
  */
-import type { InternerTransport } from '../client/aufrufe.js';
+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`. */
@@ -69,3 +88,4 @@ export declare function listWebhookDeliveries(transport: InternerTransport, opti
     webhookId?: string;
     limit?: number;
 }): Promise<InventoryWebhookDelivery[]>;
+export {};

package/dist/cjs/inventory/endpunkte.js

@@ -1,7 +1,8 @@
 "use strict";
 /**
  * Die Aufrufe der Lager-API: Artikel, Standorte, Bestand und Bewegungen
- * lesen, Konto-Webhooks verwalten (Backend Stufe 5a).
+ * 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.
@@ -16,6 +17,10 @@
  * ([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;

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

@@ -8,7 +8,8 @@
  * `KasseneckApiError.code`.
  */
 import type { KasseneckApiError } from '../client/errors.js';
-import { type InventoryErrorCode, type InventoryRequestErrorCode } from './vertrag.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;
@@ -31,3 +32,12 @@ export declare function inventoryFieldErrors(error: unknown): InventoryFieldErro
  * 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

@@ -14,7 +14,10 @@ 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) {
@@ -45,3 +48,19 @@ function inventoryRetryAfterSec(error) {
     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);
+}