hyxi-cloud-api 1.2.6__tar.gz → 1.2.7__tar.gz

{hyxi_cloud_api-1.2.6/src/hyxi_cloud_api.egg-info → hyxi_cloud_api-1.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyxi-cloud-api
-Version: 1.2.6
+Version: 1.2.7
 Summary: An async API client for HYXi Cloud.
 Author-email: Veldkornet <Veldkornet@users.noreply.github.com>
 Classifier: Programming Language :: Python :: 3
@@ -81,6 +81,15 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+HYXI Open API base URLs vary by region. The examples in this README use the
+Europe endpoint by default.
+
+| Node | Request Address |
+| :--- | :--- |
+| China | `https://open-cn.hyxicloud.com` |
+| Europe (default) | `https://open.hyxicloud.com` |
+| North America | `https://open-or.hyxicloud.com` |
+
 ## 🔧 Device Control
 
 You can control inverter operating modes directly through the API. This requires a device serial number, which you can obtain from the device data response above.
@@ -109,6 +118,39 @@ except client.ControlError as e:
     print(f"Control command failed: {e}")
 ```
 
+## 🔔 Subscriptions
+
+You can subscribe a callback URL to HYXI push notifications for real-time data,
+alarms, and FCAS/frequency-modulation real-time data.
+
+```python
+async def subscription_example(client):
+    callback_url = "https://your-public-callback-host/hyxi/callback"
+    device_sns = ["60700000000001", "60700000000002"]
+
+    real_time = await client.subscribe_real_time_data(
+        callback_url,
+        device_sns,
+        post_rate=60000,  # milliseconds, 5000-3600000
+    )
+
+    alarm = await client.subscribe_alarm(
+        callback_url,
+        device_sns,
+        post_rate=60000,  # milliseconds, 5000-3600000
+    )
+
+    fcas = await client.subscribe_fm_real_time_data(
+        callback_url,
+        device_sns,
+        post_rate=1,  # hours, 1-6
+    )
+
+    await client.cancel_subscription(real_time["data"]["subscribeCode"])
+```
+
+Subscription failures raise `HyxiApiClient.SubscriptionError`.
+
 ## 🛠️ Requirements
 * Python 3.14 or newer
 * `aiohttp` >= 3.13.3

{hyxi_cloud_api-1.2.6 → hyxi_cloud_api-1.2.7}/README.md

@@ -57,6 +57,15 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+HYXI Open API base URLs vary by region. The examples in this README use the
+Europe endpoint by default.
+
+| Node | Request Address |
+| :--- | :--- |
+| China | `https://open-cn.hyxicloud.com` |
+| Europe (default) | `https://open.hyxicloud.com` |
+| North America | `https://open-or.hyxicloud.com` |
+
 ## 🔧 Device Control
 
 You can control inverter operating modes directly through the API. This requires a device serial number, which you can obtain from the device data response above.
@@ -85,6 +94,39 @@ except client.ControlError as e:
     print(f"Control command failed: {e}")
 ```
 
+## 🔔 Subscriptions
+
+You can subscribe a callback URL to HYXI push notifications for real-time data,
+alarms, and FCAS/frequency-modulation real-time data.
+
+```python
+async def subscription_example(client):
+    callback_url = "https://your-public-callback-host/hyxi/callback"
+    device_sns = ["60700000000001", "60700000000002"]
+
+    real_time = await client.subscribe_real_time_data(
+        callback_url,
+        device_sns,
+        post_rate=60000,  # milliseconds, 5000-3600000
+    )
+
+    alarm = await client.subscribe_alarm(
+        callback_url,
+        device_sns,
+        post_rate=60000,  # milliseconds, 5000-3600000
+    )
+
+    fcas = await client.subscribe_fm_real_time_data(
+        callback_url,
+        device_sns,
+        post_rate=1,  # hours, 1-6
+    )
+
+    await client.cancel_subscription(real_time["data"]["subscribeCode"])
+```
+
+Subscription failures raise `HyxiApiClient.SubscriptionError`.
+
 ## 🛠️ Requirements
 * Python 3.14 or newer
 * `aiohttp` >= 3.13.3

{hyxi_cloud_api-1.2.6 → hyxi_cloud_api-1.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hyxi-cloud-api"
-version = "1.2.6"
+version = "1.2.7"
 authors = [
   { name="Veldkornet", email="Veldkornet@users.noreply.github.com" },
 ]

{hyxi_cloud_api-1.2.6 → hyxi_cloud_api-1.2.7}/src/hyxi_cloud_api/__init__.py

@@ -5,5 +5,5 @@ from .api import HyxiApiClient
 # Module-level alias so callers can do: from hyxi_cloud_api import VPP_ACTIVE_MODES
 VPP_ACTIVE_MODES: frozenset[str] = HyxiApiClient.VPP_ACTIVE_MODES
 
-__version__ = "1.2.6"
+__version__ = "1.2.7"
 __all__ = ["VPP_ACTIVE_MODES", "HyxiApiClient"]

{hyxi_cloud_api-1.2.6 → hyxi_cloud_api-1.2.7}/src/hyxi_cloud_api/api.py

@@ -19,6 +19,7 @@ import time
 from collections import defaultdict
 from dataclasses import dataclass, field
 from typing import Any
+from urllib.parse import urlparse
 
 try:
     from datetime import UTC, datetime
@@ -776,6 +777,9 @@ class HyxiApiClient:  # pylint: disable=too-many-instance-attributes
     class ControlError(Exception):
         """Raised when a device control command fails."""
 
+    class SubscriptionError(Exception):
+        """Raised when a subscription request fails."""
+
     def __init__(
         self, access_key, secret_key, base_url, session: aiohttp.ClientSession
     ):
@@ -931,6 +935,14 @@ class HyxiApiClient:  # pylint: disable=too-many-instance-attributes
             _LOGGER.error("HYXI Token Request Failed: %s", e)
         return False
 
+    async def _ensure_authenticated(self, error_cls: type[Exception]) -> None:
+        """Refresh the API token or raise the provided domain error."""
+        token_status = await self._refresh_token()
+        if token_status == "auth_failed":
+            raise error_cls("Authentication failed")
+        if not token_status:
+            raise error_cls("Could not obtain API token")
+
     async def _fetch_device_metrics(self, sn, entry):
         """Helper to fetch detailed metrics for a single device."""
         q_path = "/api/device/v1/queryDeviceData"
@@ -1614,11 +1626,7 @@ class HyxiApiClient:  # pylint: disable=too-many-instance-attributes
         Values are strings per the developer docs ('' for idle/self-consumption,
         a wattage like '100' for 1063/1064, '0'/'1' for switches).
         """
-        token_status = await self._refresh_token()
-        if token_status == "auth_failed":
-            raise self.ControlError("Authentication failed")
-        if not token_status:
-            raise self.ControlError("Could not obtain API token")
+        await self._ensure_authenticated(self.ControlError)
 
         path = "/api/device/v2/control"
         body = {
@@ -1641,6 +1649,133 @@ class HyxiApiClient:  # pylint: disable=too-many-instance-attributes
         )
         return res
 
+    # ── Subscription API ────────────────────────────────────────────────
+
+    async def _post_subscription(self, path: str, body: dict) -> dict:
+        """Send an authenticated subscription request."""
+        await self._ensure_authenticated(self.SubscriptionError)
+
+        _LOGGER.debug("HYXI subscription request to %s", path)
+        _, res = await self._request("POST", path, json=body)
+        if res is None or not res.get("success"):
+            code = res.get("code", "unknown") if res else "no_response"
+            msg = res.get("msg", "") if res else ""
+            raise self.SubscriptionError(
+                f"subscription request failed (code={code}): {msg}"
+            )
+        return res
+
+    @staticmethod
+    def _validate_subscription_device_sns(device_sn_list: list[str]) -> None:
+        """Validate subscription device SN list constraints."""
+        if not device_sn_list:
+            raise ValueError("device_sn_list must contain at least one device SN")
+        if len(device_sn_list) > 1000:
+            raise ValueError("device_sn_list cannot contain more than 1000 device SNs")
+
+    @staticmethod
+    def _validate_callback_url(callback_url: str) -> None:
+        """Validate the subscriber callback URL."""
+        if not callback_url or not callback_url.strip():
+            raise ValueError("callback_url must be a non-empty string")
+        parsed = urlparse(callback_url.strip())
+        if parsed.scheme not in ("http", "https") or not parsed.netloc:
+            raise ValueError("callback_url must be a valid http/https URL")
+
+    @staticmethod
+    def _validate_post_rate_ms(post_rate: int) -> None:
+        """Validate millisecond subscription push rate."""
+        if not 5000 <= post_rate <= 3600000:
+            raise ValueError("post_rate must be between 5000 and 3600000 milliseconds")
+
+    async def subscribe_real_time_data(
+        self,
+        callback_url: str,
+        device_sn_list: list[str],
+        post_rate: int,
+        data_code_list: list[str] | None = None,
+    ) -> dict:
+        """Subscribe to real-time device data notifications.
+
+        Endpoint: POST /api/subscribe/v1/realTimeData
+        """
+        self._validate_callback_url(callback_url)
+        self._validate_subscription_device_sns(device_sn_list)
+        self._validate_post_rate_ms(post_rate)
+
+        body: dict[str, Any] = {
+            "callBackUrl": callback_url,
+            "deviceSnList": device_sn_list,
+            "postRate": int(post_rate),
+        }
+        if data_code_list is not None:
+            body["dataCodeList"] = data_code_list
+
+        return await self._post_subscription("/api/subscribe/v1/realTimeData", body)
+
+    async def subscribe_alarm(
+        self,
+        callback_url: str,
+        device_sn_list: list[str],
+        post_rate: int,
+        alarm_code_list: list[str] | None = None,
+    ) -> dict:
+        """Subscribe to device alarm notifications.
+
+        Endpoint: POST /api/subscribe/v1/alarm
+        """
+        self._validate_callback_url(callback_url)
+        self._validate_subscription_device_sns(device_sn_list)
+        self._validate_post_rate_ms(post_rate)
+
+        body: dict[str, Any] = {
+            "callBackUrl": callback_url,
+            "deviceSnList": device_sn_list,
+            "postRate": int(post_rate),
+        }
+        if alarm_code_list is not None:
+            body["alarmCodeList"] = alarm_code_list
+
+        return await self._post_subscription("/api/subscribe/v1/alarm", body)
+
+    async def subscribe_fm_real_time_data(
+        self,
+        callback_url: str,
+        device_sn_list: list[str],
+        post_rate: int,
+    ) -> dict:
+        """Subscribe to FCAS/frequency modulation real-time device data.
+
+        Endpoint: POST /api/subscribe/v1/FMRealTimeData
+
+        Args:
+            post_rate: Push rate in hours. Must be between 1 and 6.
+        """
+        self._validate_callback_url(callback_url)
+        self._validate_subscription_device_sns(device_sn_list)
+        if not 1 <= post_rate <= 6:
+            raise ValueError("post_rate must be between 1 and 6 hours")
+
+        body = {
+            "callBackUrl": callback_url,
+            "deviceSnList": device_sn_list,
+            "postRate": int(post_rate),
+        }
+        return await self._post_subscription("/api/subscribe/v1/FMRealTimeData", body)
+
+    async def cancel_subscription(self, subscribe_code: str) -> dict:
+        """Cancel a subscription by subscription code.
+
+        Endpoint: POST /api/subscribe/v1/cancel
+        """
+        if not subscribe_code or not subscribe_code.strip():
+            raise ValueError("subscribe_code must be a non-empty string")
+
+        return await self._post_subscription(
+            "/api/subscribe/v1/cancel",
+            {"subscribeCode": subscribe_code.strip()},
+        )
+
     async def set_mode_idle(self, device_sn: str) -> dict:
         """Set inverter to Idle mode (controlId 1062).
 
@@ -1779,3 +1914,8 @@ class HyxiApiClient:  # pylint: disable=too-many-instance-attributes
             res.get("success"),
         )
         return res
+
+    @staticmethod
+    def compute_derived_metrics(m_raw: dict, device_type: str = "") -> dict:
+        """Calculate derived metrics (grid import/export, bat charging/discharging, etc.) from raw metrics."""
+        return _compute_derived_metrics(m_raw, device_type)

{hyxi_cloud_api-1.2.6 → hyxi_cloud_api-1.2.7/src/hyxi_cloud_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyxi-cloud-api
-Version: 1.2.6
+Version: 1.2.7
 Summary: An async API client for HYXi Cloud.
 Author-email: Veldkornet <Veldkornet@users.noreply.github.com>
 Classifier: Programming Language :: Python :: 3
@@ -81,6 +81,15 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+HYXI Open API base URLs vary by region. The examples in this README use the
+Europe endpoint by default.
+
+| Node | Request Address |
+| :--- | :--- |
+| China | `https://open-cn.hyxicloud.com` |
+| Europe (default) | `https://open.hyxicloud.com` |
+| North America | `https://open-or.hyxicloud.com` |
+
 ## 🔧 Device Control
 
 You can control inverter operating modes directly through the API. This requires a device serial number, which you can obtain from the device data response above.
@@ -109,6 +118,39 @@ except client.ControlError as e:
     print(f"Control command failed: {e}")
 ```
 
+## 🔔 Subscriptions
+
+You can subscribe a callback URL to HYXI push notifications for real-time data,
+alarms, and FCAS/frequency-modulation real-time data.
+
+```python
+async def subscription_example(client):
+    callback_url = "https://your-public-callback-host/hyxi/callback"
+    device_sns = ["60700000000001", "60700000000002"]
+
+    real_time = await client.subscribe_real_time_data(
+        callback_url,
+        device_sns,
+        post_rate=60000,  # milliseconds, 5000-3600000
+    )
+
+    alarm = await client.subscribe_alarm(
+        callback_url,
+        device_sns,
+        post_rate=60000,  # milliseconds, 5000-3600000
+    )
+
+    fcas = await client.subscribe_fm_real_time_data(
+        callback_url,
+        device_sns,
+        post_rate=1,  # hours, 1-6
+    )
+
+    await client.cancel_subscription(real_time["data"]["subscribeCode"])
+```
+
+Subscription failures raise `HyxiApiClient.SubscriptionError`.
+
 ## 🛠️ Requirements
 * Python 3.14 or newer
 * `aiohttp` >= 3.13.3

{hyxi_cloud_api-1.2.6 → hyxi_cloud_api-1.2.7}/src/hyxi_cloud_api.egg-info/SOURCES.txt

@@ -42,5 +42,6 @@ tests/test_process_devices_for_plant.py
 tests/test_sanitize_dict.py
 tests/test_sanitize_list.py
 tests/test_security_fix.py
+tests/test_subscriptions.py
 tests/test_token_errors.py
 tests/test_token_handling.py

hyxi_cloud_api-1.2.7/tests/test_subscriptions.py

@@ -0,0 +1,163 @@
+"""Tests for the HYXI subscription API methods."""
+
+import sys
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+if "aiohttp" not in sys.modules or not hasattr(sys.modules["aiohttp"], "ClientError"):
+    m = MagicMock()
+    m.ClientError = Exception
+    m.ClientResponseError = type("ClientResponseError", (Exception,), {})
+    m.ContentTypeError = type("ContentTypeError", (Exception,), {})
+    sys.modules["aiohttp"] = m
+
+from src.hyxi_cloud_api.api import HyxiApiClient
+
+
+def _client() -> HyxiApiClient:
+    api = HyxiApiClient("ak", "sk", "https://api.com", MagicMock())
+    api._refresh_token = AsyncMock(return_value=True)
+    api._request = AsyncMock(
+        return_value=(
+            200,
+            {
+                "code": "0",
+                "msg": "Success",
+                "data": {"subscribeCode": "sub-code"},
+                "success": True,
+            },
+        )
+    )
+    return api
+
+
+@pytest.mark.asyncio
+async def test_subscribe_real_time_data():
+    """Test real-time data subscription payload."""
+    api = _client()
+
+    result = await api.subscribe_real_time_data(
+        "https://example.com/hyxi",
+        ["SN1", "SN2"],
+        60000,
+        data_code_list=["pv1p"],
+    )
+
+    assert result["data"]["subscribeCode"] == "sub-code"
+    api._request.assert_called_once()
+    call_args = api._request.call_args
+    assert call_args.args[:2] == ("POST", "/api/subscribe/v1/realTimeData")
+    body = call_args.kwargs["json"]
+    assert body == {
+        "callBackUrl": "https://example.com/hyxi",
+        "deviceSnList": ["SN1", "SN2"],
+        "postRate": 60000,
+        "dataCodeList": ["pv1p"],
+    }
+
+
+@pytest.mark.asyncio
+async def test_subscribe_alarm():
+    """Test alarm subscription payload."""
+    api = _client()
+
+    await api.subscribe_alarm(
+        "https://example.com/hyxi",
+        ["SN1"],
+        5000,
+        alarm_code_list=["704"],
+    )
+
+    call_args = api._request.call_args
+    assert call_args.args[:2] == ("POST", "/api/subscribe/v1/alarm")
+    body = call_args.kwargs["json"]
+    assert body == {
+        "callBackUrl": "https://example.com/hyxi",
+        "deviceSnList": ["SN1"],
+        "postRate": 5000,
+        "alarmCodeList": ["704"],
+    }
+
+
+@pytest.mark.asyncio
+async def test_subscribe_fm_real_time_data():
+    """Test FCAS real-time data subscription payload."""
+    api = _client()
+
+    await api.subscribe_fm_real_time_data("https://example.com/hyxi", ["SN1"], 1)
+
+    call_args = api._request.call_args
+    assert call_args.args[:2] == ("POST", "/api/subscribe/v1/FMRealTimeData")
+    body = call_args.kwargs["json"]
+    assert body == {
+        "callBackUrl": "https://example.com/hyxi",
+        "deviceSnList": ["SN1"],
+        "postRate": 1,
+    }
+
+
+@pytest.mark.asyncio
+async def test_cancel_subscription():
+    """Test subscription cancellation payload."""
+    api = _client()
+
+    await api.cancel_subscription(" sub-code ")
+
+    call_args = api._request.call_args
+    assert call_args.args[:2] == ("POST", "/api/subscribe/v1/cancel")
+    assert call_args.kwargs["json"] == {"subscribeCode": "sub-code"}
+
+
+@pytest.mark.asyncio
+async def test_subscription_error_on_auth_failed():
+    """Test SubscriptionError is raised when authentication fails."""
+    api = HyxiApiClient("ak", "sk", "https://api.com", MagicMock())
+    api._refresh_token = AsyncMock(return_value="auth_failed")
+
+    with pytest.raises(api.SubscriptionError, match="Authentication failed"):
+        await api.subscribe_alarm("https://example.com/hyxi", ["SN1"], 60000)
+
+
+@pytest.mark.asyncio
+async def test_subscription_error_on_api_failure():
+    """Test SubscriptionError is raised when API returns success=False."""
+    api = HyxiApiClient("ak", "sk", "https://api.com", MagicMock())
+    api._refresh_token = AsyncMock(return_value=True)
+    api._request = AsyncMock(
+        return_value=(
+            200,
+            {"success": False, "code": "C000001", "msg": "Parameter error"},
+        )
+    )
+
+    with pytest.raises(api.SubscriptionError, match="subscription request failed"):
+        await api.subscribe_real_time_data("https://example.com/hyxi", ["SN1"], 60000)
+
+
+@pytest.mark.asyncio
+async def test_subscription_validation():
+    """Test subscription input validation."""
+    api = _client()
+
+    with pytest.raises(ValueError, match="callback_url must be a non-empty string"):
+        await api.subscribe_alarm("", ["SN1"], 60000)
+
+    with pytest.raises(ValueError, match="at least one device SN"):
+        await api.subscribe_alarm("https://example.com/hyxi", [], 60000)
+
+    with pytest.raises(ValueError, match="more than 1000"):
+        await api.subscribe_alarm(
+            "https://example.com/hyxi",
+            [f"SN{i}" for i in range(1001)],
+            60000,
+        )
+
+    with pytest.raises(ValueError, match="between 5000 and 3600000 milliseconds"):
+        await api.subscribe_real_time_data("https://example.com/hyxi", ["SN1"], 4999)
+
+    with pytest.raises(ValueError, match="between 1 and 6 hours"):
+        await api.subscribe_fm_real_time_data("https://example.com/hyxi", ["SN1"], 7)
+
+    with pytest.raises(ValueError, match="subscribe_code must be a non-empty string"):
+        await api.cancel_subscription(" ")