plexus-python 0.11.2__py3-none-any.whl → 0.11.4__py3-none-any.whl

plexus/__init__.py

@@ -23,7 +23,7 @@ from plexus.client import (
 )
 from plexus.config import RetryConfig
 
-__version__ = "0.11.2"
+__version__ = "0.11.4"
 __all__ = [
     "AuthenticationError",
     "BatchSender",

plexus/_skills/plexus-firmware/SKILL.md

@@ -61,7 +61,7 @@ Four things the gateway will reject you for. Get these right or nothing lands:
 1. **The array is `points`.** `"metrics": [...]` returns `400 {"error":"'points' array is required"}`.
 2. **Every point needs `class`**, either `"metric"` or `"event"`. There is no default.
 3. **`timestamp` is a number, never a string.** An ISO-8601 string returns `points[i].timestamp must be a number`. Epoch **milliseconds**; a positive value below `1e12` is read as **seconds** and scaled for you, so either unit works as long as it's numeric.
-4. **`source_id` must match `^[a-z0-9][a-z0-9_-]{1,62}$`** and is not deduplicated — two devices declaring the same id merge into one source. This is what SD-card clones do when they all boot as `raspberrypi`.
+4. **`source_id` must match `^[a-z0-9][a-z0-9._-]*$` (max 256 chars)** and is not deduplicated — two devices declaring the same id merge into one source. This is what SD-card clones do when they all boot as `raspberrypi`.
 
 `timestamp` is optional. Omit it and the gateway stamps the point with its receive time — which is the right move on a device whose clock has never been NTP-synced. Per-point `tags` (a flat string→string map) are supported and optional.
 

plexus/cli.py

@@ -31,6 +31,7 @@ import threading
 import urllib.parse
 import webbrowser
 from pathlib import Path
+from typing import Any
 
 from . import config
 
@@ -428,8 +429,15 @@ def cmd_logout(_args: argparse.Namespace) -> int:
     return 0
 
 
-def cmd_whoami(_args: argparse.Namespace) -> int:
-    """Print the prefix of the locally stored key + the configured endpoint."""
+def cmd_whoami(args: argparse.Namespace) -> int:
+    """Report the local key, and whether the server still accepts it.
+
+    Printing the key alone was worse than printing nothing: a revoked or
+    expired credential produced confident-looking output and a zero exit, and
+    the 401s that followed from the SDK looked unrelated. `whoami` is what
+    someone runs precisely when they suspect their auth — it has to answer
+    that question rather than confirm a file exists.
+    """
     key = config.get_api_key()
     endpoint = config.get_endpoint()
     if not key:
@@ -438,7 +446,60 @@ def cmd_whoami(_args: argparse.Namespace) -> int:
     masked = f"{key[:8]}…{key[-4:]}" if len(key) > 12 else key
     print(f"key:      {masked}")
     print(f"endpoint: {endpoint}")
-    return 0
+
+    if args.no_verify:
+        return 0
+
+    status, body = _verify_key(endpoint, key)
+    if status == 200:
+        org = body.get("org_id") or "unknown"
+        scopes = ", ".join(body.get("scopes") or []) or "default"
+        print(f"org:      {org}")
+        print(f"scopes:   {scopes}")
+        print("status:   valid")
+        return 0
+    if status == 401:
+        print("status:   REJECTED — this key is invalid, revoked or expired.")
+        print("          Run `plexus init --force` to authorize this machine again.")
+        return 1
+    if status == 403:
+        print("status:   DISABLED — the key is real but access is switched off.")
+        print("          Usually billing; check with your org admin.")
+        return 1
+    if status is None:
+        # Could not ask. Say so rather than implying either answer.
+        print(f"status:   unknown — could not reach {endpoint} ({body})")
+        return 0
+    print(f"status:   unexpected response ({status})")
+    return 1
+
+
+def _verify_key(endpoint: str, key: str) -> tuple[int | None, Any]:
+    """Ask the server whether a key is good. Returns (status, parsed_or_reason).
+
+    A network failure returns (None, reason): unreachable is not the same as
+    rejected, and reporting one as the other is how a flaky connection gets
+    mistaken for a credentials problem.
+    """
+    import json as _json
+    import urllib.error
+    import urllib.request
+
+    req = urllib.request.Request(
+        f"{endpoint.rstrip('/')}/api/auth/verify-key",
+        headers={"x-api-key": key},
+        method="GET",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            return resp.status, _json.loads(resp.read().decode() or "{}")
+    except urllib.error.HTTPError as e:
+        try:
+            return e.code, _json.loads(e.read().decode() or "{}")
+        except Exception:
+            return e.code, {}
+    except Exception as e:  # DNS, TLS, timeout, offline
+        return None, str(e)
 
 
 def _bundled_skills_dir() -> Path | None:
@@ -507,11 +568,50 @@ def _default_skills_target(args: argparse.Namespace) -> Path:
     return Path.home() / ".claude" / "skills"
 
 
+class _VersionAwareParser(argparse.ArgumentParser):
+    """Turns an unknown subcommand into a version diagnosis.
+
+    argparse says `invalid choice: 'skills'` and stops. When the real cause is
+    an old install — a pipx shim from months ago shadowing a fresh pip
+    install, say — that message sends people looking for a typo instead of at
+    their version. The command they were told to run genuinely does not exist
+    *here*, and the fix is an upgrade, so say which version is running and how
+    to move it.
+    """
+
+    def error(self, message: str) -> None:  # type: ignore[override]
+        if "invalid choice" in message:
+            from plexus import __version__
+
+            self.print_usage(sys.stderr)
+            print(f"\n{self.prog}: error: {message}", file=sys.stderr)
+            print(
+                f"\nYou are running plexus-python {__version__}. If you were "
+                "following a doc that\nnames this command, your install is "
+                "probably older than the doc:\n"
+                "\n    pip install --upgrade plexus-python"
+                "\n    pipx upgrade plexus-python      # if you installed with pipx"
+                "\n\nThen check with: plexus --version",
+                file=sys.stderr,
+            )
+            self.exit(2)
+        super().error(message)
+
+
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
+    from plexus import __version__
+
+    parser = _VersionAwareParser(
         prog="plexus",
         description="Plexus CLI — auth, send, query telemetry from your terminal.",
     )
+    # The first thing anyone types when a CLI misbehaves, and previously an
+    # error: `plexus --version` demanded a subcommand and told you nothing.
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"plexus-python {__version__}",
+    )
     sub = parser.add_subparsers(dest="command", required=True)
 
     init = sub.add_parser(
@@ -537,6 +637,11 @@ def build_parser() -> argparse.ArgumentParser:
     logout.set_defaults(func=cmd_logout)
 
     whoami = sub.add_parser("whoami", help="Show the local credential summary.")
+    whoami.add_argument(
+        "--no-verify",
+        action="store_true",
+        help="Skip the server check and only print what is stored locally.",
+    )
     whoami.set_defaults(func=cmd_whoami)
 
     skills = sub.add_parser(

plexus/ws.py

@@ -1,7 +1,7 @@
 """
 WebSocket transport for the Plexus Python SDK.
 
-Wire-compatible with the C SDK (`plexus_ws.c`). Targets the gateway's
+Implements the gateway's device wire protocol. Targets its
 `/ws/device` endpoint and exchanges the same JSON frames:
 
     client → {"type": "device_auth", "api_key": ..., "source_id": ...,
@@ -392,7 +392,7 @@ class WebSocketTransport:
         command = msg.get("command") or ""
         params = msg.get("params") or {}
 
-        # Ack immediately (matches C SDK: plexus_ws.c:275-280)
+        # Ack immediately, per the gateway wire contract
         self._send_frame({
             "type": "command_result",
             "id": cmd_id,
@@ -547,8 +547,7 @@ def _safe_json(raw: Any) -> dict[str, Any]:
 
 
 def _backoff_delay(attempt: int) -> float:
-    """Exponential backoff with ±25% jitter, capped at BACKOFF_MAX_S.
-    Matches plexus_ws.c:44-52."""
+    """Exponential backoff with ±25% jitter, capped at BACKOFF_MAX_S."""
     base = min(BACKOFF_BASE_S * (2 ** attempt), BACKOFF_MAX_S)
     jitter = base * 0.25 * (2 * random.random() - 1)
     return max(0.1, base + jitter)

{plexus_python-0.11.2.dist-info → plexus_python-0.11.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plexus-python
-Version: 0.11.2
+Version: 0.11.4
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.company
 Project-URL: Documentation, https://docs.plexus.company
@@ -66,7 +66,7 @@ curl -sL https://app.plexus.company/setup | bash -s -- \
   --key plx_xxx --name drone-01
 ```
 
-The name must match `^[a-z0-9][a-z0-9_-]{1,62}$`. `setup.sh` refuses to run without `--name` (or without a TTY to prompt for one) — this is deliberate, because the previous `hostname` fallback silently merged telemetry from cloned SD-card images that all booted as `raspberrypi`.
+The name must match `^[a-z0-9][a-z0-9._-]*$` (max 256 chars). `setup.sh` refuses to run without `--name` (or without a TTY to prompt for one) — this is deliberate, because the previous `hostname` fallback silently merged telemetry from cloned SD-card images that all booted as `raspberrypi`.
 
 **Names are not auto-deduplicated.** The gateway echoes back whatever `source_id` you declare, unchanged — pick a unique name per device (that's what `--name` and `source_id=...` are for). Two devices that declare the same name write into the same source.
 
@@ -252,7 +252,7 @@ px.send("temperature", 72.5, timestamp=t)   # your timestamp, used as-is, no cor
 
 ## Transport
 
-By default the SDK connects over a **WebSocket** to `/ws/device` on the gateway — same wire protocol as the C SDK. This gives you:
+By default the SDK connects over a **WebSocket** to `/ws/device` on the gateway — the gateway's device wire protocol. This gives you:
 
 - lower-latency streaming of telemetry,
 - live command delivery from the UI / API to the device.

{plexus_python-0.11.2.dist-info → plexus_python-0.11.4.dist-info}/RECORD

@@ -1,19 +1,19 @@
-plexus/__init__.py,sha256=aKzqSESaFXWQ2mQ6XnckTtAsezjyYj4UpxhJEkWeOhk,808
+plexus/__init__.py,sha256=3108jW9HO6oLnblXhpp7gpqyL2ZAE7uaMC5F18gwQ5c,808
 plexus/_log.py,sha256=3fjXrHFZghQ_17umMcvDUjjTH6aTQB3J4SpVDBiH03w,335
 plexus/batching.py,sha256=mPMa3m9xK-DCwRmuyL_aqaTltimIOtwoDzz4PfKWyh8,10452
 plexus/buffer.py,sha256=UNv_jEcrDwbkjJ6uhCehb7uBI2EuFEwO40waDpZn_5I,9579
-plexus/cli.py,sha256=TenKqhvh7Z-JhAUj4kjogrRGA2Hlrfd3TvBFo4S5tlk,17633
+plexus/cli.py,sha256=YFkptze8LRc6mBmDgbsTeU8J6i8MMsdTWvtm3jCINiI,21773
 plexus/client.py,sha256=H69DR30pj3X8PiURZsViGTDHsIsQ2Kn4muHNECsioKw,53865
 plexus/config.py,sha256=RuDh5UdVGdVQld5kQlXZO6CVXO4tS0HBalyaoAlXNvc,4416
-plexus/ws.py,sha256=2kUCTPkS-tG1XpL9RAzTiytk4Dbck5ypqkbDRSKaTF8,19811
+plexus/ws.py,sha256=xQhJCOizX-V34tF3-r7Zpzs_wnBbNSCeEoZeFFXWH7E,19763
 plexus/cameras/__init__.py,sha256=AVu1vE1xfYk9lz1cprHlTfi0ieHf84UhQh9Z92E05b8,490
 plexus/cameras/thermal.py,sha256=-klCEJQG5GlLtELaowWOPYomwMsLK8O5pmmX0PqUrTA,12022
 plexus/_skills/README.md,sha256=9TNo9mssmBiBPkrYBiA2JJHWOIAEw6DvCWCYAvfzmjM,3243
 plexus/_skills/plexus/SKILL.md,sha256=Q1ZYe9YH-gOhMcGYuMG5H9DkHMfQOr3OazCtlxtP9f8,13617
 plexus/_skills/plexus-dashboard/SKILL.md,sha256=8xjdvI3orM31XHTLv1fSAWstCGMwt1HnEbo0SlpTxV4,9508
-plexus/_skills/plexus-firmware/SKILL.md,sha256=IkUqNbg5sM5VaZEb189P_aOUkm9_PlSqd4JLH0Nv830,12081
-plexus_python-0.11.2.dist-info/METADATA,sha256=Cpqy4cAMWY7qa1J4ofKpGMVKkRCGAYDhLTDoFVp9vfI,13517
-plexus_python-0.11.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-plexus_python-0.11.2.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
-plexus_python-0.11.2.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
-plexus_python-0.11.2.dist-info/RECORD,,
+plexus/_skills/plexus-firmware/SKILL.md,sha256=C5tOGu0_LOb76n8US2SLpWSdZdeHQIa4e_5fvkX4DGU,12093
+plexus_python-0.11.4.dist-info/METADATA,sha256=wu8laMoqY4e-3NtQbbma-LQFg4C0C6f0-1MwVzskasY,13532
+plexus_python-0.11.4.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+plexus_python-0.11.4.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
+plexus_python-0.11.4.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
+plexus_python-0.11.4.dist-info/RECORD,,