@kreiseck/kasseneck-api 1.11.0 → 1.12.0

package/dist/cjs/models/receipt-item.d.ts

@@ -36,7 +36,7 @@ export interface ReceiptItem {
      * negative Entgeltminderungen je Steuersatz; die Kennzeichnung steuert nur
      * die Bon-Darstellung (Summenzeile mit Aufteilung), nie die Beträge.
      */
-    kind?: 'tip' | 'discount';
+    kind?: 'tip' | 'discount' | 'voucher' | 'voucher_float';
     /** Empfaenger der Trinkgeld-Position; `null` = nicht zugeordnet. */
     recipient?: TipRecipient | null;
     /** Zahlart der Trinkgeld-Position (kann von der des Belegs abweichen). */
@@ -73,6 +73,14 @@ export interface TipRecipient {
 export declare function isTipItem(item: ReceiptItem | ReceiptItemPayloadRead): boolean;
 /** Rabatt-Position? Die eine Erkennungsstelle — niemand prueft `kind` selbst. */
 export declare function isDiscountItem(item: ReceiptItem | ReceiptItemPayloadRead): boolean;
+/**
+ * Gutschein-Position (Server, neue Gutscheinform)? `voucher` ist eine
+ * Einloesung oder ein Verkauf mit Umsatzsteuer-Wirkung, siehe
+ * [isVoucherFloatItem] fuer den durchlaufenden Posten.
+ */
+export declare function isVoucherItem(item: ReceiptItem | ReceiptItemPayloadRead): boolean;
+/** Gutschein-Position als durchlaufender Posten (Mehrzweck: Verkauf, Auszahlung)? */
+export declare function isVoucherFloatItem(item: ReceiptItem | ReceiptItemPayloadRead): boolean;
 /**
  * Nutzlast-Form, die dieses Paket **schreibt** (v2):
  * `{ name, quantity, unitPriceCents, vatRate }`.
@@ -82,8 +90,8 @@ export interface ReceiptItemPayload {
     quantity: number;
     unitPriceCents: number;
     vatRate: number;
-    /** Trinkgeld-/Rabatt-Kennzeichnung, siehe [ReceiptItem.kind]. */
-    kind?: 'tip' | 'discount';
+    /** Trinkgeld-/Rabatt-/Gutschein-Kennzeichnung, siehe [ReceiptItem.kind]. */
+    kind?: 'tip' | 'discount' | 'voucher' | 'voucher_float';
     recipient?: TipRecipient | null;
     paymentMethod?: string;
     receivedImmediately?: boolean;

package/dist/cjs/models/receipt-item.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isTipItem = isTipItem;
 exports.isDiscountItem = isDiscountItem;
+exports.isVoucherItem = isVoucherItem;
+exports.isVoucherFloatItem = isVoucherFloatItem;
 exports.toReceiptItemPayload = toReceiptItemPayload;
 exports.fromReceiptItemPayload = fromReceiptItemPayload;
 exports.receiptItemTotalCents = receiptItemTotalCents;
@@ -18,6 +20,18 @@ function isTipItem(item) {
 function isDiscountItem(item) {
     return item != null && item.kind === 'discount';
 }
+/**
+ * Gutschein-Position (Server, neue Gutscheinform)? `voucher` ist eine
+ * Einloesung oder ein Verkauf mit Umsatzsteuer-Wirkung, siehe
+ * [isVoucherFloatItem] fuer den durchlaufenden Posten.
+ */
+function isVoucherItem(item) {
+    return item != null && item.kind === 'voucher';
+}
+/** Gutschein-Position als durchlaufender Posten (Mehrzweck: Verkauf, Auszahlung)? */
+function isVoucherFloatItem(item) {
+    return item != null && item.kind === 'voucher_float';
+}
 function toReceiptItemPayload(item) {
     // Schreibpfad bleibt streng: ein unaufgeloester (unbekannter) Steuersatz
     // darf nicht unbesehen wieder hinausgehen.
@@ -46,6 +60,11 @@ function toReceiptItemPayload(item) {
     // am Bon wieder als gewoehnliche Warenzeile mit "1 x" an.
     if (item.kind === 'discount')
         nutzlast.kind = 'discount';
+    // Gutschein-Positionen (vom Server) reisen mit: der Cache der Kasse schreibt
+    // gelesene Belege wieder, und ein Wunsch an den Server traegt sie nie
+    // (createReceipt weist sie als voucher_invalid ab).
+    if (item.kind === 'voucher' || item.kind === 'voucher_float')
+        nutzlast.kind = item.kind;
     // Artikel-Verweis reist mit (Erloesgruppen im Bericht); leere Werte nicht.
     if (item.articleId != null && item.articleId !== '')
         nutzlast.articleId = item.articleId;
@@ -90,7 +109,9 @@ function fromReceiptItemPayload(payload) {
             }
             : payload.kind === 'discount'
                 ? { kind: 'discount' }
-                : {}),
+                : payload.kind === 'voucher' || payload.kind === 'voucher_float'
+                    ? { kind: payload.kind }
+                    : {}),
         // Artikel-Verweis erhalten (Storno-Spiegelung schreibt ihn wieder mit).
         ...(typeof payload.articleId === 'string' && payload.articleId !== '' ? { articleId: payload.articleId } : {}),
         // Lager: Bezug und Rueckgabe-Wahl einer Storno-Zeile (nur gelesen; ein

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

@@ -143,11 +143,41 @@ export declare function readRegistrationInfo(roh: {
     cardRegisteredAt?: unknown;
     cashregisterRegisteredAt?: unknown;
 }): RegistrationInfo;
+/**
+ * Vorzeichen der Wertgutscheine am Beleg: am Storno-Beleg -1, sonst 1.
+ *
+ * Das Backend spiegelt Wertgutscheine beim Vollstorno mit UNVERAENDERTER
+ * `action` und positivem Wert (storno-core.stornoVouchers); der Fluss dreht
+ * sich am Storno um (zahlungen-core.wertgutscheinFlussCents, hier
+ * `receiptDueCents`): ein verkaufter Gutschein wird zurueckgezahlt, ein
+ * eingeloester mindert die Rueckzahlung.
+ */
+export declare function receiptValueVoucherSign(receipt: Receipt): 1 | -1;
 /**
  * Zwischensumme in **Cent** — Positionen plus verkaufte Wertgutscheine minus
  * eingeloeste Promotionsgutscheine. Wertgutschein-Einloesungen wirken erst auf
  * [receiptSumCents], nicht hier (siehe Dart-Vorbild `subSumCents`/`sumCents`).
+ * Am Storno-Beleg zaehlen Wertgutscheine mit umgekehrtem Vorzeichen
+ * ([receiptValueVoucherSign]), und ein gespiegelter Promotionsgutschein
+ * mindert nichts: den Rabatt nimmt der Server dort ueber Ausgleichspositionen
+ * (`kind: 'discount'`) zurueck, und belegToepfe verteilt einen Promo-Eintrag
+ * nur auf eine positive Topfsumme, die ein Storno nie hat.
+ *
+ * Gutscheine der neuen Form (Spec 2026-10-14): ihr Betrag steht als Position
+ * (`kind: 'voucher'` bei Einzweck/Leistung, `'voucher_float'` im 0-%-Topf) und
+ * zaehlt hier schon mit den Positionen. Ein Eintrag mit `zeroRateBucket`
+ * (Server: `imNullTopf`, Mehrzweck-Verkauf ab dem Stichtag, Auszahlung) zaehlt
+ * darum nicht noch einmal -- sonst stuende der Betrag doppelt am Bon
+ * (Vorfall 16.10.2026: Verkauf ueber 30 € mit „Gesamt 60,00“). Eintraege der
+ * Arten `single_purpose`/`service` tragen keinen Fluss (wie
+ * gutschein-beleg.zahlbetrag, das nur `value`/`promo` an den Fluss gibt).
  */
 export declare function receiptSubSumCents(receipt: Receipt): number;
-/** Gesamtsumme in **Cent** — Zwischensumme minus eingeloeste Wertgutscheine. */
+/**
+ * Gesamtsumme in **Cent** — Zwischensumme minus eingeloeste Wertgutscheine
+ * (am Storno-Beleg plus, siehe [receiptValueVoucherSign]). Zwilling von
+ * zahlungen-core.wertgutscheinFlussCents: eine Auszahlung (`payout`) eines
+ * Wertgutscheins ohne `zeroRateBucket` mindert wie eine Einloesung; mit
+ * `zeroRateBucket` steht sie als Position und zaehlt nur dort.
+ */
 export declare function receiptSumCents(receipt: Receipt): number;

package/dist/cjs/models/receipt.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.toReceiptPayload = toReceiptPayload;
 exports.fromReceiptPayload = fromReceiptPayload;
 exports.readRegistrationInfo = readRegistrationInfo;
+exports.receiptValueVoucherSign = receiptValueVoucherSign;
 exports.receiptSubSumCents = receiptSubSumCents;
 exports.receiptSumCents = receiptSumCents;
 const index_js_1 = require("../enums/index.js");
@@ -134,29 +135,68 @@ function gueltigeRueckzahlungen(rueckzahlungen) {
     }
     return raus;
 }
+/**
+ * Vorzeichen der Wertgutscheine am Beleg: am Storno-Beleg -1, sonst 1.
+ *
+ * Das Backend spiegelt Wertgutscheine beim Vollstorno mit UNVERAENDERTER
+ * `action` und positivem Wert (storno-core.stornoVouchers); der Fluss dreht
+ * sich am Storno um (zahlungen-core.wertgutscheinFlussCents, hier
+ * `receiptDueCents`): ein verkaufter Gutschein wird zurueckgezahlt, ein
+ * eingeloester mindert die Rueckzahlung.
+ */
+function receiptValueVoucherSign(receipt) {
+    const typ = typeof receipt.receiptType === 'object' ? receipt.receiptType.value : receipt.receiptType;
+    return typ === index_js_1.ReceiptType.cancellation.value ? -1 : 1;
+}
 /**
  * Zwischensumme in **Cent** — Positionen plus verkaufte Wertgutscheine minus
  * eingeloeste Promotionsgutscheine. Wertgutschein-Einloesungen wirken erst auf
  * [receiptSumCents], nicht hier (siehe Dart-Vorbild `subSumCents`/`sumCents`).
+ * Am Storno-Beleg zaehlen Wertgutscheine mit umgekehrtem Vorzeichen
+ * ([receiptValueVoucherSign]), und ein gespiegelter Promotionsgutschein
+ * mindert nichts: den Rabatt nimmt der Server dort ueber Ausgleichspositionen
+ * (`kind: 'discount'`) zurueck, und belegToepfe verteilt einen Promo-Eintrag
+ * nur auf eine positive Topfsumme, die ein Storno nie hat.
+ *
+ * Gutscheine der neuen Form (Spec 2026-10-14): ihr Betrag steht als Position
+ * (`kind: 'voucher'` bei Einzweck/Leistung, `'voucher_float'` im 0-%-Topf) und
+ * zaehlt hier schon mit den Positionen. Ein Eintrag mit `zeroRateBucket`
+ * (Server: `imNullTopf`, Mehrzweck-Verkauf ab dem Stichtag, Auszahlung) zaehlt
+ * darum nicht noch einmal -- sonst stuende der Betrag doppelt am Bon
+ * (Vorfall 16.10.2026: Verkauf ueber 30 € mit „Gesamt 60,00“). Eintraege der
+ * Arten `single_purpose`/`service` tragen keinen Fluss (wie
+ * gutschein-beleg.zahlbetrag, das nur `value`/`promo` an den Fluss gibt).
  */
 function receiptSubSumCents(receipt) {
+    const vz = receiptValueVoucherSign(receipt);
     let cents = receipt.items.reduce((acc, item) => acc + (0, receipt_item_js_1.receiptItemTotalCents)(item), 0);
     for (const voucher of receipt.vouchers) {
-        if (voucher.action === index_js_1.VoucherAction.redeem && voucher.type === index_js_1.VoucherType.promo) {
+        if (voucher.zeroRateBucket === true)
+            continue;
+        if (vz === 1 && voucher.action === index_js_1.VoucherAction.redeem && voucher.type === index_js_1.VoucherType.promo) {
             cents -= voucher.valueCents ?? 0;
         }
         if (voucher.action === index_js_1.VoucherAction.sell && voucher.type === index_js_1.VoucherType.value) {
-            cents += voucher.valueCents ?? 0;
+            cents += vz * (voucher.valueCents ?? 0);
         }
     }
     return cents;
 }
-/** Gesamtsumme in **Cent** — Zwischensumme minus eingeloeste Wertgutscheine. */
+/**
+ * Gesamtsumme in **Cent** — Zwischensumme minus eingeloeste Wertgutscheine
+ * (am Storno-Beleg plus, siehe [receiptValueVoucherSign]). Zwilling von
+ * zahlungen-core.wertgutscheinFlussCents: eine Auszahlung (`payout`) eines
+ * Wertgutscheins ohne `zeroRateBucket` mindert wie eine Einloesung; mit
+ * `zeroRateBucket` steht sie als Position und zaehlt nur dort.
+ */
 function receiptSumCents(receipt) {
+    const vz = receiptValueVoucherSign(receipt);
     let cents = receiptSubSumCents(receipt);
     for (const voucher of receipt.vouchers) {
-        if (voucher.action === index_js_1.VoucherAction.redeem && voucher.type === index_js_1.VoucherType.value) {
-            cents -= voucher.valueCents ?? 0;
+        if (voucher.zeroRateBucket === true || voucher.type !== index_js_1.VoucherType.value)
+            continue;
+        if (voucher.action === index_js_1.VoucherAction.redeem || voucher.action === index_js_1.VoucherAction.payout) {
+            cents -= vz * (voucher.valueCents ?? 0);
         }
     }
     return cents;

package/dist/cjs/models/voucher.d.ts

@@ -16,11 +16,41 @@ export interface Voucher {
     action: VoucherAction | string;
     type: VoucherType | string;
     valueCents?: number;
+    /** Neue Form: Betrag in Cent (Verkauf, Einloesung, Auszahlung). */
+    amountCents?: number;
+    /** Neue Form, Leistungsgutschein: verkaufter Artikel. */
+    articleId?: string;
+    /** Neue Form, Leistungsgutschein: Menge (Verkauf) bzw. eingeloeste Menge. */
+    quantity?: number;
+    /** Neue Form, Leistungsgutschein einloesen: Indizes der Belegpositionen. */
+    positions?: number[];
+    /** Neue Form, Auszahlung: Grund, 1 bis 200 Zeichen. */
+    reason?: string;
+    voucherType?: string;
+    voucherId?: string;
+    /** Letzte vier Zeichen des Codes; der Klartext steht nie am Beleg. */
+    codeSuffix?: string;
+    vatRateBp?: number;
+    article?: VoucherArticle;
+    balanceAfterCents?: number;
+    remainingQuantityAfter?: number;
+    taxedWith?: string;
+    exempt?: boolean;
+    zeroRateBucket?: boolean;
+}
+/** Artikel eines Leistungsgutscheins, wie der Server ihn am Beleg festhaelt. */
+export interface VoucherArticle {
+    id: string;
+    name: string;
+    vatRateBp: number;
+    priceCents: number;
 }
 /**
- * Nutzlast eines Gutscheins. Geschrieben wird nur `valueCents` (ganze Cent);
- * `value` (Euro) kommt nur beim Lesen vor: der Server legt es in seinen
- * Antworten daneben, gelesen wird es nur, wenn `valueCents` fehlt.
+ * Nutzlast eines Gutscheins. Altform: nur `valueCents` (ganze Cent); `value`
+ * (Euro) kommt nur beim Lesen vor: der Server legt es in seinen Antworten
+ * daneben, gelesen wird es nur, wenn `valueCents` fehlt. Neue Form: roh mit
+ * `amountCents` und den weiteren Feldern; gesetzte Feldern gehen hinaus,
+ * fehlende fehlen (kein `valueCents: null` an der neuen Form).
  * `name` und `code` gehen nur hinaus, wenn sie gesetzt sind.
  */
 export interface VoucherPayload {
@@ -29,8 +59,31 @@ export interface VoucherPayload {
     action: string;
     type: string;
     value?: number | null;
-    valueCents: number | null;
+    valueCents?: number | null;
+    amountCents?: number;
+    articleId?: string;
+    quantity?: number;
+    positions?: number[];
+    reason?: string;
+    voucherType?: string;
+    voucherId?: string;
+    codeSuffix?: string;
+    vatRateBp?: number;
+    article?: VoucherArticle;
+    balanceAfterCents?: number;
+    remainingQuantityAfter?: number;
+    taxedWith?: string;
+    exempt?: boolean;
+    zeroRateBucket?: boolean;
 }
+/** Arten der neuen Gutscheinform (die Altwerte sind `value` und `promo`). */
+export declare const NEUE_GUTSCHEINARTEN: readonly string[];
+/** Gehoert der Gutschein zur neuen Form (Art oder Aktion `payout`)? */
+export declare function isNewFormVoucher(voucher: Pick<Voucher, 'type' | 'action'>): boolean;
+/** Felder, die nur der Server setzt; an einem Wunsch sind sie `voucher_invalid`. */
+export declare const GUTSCHEIN_SERVERFELDER: readonly ["voucherId", "codeSuffix", "zeroRateBucket", "voucherType"];
+/** Welche Serverfelder tragt der Gutschein (leere Liste = keines)? */
+export declare function voucherServerFields(voucher: Voucher): string[];
 export declare function toVoucherPayload(voucher: Voucher): VoucherPayload;
 /**
  * Ist der Gutschein an das Backend sendbar? Zwilling von `KeckVoucher.isValid`

package/dist/cjs/models/voucher.js

@@ -1,18 +1,54 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.GUTSCHEIN_SERVERFELDER = exports.NEUE_GUTSCHEINARTEN = void 0;
+exports.isNewFormVoucher = isNewFormVoucher;
+exports.voucherServerFields = voucherServerFields;
 exports.toVoucherPayload = toVoucherPayload;
 exports.voucherIsValid = voucherIsValid;
 exports.fromVoucherPayload = fromVoucherPayload;
 const index_js_1 = require("../enums/index.js");
 const money_js_1 = require("../money.js");
 const enum_payload_js_1 = require("./enum-payload.js");
+/** Arten der neuen Gutscheinform (die Altwerte sind `value` und `promo`). */
+exports.NEUE_GUTSCHEINARTEN = [
+    index_js_1.VoucherType.multi_purpose,
+    index_js_1.VoucherType.single_purpose,
+    index_js_1.VoucherType.service,
+    index_js_1.VoucherType.promotion,
+];
+/** Gehoert der Gutschein zur neuen Form (Art oder Aktion `payout`)? */
+function isNewFormVoucher(voucher) {
+    return exports.NEUE_GUTSCHEINARTEN.includes(voucher.type) || voucher.action === index_js_1.VoucherAction.payout;
+}
+/** Felder, die nur der Server setzt; an einem Wunsch sind sie `voucher_invalid`. */
+exports.GUTSCHEIN_SERVERFELDER = ['voucherId', 'codeSuffix', 'zeroRateBucket', 'voucherType'];
+/** Welche Serverfelder tragt der Gutschein (leere Liste = keines)? */
+function voucherServerFields(voucher) {
+    return exports.GUTSCHEIN_SERVERFELDER.filter((feld) => voucher[feld] != null);
+}
+const NEUE_FELDER = [
+    'amountCents', 'articleId', 'quantity', 'positions', 'reason', 'voucherType', 'voucherId', 'codeSuffix',
+    'vatRateBp', 'article', 'balanceAfterCents', 'remainingQuantityAfter', 'taxedWith', 'exempt', 'zeroRateBucket',
+];
 function toVoucherPayload(voucher) {
+    const action = (0, enum_payload_js_1.requireEnumKey)(index_js_1.VoucherAction, voucher.action, 'Gutschein-Aktion');
+    const type = (0, enum_payload_js_1.requireEnumKey)(index_js_1.VoucherType, voucher.type, 'Gutscheinart');
+    // Felder der neuen Form gehen roh hinaus, soweit gesetzt (auch an einem
+    // gelesenen Altbeleg: dort fehlen sie, die Nutzlast bleibt byte-gleich).
+    const roh = voucher;
+    const neu = {};
+    for (const feld of NEUE_FELDER)
+        if (roh[feld] != null)
+            neu[feld] = roh[feld];
     return {
-        action: (0, enum_payload_js_1.requireEnumKey)(index_js_1.VoucherAction, voucher.action, 'Gutschein-Aktion'),
-        type: (0, enum_payload_js_1.requireEnumKey)(index_js_1.VoucherType, voucher.type, 'Gutscheinart'),
-        valueCents: voucher.valueCents ?? null,
+        action,
+        type,
+        // Die neue Form kennt kein `valueCents`; nur ein gelesener Eintrag (die
+        // Auszahlung steht beim Server als Wert mit Cent) traegt es weiter.
+        ...(isNewFormVoucher(voucher) && voucher.valueCents == null ? {} : { valueCents: voucher.valueCents ?? null }),
         ...(voucher.code != null ? { code: voucher.code } : {}),
         ...(voucher.name != null ? { name: voucher.name } : {}),
+        ...neu,
     };
 }
 /**
@@ -22,6 +58,8 @@ function toVoucherPayload(voucher) {
  * gesetzter Wert muss positiv sein.
  */
 function voucherIsValid(voucher) {
+    if (isNewFormVoucher(voucher))
+        return newFormVoucherIsValid(voucher);
     if (voucher.type === index_js_1.VoucherType.value && voucher.valueCents == null) {
         return false;
     }
@@ -63,5 +101,75 @@ function fromVoucherPayload(payload) {
         action: (0, enum_payload_js_1.readEnumKey)(index_js_1.VoucherAction, payload.action),
         type: (0, enum_payload_js_1.readEnumKey)(index_js_1.VoucherType, payload.type),
         valueCents,
+        ...lesenNeu(payload),
     };
 }
+/** Felder der neuen Form beim Lesen: nur was dasteht (Altbelege bleiben schlank). */
+function lesenNeu(payload) {
+    const roh = payload;
+    const neu = {};
+    for (const feld of NEUE_FELDER)
+        if (roh[feld] != null)
+            neu[feld] = roh[feld];
+    return neu;
+}
+/** Grenzen wie der Server (gutschein-beleg): Betrag 1 bis 1.000.000 Cent, Menge 1 bis 100. */
+const MAX_BETRAG_CENTS = 1_000_000;
+const MAX_STUECK = 100;
+const MAX_GRUND = 200;
+const istCent = (n) => typeof n === 'number' && Number.isInteger(n) && n >= 1 && n <= MAX_BETRAG_CENTS;
+const istMenge = (n) => typeof n === 'number' && Number.isInteger(n) && n >= 1 && n <= MAX_STUECK;
+const hatText = (t) => typeof t === 'string' && t.trim().length > 0;
+/**
+ * Wunsch der neuen Form sendbar? Bildet die Regeln des Servers ab: Serverfelder
+ * nie, Betrag/Menge ganz und positiv, Code bei Einloesung und Auszahlung,
+ * Auszahlung nur Mehrzweck/Einzweck mit Grund (1 bis 200 Zeichen), Aktion nur
+ * einloesbar, Leistung braucht Artikel und Menge (Verkauf) bzw. Positionen
+ * (Einloesung). Felder, die zu einer anderen Aktion/Art gehoeren, sind
+ * ebenfalls nicht erlaubt (der Server wiese sie ab).
+ */
+function newFormVoucherIsValid(v) {
+    if (voucherServerFields(v).length > 0)
+        return false;
+    const r = v;
+    for (const feld of ['vatRateBp', 'article', 'balanceAfterCents', 'remainingQuantityAfter', 'taxedWith', 'exempt']) {
+        if (r[feld] != null)
+            return false;
+    }
+    if (v.valueCents != null)
+        return false;
+    const allein = v.type === index_js_1.VoucherType.multi_purpose || v.type === index_js_1.VoucherType.single_purpose;
+    if (v.action === index_js_1.VoucherAction.payout) {
+        return allein && hatText(v.code) && istCent(v.amountCents) && hatText(v.reason) && v.reason.trim().length <= MAX_GRUND
+            && v.articleId == null && v.quantity == null && v.positions == null;
+    }
+    if (v.reason != null)
+        return false;
+    if (allein) {
+        if (v.articleId != null || v.quantity != null || v.positions != null)
+            return false;
+        if (v.action === index_js_1.VoucherAction.sell)
+            return istCent(v.amountCents);
+        if (v.action === index_js_1.VoucherAction.redeem)
+            return hatText(v.code) && istCent(v.amountCents);
+        return false;
+    }
+    if (v.type === index_js_1.VoucherType.service) {
+        if (v.amountCents != null)
+            return false;
+        if (v.action === index_js_1.VoucherAction.sell) {
+            return hatText(v.articleId) && istMenge(v.quantity) && v.positions == null;
+        }
+        if (v.action === index_js_1.VoucherAction.redeem) {
+            return hatText(v.code) && Array.isArray(v.positions) && v.positions.length > 0
+                && v.positions.every((i) => Number.isInteger(i) && i >= 0) && new Set(v.positions).size === v.positions.length && v.articleId == null && v.quantity == null;
+        }
+        return false;
+    }
+    if (v.type === index_js_1.VoucherType.promotion) {
+        return v.action === index_js_1.VoucherAction.redeem && hatText(v.code)
+            && v.amountCents == null && v.articleId == null && v.quantity == null && v.positions == null;
+    }
+    // Altart mit neuer Aktion (payout + value/promo): nicht sendbar.
+    return false;
+}

package/dist/cjs/partner/fehler.d.ts

@@ -61,7 +61,7 @@ import { KasseneckApiError } from '../client/errors.js';
  *
  * Reihenfolge und Bestand wie im Abzug des Backends.
  */
-export declare const PARTNER_ERROR_CODES: readonly ["validation", "rate_limited", "app_not_found", "app_not_accepted", "live_not_allowed", "customer_exists", "customer_conflict", "customer_limit", "access_not_allowed", "email_taken", "no_email", "tax_number_missing", "fon_missing", "signature_pending", "signature_missing", "signature_unknown", "signature_ambiguous", "signature_not_ready", "signature_limit", "signature_failed", "module_inactive", "cashregister_limit", "cashregister_not_found", "contracts_pending", "kind_not_allowed", "mode_not_allowed", "power_of_attorney_missing", "not_found", "no_version", "unknown_version", "text_changed", "already_accepted", "activation_failed", "webhook_limit", "webhook_inactive", "event_not_subscribed"];
+export declare const PARTNER_ERROR_CODES: readonly ["validation", "rate_limited", "app_not_found", "app_not_accepted", "live_not_allowed", "customer_exists", "customer_conflict", "customer_limit", "access_not_allowed", "email_taken", "no_email", "tax_number_missing", "fon_missing", "signature_pending", "signature_missing", "signature_unknown", "signature_ambiguous", "signature_not_ready", "signature_limit", "signature_failed", "module_inactive", "cashregister_limit", "cashregister_not_found", "contracts_pending", "kind_not_allowed", "mode_not_allowed", "power_of_attorney_missing", "not_found", "no_version", "unknown_version", "text_changed", "already_accepted", "activation_failed", "activation_in_progress", "webhook_limit", "webhook_inactive", "event_not_subscribed"];
 /**
  * Die Codes, die nur im **Partner-Portal** entstehen — beim Pflegen der App,
  * der Schluessel, der Mitglieder und der Signaturkarten.

package/dist/cjs/partner/fehler.js

@@ -111,6 +111,7 @@ exports.PARTNER_ERROR_CODES = [
     'text_changed',
     'already_accepted',
     'activation_failed',
+    'activation_in_progress',
     // Webhooks
     'webhook_limit',
     'webhook_inactive',
@@ -218,6 +219,7 @@ const RAT = {
     text_changed: 'Der gezeigte Vertragstext hat sich seit dem Laden geaendert (data.textHash traegt die aktuell geltende Pruefsumme). Neu laden und danach erneut bestaetigen lassen.',
     already_accepted: 'Diese Fassung ist bereits bestaetigt (data.contractId). Nichts weiter zu tun.',
     activation_failed: 'Die Inbetriebnahme blieb an data.step haengen (ggf. data.rc). activateCashregister erneut aufrufen — jeder Schritt ist idempotent, der Lauf setzt an der Bruchstelle an.',
+    activation_in_progress: 'Die Inbetriebnahme dieser Kasse laeuft bereits. Kurz warten und den Stand abfragen, nicht erneut anstossen.',
     webhook_limit: 'Hoechstens 10 Webhook-Endpunkte je Partner. Einen ungenutzten loeschen.',
     webhook_inactive: 'Der Webhook steht auf active:false. Zuerst aktivieren, dann erneut proben.',
     event_not_subscribed: 'Der Endpunkt abonniert dieses Ereignis nicht — auch eine Probe bekommt nur, was in seiner events-Liste steht. events erweitern und erneut versuchen.',

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

@@ -28,6 +28,6 @@ export { getPartnerInfo, createPartnerCustomer, listPartnerCustomers, checkPartn
 export { createPartnerWebhook, listPartnerWebhooks, rotatePartnerWebhookSecret, updatePartnerWebhook, deletePartnerWebhook, sendPartnerWebhookTest, listPartnerWebhookDeliveries, parseWebhookEvent, isPartnerWebhookEvent, PARTNER_WEBHOOK_EVENTS, WEBHOOK_ENVELOPE_FIELDS, WEBHOOK_DELIVERY_STATUSES, type PartnerWebhookEvent, type PartnerWebhookEventType, type PartnerWebhook, type CreateWebhookOptions, type CreateWebhookResult, type DeleteWebhookResult, type WebhookApiVersion, type WebhookDeliveryStatus, type WebhookTestDelivery, type ContractAcceptedEventData, type SignatureFailedEventData, type CashregisterFailedEventData, type WebhookPatch, type WebhookList, type WebhookDelivery, type WebhookTestResult, type WebhookEventResult, } from './webhooks.js';
 export { verifyWebhookSignature, parseSignatureHeader, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_TOLERANCE_SEC, WEBHOOK_RETRY_PLAN_SEC, WEBHOOK_MAX_ATTEMPTS, WEBHOOK_TIMEOUT_MS, WEBHOOK_LIMIT, type VerifyWebhookOptions, type WebhookVerifyResult, type WebhookVerifyReason, } from './webhook-signatur.js';
 export { PARTNER_ENVS, LEGAL_FORMS, AUSTRIAN_STATES, CONTACT_ROLES, AVV_MODES, FEE_INTERVALS, CONTRACT_KINDS, CONTRACT_SOURCES, SIGNATURE_HISTORY_REASONS, SIGNATURE_ERROR_CODES, } from './typen.js';
-export type { PartnerEnv, PartnerScope, PartnerApp, PartnerInfo, LegalForm, AustrianState, ContactRole, AvvMode, FeeInterval, PartnerFee, SignatureHistoryReason, SignatureErrorCode, RequestSignatureOptions, CustomerSignature, ContractKind, ContractSource, ReportCustomerContractOptions, ReportCustomerContractResult, BusinessAddress, BusinessTaxDetails, BusinessContact, BusinessTaxAdvisor, Business, CreateCustomerOptions, CreateCustomerResult, PartnerCustomerStatus, PartnerCustomerSummary, AvvStatus, ContractStatus, PartnerCustomerFonStatus, ListCustomersOptions, PartnerCustomerList, PartnerCustomer, FonLinkResult, SignatureRequestStatus, SignatureHistoryEntry, SignatureRequest, RequestSignatureResult, CustomerSignatureStatus, CashregisterActivationStep, CustomerCashregisterStatus, CustomerCashregister, CreateCashregisterOptions, CreateCashregisterResult, ActivateCashregisterResult, CustomerCashregisterList, CustomerCashregisterCredential, CustomerCredentials, } from './typen.js';
+export type { PartnerEnv, PartnerScope, PartnerApp, PartnerInfo, LegalForm, AustrianState, ContactRole, AvvMode, FeeInterval, PartnerFee, SignatureHistoryReason, SignatureFulfillment, SignatureErrorCode, RequestSignatureOptions, CustomerSignature, ContractKind, ContractSource, ReportCustomerContractOptions, ReportCustomerContractResult, BusinessAddress, BusinessTaxDetails, BusinessContact, BusinessTaxAdvisor, Business, CreateCustomerOptions, CreateCustomerResult, PartnerCustomerStatus, PartnerCustomerSummary, AvvStatus, ContractStatus, PartnerCustomerFonStatus, ListCustomersOptions, PartnerCustomerList, PartnerCustomer, FonLinkResult, SignatureRequestStatus, SignatureHistoryEntry, SignatureRequest, RequestSignatureResult, CustomerSignatureStatus, CashregisterActivationStep, CustomerCashregisterStatus, CustomerCashregister, CreateCashregisterOptions, CreateCashregisterResult, ActivateCashregisterResult, CustomerCashregisterList, CustomerCashregisterCredential, CustomerCredentials, } from './typen.js';
 /** `credentials:read` — nicht im Standardsatz, siehe typen.ts. */
 export { SCOPE_CREDENTIALS } from './typen.js';

package/dist/cjs/partner/typen.d.ts

@@ -382,7 +382,7 @@ export type SignatureRequestStatus = 'requested' | 'assigned' | 'registered' | '
  * Gruende in der Historie eines Signaturantrags. `card_entered` und
  * `finanzonline` hiessen unter `/v1` `karte_eingetragen` und `fon`.
  */
-export declare const SIGNATURE_HISTORY_REASONS: readonly ["api", "portal", "card_entered", "finanzonline", "automation_off", "test_environment", "no_stock"];
+export declare const SIGNATURE_HISTORY_REASONS: readonly ["api", "portal", "card_entered", "finanzonline", "automation_off", "test_environment", "no_stock", "card_pool_activated", "activation_run", "finanzonline_completed"];
 /** Offen fuer spaeter ergaenzte Gruende, siehe [SIGNATURE_HISTORY_REASONS]. */
 export type SignatureHistoryReason = typeof SIGNATURE_HISTORY_REASONS[number] | (string & {});
 /**
@@ -400,6 +400,8 @@ export interface SignatureHistoryEntry {
     at: number;
     reason: SignatureHistoryReason | null;
 }
+/** Erfuellungsweg eines Signaturantrags; offen fuer spaeter ergaenzte Werte. */
+export type SignatureFulfillment = 'automatic' | 'manual' | (string & {});
 export interface SignatureRequest {
     requestId: string;
     status: SignatureRequestStatus;
@@ -408,6 +410,8 @@ export interface SignatureRequest {
     kind: string;
     vdaId: string | null;
     signatureId: string | null;
+    /** Wie der Antrag erfuellt wird: aus dem Kartenvorrat oder von Hand. */
+    fulfillment?: SignatureFulfillment;
     error: {
         code: SignatureErrorCode | null;
         message: string | null;
@@ -442,6 +446,8 @@ export interface CustomerSignature {
     status: SignatureRequestStatus | 'decommissioned';
     statusText: string;
     inProgress: boolean;
+    /** Wie der Antrag erfuellt wird: aus dem Kartenvorrat oder von Hand. */
+    fulfillment?: SignatureFulfillment;
     ready: boolean;
     kind: string;
     vdaId: string | null;

package/dist/cjs/partner/typen.js

@@ -100,6 +100,9 @@ exports.SIGNATURE_HISTORY_REASONS = [
     'automation_off',
     'test_environment',
     'no_stock',
+    'card_pool_activated',
+    'activation_run',
+    'finanzonline_completed',
 ];
 /**
  * `error.code` eines Signaturantrags oder einer Signatur (`SignatureRequest`,

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

@@ -4,10 +4,11 @@ import { type PosSettings, type PosBusinessSettings, type PosDeviceSettings } fr
 export declare function getPosSettings(transport: InternerTransport, options?: {
     deviceId?: string;
 }): Promise<PosSettings>;
-/** `{business, device}` einer Antwort, gemischt mit den Standardwerten. */
+/** `{business, device, vouchers}` einer Antwort, gemischt mit den Standardwerten. */
 export declare function posSettingsFromWire(data: {
     business?: unknown;
     device?: unknown;
+    vouchers?: unknown;
 } | null | undefined): PosSettings;
 /** Betriebsweite Einstellungen schreiben (Recht `layout`); liefert den gemischten Stand. */
 export declare function setMyPosSettings(transport: InternerTransport, business: Partial<PosBusinessSettings>): Promise<PosBusinessSettings>;

package/dist/cjs/pos/client.js

@@ -6,6 +6,7 @@ exports.setMyPosSettings = setMyPosSettings;
 exports.setMyRegisterDeviceSettings = setMyRegisterDeviceSettings;
 exports.setMyPosLogo = setMyPosLogo;
 const errors_js_1 = require("../client/errors.js");
+const gutschein_js_1 = require("./gutschein.js");
 const settings_js_1 = require("./settings.js");
 /*
  * Die Einstellungs-Aufrufe am Draht `/api/v3`: Parameter und Antwort heissen
@@ -34,9 +35,10 @@ async function getPosSettings(transport, options = {}) {
     const daten = await transport('getKasseSettings', params);
     return posSettingsFromWire(daten);
 }
-/** `{business, device}` einer Antwort, gemischt mit den Standardwerten. */
+/** `{business, device, vouchers}` einer Antwort, gemischt mit den Standardwerten. */
 function posSettingsFromWire(data) {
     return {
+        vouchers: (0, gutschein_js_1.posVoucherSettingsFromWire)(data?.vouchers),
         business: (0, settings_js_1.mergePosSettings)(settings_js_1.POS_BUSINESS_DEFAULTS, objekt(data?.business)),
         device: (0, settings_js_1.mergePosSettings)(settings_js_1.POS_DEVICE_DEFAULTS, objekt(data?.device)),
     };

package/dist/cjs/pos/gutschein.d.ts

@@ -0,0 +1,90 @@
+import type { InternerTransport } from '../client/aufrufe.js';
+/**
+ * Gutschein pruefen und Etikett nachdrucken an der Kasse (Backend
+ * gutschein-endpoints). Beide Aufrufe gibt es nur ueber den Kassenweg
+ * `/api/v3`.
+ *
+ * Der Klartext-Code lebt nur im Speicher des Aufrufs: er wird weder
+ * protokolliert noch in einer Fehlermeldung genannt. Die Kasse bekommt nach
+ * dem Pruefen nur die letzten vier Zeichen (`codeSuffix`) zurueck.
+ */
+export type VoucherKind = 'multi_purpose' | 'single_purpose' | 'service' | 'promotion';
+export type VoucherStatus = 'active' | 'used_up' | 'expired' | 'paid_out' | 'cancelled' | 'blocked';
+export declare const VOUCHER_KINDS: readonly VoucherKind[];
+export declare const VOUCHER_STATUSES: readonly VoucherStatus[];
+/** Gueltigkeit eines Gutscheins; Daten als `YYYY-MM-DD` (Wiener Tag). Was der Server nicht nennt, fehlt. */
+export interface VoucherValidity {
+    pattern: 'unlimited' | '1+3' | 'custom';
+    redeemableUntil?: string;
+    refundableUntil?: string;
+    validUntil?: string;
+}
+/** Der Artikel eines Dienstleistungsgutscheins. */
+export interface VoucherArticle {
+    id: string;
+    name: string;
+    vatRateBp: number;
+    priceCents: number;
+}
+/**
+ * Stand eines Gutscheins nach dem Code-Eingeben. Felder, die zur Art nicht
+ * passen oder die der Server nicht sendet, fehlen im Modell (nie `null`).
+ */
+export interface VoucherCheck {
+    type: VoucherKind;
+    status: VoucherStatus;
+    /** Die letzten vier Zeichen des Codes, fuer Anzeige und Beleg. */
+    codeSuffix: string;
+    balanceCents?: number;
+    faceValueCents?: number;
+    quantity?: number;
+    remainingQuantity?: number;
+    vatRateBp?: number;
+    article?: VoucherArticle;
+    discountCents?: number;
+    discountPercentBp?: number;
+    validity?: VoucherValidity;
+    /**
+     * Befreit verkauft (Kleinunternehmer beim Verkauf, Satz 0): eine Einloesung
+     * verteilt sich anteilig auf alle Saetze des Korbs, auch in einem
+     * inzwischen steuerpflichtigen Konto. Fehlt bei aelteren Servern.
+     */
+    exempt?: boolean;
+}
+/** Gutschein-Einstellungen der Kasse (Block `vouchers` aus `getKasseSettings`). */
+export interface PosVoucherSettings {
+    sale: boolean;
+    valueVoucherType: 'multi_purpose' | 'single_purpose' | null;
+    vatRateBp: number | null;
+}
+/** Ohne Block `vouchers` (alter Server, Konto ohne Schalter): Verkaufen ist aus. */
+export declare const VOUCHER_SETTINGS_DEFAULTS: Readonly<PosVoucherSettings>;
+/**
+ * Block `vouchers` einer Einstellungs-Antwort, geschlossen im Zweifel: ist
+ * irgendein Feld unstimmig, gilt der ganze Block als nicht gelesen und
+ * Verkaufen bleibt aus (kein Wurf, sonst ginge das Laden aller Einstellungen
+ * verloren). Stimmig heisst: `sale` ein Wahrheitswert, die Art
+ * `multi_purpose`/`single_purpose`/`null`, der Satz eine ganze Zahl >= 0 oder
+ * `null`; Mehrzweck traegt keinen Satz, Einzweck braucht einen, und ein
+ * eingeschalteter Verkauf braucht eine Art. Ein ausgeschalteter Verkauf darf
+ * eine Art behalten.
+ */
+export declare function posVoucherSettingsFromWire(block: unknown): PosVoucherSettings;
+/**
+ * Gutschein am Code pruefen (Gutschein-Recht `voucherRedeem`). Der Code wird
+ * tolerant eingelesen (Gross/klein, Bindestriche, `O`/`0`, `I`/`L`/`1`) und
+ * vor dem Senden auf sein Pruefzeichen geprueft: ein Tippfehler geht nie ueber
+ * das Netz, sondern endet mit `KasseneckValidationError`. Fachliche Fehler
+ * kommen als `KasseneckApiError` mit dem Code des Servers
+ * (`voucher_not_found`, `too_many_voucher_checks`, `not_permitted` …).
+ */
+export declare function checkVoucher(transport: InternerTransport, code: string): Promise<VoucherCheck>;
+/**
+ * Etikett eines Gutscheins noch einmal drucken (Gutschein-Recht
+ * `voucherManage`). Antwort ist der Klartext-Code zum Drucken; er gehoert
+ * nur in den Speicher bis zum Druck. Aufrufer duerfen ihn nicht protokollieren,
+ * speichern oder in Meldungen nennen; Lesefehler dieser Antwort nennen ihn nie.
+ */
+export declare function reprintVoucherLabel(transport: InternerTransport, id: string): Promise<{
+    code: string;
+}>;