objectionengine2-teams 1.0.0__py3-none-any.whl

objectionengine2_teams/__init__.py

@@ -0,0 +1,20 @@
+"""Use Microsoft Graph messages as objectionengine2 dialogue."""
+
+from .auth import OFFICE_CLIENT_ID, AuthenticationError, acquire_access_token
+from .convert import messages_to_comments
+from .graph import GraphClient, GraphError
+from .links import TeamsTarget, parse_teams_link
+from .render import fetch_comments, render_teams_link
+
+__all__ = [
+    "OFFICE_CLIENT_ID",
+    "AuthenticationError",
+    "GraphClient",
+    "GraphError",
+    "TeamsTarget",
+    "acquire_access_token",
+    "fetch_comments",
+    "messages_to_comments",
+    "parse_teams_link",
+    "render_teams_link",
+]

objectionengine2_teams/auth.py

@@ -0,0 +1,159 @@
+"""Delegated Microsoft Graph authentication with a persistent Azure Identity cache."""
+
+import hashlib
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+from azure.core.exceptions import AzureError
+from azure.identity import (
+    AuthenticationRecord,
+    DeviceCodeCredential,
+    InteractiveBrowserCredential,
+    SharedTokenCacheCredential,
+    TokenCachePersistenceOptions,
+)
+from azure.identity.broker import InteractiveBrowserBrokerCredential
+from msal import PublicClientApplication
+
+OFFICE_CLIENT_ID = "d3590ed6-52b3-4102-aeff-aad2292ab01c"
+BROWSER_REDIRECT_URI = "http://localhost:8400"
+_SCOPES = {
+    "chat": "https://graph.microsoft.com/Chat.ReadWrite",
+    "channel": "https://graph.microsoft.com/ChannelMessage.Read.All",
+}
+
+
+class AuthenticationError(RuntimeError):
+    """Microsoft Entra ID did not issue a usable Graph token."""
+
+
+def _state_dir() -> Path:
+    """Return the per-user directory for non-secret authentication records."""
+    if os.name == "nt":
+        root = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
+    elif sys.platform == "darwin":
+        root = Path.home() / "Library" / "Application Support"
+    else:
+        root = Path(
+            os.environ.get("XDG_STATE_HOME") or Path.home() / ".local" / "state"
+        )
+    return root / "objectionengine2-teams"
+
+
+def _cache_key(client_id: str, tenant_id: str) -> str:
+    return hashlib.sha256(
+        f"{client_id.lower()}\0{tenant_id.lower()}".encode()
+    ).hexdigest()[:24]
+
+
+def _load_record(path: Path, client_id: str) -> AuthenticationRecord | None:
+    try:
+        serialized = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+    except OSError as exc:
+        raise AuthenticationError(
+            f"Could not read the cached account record at {path}: {exc}"
+        ) from exc
+    try:
+        record = AuthenticationRecord.deserialize(serialized)
+    except (TypeError, ValueError, KeyError) as exc:
+        raise AuthenticationError(
+            f"The cached account record at {path} is invalid. Delete it and sign in again."
+        ) from exc
+    return record if record.client_id.lower() == client_id.lower() else None
+
+
+def _save_record(path: Path, record: AuthenticationRecord) -> None:
+    """Atomically save account identity; Azure Identity stores tokens separately."""
+    temporary_path: Path | None = None
+    try:
+        path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=path.parent,
+            prefix=".account-",
+            delete=False,
+        ) as temporary:
+            temporary_path = Path(temporary.name)
+            temporary.write(record.serialize())
+        os.replace(temporary_path, path)
+    except OSError as exc:
+        raise AuthenticationError(
+            f"Could not save the cached account record at {path}: {exc}"
+        ) from exc
+    finally:
+        if temporary_path is not None:
+            temporary_path.unlink(missing_ok=True)
+
+
+def acquire_access_token(
+    kind: str,
+    *,
+    tenant_id: str | None = None,
+    client_id: str = OFFICE_CLIENT_ID,
+    auth_method: str = "broker",
+    redirect_uri: str = BROWSER_REDIRECT_URI,
+    record_dir: str | Path | None = None,
+) -> str:
+    """Return a Graph token, reusing the user's cached account when possible.
+
+    Broker sign-in is the default. Set ``auth_method='browser'`` or
+    ``auth_method='device-code'`` to use another interactive method. All
+    methods use the Microsoft Office public client ID unless overridden.
+    """
+    if kind not in _SCOPES:
+        raise ValueError("kind must be 'chat' or 'channel'")
+    if auth_method not in ("broker", "browser", "device-code", "cache"):
+        raise ValueError(
+            "auth_method must be 'broker', 'browser', 'device-code', or 'cache'"
+        )
+
+    tenant = tenant_id or "organizations"
+    key = _cache_key(client_id, tenant)
+    record_path = (
+        Path(record_dir) if record_dir is not None else _state_dir()
+    ) / f"{key}.json"
+    record = _load_record(record_path, client_id)
+    options = TokenCachePersistenceOptions(
+        name=f"objectionengine2-teams-{key}", allow_unencrypted_storage=True
+    )
+    kwargs = {
+        "client_id": client_id,
+        "tenant_id": tenant,
+        "cache_persistence_options": options,
+    }
+    if record is not None:
+        kwargs["authentication_record"] = record
+    scope = _SCOPES[kind]
+    credential = None
+    try:
+        if auth_method == "broker":
+            credential = InteractiveBrowserBrokerCredential(
+                parent_window_handle=PublicClientApplication.CONSOLE_WINDOW_HANDLE,
+                use_default_broker_account=True,
+                **kwargs,
+            )
+        elif auth_method == "cache":
+            credential = SharedTokenCacheCredential(**kwargs)
+        elif auth_method == "browser":
+            credential = InteractiveBrowserCredential(
+                redirect_uri=redirect_uri, **kwargs
+            )
+        elif auth_method == "device-code":
+            credential = DeviceCodeCredential(**kwargs)
+        if record is None and auth_method in ("browser", "device-code"):
+            record = credential.authenticate(scopes=[scope])
+            _save_record(record_path, record)
+        return credential.get_token(scope).token
+    except AzureError as exc:
+        raise AuthenticationError(
+            f"Microsoft sign-in could not grant {scope} to client {client_id}: {exc}. "
+            "Your tenant may require administrator consent for this Graph permission."
+        ) from exc
+    finally:
+        if credential is not None:
+            credential.close()

objectionengine2_teams/cli.py

@@ -0,0 +1,61 @@
+"""Command-line interface for rendering a Teams conversation."""
+
+import argparse
+
+from .auth import BROWSER_REDIRECT_URI, OFFICE_CLIENT_ID, AuthenticationError
+from .graph import GraphError
+from .render import render_teams_link
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="objectionengine2-teams",
+        description="Render a Microsoft Teams chat or channel as an Objection Engine video.",
+    )
+    parser.add_argument("link", help="A Teams chat, channel, or starting message link")
+    parser.add_argument("-o", "--output", default="teams.mp4", help="Output MP4 path")
+    parser.add_argument(
+        "--end-link", help="Inclusive ending message link in the same conversation"
+    )
+    parser.add_argument(
+        "--max-messages",
+        type=int,
+        help="At most N messages from the start link, or the newest N for a whole chat/channel",
+    )
+    parser.add_argument(
+        "--client-id", default=OFFICE_CLIENT_ID, help="Public client application ID"
+    )
+    parser.add_argument(
+        "--auth-method",
+        choices=("broker", "browser", "device-code", "cache"),
+        default="broker",
+        help="Sign-in method (default: broker)",
+    )
+    parser.add_argument(
+        "--redirect-uri",
+        default=BROWSER_REDIRECT_URI,
+        help="Registered redirect URI for browser sign-in",
+    )
+    parser.add_argument(
+        "--music-code", default="pwr", help="Objection Engine music code"
+    )
+    parser.add_argument("--resolution-scale", type=float, default=1.0)
+    args = parser.parse_args(argv)
+    if args.max_messages is not None and args.max_messages < 1:
+        parser.error("--max-messages must be positive")
+    try:
+        output = render_teams_link(
+            args.link,
+            args.output,
+            end_link=args.end_link,
+            max_messages=args.max_messages,
+            client_id=args.client_id,
+            auth_method=args.auth_method,
+            redirect_uri=args.redirect_uri,
+            music_code=args.music_code,
+            resolution_scale=args.resolution_scale,
+        )
+    except (AuthenticationError, GraphError, ValueError) as exc:
+        parser.exit(1, f"{parser.prog}: {exc}\n")
+    print(f"Saved {output}")
+    return 0

objectionengine2_teams/convert.py

@@ -0,0 +1,119 @@
+"""Map Microsoft Graph chatMessage bodies to objectionengine2 comments."""
+
+from html.parser import HTMLParser
+import re
+from typing import Any, Iterable
+
+from objectionengine2.beans.comment import Comment
+
+
+class _TeamsHTMLParser(HTMLParser):
+    _BREAKS = {"br", "div", "p", "li", "blockquote", "tr"}
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.parts: list[str] = []
+        self.hidden_depth = 0
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag in {"script", "style"}:
+            self.hidden_depth += 1
+        elif self.hidden_depth == 0 and tag in self._BREAKS:
+            self.parts.append("\n")
+        elif self.hidden_depth == 0 and tag == "img":
+            alt = dict(attrs).get("alt")
+            if alt:
+                self.parts.append(alt)
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in {"script", "style"} and self.hidden_depth:
+            self.hidden_depth -= 1
+        elif self.hidden_depth == 0 and tag in self._BREAKS:
+            self.parts.append("\n")
+
+    def handle_data(self, data: str) -> None:
+        if self.hidden_depth == 0:
+            self.parts.append(data)
+
+
+def _message_text(message: dict[str, Any]) -> str:
+    subject = message.get("subject")
+    title = re.sub(r"\s+", " ", subject).strip() if isinstance(subject, str) else ""
+    body = message.get("body") or {}
+    if not isinstance(body, dict):
+        body = {}
+    content = body.get("content") or ""
+    if not isinstance(content, str):
+        content = ""
+    if str(body.get("contentType", "")).lower() == "html":
+        parser = _TeamsHTMLParser()
+        parser.feed(content)
+        content = "".join(parser.parts)
+    lines = [re.sub(r"\s+", " ", line).strip() for line in content.splitlines()]
+    text = "\n".join(line for line in lines if line)
+    if not text:
+        attachments = message.get("attachments") or []
+        if isinstance(attachments, list) and attachments:
+            names = [attachment.get("name") for attachment in attachments if isinstance(attachment, dict)]
+            names = [name for name in names if isinstance(name, str) and name.strip()]
+            text = "Shared an attachment" + (": " + ", ".join(names) if names else "")
+    return "\n".join(part for part in (title, text) if part)
+
+
+def _speaker(message: dict[str, Any]) -> tuple[str, str]:
+    actor = message.get("from") or {}
+    if not isinstance(actor, dict):
+        actor = {}
+    for key in ("user", "application", "device"):
+        value = actor.get(key)
+        if isinstance(value, dict):
+            name = value.get("displayName") or "Unknown speaker"
+            identity = value.get("id") or name
+            return str(identity), str(name)
+    return "unknown", "Unknown speaker"
+
+
+def messages_to_comments(
+    messages: Iterable[dict[str, Any]],
+    *,
+    start_message_id: str | None = None,
+    end_message_id: str | None = None,
+    max_messages: int | None = None,
+) -> list[Comment]:
+    """Convert an inclusive message range to chronological dialogue."""
+    if max_messages is not None and max_messages < 1:
+        raise ValueError("max_messages must be positive")
+    ordered: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for message in messages:
+        message_id = str(message.get("id") or "")
+        if message_id and message_id in seen:
+            continue
+        seen.add(message_id)
+        ordered.append(message)
+    ordered.sort(key=lambda message: (str(message.get("createdDateTime") or ""), str(message.get("id") or "")))
+
+    ids = [str(message.get("id") or "") for message in ordered]
+    if start_message_id is not None and start_message_id not in ids:
+        raise ValueError(f"Start message {start_message_id} was not found in this conversation")
+    if end_message_id is not None and end_message_id not in ids:
+        raise ValueError(f"End message {end_message_id} was not found in this conversation")
+    if not ordered:
+        return []
+    start = ids.index(start_message_id) if start_message_id is not None else 0
+    end = ids.index(end_message_id) if end_message_id is not None else len(ordered) - 1
+    if end < start:
+        raise ValueError("The end message occurs before the start message")
+
+    comments: list[Comment] = []
+    for message in ordered[start : end + 1]:
+        if message.get("messageType", "message") != "message" or message.get("deletedDateTime"):
+            continue
+        text = _message_text(message)
+        if not text:
+            continue
+        user_id, user_name = _speaker(message)
+        comments.append(Comment(user_id=user_id, user_name=user_name, text_content=text))
+    if max_messages is not None:
+        comments = comments[:max_messages] if start_message_id else comments[-max_messages:]
+    return comments

objectionengine2_teams/graph.py

@@ -0,0 +1,171 @@
+"""Small Microsoft Graph client for Teams message collections."""
+
+from collections.abc import Callable, Iterator
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from time import sleep
+from typing import Any
+from urllib.parse import quote, urlsplit
+
+import requests
+
+from .links import TeamsTarget
+
+
+_GRAPH_ROOT = "https://graph.microsoft.com/v1.0"
+
+
+class GraphError(RuntimeError):
+    """Microsoft Graph did not return a usable Teams message collection."""
+
+
+class GraphClient:
+    def __init__(
+        self,
+        access_token: str,
+        *,
+        session: requests.Session | None = None,
+        wait: Callable[[float], None] = sleep,
+        max_retries: int = 4,
+    ) -> None:
+        if not access_token:
+            raise ValueError("A Microsoft Graph access token is required")
+        self._session = session if session is not None else requests.Session()
+        self._owns_session = session is None
+        self._headers = {"Authorization": f"Bearer {access_token}", "Accept": "application/json"}
+        self._wait = wait
+        self._max_retries = max_retries
+
+    def close(self) -> None:
+        if self._owns_session:
+            self._session.close()
+
+    def __enter__(self) -> "GraphClient":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    @staticmethod
+    def _validate_url(url: str) -> None:
+        parsed = urlsplit(url)
+        if (
+            parsed.scheme != "https"
+            or parsed.hostname != "graph.microsoft.com"
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.port is not None
+            or not parsed.path.startswith("/v1.0/")
+        ):
+            raise GraphError("Microsoft Graph returned an unsafe pagination URL")
+
+    @staticmethod
+    def _retry_delay(response: requests.Response, attempt: int) -> float:
+        retry_after = response.headers.get("Retry-After")
+        if retry_after:
+            try:
+                return min(120.0, max(0.0, float(retry_after)))
+            except ValueError:
+                try:
+                    deadline = parsedate_to_datetime(retry_after)
+                    return min(120.0, max(0.0, (deadline - datetime.now(timezone.utc)).total_seconds()))
+                except (TypeError, ValueError):
+                    pass
+        return min(30.0, float(2**attempt))
+
+    def _get_json(self, url: str, scope: str) -> dict[str, Any]:
+        self._validate_url(url)
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._session.get(
+                    url, headers=self._headers, timeout=30, allow_redirects=False
+                )
+            except requests.RequestException as exc:
+                raise GraphError(f"Could not reach Microsoft Graph: {exc}") from exc
+            if response.status_code in (429, 503, 504) and attempt < self._max_retries:
+                self._wait(self._retry_delay(response, attempt))
+                continue
+            if response.status_code == 403:
+                raise GraphError(
+                    f"Microsoft Graph denied access (403). The signed-in user needs access "
+                    f"to this conversation, and client consent for {scope} is required."
+                )
+            if response.status_code == 401:
+                raise GraphError("Microsoft Graph rejected the access token (401); sign in again")
+            if response.status_code >= 400 or response.status_code < 200 or response.status_code >= 300:
+                detail = ""
+                try:
+                    detail = response.json().get("error", {}).get("message", "")
+                except (ValueError, AttributeError):
+                    pass
+                raise GraphError(f"Microsoft Graph returned HTTP {response.status_code}: {detail}".strip())
+            try:
+                data = response.json()
+            except ValueError as exc:
+                raise GraphError("Microsoft Graph returned invalid JSON") from exc
+            if not isinstance(data, dict):
+                raise GraphError("Microsoft Graph returned an unexpected response")
+            return data
+        raise AssertionError("unreachable")
+
+    def _pages(self, url: str, scope: str) -> Iterator[dict[str, Any]]:
+        seen: set[str] = set()
+        while url:
+            if url in seen:
+                raise GraphError("Microsoft Graph returned a repeated pagination URL")
+            seen.add(url)
+            page = self._get_json(url, scope)
+            items = page.get("value")
+            if not isinstance(items, list):
+                raise GraphError("Microsoft Graph omitted the message collection")
+            for item in items:
+                if not isinstance(item, dict):
+                    raise GraphError("Microsoft Graph returned a malformed message")
+                yield item
+            next_url = page.get("@odata.nextLink")
+            if next_url is not None and not isinstance(next_url, str):
+                raise GraphError("Microsoft Graph returned a malformed pagination URL")
+            url = next_url or ""
+
+    def iter_messages(
+        self, target: TeamsTarget, *, end_message_id: str | None = None
+    ) -> Iterator[dict[str, Any]]:
+        """Yield chat messages, one channel thread, or a complete channel."""
+        if target.kind == "chat" and target.chat_id:
+            chat = quote(target.chat_id, safe="")
+            url = f"{_GRAPH_ROOT}/chats/{chat}/messages?$top=50&$orderby=createdDateTime desc"
+            found_start = False
+            found_end = end_message_id is None
+            for message in self._pages(url, "Chat.Read"):
+                yield message
+                if str(message.get("id")) == target.start_message_id:
+                    found_start = True
+                if str(message.get("id")) == end_message_id:
+                    found_end = True
+                if target.start_message_id and found_start and found_end:
+                    break
+            return
+        if target.kind == "channel" and target.team_id and target.channel_id:
+            team = quote(target.team_id, safe="")
+            channel = quote(target.channel_id, safe="")
+            root = f"{_GRAPH_ROOT}/teams/{team}/channels/{channel}/messages"
+            if target.start_message_id:
+                parent_id = target.parent_message_id or target.start_message_id
+                thread_url = f"{root}/{quote(parent_id, safe='')}"
+                parent = self._get_json(thread_url, "ChannelMessage.Read.All")
+                if str(parent.get("id")) != parent_id:
+                    raise GraphError("Microsoft Graph returned a different channel thread")
+                yield parent
+                yield from self._pages(
+                    f"{thread_url}/replies?$top=50", "ChannelMessage.Read.All"
+                )
+                return
+            for message in self._pages(f"{root}?$top=50", "ChannelMessage.Read.All"):
+                yield message
+                message_id = message.get("id")
+                if not isinstance(message_id, str) or not message_id:
+                    raise GraphError("A channel message is missing its ID")
+                reply_url = f"{root}/{quote(message_id, safe='')}/replies?$top=50"
+                yield from self._pages(reply_url, "ChannelMessage.Read.All")
+            return
+        raise ValueError("Incomplete Teams target")

objectionengine2_teams/links.py

@@ -0,0 +1,120 @@
+"""Recognize documented Microsoft Teams chat and channel deep links."""
+
+from dataclasses import dataclass
+import json
+import re
+from typing import Literal
+from urllib.parse import parse_qs, unquote, urlsplit
+from uuid import UUID
+
+
+_TEAMS_HOSTS = {"teams.microsoft.com", "teams.cloud.microsoft"}
+_ID_RE = re.compile(r"^19:[A-Za-z0-9._@:-]{1,500}$")
+_MESSAGE_ID_RE = re.compile(r"^[A-Za-z0-9._@:-]{1,500}$")
+
+
+@dataclass(frozen=True)
+class TeamsTarget:
+    kind: Literal["chat", "channel"]
+    chat_id: str | None = None
+    team_id: str | None = None
+    channel_id: str | None = None
+    tenant_id: str | None = None
+    start_message_id: str | None = None
+    parent_message_id: str | None = None
+
+
+def _uuid_parameter(query: dict[str, list[str]], name: str) -> str | None:
+    values = query.get(name, [])
+    if not values:
+        return None
+    if len(values) != 1:
+        raise ValueError(f"Teams link has more than one {name} parameter")
+    try:
+        return str(UUID(values[0]))
+    except ValueError as exc:
+        raise ValueError(f"Teams link has an invalid {name} parameter") from exc
+
+
+def _teams_id(raw: str) -> str:
+    value = unquote(raw)
+    if not _ID_RE.fullmatch(value):
+        raise ValueError("Teams link has an invalid chat or channel ID")
+    return value
+
+
+def _message_id(raw: str) -> str:
+    value = unquote(raw)
+    if not _MESSAGE_ID_RE.fullmatch(value):
+        raise ValueError("Teams link has an invalid message ID")
+    return value
+
+
+def parse_teams_link(link: str) -> TeamsTarget:
+    """Return the conversation addressed by a Teams deep link.
+
+    A channel message link selects one thread and starts at its path message ID.
+    """
+    parsed = urlsplit(link)
+    if (
+        parsed.scheme != "https"
+        or parsed.hostname not in _TEAMS_HOSTS
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.port is not None
+    ):
+        raise ValueError("Expected an HTTPS link on teams.microsoft.com or teams.cloud.microsoft")
+
+    parts = parsed.path.strip("/").split("/")
+    query = parse_qs(parsed.query)
+    tenant_id = _uuid_parameter(query, "tenantId")
+    group_id = _uuid_parameter(query, "groupId")
+
+    if len(parts) >= 4 and parts[:2] == ["l", "chat"] and parts[3] == "conversations":
+        chat_id = _teams_id(parts[2])
+        return TeamsTarget("chat", chat_id=chat_id, tenant_id=tenant_id)
+
+    if len(parts) >= 4 and parts[:2] == ["l", "channel"]:
+        channel_id = _teams_id(parts[2])
+        if group_id is None:
+            raise ValueError("Channel links must include groupId (the team ID)")
+        return TeamsTarget("channel", team_id=group_id, channel_id=channel_id, tenant_id=tenant_id)
+
+    if len(parts) == 4 and parts[:2] == ["l", "team"] and parts[3] == "conversations":
+        channel_id = _teams_id(parts[2])
+        if group_id is None:
+            raise ValueError("Team links must include groupId (the team ID)")
+        return TeamsTarget("channel", team_id=group_id, channel_id=channel_id, tenant_id=tenant_id)
+
+    if len(parts) == 4 and parts[:2] == ["l", "message"]:
+        conversation_id = _teams_id(parts[2])
+        start_message_id = _message_id(parts[3])
+        if group_id is not None:
+            parents = query.get("parentMessageId", [])
+            if len(parents) > 1:
+                raise ValueError("Teams link has more than one parentMessageId parameter")
+            parent_message_id = _message_id(parents[0]) if parents else start_message_id
+            return TeamsTarget(
+                "channel",
+                team_id=group_id,
+                channel_id=conversation_id,
+                tenant_id=tenant_id,
+                start_message_id=start_message_id,
+                parent_message_id=parent_message_id,
+            )
+        context_values = query.get("context", [])
+        if context_values:
+            try:
+                context = json.loads(context_values[0])
+            except json.JSONDecodeError as exc:
+                raise ValueError("Teams link has an invalid context parameter") from exc
+            if not isinstance(context, dict) or context.get("contextType") != "chat":
+                raise ValueError("A channel message link must include groupId")
+        if conversation_id.endswith("@thread.tacv2"):
+            raise ValueError("A channel message link must include groupId")
+        return TeamsTarget(
+            "chat", chat_id=conversation_id, tenant_id=tenant_id,
+            start_message_id=start_message_id,
+        )
+
+    raise ValueError("Unsupported Teams link; copy a chat, channel, or message link from Teams")

objectionengine2_teams/render.py

@@ -0,0 +1,114 @@
+"""Public Teams-to-video API."""
+
+from contextlib import contextmanager
+import os
+from pathlib import Path
+
+from objectionengine2.beans.comment import Comment
+from objectionengine2.renderer import render_comment_list
+
+from .auth import BROWSER_REDIRECT_URI, OFFICE_CLIENT_ID, acquire_access_token
+from .convert import messages_to_comments
+from .graph import GraphClient
+from .links import TeamsTarget, parse_teams_link
+
+
+@contextmanager
+def _default_sentiment():
+    """Select Hugging Face for this render unless the caller chose a core mode."""
+    if "oe_sentiment_model" in os.environ:
+        yield
+        return
+    os.environ["oe_sentiment_model"] = "hf"
+    try:
+        yield
+    finally:
+        os.environ.pop("oe_sentiment_model", None)
+
+
+def _end_target(start: TeamsTarget, end_link: str | None) -> TeamsTarget | None:
+    if end_link is None:
+        return None
+    end = parse_teams_link(end_link)
+    if start.start_message_id is None or end.start_message_id is None:
+        raise ValueError("Both start and end links must point to messages")
+    if start.kind != end.kind:
+        raise ValueError("Start and end links must point to the same conversation")
+    if start.kind == "chat" and start.chat_id != end.chat_id:
+        raise ValueError("Start and end links must point to the same chat")
+    if start.kind == "channel":
+        if (start.team_id, start.channel_id) != (end.team_id, end.channel_id):
+            raise ValueError("Start and end links must point to the same channel")
+        if start.parent_message_id != end.parent_message_id:
+            raise ValueError("Start and end links must point to the same channel thread")
+    if start.tenant_id and end.tenant_id and start.tenant_id != end.tenant_id:
+        raise ValueError("Start and end links must point to the same tenant")
+    return end
+
+
+def fetch_comments(
+    link: str,
+    *,
+    end_link: str | None = None,
+    max_messages: int | None = None,
+    client_id: str = OFFICE_CLIENT_ID,
+    auth_method: str = "broker",
+    redirect_uri: str = BROWSER_REDIRECT_URI,
+) -> list[Comment]:
+    """Read a Teams conversation from the linked message through an optional end."""
+    target = parse_teams_link(link)
+    end = _end_target(target, end_link)
+    tenant_id = target.tenant_id or (end.tenant_id if end else None)
+    token = acquire_access_token(
+        target.kind,
+        tenant_id=tenant_id,
+        client_id=client_id,
+        auth_method=auth_method,
+        redirect_uri=redirect_uri,
+    )
+    with GraphClient(token) as graph:
+        messages = (
+            graph.iter_messages(target, end_message_id=end.start_message_id)
+            if end else graph.iter_messages(target)
+        )
+        comments = messages_to_comments(
+            messages,
+            start_message_id=target.start_message_id,
+            end_message_id=end.start_message_id if end else None,
+            max_messages=max_messages,
+        )
+    return comments
+
+
+def render_teams_link(
+    link: str,
+    output_filename: str | Path = "teams.mp4",
+    *,
+    end_link: str | None = None,
+    max_messages: int | None = None,
+    client_id: str = OFFICE_CLIENT_ID,
+    auth_method: str = "broker",
+    redirect_uri: str = BROWSER_REDIRECT_URI,
+    music_code: str = "pwr",
+    resolution_scale: float = 1,
+) -> Path:
+    """Render a Teams conversation, starting at the linked message, to MP4."""
+    comments = fetch_comments(
+        link,
+        end_link=end_link,
+        max_messages=max_messages,
+        client_id=client_id,
+        auth_method=auth_method,
+        redirect_uri=redirect_uri,
+    )
+    if not comments:
+        raise ValueError("This Teams conversation has no renderable messages")
+    output = Path(output_filename)
+    with _default_sentiment():
+        render_comment_list(
+            comments,
+            output_filename=str(output),
+            music_code=music_code,
+            resolution_scale=resolution_scale,
+        )
+    return output

objectionengine2_teams-1.0.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: objectionengine2-teams
+Version: 1.0.0
+Summary: Render Microsoft Teams chats and channels with objectionengine2
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: objectionengine2[sentiment]>=1.0.0,<2
+Requires-Dist: azure-identity>=1.25,<2
+Requires-Dist: requests>=2.32,<3
+Requires-Dist: torch>=2.8,<3
+Requires-Dist: azure-identity-broker>=1.3.0
+Requires-Dist: msal>=1.30,<2
+Requires-Dist: objectionengine2[sentiment] ; extra == 'sentiment'
+Requires-Python: >=3.10, <3.15
+Provides-Extra: sentiment
+Description-Content-Type: text/markdown
+
+# objectionengine2-teams
+
+Render a Microsoft Teams chat or channel as an Objection Engine 2 video. This is
+a separate Python 3.10–3.14 package using Microsoft Graph delegated access.
+
+## Install
+
+Clone `objectionengine2-teams` and install its dependencies with uv. The core
+`objectionengine2` package is installed from PyPI:
+
+```bash
+cd ~/development/objectionengine2-teams
+uv sync --locked
+```
+
+The standard install includes the core sentiment dependencies. The first
+render downloads the Hugging Face sentiment model.
+
+Install FFmpeg and `ffprobe` for video rendering. Objection Engine saves its
+asset pack and sentiment model under the platformdirs user cache for
+`objectionengine2`. The first render populates the cache. See the cache path
+with `uv run python -c 'from objectionengine2.cache import cache_path; print(cache_path())'`.
+Run from the Teams checkout:
+
+```bash
+cd ~/development/objectionengine2-teams
+mkdir -p outputs
+uv run --locked objectionengine2-teams \
+  'https://teams.microsoft.com/l/chat/19:example@thread.v2/conversations' \
+  -o outputs/teams.mp4
+```
+
+Replace the example URL with a real link copied from a chat or channel. A
+channel link renders the channel; a channel **message link** renders only its
+thread. Its `parentMessageId` identifies the thread root, while the message ID
+in the URL path is the first message rendered. A chat message link likewise
+starts at the linked message. You can bound the render with another message
+link in the same chat or channel thread:
+
+```bash
+uv run --locked objectionengine2-teams \
+  '<start message link>' --end-link '<end message link>' -o outputs/teams.mp4
+```
+
+Both endpoints are included. `--max-messages 20` selects the first 20 rendered
+messages after a start link, or the newest 20 for an unbounded chat/channel
+link. The CLI sorts them by creation time. When a channel thread's first
+message has a title, it appears before that message's body in its comment.
+Starting from a later reply excludes the first message and its title. Rich
+attachments, reactions, deleted messages, and system events are not represented;
+an attachment-only message becomes a short placeholder.
+
+## Sign-in and permissions
+
+The default public client ID is the requested Microsoft Office ID,
+`d3590ed6-52b3-4102-aeff-aad2292ab01c`. Azure Identity uses
+`InteractiveBrowserBrokerCredential` by default and requests only the delegated
+permission needed for the link:
+
+| Link | Delegated Microsoft Graph permission |
+| --- | --- |
+| Chat | `Chat.Read` |
+| Channel | `ChannelMessage.Read.All` |
+
+The signed-in user must have access to the conversation. Microsoft Entra may
+reject this client or require administrator consent, especially for the channel
+permission. The client ID does not itself guarantee a grant. If the Office
+client cannot obtain the requested scope, register a public client application
+in your tenant with the Graph delegated permission and pass its ID through
+`--client-id`. Broker sign-in uses the platform's broker redirect URI; on
+Windows and WSL, that is
+`ms-appx-web://Microsoft.AAD.BrokerPlugin/<client-id>`. The application must
+allow that redirect. The `--redirect-uri` option applies only to explicit
+`--auth-method browser` sign-in, whose default callback is
+`http://localhost:8400`.
+
+On Windows, broker sign-in uses Web Account Manager. On WSL 2.4.13 or newer,
+it can use the Windows broker as well. On other Linux setups it may open a
+browser if a supported broker is unavailable. To select another method, use:
+
+```bash
+uv run --locked objectionengine2-teams '<Teams message link>' \
+  --auth-method browser -o outputs/teams.mp4
+uv run --locked objectionengine2-teams '<Teams message link>' \
+  --auth-method device-code -o outputs/teams.mp4
+```
+
+Azure Identity persists tokens in a per-user cache and reuses them on later
+runs. Broker sign-in first tries the default broker account silently and then
+offers interactive sign-in if needed. Use `--auth-method cache` to read an
+already cached token without an interactive fallback. Azure Identity encrypts
+the persistent cache when the platform supports it; on platforms without
+user-data encryption (including some WSL installations), it may store tokens
+unencrypted. Keep your user profile private. Browser and device-code sign-in
+also save a separate non-secret account record under the user state directory
+(`~/.local/state/objectionengine2-teams/` on Linux unless `XDG_STATE_HOME` is
+set). The methods use the same named persistent token cache.
+
+## Sentiment and objections
+
+Teams messages have no explicit `Comment.score`. Teams renders use the core
+Hugging Face sentiment model by default. The normal command is enough:
+
+```bash
+uv run --locked objectionengine2-teams \
+  '<Teams message link>' -o outputs/teams.mp4
+```
+
+Set `oe_sentiment_model=neutral` or `oe_bypass_sentiment=1` to use neutral
+sentiment for a render. An explicit `oe_sentiment_model` value is respected.
+A strongly negative classification
+(confidence above 0.5) has roughly a 70% chance of triggering an objection;
+a strongly positive one has roughly a 30% chance. An objection is therefore
+possible, not guaranteed, for any particular message. If you need to choose
+the sentiment yourself, call `fetch_comments`, set `comment.score` to a negative
+or positive value above 0.5 in magnitude, then pass the comments to
+`objectionengine2.renderer.render_comment_list`. The objection still has a
+random chance of occurring.
+
+## Python API
+
+```python
+from objectionengine2_teams import fetch_comments, render_teams_link
+
+comments = fetch_comments(start_message_url, end_link=end_message_url)
+render_teams_link(start_message_url, "outputs/teams.mp4", end_link=end_message_url)
+```
+
+`fetch_comments` returns `objectionengine2.beans.comment.Comment` objects.
+`render_teams_link` enables Hugging Face sentiment by default for its render.
+Both calls default to broker sign-in. Pass `auth_method="browser"`,
+`auth_method="device-code"`, or `auth_method="cache"` to select another
+method. Later calls reuse cached tokens when valid.
+To inspect messages and render without fetching them twice, use the comments
+with `objectionengine2.renderer.render_comment_list` directly.
+
+## Tests
+
+```bash
+cd ~/development/objectionengine2-teams
+uv run --locked pytest -q
+uv build --no-sources
+```
+
+The default tests use fake Graph responses and Azure Identity credentials. They
+never access a tenant, download assets or models, or render private Teams content. To exercise
+the complete video encoder with local fixture messages, run:
+
+```bash
+uv run --locked pytest -q -m asset_integration
+```
+
+That test calls `objectionengine2.utils.ensure_assets_are_available()` first,
+then renders with default Hugging Face sentiment. It populates the platform
+cache with assets and the model when necessary. A live Teams render still
+requires a link, sign-in, and Graph consent; it cannot be validated by the
+offline suite.

objectionengine2_teams-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+objectionengine2_teams/__init__.py,sha256=xbRHbqbWuQPK7CNLsDPUeYEHuRwrbZPMUuBDVQylO1k,581
+objectionengine2_teams/auth.py,sha256=f6hHzY65R-gecLtn5fry56HEXJ7_dYQZL7ktdkhAsnY,5736
+objectionengine2_teams/cli.py,sha256=h2rFvnKVYavKNU70NM4PU6tCmHwtVuP2rzaLnXbpZPM,2270
+objectionengine2_teams/convert.py,sha256=CXWrdfeezQxiYvBJlr1DJPRhbtpkU9mZCKEtjiq_Uu4,4850
+objectionengine2_teams/graph.py,sha256=TZKcQeBh6ZLfrPlB5z-VUetrr67bjC2nuu4LXc9m5fg,7466
+objectionengine2_teams/links.py,sha256=WHCdpjqVPbZastnkF8Ufrd8CAV7g6nG7PobOiC2nPvQ,4622
+objectionengine2_teams/render.py,sha256=Up4CGFw95GFpeSe_fCAyaiLuF7oSuj9myeFNjcR-oZ0,3962
+objectionengine2_teams-1.0.0.dist-info/licenses/LICENSE,sha256=wGhNQGmqMQ0_rdITtIw5RmIuamyl3dP-KkuFVDkIMR0,1092
+objectionengine2_teams-1.0.0.dist-info/WHEEL,sha256=nQ0eT7mepDP-DkLACRDiCUi7cAIJyLg4OevuC4KpLLY,80
+objectionengine2_teams-1.0.0.dist-info/entry_points.txt,sha256=M_2uhUs-lltWr4rM4BaYJl-y3tx2XX69fHV784_TAhk,76
+objectionengine2_teams-1.0.0.dist-info/METADATA,sha256=NIKe5e7VCxuBJCxOJeAt46yuvziEevghWdeJ7nVVl8g,7473
+objectionengine2_teams-1.0.0.dist-info/RECORD,,

objectionengine2_teams-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.4
+Root-Is-Purelib: true
+Tag: py3-none-any

objectionengine2_teams-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+objectionengine2-teams = objectionengine2_teams.cli:main
+

objectionengine2_teams-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 objectionengine2-teams contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.