Telegram Bot API December 4, 2024 updates (v8.1)

Author: johnspade

README.md

@@ -1,6 +1,6 @@
 # F[Tg] - Telegramium
 
-[![Telegram](https://img.shields.io/badge/Telegram%20Bot%20API-8.0%20(October%2031%2C%202024)-blue)](https://core.telegram.org/bots/api#recent-changes)
+[![Telegram](https://img.shields.io/badge/Telegram%20Bot%20API-8.1%20(December%204%2C%202024)-blue)](https://core.telegram.org/bots/api#recent-changes)
 [![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.github.apimorphism/telegramium-core_3/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.github.apimorphism/telegramium-core_3)
 
 

build.sbt

@@ -1,7 +1,7 @@
 enablePlugins(GitPlugin)
 
 ThisBuild / version := Version.mkVersion(
-  "9.800.0",
+  "9.801.0",
   git.gitCurrentBranch.value,
   git.gitDescribedVersion.value,
   git.gitUncommittedChanges.value

telegramium-core/src/main/scala/telegramium/bots/AffiliateInfo.scala

@@ -0,0 +1,25 @@
+package telegramium.bots
+
+/** Contains information about the affiliate that received a commission via this transaction.
+  *
+  * @param commissionPerMille
+  *   The number of Telegram Stars received by the affiliate for each 1000 Telegram Stars received by the bot from
+  *   referred users
+  * @param amount
+  *   Integer amount of Telegram Stars received by the affiliate from the transaction, rounded to 0; can be negative for
+  *   refunds
+  * @param affiliateUser
+  *   Optional. The bot or the user that received an affiliate commission if it was received by a bot or a user
+  * @param affiliateChat
+  *   Optional. The chat that received an affiliate commission if it was received by a chat
+  * @param nanostarAmount
+  *   Optional. The number of 1/1000000000 shares of Telegram Stars received by the affiliate; from -999999999 to
+  *   999999999; can be negative for refunds
+  */
+final case class AffiliateInfo(
+  commissionPerMille: Int,
+  amount: Int,
+  affiliateUser: Option[User] = Option.empty,
+  affiliateChat: Option[Chat] = Option.empty,
+  nanostarAmount: Option[Int] = Option.empty
+)

telegramium-core/src/main/scala/telegramium/bots/StarTransaction.scala

@@ -7,9 +7,11 @@ package telegramium.bots
   *   transactions. Coincides with SuccessfulPayment.telegram_payment_charge_id for successful incoming payments from
   *   users.
   * @param amount
-  *   Number of Telegram Stars transferred by the transaction
+  *   Integer amount of Telegram Stars transferred by the transaction
   * @param date
   *   Date the transaction was created in Unix time
+  * @param nanostarAmount
+  *   Optional. The number of 1/1000000000 shares of Telegram Stars transferred by the transaction; from 0 to 999999999
   * @param source
   *   Optional. Source of an incoming transaction (e.g., a user purchasing goods or services, Fragment refunding a
   *   failed withdrawal). Only for incoming transactions
@@ -21,6 +23,7 @@ final case class StarTransaction(
   id: String,
   amount: Int,
   date: Int,
+  nanostarAmount: Option[Int] = Option.empty,
   source: Option[iozhik.OpenEnum[TransactionPartner]] = Option.empty,
   receiver: Option[iozhik.OpenEnum[TransactionPartner]] = Option.empty
 )

telegramium-core/src/main/scala/telegramium/bots/TransactionPartner.scala

@@ -2,6 +2,17 @@ package telegramium.bots
 
 sealed trait TransactionPartner {}
 
+/** Describes the affiliate program that issued the affiliate commission received via this transaction.
+  *
+  * @param commissionPerMille
+  *   The number of Telegram Stars received by the bot for each 1000 Telegram Stars received by the affiliate program
+  *   sponsor from referred users
+  * @param sponsorUser
+  *   Optional. Information about the bot that sponsored the affiliate program
+  */
+final case class TransactionPartnerAffiliateProgram(commissionPerMille: Int, sponsorUser: Option[User] = Option.empty)
+    extends TransactionPartner
+
 /** Describes a transaction with an unknown source or recipient. */
 case object TransactionPartnerOther extends TransactionPartner
 
@@ -12,6 +23,8 @@ case object TransactionPartnerTelegramAds extends TransactionPartner
   *
   * @param user
   *   Information about the user
+  * @param affiliate
+  *   Optional. Information about the affiliate that received a commission via this transaction
   * @param invoicePayload
   *   Optional. Bot-specified invoice payload
   * @param subscriptionPeriod
@@ -25,6 +38,7 @@ case object TransactionPartnerTelegramAds extends TransactionPartner
   */
 final case class TransactionPartnerUser(
   user: User,
+  affiliate: Option[AffiliateInfo] = Option.empty,
   invoicePayload: Option[String] = Option.empty,
   subscriptionPeriod: Option[Int] = Option.empty,
   paidMedia: List[iozhik.OpenEnum[PaidMedia]] = List.empty,

telegramium-core/src/main/scala/telegramium/bots/client/CreateInvoiceLinkReq.scala

@@ -23,7 +23,7 @@ import telegramium.bots.LabeledPrice
   *   The number of seconds the subscription will be active for before the next payment. The currency must be set to
   *   “XTR” (Telegram Stars) if the parameter is used. Currently, it must always be 2592000 (30 days) if specified. Any
   *   number of subscriptions can be active for a given bot at the same time, including multiple concurrent
-  *   subscriptions from the same user.
+  *   subscriptions from the same user. Subscription price must no exceed 2500 Telegram Stars.
   * @param maxTipAmount
   *   The maximum accepted amount for tips in the smallest units of the currency (integer, not float/double). For
   *   example, for a maximum tip of US$ 1.45 pass max_tip_amount = 145. See the exp parameter in currencies.json, it

telegramium-core/src/main/scala/telegramium/bots/client/Methods.scala

@@ -493,7 +493,7 @@ trait Methods {
     *   The number of seconds the subscription will be active for before the next payment. The currency must be set to
     *   “XTR” (Telegram Stars) if the parameter is used. Currently, it must always be 2592000 (30 days) if specified.
     *   Any number of subscriptions can be active for a given bot at the same time, including multiple concurrent
-    *   subscriptions from the same user.
+    *   subscriptions from the same user. Subscription price must no exceed 2500 Telegram Stars.
     * @param maxTipAmount
     *   The maximum accepted amount for tips in the smallest units of the currency (integer, not float/double). For
     *   example, for a maximum tip of US$ 1.45 pass max_tip_amount = 145. See the exp parameter in currencies.json, it

telegramium-core/src/main/scala/telegramium/bots/package.scala

@@ -3725,22 +3725,45 @@ object CirceImplicits {
       telegram_ads.asJson.mapObject(_.add("type", Json.fromString("telegram_ads")))
     case telegram_api: TransactionPartnerTelegramApi =>
       telegram_api.asJson.mapObject(_.add("type", Json.fromString("telegram_api")))
+    case affiliate_program: TransactionPartnerAffiliateProgram =>
+      affiliate_program.asJson.mapObject(_.add("type", Json.fromString("affiliate_program")))
     case user: TransactionPartnerUser        => user.asJson.mapObject(_.add("type", Json.fromString("user")))
     case other: TransactionPartnerOther.type => other.asJson.mapObject(_.add("type", Json.fromString("other")))
   }
 
   implicit lazy val transactionpartnerDecoder: Decoder[iozhik.OpenEnum[TransactionPartner]] = for {
     fType <- Decoder[String].prepare(_.downField("type"))
     value <- fType match {
-      case "fragment"     => Decoder[TransactionPartnerFragment].map(iozhik.OpenEnum.Known(_))
-      case "telegram_ads" => Decoder[TransactionPartnerTelegramAds.type].map(iozhik.OpenEnum.Known(_))
-      case "telegram_api" => Decoder[TransactionPartnerTelegramApi].map(iozhik.OpenEnum.Known(_))
-      case "user"         => Decoder[TransactionPartnerUser].map(iozhik.OpenEnum.Known(_))
-      case "other"        => Decoder[TransactionPartnerOther.type].map(iozhik.OpenEnum.Known(_))
-      case unknown        => Decoder.const(iozhik.OpenEnum.Unknown[TransactionPartner](unknown))
+      case "fragment"          => Decoder[TransactionPartnerFragment].map(iozhik.OpenEnum.Known(_))
+      case "telegram_ads"      => Decoder[TransactionPartnerTelegramAds.type].map(iozhik.OpenEnum.Known(_))
+      case "telegram_api"      => Decoder[TransactionPartnerTelegramApi].map(iozhik.OpenEnum.Known(_))
+      case "affiliate_program" => Decoder[TransactionPartnerAffiliateProgram].map(iozhik.OpenEnum.Known(_))
+      case "user"              => Decoder[TransactionPartnerUser].map(iozhik.OpenEnum.Known(_))
+      case "other"             => Decoder[TransactionPartnerOther.type].map(iozhik.OpenEnum.Known(_))
+      case unknown             => Decoder.const(iozhik.OpenEnum.Unknown[TransactionPartner](unknown))
     }
   } yield value
 
+  implicit lazy val transactionpartneraffiliateprogramEncoder: Encoder[TransactionPartnerAffiliateProgram] =
+    (x: TransactionPartnerAffiliateProgram) => {
+      Json.fromFields(
+        List(
+          "sponsor_user"         -> x.sponsorUser.asJson,
+          "commission_per_mille" -> x.commissionPerMille.asJson
+        ).filter(!_._2.isNull)
+      )
+    }
+
+  implicit lazy val transactionpartneraffiliateprogramDecoder: Decoder[TransactionPartnerAffiliateProgram] =
+    Decoder.instance { h =>
+      for {
+        _sponsorUser        <- h.get[Option[User]]("sponsor_user")
+        _commissionPerMille <- h.get[Int]("commission_per_mille")
+      } yield {
+        TransactionPartnerAffiliateProgram(sponsorUser = _sponsorUser, commissionPerMille = _commissionPerMille)
+      }
+    }
+
   implicit lazy val transactionpartnerotherEncoder: Encoder[TransactionPartnerOther.type] =
     (_: TransactionPartnerOther.type) => ().asJson
 
@@ -3758,6 +3781,7 @@ object CirceImplicits {
       Json.fromFields(
         List(
           "user"                -> x.user.asJson,
+          "affiliate"           -> x.affiliate.asJson,
           "invoice_payload"     -> x.invoicePayload.asJson,
           "subscription_period" -> x.subscriptionPeriod.asJson,
           "paid_media"          -> x.paidMedia.asJson,
@@ -3771,6 +3795,7 @@ object CirceImplicits {
     Decoder.instance { h =>
       for {
         _user               <- h.get[User]("user")
+        _affiliate          <- h.get[Option[AffiliateInfo]]("affiliate")
         _invoicePayload     <- h.get[Option[String]]("invoice_payload")
         _subscriptionPeriod <- h.get[Option[Int]]("subscription_period")
         _paidMedia          <- h.getOrElse[List[iozhik.OpenEnum[PaidMedia]]]("paid_media")(List.empty)
@@ -3779,6 +3804,7 @@ object CirceImplicits {
       } yield {
         TransactionPartnerUser(
           user = _user,
+          affiliate = _affiliate,
           invoicePayload = _invoicePayload,
           subscriptionPeriod = _subscriptionPeriod,
           paidMedia = _paidMedia,
@@ -3824,6 +3850,38 @@ object CirceImplicits {
       }
     }
 
+  implicit lazy val affiliateinfoEncoder: Encoder[AffiliateInfo] =
+    (x: AffiliateInfo) => {
+      Json.fromFields(
+        List(
+          "affiliate_user"       -> x.affiliateUser.asJson,
+          "affiliate_chat"       -> x.affiliateChat.asJson,
+          "commission_per_mille" -> x.commissionPerMille.asJson,
+          "amount"               -> x.amount.asJson,
+          "nanostar_amount"      -> x.nanostarAmount.asJson
+        ).filter(!_._2.isNull)
+      )
+    }
+
+  implicit lazy val affiliateinfoDecoder: Decoder[AffiliateInfo] =
+    Decoder.instance { h =>
+      for {
+        _affiliateUser      <- h.get[Option[User]]("affiliate_user")
+        _affiliateChat      <- h.get[Option[Chat]]("affiliate_chat")
+        _commissionPerMille <- h.get[Int]("commission_per_mille")
+        _amount             <- h.get[Int]("amount")
+        _nanostarAmount     <- h.get[Option[Int]]("nanostar_amount")
+      } yield {
+        AffiliateInfo(
+          affiliateUser = _affiliateUser,
+          affiliateChat = _affiliateChat,
+          commissionPerMille = _commissionPerMille,
+          amount = _amount,
+          nanostarAmount = _nanostarAmount
+        )
+      }
+    }
+
   implicit lazy val animationEncoder: Encoder[Animation] =
     (x: Animation) => {
       Json.fromFields(
@@ -6605,25 +6663,34 @@ object CirceImplicits {
     (x: StarTransaction) => {
       Json.fromFields(
         List(
-          "id"       -> x.id.asJson,
-          "amount"   -> x.amount.asJson,
-          "date"     -> x.date.asJson,
-          "source"   -> x.source.asJson,
-          "receiver" -> x.receiver.asJson
+          "id"              -> x.id.asJson,
+          "amount"          -> x.amount.asJson,
+          "nanostar_amount" -> x.nanostarAmount.asJson,
+          "date"            -> x.date.asJson,
+          "source"          -> x.source.asJson,
+          "receiver"        -> x.receiver.asJson
         ).filter(!_._2.isNull)
       )
     }
 
   implicit lazy val startransactionDecoder: Decoder[StarTransaction] =
     Decoder.instance { h =>
       for {
-        _id       <- h.get[String]("id")
-        _amount   <- h.get[Int]("amount")
-        _date     <- h.get[Int]("date")
-        _source   <- h.get[Option[iozhik.OpenEnum[TransactionPartner]]]("source")
-        _receiver <- h.get[Option[iozhik.OpenEnum[TransactionPartner]]]("receiver")
+        _id             <- h.get[String]("id")
+        _amount         <- h.get[Int]("amount")
+        _nanostarAmount <- h.get[Option[Int]]("nanostar_amount")
+        _date           <- h.get[Int]("date")
+        _source         <- h.get[Option[iozhik.OpenEnum[TransactionPartner]]]("source")
+        _receiver       <- h.get[Option[iozhik.OpenEnum[TransactionPartner]]]("receiver")
       } yield {
-        StarTransaction(id = _id, amount = _amount, date = _date, source = _source, receiver = _receiver)
+        StarTransaction(
+          id = _id,
+          amount = _amount,
+          nanostarAmount = _nanostarAmount,
+          date = _date,
+          source = _source,
+          receiver = _receiver
+        )
       }
     }