ctrader-api-client 0.4.3__tar.gz → 0.5.0__tar.gz

{ctrader_api_client-0.4.3 → ctrader_api_client-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrader-api-client
-Version: 0.4.3
+Version: 0.5.0
 Summary: API Client to interact with the cTrader Open API spec
 Author-email: Elio <elioachukri@pm.me>
 License-File: LICENSE
@@ -183,7 +183,7 @@ async def on_spot(event: SpotEvent):
 async def on_execution(event: ExecutionEvent):
     print(f"Order {event.order_id}: {event.execution_type}")
 
-# Account ready (fires on initial auth and after reconnection)
+# Account ready (fires on initial auth, after reconnection, and after account-disconnect recovery)
 @client.on(ReadyEvent)
 async def on_ready(event: ReadyEvent):
     # Set up subscriptions here
@@ -225,6 +225,13 @@ The client automatically handles connection drops:
 3. Emits `ReadyEvent` for each restored account (for resubscribing to market data)
 4. Emits `ReconnectedEvent` with summary of restored/failed accounts
 
+It also handles **server-side account disconnects** (e.g. a broker dropping the
+account session over the weekend while the connection stays up): the account is
+re-authenticated on the existing connection with backoff until it succeeds, then
+a `ReadyEvent` is emitted so subscriptions can be restored. Account
+authorization is observable via `client.is_account_authorized(account_id)`,
+which is distinct from the transport-level `client.is_connected`.
+
 Use `ReadyEvent` to set up subscriptions that persist across reconnections.
 
 ## Configuration

{ctrader_api_client-0.4.3 → ctrader_api_client-0.5.0}/README.md

@@ -164,7 +164,7 @@ async def on_spot(event: SpotEvent):
 async def on_execution(event: ExecutionEvent):
     print(f"Order {event.order_id}: {event.execution_type}")
 
-# Account ready (fires on initial auth and after reconnection)
+# Account ready (fires on initial auth, after reconnection, and after account-disconnect recovery)
 @client.on(ReadyEvent)
 async def on_ready(event: ReadyEvent):
     # Set up subscriptions here
@@ -206,6 +206,13 @@ The client automatically handles connection drops:
 3. Emits `ReadyEvent` for each restored account (for resubscribing to market data)
 4. Emits `ReconnectedEvent` with summary of restored/failed accounts
 
+It also handles **server-side account disconnects** (e.g. a broker dropping the
+account session over the weekend while the connection stays up): the account is
+re-authenticated on the existing connection with backoff until it succeeds, then
+a `ReadyEvent` is emitted so subscriptions can be restored. Account
+authorization is observable via `client.is_account_authorized(account_id)`,
+which is distinct from the transport-level `client.is_connected`.
+
 Use `ReadyEvent` to set up subscriptions that persist across reconnections.
 
 ## Configuration

{ctrader_api_client-0.4.3 → ctrader_api_client-0.5.0}/docs/api/events.md

@@ -85,7 +85,9 @@ async def on_spot(event: SpotEvent):
     options:
       show_source: false
 
-**Use this to set up subscriptions that persist across reconnections:**
+**Use this to set up subscriptions that persist across reconnections.** It fires
+on initial auth, after a transport reconnection, and after recovery from a
+server-side account disconnect — `is_reconnect` is `True` for the latter two:
 
 ```python
 @client.on(ReadyEvent)
@@ -93,9 +95,19 @@ async def on_ready(event: ReadyEvent):
     await client.market_data.subscribe_spots(event.account_id, [270])
 
     if event.is_reconnect:
-        print("Connection restored!")
+        print("Session restored!")
 ```
 
+`ReadyEvent` emission is driven by why authentication occurred, expressed as an
+`AuthTrigger`. It is emitted for `INITIAL`, `RECONNECT`, and `ACCOUNT_REAUTH`
+(all of which lose or re-establish subscriptions), and suppressed for
+`TOKEN_REFRESH` (session intact).
+
+::: ctrader_api_client.auth.AuthTrigger
+    options:
+      show_source: false
+      members: true
+
 ::: ctrader_api_client.events.TraderUpdateEvent
     options:
       show_source: false
@@ -137,6 +149,11 @@ async def on_reconnected(event: ReconnectedEvent):
     options:
       show_source: false
 
+The client recovers from this automatically — it re-authenticates the account on
+the existing connection with backoff and emits a `ReadyEvent` on success. The
+event is informational; subscribe to it only if you want to observe or log the
+drop. Check current authorization with `client.is_account_authorized(account_id)`.
+
 ::: ctrader_api_client.events.TokenInvalidatedEvent
     options:
       show_source: false

{ctrader_api_client-0.4.3 → ctrader_api_client-0.5.0}/docs/getting-started.md

@@ -167,19 +167,26 @@ if __name__ == "__main__":
 
 ## Handling Reconnections
 
-The client automatically reconnects when the connection drops. Use `ReadyEvent` to restore subscriptions:
+The client automatically reconnects when the connection drops, and also recovers
+from server-side account disconnects (where the account session is dropped but
+the connection stays up). In both cases it re-authenticates and emits a
+`ReadyEvent`. Use `ReadyEvent` to restore subscriptions:
 
 ```python
 @client.on(ReadyEvent)
 async def on_ready(event: ReadyEvent):
-    """Called on initial auth AND after reconnection."""
+    """Called on initial auth, after reconnection, and after account recovery."""
     # Set up subscriptions here - they persist across reconnects
     await client.market_data.subscribe_spots(event.account_id, [270, 271, 272])
 
     if event.is_reconnect:
-        print("Connection restored!")
+        print("Session restored!")
 ```
 
+You can check whether an account currently has a live, authorized session with
+`client.is_account_authorized(account_id)` — distinct from the transport-level
+`client.is_connected`.
+
 For additional reconnection information:
 
 ```python

{ctrader_api_client-0.4.3 → ctrader_api_client-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrader-api-client"
-version = "0.4.3"
+version = "0.5.0"
 description = "API Client to interact with the cTrader Open API spec"
 readme = "README.md"
 authors = [

{ctrader_api_client-0.4.3 → ctrader_api_client-0.5.0}/src/ctrader_api_client/__init__.py

@@ -38,6 +38,7 @@ Example:
     ```
 """
 
+from .auth import AuthTrigger
 from .client import CTraderClient
 from .config import ClientConfig
 
@@ -54,6 +55,7 @@ from .enums import (
 
 __all__ = [
     "AccountType",
+    "AuthTrigger",
     "CTraderClient",
     "ClientConfig",
     "ExecutionType",

{ctrader_api_client-0.4.3 → ctrader_api_client-0.5.0}/src/ctrader_api_client/auth/__init__.py

@@ -6,9 +6,11 @@ with automatic token refresh management.
 
 from .credentials import AccountCredentials
 from .manager import AuthManager
+from .trigger import AuthTrigger
 
 
 __all__ = [
     "AccountCredentials",
     "AuthManager",
+    "AuthTrigger",
 ]

{ctrader_api_client-0.4.3 → ctrader_api_client-0.5.0}/src/ctrader_api_client/auth/manager.py

@@ -30,6 +30,7 @@ from ..exceptions import (
 )
 from ..models import AccountSummary
 from .credentials import AccountCredentials
+from .trigger import AuthTrigger
 
 
 if TYPE_CHECKING:
@@ -39,7 +40,7 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 TokenRefreshCallback = Callable[[AccountCredentials], Awaitable[None]]
-AccountReadyCallback = Callable[[int, bool, bool], Awaitable[None]]  # (account_id, is_reconnect, is_reauth)
+AccountReadyCallback = Callable[[int, AuthTrigger], Awaitable[None]]  # (account_id, trigger)
 
 
 class AuthManager:
@@ -77,6 +78,8 @@ class AuthManager:
         refresh_retry_attempts: int = 3,
         refresh_retry_min_wait: float = 1.0,
         refresh_retry_max_wait: float = 30.0,
+        reauth_retry_min_wait: float = 1.0,
+        reauth_retry_max_wait: float = 60.0,
         on_tokens_refreshed: TokenRefreshCallback | None = None,
         on_account_ready: AccountReadyCallback | None = None,
     ) -> None:
@@ -96,10 +99,14 @@ class AuthManager:
                 Defaults to 1.0.
             refresh_retry_max_wait: Maximum wait between retries (seconds).
                 Defaults to 30.0.
+            reauth_retry_min_wait: Initial backoff between account recovery
+                re-auth attempts (seconds). Defaults to 1.0.
+            reauth_retry_max_wait: Maximum backoff between account recovery
+                re-auth attempts (seconds). Defaults to 60.0.
             on_tokens_refreshed: Async callback invoked when tokens are refreshed.
                 Receives the new AccountCredentials. Use this to persist tokens.
             on_account_ready: Async callback invoked when an account is authenticated.
-                Receives (account_id, is_reconnect). Use this to perform any initial client setup.
+                Receives (account_id, trigger). Use this to perform any initial client setup.
         """
         self._protocol = protocol
         self._client_id = client_id
@@ -109,12 +116,21 @@ class AuthManager:
         self._retry_attempts = refresh_retry_attempts
         self._retry_min_wait = refresh_retry_min_wait
         self._retry_max_wait = refresh_retry_max_wait
+        self._reauth_retry_min_wait = reauth_retry_min_wait
+        self._reauth_retry_max_wait = reauth_retry_max_wait
         self._on_tokens_refreshed = on_tokens_refreshed
         self._on_account_ready = on_account_ready
 
         # Account storage
         self._accounts: dict[int, AccountCredentials] = {}
 
+        # Accounts with a live, authorized server-side session
+        self._authorized_accounts: set[int] = set()
+
+        # Accounts awaiting recovery re-auth after a server-side disconnect
+        self._pending_reauth: set[int] = set()
+        self._reauth_signal = anyio.Event()
+
         # Background task management
         self._task_group: anyio.abc.TaskGroup | None = None
         self._task_scope: anyio.CancelScope | None = None
@@ -130,9 +146,25 @@ class AuthManager:
 
     @property
     def authenticated_accounts(self) -> list[int]:
-        """List of authenticated account IDs."""
+        """List of account IDs the manager holds credentials for."""
         return list(self._accounts.keys())
 
+    @property
+    def authorized_accounts(self) -> list[int]:
+        """List of account IDs with a live, authorized server-side session."""
+        return list(self._authorized_accounts)
+
+    def is_account_authorized(self, account_id: int) -> bool:
+        """Whether the account currently has a live, authorized session.
+
+        Returns False after a server-side account disconnect until recovery
+        re-authentication succeeds.
+
+        Args:
+            account_id: The cTID trader account ID.
+        """
+        return account_id in self._authorized_accounts
+
     def get_credentials(self, account_id: int) -> AccountCredentials | None:
         """Get credentials for an account.
 
@@ -179,7 +211,10 @@ class AuthManager:
         return response
 
     async def authenticate_account(
-        self, credentials: AccountCredentials, timeout: float = 30.0, reauth: bool = False, reconnect: bool = False
+        self,
+        credentials: AccountCredentials,
+        timeout: float = 30.0,
+        trigger: AuthTrigger = AuthTrigger.INITIAL,
     ) -> ProtoOAAccountAuthRes:
         """Authenticate a trading account.
 
@@ -188,9 +223,9 @@ class AuthManager:
         Args:
             credentials: The account credentials including tokens.
             timeout: Request timeout in seconds.
-            reauth: Whether this is a re-authentication (token refresh) or initial auth.
-            reconnect: Whether this authentication is happening during a connection reconnect. This can be used
-                to differentiate between a token refresh and a full reconnect scenario in the account ready callback.
+            trigger: Why the authentication is happening. Threaded through to
+                the account-ready callback so subscription restoration can be
+                driven correctly (see AuthTrigger).
 
         Returns:
             The authentication response from the server.
@@ -199,10 +234,10 @@ class AuthManager:
             APIError: If authentication fails.
             CTraderConnectionTimeoutError: If request times out.
         """
-        if reauth:
-            logger.debug("Re-authenticating account %d", credentials.account_id)
-        else:
+        if trigger is AuthTrigger.INITIAL:
             logger.debug("Authenticating account %d", credentials.account_id)
+        else:
+            logger.debug("Re-authenticating account %d (%s)", credentials.account_id, trigger.value)
 
         request = ProtoOAAccountAuthReq(
             ctid_trader_account_id=credentials.account_id,
@@ -217,14 +252,16 @@ class AuthManager:
                 description=f"Expected ProtoOAAccountAuthRes, got {type(response).__name__}",
             )
 
-        # Store credentials for refresh monitoring
+        # Store credentials for refresh monitoring and mark the session live
         self._accounts[credentials.account_id] = credentials
+        self._authorized_accounts.add(credentials.account_id)
+        self._pending_reauth.discard(credentials.account_id)
         logger.debug("Account %d authenticated successfully", credentials.account_id)
 
         # Notify callback
         if self._on_account_ready is not None:
             try:
-                await self._on_account_ready(credentials.account_id, reconnect, reauth)
+                await self._on_account_ready(credentials.account_id, trigger)
             except Exception as e:
                 logger.warning(
                     "Account ready callback failed for account %d: %s",
@@ -368,15 +405,42 @@ class AuthManager:
         """
         if account_id in self._accounts:
             del self._accounts[account_id]
+            self._authorized_accounts.discard(account_id)
+            self._pending_reauth.discard(account_id)
             logger.debug("Account %d removed from auth manager", account_id)
             return True
         return False
 
+    def handle_account_disconnect(self, account_id: int) -> None:
+        """Handle a server-side account disconnect.
+
+        Marks the account's session as no longer authorized and schedules
+        recovery re-authentication on the existing connection. Idempotent while
+        a recovery is already pending for the account.
+
+        Args:
+            account_id: The cTID trader account ID reported as disconnected.
+        """
+        if account_id not in self._accounts:
+            return
+
+        self._authorized_accounts.discard(account_id)
+
+        if account_id in self._pending_reauth:
+            return
+
+        self._pending_reauth.add(account_id)
+        self._reauth_signal.set()
+        logger.warning(
+            "Account %d disconnected by server; scheduling re-authentication",
+            account_id,
+        )
+
     async def start(self) -> None:
-        """Start the token refresh monitor.
+        """Start the background monitors.
 
-        This runs a background task that periodically checks for expiring
-        tokens and refreshes them automatically.
+        Runs the token refresh monitor and the account recovery monitor, which
+        re-authenticates accounts dropped by a server-side disconnect.
         """
         if self._running:
             return
@@ -385,10 +449,11 @@ class AuthManager:
         self._task_group = anyio.create_task_group()
         await self._task_group.__aenter__()
         self._task_group.start_soon(self._refresh_loop)
-        logger.debug("Token refresh monitor started")
+        self._task_group.start_soon(self._reauth_loop)
+        logger.debug("Auth monitors started")
 
     async def stop(self) -> None:
-        """Stop the token refresh monitor."""
+        """Stop the background monitors."""
         self._running = False
 
         if self._task_scope is not None:
@@ -402,7 +467,49 @@ class AuthManager:
                 pass
             self._task_group = None
 
-        logger.debug("Token refresh monitor stopped")
+        self._authorized_accounts.clear()
+        self._pending_reauth.clear()
+
+        logger.debug("Auth monitors stopped")
+
+    async def _reauth_loop(self) -> None:
+        """Recover accounts dropped by a server-side account disconnect.
+
+        Waits for accounts flagged by handle_account_disconnect, then
+        re-authenticates them on the existing connection with capped
+        exponential backoff, retrying indefinitely until each succeeds or the
+        manager stops. A successful re-auth restores authorized state and emits
+        a ReadyEvent so subscriptions can be restored.
+        """
+        while self._running:
+            await self._reauth_signal.wait()
+            self._reauth_signal = anyio.Event()
+
+            backoff = self._reauth_retry_min_wait
+            while self._running and self._pending_reauth:
+                recovered_any = False
+                for account_id in list(self._pending_reauth):
+                    credentials = self._accounts.get(account_id)
+                    if credentials is None:
+                        self._pending_reauth.discard(account_id)
+                        continue
+                    try:
+                        await self.authenticate_account(credentials, trigger=AuthTrigger.ACCOUNT_REAUTH)
+                        recovered_any = True
+                    except Exception as e:
+                        logger.warning(
+                            "Recovery re-authentication for account %d failed, will retry: %s",
+                            account_id,
+                            e,
+                        )
+
+                if not self._pending_reauth:
+                    break
+
+                if recovered_any:
+                    backoff = self._reauth_retry_min_wait
+                await anyio.sleep(backoff)
+                backoff = min(backoff * 2, self._reauth_retry_max_wait)
 
     async def _refresh_loop(self) -> None:
         """Periodically check and refresh expiring tokens."""
@@ -488,7 +595,7 @@ class AuthManager:
                     )
 
                     # Re-authenticate the account with the new token
-                    await self.authenticate_account(new_credentials, reauth=True)
+                    await self.authenticate_account(new_credentials, trigger=AuthTrigger.TOKEN_REFRESH)
 
                     # Notify callback
                     if self._on_tokens_refreshed is not None:

ctrader_api_client-0.5.0/src/ctrader_api_client/auth/trigger.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class AuthTrigger(Enum):
+    """Reason an account authentication was performed.
+
+    Threaded through account authentication so downstream logic can
+    distinguish cases where the server-side session (and its subscriptions)
+    is lost from cases where it is preserved.
+    """
+
+    INITIAL = "INITIAL"
+    RECONNECT = "RECONNECT"
+    TOKEN_REFRESH = "TOKEN_REFRESH"
+    ACCOUNT_REAUTH = "ACCOUNT_REAUTH"

{ctrader_api_client-0.4.3 → ctrader_api_client-0.5.0}/src/ctrader_api_client/client.py

@@ -5,7 +5,7 @@ from collections.abc import Awaitable, Callable
 from typing import Any, TypeVar, overload
 
 from .api import AccountsAPI, MarketDataAPI, SymbolsAPI, TradingAPI
-from .auth import AuthManager
+from .auth import AuthManager, AuthTrigger
 from .config import ClientConfig
 from .connection import HeartbeatManager, Protocol, Transport
 from .events import (
@@ -170,6 +170,9 @@ class CTraderClient:
         # Set up reconnection handler
         self._protocol._on_reconnect = self._handle_reconnect
 
+        # Recover accounts dropped by a server-side disconnect
+        self._emitter.subscribe(AccountDisconnectEvent, self._handle_account_disconnect)
+
     # -------------------------------------------------------------------------
     # Properties
     # -------------------------------------------------------------------------
@@ -229,9 +232,21 @@ class CTraderClient:
 
     @property
     def is_connected(self) -> bool:
-        """Whether the client is connected to the server."""
+        """Whether the client is connected to the server (transport level)."""
         return self._connected and self._transport.is_connected
 
+    def is_account_authorized(self, account_id: int) -> bool:
+        """Whether the account currently has a live, authorized session.
+
+        Returns False after a server-side account disconnect until recovery
+        re-authentication succeeds. Distinct from is_connected, which only
+        reflects the transport-level connection.
+
+        Args:
+            account_id: The cTID trader account ID.
+        """
+        return self._auth.is_account_authorized(account_id)
+
     @property
     def protocol(self) -> Protocol:
         """Direct access to the protocol layer.
@@ -288,24 +303,29 @@ class CTraderClient:
         self._connected = False
         logger.debug("Connection closed")
 
-    async def _emit_ready_event(self, account_id: int, is_reconnect: bool, is_reauth: bool) -> None:
+    async def _emit_ready_event(self, account_id: int, trigger: AuthTrigger) -> None:
         """Emit ReadyEvent when an account is authenticated.
 
-        Called by AuthManager after successful account authentication.
-
-        Does NOT emit if this is a re-auth with no reconnection (e.g. token refresh), since subscriptions
-        are not lost in that case and users don't need to restore them.
+        Called by AuthManager after successful account authentication. Emitted
+        for every authentication that (re)establishes a server-side session and
+        therefore requires subscriptions to be (re)applied: INITIAL, RECONNECT,
+        and ACCOUNT_REAUTH. Suppressed for TOKEN_REFRESH, where the session and
+        its subscriptions remain intact.
 
         Args:
             account_id: The authenticated account ID.
-            is_reconnect: True if this is a re-authentication after reconnection.
+            trigger: Why the authentication occurred.
         """
-        if is_reauth and not is_reconnect:
-            # Don't emit ReadyEvent for token refresh re-auth, since subscriptions are not lost
+        if trigger is AuthTrigger.TOKEN_REFRESH:
             return
 
+        is_reconnect = trigger in (AuthTrigger.RECONNECT, AuthTrigger.ACCOUNT_REAUTH)
         await self._emitter.emit(ReadyEvent(account_id=account_id, is_reconnect=is_reconnect))
 
+    async def _handle_account_disconnect(self, event: AccountDisconnectEvent) -> None:
+        """Route a server-side account disconnect into recovery re-auth."""
+        self._auth.handle_account_disconnect(event.account_id)
+
     async def _handle_reconnect(self) -> None:
         """Handle automatic reconnection by re-authenticating.
 
@@ -342,7 +362,7 @@ class CTraderClient:
         # Re-authenticate all previously authenticated accounts
         for account_id, credentials in list(self._auth._accounts.items()):
             try:
-                await self._auth.authenticate_account(credentials, reconnect=True)
+                await self._auth.authenticate_account(credentials, trigger=AuthTrigger.RECONNECT)
                 restored.append(account_id)
                 logger.debug("Re-authenticated account %d", account_id)
             except Exception as e:

{ctrader_api_client-0.4.3 → ctrader_api_client-0.5.0}/src/ctrader_api_client/events/types.py

@@ -197,7 +197,11 @@ class ClientDisconnectEvent:
 class AccountDisconnectEvent:
     """Account disconnect event.
 
-    Emitted when a specific account session is terminated.
+    Emitted when a specific account session is terminated by the server while
+    the underlying connection stays up. The client handles recovery
+    automatically: it re-authenticates the account on the existing connection
+    with backoff until it succeeds, then emits a ReadyEvent. This event is
+    informational; no user action is required to restore the session.
 
     Attributes:
         account_id: The cTID trader account ID.
@@ -287,12 +291,17 @@ class ReconnectedEvent:
 class ReadyEvent:
     """Emitted when an account is authenticated and ready for use.
 
-    Fired after both initial authentication and reconnection re-authentication.
-    Use this to set up subscriptions that should persist across reconnections.
+    Fired whenever a server-side session is (re)established and subscriptions
+    must be (re)applied: initial authentication, re-authentication after a
+    transport reconnection, and recovery after a server-side account
+    disconnect. It is not fired for token-refresh re-auth, where the session
+    and its subscriptions remain intact. Use this to set up subscriptions that
+    should persist across reconnections.
 
     Attributes:
         account_id: The cTID trader account ID that is now ready.
-        is_reconnect: True if this follows a reconnection, False for initial auth.
+        is_reconnect: True if this follows a reconnection or account-disconnect
+            recovery, False for initial authentication.
     """
 
     account_id: int

{ctrader_api_client-0.4.3 → ctrader_api_client-0.5.0}/tests/unit/auth/test_manager.py

@@ -18,6 +18,7 @@ from ctrader_api_client._internal.proto import (
 )
 from ctrader_api_client.auth.credentials import AccountCredentials
 from ctrader_api_client.auth.manager import AuthManager
+from ctrader_api_client.auth.trigger import AuthTrigger
 from ctrader_api_client.connection.protocol import Protocol
 from ctrader_api_client.exceptions import AccountNotFoundError, APIError, TokenRefreshError
 
@@ -773,3 +774,189 @@ class TestAuthenticateByTraderLogin:
         assert mock_protocol.send_request.call_count == 2
         for call in mock_protocol.send_request.call_args_list:
             assert call[1]["timeout"] == 45.0
+
+
+class TestAuthorizedState:
+    """Tests for account authorization tracking."""
+
+    @pytest.mark.anyio
+    async def test_authenticate_marks_account_authorized(
+        self,
+        mock_protocol: MagicMock,
+        sample_credentials: AccountCredentials,
+    ) -> None:
+        mock_protocol.send_request.return_value = ProtoOAAccountAuthRes(
+            ctid_trader_account_id=sample_credentials.account_id
+        )
+
+        auth = AuthManager(protocol=mock_protocol, client_id="test", client_secret="test")
+
+        await auth.authenticate_account(sample_credentials)
+
+        assert auth.is_account_authorized(sample_credentials.account_id) is True
+        assert sample_credentials.account_id in auth.authorized_accounts
+
+    @pytest.mark.anyio
+    async def test_handle_disconnect_deauthorizes_known_account(
+        self,
+        mock_protocol: MagicMock,
+        sample_credentials: AccountCredentials,
+    ) -> None:
+        mock_protocol.send_request.return_value = ProtoOAAccountAuthRes(
+            ctid_trader_account_id=sample_credentials.account_id
+        )
+
+        auth = AuthManager(protocol=mock_protocol, client_id="test", client_secret="test")
+        await auth.authenticate_account(sample_credentials)
+
+        auth.handle_account_disconnect(sample_credentials.account_id)
+
+        assert auth.is_account_authorized(sample_credentials.account_id) is False
+        assert sample_credentials.account_id in auth._pending_reauth
+
+    def test_handle_disconnect_ignores_unknown_account(self, mock_protocol: MagicMock) -> None:
+        auth = AuthManager(protocol=mock_protocol, client_id="test", client_secret="test")
+
+        auth.handle_account_disconnect(99999)
+
+        assert 99999 not in auth._pending_reauth
+
+    @pytest.mark.anyio
+    async def test_handle_disconnect_is_idempotent(
+        self,
+        mock_protocol: MagicMock,
+        sample_credentials: AccountCredentials,
+    ) -> None:
+        mock_protocol.send_request.return_value = ProtoOAAccountAuthRes(
+            ctid_trader_account_id=sample_credentials.account_id
+        )
+
+        auth = AuthManager(protocol=mock_protocol, client_id="test", client_secret="test")
+        await auth.authenticate_account(sample_credentials)
+
+        auth.handle_account_disconnect(sample_credentials.account_id)
+        auth.handle_account_disconnect(sample_credentials.account_id)
+
+        assert auth._pending_reauth == {sample_credentials.account_id}
+
+    @pytest.mark.anyio
+    async def test_reconnect_reauth_clears_pending_recovery(
+        self,
+        mock_protocol: MagicMock,
+        sample_credentials: AccountCredentials,
+    ) -> None:
+        mock_protocol.send_request.return_value = ProtoOAAccountAuthRes(
+            ctid_trader_account_id=sample_credentials.account_id
+        )
+
+        auth = AuthManager(protocol=mock_protocol, client_id="test", client_secret="test")
+        await auth.authenticate_account(sample_credentials)
+        auth.handle_account_disconnect(sample_credentials.account_id)
+
+        assert sample_credentials.account_id in auth._pending_reauth
+        assert auth.is_account_authorized(sample_credentials.account_id) is False
+
+        # The transport-reconnect path re-authenticates the account directly.
+        await auth.authenticate_account(sample_credentials, trigger=AuthTrigger.RECONNECT)
+
+        assert sample_credentials.account_id not in auth._pending_reauth
+        assert auth.is_account_authorized(sample_credentials.account_id) is True
+
+
+class TestReauthLoop:
+    """Tests for the account recovery re-auth loop."""
+
+    @pytest.mark.anyio
+    async def test_recovers_disconnected_account(self, mock_protocol: MagicMock) -> None:
+        ready_calls: list[tuple[int, AuthTrigger]] = []
+
+        async def on_ready(account_id: int, trigger: AuthTrigger) -> None:
+            ready_calls.append((account_id, trigger))
+
+        auth = AuthManager(
+            protocol=mock_protocol,
+            client_id="test",
+            client_secret="test",
+            reauth_retry_min_wait=0.01,
+            reauth_retry_max_wait=0.02,
+            on_account_ready=on_ready,
+        )
+        creds = AccountCredentials(1, "token", "refresh", time.time() + 3600)
+        mock_protocol.send_request.return_value = ProtoOAAccountAuthRes(ctid_trader_account_id=1)
+
+        await auth.authenticate_account(creds)
+        await auth.start()
+        try:
+            auth.handle_account_disconnect(1)
+            assert auth.is_account_authorized(1) is False
+
+            with anyio.fail_after(1):
+                while not auth.is_account_authorized(1):
+                    await anyio.sleep(0.01)
+
+            assert auth.is_account_authorized(1) is True
+            assert 1 not in auth._pending_reauth
+        finally:
+            await auth.stop()
+
+        assert (1, AuthTrigger.ACCOUNT_REAUTH) in ready_calls
+
+    @pytest.mark.anyio
+    async def test_recovery_retries_until_success(self, mock_protocol: MagicMock) -> None:
+        auth = AuthManager(
+            protocol=mock_protocol,
+            client_id="test",
+            client_secret="test",
+            reauth_retry_min_wait=0.01,
+            reauth_retry_max_wait=0.02,
+        )
+        creds = AccountCredentials(1, "token", "refresh", time.time() + 3600)
+
+        mock_protocol.send_request.return_value = ProtoOAAccountAuthRes(ctid_trader_account_id=1)
+        await auth.authenticate_account(creds)
+
+        await auth.start()
+        try:
+            # Two failures, then a successful recovery re-auth.
+            mock_protocol.send_request.side_effect = [
+                APIError("CONNECTION_CLOSED"),
+                APIError("CONNECTION_CLOSED"),
+                ProtoOAAccountAuthRes(ctid_trader_account_id=1),
+            ]
+            auth.handle_account_disconnect(1)
+
+            with anyio.fail_after(1):
+                while not auth.is_account_authorized(1):
+                    await anyio.sleep(0.01)
+
+            assert auth.is_account_authorized(1) is True
+            # Two failed attempts plus the successful one.
+            assert mock_protocol.send_request.call_count >= 3
+        finally:
+            await auth.stop()
+
+    @pytest.mark.anyio
+    async def test_stop_clears_state_while_recovery_pending(self, mock_protocol: MagicMock) -> None:
+        auth = AuthManager(
+            protocol=mock_protocol,
+            client_id="test",
+            client_secret="test",
+            reauth_retry_min_wait=5.0,
+            reauth_retry_max_wait=5.0,
+        )
+        creds = AccountCredentials(1, "token", "refresh", time.time() + 3600)
+
+        mock_protocol.send_request.return_value = ProtoOAAccountAuthRes(ctid_trader_account_id=1)
+        await auth.authenticate_account(creds)
+
+        # Recovery re-auth keeps failing, so the account stays pending.
+        mock_protocol.send_request.side_effect = APIError("CONNECTION_CLOSED")
+
+        await auth.start()
+        auth.handle_account_disconnect(1)
+        await anyio.sleep(0.02)  # allow one failed attempt before the long backoff
+        await auth.stop()
+
+        assert auth._running is False
+        assert auth._authorized_accounts == set()
+        assert auth._pending_reauth == set()

{ctrader_api_client-0.4.3 → ctrader_api_client-0.5.0}/tests/unit/test_client.py

@@ -8,9 +8,15 @@ import pytest
 
 from ctrader_api_client import ClientConfig, CTraderClient
 from ctrader_api_client.api import AccountsAPI, MarketDataAPI, SymbolsAPI, TradingAPI
-from ctrader_api_client.auth import AuthManager
+from ctrader_api_client.auth import AuthManager, AuthTrigger
 from ctrader_api_client.connection import HeartbeatManager, Protocol, Transport
-from ctrader_api_client.events import EventEmitter, EventRouter, SpotEvent
+from ctrader_api_client.events import (
+    AccountDisconnectEvent,
+    EventEmitter,
+    EventRouter,
+    ReadyEvent,
+    SpotEvent,
+)
 
 
 @pytest.fixture
@@ -489,3 +495,55 @@ class TestCTraderClientEventOff:
         result = client.off(SpotEvent, my_handler)
 
         assert result is False
+
+
+class TestEmitReadyEvent:
+    """Test CTraderClient._emit_ready_event() trigger handling."""
+
+    @pytest.mark.anyio
+    async def test_token_refresh_suppresses_ready_event(self, config: ClientConfig):
+        client = CTraderClient(config)
+        client._emitter.emit = AsyncMock()
+
+        await client._emit_ready_event(1, AuthTrigger.TOKEN_REFRESH)
+
+        client._emitter.emit.assert_not_called()
+
+    @pytest.mark.anyio
+    @pytest.mark.parametrize(
+        ("trigger", "expected_is_reconnect"),
+        [
+            (AuthTrigger.INITIAL, False),
+            (AuthTrigger.RECONNECT, True),
+            (AuthTrigger.ACCOUNT_REAUTH, True),
+        ],
+    )
+    async def test_emits_ready_event_with_expected_flag(
+        self,
+        config: ClientConfig,
+        trigger: AuthTrigger,
+        expected_is_reconnect: bool,
+    ):
+        client = CTraderClient(config)
+        client._emitter.emit = AsyncMock()
+
+        await client._emit_ready_event(7, trigger)
+
+        client._emitter.emit.assert_called_once()
+        event = client._emitter.emit.call_args[0][0]
+        assert isinstance(event, ReadyEvent)
+        assert event.account_id == 7
+        assert event.is_reconnect is expected_is_reconnect
+
+
+class TestAccountDisconnectRouting:
+    """Test that account disconnect events drive recovery re-auth."""
+
+    @pytest.mark.anyio
+    async def test_account_disconnect_event_routes_to_auth(self, config: ClientConfig):
+        client = CTraderClient(config)
+        client._auth.handle_account_disconnect = MagicMock()
+
+        await client._emitter.emit(AccountDisconnectEvent(account_id=555))
+
+        client._auth.handle_account_disconnect.assert_called_once_with(555)

{ctrader_api_client-0.4.3 → ctrader_api_client-0.5.0}/uv.lock

@@ -201,7 +201,7 @@ wheels = [
 
 [[package]]
 name = "ctrader-api-client"
-version = "0.4.3"
+version = "0.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "anyio" },