@kreiseck/kasseneck-api 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,98 @@ 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.
 
+## 0.12.0
+
+### Storno mit Kartendaten der Erstattung
+
+**Anlass:** sastre zieht vom alten Storno-Weg (`createCancelReceipt`, ohne
+Bezug) auf `cancelReceipt` um. Bei einer Kartenerstattung haengt sastre heute
+die Terminaldaten der Gutschrift/Aufhebung an den Stornobeleg -- ueber den
+neuen Endpunkt ging das bisher nicht, der Kartenblock fiele vom Storno-Bon.
+Backend: keck#371.
+
+- **`cancelReceipt` nimmt `creditCardProvider`, `cardPaymentId` und
+  `cardPaymentData` an** -- die Daten der ERSTATTUNG, nie der Originalzahlung.
+  Nur bei Rueckzahlweg Karte: ein ausdruecklich anderer `paymentMethod` wird
+  schon hier abgewiesen, ohne Angabe entscheidet das Backend an der
+  Zahlungsart des Originals. Ein unbekannter Kartenanbieter geht gar nicht erst
+  raus.
+- Ohne Kartendaten aendert sich nichts.
+- `package-lock.json` traegt wieder die Paketversion (stand seit 0.11.0 auf
+  0.10.0).
+
+## 0.11.0
+
+### Die QR-Modulgröße wird gerechnet, nicht gesetzt — samt Notausgang und Modell 1
+
+**Anlass:** Am echten Beleg fehlte der QR-Code, die Probe im Drucker-Wizard
+druckte ihn. Der native QR-Befehl bekommt eine Modulgröße in Druckpunkten mit
+und rechnet nicht nach, ob das Symbol samt Ruhezone auf die Rolle geht. Ein
+Beleg-QR mit realer RKSV-Nutzlast hat 57 Module, mit Ruhezone also 65; bei
+sechs Punkten je Modul sind das 390 Druckpunkte, und ein 58-mm-Kopf hat 384.
+Zu breit heißt bei den meisten Geräten nicht „abgeschnitten", sondern **gar
+kein QR**. Der Befund stammt aus dem Flutter-Zwilling `kasseneck_api` (dort
+6.9.0), der fest mit sechs Punkten druckte; dieses Paket druckt seit jeher mit
+vier und war davon nicht betroffen. Die Regel ist trotzdem dieselbe — sie
+deckelt auch eine bewusst gewählte größere Modulgröße gegen den Papierrand ab.
+
+- **Neu `…/printing`: die Rechenregel, rein und ohne Drucker.**
+  `qrModulAnzahl(nutzlast)` gibt die Modulanzahl bei Fehlerkorrektur **M**
+  (konservativ: der native Befehl druckt mit L, das braucht nie mehr Module);
+  `qrGroesseBerechnen({ papierbreitePunkte, moduleAnzahl, groesse })` und
+  `qrGroesseFuer({ nutzlast, papierbreitePunkte, groesse })` geben ein
+  `QrGroesse` mit `punkte` (`null` = passt nicht), `module`, `breitePunkte`,
+  `unterMindestmass` und `passt`. Dazu `QrModulGroesse`, `QR_MODUL_DECKEL`,
+  `QR_RUHEZONE_MODULE` (4), `QR_MINDEST_PUNKTE` (4), `QR_AUSNAHME_PUNKTE` (3),
+  `QR_HOECHST_PUNKTE` (8) und `QR_DRUCK_PUNKTE` (58 mm = 384, 80 mm = 576 —
+  die echte Kopfbreite, nicht die Spaltenbreite 372/558).
+- **`escPosQrCode` rechnet, wenn keine feste `size` mitkommt.** `groesse` ist
+  ein **Deckel**, keine Vorgabe: gedruckt wird die größte Größe, die noch
+  passt, höchstens aber der Deckel. `auto` deckelt beim Bestandswert dieses
+  Pakets (4), `klein` 4, `mittel` 6, `gross` 8. **Ohne ausdrückliche Wahl
+  ändert sich kein Byte** — nur dort, wo heute gar nichts herauskommt, rechnet
+  die Regel herunter. (Im Flutter-Zwilling deckelt `auto` bei 6, weil dort 6
+  der Bestandswert ist; die Regel ist dieselbe, der Bestand nicht.)
+- **`EscPosDocument.qrFehler` / `.qrAusweich`.** `qrFehler` heißt „Beleg ohne
+  QR" — das Symbol passt auch mit der Ausnahmegröße nicht, und ein Befehl, von
+  dem man weiß, dass er nichts druckt, täuscht nur einen Ausdruck vor.
+  `qrAusweich` heißt „gedruckt, aber nicht auf dem eingestellten Weg" — unter
+  der Mindestgröße oder als Bild. Das eine gehört dem Kunden gesagt, das
+  andere dem Chef. `escPosReset` räumt beide weg.
+- **Neu `…/receipt`: `escPosLayoutErgebnis`** gibt `{ bytes, qrFehler,
+  qrAusweich }`; `escPosLayoutBytes` bleibt unverändert und gibt weiter nur
+  die Bytes. Neue Optionen `qrGroesse`, `qrModus` (`QrPrintMode`) und
+  `qrMatrix`.
+- **Der Notausgang.** Passt das Symbol nativ nicht aufs Papier und ist ein
+  `qrMatrix` mitgegeben, geht der QR als Rasterbild hinaus (`GS v 0`) statt
+  gar nicht — ein Pflichtbeleg ohne QR ist der schlechteste aller Ausgänge.
+  Das Raster kommt vom Aufrufer: dieses Paket rechnet keine QR-Codes und
+  verarbeitet keine Bilder. Dafür neu `escPosQrRaster`, `qrRasterPunkte` und
+  der Typ `QrMatrix`.
+- **Modell 1.** `qrCodeBytes(..., { modell1: true })` bzw. `qrModus:
+  'nativeModel1'` stellt den Wahlbefehl `GS ( k 04 00 31 41 31 00` voran. Für
+  günstige Drucker, die nur diesen älteren Symboltyp beherrschen; belegt ist
+  eines, das bei Modell 2 unter dem Code eine „0" ausgibt — das Parameterbyte
+  `0x30` des Druckbefehls, das es nicht als Befehl erkennt. Ohne ausdrückliche
+  Wahl geht **gar kein** Modellbefehl hinaus, wie bisher.
+- **Derselbe Fehler im ePOS-Weg — und dort ist er der akute.** `eposPrintXml`
+  setzte `<symbol … width="6">` fest, unabhängig von der Papierbreite: 57
+  Module plus Ruhezone sind bei sechs Punkten 390 Druckpunkte, ein 58-mm-Kopf
+  hat 384, und der Epson lässt ein zu breites Symbol weg. **Genau daran fehlte
+  am echten Beleg der QR.** Jetzt gilt dieselbe Regel — Untergrenze 4,
+  Ausnahme 3 mit Meldung, darunter kein `<symbol>`. Der Bestandswert dieses
+  Wegs ist 6, deshalb ist die Vorgabe hier der Deckel `mittel`; ohne
+  ausdrückliche Wahl ändert sich nur dort etwas, wo heute gar nichts
+  herauskommt. Neu `eposPrintXmlErgebnis` (`{ xml, qrFehler, qrAusweich }`) und
+  die Optionen `qrGroesse` an `eposPrintXml` und `eposDirectPrint`; `qrBreite`
+  bleibt, ist jetzt aber ausdrücklich die **feste** Größe und schaltet die
+  Rechnung ab.
+- **Bestandsschutz als Golden-Test.** Zwei feste SHA-256 über den gesamten
+  Bytestrom eines Belegs (58 und 80 mm) und zwei weitere über das vollständige
+  ePOS-XML halten fest, dass sich ohne Wahl kein Byte ändert. Dazu prüft `test/paket-inhalt.test.ts`, dass die Dateiliste des
+  Pakets eine Positivliste bleibt und im mitgelieferten `fixtures/` nichts
+  Örtliches liegt.
+
 ## 0.10.0
 
 ### Die Antwortcodeliste von hobex — jeder Code eingeordnet, jeder Ausgang mit Grund
@@ -12,7 +104,8 @@ nur der Grund überlebt den nächsten Umbau.
 geschickt. Drei der Codes kamen seit dem 28.08.2026 im Betrieb vor (`100004`,
 `100005`, `100015`) und waren bis jetzt ungedeutet. Jede Zahlung damit lief in
 die Klaerung und endete erst ueber die Zwei-9027-Regel. Zwilling:
-`kasseneck_api` 6.9.0, Begruendungen dort in `doc/kartenzahlung.md`.
+`kasseneck_api` 6.10.0 (6.9.0 war inzwischen vergeben), Begruendungen dort in
+`doc/kartenzahlung.md`.
 
 - **`HPS_CODES`** fuehrt alle 31 Codes der Liste zusammen mit den gemessenen:
   Code, hobex-Titel, Bedeutung, Wirkung (`effect`), Grund (`reason`) und

package/README.md

@@ -344,6 +344,47 @@ app.post('/kasseneck-webhook', express.raw({ type: '*/*' }), async (req, res) =>
 
 So zieht sich niemand den React-Adapter in ein Node-Programm.
 
+## Der QR-Code passt aufs Papier
+
+Der native QR-Befehl bekommt eine Modulgröße in Druckpunkten mit und rechnet
+selbst nicht nach, ob das Symbol samt Ruhezone auf die Rolle geht. Zu breit
+heißt bei den meisten Bondruckern nicht „abgeschnitten", sondern **gar kein
+QR** — auf einem Pflichtbeleg der schlechteste aller Ausgänge. Deshalb rechnet
+dieses Paket die Größe, statt sie zu setzen:
+
+```ts
+import { qrGroesseFuer, QR_DRUCK_PUNKTE } from '@kreiseck/kasseneck-api/printing';
+
+const mass = qrGroesseFuer({ nutzlast: beleg.qr, papierbreitePunkte: QR_DRUCK_PUNKTE.mm58 });
+// mass.punkte: Punkte je Modul, null = passt auch mit der Ausnahmegröße nicht
+// mass.unterMindestmass: gedruckt, aber unter 4 Punkten je Modul
+```
+
+Am Belegweg passiert das von selbst. `qrGroesse` ist ein **Deckel**, keine
+Vorgabe: gedruckt wird die größte Größe, die noch passt, höchstens aber der
+Deckel. `auto` (Vorgabe) deckelt beim Bestandswert 4 — ohne ausdrückliche Wahl
+ändert sich also kein Byte.
+
+```ts
+import { escPosLayoutErgebnis } from '@kreiseck/kasseneck-api/receipt';
+
+const { bytes, qrFehler, qrAusweich } = escPosLayoutErgebnis(layout, {
+  qrGroesse: 'gross',        // 'auto' | 'klein' | 'mittel' | 'gross'
+  qrModus: 'nativeModel1',   // ältere Drucker, die nur Modell 1 können
+  qrMatrix: rasterFuer,      // Notausgang: der QR als Bild statt gar nicht
+});
+```
+
+Der Epson-Weg (`eposPrintXml` / `eposDirectPrint`) rechnet genauso;
+`eposPrintXmlErgebnis` gibt dort `{ xml, qrFehler, qrAusweich }`. Sein
+Bestandswert ist 6, deshalb ist die Vorgabe dort der Deckel `mittel`.
+
+`qrFehler` heißt „Beleg ohne QR" — das gehört dem Kunden gesagt. `qrAusweich`
+heißt „gedruckt, aber der eingestellte Weg taugt für dieses Gerät nicht" — das
+gehört dem Chef gesagt. Den Bildweg fährt das Paket nur mit einem `qrMatrix`,
+das die Nutzlast in ein fertiges Raster übersetzt: hier wird bewusst weder ein
+QR gerechnet noch ein Bild verarbeitet.
+
 ## Hobex HPS über Kasseneck Connect
 
 Ein Browser hat weiterhin keine rohen TCP-Sockets — ein **direkter**

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

@@ -117,6 +117,14 @@ export type CancelReceiptOptions = {
     note?: string;
     /** Rueckzahlweg; ohne Angabe die Zahlungsart des stornierten Belegs. */
     paymentMethod?: KeckPaymentMethod | KeckPaymentMethodKey;
+    /**
+     * Kartendaten der ERSTATTUNG (Gutschrift oder Aufhebung am Terminal) fuer
+     * den Kartenblock am Storno-Bon -- nur bei Rueckzahlweg Karte. Beschreiben
+     * nie die Originalzahlung; das Backend uebernimmt sie nicht vom Original.
+     */
+    creditCardProvider?: CreditCardProvider;
+    cardPaymentId?: string;
+    cardPaymentData?: Record<string, unknown>;
 } & ({
     receipt: Receipt;
     cashregisterId?: string;

package/dist/cjs/client/receipts.js

@@ -154,6 +154,24 @@ async function cancelReceipt(rufen, options) {
         params.note = options.note;
     if (options.paymentMethod != null)
         params.paymentMethod = gepruefteZahlungsart(options.paymentMethod);
+    const karte = options.creditCardProvider != null || options.cardPaymentId != null || options.cardPaymentData != null;
+    if (karte) {
+        // Ohne paymentMethod entscheidet das Backend an der Zahlungsart des
+        // Originals; ein ausdruecklich anderer Rueckzahlweg ist hier schon falsch.
+        if (params.paymentMethod != null && params.paymentMethod !== index_js_1.KeckPaymentMethod.creditCard.value) {
+            throw new errors_js_1.KasseneckValidationError('cancelReceipt', 'Kartendaten gibt es nur bei paymentMethod creditCard', 'request');
+        }
+        if (options.creditCardProvider != null) {
+            if (!Object.prototype.hasOwnProperty.call(index_js_1.CreditCardProvider, options.creditCardProvider)) {
+                throw new errors_js_1.KasseneckValidationError('cancelReceipt', `Kartenanbieter: unbekannter Schluessel "${options.creditCardProvider}"`, 'request');
+            }
+            params.creditCardProvider = options.creditCardProvider;
+        }
+        if (options.cardPaymentId != null && options.cardPaymentId !== '')
+            params.cardPaymentId = options.cardPaymentId;
+        if (options.cardPaymentData != null)
+            params.cardPaymentData = options.cardPaymentData;
+    }
     const daten = await rufen('cancelReceipt', params);
     const receipt = belegAusHuelle(daten, 'cancelReceipt');
     const huelle = daten;

package/dist/cjs/printing/escpos.d.ts

@@ -27,6 +27,7 @@
  * Nicht enthalten (bewusst): Rasterbilder/Logos, Capability-Profile einzelner
  * Druckermodelle, Kassenlade, 1D-Barcodes.
  */
+import { type QrModulGroesse } from './qr-groesse.js';
 /** Papierbreite der Bonrolle. */
 export type PosPaperSize = 'mm58' | 'mm80';
 /** Ausrichtung einer Textzeile bzw. innerhalb einer Spalte. */
@@ -43,6 +44,14 @@ export type PosTextSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
 export type QrSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
 /** Fehlerkorrekturstufe des QR-Codes. */
 export type QrCorrection = 'L' | 'M' | 'Q' | 'H';
+/**
+ * Fertig gerechnetes QR-Raster, quadratisch, `true` = schwarzes Modul —
+ * **ohne** Ruhezone, die setzt der Drucker-Weg selbst.
+ *
+ * Dieses Paket rastert bewusst nicht selbst (keine Bildverarbeitung, siehe
+ * Kopf dieser Datei); wer den Bildweg braucht, bringt sein eigenes Raster mit.
+ */
+export type QrMatrix = readonly (readonly boolean[])[];
 /** Textstil. Fehlende Felder gelten als Vorgabewert (nicht als "unveraendert"). */
 export interface PosStyles {
     bold?: boolean;
@@ -88,8 +97,26 @@ export interface EscPosHrOptions {
 }
 export interface EscPosQrOptions {
     align?: PosAlign;
+    /**
+     * Feste Modulgroesse in Druckpunkten. Gesetzt schaltet sie die Rechnung ab —
+     * fuer Aufrufer, die genau wissen, was ihr Geraet kann. Ohne sie entscheidet
+     * die Regel in `qr-groesse.ts`.
+     */
     size?: QrSize;
     correction?: QrCorrection;
+    /** Deckel fuer die gerechnete Modulgroesse; wirkungslos neben `size`. */
+    groesse?: QrModulGroesse;
+    /** Modell 1 des Symbols ausdruecklich waehlen — siehe `qrCodeBytes`. */
+    modell1?: boolean;
+}
+export interface EscPosQrRasterOptions {
+    align?: PosAlign;
+    /** Feste Punkte je Modul; ohne Angabe gerechnet (mindestens 1). */
+    punkteJeModul?: number;
+    /** Deckel fuer die gerechnete Groesse. */
+    groesse?: QrModulGroesse;
+    /** Ruhezone je Seite in Modulen; Vorgabe `QR_RUHEZONE_MODULE` (4). */
+    ruhezoneModule?: number;
 }
 /** Interner Stilzustand — immer vollstaendig, nie teilbefuellt. */
 interface AktuelleStile {
@@ -111,6 +138,25 @@ interface AktuelleStile {
 export interface EscPosDocument {
     readonly paperSize: PosPaperSize;
     readonly spaceBetweenRows: number;
+    /**
+     * Der Beleg ging ohne QR hinaus — `null`, solange alles in Ordnung ist.
+     * Gesetzt, wenn das Symbol auch mit der Ausnahmegroesse nicht auf das Papier
+     * passt und kein Bildweg mitgegeben wurde. Auf einer oesterreichischen Kassa
+     * ist der QR die maschinenlesbare Signatur: das muss der Aufrufer erfahren,
+     * ohne den Bytestrom zu durchsuchen.
+     */
+    qrFehler: string | null;
+    /**
+     * Der QR steht auf dem Papier, aber nicht so wie eingestellt — `null`,
+     * solange nichts abgewichen ist. Zwei Faelle, beide mit Grund im Text: das
+     * Symbol war fuer den nativen Befehl zu breit und ging als Bild hinaus, oder
+     * es passte nur unter der Mindest-Modulgroesse.
+     *
+     * Getrennt von `qrFehler`, weil die Handlung eine andere ist: dort heisst es
+     * "Beleg ohne QR, nachdrucken oder elektronisch ausgeben", hier "gedruckt,
+     * aber der eingestellte Weg taugt fuer dieses Geraet nicht".
+     */
+    qrAusweich: string | null;
     /** intern: bisher erzeugte Bytes */
     readonly bytes: number[];
     /** intern: global gesetzte Codepage (ueberlebt `escPosReset`) */
@@ -213,7 +259,45 @@ export declare function escPosRow(doc: EscPosDocument, columns: readonly PosColu
 export declare function qrCodeBytes(text: string, options?: {
     size?: QrSize;
     correction?: QrCorrection;
+    modell1?: boolean;
 }): Uint8Array;
-/** Setzt die Ausrichtung und haengt den nativen QR-Befehl an. */
+/**
+ * Setzt die Ausrichtung und haengt den nativen QR-Befehl an — mit
+ * **gerechneter** Modulgroesse, sofern `options.size` sie nicht festlegt.
+ *
+ * Ohne `size` entscheidet die Regel aus `qr-groesse.ts`: so gross wie
+ * moeglich, gedeckelt durch `options.groesse` (Vorgabe `auto` = der
+ * Bestandswert 4 dieses Pakets). Passt das Symbol auch mit der
+ * Ausnahmegroesse nicht aufs Papier, geht **kein** QR-Befehl hinaus und
+ * `doc.qrFehler` sagt warum: der Drucker schneidet ein zu breites Symbol
+ * nicht ab, er laesst es weg — ein Befehl, von dem man weiss, dass er nichts
+ * druckt, taeuschte nur einen Ausdruck vor. Den Bildweg kennt diese Ebene
+ * nicht; den faehrt `escPosQrRaster` bzw. der Belegweg in `layout-escpos.ts`.
+ *
+ * Eine leere Nutzlast geht unveraendert durch (fester Bestandsweg, keine
+ * Rechnung): sie ist ein Datenfehler, kein Papierfehler, und der Aufrufer
+ * behandelt sie ohnehin schon.
+ */
 export declare function escPosQrCode(doc: EscPosDocument, text: string, options?: EscPosQrOptions): void;
+/**
+ * Der Bildweg: ein fertiges QR-Raster als Rasterbild (`GS v 0`) — der
+ * Notausgang, wenn der native Befehl das Symbol nicht auf das Papier bringt.
+ *
+ * Ein Pflichtbeleg ohne QR ist der schlechteste aller Ausgaenge; als Bild
+ * geht jedes Symbol hinaus, weil die Punkte je Modul hier bis auf 1 fallen
+ * duerfen. Dafuer ist das Bild langsamer und auf manchen Geraeten blasser.
+ *
+ * Das Raster selbst kommt vom Aufrufer (siehe `QrMatrix`): dieses Paket
+ * rechnet keine QR-Codes und verarbeitet keine Bilder.
+ */
+export declare function escPosQrRaster(doc: EscPosDocument, matrix: QrMatrix, options?: EscPosQrRasterOptions): void;
+/**
+ * Punkte je Modul, mit denen `escPosQrRaster` ein Raster dieser Groesse auf
+ * dieses Papier bringt — dieselbe Rechnung, nur ohne Untergrenze 3: ein Bild
+ * darf bis auf einen Punkt je Modul schrumpfen und passt darum immer.
+ */
+export declare function qrRasterPunkte(paperSize: PosPaperSize, moduleAnzahl: number, options?: {
+    groesse?: QrModulGroesse;
+    ruhezoneModule?: number;
+}): number;
 export {};

package/dist/cjs/printing/escpos.js

@@ -47,6 +47,9 @@ exports.escPosHr = escPosHr;
 exports.escPosRow = escPosRow;
 exports.qrCodeBytes = qrCodeBytes;
 exports.escPosQrCode = escPosQrCode;
+exports.escPosQrRaster = escPosQrRaster;
+exports.qrRasterPunkte = qrRasterPunkte;
+const qr_groesse_js_1 = require("./qr-groesse.js");
 // -------------------------------------------------------------- Befehlsbytes
 // Wortwoertlich aus commands.dart. Die Zahlen sind ASCII-Codes der dortigen
 // Zeichenketten: cCutFull = '$gs' + 'V0' ist GS 0x56 0x30 — die Ziffer '0',
@@ -81,6 +84,8 @@ const ZEILENUMBRUCH = 0x0a;
 const CODEPAGE_ID = { CP437: 0, CP1252: 16 };
 /** Korrekturstufen fuer GS ( k Funktion 169 — aus qrcode.dart. */
 const QR_KORREKTUR = { L: 48, M: 49, Q: 50, H: 51 };
+/** Nennbreite der Rolle in Millimetern — nur fuer Meldungstexte. */
+const PAPIER_MM = { mm58: 58, mm80: 80 };
 /** Druckbreite in Punkten je Papierformat — aus enums.dart (EscPaperSize.width). */
 const PAPIER_BREITE = { mm58: 372, mm80: 558 };
 /** Zeichen je Zeile nach Papier und Schrift — aus generator.dart. */
@@ -231,6 +236,8 @@ function createEscPosDocument(options = {}) {
         globalFont: null,
         maxCharsPerLine: null,
         styles: vollstaendigeStile(),
+        qrFehler: null,
+        qrAusweich: null,
     };
 }
 /** Die bisher erzeugten Bytes als Kopie. */
@@ -245,6 +252,10 @@ function escPosBytes(doc) {
 function escPosReset(doc) {
     anhaengen(doc, C_INIT);
     doc.styles = vollstaendigeStile();
+    // Wie `PrintPaper.reset()` im Flutter-Zwilling: ein neu begonnener Beleg
+    // erbt die QR-Meldungen des vorigen nicht.
+    doc.qrFehler = null;
+    doc.qrAusweich = null;
     escPosSetGlobalCodeTable(doc, doc.globalCodeTable);
     escPosSetGlobalFont(doc, doc.globalFont);
 }
@@ -609,6 +620,16 @@ function qrCodeBytes(text, options = {}) {
         throw new Error('QR-Inhalt ist zu lang');
     }
     const bytes = [];
+    // Funktion 165: Symboltyp. Ohne diesen Befehl — dem Bestandsweg — waehlt der
+    // Drucker sein eigenes Modell, in aller Regel Modell 2. Genau das koennen
+    // manche guenstigen Geraete nicht: belegt ist eines, das unter dem Code eine
+    // "0" ausgibt, das Parameterbyte 0x30 des Druckbefehls, das es nicht als
+    // Befehl erkannt hat. Der Befehl geht deshalb nur hinaus, wenn er
+    // ausdruecklich verlangt ist; ein aufgedraengtes "Modell 2 fuer alle" waere
+    // eine stille Umstellung an jedem Bestandsgeraet.
+    if (options.modell1 === true) {
+        bytes.push(...C_QR_HEADER, 0x04, 0x00, 0x31, 0x41, 0x31, 0x00);
+    }
     // Funktion 167: Modulgroesse
     bytes.push(...C_QR_HEADER, 0x03, 0x00, 0x31, 0x43, size);
     // Funktion 169: Fehlerkorrektur
@@ -624,15 +645,57 @@ function qrCodeBytes(text, options = {}) {
     bytes.push(...C_QR_HEADER, 0x03, 0x00, 0x31, 0x51, 0x30);
     return Uint8Array.from(bytes);
 }
-/** Setzt die Ausrichtung und haengt den nativen QR-Befehl an. */
+/**
+ * Setzt die Ausrichtung und haengt den nativen QR-Befehl an — mit
+ * **gerechneter** Modulgroesse, sofern `options.size` sie nicht festlegt.
+ *
+ * Ohne `size` entscheidet die Regel aus `qr-groesse.ts`: so gross wie
+ * moeglich, gedeckelt durch `options.groesse` (Vorgabe `auto` = der
+ * Bestandswert 4 dieses Pakets). Passt das Symbol auch mit der
+ * Ausnahmegroesse nicht aufs Papier, geht **kein** QR-Befehl hinaus und
+ * `doc.qrFehler` sagt warum: der Drucker schneidet ein zu breites Symbol
+ * nicht ab, er laesst es weg — ein Befehl, von dem man weiss, dass er nichts
+ * druckt, taeuschte nur einen Ausdruck vor. Den Bildweg kennt diese Ebene
+ * nicht; den faehrt `escPosQrRaster` bzw. der Belegweg in `layout-escpos.ts`.
+ *
+ * Eine leere Nutzlast geht unveraendert durch (fester Bestandsweg, keine
+ * Rechnung): sie ist ein Datenfehler, kein Papierfehler, und der Aufrufer
+ * behandelt sie ohnehin schon.
+ */
 function escPosQrCode(doc, text, options = {}) {
     escPosSetStyles(doc, { align: options.align ?? 'center' });
     const qrOptionen = {};
-    if (options.size !== undefined)
-        qrOptionen.size = options.size;
     if (options.correction !== undefined)
         qrOptionen.correction = options.correction;
-    anhaengen(doc, qrCodeBytes(text, qrOptionen));
+    if (options.modell1 !== undefined)
+        qrOptionen.modell1 = options.modell1;
+    let drucken = true;
+    if (options.size !== undefined) {
+        qrOptionen.size = options.size;
+    }
+    else if (text !== '') {
+        const mass = (0, qr_groesse_js_1.qrGroesseFuer)({
+            nutzlast: text,
+            papierbreitePunkte: qr_groesse_js_1.QR_DRUCK_PUNKTE[doc.paperSize],
+            groesse: options.groesse ?? 'auto',
+        });
+        if (!mass.passt) {
+            doc.qrFehler =
+                `QR mit ${mass.module} Modulen ist fuer ${PAPIER_MM[doc.paperSize]} mm ` +
+                    `(${qr_groesse_js_1.QR_DRUCK_PUNKTE[doc.paperSize]} Punkte) zu breit`;
+            drucken = false;
+        }
+        else {
+            if (mass.unterMindestmass) {
+                doc.qrAusweich =
+                    `QR mit ${mass.module} Modulen passt nur mit ${String(mass.punkte)} Punkten ` +
+                        `je Modul — unter dem Mindestmass von ${qr_groesse_js_1.QR_MINDEST_PUNKTE}`;
+            }
+            qrOptionen.size = mass.punkte;
+        }
+    }
+    if (drucken)
+        anhaengen(doc, qrCodeBytes(text, qrOptionen));
     // Ausrichtung SOFORT zuruecksetzen: `ESC a` gilt nur am Zeilenanfang. Die
     // Spalten-Positionierung (`ESC $`) schickt ihren Reset sonst mitten in der
     // Zeile — Epson ignoriert ihn, und alles nach dem QR rueckte nach rechts
@@ -641,3 +704,76 @@ function escPosQrCode(doc, text, options = {}) {
         escPosSetStyles(doc, { align: 'left' });
     }
 }
+/**
+ * Der Bildweg: ein fertiges QR-Raster als Rasterbild (`GS v 0`) — der
+ * Notausgang, wenn der native Befehl das Symbol nicht auf das Papier bringt.
+ *
+ * Ein Pflichtbeleg ohne QR ist der schlechteste aller Ausgaenge; als Bild
+ * geht jedes Symbol hinaus, weil die Punkte je Modul hier bis auf 1 fallen
+ * duerfen. Dafuer ist das Bild langsamer und auf manchen Geraeten blasser.
+ *
+ * Das Raster selbst kommt vom Aufrufer (siehe `QrMatrix`): dieses Paket
+ * rechnet keine QR-Codes und verarbeitet keine Bilder.
+ */
+function escPosQrRaster(doc, matrix, options = {}) {
+    const module = matrix.length;
+    if (module <= 0)
+        throw new Error('QR-Raster ist leer');
+    for (const zeile of matrix) {
+        if (zeile.length !== module)
+            throw new Error('QR-Raster ist nicht quadratisch');
+    }
+    const ruhezone = options.ruhezoneModule ?? qr_groesse_js_1.QR_RUHEZONE_MODULE;
+    if (!istGanzzahl(ruhezone) || ruhezone < 0) {
+        throw new Error('ruhezoneModule muss eine Ganzzahl >= 0 sein');
+    }
+    const gesamtModule = module + 2 * ruhezone;
+    let punkte = options.punkteJeModul;
+    if (punkte === undefined) {
+        const deckel = qr_groesse_js_1.QR_MODUL_DECKEL[options.groesse ?? 'auto'];
+        punkte = Math.max(1, Math.min(deckel, Math.floor(qr_groesse_js_1.QR_DRUCK_PUNKTE[doc.paperSize] / gesamtModule)));
+    }
+    if (!istGanzzahl(punkte) || punkte < 1) {
+        throw new Error('punkteJeModul muss eine Ganzzahl >= 1 sein');
+    }
+    const breite = gesamtModule * punkte;
+    const byteJeZeile = Math.ceil(breite / 8);
+    const daten = new Uint8Array(byteJeZeile * breite);
+    for (let y = 0; y < breite; y++) {
+        const modulY = Math.floor(y / punkte) - ruhezone;
+        if (modulY < 0 || modulY >= module)
+            continue;
+        const zeile = matrix[modulY];
+        for (let x = 0; x < breite; x++) {
+            const modulX = Math.floor(x / punkte) - ruhezone;
+            if (modulX < 0 || modulX >= module)
+                continue;
+            if (zeile[modulX] !== true)
+                continue;
+            const i = y * byteJeZeile + (x >> 3);
+            daten[i] = daten[i] | (0x80 >> (x & 7));
+        }
+    }
+    escPosSetStyles(doc, { align: options.align ?? 'center' });
+    // GS v 0 m xL xH yL yH d1...dk — m = 0: normale Dichte, 1:1.
+    anhaengen(doc, [
+        GS, 0x76, 0x30, 0x00,
+        byteJeZeile & 0xff, (byteJeZeile >> 8) & 0xff,
+        breite & 0xff, (breite >> 8) & 0xff,
+        ...daten,
+    ]);
+    anhaengen(doc, [ZEILENUMBRUCH]);
+    if ((options.align ?? 'center') !== 'left') {
+        escPosSetStyles(doc, { align: 'left' });
+    }
+}
+/**
+ * Punkte je Modul, mit denen `escPosQrRaster` ein Raster dieser Groesse auf
+ * dieses Papier bringt — dieselbe Rechnung, nur ohne Untergrenze 3: ein Bild
+ * darf bis auf einen Punkt je Modul schrumpfen und passt darum immer.
+ */
+function qrRasterPunkte(paperSize, moduleAnzahl, options = {}) {
+    const ruhezone = options.ruhezoneModule ?? qr_groesse_js_1.QR_RUHEZONE_MODULE;
+    const deckel = qr_groesse_js_1.QR_MODUL_DECKEL[options.groesse ?? 'auto'];
+    return Math.max(1, Math.min(deckel, Math.floor(qr_groesse_js_1.QR_DRUCK_PUNKTE[paperSize] / (moduleAnzahl + 2 * ruhezone))));
+}

package/dist/cjs/printing/index.d.ts

@@ -1,3 +1,4 @@
-export { type PosPaperSize, type PosAlign, type PosFont, type PosCutMode, type PosCodeTable, type PosTextSize, type QrSize, type QrCorrection, type PosStyles, type PosColumn, type EscPosOptions, type EscPosTextOptions, type EscPosHrOptions, type EscPosQrOptions, type EscPosDocument, createEscPosDocument, escPosBytes, escPosReset, escPosSetGlobalCodeTable, escPosSetGlobalFont, escPosSetStyles, escPosText, escPosEmptyLines, escPosFeed, escPosCut, escPosHr, escPosRow, escPosQrCode, encodeEscPosText, qrCodeBytes, escPosMaxCharsPerLine, escPosWortzeilen, wortzeilenText, } from './escpos.js';
+export { type PosPaperSize, type PosAlign, type PosFont, type PosCutMode, type PosCodeTable, type PosTextSize, type QrSize, type QrCorrection, type QrMatrix, type PosStyles, type PosColumn, type EscPosOptions, type EscPosTextOptions, type EscPosHrOptions, type EscPosQrOptions, type EscPosQrRasterOptions, type EscPosDocument, createEscPosDocument, escPosBytes, escPosReset, escPosSetGlobalCodeTable, escPosSetGlobalFont, escPosSetStyles, escPosText, escPosEmptyLines, escPosFeed, escPosCut, escPosHr, escPosRow, escPosQrCode, escPosQrRaster, qrRasterPunkte, encodeEscPosText, qrCodeBytes, escPosMaxCharsPerLine, escPosWortzeilen, wortzeilenText, } from './escpos.js';
+export { type QrModulGroesse, type QrGroesse, QR_MODUL_DECKEL, QR_RUHEZONE_MODULE, QR_MINDEST_PUNKTE, QR_AUSNAHME_PUNKTE, QR_HOECHST_PUNKTE, QR_DRUCK_PUNKTE, qrModulAnzahl, qrGroesseBerechnen, qrGroesseFuer, } from './qr-groesse.js';
 export { escPosPrintableText } from './printable.js';
 export { type UsbEndpointLike, type UsbAlternateLike, type UsbInterfaceLike, type UsbConfigurationLike, type UsbTransferOutResultLike, type UsbWriterLike, type UsbIdentityLike, type UsbDeviceLike, type UsbPrinterEndpoint, type UsbPrinterConnection, USB_VENDOR_EPSON, USB_CLASS_PRINTER, UsbTimeoutError, usbDeviceKey, usbFindPrinterEndpoint, usbWriteAll, usbConnectPrinter, usbPrint, usbDisconnect, } from './webusb.js';

package/dist/cjs/printing/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.usbDisconnect = exports.usbPrint = exports.usbConnectPrinter = exports.usbWriteAll = exports.usbFindPrinterEndpoint = exports.usbDeviceKey = exports.UsbTimeoutError = exports.USB_CLASS_PRINTER = exports.USB_VENDOR_EPSON = exports.escPosPrintableText = exports.wortzeilenText = exports.escPosWortzeilen = exports.escPosMaxCharsPerLine = exports.qrCodeBytes = exports.encodeEscPosText = exports.escPosQrCode = exports.escPosRow = exports.escPosHr = exports.escPosCut = exports.escPosFeed = exports.escPosEmptyLines = exports.escPosText = exports.escPosSetStyles = exports.escPosSetGlobalFont = exports.escPosSetGlobalCodeTable = exports.escPosReset = exports.escPosBytes = exports.createEscPosDocument = void 0;
+exports.usbDisconnect = exports.usbPrint = exports.usbConnectPrinter = exports.usbWriteAll = exports.usbFindPrinterEndpoint = exports.usbDeviceKey = exports.UsbTimeoutError = exports.USB_CLASS_PRINTER = exports.USB_VENDOR_EPSON = exports.escPosPrintableText = exports.qrGroesseFuer = exports.qrGroesseBerechnen = exports.qrModulAnzahl = exports.QR_DRUCK_PUNKTE = exports.QR_HOECHST_PUNKTE = exports.QR_AUSNAHME_PUNKTE = exports.QR_MINDEST_PUNKTE = exports.QR_RUHEZONE_MODULE = exports.QR_MODUL_DECKEL = exports.wortzeilenText = exports.escPosWortzeilen = exports.escPosMaxCharsPerLine = exports.qrCodeBytes = exports.encodeEscPosText = exports.qrRasterPunkte = exports.escPosQrRaster = exports.escPosQrCode = exports.escPosRow = exports.escPosHr = exports.escPosCut = exports.escPosFeed = exports.escPosEmptyLines = exports.escPosText = exports.escPosSetStyles = exports.escPosSetGlobalFont = exports.escPosSetGlobalCodeTable = exports.escPosReset = exports.escPosBytes = exports.createEscPosDocument = void 0;
 var escpos_js_1 = require("./escpos.js");
 Object.defineProperty(exports, "createEscPosDocument", { enumerable: true, get: function () { return escpos_js_1.createEscPosDocument; } });
 Object.defineProperty(exports, "escPosBytes", { enumerable: true, get: function () { return escpos_js_1.escPosBytes; } });
@@ -15,11 +15,23 @@ Object.defineProperty(exports, "escPosCut", { enumerable: true, get: function ()
 Object.defineProperty(exports, "escPosHr", { enumerable: true, get: function () { return escpos_js_1.escPosHr; } });
 Object.defineProperty(exports, "escPosRow", { enumerable: true, get: function () { return escpos_js_1.escPosRow; } });
 Object.defineProperty(exports, "escPosQrCode", { enumerable: true, get: function () { return escpos_js_1.escPosQrCode; } });
+Object.defineProperty(exports, "escPosQrRaster", { enumerable: true, get: function () { return escpos_js_1.escPosQrRaster; } });
+Object.defineProperty(exports, "qrRasterPunkte", { enumerable: true, get: function () { return escpos_js_1.qrRasterPunkte; } });
 Object.defineProperty(exports, "encodeEscPosText", { enumerable: true, get: function () { return escpos_js_1.encodeEscPosText; } });
 Object.defineProperty(exports, "qrCodeBytes", { enumerable: true, get: function () { return escpos_js_1.qrCodeBytes; } });
 Object.defineProperty(exports, "escPosMaxCharsPerLine", { enumerable: true, get: function () { return escpos_js_1.escPosMaxCharsPerLine; } });
 Object.defineProperty(exports, "escPosWortzeilen", { enumerable: true, get: function () { return escpos_js_1.escPosWortzeilen; } });
 Object.defineProperty(exports, "wortzeilenText", { enumerable: true, get: function () { return escpos_js_1.wortzeilenText; } });
+var qr_groesse_js_1 = require("./qr-groesse.js");
+Object.defineProperty(exports, "QR_MODUL_DECKEL", { enumerable: true, get: function () { return qr_groesse_js_1.QR_MODUL_DECKEL; } });
+Object.defineProperty(exports, "QR_RUHEZONE_MODULE", { enumerable: true, get: function () { return qr_groesse_js_1.QR_RUHEZONE_MODULE; } });
+Object.defineProperty(exports, "QR_MINDEST_PUNKTE", { enumerable: true, get: function () { return qr_groesse_js_1.QR_MINDEST_PUNKTE; } });
+Object.defineProperty(exports, "QR_AUSNAHME_PUNKTE", { enumerable: true, get: function () { return qr_groesse_js_1.QR_AUSNAHME_PUNKTE; } });
+Object.defineProperty(exports, "QR_HOECHST_PUNKTE", { enumerable: true, get: function () { return qr_groesse_js_1.QR_HOECHST_PUNKTE; } });
+Object.defineProperty(exports, "QR_DRUCK_PUNKTE", { enumerable: true, get: function () { return qr_groesse_js_1.QR_DRUCK_PUNKTE; } });
+Object.defineProperty(exports, "qrModulAnzahl", { enumerable: true, get: function () { return qr_groesse_js_1.qrModulAnzahl; } });
+Object.defineProperty(exports, "qrGroesseBerechnen", { enumerable: true, get: function () { return qr_groesse_js_1.qrGroesseBerechnen; } });
+Object.defineProperty(exports, "qrGroesseFuer", { enumerable: true, get: function () { return qr_groesse_js_1.qrGroesseFuer; } });
 var printable_js_1 = require("./printable.js");
 Object.defineProperty(exports, "escPosPrintableText", { enumerable: true, get: function () { return printable_js_1.escPosPrintableText; } });
 var webusb_js_1 = require("./webusb.js");