mgraphctl 0.1.0__py3-none-any.whl

mgraphctl/commands/chats.py

@@ -0,0 +1,329 @@
+"""Teams chat commands (spec §8.8)."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from mgraphctl import auth
+from mgraphctl.cli import (
+    AllFlag,
+    DryRunFlag,
+    JsonFlag,
+    LimitOpt,
+    gate,
+    graph_command,
+    make_noun_app,
+    page_bounds,
+    read_body,
+)
+from mgraphctl.errors import UsageError
+from mgraphctl.graph import chats, teams, users
+from mgraphctl.http import GraphClient
+from mgraphctl.render import (
+    Column,
+    DryRunResult,
+    FileResult,
+    ListResult,
+    ObjectResult,
+    Window,
+    WriteResult,
+    dig,
+    fmt_dt,
+    fmt_size,
+    parse_dt,
+    truncate,
+)
+
+CREATE_SCOPES = ["Chat.Create"]
+CHANNEL_SCOPES = ["ChannelMessage.Read.All"]
+
+ChatArg = Annotated[str, typer.Argument(metavar="CHAT", help="Chat id (19:…) or a UPN.")]
+BodyOpt = Annotated[str | None, typer.Option("--body", help="Message text.")]
+BodyFileOpt = Annotated[
+    str | None, typer.Option("--body-file", help="File holding the text, or - for stdin.")
+]
+HtmlFlag = Annotated[bool, typer.Option("--html", help="Send the body as HTML.")]
+
+app = make_noun_app("Teams chats and direct messages.")
+
+
+@app.command("list")
+@graph_command(scopes=["Chat.Read"])
+def list_(
+    client: GraphClient,
+    unread: Annotated[bool, typer.Option("--unread", help="Only chats with unread mail.")] = False,
+    chat_type: Annotated[
+        str | None, typer.Option("--type", help="oneOnOne, group or meeting.")
+    ] = None,
+    since: Annotated[
+        str | None,
+        typer.Option("--since", metavar="DT", help="Only chats with a message since this time."),
+    ] = None,
+    limit: LimitOpt = None,
+    all_: AllFlag = False,
+    json_: JsonFlag = False,
+):
+    """List your chats, most recently active first."""
+    tz = client.tz
+    since_dt = parse_dt(since, tz) if since else None
+    limit, all_ = page_bounds(limit, all_, default=20)
+    page = chats.list_chats(
+        client,
+        chat_type=chats.normalise_chat_type(chat_type),
+        since=since_dt,
+        limit=limit,
+        all_=all_,
+    )
+    items = [c for c in page.items if chats.is_unread(c)] if unread else page.items
+    oid = auth.my_oid()
+    columns = [
+        Column("id", "id"),
+        Column("flags", lambda c: "*" if chats.is_unread(c) else ""),
+        Column("type", "chatType"),
+        Column("updated", lambda c: fmt_dt(c.get("lastUpdatedDateTime"), tz)),
+    ]
+    if since_dt is not None:
+        # The column `--since` is measured against, so the boundary is visible in text mode.
+        columns.append(
+            Column(
+                "lastMessage",
+                lambda c: fmt_dt(dig(c, "lastMessagePreview.createdDateTime"), tz),
+            )
+        )
+    columns.append(Column("title", lambda c: truncate(chats.chat_title(c, oid))))
+    return ListResult(
+        items=items,
+        page=page,
+        window=Window(after=since_dt),
+        hit_cap=chats.CAP_CHATS if all_ else None,
+        empty_text="No chats.",
+        columns=columns,
+    )
+
+
+@app.command("get")
+@graph_command(scopes=["Chat.Read"])
+def get(client: GraphClient, chat: ChatArg, json_: JsonFlag = False):
+    """Show one chat."""
+    chat_id = chats.resolve_chat(client, chat)
+    oid = auth.my_oid()
+    tz = client.tz
+    return ObjectResult(
+        obj=chats.get_chat(client, chat_id),
+        fields=[
+            ("Title", lambda c: chats.chat_title(c, oid)),
+            ("Type", "chatType"),
+            ("Updated", lambda c: fmt_dt(c.get("lastUpdatedDateTime"), tz)),
+            ("Web URL", "webUrl"),
+            ("Chat id", "id"),
+        ],
+    )
+
+
+@app.command("members")
+@graph_command(scopes=["Chat.Read"])
+def members(client: GraphClient, chat: ChatArg, json_: JsonFlag = False):
+    """List a chat's members."""
+    chat_id = chats.resolve_chat(client, chat)
+    page = chats.list_chat_members(client, chat_id)
+    return ListResult(
+        items=page.items,
+        page=page,
+        supports_all=False,
+        empty_text="No members.",
+        columns=[
+            Column("id", "id"),
+            Column("name", "displayName"),
+            Column("email", "email"),
+            Column("userId", "userId"),
+        ],
+    )
+
+
+@app.command("messages")
+@graph_command(scopes=["Chat.Read"])
+def messages(
+    client: GraphClient,
+    chat: ChatArg,
+    after: Annotated[
+        str | None, typer.Option("--after", metavar="DT", help="Only messages after this time.")
+    ] = None,
+    before: Annotated[
+        str | None, typer.Option("--before", metavar="DT", help="Only messages before this time.")
+    ] = None,
+    full: Annotated[
+        bool, typer.Option("--full", help="Print whole bodies, not 300 chars.")
+    ] = False,
+    limit: LimitOpt = None,
+    all_: AllFlag = False,
+    json_: JsonFlag = False,
+):
+    """List chat messages, oldest first in text mode."""
+    tz = client.tz
+    since = parse_dt(after, tz) if after else None
+    until = parse_dt(before, tz, end_of_day=True) if before else None
+    if since is not None and until is not None and since > until:
+        raise UsageError("USAGE", "--after must not be later than --before")
+    limit, all_ = page_bounds(limit, all_, default=20)
+    chat_id = chats.resolve_chat(client, chat)
+    page = chats.chat_messages(client, chat_id, after=since, before=until, limit=limit, all_=all_)
+    # JSON keeps the Graph order (newest first); text reads better oldest first (§10 quirk 17).
+    # A chat message is the same Graph resource as a channel message, rendered by `graph.teams`.
+    return ListResult(
+        items=page.items if json_ else list(reversed(page.items)),
+        page=page,
+        window=Window(after=since, before=until),
+        hit_cap=chats.CAP_MESSAGES if all_ else None,
+        empty_text="No messages.",
+        columns=teams.message_columns(client.tz, full),
+    )
+
+
+@app.command("send")
+@graph_command(scopes=["ChatMessage.Send"])
+def send(
+    client: GraphClient,
+    chat: ChatArg,
+    body: BodyOpt = None,
+    body_file: BodyFileOpt = None,
+    html: HtmlFlag = False,
+    dry_run: DryRunFlag = False,
+    json_: JsonFlag = False,
+):
+    """Send a message to a chat."""
+    text = read_body(body, body_file)
+    chat_id = chats.resolve_chat(client, chat)
+    plan = chats.plan_chat_send(client, chat_id, body=text, html=html)
+    if dry_run:
+        return DryRunResult(plan)
+    return WriteResult(obj=client.execute(plan[0]), message="Sent.")
+
+
+@app.command("dm")
+@graph_command(scopes=["Chat.Read", "ChatMessage.Send"])
+def dm(
+    client: GraphClient,
+    user: Annotated[str, typer.Argument(metavar="USER", help="UPN, user id, or 'me'.")],
+    body: BodyOpt = None,
+    body_file: BodyFileOpt = None,
+    html: HtmlFlag = False,
+    dry_run: DryRunFlag = False,
+    json_: JsonFlag = False,
+):
+    """Send a direct message, creating the 1:1 chat when there is none yet."""
+    text = read_body(body, body_file)
+    if dry_run:
+        # Both branches are shown; looking the chat up would be a request (spec §8.8).
+        return DryRunResult(chats.plan_dm(client, user, None, body=text, html=html))
+    who = users.get_user(client, user, select=chats.DM_SELECT)
+    sent = chats.run_dm(
+        client,
+        who,
+        body=text,
+        html=html,
+        my_oid=auth.my_oid(),
+        can_create=lambda: gate(CREATE_SCOPES),
+    )
+    return WriteResult(obj=sent, message="Sent.")
+
+
+@app.command("create")
+@graph_command(scopes=CREATE_SCOPES)
+def create(
+    client: GraphClient,
+    member: Annotated[
+        list[str] | None,
+        typer.Option("--members", help="UPN or user id to add (repeatable, at least one)."),
+    ] = None,
+    topic: Annotated[str | None, typer.Option("--topic", help="Group chat topic.")] = None,
+    dry_run: DryRunFlag = False,
+    json_: JsonFlag = False,
+):
+    """Create a chat with the given members."""
+    plan = chats.plan_create_chat(
+        client, member_ids=member or [], topic=topic, my_oid=auth.my_oid()
+    )
+    if dry_run:
+        return DryRunResult(plan)
+    created = client.execute(plan[0]) or {}
+    return WriteResult(obj=created, message=f"Created chat {created.get('id')}.")
+
+
+@app.command("search")
+@graph_command(scopes=["Chat.Read"])
+def search(
+    client: GraphClient,
+    q: Annotated[str, typer.Argument(metavar="Q", help="What to look for.")],
+    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,
+    json_: JsonFlag = False,
+):
+    """Search your chat and channel messages. Hits carry a snippet, not the whole body."""
+    limit, all_ = page_bounds(limit, all_, default=25)
+    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 = chats.search_chat_messages(
+        client,
+        q,
+        after=after_dt,
+        before=before_dt,
+        limit=chats.CAP_SEARCH if all_ else limit,
+    )
+    return ListResult(
+        items=[chats.shape_chat_hit(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=chats.CAP_SEARCH if all_ else None,
+        empty_text="No messages found.",
+        columns=[
+            Column("id", "id"),
+            Column("created", lambda h: fmt_dt(h.get("created"), tz)),
+            Column("from", "from"),
+            Column("where", "where"),
+            Column("summary", lambda h: truncate(h.get("summary"))),
+        ],
+    )
+
+
+@app.command("hosted-content")
+@graph_command(scopes=[])
+def hosted_content(
+    client: GraphClient,
+    chat: Annotated[
+        str, typer.Argument(metavar="CHAT|URL", help="Chat id, or a full hostedContents URL.")
+    ],
+    msg_id: Annotated[str | None, typer.Argument(metavar="[MSGID]", help="Message id.")] = None,
+    hc_id: Annotated[
+        str | None, typer.Argument(metavar="[HCID]", help="Hosted content id.")
+    ] = None,
+    output: Annotated[
+        Path | None, typer.Option("--output", help="Where to write it; default is sniffed.")
+    ] = None,
+    json_: JsonFlag = False,
+):
+    """Download an image or file hosted inside a Teams message."""
+    target, hosted_id, is_channel = chats.hosted_content_target(chat, msg_id, hc_id)
+    # A channel URL reads channel messages, not chats, so the gate follows the form (spec §8.8).
+    gate(CHANNEL_SCOPES if is_channel else ["Chat.Read"])
+    # The name's extension comes from the bytes, so they are read before the file is opened.
+    data = client.request("GET", target, expect="bytes") or b""
+    dest = output or Path(chats.hosted_content_name(hosted_id, data))
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_bytes(data)
+    return FileResult(
+        path=dest,
+        bytes=len(data),
+        meta={},
+        message=f"Downloaded {dest.name} ({fmt_size(len(data))}) to {dest}",
+    )

mgraphctl/commands/config_cmd.py

@@ -0,0 +1,140 @@
+"""`config path|show|init`: the config file, its resolved values and where each came from."""
+
+import contextlib
+import os
+import tempfile
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from mgraphctl import config, render
+from mgraphctl.cli import Globals, JsonFlag, make_noun_app
+from mgraphctl.errors import UsageError
+from mgraphctl.render import TextResult, WriteResult
+
+app = make_noun_app("The config file: where it is, what it resolves to, and a starter template.")
+
+
+@app.command("path")
+def path_(json_: JsonFlag = False) -> None:
+    """Print the config file path in use."""
+    p = config.config_path()
+    render.emit(
+        TextResult(text=str(p), json_obj=dict(path=str(p), exists=p.exists())), json_mode=json_
+    )
+
+
+@app.command("show")
+def show(ctx: typer.Context, json_: JsonFlag = False) -> None:
+    """Every setting with its effective value and source (flag, env, file or default)."""
+    g: Globals = ctx.find_root().obj
+    rows = []
+    for key, value, source in config.effective_settings():
+        # The root callback already resolved these two (flag, detection): report what it uses.
+        if key == "tz":
+            value = g.tz
+        elif key == "debug":
+            value = g.debug
+        if key in g.flag_keys:
+            source = "flag"
+        rows.append((key, value, source))
+    unknown = config.unknown_config_keys()
+    p = config.config_path()
+    width = max(len(k) for k, _, _ in rows)
+    vwidth = max(len(str(v)) for _, v, _ in rows)
+    lines = [f"Config file: {p}"]
+    lines += [f"  {k:<{width}}  {str(v):<{vwidth}}  {src}" for k, v, src in rows]
+    if unknown:
+        lines.append(f"Unknown keys ignored: {', '.join(unknown)}")
+    payload = dict(
+        path=str(p),
+        settings={k: v for k, v, _ in rows},
+        sources={k: src for k, _, src in rows},
+        unknownKeys=unknown,
+    )
+    render.emit(TextResult(text="\n".join(lines), json_obj=payload), json_mode=json_)
+
+
+@app.command("init")
+def init(
+    force: Annotated[bool, typer.Option("--force", help="Overwrite an existing file.")] = False,
+    json_: JsonFlag = False,
+) -> None:
+    """Write a commented template with every key at its default."""
+    p = config.config_path()
+    existed = p.exists()
+    if existed and not force:
+        raise UsageError("USAGE", f"{p} already exists", hint="pass --force to overwrite it")
+    _write(p, config.CONFIG_TEMPLATE)
+    render.emit(
+        WriteResult(obj=dict(path=str(p), overwritten=existed), message=f"Wrote {p}"),
+        json_mode=json_,
+    )
+
+
+@app.command("set")
+def set_(
+    key: Annotated[str, typer.Argument(help="One of the config keys (see `config show`).")],
+    value: Annotated[str, typer.Argument(help="The value; integers for the numeric keys.")],
+    json_: JsonFlag = False,
+) -> None:
+    """Set one key in the config file, creating the file when it does not exist."""
+    parsed = config.parse_config_value(key, value)
+    if key == "tz" and not render.is_iana(value):
+        raise UsageError("USAGE", f"unknown time zone {value!r}; use an IANA name")
+    p = config.config_path()
+    config.load_config_file(p)  # a file that is not valid TOML must be fixed by hand first
+    _write(p, config.upsert_config_line(_read(p), key, parsed))
+    message = f"Set {key} = {config.format_toml_value(parsed)} in {p}"
+    render.emit(
+        WriteResult(obj=dict(path=str(p), key=key, value=parsed), message=message),
+        json_mode=json_,
+    )
+
+
+@app.command("unset")
+def unset(
+    key: Annotated[str, typer.Argument(help="One of the config keys (see `config show`).")],
+    json_: JsonFlag = False,
+) -> None:
+    """Comment a key out of the config file, so the environment or the default applies."""
+    if key not in config.CONFIG_KEYS:
+        raise UsageError(
+            "USAGE",
+            f"unknown config key {key!r}",
+            hint=f"one of: {', '.join(config.CONFIG_KEYS)}",
+        )
+    p = config.config_path()
+    removed = key in config.load_config_file(p)
+    if removed:
+        _write(p, config.upsert_config_line(_read(p), key, None))
+    render.emit(
+        WriteResult(obj=dict(path=str(p), key=key, removed=removed), message=f"Unset {key} in {p}"),
+        json_mode=json_,
+    )
+
+
+def _read(p: Path) -> str:
+    try:
+        return p.read_text()
+    except FileNotFoundError:
+        return ""
+
+
+def _write(p: Path, text: str) -> None:
+    """Atomic 0600 write into a 0700 directory, the same way the token cache is saved."""
+    p.parent.mkdir(parents=True, exist_ok=True)
+    with contextlib.suppress(OSError):
+        p.parent.chmod(0o700)
+    fd, tmp = tempfile.mkstemp(dir=p.parent, prefix=f"{p.name}.", suffix=".tmp")
+    try:
+        os.fchmod(fd, 0o600)
+        os.write(fd, text.encode())
+    finally:
+        os.close(fd)
+    os.replace(tmp, p)
+
+
+def register(root: typer.Typer) -> None:
+    root.add_typer(app, name="config")

mgraphctl/commands/groups.py

@@ -0,0 +1,65 @@
+"""Microsoft 365 groups (spec §8.16)."""
+
+from typing import Annotated
+
+import typer
+
+from mgraphctl.cli import AllFlag, JsonFlag, LimitOpt, graph_command, make_noun_app, page_bounds
+from mgraphctl.graph import groups
+from mgraphctl.http import GraphClient
+from mgraphctl.render import Column, ListResult
+
+app = make_noun_app("Microsoft 365 groups.")
+
+
+@app.command("list")
+@graph_command(scopes=["User.Read"])
+def list_(
+    client: GraphClient,
+    unified: Annotated[bool, typer.Option("--unified", help="Only Microsoft 365 groups.")] = False,
+    limit: LimitOpt = None,
+    all_: AllFlag = False,
+    json_: JsonFlag = False,
+):
+    """List the groups the signed-in user belongs to."""
+    limit, all_ = page_bounds(limit, all_, default=20)
+    page = groups.list_groups(client, unified=unified, limit=limit, all_=all_)
+    return ListResult(
+        items=page.items,
+        page=page,
+        hit_cap=groups.CAP if all_ else None,
+        columns=[
+            Column("id", "id"),
+            Column("name", "displayName"),
+            Column("mail", "mail"),
+            Column("types", "groupTypes"),
+            Column("description", "description"),
+        ],
+    )
+
+
+@app.command("members")
+@graph_command(scopes=["Group.Read.All"])
+def members(
+    client: GraphClient,
+    group: Annotated[str, typer.Argument(metavar="GROUP")],
+    limit: LimitOpt = None,
+    all_: AllFlag = False,
+    json_: JsonFlag = False,
+):
+    """List a group's members, by group name or id."""
+    limit, all_ = page_bounds(limit, all_, default=20)
+    resolved = groups.resolve_group(client, group)
+    page = groups.list_members(client, resolved["id"], limit=limit, all_=all_)
+    return ListResult(
+        items=page.items,
+        page=page,
+        hit_cap=groups.CAP if all_ else None,
+        columns=[
+            Column("id", "id"),
+            Column("name", "displayName"),
+            Column("upn", "userPrincipalName"),
+            Column("mail", "mail"),
+            Column("title", "jobTitle"),
+        ],
+    )