feat: Add Layer 189 API support and native StarGift event integration

- Add getUserStarGifts API definition and related types in api.tl
- Extend ChatAction event to natively support all StarGift MessageAction types
- Support MessageActionGiftStars, MessageActionPrizeStars, and 2 other StarGift actions
- Add rich event attributes including stars amount, gift objects, and save status
- Enable complete StarGift service message monitoring and query functionality

telethon/events/chataction.py

@@ -15,6 +15,7 @@ class ChatAction(EventBuilder):
     * Whenever a user joins or is added to the group.
     * Whenever a user is removed or leaves a group if it has
       less than 50 members or the removed user was a bot.
+    * Whenever a StarGift is sent or received.
 
     Note that "chat" refers to "small group, megagroup and broadcast
     channel", whereas "group" refers to "small group and megagroup" only.
@@ -29,6 +30,10 @@ class ChatAction(EventBuilder):
                 # Welcome every new user
                 if event.user_joined:
                     await event.reply('Welcome to the group!')
+                
+                # Handle StarGift events
+                if event.star_gift:
+                    await event.reply(f'A StarGift was sent!')
     """
 
     @classmethod
@@ -107,6 +112,38 @@ class ChatAction(EventBuilder):
             elif isinstance(action, types.MessageActionGameScore):
                 return cls.Event(msg,
                                  new_score=action.score)
+            # StarGift related actions
+            elif isinstance(action, types.MessageActionGiftStars):
+                return cls.Event(msg,
+                                 users=msg.from_id,
+                                 star_gift_action='gift_stars',
+                                 stars_amount=action.stars,
+                                 star_gift_crypto_currency=getattr(action, 'crypto_currency', None),
+                                 star_gift_crypto_amount=getattr(action, 'crypto_amount', None))
+            elif isinstance(action, types.MessageActionPrizeStars):
+                return cls.Event(msg,
+                                 users=msg.from_id,
+                                 star_gift_action='prize_stars',
+                                 stars_amount=action.stars,
+                                 star_gift_unclaimed=getattr(action, 'unclaimed', False),
+                                 star_gift_boost_peer=getattr(action, 'boost_peer', None))
+            elif isinstance(action, types.MessageActionStarGift):
+                return cls.Event(msg,
+                                 users=msg.from_id,
+                                 star_gift_action='star_gift',
+                                 star_gift_object=action.gift,
+                                 star_gift_saved=getattr(action, 'saved', False),
+                                 star_gift_message=getattr(action, 'message', None),
+                                 star_gift_convert_stars=getattr(action, 'convert_stars', None))
+            elif isinstance(action, types.MessageActionStarGiftUnique):
+                return cls.Event(msg,
+                                 users=msg.from_id,
+                                 star_gift_action='star_gift_unique',
+                                 star_gift_object=action.gift,
+                                 star_gift_saved=getattr(action, 'saved', False),
+                                 star_gift_message=getattr(action, 'message', None),
+                                 star_gift_convert_stars=getattr(action, 'convert_stars', None),
+                                 star_gift_upgrade_stars=getattr(action, 'upgrade_stars', None))
 
         elif isinstance(update, types.UpdateChannelParticipant) \
                 and bool(update.new_participant) != bool(update.prev_participant):
@@ -159,11 +196,51 @@ class ChatAction(EventBuilder):
 
             unpin (`bool`):
                 `True` if the existing pin gets unpinned.
+
+            star_gift (`bool`):
+                `True` if this is a StarGift related action.
+
+            star_gift_action (`str`, optional):
+                The type of StarGift action: 'gift_stars', 'prize_stars', 'star_gift', or 'star_gift_unique'.
+
+            stars_amount (`int`, optional):
+                The amount of stars involved in the gift (for gift_stars and prize_stars).
+
+            star_gift_object (optional):
+                The StarGift object (for star_gift and star_gift_unique actions).
+
+            star_gift_saved (`bool`, optional):
+                Whether the StarGift was saved (for star_gift and star_gift_unique actions).
+
+            star_gift_message (optional):
+                Message accompanying the StarGift (for star_gift and star_gift_unique actions).
+
+            star_gift_convert_stars (`int`, optional):
+                Amount of stars the gift can be converted to.
+
+            star_gift_upgrade_stars (`int`, optional):
+                Amount of stars needed to upgrade (for star_gift_unique only).
+
+            star_gift_crypto_currency (`str`, optional):
+                Cryptocurrency used (for gift_stars only).
+
+            star_gift_crypto_amount (`int`, optional):
+                Amount of cryptocurrency (for gift_stars only).
+
+            star_gift_unclaimed (`bool`, optional):
+                Whether the prize is unclaimed (for prize_stars only).
+
+            star_gift_boost_peer (optional):
+                Boost peer information (for prize_stars only).
         """
 
         def __init__(self, where, new_photo=None,
                      added_by=None, kicked_by=None, created=None,
-                     users=None, new_title=None, pin_ids=None, pin=None, new_score=None):
+                     users=None, new_title=None, pin_ids=None, pin=None, new_score=None,
+                     star_gift_action=None, stars_amount=None, star_gift_object=None,
+                     star_gift_saved=None, star_gift_message=None, star_gift_convert_stars=None,
+                     star_gift_upgrade_stars=None, star_gift_crypto_currency=None,
+                     star_gift_crypto_amount=None, star_gift_unclaimed=None, star_gift_boost_peer=None):
             if isinstance(where, types.MessageService):
                 self.action_message = where
                 where = where.peer_id
@@ -216,6 +293,20 @@ class ChatAction(EventBuilder):
             self.new_score = new_score
             self.unpin = not pin
 
+            # StarGift related attributes
+            self.star_gift = star_gift_action is not None
+            self.star_gift_action = star_gift_action
+            self.stars_amount = stars_amount
+            self.star_gift_object = star_gift_object
+            self.star_gift_saved = star_gift_saved
+            self.star_gift_message = star_gift_message
+            self.star_gift_convert_stars = star_gift_convert_stars
+            self.star_gift_upgrade_stars = star_gift_upgrade_stars
+            self.star_gift_crypto_currency = star_gift_crypto_currency
+            self.star_gift_crypto_amount = star_gift_crypto_amount
+            self.star_gift_unclaimed = star_gift_unclaimed
+            self.star_gift_boost_peer = star_gift_boost_peer
+
         def _set_client(self, client):
             super()._set_client(client)
             if self.action_message:

telethon_generator/data/api.tl

@@ -1899,6 +1899,10 @@ starGiftUnique#6411db89 flags:# id:long title:string slug:string num:int owner_i
 payments.starGiftsNotModified#a388a368 = payments.StarGifts;
 payments.starGifts#901689ea hash:int gifts:Vector<StarGift> = payments.StarGifts;
 
+userStarGift#eea49a6e flags:# name_hidden:flags.0?true unsaved:flags.5?true from_id:flags.1?long date:int gift:StarGift message:flags.2?TextWithEntities msg_id:flags.3?int convert_stars:flags.4?long = UserStarGift;
+
+payments.userStarGifts#6b65b517 flags:# count:int gifts:Vector<UserStarGift> next_offset:flags.0?string users:Vector<User> = payments.UserStarGifts;
+
 messageReportOption#7903e3d9 text:string option:bytes = MessageReportOption;
 
 reportResultChooseOption#f0e4e0b6 title:string options:Vector<MessageReportOption> = ReportResult;
@@ -2569,6 +2573,7 @@ payments.changeStarsSubscription#c7770878 flags:# peer:InputPeer subscription_id
 payments.fulfillStarsSubscription#cc5bebb3 peer:InputPeer subscription_id:string = Bool;
 payments.getStarsGiveawayOptions#bd1efd3e = Vector<StarsGiveawayOption>;
 payments.getStarGifts#c4563590 hash:int = payments.StarGifts;
+payments.getUserStarGifts#5e72c7e1 user_id:InputUser offset:string limit:int = payments.UserStarGifts;
 payments.saveStarGift#2a2a697c flags:# unsave:flags.0?true stargift:InputSavedStarGift = Bool;
 payments.convertStarGift#74bf076b stargift:InputSavedStarGift = Bool;
 payments.botCancelStarsSubscription#6dfa0622 flags:# restore:flags.0?true user_id:InputUser charge_id:string = Bool;