rtls-sdk 0.2.0__py3-none-any.whl

rtls_sdk/compounds/tags.py

@@ -0,0 +1,404 @@
+"""Compound tag workflows.
+
+Each function here is the multi-call sequence behind one ``TagsAPI``
+compound method. Rollback discipline (DESIGN §4.3 / §4.4 / §4.5):
+
+- ``create`` rolls back tag creation if a subsequent step fails.
+- ``update`` cannot truly roll back a partial update; it raises a
+  ``PartialFailureError`` with stable step names listing what completed.
+- ``delete`` best-effort deletes the attached zone first; failure there
+  is logged and the tag delete proceeds.
+
+The list of stable step-name strings is in each function's docstring.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Final
+
+from ..errors import PartialFailureError, RtlsError
+from ..models import BulkFailure, BulkResult, Tag
+
+if TYPE_CHECKING:
+    from .._client import RtlsClient
+
+
+logger = logging.getLogger("rtls_sdk.compounds.tags")
+
+
+# ZoneSpec — the dict shape callers pass to attach a zone in one go.
+# Not a typed model in v1: the server accepts many fields and we want
+# to pass through whatever the caller provides verbatim.
+ZoneSpec = dict[str, Any]
+
+
+class _Unset:
+    """Sentinel singleton for "argument not supplied" semantics."""
+
+    _instance: _Unset | None = None
+
+    def __new__(cls) -> _Unset:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+UNSET: Final[_Unset] = _Unset()
+
+
+def create_tag(
+    client: RtlsClient,
+    name: str,
+    *,
+    attached_zone: ZoneSpec | None = None,
+    groups: list[str] | None = None,
+    **fields: Any,
+) -> Tag:
+    """Create a tag, optionally attaching a zone and group memberships.
+
+    Step names (stable, part of the API contract):
+    ``create_tag``, ``create_zone``, ``replace_groups``,
+    ``update_tag_with_zone_uid``.
+
+    Rollback: if any step after ``create_tag`` fails, the SDK tries to
+    ``delete_raw`` the freshly-created tag. If that rollback also fails,
+    :class:`PartialFailureError` carries both errors and a
+    ``partial_result`` with the orphaned uid for manual cleanup.
+    """
+    completed: list[str] = []
+    partial: dict[str, Any] = {"tag_uid": None, "zone_uid": None}
+
+    # Step 1: create the tag.
+    try:
+        tag = client.tags.create_raw(name=name, **fields)
+    except RtlsError:
+        raise
+    completed.append("create_tag")
+    partial["tag_uid"] = tag.uid
+
+    # Step 2: optionally attach a zone bound to this tag.
+    zone_uid: str | None = None
+    if attached_zone is not None:
+        try:
+            zone_payload = {
+                **attached_zone,
+                "trackable_object_uid": tag.uid,
+                "dynamic": True,
+            }
+            zone = client.zones.create_raw(name=zone_payload.pop("name"), **zone_payload)
+            zone_uid = zone.uid
+        except RtlsError as exc:
+            _rollback_tag(client, tag.uid, partial=partial)
+            raise PartialFailureError(
+                f"tags.create: create_zone failed: {exc}",
+                completed_steps=completed,
+                failed_step="create_zone",
+                cause=exc,
+                partial_result=partial,
+            ) from exc
+        completed.append("create_zone")
+        partial["zone_uid"] = zone_uid
+
+    # Step 3: optionally set group memberships.
+    if groups is not None:
+        try:
+            client.tags.replace_groups(tag.uid, groups, no_notify=True)
+        except RtlsError as exc:
+            _rollback_zone(client, zone_uid)
+            _rollback_tag(client, tag.uid, partial=partial)
+            raise PartialFailureError(
+                f"tags.create: replace_groups failed: {exc}",
+                completed_steps=completed,
+                failed_step="replace_groups",
+                cause=exc,
+                partial_result=partial,
+            ) from exc
+        completed.append("replace_groups")
+
+    # Step 4: if we created a bound zone, write self_zone_uid back onto
+    # the tag so its server-side state matches the binding.
+    final_tag: Tag = tag
+    if zone_uid is not None:
+        try:
+            final_tag = client.tags.update_raw(tag.uid, self_zone_uid=zone_uid)
+        except RtlsError as exc:
+            # Don't roll back here — the tag exists, the zone exists,
+            # they're bound on the zone side. The user can recover by
+            # calling tags.update(uid, attached_zone=...) themselves.
+            raise PartialFailureError(
+                f"tags.create: update_tag_with_zone_uid failed: {exc}",
+                completed_steps=completed,
+                failed_step="update_tag_with_zone_uid",
+                cause=exc,
+                partial_result=partial,
+            ) from exc
+        completed.append("update_tag_with_zone_uid")
+
+    return final_tag
+
+
+def _rollback_tag(client: RtlsClient, uid: str, *, partial: dict[str, Any]) -> None:
+    """Best-effort delete of a tag created by a now-failing compound."""
+    try:
+        client.tags.delete_raw(uid)
+        partial["tag_uid"] = None
+    except RtlsError as exc:
+        logger.warning("rollback of created tag %s failed: %s", uid, exc)
+
+
+def _rollback_zone(client: RtlsClient, uid: str | None) -> None:
+    if uid is None:
+        return
+    try:
+        client.zones.delete_raw(uid)
+    except RtlsError as exc:
+        logger.warning("rollback of created zone %s failed: %s", uid, exc)
+
+
+def update_tag(
+    client: RtlsClient,
+    uid: str,
+    *,
+    attached_zone: ZoneSpec | None | _Unset = UNSET,
+    groups: list[str] | None | _Unset = UNSET,
+    **fields: Any,
+) -> Tag:
+    """Diff-driven update of a tag's fields, attached zone, and groups.
+
+    Sentinel ``...`` marks "leave unchanged". Pass ``attached_zone=None``
+    to explicitly *remove* the bound zone; pass a dict to set/replace it.
+    Same for ``groups``.
+
+    Step names (stable):
+    ``load_current_tag``, ``delete_attached_zone``,
+    ``create_attached_zone``, ``update_attached_zone``,
+    ``replace_groups``, ``update_tag``.
+
+    No rollback path — partial updates cannot be unwound cleanly. On
+    failure the SDK raises :class:`PartialFailureError` listing which
+    steps completed; the user reconciles state.
+    """
+    completed: list[str] = []
+
+    # Step 1: load current state so we can compute the zone diff.
+    try:
+        current = client.tags.get(uid)
+    except RtlsError as exc:
+        raise PartialFailureError(
+            f"tags.update: load_current_tag failed: {exc}",
+            completed_steps=completed,
+            failed_step="load_current_tag",
+            cause=exc,
+        ) from exc
+    completed.append("load_current_tag")
+
+    # Step 2: zone diff. UNSET means "leave unchanged".
+    if not isinstance(attached_zone, _Unset):
+        existing_zone_uid = current.self_zone_uid
+        if attached_zone is None and existing_zone_uid is not None:
+            # Removing.
+            step = "delete_attached_zone"
+            try:
+                client.zones.delete_raw(existing_zone_uid)
+            except RtlsError as exc:
+                raise PartialFailureError(
+                    f"tags.update: {step} failed: {exc}",
+                    completed_steps=completed,
+                    failed_step=step,
+                    cause=exc,
+                ) from exc
+            completed.append(step)
+            fields["self_zone_uid"] = None
+        elif attached_zone is not None and existing_zone_uid is None:
+            # Creating new bound zone.
+            step = "create_attached_zone"
+            try:
+                payload = {
+                    **attached_zone,
+                    "trackable_object_uid": uid,
+                    "dynamic": True,
+                }
+                new_zone = client.zones.create_raw(name=payload.pop("name"), **payload)
+            except RtlsError as exc:
+                raise PartialFailureError(
+                    f"tags.update: {step} failed: {exc}",
+                    completed_steps=completed,
+                    failed_step=step,
+                    cause=exc,
+                ) from exc
+            completed.append(step)
+            fields["self_zone_uid"] = new_zone.uid
+        elif attached_zone is not None and existing_zone_uid is not None:
+            # Updating existing bound zone.
+            step = "update_attached_zone"
+            try:
+                client.zones.update_raw(existing_zone_uid, **attached_zone)
+            except RtlsError as exc:
+                raise PartialFailureError(
+                    f"tags.update: {step} failed: {exc}",
+                    completed_steps=completed,
+                    failed_step=step,
+                    cause=exc,
+                ) from exc
+            completed.append(step)
+
+    # Step 3: groups diff.
+    if not isinstance(groups, _Unset):
+        step = "replace_groups"
+        try:
+            client.tags.replace_groups(uid, groups or [], no_notify=True)
+        except RtlsError as exc:
+            raise PartialFailureError(
+                f"tags.update: {step} failed: {exc}",
+                completed_steps=completed,
+                failed_step=step,
+                cause=exc,
+            ) from exc
+        completed.append(step)
+
+    # Step 4: write remaining field updates onto the tag.
+    if fields:
+        step = "update_tag"
+        try:
+            tag = client.tags.update_raw(uid, **fields)
+        except RtlsError as exc:
+            raise PartialFailureError(
+                f"tags.update: {step} failed: {exc}",
+                completed_steps=completed,
+                failed_step=step,
+                cause=exc,
+            ) from exc
+        completed.append(step)
+        return tag
+
+    # No-op update — re-fetch to give the caller a fresh view.
+    return client.tags.get(uid)
+
+
+def delete_tag(client: RtlsClient, target: Tag | str, *, skip_load: bool = False) -> None:
+    """Delete a tag, cascading to its attached zone if any.
+
+    Step names: ``load_tag``, ``delete_attached_zone``, ``delete_tag``.
+
+    ``delete_attached_zone`` failure is logged at WARNING and the
+    cascade continues — leaving an orphan zone behind is preferable to
+    leaving a half-deleted tag.
+
+    Pass a :class:`Tag` instance to skip the load step.
+    """
+    completed: list[str] = []
+    if isinstance(target, Tag):
+        tag: Tag = target
+    elif skip_load:
+        tag = Tag.from_wire({"uid": target, "name": "", "self_zone_uid": None})
+    else:
+        try:
+            tag = client.tags.get(target)
+        except RtlsError as exc:
+            raise PartialFailureError(
+                f"tags.delete: load_tag failed: {exc}",
+                completed_steps=completed,
+                failed_step="load_tag",
+                cause=exc,
+            ) from exc
+        completed.append("load_tag")
+
+    if tag.self_zone_uid:
+        try:
+            client.zones.delete_raw(tag.self_zone_uid)
+            completed.append("delete_attached_zone")
+        except RtlsError as exc:
+            logger.warning(
+                "tags.delete: orphan attached zone %s on tag %s (%s)",
+                tag.self_zone_uid,
+                tag.uid,
+                exc,
+            )
+
+    try:
+        client.tags.delete_raw(tag.uid)
+    except RtlsError as exc:
+        raise PartialFailureError(
+            f"tags.delete: delete_tag failed: {exc}",
+            completed_steps=completed,
+            failed_step="delete_tag",
+            cause=exc,
+            partial_result={"tag_uid": tag.uid},
+        ) from exc
+
+
+def bulk_delete_tags(client: RtlsClient, targets: list[Tag | str]) -> BulkResult[None]:
+    """Loop :func:`delete_tag` over a list with continue-on-error semantics."""
+    result: BulkResult[None] = BulkResult()
+    for target in targets:
+        try:
+            delete_tag(client, target)
+            result.succeeded.append(None)
+        except RtlsError as exc:
+            uid = target.uid if isinstance(target, Tag) else target
+            result.failures.append(BulkFailure(error=exc, input=target, uid=uid))
+    return result
+
+
+def bulk_update_tags(
+    client: RtlsClient, uids: list[str], changes: dict[str, Any]
+) -> BulkResult[Tag]:
+    """Loop :func:`update_tag` over a list with continue-on-error.
+
+    ``changes`` is applied identically to each uid. ``attached_zone`` and
+    ``groups`` are treated as ordinary fields here — they're delegated
+    to :func:`update_tag` which interprets them.
+    """
+    attached_zone = changes.pop("attached_zone", UNSET)
+    groups = changes.pop("groups", UNSET)
+    result: BulkResult[Tag] = BulkResult()
+    for uid in uids:
+        try:
+            tag = update_tag(
+                client,
+                uid,
+                attached_zone=attached_zone,
+                groups=groups,
+                **changes,
+            )
+            result.succeeded.append(tag)
+        except RtlsError as exc:
+            result.failures.append(BulkFailure(error=exc, input=uid, uid=uid))
+    return result
+
+
+def list_active_in_period(
+    client: RtlsClient,
+    sublocation_uid: str,
+    start: datetime,
+    end: datetime,
+) -> list[Tag]:
+    """Inner-join trackables and active associations over a window.
+
+    Two underlying calls — both are required; if either fails, raise
+    (rather than return a half-joined result that pretends to be
+    complete).
+    """
+    tags = client.tags.list_active_for_period(start, end, sublocation_uid=sublocation_uid)
+    associations = client.associations.list_active_in_period(start, end)
+    bound_uids = {assoc.obj_uid for assoc in associations if assoc.obj_uid}
+    return [tag for tag in tags if tag.uid in bound_uids]
+
+
+__all__ = [
+    "ZoneSpec",
+    "bulk_delete_tags",
+    "bulk_update_tags",
+    "create_tag",
+    "delete_tag",
+    "list_active_in_period",
+    "update_tag",
+]

rtls_sdk/compounds/users.py

@@ -0,0 +1,143 @@
+"""Compound user workflows.
+
+Step-name conventions:
+
+- ``create``: ``create_user``, ``bind_project_role``, ``delete_user_rollback``.
+- ``update``: ``update_user``, ``bind_project_role``.
+
+A successful ``create`` rolls back the freshly-created user if the
+project-role binding step fails. ``update`` does not have a clean
+rollback path — partial updates land in ``PartialFailureError`` with
+``completed_steps`` for the caller to reconcile.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from ..errors import PartialFailureError, RtlsError
+from ..models import Role, User
+
+if TYPE_CHECKING:
+    from .._client import RtlsClient
+
+
+logger = logging.getLogger("rtls_sdk.compounds.users")
+
+
+def create_user(
+    client: RtlsClient,
+    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.
+
+    Step names: ``create_user``, ``bind_project_role``,
+    ``delete_user_rollback``.
+
+    If the user comes back from the server as ``COMPANY_ADMIN``, the
+    role binding is skipped — they already have implicit access at the
+    company level (matches the JS reference client's check).
+    """
+    user = client.users.create_raw(email, password, **fields)
+    completed = ["create_user"]
+
+    if project_role is not None and project_uid is not None:
+        if user.role == Role.COMPANY_ADMIN:
+            # Company admins don't need per-project role assignment.
+            return user
+
+        role_str = project_role.value if isinstance(project_role, Role) else project_role
+        try:
+            client.users.update_access(project_uid, uid=user.uid or "", role=role_str)
+        except RtlsError as exc:
+            # Roll back the user create.
+            rollback_uid = user.uid
+            try:
+                if rollback_uid:
+                    client.users.delete(rollback_uid)
+                completed.append("delete_user_rollback")
+                partial: dict[str, Any] = {"user_uid": None}
+            except RtlsError as rollback_exc:
+                logger.warning(
+                    "rollback of created user %s failed: %s",
+                    rollback_uid,
+                    rollback_exc,
+                )
+                partial = {"user_uid": rollback_uid}
+            raise PartialFailureError(
+                f"users.create: bind_project_role failed: {exc}",
+                completed_steps=completed,
+                failed_step="bind_project_role",
+                cause=exc,
+                partial_result=partial,
+            ) from exc
+    return user
+
+
+def update_user(
+    client: RtlsClient,
+    uid: str,
+    *,
+    project_uid: str | None = None,
+    project_role: str | Role | None = None,
+    **fields: Any,
+) -> User:
+    """Update a user's profile + (optionally) their project role.
+
+    Step names: ``update_user``, ``bind_project_role``.
+
+    No rollback — server-side updates can't be cleanly reversed. On
+    partial failure the SDK raises :class:`PartialFailureError` with
+    ``completed_steps=["update_user"]`` so the caller knows the user's
+    fields were updated but their role binding wasn't.
+
+    Self-edit handling: if the user being updated is the SDK's current
+    user, and the update changes the email, the SDK refreshes the
+    stored email so subsequent ``X-User-Email`` headers stay valid.
+    """
+    # Identify self-edit BEFORE the update so we know what to refresh
+    # after. The lazy lookup of user_uid via me() is gated on email
+    # being part of the update — no extra GET if we're not changing
+    # email or scope.
+    self_uid = client._auth_state.user_uid
+    if self_uid is None and "email" in fields:
+        try:
+            self_uid = client.users.me().uid
+        except RtlsError:
+            self_uid = None
+
+    user = client.users.update_raw(uid, **fields)
+    completed = ["update_user"]
+
+    # Self-edit detection: refresh the auth state's cached email.
+    if self_uid and uid == self_uid:
+        new_email = fields.get("email")
+        if isinstance(new_email, str):
+            client._auth_state._email = new_email
+
+    if project_role is not None and project_uid is not None:
+        if user.role == Role.COMPANY_ADMIN:
+            return user
+
+        role_str = project_role.value if isinstance(project_role, Role) else project_role
+        try:
+            client.users.update_access(project_uid, uid=uid, role=role_str)
+        except RtlsError as exc:
+            raise PartialFailureError(
+                f"users.update: bind_project_role failed: {exc}",
+                completed_steps=completed,
+                failed_step="bind_project_role",
+                cause=exc,
+            ) from exc
+        completed.append("bind_project_role")
+
+    return user
+
+
+__all__ = ["create_user", "update_user"]