Новый api отправки сообщений

2025-12-24 08:43:46 +03:00
parent 833d8c80d9
commit 37cb6599ba
19 changed files with 478 additions and 338 deletions
--- a/BotPages.Core/Abstractions/AdapterOptionsBag.cs
+++ b/BotPages.Core/Abstractions/AdapterOptionsBag.cs
@@ -0,0 +1,44 @@
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Êîíòåéíåð äëÿ àäàïòåð-ñïåöèôè÷íûõ îïöèé, ïîçâîëÿþùèé õðàíèòü ïàðàìåòðû äëÿ íåñêîëüêèõ àäàïòåðîâ.
+/// Èñïîëüçóåòñÿ âíóòðè `SendRequest.AdapterOptions`.
+/// </summary>
+public sealed class AdapterOptionsBag
+{
+    private readonly Dictionary<string, object?> _map = new(StringComparer.OrdinalIgnoreCase);
+
+    /// <summary>
+    /// Óñòàíîâèòü îïöèè äëÿ àäàïòåðà.
+    /// </summary>
+    public void Set<T>(string adapterKey, T options)
+    {
+        if (adapterKey is null) throw new ArgumentNullException(nameof(adapterKey));
+        _map[adapterKey] = options;
+    }
+
+    /// <summary>
+    /// Ïîïðîáîâàòü ïîëó÷èòü îïöèè äëÿ àäàïòåðà.
+    /// </summary>
+    public bool TryGet<T>(string adapterKey, out T? options)
+    {
+        if (adapterKey is null) throw new ArgumentNullException(nameof(adapterKey));
+        if (_map.TryGetValue(adapterKey, out var o) && o is T t)
+        {
+            options = t;
+            return true;
+        }
+
+        options = default;
+        return false;
+    }
+
+    /// <summary>
+    /// Ïîëó÷èòü îïöèè èëè âåðíóòü null.
+    /// </summary>
+    public T? GetOrDefault<T>(string adapterKey)
+    {
+        TryGet(adapterKey, out T? v);
+        return v;
+    }
+}
--- a/BotPages.Core/Abstractions/IMessengerAdapter.cs
+++ b/BotPages.Core/Abstractions/IMessengerAdapter.cs
@@ -15,27 +15,9 @@ public interface IMessengerAdapter
    Capabilities Capabilities { get; }

    /// <summary>
-    /// Отправить текстовое сообщение в чат.
+    /// Универсальный метод отправки с использованием общего описания запроса.
    /// </summary>
-    Task<string?> SendTextAsync(string chatId,
-        string text,
-        MessageFormat format = MessageFormat.Plain,
-        IEnumerable<IEnumerable<InlineButton>>? inline = null,
-        IEnumerable<IEnumerable<ReplyButton>>? reply = null,
-        string? messageId = null,
-        CancellationToken ct = default
-    );
-
-    /// <summary>
-    /// Отправить файл в чат.
-    /// </summary>
-    Task SendFileAsync(string chatId,
-        FileDescriptor file,
-        string? caption = null,
-        MessageFormat? captionFormat = null,
-        IEnumerable<IEnumerable<InlineButton>>? inline = null,
-        IEnumerable<IEnumerable<ReplyButton>>? reply = null,
-        CancellationToken ct = default);
+    Task<string?> SendAsync(SendRequest request, CancellationToken ct = default);

    /// <summary>
    /// Создать билдер альбома для отправки медиагруппы.
--- a/BotPages.Core/Abstractions/SendRequest.cs
+++ b/BotPages.Core/Abstractions/SendRequest.cs
@@ -0,0 +1,43 @@
+using BotPages.Core.Messaging;
+
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Óíèâåðñàëüíàÿ ñòðóêòóðà çàïðîñà íà îòïðàâêó ñîîáùåíèÿ/ôàéëà, èñïîëüçóåìàÿ àäàïòåðàìè.
+/// Ïîìåùåíà â Core ÷òîáû áûòü äîñòóïíîé äëÿ âñåõ àäàïòåðîâ.
+/// </summary>
+public sealed class SendRequest
+{
+    /// <summary>Èäåíòèôèêàòîð ÷àòà/ñåññèè â ìåññåíäæåðå.</summary>
+    public required string ChatId { get; init; }
+
+    /// <summary>Òåêñò ñîîáùåíèÿ (åñëè îòïðàâëÿåòñÿ òåêñò).</summary>
+    public string? Text { get; init; }
+
+    /// <summary>Ôîðìàò òåêñòà (HTML/Markdown/Plain).</summary>
+    public MessageFormat? TextFormat { get; init; }
+
+    /// <summary>Inline êíîïêè (ñòðîêè êíîïîê).</summary>
+    public IEnumerable<IEnumerable<InlineButton>>? Inline { get; init; }
+
+    /// <summary>Reply êëàâèàòóðà (ñòðîêè êíîïîê).</summary>
+    public IEnumerable<IEnumerable<ReplyButton>>? Reply { get; init; }
+
+    /// <summary>Id ðåäàêòèðóåìîãî ñîîáùåíèÿ (åñëè ðåäàêòèðóåì).</summary>
+    public string? MessageId { get; init; }
+
+    /// <summary>Ôàéë äëÿ îòïðàâêè (åñëè îòïðàâëÿåòñÿ ôàéë).</summary>
+    public FileDescriptor? File { get; init; }
+
+    /// <summary>Ïîäïèñü äëÿ ôàéëà.</summary>
+    public string? Caption { get; init; }
+
+    /// <summary>Ôîðìàò ïîäïèñè/ïîäïèñè äëÿ ôàéëà.</summary>
+    public MessageFormat? CaptionFormat { get; init; }
+
+    /// <summary>
+    /// Êîíòåéíåð àäàïòåð-ñïåöèôè÷íûõ îïöèé.
+    /// Ñîäåðæèò èìåíà/êëþ÷è àäàïòåðîâ è ñîîòâåòñòâóþùèå îáúåêòû îïöèé.
+    /// </summary>
+    public AdapterOptionsBag? AdapterOptions { get; init; }
+}
--- a/BotPages.Core/Context/PageContextAdapterExtensions.cs
+++ b/BotPages.Core/Context/PageContextAdapterExtensions.cs
@@ -4,12 +4,19 @@ using BotPages.Core.Messaging;
 namespace BotPages.Core;

 /// <summary>
-/// Расширения <see cref="PageContext"/> для работы с <see cref="IMessengerAdapter"/>
+/// Расширения <see cref="PageContext"/> для работы с адаптером.
+/// Упрощают создание универсального `SendRequest`.
 /// </summary>
 public static class PageContextAdapterExtensions
 {
    /// <summary>
-    /// Отправить текстовое сообщение.
+    /// Отправить универсальный запрос через привязанный адаптер.
+    /// </summary>
+    public static Task<string?> SendAsync(this PageContext ctx, SendRequest request, CancellationToken ct = default)
+        => ctx.Adapter.SendAsync(request, ct);
+
+    /// <summary>
+    /// Удобная оболочка: отправить текстовое сообщение.
    /// </summary>
    public static Task<string?> SendTextAsync(this PageContext ctx,
        string text,
@@ -17,25 +24,56 @@ public static class PageContextAdapterExtensions
        IEnumerable<IEnumerable<InlineButton>>? inline = null,
        IEnumerable<IEnumerable<ReplyButton>>? reply = null,
        string? messageId = null,
+        object? adapterOptions = null,
        CancellationToken ct = default)
-        => ctx.Adapter.SendTextAsync(ctx.Update.Chat.Id, text, format, inline, reply, messageId, ct);
+    {
+        var bag = adapterOptions switch
+        {
+            null => null,
+            AdapterOptionsBag b => b,
+            _ => throw new ArgumentException("adapterOptions must be an AdapterOptionsBag or null. Use MessageBuilder extensions to set adapter options.", nameof(adapterOptions))
+        };
+
+        return ctx.SendAsync(new SendRequest
+        {
+            ChatId = ctx.Update.Chat.Id,
+            Text = text,
+            TextFormat = format,
+            Inline = inline,
+            Reply = reply,
+            MessageId = messageId,
+            AdapterOptions = bag
+        }, ct);
+    }

    /// <summary>
-    /// Отправить файл.
+    /// Удобная оболочка: отправить файл.
    /// </summary>
-    public static Task SendFileAsync(this PageContext ctx,
+    public static Task<string?> SendFileAsync(this PageContext ctx,
        FileDescriptor file,
        string? caption = null,
        MessageFormat? captionFormat = null,
        IEnumerable<IEnumerable<InlineButton>>? inline = null,
        IEnumerable<IEnumerable<ReplyButton>>? reply = null,
-        CancellationToken ct = default
-    )
-        => ctx.Adapter.SendFileAsync(chatId: ctx.Update.Chat.Id,
-            file: file,
-            caption: caption,
-            captionFormat: captionFormat,
-            inline: inline,
-            reply: reply,
-            ct: ct);
+        object? adapterOptions = null,
+        CancellationToken ct = default)
+    {
+        var bag = adapterOptions switch
+        {
+            null => null,
+            AdapterOptionsBag b => b,
+            _ => throw new ArgumentException("adapterOptions must be an AdapterOptionsBag or null. Use MessageBuilder extensions to set adapter options.", nameof(adapterOptions))
+        };
+
+        return ctx.SendAsync(new SendRequest
+        {
+            ChatId = ctx.Update.Chat.Id,
+            File = file,
+            Caption = caption,
+            CaptionFormat = captionFormat,
+            Inline = inline,
+            Reply = reply,
+            AdapterOptions = bag
+        }, ct);
+    }
 }
--- a/BotPages.Core/Messaging/MessageBuilder.cs
+++ b/BotPages.Core/Messaging/MessageBuilder.cs
@@ -4,6 +4,7 @@ namespace BotPages.Core.Messaging;

 /// <summary>
 /// Fluent‑билдер для отправки сообщений (текст, кнопки, файлы, альбомы, прогресс).
+/// Поддерживает указание адаптер-специфичных опций через `WithAdapterOption`.
 /// </summary>
 public sealed class MessageBuilder
 {
@@ -16,10 +17,21 @@ public sealed class MessageBuilder
    private readonly List<(FileDescriptor file, string? caption, MessageFormat? captionFormat)> _album = new();
    private bool _disableReplyKeyboard;
    private string? _editMessageId = null;
+    private AdapterOptionsBag? _adapterOptions = null;

    /// <summary>Создать билдер сообщений.</summary>
    public MessageBuilder(PageContext ctx) => _ctx = ctx;

+    /// <summary>
+    /// Установить опции для конкретного адаптера. Ключ адаптера определяется адаптером (напр., "telegram").
+    /// </summary>
+    public MessageBuilder WithAdapterOption<T>(string adapterKey, T options)
+    {
+        if (_adapterOptions is null) _adapterOptions = new AdapterOptionsBag();
+        _adapterOptions.Set(adapterKey, options);
+        return this;
+    }
+
    /// <summary>Текст сообщения.</summary>
    public MessageBuilder Text(string text, MessageFormat format = MessageFormat.Plain)
    {
@@ -63,7 +75,7 @@ public sealed class MessageBuilder
        return this;
    }

-    /// <summary>Добавить строку inline‑кнопок.</summary>
+    /// <summary>Добавить строки inline‑кнопок.</summary>
    public MessageBuilder Inline(IEnumerable<IEnumerable<InlineButton>> row)
    {
        _inline.AddRange(row.Select(t => t.ToList()).ToList());
@@ -73,7 +85,6 @@ public sealed class MessageBuilder
    /// <summary>
    /// Отключение Reply клавиатуры.
    /// </summary>
-    /// <returns></returns>
    public MessageBuilder DisableReply()
    {
        _disableReplyKeyboard = true;
@@ -96,7 +107,7 @@ public sealed class MessageBuilder
        return this;
    }

-    /// <summary>Добавить строку reply‑кнопок.</summary>
+    /// <summary>Добавить строки reply‑кнопок.</summary>
    public MessageBuilder Reply(IEnumerable<IEnumerable<ReplyButton>> row)
    {
        _disableReplyKeyboard = false;
@@ -130,18 +141,16 @@ public sealed class MessageBuilder
        // Текст
        if (!string.IsNullOrWhiteSpace(_text))
        {
-            messageId = await _ctx.SendTextAsync(_text, _format, _inline, reply, _editMessageId, ct);
+            messageId = await _ctx.SendTextAsync(_text, _format, _inline, reply, _editMessageId, _adapterOptions, ct);
        }

        // Файлы
        foreach (var (file, caption, captionFormat) in _files)
-            await _ctx.SendFileAsync(file: file
-                , caption: caption
-                , captionFormat: captionFormat
-                , reply: reply
-                , inline: _inline
-                , ct: ct
-            );
+        {
+            var res = await _ctx.SendFileAsync(file, caption, captionFormat, _inline, reply, _adapterOptions, ct);
+            // сохранить первый возвращённый id сообщения
+            if (messageId is null && res is not null) messageId = res;
+        }

        // Альбом
        if (_album.Count > 0)
@@ -157,6 +166,7 @@ public sealed class MessageBuilder
        _album.Clear();

        _editMessageId = null;
+        _adapterOptions = null;

        return messageId;
    }
--- a/BotPages.Core/Middleware/ErrorHandlingMiddleware.cs
+++ b/BotPages.Core/Middleware/ErrorHandlingMiddleware.cs
@@ -27,8 +27,12 @@ public sealed class ErrorHandlingMiddleware : IPageMiddleware
        {
            _logger.Log(LogLevel.Critical, "Unhandled exception in middleware pipeline.", ex);

-            // Теперь можно напрямую использовать PageContext для ответа
-            await ctx.SendTextAsync("Произошла ошибка при обработке запроса. Попробуйте ещё раз.", ct: ct);
+            // Отправляем универсальный запрос с текстом об ошибке
+            await ctx.SendAsync(new SendRequest
+            {
+                ChatId = ctx.Update.Chat.Id,
+                Text = "Произошла ошибка при обработке запроса. Попробуйте ещё раз."
+            }, ct);
        }
    }
 }
--- a/BotPages.Telegram/BotPagesAppExtension.cs
+++ b/BotPages.Telegram/BotPagesAppExtension.cs
@@ -15,8 +15,14 @@ public static class BotPagesAppExtension
    /// <param name="messengerType"></param>
    /// <returns></returns>
    public static BotPagesApp AddTelegramAdapter(this BotPagesApp app, string token, string messengerType = "")
+        => app.AddTelegramAdapter(token, null, messengerType);
+
+    /// <summary>
+    /// Добавление адаптера для телеграмм с опциями.
+    /// </summary>
+    public static BotPagesApp AddTelegramAdapter(this BotPagesApp app, string token, TelegramOptions? options, string messengerType = "")
    {
-        var telegram = new TelegramAdapter(app.Logger, token);
+        var telegram = new TelegramAdapter(app.Logger, token, options);

        if (!string.IsNullOrWhiteSpace(messengerType)) telegram.MessengerType = messengerType;

--- a/BotPages.Telegram/MessageBuilderExtensions.cs
+++ b/BotPages.Telegram/MessageBuilderExtensions.cs
@@ -0,0 +1,43 @@
+using BotPages.Core.Abstractions;
+using BotPages.Core.Messaging;
+
+namespace BotPages.Telegram;
+
+/// <summary>
+/// Ðàñøèðåíèÿ äëÿ `MessageBuilder` ñïåöèôè÷íûå äëÿ Telegram.
+/// Ïîçâîëÿþò óäîáíî çàäàòü `TelegramOptions` äëÿ êîíêðåòíîãî ñîîáùåíèÿ
+/// áåç èçìåíåíèÿ ñàìîãî áèëäåðà.
+/// </summary>
+public static class MessageBuilderExtensions
+{
+    /// <summary>
+    /// Óñòàíîâèòü îïöèè Telegram äëÿ êîíêðåòíîãî ñîîáùåíèÿ (ïåðåîïðåäåëÿþò îïöèè àäàïòåðà).
+    /// </summary>
+    public static MessageBuilder WithTelegramOptions(this MessageBuilder builder, TelegramOptions options)
+    {
+        // Ensure bag exists
+        var bag = (builder as object) switch
+        {
+            MessageBuilder mb => GetAdapterBag(mb) ?? CreateAndSetAdapterBag(mb),
+            _ => null
+        };
+
+        bag?.Set("telegram", options);
+        return builder;
+    }
+
+    // Reflection helpers to access private adapterOptions field on MessageBuilder
+    private static AdapterOptionsBag? GetAdapterBag(MessageBuilder builder)
+    {
+        var fi = typeof(MessageBuilder).GetField("_adapterOptions", System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);
+        return fi?.GetValue(builder) as AdapterOptionsBag;
+    }
+
+    private static AdapterOptionsBag CreateAndSetAdapterBag(MessageBuilder builder)
+    {
+        var fi = typeof(MessageBuilder).GetField("_adapterOptions", System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);
+        var bag = new AdapterOptionsBag();
+        fi?.SetValue(builder, bag);
+        return bag;
+    }
+}
--- a/BotPages.Telegram/TelegramAdapter.cs
+++ b/BotPages.Telegram/TelegramAdapter.cs
@@ -21,11 +21,12 @@ namespace BotPages.Telegram;
 /// Адаптер для Telegram на базе Telegram.Bot.
 /// Реализует отправку текста, кнопок, файлов, альбомов и прогресса.
 /// </summary>
-public sealed class TelegramAdapter : IMessangerAdapterSetup
+public sealed class TelegramAdapter : IMessengerAdapterSetup
 {
    private readonly ILogger _logger;
    private TelegramBotClient? _client;
    private string _token;
+    private readonly TelegramOptions _options;
    private static Capabilities _capabilities = new()
    {
        SupportsInlineButtons = true,
@@ -37,10 +38,11 @@ public sealed class TelegramAdapter : IMessangerAdapterSetup
    };

    /// <summary>Создать адаптер Telegram.</summary>
-    public TelegramAdapter(ILogger logger, string token)
+    public TelegramAdapter(ILogger logger, string token, TelegramOptions? options = null)
    {
        _logger = logger;
        _token = token;
+        _options = options ?? new TelegramOptions();
    }

    /// <summary>
@@ -81,6 +83,7 @@ public sealed class TelegramAdapter : IMessangerAdapterSetup
            cancellationToken: ct
        );

+
        await _client.SetMyCommands(commands.Where(t => t.Publish).Select(t => new BotCommand(t.Name, t.Description ?? t.Name.TrimStart('/'))), cancellationToken: ct);

        var me = await _client.GetMe();
@@ -89,13 +92,11 @@ public sealed class TelegramAdapter : IMessangerAdapterSetup
        return;
    }

-    /// <inheritdoc />
-    public async Task<string?> SendTextAsync(string chatId, string text,
-        MessageFormat format = MessageFormat.Plain,
-        IEnumerable<IEnumerable<InlineButton>>? inline = null,
-        IEnumerable<IEnumerable<ReplyButton>>? reply = null,
-        string? messageId = null,
-        CancellationToken ct = default)
+    /// <summary>
+    /// Универсальный внутренний метод отправки — определяет, нужно ли отправлять текст или файл по параметрам.
+    /// Возвращает id сообщения (или null).
+    /// </summary>
+    public async Task<string?> SendAsync(SendRequest req, CancellationToken ct)
    {
        if (_client is null)
        {
@@ -103,23 +104,29 @@ public sealed class TelegramAdapter : IMessangerAdapterSetup
            return null;
        }

+        // determine adapter-specific options (TelegramOptions) from bag or use adapter default
+        TelegramOptions telegramOptions = _options;
+        if (req.AdapterOptions is AdapterOptionsBag bag && bag.TryGet("telegram", out TelegramOptions? opt) && opt is not null)
+        {
+            telegramOptions = opt;
+        }
+        var disableNotification = !telegramOptions.NotifyOnSend;
+
+        // Build markup
        InlineKeyboardMarkup? inlineMarkup = null;
        ReplyMarkup? markup = null;

-        if (inline is not null && inline.Any())
+        if (req.Inline is not null && req.Inline.Any())
        {
            inlineMarkup = new InlineKeyboardMarkup(
-                inline.Select(row => row.Select(b => new InlineKeyboardButton(b.Label, b.Value)).ToArray())
-                      .ToArray()
+                req.Inline.Select(row => row.Select(b => new InlineKeyboardButton(b.Label, b.Value)).ToArray()).ToArray()
            );
        }
-        else if (reply is not null)
+        else if (req.Reply is not null)
        {
-            if (reply.Any())
+            if (req.Reply.Any())
            {
-                markup = new ReplyKeyboardMarkup(
-                    reply.Select(row => row.Select(b => new KeyboardButton(b.Label)).ToArray()).ToArray()
-                )
+                markup = new ReplyKeyboardMarkup(req.Reply.Select(row => row.Select(b => new KeyboardButton(b.Label)).ToArray()).ToArray())
                {
                    ResizeKeyboard = true
                };
@@ -130,90 +137,17 @@ public sealed class TelegramAdapter : IMessangerAdapterSetup
            }
        }

-        var parseMode = ParseMode.None;
-
-        switch (format)
+        // If there is a file — send file
+        if (req.File is not null)
        {
-            case MessageFormat.Html:
-                {
-                    parseMode = ParseMode.Html;
-                    break;
-                }
-            case MessageFormat.Plain:
-                {
-                    parseMode = ParseMode.None;
-                    break;
-                }
-            case MessageFormat.Markdown:
-                {
-                    parseMode = ParseMode.MarkdownV2;
-                    break;
-                }
-            default:
-                {
-                    _logger.Log(LogLevel.Warn, $"MessageFormat '{format}' not supported. Degraded to plain text.");
-                    break;
-                }
-        }
-
-        // Длина сообщения
-        if (text.Length > Capabilities.MaxMessageLength)
-        {
-            _logger.Log(LogLevel.Warn, $"Message too long ({text.Length}). Truncated to {Capabilities.MaxMessageLength}.");
-            text = text.Substring(0, Capabilities.MaxMessageLength);
-        }
-
-        if (!string.IsNullOrWhiteSpace(messageId))
-        {
-            await _client.EditMessageText(
-                messageId: int.Parse(messageId),
-                chatId: long.Parse(chatId),
-                text: text,
-                parseMode: parseMode,
-                replyMarkup: inlineMarkup,
-                cancellationToken: ct
-            );
-
-            return messageId;
-        }
-        else
-        {
-            if (inlineMarkup is not null) markup = inlineMarkup;
-
-            var message = await _client.SendMessage(
-                chatId: long.Parse(chatId),
-                text: text,
-                parseMode: parseMode,
-                replyMarkup: markup,
-                cancellationToken: ct
-            );
-
-            return message.Id.ToString();
-        }
-    }
-
-    /// <inheritdoc />
-    public async Task SendFileAsync(string chatId,
-        FileDescriptor file,
-        string? caption = null,
-        MessageFormat? captionFormat = null,
-        IEnumerable<IEnumerable<InlineButton>>? inline = null,
-        IEnumerable<IEnumerable<ReplyButton>>? reply = null,
-        CancellationToken ct = default
-    )
-    {
-        if (_client is null)
-        {
-            _logger.Log(LogLevel.Critical, $"{MessengerType} client is not initialized.");
-            return;
-        }
+            var file = req.File;

            // Получаем поток, если он задан
            Stream? stream = null;
            if (file.GetStreamAsync is not null)
            {
                stream = await file.GetStreamAsync(ct);
-            stream.Position = 0;
+                if (stream is not null) stream.Position = 0;
            }

            InputFile inputFile;
@@ -232,78 +166,140 @@ public sealed class TelegramAdapter : IMessangerAdapterSetup
            }

            var parseMode = ParseMode.None;
-
-        switch (captionFormat)
+            switch (req.CaptionFormat)
            {
                case MessageFormat.Html:
-                {
                    parseMode = ParseMode.Html;
                    break;
-                }
-            case MessageFormat.Plain:
-                {
-                    parseMode = ParseMode.None;
-                    break;
-                }
                case MessageFormat.Markdown:
-                {
                    parseMode = ParseMode.MarkdownV2;
                    break;
-                }
+                case MessageFormat.Plain:
                case null:
-                {
                    parseMode = ParseMode.None;
                    break;
            }
-            default:
+
+            if (inlineMarkup is not null) markup = inlineMarkup;
+
+            Message? sentMessage = req.File.Kind switch
            {
-                    _logger.Log(LogLevel.Warn, $"MessageFormat '{captionFormat}' not supported. Degraded to plain text.");
+                FileKind.Photo => await _client.SendPhoto(long.Parse(req.ChatId), inputFile, req.Caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
+                FileKind.Video => await _client.SendVideo(long.Parse(req.ChatId), inputFile, caption: req.Caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
+                FileKind.Audio => await _client.SendAudio(long.Parse(req.ChatId), inputFile, req.Caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
+                _ => await _client.SendDocument(long.Parse(req.ChatId), inputFile, req.Caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
+            };
+
+            return sentMessage?.MessageId.ToString();
+        }
+
+        // Otherwise treat as text
+        if (!string.IsNullOrWhiteSpace(req.Text))
+        {
+            var format = req.TextFormat ?? MessageFormat.Plain;
+            var parseMode = ParseMode.None;
+
+            switch (format)
+            {
+                case MessageFormat.Html:
+                    parseMode = ParseMode.Html;
+                    break;
+                case MessageFormat.Markdown:
+                    parseMode = ParseMode.MarkdownV2;
+                    break;
+                case MessageFormat.Plain:
+                default:
+                    parseMode = ParseMode.None;
                    break;
            }
+
+            // Длина сообщения
+            var text = req.Text!;
+            if (text.Length > Capabilities.MaxMessageLength)
+            {
+                _logger.Log(LogLevel.Warn, $"Message too long ({text.Length}). Truncated to {Capabilities.MaxMessageLength}.");
+                text = text.Substring(0, Capabilities.MaxMessageLength);
            }

-        ReplyMarkup? markup = null;
-
-        if (inline is not null && inline.Any())
+            if (!string.IsNullOrWhiteSpace(req.MessageId))
            {
-            markup = new InlineKeyboardMarkup(
-                inline.Select(row => row.Select(b => new InlineKeyboardButton(b.Label, b.Value)).ToArray())
-                      .ToArray()
+                await _client.EditMessageText(
+                    messageId: int.Parse(req.MessageId),
+                    chatId: long.Parse(req.ChatId),
+                    text: text,
+                    parseMode: parseMode,
+                    replyMarkup: inlineMarkup,
+                    cancellationToken: ct
                );
-        }
-        else if (reply is not null)
-        {
-            if (reply.Any())
-            {
-                markup = new ReplyKeyboardMarkup(
-                    reply.Select(row => row.Select(b => new KeyboardButton(b.Label)).ToArray()).ToArray()
-                )
-                {
-                    ResizeKeyboard = true
-                };
+
+                return req.MessageId;
            }
            else
            {
-                markup = new ReplyKeyboardRemove();
+                if (inlineMarkup is not null) markup = inlineMarkup;
+
+                var message = await _client.SendMessage(
+                    chatId: long.Parse(req.ChatId),
+                    text: text,
+                    parseMode: parseMode,
+                    replyMarkup: markup,
+                    disableNotification: disableNotification,
+                    cancellationToken: ct
+                );
+
+                return message.MessageId.ToString();
            }
        }

-        // В зависимости от FileKind выбираем подходящий метод
-        switch (file.Kind)
-        {
-            case FileKind.Photo:
-                await _client.SendPhoto(long.Parse(chatId), inputFile, caption ?? "", parseMode, replyMarkup: markup, cancellationToken: ct);
-                break;
-            case FileKind.Video:
-                await _client.SendVideo(long.Parse(chatId), inputFile, caption: caption ?? "", parseMode, replyMarkup: markup, cancellationToken: ct);
-                break;
-            case FileKind.Audio:
-                await _client.SendAudio(long.Parse(chatId), inputFile, caption ?? "", parseMode, replyMarkup: markup, cancellationToken: ct);
-                break;
-            default:
-                await _client.SendDocument(long.Parse(chatId), inputFile, caption ?? "", parseMode, replyMarkup: markup, cancellationToken: ct);
-                break;
+        return null;
    }
+
+    /// <inheritdoc />
+    public Task<string?> SendTextAsync(string chatId, string text,
+        MessageFormat format = MessageFormat.Plain,
+        IEnumerable<IEnumerable<InlineButton>>? inline = null,
+        IEnumerable<IEnumerable<ReplyButton>>? reply = null,
+        string? messageId = null,
+        object? adapterOptions = null,
+        CancellationToken ct = default)
+    {
+        var req = new SendRequest
+        {
+            ChatId = chatId,
+            Text = text,
+            TextFormat = format,
+            Inline = inline,
+            Reply = reply,
+            MessageId = messageId,
+            AdapterOptions = adapterOptions as AdapterOptionsBag
+        };
+
+        return SendAsync(req, ct);
+    }
+
+    /// <inheritdoc />
+    public Task SendFileAsync(string chatId,
+        FileDescriptor file,
+        string? caption = null,
+        MessageFormat? captionFormat = null,
+        IEnumerable<IEnumerable<InlineButton>>? inline = null,
+        IEnumerable<IEnumerable<ReplyButton>>? reply = null,
+        object? adapterOptions = null,
+        CancellationToken ct = default
+    )
+    {
+        var req = new SendRequest
+        {
+            ChatId = chatId,
+            File = file,
+            Caption = caption,
+            CaptionFormat = captionFormat,
+            Inline = inline,
+            Reply = reply,
+            AdapterOptions = adapterOptions as AdapterOptionsBag
+        };
+
+        return SendAsync(req, ct);
    }

    /// <inheritdoc />
--- a/BotPages.Telegram/TelegramOptions.cs
+++ b/BotPages.Telegram/TelegramOptions.cs
@@ -0,0 +1,14 @@
+namespace BotPages.Telegram;
+
+/// <summary>
+/// Настройки адаптера Telegram, применяемые по умолчанию при отправке сообщений.
+/// </summary>
+public sealed class TelegramOptions
+{
+    /// <summary>
+    /// Отправлять ли уведомление (sound) при отправке сообщения. По умолчанию true.
+    /// </summary>
+    public bool NotifyOnSend { get; set; } = true;
+
+    // В будущем можно добавить: default parse mode, disable web page preview и т.д.
+}
--- a/Demo/Pages/DetailsPage.cs
+++ b/Demo/Pages/DetailsPage.cs
@@ -6,7 +6,6 @@ namespace Demo.Pages;

 /// <summary>
 /// Страница ввода деталей заявки.
-/// Страница с параметрами и получением состояния.
 /// </summary>
 public sealed class DetailsPage : StatefullPage<string>
 {
@@ -32,20 +31,15 @@ public sealed class DetailsPage : StatefullPage<string>
        switch (payload)
        {
            case "next":
-                {
                await SaveState(ctx, ct);
                await ctx.Navigation.GoToAsync<FilesPage>(ctx, ct);
                break;
-                }

            case "back":
-                {
                await ctx.Navigation.GoToAsync<TitlePage>(ctx, ct);
                break;
        }
    }
-        ;
-    }

    public override async Task OnText(PageContext ctx, string text, CancellationToken ct)
    {
@@ -61,7 +55,6 @@ public sealed class DetailsPage : StatefullPage<string>
        string? title = "";
        args?.TryGetValue("title", out title);

-        // Навигация на страницу по имени
        await ctx.Navigation.GoToAsync<DetailsPage, string>(ctx, title ?? "", ct);
    };
 }
--- a/Demo/Pages/FileSendPage.cs
+++ b/Demo/Pages/FileSendPage.cs
@@ -15,7 +15,7 @@ public sealed class FileSendPage : SingletonPage

        var demoFile = new FileDescriptor
        {
-            Id = "", // не используется при отправке нового файла
+            Id = "",
            Name = "demo.txt",
            Extension = "txt",
            Size = stream.Length,
--- a/Demo/Pages/FilesPage.cs
+++ b/Demo/Pages/FilesPage.cs
@@ -6,7 +6,7 @@ namespace Demo.Pages;

 /// <summary>
 /// Страница загрузки файлов.
-/// Обычная страница с полученим и сохранением состояния.
+/// Обычная страница с получением и сохранением состояния.
 /// </summary>
 public sealed class FilesPage : SingletonPage
 {
@@ -18,15 +18,17 @@ public sealed class FilesPage : SingletonPage

    public override async Task OnFile(PageContext ctx, List<FileDescriptor> files, CancellationToken ct)
    {
+        // Пересылаем каждый файл обратно с подтверждением
        foreach (var file in files)
        {
-            await ctx.SendFileAsync(file, $"Файл '{file.Name}' получен и отправлен обратно.", ct: ct);
+            await new MessageBuilder(ctx)
+                .File(file, $"Файл '{file.Name}' получен и отправлен обратно.")
+                .SendAsync(ct);
        }

-        //Обращение через Storage
+        // Сохраняем данные в хранилище состояния
        var request = await ctx.StateStorage.GetAsync<Models.Request>(ctx.SessionKey, "Request", ct);
        request.FilesCount = files.Count;
-        //Обращение через Context
        await ctx.SetStorageAsync("Request", request, ct);

        await new MessageBuilder(ctx)
--- a/Demo/Pages/SubmitPage.cs
+++ b/Demo/Pages/SubmitPage.cs
@@ -10,9 +10,7 @@ public sealed class SubmitPage : SingletonPage
 {
    public override async Task OnEnter(PageContext ctx, CancellationToken ct)
    {
-        var progress = new MessageBuilder(ctx);
-
-        var messageId = await progress
+        var messageId = await new MessageBuilder(ctx)
            .Text("Отправка заявки\n7%")
            .SendAsync(ct);

@@ -21,7 +19,7 @@ public sealed class SubmitPage : SingletonPage
        {
            i += 25;
            Thread.Sleep(TimeSpan.FromMilliseconds(200));
-            await progress
+            await new MessageBuilder(ctx)
                .Text($"Отправка заявки\n{i}%")
                .EditMessage(messageId!)
                .SendAsync(ct);
--- a/Demo/Pages/TitlePage.cs
+++ b/Demo/Pages/TitlePage.cs
@@ -5,7 +5,6 @@ using BotPages.Core.Messaging;
 namespace Demo.Pages;
 /// <summary>
 /// Страница ввода заголовка заявки.
-/// Обычная страница вводом текста.
 /// </summary>
 public sealed class TitlePage : SingletonPage
 {
--- a/Demo/Pages/WelcomePage.cs
+++ b/Demo/Pages/WelcomePage.cs
@@ -7,7 +7,6 @@ namespace Demo.Pages;

 /// <summary>
 /// Стартовая страница демо‑бота.
-/// Обычная страница с кнопками
 /// </summary>
 [Route("Welcome")]
 public sealed class WelcomePage : SingletonPage
@@ -31,20 +30,14 @@ public sealed class WelcomePage : SingletonPage
        switch (button)
        {
            case WelcomePageButtons.CreateRequest:
-                {
                return ctx.Navigation.GoToAsync<TitlePage>(ctx, ct);
-                }

            case WelcomePageButtons.Help:
-                {
                return new MessageBuilder(ctx).Text("Здесь будет справка.", MessageFormat.Plain).SendAsync(ct);
-                }

            case WelcomePageButtons.SendFile:
-                {
                return ctx.Navigation.GoToAsync<FileSendPage>(ctx, ct);
        }
-        }

        return base.OnText(ctx, text, ct);
    }
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # BotPages

-BotPages — кроссплатформенный фреймворк для создания диалоговых ботов с системой страниц (page‑based conversational framework).
+BotPages — кроссплатформенный фреймворк для создания диалоговых ботов с моделью страниц (page‑based conversational framework).

 Цели проекта:
 - Простая модель страниц и навигации.
@@ -11,7 +11,7 @@ BotPages — кроссплатформенный фреймворк для со
 Структура репозитория

 - `BotPages.Core` — ядро фреймворка: навигация, страницы, маршрутизация, реестр команд, middleware, абстракции адаптеров и хранилища состояния.
- `BotPages.Telegram` — адаптер для Telegram Bot API (реализация `IMessangerAdapterSetup`/`IMessengerAdapter`).
+- `BotPages.Telegram` — адаптер для Telegram Bot API (реализация `IMessengerAdapter`).
 - `Demo` — пример приложения с несколькими страницами и конфигурацией адаптера.
 - `BotPages` — мета‑проект для упаковки библиотек.
 - `docs/` — внутренняя документация проекта (Quickstart, API reference и т.д.).
@@ -51,14 +51,24 @@ export TELEGRAM_TOKEN="<token>" # Linux/macOS
 dotnet run --project Demo
 ```

-Основные концепции
+Простой пример конфигурации

- `BotPagesApp` — точка конфигурации приложения: регистрация адаптеров, middleware, маршрутов и команд, запуск.
+```csharp
+var app = new BotPagesApp(stateStorage, logger)
+    .AddTelegramAdapter(token)
+    .AddDefaultPage<WelcomePage>()
+    .MapCommand<WelcomePage>('/start')
+    .AddMiddleware(new LoggingMiddleware(logger));
+
+await app.Build(CancellationToken.None);
+```
+
+Ключевые концепции
+
+- `SendRequest` — единый формат запроса на отправку (текст, файлы, кнопки, опции). Адаптеры реализуют `IMessengerAdapter.SendAsync(SendRequest)`.
 - `Page`, `StatefulPage`, `SingletonPage` — модели страниц с жизненным циклом (`OnEnter`, `OnUpdate`, `OnText`, `OnButton`, `OnFile`, `OnError`).
- `NavigationService` — управление переходами между страницами и определение текущей страницы по сессии.
- `CommandsRegistry` — шаблоны команд вида `/cmd {arg} {opt?}` с поддержкой именованных и опциональных аргументов.
+- `NavigationService` — управление переходами между страницами.
 - `IPageMiddleware` — middleware-конвейер, выполняющийся для каждого апдейта.
- `IMessangerAdapterSetup` / `IMessengerAdapter` — интерфейсы, позволяющие подключать новые мессенджеры.

 Документация

@@ -67,30 +77,6 @@ dotnet run --project Demo
 - `docs/API_REFERENCE.md` — краткий reference публичных API.
 - `docs/PROJECT_DOCUMENTATION.md` — обзор архитектуры и компонентов.

-XML‑документация генерируется при сборке (опция `GenerateDocumentationFile` в `.csproj`), её можно использовать для генерации HTML‑референса (docfx, MkDocs и т.п.).
-
-Примеры использования
-
-```csharp
-var app = new BotPagesApp(stateStorage, logger)
-    .AddAdapter("telegram", new TelegramAdapterSetup(token))
-    .AddDefaultPage<WelcomePage>()
-    .MapCommand<WelcomePage>("/start")
-    .AddMiddleware(new LoggingMiddleware(logger));
-
-await app.Build(CancellationToken.None);
-```
-
-Вклад и тестирование
-
- Принимам пулл‑реквесты. Описание PR должно содержать цель и краткое описание изменения.
- Следуйте единому стилю кода и включённым nullable-аннотациям.
-
 Лицензия

 Проект распространяется под лицензией MIT. Смотрите файл `LICENSE`.
-
-Контакты
-
-Автор: FrigaT
-Репозиторий: https://git.frigat.duckdns.org/FrigaT/BotPages
--- a/docs/API_REFERENCE.md
+++ b/docs/API_REFERENCE.md
@@ -1,50 +1,39 @@
-# API Reference (краткий)
+# Справочник API

-Документ перечисляет публичные API фреймворка и их назначение.
+Ниже краткое описание публичных API проекта BotPages.

 ## BotPages.Core

 ### `BotPagesApp`
- `AddAdapter(string messengerType, IMessangerAdapterSetup adapter)` — зарегистрировать адаптер для мессенджера.
- `AddDefaultPage<TPage>() where TPage : SingletonPage` — установить "домашнюю" страницу приложения.
- `AddMiddleware<TMiddleware>(TMiddleware instance) where TMiddleware : IPageMiddleware` — добавить middleware в конвейер.
- `MapCommand<TPage>(string commandTemplate) where TPage : Page` — зарегистрировать команду, ведущую на страницу.
- `MapCommand(string template, CommandHandler handler)` — зарегистрировать кастомный обработчик команды.
- `MapRoute<TPage>(string template) where TPage : Page` — вручную зарегистрировать маршрут для страницы.
- `AutoMapRoute()` — автоматически найти и зарегистрировать все Page-типы в загруженных сборках.
- `HandleUpdateAsync(UpdateContext update, CancellationToken ct)` — главный обработчик апдейтов (вызвается адаптером).
- `Build(CancellationToken ct)` — запустить все адаптеры и начать обработку апдейтов.
+- `AddTelegramAdapter(string token)` — регистрирует Telegram адаптер с заданным токеном.
+- `AddAdapter(string messengerType, IMessengerAdapter adapter)` — регистрирует произвольный адаптер.
+- `AddMiddleware(IPageMiddleware middleware)` — добавляет middleware в pipeline.
+- `MapCommand<TPage>(string template)` — привязать команду к странице.
+- `MapRoute<TPage>(string template)` — зарегистрировать маршрут.
+- `AutoMapRoute()` — выполнить автопоиск Page?классов и зарегистрировать их маршруты.
+- `Build(CancellationToken ct)` — подготовить и запустить приложение.

-### Страницы
- `Page` — абстрактный базовый класс.
- `StatefulPage` — страница с сохранением состояния.
- `SingletonPage` — одноэкземплярная страница.
+### `IMessengerAdapter`
+- `Task<string?> SendAsync(SendRequest request, CancellationToken ct = default)` — универсальный метод отправки для всех адаптеров.
+- `IAlbumBuilder CreateAlbumBuilder(PageContext ctx)` — создать билдер альбома (если поддерживается).
+- `Task OnLeaveAsync(PageContext ctx, CancellationToken ct)` — вызывается при уходе со страницы.

-### Навигация
- `NavigationService` — отвечает за определение текущей страницы и переходы.
-  - `GoToAsync<TPage>(PageContext ctx, CancellationToken ct)`
-  - `GoToHomeAsync(PageContext ctx, CancellationToken ct)`
+### `SendRequest`
+- `ChatId` — идентификатор чата.
+- `Text`, `TextFormat` — текст и формат.
+- `File`, `Caption`, `CaptionFormat` — файл и подпись.
+- `Inline`, `Reply` — inline и reply клавиатуры.
+- `MessageId` — id редактируемого сообщения.
+- `AdapterOptions` — адаптер?специфичные опции (например `TelegramOptions`).

-### Команды
- `CommandsRegistry` — реестр команд (внутренний). Поддерживает шаблоны с именованными аргументами и опциональными параметрами.
-
-### Middleware
- `IPageMiddleware` — интерфейс middleware.
-  - `InvokeAsync(PageContext ctx, Func<Task> next, CancellationToken ct)`
-
-### Абстракции адаптеров
- `IMessangerAdapterSetup` — настройка адаптера.
- `IMessengerAdapter` — экземпляр адаптера, реализующий `StartAdapterAsync(Func<UpdateContext, Task> onUpdate, List<Command> commands, CancellationToken ct)`.
- `IMessengerAdapterFactory` — фабрика/реестр адаптеров (`MultiAdapterFactory` — реализация).
-
-### Хранилище состояний
- `IStateStorage` — абстракция для сохранения состояния страниц между сессиями.
+### `PageContext` расширения
+- `SendAsync(SendRequest request, CancellationToken ct = default)` — отправить `SendRequest`.
+- `SendTextAsync(...)`, `SendFileAsync(...)` — удобные оболочки, создающие `SendRequest`.

 ## BotPages.Telegram
- Реализация адаптера для Telegram на базе `Telegram.Bot`.
- `TelegramUpdateMapper` — маппит апдейты Telegram в `UpdateContext`.
- `TelegramAlbumBuilder` — собирает медиа-альбомы из последовательных апдейтов.
- `TelegramAdapter` — реализация адаптера, стартует `StartAdapterAsync`.
+- `TelegramAdapter` — реализация `IMessengerAdapter` для Telegram.
+- `TelegramOptions` — настройки адаптера (например `NotifyOnSend`).
+- `MessageBuilderExtensions.WithTelegramOptions` — расширение для установки `TelegramOptions` для конкретного сообщения.


 # Генерация документации
--- a/docs/GETTING_STARTED.md
+++ b/docs/GETTING_STARTED.md
@@ -1,28 +1,37 @@
-# Быстрый старт — BotPages
+# Быстрый старт с BotPages

-Эта инструкция поможет запустить и протестировать проект локально.
+Это руководство поможет быстро запустить demo?приложение с Telegram?адаптером.

 Требования
 - .NET 8 SDK
- Токен Telegram (если используете Telegram-адаптер)
+- Токен Telegram?бота (для demo)

 Сборка
+
 ```bash
 dotnet build
 ```

-Запуск демонстрации
-1. Откройте проект `Demo`.
-2. Внесите токен Telegram (если используется) в код инициализации адаптера или в переменные окружения проекта Demo.
-3. Запустите:
+Запуск demo
+
+1. Установите переменную окружения `TELEGRAM_TOKEN`:
+
+```bash
+setx TELEGRAM_TOKEN "<token>"   # Windows
+export TELEGRAM_TOKEN="<token>" # Linux/macOS
+```
+
+2. Запустите demo:
+
 ```bash
 dotnet run --project Demo
 ```

 Пример конфигурации приложения
+
 ```csharp
 var app = new BotPagesApp(stateStorage, logger)
-    .AddAdapter("telegram", new TelegramAdapterSetup("<token>"))
+    .AddTelegramAdapter(token)
    .AddDefaultPage<WelcomePage>()
    .MapCommand<WelcomePage>("/start")
    .AddMiddleware(new LoggingMiddleware(logger));
@@ -30,18 +39,9 @@ var app = new BotPagesApp(stateStorage, logger)
 await app.Build(CancellationToken.None);
 ```

-Как написать страницу
- Наследуйте `StatefulPage` для страниц с пер-сессионным состоянием.
- Наследуйте `SingletonPage` для одноэкземплярных страниц.
- Переопределите `OnEnter`, `OnUpdate`, `OnText`, `OnButton`, `OnFile`, `OnError` по необходимости.
- Для автоматического маппинга маршрутов используйте `AutoMapRoute()`.
+Основные понятия
+- `SendRequest` — единый формат запроса на отправку (текст, файлы, кнопки, адаптер?опции). Используйте `PageContext.SendAsync` для отправки.
+- `Page` / `StatefulPage` / `SingletonPage` — модели страниц и их жизненный цикл.
+- `IPageMiddleware` — middleware выполняется для каждого входящего обновления.

-Тестирование команд
- Команды регистрируются в `BotPagesApp.MapCommand`.
- Шаблон команд поддерживает именованные и опциональные аргументы: `/cmd {a} {b?}`.
-
-Подсказки
- Middleware выполняются в том порядке, в котором их добавляют в `BotPagesApp`.
- Команды имеют приоритет над обработкой страниц (если текст начинается с `/`).
-
-Если требуется подробный справочник API — смотрите `docs/API_REFERENCE.md`.
+Далее: см. `docs/API_REFERENCE.md` для описания публичных API.