elli-client 1.0.3__py3-none-any.whl

elli_client/__init__.py

@@ -0,0 +1,8 @@
+"""Elli Client - Python client for Elli Wallbox API"""
+
+from .client import ElliAPIClient
+from .models import ChargingSession, FirmwareInfo, Station, TokenResponse
+
+__version__ = "1.0.3"
+
+__all__ = ["ElliAPIClient", "ChargingSession", "Station", "TokenResponse", "FirmwareInfo"]

elli_client/client.py

@@ -0,0 +1,353 @@
+"""Elli API Client with OAuth2 PKCE Authentication"""
+
+import base64
+import hashlib
+import re
+import secrets
+from typing import Any, Dict, Optional
+from urllib.parse import parse_qs, urljoin, urlparse
+
+import httpx
+
+from .config import settings
+from .models import ChargingSession, Station, TokenResponse
+
+
+class ElliAPIClient:
+    """Client for Elli Charging API with OAuth2 PKCE authentication"""
+
+    # Default OAuth2 configuration (from official Elli iOS app)
+    DEFAULT_AUTH_BASE_URL = "https://login.elli.eco"
+    DEFAULT_API_BASE_URL = "https://api.elli.eco"
+    DEFAULT_CLIENT_ID = "vFGCyS5GUbctkPk1FfcNH6TrDtyfUCwX"
+    DEFAULT_REDIRECT_URI = "com.elli.ios.emsp://login.elli.eco/ios/com.elli.ios.emsp/callback"
+    DEFAULT_AUDIENCE = "https://api.elli.eco/"
+    DEFAULT_SCOPE = "offline_access openid profile"
+
+    def __init__(
+        self,
+        auth_base_url: Optional[str] = None,
+        api_base_url: Optional[str] = None,
+        client_id: Optional[str] = None,
+        redirect_uri: Optional[str] = None,
+        audience: Optional[str] = None,
+        scope: Optional[str] = None,
+    ):
+        """
+        Initialize Elli API Client.
+
+        Args:
+            auth_base_url: OAuth2 authorization server URL (default: from env or DEFAULT_AUTH_BASE_URL)
+            api_base_url: Elli API base URL (default: from env or DEFAULT_API_BASE_URL)
+            client_id: OAuth2 client ID (default: from env or DEFAULT_CLIENT_ID)
+            redirect_uri: OAuth2 redirect URI (default: from env or DEFAULT_REDIRECT_URI)
+            audience: OAuth2 audience (default: from env or DEFAULT_AUDIENCE)
+            scope: OAuth2 scope (default: from env or DEFAULT_SCOPE)
+        """
+        self.client = httpx.Client(timeout=30.0)
+        self.access_token: Optional[str] = None
+        self.refresh_token: Optional[str] = None
+
+        # Load config: parameter > environment > default
+        self.auth_base_url = auth_base_url or settings.elli_auth_base_url or self.DEFAULT_AUTH_BASE_URL
+        self.api_base_url = api_base_url or settings.elli_api_base_url or self.DEFAULT_API_BASE_URL
+        self.client_id = client_id or settings.elli_client_id or self.DEFAULT_CLIENT_ID
+        self.redirect_uri = redirect_uri or settings.elli_redirect_uri or self.DEFAULT_REDIRECT_URI
+        self.audience = audience or settings.elli_audience or self.DEFAULT_AUDIENCE
+        self.scope = scope or settings.elli_scope or self.DEFAULT_SCOPE
+
+    def _generate_pkce_pair(self) -> tuple[str, str]:
+        """Generate PKCE code verifier and code challenge"""
+        # Generate code verifier (43-128 characters)
+        code_verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).decode("utf-8").rstrip("=")
+
+        # Generate code challenge (SHA256 hash of verifier)
+        code_challenge = (
+            base64.urlsafe_b64encode(hashlib.sha256(code_verifier.encode("utf-8")).digest()).decode("utf-8").rstrip("=")
+        )
+
+        return code_verifier, code_challenge
+
+    def _generate_state(self) -> str:
+        """Generate random state parameter for OAuth2"""
+        return base64.urlsafe_b64encode(secrets.token_bytes(32)).decode("utf-8").rstrip("=")
+
+    def login(self, email: str, password: str) -> TokenResponse:
+        """
+        Login to Elli API using username/password with OAuth2 PKCE flow.
+
+        Args:
+            email: Elli account email
+            password: Elli account password
+
+        Returns:
+            TokenResponse with access_token, refresh_token, etc.
+
+        Raises:
+            ValueError: If login fails or authorization code cannot be extracted
+        """
+        # Generate PKCE parameters
+        code_verifier, code_challenge = self._generate_pkce_pair()
+        state = self._generate_state()
+
+        # Step 1: Initiate authorization with PKCE
+        authorize_params = {
+            "client_id": self.client_id,
+            "code_challenge": code_challenge,
+            "code_challenge_method": "S256",
+            "audience": self.audience,
+            "redirect_uri": self.redirect_uri,
+            "scope": self.scope,
+            "response_type": "code",
+            "state": state,
+            "prompt": "login",
+            "connection_scope": "openid profile",
+            "ui_locales": "de",
+        }
+
+        # Get login page to obtain state and cookies
+        auth_response = self.client.get(
+            f"{self.auth_base_url}/authorize", params=authorize_params, follow_redirects=True
+        )
+
+        # Extract state from the redirected URL
+        auth_state = state
+        if "state=" in str(auth_response.url):
+            parsed = urlparse(str(auth_response.url))
+            query_params = parse_qs(parsed.query)
+            if "state" in query_params:
+                auth_state = query_params["state"][0]
+
+        # Step 2: Submit login credentials
+        login_data = {"username": email, "password": password, "action": "default"}
+
+        # The actual login endpoint with state
+        login_url = f"{self.auth_base_url}/u/login"
+        login_params = {"state": auth_state, "ui_locales": "de"}
+
+        login_response = self.client.post(
+            login_url,
+            params=login_params,
+            data=login_data,
+            headers={
+                "Content-Type": "application/x-www-form-urlencoded",
+                "Origin": self.auth_base_url,
+            },
+            follow_redirects=False,
+        )
+
+        # Step 3: Follow redirect chain to get authorization code
+        max_redirects = 10
+        redirect_count = 0
+        current_response = login_response
+        auth_code = None
+
+        while redirect_count < max_redirects:
+            if current_response.status_code not in [302, 303, 307, 308]:
+                break
+
+            location = current_response.headers.get("Location", "")
+            if not location:
+                break
+
+            # Make location absolute if it's relative
+            if location.startswith("/"):
+                location = urljoin(self.auth_base_url, location)
+
+            # Check if we have the authorization code
+            if "code=" in location:
+                code_match = re.search(r"code=([^&]+)", location)
+                if code_match:
+                    auth_code = code_match.group(1)
+                    break
+
+            # Follow the redirect
+            current_response = self.client.get(
+                location, follow_redirects=False, headers={"Referer": self.auth_base_url}
+            )
+            redirect_count += 1
+
+        if not auth_code:
+            # Check final response
+            if current_response.status_code == 200:
+                # Look for code in the response body or URL
+                code_match = re.search(r'code=([^&\'"]+)', str(current_response.text))
+                if code_match:
+                    auth_code = code_match.group(1)
+
+        if not auth_code:
+            raise ValueError(
+                f"Could not extract authorization code. Last status: {current_response.status_code}, "
+                f"Last URL: {current_response.url}"
+            )
+
+        # Step 4: Exchange authorization code for tokens
+        token_data = {
+            "code": auth_code,
+            "client_id": self.client_id,
+            "redirect_uri": self.redirect_uri,
+            "grant_type": "authorization_code",
+            "code_verifier": code_verifier,
+        }
+
+        token_response = self.client.post(
+            f"{self.auth_base_url}/oauth/token",
+            json=token_data,
+            headers={
+                "Content-Type": "application/json",
+            },
+        )
+
+        if token_response.status_code != 200:
+            raise ValueError(f"Token exchange failed: {token_response.status_code} - {token_response.text}")
+
+        token_data_response = token_response.json()
+        token = TokenResponse(**token_data_response)
+
+        # Store tokens
+        self.access_token = token.access_token
+        self.refresh_token = token.refresh_token
+
+        return token
+
+    def _get_headers(self) -> Dict[str, str]:
+        """Get headers for API requests"""
+        if not self.access_token:
+            raise ValueError("Not authenticated. Call login() first.")
+
+        return {
+            "Authorization": f"Bearer {self.access_token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": "Elli-Charging-Prod/10221",
+            "platform": "iOS",
+        }
+
+    def get_charging_sessions(self, include_momentary_speed: bool = True) -> list[ChargingSession]:
+        """
+        Get all charging sessions.
+
+        Args:
+            include_momentary_speed: Include momentary charging power in watts (default: True)
+
+        Returns:
+            List of ChargingSession objects containing session data including:
+            - Session ID, station ID, status
+            - Start/end times
+            - Energy consumption in Wh
+            - Momentary power in W (if include_momentary_speed=True)
+            - RFID card information
+
+        Raises:
+            ValueError: If not authenticated or API request fails
+        """
+        params = {}
+        if include_momentary_speed:
+            params["include_momentary_charging_speed_watts"] = "true"
+
+        response = self.client.get(
+            f"{self.api_base_url}/chargeathome/v1/charging-sessions", headers=self._get_headers(), params=params
+        )
+
+        if response.status_code != 200:
+            raise ValueError(f"Failed to get charging sessions: {response.status_code} - {response.text}")
+
+        data = response.json()
+        sessions = []
+        for session_data in data.get("charging_sessions", []):
+            sessions.append(ChargingSession(**session_data))
+
+        return sessions
+
+    def get_stations(self) -> list[Station]:
+        """
+        Get all charging stations associated with the account.
+
+        Returns:
+            List of Station objects containing:
+            - Station ID, name, serial number
+            - Model information
+            - Firmware version
+            - Status (e.g., IDLE, CONNECTED, CHARGING)
+
+        Raises:
+            ValueError: If not authenticated or API request fails
+        """
+        response = self.client.get(f"{self.api_base_url}/chargeathome/v1/stations", headers=self._get_headers())
+
+        if response.status_code != 200:
+            raise ValueError(f"Failed to get stations: {response.status_code} - {response.text}")
+
+        data = response.json()
+        stations = []
+        for station_data in data.get("stations", []):
+            stations.append(Station(**station_data))
+
+        return stations
+
+    def get_firmware_info(self) -> list[Station]:
+        """
+        Get firmware information for all stations.
+
+        Returns:
+            List of Station objects with firmware details including:
+            - Current firmware version
+            - Available updates (if any)
+
+        Raises:
+            ValueError: If not authenticated or API request fails
+        """
+        response = self.client.get(f"{self.api_base_url}/chargeathome/v1/firmware/updates", headers=self._get_headers())
+
+        if response.status_code != 200:
+            raise ValueError(f"Failed to get firmware info: {response.status_code} - {response.text}")
+
+        data = response.json()
+        stations = []
+        for station_data in data.get("stations", []):
+            stations.append(Station(**station_data))
+
+        return stations
+
+    def get_accumulated_charging(self, station_id: str) -> Dict[str, Any]:
+        """
+        Get accumulated charging statistics for a specific station.
+
+        Args:
+            station_id: The ID of the charging station
+
+        Returns:
+            Dictionary containing accumulated statistics:
+            - Total energy charged (kWh)
+            - Total number of sessions
+            - Time-based statistics
+
+        Raises:
+            ValueError: If not authenticated or API request fails
+        """
+        response = self.client.get(
+            f"{self.api_base_url}/chargeathome/v1/charging-sessions/accumulated",
+            headers=self._get_headers(),
+            params={"station_id": station_id},
+        )
+
+        if response.status_code != 200:
+            raise ValueError(f"Failed to get accumulated charging: {response.status_code} - {response.text}")
+
+        return response.json()
+
+    def close(self):
+        """
+        Close the HTTP client and cleanup resources.
+
+        Should be called when done using the client, or use context manager (with statement).
+        """
+        self.client.close()
+
+    def __enter__(self):
+        """Context manager entry"""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - ensures cleanup"""
+        self.close()

elli_client/config.py

@@ -0,0 +1,32 @@
+"""Configuration management for Elli API"""
+
+from typing import Optional
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables"""
+
+    # User Credentials
+    elli_email: Optional[str] = None
+    elli_password: Optional[str] = None
+    elli_station_id: Optional[str] = None
+
+    # OAuth2 Configuration (optional overrides)
+    # If not set in .env, defaults from ElliAPIClient will be used
+    elli_auth_base_url: Optional[str] = None
+    elli_api_base_url: Optional[str] = None
+    elli_client_id: Optional[str] = None
+    elli_redirect_uri: Optional[str] = None
+    elli_audience: Optional[str] = None
+    elli_scope: Optional[str] = None
+
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+        case_sensitive = False
+
+
+# Global settings instance
+settings = Settings()

elli_client/models.py

@@ -0,0 +1,62 @@
+"""Data models for Elli API"""
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class TokenResponse(BaseModel):
+    """OAuth2 token response from Elli API."""
+
+    access_token: str  # JWT access token for API authentication
+    refresh_token: str  # Refresh token for obtaining new access tokens
+    id_token: str  # OpenID Connect ID token
+    token_type: str  # Token type (usually "Bearer")
+    expires_in: int  # Token expiration time in seconds
+    scope: str  # Granted OAuth2 scopes
+
+
+class ChargingSession(BaseModel):
+    """Charging session data from Elli API."""
+
+    id: str
+    station_id: str
+    start_date_time: str
+
+    # Energy and power data
+    energy_consumption_wh: Optional[int] = None
+    momentary_charging_speed_watts: Optional[int] = None
+
+    # Session state
+    lifecycle_state: Optional[str] = None
+    charging_state: Optional[str] = None
+
+    # Authentication and authorization
+    connector_id: Optional[int] = None
+    authentication_method: Optional[str] = None
+    authorization_mode: Optional[str] = None
+    rfid_card_id: Optional[str] = None
+    rfid_card_serial_number: Optional[str] = None
+
+    # Timestamps
+    end_date_time: Optional[str] = None
+    last_updated: Optional[str] = None
+
+
+class FirmwareInfo(BaseModel):
+    """Firmware information for a station."""
+
+    id: str
+    version: str
+    release_notes_link: Optional[str] = None
+
+
+class Station(BaseModel):
+    """Charging station information."""
+
+    id: str  # Unique station identifier
+    name: str  # Station name
+    serial_number: Optional[str] = None  # Hardware serial number
+    model: Optional[str] = None  # Station model (e.g., "Elli Wallbox Pro")
+    firmware_version: Optional[str] = None  # Current firmware version
+    installed_firmware: Optional[FirmwareInfo] = None  # Detailed firmware info

elli_client-1.0.3.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: elli-client
+Version: 1.0.3
+Summary: Python client for Elli Wallbox API
+Author: Marc Szymkowiak
+License: MIT
+Project-URL: Homepage, https://github.com/marcszy91/elli-client
+Project-URL: Bug Tracker, https://github.com/marcszy91/elli-client/issues
+Project-URL: Source Code, https://github.com/marcszy91/elli-client
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pydantic-settings>=2.5.0
+Provides-Extra: dev
+Requires-Dist: black>=24.3.0; extra == "dev"
+Requires-Dist: isort>=5.13.2; extra == "dev"
+Requires-Dist: flake8>=7.0.0; extra == "dev"
+Requires-Dist: pytest>=8.1.1; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.6; extra == "dev"
+Requires-Dist: pre-commit>=3.7.0; extra == "dev"
+Dynamic: license-file
+
+# Elli Client
+
+Python client library for the Elli Wallbox API.
+
+## Installation
+
+```bash
+pip install elli-client
+```
+
+## Quick Start
+
+```python
+from elli_client import ElliAPIClient
+
+# Initialize client and login
+client = ElliAPIClient()
+token = client.login("your.email@example.com", "your_password")
+
+# Get charging stations
+stations = client.get_stations()
+for station in stations:
+    print(f"Station: {station.name} ({station.id})")
+
+# Get active charging session
+session = client.get_active_charging_session()
+if session:
+    print(f"Charging: {session.energy_consumption_wh / 1000:.2f} kWh")
+    print(f"Power: {session.momentary_power_w} W")
+```
+
+## Features
+
+- Authentication with Elli Account
+- Query charging stations
+- Retrieve charging sessions (active and historical)
+- Current charging power and energy consumption
+- Station information
+
+## Documentation
+
+- **[Quick Start Guide](docs/quick-start.md)** - Get started in minutes
+- **[API Reference](docs/api.md)** - Complete API documentation
+- **[Docs Overview](docs/README.md)** - Documentation index
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/marcszy91/elli-client
+cd elli-client
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+
+# Copy environment template and add your credentials
+cp .env.template .env
+# Edit .env and add your ELLI_EMAIL and ELLI_PASSWORD
+```
+
+### Testing
+
+```bash
+# Format code
+black src/
+isort src/
+
+# Run tests (when implemented)
+pytest
+```
+
+## Home Assistant Integration
+
+This client is used by the [Elli Charger HACS integration](https://github.com/marcszy91/hacs-elli-charger) for Home Assistant.
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Disclaimer
+
+This library was created through reverse engineering of the official Elli iPhone app. It is not officially supported by Elli or Volkswagen Group Charging GmbH. Use at your own risk.

elli_client-1.0.3.dist-info/RECORD

@@ -0,0 +1,9 @@
+elli_client/__init__.py,sha256=L5OOtu5ssm4C-S8UNW4NGQIl2RWXelVPzUo3iJ9iyh0,279
+elli_client/client.py,sha256=Vs-H_TA7O-L5o0YOjSm4weE3VdipgrPlBBvAqnbFQ2U,12825
+elli_client/config.py,sha256=iwf9BEwyTa5rK40BZ1Yg9A4xZLtDF4TLJIcLedgJgeA,887
+elli_client/models.py,sha256=uySFwPvZ199x6LJbE6_QBZu0Oje2ECUTbB6_zVCQ-hw,1829
+elli_client-1.0.3.dist-info/licenses/LICENSE,sha256=_j0lKzBDjuE73KOKnXY5090YQF4wgu05gFe4HTKbZkI,1072
+elli_client-1.0.3.dist-info/METADATA,sha256=8F241Z5VqPajVl0oDFDXI8mGscD6GBARBJAlec9cL34,3197
+elli_client-1.0.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+elli_client-1.0.3.dist-info/top_level.txt,sha256=KMmrqD-T6xXIxCwtLQk6QlJ1OOWzyD8vFIQkWcWiQ6k,12
+elli_client-1.0.3.dist-info/RECORD,,

elli_client-1.0.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

elli_client-1.0.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marc Szymkowiak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

elli_client-1.0.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+elli_client