@kreiseck/kasseneck-api 1.35.0 → 1.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/CHANGELOG.md +31 -9
  2. package/dist/cjs/client/api.d.ts +15 -1
  3. package/dist/cjs/client/api.js +4 -0
  4. package/dist/cjs/client/aufrufe.d.ts +2 -2
  5. package/dist/cjs/client/aufrufe.js +10 -0
  6. package/dist/cjs/client/auth.d.ts +9 -3
  7. package/dist/cjs/client/auth.js +5 -4
  8. package/dist/cjs/client/ewp.d.ts +125 -0
  9. package/dist/cjs/client/ewp.js +95 -0
  10. package/dist/cjs/client/index.d.ts +1 -0
  11. package/dist/cjs/client/index.js +4 -1
  12. package/dist/cjs/client/list-deposit-types.d.ts +3 -0
  13. package/dist/cjs/client/list-deposit-types.js +3 -0
  14. package/dist/cjs/client/receipts.d.ts +3 -3
  15. package/dist/cjs/index.d.ts +1 -1
  16. package/dist/cjs/index.js +4 -2
  17. package/dist/cjs/invoice/index.d.ts +2 -2
  18. package/dist/cjs/invoice/index.js +2 -1
  19. package/dist/cjs/invoice/texte.d.ts +5 -0
  20. package/dist/cjs/invoice/texte.js +10 -0
  21. package/dist/cjs/invoice/typen.d.ts +34 -1
  22. package/dist/cjs/invoice/vertrag.d.ts +13 -4
  23. package/dist/cjs/invoice/vertrag.js +29 -6
  24. package/dist/cjs/payments/hobex-hps/connect-client.d.ts +43 -1
  25. package/dist/cjs/payments/hobex-hps/connect-client.js +51 -1
  26. package/dist/cjs/payments/hobex-hps/outcome.d.ts +4 -3
  27. package/dist/cjs/payments/hobex-hps/payments.d.ts +85 -35
  28. package/dist/cjs/payments/hobex-hps/payments.js +137 -53
  29. package/dist/cjs/receipt/layout.js +1 -1
  30. package/dist/cjs/stored/vokabular.d.ts +1 -1
  31. package/dist/cjs/stored/vokabular.js +1 -1
  32. package/dist/cjs/version.d.ts +1 -1
  33. package/dist/cjs/version.js +1 -1
  34. package/dist/esm/client/api.d.ts +15 -1
  35. package/dist/esm/client/api.js +4 -0
  36. package/dist/esm/client/aufrufe.d.ts +2 -2
  37. package/dist/esm/client/aufrufe.js +10 -0
  38. package/dist/esm/client/auth.d.ts +9 -3
  39. package/dist/esm/client/auth.js +5 -4
  40. package/dist/esm/client/ewp.d.ts +125 -0
  41. package/dist/esm/client/ewp.js +89 -0
  42. package/dist/esm/client/index.d.ts +1 -0
  43. package/dist/esm/client/index.js +1 -0
  44. package/dist/esm/client/list-deposit-types.d.ts +3 -0
  45. package/dist/esm/client/list-deposit-types.js +3 -0
  46. package/dist/esm/client/receipts.d.ts +3 -3
  47. package/dist/esm/index.d.ts +1 -1
  48. package/dist/esm/index.js +1 -1
  49. package/dist/esm/invoice/index.d.ts +2 -2
  50. package/dist/esm/invoice/index.js +1 -1
  51. package/dist/esm/invoice/texte.d.ts +5 -0
  52. package/dist/esm/invoice/texte.js +10 -0
  53. package/dist/esm/invoice/typen.d.ts +34 -1
  54. package/dist/esm/invoice/vertrag.d.ts +13 -4
  55. package/dist/esm/invoice/vertrag.js +28 -5
  56. package/dist/esm/payments/hobex-hps/connect-client.d.ts +43 -1
  57. package/dist/esm/payments/hobex-hps/connect-client.js +50 -1
  58. package/dist/esm/payments/hobex-hps/outcome.d.ts +4 -3
  59. package/dist/esm/payments/hobex-hps/payments.d.ts +85 -35
  60. package/dist/esm/payments/hobex-hps/payments.js +138 -54
  61. package/dist/esm/receipt/layout.js +1 -1
  62. package/dist/esm/stored/vokabular.d.ts +1 -1
  63. package/dist/esm/stored/vokabular.js +1 -1
  64. package/dist/esm/version.d.ts +1 -1
  65. package/dist/esm/version.js +1 -1
  66. package/fixtures/hobex-hps-cases.json +654 -0
  67. package/fixtures/hobex-hps-codes.json +1 -1
  68. package/fixtures/invoice-api-examples/issue-error-deposit.json +39 -0
  69. package/fixtures/invoice-api-examples/issue-invoice-deposit.json +55 -0
  70. package/fixtures/invoice-api.schema.json +65 -2
  71. package/fixtures/invoice-texts.json +11 -1
  72. package/fixtures/manifest.json +1 -1
  73. package/fixtures/pos-texts.json +1 -1
  74. package/fixtures/receipts/card-hobex-hps.json +1 -1
  75. package/fixtures/surface.json +13 -4
  76. package/fixtures/v3/antworten/belege.json +1 -1
  77. package/fixtures/v3/antworten/belegmail.json +1 -1
  78. package/fixtures/v3/antworten/berichte.json +1 -1
  79. package/fixtures/v3/antworten/kasse-belege.json +1 -1
  80. package/fixtures/v3/antworten/kasse.json +2 -2
  81. package/fixtures/v3/antworten/lager.json +1 -1
  82. package/fixtures/v3/antworten/rechnungen.json +1 -1
  83. package/fixtures/v3/antworten/storno.json +1 -1
  84. package/fixtures/v3/stored/belege.json +1 -1
  85. package/fixtures/v3/stored/kasse.json +2 -2
  86. package/fixtures/v3/stored/rechnungen.json +1 -1
  87. package/fixtures/v3/v3-vokabular.json +358 -5
  88. package/fixtures/v3/zahlbetrag-faelle.json +1 -1
  89. package/package.json +1 -1
@@ -79,6 +79,12 @@ export const INVOICE_ERROR_CODES = [
79
79
  'reservation_not_active', // schon eingeloest oder freigegeben
80
80
  // Seit 1.15.0 (Vertrag): die Rechnungsnummer ist schon vergeben (§ 11 Abs. 1 Z 3 lit. h UStG), nichts ausgestellt.
81
81
  'invoice_number_taken',
82
+ // Seit 1.36.0 (Vertrag): Pfand an Positionen (`items[].deposit`), hinten angehaengt.
83
+ 'deposit_not_enabled', // Pfand ist fuer dieses Konto nicht eingeschaltet
84
+ 'deposit_type_not_found', // die Pfandart gibt es nicht (oder ist stillgelegt)
85
+ 'deposit_set_by_server', // das Pfand zu einer Artikelposition leitet der Server selbst ab
86
+ 'invalid_deposit_quantity', // die Pfandmenge passt nicht zur Menge der Position
87
+ 'invalid_deposit', // sonstige Pfandangabe unzulaessig, `index` nennt die Position
82
88
  ];
83
89
  /**
84
90
  * Codes, die Anmeldung und Rand auf jedem Rechnungsaufruf erzeugen koennen,
@@ -447,9 +453,26 @@ export const ITEM_FIELDS = Object.freeze({
447
453
  */
448
454
  articleId: id,
449
455
  });
456
+ /**
457
+ * Pfandangabe an einer Position (seit 1.36.0, `deposit`): die Position ist eine
458
+ * Pfandzeile zu der Position `depositFor` (Index in `items`, 0 bis 499). Gleich
459
+ * dem Feld `DEPOSIT_FELD` des Backends. Zeile fuer Zeile Pfand sendet das
460
+ * Fremdsystem selbst; zu einer Position mit `articleId` leitet der Server das
461
+ * Pfand ab (`deposit_set_by_server`).
462
+ */
463
+ export const DEPOSIT_ITEM_FIELD = Object.freeze({
464
+ type: 'object',
465
+ required: false,
466
+ fields: Object.freeze({
467
+ depositTypeId: { type: 'string', required: true, min: 1, max: 128 },
468
+ depositFor: { type: 'integer', required: true, min: 0, max: 499 },
469
+ gtin: { type: 'string', required: false, min: 8, max: 14, pattern: '^[0-9]{8,14}$' },
470
+ ownFilling: { type: 'boolean', required: false },
471
+ }),
472
+ });
450
473
  /**
451
474
  * Eine Rechnungsposition beim Ausstellen: die gemeinsamen Positionsfelder plus
452
- * `reservationId` (seit 1.5.0). Die Reservierung aus der Lager-API
475
+ * `reservationId` (seit 1.5.0) und `deposit` (seit 1.36.0). Die Reservierung aus der Lager-API
453
476
  * (`createReservation`) wird beim Ausstellen geprueft und beim Buchen der
454
477
  * Rechnung eingeloest; die Position braucht dazu `articleId`. Unbekannt =
455
478
  * `reservation_not_found`, schon eingeloest oder freigegeben =
@@ -459,7 +482,7 @@ export const ITEM_FIELDS = Object.freeze({
459
482
  * `reservation_expired`. Weniger verkauft als reserviert gibt den Rest frei.
460
483
  * Gutschriften kennen das Feld nicht (`validation`).
461
484
  */
462
- export const INVOICE_ITEM_FIELDS = Object.freeze({ ...ITEM_FIELDS, reservationId: id });
485
+ export const INVOICE_ITEM_FIELDS = Object.freeze({ ...ITEM_FIELDS, reservationId: id, deposit: DEPOSIT_ITEM_FIELD });
463
486
  /** Genau einer der beiden Preise je Position (§ 9.1). */
464
487
  export const ITEM_PRICE_EXACTLY_ONE = Object.freeze([
465
488
  Object.freeze(['unitPriceCents']),
@@ -478,11 +501,11 @@ const positionen = {
478
501
  const returnDisposition = { type: 'enum', required: false, values: RETURN_DISPOSITIONS };
479
502
  /**
480
503
  * Eine Gutschriftsposition: die gemeinsamen Positionsfelder plus
481
- * `returnDisposition` (wohin die zurueckgenommene Ware geht), ohne
482
- * `reservationId`. An einer Rechnungsposition weist der Server
504
+ * `returnDisposition` (wohin die zurueckgenommene Ware geht) und `deposit`
505
+ * (seit 1.36.0), ohne `reservationId`. An einer Rechnungsposition weist der Server
483
506
  * `returnDisposition` als unbekannt ab.
484
507
  */
485
- export const CREDIT_NOTE_ITEM_FIELDS = Object.freeze({ ...ITEM_FIELDS, returnDisposition });
508
+ export const CREDIT_NOTE_ITEM_FIELDS = Object.freeze({ ...ITEM_FIELDS, returnDisposition, deposit: DEPOSIT_ITEM_FIELD });
486
509
  const gutschriftPositionen = {
487
510
  type: 'list',
488
511
  required: true,
@@ -23,9 +23,44 @@ export interface HpsConnectTarget {
23
23
  host: string;
24
24
  /** Vorgabe: `8080` (hobex-HPS-Standardport), siehe Connect. */
25
25
  port?: number;
26
- /** Terminal-ID, wie am Geraet angezeigt (fuehrende Nullen werden toleriert). */
26
+ /**
27
+ * Terminal-ID, gern so, wie sie am Geraet und auf dem Beleg steht (achtstellig
28
+ * mit fuehrender Null, `03600335`). Das HPS kennt sie nur OHNE fuehrende Null
29
+ * und weist jede andere Schreibweise mit `100108 "Invalid TID"` ab; dieser
30
+ * Client schreibt sie deshalb vor jedem Aufruf um, siehe [normalizeHpsTid].
31
+ */
27
32
  tid: string;
28
33
  }
34
+ /**
35
+ * Die TID in der Form, die das hobex-HPS annimmt: Leerraum am Rand
36
+ * ([RAND_LEERRAUM]) und fuehrende Nullen fallen weg.
37
+ *
38
+ * Am 10.11.2026 gemessen (TID 3600335, HPS 1.14.4, Firmware 7.3.6): Diagnose
39
+ * und Zahlung mit `03600335` antworten sofort `100108 "Invalid TID"` (nichts
40
+ * belastet), mit `3600335` normal; `003600335`, `0360033` und `36003350` sind
41
+ * ebenfalls `Invalid TID`. Auf Beleg und Geraet steht die TID achtstellig mit
42
+ * fuehrender Null -- so wird sie auch eingetragen.
43
+ *
44
+ * Umgeschrieben wird NUR eine rein ziffrige TID mit mindestens einer Ziffer
45
+ * ungleich `0`. Alles andere geht UNVERAENDERT hinaus, auch die `0` der
46
+ * Erkennungsprobe von Connect und eine TID aus lauter Nullen: still etwas
47
+ * anderes daraus zu machen, hiesse ein anderes Terminal anzusprechen als das
48
+ * eingetragene. Bewusst kein Wurf: Connect weist eine nicht rein ziffrige TID
49
+ * selbst ab (`bad_request`, vor jedem Terminal-Kontakt, hier
50
+ * [HpsPreflightError]), und das HPS antwortet auf eine unbekannte mit
51
+ * `100108` -- in beiden Faellen geht kein Geld, und der Aufrufer bekommt den
52
+ * Grund auf dem Weg, den er fuer jede andere Abweisung auch auswertet.
53
+ *
54
+ * Kein Text (ein Aufrufer ohne Typpruefung uebergibt etwa eine Zahl) geht
55
+ * ebenso unveraendert hinaus: Connect weist ihn dann mit "Es fehlt die
56
+ * Terminal-ID" ab ([HpsPreflightError]), statt dass hier ein Wurf aus dem
57
+ * Zahlweg einen offenen Ausgang machte.
58
+ *
59
+ * Die einzige Stelle, an der die TID umgeschrieben wird: jeder Aufruf geht
60
+ * ueber `target`. Zwilling: `HpsClient` im Dart-Paket (`_normalizeTid`), Faelle
61
+ * in `fixtures/hobex-hps-cases.json`.
62
+ */
63
+ export declare function normalizeHpsTid(tid: string): string;
29
64
  export interface HpsConnectPaymentOptions extends HpsConnectTarget {
30
65
  /** Kennung dieser Zahlung — MUSS vor diesem Aufruf feststehen, siehe `transaction-id.ts`. */
31
66
  transactionId: string;
@@ -93,6 +128,13 @@ export interface HpsConnectClientOptions {
93
128
  export interface HpsConnectClient {
94
129
  payment(options: HpsConnectPaymentOptions): Promise<HpsTransactionResponse>;
95
130
  status(options: HpsConnectTransactionOptions): Promise<HpsTransactionResponse>;
131
+ /**
132
+ * Abbruch eines laufenden Vorgangs. `responseCode '0'` heisst nur, dass das
133
+ * Terminal die Anfrage angenommen hat -- NICHT, dass der Vorgang abgebrochen
134
+ * ist: am 10.11.2026 endete eine Zahlung nach so einer Quittung genehmigt.
135
+ * Den Ausgang sagt die Antwort auf die Zahlung oder die Statusabfrage, siehe
136
+ * `payments.ts`.
137
+ */
96
138
  abort(options: HpsConnectTransactionOptions): Promise<HpsTransactionResponse>;
97
139
  /** Gutschrift — ein Kartenfluss wie [payment], deshalb dieselbe lange Frist. */
98
140
  refund(options: HpsConnectRefundOptions): Promise<HpsTransactionResponse>;
@@ -1,6 +1,55 @@
1
1
  import { HpsConnectTerminalError, HpsConnectTransportError, HpsPreflightError, HpsTransactionIdError, PREFLIGHT_CONNECT_CODES, TERMINAL_UNREACHABLE_CONNECT_CODES, } from './errors.js';
2
2
  import { isValidHpsTransactionId } from './transaction-id.js';
3
3
  import { parseHpsTransactionResponse } from './transaction-response.js';
4
+ /** Nur eine rein ziffrige TID wird umgeschrieben. */
5
+ const NUR_ZIFFERN = /^[0-9]+$/;
6
+ const FUEHRENDE_NULLEN = /^0+/;
7
+ /**
8
+ * Leerraum am Rand, der wegfaellt: nur ASCII (Leerzeichen, Tab, Zeilenvorschub,
9
+ * Wagenruecklauf, vertikaler Tab, Seitenvorschub). Bewusst eine feste Liste
10
+ * statt `trim()`: JavaScript und Dart zaehlen Unicode-Leerraum verschieden
11
+ * (U+0085 trimmt Dart, JavaScript nicht), und die Zwillinge sollen dieselbe
12
+ * TID hinausschicken. Jedes andere Zeichen am Rand laesst die TID unveraendert.
13
+ */
14
+ const RAND_LEERRAUM = /^[ \t\n\r\x0B\x0C]+|[ \t\n\r\x0B\x0C]+$/g;
15
+ /**
16
+ * Die TID in der Form, die das hobex-HPS annimmt: Leerraum am Rand
17
+ * ([RAND_LEERRAUM]) und fuehrende Nullen fallen weg.
18
+ *
19
+ * Am 10.11.2026 gemessen (TID 3600335, HPS 1.14.4, Firmware 7.3.6): Diagnose
20
+ * und Zahlung mit `03600335` antworten sofort `100108 "Invalid TID"` (nichts
21
+ * belastet), mit `3600335` normal; `003600335`, `0360033` und `36003350` sind
22
+ * ebenfalls `Invalid TID`. Auf Beleg und Geraet steht die TID achtstellig mit
23
+ * fuehrender Null -- so wird sie auch eingetragen.
24
+ *
25
+ * Umgeschrieben wird NUR eine rein ziffrige TID mit mindestens einer Ziffer
26
+ * ungleich `0`. Alles andere geht UNVERAENDERT hinaus, auch die `0` der
27
+ * Erkennungsprobe von Connect und eine TID aus lauter Nullen: still etwas
28
+ * anderes daraus zu machen, hiesse ein anderes Terminal anzusprechen als das
29
+ * eingetragene. Bewusst kein Wurf: Connect weist eine nicht rein ziffrige TID
30
+ * selbst ab (`bad_request`, vor jedem Terminal-Kontakt, hier
31
+ * [HpsPreflightError]), und das HPS antwortet auf eine unbekannte mit
32
+ * `100108` -- in beiden Faellen geht kein Geld, und der Aufrufer bekommt den
33
+ * Grund auf dem Weg, den er fuer jede andere Abweisung auch auswertet.
34
+ *
35
+ * Kein Text (ein Aufrufer ohne Typpruefung uebergibt etwa eine Zahl) geht
36
+ * ebenso unveraendert hinaus: Connect weist ihn dann mit "Es fehlt die
37
+ * Terminal-ID" ab ([HpsPreflightError]), statt dass hier ein Wurf aus dem
38
+ * Zahlweg einen offenen Ausgang machte.
39
+ *
40
+ * Die einzige Stelle, an der die TID umgeschrieben wird: jeder Aufruf geht
41
+ * ueber `target`. Zwilling: `HpsClient` im Dart-Paket (`_normalizeTid`), Faelle
42
+ * in `fixtures/hobex-hps-cases.json`.
43
+ */
44
+ export function normalizeHpsTid(tid) {
45
+ if (typeof tid !== 'string')
46
+ return tid;
47
+ const ohneRand = tid.replace(RAND_LEERRAUM, '');
48
+ if (!NUR_ZIFFERN.test(ohneRand))
49
+ return tid;
50
+ const ohneNullen = ohneRand.replace(FUEHRENDE_NULLEN, '');
51
+ return ohneNullen === '' ? tid : ohneNullen;
52
+ }
4
53
  const DEFAULT_BASE_URL = 'http://127.0.0.1:27182';
5
54
  const DEFAULT_SHORT_TIMEOUT_MS = 30_000;
6
55
  const DEFAULT_PAYMENT_TIMEOUT_MS = 4 * 60_000 + 30_000;
@@ -83,7 +132,7 @@ export function createHpsConnectClient(options) {
83
132
  return value;
84
133
  }
85
134
  function target(t) {
86
- return { host: t.host, port: t.port, tid: t.tid };
135
+ return { host: t.host, port: t.port, tid: normalizeHpsTid(t.tid) };
87
136
  }
88
137
  return {
89
138
  async payment(o) {
@@ -40,9 +40,10 @@ export interface HpsPaymentResult {
40
40
  * fuer den Bediener in `HPS_REASON_HINTS`.
41
41
  *
42
42
  * Gesetzt an der Stelle, die den Ausgang entschieden hat, nicht aus
43
- * [response] abgeleitet: ein bestaetigter Abbruch antwortet `'0'` und ist
44
- * trotzdem `'aborted'`, und wenn die Zwei-9027-Regel eine Zahlung als
45
- * abgelehnt klaert, zaehlt der Code der ZAHLUNG, nicht das `9027` danach.
43
+ * [response] abgeleitet: ein quittiertes Storno nach einer Stoerung beim
44
+ * Host antwortet `'0'` und ist trotzdem `'voidedAfterHostFault'`, und wenn
45
+ * die Zwei-9027-Regel eine Zahlung als abgelehnt klaert, zaehlt der Code der
46
+ * ZAHLUNG, nicht das `9027` danach.
46
47
  * Fehlt, wenn kein Code etwas erklaert (die Leitung riss ab, bevor das
47
48
  * Terminal etwas sagte) und bei einer Aufhebung, die nicht gegriffen hat.
48
49
  */
@@ -15,49 +15,80 @@ import type { HpsPaymentResult } from './outcome.js';
15
15
  *
16
16
  * Regel, von der nicht abgewichen wird: `outcome: 'declined'` entsteht
17
17
  * ausschliesslich aus einer POSITIVEN Aussage — einem GEMESSENEN Ergebniscode
18
- * des Terminals ungleich `'0'` ([isConclusive]), einem nachweislich
19
- * gelungenen Abbruch, oder dem gemessenen "Terminal beschaeftigt"-Fall
20
- * (HTTP 409 auf die ERZEUGENDE Anfrage, siehe `errors.ts`,
21
- * `HpsConnectTerminalError.isTerminalBusy`). Ein Transportfehler, ein
22
- * Zeitablauf oder eine Wissensluecke fuehren NIE dorthin: keines davon ist
18
+ * des Terminals ungleich `'0'` ([isConclusive]) auf die Zahlung oder in der
19
+ * Statusabfrage, der Zwei-9027-Regel nach einer Antwort MIT Code
20
+ * ([ausGeschlossenerAntwort]), einem `9011` (aufgehoben) in der Statusabfrage
21
+ * nach einem nachgeschickten Storno, oder dem gemessenen "Terminal
22
+ * beschaeftigt"-Fall (HTTP 409 auf die ERZEUGENDE Anfrage, siehe
23
+ * `errors.ts`, `HpsConnectTerminalError.isTerminalBusy`). Ein
24
+ * Transportfehler, ein Zeitablauf, eine Wissensluecke, ein quittierter
25
+ * Abbruch und ein quittiertes Storno fuehren NIE dorthin: keines davon ist
23
26
  * eine Aussage darueber, dass nichts belastet wurde. Genau diese
24
27
  * Verwechslung hat am 24.08.2026 eine echte Belastung als unbelastet
25
28
  * ausgewiesen und den Kunden ein zweites Mal belastet.
26
29
  *
27
- * ## Der Klaerweg, wie er am 26./27.08.2026 am hobex-HPS gemessen wurde
30
+ * ## Der Klaerweg
28
31
  *
29
- * Bleibt die Antwort auf eine Zahlung aus:
32
+ * Bleibt die Antwort auf eine Zahlung aus, oder sagt sie nichts:
30
33
  *
31
- * 1. [HpsConnectClient.abort] einmalig versuchen.
32
- * 2. `responseCode === '0'` -> der Vorgang war noch abbrechbar, also nicht
33
- * abgeschlossen -> `declined`, beweisbar.
34
- * 3. Jeder andere Code (gemessen `100010`) -> der Vorgang ist ueber den
35
- * abbrechbaren Punkt hinaus -> JETZT die Statusabfrage pollen, sie liefert
36
- * nun eine echte Aussage.
37
- * 4. Abbruch scheitert am Transport -> pollen wie in 3.
38
- * 5. Beim Pollen ist `9027` KEIN Ergebnis, sondern ein Grund weiterzumachen.
39
- * Budget erschoepft -> `unresolved`.
34
+ * 1. [HpsConnectClient.abort] einmalig versuchen. Die Absicht: ein
35
+ * Kartenfluss, der noch auf die Karte wartet, soll enden, damit nach der
36
+ * Klaerung keine spaet aufgelegte Karte mehr belastet wird. Eine Garantie
37
+ * ist das nicht -- ob der Abbruch greift, sagt seine Quittung nicht.
38
+ * 2. Die Antwort auf den Abbruch entscheidet NICHTS, auch `'0'` nicht (siehe
39
+ * "Ein quittierter Abbruch ist keine Aussage"). Sie steht nur im Nachweis.
40
+ * 3. Dann die Statusabfrage pollen: `'0'` -> `approved`, mit der Antwort des
41
+ * Status als Beleg; ein schluessiger Code (etwa `9011` aufgehoben) ->
42
+ * `declined`; `9027` ist KEIN Ergebnis, sondern ein Grund weiterzumachen
43
+ * -- ausser nach einer Antwort MIT Code auf die Zahlung, siehe
44
+ * [ausGeschlossenerAntwort].
45
+ * 4. Budget erschoepft -> `unresolved`.
40
46
  *
41
- * Der Abbruch VOR dem Pollen ist wesentlich: die Statusabfrage meldet
42
- * "laeuft noch" nie (sie antwortet auf jeden nicht genehmigten Vorgang mit
43
- * `9027`). Der Abbruchversuch ist auf einen Bruchteil des Klaerbudgets
44
- * gedeckelt ([ABORT_BUDGET_DIVISOR]), sonst friesst ein haengender Abbruch
45
- * die ganze Klaerung.
47
+ * Der Abbruchversuch ist auf einen Bruchteil des Klaerbudgets gedeckelt
48
+ * ([ABORT_BUDGET_DIVISOR]), sonst friesst ein haengender Abbruch die ganze
49
+ * Klaerung.
46
50
  *
47
51
  * Die Kennung ist in JEDEM Ergebnis gesetzt, auch bei `'unresolved'`.
48
52
  *
53
+ * ## Ein quittierter Abbruch ist keine Aussage (10.11.2026)
54
+ *
55
+ * Bis 1.35.0 hiess `'0'` auf den Abbruch "der Vorgang war noch abbrechbar,
56
+ * es ist nichts belastet" -- geschlossen aus einer Messung vom 26.08.2026, bei
57
+ * der der Abbruch WAEHREND des Wartens auf die Karte kam und die Zahlung
58
+ * danach mit `100002` "Aborted" endete. Am 10.11.2026 widerlegt (TID 3600335,
59
+ * HPS 1.14.4, Firmware 7.3.6, Testsystem): Abbruch vier Sekunden nach dem
60
+ * Start einer Zahlung ueber 0,01 EUR, nach 0,18 s quittiert mit `'0'`
61
+ * "Authorized" -- und die laufende Zahlung endete trotzdem GENEHMIGT
62
+ * (kontaktlos), die Statusabfrage danach ebenso. `'0'`
63
+ * heisst also nur, dass das Terminal die Abbruch-Anfrage angenommen hat,
64
+ * nicht, dass die Zahlung abgebrochen ist. Als `declined` gelesen, haette die
65
+ * Kasse "nichts belastet, noch einmal versuchen" gemeldet: der Weg zur
66
+ * Doppelbelastung vom 24.08.2026.
67
+ *
68
+ * Auch ein `9027` kurz nach einem angenommenen Abbruch ist keine Aussage:
69
+ * solange eine Zahlung laeuft, antwortet die Statusabfrage `9027` (gemessen
70
+ * 26.08.2026), und dass sie nach einem angenommenen Abbruch weiterlaufen kann,
71
+ * zeigt die Messung oben. Wie lange danach noch eine Genehmigung kommen kann,
72
+ * ist ungemessen. Ohne Antwort mit Code auf die Zahlung endet ein Abbruch mit
73
+ * anhaltendem `9027` deshalb bei `unresolved`, nicht bei `declined`.
74
+ *
75
+ * Bricht die KASSE eine laufende Zahlung ab (eigener Aufruf von
76
+ * [HpsConnectClient.abort], waehrend [pay] noch auf die Antwort wartet),
77
+ * entscheidet die Antwort auf die Zahlung selbst -- `approved`, wenn sie
78
+ * genehmigt meldet, `declined` mit `100002`. [pay] liest die Quittung dieses
79
+ * fremden Abbruchs nicht.
80
+ *
49
81
  * ## [refund] bekommt EXAKT denselben Klaerweg wie [pay]
50
82
  *
51
- * Abbruch eingeschlossen -- und das ist GEMESSEN, nicht analog geschlossen.
52
- * Am 26.08.2026 nachgemessen: `abort` auf eine LAUFENDE Gutschrift antwortet
53
- * ebenfalls mit `responseCode '0'`, und die Gutschrift endet daraufhin mit
54
- * `100002` "Aborted". Der Abbruch ist dort also derselbe Diskriminator wie bei
55
- * einer Zahlung. Die Kennung ist bei [refund] die des NEUEN Vorgangs (der
56
- * Gutschrift selbst), eine Statusabfrage darauf liefert also genau deren
57
- * Ausgang -- deshalb reicht dieselbe [resolve]-Funktion unveraendert. Ohne den
58
- * Abbruch haette die Klaerung einer Gutschrift gar keinen Diskriminator mehr
59
- * und endete fast immer bei `unresolved`, weil die Statusabfrage auch hier
60
- * `9027` antwortet.
83
+ * Abbruch eingeschlossen. Die Kennung ist bei [refund] die des NEUEN Vorgangs
84
+ * (der Gutschrift selbst), eine Statusabfrage darauf liefert also genau deren
85
+ * Ausgang -- deshalb reicht dieselbe [resolve]-Funktion unveraendert. Am
86
+ * 26.08.2026 gemessen: `abort` auf eine LAUFENDE Gutschrift antwortet
87
+ * ebenfalls mit `responseCode '0'`, und die Gutschrift endete daraufhin mit
88
+ * `100002` "Aborted". Wie bei der Zahlung beweist die Quittung allein nichts:
89
+ * eine Gutschrift, die nach dem angenommenen Abbruch doch durchgeht, als
90
+ * `declined` zu melden, laedt zu einer zweiten Gutschrift ein. Bleibt die
91
+ * Statusabfrage danach bei `9027`, endet die Klaerung bei `unresolved`.
61
92
  *
62
93
  * ## [cancel] ist die Ausnahme, in beiden Richtungen
63
94
  *
@@ -113,10 +144,29 @@ import type { HpsPaymentResult } from './outcome.js';
113
144
  *
114
145
  * Fuer einen Teil dieser Codes -- der Host hat nicht oder nicht brauchbar
115
146
  * geantwortet, etwa `9908` -- gibt hobex vor, ein Storno nachzuschicken
116
- * (`sendReversal`). [pay] tut das genau einmal, mit Kennung und Betrag der
117
- * Zahlung, bevor die Statusabfrage laeuft: quittiert mit `'0'` -> `declined`
118
- * mit `'voidedAfterHostFault'`; sonst weiter wie oben, und ein `9011` in der
119
- * Statusabfrage heisst dann ebenfalls `declined`. Am Geraet ungemessen, siehe
147
+ * (`sendReversal`). [pay] tut das genau einmal, mit der Kennung der Zahlung
148
+ * und dem Betrag, den das Terminal belastet: Betrag UND Trinkgeld (wie die
149
+ * Rueckbuchung der Web-Kasse). Danach laeuft immer die Statusabfrage:
150
+ *
151
+ * - `9011` (aufgehoben) -> `declined`, die einzige Stelle, an der nach einem
152
+ * Storno ein Ausgang feststeht: mit `'voidedAfterHostFault'`, wenn das
153
+ * Storno gewirkt haben kann, sonst mit `'canceled'` -- dann hat etwas
154
+ * anderes die Zahlung aufgehoben.
155
+ * - Ist das Storno nicht sicher abgewiesen ([StornoAusgang]: quittiert mit
156
+ * `'0'`, abgerissen, ohne Code, mit einem unbekannten oder einem
157
+ * Storniert-Code wie `8009`), ist auch `'0'` in der Statusabfrage keine
158
+ * Aussage: das Storno kann noch unterwegs sein, oder es hat nicht
159
+ * gegriffen. Sie zaehlt dann wie `9027` als "nichts Neues", und nach zwei
160
+ * solchen Antworten endet die Klaerung als `unresolved`.
161
+ * - Nur wenn das Storno nach einer ausdruecklichen Positivliste NICHT
162
+ * ausgefuehrt wurde (nicht gesendet, nicht angenommen, abgewiesen -- siehe
163
+ * [stornoAbgewiesen]), ist `'0'` in der Statusabfrage `approved`. Gemessen
164
+ * ist davon nur `9002` auf eine unbekannte Kennung (27.08.2026); die
165
+ * uebrigen Eintraege stuetzen sich auf die Codeliste von hobex und TECS.
166
+ *
167
+ * Die Quittung `'0'` auf das Storno allein beweist nichts -- dieselbe Lehre
168
+ * wie beim Abbruch (10.11.2026). Am Geraet ungemessen sind das Storno nach
169
+ * einer Host-Stoerung und der Stornobetrag mit Trinkgeld, siehe
120
170
  * Dart-Zwilling. [refund] schickt kein Storno nach (TECS: `9031`), [cancel]
121
171
  * ist selbst eines.
122
172
  */