rtls-sdk 0.2.0__py3-none-any.whl

rtls_sdk/resources/events.py

@@ -0,0 +1,149 @@
+"""Events resource sub-client.
+
+M2 ships a single-page reader for zone events; M7 adds the lazy
+iterator surface (``iter_pws`` / ``pages``) for PWS / external_events
+via the body-URL paginator.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from datetime import datetime
+from typing import Any
+
+from .._envelope import unwrap_resource
+from .._pagination import BodyUrlPaginator, Page
+from .._query import pack_array_param
+from .._time import to_epoch_ms
+from ..models import PwsEvent, ZoneEvent
+from ._base import ResourceAPI
+
+
+class EventsAPI(ResourceAPI):
+    """Read zone events and external (PWS) events.
+
+    ``iter_pws`` and ``pages`` are lazy: HTTP requests fire only when
+    the iterator advances past the current page. This keeps large
+    windows out of memory and lets callers ``break`` early.
+    """
+
+    def list_zone_events(
+        self,
+        start: datetime,
+        end: datetime,
+        *,
+        area_uids: list[str],
+        type: str = "information",
+    ) -> list[ZoneEvent]:
+        """Return zone events for ``area_uids`` in ``[start, end]``.
+
+        The server returns a paginated response; this method reads only
+        the first page. Callers needing the full set should use the
+        iterator surface.
+        """
+        params: list[tuple[str, str]] = [
+            ("from", str(to_epoch_ms(start, arg_name="start"))),
+            ("to", str(to_epoch_ms(end, arg_name="end"))),
+            ("type", type),
+            ("format", "json"),
+        ]
+        params.extend(pack_array_param("area_uid", area_uids))
+        response = self._get("/api/v2/data/zone_events", params=params)
+        payload = response.json()
+        if isinstance(payload, dict):
+            for key in ("zone_events", "events", "data"):
+                if key in payload and isinstance(payload[key], list):
+                    return [ZoneEvent.from_wire(it) for it in payload[key]]
+        items = unwrap_resource(payload, "zone_events")
+        return [ZoneEvent.from_wire(item) for item in items]
+
+    def iter_pws(
+        self,
+        *,
+        trackable_uid: str | list[str],
+        start: datetime,
+        end: datetime,
+        page_size: int = 1000,
+    ) -> Iterator[PwsEvent]:
+        """Lazy iterator over PWS events for one or more trackables.
+
+        Yields one :class:`PwsEvent` per server row. HTTP requests fire
+        only when the iterator advances past the current page — calling
+        ``list(client.events.iter_pws(...))`` materialises everything,
+        while ``next(iter)`` fetches the minimum needed.
+
+        Parameters
+        ----------
+        trackable_uid
+            One uid string or a list of uids (Rails-style
+            ``track_uid[]=`` query params).
+        start, end
+            Tz-aware datetimes. Naive datetimes raise ``ValueError``.
+        page_size
+            Server-side limit hint. The server may return fewer rows.
+
+        Examples
+        --------
+        >>> for event in client.events.iter_pws(
+        ...     trackable_uid="t-1", start=start, end=end
+        ... ):
+        ...     print(event.ts, event.zone_uid)
+        """
+        return iter(self._build_pws_paginator(trackable_uid, start, end, page_size))
+
+    def pages(
+        self,
+        *,
+        trackable_uid: str | list[str],
+        start: datetime,
+        end: datetime,
+        page_size: int = 1000,
+    ) -> Iterator[Page[PwsEvent]]:
+        """Iterate one :class:`Page` at a time — for progress reporting.
+
+        Same conventions as :meth:`iter_pws`, but yields whole pages
+        carrying ``page_number`` / ``total_count`` / ``has_next`` so
+        callers can print progress without counting items themselves.
+        """
+        return self._build_pws_paginator(trackable_uid, start, end, page_size).pages()
+
+    def _build_pws_paginator(
+        self,
+        trackable_uid: str | list[str],
+        start: datetime,
+        end: datetime,
+        page_size: int,
+    ) -> BodyUrlPaginator[PwsEvent]:
+        uids = [trackable_uid] if isinstance(trackable_uid, str) else list(trackable_uid)
+        params: list[tuple[str, str]] = [
+            ("event_type[]", "pws"),
+            ("from", str(to_epoch_ms(start, arg_name="start"))),
+            ("to", str(to_epoch_ms(end, arg_name="end"))),
+            ("limit", str(page_size)),
+        ]
+        params.extend(pack_array_param("track_uid", uids))
+
+        def parse(raw: Any) -> list[PwsEvent]:
+            if not isinstance(raw, list):
+                return []
+            out: list[PwsEvent] = []
+            for item in raw:
+                if isinstance(item, dict):
+                    out.append(PwsEvent.from_wire(item))
+            return out
+
+        # Bind the client's request method as the fetcher. Wraps in
+        # check_response via self._client._request semantics.
+        def fetch(path: str, *, params: Any = None) -> Any:
+            return self._client._request("GET", path, params=params)
+
+        return BodyUrlPaginator[PwsEvent](
+            fetch=fetch,
+            path="/api/v2/external_events",
+            params=params,
+            parse_items=parse,
+            list_key="external_events",
+        )
+
+
+__all__ = ["EventsAPI"]

rtls_sdk/resources/floorplans.py

@@ -0,0 +1,283 @@
+"""Floorplans resource sub-client.
+
+Full CRUD plus image upload (base64-in-JSON on the same POST body) and
+image download. Live-server schema (probed M10) requires:
+
+- ``POST /api/v2/floorplans/`` — ``sublocation_uid`` and ``image:
+  {original_filename, file}`` are required; ``display_name``,
+  ``image_scale``, ``image_rotation``, ``image_offset_x``,
+  ``image_offset_y`` are optional. **There is no `name` field, and
+  imageless floorplans are NOT permitted.**
+- ``PUT /api/v2/floorplans/{uid}`` — accepts any subset of the above
+  fields. Image replacement is optional.
+- ``GET /api/v2/floorplans/{uid}`` — returns ``{floorplans: [<item>]}``
+  (single-item list envelope).
+- The created floorplan's ``url`` is a relative path of the form
+  ``/uploads/floorplan/image/<uid>/<original_filename>`` and is
+  fetched via a separate authenticated GET with a 180-second read
+  timeout (production floorplans can be tens of MB of PDF).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import IO, Any
+from urllib.parse import urljoin
+
+import httpx
+
+from .._envelope import unwrap_resource, unwrap_resource_single
+from .._query import encode_image_payload
+from ..models import Floorplan
+from ._base import ResourceAPI
+
+# Matches the desktop site-plan client's ``Network::Timeout::Resource``
+# of 180 s. Used only for image GETs — chunked PDFs can be tens of MB.
+_IMAGE_DOWNLOAD_TIMEOUT_SEC: float = 180.0
+
+
+class FloorplansAPI(ResourceAPI):
+    """List, create, update, delete floorplans; upload + download images.
+
+    ``list`` is defined last (class-scope shadow workaround).
+    """
+
+    def get(self, uid: str) -> Floorplan:
+        """Fetch one floorplan by uid.
+
+        Wire format: server returns ``{floorplans: [<item>]}`` even for
+        a single-uid GET. The SDK unwraps the list.
+        """
+        response = self._get(f"/api/v2/floorplans/{uid}")
+        payload = response.json()
+        if isinstance(payload, dict) and "floorplans" in payload:
+            items = payload["floorplans"]
+            if isinstance(items, list) and items:
+                return Floorplan.from_wire(items[0])
+        if isinstance(payload, dict):
+            try:
+                return Floorplan.from_wire(unwrap_resource_single(payload, "floorplan"))
+            except ValueError:
+                return Floorplan.from_wire(payload)
+        raise ValueError(f"unexpected floorplan payload shape: {type(payload).__name__}")
+
+    def create(
+        self,
+        *,
+        sublocation_uid: str,
+        image_bytes: bytes | None = None,
+        original_filename: str | None = None,
+        image_path: str | Path | None = None,
+        display_name: str | None = None,
+        image_scale: float = 1.0,
+        image_rotation: float = 0.0,
+        image_offset_x: float = 0.0,
+        image_offset_y: float = 0.0,
+        **fields: Any,
+    ) -> Floorplan:
+        """Create a floorplan attached to ``sublocation_uid``.
+
+        Image input is required and either-or:
+
+        - Pass ``image_bytes`` (``bytes``) + ``original_filename`` (``str``), OR
+        - Pass ``image_path`` (``str | Path``) — the SDK reads the file
+          and derives ``original_filename`` from ``Path(image_path).name``.
+
+        Passing both raises ``ValueError``. Passing neither raises
+        ``ValueError`` — the server schema requires an image.
+
+        Parameters
+        ----------
+        sublocation_uid
+            Parent area uid. Required.
+        image_bytes
+            Raw image bytes (PNG / SVG / PDF). Must be valid for its
+            format — the server runs ``image-size`` on the bytes and
+            500s on a malformed file.
+        original_filename
+            File name as the server should store it. Required when
+            ``image_bytes`` is passed.
+        image_path
+            Convenience: a path on disk. Mutually exclusive with
+            ``image_bytes`` / ``original_filename``.
+        display_name
+            Optional user-facing label (the server's ``display_name``
+            field — note ``display_name``, not ``name``).
+        image_scale, image_rotation, image_offset_x, image_offset_y
+            Placement transform. Identity defaults.
+        **fields
+            Other server-accepted fields (deployment-specific).
+
+        Examples
+        --------
+        From in-memory bytes:
+
+        >>> with open("warehouse.png", "rb") as fh:
+        ...     plan = client.floorplans.create(
+        ...         sublocation_uid=area.uid,
+        ...         image_bytes=fh.read(),
+        ...         original_filename="warehouse.png",
+        ...     )
+
+        From a path:
+
+        >>> plan = client.floorplans.create(
+        ...     sublocation_uid=area.uid,
+        ...     image_path="warehouse.png",
+        ...     display_name="Warehouse 12 — Bay 3",
+        ... )
+        """
+        image = self._resolve_image_payload(
+            image_bytes=image_bytes,
+            original_filename=original_filename,
+            image_path=image_path,
+            required=True,
+        )
+        body: dict[str, Any] = {
+            "sublocation_uid": sublocation_uid,
+            "image": image,
+            "image_scale": image_scale,
+            "image_rotation": image_rotation,
+            "image_offset_x": image_offset_x,
+            "image_offset_y": image_offset_y,
+            **fields,
+        }
+        if display_name is not None:
+            body["display_name"] = display_name
+        response = self._post("/api/v2/floorplans/", json=body)
+        return _parse_floorplan(response.json())
+
+    def update(
+        self,
+        uid: str,
+        *,
+        image_bytes: bytes | None = None,
+        original_filename: str | None = None,
+        image_path: str | Path | None = None,
+        **fields: Any,
+    ) -> Floorplan:
+        """Update a floorplan's fields. Image replacement is optional.
+
+        Same either-or rule for image inputs as :meth:`create`. Pass
+        neither to keep the stored image untouched; pass one to replace
+        it.
+        """
+        if image_bytes is not None or image_path is not None:
+            fields = {
+                **fields,
+                "image": self._resolve_image_payload(
+                    image_bytes=image_bytes,
+                    original_filename=original_filename,
+                    image_path=image_path,
+                    required=False,
+                ),
+            }
+        response = self._put(f"/api/v2/floorplans/{uid}", json=fields)
+        return _parse_floorplan(response.json())
+
+    def delete(self, uid: str) -> None:
+        """Delete a floorplan (server removes the row AND the stored image)."""
+        self._delete(f"/api/v2/floorplans/{uid}")
+
+    def download_image(
+        self,
+        floorplan_or_uid: Floorplan | str,
+        *,
+        stream_to: IO[bytes] | None = None,
+    ) -> bytes | None:
+        """Download a floorplan's image bytes.
+
+        Accepts a :class:`Floorplan` (uses its ``.url``) or a uid (the
+        SDK first calls :meth:`get` to resolve). The request issues a
+        single GET against the server-returned relative URL with a
+        180-second read timeout — production floorplans can be tens of
+        MB of PDF, well beyond the default 30-second read budget.
+
+        With ``stream_to=None`` (default), accumulates the full body
+        and returns ``bytes``.
+
+        With ``stream_to=<writable bytes file-like>``, writes chunks
+        as they arrive and returns ``None``. Use this for very large
+        downloads to keep memory bounded.
+
+        Examples
+        --------
+        >>> data = client.floorplans.download_image(plan)
+        >>> with open("warehouse.png", "wb") as fh:
+        ...     client.floorplans.download_image(plan, stream_to=fh)
+        """
+        if isinstance(floorplan_or_uid, Floorplan):
+            plan_url = floorplan_or_uid.url
+        else:
+            plan_url = self.get(floorplan_or_uid).url
+        if not plan_url:
+            raise ValueError("floorplan has no image URL (was an image actually uploaded?)")
+
+        absolute = urljoin(str(self._client._http.base_url), plan_url)
+        timeout = httpx.Timeout(
+            connect=10.0,
+            read=_IMAGE_DOWNLOAD_TIMEOUT_SEC,
+            write=10.0,
+            pool=5.0,
+        )
+
+        if stream_to is None:
+            response = self._client._http.get(absolute, timeout=timeout)
+            response.raise_for_status()
+            return response.content
+
+        with self._client._http.stream("GET", absolute, timeout=timeout) as response:
+            response.raise_for_status()
+            for chunk in response.iter_bytes(chunk_size=64 * 1024):
+                stream_to.write(chunk)
+        return None
+
+    # -- helpers --------------------------------------------------------
+
+    def _resolve_image_payload(
+        self,
+        *,
+        image_bytes: bytes | None,
+        original_filename: str | None,
+        image_path: str | Path | None,
+        required: bool,
+    ) -> dict[str, Any]:
+        """Resolve the either-or image input into a server-shaped sub-object."""
+        if image_bytes is not None and image_path is not None:
+            raise ValueError("pass either image_bytes / image_path, not both")
+        if image_path is not None:
+            path = Path(image_path)
+            return encode_image_payload(path.read_bytes(), original_filename or path.name)
+        if image_bytes is not None:
+            if not original_filename:
+                raise ValueError(
+                    "original_filename is required when image_bytes is passed "
+                    "(the server uses it to compose the storage path)"
+                )
+            return encode_image_payload(image_bytes, original_filename)
+        if required:
+            raise ValueError(
+                "image is required on floorplans.create: "
+                "pass image_bytes + original_filename, or image_path"
+            )
+        # Unreachable in practice: callers only enter this method when at
+        # least one of the image inputs is set, OR with required=True.
+        raise ValueError("no image input supplied")
+
+    def list(self) -> list[Floorplan]:
+        response = self._get("/api/v2/floorplans/")
+        items = unwrap_resource(response.json(), "floorplans")
+        return [Floorplan.from_wire(item) for item in items]
+
+
+def _parse_floorplan(payload: Any) -> Floorplan:
+    """Server returns bare object on create/update; some deployments envelope."""
+    if isinstance(payload, dict):
+        try:
+            return Floorplan.from_wire(unwrap_resource_single(payload, "floorplan"))
+        except ValueError:
+            return Floorplan.from_wire(payload)
+    raise ValueError(f"unexpected floorplan payload shape: {type(payload).__name__}")
+
+
+__all__ = ["FloorplansAPI"]

rtls_sdk/resources/groups.py

@@ -0,0 +1,99 @@
+"""Groups resource sub-client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._envelope import unwrap_resource, unwrap_resource_single
+from ..compounds import groups as _compound
+from ..models import BulkResult, Group
+from ._base import ResourceAPI
+
+
+class GroupsAPI(ResourceAPI):
+    """List, create, update, and delete trackable groups.
+
+    ``list`` is defined last (class-scope shadow workaround for mypy).
+    M4 adds compound ``delete`` (cascade-detach) and ``add_tags`` /
+    ``remove_tags`` helpers.
+    """
+
+    def create(self, name: str, **fields: Any) -> Group:
+        """Create a new group (single REST call)."""
+        body: dict[str, Any] = {"name": name, **fields}
+        response = self._post("/api/v2/groups", json=body)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "group")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Group.from_wire(item)
+
+    def update(self, uid: str, **fields: Any) -> Group:
+        """Update a group's metadata (single REST call)."""
+        response = self._put(f"/api/v2/groups/{uid}", json=fields)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "group")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Group.from_wire(item)
+
+    def delete_raw(self, uid: str) -> None:
+        """Delete a group (single REST call, no trackable-detach).
+
+        **Advanced.** :meth:`delete` (added in M4) first removes the
+        group from every trackable that referenced it. Calling
+        ``delete_raw`` on a group with members leaves dangling references
+        — only use it if you've already detached or know the server
+        cascades server-side.
+        """
+        self._delete(f"/api/v2/groups/{uid}")
+
+    def delete(self, uid: str) -> None:
+        """Delete a group, first detaching every trackable that referenced it.
+
+        The server has no "tags in group X" endpoint per the JS reference
+        client (RESEARCH §4 "Delete group"), so the SDK lists trackables
+        and filters client-side, then calls ``replace_groups`` on each
+        member before the final ``DELETE /groups/{uid}``.
+
+        Step names: ``load_member_tags``, ``detach_from_tag``,
+        ``delete_group``.
+
+        Detach failures do not abort the cascade — the group is still
+        deleted afterward. If any tags couldn't be detached, the SDK
+        raises :class:`PartialFailureError` AFTER the group delete
+        succeeded, with the dangling tag uids in ``partial_result``.
+        """
+        _compound.delete_group(self._client, uid)
+
+    def add_tags(self, group_uid: str, tag_uids: list[str]) -> BulkResult[None]:
+        """Add a group to each tag's membership, continue-on-error.
+
+        For each tag the SDK loads its current group list, appends
+        ``group_uid`` (no-op if already present), and writes the new
+        list. Failures land in ``BulkResult.failures``.
+        """
+        return _compound.add_tags(self._client, group_uid, tag_uids)
+
+    def remove_tags(self, group_uid: str, tag_uids: list[str]) -> BulkResult[None]:
+        """Remove a group from each tag's membership, continue-on-error."""
+        return _compound.remove_tags(self._client, group_uid, tag_uids)
+
+    def list(self) -> list[Group]:
+        """Return all groups for the current project.
+
+        Examples
+        --------
+        >>> groups = client.groups.list()
+        >>> {g.name: g.uid for g in groups}
+        {'Fleet': 'g-fleet', 'Loading bay': 'g-loading'}
+        """
+        response = self._get("/api/v2/groups/")
+        payload = response.json()
+        items = unwrap_resource(payload, "groups")
+        return [Group.from_wire(item) for item in items]
+
+
+__all__ = ["GroupsAPI"]

rtls_sdk/resources/logger.py

@@ -0,0 +1,40 @@
+"""Logger resource sub-client (admin).
+
+Admin-only operations for tuning the server's logging filter at runtime.
+Most SDK consumers will never need this — included for parity with the
+JS reference client.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._base import ResourceAPI
+
+
+class LoggerAPI(ResourceAPI):
+    """Get / set / clear the server's runtime logger filter (admin).
+
+    The JS reference client treats this endpoint as no-auth-required;
+    the SDK relies on the configured client identity. Filters are
+    arbitrary key/value pairs whose semantics live server-side.
+    """
+
+    def get_filter(self) -> dict[str, Any]:
+        """Read the current server logger filter."""
+        response = self._get("/api/v2/logger/")
+        payload = response.json() if response.content else None
+        return payload if isinstance(payload, dict) else {"data": payload}
+
+    def set_filter(self, filters: dict[str, Any]) -> dict[str, Any]:
+        """Apply / merge a new server logger filter."""
+        response = self._post("/api/v2/logger/", json=filters)
+        payload = response.json() if response.content else None
+        return payload if isinstance(payload, dict) else {"data": payload}
+
+    def clear_filter(self) -> None:
+        """Clear the current server logger filter."""
+        self._delete("/api/v2/logger/")
+
+
+__all__ = ["LoggerAPI"]

rtls_sdk/resources/messaging.py

@@ -0,0 +1,51 @@
+"""Messaging resource sub-client.
+
+The wire endpoint is ``POST /api/v2/messaging`` (RESEARCH Discrepancy
+#15) — distinct from the deprecated ``/api/v2/win_message_que/create.json``
+the JS client still defines but doesn't call. The SDK exposes only the
+live endpoint.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._base import ResourceAPI
+
+
+class MessagingAPI(ResourceAPI):
+    """Send messages to trackable badges / users."""
+
+    def send(self, *, from_uid: str, to_uids: list[str], body: str) -> dict[str, Any]:
+        """Send a message addressed to one or more recipients.
+
+        Parameters
+        ----------
+        from_uid
+            The sender's uid (typically the current user).
+        to_uids
+            Recipient uids — trackables, users, or device uids depending
+            on what your deployment routes via messaging.
+        body
+            The message text.
+
+        Returns
+        -------
+        dict
+            The server response. M3 surfaces it as a raw dict because
+            the wire shape isn't documented stably (RESEARCH §1 only
+            says "messages: []"); a typed model can be added later
+            without breaking callers that already treat the return as
+            opaque.
+        """
+        payload = {
+            "from": {"uid": from_uid},
+            "to": {"uids": to_uids},
+            "body": body,
+        }
+        response = self._post("/api/v2/messaging", json=payload)
+        parsed = response.json() if response.content else None
+        return parsed if isinstance(parsed, dict) else {"data": parsed}
+
+
+__all__ = ["MessagingAPI"]