rtls-sdk 0.2.0__py3-none-any.whl

rtls_sdk/resources/system.py

@@ -0,0 +1,125 @@
+"""System / host resource sub-client.
+
+These endpoints expose server-health diagnostics. They share an
+``RtlsClient`` with the rest of the SDK but use simple object responses
+(no envelope wrapping).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..compounds import system as _compound
+from ..models import Connection, Host, SystemHealth, Uptime, Version, WsHost
+from ._base import ResourceAPI
+
+
+class SystemAPI(ResourceAPI):
+    """Host info, uptime, connections, and server version metadata.
+
+    The aggregated :meth:`health` view (fan-out across host + uptime +
+    connections) is implemented in M5; M2 only exposes the individual
+    accessors.
+    """
+
+    def host(self) -> Host:
+        """Return the server's hostname + status snapshot."""
+        response = self._get("/api/v2/host")
+        return Host.from_wire(_as_dict(response.json()))
+
+    def uptime(self) -> list[Uptime]:
+        """Return per-service uptime rows."""
+        response = self._get("/api/v2/host/uptime")
+        return [Uptime.from_wire(_as_dict(item)) for item in _as_list(response.json())]
+
+    def connections(self) -> list[Connection]:
+        """Return active server connections."""
+        response = self._get("/api/v2/host/connections")
+        return [Connection.from_wire(_as_dict(item)) for item in _as_list(response.json())]
+
+    def version(self) -> Version:
+        """Return server version info from ``GET /version``.
+
+        Note: ``/version`` is one of the few endpoints not under the
+        ``/api/v2/`` prefix.
+        """
+        response = self._get("/version")
+        return Version.from_wire(_as_dict(response.json()))
+
+    def beta_version(self) -> Version:
+        """Return the beta-channel version info."""
+        response = self._get("/api/v2/beta/version")
+        return Version.from_wire(_as_dict(response.json()))
+
+    def health(self) -> SystemHealth:
+        """Aggregate host + uptime + connections in one snapshot.
+
+        Each sub-call is independent: a failure on one sets that field
+        to ``None`` and records the exception in
+        ``SystemHealth.errors``, leaving the rest of the snapshot
+        intact. ``partial=True`` when any sub-call failed.
+
+        Sequential in v1 (sync SDK); a v2 async surface would fan these
+        out in parallel.
+        """
+        return _compound.collect_system_health(self._client)
+
+    def ws_host(self) -> WsHost:
+        """Return the WebSocket hostname the server expects clients to dial.
+
+        This is the single REST hop needed before opening a WS connection
+        (deferred to v2).
+        """
+        response = self._get("/api/v2/wshost/")
+        return WsHost.from_wire(_as_dict(response.json()))
+
+    def helper_link(self) -> str | None:
+        """URL of the help portal (deployment-specific).
+
+        Returned by ``GET /info/helper``. Body shape is loose across
+        deployments; this method surfaces whichever URL-shaped string
+        the server returned, or ``None`` if absent. Used by
+        :meth:`ContextAPI.load` (M6).
+        """
+        response = self._get("/api/v2/info/helper")
+        return _extract_url(response.json())
+
+    def monitor_link(self) -> str | None:
+        """URL of the site-monitor portal (deployment-specific).
+
+        Returned by ``GET /info/site_monitor``. Same loose-shape
+        conventions as :meth:`helper_link`.
+        """
+        response = self._get("/api/v2/info/site_monitor")
+        return _extract_url(response.json())
+
+
+def _extract_url(payload: Any) -> str | None:
+    """Pick a URL-shaped string out of a loose info-endpoint payload."""
+    if isinstance(payload, str):
+        return payload
+    if isinstance(payload, dict):
+        for key in ("url", "link", "href", "value", "data"):
+            value = payload.get(key)
+            if isinstance(value, str) and value:
+                return value
+    return None
+
+
+def _as_dict(payload: Any) -> dict[str, Any]:
+    if isinstance(payload, dict):
+        return payload
+    return {"data": payload}
+
+
+def _as_list(payload: Any) -> list[Any]:
+    if isinstance(payload, list):
+        return list(payload)
+    if isinstance(payload, dict):
+        for key in ("uptime", "connections", "data"):
+            if key in payload and isinstance(payload[key], list):
+                return list(payload[key])
+    return []
+
+
+__all__ = ["SystemAPI"]

rtls_sdk/resources/tags.py

@@ -0,0 +1,370 @@
+"""Trackable / tag resource sub-client."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from .._envelope import unwrap_resource, unwrap_resource_single
+from .._time import to_epoch_ms
+from ..compounds import tags as _compound
+from ..compounds.tags import UNSET, _Unset
+from ..errors import NotFound
+from ..models import BulkResult, Position, Tag, TagTemplate
+from ._base import ResourceAPI
+
+
+class TagsAPI(ResourceAPI):
+    """List, get, and (later) mutate trackables.
+
+    The wire name for trackables is ``trackable_objects`` — exposed as
+    ``tags`` here because "tag" is what operators actually call them.
+
+    Note on method order: ``list`` is defined last in this class so that
+    mypy resolves ``list[Tag]`` annotations in other methods to the
+    builtin ``list`` and not to ``TagsAPI.list``. (Python class-scope
+    shadowing limitation, even with PEP-563 deferred annotations.)
+    """
+
+    def get(self, uid: str) -> Tag:
+        """Fetch a single trackable by uid.
+
+        The server returns ``{trackableObjects: [t]}`` even for single
+        gets — a one-element list wrapper. The SDK unwraps it. An empty
+        wrapper (meaning the uid isn't valid) raises :class:`NotFound`.
+        """
+        response = self._get(f"/api/v2/trackable_objects/{uid}")
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "trackableObjects")
+        except ValueError as exc:
+            raise NotFound(
+                f"trackable {uid!r} not found",
+                status_code=response.status_code,
+                request_url=str(response.request.url),
+                request_method=response.request.method,
+            ) from exc
+        return Tag.from_wire(item)
+
+    def list_active_for_period(
+        self,
+        start: datetime,
+        end: datetime,
+        *,
+        sublocation_uid: str,
+    ) -> list[Tag]:
+        """Trackables active in ``[start, end]`` inside one sublocation.
+
+        Timestamps go on the wire as epoch milliseconds.
+        """
+        params = {
+            "sublocation_uid": sublocation_uid,
+            "from": str(to_epoch_ms(start, arg_name="start")),
+            "to": str(to_epoch_ms(end, arg_name="end")),
+        }
+        response = self._get("/api/v2/trackable_objects/active_for_period", params=params)
+        items = unwrap_resource(response.json(), "trackableObjects")
+        return [Tag.from_wire(item) for item in items]
+
+    def list_existed_for_period(self, start: datetime, end: datetime) -> list[Tag]:
+        """Trackables that existed at any point in ``[start, end]``."""
+        params = {
+            "from": str(to_epoch_ms(start, arg_name="start")),
+            "to": str(to_epoch_ms(end, arg_name="end")),
+        }
+        response = self._get("/api/v2/trackable_objects/existed_for_period", params=params)
+        items = unwrap_resource(response.json(), "trackableObjects")
+        return [Tag.from_wire(item) for item in items]
+
+    def list_templates(self) -> list[TagTemplate]:
+        """Return all tag-creation templates available on the server.
+
+        Server-side templates are pre-baked configurations operators reuse
+        when creating new trackables.
+        """
+        response = self._get("/api/v2/trackable_objects/templates")
+        payload = response.json()
+        # The wire envelope key is ``trackable_templates`` (snake_case)
+        # rather than the camelCase used by ``trackableObjects``.
+        items = unwrap_resource(payload, "trackable_templates")
+        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.
+        """
+        response = self._get(f"/api/v2/trackable_objects/position_from_state/{uid}")
+        payload = response.json()
+        if not isinstance(payload, dict):
+            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])
+        # Some deployments return the position object directly.
+        if "x" in payload or "ts" in payload:
+            return Position.from_wire(payload)
+        return None
+
+    def create_raw(self, name: str, **fields: Any) -> Tag:
+        """Create a tag (single REST call, no zone / group plumbing).
+
+        **Advanced.** Most users want :meth:`create` (added in M4) which
+        also handles attached-zone and group binding automatically.
+
+        Parameters
+        ----------
+        name
+            Required. The tag's name.
+        **fields
+            Any other field the server's ``createTrackObject`` schema
+            accepts: ``display_name``, ``description``, ``type``,
+            ``category``, ``position_update_interval``, ``self_zone_uid``,
+            ``buffer``, ``tag_config``, ``acc_config``, ``bt_config``,
+            ``sensor_config``, ``user_params``, ``custom_info``,
+            ``t2t_no_alarm_uid``. Unknown fields are stripped silently
+            by the server's Joi default.
+
+        Notes
+        -----
+        **Tags do NOT carry a `mac_address`.** The MAC belongs to a
+        :class:`Node` (the hardware), bound to a tag via an
+        :class:`Association` (`trackable_objects_associations`). Passing
+        ``mac_address=`` here is a silent no-op — the server drops it.
+        If your workflow is "I have a MAC and want a tag bound to it,"
+        call :meth:`NodesAPI.create` + :meth:`AssociationsAPI.create`
+        in sequence. A compound ``tags.create_with_node`` that wraps
+        the saga is planned for a future milestone.
+
+        Returns
+        -------
+        Tag
+            The created tag as returned by the server.
+        """
+        body: dict[str, Any] = {"name": name, **fields}
+        response = self._post("/api/v2/trackable_objects", json=body)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "trackableObjects")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Tag.from_wire(item)
+
+    def update_raw(self, uid: str, **fields: Any) -> Tag:
+        """Update a trackable (single REST call).
+
+        **Advanced.** Most users want :meth:`update` (added in M4) which
+        diff-applies zone/group changes alongside the field updates.
+        """
+        response = self._put(f"/api/v2/trackable_objects/{uid}", json=fields)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "trackableObjects")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Tag.from_wire(item)
+
+    def delete_raw(self, uid: str) -> None:
+        """Delete a trackable (single REST call, no zone-cascade).
+
+        **Advanced.** Most users want :meth:`delete` (added in M4) which
+        also deletes the trackable's attached zone if any.
+        """
+        self._delete(f"/api/v2/trackable_objects/{uid}")
+
+    def replace_groups(self, uid: str, group_uids: list[str], *, no_notify: bool = True) -> None:
+        """Replace the set of groups a trackable belongs to.
+
+        Two server paths exist:
+
+        - ``PUT /trackable_objects/{uid}/groups`` with a bare-array body
+          (per RESEARCH §5 quirk #15 and the JS reference client).
+        - ``PUT /trackable_objects/{uid}`` with ``{"groups": [...]}`` in
+          the body (the standard tag-update endpoint).
+
+        The live test server treats the dedicated ``/groups`` endpoint
+        as a silent no-op (returns 204, doesn't persist) — only the
+        tag-update path actually writes membership. The SDK uses the
+        tag-update path because it's the one that works.
+
+        ``no_notify`` is accepted for API stability but ignored on the
+        tag-update path; the server doesn't broadcast a group-change
+        event from there.
+        """
+        del no_notify  # kept for signature stability; no analog on the working path
+        self._put(f"/api/v2/trackable_objects/{uid}", json={"groups": group_uids})
+
+    def create(
+        self,
+        name: str,
+        *,
+        attached_zone: dict[str, Any] | None = None,
+        groups: list[str] | None = None,
+        **fields: Any,
+    ) -> Tag:
+        """Create a tag, optionally attaching a zone and group memberships.
+
+        One call collapses up to four REST round-trips (create tag,
+        create bound zone, replace groups, update tag with
+        ``self_zone_uid``). On any sub-step failure the SDK attempts to
+        roll back the created tag and zone; if a rollback fails, the
+        raised :class:`PartialFailureError` carries the orphaned uid in
+        its ``partial_result`` so the caller can clean up.
+
+        Step names (for ``PartialFailureError.failed_step``):
+        ``create_tag``, ``create_zone``, ``replace_groups``,
+        ``update_tag_with_zone_uid``.
+
+        Parameters
+        ----------
+        name
+            Required tag name.
+        attached_zone
+            Optional zone spec dict — ``shape``, geometry, etc. The SDK
+            stamps ``trackable_object_uid`` and ``dynamic=True`` onto
+            it automatically.
+        groups
+            Optional list of group uids the tag should belong to.
+        **fields
+            Other tag fields the ``createTrackObject`` schema accepts
+            (``display_name``, ``type``, ``category``, etc.). **Not
+            `mac_address`** — see Notes below.
+
+        Notes
+        -----
+        Tags do NOT carry a ``mac_address``. The MAC belongs to a
+        :class:`Node`, bound via an :class:`Association`. See the
+        Notes on :meth:`create_raw` for how to bind hardware to a tag.
+
+        Examples
+        --------
+        >>> tag = client.tags.create(
+        ...     name="Forklift 7",
+        ...     attached_zone={"shape": "circle", "geometry": {"radius": 3000}},
+        ...     groups=["g-fleet"],
+        ... )
+        """
+        return _compound.create_tag(
+            self._client,
+            name,
+            attached_zone=attached_zone,
+            groups=groups,
+            **fields,
+        )
+
+    def update(
+        self,
+        uid: str,
+        *,
+        attached_zone: dict[str, Any] | None | _Unset = UNSET,
+        groups: list[str] | None | _Unset = UNSET,
+        **fields: Any,
+    ) -> Tag:
+        """Diff-driven update of a tag's fields, attached zone, and groups.
+
+        ``attached_zone`` / ``groups`` accept three forms:
+
+        - default (``...`` — sentinel): leave unchanged.
+        - ``None``: remove (delete bound zone / clear groups).
+        - dict / list: set or replace.
+
+        Step names: ``load_current_tag``, ``delete_attached_zone``,
+        ``create_attached_zone``, ``update_attached_zone``,
+        ``replace_groups``, ``update_tag``.
+
+        Unlike :meth:`create`, partial updates cannot be unwound
+        cleanly. On failure the SDK raises :class:`PartialFailureError`
+        listing the ``completed_steps`` so the caller can reconcile.
+        """
+        return _compound.update_tag(
+            self._client,
+            uid,
+            attached_zone=attached_zone,
+            groups=groups,
+            **fields,
+        )
+
+    def delete(self, target: Tag | str | list[Tag | str]) -> BulkResult[None] | None:
+        """Delete one or many tags, cascading to attached zones.
+
+        - Single uid (``str``) or :class:`Tag`: returns ``None``, raises
+          :class:`PartialFailureError` on failure.
+        - List: returns :class:`BulkResult` with per-item errors; an
+          error on one row does NOT abort the others.
+
+        Passing :class:`Tag` instances skips the per-tag GET that would
+        otherwise be needed to discover ``self_zone_uid``.
+
+        Step names (single-target variant): ``load_tag``,
+        ``delete_attached_zone``, ``delete_tag``.
+        """
+        if isinstance(target, list):
+            return _compound.bulk_delete_tags(self._client, target)
+        _compound.delete_tag(self._client, target)
+        return None
+
+    def bulk_update(self, tag_uids: list[str], changes: dict[str, Any]) -> BulkResult[Tag]:
+        """Apply the same updates to many tags, continue-on-error.
+
+        Each tag is updated via :meth:`update` (so ``attached_zone`` and
+        ``groups`` inside ``changes`` get the same diff semantics as the
+        single-tag form). Failures land in ``BulkResult.failures``.
+        """
+        return _compound.bulk_update_tags(self._client, tag_uids, dict(changes))
+
+    def list_active_in_period(
+        self,
+        sublocation_uid: str,
+        start: datetime,
+        end: datetime,
+    ) -> list[Tag]:
+        """Tags active in ``[start, end]`` inside one sublocation.
+
+        Inner-joins ``trackable_objects/active_for_period`` with the
+        active-association list — the union the JS reference client
+        manually composes (RESEARCH §4 "Load trackables with active
+        associations for a period").
+        """
+        return _compound.list_active_in_period(self._client, sublocation_uid, start, end)
+
+    def list(self, *, include_removed: bool = False, company_scope: bool = False) -> list[Tag]:
+        """Return active trackables in the current project scope.
+
+        Parameters
+        ----------
+        include_removed
+            Include soft-deleted trackables. Defaults to ``False``.
+        company_scope
+            If ``True``, list across the whole company instead of the
+            currently-scoped project.
+
+        Returns
+        -------
+        list[Tag]
+            Possibly empty.
+
+        Examples
+        --------
+        >>> tags = client.tags.list()
+        >>> [t.name for t in tags]
+        ['Forklift 7', 'Pallet jack 12']
+        """
+        if company_scope:
+            path = "/api/v2/trackable_objects/all"
+            params = {"include_removed": "true"} if include_removed else None
+        elif include_removed:
+            path = "/api/v2/trackable_objects/all"
+            params = {"include_removed": "true"}
+        else:
+            path = "/api/v2/trackable_objects"
+            params = None
+
+        response = self._get(path, params=params)
+        payload = response.json()
+        items = unwrap_resource(payload, "trackableObjects")
+        return [Tag.from_wire(item) for item in items]
+
+
+__all__ = ["TagsAPI"]