<?php
declare(strict_types=1);

namespace Payments;

/**
 * Vertrag fuer Zahlungsanbieter mit Weiterleitung (PayPal v2, spaeter Amazon Pay,
 * Mollie, Klarna Payments ...).
 *
 * Lebenszyklus einer Zahlung:
 *   1. Cashdesk legt die Shop-Bestellung an (Zahlstatus offen).
 *   2. start()      -> Zahlung beim Anbieter anlegen, Kunde per 302 weiterleiten.
 *   3. onReturn()   -> Kunde kommt zurueck: Zahlung abschliessen, Bestellung bezahlt setzen.
 *      onCancel()   -> Kunde hat abgebrochen: Bestellung stornieren, Warenkorb bleibt.
 *   4. onWebhook()  -> Anbieter meldet serverseitig (unabhaengig vom Kunden).
 *   5. reconcile()  -> Cron: haengende Vorgaenge beim Anbieter nachfragen.
 *
 * Alles, was fuer alle Anbieter gleich ist (Mail erst nach Zahlung, Warenkorb erst
 * nach Zahlung, Ereignisprotokoll, Betragsabgleich), lebt in AbstractProvider.
 */
interface ProviderInterface
{
    /** Technischer Name = payment_methods.module = Konfigurationsgruppe, z.B. 'paypal_v2'. */
    public function module(): string;

    /** Anzeigename fuers Backend und Protokoll. */
    public function label(): string;

    /** true: die Bestellung ist erst nach Rueckkehr vom Anbieter bezahlt (Mail/Warenkorb warten). */
    public function paysAfterRedirect(): bool;

    /**
     * Zahlung anlegen und Weiterleitungs-URL liefern.
     *
     * @param  int   $orderId   Shop-Bestellung (orders.id)
     * @param  float $amount    zu zahlender Bruttobetrag (nach Gutschein)
     * @return string           URL, zu der der Kunde geschickt wird
     * @throws \RuntimeException wenn der Anbieter nicht erreichbar ist oder ablehnt
     */
    public function start(int $orderId, float $amount): string;

    /**
     * Rueckkehr des Kunden vom Anbieter.
     * @param  array<string,mixed> $query  $_GET der Rueckkehr-URL
     */
    public function onReturn(array $query): Result;

    /** @param array<string,mixed> $query */
    public function onCancel(array $query): Result;

    /**
     * Server-zu-Server-Nachricht des Anbieters.
     * @param  array<string,string> $headers  Request-Header, Schluessel kleingeschrieben
     * @return int HTTP-Status, den der Endpunkt zurueckgeben soll (2xx = angenommen)
     */
    public function onWebhook(array $headers, string $rawBody): int;

    /**
     * Haengende Vorgaenge nachziehen (Cron). Liefert eine kurze Zusammenfassung je Vorgang.
     * @return list<string>
     */
    public function reconcile(bool $dryRun = true): array;

    // ------------------------------------------------------------ Express
    // "Direkt bezahlen" aus dem Warenkorb: der Kunde geht OHNE Adresse zum Anbieter,
    // der liefert Adresse + E-Mail, die Kasse ist damit vorbelegt, ein Klick auf
    // "zahlungspflichtig bestellen" zieht das Geld ein -- kein zweiter Besuch beim Anbieter.

    /** Bietet der Anbieter den Express-Weg an (und ist er eingeschaltet)? */
    public function supportsExpress(): bool;

    /**
     * Express-Vorgang fuer den aktuellen Warenkorb anlegen (noch keine Bestellung!).
     * @param  float $amount  Warenwert brutto ohne Versand (Land noch unbekannt)
     * @return string         URL zum Anbieter
     */
    public function startExpress(float $amount): string;

    /**
     * Rueckkehr vom Anbieter im Express-Weg: Adresse und E-Mail des Kunden abholen.
     * @param  array<string,mixed> $query  $_GET der Rueckkehr-URL
     * @return array<string,mixed>|null    Kundendaten fuer die Kasse (Schluessel: reference,
     *         email, firstname, surname, company, street, house_number, zip_code, city,
     *         country_iso, approve_url) oder null, wenn der Vorgang nicht zugeordnet werden kann
     */
    public function onExpressReturn(array $query): ?array;

    /**
     * Express abschliessen, nachdem die Bestellung angelegt ist: Betrag beim Anbieter auf
     * den Endbetrag (inkl. Versand) setzen und einziehen.
     * @return string  '' = bezahlt; sonst eine URL, zu der der Kunde noch einmal muss
     *                 (Anbieter verlangt erneute Freigabe, z.B. nach Betragsaenderung)
     */
    public function finishExpress(int $orderId, float $amount, string $reference): string;

    /**
     * Felder fuer den Zahlart-Editor im Backend, die NICHT in `configuration` liegen,
     * sondern verschluesselt (Secrets). name => Beschriftung.
     * @return array<string,string>
     */
    public function secretFields(): array;
}