More EventSub Subscription Types (#303)

* Added new Subscription notifications: Gift and Message
Added convenience method EventSubClient.delete_all_active_subscriptions

* Updated Docs

* Fixed function names for uniformity

* Added emote data to Subscription Messages

* Added emote data to Subscription Messages

* Small correction to EventSub Docs

* Updated changelog with "Future via PR #303" section.

Heading to be replaced with "Master" when all changes are ready and version number determined

* Updated changelog with "Future via PR #303" section.

Heading to be replaced with "Master" when all changes are ready and version number determined

* Updated changelog

* Updated changelog

* Updated Docs. Fixed lack of members for EventSubClient. Now has a lot of members

* Updated Docs. Fixed lack of members for EventSubClient. Now has a lot of members

* One last Docs update.

* One last Docs update, for real.

* Update requested changes

Co-authored-by: Tom <[email protected]>

Author: DNEAVES

docs/changelog.rst

@@ -50,6 +50,13 @@ Master
 
 - ext.eventsub
     - Additions
+        - Added Gift Subcriptions subscriptions for gifting other users Subs:
+            - Subscribed via :func:`twitchio.ext.eventsub.EventSubClient.subscribe_channel_subscription_gifts`
+            - Callback function is :func:`twitchio.ext.eventsub.event_eventsub_notification_subscription_gift`
+        - Added Resubscription Message subscriptions for Resub messages:
+            - Subscribed via :func:`twitchio.ext.eventsub.EventSubClient.subscribe_channel_subscription_messages`
+            - Callback function is :func:`twitchio.ext.eventsub.event_eventsub_notification_subscription_message`
+        - Added :func:`twitchio.ext.eventsub.EventSubClient.delete_all_active_subscriptions` for convenience
         - Created an Eventsub-specific :class:`~twitchio.ext.eventsub.CustomReward` model
 
 2.3.0

docs/exts/eventsub.rst

@@ -108,6 +108,14 @@ This is a list of events dispatched by the eventsub ext.
 
     Called when someone subscribes to a channel that you've subscribed to.
 
+.. function:: event_eventsub_notification_subscription_gift(event: ChannelSubscriptionGiftData)
+
+    Called when someone gifts a subscription to a channel that you've subscribed to.
+
+.. function:: event_eventsub_notification_subscription_message(event: ChannelSubscriptionMessageData)
+
+    Called when someone resubscribes with a message to a channel that you've subscribed to.
+
 .. function:: event_eventsub_notification_cheer(event: ChannelCheerData)
 
     Called when someone cheers on a channel you've subscribed to.
@@ -152,8 +160,7 @@ API Reference
 
 .. autoclass:: EventSubClient
     :members:
-
-(The above is broken, and does not show members)
+    :undoc-members:
 
 .. attributetable:: Subscription
 
@@ -179,6 +186,18 @@ API Reference
     :members:
     :inherited-members:
 
+.. attributetable::: ChannelSubscriptionGiftData
+
+.. autoclass:: ChannelSubscriptionGiftData
+    :members:
+    :inherited-members:
+
+.. attributetable::: ChannelSubscriptionMessageData
+
+.. autoclass:: ChannelSubscriptionMessageData
+    :members:
+    :inherited-members:
+
 .. attributetable::: ChannelCheerData
 
 .. autoclass:: ChannelCheerData

twitchio/ext/eventsub/models.py

@@ -237,6 +237,77 @@ def __init__(self, client: EventSubClient, data: dict):
         self.is_gift: bool = data["is_gift"]
 
 
+class ChannelSubscriptionGiftData(EventData):
+    """
+    A Subscription Gift event
+    Explicitly, the act of giving another user a Subscription.
+    Receiving a gift-subscription uses ChannelSubscribeData above, with is_gift is ``True``
+
+    Attributes
+    -----------
+    is_anonymous: :class:`bool`
+        Whether the gift sub was anonymous
+    user: Optional[:class:`twitchio.PartialUser`]
+        The user that gifted subs. Will be ``None`` if ``is_anonymous`` is ``True``
+    broadcaster: :class:`twitchio.PartialUser`
+        The channel that was subscribed to
+    tier: :class:`int`
+        The tier of the subscription
+    total: :class:`int`
+        The total number of subs gifted by a user at once
+    cumulative_total: Optional[:class:`int`]
+        The total number of subs gifted by a user overall. Will be ``None`` if ``is_anonymous`` is ``True``
+    """
+
+    __slots__ = "is_anonymous", "user", "broadcaster", "tier", "total", "cumulative"
+
+    def __init__(self, client: EventSubClient, data: dict):
+        self.is_anonymous: bool = data["is_anonymous"]
+        self.user: Optional[PartialUser] = _transform_user(client, data, "user") if not self.is_anonymous else None
+        self.broadcaster: Optional[PartialUser] = _transform_user(client, data, "broadcaster_user")
+        self.tier = int(data["tier"])
+        self.total = int(data["total"])
+        self.cumulative_total: Optional[int] = int(data["cumulative_total"]) if not self.is_anonymous else None
+
+
+class ChannelSubscriptionMessageData(EventData):
+    """
+    A Subscription Message event.
+    A combination of resubscriptions + the messages users type as part of the resub.
+
+    Attributes
+    -----------
+    user: :class:`twitchio.PartialUser`
+        The user who subscribed
+    broadcaster: :class:`twitchio.PartialUser`
+        The channel that was subscribed to
+    tier: :class:`int`
+        The tier of the subscription
+    message: :class:`str`
+        The user's resubscription message
+    emote_data: :class:`list`
+        emote data within the user's resubscription message. Not the emotes themselves
+    cumulative_months: :class:`int`
+        The total number of months a user has subscribed to the channel
+    streak: Optional[:class:`int`]
+        The total number of months subscribed in a row. ``None`` if the user declines to share it.
+    duration: :class:`int`
+        The length of the subscription. Typically 1, but some users may buy subscriptions for several months.
+    """
+
+    __slots__ = "user", "broadcaster", "tier", "message", "emote_data", "cumulative", "streak", "duration"
+
+    def __init__(self, client: EventSubClient, data: dict):
+        self.user = _transform_user(client, data, "user")
+        self.broadcaster = _transform_user(client, data, "broadcaster_user")
+        self.tier = int(data["tier"])
+        self.message: str = data["message"]["text"]
+        self.emote_data: List[Dict] = data["message"].get("emotes", [])
+        self.cumulative_months: int = data["cumulative_months"]
+        self.streak: Optional[int] = data["streak_months"]
+        self.duration: int = data["duration_months"]
+
+
 class ChannelCheerData(EventData):
     """
     A Cheer event
@@ -1092,6 +1163,8 @@ def __init__(self, client: EventSubClient, data: dict):
     ChannelBanData,
     ChannelUnbanData,
     ChannelSubscribeData,
+    ChannelSubscriptionGiftData,
+    ChannelSubscriptionMessageData,
     ChannelCheerData,
     ChannelUpdateData,
     ChannelFollowData,
@@ -1126,6 +1199,8 @@ class _SubscriptionTypes(metaclass=_SubTypesMeta):
 
     follow = "channel.follow", 1, ChannelFollowData
     subscription = "channel.subscribe", 1, ChannelSubscribeData
+    subscription_gift = "channel.subscription.gift", 1, ChannelSubscriptionGiftData
+    subscription_message = "channel.subscription.message", 1, ChannelSubscriptionMessageData
     cheer = "channel.cheer", 1, ChannelCheerData
     raid = "channel.raid", 1, ChannelRaidData
     ban = "channel.ban", 1, ChannelBanData

twitchio/ext/eventsub/server.py

@@ -46,6 +46,12 @@ def stop(self):
     async def delete_subscription(self, subscription_id: str):
         await self._http.delete_subscription(subscription_id)
 
+    async def delete_all_active_subscriptions(self):
+        # A convenience method
+        active_subscriptions = await self.get_subscriptions("enabled")
+        for subscription_id in active_subscriptions:
+            await self.delete_subscription(subscription_id)
+
     async def get_subscriptions(self, status: str = None):
         # All possible statuses are:
         #
@@ -114,6 +120,12 @@ def subscribe_channel_unbans(self, broadcaster: Union[PartialUser, str, int]):
     def subscribe_channel_subscriptions(self, broadcaster: Union[PartialUser, str, int]):
         return self._subscribe_with_broadcaster(models.SubscriptionTypes.subscription, broadcaster)
 
+    def subscribe_channel_subscription_gifts(self, broadcaster: Union[PartialUser, str, int]):
+        return self._subscribe_with_broadcaster(models.SubscriptionTypes.subscription_gift, broadcaster)
+
+    def subscribe_channel_subscription_messages(self, broadcaster: Union[PartialUser, str, int]):
+        return self._subscribe_with_broadcaster(models.SubscriptionTypes.subscription_message, broadcaster)
+
     def subscribe_channel_cheers(self, broadcaster: Union[PartialUser, str, int]):
         return self._subscribe_with_broadcaster(models.SubscriptionTypes.cheer, broadcaster)