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

package/CHANGELOG.md

@@ -4,6 +4,439 @@ 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.0.0
+
+The package speaks the English API `/v3` and nothing else, and its own
+surface is English as well: exported names, fields, values, error codes,
+subpaths, text catalogue keys, placeholders and the contract files in
+`fixtures/`. Reason: the backend now runs `/v3` for every endpoint
+group, `/v1` is deprecated, and a half-German client on an English wire would
+translate twice and drift. One breaking release instead of several: every
+consumer migrates once. Rendered texts (messages, labels, printed receipts,
+invoice PDFs) are byte for byte the same as in 0.31.0, and so are the printed
+bytes of every golden receipt.
+
+This entry is written in English, like the developer documentation from here
+on.
+
+### Migrating from 0.x
+
+#### The 0.x line
+
+0.x keeps talking to `/v1` and gets fixes only. Before 1.0.0 becomes
+`latest`, the last 0.x release is to be tagged with the npm dist-tag `legacy`, so
+that `npm install @kreiseck/kasseneck-api@legacy` keeps installing it; until then,
+pin the 0.x version you use (`@kreiseck/kasseneck-api@^0.31.0`). Nothing forces
+an upgrade as long as `/v1` is served.
+
+#### Wire: `/v3` only
+
+- **Base URLs.** Public calls go to `https://api.kasseneck.at/v3`
+  (`DEFAULT_BASE_URL`, option `baseUrl`), the register calls to
+  `https://kasse.kasseneck.at/api/v3` (`POS_BASE_URL`, new option
+  `posBaseUrl`). The browser register on its own origin passes
+  `posBaseUrl: '/api/v3'`. The package routes each call itself: the 19
+  register-only calls (pairing, sign-in, settings, articles, printers, …)
+  always take the register path, and with `registerUserAuth` so do the six
+  calls both paths serve (`createReceipt`, `getReceipt`,
+  `generateFullReceiptId`, `cancelReceipt`, `sendReceiptEmail`,
+  `listMyTipRecipients`). `PUBLIC_CALLS` and `POS_CALLS` list them. Reason:
+  the register path and the public API are different hosts with different
+  authentication; a single base could not serve both.
+- **`baseUrl` now covers public calls only.** Whoever passed `baseUrl` to
+  pairing, sign-in or the register calls (the browser register used `/api`)
+  switches to `posBaseUrl: '/api/v3'`. Every base must end in `/v3` once
+  trailing slashes are removed; `/v1` or a bare `/api` throws a
+  `KasseneckValidationError` when the client is created. Reason: a 1.x client
+  must never speak `/v1` by accident.
+- **Marker, fail closed.** Requests to a Kasseneck base carry
+  `Kasseneck-Api-Version: v3` and `Kasseneck-Client: kasseneck-api/<version>`
+  (new option `clientHeader` for apps that name themselves). Each response is
+  checked before its body is read: HTTP 200 with HTML is `route_missing`, a
+  response without `Kasseneck-Api-Version: v3` is `dialect_mismatch`, HTTP 404
+  with marker and error envelope is `not_found`. All three are
+  `KasseneckApiError`s. In 0.x an HTML page at HTTP 200 was a
+  `KasseneckHttpError`. Reason: an answer from an edge without `/v3` may still
+  have signed a receipt, and reading it as a 0.x answer would hide that.
+- **Browser on another origin.** Until the backend allows the two headers in
+  the `/v3` CORS preflight, a browser that calls `api.kasseneck.at/v3` from a
+  foreign origin sets the new option `omitKasseneckHeaders: true`. The
+  response check stays. Same-origin clients and Node need nothing.
+- **English keys, values and codes on the wire.** Error codes are English,
+  lower case, `snake_case`: `bereits_storniert` is `already_cancelled`,
+  `STORNO_REFUND_REFERENCE_UNKNOWN` is `cancellation_refund_reference_unknown`,
+  `PAYMENTS_SUM_MISMATCH` is `payments_sum_mismatch`, `adresse_ungueltig` is
+  `invalid_address`, `zu_oft` is `too_many_requests`. Cancellation reasons are
+  `input_error`, `customer_cancelled`, `wrong_payment_method`, `duplicate`,
+  `other` (the German display text stays in `CANCELLATION_REASONS`). Register
+  settings are `{ business, device }` with English keys and values
+  (`stil: 'nacht'` is `theme: 'night'`). `listMyReceipts` sends
+  `cashregisterId`, `sendReceiptEmail` takes `language` (was `sprache`) and
+  reports `via` as `own`, `platform` or `platform_fallback`. The invoice API
+  uses `docType` `invoice`/`credit_note` (was `RE`/`GU`) and `taxScheme`
+  `intraCommunitySupply` (was `igLieferung`). Texts for people (`message`,
+  `serverMessage`, `nextSteps`) and the terms of the BMF and FinanzOnline stay
+  German.
+
+#### Behaviour changes
+
+- **`payments[]` is mandatory** on every sale (`sellReceipt`,
+  `sellReceiptWithCompany`, `createReceipt` with `standard` or `training`),
+  empty only when the amount due is 0. The new `receiptDueCents(items,
+  vouchers, receiptType, { tip, tipRecipient })` computes that amount exactly
+  as the backend does, including its rounding (checked against 1206 cases
+  computed by the backend's own code, `fixtures/receipt-due-generated.json`);
+  `receiptDueBreakdown` adds the buckets. `paymentsExpectedCents(error)` reads
+  the expected amount of a `payments_sum_mismatch`. Reason: `/v3` knows no
+  single payment method; a table that pays with two cards and cash is one
+  receipt.
+- **`tipRecipient` is required** in `receiptDueCents` (`'owner'` or
+  `'staff'`) for a tip without `recipients`, and each `recipients[].owner` is
+  required. Reason: an owner's tip is turnover, spread over the goods' VAT
+  rates and discounted with them, a staff tip is not; only the register knows
+  who is signed in, and a guess would give a wrong amount due. The helper also
+  refuses `tip` together with `payments[].tipCents` (`tip_conflict`, as the
+  server does). On the sale itself `tip.sofortErhalten` is
+  `tip.receivedImmediately`, and unknown tip keys throw.
+- **`outcome` on errors.** `KasseneckApiError`, `KasseneckHttpError` and
+  `KasseneckNetworkError` carry `outcome: 'unknown' | 'rejected'`
+  (`ErrorOutcome`), and `isOutcomeUnknown(error)` covers all three. Unknown
+  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.
+- **Strict validation before sending.** The 0.x payment fields
+  (`paymentMethod`, `paymentMethodFromServer`, `creditCardProvider`,
+  `cardPaymentId`, `cardPaymentData`) throw, also from plain JavaScript.
+  Unknown keys in tips, layout options, register settings and
+  `sendReceiptEmail` throw; for the layout options of 0.x (`testKasse`,
+  `testSignatur`, `pruefangaben`, `regelwerk`) the message names the English
+  successor. Settings values outside a field's list, a `vatRates` map without
+  any rate switched on, unknown shortcut actions and a key bound twice are
+  rejected. A card refund through a provider without its own
+  `providerPaymentId` and without the original payment's id throws before
+  sending. Reason: under 0.x an unknown German option was ignored, and a test
+  receipt could silently lose its TESTKASSE banner.
+- **Register settings: send only what changed.** Values the package does not
+  know are kept as read (`PosOpen<T>`, `unknownPosSettingValues`) and never
+  replaced by a default; `posSettingsChanges(before, after)` produces the
+  patch, with `vatRates` and `shortcuts` as whole maps. `mergePosSettings`
+  always drops the German values of 0.x; `sanitizePosSettings` does the same
+  for a state you stored yourself. Reason: the server merges deeply, and a
+  whole block would overwrite values a newer server knows.
+- **Unknown values stay visible.** `ReceiptSummary.cancellationStatus`
+  (was `stornoStand` `offen`/`teil`/`voll`) is `none`/`partial`/`full`, or
+  `'unknown'` for a value this version does not know; a missing field stays
+  missing and never becomes `none`. `PrintJobStatus` gains `'unknown'`, and
+  `isPrintJobFinished` treats it as final.
+- **Server layout first.** `receiptLayoutFromResult(result, {
+  fallbackPaperSize })` returns the server's `layout` (80 mm) whenever the
+  response carries one and only builds one otherwise (default `mm58`, as in
+  0.x). Print width is chosen by the print path. Reason: on the public
+  channel only the server's layout carries the card block.
+- **Error catalogues per endpoint group, one shape everywhere.**
+  `RECEIPT_ERROR_CODES` (new), `CANCELLATION_ERROR_CODES`,
+  `PAYMENT_ERROR_CODES`, `RECEIPT_EMAIL_ERROR_CODES`, `REGISTER_ERROR_CODES`
+  (new) and `POS_ERROR_CODES` (new) list the group's own codes, then the
+  sign-in and edge codes that can reach it, then the codes the package sets
+  itself (`CLIENT_ERROR_CODES`: `route_missing` everywhere,
+  `response_unreadable` for receipts and cancellations), so the derived types
+  are wider. The `payments[]` codes of a sale or cancellation
+  (`payments_sum_mismatch`, `payment_method_not_supported`, …) are in
+  `PAYMENT_ERROR_CODES`: a sale can answer with a code from
+  `RECEIPT_ERROR_CODES` or `PAYMENT_ERROR_CODES`, a cancellation with one from
+  `CANCELLATION_ERROR_CODES` or `PAYMENT_ERROR_CODES`.
+  `RECEIPT_EMAIL_SEND_ERROR_CODES` holds the four sending codes.
+  `INVOICE_ERROR_CODES` and `PARTNER_ERROR_CODES` stay the server's catalogues;
+  `INVOICE_REQUEST_ERROR_CODES` (new) and `PARTNER_REQUEST_ERROR_CODES` add
+  the sign-in, edge and package codes. Every group offers
+  `is…ErrorCode(value)`, `…ErrorCode(error)`, `is…Error(error, code?)` (a type
+  guard, code optional) and `…FieldErrors(error)`; new are `isReceiptError`,
+  `isCancellationError`, `isPaymentError`, `isReceiptEmailError`,
+  `isInvoiceErrorCode`, `receiptFieldErrors`, `cancellationFieldErrors`,
+  `paymentFieldErrors`, `receiptEmailFieldErrors` and `registerFieldErrors`, and
+  `isInvoiceError` takes the code as optional.
+- **Partner.** `partnerErrorAdvice` (was `partnerFehlerRat`) always returns a
+  sentence, with a fallback for unknown codes; `isPartnerError` accepts
+  unknown codes. `reportCustomerContract` is offered now.
+- **Tree shaking.** `package.json` declares `"sideEffects": false`, so a
+  bundler drops every module whose exports are unused (esbuild, one import of
+  `isOutcomeUnknown` from the root: 13 kB before, 2 kB after). No module
+  changes anything outside itself when imported, and the package ships no
+  CSS; the build checks both (`scripts/check-build-exports.mjs`). Parameter
+  names of exported functions and methods are English now as well (for
+  example `rasterizeLogo(rgba, pxWidth, pxHeight, dimensions, chars)`); that
+  changes nothing at runtime.
+
+#### Exported names
+
+Every German export name has an English successor; there are no aliases, so
+the compiler finds every place to change. The most common ones:
+
+| Area | 0.x | 1.0 |
+|---|---|---|
+| root | `AUFRUFE`, `Aufruf` | `ALL_CALLS`, `ApiCall` |
+| root | `KASSE_BETRIEB_STANDARD`, `KASSE_GERAET_STANDARD`, `mergeKasseSettings`, `fromKasseArtikelPayload` | `POS_BUSINESS_DEFAULTS`, `POS_DEVICE_DEFAULTS`, `mergePosSettings`, `fromPosArticlePayload` |
+| root | `KasseSettings`, `KasseSettingsBetrieb`, `KasseSettingsGeraet`, `KasseArtikel` | `PosSettings`, `PosBusinessSettings`, `PosDeviceSettings`, `PosArticle` |
+| layout | `AKTUELLES_REGELWERK`, `LayoutRegelwerk`, `Pruefangaben` | `CURRENT_LAYOUT_RULESET`, `LayoutRuleset`, `RegistrationInfo` |
+| layout options | `testKasse`, `testSignatur`, `pruefangaben`, `regelwerk` | `testCashregister`, `testSignature`, `registrationInfo`, `ruleset` |
+| `ReceiptWithCompany` | `testKasse`, `testSignatur`, `kopfId`, `pruefangaben`, `logoStufe` | `testCashregister`, `testSignature`, `headerVersionId`, `registrationInfo`, `logoScale` |
+| `ReceiptCompany` | `taxnr`, `uid` | `taxNumber`, `vatId` |
+| layout lines | `regelwerk`, `ton` (`belegart`, `warnung`) | `ruleset`, `tone` (`receipt_type`, `warning`) |
+| receipt sheet | `belegBlatt`, `BelegBlatt`, `BlattBlock`, `LogoStufe`, `logoRaster`, `logoMass` | `receiptSheet`, `ReceiptSheet`, `SheetBlock`, `SheetLogoSize`, `rasterizeLogo`, `logoDimensions` |
+| sheet fields | `zeichen`, `bloecke`, `art`, `fett`, `marke`, `stufe`, `pxBreite`, `pxHoehe` | `charsPerLine`, `blocks`, `kind`, `bold`, `brandMark`, `size`, `pixelWidth`, `pixelHeight` |
+| printing | `qrGroesseFuer`, `QR_DRUCK_PUNKTE`, `QrModulGroesse` (`klein`/`mittel`/`gross`) | `qrSizingFor`, `QR_PRINT_WIDTH_DOTS`, `QrModuleSize` (`small`/`medium`/`large`) |
+| printing options | `qrGroesse`, `qrModus`, `qrAusweich`, `qrFehler`, `marke` | `qrModuleSize`, `qrMode`, `qrFallback`, `qrError`, `brandMark` |
+| React | `BelegBlattView`, `BelegBlattZeilen`, `qrVerdeckt` | `ReceiptSheetView`, `ReceiptSheetLines`, `qrHidden` |
+| `./pos` | `getKasseSettings`, `setMyKasseSettings`, `KASSE_TASTEN_AKTIONEN`, `TASTEN_AKTIONEN` | `getPosSettings`, `setMyPosSettings`, `POS_SHORTCUT_ACTIONS` |
+| `./pos` value lists | `STIL`, `SCHRIFT`, `DRUCKER_ART`, `PAPIER`, `KASSIEREN_MODUS`, … | `THEME`, `FONT_SIZE`, `PRINTER_TYPE`, `PAPER_SIZE`, `CHECKOUT_MODE`, … |
+| `./pos` texts | `MELDUNGEN`, `BESCHRIFTUNGEN`, `meldung`, `beschriftung`, `BELEG_MAIL_FEHLER`, `belegMailFehler` | `MESSAGES`, `LABELS`, `messageText`, `labelText`, `RECEIPT_EMAIL_ERROR_MESSAGES`, `receiptEmailErrorMessage` |
+| `./pos` printers | `NetzDrucker`, `DruckJob`, `druckerId`, `titel`, `quelle`, `marke` | `NetworkPrinter`, `PrintJob`, `printerId`, `title`, `source`, `brandMark` |
+| `./register` | `RegisterGeraeteAngaben`, `RegisterSessionsStand`, `altbestand`, `selbst` | `RegisterDeviceInfo`, `RegisterSessionOverview`, `pinPolicyOutdated`, `own` |
+| `./invoice` | `createRechnungApi`, `rechnungKeyAuth`, `istRechnungFehler`, `rechnungFeldFehler`, `RECHNUNG_TEXTE` | `createInvoiceApi`, `invoiceKeyAuth`, `isInvoiceError`, `invoiceFieldErrors`, `INVOICE_TEXTS` |
+| `./invoice` | `rechnungSummen`, `RECHNUNG_AUFRUFE`, `RECHNUNG_VERTRAG_VERSION` (1) | `computeInvoiceTotals`, `INVOICE_ENDPOINTS`, `INVOICE_CONTRACT_VERSION` (2) |
+| `./invoice/calc` | `rechnungRechnen`, `positionAusEuro`, `RechenFehler`, `STEUERFREIE_FAELLE`, `BETRAG_GRENZE_CENTS` | `calculateInvoice`, `itemFromEuro`, `CalcError`, `ZERO_RATED_TAX_SCHEMES`, `MAX_AMOUNT_CENTS` |
+| `./invoice/calc` codes | `kein_ganzzahlwert`, `ausserhalb`, `kein_zahlwert`, `nachkommastellen` | `not_integer`, `out_of_range`, `not_a_number`, `too_many_decimals` |
+| `./partner` | `PARTNER_ABLAUF`, `PARTNER_FEHLER_CODES`, `istPartnerFehler`, `partnerFehlerRat`, `partnerFeldFehler` | `PARTNER_FLOW`, `PARTNER_ERROR_CODES`, `isPartnerError`, `partnerErrorAdvice`, `partnerFieldErrors` |
+| `./partner` types | `Betrieb`, `Kunde`, `Kasse`, `SignaturStand`, `WebhookZustellung` | `Business`, `PartnerCustomer`, `CustomerCashregister`, `CustomerSignatureStatus`, `WebhookDelivery` |
+| enums | `VatRate.vat4komma9` | `VatRate.vat4_9` |
+| misc | `KasseneckSecret.vorhanden`, `UsbTimeoutError.schritt`, `istZeroKind`, `verteileRabatt` | `hasValue`, `step`, `isZeroKind`, `distributeDiscount` |
+
+The register settings fields follow the `/v3` vocabulary (`logoAn` is
+`logoEnabled`, `zahlGetrennt` is `paySplit`, `kassierenModus` is
+`checkoutMode`, `druckerArt` is `printerType`, `tasten` is `shortcuts`, the
+shortcut action `kassieren` is `checkout`, `getrennt` is `splitPayment`, …).
+The complete list of settings keys and values, like every other renamed
+key in the contract files, is in `fixtures/renames-1.0.json` (`structure`,
+`values`). For export names the TSDoc of each 1.0 export and the compiler are
+the reference: an old name no longer resolves.
+
+#### Subpaths
+
+| 0.x | 1.0 |
+|---|---|
+| `@kreiseck/kasseneck-api/kasse` | `@kreiseck/kasseneck-api/pos` |
+| `@kreiseck/kasseneck-api/rechnung` | `@kreiseck/kasseneck-api/invoice` |
+| `@kreiseck/kasseneck-api/rechnung/rechnen` | `@kreiseck/kasseneck-api/invoice/calc` |
+| (none) | `@kreiseck/kasseneck-api/stored` |
+
+The old subpaths are gone, not aliased.
+
+#### Text keys and placeholders
+
+The keys of the register catalogue (`MESSAGES`, `LABELS`) and of the invoice
+texts are English: `storno.ergebnis_unklar` is `cancellation.outcome_unknown`,
+`getrennt.*` is `split.*`, `kartenzahlung.*` is `card_payment.*`,
+`abschluss.*` is `completion.*`, `steuer.igLieferung.titel` is
+`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
+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`,
+`network`, `unexpected`, `other`. Every rendered text is unchanged; a test
+fills each text of both catalogues old and new with the same values and
+compares them character for character. The full key and placeholder tables
+are `texts` and `placeholders` in `fixtures/renames-1.0.json`.
+
+#### Contract files
+
+The files in `fixtures/` have English paths and keys: `kasse-texte.json` is
+`pos-texts.json`, `oberflaeche.json` is `surface.json`,
+`kasse-settings-standard.json` is `pos-settings-defaults.json`,
+`rechnung-texte.json` is `invoice-texts.json`, `belege/` is `receipts/`,
+`erwartet/` is `expected/` (`.blatt32.json` is `.sheet32.json`), golden
+receipts are renamed (`verkauf-bar` is `sale-cash`, `storno-voll` is
+`cancellation-full`), and the manifest uses `ruleset`, `receipts`, `input`,
+`expected`. `surface.json` replaces `aufrufe` with `baseUrls`, `calls` and
+`routes`. `fixtures/renames-1.0.json` lists every path and key that changed
+from 0.30.0/0.31.0, the renamed machine values and the shape changes; a test
+checks it against the frozen 0.x inventory, so no old key is missing. New: `fixtures/v3/` (the backend's `/v3` contract, copied byte for
+byte), `receipt-due-generated.json`, `stored/pos-settings-defaults.json`.
+
+#### Removed
+
+- `createCancelReceipt`, `CreateCancelReceiptOptions` and cancelling through
+  `createReceipt` with `receiptType: 'cancellation'`: use `cancelReceipt`.
+- The single-payment path: `paymentMethod`, `paymentMethodFromServer`,
+  `creditCardProvider`, `cardPaymentId`, `cardPaymentData` on sales and
+  cancellations, and `SellReceiptWithPaymentsOptions` (there is only one way
+  to sell now).
+- The deprecated aliases of 0.28: `Rechtsform`, `Bundesland`, `KontaktRolle`
+  (use `LegalForm`, `AustrianState`, `ContactRole`).
+- `KASSE_TASTEN_AKTIONEN` and `TASTEN_AKTIONEN` as two names for one list:
+  there is only `POS_SHORTCUT_ACTIONS`.
+
+#### New
+
+- `…/stored`: `fromStoredReceipt`, `fromStoredReceiptWithCompany`,
+  `fromStoredCompany`, `fromStoredPosSettings`, `invalidStoredPosSettings`,
+  `fromStoredArticle` turn stored Firestore documents into the `/v3` models,
+  following the server's rules. For clients that read Firestore directly.
+- Receipts: `receiptDueCents`, `receiptDueBreakdown`, `paymentsExpectedCents`,
+  `cardRefundReference`, `receiptLayoutFromResult`, `getReportV2`,
+  `RECEIPT_ERROR_CODES`/`isReceiptErrorCode`, `CANCELLATION_STATUSES`,
+  `RECEIPT_EMAIL_VIAS`, `RECEIPT_EMAIL_SEND_ERROR_CODES`.
+- Transport: `POS_BASE_URL`, `PUBLIC_CALLS`, `POS_CALLS`, options
+  `posBaseUrl`, `clientHeader`, `omitKasseneckHeaders`; `ErrorOutcome`,
+  `isOutcomeUnknown`.
+- `…/register`: `REGISTER_ERROR_CODES`, `isRegisterErrorCode`,
+  `registerErrorCode`, `isRegisterError`, `registerErrorDetails`; the pairing
+  result carries `companyName`, `cashregisterLabel` and `testEnvironment`.
+- `…/pos`: `posSettingsChanges`, `sanitizePosSettings`,
+  `unknownPosSettingValues`, `posSettingsFromWire`, `POS_BUSINESS_VALUES`,
+  `POS_DEVICE_VALUES`, `POS_SHORTCUT_SHARED_PAIRS`, `posShortcutConflict`,
+  `setMyPosLogo`, `isPrintJobFinished`, `POS_ERROR_CODES`, `isPosError`,
+  `posFieldErrors`, `QUANTITY_RULES`, `PRINT_JOB_STATUSES`,
+  `PRINT_JOB_SOURCES`.
+- `…/partner`: `reportCustomerContract`, `PARTNER_REQUEST_ERROR_CODES`, the
+  value lists `LEGAL_FORMS`, `AUSTRIAN_STATES`, `CONTACT_ROLES`, `AVV_MODES`,
+  `FEE_INTERVALS`, `CONTRACT_KINDS`, `CONTRACT_SOURCES`,
+  `SIGNATURE_HISTORY_REASONS`, `SIGNATURE_ERROR_CODES`,
+  `WEBHOOK_DELIVERY_STATUSES`, and the events `customer.avv_accepted` and
+  `customer.terms_accepted` in `PARTNER_WEBHOOK_EVENTS`.
+- `…/invoice`: `WRITE_OFF_REASON_CODES`, `EINVOICE_MISSING_CODES`;
+  `getInvoiceXml` returns `{ xml, format, filename }` instead of the bare XML
+  text; `InvoiceDetail.payments[]` carries `id` and `reference`.
+
+## 0.31.0
+
+Texte und Einstellung für „Getrennt zahlen" an der Kasse (ein Tisch zahlt in Teilen, ein Beleg mit
+mehreren Zahlungen). Nur Texte, eine Einstellung und eine Tasten-Aktion; kein Aufruf und kein
+Rechenweg ändert sich.
+
+- **`tenderedCents` an jeder Barzahlung**: die Doku an `ReceiptPaymentInput` und
+  `PAYMENT_TENDERED_INVALID` sagte „höchstens an einer Zahlung“. Das Backend erlaubt jetzt jeder
+  Barzahlung ihren eigenen gegebenen Betrag. Grund: beim getrennten Zahlen gibt jeder Gast selbst,
+  der Bon zeigte Gegeben/Rückgeld aber nur beim letzten. Der Bon druckte schon je Zahlung; ein Test
+  hält drei Barzahlungen mit je eigenem Rückgeld fest.
+- **Neue Sätze in `MELDUNGEN`** unter `getrennt.*` (Hinweis zur Einstellung, Prüfungen der
+  Teilzahlung, gesperrter Warenkorb, Rückbuchung bar/Terminal/Karte ohne Anbindung, angefangene
+  Sitzung nach dem Neuladen) und unter `storno.*` (Rückgabe je Zahlung, Karten nach dem Storno von Hand gutschreiben).
+  Grund: Browser-Kasse und Kassen-App sollen am Tresen dieselben Worte sagen; eine schon belastete
+  Karte nennt in jedem Satz den Betrag, und keiner rät zum zweiten Kassieren.
+- **`STORNO_ZAHLUNG_FEHLER`**: Zuordnung der Backend-Codes `STORNO_PAYMENTS_REQUIRED`,
+  `STORNO_REFUND_EXCEEDS_PAYMENT`, `STORNO_REFUND_REFERENCE_REQUIRED`,
+  `STORNO_REFUND_REFERENCE_UNKNOWN` und `PAYMENTS_SUM_MISMATCH` zu ihrem Satz, auch in
+  `fixtures/kasse-texte.json` (`stornoZahlungFehler`). Grund: beide Kassen entscheiden am Code,
+  nie am Wortlaut des Backends. `stornoZahlungFehler(code)` liefert den Schlüssel dazu, ein
+  unbekannter Code fällt auf `storno.fehlgeschlagen` (wie `belegMailFehler`).
+- **Neuer Storno-Code `STORNO_OUTCOME_UNKNOWN`** am Ende von `CANCELLATION_ERROR_CODES` (Zwilling
+  von `STORNO_FEHLERCODES` in `functions/gemeinsam/storno-core.js`; unter `/v3`
+  `cancellation_outcome_unknown`, `isCancellationErrorCode` prüft weiter exakt) mit dem Satz
+  `storno.ergebnis_unklar`. Grund: der Storno-Beleg kann schon signiert sein, obwohl der Ausgang
+  offen ist; wer dann noch einmal storniert, storniert womöglich doppelt. Der Satz rät darum,
+  nicht zu wiederholen und die Belegliste später neu zu laden.
+- **Aufteilung als eigener Schritt**: neue Beschriftungen `getrennt.weiter` („Weiter · {betrag}
+  getrennt“), `getrennt.aufteilung`, `getrennt.zurueck_zahlart`, `getrennt.tab_positionen`,
+  `getrennt.tab_betrag`, `getrennt.stueck_mehr`/`_weniger`,
+  `getrennt.gegeben`, `getrennt.gegeben_rueckgeld` und die Sätze
+  `getrennt.positionen_gesperrt` und `getrennt.positionen_waehlen`. Grund: Nutzertest – erst
+  „Weiter“, dann je Zahlung nach Positionen (stückweise) oder als Betrag. Nach einer Zahlung als
+  Betrag ist „Nach Positionen“ gesperrt, weil sich Beträge keinen Stücken zuordnen lassen; der
+  Satz sagt das.
+- **Zahlart je Zahlung, ein Knopf zum Hinzufügen**: `getrennt.zahlart` („Zahlart“),
+  `getrennt.art_bar`/`getrennt.art_karte` („Bar“/„Karte“) als Umschalter oben in der Zahlung,
+  `getrennt.zahlung_hinzufuegen` („Zahlung hinzufügen · {betrag}“) für den einen Knopf unten
+  rechts und der Satz `getrennt.gegeben_fehlt` (Barzahlung ohne „Gegeben“ bei eingeschaltetem
+  Rückgeld-Rechner, Wortlaut wie beim Abschluss). `getrennt.bar_kassieren`/`getrennt.karte_kassieren`
+  und `getrennt.kassieren` („Zahlung {n} kassieren“) entfallen (noch nie veröffentlicht). Grund: Nutzertest – zwei Knöpfe, die sofort kassieren,
+  lagen zu nah beieinander; jetzt wählt der Kassier die Zahlart wie jede andere Eingabe, und nur
+  ein Knopf löst die Zahlung aus. Offen 0 macht aus demselben Knopf „Abschließen“.
+- **Nach Positionen als Kacheln**: `getrennt.offene_positionen`, `getrennt.stueck_offen`
+  („{n} offen“), `getrennt.stueck_gewaehlt` („{n} von {offen}“), `getrennt.nichts_gewaehlt` und
+  `getrennt.alles_bezahlt`. `getrennt.stueck_bezahlt` entfällt (noch nie veröffentlicht): bezahlte
+  Stück verschwinden aus der Auswahl. Grund: Nutzertest – in der großen Fläche stehen nur noch die
+  offenen Produkte als Kacheln, der Kassier tippt dort an, was dieser Gast zahlt.
+- **`BESCHRIFTUNGEN` und `beschriftung()`**: ein zweiter Katalog für Knöpfe und Zeilennamen
+  („Getrennt", „Zahlung {n}", „Offen", „Rest", „÷ {n}", „davon Trinkgeld {betrag}", „Wie
+  zurückgeben?", „Alles bar", „Mehrere" …), in `fixtures/kasse-texte.json` unter `beschriftungen`.
+  Grund: `MELDUNGEN` führt nur Sätze (die Wächter beider Kassen erkennen Sätze daran), „Rest" ist
+  keiner – muss aber in beiden Kassen gleich heißen. Die Zahlarten folgen dem Bon
+  („Kartenzahlung", „Barzahlung").
+- **Vier weitere Sätze unter `getrennt.*`**: `sitzung_unlesbar` (eine auf dem Gerät abgelegte
+  Sitzung lässt sich nicht mehr lesen – auf schon belastete Karten hinweisen, im Panel oder am
+  Terminal nachsehen lassen), `ablage_fehlgeschlagen` (die Ablage schlägt fehl – vor dem
+  Neuladen warnen, sonst verschwinden belastete Karten aus der Liste), `zu_viele_zahlungen`
+  (höchstens 20 Zahlungen je Beleg) und `entkoppeln_offene_karten` (ein entkoppeltes Gerät hatte
+  noch offene Kartenzahlungen – die Beträge stehen daneben, der Satz selbst bleibt ohne
+  Platzhalter). Grund: die Ablage der Teilzahlung läuft rein lokal auf dem Gerät; geht sie
+  verloren oder lässt sie sich nicht lesen, ist eine schon belastete Karte das teure Risiko, und
+  der Satz muss zum Nachschauen anleiten statt zum Weiterkassieren zu verleiten.
+- **Einstellung `zahlGetrennt`** (Betrieb, Standard `false`) und **Tasten-Aktion `getrennt`**
+  (ohne Vorgabe-Taste). Grund: für Betriebe ohne Bedarf bleibt die Kasse, wie sie ist; eine
+  unerprobte Vorgabe-Taste finge womöglich der Browser ab. Das Backend (`kasse-settings-core.js`)
+  muss beide nachziehen, sonst verwirft sein Validator den Wert beim Speichern.
+- **Vorgabe `kassierenModus` jetzt `'panel'`** (vorher `'seite'`): kassiert wird im Korb-Panel,
+  die Kacheln bleiben stehen. Grund: Nutzertest – so bleibt der Kachelbereich beim Kassieren
+  sichtbar, auch beim getrennten Zahlen. Ein gespeichertes `'seite'` bleibt; gespeichert werden
+  aber nur geänderte Felder, darum wechselt jedes Konto, das den Schalter nie angefasst hat, mit
+  dem Backend-Standard auf das Korb-Panel. Das Backend (`BETRIEB_STANDARD` in
+  `kasse-settings-core.js`) und der Dart-Zwilling ziehen denselben Wert nach.
+- **Texte, die bisher nur in der Browser-Kasse standen, jetzt im Katalog**: Sätze
+  `kassieren.nichts_erfasst`, `kassieren.gegeben_fehlt`, `kassieren.gegeben_zu_wenig`,
+  `kassieren.gesperrt` („Kassieren gesperrt: {grund}“), `trinkgeld.ueber_haelfte`,
+  `sitzung.meldet_ab` („Kasse meldet in {sekunden} s ab …“), `abmelden.noch_einmal`,
+  `kartenzahlung.terminal_bricht_ab` und `connect.entkoppeln_frage` (nur Web); Beschriftungen
+  `kassieren.trinkgeld`, `kassieren.kein`, `kassieren.eigener_betrag`, `kassieren.passend`,
+  `kassieren.gegeben_loeschen`, `kassieren.es_fehlen_noch`, `kassieren.rueckgeld`,
+  `kartenzahlung.betrag_am_terminal`, `kartenzahlung.karte_vorhalten` („… · noch {zeit}“),
+  `kopplung.neu_koppeln`, `abmelden.frage`, `abmelden.weiter_arbeiten`, `geraet.entkoppeln`,
+  `connect.entkoppeln_bestaetigen` (nur Web), `storno.titel` („Storno zu {beleg}“),
+  `meldung.ausblenden` („Meldung ausblenden: {meldung}“) und `meldung.warnung_ausblenden`
+  („Verstanden – Warnung ausblenden: {meldung}“). Wortlaut wie bisher in der Browser-Kasse.
+  Grund: Oberflächen-Vertrag – beide Kassen zeigen dieselben Wörter; das X an einer Meldung nennt
+  jetzt, welche Meldung es ausblendet (in der Ecke stehen oft mehrere).
+- **Halbgeviertstrich statt Geviertstrich** in allen sichtbaren Texten von `MELDUNGEN` (u. a.
+  `abschluss.unklar`, `kartenzahlung.unklar`, `kartenzahlung.karte_gebucht_beleg_offen`,
+  `connect.*`, `druck.*`) und in den Sätzen der Hobex-Antwortcodes (`transaction-response.ts`,
+  auch `fixtures/hobex-hps-codes.json`): „ – “ statt „ — “. Nur das Zeichen ändert sich, kein
+  Wortlaut und kein Schlüssel. Wer einen dieser Sätze wörtlich vergleicht, muss nachziehen.
+  Grund: einheitliche Typografie am Bildschirm; der Geviertstrich wirkt dort wie ein
+  Maschinenzeichen. Die Rechnungstexte (`rechnung/texte.ts`, PDF) bleiben unverändert.
+- **`Cancellation` trägt `refundedByPayment`** (Zahlungs-ID auf positive Cent), Zwilling der
+  gleichnamigen Backend-Ablage (`functions/gemeinsam/storno-core.js`). Die Lesung
+  (`fromReceiptPayload`) behält nur ganzzahlige, nicht negative Werte, verwirft ungültige
+  Einträge einzeln statt den ganzen Eintrag zu verwerfen, und lässt das Feld weg, wenn die
+  Nutzlast es nicht trägt – bestehende Belege lesen sich unverändert. Auch am `pending`-Eintrag
+  vorhanden. Grund: über alle Storno-Einträge darf je Zahlung nie mehr zurückgehen, als bezahlt
+  wurde; ohne das Feld ließe sich das am Client nicht nachvollziehen.
+- **Weitere Sätze in `MELDUNGEN`**: `getrennt.karte_bereits_zurueckgebucht` (das Terminal meldet
+  eine Gutschrift, die hier noch als offene Rückbuchung steht), `abschluss.erledigen_frage` (nur erledigen, was wirklich in der Belegliste steht),
+  `kartenzahlung.korb_gesperrt_karte_belastet` und `kartenzahlung.entkoppeln_karte_belastet`.
+  Grund: jeder dieser Zustände ist eine schon belastete oder gutgeschriebene Karte ohne
+  passenden Beleg – der teuerste Fehler am Tresen ist die doppelte Buchung, und kein Satz davon
+  darf zum Wiederholen raten, ohne vorher den Terminal-Beleg zu nennen.
+- **Weitere `BESCHRIFTUNGEN`**: `allgemein.abbrechen`, `abschluss.beleg_vorhanden`,
+  `abschluss.erledigen`, `getrennt.karte_zurueckbuchen`, `getrennt.trotzdem_neu_koppeln`,
+  `getrennt.zahlung_behalten`, `getrennt.klaeren`, `getrennt.wurde_belastet`,
+  `getrennt.nicht_belastet`, `getrennt.erneut_zurueckbuchen`, `storno.differenz`. Grund: Knöpfe
+  zu den neuen Sätzen oben, in beiden Kassen gleich beschriftet.
+- **Storno eines Belegs mit mehreren Zahlungen: Karten gehen von Hand zurück.**
+  `storno.karten_gutschreiben` steht nach dem gebuchten Storno über der Liste der Karten zum
+  Abhaken (eine oder mehrere, mit oder ohne Anbindung); `storno.ergebnis_unklar_karten` ersetzt
+  `storno.ergebnis_unklar`, wenn der gesendete Vorschlag Karten enthielt – erst die Belegliste
+  neu laden, erst dann gutschreiben (`STORNO_ZAHLUNG_FEHLER` zeigt weiter auf
+  `storno.ergebnis_unklar`, die Wahl trifft die Kasse am Vorschlag). Die Sätze und Knöpfe einer
+  Gutschrift am Terminal VOR dem Senden (`storno.gutschrift_laeuft`,
+  `storno.gutschrift_fehlgeschlagen`, `storno.gutschrift_unklar`,
+  `storno.gutgeschrieben_nicht_gebucht`, `storno.gutschrift_pruefen`,
+  `storno.extern_gutschreiben`, `storno.am_terminal_gutgeschrieben`,
+  `storno.nicht_gutgeschrieben`) sind wieder entfernt; sie waren nie veröffentlicht. Grund:
+  eine Gutschrift vor dem gebuchten Storno lässt Geld zurückgehen, ohne dass ein Storno-Beleg
+  sicher entsteht; die automatische Gutschrift kommt als eigener Schritt mit
+  Server-Unterstützung.
+- **`storno.karten_nicht_abgehakt`**: wird die Liste der Karten nach dem gebuchten Storno
+  geschlossen, obwohl nicht jede Karte abgehakt ist, fragt die Kasse einmal nach. Grund: eine
+  vergessene Gutschrift fällt sonst erst dem Gast auf, und am Storno-Beleg sieht sie niemand mehr.
+
 ## 0.30.0
 
 Mehrere Zahlungen je Beleg. Setzt ein Backend mit `payments` voraus (keck, live seit

package/README.de.md

@@ -22,20 +22,24 @@ optional und nur für `@kreiseck/kasseneck-api/react` nötig.
 ## Ein Beleg in wenigen Zeilen
 
 ```ts
-import { createKasseneckApi, apiKeyAuth, KeckPaymentMethod, VatRate } from '@kreiseck/kasseneck-api';
-import { buildReceiptLayout, escPosLayoutBytes } from '@kreiseck/kasseneck-api/receipt';
+import { createKasseneckApi, apiKeyAuth, KeckPaymentMethod, VatRate, receiptDueCents, receiptLayoutFromResult } from '@kreiseck/kasseneck-api';
+import { escPosLayoutBytes } from '@kreiseck/kasseneck-api/receipt';
 
 const api = createKasseneckApi({
   auth: apiKeyAuth({ apiKey: 'kr_live_…', cashregisterToken: 'cb_live_…' }),
 });
 
-const { receipt, company, testKasse, testSignatur, pruefangaben } = await api.sellReceiptWithCompany({
-  paymentMethod: KeckPaymentMethod.cash,
-  items: [{ name: 'Café Latte', quantity: 2, vat: VatRate.vat20, priceCents: 390 }],
+const items = [{ name: 'Café Latte', quantity: 2, vat: VatRate.vat20, priceCents: 390 }];
+const result = await api.sellReceiptWithCompany({
+  items,
+  // Die Zahlungen ergeben genau den Zahlbetrag (ganze Cent).
+  payments: [{ method: KeckPaymentMethod.cash, amountCents: receiptDueCents(items, [], 'standard') }],
 });
 
-const layout = buildReceiptLayout(receipt, company, { paperSize: 'mm58', testKasse, testSignatur, pruefangaben });
-const bytes = escPosLayoutBytes(layout);   // für den Bondrucker
+// Das Layout des Servers (`layout`, 80 mm) gewinnt; nur ohne entsteht es aus derselben Antwort (`fallbackPaperSize`, Vorgabe mm58).
+// Die Druckbreite wählt der Druckweg.
+const layout = receiptLayoutFromResult(result);
+const bytes = escPosLayoutBytes(layout, { paperSize: 'mm58' });   // für den Bondrucker
 ```
 
 Beträge sind immer ganze Cent (`priceCents`), Mengen am Beleg ganze Zahlen.