<?php
/**
 * Contract for PayPal webhook signature verification.
 *
 * @since   1.0.0
 * @package DonationRouter
 */

declare( strict_types=1 );
namespace DonationRouter;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Verifies a PayPal webhook event signature against the PayPal API.
 *
 * Implementations MUST cache verification results to avoid rate-limiting.
 * The canonical implementation uses PayPal's verify-webhook-signature REST
 * endpoint; a test double may short-circuit the HTTP call.
 *
 * @since 1.0.0
 */
interface Webhook_Signature_Verifier_Interface {

	/**
	 * Verify that a webhook event was genuinely sent by PayPal.
	 *
	 * @since 1.0.0
	 *
	 * @param object              $event        Decoded JSON event object.
	 * @param array<string,mixed> $headers      Normalised HTTP headers (lowercase keys).
	 * @param string              $webhook_id   PayPal webhook ID registered for this account.
	 * @param string              $access_token Bearer token for the account.
	 * @param string              $mode         Account environment ('live' or 'sandbox').
	 *
	 * @return bool True when PayPal confirms the signature is valid.
	 */
	public function verify( object $event, array $headers, string $webhook_id, string $access_token, string $mode = 'live' ): bool;
}
