@kreiseck/kasseneck-api 1.15.0 → 1.17.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ Was vor 0.7.0 geschah, steht in der Commit-Historie (`git log`); ab hier wird
 es hier geführt. Ein Eintrag nennt die Änderung **und ihren Grund** —
 nur der Grund überlebt den nächsten Umbau.
 
+## 1.17.0 - 2026-10-29
+
+Vouchers at the register, stage 4b: voucher types (Gutschein-Sorten). A business names any number of voucher types (multi- or single-purpose, free or fixed amount, validity, payout, label template); the register shows one tile per type in a tab "Gutscheine" and sells a value voucher only through a type. Additive for reading, with three behaviour changes for selling (see the items on `typeId` and the due amount).
+
+- **Voucher types in the register settings: `PosVoucherSettings.typeSale`, `types`, `serviceArticles`, `labelDefault`.** `typeSale` shows the tab (server switch and at least one sellable type or service article), `types` are the sellable types in tile order (`PosVoucherType`: `id`, `name`, `kind`, `vatRateBp`, `amount` free or fixed, `validity` unlimited or years, `payout`, `label`, `order`, `active`, `soldCount`), `serviceArticles` adds the fixed tile "Leistungsgutschein", `labelDefault` is the business's standard label template. The four fields are optional in the type so existing literals still compile; `posVoucherSettingsFromWire` always sets them (an older server: off, empty, `null`). Fail-closed as before: a malformed `typeSale`, `serviceArticles` or `types` closes the whole block, a malformed type is dropped on its own (unknown kind, rate not matching the kind, fixed amount outside 1.00-10,000.00 €, years outside 1-30, payout `never` with a limited validity, inactive, reserved id), and `typeSale` is off when no type and no service article is left. An unusable label template becomes `null` and never closes anything (a sale never fails on the label). The old field `label` (registers before 1.17) is not read. Reason: from stage 4b the server sells value vouchers only through a voucher type and keeps `sale` always `false`, so registers before 1.17 never offer a sale it would reject.
+- **New types and lists in `./pos`:** `PosVoucherType`, `VoucherLabelTemplate` (passed through as a copy; the package does not draw labels), `VoucherPayout`, `VoucherTypeKind`, `VOUCHER_TYPE_KINDS`, `VOUCHER_AMOUNT_MODES`, `VOUCHER_TYPE_VALIDITY_PATTERNS`, `VOUCHER_PAYOUTS` (equal to the `/v3` catalogues, also in `fixtures/surface.json`). Reason: web register and app read the same model.
+- **A value voucher is sold only with `typeId`:** `Voucher.typeId` carries the voucher type, the wish is `{ action: 'sell', type: kind, typeId, amountCents }` (with a fixed amount exactly `amount.cents`). `type` may be left out on the wire (the kind then comes from the type); a wish read that way goes out without `type`. Behaviour change: `voucherIsValid` is `false` for a multi- or single-purpose sale without `typeId`, and `createReceipt` rejects it before sending (message starts with `voucher_type_required`); `typeId` on any other action or kind is rejected as `voucher_invalid`, and so are `typeName` and `payout` on a wish (server fields, `GUTSCHEIN_SERVERFELDER`). Reason: the server answers a value sale without type `voucher_type_required`; nothing is sent that it would refuse.
+- **Due amount with voucher types: `ReceiptDueOptions.voucherTypes` (`VoucherDueType` = `id`, `kind`, `vatRateBp`, `amount` of a `PosVoucherType`).** A sale through a type takes kind and rate from the type (multi-purpose as value flow, from the zero-rate date in the 0 % bucket; single-purpose as an item at the rate of the type, 0 % for a small business). A type the register does not pass (or one the server would not sell) throws `voucher_type_not_found`, a different fixed amount `voucher_amount_mismatch`, and so does a `type` other than the kind of the type (the owner switched the kind after the register loaded its types; the register reloads them on this code), a reserved id `voucher_type_not_found`. Behaviour change: a value sale without `typeId` still computes with a `voucherSettings` that names a kind exactly as in 1.16 (for existing callers), but without `voucherSettings` or with one naming no kind (`valueVoucherType: null`, as every stage-4b server sends) it now throws `voucher_type_required` instead of `voucher_settings_missing`. Reason: the register computes the amount to charge before the card terminal, with the same rules and codes as the server's `gutschein-beleg.plane`.
+- **Payout locked per voucher:** `VoucherCheck.payout` (`allowed`/`never`, frozen at sale) and `VoucherCheck.typeName` from `checkVoucher`; a payout of a `never` voucher throws `voucher_payout_not_allowed` in the due amount (also when expired). An unknown payout value reads as `never` without throwing, because redeeming must not fail on a new value. Reason: a business may exclude payouts for unlimited voucher types; the server refuses them.
+- **Validity in years:** `VoucherValidity.redeemableYears` (1-30) from `checkVoucher`, also in `IssuedVoucher.validity`. The patterns stay `unlimited`, `1+3`, `custom`; the type's own pattern `years` never appears on a voucher. A voucher of a type with N years comes as `1+3` for every N, with the explicit dates (`redeemableUntil` = sale + N years, `refundableUntil` = sale + N + 3 years) and `redeemableYears` = N; read N from `redeemableYears`, never from the pattern. Reason: registers before 1.17 keep redeeming such vouchers and print "einlösbar bis <date>" from `redeemableUntil` on a reprint (with `custom` and no `validUntil` they printed no validity line at all).
+- **Service vouchers only for approved articles: `PosArticle.serviceVoucher`** (only an explicit `true` counts; the reader always sets it, also `fromStoredArticle` from `gutscheinLeistung`), and `VoucherDueArticle.serviceVoucher`: `false` throws `voucher_service_not_allowed`, absent computes as before. Reason: the tile "Leistungsgutschein" offers only approved articles, the server sells no other.
+- **Receipt entries of a sale through a type** read and write back `typeId`, `typeName` and `payout`; `IssuedVoucher` gains `typeId` and `typeName`; the `./stored` twin maps `sorteId`, `sorteName` and `auszahlung` (`erlaubt`/`nie`) like the server. Reason: the receipt and the label show the type name, and a cached receipt must write back unchanged.
+- **5 labels and 5 sentences:** `voucher.tab` (Gutscheine), `voucher.enter_amount` (Betrag eingeben), `voucher.service_tile` (Leistungsgutschein), `voucher.kind_multi_short` (Mehrzweck), `voucher.kind_single_short` (Einzweck {rate} %); `VOUCHER_ERROR_MESSAGES` maps the new register codes to `voucher_error.type_required`, `type_not_found`, `amount_mismatch`, `service_not_allowed`, `payout_not_allowed` (also in `fixtures/pos-texts.json`). The codes of the customer area (`invalid_voucher_type`, `voucher_type_in_use`, `too_many_voucher_types`) are not register codes and get no sentence here. Reason: web register and app say the same words for the same tile and error.
+- **One sentence of the register itself: `voucher.type_changed`** ("Diese Gutschein-Sorte hat sich geändert. Bitte die Zeile entfernen und die Kachel neu antippen.", also in `fixtures/pos-texts.json`). The register shows it on a voucher sale line in the cart that no longer matches the reloaded types (type changed, deactivated or deleted); the sentences after a server rejection stay `voucher_error.type_not_found` and `voucher_error.amount_mismatch`. Reason: those say "Die Kasse lädt die Sorten neu", which is over once the types are reloaded; the line blocks payment until it is removed and the tile tapped again, and the cashier must be told so.
+- Contract re-fetched from the backend (stage 4b): the server names the position of a single-purpose sale with the type name, so the print digests of `sale_single_purpose_voucher` (both channels) are redrawn; the generated due cases (`fixtures/receipt-due-voucher-generated.json`, seed 20261027) now sell through types, with and without `type`, free and fixed, and cover the rejections above.
+
+## 1.16.0 - 2026-10-28
+
+Header data for the full view of `listReceipts`, and the new upper limit of `getReportV2`. Additive.
+
+- **`ListReceiptsPage.metadata`** (only with `view: 'full'`): the business data for the receipt header, the same `ReportV2Metadata` as `getReportV2().metadata` (`companyName`, address, `taxNumber`, `vatId`, footers, logo, `label` of the cash register); missing on the summary view. A `metadata` that is not an object is a response error. Reason: an app that prints a receipt again needs the header, and moving from `getReportV2` to `listReceipts` must not lose it.
+- **`getReportV2`: the server now refuses more than 62 calendar days between `start` and `end`** with `range_too_long` (`KasseneckApiError`), without reading any receipt. The package does not check this before sending. Reason: one call could load an unbounded number of receipts; lists belong to `listReceipts`.
+- Contract `v3` from the backend after keck#790.
+
 ## 1.15.0 - 2026-10-28
 
 Receipt lists page by page: `listReceipts` and `listAllReceipts` for the new public endpoint `listReceipts` (`/v3` only). Additive.

package/README.md

@@ -792,6 +792,8 @@ receipt in 24 hours, 30 per register per hour) and `send_failed`.
 
 ## Receipt printing: QR code, logo, printers
 
+`view: 'full'` returns the stored receipts plus `page.metadata` (business data for the receipt header, the same as `getReportV2().metadata`). `getReportV2` itself accepts at most 62 days between `start` and `end` (`range_too_long`).
+
 ### The QR code fits the paper
 
 The native QR command is given a module size in dots and does not check

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

@@ -1,5 +1,6 @@
 import { KeckPaymentMethod, ReceiptType } from '../enums/index.js';
 import { type CancellationReason, type CancellationStatus, type Receipt, type ReceiptPayment, type ZeroKind } from '../models/index.js';
+import type { ReportV2Metadata } from './reports.js';
 import type { InternerTransport } from './aufrufe.js';
 /**
  * Belege einer Kasse auflisten (`listReceipts`, nur unter `/v3`): ein Tag oder
@@ -174,6 +175,11 @@ export interface ListReceiptsPage<V extends ListReceiptsView = 'summary'> {
      * den Tag keine Statistik gibt. Auf allen anderen Seiten fehlt das Feld.
      */
     daySummary?: ListReceiptsDaySummary | null;
+    /**
+     * Nur bei `view: 'full'`: Firmendaten fuer den Belegkopf (Nachdruck), dieselben Felder wie
+     * `getReportV2().metadata`. Bei der Kurzansicht fehlt das Feld.
+     */
+    metadata?: V extends 'full' ? ReportV2Metadata : never;
 }
 /** Zeile `view: summary` vom Draht. */
 export declare function fromListReceiptsSummaryPayload(payload: Record<string, unknown>): ListReceiptsSummary;

package/dist/cjs/client/list-receipts.js

@@ -212,6 +212,13 @@ function tagessumme(roh) {
         revenueByRate: saetze.filter(istObjekt).map((z) => ({ rateBp: cent(z['rateBp']), grossCents: cent(z['grossCents']) })),
     };
 }
+/** `metadata` der vollen Ansicht wie bei getReportV2: Firmendaten plus Bezeichnung der Kasse. */
+function kopfdaten(roh) {
+    if (!istObjekt(roh))
+        throw antwortfehler('metadata ist kein Objekt');
+    const label = roh.label;
+    return { ...(0, index_js_2.fromReceiptCompanyPayload)(roh), label: typeof label === 'string' ? label : '' };
+}
 /**
  * Eine Seite Belege der angemeldeten Kasse (`listReceipts`). Die Eingabe wird
  * vor dem Senden nach den Regeln des Servers geprueft (genau eine Form des
@@ -248,6 +255,7 @@ async function listReceipts(transport, options) {
         hasMore: daten['hasMore'],
         nextCursor: daten['hasMore'] ? weiter : null,
         ...('daySummary' in daten ? { daySummary: tagessumme(daten['daySummary']) } : {}),
+        ...(voll && 'metadata' in daten ? { metadata: kopfdaten(daten['metadata']) } : {}),
     };
 }
 /**

package/dist/cjs/client/receipts.js

@@ -20,6 +20,7 @@ exports.belegAusHuelle = belegAusHuelle;
 exports.belegMitFirmaAusHuelle = belegMitFirmaAusHuelle;
 exports.paymentsExpectedCents = paymentsExpectedCents;
 const index_js_1 = require("../enums/index.js");
+const voucher_js_1 = require("../models/voucher.js");
 const index_js_2 = require("../models/index.js");
 const receipt_output_js_1 = require("../models/receipt-output.js");
 const validator_1 = require("@kreiseck/validator");
@@ -143,6 +144,13 @@ function createReceiptParams(options) {
         if (typ.value === index_js_1.ReceiptType.training.value && vouchers.some(index_js_2.isNewFormVoucher)) {
             throw eingabefehler('Gutscheine der neuen Form gibt es nicht auf Schulungsbelegen (receiptType training).');
         }
+        // Gutscheine Stufe 4b: ein Wertgutschein nur ueber eine Sorte, die Sorte nur an einem solchen Verkauf.
+        if (vouchers.some((voucher) => (0, voucher_js_1.istWertVerkauf)(voucher) && voucher.typeId == null)) {
+            throw eingabefehler('voucher_type_required: Ein Mehrzweck- oder Einzweckgutschein wird nur ueber eine Gutschein-Sorte verkauft (typeId aus getKasseSettings vouchers.types).');
+        }
+        if (vouchers.some((voucher) => voucher.typeId != null && !(0, voucher_js_1.istWertVerkauf)(voucher))) {
+            throw eingabefehler('voucher_invalid: typeId gehoert nur an den Verkauf eines Mehrzweck- oder Einzweckgutscheins.');
+        }
         if (vouchers.some((voucher) => !(0, index_js_2.voucherIsValid)(voucher))) {
             throw eingabefehler('Ungueltiger Gutschein uebergeben.');
         }

package/dist/cjs/index.d.ts

@@ -1,6 +1,6 @@
 export { ReceiptType, type ReceiptTypeKey, VatRate, type VatRateKey, KeckPaymentMethod, type KeckPaymentMethodKey, CreditCardProvider, type CreditCardProviderKey, VoucherType, type VoucherTypeKey, VoucherAction, type VoucherActionKey, StripeLinkMode, type StripeLinkModeKey, } from './enums/index.js';
 export { type ReceiptItem, type ReceiptItemPayload, type ReceiptItemPayloadRead, toReceiptItemPayload, fromReceiptItemPayload, receiptItemTotalCents, receiptItemIsValid, negateReceiptItem, type TipRecipient, isTipItem, isVoucherItem, isVoucherFloatItem, type Voucher, type VoucherArticle, type IssuedVoucher, type VoucherPayload, toVoucherPayload, fromVoucherPayload, voucherIsValid, type Receipt, type RegistrationInfo, type ReceiptPayload, type ReceiptPayloadRead, toReceiptPayload, fromReceiptPayload, receiptSubSumCents, receiptSumCents, receiptValueVoucherSign, type CancellationOf, type CancellationItem, type Cancellation, type CancellationReason, type CancellationErrorCode, type CancellationStatus, type ReturnDisposition, RETURN_DISPOSITIONS, CANCELLATION_REASONS, CANCELLATION_STATUSES, CANCELLATION_ERROR_CODES, CANCELLATION_RESERVATION_MS, isCancellationReason, isReturnDisposition, isCancellationErrorCode, cancellationErrorCode, isCancellationError, cancellationFieldErrors, type CancellationFieldError, type ReceiptPayment, type ReceiptPaymentPayload, type ReceiptPaymentInput, fromReceiptPaymentPayload, toReceiptPaymentPayload, type PaymentErrorCode, PAYMENT_ERROR_CODES, isPaymentErrorCode, paymentErrorCode, isPaymentError, paymentFieldErrors, type PaymentFieldError, type ReceiptEmailErrorCode, type ReceiptEmailVia, RECEIPT_EMAIL_ERROR_CODES, RECEIPT_EMAIL_SEND_ERROR_CODES, type ReceiptEmailSendErrorCode, RECEIPT_EMAIL_VIAS, isReceiptEmailErrorCode, receiptEmailErrorCode, isReceiptEmailError, receiptEmailFieldErrors, type ReceiptEmailFieldError, RECEIPT_OUTPUT_KINDS, type ReceiptOutputKind, RECEIPT_OUTPUT_LOG_KINDS, type ReceiptOutputLogKind, RECEIPT_OUTPUT_RESULTS, type ReceiptOutputResult, RECEIPT_OUTPUT_ENTRIES_MAX, type ReceiptOutput, type ReceiptOutputActor, RECEIPT_OUTPUT_ENTRY_ERROR_CODES, type ReceiptOutputEntryErrorCode, RECEIPT_OUTPUT_ERROR_CODES, type ReceiptOutputErrorCode, isReceiptOutputErrorCode, receiptOutputErrorCode, isReceiptOutputError, receiptOutputFieldErrors, type ReceiptOutputFieldError, type ReceiptErrorCode, type ReceiptFieldError, RECEIPT_ERROR_CODES, isReceiptErrorCode, receiptErrorCode, isReceiptError, receiptFieldErrors, remainingQuantities, TIP_REFUND_SOURCES, type TipRefundSource, isTipRefundSource, openStaffTipCents, cancellationItemsForTip, cancellationCashRefundCents, asksTipRefundSource, asksRefundTip, type ReceiptCompany, type ReceiptCompanyPayload, fromReceiptCompanyPayload, receiptCompanyTaxInfo, type Cashregister, type CashregisterOnboarding, type CashregisterPayload, type CashregisterOnboardingPayload, type CashregisterAutoLogout, type CashregisterAutoLogoutPayload, fromCashregisterPayload, type ReceiptSummary, type ReceiptSummaryPayload, fromReceiptSummaryPayload, type ZeroKind, ZERO_KINDS, isZeroKind, type ReportMonth, reportMonthFromDate, previousReportMonth, nextReportMonth, reportMonthKey, reportMonthReadable, type StripeUrlSession, type StripeUrlSessionPayload, toStripeUrlSessionPayload, fromStripeUrlSessionPayload, type HobexReceipt, type HobexReceiptPayload, toHobexReceiptPayload, fromHobexReceiptPayload, hobexReceiptToCardPaymentData, hobexReceiptNeedsSignature, } from './models/index.js';
 export { type AuthCredentials, type KasseneckAuth, type ApiKeyAuthOptions, type RegisterUserAuthOptions, apiKeyAuth, registerUserAuth, DEFAULT_BASE_URL, POS_BASE_URL, DEFAULT_TIMEOUT_MS, type HttpResponseLike, type HttpRequestInit, type FetchLike, type TransportOptions, type TransportBodyFields, type TransportCallOptions, type KasseneckTransport, type KasseneckBinaryTransport, type KasseneckPdfOrDataTransport, type PdfOrData, ALL_CALLS, type ApiCall, PUBLIC_CALLS, POS_CALLS, UNKNOWN_OUTCOME_CALLS, type PublicCall, type PosCall, createTransport, createBinaryTransport, createPdfOrDataTransport, KasseneckApiError, KasseneckAuthError, KasseneckHttpError, KasseneckNetworkError, KasseneckValidationError, type ValidationScope, type KasseneckError, type HttpFailureReason, type CauseDigest, type ErrorOutcome, CLIENT_ERROR_CODES, type ClientErrorCode, isKasseneckApiError, isKasseneckAuthError, isKasseneckHttpError, isKasseneckNetworkError, isKasseneckValidationError, isOutcomeUnknown, type ReceiptCommonOptions, type SellReceiptOptions, type TipOptions, type TipRecipientShare, type CancelReceiptOptions, type CancelReceiptResult, type ReceiptWithCompany, sellReceipt, sellReceiptWithCompany, paymentsExpectedCents, cardRefundReference, receiptLayoutFromResult, cancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, type ListMyReceiptsOptions, type ReceiptList, type ReceiptListStats, listMyCashregisters, checkVoucherCombinationError, type SendReceiptEmailOptions, type SendReceiptEmailResult, sendReceiptEmail, type ReceiptOutputEntry, type LogReceiptOutputsOptions, type LogReceiptOutputsResult, type RejectedReceiptOutput, logReceiptOutputs, downloadDailyReport, downloadMonthlyReport, getCashregisterReport, type CashregisterReportPeriod, getReportV2, type ReportV2, type ReportV2Metadata, type ReportV2Options, listReceipts, listAllReceipts, fromListReceiptsSummaryPayload, LIST_RECEIPTS_VIEWS, LIST_RECEIPTS_ORDERS, LIST_RECEIPTS_LIMIT_MAX, LIST_RECEIPTS_DAYS_MAX, LIST_ALL_RECEIPTS_MAX_PAGES, LIST_RECEIPTS_ERROR_CODES, type ListReceiptsErrorCode, type ListReceiptsView, type ListReceiptsOrder, type ListReceiptsOptions, type ListReceiptsWindow, type ListReceiptsGrossByRate, type ListReceiptsSummary, type ListReceiptsDaySummary, type ListReceiptsPage, type ListedReceipt, type CashboxStatus, type SignatureStatus, getCashboxStatus, getSignatureStatus, type KasseneckApi, createKasseneckApi, } from './client/index.js';
-export { type ReceiptDueTip, type ReceiptDueTipRecipient, type ReceiptDueOptions, type ReceiptDueBuckets, type ReceiptDueBreakdown, type ReceiptDueErrorReason, receiptDueCents, receiptDueBreakdown, ReceiptDueError, RECEIPT_DUE_ERROR_REASONS, isReceiptDueError, type VoucherDueInfo, type VoucherDueArticle, type VoucherRedeemContext, voucherRedeemMaxCents, VOUCHER_ZERO_RATE_BUCKET_FROM, } from './receipt/due.js';
+export { type ReceiptDueTip, type ReceiptDueTipRecipient, type ReceiptDueOptions, type ReceiptDueBuckets, type ReceiptDueBreakdown, type ReceiptDueErrorReason, receiptDueCents, receiptDueBreakdown, ReceiptDueError, RECEIPT_DUE_ERROR_REASONS, isReceiptDueError, type VoucherDueInfo, type VoucherDueArticle, type VoucherDueType, type VoucherRedeemContext, voucherRedeemMaxCents, VOUCHER_ZERO_RATE_BUCKET_FROM, } from './receipt/due.js';
 export { parseServerTimeStamp, toViennaWallClock, type ViennaWallClock } from './vienna-time.js';
 export { type PosBusinessSettings, type PosDeviceSettings, type PosSettings, type ArticleGroup, type PosArticle, POS_BUSINESS_DEFAULTS, POS_DEVICE_DEFAULTS, mergePosSettings, fromArticleGroupPayload, fromPosArticlePayload, listMyArticleGroups, listMyArticles, getPosSettings, setMyPosSettings, setMyRegisterDeviceSettings, distributeDiscount, cancelScopeOf, receiptsScopeOf, stockViewOf, voucherPermsOf, } from './pos/index.js';

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

@@ -14,6 +14,12 @@ export interface Voucher {
     name?: string;
     code?: string;
     action: VoucherAction | string;
+    /**
+     * Art des Gutscheins. Beim Verkauf ueber eine Sorte die Art der Sorte
+     * (`PosVoucherType.kind`): der Server prueft sie gegen die Sorte und lehnt
+     * eine andere ab (`voucher_invalid`). Am Draht darf sie dort fehlen (die Art
+     * kommt dann aus der Sorte); ein so gelesener Wunsch geht ohne `type` hinaus.
+     */
     type: VoucherType | string;
     valueCents?: number;
     /** Neue Form: Betrag in Cent (Verkauf, Einloesung, Auszahlung). */
@@ -26,6 +32,18 @@ export interface Voucher {
     positions?: number[];
     /** Neue Form, Auszahlung: Grund, 1 bis 200 Zeichen. */
     reason?: string;
+    /**
+     * Neue Form, Wertgutschein verkaufen: die Gutschein-Sorte
+     * (`PosVoucherType.id` aus `getKasseSettings`). Pflicht fuer jeden Verkauf
+     * eines Mehrzweck- oder Einzweckgutscheins (Server: `voucher_type_required`),
+     * an jeder anderen Aktion oder Art verboten. Am gelesenen Eintrag die Sorte
+     * des Verkaufs (fehlt ohne Sorte).
+     */
+    typeId?: string;
+    /** Name der Sorte beim Verkauf (eingefroren). */
+    typeName?: string;
+    /** Auszahlung des verkauften Gutscheins (`allowed`/`never`, eingefroren). */
+    payout?: string;
     voucherType?: string;
     voucherId?: string;
     /** Letzte vier Zeichen des Codes; der Klartext steht nie am Beleg. */
@@ -53,8 +71,13 @@ export interface IssuedVoucher {
     quantity?: number;
     /** Nur bei Leistungsgutscheinen: Name des verkauften Artikels; sonst fehlt das Feld. */
     articleName?: string;
+    /** Verkauf ueber eine Sorte: ihre Kennung und ihr Name; sonst fehlen die Felder. */
+    typeId?: string;
+    typeName?: string;
     validity?: {
         pattern: string;
+        /** Sorte „N Jahre“: die Zahl N (Muster `1+3` fuer jedes N, die Daten gelten); fehlt sonst. */
+        redeemableYears?: number;
         redeemableUntil: string | null;
         refundableUntil: string | null;
         validUntil: string | null;
@@ -87,6 +110,9 @@ export interface VoucherPayload {
     quantity?: number;
     positions?: number[];
     reason?: string;
+    typeId?: string;
+    typeName?: string;
+    payout?: string;
     voucherType?: string;
     voucherId?: string;
     codeSuffix?: string;
@@ -100,10 +126,19 @@ export interface VoucherPayload {
 }
 /** 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"];
+/** Gehoert der Gutschein zur neuen Form (Art, Aktion `payout` oder Verkauf ueber eine Sorte ohne Art)? */
+export declare function isNewFormVoucher(voucher: Pick<Voucher, 'type' | 'action' | 'typeId'>): boolean;
+/**
+ * Wert-Verkauf: ein Mehrzweck- oder Einzweckgutschein wird verkauft (mit Art
+ * oder nur ueber die Sorte). Paketintern: Zahlbetrag und Pruefung vor dem
+ * Senden entscheiden daran, ob eine Sorte noetig ist.
+ */
+export declare function istWertVerkauf(voucher: Pick<Voucher, 'type' | 'action' | 'typeId'>): boolean;
+/**
+ * Felder, die nur der Server setzt; an einem Wunsch sind sie `voucher_invalid`.
+ * Sortenname und Auszahlung friert der Server beim Verkauf ein (Stufe 4b).
+ */
+export declare const GUTSCHEIN_SERVERFELDER: readonly ["voucherId", "codeSuffix", "zeroRateBucket", "voucherType", "typeName", "payout"];
 /** Welche Serverfelder tragt der Gutschein (leere Liste = keines)? */
 export declare function voucherServerFields(voucher: Voucher): string[];
 export declare function toVoucherPayload(voucher: Voucher): VoucherPayload;
@@ -115,3 +150,10 @@ export declare function toVoucherPayload(voucher: Voucher): VoucherPayload;
  */
 export declare function voucherIsValid(voucher: Voucher): boolean;
 export declare function fromVoucherPayload(payload: VoucherPayload): Voucher;
+/**
+ * Die Form eines Wunschs der neuen Form. `sorteNoetig: false` laesst einen
+ * Wert-Verkauf ohne `typeId` zu: so rechnet der Zahlbetrag den Verkauf eines
+ * Aufrufers bis 1.16 mit der alten Gutschein-Einstellung weiter (der Server ab
+ * Stufe 4b antwortet darauf `voucher_type_required`). Paketintern.
+ */
+export declare function wunschFormGueltig(v: Voucher, sorteNoetig: boolean): boolean;

package/dist/cjs/models/voucher.js

@@ -2,10 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GUTSCHEIN_SERVERFELDER = exports.NEUE_GUTSCHEINARTEN = void 0;
 exports.isNewFormVoucher = isNewFormVoucher;
+exports.istWertVerkauf = istWertVerkauf;
 exports.voucherServerFields = voucherServerFields;
 exports.toVoucherPayload = toVoucherPayload;
 exports.voucherIsValid = voucherIsValid;
 exports.fromVoucherPayload = fromVoucherPayload;
+exports.wunschFormGueltig = wunschFormGueltig;
 const index_js_1 = require("../enums/index.js");
 const money_js_1 = require("../money.js");
 const enum_payload_js_1 = require("./enum-payload.js");
@@ -16,23 +18,44 @@ exports.NEUE_GUTSCHEINARTEN = [
     index_js_1.VoucherType.service,
     index_js_1.VoucherType.promotion,
 ];
-/** Gehoert der Gutschein zur neuen Form (Art oder Aktion `payout`)? */
+/**
+ * Verkauf ueber eine Sorte ohne Art (`typeId` ohne `type`): die Art kommt aus
+ * der Sorte. Zwilling von `gutschein-beleg.istSortenVerkauf`.
+ */
+function istSortenVerkaufOhneArt(voucher) {
+    return voucher.action === index_js_1.VoucherAction.sell && voucher.type == null && voucher.typeId != null;
+}
+/** Gehoert der Gutschein zur neuen Form (Art, Aktion `payout` oder Verkauf ueber eine Sorte ohne Art)? */
 function isNewFormVoucher(voucher) {
-    return exports.NEUE_GUTSCHEINARTEN.includes(voucher.type) || voucher.action === index_js_1.VoucherAction.payout;
+    return exports.NEUE_GUTSCHEINARTEN.includes(voucher.type) || voucher.action === index_js_1.VoucherAction.payout || istSortenVerkaufOhneArt(voucher);
+}
+/**
+ * Wert-Verkauf: ein Mehrzweck- oder Einzweckgutschein wird verkauft (mit Art
+ * oder nur ueber die Sorte). Paketintern: Zahlbetrag und Pruefung vor dem
+ * Senden entscheiden daran, ob eine Sorte noetig ist.
+ */
+function istWertVerkauf(voucher) {
+    return voucher.action === index_js_1.VoucherAction.sell
+        && (voucher.type === index_js_1.VoucherType.multi_purpose || voucher.type === index_js_1.VoucherType.single_purpose || istSortenVerkaufOhneArt(voucher));
 }
-/** Felder, die nur der Server setzt; an einem Wunsch sind sie `voucher_invalid`. */
-exports.GUTSCHEIN_SERVERFELDER = ['voucherId', 'codeSuffix', 'zeroRateBucket', 'voucherType'];
+/**
+ * Felder, die nur der Server setzt; an einem Wunsch sind sie `voucher_invalid`.
+ * Sortenname und Auszahlung friert der Server beim Verkauf ein (Stufe 4b).
+ */
+exports.GUTSCHEIN_SERVERFELDER = ['voucherId', 'codeSuffix', 'zeroRateBucket', 'voucherType', 'typeName', 'payout'];
 /** 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',
+    'amountCents', 'articleId', 'quantity', 'positions', 'reason', 'typeId', 'typeName', 'payout', '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');
+    // Verkauf ueber eine Sorte ohne Art: `type` bleibt weg wie im Wunsch (die Art kommt aus der Sorte).
+    const ohneArt = istSortenVerkaufOhneArt(voucher);
+    const type = ohneArt ? undefined : (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;
@@ -42,7 +65,7 @@ function toVoucherPayload(voucher) {
             neu[feld] = roh[feld];
     return {
         action,
-        type,
+        ...(ohneArt ? {} : { 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 }),
@@ -95,11 +118,13 @@ function fromVoucherPayload(payload) {
         : payload.value != null
             ? (0, money_js_1.euroToCents)(payload.value)
             : undefined;
+    // Ein Verkaufswunsch ueber eine Sorte darf ohne Art sein: dann bleibt `type` weg (nicht `undefined`).
+    const ohneArt = payload.type == null && payload.action === index_js_1.VoucherAction.sell && payload.typeId != null;
     return {
         name: payload.name ?? undefined,
         code: payload.code ?? undefined,
         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),
+        ...(ohneArt ? {} : { type: (0, enum_payload_js_1.readEnumKey)(index_js_1.VoucherType, payload.type) }),
         valueCents,
         ...lesenNeu(payload),
     };
@@ -120,15 +145,31 @@ 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;
+/**
+ * Form einer Sorten-Kennung am Wunsch (gutschein-core.ID_MUSTER ohne den
+ * Ausschluss): eine reservierte `__…__` ist der Form nach gueltig, der Server
+ * kennt sie nur nicht (`voucher_type_not_found`), ebenso der Zahlbetrag.
+ */
+const SORTE_ID_FORM = /^[A-Za-z0-9_-]{1,128}$/;
 /**
  * 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
+ * (Einloesung), ein Wertgutschein wird nur ueber eine Sorte verkauft
+ * (`typeId`). Felder, die zu einer anderen Aktion/Art gehoeren, sind
  * ebenfalls nicht erlaubt (der Server wiese sie ab).
  */
 function newFormVoucherIsValid(v) {
+    return wunschFormGueltig(v, true);
+}
+/**
+ * Die Form eines Wunschs der neuen Form. `sorteNoetig: false` laesst einen
+ * Wert-Verkauf ohne `typeId` zu: so rechnet der Zahlbetrag den Verkauf eines
+ * Aufrufers bis 1.16 mit der alten Gutschein-Einstellung weiter (der Server ab
+ * Stufe 4b antwortet darauf `voucher_type_required`). Paketintern.
+ */
+function wunschFormGueltig(v, sorteNoetig) {
     if (voucherServerFields(v).length > 0)
         return false;
     const r = v;
@@ -138,6 +179,14 @@ function newFormVoucherIsValid(v) {
     }
     if (v.valueCents != null)
         return false;
+    // Die Sorte gehoert nur an einen Wert-Verkauf (Server: sorteId sonst voucher_invalid).
+    if (istWertVerkauf(v)) {
+        if (v.typeId == null ? sorteNoetig : (typeof v.typeId !== 'string' || !SORTE_ID_FORM.test(v.typeId)))
+            return false;
+        return v.articleId == null && v.quantity == null && v.positions == null && v.reason == null && istCent(v.amountCents);
+    }
+    if (v.typeId != 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
@@ -148,8 +197,6 @@ function newFormVoucherIsValid(v) {
     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;

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

@@ -88,6 +88,14 @@ export interface PosArticle {
      * traegt (aeltere Backends) -- dann nicht aus anderen Feldern ableiten.
      */
     stockTracked?: boolean | null;
+    /**
+     * Als Leistungsgutschein verkaufbar (Gutscheine Stufe 4b, Haken im
+     * Artikelstamm). Die Kachel „Leistungsgutschein“ bietet nur diese Artikel
+     * an; der Server verkauft einen anderen nicht (`voucher_service_not_allowed`).
+     * Optional wie `stockLocationIds`, der Leser setzt es immer: nur ein
+     * ausdrueckliches `true` gilt.
+     */
+    serviceVoucher?: boolean;
 }
 /** Deckelt eine gewuenschte Menge an der Hoechstmenge des Artikels (null = keine Grenze). */
 export declare function allowedQuantity(a: Pick<PosArticle, 'maxQuantity'>, wanted: number): number;
@@ -113,6 +121,7 @@ export interface PosArticlePayload {
     ean?: string | null;
     internalCode?: string | null;
     stockTracked?: boolean | null;
+    serviceVoucher?: boolean | null;
 }
 export declare function fromPosArticlePayload(p: PosArticlePayload): PosArticle;
 /**

package/dist/cjs/pos/artikel.js

@@ -82,6 +82,7 @@ function fromPosArticlePayload(p) {
         ean: textOderNull(p.ean),
         internalCode: textOderNull(p.internalCode),
         stockTracked: typeof p.stockTracked === 'boolean' ? p.stockTracked : null,
+        serviceVoucher: p.serviceVoucher === true,
     };
 }
 /**

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

@@ -15,10 +15,27 @@ 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';
+    /**
+     * Gutschein einer Sorte „N Jahre einloesbar, danach 3 Jahre Rueckzahlung“:
+     * die Zahl N (1 bis 30); `pattern` ist dann `1+3` fuer jedes N. Fehlt bei
+     * Gutscheinen ohne Sorte und bei unbefristeten. Die Daten stehen trotzdem in
+     * `redeemableUntil` (+N) und `refundableUntil` (+N+3) und gelten.
+     */
+    redeemableYears?: number;
     redeemableUntil?: string;
     refundableUntil?: string;
     validUntil?: string;
 }
+/** Auszahlung eines Gutscheins bzw. einer Sorte: erlaubt oder nie (nur bei unbefristeter Gueltigkeit). */
+export type VoucherPayout = 'allowed' | 'never';
+/** Art einer Gutschein-Sorte: nur Wertgutscheine (Leistung und Aktion sind keine Sorte). */
+export type VoucherTypeKind = 'multi_purpose' | 'single_purpose';
+export declare const VOUCHER_PAYOUTS: readonly VoucherPayout[];
+export declare const VOUCHER_TYPE_KINDS: readonly VoucherTypeKind[];
+/** Betrag einer Sorte: frei an der Kasse eingegeben oder fest. */
+export declare const VOUCHER_AMOUNT_MODES: readonly ('free' | 'fixed')[];
+/** Gueltigkeit einer Sorte: unbefristet oder N Jahre (das Muster der Sorte, nicht das eines Gutscheins). */
+export declare const VOUCHER_TYPE_VALIDITY_PATTERNS: readonly ('unlimited' | 'years')[];
 /** Der Artikel eines Dienstleistungsgutscheins. */
 export interface VoucherArticle {
     id: string;
@@ -50,12 +67,92 @@ export interface VoucherCheck {
      * inzwischen steuerpflichtigen Konto. Fehlt bei aelteren Servern.
      */
     exempt?: boolean;
+    /** Name der Sorte, mit der der Gutschein verkauft wurde (beim Verkauf eingefroren); fehlt ohne Sorte. */
+    typeName?: string;
+    /**
+     * Auszahlung dieses Gutscheins (beim Verkauf eingefroren); fehlt ohne
+     * Sorte. Bei `never` lehnt der Server jede Auszahlung ab
+     * (`voucher_payout_not_allowed`); Einloesen geht unveraendert.
+     */
+    payout?: VoucherPayout;
+}
+/**
+ * Etikett-Vorlage in der `/v3`-Form (Groesse, Layout, Drehung, Felder,
+ * Freitext). Das Paket zeichnet keine Etiketten: es reicht die Vorlage als
+ * Kopie durch, gezeichnet wird in der Kasse (druck-kit, Kassen-App). Weitere
+ * Schluessel eines neueren Servers bleiben erhalten.
+ */
+export interface VoucherLabelTemplate {
+    /** Etikettgroesse `BxH` in mm, z. B. `40x30`. */
+    size: string;
+    layout: string;
+    /** 0 oder 90 (Grad); fehlt = 0. */
+    rotation?: number;
+    fields?: Record<string, boolean>;
+    freeText?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Gutschein-Sorte (Gutscheine Stufe 4b): eine Kachel im Reiter „Gutscheine“.
+ * Die Kasse bekommt nur verkaufbare Sorten (aktiv und gueltig), in
+ * Kachelfolge. Verkauft wird ein Wertgutschein nur ueber eine Sorte:
+ * `{ action: 'sell', type: kind, typeId: id, amountCents }` (bei `fixed` genau
+ * `amount.cents`); Art, Satz, Gueltigkeit und Auszahlung nimmt der Server aus
+ * der Sorte und friert sie am Gutschein ein.
+ */
+export interface PosVoucherType {
+    id: string;
+    name: string;
+    kind: VoucherTypeKind;
+    /** Satz in Basispunkten, nur bei Einzweck (> 0); Mehrzweck `null`. */
+    vatRateBp: number | null;
+    /** Betrag: frei (Zahlenfeld) oder fest (sofort in den Korb), Cent ganzzahlig. */
+    amount: {
+        mode: 'free';
+    } | {
+        mode: 'fixed';
+        cents: number;
+    };
+    /** Unbefristet oder N Jahre einloesbar, danach 3 Jahre Rueckzahlung (N 1 bis 30). */
+    validity: {
+        pattern: 'unlimited';
+    } | {
+        pattern: 'years';
+        years: number;
+    };
+    payout: VoucherPayout;
+    /** Wirksame Vorlage der Sorte (eigene, sonst die Standardvorlage); `null`, wenn die Antwort keine brauchbare traegt. */
+    label: VoucherLabelTemplate | null;
+    order: number;
+    active: boolean;
+    /** Verkaufte Gutscheine dieser Sorte (nur zur Anzeige). */
+    soldCount: number;
 }
-/** Gutschein-Einstellungen der Kasse (Block `vouchers` aus `getKasseSettings`). */
+/**
+ * Gutschein-Einstellungen der Kasse (Block `vouchers` aus `getKasseSettings`).
+ *
+ * Seit Gutscheine Stufe 4b verkauft eine Kasse ueber Sorten: Reiter und
+ * Kacheln zeigt sie mit `typeSale` (und dem Recht `voucherSell`), je Sorte aus
+ * `types` und die feste Kachel „Leistungsgutschein“ mit `serviceArticles`.
+ * `sale`, `valueVoucherType` und `vatRateBp` gelten nur Kassen vor 1.17; der
+ * Server schickt `sale` immer als `false`.
+ *
+ * Die vier neuen Felder sind optional, damit bestehende Literale von
+ * Verbrauchern weiter uebersetzen; der Leser ([posVoucherSettingsFromWire])
+ * setzt sie immer.
+ */
 export interface PosVoucherSettings {
     sale: boolean;
     valueVoucherType: 'multi_purpose' | 'single_purpose' | null;
     vatRateBp: number | null;
+    /** Gutscheine verkaufen (Reiter „Gutscheine“): Schalter des Servers und mindestens eine Sorte oder ein Leistungsartikel. */
+    typeSale?: boolean;
+    /** Verkaufbare Sorten in Kachelfolge. */
+    types?: PosVoucherType[];
+    /** Es gibt aktive Artikel, die als Leistungsgutschein freigegeben sind (`PosArticle.serviceVoucher`). */
+    serviceArticles?: boolean;
+    /** Standardvorlage des Etiketts (Leistungsgutschein, Notausgang); `null` ohne brauchbare Vorlage. */
+    labelDefault?: VoucherLabelTemplate | null;
 }
 /** Ohne Block `vouchers` (alter Server, Konto ohne Schalter): Verkaufen ist aus. */
 export declare const VOUCHER_SETTINGS_DEFAULTS: Readonly<PosVoucherSettings>;
@@ -67,7 +164,15 @@ export declare const VOUCHER_SETTINGS_DEFAULTS: Readonly<PosVoucherSettings>;
  * `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.
+ * eine Art behalten. `typeSale` und `serviceArticles` sind Wahrheitswerte,
+ * `types` eine Liste (fehlen sie, antwortet ein aelterer Server: aus, leer).
+ *
+ * Sorten (Gutscheine Stufe 4b) liest der Leser einzeln: eine unstimmige Sorte
+ * faellt weg ([sorteVomDraht]), die anderen bleiben; ist danach weder eine
+ * Sorte noch ein Leistungsartikel da, ist `typeSale` aus (kein leerer Reiter).
+ * Eine unbrauchbare Etikett-Vorlage schliesst nichts: sie wird `null`, die
+ * Kasse druckt dann ihren Standard (ein Verkauf scheitert nie an der Vorlage).
+ * Das alte Feld `label` (Kassen vor 1.17, Ruling R3) liest das Paket nicht.
  */
 export declare function posVoucherSettingsFromWire(block: unknown): PosVoucherSettings;
 /**