From 21de582202bebc5f65b171b28334c5216899f899 Mon Sep 17 00:00:00 2001
From: EvieePy <evieepy@gmail.com>
Date: Sat, 9 Dec 2023 15:53:56 +1000
Subject: [PATCH 1/2] Add extra_event for unknown plugin events

---
 docs/wavelink.rst     | 14 ++++++++++++++
 wavelink/payloads.py  | 28 ++++++++++++++++++++++++++++
 wavelink/websocket.py |  3 ++-
 3 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/docs/wavelink.rst b/docs/wavelink.rst
index e4c25d9b..939c2c87 100644
--- a/docs/wavelink.rst
+++ b/docs/wavelink.rst
@@ -77,6 +77,15 @@ An event listener in a cog.
     Called when a node has been closed and cleaned-up. The second parameter ``disconnected`` is a list of
     :class:`wavelink.Player` that were connected on this Node and are now disconnected.
 
+.. function:: on_wavelink_extra_event(payload: wavelink.ExtraEventPayload)
+
+    Called when an ``Unknown`` and/or ``Unhandled`` event is recevied via Lavalink. This is most likely due to
+    a plugin like SponsorBlock sending custom event data. The payload includes the raw data sent from Lavalink.
+
+    .. note::
+
+        Please see the documentation for your Lavalink plugins to determine what data they send.
+
 
 Types
 -----
@@ -190,6 +199,11 @@ Payloads
 .. autoclass:: InfoResponsePayload
     :members:
 
+.. attributetable:: ExtraEventPayload
+
+.. autoclass:: ExtraEventPayload
+    :members:
+
 
 Enums
 -----
diff --git a/wavelink/payloads.py b/wavelink/payloads.py
index 2edc46f2..cef40d23 100644
--- a/wavelink/payloads.py
+++ b/wavelink/payloads.py
@@ -62,6 +62,7 @@
     "PlayerStatePayload",
     "VoiceStatePayload",
     "PlayerResponsePayload",
+    "ExtraEventPayload",
 )
 
 
@@ -520,3 +521,30 @@ def __init__(self, data: InfoResponse) -> None:
         self.source_managers: list[str] = data["sourceManagers"]
         self.filters: list[str] = data["filters"]
         self.plugins: list[PluginResponsePayload] = [PluginResponsePayload(p) for p in data["plugins"]]
+
+
+class ExtraEventPayload:
+    """Payload received in the :func:`on_wavelink_extra_event` event.
+
+    This payload is created when an ``Unknown`` and ``Unhandled`` event is received from Lavalink, most likely via
+    a plugin.
+
+    .. note::
+
+        See the appropriate documentation of the plugin for the data sent with these events.
+
+
+    Attributes
+    ----------
+    node: :class:`~wavelink.Node`
+        The node that the event pertains to.
+    player: :class:`~wavelink.Player` | None
+        The player associated with this event. Could be None.
+    data: dict[str, Any]
+        The raw data sent from Lavalink for this event.
+    """
+
+    def __init__(self, *, node: Node, player: Player | None, data: dict[str, Any]) -> None:
+        self.node = node
+        self.player = player
+        self.data = data
diff --git a/wavelink/websocket.py b/wavelink/websocket.py
index 96222563..c13b5e8f 100644
--- a/wavelink/websocket.py
+++ b/wavelink/websocket.py
@@ -239,7 +239,8 @@ async def keep_alive(self) -> None:
                     self.dispatch("websocket_closed", wcpayload)
 
                 else:
-                    logger.debug(f"Received unknown event type from Lavalink '{data['type']}'. Disregarding.")
+                    other_payload: ExtraEventPayload = ExtraEventPayload(node=self.node, player=player, data=data)
+                    self.dispatch("extra_event", other_payload)
             else:
                 logger.debug(f"'Received an unknown OP from Lavalink '{data['op']}'. Disregarding.")
 

From 59efffa71b76e51c905a27e10150a205547d224f Mon Sep 17 00:00:00 2001
From: EvieePy <evieepy@gmail.com>
Date: Sat, 9 Dec 2023 15:57:59 +1000
Subject: [PATCH 2/2] Added some additional documentation

---
 docs/migrating.rst   | 1 +
 docs/wavelink.rst    | 3 +++
 wavelink/payloads.py | 3 +++
 3 files changed, 7 insertions(+)

diff --git a/docs/migrating.rst b/docs/migrating.rst
index 989f77c3..3bc7ad07 100644
--- a/docs/migrating.rst
+++ b/docs/migrating.rst
@@ -86,6 +86,7 @@ Added
 - :meth:`wavelink.Node.fetch_player_info`
 - :meth:`wavelink.Node.fetch_players`
 - :attr:`wavelink.Playable.extras`
+- :func:`wavelink.on_wavelink_extra_event`
 
 
 Connecting
diff --git a/docs/wavelink.rst b/docs/wavelink.rst
index 939c2c87..16dbe552 100644
--- a/docs/wavelink.rst
+++ b/docs/wavelink.rst
@@ -85,6 +85,9 @@ An event listener in a cog.
     .. note::
 
         Please see the documentation for your Lavalink plugins to determine what data they send.
+    
+
+    .. versionadded:: 3.1.0
 
 
 Types
diff --git a/wavelink/payloads.py b/wavelink/payloads.py
index cef40d23..e869e37a 100644
--- a/wavelink/payloads.py
+++ b/wavelink/payloads.py
@@ -542,6 +542,9 @@ class ExtraEventPayload:
         The player associated with this event. Could be None.
     data: dict[str, Any]
         The raw data sent from Lavalink for this event.
+
+
+    .. versionadded:: 3.1.0
     """
 
     def __init__(self, *, node: Node, player: Player | None, data: dict[str, Any]) -> None: