@kreiseck/kasseneck-api 1.0.0-rc.1 → 1.0.0-rc.3

package/CHANGELOG.md

@@ -104,13 +104,49 @@ an upgrade as long as `/v1` is served.
   means the operation may have happened: `dialect_mismatch`,
   `receipt_outcome_unknown`, `cancellation_outcome_unknown`,
   `response_translation_failed` (unless `details.handled === false`),
-  `response_unreadable` (a signing call reported success but the response
-  lacks the receipt, the reference or the remaining quantities), and on
-  `createReceipt`, `cancelReceipt` and `financeWebService` a network error,
-  timeout or HTTP 5xx after sending as well as HTTP 200 with the `/v3` marker
-  but an empty, non-JSON or status-less body. Never retry those; read the
-  result back. Reason: a retried receipt is a second signed receipt in the
-  chain.
+  `response_unreadable` (a signing or money call reported success but the
+  response lacks the receipt, the reference, the remaining quantities, the
+  Hobex receipt or the captured payment intent), and on `createReceipt`,
+  `cancelReceipt`, `financeWebService`, `hobexPayApi`, `hobexRefundApi` and
+  `stripeCaptureIntent` a network error, timeout or HTTP 5xx after sending as
+  well as HTTP 200 with the `/v3` marker but an empty, non-JSON (also HTML) or
+  status-less body. Never retry those; read the result back. Reason: a
+  retried receipt is a second signed receipt in the chain.
+- **Money calls have an unknown outcome too (1.0.0-rc.2).** `hobexPay`,
+  `hobexRefund` and `stripeCaptureIntent` joined the calls above. In rc.1 a
+  timeout, network error or HTTP 5xx on them was `'rejected'`, and a success
+  reply without a readable Hobex receipt or payment intent was a
+  `KasseneckValidationError` (`scope: 'response'`); now both are `'unknown'`
+  (the latter as `KasseneckApiError` `response_unreadable`), and HTML with the
+  `/v3` marker is `not-json` with `'unknown'` instead of `route_missing`. An
+  error envelope throws a `KasseneckApiError` with its `code`; `hobexRefund`
+  never returns `false`. **Callers must never retry these calls, and must not
+  pass a `fetch` that retries by itself or wrap the package's requests in a
+  retrying layer** (proxy, service worker, HTTP client with a retry policy).
+  Reason: an app that read `'rejected'` could charge or refund a card twice;
+  a silent resend below the package does the same without any error. Same
+  change as in the Dart twin `kasseneck_api` (no `RetryClient`).
+- **Findings of the Dart twin (1.0.0-rc.3).** `listMyCashregisters` reads
+  the start receipt under `onboarding.start_receipt_created`/`_transmitted`
+  (`_at`) as `/v3` sends it; rc.1 and rc.2 read the internal
+  `startbeleg_*` names and reported every register as having no start
+  receipt (`CashregisterOnboardingPayload` changes accordingly). The fields
+  of `CashregisterOnboarding` are English now as well: `startbelegCreated`
+  is `startReceiptCreated`, `startbelegTransmitted` is
+  `startReceiptTransmitted`, `startbelegCreatedAt` is `startReceiptCreatedAt`,
+  `startbelegTransmittedAt` is `startReceiptTransmittedAt`; the German-name
+  guard no longer exempts `startbeleg`.
+  `sendReceiptEmail` reads its success reply leniently: without `to` it
+  returns the address you sent, without `at` it returns `at: null`
+  (`SendReceiptEmailResult.at` is `string | null`); throwing there would
+  invite a second email. `listMyPrinters` without `data.printers` and
+  `createPrintJob`/`getPrintJob` without `data.jobId` throw a
+  `KasseneckValidationError` (`scope: 'response'`) instead of returning an
+  empty list or an empty id: "no printer yet" must not look like a broken
+  reply, and a job without an id cannot be polled, so the cashier would print
+  again. `setMyRegisterDeviceSettings` takes `shortcuts` only as the whole map
+  of known actions (as `posSettingsChanges` produces it): the server checks
+  keys bound twice only within the map it receives.
 - **Strict validation before sending.** The 0.x payment fields
   (`paymentMethod`, `paymentMethodFromServer`, `creditCardProvider`,
   `cardPaymentId`, `cardPaymentData`) throw, also from plain JavaScript.
@@ -237,7 +273,7 @@ texts are English: `storno.ergebnis_unklar` is `cancellation.outcome_unknown`,
 `tax.intra_community_supply.title`. Every part is lower case with underscores,
 only country codes stay upper case (`country.AT`). Placeholders are English
 too: `{betrag}` is `{amount}`, `{grund}` is `{reason}`, `{sekunden}` is
-`{seconds}`, `{uid}` is `{vatId}`, and so on for 23 of 30 names; pass the
+`{seconds}`, `{uid}` is `{vatId}`, and so on for 25 of 30 names; pass the
 values under the new names (`messageText('checkout.locked', { reason })`). An
 old name throws as a missing value. `ERROR_RULES` entries use
 `kind`/`behavior`/`key` with the kinds `api`, `plain_text`, `timeout`,

package/README.md

@@ -427,9 +427,10 @@ silently. For a layout option of 0.x the message names its English successor.
 ### `outcome: 'unknown'`: never retry, look it up
 
 `KasseneckApiError`, `KasseneckHttpError` and `KasseneckNetworkError` carry
-`outcome`. `'rejected'` means no signing operation is left open: no receipt was
-signed and nothing went to FinanzOnline, so retrying the same request does not
-create a second receipt (whether it helps depends on the code). `'unknown'` means the operation **may have been carried out**, for
+`outcome`. `'rejected'` means no operation with an effect is left open: no
+receipt was signed, nothing went to FinanzOnline and no money moved, so
+retrying the same request does not create a second receipt or charge (whether
+it helps depends on the code). `'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
@@ -437,18 +438,35 @@ 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 call reported success, but the response
-  lacks what the call promises (no receipt, no reference, no remaining
-  quantities);
-- on the signing calls `createReceipt`, `cancelReceipt` and
-  `financeWebService`: a network error or timeout after sending began, HTTP
+- `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,
   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.
 
-`outcome` only covers signing. After a network error on `issueInvoice` an
-invoice may still have been issued; retry it with the same `idempotencyKey`.
+On the money calls an unknown outcome means the card may have been charged,
+the refund may have gone through, the payment may have been captured. A
+rejection of `hobexRefund` throws a `KasseneckApiError` with its `code`; it
+never returns `false`, because a `false` on an unclear outcome invites a
+second refund.
+
+**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`.
 
 ```ts
 import { isOutcomeUnknown, paymentsExpectedCents } from '@kreiseck/kasseneck-api';
@@ -597,10 +615,14 @@ const confirmation = await api.sendReceiptEmail({
   language: 'de',                        // optional; the backend currently only uses 'de'
 });
 confirmation.to;   // address as the backend logged it (trimmed, lower case)
-confirmation.at;   // time, ISO with Vienna offset
+confirmation.at;   // time, ISO with Vienna offset, or null
 confirmation.via;  // 'own' | 'platform' | 'platform_fallback' | null
 ```
 
+A success response means the email has gone out. If it lacks `to` or `at`,
+the call still succeeds: `to` falls back to the address you sent and `at` is
+`null`. Throwing there would invite sending the email a second time.
+
 The email contains a **link to the public receipt page**, not a PDF
 attachment: the receipt page uses the same line model as screen and printed
 receipt and offers a PDF there. The receipt itself stays untouched (BAO § 131,
@@ -792,6 +814,11 @@ process:
 - **Hobex cloud** (`hobexPay`, `hobexRefund`): a terminal registered with
   Hobex, controlled over the network through the backend. Amounts are passed in
   cents; the package converts to euros for Hobex.
+
+`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)).
 - **Hobex HPS via Kasseneck Connect**, described below.
 
 ### Hobex HPS via Kasseneck Connect

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

@@ -20,7 +20,7 @@
  *   Single-Page-App hat geantwortet, der Aufruf kam nie an),
  *   `dialect_mismatch` (Antwort ohne Kennzeichen `Kasseneck-Api-Version: v3`:
  *   ein Rand ohne `/v3` hat geantwortet, **Ausgang unklar**) und
- *   `response_unreadable` (ein signierender Aufruf meldete Erfolg, die
+ *   `response_unreadable` (ein Aufruf mit Wirkung meldete Erfolg, die
  *   Antwort traegt aber nicht, was er zusagt: **Ausgang unklar**).
  *   **Entscheidend ist `outcome`:** `'rejected'` heisst abgelehnt, nichts
  *   geschehen, Wiederholen hilft nicht. `'unknown'` heisst: der Vorgang kann
@@ -29,14 +29,16 @@
  * - `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 signierenden
- *   Aufruf hat HTTP 5xx `outcome: 'unknown'`, ebenso HTTP 200 mit
- *   Kennzeichen, aber leerem oder unlesbarem Rumpf.
+ *   `reason` trennt die Faelle maschinenlesbar. Auf einem Aufruf mit
+ *   Wirkung (signierend oder geldbewegend) 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
- *   der signierenden (`createReceipt`, `cancelReceipt`, `financeWebService`),
- *   ist er `'unknown'`.
+ *   mit Wirkung (signierend: `createReceipt`, `cancelReceipt`,
+ *   `financeWebService`; geldbewegend: `hobexPayApi`, `hobexRefundApi`,
+ *   `stripeCaptureIntent`), ist er `'unknown'`.
  * - `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
@@ -111,7 +113,7 @@ export type ErrorOutcome = 'unknown' | 'rejected';
 /**
  * Codes, die das Paket selbst vergibt, nicht der Server: `route_missing`
  * (HTML statt Backend, der Aufruf kam nie an) und `response_unreadable`
- * (ein signierender Aufruf meldete Erfolg, die Antwort ist aber unlesbar;
+ * (ein Aufruf mit Wirkung meldete Erfolg, die Antwort ist aber unlesbar;
  * Ausgang unklar). `dialect_mismatch` vergibt das Paket ebenfalls, der Code
  * gehoert aber schon zum Rand des Servers (`errorCodes.edge`).
  */
@@ -142,7 +144,7 @@ export declare class KasseneckApiError extends Error {
     /**
      * `'unknown'` bei `dialect_mismatch`, `receipt_outcome_unknown`,
      * `cancellation_outcome_unknown`, `response_unreadable` (Erfolg gemeldet,
-     * Antwort eines signierenden Aufrufs aber unlesbar) und
+     * Antwort eines Aufrufs mit Wirkung aber unlesbar) und
      * `response_translation_failed` (ausser mit `details.handled === false`);
      * sonst `'rejected'`. Bei `'unknown'` nie wiederholen, sondern nachlesen.
      */
@@ -162,8 +164,9 @@ export declare class KasseneckHttpError extends Error {
     /** Maschinenlesbarer Grund — trennt den Rewrite-Fall vom 500er ohne Textparsen. */
     readonly reason: HttpFailureReason;
     /**
-     * `'unknown'` auf einem signierenden Aufruf (`createReceipt`,
-     * `cancelReceipt`, `financeWebService`) bei HTTP 5xx und bei HTTP 200 mit
+     * `'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).
@@ -249,3 +252,16 @@ export declare function isKasseneckHttpError(error: unknown): error is Kasseneck
 export declare function isKasseneckNetworkError(error: unknown): error is KasseneckNetworkError;
 export declare function isKasseneckAuthError(error: unknown): error is KasseneckAuthError;
 export declare function isKasseneckValidationError(error: unknown): error is KasseneckValidationError;
+/**
+ * Liest die Erfolgsantwort eines Aufrufs **mit Wirkung** (signierend oder
+ * geldbewegend). Scheitert das Lesen (fehlender Beleg, fehlender Bezug,
+ * unbrauchbares Feld oder ein Laufzeitfehler beim Umwandeln), hat der Server
+ * trotzdem Erfolg gemeldet: der Beleg ist signiert und im DEP, die Karte
+ * belastet bzw. der Einzug gelaufen. Das darf nie als gewoehnlicher Fehler
+ * enden, sonst kassiert die Kasse ein zweites Mal. Darum wird daraus
+ * `KasseneckApiError` mit Code `response_unreadable` und `outcome: 'unknown'`.
+ * Der Grund stammt vom Paket; aus der Antwort selbst wird nichts uebernommen.
+ *
+ * Paketintern (receipts.ts, payments/); nicht Teil der Paketoberflaeche.
+ */
+export declare function signiertGelesen<T>(functionName: string, lesen: () => T): T;

package/dist/cjs/client/errors.js

@@ -21,7 +21,7 @@
  *   Single-Page-App hat geantwortet, der Aufruf kam nie an),
  *   `dialect_mismatch` (Antwort ohne Kennzeichen `Kasseneck-Api-Version: v3`:
  *   ein Rand ohne `/v3` hat geantwortet, **Ausgang unklar**) und
- *   `response_unreadable` (ein signierender Aufruf meldete Erfolg, die
+ *   `response_unreadable` (ein Aufruf mit Wirkung meldete Erfolg, die
  *   Antwort traegt aber nicht, was er zusagt: **Ausgang unklar**).
  *   **Entscheidend ist `outcome`:** `'rejected'` heisst abgelehnt, nichts
  *   geschehen, Wiederholen hilft nicht. `'unknown'` heisst: der Vorgang kann
@@ -30,14 +30,16 @@
  * - `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 signierenden
- *   Aufruf hat HTTP 5xx `outcome: 'unknown'`, ebenso HTTP 200 mit
- *   Kennzeichen, aber leerem oder unlesbarem Rumpf.
+ *   `reason` trennt die Faelle maschinenlesbar. Auf einem Aufruf mit
+ *   Wirkung (signierend oder geldbewegend) 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
- *   der signierenden (`createReceipt`, `cancelReceipt`, `financeWebService`),
- *   ist er `'unknown'`.
+ *   mit Wirkung (signierend: `createReceipt`, `cancelReceipt`,
+ *   `financeWebService`; geldbewegend: `hobexPayApi`, `hobexRefundApi`,
+ *   `stripeCaptureIntent`), ist er `'unknown'`.
  * - `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
@@ -80,6 +82,7 @@ exports.isKasseneckHttpError = isKasseneckHttpError;
 exports.isKasseneckNetworkError = isKasseneckNetworkError;
 exports.isKasseneckAuthError = isKasseneckAuthError;
 exports.isKasseneckValidationError = isKasseneckValidationError;
+exports.signiertGelesen = signiertGelesen;
 // Bezeichner-artig: Buchstabe vorn, danach nur Bezeichnerzeichen, hoechstens
 // 64 Zeichen. Das laesst `TypeError`, `ECONNREFUSED` und `auth/internal-error`
 // durch, aber keinen Freitext und kein ID-Token (~900 Zeichen).
@@ -236,7 +239,7 @@ function ausgangAusCode(code, details) {
 /**
  * Codes, die das Paket selbst vergibt, nicht der Server: `route_missing`
  * (HTML statt Backend, der Aufruf kam nie an) und `response_unreadable`
- * (ein signierender Aufruf meldete Erfolg, die Antwort ist aber unlesbar;
+ * (ein Aufruf mit Wirkung meldete Erfolg, die Antwort ist aber unlesbar;
  * Ausgang unklar). `dialect_mismatch` vergibt das Paket ebenfalls, der Code
  * gehoert aber schon zum Rand des Servers (`errorCodes.edge`).
  */
@@ -266,7 +269,7 @@ class KasseneckApiError extends Error {
     /**
      * `'unknown'` bei `dialect_mismatch`, `receipt_outcome_unknown`,
      * `cancellation_outcome_unknown`, `response_unreadable` (Erfolg gemeldet,
-     * Antwort eines signierenden Aufrufs aber unlesbar) und
+     * Antwort eines Aufrufs mit Wirkung aber unlesbar) und
      * `response_translation_failed` (ausser mit `details.handled === false`);
      * sonst `'rejected'`. Bei `'unknown'` nie wiederholen, sondern nachlesen.
      */
@@ -301,8 +304,9 @@ class KasseneckHttpError extends Error {
     /** Maschinenlesbarer Grund — trennt den Rewrite-Fall vom 500er ohne Textparsen. */
     reason;
     /**
-     * `'unknown'` auf einem signierenden Aufruf (`createReceipt`,
-     * `cancelReceipt`, `financeWebService`) bei HTTP 5xx und bei HTTP 200 mit
+     * `'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).
@@ -426,3 +430,24 @@ function isKasseneckAuthError(error) {
 function isKasseneckValidationError(error) {
     return error instanceof KasseneckValidationError;
 }
+/**
+ * Liest die Erfolgsantwort eines Aufrufs **mit Wirkung** (signierend oder
+ * geldbewegend). Scheitert das Lesen (fehlender Beleg, fehlender Bezug,
+ * unbrauchbares Feld oder ein Laufzeitfehler beim Umwandeln), hat der Server
+ * trotzdem Erfolg gemeldet: der Beleg ist signiert und im DEP, die Karte
+ * belastet bzw. der Einzug gelaufen. Das darf nie als gewoehnlicher Fehler
+ * enden, sonst kassiert die Kasse ein zweites Mal. Darum wird daraus
+ * `KasseneckApiError` mit Code `response_unreadable` und `outcome: 'unknown'`.
+ * Der Grund stammt vom Paket; aus der Antwort selbst wird nichts uebernommen.
+ *
+ * Paketintern (receipts.ts, payments/); nicht Teil der Paketoberflaeche.
+ */
+function signiertGelesen(functionName, lesen) {
+    try {
+        return lesen();
+    }
+    catch (ursache) {
+        const grund = ursache instanceof KasseneckValidationError ? ursache.reason : 'Antwort nicht lesbar';
+        throw new KasseneckApiError(functionName, `Erfolg gemeldet, Antwort aber unlesbar (${grund}). Der Vorgang kann ausgefuehrt sein: nicht wiederholen, sondern nachlesen.`, {}, 'response_unreadable');
+    }
+}

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

@@ -315,10 +315,17 @@ export interface SendReceiptEmailOptions {
 }
 /** Was der Versand bestaetigt (Backend: beleg-mail-endpoints.js). */
 export interface SendReceiptEmailResult {
-    /** Adresse in der Form, in der das Backend sie protokolliert hat (getrimmt, klein). */
+    /**
+     * Adresse in der Form, in der das Backend sie protokolliert hat (getrimmt,
+     * klein). Nennt die Antwort keine, die gesendete (getrimmte) Adresse.
+     */
     to: string;
-    /** Zeitpunkt des Versands, ISO mit Wiener Zonenoffset (`2026-09-11T14:05:00+02:00`). */
-    at: string;
+    /**
+     * Zeitpunkt des Versands, ISO mit Wiener Zonenoffset
+     * (`2026-09-11T14:05:00+02:00`). `null`, wenn die Antwort keinen nennt: der
+     * Versand ist trotzdem bestaetigt.
+     */
+    at: string | null;
     /**
      * Versandweg: `own` (Postfach des Betriebs), `platform` oder
      * `platform_fallback` ([RECEIPT_EMAIL_VIAS]). `null`, wenn die Antwort ihn

package/dist/cjs/client/receipts.js

@@ -58,12 +58,12 @@ function receiptLayoutFromResult(result, options = {}) {
  */
 async function createReceipt(rufen, options) {
     const daten = await rufen('createReceipt', createReceiptParams(options));
-    return signiertGelesen('createReceipt', () => belegAusHuelle(daten, 'createReceipt'));
+    return (0, errors_js_1.signiertGelesen)('createReceipt', () => belegAusHuelle(daten, 'createReceipt'));
 }
 /** Wie [createReceipt], liest aus derselben Antwort zusaetzlich die Firmendaten. */
 async function createReceiptWithCompany(rufen, options) {
     const daten = await rufen('createReceipt', createReceiptParams(options));
-    return signiertGelesen('createReceipt', () => belegMitFirmaAusHuelle(daten, 'createReceipt'));
+    return (0, errors_js_1.signiertGelesen)('createReceipt', () => belegMitFirmaAusHuelle(daten, 'createReceipt'));
 }
 /**
  * Baut die Nutzlast von `createReceipt` und prueft die Eingabe. Wirft, bevor
@@ -199,7 +199,7 @@ async function cancelReceipt(transport, options) {
     if (zahlungen !== undefined)
         params.payments = zahlungen;
     const daten = await transport('cancelReceipt', params);
-    return signiertGelesen('cancelReceipt', () => stornoAusHuelle(daten));
+    return (0, errors_js_1.signiertGelesen)('cancelReceipt', () => stornoAusHuelle(daten));
 }
 /** Liest die Storno-Antwort `{ receipt, cancellationOf, remaining }`. */
 function stornoAusHuelle(daten) {
@@ -395,14 +395,17 @@ async function sendReceiptEmail(transport, options) {
     if (options.language !== undefined && options.language !== '')
         params.language = options.language;
     const daten = await transport('sendReceiptEmail', params);
-    if (typeof daten?.to !== 'string' || daten.to === '') {
-        throw antwortfehler('sendReceiptEmail', 'Antwort nennt keine Empfaengeradresse (data.to fehlt)');
-    }
-    if (typeof daten.at !== 'string' || daten.at === '') {
-        throw antwortfehler('sendReceiptEmail', 'Antwort nennt keinen Zeitpunkt (data.at fehlt)');
-    }
-    const via = index_js_2.RECEIPT_EMAIL_VIAS.includes(daten.via) ? daten.via : null;
-    return { to: daten.to, at: daten.at, via };
+    // Nachsichtig gelesen (wie der Dart-Zwilling): eine Erfolgsantwort heisst,
+    // die Mail ist schon verschickt. Ein Fehler wegen eines fehlenden
+    // Antwortfelds luede zum zweiten Versand ein; also zurueck, was da ist.
+    const gemeldet = daten?.to;
+    const zeit = daten?.at;
+    const via = index_js_2.RECEIPT_EMAIL_VIAS.includes(daten?.via) ? daten.via : null;
+    return {
+        to: typeof gemeldet === 'string' && gemeldet.trim() !== '' ? gemeldet : to,
+        at: typeof zeit === 'string' && zeit !== '' ? zeit : null,
+        via,
+    };
 }
 /**
  * Prueft die Gutschein-Kombination eines Belegs und liefert den ersten
@@ -685,24 +688,6 @@ function kartenanbieter(wert) {
 function eingabefehler(grund) {
     return new errors_js_1.KasseneckValidationError('createReceipt', grund, 'request');
 }
-/**
- * Liest die Erfolgsantwort eines **signierenden** Aufrufs. Scheitert das
- * Lesen (fehlender Beleg, fehlender Bezug, unbrauchbares Feld oder ein
- * Laufzeitfehler beim Umwandeln), hat der Server trotzdem Erfolg gemeldet:
- * der Beleg ist signiert und im DEP. Das darf nie als gewoehnlicher Fehler
- * enden, sonst kassiert die Kasse ein zweites Mal. Darum wird daraus
- * `KasseneckApiError` mit Code `response_unreadable` und `outcome: 'unknown'`.
- * Der Grund stammt vom Paket; aus der Antwort selbst wird nichts uebernommen.
- */
-function signiertGelesen(functionName, lesen) {
-    try {
-        return lesen();
-    }
-    catch (ursache) {
-        const grund = ursache instanceof errors_js_1.KasseneckValidationError ? ursache.reason : 'Antwort nicht lesbar';
-        throw new errors_js_1.KasseneckApiError(functionName, `Erfolg gemeldet, Antwort aber unlesbar (${grund}). Der Vorgang kann ausgefuehrt sein: nicht wiederholen, sondern nachlesen.`, {}, 'response_unreadable');
-    }
-}
 /** Die Antwort meldete Erfolg, trug aber nicht, was der Aufruf zusagt. */
 function antwortfehler(functionName, grund) {
     return new errors_js_1.KasseneckValidationError(functionName, grund, 'response');

package/dist/cjs/client/transport.js

@@ -62,10 +62,22 @@ const KASSENECK_HOSTS = new Set(['api.kasseneck.at', 'kasse.kasseneck.at']);
 /** Die 1.x-Linie spricht nur `/v3`: jede Basis endet so (`/v3` oder `/api/v3`). */
 const V3_ENDE = /\/v3$/;
 /**
- * Aufrufe, die signieren bzw. bei FinanzOnline etwas ausloesen. Ein Netzfehler,
- * nachdem die Anfrage unterwegs war, laesst ihren Ausgang offen.
+ * Aufrufe mit Wirkung, die nie blind wiederholt werden duerfen: sie signieren
+ * (`createReceipt`, `cancelReceipt`), loesen bei FinanzOnline etwas aus
+ * (`financeWebService`) oder bewegen Geld (`hobexPayApi` belastet eine Karte,
+ * `hobexRefundApi` erstattet, `stripeCaptureIntent` zieht eine vorgemerkte
+ * Zahlung ein). Scheitert einer, nachdem die Anfrage unterwegs war (Netz,
+ * Zeitlimit, HTTP 5xx, unlesbare Erfolgsantwort, HTML mit Kennzeichen), ist
+ * sein Ausgang offen.
  */
-const SIGNIERENDE_AUFRUFE = new Set(['createReceipt', 'cancelReceipt', 'financeWebService']);
+const UNKNOWN_OUTCOME_CALLS = new Set([
+    'createReceipt',
+    'cancelReceipt',
+    'financeWebService',
+    'hobexPayApi',
+    'hobexRefundApi',
+    'stripeCaptureIntent',
+]);
 /**
  * Produkte, die das Backend in `Kasseneck-Client` zaehlt (Positivliste,
  * Nachtrag §6); alles andere zaehlte dort als `ungueltig`. Das Paket weist
@@ -162,9 +174,9 @@ function createCore(options) {
                     return ursache;
                 }
                 // Bis hierher kam keine verwertbare Antwort: Netz weg oder Zeitlimit.
-                // Die Anfrage war schon unterwegs: bei einem signierenden Aufruf kann
-                // der Beleg entstanden sein (Ausgang unklar, nachlesen).
-                return new errors_js_1.KasseneckNetworkError(fehlerName, abbruch.signal.aborted, zeitlimitMs, (0, errors_js_1.causeDigest)(ursache, geheimnisse), SIGNIERENDE_AUFRUFE.has(functionName) ? 'unknown' : 'rejected');
+                // Die Anfrage war schon unterwegs: bei einem Aufruf mit Wirkung kann
+                // der Beleg bzw. die Zahlung entstanden sein (Ausgang unklar, nachlesen).
+                return new errors_js_1.KasseneckNetworkError(fehlerName, abbruch.signal.aborted, zeitlimitMs, (0, errors_js_1.causeDigest)(ursache, geheimnisse), UNKNOWN_OUTCOME_CALLS.has(functionName) ? 'unknown' : 'rejected');
             };
             const basis = basisFuer(functionName);
             const url = `${basis}/${encodeURIComponent(functionName)}`;
@@ -217,18 +229,18 @@ function createCore(options) {
                     if (fehler)
                         throw fehler;
                 }
-                // 5xx auf einem signierenden Aufruf: der Handler kann gelaufen sein.
-                const ausgang = antwort.status >= 500 && SIGNIERENDE_AUFRUFE.has(functionName) ? 'unknown' : 'rejected';
+                // 5xx auf einem Aufruf mit Wirkung: der Handler kann gelaufen sein.
+                const ausgang = antwort.status >= 500 && UNKNOWN_OUTCOME_CALLS.has(functionName) ? 'unknown' : 'rejected';
                 throw new errors_js_1.KasseneckHttpError(fehlerName, antwort.status, inhaltstyp, 'server-error', ausgang);
             }
             // HTTP 200 mit HTML: die Auffangregel der Single-Page-App hat den Aufruf
             // bedient, keine Function hat ihn gesehen (Nachtrag §5.4, R15).
             if (inhaltstyp !== undefined && /^\s*text\/html\b/i.test(inhaltstyp)) {
                 // Mit Kennzeichen hat der `/v3`-Rand den Aufruf gesehen (etwa ein
-                // Proxy, der nur den Inhaltstyp umschreibt). Bei einem signierenden
-                // Aufruf kann der Beleg dann entstanden sein: unlesbarer Rumpf,
+                // Proxy, der nur den Inhaltstyp umschreibt). Bei einem Aufruf mit
+                // Wirkung kann der Beleg bzw. die Zahlung dann entstanden sein: unlesbarer Rumpf,
                 // Ausgang unklar, statt `route_missing`.
-                if (SIGNIERENDE_AUFRUFE.has(functionName) && traegtKennzeichen(antwort)) {
+                if (UNKNOWN_OUTCOME_CALLS.has(functionName) && traegtKennzeichen(antwort)) {
                     throw new errors_js_1.KasseneckHttpError(fehlerName, antwort.status, inhaltstyp, 'not-json', 'unknown');
                 }
                 throw new errors_js_1.KasseneckApiError(fehlerName, 'Route fehlt: die Antwort ist eine HTML-Seite statt des Backends', {}, 'route_missing');
@@ -245,8 +257,8 @@ function createCore(options) {
             }
             // Ab hier kam HTTP 200 mit Kennzeichen: der `/v3`-Rand hat den Aufruf
             // gesehen. Ist der Rumpf dann unlesbar (gekuerzt von einem Proxy,
-            // abgebrochene Verbindung), kann ein signierender Handler gelaufen sein.
-            const unlesbar = SIGNIERENDE_AUFRUFE.has(functionName) ? 'unknown' : 'rejected';
+            // abgebrochene Verbindung), kann ein Handler mit Wirkung gelaufen sein.
+            const unlesbar = UNKNOWN_OUTCOME_CALLS.has(functionName) ? 'unknown' : 'rejected';
             return auswerten(koerper, fehlerName, antwort.status, inhaltstyp, geheimnisse, unlesbar);
         }
         finally {

package/dist/cjs/models/cashregister.d.ts

@@ -45,11 +45,11 @@ export interface Cashregister {
  */
 export interface CashregisterOnboarding {
     cashboxRegistered: boolean;
-    startbelegCreated: boolean;
-    startbelegTransmitted: boolean;
+    startReceiptCreated: boolean;
+    startReceiptTransmitted: boolean;
     cashboxRegisteredAt?: Date;
-    startbelegCreatedAt?: Date;
-    startbelegTransmittedAt?: Date;
+    startReceiptCreatedAt?: Date;
+    startReceiptTransmittedAt?: Date;
 }
 /** Nutzlast-Form, die dieses Paket liest — die Feldnamen von `listMyCashregisters`. */
 export interface CashregisterPayload {
@@ -61,13 +61,19 @@ export interface CashregisterPayload {
     token?: string | null;
     onboarding?: CashregisterOnboardingPayload | null;
 }
+/**
+ * `onboarding` am Draht `/v3` (fixtures/v3/antworten/kasse.json): der
+ * Startbeleg heisst dort `start_receipt_*`. Die inneren Namen
+ * `startbeleg_*` sendet nur `/v1`; wer sie hier laese, meldete jede Kasse
+ * als „Startbeleg fehlt“.
+ */
 export interface CashregisterOnboardingPayload {
     cashbox_registered?: boolean | null;
-    startbeleg_created?: boolean | null;
-    startbeleg_transmitted?: boolean | null;
+    start_receipt_created?: boolean | null;
+    start_receipt_transmitted?: boolean | null;
     cashbox_registered_at?: string | null;
-    startbeleg_created_at?: string | null;
-    startbeleg_transmitted_at?: string | null;
+    start_receipt_created_at?: string | null;
+    start_receipt_transmitted_at?: string | null;
 }
 /**
  * Liest eine Kasse aus der Antwort. `id` gewinnt aus der Nutzlast, faellt aber

package/dist/cjs/models/cashregister.js

@@ -18,11 +18,11 @@ function fromCashregisterPayload(payload, id) {
         ...(payload.signature_id ? { signatureId: payload.signature_id } : {}),
         onboarding: {
             cashboxRegistered: ob.cashbox_registered === true,
-            startbelegCreated: ob.startbeleg_created === true,
-            startbelegTransmitted: ob.startbeleg_transmitted === true,
+            startReceiptCreated: ob.start_receipt_created === true,
+            startReceiptTransmitted: ob.start_receipt_transmitted === true,
             ...zeitfeld('cashboxRegisteredAt', ob.cashbox_registered_at),
-            ...zeitfeld('startbelegCreatedAt', ob.startbeleg_created_at),
-            ...zeitfeld('startbelegTransmittedAt', ob.startbeleg_transmitted_at),
+            ...zeitfeld('startReceiptCreatedAt', ob.start_receipt_created_at),
+            ...zeitfeld('startReceiptTransmittedAt', ob.start_receipt_transmitted_at),
         },
     };
 }

package/dist/cjs/payments/hobex.d.ts

@@ -45,6 +45,10 @@ export interface HobexTransactionIdOptions {
  *
  * **Der Endpunkt heisst `hobexPayApi`** — mit Suffix; ohne ihn gibt es ihn
  * nicht.
+ *
+ * **Nie wiederholen.** Bei `isOutcomeUnknown(e)` (Netz, Zeitlimit, HTTP 5xx,
+ * unlesbare Antwort) kann die Karte belastet sein: den Stand ueber die
+ * Transaktionskennung nachlesen, nicht ein zweites Mal belasten.
  */
 export declare function hobexPay(transport: InternerTransport, options: HobexPayOptions): Promise<HobexReceipt>;
 /**
@@ -57,7 +61,11 @@ export declare function hobexPay(transport: InternerTransport, options: HobexPay
  * schon im Transport, sobald der Status nicht ausdruecklich Erfolg ist. Ein
  * Wahrheitswert waere hier also immer `true` — eine Luege ueber den
  * Informationsgehalt, an der ein Aufrufer ein `if` aufhaengt, das nie greift.
- * Misserfolg kommt als geworfener Fehler.
+ * Misserfolg kommt als geworfener Fehler: eine Fehlerhuelle als
+ * [KasseneckApiError] mit Code, Netz, Zeitlimit, HTTP 5xx und eine unlesbare
+ * Erfolgsantwort mit `outcome: 'unknown'` (die Erstattung kann gelaufen sein).
+ * Ein `false` an dieser Stelle luede zum zweiten Versuch ein, also zur
+ * doppelten Erstattung. **Nie wiederholen**, sondern den Stand nachlesen.
  *
  * **Der Endpunkt heisst `hobexRefundApi`** — mit Suffix.
  */

package/dist/cjs/payments/hobex.js

@@ -41,6 +41,10 @@ const ENDPUNKT_REFUND = 'hobexRefundApi';
  *
  * **Der Endpunkt heisst `hobexPayApi`** — mit Suffix; ohne ihn gibt es ihn
  * nicht.
+ *
+ * **Nie wiederholen.** Bei `isOutcomeUnknown(e)` (Netz, Zeitlimit, HTTP 5xx,
+ * unlesbare Antwort) kann die Karte belastet sein: den Stand ueber die
+ * Transaktionskennung nachlesen, nicht ein zweites Mal belasten.
  */
 async function hobexPay(transport, options) {
     const params = zahlungsNutzlast(ENDPUNKT_PAY, options);
@@ -48,7 +52,11 @@ async function hobexPay(transport, options) {
     // geht sie als null raus, nicht gar nicht. Der Transport wirft nur
     // `undefined` weg, `null` bleibt erhalten — genau diese Unterscheidung.
     params['reference'] = options.reference ?? null;
-    return belegAusNutzlast(await transport(ENDPUNKT_PAY, params));
+    const daten = await transport(ENDPUNKT_PAY, params);
+    // Erfolg gemeldet heisst: die Karte ist belastet. Ist der Beleg dann
+    // unlesbar, bleibt der Ausgang unklar (`response_unreadable`), damit keine
+    // App ein zweites Mal belastet.
+    return (0, errors_js_1.signiertGelesen)(ENDPUNKT_PAY, () => belegAusNutzlast(daten));
 }
 /**
  * Erstattet eine zuvor ueber die Hobex-Cloud getaetigte Zahlung. Das Backend
@@ -60,7 +68,11 @@ async function hobexPay(transport, options) {
  * schon im Transport, sobald der Status nicht ausdruecklich Erfolg ist. Ein
  * Wahrheitswert waere hier also immer `true` — eine Luege ueber den
  * Informationsgehalt, an der ein Aufrufer ein `if` aufhaengt, das nie greift.
- * Misserfolg kommt als geworfener Fehler.
+ * Misserfolg kommt als geworfener Fehler: eine Fehlerhuelle als
+ * [KasseneckApiError] mit Code, Netz, Zeitlimit, HTTP 5xx und eine unlesbare
+ * Erfolgsantwort mit `outcome: 'unknown'` (die Erstattung kann gelaufen sein).
+ * Ein `false` an dieser Stelle luede zum zweiten Versuch ein, also zur
+ * doppelten Erstattung. **Nie wiederholen**, sondern den Stand nachlesen.
  *
  * **Der Endpunkt heisst `hobexRefundApi`** — mit Suffix.
  */

package/dist/cjs/payments/stripe.d.ts

@@ -57,5 +57,8 @@ export declare function createStripeLink(transport: InternerTransport, options:
  * **Der Parameter heisst `stripe_sessions_id`** — mit "sessions" im Plural, so
  * das Vorbild und so das Backend. Der naheliegende Singular waere ein fehlender
  * Pflichtparameter.
+ *
+ * **Nie wiederholen.** Bei `isOutcomeUnknown(e)` (Netz, Zeitlimit, HTTP 5xx,
+ * unlesbare Antwort) kann der Einzug gelaufen sein: den Stand nachlesen.
  */
 export declare function stripeCaptureIntent(transport: InternerTransport, stripeSessionId: string): Promise<StripeCaptureResult>;