etrade-python 1.0.0__py3-none-any.whl

etrade_python/transactions/models.py

@@ -0,0 +1,201 @@
+"""Typed transaction request and response models."""
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Any, cast
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from etrade_python._dates import parse_broker_datetime
+
+
+class BrokerModel(BaseModel):
+    """Base response model that discards unmodeled broker fields."""
+
+    model_config = ConfigDict(extra="ignore", frozen=True, populate_by_name=True)
+
+
+class TransactionsRequest(BaseModel):
+    """Query parameters for list transactions."""
+
+    model_config = ConfigDict(frozen=True)
+
+    marker: str | None = None
+    count: int | None = Field(default=None, ge=1, le=50)
+    start_date: str | None = None
+    end_date: str | None = None
+    sort_order: str | None = "DESC"
+
+    @field_validator("marker", "start_date", "end_date", "sort_order")
+    @classmethod
+    def nonempty_string(cls, value: str | None) -> str | None:
+        if value is not None and not value.strip():
+            raise ValueError("A nonempty value is required")
+        return value
+
+    @model_validator(mode="after")
+    def validate_date_range(self) -> "TransactionsRequest":
+        if (self.start_date is None) != (self.end_date is None):
+            raise ValueError("start_date and end_date must be supplied together")
+        return self
+
+    def query_params(self) -> dict[str, str | int | None]:
+        return {
+            "marker": self.marker,
+            "count": self.count,
+            "startDate": self.start_date,
+            "endDate": self.end_date,
+            "sortOrder": self.sort_order,
+        }
+
+
+class TransactionDetailsRequest(BaseModel):
+    """Query parameters for transaction detail lookup."""
+
+    model_config = ConfigDict(frozen=True)
+
+    store_id: str | None = None
+
+    @field_validator("store_id")
+    @classmethod
+    def nonempty_string(cls, value: str | None) -> str | None:
+        if value is not None and not value.strip():
+            raise ValueError("A nonempty value is required")
+        return value
+
+    def query_params(self) -> dict[str, str | None]:
+        return {"storeId": self.store_id}
+
+
+class ProductId(BrokerModel):
+    symbol: str | None = None
+    type_code: str | None = Field(default=None, alias="typeCode")
+
+
+class TransactionProduct(BrokerModel):
+    symbol: str | None = None
+    security_type: str | None = Field(default=None, alias="securityType")
+    security_sub_type: str | None = Field(default=None, alias="securitySubType")
+    call_put: str | None = Field(default=None, alias="callPut")
+    expiry_year: int | None = Field(default=None, alias="expiryYear")
+    expiry_month: int | None = Field(default=None, alias="expiryMonth")
+    expiry_day: int | None = Field(default=None, alias="expiryDay")
+    strike_price: Decimal | None = Field(default=None, alias="strikePrice")
+    expiry_type: str | None = Field(default=None, alias="expiryType")
+    product_id: ProductId | None = Field(default=None, alias="productId")
+
+
+class TransactionCategory(BrokerModel):
+    category_id: int | str | None = Field(default=None, alias="categoryId")
+    parent_id: int | str | None = Field(default=None, alias="parentId")
+    category_name: str | None = Field(default=None, alias="categoryName")
+    parent_name: str | None = Field(default=None, alias="parentName")
+
+
+class TransactionBrokerage(BrokerModel):
+    transaction_type: str | None = Field(default=None, alias="transactionType")
+    product: TransactionProduct | None = None
+    quantity: Decimal | None = None
+    price: Decimal | None = None
+    settlement_currency: str | None = Field(default=None, alias="settlementCurrency")
+    payment_currency: str | None = Field(default=None, alias="paymentCurrency")
+    fee: Decimal | None = None
+    memo: str | None = None
+    check_no: int | str | None = Field(default=None, alias="checkNo")
+    order_no: int | str | None = Field(default=None, alias="orderNo")
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_product(cls, value: object) -> object:
+        if not isinstance(value, dict):
+            return value
+        data = dict(cast(dict[str, Any], value))
+        if "Product" in data and "product" not in data:
+            data["product"] = data["Product"]
+        data.pop("Product", None)
+        if data.get("product") == {}:
+            data["product"] = None
+        return data
+
+
+class Transaction(BrokerModel):
+    transaction_id: int | str | None = Field(default=None, alias="transactionId")
+    account_id: int | str | None = Field(default=None, alias="accountId")
+    transaction_date: datetime | None = Field(default=None, alias="transactionDate")
+    post_date: datetime | None = Field(default=None, alias="postDate")
+    amount: Decimal | None = None
+    description: str | None = None
+    transaction_type: str | None = Field(default=None, alias="transactionType")
+    inst_type: str | None = Field(default=None, alias="instType")
+    store_id: int | str | None = Field(default=None, alias="storeId")
+    category: TransactionCategory | None = None
+    brokerage: TransactionBrokerage | None = None
+
+    @field_validator("transaction_date", "post_date", mode="before")
+    @classmethod
+    def parse_transaction_dates(cls, value: object) -> datetime | None:
+        return parse_broker_datetime(value)
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_nested_aliases(cls, value: object) -> object:
+        if not isinstance(value, dict):
+            return value
+        data = dict(cast(dict[str, Any], value))
+        for source, target in {"Category": "category", "Brokerage": "brokerage"}.items():
+            if source in data and target not in data:
+                data[target] = data[source]
+            data.pop(source, None)
+            if data.get(target) == {}:
+                data[target] = None
+        return data
+
+
+def _empty_transactions() -> list[Transaction]:
+    return []
+
+
+class TransactionsResponse(BrokerModel):
+    transactions: list[Transaction] = Field(
+        default_factory=_empty_transactions, alias="transaction"
+    )
+    marker: str | None = None
+    next: str | None = None
+    page_markers: str | None = Field(default=None, alias="pageMarkers")
+    more_transactions: bool | str | None = Field(default=None, alias="moreTransactions")
+    transaction_count: int | str | None = Field(default=None, alias="transactionCount")
+    total_count: int | str | None = Field(default=None, alias="totalCount")
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_response(cls, value: object) -> object:
+        if not isinstance(value, dict):
+            return value
+        data = dict(cast(dict[str, Any], value))
+        if "Transaction" in data and "transaction" not in data:
+            data["transaction"] = data["Transaction"]
+        data.pop("Transaction", None)
+        return data
+
+    @field_validator("transactions", mode="before")
+    @classmethod
+    def normalize_transactions(cls, value: object) -> object:
+        if value is None:
+            return []
+        if isinstance(value, dict):
+            return [cast(dict[str, Any], value)]
+        return value
+
+
+class TransactionDetailsResponse(BrokerModel):
+    transaction: Transaction
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_response(cls, value: object) -> object:
+        if not isinstance(value, dict):
+            return value
+        data = cast(dict[str, Any], value)
+        if "transaction" in data:
+            return data
+        return {"transaction": data}

etrade_python/transactions/service.py

@@ -0,0 +1,138 @@
+"""Transactions API service."""
+
+from collections.abc import AsyncIterator
+from typing import Any, cast
+
+from pydantic import ValidationError
+
+from etrade_python.exceptions import ETradeResponseError, ETradeValidationError
+from etrade_python.transactions.models import (
+    Transaction,
+    TransactionDetailsRequest,
+    TransactionDetailsResponse,
+    TransactionsRequest,
+    TransactionsResponse,
+)
+from etrade_python.transport.http import ApiTransport
+from etrade_python.transport.response import (
+    JsonValue,
+    raise_response_validation_error,
+    validate_response_shape,
+)
+from etrade_python.transport.retry import RetrySafety
+
+
+class TransactionsService:
+    """Access E*TRADE transaction endpoints."""
+
+    def __init__(self, transport: ApiTransport) -> None:
+        self._transport = transport
+
+    async def list(
+        self, account_id_key: str, request: TransactionsRequest | None = None
+    ) -> TransactionsResponse:
+        if not account_id_key.strip():
+            raise ETradeValidationError("account_id_key is required")
+
+        transactions_request = request or TransactionsRequest()
+        response = await self._transport.request(
+            "GET",
+            f"/v1/accounts/{account_id_key}/transactions.json",
+            params=transactions_request.query_params(),
+            safety=RetrySafety.SAFE_READ,
+            operation="transactions.list",
+        )
+        if response.status_code == 204 and response.data is None:
+            return TransactionsResponse(transaction=[])
+        data = _require_mapping(response.data)
+        transactions_data = _unwrap(data, "TransactionListResponse")
+        try:
+            return validate_response_shape(
+                TransactionsResponse.model_validate(transactions_data),
+                "transactions",
+                collection_field="transactions",
+            )
+        except ValidationError as error:
+            raise_response_validation_error("Invalid transactions response", error)
+
+    async def get(
+        self,
+        account_id_key: str,
+        transaction_id: str,
+        request: TransactionDetailsRequest | None = None,
+    ) -> TransactionDetailsResponse:
+        if not account_id_key.strip():
+            raise ETradeValidationError("account_id_key is required")
+        if not transaction_id.strip():
+            raise ETradeValidationError("transaction_id is required")
+
+        details_request = request or TransactionDetailsRequest()
+        response = await self._transport.request(
+            "GET",
+            f"/v1/accounts/{account_id_key}/transactions/{transaction_id}.json",
+            params=details_request.query_params(),
+            safety=RetrySafety.SAFE_READ,
+            operation="transactions.get",
+        )
+        data = _require_mapping(response.data)
+        transaction_data = _unwrap(data, "TransactionDetailsResponse")
+        try:
+            return validate_response_shape(
+                TransactionDetailsResponse.model_validate(transaction_data), "transaction details"
+            )
+        except ValidationError as error:
+            raise_response_validation_error("Invalid transaction details response", error)
+
+    async def list_all(
+        self, account_id_key: str, request: TransactionsRequest | None = None
+    ) -> AsyncIterator[Transaction]:
+        """Iterate pages, omitting repeated boundary transactions.
+
+        Automatic pagination requires count >= 2 because an inclusive marker
+        cannot advance a one-record page. Single-page list() permits count=1.
+        """
+        base_request = request or TransactionsRequest()
+        count = base_request.count or 50
+        if count == 1:
+            raise ETradeValidationError("Automatic transaction pagination requires count >= 2")
+        current_request = base_request
+        previous_last_id: str | None = None
+        seen_markers: set[str] = {base_request.marker} if base_request.marker else set()
+        while True:
+            page = await self.list(account_id_key, current_request)
+            marker = page.marker
+            has_next_page = bool(marker) and len(page.transactions) >= count
+            if has_next_page and marker in seen_markers:
+                raise ETradeResponseError("Transaction pagination did not advance")
+
+            transactions = page.transactions
+            if (
+                transactions
+                and previous_last_id is not None
+                and transactions[0].transaction_id is not None
+                and str(transactions[0].transaction_id) == previous_last_id
+            ):
+                transactions = transactions[1:]
+            for transaction in transactions:
+                yield transaction
+
+            if not has_next_page:
+                return
+            last_id = page.transactions[-1].transaction_id
+            previous_last_id = str(last_id) if last_id is not None else None
+            if marker is not None:
+                seen_markers.add(marker)
+            current_request = base_request.model_copy(update={"marker": marker})
+
+
+def _require_mapping(data: JsonValue) -> dict[str, Any]:
+    if not isinstance(data, dict):
+        raise ETradeResponseError("Invalid transaction response")
+    return cast(dict[str, Any], data)
+
+
+def _unwrap(data: dict[str, Any], envelope: str) -> dict[str, Any]:
+    value = data.get(envelope, data)
+    if not isinstance(value, dict):
+        raise ETradeResponseError("Invalid transaction response")
+    return cast(dict[str, Any], value)

etrade_python/transport/__init__.py

@@ -0,0 +1,7 @@
+"""Transport extension points, usable with HTTPX MockTransport in tests."""
+
+from etrade_python.transport.auth import RequestAuthenticator
+from etrade_python.transport.http import ApiTransport
+from etrade_python.transport.retry import RetryPolicy, RetrySafety
+
+__all__ = ["ApiTransport", "RequestAuthenticator", "RetryPolicy", "RetrySafety"]

etrade_python/transport/auth.py

@@ -0,0 +1,17 @@
+"""Request authentication and optional confirmed-usage notification."""
+
+from collections.abc import Awaitable, Callable
+from typing import Protocol
+
+import httpx
+
+
+class RequestAuthenticator(Protocol):
+    async def authenticate(self, request: httpx.Request) -> Callable[[], Awaitable[None]] | None:
+        """Attach auth headers in place, using fresh signing state for each attempt.
+
+        Must not change the method, URL, or body. Implementations must mask their own repr
+        and must not log secrets. May return a request-local callback to record usage
+        after a completed 2xx exchange. Returning None requires no notification.
+        """
+        ...

etrade_python/transport/http.py

@@ -0,0 +1,240 @@
+"""Shared async request pipeline. No business endpoint or OAuth logic lives here."""
+
+import asyncio
+import json
+import logging
+import re
+import time
+from collections.abc import Awaitable, Callable, Mapping
+from decimal import Decimal
+from typing import Literal
+from urllib.parse import unquote
+
+import httpx
+
+from etrade_python._version import __version__
+from etrade_python.config import ETradeSettings
+from etrade_python.exceptions import (
+    AuthenticationRequired,
+    AuthorizationExpired,
+    ETradeAuthenticationError,
+    ETradeTransportError,
+    ETradeValidationError,
+)
+from etrade_python.transport.auth import RequestAuthenticator
+from etrade_python.transport.logging import private_http_exchange
+from etrade_python.transport.response import JsonValue, Redactor, TransportResponse, parse_response
+from etrade_python.transport.retry import RetryPolicy, RetrySafety
+
+LOGGER = logging.getLogger("etrade_python.transport")
+HttpMethod = Literal["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD"]
+QueryParameters = Mapping[str, str | int | bool | None]
+
+
+def _decimal_json(value: object) -> str:
+    if isinstance(value, Decimal) and value.is_finite():
+        return str(value)
+    raise ValueError("Unsupported JSON value")
+
+
+class ApiTransport:
+    """One shared HTTP client, with per-request authentication and retry state.
+
+    Injected clients remain caller-owned. Their hooks and logging configuration
+    are also caller-owned and must not record credentials or account information.
+    """
+
+    def __init__(
+        self,
+        settings: ETradeSettings,
+        *,
+        authenticator: RequestAuthenticator | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        http_transport: httpx.AsyncBaseTransport | None = None,
+        retry_policy: RetryPolicy | None = None,
+        sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+    ) -> None:
+        if http_client is not None and http_transport is not None:
+            raise ETradeValidationError("Supply either http_client or http_transport, not both")
+        self._settings = settings
+        self._authenticator = authenticator
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(
+            transport=http_transport,
+            timeout=settings.request_timeout_seconds,
+            follow_redirects=False,
+            trust_env=False,
+        )
+        self._retry_policy = retry_policy or RetryPolicy()
+        self._sleep = sleep
+        self._closed = False
+
+    async def __aenter__(self) -> "ApiTransport":
+        if self._closed:
+            raise ETradeTransportError("Transport is closed")
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if not self._closed:
+            self._closed = True
+            if self._owns_client:
+                await self._client.aclose()
+
+    async def request(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        params: QueryParameters | None = None,
+        body: JsonValue = None,
+        safety: RetrySafety = RetrySafety.NEVER,
+        operation: str = "request",
+    ) -> TransportResponse:
+        """Request an API-relative JSON endpoint.
+
+        `operation` is a static label such as `accounts.list`, never user data.
+        `path` includes /v1 and any desired .json suffix. Query parameters must be
+        passed separately. Decimal request values serialize as JSON strings.
+        """
+        if self._closed:
+            raise ETradeTransportError("Transport is closed")
+        self._validate_path(path)
+        if not re.fullmatch(r"[a-z_]+(?:\.[a-z_]+)*", operation):
+            raise ETradeValidationError("Invalid operation label")
+        if method not in {"GET", "POST", "PUT", "DELETE", "PATCH", "HEAD"}:
+            raise ETradeValidationError("Invalid HTTP method")
+        if safety is RetrySafety.SAFE_READ and method not in {"GET", "HEAD"}:
+            raise ETradeValidationError("Only read requests may be classified as safe reads")
+        if self._authenticator is None:
+            raise AuthenticationRequired(
+                "An authenticator is required; OAuth is not implemented yet"
+            )
+        try:
+            content = (
+                json.dumps(body, default=_decimal_json, allow_nan=False).encode()
+                if body is not None
+                else None
+            )
+        except (ValueError, TypeError, RecursionError):
+            raise ETradeValidationError("Invalid JSON request body") from None
+        headers = {"Accept": "application/json", "User-Agent": f"etrade-python/{__version__}"}
+        if content is not None:
+            headers["Content-Type"] = "application/json"
+        url = self._settings.environment.api_base_url + path
+        attempt = 0
+        while True:
+            attempt += 1
+            try:
+                request = self._client.build_request(
+                    method,
+                    url,
+                    params={k: v for k, v in (params or {}).items() if v is not None},
+                    content=content,
+                    headers=headers,
+                    timeout=self._settings.request_timeout_seconds,
+                )
+            except (httpx.HTTPError, ValueError, TypeError):
+                raise ETradeValidationError("Could not construct HTTP request") from None
+            original_url, original_content = request.url, request.content
+            try:
+                record_usage = await self._authenticator.authenticate(request)
+            except AuthenticationRequired:
+                raise AuthenticationRequired("Authorization is required") from None
+            except AuthorizationExpired:
+                raise AuthorizationExpired("Authorization has expired") from None
+            except Exception:
+                raise ETradeAuthenticationError("Request authentication failed") from None
+            if (
+                request.method != method
+                or request.url != original_url
+                or request.content != original_content
+            ):
+                raise ETradeAuthenticationError(
+                    "Authenticator changed the request method, URL, or body"
+                )
+            redactor = self._redactor(request)
+            started = time.monotonic()
+            try:
+                with private_http_exchange():
+                    response = await self._client.send(request, follow_redirects=False, auth=None)
+            except httpx.TransportError as exc:
+                self._log(operation, attempt, started, None)
+                delay = self._retry_policy.delay(safety=safety, attempt=attempt, error=exc)
+                if delay is None:
+                    raise ETradeTransportError(
+                        "HTTP exchange failed; the outcome of a mutation may be unknown"
+                    ) from None
+                await self._sleep(delay)
+                continue
+            except httpx.HTTPError:
+                raise ETradeTransportError("HTTP exchange failed") from None
+            self._log(operation, attempt, started, response.status_code)
+            delay = self._retry_policy.delay(safety=safety, attempt=attempt, response=response)
+            if delay is not None:
+                await response.aclose()
+                await self._sleep(delay)
+                continue
+            try:
+                if 200 <= response.status_code < 300 and record_usage is not None:
+                    try:
+                        await record_usage()
+                    except Exception:
+                        # A local storage failure must not obscure a successful trade
+                        # or cause callers to retry a confirmed broker exchange.
+                        LOGGER.warning(
+                            "Could not record authenticated request usage",
+                            extra={"operation": operation},
+                        )
+                return parse_response(response, redactor)
+            finally:
+                await response.aclose()
+
+    @staticmethod
+    def _validate_path(path: str) -> None:
+        decoded = unquote(path)
+        if (
+            not path.startswith("/v1/")
+            or any(c.isspace() for c in path)
+            or any(c in decoded for c in ("?", "#", "\\", "%"))
+            or "//" in decoded
+            # Encoded ordinary spaces are valid in company-name lookup paths.
+            or any((c.isspace() and c != " ") or ord(c) < 32 or ord(c) == 127 for c in decoded)
+            or any(part in {".", ".."} for part in decoded.split("/"))
+        ):
+            raise ETradeValidationError(
+                "Expected a relative /v1/ API path without query or traversal"
+            )
+
+    def _redactor(self, request: httpx.Request) -> Redactor:
+        secrets = [
+            self._settings.consumer_key.get_secret_value(),
+            self._settings.consumer_secret.get_secret_value(),
+        ]
+        authorization = request.headers.get("authorization", "")
+        secrets.append(authorization)
+        # OAuth header values may be percent encoded. Include both representations.
+        secrets.extend(re.findall(r'="([^"\r\n]*)"', authorization))
+        if authorization and not authorization.startswith("OAuth "):
+            secrets.append(authorization.split(" ", 1)[-1])
+        secrets.extend(str(value) for value in request.url.params.values())
+        segments = request.url.path.split("/")
+        if "accounts" in segments:
+            index = segments.index("accounts") + 1
+            if index < len(segments) and segments[index] != "list.json":
+                secrets.append(segments[index])
+        return Redactor(secrets)
+
+    def _log(self, operation: str, attempt: int, started: float, status: int | None) -> None:
+        LOGGER.info(
+            "E*TRADE HTTP attempt",
+            extra={
+                "operation": operation,
+                "environment": self._settings.environment.value,
+                "status_code": status,
+                "latency_seconds": time.monotonic() - started,
+                "attempt": attempt,
+            },
+        )

etrade_python/transport/logging.py

@@ -0,0 +1,38 @@
+"""Keep HTTPX's automatic URL/wire logs out of SDK request diagnostics."""
+
+import logging
+from collections.abc import Generator
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+_SENSITIVE_EXCHANGE: ContextVar[bool] = ContextVar("etrade_sensitive_exchange", default=False)
+_HTTP_LOGGERS = (
+    "httpx",
+    "httpcore.connection",
+    "httpcore.http11",
+    "httpcore.http2",
+    "httpcore.proxy",
+    "httpcore.socks",
+)
+
+
+class _ExchangeFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        # This affects only the current task's SDK exchange, not unrelated clients.
+        return not _SENSITIVE_EXCHANGE.get()
+
+
+_FILTER = _ExchangeFilter()
+
+
+@contextmanager
+def private_http_exchange() -> Generator[None, None, None]:
+    for name in _HTTP_LOGGERS:
+        # addFilter is idempotent for the same instance. Do not change log levels
+        # or handlers, which are owned by the host application.
+        logging.getLogger(name).addFilter(_FILTER)
+    token = _SENSITIVE_EXCHANGE.set(True)
+    try:
+        yield
+    finally:
+        _SENSITIVE_EXCHANGE.reset(token)