<?php
/**
 * Click event repository contract.
 *
 * @package Affilun\Infrastructure\Persistence
 */

declare(strict_types=1);

namespace Affilun\Infrastructure\Persistence;

use DateTimeImmutable;

/**
 * Persistence port for public click tracking events and rollups.
 */
interface ClickEventRepository {

	/**
	 * Record a sanitized click event.
	 *
	 * @param array<string,mixed> $event Sanitized event payload.
	 */
	public function record( array $event ): void;

	/**
	 * Return recent click events for dashboard/export surfaces.
	 *
	 * @param int $limit Maximum rows.
	 *
	 * @return list<array<string,mixed>>
	 */
	public function recentEvents( int $limit = 500 ): array;

	/**
	 * Count recent click events for a coarse client bucket.
	 *
	 * @param string            $userAgentHash User-agent hash.
	 * @param string            $refererHost   Referer host.
	 * @param DateTimeImmutable $since         Lower bound, inclusive.
	 */
	public function countRecentMatching( string $userAgentHash, string $refererHost, DateTimeImmutable $since ): int;

	/**
	 * Delete click events and rollups strictly older than the supplied cutoff.
	 *
	 * @param DateTimeImmutable $cutoff Cutoff instant.
	 */
	public function deleteOlderThan( DateTimeImmutable $cutoff ): int;
}