rtls-sdk 0.2.0__py3-none-any.whl

rtls_sdk/resources/users.py

@@ -0,0 +1,275 @@
+"""Users resource sub-client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._envelope import unwrap_resource
+from ..compounds import users as _compound
+from ..errors import RtlsError
+from ..models import Role, User
+from ._base import ResourceAPI
+
+
+class UsersAPI(ResourceAPI):
+    """User-related calls.
+
+    M2 ships ``list``, ``me``, and ``get_access_control``. Mutating
+    operations (create / update / delete / change_password) land in M3
+    and M5. ``list`` is defined last to avoid mypy's class-scope shadow
+    of the builtin ``list``.
+    """
+
+    def me(self) -> User:
+        """Return the currently-authenticated user as a :class:`User`.
+
+        There is no server-side ``/users/me`` endpoint — this method is
+        composed: it calls ``GET /users/?withProjects=true``, finds the
+        record whose ``email`` matches the SDK's stored auth email, and
+        returns it.
+
+        Raises
+        ------
+        RtlsError
+            If the current email is not present in the response (the
+            server's user list excludes self for some reason — unusual
+            but possible with scoped tokens).
+
+        Examples
+        --------
+        >>> me = client.auth.whoami()
+        >>> me.email, me.role
+        ('qa@example.com', Role.SYSTEM_ADMIN)
+        """
+        users = self.list(with_projects=True)
+        email = self._client._auth_state.email
+        if email is None:
+            raise RtlsError(
+                "users.me() called before authentication completed — this is an SDK bug",
+            )
+
+        target = email.lower()
+        for user in users:
+            if user.email.lower() == target:
+                # Cache uid on the auth state for self-edit detection in
+                # users.update() and auth.change_password().
+                if user.uid:
+                    self._client._auth_state._user_uid = user.uid
+                return user
+
+        raise RtlsError(
+            f"authenticated user {email!r} not found in /users response",
+        )
+
+    def get_access_control(self) -> list[dict[str, Any]]:
+        """Return the current user's access-control entries.
+
+        Returns a list of per-company role assignments. M2 surfaces them
+        as raw dicts; a dedicated ``AccessControlEntry`` model lands
+        with the write surface in M3.
+        """
+        response = self._get("/api/v2/users/access_control/")
+        payload = response.json()
+        if isinstance(payload, dict):
+            entries = payload.get("access_control")
+            if isinstance(entries, list):
+                return entries
+        if isinstance(payload, list):
+            return payload
+        return []
+
+    def create_raw(self, email: str, password: str, **fields: Any) -> User:
+        """Create a user (single REST call, no project-access binding).
+
+        **Advanced.** :meth:`create` (added in M5) also binds the new
+        user to a project role in one compound call. Use ``create_raw``
+        only if you need to skip the role-binding step.
+        """
+        body: dict[str, Any] = {"email": email, "password": password, **fields}
+        response = self._post("/api/v2/users", json=body)
+        payload = response.json()
+        if isinstance(payload, dict):
+            item = payload.get("user", payload)
+        else:
+            item = {}
+        return User.from_wire(item if isinstance(item, dict) else {})
+
+    def update_raw(self, uid: str, **fields: Any) -> User:
+        """Update a user (single REST call, no project-access binding).
+
+        **Advanced.** :meth:`update` (added in M5) also re-binds the
+        user's project role if you pass ``project_role=``.
+        """
+        response = self._put(f"/api/v2/users/{uid}/", json=fields)
+        payload = response.json()
+        if isinstance(payload, dict):
+            item = payload.get("user", payload)
+        else:
+            item = {}
+        return User.from_wire(item if isinstance(item, dict) else {})
+
+    def delete(self, uid: str) -> None:
+        """Delete a user by uid (single REST call)."""
+        self._delete(f"/api/v2/users/{uid}/")
+
+    def update_access(self, project_uid: str, *, uid: str, role: str) -> dict[str, Any]:
+        """Assign or change a user's role on a project.
+
+        Wraps ``POST /projects/access/``. Used internally by M5's
+        :meth:`create` / :meth:`update` compounds to bind project roles
+        atomically; exposed here for callers that need it standalone.
+        """
+        body = {
+            "projectUsersAccess": [{"project_uid": project_uid, "user_uid": uid, "user_role": role}]
+        }
+        response = self._post("/api/v2/projects/access/", json=body)
+        payload = response.json()
+        return payload if isinstance(payload, dict) else {"data": payload}
+
+    def restore_password(self, email: str) -> dict[str, Any]:
+        """Trigger a password-restore email for the given address.
+
+        Unauthenticated — the server only needs the email. Returns the
+        server's response payload.
+        """
+        response = self._put("/api/v2/users/restorePassword/", json={"email": email})
+        payload = response.json()
+        return payload if isinstance(payload, dict) else {"data": payload}
+
+    def validate(self, **fields: Any) -> dict[str, Any]:
+        """Server-side validation for user-form fields.
+
+        The wire shape varies by field (``{"email": "..."}``,
+        ``{"password": "...", "uid": "...", "isOld": true}``, etc.); the
+        SDK passes through whatever you give it. Returns the parsed
+        server response. M5's :meth:`change_password` compound calls
+        this internally.
+        """
+        response = self._post("/api/v2/users/validation", json=fields)
+        payload = response.json()
+        return payload if isinstance(payload, dict) else {"data": payload}
+
+    def change_password_raw(
+        self, uid: str, *, old_password: str, new_password: str
+    ) -> dict[str, Any]:
+        """Change a user's password (single REST call, no re-login).
+
+        **Advanced.** M5's :meth:`change_password` wraps this to also
+        re-authenticate the SDK afterwards. Calling ``change_password_raw``
+        directly leaves the SDK holding a stale token — your next call
+        will trigger a 401 + re-login dance.
+        """
+        body = {"uid": uid, "oldPassword": old_password, "newPassword": new_password}
+        response = self._put("/api/v2/users/changePassword", json=body)
+        payload = response.json() if response.content else None
+        return payload if isinstance(payload, dict) else {}
+
+    def create(
+        self,
+        email: str,
+        password: str,
+        *,
+        project_uid: str | None = None,
+        project_role: str | Role | None = None,
+        **fields: Any,
+    ) -> User:
+        """Create a user and optionally bind them to a project role.
+
+        One call collapses two REST round-trips: ``POST /users`` plus
+        ``POST /projects/access/``. If the role-binding step fails, the
+        SDK best-effort rolls back the user create — see
+        :class:`PartialFailureError` for the orphan uid if rollback
+        also fails.
+
+        ``project_role`` is skipped (no second call) when the created
+        user comes back as ``COMPANY_ADMIN``: company admins have
+        implicit project access at the org level.
+
+        Step names: ``create_user``, ``bind_project_role``,
+        ``delete_user_rollback``.
+        """
+        return _compound.create_user(
+            self._client,
+            email,
+            password,
+            project_uid=project_uid,
+            project_role=project_role,
+            **fields,
+        )
+
+    def update(
+        self,
+        uid: str,
+        *,
+        project_uid: str | None = None,
+        project_role: str | Role | None = None,
+        **fields: Any,
+    ) -> User:
+        """Update a user, optionally re-binding their project role.
+
+        Self-edit detection: if ``uid`` matches the SDK's current user
+        AND the update changes ``email``, the SDK refreshes the
+        in-memory auth state so subsequent ``X-User-Email`` headers
+        stay valid.
+
+        Step names: ``update_user``, ``bind_project_role``.
+        """
+        return _compound.update_user(
+            self._client,
+            uid,
+            project_uid=project_uid,
+            project_role=project_role,
+            **fields,
+        )
+
+    def list_roles(self) -> list[Role]:
+        """Return all valid roles the server accepts on user create / update.
+
+        Endpoint shape varies by deployment; the SDK best-effort parses
+        the response into :class:`Role` members. Used by
+        :meth:`ContextAPI.load` (M6). Returns an empty list if the
+        endpoint isn't available or the response shape isn't recognized.
+        """
+        response = self._get("/api/v2/user_roles")
+        payload = response.json()
+        roles: list[Role] = []
+        # Tolerate {user_roles: [...]}, bare list, or {roles: [...]}.
+        candidates: list[Any] = []
+        if isinstance(payload, dict):
+            for key in ("user_roles", "roles", "data"):
+                value = payload.get(key)
+                if isinstance(value, list):
+                    candidates = value
+                    break
+        elif isinstance(payload, list):
+            candidates = payload
+        for item in candidates:
+            role_str: str | None = None
+            if isinstance(item, str):
+                role_str = item
+            elif isinstance(item, dict):
+                raw = item.get("name") or item.get("role") or item.get("uid")
+                if isinstance(raw, str):
+                    role_str = raw
+            if role_str is None:
+                continue
+            try:
+                roles.append(Role(role_str.lower()))
+            except ValueError:
+                # Unknown role string — skip rather than fail.
+                continue
+        return roles
+
+    def list(self, *, with_projects: bool = False) -> list[User]:
+        """Return all users visible to the current scope.
+
+        ``with_projects=True`` asks the server to include per-user
+        project assignments inside each user record.
+        """
+        params = {"withProjects": "true"} if with_projects else None
+        response = self._get("/api/v2/users/", params=params)
+        items = unwrap_resource(response.json(), "users")
+        return [User.from_wire(item) for item in items]
+
+
+__all__ = ["UsersAPI"]

rtls_sdk/resources/zones.py

@@ -0,0 +1,199 @@
+"""Zones resource sub-client."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from .._envelope import unwrap_resource, unwrap_resource_single
+from .._time import to_epoch_ms
+from ..compounds import zones as _compound
+from ..compounds.tags import UNSET, _Unset
+from ..errors import NotFound
+from ..models import Zone
+from ._base import ResourceAPI
+
+
+class ZonesAPI(ResourceAPI):
+    """List, get, and (later) mutate zones (static + buffers).
+
+    ``list`` is defined last so mypy resolves ``list[Zone]`` annotations
+    in other methods to the builtin (class-scope shadow workaround).
+    """
+
+    def get(self, uid: str) -> Zone:
+        """Fetch a single zone by uid.
+
+        The server has no dedicated ``GET /zones/{uid}`` per the JS
+        client; the SDK composes via ``list()`` and filters. This is a
+        documented stop-gap — if the server later exposes a single-zone
+        endpoint, the implementation switches without changing the
+        surface.
+        """
+        zones = self.list()
+        for zone in zones:
+            if zone.uid == uid:
+                return zone
+        raise NotFound(f"zone {uid!r} not found")
+
+    def history(self, start: datetime, end: datetime) -> list[Zone]:
+        """Return zones (including soft-deleted) active during ``[start, end]``.
+
+        Used for audit / replay workflows. Timestamps go on the wire as
+        epoch milliseconds.
+        """
+        params = {
+            "include_removed": "true",
+            "from": str(to_epoch_ms(start, arg_name="start")),
+            "to": str(to_epoch_ms(end, arg_name="end")),
+        }
+        response = self._get("/api/v2/zones/", params=params)
+        items = unwrap_resource(response.json(), "zones")
+        return [Zone.from_wire(item) for item in items]
+
+    def list_custom_prototypes(self) -> list[dict[str, Any]]:
+        """List custom-zone prototypes — server-side reusable zone shapes.
+
+        These don't yet have a dedicated model; we surface them as raw
+        dicts. M2's pydantic shapes will replace this when usage stabilizes.
+        """
+        response = self._get("/api/v2/custom_zones_prototypes/")
+        items = unwrap_resource(response.json(), "custom_zones_prototypes")
+        return list(items)
+
+    def create_raw(self, name: str, **fields: Any) -> Zone:
+        """Create a zone or buffer (single REST call).
+
+        **Advanced.** :meth:`create` (added in M4) wraps this and also
+        handles ``dynamic`` zone-to-trackable binding. Use ``create_raw``
+        only when you need exact control over the call sequence.
+
+        Parameters
+        ----------
+        name
+            Required. Zone name.
+        **fields
+            Pass ``shape``, ``points`` / ``radius_m`` / center, ``dynamic``,
+            ``trackable_object_uid``, ``sublocation_uid``, etc. — whatever
+            the server accepts.
+        """
+        body: dict[str, Any] = {"name": name, **fields}
+        response = self._post("/api/v2/zones", json=body)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "zone")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Zone.from_wire(item)
+
+    def update_raw(self, uid: str, **fields: Any) -> Zone:
+        """Update a zone (single REST call, no trackable re-binding).
+
+        **Advanced.** :meth:`update` (added in M4) handles dynamic-zone
+        re-binding automatically.
+        """
+        response = self._put(f"/api/v2/zones/{uid}", json=fields)
+        payload = response.json()
+        try:
+            item = unwrap_resource_single(payload, "zone")
+        except ValueError:
+            item = payload if isinstance(payload, dict) else {}
+        return Zone.from_wire(item)
+
+    def delete_raw(self, uid: str) -> None:
+        """Delete a zone (single REST call, no trackable-detach).
+
+        **Advanced.** :meth:`delete` (added in M4) clears any dynamic
+        binding before deletion.
+        """
+        self._delete(f"/api/v2/zones/{uid}")
+
+    def create(
+        self,
+        name: str,
+        *,
+        dynamic: bool = False,
+        trackable_uid: str | None = None,
+        **fields: Any,
+    ) -> Zone:
+        """Create a zone or buffer, binding it to a trackable if requested.
+
+        For static zones (``dynamic=False``) this is a single REST call.
+        For dynamic zones bound to a trackable, the SDK also writes
+        ``self_zone_uid`` onto the trackable so the binding is consistent
+        from both sides. The trackable update is rolled back (best
+        effort) if the zone create succeeds but the binding fails.
+
+        Step names: ``create_zone``, ``set_trackable_binding``.
+
+        Examples
+        --------
+        >>> static = client.zones.create(
+        ...     "Loading Bay", shape="polygon",
+        ...     points=[(0, 0), (10, 0), (10, 5), (0, 5)],
+        ...     sublocation_uid="sl-east",
+        ... )
+        >>> buffer_zone = client.zones.create(
+        ...     "FL7-buf", shape="circle", radius_m=3.0,
+        ...     dynamic=True, trackable_uid="t-7",
+        ... )
+        """
+        return _compound.create_zone(
+            self._client,
+            name,
+            dynamic=dynamic,
+            trackable_uid=trackable_uid,
+            **fields,
+        )
+
+    def update(
+        self,
+        uid: str,
+        *,
+        trackable_uid: str | None | _Unset = UNSET,
+        **fields: Any,
+    ) -> Zone:
+        """Update a zone, re-binding the trackable if requested.
+
+        Pass ``trackable_uid=...`` (default) to leave the current
+        binding alone. Pass ``trackable_uid=None`` to clear it;
+        ``trackable_uid="t-x"`` to rebind to a different trackable.
+
+        Step names: ``load_zone``, ``clear_old_binding``,
+        ``set_new_binding``, ``update_zone``.
+
+        If ``set_new_binding`` fails after ``clear_old_binding``
+        succeeded, the SDK best-effort restores the old binding before
+        raising. If that restore also fails, the exception's
+        ``partial_result`` names the dangling trackable.
+        """
+        return _compound.update_zone(self._client, uid, trackable_uid=trackable_uid, **fields)
+
+    def delete(self, uid: str) -> None:
+        """Delete a zone, clearing any dynamic-trackable binding first.
+
+        Step names: ``load_zone``, ``clear_binding``, ``delete_zone``.
+
+        Clearing a stale binding is best-effort — failure there is
+        logged and the delete proceeds anyway.
+        """
+        _compound.delete_zone(self._client, uid)
+
+    def list(self) -> list[Zone]:
+        """Return zones and buffers for the current project.
+
+        The server returns both static zones (``dynamic=False``) and
+        buffers (``dynamic=True``) in the same response. The SDK does
+        not filter client-side (the JS reference client does — RESEARCH §5
+        quirk #11 — and the SDK explicitly chooses not to).
+
+        Examples
+        --------
+        >>> static_zones = [z for z in client.zones.list() if not z.dynamic]
+        """
+        response = self._get("/api/v2/zones/")
+        items = unwrap_resource(response.json(), "zones")
+        return [Zone.from_wire(item) for item in items]
+
+
+__all__ = ["ZonesAPI"]

rtls_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: rtls-sdk
+Version: 0.2.0
+Summary: Python SDK for the RTLS REST API
+Project-URL: Homepage, https://github.com/rpplabs/rtls-sdk
+Project-URL: Documentation, https://github.com/rpplabs/rtls-sdk/tree/master/docs
+Project-URL: Issues, https://github.com/rpplabs/rtls-sdk/issues
+Project-URL: Changelog, https://github.com/rpplabs/rtls-sdk/blob/master/CHANGELOG.md
+Author: RTLS SDK Maintainers
+License: MIT
+License-File: LICENSE
+Keywords: iot,rtls,sdk,tracking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest-httpserver>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# RTLS SDK
+
+A Python SDK for the RTLS REST API. Three-step usage:
+
+```python
+from rtls_sdk import RtlsClient
+
+client = RtlsClient.from_env()
+tags = client.tags.list()
+```
+
+That's it — token, refresh, scoping headers, 401 re-login are all
+internal. The first method call performs a lazy login; subsequent
+calls reuse the session.
+
+## What you get
+
+- **Compound workflows.** One Python call replaces the multi-call
+  REST sagas the JS reference client makes you script — e.g.
+  `tags.create(name="X", attached_zone="Z", groups=[...])` runs the
+  three-step create-and-attach with rollback on partial failure.
+- **One exception hierarchy.** Everything under `RtlsError`:
+  `NotFound`, `ValidationError`, `RateLimited`, `ServerError`,
+  `PartialFailureError`, `ReportFailed` / `ReportTimeout`, …
+- **Typed models.** Pydantic v2 under the hood; `mypy --strict` clean
+  out of the box; ships `py.typed`.
+- **Mandatory redaction.** No password, token, refresh-token, cookie,
+  or `Authorization` header ever reaches a log handler. There is no
+  opt-out flag.
+- **Sync-only for v1.** Async surface and WebSocket support are on the
+  v2 roadmap.
+
+## Install
+
+```bash
+pip install rtls-sdk
+```
+
+Python 3.10+ supported. See [`docs/install.md`](docs/install.md) for
+dev install and verification.
+
+## Quickstart
+
+```bash
+export RTLS_USERNAME="qa@example.com"
+export RTLS_PASSWORD="hunter2"
+export RTLS_BASE_URL="https://rtls.example.com"
+```
+
+```python
+from rtls_sdk import RtlsClient
+
+with RtlsClient.from_env() as client:
+    for tag in client.tags.list():
+        print(tag.uid, tag.name)
+```
+
+For the full 5-minute walkthrough see
+[`docs/quickstart.md`](docs/quickstart.md).
+
+## Documentation
+
+The full docs site (`mkdocs build`):
+
+**Start here**
+
+- **[Entity catalog](docs/entities/index.md)** — one page per entity
+  (tags, sites, areas, floorplans, anchors, zones, nodes, users,
+  reports, …) with methods, examples, and model fields. The fastest
+  path to "what can I do with X?".
+- [Install](docs/install.md) · [Quickstart](docs/quickstart.md)
+
+**Cross-cutting guides**
+
+- [Compound workflows](docs/guides/compound-workflows.md) · [Reports](docs/guides/reports.md) · [Floorplans](docs/guides/floorplans.md)
+- [Error handling](docs/guides/error-handling.md) · [Scope switching](docs/guides/scope-switching.md) · [Pagination](docs/guides/pagination.md)
+- [Rate limiting](docs/guides/rate-limiting.md) · [Timestamps](docs/guides/timestamps.md) · [Credential rotation](docs/guides/credential-rotation.md)
+
+**Advanced**
+
+- [BYO token](docs/advanced/byo-token.md) · [Raw REST methods](docs/advanced/raw-rest-methods.md) · [Logging](docs/advanced/logging.md) · [HTTP client override](docs/advanced/http-client-override.md) · [Security](docs/advanced/security.md)
+
+**Reference**
+
+- [Migrating from the JS client](docs/migration/from-js-client.md)
+- API reference — auto-generated from docstrings via mkdocstrings.
+
+Build locally:
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+## Status
+
+v0.2.0 — adds M9 places CRUD (sites / areas / anchors), M10 floorplans
++ image lifecycle, M11 entity-oriented documentation reorganisation,
+and M12 schema-audit fixes (canonical bare-12-hex MACs;
+`tags.create` no longer accepts the silently-stripped `mac_address`
+argument). See [`CHANGELOG.md`](CHANGELOG.md).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).