Shop-Vertrag

storefront-contract v3: Das Backend des Shops ist das Paket @delieta/shop-runtime, zwei dünne Shims, ein veröffentlichbarer Schlüssel auf der Serverseite, signierte Aktualisierung.

Der Shop-Vertrag (storefront-contract@v3) beschreibt einen Shop auf Delieta. Das Backend des Shops ist das npm-Paket @delieta/shop-runtime (Version 1.6.0), nicht Dateien im Repository des Shops. Das Shop-Repository hält das Aussehen und zwei dünne Shims. Der Rest (Partner-API-Zugriff, Warenkorb, Kasse, Aktualisierung) kommt aus dem Paket, sodass eine Runtime-Korrektur mit einem Release alle Shops erreicht.

Vier Env-Werte

DELIETA_API_URL=https://delieta.pl
DELIETA_PUBLISHABLE_KEY=dlt_live_…
DELIETA_REVALIDATE_SECRET=…
DELIETA_DATA_MODE=live

DELIETA_API_URL ist der Origin allein: kein /api/v1, kein abschließender Schrägstrich. DELIETA_PUBLISHABLE_KEY ist der Schlüssel catalog:read + checkout:create. DELIETA_REVALIDATE_SECRET signiert das Aktualisierungssignal und prüft Vorschau-Links bei einem Shop mit Beispieldaten. DELIETA_DATA_MODE ist optional: sample oder live, nicht gesetzt heißt live, und der Build lehnt jeden anderen Wert ab. Keiner trägt das Präfix NEXT_PUBLIC_.

Kein Env → eine Seite „Shop konfigurieren“, keine leere Seite, die einen Shop vortäuscht. Env ist gesetzt, aber Delieta antwortet nicht → eine Seite „Produkte nicht verfügbar“, kein Menü mit null Artikeln, das wie ein Deployment aussieht.

Veröffentlichbarer Schlüssel: nur serverseitig

Der veröffentlichbare Schlüssel ist genau catalog:read + checkout:create. Er kann einen Warenkorb anlegen, also darf er nicht in den Browser gelangen. Die Runtime hält ihn serverseitig und sendet ihn selbst. Nach dem Build bricht delieta-shop-assert ab, wenn der Schlüssel in Client-JS-Code gelangt ist. Ein geheimer Schlüssel (orders:write, eta:quote, reservations:write, catering:write) gehört weder in den Shop noch in sein Repository. dlt_test_… ist ebenfalls kein sicheres Geheimnis in HTML.

Der Schlüssel bezeichnet die Firma. Senden Sie keine companyId.

Drei Bereiche

Bereich	Woher	Hinweise
Produkte und Marke	`GET /api/v1/menu` und `GET /api/v1/shop-config` mit dem veröffentlichbaren Schlüssel, ungecacht gelesen.	Grosze, PLN. Nicht verfügbare Artikel weggelassen. Marke, Öffnungszeiten, Module und Bestellregeln kommen aus dem Panel.
Warenkorb	`{ itemId, quantity, options? }[]`. Die Summe auf dem Bildschirm kommt aus der Produktliste.	Optionen wählt man über `options: [{ group, option }]`. Der Client sendet was, nie wie viel.
Kasse	`POST /api/v1/checkout` über den Shim `/api/delieta/checkout`, das Ergebnis aus `GET /api/v1/checkout/result`.	Delieta bepreist aus dem Katalog; zurück kommt eine Zahlungsadresse oder bei Barzahlung eine `trackingUrl`.

flowchart TD
  env["Env: origin, klucz publikowalny, sekret odswiezania"] --> rt["@delieta/shop-runtime"]
  rt --> menu["GET /menu i /shop-config bez cache"]
  menu --> cart["Koszyk: itemId, ilosc, opcje"]
  cart --> pipe["/api/delieta/checkout"]
  pipe --> checkout["POST /checkout, ceny liczy Delieta"]
  checkout --> result["GET /checkout/result i status"]
  secret["Klucz sekretny"] -.->|"nigdy w sklepie"| rt
  push["Delieta: podpisany POST /api/revalidate"] --> rt

Der Schlüssel ist nur in dem Sinn „veröffentlichbar“, dass er Bestellungen, Fahrer und Kunden nicht lesen kann. Trotzdem bleibt er auf dem Server.

Zwei Shims im Shop-Repository

Ein Shop hat genau zwei Dateien von uns. Jede ist ein einzelner export; Sie bearbeiten sie nicht, und delieta-shop-assert schlägt fehl, wenn jemand es tut.

// app/api/delieta/[...path]/route.ts
export { GET, POST } from "@delieta/shop-runtime/proxy";

// app/api/revalidate/route.ts
export { POST } from "@delieta/shop-runtime/revalidate";

Das erste ist der Proxy /api/delieta/… mit einer Erlaubnisliste von Pfaden: GET Raumplan, Reservierungsverfügbarkeit, Kassen-Zeitfenster und Bestellstatus per Kurzcode, POST Kasse, Reservierungen und Anfragen. Alles andere wird abgelehnt. Der Browser des Gastes ruft den Proxy auf, und dieser ergänzt den Schlüssel serverseitig. Das zweite empfängt die signierte Aktualisierung.

Aktualisierung, Heartbeat und Guard

Die Runtime liest Delieta ungecacht. Ändert der Inhaber Menü, Einstellungen oder Raumplan, sendet Delieta einen signierten POST /api/revalidate, und der Shop lässt seine Tags verfallen (menu, shop-config, floor-plan). Nach next build prüft delieta-shop-assert drei Dinge: Die Shims sind unberührt, die App ist kein statischer Export, der veröffentlichbare Schlüssel ist nicht in Client-Code gelangt. Außerdem sendet er den Heartbeat mit der Runtime-Version. Eine App, die ein statischer Export ist, hat keinen Server und erfüllt Vertrag v3 daher nicht.

Geld und Fehler

Beträge sind in ganzen Grosze; formatieren Sie sie erst bei der Anzeige. Partner-API-Fehler sind application/problem+json; erkennen Sie sie an code, zum Beispiel unauthorized, scope_required, rate_limited, shop_closed, slot_unavailable. Die vollständige Liste der Codes und alle Operationen, die ein Shop nutzt, stehen in der Partner-API.