pyeasyequities 2.0.0__py3-none-any.whl

easy_equities_client/__init__.py

@@ -0,0 +1 @@
+from . import accounts, clients, constants, instruments, orders, types, utils  # noqa: F401

easy_equities_client/accounts/clients.py

@@ -0,0 +1,334 @@
+import base64
+import logging
+from datetime import date, timedelta
+from typing import Any, Dict, List, Optional
+
+from requests import Session
+
+from easy_equities_client import constants
+from easy_equities_client.accounts.types import (
+    Account,
+    Holding,
+    Transaction,
+    TransactionForPeriod,
+    Valuation,
+)
+from easy_equities_client.types import Client
+
+logger = logging.getLogger(__name__)
+
+_API_GW_TRANSACTION_PATHS = [
+    "/transaction-history-provider/api/v1/transactions",
+    "/transaction-history-provider/v1/transactions",
+    "/easytrader/api/TransactionHistory/transactions",
+    "/easytrader/api/Transactions/account-transactions",
+]
+
+
+class AccountsClient(Client):
+    def __init__(self, base_url: str = "", session: Session = None):
+        super().__init__(base_url, session)
+        self._portfolio_cache: Optional[Dict] = None
+
+    def _get_portfolio_overview(self, force_refresh: bool = False) -> Dict:
+        """Fetch and cache the REST API portfolio overview."""
+        if self._portfolio_cache is None or force_refresh:
+            response = self.session.get(
+                constants.REST_API_BASE_URL + constants.REST_PORTFOLIO_OVERVIEW_PATH
+            )
+            response.raise_for_status()
+            self._portfolio_cache = response.json()
+        return self._portfolio_cache
+
+    def _find_account(self, account_id: str) -> Optional[Dict]:
+        """Return the investmentAccount dict matching account_id (accountNumber)."""
+        overview = self._get_portfolio_overview()
+        for acc in overview.get("investmentAccounts", []):
+            if acc.get("accountNumber") == account_id:
+                return acc
+        return None
+
+    def _decode_image_uri(self, image_uri: str) -> str:
+        """Decode base64-encoded image URI to a plain URL."""
+        try:
+            return base64.b64decode(image_uri).decode("utf-8")
+        except Exception:
+            return image_uri
+
+    def list(self) -> List[Account]:
+        """Return all investment accounts for the authenticated user."""
+        overview = self._get_portfolio_overview()
+        accounts = []
+        for acc in overview.get("investmentAccounts", []):
+            accounts.append(
+                Account(
+                    id=acc["accountNumber"],
+                    name=acc["productName"],
+                    trading_currency_id=str(acc.get("productId", "")),
+                )
+            )
+        return accounts
+
+    def valuations(self, account_id: str) -> Valuation:
+        """
+        Return valuation data for the given account from the REST API portfolio overview.
+
+        :param account_id: Account number string (e.g. 'EE3237137-15547214').
+        """
+        self._portfolio_cache = None
+        acc = self._find_account(account_id)
+        if acc is None:
+            raise ValueError(f"Account '{account_id}' not found in portfolio overview.")
+
+        aggregates = acc.get("aggregates", [])
+        accruals = acc.get("accruals", [])
+        costs = acc.get("costs", {})
+
+        investment_types = next(
+            (a for a in aggregates if a.get("aggregateName") == "Investment Type"), {}
+        )
+        managers = next(
+            (a for a in aggregates if a.get("aggregateName") == "Manager"), {}
+        )
+        income_accruals = next(
+            (a for a in accruals if a.get("accrualName") == "Income"), {}
+        )
+        expense_accruals = next(
+            (a for a in accruals if a.get("accrualName") == "Expense"), {}
+        )
+
+        return {
+            "accountNumber": acc.get("accountNumber"),
+            "productName": acc.get("productName"),
+            "currencyCode": acc.get("currencyCode"),
+            "totalInvestmentHoldingsValue": acc.get("totalInvestmentHoldingsValue"),
+            "InvestmentTypesAndManagers": {
+                "types": investment_types.get("items", []),
+                "managers": managers.get("items", []),
+            },
+            "AccrualIncomeSummaryItems": income_accruals.get("items", []),
+            "AccrualExpenseSummaryItems": expense_accruals.get("items", []),
+            "CostsSummaryItems": costs.get("items", []) if isinstance(costs, dict) else [],
+            "costsTotal": costs.get("costsTotal", 0) if isinstance(costs, dict) else 0,
+        }
+
+    def transactions(self, account_id: str) -> List[Transaction]:
+        """
+        Fetch transactions for the given account.
+
+        Tries multiple known API Gateway transaction endpoints. Returns an empty
+        list if the account has no transactions or the endpoint is unavailable.
+
+        :param account_id: Account number string (e.g. 'EE3237137-15547214').
+        """
+        gw = constants.API_GATEWAY_BASE_URL
+        headers = {
+            "Origin": "https://portfolio-overview.apps.easyequities.io",
+            "Referer": "https://portfolio-overview.apps.easyequities.io/",
+            "Accept": "application/json, text/plain, */*",
+        }
+
+        for path in _API_GW_TRANSACTION_PATHS:
+            url = gw + path
+            params = {"accountNumber": account_id}
+            try:
+                r = self.session.get(url, params=params, headers=headers, timeout=15)
+                if r.status_code == 200:
+                    data = r.json()
+                    logger.info(f"Transactions fetched from {path}: {len(data)} records")
+                    return data if isinstance(data, list) else data.get("transactions", [])
+                elif r.status_code == 404:
+                    # Empty result set — account exists but no transactions
+                    logger.debug(f"No transactions at {path} (404)")
+                    return []
+                else:
+                    logger.debug(f"Transaction endpoint {path} returned {r.status_code}")
+            except Exception as exc:
+                logger.debug(f"Transaction endpoint {path} error: {exc}")
+
+        # No endpoint worked — return empty list with a warning
+        logger.warning(
+            f"Could not fetch transactions for account '{account_id}'. "
+            "The transaction history API endpoint may have changed. "
+            "Check constants.API_GW_TRANSACTIONS_PATH for the latest URL."
+        )
+        return []
+
+    def transactions_for_period(
+        self, account_id: str, start_date: date, end_date: date
+    ) -> List[TransactionForPeriod]:
+        """
+        Fetch transactions for a given date range.
+
+        :param account_id: Account number string.
+        :param start_date: Start of the period (inclusive).
+        :param end_date: End of the period (inclusive).
+        """
+        gw = constants.API_GATEWAY_BASE_URL
+        headers = {
+            "Origin": "https://portfolio-overview.apps.easyequities.io",
+            "Referer": "https://portfolio-overview.apps.easyequities.io/",
+            "Accept": "application/json, text/plain, */*",
+        }
+        transactions: List[Any] = []
+        current_start = start_date
+        current_end = min(end_date, current_start + timedelta(days=90))
+
+        while current_start <= end_date:
+            logger.debug(f"Fetching transactions {current_start} → {current_end}")
+            fetched = False
+
+            for path in _API_GW_TRANSACTION_PATHS:
+                url = gw + path
+                params = {
+                    "accountNumber": account_id,
+                    "startDate": current_start.isoformat(),
+                    "endDate": current_end.isoformat(),
+                }
+                try:
+                    r = self.session.get(url, params=params, headers=headers, timeout=15)
+                    if r.status_code == 200:
+                        batch = r.json()
+                        if isinstance(batch, list):
+                            transactions = batch + transactions
+                        fetched = True
+                        break
+                    elif r.status_code == 404:
+                        fetched = True
+                        break
+                except Exception as exc:
+                    logger.debug(f"transactions_for_period error at {path}: {exc}")
+
+            if not fetched:
+                logger.warning(
+                    f"Could not fetch transactions for period {current_start}–{current_end}. "
+                    "Transaction API endpoint may have changed."
+                )
+
+            current_start = current_end + timedelta(days=1)
+            current_end = min(end_date, current_start + timedelta(days=90))
+
+        return transactions
+
+    def nav_chart(self, account_id: str, period: str = "1mo") -> dict:
+        """
+        Return the portfolio NAV (Net Asset Value) chart data for the given account.
+
+        The EasyEquities REST API endpoint ``/portfolios/nav_chart_data/{period}``
+        returns an empty response for accounts with no trading history. For accounts
+        that have holdings and transactions, it returns time-series NAV data.
+
+        Supported period strings: ``"1W"``, ``"1mo"``, ``"3mo"``, ``"6mo"``, ``"1Y"``
+
+        :param account_id: Account number string (e.g. 'EE3237137-15547214').
+        :param period: Time period string. Default ``"1mo"``.
+        :return: Dict with:
+            - ``success``    — True if chart data is available
+            - ``account_id`` — the requested account
+            - ``period``     — the requested period
+            - ``data``       — list of ``{"date": str, "nav": float}`` points,
+              empty if the account has no trade history
+            - ``message``    — explanation if no data is available
+
+        Example::
+
+            chart = client.accounts.nav_chart("EE3237137-15547214", period="3mo")
+            if chart["success"]:
+                for point in chart["data"]:
+                    print(point["date"], point["nav"])
+            else:
+                print(chart["message"])
+        """
+        url = constants.REST_API_BASE_URL + f"/portfolios/nav_chart_data/{period}"
+        headers = {
+            "Origin": "https://portfolio-overview.apps.easyequities.io",
+            "Referer": "https://portfolio-overview.apps.easyequities.io/",
+            "Accept": "application/json, text/plain, */*",
+        }
+        try:
+            r = self.session.get(url, headers=headers, timeout=15)
+            r.raise_for_status()
+            raw = r.json()
+        except Exception as exc:
+            return {
+                "success": False,
+                "account_id": account_id,
+                "period": period,
+                "data": [],
+                "message": f"Request failed: {exc}",
+            }
+
+        if not raw:
+            return {
+                "success": False,
+                "account_id": account_id,
+                "period": period,
+                "data": [],
+                "message": (
+                    "No NAV chart data returned. This account has no trading history "
+                    "yet — NAV chart data is only available for accounts with completed "
+                    "buy/sell transactions."
+                ),
+            }
+
+        points = []
+        if isinstance(raw, list):
+            for entry in raw:
+                date = entry.get("Date") or entry.get("date") or entry.get("x")
+                nav = entry.get("Nav") or entry.get("nav") or entry.get("y") or entry.get("Value")
+                if date and nav is not None:
+                    points.append({"date": str(date)[:10], "nav": float(nav)})
+        elif isinstance(raw, dict):
+            for key in ("data", "Data", "points", "Points", "series", "Series"):
+                if key in raw and isinstance(raw[key], list):
+                    for entry in raw[key]:
+                        date = entry.get("Date") or entry.get("date") or entry.get("x")
+                        nav = entry.get("Nav") or entry.get("nav") or entry.get("y") or entry.get("Value")
+                        if date and nav is not None:
+                            points.append({"date": str(date)[:10], "nav": float(nav)})
+                    break
+
+        return {
+            "success": True,
+            "account_id": account_id,
+            "period": period,
+            "data": points,
+            "message": None,
+        }
+
+    def holdings(self, account_id: str, include_shares: bool = False) -> List[Holding]:
+        """
+        Get an account's holdings from the REST API portfolio overview.
+
+        :param account_id: Account number string (e.g. 'EE3237137-15547214').
+        :param include_shares: Included for backward compatibility; share units are
+            already present in the REST API response as 'units'.
+        """
+        self._portfolio_cache = None
+        acc = self._find_account(account_id)
+        if acc is None:
+            raise ValueError(f"Account '{account_id}' not found in portfolio overview.")
+
+        currency = acc.get("currencyCode", "")
+        holdings: List[Holding] = []
+
+        for asset in acc.get("assets", []):
+            image_uri = asset.get("imageUri", "")
+            img_url = self._decode_image_uri(image_uri) if image_uri else ""
+
+            holding: Holding = {
+                "name": asset.get("assetName", ""),
+                "contract_code": asset.get("contractCode", ""),
+                "purchase_value": f"{currency} {asset.get('purchaseValue', 0)}",
+                "current_value": f"{currency} {asset.get('currentValue', 0)}",
+                "current_price": f"{currency} {asset.get('currentPrice', 0)}",
+                "img": img_url,
+                "view_url": "",
+                "isin": asset.get("assetCode", ""),
+                "shares": str(asset.get("units", "")),
+                "profit_loss_value": asset.get("profitLossValue", 0),
+                "profit_loss_percentage": asset.get("profitLossPercentage", 0),
+            }
+            holdings.append(holding)
+
+        return holdings

easy_equities_client/accounts/parsers.py

@@ -0,0 +1,195 @@
+import re
+from dataclasses import dataclass
+from typing import Any, List, Optional
+
+from bs4 import BeautifulSoup
+from bs4.element import Tag
+
+from easy_equities_client import constants
+from easy_equities_client.accounts.types import Account, Holding
+from easy_equities_client.utils import currencies
+
+amount_pattern_compiled = re.compile(constants.RE_AMOUNT_PATTERN)
+
+
+def extract_account_info(account_div: Tag) -> Optional[Account]:
+    trading_currency = account_div.parent.attrs.get("data-tradingcurrencyid")
+    if not trading_currency:
+        return None
+    return Account(
+        name=account_div.text.strip(),
+        trading_currency_id=trading_currency.strip(),
+        id=account_div.parent.attrs["data-id"].strip(),
+    )
+
+
+@dataclass
+class AccountOverviewParser:
+    """
+    Parse the accounts overview page (/AccountOverview) given the html
+    contents of the page.
+    """
+
+    page: str
+
+    def extract_accounts(self) -> List[Account]:
+        """
+        Return the accounts found on the account overview page.
+        """
+        soup = BeautifulSoup(self.page, "html.parser")
+        accounts_divs = soup.find_all(attrs={"id": "trust-account-types"})
+        return [
+            account
+            for account in [
+                extract_account_info(account_div) for account_div in accounts_divs
+            ]
+            if account
+        ]
+
+
+class HoldingFieldNotFoundException(Exception):
+    def __init__(self, field, exception):
+        return super().__init__(
+            f"Field '{field}' not found in holding div. Exception: f{exception}"
+        )
+
+
+class HoldingDivParser:
+    def __init__(self, div: Tag):
+        self.div = div
+
+    def __eq__(a, b):
+        return a.name == b.name
+
+    def __hash__(self):
+        return hash(self.name)
+
+    @property
+    def name(self) -> str:
+        return self.div.find(attrs={"class": "equity-image-as-text"}).text.strip()
+
+    @property
+    def purchase_value(self) -> str:
+        return self.div.find(attrs={"class": "purchase-value-cell"}).text.strip()
+
+    @property
+    def current_value(self) -> str:
+        return self.div.find(attrs={"class": "current-value-cell"}).text.strip()
+
+    @property
+    def current_price(self) -> str:
+        return self.div.find(attrs={"class": "current-price-cell"}).text.strip()
+
+    @property
+    def img(self) -> str:
+        return self.div.find(attrs={"class": "instrument"}).attrs["src"]
+
+    @property
+    def contract_code(self) -> str:
+        return self.img[self.img.rindex("/") + 1 : self.img.index(".png")]
+
+    @property
+    def view_url(self) -> str:
+        return (
+            self.div.find(attrs={"class": "collapse-container"})
+            .find("span")
+            .attrs["data-detailviewurl"]
+        )
+
+    @property
+    def isin(self) -> str:
+        return (
+            self.div.find(attrs={"class": "collapse-container"})
+            .find("span")
+            .attrs["data-detailviewurl"]
+            .split("=")[-1]
+        )
+
+    def to_dict(self) -> Holding:
+        fields = [
+            "name",
+            "contract_code",
+            "purchase_value",
+            "current_value",
+            "current_price",
+            "img",
+            "view_url",
+            "isin",
+        ]
+        data: Holding = {}
+        for field in fields:
+            try:
+                data[field] = getattr(self, field)  # type: ignore
+            except Exception as e:
+                raise HoldingFieldNotFoundException(field, e)
+
+        return data
+
+
+@dataclass
+class AccountHoldingsParser:
+    """
+    Parse the accounts holdings page given the html contents of the page.
+    """
+
+    page: bytes
+
+    def extract_holdings(self) -> List[Holding]:
+        """
+        Return the holdings found on the holdings page.
+        """
+        soup = BeautifulSoup(self.page, "html.parser")
+        holdings_divs = soup.find_all(attrs={"class": "holding-inner-container"})
+        # Get unique holdings (skip first row because it is the header row)
+        divs = set([HoldingDivParser(holding_div) for holding_div in holdings_divs[1:]])
+        return [div.to_dict() for div in divs]
+
+
+def get_amount_and_currency_from_string(
+    amount_string: str,
+) -> tuple[str, str | None, float]:
+    amount_match = amount_pattern_compiled.match(amount_string)
+    if amount_match is None:
+        raise Exception(
+            f"Could not parse amount {amount_string} into currency and value."
+        )
+    currency_symbol = amount_match.group("currency")
+    currency_code = currencies.convert_non_ascii_currency_symbol_to_ascii_code(
+        currency_symbol
+    )
+    value = float(
+        (amount_match.group("symbol") if amount_match.group("symbol") else "")
+        + amount_match.group("value").replace(" ", "")
+    )
+    return currency_symbol, currency_code, value
+
+
+def get_transactions_from_page(page_body: bytes) -> List[Any]:
+    """
+    :param page_body: Page html from response.content.
+    """
+    soup = BeautifulSoup(page_body, "html.parser")
+    table = soup.find("div", {"id": "TransactionHistory"}).find("tbody")
+    if table is None:
+        validation_error = soup.find(class_="validation-summary-errors")
+        if validation_error:
+            raise Exception(validation_error.text.strip())
+        return []
+    rows = table.find_all("tr")
+    transactions = []
+    for row in rows:
+        columns = row.find_all("td")
+        currency_symbol, currency_code, value = get_amount_and_currency_from_string(
+            columns[2].text.strip()
+        )
+        transactions.append(
+            {
+                "date": columns[0].text.strip(),
+                "description": columns[1].text.strip(),
+                "currency_symbol": currency_symbol,
+                "currency_code": currency_code,
+                "value": value,
+                "amount": columns[2].text.strip(),
+            }
+        )
+    return transactions

easy_equities_client/accounts/types.py

@@ -0,0 +1,63 @@
+import sys
+from dataclasses import dataclass
+from typing import List, Optional
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+
+@dataclass
+class Account:
+    id: str
+    name: str
+    trading_currency_id: str
+
+
+class Holding(TypedDict, total=False):
+    name: str
+    contract_code: str
+    purchase_value: str
+    current_value: str
+    current_price: str
+    img: str
+    view_url: str
+    isin: str
+    shares: str
+
+
+class Transaction(TypedDict):
+    TransactionId: int
+    DebitCredit: float
+    Comment: str
+    TransactionDate: str
+    LogId: int
+    ActionId: int
+    Action: str
+    ContractCode: str
+
+
+class TransactionForPeriod(TypedDict):
+    date: str
+    description: str
+    amount: str
+    currency: str
+    value: float
+
+
+class LabelValue(TypedDict):
+    Label: str
+    Value: str
+
+
+class Valuation(TypedDict):
+    NetInterestOnCashItems: List[LabelValue]
+    AccrualSummaryItems: List[LabelValue]
+    TopSummary: dict
+    InvestmentTypesAndManagers: dict
+    InvestmentSummaryItems: list
+    CostsSummaryItems: list
+    FundSummaryItems: list
+    AccrualIncomeSummaryItems: Optional[list]
+    AccrualExpenseSummaryItems: Optional[list]