rtls-sdk 0.2.0__py3-none-any.whl

rtls_sdk/models/subscriber.py

@@ -0,0 +1,68 @@
+"""Subscriber and system-notification subscriber models.
+
+These are distinct entities served by separate endpoints with different
+envelope keys (RESEARCH §3 Subscriber normalization). The SDK keeps them
+as two types rather than collapsing — they have different concerns.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field, model_validator
+
+from ._base import _BaseModel
+
+
+class SubscriberAddresses(_BaseModel):
+    """Contact addresses on a subscriber profile.
+
+    The server emits these fields as either a list of strings or a bare
+    string depending on the endpoint / version (RESEARCH §1 documented
+    arrays; the live server has been observed returning strings). The
+    model coerces both shapes into a list of strings so callers don't
+    have to branch.
+    """
+
+    email: list[str] = Field(default_factory=list)
+    phone: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_to_lists(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        out = dict(data)
+        for key in ("email", "phone"):
+            value = out.get(key)
+            if value is None:
+                out[key] = []
+            elif isinstance(value, str):
+                out[key] = [value] if value else []
+        return out
+
+
+class Subscriber(_BaseModel):
+    """An alarm-notifications subscriber.
+
+    Returned under ``{subscribers: [...]}`` from ``GET /subscribers/``.
+    """
+
+    uid: str | None = None
+    name: str | None = None
+    addresses: SubscriberAddresses | None = None
+    notifications: list[Any] = Field(default_factory=list)
+
+
+class SystemSubscriber(_BaseModel):
+    """A system-event subscriber — distinct from alarm subscribers.
+
+    Returned under ``{systemNotificationSubscriber: [...]}`` from
+    ``GET /system_notifications/``.
+    """
+
+    user_uid: str | None = None
+    notifications: list[Any] = Field(default_factory=list)
+
+
+__all__ = ["Subscriber", "SubscriberAddresses", "SystemSubscriber"]

rtls_sdk/models/system.py

@@ -0,0 +1,97 @@
+"""Host / uptime / connection / capabilities / version models."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field
+
+from ._base import _BaseModel
+
+
+class Host(_BaseModel):
+    """Host info — hostname + serverStatus (disk, memory, …).
+
+    The ``server_status`` field's shape varies by deployment and Linux
+    distribution; surface it as a dict and let ``.raw`` carry the rest.
+    """
+
+    hostname: str | None = None
+    server_status: dict[str, Any] | None = Field(default=None, alias="serverStatus")
+
+
+class Uptime(_BaseModel):
+    """A row from ``GET /host/uptime`` — service name + uptime data."""
+
+    name: str | None = None
+
+
+class Connection(_BaseModel):
+    """A row from ``GET /host/connections`` — active server connection."""
+
+
+class Capabilities(_BaseModel):
+    """SDK-detected server capabilities — SSO availability + API version.
+
+    Built by :meth:`AuthAPI.capabilities`. The ``sso`` flag reflects whether
+    ``GET /auth/sso/log_in`` resolves; ``api_version`` is ``"2.1"`` when SSO
+    is reachable, ``"2.0"`` otherwise (matches the JS reference client's
+    fallback heuristic, RESEARCH §4 "Probe SSO support").
+    """
+
+    sso: bool
+    api_version: str
+
+
+class Version(_BaseModel):
+    """Server version info from ``GET /version``.
+
+    The live server emits a nested shape: ``{api: {version}, rtls_frontend:
+    {version}, custom_product_attributes: {...}}``. Older deployments may
+    use the flat shape RESEARCH originally documented. All fields are
+    optional; the convenience properties below pull the version string
+    out of whichever form the server sent.
+    """
+
+    api_version: str | None = None
+    mysql_version: str | None = None
+    node_version: str | None = None
+    modules: list[str] | dict[str, Any] | None = None
+    user_modules: list[str] | dict[str, Any] | None = None
+    api: dict[str, Any] | None = None
+    rtls_frontend: dict[str, Any] | None = None
+    custom_product_attributes: dict[str, Any] | None = None
+
+    @property
+    def api_version_str(self) -> str | None:
+        """Return the API version as a string, regardless of wire shape."""
+        if self.api_version:
+            return self.api_version
+        if self.api and isinstance(self.api.get("version"), str):
+            value: str = self.api["version"]
+            return value
+        return None
+
+    @property
+    def frontend_version_str(self) -> str | None:
+        """Return the frontend version as a string, if available."""
+        if self.rtls_frontend and isinstance(self.rtls_frontend.get("version"), str):
+            value: str = self.rtls_frontend["version"]
+            return value
+        return None
+
+
+class WsHost(_BaseModel):
+    """The hostname for the WebSocket endpoint, returned by ``GET /wshost/``."""
+
+    ws_host: str | None = Field(default=None, alias="wsHost")
+
+
+__all__ = [
+    "Capabilities",
+    "Connection",
+    "Host",
+    "Uptime",
+    "Version",
+    "WsHost",
+]

rtls_sdk/models/system_health.py

@@ -0,0 +1,36 @@
+"""Return type for ``system.health()``.
+
+Aggregates three independent server-health calls into one struct with
+per-call error isolation (DESIGN §4.17 / §5 R4). Dataclass because the
+``errors`` dict carries live :class:`RtlsError` instances.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..errors import RtlsError
+from .system import Connection, Host, Uptime
+
+
+@dataclass
+class SystemHealth:
+    """Aggregated server-health snapshot.
+
+    Each sub-field is populated independently; a failure on one
+    sub-call sets that field to ``None`` and records the exception in
+    ``errors``, leaving the rest of the snapshot intact (RESEARCH §4
+    "Refresh System-Health dashboard" — the JS client routes each
+    error independently).
+
+    ``partial`` is ``True`` when any sub-call failed.
+    """
+
+    host: Host | None = None
+    uptime: list[Uptime] | None = None
+    connections: list[Connection] | None = None
+    partial: bool = False
+    errors: dict[str, RtlsError] = field(default_factory=dict)
+
+
+__all__ = ["SystemHealth"]

rtls_sdk/models/tag.py

@@ -0,0 +1,48 @@
+"""Tag (trackable_object) model.
+
+The server returns trackables under several envelope shapes (single inside
+``{trackableObjects: [t]}``, list inside the same, embedded inside
+associations, etc.). The SDK normalizes to one ``Tag`` type regardless.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field, model_validator
+
+from ._base import _BaseModel
+from .node import Node
+from .position import Position
+
+
+class Tag(_BaseModel):
+    """A tracked object (trackable / tag / asset).
+
+    Field aliases tolerate the embedded forms the server uses inside
+    other entities. Position and node sub-objects are eagerly parsed
+    into typed models when present.
+
+    The server has been observed to return ``groups: null`` on freshly-
+    created trackables (an unbound tag has no groups, but the field is
+    present). The SDK coerces ``None`` to ``[]`` so the typed list[str]
+    surface stays clean for consumers.
+    """
+
+    uid: str
+    name: str
+    mac_address: str | None = None
+    self_zone_uid: str | None = None
+    groups: list[str] = Field(default_factory=list)
+    position: Position | None = None
+    node: Node | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_null_lists(cls, data: Any) -> Any:
+        if isinstance(data, dict) and data.get("groups") is None:
+            data = {**data, "groups": []}
+        return data
+
+
+__all__ = ["Tag"]

rtls_sdk/models/tag_template.py

@@ -0,0 +1,24 @@
+"""Tag-template model.
+
+Returned by the client-only endpoint ``GET /trackable_objects/templates``
+(RESEARCH §1). Used as a creation prefab.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field
+
+from ._base import _BaseModel
+
+
+class TagTemplate(_BaseModel):
+    """A reusable shape for creating new trackables."""
+
+    uid: str | None = None
+    name: str | None = None
+    fields: dict[str, Any] = Field(default_factory=dict)
+
+
+__all__ = ["TagTemplate"]

rtls_sdk/models/user.py

@@ -0,0 +1,121 @@
+"""User model with a derived ``role`` enum.
+
+The server returns three boolean flags (``isSuperAdmin``,
+``isSystemUser``, ``isCompanyAdmin``) plus a raw ``role`` string. The
+SDK collapses this into a single :class:`Role` enum at parse time and
+keeps the raw flags accessible via ``user.raw_flags`` for power users.
+
+Enum values match the live server's accepted role strings (confirmed
+via the user-create validation error in M5: ``company_admin``,
+``project_system_admin``, ``project_operations_admin``,
+``project_maintainer``, ``project_user``, ``system_admin``). DESIGN §9
+open #4 — pending-backend-confirmation — is now resolved by direct
+observation of the test server.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import Field, computed_field, model_validator
+
+from ._base import _BaseModel
+
+
+class Role(str, Enum):
+    """Resolved user role.
+
+    Values are the server's accepted role strings. Ordering in this
+    declaration is informational (most-privileged first) and does not
+    imply comparable enums — compare by string equality only.
+
+    The boolean wire flags (``isSuperAdmin`` etc.) and the raw role
+    string both map into one of these members. See
+    :attr:`User.role` for the resolution rules.
+    """
+
+    SYSTEM_ADMIN = "system_admin"
+    COMPANY_ADMIN = "company_admin"
+    PROJECT_SYSTEM_ADMIN = "project_system_admin"
+    PROJECT_OPERATIONS_ADMIN = "project_operations_admin"
+    PROJECT_MAINTAINER = "project_maintainer"
+    PROJECT_USER = "project_user"
+
+
+class UserFlags(_BaseModel):
+    """Raw boolean flags the server returns on every User object."""
+
+    is_super_admin: bool = Field(default=False, alias="isSuperAdmin")
+    is_system_user: bool = Field(default=False, alias="isSystemUser")
+    is_company_admin: bool = Field(default=False, alias="isCompanyAdmin")
+
+
+class User(_BaseModel):
+    """An RTLS user.
+
+    The wire-format fields ``isSuperAdmin`` / ``isSystemUser`` /
+    ``isCompanyAdmin`` plus the raw ``role`` string are normalized into:
+
+    - ``role``: a single :class:`Role` enum value.
+    - ``raw_flags``: the four boolean flags untouched.
+    """
+
+    email: str
+    uid: str | None = None
+    first_name: str | None = Field(default=None, alias="first_name")
+    last_name: str | None = Field(default=None, alias="last_name")
+    raw_flags: UserFlags = Field(default_factory=UserFlags)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _gather_flags(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        # Lift the four wire flags into raw_flags. We keep them on the
+        # outer dict too in case downstream code (or the .raw property
+        # via extra="allow") wants them.
+        flags = {
+            k: data[k]
+            for k in (
+                "isSuperAdmin",
+                "isSystemUser",
+                "isCompanyAdmin",
+            )
+            if k in data
+        }
+        if flags:
+            data = {**data, "raw_flags": flags}
+        return data
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def role(self) -> Role:
+        """Derived role for the user.
+
+        Resolution order (boolean flags win over raw string):
+
+        1. ``is_super_admin`` → :attr:`Role.SYSTEM_ADMIN` (server-wide root).
+        2. ``is_company_admin`` → :attr:`Role.COMPANY_ADMIN`.
+        3. Raw ``role`` string, if it parses cleanly.
+        4. Default → :attr:`Role.PROJECT_USER`.
+
+        The ``is_system_user`` flag is intentionally not mapped to a
+        Role member — the server's role vocabulary has no system-user
+        entry; the flag remains accessible via ``user.raw_flags.is_system_user``
+        for callers that need it.
+        """
+        if self.raw_flags.is_super_admin:
+            return Role.SYSTEM_ADMIN
+        if self.raw_flags.is_company_admin:
+            return Role.COMPANY_ADMIN
+        raw_role = self.raw.get("role")
+        if isinstance(raw_role, str):
+            try:
+                return Role(raw_role.lower())
+            except ValueError:
+                pass
+        return Role.PROJECT_USER
+
+
+__all__ = ["Role", "User", "UserFlags"]

rtls_sdk/models/zone.py

@@ -0,0 +1,27 @@
+"""Zone model.
+
+A "zone" in RTLS-speak covers both static zones (areas defined by
+operators) and buffers (dynamic zones bound to a moving trackable). The
+``dynamic`` flag discriminates: ``False`` = static zone, ``True`` = buffer.
+"""
+
+from __future__ import annotations
+
+from ._base import _BaseModel
+
+
+class Zone(_BaseModel):
+    """A zone or buffer.
+
+    M1 ships the discriminator fields. M2 adds the geometric shape data
+    (polygon points, circle radius) and zone-type metadata.
+    """
+
+    uid: str
+    name: str
+    dynamic: bool = False
+    shape: str | None = None
+    trackable_object_uid: str | None = None
+
+
+__all__ = ["Zone"]

rtls_sdk/models/zone_event.py

@@ -0,0 +1,21 @@
+"""Zone-event model.
+
+Returned by ``GET /data/zone_events?format=json``. The CSV variant is
+returned as raw bytes by the reports surface in M7.
+"""
+
+from __future__ import annotations
+
+from ._base import _BaseModel
+
+
+class ZoneEvent(_BaseModel):
+    """A zone-traversal event (enter / exit / dwell)."""
+
+    uid: str | None = None
+    zone_uid: str | None = None
+    trackable_object_uid: str | None = None
+    event_type: str | None = None
+
+
+__all__ = ["ZoneEvent"]

rtls_sdk/resources/__init__.py

@@ -0,0 +1,49 @@
+"""Resource sub-clients exposed on :class:`RtlsClient`."""
+
+from .alarms import AlarmsAPI
+from .anchors import AnchorsAPI
+from .areas import AreasAPI
+from .associations import AssociationsAPI
+from .auth import AuthAPI
+from .companies import CompaniesAPI
+from .context import ContextAPI
+from .events import EventsAPI
+from .floorplans import FloorplansAPI
+from .groups import GroupsAPI
+from .logger import LoggerAPI
+from .messaging import MessagingAPI
+from .nodes import NodesAPI
+from .notifications import NotificationsAPI
+from .projects import ProjectsAPI
+from .reports import ReportsAPI
+from .sites import SitesAPI
+from .subscribers import SubscribersAPI
+from .system import SystemAPI
+from .tags import TagsAPI
+from .users import UsersAPI
+from .zones import ZonesAPI
+
+__all__ = [
+    "AlarmsAPI",
+    "AnchorsAPI",
+    "AreasAPI",
+    "AssociationsAPI",
+    "AuthAPI",
+    "CompaniesAPI",
+    "ContextAPI",
+    "EventsAPI",
+    "FloorplansAPI",
+    "GroupsAPI",
+    "LoggerAPI",
+    "MessagingAPI",
+    "NodesAPI",
+    "NotificationsAPI",
+    "ProjectsAPI",
+    "ReportsAPI",
+    "SitesAPI",
+    "SubscribersAPI",
+    "SystemAPI",
+    "TagsAPI",
+    "UsersAPI",
+    "ZonesAPI",
+]

rtls_sdk/resources/_base.py

@@ -0,0 +1,63 @@
+"""Base for resource sub-clients.
+
+Each ``RtlsClient`` attribute (``client.tags``, ``client.sites``, …) is an
+instance of a subclass of :class:`ResourceAPI`. The base provides the
+shared request helpers; subclasses translate REST paths into typed models.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+if TYPE_CHECKING:
+    from .._client import RtlsClient
+
+
+class ResourceAPI:
+    """Base for every resource sub-client."""
+
+    def __init__(self, client: RtlsClient) -> None:
+        self._client = client
+
+    def _get(
+        self,
+        path: str,
+        *,
+        params: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        return self._client._request("GET", path, params=params, headers=headers)
+
+    def _post(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        params: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        return self._client._request("POST", path, json=json, params=params, headers=headers)
+
+    def _put(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        params: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        return self._client._request("PUT", path, json=json, params=params, headers=headers)
+
+    def _delete(
+        self,
+        path: str,
+        *,
+        params: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        return self._client._request("DELETE", path, params=params, headers=headers)
+
+
+__all__ = ["ResourceAPI"]

rtls_sdk/resources/alarms.py

@@ -0,0 +1,108 @@
+"""Alarms resource sub-client."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from .._envelope import unwrap_resource, unwrap_resource_single
+from .._query import pack_array_param
+from .._time import to_epoch_ms
+from ..models import Alarm
+from ._base import ResourceAPI
+
+
+class AlarmsAPI(ResourceAPI):
+    """Read alarm events and (clear) existing alarms.
+
+    Three time-bounded reads:
+
+    - :meth:`list_active` — currently-open alarms.
+    - :meth:`list_for_site` — alarms in a site over a window.
+    - :meth:`list_for_area` — alarms in a single sublocation over a window.
+
+    The CSV export variants of these endpoints are deferred to the
+    reports surface in M7 (``client.reports.alarms_csv``).
+    """
+
+    def list_active(self) -> list[Alarm]:
+        response = self._get("/api/v2/alarms/active/")
+        items = unwrap_resource(response.json(), "alarms")
+        return [Alarm.from_wire(item) for item in items]
+
+    def list_for_site(
+        self,
+        start: datetime,
+        end: datetime,
+        *,
+        site_uid: str,
+        alarm_types: list[str] | None = None,
+    ) -> list[Alarm]:
+        """Return alarms raised at ``site_uid`` in ``[start, end]``.
+
+        ``alarm_types`` filters to specific alarm-type names (e.g.
+        ``["zone_violation", "buffer_violation"]``); ``None`` lists all.
+        Timestamps are converted to epoch milliseconds per the server's
+        contract (RESEARCH §2). Naive ``datetime`` raises ``ValueError``.
+        """
+        params: list[tuple[str, str]] = [
+            ("from", str(to_epoch_ms(start, arg_name="start"))),
+            ("to", str(to_epoch_ms(end, arg_name="end"))),
+            ("location_uid", site_uid),
+            ("format", "json"),
+            ("report", "1"),
+        ]
+        if alarm_types:
+            params.extend(pack_array_param("alarm_type_name", alarm_types))
+        response = self._get("/api/v2/alarms", params=params)
+        items = unwrap_resource(response.json(), "alarms")
+        return [Alarm.from_wire(item) for item in items]
+
+    def list_for_area(
+        self,
+        start: datetime,
+        end: datetime,
+        *,
+        area_uid: str,
+        alarm_types: list[str] | None = None,
+    ) -> list[Alarm]:
+        """Return alarms raised in a sublocation over a window.
+
+        Same conventions as :meth:`list_for_site`; the scoping parameter
+        is ``sublocation_uid`` instead of ``location_uid``.
+        """
+        params: list[tuple[str, str]] = [
+            ("from", str(to_epoch_ms(start, arg_name="start"))),
+            ("to", str(to_epoch_ms(end, arg_name="end"))),
+            ("sublocation_uid", area_uid),
+            ("format", "json"),
+            ("report", "1"),
+        ]
+        if alarm_types:
+            params.extend(pack_array_param("alarm_type_name", alarm_types))
+        response = self._get("/api/v2/alarms", params=params)
+        items = unwrap_resource(response.json(), "alarms")
+        return [Alarm.from_wire(item) for item in items]
+
+    def update(self, uid: str, **fields: Any) -> Alarm:
+        """Update / clear an alarm.
+
+        Uses **PUT** despite the public docs saying POST — the JS
+        reference client uses PUT and the server accepts only PUT
+        (RESEARCH Discrepancy #3).
+        """
+        response = self._put(f"/api/v2/alarms/{uid}", json=fields)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "alarms")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        # The server may also return the alarm under the bare-array
+        # envelope ``{alarms: [...]}``; take the first row if so.
+        if isinstance(item, dict) and "alarms" in item and isinstance(item["alarms"], list):
+            first = item["alarms"][0] if item["alarms"] else {}
+            item = first if isinstance(first, dict) else {}
+        return Alarm.from_wire(item if isinstance(item, dict) else {})
+
+
+__all__ = ["AlarmsAPI"]