From 77ef79db740c23e2716116184c4c4ad83a41314e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Irene=20Adler=E2=9D=A4?=
 <33165440+Aluerie@users.noreply.github.com>
Date: Sat, 7 Sep 2024 18:16:27 +0100
Subject: [PATCH] Add `channel.ad_break.begin` for EventSub (#464)

* Introduce `channel.ad_break.begin` for EventSub

Implementation for this subscription type: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelad_breakbegin

* Fix docs mess-up

Sorry, I m noob in docs and stuff
---
 docs/exts/eventsub.rst             | 10 +++++++++
 twitchio/ext/eventsub/models.py    | 33 ++++++++++++++++++++++++++++++
 twitchio/ext/eventsub/server.py    |  3 +++
 twitchio/ext/eventsub/websocket.py |  3 +++
 4 files changed, 49 insertions(+)

diff --git a/docs/exts/eventsub.rst b/docs/exts/eventsub.rst
index ea0a4b91..6335712d 100644
--- a/docs/exts/eventsub.rst
+++ b/docs/exts/eventsub.rst
@@ -234,6 +234,10 @@ This is a list of events dispatched by the eventsub ext.
 
     Called when a user donates to an active charity campaign.
 
+.. function:: event_eventsub_notification_channel_ad_break_begin(event: ChannelAdBreakBeginData)
+
+    Called when a user runs a midroll commercial break, either manually or automatically via ads manager.
+
 API Reference
 --------------
 
@@ -543,6 +547,12 @@ API Reference
     :members:
     :inherited-members:
 
+.. attributetable::: ChannelAdBreakBeginData
+
+.. autoclass:: ChannelAdBreakBeginData
+    :members:
+    :inherited-members:
+
 .. autoclass:: ChannelVIPAddRemove
     :members:
     :inherited-members:
diff --git a/twitchio/ext/eventsub/models.py b/twitchio/ext/eventsub/models.py
index 108a1b15..5e44da19 100644
--- a/twitchio/ext/eventsub/models.py
+++ b/twitchio/ext/eventsub/models.py
@@ -2195,6 +2195,36 @@ def __init__(self, client: EventSubClient, data: dict) -> None:
         self.trust_status: Literal["active_monitoring", "restricted", "none"] = data["low_trust_status"]
 
 
+class ChannelAdBreakBeginData(EventData):
+    """
+    An ad begin event.
+
+    Attributes
+    -----------
+    is_automatic: :class:`bool`
+        Whether the ad was run manually or automatically via ads manager.
+    broadcaster: :class:`~twitchio.PartialUser`
+        The channel where a midroll commercial break has started running.
+    requester: Optional[:class:`twitchio.PartialUser`]
+        The user who started the ad break. Will be ``None`` if ``is_automatic`` is ``True``.
+    duration: :class:`int`
+        The ad duration in seconds.
+    started_at: :class:`datetime.datetime`
+        When the ad began.
+    """
+
+    __slots__ = ("is_automatic", "broadcaster", "requester", "duration", "started_at")
+
+    def __init__(self, client: EventSubClient, data: dict) -> None:
+        self.is_automatic: bool = data["is_automatic"]
+        self.broadcaster: PartialUser = _transform_user(client, data, "broadcaster_user")
+        self.requester: Optional[PartialUser] = (
+            None if self.is_automatic else _transform_user(client, data, "requester_user")
+        )
+        self.duration: int = data["duration_seconds"]
+        self.started_at: datetime.datetime = _parse_datetime(data["started_at"])
+
+
 class AutoCustomReward:
     """
     A reward object for an Auto Reward Redeem.
@@ -2318,6 +2348,7 @@ def __init__(self, client: EventSubClient, data: dict) -> None:
     ChannelModerateData,
     AutoRewardRedeem,
     ChannelVIPAddRemove,
+    ChannelAdBreakBeginData,
 ]
 
 
@@ -2410,6 +2441,8 @@ class _SubscriptionTypes(metaclass=_SubTypesMeta):
 
     suspicious_user_update = "channel.suspicious_user.update", 1, SuspiciousUserUpdateData
 
+    channel_ad_break_begin = "channel.ad_break.begin", 1, ChannelAdBreakBeginData
+
 
 SubscriptionTypes = _SubscriptionTypes()
 
diff --git a/twitchio/ext/eventsub/server.py b/twitchio/ext/eventsub/server.py
index b9fc58ea..fb563ede 100644
--- a/twitchio/ext/eventsub/server.py
+++ b/twitchio/ext/eventsub/server.py
@@ -344,6 +344,9 @@ def subscribe_channel_vip_add(self, broadcaster: Union[PartialUser, str, int]):
     def subscribe_channel_vip_remove(self, broadcaster: Union[PartialUser, str, int]):
         return self._subscribe_with_broadcaster(models.SubscriptionTypes.channel_vip_remove, broadcaster)
 
+    def subscribe_channel_ad_break_begin(self, broadcaster: Union[PartialUser, str, int]):
+        return self._subscribe_with_broadcaster(models.SubscriptionTypes.channel_ad_break_begin, broadcaster)
+
     async def subscribe_user_authorization_granted(self):
         return await self._http.create_webhook_subscription(
             models.SubscriptionTypes.user_authorization_grant, {"client_id": self.client._http.client_id}
diff --git a/twitchio/ext/eventsub/websocket.py b/twitchio/ext/eventsub/websocket.py
index 352b0d77..c153bf6a 100644
--- a/twitchio/ext/eventsub/websocket.py
+++ b/twitchio/ext/eventsub/websocket.py
@@ -578,3 +578,6 @@ async def subscribe_channel_vip_add(self, broadcaster: Union[PartialUser, str, i
 
     async def subscribe_channel_vip_remove(self, broadcaster: Union[PartialUser, str, int], token: str):
         await self._subscribe_with_broadcaster(models.SubscriptionTypes.channel_vip_remove, broadcaster, token)
+
+    async def subscribe_channel_ad_break_begin(self, broadcaster: Union[PartialUser, str, int], token: str):
+        await self._subscribe_with_broadcaster(models.SubscriptionTypes.channel_ad_break_begin, broadcaster, token)