feat: add the on_disconnect event (#1199)

* feat: add the `on_disconnect` event

* Update docs/events.rst

* refactor: Move on_disconnect call.

(note, this is done without an IDE, pre-commit might fail)

* ci: correct from checks.

---------

Co-authored-by: Sophia <41456914+i0bs@users.noreply.github.com>
Co-authored-by: DeltaX <33706469+DeltaXWizard@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 4 people

docs/events.rst

@@ -52,6 +52,7 @@ There are several different internal events:
 
     - ``raw_socket_create``
     - ``on_start``
+    - ``on_disconnect``
     - ``on_interaction``
     - ``on_command``
     - ``on_command_error``
@@ -82,6 +83,13 @@ This function takes no arguments.
 .. attention::
     Unlike ``on_ready``, this event will never be dispatched more than once.
 
+Event: ``on_disconnect``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This event fires whenever the connection is invalidated and will often precede an ``on_ready`` event
+
+This function takes no arguments.
+
+
 Event: ``on_interaction``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 This event fires on any interaction (commands, components, autocomplete and modals).

interactions/api/gateway/client.py

@@ -929,6 +929,12 @@ async def _reconnect(self, to_resume: bool, code: Optional[int] = 1012) -> None:
                 if self.__heartbeat_event.is_set():
                     self.__heartbeat_event.clear()  # Because we're hardresetting the process
 
+            self._dispatch.dispatch(
+                "on_disconnect"
+            )  # will be followed by the on_ready event after reconnection
+            # reconnection happens whenever it disconnects either with or without a resume prompt
+            # as this is called whenever the WS client closes
+
             if not to_resume:
                 url = self.ws_url if self.ws_url else await self._http.get_gateway()
             else: