rtls-sdk 0.2.0__py3-none-any.whl

rtls_sdk/_client.py

@@ -0,0 +1,419 @@
+"""The main :class:`RtlsClient` class — the one thing users construct.
+
+The constructor is pure: no network I/O happens here. The first call on
+any sub-client triggers a single ``POST /auth/log_in.json`` to acquire the
+token (lazy login).
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from types import TracebackType
+from typing import Any, overload
+
+import httpx
+
+from ._auth import _AuthState
+from ._http import _RtlsAuth, check_response, wrap_transport_error
+from ._logging import log_request, log_response
+from .resources import (
+    AlarmsAPI,
+    AnchorsAPI,
+    AreasAPI,
+    AssociationsAPI,
+    AuthAPI,
+    CompaniesAPI,
+    ContextAPI,
+    EventsAPI,
+    FloorplansAPI,
+    GroupsAPI,
+    LoggerAPI,
+    MessagingAPI,
+    NodesAPI,
+    NotificationsAPI,
+    ProjectsAPI,
+    ReportsAPI,
+    SitesAPI,
+    SubscribersAPI,
+    SystemAPI,
+    TagsAPI,
+    UsersAPI,
+    ZonesAPI,
+)
+
+
+class RtlsClient:
+    """Entry point to the RTLS SDK.
+
+    Construct one client per identity. Switch project scope cheaply via
+    :meth:`with_scope` (added in M8) or by passing ``project_uid=`` to the
+    constructor.
+
+    Three construction modes are supported:
+
+    1. **From environment** (recommended for production): call
+       :meth:`from_env`. Reads ``RTLS_USERNAME`` / ``RTLS_PASSWORD`` /
+       ``RTLS_BASE_URL`` (and optional scope vars) and constructs a client.
+    2. **Explicit credentials** (for testing): pass ``username=``,
+       ``password=`` and ``base_url=``.
+    3. **Bring-your-own token** (advanced): pass ``token=`` and
+       ``base_url=``. The SDK cannot re-authenticate on 401 in this mode —
+       it raises :class:`AuthenticationError` instead.
+
+    Examples
+    --------
+    >>> client = RtlsClient.from_env()
+    >>> tags = client.tags.list()                 # lazy login fires here
+    >>> client.close()                            # or use as context mgr
+    """
+
+    @overload
+    def __init__(
+        self,
+        *,
+        username: str,
+        password: str,
+        base_url: str,
+        project_uid: str | None = None,
+        company_uid: str | None = None,
+        timeout: float = 30.0,
+        http_client: httpx.Client | None = None,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        *,
+        token: str,
+        base_url: str,
+        project_uid: str | None = None,
+        company_uid: str | None = None,
+        timeout: float = 30.0,
+        http_client: httpx.Client | None = None,
+    ) -> None: ...
+
+    def __init__(
+        self,
+        *,
+        username: str | None = None,
+        password: str | None = None,
+        token: str | None = None,
+        base_url: str,
+        project_uid: str | None = None,
+        company_uid: str | None = None,
+        timeout: float = 30.0,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._auth_state = _AuthState(
+            username=username,
+            password=password,
+            token=token,
+            project_uid=project_uid,
+            company_uid=company_uid,
+        )
+
+        if http_client is not None:
+            # Caller-supplied client. We rewire its auth to our _RtlsAuth so
+            # 401-replay and lazy-login behave as documented, and add our
+            # request/response hooks for redacted logging. The caller is
+            # responsible for the connection pool and TLS/proxy/timeout
+            # configuration; we do not change ``base_url`` or transport.
+            http_client.auth = _RtlsAuth(self._auth_state)
+            existing_hooks = dict(http_client.event_hooks)
+            existing_hooks.setdefault("request", []).append(log_request)
+            existing_hooks.setdefault("response", []).append(log_response)
+            http_client.event_hooks = existing_hooks
+            self._http = http_client
+            self._owns_http = False
+        else:
+            self._http = httpx.Client(
+                base_url=base_url,
+                auth=_RtlsAuth(self._auth_state),
+                timeout=httpx.Timeout(connect=10.0, read=timeout, write=10.0, pool=5.0),
+                transport=httpx.HTTPTransport(retries=3),
+                limits=httpx.Limits(max_connections=20, max_keepalive_connections=10),
+                headers={"User-Agent": f"rtls-sdk/{_version()}"},
+                event_hooks={
+                    "request": [log_request],
+                    "response": [log_response],
+                },
+            )
+            self._owns_http = True
+        self._auth_state.bind_http(self._http)
+
+        # Scope view: when set, every request applies these scope values as
+        # a per-thread override (None means "no header"), so the copy made
+        # by ``with_scope`` talks to a different project/company without
+        # mutating the original client's state. ``None`` here means "no
+        # view; use the auth state's default scope."
+        self._scope_view: tuple[str | None, str | None] | None = None
+
+        # Sub-clients. Instantiated once per RtlsClient.
+        self._init_resources()
+
+    def _init_resources(self) -> None:
+        """Wire the resource sub-clients to this RtlsClient instance.
+
+        Extracted so :meth:`with_scope` can re-bind them on the copy.
+        """
+        self.tags = TagsAPI(self)
+        self.sites = SitesAPI(self)
+        self.areas = AreasAPI(self)
+        self.floorplans = FloorplansAPI(self)
+        self.zones = ZonesAPI(self)
+        self.groups = GroupsAPI(self)
+        self.users = UsersAPI(self)
+        self.nodes = NodesAPI(self)
+        self.anchors = AnchorsAPI(self)
+        self.associations = AssociationsAPI(self)
+        self.alarms = AlarmsAPI(self)
+        self.events = EventsAPI(self)
+        self.reports = ReportsAPI(self)
+        self.notifications = NotificationsAPI(self)
+        self.subscribers = SubscribersAPI(self)
+        self.projects = ProjectsAPI(self)
+        self.companies = CompaniesAPI(self)
+        self.system = SystemAPI(self)
+        self.auth = AuthAPI(self)
+        self.messaging = MessagingAPI(self)
+        self.logger = LoggerAPI(self)
+        self.context = ContextAPI(self)
+
+    # -- public scope helpers --------------------------------------------
+
+    def with_scope(
+        self,
+        *,
+        project_uid: str | None = None,
+        company_uid: str | None = None,
+    ) -> RtlsClient:
+        """Return a shallow copy of this client bound to a different scope.
+
+        The copy shares the same authenticated session — ``_auth_state``,
+        token store, connection pool — so switching scope does **not**
+        trigger a re-login. The copy resolves its scope snapshot at copy
+        time: arguments left as ``None`` inherit the current effective
+        scope and freeze it on the copy. Subsequent ``use_project`` /
+        ``use_company`` calls on the original client do not affect the
+        copy's scope.
+
+        Use this for parallel / concurrent work or any case where you
+        need both scopes alive at once. For a long-lived in-place
+        rebind, use :meth:`use_project` / :meth:`use_company` instead.
+
+        Examples
+        --------
+        >>> default_client = RtlsClient.from_env()
+        >>> a = default_client.with_scope(project_uid="proj-a")
+        >>> b = default_client.with_scope(project_uid="proj-b")
+        >>> a.tags.list()  # uses proj-a
+        >>> b.tags.list()  # uses proj-b
+        >>> default_client.tags.list()  # uses the env default — unchanged
+        """
+        current_project, current_company = self._effective_scope()
+        new_project = project_uid if project_uid is not None else current_project
+        new_company = company_uid if company_uid is not None else current_company
+
+        copy = RtlsClient.__new__(RtlsClient)
+        copy._auth_state = self._auth_state
+        copy._http = self._http
+        copy._owns_http = False
+        copy._scope_view = (new_project, new_company)
+        copy._init_resources()
+        return copy
+
+    def use_project(self, project_uid: str | None) -> None:
+        """Rebind this client's default project scope in-place.
+
+        Mutates the client. Subsequent requests use ``project_uid`` as
+        the ``X-User-Project`` header (or omit the header when ``None``).
+        Unlike :meth:`with_scope`, this does NOT create a copy — every
+        sub-client and every future call sees the new scope.
+
+        Not thread-safe: concurrent calls on the same client while one
+        thread is mutating scope can interleave headers. For concurrent
+        / parallel work use :meth:`with_scope` instead.
+        """
+        if self._scope_view is not None:
+            self._scope_view = (project_uid, self._scope_view[1])
+        else:
+            self._auth_state.project_uid = project_uid
+
+    def use_company(self, company_uid: str | None) -> None:
+        """Rebind this client's default company scope in-place.
+
+        Same semantics as :meth:`use_project` — mutates in place; not
+        thread-safe; for concurrent work use :meth:`with_scope`.
+        """
+        if self._scope_view is not None:
+            self._scope_view = (self._scope_view[0], company_uid)
+        else:
+            self._auth_state.company_uid = company_uid
+
+    def _effective_scope(self) -> tuple[str | None, str | None]:
+        """The (project_uid, company_uid) this client currently sends."""
+        if self._scope_view is not None:
+            return self._scope_view
+        return (self._auth_state.project_uid, self._auth_state.company_uid)
+
+    # -- factories --------------------------------------------------------
+
+    @classmethod
+    def from_env(cls, *, prefix: str = "RTLS_") -> RtlsClient:
+        """Construct a client from environment variables.
+
+        Reads ``{prefix}USERNAME``, ``{prefix}PASSWORD``, ``{prefix}BASE_URL``
+        (required) plus ``{prefix}PROJECT_UID`` and ``{prefix}COMPANY_UID``
+        (optional). All values are looked up at call time — no caching.
+
+        Parameters
+        ----------
+        prefix
+            Environment-variable prefix. Defaults to ``"RTLS_"``.
+
+        Raises
+        ------
+        KeyError
+            If a required variable is missing.
+        """
+        return cls(
+            username=os.environ[f"{prefix}USERNAME"],
+            password=os.environ[f"{prefix}PASSWORD"],
+            base_url=os.environ[f"{prefix}BASE_URL"],
+            project_uid=os.environ.get(f"{prefix}PROJECT_UID"),
+            company_uid=os.environ.get(f"{prefix}COMPANY_UID"),
+        )
+
+    # -- context manager -------------------------------------------------
+
+    def __enter__(self) -> RtlsClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool and clear the token.
+
+        For clients returned by :meth:`with_scope`, ``close()`` is a
+        no-op — the copy doesn't own the pool. Close the original
+        client to free shared resources.
+        """
+        if self._owns_http:
+            self._http.close()
+            self._auth_state.clear()
+
+    # -- per-call scope override ----------------------------------------
+
+    @contextmanager
+    def _call_with_scope(
+        self,
+        *,
+        project_uid: str | None = None,
+        company_uid: str | None = None,
+        clear_project: bool = False,
+        clear_company: bool = False,
+    ) -> Iterator[RtlsClient]:
+        """Temporarily override scope headers for calls inside the block.
+
+        Internal — the public surface is :meth:`with_scope`. Used by
+        compounds (``nodes.release(project_uid=...)``, ``context.load()``)
+        and by the per-call wrap that :meth:`with_scope` copies use.
+
+        ``clear_project=True`` / ``clear_company=True`` force the
+        corresponding header OUT for calls inside the block, taking
+        precedence over the matching ``*_uid`` argument and the auth
+        state's default scope.
+
+        The override is per-thread (``threading.local`` on the auth
+        state), so concurrent callers don't trample each other.
+        Restored in a ``finally`` block — exceptions inside the block
+        do not leak the override.
+        """
+        override = self._auth_state._scope_override
+        old_project = getattr(override, "project_uid", None)
+        old_company = getattr(override, "company_uid", None)
+        old_clear_project = getattr(override, "clear_project", False)
+        old_clear_company = getattr(override, "clear_company", False)
+        try:
+            if clear_project:
+                override.clear_project = True
+            elif project_uid is not None:
+                override.project_uid = project_uid
+                override.clear_project = False
+            if clear_company:
+                override.clear_company = True
+            elif company_uid is not None:
+                override.company_uid = company_uid
+                override.clear_company = False
+            yield self
+        finally:
+            override.project_uid = old_project
+            override.company_uid = old_company
+            override.clear_project = old_clear_project
+            override.clear_company = old_clear_company
+
+    # -- request execution ----------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Any = None,
+        json: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """Send a request and raise typed exceptions on non-2xx.
+
+        When this client has a :attr:`_scope_view` (i.e. it was returned
+        by :meth:`with_scope`), the call is wrapped in a per-thread scope
+        override so the snapshot scope takes precedence over the auth
+        state's default. The override is restored after every call.
+        """
+        if self._scope_view is not None:
+            proj, comp = self._scope_view
+            with self._call_with_scope(
+                project_uid=proj,
+                company_uid=comp,
+                clear_project=proj is None,
+                clear_company=comp is None,
+            ):
+                return self._send(method, path, params=params, json=json, headers=headers)
+        return self._send(method, path, params=params, json=json, headers=headers)
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Any = None,
+        json: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        try:
+            response = self._http.request(method, path, params=params, json=json, headers=headers)
+        except httpx.HTTPError as exc:
+            raise wrap_transport_error(exc, url=path, method=method) from exc
+        check_response(response)
+        return response
+
+
+def _version() -> str:
+    """Return the installed package version, falling back to a dev string."""
+    try:
+        from importlib.metadata import version
+
+        return version("rtls-sdk")
+    except Exception:
+        return "0.0.0+dev"
+
+
+__all__ = ["RtlsClient"]

rtls_sdk/_envelope.py

@@ -0,0 +1,74 @@
+"""Helpers for unwrapping the server's response envelopes.
+
+The RTLS API uses two envelope shapes (RESEARCH §2):
+
+- Auth endpoints: ``{"success": true, "data": {...}}``
+- Resource endpoints: ``{"<plural_noun>": [...]}``
+
+These helpers parse strictly. We do not replicate the JS reference client's
+``data.x || data`` fallback — when the shape is wrong, fail loudly rather
+than silently return half the payload.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def unwrap_data(payload: Any) -> dict[str, Any]:
+    """Unwrap an auth-style envelope: ``{"success": true, "data": {...}}``.
+
+    Raises ``ValueError`` if the envelope shape is unexpected.
+    """
+    if not isinstance(payload, dict):
+        raise ValueError(f"expected dict envelope, got {type(payload).__name__}")
+    if "data" not in payload:
+        raise ValueError(f"missing 'data' key in envelope: {list(payload)}")
+    data = payload["data"]
+    if not isinstance(data, dict):
+        raise ValueError(f"'data' is not a dict: {type(data).__name__}")
+    return data
+
+
+def unwrap_resource(payload: Any, key: str) -> list[dict[str, Any]]:
+    """Unwrap a resource list envelope: ``{"<key>": [...]}``.
+
+    Tolerates both the wrapped form and a bare list (some endpoints — see
+    RESEARCH §5 — return one or the other depending on server version).
+    Raises ``ValueError`` if neither shape matches.
+    """
+    if isinstance(payload, list):
+        return payload
+    if isinstance(payload, dict):
+        items = payload.get(key)
+        if isinstance(items, list):
+            return items
+        raise ValueError(f"expected {{'{key}': [...]}} envelope, got keys {list(payload)}")
+    raise ValueError(f"expected list or dict envelope, got {type(payload).__name__}")
+
+
+def unwrap_resource_single(payload: Any, key: str) -> dict[str, Any]:
+    """Unwrap a single-resource envelope.
+
+    The server returns ``{"<key>": [t]}`` even for single-resource GETs
+    (RESEARCH §3 Trackable / Discrepancy #10). Some endpoints return the
+    object bare. Handle both, raise ``ValueError`` on neither.
+    """
+    if isinstance(payload, dict):
+        if key in payload:
+            inner = payload[key]
+            if isinstance(inner, list):
+                if not inner:
+                    raise ValueError(f"empty list under '{key}'")
+                first = inner[0]
+                if not isinstance(first, dict):
+                    raise ValueError(f"first item under '{key}' is not a dict")
+                return first
+            if isinstance(inner, dict):
+                return inner
+            raise ValueError(f"value under '{key}' is neither dict nor list")
+        return payload
+    raise ValueError(f"expected dict envelope, got {type(payload).__name__}")
+
+
+__all__ = ["unwrap_data", "unwrap_resource", "unwrap_resource_single"]

rtls_sdk/_http.py

@@ -0,0 +1,145 @@
+"""httpx.Auth subclass and the response-to-exception mapping.
+
+The auth subclass implements lazy login + 401-once-replay; it does not
+raise typed exceptions. Error mapping is a separate helper called by the
+resource sub-clients after every request, so the auth flow can intercept
+401 before the error-raising path runs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from ._logging import redact_body
+from .errors import (
+    ConnectionError as RtlsConnectionError,
+)
+from .errors import (
+    RateLimited,
+    RtlsError,
+    ValidationError,
+    exception_for_status,
+    parse_error_envelope,
+)
+
+if TYPE_CHECKING:
+    from ._auth import _AuthState
+
+
+# Endpoints whose 401s must not trigger re-authentication (otherwise we
+# recurse). Match by substring against the URL path.
+_NO_REAUTH_PATHS: tuple[str, ...] = (
+    "/auth/log_in",
+    "/auth/refresh_token",
+)
+
+
+class _RtlsAuth(httpx.Auth):
+    """Attach SDK auth headers; on 401, re-authenticate once and replay.
+
+    This class is intentionally limited to auth concerns. It does not
+    raise typed exceptions — that's the response-checking helper's job,
+    called by the resource layer after each request.
+    """
+
+    requires_response_body = False
+
+    def __init__(self, state: _AuthState) -> None:
+        self._state = state
+
+    def sync_auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        # Lazy login — runs at most once per client lifetime, serialized
+        # by the state's lock.
+        self._state.login_if_needed()
+        self._apply_headers(request)
+        # Remember which token we sent so a concurrent thread doing the
+        # refresh doesn't cause us to do a second redundant refresh.
+        token_used = self._state.token
+
+        response = yield request
+
+        if response.status_code == 401 and self._should_retry(request):
+            self._state.reauthenticate(expected_token=token_used)
+            self._apply_headers(request)
+            yield request
+            # The second response is returned to the caller; if it's also
+            # 401, check_response below will raise AuthenticationError.
+
+    def _apply_headers(self, request: httpx.Request) -> None:
+        for key, value in self._state.headers().items():
+            request.headers[key] = value
+
+    def _should_retry(self, request: httpx.Request) -> bool:
+        if not self._state.can_reauthenticate():
+            return False
+        path = request.url.path
+        return not any(skip in path for skip in _NO_REAUTH_PATHS)
+
+
+def check_response(response: httpx.Response) -> None:
+    """Raise the appropriate typed exception if ``response`` is non-2xx.
+
+    Called by the resource layer after every request. Reads and parses
+    the response body, applies secret redaction before stashing on the
+    raised exception, and maps the status code to a class from
+    ``rtls_sdk.errors``.
+    """
+    if 200 <= response.status_code < 300:
+        return
+
+    body: Any = None
+    if response.headers.get("content-type", "").startswith("application/json"):
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+    body = redact_body(body)
+
+    envelope = parse_error_envelope(body)
+    exc_cls = exception_for_status(response.status_code)
+    message = envelope or f"HTTP {response.status_code}"
+
+    common: dict[str, Any] = {
+        "status_code": response.status_code,
+        "request_url": str(response.request.url),
+        "request_method": response.request.method,
+        "response_body": body,
+        "error_envelope": envelope,
+    }
+
+    if exc_cls is ValidationError:
+        field_errors: dict[str, Any] | None = None
+        if isinstance(body, dict):
+            raw_errors = body.get("errors") or body.get("field_errors")
+            if isinstance(raw_errors, dict):
+                field_errors = raw_errors
+        raise ValidationError(message, field_errors=field_errors, **common)
+
+    if exc_cls is RateLimited:
+        retry_after = response.headers.get("Retry-After")
+        retry_after_seconds: float | None = None
+        if retry_after is not None:
+            try:
+                retry_after_seconds = float(retry_after)
+            except ValueError:
+                retry_after_seconds = None
+        raise RateLimited(message, retry_after_seconds=retry_after_seconds, **common)
+
+    raise exc_cls(message, **common)
+
+
+def wrap_transport_error(exc: httpx.HTTPError, *, url: str, method: str) -> RtlsError:
+    """Convert an httpx transport-level exception to our ConnectionError."""
+    return RtlsConnectionError(
+        f"transport error: {exc.__class__.__name__}: {exc}",
+        request_url=url,
+        request_method=method,
+    )
+
+
+__all__ = ["_RtlsAuth", "check_response", "wrap_transport_error"]