landbook-api 0.1.0__tar.gz

landbook_api-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,83 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g. 0.1.0), no leading v"
+        required: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[test]"
+      - run: pytest
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+  github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Get version
+        id: version
+        run: |
+          if [ -n "${{ inputs.version }}" ]; then
+            echo "version=${{ inputs.version }}" >> $GITHUB_OUTPUT
+          else
+            echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Extract changelog entry
+        id: changelog
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          NOTES=$(awk "/^## \[$VERSION\]/{found=1; next} found && /^## /{exit} found{print}" CHANGELOG.md | sed '/^[[:space:]]*$/d')
+          {
+            echo "notes<<EOF"
+            echo "## What's Changed"
+            echo ""
+            echo "$NOTES"
+            echo ""
+            echo "**Full changelog:** https://github.com/zackwag/landbook-api/blob/main/CHANGELOG.md"
+            echo "EOF"
+          } >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: "v${{ steps.version.outputs.version }}"
+          name: "v${{ steps.version.outputs.version }}"
+          body: "${{ steps.changelog.outputs.notes }}"
+          make_latest: true

landbook_api-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,20 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[test]"
+      - run: pytest

landbook_api-0.1.0/.gitignore

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

landbook_api-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [0.1.0] - 2026-07-18
+
+- Initial release, extracted from the [landbook-ha](https://github.com/zackwag/landbook-ha) Home Assistant integration (`api.py` and `mqtt_client.py`, previously bundled with the integration code).

landbook_api-0.1.0/LICENSE

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

landbook_api-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: landbook-api
+Version: 0.1.0
+Summary: Unofficial Python client for the Landbook (Netprisma/Landecia) smart home cloud API — REST auth/device discovery and MQTT pub/sub.
+Project-URL: Homepage, https://github.com/zackwag/landbook-api
+Project-URL: Issues, https://github.com/zackwag/landbook-api/issues
+Author: Zack Wagner
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.10
+Requires-Dist: paho-mqtt>=2.0.0
+Requires-Dist: pycryptodome>=3.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# landbook-api
+
+Unofficial Python client for the Landbook smart home cloud API (Netprisma/Landecia), reverse-engineered from the Landbook iOS app. Covers:
+
+- **REST**: email/password login, token refresh, device discovery, TSL (Thing Specification Language) model fetch, device attribute reads.
+- **MQTT**: a persistent WebSocket/TLS pub-sub connection for real-time device control and state (`LandbookMQTTClient`).
+
+This library powers the [landbook-ha](https://github.com/zackwag/landbook-ha) Home Assistant integration, but has no dependency on Home Assistant and can be used standalone.
+
+## Installation
+
+```bash
+pip install landbook-api
+```
+
+## Usage
+
+```python
+from landbook_api import login, get_device_list, get_tsl, LandbookMQTTClient
+
+bearer_token, uid, refresh_token = login("you@example.com", "your-password", region="us")
+
+devices = get_device_list(bearer_token, region="us")
+pk = devices[0]["productKey"]
+dk = devices[0]["deviceKey"]
+
+properties = get_tsl(bearer_token, pk, region="us")
+
+client = LandbookMQTTClient(uid, bearer_token)
+client.connect()
+
+def on_message(topic_suffix: str, payload: dict) -> None:
+    print(topic_suffix, payload)
+
+device_id = f"qd{pk}{dk}"
+client.subscribe_device(device_id, on_message)
+client.send_read(device_id, pk, dk, [p["code"] for p in properties])
+```
+
+Async equivalents (`async_login`, `async_get_device_list`, `async_get_tsl`, `async_refresh_token`, `async_get_device_attributes`) are also exported — each wraps the sync call in a thread executor.
+
+## Supported Regions
+
+| Region | API |
+|--------|-----|
+| United States | `iot-api.quectelus.com` |
+| Europe | `iot-api.quecteleu.com` |
+| China | `iot-gateway.quectel.com` |
+
+Pass `region="us"`, `"eu"`, or `"cn"` to any call (defaults to `"us"`). EU and CN are untested — reports welcome via issues.
+
+## Session Tokens
+
+`login()` returns a `(bearer_token, uid, refresh_token)` tuple. The access token (`bearer_token`) is valid for 2 hours; the refresh token is valid for 30 days and must be used to obtain a new pair via `refresh_token()` before the access token expires. Both values should be persisted by the caller — this library does not manage token storage.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+## Disclaimer
+
+This is an unofficial, reverse-engineered client with no affiliation to Landbook, Netprisma, or Landecia. It may break if the upstream API changes.

landbook_api-0.1.0/README.md

@@ -0,0 +1,65 @@
+# landbook-api
+
+Unofficial Python client for the Landbook smart home cloud API (Netprisma/Landecia), reverse-engineered from the Landbook iOS app. Covers:
+
+- **REST**: email/password login, token refresh, device discovery, TSL (Thing Specification Language) model fetch, device attribute reads.
+- **MQTT**: a persistent WebSocket/TLS pub-sub connection for real-time device control and state (`LandbookMQTTClient`).
+
+This library powers the [landbook-ha](https://github.com/zackwag/landbook-ha) Home Assistant integration, but has no dependency on Home Assistant and can be used standalone.
+
+## Installation
+
+```bash
+pip install landbook-api
+```
+
+## Usage
+
+```python
+from landbook_api import login, get_device_list, get_tsl, LandbookMQTTClient
+
+bearer_token, uid, refresh_token = login("you@example.com", "your-password", region="us")
+
+devices = get_device_list(bearer_token, region="us")
+pk = devices[0]["productKey"]
+dk = devices[0]["deviceKey"]
+
+properties = get_tsl(bearer_token, pk, region="us")
+
+client = LandbookMQTTClient(uid, bearer_token)
+client.connect()
+
+def on_message(topic_suffix: str, payload: dict) -> None:
+    print(topic_suffix, payload)
+
+device_id = f"qd{pk}{dk}"
+client.subscribe_device(device_id, on_message)
+client.send_read(device_id, pk, dk, [p["code"] for p in properties])
+```
+
+Async equivalents (`async_login`, `async_get_device_list`, `async_get_tsl`, `async_refresh_token`, `async_get_device_attributes`) are also exported — each wraps the sync call in a thread executor.
+
+## Supported Regions
+
+| Region | API |
+|--------|-----|
+| United States | `iot-api.quectelus.com` |
+| Europe | `iot-api.quecteleu.com` |
+| China | `iot-gateway.quectel.com` |
+
+Pass `region="us"`, `"eu"`, or `"cn"` to any call (defaults to `"us"`). EU and CN are untested — reports welcome via issues.
+
+## Session Tokens
+
+`login()` returns a `(bearer_token, uid, refresh_token)` tuple. The access token (`bearer_token`) is valid for 2 hours; the refresh token is valid for 30 days and must be used to obtain a new pair via `refresh_token()` before the access token expires. Both values should be persisted by the caller — this library does not manage token storage.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+## Disclaimer
+
+This is an unofficial, reverse-engineered client with no affiliation to Landbook, Netprisma, or Landecia. It may break if the upstream API changes.

landbook_api-0.1.0/landbook_api/__init__.py

@@ -0,0 +1,41 @@
+"""Unofficial Python client for the Landbook (Netprisma/Landecia) cloud API.
+
+Covers REST auth/device discovery/TSL model fetch and the WebSocket/TLS MQTT
+pub/sub channel used for real-time device control and state.
+"""
+from .api import (
+    LandbookAPIError,
+    LandbookAuthError,
+    async_get_device_attributes,
+    async_get_device_list,
+    async_get_tsl,
+    async_login,
+    async_refresh_token,
+    get_device_attributes,
+    get_device_list,
+    get_tsl,
+    login,
+    refresh_token,
+)
+from .const import DEFAULT_REGION, REGIONS
+from .mqtt_client import LandbookMQTTClient
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "LandbookAPIError",
+    "LandbookAuthError",
+    "LandbookMQTTClient",
+    "DEFAULT_REGION",
+    "REGIONS",
+    "login",
+    "async_login",
+    "get_device_list",
+    "async_get_device_list",
+    "get_tsl",
+    "async_get_tsl",
+    "refresh_token",
+    "async_refresh_token",
+    "get_device_attributes",
+    "async_get_device_attributes",
+]

landbook_api-0.1.0/landbook_api/api.py

@@ -0,0 +1,199 @@
+"""Landbook API client — auth, device discovery, TSL model fetch."""
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import json
+import random
+import string
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from Crypto.Cipher import AES
+from Crypto.Util.Padding import pad
+
+from .const import (
+    APP_ID,
+    APP_SYSTEM_TYPE,
+    APP_VERSION,
+    DEFAULT_REGION,
+    REGIONS,
+)
+
+
+class LandbookAuthError(Exception):
+    """Raised when login fails."""
+
+
+class LandbookAPIError(Exception):
+    """Raised when an API call fails."""
+
+
+def _region_cfg(region: str) -> dict:
+    return REGIONS.get(region, REGIONS[DEFAULT_REGION])
+
+
+def _encrypt_password(password: str) -> tuple[str, str]:
+    """Return (pwd_b64, rand) — AES-128-CBC, matches the Landbook app logic."""
+    rand = "".join(random.choices(string.ascii_letters + string.digits, k=16))
+    md5_full = hashlib.md5(rand.encode()).hexdigest().upper()
+    hash_random = md5_full[8:24]
+    iv = hash_random[8:16] + hash_random[0:8]
+
+    cipher = AES.new(hash_random.encode(), AES.MODE_CBC, iv.encode())
+    encrypted = cipher.encrypt(pad(password.encode(), AES.block_size))
+    pwd = base64.b64encode(encrypted).decode()
+    return pwd, rand
+
+
+def _default_headers() -> dict[str, str]:
+    return {
+        "appId": APP_ID,
+        "appVersion": APP_VERSION,
+        "appSystemType": APP_SYSTEM_TYPE,
+        "Accept": "application/json",
+    }
+
+
+def login(email: str, password: str, region: str = DEFAULT_REGION) -> tuple[str, str, str]:
+    """Authenticate and return (bearer_token, uid, refresh_token).
+
+    The access token is only valid for 2 hours; the refresh token (returned
+    alongside it) is what actually renews the session and is valid for 30
+    days. Both must be persisted — see refresh_token() below.
+    """
+    cfg = _region_cfg(region)
+    pwd, rand = _encrypt_password(password)
+
+    sig = hashlib.sha256(
+        (email + pwd + rand + cfg["app_domain_key"]).encode()
+    ).hexdigest()
+
+    data = urllib.parse.urlencode(
+        {
+            "email": email,
+            "pwd": pwd,
+            "random": rand,
+            "userDomain": cfg["user_domain"],
+            "signature": sig,
+        }
+    ).encode()
+
+    login_url = cfg["api_base"] + "/v2/enduser/enduserapi/emailPwdLogin"
+    headers = {**_default_headers(), "Content-Type": "application/x-www-form-urlencoded"}
+    req = urllib.request.Request(login_url, data=data, headers=headers)
+
+    try:
+        resp = json.loads(urllib.request.urlopen(req).read())
+    except Exception as exc:
+        raise LandbookAuthError(f"Login request failed: {exc}") from exc
+
+    if resp.get("code") != 200 or "data" not in resp:
+        raise LandbookAuthError(f"Login failed: {resp.get('msg', 'unknown error')}")
+
+    bearer_token: str = resp["data"]["accessToken"]["token"]
+    refresh_token_value: str = resp["data"]["refreshToken"]["token"]
+    rest_token = bearer_token.replace("Bearer ", "")
+    payload_b64 = rest_token.split(".")[1]
+    uid: str = json.loads(base64.b64decode(payload_b64 + "=="))["uid"]
+
+    return bearer_token, uid, refresh_token_value
+
+
+def _api_get(bearer_token: str, api_base: str, path: str, params: dict | None = None) -> Any:
+    url = api_base + path
+    if params:
+        url += "?" + urllib.parse.urlencode(params)
+    headers = {**_default_headers(), "Authorization": bearer_token}
+    req = urllib.request.Request(url, headers=headers)
+    try:
+        resp = json.loads(urllib.request.urlopen(req).read())
+    except Exception as exc:
+        raise LandbookAPIError(f"API call to {path} failed: {exc}") from exc
+    if resp.get("code") != 200:
+        raise LandbookAPIError(f"API error on {path}: {resp.get('msg', 'unknown')}")
+    return resp["data"]
+
+
+def get_device_list(bearer_token: str, region: str = DEFAULT_REGION) -> list[dict]:
+    api_base = _region_cfg(region)["api_base"]
+    data = _api_get(bearer_token, api_base, "/v2/binding/enduserapi/userDeviceList", {"page": 1, "pageSize": 50})
+    return data.get("list", [])
+
+
+def get_tsl(bearer_token: str, pk: str, region: str = DEFAULT_REGION) -> list[dict]:
+    api_base = _region_cfg(region)["api_base"]
+    data = _api_get(bearer_token, api_base, "/v2/binding/enduserapi/productTSL", {"pk": pk})
+    properties = [
+        p for p in data.get("properties", [])
+        if "W" in p.get("subType", "") and p["type"] == "PROPERTY"
+    ]
+    properties.sort(key=lambda p: p.get("sort", 0))
+    return properties
+
+
+def refresh_token(bearer_token: str, refresh_token_value: str, region: str = DEFAULT_REGION) -> tuple[str, str]:
+    """Exchange the refresh token for a new (access_token, refresh_token) pair.
+
+    The API requires BOTH the current access token as the Authorization
+    header AND the full refresh token (including its "Bearer " prefix) as a
+    form-encoded `refreshToken` body field — sending only one or the other
+    is rejected. The refresh token itself rotates on every successful call,
+    so the new one returned here must be persisted too, not just the access
+    token.
+    """
+    api_base = _region_cfg(region)["api_base"]
+    headers = {
+        **_default_headers(),
+        "Authorization": bearer_token,
+        "Content-Type": "application/x-www-form-urlencoded",
+    }
+    data = urllib.parse.urlencode({"refreshToken": refresh_token_value}).encode()
+    req = urllib.request.Request(
+        api_base + "/v2/enduser/enduserapi/refreshToken",
+        data=data,
+        headers=headers,
+        method="PUT",
+    )
+    try:
+        resp = json.loads(urllib.request.urlopen(req).read())
+    except Exception as exc:
+        raise LandbookAPIError(f"Token refresh request failed: {exc}") from exc
+
+    if resp.get("code") != 200 or "data" not in resp:
+        raise LandbookAuthError(f"Token refresh rejected: {resp.get('msg', 'unknown error')}")
+    return resp["data"]["accessToken"]["token"], resp["data"]["refreshToken"]["token"]
+
+
+def get_device_attributes(bearer_token: str, pk: str, dk: str, region: str = DEFAULT_REGION) -> dict:
+    api_base = _region_cfg(region)["api_base"]
+    return _api_get(bearer_token, api_base, "/v2/binding/enduserapi/getDeviceBusinessAttributes", {"pk": pk, "dk": dk})
+
+
+async def async_login(email: str, password: str, region: str = DEFAULT_REGION) -> tuple[str, str, str]:
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(None, login, email, password, region)
+
+
+async def async_get_device_list(bearer_token: str, region: str = DEFAULT_REGION) -> list[dict]:
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(None, get_device_list, bearer_token, region)
+
+
+async def async_get_tsl(bearer_token: str, pk: str, region: str = DEFAULT_REGION) -> list[dict]:
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(None, get_tsl, bearer_token, pk, region)
+
+
+async def async_refresh_token(
+    bearer_token: str, refresh_token_value: str, region: str = DEFAULT_REGION
+) -> tuple[str, str]:
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(None, refresh_token, bearer_token, refresh_token_value, region)
+
+
+async def async_get_device_attributes(bearer_token: str, pk: str, dk: str, region: str = DEFAULT_REGION) -> dict:
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(None, get_device_attributes, bearer_token, pk, dk, region)

landbook_api-0.1.0/landbook_api/const.py

@@ -0,0 +1,36 @@
+"""Protocol constants for the Landbook (Netprisma/Landecia) cloud API."""
+
+APP_ID = "584"
+APP_VERSION = "3.6.0"
+APP_SYSTEM_TYPE = "ios"
+
+MQTT_PORT = 8443
+MQTT_WS_PATH = "/ws/v2"
+MQTT_KEEPALIVE = 40
+
+# Region definitions — sourced from ad0.java (i=0 CN, i=1 EU, i=2 US)
+REGIONS: dict[str, dict] = {
+    "us": {
+        "label": "United States",
+        "api_base": "https://iot-api.quectelus.com",
+        "mqtt_host": "iot-south.landecia.com",
+        "user_domain": "U.SP.8589934603",
+        "app_domain_key": "pUTp5goB1bLinprRQMmK3EPiiuPiGrJtKUNptWRXVmP",
+    },
+    "eu": {
+        "label": "Europe",
+        "api_base": "https://iot-api.quecteleu.com",
+        "mqtt_host": "iot-south.quecteleu.com",
+        "user_domain": "E.SP.4294967410",
+        "app_domain_key": "3aRNUwWahjyANa7WfBK2wCCkxCexB6nXxKJwXxfePvzf",
+    },
+    "cn": {
+        "label": "China",
+        "api_base": "https://iot-gateway.quectel.com",
+        "mqtt_host": "iot-south.quectelcn.com",
+        "user_domain": "C.DM.5903.1",
+        "app_domain_key": "EufftRJSuWuVY7c6txzGifV9bJcfXHAFa7hXY5doXSn7",
+    },
+}
+
+DEFAULT_REGION = "us"

landbook_api-0.1.0/landbook_api/mqtt_client.py

@@ -0,0 +1,234 @@
+"""Landbook MQTT client — WebSocket/TLS connection, pub/sub."""
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+from collections.abc import Callable
+from typing import Any
+
+import paho.mqtt.client as mqtt
+
+from .const import MQTT_KEEPALIVE, MQTT_PORT, MQTT_WS_PATH, REGIONS, DEFAULT_REGION
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class LandbookMQTTClient:
+    """Manages a single persistent MQTT connection for one account."""
+
+    def __init__(
+        self,
+        uid: str,
+        bearer_token: str,
+        mqtt_host: str | None = None,
+        token_refresher: Callable[[], str] | None = None,
+    ) -> None:
+        self._uid = uid
+        self._bearer_token = bearer_token
+        self._mqtt_host = mqtt_host or REGIONS[DEFAULT_REGION]["mqtt_host"]
+        self._token_refresher = token_refresher
+        self._client: mqtt.Client | None = None
+        self._connected = False
+        self._shutting_down = False
+        self._reauth_pending = False
+        self._msg_counter = 1000
+        self._reconnect_timer: threading.Timer | None = None
+
+        # device_id -> list of callbacks
+        self._listeners: dict[str, list[Callable[[str, Any], None]]] = {}
+        # called after (re)connect to refresh state
+        self._on_reconnect: Callable[[], None] | None = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def connect(self) -> None:
+        """Establish the WebSocket/TLS MQTT connection (blocking until connected or timeout)."""
+        client_id = f"qu_{self._uid}_{int(time.time() * 1000)}"
+        client = mqtt.Client(
+            mqtt.CallbackAPIVersion.VERSION2,
+            client_id=client_id,
+            transport="websockets",
+            protocol=mqtt.MQTTv311,
+        )
+        client.ws_set_options(path=MQTT_WS_PATH)
+        client.tls_set()
+        client.username_pw_set("", self._bearer_token)
+        client.on_connect = self._on_connect
+        client.on_message = self._on_message
+        client.on_disconnect = self._on_disconnect
+
+        client.connect(self._mqtt_host, MQTT_PORT, keepalive=MQTT_KEEPALIVE)
+        client.loop_start()
+        self._client = client
+
+        for _ in range(40):
+            if self._connected:
+                break
+            time.sleep(0.25)
+
+        if not self._connected:
+            raise ConnectionError("MQTT connection timed out")
+
+    def update_token(self, bearer_token: str) -> None:
+        """Update the stored token (e.g. after a refresh)."""
+        self._bearer_token = bearer_token
+
+    def halt_reconnects(self) -> None:
+        """Stop all reconnect attempts (e.g. while reauth is pending)."""
+        self._reauth_pending = True
+        if self._reconnect_timer:
+            self._reconnect_timer.cancel()
+            self._reconnect_timer = None
+
+    def disconnect(self) -> None:
+        self._shutting_down = True
+        if self._reconnect_timer:
+            self._reconnect_timer.cancel()
+            self._reconnect_timer = None
+        if self._client:
+            self._client.loop_stop()
+            self._client.disconnect()
+            self._client = None
+        self._connected = False
+
+    def subscribe_device(
+        self,
+        device_id: str,
+        callback: Callable[[str, Any], None],
+    ) -> None:
+        """Subscribe to all topics for a device and register a callback.
+
+        callback(topic_suffix, payload_dict)
+        """
+        if device_id not in self._listeners:
+            self._listeners[device_id] = []
+            if self._client and self._connected:
+                self._subscribe_topics(device_id)
+
+        self._listeners[device_id].append(callback)
+
+    def send_read(self, device_id: str, pk: str, dk: str, codes: list[str]) -> None:
+        """Request current values for the given property codes (READ-ATTR)."""
+        if not self._client or not self._connected:
+            return
+        self._msg_counter = (self._msg_counter + 1) & 0xFFFF
+        payload = json.dumps(
+            {
+                "msgId": self._msg_counter,
+                "productKey": pk,
+                "deviceKey": dk,
+                "type": "READ-ATTR",
+                "kv": json.dumps(codes),
+                "cacheTime": 0,
+                "isCache": False,
+                "isCover": False,
+            }
+        )
+        self._client.publish(f"q/1/d/{device_id}/sys_", payload, qos=1)
+        _LOGGER.debug("send_read device=%s codes=%s", device_id, codes)
+
+    def send_write(self, device_id: str, pk: str, dk: str, props: dict) -> None:
+        """Publish a WRITE-ATTR command."""
+        if not self._client or not self._connected:
+            raise ConnectionError("MQTT not connected")
+
+        self._msg_counter = (self._msg_counter + 1) & 0xFFFF
+        payload = json.dumps(
+            {
+                "msgId": self._msg_counter,
+                "productKey": pk,
+                "deviceKey": dk,
+                "type": "WRITE-ATTR",
+                "kv": json.dumps([props]),
+                "cacheTime": 0,
+                "isCache": False,
+                "isCover": False,
+            }
+        )
+        self._client.publish(f"q/1/d/{device_id}/sys_", payload, qos=1)
+        _LOGGER.debug("send_write device=%s props=%s", device_id, props)
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _subscribe_topics(self, device_id: str) -> None:
+        assert self._client
+        # Subscribe to all known downstream topics for this device
+        for suffix in ("ack_", "bus_", "onl_", "ota_", "inf_", "loc_"):
+            self._client.subscribe(f"q/2/d/{device_id}/{suffix}", qos=1)
+
+    def _on_connect(self, client, userdata, flags, reason_code, properties):
+        if str(reason_code) in ("Success", "0") or reason_code == 0:
+            self._connected = True
+            for device_id in self._listeners:
+                self._subscribe_topics(device_id)
+            _LOGGER.info("Landbook MQTT connected")
+            if self._on_reconnect:
+                self._on_reconnect()
+        else:
+            _LOGGER.error("Landbook MQTT connect failed: %s", reason_code)
+
+    def _on_disconnect(self, client, userdata, disconnect_flags, reason_code, properties):
+        self._connected = False
+        if self._shutting_down:
+            _LOGGER.debug("Landbook MQTT disconnected cleanly (unload)")
+            return
+        if self._reauth_pending:
+            _LOGGER.debug("Landbook MQTT disconnected while reauth pending — not reconnecting")
+            return
+        _LOGGER.warning("Landbook MQTT disconnected: %s — scheduling reconnect", reason_code)
+        self._schedule_reconnect(delay=5)
+
+    def _schedule_reconnect(self, delay: float = 5) -> None:
+        if self._reconnect_timer:
+            self._reconnect_timer.cancel()
+        self._reconnect_timer = threading.Timer(delay, self._reconnect)
+        self._reconnect_timer.daemon = True
+        self._reconnect_timer.start()
+
+    def _reconnect(self) -> None:
+        if self._reauth_pending:
+            return
+        _LOGGER.info("Landbook MQTT attempting reconnect")
+        try:
+            if self._token_refresher:
+                self._bearer_token = self._token_refresher()
+                _LOGGER.debug("Token refreshed before reconnect")
+        except Exception as exc:
+            _LOGGER.warning("Token refresh failed, reconnecting with old token: %s", exc)
+        if self._reauth_pending:
+            return
+        try:
+            if self._client:
+                self._client.loop_stop()
+            self.connect()
+        except Exception as exc:
+            _LOGGER.warning("Reconnect failed: %s — will retry in 30s", exc)
+            self._schedule_reconnect(delay=30)
+
+    def _on_message(self, client, userdata, msg: mqtt.MQTTMessage) -> None:
+        parts = msg.topic.split("/")
+        # topic format: q/2/d/{device_id}/{suffix}
+        if len(parts) < 5:
+            return
+        device_id = parts[3]
+        suffix = parts[4]
+
+        try:
+            payload = json.loads(msg.payload.decode())
+        except Exception:
+            _LOGGER.debug("Non-JSON MQTT payload on %s", msg.topic)
+            return
+
+        _LOGGER.debug("MQTT [%s] %s: %s", device_id, suffix, payload)
+
+        for cb in self._listeners.get(device_id, []):
+            try:
+                cb(suffix, payload)
+            except Exception:
+                _LOGGER.exception("Error in MQTT listener for %s", device_id)

landbook_api-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "landbook-api"
+version = "0.1.0"
+description = "Unofficial Python client for the Landbook (Netprisma/Landecia) smart home cloud API — REST auth/device discovery and MQTT pub/sub."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Zack Wagner" }]
+requires-python = ">=3.10"
+dependencies = [
+    "paho-mqtt>=2.0.0",
+    "pycryptodome>=3.0.0",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Home Automation",
+]
+
+[project.urls]
+Homepage = "https://github.com/zackwag/landbook-api"
+Issues = "https://github.com/zackwag/landbook-api/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["landbook_api"]

landbook_api-0.1.0/tests/test_api.py

@@ -0,0 +1,41 @@
+import base64
+
+from landbook_api import DEFAULT_REGION, REGIONS, LandbookMQTTClient
+from landbook_api.api import _encrypt_password, _region_cfg
+
+
+def test_regions_have_required_keys():
+    required = {"label", "api_base", "mqtt_host", "user_domain", "app_domain_key"}
+    for region, cfg in REGIONS.items():
+        assert required <= cfg.keys(), f"region {region} missing keys"
+
+
+def test_default_region_is_valid():
+    assert DEFAULT_REGION in REGIONS
+
+
+def test_region_cfg_falls_back_to_default_for_unknown_region():
+    assert _region_cfg("does-not-exist") == REGIONS[DEFAULT_REGION]
+
+
+def test_region_cfg_returns_requested_region():
+    assert _region_cfg("eu") == REGIONS["eu"]
+
+
+def test_encrypt_password_returns_base64_ciphertext_and_16_char_rand():
+    pwd_b64, rand = _encrypt_password("hunter2")
+    assert len(rand) == 16
+    # Should round-trip through base64 without error.
+    base64.b64decode(pwd_b64)
+
+
+def test_encrypt_password_uses_random_salt_each_call():
+    pwd_a, rand_a = _encrypt_password("hunter2")
+    pwd_b, rand_b = _encrypt_password("hunter2")
+    assert rand_a != rand_b
+    assert pwd_a != pwd_b
+
+
+def test_mqtt_client_can_be_constructed_without_connecting():
+    client = LandbookMQTTClient(uid="u1", bearer_token="Bearer abc")
+    assert client._mqtt_host == REGIONS[DEFAULT_REGION]["mqtt_host"]