mgraphctl 0.1.0__py3-none-any.whl

mgraphctl/commands/mailbox.py

@@ -0,0 +1,176 @@
+"""Mailbox settings, automatic replies and the focused inbox (spec §8.3)."""
+
+from typing import Annotated
+
+import typer
+
+from mgraphctl.cli import (
+    AllFlag,
+    DryRunFlag,
+    JsonFlag,
+    LimitOpt,
+    graph_command,
+    make_noun_app,
+    page_bounds,
+)
+from mgraphctl.errors import UsageError
+from mgraphctl.graph import mail, mailbox
+from mgraphctl.html import to_markdown
+from mgraphctl.http import GraphClient
+from mgraphctl.render import (
+    DryRunResult,
+    ListResult,
+    ObjectResult,
+    Window,
+    WriteResult,
+    fmt_dtz,
+    parse_dt,
+)
+
+app = make_noun_app("Mailbox settings, automatic replies, focused inbox.")
+oof = make_noun_app("Automatic replies (out of office).")
+app.add_typer(oof, name="oof")
+
+
+def _working_hours(settings: dict) -> str:
+    """`Mon,Tue,Wed,Thu,Fri 08:00-17:00 (Europe/Warsaw)`, or "" when Graph sent nothing."""
+    hours = settings.get("workingHours") or {}
+    days = hours.get("daysOfWeek") or []
+    if not days:
+        return ""
+    zone = (hours.get("timeZone") or {}).get("name") or ""
+    labels = ",".join(str(day)[:3].capitalize() for day in days)
+    start = str(hours.get("startTime") or "")[:5]
+    end = str(hours.get("endTime") or "")[:5]
+    return f"{labels} {start}-{end} ({zone})"
+
+
+OOF_MESSAGES = (
+    ("Internal reply", "internalReplyMessage"),
+    ("External reply", "externalReplyMessage"),
+)
+
+
+def _oof_body(setting: dict) -> str | None:
+    """The reply messages as text, one labelled block each."""
+    blocks = [
+        f"{label}\n{to_markdown(setting[key], 'mail')}"
+        for label, key in OOF_MESSAGES
+        if setting.get(key)
+    ]
+    return "\n\n".join(blocks) if blocks else None
+
+
+@app.command("settings")
+@graph_command(scopes=["MailboxSettings.Read"])
+def settings(client: GraphClient, json_: JsonFlag = False):
+    """Show the mailbox's time zone, language, working hours and reply status."""
+    obj = mailbox.get_settings(client)
+    return ObjectResult(
+        obj=obj,
+        fields=[
+            ("Time zone", "timeZone"),
+            ("Language", "language.displayName"),
+            ("Working hours", _working_hours),
+            ("Automatic replies", "automaticRepliesSetting.status"),
+            ("Date format", "dateFormat"),
+            ("Time format", "timeFormat"),
+        ],
+    )
+
+
+@oof.command("get")
+@graph_command(scopes=["MailboxSettings.Read"])
+def oof_get(client: GraphClient, json_: JsonFlag = False):
+    """Show the automatic replies setting."""
+    setting = mailbox.get_oof(client)
+    tz = client.tz
+    return ObjectResult(
+        obj=setting,
+        fields=[
+            ("Status", "status"),
+            ("External audience", "externalAudience"),
+            ("Start", lambda s: fmt_dtz(s.get("scheduledStartDateTime"), tz)),
+            ("End", lambda s: fmt_dtz(s.get("scheduledEndDateTime"), tz)),
+        ],
+        body=_oof_body(setting),
+    )
+
+
+@oof.command("set")
+@graph_command(scopes=["MailboxSettings.ReadWrite"])
+def oof_set(
+    client: GraphClient,
+    message: Annotated[str | None, typer.Option("--message", help="Internal reply text.")] = None,
+    external_message: Annotated[
+        str | None, typer.Option("--external-message", help="External reply (default: --message).")
+    ] = None,
+    start: Annotated[str | None, typer.Option("--start", help="Start of the period.")] = None,
+    end: Annotated[str | None, typer.Option("--end", help="End of the period.")] = None,
+    external: Annotated[
+        str | None,
+        typer.Option("--external", help="Who outside sees a reply: all, contacts, none."),
+    ] = None,
+    internal_only: Annotated[
+        bool, typer.Option("--internal-only", help="Same as --external none.")
+    ] = False,
+    clear: Annotated[bool, typer.Option("--clear", help="Turn automatic replies off.")] = False,
+    dry_run: DryRunFlag = False,
+    json_: JsonFlag = False,
+):
+    """Turn automatic replies on (always or for a period) or off."""
+    tz = client.tz
+    if not clear and not message:
+        raise UsageError("USAGE", "--message is required unless --clear is given")
+    if (start is None) != (end is None):
+        raise UsageError("USAGE", "--start and --end go together; give both or neither")
+    if external is not None and external not in mailbox.AUDIENCE:
+        raise UsageError(
+            "USAGE",
+            f"--external must be one of {', '.join(mailbox.AUDIENCE)} (got {external!r})",
+        )
+    if internal_only and external not in (None, "none"):
+        raise UsageError("USAGE", "--internal-only and --external are mutually exclusive")
+    audience = "none" if internal_only else mailbox.AUDIENCE[external or "all"]
+    plan = mailbox.plan_set_oof(
+        client,
+        message=message,
+        external_message=external_message,
+        start=parse_dt(start, tz) if start else None,
+        end=parse_dt(end, tz, end_of_day=True) if end else None,
+        audience=audience,
+        clear=clear,
+        tz=tz,
+    )
+    if dry_run:
+        return DryRunResult(plan)
+    updated = mail.run_plan(client, plan)[0]
+    return WriteResult(obj=updated, message="Automatic replies updated.")
+
+
+@app.command("focused")
+@graph_command(scopes=["Mail.Read"])
+def focused(
+    client: GraphClient,
+    other: Annotated[
+        bool, typer.Option("--other", help="Show the Other inbox instead of Focused.")
+    ] = False,
+    after: Annotated[
+        str, typer.Option("--after", help="Only messages received after this.")
+    ] = "-30d",
+    limit: LimitOpt = None,
+    all_: AllFlag = False,
+    json_: JsonFlag = False,
+):
+    """List Focused (or Other) inbox messages, newest first."""
+    limit, all_ = page_bounds(limit, all_, default=25)
+    tz = client.tz
+    after_dt = parse_dt(after, tz)
+    page = mailbox.list_focused(client, other=other, after=after_dt, limit=limit, all_=all_)
+    return ListResult(
+        items=page.items,
+        page=page,
+        window=Window(after=after_dt),
+        hit_cap=mail.CAP_LIST if all_ else None,
+        columns=mail.message_columns(tz),
+    )

mgraphctl/commands/meetings.py

@@ -0,0 +1,294 @@
+"""Online meetings, transcripts and AI insights (spec §8.10)."""
+
+from datetime import timedelta
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from mgraphctl import auth, render
+from mgraphctl.cli import JsonFlag, LimitOpt, gate, graph_command, make_noun_app
+from mgraphctl.errors import UsageError
+from mgraphctl.graph import meetings
+from mgraphctl.html import vtt_to_speaker_turns, vtt_to_text
+from mgraphctl.http import GraphClient
+from mgraphctl.render import (
+    Column,
+    FileResult,
+    ListResult,
+    ObjectResult,
+    TextResult,
+    Window,
+    fmt_dt,
+    fmt_dtz,
+    fmt_size,
+    truncate,
+)
+
+app = make_noun_app("Online meetings, transcripts and AI insights.")
+
+DEFAULT_LIMIT = 50
+FORMATS = ("text", "vtt")
+
+MeetingArg = Annotated[str | None, typer.Argument(metavar="MEETING", help="An online meeting id.")]
+JoinUrlOpt = Annotated[
+    str | None, typer.Option("--join-url", help="Select the meeting by its join URL.")
+]
+EventOpt = Annotated[
+    str | None, typer.Option("--event", help="Select the meeting from a calendar event id.")
+]
+
+GET_FIELDS = [
+    ("Meeting id", "id"),
+    ("Subject", "subject"),
+    ("Join URL", "joinWebUrl"),
+]
+
+
+def _window(start: str | None, end: str | None, tz: str) -> tuple:
+    """The `[start, end]` window: explicit `--start`/`--end`, else the last 7 days (spec §8.10)."""
+    start_dt = (
+        render.parse_dt(start, tz) if start else render.parse_dt("today", tz) - timedelta(days=7)
+    )
+    end_dt = (
+        render.parse_dt(end, tz, end_of_day=True)
+        if end
+        else render.parse_dt("today", tz, end_of_day=True)
+    )
+    return start_dt, end_dt
+
+
+@app.command("list")
+@graph_command(scopes=["Calendars.Read"])
+def list_(
+    client: GraphClient,
+    start: Annotated[str | None, typer.Option("--start", help="Start of the window.")] = None,
+    end: Annotated[str | None, typer.Option("--end", help="End of the window.")] = None,
+    subject: Annotated[
+        str | None, typer.Option("--subject", help="Case-insensitive subject substring.")
+    ] = None,
+    resolve: Annotated[
+        bool, typer.Option("--resolve", help="Resolve each event to its online meeting id.")
+    ] = False,
+    with_transcripts: Annotated[
+        bool,
+        typer.Option("--with-transcripts", help="Also list transcript ids (implies --resolve)."),
+    ] = False,
+    limit: LimitOpt = None,
+    json_: JsonFlag = False,
+):
+    """List calendar events that are online meetings (default window: the last 7 days)."""
+    tz = client.tz
+    start_dt, end_dt = _window(start, end, tz)
+    bound = limit if limit is not None else DEFAULT_LIMIT
+    page = meetings.list_online_events(
+        client, start=start_dt, end=end_dt, subject=subject, limit=bound, tz=tz
+    )
+    events = page.items
+    do_resolve = resolve or with_transcripts
+    resolved: dict[str, dict] = {}
+    if do_resolve:
+        gate(["OnlineMeetings.Read"])
+        resolved = meetings.resolve_meetings(client, events)
+    transcripts: dict[str, list] = {}
+    if with_transcripts:
+        gate(["OnlineMeetingTranscript.Read.All"])
+        meeting_ids = [m["id"] for m in resolved.values() if m.get("id")]
+        transcripts = meetings.transcripts_for(client, meeting_ids)
+    items = []
+    for event in events:
+        meeting = resolved.get(event["id"])
+        meeting_id = meeting.get("id") if meeting else None
+        items.append(
+            {
+                "eventId": event.get("id"),
+                "subject": event.get("subject"),
+                "start": event.get("start"),
+                "end": event.get("end"),
+                "organizer": event.get("organizer"),
+                "meetingId": meeting_id if do_resolve else None,
+                "transcriptIds": (
+                    [t.get("id") for t in transcripts.get(meeting_id, [])]
+                    if with_transcripts and meeting_id
+                    else []
+                ),
+            }
+        )
+    return ListResult(
+        items=items,
+        page=page,
+        window=Window(after=start_dt, before=end_dt),
+        supports_all=False,
+        columns=[
+            Column("start", lambda it: fmt_dtz(it.get("start"), tz)),
+            Column("subject", lambda it: truncate(it.get("subject"))),
+            Column("event_id", "eventId"),
+            Column("meeting_id", "meetingId"),
+            Column("transcripts", "transcriptIds"),
+        ],
+    )
+
+
+@app.command("get")
+@graph_command(scopes=["OnlineMeetings.Read"])
+def get(
+    client: GraphClient,
+    meeting: MeetingArg = None,
+    join_url: JoinUrlOpt = None,
+    event: EventOpt = None,
+    json_: JsonFlag = False,
+):
+    """Show one online meeting."""
+    obj = meetings.get_meeting(client, meeting, join_url=join_url, event=event)
+    return ObjectResult(obj=obj, fields=list(GET_FIELDS))
+
+
+@app.command("transcripts")
+@graph_command(scopes=["OnlineMeetingTranscript.Read.All"])
+def transcripts(
+    client: GraphClient,
+    meeting: MeetingArg = None,
+    join_url: JoinUrlOpt = None,
+    event: EventOpt = None,
+    json_: JsonFlag = False,
+):
+    """List the transcripts recorded for one online meeting."""
+    selected = meetings.select_meeting(client, meeting, join_url, event)
+    items = meetings.list_transcripts(client, selected["id"])
+    tz = client.tz
+    return ListResult(
+        items=items,
+        columns=[
+            Column("id", "id"),
+            Column("created", lambda t: fmt_dt(t.get("createdDateTime"), tz)),
+        ],
+    )
+
+
+@app.command("transcript")
+@graph_command(scopes=["OnlineMeetingTranscript.Read.All"])
+def transcript(
+    client: GraphClient,
+    ids: Annotated[
+        list[str] | None,
+        typer.Argument(
+            metavar="[MEETING] TRANSCRIPT_ID", help="The meeting id, then the transcript id."
+        ),
+    ] = None,
+    join_url: JoinUrlOpt = None,
+    event: EventOpt = None,
+    fmt: Annotated[str, typer.Option("--format", help="text or vtt.")] = "text",
+    speakers: Annotated[
+        bool, typer.Option("--speakers", help="Merge each speaker's consecutive cues into a turn.")
+    ] = False,
+    output: Annotated[
+        Path | None, typer.Option("--output", help="Write to this file instead of stdout.")
+    ] = None,
+    json_: JsonFlag = False,
+):
+    """Show one transcript's content."""
+    tokens = ids or []
+    if len(tokens) == 2:
+        meeting, transcript_id = tokens
+    elif len(tokens) == 1:
+        meeting, transcript_id = None, tokens[0]
+    else:
+        raise UsageError("USAGE", "give TRANSCRIPT_ID, and MEETING or --join-url or --event")
+    if fmt not in FORMATS:
+        raise UsageError("USAGE", f"--format must be one of {', '.join(FORMATS)}")
+    if speakers and fmt == "vtt":
+        raise UsageError(
+            "USAGE", "--speakers renders text; it cannot be combined with --format vtt"
+        )
+    selected = meetings.select_meeting(client, meeting, join_url, event)
+    meeting_id = selected["id"]
+    body = meetings.get_transcript_body(client, meeting_id, transcript_id)
+    # What Graph returned, not what was asked for: the speaker-attribution fallback answers in
+    # plain text even to a vtt request, and some meeting types answer in vtt to a text one.
+    is_vtt = meetings.looks_like_vtt(body)
+    if speakers:
+        text, shape = (vtt_to_speaker_turns(body) if is_vtt else body), "text"
+    elif fmt == "vtt":
+        text, shape = body, ("vtt" if is_vtt else "text")
+    else:
+        text, shape = (vtt_to_text(body) if is_vtt else body), "text"
+    if output is not None:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(text, encoding="utf-8")
+        size = len(text.encode("utf-8"))
+        return FileResult(
+            path=output,
+            bytes=size,
+            meta=dict(meetingId=meeting_id, transcriptId=transcript_id, format=shape),
+            message=f"Wrote the {shape} transcript ({fmt_size(size)}) to {output}",
+        )
+    # `createdDateTime` costs one extra request, so only the path that emits it pays.
+    created = meetings.transcript_created_at(client, meeting_id, transcript_id) if json_ else None
+    payload = dict(
+        meetingId=meeting_id,
+        transcriptId=transcript_id,
+        createdDateTime=created,
+        format=shape,
+        content=text,
+    )
+    return TextResult(text=text, json_obj=payload)
+
+
+@app.command("insights")
+@graph_command(scopes=["OnlineMeetingAiInsight.Read.All"])
+def insights(
+    client: GraphClient,
+    meeting: MeetingArg = None,
+    join_url: JoinUrlOpt = None,
+    event: EventOpt = None,
+    json_: JsonFlag = False,
+):
+    """AI-generated meeting insights (recap, action items, mentions)."""
+    selected = meetings.select_meeting(client, meeting, join_url, event)
+    oid = auth.my_oid()
+    items, note = meetings.insights(client, oid, selected["id"])
+    return ListResult(
+        items=items,
+        columns=[Column("id", "id"), Column("title", "title")],
+        empty_text=note or "No results.",
+        extra={"note": note} if note else None,
+    )
+
+
+@app.command("recordings")
+@graph_command(scopes=["OnlineMeetingRecording.Read.All"])
+def recordings(
+    client: GraphClient,
+    meeting: MeetingArg = None,
+    join_url: JoinUrlOpt = None,
+    event: EventOpt = None,
+    download: Annotated[
+        str | None, typer.Option("--download", metavar="RID", help="Recording id to download.")
+    ] = None,
+    output: Annotated[
+        Path | None, typer.Option("--output", help="File to write the recording to.")
+    ] = None,
+    json_: JsonFlag = False,
+):
+    """List recordings for one online meeting, or download one."""
+    selected = meetings.select_meeting(client, meeting, join_url, event)
+    meeting_id = selected["id"]
+    if download is not None or output is not None:
+        if download is None or output is None:
+            raise UsageError("USAGE", "--download and --output must be given together")
+        got = meetings.download_recording(client, meeting_id, download, output)
+        return FileResult(
+            path=got.path,
+            bytes=got.bytes,
+            meta=dict(contentType=got.content_type),
+            message=f"Downloaded recording ({fmt_size(got.bytes)}) to {got.path}",
+        )
+    items = meetings.list_recordings(client, meeting_id)
+    tz = client.tz
+    return ListResult(
+        items=items,
+        columns=[
+            Column("id", "id"),
+            Column("created", lambda r: fmt_dt(r.get("createdDateTime"), tz)),
+        ],
+    )