youtube-kit 0.2.0__py3-none-any.whl

youtube_kit/cli.py

@@ -0,0 +1,217 @@
+"""`ytk`: the command-line adapter over the core operations.
+
+Contract (relied on by agents and scripts, documented in skills/youtube/SKILL.md):
+- stdout carries exactly one JSON document per successful command, nulls omitted.
+- Failures print {"error": {"type", "message", "details"?}} to stderr and exit
+  with the error's code: 2 invalid input, 3 not found, 4 not authorized, 5 quota
+  exceeded, 6 forbidden, 7 network, 8 confirmation required, 9 protected,
+  10 timeout, 1 anything else (type "error"). Usage errors from argument parsing exit 2 with type
+  "usage" (as formatted text when stderr is a terminal).
+- Guarded deletes ask a human at a terminal instead of exiting 8; declining exits 1.
+  For agents, the exit-8 details include `rerun`, the exact command that confirms.
+"""
+
+import contextlib
+import json
+import shlex
+import sys
+from collections.abc import Iterator, Sequence
+from importlib.metadata import version
+from typing import Annotated
+
+import cyclopts
+import pydantic_core
+from cyclopts import CycloptsError
+
+from . import core
+from .core import auth, progress
+from .core.config import Settings
+from .core.models import AuthStatus
+from .core.ops import analytics, branding, channels, comments, playlists, search, subscriptions, videos
+
+app = cyclopts.App(
+    name="ytk",
+    help="YouTube Data and Analytics APIs from the command line. Prints JSON; see `ytk <command> --help`.",
+    version=version("youtube-kit"),
+    # No --no-X / --empty-X flags, except on update commands where "unset" and "clear" mean something.
+    default_parameter=cyclopts.Parameter(negative_bool=(), negative_iterable=()),
+)
+
+video = app.command(cyclopts.App(name="video", help="Look up, upload, edit, and delete videos."))
+playlist = app.command(cyclopts.App(name="playlist", help="Look up and manage playlists."))
+comment = app.command(cyclopts.App(name="comment", help="Read, write, and moderate comments."))
+channel = app.command(cyclopts.App(name="channel", help="Look up channels, and brand your own."))
+watermark = channel.command(cyclopts.App(name="watermark", help="The subscribe watermark shown over your videos."))
+section = channel.command(cyclopts.App(name="section", help="Sections on a channel's home page."))
+subscription = app.command(cyclopts.App(name="subscription", help="Your subscriptions to other channels."))
+auth_app = app.command(cyclopts.App(name="auth", help="Authorize access to your YouTube account."))
+
+_NEGATIVES = cyclopts.Parameter(negative_bool=None, negative_iterable=None)
+
+app.command(search.search, name="search")
+app.command(analytics.get_analytics, name="analytics")
+
+video.command(videos.get_videos, name="get")
+video.command(videos.list_video_categories, name="categories")
+video.command(videos.upload_video, name="upload")
+video.command(videos.get_processing_status, name="status")
+video.command(videos.update_video, name="update", default_parameter=_NEGATIVES)
+video.command(videos.set_thumbnail, name="thumbnail")
+video.command(videos.rate_video, name="rate")
+video.command(videos.get_my_ratings, name="rating")
+video.command(videos.delete_video, name="delete")
+
+playlist.command(playlists.list_playlists, name="list")
+playlist.command(playlists.get_playlists, name="get")
+playlist.command(playlists.list_playlist_items, name="items")
+playlist.command(playlists.create_playlist, name="create")
+playlist.command(playlists.update_playlist, name="update")
+playlist.command(playlists.set_playlist_thumbnail, name="thumbnail")
+playlist.command(playlists.delete_playlist, name="delete")
+playlist.command(playlists.add_video_to_playlist, name="add")
+playlist.command(playlists.remove_from_playlist, name="remove")
+playlist.command(playlists.move_in_playlist, name="move")
+
+comment.command(comments.list_comments, name="list")
+comment.command(comments.list_replies, name="replies")
+comment.command(comments.post_comment, name="post")
+comment.command(comments.reply_to_comment, name="reply")
+comment.command(comments.edit_comment, name="edit")
+comment.command(comments.delete_comment, name="delete")
+comment.command(comments.approve_comments, name="approve")
+comment.command(comments.hold_comments, name="hold")
+comment.command(comments.reject_comments, name="reject")
+
+channel.command(channels.get_channel, name="get")
+channel.command(channels.list_activities, name="activity")
+channel.command(branding.update_channel, name="update", default_parameter=_NEGATIVES)
+channel.command(branding.set_channel_banner, name="banner")
+watermark.command(branding.set_watermark, name="set")
+watermark.command(branding.remove_watermark, name="remove")
+section.command(branding.list_sections, name="list")
+section.command(branding.add_section, name="add")
+section.command(branding.update_section, name="update")
+section.command(branding.delete_section, name="delete")
+
+subscription.command(subscriptions.list_subscriptions, name="list")
+subscription.command(subscriptions.subscribe, name="add")
+subscription.command(subscriptions.unsubscribe, name="remove")
+
+
+@auth_app.command(name="login")
+# negative_bool=None brings back --no-browser, which the app-wide default turns off.
+def auth_login(*, browser: Annotated[bool, cyclopts.Parameter(negative_bool=None)] = True) -> AuthStatus:
+    """Authorize your YouTube account through Google's OAuth consent screen.
+
+    Needs an OAuth client of type "Desktop app" saved as client_secrets.json
+    (see `ytk auth status` for the path). The token is stored for both the CLI
+    and the MCP server.
+
+    Args:
+        browser: Open the consent page automatically. With --no-browser, open the printed URL yourself.
+    """
+    # The OAuth library prints the consent URL to stdout, which is reserved for JSON.
+    with contextlib.redirect_stdout(sys.stderr):
+        return auth.login(Settings.from_env(), open_browser=browser)
+
+
+@auth_app.command(name="status")
+def auth_status() -> AuthStatus:
+    """Show which credentials are configured and where they are stored. Makes no API calls."""
+    return auth.status(Settings.from_env())
+
+
+@auth_app.command(name="logout")
+def auth_logout() -> AuthStatus:
+    """Delete the stored OAuth token. The API key, if any, is unaffected."""
+    return auth.logout(Settings.from_env())
+
+
+@app.command(name="mcp")
+def serve_mcp() -> None:
+    """Run the MCP server over stdio, exposing the same operations as tools."""
+    from . import mcp_server  # deferred: FastMCP is slow to import and only needed here
+
+    mcp_server.run()
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    human = sys.stderr.isatty()
+    try:
+        with _terminal_progress():
+            result = app(argv, exit_on_error=False, print_error=human, result_action="return_value")
+    except CycloptsError as e:
+        if not human:  # a person got cyclopts' formatted message already
+            print(json.dumps({"error": {"type": "usage", "message": str(e)}}, ensure_ascii=False), file=sys.stderr)
+        return 2
+    except core.ConfirmationRequired as e:
+        confirmed = _with_confirm(argv, e.details["confirm"])
+        if not (sys.stdin.isatty() and sys.stderr.isatty()):
+            e.details["rerun"] = shlex.join(["ytk", *confirmed])
+            return _fail(e)
+        if not _approved(e.details):
+            print("Cancelled; nothing was deleted.", file=sys.stderr)
+            return 1
+        # Rerunning fetches and checks the target again rather than trusting what was shown.
+        return main(confirmed)
+    except core.YouTubeError as e:
+        return _fail(e)
+    except KeyboardInterrupt:
+        return 130
+    except Exception as e:  # noqa: BLE001  -- keep the JSON contract even for bugs and odd responses
+        return _fail(core.YouTubeError(f"{type(e).__name__}: {e}"))
+    if result is not None:
+        indent = 2 if sys.stdout.isatty() else None
+        try:
+            print(pydantic_core.to_json(result, indent=indent, exclude_none=True).decode())
+        except BrokenPipeError:  # e.g. piped into head
+            sys.stdout = None  # stop the interpreter's final flush from raising again
+    return 0
+
+
+def _fail(error: core.YouTubeError) -> int:
+    body = {"type": error.kind, "message": str(error)}
+    if error.details:
+        body["details"] = error.details
+    print(json.dumps({"error": body}, ensure_ascii=False), file=sys.stderr)
+    return error.exit_code
+
+
+def _with_confirm(argv: list[str], value: str) -> list[str]:
+    end = argv.index("--") if "--" in argv else len(argv)
+    return [*argv[:end], "--confirm", value, *argv[end:]]
+
+
+def _approved(plan: dict) -> bool:
+    print(f"About to permanently delete {plan['kind']} {plan['confirm']}:", file=sys.stderr)
+    for key, value in plan.items():
+        if key not in {"kind", "confirm"}:
+            print(f"  {key}: {str(value).replace(chr(10), chr(10) + '    ')}", file=sys.stderr)
+    print("Delete it? [y/N] ", end="", file=sys.stderr, flush=True)
+    return sys.stdin.readline().strip().lower() in {"y", "yes"}
+
+
+@contextlib.contextmanager
+def _terminal_progress() -> Iterator[None]:
+    """Show a self-overwriting percentage on stderr when a human is watching.
+
+    The line is ended on exit, before any error is printed after it.
+    """
+    if not sys.stderr.isatty():
+        yield
+        return
+    shown = False
+
+    def show(done: int, total: int) -> None:
+        nonlocal shown
+        shown = True
+        percent = 100 * done // total if total else 100
+        print(f"\rprogress: {percent:3d}%", end="", file=sys.stderr, flush=True)
+
+    try:
+        with progress.reporting_to(show):
+            yield
+    finally:
+        if shown:
+            print(file=sys.stderr)

youtube_kit/core/__init__.py

@@ -0,0 +1,36 @@
+"""Transport-neutral YouTube Data API core. No printing, no exit codes, no MCP.
+
+Operations live in `core.ops.<noun>` modules; importing this package registers them all in OPERATIONS.
+"""
+
+from . import ops as ops
+from .errors import (
+    ConfirmationRequired,
+    Forbidden,
+    InvalidRequest,
+    NetworkError,
+    NotAuthorized,
+    NotFound,
+    Protected,
+    QuotaExceeded,
+    TimedOut,
+    YouTubeError,
+)
+from .operation import OPERATIONS, OperationInfo, info
+
+__all__ = [
+    "OPERATIONS",
+    "ConfirmationRequired",
+    "Forbidden",
+    "InvalidRequest",
+    "NetworkError",
+    "NotAuthorized",
+    "NotFound",
+    "OperationInfo",
+    "Protected",
+    "QuotaExceeded",
+    "TimedOut",
+    "YouTubeError",
+    "info",
+    "ops",
+]

youtube_kit/core/auth.py

@@ -0,0 +1,103 @@
+"""OAuth token lifecycle: login, load (with refresh), logout, status."""
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+
+from .config import Settings
+from .errors import LOGIN_HINT, NotAuthorized
+from .models import AuthStatus
+
+# Full read/write access to the user's YouTube account: uploads, edits, playlists, comments.
+YOUTUBE = "https://www.googleapis.com/auth/youtube.force-ssl"
+# YouTube Analytics reports, revenue included.
+ANALYTICS = "https://www.googleapis.com/auth/yt-analytics-monetary.readonly"
+SCOPES = [YOUTUBE, ANALYTICS]
+
+
+def load_credentials(settings: Settings, scope: str = YOUTUBE) -> Credentials:
+    """Stored OAuth credentials, refreshed and re-saved if expired. They must include `scope`."""
+    if not settings.token_file.exists():
+        raise NotAuthorized(f"No OAuth token at {settings.token_file}. {LOGIN_HINT}")
+    try:
+        info = json.loads(settings.token_file.read_text())
+    except ValueError as e:
+        raise NotAuthorized(f"OAuth token at {settings.token_file} is unreadable ({e}). {LOGIN_HINT}") from e
+    # The token lists the scopes Google granted; the user may have unticked some, or logged in before
+    # a scope was added. A refresh can't add scopes; the only fix is logging in again. Tokens from
+    # elsewhere may not list scopes at all; Google then answers for itself.
+    if "scopes" in info and scope not in info["scopes"]:
+        access = "analytics" if scope == ANALYTICS else "YouTube"
+        raise NotAuthorized(f"Your login doesn't grant {access} access. {LOGIN_HINT} Allow every requested permission.")
+    try:
+        creds = Credentials.from_authorized_user_info(info)
+    except ValueError as e:
+        raise NotAuthorized(f"OAuth token at {settings.token_file} is incomplete ({e}). {LOGIN_HINT}") from e
+    if creds.valid:
+        return creds
+    if not creds.refresh_token:
+        raise NotAuthorized(f"OAuth token at {settings.token_file} expired and cannot be refreshed. {LOGIN_HINT}")
+    creds.refresh(Request())
+    _save_token(settings.token_file, json.loads(creds.to_json()))
+    return creds
+
+
+def login(settings: Settings, *, open_browser: bool = True) -> AuthStatus:
+    """Run the installed-app OAuth flow and store the token. Prints the auth URL to stdout."""
+    if not settings.client_secrets_file.exists():
+        raise NotAuthorized(
+            f"OAuth client secrets not found at {settings.client_secrets_file}. "
+            "In Google Cloud Console, enable YouTube Data API v3, create an OAuth client ID "
+            "of type 'Desktop app', and save its JSON to that path "
+            "(or point YOUTUBE_CLIENT_SECRETS at it)."
+        )
+    # Google lets users untick scopes; without this, oauthlib raises instead of returning what was granted.
+    os.environ.setdefault("OAUTHLIB_RELAX_TOKEN_SCOPE", "1")
+    flow = InstalledAppFlow.from_client_secrets_file(str(settings.client_secrets_file), SCOPES)
+    # prompt=consent: without it Google may omit the refresh token when re-authorizing.
+    creds = flow.run_local_server(port=0, open_browser=open_browser, prompt="consent")
+    info = json.loads(creds.to_json())
+    info["scopes"] = creds.granted_scopes or SCOPES  # Google omits the list when all were granted
+    _save_token(settings.token_file, info)
+    return status(settings)
+
+
+def logout(settings: Settings) -> AuthStatus:
+    """Delete the stored token. Does not revoke it with Google."""
+    settings.token_file.unlink(missing_ok=True)
+    return status(settings)
+
+
+def status(settings: Settings) -> AuthStatus:
+    """What credentials are configured. Local check only; makes no network calls."""
+    try:
+        granted_scopes = json.loads(settings.token_file.read_text()).get("scopes")
+    except (OSError, ValueError, AttributeError):
+        granted_scopes = None
+    return AuthStatus(
+        api_key_set=settings.api_key is not None,
+        token_file=str(settings.token_file),
+        token_present=settings.token_file.exists(),
+        granted_scopes=granted_scopes,
+        client_secrets_file=str(settings.client_secrets_file),
+        client_secrets_present=settings.client_secrets_file.exists(),
+        config_file=str(settings.config_file),
+    )
+
+
+def _save_token(path: Path, info: dict) -> None:
+    # Atomic replace: the CLI and a running MCP server may refresh concurrently.
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=".token-", suffix=".json")
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(info, f)
+        os.replace(tmp, path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise

youtube_kit/core/client.py

@@ -0,0 +1,62 @@
+"""googleapiclient Resources for the YouTube Data and Analytics APIs.
+
+Resources are cached per thread because httplib2 connections are not thread-safe
+and the MCP server runs sync tools on worker threads. The OAuth client is keyed by
+the token file's mtime, so a long-running server picks up `ytk auth login` without
+a restart.
+"""
+
+import threading
+
+from googleapiclient.discovery import Resource, build
+
+from . import auth
+from .config import Settings
+from .errors import LOGIN_HINT, NotAuthorized
+
+_local = threading.local()
+
+
+def public() -> Resource:
+    """Client for public data: the API key if set, otherwise the user's OAuth token."""
+    settings = Settings.from_env()
+    if settings.api_key is None:
+        if not settings.token_file.exists():
+            raise NotAuthorized(f"No credentials. Set YOUTUBE_API_KEY for public data, or: {LOGIN_HINT}")
+        return oauth()
+    return _cached("public", settings.api_key, lambda: _build(developerKey=settings.api_key))
+
+
+def oauth() -> Resource:
+    """Client acting as the authorized user (uploads, edits, own channel)."""
+    settings = Settings.from_env()
+    return _cached("oauth", _token_key(settings), lambda: _build(credentials=auth.load_credentials(settings)))
+
+
+def analytics() -> Resource:
+    """YouTube Analytics client for the authorized user's channel."""
+    settings = Settings.from_env()
+    return _cached(
+        "analytics",
+        _token_key(settings),
+        lambda: _build("youtubeAnalytics", "v2", credentials=auth.load_credentials(settings, auth.ANALYTICS)),
+    )
+
+
+def _token_key(settings: Settings) -> int | None:
+    try:
+        return settings.token_file.stat().st_mtime_ns
+    except FileNotFoundError:
+        return None  # load_credentials raises the actionable error
+
+
+def _cached(slot: str, key: object, make) -> Resource:
+    cached = getattr(_local, slot, None)
+    if cached is None or cached[0] != key:
+        cached = (key, make())
+        setattr(_local, slot, cached)
+    return cached[1]
+
+
+def _build(service: str = "youtube", version: str = "v3", **kwargs) -> Resource:
+    return build(service, version, cache_discovery=False, static_discovery=True, **kwargs)

youtube_kit/core/config.py

@@ -0,0 +1,59 @@
+"""Where credentials and settings come from. Environment variables override the defaults."""
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Self
+
+from platformdirs import user_config_path
+
+from .errors import InvalidRequest
+
+APP_NAME = "youtube-kit"
+
+
+@dataclass(frozen=True)
+class Settings:
+    api_key: str | None
+    token_file: Path
+    client_secrets_file: Path
+    config_file: Path
+
+    @classmethod
+    def from_env(cls) -> Self:
+        config_dir = user_config_path(APP_NAME)
+        return cls(
+            api_key=os.environ.get("YOUTUBE_API_KEY") or None,
+            token_file=_path_env("YOUTUBE_TOKEN_FILE", config_dir / "token.json"),
+            client_secrets_file=_path_env("YOUTUBE_CLIENT_SECRETS", config_dir / "client_secrets.json"),
+            config_file=_path_env("YOUTUBE_CONFIG_FILE", config_dir / "config.toml"),
+        )
+
+
+@dataclass(frozen=True)
+class DeleteProtection:
+    """Videos past either limit can't be deleted through this toolkit."""
+
+    max_views: int = 100
+    max_public_age_days: int = 7
+
+    @classmethod
+    def load(cls, config_file: Path) -> Self:
+        """The [delete_protection] table of the config file; defaults when absent. Bad values are an error."""
+        if not config_file.exists():
+            return cls()
+        try:
+            table = tomllib.loads(config_file.read_text()).get("delete_protection", {})
+            limits = cls(**table)
+        except (tomllib.TOMLDecodeError, TypeError) as e:
+            raise InvalidRequest(f"Invalid {config_file}: {e}") from e
+        for name, value in vars(limits).items():
+            if type(value) is not int or value < 0:
+                raise InvalidRequest(f"Invalid {config_file}: delete_protection.{name} must be a whole number >= 0.")
+        return limits
+
+
+def _path_env(name: str, default: Path) -> Path:
+    value = os.environ.get(name)
+    return Path(value).expanduser() if value else default

youtube_kit/core/errors.py

@@ -0,0 +1,118 @@
+"""Domain errors. Adapters map these to MCP tool errors and CLI exit codes."""
+
+import json
+from typing import Any, ClassVar
+
+from googleapiclient.errors import HttpError
+
+
+class YouTubeError(Exception):
+    """Base class. `kind` is a stable machine-readable name; `exit_code` is the CLI status.
+
+    `details` is optional structured context the caller can act on.
+    """
+
+    kind: ClassVar[str] = "error"
+    exit_code: ClassVar[int] = 1
+
+    def __init__(self, message: str, *, details: dict[str, Any] | None = None):
+        super().__init__(message)
+        self.details = details or {}
+
+
+class InvalidRequest(YouTubeError):
+    kind = "invalid_request"
+    exit_code = 2
+
+
+class NotFound(YouTubeError):
+    kind = "not_found"
+    exit_code = 3
+
+
+class NotAuthorized(YouTubeError):
+    kind = "not_authorized"
+    exit_code = 4
+
+
+class QuotaExceeded(YouTubeError):
+    kind = "quota_exceeded"
+    exit_code = 5
+
+
+class Forbidden(YouTubeError):
+    """Authorized, but YouTube refuses the action (e.g. comments disabled)."""
+
+    kind = "forbidden"
+    exit_code = 6
+
+
+class NetworkError(YouTubeError):
+    """YouTube could not be reached. Safe to retry."""
+
+    kind = "network"
+    exit_code = 7
+
+
+class ConfirmationRequired(YouTubeError):
+    """A guarded delete needs `confirm`; `details` describe the target and the value to pass."""
+
+    kind = "confirmation_required"
+    exit_code = 8
+
+
+class Protected(YouTubeError):
+    """Refused by the delete protection limits. No flag overrides them; only the config file does."""
+
+    kind = "protected"
+    exit_code = 9
+
+
+class TimedOut(YouTubeError):
+    """Waiting for YouTube took longer than allowed. The work may still finish."""
+
+    kind = "timeout"
+    exit_code = 10
+
+
+LOGIN_HINT = "Run `ytk auth login` to authorize your YouTube account."
+API_KEY_HINT = "Check YOUTUBE_API_KEY, or unset it to use your OAuth login for public data too."
+
+_QUOTA_REASONS = {"quotaExceeded", "dailyLimitExceeded"}
+_AUTH_REASONS = {"authError", "insufficientPermissions"}
+
+
+def from_http_error(error: HttpError) -> YouTubeError:
+    """Translate a googleapiclient HttpError into the matching domain error."""
+    status = error.resp.status
+    reason = _first_reason(error.content)
+    message = error.reason or f"HTTP {status}"
+
+    if reason in _QUOTA_REASONS:
+        return QuotaExceeded(f"{message} Daily quota resets at midnight Pacific Time.")
+    if status == 429:
+        return QuotaExceeded(f"{message} Too many requests; retry in a minute.")
+    # A bad key (400) and a missing scope (403) only show their specific reason in the error details.
+    if b"API_KEY_INVALID" in error.content:
+        return NotAuthorized(f"{message} {API_KEY_HINT}")
+    if b"ACCESS_TOKEN_SCOPE_INSUFFICIENT" in error.content:
+        return NotAuthorized(f"{message} {LOGIN_HINT}")
+    if reason == "youtubeSignupRequired":
+        return Forbidden(f"{message} The authorized Google account needs a YouTube channel.")
+    if status == 401 or reason in _AUTH_REASONS:
+        return NotAuthorized(f"{message} {LOGIN_HINT}")
+    if status == 403:
+        return Forbidden(message)
+    if status == 404:
+        return NotFound(message)
+    if status == 400:
+        return InvalidRequest(message)
+    return YouTubeError(f"YouTube API error (HTTP {status}): {message}")
+
+
+def _first_reason(content: bytes) -> str | None:
+    try:
+        errors = json.loads(content)["error"]["errors"]
+        return errors[0]["reason"]
+    except (ValueError, KeyError, IndexError, TypeError):
+        return None

youtube_kit/core/guard.py

@@ -0,0 +1,50 @@
+"""Guards for irreversible deletes: a confirmation bound to the target, and damage limits for videos."""
+
+from datetime import UTC, datetime
+from typing import Any
+
+from .config import DeleteProtection, Settings
+from .errors import ConfirmationRequired, InvalidRequest, Protected
+from .models import Video
+
+
+def require_confirm(kind: str, target_id: str, confirm: str | None, plan: dict[str, Any]) -> None:
+    """Pass only when `confirm` names the target; otherwise describe what would be deleted."""
+    if confirm == target_id:
+        return
+    if confirm is not None:
+        raise InvalidRequest(f"confirm must be {target_id}, the ID being deleted; got {confirm}.")
+    raise ConfirmationRequired(
+        f"Deleting {kind} {target_id} can't be undone. Show the user what will be deleted, "
+        f"and only after they approve, repeat the request with confirm set to {target_id}.",
+        details={"kind": kind, **plan, "confirm": target_id},
+    )
+
+
+def check_protected(video: Video) -> None:
+    """Refuse videos past the configured limits, or whose view count we can't see."""
+    settings = Settings.from_env()
+    limits = DeleteProtection.load(settings.config_file)
+    views = video.stats.views if video.stats else None
+    reasons = []
+    if views is None:
+        reasons.append("its view count is hidden")
+    elif views > limits.max_views:
+        reasons.append(f"it has {views} views (limit {limits.max_views})")
+    if video.privacy == "public":
+        # YouTube only exposes the upload time, so a video made public later counts from its upload.
+        age = (datetime.now(UTC) - video.published_at).days if video.published_at else None
+        if age is None or age > limits.max_public_age_days:
+            uploaded = "at an unknown time" if age is None else f"{age} days ago"
+            reasons.append(f"it is public and was uploaded {uploaded} (limit {limits.max_public_age_days} days)")
+    if reasons:
+        raise Protected(
+            f"Video {video.id} is protected from deletion: {'; '.join(reasons)}. Delete it in YouTube Studio, "
+            f"or raise the limits under [delete_protection] in {settings.config_file}.",
+            details={
+                "studio_url": f"https://studio.youtube.com/video/{video.id}/edit",
+                "config_file": str(settings.config_file),
+                "max_views": limits.max_views,
+                "max_public_age_days": limits.max_public_age_days,
+            },
+        )