teams-transcripts 0.5.0__py3-none-any.whl

teams_transcripts/domain/mcps.py

@@ -0,0 +1,343 @@
+"""MCPS response parsing and artifact formatting.
+
+Pure functions for converting raw MCPS API responses into domain objects
+and formatting them for display (text table or JSON).
+
+The MCPS (Meeting Content and Presence Service) API returns meeting
+artifacts via ``startListArtifactsByUserWorkflow``.  This module handles
+the response structure:
+
+.. code-block:: json
+
+    {
+      "value": [
+        {
+          "threadInfo": {
+            "subject": "...",
+            "threadId": "19:meeting_...",
+            "callId": "...",
+            "iCalUid": "..."
+          },
+          "resources": [
+            {"type": "TranscriptV2", "location": "https://..."},
+            {"type": "Recording", "location": "https://..."}
+          ]
+        }
+      ],
+      "paginationInfo": {"hasNextPage": true, "skipToken": "..."}
+    }
+
+Public API:
+    extract_meeting_id(thread_id) -> str
+    build_thread_id(meeting_id) -> str
+    parse_mcps_response(raw, query_date) -> list[MeetingArtifact]
+    format_artifacts_table(artifacts) -> str
+    format_artifacts_json(artifacts) -> str
+
+Schema version: 2.0.0
+Created: 2026-04-28
+Updated: 2026-05-01
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import typing
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+
+if typing.TYPE_CHECKING:
+    import datetime as dt
+
+from teams_transcripts.domain.models import MeetingArtifact
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# MCPS response Pydantic models
+# ---------------------------------------------------------------------------
+
+
+class McpsResourceMetadata(BaseModel):
+    """Metadata block within an MCPS resource entry."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    web_url: str = Field(default="", alias="webUrl")
+
+
+class McpsResource(BaseModel):
+    """A single resource (transcript or recording) within an MCPS entry."""
+
+    model_config = ConfigDict(extra="allow")
+
+    type: str = ""
+    location: str = ""
+    metadata: McpsResourceMetadata | None = None
+
+
+class McpsThreadInfo(BaseModel):
+    """Thread information for an MCPS meeting entry.
+
+    The MCPS API may return ``null`` for any string field.  The
+    before-mode validator coerces nulls to empty strings so downstream
+    code can rely on ``str`` types without null checks.
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    subject: str = ""
+    thread_id: str = Field(default="", alias="threadId")
+    call_id: str = Field(default="", alias="callId")
+    ical_uid: str = Field(default="", alias="iCalUid")
+
+    @field_validator("subject", "thread_id", "call_id", "ical_uid", mode="before")
+    @classmethod
+    def _coerce_null_to_empty(cls, v: str | None) -> str:
+        """Coerce ``None`` (JSON null) to empty string."""
+        return v if v is not None else ""
+
+
+class McpsEntry(BaseModel):
+    """A single meeting entry in the MCPS response value array."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    thread_info: McpsThreadInfo = Field(default_factory=McpsThreadInfo, alias="threadInfo")
+    resources: list[McpsResource] = []
+
+
+class McpsResponse(BaseModel):
+    """Top-level MCPS API response from startListArtifactsByUserWorkflow."""
+
+    model_config = ConfigDict(extra="allow")
+
+    value: list[McpsEntry] = []
+
+
+def extract_meeting_id(thread_id: str) -> str:
+    """Extract a short meeting ID from a Teams thread_id.
+
+    Thread IDs have the format ``19:meeting_<BASE64>@thread.v2`` where
+    the base64 segment decodes to a UUID.  This function extracts and
+    returns that UUID.  If the format is unexpected, returns a truncated
+    form of the thread_id.
+
+    Args:
+        thread_id: The full thread ID string.
+
+    Returns:
+        A UUID string (36 chars) or a fallback short identifier.
+    """
+    if not thread_id:
+        return ""
+    try:
+        # Extract base64 segment: 19:meeting_<B64>@thread.v2
+        if "_" in thread_id and "@" in thread_id:
+            b64 = thread_id.split("_", 1)[1].rsplit("@", 1)[0]
+            # Pad for base64 decoding (add missing chars to reach multiple of 4)
+            remainder = len(b64) % 4
+            if remainder:
+                b64 += "=" * (4 - remainder)
+            # Use urlsafe_b64decode which accepts both standard base64
+            # (+ and /) and URL-safe base64 (- and _).  Teams may use
+            # either variant depending on client version/region.
+            return base64.urlsafe_b64decode(b64).decode("utf-8")
+    except Exception:  # noqa: S110
+        pass
+    # Fallback: return first 36 chars of thread_id
+    return thread_id[:36]
+
+
+def build_thread_id(meeting_id: str) -> str:
+    """Reconstruct a full Teams thread_id from a meeting UUID.
+
+    Inverse of :func:`extract_meeting_id`.  Encodes the UUID as base64
+    and wraps it in the ``19:meeting_<BASE64>@thread.v2`` format.
+
+    Args:
+        meeting_id: A UUID string (e.g. ``2b4c1f5c-636d-4d78-a087-c2cbf3887fd8``).
+
+    Returns:
+        The full thread_id string.
+
+    Raises:
+        ValueError: If meeting_id is empty.
+    """
+    if not meeting_id:
+        msg = "meeting_id must not be empty"
+        raise ValueError(msg)
+    # Encode UUID to base64, strip padding
+    encoded = base64.b64encode(meeting_id.encode("utf-8")).decode("utf-8").rstrip("=")
+    return f"19:meeting_{encoded}@thread.v2"
+
+
+def parse_mcps_response(raw: dict, query_date: dt.date) -> list[MeetingArtifact]:
+    """Parse a raw MCPS response into a list of MeetingArtifact objects.
+
+    Validates the response structure via :class:`McpsResponse`, then
+    extracts transcript/recording information from typed resource objects.
+
+    Args:
+        raw: The raw JSON response dict from
+            ``startListArtifactsByUserWorkflow``.
+        query_date: The date that was queried (used as the artifact date
+            since the API does not return meeting start times reliably).
+
+    Returns:
+        A list of :class:`MeetingArtifact` instances.  Empty list if
+        ``raw`` has no ``value`` key, it is empty, or validation fails.
+    """
+    try:
+        response = McpsResponse.model_validate(raw)
+    except ValidationError:
+        logger.debug("MCPS response failed validation", exc_info=True)
+        return []
+
+    if not response.value:
+        return []
+
+    artifacts: list[MeetingArtifact] = []
+    for entry in response.value:
+        has_transcript = False
+        has_recording = False
+        transcript_url: str | None = None
+        recording_url: str | None = None
+
+        for resource in entry.resources:
+            meta = resource.metadata or McpsResourceMetadata()
+            if resource.type == "TranscriptV2":
+                has_transcript = True
+                transcript_url = resource.location or None
+                # When a recording exists, the TranscriptV2 resource
+                # includes the recording URL in metadata.webUrl
+                if meta.web_url:
+                    has_recording = True
+                    recording_url = meta.web_url
+            elif resource.type == "Recording":
+                has_recording = True
+                recording_url = resource.location or meta.web_url or None
+
+        artifact = MeetingArtifact(
+            subject=entry.thread_info.subject or "(unnamed)",
+            thread_id=entry.thread_info.thread_id,
+            call_id=entry.thread_info.call_id,
+            ical_uid=entry.thread_info.ical_uid,
+            date=query_date,
+            has_transcript=has_transcript,
+            has_recording=has_recording,
+            transcript_url=transcript_url,
+            recording_url=recording_url,
+        )
+        artifacts.append(artifact)
+
+    return artifacts
+
+
+def format_artifacts_table(artifacts: list[MeetingArtifact]) -> str:
+    """Format a list of meeting artifacts as a plain-text table.
+
+    Produces a fixed-width table with columns: Date, Subject, T (transcript
+    indicator), R (recording indicator), ID (meeting UUID), and optionally
+    Call ID (shown when at least one artifact has a non-empty call_id).
+
+    The Call ID column enables ``--call-id`` targeting for unambiguous
+    occurrence selection in recurring meeting series.
+
+    Args:
+        artifacts: List of artifacts to format (should be pre-sorted).
+
+    Returns:
+        Formatted table string (no trailing newline).  Returns a
+        "No meetings found" message if the list is empty.
+    """
+    if not artifacts:
+        return "No meetings with transcripts found."
+
+    # Determine whether to show the Call ID column
+    has_call_ids = any(a.call_id for a in artifacts)
+
+    # Compute column widths
+    date_width = 10  # YYYY-MM-DD
+    id_width = 36  # UUID
+    # Subject column: minimum 7 ("Subject"), max 48 (reduced to fit ID)
+    max_subject = max(len(a.subject) for a in artifacts)
+    subject_width = min(max(max_subject, 7), 48)
+
+    # Call ID width: sized to longest value (minimum 7 for "Call ID" header)
+    if has_call_ids:
+        max_call_id = max((len(a.call_id) for a in artifacts if a.call_id), default=7)
+        call_id_width = max(max_call_id, 7)
+    else:
+        call_id_width = 0
+
+    # Header
+    header = (
+        f"{'Date':<{date_width}}  "
+        f"{'Subject':<{subject_width}}  "
+        f"{'T':>1}  {'R':>1}  "
+        f"{'ID':<{id_width}}"
+    )
+    separator = f"{'-' * date_width}  {'-' * subject_width}  {'-':>1}  {'-':>1}  {'-' * id_width}"
+    if has_call_ids:
+        header += f"  {'Call ID':<{call_id_width}}"
+        separator += f"  {'-' * call_id_width}"
+
+    lines = [header, separator]
+    for a in artifacts:
+        subject_display = a.subject[:subject_width]
+        t_indicator = "Y" if a.has_transcript else "-"
+        r_indicator = "Y" if a.has_recording else "-"
+        meeting_id = extract_meeting_id(a.thread_id)
+        line = (
+            f"{a.date.isoformat():<{date_width}}  "
+            f"{subject_display:<{subject_width}}  "
+            f"{t_indicator:>1}  "
+            f"{r_indicator:>1}  "
+            f"{meeting_id:<{id_width}}"
+        )
+        if has_call_ids:
+            call_id_display = a.call_id or "-"
+            line += f"  {call_id_display:<{call_id_width}}"
+        lines.append(line)
+
+    # Footer with count
+    lines.append("")
+    lines.append(f"{len(artifacts)} meeting(s) found.")
+
+    return "\n".join(lines)
+
+
+def format_artifacts_json(artifacts: list[MeetingArtifact]) -> str:
+    """Format a list of meeting artifacts as a JSON array.
+
+    Each artifact is serialised as a dict with all fields.  The ``date``
+    field is ISO-formatted.
+
+    Args:
+        artifacts: List of artifacts to format.
+
+    Returns:
+        Pretty-printed JSON string.
+    """
+    entries = []
+    for a in artifacts:
+        entry = {
+            "subject": a.subject,
+            "date": a.date.isoformat(),
+            "thread_id": a.thread_id,
+            "call_id": a.call_id,
+            "ical_uid": a.ical_uid,
+            "has_transcript": a.has_transcript,
+            "has_recording": a.has_recording,
+        }
+        if a.transcript_url:
+            entry["transcript_url"] = a.transcript_url
+        if a.recording_url:
+            entry["recording_url"] = a.recording_url
+        entries.append(entry)
+
+    return json.dumps(entries, indent=2)