@kreiseck/kasseneck-api 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,182 @@ 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`.
+Reason: since stage 5a the backend offers articles, locations, stock and the
+stock ledger under `/v3` with the account's `api_key`, plus webhooks that
+report every stock change within seconds. A shop that shows stock or keeps
+its own copy needs a typed client and, above all, a signature check it
+cannot get wrong.
+
+Additive, no breaking change; existing calls send and read the same bytes as
+in 1.3.0.
+
+- **`createInventoryClient({ apiKey })`** (`./inventory`, server only, base
+  `https://api.kasseneck.at/v3`): `getArticle`, `listArticles`,
+  `lookupArticleByCode` (code as text or `{ code }`, or
+  `{ externalSystem, externalId }`), `listLocations`, `getStock`, `listStock`,
+  `listStockMovements`, and the async iterators `iterateArticles`,
+  `iterateStock`, `iterateStockMovements` that follow `nextCursor` until
+  `null` (the same cursor twice throws instead of looping). Webhook management:
+  `createWebhook`, `updateWebhook`, `deleteWebhook`, `listWebhooks`,
+  `sendWebhookTest`, `rotateWebhookSecret`, `listWebhookDeliveries`. Every call
+  is also exported as a free function taking the transport.
+- **Models**: `Article` (incl. `stockLocationIds`; `purchasePriceMicros` only
+  with the account permission `costs`, otherwise the field is absent, not
+  `null`), `StockLevel` (`onHand`, `reserved`, `available`, `defective`,
+  `sequence`, `updatedAt`), `StockValue`, `StockMovement`, `Location`,
+  `InventoryWebhook` (`consecutiveFailures`), `InventoryWebhookDelivery`
+  (`deliveryId`; status `delivered`, `pending`, `failed`, `dropped`); the same
+  names as for partner webhooks. Quantities are integer thousandths, money
+  integer cents, purchase prices integer micro-euros; `available` may be
+  negative. A fractional or missing quantity, amount or `sequence` in a
+  response throws `KasseneckValidationError` with `scope: 'response'`, as for
+  register stock since 1.2.0. A `Date` in `updatedSince`, `changedSince`,
+  `from` or `to` goes out as ISO 8601 UTC.
+- **Incoming webhooks**: `verifyInventoryWebhookSignature(secret, header, rawBody,
+  { toleranceSec = 300, now })` resolves to `true` or `false` and never
+  throws: HMAC-SHA256 over `"<t>.<raw body>"`, constant-time comparison,
+  300 seconds in both directions, several `v1=` parts allowed; checked against
+  the backend's test vector (t=1700000000). Asynchronous because it uses
+  WebCrypto, as `./partner` does. `parseInventoryWebhookEvent(rawBody)` returns a typed
+  `InventoryWebhookEvent` for `stock.changed` (`cause`, `movementId`),
+  `stock.below_minimum` (when `onHand` drops below the minimum stock set for
+  the location; the article's `minStock` alone never triggers it, the same rule
+  as `listStock({ belowMinimum: true })`) and `article.created|updated|deactivated`, with
+  `accountId` instead of `partnerId` in the envelope; an event type this
+  version does not know returns `null`, a body that is no envelope throws.
+  Both carry `Inventory` in their name on purpose: `./partner` has a
+  `verifyWebhookSignature` with an options object that resolves to
+  `{ ok, reason }`, and an object is truthy, so a mix-up in plain JavaScript
+  would accept every delivery.
+- **Errors** through the existing classes: `INVENTORY_ERROR_CODES`
+  (`rate_limited` with `retryAfterSec`, also after 20 `sendWebhookTest` per
+  account and calendar day in Vienna, `inventory_api_not_enabled`,
+  `module_inactive`, `article_not_found`, `invalid_cursor`, `webhook_limit`
+  and the other webhook codes …), `INVENTORY_REQUEST_ERROR_CODES`, `isInventoryError`,
+  `inventoryErrorCode`, `inventoryFieldErrors`, `inventoryRetryAfterSec`.
+- **Lists as data**: `INVENTORY_ENDPOINTS`, `INVENTORY_WEBHOOK_EVENTS`,
+  `INVENTORY_WEBHOOK_ENVELOPE_FIELDS`, `LOCATION_TYPES`,
+  `STOCK_MOVEMENT_TYPES`, `STOCK_MOVEMENT_SOURCES`, `STOCK_CONDITIONS`,
+  `STOCK_CHANGE_CAUSES`, `WEBHOOK_DELIVERY_STATUSES`, each held against the
+  backend contract. A goods receipt is `goods_receipt` (movement type and
+  cause), opening stock taken over is `takeover` (also as cause); `receipt`
+  only ever means a sales receipt (`source.type`).
+- **Contract**: `fixtures/v3/` pulled again from the backend (the 14 new
+  endpoints, catalogs and events, and `antworten/lager.json` with real
+  responses and delivered webhook events that the tests read); `PUBLIC_CALLS` and `ALL_CALLS` gain the 14
+  names; `surface.json` gains the key `inventory` with the lists above.
+
 ## 1.3.0
 
 Article codes on `PosArticle` and the stock words of the register in the

package/README.md

@@ -49,6 +49,7 @@ models, same enum values, checked against each other in tests.
 - [Card payments](#card-payments)
 - [Partner API (`./partner`)](#partner-api-partner)
 - [Invoice API (`./invoice`)](#invoice-api-invoice)
+- [Inventory API (`./inventory`)](#inventory-api-inventory)
 - [Migrating from 0.x](#migrating-from-0x)
 - [Development](#development)
 - [Contract files for the twin packages](#contract-files-for-the-twin-packages)
@@ -211,6 +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; 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. |
 
@@ -408,6 +410,7 @@ the received body.
 | `POS_ERROR_CODES` | `isPosError` (`…/pos`) | settings, articles, printers, tip recipients |
 | `PARTNER_ERROR_CODES` + `PARTNER_REQUEST_ERROR_CODES` | `isPartnerError` (`…/partner`) | partner API |
 | `INVOICE_ERROR_CODES` + `INVOICE_REQUEST_ERROR_CODES` | `isInvoiceError` (`…/invoice`) | invoice API |
+| `INVENTORY_ERROR_CODES` + `INVENTORY_REQUEST_ERROR_CODES` | `isInventoryError` (`…/inventory`) | inventory API |
 
 Every group has the same helpers: `is…ErrorCode(value)`, `…ErrorCode(error)`
 (the code if the group knows it), `is…Error(error, code?)` (a type guard; without
@@ -1348,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`.
@@ -1417,6 +1440,275 @@ but € 23.49 with the core and on the invoice. It stays unchanged for existing
 callers; use `calculateInvoice` or `previewInvoice` in new code. Test cases for
 the old formula: `fixtures/invoice-totals.json`.
 
+## Inventory API (`./inventory`)
+
+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. 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
+micro-euros. `available = onHand − reserved` and may be negative: the register
+never refuses a sale. A fractional quantity in a response throws
+`KasseneckValidationError` with `scope: 'response'`; it is never read as `0`.
+
+```ts
+import express from 'express';
+import { createInventoryClient, verifyInventoryWebhookSignature, parseInventoryWebhookEvent } from '@kreiseck/kasseneck-api/inventory';
+
+const inventory = createInventoryClient({ apiKey: process.env.KASSENECK_API_KEY! });
+
+// 1. Read: an article by its EAN, then its stock per location.
+const article = await inventory.lookupArticleByCode('9001234567896');
+const { stock } = await inventory.getStock(article.id);
+// stock[0]: { articleId, locationId, onHand: 12000, reserved: 2000, available: 10000, defective: 0, sequence: 42, updatedAt }
+
+// 2. Initial sync, page by page over nextCursor.
+for await (const row of inventory.iterateStock()) {
+  await shop.saveStock(row.articleId, row.locationId, row.available, row.sequence);
+}
+
+// 3. Subscribe once. The secret is shown only in this response.
+const { secret } = await inventory.createWebhook({
+  url: 'https://shop.example.com/kasseneck-webhook',
+  events: ['stock.changed', 'stock.below_minimum'],
+  description: 'Bäckerei Kornblum online shop',
+});
+
+// 4. Receive. express.raw BEFORE any JSON parser: the signature covers the bytes as received.
+const app = express();
+app.post('/kasseneck-webhook', express.raw({ type: '*/*' }), async (req, res) => {
+  // await is required: the check is asynchronous, and a forgotten await
+  // yields a Promise, which is truthy, so every delivery would pass.
+  if (!(await verifyInventoryWebhookSignature(secret, req.header('X-Kasseneck-Signature'), req.body))) {
+    return res.sendStatus(400);
+  }
+  let event;
+  try {
+    event = parseInventoryWebhookEvent(req.body);   // throws on a malformed envelope
+  } catch {
+    return res.sendStatus(400);
+  }
+  res.sendStatus(200);                  // answer within 10 s, work afterwards
+  if (!event || event.test) return;     // unknown type of a later version, or a test delivery
+  if (event.type === 'stock.changed') {
+    // State, not delta: keep it only if sequence is higher than the stored one.
+    await shop.saveStockIfNewer(event.data.articleId, event.data.locationId, event.data.available, event.data.sequence);
+  }
+});
+```
+
+- **Signature.** `verifyInventoryWebhookSignature(secret, header, rawBody, { toleranceSec, now })`
+  resolves to `true` or `false` and never throws. It is the same procedure as
+  for partner webhooks: `X-Kasseneck-Signature: t=<unix seconds>,v1=<hex>`
+  with HMAC-SHA256 over `"<t>.<raw body>"`, compared in constant time, and a
+  window of 300 seconds in both directions against replays. It is asynchronous
+  because it uses WebCrypto: always `await` it, a forgotten `await` leaves a
+  Promise, which is truthy, and lets every delivery through. The name differs
+  on purpose from `verifyWebhookSignature` in `./partner`, which takes an
+  options object and resolves to `{ ok, reason }`. After `rotateWebhookSecret`
+  only the new secret is valid; pass both during your own switch-over
+  (`secret` may be a list, one match is enough).
+- **Parsing.** `parseInventoryWebhookEvent(rawBody)` returns `null` for an
+  event type this version does not know (answer 2xx and skip it) and throws
+  `KasseneckValidationError` on a body that is no envelope or carries a
+  fractional quantity; verify first, then parse inside `try`.
+- **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`, `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.
+  `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
+  loses nothing. Lists take `limit` (1–200, default 50) and `cursor`.
+- **Test deliveries.** `sendWebhookTest` sends a recognisably invented payload
+  with `test: true` in the envelope. At most 20 per account and calendar day in
+  Vienna (live and test environment count separately; rejected calls do not
+  count); after that `rate_limited` with the wait until midnight in Vienna.
+  Deliveries carry `deliveryId` (the header `X-Kasseneck-Delivery`), webhooks
+  `consecutiveFailures`, the same names as for partner webhooks.
+- **Errors.** `rate_limited` (about 20 requests per second per account, or the
+  daily limit of `sendWebhookTest`) carries the wait in
+  `inventoryRetryAfterSec(error)`. `inventory_api_not_enabled`,
+  `module_inactive`, `article_not_found`, `invalid_cursor`,
+  `webhook_not_found`, `webhook_limit` (5 per account),
+  `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
@@ -1492,7 +1784,7 @@ in machine form what both sides agreed on, among them:
 |---|---|---|
 | `pos-settings-defaults.json` | field names and defaults of the register settings as sent on `/api/v3` (`business`, `device`), derived from the backend contract in `fixtures/v3/` | `npm run fixtures:kasse` |
 | `stored/pos-settings-defaults.json` | the same defaults in the stored (internal, German) form (`betrieb`, `geraet`) | `npm run fixtures:kasse` |
-| `surface.json` | base URLs (`baseUrls.public`, `baseUrls.pos`), the calls per path (`calls`, and the backend's `routes`), settings value lists (`enums`, keyed by field), other register lists (`pos`), register error codes, permission keys, shortcut actions, partner and invoice lists | `npm run fixtures:oberflaeche` |
+| `surface.json` | base URLs (`baseUrls.public`, `baseUrls.pos`), the calls per path (`calls`, and the backend's `routes`), settings value lists (`enums`, keyed by field), other register lists (`pos`), register error codes, permission keys, shortcut actions, partner, invoice and inventory lists | `npm run fixtures:oberflaeche` |
 | `hobex-hps-codes.json` | measured HPS result codes, their meaning and whether they settle an outcome (the contract behind `isConclusive`) | `npm run fixtures:hobex-hps-codes` |
 | `pos-texts.json` | the register's message catalogue | `npm run fixtures:texte` |
 | `invoice-texts.json` | invoice texts in both languages | `npm run fixtures:rechnungstexte` |

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"];
+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"];
+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

@@ -75,6 +75,35 @@ exports.ALL_CALLS = [
     'rotatePartnerWebhookSecret',
     'updateCustomer',
     'updatePartnerWebhook',
+    // Lager-API (Stufe 5a, ./inventory)
+    'getArticle',
+    'listArticles',
+    'lookupArticleByCode',
+    'listLocations',
+    'getStock',
+    'listStock',
+    'listStockMovements',
+    'createWebhook',
+    'updateWebhook',
+    'deleteWebhook',
+    'listWebhooks',
+    '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>`),
@@ -146,6 +175,35 @@ exports.PUBLIC_CALLS = [
     'listInvoiceItems',
     'setCustomerMandate',
     'revokeCustomerMandate',
+    // Lager-API lesen und Konto-Webhooks (Backend Stufe 5a), umhuellt in `./inventory`.
+    'getArticle',
+    'listArticles',
+    'lookupArticleByCode',
+    'listLocations',
+    'getStock',
+    'listStock',
+    'listStockMovements',
+    'createWebhook',
+    'updateWebhook',
+    'deleteWebhook',
+    'listWebhooks',
+    '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>`,