teams-transcripts 0.5.0__py3-none-any.whl

teams_transcripts/adapters/cdp/helpers.py

@@ -0,0 +1,449 @@
+"""CDP HTTP helpers and target discovery.
+
+Provides functions for interacting with CDP's HTTP endpoints and
+discovering specific browser targets (Teams pages, SharePoint iframes).
+
+Extracted from ``transcript_download.py`` lines 580-588 (cdp_http_get),
+793-809 (find_teams_targets), 817-829 (find_search_target),
+768-785 (verify_cdp), 1897-1908 (find_xplatplugins_targets),
+1911-1993 (find_iframe_target).
+
+Functions that were both I/O and filtering have been split:
+* Pure filtering: ``filter_teams_targets``, ``filter_xplatplugins_targets``
+* I/O orchestrators: ``find_teams_targets``, ``find_xplatplugins_targets``,
+  ``find_search_target``, ``find_iframe_target``, ``verify_cdp``
+
+Schema version: 1.0.0
+Created: 2026-04-25
+"""
+
+from __future__ import annotations
+
+import json
+import typing
+import urllib.request
+
+from teams_transcripts.adapters.cdp.connection import connect_to_target
+from teams_transcripts.infrastructure.errors import (
+    EXIT_CDP_UNAVAILABLE,
+    EXIT_DOWNLOAD_FAILED,
+    exit_error,
+)
+
+if typing.TYPE_CHECKING:
+    from teams_transcripts.domain.models import MeetingConfig
+    from teams_transcripts.infrastructure.logging import Logger
+    from teams_transcripts.infrastructure.signals import ShutdownCoordinator
+
+
+# ---------------------------------------------------------------------------
+# HTTP helpers
+# ---------------------------------------------------------------------------
+
+
+def cdp_http_get(port: int, path: str) -> dict | list | None:
+    """GET a CDP HTTP endpoint, return parsed JSON or ``None`` on failure.
+
+    Only connects to 127.0.0.1 -- the URL is constructed internally and
+    never from external input.
+
+    Args:
+        port: CDP debugging port number.
+        path: URL path (e.g. ``"/json/version"``).
+
+    Returns:
+        Parsed JSON (dict or list), or ``None`` if the request failed.
+
+    Raises:
+        ValueError: If *port* is not in the valid range or *path* does
+            not start with ``/``.
+    """
+    if not (1 <= port <= 65535):
+        msg = f"Port out of range: {port}"
+        raise ValueError(msg)
+    if not path.startswith("/"):
+        msg = f"Path must start with '/': {path!r}"
+        raise ValueError(msg)
+    url = f"http://127.0.0.1:{port}{path}"
+    try:
+        with urllib.request.urlopen(url, timeout=5) as resp:  # noqa: S310 -- localhost only
+            return json.loads(resp.read())
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Target filtering (pure)
+# ---------------------------------------------------------------------------
+
+
+def filter_teams_targets(targets: list[dict]) -> list[dict]:
+    """Filter a target list to main Teams v2 page targets.
+
+    Excludes service workers and other non-page targets.
+
+    Args:
+        targets: Raw CDP target list from ``/json``.
+
+    Returns:
+        Filtered list of Teams page targets.
+    """
+    results = []
+    for t in targets:
+        url = t.get("url", "")
+        is_teams_v2 = "teams.microsoft.com/v2" in url
+        is_teams_live = "teams.live.com/v2" in url
+        is_m365_chat = "microsoft365.com/chat" in url
+        is_page = "worker" not in url
+        if (is_teams_v2 or is_teams_live or is_m365_chat) and is_page:
+            results.append(t)
+    return results
+
+
+def filter_xplatplugins_targets(targets: list[dict]) -> list[dict]:
+    """Filter a target list to SharePoint transcript iframe targets.
+
+    Matches targets whose URL contains both ``sharepoint`` and
+    ``xplatplugins``.  This is the only pattern observed in production
+    for the Teams transcript viewer iframe (hosted at
+    ``/_layouts/15/xplatplugins.aspx``).
+
+    The filter is deliberately narrow to avoid false positives from
+    other SharePoint iframes (SPFx portals, OneDrive file browser,
+    Stream embeds, etc.) which would cause iframe disambiguation
+    failures.
+
+    Args:
+        targets: Raw CDP target list from ``/json``.
+
+    Returns:
+        Filtered list of SharePoint transcript iframe targets.
+    """
+    matches = []
+    for t in targets:
+        url = t.get("url", "")
+        if "sharepoint" in url and "xplatplugins" in url:
+            matches.append(t)
+    return matches
+
+
+def filter_worker_targets(targets: list[dict], tenant_id: str | None = None) -> list[dict]:
+    """Filter a target list to Teams precompiled web worker targets.
+
+    Workers are the per-tenant background threads that host the GraphQL
+    handlers, MCPS workflow starters, and token acquisition services.
+    They have ``type: "worker"`` in the CDP target list and a URL
+    containing ``precompiled-web-worker``.
+
+    Args:
+        targets: Raw CDP target list from ``/json``.
+        tenant_id: Optional tenant ID to prefer.  When provided,
+            workers whose URL contains this tenant ID are returned
+            first, followed by other matching workers.
+
+    Returns:
+        Filtered list of worker target dicts, ordered by tenant
+        match preference (tenant-matching first).
+    """
+    tenant_matches = []
+    other_matches = []
+    for t in targets:
+        url = t.get("url", "")
+        target_type = t.get("type", "")
+        is_worker = "precompiled-web-worker" in url or target_type == "other"
+        if not is_worker:
+            continue
+        if tenant_id and tenant_id in url:
+            tenant_matches.append(t)
+        else:
+            other_matches.append(t)
+    return tenant_matches + other_matches
+
+
+# ---------------------------------------------------------------------------
+# I/O orchestrators
+# ---------------------------------------------------------------------------
+
+
+def find_teams_targets(
+    port: int,
+    *,
+    logger: Logger,
+    format_json: bool,
+) -> list[dict]:
+    """Discover main Teams page targets via CDP HTTP.
+
+    Calls ``cdp_http_get`` and filters the result.  Exits with
+    ``CDP_UNAVAILABLE`` if no targets can be listed.
+
+    Args:
+        port: CDP debugging port.
+        logger: Logger instance.
+        format_json: Whether to format errors as JSON.
+
+    Returns:
+        List of Teams page target dicts.
+    """
+    raw_targets = cdp_http_get(port, "/json")
+    if not raw_targets or not isinstance(raw_targets, list):
+        exit_error(
+            EXIT_CDP_UNAVAILABLE,
+            "CDP_UNAVAILABLE",
+            "Could not list CDP targets.",
+            step="step3",
+            format_json=format_json,
+        )
+
+    return filter_teams_targets(raw_targets)
+
+
+def find_worker_targets(
+    port: int,
+    *,
+    logger: Logger,
+    tenant_id: str | None = None,
+) -> list[dict]:
+    """Discover Teams web worker targets via CDP HTTP.
+
+    Args:
+        port: CDP debugging port.
+        logger: Logger instance.
+        tenant_id: Optional tenant ID to filter workers by.
+
+    Returns:
+        List of worker target dicts (may be empty).
+    """
+    raw_targets = cdp_http_get(port, "/json")
+    if not raw_targets or not isinstance(raw_targets, list):
+        return []
+    workers = filter_worker_targets(raw_targets, tenant_id=tenant_id)
+    logger.log("list-transcripts", f"Found {len(workers)} worker target(s)")
+    return workers
+
+
+def find_xplatplugins_targets_io(port: int) -> list[dict]:
+    """Discover xplatplugins iframe targets via CDP HTTP.
+
+    Args:
+        port: CDP debugging port.
+
+    Returns:
+        List of xplatplugins target dicts (may be empty).
+    """
+    raw_targets = cdp_http_get(port, "/json")
+    if not raw_targets or not isinstance(raw_targets, list):
+        return []
+    return filter_xplatplugins_targets(raw_targets)
+
+
+def _search_target_sort_key(target: dict) -> tuple[int, str]:
+    """Sort key that prioritises the primary Teams page over tenant pages.
+
+    The primary Teams page (titled ``"Microsoft Teams"``) is the most
+    stable target for keyboard-driven navigation.  Tenant-specific
+    pages (e.g. ``"Central Hub | insidemedia.net"``) can navigate away
+    when ``Ctrl+3`` is sent, destroying the WebSocket connection.
+
+    Returns a ``(priority, title)`` tuple so targets with the same
+    priority are ordered alphabetically by title for determinism.
+    """
+    title = target.get("title", "")
+    if title == "Microsoft Teams":
+        return (0, title)
+    return (1, title)
+
+
+async def find_search_target(
+    port: int,
+    targets: list[dict],
+    *,
+    logger: Logger,
+) -> str | None:
+    """Find which CDP target has the Teams search input element.
+
+    Targets are checked in priority order: pages titled
+    ``"Microsoft Teams"`` are tried first because they are the most
+    stable target for subsequent keyboard navigation.
+
+    Args:
+        port: CDP debugging port.
+        targets: List of candidate target dicts.
+        logger: Logger instance.
+
+    Returns:
+        The target ID with the search input, or ``None``.
+    """
+    sorted_targets = sorted(targets, key=_search_target_sort_key)
+    for t in sorted_targets:
+        target_id = await _check_target_has_search(port, t, logger)
+        if target_id is not None:
+            logger.log("step4", f"Search input found on target: {target_id[:20]}...")
+            return target_id
+    return None
+
+
+async def _check_target_has_search(port: int, target: dict, logger: Logger) -> str | None:
+    """Check whether a single CDP target contains the search input.
+
+    Returns the target ID if found, ``None`` otherwise.  Connection
+    failures and timeouts are logged and treated as "not found".
+    """
+    try:
+        ws, cdp = await connect_to_target(port, target["id"])
+        async with ws:
+            result = await cdp.evaluate("!!document.querySelector('#ms-searchux-input')")
+            if result is True:
+                return target["id"]
+    except Exception as exc:
+        logger.log("step4", f"Target {target['id'][:20]}... check failed: {exc}")
+    return None
+
+
+def verify_cdp(
+    port: int,
+    *,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+    format_json: bool,
+) -> str:
+    """Verify CDP is responding and return the browser version string.
+
+    Retries up to 5 times with 3-second intervals.  Exits with
+    ``CDP_UNAVAILABLE`` if all attempts fail.
+
+    Args:
+        port: CDP debugging port.
+        logger: Logger instance.
+        shutdown: Shutdown coordinator for interruptibility.
+        format_json: Whether to format errors as JSON.
+
+    Returns:
+        Browser version string (e.g. ``"Chrome/123.0.6312.86"``).
+    """
+    for attempt in range(5):
+        shutdown.check_shutdown()
+        version = cdp_http_get(port, "/json/version")
+        if isinstance(version, dict) and "Browser" in version:
+            browser = version["Browser"]
+            logger.log("step2", f"CDP verified: {browser}")
+            return browser
+        logger.log("step2", f"Attempt {attempt + 1}/5 -- waiting...")
+        shutdown.interruptible_sleep_sync(3)
+
+    # exit_error calls sys.exit (typed NoReturn) -- unreachable beyond this point
+    exit_error(
+        EXIT_CDP_UNAVAILABLE,
+        "CDP_UNAVAILABLE",
+        "CDP did not respond after 5 attempts. Check Teams is running.",
+        step="step2",
+        format_json=format_json,
+    )
+    raise SystemExit(EXIT_CDP_UNAVAILABLE)
+
+
+def find_iframe_target(
+    port: int,
+    *,
+    config: MeetingConfig,
+    agent_client: typing.Any,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+    pre_nav_iframe_ids: set[str] | None = None,
+    allow_missing: bool = False,
+) -> str | None:
+    """Find the correct xplatplugins iframe target.
+
+    Uses the LLM agent if multiple candidates are found and
+    disambiguation is needed.  Falls back to the most recent target.
+
+    Args:
+        port: CDP debugging port.
+        config: Meeting configuration.
+        agent_client: Vertex AI agent client.
+        logger: Logger instance.
+        shutdown: Shutdown coordinator.
+        pre_nav_iframe_ids: Set of iframe target IDs that existed
+            before navigation (to prefer newly created targets).
+        allow_missing: When ``True``, return ``None`` instead of
+            calling :func:`exit_error` when no targets are found.
+            Used by the multi-part download loop to retry navigation
+            rather than hard-exiting.
+
+    Returns:
+        The selected target ID, or ``None`` when *allow_missing* is
+        set and no targets were found.
+    """
+    from teams_transcripts.adapters.vertex import agent_text_query
+
+    logger.log("step6", "Looking for transcript iframe target...")
+    pre_nav_iframe_ids = pre_nav_iframe_ids or set()
+
+    # Retry as the iframe may still be loading
+    matches: list[dict] = []
+    new_matches: list[dict] = []
+    for attempt in range(10):
+        shutdown.check_shutdown()
+        matches = find_xplatplugins_targets_io(port)
+        new_matches = [t for t in matches if t["id"] not in pre_nav_iframe_ids]
+        if new_matches:
+            break
+        if matches and attempt >= 5:
+            logger.log("step6", "No new iframe targets appeared. Using existing targets.")
+            new_matches = matches
+            break
+        label = "new iframe" if matches else "any iframe"
+        logger.log("step6", f"Waiting for {label} target (attempt {attempt + 1}/10)...")
+        shutdown.interruptible_sleep_sync(2)
+
+    candidates = new_matches or matches
+
+    if not candidates:
+        if allow_missing:
+            logger.log("step6", "No iframe targets found (will retry).")
+            return None
+        exit_error(
+            EXIT_DOWNLOAD_FAILED,
+            "IFRAME_NOT_FOUND",
+            "No xplatplugins iframe target found. "
+            "Check that Step 5 completed and the Transcript tab loaded.",
+            step="step6",
+            format_json=config.format_json,
+        )
+
+    if len(candidates) == 1:
+        tid = candidates[0]["id"]
+        is_new = tid not in pre_nav_iframe_ids
+        logger.log("step6", f"{'New' if is_new else 'Existing'} iframe target: {tid[:20]}...")
+        return tid
+
+    # Multiple targets -- ask the agent
+    logger.log("step6", f"{len(candidates)} iframe targets to choose from. Asking agent...")
+
+    target_list = "\n".join(
+        f"  [{i}] ID: {t['id']}, URL: {t['url'][:200]}" for i, t in enumerate(candidates)
+    )
+    prompt = (
+        f"Multiple SharePoint iframe targets were found in a Teams CDP session. "
+        f"I am looking for the transcript of the meeting "
+        f"'{config.meeting}' on {config.date}.\n\n"
+        f"Targets:\n{target_list}\n\n"
+        f"Which target most likely corresponds to this meeting? "
+        f"Look at the URL paths for clues (e.g., organiser name, meeting context). "
+        f'Return JSON: {{"target_id": "<full target ID>"}} '
+        f"for the best match."
+    )
+
+    result = agent_text_query(agent_client, config.model, prompt, logger=logger)
+
+    if result and result.get("target_id"):
+        for t in candidates:
+            if t["id"] == result["target_id"]:
+                logger.log("step6", f"Agent selected target: {t['id'][:20]}...")
+                return t["id"]
+        for t in candidates:
+            if result["target_id"] in t["id"] or t["id"] in result["target_id"]:
+                logger.log("step6", f"Agent selected target (partial match): {t['id'][:20]}...")
+                return t["id"]
+
+    logger.log("step6", "Agent could not disambiguate. Using most recent target.")
+    return candidates[-1]["id"]