@kreiseck/kasseneck-api 0.31.0 → 1.0.0-rc.2

package/dist/esm/partner/webhooks.d.ts

@@ -6,20 +6,20 @@
  * einem, der sonst nichts von diesem Paket benutzt.
  */
 import type { InternerTransport } from '../client/aufrufe.js';
+import type { CashregisterActivationStep, ContractKind, ContractSource, PartnerEnv } from './typen.js';
 import { type VerifyWebhookOptions, type WebhookVerifyReason } from './webhook-signatur.js';
 /**
- * Alle Ereignisse, die ein Webhook abonnieren **und proben** kann. Ein
+ * Alle Ereignisse, die ein Webhook abonnieren **und proben** kann, in der
+ * Reihenfolge des Backend-Katalogs (`listPartnerWebhooks().events`). Ein
  * Endpunkt bekommt ausschliesslich die, die in seiner `events`-Liste stehen.
  *
- * **Noch nicht in der Liste:** `customer.avv_accepted` und
- * `customer.terms_accepted`. Das Backend bietet sie inzwischen zum Abonnieren
- * an; die Liste wird mit dem Dart-Zwilling gemeinsam erweitert, weil beide
- * gegeneinander geprueft werden. Abonnieren geht trotzdem schon (`events`
- * nimmt jeden Namen), die Nutzlast beschreibt [ContractAcceptedEventData].
+ * Die Nutzlasten der Ereignisse, die `/v3` uebersetzt, beschreiben
+ * [ContractAcceptedEventData], [SignatureFailedEventData] und
+ * [CashregisterFailedEventData].
  */
-export declare const PARTNER_WEBHOOK_EVENTS: readonly ["customer.created", "customer.updated", "customer.status_changed", "customer.fon_verified", "customer.live_enabled", "signature.requested", "signature.ready", "signature.failed", "cashregister.created", "cashregister.live", "cashregister.failed", "app.version.accepted", "app.version.rejected", "webhook.test"];
+export declare const PARTNER_WEBHOOK_EVENTS: readonly ["customer.created", "customer.updated", "customer.status_changed", "customer.fon_verified", "customer.live_enabled", "customer.avv_accepted", "customer.terms_accepted", "signature.requested", "signature.ready", "signature.failed", "cashregister.created", "cashregister.live", "cashregister.failed", "app.version.accepted", "app.version.rejected", "webhook.test"];
 export type PartnerWebhookEventType = typeof PARTNER_WEBHOOK_EVENTS[number];
-export declare function istPartnerWebhookEvent(wert: unknown): wert is PartnerWebhookEventType;
+export declare function isPartnerWebhookEvent(value: unknown): value is PartnerWebhookEventType;
 /**
  * Die Felder des Umschlags, so wie er auf der Leitung liegt.
  *
@@ -27,7 +27,7 @@ export declare function istPartnerWebhookEvent(wert: unknown): wert is PartnerWe
  * genau ein solches Feld verschwindet sonst auf einer Seite, ohne dass etwas
  * rot wird.
  */
-export declare const WEBHOOK_UMSCHLAG_FELDER: readonly ["id", "type", "createdAt", "partnerId", "test", "data"];
+export declare const WEBHOOK_ENVELOPE_FIELDS: readonly ["id", "type", "createdAt", "partnerId", "test", "data"];
 /**
  * Die Huelle jeder Zustellung. `type` bleibt bewusst offen fuer unbekannte
  * Werte (`(string & {})`): ein spaeter ergaenztes Ereignis soll einen
@@ -69,14 +69,6 @@ export interface PartnerWebhookEvent<T = Record<string, unknown>> {
  * Webhook hat.
  */
 export type WebhookApiVersion = 'v1' | 'v3';
-/** Art des Vertrags in `customer.avv_accepted` / `customer.terms_accepted`. */
-export type ContractKind = 'avv' | 'terms';
-/**
- * Wo der Betrieb bestaetigt hat. Unter `v1` hiessen die ersten fuenf
- * `einrichten`, `prozess`, `partner_vollmacht`, `admin_papier`,
- * `papier_upload`; `app` und `portal` sind in beiden Sprachen gleich.
- */
-export type ContractSource = 'setup_link' | 'process_link' | 'partner_power_of_attorney' | 'admin_paper' | 'paper_upload' | 'app' | 'portal' | (string & {});
 /**
  * Nutzlast von `customer.avv_accepted` und `customer.terms_accepted` in der
  * Sprache `v3`. Ein Webhook mit `apiVersion: 'v1'` schickt hier weiter
@@ -90,6 +82,41 @@ export interface ContractAcceptedEventData {
     confirmedAt: number;
     source: ContractSource;
 }
+/**
+ * Nutzlast von `signature.failed` in der Sprache `v3`. `code` ist immer
+ * `signature_failed` (FinanzOnline hat die Registrierung abgelehnt, `rc`
+ * nennt den Rueckgabecode); die Ursache im Einzelnen steht am Antrag
+ * (`getCustomerSignatureStatus`, `requests[].error.code`, siehe
+ * [SIGNATURE_ERROR_CODES]). `message` ist ein Text fuer Menschen.
+ */
+export interface SignatureFailedEventData {
+    customerId: string;
+    companyName: string;
+    requestId: string;
+    code: 'signature_failed' | (string & {});
+    /** Rueckgabecode von FinanzOnline, falls es einen gab. */
+    rc: string | null;
+    message: string;
+}
+/**
+ * Nutzlast von `cashregister.failed` in der Sprache `v3`: an welchem Schritt
+ * die Inbetriebnahme stehen blieb und mit welchem Code. Der Server feuert das
+ * Ereignis mit `signature_not_ready`, `fon_missing` oder `activation_failed`.
+ * Fehlende Vertraege (`contracts_pending`) loesen **kein** Ereignis aus: das
+ * meldet `activateCashregister` als Fehler, die Freigabe melden
+ * `customer.avv_accepted` und `customer.terms_accepted`.
+ */
+export interface CashregisterFailedEventData {
+    customerId: string;
+    companyName: string;
+    cashregisterId: string;
+    step: CashregisterActivationStep | null;
+    code: 'signature_not_ready' | 'fon_missing' | 'activation_failed' | (string & {});
+    /** Rueckgabecode von FinanzOnline, falls es einen gab. */
+    rc: string | null;
+    message: string;
+    env: PartnerEnv;
+}
 export type WebhookEventResult = {
     ok: true;
     event: PartnerWebhookEvent;
@@ -113,9 +140,10 @@ export type WebhookEventResult = {
  * Eine ausbleibende Antwort wird bis zu fuenfmal wiederholt (1 min, 5 min,
  * 30 min, 2 h, 12 h) und gilt dann als fehlgeschlagen.
  */
-export declare function parseWebhookEvent(optionen: VerifyWebhookOptions): Promise<WebhookEventResult>;
-/** Stand einer Zustellung; `/v1` sagte `offen`, `zugestellt`, `fehlgeschlagen`, `verworfen`. */
-export type WebhookDeliveryStatus = 'pending' | 'delivered' | 'failed' | 'dropped';
+export declare function parseWebhookEvent(options: VerifyWebhookOptions): Promise<WebhookEventResult>;
+/** Staende einer Zustellung; `/v1` sagte `offen`, `zugestellt`, `fehlgeschlagen`, `verworfen`. */
+export declare const WEBHOOK_DELIVERY_STATUSES: readonly ["pending", "delivered", "failed", "dropped"];
+export type WebhookDeliveryStatus = typeof WEBHOOK_DELIVERY_STATUSES[number];
 export interface PartnerWebhook {
     webhookId: string;
     /** Sprache der Nutzlast; fehlt sie in der Antwort, ist es ein Bestands-Webhook und damit `v1`. */
@@ -173,7 +201,7 @@ export interface DeleteWebhookResult {
     /** Unter `/v1` hiess das Feld `geloescht`. */
     deleted: boolean;
 }
-export interface WebhookListe {
+export interface WebhookList {
     webhooks: PartnerWebhook[];
     /** Der Katalog: Ereignisname und deutscher Text, so wie das Panel ihn zeigt. */
     events: {
@@ -181,7 +209,7 @@ export interface WebhookListe {
         text: string;
     }[];
 }
-export interface WebhookZustellung {
+export interface WebhookDelivery {
     deliveryId: string;
     webhookId: string;
     event: string;
@@ -203,7 +231,7 @@ export interface WebhookZustellung {
  * **Das Secret in der Antwort ist der einzige Weg dazu.** Es sofort dorthin
  * schreiben, wo der Empfaenger es liest — nicht in ein Protokoll.
  */
-export declare function createPartnerWebhook(rufen: InternerTransport, optionen: CreateWebhookOptions): Promise<CreateWebhookResult>;
+export declare function createPartnerWebhook(transport: InternerTransport, options: CreateWebhookOptions): Promise<CreateWebhookResult>;
 /**
  * Ein neues Secret fuer denselben Endpunkt.
  *
@@ -214,22 +242,22 @@ export declare function createPartnerWebhook(rufen: InternerTransport, optionen:
  * Das alte Secret gilt ab der Antwort NICHT mehr: die naechste Zustellung ist
  * schon mit dem neuen signiert. Erst speichern, dann weiterarbeiten.
  */
-export declare function rotatePartnerWebhookSecret(rufen: InternerTransport, webhookId: string): Promise<CreateWebhookResult>;
+export declare function rotatePartnerWebhookSecret(transport: InternerTransport, webhookId: string): Promise<CreateWebhookResult>;
 /** Die Webhook-Endpunkte dieses Partners samt Ereignis-Katalog. */
-export declare function listPartnerWebhooks(rufen: InternerTransport): Promise<WebhookListe>;
+export declare function listPartnerWebhooks(transport: InternerTransport): Promise<WebhookList>;
 /**
  * Aendert einen Endpunkt. Nur die genannten Felder — ein leeres `patch` lehnt
  * das Backend ab (`validation`, Feld `patch`), statt stillschweigend nichts zu
  * tun.
  */
-export declare function updatePartnerWebhook(rufen: InternerTransport, webhookId: string, patch: WebhookPatch): Promise<PartnerWebhook>;
+export declare function updatePartnerWebhook(transport: InternerTransport, webhookId: string, patch: WebhookPatch): Promise<PartnerWebhook>;
 /**
  * Loescht einen Endpunkt. Danach kommt dort nichts mehr an; offene
  * Zustellungen werden verworfen (`dropped`).
  */
-export declare function deletePartnerWebhook(rufen: InternerTransport, webhookId: string): Promise<DeleteWebhookResult>;
+export declare function deletePartnerWebhook(transport: InternerTransport, webhookId: string): Promise<DeleteWebhookResult>;
 /** Eine Zustellung der Probe, so wie `sendPartnerWebhookTest` sie meldet. */
-export interface WebhookTestZustellung {
+export interface WebhookTestDelivery {
     deliveryId: string;
     webhookId: string;
     status: WebhookDeliveryStatus | (string & {});
@@ -239,7 +267,7 @@ export interface WebhookTestResult {
     eventId: string;
     /** Welches Ereignis geprobt wurde — ohne Angabe `webhook.test`. */
     event: string;
-    deliveries: WebhookTestZustellung[];
+    deliveries: WebhookTestDelivery[];
 }
 /**
  * Schickt eine Probe an genau diesen Endpunkt.
@@ -261,13 +289,13 @@ export interface WebhookTestResult {
  * den Namen bei, damit ein Leser der Doku und ein Leser des Codes dasselbe
  * suchen.
  */
-export declare function sendPartnerWebhookTest(rufen: InternerTransport, webhookId: string, event?: PartnerWebhookEventType | (string & {})): Promise<WebhookTestResult>;
+export declare function sendPartnerWebhookTest(transport: InternerTransport, webhookId: string, event?: PartnerWebhookEventType | (string & {})): Promise<WebhookTestResult>;
 /**
  * Die letzten Zustellversuche — mit `webhookId` fuer einen Endpunkt, ohne ihn
  * fuer alle. Die Stelle, an der sich „mein Server bekommt nichts" klaeren
  * laesst, ohne bei Kasseneck nachzufragen.
  */
-export declare function listPartnerWebhookDeliveries(rufen: InternerTransport, optionen?: {
+export declare function listPartnerWebhookDeliveries(transport: InternerTransport, options?: {
     webhookId?: string;
     limit?: number;
-}): Promise<WebhookZustellung[]>;
+}): Promise<WebhookDelivery[]>;

package/dist/esm/partner/webhooks.js

@@ -11,14 +11,13 @@ import { verifyWebhookSignature, } from './webhook-signatur.js';
 // Ereignisse
 // ---------------------------------------------------------------------------
 /**
- * Alle Ereignisse, die ein Webhook abonnieren **und proben** kann. Ein
+ * Alle Ereignisse, die ein Webhook abonnieren **und proben** kann, in der
+ * Reihenfolge des Backend-Katalogs (`listPartnerWebhooks().events`). Ein
  * Endpunkt bekommt ausschliesslich die, die in seiner `events`-Liste stehen.
  *
- * **Noch nicht in der Liste:** `customer.avv_accepted` und
- * `customer.terms_accepted`. Das Backend bietet sie inzwischen zum Abonnieren
- * an; die Liste wird mit dem Dart-Zwilling gemeinsam erweitert, weil beide
- * gegeneinander geprueft werden. Abonnieren geht trotzdem schon (`events`
- * nimmt jeden Namen), die Nutzlast beschreibt [ContractAcceptedEventData].
+ * Die Nutzlasten der Ereignisse, die `/v3` uebersetzt, beschreiben
+ * [ContractAcceptedEventData], [SignatureFailedEventData] und
+ * [CashregisterFailedEventData].
  */
 export const PARTNER_WEBHOOK_EVENTS = [
     'customer.created',
@@ -26,6 +25,8 @@ export const PARTNER_WEBHOOK_EVENTS = [
     'customer.status_changed',
     'customer.fon_verified',
     'customer.live_enabled',
+    'customer.avv_accepted',
+    'customer.terms_accepted',
     'signature.requested',
     'signature.ready',
     'signature.failed',
@@ -36,8 +37,8 @@ export const PARTNER_WEBHOOK_EVENTS = [
     'app.version.rejected',
     'webhook.test',
 ];
-export function istPartnerWebhookEvent(wert) {
-    return typeof wert === 'string' && PARTNER_WEBHOOK_EVENTS.includes(wert);
+export function isPartnerWebhookEvent(value) {
+    return typeof value === 'string' && PARTNER_WEBHOOK_EVENTS.includes(value);
 }
 /**
  * Die Felder des Umschlags, so wie er auf der Leitung liegt.
@@ -46,7 +47,7 @@ export function istPartnerWebhookEvent(wert) {
  * genau ein solches Feld verschwindet sonst auf einer Seite, ohne dass etwas
  * rot wird.
  */
-export const WEBHOOK_UMSCHLAG_FELDER = ['id', 'type', 'createdAt', 'partnerId', 'test', 'data'];
+export const WEBHOOK_ENVELOPE_FIELDS = ['id', 'type', 'createdAt', 'partnerId', 'test', 'data'];
 /**
  * Prueft die Signatur **und** liest das Ereignis — in dieser Reihenfolge. Wer
  * zuerst parst und dann prueft, hat den fremden Rumpf schon durch seinen Code
@@ -62,11 +63,11 @@ export const WEBHOOK_UMSCHLAG_FELDER = ['id', 'type', 'createdAt', 'partnerId',
  * Eine ausbleibende Antwort wird bis zu fuenfmal wiederholt (1 min, 5 min,
  * 30 min, 2 h, 12 h) und gilt dann als fehlgeschlagen.
  */
-export async function parseWebhookEvent(optionen) {
-    const geprueft = await verifyWebhookSignature(optionen);
+export async function parseWebhookEvent(options) {
+    const geprueft = await verifyWebhookSignature(options);
     if (!geprueft.ok)
         return { ok: false, reason: geprueft.reason };
-    const text = typeof optionen.body === 'string' ? optionen.body : new TextDecoder('utf-8').decode(optionen.body);
+    const text = typeof options.body === 'string' ? options.body : new TextDecoder('utf-8').decode(options.body);
     let roh;
     try {
         roh = JSON.parse(text);
@@ -97,6 +98,11 @@ export async function parseWebhookEvent(optionen) {
         },
     };
 }
+// ---------------------------------------------------------------------------
+// Endpunkte verwalten
+// ---------------------------------------------------------------------------
+/** Staende einer Zustellung; `/v1` sagte `offen`, `zugestellt`, `fehlgeschlagen`, `verworfen`. */
+export const WEBHOOK_DELIVERY_STATUSES = ['pending', 'delivered', 'failed', 'dropped'];
 function objekt(wert) {
     return wert !== null && typeof wert === 'object' && !Array.isArray(wert) ? wert : {};
 }
@@ -134,18 +140,18 @@ function webhook(eintrag) {
  * **Das Secret in der Antwort ist der einzige Weg dazu.** Es sofort dorthin
  * schreiben, wo der Empfaenger es liest — nicht in ein Protokoll.
  */
-export async function createPartnerWebhook(rufen, optionen) {
-    const url = typeof optionen?.url === 'string' ? optionen.url.trim() : '';
+export async function createPartnerWebhook(transport, options) {
+    const url = typeof options?.url === 'string' ? options.url.trim() : '';
     if (!url)
         throw new KasseneckValidationError('createPartnerWebhook', 'url fehlt', 'request');
-    if (!Array.isArray(optionen.events) || optionen.events.length === 0) {
+    if (!Array.isArray(options.events) || options.events.length === 0) {
         throw new KasseneckValidationError('createPartnerWebhook', 'events ist leer — ein Endpunkt ohne Ereignis bekaeme nie etwas', 'request');
     }
-    const daten = objekt(await rufen('createPartnerWebhook', {
+    const daten = objekt(await transport('createPartnerWebhook', {
         url,
-        events: optionen.events,
-        description: optionen.description,
-        active: optionen.active,
+        events: options.events,
+        description: options.description,
+        active: options.active,
     }));
     const secret = daten['secret'];
     if (typeof secret !== 'string' || !secret) {
@@ -163,11 +169,11 @@ export async function createPartnerWebhook(rufen, optionen) {
  * Das alte Secret gilt ab der Antwort NICHT mehr: die naechste Zustellung ist
  * schon mit dem neuen signiert. Erst speichern, dann weiterarbeiten.
  */
-export async function rotatePartnerWebhookSecret(rufen, webhookId) {
+export async function rotatePartnerWebhookSecret(transport, webhookId) {
     const id = typeof webhookId === 'string' ? webhookId.trim() : '';
     if (!id)
         throw new KasseneckValidationError('rotatePartnerWebhookSecret', 'webhookId fehlt', 'request');
-    const daten = objekt(await rufen('rotatePartnerWebhookSecret', { webhookId: id }));
+    const daten = objekt(await transport('rotatePartnerWebhookSecret', { webhookId: id }));
     const secret = daten['secret'];
     if (typeof secret !== 'string' || !secret) {
         throw new KasseneckValidationError('rotatePartnerWebhookSecret', 'Antwort enthaelt kein secret — dann waere der Wechsel nicht nachvollziehbar', 'response');
@@ -175,8 +181,8 @@ export async function rotatePartnerWebhookSecret(rufen, webhookId) {
     return { webhook: webhook(daten['webhook']), secret };
 }
 /** Die Webhook-Endpunkte dieses Partners samt Ereignis-Katalog. */
-export async function listPartnerWebhooks(rufen) {
-    const daten = objekt(await rufen('listPartnerWebhooks'));
+export async function listPartnerWebhooks(transport) {
+    const daten = objekt(await transport('listPartnerWebhooks'));
     return {
         webhooks: (Array.isArray(daten['webhooks']) ? daten['webhooks'] : []).map(webhook),
         events: (Array.isArray(daten['events']) ? daten['events'] : []).map((e) => ({
@@ -190,25 +196,25 @@ export async function listPartnerWebhooks(rufen) {
  * das Backend ab (`validation`, Feld `patch`), statt stillschweigend nichts zu
  * tun.
  */
-export async function updatePartnerWebhook(rufen, webhookId, patch) {
+export async function updatePartnerWebhook(transport, webhookId, patch) {
     const id = typeof webhookId === 'string' ? webhookId.trim() : '';
     if (!id)
         throw new KasseneckValidationError('updatePartnerWebhook', 'webhookId fehlt', 'request');
     if (patch === null || typeof patch !== 'object' || Object.keys(patch).length === 0) {
         throw new KasseneckValidationError('updatePartnerWebhook', 'patch nennt keine Aenderung', 'request');
     }
-    const daten = objekt(await rufen('updatePartnerWebhook', { webhookId: id, patch }));
+    const daten = objekt(await transport('updatePartnerWebhook', { webhookId: id, patch }));
     return webhook(daten['webhook']);
 }
 /**
  * Loescht einen Endpunkt. Danach kommt dort nichts mehr an; offene
  * Zustellungen werden verworfen (`dropped`).
  */
-export async function deletePartnerWebhook(rufen, webhookId) {
+export async function deletePartnerWebhook(transport, webhookId) {
     const id = typeof webhookId === 'string' ? webhookId.trim() : '';
     if (!id)
         throw new KasseneckValidationError('deletePartnerWebhook', 'webhookId fehlt', 'request');
-    const daten = objekt(await rufen('deletePartnerWebhook', { webhookId: id }));
+    const daten = objekt(await transport('deletePartnerWebhook', { webhookId: id }));
     return {
         webhookId: typeof daten['webhookId'] === 'string' ? daten['webhookId'] : id,
         deleted: daten['deleted'] === true,
@@ -234,12 +240,12 @@ export async function deletePartnerWebhook(rufen, webhookId) {
  * den Namen bei, damit ein Leser der Doku und ein Leser des Codes dasselbe
  * suchen.
  */
-export async function sendPartnerWebhookTest(rufen, webhookId, event) {
+export async function sendPartnerWebhookTest(transport, webhookId, event) {
     const id = typeof webhookId === 'string' ? webhookId.trim() : '';
     if (!id)
         throw new KasseneckValidationError('sendPartnerWebhookTest', 'webhookId fehlt', 'request');
     const ereignis = typeof event === 'string' ? event.trim() : '';
-    const daten = objekt(await rufen('sendPartnerWebhookTest', { webhookId: id, event: ereignis || undefined }));
+    const daten = objekt(await transport('sendPartnerWebhookTest', { webhookId: id, event: ereignis || undefined }));
     return {
         eventId: typeof daten['eventId'] === 'string' ? daten['eventId'] : '',
         event: typeof daten['event'] === 'string' ? daten['event'] : ereignis || 'webhook.test',
@@ -259,11 +265,11 @@ export async function sendPartnerWebhookTest(rufen, webhookId, event) {
  * fuer alle. Die Stelle, an der sich „mein Server bekommt nichts" klaeren
  * laesst, ohne bei Kasseneck nachzufragen.
  */
-export async function listPartnerWebhookDeliveries(rufen, optionen = {}) {
-    if (optionen.limit !== undefined && (!Number.isInteger(optionen.limit) || optionen.limit < 1 || optionen.limit > 200)) {
+export async function listPartnerWebhookDeliveries(transport, options = {}) {
+    if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 200)) {
         throw new KasseneckValidationError('listPartnerWebhookDeliveries', 'limit muss zwischen 1 und 200 liegen', 'request');
     }
-    const daten = objekt(await rufen('listPartnerWebhookDeliveries', { webhookId: optionen.webhookId, limit: optionen.limit }));
+    const daten = objekt(await transport('listPartnerWebhookDeliveries', { webhookId: options.webhookId, limit: options.limit }));
     return (Array.isArray(daten['deliveries']) ? daten['deliveries'] : []).map((eintrag) => {
         const z = objekt(eintrag);
         const zahl = (wert) => (typeof wert === 'number' && Number.isFinite(wert) ? wert : null);

package/dist/esm/payments/hobex.d.ts

@@ -45,8 +45,12 @@ export interface HobexTransactionIdOptions {
  *
  * **Der Endpunkt heisst `hobexPayApi`** — mit Suffix; ohne ihn gibt es ihn
  * nicht.
+ *
+ * **Nie wiederholen.** Bei `isOutcomeUnknown(e)` (Netz, Zeitlimit, HTTP 5xx,
+ * unlesbare Antwort) kann die Karte belastet sein: den Stand ueber die
+ * Transaktionskennung nachlesen, nicht ein zweites Mal belasten.
  */
-export declare function hobexPay(rufen: InternerTransport, options: HobexPayOptions): Promise<HobexReceipt>;
+export declare function hobexPay(transport: InternerTransport, options: HobexPayOptions): Promise<HobexReceipt>;
 /**
  * Erstattet eine zuvor ueber die Hobex-Cloud getaetigte Zahlung. Das Backend
  * storniert zuerst (Void, solange der Tagesabschluss aussteht) und erstattet
@@ -57,11 +61,15 @@ export declare function hobexPay(rufen: InternerTransport, options: HobexPayOpti
  * schon im Transport, sobald der Status nicht ausdruecklich Erfolg ist. Ein
  * Wahrheitswert waere hier also immer `true` — eine Luege ueber den
  * Informationsgehalt, an der ein Aufrufer ein `if` aufhaengt, das nie greift.
- * Misserfolg kommt als geworfener Fehler.
+ * Misserfolg kommt als geworfener Fehler: eine Fehlerhuelle als
+ * [KasseneckApiError] mit Code, Netz, Zeitlimit, HTTP 5xx und eine unlesbare
+ * Erfolgsantwort mit `outcome: 'unknown'` (die Erstattung kann gelaufen sein).
+ * Ein `false` an dieser Stelle luede zum zweiten Versuch ein, also zur
+ * doppelten Erstattung. **Nie wiederholen**, sondern den Stand nachlesen.
  *
  * **Der Endpunkt heisst `hobexRefundApi`** — mit Suffix.
  */
-export declare function hobexRefund(rufen: InternerTransport, options: HobexRefundOptions): Promise<void>;
+export declare function hobexRefund(transport: InternerTransport, options: HobexRefundOptions): Promise<void>;
 /**
  * Erzeugt eine neue Hobex-Transaktionskennung: 19 Ziffern aus Zeitanteil und
  * Zufall (Zwilling von `newHobexTransactionId` im Vorbild, Zeile 522).

package/dist/esm/payments/hobex.js

@@ -1,5 +1,5 @@
 import { fromHobexReceiptPayload } from '../models/index.js';
-import { KasseneckValidationError } from '../client/errors.js';
+import { KasseneckValidationError, signiertGelesen } from '../client/errors.js';
 import { toViennaWallClock } from '../vienna-time.js';
 import { centsToEuro } from '../money.js';
 /**
@@ -36,14 +36,22 @@ const ENDPUNKT_REFUND = 'hobexRefundApi';
  *
  * **Der Endpunkt heisst `hobexPayApi`** — mit Suffix; ohne ihn gibt es ihn
  * nicht.
+ *
+ * **Nie wiederholen.** Bei `isOutcomeUnknown(e)` (Netz, Zeitlimit, HTTP 5xx,
+ * unlesbare Antwort) kann die Karte belastet sein: den Stand ueber die
+ * Transaktionskennung nachlesen, nicht ein zweites Mal belasten.
  */
-export async function hobexPay(rufen, options) {
+export async function hobexPay(transport, options) {
     const params = zahlungsNutzlast(ENDPUNKT_PAY, options);
     // `reference` steht im Vorbild **unbedingt** in der Nutzlast: ohne Angabe
     // geht sie als null raus, nicht gar nicht. Der Transport wirft nur
     // `undefined` weg, `null` bleibt erhalten — genau diese Unterscheidung.
     params['reference'] = options.reference ?? null;
-    return belegAusNutzlast(await rufen(ENDPUNKT_PAY, params));
+    const daten = await transport(ENDPUNKT_PAY, params);
+    // Erfolg gemeldet heisst: die Karte ist belastet. Ist der Beleg dann
+    // unlesbar, bleibt der Ausgang unklar (`response_unreadable`), damit keine
+    // App ein zweites Mal belastet.
+    return signiertGelesen(ENDPUNKT_PAY, () => belegAusNutzlast(daten));
 }
 /**
  * Erstattet eine zuvor ueber die Hobex-Cloud getaetigte Zahlung. Das Backend
@@ -55,13 +63,17 @@ export async function hobexPay(rufen, options) {
  * schon im Transport, sobald der Status nicht ausdruecklich Erfolg ist. Ein
  * Wahrheitswert waere hier also immer `true` — eine Luege ueber den
  * Informationsgehalt, an der ein Aufrufer ein `if` aufhaengt, das nie greift.
- * Misserfolg kommt als geworfener Fehler.
+ * Misserfolg kommt als geworfener Fehler: eine Fehlerhuelle als
+ * [KasseneckApiError] mit Code, Netz, Zeitlimit, HTTP 5xx und eine unlesbare
+ * Erfolgsantwort mit `outcome: 'unknown'` (die Erstattung kann gelaufen sein).
+ * Ein `false` an dieser Stelle luede zum zweiten Versuch ein, also zur
+ * doppelten Erstattung. **Nie wiederholen**, sondern den Stand nachlesen.
  *
  * **Der Endpunkt heisst `hobexRefundApi`** — mit Suffix.
  */
-export async function hobexRefund(rufen, options) {
+export async function hobexRefund(transport, options) {
     // Anders als die Zahlung sendet der Refund im Vorbild **keine** reference.
-    await rufen(ENDPUNKT_REFUND, zahlungsNutzlast(ENDPUNKT_REFUND, options));
+    await transport(ENDPUNKT_REFUND, zahlungsNutzlast(ENDPUNKT_REFUND, options));
 }
 /**
  * Erzeugt eine neue Hobex-Transaktionskennung: 19 Ziffern aus Zeitanteil und

package/dist/esm/payments/stripe.d.ts

@@ -50,12 +50,15 @@ export interface StripeCaptureResult {
  * Methodenname und Endpunktname fallen wie schon beim Monatsbericht
  * auseinander (siehe client/reports.ts).
  */
-export declare function createStripeLink(rufen: InternerTransport, options: CreateStripeLinkOptions): Promise<StripeUrlSession>;
+export declare function createStripeLink(transport: InternerTransport, options: CreateStripeLinkOptions): Promise<StripeUrlSession>;
 /**
  * Zieht die zuvor nur reservierte Zahlung einer `authorization`-Sitzung ein.
  *
  * **Der Parameter heisst `stripe_sessions_id`** — mit "sessions" im Plural, so
  * das Vorbild und so das Backend. Der naheliegende Singular waere ein fehlender
  * Pflichtparameter.
+ *
+ * **Nie wiederholen.** Bei `isOutcomeUnknown(e)` (Netz, Zeitlimit, HTTP 5xx,
+ * unlesbare Antwort) kann der Einzug gelaufen sein: den Stand nachlesen.
  */
-export declare function stripeCaptureIntent(rufen: InternerTransport, stripeSessionId: string): Promise<StripeCaptureResult>;
+export declare function stripeCaptureIntent(transport: InternerTransport, stripeSessionId: string): Promise<StripeCaptureResult>;

package/dist/esm/payments/stripe.js

@@ -1,6 +1,6 @@
 import { StripeLinkMode } from '../enums/index.js';
 import { fromStripeUrlSessionPayload, toReceiptItemPayload, receiptItemIsValid, } from '../models/index.js';
-import { KasseneckValidationError } from '../client/errors.js';
+import { KasseneckValidationError, signiertGelesen } from '../client/errors.js';
 /**
  * Stripe-Zahlungslinks — Zwilling der Stripe-Aufrufe in
  * kasseneck_api/lib/kasseneck_api.dart (Zeilen 443-484).
@@ -25,7 +25,7 @@ const ENDPUNKT_CAPTURE = 'stripeCaptureIntent';
  * Methodenname und Endpunktname fallen wie schon beim Monatsbericht
  * auseinander (siehe client/reports.ts).
  */
-export async function createStripeLink(rufen, options) {
+export async function createStripeLink(transport, options) {
     const { items } = options;
     // Vor dem Senden pruefen: ein Zahlungslink ist zwar folgenlos wiederholbar,
     // eine abgewiesene Anfrage aber eine unnoetige Runde ueber das Netz — und der
@@ -60,7 +60,7 @@ export async function createStripeLink(rufen, options) {
     if (options.customerEmail != null) {
         params['customer_email'] = options.customerEmail;
     }
-    return sitzungAusNutzlast(await rufen(ENDPUNKT_LINK, params));
+    return sitzungAusNutzlast(await transport(ENDPUNKT_LINK, params));
 }
 /**
  * Zieht die zuvor nur reservierte Zahlung einer `authorization`-Sitzung ein.
@@ -68,13 +68,18 @@ export async function createStripeLink(rufen, options) {
  * **Der Parameter heisst `stripe_sessions_id`** — mit "sessions" im Plural, so
  * das Vorbild und so das Backend. Der naheliegende Singular waere ein fehlender
  * Pflichtparameter.
+ *
+ * **Nie wiederholen.** Bei `isOutcomeUnknown(e)` (Netz, Zeitlimit, HTTP 5xx,
+ * unlesbare Antwort) kann der Einzug gelaufen sein: den Stand nachlesen.
  */
-export async function stripeCaptureIntent(rufen, stripeSessionId) {
+export async function stripeCaptureIntent(transport, stripeSessionId) {
     if (typeof stripeSessionId !== 'string' || !stripeSessionId.trim()) {
         throw eingabefehler(ENDPUNKT_CAPTURE, 'stripeSessionId fehlt');
     }
-    const daten = await rufen(ENDPUNKT_CAPTURE, { stripe_sessions_id: stripeSessionId });
-    return einzugAusNutzlast(daten);
+    const daten = await transport(ENDPUNKT_CAPTURE, { stripe_sessions_id: stripeSessionId });
+    // Erfolg gemeldet heisst: eingezogen. Eine unlesbare Nutzlast bleibt
+    // Ausgang unklar (`response_unreadable`), nie ein gewoehnlicher Lesefehler.
+    return signiertGelesen(ENDPUNKT_CAPTURE, () => einzugAusNutzlast(daten));
 }
 /**
  * Positionen in ihre Nutzlast wandeln und dabei die strenge Schreibpfad-

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

@@ -0,0 +1,90 @@
+import type { InternerTransport } from '../client/aufrufe.js';
+/**
+ * Artikelgruppen (Kategorien der Kachel-Kasse) und Artikel in der Form, die
+ * die Kacheln brauchen, Backend: `article-endpoints.js`
+ * (`listMyArticleGroups`, `listMyArticles` mit `groupId`/`tile`).
+ */
+export interface ArticleGroup {
+    id: string;
+    name: string;
+    /** #RRGGBB */
+    color: string;
+    /** Kategorie-Symbol (Emoji, hoechstens zwei Zeichen) oder null. */
+    symbol: string | null;
+    sort: number;
+    vatRate: number | null;
+}
+export interface ArticleGroupPayload {
+    id?: string | null;
+    name?: string | null;
+    color?: string | null;
+    symbol?: string | null;
+    sort?: number | null;
+    vatRate?: number | null;
+}
+export declare function fromArticleGroupPayload(p: ArticleGroupPayload): ArticleGroup;
+/**
+ * Mengenregel eines Artikels (Draht `quantityRule`): `piece` = ganze Stueck
+ * (1, 2, 3 ...), `decimal` = Kommamenge in der Einheit (0,250 kg, 1,5 m).
+ * Beleg und DEP bleiben ganzzahlig: eine Kommamenge wird an der Kasse als EINE
+ * Position mit ausgerechnetem Betrag gebucht, die Bezeichnung traegt die Menge
+ * („Wurst 0,250 kg“). Siehe [quantityRuleForUnit] fuer die Vorgabe je Einheit.
+ */
+export declare const QUANTITY_RULES: readonly ["piece", "decimal"];
+export type QuantityRule = typeof QUANTITY_RULES[number];
+export interface QuantityDefaults {
+    rule: QuantityRule;
+    /** Kasse fragt beim Antippen nach der Menge (Wurst nach Gewicht: ja; Semmel: nein). */
+    ask: boolean;
+    /** Nachkommastellen bei `decimal`. */
+    decimals: number;
+}
+/** Vorgabe je Einheit: was der Betrieb bei einem neuen Artikel bekommt und aendern darf. */
+export declare function quantityRuleForUnit(unit: string | null | undefined): QuantityDefaults;
+/** Wirksame Regel eines Artikels: gespeicherte Angabe schlaegt die Vorgabe der Einheit. */
+export declare function quantityDefaults(a: Pick<PosArticle, 'unit' | 'quantityRule' | 'askQuantity'>): QuantityDefaults;
+/** Artikel, wie ihn die Kasse fuer Kacheln und Belegpositionen braucht. */
+export interface PosArticle {
+    id: string;
+    name: string;
+    unitPriceCents: number | null;
+    vatRate: number | null;
+    unit: string;
+    groupId: string | null;
+    /** Erloesgruppe (Buchhaltung); null = keine. */
+    revenueGroupId: string | null;
+    /** Kachel sichtbar (Draht `tile.visible`, fehlt = sichtbar). */
+    visible: boolean;
+    /** Reihenfolge der Kachel (Draht `tile.sort`). */
+    sort: number;
+    active: boolean;
+    /** Gespeicherte Mengenregel; null = Vorgabe der Einheit. */
+    quantityRule: QuantityRule | null;
+    /** Gespeichert: Kasse fragt nach der Menge; null = Vorgabe der Einheit. */
+    askQuantity: boolean | null;
+    /** Hoechstmenge je Beleg (bei kg/l/m auch Kommazahl); null = keine Grenze. */
+    maxQuantity: number | null;
+}
+/** Deckelt eine gewuenschte Menge an der Hoechstmenge des Artikels (null = keine Grenze). */
+export declare function allowedQuantity(a: Pick<PosArticle, 'maxQuantity'>, wanted: number): number;
+/** Ein Artikel am Draht `/api/v3` (`listMyArticles`), soweit dieses Paket ihn liest. */
+export interface PosArticlePayload {
+    id?: string | null;
+    name?: string | null;
+    unitPriceCents?: number | null;
+    vatRate?: number | null;
+    unit?: string | null;
+    groupId?: string | null;
+    revenueGroupId?: string | null;
+    tile?: {
+        visible?: boolean | null;
+        sort?: number | null;
+    } | null;
+    active?: boolean | null;
+    quantityRule?: string | null;
+    askQuantity?: boolean | null;
+    maxQuantity?: number | null;
+}
+export declare function fromPosArticlePayload(p: PosArticlePayload): PosArticle;
+export declare function listMyArticleGroups(transport: InternerTransport): Promise<ArticleGroup[]>;
+export declare function listMyArticles(transport: InternerTransport): Promise<PosArticle[]>;