<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Interface for dead-letter storage of permanently failed conversion jobs.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface DeadLetterStorageInterface {

  /**
   * Stores a permanently failed job in the dead-letter table.
   *
   * Uses upsert semantics keyed on media_id so repeated failures
   * for the same media entity update the existing record.
   *
   * @param int $mediaId
   *   The media entity ID.
   * @param string $errorMessage
   *   The final error message.
   * @param int $retryCount
   *   Number of retry attempts that were made.
   * @param string|null $profileId
   *   Optional conversion profile ID.
   * @param string|null $lastErrorCode
   *   Optional error code for categorisation.
   * @param string $fieldName
   *   Optional source field name for field-scoped storage.
   */
  public function store(int $mediaId, string $errorMessage, int $retryCount, ?string $profileId = NULL, ?string $lastErrorCode = NULL, string $fieldName = ''): void;

  /**
   * Returns dead-letter entries ordered by most recent failure first.
   *
   * @param int $limit
   *   Maximum number of entries to return.
   * @param int $offset
   *   Number of entries to skip.
   *
   * @phpstan-return array<int, array{id: int, media_id: int, field_name: string, error_message: string, retry_count: int, failed_at: int, profile_id: string|null, last_error_code: string|null}>
   */
  #[\NoDiscard]
  public function getAll(int $limit = 50, int $offset = 0): array;

  /**
   * Gets the dead-letter entry for a specific media entity.
   *
   * @param int $mediaId
   *   The media entity ID.
   * @param string $fieldName
   *   Optional source field name. Empty string returns the latest row for
   *   the media entity across all fields.
   *
   * @phpstan-return array{id: int, media_id: int, field_name: string, error_message: string, retry_count: int, failed_at: int, profile_id: string|null, last_error_code: string|null}|null
   */
  #[\NoDiscard]
  public function getByMediaId(int $mediaId, string $fieldName = ''): ?array;

  /**
   * Removes the dead-letter entry for a specific media entity.
   *
   * @param int $mediaId
   *   The media entity ID.
   * @param string $fieldName
   *   Optional source field name. Empty string removes all rows for media.
   */
  public function remove(int $mediaId, string $fieldName = ''): void;

  /**
   * Purges entries older than the specified number of days.
   *
   * @param int $olderThanDays
   *   Remove entries whose failed_at timestamp is older than this many days.
   *
   * @return int
   *   Number of entries purged.
   */
  public function purge(int $olderThanDays = 30): int;

  /**
   * Returns the total number of dead-letter entries.
   *
   * @return int
   *   The count of dead-letter entries.
   */
  #[\NoDiscard]
  public function count(): int;

}
