Add new API routes (#441)

* Add new API routes

* add docs

Author: IAmTomahawkx

docs/reference.rst

@@ -11,6 +11,13 @@ ActiveExtension
     :members:
     :inherited-members:
 
+AdSchedule
+------------
+.. attributetable:: AdSchedule
+
+.. autoclass:: AdSchedule
+    :members:
+
 AutomodCheckMessage
 ---------------------
 .. attributetable:: AutomodCheckMessage

twitchio/http.py

@@ -645,7 +645,6 @@ async def get_hype_train(self, broadcaster_id: str, id: Optional[str] = None, to
         )
 
     async def post_automod_check(self, token: str, broadcaster_id: str, *msgs: List[Dict[str, str]]):
-        print(msgs)
         return await self.request(
             Route(
                 "POST",
@@ -656,6 +655,14 @@ async def post_automod_check(self, token: str, broadcaster_id: str, *msgs: List[
             )
         )
 
+    async def post_snooze_ad(self, token: str, broadcaster_id: str):
+        q = [("broadcaster_id", broadcaster_id)]
+        return await self.request(Route("POST", "channels/ads/schedule/snooze", query=q, token=token))
+
+    async def get_ad_schedule(self, token: str, broadcaster_id: str):
+        q = [("broadcaster_id", broadcaster_id)]
+        return await self.request(Route("GET", "channels/ads", query=q, token=token))
+
     async def get_channel_ban_unban_events(self, token: str, broadcaster_id: str, user_ids: List[str] = None):
         q = [("broadcaster_id", broadcaster_id)]
         if user_ids:
@@ -668,6 +675,10 @@ async def get_channel_bans(self, token: str, broadcaster_id: str, user_ids: List
             q.extend(("user_id", id) for id in user_ids)
         return await self.request(Route("GET", "moderation/banned", query=q, token=token))
 
+    async def get_moderated_channels(self, token: str, user_id: str):
+        q = [("user_id", user_id)]
+        return await self.request(Route("GET", "moderation/channels", query=q, token=token))
+
     async def get_channel_moderators(self, token: str, broadcaster_id: str, user_ids: List[str] = None):
         q = [("broadcaster_id", broadcaster_id)]
         if user_ids:

twitchio/models.py

@@ -33,6 +33,7 @@
 if TYPE_CHECKING:
     from .http import TwitchHTTP
 __all__ = (
+    "AdSchedule",
     "BitsLeaderboard",
     "Clip",
     "CheerEmote",
@@ -87,6 +88,44 @@
 )
 
 
+class AdSchedule:
+    """
+    Represents a channel's ad schedule.
+
+    Attributes
+    -----------
+    next_ad_at: Optional[:class:`datetime.datetime`]
+        When the next ad will roll. Will be ``None`` if the streamer does not schedule ads, or is not live.
+    last_ad_at: Optional[:class:`datetime.datetime`]
+        When the last ad rolled. Will be ``None`` if the streamer has not rolled an ad.
+        Will always be ``None`` when this comes from snoozing an ad.
+    duration: :class:`int`
+        How long the upcoming ad will be, in seconds.
+    preroll_freeze_time: Optional[:class:`int`]
+        The amount of pre-roll free time remaining for the channel in seconds. Will be 0 if the streamer is not pre-roll free.
+        Will be ``None`` when this comes from snoozing an ad.
+    snooze_count: :class:`int`
+        How many snoozes the streamer has left.
+    snooze_refresh_at: :class:`datetime.datetime`
+        When the streamer will gain another snooze.
+    """
+
+    __slots__ = "next_ad_at", "last_ad_at", "duration", "preroll_freeze_time", "snooze_count", "snooze_refresh_at"
+
+    def __init__(self, data: dict) -> None:
+        self.duration: int = data["duration"]
+        self.preroll_freeze_time: int = data["preroll_freeze_time"]
+        self.snooze_count: int = data["snooze_count"]
+
+        self.snooze_refresh_at: datetime.datetime = parse_timestamp(data["snooze_refresh_at"])
+        self.next_ad_at: Optional[datetime.datetime] = (
+            parse_timestamp(data["next_ad_at"]) if data["next_ad_at"] else None
+        )
+        self.last_ad_at: Optional[datetime.datetime] = (
+            parse_timestamp(data["last_ad_at"]) if data["last_ad_at"] else None
+        )
+
+
 class BitsLeaderboard:
     """
     Represents a Bits leaderboard from the twitch API.

twitchio/user.py

@@ -37,6 +37,7 @@
     from .http import TwitchHTTP
     from .channel import Channel
     from .models import (
+        AdSchedule,
         BitsLeaderboard,
         Clip,
         ExtensionBuilder,
@@ -334,6 +335,48 @@ async def create_clip(self, token: str, has_delay=False) -> dict:
         data = await self._http.post_create_clip(token, self.id, has_delay)
         return data[0]
 
+    async def fetch_ad_schedule(self, token: str) -> AdSchedule:
+        """|coro|
+
+        Fetches the streamers's ad schedule.
+
+        Parameters
+        -----------
+        token: :class:`str`
+            The user's oauth token with the ``channel:read:ads`` scope.
+
+        Returns
+        --------
+        :class:`twitchio.AdSchedule`
+        """
+        from .models import AdSchedule
+
+        data = await self._http.get_ad_schedule(token, str(self.id))
+        return AdSchedule(data[0])
+
+    async def snooze_ad(self, token: str) -> List[AdSchedule]:
+        """|coro|
+
+        Snoozes an ad on the streamer's channel.
+
+        .. note::
+            The resulting :class:`~twitchio.AdSchedule` only has data for the :attr:`~twitchio.AdSchedule.snooze_count`,
+            :attr:`~twitchio.AdSchedule.snooze_refresh_at`, and :attr:`~twitchio.AdSchedule.next_ad_at` attributes.
+
+        Parameters
+        -----------
+        token: :class:`str`
+            The user's oauth token with the ``channel:manage:ads`` scope.
+
+        Returns
+        --------
+        :class:`twitchio.AdSchedule`
+        """
+        from .models import AdSchedule
+
+        data = await self._http.post_snooze_ad(token, str(self.id))
+        return AdSchedule(data[0])
+
     async def fetch_clips(
         self,
         started_at: Optional[datetime.datetime] = None,
@@ -403,6 +446,23 @@ async def fetch_bans(self, token: str, userids: List[Union[str, int]] = None) ->
         data = await self._http.get_channel_bans(token, str(self.id), user_ids=userids)
         return [UserBan(self._http, d) for d in data]
 
+    async def fetch_moderated_channels(self, token: str) -> List[PartialUser]:
+        """|coro|
+
+        Fetches channels that this user moderates.
+
+        Parameters
+        -----------
+        token: :class:`str`
+            An oauth token for this user with the ``user:read:moderated_channels`` scope.
+
+        Returns
+        --------
+        List[:class:`twitchio.PartialUser`]
+        """
+        data = await self._http.get_moderated_channels(token, str(self.id))
+        return [PartialUser(self._http, d["user_id"], d["user_name"]) for d in data]
+
     async def fetch_moderators(self, token: str, userids: List[int] = None):
         """|coro|