feat: subscriptions & related changes

Author: plun1331

discord/client.py

@@ -2048,7 +2048,7 @@ async def fetch_skus(self) -> list[SKU]:
             The bot's SKUs.
         """
         data = await self._connection.http.list_skus(self.application_id)
-        return [SKU(data=s) for s in data]
+        return [SKU(state=self._connection, data=s) for s in data]
 
     def entitlements(
         self,

discord/enums.py

@@ -1053,6 +1053,14 @@ class PollLayoutType(Enum):
     default = 1
 
 
+class SubscriptionStatus(Enum):
+    """The status of a subscription."""
+
+    active = 1
+    ending = 2
+    inactive = 3
+
+
 T = TypeVar("T")
 
 

discord/http.py

@@ -3027,6 +3027,41 @@ def delete_test_entitlement(
         )
         return self.request(r)
 
+    async def list_sku_subscriptions(
+        self,
+        sku_id: Snowflake,
+        *,
+        before: Snowflake | None = None,
+        after: Snowflake | None = None,
+        limit: int = 50,
+        user_id: Snowflake | None = None,
+    ) -> Response[list[monetization.Subscription]]:
+        params: dict[str, Any] = {}
+        if before is not None:
+            params["before"] = before
+        if after is not None:
+            params["after"] = after
+        if limit is not None:
+            params["limit"] = limit
+        if user_id is not None:
+            params["user_id"] = user_id
+        return self.request(
+            Route("GET", "/skus/{sku_id}/subscriptions", sku_id=sku_id),
+            params=params,
+        )
+
+    async def get_subscription(
+        self,
+        sku_id: Snowflake,
+        subscription_id: Snowflake,
+    ) -> Response[monetization.Subscription]:
+        return self.request(
+            Route(
+                "GET", "/skus/{sku_id}/subscriptions/{subscription_id}",
+                sku_id=sku_id, subscription_id=subscription_id
+            )
+        )
+
     # Onboarding
 
     def get_onboarding(self, guild_id: Snowflake) -> Response[onboarding.Onboarding]:

discord/iterators.py

@@ -52,6 +52,7 @@
     "MemberIterator",
     "ScheduledEventSubscribersIterator",
     "EntitlementIterator",
+    "SubscriptionIterator",
 )
 
 if TYPE_CHECKING:
@@ -67,6 +68,7 @@
     from .types.threads import Thread as ThreadPayload
     from .types.user import PartialUser as PartialUserPayload
     from .user import User
+    from .types.monetization import Subscription as SubscriptionPayload
 
 T = TypeVar("T")
 OT = TypeVar("OT")
@@ -1041,3 +1043,105 @@ async def fill_entitlements(self):
 
         for element in reversed(data):
             await self.entitlements.put(Entitlement(data=element, state=self.state))
+
+
+class SubscriptionIterator(_AsyncIterator["Subscription"]):
+    def __init__(
+        self,
+        state,
+        sku_id: int,
+        limit: int = None,
+        before: datetime.datetime | None = None,
+        after: datetime.datetime | None = None,
+        user_id: int | None = None
+    ):
+        if isinstance(before, datetime.datetime):
+            before = Object(id=time_snowflake(before, high=False))
+        if isinstance(after, datetime.datetime):
+            after = Object(id=time_snowflake(after, high=True))
+
+        self.state = state
+        self.sku_id = sku_id
+        self.limit = limit
+        self.before = before
+        self.after = after
+        self.user_id = user_id
+
+        self._filter = None
+
+        self.get_subscriptions = state.http.list_sku_subscriptions
+        self.subscriptions = asyncio.Queue()
+
+        if self.before and self.after:
+            self._retrieve_subscriptions = self._retrieve_subscriptions_before_strategy  # type: ignore
+            self._filter = lambda m: int(m["id"]) > self.after.id
+        elif self.after:
+            self._retrieve_subscriptions = self._retrieve_subscriptions_after_strategy  # type: ignore
+        else:
+            self._retrieve_subscriptions = self._retrieve_subscriptions_before_strategy  # type: ignore
+
+    async def next(self) -> Guild:
+        if self.subscriptions.empty():
+            await self.fill_subscriptions()
+
+        try:
+            return self.subscriptions.get_nowait()
+        except asyncio.QueueEmpty:
+            raise NoMoreItems()
+
+    def _get_retrieve(self):
+        l = self.limit
+        if l is None or l > 100:
+            r = 100
+        else:
+            r = l
+        self.retrieve = r
+        return r > 0
+
+    def create_subscription(self, data):
+        from .monetization import Subscription
+
+        return Subscription(state=self.state, data=data)
+
+    async def fill_subscriptions(self):
+        if self._get_retrieve():
+            data = await self._retrieve_subscriptions(self.retrieve)
+            if self.limit is None or len(data) < 100:
+                self.limit = 0
+
+            if self._filter:
+                data = filter(self._filter, data)
+
+            for element in data:
+                await self.subscriptions.put(self.create_subscription(element))
+
+    async def _retrieve_subscriptions(self, retrieve) -> list[SubscriptionPayload]:
+        raise NotImplementedError
+
+    async def _retrieve_subscriptions_before_strategy(self, retrieve):
+        before = self.before.id if self.before else None
+        data: list[SubscriptionPayload] = await self.get_subscriptions(
+            self.sku_id,
+            limit=retrieve,
+            before=before,
+            user_id=self.user_id,
+        )
+        if len(data):
+            if self.limit is not None:
+                self.limit -= retrieve
+            self.before = Object(id=int(data[-1]["id"]))
+        return data
+
+    async def _retrieve_subscriptions_after_strategy(self, retrieve):
+        after = self.after.id if self.after else None
+        data: list[SubscriptionPayload] = await self.get_subscriptions(
+            self.sku_id,
+            limit=retrieve,
+            after=after,
+            user_id=self.user_id,
+        )
+        if len(data):
+            if self.limit is not None:
+                self.limit -= retrieve
+            self.after = Object(id=int(data[0]["id"]))
+        return data

discord/monetization.py

@@ -27,17 +27,20 @@
 
 from typing import TYPE_CHECKING
 
-from .enums import EntitlementType, SKUType, try_enum
+from .abc import Snowflake, SnowflakeTime
+from .enums import EntitlementType, SKUType, SubscriptionStatus, try_enum
 from .flags import SKUFlags
+from .iterators import SubscriptionIterator
 from .mixins import Hashable
-from .utils import MISSING, _get_as_snowflake, parse_time
+from .utils import cached_property, cached_slot_property, MISSING, _get_as_snowflake, parse_time
 
 if TYPE_CHECKING:
     from datetime import datetime
 
     from .state import ConnectionState
     from .types.monetization import SKU as SKUPayload
     from .types.monetization import Entitlement as EntitlementPayload
+    from .types.monetization import Subscription as SubscriptionPayload
 
 
 __all__ = (
@@ -68,6 +71,7 @@ class SKU(Hashable):
     """
 
     __slots__ = (
+        "_state",
         "id",
         "type",
         "application_id",
@@ -76,7 +80,8 @@ class SKU(Hashable):
         "flags",
     )
 
-    def __init__(self, *, data: SKUPayload) -> None:
+    def __init__(self, *, state: ConnectionState, data: SKUPayload) -> None:
+        self._state: ConnectionState = state
         self.id: int = int(data["id"])
         self.type: SKUType = try_enum(SKUType, data["type"])
         self.application_id: int = int(data["application_id"])
@@ -101,12 +106,48 @@ def url(self) -> str:
         """:class:`str`: Returns the URL for the SKU."""
         return f"https://discord.com/application-directory/{self.application_id}/store/{self.id}"
 
+    def list_subscriptions(
+        self,
+        user: Snowflake,  # user is required because this is a bot, we are not using oauth2
+        *,
+        before: SnowflakeTime | None = None,
+        after: SnowflakeTime | None = None,
+        limit: int | None = 100,
+    ) -> SubscriptionIterator:
+        """Returns an :class:`.AsyncIterator` that enables fetching the SKU's subscriptions.
+
+        .. versionadded:: 2.7
+
+        Parameters
+        ----------
+        user: :class:`.abc.Snowflake`
+            The user to retrieve subscriptions for.
+        before: :class:`.abc.Snowflake` | :class:`datetime.datetime` | None
+            Retrieves subscriptions before this date or object.
+            If a datetime is provided, it is recommended to use a UTC-aware datetime.
+            If the datetime is naive, it is assumed to be local time.
+        after: :class:`.abc.Snowflake` | :class:`datetime.datetime` | None
+            Retrieve subscriptions after this date or object.
+            If a datetime is provided, it is recommended to use a UTC-aware datetime.
+            If the datetime is naive, it is assumed to be local time.
+        limit: :class:`int` | None
+            The number of subscriptions to retrieve. If ``None``, retrieves all subscriptions.
+        """
+        return SubscriptionIterator(self._state, self.id, user_id=user.id, before=before, after=after, limit=limit)
+
 
 class Entitlement(Hashable):
     """Represents a Discord entitlement.
 
     .. versionadded:: 2.5
 
+    .. notice::
+
+        As of October 1, 2024, entitlements that have been purchased will have ``ends_at`` set to ``None``
+        unless the parent :class:`Subscription` has been cancelled.
+
+        `See the Discord changelog. <https://discord.com/developers/docs/change-log#premium-apps-entitlement-migration-and-new-subscription-api>`_
+
     Attributes
     ----------
     id: :class:`int`
@@ -130,7 +171,7 @@ class Entitlement(Hashable):
     consumed: :class:`bool`
         Whether or not this entitlement has been consumed.
         This will always be ``False`` for entitlements that are not
-        of type :attr:`EntitlementType.consumable`.
+        from an SKU of type :attr:`SKUType.consumable`.
     """
 
     __slots__ = (
@@ -158,7 +199,7 @@ def __init__(self, *, data: EntitlementPayload, state: ConnectionState) -> None:
         self.starts_at: datetime | MISSING = (
             parse_time(data.get("starts_at")) or MISSING
         )
-        self.ends_at: datetime | MISSING = parse_time(data.get("ends_at")) or MISSING
+        self.ends_at: datetime | MISSING | None = parse_time(ea) if (ea := data.get("ends_at")) is not None else MISSING
         self.guild_id: int | MISSING = _get_as_snowflake(data, "guild_id") or MISSING
         self.consumed: bool = data.get("consumed", False)
 
@@ -177,18 +218,13 @@ async def consume(self) -> None:
 
         Consumes this entitlement.
 
-        This can only be done on entitlements of type :attr:`EntitlementType.consumable`.
+        This can only be done on entitlements from an SKU of type :attr:`SKUType.consumable`.
 
         Raises
         ------
-        TypeError
-            The entitlement is not consumable.
         HTTPException
             Consuming the entitlement failed.
         """
-        if self.type is not EntitlementType.consumable:
-            raise TypeError("Cannot consume non-consumable entitlement")
-
         await self._state.http.consume_entitlement(self._state.application_id, self.id)
         self.consumed = True
 
@@ -205,3 +241,69 @@ async def delete(self) -> None:
             Deleting the entitlement failed.
         """
         await self._state.http.delete_test_entitlement(self.application_id, self.id)
+
+
+class Subscription(Hashable):
+    """Represents a user making recurring payments for one or more SKUs.
+
+    Successful payments grant the user access to entitlements associated with the SKU.
+
+    .. versionadded:: 2.7
+
+    Attributes
+    ----------
+    id: :class:`int`
+        The subscription's ID.
+    user_id: :class:`int`
+        The ID of the user that owns this subscription.
+    sku_ids: List[:class:`int`]
+        The IDs of the SKUs this subscription is for.
+    entitlement_ids: List[:class:`int`]
+        The IDs of the entitlements this subscription is for.
+    current_period_start: :class:`datetime.datetime`
+        The start of the current subscription period.
+    current_period_end: :class:`datetime.datetime`
+        The end of the current subscription period.
+    status: :class:`SubscriptionStatus`
+        The status of the subscription.
+    canceled_at: :class:`datetime.datetime` | ``None``
+        When the subscription was canceled.
+    """
+    __slots__ = (
+        "_state",
+        "id",
+        "user_id",
+        "sku_ids",
+        "entitlement_ids",
+        "current_period_start",
+        "current_period_end",
+        "status",
+        "canceled_at",
+        "country",
+    )
+
+    def __init__(self, *, state: ConnectionState, data: SubscriptionPayload) -> None:
+        self._state: ConnectionState = state
+        self.id: int = int(data["id"])
+        self.user_id: int = int(data["user_id"])
+        self.sku_ids: list[int] = list(map(int, data["sku_ids"]))
+        self.entitlement_ids: list[int] = list(map(int, data["entitlement_ids"]))
+        self.current_period_start: datetime = parse_time(data["current_period_start"])
+        self.current_period_end: datetime = parse_time(data["current_period_end"])
+        self.status: SubscriptionStatus = try_enum(SubscriptionStatus, data["status"])
+        self.canceled_at: datetime | None = parse_time(data.get("canceled_at"))
+        self.country: str | None = data.get("country")  # Not documented, it is only available with oauth2, not bots
+
+    def __repr__(self) -> str:
+        return (
+            f"<Subscription id={self.id} user_id={self.user_id} status={self.status}>"
+        )
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, self.__class__) and other.id == self.id
+
+    @property
+    def user(self):
+        """Optional[:class:`User`]: The user that owns this subscription."""
+        return self._state.get_user(self.user_id)
+