Add Bits Use model and docs

Author: chillymosh

docs/references/events.rst

@@ -44,6 +44,10 @@ Events Reference
      - :meth:`~eventsub.AdBreakBeginSubscription`
      - :func:`~twitchio.event_ad_break()`
      - :class:`~models.eventsub_.ChannelAdBreakBegin`
+   * - Channel Bits Use
+     - :meth:`~eventsub.ChannelBitsUseSubscription`
+     - :func:`~twitchio.event_bits_use()`
+     - :class:`~models.eventsub_.ChannelBitsUse`
    * - Channel Chat Clear
      - :meth:`~eventsub.ChatClearSubscription`
      - :func:`~twitchio.event_chat_clear()`
@@ -785,6 +789,18 @@ Chat / Messages
 
   :param twitchio.Whisper payload: The EventSub payload for this event.
 
+.. py:function:: event_bits_use(payload: twitchio.ChannelBitsUse) -> None
+  :async:
+
+  Event dispatched whenever Bits are used on a channel.
+    
+  Corresponds to the Twitch EventSub subscription :es-docs:`Channel Bits Use <channelbitsuse>`.
+    
+  You must subscribe to EventSub with :class:`~twitchio.eventsub.ChannelBitsUseSubscription` for each required user
+  to receive this event.
+
+  :param twitchio.ChannelBitsUse payload: The EventSub payload for this event.
+
 Goals
 -----
 

docs/references/eventsub_models.rst

@@ -48,6 +48,11 @@ Eventsub
 .. autoclass:: twitchio.ChannelAdBreakBegin()
     :members:
 
+.. attributetable:: twitchio.ChannelBitsUse
+
+.. autoclass:: twitchio.ChannelBitsUse()
+    :members:
+
 .. attributetable:: twitchio.ChannelChatClear
 
 .. autoclass:: twitchio.ChannelChatClear()
@@ -476,6 +481,16 @@ Eventsub
 .. autoclass:: twitchio.HypeTrainEnd()
     :members:
 
+.. attributetable:: twitchio.PowerUp
+
+.. autoclass:: twitchio.PowerUp()
+    :members:
+
+.. attributetable:: twitchio.PowerUpEmote
+
+.. autoclass:: twitchio.PowerUpEmote()
+    :members:
+
 .. attributetable:: twitchio.ShieldModeBegin
 
 .. autoclass:: twitchio.ShieldModeBegin()

twitchio/events.pyi

@@ -65,6 +65,7 @@ async def event_chat_clear_user(payload: twitchio.ChannelChatClearUserMessages)
 async def event_chat_settings_update(payload: twitchio.ChatSettingsUpdate) -> None: ...
 async def event_chat_user_message_hold(payload: twitchio.ChatUserMessageHold) -> None: ...
 async def event_chat_user_message_update(payload: twitchio.ChatUserMessageUpdate) -> None: ...
+async def event_bits_use(payload: twitchio.ChannelBitsUse) -> None: ...
 
 # Shared Chat
 async def event_shared_chat_begin(payload: twitchio.SharedChatSessionBegin) -> None: ...

twitchio/models/eventsub_.py

@@ -74,6 +74,7 @@
     "Boundary",
     "ChannelAdBreakBegin",
     "ChannelBan",
+    "ChannelBitsUse",
     "ChannelChatClear",
     "ChannelChatClearUserMessages",
     "ChannelCheer",
@@ -156,6 +157,8 @@
     "ModerateUnbanRequest",
     "ModerateWarn",
     "PollVoting",
+    "PowerUp",
+    "PowerUpEmote",
     "SharedChatSessionBegin",
     "SharedChatSessionEnd",
     "SharedChatSessionUpdate",
@@ -719,6 +722,97 @@ def __repr__(self) -> str:
         return f"<AutomodTermsUpdate broadcaster={self.broadcaster} moderator={self.moderator} action={self.action} automod={self.automod}>"
 
 
+class PowerUpEmote:
+    """
+    Represents a PowerUp Emote on a channel bits use event.
+
+    Attributes
+    ----------
+    id: str
+        The ID that uniquely identifies this emote.
+    name: str
+        The human readable emote token.
+    """
+
+    __slots__ = ("id", "name")
+
+    def __init__(self, data: PowerUpEmoteDataData) -> None:
+        self.id: str = data["id"]
+        self.name: str = data["name"]
+
+
+class PowerUp:
+    """
+    Represents a PowerUp on a channel bits use event.
+
+    Attributes
+    ----------
+    emote: PowerUpEmote | None
+        Emote associated with the reward. Is `None` if no emote was used.
+    type: typing.Literal["message_effect", "celebration", "gigantify_an_emote"]
+        The type of Power-up redeemed.
+
+            - message_effect
+            - celebration
+            - gigantify_an_emote
+
+    message_effect_id: str | None
+        The ID of the message effect. Is `None` if no message effect was used.
+    """
+
+    __slots__ = ("emote", "message_effect_id", "type")
+
+    def __init__(self, data: PowerUpData) -> None:
+        emote = data.get("emote")
+        self.emote: PowerUpEmote | None = PowerUpEmote(emote) if emote is not None else None
+        self.type: Literal["message_effect", "celebration", "gigantify_an_emote"] = data["type"]
+        self.message_effect_id: str | None = data.get("message_effect_id")
+
+
+class ChannelBitsUse(BaseEvent):
+    """
+    Represents a channel bits use event.
+
+    Attributes
+    ----------
+    broadcaster: PartialUser
+        The broadcastter / channel where the Bits were redeemed.
+    user: PartialUser
+        The redeeming user.
+    bits: int
+        The number of Bits used.
+    type: typing.Literal["cheer", "power_up"]
+        What the Bits were used for.
+    text: str | None
+        The chat message in plain text. Is `None` if no chat message was used.
+    fragments: list[ChatMessageFragment]
+        The ordered list of chat message fragments. Is `None` if no chat message was used.
+    power_up: PowerUp | None
+        Data about Power-up. Is `None` if a Power-up is not used.
+    """
+
+    subscription_type = "channel.bits.use"
+
+    __slots__ = ("bits", "broadcaster", "fragments", "power_up", "text", "type", "user")
+
+    def __init__(self, payload: ChannelBitsUseEvent, *, http: HTTPClient) -> None:
+        self.broadcaster = PartialUser(
+            payload["broadcaster_user_id"], payload["broadcaster_user_login"], payload["broadcaster_user_name"], http=http
+        )
+        self.user = PartialUser(payload["user_id"], payload["user_login"], payload["user_name"], http=http)
+        self.bits: int = int(payload["bits"])
+        self.type: Literal["cheer", "power_up"] = payload["type"]
+        self.text: str | None = payload.get("message").get("text")
+        power_up = payload.get("power_up")
+        self.power_up: PowerUp | None = PowerUp(power_up) if power_up is not None else None
+        self.fragments: list[ChatMessageFragment] = [
+            ChatMessageFragment(fragment, http=http) for fragment in payload["message"]["fragments"]
+        ]
+
+    def __repr__(self) -> str:
+        return f"<ChannelBitsUse broadcaster={self.broadcaster} user={self.user} bits={self.bits} type={self.type}>"
+
+
 class ChannelUpdate(BaseEvent):
     """
     Represents a channel update event.

twitchio/types_/eventsub.py

@@ -131,6 +131,8 @@
     "ModerateUnbanRequestData",
     "ModerateWarnData",
     "PollChoiceData",
+    "PowerUpData",
+    "PowerUpEmoteDataData",
     "ReedemedRewardData",
     "ShieldModeBeginEvent",
     "ShieldModeEndEvent",
@@ -356,14 +358,14 @@ class ChannelAdBreakBeginEvent(BaseBroadcasterEvent):
     is_automatic: str
 
 
-class PowerUpEmote(TypedDict):
+class PowerUpEmoteDataData(TypedDict):
     id: str
     name: str
 
 
 class PowerUpData(TypedDict):
     type: Literal["message_effect", "celebration", "gigantify_an_emote"]
-    emote: PowerUpEmote | None
+    emote: PowerUpEmoteDataData | None
     message_effect_id: str | None