yt-studio-mcp 0.1.0__tar.gz

yt_studio_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e '.[dev]'
+      - name: Lint
+        run: ruff check src tests
+      - name: Tests
+        run: pytest
+      - name: Forbidden terms check
+        env:
+          FORBIDDEN_TERMS: ${{ secrets.FORBIDDEN_TERMS }}
+        run: |
+          if [ -n "$FORBIDDEN_TERMS" ] && git grep -qiE "$FORBIDDEN_TERMS" -- . ; then
+            echo "::error::forbidden terms found in repository"
+            exit 1
+          fi
+      - name: Secret shape check
+        run: |
+          if git grep -nE '(refresh_token|client_secret)"?\s*[:=]\s*"[A-Za-z0-9_/-]{20,}' -- ':!tests' ; then
+            echo "::error::possible hardcoded credential"
+            exit 1
+          fi

yt_studio_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

yt_studio_mcp-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+docs/superpowers/
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/
+credentials.json
+client_secret*.json

yt_studio_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aaronckj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yt_studio_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: yt-studio-mcp
+Version: 0.1.0
+Summary: MCP server for managing a YouTube channel: videos, comments, playlists, live streams, analytics, and auditable comment-entry giveaways.
+Project-URL: Homepage, https://github.com/aaronckj/yt-studio-mcp
+Project-URL: Issues, https://github.com/aaronckj/yt-studio-mcp/issues
+Author: aaronckj
+License-Expression: MIT
+License-File: LICENSE
+Keywords: giveaway,mcp,model-context-protocol,youtube,youtube-api
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: google-api-python-client>=2.100
+Requires-Dist: google-auth-oauthlib>=1.2
+Requires-Dist: google-auth>=2.30
+Requires-Dist: mcp>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# yt-studio-mcp
+
+An MCP (Model Context Protocol) server for managing a YouTube channel through
+the official Google APIs — videos, comments and moderation, playlists, live
+broadcasts, captions, analytics — plus an **auditable giveaway suite** for
+running comment-entry giveaways with deterministic, independently verifiable
+winner drawing.
+
+- Official APIs only (YouTube Data v3 + YouTube Analytics v2). No scraping.
+- Every mutating tool accepts `dry_run=true` and returns a preview instead of writing.
+- No secrets in this repo, in logs, or in your MCP client config.
+
+## Quick start
+
+### 1. Create Google credentials (~5 minutes, one time)
+
+1. Go to [console.cloud.google.com](https://console.cloud.google.com), create a project.
+2. **APIs & Services → Library**: enable **YouTube Data API v3** and **YouTube Analytics API**.
+3. **APIs & Services → OAuth consent screen**: External, add yourself as a test user.
+4. **APIs & Services → Credentials → Create credentials → OAuth client ID → Desktop app**;
+   download the JSON as `client_secret.json`.
+
+### 2. Authorize your channel
+
+```bash
+uvx yt-studio-mcp auth --client-secret /path/to/client_secret.json
+```
+
+A browser opens — sign in and **pick the channel** (Brand Accounts appear as
+separate choices). The refresh token is stored locally (see Secret storage).
+
+### 3. Connect your MCP client
+
+```bash
+# Claude Code
+claude mcp add yt-studio -s user -- uvx yt-studio-mcp
+```
+
+## Tools
+
+| Area | Tools |
+|---|---|
+| Channel/videos | `channel_info`, `list_videos`, `get_video`, `update_video`, `set_thumbnail`, `upload_video`, `delete_video` |
+| Playlists | `list_playlists`, `create_playlist`, `delete_playlist`, `add_to_playlist`, `remove_from_playlist`, `list_playlist_items` |
+| Comments | `list_comments`, `post_video_question`, `reply_to_comment`, `moderate_comment`, `mark_spam`, `delete_comment` |
+| Live | `list_broadcasts`, `create_broadcast`, `list_streams`, `bind_broadcast`, `live_chat_messages`, `post_chat_message`, `delete_chat_message`, `ban_chat_user` |
+| Captions | `list_captions`, `upload_caption`, `download_caption` |
+| Analytics | `channel_report`, `video_report`, `top_videos` |
+| Giveaways | `collect_entries`, `draw_winners`, `make_verification_code`, `check_verification_reply`, `post_winner_reply` |
+| Meta | `quota_status`, `health_check` |
+
+Known API limitations (documented, not bugs): comments cannot be pinned via
+the API (`post_video_question` reminds you to pin manually in Studio), and
+Community-tab posts have no public API.
+
+## Running a giveaway
+
+The giveaway suite implements a common official-rules pattern: *comment on
+any video during the entry window; each distinct video counts as one entry,
+capped per person; winners drawn at random.*
+
+```text
+1. collect_entries(start="2026-01-01T00:00:00Z", end="2026-01-31T23:59:59Z",
+                   max_entries_per_user=5, exclude_channel_ids=[...])
+     → walks every upload's comments, derives entries, writes a snapshot
+       file and returns its SHA-256 entry hash. Announce the hash if you
+       want third-party verifiability.
+
+2. draw_winners(snapshot_path, n=5, seed="any-public-string")
+     → deterministic: a seeded shuffle over the canonically sorted entries,
+       first n distinct channels win. Anyone with the snapshot + seed can
+       re-run the draw and get identical winners. Records an audit file.
+       Screen-record this step for extra transparency.
+
+3. make_verification_code(audit_path, winner_channel_id)
+     → short code you send to the claimed winner over your announced contact
+       channel.
+
+4. check_verification_reply(audit_path, comment_id, winner_channel_id)
+     → confirms the reply was authored by the winning channel and contains
+       the code — proves account ownership before shipping a prize.
+
+5. post_winner_reply(comment_id, "Congratulations! ...")
+```
+
+Entries and audit records live in `~/.config/yt-studio-mcp/giveaways/`.
+
+*This tool automates entry collection and drawing; giveaway laws vary by
+jurisdiction and platform policies apply (e.g. YouTube's contest policies).
+You are responsible for your own official rules and compliance.*
+
+## Secret storage
+
+| Backend | Select with | Stores |
+|---|---|---|
+| `file` (default) | — | `~/.config/yt-studio-mcp/credentials.json`, chmod 0600 |
+| `env` | `YT_MCP_SECRETS=env` | reads `YT_MCP_REFRESH_TOKEN`, `YT_MCP_CLIENT_ID`, `YT_MCP_CLIENT_SECRET` |
+| `vaultproxy` | `YT_MCP_SECRETS=vaultproxy` (+ `VAULTPROXY_URL`) | items in a Vaultwarden vault via a local vaultproxy HTTP API |
+
+## Quota
+
+The Data API's default allocation is 10,000 units/day. Most reads cost 1
+unit; writes cost ~50; a video upload costs 1,600. `quota_status()` shows a
+session estimate and warns at 80%. `collect_entries` reports what it spent.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+ruff check src tests && pytest
+```
+
+Tests are fully offline (mocked Google API). PRs welcome.
+
+## License
+
+MIT

yt_studio_mcp-0.1.0/README.md

@@ -0,0 +1,117 @@
+# yt-studio-mcp
+
+An MCP (Model Context Protocol) server for managing a YouTube channel through
+the official Google APIs — videos, comments and moderation, playlists, live
+broadcasts, captions, analytics — plus an **auditable giveaway suite** for
+running comment-entry giveaways with deterministic, independently verifiable
+winner drawing.
+
+- Official APIs only (YouTube Data v3 + YouTube Analytics v2). No scraping.
+- Every mutating tool accepts `dry_run=true` and returns a preview instead of writing.
+- No secrets in this repo, in logs, or in your MCP client config.
+
+## Quick start
+
+### 1. Create Google credentials (~5 minutes, one time)
+
+1. Go to [console.cloud.google.com](https://console.cloud.google.com), create a project.
+2. **APIs & Services → Library**: enable **YouTube Data API v3** and **YouTube Analytics API**.
+3. **APIs & Services → OAuth consent screen**: External, add yourself as a test user.
+4. **APIs & Services → Credentials → Create credentials → OAuth client ID → Desktop app**;
+   download the JSON as `client_secret.json`.
+
+### 2. Authorize your channel
+
+```bash
+uvx yt-studio-mcp auth --client-secret /path/to/client_secret.json
+```
+
+A browser opens — sign in and **pick the channel** (Brand Accounts appear as
+separate choices). The refresh token is stored locally (see Secret storage).
+
+### 3. Connect your MCP client
+
+```bash
+# Claude Code
+claude mcp add yt-studio -s user -- uvx yt-studio-mcp
+```
+
+## Tools
+
+| Area | Tools |
+|---|---|
+| Channel/videos | `channel_info`, `list_videos`, `get_video`, `update_video`, `set_thumbnail`, `upload_video`, `delete_video` |
+| Playlists | `list_playlists`, `create_playlist`, `delete_playlist`, `add_to_playlist`, `remove_from_playlist`, `list_playlist_items` |
+| Comments | `list_comments`, `post_video_question`, `reply_to_comment`, `moderate_comment`, `mark_spam`, `delete_comment` |
+| Live | `list_broadcasts`, `create_broadcast`, `list_streams`, `bind_broadcast`, `live_chat_messages`, `post_chat_message`, `delete_chat_message`, `ban_chat_user` |
+| Captions | `list_captions`, `upload_caption`, `download_caption` |
+| Analytics | `channel_report`, `video_report`, `top_videos` |
+| Giveaways | `collect_entries`, `draw_winners`, `make_verification_code`, `check_verification_reply`, `post_winner_reply` |
+| Meta | `quota_status`, `health_check` |
+
+Known API limitations (documented, not bugs): comments cannot be pinned via
+the API (`post_video_question` reminds you to pin manually in Studio), and
+Community-tab posts have no public API.
+
+## Running a giveaway
+
+The giveaway suite implements a common official-rules pattern: *comment on
+any video during the entry window; each distinct video counts as one entry,
+capped per person; winners drawn at random.*
+
+```text
+1. collect_entries(start="2026-01-01T00:00:00Z", end="2026-01-31T23:59:59Z",
+                   max_entries_per_user=5, exclude_channel_ids=[...])
+     → walks every upload's comments, derives entries, writes a snapshot
+       file and returns its SHA-256 entry hash. Announce the hash if you
+       want third-party verifiability.
+
+2. draw_winners(snapshot_path, n=5, seed="any-public-string")
+     → deterministic: a seeded shuffle over the canonically sorted entries,
+       first n distinct channels win. Anyone with the snapshot + seed can
+       re-run the draw and get identical winners. Records an audit file.
+       Screen-record this step for extra transparency.
+
+3. make_verification_code(audit_path, winner_channel_id)
+     → short code you send to the claimed winner over your announced contact
+       channel.
+
+4. check_verification_reply(audit_path, comment_id, winner_channel_id)
+     → confirms the reply was authored by the winning channel and contains
+       the code — proves account ownership before shipping a prize.
+
+5. post_winner_reply(comment_id, "Congratulations! ...")
+```
+
+Entries and audit records live in `~/.config/yt-studio-mcp/giveaways/`.
+
+*This tool automates entry collection and drawing; giveaway laws vary by
+jurisdiction and platform policies apply (e.g. YouTube's contest policies).
+You are responsible for your own official rules and compliance.*
+
+## Secret storage
+
+| Backend | Select with | Stores |
+|---|---|---|
+| `file` (default) | — | `~/.config/yt-studio-mcp/credentials.json`, chmod 0600 |
+| `env` | `YT_MCP_SECRETS=env` | reads `YT_MCP_REFRESH_TOKEN`, `YT_MCP_CLIENT_ID`, `YT_MCP_CLIENT_SECRET` |
+| `vaultproxy` | `YT_MCP_SECRETS=vaultproxy` (+ `VAULTPROXY_URL`) | items in a Vaultwarden vault via a local vaultproxy HTTP API |
+
+## Quota
+
+The Data API's default allocation is 10,000 units/day. Most reads cost 1
+unit; writes cost ~50; a video upload costs 1,600. `quota_status()` shows a
+session estimate and warns at 80%. `collect_entries` reports what it spent.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+ruff check src tests && pytest
+```
+
+Tests are fully offline (mocked Google API). PRs welcome.
+
+## License
+
+MIT

yt_studio_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "yt-studio-mcp"
+version = "0.1.0"
+description = "MCP server for managing a YouTube channel: videos, comments, playlists, live streams, analytics, and auditable comment-entry giveaways."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "aaronckj" }]
+keywords = ["mcp", "youtube", "youtube-api", "giveaway", "model-context-protocol"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "mcp>=1.2",
+  "google-api-python-client>=2.100",
+  "google-auth>=2.30",
+  "google-auth-oauthlib>=1.2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+yt-studio-mcp = "yt_studio_mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/aaronckj/yt-studio-mcp"
+Issues = "https://github.com/aaronckj/yt-studio-mcp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yt_studio_mcp"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

yt_studio_mcp-0.1.0/src/yt_studio_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

yt_studio_mcp-0.1.0/src/yt_studio_mcp/__main__.py

@@ -0,0 +1,39 @@
+"""CLI entry: `yt-studio-mcp` serves; `yt-studio-mcp auth` authorizes."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main() -> None:
+    if len(sys.argv) > 1 and sys.argv[1] == "scan":
+        from .scan_cli import main as scan_main
+
+        raise SystemExit(scan_main(sys.argv[2:]))
+
+    parser = argparse.ArgumentParser(prog="yt-studio-mcp")
+    sub = parser.add_subparsers(dest="command")
+    auth_p = sub.add_parser("auth", help="one-time interactive OAuth consent")
+    auth_p.add_argument(
+        "--client-secret",
+        required=True,
+        help="path to the OAuth client_secret.json downloaded from Google Cloud",
+    )
+    sub.add_parser("serve", help="run the MCP server (default)")
+    sub.add_parser("scan", help="headless spam scan for cron (see scan --help)")
+    args = parser.parse_args()
+
+    if args.command == "auth":
+        from .auth import run_auth_flow
+
+        print(run_auth_flow(args.client_secret), file=sys.stderr)
+        return
+
+    from .server import build_app
+
+    build_app().run()
+
+
+if __name__ == "__main__":
+    main()

yt_studio_mcp-0.1.0/src/yt_studio_mcp/auth.py

@@ -0,0 +1,73 @@
+"""OAuth: one-time interactive flow plus credential rebuild/refresh."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from google.auth.transport.requests import Request as GoogleRequest
+from google.oauth2.credentials import Credentials
+
+from .secrets import SecretStore, get_store
+
+SCOPES = [
+    "https://www.googleapis.com/auth/youtube.force-ssl",
+    "https://www.googleapis.com/auth/youtube.upload",
+    "https://www.googleapis.com/auth/yt-analytics.readonly",
+]
+TOKEN_URI = "https://oauth2.googleapis.com/token"
+
+
+class AuthError(RuntimeError):
+    pass
+
+
+def run_auth_flow(client_secret_path: str, store: SecretStore | None = None) -> str:
+    """Interactive browser consent. Stores refresh token + client info. Returns channel hint."""
+    from google_auth_oauthlib.flow import InstalledAppFlow
+
+    store = store or get_store()
+    path = Path(client_secret_path)
+    if not path.exists():
+        raise AuthError(f"client secret file not found: {path}")
+    flow = InstalledAppFlow.from_client_secrets_file(str(path), scopes=SCOPES)
+    creds = flow.run_local_server(port=0, prompt="consent")
+    if not creds.refresh_token:
+        raise AuthError("no refresh token returned; remove prior grants and retry")
+    conf = json.loads(path.read_text())
+    client = conf.get("installed") or conf.get("web") or {}
+    store.set("refresh_token", creds.refresh_token)
+    store.set("client_id", client.get("client_id", creds.client_id or ""))
+    store.set("client_secret", client.get("client_secret", creds.client_secret or ""))
+    return "authorized; credentials stored"
+
+
+def _refresh(creds: Credentials) -> None:
+    creds.refresh(GoogleRequest())
+
+
+def get_credentials(store: SecretStore | None = None) -> Credentials:
+    """Rebuild Credentials from the secret store and refresh the access token."""
+    store = store or get_store()
+    refresh_token = store.get("refresh_token")
+    client_id = store.get("client_id")
+    client_secret = store.get("client_secret")
+    if not (refresh_token and client_id and client_secret):
+        raise AuthError(
+            "no stored credentials; run `yt-studio-mcp auth --client-secret <path>` first"
+        )
+    creds = Credentials(
+        token=None,
+        refresh_token=refresh_token,
+        client_id=client_id,
+        client_secret=client_secret,
+        token_uri=TOKEN_URI,
+        scopes=SCOPES,
+    )
+    try:
+        _refresh(creds)
+    except Exception as exc:
+        raise AuthError(
+            f"token refresh failed ({exc}); re-run `yt-studio-mcp auth`"
+        ) from exc
+    return creds

yt_studio_mcp-0.1.0/src/yt_studio_mcp/client.py

@@ -0,0 +1,145 @@
+"""Google API client wrapper: quota accounting, error mapping, logging."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any
+
+from googleapiclient.errors import HttpError
+
+logger = logging.getLogger("yt_studio_mcp")
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+
+# Data API v3 quota costs (units) by operation family.
+COSTS = {
+    "list": 1,
+    "insert": 50,
+    "update": 50,
+    "delete": 50,
+    "setModerationStatus": 50,
+    "markAsSpam": 50,
+    "thumbnails.set": 50,
+    "videos.insert": 1600,
+    "captions.insert": 400,
+    "captions.update": 450,
+    "captions.download": 200,
+    "analytics.query": 0,
+}
+
+HINTS = {
+    "quotaExceeded": "Daily quota exhausted; resets midnight Pacific. Check quota_status().",
+    "forbidden": "Check the authorized channel and OAuth scopes; re-run `yt-studio-mcp auth`.",
+    "notFound": "The referenced resource id does not exist or is not visible to this channel.",
+    "authError": "Re-run `yt-studio-mcp auth`.",
+    "commentsDisabled": "Comments are disabled on that video.",
+}
+
+
+class ApiError(RuntimeError):
+    def __init__(self, reason: str, status: int, detail: str):
+        self.reason = reason
+        self.status = status
+        self.hint = HINTS.get(reason, "")
+        super().__init__(f"{reason} (HTTP {status}): {detail} {self.hint}".strip())
+
+
+class QuotaTracker:
+    def __init__(self) -> None:
+        self.spent = 0
+        self.calls = 0
+
+    def add(self, cost: int) -> None:
+        self.spent += cost
+        self.calls += 1
+
+
+class YT:
+    """Lazy holder for the Data v3 and Analytics v2 services."""
+
+    def __init__(self, data_service: Any = None, analytics_service: Any = None):
+        self._data = data_service
+        self._analytics = analytics_service
+        self.quota = QuotaTracker()
+
+    @property
+    def data(self) -> Any:
+        if self._data is None:
+            from googleapiclient.discovery import build
+
+            from .auth import get_credentials
+
+            self._data = build(
+                "youtube", "v3", credentials=get_credentials(), cache_discovery=False
+            )
+        return self._data
+
+    @property
+    def analytics(self) -> Any:
+        if self._analytics is None:
+            from googleapiclient.discovery import build
+
+            from .auth import get_credentials
+
+            self._analytics = build(
+                "youtubeAnalytics", "v2", credentials=get_credentials(), cache_discovery=False
+            )
+        return self._analytics
+
+    def call(self, request: Any, op: str = "list") -> dict:
+        """Execute a prepared API request with quota accounting and error mapping."""
+        cost = COSTS.get(op, COSTS.get(op.split(".")[-1], 1))
+        started = time.monotonic()
+        try:
+            result = request.execute()
+            self.quota.add(cost)
+            logger.info("api op=%s cost=%s ms=%d", op, cost, (time.monotonic() - started) * 1000)
+            return result if result is not None else {}
+        except HttpError as exc:
+            self.quota.add(cost)
+            reason = "unknown"
+            detail = str(exc)
+            try:
+                body = json.loads(exc.content.decode())
+                err = body.get("error", {})
+                detail = err.get("message", detail)
+                errors = err.get("errors") or [{}]
+                reason = errors[0].get("reason", err.get("status", "unknown"))
+            except Exception:  # noqa: BLE001 - best-effort body parse
+                pass
+            logger.error("api op=%s failed reason=%s detail=%s", op, reason, detail)
+            raise ApiError(reason, exc.resp.status if exc.resp else 0, detail) from exc
+
+    def paginate(self, resource: Any, op: str, limit: int, **params) -> list[dict]:
+        """Collect up to `limit` items across pages of a .list endpoint."""
+        items: list[dict] = []
+        token = None
+        while len(items) < limit:
+            page = self.call(
+                resource.list(**params, maxResults=min(50, limit - len(items)), pageToken=token),
+                op=op,
+            )
+            items.extend(page.get("items", []))
+            token = page.get("nextPageToken")
+            if not token:
+                break
+        return items[:limit]
+
+
+def preview(action: str, would: dict) -> dict:
+    return {"preview": True, "action": action, "would": would}
+
+
+_yt: YT | None = None
+
+
+def get_yt() -> YT:
+    global _yt
+    if _yt is None:
+        _yt = YT()
+    return _yt