@kreiseck/kasseneck-api 1.34.0 → 1.35.1
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.
- package/CHANGELOG.md +22 -0
- package/README.md +11 -1
- package/dist/cjs/payments/hobex-hps/connect-client.d.ts +43 -1
- package/dist/cjs/payments/hobex-hps/connect-client.js +51 -1
- package/dist/cjs/payments/hobex-hps/outcome.d.ts +4 -3
- package/dist/cjs/payments/hobex-hps/payments.d.ts +85 -35
- package/dist/cjs/payments/hobex-hps/payments.js +137 -53
- package/dist/cjs/pos/drucker-katalog.d.ts +148 -0
- package/dist/cjs/pos/drucker-katalog.js +260 -0
- package/dist/cjs/pos/index.d.ts +1 -0
- package/dist/cjs/pos/index.js +8 -3
- package/dist/cjs/receipt/layout.js +1 -1
- package/dist/cjs/version.d.ts +1 -1
- package/dist/cjs/version.js +1 -1
- package/dist/esm/payments/hobex-hps/connect-client.d.ts +43 -1
- package/dist/esm/payments/hobex-hps/connect-client.js +50 -1
- package/dist/esm/payments/hobex-hps/outcome.d.ts +4 -3
- package/dist/esm/payments/hobex-hps/payments.d.ts +85 -35
- package/dist/esm/payments/hobex-hps/payments.js +138 -54
- package/dist/esm/pos/drucker-katalog.d.ts +148 -0
- package/dist/esm/pos/drucker-katalog.js +252 -0
- package/dist/esm/pos/index.d.ts +1 -0
- package/dist/esm/pos/index.js +3 -0
- package/dist/esm/receipt/layout.js +1 -1
- package/dist/esm/version.d.ts +1 -1
- package/dist/esm/version.js +1 -1
- package/fixtures/hobex-hps-cases.json +654 -0
- package/fixtures/hobex-hps-codes.json +1 -1
- package/fixtures/invoice-api.schema.json +1 -1
- package/fixtures/invoice-texts.json +1 -1
- package/fixtures/manifest.json +1 -1
- package/fixtures/pos-texts.json +1 -1
- package/fixtures/printer-catalog.json +1802 -0
- package/fixtures/receipts/card-hobex-hps.json +1 -1
- package/fixtures/surface.json +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,28 @@ Was vor 0.7.0 geschah, steht in der Commit-Historie (`git log`); ab hier wird
|
|
|
4
4
|
es hier geführt. Ein Eintrag nennt die Änderung **und ihren Grund** —
|
|
5
5
|
nur der Grund überlebt den nächsten Umbau.
|
|
6
6
|
|
|
7
|
+
## 1.35.1 - unveröffentlicht
|
|
8
|
+
|
|
9
|
+
Fixes in the hobex HPS card payment through Kasseneck Connect (`./payments`). The first two were measured at the test terminal 3600335 (HPS 1.14.4, firmware 7.3.6, `tecstest.hobex.at`) on 10.11.2026; the reversal fix follows from the same lesson.
|
|
10
|
+
|
|
11
|
+
- **An accepted abort no longer means "nothing charged".** Until now the clarification of a payment or refund without an answer (transport error, timeout, an answer without a decision) read `responseCode '0'` on `POST /api/transaction/abort` as proof that the transaction was still abortable and returned `declined` with reason `aborted`, without asking the status. Measured: an abort sent four seconds into a contactless payment of 0.01 EUR was answered with `'0'` "Authorized" after 0.18 s, and the running payment still ended **approved**; the status query afterwards said approved as well. Read as `declined`, the till would have said "nothing charged, try again" for a charged card. Now the answer to the abort decides nothing and only goes into `steps` (the entry starts with "Abbruch angenommen (0)" and says that this does not tell whether the card was charged); the status query always follows: `'0'` -> `approved` with the status answer as `response`, a conclusive code (e.g. `9011` canceled) -> `declined`, `9027` -> keep asking, and only after an answer with a code to the payment the two-`9027` rule makes it `declined`. A payment without any answer, an accepted abort and a status that stays `9027` now ends as `unresolved` instead of `declined`: while a payment runs the status also answers `9027`, and how long an approval can still arrive after an accepted abort is not measured. When the till aborts a running payment itself (its own `abort` call while `pay()` still waits), the answer to the payment decides, as before; `pay()` never reads that abort's answer. Reason `aborted` now only comes from a terminal code (`100002`).
|
|
12
|
+
- **A confirmed reversal after a host fault no longer means "nothing charged" either, and it now reverses the tip too.** After a host code that asks for a reversal (`sendReversal`, e.g. `9908`), `pay()` used to return `declined` with reason `voidedAfterHostFault` as soon as the void answered `'0'`, without asking the status. Like the abort, that answer alone proves nothing. Now the status query always follows: `9011` (canceled) -> `declined`, with reason `voidedAfterHostFault` if the void may have worked, `canceled` if it provably did not (then something else canceled the payment, and `steps` says so instead of "the reversal took effect"). Unless the void was provably not executed, a `'0'` in the status is no statement either (the void may still be on its way or may not have taken effect); it counts as "nothing new" like `9027`, and two of those end as `unresolved`. "Provably not executed" is an explicit positive list: not sent (`HpsPreflightError`, Connect refused it before the terminal; the trail now says so instead of "whether it worked is open"), not accepted (HTTP 409), or refused with a conclusive code that rejects the request itself (`rejectsRequest`, e.g. `9002`, the only one measured on a void, 27.08.2026), denies the cancellation (`cancelDenied`: `9023`, `9222`) or refuses the amount (`amountInvalid`). Everything else may have worked, explicitly codes that themselves mean "reversed" or "canceled" (`8009`, `100029`, `3053`-`3063`, `9032`, `9011`), abort codes (`100002`, `17`, `8004`), host declines and unknown codes. The reversal amount is now what the terminal charged, `amountCents + tipCents` (as the till's own refund does), not `amountCents` alone. Not measured at the device: the reversal after a host fault and a reversal amount with tip.
|
|
13
|
+
- **TID without leading zero.** The TID printed on the receipt and shown on the device has eight digits with a leading zero (`03600335`); the HPS only accepts it without (`3600335`) and answers diagnosis and payment with `100108 "Invalid TID"` otherwise (`003600335`, `0360033` and `36003350` as well). The Connect client now writes the TID once, for every call (payment, status, abort, refund, cancel, diagnosis), without surrounding white space and leading zeros (`normalizeHpsTid` in `connect-client.ts`, not exported from `./payments`). Only a TID of digits with at least one digit other than `0` is rewritten; anything else, the probe TID `0` and a TID of zeros only go out unchanged (Connect refuses a TID that is not digits only with `bad_request`, the HPS an unknown one with `100108`; in both cases nothing is charged). White space means ASCII only (space, tab, LF, CR, VT, FF), the same fixed list as in Dart, because JavaScript and Dart trim Unicode white space differently (U+0085). A TID that is not a string (a caller without type checks passing a number) also goes out unchanged, so Connect refuses it before the terminal (`HpsPreflightError`) instead of a throw inside the payment turning into an open outcome. The caller's target object is not changed. The doc comment that claimed leading zeros were tolerated is corrected.
|
|
14
|
+
- **Contract:** new file `fixtures/hobex-hps-cases.json` with the TID cases, receipt cases (`hobexReceiptFromHps` + `hobexReceiptToCardPaymentData` on the full measured payment answer and on a status answer in the v2 form from the shortened 10.11. notes: `aid`, `cvm` as number, `currency: null`; whether `transactionId` is missing there is assumed, not measured, so it is checked with and without) and the clarification cases built from the measured answers, among them the reversal cases (and `reversalAnswers`: every listed answer to the void, once with an approval and once with `9011` in the status), a later approval after two `9027`, a till abort answered with `100002` and an abort answered with HTTP 404; the Dart twin computes the same cases. Card data in the contract and in the tests is a test card (`541333******0021`, expiry `2912`); the real card data of the test terminal (number, expiry, cryptogram, VU) is removed from `fixtures/` and `test/`, in `fixtures/receipts/card-hobex-hps.json` the expiry only (the printed bon and all goldens are unchanged, only its input hash in `manifest.json` moves); real approval and receipt numbers of the test terminal in the tests and doc comments are replaced by invented ones or dropped.
|
|
15
|
+
- `fixtures/surface.json`, `pos-texts.json`, `invoice-texts.json`, `hobex-hps-codes.json` and `invoice-api.schema.json` regenerated for the version.
|
|
16
|
+
|
|
17
|
+
## 1.35.0 - unveröffentlicht
|
|
18
|
+
|
|
19
|
+
Printer catalog for setting up a receipt printer through Kasseneck Connect with one click. Additive; every existing call, receipt and golden behaves as before.
|
|
20
|
+
|
|
21
|
+
- **`printerCatalogEntry(model: string | null | undefined)`** (`./pos`) returns the approved catalog entry for a model name as Connect reports it (mDNS, `GS I`), or `null` for an unknown model; `undefined` is allowed because Connect leaves `model` out of a find it cannot name. **`printerCatalogSettings(entry)`** returns what the entry proposes for the first setup: `device` (`paperSize`, `codePage`, `cut`, `qrMode`, `drawerEnabled`), sendable as it is with `setMyRegisterDeviceSettings`, and `paperSizeNeedsCheck`. Reason: the boss should set up a known printer without knowing paper width, code page or QR mode; an unknown model only asks for the paper width.
|
|
22
|
+
- **Paper width:** an entry lists the paper size settings that fit the model (`paperSizes`; another roll needs the paper guide and a printer setting) and its factory setting (`values.paperSize`), plus `nativeCharsPerLine`, the font A columns the printer has at its factory setting (data sheet). No size in `paperSizes` may lay out more characters than that. When there is more than one, `paperSizeNeedsCheck` is `true`: the proposed width is only the factory setting, and the till confirms it with a test print at the first setup. `drawerEnabled` (from `drawerKick`) is only a proposal for the first setup as well; the till never overrides a choice the boss made.
|
|
23
|
+
- **Only approved entries count.** An entry that is not approved behaves like an unknown model. Approval needs a complete device test: date, Connect version, printer firmware, who tested, every value field checked (`checked`, the code page with € and umlauts) and a print at every paper width (`checkedPaperSizes`).
|
|
24
|
+
- **Starting stock**, not approved yet, so `printerCatalogEntry` answers `null` for every model until a device test approves an entry in a later version: Epson TM-m30III, TM-m30II and TM-T20III (80 mm and 48 characters by default, 58 mm with the paper guide according to the Epson data sheet), TM-m10 (58 mm only, 32 characters) and TM-T88VI, TM-T88VII; all with drawer port, QR from the printer, CP1252. The TM-T88 models print at 180 dpi (512 dots on 80 mm, font A 42 columns), so 48 characters do not fit: they get the till's 32-character layout (`paperSize: 'mm58'`, the 384 dots of `GS W` fit into their 512) even with 80 mm paper, never propose `mm80` and need no width confirmation, until there is a 42-character setting.
|
|
25
|
+
- **Model names are normalized** before matching: `a-z` to upper case (ASCII only), any other character outside ASCII that is neither punctuation nor white space (`Ï`, `ı`, `é`, `®`, `ff`) makes the name unknown, every run of other characters than `A-Z`/`0-9` becomes one `-`, none at the edges, and one leading manufacturer of the catalog (`EPSON-`, the longest first) is dropped. `TM-m30III`, `EPSON TM-m30III`, `tm m30iii` and `(EPSON TM-m30III)` find the same entry. Separators stay as one `-` instead of disappearing, because `TM-T20II-i` is a model of its own and would otherwise match `TM-T20III`; written without the hyphen (`TM-T20IIi`) it cannot be told apart. Matching is exact: `TM-m30III-H`, `TM-T88V` or `TM-m30` are unknown.
|
|
26
|
+
- **Values only from the device settings:** `cut` is `partial` or `none` (what the till offers), `qrMode` `escpos` or `raster` (`auto` means "not decided" and says nothing about a model), and `charsPerLine` must match the factory paper size (`CHARS_PER_PAPER_SIZE`: 32 for `mm58`, 48 for `mm80`).
|
|
27
|
+
- **Contract:** new file `fixtures/printer-catalog.json` with the entries, the value sets and the test cases (normalization, lookup with the shipped catalog, with every entry approved, with some approved and with a catalog of its own with overlapping manufacturers, proposals, catalog problems such as a match name in two entries, a paper size wider than the printer or an incomplete device test). The Dart twin computes the same cases. The catalog itself is checked only by the tests; at run time nothing is repaired or dropped silently.
|
|
28
|
+
|
|
7
29
|
## 1.34.0 - unveröffentlicht
|
|
8
30
|
|
|
9
31
|
Read the deposit types of a business with the API key: new `listDepositTypes()` on the API client (`/v3` only, right `read`, no effect). Additive; every existing call, receipt and golden behaves as before.
|
package/README.md
CHANGED
|
@@ -208,7 +208,7 @@ adapter:
|
|
|
208
208
|
| `…/printing` | ESC/POS generation (byte sequences for thermal printers), QR sizing, printing over WebUSB. |
|
|
209
209
|
| `…/payments` | Stripe payment links, Hobex cloud (both HTTP endpoints of the backend), and Hobex **HPS** via **Kasseneck Connect** (local device agent that talks to the terminal). |
|
|
210
210
|
| `…/register` | Sign-in for the browser register: pair and unpair a device, list its users and sessions, sign in by PIN, renew and end the session. |
|
|
211
|
-
| `…/pos` | Tile register: register settings (business-wide and per device), article groups and articles for tiles, discount distribution per VAT rate, scopes of register permissions, network printers and print jobs, tip recipients, the register's message catalogue. |
|
|
211
|
+
| `…/pos` | Tile register: register settings (business-wide and per device), article groups and articles for tiles, discount distribution per VAT rate, scopes of register permissions, network printers and print jobs, the printer catalog for setting up a printer through Kasseneck Connect, tip recipients, the register's message catalogue. |
|
|
212
212
|
| `…/partner` | Partner API (`/v3`, English): create businesses, FinanzOnline link, signature, cash registers, credentials, webhooks with signature verification. **Belongs on a server.** |
|
|
213
213
|
| `…/stored` | Stored Firestore documents (inner form, German) as the same English models the `/v3` wire returns: receipts with company and layout, register settings, articles. For clients that read Firestore directly, such as the admin panel. |
|
|
214
214
|
| `…/invoice` | Invoice API: create and search customers, issue finalised invoices, credit notes and cancellation, PDF and e-invoice XML, the contract as data. **Belongs on a server.** |
|
|
@@ -1048,6 +1048,16 @@ the register's text catalogue (`MESSAGES`, `LABELS`, `messageText`,
|
|
|
1048
1048
|
`messageText('checkout.locked', { reason })`. The rendered German texts are
|
|
1049
1049
|
the same as in 0.x.
|
|
1050
1050
|
|
|
1051
|
+
**Printer catalog.** `printerCatalogEntry(model)` finds the approved catalog
|
|
1052
|
+
entry for a model name as Kasseneck Connect reports it (case, a leading
|
|
1053
|
+
`EPSON` and the kind of separator do not count; `null` for an unknown model),
|
|
1054
|
+
and `printerCatalogSettings(entry)` returns what it proposes for the first
|
|
1055
|
+
setup: `device` (`paperSize`, `codePage`, `cut`, `qrMode`, `drawerEnabled`)
|
|
1056
|
+
and `paperSizeNeedsCheck`, `true` when the model can be switched to another
|
|
1057
|
+
paper width and the till should confirm it with a test print. Only entries
|
|
1058
|
+
approved after a complete device test count; the entries and their test cases
|
|
1059
|
+
are in `fixtures/printer-catalog.json`.
|
|
1060
|
+
|
|
1051
1061
|
**Stock at the register.** Three calls on the register path (`/api/v3` only),
|
|
1052
1062
|
permissions checked by the server (`stockView`, `stockCosts`, `stockLocation`
|
|
1053
1063
|
in `REGISTER_PERMS`):
|
|
@@ -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
|
-
/**
|
|
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,9 +1,59 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.normalizeHpsTid = normalizeHpsTid;
|
|
3
4
|
exports.createHpsConnectClient = createHpsConnectClient;
|
|
4
5
|
const errors_js_1 = require("./errors.js");
|
|
5
6
|
const transaction_id_js_1 = require("./transaction-id.js");
|
|
6
7
|
const transaction_response_js_1 = require("./transaction-response.js");
|
|
8
|
+
/** Nur eine rein ziffrige TID wird umgeschrieben. */
|
|
9
|
+
const NUR_ZIFFERN = /^[0-9]+$/;
|
|
10
|
+
const FUEHRENDE_NULLEN = /^0+/;
|
|
11
|
+
/**
|
|
12
|
+
* Leerraum am Rand, der wegfaellt: nur ASCII (Leerzeichen, Tab, Zeilenvorschub,
|
|
13
|
+
* Wagenruecklauf, vertikaler Tab, Seitenvorschub). Bewusst eine feste Liste
|
|
14
|
+
* statt `trim()`: JavaScript und Dart zaehlen Unicode-Leerraum verschieden
|
|
15
|
+
* (U+0085 trimmt Dart, JavaScript nicht), und die Zwillinge sollen dieselbe
|
|
16
|
+
* TID hinausschicken. Jedes andere Zeichen am Rand laesst die TID unveraendert.
|
|
17
|
+
*/
|
|
18
|
+
const RAND_LEERRAUM = /^[ \t\n\r\x0B\x0C]+|[ \t\n\r\x0B\x0C]+$/g;
|
|
19
|
+
/**
|
|
20
|
+
* Die TID in der Form, die das hobex-HPS annimmt: Leerraum am Rand
|
|
21
|
+
* ([RAND_LEERRAUM]) und fuehrende Nullen fallen weg.
|
|
22
|
+
*
|
|
23
|
+
* Am 10.11.2026 gemessen (TID 3600335, HPS 1.14.4, Firmware 7.3.6): Diagnose
|
|
24
|
+
* und Zahlung mit `03600335` antworten sofort `100108 "Invalid TID"` (nichts
|
|
25
|
+
* belastet), mit `3600335` normal; `003600335`, `0360033` und `36003350` sind
|
|
26
|
+
* ebenfalls `Invalid TID`. Auf Beleg und Geraet steht die TID achtstellig mit
|
|
27
|
+
* fuehrender Null -- so wird sie auch eingetragen.
|
|
28
|
+
*
|
|
29
|
+
* Umgeschrieben wird NUR eine rein ziffrige TID mit mindestens einer Ziffer
|
|
30
|
+
* ungleich `0`. Alles andere geht UNVERAENDERT hinaus, auch die `0` der
|
|
31
|
+
* Erkennungsprobe von Connect und eine TID aus lauter Nullen: still etwas
|
|
32
|
+
* anderes daraus zu machen, hiesse ein anderes Terminal anzusprechen als das
|
|
33
|
+
* eingetragene. Bewusst kein Wurf: Connect weist eine nicht rein ziffrige TID
|
|
34
|
+
* selbst ab (`bad_request`, vor jedem Terminal-Kontakt, hier
|
|
35
|
+
* [HpsPreflightError]), und das HPS antwortet auf eine unbekannte mit
|
|
36
|
+
* `100108` -- in beiden Faellen geht kein Geld, und der Aufrufer bekommt den
|
|
37
|
+
* Grund auf dem Weg, den er fuer jede andere Abweisung auch auswertet.
|
|
38
|
+
*
|
|
39
|
+
* Kein Text (ein Aufrufer ohne Typpruefung uebergibt etwa eine Zahl) geht
|
|
40
|
+
* ebenso unveraendert hinaus: Connect weist ihn dann mit "Es fehlt die
|
|
41
|
+
* Terminal-ID" ab ([HpsPreflightError]), statt dass hier ein Wurf aus dem
|
|
42
|
+
* Zahlweg einen offenen Ausgang machte.
|
|
43
|
+
*
|
|
44
|
+
* Die einzige Stelle, an der die TID umgeschrieben wird: jeder Aufruf geht
|
|
45
|
+
* ueber `target`. Zwilling: `HpsClient` im Dart-Paket (`_normalizeTid`), Faelle
|
|
46
|
+
* in `fixtures/hobex-hps-cases.json`.
|
|
47
|
+
*/
|
|
48
|
+
function normalizeHpsTid(tid) {
|
|
49
|
+
if (typeof tid !== 'string')
|
|
50
|
+
return tid;
|
|
51
|
+
const ohneRand = tid.replace(RAND_LEERRAUM, '');
|
|
52
|
+
if (!NUR_ZIFFERN.test(ohneRand))
|
|
53
|
+
return tid;
|
|
54
|
+
const ohneNullen = ohneRand.replace(FUEHRENDE_NULLEN, '');
|
|
55
|
+
return ohneNullen === '' ? tid : ohneNullen;
|
|
56
|
+
}
|
|
7
57
|
const DEFAULT_BASE_URL = 'http://127.0.0.1:27182';
|
|
8
58
|
const DEFAULT_SHORT_TIMEOUT_MS = 30_000;
|
|
9
59
|
const DEFAULT_PAYMENT_TIMEOUT_MS = 4 * 60_000 + 30_000;
|
|
@@ -86,7 +136,7 @@ function createHpsConnectClient(options) {
|
|
|
86
136
|
return value;
|
|
87
137
|
}
|
|
88
138
|
function target(t) {
|
|
89
|
-
return { host: t.host, port: t.port, tid: t.tid };
|
|
139
|
+
return { host: t.host, port: t.port, tid: normalizeHpsTid(t.tid) };
|
|
90
140
|
}
|
|
91
141
|
return {
|
|
92
142
|
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
|
|
44
|
-
*
|
|
45
|
-
* abgelehnt klaert, zaehlt der Code der
|
|
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])
|
|
19
|
-
*
|
|
20
|
-
* (
|
|
21
|
-
*
|
|
22
|
-
*
|
|
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
|
|
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
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
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
|
|
42
|
-
*
|
|
43
|
-
*
|
|
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
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
-
*
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
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
|
|
117
|
-
*
|
|
118
|
-
*
|
|
119
|
-
*
|
|
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
|
*/
|