@kreiseck/kasseneck-api 0.10.0 → 0.12.0

package/dist/esm/client/receipts.js

@@ -140,6 +140,24 @@ export 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 !== KeckPaymentMethod.creditCard.value) {
+            throw new KasseneckValidationError('cancelReceipt', 'Kartendaten gibt es nur bei paymentMethod creditCard', 'request');
+        }
+        if (options.creditCardProvider != null) {
+            if (!Object.prototype.hasOwnProperty.call(CreditCardProvider, options.creditCardProvider)) {
+                throw new 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/esm/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/esm/printing/escpos.js

@@ -27,6 +27,7 @@
  * Nicht enthalten (bewusst): Rasterbilder/Logos, Capability-Profile einzelner
  * Druckermodelle, Kassenlade, 1D-Barcodes.
  */
+import { QR_DRUCK_PUNKTE, QR_MINDEST_PUNKTE, QR_MODUL_DECKEL, QR_RUHEZONE_MODULE, qrGroesseFuer, } from './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',
@@ -61,6 +62,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. */
@@ -211,6 +214,8 @@ export function createEscPosDocument(options = {}) {
         globalFont: null,
         maxCharsPerLine: null,
         styles: vollstaendigeStile(),
+        qrFehler: null,
+        qrAusweich: null,
     };
 }
 /** Die bisher erzeugten Bytes als Kopie. */
@@ -225,6 +230,10 @@ export function escPosBytes(doc) {
 export 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);
 }
@@ -589,6 +598,16 @@ export 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
@@ -604,15 +623,57 @@ export 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.
+ */
 export 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 = qrGroesseFuer({
+            nutzlast: text,
+            papierbreitePunkte: 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_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_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
@@ -621,3 +682,76 @@ export 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.
+ */
+export 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_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_MODUL_DECKEL[options.groesse ?? 'auto'];
+        punkte = Math.max(1, Math.min(deckel, Math.floor(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.
+ */
+export function qrRasterPunkte(paperSize, moduleAnzahl, options = {}) {
+    const ruhezone = options.ruhezoneModule ?? QR_RUHEZONE_MODULE;
+    const deckel = QR_MODUL_DECKEL[options.groesse ?? 'auto'];
+    return Math.max(1, Math.min(deckel, Math.floor(QR_DRUCK_PUNKTE[paperSize] / (moduleAnzahl + 2 * ruhezone))));
+}

package/dist/esm/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/esm/printing/index.js

@@ -1,3 +1,4 @@
-export { createEscPosDocument, escPosBytes, escPosReset, escPosSetGlobalCodeTable, escPosSetGlobalFont, escPosSetStyles, escPosText, escPosEmptyLines, escPosFeed, escPosCut, escPosHr, escPosRow, escPosQrCode, encodeEscPosText, qrCodeBytes, escPosMaxCharsPerLine, escPosWortzeilen, wortzeilenText, } from './escpos.js';
+export { createEscPosDocument, escPosBytes, escPosReset, escPosSetGlobalCodeTable, escPosSetGlobalFont, escPosSetStyles, escPosText, escPosEmptyLines, escPosFeed, escPosCut, escPosHr, escPosRow, escPosQrCode, escPosQrRaster, qrRasterPunkte, encodeEscPosText, qrCodeBytes, escPosMaxCharsPerLine, escPosWortzeilen, wortzeilenText, } from './escpos.js';
+export { 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 { USB_VENDOR_EPSON, USB_CLASS_PRINTER, UsbTimeoutError, usbDeviceKey, usbFindPrinterEndpoint, usbWriteAll, usbConnectPrinter, usbPrint, usbDisconnect, } from './webusb.js';

package/dist/esm/printing/qr-groesse.d.ts

@@ -0,0 +1,122 @@
+import type { PosPaperSize, QrSize } from './escpos.js';
+/**
+ * Die Rechenregel fuer die Modulgroesse des Beleg-QR — rein, ohne Drucker.
+ * Zwilling von `kasseneck_api/lib/src/printing/qr_groesse.dart` (Flutter).
+ *
+ * Vorgeschichte: der native QR-Befehl bekommt eine feste Modulgroesse in
+ * Druckpunkten mit und rechnet nicht nach, ob das Symbol aufs Papier passt.
+ * Ein Beleg-QR mit realer RKSV-Nutzlast hat 57 Module, mit Ruhezone also
+ * (57 + 8) Module breit; bei sechs Punkten je Modul sind das 390 Druckpunkte,
+ * und ein 58-mm-Kopf hat 384. Zu breit heisst bei den meisten Geraeten nicht
+ * "abgeschnitten", sondern **gar kein QR** — auf einem Pflichtbeleg der
+ * schlechteste aller Ausgaenge. (Im Flutter-Zwilling war genau das der
+ * belegte Fehler; dieses Paket druckt seit jeher mit vier Punkten und blieb
+ * darum verschont. Die Regel ist trotzdem dieselbe: sie deckelt auch eine
+ * ausdruecklich gewaehlte groessere Modulgroesse gegen den Papierrand ab.)
+ */
+/**
+ * Wie gross die Module des Beleg-QR werden duerfen — ein **Deckel**, keine
+ * Vorgabe: gedruckt wird immer die groesste Groesse, die noch aufs Papier
+ * passt, hoechstens aber diese hier.
+ *
+ * `auto` und `klein` decken beide bei 4 — das ist kein Versehen. 4 ist der
+ * Wert, den der native Weg dieses Pakets seit jeher druckt
+ * (`qrCodeBytes(..., size ?? 4)`); ohne diesen Deckel bekaeme jedes Geraet ab
+ * sofort ungefragt einen groesseren QR als gestern. `auto` heisst also
+ * "rechne, aber aendere den Bestand nicht".
+ *
+ * **Abweichung zum Flutter-Zwilling, bewusst:** dort deckelt `auto` bei 6,
+ * weil dort 6 der Bestandswert ist. Die Regel ist in beiden Paketen
+ * dieselbe — "so gross wie moeglich, hoechstens der Bestandswert" —, nur der
+ * Bestandswert unterscheidet sich. `mittel` (6) und `gross` (8) sind in
+ * beiden Paketen gleich; sie waehlt ein Mensch.
+ */
+export type QrModulGroesse = 'auto' | 'klein' | 'mittel' | 'gross';
+/** Groesste Modulgroesse in Druckpunkten, die der jeweilige Deckel zulaesst. */
+export declare const QR_MODUL_DECKEL: Readonly<Record<QrModulGroesse, number>>;
+/**
+ * Ergebnis der Modulgroessen-Rechnung.
+ *
+ * Traegt bewusst mehr als die Zahl: ob ueberhaupt etwas passt (`passt`), ob
+ * nur unter der Mindestgroesse (`unterMindestmass`) und wie breit das Symbol
+ * wird (`breitePunkte`). Eine blosse Zahl haette die Ausnahme verschwiegen.
+ */
+export interface QrGroesse {
+    /**
+     * Modulgroesse in Druckpunkten, `null` wenn das Symbol auch mit der
+     * Ausnahmegroesse nicht aufs Papier passt.
+     */
+    readonly punkte: QrSize | null;
+    /** Modulanzahl des Symbols (ohne Ruhezone). */
+    readonly module: number;
+    /** Gesamtbreite inklusive Ruhezone in Druckpunkten; 0, wenn nichts passt. */
+    readonly breitePunkte: number;
+    /**
+     * Gedruckt wird unter `QR_MINDEST_PUNKTE`. Erlaubt, aber eine Ausnahme, von
+     * der der Aufrufer erfahren muss — billige Thermodrucker und Handykameras
+     * tun sich damit schwer, besonders auf gewelltem Papier.
+     */
+    readonly unterMindestmass: boolean;
+    /** Kurz fuer `punkte !== null`. */
+    readonly passt: boolean;
+}
+/** Ruhezone je Seite, in Modulen (QR-Norm). */
+export declare const QR_RUHEZONE_MODULE = 4;
+/** Untergrenze: 4 Punkte sind bei 203 dpi rund 0,5 mm je Modul. */
+export declare const QR_MINDEST_PUNKTE = 4;
+/** Ausnahme, wenn `QR_MINDEST_PUNKTE` nicht passt — gemeldet, nicht still. */
+export declare const QR_AUSNAHME_PUNKTE = 3;
+/** Obergrenze des Druckbefehls in diesem Stack (`GS ( k` Funktion 167: 1..8). */
+export declare const QR_HOECHST_PUNKTE = 8;
+/**
+ * Druckbreite des Kopfes in Punkten (203 dpi): 58 mm = 384, 80 mm = 576 —
+ * Zwilling von `KeckPaperSize.druckPunkte`.
+ *
+ * Nicht dasselbe wie die Spaltenbreite in `escpos.ts` (372/558): die stammt
+ * aus `EscPaperSize.width` und laesst absichtlich Rand fuer die
+ * Textpositionierung. Wer rechnet, ob ein Symbol aufs Papier passt, braucht
+ * die echte Kopfbreite — ein QR, der auch nur einen Punkt zu breit ist, wird
+ * von den meisten Geraeten gar nicht gedruckt.
+ */
+export declare const QR_DRUCK_PUNKTE: Readonly<Record<PosPaperSize, number>>;
+/**
+ * Modulanzahl, die `nutzlast` bei Fehlerkorrektur **M** braucht.
+ *
+ * Warum M, obwohl der native Befehl mit L druckt: M braucht bei gleicher
+ * Nutzlast gleich viele oder mehr Module als L. Wer mit M rechnet und mit L
+ * druckt, druckt nie breiter als gerechnet — die Rechnung ist konservativ,
+ * nie knapp. Umgekehrt waere sie eine Rechnung, die aufgeht, und ein Symbol,
+ * das ueber den Papierrand laeuft. Dasselbe gilt fuer die Byte-Zaehlung: hier
+ * zaehlt UTF-8 (wie im Flutter-Zwilling), waehrend `qrCodeBytes` die Nutzlast
+ * als Latin-1 sendet — UTF-8 ist nie kuerzer, die Rechnung also nie zu klein.
+ *
+ * Wirft, wenn die Nutzlast in keine Version passt — wie `qrCodeBytes` bei zu
+ * langem Inhalt. Ein still zurueckgegebenes "passt nicht" haette den
+ * Datenfehler als Papierfehler getarnt.
+ */
+export declare function qrModulAnzahl(nutzlast: string): number;
+/**
+ * Groesste Modulgroesse, mit der `moduleAnzahl` Module **samt Ruhezone** in
+ * `papierbreitePunkte` passen, gedeckelt durch `groesse`.
+ *
+ * Wirft bei sinnlosen Eingaben: eine Papierbreite von 0 oder ein Symbol ohne
+ * Module ist ein Programmierfehler, und ein still zurueckgegebenes "passt
+ * nicht" haette ihn als Druckerproblem getarnt.
+ */
+export declare function qrGroesseBerechnen(options: {
+    papierbreitePunkte: number;
+    moduleAnzahl: number;
+    groesse?: QrModulGroesse;
+}): QrGroesse;
+/**
+ * Wie `qrGroesseBerechnen`, nur mit der Modulanzahl aus `nutzlast`.
+ *
+ * Eine leere Nutzlast ergibt kein Symbol — sie "passt nicht", statt zu
+ * werfen: der Aufrufer behandelt den Fall ohnehin schon (leerer QR am Beleg
+ * ist ein Datenfehler, kein Papierfehler).
+ */
+export declare function qrGroesseFuer(options: {
+    nutzlast: string;
+    papierbreitePunkte: number;
+    groesse?: QrModulGroesse;
+}): QrGroesse;

package/dist/esm/printing/qr-groesse.js

@@ -0,0 +1,120 @@
+/** Groesste Modulgroesse in Druckpunkten, die der jeweilige Deckel zulaesst. */
+export const QR_MODUL_DECKEL = {
+    auto: 4,
+    klein: 4,
+    mittel: 6,
+    gross: 8,
+};
+// --------------------------------------------------------------- Konstanten
+/** Ruhezone je Seite, in Modulen (QR-Norm). */
+export const QR_RUHEZONE_MODULE = 4;
+/** Untergrenze: 4 Punkte sind bei 203 dpi rund 0,5 mm je Modul. */
+export const QR_MINDEST_PUNKTE = 4;
+/** Ausnahme, wenn `QR_MINDEST_PUNKTE` nicht passt — gemeldet, nicht still. */
+export const QR_AUSNAHME_PUNKTE = 3;
+/** Obergrenze des Druckbefehls in diesem Stack (`GS ( k` Funktion 167: 1..8). */
+export const QR_HOECHST_PUNKTE = 8;
+/**
+ * Druckbreite des Kopfes in Punkten (203 dpi): 58 mm = 384, 80 mm = 576 —
+ * Zwilling von `KeckPaperSize.druckPunkte`.
+ *
+ * Nicht dasselbe wie die Spaltenbreite in `escpos.ts` (372/558): die stammt
+ * aus `EscPaperSize.width` und laesst absichtlich Rand fuer die
+ * Textpositionierung. Wer rechnet, ob ein Symbol aufs Papier passt, braucht
+ * die echte Kopfbreite — ein QR, der auch nur einen Punkt zu breit ist, wird
+ * von den meisten Geraeten gar nicht gedruckt.
+ */
+export const QR_DRUCK_PUNKTE = { mm58: 384, mm80: 576 };
+/**
+ * Nutzlast in Byte, die eine QR-Version 1..40 bei Fehlerkorrektur **M** im
+ * Byte-Modus aufnimmt (ISO/IEC 18004, Tabelle 7).
+ *
+ * Byte-Modus, weil die RKSV-Nutzlast beliebige Zeichen traegt; Ziffern- oder
+ * Alphanumerik-Modus waere enger gefasst und wuerde fuer denselben Text
+ * weniger Module ergeben — also zu klein rechnen.
+ */
+const BYTE_KAPAZITAET_M = [
+    14, 26, 42, 62, 84, 106, 122, 152, 180, 213,
+    251, 287, 331, 362, 412, 450, 504, 560, 624, 666,
+    711, 779, 857, 911, 997, 1059, 1125, 1190, 1264, 1370,
+    1452, 1538, 1628, 1722, 1809, 1911, 1989, 2099, 2213, 2331,
+];
+// ------------------------------------------------------------- oeffentlich
+/**
+ * Modulanzahl, die `nutzlast` bei Fehlerkorrektur **M** braucht.
+ *
+ * Warum M, obwohl der native Befehl mit L druckt: M braucht bei gleicher
+ * Nutzlast gleich viele oder mehr Module als L. Wer mit M rechnet und mit L
+ * druckt, druckt nie breiter als gerechnet — die Rechnung ist konservativ,
+ * nie knapp. Umgekehrt waere sie eine Rechnung, die aufgeht, und ein Symbol,
+ * das ueber den Papierrand laeuft. Dasselbe gilt fuer die Byte-Zaehlung: hier
+ * zaehlt UTF-8 (wie im Flutter-Zwilling), waehrend `qrCodeBytes` die Nutzlast
+ * als Latin-1 sendet — UTF-8 ist nie kuerzer, die Rechnung also nie zu klein.
+ *
+ * Wirft, wenn die Nutzlast in keine Version passt — wie `qrCodeBytes` bei zu
+ * langem Inhalt. Ein still zurueckgegebenes "passt nicht" haette den
+ * Datenfehler als Papierfehler getarnt.
+ */
+export function qrModulAnzahl(nutzlast) {
+    const laenge = new TextEncoder().encode(nutzlast).length;
+    for (let i = 0; i < BYTE_KAPAZITAET_M.length; i++) {
+        if (laenge <= BYTE_KAPAZITAET_M[i])
+            return 17 + 4 * (i + 1);
+    }
+    throw new Error('QR-Inhalt ist zu lang');
+}
+/**
+ * Groesste Modulgroesse, mit der `moduleAnzahl` Module **samt Ruhezone** in
+ * `papierbreitePunkte` passen, gedeckelt durch `groesse`.
+ *
+ * Wirft bei sinnlosen Eingaben: eine Papierbreite von 0 oder ein Symbol ohne
+ * Module ist ein Programmierfehler, und ein still zurueckgegebenes "passt
+ * nicht" haette ihn als Druckerproblem getarnt.
+ */
+export function qrGroesseBerechnen(options) {
+    const { papierbreitePunkte, moduleAnzahl } = options;
+    const groesse = options.groesse ?? 'auto';
+    if (!Number.isInteger(papierbreitePunkte) || papierbreitePunkte <= 0) {
+        throw new Error('papierbreitePunkte muss eine Ganzzahl > 0 sein');
+    }
+    if (!Number.isInteger(moduleAnzahl) || moduleAnzahl <= 0) {
+        throw new Error('moduleAnzahl muss eine Ganzzahl > 0 sein');
+    }
+    const roh = QR_MODUL_DECKEL[groesse];
+    if (roh === undefined) {
+        throw new Error(`Unbekannte QR-Modulgroesse: ${String(groesse)}`);
+    }
+    const gesamtModule = moduleAnzahl + QR_RUHEZONE_MODULE * 2;
+    const passend = Math.floor(papierbreitePunkte / gesamtModule);
+    if (passend < QR_AUSNAHME_PUNKTE) {
+        return { punkte: null, module: moduleAnzahl, breitePunkte: 0, unterMindestmass: false, passt: false };
+    }
+    const deckel = Math.min(Math.max(roh, QR_AUSNAHME_PUNKTE), QR_HOECHST_PUNKTE);
+    const punkte = passend < QR_MINDEST_PUNKTE ? QR_AUSNAHME_PUNKTE : Math.min(passend, deckel);
+    return {
+        punkte: punkte,
+        module: moduleAnzahl,
+        breitePunkte: gesamtModule * punkte,
+        unterMindestmass: punkte < QR_MINDEST_PUNKTE,
+        passt: true,
+    };
+}
+/**
+ * Wie `qrGroesseBerechnen`, nur mit der Modulanzahl aus `nutzlast`.
+ *
+ * Eine leere Nutzlast ergibt kein Symbol — sie "passt nicht", statt zu
+ * werfen: der Aufrufer behandelt den Fall ohnehin schon (leerer QR am Beleg
+ * ist ein Datenfehler, kein Papierfehler).
+ */
+export function qrGroesseFuer(options) {
+    if (options.nutzlast === '') {
+        return { punkte: null, module: 0, breitePunkte: 0, unterMindestmass: false, passt: false };
+    }
+    const weiter = {
+        papierbreitePunkte: options.papierbreitePunkte,
+        moduleAnzahl: qrModulAnzahl(options.nutzlast),
+    };
+    if (options.groesse !== undefined)
+        weiter.groesse = options.groesse;
+    return qrGroesseBerechnen(weiter);
+}

package/dist/esm/receipt/epos.d.ts

@@ -1,5 +1,6 @@
 import type { ReceiptLayout } from './layout.js';
 import type { PosPaperSize } from '../printing/escpos.js';
+import { type QrModulGroesse } from '../printing/index.js';
 /**
  * ePOS-Print XML (Epson TM-Drucker: Server Direct Print, ePOS-Print ueber
  * HTTP) -- **aus dem Zeichenraster**: jede Rasterzeile wird eine <text>-Zeile
@@ -14,13 +15,49 @@ import type { PosPaperSize } from '../printing/escpos.js';
 export interface EposPrintXmlOptions {
     /** Zeichen je Zeile; Vorgabe nach `layout.paperSize` (32/48). */
     zeichen?: number;
-    /** QR-Modulgroesse (Epson `width` 3..16), Vorgabe 6. */
+    /**
+     * **Feste** QR-Modulgroesse (Epson `width` 3..16). Gesetzt schaltet sie die
+     * Rechnung ab -- dann passt der Aufrufer selbst auf, dass das Symbol samt
+     * Ruhezone auf die Rolle geht.
+     */
     qrBreite?: number;
+    /**
+     * Deckel fuer die gerechnete QR-Modulgroesse; Vorgabe `mittel`.
+     *
+     * Warum `mittel` und nicht `auto`: `auto` deckelt beim Bestandswert des
+     * **ESC/POS**-Befehls dieses Pakets (4), dieser Weg druckt aber seit jeher
+     * mit 6. Die Vorgabe nennt den Bestandswert dieses Wegs also ausdruecklich,
+     * damit ohne Wahl kein Byte anders herauskommt.
+     */
+    qrGroesse?: QrModulGroesse;
     /** Papierschnitt am Ende, Vorgabe true. */
     cut?: boolean;
 }
+/**
+ * Das XML **samt** dem, was dem QR unterwegs zugestossen ist -- dieselbe
+ * Buchfuehrung wie `EscPosLayoutErgebnis` am ESC/POS-Weg.
+ */
+export interface EposPrintErgebnis {
+    xml: string;
+    /** Der Beleg ging ohne QR hinaus; das Symbol passt auch mit 3 Punkten nicht. */
+    qrFehler: string | null;
+    /** Der QR steht da, aber unter der Mindest-Modulgroesse. */
+    qrAusweich: string | null;
+}
 export declare function eposXmlEscape(text: string): string;
+/** Nur das XML; wer die QR-Meldungen braucht, nimmt [eposPrintXmlErgebnis]. */
 export declare function eposPrintXml(layout: ReceiptLayout, options?: EposPrintXmlOptions): string;
+/**
+ * Wie [eposPrintXml], gibt aber zusaetzlich zurueck, was dem QR zugestossen
+ * ist.
+ *
+ * **Die QR-Modulgroesse wird gerechnet.** Vorher stand hier fest 6, unabhaengig
+ * von der Papierbreite: ein Beleg-QR mit realer RKSV-Nutzlast hat 57 Module,
+ * mit Ruhezone 65, bei sechs Punkten also 390 Druckpunkte -- und ein
+ * 58-mm-Kopf hat 384. Der Epson schneidet ein zu breites Symbol nicht ab, er
+ * laesst es weg; genau daran fehlte am echten Beleg der QR.
+ */
+export declare function eposPrintXmlErgebnis(layout: ReceiptLayout, options?: EposPrintXmlOptions): EposPrintErgebnis;
 /**
  * Epson-Drucker mit ePOS-Print direkt aus dem Browser ansprechen (ohne
  * Server-Umweg): POST an `https://<ip>/cgi-bin/epos/service.cgi`. Der Drucker
@@ -36,6 +73,10 @@ export interface EposDirectOptions {
     devid?: string;
     /** Papier des Druckers -- bestimmt das Raster; Vorgabe: das des Layouts. */
     papier?: PosPaperSize;
+    /** Feste QR-Modulgroesse; siehe [EposPrintXmlOptions.qrBreite]. */
+    qrBreite?: number;
+    /** Deckel fuer die gerechnete QR-Modulgroesse; siehe [EposPrintXmlOptions.qrGroesse]. */
+    qrGroesse?: QrModulGroesse;
     timeoutMs?: number;
 }
 export interface EposResponse {