<?php

declare(strict_types=1);

namespace App\Framework\ErrorAggregation\Storage;

use App\Framework\ErrorAggregation\ErrorEvent;
use App\Framework\ErrorAggregation\ErrorPattern;
use App\Framework\Exception\Core\ErrorSeverity;

/**
 * Interface for error storage backends
 */
interface ErrorStorageInterface
{
    /**
     * Stores a single error event
     */
    public function storeEvent(ErrorEvent $event): void;

    /**
     * Stores multiple error events in batch
     */
    public function storeEventsBatch(array $events): void;

    /**
     * Stores or updates an error pattern
     */
    public function storePattern(ErrorPattern $pattern): void;

    /**
     * Gets error pattern by ID
     */
    public function getPatternById(string $patternId): ?ErrorPattern;

    /**
     * Gets error pattern by fingerprint
     */
    public function getPatternByFingerprint(string $fingerprint): ?ErrorPattern;

    /**
     * Gets active error patterns
     */
    public function getActivePatterns(int $limit = 50, int $offset = 0): array;

    /**
     * Gets error patterns by service
     */
    public function getPatternsByService(string $service, int $limit = 50): array;

    /**
     * Gets recent error events
     */
    public function getRecentEvents(int $limit = 100, ?ErrorSeverity $severity = null): array;

    /**
     * Gets error statistics for a time period
     */
    public function getStatistics(\DateTimeImmutable $from, \DateTimeImmutable $to): array;

    /**
     * Gets error trends grouped by time period
     */
    public function getErrorTrends(
        \DateTimeImmutable $from,
        \DateTimeImmutable $to,
        string $groupBy = 'hour'
    ): array;

    /**
     * Gets top error patterns by occurrence count
     */
    public function getTopPatterns(int $limit = 10, ?string $service = null): array;

    /**
     * Deletes old events based on cutoff date and severity
     */
    public function deleteOldEvents(\DateTimeImmutable $cutoffDate, ErrorSeverity $severity): int;

    /**
     * Deletes old inactive patterns
     */
    public function deleteOldPatterns(\DateTimeImmutable $cutoffDate): int;

    /**
     * Exports events for external analysis
     */
    public function exportEvents(
        \DateTimeImmutable $from,
        \DateTimeImmutable $to,
        array $filters = []
    ): \Generator;

    /**
     * Gets health status of storage backend
     */
    public function getHealthStatus(): array;
}
