@kreiseck/kasseneck-api 0.6.7

package/dist/esm/register/index.js

@@ -0,0 +1,51 @@
+/**
+ * Unterpfad `@kreiseck/kasseneck-api/register` — die **Anmeldung der
+ * Browser-Kasse**: ein Geraet koppeln, seine Kassen-Benutzer auflisten, einen
+ * davon per PIN anmelden (mit oder ohne Benutzerauswahl), und die entstandene
+ * Sitzung erneuern bzw. beenden.
+ *
+ * Diese Aufrufe stehen vor allen anderen: ohne sie gibt es keine
+ * Identitaet, mit der ein Beleg entstehen koennte.
+ *
+ * **Sie zerfallen in zwei Haelften, und der Unterschied ist wesentlich:**
+ *
+ * | Aufruf | Anmeldung |
+ * |---|---|
+ * | [pairRegisterDevice] | **keine** — der Kopplungs-Code ist der Nachweis |
+ * | [listRegisterUsersForDevice] | **keine** — der Ausweis des Geraets ist der Nachweis |
+ * | [unpairRegisterDevice] | **keine** — der Ausweis des Geraets; sperrt es im Backend (Entkoppeln) |
+ * | [registerUserLogin] | **keine** — dieser Aufruf erzeugt sie |
+ * | [registerPinLogin] | **keine** — wie registerUserLogin, nur ohne Benutzerauswahl (Geraete-Modus `pin`) |
+ * | [renewRegisterSession] | Kassen-Benutzer (`registerUserAuth`) |
+ * | [endRegisterSession] | Kassen-Benutzer (`registerUserAuth`) |
+ *
+ * Die ersten drei nehmen deshalb **keinen Transport** entgegen, sondern nur
+ * die Verbindungsangaben, und bauen ihn selbst — die anmeldungsfreie Anmeldung
+ * dahinter wird bewusst nicht exportiert, sonst liesse sich damit jeder Aufruf
+ * des Pakets ohne Anmeldung bauen (ausfuehrlich in pairing.ts). Die letzten
+ * beiden nehmen den Transport wie jeder andere Endpunkt-Aufruf und stehen
+ * zusaetzlich in `createKasseneckApi`.
+ *
+ * Der uebliche Ablauf einer Browser-Kasse:
+ *
+ * ```ts
+ * import {
+ *   pairRegisterDevice, listRegisterUsersForDevice, registerUserLogin,
+ * } from '@kreiseck/kasseneck-api/register';
+ *
+ * // Einmalig: Code aus dem Panel gegen den Geraeteausweis tauschen.
+ * const geraet = await pairRegisterDevice({ code: 'K7NPQR34', label: 'Schank' });
+ *
+ * // Bei jedem Schichtwechsel: auswaehlen und per PIN anmelden.
+ * const { users } = await listRegisterUsersForDevice(geraet);
+ * const sitzung = await registerUserLogin({
+ *   ...geraet, userId: users[0]!.id, pin: '1234', cashregisterId: geraet.cashregisterId,
+ * });
+ * ```
+ *
+ * Mit `sitzung.customToken` meldet sich der Verbraucher bei Firebase an; das
+ * daraus entstehende ID-Token und `sitzung.sessionId` ergeben zusammen
+ * `registerUserAuth` — ab da laeuft alles Weitere ueber den ueblichen Weg.
+ */
+export { pairRegisterDevice, listRegisterUsersForDevice, unpairRegisterDevice, registerUserLogin, registerPinLogin, } from './pairing.js';
+export { renewRegisterSession, endRegisterSession } from './session.js';

package/dist/esm/register/pairing.d.ts

@@ -0,0 +1,248 @@
+import { type TransportOptions } from '../client/transport.js';
+import { type ReceiptCompany } from '../models/receipt-company.js';
+import { type KasseSettings } from '../kasse/settings.js';
+/**
+ * Verbindungsangaben ohne Anmeldung — alles, was [TransportOptions] ausser der
+ * Anmeldung fuehrt. Alle Felder sind wahlfrei: ohne Angabe gelten Basis-URL und
+ * Zeitlimit der Produktion und das globale `fetch`.
+ */
+export type RegisterDeviceConnection = Omit<TransportOptions, 'auth'>;
+/** Ausweis eines gekoppelten Geraets — Nachweis der beiden Folgeaufrufe. */
+export interface RegisterDeviceCredentials {
+    /** Kunde, unter dem das Geraet haengt (aus der Kopplung). */
+    ownerUid: string;
+    /** Dieses Geraet (aus der Kopplung). */
+    deviceId: string;
+    /** Geheimnis dieses Geraets; das Backend liefert es genau einmal aus. */
+    deviceSecret: string;
+}
+/** Was das Geraet ueber sich sagt -- fuer das Panel (welches Geraet ist das?). Alles optional. */
+export interface RegisterClientInfo {
+    userAgent?: string;
+    platform?: string;
+    language?: string;
+    /** IANA-Zeitzone, z. B. Europe/Vienna. */
+    tz?: string;
+    screen?: {
+        w: number;
+        h: number;
+    };
+}
+/** Standort aus der Browser-Ortung (freiwillig); Grundlage der Standortsperre. */
+export interface RegisterGeo {
+    lat: number;
+    lng: number;
+    /** Genauigkeit in Metern. */
+    acc?: number;
+}
+/** Angaben, die Kopplung und Login zusaetzlich mitschicken duerfen. */
+export interface RegisterGeraeteAngaben {
+    client?: RegisterClientInfo;
+    geo?: RegisterGeo | null;
+}
+export interface PairRegisterDeviceOptions extends RegisterDeviceConnection, RegisterGeraeteAngaben {
+    /**
+     * Achtstelliger Kopplungs-Code aus dem Panel. Er ist 15 Minuten gueltig,
+     * genau **einmal** verwendbar und gilt fuer eine bestimmte Kasse.
+     *
+     * Gross-/Kleinschreibung und Leerzeichen an den Raendern sind gleichgueltig:
+     * das Backend beschneidet und schreibt gross. Dieses Paket prueft das Format
+     * **nicht** — es kennt das Alphabet nicht und wuerde eine spaetere Erweiterung
+     * ausschliessen.
+     */
+    code: string;
+    /** Bezeichnung dieses Geraets in der Geraeteliste; ohne Angabe "Kasse". */
+    label?: string;
+}
+/** Ergebnis der Kopplung — der vollstaendige Ausweis dieses Geraets. */
+export interface PairedRegisterDevice extends RegisterDeviceCredentials {
+    /** Kasse, an die die Kopplung dieses Geraet gebunden hat. */
+    cashregisterId: string;
+    /** Firmenname des Betriebs (Backend: `betrieb`) — Anzeige, kann leer sein. */
+    companyName: string;
+    /** Bezeichnung der Kasse (Backend: `kasse`) — Anzeige, kann leer sein. */
+    cashregisterLabel: string;
+}
+/**
+ * Art eines Kassen-Benutzers: eine Person oder ein Geraet (Sammelkonto). Ein
+ * kuenftiger, hier noch unbekannter Wert kommt unveraendert durch, statt still
+ * zu "person" zu werden — beim Lesen ist dieses Paket tolerant.
+ */
+export type RegisterUserKind = 'person' | 'device' | (string & {});
+/** Ein Kassen-Benutzer, wie ihn der Anmeldebildschirm zeigt. */
+export interface RegisterUserSummary {
+    id: string;
+    /** Anzeigename; kann leer sein. */
+    name: string;
+    kind: RegisterUserKind;
+    /**
+     * Die PIN dieses Benutzers wurde noch nicht unter der aktuellen Regel des
+     * Betriebs gesetzt: die Kasse zeigt ihm das Freifeld statt der Kaestchen.
+     * Das Backend sendet das Feld nur, wenn es zutrifft; gelesen ist es immer da.
+     */
+    altbestand: boolean;
+}
+/** PIN-Regel des Betriebs — daraus baut die Kasse Kaestchen und Tastatur. */
+export interface RegisterPinPolicy {
+    /** Feste Stellenzahl (Backend: 3 bis 6). */
+    stellen: number;
+    /** `ziffern` (nur 0-9) oder `zeichen` (0-9 plus Kopplungs-Alphabet). */
+    zeichen: 'ziffern' | 'zeichen' | (string & {});
+}
+/** Anmeldemodus des Geraets; ein unbekannter kuenftiger Wert kommt durch. */
+export type RegisterLoginMode = 'auswahl' | 'pin' | (string & {});
+/** Antwort von [listRegisterUsersForDevice]: Benutzer, Regel, Modus. */
+export interface RegisterDeviceUsers {
+    /** Im Modus `pin` bewusst leer — Namen haben am nur-PIN-Geraet nichts verloren. */
+    users: RegisterUserSummary[];
+    /** Kassen-Einstellungen (betriebsweit + Geraet), gemischt mit den Standardwerten. */
+    settings: KasseSettings;
+    /** Belegkopf-Daten des Betriebs (Name, Anschrift, UID, Fusszeilen) -- ohne Geheimnisse. */
+    betriebsdaten: ReceiptCompany | null;
+    /**
+     * `null`, wenn das Backend (noch) keine Regel nennt — dann zeigt die Kasse
+     * das Freifeld, statt Kaestchen mit einer erratenen Stellenzahl.
+     */
+    policy: RegisterPinPolicy | null;
+    loginMode: RegisterLoginMode;
+    /** Der Betrieb verlangt die Ortung beim Login (Standortsperre an). */
+    standortsperre: boolean;
+}
+/**
+ * Rechte eines Kassen-Benutzers (Backend: `perms`, Vorlagen `PERMS_KASSIER`
+ * und `PERMS_CHEF`). Der Inhaber kann einzelne Rechte abweichend setzen,
+ * deshalb sind weitere Schluessel zugelassen.
+ *
+ * **Ein fehlendes Recht gilt als nicht erteilt.** Die Oberflaeche soll im
+ * Zweifel weniger anbieten, nicht mehr; die tatsaechliche Grenze zieht ohnehin
+ * das Backend.
+ */
+/** Reichweite eines Rechts: keine | nur eigene Belege | alle. */
+export type RegisterScope = 'none' | 'own' | 'all';
+export interface RegisterUserPerms {
+    /** Belege ausstellen. */
+    sell: boolean;
+    /** Belege stornieren (Schalter, gespiegelt aus cancelScope !== 'none'). */
+    cancel: boolean;
+    /** Artikelstamm bearbeiten. */
+    articles: boolean;
+    /** Beleglayout/Kassen-Einstellungen bearbeiten (Chef). */
+    layout: boolean;
+    /** Berichte ansehen. */
+    reports: boolean;
+    /** Eine belegte Kasse uebernehmen (nur Kassen-Chef). */
+    takeover: boolean;
+    /** Storno-Reichweite; fehlt bei Altbestand (dann zaehlt `cancel`: true = all). */
+    cancelScope?: RegisterScope;
+    /** Belege ansehen; fehlt bei Altbestand (= all). */
+    receiptsScope?: RegisterScope;
+    /** Kassenlade ohne Verkauf oeffnen. */
+    drawer?: boolean;
+    /** Rabatt geben. */
+    discount?: boolean;
+    /** Trinkgeld anderen zuweisen. */
+    tipAssign?: boolean;
+    [weiteresRecht: string]: boolean | RegisterScope | undefined;
+}
+/** Reichweite lesen, mit der Migration des Backends (register-auth.js). */
+export declare function cancelScopeOf(perms: RegisterUserPerms | null | undefined): RegisterScope;
+export declare function receiptsScopeOf(perms: RegisterUserPerms | null | undefined): RegisterScope;
+/** Der angemeldete Kassen-Benutzer. */
+export interface RegisterUser {
+    id: string;
+    name: string;
+    perms: RegisterUserPerms;
+}
+/** Ergebnis der PIN-Anmeldung. */
+export interface RegisterUserSession {
+    /**
+     * Firebase-Custom-Token. Damit meldet der Verbraucher sich bei Firebase an
+     * und bekommt das ID-Token, das `registerUserAuth` braucht; dieses Paket
+     * kennt Firebase nicht.
+     */
+    customToken: string;
+    /** Laufende Sitzung — Kopfzeile `register-session` jedes weiteren Aufrufs. */
+    sessionId: string;
+    /**
+     * Ablauf der Sitzung in Millisekunden seit 1970 (das Backend rechnet hier mit
+     * `Date.now()`, nicht mit Wiener Wanduhrzeit). Die Sitzung lebt 90 Sekunden
+     * und will alle 30 Sekunden erneuert werden.
+     */
+    expiresAt: number;
+    user: RegisterUser;
+}
+export interface ListRegisterUsersForDeviceOptions extends RegisterDeviceConnection, RegisterDeviceCredentials {
+}
+export interface RegisterUserLoginOptions extends RegisterDeviceConnection, RegisterDeviceCredentials, RegisterGeraeteAngaben {
+    /** Kassen-Benutzer aus [listRegisterUsersForDevice]. */
+    userId: string;
+    /**
+     * PIN dieses Benutzers. Das Format prueft dieses Paket **nicht**: eine zu
+     * strenge Pruefung im Client sperrte Benutzer aus, deren PIN das Panel anders
+     * gesetzt hat.
+     */
+    pin: string;
+    /** Kasse, an der die Sitzung eroeffnet wird. */
+    cashregisterId: string;
+    /**
+     * Eine belegte Kasse uebernehmen. Nur mit dem Recht `takeover` (Kassen-Chef);
+     * die aelteste laufende Sitzung wird dabei verdraengt. Ohne das Recht bleibt
+     * es bei der Abweisung "Kasse wird gerade auf … verwendet".
+     */
+    takeover?: boolean;
+}
+export interface RegisterPinLoginOptions extends RegisterDeviceConnection, RegisterDeviceCredentials, RegisterGeraeteAngaben {
+    /**
+     * Die PIN allein — sie identifiziert UND authentifiziert (Geraete-Modus
+     * `pin`; das Backend haelt PINs je Betrieb eindeutig). Das Format prueft
+     * dieses Paket **nicht** — dieselbe Zurueckhaltung wie bei
+     * [RegisterUserLoginOptions.pin].
+     */
+    pin: string;
+    /** Kasse, an der die Sitzung eroeffnet wird. */
+    cashregisterId: string;
+    /** Wie [RegisterUserLoginOptions.takeover]. */
+    takeover?: boolean;
+}
+/**
+ * Geraet koppeln: der Kopplungs-Code wird gegen den dauerhaften Ausweis dieses
+ * Geraets getauscht. **Ohne Anmeldung** — der Code ist der Nachweis.
+ *
+ * Er wird dabei verbraucht, auch wenn der Aufrufer das Ergebnis verliert: eine
+ * unvollstaendige Antwort ist deshalb ein Fehler und kein halbes Geraet (siehe
+ * [PairedRegisterDevice]).
+ */
+export declare function pairRegisterDevice(options: PairRegisterDeviceOptions): Promise<PairedRegisterDevice>;
+/**
+ * Kassen-Benutzer dieses Betriebs auflisten — die Auswahl des
+ * Anmeldebildschirms. **Ohne Anmeldung**; der Ausweis des Geraets ist der
+ * Nachweis.
+ *
+ * Die Antwort traegt ausschliesslich Kennung, Name und Art: keine Rechte, keine
+ * Kassen, keine Hashes. Gesperrte Benutzer fehlen bereits in der Antwort.
+ */
+/**
+ * „Geraet entkoppeln“ an der Kasse selbst: das Geraet weist sich mit seinem
+ * Geheimnis aus und sperrt sich im Backend — damit sieht das Panel den
+ * Widerruf und keine Sitzung laeuft nach. Idempotent: ein schon gesperrtes
+ * Geraet meldet Erfolg. Danach das Geraet lokal vergessen.
+ */
+export declare function unpairRegisterDevice(options: ListRegisterUsersForDeviceOptions): Promise<void>;
+export declare function listRegisterUsersForDevice(options: ListRegisterUsersForDeviceOptions): Promise<RegisterDeviceUsers>;
+/**
+ * Kassen-Benutzer per PIN anmelden. **Ohne Anmeldung** — dieser Aufruf
+ * erzeugt sie: das Custom Token der Antwort wird zum ID-Token, die `sessionId`
+ * zur Kopfzeile `register-session`. Beides zusammen ergibt `registerUserAuth`.
+ *
+ * Das Backend prueft in dieser Reihenfolge: Geraet, Benutzer, Sperre, PIN,
+ * Kassenzuweisung, Kopplungsbindung, Lizenzplatz. Fehlversuche zaehlen und
+ * sperren gestaffelt (ab dem fuenften 30 Sekunden, ab dem neunten 15 Minuten).
+ */
+export declare function registerUserLogin(options: RegisterUserLoginOptions): Promise<RegisterUserSession>;
+/**
+ * Kassen-Benutzer allein mit der PIN anmelden (Geraete-Modus `pin`). **Ohne
+ * Anmeldung** — wie [registerUserLogin], nur ohne Benutzerauswahl: das Backend
+ * ermittelt den Benutzer ueber die betriebsweit eindeutige PIN. Fehlversuche
+ * zaehlen und sperren dort am **Geraet**, nicht an einem Benutzer.
+ */
+export declare function registerPinLogin(options: RegisterPinLoginOptions): Promise<RegisterUserSession>;

package/dist/esm/register/pairing.js

@@ -0,0 +1,270 @@
+import { KasseneckValidationError } from '../client/errors.js';
+import { createTransport } from '../client/transport.js';
+import { fromReceiptCompanyPayload } from '../models/receipt-company.js';
+import { KASSE_BETRIEB_STANDARD, KASSE_GERAET_STANDARD, mergeKasseSettings, } from '../kasse/settings.js';
+/**
+ * Die drei Aufrufe, die **ohne jede Identitaet** laufen: Kopplung eines
+ * Geraets, Benutzerliste dieses Geraets, PIN-Anmeldung. Sie sind der Weg, auf
+ * dem eine Identitaet ueberhaupt erst entsteht — vor ihnen gibt es weder
+ * ID-Token noch Sitzung noch `api_key`.
+ *
+ * **Warum sie keine Anmeldung und keinen Transport entgegennehmen.** Alle
+ * uebrigen Endpunkt-Aufrufe dieses Pakets bekommen einen fertigen
+ * [KasseneckTransport] als ersten Parameter. Hier ginge das nur mit einer
+ * anmeldungsfreien Anmeldung — und die muesste dann exportiert sein. Genau das
+ * waere ein Schlupfloch: mit ihr liesse sich `createTransport` bzw.
+ * `createKasseneckApi` bauen und damit **jeder** Aufruf des Pakets ohne
+ * Anmeldung absetzen, auch `createReceipt`. Das Backend wiese das ab, aber ein
+ * Paket, das den Weg anbietet, sagt damit, dass es ihn gibt.
+ *
+ * Deshalb nehmen diese drei nur die **Verbindungsangaben** (Basis-URL,
+ * Zeitlimit, `fetch`) entgegen und bauen ihren Transport selbst — mit einer
+ * Anmeldung, die diese Datei nicht verlaesst. Damit gibt es im ganzen Paket
+ * keinen Weg, einen anmeldungsfreien Transport in die Hand zu bekommen.
+ *
+ * **Geheimnisse in der Nutzlast.** Diese drei Aufrufe fuehren Kopplungs-Code,
+ * Geraetegeheimnis und PIN — nicht in Kopfzeilen, sondern im Rumpf. Der
+ * Transport schuetzt seine Fehler von sich aus nur gegen die Werte, die er als
+ * Kopfzeilen gesendet hat (siehe client/errors.ts, `causeDigest`); hier ist
+ * diese Liste leer. Die Aufrufe nennen ihm ihre Geheimnisse deshalb
+ * ausdruecklich, sonst kaeme ein bezeichner-foermiges Geraetegeheimnis ueber
+ * die verdichtete Ursache eines Netzfehlers doch noch ins Protokoll.
+ */
+/**
+ * Anmeldung, die keine ist: weder Kopfzeilen noch Zusatzparameter.
+ *
+ * **Nicht exportiert und niemals exportieren** — der Grund steht im
+ * Modulkommentar. Pro Aufruf ein frisches Objekt, wie die echten Anmeldungen
+ * es auch halten.
+ */
+const ohneAnmeldung = () => ({ headers: {}, params: {} });
+/** Reichweite lesen, mit der Migration des Backends (register-auth.js). */
+export function cancelScopeOf(perms) {
+    if (!perms)
+        return 'none';
+    if (perms.cancelScope !== undefined)
+        return ['none', 'own', 'all'].includes(perms.cancelScope) ? perms.cancelScope : 'none';
+    return perms.cancel === true ? 'all' : 'none';
+}
+export function receiptsScopeOf(perms) {
+    if (!perms)
+        return 'none';
+    if (perms.receiptsScope === undefined)
+        return 'all';
+    return ['none', 'own', 'all'].includes(perms.receiptsScope) ? perms.receiptsScope : 'none';
+}
+/**
+ * Geraet koppeln: der Kopplungs-Code wird gegen den dauerhaften Ausweis dieses
+ * Geraets getauscht. **Ohne Anmeldung** — der Code ist der Nachweis.
+ *
+ * Er wird dabei verbraucht, auch wenn der Aufrufer das Ergebnis verliert: eine
+ * unvollstaendige Antwort ist deshalb ein Fehler und kein halbes Geraet (siehe
+ * [PairedRegisterDevice]).
+ */
+export async function pairRegisterDevice(options) {
+    const { code, label, client, geo, ...verbindung } = options;
+    pflicht('pairRegisterDevice', 'code', code);
+    // Der Code ist das Geheimnis dieses Aufrufs — siehe Modulkommentar.
+    const daten = await transportFuer(verbindung)('pairRegisterDevice', { code, label, client, geo: geo ?? undefined }, undefined, [code]);
+    return {
+        deviceId: pflichtfeld('pairRegisterDevice', daten, 'deviceId'),
+        deviceSecret: pflichtfeld('pairRegisterDevice', daten, 'deviceSecret'),
+        ownerUid: pflichtfeld('pairRegisterDevice', daten, 'ownerUid'),
+        cashregisterId: pflichtfeld('pairRegisterDevice', daten, 'cashregisterId'),
+        companyName: text(daten?.['betrieb']),
+        cashregisterLabel: text(daten?.['kasse']),
+    };
+}
+/**
+ * Kassen-Benutzer dieses Betriebs auflisten — die Auswahl des
+ * Anmeldebildschirms. **Ohne Anmeldung**; der Ausweis des Geraets ist der
+ * Nachweis.
+ *
+ * Die Antwort traegt ausschliesslich Kennung, Name und Art: keine Rechte, keine
+ * Kassen, keine Hashes. Gesperrte Benutzer fehlen bereits in der Antwort.
+ */
+/**
+ * „Geraet entkoppeln“ an der Kasse selbst: das Geraet weist sich mit seinem
+ * Geheimnis aus und sperrt sich im Backend — damit sieht das Panel den
+ * Widerruf und keine Sitzung laeuft nach. Idempotent: ein schon gesperrtes
+ * Geraet meldet Erfolg. Danach das Geraet lokal vergessen.
+ */
+export async function unpairRegisterDevice(options) {
+    const { ownerUid, deviceId, deviceSecret, ...verbindung } = options;
+    const name = 'unpairRegisterDevice';
+    pflicht(name, 'ownerUid', ownerUid);
+    pflicht(name, 'deviceId', deviceId);
+    pflicht(name, 'deviceSecret', deviceSecret);
+    await transportFuer(verbindung)(name, { ownerUid, deviceId, deviceSecret }, undefined, [deviceSecret]);
+}
+export async function listRegisterUsersForDevice(options) {
+    const { ownerUid, deviceId, deviceSecret, ...verbindung } = options;
+    const name = 'listRegisterUsersForDevice';
+    pflicht(name, 'ownerUid', ownerUid);
+    pflicht(name, 'deviceId', deviceId);
+    pflicht(name, 'deviceSecret', deviceSecret);
+    const daten = await transportFuer(verbindung)(name, { ownerUid, deviceId, deviceSecret }, undefined, [deviceSecret]);
+    const liste = daten?.users;
+    if (!Array.isArray(liste)) {
+        throw antwortfehler(name, 'Antwort enthaelt keine Benutzerliste (data.users fehlt)');
+    }
+    const users = liste.map((eintrag) => {
+        const roh = (typeof eintrag === 'object' && eintrag !== null ? eintrag : {});
+        return {
+            // Ein Eintrag ohne Kennung ist nicht anmeldbar — ihn anzuzeigen hiesse,
+            // dem Kassier eine Schaltflaeche zu geben, die nichts tun kann.
+            id: pflichtfeld(name, roh, 'id'),
+            name: text(roh['name']),
+            kind: typeof roh['kind'] === 'string' && roh['kind'] ? roh['kind'] : 'person',
+            altbestand: roh['altbestand'] === true,
+        };
+    });
+    const settingsRoh = (daten?.settings ?? {});
+    const settings = {
+        betrieb: mergeKasseSettings(KASSE_BETRIEB_STANDARD, (settingsRoh.betrieb ?? null)),
+        geraet: mergeKasseSettings(KASSE_GERAET_STANDARD, (settingsRoh.geraet ?? null)),
+    };
+    const bd = daten?.betriebsdaten;
+    const betriebsdaten = bd && typeof bd === 'object' ? fromReceiptCompanyPayload(bd) : null;
+    return { users, policy: regel(daten?.policy), loginMode: daten?.loginMode === 'pin' ? 'pin' : 'auswahl', settings, betriebsdaten, standortsperre: daten?.standortsperre === true };
+}
+/** Die Regel aus der Antwort — oder `null`, wenn keine brauchbare kommt. */
+function regel(wert) {
+    if (typeof wert !== 'object' || wert === null || Array.isArray(wert))
+        return null;
+    const roh = wert;
+    const stellen = roh['stellen'];
+    const zeichen = roh['zeichen'];
+    if (typeof stellen !== 'number' || !Number.isInteger(stellen) || stellen < 1)
+        return null;
+    if (typeof zeichen !== 'string' || zeichen === '')
+        return null;
+    return { stellen, zeichen: zeichen };
+}
+/**
+ * Kassen-Benutzer per PIN anmelden. **Ohne Anmeldung** — dieser Aufruf
+ * erzeugt sie: das Custom Token der Antwort wird zum ID-Token, die `sessionId`
+ * zur Kopfzeile `register-session`. Beides zusammen ergibt `registerUserAuth`.
+ *
+ * Das Backend prueft in dieser Reihenfolge: Geraet, Benutzer, Sperre, PIN,
+ * Kassenzuweisung, Kopplungsbindung, Lizenzplatz. Fehlversuche zaehlen und
+ * sperren gestaffelt (ab dem fuenften 30 Sekunden, ab dem neunten 15 Minuten).
+ */
+export async function registerUserLogin(options) {
+    const { ownerUid, deviceId, deviceSecret, userId, pin, cashregisterId, takeover, client, geo, ...verbindung } = options;
+    const name = 'registerUserLogin';
+    pflicht(name, 'ownerUid', ownerUid);
+    pflicht(name, 'deviceId', deviceId);
+    pflicht(name, 'deviceSecret', deviceSecret);
+    pflicht(name, 'userId', userId);
+    pflicht(name, 'pin', pin);
+    pflicht(name, 'cashregisterId', cashregisterId);
+    const daten = await transportFuer(verbindung)(name, {
+        ownerUid,
+        deviceId,
+        deviceSecret,
+        userId,
+        pin,
+        cashregisterId,
+        // Nur die ausdrueckliche Uebernahme geht mit: das Backend prueft auf
+        // `=== true`, und ein mitgesendetes `false` waere nur Rauschen.
+        takeover: takeover === true ? true : undefined,
+        client, geo: geo ?? undefined,
+    }, undefined, [pin, deviceSecret]);
+    return sitzungAusAntwort(name, daten);
+}
+/**
+ * Kassen-Benutzer allein mit der PIN anmelden (Geraete-Modus `pin`). **Ohne
+ * Anmeldung** — wie [registerUserLogin], nur ohne Benutzerauswahl: das Backend
+ * ermittelt den Benutzer ueber die betriebsweit eindeutige PIN. Fehlversuche
+ * zaehlen und sperren dort am **Geraet**, nicht an einem Benutzer.
+ */
+export async function registerPinLogin(options) {
+    const { ownerUid, deviceId, deviceSecret, pin, cashregisterId, takeover, client, geo, ...verbindung } = options;
+    const name = 'registerPinLogin';
+    pflicht(name, 'ownerUid', ownerUid);
+    pflicht(name, 'deviceId', deviceId);
+    pflicht(name, 'deviceSecret', deviceSecret);
+    pflicht(name, 'pin', pin);
+    pflicht(name, 'cashregisterId', cashregisterId);
+    const daten = await transportFuer(verbindung)(name, {
+        ownerUid,
+        deviceId,
+        deviceSecret,
+        pin,
+        cashregisterId,
+        // Nur die ausdrueckliche Uebernahme geht mit — wie bei registerUserLogin.
+        takeover: takeover === true ? true : undefined,
+        client, geo: geo ?? undefined,
+    }, undefined, [pin, deviceSecret]);
+    return sitzungAusAntwort(name, daten);
+}
+/** Die Sitzungsantwort beider Anmeldewege — ein Vertrag, eine Lesart. */
+function sitzungAusAntwort(name, daten) {
+    const roherBenutzer = daten?.['user'];
+    if (typeof roherBenutzer !== 'object' || roherBenutzer === null || Array.isArray(roherBenutzer)) {
+        throw antwortfehler(name, 'Antwort enthaelt keinen Benutzer (data.user fehlt)');
+    }
+    const benutzer = roherBenutzer;
+    const expiresAt = daten?.['expiresAt'];
+    if (typeof expiresAt !== 'number' || !Number.isFinite(expiresAt)) {
+        throw antwortfehler(name, 'Antwort enthaelt keinen Ablaufzeitpunkt (data.expiresAt fehlt)');
+    }
+    return {
+        customToken: pflichtfeld(name, daten, 'customToken'),
+        sessionId: pflichtfeld(name, daten, 'sessionId'),
+        expiresAt,
+        user: {
+            id: pflichtfeld(name, benutzer, 'id'),
+            name: text(benutzer['name']),
+            perms: rechte(benutzer['perms']),
+        },
+    };
+}
+/** Transport ohne Anmeldung; `auth` steht zuletzt und ist damit nicht zu ueberschreiben. */
+function transportFuer(verbindung) {
+    return createTransport({ ...verbindung, auth: ohneAnmeldung });
+}
+/**
+ * Pflichtangabe des Aufrufers. Die Meldung nennt das **Feld**, nie seinen Wert
+ * — das Feld heisst `pin`, `deviceSecret` oder `code`.
+ */
+function pflicht(functionName, feld, wert) {
+    if (typeof wert !== 'string' || wert.trim() === '') {
+        throw new KasseneckValidationError(functionName, `${feld} fehlt`, 'request');
+    }
+}
+/**
+ * Pflichtfeld der Antwort. Auch hier wandert **nichts aus der Antwort** in die
+ * Meldung; genannt wird nur, welches Feld fehlt.
+ */
+function pflichtfeld(functionName, daten, feld) {
+    const wert = daten?.[feld];
+    if (typeof wert !== 'string' || wert === '') {
+        throw antwortfehler(functionName, `Antwort enthaelt kein Feld "${feld}"`);
+    }
+    return wert;
+}
+/** Rechte lesen: nur Wahrheitswerte, alles Fehlende gilt als nicht erteilt. */
+function rechte(wert) {
+    const roh = (typeof wert === 'object' && wert !== null && !Array.isArray(wert) ? wert : {});
+    const gelesen = {};
+    for (const [name, inhalt] of Object.entries(roh)) {
+        gelesen[name] = inhalt === true;
+    }
+    return {
+        sell: false,
+        cancel: false,
+        articles: false,
+        layout: false,
+        reports: false,
+        takeover: false,
+        ...gelesen,
+    };
+}
+/** Leere Zeichenkette statt `undefined` — Anzeigefelder duerfen leer sein. */
+const text = (wert) => (typeof wert === 'string' ? wert : '');
+/** Die Antwort meldete Erfolg, trug aber nicht, was der Aufruf zusagt. */
+function antwortfehler(functionName, grund) {
+    return new KasseneckValidationError(functionName, grund, 'response');
+}

package/dist/esm/register/session.d.ts

@@ -0,0 +1,37 @@
+import type { KasseneckTransport } from '../client/transport.js';
+/**
+ * Die beiden Aufrufe der **laufenden** Kassen-Sitzung. Anders als die drei in
+ * pairing.ts haben sie eine Identitaet: sie laufen ueber `registerUserAuth`
+ * (ID-Token als Bearer, Sitzung als Kopfzeile `register-session`) und nehmen
+ * darum einen fertigen [KasseneckTransport] entgegen wie jeder andere
+ * Endpunkt-Aufruf dieses Pakets.
+ *
+ * Beide fuehren **keinen einzigen Parameter**: welche Sitzung gemeint ist,
+ * steht im Token und in der Kopfzeile. Der Parameter `cashregisterId`, den man
+ * im Rumpf sieht, kommt aus der Anmeldung.
+ *
+ * Das Backend setzt fuer beide `allowRegisterUser`; mit `apiKeyAuth` sind sie
+ * nicht erreichbar (dieses Paket bildet das nicht nach — wer darf, entscheidet
+ * das Backend).
+ */
+/**
+ * Sitzung verlaengern und den neuen Ablaufzeitpunkt liefern (Millisekunden
+ * seit 1970).
+ *
+ * Die Sitzung lebt 90 Sekunden; die Browser-Kasse erneuert alle 30. Ist sie
+ * bereits beendet oder uebernommen, antwortet das Backend fachlich ("Sitzung
+ * beendet — bitte neu anmelden.") — dann hilft nur eine neue Anmeldung ueber
+ * `registerUserLogin`.
+ */
+export declare function renewRegisterSession(rufen: KasseneckTransport): Promise<number>;
+/**
+ * Sitzung beenden und den Lizenzplatz sofort freigeben — der regulaere Weg des
+ * Abmeldens.
+ *
+ * Das Backend antwortet mit `{ok:true}`; dieser Aufruf prueft das Feld
+ * **nicht**: dass der Vorgang gelang, sagt bereits die Erfolgshuelle, die der
+ * Transport auswertet. Eine zweite Pruefung derselben Aussage braeche nur an
+ * einer harmlosen Vertragsaenderung — ausgerechnet beim Abmelden, dem Aufruf,
+ * der auch dann durchgehen soll, wenn sonst nichts mehr geht.
+ */
+export declare function endRegisterSession(rufen: KasseneckTransport): Promise<void>;

package/dist/esm/register/session.js

@@ -0,0 +1,48 @@
+import { KasseneckValidationError } from '../client/errors.js';
+/**
+ * Die beiden Aufrufe der **laufenden** Kassen-Sitzung. Anders als die drei in
+ * pairing.ts haben sie eine Identitaet: sie laufen ueber `registerUserAuth`
+ * (ID-Token als Bearer, Sitzung als Kopfzeile `register-session`) und nehmen
+ * darum einen fertigen [KasseneckTransport] entgegen wie jeder andere
+ * Endpunkt-Aufruf dieses Pakets.
+ *
+ * Beide fuehren **keinen einzigen Parameter**: welche Sitzung gemeint ist,
+ * steht im Token und in der Kopfzeile. Der Parameter `cashregisterId`, den man
+ * im Rumpf sieht, kommt aus der Anmeldung.
+ *
+ * Das Backend setzt fuer beide `allowRegisterUser`; mit `apiKeyAuth` sind sie
+ * nicht erreichbar (dieses Paket bildet das nicht nach — wer darf, entscheidet
+ * das Backend).
+ */
+/**
+ * Sitzung verlaengern und den neuen Ablaufzeitpunkt liefern (Millisekunden
+ * seit 1970).
+ *
+ * Die Sitzung lebt 90 Sekunden; die Browser-Kasse erneuert alle 30. Ist sie
+ * bereits beendet oder uebernommen, antwortet das Backend fachlich ("Sitzung
+ * beendet — bitte neu anmelden.") — dann hilft nur eine neue Anmeldung ueber
+ * `registerUserLogin`.
+ */
+export async function renewRegisterSession(rufen) {
+    const daten = await rufen('renewRegisterSession');
+    const expiresAt = daten?.expiresAt;
+    if (typeof expiresAt !== 'number' || !Number.isFinite(expiresAt)) {
+        // Ohne brauchbaren Ablaufzeitpunkt weiss die Kasse nicht, wann sie das
+        // naechste Mal erneuern muss — das ist ein Antwortfehler und kein Erfolg.
+        throw new KasseneckValidationError('renewRegisterSession', 'Antwort enthaelt keinen Ablaufzeitpunkt (data.expiresAt fehlt)', 'response');
+    }
+    return expiresAt;
+}
+/**
+ * Sitzung beenden und den Lizenzplatz sofort freigeben — der regulaere Weg des
+ * Abmeldens.
+ *
+ * Das Backend antwortet mit `{ok:true}`; dieser Aufruf prueft das Feld
+ * **nicht**: dass der Vorgang gelang, sagt bereits die Erfolgshuelle, die der
+ * Transport auswertet. Eine zweite Pruefung derselben Aussage braeche nur an
+ * einer harmlosen Vertragsaenderung — ausgerechnet beim Abmelden, dem Aufruf,
+ * der auch dann durchgehen soll, wenn sonst nichts mehr geht.
+ */
+export async function endRegisterSession(rufen) {
+    await rufen('endRegisterSession');
+}

package/dist/esm/vienna-time.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Server-Zeitstempel parsen: ohne Offset = Wiener Wanduhrzeit, mit
+ * Offset/`Z` = bereits ein echter Zeitpunkt. Ergebnis ist immer ein echter
+ * Zeitpunkt (JS-`Date`, intern UTC-Millisekunden seit Epoch).
+ */
+export declare function parseServerTimeStamp(raw: string): Date;
+/** Wiener Wanduhrzeit: die Ziffern, die eine Uhr in Wien anzeigt. `month` ist 1-12. */
+export interface ViennaWallClock {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    millisecond: number;
+}
+/**
+ * Echter Zeitpunkt -> Wiener Wanduhrzeit (Gegenstueck zu
+ * [parseServerTimeStamp]). Der Versatz kommt aus derselben Sommerzeitregel wie
+ * die Hinrichtung; hier ist er direkt anwendbar, weil der Zeitpunkt schon
+ * feststeht.
+ */
+export declare function toViennaWallClock(zeitpunkt: Date): ViennaWallClock;