<?php
/**
 * @package Hafenstudios\Kurato
 */

namespace Hafenstudios\Kurato\Mail;

defined( 'ABSPATH' ) || exit;

/**
 * Normalisiert den herstellerspezifischen Webhook-Payload eines ESP zu einem
 * einheitlichen Kurato-Ereignis (K4-Konzept Abschnitt 9).
 *
 * v1 liefert nur den Brevo-Normalizer; SES/Postmark docken in 1.1 hinter genau
 * dieser Schnittstelle an, ohne den `BrevoWebhookController`/`SuppressionService`
 * zu aendern.
 */
interface WebhookNormalizer {

	/**
	 * Normalisiert einen Roh-Payload.
	 *
	 * @param array<string, mixed> $payload Roher, dekodierter JSON-Payload.
	 * @return array{type:string,email:string,reason:string}|null Normalisiertes
	 *         Ereignis oder null, wenn der Typ unbekannt/irrelevant ist oder die
	 *         E-Mail fehlt (der Aufrufer quittiert dann mit 200, damit der ESP
	 *         nicht wiederholt).
	 */
	public function normalize( array $payload ): ?array;
}
