fxsocket 0.1__py3-none-any.whl

fxsocket/__init__.py

@@ -0,0 +1,134 @@
+"""FxSocket Python SDK.
+
+Account management today (the v1 API); per-account terminal REST and
+WebSocket streaming for MT4/MT5 land in the next milestones.
+"""
+
+from __future__ import annotations
+
+from . import errors
+from ._version import __version__
+from .client import AsyncClient, Client
+from .enums import (
+    DealEntry,
+    HealthStatus,
+    OrderKind,
+    OrderOperation,
+    Platform,
+    Timeframe,
+    TradingStatus,
+)
+from .errors import (
+    AccountCapError,
+    AuthError,
+    ConnectFailedError,
+    DuplicateAccountError,
+    FxSocketError,
+    NoSubscriptionError,
+    NotFoundError,
+    RateLimitError,
+    StreamError,
+    TerminalNotReadyError,
+    TerminalTimeoutError,
+    UnsupportedOnPlatformError,
+    ValidationError,
+)
+from .models import (
+    Account,
+    AccountInfo,
+    AccountSummary,
+    Candle,
+    Health,
+    HealthChecks,
+    HistoryTrade,
+    MarginCalc,
+    OpenedOrder,
+    OrderResult,
+    PositionTrade,
+    ProfitCalc,
+    Quote,
+    ServerTimezone,
+    SymbolInfo,
+    TerminalStatusData,
+    TradeEventData,
+)
+from .terminal import (
+    AccountUpdate,
+    AsyncStream,
+    AsyncTerminalClient,
+    Bar,
+    PositionsUpdate,
+    Stream,
+    StreamErrorEvent,
+    StreamEvent,
+    StreamWarning,
+    Subscribed,
+    Subscriptions,
+    TerminalClient,
+    TerminalUpdate,
+    Tick,
+    TradeUpdate,
+    UnknownEvent,
+    Unsubscribed,
+)
+
+__all__ = [
+    "__version__",
+    "Client",
+    "AsyncClient",
+    "TerminalClient",
+    "AsyncTerminalClient",
+    "AsyncStream",
+    "Stream",
+    "StreamEvent",
+    "Tick",
+    "Bar",
+    "AccountUpdate",
+    "PositionsUpdate",
+    "TradeUpdate",
+    "TerminalUpdate",
+    "StreamWarning",
+    "Subscribed",
+    "Unsubscribed",
+    "StreamErrorEvent",
+    "Subscriptions",
+    "UnknownEvent",
+    "TradeEventData",
+    "TerminalStatusData",
+    "Account",
+    "AccountSummary",
+    "AccountInfo",
+    "OpenedOrder",
+    "HistoryTrade",
+    "PositionTrade",
+    "ServerTimezone",
+    "Quote",
+    "SymbolInfo",
+    "Candle",
+    "OrderResult",
+    "MarginCalc",
+    "ProfitCalc",
+    "Health",
+    "HealthChecks",
+    "Platform",
+    "TradingStatus",
+    "OrderOperation",
+    "OrderKind",
+    "DealEntry",
+    "HealthStatus",
+    "Timeframe",
+    "errors",
+    "FxSocketError",
+    "AuthError",
+    "RateLimitError",
+    "ValidationError",
+    "NotFoundError",
+    "AccountCapError",
+    "NoSubscriptionError",
+    "DuplicateAccountError",
+    "ConnectFailedError",
+    "TerminalNotReadyError",
+    "TerminalTimeoutError",
+    "UnsupportedOnPlatformError",
+    "StreamError",
+]

fxsocket/_http.py

@@ -0,0 +1,68 @@
+"""Thin transport helpers shared by the sync and async clients.
+
+The response handling is identical for both, so it lives in one place; the
+sync/async split is only in who awaits the network call.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ._version import __version__
+from .errors import error_from_response
+
+
+def auth_headers(api_key: str) -> dict[str, str]:
+    """Default headers carrying the API key for every request."""
+    return {
+        "X-API-Key": api_key,
+        "User-Agent": f"fxsocket-python/{__version__}",
+        "Accept": "application/json",
+    }
+
+
+def process_response(resp: httpx.Response) -> Any:
+    """Return the decoded JSON body, or raise a typed error on failure."""
+    if resp.is_success:
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+    raise error_from_response(resp)
+
+
+class SyncHTTP:
+    """Synchronous request wrapper over an :class:`httpx.Client`."""
+
+    def __init__(self, client: httpx.Client) -> None:
+        self._client = client
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+    ) -> Any:
+        resp = self._client.request(method, path, params=params, json=json)
+        return process_response(resp)
+
+
+class AsyncHTTP:
+    """Asynchronous request wrapper over an :class:`httpx.AsyncClient`."""
+
+    def __init__(self, client: httpx.AsyncClient) -> None:
+        self._client = client
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+    ) -> Any:
+        resp = await self._client.request(method, path, params=params, json=json)
+        return process_response(resp)

fxsocket/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1"

fxsocket/client.py

@@ -0,0 +1,254 @@
+"""Top-level entry points: :class:`Client` (sync) and :class:`AsyncClient`.
+
+Both expose ``.accounts`` (the management API), ``.terminal(account)`` (the
+per-account terminal REST client), and ``.stream(account)`` (WebSocket
+streaming — a sync :class:`~fxsocket.Stream` or an async
+:class:`~fxsocket.AsyncStream`).
+"""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+
+from ._http import AsyncHTTP, SyncHTTP, auth_headers
+from .config import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, ENV_API_KEY
+from .errors import AuthError, TerminalNotReadyError
+from .management import Accounts, AsyncAccounts
+from .models import Account
+from .terminal.client import AsyncTerminalClient, TerminalClient
+from .terminal.stream import AsyncStream, Stream
+
+
+def _resolve_api_key(api_key: str | None) -> str:
+    key = api_key or os.environ.get(ENV_API_KEY)
+    if not key:
+        raise AuthError(
+            "No API key. Pass api_key=... or set the "
+            f"{ENV_API_KEY} environment variable."
+        )
+    return key
+
+
+class Client:
+    """Synchronous FxSocket client.
+
+    Usage::
+
+        from fxsocket import Client
+
+        with Client(api_key="fxs_live_...") as fx:
+            for acct in fx.accounts.list():
+                print(acct.nickname, acct.status)
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        verify_terminal_tls: bool = True,
+    ) -> None:
+        self._api_key = _resolve_api_key(api_key)
+        self._timeout = timeout
+        #: Verify TLS for terminal calls. Private-hosting droplets use a
+        #: self-signed cert; set False (or pass a CA) to reach them.
+        self.verify_terminal_tls = verify_terminal_tls
+        self._http_client = httpx.Client(
+            base_url=base_url,
+            headers=auth_headers(self._api_key),
+            timeout=timeout,
+        )
+        #: Account management (the v1 API).
+        self.accounts = Accounts(SyncHTTP(self._http_client))
+        self._terminals: dict[tuple[str, str], TerminalClient] = {}
+
+    def terminal(
+        self,
+        account: Account,
+        *,
+        verify: bool | None = None,
+        timeout: float | None = None,
+    ) -> TerminalClient:
+        """Return a REST client bound to ``account``'s terminal.
+
+        Resolves the endpoint from ``account.rest_url`` (shared pod or private
+        droplet). Raises :class:`TerminalNotReadyError` when the account has no
+        terminal yet (still provisioning, or bridge-only). Clients are cached
+        per endpoint and closed by :meth:`close`. Pass ``verify=False`` for a
+        private droplet's self-signed certificate.
+        """
+        if not account.rest_url:
+            raise TerminalNotReadyError(
+                f"Account {account.id} has no terminal endpoint yet "
+                "(still provisioning, or bridge-only)."
+            )
+        key = (account.rest_url, account.platform.value)
+        cached = self._terminals.get(key)
+        if cached is None:
+            cached = TerminalClient(
+                base_url=account.rest_url,
+                api_key=self._api_key,
+                platform=account.platform,
+                verify=self.verify_terminal_tls if verify is None else verify,
+                timeout=self._timeout if timeout is None else timeout,
+            )
+            self._terminals[key] = cached
+        return cached
+
+    def stream(
+        self,
+        account: Account,
+        *,
+        verify: bool | None = None,
+        auto_reconnect: bool = True,
+    ) -> Stream:
+        """Open a synchronous WebSocket stream for ``account``.
+
+        Returns a context-managed :class:`~fxsocket.Stream`; use it as
+        ``with client.stream(account) as s:`` and iterate it. Raises
+        :class:`TerminalNotReadyError` if the account has no WS endpoint yet.
+        """
+        if not account.ws_url:
+            raise TerminalNotReadyError(
+                f"Account {account.id} has no WebSocket endpoint yet "
+                "(still provisioning, or bridge-only)."
+            )
+        verify_tls = self.verify_terminal_tls if verify is None else verify
+        api_key = self._api_key
+        platform = account.platform
+        ws_url = account.ws_url
+
+        def factory() -> AsyncStream:
+            return AsyncStream(
+                ws_url=ws_url,
+                api_key=api_key,
+                platform=platform,
+                verify=verify_tls,
+                auto_reconnect=auto_reconnect,
+            )
+
+        return Stream(factory)
+
+    def close(self) -> None:
+        try:
+            for term in self._terminals.values():
+                try:
+                    term.close()
+                except Exception:
+                    pass
+            self._terminals.clear()
+        finally:
+            self._http_client.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncClient:
+    """Asynchronous FxSocket client.
+
+    Usage::
+
+        from fxsocket import AsyncClient
+
+        async with AsyncClient(api_key="fxs_live_...") as fx:
+            accounts = await fx.accounts.list()
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        verify_terminal_tls: bool = True,
+    ) -> None:
+        self._api_key = _resolve_api_key(api_key)
+        self._timeout = timeout
+        self.verify_terminal_tls = verify_terminal_tls
+        self._http_client = httpx.AsyncClient(
+            base_url=base_url,
+            headers=auth_headers(self._api_key),
+            timeout=timeout,
+        )
+        self.accounts = AsyncAccounts(AsyncHTTP(self._http_client))
+        self._terminals: dict[tuple[str, str], AsyncTerminalClient] = {}
+
+    def terminal(
+        self,
+        account: Account,
+        *,
+        verify: bool | None = None,
+        timeout: float | None = None,
+    ) -> AsyncTerminalClient:
+        """Return an async REST client bound to ``account``'s terminal.
+
+        See :meth:`Client.terminal`. Clients are cached per endpoint and closed
+        by :meth:`aclose`.
+        """
+        if not account.rest_url:
+            raise TerminalNotReadyError(
+                f"Account {account.id} has no terminal endpoint yet "
+                "(still provisioning, or bridge-only)."
+            )
+        key = (account.rest_url, account.platform.value)
+        cached = self._terminals.get(key)
+        if cached is None:
+            cached = AsyncTerminalClient(
+                base_url=account.rest_url,
+                api_key=self._api_key,
+                platform=account.platform,
+                verify=self.verify_terminal_tls if verify is None else verify,
+                timeout=self._timeout if timeout is None else timeout,
+            )
+            self._terminals[key] = cached
+        return cached
+
+    def stream(
+        self,
+        account: Account,
+        *,
+        verify: bool | None = None,
+        auto_reconnect: bool = True,
+    ) -> AsyncStream:
+        """Open an async WebSocket stream for ``account``.
+
+        Returns an :class:`~fxsocket.AsyncStream`; use it as
+        ``async with client.stream(account) as s:`` and iterate it. Raises
+        :class:`TerminalNotReadyError` if the account has no WS endpoint yet.
+        """
+        if not account.ws_url:
+            raise TerminalNotReadyError(
+                f"Account {account.id} has no WebSocket endpoint yet "
+                "(still provisioning, or bridge-only)."
+            )
+        return AsyncStream(
+            ws_url=account.ws_url,
+            api_key=self._api_key,
+            platform=account.platform,
+            verify=self.verify_terminal_tls if verify is None else verify,
+            auto_reconnect=auto_reconnect,
+        )
+
+    async def aclose(self) -> None:
+        try:
+            for term in self._terminals.values():
+                try:
+                    await term.aclose()
+                except Exception:
+                    pass
+            self._terminals.clear()
+        finally:
+            await self._http_client.aclose()
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()

fxsocket/config.py

@@ -0,0 +1,12 @@
+"""Library-wide defaults."""
+
+from __future__ import annotations
+
+#: Base URL of the public management API (account CRUD + status).
+DEFAULT_BASE_URL = "https://api.fxsocket.com/v1"
+
+#: Default request timeout, in seconds, for REST calls.
+DEFAULT_TIMEOUT = 30.0
+
+#: Environment variable read when no ``api_key`` is passed explicitly.
+ENV_API_KEY = "FXSOCKET_API_KEY"

fxsocket/enums.py

@@ -0,0 +1,122 @@
+"""Enumerations mirroring the FxSocket / terminal API vocabulary.
+
+All are ``str`` enums, so they compare equal to the raw wire values and
+serialize back to them unchanged.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Platform(str, Enum):
+    """Trading platform of a linked account."""
+
+    MT4 = "mt4"
+    MT5 = "mt5"
+
+
+class TradingStatus(str, Enum):
+    """Unified, public connection status of an account (v1 ``status``)."""
+
+    CONNECTED = "connected"
+    CONNECTING = "connecting"
+    DISCONNECTED = "disconnected"
+    ERROR = "error"
+
+
+class OrderOperation(str, Enum):
+    """Order operation accepted by the terminal ``/OrderSend``.
+
+    All eight are accepted by both the MT4 and MT5 terminal APIs (the MT4
+    server's ``parse_operation`` maps ``BuyStopLimit``/``SellStopLimit`` too),
+    so the SDK does not gate operations by platform.
+    """
+
+    BUY = "Buy"
+    SELL = "Sell"
+    BUY_LIMIT = "BuyLimit"
+    SELL_LIMIT = "SellLimit"
+    BUY_STOP = "BuyStop"
+    SELL_STOP = "SellStop"
+    BUY_STOP_LIMIT = "BuyStopLimit"
+    SELL_STOP_LIMIT = "SellStopLimit"
+
+
+#: Operations that require a ``stop_limit_price``.
+STOP_LIMIT_OPERATIONS = frozenset(
+    {OrderOperation.BUY_STOP_LIMIT, OrderOperation.SELL_STOP_LIMIT}
+)
+
+#: Operations that are pending orders (require an entry ``price``).
+PENDING_OPERATIONS = frozenset(
+    {
+        OrderOperation.BUY_LIMIT,
+        OrderOperation.SELL_LIMIT,
+        OrderOperation.BUY_STOP,
+        OrderOperation.SELL_STOP,
+        OrderOperation.BUY_STOP_LIMIT,
+        OrderOperation.SELL_STOP_LIMIT,
+    }
+)
+
+
+class OrderKind(str, Enum):
+    """Whether an opened row is a live position or a resting pending order."""
+
+    POSITION = "Position"
+    PENDING = "Pending"
+
+
+class DealEntry(str, Enum):
+    """Direction of a deal in trade history / the ``trades`` stream."""
+
+    IN = "In"
+    OUT = "Out"
+    IN_OUT = "InOut"
+
+
+class HealthStatus(str, Enum):
+    """Roll-up status reported by the terminal ``/status`` endpoint."""
+
+    READY = "ready"
+    STARTING = "starting"
+    DEGRADED = "degraded"
+    DOWN = "down"
+
+
+class Timeframe(str, Enum):
+    """Candle timeframes.
+
+    The MT5-only members (``M2``, ``M3``, ``H2``, ``H6``, ``H8``, ``H12``)
+    are rejected client-side for MT4 accounts.
+    """
+
+    M1 = "M1"
+    M2 = "M2"
+    M3 = "M3"
+    M5 = "M5"
+    M15 = "M15"
+    M30 = "M30"
+    H1 = "H1"
+    H2 = "H2"
+    H4 = "H4"
+    H6 = "H6"
+    H8 = "H8"
+    H12 = "H12"
+    D1 = "D1"
+    W1 = "W1"
+    MN1 = "MN1"
+
+
+#: Timeframes that only MT5 supports.
+MT5_ONLY_TIMEFRAMES = frozenset(
+    {
+        Timeframe.M2,
+        Timeframe.M3,
+        Timeframe.H2,
+        Timeframe.H6,
+        Timeframe.H8,
+        Timeframe.H12,
+    }
+)