teams-transcripts 0.5.0__py3-none-any.whl

teams_transcripts/__init__.py

@@ -0,0 +1 @@
+"""teams_transcripts -- hexagonal architecture for Teams transcript download."""

teams_transcripts/__main__.py

@@ -0,0 +1,288 @@
+"""CLI entry point for the teams_transcripts package.
+
+Usage::
+
+    python -m teams_transcripts --meeting "Weekly Standup" --datetime 2026-04-25
+    python -m teams_transcripts --meeting-id UUID
+    python -m teams_transcripts --list-tenants
+    python -m teams_transcripts --list-transcripts
+    python -m teams_transcripts --list-transcripts 7 --format json
+
+This module is the thin entry point that wires infrastructure (config,
+logging, signals) to the downloader service, the list-tenants command,
+or the list-transcripts command.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+import typing
+
+from teams_transcripts.infrastructure.config import (
+    _format_explicitly_set,
+    parse_args,
+    resolve_config,
+)
+from teams_transcripts.infrastructure.errors import EXIT_BAD_ARGS, exit_error
+from teams_transcripts.infrastructure.logging import Logger
+from teams_transcripts.infrastructure.signals import ShutdownCoordinator
+from teams_transcripts.services.downloader import run_download
+
+if typing.TYPE_CHECKING:
+    from teams_transcripts.adapters.cdp.browser import CdpBrowserAdapter
+    from teams_transcripts.services.tenant import TenantVerification
+
+# Flags that are only relevant in download mode and must be rejected in list modes.
+_DOWNLOAD_ONLY_FLAGS: dict[str, str] = {
+    "--gcp-project": "--gcp-project",
+    "--model": "--model",
+    "--gcp-region": "--gcp-region",
+    "--adc": "--adc",
+    "--dry-run": "--dry-run",
+    "--transcript": "--transcript",
+    "--chat": "--chat",
+    "--metadata": "--metadata",
+}
+
+
+def _check_download_only_flags(mode_flag: str, format_json: bool) -> None:
+    """Reject download-only flags that have no effect in list modes."""
+    for argv_flag, display_name in _DOWNLOAD_ONLY_FLAGS.items():
+        if any(arg == argv_flag or arg.startswith(f"{argv_flag}=") for arg in sys.argv):
+            exit_error(
+                EXIT_BAD_ARGS,
+                "BAD_ARGS",
+                f"{display_name} is incompatible with {mode_flag}.",
+                format_json=format_json,
+            )
+
+
+def main() -> None:
+    """Synchronous entry point for ``python -m teams_transcripts``."""
+    # Show help when invoked with no arguments.
+    if len(sys.argv) <= 1:
+        sys.argv.append("--help")
+
+    args = parse_args()
+
+    # --list-tenants and --list-transcripts are mutually exclusive.
+    if args.list_tenants and args.list_transcripts is not None:
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "--list-tenants and --list-transcripts are mutually exclusive.",
+            format_json=args.output_format == "json",
+        )
+
+    # --list-tenants: separate command path (no MeetingConfig needed)
+    if args.list_tenants:
+        _run_list_tenants(args)
+        return
+
+    # --list-transcripts: separate command path (no MeetingConfig needed)
+    if args.list_transcripts is not None:
+        _run_list_transcripts(args)
+        return
+
+    config = resolve_config(args)
+
+    logger = Logger(quiet=config.quiet, verbose=config.verbose)
+    shutdown = ShutdownCoordinator(format_json=config.format_json)
+    shutdown.install_signal_handlers()
+
+    asyncio.run(run_download(config, logger, shutdown))
+
+
+def _run_list_tenants(args: object) -> None:
+    """Handle the --list-tenants command path.
+
+    Validates flag combinations, then delegates to
+    ``services.tenant.run_list_tenants``.
+    """
+    from teams_transcripts.services.tenant import run_list_tenants
+
+    format_json = args.output_format == "json"  # type: ignore[attr-defined]
+
+    # Incompatible flags
+    if args.meeting is not None:  # type: ignore[attr-defined]
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "--meeting is incompatible with --list-tenants.",
+            format_json=format_json,
+        )
+    if args.meeting_id is not None:  # type: ignore[attr-defined]
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "--meeting-id is incompatible with --list-tenants.",
+            format_json=format_json,
+        )
+    if args.datetime is not None:  # type: ignore[attr-defined]
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "--datetime is incompatible with --list-tenants.",
+            format_json=format_json,
+        )
+    _check_download_only_flags("--list-tenants", format_json)
+
+    logger = Logger(
+        quiet=args.quiet,  # type: ignore[attr-defined]
+        verbose=args.verbose,  # type: ignore[attr-defined]
+    )
+    shutdown = ShutdownCoordinator(format_json=format_json)
+    shutdown.install_signal_handlers()
+
+    asyncio.run(
+        run_list_tenants(
+            args.port,  # type: ignore[attr-defined]
+            logger=logger,
+            shutdown=shutdown,
+            format_json=format_json,
+            output_path=args.output,  # type: ignore[attr-defined]
+            force_restart=getattr(args, "force_restart", False),
+        )
+    )
+
+
+def _run_list_transcripts(args: object) -> None:
+    """Handle the --list-transcripts command path.
+
+    Validates flag combinations, then delegates to
+    ``services.listing.run_list_transcripts``.
+    """
+    from teams_transcripts.adapters.cdp.browser import CdpBrowserAdapter
+    from teams_transcripts.adapters.cdp.helpers import find_teams_targets, verify_cdp
+    from teams_transcripts.adapters.cdp.teams import ensure_teams_running
+    from teams_transcripts.infrastructure.errors import EXIT_CDP_UNAVAILABLE
+    from teams_transcripts.services.listing import run_list_transcripts
+    from teams_transcripts.services.tenant import pick_detection_target
+
+    format_json = args.output_format == "json"  # type: ignore[attr-defined]
+
+    # --format vtt is not valid with --list-transcripts
+    # Only reject if user explicitly passed --format vtt (the argparse default is vtt)
+    if args.output_format == "vtt" and _format_explicitly_set(args):  # type: ignore[attr-defined]
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "--format vtt is not valid with --list-transcripts. "
+            "Use --format json or omit --format for a table.",
+            format_json=False,
+        )
+
+    # Incompatible flags
+    if args.meeting is not None:  # type: ignore[attr-defined]
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "--meeting is incompatible with --list-transcripts.",
+            format_json=format_json,
+        )
+    if args.meeting_id is not None:  # type: ignore[attr-defined]
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "--meeting-id is incompatible with --list-transcripts.",
+            format_json=format_json,
+        )
+    if args.datetime is not None:  # type: ignore[attr-defined]
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "--datetime is incompatible with --list-transcripts.",
+            format_json=format_json,
+        )
+    _check_download_only_flags("--list-transcripts", format_json)
+
+    days = args.list_transcripts  # type: ignore[attr-defined]
+    if days < 1:
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            "--list-transcripts DAYS must be 1 or greater.",
+            format_json=format_json,
+        )
+
+    if not 1 <= args.port <= 65535:  # type: ignore[attr-defined]
+        exit_error(
+            EXIT_BAD_ARGS,
+            "BAD_ARGS",
+            f"Invalid port '{args.port}'. Expected a value from 1 to 65535.",  # type: ignore[attr-defined]
+            format_json=format_json,
+        )
+
+    logger = Logger(
+        quiet=args.quiet,  # type: ignore[attr-defined]
+        verbose=args.verbose,  # type: ignore[attr-defined]
+    )
+    shutdown = ShutdownCoordinator(format_json=format_json)
+    shutdown.install_signal_handlers()
+
+    tenant = args.tenant or os.environ.get("TEAMS_TENANT") or None  # type: ignore[attr-defined]
+    tenant_id: str | None = None
+    if tenant:
+        ensure_teams_running(
+            args.port,  # type: ignore[attr-defined]
+            logger=logger,
+            shutdown=shutdown,
+            format_json=format_json,
+            force=getattr(args, "force_restart", False),
+        )
+        verify_cdp(args.port, logger=logger, shutdown=shutdown, format_json=format_json)  # type: ignore[attr-defined]
+        targets = find_teams_targets(args.port, logger=logger, format_json=format_json)  # type: ignore[attr-defined]
+        if not targets:
+            exit_error(
+                EXIT_CDP_UNAVAILABLE,
+                "NO_TARGETS",
+                "No Teams page targets found via CDP.",
+                step="list-transcripts",
+                format_json=format_json,
+            )
+        browser = CdpBrowserAdapter(port=args.port)  # type: ignore[attr-defined]
+        awaitable = _resolve_tenant_for_list(
+            browser,
+            pick_detection_target(targets),
+            tenant,
+            logger,
+            format_json,
+        )
+        resolved = asyncio.run(awaitable)
+        tenant_id = resolved.tenant_id
+
+    asyncio.run(
+        run_list_transcripts(
+            args.port,  # type: ignore[attr-defined]
+            days=days,
+            logger=logger,
+            shutdown=shutdown,
+            format_json=format_json,
+            output_path=args.output,  # type: ignore[attr-defined]
+            tenant_id=tenant_id,
+            force_restart=getattr(args, "force_restart", False),
+        )
+    )
+
+
+async def _resolve_tenant_for_list(
+    browser: CdpBrowserAdapter,
+    target_id: str,
+    tenant: str,
+    logger: Logger,
+    format_json: bool,
+) -> TenantVerification:
+    """Resolve a list-mode tenant domain to a canonical tenant ID."""
+    from teams_transcripts.services.tenant import resolve_requested_tenant
+
+    await browser.connect(target_id)
+    try:
+        return await resolve_requested_tenant(browser, tenant, logger, format_json=format_json)
+    finally:
+        await browser.disconnect()
+
+
+if __name__ == "__main__":
+    main()

teams_transcripts/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapter implementations -- concrete implementations of port interfaces."""

teams_transcripts/adapters/cdp/__init__.py

@@ -0,0 +1 @@
+"""CDP adapter -- Chrome DevTools Protocol implementation of BrowserPort."""

teams_transcripts/adapters/cdp/browser.py

@@ -0,0 +1,196 @@
+"""CDP browser adapter -- implements BrowserPort using CDP WebSocket.
+
+Wraps low-level CDP operations (navigate, click, evaluate, screenshot,
+type_text) into the BrowserPort protocol interface.
+
+Extracted from ``transcript_download.py`` line 832 (type_text_via_cdp).
+Higher-level operations (navigate_to_meeting, etc.) live in services.
+
+Schema version: 1.0.0
+Created: 2026-04-25
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+
+from teams_transcripts.adapters.cdp.connection import (
+    CDPConnection,
+    WebSocketLike,
+    connect_to_target,
+)
+
+
+class CdpBrowserAdapter:
+    """BrowserPort implementation using Chrome DevTools Protocol.
+
+    Manages a single CDP connection to a browser target.  Methods
+    correspond to the BrowserPort protocol operations.
+
+    Args:
+        port: CDP debugging port number.
+    """
+
+    def __init__(self, port: int) -> None:
+        self._port = port
+        self._ws: WebSocketLike | None = None
+        self._cdp: CDPConnection | None = None
+
+    @property
+    def cdp(self) -> CDPConnection:
+        """The underlying CDPConnection (for direct CDP access in services)."""
+        if self._cdp is None:
+            msg = "Not connected -- call connect() first"
+            raise RuntimeError(msg)
+        return self._cdp
+
+    async def connect(self, target_id: str) -> None:
+        """Open a CDP WebSocket connection to the specified target.
+
+        Args:
+            target_id: CDP target identifier.
+        """
+        self._ws, self._cdp = await connect_to_target(self._port, target_id)
+
+    async def disconnect(self) -> None:
+        """Close the current WebSocket connection."""
+        if self._ws is not None:
+            await self._ws.close()
+            self._ws = None
+            self._cdp = None
+
+    async def evaluate(self, expression: str, *, timeout: float = 15) -> object:
+        """Evaluate JavaScript in the connected target.
+
+        Args:
+            expression: JavaScript source to evaluate.
+            timeout: Maximum seconds to wait.
+
+        Returns:
+            The evaluated value.
+        """
+        return await self.cdp.evaluate(expression, timeout=timeout)
+
+    async def send_command(
+        self,
+        method: str,
+        params: dict | None = None,
+        *,
+        timeout: float = 15,
+    ) -> dict:
+        """Send a raw CDP command.
+
+        Args:
+            method: CDP method name.
+            params: CDP method parameters.
+            timeout: Maximum seconds to wait.
+
+        Returns:
+            The full CDP response dict.
+        """
+        return await self.cdp.send(method, params, timeout=timeout)
+
+    async def navigate(self, url: str, *, timeout: float = 30) -> None:
+        """Navigate to a URL.
+
+        Args:
+            url: Destination URL.
+            timeout: Maximum seconds to wait for navigation.
+        """
+        await self.cdp.send("Page.navigate", {"url": url}, timeout=timeout)
+
+    async def click(self, selector: str, *, timeout: float = 10) -> bool:
+        """Click the first element matching a CSS selector.
+
+        Uses JavaScript ``querySelector`` + ``click()`` rather than
+        CDP Input events for reliability.
+
+        Args:
+            selector: CSS selector string.
+            timeout: Maximum seconds to wait.
+
+        Returns:
+            ``True`` if the click succeeded.
+        """
+        js = f"""
+        (function() {{
+            var el = document.querySelector({selector!r});
+            if (!el) return false;
+            el.click();
+            return true;
+        }})()
+        """
+        result = await self.cdp.evaluate(js, timeout=timeout)
+        return result is True
+
+    async def type_text(self, text: str, *, delay_ms: int = 50) -> None:
+        """Type text character by character using CDP Input events.
+
+        Simulates keyDown/keyUp events for each character.
+
+        Args:
+            text: Text to type.
+            delay_ms: Milliseconds between keystrokes.
+        """
+        delay_sec = delay_ms / 1000.0
+        for char in text:
+            await self.cdp.send(
+                "Input.dispatchKeyEvent",
+                {
+                    "type": "keyDown",
+                    "text": char,
+                    "key": char,
+                    "code": f"Key{char.upper()}" if char.isalpha() else "",
+                    "windowsVirtualKeyCode": (ord(char.upper()) if char.isalpha() else ord(char)),
+                },
+            )
+            await self.cdp.send(
+                "Input.dispatchKeyEvent",
+                {
+                    "type": "keyUp",
+                    "key": char,
+                    "code": f"Key{char.upper()}" if char.isalpha() else "",
+                    "windowsVirtualKeyCode": (ord(char.upper()) if char.isalpha() else ord(char)),
+                },
+            )
+            await asyncio.sleep(delay_sec)
+
+    async def screenshot(self, *, image_format: str = "png") -> bytes:
+        """Capture a screenshot.
+
+        Args:
+            image_format: Image format (``"png"`` or ``"jpeg"``).
+
+        Returns:
+            Raw image bytes.
+        """
+        b64_data = await self.cdp.screenshot()
+        return base64.b64decode(b64_data)
+
+    async def wait_for_selector(
+        self,
+        selector: str,
+        *,
+        timeout: float = 10,
+    ) -> bool:
+        """Wait for an element to appear in the DOM.
+
+        Polls every 200ms until the selector matches or timeout expires.
+
+        Args:
+            selector: CSS selector string.
+            timeout: Maximum seconds to wait.
+
+        Returns:
+            ``True`` if found, ``False`` on timeout.
+        """
+        elapsed = 0.0
+        interval = 0.2
+        while elapsed < timeout:
+            result = await self.cdp.evaluate(f"!!document.querySelector({selector!r})")
+            if result is True:
+                return True
+            await asyncio.sleep(interval)
+            elapsed += interval
+        return False

teams_transcripts/adapters/cdp/connection.py

@@ -0,0 +1,168 @@
+"""CDP WebSocket connection management.
+
+Provides the :class:`CDPConnection` class for sending CDP commands over
+a WebSocket, and the :func:`connect_to_target` helper for establishing
+new connections.
+
+Extracted from ``transcript_download.py`` lines 595-648.
+
+Schema version: 1.0.0
+Created: 2026-04-25
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import typing
+
+import websockets
+
+if typing.TYPE_CHECKING:
+    import types
+
+
+class CDPError(RuntimeError):
+    """Raised when CDP returns a command error or JavaScript exception."""
+
+    def __init__(self, details: object) -> None:
+        super().__init__(f"CDP command failed: {details}")
+        self.details = details
+
+
+@typing.runtime_checkable
+class WebSocketLike(typing.Protocol):
+    """Minimal WebSocket interface used by CDPConnection.
+
+    Both ``websockets.ClientConnection`` and test fakes satisfy this
+    protocol structurally -- no inheritance required.
+
+    Parameter names use positional-only syntax so the protocol does
+    not enforce specific parameter names on implementations.
+    """
+
+    async def send(self, message: str, /) -> None: ...
+    async def recv(self, /) -> str | bytes: ...
+    async def close(self, /) -> None: ...
+
+    async def __aenter__(self) -> WebSocketLike: ...
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: types.TracebackType | None,
+        /,
+    ) -> None: ...
+
+
+class CDPConnection:
+    """Manages a CDP WebSocket connection with message ID tracking.
+
+    Wraps a WebSocket instance satisfying :class:`WebSocketLike`, providing:
+
+    * Auto-incrementing message IDs for request/response correlation.
+    * Convenience methods for common CDP operations (evaluate, screenshot).
+    * Message draining to clear stale events from the receive buffer.
+
+    Args:
+        ws: An open WebSocket connection.
+    """
+
+    def __init__(self, ws: WebSocketLike) -> None:
+        self._ws = ws
+        self._msg_id = 0
+
+    async def send(
+        self,
+        method: str,
+        params: dict | None = None,
+        timeout: float = 15,
+    ) -> dict:
+        """Send a CDP command and wait for the matching response.
+
+        Args:
+            method: CDP method name (e.g. ``"Runtime.evaluate"``).
+            params: CDP method parameters.  Defaults to empty dict.
+            timeout: Maximum seconds to wait for the response.
+
+        Returns:
+            The full CDP response dict (contains ``id`` and ``result``
+            or ``error``).
+        """
+        self._msg_id += 1
+        mid = self._msg_id
+        await self._ws.send(
+            json.dumps(
+                {
+                    "id": mid,
+                    "method": method,
+                    "params": params or {},
+                }
+            )
+        )
+        while True:
+            raw = await asyncio.wait_for(self._ws.recv(), timeout=timeout)
+            data = json.loads(raw)
+            if "id" in data and data["id"] == mid:
+                if "error" in data:
+                    raise CDPError(data["error"])
+                return data
+
+    async def evaluate(self, expression: str, timeout: float = 15) -> object:
+        """Evaluate a JavaScript expression via ``Runtime.evaluate``.
+
+        Args:
+            expression: JavaScript source to evaluate.
+            timeout: Maximum seconds to wait for a result.
+
+        Returns:
+            The evaluated value (primitive, dict, list, or ``None``).
+        """
+        resp = await self.send(
+            "Runtime.evaluate",
+            {"expression": expression},
+            timeout=timeout,
+        )
+        if resp.get("result", {}).get("exceptionDetails"):
+            raise CDPError(resp["result"]["exceptionDetails"])
+        return resp.get("result", {}).get("result", {}).get("value")
+
+    async def drain(self, timeout: float = 0.5) -> None:
+        """Drain any pending messages from the WebSocket.
+
+        Useful after navigation or other operations that produce
+        unsolicited CDP events.
+
+        Args:
+            timeout: Seconds to wait for each message before assuming
+                the buffer is empty.
+        """
+        try:
+            while True:
+                await asyncio.wait_for(self._ws.recv(), timeout=timeout)
+        except (asyncio.TimeoutError, TimeoutError):
+            pass
+
+    async def screenshot(self) -> str:
+        """Take a screenshot via CDP.
+
+        Returns:
+            Base64-encoded PNG image data.
+        """
+        resp = await self.send("Page.captureScreenshot", {"format": "png"})
+        return resp.get("result", {}).get("data", "")
+
+
+async def connect_to_target(port: int, target_id: str) -> tuple[WebSocketLike, CDPConnection]:
+    """Connect to a CDP target via WebSocket.
+
+    Args:
+        port: CDP debugging port number.
+        target_id: CDP target identifier.
+
+    Returns:
+        A tuple of ``(websocket, CDPConnection)``.
+    """
+    ws_url = f"ws://127.0.0.1:{port}/devtools/page/{target_id}"
+    ws = await websockets.connect(ws_url, max_size=16 * 1024 * 1024)
+    return ws, CDPConnection(ws)