rtls-sdk 0.2.0__py3-none-any.whl

rtls_sdk/models/bulk.py

@@ -0,0 +1,80 @@
+"""BulkResult — return type for bulk operations.
+
+A ``BulkResult[T]`` is the SDK's standard "I tried N things and N1
+succeeded and N2 failed" shape (DESIGN §2.3 / §5.4). Used by every bulk
+method that follows the continue-on-error semantic (the M3 default —
+RESEARCH §9 R1).
+
+This is a dataclass, not a pydantic model. ``BulkFailure.error`` carries
+a live ``RtlsError`` instance — pydantic would refuse to validate that
+without contortions, and the user-facing benefit of pydantic (alias-
+tolerant deserialization, JSON dump) doesn't apply here: these objects
+are constructed by the SDK, never parsed from wire format.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar
+
+from ..errors import RtlsError
+
+T = TypeVar("T")
+
+
+@dataclass
+class BulkFailure:
+    """One row that failed inside a bulk operation.
+
+    Attributes
+    ----------
+    error
+        The typed SDK exception that fired for this row.
+    input
+        Whatever the caller passed for this row (e.g. a uid string, a
+        dict of fields). Useful for retrying the failed subset.
+    uid
+        Convenience accessor when ``input`` is itself a uid.
+    """
+
+    error: RtlsError
+    input: Any = None
+    uid: str | None = None
+
+
+@dataclass
+class BulkResult(Generic[T]):
+    """Result of a continue-on-error bulk operation.
+
+    The SDK accumulates successes and failures separately so the caller
+    can react to a partial outcome without parsing exception messages.
+
+    Examples
+    --------
+    >>> result = client.tags.bulk_delete(["t-1", "t-missing", "t-3"])
+    >>> result.success_count, result.failure_count
+    (2, 1)
+    >>> result.failures[0].error
+    NotFound('trackable t-missing not found')
+    """
+
+    succeeded: list[T] = field(default_factory=list)
+    failures: list[BulkFailure] = field(default_factory=list)
+
+    @property
+    def success_count(self) -> int:
+        return len(self.succeeded)
+
+    @property
+    def failure_count(self) -> int:
+        return len(self.failures)
+
+    def __bool__(self) -> bool:
+        """Truthy when nothing failed.
+
+        Lets callers write ``if result: ...`` for the happy path.
+        """
+        return self.failure_count == 0
+
+
+__all__ = ["BulkFailure", "BulkResult"]

rtls_sdk/models/company.py

@@ -0,0 +1,32 @@
+"""Company model.
+
+The server returns ``Company`` under several wire envelopes (login,
+``/companies``, SSO callback) with different field subsets — see
+RESEARCH §3. The SDK collapses them into one model with optional fields
+that absorb the divergence.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._base import _BaseModel
+
+
+class Company(_BaseModel):
+    """A company / tenant.
+
+    Many fields are optional because the wire payload varies by endpoint;
+    ``uid`` and ``name`` are always present.
+    """
+
+    uid: str
+    name: str
+    scope: str | None = None
+    role_uid: str | None = None
+    role: str | None = None
+    taggings_count: int | None = None
+    user_params: dict[str, Any] | None = None
+
+
+__all__ = ["Company"]

rtls_sdk/models/csv_blob.py

@@ -0,0 +1,40 @@
+"""``CsvBlob`` — the SDK's return type for CSV report downloads.
+
+Dataclass with a ``filename`` hint (parsed from the server's
+``response-filename`` custom header — RESEARCH §5 quirk #11) plus a
+:meth:`write_to` convenience.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class CsvBlob:
+    """An in-memory CSV download.
+
+    Attributes
+    ----------
+    content
+        The full CSV bytes. Already-deduped of duplicate header rows
+        when the report came back chunked.
+    filename
+        Server-suggested filename from the ``response-filename`` header,
+        or ``None`` if absent. Use it as the default when saving to disk.
+    """
+
+    content: bytes
+    filename: str | None = None
+
+    def write_to(self, path: str | Path) -> None:
+        """Save :attr:`content` to ``path``.
+
+        Convenience helper — equivalent to
+        ``Path(path).write_bytes(self.content)``.
+        """
+        Path(path).write_bytes(self.content)
+
+
+__all__ = ["CsvBlob"]

rtls_sdk/models/floorplan.py

@@ -0,0 +1,42 @@
+"""Floorplan model."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._base import _BaseModel
+
+
+class Floorplan(_BaseModel):
+    """A floorplan image attached to a sublocation.
+
+    The server returns ``display_name`` as the user-facing label and
+    ``url`` as a relative path of the form
+    ``/uploads/floorplan/image/<uid>/<original_filename>``. There is
+    no ``name`` field — the M9 read-only model carried one in error,
+    fixed in M10.
+
+    Pixel dimensions (``width``, ``height``) are server-computed from
+    the uploaded image; ``size`` is the byte size.
+
+    Fields kept permissive (``str | None``, ``Any``) because some
+    deployments null-out values the SDK doesn't know what to do with
+    yet (e.g. ``img_blob`` is ``None`` on the test server).
+    """
+
+    uid: str
+    sublocation_uid: str | None = None
+    url: str | None = None
+    display_name: str | None = None
+    image_scale: float | None = None
+    image_rotation: float | None = None
+    image_offset_x: float | None = None
+    image_offset_y: float | None = None
+    width: int | None = None
+    height: int | None = None
+    size: int | None = None
+    selected: int | bool | None = None
+    img_blob: Any = None
+
+
+__all__ = ["Floorplan"]

rtls_sdk/models/group.py

@@ -0,0 +1,20 @@
+"""Group model."""
+
+from __future__ import annotations
+
+from ._base import _BaseModel
+
+
+class Group(_BaseModel):
+    """A trackable group.
+
+    Groups are flat collections of trackables. Membership lives on the
+    trackable side (``Tag.groups``); the group itself only carries a name
+    and metadata.
+    """
+
+    uid: str
+    name: str
+
+
+__all__ = ["Group"]

rtls_sdk/models/heatmap.py

@@ -0,0 +1,37 @@
+"""Heatmap report models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import Field
+
+from ._base import _BaseModel
+
+
+class HeatmapInput(_BaseModel):
+    """The request shape echoed back by the heatmap status endpoint."""
+
+    start: datetime | str | int | None = None
+    end: datetime | str | int | None = None
+    tag_uids: list[str] = Field(default_factory=list, alias="uids")
+    names: list[str] | None = None
+
+
+class Heatmap(_BaseModel):
+    """A completed heatmap report.
+
+    ``image_url`` is the URL of the rendered PNG/SVG (built from the
+    server's hostname + ``/api/v2/heatmap/{uid}`` + any query the
+    server returned).
+    """
+
+    uid: str
+    image_url: str
+    name: str | None = None
+    input: HeatmapInput | None = None
+    output_metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+__all__ = ["Heatmap", "HeatmapInput"]

rtls_sdk/models/import_result.py

@@ -0,0 +1,42 @@
+"""Return type for ``nodes.import_``.
+
+Built by the SDK after a validate + per-row create loop. Dataclass
+rather than pydantic because the ``failures`` list carries live
+:class:`BulkFailure` instances (which wrap typed exceptions).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .bulk import BulkFailure
+
+
+@dataclass
+class ImportResult:
+    """Result of a CSV-style import operation.
+
+    Attributes
+    ----------
+    valid
+        MAC addresses the server's validation endpoint accepted as new.
+    invalid
+        MAC addresses rejected as malformed or otherwise invalid.
+    duplicate
+        MAC addresses already present in the server.
+    imported_count
+        Number of nodes actually created during the per-row loop. Equal
+        to ``len(valid) - len(failures)`` after a successful run.
+    failures
+        Per-row failures (only populated when validation succeeded but
+        subsequent ``nodes.create`` calls failed for individual rows).
+    """
+
+    valid: list[str] = field(default_factory=list)
+    invalid: list[str] = field(default_factory=list)
+    duplicate: list[str] = field(default_factory=list)
+    imported_count: int = 0
+    failures: list[BulkFailure] = field(default_factory=list)
+
+
+__all__ = ["ImportResult"]

rtls_sdk/models/node.py

@@ -0,0 +1,28 @@
+"""Node (hardware tag) model.
+
+The same model is used for standalone-list responses and the embedded
+``node`` field inside Trackable. The embedded form carries fewer fields;
+they're declared optional so both parse cleanly.
+"""
+
+from __future__ import annotations
+
+from ._base import _BaseModel
+
+
+class Node(_BaseModel):
+    """A hardware node (tag/beacon) registered to the system."""
+
+    uid: str | None = None
+    mac_address: str | None = None
+    # node_id is an int on the wire (a short numeric RF protocol ID, e.g. 5).
+    # M2 read tests assumed string; the live server returns int. Accept both
+    # so the model parses cleanly across deployments / mock fixtures.
+    node_id: int | str | None = None
+    responsive: bool | None = None
+    idle: bool | None = None
+    cbid: str | None = None
+    parent_sublocation_uid: str | None = None
+
+
+__all__ = ["Node"]

rtls_sdk/models/notification.py

@@ -0,0 +1,38 @@
+"""Notification profile and notification-type models."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import model_validator
+
+from ._base import _BaseModel
+
+
+class NotificationProfile(_BaseModel):
+    """A notification profile: rules for emitting alerts on alarms."""
+
+    uid: str
+    name: str | None = None
+
+
+class NotificationType(_BaseModel):
+    """One entry from ``GET /notification_types``.
+
+    The live server returns this list as bare strings (e.g.
+    ``"zone_violation"``); some deployments use objects. The model
+    accepts either form — a string is wrapped as ``NotificationType(name=...)``.
+    """
+
+    name: str | None = None
+    type: str | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize(cls, data: Any) -> Any:
+        if isinstance(data, str):
+            return {"name": data}
+        return data
+
+
+__all__ = ["NotificationProfile", "NotificationType"]

rtls_sdk/models/position.py

@@ -0,0 +1,66 @@
+"""Position model with embedded-vs-standalone normalization.
+
+The server emits position data under two wire formats (RESEARCH §3):
+
+- **Embedded** inside Trackable: ``sl_uid``, ``sl_id``, ``dev_id``, ``mac``, ``ts``.
+- **Standalone** under ``/positions``: ``area_uid``, ``trackable_uid``, ``mac_address``, ``ts``.
+
+The SDK normalizes both into one canonical shape with the standalone
+field names. Callers see ``area_uid``, never ``sl_uid``.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import model_validator
+
+from .._time import from_epoch_ms
+from ._base import _BaseModel
+
+
+class Position(_BaseModel):
+    """A position fix for a trackable.
+
+    Field names are canonical (the standalone-endpoint form). Wire-format
+    aliases ``sl_uid`` / ``dev_id`` / ``mac`` are rewritten at parse time
+    so consumers don't need to know which endpoint produced the data.
+    """
+
+    area_uid: str | None = None
+    trackable_uid: str | None = None
+    mac_address: str | None = None
+    project_uid: str | None = None
+    inactive: bool | None = None
+    x: float | None = None
+    y: float | None = None
+    z: float | None = None
+    ts: datetime | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _rewrite_aliases(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+
+        out = dict(data)
+
+        # Embedded-form → canonical-form renames.
+        if "area_uid" not in out and "sl_uid" in out:
+            out["area_uid"] = out["sl_uid"]
+        if "trackable_uid" not in out and "dev_id" in out:
+            out["trackable_uid"] = out["dev_id"]
+        if "mac_address" not in out and "mac" in out:
+            out["mac_address"] = out["mac"]
+
+        # Server sends ts as epoch ms; pydantic can parse ints to datetime
+        # if we hand it a float-seconds value, so convert eagerly.
+        ts_raw = out.get("ts")
+        if isinstance(ts_raw, (int, float)) and not isinstance(ts_raw, bool):
+            out["ts"] = from_epoch_ms(ts_raw)
+
+        return out
+
+
+__all__ = ["Position"]

rtls_sdk/models/project.py

@@ -0,0 +1,26 @@
+"""Project model."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field
+
+from ._base import _BaseModel
+
+
+class Project(_BaseModel):
+    """A project — a unit of access control + scoping.
+
+    Most operator-level resources (tags, zones, alarms, …) are scoped to
+    a project. The currently-active project is set on the SDK via the
+    ``project_uid=`` constructor argument or ``RTLS_PROJECT_UID`` env var.
+    """
+
+    uid: str
+    name: str | None = None
+    settings: dict[str, Any] | None = None
+    users: list[Any] = Field(default_factory=list)
+
+
+__all__ = ["Project"]

rtls_sdk/models/pws.py

@@ -0,0 +1,38 @@
+"""PWS (proximity warning system) event + report models."""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from ._base import _BaseModel
+
+
+class PwsEvent(_BaseModel):
+    """One PWS event row from ``/external_events?event_type[]=pws``.
+
+    Fields beyond uid/ts are deployment-specific; rely on ``.raw`` for
+    anything the SDK doesn't expose explicitly.
+    """
+
+    uid: str | None = None
+    trackable_uid: str | None = None
+    ts: int | float | None = None
+    zone_uid: str | None = None
+    type: str | None = None
+
+
+class PwsReport(_BaseModel):
+    """Aggregated PWS report — every page concatenated in memory.
+
+    For windows that span many pages, prefer
+    :meth:`EventsAPI.iter_pws` (lazy) over :meth:`ReportsAPI.pws`
+    (eager). The aggregate form is convenient for ad-hoc analysis;
+    the lazy form is friendlier to RAM and lets you stop early.
+    """
+
+    events: list[PwsEvent] = Field(default_factory=list)
+    total_count: int | None = None
+    timezone: str | None = None
+
+
+__all__ = ["PwsEvent", "PwsReport"]

rtls_sdk/models/report.py

@@ -0,0 +1,34 @@
+"""Report and report-type models.
+
+M2 ships just the read surface (``reports.list`` / ``reports.get``); the
+heatmap / PWS / CSV report compounds land in M7.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from ._base import _BaseModel
+
+
+class ReportType(str, Enum):
+    """Enumerated report types accepted by ``reports.list(..., type=)``."""
+
+    DISTANCE = "distance"
+    ALARMS = "alarms"
+    ATTENDANCE = "attendance"
+    ZONE_ACTIVITY = "zone_activity"
+    HEATMAP = "heatmap"
+    PWS = "pws"
+
+
+class Report(_BaseModel):
+    """A generated report's metadata."""
+
+    uid: str
+    name: str | None = None
+    type: str | None = None
+    status: int | None = None
+
+
+__all__ = ["Report", "ReportType"]

rtls_sdk/models/session_context.py

@@ -0,0 +1,81 @@
+"""Return type for :meth:`ContextAPI.load` — the M6 mega-method.
+
+One call hydrates ~20 entity types. Each is optional (a sub-call failure
+records the exception on :attr:`errors` and leaves that field as its
+default), so a partial-but-useful snapshot is preferable to a blanket
+failure.
+
+Dataclass rather than pydantic because :attr:`errors` holds live
+:class:`RtlsError` instances. Construction is SDK-internal; the model
+never round-trips through JSON.
+
+Stable sub-resource names (used as ``errors`` dict keys; documented as
+part of the public API contract): ``sites``, ``areas``, ``floorplans``,
+``tags``, ``associations``, ``zones``, ``zone_prototypes``, ``groups``,
+``alarms``, ``notifications``, ``notification_types``, ``subscribers``,
+``system_subscribers``, ``anchors``, ``nodes``, ``users``, ``user_roles``,
+``tag_templates``, ``helper_link``, ``monitor_link``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from ..errors import RtlsError
+from .alarm import Alarm
+from .anchor import Anchor
+from .area import Area
+from .association import Association
+from .floorplan import Floorplan
+from .group import Group
+from .node import Node
+from .notification import NotificationProfile, NotificationType
+from .site import Site
+from .subscriber import Subscriber, SystemSubscriber
+from .tag import Tag
+from .tag_template import TagTemplate
+from .user import Role, User
+from .zone import Zone
+
+
+@dataclass
+class SessionContext:
+    """Hydrated snapshot of the deployment under the current scope."""
+
+    sites: list[Site] = field(default_factory=list)
+    areas: list[Area] = field(default_factory=list)
+    floorplans: list[Floorplan] = field(default_factory=list)
+    tags: list[Tag] = field(default_factory=list)
+    associations: list[Association] = field(default_factory=list)
+    zones: list[Zone] = field(default_factory=list)
+    zone_prototypes: list[dict[str, Any]] = field(default_factory=list)
+    groups: list[Group] = field(default_factory=list)
+    alarms: list[Alarm] = field(default_factory=list)
+    notifications: list[NotificationProfile] = field(default_factory=list)
+    notification_types: list[NotificationType] = field(default_factory=list)
+    subscribers: list[Subscriber] = field(default_factory=list)
+    system_subscribers: list[SystemSubscriber] = field(default_factory=list)
+    anchors: list[Anchor] = field(default_factory=list)
+    nodes: list[Node] = field(default_factory=list)
+    users: list[User] = field(default_factory=list)
+    user_roles: list[Role] = field(default_factory=list)
+    tag_templates: list[TagTemplate] = field(default_factory=list)
+    monitor_link: str | None = None
+    helper_link: str | None = None
+    partial: bool = False
+    errors: dict[str, RtlsError] = field(default_factory=dict)
+    loaded_at: datetime | None = None
+
+    def errors_summary(self) -> dict[str, str]:
+        """Return a JSON-serializable view of :attr:`errors`.
+
+        ``RtlsError`` instances aren't directly serializable; this
+        method converts each to a short ``"<type>: <message>"`` string,
+        suitable for logging or for caching the snapshot to disk.
+        """
+        return {name: f"{type(err).__name__}: {err}" for name, err in self.errors.items()}
+
+
+__all__ = ["SessionContext"]

rtls_sdk/models/site.py

@@ -0,0 +1,31 @@
+"""Site (location) model."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._base import _BaseModel
+
+
+class Site(_BaseModel):
+    """A top-level physical location.
+
+    Sites contain :class:`Area` rows (sublocations). Fields beyond
+    ``uid`` / ``name`` are optional and surface what the server returns
+    on a successful create / read.
+
+    ``shift`` is typed as ``Any`` because the wire format varies by
+    deployment (some servers emit ``{}`` / ``{...}``, others emit
+    ``[]`` / ``[...]`` depending on whether shifts are configured).
+    The SDK doesn't take sides — read it as-is.
+    """
+
+    uid: str
+    name: str | None = None
+    shift: Any = None
+    address: str | None = None
+    country: str | None = None
+    timezone: str | None = None
+
+
+__all__ = ["Site"]