ANTOOZA-BACKEND/Application/Abstractions/YouTube/IYouTubePubSubService.cs

namespace Application.Abstractions.YouTube;

/// <summary>
/// YouTube PubSubHubbub(WebSub) 구독 관리
/// 채널의 새 영상/생방송 알림을 푸시로 수신
/// </summary>
public interface IYouTubePubSubService
{
    /// <summary>특정 채널의 피드 구독 신청</summary>
    Task<bool> SubscribeAsync(string channelId, CancellationToken ct);

    /// <summary>특정 채널의 피드 구독 해지</summary>
    Task<bool> UnsubscribeAsync(string channelId, CancellationToken ct);

    /// <summary>Atom Feed 알림 파싱</summary>
    YouTubePubSubNotification? ParseNotification(string atomXml);

    /// <summary>HMAC 서명 검증</summary>
    bool VerifySignature(string payload, string signature);

    /// <summary>현재 구독 중인 YouTube 채널 ID 목록 조회</summary>
    Task<IReadOnlyList<string>> GetSubscribedChannelIdsAsync(CancellationToken ct);

    /// <summary>
    /// PubSub 알림 중복 처리 방지용 마커.
    /// 처음 호출 시 true, 이미 처리된 videoId면 false 반환.
    /// </summary>
    Task<bool> TryMarkProcessedAsync(string videoId, CancellationToken ct);

    /// <summary>
    /// 채널의 마지막으로 처리된 videoId 조회 (Feed 폴링 중복 감지용).
    /// </summary>
    Task<string?> GetLastProcessedVideoIdAsync(string youtubeChannelID, CancellationToken ct);

    /// <summary>
    /// 채널의 마지막 처리 videoId 저장 (PubSub/Feed 어느 경로든 처리 후 호출).
    /// </summary>
    Task SetLastProcessedVideoIdAsync(string youtubeChannelID, string videoId, CancellationToken ct);

    /// <summary>
    /// 채널별 마지막 Feed 폴링 시각 저장 (신규 비디오 감지 여부와 무관, 매 폴링 시 호출).
    /// </summary>
    Task SetLastPolledAtAsync(string youtubeChannelID, DateTime utcNow, CancellationToken ct);

    /// <summary>
    /// 모든 채널의 마지막 Feed 폴링 시각 일괄 조회 (관리자 대시보드용).
    /// </summary>
    Task<IReadOnlyDictionary<string, DateTime>> GetAllLastPolledAtAsync(CancellationToken ct);

    /// <summary>
    /// 모든 채널의 마지막 처리 videoId 일괄 조회 (관리자 대시보드용).
    /// </summary>
    Task<IReadOnlyDictionary<string, string>> GetAllLastProcessedVideoIdsAsync(CancellationToken ct);

    /// <summary>
    /// 채널의 PubSub lease 만료 예정 시각 저장 (구독 verify 시 lease_seconds 기반).
    /// </summary>
    Task SetLeaseExpiryAsync(string youtubeChannelID, DateTime expiresAtUtc, CancellationToken ct);

    /// <summary>
    /// 모든 채널의 PubSub lease 만료 예정 시각 일괄 조회 (관리자 대시보드용).
    /// </summary>
    Task<IReadOnlyDictionary<string, DateTime>> GetAllLeaseExpiriesAsync(CancellationToken ct);
}