@kreiseck/kasseneck-api 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -4,6 +4,64 @@ 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.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 }]`).
@@ -1566,7 +1600,11 @@ 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 with the same key; `previewGoodsReceipt` and the reading
+calls stay `'rejected'`. 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
@@ -1784,7 +1822,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,7 +12,7 @@
  * weiterhin jeden `string`: wer einen Aufruf braucht, den dieses Paket nicht
  * umhuellt, muss ihn weiterhin absetzen koennen.
  */
-import type { TransportBodyFields } from './transport.js';
+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"];
 export type ApiCall = typeof ALL_CALLS[number];
 /**
@@ -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", "cancelInvoice", "cancelReceipt", "changeStockCondition", "createArticle", "createCreditNote", "createCustomer", "createCustomerCashregister", "createInvoiceItem", "createPartnerCustomer", "createPartnerWebhook", "createPrintJob", "createReceipt", "createReservation", "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", "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>;

package/dist/cjs/client/aufrufe.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.POS_CALLS = exports.PUBLIC_CALLS = exports.ALL_CALLS = void 0;
+exports.CALLS_WITHOUT_EFFECT = exports.UNKNOWN_OUTCOME_CALLS = exports.POS_CALLS = exports.PUBLIC_CALLS = exports.ALL_CALLS = void 0;
+exports.isUnknownOutcomeCall = isUnknownOutcomeCall;
 exports.isPosCall = isPosCall;
 exports.isPosOnlyCall = isPosOnlyCall;
 exports.ALL_CALLS = [
@@ -242,6 +243,172 @@ exports.POS_CALLS = [
     'listMyStock',
     'setMyCashregisterStockLocation',
 ];
+/**
+ * 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`).
+ */
+exports.UNKNOWN_OUTCOME_CALLS = [
+    'activateCashregister',
+    'cancelInvoice',
+    'cancelReceipt',
+    'changeStockCondition',
+    'createArticle',
+    'createCreditNote',
+    'createCustomer',
+    'createCustomerCashregister',
+    'createInvoiceItem',
+    'createPartnerCustomer',
+    'createPartnerWebhook',
+    'createPrintJob',
+    'createReceipt',
+    'createReservation',
+    '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',
+    'updateWebhook',
+    'withdrawInvoiceItem',
+];
+/**
+ * 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.
+ */
+exports.CALLS_WITHOUT_EFFECT = Object.freeze({
+    checkPartnerCustomerEmail: 'read',
+    downloadDailyReport: 'read',
+    downloadReceipt: 'read',
+    downloadReport: 'read',
+    createPaymentLinkStripe: 'repeatable',
+    endRegisterSession: 'repeatable',
+    generateFullReceiptId: 'read',
+    getArticle: 'read',
+    getCustomer: 'read',
+    getCustomerCredentials: 'read',
+    getCustomerSignatureStatus: 'read',
+    getFirstReceiptDate: 'read',
+    getInvoice: 'read',
+    getInvoiceItem: 'read',
+    getInvoicePdf: 'read',
+    getInvoiceSetupStatus: 'read',
+    getInvoiceXml: 'read',
+    getKasseSettings: 'read',
+    getPartnerBilling: 'read',
+    getPartnerBillingMonth: 'read',
+    getPartnerCustomer: 'read',
+    getPartnerInfo: 'read',
+    getPrintJob: 'read',
+    getReceipt: 'read',
+    getReportV2: 'read',
+    getReservation: 'read',
+    getStock: 'read',
+    hobexGetStatus: 'read',
+    listArticles: 'read',
+    listBrands: 'read',
+    listCustomerCashregisters: 'read',
+    listInvoiceItems: 'read',
+    listInvoices: 'read',
+    listLocations: 'read',
+    listMyArticleGroups: 'read',
+    listMyArticles: 'read',
+    listMyCashregisters: 'read',
+    listMyPrinters: 'read',
+    listMyReceipts: 'read',
+    listMyStock: 'read',
+    listMyStockLocations: 'read',
+    listMyTipRecipients: 'read',
+    listPartnerCustomers: 'read',
+    listPartnerWebhookDeliveries: 'read',
+    listPartnerWebhooks: 'read',
+    listRegisterSessionsForDevice: 'read',
+    listRegisterUsersForDevice: 'read',
+    listReservations: 'read',
+    listStock: 'read',
+    listStockMovements: 'read',
+    listWebhookDeliveries: 'read',
+    listWebhooks: 'read',
+    lookupArticleByCode: 'read',
+    registerPinLogin: 'repeatable',
+    registerUserLogin: 'repeatable',
+    renewRegisterSession: 'repeatable',
+    searchCustomers: 'read',
+});
+const MIT_WIRKUNG = new Set(exports.UNKNOWN_OUTCOME_CALLS);
+/**
+ * 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`.
+ */
+function isUnknownOutcomeCall(name) {
+    return MIT_WIRKUNG.has(name);
+}
 const OEFFENTLICH = new Set(exports.PUBLIC_CALLS);
 const KASSENWEG = new Set(exports.POS_CALLS);
 const NUR_KASSE = new Set(exports.POS_CALLS.filter((name) => !OEFFENTLICH.has(name)));

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

@@ -25,20 +25,27 @@
  *   **Entscheidend ist `outcome`:** `'rejected'` heisst abgelehnt, nichts
  *   geschehen, Wiederholen hilft nicht. `'unknown'` heisst: der Vorgang kann
  *   ausgefuehrt sein (bei `createReceipt` ein signierter Beleg). Dann **nie
- *   wiederholen**, sondern das Ergebnis nachlesen (Belegliste, `getReceipt`).
+ *   blind wiederholen**: Belege, Stornos und Zahlungen nachlesen
+ *   (Belegliste, `getReceipt`, Terminal-Beleg); ein Aufruf mit
+ *   `idempotencyKey` (Lager schreiben, Rechnung, Partner-Betrieb mit
+ *   Schluessel) darf mit **demselben** Schluessel erneut gesendet werden und
+ *   wirkt genau einmal, nie mit einem neuen. `createInvoiceItem` erkennt die
+ *   Wiederholung an `source` + `reference` (dieselben Werte erneut senden);
+ *   Posten aendern oder zurueckziehen und Mandate haben keinen Schluessel:
+ *   erst nachlesen.
  * - `KasseneckHttpError` — die Antwort war **keine** verwertbare Huelle:
  *   HTTP 500/404 ohne Huelle, leerer Rumpf oder Text statt JSON. Beim
  *   Bericht-Download gelten dieselben Gruende fuer alles, was kein PDF ist.
  *   `reason` trennt die Faelle maschinenlesbar. Auf einem Aufruf mit
- *   Wirkung (signierend oder geldbewegend) hat HTTP 5xx
+ *   Wirkung (`UNKNOWN_OUTCOME_CALLS` in aufrufe.ts) hat HTTP 5xx
  *   `outcome: 'unknown'`, ebenso HTTP 200 mit Kennzeichen, aber leerem oder
  *   unlesbarem Rumpf.
  * - `KasseneckNetworkError` — die Antwort kam gar nicht: Netz weg, DNS,
  *   abgebrochene Verbindung oder Zeitueberschreitung (`timedOut`). Auch hier
  *   gilt `outcome`: war die Anfrage schon unterwegs und ist der Aufruf einer
- *   mit Wirkung (signierend: `createReceipt`, `cancelReceipt`,
- *   `financeWebService`; geldbewegend: `hobexPayApi`, `hobexRefundApi`,
- *   `stripeCaptureIntent`), ist er `'unknown'`.
+ *   mit Wirkung (signieren, Geld bewegen, buchen, ausstellen, anlegen,
+ *   aendern, loeschen, senden; die Liste `UNKNOWN_OUTCOME_CALLS`), ist er
+ *   `'unknown'`. Lesen und Probelauf bleiben `'rejected'`.
  * - `KasseneckAuthError` — es kam nicht einmal zur Anfrage, weil die Anmeldung
  *   scheiterte (fehlende Zugangsdaten, oder der Token-/Sitzungsgeber warf).
  *   In der Browser-Kasse mit ihrer 90-Sekunden-Sitzung ist das Alltag, kein
@@ -106,8 +113,10 @@ export declare function causeDigest(ursache: unknown, geheimnisse: readonly stri
 export declare function fehlerDetails(daten: unknown, geheimnisse: readonly string[]): Record<string, unknown>;
 /**
  * Ausgang eines gescheiterten Aufrufs. `'rejected'`: nichts geschehen.
- * `'unknown'`: der Vorgang kann ausgefuehrt sein; nie wiederholen, sondern
- * das Ergebnis nachlesen.
+ * `'unknown'`: der Vorgang kann ausgefuehrt sein; nie blind wiederholen.
+ * Belege, Stornos und Zahlungen nachlesen; ein Aufruf mit `idempotencyKey`
+ * nur mit **demselben** Schluessel erneut senden (wirkt genau einmal); ohne
+ * Schluessel erst nachlesen.
  */
 export type ErrorOutcome = 'unknown' | 'rejected';
 /**
@@ -195,12 +204,12 @@ export declare class KasseneckHttpError extends Error {
     /** Maschinenlesbarer Grund — trennt den Rewrite-Fall vom 500er ohne Textparsen. */
     readonly reason: HttpFailureReason;
     /**
-     * `'unknown'` auf einem Aufruf mit Wirkung (`createReceipt`,
-     * `cancelReceipt`, `financeWebService`, `hobexPayApi`, `hobexRefundApi`,
-     * `stripeCaptureIntent`) bei HTTP 5xx und bei HTTP 200 mit
-     * Kennzeichen, aber unlesbarem Rumpf (`empty-body`, `not-json` auch bei
-     * `text/html`, `missing-status`): der Handler kann gelaufen sein, nie wiederholen,
-     * sondern nachlesen. Sonst `'rejected'` (auch 4xx).
+     * `'unknown'` auf einem Aufruf mit Wirkung (`UNKNOWN_OUTCOME_CALLS`:
+     * signieren, Geld bewegen, buchen, ausstellen, anlegen, aendern, loeschen,
+     * senden) bei HTTP 5xx und bei HTTP 200 mit Kennzeichen, aber unlesbarem
+     * Rumpf (`empty-body`, `not-json` auch bei `text/html`, `missing-status`):
+     * der Handler kann gelaufen sein, nie blind wiederholen (siehe
+     * [ErrorOutcome]). Sonst `'rejected'` (auch 4xx, Lesen und Probelauf).
      */
     readonly outcome: ErrorOutcome;
     constructor(functionName: string, statusCode: number, contentType: string | undefined, reason: HttpFailureReason, outcome?: ErrorOutcome);
@@ -218,9 +227,10 @@ export declare class KasseneckNetworkError extends Error {
     /** Code der zugrunde liegenden Ursache, sofern unbedenklich (z. B. `ECONNREFUSED`). */
     readonly causeCode: string | undefined;
     /**
-     * `'unknown'`, wenn die Anfrage schon unterwegs war und der Aufruf signiert
-     * (`createReceipt`, `cancelReceipt`, `financeWebService`): dann nie
-     * wiederholen, sondern nachlesen. Sonst `'rejected'`.
+     * `'unknown'`, wenn die Anfrage schon unterwegs war und der Aufruf Wirkung
+     * hat (`UNKNOWN_OUTCOME_CALLS`): dann nie blind wiederholen (siehe
+     * [ErrorOutcome]). Sonst `'rejected'`, auch bei Lesen und Probelauf und
+     * wenn schon die Anmeldung das Zeitlimit verbrauchte.
      */
     readonly outcome: ErrorOutcome;
     constructor(functionName: string, timedOut: boolean, timeoutMs: number, cause?: CauseDigest, outcome?: ErrorOutcome);
@@ -273,9 +283,12 @@ export declare class KasseneckValidationError extends Error {
 export type KasseneckError = KasseneckApiError | KasseneckHttpError | KasseneckNetworkError | KasseneckAuthError | KasseneckValidationError;
 /**
  * Ist der Ausgang dieses Fehlers unklar (`outcome === 'unknown'`)? Dann den
- * Aufruf **nicht wiederholen**, sondern das Ergebnis nachlesen. Gilt fuer
- * jede Fehlerart; nur [KasseneckApiError], [KasseneckHttpError] und
- * [KasseneckNetworkError] koennen `'unknown'` sein.
+ * Aufruf **nicht blind wiederholen**: Belege, Stornos und Zahlungen
+ * nachlesen; einen Aufruf mit `idempotencyKey` nur mit **demselben**
+ * Schluessel erneut senden (wirkt genau einmal, ein neuer buchte doppelt);
+ * ohne Schluessel erst nachlesen. Gilt fuer jede Fehlerart; nur
+ * [KasseneckApiError], [KasseneckHttpError] und [KasseneckNetworkError]
+ * koennen `'unknown'` sein.
  */
 export declare function isOutcomeUnknown(error: unknown): boolean;
 export declare function isKasseneckApiError(error: unknown): error is KasseneckApiError;