socialcli 0.3.0__py3-none-any.whl

socialctl/management/stories_cli.py

@@ -0,0 +1,172 @@
+"""Safe, auditable CLI for preparing, applying and verifying Stories."""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import httpx
+import typer
+from socialctl.approval_cli import read_approval
+from pydantic import ValidationError
+
+from socialctl.management.changes import ChangeError
+from socialctl.management.cli import DEFAULT_ROOT, _brand, _fail
+from socialctl.management.stories import (
+    MetaStoryClient,
+    StoryError,
+    StoryStore,
+    apply_story,
+    prepare_story,
+    verify_story,
+)
+from socialctl.media import MediaInvalida, MediaNoEncontrada, leer_media
+from socialctl.models import Platform, StoryPost
+from socialctl.rutas import validar_ruta_relativa
+
+
+story_app = typer.Typer(
+    help="Durable Instagram Stories and explicit handoff for Facebook Page Stories."
+)
+
+
+def make_http_client() -> httpx.Client:
+    return httpx.Client(timeout=30.0, follow_redirects=False)
+
+
+def _json(value) -> str:
+    if hasattr(value, "model_dump"):
+        value = value.model_dump(mode="json")
+    return json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True)
+
+
+def render_story_preview(change) -> str:
+    delivery = (
+        "Instagram: media_type=STORIES will be sent; text is editorial reference and is not sent. "
+        "Public API is documented, but this account's write grant is unverified."
+        if change.story.platform is Platform.INSTAGRAM
+        else "Facebook: Page Stories has a public API, but socialcli does not implement its separate flow yet; apply returns handoff_required without POST."
+    )
+    return (
+        "FULL PREVIEW — standalone Story\n"
+        + _json(change)
+        + f"\n{delivery}"
+        + "\nLocal media is not modified, generated or reencoded."
+        + f"\nExact fingerprint for approval: {change.fingerprint}"
+    )
+
+
+def _expiry(value: str | None) -> datetime:
+    if value is None:
+        return datetime.now(timezone.utc) + timedelta(hours=24)
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except (TypeError, ValueError):
+        raise StoryError("--expires-at must be an ISO 8601 timestamp with timezone") from None
+    if parsed.utcoffset() is None:
+        raise StoryError("--expires-at must include a timezone")
+    return parsed
+
+
+@story_app.command("prepare")
+def prepare(
+    platform: Platform = typer.Option(..., "--platform", help="instagram or facebook."),
+    media: str = typer.Option(..., "--media", help="Relative path inside <Brand>/media/."),
+    media_url: str | None = typer.Option(None, "--media-url", help="Exact public HTTPS URL; required for Instagram."),
+    text: str | None = typer.Option(None, "--text", help="Optional editorial text; Instagram does not receive it in F2."),
+    expires_at: str | None = typer.Option(None, "--expires-at", help="ISO 8601 expiry; default 24 hours."),
+    source_video_id: str | None = typer.Option(None, "--source-video-id", "--youtube-video-id", help="Optional related long-form YouTube video ID."),
+    brand: str = typer.Option(..., "--brand", help="Owning brand; never inferred."),
+    root: Path = typer.Option(DEFAULT_ROOT, "--root", help="Social project root."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Prepare and display local ChangeSet; never write to Meta."),
+) -> None:
+    """Validate and persist local proposal without any remote request."""
+    selected = _brand(root, brand)
+    try:
+        path = validar_ruta_relativa(
+            selected.raiz / "media", media, StoryError, "Story media"
+        )
+        asset = leer_media(path, ruta_relativa=media)
+        story = StoryPost(
+            platform=platform,
+            media=asset,
+            public_url=media_url,
+            text=text,
+            expires_at=_expiry(expires_at),
+            source_video_id=source_video_id,
+        )
+        change = prepare_story(selected, StoryStore(selected.raiz), story)
+    except (ChangeError, MediaNoEncontrada, MediaInvalida, ValidationError) as exc:
+        _fail(str(exc))
+    typer.echo("Remote DRY-RUN: local proposal persisted; no Meta writes.")
+    typer.echo(render_story_preview(change))
+
+
+@story_app.command("status")
+def status(
+    change_id: str,
+    brand: str = typer.Option(..., "--brand", help="Owning brand; never inferred."),
+    root: Path = typer.Option(DEFAULT_ROOT, "--root", help="Social project root."),
+) -> None:
+    """Display ChangeSet and journal without credentials or remote calls."""
+    selected = _brand(root, brand)
+    try:
+        change = StoryStore(selected.raiz).load(change_id)
+    except ChangeError as exc:
+        _fail(str(exc))
+    typer.echo(_json(change))
+
+
+@story_app.command("apply")
+def apply(
+    change_id: str,
+    approval_stdin: bool = typer.Option(False, "--approval-stdin", help="Explicitly read one approval line from stdin."),
+    approval_digest: str | None = typer.Option(None, "--approval-fingerprint", "--approval", "--approval-digest", help="Exact fingerprint displayed by prepare."),
+    brand: str = typer.Option(..., "--brand", help="Owning brand; never inferred."),
+    root: Path = typer.Option(DEFAULT_ROOT, "--root", help="Social project root."),
+) -> None:
+    """Require exact fingerprint and apply without repeating uncertain POSTs."""
+    selected = _brand(root, brand)
+    store = StoryStore(selected.raiz)
+    try:
+        prepared = store.load(change_id)
+        typer.echo(render_story_preview(prepared))
+        digest = read_approval(approval_digest, approval_stdin=approval_stdin)
+        if digest != prepared.fingerprint:
+            raise StoryError("approval does not match exact Story fingerprint")
+        if prepared.story.platform is Platform.FACEBOOK:
+            result = apply_story(None, store, change_id, digest, brand=selected)
+        else:
+            with make_http_client() as http:
+                client = MetaStoryClient(selected, Platform.INSTAGRAM, http)
+                result = apply_story(client, store, change_id, digest)
+    except (ChangeError, OSError, ValueError) as exc:
+        _fail(str(exc))
+    typer.echo(_json(result))
+    if result.status != "verified":
+        raise typer.Exit(1)
+
+
+@story_app.command("verify")
+def verify(
+    change_id: str,
+    brand: str = typer.Option(..., "--brand", help="Owning brand; never inferred."),
+    root: Path = typer.Option(DEFAULT_ROOT, "--root", help="Social project root."),
+) -> None:
+    """Use GET only to verify an already persisted remote ID; never publish."""
+    selected = _brand(root, brand)
+    store = StoryStore(selected.raiz)
+    try:
+        prepared = store.load(change_id)
+        if prepared.story.platform is Platform.FACEBOOK:
+            result = prepared
+        else:
+            with make_http_client() as http:
+                result = verify_story(
+                    MetaStoryClient(selected, Platform.INSTAGRAM, http), store, change_id
+                )
+    except (ChangeError, OSError, ValueError) as exc:
+        _fail(str(exc))
+    typer.echo(_json(result))
+    if result.status != "verified":
+        raise typer.Exit(1)

socialctl/management/youtube.py

@@ -0,0 +1,323 @@
+"""Safe YouTube metadata inspection and editing via standard Data API endpoints; V1 edits snippet, V2 validates other parts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+
+from socialctl.agent_errors import with_error_code, with_http_error_code
+from socialctl.adapters.errores import mensaje_de_error
+from socialctl.auth import AuthError, obtener_token
+from socialctl.brands import Brand
+from socialctl.models import Platform
+
+CHANNELS_URL = "https://www.googleapis.com/youtube/v3/channels"
+VIDEOS_URL = "https://www.googleapis.com/youtube/v3/videos"
+
+WRITABLE_SNIPPET_FIELDS = frozenset(
+    {
+        "title",
+        "description",
+        "tags",
+        "categoryId",
+        "defaultLanguage",
+        "defaultAudioLanguage",
+    }
+)
+READ_ONLY_SNIPPET_FIELDS = frozenset(
+    {
+        "publishedAt",
+        "channelId",
+        "thumbnails",
+        "channelTitle",
+        "liveBroadcastContent",
+        "localized",
+    }
+)
+
+
+class YouTubeManagementError(RuntimeError):
+    """Safe read or identity validation failure."""
+
+
+class YouTubeUpdateRejected(YouTubeManagementError):
+    """YouTube unequivocally rejected the write."""
+
+    def __init__(self, message: str, *, diagnostic: dict[str, str] | None = None):
+        super().__init__(message)
+        self.diagnostic = diagnostic
+
+
+class YouTubeUpdateConflict(YouTubeUpdateRejected):
+    """ETag changed between reread and PUT (HTTP 412)."""
+
+
+class YouTubeUpdateUncertain(YouTubeManagementError):
+    """Whether PUT was applied cannot be determined reliably."""
+
+
+# Only recognized reason identifiers may enter journals; provider prose is excluded.
+_REJECTION_REASONS = frozenset({
+    "quotaExceeded", "dailyLimitExceeded", "rateLimitExceeded", "userRateLimitExceeded",
+    "insufficientPermissions", "forbidden", "forbiddenPrivacySetting",
+    "invalidTitle", "invalidDescription", "invalidVideoMetadata", "invalidValue",
+    "invalidPublishAt", "invalidCategoryId", "invalidTags", "invalidDefaultLanguage",
+    "defaultLanguageNotSet", "localizationValidationError", "videoNotFound",
+    "videoChartNotFound", "uploadLimitExceeded", "badRequest", "authError",
+})
+
+
+def _rejection_diagnostic(response: httpx.Response) -> dict[str, str]:
+    """Keep bounded classification, never provider prose, bodies, URLs or headers."""
+    status = str(response.status_code)
+    reasons = []
+    try:
+        errors = response.json()["error"]["errors"]
+        if isinstance(errors, list):
+            for item in errors[:16]:
+                reason = item.get("reason") if isinstance(item, dict) else None
+                if isinstance(reason, str) and reason in _REJECTION_REASONS and reason not in reasons:
+                    reasons.append(reason)
+    except (ValueError, KeyError, TypeError):
+        pass
+    diagnostic = {"http_status": status}
+    if reasons:
+        diagnostic["reason"] = ",".join(reasons)
+    reason_text = f"; reason={diagnostic['reason']}" if reasons else ""
+    diagnostic["error"] = f"YouTube rejected videos.update (HTTP {status}{reason_text}); no change applied."
+    if "insufficientPermissions" in reasons:
+        diagnostic["error"] += " Check granted youtube.force-ssl or youtube management permission."
+    return diagnostic
+
+
+@dataclass(frozen=True)
+class InspectedVideo:
+    video_id: str
+    channel_id: str
+    etag: str
+    snippet: dict[str, Any]
+
+
+class YouTubeManagementClient:
+    """Inspect a video and update only its complete snippet."""
+
+    def __init__(self, brand: Brand, client: httpx.Client) -> None:
+        self.brand = brand
+        self.client = client
+
+    @property
+    def configured_channel_id(self) -> str:
+        account = self.brand.cuentas.get("youtube") or {}
+        channel_id = account.get("channel_id") if isinstance(account, dict) else None
+        if not isinstance(channel_id, str) or not channel_id.strip():
+            raise YouTubeManagementError(
+                f"youtube.channel_id missing in {self.brand.raiz / 'accounts.yml'}"
+            )
+        return channel_id
+
+    def inspect(self, video_id: str) -> InspectedVideo:
+        """Read video after verifying configured account, token and ownership."""
+        if not isinstance(video_id, str) or not video_id.strip():
+            raise YouTubeManagementError("video ID is empty")
+
+        configured = self.configured_channel_id
+        token = self._token()
+        authenticated = self._authenticated_channel(token)
+        if authenticated != configured:
+            raise YouTubeManagementError(
+                "authenticated channel does not match brand youtube.channel_id "
+                f"{self.brand.nombre}: authenticated={authenticated}, configured={configured}"
+            )
+
+        payload = self._get_json(
+            VIDEOS_URL,
+            token,
+            params={"part": "snippet", "id": video_id},
+            operation="read video",
+        )
+        items = payload.get("items") if isinstance(payload, dict) else None
+        if not isinstance(items, list) or not items:
+            raise YouTubeManagementError(
+                f"YouTube did not return video {video_id}; check its ID and permissions"
+            )
+        item = items[0]
+        if not isinstance(item, dict) or item.get("id") != video_id:
+            raise YouTubeManagementError("YouTube returned an unexpected video resource")
+        snippet = item.get("snippet")
+        if not isinstance(snippet, dict):
+            raise YouTubeManagementError("YouTube returned an invalid video snippet")
+
+        channel_id = snippet.get("channelId")
+        if channel_id != configured:
+            raise YouTubeManagementError(
+                f"video {video_id} does not belong to the configured channel for "
+                f"{self.brand.nombre}"
+            )
+
+        unknown = set(snippet) - WRITABLE_SNIPPET_FIELDS - READ_ONLY_SNIPPET_FIELDS
+        if unknown:
+            names = ", ".join(sorted(unknown))
+            raise YouTubeManagementError(
+                "snippet contains an unknown field with uncertain mutability: "
+                f"{names}; editing rejected to avoid dropping it"
+            )
+
+        etag = item.get("etag")
+        if not isinstance(etag, str) or not etag:
+            raise YouTubeManagementError(
+                "YouTube did not return an ETag; editing rejected to avoid overwriting "
+                "a concurrent change"
+            )
+        return InspectedVideo(
+            video_id=video_id,
+            channel_id=channel_id,
+            etag=etag,
+            snippet=dict(snippet),
+        )
+
+    def update_snippet(
+        self, video_id: str, snippet: dict[str, Any], *, etag: str
+    ) -> None:
+        self._update_parts(video_id, {"snippet": snippet}, etag=etag)
+
+    def _update_parts(
+        self, video_id: str, parts: dict[str, Any], *, etag: str,
+        before_put: Callable[[], None] | None = None,
+    ) -> None:
+        """Send one conditional PUT for caller-validated parts. Transport/5xx errors are uncertain; 412 conflicts and other 4xx rejections are definitive."""
+        if not etag:
+            raise YouTubeUpdateRejected("cannot update without ETag")
+        configured = self.configured_channel_id
+        token = self._token()
+        authenticated = self._authenticated_channel(token)
+        if authenticated != configured:
+            raise YouTubeUpdateRejected(
+                "authenticated channel changed before videos.update; PUT was not sent"
+            )
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "If-Match": etag,
+            "Content-Type": "application/json",
+        }
+        body = {"id": video_id, **parts}
+        # Time-sensitive outgoing metadata must be checked after token refresh
+        # and final authenticated-channel lookup, immediately before the PUT.
+        if before_put is not None:
+            before_put()
+        try:
+            response = self.client.put(
+                VIDEOS_URL,
+                headers=headers,
+                params={"part": ",".join(sorted(parts))},
+                json=body,
+            )
+        except httpx.TimeoutException:
+            raise YouTubeUpdateUncertain(
+                "uncertain outcome: videos.update timed out"
+            ) from None
+        except (httpx.HTTPError, httpx.InvalidURL):
+            raise YouTubeUpdateUncertain(
+                "uncertain outcome: connection lost during videos.update"
+            ) from None
+        except Exception:
+            raise YouTubeUpdateUncertain(
+                "uncertain outcome: unexpected failure during videos.update"
+            ) from None
+
+        error = mensaje_de_error(response, token)
+        if response.status_code == 412:
+            raise YouTubeUpdateConflict(
+                "ETag conflict (HTTP 412 conditionNotMet); PUT was not retried"
+            )
+        if 500 <= response.status_code:
+            raise YouTubeUpdateUncertain(
+                f"uncertain outcome after videos.update: {error}"
+            )
+        if not response.is_success:
+            diagnostic = _rejection_diagnostic(response)
+            raise YouTubeUpdateRejected(diagnostic["error"], diagnostic=diagnostic)
+
+        try:
+            payload = response.json()
+        except Exception:
+            raise YouTubeUpdateUncertain(
+                "uncertain outcome: videos.update returned unverifiable JSON"
+            ) from None
+        if not isinstance(payload, dict) or payload.get("id") != video_id:
+            raise YouTubeUpdateUncertain(
+                "uncertain outcome: videos.update returned an unexpected resource"
+            )
+
+    def editable_snippet(self, inspected: InspectedVideo) -> dict[str, Any]:
+        """Extract all present writable fields without inventing absent values."""
+        return {
+            key: inspected.snippet[key]
+            for key in WRITABLE_SNIPPET_FIELDS
+            if key in inspected.snippet
+        }
+
+    def _token(self) -> str:
+        try:
+            return obtener_token(self.brand, Platform.YOUTUBE, self.client)
+        except AuthError as exc:
+            raise with_error_code(YouTubeManagementError(str(exc)), exc, read_only=True) from None
+        except Exception as exc:
+            # Un fallo imprevisto podría arrastrar el secreto en su texto.
+            raise with_error_code(YouTubeManagementError("failed to read or refresh YouTube credentials"), exc, read_only=True, fallback="authorization_unavailable") from None
+
+    def _authenticated_channel(self, token: str) -> str:
+        payload = self._get_json(
+            CHANNELS_URL,
+            token,
+            params={"part": "id", "mine": "true"},
+            operation="check authenticated channel",
+        )
+        items = payload.get("items") if isinstance(payload, dict) else None
+        if not isinstance(items, list) or not items or not isinstance(items[0], dict):
+            raise YouTubeManagementError(
+                "Data API returned no channel for the brand token"
+            )
+        channel_id = items[0].get("id")
+        if not isinstance(channel_id, str) or not channel_id:
+            raise YouTubeManagementError("Data API returned an invalid authenticated channel")
+        return channel_id
+
+    def _get_json(
+        self, url: str, token: str, *, params: dict[str, str], operation: str
+    ) -> dict[str, Any]:
+        try:
+            response = self.client.get(
+                url, headers={"Authorization": f"Bearer {token}"}, params=params
+            )
+        except httpx.TimeoutException as exc:
+            raise with_error_code(YouTubeManagementError(
+                f"timed out while attempting to {operation} on YouTube"), exc, read_only=True) from None
+        except (httpx.HTTPError, httpx.InvalidURL) as exc:
+            raise with_error_code(YouTubeManagementError(
+                f"failed to connect to YouTube to {operation}"), exc, read_only=True) from None
+        except Exception:
+            raise YouTubeManagementError(
+                f"unexpected failure during {operation} on YouTube"
+            ) from None
+        if not response.is_success:
+            detail = mensaje_de_error(response, token)
+            if response.status_code == 403:
+                raise with_http_error_code(YouTubeManagementError(
+                    f"YouTube did not allow {operation}; check youtube.readonly. "
+                    f"Detail: {detail}"), response, read_only=True)
+            raise with_http_error_code(YouTubeManagementError(
+                f"YouTube returned {response.status_code} during {operation}: {detail}"), response, read_only=True)
+        try:
+            payload = response.json()
+        except Exception:
+            raise YouTubeManagementError(
+                f"YouTube returned a non-JSON response during {operation}"
+            ) from None
+        if not isinstance(payload, dict):
+            raise YouTubeManagementError(
+                f"YouTube returned an invalid response during {operation}"
+            )
+        return payload