@kreiseck/kasseneck-api 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -4,6 +4,130 @@ 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.6.0
+
+Inventory API, variants: `./inventory` gains the five endpoints of backend
+stage 5c. Reason: a shop sells the same apron in three sizes and two colours.
+Until now it had to create six unrelated articles and keep their names, prices
+and codes in step by hand; nothing told the shop or the register that they
+belong together, and nothing stopped a second "M red". A variant group holds
+what they share and guarantees that each combination exists once.
+
+Additive at runtime; existing calls send the same bytes as in 1.5.1. Two
+things change for code that relies on the old shape: the unions
+`InventoryWebhookEvent`/`InventoryWebhookEventType`, `InventoryErrorCode`,
+`InventoryEndpoint` and `ApiCall` gain members, so an exhaustive `switch` with a
+`never` check (or a `Record<…>` over them) needs the new cases; and
+`parseInventoryWebhookEvent` now returns an event for `variant_group.*` where
+1.5.x returned `null`.
+
+- **Variant groups**: `createVariantGroup` (with `createMatrix: true` every
+  combination of the values, at most 100, or the listed `variants[]`, at most
+  100; never both), `updateVariantGroup` (name, defaults as a partial update,
+  `addAttributeValues`, or `active: false` to deactivate the group and all its
+  variants for good), `getVariantGroup`, `listVariantGroups` and
+  `iterateVariantGroups` (sorted by `updatedAt` ascending, filters `active`
+  and `updatedSince`). `VariantGroup` carries `attributes` (1 to 3, each with
+  `key`, `label` and 1 to 30 `values`, in group order), `defaults`
+  (`unitPriceCents`, `vatRate`, `unit`, `groupId`, `stockTracked`), `active`,
+  `variants[]` (`articleId` and `variantAttributes` of every active variant)
+  and the times. The group answers carry no articles: read them with
+  `listArticles({ variantGroupId })`.
+- **Variants are articles**: `addVariant` creates one more variant and answers
+  with the article as `createArticle` does. Each variant takes the article
+  fields of `createArticle`; fields it does not name are filled from the group
+  defaults at creation, the name defaults to "<group> <value1> <value2>" in
+  attribute order. `Article.variantGroupId` and `Article.variantAttributes`
+  are set only on variants; the keys of `variantAttributes` come sorted by code
+  point, the attribute order is in `VariantGroup.attributes`.
+- **Idempotency**: the three writes take `idempotencyKey` (required in the
+  type and refused before sending without a valid one) and are in
+  `UNKNOWN_OUTCOME_CALLS`: after `outcome: 'unknown'` resend with the same key.
+  `getVariantGroup` and `listVariantGroups` are reads.
+- **Checked before sending**, nothing else: the key, `variantGroupId`,
+  `createMatrix: true` together with `variants`, `variants` that is no list or
+  holds an entry without a `variantAttributes` object, integer prices,
+  quantities and purchase prices (also in `defaults` and in every variant), an
+  update without a change, `active` other than `false` or not alone,
+  `addAttributeValues` that is no object. The limits (3 attributes, 30 values,
+  matrix 100, 250 active variants per group) are left to the server, so it can
+  raise them; they are exported as `VARIANT_ATTRIBUTES_MAX`,
+  `VARIANT_VALUES_MAX`, `VARIANT_MATRIX_MAX`, `VARIANT_GROUP_ACTIVE_MAX`.
+- **Events**: `variant_group.created` and `variant_group.updated` in
+  `INVENTORY_WEBHOOK_EVENTS` and `parseInventoryWebhookEvent`, carrying the
+  group as `getVariantGroup` returns it. `updated` fires only on a visible
+  change (new value, new or deactivated variant, name, defaults, deactivating
+  the group). Two deliveries may overtake each other: keep the one with the
+  later `updatedAt`.
+- **Errors**: `INVENTORY_ERROR_CODES` appends `variant_group_not_found`,
+  `variant_already_exists` (with `field`, and `articleId` of the existing
+  variant), `invalid_variant_attributes` (with `field` and `errors[]`),
+  `variant_group_inactive` and `variant_limit`. `too_many_positions` now also
+  answers a variant request that would need more writes than fit into one
+  operation, with `field` (`variants`, `createMatrix`, or `externalIds` for
+  `addVariant`); nothing is written then.
+- **Contract**: `fixtures/v3/` pulled from the backend (stage 5c); the
+  vocabulary of `./stored` regenerated from it (fingerprint only, no schema
+  change for stored documents).
+
+## 1.5.1
+
+Every call with an effect reports `outcome: 'unknown'` when it fails after
+sending began: network error, timeout, HTTP 5xx, HTTP 200 with the `/v3`
+marker but an empty, non-JSON or status-less body, and HTML with the marker.
+Reason: until 1.5.0 only the six signing and money calls did; a goods receipt,
+a reservation or `issueInvoice` came back as `'rejected'` ("did not happen")
+although the server may have booked it. Whoever believed that and resent with
+a **new** `idempotencyKey` booked twice.
+
+A change to the safe side, no change on the wire; requests send the same body
+as in 1.5.0 (only the `Kasseneck-Client` header carries the new version).
+
+- **Which calls**: `UNKNOWN_OUTCOME_CALLS` (exported, sorted), also in
+  `fixtures/surface.json` as `unknownOutcomeCalls` for the Dart twin. New in it:
+  inventory writes (`createArticle`, `updateArticle`, `deactivateArticle`,
+  `receiveGoods`, `transferStock`, `recordStockLoss`, `changeStockCondition`,
+  `reverseStockMovement`), reservations (`createReservation`,
+  `extendReservation`, `releaseReservation`), inventory and partner webhooks
+  (create, update, delete, rotate the secret, test delivery), the invoice API
+  (`issueInvoice`, `cancelInvoice`, `createCreditNote`, `recordInvoicePayment`,
+  `createCustomer`, `updateCustomer`), invoice items and SEPA mandates
+  (`createInvoiceItem`, `updateInvoiceItem`, `withdrawInvoiceItem`,
+  `setCustomerMandate`, `revokeCustomerMandate`), the partner calls with an
+  effect (`createPartnerCustomer`, `sendPartnerCustomerFonLink`,
+  `requestCustomerSignature`, `createCustomerCashregister`,
+  `activateCashregister`, `reportCustomerContract`), and on the register
+  `pairRegisterDevice`, `unpairRegisterDevice`, `setMyKasseSettings`,
+  `setMyKasseLogo`, `setMyRegisterDeviceSettings`,
+  `setMyCashregisterStockLocation`, `createPrintJob`, `sendReceiptEmail`.
+- **Which stay `'rejected'`**: reading calls, dry runs (`previewGoodsReceipt`,
+  `previewInvoice`, `issueInvoice` with `dryRun: true`), the register sign-in
+  sessions (`registerUserLogin`, `registerPinLogin`, `renewRegisterSession`,
+  `endRegisterSession`) and `createPaymentLinkStripe`: a repeat books nothing.
+  A timeout already during sign-in stays `'rejected'` as before: nothing was
+  sent.
+- **What to do**: with an `idempotencyKey`, send the same request with the
+  **same** key; it takes effect once and returns the stored answer.
+  `createInvoiceItem` is recognised by `source` + `reference`: the same values
+  again are safe. Without a key (receipts, cancellations, money calls,
+  settings, webhooks, changing or withdrawing invoice items, mandates), read
+  the state first. The rule for receipts and payments is unchanged: look it up,
+  never resend.
+- **Per call**: the transport takes a fifth argument `{ hasEffect }`
+  (`TransportCallOptions`). `true` marks a call with an effect that this
+  package does not know. `false` only counts together with
+  `params.dryRun === true` (a dry run under the name of the real call; the
+  package's own previews use it); without `dryRun: true` a call from the list
+  stays `'unknown'`, so no option can turn a real booking into `'rejected'`.
+  Without the option the list decides, and an unknown name counts as having no
+  effect.
+- **Guard**: every call the package knows (`ALL_CALLS`, `PUBLIC_CALLS`,
+  `POS_CALLS`) is classified as with or without effect; a new call without a
+  classification fails the tests.
+- `CALLS_WITH_EFFECT` of the register texts and `fixtures/pos-texts.json` are
+  unchanged; `messageOutcome` follows the transport first, so the register
+  shows the careful sentence for every call above.
+
 ## 1.5.0
 
 Inventory API, write side and reservations: `./inventory` gains the 13

package/README.md

@@ -433,30 +433,42 @@ receipt email, and values outside a settings field's value list throw a
 `KasseneckValidationError` before anything is sent, instead of being dropped
 silently. For a layout option of 0.x the message names its English successor.
 
-### `outcome: 'unknown'`: never retry, look it up
+### `outcome: 'unknown'`: never resend blindly
 
 `KasseneckApiError`, `KasseneckHttpError` and `KasseneckNetworkError` carry
 `outcome`. `'rejected'` means the server turned the request down; whether
 anything else is safe to do depends on the code, and on the money calls it
 is only set for the codes listed below. `'unknown'` means the operation **may have been carried out**, for
-`createReceipt` a signed receipt in the chain. Then never send it again: read
-the result back (`getReceipt`, `listMyReceipts`, the original of a
-cancellation) and continue from there. `isOutcomeUnknown(error)` covers all
-three classes. The outcome is unknown for:
+`createReceipt` a signed receipt in the chain. Then never send it again blindly:
+read the result back (`getReceipt`, `listMyReceipts`, the original of a
+cancellation) and continue from there. A call with an `idempotencyKey` (or,
+for invoice items, the same `source` and `reference`) is the exception: send
+it again unchanged (see below).
+`isOutcomeUnknown(error)` covers all three classes. The outcome is unknown for:
 
 - `dialect_mismatch`, `receipt_outcome_unknown`, `cancellation_outcome_unknown`;
 - `response_translation_failed`, unless `details.handled === false`;
 - `response_unreadable`: a signing or money-moving call reported success,
   but the response lacks what the call promises (no receipt, no reference, no
   remaining quantities, no Hobex receipt, no captured payment intent);
-- on the calls with an effect: the signing calls `createReceipt`,
-  `cancelReceipt` and `financeWebService`, and the money calls `hobexPay`
-  (`hobexPayApi`, charges a card), `hobexRefund` (`hobexRefundApi`) and
-  `stripeCaptureIntent`: a network error or timeout after sending began, HTTP
-  5xx, and HTTP 200 with the `Kasseneck-Api-Version: v3` marker but an empty,
+- on every call with an effect (`UNKNOWN_OUTCOME_CALLS`, also in
+  `fixtures/surface.json` as `unknownOutcomeCalls`): the signing calls
+  `createReceipt`, `cancelReceipt` and `financeWebService`, the money calls
+  `hobexPay` (`hobexPayApi`, charges a card), `hobexRefund`
+  (`hobexRefundApi`) and `stripeCaptureIntent`, and since 1.5.1 every other
+  call that books, issues, creates, changes, deletes or sends something:
+  inventory writes and reservations, webhooks, invoices, credit notes,
+  recorded payments, customers, invoice items and SEPA mandates, partner
+  businesses, register settings, pairing, print jobs and receipt emails.
+  There it is a network error or timeout after sending began, HTTP 5xx, and
+  HTTP 200 with the `Kasseneck-Api-Version: v3` marker but an empty,
   non-JSON (also `text/html`) or status-less body (`KasseneckHttpError`,
   `reason` `empty-body`, `not-json` or `missing-status`). HTML without the
-  marker stays `route_missing` with `'rejected'`: no function saw the call;
+  marker stays `route_missing` with `'rejected'`: no function saw the call.
+  Reading calls and dry runs (`previewGoodsReceipt`, `previewInvoice`) stay
+  `'rejected'`, and so do the register sign-in sessions and
+  `createPaymentLinkStripe`: a repeat books nothing (a second short-lived
+  session, a second link nobody else has seen);
 - on the money calls: every error envelope **without a code**, and every
   code that is not one of the rejection codes below. The Hobex and Stripe
   handlers also answer with a plain error message after the provider was
@@ -490,17 +502,33 @@ failed `hobexRefund` throws a `KasseneckApiError`; it never returns `false`,
 because a `false` on an unclear outcome invites a second refund. Even a
 `'rejected'` is no invitation to resend blindly: fix the cause first.
 
-**Never retry these six calls, and never put a retrying layer under the
-package.** A `fetch` passed in `options.fetch` (or a proxy or service worker in
-front of it) must not resend a request by itself after a network error, a
-timeout or a 5xx: a silent second send is a second signed receipt, a second
-charge or a second refund, and the package cannot see it. Look the result up
-instead (`getReceipt`, `listMyReceipts`, the Hobex transaction by its
-`transactionId`, the Stripe session).
-
-`outcome` only covers signing and the money calls. After a network error on
-`issueInvoice` an invoice may still have been issued; retry it with the same
-`idempotencyKey`.
+**Never retry a call with an effect blindly, and never put a retrying layer
+under the package.** A `fetch` passed in `options.fetch` (or a proxy or service
+worker in front of it) must not resend a request by itself after a network
+error, a timeout or a 5xx: a silent second send is a second signed receipt, a
+second charge, a second refund or a second booking, and the package cannot
+see it. Look the result up instead (`getReceipt`, `listMyReceipts`, the Hobex
+transaction by its `transactionId`, the Stripe session).
+
+**With an `idempotencyKey`** (inventory writes and reservations, `issueInvoice`,
+`cancelInvoice`, `createCreditNote`, `recordInvoicePayment`, `createCustomer`
+and `createPartnerCustomer` with a key) the safe retry after `'unknown'` is the
+same request with the **same** key: it takes effect exactly once and returns
+the stored answer (invoices and partner customers mark it with
+`replayed: true`; inventory writes return the stored answer unchanged). Never a
+new key: that books a second time. `createInvoiceItem` has no key; the server recognises a repeat by
+`source` + `reference`, so the same request with the same values is safe
+(`replayed: true`; other data gives `item_reference_conflict`). Without a key
+(receipts, cancellations, money calls, settings, webhooks, `updateCustomer`,
+`createCustomer` and `createPartnerCustomer` without one, `updateInvoiceItem`,
+`withdrawInvoiceItem`, `setCustomerMandate`, `revokeCustomerMandate`) read the
+state first (for invoice items `getInvoiceItem`) and only then decide.
+
+A call through the open transport that this package does not know counts as
+having no effect; say so with `transport(name, params, undefined, undefined,
+{ hasEffect: true })`. `hasEffect: false` only counts together with
+`params.dryRun === true` (a dry run under the name of the real call); without
+it a call with an effect stays `'unknown'`.
 
 ```ts
 import { isOutcomeUnknown, paymentsExpectedCents } from '@kreiseck/kasseneck-api';
@@ -944,7 +972,7 @@ process:
 `hobexPay`, `hobexRefund` and `stripeCaptureIntent` move money. They are never
 retried, neither by the app nor by a retrying `fetch` under the package: on
 `isOutcomeUnknown(error)` look the payment up (see
-[`outcome: 'unknown'`](#outcome-unknown-never-retry-look-it-up)).
+[`outcome: 'unknown'`](#outcome-unknown-never-resend-blindly)).
 - **Hobex HPS via Kasseneck Connect**, described below.
 
 ### Hobex HPS via Kasseneck Connect
@@ -1373,7 +1401,13 @@ try {
 
 **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`.
+key with different data gives `idempotency_conflict`. Since 1.5.1 every invoice
+call with an effect (`issueInvoice`, `cancelInvoice`, `createCreditNote`,
+`recordInvoicePayment`, `createCustomer`, `updateCustomer`) reports
+`outcome: 'unknown'` after a timeout, a network error, HTTP 5xx or an
+unreadable answer (before: `'rejected'`); `previewInvoice` and the reading
+calls stay `'rejected'`. See
+[`outcome: 'unknown'`](#outcome-unknown-never-resend-blindly).
 
 Validation errors arrive as `validation` with field paths
 (`invoiceFieldErrors(error)` → `[{ field: 'items[0].vatRate', message }]`).
@@ -1448,7 +1482,8 @@ 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
+[Shop: reserve and invoice](#shop-reserve-and-invoice)); since 1.6.0 variant
+groups (sizes, colours, see [Variants](#variants)). 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
@@ -1566,7 +1601,16 @@ 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
+**same** key, never with a new one. Since 1.5.1 every write, reservation and
+webhook call reports `outcome: 'unknown'` in that case (also after HTTP 5xx or
+an unreadable answer; before: `'rejected'`), so `isOutcomeUnknown(error)` is
+the signal to resend writes and reservations with the same key;
+`previewGoodsReceipt` and the reading calls stay `'rejected'`. The webhook
+calls (`createWebhook`, `updateWebhook`, `deleteWebhook`,
+`rotateWebhookSecret`, `sendWebhookTest`) have no key: after `'unknown'` look
+the state up first (`listWebhooks`, `listWebhookDeliveries`) instead of
+resending, or you get a second webhook, a second new secret or a used-up test
+delivery. 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
@@ -1709,6 +1753,116 @@ function onDelivery(rawBody: Buffer) {
   net without webhooks; the stock ledger shows reservations as movements of
   type `reservation` with `quantityDelta: 0` and the change in `reservedDelta`.
 
+### Variants
+
+A variant is an ordinary article with `variantGroupId` and
+`variantAttributes`: its own id, code, stock and tile at the register; it is
+read, booked, reserved and invoiced like any other article. The variant group
+holds what the variants share (name, attributes with their values, defaults
+for new variants) and guarantees that each combination exists only once. The
+writes take an `idempotencyKey` and the account switch *Lager-API schreiben*,
+like every other write.
+
+```ts
+import { createInventoryClient, isInventoryError, parseInventoryWebhookEvent } from '@kreiseck/kasseneck-api/inventory';
+
+const inventory = createInventoryClient({ apiKey: process.env.KASSENECK_API_KEY! });
+
+// 1. Create the group with every combination (3 sizes × 2 colours = 6 variants).
+const apron = await inventory.createVariantGroup({
+  idempotencyKey: 'shop-group-3001',
+  name: 'Schürze',
+  attributes: [
+    { key: 'size', label: 'Größe', values: ['S', 'M', 'L'] },
+    { key: 'colour', label: 'Farbe', values: ['rot', 'blau'] },
+  ],
+  defaults: { unitPriceCents: 2490, vatRate: 20, stockTracked: true },
+  createMatrix: true,
+});
+// apron.variants: [{ articleId, variantAttributes: { colour: 'rot', size: 'S' } }, …]
+
+// 2. The answer carries ids only. Read the articles of the group (names
+//    "Schürze S rot" …, own codes) and map them to the shop's products.
+for await (const article of inventory.iterateArticles({ variantGroupId: apron.id })) {
+  await shop.linkVariant(article.variantAttributes!, article.id, article.internalCode);
+}
+
+// 3. A new size later: add the value, then the variants you want.
+await inventory.updateVariantGroup({
+  idempotencyKey: 'shop-group-3001-xl',
+  variantGroupId: apron.id,
+  addAttributeValues: { size: ['S', 'M', 'L', 'XL'] },   // known values are skipped
+});
+try {
+  await inventory.addVariant({
+    idempotencyKey: 'shop-variant-3001-xl-rot',
+    variantGroupId: apron.id,
+    variantAttributes: { size: 'XL', colour: 'rot' },
+    ean: '9001234567834',                                  // optional: a foreign article with this code
+  });
+} catch (error) {
+  if (!isInventoryError(error, 'variant_already_exists')) throw error;
+  // Exists already (error.details.articleId): link that one instead.
+}
+
+// 4. Webhooks: keep the group state with the latest updatedAt.
+function onDelivery(rawBody: Buffer) {
+  const event = parseInventoryWebhookEvent(rawBody);
+  if (event && !event.test && (event.type === 'variant_group.created' || event.type === 'variant_group.updated')) {
+    return shop.saveGroupIfNewer(event.data.id, event.data, event.data.updatedAt);
+  }
+}
+```
+
+- **Limits.** At most 3 attributes per group (keys `^[a-z0-9_]{1,32}$`,
+  `__…__` is reserved), at most 30 values per attribute (1 to 30 characters,
+  unique ignoring case), at most 100 combinations with `createMatrix` and at
+  most 100 entries in `variants[]` per request, at most 250 active variants
+  per group (`variant_limit`). The client does not check these before sending
+  (the server may raise them); they are exported as
+  `VARIANT_ATTRIBUTES_MAX`, `VARIANT_VALUES_MAX`, `VARIANT_MATRIX_MAX` and
+  `VARIANT_GROUP_ACTIVE_MAX`. A request that would need more writes than fit
+  into one operation (about 187 external ids with 100 variants) is refused as
+  a whole with `too_many_positions` and `field` (`variants`, `createMatrix`,
+  or `externalIds` for `addVariant`); nothing is written. Send fewer variants
+  and add the rest with `addVariant`.
+- **Order.** `attributes` keeps the order of the group: it decides the default
+  name "<group> <value1> <value2>" and the matrix (the first attribute runs
+  outermost). `variantAttributes` on articles, in `variants[]` and in webhooks
+  comes with its keys **sorted by code point**, not in attribute order; compare
+  by key, never by position. Values are stored trimmed and in Unicode NFC; a
+  variant's value must match a listed value exactly (case and spaces are not
+  adjusted), otherwise `invalid_variant_attributes` names the `field`.
+- **Variants are articles.** `addVariant` answers with the article as
+  `createArticle` does. Each variant takes the fields of `createArticle`;
+  fields it does not name are filled from the group defaults **at creation
+  only**: changing the group name or defaults later changes no existing
+  variant (use `updateArticle`). `createArticle` and `updateArticle` refuse
+  `variantGroupId` and `variantAttributes`; a variant is never moved to another
+  group, and an existing article never becomes a variant.
+- **Deactivating.** `deactivateArticle` on one variant of an active group
+  takes it out of the group's `variants[]` and frees its combination for a new
+  variant.
+  `updateVariantGroup({ active: false })` deactivates the group and every
+  variant (codes and external ids become free), stands alone and is final; a
+  deactivated group answers every other change and `addVariant` with
+  `variant_group_inactive`. The answer comes when all variants are
+  deactivated; after `outcome: 'unknown'` simply repeat it, also with a new
+  key, it completes an interrupted run.
+- **After `unknown`.** As with every write: resend with the **same**
+  `idempotencyKey`. A new key would create the group a second time (the
+  combination check is per group). `variant_already_exists` on `addVariant`
+  carries `articleId` of the existing variant.
+- **Events.** `variant_group.created` and `variant_group.updated` carry the
+  group as `getVariantGroup` returns it (with `variants[]`, without articles).
+  `updated` fires only on a visible change; creating a variant also sends
+  `article.created`, deactivating the group one `variant_group.updated` and
+  one `article.deactivated` per variant. Deliveries can overtake each other:
+  keep a group state only if its `updatedAt` is later than the stored one.
+  Without webhooks, `listVariantGroups({ updatedSince })` and
+  `listArticles({ variantGroupId, updatedSince })` are sorted by `updatedAt`
+  ascending and include the boundary.
+
 ## Migrating from 0.x
 
 1.0 is one breaking step: the wire, the exported names and the contract files
@@ -1784,7 +1938,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, invoice and inventory lists | `npm run fixtures:oberflaeche` |
+| `surface.json` | base URLs (`baseUrls.public`, `baseUrls.pos`), the calls per path (`calls`, and the backend's `routes`), the calls with an effect whose outcome is `unknown` after a timeout, network error, 5xx or unreadable answer (`unknownOutcomeCalls`, sorted), 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

@@ -12,8 +12,8 @@
  * weiterhin jeden `string`: wer einen Aufruf braucht, den dieses Paket nicht
  * 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", "createArticle", "updateArticle", "deactivateArticle", "receiveGoods", "transferStock", "recordStockLoss", "changeStockCondition", "reverseStockMovement", "createReservation", "extendReservation", "releaseReservation", "getReservation", "listReservations"];
+import type { TransportBodyFields, TransportCallOptions } 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", "createArticle", "updateArticle", "deactivateArticle", "receiveGoods", "transferStock", "recordStockLoss", "changeStockCondition", "reverseStockMovement", "createReservation", "extendReservation", "releaseReservation", "getReservation", "listReservations", "createVariantGroup", "updateVariantGroup", "getVariantGroup", "listVariantGroups", "addVariant"];
 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", "createArticle", "updateArticle", "deactivateArticle", "receiveGoods", "transferStock", "recordStockLoss", "changeStockCondition", "reverseStockMovement", "createReservation", "extendReservation", "releaseReservation", "getReservation", "listReservations"];
+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", "createVariantGroup", "updateVariantGroup", "getVariantGroup", "listVariantGroups", "addVariant"];
 /**
  * Die Endpunkte des Kassenwegs (`https://kasse.kasseneck.at/api/v3/<name>`,
  * Web-Kasse: gleicher Ursprung `/api/v3`), in der Reihenfolge von
@@ -31,6 +31,60 @@ export declare const PUBLIC_CALLS: readonly ["createReceipt", "getReceipt", "can
 export declare const POS_CALLS: readonly ["pairRegisterDevice", "listRegisterUsersForDevice", "listRegisterSessionsForDevice", "registerUserLogin", "registerPinLogin", "renewRegisterSession", "endRegisterSession", "unpairRegisterDevice", "listMyCashregisters", "listMyReceipts", "getReceipt", "createReceipt", "generateFullReceiptId", "cancelReceipt", "sendReceiptEmail", "listMyArticleGroups", "listMyArticles", "getKasseSettings", "setMyKasseSettings", "setMyKasseLogo", "setMyRegisterDeviceSettings", "listMyPrinters", "createPrintJob", "getPrintJob", "listMyTipRecipients", "listMyStockLocations", "listMyStock", "setMyCashregisterStockLocation"];
 export type PublicCall = typeof PUBLIC_CALLS[number];
 export type PosCall = typeof POS_CALLS[number];
+/**
+ * Die Aufrufe **mit Wirkung**, alphabetisch: sie legen etwas an, aendern oder
+ * loeschen es, buchen, signieren, bewegen Geld oder senden etwas hinaus
+ * (Mail, Druckjob, Probesendung). Scheitert einer, nachdem die Anfrage
+ * unterwegs war (Netzfehler, Zeitlimit, HTTP 5xx, unlesbare Erfolgsantwort,
+ * HTML mit Kennzeichen), meldet der Transport `outcome: 'unknown'`: der
+ * Vorgang kann ausgefuehrt sein.
+ *
+ * Bis 1.5.0 galt das nur fuer die sechs signierenden und geldbewegenden
+ * Aufrufe; ein Wareneingang oder eine Rechnung nach einem Zeitlimit kam als
+ * `'rejected'` an, und wer das glaubte und mit NEUEM Idempotenzschluessel
+ * neu sendete, buchte doppelt.
+ *
+ * Geht als `unknownOutcomeCalls` in den Vertrag (`fixtures/surface.json`);
+ * der Dart-Zwilling prueft seine Liste dagegen. Jeder Aufruf aus
+ * [ALL_CALLS], [PUBLIC_CALLS] und [POS_CALLS] steht entweder hier oder in
+ * [CALLS_WITHOUT_EFFECT] (Waechter `test/ausgang-einordnung.test.ts`).
+ */
+export declare const UNKNOWN_OUTCOME_CALLS: readonly ["activateCashregister", "addVariant", "cancelInvoice", "cancelReceipt", "changeStockCondition", "createArticle", "createCreditNote", "createCustomer", "createCustomerCashregister", "createInvoiceItem", "createPartnerCustomer", "createPartnerWebhook", "createPrintJob", "createReceipt", "createReservation", "createVariantGroup", "createWebhook", "deactivateArticle", "deletePartnerWebhook", "deleteWebhook", "extendReservation", "financeWebService", "hobexPayApi", "hobexRefundApi", "issueInvoice", "pairRegisterDevice", "receiveGoods", "recordInvoicePayment", "recordStockLoss", "releaseReservation", "reportCustomerContract", "requestCustomerSignature", "reverseStockMovement", "revokeCustomerMandate", "rotatePartnerWebhookSecret", "rotateWebhookSecret", "sendPartnerCustomerFonLink", "sendPartnerWebhookTest", "sendReceiptEmail", "sendWebhookTest", "setCustomerMandate", "setMyCashregisterStockLocation", "setMyKasseLogo", "setMyKasseSettings", "setMyRegisterDeviceSettings", "stripeCaptureIntent", "transferStock", "unpairRegisterDevice", "updateArticle", "updateCustomer", "updateInvoiceItem", "updatePartnerWebhook", "updateVariantGroup", "updateWebhook", "withdrawInvoiceItem"];
+/** Warum ein Aufruf keine Wirkung hat, die ein Zeitlimit offen lassen koennte. */
+export type CallWithoutEffectReason = 'read' | 'repeatable';
+/**
+ * Die Aufrufe **ohne Wirkung**, je mit Grund. Bei ihnen bleibt es bei
+ * `outcome: 'rejected'`, auch nach Zeitlimit, Netzfehler oder HTTP 5xx; eine
+ * Wiederholung bucht nichts doppelt:
+ *
+ * - `read`: reines Lesen (auch Berichte, Dateien, `generateFullReceiptId`,
+ *   das nur einen Link-Schluessel ableitet, und `getCustomerCredentials`,
+ *   dessen Abruf das Backend nur mitschreibt).
+ * - `repeatable`: legt etwas an, das ohne die verlorene Antwort niemand
+ *   erreicht und das von selbst verfaellt, und bucht nichts. Die Sitzung der
+ *   Kassen-Anmeldung (anmelden, verlaengern, abmelden: eine Wiederholung legt
+ *   hoechstens eine weitere kurzlebige Sitzung an bzw. verlaengert oder
+ *   beendet dieselbe noch einmal) und der Stripe-Zahlungslink
+ *   (`createPaymentLinkStripe`: den Link kennt nur die Antwort, ein nie
+ *   zugestellter Link wird nie bezahlt; Geld bewegt erst die Zahlung bzw.
+ *   `stripeCaptureIntent`).
+ *
+ * Probelaeufe (`previewGoodsReceipt`, `previewInvoice`) teilen den Namen mit
+ * dem echten Aufruf und stehen darum nicht hier; die Huellen setzen fuer sie
+ * `hasEffect: false` beim Aufruf, das nur zusammen mit `dryRun: true` gilt
+ * (siehe `TransportCallOptions`).
+ *
+ * Paketintern; nicht Teil der Paketoberflaeche.
+ */
+export declare const CALLS_WITHOUT_EFFECT: Readonly<Record<string, CallWithoutEffectReason>>;
+/**
+ * Hat dieser Aufruf Wirkung, ist sein Ausgang nach Zeitlimit, Netzfehler,
+ * HTTP 5xx oder unlesbarer Erfolgsantwort also unklar? `financeWebService`
+ * zaehlt mit jedem Vorgang. Ein Name, den dieses Paket nicht kennt (der
+ * offene Transport nimmt jeden), ist `false`; wer so einen Aufruf mit Wirkung
+ * absetzt, sagt es mit `hasEffect: true`.
+ */
+export declare function isUnknownOutcomeCall(name: string): boolean;
 /** Einer der 28 Aufrufe des Kassenwegs. */
 export declare function isPosCall(name: string): boolean;
 /**
@@ -40,6 +94,6 @@ export declare function isPosCall(name: string): boolean;
  */
 export declare function isPosOnlyCall(name: string): boolean;
 /** Wie [KasseneckTransport], nur mit bekanntem Aufrufnamen. Nicht exportiert nach aussen. */
-export type InternerTransport = <T = unknown>(functionName: ApiCall, params?: Record<string, unknown>, extraBodyFields?: TransportBodyFields, secretParams?: readonly string[]) => Promise<T>;
+export type InternerTransport = <T = unknown>(functionName: ApiCall, params?: Record<string, unknown>, extraBodyFields?: TransportBodyFields, secretParams?: readonly string[], options?: TransportCallOptions) => Promise<T>;
 /** Wie [KasseneckBinaryTransport], nur mit bekanntem Aufrufnamen. */
 export type InternerBinaerTransport = (functionName: ApiCall, params?: Record<string, unknown>) => Promise<Uint8Array>;