socialcli 0.3.0__py3-none-any.whl

socialctl/metricas/youtube.py

@@ -0,0 +1,403 @@
+"""Read YouTube metrics via Data API for catalog/cumulative stats and Analytics API for bounded period metrics and enrichment."""
+
+from __future__ import annotations
+
+import re
+from datetime import date, datetime, timezone
+
+import httpx
+
+from socialctl.adapters.errores import mensaje_de_error
+from socialctl.auth import obtener_token
+from socialctl.brands import Brand
+from socialctl.metricas.base import Lector, SinPermiso
+from socialctl.metricas.modelos import (
+    Audiencia,
+    Cuenta,
+    EstadoLectura,
+    LecturaRed,
+    Metricas,
+    Pieza,
+    TipoPieza,
+)
+from socialctl.models import Platform
+from socialctl.read_budget import ReadDeadlineExceeded
+
+ANALYTICS = "https://youtubeanalytics.googleapis.com/v2/reports"
+CANALES = "https://www.googleapis.com/youtube/v3/channels"
+VIDEOS = "https://www.googleapis.com/youtube/v3/videos"
+
+#: Fecha lo bastante temprana como para cubrir la vida del canal.
+INICIO_DE_LOS_TIEMPOS = "2005-02-14"  # YouTube no existía antes
+
+#: La Data API acepta como mucho 50 ids por petición de `videos.list`.
+LOTE = 50
+
+#: Tope que impone la propia API al informe de "top videos": «Top videos
+#: reports require a sort parameter and a maxResults value of 200 or less»
+#: (developers.google.com/youtube/analytics/channel_reports). Sin `maxResults`
+#: y sin `sort`, la petición responde 400 y no llega ninguna pieza.
+#:
+#: **Consecuencia declarada:** hoy no se pagina. Un canal con más de 200
+#: vídeos no se lee entero: se leen **los 200 más vistos** (por `sort=-views`)
+#: y los demás no aparecen en el snapshot ni en `piezas.yml`. Ninguna marca de
+#: este proyecto se acerca a esa cifra; cuando alguna lo haga, la solución es
+#: paginar con `startIndex` (1, 201, 401…) hasta agotar los resultados, no
+#: subir este número.
+MAX_VIDEOS = 200
+
+#: **Coste de cuota, declarado.** La curva de retención y las fuentes de
+#: tráfico se piden **una petición por pieza cada una** (ver `_retencion` y
+#: `_trafico`): con el techo de `MAX_VIDEOS`, una ejecución puede hacer hasta
+#: 2 × 200 = 400 peticiones a Analytics, además de las del catálogo. Es el
+#: precio de las dos únicas lecturas que **explican** el resultado en vez de
+#: contarlo, y se paga a propósito; lo que el spec (§9) pide -no gastar cuota
+#: de más- se cumple pidiendo solo las métricas necesarias y agrupando
+#: `videos.list` en lotes de 50, no renunciando a la retención.
+#:
+#: **Qué pasa si la cuota se agota antes del bucle** (canal, informe por
+#: vídeo, catálogo): sigue tumbando la lectura entera -sin esas tres
+#: llamadas no hay nada que devolver-, exactamente igual que cualquier otro
+#: fallo ahí. `leer_red` lo convierte en `estado: error` **solo para
+#: YouTube**; las otras tres redes se leen igual y el snapshot del día se
+#: escribe. El remedio es esperar al siguiente día de cuota o acotar con
+#: `--desde`.
+#:
+#: **Qué pasa si se agota DENTRO del bucle (degradar, no perder).** Cada
+#: pieza ya trae sus métricas base -las del informe por vídeo, sin coste
+#: adicional- antes de intentar su retención y su tráfico: perder esas dos
+#: peticiones no tiene por qué tirar lo que ya se pagó. `leer()` aísla el
+#: enriquecimiento de cada pieza (ver `_enriquecer`): si falla, esa pieza se
+#: queda con `curva_retencion: []` y `fuentes_trafico: {}` -nunca
+#: inventadas, la regla de oro del módulo- y el bucle sigue con la
+#: siguiente. Si el fallo es justo cuota agotada -`_pedir` ya distingue hoy
+#: «sin permiso» (`SinPermiso`) de «cualquier otro 403», y ese «cualquier
+#: otro 403» es, por descarte, cuota- se deja de pedir retención y tráfico
+#: para el resto de piezas pendientes en vez de insistir 250 veces más:
+#: `_CuotaAgotada` (ver su docstring) reutiliza ese mismo criterio, no uno
+#: nuevo. Ninguna pieza se pierde; solo se queda sin las dos métricas que
+#: no se pudieron pagar.
+#:
+# Optional enrichment failures are recorded on affected pieces. Channel-level
+# audience failures are recorded in LecturaRed.warnings. Both are visible in
+# structured coverage and reports; neither discards validated base metrics.
+# Once a read deadline expires, remaining enrichment and audience requests stop.
+CLAVE_ENRIQUECIMIENTO_FALLIDO = "enriquecimiento_fallido"
+
+_DURACION = re.compile(
+    r"^P(?:(?P<d>\d+)D)?T(?:(?P<h>\d+)H)?(?:(?P<m>\d+)M)?(?:(?P<s>\d+)S)?$"
+)
+
+
+def _segundos(iso8601: str) -> int | None:
+    """Convert YouTube ISO 8601 duration to seconds."""
+    m = _DURACION.match(iso8601 or "")
+    if not m:
+        return None
+    partes = {k: int(v) for k, v in m.groupdict(default="0").items()}
+    return partes["d"] * 86400 + partes["h"] * 3600 + partes["m"] * 60 + partes["s"]
+
+
+def _entero(valor: object) -> int | None:
+    """Convert available data to integer; absent metrics remain None."""
+    if valor is None:
+        return None
+    try:
+        return int(valor)
+    except (TypeError, ValueError):
+        return None
+
+
+def _filas(respuesta: dict) -> list[list]:
+    return respuesta.get("rows") or []
+
+
+class _CuotaAgotada(RuntimeError):
+    """Non-scope YouTube HTTP failure, distinct from SinPermiso so only actual quota exhaustion stops later enrichment."""
+
+
+class YouTubeLector(Lector):
+    platform = Platform.YOUTUBE
+
+    def leer(
+        self, brand: Brand, client: httpx.Client, desde: date | None
+    ) -> LecturaRed:
+        token = obtener_token(brand, self.platform, client)
+        cabeceras = {"Authorization": f"Bearer {token}"}
+        hoy = date.today()
+
+        canal = self._canal(client, cabeceras)
+        cuenta = Cuenta(
+            seguidores=_entero(canal["statistics"].get("subscriberCount")),
+            total_piezas=_entero(canal["statistics"].get("videoCount")),
+            total_vistas=_entero(canal["statistics"].get("viewCount")),
+        )
+
+        por_video = self._analytics(
+            client, cabeceras, hoy,
+            dimensions="video",
+            metrics=(
+                "views,estimatedMinutesWatched,averageViewDuration,"
+                "averageViewPercentage,subscribersGained,likes,comments,shares"
+            ),
+            # Obligatorios en el informe por vídeo, y solo en él: sin los dos
+            # la API responde 400 (ver MAX_VIDEOS). Los otros tres informes
+            # de este lector -retención, tráfico, audiencia- no los admiten
+            # como requisito y no se los mandamos.
+            maxResults=str(MAX_VIDEOS),
+            sort="-views",
+        )
+        ids = [fila[0] for fila in _filas(por_video)]
+        catalogo = self._videos(client, cabeceras, ids)
+
+        piezas = []
+        # Una vez agotada la cuota, ninguna petición más de este tipo va a
+        # funcionar: se deja de intentar (ni siquiera se llama a `_pedir`)
+        # para el resto de piezas pendientes, que se conservan igual con sus
+        # métricas base. Ver el bloque de MAX_VIDEOS para el porqué.
+        cuota_agotada = False
+        deadline_error = None
+        warnings = []
+        # Collect channel-level audience before expensive per-video enrichment.
+        audiencia = None
+        try:
+            audiencia = self._audiencia(client, cabeceras, hoy)
+        except Exception as exc:
+            from socialctl.read_reports import safe_error
+            warnings.append('Audience unavailable: ' + safe_error(str(exc)))
+            if isinstance(exc, ReadDeadlineExceeded):
+                deadline_error = exc
+        for fila in _filas(por_video):
+            pieza = self._pieza(fila, catalogo)
+            if pieza is None:
+                continue
+            if desde is not None and pieza.publicado_el.date() < desde:
+                continue
+
+            if cuota_agotada or deadline_error:
+                pieza.especificas["curva_retencion"] = []
+                pieza.especificas["fuentes_trafico"] = {}
+                pieza.especificas[CLAVE_ENRIQUECIMIENTO_FALLIDO] = (
+                    str(deadline_error) if deadline_error else
+                    "not requested: Analytics quota was already exhausted while "
+                    "enriching an earlier item"
+                )
+            else:
+                try:
+                    self._enriquecer(client, cabeceras, hoy, pieza)
+                except _CuotaAgotada:
+                    cuota_agotada = True
+                except ReadDeadlineExceeded as exc:
+                    deadline_error = exc
+
+            piezas.append(pieza)
+
+        # Reporting reports arrive as immutable CSV imports. They are a
+        # separate, delayed source; no report means unknown, never zero.
+        from socialctl.metricas.analytics_ingest import ObservationStore
+        from socialctl.metricas.reach import attach_reach
+        from socialctl.management.youtube_resources import ResourceError
+        authenticated_channel = canal.get('id')
+        configured_channel = (brand.cuentas.get('youtube') or {}).get('channel_id')
+        if configured_channel and configured_channel != authenticated_channel:
+            raise ValueError('YouTube Reporting account differs from authenticated channel')
+        observations = ObservationStore(brand.raiz, authenticated_channel)
+        if observations.root.exists():
+            try:
+                attach_reach(piezas, observations.active(), hoy)
+            except (ResourceError, ValueError, KeyError, TypeError):
+                for pieza in piezas:
+                    pieza.especificas['thumbnail_reach_error'] = (
+                        'imported reach report unreadable; impressions/CTR unknown')
+
+        return LecturaRed(
+            estado=EstadoLectura.OK,
+            account_id=authenticated_channel,
+            cuenta=cuenta,
+            piezas=piezas,
+            audiencia=audiencia,
+            warnings=warnings,
+        )
+
+    # --- peticiones -----------------------------------------------------
+
+    def _pedir(self, client: httpx.Client, url: str, cabeceras: dict, params: dict) -> dict:
+        """Request data and distinguish missing granted scope from other errors using sanitized messages."""
+        r = client.get(url, headers=cabeceras, params=params)
+        if r.is_success:
+            return r.json()
+
+        token = cabeceras.get("Authorization", "").removeprefix("Bearer ")
+
+        if r.status_code == 403:
+            # Google devuelve 403 tanto por scope insuficiente como por
+            # cuota agotada; solo el primero se arregla reautenticando, así
+            # que se distinguen por el texto antes de decirle al usuario qué
+            # hacer.
+            cuerpo = r.text
+            if "insufficient" in cuerpo.lower() or "PERMISSION_DENIED" in cuerpo:
+                scope = (
+                    "yt-analytics.readonly" if url == ANALYTICS else "youtube.readonly"
+                )
+                raise SinPermiso(self.platform, scope)
+
+            # Cualquier otro 403 es, por descarte, el caso que importa: la
+            # cuota diaria agotada. `_CuotaAgotada` es una `RuntimeError`
+            # más -mismo mensaje, mismo comportamiento para quien no la
+            # distinga-, pero permite que `leer()` deje de insistir con el
+            # resto de piezas sin repetir aquí ningún criterio nuevo.
+            raise _CuotaAgotada(
+                f"YouTube returned {r.status_code} for {url}: "
+                f"{mensaje_de_error(r, token)}"
+            )
+
+        raise RuntimeError(
+            f"YouTube returned {r.status_code} for {url}: "
+            f"{mensaje_de_error(r, token)}"
+        )
+
+    def _canal(self, client: httpx.Client, cabeceras: dict) -> dict:
+        datos = self._pedir(client, CANALES, cabeceras, {
+            "part": "snippet,statistics,contentDetails",
+            "mine": "true",
+        })
+        items = datos.get("items") or []
+        if not items:
+            raise RuntimeError(
+                "Data API returned no channel for this token: "
+                "check that you authorized the correct account"
+            )
+        return items[0]
+
+    def _analytics(
+        self, client: httpx.Client, cabeceras: dict, hoy: date, **extra: str
+    ) -> dict:
+        params = {
+            "ids": "channel==MINE",
+            "startDate": INICIO_DE_LOS_TIEMPOS,
+            "endDate": hoy.isoformat(),
+            **extra,
+        }
+        return self._pedir(client, ANALYTICS, cabeceras, params)
+
+    def _videos(self, client: httpx.Client, cabeceras: dict, ids: list[str]) -> dict[str, dict]:
+        catalogo: dict[str, dict] = {}
+        for i in range(0, len(ids), LOTE):
+            datos = self._pedir(client, VIDEOS, cabeceras, {
+                "part": "snippet,statistics,contentDetails",
+                "id": ",".join(ids[i : i + LOTE]),
+            })
+            for item in datos.get("items") or []:
+                catalogo[item["id"]] = item
+        return catalogo
+
+    # --- composición ----------------------------------------------------
+
+    def _pieza(self, fila: list, catalogo: dict[str, dict]) -> Pieza | None:
+        id_video = fila[0]
+        item = catalogo.get(id_video)
+        if item is None:
+            # El vídeo salió en Analytics pero no en el catálogo: borrado o
+            # privado. No se inventa nada: se omite.
+            return None
+
+        duracion = _segundos(item["contentDetails"].get("duration", ""))
+        estadisticas = item.get("statistics", {})
+        publicado = datetime.fromisoformat(
+            item["snippet"]["publishedAt"].replace("Z", "+00:00")
+        ).astimezone(timezone.utc).replace(tzinfo=None)
+
+        return Pieza(
+            id=id_video,
+            url=f"https://www.youtube.com/watch?v={id_video}",
+            titulo=item["snippet"]["title"],
+            publicado_el=publicado,
+            tipo=(
+                # 180 s y no 60: desde octubre de 2024 YouTube admite Shorts
+                # de hasta **3 minutos**, así que el umbral de 60 s dejaría
+                # clasificados como "largo" cortes que son Shorts a todos los
+                # efectos. Un vídeo horizontal de dos minutos caería del lado
+                # equivocado, pero la API no da la relación de aspecto en
+                # `contentDetails`, y en este proyecto no se publican
+                # horizontales tan cortos.
+                TipoPieza.VERTICAL
+                if duracion is not None and duracion <= 180
+                else TipoPieza.LARGO
+            ),
+            duracion_seg=duracion,
+            acumulado=Metricas(
+                vistas=_entero(estadisticas.get("viewCount")),
+                likes=_entero(estadisticas.get("likeCount")),
+                comentarios=_entero(estadisticas.get("commentCount")),
+                compartidos=_entero(fila[8]) if len(fila) > 8 else None,
+            ),
+            especificas={
+                "minutos_vistos": _entero(fila[2]),
+                "duracion_media_seg": _entero(fila[3]),
+                "porcentaje_visto": fila[4] if len(fila) > 4 else None,
+                "suscriptores_ganados": _entero(fila[5]) if len(fila) > 5 else None,
+            },
+        )
+
+    def _retencion(
+        self, client: httpx.Client, cabeceras: dict, hoy: date, id_video: str
+    ) -> list[dict]:
+        datos = self._analytics(
+            client, cabeceras, hoy,
+            dimensions="elapsedVideoTimeRatio",
+            metrics="audienceWatchRatio",
+            filters=f"video=={id_video};audienceType==ORGANIC",
+        )
+        return [{"posicion": fila[0], "ratio": fila[1]} for fila in _filas(datos)]
+
+    def _trafico(
+        self, client: httpx.Client, cabeceras: dict, hoy: date, id_video: str
+    ) -> dict[str, int]:
+        datos = self._analytics(
+            client, cabeceras, hoy,
+            dimensions="insightTrafficSourceType",
+            metrics="views",
+            filters=f"video=={id_video}",
+        )
+        return {fila[0]: _entero(fila[1]) for fila in _filas(datos)}
+
+    def _enriquecer(
+        self, client: httpx.Client, cabeceras: dict, hoy: date, pieza: Pieza
+    ) -> None:
+        """Enrich one item with retention and traffic; both requests must succeed, otherwise record failure without partial enrichment."""
+        try:
+            pieza.especificas["curva_retencion"] = self._retencion(
+                client, cabeceras, hoy, pieza.id
+            )
+            pieza.especificas["fuentes_trafico"] = self._trafico(
+                client, cabeceras, hoy, pieza.id
+            )
+        except Exception as e:  # noqa: BLE001 - aísla esta pieza, no tumba la lectura
+            pieza.especificas["curva_retencion"] = []
+            pieza.especificas["fuentes_trafico"] = {}
+            pieza.especificas[CLAVE_ENRIQUECIMIENTO_FALLIDO] = str(e)
+            if isinstance(e, (_CuotaAgotada, ReadDeadlineExceeded)):
+                raise
+
+    def _audiencia(self, client: httpx.Client, cabeceras: dict, hoy: date) -> Audiencia:
+        paises_crudos = self._analytics(
+            # `sort=-views` no es decorativo: el spec pide el **top 10** de
+            # países, y sin ordenar serían "los 10 primeros que devuelva la
+            # API", que es otra cosa.
+            client, cabeceras, hoy, dimensions="country", metrics="views",
+            sort="-views",
+        )
+        filas = _filas(paises_crudos)[:10]
+        total = sum(fila[1] for fila in filas) or 0
+        paises = (
+            {fila[0]: round(fila[1] * 100 / total, 1) for fila in filas}
+            if total
+            else {}
+        )
+
+        edades_crudas = self._analytics(
+            client, cabeceras, hoy, dimensions="ageGroup", metrics="viewerPercentage"
+        )
+        edades = {fila[0]: fila[1] for fila in _filas(edades_crudas)}
+
+        return Audiencia(paises=paises, edades=edades)

socialctl/migration_cli.py

@@ -0,0 +1,60 @@
+"""Operator-facing migration lifecycle; no publication or remote writes."""
+from pathlib import Path
+import json
+
+import typer
+
+from socialctl.brands import cargar_brand
+from socialctl import queue_migration
+
+migration_app = typer.Typer(help="Relocate media and migrate verified legacy approvals.")
+from socialctl.workspace import default_root
+
+DEFAULT_ROOT = default_root()
+
+
+def _run(operation):
+    try:
+        return operation()
+    except Exception as exc:
+        typer.echo(f"Migration error: {exc}", err=True)
+        raise typer.Exit(1) from exc
+
+
+@migration_app.command("prepare")
+def prepare(brand: str = typer.Option(..., "--brand"), root: Path = typer.Option(DEFAULT_ROOT),
+            backend: str = typer.Option("json"), dry_run: bool = typer.Option(False, "--dry-run")):
+    proposal = _run(lambda: queue_migration.prepare(cargar_brand(root, brand), backend=backend, dry_run=dry_run))
+    typer.echo(proposal["preview"])
+    typer.echo("\nExact path mapping:")
+    for item in proposal["media"]:
+        typer.echo(f"{item['source']} -> media/{item['relative_path']} -> {item['public_url']} ({item['size']} bytes, SHA256 {item['sha256']})")
+    typer.echo("\n" + proposal["legacy_limitation"])
+    for entry in proposal["entries"]:
+        typer.echo(f"{entry['id']} | {entry['status']} | {entry['scheduled_at']} | attempts={entry['attempts']}")
+    typer.echo(f"Proposal: {proposal['id']}\nDigest: {proposal['digest']}")
+    typer.echo("Dry-run: no proposal saved or queue modified." if dry_run else "Proposal saved; queue unchanged and no content published.")
+
+
+@migration_app.command("stage")
+def stage(brand: str = typer.Option(..., "--brand"), proposal: str = typer.Option(...),
+          output: Path = typer.Option(...), root: Path = typer.Option(DEFAULT_ROOT)):
+    manifest = _run(lambda: queue_migration.stage(cargar_brand(root, brand), proposal, output))
+    typer.echo(json.dumps(manifest, indent=2, ensure_ascii=False))
+    typer.echo(f"Transfer manifest: {output / 'transfer-manifest.json'}; remote transfer is the operator's responsibility.")
+
+
+@migration_app.command("apply")
+def apply(brand: str = typer.Option(..., "--brand"), proposal: str = typer.Option(...),
+          digest: str = typer.Option(...), root: Path = typer.Option(DEFAULT_ROOT),
+          acknowledge_legacy_limitations: bool = typer.Option(False, "--acknowledge-legacy-limitations")):
+    intent = _run(lambda: queue_migration.apply(cargar_brand(root, brand), proposal, digest,
+                  acknowledge_legacy_limitations=acknowledge_legacy_limitations))
+    typer.echo(f"Migration {proposal}: {intent['status']}; approvals, accounts and schedules preserved.")
+
+
+@migration_app.command("rollback")
+def rollback(brand: str = typer.Option(..., "--brand"), proposal: str = typer.Option(...),
+             root: Path = typer.Option(DEFAULT_ROOT)):
+    _run(lambda: queue_migration.rollback(cargar_brand(root, brand), proposal))
+    typer.echo(f"Migration {proposal} restored. Supplied media and copies preserved.")

socialctl/migration_files.py

@@ -0,0 +1,68 @@
+"""Durable migration files and byte-preserving YAML scalar relocation."""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+import yaml
+
+from socialctl.scheduler import ScheduleError, ScheduleStore
+
+
+def durable_write(path: Path, data: bytes) -> None:
+    missing = []
+    parent = path.parent
+    while not parent.exists():
+        missing.append(parent)
+        parent = parent.parent
+    for directory in reversed(missing):
+        directory.mkdir(exist_ok=True)
+        ScheduleStore._sync_directory(directory.parent)
+    fd, temporary = tempfile.mkstemp(prefix=".migration-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+        ScheduleStore._sync_directory(path.parent)
+    finally:
+        Path(temporary).unlink(missing_ok=True)
+
+
+def write_json(path: Path, value: dict) -> None:
+    durable_write(path, (json.dumps(value, indent=2, ensure_ascii=False) + "\n").encode())
+
+
+def rewrite_media(raw: bytes, replacements: dict[str, dict[str, str]]) -> bytes:
+    """Replace only media scalar tokens. Aliases/anchors/duplicate keys fail closed."""
+    text = raw.decode("utf-8")
+    if any(isinstance(token, (yaml.tokens.AnchorToken, yaml.tokens.AliasToken)) for token in yaml.scan(text)):
+        raise ScheduleError("YAML aliases/anchors do not support safe migration")
+    root = yaml.compose(text)
+    def mapping(node):
+        if not isinstance(node, yaml.MappingNode):
+            raise ScheduleError("unsupported YAML structure")
+        result = {}
+        for key, value in node.value:
+            if not isinstance(key, yaml.ScalarNode) or key.value in result or key.value == "<<":
+                raise ScheduleError("ambiguous YAML keys")
+            result[key.value] = value
+            if isinstance(value, yaml.MappingNode):
+                mapping(value)
+        return result
+    platforms = mapping(mapping(root)["platforms"])
+    spans = []
+    for platform, paths in replacements.items():
+        media = mapping(platforms[platform]).get("media")
+        if not isinstance(media, yaml.SequenceNode):
+            raise ScheduleError("media must be an explicit list")
+        for item in media.value:
+            if not isinstance(item, yaml.ScalarNode) or item.tag != "tag:yaml.org,2002:str" or item.value not in paths:
+                raise ScheduleError("ambiguous or modified YAML media")
+            spans.append((item.start_mark.index, item.end_mark.index, json.dumps(paths[item.value])))
+    for start, end, replacement in sorted(spans, reverse=True):
+        text = text[:start] + replacement + text[end:]
+    return text.encode("utf-8")

socialctl/models.py

@@ -0,0 +1,150 @@
+"""Shared socialctl data models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+class Platform(str, Enum):
+    YOUTUBE = "youtube"
+    FACEBOOK = "facebook"
+    INSTAGRAM = "instagram"
+    TIKTOK = "tiktok"
+
+
+class MediaKind(str, Enum):
+    VIDEO = "video"
+    IMAGE = "image"
+
+
+class CampaignType(str, Enum):
+    CLIP_VERTICAL = "clip-vertical"
+    LANZAMIENTO_VIDEO_LARGO = "lanzamiento-video-largo"
+    POST_IMAGEN = "post-imagen"
+
+
+class PostStatus(str, Enum):
+    PUBLICADO = "publicado"
+    PENDIENTE_CONFIRMACION = "pendiente_confirmacion"
+    ERROR = "error"
+    OMITIDO = "omitido"
+
+
+class MediaAsset(BaseModel):
+    probe: dict | None = Field(default=None, exclude=True)
+    """Read-only technical observations, excluded from durable approval payloads."""
+    path: Path
+    kind: MediaKind
+    width: int | None = None
+    height: int | None = None
+    duration_s: float | None = None
+    size_bytes: int = 0
+    ruta_relativa: str = ""
+    """Original relative media path, including subdirectories. Empty values fall back through ruta_relativa_efectiva."""
+
+
+    def __eq__(self, other):
+        # Ephemeral inspection details are not part of durable media identity.
+        if isinstance(other, MediaAsset):
+            return BaseModel.__eq__(self.model_copy(update={"probe": None}),
+                                    other.model_copy(update={"probe": None}))
+        return NotImplemented
+
+
+class StoryPost(BaseModel):
+    """A standalone Story, separate from feed and Reel posts."""
+
+    platform: Platform
+    media: MediaAsset
+    public_url: str | None = None
+    text: str | None = None
+    expires_at: datetime
+    source_video_id: str | None = Field(default=None, pattern=r"^[A-Za-z0-9_-]{11}$")
+
+    @model_validator(mode="after")
+    def validate_story(self):
+        if self.platform not in {Platform.FACEBOOK, Platform.INSTAGRAM}:
+            raise ValueError("Stories are only supported on Facebook or Instagram")
+        if self.text is not None and not self.text.strip():
+            raise ValueError("optional Story text cannot be empty")
+        if self.expires_at.utcoffset() is None:
+            raise ValueError("expires_at must include a timezone")
+        return self
+
+
+class PlatformPost(BaseModel):
+    platform: Platform
+    title: str | None = None
+    body: str
+    hashtags: list[str] = []
+    tags: list[str] | None = Field(default=None, exclude_if=lambda value: value is None)
+    visible_hashtags: list[str] | None = Field(default=None, exclude_if=lambda value: value is None)
+
+    @field_validator("tags", "visible_hashtags", mode="before")
+    @classmethod
+    def explicit_youtube_lists(cls, value):
+        if not isinstance(value, list) or any(not isinstance(item, str) for item in value):
+            raise ValueError("tags/visible_hashtags require lists of strings; omitting them preserves legacy mode")
+        return value
+
+    @model_validator(mode="after")
+    def validate_youtube_tags(self):
+        if self.platform != Platform.YOUTUBE and (self.tags is not None or self.visible_hashtags is not None):
+            raise ValueError("tags/visible_hashtags are only supported on YouTube")
+        if self.tags is not None and self.hashtags:
+            raise ValueError("YouTube: legacy hashtags and explicit tags are ambiguous; use one")
+        if self.visible_hashtags is not None:
+            for tag in self.visible_hashtags:
+                value = tag.removeprefix("#")
+                if not value or any(not (char.isalnum() or char == "_") for char in value):
+                    raise ValueError("visible_hashtags requires each hashtag without spaces or punctuation")
+        return self
+
+    media: list[MediaAsset] = []
+    link: str | None = None
+    content_origin: Literal["standalone", "youtube_long"] | None = None
+    source_video_id: str | None = Field(default=None, pattern=r"^[A-Za-z0-9_-]{11}$")
+    first_comment: str | None = None
+    privacy: str | None = None
+    """Requested privacy where supported. YouTube uses this field and defaults to private; TikTok validates creator_info options separately."""
+
+
+class Post(BaseModel):
+    source_mapping_digest: str | None = Field(default=None, exclude_if=lambda value: value is None)
+    slug: str
+    brand: str
+    campaign: CampaignType
+    platforms: dict[Platform, PlatformPost]
+
+
+class PostResult(BaseModel):
+    platform: Platform
+    status: PostStatus
+    url: str | None = None
+    platform_id: str | None = None
+    error: str | None = None
+    warnings: list[str] = []
+    publication_id: str | None = None
+    first_comment_id: str | None = None
+    first_comment_change_id: str | None = None
+    first_comment_status: str | None = None
+    requested_privacy: str | None = None
+    observed_privacy: str | None = None
+    observed_publish_at: str | None = None
+    observed_processing_status: str | None = None
+    visibility_observed_at: str | None = None
+    riesgo_duplicado: bool = False
+    """True when content may already be published despite an error. Automatic retry must respect this structured duplicate-risk signal."""
+
+
+class ValidationError(BaseModel):
+    """A specific validation failure detected before publication."""
+
+    platform: Platform
+    campo: str
+    motivo: str