pybluetti 0.1.0__tar.gz

pybluetti-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions: {}
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
+        with:
+          python-version: "3.13"
+
+      - name: Install the build tool
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload the built distribution
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI (trusted publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for PyPI trusted publishing (OIDC) - no API token stored anywhere
+    steps:
+      - name: Download the built distribution
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

pybluetti-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,55 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions: {}
+
+jobs:
+  pytest:
+    name: Run test suite
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: scripts/setup
+
+      - name: Run pytest with coverage
+        run: scripts/test
+
+  lint:
+    name: Run ruff
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
+        with:
+          python-version: "3.13"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Run ruff
+        run: ruff check .

pybluetti-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.ruff_cache/
+.venv/
+venv/
+.mypy_cache/

pybluetti-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Unreleased
+
+- Replaced `StompClient`'s blocking `websocket-client` transport (a dedicated daemon thread plus a second dedicated heartbeat thread) with `aiohttp`'s native async websocket client (`ClientSession.ws_connect`). `connect()`/`disconnect()`/`reconnect()` are now coroutines; the receive loop and heartbeat run as `asyncio.Task`s instead of threads. `StompListener` is folded into `StompClient` (no more callback registration to justify a separate object). STOMP protocol framing (`stomper`) and all frame-handling logic/log messages are unchanged. `websocket-client` dropped from dependencies.
+- Migrated the BLUETTI cloud API client from `bluetti-home-assistant`'s `custom_components/bluetti/api/` (plus `model/product.py` and `application_exception.py`): `Bluetti`/`ProductClient` (HTTP), `StompClient`/`StompListener` (websocket push updates), `UserProduct`, `UnifyResponse`, `ApplicationRuntimeException`. Decoupled from Home Assistant - server URLs and an `on_auth_expired` callback are now plain constructor arguments instead of a `hass` object. The websocket transport itself (`websocket-client` on a dedicated thread) is unchanged in this step.
+- Initial repository scaffold: packaging (`pyproject.toml`, `hatchling`), test/lint scripts, CI, MIT license.

pybluetti-0.1.0/LICENSE

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

pybluetti-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.5
+Name: pybluetti
+Version: 0.1.0
+Summary: Async Python client for the BLUETTI cloud API - device discovery, state, and control.
+Project-URL: Homepage, https://github.com/chpego/pybluetti
+Project-URL: Used by, https://github.com/bluetti-official/bluetti-home-assistant
+Project-URL: Issues, https://github.com/chpego/pybluetti/issues
+Author: chpego
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: pydantic>=2.0
+Requires-Dist: stomper>=0.4
+Provides-Extra: test
+Requires-Dist: aioresponses; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pybluetti
+
+Async Python client for the BLUETTI cloud API - device discovery, state, and control.
+
+## Status: fully async, not yet wired up or published
+
+This repository is the extraction target for the API client code that used to
+live in
+[`bluetti-home-assistant`](https://github.com/bluetti-official/bluetti-home-assistant)'s
+`custom_components/bluetti/api/`, following the same pattern
+[`pyenphase`](https://github.com/pyenphase/pyenphase) uses for the `enphase_envoy`
+Home Assistant integration: a standalone, independently testable and
+versionable library, decoupled from Home Assistant's own release cycle.
+
+The extraction is happening in three steps:
+
+1. **Done.** Move the client code here mechanically, decoupled from `hass`
+   (server URLs and an `on_auth_expired` callback are passed in as plain
+   constructor arguments instead - see `src/pybluetti/`).
+2. **Done.** Replace the blocking `websocket-client` transport (previously
+   run on a dedicated thread to keep it out of Home Assistant's event loop)
+   with `aiohttp`'s native async websocket client - `src/pybluetti/websocket.py`
+   has no threads left. STOMP protocol framing (`stomper`) is unchanged.
+3. *Not started.* Publish to PyPI, and switch `bluetti-home-assistant`'s
+   `manifest.json`/imports to depend on this package instead of its own
+   in-tree copy.
+
+## Why extract it
+
+- **Independent testing and versioning**, not tied to Home Assistant's release cadence.
+- **A step toward Home Assistant core inclusion** - core integrations are expected to depend on
+  an external library for the actual device/API communication, not embed raw HTTP/websocket
+  calls directly in the integration.
+- **Fixed a known gap along the way**: the embedded client used to run the blocking
+  `websocket-client` library on a dedicated thread to keep it out of Home Assistant's event
+  loop. `pybluetti` is fully async instead, matching `bluetti-home-assistant`'s own
+  `quality_scale.yaml` `async-dependency` goal once step 3 wires it up.
+
+## Development
+
+```bash
+scripts/setup   # install runtime + test dependencies
+scripts/test    # run the test suite (100% line coverage enforced)
+scripts/lint    # run ruff, auto-fixing what it safely can
+```
+
+## License
+
+MIT - see [LICENSE](LICENSE).

pybluetti-0.1.0/README.md

@@ -0,0 +1,49 @@
+# pybluetti
+
+Async Python client for the BLUETTI cloud API - device discovery, state, and control.
+
+## Status: fully async, not yet wired up or published
+
+This repository is the extraction target for the API client code that used to
+live in
+[`bluetti-home-assistant`](https://github.com/bluetti-official/bluetti-home-assistant)'s
+`custom_components/bluetti/api/`, following the same pattern
+[`pyenphase`](https://github.com/pyenphase/pyenphase) uses for the `enphase_envoy`
+Home Assistant integration: a standalone, independently testable and
+versionable library, decoupled from Home Assistant's own release cycle.
+
+The extraction is happening in three steps:
+
+1. **Done.** Move the client code here mechanically, decoupled from `hass`
+   (server URLs and an `on_auth_expired` callback are passed in as plain
+   constructor arguments instead - see `src/pybluetti/`).
+2. **Done.** Replace the blocking `websocket-client` transport (previously
+   run on a dedicated thread to keep it out of Home Assistant's event loop)
+   with `aiohttp`'s native async websocket client - `src/pybluetti/websocket.py`
+   has no threads left. STOMP protocol framing (`stomper`) is unchanged.
+3. *Not started.* Publish to PyPI, and switch `bluetti-home-assistant`'s
+   `manifest.json`/imports to depend on this package instead of its own
+   in-tree copy.
+
+## Why extract it
+
+- **Independent testing and versioning**, not tied to Home Assistant's release cadence.
+- **A step toward Home Assistant core inclusion** - core integrations are expected to depend on
+  an external library for the actual device/API communication, not embed raw HTTP/websocket
+  calls directly in the integration.
+- **Fixed a known gap along the way**: the embedded client used to run the blocking
+  `websocket-client` library on a dedicated thread to keep it out of Home Assistant's event
+  loop. `pybluetti` is fully async instead, matching `bluetti-home-assistant`'s own
+  `quality_scale.yaml` `async-dependency` goal once step 3 wires it up.
+
+## Development
+
+```bash
+scripts/setup   # install runtime + test dependencies
+scripts/test    # run the test suite (100% line coverage enforced)
+scripts/lint    # run ruff, auto-fixing what it safely can
+```
+
+## License
+
+MIT - see [LICENSE](LICENSE).

pybluetti-0.1.0/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pybluetti"
+version = "0.1.0"
+description = "Async Python client for the BLUETTI cloud API - device discovery, state, and control."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{ name = "chpego" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+]
+dependencies = [
+    "aiohttp>=3.9",
+    "pydantic>=2.0",
+    "stomper>=0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/chpego/pybluetti"
+"Used by" = "https://github.com/bluetti-official/bluetti-home-assistant"
+Issues = "https://github.com/chpego/pybluetti/issues"
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "aioresponses",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pybluetti"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # Formatter-incompatible / removed rules.
+    "D203", # no-blank-line-before-class
+    "D212", # multi-line-summary-first-line
+    "COM812", # incompatible with formatter
+    "ISC001", # incompatible with formatter
+
+    "D1", # undocumented-* - matches "no comment unless the why is non-obvious"
+    "CPY001", # missing-copyright-notice - a top-level LICENSE file covers this
+
+    # Deliberately NOT bootstrapped away like bluetti-home-assistant's ANN
+    # ignores: that codebase predates strict typing and ratchets up over
+    # time, but this one starts from zero, and reaching HA core eventually
+    # needs "strict-typing: done" - so annotations are required on src/ from
+    # the first commit instead of being deferred (see per-file-ignores below
+    # for why tests/ is exempt).
+
+    # The following are carried over verbatim from bluetti-home-assistant's
+    # own ruff.toml, for the exact same reason it lists there: client.py,
+    # product_client.py, and websocket.py are a mechanical port of that
+    # repo's api/ package (see pybluetti's README), so they inherit its
+    # patterns rather than introducing new laxness here.
+    "E501", # line-too-long
+    "N803", "N815", # non-lowercase naming - mirrors the cloud API's own field/param casing
+    "N818", # error-suffix-on-exception-name
+    "BLE001", # blind-except
+    "PLR2004", # magic-value-comparison
+    "ANN401", # Any is inherent to _request()'s generic response-type parameter
+    "ARG002", "ARG004", # unused arguments - expected for async context-manager/callback protocol signatures
+    "UP042", "UP046", # typing modernization (PEP 695 generics, StrEnum) not worth the diff in a direct port
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101", # assert is the normal pytest idiom, not a smell, here.
+    "SLF001", # the ported websocket tests deliberately reach into name-mangled
+              # privates (_StompClient__on_open etc.), by design - see
+              # bluetti-home-assistant's own identical ignore.
+    "ANN001", "ANN002", "ANN003", "ANN201", "ANN202", "ANN204", # test functions and
+              # fixture/mock helpers aren't part of the library's public surface,
+              # so the "annotations required" rule above doesn't apply to them.
+]

pybluetti-0.1.0/scripts/lint

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -e
+
+cd "$(dirname "$0")/.."
+
+ruff check . --fix

pybluetti-0.1.0/scripts/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -e
+
+cd "$(dirname "$0")/.."
+
+python3 -m pip install --upgrade pip
+python3 -m pip install --editable ".[test]"
+python3 -m pip install ruff

pybluetti-0.1.0/scripts/test

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -e
+
+cd "$(dirname "$0")/.."
+
+python3 -m pytest tests/ -q --cov=pybluetti --cov-report=term-missing --cov-fail-under=100

pybluetti-0.1.0/src/pybluetti/__init__.py

@@ -0,0 +1,31 @@
+"""
+Async Python client for the BLUETTI cloud API.
+
+Extracted from
+https://github.com/bluetti-official/bluetti-home-assistant's
+custom_components/bluetti/api/, the same way
+https://github.com/pyenphase/pyenphase backs the enphase_envoy Home Assistant
+integration. Fully async, including the websocket push-update transport
+(`aiohttp`'s native websocket client, no dedicated threads). Wiring
+bluetti-home-assistant to depend on this package is a separate follow-up.
+"""
+
+from .client import Bluetti
+from .const import Method
+from .exceptions import ApplicationRuntimeException
+from .models import UserProduct
+from .product_client import ProductClient
+from .unify_response import UnifyResponse
+from .websocket import StompClient
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ApplicationRuntimeException",
+    "Bluetti",
+    "Method",
+    "ProductClient",
+    "StompClient",
+    "UnifyResponse",
+    "UserProduct",
+]

pybluetti-0.1.0/src/pybluetti/client.py

@@ -0,0 +1,105 @@
+"""Base BLUETTI cloud API client."""
+
+import logging
+from abc import abstractmethod
+from collections.abc import Callable
+from json import dumps
+from typing import Any, Generic, TypeVar
+
+import aiohttp
+from pydantic import TypeAdapter
+
+from .const import Method
+from .exceptions import ApplicationRuntimeException
+from .unify_response import UnifyResponse
+
+T = TypeVar("T")
+
+
+class Bluetti(Generic[T]):
+    """Base class describing interactions with the BLUETTI cloud service."""
+
+    _accessToken: str | None = None
+    _httpSession: aiohttp.ClientSession
+    _gateway_url: str
+    _on_auth_expired: Callable[[], None] | None
+
+    @property
+    @abstractmethod
+    def logger(self) -> logging.Logger:
+        """The subclass's logger."""
+
+    def __init__(
+        self,
+        httpSession: aiohttp.ClientSession,
+        gateway_url: str,
+        accessToken: str | None = None,
+        on_auth_expired: Callable[[], None] | None = None,
+    ) -> None:
+        """
+        Initialize the client.
+
+        - httpSession: the aiohttp session to issue requests on.
+        - gateway_url: the BLUETTI cloud gateway base URL (region-specific).
+        - accessToken: the OAuth2 access token to authenticate requests with.
+        - on_auth_expired: called when the cloud reports the access token as
+          expired (msgCode 805), so the caller can react (e.g. trigger a
+          refresh or re-authentication flow).
+        """
+        self._httpSession = httpSession
+        self._gateway_url = gateway_url
+        self._accessToken = accessToken
+        self._on_auth_expired = on_auth_expired
+
+    async def _request(
+        self,
+        responseType: Any,
+        method: Method,
+        path: str,
+        params: dict[str, Any] | None = None,
+        body: dict[str, Any] | None = None,
+    ) -> UnifyResponse[T] | str:
+        """
+        Send a request to the server.
+
+        - responseType: the type of response data, without the UnifyResponse wrapper.
+        - method: the HTTP method.
+        """
+        # when the method is 'GET', the request body must be null.
+        if method == Method.GET:
+            body = None
+
+        headers = {
+            "Authorization": f"{self._accessToken}",
+        }
+
+        # Remove None values from params and json
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+            self.logger.debug("======> Client request parameters: %s", params)
+        if body:
+            body = {k: v for k, v in body.items() if v is not None}
+            self.logger.debug("======> Client request body: %s", dumps(body))
+            headers["Content-Type"] = "application/json"
+
+        async with self._httpSession.request(
+            method,
+            f"{self._gateway_url}{path}",
+            headers=headers,
+            json=body,
+            params=params,
+        ) as response:
+            self.logger.debug("<====== Server response status %s from %s", response.status, response.url)
+            self.logger.debug("<====== Server response type is: %s", response.content_type)
+
+            if not response.ok:
+                raise ApplicationRuntimeException(msgCode=response.status, data=await response.text())
+
+            if response.content_type.lower().startswith("application/json"):
+                data = await response.json()  # read response body to JSON
+                unify_response = TypeAdapter(UnifyResponse[responseType]).validate_python(data)
+                if data.get("msgCode") == 805 and self._on_auth_expired is not None:
+                    self._on_auth_expired()
+                    self.logger.info("token have expired")
+                return unify_response
+            return await response.text()

pybluetti-0.1.0/src/pybluetti/const.py

@@ -0,0 +1,18 @@
+"""Shared constants for pybluetti."""
+
+from enum import Enum
+
+
+class StringEnum(str, Enum):
+    """String Enum define."""
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class Method(StringEnum):
+    """HTTP Methods define."""
+
+    GET = "GET"
+    POST = "POST"
+    DELETE = "DELETE"

pybluetti-0.1.0/src/pybluetti/exceptions.py

@@ -0,0 +1,18 @@
+"""Exceptions raised by the pybluetti client."""
+
+
+class ApplicationRuntimeException(Exception):
+    """Raised when a BLUETTI cloud API call fails."""
+
+    message: str = "An unknown error has occurred."
+    msgCode: int
+    data: dict | str | None = None
+
+    def __init__(self, msgCode: int, data: dict | str | None = None, errMessage: str | None = None) -> None:
+        self.msgCode = msgCode
+        self.data = data
+
+        if errMessage is not None:
+            self.message = errMessage
+
+        super().__init__(self.message)

pybluetti-0.1.0/src/pybluetti/models.py

@@ -0,0 +1,14 @@
+"""Response models for the BLUETTI cloud API."""
+
+from pydantic import BaseModel
+
+
+class UserProduct(BaseModel):
+    """A device/power station bound to a BLUETTI account."""
+
+    sn: str
+    stateList: list
+    online: str
+    model: str | None = None
+    name: str | None = None
+    isBindByCurUser: str | None = None

pybluetti-0.1.0/src/pybluetti/product_client.py

@@ -0,0 +1,57 @@
+"""Client for the BLUETTI product/device endpoints."""
+
+import logging
+
+from .client import Bluetti
+from .const import Method
+from .models import UserProduct
+from .unify_response import UnifyResponse
+
+
+class ProductClient(Bluetti):
+    """Class describing for the BLUETTI products."""
+
+    __LOGGER__ = None
+    """The api client logger."""
+
+    @property
+    def logger(self) -> logging.Logger:
+        """Get the api client logger."""
+        if self.__LOGGER__ is None:
+            self.__LOGGER__ = logging.getLogger(__name__ + "." + __class__.__name__)
+        return self.__LOGGER__
+
+    async def get_user_products(self) -> UnifyResponse[list[UserProduct]]:
+        """Get the devices/power stations bound to the account."""
+        return await self._request(
+            list[UserProduct],
+            Method.GET,
+            "/api/bluiotdata/ha/v1/devices",
+        )
+
+    async def get_device_status(self, sns: str | None = None) -> UnifyResponse[list[UserProduct]]:
+        """Poll device state."""
+        return await self._request(
+            list[UserProduct],
+            Method.GET,
+            "/api/bluiotdata/ha/v1/deviceStates",
+            params={"sns": sns},
+        )
+
+    async def control_device(self, payload: dict | None = None) -> UnifyResponse[dict] | str:
+        """Send a control command to a device."""
+        return await self._request(
+            dict,
+            method=Method.POST,
+            path="/api/bluiotdata/ha/v1/fulfillment",
+            body=payload,
+        )
+
+    async def bind_devices(self, payload: dict | None = None) -> UnifyResponse[dict] | str:
+        """Bind devices to the account."""
+        return await self._request(
+            dict,
+            method=Method.POST,
+            path="/api/bluiotdata/ha/v1/bindDevices",
+            body=payload,
+        )

pybluetti-0.1.0/src/pybluetti/unify_response.py

@@ -0,0 +1,23 @@
+"""The envelope every BLUETTI cloud API response is wrapped in."""
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+
+class UnifyResponse(BaseModel, Generic[T]):
+    """The Unify Server Response class."""
+
+    msgId: str
+    msgCode: int
+    data: T | None = None
+
+    def is_ok(self) -> bool:
+        """Return true if the server response is success."""
+        return self.msgCode == 0
+
+    def has_data(self) -> bool:
+        """Return true if the server response is success and has response data."""
+        return self.is_ok() and self.data is not None