@kreiseck/kasseneck-api 1.11.0 → 1.12.0

package/dist/esm/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/esm/models/voucher.js

@@ -1,13 +1,46 @@
 import { VoucherAction, VoucherType } from '../enums/index.js';
 import { euroToCents } from '../money.js';
 import { readEnumKey, requireEnumKey } from './enum-payload.js';
+/** Arten der neuen Gutscheinform (die Altwerte sind `value` und `promo`). */
+export const NEUE_GUTSCHEINARTEN = [
+    VoucherType.multi_purpose,
+    VoucherType.single_purpose,
+    VoucherType.service,
+    VoucherType.promotion,
+];
+/** Gehoert der Gutschein zur neuen Form (Art oder Aktion `payout`)? */
+export function isNewFormVoucher(voucher) {
+    return NEUE_GUTSCHEINARTEN.includes(voucher.type) || voucher.action === VoucherAction.payout;
+}
+/** Felder, die nur der Server setzt; an einem Wunsch sind sie `voucher_invalid`. */
+export const GUTSCHEIN_SERVERFELDER = ['voucherId', 'codeSuffix', 'zeroRateBucket', 'voucherType'];
+/** Welche Serverfelder tragt der Gutschein (leere Liste = keines)? */
+export function voucherServerFields(voucher) {
+    return 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',
+];
 export function toVoucherPayload(voucher) {
+    const action = requireEnumKey(VoucherAction, voucher.action, 'Gutschein-Aktion');
+    const type = requireEnumKey(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: requireEnumKey(VoucherAction, voucher.action, 'Gutschein-Aktion'),
-        type: requireEnumKey(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,
     };
 }
 /**
@@ -17,6 +50,8 @@ export function toVoucherPayload(voucher) {
  * gesetzter Wert muss positiv sein.
  */
 export function voucherIsValid(voucher) {
+    if (isNewFormVoucher(voucher))
+        return newFormVoucherIsValid(voucher);
     if (voucher.type === VoucherType.value && voucher.valueCents == null) {
         return false;
     }
@@ -58,5 +93,75 @@ export function fromVoucherPayload(payload) {
         action: readEnumKey(VoucherAction, payload.action),
         type: readEnumKey(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 === VoucherType.multi_purpose || v.type === VoucherType.single_purpose;
+    if (v.action === 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 === VoucherAction.sell)
+            return istCent(v.amountCents);
+        if (v.action === VoucherAction.redeem)
+            return hatText(v.code) && istCent(v.amountCents);
+        return false;
+    }
+    if (v.type === VoucherType.service) {
+        if (v.amountCents != null)
+            return false;
+        if (v.action === VoucherAction.sell) {
+            return hatText(v.articleId) && istMenge(v.quantity) && v.positions == null;
+        }
+        if (v.action === 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 === VoucherType.promotion) {
+        return v.action === 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/esm/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/esm/partner/fehler.js

@@ -101,6 +101,7 @@ export const PARTNER_ERROR_CODES = [
     'text_changed',
     'already_accepted',
     'activation_failed',
+    'activation_in_progress',
     // Webhooks
     'webhook_limit',
     'webhook_inactive',
@@ -208,6 +209,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/esm/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/esm/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/esm/partner/typen.js

@@ -97,6 +97,9 @@ export const 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/esm/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/esm/pos/client.js

@@ -1,4 +1,5 @@
 import { KasseneckValidationError } from '../client/errors.js';
+import { posVoucherSettingsFromWire } from './gutschein.js';
 import { POS_BUSINESS_DEFAULTS, POS_DEVICE_DEFAULTS, POS_BUSINESS_VALUES, POS_DEVICE_VALUES, POS_SHORTCUT_ACTIONS, POS_DEVICE_OPTIONAL_FIELDS, POS_BUSINESS_OPTIONAL_FIELDS, mergePosSettings, posShortcutConflict, _istAltwert0x, _optionalerWert, } from './settings.js';
 /*
  * Die Einstellungs-Aufrufe am Draht `/api/v3`: Parameter und Antwort heissen
@@ -27,9 +28,10 @@ export 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. */
 export function posSettingsFromWire(data) {
     return {
+        vouchers: posVoucherSettingsFromWire(data?.vouchers),
         business: mergePosSettings(POS_BUSINESS_DEFAULTS, objekt(data?.business)),
         device: mergePosSettings(POS_DEVICE_DEFAULTS, objekt(data?.device)),
     };

package/dist/esm/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;
+}>;

package/dist/esm/pos/gutschein.js

@@ -0,0 +1,158 @@
+import { VoucherCode } from '@kreiseck/validator';
+import { KasseneckApiError, KasseneckValidationError } from '../client/errors.js';
+export const VOUCHER_KINDS = Object.freeze(['multi_purpose', 'single_purpose', 'service', 'promotion']);
+export const VOUCHER_STATUSES = Object.freeze(['active', 'used_up', 'expired', 'paid_out', 'cancelled', 'blocked']);
+const VOUCHER_VALIDITY_PATTERNS = ['unlimited', '1+3', 'custom'];
+/** Ohne Block `vouchers` (alter Server, Konto ohne Schalter): Verkaufen ist aus. */
+export const VOUCHER_SETTINGS_DEFAULTS = Object.freeze({
+    sale: false, valueVoucherType: null, vatRateBp: null,
+});
+/**
+ * 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 function posVoucherSettingsFromWire(block) {
+    const zu = () => ({ ...VOUCHER_SETTINGS_DEFAULTS });
+    if (block === null || typeof block !== 'object' || Array.isArray(block))
+        return zu();
+    const b = block;
+    const sale = b['sale'];
+    const art = b['valueVoucherType'] ?? null;
+    const satz = b['vatRateBp'] ?? null;
+    if (typeof sale !== 'boolean')
+        return zu();
+    if (art !== null && art !== 'multi_purpose' && art !== 'single_purpose')
+        return zu();
+    if (satz !== null && !(typeof satz === 'number' && Number.isInteger(satz) && satz >= 0))
+        return zu();
+    if (sale && art === null)
+        return zu();
+    if (art === 'single_purpose' && satz === null)
+        return zu();
+    if (art === 'multi_purpose' && satz !== null)
+        return zu();
+    return { sale, valueVoucherType: art, vatRateBp: satz };
+}
+function fehler(name, grund) {
+    return new KasseneckValidationError(name, `Antwort: ${grund}`, 'response');
+}
+function objekt(name, pfad, w) {
+    if (w === null || typeof w !== 'object' || Array.isArray(w))
+        throw fehler(name, `${pfad} ist kein Objekt`);
+    return w;
+}
+const fehlt = (w) => w === undefined || w === null;
+function ganzzahlWennDa(name, pfad, ziel, o, feld) {
+    const w = o[feld];
+    if (fehlt(w))
+        return;
+    if (typeof w !== 'number' || !Number.isSafeInteger(w))
+        throw fehler(name, `${pfad}.${feld} ist keine ganze Zahl`);
+    ziel[feld] = w;
+}
+function textPflicht(name, pfad, o, feld) {
+    const w = o[feld];
+    if (typeof w !== 'string' || w === '')
+        throw fehler(name, `${pfad}.${feld} fehlt`);
+    return w;
+}
+function wahl(name, pfad, o, feld, erlaubt) {
+    const w = o[feld];
+    if (typeof w !== 'string' || !erlaubt.includes(w))
+        throw fehler(name, `${pfad}.${feld} ist unbekannt`);
+    return w;
+}
+function gueltigkeit(name, w) {
+    const o = objekt(name, 'validity', w);
+    const raus = { pattern: wahl(name, 'validity', o, 'pattern', VOUCHER_VALIDITY_PATTERNS) };
+    for (const feld of ['redeemableUntil', 'refundableUntil', 'validUntil']) {
+        const t = o[feld];
+        if (fehlt(t))
+            continue;
+        if (typeof t !== 'string' || t === '')
+            throw fehler(name, `validity.${feld} ist kein Datum`);
+        raus[feld] = t;
+    }
+    return raus;
+}
+function artikel(name, w) {
+    const o = objekt(name, 'article', w);
+    const raus = { id: textPflicht(name, 'article', o, 'id'), name: textPflicht(name, 'article', o, 'name') };
+    for (const feld of ['vatRateBp', 'priceCents']) {
+        const z = o[feld];
+        if (typeof z !== 'number' || !Number.isSafeInteger(z))
+            throw fehler(name, `article.${feld} ist keine ganze Zahl`);
+        raus[feld] = z;
+    }
+    return raus;
+}
+function leseCheck(name, w) {
+    const o = objekt(name, 'data', w);
+    const raus = {
+        type: wahl(name, 'data', o, 'type', VOUCHER_KINDS),
+        status: wahl(name, 'data', o, 'status', VOUCHER_STATUSES),
+        codeSuffix: textPflicht(name, 'data', o, 'codeSuffix'),
+    };
+    for (const feld of ['balanceCents', 'faceValueCents', 'quantity', 'remainingQuantity', 'vatRateBp', 'discountCents', 'discountPercentBp']) {
+        ganzzahlWennDa(name, 'data', raus, o, feld);
+    }
+    if (!fehlt(o.article))
+        raus.article = artikel(name, o.article);
+    if (!fehlt(o.validity))
+        raus.validity = gueltigkeit(name, o.validity);
+    if (!fehlt(o.exempt)) {
+        if (typeof o.exempt !== 'boolean')
+            throw fehler(name, 'data.exempt ist kein Wahrheitswert');
+        raus.exempt = o.exempt;
+    }
+    return raus;
+}
+/**
+ * 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 async function checkVoucher(transport, code) {
+    const name = 'checkVoucher';
+    const geprueft = typeof code === 'string' ? VoucherCode.validate(code) : null;
+    // Der Code steht bewusst nicht in der Meldung.
+    if (!geprueft || !geprueft.ok)
+        throw new KasseneckValidationError(name, 'code ist kein gueltiger Gutscheincode', 'request');
+    // Der Code reist im Rumpf: als Geheimnis nennen, damit er in keinem Fehler (Servertext, Ursache) auftaucht.
+    const geheim = [geprueft.normalized, VoucherCode.format(geprueft.normalized)];
+    let antwort;
+    try {
+        antwort = await transport(name, { code: geprueft.normalized }, undefined, geheim);
+    }
+    catch (fehler) {
+        // Der Transport siebt nur Ursachen; ein Servertext, der den Code wiederholt, wird hier geschwaerzt.
+        if (fehler instanceof KasseneckApiError && geheim.some((g) => fehler.serverMessage.includes(g))) {
+            const text = geheim.reduce((t, g) => t.split(g).join('****'), fehler.serverMessage);
+            throw new KasseneckApiError(name, text, fehler.details, fehler.code);
+        }
+        throw fehler;
+    }
+    return leseCheck(name, antwort);
+}
+/**
+ * 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 async function reprintVoucherLabel(transport, id) {
+    const name = 'reprintVoucherLabel';
+    if (typeof id !== 'string' || id.trim() === '')
+        throw new KasseneckValidationError(name, 'id fehlt', 'request');
+    const o = objekt(name, 'data', await transport(name, { id }));
+    return { code: textPflicht(name, 'data', o, 'code') };
+}

package/dist/esm/pos/index.d.ts

@@ -11,15 +11,16 @@ export { type ArticleGroup, type ArticleGroupPayload, fromArticleGroupPayload, t
 export { getPosSettings, setMyPosSettings, setMyRegisterDeviceSettings, setMyPosLogo, posSettingsFromWire, type SetMyPosLogoOptions, } from './client.js';
 export { POS_ERROR_CODES, type PosErrorCode, isPosErrorCode, posErrorCode, isPosError, type PosFieldError, posFieldErrors, } from './errors.js';
 export { distributeDiscount } from '../receipt/discount.js';
-export { cancelScopeOf, receiptsScopeOf, stockViewOf, type RegisterScope, type RegisterUserPerms } from '../register/pairing.js';
+export { cancelScopeOf, receiptsScopeOf, stockViewOf, voucherPermsOf, type VoucherPerms, type RegisterScope, type RegisterUserPerms } from '../register/pairing.js';
 export { type NetworkPrinter, type PrintJob, type PrintJobStatus, PRINT_JOB_STATUSES, type PrintJobSource, PRINT_JOB_SOURCES, isPrintJobFinished, type CreatePrintJobOptions, listMyPrinters, createPrintJob, getPrintJob, } from './drucker.js';
 export { listMyTipRecipients } from './trinkgeld.js';
 export { STOCK_LOCATION_TYPES, type StockLocationType, type StockLocation, type StockLocationAddress, type StockLevel, type StockValue, type StockList, type ListMyStockOptions, type SetMyCashregisterStockLocationOptions, type CashregisterStockLocation, listMyStockLocations, listMyStock, setMyCashregisterStockLocation, } from './lager.js';
 export { type ListMyStocktakesOptions, type ListMyStocktakeItemsOptions, type ListMyStocktakeCountsOptions, type RecordMyStocktakeCountOptions, type VoidMyStocktakeCountOptions, listMyStocktakes, listMyStocktakeItems, listMyStocktakeCounts, recordMyStocktakeCount, voidMyStocktakeCount, parseQuantityMilli, } from './inventur.js';
 export type { Stocktake, StocktakeItem, StocktakeCount, StocktakeCountResult, StocktakeItemPage, StocktakeCountPage, StocktakeActor, StocktakeProgress, StocktakeReview, StocktakeRecount, StocktakeScope, } from '../inventory/typen.js';
 export type { StocktakeStatus } from '../inventory/vertrag.js';
+export { VOUCHER_KINDS, VOUCHER_STATUSES, checkVoucher, reprintVoucherLabel, VOUCHER_SETTINGS_DEFAULTS, posVoucherSettingsFromWire, type VoucherKind, type VoucherStatus, type VoucherValidity, type VoucherArticle, type VoucherCheck, type PosVoucherSettings, } from './gutschein.js';
 export { type GetMyDrawerStateOptions, type OpenMyShiftOptions, type RecordMyCashMovementOptions, type DrawerOpeningEntry, type LogMyDrawerOpeningsOptions, type GetMyShiftReportOptions, type TipPayout, type CloseMyShiftOptions, type AfterCountOption, getMyDrawerState, openMyShift, recordMyCashMovement, logMyDrawerOpenings, getMyShiftReport, closeMyShift, sumDenominations, parseCentsAllowZero, newIdempotencyKey, shiftTipLines, durationText, type ShiftTipLine, type ShiftTipLineKey, } from './schicht.js';
 export { EUR_DENOMINATIONS, MOVEMENT_TYPES, MANUAL_MOVEMENT_TYPES, CASH_LOCATIONS, OPENING_REASONS, MANUAL_OPENING_REASONS, SHIFT_RECEIPT_KINDS, AFTER_COUNT_TYPES, type AfterCountType, type AfterCount, type EurDenomination, type MovementType, type ManualMovementType, type CashLocation, type OpeningReason, type ManualOpeningReason, type ShiftReceiptKind, type ShiftStatus, type ShiftActorRole, type Denominations, type ShiftActor, type DrawerInfo, type DrawerRights, type NonCashAmount, type ShiftTipTotals, type ShiftTip, type ShiftRunningTotals, type ShiftReconciliation, type Shift, type TipClaim, type DrawerOpening, type DrawerState, type CashMovement, type ShiftReceiptHeader, type ShiftReceiptMovement, type ShiftReceiptTip, type ShiftSummaryReceipt, type CashMovementReceipt, type ShiftReceipt, type OpenShiftResult, type CashMovementResult, type DrawerOpeningsResult, type ShiftReport, type CloseShiftResult, } from './schicht-typen.js';
 export { type ShiftReceiptLayoutOptions, shiftReceiptLayout, cashMovementLayout } from '../receipt/shift-sheet.js';
 export { RETURN_DISPOSITIONS, isReturnDisposition, type ReturnDisposition } from '../models/cancellation.js';
-export { MESSAGES, ERROR_RULES, ERROR_CODE_RULES, ERROR_OUTCOME_RULES, CALLS_WITH_EFFECT, findErrorRule, messageOutcome, messageText, messageAppliesTo, RECEIPT_EMAIL_ERROR_MESSAGES, receiptEmailErrorMessage, CANCELLATION_PAYMENT_ERROR_MESSAGES, cancellationPaymentErrorMessage, LABELS, labelText, RETURN_DISPOSITION_LABELS, type TextEntry, type MessageKey, type ErrorKind, type ErrorRule, type ErrorRuleDetail, type Surface, type ReceiptEmailMessageCode, type CancellationPaymentMessageCode, type LabelKey, } from './texte.js';
+export { MESSAGES, ERROR_RULES, ERROR_CODE_RULES, ERROR_OUTCOME_RULES, CALLS_WITH_EFFECT, findErrorRule, messageOutcome, messageText, messageAppliesTo, RECEIPT_EMAIL_ERROR_MESSAGES, receiptEmailErrorMessage, CANCELLATION_PAYMENT_ERROR_MESSAGES, cancellationPaymentErrorMessage, VOUCHER_ERROR_MESSAGES, voucherErrorMessage, LABELS, labelText, RETURN_DISPOSITION_LABELS, type TextEntry, type MessageKey, type ErrorKind, type ErrorRule, type ErrorRuleDetail, type Surface, type ReceiptEmailMessageCode, type CancellationPaymentMessageCode, type LabelKey, } from './texte.js';

package/dist/esm/pos/index.js

@@ -15,11 +15,13 @@ export { POS_ERROR_CODES, isPosErrorCode, posErrorCode, isPosError, posFieldErro
 export { distributeDiscount } from '../receipt/discount.js';
 // Reichweiten der Kassen-Rechte (Migration wie im Backend) -- bewusst NICHT im
 // Register-Unterpfad: dessen Exportnamen sind 1:1 Function-Namen (Rewrites).
-export { cancelScopeOf, receiptsScopeOf, stockViewOf } from '../register/pairing.js';
+export { cancelScopeOf, receiptsScopeOf, stockViewOf, voucherPermsOf } from '../register/pairing.js';
 export { PRINT_JOB_STATUSES, PRINT_JOB_SOURCES, isPrintJobFinished, listMyPrinters, createPrintJob, getPrintJob, } from './drucker.js';
 export { listMyTipRecipients } from './trinkgeld.js';
 export { STOCK_LOCATION_TYPES, listMyStockLocations, listMyStock, setMyCashregisterStockLocation, } from './lager.js';
 export { listMyStocktakes, listMyStocktakeItems, listMyStocktakeCounts, recordMyStocktakeCount, voidMyStocktakeCount, parseQuantityMilli, } from './inventur.js';
+// Gutschein pruefen und Etikett nachdrucken an der Kasse.
+export { VOUCHER_KINDS, VOUCHER_STATUSES, checkVoucher, reprintVoucherLabel, VOUCHER_SETTINGS_DEFAULTS, posVoucherSettingsFromWire, } from './gutschein.js';
 // Schicht, Kassenstand und Lade-Protokoll (1.9.0): Aufrufe, Kataloge, Helfer, Bons.
 export { getMyDrawerState, openMyShift, recordMyCashMovement, logMyDrawerOpenings, getMyShiftReport, closeMyShift, sumDenominations, parseCentsAllowZero, newIdempotencyKey, shiftTipLines, durationText, } from './schicht.js';
 export { EUR_DENOMINATIONS, MOVEMENT_TYPES, MANUAL_MOVEMENT_TYPES, CASH_LOCATIONS, OPENING_REASONS, MANUAL_OPENING_REASONS, SHIFT_RECEIPT_KINDS, AFTER_COUNT_TYPES, } from './schicht-typen.js';
@@ -27,4 +29,4 @@ export { shiftReceiptLayout, cashMovementLayout } from '../receipt/shift-sheet.j
 // Rueckgabe-Wahl beim Storno (Kassen-Dialog); dieselbe Liste wie an der Wurzel.
 export { RETURN_DISPOSITIONS, isReturnDisposition } from '../models/cancellation.js';
 // Was die Kasse selbst sagt: ein Katalog fuer Browser-Kasse und App.
-export { MESSAGES, ERROR_RULES, ERROR_CODE_RULES, ERROR_OUTCOME_RULES, CALLS_WITH_EFFECT, findErrorRule, messageOutcome, messageText, messageAppliesTo, RECEIPT_EMAIL_ERROR_MESSAGES, receiptEmailErrorMessage, CANCELLATION_PAYMENT_ERROR_MESSAGES, cancellationPaymentErrorMessage, LABELS, labelText, RETURN_DISPOSITION_LABELS, } from './texte.js';
+export { MESSAGES, ERROR_RULES, ERROR_CODE_RULES, ERROR_OUTCOME_RULES, CALLS_WITH_EFFECT, findErrorRule, messageOutcome, messageText, messageAppliesTo, RECEIPT_EMAIL_ERROR_MESSAGES, receiptEmailErrorMessage, CANCELLATION_PAYMENT_ERROR_MESSAGES, cancellationPaymentErrorMessage, VOUCHER_ERROR_MESSAGES, voucherErrorMessage, LABELS, labelText, RETURN_DISPOSITION_LABELS, } from './texte.js';

package/dist/esm/pos/settings.d.ts

@@ -11,6 +11,7 @@
  * derselben Werte liegt unter `fixtures/stored/`. Trinkgeld ist bewusst AUS,
  * bis die Buchung geklaert ist (Spec kachel-kasse § 9).
  */
+import { type PosVoucherSettings } from './gutschein.js';
 export declare const THEME: readonly ["clear", "warm", "night", "contrast"];
 export type PosTheme = typeof THEME[number];
 export declare const FONT_SIZE: readonly ["S", "M", "L", "XL"];
@@ -268,6 +269,8 @@ export interface PosDeviceSettings {
 export interface PosSettings {
     business: PosBusinessSettings;
     device: PosDeviceSettings;
+    /** Gutschein-Verkauf der Kasse (Block `vouchers`); ohne Block ist Verkaufen aus. */
+    vouchers: PosVoucherSettings;
 }
 export declare const POS_BUSINESS_DEFAULTS: Readonly<PosBusinessSettings>;
 export declare const POS_DEVICE_DEFAULTS: Readonly<PosDeviceSettings>;