rtls-sdk 0.2.0__py3-none-any.whl

rtls_sdk/resources/anchors.py

@@ -0,0 +1,147 @@
+"""WIN anchors resource sub-client.
+
+A WIN anchor is a **placed beacon**, identified by its server-issued
+``uid`` — *not* by a MAC address. The MAC address belongs to a
+:class:`Node` (the hardware), and the binding between a node and an
+anchor is an :class:`Association` (``anchor_assoc``). The desktop
+site-plan client aggregates the three for display, but the server
+keeps them separate.
+
+The server's ``create_win_anchor`` schema requires:
+
+- ``name`` (string)
+- ``type`` (``ANCHOR`` or ``BRIDGE``; defaults to ``ANCHOR``)
+- ``position`` (object): ``{x, y, z, sublocation_uid}`` (or ``sl_uid``)
+
+Optional: ``locked``, ``acc_config``, ``bt_config``, ``state``,
+``device_config``.
+
+If your workflow is "I have a MAC and want a placed anchor bound to
+it," that's three calls — anchor create + node create + association
+create. A compound that wraps the saga is planned for a future
+milestone; for now, drive the three primitives in your application.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._envelope import unwrap_resource, unwrap_resource_single
+from ..models import Anchor
+from ._base import ResourceAPI
+
+_VALID_ANCHOR_TYPES: frozenset[str] = frozenset({"ANCHOR", "BRIDGE"})
+
+
+class AnchorsAPI(ResourceAPI):
+    """List, create, update, and delete WIN anchors in the current scope.
+
+    Anchors are present only when the WIN module is enabled on the
+    server. Some deployments return 404 on the list endpoint — the SDK
+    raises :class:`NotFound`.
+
+    Server-side anchor deletion closes open anchor associations
+    automatically; the SDK does not pre-emptively call
+    :meth:`AssociationsAPI.close`.
+
+    ``list`` is defined last (class-scope shadow workaround).
+    """
+
+    def create(
+        self,
+        *,
+        name: str,
+        position: dict[str, Any],
+        type: str = "ANCHOR",
+        **fields: Any,
+    ) -> Anchor:
+        """Create a placed anchor (WIN beacon).
+
+        Parameters
+        ----------
+        name
+            Display name. Required.
+        position
+            Placement object. Must include ``x``, ``y``, ``z`` numbers
+            and either ``sublocation_uid`` or ``sl_uid``. The server's
+            Joi schema accepts both alias names.
+        type
+            ``"ANCHOR"`` (default) or ``"BRIDGE"``. Other values are
+            rejected with ``ValueError`` before any HTTP call.
+        **fields
+            Optional pass-through fields the server schema permits:
+            ``locked`` (bool), ``acc_config`` / ``bt_config`` /
+            ``state`` (dicts), ``device_config`` (dict with
+            ``battery``, ``model``, ``pwr_profile``, plus arbitrary
+            keys up to 64 bytes).
+
+        Examples
+        --------
+        >>> anchor = client.anchors.create(
+        ...     name="Anchor 7",
+        ...     position={"x": 1.0, "y": 2.0, "z": 0.0, "sublocation_uid": area.uid},
+        ... )
+        >>> anchor.uid
+        'NELkj…'
+
+        Notes
+        -----
+        ``win_anchor`` does NOT carry a ``mac_address`` field. If you
+        want to bind a piece of hardware (with a MAC) to this anchor,
+        also call :meth:`NodesAPI.create` and
+        :meth:`AssociationsAPI.create` (or use the planned
+        ``anchors.create_with_node`` compound when it lands).
+        """
+        if type not in _VALID_ANCHOR_TYPES:
+            raise ValueError(
+                f"anchor type must be one of {sorted(_VALID_ANCHOR_TYPES)}; got {type!r}"
+            )
+        body: dict[str, Any] = {
+            "name": name,
+            "type": type,
+            "position": position,
+            **fields,
+        }
+        response = self._post("/api/v2/win_anchors/", json=body)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "win_anchor")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Anchor.from_wire(item)
+
+    def update(self, uid: str, **fields: Any) -> Anchor:
+        """Update an anchor's fields.
+
+        Free-form ``**fields`` to match the server's permissive
+        ``update_win_anchor`` schema. Validates ``type`` when present
+        (must be ``ANCHOR`` or ``BRIDGE``). Does NOT validate
+        ``position`` structure — caller is responsible for shape.
+        """
+        if "type" in fields and fields["type"] not in _VALID_ANCHOR_TYPES:
+            raise ValueError(
+                f"anchor type must be one of {sorted(_VALID_ANCHOR_TYPES)}; got {fields['type']!r}"
+            )
+        response = self._put(f"/api/v2/win_anchors/{uid}", json=fields)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "win_anchor")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Anchor.from_wire(item)
+
+    def delete(self, uid: str) -> None:
+        """Delete an anchor.
+
+        Server-side closes any open anchor associations referencing it;
+        the SDK does NOT pre-emptively call ``associations.close``.
+        """
+        self._delete(f"/api/v2/win_anchors/{uid}")
+
+    def list(self) -> list[Anchor]:
+        response = self._get("/api/v2/win_anchors/")
+        items = unwrap_resource(response.json(), "win_anchors")
+        return [Anchor.from_wire(item) for item in items]
+
+
+__all__ = ["AnchorsAPI"]

rtls_sdk/resources/areas.py

@@ -0,0 +1,78 @@
+"""Areas (sublocations) resource sub-client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._envelope import unwrap_resource, unwrap_resource_single
+from ..models import Area
+from ._base import ResourceAPI
+
+
+class AreasAPI(ResourceAPI):
+    """List, create, update, and delete areas (sublocations) in the current scope.
+
+    The wire-format name is ``sublocations``; SDK exposes them as
+    ``areas`` to match operator terminology.
+
+    Cascade contract: ``areas.delete(uid)`` removes the area and every
+    floorplan, anchor, and zone bound to 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, *, location_uid: str, **fields: Any) -> Area:
+        """Create an area inside ``location_uid``.
+
+        Parameters
+        ----------
+        name
+            Display name.
+        location_uid
+            Parent site uid. Required by the server.
+        **fields
+            Additional optional placement metadata: ``description``,
+            ``position_x``, ``position_y``, ``width``, ``height``,
+            ``rotation``.
+
+        Examples
+        --------
+        >>> area = client.areas.create(name="Bay 3", location_uid=site.uid)
+        """
+        body: dict[str, Any] = {"name": name, "location_uid": location_uid, **fields}
+        response = self._post("/api/v2/sublocations/", json=body)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "sublocation")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Area.from_wire(item)
+
+    def update(self, uid: str, **fields: Any) -> Area:
+        """Update an area's fields.
+
+        The body is the kwargs verbatim — the SDK does not enforce an
+        allowlist on area updates, mirroring the desktop site-plan
+        client's ``updateItem`` flow.
+        """
+        response = self._put(f"/api/v2/sublocations/{uid}", json=fields)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "sublocation")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Area.from_wire(item)
+
+    def delete(self, uid: str) -> None:
+        """Delete an area (cascades to its floorplans / anchors / zones server-side)."""
+        self._delete(f"/api/v2/sublocations/{uid}")
+
+    def list(self) -> list[Area]:
+        """Return all areas visible to the current scope."""
+        response = self._get("/api/v2/sublocations/")
+        items = unwrap_resource(response.json(), "sublocations")
+        return [Area.from_wire(item) for item in items]
+
+
+__all__ = ["AreasAPI"]

rtls_sdk/resources/associations.py

@@ -0,0 +1,157 @@
+"""Trackable-association resource sub-client."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from .._envelope import unwrap_resource, unwrap_resource_single
+from .._query import normalize_mac
+from .._time import to_epoch_seconds
+from ..errors import RtlsError
+from ..models import Association, BulkFailure, BulkResult
+from ._base import ResourceAPI
+
+
+class AssociationsAPI(ResourceAPI):
+    """Read trackable ↔ MAC associations.
+
+    Two endpoints surface here:
+
+    - :meth:`list` reads currently-open associations.
+    - :meth:`list_active_in_period` reads associations active in a window;
+      uses a distinct endpoint path (``/track_assoc``) and — uniquely
+      among RTLS endpoints — accepts ``start`` / ``end`` as **epoch
+      seconds**, not milliseconds (RESEARCH §4).
+
+    ``list`` is defined last (class-scope shadow workaround).
+    """
+
+    def list_active_in_period(self, start: datetime, end: datetime) -> list[Association]:
+        """Return associations active during ``[start, end]``.
+
+        The SDK converts ``datetime`` to epoch seconds for this endpoint.
+        Pass timezone-aware datetimes; naive values raise ``ValueError``.
+        """
+        params = {
+            "start": to_epoch_seconds(start, arg_name="start"),
+            "end": to_epoch_seconds(end, arg_name="end"),
+        }
+        response = self._get("/api/v2/track_assoc", params=params)
+        items = unwrap_resource(response.json(), "trackable_objects_associations")
+        return [Association.from_wire(item) for item in items]
+
+    def create(self, mac_address: str, trackable_uid: str) -> Association:
+        """Create a trackable-association (bind a MAC to a tag).
+
+        The MAC is normalized to bare 12-hex lowercase before sending
+        (server validates ``/^[a-fA-F0-9]{12}$/``).
+
+        Note: this binds a node (by MAC) to a TAG (`obj_uid`). To bind a
+        node to a placed ANCHOR (`win_uid`), the wire endpoint is
+        ``/win_anchor_associations`` — that resource is not yet exposed
+        on the SDK (planned for a future milestone alongside
+        ``anchors.create_with_node``).
+        """
+        body = {"mac_address": normalize_mac(mac_address), "obj_uid": trackable_uid}
+        response = self._post("/api/v2/trackable_objects_associations/", json=body)
+        payload = response.json()
+        # Create returns the singular envelope {association: ...}; the SDK
+        # tolerates both shapes.
+        try:
+            item = unwrap_resource_single(payload, "association")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Association.from_wire(item)
+
+    def close(
+        self,
+        association: Association | str | None = None,
+        *,
+        mac_address: str | None = None,
+        trackable_uid: str | None = None,
+    ) -> Association:
+        """Close an open association.
+
+        The endpoint is ``PUT /trackable_objects_associations/close`` and
+        the server identifies the association by ``mac_address`` OR
+        ``obj_uid`` (the trackable's uid) in the body — **not** by the
+        association's own uid (the server's close-handler reads only
+        ``req.body.mac_address`` and ``req.body.obj_uid``). M14 regression
+        — earlier ``close(uid)`` sent ``{"uid": "..."}`` and the server
+        replied ``"No mac or trackable object uid specified."``.
+
+        Three accepted call shapes:
+
+        - ``close(association)`` — pass the :class:`Association` object
+          returned by :meth:`create` / :meth:`list`; the SDK picks
+          ``mac_address`` or ``obj_uid`` from it.
+        - ``close(association_uid)`` — pass the association's own uid;
+          the SDK does one extra ``list()`` to resolve the identifying
+          fields.
+        - ``close(mac_address=..., trackable_uid=...)`` — pass either
+          identifier explicitly.
+        """
+        if isinstance(association, Association):
+            mac_address = mac_address or association.mac_address
+            trackable_uid = trackable_uid or association.obj_uid
+        elif isinstance(association, str):
+            # Look up by association uid (extra round-trip — callers can
+            # avoid this by passing the Association object directly).
+            for existing in self.list():
+                if existing.uid == association:
+                    mac_address = mac_address or existing.mac_address
+                    trackable_uid = trackable_uid or existing.obj_uid
+                    break
+
+        body: dict[str, str] = {}
+        if mac_address:
+            body["mac_address"] = mac_address
+        if trackable_uid:
+            body["obj_uid"] = trackable_uid
+        if not body:
+            raise ValueError(
+                "associations.close: provide an Association, an association uid, "
+                "or mac_address / trackable_uid kwargs"
+            )
+
+        response = self._put("/api/v2/trackable_objects_associations/close", json=body)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "association")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Association.from_wire(item)
+
+    def bulk_create(self, pairs: list[tuple[str, str]]) -> BulkResult[Association]:
+        """Create many associations, one at a time, continue-on-error.
+
+        Parameters
+        ----------
+        pairs
+            List of ``(mac_address, trackable_uid)`` tuples.
+
+        Returns
+        -------
+        BulkResult[Association]
+            ``succeeded`` lists the created associations; ``failures``
+            carries per-row errors.
+        """
+        result: BulkResult[Association] = BulkResult()
+        for mac, tag_uid in pairs:
+            try:
+                result.succeeded.append(self.create(mac, tag_uid))
+            except RtlsError as exc:
+                result.failures.append(
+                    BulkFailure(error=exc, input={"mac_address": mac, "obj_uid": tag_uid})
+                )
+            # ValueError from MAC normalization (malformed input) is a
+            # programmer error — propagates out and aborts the bulk.
+        return result
+
+    def list(self) -> list[Association]:
+        response = self._get("/api/v2/trackable_objects_associations/")
+        items = unwrap_resource(response.json(), "trackable_objects_associations")
+        return [Association.from_wire(item) for item in items]
+
+
+__all__ = ["AssociationsAPI"]

rtls_sdk/resources/auth.py

@@ -0,0 +1,63 @@
+"""Auth / capabilities resource sub-client."""
+
+from __future__ import annotations
+
+from ..compounds import auth as _compound
+from ..errors import RtlsError
+from ..models import Capabilities, User
+from ._base import ResourceAPI
+
+
+class AuthAPI(ResourceAPI):
+    """User-facing auth helpers — capabilities probe and ``whoami``.
+
+    Note that the active SDK token is *not* exposed here. Mutating
+    operations (login, logout, change-password) land in M5.
+    """
+
+    def whoami(self) -> User:
+        """Return the currently-authenticated user.
+
+        Delegates to :meth:`UsersAPI.me` — composed via a search of
+        ``GET /users?withProjects=true`` for the row matching the SDK's
+        stored auth email. See ``UsersAPI.me`` for details.
+        """
+        return self._client.users.me()
+
+    def capabilities(self) -> Capabilities:
+        """Probe whether SSO is configured + infer the API version.
+
+        Calls ``GET /auth/sso/log_in``. A successful response means SSO is
+        configured (``sso=True``, ``api_version="2.1"``); any
+        :class:`RtlsError` from the call means SSO is unavailable
+        (``sso=False``, ``api_version="2.0"``). This mirrors the JS
+        reference client's "rejection-is-the-signal" heuristic
+        (RESEARCH §4 "Probe SSO support").
+        """
+        try:
+            self._get("/api/v2/auth/sso/log_in")
+        except RtlsError:
+            return Capabilities(sso=False, api_version="2.0")
+        return Capabilities(sso=True, api_version="2.1")
+
+    def change_password(self, old_password: str, new_password: str) -> None:
+        """Change the current user's password and re-authenticate the SDK.
+
+        Four steps: validate the old password, validate the new
+        password, ``PUT /users/changePassword``, then clear the cached
+        token and force a fresh login with the new credentials. After a
+        successful run, the SDK's stored password is the new one.
+
+        Step names: ``validate_old``, ``validate_new``,
+        ``change_password``, ``reauthenticate``.
+
+        If the re-authentication step fails (server accepted the change
+        but the new login can't proceed), the SDK raises
+        :class:`AuthenticationError` with a message explaining that the
+        in-memory state is now stale. The caller should reconstruct the
+        client with the new password.
+        """
+        _compound.change_password(self._client, old_password, new_password)
+
+
+__all__ = ["AuthAPI"]

rtls_sdk/resources/companies.py

@@ -0,0 +1,79 @@
+"""Companies resource sub-client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._envelope import unwrap_resource, unwrap_resource_single
+from ..models import Company
+from ._base import ResourceAPI
+
+
+class CompaniesAPI(ResourceAPI):
+    """List, create, update, and delete companies.
+
+    ``list`` is defined last (class-scope shadow workaround).
+    """
+
+    def create(
+        self,
+        name: str,
+        *,
+        admin_email: str,
+        admin_password: str,
+        admin_role: str = "company_admin",
+        **company_fields: Any,
+    ) -> Company:
+        """Create a new company and seed it with an admin user.
+
+        Per RESEARCH §1, ``POST /companies/`` accepts a body like
+        ``{company: {...}, user: {email, password, role}}`` — the SDK
+        normalises that envelope shape so callers don't have to.
+
+        The seeded admin's ``role`` is server-required (Joi
+        ``companyCreate.user.role``). It defaults to ``"company_admin"``,
+        the only role that makes sense for a freshly-seeded tenant.
+        """
+        body = {
+            "company": {"name": name, **company_fields},
+            "user": {
+                "email": admin_email,
+                "password": admin_password,
+                "role": admin_role,
+            },
+        }
+        response = self._post("/api/v2/companies/", json=body)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "company")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Company.from_wire(item)
+
+    def update(self, uid: str, **fields: Any) -> Company:
+        """Update a company's fields."""
+        body = {"company": fields}
+        response = self._put(f"/api/v2/companies/{uid}", json=body)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "company")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Company.from_wire(item)
+
+    def delete(self, uid: str) -> None:
+        """Delete a company."""
+        self._delete(f"/api/v2/companies/{uid}")
+
+    def list(self) -> list[Company]:
+        """Return companies visible to the current user.
+
+        On most deployments this returns exactly one company; super-admin
+        users may see all companies.
+        """
+        response = self._get("/api/v2/companies/")
+        items = unwrap_resource(response.json(), "companies")
+        return [Company.from_wire(item) for item in items]
+
+
+__all__ = ["CompaniesAPI"]

rtls_sdk/resources/context.py

@@ -0,0 +1,50 @@
+"""Session-bootstrap sub-client (M6).
+
+Surfaces :meth:`load` — the mega-method that hydrates the full
+deployment view under the active project scope. Delegates to
+:mod:`rtls_sdk.compounds.context`.
+"""
+
+from __future__ import annotations
+
+from ..compounds import context as _compound
+from ..models import SessionContext
+from ._base import ResourceAPI
+
+
+class ContextAPI(ResourceAPI):
+    """Aggregated session bootstrap.
+
+    The single :meth:`load` method replaces the JS reference client's
+    18-call ``loadEntities`` saga (RESEARCH §4) — DESIGN's highest-value
+    compound collapse.
+    """
+
+    def load(self, *, scope: str | None = None) -> SessionContext:
+        """Hydrate the deployment view under the current scope.
+
+        Sub-resources are fetched sequentially in a stable order. Each
+        sub-call's failure goes into :attr:`SessionContext.errors`
+        keyed by a stable name; the rest of the snapshot still
+        populates. :attr:`SessionContext.partial` is ``True`` when any
+        sub-call failed.
+
+        Parameters
+        ----------
+        scope
+            ``None`` or ``"project"`` (the default and only supported
+            value in v1). ``"company"`` and ``"system"`` raise
+            :class:`NotImplementedError`.
+
+        Examples
+        --------
+        >>> ctx = client.context.load()
+        >>> ctx.tags, ctx.zones, ctx.sites
+        >>> if ctx.partial:
+        ...     for name, exc in ctx.errors.items():
+        ...         print(f"{name}: {exc}")
+        """
+        return _compound.collect_session_context(self._client, scope=scope)
+
+
+__all__ = ["ContextAPI"]