<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\media\MediaInterface;

/**
 * Coordinates deletion of local and remote conversion artifacts.
 *
 * @internal
 */
interface MediaArtifactManagerInterface {

  /**
   * Deletes tracked conversion artifacts for a media entity.
   *
   * @param \Drupal\media\MediaInterface $media
   *   Media entity whose artifacts should be removed.
   * @param bool $deleteLocalFiles
   *   TRUE to delete local file entities and streaming directories.
   * @param bool $deleteRemoteFiles
   *   TRUE to delete remote CDN objects.
   * @param bool $deleteProgress
   *   TRUE to delete progress state.
   * @param bool $deleteQueueState
   *   TRUE to remove queue, retry and dead-letter state.
   * @param string $fieldName
   *   Optional source field name. Empty string deletes artifacts for all
   *   configured fields on the media entity.
   *
   * @return array<int, string>
   *   Unique local artifact URIs that were detached from output storage.
   */
  #[\NoDiscard]
  public function deleteArtifacts(
    MediaInterface $media,
    bool $deleteLocalFiles = TRUE,
    bool $deleteRemoteFiles = TRUE,
    bool $deleteProgress = TRUE,
    bool $deleteQueueState = TRUE,
    string $fieldName = '',
  ): array;

}
