rtls-sdk 0.2.0__py3-none-any.whl

rtls_sdk/resources/nodes.py

@@ -0,0 +1,157 @@
+"""Nodes resource sub-client."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from .._envelope import unwrap_resource, unwrap_resource_single
+from .._query import normalize_mac
+from ..compounds import nodes as _compound
+from ..models import BulkResult, ImportResult, Node
+from ._base import ResourceAPI
+
+
+class NodesAPI(ResourceAPI):
+    """Read and (with care) mutate hardware nodes.
+
+    The JS reference client fetches nodes at company scope, not project
+    scope. The SDK doesn't auto-switch — call
+    ``client.with_scope(company_uid=...)`` if you need the company-wide
+    view. (``with_scope`` lands in M8.)
+
+    M5 adds compound :meth:`release` (close-association + release in one
+    call, with per-call scope) and :meth:`import_` (validate + create
+    loop). ``list`` is defined last (class-scope shadow workaround).
+    """
+
+    def create(self, mac_address: str, **fields: Any) -> Node:
+        """Register a new node by its MAC address.
+
+        The MAC is the only required input. The server's ``createNode``
+        schema accepts other fields (``name``, ``hw_info``,
+        ``parent_mac_address``, ``bridge_mac_address``, ``announce``,
+        ``node_type``, ``periferial_info``, ``uwb_trx_config``,
+        ``company_uid``, ``project_uid``) via ``**fields``, but the
+        canonical commissioning flow is MAC-only; metadata is added
+        later via :meth:`update_raw`.
+
+        The MAC is normalized to bare 12-hex lowercase (the server's
+        validation regex is ``/^[a-fA-F0-9]{12}$/`` — no separators).
+        Six input formats accepted; malformed input raises
+        :class:`ValueError` before any HTTP call.
+
+        Examples
+        --------
+        >>> node = client.nodes.create("aabbccddeeff")
+        >>> node.mac_address
+        'aabbccddeeff'
+        """
+        body: dict[str, Any] = {"mac_address": normalize_mac(mac_address), **fields}
+        response = self._post("/api/v2/nodes/", json=body)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "node")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Node.from_wire(item)
+
+    def delete_raw(self, uid: str) -> None:
+        """Delete a node (single REST call, fail-fast).
+
+        **Advanced.** :meth:`delete` (added in M5) is the
+        continue-on-error bulk variant.
+        """
+        self._delete(f"/api/v2/nodes/{uid}")
+
+    def validate(self, mac_addresses: list[str]) -> dict[str, Any]:
+        """Validate one or more MAC addresses against the server.
+
+        Returns the raw server response (typically containing ``valid``,
+        ``invalid``, ``duplicate`` lists). M5's :meth:`import_` compound
+        wraps this.
+        """
+        normalized = [normalize_mac(m) for m in mac_addresses]
+        response = self._post("/api/v2/nodes/validate/", json={"mac_addresses": normalized})
+        payload = response.json()
+        if isinstance(payload, dict):
+            return payload
+        return {"data": payload}
+
+    def assign_raw(self, mac_address: str, *, project_uid: str) -> dict[str, Any]:
+        """Assign a node to a project (single REST call).
+
+        **Advanced.** See M5's :meth:`release` for the inverse, which is
+        wrapped as a compound to avoid the JS client's scope-mutation bug.
+        """
+        body = {"mac_address": normalize_mac(mac_address), "project_uid": project_uid}
+        response = self._post("/api/v2/nodes_associations/assign", json=body)
+        payload = response.json()
+        return payload if isinstance(payload, dict) else {"data": payload}
+
+    def release_raw(self, mac_address: str, *, project_uid: str) -> dict[str, Any]:
+        """Release a node from a project (single REST call).
+
+        **Advanced.** This does NOT close any open trackable-association
+        for the MAC first — :meth:`release` (M5) does both safely with
+        per-call scope.
+        """
+        body = {"mac_address": normalize_mac(mac_address), "project_uid": project_uid}
+        response = self._post("/api/v2/nodes_associations/release", json=body)
+        payload = response.json()
+        return payload if isinstance(payload, dict) else {"data": payload}
+
+    def release(self, mac_address: str, *, project_uid: str | None = None) -> None:
+        """Release a node from a project, closing any open association.
+
+        The compound first looks up the open trackable-association for
+        ``mac_address`` and closes it; only then does it release the
+        node. All sub-calls run under a per-call scope override so the
+        target project travels in the request headers — the JS
+        reference client mutates ``axios.defaults`` here and leaks the
+        change on error (RESEARCH §4 "Release node and close its
+        association"). The SDK's per-call scope is per-thread and
+        reverts on exit.
+
+        Step names: ``close_association``, ``release_node``.
+        """
+        _compound.release_node(self._client, normalize_mac(mac_address), project_uid=project_uid)
+
+    def import_(
+        self,
+        mac_addresses: list[str],
+        *,
+        on_progress: Callable[[int, int], None] | None = None,
+    ) -> ImportResult:
+        """Validate MAC addresses, then create each valid row.
+
+        Short-circuits if any MAC fails validation — no partial creates
+        when the input has known-bad rows. ``on_progress(done, total)``
+        (optional) is invoked after each create attempt.
+
+        Returns
+        -------
+        ImportResult
+            Lists of valid / invalid / duplicate MACs, the number of
+            nodes actually created, and per-row failures from the
+            create step.
+        """
+        normalized = [normalize_mac(m) for m in mac_addresses]
+        return _compound.import_nodes(self._client, normalized, on_progress=on_progress)
+
+    def delete(self, uid_or_uids: str | list[str]) -> BulkResult[None]:
+        """Delete one or many nodes, continue-on-error.
+
+        Diverges from :meth:`delete_raw` (M3) which is fail-fast: this
+        compound continues past per-item failures and returns a
+        :class:`BulkResult` listing successes and failures separately.
+        """
+        return _compound.delete_nodes(self._client, uid_or_uids)
+
+    def list(self) -> list[Node]:
+        response = self._get("/api/v2/nodes")
+        items = unwrap_resource(response.json(), "nodes")
+        return [Node.from_wire(item) for item in items]
+
+
+__all__ = ["NodesAPI"]

rtls_sdk/resources/notifications.py

@@ -0,0 +1,55 @@
+"""Notifications resource sub-client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._envelope import unwrap_resource, unwrap_resource_single
+from ..models import NotificationProfile, NotificationType
+from ._base import ResourceAPI
+
+
+class NotificationsAPI(ResourceAPI):
+    """Read and manage notification profiles + notification-type metadata.
+
+    ``list`` is defined last (class-scope shadow workaround).
+    """
+
+    def create(self, name: str, **fields: Any) -> NotificationProfile:
+        """Create a notification profile."""
+        body: dict[str, Any] = {"name": name, **fields}
+        response = self._post("/api/v2/notifications/", json=body)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "notification")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return NotificationProfile.from_wire(item)
+
+    def update(self, uid: str, **fields: Any) -> NotificationProfile:
+        """Update a notification profile."""
+        response = self._put(f"/api/v2/notifications/{uid}", json=fields)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "notification")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return NotificationProfile.from_wire(item)
+
+    def delete(self, uid: str) -> None:
+        """Delete a notification profile."""
+        self._delete(f"/api/v2/notifications/{uid}")
+
+    def list_types(self) -> list[NotificationType]:
+        """Enumerate the kinds of events notifications can subscribe to."""
+        response = self._get("/api/v2/notification_types")
+        items = unwrap_resource(response.json(), "notification_types")
+        return [NotificationType.from_wire(item) for item in items]
+
+    def list(self) -> list[NotificationProfile]:
+        response = self._get("/api/v2/notifications/")
+        items = unwrap_resource(response.json(), "notifications")
+        return [NotificationProfile.from_wire(item) for item in items]
+
+
+__all__ = ["NotificationsAPI"]

rtls_sdk/resources/projects.py

@@ -0,0 +1,67 @@
+"""Projects resource sub-client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._envelope import unwrap_resource, unwrap_resource_single
+from ..models import Project
+from ._base import ResourceAPI
+
+
+class ProjectsAPI(ResourceAPI):
+    """List, create, update, and delete projects.
+
+    ``list`` is defined last (class-scope shadow workaround).
+    """
+
+    def create(self, name: str, **fields: Any) -> Project:
+        """Create a new project.
+
+        Server's Joi ``createProject`` schema expects the body nested
+        under a top-level ``project`` key:
+        ``{"project": {"name": "...", ...}}``. The SDK wraps the body so
+        callers can pass flat kwargs. M14 regression — phase-1 failure
+        was the server returning ``"project" is required``.
+        """
+        body: dict[str, Any] = {"project": {"name": name, **fields}}
+        response = self._post("/api/v2/projects/", json=body)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "project")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Project.from_wire(item)
+
+    def update(self, uid: str, **fields: Any) -> Project:
+        """Update a project's fields.
+
+        Body is nested under ``project`` to match
+        :meth:`create` / the Joi ``updateProject`` schema.
+        """
+        body: dict[str, Any] = {"project": fields}
+        response = self._put(f"/api/v2/projects/{uid}", json=body)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "project")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Project.from_wire(item)
+
+    def delete(self, uid: str) -> None:
+        """Delete a project."""
+        self._delete(f"/api/v2/projects/{uid}")
+
+    def list(self) -> list[Project]:
+        """Return projects visible to the current user.
+
+        Project listing does not require an active ``X-User-Project`` header
+        (RESEARCH §1 Projects row 1) — it's commonly the first scoped call
+        after login.
+        """
+        response = self._get("/api/v2/projects/")
+        items = unwrap_resource(response.json(), "projects")
+        return [Project.from_wire(item) for item in items]
+
+
+__all__ = ["ProjectsAPI"]

rtls_sdk/resources/reports.py

@@ -0,0 +1,180 @@
+"""Reports resource sub-client."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import IO
+
+from .._envelope import unwrap_resource_single
+from .._time import to_iso8601
+from ..compounds import reports as _compound
+from ..models import CsvBlob, Heatmap, PwsReport, Report, ReportType
+from ._base import ResourceAPI
+
+
+class ReportsAPI(ResourceAPI):
+    """Generate and read reports.
+
+    M2 shipped read-only access (``list``, ``get``). M7 adds the
+    compound flows: heatmap polling, PWS aggregation, CSV downloads
+    (zone-activity, alarms).
+
+    ``list`` is defined last (class-scope shadow workaround for mypy).
+    """
+
+    def get(self, uid: str, *, is_output_file: bool = False) -> Report:
+        """Fetch a single report's metadata."""
+        params = {"file": "1"} if is_output_file else None
+        response = self._get(f"/api/v2/report/{uid}", params=params)
+        payload = response.json()
+        if isinstance(payload, dict) and "report" in payload:
+            return Report.from_wire(unwrap_resource_single(payload, "report"))
+        if isinstance(payload, dict):
+            return Report.from_wire(payload)
+        raise ValueError(f"unexpected report payload shape: {type(payload).__name__}")
+
+    # -- M7 compounds --------------------------------------------------
+
+    def heatmap(
+        self,
+        *,
+        start: datetime,
+        end: datetime,
+        tag_uids: list[str],
+        names: list[str] | None = None,
+        poll_interval: float = 2.0,
+        timeout: float | None = None,
+    ) -> Heatmap:
+        """Generate a heatmap report — POST, then poll until ready.
+
+        Uses the live ``/api/v2/obsolete/report`` paths (RESEARCH
+        Discrepancy #5). Default ``timeout=None`` is unbounded; pass a
+        finite value to bound the wait. On timeout the SDK raises
+        :class:`ReportTimeout` carrying the in-flight ``report_uid`` so
+        the caller can resume polling via :meth:`get` later.
+
+        On a server-reported error the SDK raises :class:`ReportFailed`.
+
+        Examples
+        --------
+        >>> heatmap = client.reports.heatmap(
+        ...     start=start, end=end, tag_uids=["t-1", "t-2"], timeout=300,
+        ... )
+        >>> heatmap.image_url
+        'https://rtls.example.com/api/v2/heatmap/h-1?...'
+        """
+        return _compound.generate_heatmap(
+            self._client,
+            start=start,
+            end=end,
+            tag_uids=tag_uids,
+            names=names,
+            poll_interval=poll_interval,
+            timeout=timeout,
+        )
+
+    def pws(
+        self,
+        *,
+        trackable_uid: str | list[str],
+        start: datetime,
+        end: datetime,
+        timezone: str | None = None,
+    ) -> PwsReport:
+        """Aggregate all PWS-event pages into a :class:`PwsReport`.
+
+        Holds the full result set in memory. For large windows prefer
+        :meth:`EventsAPI.iter_pws` (lazy).
+        """
+        return _compound.generate_pws_report(
+            self._client,
+            trackable_uid=trackable_uid,
+            start=start,
+            end=end,
+            timezone=timezone,
+        )
+
+    def zone_activity_csv(
+        self,
+        *,
+        start: datetime,
+        end: datetime,
+        area_uids: list[str],
+        stream_to: IO[bytes] | None = None,
+        dedup_headers: bool = True,
+    ) -> CsvBlob | None:
+        """Download Zone-Activity CSV, following ``content-next-page`` chunks.
+
+        With ``stream_to=None`` (default) the SDK accumulates in memory
+        and returns a :class:`CsvBlob`. With ``stream_to=<file-like>``
+        chunks are written as they arrive and the return is ``None``.
+
+        Duplicate header rows in chunks 2..N are stripped by default
+        (``dedup_headers=True``) so the concatenated bytes parse as one
+        coherent CSV.
+        """
+        return _compound.download_zone_activity_csv(
+            self._client,
+            start=start,
+            end=end,
+            area_uids=area_uids,
+            stream_to=stream_to,
+            dedup_headers=dedup_headers,
+        )
+
+    def alarms_csv(
+        self,
+        *,
+        start: datetime,
+        end: datetime,
+        site_uid: str,
+        alarm_types: list[str] | None = None,
+        include_banner: bool = True,
+    ) -> CsvBlob:
+        """Download Alarms CSV with an optional multi-line banner prefix.
+
+        The banner mirrors the JS reference client's behaviour
+        (``#Site / #From / #To`` lines) so downstream tooling can
+        identify the report. Pass ``include_banner=False`` for the
+        bare server CSV.
+        """
+        return _compound.download_alarms_csv(
+            self._client,
+            start=start,
+            end=end,
+            site_uid=site_uid,
+            alarm_types=alarm_types,
+            include_banner=include_banner,
+        )
+
+    def list(
+        self,
+        *,
+        site_uid: str,
+        start: datetime,
+        end: datetime,
+        type: ReportType,
+    ) -> list[Report]:
+        """List reports of ``type`` generated for ``site_uid`` in a window.
+
+        Timestamps are sent as ISO-8601 strings (RESEARCH §2 — reports
+        diverge from alarms here). Naive ``datetime`` raises ``ValueError``.
+        """
+        params = {
+            "site_uid": site_uid,
+            "from": to_iso8601(start, arg_name="start"),
+            "to": to_iso8601(end, arg_name="end"),
+            "type": type.value,
+        }
+        response = self._get("/api/v2/report", params=params)
+        payload = response.json()
+        if isinstance(payload, dict):
+            items = payload.get("reports")
+            if isinstance(items, list):
+                return [Report.from_wire(item) for item in items]
+        if isinstance(payload, list):
+            return [Report.from_wire(item) for item in payload]
+        return []
+
+
+__all__ = ["ReportsAPI"]

rtls_sdk/resources/sites.py

@@ -0,0 +1,115 @@
+"""Sites (locations) resource sub-client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._envelope import unwrap_resource, unwrap_resource_single
+from ..models import Site
+from ._base import ResourceAPI
+
+# The JS reference client only sends ``{name, shift}`` on a site update,
+# even though the server (per docs) accepts more. The SDK matches the
+# client's conservatism to avoid surprising server-side validation
+# failures. RESEARCH §1 / Discrepancy #13. The constraint is on UPDATE
+# only — ``create`` accepts a wider body because the desktop site-plan
+# client sends additional fields (address, country, timezone, …) at
+# creation time.
+_SITE_UPDATE_FIELDS: frozenset[str] = frozenset({"name", "shift"})
+
+
+class SitesAPI(ResourceAPI):
+    """List, create, update, and delete physical sites in the current scope.
+
+    The wire-format name is ``locations``; SDK exposes them as ``sites``
+    because that's the operator-facing term.
+
+    Cascade contract: ``sites.delete(uid)`` deletes the site **and**
+    every area, floorplan, anchor, and zone under it (server-side
+    cascade). The SDK does not pre-emptively delete children.
+
+    ``list`` is defined last (class-scope shadow workaround).
+    """
+
+    def create(self, name: str, *, shift: dict[str, Any] | None = None, **fields: Any) -> Site:
+        """Create a site.
+
+        Parameters
+        ----------
+        name
+            Display name.
+        shift
+            Optional shift configuration (the JS reference client's only
+            documented update field — passing it on create is also legal).
+        **fields
+            Additional fields the deployment supports (``address``,
+            ``country``, ``timezone``, …). The desktop site-plan client
+            sends these on create; the server's create surface is wider
+            than its update surface, so no allowlist is enforced here.
+
+        Examples
+        --------
+        >>> site = client.sites.create(name="Warehouse 12")
+        >>> site_with_addr = client.sites.create(
+        ...     name="Warehouse 13", address="123 Main", country="US",
+        ... )
+        """
+        body: dict[str, Any] = {"name": name, **fields}
+        if shift is not None:
+            body["shift"] = shift
+        response = self._post("/api/v2/locations/", json=body)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "location")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Site.from_wire(item)
+
+    def update(self, uid: str, **fields: Any) -> Site:
+        """Update a site's name and / or shift configuration.
+
+        Only ``name`` and ``shift`` are accepted — passing any other
+        field raises :class:`ValueError` *before* any HTTP call is made.
+        This mirrors the JS reference client's conservative payload
+        (RESEARCH Discrepancy #13). If you have a use case that needs
+        other fields updated, file an issue — the SDK can be opened up
+        once the server-side contract is confirmed.
+        """
+        extra = set(fields) - _SITE_UPDATE_FIELDS
+        if extra:
+            raise ValueError(
+                f"sites.update only accepts {sorted(_SITE_UPDATE_FIELDS)}; "
+                f"got unexpected field(s): {sorted(extra)}"
+            )
+        response = self._put(f"/api/v2/locations/{uid}", json=fields)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "location")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Site.from_wire(item)
+
+    def delete(self, uid: str) -> None:
+        """Delete a site (cascades to areas / floorplans / anchors / zones server-side).
+
+        A subsequent GET returns 404 → :class:`NotFound`. The cascade is
+        the server's contract, not the SDK's — the SDK does NOT iterate
+        children before issuing the DELETE.
+        """
+        self._delete(f"/api/v2/locations/{uid}")
+
+    def list(self) -> list[Site]:
+        """Return all sites visible to the current project scope.
+
+        Examples
+        --------
+        >>> for site in client.sites.list():
+        ...     print(site.uid, site.name)
+        """
+        response = self._get("/api/v2/locations/")
+        payload = response.json()
+        items = unwrap_resource(payload, "locations")
+        return [Site.from_wire(item) for item in items]
+
+
+__all__ = ["SitesAPI"]

rtls_sdk/resources/subscribers.py

@@ -0,0 +1,110 @@
+"""Subscribers resource sub-client.
+
+Two distinct sub-surfaces:
+
+- ``subscribers`` — alarm-notification subscribers; envelope key
+  ``subscribers``.
+- system-notification subscribers — envelope key
+  ``systemNotificationSubscriber``. Returned as a list of
+  :class:`SystemSubscriber`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._envelope import unwrap_resource, unwrap_resource_single
+from ..models import Subscriber, SystemSubscriber
+from ._base import ResourceAPI
+
+
+class SubscribersAPI(ResourceAPI):
+    """Read and manage alarm subscribers and system-notification subscribers.
+
+    ``list`` is defined last (class-scope shadow workaround).
+    """
+
+    def create(self, name: str, **fields: Any) -> Subscriber:
+        """Create an alarm subscriber.
+
+        ``fields`` typically contains ``addresses`` (``{"email": [...],
+        "phone": [...]}``) and a ``notifications`` list.
+        """
+        body: dict[str, Any] = {"name": name, **fields}
+        response = self._post("/api/v2/subscribers/", json=body)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "subscriber")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Subscriber.from_wire(item)
+
+    def update(self, uid: str, **fields: Any) -> Subscriber:
+        """Update an alarm subscriber."""
+        response = self._put(f"/api/v2/subscribers/{uid}", json=fields)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "subscriber")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Subscriber.from_wire(item)
+
+    def delete(self, uid: str) -> None:
+        """Delete an alarm subscriber."""
+        self._delete(f"/api/v2/subscribers/{uid}")
+
+    def update_system_notifications(
+        self, user_uid: str, notifications: list[Any]
+    ) -> SystemSubscriber:
+        """Update a user's system-event subscriptions.
+
+        System-event subscriptions live on a separate endpoint
+        (``/system_notifications/``) with a different envelope shape
+        (RESEARCH §3 Subscriber normalization).
+        """
+        body = {"user_uid": user_uid, "notifications": notifications}
+        response = self._put("/api/v2/system_notifications/", json=body)
+        payload = response.json()
+        if isinstance(payload, dict):
+            inner = payload.get("systemNotificationSubscriber")
+            if isinstance(inner, list) and inner:
+                first = inner[0]
+                if isinstance(first, dict):
+                    return SystemSubscriber.from_wire(first)
+            if isinstance(inner, dict):
+                return SystemSubscriber.from_wire(inner)
+            return SystemSubscriber.from_wire(payload)
+        return SystemSubscriber.from_wire({})
+
+    def list_system_notification_subscribers(self) -> list[SystemSubscriber]:
+        """List system-event subscribers (distinct from alarm subscribers).
+
+        The server's envelope here is ``systemNotificationSubscriber``
+        (singular noun, list value) — RESEARCH §3 Subscriber normalization.
+        """
+        response = self._get("/api/v2/system_notifications/")
+        payload = response.json()
+        items: list[Any]
+        if isinstance(payload, dict):
+            raw = payload.get("systemNotificationSubscriber")
+            if raw is None:
+                raw = payload.get("system_notification_subscriber")
+            if isinstance(raw, list):
+                items = raw
+            elif isinstance(raw, dict):
+                items = [raw]
+            else:
+                items = []
+        elif isinstance(payload, list):
+            items = payload
+        else:
+            items = []
+        return [SystemSubscriber.from_wire(item) for item in items]
+
+    def list(self) -> list[Subscriber]:
+        response = self._get("/api/v2/subscribers/")
+        items = unwrap_resource(response.json(), "subscribers")
+        return [Subscriber.from_wire(item) for item in items]
+
+
+__all__ = ["SubscribersAPI"]