smartbox 2.6.2__tar.gz → 3.0.0__tar.gz

{smartbox-2.6.2 → smartbox-3.0.0}/.gitignore

@@ -73,3 +73,9 @@ junit.xml
 .DS_Store
 
 *.code-workspace
+
+# ws_user probe token stores (contain live credentials)
+*token*store*.json
+wsu_store.json
+*token*store*.json.tmp
+wsu_store.json.tmp

{smartbox-2.6.2 → smartbox-3.0.0}/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## 3.0.0
+
+First stable release of the standalone protocol/core library used by the 3.x
+Home Assistant integration.
+
+### Breaking
+
+* The 2.7 session/update-manager API is replaced by `smartbox.protocol`
+  (`SmartboxClient`, auth, `ws_user` transport, named writes) and
+  `smartbox.core` (`SmartboxEngine`, state, deadlines, feed).
+* The library is Home Assistant-free by construction; the integration depends
+  on it instead of vendoring the layers.
+* The CLI now uses the new client and `ws_user` transport. The old per-device
+  `socket` command is replaced by `listen`; `set-setup` exposes the granular
+  setup writes; boost and node power-limit commands are added.
+
+### New
+
+* The CLI remains available as the optional `cli` extra:
+  `pip install "smartbox[cli] ..."`.
+* `SmartboxClient.get_home_guests()` and the CLI `guests` command.
+* `WriteApi.set_setup_value()` as the CLI/debug escape hatch for setup keys
+  without a named setter.
+
+See GitHub release notes: https://github.com/jandado/smartbox/releases
+
+## 2.7.0
+
+### New
+* Per-user `ws_user` websocket transport (`WsUserSocketSession`,
+  `check_ws_user_support`): one connection serves every device of the
+  account, replacing N per-device `socket_io` sessions. Wire protocol
+  and every failure mode verified live (api-notes.md, "Transports —
+  socket_io vs ws_user"). Selected via the new `ws_user_socket=` kwarg
+  on `UpdateManager`; the default transport is unchanged.
+* `WsUserUnsupportedError` + the fallback doctrine: only deterministic
+  handshake rejections (HTTP 401/403/404/410 in the one-shot probe on a
+  fresh token; 404/410 in the run loop, or 401/403 that keep rejecting
+  freshly minted tokens) signal "endpoint unsupported"; transient
+  trouble is retried and never demotes.
+* In `ws_user` mode `UpdateManager` ignores the SocketSession
+  pass-through kwargs (warned at construction) — the shared socket's
+  liveness is heartbeat-driven, not knob-driven.
+
+### Breaking
+* `UpdateManager.socket_session` now returns `None` when the manager
+  runs in `ws_user` mode (previously always a `SocketSession`); use the
+  new `ws_user_socket` accessor to distinguish modes.
+
+### Features
+* CLI: every authentication option also resolves from a `SMARTBOX_*`
+  environment variable, and the `smartbox` console script loads a `.env`
+  file (searched upward from the working directory) before parsing
+  options. Precedence: command line > shell environment > `.env`. See
+  `.env.example`.
+
+### Fixes
+* CLI: `.env` parsing now follows python-dotenv semantics — an inline
+  `#` starts a comment only when it is preceded by whitespace and lies
+  outside quotes, and quoted values unquote even when a trailing
+  comment follows them. Previously inline comments silently became
+  part of the value and quote-stripping was defeated, corrupting
+  credentials written in the conventional quoted style.
+
+### Refactor
+* `UpdateManager`: `subscribe_to_node_status`/`_setup`/`_version`/`_prog`
+  share one `_subscribe_to_node_key` implementation.
+
+### Tests & CI
+* Socket tests for the namespace callbacks, websocket cleanup, SIGINT
+  handler and cancellation during connect; coverage floor of 95%
+  (`fail_under`) enforced.
+* ruff and mypy run over `tests/` in CI; `socket.py` is no longer
+  excluded from codecov.
+
+### Docs
+* README rewritten: library usage, command table, `.env` section and an
+  actionable Support section. api-notes documents how to capture the
+  Basic Auth credential and the new-reseller issue template points to it.
+
 ## 2.6.2
 
 Port round of upstream PR #64 (ajtudela, `improvements/fix_bugs`, 19
@@ -77,8 +157,8 @@ version bump).
   device group move, node select/power, group geo_data/extra_data, invite
   flows (invite/revoke/confirm — confirm is unauthenticated), quiet-home
   notification config GET/POST + test, encrypted-wifi-credentials and
-  geocoding helpers. Read-only-verified paths pinned from the vendor app
-  bundle; all writes marked **unverified on live hardware** in docstrings.
+  geocoding helpers. Read-only-verified paths pinned from the official
+  vendor app; all writes marked **unverified on live hardware** in docstrings.
   New base helpers: `_api_delete`, host-relative `_api_get` (params not
   logged — may carry secrets) and `_api_post_path` (auth optional).
 * Away-status writes default `enabled: true` to match the vendor app shape

smartbox-3.0.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: smartbox
+Version: 3.0.0
+Summary: Python API to control heating 'smart boxes'
+Project-URL: Homepage, https://github.com/jandado/smartbox
+Project-URL: Issues, https://github.com/jandado/smartbox/issues
+Project-URL: Upstream, https://github.com/ajtudela/smartbox
+Author-email: Alberto Tudela <ajtudela@gmail.com>, Delmael <delmael@outlook.com>, graham33 <graham@grahambennett.org>
+Maintainer: Jan Dado
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.14.2
+Requires-Dist: aiohttp<4,>=3
+Provides-Extra: cli
+Requires-Dist: asyncclick; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# smartbox 3.0
+
+Python library for Smartbox heating systems (Helki and its resellers: Elnur,
+Haverland, Climastar, Technotherm, HJM, …).
+
+This is the 3.0 rewrite. It exposes the protocol and domain layers that the
+Home Assistant integration uses, without importing Home Assistant. The 2.7
+API remains available on the `main` branch and the `v2.7.0` tag.
+
+## Install
+
+From the tagged source:
+
+```sh
+pip install "smartbox @ https://github.com/jandado/smartbox/archive/refs/tags/v3.0.0.tar.gz"
+```
+
+With the optional command line tool:
+
+```sh
+pip install "smartbox[cli] @ https://github.com/jandado/smartbox/archive/refs/tags/v3.0.0.tar.gz"
+```
+
+For development:
+
+```sh
+uv sync --all-extras --dev
+```
+
+## Library
+
+`SmartboxClient` owns the REST API and the token lifecycle. `smartbox.core`
+contains the Home Assistant-free state engine, write confirmation and feed
+supervision.
+
+```python
+import asyncio
+
+from smartbox.core import SmartboxEngine
+from smartbox.protocol import API_HOST, AuthConfig, ManagedTokenSource, SmartboxClient
+
+CONFIG = AuthConfig(
+    api_host=API_HOST,
+    basic_auth_creds="<reseller Basic auth>",
+    serial_id="1",
+    username="you@example.com",
+    password="secret",
+    referer="https://app.helki.com/",
+)
+
+async def main() -> None:
+    client = SmartboxClient(CONFIG)
+    try:
+        print(await client.get_devices())
+    finally:
+        await client.close()
+```
+
+The lower layers are Home Assistant-free and are tested without the HA test
+harness.
+
+## CLI
+
+The CLI is an optional extra; the base package only depends on `aiohttp`.
+
+Authentication options are `-a/--api-name`, `-b/--basic-auth-creds`,
+`-u/--username`, `-p/--password`, `-r/--x-referer`, `-i/--x-serial-id`.
+They also resolve from `SMARTBOX_*` environment variables, and the script
+loads the nearest `.env` file. Command line values win over the environment,
+which wins over `.env`.
+
+```sh
+smartbox -a api -u you@example.com -p secret devices
+smartbox -a api -u you@example.com -p secret nodes
+smartbox -a api -u you@example.com -p secret status
+smartbox -a api -u you@example.com -p secret set-status -d DEV -n 0 --mode auto
+smartbox -a api -u you@example.com -p secret set-boost-mode -d DEV -n 0 \
+  --active --mode runback --temperature 21 --time-minutes 60
+smartbox -a api -u you@example.com -p secret listen
+```
+
+`smartbox --help` lists every command. Reads print the raw wire payloads;
+writes print the posted path and body. `listen` follows the shared `ws_user`
+feed and can filter updates with `--device-id`.
+
+## Layout
+
+- `smartbox.protocol` — auth, REST client, `ws_user` transport, wire values
+  and named writes.
+- `smartbox.core` — versioned state store, merges, write confirmation,
+  deadlines and feed supervision.
+- `smartbox.cli` — the optional debugging CLI.
+
+The canonical wire record lives in the sibling `hass-smartbox` repository
+under `docs/` (`api-contract.md`, `api-ws-user.md`, `webapi-spec.md`);
+`webapi-spec.md` in this repo is a pointer.
+
+## Development
+
+```sh
+uv run pytest
+uv run ruff check src tests
+uv run mypy src
+uv run tox
+```
+
+## Credits
+
+The original library and the 2.7.x line are by Alberto Tudela, Delmael,
+graham33 and the upstream contributors. This fork carries the 3.0 rewrite;
+upstream collaboration is welcome.

smartbox-3.0.0/README.md

@@ -0,0 +1,111 @@
+# smartbox 3.0
+
+Python library for Smartbox heating systems (Helki and its resellers: Elnur,
+Haverland, Climastar, Technotherm, HJM, …).
+
+This is the 3.0 rewrite. It exposes the protocol and domain layers that the
+Home Assistant integration uses, without importing Home Assistant. The 2.7
+API remains available on the `main` branch and the `v2.7.0` tag.
+
+## Install
+
+From the tagged source:
+
+```sh
+pip install "smartbox @ https://github.com/jandado/smartbox/archive/refs/tags/v3.0.0.tar.gz"
+```
+
+With the optional command line tool:
+
+```sh
+pip install "smartbox[cli] @ https://github.com/jandado/smartbox/archive/refs/tags/v3.0.0.tar.gz"
+```
+
+For development:
+
+```sh
+uv sync --all-extras --dev
+```
+
+## Library
+
+`SmartboxClient` owns the REST API and the token lifecycle. `smartbox.core`
+contains the Home Assistant-free state engine, write confirmation and feed
+supervision.
+
+```python
+import asyncio
+
+from smartbox.core import SmartboxEngine
+from smartbox.protocol import API_HOST, AuthConfig, ManagedTokenSource, SmartboxClient
+
+CONFIG = AuthConfig(
+    api_host=API_HOST,
+    basic_auth_creds="<reseller Basic auth>",
+    serial_id="1",
+    username="you@example.com",
+    password="secret",
+    referer="https://app.helki.com/",
+)
+
+async def main() -> None:
+    client = SmartboxClient(CONFIG)
+    try:
+        print(await client.get_devices())
+    finally:
+        await client.close()
+```
+
+The lower layers are Home Assistant-free and are tested without the HA test
+harness.
+
+## CLI
+
+The CLI is an optional extra; the base package only depends on `aiohttp`.
+
+Authentication options are `-a/--api-name`, `-b/--basic-auth-creds`,
+`-u/--username`, `-p/--password`, `-r/--x-referer`, `-i/--x-serial-id`.
+They also resolve from `SMARTBOX_*` environment variables, and the script
+loads the nearest `.env` file. Command line values win over the environment,
+which wins over `.env`.
+
+```sh
+smartbox -a api -u you@example.com -p secret devices
+smartbox -a api -u you@example.com -p secret nodes
+smartbox -a api -u you@example.com -p secret status
+smartbox -a api -u you@example.com -p secret set-status -d DEV -n 0 --mode auto
+smartbox -a api -u you@example.com -p secret set-boost-mode -d DEV -n 0 \
+  --active --mode runback --temperature 21 --time-minutes 60
+smartbox -a api -u you@example.com -p secret listen
+```
+
+`smartbox --help` lists every command. Reads print the raw wire payloads;
+writes print the posted path and body. `listen` follows the shared `ws_user`
+feed and can filter updates with `--device-id`.
+
+## Layout
+
+- `smartbox.protocol` — auth, REST client, `ws_user` transport, wire values
+  and named writes.
+- `smartbox.core` — versioned state store, merges, write confirmation,
+  deadlines and feed supervision.
+- `smartbox.cli` — the optional debugging CLI.
+
+The canonical wire record lives in the sibling `hass-smartbox` repository
+under `docs/` (`api-contract.md`, `api-ws-user.md`, `webapi-spec.md`);
+`webapi-spec.md` in this repo is a pointer.
+
+## Development
+
+```sh
+uv run pytest
+uv run ruff check src tests
+uv run mypy src
+uv run tox
+```
+
+## Credits
+
+The original library and the 2.7.x line are by Alberto Tudela, Delmael,
+graham33 and the upstream contributors. This fork carries the 3.0 rewrite;
+upstream collaboration is welcome.

{smartbox-2.6.2 → smartbox-3.0.0}/pyproject.toml

@@ -1,12 +1,15 @@
 [project]
 name = "smartbox"
-version = "2.6.2"
+version = "3.0.0"
 requires-python = ">=3.14.2"
 authors = [
   { name="Alberto Tudela", email="ajtudela@gmail.com" },
   { name="Delmael", email="delmael@outlook.com" },
   { name="graham33", email="graham@grahambennett.org" },
 ]
+maintainers = [
+  { name="Jan Dado" },
+]
 description = "Python API to control heating 'smart boxes'"
 readme = "README.md"
 
@@ -19,38 +22,44 @@ license = "MIT"
 license-files = ["LICEN[CS]E*"]
 dependencies = [
     "aiohttp>=3,<4",
-    "asyncclick",
-    "jq",
-    "pydantic>=2,<3",
-    "python-socketio>=5,<6",
 ]
 
-[project.urls]
-Homepage = "https://github.com/ajtudela/smartbox"
-Issues = "https://github.com/ajtudela/smartbox/issues"
+[project.optional-dependencies]
+cli = ["asyncclick"]
 
 [project.scripts]
-smartbox = "smartbox.cmd:smartbox"
+smartbox = "smartbox.cli:cli"
+
+[project.urls]
+Homepage = "https://github.com/jandado/smartbox"
+Issues = "https://github.com/jandado/smartbox/issues"
+Upstream = "https://github.com/ajtudela/smartbox"
 
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src/smartbox",
+  "/tests",
+  "/README.md",
+  "/LICENSE",
+  "/CHANGELOG.md",
+]
+
 
 [dependency-groups]
 dev = [
-    "pre-commit",
-    "freezegun",
+    "asyncclick",
+    "multidict",
     "pytest",
     "pytest-asyncio",
     "pytest-cov",
-    "pytest-mock",
-    "pytest-randomly",
-    "requests-mock",
-    "tox",
     "ruff",
     "mypy",
-    "time-machine",
+    "tox",
+    "yarl",
 ]
 
 [tool.pytest.ini_options]
@@ -61,22 +70,27 @@ markers = [
     "network: tests that make real HTTP calls to reseller servers (deselected by default; run with -m network)",
 ]
 
+[tool.coverage.run]
+# The CLI is an optional extra; it is exercised manually against the live API
+# and by the `--help`/reseller smoke tests, not by the core coverage gate.
+omit = ["src/smartbox/cli.py"]
+
+[tool.coverage.report]
+fail_under = 95
+exclude_also = ["if __name__ == .__main__.:"]
+
 [tool.mypy]
 warn_unused_configs = true
 
 [[tool.mypy.overrides]]
-module = [
-    "jq",
-    "socketio",
-    "asyncio",
-]
+module = ["asyncio"]
 ignore_missing_imports = true
 disable_error_code = ["arg-type"]
 
 [tool.ruff]
 target-version = "py314"
 fix = true
-line-length = 80
+line-length = 88
 extend-exclude = ["tools"]
 
 [tool.ruff.lint]
@@ -136,8 +150,17 @@ max-complexity = 25
     "S106",
     "PLR2004",
     "B018",
+    "PT011",
+]
+"src/smartbox/cli.py" = [
+    "ANN401",
+    "D10",
+    "EM101",
+    "EM102",
+    "PLR2004",
+    "TRY003",
 ]
-"src/smartbox/cmd.py" = ["T201", "ANN001"]
+"src/smartbox/core/**" = ["TID252"]
 "tools/*" = ["T201", "ANN401", "INP001", "PLR0911", "PLR0915", "S108", "ASYNC240"]
 
 

smartbox-3.0.0/src/smartbox/__init__.py

@@ -0,0 +1,17 @@
+"""Smartbox protocol and domain layers.
+
+The package is Home Assistant-agnostic: ``smartbox.protocol`` owns the
+wire and the ``smartbox.core`` package owns the domain state. Both are
+usable without the HA test harness.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from . import core, protocol
+
+try:
+    __version__ = version("smartbox")
+except PackageNotFoundError:  # pragma: no cover - vendored/undist import
+    __version__ = "0.0.0"
+
+__all__ = ["__version__", "core", "protocol"]