🚀 Merge #270: Televerse v1.21.0

CHANGELOG.md

@@ -1,3 +1,15 @@
+# 1.21.0
+
+- 🤖 Bot API 7.6
+- Added methods to register callbacks for handling paid media in bot messages:
+  - `Bot.onPaidMedia`: Registers a callback for whenever any type of paid media
+    is received in messages.
+  - `Bot.onPaidMediaVideo`: Registers a callback for whenever paid media videos
+    are received in messages.
+  - `Bot.onPaidMediaPhoto`: Registers a callback for whenever paid media photos
+    are received in messages.
+- New method `RawAPI.sendPaidMedia` is added to send paid media.
+
 # 1.20.0
 
 - 🥳 Support for Custom Context

README.md

@@ -3,7 +3,7 @@
 
 [![Pub Version](https://img.shields.io/pub/v/televerse?color=blue&logo=blue)](https://pub.dev/packages/televerse)
 ![GitHub](https://img.shields.io/github/license/HeySreelal/televerse?color=green)
-![](https://shields.io/badge/Latest-Bot%20API%207.5-blue)
+![](https://shields.io/badge/Latest-Bot%20API%207.6-blue)
 
 <a href="https://telegram.me/TeleverseDart">
     <img src="https://img.shields.io/badge/Telegram%2F@TeleverseDart-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white"/>
@@ -13,7 +13,7 @@
 
 ---
 
-🤖 `Bot API version: Bot API 7.5 (June 18, 2024)`
+🤖 `Bot API version: Bot API 7.6 (July 1, 2024)`
 
 Televerse is a powerful, easy-to-use, and highly customizable Telegram bot
 framework built with Dart programming language. It provides a complete and
@@ -23,9 +23,20 @@ public interface, making it easy for developers to write strictly typed code.
 
 ## 🔥 What's latest?
 
-### 🗓️ June 28, 2024
+### 🤖 Bot API 7.6
 
-🎉 Support for Custom Contexts!
+(🗓️ July 1, 2024)
+
+In a nutshell, the updates include support for the new Paid Media messages.
+Brings the new `sendPaidMedia` message to send paid media messages. Introduces
+`TransactionPartnerTelegramAds`, new field in `ChatFullInfo`, and more.
+
+Checkout [changelog](https://core.telegram.org/bots/api#july-1-2024) for more
+details! 🚀
+
+### 🎉 Support for Custom Contexts!
+
+(🗓️ June 28, 2024)
 
 Televerse now lets you build even more powerful bots with custom contexts!
 
@@ -39,25 +50,15 @@ constructors to create context objects with personalized behaviors and
 capabilities. This update allows you to tailor your bot's responses, handle
 complex workflows, and integrate additional features seamlessly.
 
-### 🗓️ June 22, 2024
-
-Introducing Middleware & Transformer support! You can now use the `Bot.use`
-method to attach middlewares to your bot. These middlewares will be processed
-before your main handler runs, allowing you to pre-process or even decide
-whether to execute the main handler. Additionally, using a `Transformer` lets
-you directly modify the request payload, reducing redundant code and simplifying
-your coding experience.
+### Introducing Middleware & Transformer support!
 
-### 🗓️ June 18, 2024
+(🗓️ June 22, 2024)
 
-In a nutshell, the updates include new Payment system with
-[Telegram Stars](https://t.me/BotNews/90). Includes a bunch of new models
-related to Star Payments and new method to get Bot's Star Payment history. This
-update also includes support for Business Bots to edit messages as well as
-accept callback and inline queries.
-
-Checkout [changelog](https://core.telegram.org/bots/api#june-18-2024) for more
-details! 🚀
+You can now use the `Bot.use` method to attach middlewares to your bot. These
+middlewares will be processed before your main handler runs, allowing you to
+pre-process or even decide whether to execute the main handler. Additionally,
+using a `Transformer` lets you directly modify the request payload, reducing
+redundant code and simplifying your coding experience.
 
 <hr>
 

lib/src/telegram/models/abstracts/input_paid_media.dart

@@ -0,0 +1,20 @@
+part of '../models.dart';
+
+/// This object describes the paid media to be sent.
+/// Currently, it can be one of [InputPaidMediaPhoto] or [InputPaidMediaVideo].
+sealed class InputPaidMedia {
+  /// Type of the media.
+  InputPaidMediaType get type;
+
+  /// File to send.
+  /// Pass a file_id to send a file that exists on the Telegram servers (recommended),
+  /// pass an HTTP URL for Telegram to get a file from the Internet, or pass “attach://<file_attach_name>”
+  /// to upload a new one using multipart/form-data under <file_attach_name> name.
+  final InputFile media;
+
+  /// Creates a new [InputPaidMedia] object from JSON.
+  const InputPaidMedia(this.media);
+
+  /// Converts an [InputPaidMedia] to a [Map] for JSON encoding.
+  Map<String, dynamic> toJson();
+}

lib/src/telegram/models/abstracts/menu_button.dart

@@ -10,14 +10,11 @@ abstract class MenuButton {
   /// Creates a new [MenuButton] object.
   /// This method decides which [MenuButton] subclass to use based on the [type] field.
   static MenuButton create(Map<String, dynamic> json) {
-    switch (json['type']) {
-      case 'commands':
-        return MenuButtonCommands.fromJson(json);
-      case 'web_app':
-        return MenuButtonWebApp.fromJson(json);
-      default:
-        return MenuButtonDefault.fromJson(json);
-    }
+    return switch (json['type']) {
+      'commands' => MenuButtonCommands.fromJson(json),
+      'web_app' => MenuButtonWebApp.fromJson(json),
+      _ => MenuButtonDefault.fromJson(json),
+    };
   }
 
   /// Creates a new [MenuButton] object.

lib/src/telegram/models/abstracts/paid_media.dart

@@ -0,0 +1,25 @@
+part of '../models.dart';
+
+/// This object describes paid media.
+/// Currently, it can be one of [PaidMediaPreview], [PaidMediaPhoto], [PaidMediaVideo].
+abstract class PaidMedia {
+  /// Type of the paid media.
+  PaidMediaType get type;
+
+  /// Creates a new [PaidMedia] object.
+  /// This method decides which [PaidMedia] subclass to use based on the [type] field.
+  static PaidMedia fromJson(Map<String, dynamic> json) {
+    return switch (json['type']) {
+      'preview' => PaidMediaPreview.fromJson(json),
+      'photo' => PaidMediaPhoto.fromJson(json),
+      'video' => PaidMediaVideo.fromJson(json),
+      _ => throw ArgumentError('Invalid paid media type')
+    };
+  }
+
+  /// Creates a new [PaidMedia] object from JSON.
+  const PaidMedia();
+
+  /// Converts a [PaidMedia] to a [Map] for JSON encoding.
+  Map<String, dynamic> toJson();
+}

lib/src/telegram/models/abstracts/transaction_partner.dart

@@ -13,6 +13,7 @@ abstract class TransactionPartner {
       'fragment' => TransactionPartnerFragment.fromJson(json),
       'user' => TransactionPartnerUser.fromJson(json),
       'other' => TransactionPartnerOther.fromJson(json),
+      'telegram_ads' => TransactionPartnerTelegramAds.fromJson(json),
       _ => throw ArgumentError('Invalid transaction partner type')
     };
   }

lib/src/telegram/models/chat_full_info.dart

@@ -110,6 +110,9 @@ class ChatFullInfo extends Chat implements WithID {
   /// The maximum number of reactions that can be set on a message in the chat
   final int maxReactionCount;
 
+  /// Optional. True, if paid media messages can be sent or forwarded to the channel chat. The field is available only for channel chats.
+  final bool? canSendPaidMedia;
+
   /// Constructs a [Chat] object.
   const ChatFullInfo({
     required super.id,
@@ -155,6 +158,7 @@ class ChatFullInfo extends Chat implements WithID {
     this.personalChat,
     this.birthdate,
     this.maxReactionCount = 0,
+    this.canSendPaidMedia,
   });
 
   /// Creates a [Chat] object from json.
@@ -225,6 +229,7 @@ class ChatFullInfo extends Chat implements WithID {
           ? null
           : Birthdate.fromJson(json['birthdate']),
       maxReactionCount: json["max_reaction_count"],
+      canSendPaidMedia: json["can_send_paid_media"],
     );
   }
 
@@ -277,6 +282,7 @@ class ChatFullInfo extends Chat implements WithID {
       'business_opening_hours': businessOpeningHours?.toJson(),
       'personal_chat': personalChat?.toJson(),
       'birthdate': birthdate?.toJson(),
+      'can_send_paid_media': canSendPaidMedia,
     }..removeWhere(_nullFilter);
   }
 }

lib/src/telegram/models/external_reply_info.dart

@@ -71,6 +71,9 @@ class ExternalReplyInfo {
   /// Optional. Message is a venue, information about the venue
   final Venue? venue;
 
+  /// Optional. Message contains paid media; information about the paid media
+  final PaidMediaInfo? paidMedia;
+
   /// Constructs the [ExternalReplyInfo]
   const ExternalReplyInfo({
     required this.origin,
@@ -96,6 +99,7 @@ class ExternalReplyInfo {
     this.location,
     this.poll,
     this.venue,
+    this.paidMedia,
   });
 
   /// Converts instance of [ExternalReplyInfo] into JSON encodable [Map].
@@ -124,6 +128,7 @@ class ExternalReplyInfo {
       'location': location?.toJson(),
       'poll': poll?.toJson(),
       'venue': venue?.toJson(),
+      'paid_media': paidMedia?.toJson(),
     }..removeWhere(_nullFilter);
   }
 
@@ -169,6 +174,9 @@ class ExternalReplyInfo {
           json['location'] != null ? Location.fromJson(json['location']) : null,
       poll: json['poll'] != null ? Poll.fromJson(json['poll']) : null,
       venue: json['venue'] != null ? Venue.fromJson(json['venue']) : null,
+      paidMedia: json['paid_media'] != null
+          ? PaidMediaInfo.fromJson(json['paid_media'])
+          : null,
     );
   }
 }

lib/src/telegram/models/input_paid_media_photo.dart

@@ -0,0 +1,28 @@
+part of 'models.dart';
+
+/// The paid media to send is a photo.
+class InputPaidMediaPhoto implements InputPaidMedia {
+  @override
+  InputPaidMediaType get type => InputPaidMediaType.photo;
+
+  /// File to send.
+  /// Pass a file_id to send a file that exists on the Telegram servers (recommended),
+  /// pass an HTTP URL for Telegram to get a file from the Internet, or pass “attach://<file_attach_name>”
+  /// to upload a new one using multipart/form-data under <file_attach_name> name.
+  @override
+  final InputFile media;
+
+  /// Constructs a [InputPaidMediaPhoto] object.
+  const InputPaidMediaPhoto({
+    required this.media,
+  });
+
+  /// Converts a [InputPaidMediaPhoto] object to JSON.
+  @override
+  Map<String, dynamic> toJson() {
+    return {
+      'type': type,
+      'media': media.getValue('media'),
+    };
+  }
+}

lib/src/telegram/models/input_paid_media_video.dart

@@ -0,0 +1,53 @@
+part of 'models.dart';
+
+/// The paid media to send is a video.
+class InputPaidMediaVideo implements InputPaidMedia {
+  @override
+  InputPaidMediaType get type => InputPaidMediaType.video;
+
+  /// File to send.
+  /// Pass a file_id to send a file that exists on the Telegram servers (recommended),
+  /// pass an HTTP URL for Telegram to get a file from the Internet, or pass “attach://<file_attach_name>”
+  /// to upload a new one using multipart/form-data under <file_attach_name> name.
+  @override
+  final InputFile media;
+
+  /// Optional. Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side.
+  final InputFile? thumbnail;
+
+  /// Optional. Video width.
+  final int? width;
+
+  /// Optional. Video height.
+  final int? height;
+
+  /// Optional. Video duration in seconds.
+  final int? duration;
+
+  /// Optional. Pass True if the uploaded video is suitable for streaming.
+  final bool? supportsStreaming;
+
+  /// Constructs a [InputPaidMediaVideo] object.
+  const InputPaidMediaVideo({
+    required this.media,
+    this.thumbnail,
+    this.width,
+    this.height,
+    this.duration,
+    this.supportsStreaming,
+  });
+
+  /// Converts a [InputPaidMediaVideo] object to JSON.
+  @override
+  Map<String, dynamic> toJson() {
+    return {
+      'type': type,
+      'media': media.getValue('media'),
+      'thumbnail': thumbnail?.getValue('thumbnail'),
+      'width': width,
+      'height': height,
+      'duration': duration,
+      'supports_streaming': supportsStreaming,
+    }..removeWhere(_nullFilter);
+  }
+}

lib/src/telegram/models/menu_button_web_app.dart

@@ -9,7 +9,9 @@ class MenuButtonWebApp extends MenuButton {
   /// Text on the button
   final String text;
 
-  /// Description of the Web App that will be launched when the user presses the button. The Web App will be able to send an arbitrary message on behalf of the user using the method answerWebAppQuery.
+  /// Description of the Web App that will be launched when the user presses the button. The Web App will be able to send an arbitrary message on behalf of the user using the method `answerWebAppQuery`.
+  ///
+  /// Alternatively, a `t.me` link to a Web App of the bot can be specified in the object instead of the Web App's URL, in which case the Web App will be opened as if the user pressed the link.
   final WebAppInfo webApp;
 
   /// Constructs a [MenuButtonWebApp] object

lib/src/telegram/models/message.dart

@@ -259,6 +259,9 @@ class Message implements MaybeInaccessibleMessage, WithUser {
   /// Optional. True, if the caption must be shown above the message media
   final bool? showCaptionAboveMedia;
 
+  /// Optional. Message contains paid media; information about the paid media
+  final PaidMediaInfo? paidMedia;
+
   /// Creates a Message object.
   const Message({
     this.from,
@@ -344,6 +347,7 @@ class Message implements MaybeInaccessibleMessage, WithUser {
     this.chatBackgroundSet,
     this.effectId,
     this.showCaptionAboveMedia,
+    this.paidMedia,
   });
 
   /// Creates a [Message] object from json map.
@@ -530,6 +534,9 @@ class Message implements MaybeInaccessibleMessage, WithUser {
           : null,
       effectId: json["effect_id"],
       showCaptionAboveMedia: json["show_caption_above_media"],
+      paidMedia: json['paid_media'] != null
+          ? PaidMediaInfo.fromJson(json['paid_media'])
+          : null,
     );
   }
 
@@ -621,6 +628,7 @@ class Message implements MaybeInaccessibleMessage, WithUser {
       'chat_background_set': chatBackgroundSet?.toJson(),
       'effect_id': effectId,
       'show_caption_above_media': showCaptionAboveMedia,
+      'paid_media': paidMedia?.toJson(),
     }..removeWhere(_nullFilter);
   }
 

lib/src/telegram/models/models.dart

@@ -254,3 +254,14 @@ part 'abstracts/revenue_withdrawal_state.dart';
 part 'revenue_withdrawal_state_pending.dart';
 part 'revenue_withdrawal_state_succeeded.dart';
 part 'revenue_withdrawal_state_failed.dart';
+
+// Bot API 7.6
+part 'abstracts/paid_media.dart';
+part 'paid_media_video.dart';
+part 'paid_media_photo.dart';
+part 'paid_media_preview.dart';
+part 'paid_media_info.dart';
+part 'abstracts/input_paid_media.dart';
+part 'input_paid_media_photo.dart';
+part 'input_paid_media_video.dart';
+part 'transaction_partner_telegram_ads.dart';