ctrader-api-client 0.6.0__tar.gz → 0.7.0__tar.gz

{ctrader_api_client-0.6.0 → ctrader_api_client-0.7.0}/.claude/settings.local.json

@@ -1,7 +1,8 @@
 {
   "permissions": {
     "allow": [
-      "Bash(git -C \"/home/tek/Desktop/Algo Trading/Live Trading/cTrader/ctrader-api-client\" log --oneline -10)"
+      "Bash(git -C \"/home/tek/Desktop/Algo Trading/Live Trading/cTrader/ctrader-api-client\" log --oneline -10)",
+      "Bash(git add *)"
     ]
   }
 }

ctrader_api_client-0.7.0/HARDENING.md

@@ -0,0 +1,251 @@
+# Architecture hardening
+
+Working notes for the `harden-architecture` branch. Everything below is against
+`master` at `8f649f2`.
+
+## Done
+
+Each item is one commit, in order.
+
+### Connection and auth lifecycle tests — `de41c4d`
+
+Edge cases the existing suite did not reach, added before any of the
+refactoring below so the refactoring had something to fail against: framing,
+reconnection, token lifecycle and client startup.
+
+### Typed request correlation — `bb66230`
+
+`Protocol` tracked in-flight requests across three parallel dicts keyed by
+message id. They could disagree. Replaced by a single object holding the event,
+the outcome and the expected response type, so a pending request is one thing
+that either exists or does not.
+
+### Event handler registration — `4131424`
+
+Registering a handler and unregistering it were written out separately at every
+call site. `on_event` now returns a disposer, and callers hold that instead of
+remembering how to undo their own registration.
+
+### Pluggable token storage — `b6dc7df`
+
+Added the `TokenStore` protocol and the option to pass one to the client. The
+client writes through it whenever tokens rotate, so a process that restarts can
+pick up where it left off rather than re-authenticating from credentials.
+
+Two things moved in passing, both breaking:
+
+- `AuthTrigger` moved from `auth/trigger.py`, which is gone, to `enums.py`. It
+  describes why a session was established, which the event types need and the
+  auth package should not own alone.
+- `ReadyEvent.is_reconnect` is now a property over a `trigger: AuthTrigger`
+  field. Reading it is unchanged; constructing a `ReadyEvent` is not.
+
+### Dead code and a start() guard — `de21183`
+
+Removed `on_handler_error()`, which nothing called. Made
+`HeartbeatManager.start()` idempotent: a second call used to overwrite the
+nursery reference and leave the first loop unreachable, so `stop()` could never
+find it.
+
+### Automatic subscription restore — `e0a3273`
+
+Subscriptions were restored by an explicit call after reconnection, which meant
+every reconnection path had to remember to make it. `MarketDataAPI` is now
+registered as a restorer and the reconnect path drives it.
+
+### TokenStore documentation — `2f17ac3`
+
+No code change. `TokenStore` is write-only by design — the library never reads
+it back, because only the caller knows which accounts a given process is
+responsible for. The name suggested otherwise, so the docstrings, the README
+example and `docs/api/client.md` now say so and show the startup branch the
+caller is expected to write.
+
+Deliberately **not** done: adding `load()` to the protocol. The library would
+have no reason to call it.
+
+### Composition root — `b3e6fb5`
+
+`CTraderClient.__init__` built eleven collaborators and wired them together,
+which made the client impossible to construct with a substitute for any one of
+them. That wiring moved verbatim to `composition.py` as `build_graph()`
+returning a frozen `ClientGraph`, and `CTraderClient.from_graph()` adopts one.
+
+Two ordering constraints in the wiring are load-bearing and are noted in the
+source: market data is built before auth because it is the restorer, and auth
+before the router because it is the recovery.
+
+Deliberately **not** done: a `build_client()` convenience wrapper.
+`build_graph` plus `from_graph` already covers it.
+
+### Lifecycle inversion — `bd92f44` — **breaking**
+
+`Protocol`, `HeartbeatManager` and `AuthManager` each held a task group handed
+to them by a `start()` call and exited by a later `stop()` call from a different
+task. `start()` replaced by `serve()`, which owns its nursery lexically and
+suspends inside it; `stop()` reduced to cancelling the scope, which is allowed
+from any task.
+
+`CTraderClient.connect()` and `.close()` are **gone**. `async with client:` is
+the only way to bring a client up. The nursery lives in the `async with` block,
+so a background loop that dies is raised out of it rather than discovered at
+shutdown.
+
+Three things fell out of this:
+
+- Every `except Exception: pass` in a `stop()` is gone; there is nothing left
+  to swallow.
+- Cleanup moved into each `serve()`'s `finally`, so cancellation now cleans up
+  as thoroughly as an orderly stop.
+- `task_group.start` rather than `start_soon` in the client means the reader is
+  provably live before anything is sent. That ordering used to be implicit.
+
+Test-side, `connected` and `serving` fixtures give the *test* ownership of the
+task group, for the same reason: a loop that dies mid-test surfaces at the end
+of it instead of vanishing.
+
+### B1 — connection supervisor — `9df080b` — **breaking**
+
+`Protocol` reported drops and recoveries through two callbacks the client set
+on it by hand, and `CTraderClient._lifecycle` knew the order transport,
+protocol, heartbeat and auth had to come up in. Both are gone.
+
+`ConnectionSupervisor` owns the transport, the protocol and the heartbeat.
+`serving()` is an async context manager rather than a `serve()`: connecting
+happens before the block is entered, so a server that is not there still raises
+`CTraderConnectionFailedError` instead of the `ExceptionGroup` a task group
+would make of it. `_lifecycle` is now the supervisor's block with auth and the
+router inside it.
+
+The callbacks became one port. `ConnectionListener` — `on_connection_lost` and
+`on_connection_restored` — is what `Protocol` reports to and what the
+supervisor fans out to. The supervisor puts the heartbeat back itself before
+notifying, because that is its own machinery rather than a listener's concern.
+
+The listener is `AuthManager`, not the client. Re-authenticating the
+application and every account after a reconnect, and reporting the outcome as
+`ReconnectedEvent`, is session work; it only lived on the client because the
+callback did. That takes ~70 lines off `client.py`, and puts the logic where
+B3's `SessionRecovery` would want it.
+
+Breaking: `Protocol.set_reconnect_handler` and `set_disconnect_handler` are
+replaced by `Protocol.set_listener`, and `AuthManager.handle_connection_lost`
+is now the private `_forget_sessions`, reached through the port.
+
+Test-side, a `make_graph` fixture hands tests the graph before the client
+adopts it, which is how the listener fan-out is exercised.
+
+### Exception shape at the client boundary — `ff6137a`
+
+Found while placing automatic application authentication. Since the lifecycle
+inversion, the task group holding the background tasks surrounds the `yield` in
+`_lifecycle`, so *every* exception leaving `async with client:` passed through
+it — and anyio wraps a lone exception as readily as a group. A caller's own
+`ValueError` came back as `ExceptionGroup: unhandled errors in a TaskGroup (1
+sub-exception)`, and `except CTraderConnectionFailedError` would have stopped
+matching anything the machinery raised.
+
+`__aenter__` and `__aexit__` now peel single-exception groups, recursively,
+since the supervisor's task group nests inside the client's. Several failures
+still arrive as a group, because that is what they are, and the block's own
+exception is returned to the caller untouched rather than re-raised.
+
+Not a break against `master`: this restores the shape callers had before the
+branch.
+
+### B3 — split AuthManager — `651da82` — **breaking**
+
+`auth/manager.py` was 751 lines doing four unrelated jobs. It is now four
+pieces, each with one:
+
+- `auth/_session.py` — `SessionStore`, joining the session state types already
+  there. It owns the dict, its invalidation and every query over it, so the
+  distinction between credentials (which outlive a link) and sessions (which do
+  not) is stated once instead of being re-derived by each collaborator.
+- `auth/_refresh.py` — `TokenRefresher`, the refresh loop, its retry policy and
+  the `TokenStore` write-through.
+- `auth/_recovery.py` — `SessionRecovery`, the reauth loop and the
+  `ConnectionListener` methods. It is also the `SessionRecovery` port the event
+  router already typed its collaborator as, so the names finally line up.
+- `auth/manager.py` — `AuthManager`, down to turning credentials into live
+  sessions.
+
+The refresher and the recovery monitor each serve themselves, so `_lifecycle`
+starts two tasks where it started one, and `AuthManager` no longer has a
+lifecycle of its own.
+
+The public surface was cut at the same time, on the rule that nothing returning
+a bare `ProtoOA` message should be public:
+
+- `authenticate_app` is called by the client as it connects, and on every
+  reconnect. A client that cannot authenticate does not open, and the failure
+  arrives as `ApplicationAuthError` thanks to the unwrapping above.
+- `authenticate_account` became `authenticate_trader`, returning nothing. The
+  `trigger` argument moved to the internal `establish`, where the refresher and
+  the recovery monitor use it.
+- `get_accounts` and `resolve_account_id` moved to `AccountsAPI` as
+  `list_by_token` and `resolve_account_id`. They are account queries, not auth.
+- `authenticate_by_trader_login` is gone with no replacement. Resolving a login
+  and authenticating an account are two steps, and the convenience of joining
+  them cost a second way to do the same thing:
+  `await client.auth.authenticate_trader(await store.load(account_id))` is now
+  the only shape, restart or not.
+
+`APIError.is_token_failure()` replaces the module-level helper, since three
+modules now need to ask.
+
+### Flat public surface — `6cc397c`
+
+The package exported `CTraderClient`, `ClientConfig` and seven of the fourteen
+enums "for easier access". The seven were an arbitrary subset: a caller reading
+`order.status`, `order.time_in_force`, `deal.status`, `symbol.trading_mode` or
+`account.access_rights` had to switch to `ctrader_api_client.enums` halfway down
+the file. `AccountCredentials`, the one type nobody can avoid constructing, sat
+two modules deep.
+
+The top level now carries what a caller names — what you construct, what you
+receive, what you catch — and the subpackages keep what the composition root
+wires. Sixty-eight names: the client and its config, the credentials and the two
+policies and the `TokenStore` protocol, every enum, every model, every event
+type, every exception. `AuthManager`, `SessionStore`, `TokenRefresher`,
+`SessionRecovery`, the emitter/publisher/router and everything under `api/`,
+`connection/` and `_internal/` stay where they are, since the client hands them
+to you already assembled.
+
+The result models are exported despite `Account`, `Order`, `Position`, `Symbol`
+and `Event` being names a trading codebase may well use itself. A name you
+receive is a name you annotate, and `import ctrader_api_client as ct` is there
+for anyone with a conflict.
+
+Additive: the subpackage paths still work. Importing costs nothing extra either,
+since `from .client import CTraderClient` already pulled the whole graph in.
+
+The `Environment` enum was deleted in passing — declared, documented, and
+referenced nowhere. `ClientConfig` takes a `host` string.
+
+## Open
+
+### Version bump and changelog
+
+The lifecycle inversion removes `connect()` and `close()` from the public API,
+and the connection supervisor replaces `Protocol.set_reconnect_handler` /
+`set_disconnect_handler` with `set_listener` and drops
+`AuthManager.handle_connection_lost`. The AuthManager split then removes
+`authenticate_app`, `authenticate_account`, `authenticate_by_trader_login`,
+`get_accounts` and `resolve_account_id` from `client.auth`, adding
+`authenticate_trader` in their place and moving the two queries to
+`client.accounts`. The `TokenStore` commit moved `AuthTrigger` out of
+`auth.trigger` into `enums`, and turned `ReadyEvent.is_reconnect` into a
+property over a new `trigger` field, which breaks anyone constructing the event
+themselves. This needs a bump from `0.6.0` and a note saying so.
+
+The flat surface is additive and breaks nobody, but the `Environment` enum it
+deleted was public, so it belongs in the same note. Nothing else on the branch
+breaks a caller.
+
+### Smaller things noticed but not acted on
+
+- `client.py` is down to 501 lines, nearly all delegation and docstrings.
+- `protocol.py` is 550 lines and does framing, correlation, dispatch and
+  reconnection. Splitting it was never discussed; noting it as an observation
+  rather than a proposal.

{ctrader_api_client-0.6.0 → ctrader_api_client-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrader-api-client
-Version: 0.6.0
+Version: 0.7.0
 Summary: API Client to interact with the cTrader Open API spec
 Author-email: Elio <elioachukri@pm.me>
 License-File: LICENSE
@@ -51,8 +51,13 @@ pip install ctrader-api-client
 
 ```python
 import asyncio
-from ctrader_api_client import CTraderClient, ClientConfig
-from ctrader_api_client.events import ReadyEvent, SpotEvent
+from ctrader_api_client import (
+    AccountCredentials,
+    ClientConfig,
+    CTraderClient,
+    ReadyEvent,
+    SpotEvent,
+)
 
 config = ClientConfig(
     client_id="your_client_id",
@@ -67,21 +72,23 @@ async def on_price(event: SpotEvent):
     print(f"Price update: {event.bid}/{event.ask}")
 
 
-@client.on(ReadyEvent)
-async def on_ready(event: ReadyEvent):
-    """Called when account is authenticated and ready."""
-    await client.market_data.subscribe_spots(event.account_id, [270])
-
-
 async def main():
     async with client:
-        await client.auth.authenticate_app()
-        await client.auth.authenticate_by_trader_login(
+        account_id = await client.accounts.resolve_account_id(
+            "your_access_token",
             trader_login=12345678,
-            access_token="your_access_token",
-            refresh_token="your_refresh_token",
-            expires_at=1778617423,
         )
+        await client.auth.authenticate_trader(
+            AccountCredentials(
+                account_id=account_id,
+                access_token="your_access_token",
+                refresh_token="your_refresh_token",
+                expires_at=1778617423,
+            )
+        )
+
+        # Subscribe once. The client re-applies this after any reconnection.
+        await client.market_data.subscribe_spots(account_id, [270])
 
         # Keep running to receive events
         await asyncio.Event().wait()
@@ -108,15 +115,19 @@ For production applications, implement the OAuth flow according to the [cTrader
 ### Authentication
 
 ```python
-# Authenticate the application
-await client.auth.authenticate_app()
+# The application is authenticated as the client connects.
+
+# Discover the account behind a trader login
+account_id = await client.accounts.resolve_account_id("...", trader_login=12345678)
 
 # Authenticate a trading account
-creds = await client.auth.authenticate_by_trader_login(
-    trader_login=12345678,
-    access_token="...",
-    refresh_token="...",
-    expires_at=1778617423,
+await client.auth.authenticate_trader(
+    AccountCredentials(
+        account_id=account_id,
+        access_token="...",
+        refresh_token="...",
+        expires_at=1778617423,
+    )
 )
 
 # Tokens are automatically refreshed before expiry. A refresh that fails is
@@ -124,6 +135,75 @@ creds = await client.auth.authenticate_by_trader_login(
 # TokenRefreshFailedEvent so a persistently dead refresh token is observable.
 ```
 
+### Persisting Rotated Tokens
+
+Every refresh issues a new access **and** refresh token, and invalidates the old
+pair immediately. Pass a `TokenStore` and the client writes each new pair through
+as it is issued:
+
+```python
+from ctrader_api_client import AccountCredentials, CTraderClient, TokenStore
+
+
+class PostgresTokenStore(TokenStore):
+    def __init__(self, pool):
+        self._pool = pool
+
+    async def save(self, credentials: AccountCredentials) -> None:
+        await self._pool.execute(
+            """
+            INSERT INTO ctrader_tokens (account_id, access_token, refresh_token, expires_at)
+            VALUES ($1, $2, $3, $4)
+            ON CONFLICT (account_id) DO UPDATE SET
+                access_token = EXCLUDED.access_token,
+                refresh_token = EXCLUDED.refresh_token,
+                expires_at = EXCLUDED.expires_at
+            """,
+            credentials.account_id,
+            credentials.access_token,
+            credentials.refresh_token,
+            credentials.expires_at,
+        )
+
+    # Not part of the protocol. The client never reads the store; you do.
+    async def load(self, account_id: int) -> AccountCredentials | None:
+        row = await self._pool.fetchrow(
+            "SELECT access_token, refresh_token, expires_at FROM ctrader_tokens WHERE account_id = $1",
+            account_id,
+        )
+        if row is None:
+            return None
+        return AccountCredentials(account_id=account_id, **dict(row))
+
+
+client = CTraderClient(config, token_store=PostgresTokenStore(pool))
+```
+
+The save happens before the new token is put to use. A save that raises aborts
+that refresh, which is reported as a `TokenRefreshFailedEvent` and retried on the
+next check interval, so a transient storage outage recovers on its own.
+
+The protocol is write-only, because writing is the half the client has to do for
+you: rotation happens mid-session, at a moment you cannot observe. Reading back is
+yours, since only you know which accounts a given process is responsible for:
+
+```python
+store = PostgresTokenStore(pool)
+client = CTraderClient(config, token_store=store)
+
+async with client:
+    stored = await store.load(account_id)
+    if stored is None:
+        stored = AccountCredentials(
+            account_id=account_id,
+            access_token="your_access_token",
+            refresh_token="your_refresh_token",
+            expires_at=1778617423,
+        )
+
+    await client.auth.authenticate_trader(stored)
+```
+
 ### Market Data
 
 ```python
@@ -142,8 +222,7 @@ bars = await client.market_data.get_trendbars(
 ### Trading
 
 ```python
-from ctrader_api_client.models import NewOrderRequest, ClosePositionRequest
-from ctrader_api_client.enums import OrderType, OrderSide
+from ctrader_api_client import ClosePositionRequest, NewOrderRequest, OrderSide, OrderType
 
 # Place a market order
 request = NewOrderRequest(
@@ -168,11 +247,12 @@ await client.trading.close_position(account_id, close_position)
 ### Event Handling
 
 ```python
-from ctrader_api_client.events import (
-    SpotEvent,
+from ctrader_api_client import (
     ExecutionEvent,
     ReadyEvent,
     ReconnectedEvent,
+    SpotEvent,
+    SubscriptionRestoreFailedEvent,
     TokenRefreshFailedEvent,
 )
 
@@ -187,10 +267,11 @@ async def on_execution(event: ExecutionEvent):
     print(f"Order {event.order_id}: {event.execution_type}")
 
 # Account ready (fires on initial auth, after reconnection, and after account-disconnect recovery)
+# Subscriptions are already restored by this point; use it to reconcile your own state.
 @client.on(ReadyEvent)
 async def on_ready(event: ReadyEvent):
-    # Set up subscriptions here
-    await client.market_data.subscribe_spots(event.account_id, symbols)
+    if event.is_reconnect:
+        positions = await client.trading.get_open_positions(event.account_id)
 
 # Connection restored
 @client.on(ReconnectedEvent)
@@ -202,6 +283,11 @@ async def on_reconnected(event: ReconnectedEvent):
 @client.on(TokenRefreshFailedEvent, account_id=account_id)
 async def on_refresh_failed(event: TokenRefreshFailedEvent):
     print(f"Token refresh failed for {event.account_id}: {event.error}")
+
+# Market data could not be re-applied after a reconnection (retried on the next one)
+@client.on(SubscriptionRestoreFailedEvent, account_id=account_id)
+async def on_restore_failed(event: SubscriptionRestoreFailedEvent):
+    print(f"Account {event.account_id} is missing market data: {event.error}")
 ```
 
 ### Symbols
@@ -231,23 +317,28 @@ The client automatically handles connection drops:
 
 1. Reconnects with exponential backoff
 2. Re-authenticates the app and all accounts
-3. Emits `ReadyEvent` for each restored account (for resubscribing to market data)
-4. Emits `ReconnectedEvent` with summary of restored/failed accounts
+3. Re-applies each account's market data subscriptions
+4. Emits `ReadyEvent` for each restored account
+5. 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
+re-authenticated on the existing connection with backoff until it succeeds, its
+subscriptions are re-applied, and then a `ReadyEvent` is emitted. 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.
+Subscribe once, when you first authenticate. The client remembers what each
+account asked for and re-applies it before announcing the account as ready, so
+do not re-subscribe from a `ReadyEvent` handler — the server rejects a duplicate
+subscription. If restoration fails it stops at the first failure and emits a
+`SubscriptionRestoreFailedEvent`, keeping the intent so the next reconnection
+tries again.
 
 ## Configuration
 
 ```python
-from ctrader_api_client import ClientConfig
-from ctrader_api_client.auth import ReauthPolicy, RefreshPolicy
+from ctrader_api_client import ClientConfig, ReauthPolicy, RefreshPolicy
 
 config = ClientConfig(
     client_id="your_client_id",