<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Interface for dashboard statistics service.
 *
 * Provides cached statistics about video conversions for dashboard display.
 *
 * @internal
 */
interface DashboardStatsServiceInterface {

  /**
   * Gets conversion statistics with counts for different states.
   *
   * @return array{
   *   completed: int,
   *   failed: int,
   *   pending: int,
   *   converting: int,
   *   total: int,
   *   success_rate: float,
   *   }
   *   Conversion statistics array.
   */
  #[\NoDiscard]
  public function getConversionStats(): array;

  /**
   * Gets recent conversions for dashboard display.
   *
   * @param int $limit
   *   Maximum number of conversions to return.
   *
   * @return array<array{
   *   media_id: int,
   *   media_name: string,
   *   media_url: string|null,
   *   status: string,
   *   started_at: int|null,
   *   completed_at: int|null,
   *   duration: string,
   *   error_message: string|null,
   *   }>
   *   Array of recent conversion data.
   */
  #[\NoDiscard]
  public function getRecentConversions(int $limit = 20): array;

  /**
   * Gets the average conversion time in seconds.
   *
   * Calculates the average time from started to completed for successful
   * conversions over the last 24 hours.
   *
   * @return float|null
   *   Average conversion time in seconds, or NULL if no data available.
   */
  #[\NoDiscard]
  public function getAverageConversionTime(): ?float;

  /**
   * Gets the success rate for conversions.
   *
   * Calculates the percentage of successful conversions out of all completed
   * conversions (completed + failed) over the last 24 hours.
   *
   * @return float
   *   Success rate as a percentage (0-100).
   */
  #[\NoDiscard]
  public function getSuccessRate(): float;

  /**
   * Gets recent failed conversions with error messages.
   *
   * @param int $limit
   *   Maximum number of failures to return.
   *
   * @return array<array{
   *   media_id: int,
   *   media_name: string,
   *   media_url: string|null,
   *   error_message: string,
   *   failed_at: int,
   *   failed_at_formatted: string,
   *   }>
   *   Array of recent failure data.
   */
  #[\NoDiscard]
  public function getRecentFailures(int $limit = 10): array;

  /**
   * Gets 24-hour conversion statistics.
   *
   * @return array{
   *   completed: int,
   *   failed: int,
   *   total: int,
   *   success_rate: float,
   *   average_time: float|null,
   *   }
   *   Statistics for the last 24 hours.
   */
  #[\NoDiscard]
  public function get24HourStats(): array;

  /**
   * Clears the dashboard statistics cache.
   */
  public function clearCache(): void;

}
