<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\media\MediaInterface;

/**
 * Inspects and manages converted outputs for a media entity.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface MediaConversionInspectorInterface {

  /**
   * Checks whether a media entity can be reconverted.
   *
   * @param \Drupal\media\MediaInterface $media
   *   The media entity.
   * @param string $fieldName
   *   Optional source field name. Empty string uses the preferred context.
   *
   * @return array{
   *   can_reconvert: bool,
   *   reason?: string|null,
   *   existing_outputs: array<string, string>
   *   }
   *   Reconvert state and known output paths.
   */
  #[\NoDiscard]
  public function canReconvert(MediaInterface $media, string $fieldName = ''): array;

  /**
   * Deletes converted outputs for a media entity.
   *
   * @param \Drupal\media\MediaInterface $media
   *   The media entity.
   * @param string $fieldName
   *   Optional source field name. Empty string uses the preferred context.
   *
   * @return array<int, string>
   *   Deleted URIs.
   */
  public function deleteConvertedFiles(MediaInterface $media, string $fieldName = ''): array;

  /**
   * Returns the current conversion status for a media entity.
   *
   * @param \Drupal\media\MediaInterface $media
   *   The media entity.
   * @param string $fieldName
   *   Optional source field name. Empty string uses the preferred context.
   *
   * @return array{
   *   has_source: bool,
   *   is_queued: bool,
   *   is_converting: bool,
   *   is_converted: bool,
   *   outputs: array<string, string>,
   *   error: string|null
   *   }
   *   Status payload.
   */
  #[\NoDiscard]
  public function getStatus(MediaInterface $media, string $fieldName = ''): array;

  /**
   * Checks whether a media entity is eligible for conversion.
   *
   * @param \Drupal\media\MediaInterface $media
   *   The media entity to check.
   * @param string $fieldName
   *   Optional source field name. Empty string uses the preferred context.
   */
  #[\NoDiscard]
  public function isEligibleForConversion(MediaInterface $media, string $fieldName = ''): bool;

}
