TeleWave/backend/src/TeleWave.Application/Common/Interfaces/ITelegramApi.cs

using TeleWave.Domain.Notifications;

namespace TeleWave.Application.Common.Interfaces;

/// <summary>Кнопка инлайн-клавиатуры: подпись и что вернётся в callback.</summary>
public sealed record TelegramButton(string Text, string CallbackData);

/// <summary>Обновление от Telegram — только то, что нам нужно от его модели.</summary>
public sealed record TelegramUpdate(
    long UpdateId,
    long? ChatId,
    string? Text,
    string? From,
    /// <summary>Идентификатор нажатия: на него надо ответить, иначе кнопка «крутится» у зрителя.</summary>
    string? CallbackId,
    string? CallbackData,
    long? CallbackMessageId
);

/// <summary>Кто мы для Telegram — ответ getMe, по нему проверяется токен.</summary>
public sealed record TelegramBotInfo(long Id, string Username);

/// <summary>
/// Порт к Bot API. Держим ровно те вызовы, что нужны боту расписания: узнать себя, получить
/// обновления, ответить сообщением с кнопками и переключить вебхук.
///
/// Настройки (токен, прокси) реализация читает сама на каждый вызов: админ меняет их в рантайме,
/// и держать клиента, собранного на старте, значило бы требовать перезапуск контейнера.
/// </summary>
public interface ITelegramApi
{
    Task<TelegramBotInfo?> GetMeAsync(
        TelegramSettings settings,
        CancellationToken cancellationToken
    );

    Task<IReadOnlyList<TelegramUpdate>> GetUpdatesAsync(
        TelegramSettings settings,
        long offset,
        CancellationToken cancellationToken
    );

    Task SendMessageAsync(
        TelegramSettings settings,
        long chatId,
        string text,
        IReadOnlyList<IReadOnlyList<TelegramButton>>? keyboard,
        CancellationToken cancellationToken
    );

    /// <summary>Переписывает уже отправленное сообщение — так меню подписок обновляется на месте.</summary>
    Task EditMessageAsync(
        TelegramSettings settings,
        long chatId,
        long messageId,
        string text,
        IReadOnlyList<IReadOnlyList<TelegramButton>>? keyboard,
        CancellationToken cancellationToken
    );

    /// <summary>Гасит «часики» на нажатой кнопке; текст — всплывающая подсказка.</summary>
    Task AnswerCallbackAsync(
        TelegramSettings settings,
        string callbackId,
        string? text,
        CancellationToken cancellationToken
    );

    /// <summary>
    /// Разбирает тело вебхука в то же обновление, что приходит опросом: разговор с ботом один,
    /// и знать про две модели ему незачем. null — тело не разобралось.
    /// </summary>
    Task<TelegramUpdate?> ReadUpdateAsync(Stream body, CancellationToken cancellationToken);

    Task SetWebhookAsync(TelegramSettings settings, CancellationToken cancellationToken);

    Task DeleteWebhookAsync(TelegramSettings settings, CancellationToken cancellationToken);
}