lumera 0.4.6__py3-none-any.whl → 0.9.4__py3-none-any.whl

lumera/automations.py

@@ -0,0 +1,904 @@
+"""
+Automation execution and management for Lumera.
+
+This module provides a high-level interface for running and managing Lumera
+automations (background Python scripts).
+
+Run functions:
+    run()                - Run an automation by ID
+    run_by_external_id() - Run an automation by external_id
+    get_run()            - Get a run by ID
+    list_runs()          - List runs for an automation
+
+Automation management:
+    list()               - List all automations
+    get()                - Get automation by ID
+    get_by_external_id() - Get automation by external_id
+    create()             - Create a new automation
+    update()             - Update an automation
+    upsert()             - Create or update by external_id
+
+Log streaming:
+    stream_logs()        - Stream live logs from a running automation
+
+Example:
+    >>> from lumera import automations
+    >>>
+    >>> # Run an automation
+    >>> run = automations.run("automation_id", inputs={"limit": 100})
+    >>> print(run.id, run.status)
+    >>>
+    >>> # Wait for completion
+    >>> result = run.wait(timeout=300)
+    >>>
+    >>> # Or poll manually
+    >>> while run.status in ["queued", "running"]:
+    ...     time.sleep(5)
+    ...     run.refresh()
+    >>> print(run.result)
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Iterator, Mapping
+
+__all__ = [
+    # Run operations
+    "run",
+    "run_by_external_id",
+    "get_run",
+    "list_runs",
+    # Automation management
+    "list",
+    "get",
+    "get_by_external_id",
+    "create",
+    "update",
+    "upsert",
+    # Log streaming and download
+    "stream_logs",
+    "get_log_download_url",
+    # Classes
+    "Run",
+    "Automation",
+]
+
+from ._utils import LumeraAPIError, _api_request
+from .sdk import get_automation_run as _get_automation_run
+from .sdk import run_automation as _run_automation
+
+# ============================================================================
+# Run Class
+# ============================================================================
+
+
+class Run:
+    """Represents an automation run with methods for polling and waiting.
+
+    Attributes:
+        id: The run ID.
+        automation_id: The automation ID.
+        status: Current status (queued, running, succeeded, failed, cancelled, timeout).
+        inputs: The inputs passed to the run.
+        result: The result returned by the automation (when succeeded).
+        error: Error message (when failed).
+        created: Creation timestamp.
+        started_at: Execution start timestamp.
+        finished_at: Completion timestamp.
+        external_id: Optional correlation ID.
+        trigger: How the run was initiated (manual, webhook, schedule, assistant).
+        log_pointer: S3 location of archived logs (after completion).
+        artifacts: List of output files created during execution.
+    """
+
+    def __init__(self, data: dict[str, Any]) -> None:
+        self._data = data
+
+    @property
+    def id(self) -> str:
+        return self._data.get("id", "")
+
+    @property
+    def automation_id(self) -> str:
+        return self._data.get("automation_id", "")
+
+    @property
+    def status(self) -> str:
+        return self._data.get("status", "")
+
+    @property
+    def inputs(self) -> dict[str, Any]:
+        raw = self._data.get("inputs", "{}")
+        if isinstance(raw, str):
+            try:
+                return json.loads(raw)
+            except json.JSONDecodeError:
+                return {}
+        return raw if isinstance(raw, dict) else {}
+
+    @property
+    def result(self) -> dict[str, Any] | None:
+        return self._data.get("result")
+
+    @property
+    def error(self) -> str | None:
+        return self._data.get("error")
+
+    @property
+    def created(self) -> str | None:
+        return self._data.get("created")
+
+    @property
+    def started_at(self) -> str | None:
+        return self._data.get("started_at")
+
+    @property
+    def finished_at(self) -> str | None:
+        return self._data.get("finished_at")
+
+    @property
+    def external_id(self) -> str | None:
+        return self._data.get("external_id")
+
+    @property
+    def trigger(self) -> str | None:
+        return self._data.get("trigger")
+
+    @property
+    def log_pointer(self) -> dict[str, Any] | None:
+        return self._data.get("log_pointer")
+
+    @property
+    def artifacts(self) -> list[dict[str, Any]]:
+        return self._data.get("artifacts") or []
+
+    @property
+    def is_terminal(self) -> bool:
+        """Returns True if the run has completed (success, failure, or cancelled)."""
+        return self.status in ("succeeded", "failed", "cancelled", "timeout")
+
+    def refresh(self) -> Run:
+        """Refresh run status from the server.
+
+        Returns:
+            self (for chaining).
+        """
+        if not self.id:
+            raise ValueError("Cannot refresh run without id")
+        updated = _get_automation_run(run_id=self.id)
+        self._data = updated
+        return self
+
+    def wait(
+        self,
+        timeout: float = 300,
+        poll_interval: float = 2.0,
+    ) -> dict[str, Any] | None:
+        """Block until the run completes or timeout is reached.
+
+        Args:
+            timeout: Maximum seconds to wait (default 300 = 5 minutes).
+            poll_interval: Seconds between status checks (default 2).
+
+        Returns:
+            The result dict if succeeded, None otherwise.
+
+        Raises:
+            TimeoutError: If timeout is reached before completion.
+            RuntimeError: If the run failed.
+        """
+        start = time.monotonic()
+        while not self.is_terminal:
+            elapsed = time.monotonic() - start
+            if elapsed >= timeout:
+                raise TimeoutError(
+                    f"Run {self.id} did not complete within {timeout}s (status: {self.status})"
+                )
+            time.sleep(poll_interval)
+            self.refresh()
+
+        if self.status == "failed":
+            raise RuntimeError(f"Run {self.id} failed: {self.error}")
+        if self.status in ("cancelled", "timeout"):
+            raise RuntimeError(f"Run {self.id} was {self.status}")
+
+        return self.result
+
+    def cancel(self) -> Run:
+        """Cancel the run if it's still running.
+
+        Returns:
+            self (for chaining).
+        """
+        if not self.id:
+            raise ValueError("Cannot cancel run without id")
+        result = _api_request("POST", f"automation-runs/{self.id}/cancel")
+        if isinstance(result, dict):
+            self._data = result
+        return self
+
+    def get_log_download_url(self) -> str:
+        """Get a presigned URL to download the run's logs.
+
+        Logs are archived to S3 after the run completes. This method returns
+        a presigned URL that can be used to download the log file.
+
+        **Caution for coding agents:** Automation logs can be very large (up to 50MB).
+        Avoid reading entire log contents into context. Instead, download to a file
+        and use tools like `grep`, `tail`, or `head` to extract relevant portions.
+
+        Returns:
+            A presigned URL string for downloading the logs.
+
+        Raises:
+            ValueError: If the run has no ID.
+            RuntimeError: If logs are not yet available (run still in progress).
+
+        Example:
+            >>> run = automations.get_run("run_id")
+            >>> if run.is_terminal:
+            ...     url = run.get_log_download_url()
+            ...     # Download to file, then use grep/tail to inspect
+        """
+        if not self.id:
+            raise ValueError("Cannot get log URL without run id")
+        return get_log_download_url(self.id)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the underlying data dict."""
+        return self._data.copy()
+
+    def __repr__(self) -> str:
+        return f"Run(id={self.id!r}, status={self.status!r}, automation_id={self.automation_id!r})"
+
+
+# ============================================================================
+# Automation Class
+# ============================================================================
+
+
+class Automation:
+    """Represents an automation definition.
+
+    Attributes:
+        id: The automation ID.
+        name: Display name.
+        description: Human-readable description.
+        external_id: Stable identifier for programmatic access.
+        code: Python source code.
+        input_schema: JSON schema defining inputs.
+        status: Automation status (active, inactive, archived).
+        schedule: Cron schedule (if scheduled).
+        last_run_status: Status of the most recent run.
+    """
+
+    def __init__(self, data: dict[str, Any]) -> None:
+        self._data = data
+
+    @property
+    def id(self) -> str:
+        return self._data.get("id", "")
+
+    @property
+    def name(self) -> str:
+        return self._data.get("name", "")
+
+    @property
+    def description(self) -> str | None:
+        return self._data.get("description")
+
+    @property
+    def external_id(self) -> str | None:
+        return self._data.get("external_id")
+
+    @property
+    def code(self) -> str:
+        return self._data.get("code", "")
+
+    @property
+    def input_schema(self) -> dict[str, Any] | None:
+        """Return the input schema as a dict. API always returns JSON object."""
+        return self._data.get("input_schema")
+
+    @property
+    def status(self) -> str | None:
+        return self._data.get("status")
+
+    @property
+    def schedule(self) -> str | None:
+        return self._data.get("schedule")
+
+    @property
+    def last_run_status(self) -> str | None:
+        return self._data.get("last_run_status")
+
+    def run(
+        self,
+        inputs: Mapping[str, Any] | None = None,
+        *,
+        external_id: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> Run:
+        """Run this automation.
+
+        Args:
+            inputs: Input parameters for the run.
+            external_id: Optional correlation ID for idempotency.
+            metadata: Optional metadata to attach to the run.
+
+        Returns:
+            A Run object representing the execution.
+        """
+        return run(self.id, inputs=inputs, external_id=external_id, metadata=metadata)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the underlying data dict."""
+        return self._data.copy()
+
+    def __repr__(self) -> str:
+        return f"Automation(id={self.id!r}, name={self.name!r})"
+
+
+# ============================================================================
+# Run Functions
+# ============================================================================
+
+
+def run(
+    automation_id: str,
+    inputs: Mapping[str, Any] | None = None,
+    *,
+    files: Mapping[str, Any] | None = None,
+    external_id: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> Run:
+    """Run an automation by ID.
+
+    Args:
+        automation_id: The automation ID to run.
+        inputs: Input parameters (dict). Types are coerced based on input_schema.
+        files: File inputs to upload (mapping of input key to file path(s)).
+        external_id: Optional correlation ID for idempotency. Repeated calls
+            with the same external_id return the existing run.
+        metadata: Optional metadata to attach to the run.
+
+    Returns:
+        A Run object for tracking execution status.
+
+    Example:
+        >>> run = automations.run("abc123", inputs={"limit": 100})
+        >>> print(run.id, run.status)
+        >>> result = run.wait(timeout=300)
+    """
+    result = _run_automation(
+        automation_id,
+        inputs=inputs,
+        files=files,
+        external_id=external_id,
+        metadata=metadata,
+    )
+    return Run(result)
+
+
+def run_by_external_id(
+    external_id: str,
+    inputs: Mapping[str, Any] | None = None,
+    *,
+    files: Mapping[str, Any] | None = None,
+    run_external_id: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> Run:
+    """Run an automation by its external_id (more stable than internal ID).
+
+    Args:
+        external_id: The automation's external_id (e.g., "deposit_matching:step1").
+        inputs: Input parameters (dict).
+        files: File inputs to upload.
+        run_external_id: Optional correlation ID for the run itself.
+        metadata: Optional metadata to attach to the run.
+
+    Returns:
+        A Run object for tracking execution status.
+
+    Example:
+        >>> run = automations.run_by_external_id(
+        ...     "deposit_matching:step1",
+        ...     inputs={"limit": 100}
+        ... )
+    """
+    automation = get_by_external_id(external_id)
+    return run(
+        automation.id,
+        inputs=inputs,
+        files=files,
+        external_id=run_external_id,
+        metadata=metadata,
+    )
+
+
+def get_run(run_id: str) -> Run:
+    """Get a run by its ID.
+
+    Args:
+        run_id: The run ID.
+
+    Returns:
+        A Run object with current status.
+
+    Example:
+        >>> run = automations.get_run("run_abc123")
+        >>> print(run.status, run.result)
+    """
+    result = _get_automation_run(run_id=run_id)
+    return Run(result)
+
+
+def list_runs(
+    automation_id: str | None = None,
+    *,
+    status: str | None = None,
+    limit: int = 100,
+    offset: int = 0,
+    sort: str = "created",
+    dir: str = "desc",
+) -> list[Run]:
+    """List runs, optionally filtered by automation and status.
+
+    Args:
+        automation_id: Filter by automation ID (optional).
+        status: Filter by status (queued, running, succeeded, failed, etc.).
+        limit: Maximum number of results (default 100).
+        offset: Pagination offset.
+        sort: Sort field (default "created").
+        dir: Sort direction ("asc" or "desc", default "desc").
+
+    Returns:
+        List of Run objects.
+
+    Example:
+        >>> runs = automations.list_runs("automation_id", status="succeeded", limit=10)
+        >>> for r in runs:
+        ...     print(r.id, r.created, r.status)
+    """
+    params: dict[str, Any] = {
+        "limit": limit,
+        "offset": offset,
+        "sort": sort,
+        "dir": dir,
+    }
+    if automation_id:
+        params["automation_id"] = automation_id
+    if status:
+        params["status"] = status
+
+    result = _api_request("GET", "automation-runs", params=params)
+    items = []
+    if isinstance(result, dict):
+        # API returns runs in different keys depending on context
+        items = result.get("automation_runs") or result.get("data") or []
+    return [Run(item) for item in items if isinstance(item, dict)]
+
+
+# ============================================================================
+# Automation Management Functions
+# ============================================================================
+
+
+def list(
+    *,
+    q: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+    sort: str = "created",
+    dir: str = "desc",
+) -> list[Automation]:
+    """List all automations.
+
+    Args:
+        q: Search query (case-insensitive name/description search).
+        limit: Maximum number of results (default 50).
+        offset: Pagination offset.
+        sort: Sort field (default "created").
+        dir: Sort direction ("asc" or "desc", default "desc").
+
+    Returns:
+        List of Automation objects.
+
+    Example:
+        >>> all_automations = automations.list()
+        >>> for a in all_automations:
+        ...     print(a.id, a.name)
+    """
+    params: dict[str, Any] = {
+        "limit": limit,
+        "offset": offset,
+        "sort": sort,
+        "dir": dir,
+    }
+    if q:
+        params["q"] = q
+
+    result = _api_request("GET", "automations", params=params)
+    items = []
+    if isinstance(result, dict):
+        items = result.get("automations") or []
+    return [Automation(item) for item in items if isinstance(item, dict)]
+
+
+def get(automation_id: str) -> Automation:
+    """Get an automation by ID.
+
+    Args:
+        automation_id: The automation ID.
+
+    Returns:
+        An Automation object.
+
+    Example:
+        >>> automation = automations.get("abc123")
+        >>> print(automation.name, automation.input_schema)
+    """
+    automation_id = automation_id.strip()
+    if not automation_id:
+        raise ValueError("automation_id is required")
+
+    result = _api_request("GET", f"automations/{automation_id}")
+    if not isinstance(result, dict):
+        raise RuntimeError("Unexpected response")
+    return Automation(result)
+
+
+def get_by_external_id(external_id: str) -> Automation:
+    """Get an automation by its external_id.
+
+    Args:
+        external_id: The automation's external_id.
+
+    Returns:
+        An Automation object.
+
+    Raises:
+        LumeraAPIError: If no automation with that external_id exists.
+
+    Example:
+        >>> automation = automations.get_by_external_id("deposit_matching:step1")
+        >>> print(automation.id, automation.name)
+    """
+    external_id = external_id.strip()
+    if not external_id:
+        raise ValueError("external_id is required")
+
+    result = _api_request("GET", "automations", params={"external_id": external_id, "limit": 1})
+    if isinstance(result, dict):
+        items = result.get("automations") or []
+        if items and isinstance(items[0], dict):
+            return Automation(items[0])
+
+    raise LumeraAPIError(
+        404,
+        f"Automation with external_id '{external_id}' not found",
+        url="automations",
+        payload=None,
+    )
+
+
+def create(
+    name: str,
+    code: str,
+    *,
+    input_schema: Mapping[str, Any] | None = None,
+    description: str | None = None,
+    external_id: str | None = None,
+    schedule: str | None = None,
+    schedule_tz: str | None = None,
+) -> Automation:
+    """Create a new automation.
+
+    Args:
+        name: Display name for the automation.
+        code: Python code with the entrypoint function.
+        input_schema: JSON schema defining inputs. Should include
+            ``function.name`` and ``function.parameters``.
+        description: Human-readable description.
+        external_id: Stable identifier for programmatic access.
+        schedule: Cron expression for scheduled runs.
+        schedule_tz: Timezone for schedule (e.g., "America/New_York").
+
+    Returns:
+        The created Automation object.
+
+    Example:
+        >>> automation = automations.create(
+        ...     name="My Automation",
+        ...     code="def main(x): return {'result': x * 2}",
+        ...     input_schema={
+        ...         "type": "function",
+        ...         "function": {
+        ...             "name": "main",
+        ...             "parameters": {
+        ...                 "type": "object",
+        ...                 "properties": {"x": {"type": "integer"}},
+        ...                 "required": ["x"]
+        ...             }
+        ...         }
+        ...     }
+        ... )
+    """
+    payload: dict[str, Any] = {
+        "name": name,
+        "code": code,
+    }
+    if input_schema is not None:
+        payload["input_schema"] = input_schema
+    if description is not None:
+        payload["description"] = description
+    if external_id is not None:
+        payload["external_id"] = external_id
+    if schedule is not None:
+        payload["schedule"] = schedule
+    if schedule_tz is not None:
+        payload["schedule_tz"] = schedule_tz
+
+    result = _api_request("POST", "automations", json_body=payload)
+    if not isinstance(result, dict):
+        raise RuntimeError("Unexpected response")
+    return Automation(result)
+
+
+def update(
+    automation_id: str,
+    *,
+    name: str | None = None,
+    code: str | None = None,
+    input_schema: Mapping[str, Any] | None = None,
+    description: str | None = None,
+    external_id: str | None = None,
+    schedule: str | None = None,
+    schedule_tz: str | None = None,
+) -> Automation:
+    """Update an existing automation.
+
+    Args:
+        automation_id: The automation ID to update.
+        name: New display name.
+        code: New Python code.
+        input_schema: New input schema.
+        description: New description.
+        external_id: New external_id.
+        schedule: New cron schedule (empty string to clear).
+        schedule_tz: New schedule timezone.
+
+    Returns:
+        The updated Automation object.
+
+    Example:
+        >>> automations.update("abc123", code=new_code)
+    """
+    automation_id = automation_id.strip()
+    if not automation_id:
+        raise ValueError("automation_id is required")
+
+    payload: dict[str, Any] = {}
+    if name is not None:
+        payload["name"] = name
+    if code is not None:
+        payload["code"] = code
+    if input_schema is not None:
+        payload["input_schema"] = input_schema
+    if description is not None:
+        payload["description"] = description
+    if external_id is not None:
+        payload["external_id"] = external_id
+    if schedule is not None:
+        payload["schedule"] = schedule
+    if schedule_tz is not None:
+        payload["schedule_tz"] = schedule_tz
+
+    if not payload:
+        raise ValueError("At least one field to update is required")
+
+    result = _api_request("PATCH", f"automations/{automation_id}", json_body=payload)
+    if not isinstance(result, dict):
+        raise RuntimeError("Unexpected response")
+    return Automation(result)
+
+
+def upsert(
+    external_id: str,
+    *,
+    name: str,
+    code: str,
+    input_schema: Mapping[str, Any] | None = None,
+    description: str | None = None,
+    schedule: str | None = None,
+    schedule_tz: str | None = None,
+) -> Automation:
+    """Create or update an automation by external_id (idempotent deploy).
+
+    If an automation with the given external_id exists, it will be updated.
+    Otherwise, a new automation will be created.
+
+    Args:
+        external_id: Stable identifier (required for upsert).
+        name: Display name.
+        code: Python code.
+        input_schema: JSON schema defining inputs.
+        description: Human-readable description.
+        schedule: Cron expression for scheduled runs.
+        schedule_tz: Timezone for schedule.
+
+    Returns:
+        The created or updated Automation object.
+
+    Example:
+        >>> # Idempotent deployment
+        >>> automations.upsert(
+        ...     external_id="my_app:my_automation",
+        ...     name="My Automation",
+        ...     code=open("my_script.py").read(),
+        ...     input_schema=schema
+        ... )
+    """
+    external_id = external_id.strip()
+    if not external_id:
+        raise ValueError("external_id is required for upsert")
+
+    # Try to find existing
+    try:
+        existing = get_by_external_id(external_id)
+        # Update existing
+        return update(
+            existing.id,
+            name=name,
+            code=code,
+            input_schema=input_schema,
+            description=description,
+            schedule=schedule,
+            schedule_tz=schedule_tz,
+        )
+    except LumeraAPIError as e:
+        if e.status_code != 404:
+            raise
+        # Create new
+        return create(
+            name=name,
+            code=code,
+            input_schema=input_schema,
+            description=description,
+            external_id=external_id,
+            schedule=schedule,
+            schedule_tz=schedule_tz,
+        )
+
+
+def delete(automation_id: str) -> None:
+    """Delete an automation.
+
+    Args:
+        automation_id: The automation ID to delete.
+
+    Example:
+        >>> automations.delete("abc123")
+    """
+    automation_id = automation_id.strip()
+    if not automation_id:
+        raise ValueError("automation_id is required")
+
+    _api_request("DELETE", f"automations/{automation_id}")
+
+
+# ============================================================================
+# Log Streaming
+# ============================================================================
+
+
+def stream_logs(run_id: str, *, timeout: float = 30) -> Iterator[str]:
+    """Stream live logs from a running automation.
+
+    Connects to the server-sent events endpoint and yields log lines
+    as they arrive. Stops when the run completes.
+
+    Args:
+        run_id: The run ID to stream logs from.
+        timeout: HTTP connection timeout in seconds.
+
+    Yields:
+        Log lines as strings.
+
+    Example:
+        >>> for line in automations.stream_logs("run_id"):
+        ...     print(line)
+    """
+    import base64
+    import os
+
+    import requests
+
+    run_id = run_id.strip()
+    if not run_id:
+        raise ValueError("run_id is required")
+
+    base_url = os.environ.get("LUMERA_BASE_URL", "https://app.lumerahq.com/api").rstrip("/")
+    token = os.environ.get("LUMERA_TOKEN", "")
+    if not token:
+        raise ValueError("LUMERA_TOKEN environment variable is required")
+
+    url = f"{base_url}/automation-runs/{run_id}/logs/live"
+    headers = {
+        "Authorization": f"token {token}",
+        "Accept": "text/event-stream",
+    }
+
+    with requests.get(url, headers=headers, stream=True, timeout=timeout) as resp:
+        resp.raise_for_status()
+
+        current_event = ""
+        current_data = ""
+
+        for line in resp.iter_lines(decode_unicode=True):
+            if line is None:
+                continue
+
+            if line.startswith("event:"):
+                current_event = line[6:].strip()
+            elif line.startswith("data:"):
+                current_data = line[5:].strip()
+            elif line == "":
+                # End of event
+                if current_event == "chunk" and current_data:
+                    try:
+                        data = json.loads(current_data)
+                        if "data" in data:
+                            # Data is base64-encoded
+                            raw = base64.b64decode(data["data"])
+                            decoded = raw.decode("utf-8", errors="replace")
+                            yield from decoded.splitlines()
+                    except (json.JSONDecodeError, KeyError):
+                        pass
+                elif current_event == "complete":
+                    return
+                current_event = ""
+                current_data = ""
+
+
+def get_log_download_url(run_id: str) -> str:
+    """Get a presigned URL to download the logs for a completed run.
+
+    Logs are archived to S3 after a run completes. This function returns
+    a presigned URL that can be used to download the log file directly.
+
+    **Caution for coding agents:** Automation logs can be very large (up to 50MB).
+    Avoid reading entire log contents into context. Instead, download to a file
+    and use tools like `grep`, `tail`, or `head` to extract relevant portions.
+
+    Args:
+        run_id: The run ID to get logs for.
+
+    Returns:
+        A presigned URL string for downloading the logs.
+
+    Raises:
+        ValueError: If run_id is empty.
+        LumeraAPIError: If the run doesn't exist or logs aren't available.
+
+    Example:
+        >>> url = automations.get_log_download_url("run_abc123")
+        >>> # Download to file, then inspect with shell tools
+        >>> import subprocess
+        >>> subprocess.run(["curl", "-o", "run.log", url])
+        >>> # Use grep/tail to extract relevant parts
+    """
+    run_id = run_id.strip()
+    if not run_id:
+        raise ValueError("run_id is required")
+
+    result = _api_request(
+        "GET",
+        f"automation-runs/{run_id}/files/download-url",
+        params={"name": "run.log"},
+    )
+    if isinstance(result, dict) and "url" in result:
+        return result["url"]
+    raise RuntimeError("Unexpected response: no download URL returned")