mgraphctl 0.1.0__py3-none-any.whl

mgraphctl/graph/people.py

@@ -0,0 +1,83 @@
+"""Graph operations for people, contacts, directory users and photos (spec §8.5).
+
+Pure: client and parameters in, Graph dicts / PageResult / DownloadResult out.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mgraphctl import odata
+from mgraphctl.errors import GraphError
+from mgraphctl.http import DownloadResult, GraphClient, PageResult
+
+PEOPLE_SELECT = (
+    "id,displayName,scoredEmailAddresses,jobTitle,department,companyName,personType,"
+    "userPrincipalName"
+)
+CONTACTS_SELECT = "id,displayName,emailAddresses,mobilePhone,businessPhones,jobTitle,companyName"
+
+PAGE = 50
+CAP = 250  # spec §5.3: people search, contacts — page_size 50, default limit 20, --all cap 250
+
+
+def search_people(client: GraphClient, q: str, *, limit: int, all_: bool) -> PageResult:
+    """`/me/people` relevance search (spec §8.5 `search`); the endpoint is in maintenance mode."""
+    params = {"$search": odata.kql(q), "$select": PEOPLE_SELECT}
+    return client.paginate(
+        "/me/people", params=params, limit=limit, all_=all_, cap=CAP, page_size=PAGE
+    )
+
+
+def _contact_matches(contact: dict, term: str) -> bool:
+    if term in (contact.get("displayName") or "").casefold():
+        return True
+    return any(
+        term in (addr.get("address") or "").casefold()
+        for addr in contact.get("emailAddresses") or []
+    )
+
+
+def list_contacts(client: GraphClient, *, search: str | None, limit: int, all_: bool) -> PageResult:
+    """Contacts, optionally `$search`-filtered; a 400 on `$search` falls back to a client-side
+    substring match over displayName/email of up to 250 contacts (spec §8.5 `contacts`).
+    """
+    if not search:
+        return client.paginate(
+            "/me/contacts",
+            params={"$select": CONTACTS_SELECT},
+            limit=limit,
+            all_=all_,
+            cap=CAP,
+            page_size=PAGE,
+        )
+    params = {"$select": CONTACTS_SELECT, "$search": odata.kql(search)}
+    try:
+        return client.paginate(
+            "/me/contacts", params=params, limit=limit, all_=all_, cap=CAP, page_size=PAGE
+        )
+    except GraphError as exc:
+        if exc.status != 400:
+            raise
+        page = client.paginate(
+            "/me/contacts",
+            params={"$select": CONTACTS_SELECT},
+            limit=None,
+            all_=True,
+            cap=CAP,
+            page_size=CAP,
+        )
+        term = search.casefold()
+        filtered = [c for c in page.items if _contact_matches(c, term)]
+        bound = CAP if all_ else min(limit, CAP)
+        return PageResult(items=filtered[:bound], truncated=len(filtered) > bound, pages=page.pages)
+
+
+def get_contact(client: GraphClient, contact_id: str) -> dict:
+    return client.get(odata.p("me", "contacts", contact_id))
+
+
+def download_photo(client: GraphClient, upn: str | None, size: str, dest: Path) -> DownloadResult:
+    """`/me/photo/$value` for the signed-in user; `/users/{upn}/photos/{size}/$value` otherwise."""
+    path = "/me/photo/$value" if upn is None else f"{odata.p('users', upn)}/photos/{size}/$value"
+    return client.download(path, dest)

mgraphctl/graph/planner.py

@@ -0,0 +1,415 @@
+"""Graph operations for Planner plans and tasks (spec §8.14).
+
+Pure: client and parameters in, Graph dicts / `Plan` out. Planner paths carry no OData query
+parameters (spec §8.14); slicing (`--limit`) and filtering (bucket, completed) happen client-side
+on values already returned by Graph. `list_plans` and `my_tasks` annotate merged items with
+underscore-prefixed keys (`_groupName`, `_planTitle`, `_bucketName`) used only by text-mode
+columns; JSON callers get them too since `render.emit` serialises `ListResult.items` unchanged.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from mgraphctl import odata
+from mgraphctl.errors import GraphError, MsgraphError, UsageError
+from mgraphctl.graph import users
+from mgraphctl.http import (
+    JSON_HEADERS,
+    BatchRequest,
+    GraphClient,
+    PageResult,
+    Plan,
+    PlannedRequest,
+)
+from mgraphctl.render import to_iso_offset
+from mgraphctl.resolve import looks_like_id, pick_unique, split_id_prefix
+
+# `on_skip`, when given, is called with one human-readable line per batch sub-request that
+# failed (e.g. a group without Planner enabled, or a plan deleted since `my_tasks` read the
+# task list). Both `list_plans` and `my_tasks` degrade gracefully on such a failure — the rest
+# of the merged/annotated result is still returned — rather than failing the whole command;
+# callers pass `render.note` so the omission is visible on stderr instead of silent. `graph/*`
+# functions never call `render` directly (spec §7.2), hence the injected callback.
+OnSkip = Callable[[str], None]
+
+MY_TASKS_PLAN_TITLE_CAP = 20
+PERCENT_VALUES = (0, 50, 100)
+# Not a user-facing cap: large enough that name resolution never misses a real match because
+# a display `--limit` truncated the merged list first.
+RESOLUTION_LIMIT = 10_000
+
+
+def _run(client: GraphClient, plan: Plan) -> Any:
+    """Execute every step of `plan` in order, returning the last step's result."""
+    result: Any = None
+    for step in plan:
+        result = client.execute(step)
+    return result
+
+
+# --------------------------------------------------------------------------- reads
+
+
+def list_plans(
+    client: GraphClient, *, limit: int = 50, on_skip: OnSkip | None = None
+) -> PageResult:
+    """Plans the signed-in user owns, plus every plan of a group they belong to (§8.14).
+
+    `GET /me/planner/plans` ∪ (for each unified group from `users.list_unified_groups`) a
+    `$batch` of `GET /groups/{id}/planner/plans`, deduped by id. Plans found only via a group
+    are annotated with `_groupName` (text column only); the owned list is authoritative and
+    keeps no `_groupName`, but a plan seen in more than one place still gets one if a group
+    supplied it. A group whose batch sub-request fails (e.g. Planner not enabled there) is
+    skipped rather than failing the whole call — same policy as `my_tasks` below for a failed
+    plan-title lookup — reported through `on_skip` when given.
+    """
+    own = client.get("/me/planner/plans") or {}
+    merged: dict[str, dict] = {item["id"]: item for item in own.get("value") or []}
+    groups = users.list_unified_groups(client)
+    if groups:
+        requests = [
+            BatchRequest(
+                id=str(i), method="GET", url=odata.p("groups", g["id"], "planner", "plans")
+            )
+            for i, g in enumerate(groups, 1)
+        ]
+        responses = client.batch(requests)
+        for group, response in zip(groups, responses, strict=True):
+            if response.error is not None:
+                if on_skip is not None:
+                    name = group.get("displayName") or group["id"]
+                    on_skip(f"skipped plans for group {name}: {response.error.message}")
+                continue
+            for item in (response.body or {}).get("value") or []:
+                existing = merged.get(item["id"])
+                if existing is not None:
+                    existing.setdefault("_groupName", group.get("displayName"))
+                else:
+                    merged[item["id"]] = {**item, "_groupName": group.get("displayName")}
+    items = list(merged.values())
+    return PageResult(items=items[:limit], truncated=len(items) > limit, pages=1)
+
+
+def resolve_plan(client: GraphClient, value: str) -> dict:
+    """A plan id, or `title` looked up among `list_plans` (§6.6)."""
+    if looks_like_id(value, "planner"):
+        bare, _ = split_id_prefix(value)
+        return {"id": bare}
+    # Resolution needs every visible plan, not just the first page a `--limit` would keep.
+    candidates = list_plans(client, limit=RESOLUTION_LIMIT)
+    return pick_unique(candidates.items, "title", value, what="plan")
+
+
+def get_plan(client: GraphClient, plan_id: str) -> dict:
+    """`{...plan, "details": {...}}` (spec §8.14 `plan`)."""
+    plan_obj = client.get(odata.p("planner", "plans", plan_id))
+    details = client.get(odata.p("planner", "plans", plan_id, "details"))
+    return {**plan_obj, "details": details}
+
+
+def list_buckets(client: GraphClient, plan_id: str) -> list[dict]:
+    payload = client.get(odata.p("planner", "plans", plan_id, "buckets")) or {}
+    return payload.get("value") or []
+
+
+def resolve_bucket(client: GraphClient, plan_id: str, value: str) -> dict:
+    """A bucket id, or `name` looked up among the plan's buckets (§6.6)."""
+    if looks_like_id(value, "planner"):
+        bare, _ = split_id_prefix(value)
+        return {"id": bare}
+    return pick_unique(list_buckets(client, plan_id), "name", value, what="bucket")
+
+
+def resolve_bucket_for_task(client: GraphClient, task_id: str, value: str) -> dict:
+    """Resolve a `--bucket` name on `update`, where the plan is not already known.
+
+    An id-shaped value never needs the task's plan; a name does, so this fetches the task
+    first to learn `planId` before delegating to `resolve_bucket`.
+    """
+    if looks_like_id(value, "planner"):
+        bare, _ = split_id_prefix(value)
+        return {"id": bare}
+    current = client.get(odata.p("planner", "tasks", task_id))
+    return resolve_bucket(client, current["planId"], value)
+
+
+def list_tasks(
+    client: GraphClient,
+    plan_id: str,
+    *,
+    bucket_id: str | None = None,
+    include_completed: bool = False,
+    limit: int = 50,
+) -> PageResult:
+    """A plan's tasks, hiding completed ones and naming buckets, sliced to `limit` (§8.14)."""
+    payload = client.get(odata.p("planner", "plans", plan_id, "tasks")) or {}
+    items = payload.get("value") or []
+    if not include_completed:
+        items = [t for t in items if t.get("percentComplete") != 100]
+    if bucket_id is not None:
+        items = [t for t in items if t.get("bucketId") == bucket_id]
+    names = {b["id"]: b.get("name") for b in list_buckets(client, plan_id)}
+    for item in items:
+        item["_bucketName"] = names.get(item.get("bucketId"), "")
+    return PageResult(items=items[:limit], truncated=len(items) > limit, pages=1)
+
+
+def my_tasks(
+    client: GraphClient,
+    *,
+    include_completed: bool = False,
+    limit: int = 50,
+    on_skip: OnSkip | None = None,
+) -> PageResult:
+    """The signed-in user's tasks across every plan, annotated with plan titles (§8.14 `--my`).
+
+    A plan whose title lookup fails (e.g. deleted since the task was created) is skipped —
+    that task just keeps a blank `_planTitle` — same graceful-degradation policy as
+    `list_plans` above for a failed group lookup, reported through `on_skip` when given.
+    """
+    payload = client.get("/me/planner/tasks") or {}
+    items = payload.get("value") or []
+    if not include_completed:
+        items = [t for t in items if t.get("percentComplete") != 100]
+    plan_ids = list(dict.fromkeys(t["planId"] for t in items if t.get("planId")))
+    plan_ids = plan_ids[:MY_TASKS_PLAN_TITLE_CAP]
+    titles: dict[str, str] = {}
+    if plan_ids:
+        requests = [
+            BatchRequest(id=str(i), method="GET", url=odata.p("planner", "plans", pid))
+            for i, pid in enumerate(plan_ids, 1)
+        ]
+        responses = client.batch(requests)
+        for pid, response in zip(plan_ids, responses, strict=True):
+            if response.error is None and isinstance(response.body, dict):
+                titles[pid] = response.body.get("title", "")
+            elif on_skip is not None:
+                detail = response.error.message if response.error else "empty response"
+                on_skip(f"skipped plan title for {pid}: {detail}")
+    for item in items:
+        item["_planTitle"] = titles.get(item.get("planId"), "")
+    return PageResult(items=items[:limit], truncated=len(items) > limit, pages=1)
+
+
+def get_task(client: GraphClient, task_id: str) -> dict:
+    """`{...task, "details": {...}}`; a details fetch failure is swallowed (§8.14 `task`)."""
+    task_obj = client.get(odata.p("planner", "tasks", task_id))
+    try:
+        details = client.get(odata.p("planner", "tasks", task_id, "details"))
+    except MsgraphError:
+        details = {}
+    return {**task_obj, "details": details}
+
+
+# --------------------------------------------------------------------------- writes
+
+
+def _create_body(
+    *,
+    plan_id: str,
+    bucket_id: str | None,
+    title: str,
+    due: Any,
+    assignee_oids: list[str],
+    priority: int | None,
+) -> dict:
+    body: dict[str, Any] = {"planId": plan_id}
+    if bucket_id is not None:
+        body["bucketId"] = bucket_id
+    body["title"] = title
+    if due is not None:
+        body["dueDateTime"] = to_iso_offset(due)
+    if priority is not None:
+        body["priority"] = priority
+    if assignee_oids:
+        body["assignments"] = {
+            oid: {"@odata.type": "#microsoft.graph.plannerAssignment", "orderHint": " !"}
+            for oid in assignee_oids
+        }
+    return body
+
+
+def _description_step(tasks_url: str, task_id: str, description: str) -> PlannedRequest:
+    url = f"{tasks_url}/{task_id}/details"
+    return PlannedRequest(
+        "PATCH", url, {**JSON_HEADERS, "If-Match": "{etag}"}, {"description": description}
+    )
+
+
+def _write_description(client: GraphClient, task_id: str, description: str) -> dict:
+    path = odata.p("planner", "tasks", task_id, "details")
+    details = client.get(path) or {}
+    etag = details.get("@odata.etag")
+    headers = {"If-Match": etag} if etag else {}
+    return client.patch(path, json={"description": description}, headers=headers)
+
+
+def plan_create_task(
+    client: GraphClient,
+    *,
+    plan_id: str,
+    bucket_id: str | None = None,
+    title: str,
+    due: Any = None,
+    assignee_oids: list[str] | None = None,
+    priority: int | None = None,
+    description: str | None = None,
+) -> Plan:
+    body = _create_body(
+        plan_id=plan_id,
+        bucket_id=bucket_id,
+        title=title,
+        due=due,
+        assignee_oids=assignee_oids or [],
+        priority=priority,
+    )
+    tasks_url = client.url(odata.p("planner", "tasks"))
+    steps: Plan = [PlannedRequest("POST", tasks_url, dict(JSON_HEADERS), body)]
+    if description is not None:
+        steps.append(_description_step(tasks_url, "{taskId}", description))
+    return steps
+
+
+def run_create_task(
+    client: GraphClient,
+    *,
+    plan_id: str,
+    bucket_id: str | None = None,
+    title: str,
+    due: Any = None,
+    assignee_oids: list[str] | None = None,
+    priority: int | None = None,
+    description: str | None = None,
+) -> dict:
+    body = _create_body(
+        plan_id=plan_id,
+        bucket_id=bucket_id,
+        title=title,
+        due=due,
+        assignee_oids=assignee_oids or [],
+        priority=priority,
+    )
+    task = client.post(odata.p("planner", "tasks"), json=body)
+    if description is not None:
+        details = _write_description(client, task["id"], description)
+        task = {**task, "details": details}
+    return task
+
+
+def _update_body(
+    *,
+    title: str | None = None,
+    due: Any = None,
+    percent: int | None = None,
+    bucket_id: str | None = None,
+    priority: int | None = None,
+    assign_oids: list[str] | None = None,
+    unassign_oids: list[str] | None = None,
+) -> dict:
+    body: dict[str, Any] = {}
+    if title is not None:
+        body["title"] = title
+    if due is not None:
+        body["dueDateTime"] = to_iso_offset(due)
+    if percent is not None:
+        if percent not in PERCENT_VALUES:
+            raise UsageError("USAGE", "--percent must be 0, 50 or 100")
+        body["percentComplete"] = percent
+    if bucket_id is not None:
+        body["bucketId"] = bucket_id
+    if priority is not None:
+        body["priority"] = priority
+    assignments: dict[str, Any] = {}
+    for oid in assign_oids or []:
+        assignments[oid] = {"@odata.type": "#microsoft.graph.plannerAssignment", "orderHint": " !"}
+    for oid in unassign_oids or []:
+        assignments[oid] = None
+    if assignments:
+        body["assignments"] = assignments
+    return body
+
+
+def plan_update_task(
+    client: GraphClient,
+    task_id: str,
+    *,
+    title: str | None = None,
+    due: Any = None,
+    percent: int | None = None,
+    bucket_id: str | None = None,
+    priority: int | None = None,
+    assign_oids: list[str] | None = None,
+    unassign_oids: list[str] | None = None,
+    description: str | None = None,
+) -> Plan:
+    body = _update_body(
+        title=title,
+        due=due,
+        percent=percent,
+        bucket_id=bucket_id,
+        priority=priority,
+        assign_oids=assign_oids,
+        unassign_oids=unassign_oids,
+    )
+    tasks_url = client.url(odata.p("planner", "tasks"))
+    steps: Plan = []
+    if body:
+        headers = {**JSON_HEADERS, "If-Match": "{etag}", "Prefer": "return=representation"}
+        steps.append(PlannedRequest("PATCH", f"{tasks_url}/{task_id}", headers, body))
+    if description is not None:
+        steps.append(_description_step(tasks_url, task_id, description))
+    return steps
+
+
+def run_update_task(
+    client: GraphClient,
+    task_id: str,
+    *,
+    title: str | None = None,
+    due: Any = None,
+    percent: int | None = None,
+    bucket_id: str | None = None,
+    priority: int | None = None,
+    assign_oids: list[str] | None = None,
+    unassign_oids: list[str] | None = None,
+    description: str | None = None,
+) -> dict:
+    body = _update_body(
+        title=title,
+        due=due,
+        percent=percent,
+        bucket_id=bucket_id,
+        priority=priority,
+        assign_oids=assign_oids,
+        unassign_oids=unassign_oids,
+    )
+    result: dict | None = None
+    if body:
+        path = odata.p("planner", "tasks", task_id)
+        etag = (client.get(path) or {}).get("@odata.etag")
+        headers = {"If-Match": etag, "Prefer": "return=representation"}
+        try:
+            result = client.patch(path, json=body, headers=headers)
+        except GraphError as exc:
+            if exc.status != 412:
+                raise
+            etag = (client.get(path) or {}).get("@odata.etag")
+            headers = {"If-Match": etag, "Prefer": "return=representation"}
+            result = client.patch(path, json=body, headers=headers)
+    if description is not None:
+        details = _write_description(client, task_id, description)
+        result = {**(result or {}), "details": details}
+    return result or {}
+
+
+def plan_delete_task(client: GraphClient, task_id: str) -> Plan:
+    url = client.url(odata.p("planner", "tasks", task_id))
+    return [PlannedRequest("DELETE", url, {"If-Match": "{etag}"}, None, expect="none")]
+
+
+def run_delete_task(client: GraphClient, task_id: str) -> None:
+    path = odata.p("planner", "tasks", task_id)
+    etag = (client.get(path) or {}).get("@odata.etag")
+    client.delete(path, headers={"If-Match": etag}, expect="none")

mgraphctl/graph/presence.py

@@ -0,0 +1,89 @@
+"""Graph operations for Teams presence (spec §8.9).
+
+Pure: client and parameters in, Graph dicts or a `Plan` out.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import timedelta
+
+from mgraphctl import odata
+from mgraphctl.errors import UsageError
+from mgraphctl.http import JSON_HEADERS, GraphClient, Plan, PlannedRequest
+from mgraphctl.render import iso_duration
+
+# The CLI state, and the `availability` / `activity` pair Graph wants for it.
+PRESENCE_PAIRS: dict[str, tuple[str, str]] = {
+    "available": ("Available", "Available"),
+    "busy": ("Busy", "Busy"),
+    "dnd": ("DoNotDisturb", "DoNotDisturb"),
+    "brb": ("BeRightBack", "BeRightBack"),
+    "away": ("Away", "Away"),
+    "offline": ("Offline", "OffWork"),
+}
+
+
+def resolve_pair(state: str) -> tuple[str, str]:
+    """The Graph availability/activity pair for a CLI state name."""
+    pair = PRESENCE_PAIRS.get(state.casefold())
+    if pair is None:
+        raise UsageError(
+            "USAGE", f"unknown presence {state!r}; use one of {', '.join(PRESENCE_PAIRS)}"
+        )
+    return pair
+
+
+def get_presence(client: GraphClient) -> dict:
+    return client.get("/me/presence")
+
+
+def get_presences(client: GraphClient, ids: Iterable[str]) -> list[dict]:
+    payload = client.post("/communications/getPresencesByUserId", json={"ids": list(ids)}) or {}
+    return payload.get("value") or []
+
+
+def _presence_base(client: GraphClient, my_oid: str) -> str:
+    """`/users/{oid}/presence`; the oid comes from the token, so there is no `/me` call."""
+    return client.url(odata.p("users", my_oid, "presence"))
+
+
+def plan_set(
+    client: GraphClient,
+    my_oid: str,
+    availability: str,
+    *,
+    expiration: timedelta,
+    message: str | None,
+) -> Plan:
+    state, activity = resolve_pair(availability)
+    base = _presence_base(client, my_oid)
+    steps = [
+        PlannedRequest(
+            "POST",
+            f"{base}/setUserPreferredPresence",
+            dict(JSON_HEADERS),
+            {
+                "availability": state,
+                "activity": activity,
+                "expirationDuration": iso_duration(expiration),
+            },
+            expect="none",
+        )
+    ]
+    if message is not None:
+        steps.append(
+            PlannedRequest(
+                "POST",
+                f"{base}/setStatusMessage",
+                dict(JSON_HEADERS),
+                {"statusMessage": {"message": {"content": message, "contentType": "text"}}},
+                expect="none",
+            )
+        )
+    return steps
+
+
+def plan_clear(client: GraphClient, my_oid: str) -> Plan:
+    base = _presence_base(client, my_oid)
+    return [PlannedRequest("POST", f"{base}/clearUserPreferredPresence", {}, None, expect="none")]