<?php

declare(strict_types=1);

namespace App\Framework\Waf\Feedback;

use App\Framework\Core\ValueObjects\Timestamp;
use App\Framework\Waf\DetectionCategory;

/**
 * Repository interface for storing and retrieving WAF feedback
 */
interface FeedbackRepositoryInterface
{
    /**
     * Saves feedback for a WAF detection
     */
    public function saveFeedback(DetectionFeedback $feedback): void;

    /**
     * Retrieves feedback for a specific detection
     *
     * @return DetectionFeedback[]
     */
    public function getFeedbackForDetection(string $detectionId): array;

    /**
     * Retrieves all feedback entries for a specific category
     *
     * @param DetectionCategory $category The category to filter by
     * @param Timestamp|null $since Optional timestamp to filter feedback after a certain date
     * @return DetectionFeedback[]
     */
    public function getFeedbackByCategory(DetectionCategory $category, ?Timestamp $since = null): array;

    /**
     * Retrieves feedback entries by feedback type
     *
     * @param FeedbackType $feedbackType The feedback type to filter by
     * @param Timestamp|null $since Optional timestamp to filter feedback after a certain date
     * @return DetectionFeedback[]
     */
    public function getFeedbackByFeedbackType(FeedbackType $feedbackType, ?Timestamp $since = null): array;

    /**
     * Gets feedback statistics
     *
     * @return array<string, mixed> Statistics about the feedback
     */
    public function getFeedbackStats(): array;

    /**
     * Gets the most recent feedback entries
     *
     * @param int $limit Maximum number of entries to return
     * @return DetectionFeedback[]
     */
    public function getRecentFeedback(int $limit = 10): array;
}
