@kreiseck/kasseneck-api 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -4,6 +4,74 @@ 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.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, manage account webhooks, verify and parse incoming stock and article 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
@@ -1417,6 +1420,114 @@ 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. 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`).
+
+**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` …) 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
+  `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.
+- **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)`.
+
 ## Migrating from 0.x
 
 1.0 is one breaking step: the wire, the exported names and the contract files
@@ -1492,7 +1603,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"];
 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"];
 /**
  * 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,21 @@ 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',
 ];
 /**
  * Die oeffentlichen Endpunkte unter `/v3` (`https://api.kasseneck.at/v3/<name>`),
@@ -146,6 +161,21 @@ 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',
 ];
 /**
  * Die Endpunkte des Kassenwegs (`https://kasse.kasseneck.at/api/v3/<name>`,

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

@@ -0,0 +1,45 @@
+/**
+ * Fassade ueber den Aufrufen der Lager-API: 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 { InventoryWebhookEventType } from './vertrag.js';
+export interface InventoryClientOptions {
+    /** `api_key` des Kontos (`kr_live_…` / `kr_test_…`). Gehoert auf einen Server. */
+    apiKey: string;
+    /** Abweichende Basis-URL (eigener Proxy); muss auf `/v3` enden. Vorgabe `https://api.kasseneck.at/v3`. */
+    baseUrl?: string;
+    /** Zeitlimit je Aufruf in Millisekunden. */
+    timeoutMs?: number;
+    /** Eigene `fetch`-Umsetzung (Tests, Proxys). */
+    fetch?: FetchLike;
+}
+export interface InventoryClient {
+    getArticle(articleId: string): Promise<Article>;
+    listArticles(query?: ArticleListQuery): Promise<ArticlePage>;
+    /** Alle Artikel der Abfrage ueber `nextCursor`: `for await (const a of client.iterateArticles())`. */
+    iterateArticles(query?: ArticleListQuery): AsyncGenerator<Article, void, undefined>;
+    lookupArticleByCode(lookup: ArticleLookup): Promise<Article>;
+    listLocations(): Promise<Location[]>;
+    getStock(articleId: string): Promise<StockResult>;
+    listStock(query?: StockListQuery): Promise<StockPage>;
+    iterateStock(query?: StockListQuery): AsyncGenerator<StockLevel, void, undefined>;
+    listStockMovements(query?: StockMovementQuery): Promise<StockMovementPage>;
+    iterateStockMovements(query?: StockMovementQuery): AsyncGenerator<StockMovement, void, undefined>;
+    createWebhook(options: CreateInventoryWebhookOptions): Promise<InventoryWebhookWithSecret>;
+    updateWebhook(webhookId: string, patch: InventoryWebhookPatch): Promise<InventoryWebhook>;
+    deleteWebhook(webhookId: string): Promise<{
+        webhookId: string;
+        deleted: boolean;
+    }>;
+    listWebhooks(): Promise<InventoryWebhookList>;
+    sendWebhookTest(webhookId: string, event: InventoryWebhookEventType | (string & {})): Promise<InventoryWebhookTestResult>;
+    rotateWebhookSecret(webhookId: string): Promise<InventoryWebhookWithSecret>;
+    listWebhookDeliveries(options?: {
+        webhookId?: string;
+        limit?: number;
+    }): Promise<InventoryWebhookDelivery[]>;
+}
+export declare function createInventoryClient(options: InventoryClientOptions): InventoryClient;

package/dist/cjs/inventory/api.js

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

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

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

package/dist/cjs/inventory/auth.js

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

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

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