gflow-cli 0.2.0a1__py3-none-any.whl

flow_cli/__init__.py

@@ -0,0 +1,3 @@
+"""flow-cli — unofficial CLI for Google Flow."""
+
+__version__ = "0.2.0a1"

flow_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Allows `python -m flow_cli ...` invocation."""
+
+from flow_cli.cli import main
+
+if __name__ == "__main__":
+    main()

flow_cli/api/__init__.py

@@ -0,0 +1,18 @@
+"""Low-level REST client for Flow's private aisandbox-pa API."""
+
+from flow_cli.api.client import FlowApiClient, FlowApiError
+from flow_cli.api.dto import AssetInfo, ProjectInfo, VideoOperation, VideoStatus
+from flow_cli.api.video import Aspect, GenerateVideoRequest, Mode, Tier
+
+__all__ = [
+    "Aspect",
+    "AssetInfo",
+    "FlowApiClient",
+    "FlowApiError",
+    "GenerateVideoRequest",
+    "Mode",
+    "ProjectInfo",
+    "Tier",
+    "VideoOperation",
+    "VideoStatus",
+]

flow_cli/api/client.py

@@ -0,0 +1,246 @@
+"""FlowApiClient — typed wrapper around Flow's private REST surface.
+
+Architecture: the client manages its own Playwright persistent-context
+lifecycle (async context manager). All HTTP goes through `page.request`
+so Google's session cookies attach automatically — no manual bearer-token
+extraction.
+
+The video-generation route requires a fresh reCAPTCHA token per call;
+that piece lives in `flow_cli.api.recaptcha` and `generate_video()` (added
+in a later commit). For now this client implements the four routes that
+DON'T need reCAPTCHA: createProject, uploadImage, checkStatus, download.
+
+Usage:
+    async with FlowApiClient(profile_dir) as client:
+        project = await client.create_project()
+        asset = await client.upload_image(project.project_id, Path("hero.png"))
+        ...
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import secrets
+import time
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from playwright.async_api import BrowserContext, Page, Playwright, async_playwright
+
+from flow_cli.api import routes
+from flow_cli.api.dto import AssetInfo, ProjectInfo, VideoOperation, VideoStatus
+from flow_cli.api.recaptcha import TokenMinter
+from flow_cli.api.video import GenerateVideoRequest, build_generate_body
+
+logger = logging.getLogger(__name__)
+
+
+class FlowApiError(RuntimeError):
+    """Raised when a Flow API call returns a non-2xx response."""
+
+    def __init__(self, status: int, body: str, *, route: str):
+        self.status = status
+        self.body = body
+        self.route = route
+        super().__init__(f"Flow API {route} -> HTTP {status}: {body[:200]}")
+
+
+class FlowApiClient:
+    """Async context-managed client for Flow's REST surface.
+
+    Holds a Playwright persistent context and a single page (used as the HTTP
+    transport via `page.request`). Auth = whatever cookies the profile dir
+    has from a prior `gflow auth login`.
+    """
+
+    def __init__(self, profile_dir: Path, *, headless: bool = True):
+        self.profile_dir = profile_dir
+        self.headless = headless
+        self._pw: Playwright | None = None
+        self._context: BrowserContext | None = None
+        self._page: Page | None = None
+
+    # --- lifecycle --------------------------------------------------------
+
+    async def __aenter__(self) -> FlowApiClient:
+        self._pw = await async_playwright().start()
+        self._context = await self._pw.chromium.launch_persistent_context(
+            user_data_dir=str(self.profile_dir),
+            headless=self.headless,
+            viewport={"width": 1280, "height": 720},
+            locale="en-US",
+            extra_http_headers={"Accept-Language": "en-US,en;q=0.9"},
+        )
+        self._page = (
+            self._context.pages[0] if self._context.pages else await self._context.new_page()
+        )
+        # Bootstrap navigation so cookies + JS context are loaded before any
+        # API call. Many endpoints 401 if you POST cold without an active page.
+        await self._page.goto(
+            routes.EDITOR_BOOTSTRAP_URL, wait_until="domcontentloaded", timeout=60_000
+        )
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        if self._context:
+            try:
+                await self._context.close()
+            except Exception:
+                pass
+        if self._pw:
+            try:
+                await self._pw.stop()
+            except Exception:
+                pass
+
+    @property
+    def page(self) -> Page:
+        if self._page is None:
+            raise RuntimeError("FlowApiClient not entered — use `async with`")
+        return self._page
+
+    # --- private HTTP helpers --------------------------------------------
+
+    async def _post_json(
+        self, url: str, body: dict[str, Any], *, content_type: str = "text/plain;charset=UTF-8"
+    ) -> Any:
+        """POST a JSON body. aisandbox-pa requires text/plain content-type
+        (not application/json) — see samples/captured/*.json. The tRPC
+        host on labs.google accepts standard application/json."""
+        body_str = json.dumps(body)
+        logger.debug("POST %s body=%s", url, body_str[:300])
+        resp = await self.page.request.post(
+            url,
+            data=body_str,
+            headers={"content-type": content_type},
+        )
+        text = await resp.text()
+        if resp.status >= 400:
+            raise FlowApiError(resp.status, text, route=url)
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError as e:
+            raise FlowApiError(resp.status, f"non-JSON response: {text[:200]}", route=url) from e
+
+    async def _patch_json(self, url: str, body: dict[str, Any]) -> Any:
+        body_str = json.dumps(body)
+        logger.debug("PATCH %s body=%s", url, body_str[:300])
+        resp = await self.page.request.patch(
+            url,
+            data=body_str,
+            headers={"content-type": "text/plain;charset=UTF-8"},
+        )
+        text = await resp.text()
+        if resp.status >= 400:
+            raise FlowApiError(resp.status, text, route=url)
+        try:
+            return json.loads(text) if text else {}
+        except json.JSONDecodeError:
+            return {}
+
+    # --- public API -------------------------------------------------------
+
+    async def create_project(self, title: str | None = None) -> ProjectInfo:
+        """Bootstrap a fresh Flow project. Title defaults to a timestamp.
+
+        Maps to `POST .../trpc/project.createProject`.
+        """
+        title = title or _default_project_title()
+        body = {"json": {"projectTitle": title, "toolName": "PINHOLE"}}
+        data = await self._post_json(routes.CREATE_PROJECT, body, content_type="application/json")
+        return ProjectInfo.from_create_response(data)
+
+    async def upload_image(self, project_id: str, image_path: Path) -> AssetInfo:
+        """Upload an image into a Flow project's library.
+
+        Maps to `POST /v1/flow/uploadImage`. Image bytes go in base64.
+        Returns the asset UUID + dimensions Flow inferred.
+        """
+        if not image_path.exists():
+            raise FileNotFoundError(image_path)
+        b64 = base64.b64encode(image_path.read_bytes()).decode()
+        body = {
+            "clientContext": {"projectId": project_id, "tool": "PINHOLE"},
+            "imageBytes": b64,
+        }
+        data = await self._post_json(routes.UPLOAD_IMAGE, body)
+        return AssetInfo.from_upload_response(data)
+
+    async def get_video_status(self, project_id: str, media_names: list[str]) -> list[VideoStatus]:
+        """Poll the status of one or more in-flight video generations.
+
+        Maps to `POST /v1/video:batchCheckAsyncVideoGenerationStatus`.
+        """
+        body = {"media": [{"name": n, "projectId": project_id} for n in media_names]}
+        data = await self._post_json(routes.CHECK_VIDEO_STATUS, body)
+        return [VideoStatus.from_check_status_item(it) for it in data.get("media", [])]
+
+    async def download(self, name_or_url: str, out_path: Path) -> Path:
+        """Download an asset (image or video) to `out_path`. Returns out_path."""
+        url = (
+            name_or_url
+            if name_or_url.startswith("http")
+            else routes.media_download_url(name_or_url)
+        )
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        resp = await self.page.request.get(url, max_redirects=5, timeout=120_000)
+        if resp.status >= 400:
+            raise FlowApiError(resp.status, await resp.text(), route=url)
+        out_path.write_bytes(await resp.body())
+        return out_path
+
+    async def archive_workflow(self, workflow_id: str, project_id: str) -> None:
+        """Soft-delete (archive) a workflow — used by clear-library tooling.
+
+        Maps to `PATCH /v1/flowWorkflows/{id}` with `metadata.archived=true`.
+        """
+        url = f"{routes.ARCHIVE_WORKFLOW_BASE}/{workflow_id}"
+        body = {
+            "workflow": {
+                "name": workflow_id,
+                "projectId": project_id,
+                "metadata": {"archived": True},
+            },
+            "updateMask": "metadata.archived",
+        }
+        await self._patch_json(url, body)
+
+    async def generate_video(
+        self,
+        *,
+        project_id: str,
+        req: GenerateVideoRequest,
+        seed: int | None = None,
+        recaptcha_action: str = "videoGeneration",
+        batch_id: str | None = None,
+    ) -> VideoOperation:
+        """Enqueue a Veo video generation. Returns the operation reference.
+
+        Mints a fresh reCAPTCHA token via the live page session before
+        submitting. Caller polls completion via `get_video_status`.
+        """
+        minter = TokenMinter(self.page)
+        token = await minter.mint(recaptcha_action)
+        body = build_generate_body(
+            req,
+            project_id=project_id,
+            recaptcha_token=token,
+            batch_id=batch_id or _new_batch_id(),
+            seed=seed if seed is not None else secrets.randbelow(2**31),
+            session_id=f";{int(time.time() * 1000)}",
+        )
+        data = await self._post_json(routes.GENERATE_VIDEO, body)
+        return VideoOperation.from_generate_response(data)
+
+
+def _default_project_title() -> str:
+    return datetime.now().strftime("flow-cli %b %d, %I:%M %p")
+
+
+def _new_batch_id() -> str:
+    """Generate a fresh batch ID for the mediaGenerationContext."""
+    return str(uuid.uuid4())

flow_cli/api/dto.py

@@ -0,0 +1,137 @@
+"""Typed DTOs for Flow API requests/responses.
+
+All frozen dataclasses — once constructed, instances are immutable and
+hashable. Parsers (`*.from_response`) defensively read JSON dicts and
+raise `ValueError` on missing/malformed fields rather than letting
+KeyErrors leak.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ProjectInfo:
+    """A Flow project — owns assets, jobs, library entries."""
+
+    project_id: str
+    title: str
+
+    @classmethod
+    def from_create_response(cls, data: dict[str, Any]) -> ProjectInfo:
+        """Parse `POST .../project.createProject` JSON.
+
+        Wire shape:
+          {result: {data: {json: {result: {projectId, projectInfo: {projectTitle}}}}}}
+        """
+        try:
+            inner = data["result"]["data"]["json"]["result"]
+            return cls(
+                project_id=inner["projectId"],
+                title=inner["projectInfo"]["projectTitle"],
+            )
+        except (KeyError, TypeError) as e:
+            raise ValueError(f"unexpected createProject response shape: {e}") from e
+
+
+@dataclass(frozen=True)
+class AssetInfo:
+    """A media asset (image or video) registered in a Flow project."""
+
+    name: str  # asset UUID
+    project_id: str
+    workflow_id: str
+    display_name: str
+    width: int
+    height: int
+
+    @classmethod
+    def from_upload_response(cls, data: dict[str, Any]) -> AssetInfo:
+        """Parse `POST /v1/flow/uploadImage` JSON.
+
+        Wire shape:
+          {media: {name, projectId, workflowId, image: {dimensions: {width, height}}, ...},
+           workflow: {metadata: {displayName}, ...}}
+        """
+        try:
+            media = data["media"]
+            dims = media.get("image", {}).get("dimensions", {})
+            return cls(
+                name=media["name"],
+                project_id=media["projectId"],
+                workflow_id=media["workflowId"],
+                display_name=data.get("workflow", {}).get("metadata", {}).get("displayName", ""),
+                width=int(dims.get("width", 0)),
+                height=int(dims.get("height", 0)),
+            )
+        except (KeyError, TypeError) as e:
+            raise ValueError(f"unexpected uploadImage response shape: {e}") from e
+
+
+@dataclass(frozen=True)
+class VideoStatus:
+    """Snapshot of one in-flight video generation."""
+
+    media_name: str  # asset UUID, used to track the job
+    project_id: str
+    status: str  # MEDIA_GENERATION_STATUS_PENDING|RUNNING|COMPLETED|FAILED
+    operation_name: str | None  # set once generation has started
+    workflow_id: str | None
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in (
+            "MEDIA_GENERATION_STATUS_COMPLETED",
+            "MEDIA_GENERATION_STATUS_FAILED",
+        )
+
+    @property
+    def succeeded(self) -> bool:
+        return self.status == "MEDIA_GENERATION_STATUS_COMPLETED"
+
+    @classmethod
+    def from_check_status_item(cls, item: dict[str, Any]) -> VideoStatus:
+        """Parse one element of the `media[]` array in the check-status response."""
+        try:
+            return cls(
+                media_name=item["name"],
+                project_id=item["projectId"],
+                status=item["mediaMetadata"]["mediaStatus"]["mediaGenerationStatus"],
+                operation_name=item.get("video", {}).get("operation", {}).get("name"),
+                workflow_id=item.get("workflowId"),
+            )
+        except (KeyError, TypeError) as e:
+            raise ValueError(f"unexpected check-status item shape: {e}") from e
+
+
+@dataclass(frozen=True)
+class VideoOperation:
+    """Reference returned when a generation request is enqueued."""
+
+    media_name: str  # asset UUID — pass to get_video_status() to poll
+    project_id: str
+    operation_name: str
+    workflow_id: str
+
+    @classmethod
+    def from_generate_response(cls, data: dict[str, Any]) -> VideoOperation:
+        """Parse `POST /v1/video:batchAsyncGenerateVideoText` JSON.
+
+        Wire shape (one operation):
+            {operations: [{operation: {name}, ...}],
+             media: [{name, projectId, workflowId, ...}],
+             workflows: [{name, projectId, ...}]}
+        """
+        try:
+            op = data["operations"][0]["operation"]["name"]
+            media = data["media"][0]
+            return cls(
+                media_name=media["name"],
+                project_id=media["projectId"],
+                operation_name=op,
+                workflow_id=media["workflowId"],
+            )
+        except (KeyError, IndexError, TypeError) as e:
+            raise ValueError(f"unexpected generateVideo response shape: {e}") from e

flow_cli/api/recaptcha.py

@@ -0,0 +1,107 @@
+"""reCAPTCHA Enterprise token minting via Playwright page.evaluate.
+
+The site key is discovered from the page source (loaded by the persistent
+context's bootstrap navigation in `FlowApiClient.__aenter__`). Tokens are
+single-use, ~2 min expiry — minted per `generate_video()` call.
+
+`TokenMinter` caches the discovered site key for the lifetime of one
+FlowApiClient session.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+
+class _PageLike(Protocol):
+    """Minimal subset of playwright.async_api.Page we need.
+
+    Defined as a Protocol so tests can pass mocks without importing Playwright.
+    """
+
+    async def evaluate(self, expression: str, arg: Any = None) -> Any: ...
+
+
+class RecaptchaError(RuntimeError):
+    """Raised when reCAPTCHA token minting fails (script missing,
+    Google refused to mint, etc.)."""
+
+
+_DISCOVER_SITE_KEY_JS = """
+() => {
+    const scripts = document.querySelectorAll('script[src*="recaptcha/enterprise.js"]');
+    for (const s of scripts) {
+        const m = (s.getAttribute('src') || '').match(/[?&]render=([^&]+)/);
+        if (m) return m[1];
+    }
+    return null;
+}
+"""
+
+_EXECUTE_JS = """
+async ([siteKey, action]) => {
+    return await new Promise((resolve, reject) => {
+        if (typeof grecaptcha === 'undefined' || !grecaptcha.enterprise) {
+            return reject(new Error('grecaptcha.enterprise not loaded'));
+        }
+        grecaptcha.enterprise.ready(() => {
+            grecaptcha.enterprise
+                .execute(siteKey, { action })
+                .then(resolve)
+                .catch(reject);
+        });
+    });
+}
+"""
+
+
+async def discover_site_key(page: _PageLike) -> str:
+    """Read the reCAPTCHA Enterprise site key from the loaded page.
+
+    Raises `RecaptchaError` if the recaptcha/enterprise.js script tag is
+    missing or doesn't carry a `render=<key>` query param.
+    """
+    key = await page.evaluate(_DISCOVER_SITE_KEY_JS)
+    if not isinstance(key, str) or not key:
+        raise RecaptchaError(
+            "Could not discover reCAPTCHA site key from the page. "
+            "The Flow editor page may have failed to load, or the reCAPTCHA "
+            "script tag layout has changed."
+        )
+    return key
+
+
+class TokenMinter:
+    """Mint reCAPTCHA tokens. Caches the site key for the session."""
+
+    def __init__(self, page: _PageLike):
+        self._page = page
+        self._site_key: str | None = None
+
+    async def site_key(self) -> str:
+        if self._site_key is None:
+            self._site_key = await discover_site_key(self._page)
+        return self._site_key
+
+    async def mint(self, action: str) -> str:
+        """Mint a fresh reCAPTCHA Enterprise token for the given action.
+
+        Tokens are single-use and expire in ~2 minutes — call this immediately
+        before the API request that consumes the token.
+        """
+        site_key = await self.site_key()
+        try:
+            token = await self._page.evaluate(_EXECUTE_JS, [site_key, action])
+        except Exception as exc:
+            raise RecaptchaError(
+                f"reCAPTCHA evaluate failed for action={action!r}: {exc}. "
+                "Likely causes: grecaptcha not loaded, page navigated away, "
+                "or Playwright timeout. Try FLOW_CLI_HEADLESS=false."
+            ) from exc
+        if not isinstance(token, str) or not token:
+            raise RecaptchaError(
+                f"reCAPTCHA returned an empty token for action={action!r}. "
+                "Likely causes: headless detection by Google, or the page "
+                "navigated away before mint. Try FLOW_CLI_HEADLESS=false."
+            )
+        return token

flow_cli/api/routes.py

@@ -0,0 +1,37 @@
+"""URL constants for every Flow REST route flow-cli touches.
+
+Two hosts are involved:
+  * aisandbox-pa.googleapis.com — the actual Flow API surface
+  * labs.google/fx/api/trpc — tRPC routes for project lifecycle
+"""
+
+from __future__ import annotations
+
+FLOW_API_BASE = "https://aisandbox-pa.googleapis.com/v1"
+LABS_TRPC_BASE = "https://labs.google/fx/api/trpc"
+LABS_BASE = "https://labs.google"
+
+# Asset / media
+UPLOAD_IMAGE = f"{FLOW_API_BASE}/flow/uploadImage"
+
+# Video generation (reCAPTCHA-required for GENERATE_VIDEO)
+GENERATE_VIDEO = f"{FLOW_API_BASE}/video:batchAsyncGenerateVideoText"
+CHECK_VIDEO_STATUS = f"{FLOW_API_BASE}/video:batchCheckAsyncVideoGenerationStatus"
+
+# Workflow management
+ARCHIVE_WORKFLOW_BASE = f"{FLOW_API_BASE}/flowWorkflows"  # + /{workflow_id}
+
+# Project lifecycle (tRPC, different host)
+CREATE_PROJECT = f"{LABS_TRPC_BASE}/project.createProject"
+
+
+# Media download — public-style URL that 302s to a signed Cloud Storage URL.
+# Cookies still required.
+def media_download_url(name: str) -> str:
+    """Build the redirect URL for an asset name (UUID)."""
+    return f"{LABS_BASE}/fx/api/trpc/media.getMediaUrlRedirect?name={name}"
+
+
+# Bootstrap URL — the Flow editor page. The persistent context navigates here
+# once before making API calls so Google's cookies + reCAPTCHA JS are loaded.
+EDITOR_BOOTSTRAP_URL = "https://labs.google/fx/tools/flow?hl=en"

flow_cli/api/video.py

@@ -0,0 +1,112 @@
+"""Pure value objects and body builders for video generation.
+
+No I/O lives in this module — `FlowApiClient.generate_video()` calls
+`build_generate_body()` and POSTs the result.
+
+`model_key()` encodes Flow's wire format for the `videoModelKey` field
+(e.g. `veo_3_1_t2v_fast_portrait`) — discovered from sample
+`samples/captured/02_batchAsyncGenerateVideoText.json`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+
+class Mode(StrEnum):
+    T2V = "t2v"
+    I2V = "i2v"
+
+
+class Tier(StrEnum):
+    FAST = "fast"
+    QUALITY = "quality"
+
+
+class Aspect(StrEnum):
+    PORTRAIT = "portrait"
+    LANDSCAPE = "landscape"
+    SQUARE = "square"
+
+    def wire(self) -> str:
+        return f"VIDEO_ASPECT_RATIO_{self.value.upper()}"
+
+    @classmethod
+    def from_cli(cls, value: str) -> Aspect:
+        mapping = {"9:16": cls.PORTRAIT, "16:9": cls.LANDSCAPE, "1:1": cls.SQUARE}
+        if value not in mapping:
+            raise ValueError(f"Unsupported aspect ratio {value!r}; choose from {sorted(mapping)}")
+        return mapping[value]
+
+
+@dataclass(frozen=True)
+class GenerateVideoRequest:
+    """Inputs for ONE video generation. T2V if start_asset_uuid is None, else I2V."""
+
+    prompt: str
+    aspect: Aspect = Aspect.PORTRAIT
+    tier: Tier = Tier.FAST
+    start_asset_uuid: str | None = None
+
+    @property
+    def mode(self) -> Mode:
+        return Mode.I2V if self.start_asset_uuid else Mode.T2V
+
+
+# Wire-format constants discovered from samples/captured/02_batchAsyncGenerateVideoText.json
+_AUDIO_FAILURE_PREF = "BLOCK_SILENCED_VIDEOS"
+_CLIENT_TOOL = "PINHOLE"
+_PAYGATE_TIER = "PAYGATE_TIER_ONE"
+_RECAPTCHA_APP_TYPE = "RECAPTCHA_APPLICATION_TYPE_WEB"
+
+
+def model_key(mode: Mode, tier: Tier, aspect: Aspect) -> str:
+    """Compose Flow's `videoModelKey` wire string."""
+    return f"veo_3_1_{mode.value}_{tier.value}_{aspect.value}"
+
+
+def build_generate_body(
+    req: GenerateVideoRequest,
+    *,
+    project_id: str,
+    recaptcha_token: str,
+    batch_id: str,
+    seed: int,
+    session_id: str,
+) -> dict[str, Any]:
+    """Build the JSON body for `POST /v1/video:batchAsyncGenerateVideoText`.
+
+    Shape mirrors `samples/captured/02_batchAsyncGenerateVideoText.json` —
+    every field there is required by the server.
+    """
+    image_input: dict[str, Any] = (
+        {"imageInput": {"mediaId": req.start_asset_uuid}} if req.start_asset_uuid else {}
+    )
+    request: dict[str, Any] = {
+        "aspectRatio": req.aspect.wire(),
+        "textInput": {"structuredPrompt": {"parts": [{"text": req.prompt}]}},
+        "videoModelKey": model_key(req.mode, req.tier, req.aspect),
+        "metadata": {},
+        "seed": seed,
+        **image_input,
+    }
+    return {
+        "mediaGenerationContext": {
+            "batchId": batch_id,
+            "audioFailurePreference": _AUDIO_FAILURE_PREF,
+        },
+        "clientContext": {
+            "projectId": project_id,
+            "tool": _CLIENT_TOOL,
+            "userPaygateTier": _PAYGATE_TIER,
+            "sessionId": session_id,
+            "recaptchaContext": {
+                "token": recaptcha_token,
+                "applicationType": _RECAPTCHA_APP_TYPE,
+            },
+        },
+        "requests": [request],
+        "useV2ModelConfig": True,
+    }