Add event_token_refreshed

Author: EvieePy

docs/references/events.rst

@@ -316,6 +316,15 @@ Client Events
   Event dispatched when an exception is raised inside of a dispatched event.
 
   :param twitchio.EventErrorPayload payload: The payload containing information about the event and exception raised.
+
+.. py:function:: event_token_refreshed(payload: twitchio.TokenRefreshedPayload) -> None:
+  :async:
+  
+  Event dispatched when a token managed by the :class:`~twitchio.Client` is successfully refreshed.
+
+  You can use this event to update the stored token locally as they are refreshed.
+
+  :param TokenRefreshedPayload payload: The payload containing various information about the refreshed token.
 
 .. py:function:: event_oauth_authorized(payload: twitchio.authentication.UserTokenPayload) -> None
   :async:
@@ -1297,4 +1306,9 @@ Payloads
 .. attributetable:: twitchio.EventErrorPayload
 
 .. autoclass:: twitchio.EventErrorPayload()
+  :members:
+
+.. attributetable:: twitchio.TokenRefreshedPayload
+
+.. autoclass:: twitchio.TokenRefreshedPayload()
   :members:

twitchio/authentication/tokens.py

@@ -22,6 +22,8 @@
 SOFTWARE.
 """
 
+from __future__ import annotations
+
 import asyncio
 import datetime
 import json
@@ -36,6 +38,7 @@
 from ..backoff import Backoff
 from ..exceptions import HTTPException, InvalidTokenException
 from ..http import HTTPAsyncIterator, PaginatedConverter
+from ..payloads import TokenRefreshedPayload
 from ..types_.tokens import TokenMappingData
 from ..utils import MISSING
 from .oauth import OAuth
@@ -44,7 +47,8 @@
 
 
 if TYPE_CHECKING:
-    from ..types_.tokens import TokenMapping
+    from ..client import Client
+    from ..types_.tokens import TokenMapping, _TokenRefreshedPayload
     from .payloads import RefreshTokenPayload
 
 
@@ -64,6 +68,7 @@ def __init__(
         scopes: Scopes | None = None,
         session: aiohttp.ClientSession = MISSING,
         nested_key: str | None = None,
+        client: Client | None = None,
     ) -> None:
         super().__init__(
             client_id=client_id,
@@ -89,6 +94,21 @@ def __init__(
         self._backoff: Backoff = Backoff(base=3, maximum_time=90)
 
         self._validate_task: asyncio.Task[None] | None = None
+        self._client = client
+
+    def _dispatch_event(self, user_id: str, payload: RefreshTokenPayload) -> None:
+        if not self._client:
+            return
+
+        data: _TokenRefreshedPayload = {
+            "user_id": user_id,
+            "refresh_token": payload.refresh_token,
+            "token": payload.access_token,
+            "scopes": Scopes(payload.scope),
+            "expires_in": payload.expires_in,
+        }
+
+        self._client.dispatch("token_refreshed", TokenRefreshedPayload(data=data))
 
     async def _attempt_refresh_on_add(self, token: str, refresh: str) -> ValidateTokenPayload:
         logger.debug("Token was invalid when attempting to add it to the token manager. Attempting to refresh.")
@@ -118,6 +138,7 @@ async def _attempt_refresh_on_add(self, token: str, refresh: str) -> ValidateTok
             "last_validated": datetime.datetime.now().isoformat(),
         }
 
+        self._dispatch_event(valid_resp.user_id, resp)
         logger.info('Token successfully added to TokenManager after refresh: "%s"', valid_resp.user_id)
         return valid_resp
 
@@ -206,6 +227,7 @@ async def request(self, route: Route) -> RawResponse | str | None:
                 "last_validated": datetime.datetime.now().isoformat(),
             }
 
+            self._dispatch_event(old["user_id"], refresh)
             route.update_headers({"Authorization": f"Bearer {refresh.access_token}"})
             return await self.request(route)
 
@@ -247,6 +269,8 @@ async def _refresh_token(self, user_id: str, refresh: str) -> None:
                 "last_validated": datetime.datetime.now().isoformat(),
             }
 
+            self._dispatch_event(user_id, resp)
+
     async def _revalidate_all(self) -> None:
         logger.debug("Attempting to revalidate all tokens that have passed the timeout on %s.", self.__class__.__qualname__)
 

twitchio/client.py

@@ -137,6 +137,7 @@ def __init__(
             redirect_uri=redirect_uri,
             scopes=scopes,
             session=session,
+            client=self,
         )
         adapter: BaseAdapter | type[BaseAdapter] = options.get("adapter", AiohttpAdapter)
         if isinstance(adapter, BaseAdapter):

twitchio/events.pyi

@@ -5,6 +5,17 @@ if TYPE_CHECKING:
 
     from .authentication import UserTokenPayload
     from .models.eventsub_ import SubscriptionRevoked
+    from .payloads import TokenRefreshedPayload
+
+async def event_token_refreshed(payload: TokenRefreshedPayload) -> None:
+    """Event dispatched when a token managed by the :class:`~twitchio.Client` is successfully refreshed.
+
+    You can use this event to update the stored token locally.
+
+    Parameters
+    ----------
+    payload: TokenRefreshedPayload
+    """
 
 async def event_oauth_authorized(payload: UserTokenPayload) -> None:
     """Event dispatched when a user authorizes your Client-ID via Twitch OAuth on a built-in web adapter.

twitchio/payloads.py

@@ -32,11 +32,13 @@
 if TYPE_CHECKING:
     from collections.abc import Callable, Coroutine
 
+    from .authentication import Scopes
     from .eventsub.enums import SubscriptionType
     from .types_.eventsub import Condition, _SubscriptionData
+    from .types_.tokens import _TokenRefreshedPayload
 
 
-__all__ = ("EventErrorPayload", "WebsocketSubscriptionData")
+__all__ = ("EventErrorPayload", "TokenRefreshedPayload", "WebsocketSubscriptionData")
 
 
 class EventErrorPayload:
@@ -99,3 +101,37 @@ def __init__(self, data: _SubscriptionData) -> None:
         self.transport: TransportMethod = TransportMethod.WEBSOCKET
         self.type: SubscriptionType = data["type"]
         self.version: str = data["version"]
+
+
+class TokenRefreshedPayload:
+    """Payload received in the :func:`~twitchio.event_token_refreshed` event when a token managed by TwitchIO is successfully
+    refreshed on the :class:`~twitchio.Client`.
+
+    Attributes
+    ----------
+    user_id: str
+        The User ID associated with the refreshed token.
+    refresh_token: str
+        The new refresh token returned by Twitch.
+    token: str
+        The updated token after refreshing returned by Twitch.
+    scopes: :class:`~twitchio.Scopes`
+        The scopes associated with the token.
+    expires_in: int
+        The time the new token expires as an :class:`int` of seconds.
+    """
+
+    __slots__ = (
+        "expires_in",
+        "refresh_token",
+        "scopes",
+        "token",
+        "user_id",
+    )
+
+    def __init__(self, data: _TokenRefreshedPayload) -> None:
+        self.user_id: str = data["user_id"]
+        self.refresh_token: str = data["refresh_token"]
+        self.token: str = data["token"]
+        self.scopes: Scopes = data["scopes"]
+        self.expires_in: int = data["expires_in"]

twitchio/types_/tokens.py

@@ -22,10 +22,16 @@
 SOFTWARE.
 """
 
-from typing import TypeAlias, TypedDict
+from __future__ import annotations
 
+from typing import TYPE_CHECKING, TypeAlias, TypedDict
 
-__all__ = ("TokenMapping", "TokenMappingData")
+
+if TYPE_CHECKING:
+    from ..authentication import Scopes
+
+
+__all__ = ("TokenMapping", "TokenMappingData", "_TokenRefreshedPayload")
 
 
 class TokenMappingData(TypedDict):
@@ -35,4 +41,12 @@ class TokenMappingData(TypedDict):
     last_validated: str
 
 
+class _TokenRefreshedPayload(TypedDict):
+    user_id: str
+    refresh_token: str
+    token: str
+    scopes: Scopes
+    expires_in: int
+
+
 TokenMapping: TypeAlias = dict[str, TokenMappingData]