sigenergy-cloud 0.1.0__tar.gz

sigenergy_cloud-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sigenergy-cloud contributors
+
+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.

sigenergy_cloud-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: sigenergy-cloud
+Version: 0.1.0
+Summary: Async Python client for the Sigenergy Cloud app API
+Author: sigenergy-cloud contributors
+Maintainer-email: Daniel Schlaug <daniel@schlaug.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/solidfox/sigenergy-cloud
+Project-URL: Issues, https://github.com/solidfox/sigenergy-cloud/issues
+Project-URL: Source, https://github.com/solidfox/sigenergy-cloud
+Keywords: sigenergy,home-assistant,asyncio,energy,solar,evse
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: pycryptodome>=3.19.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: aioresponses>=0.7; extra == "dev"
+Requires-Dist: python-dotenv>=1.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# sigenergy-cloud
+
+Async Python client for the Sigenergy Cloud app API.
+
+This package is a minimal async wrapper around the private Sigenergy Cloud app
+API. It is built for Home Assistant style integrations that need to read and
+control Sigenergy stations, batteries, and DC chargers.
+
+## Install
+
+```bash
+python -m pip install sigenergy-cloud
+```
+
+## Example
+
+```python
+from sigenergy_cloud import SigenergyCloudClient
+
+client = SigenergyCloudClient("user@example.com", "password", region="eu")
+await client.connect()
+
+flow = await client.energy_flow()
+mode = await client.current_operational_mode()
+chargers = client.dc_sns
+
+await client.close()
+```
+
+## Shape
+
+- Use `SigenergyCloudClient` for cloud calls.
+- Call `connect()` once before reading data or changing settings.
+- The client keeps the station ID and charger serial numbers after connecting.
+- Simple settings use small typed value objects.
+- Vendor response payloads are returned as dictionaries where the API shape is
+  still being mapped.
+
+## Regions
+
+| Region | Base URL |
+| --- | --- |
+| `eu` | `https://api-eu.sigencloud.com/` |
+| `cn` | `https://api-cn.sigencloud.com/` |
+| `apac` | `https://api-apac.sigencloud.com/` |
+| `us` | `https://api-us.sigencloud.com/` |

sigenergy_cloud-0.1.0/README.md

@@ -0,0 +1,46 @@
+# sigenergy-cloud
+
+Async Python client for the Sigenergy Cloud app API.
+
+This package is a minimal async wrapper around the private Sigenergy Cloud app
+API. It is built for Home Assistant style integrations that need to read and
+control Sigenergy stations, batteries, and DC chargers.
+
+## Install
+
+```bash
+python -m pip install sigenergy-cloud
+```
+
+## Example
+
+```python
+from sigenergy_cloud import SigenergyCloudClient
+
+client = SigenergyCloudClient("user@example.com", "password", region="eu")
+await client.connect()
+
+flow = await client.energy_flow()
+mode = await client.current_operational_mode()
+chargers = client.dc_sns
+
+await client.close()
+```
+
+## Shape
+
+- Use `SigenergyCloudClient` for cloud calls.
+- Call `connect()` once before reading data or changing settings.
+- The client keeps the station ID and charger serial numbers after connecting.
+- Simple settings use small typed value objects.
+- Vendor response payloads are returned as dictionaries where the API shape is
+  still being mapped.
+
+## Regions
+
+| Region | Base URL |
+| --- | --- |
+| `eu` | `https://api-eu.sigencloud.com/` |
+| `cn` | `https://api-cn.sigencloud.com/` |
+| `apac` | `https://api-apac.sigencloud.com/` |
+| `us` | `https://api-us.sigencloud.com/` |

sigenergy_cloud-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sigenergy-cloud"
+version = "0.1.0"
+description = "Async Python client for the Sigenergy Cloud app API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "sigenergy-cloud contributors" },
+]
+maintainers = [
+    { name = "Daniel Schlaug", email = "daniel@schlaug.com" },
+]
+requires-python = ">=3.10"
+keywords = ["sigenergy", "home-assistant", "asyncio", "energy", "solar", "evse"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aiohttp>=3.9.0",
+    "pycryptodome>=3.19.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "aioresponses>=0.7",
+    "python-dotenv>=1.0",
+    "build>=1.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/solidfox/sigenergy-cloud"
+Issues = "https://github.com/solidfox/sigenergy-cloud/issues"
+Source = "https://github.com/solidfox/sigenergy-cloud"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sigenergy_cloud = ["py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = [
+    "live: requires real SIGENERGY_USERNAME / SIGENERGY_PASSWORD env vars (deselect with -m 'not live')",
+    "write: test writes to the device — always paired with the restore fixture",
+]

sigenergy_cloud-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sigenergy_cloud-0.1.0/src/sigenergy_cloud/__init__.py

@@ -0,0 +1,23 @@
+"""Owned async client for the Sigenergy Cloud app API."""
+
+from .client import SigenergyCloudClient
+from .errors import (
+    SigenergyCloudAPIError,
+    SigenergyCloudAuthError,
+    SigenergyCloudError,
+    SigenergyCloudRateLimitError,
+    SigenergyCloudTokenExpiredError,
+)
+from .models import BatteryLevelSettings, PeakShavingSchedule, PeakShavingSlot
+
+__all__ = [
+    "BatteryLevelSettings",
+    "PeakShavingSchedule",
+    "PeakShavingSlot",
+    "SigenergyCloudAPIError",
+    "SigenergyCloudAuthError",
+    "SigenergyCloudClient",
+    "SigenergyCloudError",
+    "SigenergyCloudRateLimitError",
+    "SigenergyCloudTokenExpiredError",
+]

sigenergy_cloud-0.1.0/src/sigenergy_cloud/auth.py

@@ -0,0 +1,135 @@
+"""Authentication primitives for the Sigenergy Cloud app API."""
+
+from __future__ import annotations
+
+import base64
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import aiohttp
+from Crypto.Cipher import AES
+from Crypto.Util.Padding import pad
+
+from .errors import SigenergyCloudAuthError, SigenergyCloudTokenExpiredError
+
+_PASSWORD_AES_KEY = "sigensigensigenp"
+_PASSWORD_AES_IV = "sigensigensigenp"
+_OAUTH_CLIENT_ID = "sigen"
+_OAUTH_CLIENT_SECRET = "sigen"
+_TOKEN_REFRESH_MARGIN_SECONDS = 60
+
+
+def encrypt_password(password: str) -> str:
+    """Return the AES-CBC password encoding expected by Sigenergy Cloud."""
+    cipher = AES.new(
+        _PASSWORD_AES_KEY.encode("utf-8"),
+        AES.MODE_CBC,
+        _PASSWORD_AES_IV.encode("latin1"),
+    )
+    encrypted = cipher.encrypt(pad(password.encode("utf-8"), AES.block_size))
+    return base64.b64encode(encrypted).decode("utf-8")
+
+
+@dataclass(frozen=True, slots=True)
+class TokenBundle:
+    """OAuth tokens plus their local expiry deadline."""
+
+    access_token: str
+    refresh_token: str
+    expires_at: float
+
+    @classmethod
+    def from_api(cls, payload: dict[str, Any]) -> "TokenBundle":
+        """Create a token bundle from Sigenergy's OAuth response shape."""
+        expires_in = int(payload["expires_in"])
+        return cls(
+            access_token=str(payload["access_token"]),
+            refresh_token=str(payload["refresh_token"]),
+            expires_at=time.time() + max(0, expires_in - _TOKEN_REFRESH_MARGIN_SECONDS),
+        )
+
+    @property
+    def expired(self) -> bool:
+        """Return true when the token should be refreshed before use."""
+        return time.time() >= self.expires_at
+
+
+class OAuthSession:
+    """Small state holder for Sigenergy's password-grant OAuth flow."""
+
+    def __init__(self) -> None:
+        self._tokens: TokenBundle | None = None
+
+    @property
+    def headers(self) -> dict[str, str]:
+        """Return JSON headers for authenticated cloud requests."""
+        if self._tokens is None:
+            raise SigenergyCloudAuthError("Sigenergy Cloud is not authenticated")
+        return {
+            "Authorization": f"Bearer {self._tokens.access_token}",
+            "Content-Type": "application/json",
+        }
+
+    async def authenticate(
+        self,
+        session: aiohttp.ClientSession,
+        base_url: str,
+        username: str,
+        encrypted_password: str,
+    ) -> None:
+        """Authenticate with username/password and store access tokens."""
+        self._tokens = await self._request_token(
+            session,
+            base_url,
+            {
+                "username": username,
+                "password": encrypted_password,
+                "grant_type": "password",
+            },
+            SigenergyCloudAuthError,
+        )
+
+    async def ensure_token(self, session: aiohttp.ClientSession, base_url: str) -> None:
+        """Refresh the token if needed."""
+        if self._tokens is None:
+            raise SigenergyCloudAuthError("Sigenergy Cloud is not authenticated")
+        if not self._tokens.expired:
+            return
+        self._tokens = await self._request_token(
+            session,
+            base_url,
+            {
+                "grant_type": "refresh_token",
+                "refresh_token": self._tokens.refresh_token,
+            },
+            SigenergyCloudTokenExpiredError,
+        )
+
+    async def _request_token(
+        self,
+        session: aiohttp.ClientSession,
+        base_url: str,
+        form: dict[str, str],
+        error_type: type[SigenergyCloudAuthError],
+    ) -> TokenBundle:
+        url = f"{base_url}auth/oauth/token"
+        async with session.post(
+            url,
+            data=form,
+            auth=aiohttp.BasicAuth(_OAUTH_CLIENT_ID, _OAUTH_CLIENT_SECRET),
+        ) as response:
+            body = await response.text()
+            if response.status != 200:
+                raise error_type(
+                    f"Sigenergy Cloud authentication failed: HTTP {response.status}; {body}"
+                )
+            payload = await response.json()
+
+        token_payload = payload.get("data", payload)
+        if not isinstance(token_payload, dict):
+            raise error_type(f"Unexpected Sigenergy Cloud token response: {payload!r}")
+        try:
+            return TokenBundle.from_api(token_payload)
+        except KeyError as exc:
+            raise error_type(f"Incomplete Sigenergy Cloud token response: {payload!r}") from exc