@kreiseck/kasseneck-api 0.6.7

package/dist/cjs/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;

package/dist/cjs/vienna-time.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseServerTimeStamp = parseServerTimeStamp;
+exports.toViennaWallClock = toViennaWallClock;
+/**
+ * Deutung von Server-Zeitstempeln in der Geschaeftszeitzone Europe/Vienna —
+ * Zwilling von `ViennaTime.parseServerTimeStamp` in
+ * kasseneck_api/lib/services/vienna_time.dart.
+ *
+ * Zwei Richtungen: `parseServerTimeStamp` deutet die Nutzlast als Zeitpunkt,
+ * `toViennaWallClock` liest zu einem Zeitpunkt die Wiener Wanduhrzeit zurueck.
+ * Die Rueckrichtung braucht jeder, der aus einem Zeitpunkt einen fachlichen
+ * Kalenderwert ableitet (Berichtsmonat, Tagesabgrenzung): die eingebauten
+ * `getMonth()`/`getFullYear()` liefern die Zeitzone des ausfuehrenden
+ * Rechners, und ein Beleg vom 1. Maerz 00:30 Wiener Zeit faellt damit auf
+ * einer UTC-Maschine in den Februar. Weitere Anzeigehilfen des Dart-Vorbilds
+ * (`dayKey`, `now()`) sind nicht Teil dieses Pakets.
+ *
+ * Der Kasseneck-Server liefert Zeitstempel uneinheitlich: neue Belege als
+ * Wiener Wanduhrzeit ohne Offset (`getLokalAustriaTimeFinanzamtFormat()` im
+ * Backend, Format `YYYY-MM-DDTHH:mm:ss`), manche aeltere/andere Felder als
+ * echten Zeitpunkt mit `Z`/Offset. `new Date(raw)` allein ist dafuer
+ * ungeeignet: JS deutet einen offsetlosen ISO-String als **lokale** Zeit des
+ * ausfuehrenden Rechners — auf einer Wiener Maschine zufaellig richtig, in
+ * jeder anderen Zeitzone (z. B. einer Browser-Kasse im Ausland) falsch.
+ */
+const STUNDE_MS = 60 * 60 * 1000;
+const NAIVER_ZEITSTEMPEL = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?$/;
+const HAT_ZEITZONE = /Z$|[+-]\d{2}:?\d{2}$/;
+/**
+ * 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).
+ */
+function parseServerTimeStamp(raw) {
+    const trimmed = raw.trim();
+    if (HAT_ZEITZONE.test(trimmed)) {
+        const zeitpunkt = new Date(trimmed);
+        // `new Date` macht aus '2026-99-99T00:00:00Z' klaglos ein Invalid Date:
+        // eine Zeitzone allein macht noch kein Datum. Ohne diese Pruefung wandert
+        // der Unsinn still weiter und wird erst in einer Ableitung zu NaN — dort,
+        // wo niemand mehr auf den Zeitstempel schaut.
+        if (Number.isNaN(zeitpunkt.getTime())) {
+            throw new Error(`Zeitstempel: unlesbares Format "${raw}"`);
+        }
+        return zeitpunkt;
+    }
+    const match = NAIVER_ZEITSTEMPEL.exec(trimmed);
+    if (!match) {
+        throw new Error(`Zeitstempel: unlesbares Format "${raw}"`);
+    }
+    const [, jahr, monat, tag, stunde, minute, sekunde, bruchteil] = match;
+    return fromViennaWallClock({
+        year: Number(jahr),
+        month: Number(monat),
+        day: Number(tag),
+        hour: Number(stunde),
+        minute: Number(minute),
+        second: Number(sekunde),
+        millisecond: bruchteil ? Number(bruchteil.padEnd(3, '0').slice(0, 3)) : 0,
+    });
+}
+/**
+ * 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.
+ */
+function toViennaWallClock(zeitpunkt) {
+    const utcMs = zeitpunkt.getTime();
+    // Ein Invalid Date wuerde hier lautlos zu NaN in jedem Feld — und damit zu
+    // einem NaN-Berichtsmonat beim Aufrufer.
+    if (Number.isNaN(utcMs)) {
+        throw new Error('Zeitpunkt: unbrauchbarer Wert (Invalid Date)');
+    }
+    const versatzMs = (istSommerzeit(utcMs) ? 2 : 1) * STUNDE_MS;
+    const verschoben = new Date(utcMs + versatzMs);
+    return {
+        year: verschoben.getUTCFullYear(),
+        month: verschoben.getUTCMonth() + 1,
+        day: verschoben.getUTCDate(),
+        hour: verschoben.getUTCHours(),
+        minute: verschoben.getUTCMinutes(),
+        second: verschoben.getUTCSeconds(),
+        millisecond: verschoben.getUTCMilliseconds(),
+    };
+}
+/** Wiener Wanduhrzeit (Ziffern wie angezeigt) -> echter Zeitpunkt (UTC). */
+function fromViennaWallClock(wand) {
+    const basisUtcMs = Date.UTC(wand.year, wand.month - 1, wand.day, wand.hour, wand.minute, wand.second, wand.millisecond);
+    // Erst Sommerzeit annehmen; stimmt die Annahme fuer den resultierenden
+    // Zeitpunkt, war sie richtig — sonst gilt Winterzeit (wie im Dart-Vorbild).
+    const sommerVariante = basisUtcMs - 2 * STUNDE_MS;
+    if (istSommerzeit(sommerVariante)) {
+        return new Date(sommerVariante);
+    }
+    return new Date(basisUtcMs - 1 * STUNDE_MS);
+}
+/** EU-Sommerzeit: letzter Sonntag im Maerz 01:00 UTC bis letzter Sonntag im Oktober 01:00 UTC. */
+function istSommerzeit(utcMs) {
+    const jahr = new Date(utcMs).getUTCFullYear();
+    const start = letzterSonntagUtcMs(jahr, 3);
+    const ende = letzterSonntagUtcMs(jahr, 10);
+    return utcMs >= start && utcMs < ende;
+}
+/** Letzter Sonntag des Monats, 01:00 UTC (EU-Umstellungszeitpunkt). */
+function letzterSonntagUtcMs(jahr, monat) {
+    const letzterTag = new Date(Date.UTC(jahr, monat, 0)).getUTCDate();
+    // JS-Wochentag (0=Sonntag..6=Samstag) ist bereits die Anzahl Tage seit dem
+    // letzten Sonntag — keine Umrechnung noetig (anders als Darts weekday, das
+    // Montag=1..Sonntag=7 zaehlt und dafuer `% 7` braucht).
+    const wochentag = new Date(Date.UTC(jahr, monat - 1, letzterTag)).getUTCDay();
+    return Date.UTC(jahr, monat - 1, letzterTag - wochentag, 1, 0, 0, 0);
+}

package/dist/esm/client/api.d.ts

@@ -0,0 +1,75 @@
+import type { Cashregister, HobexReceipt, Receipt, ReportMonth, StripeUrlSession } from '../models/index.js';
+import { type CreateStripeLinkOptions, type StripeCaptureResult } from '../payments/stripe.js';
+import { type HobexPayOptions, type HobexRefundOptions } from '../payments/hobex.js';
+import { type TransportOptions } from './transport.js';
+import { type CashboxStatus, type SignatureStatus } from './status.js';
+import { type ListMyReceiptsOptions, type ReceiptList, type ReceiptWithCompany, type SellReceiptOptions, type CancelReceiptOptions, type CancelReceiptResult, type CreateCancelReceiptOptions } from './receipts.js';
+/**
+ * Schlichte Factory ueber den Endpunkt-Funktionen: bindet einen Transport
+ * einmal und liefert die Aufrufe ohne den wiederkehrenden ersten Parameter.
+ * Bewusst **keine** Klasse und keine Vererbung — die Aufrufe sind freie
+ * Funktionen (siehe receipts.ts) und bleiben einzeln importierbar; wer sie
+ * lieber einzeln nimmt, verliert nichts.
+ *
+ * Hier stehen **alle** Endpunkt-Aufrufe des Pakets: Belege, Berichte, Status,
+ * Zahlungen und die beiden Sitzungs-Aufrufe der Browser-Kasse. Was kein
+ * Endpunkt-Aufruf ist (Druck, Beleg-Darstellung), gehoert nicht hierher. Der
+ * Grund fuer die Vollstaendigkeit ist der Zweck der Fassade: ein **einziger**
+ * Konstruktionsweg je Anmeldung. Fehlte eine Endpunkt-Familie, muesste ein
+ * Aufrufer fuer sie zusaetzlich [createTransport] mit denselben Optionen bauen
+ * und haette zwei Wege fuer dieselbe Anmeldung nebeneinander.
+ *
+ * **Eine Ausnahme, und sie folgt aus genau diesem Grund:** Kopplung,
+ * Benutzerliste des Geraets und PIN-Anmeldung (`@kreiseck/kasseneck-api/register`)
+ * stehen **nicht** hier. Diese Fassade wird mit einer Anmeldung gebaut, jene
+ * drei laufen aber, **bevor** es eine gibt. Stuenden sie darin, sagte die
+ * Fassade eine Anmeldung zu, die fuer sie nicht gilt: ein Aufrufer riefe
+ * `pairRegisterDevice` an einer mit `apiKeyAuth` gebauten Fassade und glaubte,
+ * der Schluessel haette dabei etwas zu sagen. Sie bringen ihre
+ * Verbindungsangaben stattdessen selbst mit.
+ */
+export interface KasseneckApi {
+    /** Normalbeleg (Verkauf). */
+    sellReceipt(options: SellReceiptOptions): Promise<Receipt>;
+    /** Normalbeleg samt Firmen-/Druckdaten fuer den Belegdruck. */
+    sellReceiptWithCompany(options: SellReceiptOptions): Promise<ReceiptWithCompany>;
+    /** Storno eines bestehenden Belegs — voll oder in Teilen, ueber den Storno-Endpunkt. */
+    cancelReceipt(options: CancelReceiptOptions): Promise<CancelReceiptResult>;
+    /** Storno aus frei uebergebenen Positionen. */
+    createCancelReceipt(options: CreateCancelReceiptOptions): Promise<Receipt>;
+    /** Nullbeleg (RKSV-Pruefbeleg). */
+    zeroReceipt(): Promise<Receipt>;
+    /** Einzelnen Beleg holen. */
+    getReceipt(receiptId: string): Promise<Receipt>;
+    /** Einzelnen Beleg samt Firmen-/Druckdaten holen. */
+    getReceiptWithCompany(receiptId: string): Promise<ReceiptWithCompany>;
+    /** Verschluesselte Volltext-Belegnummer erzeugen. */
+    generateFullReceiptId(receiptId: string): Promise<string>;
+    /** Berichtsmonat des ersten Belegs (nicht fuer den Kassen-Benutzer-Weg). */
+    getFirstReceiptDate(): Promise<ReportMonth>;
+    /** Belegliste einer Kasse samt Kennzahlen (nur mit ID-Token, siehe receipts.ts). */
+    listMyReceipts(options: ListMyReceiptsOptions): Promise<ReceiptList>;
+    /** Kassen des angemeldeten Benutzers (nur mit ID-Token, siehe cashregisters.ts). */
+    listMyCashregisters(): Promise<Cashregister[]>;
+    /** Tagesbericht als PDF (Kalendertag nach Wiener Zeit). */
+    downloadDailyReport(date: Date): Promise<Uint8Array>;
+    /** Monatsbericht als PDF (Endpunkt `downloadReport`). */
+    downloadMonthlyReport(reportMonth: ReportMonth): Promise<Uint8Array>;
+    /** Betriebsstatus der Kasse bei FinanzOnline. */
+    getCashboxStatus(): Promise<CashboxStatus>;
+    /** Status der Signatureinheit bei FinanzOnline. */
+    getSignatureStatus(zertifikatNrHex: string): Promise<SignatureStatus>;
+    /** Stripe-Zahlungslink erzeugen (Endpunkt `createPaymentLinkStripe`). */
+    createStripeLink(options: CreateStripeLinkOptions): Promise<StripeUrlSession>;
+    /** Reservierte Stripe-Zahlung einziehen. */
+    stripeCaptureIntent(stripeSessionId: string): Promise<StripeCaptureResult>;
+    /** Karte ueber die Hobex-Cloud belasten. */
+    hobexPay(options: HobexPayOptions): Promise<HobexReceipt>;
+    /** Hobex-Cloud-Zahlung erstatten (ohne Rueckgabewert, siehe payments/hobex.ts). */
+    hobexRefund(options: HobexRefundOptions): Promise<void>;
+    /** Kassen-Sitzung verlaengern; liefert den neuen Ablauf (nur Kassen-Benutzer). */
+    renewRegisterSession(): Promise<number>;
+    /** Kassen-Sitzung beenden und den Lizenzplatz freigeben (nur Kassen-Benutzer). */
+    endRegisterSession(): Promise<void>;
+}
+export declare function createKasseneckApi(options: TransportOptions): KasseneckApi;

package/dist/esm/client/api.js

@@ -0,0 +1,37 @@
+import { createStripeLink, stripeCaptureIntent, } from '../payments/stripe.js';
+import { hobexPay, hobexRefund } from '../payments/hobex.js';
+import { createTransport, createBinaryTransport } from './transport.js';
+import { downloadDailyReport, downloadMonthlyReport } from './reports.js';
+import { getCashboxStatus, getSignatureStatus } from './status.js';
+import { sellReceipt, sellReceiptWithCompany, cancelReceipt, createCancelReceipt, zeroReceipt, getReceipt, getReceiptWithCompany, generateFullReceiptId, getFirstReceiptDate, listMyReceipts, } from './receipts.js';
+import { listMyCashregisters } from './cashregisters.js';
+import { renewRegisterSession, endRegisterSession } from '../register/session.js';
+export function createKasseneckApi(options) {
+    const rufen = createTransport(options);
+    // Zweiter Einstiegspunkt fuer die PDF-Downloads; dieselben Optionen,
+    // dieselbe Anmeldung — nur die Antwort wird als Bytes gelesen.
+    const rufenBinaer = createBinaryTransport(options);
+    return {
+        sellReceipt: (o) => sellReceipt(rufen, o),
+        sellReceiptWithCompany: (o) => sellReceiptWithCompany(rufen, o),
+        cancelReceipt: (o) => cancelReceipt(rufen, o),
+        createCancelReceipt: (o) => createCancelReceipt(rufen, o),
+        zeroReceipt: () => zeroReceipt(rufen),
+        getReceipt: (receiptId) => getReceipt(rufen, receiptId),
+        getReceiptWithCompany: (receiptId) => getReceiptWithCompany(rufen, receiptId),
+        generateFullReceiptId: (receiptId) => generateFullReceiptId(rufen, receiptId),
+        getFirstReceiptDate: () => getFirstReceiptDate(rufen),
+        listMyReceipts: (o) => listMyReceipts(rufen, o),
+        listMyCashregisters: () => listMyCashregisters(rufen),
+        downloadDailyReport: (date) => downloadDailyReport(rufenBinaer, date),
+        downloadMonthlyReport: (reportMonth) => downloadMonthlyReport(rufenBinaer, reportMonth),
+        getCashboxStatus: () => getCashboxStatus(rufen),
+        getSignatureStatus: (zertifikatNrHex) => getSignatureStatus(rufen, zertifikatNrHex),
+        createStripeLink: (o) => createStripeLink(rufen, o),
+        stripeCaptureIntent: (stripeSessionId) => stripeCaptureIntent(rufen, stripeSessionId),
+        hobexPay: (o) => hobexPay(rufen, o),
+        hobexRefund: (o) => hobexRefund(rufen, o),
+        renewRegisterSession: () => renewRegisterSession(rufen),
+        endRegisterSession: () => endRegisterSession(rufen),
+    };
+}

package/dist/esm/client/auth.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Die zwei Anmeldewege ans Kasseneck-Backend — gleichrangig, austauschbar,
+ * keiner ist der bevorzugte:
+ *
+ * - `apiKeyAuth` — der Weg der Geraete, POS-Apps und Dritten: der `api_key` als
+ *   Bearer plus die Kopfzeile `cashregister-token` (wie im Flutter-Zwilling
+ *   `kasseneck_api`).
+ * - `registerUserAuth` — der Weg der Browser-Kasse: ein Kassen-Benutzer, per
+ *   PIN an einem gekoppelten Geraet angemeldet. Firebase-ID-Token als Bearer,
+ *   die laufende Sitzung als Kopfzeile `register-session`, die Kasse als
+ *   Parameter `cashregisterId` in der Nutzlast.
+ *
+ * Eine Anmeldung liefert **nur** Kopfzeilen und ggf. Zusatzparameter. Sie
+ * fuehrt keine eigenen HTTP-Aufrufe, kennt den Transport nicht und haelt keinen
+ * Zustand — genau deshalb ist sie austauschbar und einzeln testbar.
+ *
+ * Das Paket weiss **nichts** von Firebase: `registerUserAuth` bekommt eine
+ * Funktion, die ein gueltiges ID-Token liefert (darf `async` sein). Sie wird
+ * bei **jedem** Aufruf befragt — Firebase-ID-Tokens laufen nach einer Stunde
+ * ab, die Sitzung der Browser-Kasse lebt sogar nur 90 Sekunden und wird alle
+ * 30 Sekunden erneuert; ein einmal gemerkter Wert waere also bald tot.
+ */
+/** Was eine Anmeldung zu einer Anfrage beisteuert. */
+export interface AuthCredentials {
+    /** Kopfzeilen der Anfrage (mindestens `Authorization`). */
+    headers: Record<string, string>;
+    /** Zusatzparameter, die in die Nutzlast wandern (z. B. `cashregisterId`). */
+    params: Record<string, unknown>;
+}
+/**
+ * Eine Anmeldung ist eine Funktion, die pro Anfrage frische Zugangsdaten
+ * liefert (synchron oder asynchron).
+ */
+export type KasseneckAuth = () => AuthCredentials | Promise<AuthCredentials>;
+export interface ApiKeyAuthOptions {
+    /** API-Schluessel im Format `kr_<env>_<...>` (opak). */
+    apiKey: string;
+    /** Kassen-Token der Kasse, an der gearbeitet wird (`cb_<env>_<...>`). */
+    cashregisterToken: string;
+}
+export interface RegisterUserAuthOptions {
+    /** Liefert ein gueltiges Firebase-ID-Token; wird pro Anfrage befragt. */
+    getIdToken: () => string | Promise<string>;
+    /** Liefert die laufende Kassen-Sitzung; wird pro Anfrage befragt. */
+    getSessionId: () => string | Promise<string>;
+    /** Kasse, an der der Kassen-Benutzer angemeldet ist. */
+    cashregisterId: string;
+}
+/** Anmeldung per API-Schluessel und Kassen-Token (Geraete, POS-Apps, Dritte). */
+export declare function apiKeyAuth(options: ApiKeyAuthOptions): KasseneckAuth;
+/** Anmeldung eines Kassen-Benutzers der Browser-Kasse (ID-Token + Sitzung). */
+export declare function registerUserAuth(options: RegisterUserAuthOptions): KasseneckAuth;

package/dist/esm/client/auth.js

@@ -0,0 +1,68 @@
+/**
+ * Die zwei Anmeldewege ans Kasseneck-Backend — gleichrangig, austauschbar,
+ * keiner ist der bevorzugte:
+ *
+ * - `apiKeyAuth` — der Weg der Geraete, POS-Apps und Dritten: der `api_key` als
+ *   Bearer plus die Kopfzeile `cashregister-token` (wie im Flutter-Zwilling
+ *   `kasseneck_api`).
+ * - `registerUserAuth` — der Weg der Browser-Kasse: ein Kassen-Benutzer, per
+ *   PIN an einem gekoppelten Geraet angemeldet. Firebase-ID-Token als Bearer,
+ *   die laufende Sitzung als Kopfzeile `register-session`, die Kasse als
+ *   Parameter `cashregisterId` in der Nutzlast.
+ *
+ * Eine Anmeldung liefert **nur** Kopfzeilen und ggf. Zusatzparameter. Sie
+ * fuehrt keine eigenen HTTP-Aufrufe, kennt den Transport nicht und haelt keinen
+ * Zustand — genau deshalb ist sie austauschbar und einzeln testbar.
+ *
+ * Das Paket weiss **nichts** von Firebase: `registerUserAuth` bekommt eine
+ * Funktion, die ein gueltiges ID-Token liefert (darf `async` sein). Sie wird
+ * bei **jedem** Aufruf befragt — Firebase-ID-Tokens laufen nach einer Stunde
+ * ab, die Sitzung der Browser-Kasse lebt sogar nur 90 Sekunden und wird alle
+ * 30 Sekunden erneuert; ein einmal gemerkter Wert waere also bald tot.
+ */
+import { KasseneckAuthError } from './errors.js';
+/** Anmeldung per API-Schluessel und Kassen-Token (Geraete, POS-Apps, Dritte). */
+export function apiKeyAuth(options) {
+    // Fehlende Zugangsdaten fallen hier auf und nicht erst als 401 vom Backend.
+    // Die Meldung nennt nur das leere Feld, nie einen Wert.
+    if (!options.apiKey) {
+        throw new KasseneckAuthError('apiKeyAuth: apiKey fehlt');
+    }
+    if (!options.cashregisterToken) {
+        throw new KasseneckAuthError('apiKeyAuth: cashregisterToken fehlt');
+    }
+    const { apiKey, cashregisterToken } = options;
+    // Pro Aufruf ein frisches Objekt: der Transport (oder ein Aufrufer) darf
+    // daran herumschreiben, ohne die naechste Anfrage zu vergiften.
+    return () => ({
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            'cashregister-token': cashregisterToken,
+        },
+        params: {},
+    });
+}
+/** Anmeldung eines Kassen-Benutzers der Browser-Kasse (ID-Token + Sitzung). */
+export function registerUserAuth(options) {
+    if (!options.cashregisterId) {
+        throw new KasseneckAuthError('registerUserAuth: cashregisterId fehlt');
+    }
+    const { getIdToken, getSessionId, cashregisterId } = options;
+    return async () => {
+        // Beides bei JEDEM Aufruf frisch — siehe Modulkommentar (Ablaufzeiten).
+        const [idToken, sessionId] = await Promise.all([getIdToken(), getSessionId()]);
+        if (!idToken) {
+            throw new KasseneckAuthError('registerUserAuth: getIdToken lieferte kein Token');
+        }
+        if (!sessionId) {
+            throw new KasseneckAuthError('registerUserAuth: getSessionId lieferte keine Sitzung');
+        }
+        return {
+            headers: {
+                Authorization: `Bearer ${idToken}`,
+                'register-session': sessionId,
+            },
+            params: { cashregisterId },
+        };
+    };
+}

package/dist/esm/client/cashregisters.d.ts

@@ -0,0 +1,21 @@
+import { type Cashregister } from '../models/index.js';
+import type { KasseneckTransport } from './transport.js';
+/**
+ * Kassen-Endpunkte.
+ *
+ * **Anmeldeweg:** `listMyCashregisters` laeuft im Backend unter
+ * `checkRequest(req, 'customer', …, {allowRegisterUser: true})` — der Bearer
+ * muss also ein Firebase-ID-Token sein. Mit `apiKeyAuth` (api_key als Bearer)
+ * ist dieser Endpunkt **nicht** erreichbar; fuer die Browser-Kasse ist
+ * `registerUserAuth` der Weg. Dieses Paket bildet das nicht nach — wer darf,
+ * entscheidet allein das Backend. Der Hinweis steht hier, damit ein Leser
+ * nicht raten muss.
+ */
+/**
+ * Die Kassen, die dem angemeldeten Benutzer offenstehen — fuer einen
+ * Kassen-Benutzer genau die ihm zugewiesenen (das Backend filtert, siehe
+ * `registerAuth.darfKasse`).
+ *
+ * Ohne diesen Aufruf kann eine Browser-Kasse ihre Kasse nicht auswaehlen.
+ */
+export declare function listMyCashregisters(rufen: KasseneckTransport): Promise<Cashregister[]>;

package/dist/esm/client/cashregisters.js

@@ -0,0 +1,33 @@
+import { fromCashregisterPayload } from '../models/index.js';
+import { KasseneckValidationError } from './errors.js';
+/**
+ * Kassen-Endpunkte.
+ *
+ * **Anmeldeweg:** `listMyCashregisters` laeuft im Backend unter
+ * `checkRequest(req, 'customer', …, {allowRegisterUser: true})` — der Bearer
+ * muss also ein Firebase-ID-Token sein. Mit `apiKeyAuth` (api_key als Bearer)
+ * ist dieser Endpunkt **nicht** erreichbar; fuer die Browser-Kasse ist
+ * `registerUserAuth` der Weg. Dieses Paket bildet das nicht nach — wer darf,
+ * entscheidet allein das Backend. Der Hinweis steht hier, damit ein Leser
+ * nicht raten muss.
+ */
+/**
+ * Die Kassen, die dem angemeldeten Benutzer offenstehen — fuer einen
+ * Kassen-Benutzer genau die ihm zugewiesenen (das Backend filtert, siehe
+ * `registerAuth.darfKasse`).
+ *
+ * Ohne diesen Aufruf kann eine Browser-Kasse ihre Kasse nicht auswaehlen.
+ */
+export async function listMyCashregisters(rufen) {
+    const daten = await rufen('listMyCashregisters');
+    const liste = daten?.cashregisters;
+    if (!Array.isArray(liste)) {
+        throw new KasseneckValidationError('listMyCashregisters', 'Antwort enthaelt keine Kassenliste (data.cashregisters fehlt)', 'response');
+    }
+    return liste.map((eintrag, i) => {
+        const nutzlast = (typeof eintrag === 'object' && eintrag !== null ? eintrag : {});
+        // Die Dokument-ID steht in dieser Antwort im Eintrag selbst; der zweite
+        // Parameter ist nur der Rueckfall (siehe fromCashregisterPayload).
+        return fromCashregisterPayload(nutzlast, nutzlast.id ?? String(i));
+    });
+}

package/dist/esm/client/errors.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Die fuenf Fehlerarten des Kasseneck-Clients — bewusst getrennt, weil ein
+ * Aufrufer auf jede anders reagieren muss:
+ *
+ * - `KasseneckValidationError` — die **Form** stimmt nicht: entweder ging
+ *   mangels brauchbarer Eingabe gar keine Anfrage raus, oder die Antwort war
+ *   nicht verwertbar. `scope` trennt die beiden Richtungen. `'request'`: die
+ *   Eingabe des Aufrufers verletzt eine Regel, die dieses Paket schon vor dem
+ *   Senden kennt (Beleg ohne Positionen, unmoegliche Gutscheinkombination) —
+ *   das ist ein Programmierfehler im Aufrufer, kein Betriebszustand.
+ *   `'response'`: das Backend meldete Erfolg, die Nutzlast enthielt aber
+ *   nicht, was der Aufruf zusagt.
+ *
+ * - `KasseneckApiError` — **fachlicher** Fehler. Das Backend antwortet immer
+ *   mit HTTP 200 und legt Erfolg/Misserfolg in den Rumpf
+ *   (`{status:'success'|'error', message, data}`, siehe `successResponse`/
+ *   `errorResponse` im Backend). Ein `status:'error'` heisst: die Anfrage kam
+ *   an und wurde abgelehnt (gesperrte Kasse, fehlendes Modul, ungueltiger
+ *   Parameter). Wiederholen hilft nicht.
+ * - `KasseneckHttpError` — die Antwort war **keine** verwertbare Huelle:
+ *   HTTP 500/404, leerer Rumpf, oder HTTP 200 mit HTML statt JSON (typisch,
+ *   wenn ein Aufruf mangels Rewrite auf der Single-Page-App landet). Beim
+ *   Bericht-Download gelten dieselben Gruende fuer alles, was kein PDF ist.
+ *   `reason` trennt die Faelle maschinenlesbar.
+ * - `KasseneckNetworkError` — die Antwort kam gar nicht: Netz weg, DNS,
+ *   abgebrochene Verbindung oder Zeitueberschreitung (`timedOut`).
+ * - `KasseneckAuthError` — es kam nicht einmal zur Anfrage, weil die Anmeldung
+ *   scheiterte (fehlende Zugangsdaten, oder der Token-/Sitzungsgeber warf).
+ *   In der Browser-Kasse mit ihrer 90-Sekunden-Sitzung ist das Alltag, kein
+ *   Sonderfall.
+ *
+ * **Geheimnisse gehoeren in keinen dieser Fehler.** Fehlermeldungen landen in
+ * Protokollen und Fehlerdiensten; weder `api_key`, Kassen-Token, Firebase-
+ * ID-Token noch Sitzungsbezeichner duerfen dorthin. Deshalb tragen die Fehler
+ * ausschliesslich Funktionsname, HTTP-Status/Inhaltstyp, den vom Paket
+ * formulierten Grund und die vom Backend formulierte Meldung — nie Kopfzeilen,
+ * nie den gesendeten Rumpf und auch nicht den empfangenen Rumpf (der koennte
+ * bei einem fremden Proxy alles Moegliche zurueckspiegeln).
+ *
+ * Aus demselben Grund haengt **keine fremde Ursache** als `cause` an diesen
+ * Fehlern: `console.error(err)` und `util.inspect` drucken die Ursachenkette
+ * mit, und fremde HTTP-Bibliotheken haengen ihre Anfrage an ihre Fehler (axios
+ * `config.headers`, got `options.headers`) — mit dem Bearer-Schluessel darin.
+ * Statt der Ursache selbst traegt `KasseneckNetworkError` ihre **verdichtete**
+ * Form: `causeName`/`causeCode`, beide nur, wenn sie wie ein Bezeichner
+ * aussehen **und** mit keinem der gesendeten Geheimnisse ueberlappen (siehe
+ * `causeDigest`).
+ *
+ * Der Formfilter allein traegt diese Zusage naemlich nicht: der
+ * Sitzungsbezeichner der Browser-Kasse ist selbst bezeichner-foermig und kaeme
+ * durch. Verdichtet werden darf nur, wo die gesendeten Geheimnisse bekannt
+ * sind — also nach dem Bauen der Anfrage. `KasseneckAuthError` traegt darum
+ * **gar keine** Ursachen-Verdichtung: dort ist noch nichts gesendet, es gibt
+ * keine Liste zum Abgleichen, und Diagnose ist an dieser Stelle weniger wert
+ * als die Zusage.
+ */
+/** Verdichtete, geheimnisfreie Form einer fremden Fehlerursache. */
+export interface CauseDigest {
+    causeName?: string | undefined;
+    causeCode?: string | undefined;
+}
+/**
+ * Reduziert eine fremde Ursache auf Name und Code — und verwirft beides, wenn
+ * es kein Bezeichner ist oder mit einem der uebergebenen Geheimnisse
+ * ueberlappt (ein Sitzungsbezeichner sieht durchaus bezeichner-artig aus).
+ *
+ * `geheimnisse` hat bewusst **keinen** Vorgabewert: eine Verdichtung ohne
+ * Abgleichliste waere nur ein Formfilter und damit keine Zusage. Wo die
+ * gesendeten Werte nicht bekannt sind, wird gar nicht verdichtet.
+ */
+export declare function causeDigest(ursache: unknown, geheimnisse: readonly string[]): CauseDigest;
+/** Fachlicher Fehler: HTTP 200, aber `status: 'error'` im Rumpf. */
+export declare class KasseneckApiError extends Error {
+    readonly name = "KasseneckApiError";
+    /** Aufgerufene Backend-Funktion, z. B. `createReceipt`. */
+    readonly functionName: string;
+    /** Meldung des Backends, unveraendert (`message` aus der Huelle). */
+    readonly serverMessage: string;
+    constructor(functionName: string, serverMessage: string);
+}
+/** Warum die Antwort keine verwertbare Huelle war. */
+export type HttpFailureReason = 'server-error' | 'empty-body' | 'not-json' | 'missing-status';
+/** Antwort ohne verwertbare Huelle (HTTP-Fehler, leerer Rumpf, HTML statt JSON). */
+export declare class KasseneckHttpError extends Error {
+    readonly name = "KasseneckHttpError";
+    readonly functionName: string;
+    /** HTTP-Statuscode der Antwort (bei HTML-statt-JSON durchaus 200). */
+    readonly statusCode: number;
+    /** Inhaltstyp der Antwort, falls die Gegenstelle einen gesetzt hat. */
+    readonly contentType: string | undefined;
+    /** Maschinenlesbarer Grund — trennt den Rewrite-Fall vom 500er ohne Textparsen. */
+    readonly reason: HttpFailureReason;
+    constructor(functionName: string, statusCode: number, contentType: string | undefined, reason: HttpFailureReason);
+}
+/** Es kam keine Antwort: Netzfehler oder Zeitueberschreitung. */
+export declare class KasseneckNetworkError extends Error {
+    readonly name = "KasseneckNetworkError";
+    readonly functionName: string;
+    /** true = das Zeitlimit lief ab und die Anfrage wurde abgebrochen. */
+    readonly timedOut: boolean;
+    /** Das geltende Zeitlimit in Millisekunden. */
+    readonly timeoutMs: number;
+    /** Name der zugrunde liegenden Ursache, sofern unbedenklich (s. `causeDigest`). */
+    readonly causeName: string | undefined;
+    /** Code der zugrunde liegenden Ursache, sofern unbedenklich (z. B. `ECONNREFUSED`). */
+    readonly causeCode: string | undefined;
+    constructor(functionName: string, timedOut: boolean, timeoutMs: number, ursache?: CauseDigest);
+}
+/**
+ * Die Anmeldung scheiterte — es ging keine Anfrage raus.
+ *
+ * Dieser Fehler traegt **nichts** aus der fremden Ursache: weder ihre Meldung
+ * (ein Token-Geber fuehrt gern den Token mit, den er gerade nicht erneuern
+ * konnte) noch eine Verdichtung ihres Namens/Codes. Zum Zeitpunkt des
+ * Anmeldefehlers ist noch nichts gesendet, es gibt also keine Liste der
+ * Geheimnisse, gegen die verdichtete Werte geprueft werden koennten — und ein
+ * reiner Formfilter laesst genau die Form durch, die ein Sitzungsbezeichner
+ * hat.
+ */
+export declare class KasseneckAuthError extends Error {
+    readonly name = "KasseneckAuthError";
+    /** Betroffene Backend-Funktion, falls der Fehler bei einem Aufruf entstand. */
+    readonly functionName: string | undefined;
+    /** Vom Paket formulierter Grund — geheimnisfrei, anders als fremde Meldungen. */
+    readonly reason: string;
+    constructor(reason: string, options?: {
+        functionName?: string;
+    });
+}
+/** Woran die Form haengt: an der Eingabe des Aufrufers oder an der Antwort. */
+export type ValidationScope = 'request' | 'response';
+/**
+ * Die Form stimmt nicht — bei `scope: 'request'` ging deshalb keine Anfrage
+ * raus, bei `scope: 'response'` kam eine unbrauchbare zurueck.
+ *
+ * Es gilt dieselbe Zusage wie fuer die uebrigen Fehlerarten: `reason` ist vom
+ * Paket formuliert und geheimnisfrei. Bei `'response'` wird insbesondere
+ * **nichts aus der Antwort** uebernommen — ein fremder Proxy koennte dort
+ * alles Moegliche zurueckspiegeln.
+ */
+export declare class KasseneckValidationError extends Error {
+    readonly name = "KasseneckValidationError";
+    /**
+     * Betroffener Vorgang — meist die Backend-Funktion, bei Pruefungen ohne
+     * Aufruf der Name der Paketfunktion (z. B. `buildReceiptLayout`).
+     */
+    readonly functionName: string;
+    /** Vom Paket formulierter Grund. */
+    readonly reason: string;
+    readonly scope: ValidationScope;
+    constructor(functionName: string, reason: string, scope: ValidationScope);
+}
+/** Alle Fehler, die dieses Paket wirft. */
+export type KasseneckError = KasseneckApiError | KasseneckHttpError | KasseneckNetworkError | KasseneckAuthError | KasseneckValidationError;
+export declare function isKasseneckApiError(fehler: unknown): fehler is KasseneckApiError;
+export declare function isKasseneckHttpError(fehler: unknown): fehler is KasseneckHttpError;
+export declare function isKasseneckNetworkError(fehler: unknown): fehler is KasseneckNetworkError;
+export declare function isKasseneckAuthError(fehler: unknown): fehler is KasseneckAuthError;
+export declare function isKasseneckValidationError(fehler: unknown): fehler is KasseneckValidationError;