rtls-sdk 0.2.0__py3-none-any.whl

rtls_sdk/_logging.py

@@ -0,0 +1,143 @@
+"""Named logger and secret redaction for SDK HTTP traffic.
+
+Redaction is mandatory and has no opt-out flag. If the user wants to log
+raw payloads they can install their own ``httpx`` event hooks on a separate
+client; the SDK's logger never emits credentials at any level.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger("rtls_sdk")
+
+_REDACTED = "***"
+
+_REDACT_HEADER_NAMES: frozenset[str] = frozenset(
+    {
+        "x-user-token",
+        "x-user-email",
+        "x-user-refresh-token",
+        "authorization",
+        "cookie",
+        "set-cookie",
+    }
+)
+
+_REDACT_BODY_KEYS: frozenset[str] = frozenset(
+    {
+        "password",
+        "token",
+        "refresh_token",
+        "access_token",
+        "client_secret",
+        "api_key",
+    }
+)
+
+# Strings longer than this in a logged body are replaced with a
+# ``<truncated N bytes>`` placeholder. Set so a base64-encoded image
+# payload (typically tens of KB to MB) doesn't pollute DEBUG logs and
+# obscure the structurally interesting fields. 1024 chars covers any
+# legitimate user-facing string (names, descriptions, URLs) with room
+# to spare.
+_MAX_LOGGED_STRING_LEN: int = 1024
+
+
+def redact_headers(headers: httpx.Headers | dict[str, str]) -> dict[str, str]:
+    """Return a copy of ``headers`` with sensitive values masked."""
+    out: dict[str, str] = {}
+    for key, value in headers.items():
+        if key.lower() in _REDACT_HEADER_NAMES:
+            out[key] = _REDACTED
+        else:
+            out[key] = value
+    return out
+
+
+def redact_body(body: Any) -> Any:
+    """Recursively mask sensitive values in a parsed JSON body.
+
+    Three transformations applied to every node:
+
+    1. Keys in :data:`_REDACT_BODY_KEYS` (case-insensitive) have their
+       values replaced with ``"***"``.
+    2. String values longer than :data:`_MAX_LOGGED_STRING_LEN` are
+       replaced with ``"<truncated N bytes>"``. This keeps base64
+       image payloads and other large blobs out of DEBUG logs.
+    3. Containers are recursed into; lists / dicts return a new
+       structure (the input is never mutated).
+    """
+    if isinstance(body, dict):
+        return {
+            key: (_REDACTED if key.lower() in _REDACT_BODY_KEYS else redact_body(value))
+            for key, value in body.items()
+        }
+    if isinstance(body, list):
+        return [redact_body(item) for item in body]
+    if isinstance(body, str) and len(body) > _MAX_LOGGED_STRING_LEN:
+        return f"<truncated {len(body)} bytes>"
+    return body
+
+
+def log_request(request: httpx.Request) -> None:
+    """httpx request event hook — log method + URL + redacted headers + body at DEBUG.
+
+    The request body is parsed as JSON when ``content-type`` is
+    ``application/json`` and run through :func:`redact_body`, which both
+    masks secret keys (passwords, tokens) and truncates strings longer
+    than 1024 chars (image payloads, etc.). Non-JSON bodies log as
+    ``<binary N bytes>`` placeholders.
+    """
+    if not logger.isEnabledFor(logging.DEBUG):
+        return
+    body: Any = None
+    content_type = request.headers.get("content-type", "")
+    if content_type.startswith("application/json") and request.content:
+        try:
+            import json
+
+            body = redact_body(json.loads(request.content))
+        except (ValueError, UnicodeDecodeError):
+            body = f"<unparseable {len(request.content)} bytes>"
+    elif request.content:
+        body = f"<binary {len(request.content)} bytes>"
+    logger.debug(
+        "request %s %s headers=%s body=%s",
+        request.method,
+        request.url,
+        redact_headers(request.headers),
+        body,
+    )
+
+
+def log_response(response: httpx.Response) -> None:
+    """httpx response event hook — log status at DEBUG; body if available."""
+    if not logger.isEnabledFor(logging.DEBUG):
+        return
+    body: Any = None
+    if response.headers.get("content-type", "").startswith("application/json"):
+        try:
+            response.read()
+            body = response.json()
+        except Exception:
+            body = None
+    logger.debug(
+        "response %s %s status=%s body=%s",
+        response.request.method,
+        response.request.url,
+        response.status_code,
+        redact_body(body),
+    )
+
+
+__all__ = [
+    "log_request",
+    "log_response",
+    "logger",
+    "redact_body",
+    "redact_headers",
+]

rtls_sdk/_pagination.py

@@ -0,0 +1,235 @@
+"""Pagination paginators — three server styles, one SDK shape.
+
+The RTLS server uses three pagination conventions across endpoints
+(RESEARCH §2):
+
+- **Style 1 — header cursor**: response header
+  ``content-next-positions-page`` carries the next ``page`` value.
+  Used by ``positions_history``.
+- **Style 2 — body-included nextPage URL**: response body has
+  ``nextPage`` (full URL) and ``totalCount``. Used by
+  ``external_events`` / PWS events.
+- **Style 3 — bare page+limit**: caller supplies ``page`` /
+  ``limit``; no metadata in the response. Continue until an empty page.
+
+Each style has its own ``Paginator`` subclass; resource methods
+construct the right one and expose a single iterator surface to
+callers. The :class:`Page` value type is identical across styles.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+if TYPE_CHECKING:
+    import httpx
+
+
+T = TypeVar("T")
+
+
+@dataclass
+class Page(Generic[T]):
+    """One page of a paginated result.
+
+    Attributes
+    ----------
+    items
+        Parsed items on this page.
+    page_number
+        1-indexed.
+    total_count
+        Total across all pages, if the server reported it (Style 2 only).
+    has_next
+        ``True`` if at least one more page is expected.
+    """
+
+    items: list[T] = field(default_factory=list)
+    page_number: int = 1
+    total_count: int | None = None
+    has_next: bool = False
+
+
+# A fetcher takes (url, params) and returns the raw httpx.Response.
+# Resource methods supply ``client._http.get``-shaped callable.
+Fetcher = Callable[..., "httpx.Response"]
+# Parse a server payload into typed items.
+ItemParser = Callable[[Any], list[T]]
+
+
+class _Paginator(Generic[T]):
+    """Common surface: ``pages()`` and ``__iter__()``."""
+
+    def pages(self) -> Iterator[Page[T]]:
+        raise NotImplementedError
+
+    def __iter__(self) -> Iterator[T]:
+        for page in self.pages():
+            yield from page.items
+
+
+class HeaderCursorPaginator(_Paginator[T]):
+    """Style 1: server returns next-page cursor in a response header.
+
+    The cursor value is whatever the server emitted (often a sequence
+    number); we feed it back as ``params["page"]`` on the next call.
+    A cursor that's literally absent (header missing) or the string
+    ``"null"`` ends pagination.
+    """
+
+    def __init__(
+        self,
+        *,
+        fetch: Fetcher,
+        path: str,
+        params: dict[str, Any] | list[tuple[str, str]],
+        parse_items: ItemParser[T],
+        header_name: str = "content-next-positions-page",
+    ) -> None:
+        self._fetch = fetch
+        self._path = path
+        # Coerce to a mutable dict so we can update ``page`` between calls.
+        if isinstance(params, dict):
+            self._params: dict[str, Any] = dict(params)
+        else:
+            self._params = dict(params)
+        self._parse_items = parse_items
+        self._header_name = header_name
+
+    def pages(self) -> Iterator[Page[T]]:
+        page_number = 0
+        while True:
+            page_number += 1
+            response = self._fetch(self._path, params=self._params)
+            items = self._parse_items(response.json())
+            cursor = response.headers.get(self._header_name)
+            has_next = bool(cursor) and cursor != "null"
+            yield Page(
+                items=items,
+                page_number=page_number,
+                total_count=None,
+                has_next=has_next,
+            )
+            if not has_next:
+                return
+            self._params["page"] = cursor
+
+
+class BodyUrlPaginator(_Paginator[T]):
+    """Style 2: server returns ``nextPage`` URL in the response body.
+
+    The URL is fed verbatim to the fetcher; the SDK does not append
+    query params to it (the server's URL already carries the right
+    query). Termination is ``nextPage`` being ``null`` / absent.
+    """
+
+    def __init__(
+        self,
+        *,
+        fetch: Fetcher,
+        path: str,
+        params: dict[str, Any] | list[tuple[str, str]],
+        parse_items: ItemParser[T],
+        list_key: str,
+        next_page_key: str = "nextPage",
+        total_key: str = "totalCount",
+    ) -> None:
+        self._fetch = fetch
+        self._initial_path = path
+        self._initial_params = params
+        self._parse_items = parse_items
+        self._list_key = list_key
+        self._next_page_key = next_page_key
+        self._total_key = total_key
+
+    def pages(self) -> Iterator[Page[T]]:
+        page_number = 0
+        path: str | None = self._initial_path
+        params: Any = self._initial_params
+
+        while path is not None:
+            page_number += 1
+            response = self._fetch(path, params=params)
+            payload = response.json()
+            list_value = payload.get(self._list_key, []) if isinstance(payload, dict) else []
+            items = self._parse_items(list_value)
+            total = payload.get(self._total_key) if isinstance(payload, dict) else None
+            next_page = payload.get(self._next_page_key) if isinstance(payload, dict) else None
+            has_next = bool(next_page)
+            yield Page(
+                items=items,
+                page_number=page_number,
+                total_count=total if isinstance(total, int) else None,
+                has_next=has_next,
+            )
+            if has_next and isinstance(next_page, str):
+                path = next_page
+                # The next-page URL carries its own query string.
+                params = None
+            else:
+                path = None
+
+
+class PageLimitPaginator(_Paginator[T]):
+    """Style 3: caller drives via ``page`` + ``limit`` query params.
+
+    No metadata in the response — the SDK heuristically continues
+    until a page comes back with fewer items than ``page_size``, OR
+    until the server explicitly stops (an empty page).
+    """
+
+    def __init__(
+        self,
+        *,
+        fetch: Fetcher,
+        path: str,
+        params: dict[str, Any] | list[tuple[str, str]],
+        parse_items: ItemParser[T],
+        page_size: int = 1000,
+    ) -> None:
+        self._fetch = fetch
+        self._path = path
+        # Coerce params to a list so we can append page/limit as tuples
+        # without overwriting existing ones (the alarms-style endpoints
+        # use Rails array params that need list-of-tuples).
+        if isinstance(params, dict):
+            self._params: list[tuple[str, str]] = [(k, str(v)) for k, v in params.items()]
+        else:
+            self._params = [(k, str(v)) for k, v in params]
+        self._parse_items = parse_items
+        self._page_size = page_size
+
+    def pages(self) -> Iterator[Page[T]]:
+        page_number = 0
+        while True:
+            page_number += 1
+            paged_params = [
+                *self._params,
+                ("page", str(page_number)),
+                ("limit", str(self._page_size)),
+            ]
+            response = self._fetch(self._path, params=paged_params)
+            items = self._parse_items(response.json())
+            # Stop when the server returns fewer than the requested
+            # page size (or zero rows).
+            has_next = len(items) >= self._page_size
+            yield Page(
+                items=items,
+                page_number=page_number,
+                total_count=None,
+                has_next=has_next,
+            )
+            if not has_next:
+                return
+
+
+__all__ = [
+    "BodyUrlPaginator",
+    "Fetcher",
+    "HeaderCursorPaginator",
+    "ItemParser",
+    "Page",
+    "PageLimitPaginator",
+]

rtls_sdk/_query.py

@@ -0,0 +1,114 @@
+"""Query-string, identifier, and payload helpers.
+
+The RTLS server expects Rails-style array parameters with a literal
+``[]`` suffix on the parameter name — e.g. ``alarm_type_name[]=a&alarm_type_name[]=b``.
+``httpx``'s default ``params=`` serializer does not add the suffix, so we
+build the parameter pairs explicitly as a list of tuples.
+
+This module also hosts:
+
+- :func:`normalize_mac` — used by node / association write paths.
+- :func:`encode_image_payload` — used by floorplan upload (M10) to
+  build the ``image: {original_filename, file: <base64>}`` sub-object
+  the server's Joi schema requires.
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+from typing import Any
+
+# A loose pre-filter: anything that contains exactly 12 hex digits, with
+# optional separators between byte pairs. We strip separators and revalidate
+# strictly before emitting the canonical form.
+_MAC_SEPARATOR_RE = re.compile(r"[:\-]")
+_HEX_12_RE = re.compile(r"^[0-9a-fA-F]{12}$")
+
+
+def normalize_mac(mac: str) -> str:
+    """Return ``mac`` in canonical bare 12-hex **lowercase** form.
+
+    The RTLS server's validation regex is ``/^[a-fA-F0-9]{12}$/`` — no
+    separators allowed; either case accepted on input. The server stores
+    and returns MACs in lowercase (observed live), so the SDK
+    normalizes to lowercase to keep ``sent_mac == returned_mac``
+    round-trips clean.
+
+    Six convenient input shapes accepted; raises :class:`ValueError`
+    on malformed input. The error message includes the offending value
+    so a caller's failed HTTP-shaped batch shows which input was wrong.
+
+    Accepted inputs:
+
+    - ``aa:bb:cc:dd:ee:ff``
+    - ``AA:BB:CC:DD:EE:FF``
+    - ``aa-bb-cc-dd-ee-ff``
+    - ``AA-BB-CC-DD-EE-FF``
+    - ``aabbccddeeff``
+    - ``AABBCCDDEEFF``
+
+    Examples
+    --------
+    >>> normalize_mac("AA-BB-CC-DD-EE-FF")
+    'aabbccddeeff'
+    >>> normalize_mac("aabbccddeeff")
+    'aabbccddeeff'
+    """
+    if not isinstance(mac, str) or not mac:
+        raise ValueError(f"mac_address must be a non-empty string; got {mac!r}")
+    stripped = _MAC_SEPARATOR_RE.sub("", mac)
+    if not _HEX_12_RE.match(stripped):
+        raise ValueError(
+            f"mac_address must be 12 hex digits (with optional ':' or '-' separators); got {mac!r}"
+        )
+    return stripped.lower()
+
+
+def encode_image_payload(image_bytes: bytes, original_filename: str) -> dict[str, Any]:
+    """Build the ``image: {original_filename, file: <base64>}`` sub-object.
+
+    The RTLS server's ``createFloorplan`` Joi schema requires both keys
+    inside the ``image`` object — see M10's live probe. The ``file``
+    value is a standard RFC 4648 §4 base64 string (NOT URL-safe).
+
+    Examples
+    --------
+    >>> encode_image_payload(b"hello", "x.png")
+    {'original_filename': 'x.png', 'file': 'aGVsbG8='}
+    """
+    if not isinstance(image_bytes, bytes):
+        raise TypeError(f"image_bytes must be bytes, got {type(image_bytes).__name__}")
+    if not isinstance(original_filename, str) or not original_filename:
+        raise ValueError("original_filename must be a non-empty string")
+    return {
+        "original_filename": original_filename,
+        "file": base64.b64encode(image_bytes).decode("ascii"),
+    }
+
+
+def pack_array_param(name: str, values: list[str]) -> list[tuple[str, str]]:
+    """Build a list of ``(key, value)`` tuples for a Rails-style array param.
+
+    Parameters
+    ----------
+    name
+        The parameter name *without* trailing ``[]``. The function adds it.
+    values
+        One value per emitted query parameter.
+
+    Returns
+    -------
+    list[tuple[str, str]]
+        Empty if ``values`` is empty.
+
+    Examples
+    --------
+    >>> pack_array_param("alarm_type_name", ["zone_violation", "buffer_violation"])
+    [('alarm_type_name[]', 'zone_violation'), ('alarm_type_name[]', 'buffer_violation')]
+    """
+    key = f"{name}[]"
+    return [(key, value) for value in values]
+
+
+__all__ = ["encode_image_payload", "normalize_mac", "pack_array_param"]

rtls_sdk/_time.py

@@ -0,0 +1,84 @@
+"""Timestamp conversion helpers.
+
+The RTLS API mixes ISO-8601 strings (reports), epoch milliseconds
+(alarms, zone events, position history), and — for one alarm endpoint —
+``Date.getTime()`` integers (RESEARCH §2). The SDK normalizes by accepting
+``datetime`` everywhere and converting to whatever the target endpoint
+expects.
+
+All inbound ``datetime`` values must be **timezone-aware**. Naive
+datetimes raise ``ValueError`` with a clear message; the SDK refuses to
+guess UTC vs. local time.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+
+def _ensure_aware(dt: datetime, *, arg_name: str = "dt") -> datetime:
+    """Reject naive datetimes early.
+
+    ``dt.tzinfo`` is ``None`` for naive datetimes. We reject rather than
+    assume UTC because silent assumption is the kind of bug that causes
+    off-by-hours data joins.
+    """
+    if dt.tzinfo is None or dt.tzinfo.utcoffset(dt) is None:
+        raise ValueError(
+            f"{arg_name} must be a timezone-aware datetime — "
+            f"the SDK does not assume UTC. Use datetime.now(timezone.utc) "
+            f"or attach a tzinfo before passing it in."
+        )
+    return dt
+
+
+def to_epoch_ms(dt: datetime, *, arg_name: str = "dt") -> int:
+    """Convert a tz-aware datetime to integer epoch milliseconds.
+
+    Used for alarms, zone events, position history, and other endpoints
+    that accept ``from=`` / ``to=`` as millisecond integers.
+
+    Raises
+    ------
+    ValueError
+        If ``dt`` is naive (no tzinfo).
+    """
+    dt = _ensure_aware(dt, arg_name=arg_name)
+    return int(dt.timestamp() * 1000)
+
+
+def to_epoch_seconds(dt: datetime, *, arg_name: str = "dt") -> int:
+    """Convert a tz-aware datetime to integer epoch seconds.
+
+    The ``/track_assoc?start=&end=`` endpoint uses seconds, not
+    milliseconds (RESEARCH §4 "Load trackables with active associations").
+    """
+    dt = _ensure_aware(dt, arg_name=arg_name)
+    return int(dt.timestamp())
+
+
+def to_iso8601(dt: datetime, *, arg_name: str = "dt") -> str:
+    """Convert a tz-aware datetime to an ISO-8601 string with offset.
+
+    Used for the reports and external-events endpoints.
+    """
+    dt = _ensure_aware(dt, arg_name=arg_name)
+    return dt.isoformat()
+
+
+def from_epoch_ms(value: int | float) -> datetime:
+    """Build a tz-aware UTC datetime from epoch milliseconds.
+
+    Used by models that surface server-side timestamps. The SDK chooses
+    UTC over local time so consumers can convert downstream without
+    ambiguity.
+    """
+    return datetime.fromtimestamp(value / 1000.0, tz=timezone.utc)
+
+
+__all__ = [
+    "from_epoch_ms",
+    "to_epoch_ms",
+    "to_epoch_seconds",
+    "to_iso8601",
+]

rtls_sdk/compounds/__init__.py

@@ -0,0 +1,19 @@
+"""Compound multi-call workflows.
+
+Each module in this package implements the multi-call sequences that
+DESIGN §4 promised the SDK would collapse into single methods. Resource
+sub-clients in ``rtls_sdk.resources`` delegate here.
+
+Step-name conventions for :class:`PartialFailureError`
+------------------------------------------------------
+
+When a compound fails mid-sequence the exception carries a
+``failed_step`` string. These strings are part of the SDK's public
+contract — callers may key recovery logic off them. They never change
+once shipped.
+
+The strings used by each compound are documented in the docstring of
+its public entry point on the resource sub-client.
+"""
+
+from __future__ import annotations

rtls_sdk/compounds/auth.py

@@ -0,0 +1,100 @@
+"""Compound auth workflows.
+
+Currently ships just ``change_password``. Future compounds (SSO login,
+session-bootstrap variants) may land here.
+
+Step names for ``change_password``: ``validate_old``, ``validate_new``,
+``change_password``, ``reauthenticate``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from ..errors import AuthenticationError, PartialFailureError, RtlsError
+
+if TYPE_CHECKING:
+    from .._client import RtlsClient
+
+
+logger = logging.getLogger("rtls_sdk.compounds.auth")
+
+
+def change_password(client: RtlsClient, old_password: str, new_password: str) -> None:
+    """Change the current user's password and re-authenticate.
+
+    Sequence:
+
+    1. ``validate_old``: confirm the supplied old password matches.
+    2. ``validate_new``: confirm the new password passes server policy.
+    3. ``change_password``: ``PUT /users/changePassword``.
+    4. ``reauthenticate``: clear the current token, swap to the new
+       password, force a fresh login.
+
+    If step 4 fails (server accepted the change but the new login
+    fails for some reason — race, network blip), the SDK raises
+    :class:`AuthenticationError` with explicit guidance: the password
+    is changed server-side but the in-memory state can't continue;
+    reconstruct the client with the new password.
+    """
+    self_user = client.users.me()
+    self_uid = self_user.uid
+    if not self_uid:
+        raise RtlsError("change_password: current user has no uid — cannot proceed")
+
+    completed: list[str] = []
+
+    # Step 1: validate old password.
+    try:
+        client.users.validate(password=old_password, uid=self_uid, isOld=True)
+    except RtlsError as exc:
+        raise PartialFailureError(
+            f"auth.change_password: validate_old failed: {exc}",
+            completed_steps=completed,
+            failed_step="validate_old",
+            cause=exc,
+        ) from exc
+    completed.append("validate_old")
+
+    # Step 2: validate new password.
+    try:
+        client.users.validate(password=new_password, uid=self_uid, isOld=False)
+    except RtlsError as exc:
+        raise PartialFailureError(
+            f"auth.change_password: validate_new failed: {exc}",
+            completed_steps=completed,
+            failed_step="validate_new",
+            cause=exc,
+        ) from exc
+    completed.append("validate_new")
+
+    # Step 3: change password.
+    try:
+        client.users.change_password_raw(
+            self_uid, old_password=old_password, new_password=new_password
+        )
+    except RtlsError as exc:
+        raise PartialFailureError(
+            f"auth.change_password: change_password failed: {exc}",
+            completed_steps=completed,
+            failed_step="change_password",
+            cause=exc,
+        ) from exc
+    completed.append("change_password")
+
+    # Step 4: re-authenticate with the new password.
+    try:
+        client._auth_state.set_password(new_password)
+        client._auth_state.login_if_needed()
+    except (RtlsError, RuntimeError) as exc:
+        raise AuthenticationError(
+            "auth.change_password: the server accepted the password change "
+            "but re-authentication failed. The in-memory client state is "
+            "now stale — reconstruct the client with the new password and "
+            "your existing email.",
+            status_code=getattr(exc, "status_code", None),
+        ) from exc
+
+
+__all__ = ["change_password"]