@kreiseck/kasseneck-api 0.10.0 → 0.11.0

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

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QR_DRUCK_PUNKTE = exports.QR_HOECHST_PUNKTE = exports.QR_AUSNAHME_PUNKTE = exports.QR_MINDEST_PUNKTE = exports.QR_RUHEZONE_MODULE = exports.QR_MODUL_DECKEL = void 0;
+exports.qrModulAnzahl = qrModulAnzahl;
+exports.qrGroesseBerechnen = qrGroesseBerechnen;
+exports.qrGroesseFuer = qrGroesseFuer;
+/** Groesste Modulgroesse in Druckpunkten, die der jeweilige Deckel zulaesst. */
+exports.QR_MODUL_DECKEL = {
+    auto: 4,
+    klein: 4,
+    mittel: 6,
+    gross: 8,
+};
+// --------------------------------------------------------------- Konstanten
+/** Ruhezone je Seite, in Modulen (QR-Norm). */
+exports.QR_RUHEZONE_MODULE = 4;
+/** Untergrenze: 4 Punkte sind bei 203 dpi rund 0,5 mm je Modul. */
+exports.QR_MINDEST_PUNKTE = 4;
+/** Ausnahme, wenn `QR_MINDEST_PUNKTE` nicht passt — gemeldet, nicht still. */
+exports.QR_AUSNAHME_PUNKTE = 3;
+/** Obergrenze des Druckbefehls in diesem Stack (`GS ( k` Funktion 167: 1..8). */
+exports.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.
+ */
+exports.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.
+ */
+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.
+ */
+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 = exports.QR_MODUL_DECKEL[groesse];
+    if (roh === undefined) {
+        throw new Error(`Unbekannte QR-Modulgroesse: ${String(groesse)}`);
+    }
+    const gesamtModule = moduleAnzahl + exports.QR_RUHEZONE_MODULE * 2;
+    const passend = Math.floor(papierbreitePunkte / gesamtModule);
+    if (passend < exports.QR_AUSNAHME_PUNKTE) {
+        return { punkte: null, module: moduleAnzahl, breitePunkte: 0, unterMindestmass: false, passt: false };
+    }
+    const deckel = Math.min(Math.max(roh, exports.QR_AUSNAHME_PUNKTE), exports.QR_HOECHST_PUNKTE);
+    const punkte = passend < exports.QR_MINDEST_PUNKTE ? exports.QR_AUSNAHME_PUNKTE : Math.min(passend, deckel);
+    return {
+        punkte: punkte,
+        module: moduleAnzahl,
+        breitePunkte: gesamtModule * punkte,
+        unterMindestmass: punkte < exports.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).
+ */
+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/cjs/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 {

package/dist/cjs/receipt/epos.js

@@ -3,19 +3,71 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EposConnectionError = void 0;
 exports.eposXmlEscape = eposXmlEscape;
 exports.eposPrintXml = eposPrintXml;
+exports.eposPrintXmlErgebnis = eposPrintXmlErgebnis;
 exports.eposServiceUrl = eposServiceUrl;
 exports.eposSoapEnvelope = eposSoapEnvelope;
 exports.eposParseResponse = eposParseResponse;
 exports.eposDirectPrint = eposDirectPrint;
 exports.eposDirectStatus = eposDirectStatus;
+const index_js_1 = require("../printing/index.js");
 const grid_js_1 = require("./grid.js");
 function eposXmlEscape(text) {
     return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
 }
 const NS = 'http://www.epson-pos.com/schemas/2011/03/epos-print';
+/** Nur das XML; wer die QR-Meldungen braucht, nimmt [eposPrintXmlErgebnis]. */
 function eposPrintXml(layout, options = {}) {
+    return eposPrintXmlErgebnis(layout, options).xml;
+}
+/**
+ * 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.
+ */
+function eposPrintXmlErgebnis(layout, options = {}) {
     const grid = (0, grid_js_1.renderReceiptGrid)(layout, { zeichen: options.zeichen ?? grid_js_1.ZEICHEN_JE_PAPIER[layout.paperSize] });
-    const qrBreite = Math.min(16, Math.max(3, Math.floor(options.qrBreite ?? 6)));
+    const deckel = options.qrGroesse ?? 'mittel';
+    const fest = options.qrBreite === undefined
+        ? null
+        : Math.min(16, Math.max(3, Math.floor(options.qrBreite)));
+    let qrFehler = null;
+    let qrAusweich = null;
+    /**
+     * Die Breite fuer eine QR-Zeile, oder `null` -- dann geht **kein** Symbol
+     * hinaus: ein Element, von dem man weiss, dass der Drucker es weglaesst,
+     * taeuscht nur einen Ausdruck vor.
+     *
+     * Eine leere Nutzlast geht unveraendert den Bestandsweg (Deckel), wie am
+     * ESC/POS-Befehl: sie ist ein Datenfehler, kein Papierfehler.
+     */
+    const qrBreiteFuer = (nutzlast) => {
+        if (fest !== null)
+            return fest;
+        if (nutzlast === '')
+            return index_js_1.QR_MODUL_DECKEL[deckel];
+        const mass = (0, index_js_1.qrGroesseFuer)({
+            nutzlast,
+            papierbreitePunkte: index_js_1.QR_DRUCK_PUNKTE[layout.paperSize],
+            groesse: deckel,
+        });
+        if (!mass.passt) {
+            qrFehler =
+                `QR mit ${mass.module} Modulen ist fuer ${layout.paperSize === 'mm58' ? 58 : 80} mm ` +
+                    `(${index_js_1.QR_DRUCK_PUNKTE[layout.paperSize]} Punkte) zu breit`;
+            return null;
+        }
+        if (mass.unterMindestmass) {
+            qrAusweich =
+                `QR mit ${mass.module} Modulen passt nur mit ${String(mass.punkte)} Punkten ` +
+                    `je Modul -- unter dem Mindestmass von ${index_js_1.QR_MINDEST_PUNKTE}`;
+        }
+        return mass.punkte;
+    };
     const out = [];
     out.push(`<epos-print xmlns="${NS}">`);
     out.push('<text lang="de"/>');
@@ -27,11 +79,15 @@ function eposPrintXml(layout, options = {}) {
             case 'space':
                 out.push('<feed line="1"/>');
                 break;
-            case 'qr':
+            case 'qr': {
+                const breite = qrBreiteFuer(z.qr ?? '');
+                if (breite === null)
+                    break;
                 out.push('<text align="center"/>');
-                out.push(`<symbol type="qrcode_model_2" level="level_m" width="${qrBreite}" height="0" size="0">${eposXmlEscape(z.qr ?? '')}</symbol>`);
+                out.push(`<symbol type="qrcode_model_2" level="level_m" width="${breite}" height="0" size="0">${eposXmlEscape(z.qr ?? '')}</symbol>`);
                 out.push('<text align="left"/>');
                 break;
+            }
             case 'banner':
                 out.push(`<text width="1" height="2" reverse="${z.ton === 'warnung' ? 'true' : 'false'}" em="true">${eposXmlEscape(z.text)}&#10;</text>`);
                 out.push('<text width="1" height="1" reverse="false" em="false"/>');
@@ -51,7 +107,7 @@ function eposPrintXml(layout, options = {}) {
         out.push('<cut type="feed"/>');
     }
     out.push('</epos-print>');
-    return out.join('\n');
+    return { xml: out.join('\n'), qrFehler, qrAusweich };
 }
 const EPOS_DEVID_VORGABE = 'local_printer';
 function eposServiceUrl(ip, devid = EPOS_DEVID_VORGABE, timeoutMs = 10000) {
@@ -159,7 +215,12 @@ async function eposDirectSend(innerXml, o, fetchFn) {
 /** Beleg direkt drucken; wirft bei Netz-/Zertifikatsproblemen, sonst die Drucker-Antwort. */
 function eposDirectPrint(layout, o, fetchFn = fetch) {
     const papier = o.papier ?? layout.paperSize;
-    return eposDirectSend(eposPrintXml({ ...layout, paperSize: papier }, { zeichen: grid_js_1.ZEICHEN_JE_PAPIER[papier] }), o, fetchFn);
+    const xmlOptionen = { zeichen: grid_js_1.ZEICHEN_JE_PAPIER[papier] };
+    if (o.qrBreite !== undefined)
+        xmlOptionen.qrBreite = o.qrBreite;
+    if (o.qrGroesse !== undefined)
+        xmlOptionen.qrGroesse = o.qrGroesse;
+    return eposDirectSend(eposPrintXml({ ...layout, paperSize: papier }, xmlOptionen), o, fetchFn);
 }
 /** Verbindungstest: leeres Dokument, druckt nichts, liefert den Druckerstatus. */
 function eposDirectStatus(o, fetchFn = fetch) {

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

@@ -1,4 +1,4 @@
 export { type LayoutAlign, type LayoutColumn, type LayoutTextLine, type LayoutColumnsLine, type LayoutRuleLine, type LayoutSpaceLine, type LayoutQrLine, type LayoutLine, type ReceiptLayout, type BuildReceiptLayoutOptions, buildReceiptLayout, receiptSignatureFailed, receiptSignatureIsTest, receiptIsZero, receiptAmountsAreZero, receiptIsSmallBusinessConsistent, receiptZdaText, type Pruefangaben, AKTUELLES_REGELWERK, type LayoutBannerLine, type LayoutRegelwerk, SMALL_BUSINESS_NOTICE, formatCents, } from './layout.js';
-export { type EscPosLayoutOptions, escPosLayoutBytes } from './layout-escpos.js';
+export { type EscPosLayoutOptions, type EscPosLayoutErgebnis, type QrPrintMode, escPosLayoutBytes, escPosLayoutErgebnis, } from './layout-escpos.js';
 export { type GridLine, type GridLineKind, type ReceiptGrid, type RenderReceiptGridOptions, renderReceiptGrid, gridSpaltenBreiten, gridAlsText, ZEICHEN_JE_PAPIER, } from './grid.js';
-export { type EposPrintXmlOptions, type EposDirectOptions, type EposResponse, EposConnectionError, eposPrintXml, eposXmlEscape, eposServiceUrl, eposSoapEnvelope, eposParseResponse, eposDirectPrint, eposDirectStatus } from './epos.js';
+export { type EposPrintXmlOptions, type EposPrintErgebnis, type EposDirectOptions, type EposResponse, EposConnectionError, eposPrintXml, eposPrintXmlErgebnis, eposXmlEscape, eposServiceUrl, eposSoapEnvelope, eposParseResponse, eposDirectPrint, eposDirectStatus } from './epos.js';

package/dist/cjs/receipt/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.eposDirectStatus = exports.eposDirectPrint = exports.eposParseResponse = exports.eposSoapEnvelope = exports.eposServiceUrl = exports.eposXmlEscape = exports.eposPrintXml = exports.EposConnectionError = exports.ZEICHEN_JE_PAPIER = exports.gridAlsText = exports.gridSpaltenBreiten = exports.renderReceiptGrid = exports.escPosLayoutBytes = exports.formatCents = exports.SMALL_BUSINESS_NOTICE = exports.AKTUELLES_REGELWERK = exports.receiptZdaText = exports.receiptIsSmallBusinessConsistent = exports.receiptAmountsAreZero = exports.receiptIsZero = exports.receiptSignatureIsTest = exports.receiptSignatureFailed = exports.buildReceiptLayout = void 0;
+exports.eposDirectStatus = exports.eposDirectPrint = exports.eposParseResponse = exports.eposSoapEnvelope = exports.eposServiceUrl = exports.eposXmlEscape = exports.eposPrintXmlErgebnis = exports.eposPrintXml = exports.EposConnectionError = exports.ZEICHEN_JE_PAPIER = exports.gridAlsText = exports.gridSpaltenBreiten = exports.renderReceiptGrid = exports.escPosLayoutErgebnis = exports.escPosLayoutBytes = exports.formatCents = exports.SMALL_BUSINESS_NOTICE = exports.AKTUELLES_REGELWERK = exports.receiptZdaText = exports.receiptIsSmallBusinessConsistent = exports.receiptAmountsAreZero = exports.receiptIsZero = exports.receiptSignatureIsTest = exports.receiptSignatureFailed = exports.buildReceiptLayout = void 0;
 var layout_js_1 = require("./layout.js");
 Object.defineProperty(exports, "buildReceiptLayout", { enumerable: true, get: function () { return layout_js_1.buildReceiptLayout; } });
 Object.defineProperty(exports, "receiptSignatureFailed", { enumerable: true, get: function () { return layout_js_1.receiptSignatureFailed; } });
@@ -14,6 +14,7 @@ Object.defineProperty(exports, "SMALL_BUSINESS_NOTICE", { enumerable: true, get:
 Object.defineProperty(exports, "formatCents", { enumerable: true, get: function () { return layout_js_1.formatCents; } });
 var layout_escpos_js_1 = require("./layout-escpos.js");
 Object.defineProperty(exports, "escPosLayoutBytes", { enumerable: true, get: function () { return layout_escpos_js_1.escPosLayoutBytes; } });
+Object.defineProperty(exports, "escPosLayoutErgebnis", { enumerable: true, get: function () { return layout_escpos_js_1.escPosLayoutErgebnis; } });
 var grid_js_1 = require("./grid.js");
 Object.defineProperty(exports, "renderReceiptGrid", { enumerable: true, get: function () { return grid_js_1.renderReceiptGrid; } });
 Object.defineProperty(exports, "gridSpaltenBreiten", { enumerable: true, get: function () { return grid_js_1.gridSpaltenBreiten; } });
@@ -22,6 +23,7 @@ Object.defineProperty(exports, "ZEICHEN_JE_PAPIER", { enumerable: true, get: fun
 var epos_js_1 = require("./epos.js");
 Object.defineProperty(exports, "EposConnectionError", { enumerable: true, get: function () { return epos_js_1.EposConnectionError; } });
 Object.defineProperty(exports, "eposPrintXml", { enumerable: true, get: function () { return epos_js_1.eposPrintXml; } });
+Object.defineProperty(exports, "eposPrintXmlErgebnis", { enumerable: true, get: function () { return epos_js_1.eposPrintXmlErgebnis; } });
 Object.defineProperty(exports, "eposXmlEscape", { enumerable: true, get: function () { return epos_js_1.eposXmlEscape; } });
 Object.defineProperty(exports, "eposServiceUrl", { enumerable: true, get: function () { return epos_js_1.eposServiceUrl; } });
 Object.defineProperty(exports, "eposSoapEnvelope", { enumerable: true, get: function () { return epos_js_1.eposSoapEnvelope; } });

package/dist/cjs/receipt/layout-escpos.d.ts

@@ -1,4 +1,4 @@
-import { type PosCodeTable, type PosCutMode, type PosPaperSize, type QrCorrection, type QrSize } from '../printing/index.js';
+import { type PosCodeTable, type PosCutMode, type PosPaperSize, type QrCorrection, type QrMatrix, type QrModulGroesse, type QrSize } from '../printing/index.js';
 import type { ReceiptLayout } from './layout.js';
 /**
  * Bruecke vom Layout-Modell zu ESC/POS-Bytes — der Bondrucker-Ausgabeweg.
@@ -14,6 +14,20 @@ import type { ReceiptLayout } from './layout.js';
  * ein unerwartetes Zeichen darin soll darum auffallen und nicht still
  * verfaelscht werden.
  */
+/**
+ * Wie der Beleg-QR auf das Papier kommt — Zwilling von `QrPrintMode`
+ * (kasseneck_api/lib/enums/qr_print_mode.dart).
+ *
+ * - `native`      — der Druckbefehl `GS ( k`; der Drucker zeichnet selbst.
+ *                   Ohne Modellbefehl, also byteidentisch zum Bestand.
+ * - `nativeModel1` — derselbe Befehl mit ausdruecklicher Wahl von **Modell 1**
+ *                   (`GS ( k 04 00 31 41 31 00`). Fuer guenstige Geraete, die
+ *                   nur diesen aelteren Symboltyp beherrschen; belegt ist
+ *                   eines, das bei Modell 2 unter dem Code eine "0" ausgibt.
+ * - `imageRaster` — der QR als Rasterbild. Braucht ein Raster vom Aufrufer
+ *                   (`qrMatrix`), weil dieses Paket keine QR-Codes rechnet.
+ */
+export type QrPrintMode = 'native' | 'nativeModel1' | 'imageRaster';
 export interface EscPosLayoutOptions {
     /** Papierbreite; Vorgabe ist die des Layouts (dessen Spaltenbreiten daran haengen). */
     paperSize?: PosPaperSize;
@@ -21,10 +35,38 @@ export interface EscPosLayoutOptions {
     codeTable?: PosCodeTable | null;
     /** Papierschnitt am Ende: `true` (voll), `'partial'` oder `false`. Vorgabe `true`. */
     cut?: boolean | PosCutMode;
-    /** Modulgroesse des QR-Codes. */
+    /**
+     * Feste Modulgroesse des QR-Codes. Gesetzt schaltet sie die Rechnung ab —
+     * dann passt der Aufrufer selbst auf, dass das Symbol aufs Papier geht.
+     */
     qrSize?: QrSize;
     /** Fehlerkorrekturstufe des QR-Codes. */
     qrCorrection?: QrCorrection;
+    /** Deckel fuer die gerechnete Modulgroesse; Vorgabe `auto`. */
+    qrGroesse?: QrModulGroesse;
+    /** Druckweg des QR; Vorgabe `native` (der Bestandsweg). */
+    qrModus?: QrPrintMode;
+    /**
+     * Raster fuer den Bildweg — ohne das gibt es keinen Notausgang.
+     *
+     * Dieses Paket rechnet keine QR-Codes und verarbeitet keine Bilder (siehe
+     * Kopf von `layout.ts`); der Aufrufer bringt das fertige Raster mit, etwa
+     * aus der QR-Bibliothek, die er ohnehin fuer den Bildschirm benutzt.
+     */
+    qrMatrix?: (nutzlast: string) => QrMatrix;
+}
+/**
+ * Der Bytestrom **samt** dem, was dem QR unterwegs zugestossen ist.
+ *
+ * Zwilling von `KeckPrintResult`: `qrFehler` heisst "Beleg ohne QR,
+ * nachdrucken oder elektronisch ausgeben", `qrAusweich` heisst "gedruckt,
+ * aber der eingestellte Weg taugt fuer dieses Geraet nicht" — das eine gehoert
+ * dem Kunden gesagt, das andere dem Chef.
+ */
+export interface EscPosLayoutErgebnis {
+    bytes: Uint8Array;
+    qrFehler: string | null;
+    qrAusweich: string | null;
 }
 /**
  * Bytes fuer den Bondrucker -- **aus dem Zeichenraster** ([renderReceiptGrid]):
@@ -33,3 +75,9 @@ export interface EscPosLayoutOptions {
  * zeigt, druckt der Drucker (Monospace, Font A: 32/48 Zeichen).
  */
 export declare function escPosLayoutBytes(layout: ReceiptLayout, options?: EscPosLayoutOptions): Uint8Array;
+/**
+ * Wie [escPosLayoutBytes], gibt aber zusaetzlich zurueck, was dem QR
+ * zugestossen ist. Die Bytes sind dieselben; wer die Meldungen braucht, nimmt
+ * diesen Weg.
+ */
+export declare function escPosLayoutErgebnis(layout: ReceiptLayout, options?: EscPosLayoutOptions): EscPosLayoutErgebnis;

package/dist/cjs/receipt/layout-escpos.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.escPosLayoutBytes = escPosLayoutBytes;
+exports.escPosLayoutErgebnis = escPosLayoutErgebnis;
 const index_js_1 = require("../printing/index.js");
 const grid_js_1 = require("./grid.js");
 /**
@@ -29,6 +30,14 @@ function druckbaresLayout(layout) {
  * zeigt, druckt der Drucker (Monospace, Font A: 32/48 Zeichen).
  */
 function escPosLayoutBytes(layout, options = {}) {
+    return escPosLayoutErgebnis(layout, options).bytes;
+}
+/**
+ * Wie [escPosLayoutBytes], gibt aber zusaetzlich zurueck, was dem QR
+ * zugestossen ist. Die Bytes sind dieselben; wer die Meldungen braucht, nimmt
+ * diesen Weg.
+ */
+function escPosLayoutErgebnis(layout, options = {}) {
     const paperSize = options.paperSize ?? layout.paperSize;
     const dokumentOptionen = { paperSize };
     if (options.codeTable !== undefined) {
@@ -36,11 +45,59 @@ function escPosLayoutBytes(layout, options = {}) {
     }
     const doc = (0, index_js_1.createEscPosDocument)(dokumentOptionen);
     (0, index_js_1.escPosReset)(doc);
+    const modus = options.qrModus ?? 'native';
     const qrOptionen = { align: 'center' };
     if (options.qrSize !== undefined)
         qrOptionen.size = options.qrSize;
     if (options.qrCorrection !== undefined)
         qrOptionen.correction = options.qrCorrection;
+    if (options.qrGroesse !== undefined)
+        qrOptionen.groesse = options.qrGroesse;
+    if (modus === 'nativeModel1')
+        qrOptionen.modell1 = true;
+    if (modus === 'imageRaster' && options.qrMatrix === undefined) {
+        throw new Error("qrModus 'imageRaster' braucht ein qrMatrix -- dieses Paket rastert nicht selbst");
+    }
+    const rasterOptionen = { align: 'center' };
+    if (options.qrGroesse !== undefined)
+        rasterOptionen.groesse = options.qrGroesse;
+    /**
+     * Eine QR-Zeile des Rasters. Hier sitzt der **Notausgang**: passt das Symbol
+     * nativ auch mit der Ausnahmegroesse nicht aufs Papier, druckt der Drucker
+     * es GAR NICHT -- er schneidet nicht ab, er laesst weg. Ein Pflichtbeleg
+     * ohne QR ist der schlechteste aller Ausgaenge, also geht der QR dann als
+     * Bild hinaus, und der Aufrufer erfaehrt es ueber `qrAusweich`.
+     *
+     * Ohne `qrMatrix` gibt es diesen Weg nicht -- dann bleibt nur die Meldung
+     * `qrFehler` aus `escPosQrCode`, und der Beleg geht ohne QR hinaus.
+     */
+    const qrZeile = (nutzlast) => {
+        const raster = options.qrMatrix;
+        if (nutzlast !== '' && raster !== undefined) {
+            if (modus === 'imageRaster') {
+                (0, index_js_1.escPosQrRaster)(doc, raster(nutzlast), rasterOptionen);
+                return;
+            }
+            // Feste `qrSize` heisst: der Aufrufer weiss, was er tut -- dann wird
+            // weder gerechnet noch ausgewichen.
+            if (options.qrSize === undefined) {
+                const mass = (0, index_js_1.qrGroesseFuer)({
+                    nutzlast,
+                    papierbreitePunkte: index_js_1.QR_DRUCK_PUNKTE[paperSize],
+                    groesse: options.qrGroesse ?? 'auto',
+                });
+                if (!mass.passt) {
+                    doc.qrAusweich =
+                        `QR mit ${mass.module} Modulen passt nativ nicht auf ` +
+                            `${paperSize === 'mm58' ? 58 : 80} mm (${index_js_1.QR_DRUCK_PUNKTE[paperSize]} Punkte) ` +
+                            `-- als Bild gedruckt`;
+                    (0, index_js_1.escPosQrRaster)(doc, raster(nutzlast), rasterOptionen);
+                    return;
+                }
+            }
+        }
+        (0, index_js_1.escPosQrCode)(doc, nutzlast, qrOptionen);
+    };
     const grid = (0, grid_js_1.renderReceiptGrid)(druckbaresLayout(layout), { zeichen: grid_js_1.ZEICHEN_JE_PAPIER[paperSize] });
     for (const zeile of grid.lines) {
         switch (zeile.kind) {
@@ -48,7 +105,7 @@ function escPosLayoutBytes(layout, options = {}) {
                 (0, index_js_1.escPosFeed)(doc, 1);
                 break;
             case 'qr':
-                (0, index_js_1.escPosQrCode)(doc, zeile.qr ?? '', qrOptionen);
+                qrZeile(zeile.qr ?? '');
                 break;
             case 'banner': {
                 // Belegart/Warnung: fett zwischen zwei Volllinien — derselbe Rahmen-
@@ -68,5 +125,5 @@ function escPosLayoutBytes(layout, options = {}) {
     if (options.cut !== false) {
         (0, index_js_1.escPosCut)(doc, options.cut === 'partial' ? 'partial' : 'full');
     }
-    return (0, index_js_1.escPosBytes)(doc);
+    return { bytes: (0, index_js_1.escPosBytes)(doc), qrFehler: doc.qrFehler, qrAusweich: doc.qrAusweich };
 }

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 {};