🤖 Merge #312: Bot API 8.1

CHANGELOG.md

@@ -1,3 +1,8 @@
+# 2.1.0
+
+- 🤖 Bot API 8.1
+- Added class `AffiliateInfo` and reflected all the changes from Bot API 8.1
+
 # 2.0.2
 
 - 🆕 Supports Middleware chaining for each handler.

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/xooniverse/televerse?color=green)
-![](https://shields.io/badge/Latest-Bot%20API%208.0-blue)
+![](https://shields.io/badge/Latest-Bot%20API%208.1-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"/>
@@ -12,7 +12,7 @@
 
 ---
 
-🤖 `Bot API version: Bot API 8.0 (November 17, 2024)` 🎃
+🤖 `Bot API version: Bot API 8.1 (December 4, 2024)` 🎃
 
 Televerse is a powerful, easy-to-use, and highly customizable Telegram bot
 framework built with Dart programming language. It provides a complete and
@@ -22,32 +22,15 @@ public interface, making it easy for developers to write strictly typed code.
 
 ## 🔥 What's latest?
 
-### 🤖 Bot API 8.0 🎃
+### 🤖 Bot API 8.1 🎃
 
-(🗓️ November 17, 2024)
+(🗓️ December 4, 2024)
 
-In a nutshell, this update majorly is about Telegram Mini Apps, though we have a few new methods for Bot API including `editUserStarSubscription`, `getAvailableGifts` etc. Being said that, now Bots can send Gifts to the user. 🎁
+In a nutshell, Bots can now detect commissions and affiliate transactions!
 
-Checkout [changelog](https://core.telegram.org/bots/api-changelog#november-17-2024) for more
+Checkout [changelog](https://core.telegram.org/bots/api-changelog#december-4-2024) for more
 details! 🚀
 
-### 🎉 Support for Custom Contexts!
-
-(🗓️ June 28, 2024)
-
-Televerse now lets you build even more powerful bots with custom contexts!
-
-- Design custom context classes to store information specific to your bot's
-  needs.
-- Keep your bot's logic organized with private context members and methods.
-- Add features like localization by integrating mixins.
-
-With the new `Bot.contextBuilder` method, you can define specialized context
-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. 
-[Read more here.](https://televerse.xooniverse.com/advanced/custom-context.html)
-
 <hr>
 
 ## 💻 Getting Started

lib/src/telegram/models/affiliate_info.dart

@@ -0,0 +1,59 @@
+part of 'models.dart';
+
+/// Contains information about the affiliate that received a commission
+/// via this transaction.
+class AffiliateInfo {
+  /// The bot or the user that received an affiliate commission if it was
+  /// received by a bot or a user.
+  final User? affiliateUser;
+
+  /// The chat that received an affiliate commission if it was received by a chat.
+  final Chat? affiliateChat;
+
+  /// The number of Telegram Stars received by the affiliate for each 1000
+  /// Telegram Stars received by the bot from referred users.
+  final int commissionPerMille;
+
+  /// Integer amount of Telegram Stars received by the affiliate from the transaction,
+  /// rounded to 0; can be negative for refunds.
+  final int amount;
+
+  /// The number of 1/1000000000 shares of Telegram Stars received by the affiliate;
+  /// from -999999999 to 999999999; can be negative for refunds.
+  final int? nanostarAmount;
+
+  /// Constructs an [AffiliateInfo] object.
+  const AffiliateInfo({
+    this.affiliateUser,
+    this.affiliateChat,
+    required this.commissionPerMille,
+    required this.amount,
+    this.nanostarAmount,
+  });
+
+  /// Creates an [AffiliateInfo] object from JSON.
+  factory AffiliateInfo.fromJson(Map<String, dynamic> json) {
+    return AffiliateInfo(
+      affiliateUser: json['affiliate_user'] != null
+          ? User.fromJson(json['affiliate_user'])
+          : null,
+      affiliateChat: json['affiliate_chat'] != null
+          ? Chat.fromJson(json['affiliate_chat'])
+          : null,
+      commissionPerMille: json['commission_per_mille'],
+      amount: json['amount'],
+      nanostarAmount: json['nanostar_amount'],
+    );
+  }
+
+  /// Converts an [AffiliateInfo] object to JSON.
+  Map<String, dynamic> toJson() {
+    return {
+      'affiliate_user': affiliateUser?.toJson(),
+      'affiliate_chat': affiliateChat?.toJson(),
+      'commission_per_mille': commissionPerMille,
+      'amount': amount,
+      'nanostar_amount': nanostarAmount,
+    }..removeWhere(_nullFilter);
+  }
+}

lib/src/telegram/models/models.dart

@@ -283,3 +283,7 @@ part 'transaction_partner_telegram_api.dart';
 part 'prepared_inline_message.dart';
 part 'gift.dart';
 part 'gifts.dart';
+
+// Bot API 8.1
+part 'transaction_partner_affiliate_program.dart';
+part 'affiliate_info.dart';

lib/src/telegram/models/star_transaction.dart

@@ -21,10 +21,14 @@ class StarTransaction {
   /// Fragment for a withdrawal). Only for outgoing transactions.
   final TransactionPartner? receiver;
 
+  /// Optional. The number of 1/1000000000 shares of Telegram Stars transferred by the transaction; from 0 to 999999999
+  final int nanostarAmount;
+
   /// Creates a new [StarTransaction] object.
   const StarTransaction({
     required this.id,
     required this.amount,
+    required this.nanostarAmount,
     required this.date,
     this.source,
     this.receiver,
@@ -42,6 +46,7 @@ class StarTransaction {
       receiver: json['receiver'] != null
           ? TransactionPartner.fromJson(json['receiver'])
           : null,
+      nanostarAmount: json['nanostar_amount'] as int,
     );
   }
 

lib/src/telegram/models/transaction_partner_affiliate_program.dart

@@ -0,0 +1,43 @@
+part of 'models.dart';
+
+/// Describes the affiliate program that issued the affiliate commission
+/// received via this transaction.
+class TransactionPartnerAffiliateProgram extends TransactionPartner {
+  @override
+  TransactionPartnerType get type => TransactionPartnerType.affiliateProgram;
+
+  /// Information about the bot that sponsored the affiliate program.
+  final User? sponsorUser;
+
+  /// The number of Telegram Stars received by the bot for each 1000 Telegram
+  /// Stars received by the affiliate program sponsor from referred users.
+  final int commissionPerMille;
+
+  /// Constructs a [TransactionPartnerAffiliateProgram] object.
+  const TransactionPartnerAffiliateProgram({
+    this.sponsorUser,
+    required this.commissionPerMille,
+  });
+
+  /// Creates a [TransactionPartnerAffiliateProgram] object from JSON.
+  factory TransactionPartnerAffiliateProgram.fromJson(
+    Map<String, dynamic> json,
+  ) {
+    return TransactionPartnerAffiliateProgram(
+      sponsorUser: json['sponsor_user'] != null
+          ? User.fromJson(json['sponsor_user'])
+          : null,
+      commissionPerMille: json['commission_per_mille'],
+    );
+  }
+
+  /// Converts a [TransactionPartnerAffiliateProgram] object to JSON.
+  @override
+  Map<String, dynamic> toJson() {
+    return {
+      'type': type.value,
+      'sponsor_user': sponsorUser?.toJson(),
+      'commission_per_mille': commissionPerMille,
+    };
+  }
+}

lib/src/telegram/models/transaction_partner_user.dart

@@ -23,6 +23,9 @@ class TransactionPartnerUser extends TransactionPartner {
   /// Optional. The gift sent to the user by the bot.
   final Gift? gift;
 
+  /// Optional. Information about the affiliate that received a commission via this transaction
+  final AffiliateInfo? affiliate;
+
   /// Constructs a [TransactionPartnerUser] object.
   const TransactionPartnerUser({
     required this.user,
@@ -31,6 +34,7 @@ class TransactionPartnerUser extends TransactionPartner {
     this.paidMediaPayload,
     this.subscriptionPeriod,
     this.gift,
+    this.affiliate,
   });
 
   /// Creates a [TransactionPartnerUser] object from JSON.
@@ -48,6 +52,9 @@ class TransactionPartnerUser extends TransactionPartner {
       paidMediaPayload: json['paid_media_payload'],
       subscriptionPeriod: json['subscription_period'],
       gift: json['gift'] != null ? Gift.fromJson(json['gift']) : null,
+      affiliate: json['affiliate'] != null
+          ? AffiliateInfo.fromJson(json['affiliate'])
+          : null,
     );
   }
 
@@ -62,6 +69,7 @@ class TransactionPartnerUser extends TransactionPartner {
       'paid_media_payload': paidMediaPayload,
       'subscription_period': subscriptionPeriod,
       'gift': gift?.toJson(),
+      'affiliate': affiliate?.toJson(),
     }..removeWhere(_nullFilter);
   }
 }

lib/src/types/transaction_partner_type.dart

@@ -16,6 +16,9 @@ enum TransactionPartnerType {
 
   /// Represents a transaction with an unknown source or recipient.
   other("other"),
+
+  /// Describes the affiliate program that issued the affiliate commission received via this transaction
+  affiliateProgram("affiliate_program"),
   ;
 
   /// The value of this enum.

pubspec.yaml

@@ -1,6 +1,6 @@
 name: televerse
-description: Televerse lets you create your own efficient Telegram bots with ease in Dart. Supports latest Telegram Bot API - 8.0!
-version: 2.0.2
+description: Televerse lets you create your own efficient Telegram bots with ease in Dart. Supports latest Telegram Bot API - 8.1!
+version: 2.1.0
 homepage: https://televerse.xooniverse.com
 repository: https://github.com/xooniverse/televerse
 topics: