@kreiseck/kasseneck-api 1.10.1 → 1.11.0

package/dist/esm/pos/schicht.js

@@ -0,0 +1,222 @@
+import { KasseneckValidationError } from '../client/errors.js';
+import { anfrage, schluessel } from '../inventory/schreiben.js';
+import { abschluss, bericht, gebucht, geoeffnet, gemeldet, ladeStand } from './schicht-lesen.js';
+import { labelText } from './texte.js';
+import { CASH_LOCATIONS, EUR_DENOMINATIONS, } from './schicht-typen.js';
+const antwort = (name) => ({ name, pfad: '', scope: 'response' });
+function anfragefehler(name, grund) {
+    return new KasseneckValidationError(name, grund, 'request');
+}
+/** Eine Kennung, die gesendet werden muss. */
+function kennung(name, p, feld) {
+    const w = p[feld];
+    if (typeof w !== 'string' || w.trim() === '')
+        throw anfragefehler(name, `${feld} fehlt`);
+}
+/** Ein Betrag in Cent: ganze Zahl, sonst wirft der Aufruf vor dem Senden. */
+function cent(name, feld, w) {
+    if (typeof w !== 'number' || !Number.isSafeInteger(w))
+        throw anfragefehler(name, `${feld} muss eine ganze Zahl (Cent) sein`);
+}
+function stueckelungPruefen(name, p) {
+    const w = p.denominations;
+    if (w === undefined || w === null)
+        return;
+    if (typeof w !== 'object' || Array.isArray(w))
+        throw anfragefehler(name, 'denominations muss eine Karte Wert -> Anzahl sein');
+    for (const [k, anzahl] of Object.entries(w))
+        cent(name, `denominations.${k}`, anzahl);
+}
+async function rufe(transport, name, p, lese) {
+    return lese(antwort(name), await transport(name, p));
+}
+/** Stand der Lade: Rechte, offene Schicht, Trinkgeld-Ansprueche und (mit `cashView`) Soll und letzte Oeffnungen. */
+export async function getMyDrawerState(transport, options = {}) {
+    const name = 'getMyDrawerState';
+    const p = anfrage(name, options);
+    if (p.drawerId === '')
+        delete p.drawerId;
+    return rufe(transport, name, p, ladeStand);
+}
+/** Schicht oeffnen: gezaehltes Startgeld oder den Bestand uebernehmen (Recht `shift`). */
+export async function openMyShift(transport, options) {
+    const name = 'openMyShift';
+    const p = anfrage(name, options);
+    kennung(name, p, 'drawerId');
+    schluessel(name, p, { pflicht: true });
+    if (p.openingFloatCents !== undefined)
+        cent(name, 'openingFloatCents', p.openingFloatCents);
+    stueckelungPruefen(name, p);
+    return rufe(transport, name, p, geoeffnet);
+}
+/** Ein- oder Auszahlung buchen (Recht `cashMove`); Antwort mit den Bon-Daten „Kassenbewegung“. */
+export async function recordMyCashMovement(transport, options) {
+    const name = 'recordMyCashMovement';
+    const p = anfrage(name, options);
+    kennung(name, p, 'drawerId');
+    schluessel(name, p, { pflicht: true });
+    cent(name, 'amountCents', p.amountCents);
+    // Nur pruefen, wenn gesetzt: Bank/Tresor fragt die Kasse nicht mehr ab.
+    if (p.location !== undefined && !CASH_LOCATIONS.includes(p.location)) {
+        throw anfragefehler(name, `location muss ${CASH_LOCATIONS.join(' oder ')} sein`);
+    }
+    return rufe(transport, name, p, gebucht);
+}
+/** Oeffnungen der Lade melden (auch nachgesendet); doppelt gemeldete zaehlen einmal. */
+export async function logMyDrawerOpenings(transport, options) {
+    const name = 'logMyDrawerOpenings';
+    const p = anfrage(name, options);
+    kennung(name, p, 'drawerId');
+    const eintraege = p.entries;
+    if (!Array.isArray(eintraege) || eintraege.length === 0)
+        throw anfragefehler(name, 'entries muss 1–50 Eintraege haben');
+    eintraege.forEach((e, i) => {
+        const k = e !== null && typeof e === 'object' ? e.idempotencyKey : undefined;
+        if (typeof k !== 'string' || k.trim() === '')
+            throw anfragefehler(name, `entries[${i}].idempotencyKey fehlt`);
+    });
+    return rufe(transport, name, p, gemeldet);
+}
+/** Bericht der Schicht: Schicht, Bewegungen und Bon-Daten (X-Bon, bei geschlossener Schicht der Z-Bon). */
+export async function getMyShiftReport(transport, options) {
+    const name = 'getMyShiftReport';
+    const p = anfrage(name, options);
+    kennung(name, p, 'shiftId');
+    return rufe(transport, name, p, bericht);
+}
+/**
+ * Schicht schliessen (Recht `shift`). `status: 'recount'` heisst: bitte noch
+ * einmal zaehlen und erneut senden (kein Fehler); nach dem zweiten Zaehlen
+ * schliesst der Server, bei grosser Abweichung nur mit `comment`. Mit
+ * `checkOnly` nur pruefen: `status: 'ready'` statt Schliessen.
+ */
+export async function closeMyShift(transport, options) {
+    const name = 'closeMyShift';
+    const p = anfrage(name, options);
+    kennung(name, p, 'shiftId');
+    schluessel(name, p, { pflicht: true });
+    cent(name, 'countedCents', p.countedCents);
+    stueckelungPruefen(name, p);
+    if (p.tipPayouts !== undefined && p.tipPayouts !== null) {
+        if (!Array.isArray(p.tipPayouts))
+            throw anfragefehler(name, 'tipPayouts muss eine Liste sein');
+        p.tipPayouts.forEach((a, i) => cent(name, `tipPayouts[${i}].cents`, a !== null && typeof a === 'object' ? a.cents : undefined));
+    }
+    if (p.checkOnly !== undefined && typeof p.checkOnly !== 'boolean')
+        throw anfragefehler(name, 'checkOnly muss true oder false sein');
+    // Nur die Form: die Art (Katalog) und die Grenzen prueft der Server.
+    if (p.afterCount !== undefined && p.afterCount !== null) {
+        if (typeof p.afterCount !== 'object' || Array.isArray(p.afterCount))
+            throw anfragefehler(name, 'afterCount muss ein Objekt { type, amountCents } sein');
+        cent(name, 'afterCount.amountCents', p.afterCount.amountCents);
+    }
+    return rufe(transport, name, p, abschluss);
+}
+// ---- Helfer der Kasse ---------------------------------------------------------
+const ANZAHL_MAX = 100000;
+const WERTE = new Set(EUR_DENOMINATIONS.map(String));
+/**
+ * Summe einer Stueckelung in Cent, oder `null`, wenn sie keine ist: ein
+ * Schluessel, der kein Euro-Wert ist ([EUR_DENOMINATIONS], genau so
+ * geschrieben, `"500"`, nicht `"0500"`), eine Anzahl, die keine ganze Zahl
+ * von 0 bis 100 000 ist. Dieselbe Regel wie am Server
+ * (`invalid_denominations`). Gemeinsame Faelle mit dem Dart-Zwilling:
+ * `fixtures/shift-cases.json`.
+ */
+export function sumDenominations(denominations) {
+    if (denominations === null || typeof denominations !== 'object' || Array.isArray(denominations))
+        return null;
+    let summe = 0;
+    for (const [wert, anzahl] of Object.entries(denominations)) {
+        if (!WERTE.has(wert))
+            return null;
+        if (typeof anzahl !== 'number' || !Number.isSafeInteger(anzahl) || anzahl < 0 || anzahl > ANZAHL_MAX)
+            return null;
+        summe += Number(wert) * anzahl;
+    }
+    return summe;
+}
+/**
+ * Ein eingetippter Betrag in Cent, **ohne Gleitkomma**: `'12,5'` → `1250`,
+ * `'0'` → `0` (anders als beim Kassieren ist 0 hier gueltig: eine leere Lade,
+ * kein Startgeld). Dezimaltrenner Komma oder Punkt mit einer oder zwei
+ * Nachkommastellen; `null` fuer leer, Vorzeichen, Tausendertrenner
+ * (`'1.000'`, `'1 000'`), drei Nachkommastellen, Euro-Zeichen und alles
+ * ueber einer sicheren Ganzzahl. Gemeinsame Faelle mit dem Dart-Zwilling:
+ * `fixtures/shift-cases.json`.
+ */
+export function parseCentsAllowZero(text) {
+    if (typeof text !== 'string')
+        return null;
+    const m = /^(\d+)(?:[.,](\d{1,2}))?$/.exec(text.trim());
+    if (!m)
+        return null;
+    const cents = BigInt(m[1]) * 100n + BigInt((m[2] ?? '').padEnd(2, '0'));
+    return cents <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(cents) : null;
+}
+/**
+ * Ein frischer Idempotenzschluessel fuer einen neuen Vorgang: `kasse-` und
+ * 32 Hex-Zeichen aus dem sicheren Zufall (`crypto.getRandomValues`), dieselbe
+ * Form wie beim Zaehlen der Inventur in der Kassen-App. Fuer „Erneut senden“
+ * nie einen neuen ziehen, sondern den alten behalten.
+ */
+export function newIdempotencyKey() {
+    const zufall = globalThis.crypto;
+    if (!zufall || typeof zufall.getRandomValues !== 'function') {
+        throw new KasseneckValidationError('newIdempotencyKey', 'kein sicherer Zufall vorhanden (crypto.getRandomValues)', 'request');
+    }
+    const bytes = zufall.getRandomValues(new Uint8Array(16));
+    return `kasse-${Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')}`;
+}
+/**
+ * Was vom Trinkgeld eines Mitarbeiters dasteht – auf dem Bon, im Kassenstand
+ * und beim Abschluss gleich (Rulings R50/R51): „verdient“ (sofort + über
+ * Lohn) immer, „über Lohn“, „schon genommen“, „selbst zurückgegeben“ (R62)
+ * und „offen“ nur, wenn nicht 0. Davor „aus früheren Schichten“ (R64, nur ≠ 0):
+ * offen = aus früheren Schichten + verdient − über Lohn − schon genommen +
+ * selbst zurückgegeben.
+ * Ist alles 0, gibt es keine Zeile, und der Mitarbeiter entfaellt ganz. Ohne
+ * `openCents` (Laufstand) zaehlt offen als 0. Gemeinsame Faelle mit dem
+ * Dart-Zwilling: `fixtures/shift-cases.json`.
+ */
+export function shiftTipLines(tip) {
+    const verdient = tip.receivedImmediatelyCents + tip.retainedCents;
+    const vortrag = tip.carriedOverCents ?? 0;
+    const zeilen = [
+        ['shift_receipt.tip_retained', tip.retainedCents],
+        ['shift_receipt.tip_paid_out', tip.paidOutCents],
+        ['shift_receipt.tip_refunded_by_employee', tip.refundedByEmployeeCents ?? 0],
+        ['shift_receipt.tip_open', tip.openCents ?? 0],
+    ];
+    const rest = zeilen.filter(([, cents]) => cents !== 0);
+    if (verdient === 0 && rest.length === 0 && vortrag === 0)
+        return [];
+    const davor = vortrag !== 0 ? [['shift_receipt.tip_carried_over', vortrag]] : [];
+    return [...davor, ['shift_receipt.tip_earned', verdient], ...rest].map(([key, cents]) => ({ key, text: labelText(key), cents }));
+}
+/**
+ * Dauer für Menschen aus ganzen Minuten: unter 1 Std. „45 Min.“, unter 1 Tag
+ * „8 Std. 32 Min.“ (bei 0 Minuten nur „8 Std.“), ab 1 Tag „1 Tag 3 Std.“ bzw.
+ * „2 Tage“ (bei 0 Stunden ohne Stunden). Negatives und Unsinn zählt als 0;
+ * Bruchteile werden abgeschnitten. Gemeinsame Fälle mit dem Dart-Zwilling:
+ * `fixtures/shift-cases.json` (`durationText`).
+ */
+export function durationText(minutes) {
+    const gesamt = Number.isFinite(minutes) && minutes > 0 ? Math.floor(minutes) : 0;
+    const tage = Math.floor(gesamt / 1440);
+    const stunden = Math.floor((gesamt % 1440) / 60);
+    const rest = gesamt % 60;
+    const teile = [];
+    if (tage > 0) {
+        teile.push(labelText(tage === 1 ? 'duration.days_one' : 'duration.days_other', { days: tage }));
+        if (stunden > 0)
+            teile.push(labelText('duration.hours', { hours: stunden }));
+    }
+    else {
+        if (stunden > 0)
+            teile.push(labelText('duration.hours', { hours: stunden }));
+        if (rest > 0 || stunden === 0)
+            teile.push(labelText('duration.minutes', { minutes: rest }));
+    }
+    return teile.join(' ');
+}

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

@@ -189,6 +189,13 @@ export interface PosBusinessSettings {
     glass: boolean;
     /** Hilfetexte in den Chef-Einstellungen anzeigen. */
     hints: boolean;
+    /**
+     * Bar-Trinkgeld behaelt der Mitarbeiter gleich: Vorbelegung des Schalters
+     * „gleich behalten“ beim Kassieren (je Verkauf aenderbar). Optional: der
+     * Server sendet das Feld nur, wenn es gespeichert ist; fehlt es, gilt aus.
+     * Lesen ueber [posTipKeptByDefault]. Siehe [POS_BUSINESS_OPTIONAL_FIELDS].
+     */
+    tipKeptByDefault?: boolean;
 }
 /** Aktionen der Kasse, die eine Taste bekommen koennen (Schluessel von `device.shortcuts`). */
 export declare const POS_SHORTCUT_ACTIONS: readonly ["checkout", "complete", "cancel", "customAmount", "cash", "card", "exactAmount", "receipts", "undoLast", "settings", "logout", "tip", "fullscreen", "clearTendered", "clearCart", "splitPayment"];
@@ -241,6 +248,13 @@ export interface PosDeviceSettings {
     qrMode: PosOpen<PosQrMode>;
     drawerEnabled: boolean;
     drawerAutoOpen: PosOpen<PosDrawerAutoOpen>;
+    /**
+     * Lade dieses Geraets (Schichtbetrieb). Optional: der Server sendet das
+     * Feld nur, wenn eine Lade zugeordnet ist; fehlt es, gilt die Hauptlade der
+     * Kasse. Beim Schreiben entfernt `null` die Zuordnung. Siehe
+     * [POS_DEVICE_OPTIONAL_FIELDS].
+     */
+    drawerId?: string | null;
     terminalIp: string;
     terminalPort: number;
     terminalVia: PosOpen<PosTerminalVia>;
@@ -257,6 +271,25 @@ export interface PosSettings {
 }
 export declare const POS_BUSINESS_DEFAULTS: Readonly<PosBusinessSettings>;
 export declare const POS_DEVICE_DEFAULTS: Readonly<PosDeviceSettings>;
+/**
+ * Optionale Geraete-Einstellungen: ohne Standardwert, der Server sendet sie
+ * nur, wenn sie gesetzt sind (Backend `GERAET_OPTIONAL`). Sie fehlen darum in
+ * [POS_DEVICE_DEFAULTS]; [mergePosSettings] uebernimmt sie, wenn sie als
+ * Kennung kommen, und der Schreibweg nimmt sie als Kennung oder `null`
+ * (Zuordnung entfernen).
+ */
+export declare const POS_DEVICE_OPTIONAL_FIELDS: readonly ["drawerId"];
+/** Gilt dieser Wert fuer ein optionales Feld? Lesen: nur eine Kennung; Schreiben: auch `null`. */
+export declare function _optionalerWert(wert: unknown, schreiben: boolean): boolean;
+/**
+ * Optionale Betriebs-Einstellungen (Schalter): ohne Standardwert, der Server
+ * sendet sie nur, wenn sie gespeichert sind (Backend `BETRIEB_OPTIONAL`).
+ * [mergePosSettings] uebernimmt sie nur als Wahrheitswert; der Schreibweg
+ * nimmt nur `true`/`false`.
+ */
+export declare const POS_BUSINESS_OPTIONAL_FIELDS: readonly ["tipKeptByDefault"];
+/** Bar-Trinkgeld „gleich behalten“ vorbelegt? Fehlt die Einstellung, gilt aus. */
+export declare function posTipKeptByDefault(business: Readonly<Partial<PosBusinessSettings>> | null | undefined): boolean;
 /**
  * Die Wertemenge je Feld, soweit das Feld eine hat: dagegen prueft der
  * Schreibweg vor dem Senden (ein deutscher Wert wie `'nacht'` geht so gar
@@ -275,7 +308,10 @@ export declare const _ALTFORM_0X: Readonly<{
 /**
  * Standard + stored. Landkarten (`vatRates`, `tipSteps`, `shortcuts`)
  * werden je Schluessel gemischt, damit neue Saetze beim Altbestand ankommen;
- * Schluessel, die der Standard nicht fuehrt, bleiben draussen.
+ * Schluessel, die der Standard nicht fuehrt, bleiben draussen, ausser einer
+ * optionalen Geraete-Einstellung ([POS_DEVICE_OPTIONAL_FIELDS]) mit gueltiger
+ * Kennung und einem optionalen Betriebs-Schalter
+ * ([POS_BUSINESS_OPTIONAL_FIELDS]) als Wahrheitswert.
  *
  * **Immer** (unabhaengig davon, welches Standard-Objekt uebergeben wird, auch
  * eine Kopie oder das einer zweiten Paketkopie) faellt ein Wert der inneren

package/dist/esm/pos/settings.js

@@ -173,6 +173,33 @@ export const POS_DEVICE_DEFAULTS = Object.freeze({
     terminalIp: '', terminalPort: 8080, terminalTid: '', terminalVia: 'direct',
     terminalType: 'none', shortcutHints: true,
 });
+/**
+ * Optionale Geraete-Einstellungen: ohne Standardwert, der Server sendet sie
+ * nur, wenn sie gesetzt sind (Backend `GERAET_OPTIONAL`). Sie fehlen darum in
+ * [POS_DEVICE_DEFAULTS]; [mergePosSettings] uebernimmt sie, wenn sie als
+ * Kennung kommen, und der Schreibweg nimmt sie als Kennung oder `null`
+ * (Zuordnung entfernen).
+ */
+export const POS_DEVICE_OPTIONAL_FIELDS = Object.freeze(['drawerId']);
+/** Form einer optionalen Kennung (Backend `ladeKennung`). */
+const OPTIONALE_KENNUNG = /^[A-Za-z0-9_-]{1,64}$/;
+/** Gilt dieser Wert fuer ein optionales Feld? Lesen: nur eine Kennung; Schreiben: auch `null`. */
+export function _optionalerWert(wert, schreiben) {
+    return (schreiben && wert === null) || (typeof wert === 'string' && OPTIONALE_KENNUNG.test(wert));
+}
+const OPTIONALE = new Set(POS_DEVICE_OPTIONAL_FIELDS);
+/**
+ * Optionale Betriebs-Einstellungen (Schalter): ohne Standardwert, der Server
+ * sendet sie nur, wenn sie gespeichert sind (Backend `BETRIEB_OPTIONAL`).
+ * [mergePosSettings] uebernimmt sie nur als Wahrheitswert; der Schreibweg
+ * nimmt nur `true`/`false`.
+ */
+export const POS_BUSINESS_OPTIONAL_FIELDS = Object.freeze(['tipKeptByDefault']);
+const OPTIONALE_SCHALTER = new Set(POS_BUSINESS_OPTIONAL_FIELDS);
+/** Bar-Trinkgeld „gleich behalten“ vorbelegt? Fehlt die Einstellung, gilt aus. */
+export function posTipKeptByDefault(business) {
+    return !!business && business.tipKeptByDefault === true;
+}
 /**
  * Die Wertemenge je Feld, soweit das Feld eine hat: dagegen prueft der
  * Schreibweg vor dem Senden (ein deutscher Wert wie `'nacht'` geht so gar
@@ -234,7 +261,10 @@ export const _ALTFORM_0X = Object.freeze({ werte: ALTWERTE_0X, aktionen: [...ALT
 /**
  * Standard + stored. Landkarten (`vatRates`, `tipSteps`, `shortcuts`)
  * werden je Schluessel gemischt, damit neue Saetze beim Altbestand ankommen;
- * Schluessel, die der Standard nicht fuehrt, bleiben draussen.
+ * Schluessel, die der Standard nicht fuehrt, bleiben draussen, ausser einer
+ * optionalen Geraete-Einstellung ([POS_DEVICE_OPTIONAL_FIELDS]) mit gueltiger
+ * Kennung und einem optionalen Betriebs-Schalter
+ * ([POS_BUSINESS_OPTIONAL_FIELDS]) als Wahrheitswert.
  *
  * **Immer** (unabhaengig davon, welches Standard-Objekt uebergeben wird, auch
  * eine Kopie oder das einer zweiten Paketkopie) faellt ein Wert der inneren
@@ -247,8 +277,16 @@ export function mergePosSettings(standard, stored) {
     const out = JSON.parse(JSON.stringify(standard));
     if (stored && typeof stored === 'object') {
         for (const key of Object.keys(stored)) {
-            if (!eigen(out, key))
+            if (!eigen(out, key)) {
+                // Optionale Geraete-Einstellung (ohne Standardwert): nur als Kennung;
+                // optionaler Betriebs-Schalter: nur als Wahrheitswert.
+                const wert = stored[key];
+                if (OPTIONALE.has(key) && _optionalerWert(wert, false))
+                    out[key] = wert;
+                if (OPTIONALE_SCHALTER.has(key) && typeof wert === 'boolean')
+                    out[key] = wert;
                 continue;
+            }
             const wert = stored[key];
             const alt = out[key];
             if (alt && typeof alt === 'object' && !Array.isArray(alt) && wert && typeof wert === 'object' && !Array.isArray(wert)) {