fxsocket 0.1__py3-none-any.whl

fxsocket/errors.py

@@ -0,0 +1,163 @@
+"""Exception hierarchy and HTTP-response → exception mapping.
+
+A single :func:`error_from_response` maps both error envelopes the platform
+uses — the management API's ``{"error", "detail"}`` and the terminal API's
+``{"error", "message", "command_id"}`` — onto typed exceptions.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class FxSocketError(Exception):
+    """Base class for every error raised by the SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: str | None = None,
+        response: httpx.Response | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.response = response
+
+
+class AuthError(FxSocketError):
+    """Missing or invalid API key (HTTP 401), or no key configured."""
+
+
+class RateLimitError(FxSocketError):
+    """Too many requests (HTTP 429). ``retry_after`` is seconds, if given."""
+
+    def __init__(self, message: str, *, retry_after: float | None = None, **kw: Any):
+        super().__init__(message, **kw)
+        self.retry_after = retry_after
+
+
+class ValidationError(FxSocketError):
+    """The request was rejected as malformed (HTTP 400 / ``MRPC_VALIDATION``)."""
+
+
+class NotFoundError(FxSocketError):
+    """The referenced account or resource does not exist (HTTP 404)."""
+
+
+class AccountCapError(FxSocketError):
+    """Plan account limit reached (HTTP 402 ``account_cap_reached``)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        cap: int | None = None,
+        current: int | None = None,
+        **kw: Any,
+    ):
+        super().__init__(message, **kw)
+        self.cap = cap
+        self.current = current
+
+
+class NoSubscriptionError(FxSocketError):
+    """No plan permits linking accounts (HTTP 402 ``no_subscription``)."""
+
+
+class DuplicateAccountError(FxSocketError):
+    """This account is already linked (HTTP 409)."""
+
+
+class ConnectFailedError(FxSocketError):
+    """The broker rejected the login during account creation (HTTP 400).
+
+    ``code`` is one of ``invalid_credentials``, ``server_not_found``,
+    ``unknown``.
+    """
+
+
+class TerminalNotReadyError(FxSocketError):
+    """The account's terminal isn't reachable yet.
+
+    Raised on HTTP 503 (trade EA not registered) and when an account has no
+    ``rest_url`` — it is still provisioning, or is bridge-only and exposes no
+    per-account terminal API.
+    """
+
+
+class TerminalTimeoutError(FxSocketError):
+    """The terminal didn't answer in time (HTTP 504 / ``MRPC_TIMEOUT``)."""
+
+
+class UnsupportedOnPlatformError(FxSocketError):
+    """A requested feature doesn't exist on the account's platform.
+
+    Enforced client-side — e.g. stop-limit orders or MT5-only timeframes on
+    an MT4 account.
+    """
+
+
+class StreamError(FxSocketError):
+    """A WebSocket-level error (server error frame, or dropped connection)."""
+
+
+_CONNECT_CODES = frozenset({"invalid_credentials", "server_not_found", "unknown"})
+
+
+def error_from_response(resp: httpx.Response) -> FxSocketError:
+    """Build the most specific :class:`FxSocketError` for a failed response."""
+    status = resp.status_code
+    body: Any = None
+    try:
+        body = resp.json()
+    except ValueError:
+        body = None
+
+    code: str | None = None
+    detail: str | None = None
+    if isinstance(body, dict):
+        code = body.get("error")
+        detail = body.get("detail") or body.get("message")
+    message = detail or code or f"HTTP {status}"
+    common: dict[str, Any] = {
+        "status_code": status,
+        "code": code,
+        "response": resp,
+    }
+
+    if status == 401:
+        return AuthError(message, **common)
+    if status == 429:
+        raw = resp.headers.get("Retry-After")
+        retry = None
+        if raw:
+            try:
+                retry = float(raw)
+            except ValueError:
+                retry = None
+        return RateLimitError(message, retry_after=retry, **common)
+    if status == 404:
+        return NotFoundError(message, **common)
+    if status == 409:
+        return DuplicateAccountError(message, **common)
+    if status == 402:
+        if code == "account_cap_reached" and isinstance(body, dict):
+            return AccountCapError(
+                message, cap=body.get("cap"), current=body.get("current"), **common
+            )
+        return NoSubscriptionError(message, **common)
+    if status == 400:
+        if code in _CONNECT_CODES:
+            return ConnectFailedError(message, **common)
+        return ValidationError(message, **common)
+    if status == 503:
+        return TerminalNotReadyError(message, **common)
+    if status == 504:
+        return TerminalTimeoutError(message, **common)
+    return FxSocketError(message, **common)

fxsocket/management.py

@@ -0,0 +1,118 @@
+"""Account management — the public v1 API (``/v1/accounts``).
+
+Accessible as ``client.accounts`` on both :class:`~fxsocket.Client` and
+:class:`~fxsocket.AsyncClient`.
+"""
+
+from __future__ import annotations
+
+from ._http import AsyncHTTP, SyncHTTP
+from .enums import Platform
+from .models import Account
+
+
+def account_id_of(account: Account | str) -> str:
+    """Accept either an :class:`Account` or a bare id string."""
+    return account.id if isinstance(account, Account) else str(account)
+
+
+def _create_payload(
+    *,
+    server: str,
+    login: int,
+    password: str,
+    platform: Platform | str,
+    nickname: str,
+) -> dict[str, object]:
+    return {
+        "platform": Platform(platform).value,
+        "server": server,
+        "login": login,
+        "password": password,
+        "nickname": nickname,
+    }
+
+
+class Accounts:
+    """Synchronous account operations."""
+
+    def __init__(self, http: SyncHTTP) -> None:
+        self._http = http
+
+    def list(self) -> list[Account]:
+        """List every account owned by the authenticated user."""
+        data = self._http.request("GET", "/accounts")
+        return [Account.model_validate(row) for row in data]
+
+    def get(self, account: Account | str) -> Account:
+        """Fetch one account by id (use this to poll connection status)."""
+        data = self._http.request("GET", f"/accounts/{account_id_of(account)}")
+        return Account.model_validate(data)
+
+    def create(
+        self,
+        *,
+        server: str,
+        login: int,
+        password: str,
+        platform: Platform | str = Platform.MT5,
+        nickname: str = "",
+    ) -> Account:
+        """Link (connect) a new MT4/MT5 account. Returns it in ``connecting``
+        state when terminal pods are enabled, else ``connected``."""
+        data = self._http.request(
+            "POST",
+            "/accounts",
+            json=_create_payload(
+                server=server,
+                login=login,
+                password=password,
+                platform=platform,
+                nickname=nickname,
+            ),
+        )
+        return Account.model_validate(data)
+
+    def delete(self, account: Account | str) -> None:
+        """Unlink (disconnect) an account and tear down its terminal."""
+        self._http.request("DELETE", f"/accounts/{account_id_of(account)}")
+
+
+class AsyncAccounts:
+    """Asynchronous mirror of :class:`Accounts`."""
+
+    def __init__(self, http: AsyncHTTP) -> None:
+        self._http = http
+
+    async def list(self) -> list[Account]:
+        data = await self._http.request("GET", "/accounts")
+        return [Account.model_validate(row) for row in data]
+
+    async def get(self, account: Account | str) -> Account:
+        data = await self._http.request("GET", f"/accounts/{account_id_of(account)}")
+        return Account.model_validate(data)
+
+    async def create(
+        self,
+        *,
+        server: str,
+        login: int,
+        password: str,
+        platform: Platform | str = Platform.MT5,
+        nickname: str = "",
+    ) -> Account:
+        data = await self._http.request(
+            "POST",
+            "/accounts",
+            json=_create_payload(
+                server=server,
+                login=login,
+                password=password,
+                platform=platform,
+                nickname=nickname,
+            ),
+        )
+        return Account.model_validate(data)
+
+    async def delete(self, account: Account | str) -> None:
+        await self._http.request("DELETE", f"/accounts/{account_id_of(account)}")

fxsocket/models.py

@@ -0,0 +1,391 @@
+"""Pydantic models for FxSocket API payloads.
+
+Two families:
+
+* The management model (:class:`Account`) — the v1 API, which already speaks
+  ``snake_case`` and returns a genuine UTC ``created_at``.
+* Terminal payloads — ``camelCase`` on the wire (accepted via aliases). Two
+  deliberate typing choices keep these robust:
+
+  - **MetaTrader vocabulary fields** (``type``, ``kind``, ``entry``,
+    ``status``) are plain ``str``, not enums: the exact serialized casing
+    varies and a strict enum would raise on an unrecognized value. Compare
+    them against the str-enums in :mod:`fxsocket.enums` (``OrderOperation``,
+    ``HealthStatus``, …) — those compare equal to the raw string.
+  - **Timestamps** are ``str``, not ``datetime``: they are in *broker server
+    time* with a stylistic trailing ``Z``, so decoding them as UTC would be
+    silently wrong. Use :class:`ServerTimezone` to convert if needed.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+from .enums import Platform, TradingStatus
+
+
+class _Camel(BaseModel):
+    """Terminal payloads: read camelCase aliases, also accept field names."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        alias_generator=to_camel,
+        extra="ignore",
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Management API (v1)
+# --------------------------------------------------------------------------- #
+
+
+class Account(BaseModel):
+    """A linked trading account, as returned by the management API (v1).
+
+    ``rest_url`` / ``ws_url`` are where this account's terminal REST and
+    WebSocket APIs live. Both are empty until the account has a reachable
+    terminal (shared pod or private droplet); a bridge-only account exposes
+    none.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    id: str
+    nickname: str = ""
+    platform: Platform
+    server: str
+    login: int
+    status: TradingStatus
+    error: str = ""
+    rest_url: str = ""
+    ws_url: str = ""
+    created_at: datetime
+
+    @property
+    def has_terminal(self) -> bool:
+        """True when this account exposes a reachable terminal API."""
+        return bool(self.rest_url)
+
+
+# --------------------------------------------------------------------------- #
+# Terminal — account state
+# --------------------------------------------------------------------------- #
+
+
+class AccountSummary(_Camel):
+    """Live financial snapshot (``GET /AccountSummary``)."""
+
+    balance: float
+    credit: float
+    profit: float
+    equity: float
+    margin: float
+    free_margin: float
+    margin_level: float
+    leverage: int
+    currency: str
+    type: str
+
+
+class AccountInfo(_Camel):
+    """Static account identity + configuration (``GET /AccountInfo``).
+
+    On MT4 ``margin_mode`` is always ``"Hedging"`` and ``fifo_close`` always
+    ``False`` (the platform has no native equivalent).
+    """
+
+    name: str
+    login: int
+    server: str
+    company: str
+    currency: str
+    currency_digits: int
+    leverage: int
+    type: str
+    margin_mode: str
+    margin_so_mode: str
+    margin_call_level: float
+    stop_out_level: float
+    trade_allowed: bool
+    trade_expert: bool
+    limit_orders: int
+    fifo_close: bool
+
+
+class OpenedOrder(_Camel):
+    """An open position or resting pending order (``GET /OpenedOrders``)."""
+
+    ticket: int
+    symbol: str
+    type: str
+    kind: str
+    lots: float
+    open_price: float
+    current_price: float
+    stop_loss: float
+    take_profit: float
+    swap: float
+    profit: float
+    magic: int
+    comment: str
+    open_time: str
+
+    @property
+    def is_pending(self) -> bool:
+        """True for a resting pending order (vs. a live position)."""
+        return self.kind.lower() == "pending"
+
+
+class HistoryTrade(_Camel):
+    """A historical deal / closed order (``GET /OrderHistory``).
+
+    On MT4 this is one row per closed *order* (no per-deal granularity);
+    ``order`` aliases the ticket and ``entry`` is constant.
+    """
+
+    ticket: int
+    order: int
+    symbol: str
+    type: str
+    entry: str
+    volume: float
+    price: float
+    commission: float
+    swap: float
+    profit: float
+    magic: int
+    comment: str
+    time: str
+
+
+class PositionTrade(_Camel):
+    """A closed round-trip position (``GET /PositionHistory``)."""
+
+    position_id: int
+    symbol: str
+    type: str
+    volume: float
+    open_time: str
+    open_price: float
+    close_time: str
+    close_price: float
+    profit: float
+    swap: float
+    commission: float
+    net_profit: float
+    magic: int
+    comment: str
+
+
+class ServerTimezone(_Camel):
+    """Broker server clock + UTC offset (``GET /ServerTimezone``).
+
+    ``utc_offset_seconds`` is ``server_time - UTC``; subtract it from a
+    broker-server timestamp to get UTC.
+    """
+
+    server_time: str
+    utc_offset_seconds: int
+
+
+# --------------------------------------------------------------------------- #
+# Terminal — market data
+# --------------------------------------------------------------------------- #
+
+
+class Quote(_Camel):
+    """Latest tick for a symbol (``GET /getQuote``).
+
+    ``last`` / ``volume`` are ~0 on forex (and always 0 on MT4).
+    """
+
+    symbol: str
+    bid: float
+    ask: float
+    time: str
+    last: float
+    volume: int
+
+
+class SymbolInfo(_Camel):
+    """Contract specification for a symbol (``GET /SymbolInfo``)."""
+
+    symbol: str
+    description: str
+    digits: int
+    point: float
+    tick_size: float
+    tick_value: float
+    contract_size: float
+    volume_min: float
+    volume_max: float
+    volume_step: float
+    stops_level: int
+    freeze_level: int
+    spread: int
+    trade_mode: str
+    swap_long: float
+    swap_short: float
+    bid: float
+    ask: float
+    currency_base: str
+    currency_profit: str
+    currency_margin: str
+
+
+class Candle(_Camel):
+    """One OHLC bar (``GET /PriceHistory``). ``real_volume`` is 0 on MT4."""
+
+    time: str
+    open: float
+    high: float
+    low: float
+    close: float
+    tick_volume: int
+    real_volume: int
+    spread: int
+
+
+# --------------------------------------------------------------------------- #
+# Terminal — trading
+# --------------------------------------------------------------------------- #
+
+
+class OrderResult(_Camel):
+    """Result of an order send / modify / close.
+
+    ``success`` is true when ``retcode`` is DONE (10009) or PLACED (10010).
+    ``deal`` is the executed deal ticket (0 for pending placement, and always
+    0 on MT4); ``order`` is the resulting position / pending-order ticket.
+    """
+
+    success: bool
+    retcode: int
+    retcode_description: str
+    deal: int
+    order: int
+    volume: float
+    price: float
+    bid: float
+    ask: float
+    comment: str
+
+
+class MarginCalc(_Camel):
+    """Required margin for a hypothetical order (``GET /OrderCalcMargin``)."""
+
+    symbol: str
+    operation: str
+    volume: float
+    price: float
+    margin: float
+    currency: str
+
+
+class ProfitCalc(_Camel):
+    """Projected P/L for a hypothetical trade (``GET /OrderCalcProfit``)."""
+
+    symbol: str
+    operation: str
+    volume: float
+    price_open: float
+    price_close: float
+    profit: float
+    currency: str
+
+
+# --------------------------------------------------------------------------- #
+# Terminal — health
+# --------------------------------------------------------------------------- #
+
+
+class TerminalHealth(_Camel):
+    alive: bool
+    build: int = 0
+    ping_ms: int = 0
+
+
+class BrokerHealth(_Camel):
+    connected: bool
+    server: str = ""
+
+
+class AccountHealth(_Camel):
+    """Account section of ``/status``. ``currency`` / ``type`` are blank when
+    not logged in; ``login`` is always the configured account."""
+
+    logged_in: bool
+    login: int = 0
+    currency: str = ""
+    type: str = ""
+    trade_allowed: bool = False
+
+
+class BridgeHealth(_Camel):
+    version: str = ""
+    trade_ea_ready: bool = False
+    symbols_synced: bool = False
+
+
+class Health(_Camel):
+    """Full health snapshot (``GET /status``) — always HTTP 200.
+
+    ``status`` is one of ``ready`` / ``starting`` / ``degraded`` / ``down``
+    (compare against :class:`fxsocket.HealthStatus`).
+    """
+
+    status: str
+    terminal: TerminalHealth
+    broker: BrokerHealth
+    account: AccountHealth
+    bridge: BridgeHealth
+    server_time: str = ""
+
+    @property
+    def is_ready(self) -> bool:
+        return self.status == "ready"
+
+
+class HealthChecks(_Camel):
+    """PII-free probe body from ``/healthz`` and ``/livez``."""
+
+    status: str
+    terminal: bool
+    broker: bool
+    account: bool
+
+
+# --------------------------------------------------------------------------- #
+# Terminal — streaming payloads (the inner ``data`` of some WS events)
+# --------------------------------------------------------------------------- #
+
+
+class TradeEventData(_Camel):
+    """A trade transaction pushed on the ``trades`` stream.
+
+    ``deal`` / ``position`` are 0 on MT4 (no per-deal model); ``entry`` is the
+    deal direction (compare against :class:`fxsocket.DealEntry`).
+    """
+
+    deal: int
+    order: int
+    position: int
+    symbol: str
+    type: str
+    entry: str
+    volume: float
+    price: float
+    profit: float
+    comment: str
+    time: str
+
+
+class TerminalStatusData(_Camel):
+    """Terminal status pushed (~1/s) on the ``terminal`` stream."""
+
+    connected: bool
+    trade_allowed: bool
+    server_time: str

fxsocket/terminal/__init__.py

@@ -0,0 +1,45 @@
+"""Per-account terminal API — REST trading/market-data and WebSocket streaming.
+
+The endpoints for an account come from ``Account.rest_url`` / ``Account.ws_url``
+(populated by the management API), which already resolve shared-pod vs
+private-droplet hosting.
+"""
+
+from .client import AsyncTerminalClient, TerminalClient
+from .stream import (
+    AccountUpdate,
+    AsyncStream,
+    Bar,
+    PositionsUpdate,
+    Stream,
+    StreamErrorEvent,
+    StreamEvent,
+    StreamWarning,
+    Subscribed,
+    Subscriptions,
+    TerminalUpdate,
+    Tick,
+    TradeUpdate,
+    UnknownEvent,
+    Unsubscribed,
+)
+
+__all__ = [
+    "TerminalClient",
+    "AsyncTerminalClient",
+    "AsyncStream",
+    "Stream",
+    "StreamEvent",
+    "Tick",
+    "Bar",
+    "AccountUpdate",
+    "PositionsUpdate",
+    "TradeUpdate",
+    "TerminalUpdate",
+    "StreamWarning",
+    "Subscribed",
+    "Unsubscribed",
+    "StreamErrorEvent",
+    "Subscriptions",
+    "UnknownEvent",
+]