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

namespace Application.Abstractions.YouTube;

/// <summary>
/// YouTube Data API v3 — 채널 정보, 구독/멤버십 확인
/// </summary>
public interface IYouTubeApiService
{
    // ── 공개 정보 (API Key 사용) ──────────────────────────────────────

    /// <summary>채널 ID로 채널 정보 조회</summary>
    Task<YouTubeChannelInfo?> GetChannelByIdAsync(string channelId, CancellationToken ct);

    /// <summary>여러 채널 ID를 한 번에 조회 (최대 50개, 1 unit)</summary>
    Task<IReadOnlyList<YouTubeChannelInfo>> GetChannelsByIdsAsync(IReadOnlyList<string> channelIds, CancellationToken ct);

    /// <summary>핸들(@username)로 채널 정보 조회</summary>
    Task<YouTubeChannelInfo?> GetChannelByHandleAsync(string handle, CancellationToken ct);

    /// <summary>videoId로 라이브 스트림 정보 조회 (liveBroadcastContent, activeLiveChatId, concurrentViewers)</summary>
    Task<YouTubeLiveStreamInfo?> GetLiveStreamInfoAsync(string videoId, CancellationToken ct);

    /// <summary>
    /// 여러 videoId의 실시간 시청자 수를 한 번에 조회 (videos.list batch, 50개당 1 unit).
    /// 라이브 아니거나 concurrentViewers 필드 없으면 해당 videoId는 결과에서 제외.
    /// </summary>
    Task<IReadOnlyDictionary<string, int>> GetConcurrentViewersAsync(IReadOnlyList<string> videoIds, CancellationToken ct);

    /// <summary>
    /// 채널의 uploads 플레이리스트에서 최근 업로드 videoId 목록 조회 (최대 50개, 1 unit).
    /// channelId는 YouTube channel ID (UC...).
    /// </summary>
    Task<IReadOnlyList<string>> GetRecentUploadsAsync(string channelId, int maxResults, CancellationToken ct);

    /// <summary>
    /// 여러 videoId를 한 번에 조회 — liveStreamingDetails + statistics (최대 50개, 3 units).
    /// 일일 배치 집계 전용.
    /// </summary>
    Task<IReadOnlyList<YouTubeVideoStats>> GetVideoStatsBatchAsync(IReadOnlyList<string> videoIds, CancellationToken ct);

    // ── 사용자별 (OAuth Access Token 필요) ────────────────────────────

    /// <summary>현재 사용자가 특정 채널을 구독 중인지 확인</summary>
    Task<bool> IsSubscribedAsync(string accessToken, string channelId, CancellationToken ct);

    /// <summary>현재 사용자의 특정 채널 멤버십 상태 확인</summary>
    Task<YouTubeMembershipStatus> CheckMembershipAsync(string accessToken, string channelId, CancellationToken ct);

    /// <summary>OAuth Access Token으로 인증된 사용자 본인의 채널 조회 (mine=true)</summary>
    Task<YouTubeChannelInfo?> GetMyChannelAsync(string accessToken, CancellationToken ct);
}