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

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;
+    }
+}

BotPages.Core/Abstractions/IMessengerAdapter.cs

@@ -15,27 +15,9 @@ public interface IMessengerAdapter
     Capabilities Capabilities { get; }
 
     /// <summary>
-    /// Отправить текстовое сообщение в чат.
+    /// Универсальный метод отправки с использованием общего описания запроса.
     /// </summary>
-    Task<string?> SendTextAsync(string chatId,
+    Task<string?> SendAsync(SendRequest request, CancellationToken ct = default);
-        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);
 
     /// <summary>
     /// Создать билдер альбома для отправки медиагруппы.

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; }
+}

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
+        object? adapterOptions = null,
-    )
+        CancellationToken ct = default)
-        => ctx.Adapter.SendFileAsync(chatId: ctx.Update.Chat.Id,
+    {
-            file: file,
+        var bag = adapterOptions switch
-            caption: caption,
+        {
-            captionFormat: captionFormat,
+            null => null,
-            inline: inline,
+            AdapterOptionsBag b => b,
-            reply: reply,
+            _ => throw new ArgumentException("adapterOptions must be an AdapterOptionsBag or null. Use MessageBuilder extensions to set adapter options.", nameof(adapterOptions))
-            ct: ct);
+        };
+
+        return ctx.SendAsync(new SendRequest
+        {
+            ChatId = ctx.Update.Chat.Id,
+            File = file,
+            Caption = caption,
+            CaptionFormat = captionFormat,
+            Inline = inline,
+            Reply = reply,
+            AdapterOptions = bag
+        }, ct);
+    }
 }

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
+            var res = await _ctx.SendFileAsync(file, caption, captionFormat, _inline, reply, _adapterOptions, ct);
-                , captionFormat: captionFormat
+            // сохранить первый возвращённый id сообщения
-                , reply: reply
+            if (messageId is null && res is not null) messageId = res;
-                , inline: _inline
+        }
-                , ct: ct
-            );
 
         // Альбом
         if (_album.Count > 0)
@@ -157,6 +166,7 @@ public sealed class MessageBuilder
         _album.Clear();
 
         _editMessageId = null;
+        _adapterOptions = null;
 
         return messageId;
     }

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);
         }
     }
 }

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;
 

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;
+    }
+}

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 />
+    /// <summary>
-    public async Task<string?> SendTextAsync(string chatId, string text,
+    /// Универсальный внутренний метод отправки — определяет, нужно ли отправлять текст или файл по параметрам.
-        MessageFormat format = MessageFormat.Plain,
+    /// Возвращает id сообщения (или null).
-        IEnumerable<IEnumerable<InlineButton>>? inline = null,
+    /// </summary>
-        IEnumerable<IEnumerable<ReplyButton>>? reply = null,
+    public async Task<string?> SendAsync(SendRequest req, CancellationToken ct)
-        string? messageId = null,
-        CancellationToken ct = default)
     {
         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())
+                req.Inline.Select(row => row.Select(b => new InlineKeyboardButton(b.Label, b.Value)).ToArray()).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(
+                markup = new ReplyKeyboardMarkup(req.Reply.Select(row => row.Select(b => new KeyboardButton(b.Label)).ToArray()).ToArray())
-                    reply.Select(row => row.Select(b => new KeyboardButton(b.Label)).ToArray()).ToArray()
-                )
                 {
                     ResizeKeyboard = true
                 };
@@ -130,180 +137,169 @@ public sealed class TelegramAdapter : IMessangerAdapterSetup
             }
         }
 
-        var parseMode = ParseMode.None;
+        // If there is a file — send file
-
+        if (req.File is not null)
-        switch (format)
         {
-            case MessageFormat.Html:
+            var file = req.File;
-                {
+
+            // Получаем поток, если он задан
+            Stream? stream = null;
+            if (file.GetStreamAsync is not null)
+            {
+                stream = await file.GetStreamAsync(ct);
+                if (stream is not null) stream.Position = 0;
+            }
+
+            InputFile inputFile;
+
+            if (stream is not null && stream != Stream.Null)
+            {
+                inputFile = new InputFileStream(stream, file.Name);
+            }
+            else if (file.Id.StartsWith("http://") || file.Id.StartsWith("https://"))
+            {
+                inputFile = new InputFileUrl(file.Id);
+            }
+            else
+            {
+                inputFile = new InputFileId(file.Id);
+            }
+
+            var parseMode = ParseMode.None;
+            switch (req.CaptionFormat)
+            {
+                case MessageFormat.Html:
                     parseMode = ParseMode.Html;
                     break;
-                }
+                case MessageFormat.Markdown:
-            case MessageFormat.Plain:
-                {
-                    parseMode = ParseMode.None;
-                    break;
-                }
-            case MessageFormat.Markdown:
-                {
                     parseMode = ParseMode.MarkdownV2;
                     break;
-                }
+                case MessageFormat.Plain:
-            default:
+                case null:
-                {
+                    parseMode = ParseMode.None;
-                    _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(
+            Message? sentMessage = req.File.Kind switch
-                chatId: long.Parse(chatId),
+            {
-                text: text,
+                FileKind.Photo => await _client.SendPhoto(long.Parse(req.ChatId), inputFile, req.Caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
-                parseMode: parseMode,
+                FileKind.Video => await _client.SendVideo(long.Parse(req.ChatId), inputFile, caption: req.Caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
-                replyMarkup: markup,
+                FileKind.Audio => await _client.SendAudio(long.Parse(req.ChatId), inputFile, req.Caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
-                cancellationToken: ct
+                _ => await _client.SendDocument(long.Parse(req.ChatId), inputFile, req.Caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
-            );
+            };
 
-            return message.Id.ToString();
+            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);
+            }
+
+            if (!string.IsNullOrWhiteSpace(req.MessageId))
+            {
+                await _client.EditMessageText(
+                    messageId: int.Parse(req.MessageId),
+                    chatId: long.Parse(req.ChatId),
+                    text: text,
+                    parseMode: parseMode,
+                    replyMarkup: inlineMarkup,
+                    cancellationToken: ct
+                );
+
+                return req.MessageId;
+            }
+            else
+            {
+                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();
+            }
+        }
+
+        return null;
     }
 
     /// <inheritdoc />
-    public async Task SendFileAsync(string chatId,
+    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
     )
     {
-        if (_client is null)
+        var req = new SendRequest
         {
-            _logger.Log(LogLevel.Critical, $"{MessengerType} client is not initialized.");
+            ChatId = chatId,
-            return;
+            File = file,
-        }
+            Caption = caption,
+            CaptionFormat = captionFormat,
+            Inline = inline,
+            Reply = reply,
+            AdapterOptions = adapterOptions as AdapterOptionsBag
+        };
 
-        // Получаем поток, если он задан
+        return SendAsync(req, ct);
-        Stream? stream = null;
-        if (file.GetStreamAsync is not null)
-        {
-            stream = await file.GetStreamAsync(ct);
-            stream.Position = 0;
-        }
-
-        InputFile inputFile;
-
-        if (stream is not null && stream != Stream.Null)
-        {
-            inputFile = new InputFileStream(stream, file.Name);
-        }
-        else if (file.Id.StartsWith("http://") || file.Id.StartsWith("https://"))
-        {
-            inputFile = new InputFileUrl(file.Id);
-        }
-        else
-        {
-            inputFile = new InputFileId(file.Id);
-        }
-
-        var parseMode = ParseMode.None;
-
-        switch (captionFormat)
-        {
-            case MessageFormat.Html:
-                {
-                    parseMode = ParseMode.Html;
-                    break;
-                }
-            case MessageFormat.Plain:
-                {
-                    parseMode = ParseMode.None;
-                    break;
-                }
-            case MessageFormat.Markdown:
-                {
-                    parseMode = ParseMode.MarkdownV2;
-                    break;
-                }
-            case null:
-                {
-                    parseMode = ParseMode.None;
-                    break;
-                }
-            default:
-                {
-                    _logger.Log(LogLevel.Warn, $"MessageFormat '{captionFormat}' not supported. Degraded to plain text.");
-                    break;
-                }
-        }
-
-        ReplyMarkup? markup = null;
-
-        if (inline is not null && inline.Any())
-        {
-            markup = new InlineKeyboardMarkup(
-                inline.Select(row => row.Select(b => new InlineKeyboardButton(b.Label, b.Value)).ToArray())
-                      .ToArray()
-            );
-        }
-        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
-                };
-            }
-            else
-            {
-                markup = new ReplyKeyboardRemove();
-            }
-        }
-
-        // В зависимости от 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;
-        }
     }
 
     /// <inheritdoc />

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 и т.д.
+}

Demo/Pages/DetailsPage.cs

@@ -6,7 +6,6 @@ namespace Demo.Pages;
 
 /// <summary>
 /// Страница ввода деталей заявки.
-/// Страница с параметрами и получением состояния.
 /// </summary>
 public sealed class DetailsPage : StatefullPage<string>
 {
@@ -32,19 +31,14 @@ public sealed class DetailsPage : StatefullPage<string>
         switch (payload)
         {
             case "next":
-                {
+                await SaveState(ctx, ct);
-                    await SaveState(ctx, ct);
+                await ctx.Navigation.GoToAsync<FilesPage>(ctx, ct);
-                    await ctx.Navigation.GoToAsync<FilesPage>(ctx, ct);
+                break;
-                    break;
-                }
 
             case "back":
-                {
+                await ctx.Navigation.GoToAsync<TitlePage>(ctx, ct);
-                    await ctx.Navigation.GoToAsync<TitlePage>(ctx, ct);
+                break;
-                    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);
     };
 }

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,

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)

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 new MessageBuilder(ctx)
-
-        var messageId = await progress
             .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);

Demo/Pages/TitlePage.cs

@@ -5,7 +5,6 @@ using BotPages.Core.Messaging;
 namespace Demo.Pages;
 /// <summary>
 /// Страница ввода заголовка заявки.
-/// Обычная страница вводом текста.
 /// </summary>
 public sealed class TitlePage : SingletonPage
 {

Demo/Pages/WelcomePage.cs

@@ -7,7 +7,6 @@ namespace Demo.Pages;
 
 /// <summary>
 /// Стартовая страница демо‑бота.
-/// Обычная страница с кнопками
 /// </summary>
 [Route("Welcome")]
 public sealed class WelcomePage : SingletonPage
@@ -31,19 +30,13 @@ public sealed class WelcomePage : SingletonPage
         switch (button)
         {
             case WelcomePageButtons.CreateRequest:
-                {
+                return ctx.Navigation.GoToAsync<TitlePage>(ctx, ct);
-                    return ctx.Navigation.GoToAsync<TitlePage>(ctx, ct);
-                }
 
             case WelcomePageButtons.Help:
-                {
+                return new MessageBuilder(ctx).Text("Здесь будет справка.", MessageFormat.Plain).SendAsync(ct);
-                    return new MessageBuilder(ctx).Text("Здесь будет справка.", MessageFormat.Plain).SendAsync(ct);
-                }
 
             case WelcomePageButtons.SendFile:
-                {
+                return ctx.Navigation.GoToAsync<FileSendPage>(ctx, ct);
-                    return ctx.Navigation.GoToAsync<FileSendPage>(ctx, ct);
-                }
         }
 
         return base.OnText(ctx, text, ct);

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` — управление переходами между страницами и определение текущей страницы по сессии.
+- `NavigationService` — управление переходами между страницами.
-- `CommandsRegistry` — шаблоны команд вида `/cmd {arg} {opt?}` с поддержкой именованных и опциональных аргументов.
 - `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`.
+Проект распространяется под лицензией MIT. Смотрите файл `LICENSE`.
-
-Контакты
-
-Автор: FrigaT
-Репозиторий: https://git.frigat.duckdns.org/FrigaT/BotPages

docs/API_REFERENCE.md

@@ -1,50 +1,39 @@
-# API Reference (краткий)
+# Справочник API
 
-Документ перечисляет публичные API фреймворка и их назначение.
+Ниже краткое описание публичных API проекта BotPages.
 
 ## BotPages.Core
 
 ### `BotPagesApp`
-- `AddAdapter(string messengerType, IMessangerAdapterSetup adapter)` — зарегистрировать адаптер для мессенджера.
+- `AddTelegramAdapter(string token)` — регистрирует Telegram адаптер с заданным токеном.
-- `AddDefaultPage<TPage>() where TPage : SingletonPage` — установить "домашнюю" страницу приложения.
+- `AddAdapter(string messengerType, IMessengerAdapter adapter)` — регистрирует произвольный адаптер.
-- `AddMiddleware<TMiddleware>(TMiddleware instance) where TMiddleware : IPageMiddleware` — добавить middleware в конвейер.
+- `AddMiddleware(IPageMiddleware middleware)` — добавляет middleware в pipeline.
-- `MapCommand<TPage>(string commandTemplate) where TPage : Page` — зарегистрировать команду, ведущую на страницу.
+- `MapCommand<TPage>(string template)` — привязать команду к странице.
-- `MapCommand(string template, CommandHandler handler)` — зарегистрировать кастомный обработчик команды.
+- `MapRoute<TPage>(string template)` — зарегистрировать маршрут.
-- `MapRoute<TPage>(string template) where TPage : Page` — вручную зарегистрировать маршрут для страницы.
+- `AutoMapRoute()` — выполнить автопоиск Page?классов и зарегистрировать их маршруты.
-- `AutoMapRoute()` — автоматически найти и зарегистрировать все Page-типы в загруженных сборках.
+- `Build(CancellationToken ct)` — подготовить и запустить приложение.
-- `HandleUpdateAsync(UpdateContext update, CancellationToken ct)` — главный обработчик апдейтов (вызвается адаптером).
-- `Build(CancellationToken ct)` — запустить все адаптеры и начать обработку апдейтов.
 
-### Страницы
+### `IMessengerAdapter`
-- `Page` — абстрактный базовый класс.
+- `Task<string?> SendAsync(SendRequest request, CancellationToken ct = default)` — универсальный метод отправки для всех адаптеров.
-- `StatefulPage` — страница с сохранением состояния.
+- `IAlbumBuilder CreateAlbumBuilder(PageContext ctx)` — создать билдер альбома (если поддерживается).
-- `SingletonPage` — одноэкземплярная страница.
+- `Task OnLeaveAsync(PageContext ctx, CancellationToken ct)` — вызывается при уходе со страницы.
 
-### Навигация
+### `SendRequest`
-- `NavigationService` — отвечает за определение текущей страницы и переходы.
+- `ChatId` — идентификатор чата.
-  - `GoToAsync<TPage>(PageContext ctx, CancellationToken ct)`
+- `Text`, `TextFormat` — текст и формат.
-  - `GoToHomeAsync(PageContext ctx, CancellationToken ct)`
+- `File`, `Caption`, `CaptionFormat` — файл и подпись.
+- `Inline`, `Reply` — inline и reply клавиатуры.
+- `MessageId` — id редактируемого сообщения.
+- `AdapterOptions` — адаптер?специфичные опции (например `TelegramOptions`).
 
-### Команды
+### `PageContext` расширения
-- `CommandsRegistry` — реестр команд (внутренний). Поддерживает шаблоны с именованными аргументами и опциональными параметрами.
+- `SendAsync(SendRequest request, CancellationToken ct = default)` — отправить `SendRequest`.
-
+- `SendTextAsync(...)`, `SendFileAsync(...)` — удобные оболочки, создающие `SendRequest`.
-### 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` — абстракция для сохранения состояния страниц между сессиями.
 
 ## BotPages.Telegram
-- Реализация адаптера для Telegram на базе `Telegram.Bot`.
+- `TelegramAdapter` — реализация `IMessengerAdapter` для Telegram.
-- `TelegramUpdateMapper` — маппит апдейты Telegram в `UpdateContext`.
+- `TelegramOptions` — настройки адаптера (например `NotifyOnSend`).
-- `TelegramAlbumBuilder` — собирает медиа-альбомы из последовательных апдейтов.
+- `MessageBuilderExtensions.WithTelegramOptions` — расширение для установки `TelegramOptions` для конкретного сообщения.
-- `TelegramAdapter` — реализация адаптера, стартует `StartAdapterAsync`.
 
 
 # Генерация документации

docs/GETTING_STARTED.md

@@ -1,28 +1,37 @@
-# Быстрый старт — BotPages
+# Быстрый старт с BotPages
 
-Эта инструкция поможет запустить и протестировать проект локально.
+Это руководство поможет быстро запустить demo?приложение с Telegram?адаптером.
 
 Требования
 - .NET 8 SDK
-- Токен Telegram (если используете Telegram-адаптер)
+- Токен Telegram?бота (для demo)
 
 Сборка
+
 ```bash
 dotnet build
 ```
 
-Запуск демонстрации
+Запуск demo
-1. Откройте проект `Demo`.
+
-2. Внесите токен Telegram (если используется) в код инициализации адаптера или в переменные окружения проекта Demo.
+1. Установите переменную окружения `TELEGRAM_TOKEN`:
-3. Запустите:
+
+```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` для страниц с пер-сессионным состоянием.
+- `SendRequest` — единый формат запроса на отправку (текст, файлы, кнопки, адаптер?опции). Используйте `PageContext.SendAsync` для отправки.
-- Наследуйте `SingletonPage` для одноэкземплярных страниц.
+- `Page` / `StatefulPage` / `SingletonPage` — модели страниц и их жизненный цикл.
-- Переопределите `OnEnter`, `OnUpdate`, `OnText`, `OnButton`, `OnFile`, `OnError` по необходимости.
+- `IPageMiddleware` — middleware выполняется для каждого входящего обновления.
-- Для автоматического маппинга маршрутов используйте `AutoMapRoute()`.
 
-Тестирование команд
+Далее: см. `docs/API_REFERENCE.md` для описания публичных API.
-- Команды регистрируются в `BotPagesApp.MapCommand`.
-- Шаблон команд поддерживает именованные и опциональные аргументы: `/cmd {a} {b?}`.
-
-Подсказки
-- Middleware выполняются в том порядке, в котором их добавляют в `BotPagesApp`.
-- Команды имеют приоритет над обработкой страниц (если текст начинается с `/`).
-
-Если требуется подробный справочник API — смотрите `docs/API_REFERENCE.md`.