sigenergy-cloud 0.1.0__py3-none-any.whl

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/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

sigenergy_cloud/client.py

@@ -0,0 +1,491 @@
+"""High-level Sigenergy Cloud client used by Home Assistant integrations."""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import Any
+
+import aiohttp
+
+from .auth import OAuthSession, encrypt_password
+from .errors import SigenergyCloudAPIError, SigenergyCloudRateLimitError
+from .models import BatteryLevelSettings, PeakShavingSchedule, PeakShavingSlot
+from .regions import base_url_for_region
+from .transport import CloudTransport
+
+
+class SigenergyCloudClient:
+    """Focused async client for the Sigenergy Cloud app API.
+
+    The class intentionally exposes domain operations, not a generic REST
+    interface. Raw dictionaries are returned for endpoints that Home Assistant
+    currently displays directly or whose shape is still under observation.
+    """
+
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        *,
+        region: str = "eu",
+        session: aiohttp.ClientSession | None = None,
+    ) -> None:
+        self.username = username
+        self.region = region
+        self.base_url = base_url_for_region(region)
+        self._encrypted_password = encrypt_password(password)
+        self._owned_session: aiohttp.ClientSession | None = None
+        self._session = session
+        self._auth = OAuthSession()
+        self._transport = CloudTransport(self.base_url, self._auth)
+
+        self.station_id: str | None = None
+        self.ac_sns: tuple[str, ...] = ()
+        self.dc_sns: tuple[str, ...] = ()
+        self._operational_modes: dict[str, Any] | None = None
+
+    @property
+    def dc_sn(self) -> str | None:
+        """Return the first DC charger serial number, for older single-device flows."""
+        return self.dc_sns[0] if self.dc_sns else None
+
+    async def connect(self) -> None:
+        """Authenticate and load the station/device identifiers."""
+        session = await self._http_session()
+        await self._auth.authenticate(
+            session,
+            self.base_url,
+            self.username,
+            self._encrypted_password,
+        )
+        await self.refresh_station()
+
+    async def close(self) -> None:
+        """Close the owned HTTP session, if this client created one."""
+        if self._owned_session is not None:
+            await self._owned_session.close()
+            self._owned_session = None
+
+    async def refresh_station(self) -> dict[str, Any]:
+        """Fetch station home data and cache station and charger serials."""
+        data = await self._data("GET", "device/owner/station/home")
+        self.station_id = str(data["stationId"])
+        self.ac_sns = tuple(str(sn) for sn in data.get("acSnList") or ())
+        self.dc_sns = tuple(str(sn) for sn in data.get("dcSnList") or ())
+        return data
+
+    async def energy_flow(self) -> dict[str, Any]:
+        """Return real-time station energy flow."""
+        try:
+            return await self._station_data(
+                "GET",
+                "device/sigen/station/energyflow/async",
+                params={"refreshFlag": "false"},
+            )
+        except SigenergyCloudRateLimitError:
+            raise
+        except SigenergyCloudAPIError:
+            return await self._data(
+                "GET",
+                "device/sigen/station/energyflow",
+                params={"id": self._station_id()},
+            )
+
+    async def available_operational_modes(self) -> dict[str, Any]:
+        """Return available energy-profile modes."""
+        data = await self._station_data("GET", "device/energy-profile/mode/all/{station_id}")
+        self._operational_modes = data
+        return data
+
+    async def current_operational_mode(self) -> str:
+        """Return the current energy-profile mode label."""
+        if self._operational_modes is None:
+            await self.available_operational_modes()
+        data = await self._station_data(
+            "GET", "device/energy-profile/mode/current/{station_id}"
+        )
+        mode = data["currentMode"]
+        profile_id = data["currentProfileId"]
+        modes = self._operational_modes or {}
+        if mode != 9:
+            for item in modes.get("defaultWorkingModes", ()):
+                if item.get("value") == str(mode):
+                    return str(item["label"])
+        else:
+            for item in modes.get("energyProfileItems", ()):
+                if item.get("profileId") == profile_id:
+                    return str(item["name"])
+        return "Unknown mode"
+
+    async def set_operational_mode(self, mode: int, profile_id: int = -1) -> dict[str, Any]:
+        """Set the station energy-profile mode."""
+        return await self._envelope(
+            "PUT",
+            "device/energy-profile/mode",
+            json={
+                "stationId": self._station_id_int(),
+                "operationMode": mode,
+                "profileId": profile_id,
+            },
+        )
+
+    async def battery_levels(self) -> BatteryLevelSettings:
+        """Return battery SOC threshold settings."""
+        data = await self._station_data(
+            "GET", "device/energy-profile/battery/level/{station_id}"
+        )
+        return BatteryLevelSettings.from_api(data)
+
+    async def set_battery_levels(self, settings: BatteryLevelSettings) -> dict[str, Any]:
+        """Replace battery SOC threshold settings."""
+        return await self._envelope(
+            "PUT",
+            "device/energy-profile/battery/level",
+            json=settings.to_api(self._station_id_int()),
+        )
+
+    async def grid_export_limit(self) -> dict[str, Any]:
+        """Return owner grid-export limit settings."""
+        return await self._station_data(
+            "GET", "device/energy-profile/grid/limitation/export/{station_id}"
+        )
+
+    async def set_grid_export_limit(
+        self, limit_kw: float, *, enabled: bool = True
+    ) -> dict[str, Any]:
+        """Set owner grid-export limit settings."""
+        return await self._set_grid_limit("export", limit_kw, enabled)
+
+    async def grid_import_limit(self) -> dict[str, Any]:
+        """Return owner grid-import limit settings."""
+        return await self._station_data(
+            "GET", "device/energy-profile/grid/limitation/import/{station_id}"
+        )
+
+    async def set_grid_import_limit(
+        self, limit_kw: float, *, enabled: bool = True
+    ) -> dict[str, Any]:
+        """Set owner grid-import limit settings."""
+        return await self._set_grid_limit("import", limit_kw, enabled)
+
+    async def battery_export_limitation(self) -> dict[str, Any]:
+        """Return whether the battery may export to the grid."""
+        return await self._station_data(
+            "GET", "device/energy-profile/battery/export/limitation/{station_id}"
+        )
+
+    async def set_battery_export_limitation(self, enabled: bool) -> dict[str, Any]:
+        """Enable or disable battery export to the grid."""
+        return await self._envelope(
+            "PUT",
+            "device/energy-profile/battery/export/limitation",
+            json={
+                "stationId": self._station_id_int(),
+                "installerSetEnable": None,
+                "ownerSetEnable": enabled,
+            },
+        )
+
+    async def peak_shaving_schedule(self) -> PeakShavingSchedule:
+        """Return the full peak-shaving schedule."""
+        data = await self._station_data(
+            "GET", "device/dischargesetting/peak/shaving/{station_id}"
+        )
+        return PeakShavingSchedule.from_api(data)
+
+    async def set_peak_shaving_schedule(
+        self, schedule: PeakShavingSchedule
+    ) -> dict[str, Any]:
+        """Replace the full peak-shaving schedule."""
+        return await self._envelope(
+            "POST",
+            "device/dischargesetting/peak/shaving",
+            json=schedule.to_api(self._station_id_int()),
+        )
+
+    async def set_peak_shaving_slot(self, slot: PeakShavingSlot) -> dict[str, Any]:
+        """Update one peak-shaving slot via read-modify-write."""
+        schedule = (await self.peak_shaving_schedule()).with_slot(slot)
+        return await self.set_peak_shaving_schedule(schedule)
+
+    async def dc_charge_mode_soc_range(self) -> dict[str, Any]:
+        """Return allowed SOC ranges for DC charger mode settings."""
+        return await self._station_data(
+            "GET", "device/charge/mode/soc/range", station_query=True
+        )
+
+    async def dc_charge_mode(self, dc_sn: str | None = None) -> dict[str, Any]:
+        """Return the current DC charger mode and mode settings."""
+        return await self._dc_data("GET", "device/charge/mode/dc", dc_sn)
+
+    async def set_dc_charge_mode(
+        self,
+        charge_mode: int,
+        *,
+        dc_sn: str | None = None,
+        enable_from_pack: bool | None = None,
+        cutoff_soc_from_pack: float | None = None,
+        allows_discharge_power: float | None = None,
+        vehicle_discharge_cutoff_soc: int | None = None,
+    ) -> dict[str, Any]:
+        """Set the DC charger mode and optional mode-specific settings."""
+        payload: dict[str, Any] = {
+            "stationId": self._station_id_int(),
+            "snCode": self._dc_sn(dc_sn),
+            "chargeMode": charge_mode,
+        }
+        optional_fields = {
+            "enableFromPack": enable_from_pack,
+            "cutoffSocFromPack": cutoff_soc_from_pack,
+            "allowsDischargePower": allows_discharge_power,
+            "vehicleDischargeCutoffSoc": vehicle_discharge_cutoff_soc,
+        }
+        payload.update({key: value for key, value in optional_fields.items() if value is not None})
+        return await self._envelope("POST", "device/charge/mode/dc", json=payload)
+
+    async def dc_charge_setting(self, dc_sn: str | None = None) -> dict[str, Any]:
+        """Return DC charger charge-power and stop-SOC settings."""
+        return await self._dc_data("GET", "device/dcevse/charge/setting", dc_sn)
+
+    async def set_dc_charge_setting(
+        self,
+        *,
+        allowed_charge_power: float,
+        vehicle_charging_cutoff_soc: int,
+        dc_sn: str | None = None,
+    ) -> dict[str, Any]:
+        """Set DC charger charge-power and stop-SOC settings."""
+        return await self._envelope(
+            "POST",
+            "device/dcevse/charge/setting",
+            json={
+                "stationId": self._station_id_int(),
+                "snCode": self._dc_sn(dc_sn),
+                "allowedChargePower": allowed_charge_power,
+                "vehicleChargingCutoffSoc": vehicle_charging_cutoff_soc,
+            },
+        )
+
+    async def set_dc_charge_enabled(
+        self, enabled: bool, *, dc_sn: str | None = None
+    ) -> dict[str, Any]:
+        """Start or stop DC charging.
+
+        Sigenergy's app API uses enable=0 to start and enable=1 to stop.
+        """
+        return await self._envelope(
+            "PUT",
+            "device/dcevse/charge/start",
+            params={
+                "enable": 0 if enabled else 1,
+                "stationId": self._station_id(),
+                "snCode": self._dc_sn(dc_sn),
+            },
+        )
+
+    async def station_is_charging(self) -> bool:
+        """Return true when the station reports active DC charging."""
+        data = await self._station_data(
+            "POST", "device/charge/check/charge", station_query=True
+        )
+        return bool(data)
+
+    async def dc_status(self, dc_sn: str | None = None) -> dict[str, Any]:
+        """Return the overall DC charger status."""
+        return await self._dc_data("GET", "device/dcevse/status", dc_sn)
+
+    async def dc_plug_status(self, dc_sn: str | None = None) -> bool | None:
+        """Return whether a vehicle is plugged into the DC charger."""
+        data = await self._dc_data("GET", "device/dcevse/plug/status", dc_sn)
+        if isinstance(data, bool) or data is None:
+            return data
+        if isinstance(data, dict):
+            for key in ("plugged", "pluggedIn", "isPlugged", "plugStatus", "status"):
+                if key in data:
+                    return bool(data[key])
+        return bool(data)
+
+    async def dc_charge_realtime(self, dc_sn: str | None = None) -> dict[str, Any]:
+        """Return real-time DC charging values."""
+        return await self._dc_data("GET", "device/dcevse/charge/realtime", dc_sn)
+
+    async def dc_discharge_realtime(self, dc_sn: str | None = None) -> dict[str, Any]:
+        """Return real-time DC discharge/V2X values."""
+        return await self._dc_data("GET", "device/dcevse/discharge/realtime", dc_sn)
+
+    async def dc_energy_totals(self, dc_sn: str | None = None) -> dict[str, Any]:
+        """Return period energy totals for a DC charger."""
+        return await self._dc_data("GET", "data-process/dcevse/energy", dc_sn)
+
+    async def dc_lifetime_totals(self, dc_sn: str | None = None) -> dict[str, Any]:
+        """Return lifetime charged/discharged totals for a DC charger."""
+        return await self._data(
+            "GET", f"data-process/dcevse/total/{self._station_id()}/{self._dc_sn(dc_sn)}"
+        )
+
+    async def dc_ocpp_status(self, dc_sn: str | None = None) -> dict[str, Any]:
+        """Return DC charger OCPP status."""
+        return await self._dc_data("GET", "device/dcevse/ocpp/status", dc_sn)
+
+    async def dc_session_records(
+        self,
+        *,
+        dc_sn: str | None = None,
+        start_date: date,
+        end_date: date,
+        page: int = 1,
+        page_size: int = 10,
+    ) -> dict[str, Any]:
+        """Return paginated DC charge/discharge session history."""
+        return await self._dc_data(
+            "GET",
+            "data-process/dcevse/record/page",
+            dc_sn,
+            params={
+                "current": page,
+                "size": page_size,
+                "startTime": start_date.strftime("%Y%m%d"),
+                "endTime": end_date.strftime("%Y%m%d"),
+            },
+        )
+
+    async def v2x_discharge_info(self, dc_sn: str | None = None) -> dict[str, Any]:
+        """Return current V2X discharge-session information."""
+        return await self._dc_data(
+            "GET",
+            "device/station-v2x/discharge/info",
+            dc_sn,
+            serial_key="dcSnCode",
+        )
+
+    async def v2x_discharge_settings(self, dc_sn: str | None = None) -> dict[str, Any]:
+        """Return V2X discharge enablement and capability flags."""
+        return await self._dc_data(
+            "GET",
+            "device/station-v2x/select",
+            dc_sn,
+        )
+
+    async def set_v2x_discharge_enabled(
+        self,
+        enabled: bool,
+        *,
+        dc_sn: str | None = None,
+    ) -> dict[str, Any]:
+        """Enable or disable V2X discharge for a DC charger."""
+        return await self._envelope(
+            "POST",
+            "device/station-v2x/open-close",
+            json={
+                "snCode": self._dc_sn(dc_sn),
+                "stationId": self._station_id_int(),
+                "dischargeEnable": 1 if enabled else 0,
+            },
+        )
+
+    async def start_v2x_discharge(
+        self,
+        *,
+        dc_sn: str | None = None,
+        duration_minutes: int = 600,
+        power_cap_kw: float | None = None,
+    ) -> dict[str, Any]:
+        """Start a manual V2X discharge session."""
+        return await self._envelope(
+            "POST",
+            "device/station-v2x/start/discharge",
+            json={
+                "snCode": self._dc_sn(dc_sn),
+                "stationId": self._station_id_int(),
+                "duration": duration_minutes,
+                "powerCap": power_cap_kw,
+            },
+        )
+
+    async def stop_v2x_discharge(self, *, dc_sn: str | None = None) -> dict[str, Any]:
+        """Stop the current V2X discharge session."""
+        return await self._envelope(
+            "POST",
+            "device/station-v2x/stop/discharge",
+            json={"snCode": self._dc_sn(dc_sn), "stationId": self._station_id_int()},
+        )
+
+    async def active_alarms(self, *, page: int = 1, page_size: int = 10) -> dict[str, Any]:
+        """Return paginated active station alarms."""
+        return await self._station_data(
+            "GET",
+            "device/alarm/page",
+            station_query=True,
+            params={"current": page, "size": page_size},
+        )
+
+    async def _set_grid_limit(
+        self, direction: str, limit_kw: float, enabled: bool
+    ) -> dict[str, Any]:
+        return await self._envelope(
+            "PUT",
+            f"device/energy-profile/grid/limitation/{direction}",
+            json={
+                "stationId": self._station_id_int(),
+                "enable": enabled,
+                "maxLimitationOwner": f"{limit_kw:.3f}",
+                "maxLimitationInstaller": None,
+            },
+        )
+
+    async def _dc_data(
+        self,
+        method: str,
+        path: str,
+        dc_sn: str | None,
+        *,
+        serial_key: str = "snCode",
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        query = {"stationId": self._station_id(), serial_key: self._dc_sn(dc_sn)}
+        if params:
+            query.update(params)
+        return await self._data(method, path, params=query)
+
+    async def _station_data(
+        self,
+        method: str,
+        path: str,
+        *,
+        station_query: bool = False,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        path = path.format(station_id=self._station_id())
+        query = dict(params or {})
+        if station_query:
+            query["stationId"] = self._station_id()
+        return await self._data(method, path, params=query or None)
+
+    async def _data(self, method: str, path: str, **kwargs: Any) -> Any:
+        return await self._transport.data(await self._http_session(), method, path, **kwargs)
+
+    async def _envelope(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        return await self._transport.envelope(
+            await self._http_session(), method, path, **kwargs
+        )
+
+    async def _http_session(self) -> aiohttp.ClientSession:
+        if self._session is not None:
+            return self._session
+        if self._owned_session is None or self._owned_session.closed:
+            self._owned_session = aiohttp.ClientSession()
+        return self._owned_session
+
+    def _station_id(self) -> str:
+        if self.station_id is None:
+            raise RuntimeError("SigenergyCloudClient.connect() has not loaded a station")
+        return self.station_id
+
+    def _station_id_int(self) -> int:
+        return int(self._station_id())
+
+    def _dc_sn(self, dc_sn: str | None) -> str:
+        selected = dc_sn or self.dc_sn
+        if selected is None:
+            raise RuntimeError("No Sigenergy DC charger serial number is available")
+        return selected

sigenergy_cloud/errors.py

@@ -0,0 +1,34 @@
+"""Typed exceptions raised by sigenergy-cloud."""
+
+from __future__ import annotations
+
+
+class SigenergyCloudError(Exception):
+    """Base error for all sigenergy-cloud failures."""
+
+
+class SigenergyCloudAuthError(SigenergyCloudError):
+    """Authentication failed or the cloud rejected the current token."""
+
+
+class SigenergyCloudTokenExpiredError(SigenergyCloudAuthError):
+    """The refresh token no longer produced a valid access token."""
+
+
+class SigenergyCloudAPIError(SigenergyCloudError):
+    """The cloud API returned an unsuccessful response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        response_body: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class SigenergyCloudRateLimitError(SigenergyCloudAPIError):
+    """The cloud API rate-limited the request."""

sigenergy_cloud/models.py

@@ -0,0 +1,111 @@
+"""Pure value objects for Sigenergy Cloud settings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Any
+
+
+def _int_percent(value: Any) -> int:
+    return int(float(value))
+
+
+@dataclass(frozen=True, slots=True)
+class BatteryLevelSettings:
+    """Battery SOC thresholds, all expressed as percentages."""
+
+    charge_soc: int
+    discharge_soc: int
+    peak_shaving_soc: int
+    backup_soc: int
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> "BatteryLevelSettings":
+        return cls(
+            charge_soc=_int_percent(data["chargeSOC"]),
+            discharge_soc=_int_percent(data["dischargeSOC"]),
+            peak_shaving_soc=_int_percent(data["peakShavingSOC"]),
+            backup_soc=_int_percent(data["backupSOC"]),
+        )
+
+    def to_api(self, station_id: int) -> dict[str, Any]:
+        return {
+            "stationId": station_id,
+            "chargeSOC": str(self.charge_soc),
+            "dischargeSOC": str(self.discharge_soc),
+            "peakShavingSOC": str(self.peak_shaving_soc),
+            "backupSOC": str(self.backup_soc),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class PeakShavingSlot:
+    """One demand-limit window in a peak-shaving schedule."""
+
+    index: int
+    which_days: tuple[int, ...]
+    start_time: str
+    end_time: str
+    peak_power_kw: float
+
+    @classmethod
+    def from_api(cls, index: int, data: dict[str, Any]) -> "PeakShavingSlot":
+        days = tuple(int(day) for day in str(data["whichDay"]).split(",") if day)
+        return cls(
+            index=index,
+            which_days=days,
+            start_time=str(data["startTime"]),
+            end_time=str(data["endTime"]),
+            peak_power_kw=float(data["peakPower"]),
+        )
+
+    def with_peak_power(self, value: float) -> "PeakShavingSlot":
+        """Return a copy with a different power cap."""
+        return replace(self, peak_power_kw=value)
+
+    def to_api(self) -> dict[str, Any]:
+        return {
+            "whichDay": ",".join(str(day) for day in self.which_days),
+            "startTime": self.start_time,
+            "endTime": self.end_time,
+            "peakPower": self.peak_power_kw,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class PeakShavingSchedule:
+    """Full station peak-shaving schedule."""
+
+    enabled: bool
+    shaving_soc: int
+    slots: tuple[PeakShavingSlot, ...] = ()
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> "PeakShavingSchedule":
+        slots = tuple(
+            PeakShavingSlot.from_api(index, slot)
+            for index, slot in enumerate(data.get("settingList", ()))
+        )
+        return cls(
+            enabled=data.get("controlMode", 0) == 1,
+            shaving_soc=int(data.get("shavingSOC", 0)),
+            slots=slots,
+        )
+
+    def with_slot(self, slot: PeakShavingSlot) -> "PeakShavingSchedule":
+        """Return a copy with one slot replaced by index."""
+        if slot.index < 0 or slot.index >= len(self.slots):
+            raise ValueError(
+                f"Slot index {slot.index} out of range for {len(self.slots)} slots"
+            )
+        slots = list(self.slots)
+        slots[slot.index] = slot
+        return replace(self, slots=tuple(slots))
+
+    def to_api(self, station_id: int) -> dict[str, Any]:
+        return {
+            "stationId": station_id,
+            "controlMode": 1 if self.enabled else 0,
+            "shavingSOC": self.shaving_soc,
+            "settingList": [slot.to_api() for slot in self.slots],
+        }

sigenergy_cloud/py.typed

@@ -0,0 +1 @@
+

sigenergy_cloud/regions.py

@@ -0,0 +1,19 @@
+"""Regional Sigenergy Cloud API endpoints."""
+
+from __future__ import annotations
+
+REGION_BASE_URLS: dict[str, str] = {
+    "eu": "https://api-eu.sigencloud.com/",
+    "cn": "https://api-cn.sigencloud.com/",
+    "apac": "https://api-apac.sigencloud.com/",
+    "us": "https://api-us.sigencloud.com/",
+}
+
+
+def base_url_for_region(region: str) -> str:
+    """Return the API base URL for a Sigenergy Cloud region."""
+    try:
+        return REGION_BASE_URLS[region]
+    except KeyError as exc:
+        supported = ", ".join(sorted(REGION_BASE_URLS))
+        raise ValueError(f"Unsupported Sigenergy region {region!r}; use one of {supported}") from exc

sigenergy_cloud/transport.py

@@ -0,0 +1,118 @@
+"""Internal HTTP transport for the Sigenergy Cloud app API."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import aiohttp
+
+from .auth import OAuthSession
+from .errors import (
+    SigenergyCloudAPIError,
+    SigenergyCloudAuthError,
+    SigenergyCloudRateLimitError,
+)
+
+_SUCCESS_CODES = {0, "0", None}
+_AUTH_CODES = {401, 403, "401", "403"}
+
+
+def _error_message(payload: Any, fallback: str) -> str:
+    if not isinstance(payload, dict):
+        return fallback
+    return (
+        payload.get("msg")
+        or payload.get("message")
+        or payload.get("error_description")
+        or payload.get("error")
+        or fallback
+    )
+
+
+class CloudTransport:
+    """Authenticated request helper shared by the high-level client."""
+
+    def __init__(self, base_url: str, auth: OAuthSession) -> None:
+        self._base_url = base_url
+        self._auth = auth
+
+    async def envelope(
+        self,
+        session: aiohttp.ClientSession,
+        method: str,
+        path: str,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Execute a request and return Sigenergy's full JSON envelope."""
+        await self._auth.ensure_token(session, self._base_url)
+        url = f"{self._base_url}{path.lstrip('/')}"
+        async with session.request(
+            method, url, headers=self._auth.headers, **kwargs
+        ) as response:
+            return await self._parse_response(response)
+
+    async def data(
+        self,
+        session: aiohttp.ClientSession,
+        method: str,
+        path: str,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute a request and return only the envelope's data member."""
+        return (await self.envelope(session, method, path, **kwargs)).get("data")
+
+    async def _parse_response(
+        self, response: aiohttp.ClientResponse
+    ) -> dict[str, Any]:
+        body = await response.text()
+        try:
+            payload: Any = json.loads(body) if body else {}
+        except json.JSONDecodeError as exc:
+            raise SigenergyCloudAPIError(
+                f"Invalid JSON from Sigenergy Cloud: HTTP {response.status}",
+                status_code=response.status,
+                response_body=body,
+            ) from exc
+
+        if response.status == 401:
+            raise SigenergyCloudAuthError(
+                _error_message(payload, "Sigenergy Cloud authentication failed")
+            )
+        if response.status == 429:
+            raise SigenergyCloudRateLimitError(
+                _error_message(payload, "Sigenergy Cloud rate limit exceeded"),
+                status_code=response.status,
+                response_body=body,
+            )
+        if response.status >= 400:
+            raise SigenergyCloudAPIError(
+                _error_message(payload, f"Sigenergy Cloud HTTP error {response.status}"),
+                status_code=response.status,
+                response_body=body,
+            )
+        if not isinstance(payload, dict):
+            raise SigenergyCloudAPIError(
+                "Unexpected non-object response from Sigenergy Cloud",
+                status_code=response.status,
+                response_body=body,
+            )
+
+        code = payload.get("code")
+        if code in _AUTH_CODES:
+            raise SigenergyCloudAuthError(
+                _error_message(payload, "Sigenergy Cloud authentication failed")
+            )
+        if code == 429 or code == "429":
+            raise SigenergyCloudRateLimitError(
+                _error_message(payload, "Sigenergy Cloud rate limit exceeded"),
+                status_code=response.status,
+                response_body=body,
+            )
+        if code not in _SUCCESS_CODES:
+            raise SigenergyCloudAPIError(
+                _error_message(payload, f"Sigenergy Cloud returned code {code}"),
+                status_code=response.status,
+                response_body=body,
+            )
+        return payload

sigenergy_cloud-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+sigenergy_cloud/__init__.py,sha256=uIVysaVBvwzlhl82-CfiZVB3mX9k4ZSu5u0_7LLtb04,640
+sigenergy_cloud/auth.py,sha256=VsJ8HvHg3FKtJxsQzmhEqf6dlg8PJLQ2M-wJiq8D8IU,4469
+sigenergy_cloud/client.py,sha256=8GKALmNVZi0XOtGuS8mEf7ovnYAvaew0de8SUpXCybY,18676
+sigenergy_cloud/errors.py,sha256=lh2ZPshh7P71wJT4QysXQ70ObMzSgL3x20oSej0YRwE,946
+sigenergy_cloud/models.py,sha256=MQrGYPeJL6-YiGyHB9w2sv-22LVnyY0Q5KIZwyw-0rM,3532
+sigenergy_cloud/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+sigenergy_cloud/regions.py,sha256=I7Jtjnf-oXqNVKapEeiPNo_Xbmkx1j5Tqrt67AGoxCY,648
+sigenergy_cloud/transport.py,sha256=LBnfnpnPQk61XmtfhGgv-Ib3ydso0JoiWX5UzIDENdo,3911
+sigenergy_cloud-0.1.0.dist-info/licenses/LICENSE,sha256=h6vpNk7UhOBKQmEM4xts7MMjppHIw79j4q155TgjH1k,1085
+sigenergy_cloud-0.1.0.dist-info/METADATA,sha256=M1jw2MvUhQElCscS5OjpDcjcZZi2tBfrunsIUT-dTtc,2653
+sigenergy_cloud-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sigenergy_cloud-0.1.0.dist-info/top_level.txt,sha256=aMNR-XxB6GEq6XR66jQDKGf36bDbQB92UfCj4D7uBQ4,16
+sigenergy_cloud-0.1.0.dist-info/RECORD,,

sigenergy_cloud-0.1.0.dist-info/WHEEL

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

sigenergy_cloud-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+sigenergy_cloud