fxsocket 0.6.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fxsocket
-Version: 0.6.0
+Version: 0.7.0
 Summary: Python SDK for the FxSocket API — MT4/MT5 account management, trading, and real-time streaming.
 Project-URL: Homepage, https://fxsocket.com
 Project-URL: Documentation, https://api.fxsocket.com/v1/docs
@@ -443,7 +443,8 @@ with Client(api_key="fxs_live_...", verify_terminal_tls=False) as fx:
             server, server="ICMarkets-Demo", login=1150125, password="..."
         )
     except SlotsFullError as err:
-        print(f"Server full ({err.used}/{err.cap}) — raise the limit in the dashboard.")
+        print(f"Server full ({err.used}/{err.cap})")
+        server = fx.private_servers.resize(server, slots=err.cap + 1)
 
     # Poll until the on-server agent has the terminal up, then trade as usual.
     while True:
@@ -460,8 +461,68 @@ Accounts on a private server are traded and streamed exactly like
 shared-cluster accounts — their `rest_url` / `ws_url` simply point at the
 server's dedicated IP. The server presents a self-signed certificate, so reach
 it with `Client(..., verify_terminal_tls=False)` (or supply a pinned CA).
-*Purchasing* a server, canceling, and slot changes happen in the dashboard;
-the API deliberately exposes no billing operations.
+
+`server.cancel_at_period_end` is `True` once a server has been told to stop
+instead of renewing; it then runs until `server.period_end` and expires.
+
+### Buying, resizing and canceling
+
+`fx.private_servers.regions()` returns where servers may run, how big they may
+be and what that costs — call it before buying rather than hardcoding slugs:
+
+```python
+options = fx.private_servers.regions()
+if options.enabled:
+    print(options.region_codes)                     # ['fra1', 'lon1', ...]
+    print(options.max_slots, options.max_servers)
+    print(options.monthly_price_eur(3))             # Decimal('45') — 3 slots/month
+```
+
+`create()` buys one, charged to the prepaid balance immediately. It comes back
+`provisioning`; poll `get()` until it is `ready`, usually a couple of minutes:
+
+```python
+from fxsocket import InsufficientBalanceError, PrivateServerStatus, ServerLimitError
+
+try:
+    server = fx.private_servers.create(slots=2, region="fra1", name="prop-guard")
+except InsufficientBalanceError as err:
+    print(f"Top up {err.shortfall_eur} EUR first")
+except ServerLimitError:
+    print(f"Already own the maximum ({options.max_servers})")
+
+while server.status != PrivateServerStatus.READY:
+    time.sleep(10)
+    server = fx.private_servers.get(server)
+```
+
+`resize()` changes the slot count. Increases are prorated over the rest of the
+period and charged now (the renewal date doesn't move); decreases are free and
+apply at the next renewal, so paid-for capacity is never destroyed mid-month.
+Shrinking below the accounts already on the server raises
+`AccountsExceedTargetError` — remove accounts first:
+
+```python
+server = fx.private_servers.resize(server, slots=4)
+```
+
+`cancel()` stops the server renewing: it runs until `period_end`, then expires.
+`resume()` undoes that while the period lasts (afterwards the machine is gone
+and `AlreadyLapsedError` is raised). `delete()` destroys the machine and every
+account on it right away, with **no refund** for the rest of the prepaid month —
+prefer `cancel()` unless you really want it gone now:
+
+```python
+server = fx.private_servers.cancel(server)      # stop at period_end
+assert server.cancel_at_period_end
+server = fx.private_servers.resume(server)      # changed your mind
+fx.private_servers.delete(server)               # irreversible, no refund
+```
+
+All of these move the prepaid balance, so they only work on balance-funded
+servers — a card- or crypto-funded one raises `NotBalanceFundedError` (a
+`ForbiddenError` subclass) and is managed from the dashboard. Read-only
+`fxs_ro_…` keys get a plain `ForbiddenError`.
 
 ## Wallet
 
@@ -483,7 +544,8 @@ if not wallet.covers_upcoming:
 Affordability is cumulative — with 24 EUR and three 12 EUR renewals the
 first two are covered and the third is not — so `shortfall_eur` is the
 total gap, not the size of any single charge. Topping up happens in the
-dashboard; the SDK deliberately exposes no payment operations.
+dashboard; the balance is only ever *spent* through the SDK (account seats
+and `private_servers.create()` / `resize()`), never topped up.
 
 ## Timestamps
 

{fxsocket-0.6.0 → fxsocket-0.7.0}/README.md

@@ -416,7 +416,8 @@ with Client(api_key="fxs_live_...", verify_terminal_tls=False) as fx:
             server, server="ICMarkets-Demo", login=1150125, password="..."
         )
     except SlotsFullError as err:
-        print(f"Server full ({err.used}/{err.cap}) — raise the limit in the dashboard.")
+        print(f"Server full ({err.used}/{err.cap})")
+        server = fx.private_servers.resize(server, slots=err.cap + 1)
 
     # Poll until the on-server agent has the terminal up, then trade as usual.
     while True:
@@ -433,8 +434,68 @@ Accounts on a private server are traded and streamed exactly like
 shared-cluster accounts — their `rest_url` / `ws_url` simply point at the
 server's dedicated IP. The server presents a self-signed certificate, so reach
 it with `Client(..., verify_terminal_tls=False)` (or supply a pinned CA).
-*Purchasing* a server, canceling, and slot changes happen in the dashboard;
-the API deliberately exposes no billing operations.
+
+`server.cancel_at_period_end` is `True` once a server has been told to stop
+instead of renewing; it then runs until `server.period_end` and expires.
+
+### Buying, resizing and canceling
+
+`fx.private_servers.regions()` returns where servers may run, how big they may
+be and what that costs — call it before buying rather than hardcoding slugs:
+
+```python
+options = fx.private_servers.regions()
+if options.enabled:
+    print(options.region_codes)                     # ['fra1', 'lon1', ...]
+    print(options.max_slots, options.max_servers)
+    print(options.monthly_price_eur(3))             # Decimal('45') — 3 slots/month
+```
+
+`create()` buys one, charged to the prepaid balance immediately. It comes back
+`provisioning`; poll `get()` until it is `ready`, usually a couple of minutes:
+
+```python
+from fxsocket import InsufficientBalanceError, PrivateServerStatus, ServerLimitError
+
+try:
+    server = fx.private_servers.create(slots=2, region="fra1", name="prop-guard")
+except InsufficientBalanceError as err:
+    print(f"Top up {err.shortfall_eur} EUR first")
+except ServerLimitError:
+    print(f"Already own the maximum ({options.max_servers})")
+
+while server.status != PrivateServerStatus.READY:
+    time.sleep(10)
+    server = fx.private_servers.get(server)
+```
+
+`resize()` changes the slot count. Increases are prorated over the rest of the
+period and charged now (the renewal date doesn't move); decreases are free and
+apply at the next renewal, so paid-for capacity is never destroyed mid-month.
+Shrinking below the accounts already on the server raises
+`AccountsExceedTargetError` — remove accounts first:
+
+```python
+server = fx.private_servers.resize(server, slots=4)
+```
+
+`cancel()` stops the server renewing: it runs until `period_end`, then expires.
+`resume()` undoes that while the period lasts (afterwards the machine is gone
+and `AlreadyLapsedError` is raised). `delete()` destroys the machine and every
+account on it right away, with **no refund** for the rest of the prepaid month —
+prefer `cancel()` unless you really want it gone now:
+
+```python
+server = fx.private_servers.cancel(server)      # stop at period_end
+assert server.cancel_at_period_end
+server = fx.private_servers.resume(server)      # changed your mind
+fx.private_servers.delete(server)               # irreversible, no refund
+```
+
+All of these move the prepaid balance, so they only work on balance-funded
+servers — a card- or crypto-funded one raises `NotBalanceFundedError` (a
+`ForbiddenError` subclass) and is managed from the dashboard. Read-only
+`fxs_ro_…` keys get a plain `ForbiddenError`.
 
 ## Wallet
 
@@ -456,7 +517,8 @@ if not wallet.covers_upcoming:
 Affordability is cumulative — with 24 EUR and three 12 EUR renewals the
 first two are covered and the third is not — so `shortfall_eur` is the
 total gap, not the size of any single charge. Topping up happens in the
-dashboard; the SDK deliberately exposes no payment operations.
+dashboard; the balance is only ever *spent* through the SDK (account seats
+and `private_servers.create()` / `resize()`), never topped up.
 
 ## Timestamps
 

{fxsocket-0.6.0 → fxsocket-0.7.0}/src/fxsocket/__init__.py

@@ -30,6 +30,8 @@ from .enums import (
 )
 from .errors import (
     AccountCapError,
+    AccountsExceedTargetError,
+    AlreadyLapsedError,
     AuthError,
     ConnectFailedError,
     DuplicateAccountError,
@@ -38,10 +40,12 @@ from .errors import (
     IdempotencyError,
     InsufficientBalanceError,
     NoSubscriptionError,
+    NotBalanceFundedError,
     NotFoundError,
     PaymentRequiredError,
     RateLimitError,
     SeatLapsedError,
+    ServerLimitError,
     SlotsFullError,
     StreamError,
     TerminalNotReadyError,
@@ -78,9 +82,11 @@ from .models import (
     PositionTrade,
     PrivateServer,
     PrivateServerAccount,
+    PrivateServerOptions,
     ProfitCalc,
     Quote,
     ReadOnlyKey,
+    Region,
     ScopedAccount,
     ServerTimezone,
     SymbolInfo,
@@ -137,6 +143,8 @@ __all__ = [
     "Account",
     "PrivateServer",
     "PrivateServerAccount",
+    "PrivateServerOptions",
+    "Region",
     "ReadOnlyKey",
     "ScopedAccount",
     "OrderDefaults",
@@ -203,6 +211,10 @@ __all__ = [
     "SeatLapsedError",
     "DuplicateAccountError",
     "SlotsFullError",
+    "ServerLimitError",
+    "AccountsExceedTargetError",
+    "AlreadyLapsedError",
+    "NotBalanceFundedError",
     "IdempotencyError",
     "ConnectFailedError",
     "TerminalNotReadyError",

fxsocket-0.7.0/src/fxsocket/_version.py

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

{fxsocket-0.6.0 → fxsocket-0.7.0}/src/fxsocket/errors.py

@@ -38,7 +38,15 @@ class AuthError(FxSocketError):
 class ForbiddenError(FxSocketError):
     """The key is valid but may not do this (HTTP 403) — typically a
     read-only ``fxs_ro_…`` key on an endpoint that mutates state, such as
-    multi-account trading."""
+    multi-account trading.
+
+    Base class for :class:`NotBalanceFundedError`."""
+
+
+class NotBalanceFundedError(ForbiddenError):
+    """This private server is not paid from the prepaid balance (HTTP 403
+    ``not_balance_funded``). Card- and crypto-funded servers are resized
+    and canceled in the dashboard, since the API only moves balance."""
 
 
 class RateLimitError(FxSocketError):
@@ -128,7 +136,7 @@ class DuplicateAccountError(FxSocketError):
 
 class SlotsFullError(FxSocketError):
     """Every purchased slot on the private server is taken (HTTP 409
-    ``slots_full``). Raise the server's limit from the dashboard."""
+    ``slots_full``). Buy more with ``client.private_servers.resize()``."""
 
     def __init__(
         self,
@@ -143,6 +151,24 @@ class SlotsFullError(FxSocketError):
         self.cap = cap
 
 
+class ServerLimitError(FxSocketError):
+    """You already own as many private servers as you may (HTTP 409
+    ``server_limit_reached``) — see ``max_servers`` on
+    :class:`~fxsocket.PrivateServerOptions`."""
+
+
+class AccountsExceedTargetError(FxSocketError):
+    """The server holds more accounts than the requested slot count allows
+    (HTTP 409 ``accounts_exceed_target``). Remove accounts first, then
+    resize."""
+
+
+class AlreadyLapsedError(FxSocketError):
+    """The paid period has already run out, so the cancellation can no
+    longer be undone (HTTP 409 ``already_lapsed``) — the machine is gone;
+    buy a new server."""
+
+
 class IdempotencyError(FxSocketError):
     """A multi-account batch was refused because of its ``Idempotency-Key``.
 
@@ -228,6 +254,8 @@ def error_from_response(resp: httpx.Response) -> FxSocketError:
     if status == 401:
         return AuthError(message, **common)
     if status == 403:
+        if code == "not_balance_funded":
+            return NotBalanceFundedError(message, **common)
         return ForbiddenError(message, **common)
     if code in _IDEMPOTENCY_CODES:
         return IdempotencyError(message, **common)
@@ -247,6 +275,12 @@ def error_from_response(resp: httpx.Response) -> FxSocketError:
             return SlotsFullError(
                 message, used=body.get("used"), cap=body.get("cap"), **common
             )
+        if code == "server_limit_reached":
+            return ServerLimitError(message, **common)
+        if code == "accounts_exceed_target":
+            return AccountsExceedTargetError(message, **common)
+        if code == "already_lapsed":
+            return AlreadyLapsedError(message, **common)
         return DuplicateAccountError(message, **common)
     if status == 402:
         fields: dict[str, Any] = body if isinstance(body, dict) else {}

{fxsocket-0.6.0 → fxsocket-0.7.0}/src/fxsocket/management.py

@@ -18,6 +18,7 @@ from .models import (
     Account,
     PrivateServer,
     PrivateServerAccount,
+    PrivateServerOptions,
     ReadOnlyKey,
     Wallet,
 )
@@ -249,11 +250,22 @@ def _private_account_payload(
     }
 
 
+def _private_server_payload(*, slots: int, region: str, name: str) -> dict[str, object]:
+    body: dict[str, object] = {"slots": slots, "region": region}
+    if name:
+        body["name"] = name
+    return body
+
+
 class PrivateServers:
     """Synchronous private-server operations.
 
-    Read + on-server account management only: purchasing a server,
-    canceling, and slot changes happen in the dashboard.
+    Covers the whole lifecycle: :meth:`regions` to see what can be bought,
+    :meth:`create` to buy one from the prepaid balance, :meth:`resize`,
+    :meth:`cancel` / :meth:`resume`, :meth:`delete`, and
+    :meth:`add_account` / :meth:`remove_account` for the accounts on it.
+    Balance is the only payment method here — card and crypto purchases
+    need a checkout redirect, so those stay in the dashboard.
     """
 
     def __init__(self, http: SyncHTTP) -> None:
@@ -264,6 +276,15 @@ class PrivateServers:
         data = self._http.request("GET", "/private-servers")
         return [PrivateServer.model_validate(row) for row in data]
 
+    def regions(self) -> PrivateServerOptions:
+        """Where private servers may run, how big they may be, what it costs.
+
+        Returns the whole options payload, not just the region list — see
+        :class:`~fxsocket.PrivateServerOptions`.
+        """
+        data = self._http.request("GET", "/private-servers/regions")
+        return PrivateServerOptions.model_validate(data)
+
     def get(self, server: PrivateServer | str) -> PrivateServer:
         """Fetch one server by id (use this to poll account readiness)."""
         data = self._http.request(
@@ -271,6 +292,89 @@ class PrivateServers:
         )
         return PrivateServer.model_validate(data)
 
+    def create(self, *, slots: int, region: str, name: str = "") -> PrivateServer:
+        """Buy a dedicated server, charged to the prepaid balance now.
+
+        ``region`` must be one of the ``code`` values from :meth:`regions`,
+        ``slots`` how many accounts it should hold (priced
+        ``first_slot + additional_slot * (slots - 1)`` per month, billed
+        again every month until you :meth:`cancel` it) and ``name`` an
+        optional label for your own reference.
+
+        Comes back already ``provisioning`` — poll :meth:`get` until
+        ``status`` is ``ready``, usually a couple of minutes. Raises
+        :class:`~fxsocket.InsufficientBalanceError` when the balance does
+        not cover it, :class:`~fxsocket.ServerLimitError` when you already
+        own the maximum, and :class:`~fxsocket.ForbiddenError` when private
+        hosting is off for the deployment or the key is read-only.
+        """
+        data = self._http.request(
+            "POST",
+            "/private-servers",
+            json=_private_server_payload(slots=slots, region=region, name=name),
+        )
+        return PrivateServer.model_validate(data)
+
+    def resize(self, server: PrivateServer | str, *, slots: int) -> PrivateServer:
+        """Change how many accounts the server may hold.
+
+        Increases are prorated over what is left of the current period and
+        charged to the balance immediately; the renewal date does not move.
+        Decreases are free and take effect at the next renewal, so capacity
+        already paid for is never destroyed mid-period.
+
+        Raises :class:`~fxsocket.AccountsExceedTargetError` when more
+        accounts are on the server than the new limit allows (remove some
+        first), :class:`~fxsocket.InsufficientBalanceError` when the
+        balance does not cover a prorated increase, and
+        :class:`~fxsocket.NotBalanceFundedError` for card- or
+        crypto-funded servers.
+        """
+        data = self._http.request(
+            "PATCH",
+            f"/private-servers/{private_server_id_of(server)}",
+            json={"slots": slots},
+        )
+        return PrivateServer.model_validate(data)
+
+    def delete(self, server: PrivateServer | str) -> None:
+        """Destroy the machine and everything on it — irreversible.
+
+        The droplet is torn down, its IP released and every account hosted
+        on it removed. There is **no refund**: whatever is left of the
+        prepaid month is forfeited. To stop paying without losing the rest
+        of the period, use :meth:`cancel` instead.
+        """
+        self._http.request("DELETE", f"/private-servers/{private_server_id_of(server)}")
+
+    def cancel(self, server: PrivateServer | str) -> PrivateServer:
+        """Stop the server renewing, letting the paid period run out.
+
+        It keeps running until ``period_end``, then expires; nothing is
+        refunded and nothing is charged again. Prefer this to
+        :meth:`delete`, which forfeits the rest of the month. Reversible
+        with :meth:`resume` while the period lasts. Raises
+        :class:`~fxsocket.NotBalanceFundedError` for card- or
+        crypto-funded servers.
+        """
+        data = self._http.request(
+            "POST", f"/private-servers/{private_server_id_of(server)}/cancel"
+        )
+        return PrivateServer.model_validate(data)
+
+    def resume(self, server: PrivateServer | str) -> PrivateServer:
+        """Undo a :meth:`cancel`, so the server renews from the balance
+        again at the end of the current period.
+
+        Only works while it is still running: raises
+        :class:`~fxsocket.AlreadyLapsedError` once the paid period has
+        lapsed and the machine is gone — buy a new one with :meth:`create`.
+        """
+        data = self._http.request(
+            "DELETE", f"/private-servers/{private_server_id_of(server)}/cancel"
+        )
+        return PrivateServer.model_validate(data)
+
     def add_account(
         self,
         private_server: PrivateServer | str,
@@ -325,12 +429,49 @@ class AsyncPrivateServers:
         data = await self._http.request("GET", "/private-servers")
         return [PrivateServer.model_validate(row) for row in data]
 
+    async def regions(self) -> PrivateServerOptions:
+        data = await self._http.request("GET", "/private-servers/regions")
+        return PrivateServerOptions.model_validate(data)
+
     async def get(self, server: PrivateServer | str) -> PrivateServer:
         data = await self._http.request(
             "GET", f"/private-servers/{private_server_id_of(server)}"
         )
         return PrivateServer.model_validate(data)
 
+    async def create(self, *, slots: int, region: str, name: str = "") -> PrivateServer:
+        data = await self._http.request(
+            "POST",
+            "/private-servers",
+            json=_private_server_payload(slots=slots, region=region, name=name),
+        )
+        return PrivateServer.model_validate(data)
+
+    async def resize(self, server: PrivateServer | str, *, slots: int) -> PrivateServer:
+        data = await self._http.request(
+            "PATCH",
+            f"/private-servers/{private_server_id_of(server)}",
+            json={"slots": slots},
+        )
+        return PrivateServer.model_validate(data)
+
+    async def delete(self, server: PrivateServer | str) -> None:
+        await self._http.request(
+            "DELETE", f"/private-servers/{private_server_id_of(server)}"
+        )
+
+    async def cancel(self, server: PrivateServer | str) -> PrivateServer:
+        data = await self._http.request(
+            "POST", f"/private-servers/{private_server_id_of(server)}/cancel"
+        )
+        return PrivateServer.model_validate(data)
+
+    async def resume(self, server: PrivateServer | str) -> PrivateServer:
+        data = await self._http.request(
+            "DELETE", f"/private-servers/{private_server_id_of(server)}/cancel"
+        )
+        return PrivateServer.model_validate(data)
+
     async def add_account(
         self,
         private_server: PrivateServer | str,

{fxsocket-0.6.0 → fxsocket-0.7.0}/src/fxsocket/models.py

@@ -131,8 +131,8 @@ class PrivateServer(BaseModel):
     ``status`` is the server lifecycle — compare against
     :class:`fxsocket.PrivateServerStatus`. ``purchased_slots`` is the paid
     limit; ``used_slots`` how many accounts currently live on the server.
-    Purchasing, canceling and slot changes happen in the dashboard, not
-    the API.
+    ``cancel_at_period_end`` is true once the server has been told to stop
+    instead of renewing — it then runs until ``period_end`` and expires.
     """
 
     model_config = ConfigDict(populate_by_name=True, extra="ignore")
@@ -144,6 +144,7 @@ class PrivateServer(BaseModel):
     ip: str = ""
     purchased_slots: int = 0
     used_slots: int = 0
+    cancel_at_period_end: bool = False
     period_end: datetime | None = None
     accounts: list[PrivateServerAccount] = []
 
@@ -156,6 +157,52 @@ class PrivateServer(BaseModel):
         return max(self.purchased_slots - self.used_slots, 0)
 
 
+class Region(BaseModel):
+    """One place a private server can run in."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    code: str
+    label: str = ""
+
+
+class PrivateServerOptions(BaseModel):
+    """Where private servers may run, how big they may be and what that
+    costs (``GET /v1/private-servers/regions``).
+
+    ``enabled`` is false when private hosting is off for the deployment —
+    ``regions`` is then empty. Prices are integer EUR cents, and a server
+    costs ``first_slot_eur_cents + additional_slot_eur_cents * (slots -
+    1)`` per month; :meth:`monthly_price_eur_cents` does that arithmetic.
+    Treat the returned list as authoritative rather than hardcoding region
+    slugs.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    enabled: bool = True
+    regions: list[Region] = []
+    max_slots: int = 0
+    max_servers: int = 0
+    first_slot_eur_cents: int = 0
+    additional_slot_eur_cents: int = 0
+
+    @property
+    def region_codes(self) -> list[str]:
+        """Just the slugs, in the order the API returned them."""
+        return [region.code for region in self.regions]
+
+    def monthly_price_eur_cents(self, slots: int) -> int:
+        """What a server of ``slots`` accounts costs per month, in cents."""
+        if slots < 1:
+            raise ValueError("slots must be at least 1")
+        return self.first_slot_eur_cents + self.additional_slot_eur_cents * (slots - 1)
+
+    def monthly_price_eur(self, slots: int) -> Decimal:
+        """:meth:`monthly_price_eur_cents` as euros."""
+        return _eur(self.monthly_price_eur_cents(slots))
+
+
 # --------------------------------------------------------------------------- #
 # Management API (v1) — read-only keys (``/v1/readonly-keys``)
 # --------------------------------------------------------------------------- #

fxsocket-0.7.0/tests/test_private_servers.py

@@ -0,0 +1,421 @@
+"""Tests for the private-server management client (sync + async)."""
+
+from __future__ import annotations
+
+import json
+from decimal import Decimal
+
+import httpx
+import pytest
+import respx
+
+from fxsocket import (
+    AccountsExceedTargetError,
+    AlreadyLapsedError,
+    AsyncClient,
+    Client,
+    DuplicateAccountError,
+    InsufficientBalanceError,
+    NotBalanceFundedError,
+    PrivateAccountStatus,
+    PrivateServerStatus,
+    ServerLimitError,
+    SlotsFullError,
+)
+from fxsocket.errors import ForbiddenError
+
+BASE = "https://api.fxsocket.com/v1"
+
+SERVER_ID = "ecf2fa95-4177-4402-8a00-dea33ae0e79a"
+
+SERVER_ACCOUNT = {
+    "id": "22222222-2222-2222-2222-222222222222",
+    "nickname": "prop-1",
+    "platform": "mt5",
+    "server": "ICMarkets-Demo",
+    "login": 7001,
+    "status": "ready",
+    "rest_url": "https://159.223.244.125/22222222-2222-2222-2222-222222222222",
+    "ws_url": "wss://159.223.244.125/22222222-2222-2222-2222-222222222222/ws",
+    "trade_ea_symbol": "",
+    "created_at": "2026-07-16T08:00:00Z",
+}
+
+SERVER = {
+    "id": SERVER_ID,
+    "name": "My Prop Guard",
+    "status": "ready",
+    "region": "lon1",
+    "ip": "159.223.244.125",
+    "purchased_slots": 2,
+    "used_slots": 1,
+    "cancel_at_period_end": False,
+    "period_end": "2026-08-16T07:01:08Z",
+    "accounts": [SERVER_ACCOUNT],
+}
+
+
+REGIONS = {
+    "enabled": True,
+    "regions": [
+        {"code": "fra1", "label": "Frankfurt, Germany"},
+        {"code": "lon1", "label": "London, United Kingdom"},
+    ],
+    "max_slots": 10,
+    "max_servers": 3,
+    "first_slot_eur_cents": 1700,
+    "additional_slot_eur_cents": 1400,
+}
+
+
+def _client() -> Client:
+    return Client(api_key="fxs_live_test")
+
+
+@respx.mock
+def test_list_servers_parses_models() -> None:
+    respx.get(f"{BASE}/private-servers").mock(
+        return_value=httpx.Response(200, json=[SERVER])
+    )
+    with _client() as fx:
+        [server] = fx.private_servers.list()
+    assert server.name == "My Prop Guard"
+    assert server.status == PrivateServerStatus.READY
+    assert server.is_ready
+    assert server.ip == "159.223.244.125"
+    assert server.free_slots == 1
+    [account] = server.accounts
+    assert account.status == PrivateAccountStatus.READY
+    assert account.has_terminal
+
+
+@respx.mock
+def test_cancel_at_period_end_is_parsed() -> None:
+    canceled = {**SERVER, "cancel_at_period_end": True}
+    respx.get(f"{BASE}/private-servers").mock(
+        return_value=httpx.Response(200, json=[canceled])
+    )
+    with _client() as fx:
+        [server] = fx.private_servers.list()
+    assert server.cancel_at_period_end
+    assert server.period_end is not None
+
+
+@respx.mock
+def test_regions_parses_options_and_prices() -> None:
+    respx.get(f"{BASE}/private-servers/regions").mock(
+        return_value=httpx.Response(200, json=REGIONS)
+    )
+    with _client() as fx:
+        options = fx.private_servers.regions()
+    assert options.enabled
+    assert options.region_codes == ["fra1", "lon1"]
+    assert options.regions[0].label == "Frankfurt, Germany"
+    assert options.max_slots == 10
+    assert options.monthly_price_eur_cents(1) == 1700
+    assert options.monthly_price_eur_cents(3) == 4500
+    assert options.monthly_price_eur(3) == Decimal("45.00")
+    with pytest.raises(ValueError):
+        options.monthly_price_eur_cents(0)
+
+
+@respx.mock
+def test_regions_disabled_deployment() -> None:
+    respx.get(f"{BASE}/private-servers/regions").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "enabled": False,
+                "regions": [],
+                "max_slots": 0,
+                "max_servers": 0,
+                "first_slot_eur_cents": 0,
+                "additional_slot_eur_cents": 0,
+            },
+        )
+    )
+    with _client() as fx:
+        options = fx.private_servers.regions()
+    assert not options.enabled
+    assert options.region_codes == []
+
+
+@respx.mock
+def test_get_accepts_model_or_id() -> None:
+    route = respx.get(f"{BASE}/private-servers/{SERVER_ID}").mock(
+        return_value=httpx.Response(200, json=SERVER)
+    )
+    with _client() as fx:
+        by_id = fx.private_servers.get(SERVER_ID)
+        by_model = fx.private_servers.get(by_id)
+    assert route.call_count == 2
+    assert by_model.id == SERVER_ID
+
+
+@respx.mock
+def test_add_account_payload_and_model() -> None:
+    route = respx.post(f"{BASE}/private-servers/{SERVER_ID}/accounts").mock(
+        return_value=httpx.Response(201, json=SERVER_ACCOUNT)
+    )
+    with _client() as fx:
+        account = fx.private_servers.add_account(
+            SERVER_ID,
+            server="ICMarkets-Demo",
+            login=7001,
+            password="pw",
+            nickname="prop-1",
+        )
+    sent = json.loads(route.calls.last.request.content)
+    assert sent == {
+        "platform": "mt5",
+        "server": "ICMarkets-Demo",
+        "login": 7001,
+        "password": "pw",
+        "nickname": "prop-1",
+        "trade_ea_symbol": "",
+    }
+    assert account.login == 7001
+
+
+@respx.mock
+def test_slots_full_maps_to_typed_error() -> None:
+    respx.post(f"{BASE}/private-servers/{SERVER_ID}/accounts").mock(
+        return_value=httpx.Response(
+            409,
+            json={
+                "error": "slots_full",
+                "detail": "Server is full (2/2).",
+                "used": 2,
+                "cap": 2,
+            },
+        )
+    )
+    with _client() as fx:
+        with pytest.raises(SlotsFullError) as err:
+            fx.private_servers.add_account(
+                SERVER_ID, server="Demo", login=1, password="pw"
+            )
+    assert err.value.used == 2
+    assert err.value.cap == 2
+
+
+@respx.mock
+def test_duplicate_still_maps_to_duplicate_error() -> None:
+    respx.post(f"{BASE}/private-servers/{SERVER_ID}/accounts").mock(
+        return_value=httpx.Response(
+            409, json={"error": "duplicate", "detail": "Already linked."}
+        )
+    )
+    with _client() as fx:
+        with pytest.raises(DuplicateAccountError):
+            fx.private_servers.add_account(
+                SERVER_ID, server="Demo", login=1, password="pw"
+            )
+
+
+@respx.mock
+def test_remove_account() -> None:
+    account_id = SERVER_ACCOUNT["id"]
+    route = respx.delete(
+        f"{BASE}/private-servers/{SERVER_ID}/accounts/{account_id}"
+    ).mock(return_value=httpx.Response(204))
+    with _client() as fx:
+        fx.private_servers.remove_account(SERVER_ID, account_id)
+    assert route.called
+
+
+@respx.mock
+def test_create_payload_and_model() -> None:
+    route = respx.post(f"{BASE}/private-servers").mock(
+        return_value=httpx.Response(
+            201, json={**SERVER, "status": "provisioning", "accounts": []}
+        )
+    )
+    with _client() as fx:
+        server = fx.private_servers.create(slots=2, region="lon1", name="My Prop Guard")
+    assert json.loads(route.calls.last.request.content) == {
+        "slots": 2,
+        "region": "lon1",
+        "name": "My Prop Guard",
+    }
+    assert server.status == PrivateServerStatus.PROVISIONING
+    assert not server.is_ready
+
+
+@respx.mock
+def test_create_omits_blank_name() -> None:
+    route = respx.post(f"{BASE}/private-servers").mock(
+        return_value=httpx.Response(201, json=SERVER)
+    )
+    with _client() as fx:
+        fx.private_servers.create(slots=1, region="fra1")
+    assert json.loads(route.calls.last.request.content) == {
+        "slots": 1,
+        "region": "fra1",
+    }
+
+
+@respx.mock
+def test_create_insufficient_balance() -> None:
+    respx.post(f"{BASE}/private-servers").mock(
+        return_value=httpx.Response(
+            402,
+            json={
+                "error": "insufficient_balance",
+                "detail": "Balance does not cover it.",
+                "shortfall_eur_cents": 1200,
+            },
+        )
+    )
+    with _client() as fx:
+        with pytest.raises(InsufficientBalanceError) as err:
+            fx.private_servers.create(slots=2, region="lon1")
+    assert err.value.shortfall_eur == Decimal("12.00")
+
+
+@respx.mock
+def test_create_server_limit_reached() -> None:
+    respx.post(f"{BASE}/private-servers").mock(
+        return_value=httpx.Response(
+            409, json={"error": "server_limit_reached", "detail": "You own 3 of 3."}
+        )
+    )
+    with _client() as fx:
+        with pytest.raises(ServerLimitError) as err:
+            fx.private_servers.create(slots=1, region="lon1")
+    assert err.value.code == "server_limit_reached"
+    assert not isinstance(err.value, DuplicateAccountError)
+
+
+@respx.mock
+def test_resize_sends_slots() -> None:
+    route = respx.patch(f"{BASE}/private-servers/{SERVER_ID}").mock(
+        return_value=httpx.Response(200, json={**SERVER, "purchased_slots": 4})
+    )
+    with _client() as fx:
+        server = fx.private_servers.resize(SERVER_ID, slots=4)
+    assert json.loads(route.calls.last.request.content) == {"slots": 4}
+    assert server.purchased_slots == 4
+    assert server.free_slots == 3
+
+
+@respx.mock
+def test_resize_below_accounts_is_typed() -> None:
+    respx.patch(f"{BASE}/private-servers/{SERVER_ID}").mock(
+        return_value=httpx.Response(
+            409,
+            json={"error": "accounts_exceed_target", "detail": "2 accounts, 1 slot."},
+        )
+    )
+    with _client() as fx:
+        with pytest.raises(AccountsExceedTargetError):
+            fx.private_servers.resize(SERVER_ID, slots=1)
+
+
+@respx.mock
+def test_resize_not_balance_funded() -> None:
+    respx.patch(f"{BASE}/private-servers/{SERVER_ID}").mock(
+        return_value=httpx.Response(
+            403, json={"error": "not_balance_funded", "detail": "Card-funded server."}
+        )
+    )
+    with _client() as fx:
+        with pytest.raises(NotBalanceFundedError) as err:
+            fx.private_servers.resize(SERVER_ID, slots=4)
+    assert isinstance(err.value, ForbiddenError)
+
+
+@respx.mock
+def test_delete_server() -> None:
+    route = respx.delete(f"{BASE}/private-servers/{SERVER_ID}").mock(
+        return_value=httpx.Response(204)
+    )
+    with _client() as fx:
+        fx.private_servers.delete(SERVER_ID)
+    assert route.called
+
+
+@respx.mock
+def test_cancel_and_resume() -> None:
+    canceled = {**SERVER, "cancel_at_period_end": True}
+    cancel_route = respx.post(f"{BASE}/private-servers/{SERVER_ID}/cancel").mock(
+        return_value=httpx.Response(200, json=canceled)
+    )
+    resume_route = respx.delete(f"{BASE}/private-servers/{SERVER_ID}/cancel").mock(
+        return_value=httpx.Response(200, json=SERVER)
+    )
+    with _client() as fx:
+        stopped = fx.private_servers.cancel(SERVER_ID)
+        resumed = fx.private_servers.resume(stopped)
+    assert cancel_route.called and resume_route.called
+    assert stopped.cancel_at_period_end
+    assert not resumed.cancel_at_period_end
+
+
+@respx.mock
+def test_resume_after_lapse() -> None:
+    respx.delete(f"{BASE}/private-servers/{SERVER_ID}/cancel").mock(
+        return_value=httpx.Response(
+            409, json={"error": "already_lapsed", "detail": "Period has lapsed."}
+        )
+    )
+    with _client() as fx:
+        with pytest.raises(AlreadyLapsedError):
+            fx.private_servers.resume(SERVER_ID)
+
+
+@respx.mock
+def test_terminal_client_from_private_account() -> None:
+    respx.get(f"{BASE}/private-servers").mock(
+        return_value=httpx.Response(200, json=[SERVER])
+    )
+    with _client() as fx:
+        [server] = fx.private_servers.list()
+        term = fx.terminal(server.accounts[0], verify=False)
+    assert term is not None
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_mirror() -> None:
+    respx.get(f"{BASE}/private-servers").mock(
+        return_value=httpx.Response(200, json=[SERVER])
+    )
+    respx.post(f"{BASE}/private-servers/{SERVER_ID}/accounts").mock(
+        return_value=httpx.Response(201, json=SERVER_ACCOUNT)
+    )
+    respx.get(f"{BASE}/private-servers/regions").mock(
+        return_value=httpx.Response(200, json=REGIONS)
+    )
+    respx.post(f"{BASE}/private-servers").mock(
+        return_value=httpx.Response(201, json=SERVER)
+    )
+    respx.patch(f"{BASE}/private-servers/{SERVER_ID}").mock(
+        return_value=httpx.Response(200, json={**SERVER, "purchased_slots": 4})
+    )
+    respx.post(f"{BASE}/private-servers/{SERVER_ID}/cancel").mock(
+        return_value=httpx.Response(200, json={**SERVER, "cancel_at_period_end": True})
+    )
+    respx.delete(f"{BASE}/private-servers/{SERVER_ID}/cancel").mock(
+        return_value=httpx.Response(200, json=SERVER)
+    )
+    respx.delete(f"{BASE}/private-servers/{SERVER_ID}").mock(
+        return_value=httpx.Response(204)
+    )
+    async with AsyncClient(api_key="fxs_live_test") as fx:
+        [server] = await fx.private_servers.list()
+        account = await fx.private_servers.add_account(
+            server, server="ICMarkets-Demo", login=7001, password="pw"
+        )
+        options = await fx.private_servers.regions()
+        bought = await fx.private_servers.create(slots=2, region="lon1")
+        bigger = await fx.private_servers.resize(bought, slots=4)
+        stopped = await fx.private_servers.cancel(bought)
+        resumed = await fx.private_servers.resume(bought)
+        await fx.private_servers.delete(bought)
+    assert server.is_ready
+    assert options.region_codes == ["fra1", "lon1"]
+    assert bigger.purchased_slots == 4
+    assert stopped.cancel_at_period_end
+    assert not resumed.cancel_at_period_end
+    assert account.login == 7001

fxsocket-0.6.0/src/fxsocket/_version.py

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

fxsocket-0.6.0/tests/test_private_servers.py

@@ -1,181 +0,0 @@
-"""Tests for the private-server management client (sync + async)."""
-
-from __future__ import annotations
-
-import httpx
-import pytest
-import respx
-
-from fxsocket import (
-    AsyncClient,
-    Client,
-    DuplicateAccountError,
-    PrivateAccountStatus,
-    PrivateServerStatus,
-    SlotsFullError,
-)
-
-BASE = "https://api.fxsocket.com/v1"
-
-SERVER_ID = "ecf2fa95-4177-4402-8a00-dea33ae0e79a"
-
-SERVER_ACCOUNT = {
-    "id": "22222222-2222-2222-2222-222222222222",
-    "nickname": "prop-1",
-    "platform": "mt5",
-    "server": "ICMarkets-Demo",
-    "login": 7001,
-    "status": "ready",
-    "rest_url": "https://159.223.244.125/22222222-2222-2222-2222-222222222222",
-    "ws_url": "wss://159.223.244.125/22222222-2222-2222-2222-222222222222/ws",
-    "trade_ea_symbol": "",
-    "created_at": "2026-07-16T08:00:00Z",
-}
-
-SERVER = {
-    "id": SERVER_ID,
-    "name": "My Prop Guard",
-    "status": "ready",
-    "region": "lon1",
-    "ip": "159.223.244.125",
-    "purchased_slots": 2,
-    "used_slots": 1,
-    "period_end": "2026-08-16T07:01:08Z",
-    "accounts": [SERVER_ACCOUNT],
-}
-
-
-def _client() -> Client:
-    return Client(api_key="fxs_live_test")
-
-
-@respx.mock
-def test_list_servers_parses_models() -> None:
-    respx.get(f"{BASE}/private-servers").mock(
-        return_value=httpx.Response(200, json=[SERVER])
-    )
-    with _client() as fx:
-        [server] = fx.private_servers.list()
-    assert server.name == "My Prop Guard"
-    assert server.status == PrivateServerStatus.READY
-    assert server.is_ready
-    assert server.ip == "159.223.244.125"
-    assert server.free_slots == 1
-    [account] = server.accounts
-    assert account.status == PrivateAccountStatus.READY
-    assert account.has_terminal
-
-
-@respx.mock
-def test_get_accepts_model_or_id() -> None:
-    route = respx.get(f"{BASE}/private-servers/{SERVER_ID}").mock(
-        return_value=httpx.Response(200, json=SERVER)
-    )
-    with _client() as fx:
-        by_id = fx.private_servers.get(SERVER_ID)
-        by_model = fx.private_servers.get(by_id)
-    assert route.call_count == 2
-    assert by_model.id == SERVER_ID
-
-
-@respx.mock
-def test_add_account_payload_and_model() -> None:
-    route = respx.post(f"{BASE}/private-servers/{SERVER_ID}/accounts").mock(
-        return_value=httpx.Response(201, json=SERVER_ACCOUNT)
-    )
-    with _client() as fx:
-        account = fx.private_servers.add_account(
-            SERVER_ID,
-            server="ICMarkets-Demo",
-            login=7001,
-            password="pw",
-            nickname="prop-1",
-        )
-    import json
-
-    sent = json.loads(route.calls.last.request.content)
-    assert sent == {
-        "platform": "mt5",
-        "server": "ICMarkets-Demo",
-        "login": 7001,
-        "password": "pw",
-        "nickname": "prop-1",
-        "trade_ea_symbol": "",
-    }
-    assert account.login == 7001
-
-
-@respx.mock
-def test_slots_full_maps_to_typed_error() -> None:
-    respx.post(f"{BASE}/private-servers/{SERVER_ID}/accounts").mock(
-        return_value=httpx.Response(
-            409,
-            json={
-                "error": "slots_full",
-                "detail": "Server is full (2/2).",
-                "used": 2,
-                "cap": 2,
-            },
-        )
-    )
-    with _client() as fx:
-        with pytest.raises(SlotsFullError) as err:
-            fx.private_servers.add_account(
-                SERVER_ID, server="Demo", login=1, password="pw"
-            )
-    assert err.value.used == 2
-    assert err.value.cap == 2
-
-
-@respx.mock
-def test_duplicate_still_maps_to_duplicate_error() -> None:
-    respx.post(f"{BASE}/private-servers/{SERVER_ID}/accounts").mock(
-        return_value=httpx.Response(
-            409, json={"error": "duplicate", "detail": "Already linked."}
-        )
-    )
-    with _client() as fx:
-        with pytest.raises(DuplicateAccountError):
-            fx.private_servers.add_account(
-                SERVER_ID, server="Demo", login=1, password="pw"
-            )
-
-
-@respx.mock
-def test_remove_account() -> None:
-    account_id = SERVER_ACCOUNT["id"]
-    route = respx.delete(
-        f"{BASE}/private-servers/{SERVER_ID}/accounts/{account_id}"
-    ).mock(return_value=httpx.Response(204))
-    with _client() as fx:
-        fx.private_servers.remove_account(SERVER_ID, account_id)
-    assert route.called
-
-
-@respx.mock
-def test_terminal_client_from_private_account() -> None:
-    respx.get(f"{BASE}/private-servers").mock(
-        return_value=httpx.Response(200, json=[SERVER])
-    )
-    with _client() as fx:
-        [server] = fx.private_servers.list()
-        term = fx.terminal(server.accounts[0], verify=False)
-    assert term is not None
-
-
-@pytest.mark.asyncio
-@respx.mock
-async def test_async_mirror() -> None:
-    respx.get(f"{BASE}/private-servers").mock(
-        return_value=httpx.Response(200, json=[SERVER])
-    )
-    respx.post(f"{BASE}/private-servers/{SERVER_ID}/accounts").mock(
-        return_value=httpx.Response(201, json=SERVER_ACCOUNT)
-    )
-    async with AsyncClient(api_key="fxs_live_test") as fx:
-        [server] = await fx.private_servers.list()
-        account = await fx.private_servers.add_account(
-            server, server="ICMarkets-Demo", login=7001, password="pw"
-        )
-    assert server.is_ready
-    assert account.login == 7001