mgraphctl 0.1.0__py3-none-any.whl

mgraphctl/graph/mailbox.py

@@ -0,0 +1,89 @@
+"""Graph operations for mailbox settings, automatic replies and the focused inbox (spec §8.3).
+
+Pure: client and parameters in, Graph dicts / `PageResult` / `Plan` out.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from mgraphctl.graph import mail
+from mgraphctl.html import text_to_html
+from mgraphctl.http import JSON_HEADERS, GraphClient, PageResult, Plan, PlannedRequest
+from mgraphctl.render import to_graph_dtz
+
+SETTINGS_PATH = "/me/mailboxSettings"
+OOF_PATH = "/me/mailboxSettings/automaticRepliesSetting"
+FOCUSED_PATH = "/me/mailFolders/inbox/messages"
+
+# `--external` values → the Graph `externalAudience` enum (spec §8.3 `oof set`).
+AUDIENCE = {"all": "all", "contacts": "contactsOnly", "none": "none"}
+
+
+def get_settings(client: GraphClient) -> dict:
+    return client.get(SETTINGS_PATH)
+
+
+def get_oof(client: GraphClient) -> dict:
+    return client.get(OOF_PATH)
+
+
+def plan_set_oof(
+    client: GraphClient,
+    *,
+    message: str | None,
+    external_message: str | None,
+    start: datetime | None,
+    end: datetime | None,
+    audience: str,
+    clear: bool,
+    tz: str,
+) -> Plan:
+    """`scheduled` when both ends are given, `alwaysEnabled` otherwise, `disabled` for --clear."""
+    if clear:
+        setting: dict[str, object] = {"status": "disabled"}
+    else:
+        setting = {
+            "status": "scheduled" if start and end else "alwaysEnabled",
+            "externalAudience": audience,
+        }
+        if start and end:
+            setting["scheduledStartDateTime"] = to_graph_dtz(start, tz)
+            setting["scheduledEndDateTime"] = to_graph_dtz(end, tz)
+        setting["internalReplyMessage"] = text_to_html(message or "")
+        setting["externalReplyMessage"] = text_to_html(external_message or message or "")
+    return [
+        PlannedRequest(
+            "PATCH",
+            client.url(SETTINGS_PATH),
+            dict(JSON_HEADERS),
+            {"automaticRepliesSetting": setting},
+        )
+    ]
+
+
+def list_focused(
+    client: GraphClient, *, other: bool, after: datetime, limit: int | None, all_: bool
+) -> PageResult:
+    """Inbox messages Outlook classified as focused (or `--other`), newest first.
+
+    `receivedDateTime` leads the filter so Graph can serve the `$orderby` from the same index.
+    """
+    classification = "other" if other else "focused"
+    params = {
+        "$select": mail.LIST_SELECT,
+        "$filter": (
+            f"receivedDateTime ge {after.isoformat()} "
+            f"and inferenceClassification eq '{classification}'"
+        ),
+        "$orderby": "receivedDateTime desc",
+    }
+    return client.paginate(
+        FOCUSED_PATH,
+        params=params,
+        outlook_tz=True,
+        limit=limit,
+        all_=all_,
+        cap=mail.CAP_LIST,
+        page_size=mail.PAGE_FILTER,
+    )

mgraphctl/graph/meetings.py

@@ -0,0 +1,269 @@
+"""Graph operations for online meetings, transcripts and AI insights (spec §8.10).
+
+Pure: client and parameters in, Graph dicts / lists out. `meetings list` resolves its own
+calendar window (its own `$select`, no import of `graph/calendar` — that module is owned by
+a different task and this one must not depend on it).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from mgraphctl import odata
+from mgraphctl.errors import GraphError, MsgraphError, NotFoundError, UsageError
+from mgraphctl.http import BatchRequest, DownloadResult, GraphClient, PageResult
+from mgraphctl.render import to_iso_offset
+
+EVENT_SELECT = "id,subject,start,end,organizer,isOnlineMeeting,onlineMeeting"
+PAGE_SIZE = 50
+CAP = 200
+
+TRANSCRIPT_TEXT_ACCEPT = "application/vnd.microsoft.graph.transcript+text"
+
+NO_LICENSE_NOTE = (
+    "AI insights require a Microsoft 365 Copilot license, or this meeting is not eligible."
+)
+NO_INSIGHTS_NOTE = "No AI insights are available for this meeting."
+
+
+def list_online_events(
+    client: GraphClient,
+    *,
+    start: datetime,
+    end: datetime,
+    subject: str | None,
+    limit: int,
+    tz: str,
+) -> PageResult:
+    """Calendar events in `[start, end]` that are online meetings with a join URL.
+
+    `truncated` (and `pages`) are threaded through from the underlying `calendarView`
+    pagination unchanged: filtering to online meetings (and by `--subject`) only ever removes
+    items, so a page that was truncated before filtering still means "there may be more".
+    """
+    params = {
+        "startDateTime": to_iso_offset(start),
+        "endDateTime": to_iso_offset(end),
+        "$select": EVENT_SELECT,
+    }
+    page = client.paginate(
+        "/me/calendarView",
+        params=params,
+        outlook_tz=True,
+        limit=limit,
+        all_=False,
+        cap=CAP,
+        page_size=PAGE_SIZE,
+    )
+    events = [
+        e
+        for e in page.items
+        if e.get("isOnlineMeeting") and (e.get("onlineMeeting") or {}).get("joinUrl")
+    ]
+    if subject:
+        needle = subject.casefold()
+        events = [e for e in events if needle in (e.get("subject") or "").casefold()]
+    return PageResult(items=events, truncated=page.truncated, pages=page.pages)
+
+
+def resolve_meetings(client: GraphClient, events: list[dict]) -> dict[str, dict]:
+    """`$batch` of one `onlineMeetings` join-URL filter per event; keyed by event id."""
+    targets = [e for e in events if (e.get("onlineMeeting") or {}).get("joinUrl")]
+    if not targets:
+        return {}
+    requests = [
+        BatchRequest(
+            id=event["id"],
+            method="GET",
+            url=odata.with_query(
+                "/me/onlineMeetings",
+                {"$filter": _join_url_filter(event["onlineMeeting"]["joinUrl"])},
+            ),
+        )
+        for event in targets
+    ]
+    resolved: dict[str, dict] = {}
+    for response in client.batch(requests):
+        if response.error is not None:
+            continue
+        values = (response.body or {}).get("value") or []
+        if values:
+            resolved[response.id] = values[0]
+    return resolved
+
+
+def transcripts_for(client: GraphClient, meeting_ids: list[str]) -> dict[str, list]:
+    """`GET /me/onlineMeetings/{id}/transcripts` for each meeting id, one call per id."""
+    result: dict[str, list] = {}
+    for meeting_id in meeting_ids:
+        if meeting_id in result:
+            continue
+        page = client.get(odata.p("me", "onlineMeetings", meeting_id, "transcripts"))
+        result[meeting_id] = (page or {}).get("value") or []
+    return result
+
+
+def _join_url_filter(join_url: str) -> str:
+    return f"JoinWebUrl eq '{odata.odata_str(join_url)}'"
+
+
+def _by_join_url(client: GraphClient, join_url: str) -> dict:
+    result = client.get("/me/onlineMeetings", params={"$filter": _join_url_filter(join_url)})
+    values = (result or {}).get("value") or []
+    if not values:
+        raise NotFoundError("NOT_FOUND", f"no online meeting found for join URL {join_url!r}")
+    return values[0]
+
+
+def select_meeting(
+    client: GraphClient, meeting: str | None, join_url: str | None, event: str | None
+) -> dict:
+    """Resolve exactly one of MEETING / `--join-url` / `--event` to a meeting dict (spec §6.6).
+
+    A bare `MEETING` id costs no request (`{"id": meeting}`); `--join-url` and `--event` both
+    end in the `$filter` lookup, which already returns the full record.
+    """
+    given = [v for v in (meeting, join_url, event) if v is not None]
+    if len(given) != 1:
+        raise UsageError("USAGE", "give exactly one of MEETING, --join-url, or --event")
+    if meeting is not None:
+        return {"id": meeting}
+    if event is not None:
+        ev = client.get(odata.p("me", "events", event), params={"$select": "onlineMeeting"})
+        join_url = (ev.get("onlineMeeting") or {}).get("joinUrl")
+        if not join_url:
+            raise NotFoundError("NOT_FOUND", f"event {event!r} has no online meeting")
+    return _by_join_url(client, join_url)
+
+
+def get_meeting(
+    client: GraphClient,
+    meeting: str | None = None,
+    *,
+    join_url: str | None = None,
+    event: str | None = None,
+) -> dict:
+    """The full online meeting record, however it was selected (`meetings get`, spec §8.10).
+
+    `select_meeting` costs no request for a bare id (it hands back `{"id": meeting}` so the
+    cheaper verbs never over-fetch); `get` always wants the full record, so a bare id gets one
+    extra `GET /me/onlineMeetings/{id}` here. `--join-url` and `--event` already resolve
+    through the `$filter` lookup, which returns the full record, so no second call is needed.
+    """
+    selected = select_meeting(client, meeting, join_url, event)
+    if meeting is not None:
+        return client.get(odata.p("me", "onlineMeetings", selected["id"]))
+    return selected
+
+
+def list_transcripts(client: GraphClient, meeting_id: str) -> list[dict]:
+    result = client.get(odata.p("me", "onlineMeetings", meeting_id, "transcripts"))
+    return (result or {}).get("value") or []
+
+
+def looks_like_vtt(body: str) -> bool:
+    """Whether a transcript body is WebVTT, which its required signature line says (§8.11).
+
+    What Graph returns does not always follow what was asked for: `$format=text/vtt` can come
+    back as plain text on the speaker-attribution fallback, and some meeting types answer with
+    vtt regardless. The body itself is the only honest source.
+    """
+    return body.lstrip("\ufeff").lstrip().startswith("WEBVTT")
+
+
+def get_transcript_body(client: GraphClient, meeting_id: str, transcript_id: str) -> str:
+    """The transcript exactly as Graph returned it — WebVTT, or plain text on the fallback.
+
+    A 403 `SpeakerAttributionNotAllowed` is retried once with an `Accept` header that asks
+    Graph for the plain-text representation directly (already speaker-scrubbed). That fallback
+    has no WebVTT form, so it always yields plain text; the caller sniffs the body with
+    `looks_like_vtt` rather than assuming it got what it asked for.
+    """
+    path = odata.p("me", "onlineMeetings", meeting_id, "transcripts", transcript_id, "content")
+    try:
+        return client.request("GET", path, params={"$format": "text/vtt"}, expect="text")
+    except GraphError as exc:
+        if exc.status == 403 and exc.code == "SpeakerAttributionNotAllowed":
+            return client.request(
+                "GET", path, headers={"Accept": TRANSCRIPT_TEXT_ACCEPT}, expect="text"
+            )
+        raise
+
+
+def transcript_created_at(client: GraphClient, meeting_id: str, transcript_id: str) -> str | None:
+    """Best-effort `createdDateTime` for one transcript, or None when the lookup fails.
+
+    Costs one extra list request, so only the `--json` path — the only one that emits the
+    field — pays it. The content fetch has already succeeded by this point, so a failure here
+    is never fatal.
+    """
+    try:
+        listed = list_transcripts(client, meeting_id)
+    except (MsgraphError, ValueError):  # ValueError covers a 200 carrying unparseable JSON
+        return None
+    for item in listed:
+        if item.get("id") == transcript_id:
+            return item.get("createdDateTime")
+    return None
+
+
+def insights(client: GraphClient, oid: str, meeting_id: str) -> tuple[list[dict], str | None]:
+    """AI insights: v1.0 first, `/beta` on 404; per-item detail from whichever base answered.
+
+    A 403 at either stage becomes a soft "needs a Copilot license" note, not an error; a
+    per-item detail failure keeps the summary list entry instead of dropping it. The summary
+    call passes no explicit `beta=`, so it honours the client's global `--beta` flag like any
+    other call; `beta` here tracks whichever base actually answered (the client's own setting
+    when the first call succeeded, or `True` when the 404 fallback to `/beta` was needed) so
+    the per-item detail GETs land on the same base as the summary that named them.
+    """
+    path = odata.p("copilot", "users", oid, "onlineMeetings", meeting_id, "aiInsights")
+    try:
+        summary = client.get(path)
+        beta = client.beta
+    except GraphError as exc:
+        if exc.status == 403:
+            return [], NO_LICENSE_NOTE
+        if exc.status != 404:
+            raise
+        try:
+            summary = client.get(path, beta=True)
+            beta = True
+        except GraphError as exc2:
+            if exc2.status == 403:
+                return [], NO_LICENSE_NOTE
+            if exc2.status == 404:
+                return [], NO_INSIGHTS_NOTE
+            raise
+    items = (summary or {}).get("value") or []
+    if not items:
+        return [], NO_INSIGHTS_NOTE
+    detailed: list[dict] = []
+    for item in items:
+        detail_path = odata.p(
+            "copilot",
+            "users",
+            oid,
+            "onlineMeetings",
+            meeting_id,
+            "aiInsights",
+            str(item.get("id")),
+        )
+        try:
+            detailed.append(client.get(detail_path, beta=beta))
+        except GraphError:
+            detailed.append(item)
+    return detailed, None
+
+
+def list_recordings(client: GraphClient, meeting_id: str) -> list[dict]:
+    result = client.get(odata.p("me", "onlineMeetings", meeting_id, "recordings"))
+    return (result or {}).get("value") or []
+
+
+def download_recording(
+    client: GraphClient, meeting_id: str, recording_id: str, dest: Path
+) -> DownloadResult:
+    path = odata.p("me", "onlineMeetings", meeting_id, "recordings", recording_id, "content")
+    return client.download(path, dest)

mgraphctl/graph/onedrive.py

@@ -0,0 +1,35 @@
+"""OneDrive-only Graph operations (spec §8.11): base resolution for `--drive`, plus the two
+listings that are always relative to the signed-in user's own drive (`sharedWithMe`, `recent`).
+
+Every other onedrive verb delegates straight to `mgraphctl.graph.files` with a `base` resolved
+by `base_for()` here; that module already implements every drive-item operation.
+"""
+
+from __future__ import annotations
+
+from mgraphctl import odata
+from mgraphctl.http import GraphClient, PageResult
+
+CAP_SHARED_WITH_ME = 200
+CAP_RECENT = 200
+
+
+def base_for(drive_id: str | None) -> str:
+    """`/me/drive`, or `/drives/{id}` when `--drive` names another drive."""
+    if drive_id is None:
+        return "/me/drive"
+    return odata.p("drives", drive_id)
+
+
+def shared_with_me(client: GraphClient, *, limit: int) -> PageResult:
+    """Items other people have shared (§8.11 `shared-with-me`); always the caller's own drive."""
+    return client.paginate(
+        "/me/drive/sharedWithMe", limit=limit, all_=False, cap=CAP_SHARED_WITH_ME, page_size=None
+    )
+
+
+def recent(client: GraphClient, *, limit: int) -> PageResult:
+    """Recently used files (§8.11 `recent`); always the caller's own drive."""
+    return client.paginate(
+        "/me/drive/recent", limit=limit, all_=False, cap=CAP_RECENT, page_size=None
+    )

mgraphctl/graph/onenote.py

@@ -0,0 +1,138 @@
+"""Graph operations for OneNote notebooks, sections and pages (spec §8.13).
+
+Pure: client and parameters in, Graph dicts / PageResult / Plan out.
+"""
+
+from __future__ import annotations
+
+from html import escape as escape_html
+
+from mgraphctl.errors import GraphError
+from mgraphctl.html import text_to_html
+from mgraphctl.http import GraphClient, PageResult, Plan, PlannedRequest
+from mgraphctl.odata import p
+from mgraphctl.resolve import looks_like_id, pick_unique, split_id_prefix
+
+NOTEBOOK_SELECT = "id,displayName,lastModifiedDateTime,links"
+SECTION_SELECT = "id,displayName,lastModifiedDateTime,parentNotebook"
+PAGE_SELECT = "id,title,lastModifiedDateTime,links"
+SEARCH_SELECT = "id,title,createdDateTime,parentSection"
+HTML_CONTENT = {"Content-Type": "text/html"}
+
+PAGE_TOP = 100
+CAP_LIST = 500
+
+
+def list_notebooks(client: GraphClient, *, limit: int, all_: bool = False) -> PageResult:
+    return client.paginate(
+        "/me/onenote/notebooks",
+        params={"$select": NOTEBOOK_SELECT},
+        limit=limit,
+        all_=all_,
+        cap=CAP_LIST,
+        page_size=PAGE_TOP,
+    )
+
+
+def resolve_notebook(client: GraphClient, value: str) -> str:
+    """A notebook id, or the id of the notebook whose `displayName` matches `value` (§6.6)."""
+    bare, forced = split_id_prefix(value)
+    if looks_like_id(value, "onenote"):
+        return bare
+    payload = client.get("/me/onenote/notebooks", params={"$top": PAGE_TOP}) or {}
+    match = pick_unique(payload.get("value") or [], "displayName", value, what="notebook")
+    return match["id"]
+
+
+def list_sections(
+    client: GraphClient, notebook_id: str | None, *, limit: int, all_: bool = False
+) -> PageResult:
+    path = (
+        "/me/onenote/sections"
+        if notebook_id is None
+        else p("me", "onenote", "notebooks", notebook_id, "sections")
+    )
+    return client.paginate(
+        path,
+        params={"$select": SECTION_SELECT},
+        limit=limit,
+        all_=all_,
+        cap=CAP_LIST,
+        page_size=PAGE_TOP,
+    )
+
+
+def resolve_section(client: GraphClient, value: str) -> str:
+    """A section id, or the id of the section whose `displayName` matches `value` (§6.6)."""
+    bare, forced = split_id_prefix(value)
+    if looks_like_id(value, "onenote"):
+        return bare
+    payload = client.get("/me/onenote/sections", params={"$top": PAGE_TOP}) or {}
+    match = pick_unique(payload.get("value") or [], "displayName", value, what="section")
+    return match["id"]
+
+
+def list_pages(client: GraphClient, section_id: str, *, limit: int, all_: bool) -> PageResult:
+    path = p("me", "onenote", "sections", section_id, "pages")
+    return client.paginate(
+        path,
+        params={"$select": PAGE_SELECT, "$orderby": "lastModifiedDateTime desc"},
+        limit=limit,
+        all_=all_,
+        cap=CAP_LIST,
+        page_size=PAGE_TOP,
+    )
+
+
+def resolve_page(client: GraphClient, value: str) -> str:
+    """A page id, or the id of the page whose `title` matches `value` (§6.6)."""
+    bare, forced = split_id_prefix(value)
+    if looks_like_id(value, "onenote"):
+        return bare
+    payload = client.get("/me/onenote/pages", params={"$top": PAGE_TOP}) or {}
+    match = pick_unique(payload.get("value") or [], "title", value, what="page")
+    return match["id"]
+
+
+def get_page(client: GraphClient, page_id: str) -> tuple[dict, str]:
+    """A page's metadata and its HTML content (two Graph calls; §8.13 `read`)."""
+    meta = client.get(p("me", "onenote", "pages", page_id), params={"$select": PAGE_SELECT})
+    content = client.get(
+        p("me", "onenote", "pages", page_id, "content"),
+        params={"includeIDs": True},
+        expect="text",
+    )
+    return meta, content
+
+
+def plan_create_page(
+    client: GraphClient, section_id: str, *, title: str, body: str, html: bool
+) -> Plan:
+    """`POST .../pages` with an HTML string body.
+
+    Title is always escaped; body is escaped and paragraph-wrapped unless `html` (quirk 14).
+    """
+    content = body if html else text_to_html(body)
+    page_html = (
+        f"<!DOCTYPE html><html><head><title>{escape_html(title)}</title></head>"
+        f"<body>{content}</body></html>"
+    )
+    url = client.url(p("me", "onenote", "sections", section_id, "pages"))
+    return [PlannedRequest("POST", url, dict(HTML_CONTENT), page_html)]
+
+
+def search_pages(client: GraphClient, q: str, *, limit: int) -> PageResult:
+    """`$search` over page titles/content; Graph only supports this for consumer notebooks."""
+    try:
+        return client.paginate(
+            "/me/onenote/pages",
+            params={"$search": q, "$select": SEARCH_SELECT},
+            limit=limit,
+            all_=False,
+            cap=CAP_LIST,
+            page_size=PAGE_TOP,
+        )
+    except GraphError as exc:
+        if exc.status in (400, 501):
+            exc.hint = f"search {q} --type driveItem"
+        raise

mgraphctl/graph/org.py

@@ -0,0 +1,86 @@
+"""Graph operations for manager, direct reports and the management chain (spec §8.6).
+
+Pure: client and parameters in, Graph dicts / PageResult / list[dict] out.
+"""
+
+from __future__ import annotations
+
+from mgraphctl import odata
+from mgraphctl.errors import GraphError, NotFoundError
+from mgraphctl.http import GraphClient, PageResult
+
+MANAGER_SELECT = "id,displayName,userPrincipalName,mail,jobTitle,department"
+CHAIN_SELECT = "id,displayName,userPrincipalName,jobTitle"
+EVENTUAL = {"ConsistencyLevel": "eventual"}
+
+PAGE = 100
+CAP = 500
+
+
+def _user_path(upn: str | None) -> str:
+    return "/me" if upn is None else odata.p("users", upn)
+
+
+def manager(client: GraphClient, upn: str | None) -> dict:
+    """The user's manager (self by default). 404 becomes a clear NOT_FOUND (spec §8.6)."""
+    try:
+        return client.get(f"{_user_path(upn)}/manager", params={"$select": MANAGER_SELECT})
+    except GraphError as exc:
+        if exc.status != 404:
+            raise
+        raise NotFoundError("NOT_FOUND", "No manager found", request_id=exc.request_id) from exc
+
+
+def reports(client: GraphClient, upn: str | None, *, limit: int, all_: bool) -> PageResult:
+    """The user's direct reports (self by default)."""
+    path = f"{_user_path(upn)}/directReports"
+    return client.paginate(
+        path, params={"$select": MANAGER_SELECT}, limit=limit, all_=all_, cap=CAP, page_size=PAGE
+    )
+
+
+def _walk_expanded(obj: dict) -> list[dict]:
+    """Self, then each nested `manager`, flattened from the `$expand` response."""
+    levels = []
+    current: dict | None = obj
+    while current is not None:
+        levels.append({k: v for k, v in current.items() if k != "manager"})
+        current = current.get("manager")
+    return levels
+
+
+def chain_expand(client: GraphClient, upn: str | None, *, max_levels: int) -> list[dict]:
+    """The management chain via one `$expand=manager($levels=max)` call (spec §8.6 `chain`).
+
+    Self, then each nested `manager`, from the single response. Raises `GraphError` (400/403
+    on a tenant that rejects the expand) for the caller to catch and fall back to
+    `chain_iterative`.
+    """
+    path = _user_path(upn)
+    expand = f"manager($levels=max;$select={CHAIN_SELECT})"
+    obj = client.get(path, params={"$expand": expand, "$count": True}, headers=EVENTUAL)
+    return _walk_expanded(obj)[: max_levels + 1]
+
+
+def chain_iterative(client: GraphClient, upn: str | None, *, max_levels: int) -> list[dict]:
+    """The management chain via a `/users/{id}/manager` walk, one level at a time.
+
+    The fallback path for tenants that reject `$expand`; callers gate this on
+    `User.Read.All` before calling it (spec §8.6, §4.4 — the branch-level gate lives in the
+    command layer, not here).
+    """
+    start = client.get(_user_path(upn), params={"$select": CHAIN_SELECT})
+    levels = [start]
+    current_id = start.get("id")
+    while current_id and len(levels) <= max_levels:
+        try:
+            nxt = client.get(
+                f"{odata.p('users', current_id)}/manager", params={"$select": CHAIN_SELECT}
+            )
+        except GraphError as exc:
+            if exc.status == 404:
+                break
+            raise
+        levels.append(nxt)
+        current_id = nxt.get("id")
+    return levels