rtls-sdk 0.2.0__py3-none-any.whl

rtls_sdk/compounds/zones.py

@@ -0,0 +1,203 @@
+"""Compound zone workflows.
+
+Static zones go through the raw path. Dynamic (buffer) zones bound to a
+trackable need the additional rebinding plumbing this module provides.
+
+Step-name conventions (stable):
+
+- ``create``: ``create_zone``, ``set_trackable_binding``.
+- ``update``: ``clear_old_binding``, ``set_new_binding``, ``update_zone``.
+- ``delete``: ``clear_binding``, ``delete_zone``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from ..errors import PartialFailureError, RtlsError
+from ..models import Zone
+from .tags import UNSET, _Unset
+
+if TYPE_CHECKING:
+    from .._client import RtlsClient
+
+
+logger = logging.getLogger("rtls_sdk.compounds.zones")
+
+
+def create_zone(
+    client: RtlsClient,
+    name: str,
+    *,
+    dynamic: bool = False,
+    trackable_uid: str | None = None,
+    **fields: Any,
+) -> Zone:
+    """Create a zone, binding it to a trackable if requested.
+
+    For static zones the compound collapses to a single
+    ``zones.create_raw`` call. For dynamic zones with a ``trackable_uid``
+    the SDK additionally writes ``self_zone_uid`` onto the trackable
+    after the zone is created.
+
+    Rollback: if the trackable update fails after the zone is created,
+    the SDK best-effort deletes the orphan zone before raising.
+    """
+    if dynamic:
+        fields = {**fields, "dynamic": True}
+        if trackable_uid:
+            fields["trackable_object_uid"] = trackable_uid
+
+    zone = client.zones.create_raw(name=name, **fields)
+    completed = ["create_zone"]
+
+    if dynamic and trackable_uid:
+        try:
+            client.tags.update_raw(trackable_uid, self_zone_uid=zone.uid)
+        except RtlsError as exc:
+            try:
+                client.zones.delete_raw(zone.uid)
+            except RtlsError as rollback_exc:
+                logger.warning("rollback of created zone %s failed: %s", zone.uid, rollback_exc)
+            raise PartialFailureError(
+                f"zones.create: set_trackable_binding failed: {exc}",
+                completed_steps=completed,
+                failed_step="set_trackable_binding",
+                cause=exc,
+                partial_result={"zone_uid": zone.uid, "trackable_uid": trackable_uid},
+            ) from exc
+        completed.append("set_trackable_binding")
+
+    return zone
+
+
+def update_zone(
+    client: RtlsClient,
+    uid: str,
+    *,
+    trackable_uid: str | None | _Unset = UNSET,
+    **fields: Any,
+) -> Zone:
+    """Update a zone, re-binding the trackable if needed.
+
+    Pass ``trackable_uid=...`` (default) to leave any current binding
+    untouched. Pass ``trackable_uid=None`` to clear the binding;
+    ``trackable_uid="t-x"`` to rebind.
+
+    The rebinding sequence is intentionally three steps:
+
+    1. Load the existing zone to discover the current binding.
+    2. If changed: clear old binding (``self_zone_uid=None`` on old tag).
+    3. If new binding requested: set new (``self_zone_uid=zone.uid`` on
+       new tag).
+    4. ``zones.update_raw`` for whatever field changes the caller passed.
+
+    If step 3 fails after step 2 succeeded, the SDK best-effort restores
+    the old binding before raising. If that restore also fails, the old
+    trackable is left dangling and the exception's ``partial_result``
+    names what needs manual reconciliation.
+    """
+    completed: list[str] = []
+
+    # Step 1: discover current binding if a change is requested.
+    current_trackable: str | None = None
+    if not isinstance(trackable_uid, _Unset):
+        try:
+            current = client.zones.get(uid)
+            current_trackable = current.trackable_object_uid
+        except RtlsError as exc:
+            raise PartialFailureError(
+                f"zones.update: failed to load current binding: {exc}",
+                completed_steps=completed,
+                failed_step="load_zone",
+                cause=exc,
+            ) from exc
+
+        # Step 2: clear old binding if we're rebinding.
+        if current_trackable and current_trackable != trackable_uid:
+            try:
+                client.tags.update_raw(current_trackable, self_zone_uid=None)
+            except RtlsError as exc:
+                raise PartialFailureError(
+                    f"zones.update: clear_old_binding failed: {exc}",
+                    completed_steps=completed,
+                    failed_step="clear_old_binding",
+                    cause=exc,
+                    partial_result={"zone_uid": uid, "old_trackable_uid": current_trackable},
+                ) from exc
+            completed.append("clear_old_binding")
+
+        # Step 3: set new binding.
+        if trackable_uid and trackable_uid != current_trackable:
+            try:
+                client.tags.update_raw(trackable_uid, self_zone_uid=uid)
+            except RtlsError as exc:
+                # Best-effort restore of old binding.
+                if current_trackable:
+                    try:
+                        client.tags.update_raw(current_trackable, self_zone_uid=uid)
+                    except RtlsError as restore_exc:
+                        logger.warning(
+                            "zones.update: restore of old binding on %s failed: %s",
+                            current_trackable,
+                            restore_exc,
+                        )
+                raise PartialFailureError(
+                    f"zones.update: set_new_binding failed: {exc}",
+                    completed_steps=completed,
+                    failed_step="set_new_binding",
+                    cause=exc,
+                    partial_result={
+                        "zone_uid": uid,
+                        "old_trackable_uid": current_trackable,
+                        "new_trackable_uid": trackable_uid,
+                    },
+                ) from exc
+            completed.append("set_new_binding")
+
+    # Step 4: write field updates.
+    try:
+        zone = client.zones.update_raw(uid, **fields)
+    except RtlsError as exc:
+        raise PartialFailureError(
+            f"zones.update: update_zone failed: {exc}",
+            completed_steps=completed,
+            failed_step="update_zone",
+            cause=exc,
+        ) from exc
+    completed.append("update_zone")
+    return zone
+
+
+def delete_zone(client: RtlsClient, uid: str) -> None:
+    """Delete a zone, clearing any dynamic-trackable binding first.
+
+    Step names: ``load_zone``, ``clear_binding``, ``delete_zone``.
+
+    ``clear_binding`` failure is logged but does not abort the delete —
+    the orphan trackable.``self_zone_uid`` is the lesser problem than
+    leaving the zone behind.
+    """
+    try:
+        zone = client.zones.get(uid)
+    except RtlsError:
+        # If we can't fetch it, fall through to the delete — the server
+        # will return 404 there if the zone doesn't exist.
+        client.zones.delete_raw(uid)
+        return
+
+    if zone.dynamic and zone.trackable_object_uid:
+        try:
+            client.tags.update_raw(zone.trackable_object_uid, self_zone_uid=None)
+        except RtlsError as exc:
+            logger.warning(
+                "zones.delete: clear_binding on tag %s failed: %s",
+                zone.trackable_object_uid,
+                exc,
+            )
+
+    client.zones.delete_raw(uid)
+
+
+__all__ = ["create_zone", "delete_zone", "update_zone"]

rtls_sdk/errors.py

@@ -0,0 +1,238 @@
+"""Exception hierarchy for the RTLS SDK.
+
+Every method in the public API raises at most one type from this module on
+failure. HTTP status codes are mapped to typed exceptions at the response
+boundary so user code never has to inspect ``response.status_code``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class RtlsError(Exception):
+    """Base for every SDK exception.
+
+    Attributes
+    ----------
+    status_code
+        HTTP status code, or ``None`` for transport-level failures.
+    request_url
+        The URL the SDK attempted to call. Includes the path; query string
+        may be present.
+    request_method
+        Uppercase HTTP method (``"GET"``, ``"POST"``, …).
+    response_body
+        Parsed response body with secrets redacted, or ``None`` if the
+        server returned no parseable body.
+    error_envelope
+        The server's ``error`` or ``message`` field if either was present.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        request_url: str | None = None,
+        request_method: str | None = None,
+        response_body: Any = None,
+        error_envelope: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.request_url = request_url
+        self.request_method = request_method
+        self.response_body = response_body
+        self.error_envelope = error_envelope
+
+
+class ConnectionError(RtlsError):
+    """Transport-level failure: DNS, connection refused, read timeout, TLS."""
+
+
+class AuthenticationError(RtlsError):
+    """401 after the SDK already tried to re-authenticate, or no credentials.
+
+    For ``from_env()`` and explicit-credential clients this means the
+    username/password is invalid (or the token was revoked). For
+    bring-your-own-token clients this means the token is invalid or expired;
+    the caller must acquire a fresh token and reconstruct the client.
+    """
+
+
+class PermissionDenied(RtlsError):
+    """403. The authenticated user lacks permission for the requested action."""
+
+
+class NotFound(RtlsError):
+    """404. The requested resource does not exist (or is hidden by scope)."""
+
+
+class Conflict(RtlsError):
+    """409. The request conflicts with current server state (e.g. duplicate MAC)."""
+
+
+class ValidationError(RtlsError):
+    """422. The request body failed server-side validation.
+
+    ``field_errors`` is populated when the server returned a structured
+    field-level error response. The shape varies by endpoint; consult the
+    raised exception's ``response_body`` for the raw form.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        field_errors: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.field_errors: dict[str, Any] = field_errors or {}
+
+
+class RateLimited(RtlsError):
+    """429 or 423. Server rate-limit hit.
+
+    ``retry_after_seconds`` is parsed from the ``Retry-After`` header when
+    present. The SDK does not auto-retry; the caller decides whether to
+    sleep and try again.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after_seconds: float | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class ServerError(RtlsError):
+    """5xx. The server failed. Retry at the caller's discretion."""
+
+
+class PartialFailureError(RtlsError):
+    """A compound multi-call operation failed partway through.
+
+    Raised by compound SDK methods (M4+) when an intermediate step succeeds
+    and a subsequent step fails. The exception carries enough context for
+    the caller to reason about the inconsistent state and decide whether
+    to roll back further manually.
+
+    Attributes
+    ----------
+    completed_steps
+        Stable step-name strings for each call that succeeded before the
+        failure. Documented per-method.
+    failed_step
+        Stable step-name string identifying the call that raised.
+    cause
+        The underlying exception that caused the failure. Also chained via
+        ``raise ... from cause``.
+    partial_result
+        Identifiers for any partially-created resources, so the caller can
+        clean up manually. Stable keys documented per-method.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        completed_steps: list[str],
+        failed_step: str,
+        cause: RtlsError,
+        partial_result: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.completed_steps = completed_steps
+        self.failed_step = failed_step
+        self.cause = cause
+        self.partial_result: dict[str, Any] = partial_result or {}
+
+
+class ReportError(RtlsError):
+    """Base for report-specific failures."""
+
+
+class ReportFailed(ReportError):
+    """The server reported an error in the report's status payload."""
+
+
+class ReportTimeout(ReportError):
+    """The SDK's polling deadline elapsed before the report completed.
+
+    ``report_uid`` carries the in-flight report's identifier so the caller
+    can resume polling later by calling ``reports.get(report_uid)``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        report_uid: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.report_uid = report_uid
+
+
+_STATUS_TO_EXC: dict[int, type[RtlsError]] = {
+    401: AuthenticationError,
+    403: PermissionDenied,
+    404: NotFound,
+    409: Conflict,
+    422: ValidationError,
+    423: RateLimited,
+    429: RateLimited,
+}
+
+
+def exception_for_status(status_code: int) -> type[RtlsError]:
+    """Map an HTTP status code to the SDK exception class to raise."""
+    if status_code in _STATUS_TO_EXC:
+        return _STATUS_TO_EXC[status_code]
+    if 500 <= status_code < 600:
+        return ServerError
+    return RtlsError
+
+
+def parse_error_envelope(body: Any) -> str | None:
+    """Tolerate both documented server error envelope shapes.
+
+    The server returns either ``{"success": false, "error": "..."}`` or
+    ``{"message": "..."}`` depending on the endpoint (RESEARCH §2). Return
+    whichever string is present, or ``None``.
+    """
+    if not isinstance(body, dict):
+        return None
+    err = body.get("error")
+    if isinstance(err, str):
+        return err
+    msg = body.get("message")
+    if isinstance(msg, str):
+        return msg
+    return None
+
+
+__all__ = [
+    "AuthenticationError",
+    "Conflict",
+    "ConnectionError",
+    "NotFound",
+    "PartialFailureError",
+    "PermissionDenied",
+    "RateLimited",
+    "ReportError",
+    "ReportFailed",
+    "ReportTimeout",
+    "RtlsError",
+    "ServerError",
+    "ValidationError",
+    "exception_for_status",
+    "parse_error_envelope",
+]

rtls_sdk/models/__init__.py

@@ -0,0 +1,73 @@
+"""Public model surface for the RTLS SDK."""
+
+from .alarm import Alarm
+from .anchor import Anchor
+from .area import Area
+from .association import Association
+from .bulk import BulkFailure, BulkResult
+from .company import Company
+from .csv_blob import CsvBlob
+from .floorplan import Floorplan
+from .group import Group
+from .heatmap import Heatmap, HeatmapInput
+from .import_result import ImportResult
+from .node import Node
+from .notification import NotificationProfile, NotificationType
+from .position import Position
+from .project import Project
+from .pws import PwsEvent, PwsReport
+from .report import Report, ReportType
+from .session_context import SessionContext
+from .site import Site
+from .subscriber import Subscriber, SubscriberAddresses, SystemSubscriber
+from .system import Capabilities, Connection, Host, Uptime, Version, WsHost
+from .system_health import SystemHealth
+from .tag import Tag
+from .tag_template import TagTemplate
+from .user import Role, User, UserFlags
+from .zone import Zone
+from .zone_event import ZoneEvent
+
+__all__ = [
+    "Alarm",
+    "Anchor",
+    "Area",
+    "Association",
+    "BulkFailure",
+    "BulkResult",
+    "Capabilities",
+    "Company",
+    "Connection",
+    "CsvBlob",
+    "Floorplan",
+    "Group",
+    "Heatmap",
+    "HeatmapInput",
+    "Host",
+    "ImportResult",
+    "Node",
+    "NotificationProfile",
+    "NotificationType",
+    "Position",
+    "Project",
+    "PwsEvent",
+    "PwsReport",
+    "Report",
+    "ReportType",
+    "Role",
+    "SessionContext",
+    "Site",
+    "Subscriber",
+    "SubscriberAddresses",
+    "SystemHealth",
+    "SystemSubscriber",
+    "Tag",
+    "TagTemplate",
+    "Uptime",
+    "User",
+    "UserFlags",
+    "Version",
+    "WsHost",
+    "Zone",
+    "ZoneEvent",
+]

rtls_sdk/models/_base.py

@@ -0,0 +1,46 @@
+"""Base pydantic model used by every SDK model.
+
+Models are frozen (immutable from the user's perspective — there's no
+``model.save()`` pattern in this SDK). They accept extra keys to remain
+forward-compatible when the server adds fields, and expose the original
+wire payload via ``.raw`` so callers can read newly-added fields without
+waiting for an SDK release.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+from typing_extensions import Self
+
+
+class _BaseModel(BaseModel):
+    """Shared base — frozen, alias-tolerant, extra-tolerant."""
+
+    model_config = ConfigDict(
+        frozen=True,
+        populate_by_name=True,
+        extra="allow",
+    )
+
+    @classmethod
+    def from_wire(cls, payload: dict[str, Any]) -> Self:
+        """Build an instance from a raw server payload, capturing the
+        original dict on ``.raw`` for forward-compat field access."""
+        instance = cls.model_validate(payload)
+        # frozen=True blocks normal assignment; bypass via object.__setattr__.
+        object.__setattr__(instance, "_raw", payload)
+        return instance
+
+    @property
+    def raw(self) -> dict[str, Any]:
+        """Return the original server payload that built this model.
+
+        Use this only to read fields the SDK doesn't know about yet —
+        the shape is unsupported and may break across server versions.
+        """
+        return getattr(self, "_raw", {})
+
+
+__all__ = ["_BaseModel"]

rtls_sdk/models/alarm.py

@@ -0,0 +1,23 @@
+"""Alarm model."""
+
+from __future__ import annotations
+
+from ._base import _BaseModel
+
+
+class Alarm(_BaseModel):
+    """An alarm event raised by the server.
+
+    Shape is consistent across the active / period / area / site endpoints
+    — the ``format=`` query parameter switches between JSON (returns
+    Alarm) and CSV (raw bytes, surfaced by report methods, not here).
+    """
+
+    uid: str | None = None
+    alarm_type_name: str | None = None
+    location_uid: str | None = None
+    sublocation_uid: str | None = None
+    trackable_object_uid: str | None = None
+
+
+__all__ = ["Alarm"]

rtls_sdk/models/anchor.py

@@ -0,0 +1,25 @@
+"""WIN anchor model."""
+
+from __future__ import annotations
+
+from ._base import _BaseModel
+
+
+class Anchor(_BaseModel):
+    """A WIN (wireless indoor navigation) anchor — fixed-position beacon.
+
+    Fields beyond ``uid`` / ``name`` / ``mac_address`` / ``sublocation_uid``
+    are optional placement metadata returned on create / read.
+    """
+
+    uid: str
+    name: str | None = None
+    mac_address: str | None = None
+    sublocation_uid: str | None = None
+    position_x: float | None = None
+    position_y: float | None = None
+    position_z: float | None = None
+    rotation: float | None = None
+
+
+__all__ = ["Anchor"]

rtls_sdk/models/area.py

@@ -0,0 +1,28 @@
+"""Area (sublocation) model."""
+
+from __future__ import annotations
+
+from ._base import _BaseModel
+
+
+class Area(_BaseModel):
+    """A sublocation inside a site.
+
+    Areas (also called sublocations) are the geographic units that zones,
+    positions, and trackables are scoped to. Fields beyond ``uid`` /
+    ``name`` / ``location_uid`` are optional placement metadata returned
+    on create / read.
+    """
+
+    uid: str
+    name: str | None = None
+    location_uid: str | None = None
+    description: str | None = None
+    position_x: float | None = None
+    position_y: float | None = None
+    width: float | None = None
+    height: float | None = None
+    rotation: float | None = None
+
+
+__all__ = ["Area"]

rtls_sdk/models/association.py

@@ -0,0 +1,48 @@
+"""Trackable-association model.
+
+The wire envelope differs between ``GET /trackable_objects_associations/``
+(``{trackable_objects_associations: [...]}``) and ``POST /…/`` create
+(``{association: ...}``). The SDK uses one ``Association`` model for both.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import model_validator
+
+from .._time import from_epoch_ms
+from ._base import _BaseModel
+
+
+class Association(_BaseModel):
+    """A binding between a hardware MAC address and a trackable.
+
+    Associations are time-bounded: a trackable can wear different physical
+    tags over its lifetime. ``closed_at`` is ``None`` on an open binding.
+    """
+
+    uid: str | None = None
+    mac_address: str | None = None
+    obj_uid: str | None = None
+    opened_at: datetime | None = None
+    closed_at: datetime | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _rewrite_aliases(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        out = dict(data)
+        for src, dst in (("start", "opened_at"), ("end", "closed_at")):
+            if dst not in out and src in out and out[src] is not None:
+                value = out[src]
+                if isinstance(value, (int, float)) and not isinstance(value, bool):
+                    out[dst] = from_epoch_ms(value)
+                else:
+                    out[dst] = value
+        return out
+
+
+__all__ = ["Association"]