rtls-sdk 0.2.0__py3-none-any.whl

rtls_sdk/__init__.py

@@ -0,0 +1,123 @@
+"""Python SDK for the RTLS REST API.
+
+Three-step usage:
+
+1. Put credentials in env vars (``RTLS_USERNAME``, ``RTLS_PASSWORD``,
+   ``RTLS_BASE_URL``).
+2. Construct the client: ``client = RtlsClient.from_env()``.
+3. Call a resource method: ``tags = client.tags.list()``.
+
+Tokens, refresh, scoping headers, 401 re-login — all internal. See the
+README for the quickstart and ``docs/advanced.md`` for advanced paths.
+"""
+
+from __future__ import annotations
+
+from ._client import RtlsClient
+from .errors import (
+    AuthenticationError,
+    Conflict,
+    ConnectionError,
+    NotFound,
+    PartialFailureError,
+    PermissionDenied,
+    RateLimited,
+    ReportError,
+    ReportFailed,
+    ReportTimeout,
+    RtlsError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    Alarm,
+    Anchor,
+    Area,
+    Association,
+    BulkFailure,
+    BulkResult,
+    Capabilities,
+    Company,
+    Connection,
+    Floorplan,
+    Group,
+    Host,
+    ImportResult,
+    Node,
+    NotificationProfile,
+    NotificationType,
+    Position,
+    Project,
+    Report,
+    ReportType,
+    Role,
+    Site,
+    Subscriber,
+    SubscriberAddresses,
+    SystemHealth,
+    SystemSubscriber,
+    Tag,
+    TagTemplate,
+    Uptime,
+    User,
+    UserFlags,
+    Version,
+    WsHost,
+    Zone,
+    ZoneEvent,
+)
+
+__all__ = [  # noqa: RUF022 — grouped logically, not alphabetically
+    # Client
+    "RtlsClient",
+    # Errors
+    "AuthenticationError",
+    "Conflict",
+    "ConnectionError",
+    "NotFound",
+    "PartialFailureError",
+    "PermissionDenied",
+    "RateLimited",
+    "ReportError",
+    "ReportFailed",
+    "ReportTimeout",
+    "RtlsError",
+    "ServerError",
+    "ValidationError",
+    # Models
+    "Alarm",
+    "Anchor",
+    "Area",
+    "Association",
+    "BulkFailure",
+    "BulkResult",
+    "Capabilities",
+    "Company",
+    "Connection",
+    "Floorplan",
+    "Group",
+    "Host",
+    "ImportResult",
+    "Node",
+    "NotificationProfile",
+    "NotificationType",
+    "Position",
+    "Project",
+    "Report",
+    "ReportType",
+    "Role",
+    "Site",
+    "Subscriber",
+    "SubscriberAddresses",
+    "SystemHealth",
+    "SystemSubscriber",
+    "Tag",
+    "TagTemplate",
+    "Uptime",
+    "User",
+    "UserFlags",
+    "Version",
+    "WsHost",
+    "Zone",
+    "ZoneEvent",
+]

rtls_sdk/_auth.py

@@ -0,0 +1,266 @@
+"""Authentication state for an ``RtlsClient`` instance.
+
+Holds credentials, current token, scoping, and the lock + event used to
+serialize concurrent re-authentications.
+
+A single ``_AuthState`` instance is shared across all sub-clients of one
+``RtlsClient``. Tokens never leave this object via any public method.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING
+
+from ._envelope import unwrap_data
+from .errors import AuthenticationError
+
+if TYPE_CHECKING:
+    import httpx
+
+
+_LOGIN_PATH = "/api/v2/auth/log_in.json"
+
+
+class _AuthState:
+    """In-memory store for the active session.
+
+    One of (``username`` + ``password``) or ``token`` must be present. With
+    only ``token``, the SDK cannot re-authenticate on expiry — it raises
+    ``AuthenticationError`` immediately on 401.
+    """
+
+    def __init__(
+        self,
+        *,
+        username: str | None,
+        password: str | None,
+        token: str | None,
+        project_uid: str | None,
+        company_uid: str | None,
+    ) -> None:
+        if (username is None) != (password is None):
+            raise TypeError("username and password must be passed together")
+        if token is None and username is None:
+            raise TypeError("provide either token= or username= + password=")
+        if token is not None and username is not None:
+            raise TypeError("pass either token= or username= + password=, not both")
+
+        self._username = username
+        self._password = password
+        self._token: str | None = token
+        self._email: str | None = username  # provisional; updated by login
+        self.project_uid = project_uid
+        self.company_uid = company_uid
+
+        # Cached uid of the currently-authenticated user. Populated when
+        # ``users.me()`` resolves the email against /users for the first
+        # time. Used by ``users.update()`` for self-edit detection.
+        self._user_uid: str | None = None
+
+        # Refresh serialization. Threads coalesce on this lock; whichever
+        # acquires it first does the actual login, the rest discover the
+        # token has changed under them and skip a duplicate refresh.
+        self._refresh_lock = threading.Lock()
+
+        # Per-thread scope override for per-call ``X-User-Project`` /
+        # ``X-User-Subcontractor`` swaps without mutating shared state.
+        # Used by ``nodes.release(project_uid=...)`` and (in M8) by
+        # ``with_scope``. Each thread sees its own override; a missing
+        # attribute means "no override" and the default scope applies.
+        self._scope_override: threading.local = threading.local()
+
+        # Bound by RtlsClient after the httpx.Client is constructed.
+        self._http: httpx.Client | None = None
+
+    # -- binding ----------------------------------------------------------
+
+    def bind_http(self, http: httpx.Client) -> None:
+        """Wire the httpx.Client used for login calls.
+
+        Login requests bypass our own auth wrapper via ``auth=None`` on the
+        call site.
+        """
+        self._http = http
+
+    # -- credential introspection ----------------------------------------
+
+    def can_reauthenticate(self) -> bool:
+        """True when stored credentials let the SDK re-login on 401."""
+        return self._password is not None and self._username is not None
+
+    @property
+    def token(self) -> str | None:
+        return self._token
+
+    @property
+    def email(self) -> str | None:
+        return self._email
+
+    @property
+    def user_uid(self) -> str | None:
+        """Cached uid of the authenticated user.
+
+        ``None`` until something calls ``users.me()`` / ``auth.whoami()``,
+        which resolves the email against the user list and caches the uid.
+        """
+        return self._user_uid
+
+    # -- headers ----------------------------------------------------------
+
+    def headers(self) -> dict[str, str]:
+        """Headers to attach to every authenticated request.
+
+        ``X-User-Subcontractor`` is omitted when no company scope is set —
+        the JS client sends the literal string ``"null"`` in that case,
+        which we treat as a bug rather than a contract (RESEARCH §5
+        quirk #4, DESIGN §9 open #3). Backend confirmation pending; if the
+        server later proves to require the header, this is the single spot
+        to change.
+
+        Scoping headers respect any per-call override set by
+        :meth:`RtlsClient._call_with_scope` (per-thread).
+        """
+        out: dict[str, str] = {}
+        if self._token is not None:
+            out["X-User-Token"] = self._token
+        if self._email is not None:
+            out["X-User-Email"] = self._email
+
+        # Per-thread override takes precedence over the default scope.
+        # ``clear_project=True`` (set by context-load's cross-scope nodes
+        # fetch) forces ``X-User-Project`` OUT regardless of any default
+        # project on the auth state.
+        override_clear_project = getattr(self._scope_override, "clear_project", False)
+        override_clear_company = getattr(self._scope_override, "clear_company", False)
+        override_project = getattr(self._scope_override, "project_uid", None)
+        override_company = getattr(self._scope_override, "company_uid", None)
+
+        if override_clear_project:
+            effective_project = None
+        elif override_project is not None:
+            effective_project = override_project
+        else:
+            effective_project = self.project_uid
+
+        if override_clear_company:
+            effective_company = None
+        elif override_company is not None:
+            effective_company = override_company
+        else:
+            effective_company = self.company_uid
+
+        if effective_project is not None:
+            out["X-User-Project"] = effective_project
+        if effective_company is not None:
+            out["X-User-Subcontractor"] = effective_company
+        return out
+
+    # -- login ------------------------------------------------------------
+
+    def login_if_needed(self) -> None:
+        """Acquire an initial token if we don't have one (lazy login)."""
+        if self._token is not None:
+            return
+        with self._refresh_lock:
+            if self._token is not None:
+                return  # another thread won the race
+            self._do_login()
+
+    def reauthenticate(self, expected_token: str | None) -> None:
+        """Re-acquire a token after a 401 — but only if it hasn't been
+        refreshed already since the caller's failing request.
+
+        ``expected_token`` is the token value the caller used when its
+        request returned 401. We acquire the lock, then check whether the
+        token has already changed (meaning another concurrent thread
+        already did the refresh). If so, return without doing another
+        login — the caller just needs to retry with the new token.
+        """
+        if not self.can_reauthenticate():
+            return
+        with self._refresh_lock:
+            if self._token != expected_token:
+                # Already refreshed by a concurrent thread.
+                return
+            self._token = None
+            self._do_login()
+
+    def _do_login(self) -> None:
+        """Perform the actual login HTTP call, populating token + email."""
+        if self._http is None:
+            raise RuntimeError("_AuthState._http is not bound; this is an SDK bug")
+        if self._username is None or self._password is None:
+            raise AuthenticationError(
+                "cannot login: no username/password stored",
+                status_code=None,
+            )
+
+        # auth=None bypasses our own _RtlsAuth wrapper. httpx accepts this
+        # at runtime; the stub doesn't model it, hence the ignore.
+        response = self._http.post(
+            _LOGIN_PATH,
+            json={"email": self._username, "password": self._password},
+            auth=None,  # type: ignore[arg-type]
+        )
+        if response.status_code != 200:
+            # Don't surface server's response body verbatim — could contain
+            # diagnostic data that names credentials. The redaction filter
+            # on response hooks already neutralized any logged version, but
+            # error messages compose differently — keep it terse here.
+            raise AuthenticationError(
+                f"login failed: HTTP {response.status_code}",
+                status_code=response.status_code,
+                request_url=str(response.request.url),
+                request_method=response.request.method,
+            )
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise AuthenticationError(
+                "login response was not valid JSON",
+                status_code=response.status_code,
+                request_url=str(response.request.url),
+                request_method=response.request.method,
+            ) from exc
+
+        try:
+            data = unwrap_data(payload)
+            token = data["token"]
+            email = data["email"]
+        except (KeyError, ValueError) as exc:
+            raise AuthenticationError(
+                f"login response had unexpected shape: {exc}",
+                status_code=response.status_code,
+                request_url=str(response.request.url),
+                request_method=response.request.method,
+            ) from exc
+
+        if not isinstance(token, str) or not isinstance(email, str):
+            raise AuthenticationError(
+                "login response had non-string token or email",
+                status_code=response.status_code,
+            )
+        self._token = token
+        self._email = email
+
+    def clear(self) -> None:
+        """Forget the in-memory token. Called by ``RtlsClient.close``."""
+        self._token = None
+
+    def set_password(self, new_password: str) -> None:
+        """Replace the stored password and invalidate the current token.
+
+        Called by ``auth.change_password`` after the server accepts a
+        password change. Subsequent calls trigger a fresh lazy login
+        with the new credentials.
+        """
+        if self._username is None:
+            raise RuntimeError(
+                "set_password called on a BYO-token client; the SDK has no username to log in with"
+            )
+        self._password = new_password
+        self._token = None
+
+
+__all__ = ["_AuthState"]