socketry 0.1.0__tar.gz → 0.2.0__tar.gz

{socketry-0.1.0 → socketry-0.2.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: socketry
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python API and CLI for controlling Jackery portable power stations
 Author: Jesus Lopez
 Author-email: Jesus Lopez <jesus@jesusla.com>
 License-Expression: MIT
 Requires-Dist: typer>=0.9
-Requires-Dist: paho-mqtt>=2.0
-Requires-Dist: requests>=2.31
+Requires-Dist: aiomqtt>=2.0
+Requires-Dist: aiohttp>=3.9
 Requires-Dist: pycryptodome>=3.19
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -15,6 +15,7 @@ Description-Content-Type: text/markdown
 # socketry
 
 [![CI](https://github.com/jlopez/socketry/actions/workflows/ci.yml/badge.svg)](https://github.com/jlopez/socketry/actions/workflows/ci.yml)
+![Coverage](https://img.shields.io/badge/coverage-74%25-yellowgreen)
 ![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
 
 Python API and CLI for controlling Jackery portable power stations.
@@ -26,14 +27,14 @@ the device or its firmware.
 ## Quick start
 
 ```bash
-uvx --from git+https://github.com/jlopez/socketry socketry login --email you@example.com --password 'yourpass'
-uvx --from git+https://github.com/jlopez/socketry socketry get
+uvx socketry login --email you@example.com --password 'yourpass'
+uvx socketry get
 ```
 
 Or install it once and use `socketry` directly:
 
 ```bash
-uv tool install git+https://github.com/jlopez/socketry
+uv tool install socketry
 socketry login --email you@example.com --password 'yourpass'
 socketry get
 ```
@@ -61,12 +62,12 @@ properties returned by newer firmware are displayed as raw key/value pairs.
 ## Install
 
 ```bash
-# Install as a CLI tool (from GitHub)
-uv tool install git+https://github.com/jlopez/socketry
-
-# Or from PyPI (once published)
+# Install as a CLI tool
 uv tool install socketry
 
+# Or run directly without installing
+uvx socketry --help
+
 # Or install as a library
 pip install socketry
 ```
@@ -165,30 +166,69 @@ Writable settings:
 | `sfc` | on / off | Super fast charge |
 | `ups` | on / off | UPS mode |
 
+### Watching live updates (`watch`)
+
+```bash
+# Stream all property changes in real time
+socketry watch
+
+# Filter to a single property
+socketry watch battery
+
+# Example output:
+# [14:32:01] 855124121010657 Output power (output-power): 182W
+# [14:32:05] 855124121010657 Battery (battery): 85%
+# [14:32:10] Disconnected, reconnecting...
+# [14:32:15] 855124121010657 Battery (battery): 84%
+```
+
+Press Ctrl+C to stop. The connection automatically reconnects if the broker
+disconnects (e.g. when a `set` command runs from another terminal).
+
+> **Note:** The Jackery broker only allows one MQTT connection per account.
+> Running `socketry set` while `watch` is active will briefly disconnect the
+> watcher. It reconnects automatically, but updates during the reconnection
+> window are lost.
+
 ## Library usage
 
 ```python
+import asyncio
 from socketry import Client
 
-# Authenticate (or load saved credentials)
-client = Client.login("email@example.com", "password")
-client.save_credentials()
+async def main():
+    # Authenticate (or load saved credentials)
+    client = await Client.login("email@example.com", "password")
+    client.save_credentials()
+
+    # Or load previously saved credentials
+    client = Client.from_saved()
+
+    # List and select devices
+    devices = await client.fetch_devices()
+    client.select_device(0)
+
+    # Read properties
+    props = await client.get_all_properties()
+    setting, value = await client.get_property("battery")
+    print(f"{setting.name}: {setting.format_value(value)}")
+
+    # Control
+    await client.set_property("ac", "on")
+    result = await client.set_property("light", "high", wait=True)
 
-# Or load previously saved credentials
-client = Client.from_saved()
+    # Subscribe to real-time updates
+    async def on_update(device_sn: str, properties: dict) -> None:
+        print(f"{device_sn}: {properties}")
 
-# List and select devices
-devices = client.fetch_devices()
-client.select_device(0)
+    async def on_disconnect() -> None:
+        print("Reconnecting...")
 
-# Read properties
-props = client.get_all_properties()
-setting, value = client.get_property("battery")
-print(f"{setting.name}: {setting.format_value(value)}")
+    subscription = await client.subscribe(on_update, on_disconnect=on_disconnect)
+    # ... later
+    await subscription.stop()
 
-# Control
-client.set_property("ac", "on")
-result = client.set_property("light", "high", wait=True)
+asyncio.run(main())
 ```
 
 ## How it works
@@ -205,7 +245,7 @@ protocol specification.
 
 ## Roadmap
 
-- [ ] MQTT real-time monitor (subscribe to live property changes)
+- [x] MQTT real-time monitor (`socketry watch` + `client.subscribe()`)
 - [ ] Token auto-refresh (JWT expires ~30 days)
 
 ## License

{socketry-0.1.0 → socketry-0.2.0}/README.md

@@ -1,6 +1,7 @@
 # socketry
 
 [![CI](https://github.com/jlopez/socketry/actions/workflows/ci.yml/badge.svg)](https://github.com/jlopez/socketry/actions/workflows/ci.yml)
+![Coverage](https://img.shields.io/badge/coverage-74%25-yellowgreen)
 ![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
 
 Python API and CLI for controlling Jackery portable power stations.
@@ -12,14 +13,14 @@ the device or its firmware.
 ## Quick start
 
 ```bash
-uvx --from git+https://github.com/jlopez/socketry socketry login --email you@example.com --password 'yourpass'
-uvx --from git+https://github.com/jlopez/socketry socketry get
+uvx socketry login --email you@example.com --password 'yourpass'
+uvx socketry get
 ```
 
 Or install it once and use `socketry` directly:
 
 ```bash
-uv tool install git+https://github.com/jlopez/socketry
+uv tool install socketry
 socketry login --email you@example.com --password 'yourpass'
 socketry get
 ```
@@ -47,12 +48,12 @@ properties returned by newer firmware are displayed as raw key/value pairs.
 ## Install
 
 ```bash
-# Install as a CLI tool (from GitHub)
-uv tool install git+https://github.com/jlopez/socketry
-
-# Or from PyPI (once published)
+# Install as a CLI tool
 uv tool install socketry
 
+# Or run directly without installing
+uvx socketry --help
+
 # Or install as a library
 pip install socketry
 ```
@@ -151,30 +152,69 @@ Writable settings:
 | `sfc` | on / off | Super fast charge |
 | `ups` | on / off | UPS mode |
 
+### Watching live updates (`watch`)
+
+```bash
+# Stream all property changes in real time
+socketry watch
+
+# Filter to a single property
+socketry watch battery
+
+# Example output:
+# [14:32:01] 855124121010657 Output power (output-power): 182W
+# [14:32:05] 855124121010657 Battery (battery): 85%
+# [14:32:10] Disconnected, reconnecting...
+# [14:32:15] 855124121010657 Battery (battery): 84%
+```
+
+Press Ctrl+C to stop. The connection automatically reconnects if the broker
+disconnects (e.g. when a `set` command runs from another terminal).
+
+> **Note:** The Jackery broker only allows one MQTT connection per account.
+> Running `socketry set` while `watch` is active will briefly disconnect the
+> watcher. It reconnects automatically, but updates during the reconnection
+> window are lost.
+
 ## Library usage
 
 ```python
+import asyncio
 from socketry import Client
 
-# Authenticate (or load saved credentials)
-client = Client.login("email@example.com", "password")
-client.save_credentials()
+async def main():
+    # Authenticate (or load saved credentials)
+    client = await Client.login("email@example.com", "password")
+    client.save_credentials()
+
+    # Or load previously saved credentials
+    client = Client.from_saved()
+
+    # List and select devices
+    devices = await client.fetch_devices()
+    client.select_device(0)
+
+    # Read properties
+    props = await client.get_all_properties()
+    setting, value = await client.get_property("battery")
+    print(f"{setting.name}: {setting.format_value(value)}")
+
+    # Control
+    await client.set_property("ac", "on")
+    result = await client.set_property("light", "high", wait=True)
 
-# Or load previously saved credentials
-client = Client.from_saved()
+    # Subscribe to real-time updates
+    async def on_update(device_sn: str, properties: dict) -> None:
+        print(f"{device_sn}: {properties}")
 
-# List and select devices
-devices = client.fetch_devices()
-client.select_device(0)
+    async def on_disconnect() -> None:
+        print("Reconnecting...")
 
-# Read properties
-props = client.get_all_properties()
-setting, value = client.get_property("battery")
-print(f"{setting.name}: {setting.format_value(value)}")
+    subscription = await client.subscribe(on_update, on_disconnect=on_disconnect)
+    # ... later
+    await subscription.stop()
 
-# Control
-client.set_property("ac", "on")
-result = client.set_property("light", "high", wait=True)
+asyncio.run(main())
 ```
 
 ## How it works
@@ -191,7 +231,7 @@ protocol specification.
 
 ## Roadmap
 
-- [ ] MQTT real-time monitor (subscribe to live property changes)
+- [x] MQTT real-time monitor (`socketry watch` + `client.subscribe()`)
 - [ ] Token auto-refresh (JWT expires ~30 days)
 
 ## License

{socketry-0.1.0 → socketry-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "socketry"
-version = "0.1.0"
+version = "0.2.0"
 description = "Python API and CLI for controlling Jackery portable power stations"
 readme = "README.md"
 authors = [
@@ -10,8 +10,8 @@ requires-python = ">=3.11"
 license = "MIT"
 dependencies = [
     "typer>=0.9",
-    "paho-mqtt>=2.0",
-    "requests>=2.31",
+    "aiomqtt>=2.0",
+    "aiohttp>=3.9",
     "pycryptodome>=3.19",
 ]
 
@@ -24,12 +24,13 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
+    "aioresponses>=0.7",
     "mypy>=1.19.1",
     "pre-commit>=4.5.1",
     "pytest>=9.0.2",
+    "pytest-asyncio>=0.26",
     "pytest-cov>=6.0.0",
     "ruff>=0.14.14",
-    "types-requests>=2.31.0",
 ]
 
 [tool.ruff]
@@ -98,6 +99,7 @@ addopts = [
     "--cov-report=html",
     "--cov-report=json",
 ]
+asyncio_mode = "auto"
 
 [tool.coverage.run]
 source = ["src/socketry"]

socketry-0.2.0/src/socketry/__init__.py

@@ -0,0 +1,6 @@
+"""Python API and CLI for controlling Jackery portable power stations."""
+
+from socketry.client import Client, Device, Subscription
+from socketry.properties import MODEL_NAMES, PROPERTIES, Setting
+
+__all__ = ["Client", "Device", "MODEL_NAMES", "PROPERTIES", "Setting", "Subscription"]

{socketry-0.1.0 → socketry-0.2.0}/src/socketry/_constants.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import platform
 from pathlib import Path
 
 API_BASE = "https://iot.jackeryapp.com/v1"
@@ -45,8 +46,16 @@ UJLtYvgsxiBKAnK8YkAyu51Jm8uLz1BZ1RANf22vv0QUTW+SGdgc5Q1h610G9N1i
 CRED_DIR = Path.home() / ".config" / "socketry"
 CRED_FILE = CRED_DIR / "credentials.json"
 
+# The server requires Android-style headers for some endpoints (notably
+# /device/bind/list returns error 10600 without them).  Values match the
+# decompiled APK v1.0.7 request interceptor (AppApplication.u).
 APP_HEADERS: dict[str, str] = {
     "platform": "2",
-    "app_version": "1.2.0",
+    "app_version": "v1.0.7",
+    "app_version_code": "107",
+    "Accept-Language": "en",
+    "sys_version": f"Python {platform.python_version()}",
+    "device_model": f"{platform.system()}/{platform.machine()}",
+    "network": "wifi",
     "Content-Type": "application/x-www-form-urlencoded",
 }

{socketry-0.1.0 → socketry-0.2.0}/src/socketry/cli.py

@@ -2,8 +2,11 @@
 
 from __future__ import annotations
 
+import asyncio
+import contextlib
 import json
 import sys
+from datetime import datetime
 
 import typer
 
@@ -60,12 +63,19 @@ def login(
 ) -> None:
     """Authenticate with Jackery and save credentials locally."""
     typer.echo(f"Logging in as {email}...")
-    client = Client.login(email, password)
+    client = asyncio.run(Client.login(email, password))
     client.save_credentials()
     n = len(client.devices)
-    typer.echo(
-        f"Logged in. {n} device(s) found. Selected: {client.device_name} (SN: {client.device_sn})"
-    )
+    if n == 0:
+        typer.echo(
+            "Logged in, but no devices found. Run `socketry debug` to troubleshoot.",
+            err=True,
+        )
+    else:
+        typer.echo(
+            f"Logged in. {n} device(s) found."
+            f" Selected: {client.device_name} (SN: {client.device_sn})"
+        )
 
 
 @app.command()
@@ -73,7 +83,7 @@ def devices() -> None:
     """List all devices (owned and shared). Refreshes from API."""
     client = _ensure_client()
     typer.echo("Fetching devices...")
-    all_devices = client.fetch_devices()
+    all_devices = asyncio.run(client.fetch_devices())
     if not all_devices:
         typer.echo("No devices found.", err=True)
         raise typer.Exit(1)
@@ -105,6 +115,68 @@ def select(index: int) -> None:
     typer.echo(f"Selected: {dev['devName']} — {model} (SN: {dev['devSn']})")
 
 
+@app.command()
+def debug() -> None:
+    """Dump raw API responses for troubleshooting device access."""
+    asyncio.run(_debug_async())
+
+
+async def _debug_async() -> None:
+    """Async implementation of the debug command."""
+    import aiohttp
+
+    from socketry._constants import API_BASE, APP_HEADERS
+
+    client = _ensure_client()
+    auth_headers = {**APP_HEADERS, "token": client.token}
+    timeout = aiohttp.ClientTimeout(total=15)
+
+    async with aiohttp.ClientSession() as session:
+        typer.echo("=== GET /device/bind/list (owned devices) ===")
+        try:
+            async with session.get(
+                f"{API_BASE}/device/bind/list",
+                headers=auth_headers,
+                timeout=timeout,
+            ) as resp:
+                typer.echo(f"Status: {resp.status}")
+                _print_json(await resp.json())
+        except Exception as e:
+            typer.echo(f"Error: {e}")
+
+        typer.echo("\n=== GET /device/bind/shared (share relationships) ===")
+        try:
+            async with session.get(
+                f"{API_BASE}/device/bind/shared",
+                headers=auth_headers,
+                timeout=timeout,
+            ) as resp:
+                typer.echo(f"Status: {resp.status}")
+                _print_json(await resp.json())
+        except Exception as e:
+            typer.echo(f"Error: {e}")
+
+        devs = client.devices
+        if devs:
+            dev = devs[0]
+            dev_id = dev.get("devId", "")
+            if dev_id:
+                typer.echo(f"\n=== GET /device/property?deviceId={dev_id} (first device) ===")
+                try:
+                    async with session.get(
+                        f"{API_BASE}/device/property",
+                        params={"deviceId": str(dev_id)},
+                        headers=auth_headers,
+                        timeout=timeout,
+                    ) as resp:
+                        typer.echo(f"Status: {resp.status}")
+                        _print_json(await resp.json())
+                except Exception as e:
+                    typer.echo(f"Error: {e}")
+            else:
+                typer.echo(f"\n(!) First device has empty devId: {json.dumps(dev)}")
+
+
 @app.command("get", context_settings={"help_option_names": ["-h", "--help"]})
 def get_property(
     ctx: typer.Context,
@@ -121,7 +193,7 @@ def get_property(
     client = _ensure_client()
 
     try:
-        data = client.get_all_properties()
+        data = asyncio.run(client.get_all_properties())
     except (ValueError, RuntimeError) as e:
         typer.echo(str(e), err=True)
         raise typer.Exit(1) from None
@@ -256,7 +328,7 @@ def set_setting(
     typer.echo(f"Setting {s.slug} to {value}...")
 
     try:
-        result = client.set_property(setting, value, wait=wait, verbose=verbose)
+        result = asyncio.run(client.set_property(setting, value, wait=wait, verbose=verbose))
     except (KeyError, ValueError) as e:
         typer.echo(str(e), err=True)
         raise typer.Exit(1) from None
@@ -273,3 +345,69 @@ def set_setting(
             typer.echo("No response from device (timeout).", err=True)
     else:
         typer.echo(f"Command sent to {client.device_name}.")
+
+
+@app.command()
+def watch(
+    name: str | None = typer.Argument(None, help="Property name to filter (optional)"),
+) -> None:
+    """Watch real-time property updates from the device via MQTT.
+
+    \b
+    Without arguments, shows all property changes.
+    With a property name, shows only that property.
+    Press Ctrl+C to stop.
+    """
+    client = _ensure_client()
+
+    setting: Setting | None = None
+    if name is not None:
+        setting = resolve(name)
+        if setting is None:
+            typer.echo(f"Unknown property '{name}'.", err=True)
+            raise typer.Exit(1)
+
+    with contextlib.suppress(KeyboardInterrupt):
+        asyncio.run(_watch_async(client, setting))
+
+
+async def _watch_async(client: Client, setting: Setting | None) -> None:
+    """Async implementation of the watch command."""
+    is_tty = sys.stdout.isatty()
+    if setting:
+        typer.echo(f"Watching {setting.name} ({setting.slug})... (Ctrl+C to stop)")
+    else:
+        typer.echo("Watching for property updates... (Ctrl+C to stop)")
+
+    async def on_update(device_sn: str, properties: dict[str, object]) -> None:
+        ts = datetime.now().strftime("%H:%M:%S")
+        for key, value in properties.items():
+            if setting and key != setting.id:
+                continue
+            s = _by_id.get(key)
+            if s:
+                label = f"{s.name} ({s.slug})"
+                formatted = s.format_value(value)
+            else:
+                label = key
+                formatted = str(value)
+            if is_tty:
+                typer.echo(
+                    f"[{ts}] {typer.style(device_sn, bold=True)} "
+                    f"{typer.style(label, fg='cyan')}: {formatted}"
+                )
+            else:
+                typer.echo(f"[{ts}] {device_sn} {label}: {formatted}")
+
+    async def on_disconnect() -> None:
+        ts = datetime.now().strftime("%H:%M:%S")
+        if is_tty:
+            typer.echo(typer.style(f"[{ts}] Disconnected, reconnecting...", fg="yellow"))
+        else:
+            typer.echo(f"[{ts}] Disconnected, reconnecting...")
+
+    subscription = await client.subscribe(on_update, on_disconnect=on_disconnect)
+    try:
+        await subscription.wait()
+    finally:
+        await subscription.stop()