rtls-sdk 0.6.2__tar.gz → 0.6.3__tar.gz

{rtls_sdk-0.6.2 → rtls_sdk-0.6.3}/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.6.3] — 2026-09-10
+
+### Fixed
+
+- `tags.last_position()` now parses the body the server actually sends.
+  `GET /trackable_objects/position_from_state/{uid}` nests the coordinates
+  under `position` and spells the area `sublocation_uid`; `Position` knew
+  only the embedded (`sl_uid`/`dev_id`/`mac`) and standalone
+  (`area_uid`/`trackable_uid`/`mac_address`) forms, so it produced a
+  `Position` with `x`/`y`/`z` all `None` — and, because models allow extra
+  keys, did so silently. Callers polling "has a fix been computed yet?" read
+  that as "no position" while the server was serving one. `Position` now
+  lifts the nested `position` object and maps `sublocation_uid` → `area_uid`
+  (explicit top-level values still win).
+- `tags.last_position()` returns `None` instead of an all-`None` `Position`
+  when the body carries no coordinates — including `{}`, which the route
+  returns when its state worker is unreachable.
+
+### Notes
+
+- `position_from_state` sends **no** timestamp, MAC or tag identity, so
+  `pos.ts` / `pos.mac_address` / `pos.tag_uid` are always `None` on a fix
+  from this call. It cannot answer "has the fix advanced?"; read the tag
+  object's own `position` property or the `pos` WebSocket channel for that.
+  Documented on the method and in `docs/entities/tags.md`.
+
 ## [0.6.2] — 2026-07-09
 
 ### Changed

{rtls_sdk-0.6.2 → rtls_sdk-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: rtls-sdk
-Version: 0.6.2
+Version: 0.6.3
 Summary: Python SDK for the RTLS REST API
 Project-URL: Documentation, https://rtls-sdk.pages.dev
 Author: RTLS SDK Maintainers

{rtls_sdk-0.6.2 → rtls_sdk-0.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rtls-sdk"
-version = "0.6.2"
+version = "0.6.3"
 description = "Python SDK for the RTLS REST API"
 readme = "README.md"
 requires-python = ">=3.10"

{rtls_sdk-0.6.2 → rtls_sdk-0.6.3}/src/rtls_sdk/models/position.py

@@ -1,9 +1,18 @@
 """Position model with embedded-vs-standalone normalization.
 
-The server emits position data under two wire formats (RESEARCH §3):
+The server emits position data under three wire formats:
 
 - **Embedded** inside a tag: ``sl_uid``, ``sl_id``, ``dev_id``, ``mac``, ``ts``.
 - **Standalone** under ``/positions``: ``area_uid``, ``trackable_uid``, ``mac_address``, ``ts``.
+- **State**, from ``/trackable_objects/position_from_state/{uid}``: the
+  coordinates are NESTED under ``position``, the area key is
+  ``sublocation_uid``, and there is **no** ``ts``/``mac``/tag identity at all::
+
+      {"position": {"x": 3800, "y": 3800, "z": 1000},
+       "sublocation_uid": "Izuz…", "location_uid": "TR2D…"}
+
+  (rtls-frontend ``routes/trackable_objects/utils.js::getTrackablePositionFromState``;
+  documented in its ``docs/internal/api/trackable_objects.md``.)
 
 The SDK normalizes both into one canonical shape with the SDK-canonical
 field names. Callers see ``area_uid`` / ``tag_uid``, never the wire aliases.
@@ -24,10 +33,17 @@ class Position(_BaseModel):
     """A position fix for a tag.
 
     Field names are SDK-canonical. Wire-format aliases ``sl_uid`` /
-    ``dev_id`` / ``mac`` (embedded) and ``trackable_uid`` (standalone) are
-    rewritten at parse time so consumers don't need to know which endpoint
-    produced the data. ``tag_uid`` is the SDK-canonical name for the
-    server's ``trackable_uid`` / ``dev_id``.
+    ``dev_id`` / ``mac`` (embedded), ``trackable_uid`` (standalone) and the
+    nested ``position`` / ``sublocation_uid`` (state) are rewritten at parse
+    time so consumers don't need to know which endpoint produced the data.
+    ``tag_uid`` is the SDK-canonical name for the server's
+    ``trackable_uid`` / ``dev_id``.
+
+    A state-form fix carries coordinates and an area, and nothing else: its
+    ``ts``, ``mac_address`` and ``tag_uid`` are ``None`` because that endpoint
+    does not send them. Do not use it to reason about fix recency — read the
+    trackable object's own ``position`` property, or the ``pos`` WebSocket
+    channel, when you need a timestamp.
     """
 
     area_uid: str | None = None
@@ -48,9 +64,23 @@ class Position(_BaseModel):
 
         out = dict(data)
 
+        # State form: lift the nested `position` object up to the top level.
+        # Top-level coordinates win — only the state endpoint nests them, and
+        # a payload carrying both is not something any server sends today.
+        nested = out.get("position")
+        if isinstance(nested, dict):
+            for axis in ("x", "y", "z"):
+                if out.get(axis) is None and nested.get(axis) is not None:
+                    out[axis] = nested[axis]
+            out.pop("position", None)
+
         # Wire-form → SDK-canonical renames.
         if "area_uid" not in out and "sl_uid" in out:
             out["area_uid"] = out["sl_uid"]
+        # State form spells the area `sublocation_uid` (the server's own wire
+        # key, kept verbatim by this endpoint).
+        if out.get("area_uid") is None and out.get("sublocation_uid") is not None:
+            out["area_uid"] = out["sublocation_uid"]
         # tag_uid <- standalone wire `trackable_uid`, else embedded `dev_id`.
         if out.get("tag_uid") is None:
             if out.get("trackable_uid") is not None:

{rtls_sdk-0.6.2 → rtls_sdk-0.6.3}/src/rtls_sdk/resources/tags.py

@@ -14,6 +14,18 @@ from ..models import BulkResult, Position, Tag, TagTemplate
 from ._base import ResourceAPI
 
 
+def _position_or_none(wire: dict[str, Any]) -> Position | None:
+    """Parse a position payload, collapsing a coordinate-less result to ``None``.
+
+    A body with no x, y or z carries no fix — whatever else it holds — and the
+    caller asked "where is this tag?", so ``None`` is the honest answer.
+    """
+    position = Position.from_wire(wire)
+    if position.x is None and position.y is None and position.z is None:
+        return None
+    return position
+
+
 class TagsAPI(ResourceAPI):
     """List, get, and (later) mutate trackables.
 
@@ -92,11 +104,31 @@ class TagsAPI(ResourceAPI):
         return [TagTemplate.from_wire(item) for item in items]
 
     def last_position(self, uid: str) -> Position | None:
-        """Return the last cached position for a trackable, if known.
-
-        The response envelope is ``{trackablePositionFromState}`` — a
-        single position object, not a list (RESEARCH §3). Returns
-        ``None`` if the server has no cached position.
+        """Return the last cached ("state") position for a tag, if known.
+
+        The response envelope is ``{trackablePositionFromState}`` — a single
+        position object, not a list — and the server sends ``null`` there when
+        it holds no fix. The object itself nests its coordinates::
+
+            {"trackablePositionFromState": {
+               "position": {"x": 3800, "y": 3800, "z": 1000},
+               "sublocation_uid": "Izuz…", "location_uid": "TR2D…"}}
+
+        :class:`~rtls_sdk.models.position.Position` flattens that on parse.
+
+        .. note::
+           This endpoint returns **no timestamp**, MAC or tag identity — only
+           coordinates and the area. ``pos.ts`` is therefore always ``None``
+           here, so this is not the call to use for "has the fix advanced?".
+           Read the tag object's own ``position`` property, or the ``pos``
+           WebSocket channel, for a timestamped fix.
+
+        Returns ``None`` when the server holds no position — including the
+        empty-object body (``{"trackablePositionFromState": {}}``) it sends
+        when the state worker is unreachable, and any body that yields no
+        coordinates at all. Never returns a ``Position`` with nothing in it:
+        an all-``None`` object reads as a real fix at the call site and is how
+        a nested-payload regression stayed invisible before.
         """
         response = self._get(f"/api/v2/trackable_objects/position_from_state/{uid}")
         payload = response.json()
@@ -104,10 +136,10 @@ class TagsAPI(ResourceAPI):
             return None
         for key in ("trackablePositionFromState", "trackable_position_from_state"):
             if key in payload and isinstance(payload[key], dict):
-                return Position.from_wire(payload[key])
+                return _position_or_none(payload[key])
         # Some deployments return the position object directly.
-        if "x" in payload or "ts" in payload:
-            return Position.from_wire(payload)
+        if "x" in payload or "position" in payload or "ts" in payload:
+            return _position_or_none(payload)
         return None
 
     def create_raw(self, name: str, **fields: Any) -> Tag: