rtls-sdk 0.2.0__tar.gz → 0.3.0__tar.gz

{rtls_sdk-0.2.0 → rtls_sdk-0.3.0}/CHANGELOG.md

@@ -7,7 +7,85 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
-## [0.2.0] — 2026-05-12
+## [0.3.0] — 2026-05-13
+
+### Documentation
+
+- New `entities/streaming.md` documenting `client.ws`, the eight
+  typed channel models, reconnects, heartbeats, backpressure, and a
+  REST → WS round-trip recipe. Reference pages (`resources.md`,
+  `models.md`, `errors.md`) now list the WS surface. Catalog and
+  quickstart link to the new page.
+
+### Added
+
+#### Typed WS channel models (M18)
+
+- `rtls_sdk.models.ws` — new sub-package with one pydantic model per
+  decoded channel: `PositionMessage` (pos), `NotifyMessage` (notify),
+  `AlarmMessage` (alarm), `ZoneEventMessage` (zone_event),
+  `SensorMessage` (sensor), `OtaMessage` (ota), `ParamPMessage`
+  (param_p), `UserMsgMessage` (user_msg). All eight inherit from
+  `WsChannelEnvelope` and carry the full wire dict on `.raw` for
+  forward-compat field access.
+- `client.ws.subscribe(...)` now yields typed messages instead of the
+  M17 untyped envelope; iteration patterns like
+  `match msg: case PositionMessage(x=x, y=y): ...` work directly. The
+  yield type narrowed from `WsChannelMessage` to `WsChannelEnvelope`.
+- Unknown channels and decode failures fall back to
+  `WsChannelMessage` (now a pydantic model, was a frozen dataclass) so
+  the iterator never dies on a single bad frame. Validation errors
+  log at WARNING with the channel name.
+- New `include_heartbeats: bool = False` kwarg on
+  `client.ws.subscribe(...)`. By default, `notify` frames with
+  `action == "HB"` are dropped at the reader; opt-in callers receive
+  them as `NotifyMessage(action="HB")`. Heartbeat drops do not count
+  toward `session.messages_dropped` — that counter remains
+  backpressure-only.
+
+### Changed
+
+- `WsChannelMessage` moved from `rtls_sdk._ws` to
+  `rtls_sdk.models.ws`; the import path under the top-level package
+  (`from rtls_sdk import WsChannelMessage`) is unchanged.
+
+#### WebSocket subscription scaffold (M17)
+
+- `client.ws` — new `WsAPI` sub-client wrapping the JSON-RPC 2.0
+  subscriptions-manager. `ws.list_channels()` returns the server's
+  advertised channel inventory in a one-shot dial (no auth required).
+  `ws.subscribe(channels, *, project_uid=None, reconnect=True,
+  queue_max=1024)` opens a long-lived session that is both a context
+  manager and a blocking iterator of `WsChannelMessage` envelopes.
+  Naming is transport-specific on purpose — future streaming
+  protocols (MQTT, Kafka) would land as siblings (`client.mqtt`,
+  `client.kafka`) rather than crowd a generic `client.stream`
+  namespace.
+- `WsChannelMessage(channel, raw)` — untyped pass-through for any
+  channel; typed channel models land in M18.
+- Reader runs on a daemon thread behind a bounded queue. Backpressure
+  drops the oldest message and bumps `session.messages_dropped`.
+  Auto-reconnect with capped exponential backoff
+  `(1, 2, 4, 8, 15, 30, 30, 30)` seconds on unclean disconnects;
+  re-subscribes the current channel set. Auth failure during reconnect
+  surfaces as `WsAuthError` from the iterator and stops further
+  attempts.
+- New error classes `WsError`, `WsAuthError`, and `WsProtocolError`
+  (all subclasses of `RtlsError`).
+- New dependency: `websockets >= 12.0`.
+
+#### User messages REST (M16)
+
+- `client.user_messages.send(tag_uid, hex)` — new `UserMessagesAPI`
+  sub-client; sends a hex payload to a tag's badge over the WIN
+  gateway. Wire endpoint: `POST /api/v2/user_msg/`. Independent of
+  `client.messaging` (which targets the inbox endpoint at
+  `/api/v2/messaging`); the two surfaces stay separate because the
+  endpoints serve different features on the wire (UDP frame vs. inbox
+  row) and share no storage. Client-side validation rejects malformed
+  hex before any network I/O.
+
+## [0.2.0] — 2026-05-13
 
 ### Added
 

{rtls_sdk-0.2.0 → rtls_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rtls-sdk
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python SDK for the RTLS REST API
 Project-URL: Homepage, https://github.com/rpplabs/rtls-sdk
 Project-URL: Documentation, https://github.com/rpplabs/rtls-sdk/tree/master/docs
@@ -21,6 +21,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic>=2.5
+Requires-Dist: websockets>=12.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.8; extra == 'dev'
 Requires-Dist: pytest-cov>=4.1; extra == 'dev'

{rtls_sdk-0.2.0 → rtls_sdk-0.3.0}/prompts/README.md

@@ -17,6 +17,12 @@ These prompts implement the design in `/Users/yzhbankov/rtls/rtls-sdk/DESIGN.md`
 | 13 | `13-m11-entity-docs.md` | M11 | Docs-only: reorganize user documentation around **entities**. New `docs/entities/` tree (one page per entity + catalog index) replaces the workflow-oriented guides. Answers "what can I do with X?" on one page. |
 | 14 | `14-m12-schema-audit-mac-fix.md` | M12 | Schema-correctness audit. Fix three real bugs caught by reading the server's Joi schemas directly: MAC format is bare 12-hex (not colon-separated); `tags.create` does not accept `mac_address` (server silently strips); add live MAC round-trip test as a regression gate. |
 | 15 | `15-m13-final-audit.md` | M13 | **Check-only.** Full ship-readiness audit across code quality, documentation site, internal consistency, wire-shape correctness, deep doc-quality analysis (with persona-driven proposals), and release artifacts. Produces `AUDIT.md` at the repo root with a verdict (ready / not ready), itemised blockers, repo-wide markdown link validation, and a prioritised list of documentation improvement proposals. Does not modify code or docs — a separate milestone applies any accepted fixes. |
+| 16 | `16-m14-e2e-live-test.md` | M14 | Full-stack live E2E test (`tests/live/test_m14_full_stack.py`). Builds the entity tree top-down, lists, updates each kind, deletes bottom-up. Fix-test-retry discipline — surfaces SDK bugs and fixes them in-flight. |
+| 17 | `17-m15-user-msg-websocket-research.md` | M15 | **Research-only.** Investigates the server-side `user_msg` REST endpoint and the JSON-RPC WebSocket protocol (subscriptions-manager). Produces `prompts/17-m15-research.md` with wire shapes, channel inventory, discrepancies, and concrete SDK extension signatures. |
+| 18 | `18-m16-user-msg-rest.md` | M16 | `messaging.send_to_tag(tag_uid, hex)` — POST `/api/v2/user_msg/` sends a hex payload to a tag's badge over the WIN gateway. Unit + integration + live test. |
+| 19 | `19-m17-ws-scaffold.md` | M17 | WebSocket sub-client `client.stream`: connect, list channels, subscribe / unsubscribe, blocking-iterator over `RawChannelMessage`, heartbeat passthrough, reconnect with backoff. Dependency: `websockets`. |
+| 20 | `20-m18-ws-typed-models.md` | M18 | Typed channel models (`PositionMessage`, `AlarmMessage`, `NotifyMessage`, `ZoneEventMessage`, `SensorMessage`, `OtaMessage`, `ParamPMessage`, `UserMsgMessage`) + discriminated-union decode dispatch + `include_heartbeats` flag (default off). |
+| 21 | `21-m19-ws-live-gate.md` | M19 | End-to-end live gate: REST `send_to_tag` → WS `user_msg` notify round-trip. Five-consecutive-pass stability requirement. |
 
 ## Inputs each prompt reads
 

{rtls_sdk-0.2.0 → rtls_sdk-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rtls-sdk"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python SDK for the RTLS REST API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -24,6 +24,7 @@ classifiers = [
 dependencies = [
     "httpx>=0.27",
     "pydantic>=2.5",
+    "websockets>=12.0",
 ]
 
 [project.optional-dependencies]

{rtls_sdk-0.2.0 → rtls_sdk-0.3.0}/src/rtls_sdk/__init__.py

@@ -28,6 +28,9 @@ from .errors import (
     RtlsError,
     ServerError,
     ValidationError,
+    WsAuthError,
+    WsError,
+    WsProtocolError,
 )
 from .models import (
     Alarm,
@@ -66,10 +69,39 @@ from .models import (
     Zone,
     ZoneEvent,
 )
+from .models.ws import (
+    AlarmMessage,
+    NotifyMessage,
+    OtaMessage,
+    ParamPMessage,
+    PositionMessage,
+    SensorMessage,
+    UserMsgMessage,
+    WsChannelEnvelope,
+    WsChannelMessage,
+    ZoneEventMessage,
+)
+from .resources import UserMessagesAPI, WsAPI
+from .resources.ws import WsSession
 
 __all__ = [  # noqa: RUF022 — grouped logically, not alphabetically
     # Client
     "RtlsClient",
+    # Resource sub-clients
+    "UserMessagesAPI",
+    "WsAPI",
+    # WebSocket types
+    "AlarmMessage",
+    "NotifyMessage",
+    "OtaMessage",
+    "ParamPMessage",
+    "PositionMessage",
+    "SensorMessage",
+    "UserMsgMessage",
+    "WsChannelEnvelope",
+    "WsChannelMessage",
+    "WsSession",
+    "ZoneEventMessage",
     # Errors
     "AuthenticationError",
     "Conflict",
@@ -84,6 +116,9 @@ __all__ = [  # noqa: RUF022 — grouped logically, not alphabetically
     "RtlsError",
     "ServerError",
     "ValidationError",
+    "WsAuthError",
+    "WsError",
+    "WsProtocolError",
     # Models
     "Alarm",
     "Anchor",

{rtls_sdk-0.2.0 → rtls_sdk-0.3.0}/src/rtls_sdk/_client.py

@@ -39,7 +39,9 @@ from .resources import (
     SubscribersAPI,
     SystemAPI,
     TagsAPI,
+    UserMessagesAPI,
     UsersAPI,
+    WsAPI,
     ZonesAPI,
 )
 
@@ -178,6 +180,8 @@ class RtlsClient:
         self.system = SystemAPI(self)
         self.auth = AuthAPI(self)
         self.messaging = MessagingAPI(self)
+        self.user_messages = UserMessagesAPI(self)
+        self.ws = WsAPI(self)
         self.logger = LoggerAPI(self)
         self.context = ContextAPI(self)
 

rtls_sdk-0.3.0/src/rtls_sdk/_ws.py

@@ -0,0 +1,390 @@
+"""Internal WebSocket session machinery for :class:`WsAPI`.
+
+The public surface lives in :mod:`rtls_sdk.resources.ws`; this module
+hosts the JSON-RPC 2.0 client, reader-thread loop, and bounded queue
+iterator. M18 dispatches ``params.subscription`` to typed pydantic
+models in :mod:`rtls_sdk.models.ws`; the fallback
+:class:`WsChannelMessage` is re-exported from that sub-package and
+remains the public name for unknown / un-modelled channels. Sibling
+streaming transports (MQTT, Kafka) would live in their own
+``_mqtt.py`` / ``_kafka.py`` modules with their own session types —
+this module is WS-specific.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import queue
+import threading
+from collections.abc import Iterator
+from types import TracebackType
+from typing import Any
+
+import websockets.exceptions
+from websockets.sync.client import ClientConnection
+from websockets.sync.client import connect as ws_connect
+
+from ._auth import _AuthState
+from .errors import WsAuthError, WsError
+from .models.ws import WsChannelEnvelope, WsChannelMessage, decode_notify
+
+_log = logging.getLogger("rtls_sdk.ws")
+
+
+def _close_code(exc: websockets.exceptions.ConnectionClosed) -> int | None:
+    """Close code from the received close frame; ``None`` if none received."""
+    rcvd = exc.rcvd
+    return None if rcvd is None else rcvd.code
+
+
+_SENTINEL_CLOSED: object = object()
+_SENTINEL_AUTH_FAIL: object = object()
+_SENTINEL_RECONNECT_EXHAUSTED: object = object()
+
+# Reconnect backoff. Once exhausted the session surfaces ``WsError``.
+_BACKOFF_SECONDS: tuple[float, ...] = (1, 2, 4, 8, 15, 30, 30, 30)
+
+# Close codes the server may emit on auth rejection: 1008 policy
+# violation + 4001 / 4003 application-range codes.
+_AUTH_CLOSE_CODES: frozenset[int] = frozenset({1008, 4001, 4003})
+
+
+class _WsSession:
+    """JSON-RPC WS subscription session backing ``WsAPI.subscribe``.
+
+    The reader runs on a daemon thread and pushes messages into a
+    bounded queue; iteration pops them off. Backpressure drops the
+    *oldest* message, bumps :attr:`messages_dropped`, and logs once
+    per 100 drops.
+    """
+
+    channels: tuple[str, ...]
+    project_uid: str
+    messages_dropped: int
+
+    def __init__(
+        self,
+        *,
+        ws_url: str,
+        channels: list[str],
+        auth_state: _AuthState,
+        project_uid: str,
+        reconnect: bool,
+        queue_max: int,
+        include_heartbeats: bool = False,
+    ) -> None:
+        self._ws_url = ws_url
+        self._channels: list[str] = list(channels)
+        self._auth_state = auth_state
+        self.project_uid = project_uid
+        self._reconnect = reconnect
+        self._include_heartbeats = include_heartbeats
+        self._queue: queue.Queue[Any] = queue.Queue(maxsize=queue_max)
+        self._lock = threading.RLock()
+        self._shutdown = threading.Event()
+        self._ws: ClientConnection | None = None
+        self._reader_thread: threading.Thread | None = None
+        self._id_lock = threading.Lock()
+        self._next_id_value = 1
+        self.messages_dropped = 0
+
+    @property
+    def channels_tuple(self) -> tuple[str, ...]:
+        with self._lock:
+            return tuple(self._channels)
+
+    # -- lifecycle --------------------------------------------------------
+
+    def _start(self) -> None:
+        """Dial, subscribe synchronously, spin up the reader thread."""
+        ws = self._dial_and_subscribe(self._channels)
+        with self._lock:
+            self._ws = ws
+        thread = threading.Thread(target=self._reader_loop, name="rtls-sdk-ws-reader", daemon=True)
+        self._reader_thread = thread
+        thread.start()
+
+    def __enter__(self) -> _WsSession:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Best-effort unsubscribe, close the socket, wake the iterator."""
+        if self._shutdown.is_set():
+            return
+        self._shutdown.set()
+        with self._lock:
+            ws = self._ws
+            channels = list(self._channels)
+        if ws is not None:
+            if channels:
+                with contextlib.suppress(Exception):
+                    ws.send(json.dumps(self._make_payload("delete", channels)))
+            with contextlib.suppress(Exception):
+                ws.close()
+        with contextlib.suppress(queue.Full):
+            self._queue.put_nowait(_SENTINEL_CLOSED)
+
+    # -- iteration --------------------------------------------------------
+
+    def __iter__(self) -> Iterator[WsChannelEnvelope]:
+        while True:
+            item = self._queue.get()
+            if item is _SENTINEL_CLOSED:
+                return
+            if item is _SENTINEL_AUTH_FAIL:
+                raise WsAuthError("WS server rejected the credentials on subscribe")
+            if item is _SENTINEL_RECONNECT_EXHAUSTED:
+                raise WsError("reconnect attempts exhausted; giving up")
+            assert isinstance(item, WsChannelEnvelope)
+            yield item
+
+    # -- channel-set mutation --------------------------------------------
+
+    def add_channels(self, channels: list[str]) -> None:
+        """Send ``add`` for new channels and merge them into the session set."""
+        with self._lock:
+            ws = self._ws
+            if ws is None:
+                raise WsError("session is not connected")
+            new = [c for c in channels if c not in self._channels]
+            if not new:
+                return
+            ws.send(json.dumps(self._make_payload("add", new)))
+            self._channels.extend(new)
+
+    def remove_channels(self, channels: list[str]) -> None:
+        """Send ``delete`` for the given channels and drop them from the set."""
+        with self._lock:
+            ws = self._ws
+            if ws is None:
+                raise WsError("session is not connected")
+            to_remove = [c for c in channels if c in self._channels]
+            if not to_remove:
+                return
+            ws.send(json.dumps(self._make_payload("delete", to_remove)))
+            self._channels = [c for c in self._channels if c not in to_remove]
+
+    # -- internals --------------------------------------------------------
+
+    def _next_id(self) -> int:
+        with self._id_lock:
+            value = self._next_id_value
+            self._next_id_value += 1
+            return value
+
+    def _make_payload(self, method: str, channels: list[str]) -> dict[str, Any]:
+        """Build an ``add`` or ``delete`` JSON-RPC request body."""
+        return {
+            "jsonrpc": "2.0",
+            "method": method,
+            "params": {
+                "data": channels,
+                "entity": "subscriptions",
+                "userEmail": self._auth_state.email or "",
+                "authToken": self._auth_state.token or "",
+                "project_uid": self.project_uid,
+            },
+            "id": self._next_id(),
+        }
+
+    def _dial_and_subscribe(self, channels: list[str]) -> ClientConnection:
+        """Open the WS, send ``add``, wait for the ack, return the socket."""
+        ws = ws_connect(self._ws_url)
+        try:
+            payload = self._make_payload("add", channels)
+            sub_id = payload["id"]
+            ws.send(json.dumps(payload))
+            self._await_subscribe_ack(ws, sub_id)
+        except BaseException:
+            with contextlib.suppress(Exception):
+                ws.close()
+            raise
+        return ws
+
+    def _await_subscribe_ack(self, ws: ClientConnection, sub_id: int) -> None:
+        """Read frames until the ``add`` ack arrives; raise on auth fail.
+
+        Buffers unrelated ``notify`` frames onto the queue so they aren't
+        lost. The first frame matching ``id == sub_id`` is the ack;
+        ``result: [<channels>]`` is success, anything else is auth fail.
+        """
+        while True:
+            try:
+                frame = ws.recv()
+            except websockets.exceptions.ConnectionClosed as exc:
+                code = _close_code(exc)
+                # No close frame OR auth-flavoured code: treat as auth
+                # rejection per the M16 probe.
+                if code is None or code in _AUTH_CLOSE_CODES or code == 1005:
+                    raise WsAuthError(f"WS closed with code {code} before subscribe ack") from exc
+                raise WsError(f"WS closed with code {code} before subscribe ack") from exc
+
+            if isinstance(frame, bytes):
+                continue
+
+            stripped = frame.strip()
+            # Service-code shape on auth failure (JSON-stringified Error).
+            if stripped == "{}":
+                raise WsAuthError("WS server returned an empty error envelope on subscribe")
+
+            try:
+                data = json.loads(frame)
+            except json.JSONDecodeError:
+                _log.warning("dropping non-JSON WS frame during subscribe")
+                continue
+            if not isinstance(data, dict):
+                continue
+
+            # HTTP-style auth-error envelope (live server primary branch).
+            if self._looks_like_auth_envelope(data):
+                raise WsAuthError(f"WS server returned auth-error envelope: {data!r}")
+            if data.get("id") == sub_id and "error" in data:
+                raise WsAuthError(f"WS server returned JSON-RPC error: {data['error']!r}")
+            if data.get("id") == sub_id:
+                result = data.get("result")
+                if isinstance(result, list) and len(result) > 0:
+                    return
+                # ``result: []`` is the QA-test auth-fail shape.
+                raise WsAuthError("WS server returned empty result on subscribe")
+            # Anything else: an early notify. Buffer it.
+            self._handle_notify_frame(data)
+
+    @staticmethod
+    def _looks_like_auth_envelope(data: dict[str, Any]) -> bool:
+        """Match the live server's HTTP-style auth-error frame."""
+        if data.get("httpCode") == 401:
+            return True
+        err_code = data.get("errorCode")
+        return isinstance(err_code, str) and "AUTH" in err_code.upper()
+
+    def _handle_notify_frame(self, data: dict[str, Any]) -> None:
+        """Route a parsed JSON frame to the iterator if it's a ``notify``."""
+        if data.get("method") != "notify":
+            return
+        params = data.get("params")
+        if not isinstance(params, dict):
+            return
+        channel = params.get("subscription")
+        body = params.get("data")
+        if not isinstance(channel, str) or not isinstance(body, dict):
+            return
+        # Heartbeat filter (M18): the ``notify`` channel may carry frames
+        # with ``action == "HB"``; suppress by default and let opt-in
+        # callers see them. Filter at the raw level rather than after
+        # decode so an HB frame without ``project_uid`` (server emits HB
+        # without project scoping) doesn't fall through to
+        # ``WsChannelMessage`` and then need a second-pass type check.
+        if not self._include_heartbeats and channel == "notify" and body.get("action") == "HB":
+            return
+        self._push(decode_notify(channel, body))
+
+    def _push(self, msg: WsChannelEnvelope) -> None:
+        """Enqueue a message, dropping the oldest on overflow."""
+        try:
+            self._queue.put_nowait(msg)
+            return
+        except queue.Full:
+            pass
+        with contextlib.suppress(queue.Empty):
+            self._queue.get_nowait()
+        with contextlib.suppress(queue.Full):
+            self._queue.put_nowait(msg)
+        self.messages_dropped += 1
+        if self.messages_dropped % 100 == 1:
+            _log.warning(
+                "stream queue full; dropped %d messages total",
+                self.messages_dropped,
+            )
+
+    def _push_sentinel(self, sentinel: object) -> None:
+        """Push a sentinel, evicting the oldest message if necessary."""
+        try:
+            self._queue.put_nowait(sentinel)
+            return
+        except queue.Full:
+            pass
+        with contextlib.suppress(queue.Empty):
+            self._queue.get_nowait()
+        with contextlib.suppress(queue.Full):
+            self._queue.put_nowait(sentinel)
+
+    def _reader_loop(self) -> None:
+        """Daemon reader: pull frames, route notifies, reconnect on close."""
+        while not self._shutdown.is_set():
+            with self._lock:
+                ws = self._ws
+            if ws is None:
+                self._push_sentinel(_SENTINEL_CLOSED)
+                return
+            try:
+                frame = ws.recv()
+            except websockets.exceptions.ConnectionClosed as exc:
+                if self._shutdown.is_set():
+                    self._push_sentinel(_SENTINEL_CLOSED)
+                    return
+                code = _close_code(exc)
+                if code in _AUTH_CLOSE_CODES:
+                    self._push_sentinel(_SENTINEL_AUTH_FAIL)
+                    return
+                if not self._reconnect:
+                    _log.info("WS closed (code=%s); reconnect disabled", code)
+                    self._push_sentinel(_SENTINEL_CLOSED)
+                    return
+                if not self._try_reconnect():
+                    return
+                continue
+            except Exception:
+                _log.exception("unexpected error in reader loop")
+                self._push_sentinel(_SENTINEL_CLOSED)
+                return
+
+            if isinstance(frame, bytes):
+                continue
+            try:
+                data = json.loads(frame)
+            except json.JSONDecodeError:
+                _log.warning("dropping non-JSON WS frame")
+                continue
+            if isinstance(data, dict):
+                self._handle_notify_frame(data)
+
+    def _try_reconnect(self) -> bool:
+        """Re-dial with exponential backoff and re-subscribe.
+
+        Returns True if reconnected. Returns False on shutdown, auth
+        failure, or exhaustion — the appropriate sentinel is already
+        on the queue in each terminal case.
+        """
+        for attempt, delay in enumerate(_BACKOFF_SECONDS):
+            if self._shutdown.wait(delay):
+                self._push_sentinel(_SENTINEL_CLOSED)
+                return False
+            with self._lock:
+                channels = list(self._channels)
+            try:
+                ws = self._dial_and_subscribe(channels)
+            except WsAuthError:
+                _log.info("auth rejected on reconnect; giving up")
+                self._push_sentinel(_SENTINEL_AUTH_FAIL)
+                return False
+            except Exception as exc:
+                _log.warning("reconnect attempt %d failed: %s", attempt + 1, exc)
+                continue
+            with self._lock:
+                self._ws = ws
+            return True
+        self._push_sentinel(_SENTINEL_RECONNECT_EXHAUSTED)
+        return False
+
+
+__all__ = ["WsChannelEnvelope", "WsChannelMessage", "_WsSession"]

{rtls_sdk-0.2.0 → rtls_sdk-0.3.0}/src/rtls_sdk/errors.py

@@ -155,6 +155,36 @@ class PartialFailureError(RtlsError):
         self.partial_result: dict[str, Any] = partial_result or {}
 
 
+class WsError(RtlsError):
+    """Base class for WebSocket surface errors.
+
+    Raised from :class:`WsAPI` and the iterator returned by
+    :meth:`WsAPI.subscribe`. Subclasses pin specific failure modes;
+    catch ``WsError`` to handle any WS-side failure uniformly. Future
+    streaming protocols (MQTT, Kafka) would carry their own error
+    hierarchies; this base intentionally does not generalize beyond WS.
+    """
+
+
+class WsAuthError(WsError):
+    """The WS server rejected the credentials on subscribe.
+
+    Surfaced from the session iterator the first time the server's
+    response (or close behavior) indicates the token / email pair was
+    not accepted on ``add``. Reconnection stops on auth failure.
+    """
+
+
+class WsProtocolError(WsError):
+    """The WS server returned a malformed or unexpected JSON-RPC frame.
+
+    Reserved for fatal frame-shape violations. The session's reader
+    tolerates an isolated bad frame (logged + skipped); a
+    ``WsProtocolError`` indicates something the session cannot
+    recover from.
+    """
+
+
 class ReportError(RtlsError):
     """Base for report-specific failures."""
 
@@ -233,6 +263,9 @@ __all__ = [
     "RtlsError",
     "ServerError",
     "ValidationError",
+    "WsAuthError",
+    "WsError",
+    "WsProtocolError",
     "exception_for_status",
     "parse_error_envelope",
 ]