mgraphctl 0.1.0__py3-none-any.whl

mgraphctl/commands/people.py

@@ -0,0 +1,201 @@
+"""People, contacts and directory users (spec §8.5)."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from mgraphctl import auth
+from mgraphctl.cli import (
+    AllFlag,
+    JsonFlag,
+    LimitOpt,
+    gate,
+    graph_command,
+    make_noun_app,
+    page_bounds,
+)
+from mgraphctl.errors import AuthError
+from mgraphctl.graph import people
+from mgraphctl.graph import users as graph_users
+from mgraphctl.http import GraphClient
+from mgraphctl.render import Column, FileResult, ListResult, ObjectResult, fmt_size
+
+app = make_noun_app("People, contacts and directory users.")
+
+CONTACT_FIELDS = [
+    ("Name", "displayName"),
+    ("Email", lambda c: _first_email(c)),
+    ("Mobile", "mobilePhone"),
+    ("Business phones", lambda c: ", ".join(c.get("businessPhones") or [])),
+    ("Title", "jobTitle"),
+    ("Company", "companyName"),
+    ("Contact id", "id"),
+]
+
+USER_FIELDS = [
+    ("Name", "displayName"),
+    ("UPN", "userPrincipalName"),
+    ("Mail", "mail"),
+    ("Title", "jobTitle"),
+    ("Dept", "department"),
+    ("Office", "officeLocation"),
+    ("Phones", lambda u: ", ".join(u.get("businessPhones") or [])),
+    ("Mobile", "mobilePhone"),
+    ("User id", "id"),
+]
+
+
+def _first_scored_email(p: dict) -> str:
+    emails = p.get("scoredEmailAddresses") or []
+    return emails[0].get("address", "") if emails else ""
+
+
+def _first_email(c: dict) -> str:
+    emails = c.get("emailAddresses") or []
+    return emails[0].get("address", "") if emails else ""
+
+
+def _first_phone(c: dict) -> str:
+    phones = c.get("businessPhones") or []
+    return c.get("mobilePhone") or (phones[0] if phones else "")
+
+
+def _has_scope(scopes: list[str]) -> bool:
+    """Whether the current token already carries `scopes`, without failing the command."""
+    try:
+        gate(scopes)
+    except AuthError:
+        return False
+    return True
+
+
+@app.command("search")
+@graph_command(scopes=["People.Read"])
+def search(
+    client: GraphClient,
+    q: Annotated[str, typer.Argument(metavar="Q")],
+    limit: LimitOpt = None,
+    all_: AllFlag = False,
+    json_: JsonFlag = False,
+):
+    """Search people relevant to the signed-in user (`/me/people`)."""
+    limit, all_ = page_bounds(limit, all_, default=20)
+    page = people.search_people(client, q, limit=limit, all_=all_)
+    return ListResult(
+        items=page.items,
+        page=page,
+        hit_cap=people.CAP if all_ else None,
+        columns=[
+            Column("id", "id"),
+            Column("name", "displayName"),
+            Column("email", _first_scored_email),
+            Column("title", "jobTitle"),
+            Column("department", "department"),
+            Column("type", lambda p: (p.get("personType") or {}).get("class", "")),
+        ],
+    )
+
+
+@app.command("contacts")
+@graph_command(scopes=["Contacts.Read"])
+def contacts(
+    client: GraphClient,
+    search: Annotated[str | None, typer.Option("--search", help="Filter by name or email.")] = None,
+    limit: LimitOpt = None,
+    all_: AllFlag = False,
+    json_: JsonFlag = False,
+):
+    """List the signed-in user's contacts."""
+    limit, all_ = page_bounds(limit, all_, default=20)
+    page = people.list_contacts(client, search=search, limit=limit, all_=all_)
+    return ListResult(
+        items=page.items,
+        page=page,
+        hit_cap=people.CAP if all_ else None,
+        columns=[
+            Column("id", "id"),
+            Column("name", "displayName"),
+            Column("email", _first_email),
+            Column("phone", _first_phone),
+            Column("title", "jobTitle"),
+            Column("company", "companyName"),
+        ],
+    )
+
+
+@app.command("contact")
+@graph_command(scopes=["Contacts.Read"])
+def contact(
+    client: GraphClient,
+    contact_id: Annotated[str, typer.Argument(metavar="ID")],
+    json_: JsonFlag = False,
+):
+    """Show one contact."""
+    return ObjectResult(obj=people.get_contact(client, contact_id), fields=list(CONTACT_FIELDS))
+
+
+@app.command("users")
+@graph_command(scopes=["User.ReadBasic.All"])
+def users(
+    client: GraphClient,
+    q: Annotated[str, typer.Argument(metavar="Q")],
+    limit: LimitOpt = None,
+    all_: AllFlag = False,
+    json_: JsonFlag = False,
+):
+    """Search the directory for users (`/users`, tokenised `$search`)."""
+    limit, all_ = page_bounds(limit, all_, default=20)
+    page = graph_users.search_users(client, q, limit=limit, all_=all_)
+    return ListResult(
+        items=page.items,
+        page=page,
+        hit_cap=graph_users.CAP if all_ else None,
+        columns=[
+            Column("id", "id"),
+            Column("name", "displayName"),
+            Column("upn", "userPrincipalName"),
+            Column("mail", "mail"),
+            Column("title", "jobTitle"),
+            Column("department", "department"),
+        ],
+    )
+
+
+@app.command("user")
+@graph_command(scopes=["User.Read"])
+def user(
+    client: GraphClient,
+    ref: Annotated[str, typer.Argument(metavar="UPN|ID")],
+    json_: JsonFlag = False,
+):
+    """Look up one org user, by UPN, id, `me`, or (with User.ReadBasic.All) display name."""
+    can_search = _has_scope(["User.ReadBasic.All"])
+    obj = graph_users.resolve_user(client, ref, can_search=can_search)
+    return ObjectResult(obj=obj, fields=list(USER_FIELDS))
+
+
+@app.command("photo")
+@graph_command(scopes=["User.Read"])
+def photo(
+    client: GraphClient,
+    upn: Annotated[str | None, typer.Argument(metavar="UPN")] = None,
+    output: Annotated[Path | None, typer.Option("--output", help="Destination file.")] = None,
+    size: Annotated[str, typer.Option("--size", help="Photo size (others only).")] = "96x96",
+    json_: JsonFlag = False,
+):
+    """Download a profile photo (self by default)."""
+    if upn is not None:
+        gate(["User.ReadBasic.All"])
+        stem = upn
+    else:
+        claims = auth.decode_jwt(auth.get_access_token(False))
+        stem = claims.get("upn") or "me"
+    dest = output or Path(f"{stem}.jpg")
+    got = people.download_photo(client, upn, size, dest)
+    return FileResult(
+        path=got.path,
+        bytes=got.bytes,
+        meta=dict(contentType=got.content_type),
+        message=f"Downloaded photo ({fmt_size(got.bytes)}) to {got.path}",
+    )

mgraphctl/commands/planner.py

@@ -0,0 +1,268 @@
+"""Planner commands: plans, buckets, tasks (spec §8.14)."""
+
+from typing import Annotated, Literal
+
+import typer
+
+from mgraphctl.cli import DryRunFlag, JsonFlag, LimitOpt, graph_command, make_noun_app
+from mgraphctl.errors import UsageError
+from mgraphctl.graph import planner, users
+from mgraphctl.http import GraphClient
+from mgraphctl.render import (
+    Column,
+    DryRunResult,
+    ListResult,
+    ObjectResult,
+    WriteResult,
+    fmt_dt,
+    note,
+    parse_dt,
+)
+
+app = make_noun_app("Planner plans and tasks.")
+
+SCOPES = ["Tasks.ReadWrite"]
+SCOPES_PLANS = ["Tasks.ReadWrite", "Group.Read.All"]
+DEFAULT_LIMIT = 50
+
+PLAN_COLUMNS = [
+    Column("id", "id"),
+    Column("title", "title"),
+    Column("group", lambda p: p.get("_groupName") or ""),
+]
+BUCKET_COLUMNS = [Column("id", "id"), Column("name", "name")]
+
+
+def _task_columns(tz: str, *, my: bool) -> list[Column]:
+    columns = [
+        Column("id", "id"),
+        Column("%", lambda t: t.get("percentComplete", "")),
+        Column("priority", lambda t: t.get("priority", "")),
+        Column("due", lambda t: fmt_dt(t.get("dueDateTime"), tz)),
+    ]
+    if my:
+        columns.append(Column("plan", lambda t: t.get("_planTitle") or ""))
+    else:
+        columns.append(Column("bucket", lambda t: t.get("_bucketName") or ""))
+    columns.append(Column("title", "title"))
+    return columns
+
+
+def _assignee_oids(client: GraphClient, upns: list[str]) -> list[str]:
+    return [users.get_user(client, upn, select="id")["id"] for upn in upns]
+
+
+@app.command("plans")
+@graph_command(scopes=SCOPES_PLANS)
+def plans(
+    client: GraphClient,
+    limit: LimitOpt = None,
+    json_: JsonFlag = False,
+):
+    """List plans you own plus every plan of a Microsoft 365 group you belong to."""
+    eff_limit = limit if limit is not None else DEFAULT_LIMIT
+    page = planner.list_plans(client, limit=eff_limit, on_skip=note)
+    return ListResult(items=page.items, columns=PLAN_COLUMNS, page=page, supports_all=False)
+
+
+@app.command("plan")
+@graph_command(scopes=SCOPES)
+def plan(
+    client: GraphClient,
+    plan_ref: Annotated[str, typer.Argument(metavar="PLAN")],
+    json_: JsonFlag = False,
+):
+    """Show one plan, with its details."""
+    resolved = planner.resolve_plan(client, plan_ref)
+    obj = planner.get_plan(client, resolved["id"])
+    fields = [
+        ("Title", "title"),
+        ("Plan id", "id"),
+        ("Created", lambda o: fmt_dt(o.get("createdDateTime"), client.tz)),
+        ("Description", lambda o: (o.get("details") or {}).get("description") or ""),
+    ]
+    return ObjectResult(obj=obj, fields=fields)
+
+
+@app.command("buckets")
+@graph_command(scopes=SCOPES)
+def buckets(
+    client: GraphClient,
+    plan_ref: Annotated[str, typer.Argument(metavar="PLAN")],
+    json_: JsonFlag = False,
+):
+    """List the buckets of a plan."""
+    resolved = planner.resolve_plan(client, plan_ref)
+    items = planner.list_buckets(client, resolved["id"])
+    return ListResult(items=items, columns=BUCKET_COLUMNS)
+
+
+@app.command("tasks")
+@graph_command(scopes=SCOPES)
+def tasks(
+    client: GraphClient,
+    plan_ref: Annotated[str | None, typer.Argument(metavar="PLAN")] = None,
+    my: Annotated[bool, typer.Option("--my", help="Your tasks across every plan.")] = False,
+    bucket: Annotated[str | None, typer.Option("--bucket", help="Bucket name or id.")] = None,
+    include_completed: Annotated[bool, typer.Option("--include-completed")] = False,
+    limit: LimitOpt = None,
+    json_: JsonFlag = False,
+):
+    """List tasks in a plan, or your own tasks across every plan (--my)."""
+    eff_limit = limit if limit is not None else DEFAULT_LIMIT
+    if my:
+        page = planner.my_tasks(
+            client, include_completed=include_completed, limit=eff_limit, on_skip=note
+        )
+        return ListResult(
+            items=page.items,
+            columns=_task_columns(client.tz, my=True),
+            page=page,
+            supports_all=False,
+        )
+    if plan_ref is None:
+        raise UsageError("USAGE", "PLAN is required unless --my is given")
+    resolved = planner.resolve_plan(client, plan_ref)
+    bucket_id = None
+    if bucket is not None:
+        bucket_id = planner.resolve_bucket(client, resolved["id"], bucket)["id"]
+    page = planner.list_tasks(
+        client,
+        resolved["id"],
+        bucket_id=bucket_id,
+        include_completed=include_completed,
+        limit=eff_limit,
+    )
+    return ListResult(
+        items=page.items,
+        columns=_task_columns(client.tz, my=False),
+        page=page,
+        supports_all=False,
+    )
+
+
+@app.command("task")
+@graph_command(scopes=SCOPES)
+def task(
+    client: GraphClient,
+    task_id: Annotated[str, typer.Argument(metavar="ID")],
+    json_: JsonFlag = False,
+):
+    """Show one task, with its details."""
+    obj = planner.get_task(client, task_id)
+    fields = [
+        ("Title", "title"),
+        ("Plan id", "planId"),
+        ("Bucket id", "bucketId"),
+        ("%", "percentComplete"),
+        ("Priority", "priority"),
+        ("Due", lambda o: fmt_dt(o.get("dueDateTime"), client.tz)),
+        ("Description", lambda o: (o.get("details") or {}).get("description") or ""),
+    ]
+    return ObjectResult(obj=obj, fields=fields)
+
+
+@app.command("create")
+@graph_command(scopes=SCOPES)
+def create(
+    client: GraphClient,
+    plan_opt: Annotated[str, typer.Option("--plan", help="Plan name or id.")],
+    title: Annotated[str, typer.Option("--title")],
+    bucket: Annotated[str | None, typer.Option("--bucket", help="Bucket name or id.")] = None,
+    due: Annotated[str | None, typer.Option("--due")] = None,
+    assign: Annotated[
+        list[str] | None, typer.Option("--assign", help="Assignee UPN (repeatable).")
+    ] = None,
+    priority: Annotated[int | None, typer.Option("--priority", min=0, max=10)] = None,
+    description: Annotated[str | None, typer.Option("--description")] = None,
+    dry_run: DryRunFlag = False,
+    json_: JsonFlag = False,
+):
+    """Create a task."""
+    resolved_plan = planner.resolve_plan(client, plan_opt)
+    bucket_id = None
+    if bucket is not None:
+        bucket_id = planner.resolve_bucket(client, resolved_plan["id"], bucket)["id"]
+    due_dt = parse_dt(due, client.tz) if due is not None else None
+    oids = _assignee_oids(client, assign or [])
+    kwargs = dict(
+        plan_id=resolved_plan["id"],
+        bucket_id=bucket_id,
+        title=title,
+        due=due_dt,
+        assignee_oids=oids,
+        priority=priority,
+        description=description,
+    )
+    if dry_run:
+        return DryRunResult(planner.plan_create_task(client, **kwargs))
+    obj = planner.run_create_task(client, **kwargs)
+    return WriteResult(obj=obj, message=f"Created task {obj.get('id')}.")
+
+
+@app.command("update")
+@graph_command(scopes=SCOPES)
+def update(
+    client: GraphClient,
+    task_id: Annotated[str, typer.Argument(metavar="ID")],
+    title: Annotated[str | None, typer.Option("--title")] = None,
+    due: Annotated[str | None, typer.Option("--due")] = None,
+    percent: Annotated[
+        Literal[0, 50, 100] | None,
+        typer.Option("--percent", help="Completion; Graph accepts only these three values."),
+    ] = None,
+    bucket: Annotated[str | None, typer.Option("--bucket", help="Bucket name or id.")] = None,
+    priority: Annotated[int | None, typer.Option("--priority", min=0, max=10)] = None,
+    assign: Annotated[list[str] | None, typer.Option("--assign")] = None,
+    unassign: Annotated[list[str] | None, typer.Option("--unassign")] = None,
+    description: Annotated[str | None, typer.Option("--description")] = None,
+    dry_run: DryRunFlag = False,
+    json_: JsonFlag = False,
+):
+    """Update a task."""
+    due_dt = parse_dt(due, client.tz) if due is not None else None
+    bucket_id = planner.resolve_bucket_for_task(client, task_id, bucket)["id"] if bucket else None
+    kwargs = dict(
+        title=title,
+        due=due_dt,
+        percent=percent,
+        bucket_id=bucket_id,
+        priority=priority,
+        assign_oids=_assignee_oids(client, assign or []),
+        unassign_oids=_assignee_oids(client, unassign or []),
+        description=description,
+    )
+    if dry_run:
+        return DryRunResult(planner.plan_update_task(client, task_id, **kwargs))
+    obj = planner.run_update_task(client, task_id, **kwargs)
+    return WriteResult(obj=obj, message=f"Updated task {task_id}.")
+
+
+@app.command("complete")
+@graph_command(scopes=SCOPES)
+def complete(
+    client: GraphClient,
+    task_id: Annotated[str, typer.Argument(metavar="ID")],
+    dry_run: DryRunFlag = False,
+    json_: JsonFlag = False,
+):
+    """Mark a task complete (percent 100)."""
+    if dry_run:
+        return DryRunResult(planner.plan_update_task(client, task_id, percent=100))
+    obj = planner.run_update_task(client, task_id, percent=100)
+    return WriteResult(obj=obj, message=f"Completed task {task_id}.")
+
+
+@app.command("delete")
+@graph_command(scopes=SCOPES)
+def delete(
+    client: GraphClient,
+    task_id: Annotated[str, typer.Argument(metavar="ID")],
+    dry_run: DryRunFlag = False,
+    json_: JsonFlag = False,
+):
+    """Delete a task."""
+    if dry_run:
+        return DryRunResult(planner.plan_delete_task(client, task_id))
+    planner.run_delete_task(client, task_id)
+    return WriteResult(obj={"status": "deleted", "id": task_id}, message=f"Deleted task {task_id}.")

mgraphctl/commands/presence.py

@@ -0,0 +1,102 @@
+"""Teams presence commands (spec §8.9)."""
+
+from typing import Annotated
+
+import typer
+
+from mgraphctl import auth
+from mgraphctl.cli import DryRunFlag, JsonFlag, gate, graph_command, make_noun_app
+from mgraphctl.graph import presence as presence_api
+from mgraphctl.graph import users
+from mgraphctl.http import GraphClient
+from mgraphctl.render import (
+    Column,
+    DryRunResult,
+    ListResult,
+    ObjectResult,
+    WriteResult,
+    dig,
+    parse_duration,
+)
+
+OTHERS_SCOPES = ["Presence.Read.All"]
+STATES = ", ".join(presence_api.PRESENCE_PAIRS)
+
+app = make_noun_app("Teams presence.")
+
+
+@app.command("get")
+@graph_command(scopes=["Presence.Read"])
+def get(
+    client: GraphClient,
+    user: Annotated[
+        list[str] | None,
+        typer.Argument(metavar="[USER...]", help="UPNs or user ids; omit for yourself."),
+    ] = None,
+    json_: JsonFlag = False,
+):
+    """Show your presence, or that of the given users."""
+    if not user:
+        return ObjectResult(
+            obj=presence_api.get_presence(client),
+            fields=[
+                ("Availability", "availability"),
+                ("Activity", "activity"),
+                ("Status", lambda p: dig(p, "statusMessage.message.content")),
+                ("User id", "id"),
+            ],
+        )
+    gate(OTHERS_SCOPES)  # Reading anyone else needs the on-demand scope (spec §4.4).
+    people = [users.get_user(client, ref, select="id,displayName") for ref in user]
+    names = {p["id"]: p.get("displayName") for p in people}
+    return ListResult(
+        items=presence_api.get_presences(client, [p["id"] for p in people]),
+        empty_text="No presence information.",
+        columns=[
+            Column("id", "id"),
+            Column("name", lambda p: names.get(p.get("id"), "")),
+            Column("availability", "availability"),
+            Column("activity", "activity"),
+        ],
+    )
+
+
+@app.command("set")
+@graph_command(scopes=["Presence.ReadWrite"])
+def set_(
+    client: GraphClient,
+    state: Annotated[str, typer.Argument(metavar="STATE", help=f"One of {STATES}.")],
+    expiration: Annotated[
+        str, typer.Option("--expiration", help="How long it lasts (30m, 2h, PT1H).")
+    ] = "1h",
+    message: Annotated[
+        str | None, typer.Option("--message", help="Status message to show alongside it.")
+    ] = None,
+    dry_run: DryRunFlag = False,
+    json_: JsonFlag = False,
+):
+    """Set your preferred presence."""
+    availability, _ = presence_api.resolve_pair(state)
+    plan = presence_api.plan_set(
+        client,
+        auth.my_oid(),
+        state,
+        expiration=parse_duration(expiration),
+        message=message,
+    )
+    if dry_run:
+        return DryRunResult(plan)
+    for step in plan:
+        client.execute(step)
+    return WriteResult(obj=None, message=f"Presence set to {availability}.")
+
+
+@app.command("clear")
+@graph_command(scopes=["Presence.ReadWrite"])
+def clear(client: GraphClient, dry_run: DryRunFlag = False, json_: JsonFlag = False):
+    """Clear your preferred presence, handing it back to Teams."""
+    plan = presence_api.plan_clear(client, auth.my_oid())
+    if dry_run:
+        return DryRunResult(plan)
+    client.execute(plan[0])
+    return WriteResult(obj=None, message="Preferred presence cleared.")

mgraphctl/commands/search.py

@@ -0,0 +1,75 @@
+"""Unified search across Microsoft 365 (spec §8.17). Registered as a top-level command."""
+
+from typing import Annotated
+
+import typer
+
+from mgraphctl.cli import AllFlag, JsonFlag, LimitOpt, gate, graph_command, page_bounds
+from mgraphctl.graph import search as search_ops
+from mgraphctl.http import GraphClient
+from mgraphctl.render import (
+    ListResult,
+    Window,
+    parse_dt,
+)
+
+
+def _split_fields(value: str | None) -> list[str] | None:
+    if value is None:
+        return None
+    fields = [f.strip() for f in value.split(",") if f.strip()]
+    return fields or None
+
+
+@graph_command(scopes=[])  # the scope depends on --type; gated at runtime below (spec §8.17)
+def command(
+    client: GraphClient,
+    q: Annotated[str, typer.Argument(metavar="Q", help="What to search for.")],
+    type_: Annotated[
+        str,
+        typer.Option(
+            "--type", help="message, event, driveItem, site, list, chatMessage, or person."
+        ),
+    ] = "message",
+    after: Annotated[
+        str | None, typer.Option("--after", metavar="DT", help="Only hits after this time.")
+    ] = None,
+    before: Annotated[
+        str | None, typer.Option("--before", metavar="DT", help="Only hits before this time.")
+    ] = None,
+    limit: LimitOpt = None,
+    all_: AllFlag = False,
+    fields: Annotated[
+        str | None, typer.Option("--fields", help="Comma-separated Graph fields to fetch.")
+    ] = None,
+    json_: JsonFlag = False,
+):
+    """Search mail, calendar, files, sites, chats or people with the Microsoft Search API."""
+    entity_type = search_ops.normalise_entity_type(type_)
+    gate(search_ops.SCOPES_BY_TYPE[entity_type])
+    limit, all_ = page_bounds(limit, all_, default=search_ops.DEFAULT_LIMIT)
+    tz = client.tz
+    after_dt = parse_dt(after, tz) if after else None
+    before_dt = parse_dt(before, tz, end_of_day=True) if before else None
+    found = search_ops.search(
+        client,
+        entity_type=entity_type,
+        q=q,
+        after=after_dt,
+        before=before_dt,
+        limit=limit,
+        all_=all_,
+        fields=_split_fields(fields),
+        tz=tz,
+    )
+    return ListResult(
+        items=[search_ops.shape_hit(entity_type, hit) for hit in found.hits],
+        truncated=found.more,
+        fetched=found.fetched_count,
+        cap=found.cap,
+        query=found.query,
+        window=Window(after=after_dt, before=before_dt),
+        hit_cap=search_ops.CAP_SEARCH if all_ else None,
+        empty_text="No results.",
+        columns=search_ops.columns_for(entity_type, tz),
+    )