namespace MktXService.Infrastructure.ExternalServices.Twitter;

/// <summary>
/// EN: Interface for Twitter API v2 client operations.
/// VI: Interface cho các thao tác client Twitter API v2.
/// </summary>
/// <remarks>
/// EN: Implements Direct Message and Account Activity API operations.
/// VI: Triển khai các thao tác Direct Message và Account Activity API.
/// </remarks>
public interface ITwitterApiClient
{
    #region Direct Messages

    /// <summary>
    /// EN: Send a direct message to a user.
    /// VI: Gửi tin nhắn trực tiếp đến người dùng.
    /// </summary>
    Task<TwitterMessageResult> SendDirectMessageAsync(
        string recipientId, 
        string text, 
        CancellationToken cancellationToken = default);

    /// <summary>
    /// EN: Send a direct message with media attachment.
    /// VI: Gửi tin nhắn trực tiếp với tệp đính kèm.
    /// </summary>
    Task<TwitterMessageResult> SendDirectMessageWithMediaAsync(
        string recipientId, 
        string text, 
        string mediaId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// EN: Get conversation history with a participant.
    /// VI: Lấy lịch sử hội thoại với một người tham gia.
    /// </summary>
    Task<IEnumerable<TwitterDirectMessage>> GetConversationAsync(
        string participantId,
        int maxResults = 50,
        string? paginationToken = null,
        CancellationToken cancellationToken = default);

    #endregion

    #region User Operations

    /// <summary>
    /// EN: Get user information by user ID.
    /// VI: Lấy thông tin người dùng theo user ID.
    /// </summary>
    Task<TwitterUser?> GetUserByIdAsync(
        string userId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// EN: Get user information by username.
    /// VI: Lấy thông tin người dùng theo username.
    /// </summary>
    Task<TwitterUser?> GetUserByUsernameAsync(
        string username,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// EN: Verify OAuth credentials and get authenticated user.
    /// VI: Xác thực OAuth credentials và lấy thông tin người dùng đã xác thực.
    /// </summary>
    Task<TwitterUser?> VerifyCredentialsAsync(CancellationToken cancellationToken = default);

    #endregion

    #region Webhooks (Account Activity API)

    /// <summary>
    /// EN: Register a webhook URL for receiving events.
    /// VI: Đăng ký webhook URL để nhận events.
    /// </summary>
    Task<string> RegisterWebhookAsync(
        string webhookUrl,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// EN: Delete a registered webhook.
    /// VI: Xóa webhook đã đăng ký.
    /// </summary>
    Task DeleteWebhookAsync(
        string webhookId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// EN: Subscribe to webhook events for the authenticated user.
    /// VI: Đăng ký nhận webhook events cho người dùng đã xác thực.
    /// </summary>
    Task SubscribeToWebhookAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// EN: Validate CRC token for webhook verification.
    /// VI: Xác thực CRC token cho webhook verification.
    /// </summary>
    string GenerateCrcResponse(string crcToken);

    #endregion

    #region Media

    /// <summary>
    /// EN: Upload media for use in messages.
    /// VI: Tải lên media để sử dụng trong tin nhắn.
    /// </summary>
    Task<string> UploadMediaAsync(
        byte[] mediaData,
        string mediaType,
        CancellationToken cancellationToken = default);

    #endregion

    #region Rate Limiting

    /// <summary>
    /// EN: Get remaining rate limit for an endpoint.
    /// VI: Lấy rate limit còn lại cho một endpoint.
    /// </summary>
    Task<RateLimitInfo> GetRateLimitInfoAsync(string endpoint);

    #endregion
}

#region DTOs

/// <summary>
/// EN: Result of sending a direct message.
/// VI: Kết quả gửi tin nhắn trực tiếp.
/// </summary>
public record TwitterMessageResult(
    bool Success,
    string? MessageId,
    string? Error);

/// <summary>
/// EN: Twitter direct message data.
/// VI: Dữ liệu tin nhắn trực tiếp Twitter.
/// </summary>
public record TwitterDirectMessage(
    string Id,
    string SenderId,
    string RecipientId,
    string Text,
    DateTime CreatedAt,
    List<TwitterMessageAttachment>? Attachments);

/// <summary>
/// EN: Message attachment data.
/// VI: Dữ liệu tệp đính kèm tin nhắn.
/// </summary>
public record TwitterMessageAttachment(
    string Type,
    string Url,
    string? MediaId);

/// <summary>
/// EN: Twitter user information.
/// VI: Thông tin người dùng Twitter.
/// </summary>
public record TwitterUser(
    string Id,
    string Username,
    string Name,
    string? ProfileImageUrl,
    string? Description,
    bool Verified,
    int FollowersCount,
    int FollowingCount);

/// <summary>
/// EN: Rate limit information.
/// VI: Thông tin giới hạn tốc độ.
/// </summary>
public record RateLimitInfo(
    int Limit,
    int Remaining,
    DateTime ResetAt);

#endregion
