mivita/app/Services/Payment/Stripe/DTOs/StripeWebhookResult.php

<?php

namespace App\Services\Payment\Stripe\DTOs;

/**
 * Ergebnis der Stripe-Webhook-Verarbeitung. Anders als beim PAYONE-IPN
 * (immer "TSOK") steuert der HTTP-Status das Retry-Verhalten von Stripe:
 * 2xx = erledigt, alles andere wird erneut zugestellt.
 */
class StripeWebhookResult
{
    private function __construct(
        public readonly int $statusCode,
        public readonly string $state,
        public readonly ?string $eventId = null,
        public readonly ?string $eventType = null,
        public readonly ?string $reason = null,
    ) {}

    /** Signatur ungültig oder Payload kein gültiges Event — kein Retry sinnvoll. */
    public static function invalidSignature(string $reason): self
    {
        return new self(statusCode: 400, state: 'invalid_signature', reason: $reason);
    }

    /** STRIPE_WEBHOOK_SECRET fehlt — 500, damit Stripe später erneut zustellt. */
    public static function notConfigured(): self
    {
        return new self(statusCode: 500, state: 'not_configured', reason: 'STRIPE_WEBHOOK_SECRET missing');
    }

    /** Event-ID bereits verarbeitet — Retry wird bestätigt, aber ignoriert. */
    public static function duplicate(string $eventId, string $eventType): self
    {
        return new self(statusCode: 200, state: 'duplicate', eventId: $eventId, eventType: $eventType);
    }

    /** Gültiges Event eines nicht behandelten Typs — protokolliert, bestätigt. */
    public static function ignored(string $eventId, string $eventType): self
    {
        return new self(statusCode: 200, state: 'ignored', eventId: $eventId, eventType: $eventType);
    }

    /** Event verarbeitet (Transaktion protokolliert, Folgeaktionen angestoßen). */
    public static function processed(string $eventId, string $eventType): self
    {
        return new self(statusCode: 200, state: 'processed', eventId: $eventId, eventType: $eventType);
    }

    /**
     * Event trägt unsere Metadata (shopping_payment_id), aber die Zahlung ist
     * (noch) nicht auffindbar — z. B. weil die Cron-DB-Transaktion noch nicht
     * committet war (Plan S4, Race Cron vs. Webhook). Non-2xx → Stripe stellt
     * erneut zu; das gespeicherte Event bleibt unverarbeitet und wird beim
     * Retry regulär verarbeitet.
     */
    public static function paymentNotYetVisible(string $eventId, string $eventType): self
    {
        return new self(
            statusCode: 503,
            state: 'payment_not_yet_visible',
            eventId: $eventId,
            eventType: $eventType,
            reason: 'shopping_payment aus metadata (noch) nicht auffindbar — Retry angefordert',
        );
    }
}