etrade-python 1.0.0__py3-none-any.whl

etrade_python/accounts/service.py

@@ -0,0 +1,136 @@
+"""Accounts API service."""
+
+from typing import Any, cast
+
+from pydantic import ValidationError
+
+from etrade_python.accounts.models import (
+    Account,
+    AccountBalanceRequest,
+    AccountBalanceResponse,
+    AccountListResponse,
+)
+from etrade_python.exceptions import ETradeResponseError, ETradeValidationError
+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 AccountsService:
+    """Access E*TRADE account list and balance endpoints."""
+
+    def __init__(self, transport: ApiTransport) -> None:
+        self._transport = transport
+
+    async def list(self) -> AccountListResponse:
+        response = await self._transport.request(
+            "GET",
+            "/v1/accounts/list.json",
+            safety=RetrySafety.SAFE_READ,
+            operation="accounts.list",
+        )
+        if response.status_code == 204 and response.data is None:
+            return AccountListResponse(accounts=[])
+
+        data = _require_mapping(response.data)
+        accounts_data = _unwrap(data, "AccountListResponse")
+        accounts_container = _optional_mapping(accounts_data, "accounts", "Accounts")
+        if accounts_container is None:
+            raise ETradeResponseError("Invalid account list response")
+
+        raw_accounts_value = _optional_value(accounts_container, "account", "Account")
+        if raw_accounts_value is None:
+            if not any(key in accounts_container for key in ("account", "Account")):
+                raise ETradeResponseError("Invalid account list response: missing collection")
+            return AccountListResponse(accounts=[])
+        if isinstance(raw_accounts_value, dict):
+            raw_accounts: list[Any] = [raw_accounts_value]
+        elif isinstance(raw_accounts_value, list):
+            raw_accounts = cast(list[Any], raw_accounts_value)
+        else:
+            raise ETradeResponseError("Invalid account list response")
+
+        accounts: list[Account] = []
+        for index, account in enumerate(raw_accounts):
+            try:
+                accounts.append(
+                    validate_response_shape(Account.model_validate(account), "account list")
+                )
+            except ValidationError as error:
+                raise_response_validation_error(
+                    "Invalid account list response", error, prefix=f"accounts.{index}"
+                )
+        return AccountListResponse(accounts=accounts)
+
+    async def get_balance(
+        self, account_id_key: str, request: AccountBalanceRequest | None = None
+    ) -> AccountBalanceResponse:
+        if not account_id_key.strip():
+            raise ETradeValidationError("account_id_key is required")
+
+        balance_request = request or AccountBalanceRequest()
+        response = await self._transport.request(
+            "GET",
+            f"/v1/accounts/{account_id_key}/balance.json",
+            params=balance_request.query_params(),
+            safety=RetrySafety.SAFE_READ,
+            operation="accounts.balance",
+        )
+        data = _require_mapping(response.data)
+        balance_data = _unwrap(data, "BalanceResponse")
+        try:
+            return validate_response_shape(
+                AccountBalanceResponse.model_validate(_normalize_balance(balance_data)),
+                "account balance",
+            )
+        except ValidationError as error:
+            raise_response_validation_error("Invalid account balance response", error)
+
+
+def _require_mapping(data: JsonValue) -> dict[str, Any]:
+    if not isinstance(data, dict):
+        raise ETradeResponseError("Invalid account 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 account response")
+    return cast(dict[str, Any], value)
+
+
+def _optional_mapping(data: dict[str, Any], *keys: str) -> dict[str, Any] | None:
+    value = _optional_value(data, *keys)
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return cast(dict[str, Any], value)
+    return None
+
+
+def _optional_value(data: dict[str, Any], *keys: str) -> Any | None:
+    for key in keys:
+        if key in data:
+            return data[key]
+    return None
+
+
+def _normalize_balance(data: dict[str, Any]) -> dict[str, Any]:
+    normalized = dict(data)
+    aliases = {
+        "Cash": "cash",
+        "Computed": "computedBalance",
+        "ComputedBalance": "computedBalance",
+        "Margin": "margin",
+        "Lending": "lending",
+    }
+    for source, target in aliases.items():
+        if source in normalized and target not in normalized:
+            normalized[target] = normalized[source]
+            del normalized[source]
+    return normalized

etrade_python/alerts/__init__.py

@@ -0,0 +1,23 @@
+"""Alerts service and models."""
+
+from etrade_python.alerts.models import (
+    Alert,
+    AlertDetailsRequest,
+    AlertDetailsResponse,
+    AlertsRequest,
+    AlertsResponse,
+    DeleteAlertsResponse,
+    FailedAlerts,
+)
+from etrade_python.alerts.service import AlertsService
+
+__all__ = [
+    "Alert",
+    "AlertDetailsRequest",
+    "AlertDetailsResponse",
+    "AlertsRequest",
+    "AlertsResponse",
+    "AlertsService",
+    "DeleteAlertsResponse",
+    "FailedAlerts",
+]

etrade_python/alerts/models.py

@@ -0,0 +1,180 @@
+"""Typed alert request and response models."""
+
+from datetime import datetime
+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)
+
+
+def _bool_query(value: bool | None) -> str | None:
+    if value is None:
+        return None
+    return "true" if value else "false"
+
+
+class AlertsRequest(BaseModel):
+    """Query parameters for alert list lookup."""
+
+    model_config = ConfigDict(frozen=True)
+
+    count: int | None = Field(default=None, ge=1, le=300)
+    category: str | None = None
+    status: str | None = None
+    direction: str | None = None
+    search: str | None = None
+
+    @field_validator("category")
+    @classmethod
+    def valid_category(cls, value: str | None) -> str | None:
+        return _normalize_choice(value, {"STOCK", "ACCOUNT"}, "category")
+
+    @field_validator("status")
+    @classmethod
+    def valid_status(cls, value: str | None) -> str | None:
+        return _normalize_choice(value, {"READ", "UNREAD", "DELETED"}, "status")
+
+    @field_validator("direction")
+    @classmethod
+    def valid_direction(cls, value: str | None) -> str | None:
+        return _normalize_choice(value, {"ASC", "DESC"}, "direction")
+
+    @field_validator("search")
+    @classmethod
+    def nonempty_search(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 | int | None]:
+        return {
+            "count": self.count,
+            "category": self.category,
+            "status": self.status,
+            "direction": self.direction,
+            "search": self.search,
+        }
+
+
+class AlertDetailsRequest(BaseModel):
+    """Query parameters for alert details lookup."""
+
+    model_config = ConfigDict(frozen=True, populate_by_name=True)
+
+    html_tags: bool | None = Field(default=None, alias="htmlTags")
+
+    def query_params(self) -> dict[str, str | None]:
+        return {"htmlTags": _bool_query(self.html_tags)}
+
+
+class Alert(BrokerModel):
+    id: int | None = None
+    create_time: datetime | None = Field(default=None, alias="createTime")
+    subject: str | None = None
+    status: str | None = None
+
+    @field_validator("create_time", mode="before")
+    @classmethod
+    def parse_create_time(cls, value: object) -> datetime | None:
+        return _parse_alert_time(value)
+
+
+class AlertDetailsResponse(Alert):
+    msg_text: str | None = Field(default=None, alias="msgText")
+    read_time: datetime | None = Field(default=None, alias="readTime")
+    delete_time: datetime | None = Field(default=None, alias="deleteTime")
+    symbol: str | None = None
+    next: str | None = None
+    prev: str | None = None
+
+    @field_validator("read_time", "delete_time", mode="before")
+    @classmethod
+    def parse_optional_times(cls, value: object) -> datetime | None:
+        return _parse_alert_time(value)
+
+
+def _empty_alerts() -> list[Alert]:
+    return []
+
+
+class AlertsResponse(BrokerModel):
+    total_alerts: int | None = Field(default=None, alias="totalAlerts")
+    alerts: list[Alert] = Field(default_factory=_empty_alerts, alias="alerts")
+
+    @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))
+        for source in ("Alert", "alert"):
+            if source in data and "alerts" not in data:
+                data["alerts"] = data[source]
+            data.pop(source, None)
+        return data
+
+    @field_validator("alerts", mode="before")
+    @classmethod
+    def normalize_alerts(cls, value: object) -> object:
+        if value is None:
+            return []
+        if isinstance(value, dict):
+            return [cast(dict[str, Any], value)]
+        return value
+
+
+def _empty_failed_alert_ids() -> list[int]:
+    return []
+
+
+class FailedAlerts(BrokerModel):
+    alert_ids: list[int] = Field(default_factory=_empty_failed_alert_ids, alias="alertId")
+
+    @field_validator("alert_ids", mode="before")
+    @classmethod
+    def normalize_alert_ids(cls, value: object) -> object:
+        if value is None:
+            return []
+        if isinstance(value, int):
+            return [value]
+        return value
+
+
+class DeleteAlertsResponse(BrokerModel):
+    result: str | None = None
+    failed_alerts: FailedAlerts | None = Field(default=None, alias="failedAlerts")
+
+    @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 "FailedAlerts" in data and "failedAlerts" not in data:
+            data["failedAlerts"] = data["FailedAlerts"]
+        data.pop("FailedAlerts", None)
+        return data
+
+
+def _normalize_choice(value: str | None, choices: set[str], label: str) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip().upper()
+    if not normalized:
+        raise ValueError("A nonempty value is required")
+    if normalized not in choices:
+        raise ValueError(f"Unsupported alert {label}")
+    return normalized
+
+
+def _parse_alert_time(value: object) -> datetime | None:
+    if value in (None, "", 0, "0"):
+        return None
+    return parse_broker_datetime(value)

etrade_python/alerts/service.py

@@ -0,0 +1,128 @@
+"""Alerts API service."""
+
+from collections.abc import Sequence
+from typing import Any, cast
+
+from pydantic import ValidationError
+
+from etrade_python.alerts.models import (
+    AlertDetailsRequest,
+    AlertDetailsResponse,
+    AlertsRequest,
+    AlertsResponse,
+    DeleteAlertsResponse,
+)
+from etrade_python.exceptions import ETradeNotFoundError, ETradeResponseError, ETradeValidationError
+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 AlertsService:
+    """Access E*TRADE alert endpoints."""
+
+    def __init__(self, transport: ApiTransport) -> None:
+        self._transport = transport
+
+    async def list(self, request: AlertsRequest | None = None) -> AlertsResponse:
+        alerts_request = request or AlertsRequest()
+        try:
+            response = await self._transport.request(
+                "GET",
+                "/v1/user/alerts.json",
+                params=alerts_request.query_params(),
+                safety=RetrySafety.SAFE_READ,
+                operation="alerts.list",
+            )
+        except ETradeNotFoundError as error:
+            if _is_no_alerts_error(error):
+                return AlertsResponse(totalAlerts=0, alerts=[])
+            raise
+        if response.status_code == 204 and response.data is None:
+            return AlertsResponse(totalAlerts=0, alerts=[])
+        data = _require_mapping(response.data, "alerts")
+        alerts_data = _unwrap(data, "AlertsResponse", "alerts")
+        try:
+            return validate_response_shape(
+                AlertsResponse.model_validate(alerts_data), "alerts", collection_field="alerts"
+            )
+        except ValidationError as error:
+            raise_response_validation_error("Invalid alerts response", error)
+
+    async def get(
+        self, alert_id: int, request: AlertDetailsRequest | None = None
+    ) -> AlertDetailsResponse:
+        normalized_id = _normalize_alert_id(alert_id)
+        details_request = request or AlertDetailsRequest()
+        response = await self._transport.request(
+            "GET",
+            f"/v1/user/alerts/{normalized_id}.json",
+            params=details_request.query_params(),
+            safety=RetrySafety.SAFE_READ,
+            operation="alerts.get",
+        )
+        data = _require_mapping(response.data, "alert details")
+        details_data = _unwrap(data, "AlertDetailsResponse", "alert details")
+        try:
+            return validate_response_shape(
+                AlertDetailsResponse.model_validate(details_data), "alert details"
+            )
+        except ValidationError as error:
+            raise_response_validation_error("Invalid alert details response", error)
+
+    async def delete(self, alert_ids: Sequence[int] | int) -> DeleteAlertsResponse:
+        ids = _normalize_alert_ids(alert_ids)
+        response = await self._transport.request(
+            "DELETE",
+            f"/v1/user/alerts/{','.join(str(alert_id) for alert_id in ids)}.json",
+            safety=RetrySafety.NEVER,
+            operation="alerts.delete",
+        )
+        data = _require_mapping(response.data, "delete alerts")
+        delete_data = _unwrap(data, "DeleteAlertsResponse", "delete alerts")
+        try:
+            return validate_response_shape(
+                DeleteAlertsResponse.model_validate(delete_data), "delete alerts"
+            )
+        except ValidationError as error:
+            raise_response_validation_error("Invalid delete alerts response", error)
+
+
+def _normalize_alert_id(alert_id: int) -> int:
+    if type(alert_id) is not int or alert_id < 1:
+        raise ETradeValidationError("alert_id must be a positive integer")
+    return alert_id
+
+
+def _normalize_alert_ids(alert_ids: Sequence[int] | int) -> list[int]:
+    if isinstance(alert_ids, bool):
+        raise ETradeValidationError("alert_ids must be integers")
+    if isinstance(alert_ids, int):
+        return [_normalize_alert_id(alert_ids)]
+    if isinstance(alert_ids, (str, bytes)) or not isinstance(cast(object, alert_ids), Sequence):
+        raise ETradeValidationError("alert_ids must be integers")
+    normalized = [_normalize_alert_id(alert_id) for alert_id in alert_ids]
+    if not normalized:
+        raise ETradeValidationError("at least one alert_id is required")
+    return normalized
+
+
+def _is_no_alerts_error(error: ETradeNotFoundError) -> bool:
+    return error.broker_code == "53" or "no alerts" in (error.broker_message or "").lower()
+
+
+def _require_mapping(data: JsonValue, response_name: str) -> dict[str, Any]:
+    if not isinstance(data, dict):
+        raise ETradeResponseError(f"Invalid {response_name} response")
+    return cast(dict[str, Any], data)
+
+
+def _unwrap(data: dict[str, Any], envelope: str, response_name: str) -> dict[str, Any]:
+    value = data.get(envelope, data)
+    if not isinstance(value, dict):
+        raise ETradeResponseError(f"Invalid {response_name} response")
+    return cast(dict[str, Any], value)

etrade_python/auth/__init__.py

@@ -0,0 +1,31 @@
+"""OAuth and session lifecycle support."""
+
+from etrade_python.auth.credentials import (
+    AuthorizationUrl,
+    ETradeCredentials,
+    RenewalResult,
+    RequestToken,
+    RevocationResult,
+)
+from etrade_python.auth.oauth import OAuthClient
+from etrade_python.auth.session import SessionAuthenticator, SessionManager, TokenStatus
+from etrade_python.auth.stores import (
+    CredentialStore,
+    KeyringCredentialStore,
+    MemoryCredentialStore,
+)
+
+__all__ = [
+    "AuthorizationUrl",
+    "CredentialStore",
+    "ETradeCredentials",
+    "KeyringCredentialStore",
+    "MemoryCredentialStore",
+    "OAuthClient",
+    "RenewalResult",
+    "RequestToken",
+    "RevocationResult",
+    "SessionAuthenticator",
+    "SessionManager",
+    "TokenStatus",
+]

etrade_python/auth/credentials.py

@@ -0,0 +1,85 @@
+"""Credential models for OAuth lifecycle state."""
+
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, field_validator
+
+
+class RequestToken(BaseModel):
+    """Temporary token used only during the browser authorization flow."""
+
+    model_config = ConfigDict(frozen=True)
+
+    oauth_token: SecretStr = Field(repr=False)
+    oauth_token_secret: SecretStr = Field(repr=False)
+    oauth_callback_confirmed: bool = False
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    @field_validator("oauth_token", "oauth_token_secret")
+    @classmethod
+    def nonempty_secret(cls, value: SecretStr) -> SecretStr:
+        if not value.get_secret_value().strip():
+            raise ValueError("A nonempty OAuth token value is required")
+        return value
+
+
+class ETradeCredentials(BaseModel):
+    """Persisted access-token credentials and lifecycle timestamps."""
+
+    model_config = ConfigDict(frozen=True)
+
+    access_token: SecretStr = Field(repr=False)
+    access_token_secret: SecretStr = Field(repr=False)
+    acquired_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    last_used_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    renewed_at: datetime | None = None
+
+    @field_validator("access_token", "access_token_secret")
+    @classmethod
+    def nonempty_secret(cls, value: SecretStr) -> SecretStr:
+        if not value.get_secret_value().strip():
+            raise ValueError("A nonempty OAuth credential is required")
+        return value
+
+    @field_validator("acquired_at", "last_used_at", "renewed_at")
+    @classmethod
+    def require_aware_datetime(cls, value: datetime | None) -> datetime | None:
+        if value is None:
+            return value
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError("Credential timestamps must be timezone-aware")
+        return value.astimezone(UTC)
+
+    def with_last_used(self, when: datetime) -> "ETradeCredentials":
+        return self.model_copy(update={"last_used_at": when.astimezone(UTC)})
+
+    def with_renewal(self, when: datetime) -> "ETradeCredentials":
+        normalized = when.astimezone(UTC)
+        return self.model_copy(update={"last_used_at": normalized, "renewed_at": normalized})
+
+
+class AuthorizationUrl(BaseModel):
+    """Browser URL for authorizing a request token."""
+
+    model_config = ConfigDict(frozen=True)
+
+    url: str = Field(repr=False)
+    request_token: RequestToken
+
+
+class RenewalResult(BaseModel):
+    """Result of a successful E*TRADE access-token renewal."""
+
+    model_config = ConfigDict(frozen=True)
+
+    credentials: ETradeCredentials
+    message: str
+
+
+class RevocationResult(BaseModel):
+    """Result of a successful E*TRADE access-token revocation."""
+
+    model_config = ConfigDict(frozen=True)
+
+    revoked: bool
+    message: str