socialcli 0.3.0__py3-none-any.whl

socialctl/metricas/resumen.py

@@ -0,0 +1,251 @@
+"""Render daily snapshot as readable Markdown at <Brand>/metricas/resumen.md; detailed data remains in JSON."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from socialctl.brands import Brand
+from socialctl.metricas.almacen import (
+    dir_metricas,
+    escribir_atomico,
+    snapshot_anterior,
+)
+from socialctl.metricas.modelos import EstadoLectura, Metricas, Pieza, Snapshot
+from socialctl.metricas.piezas import cargar_piezas
+from socialctl.metricas.youtube import CLAVE_ENRIQUECIMIENTO_FALLIDO
+from socialctl.models import Platform
+
+COLUMNAS: dict[Platform, tuple[tuple[str, str], ...]] = {
+    # YouTube: retención y suscriptores, que es lo que mide el objetivo de
+    # los largos y el de crecer en suscriptores.
+    Platform.YOUTUBE: (
+        ("% viewed", "porcentaje_visto"),
+        ("Subs", "suscriptores_ganados"),
+    ),
+    # Instagram: el spec (§7) mide su objetivo -alcance- con vistas,
+    # compartidos y guardados. Sin estas dos columnas, el gestor tendría que
+    # bajar al JSON para lo que en esta red es lo central.
+    Platform.INSTAGRAM: (("Shares", "compartidos"), ("Saves", "guardados")),
+    # TikTok: **no hay columna de guardados, y no es un olvido.** La Display
+    # API de TikTok no expone esa métrica -ver el docstring de
+    # `socialctl/metricas/tiktok.py`-, verificado contra la cuenta real de
+    # la marca el 2026-09-11, no supuesto. Su lector nunca rellena
+    # `guardados` (queda en `None` por la regla de oro de
+    # `socialctl/metricas/modelos.py`), así que esta columna saldría en
+    # blanco en todas las filas, siempre, y nadie entendería por qué.
+    #
+    # No se sustituye por `likes` ni `comentarios` -las dos vivas en su
+    # lector-: ninguna mide alcance mejor que `compartidos` sola, así que
+    # añadir una sería relleno, no una columna que aporte (mismo criterio
+    # que `METRICAS_MUERTAS` en `socialctl/metricas/facebook.py`, que
+    # tampoco sustituye `alcance` por una métrica parecida). Si alguien
+    # reintenta esto: la Display API sigue sin dar guardados; compruébalo
+    # tú mismo contra la cuenta real antes de asumir que cambió.
+    Platform.TIKTOK: (("Shares", "compartidos"),),
+    # Facebook no da guardados, y desde la Graph API v26.0 tampoco da alcance
+    # por publicación (ver `METRICAS_MUERTAS` en `metricas/facebook.py`). Lo
+    # que sí da, y mide mejor el objetivo, es la retención media: cuántos
+    # segundos aguantan de media, en segundos ya convertidos.
+    Platform.FACEBOOK: (("Shares", "compartidos"), ("Retention s", "retencion_media_seg")),
+}
+"""Use at most two platform-specific columns alongside the five common columns."""
+
+#: Cuántos caracteres del motivo de un enriquecimiento fallido caben en la
+#: celda de "Aviso" antes de recortar. La tabla tiene que seguir leyéndose de
+#: un vistazo; el motivo completo -ya redactado, sin secretos- sigue estando
+#: en el JSON del snapshot del día para quien necesite el texto entero.
+LARGO_AVISO = 80
+
+#: Cuántos caracteres del título de una pieza caben en su celda. Mismo
+#: motivo que `LARGO_AVISO`: la tabla tiene que leerse de un vistazo.
+LARGO_TITULO = 48
+
+
+def _recortar(texto: str, largo: int) -> str:
+    """Truncate to largo characters at word boundaries, marking truncation with an ellipsis."""
+    if len(texto) <= largo:
+        return texto
+    recortado = texto[: largo - 1].rstrip()
+    espacio = recortado.rfind(" ")
+    if espacio > 0:
+        recortado = recortado[:espacio].rstrip()
+    return recortado + "…"
+
+
+def _escapar(celda: str) -> str:
+    """Escape pipes and replace line breaks so text fits a Markdown table cell."""
+    return celda.replace("|", "\\|").replace("\n", " ").replace("\r", " ")
+
+
+def _valor(pieza: Pieza | None, clave: str) -> object | None:
+    """Look up clave in common metrics first, then platform-specific metrics."""
+    if pieza is None:
+        return None
+    if clave in Metricas.model_fields:
+        return getattr(pieza.acumulado, clave)
+    return pieza.especificas.get(clave)
+
+
+def _variacion(actual: object, previo: object) -> str:
+    """Format signed delta, or empty text when unchanged or unavailable."""
+    if not isinstance(actual, (int, float)) or not isinstance(previo, (int, float)):
+        return ""
+    diferencia = actual - previo
+    if isinstance(diferencia, float):
+        diferencia = round(diferencia, 1)
+        if diferencia == int(diferencia):
+            diferencia = int(diferencia)
+    if diferencia == 0:
+        return ""
+    return f"+{diferencia}" if diferencia > 0 else str(diferencia)
+
+
+def _celda(valor: object) -> str:
+    return "—" if valor is None else str(valor)
+
+
+def _celda_comparada(actual: object, previo: object) -> str:
+    """Format value with delta when an earlier matching item exists."""
+    base = _celda(actual)
+    delta = _variacion(actual, previo)
+    return f"{base} ({delta})" if delta else base
+
+
+def _aviso(pieza: Pieza) -> str:
+    """Show enrichment failure reason or an em dash; never infer missing data as zero."""
+    motivo = pieza.especificas.get(CLAVE_ENRIQUECIMIENTO_FALLIDO)
+    if not motivo:
+        return "—"
+    return f"⚠ {_recortar(str(motivo), LARGO_AVISO)}"
+
+
+def render_resumen(
+    snapshot: Snapshot, anterior: Snapshot | None, piezas: list[dict]
+) -> str:
+    editoriales = {(p.get("red"), p.get("id")): p for p in piezas}
+    lineas = [
+        f"# Metrics for {snapshot.marca}",
+        "",
+        f"**Snapshot:** {snapshot.fecha.isoformat()}",
+    ]
+
+    if anterior is None:
+        lineas.append(
+            "**Change:** no previous snapshot available for comparison "
+            "(first snapshot)."
+        )
+    else:
+        lineas.append(f"**Compared with:** {anterior.fecha.isoformat()}")
+    lineas.append("")
+
+    for platform, lectura in snapshot.redes.items():
+        lineas.append(f"## {platform.value}")
+        lineas.append("")
+        for warning in lectura.warnings:
+            lineas += [f"**Partial read:** {warning}", ""]
+        if lectura.estado is not EstadoLectura.OK:
+            lineas += [
+                f"**Status:** `{lectura.estado.value}` — {lectura.error or 'no details'}",
+                "",
+            ]
+            # El aviso de estado SÍ, pero la tabla también si hay piezas. Con
+            # `--only`, `_fusionar_snapshot_del_dia` (`socialctl/cli.py`)
+            # conserva los últimos números buenos de una red que hoy falla y
+            # le pone el `estado` de hoy; ese arreglo prometía que "el resumen
+            # y `piezas.yml` siguen viendo los últimos números buenos en vez
+            # de un hueco", y aquí no se cumplía: un `continue` incondicional
+            # borraba de `resumen.md` las piezas conservadas, la línea de
+            # seguidores y la tabla entera, justo en el escenario que el
+            # arreglo existe para evitar. Sin piezas no hay nada que enseñar
+            # y se sigue saltando la tabla, que es el caso de una red que
+            # falló sin dato previo.
+            if not lectura.piezas:
+                continue
+
+        if lectura.cuenta is not None:
+            lineas += [
+                f"Followers: {_celda(lectura.cuenta.seguidores)} · "
+                f"Items: {_celda(lectura.cuenta.total_piezas)} · "
+                f"Total views: {_celda(lectura.cuenta.total_vistas)}",
+                "",
+            ]
+
+        previas = {}
+        if anterior is not None and platform in anterior.redes:
+            previas = {p.id: p for p in anterior.redes[platform].piezas}
+
+        # `COLUMNAS` cubre las cuatro redes de `Platform`, que son todas las
+        # que puede traer un snapshot: no hay caso por defecto que atender.
+        columnas = COLUMNAS[platform]
+        titulos = ["Published", "Item", "Pillar", "Hook", "Views"]
+        titulos += [titulo for titulo, _ in columnas]
+        titulos.append("Notice")
+        lineas += [
+            "| " + " | ".join(titulos) + " |",
+            "|" + "---|" * len(titulos),
+        ]
+        for pieza in sorted(lectura.piezas, key=lambda p: p.publicado_el, reverse=True):
+            editorial = editoriales.get((platform.value, pieza.id), {})
+            previa = previas.get(pieza.id)
+            celdas = [
+                pieza.publicado_el.date().isoformat(),
+                _recortar(pieza.titulo, LARGO_TITULO),
+                _celda(editorial.get("pilar")),
+                _celda(editorial.get("gancho")),
+                _celda_comparada(
+                    pieza.acumulado.vistas,
+                    previa.acumulado.vistas if previa else None,
+                ),
+            ]
+            for _, clave in columnas:
+                celdas.append(
+                    _celda_comparada(
+                        _valor(pieza, clave),
+                        _valor(previa, clave) if previa else None,
+                    )
+                )
+            celdas.append(_aviso(pieza))
+            lineas.append("| " + " | ".join(_escapar(c) for c in celdas) + " |")
+        lineas.append("")
+        if platform is Platform.YOUTUBE:
+            reach_rows = [(pieza, pieza.especificas.get("thumbnail_reach_28d"))
+                          for pieza in lectura.piezas]
+            reach_rows = [(pieza, reach) for pieza, reach in reach_rows
+                          if isinstance(reach, dict) and reach.get("impressions") is not None]
+            if reach_rows:
+                lineas += ["### Thumbnail reach (28 days · YouTube Reporting)", "",
+                           "| Item | Impressions | CTR | Through | Report |",
+                           "|---|---:|---:|---|---|"]
+                for pieza, reach in sorted(reach_rows,
+                                           key=lambda item: item[1]["impressions"],
+                                           reverse=True)[:10]:
+                    ctr = reach.get("ctr")
+                    ctr_text = f"{ctr:.1f}%" if isinstance(ctr, (int, float)) else "—"
+                    cells = (_recortar(pieza.titulo, LARGO_TITULO),
+                             str(reach["impressions"]), ctr_text,
+                             reach.get("through", "—"),
+                             ", ".join(reach.get("report_ids", [])))
+                    lineas.append("| " + " | ".join(_escapar(value) for value in cells) + " |")
+                lineas.append("")
+            else:
+                lineas += ["**Thumbnails:** no imported reach report for these items.", ""]
+
+    lineas += [
+        "---",
+        "",
+        "Generated by `socialcli stats`. Full detail — retention curve,",
+        "traffic sources, audience — is in the JSON for the same day.",
+        "Thumbnail impressions and CTR come from YouTube Reporting when",
+        "an imported reach report exists; missing data does not equal zero.",
+        "",
+    ]
+    return "\n".join(lineas)
+
+
+def escribir_resumen(brand: Brand, snapshot: Snapshot) -> Path:
+    texto = render_resumen(
+        snapshot,
+        anterior=snapshot_anterior(brand, antes_de=snapshot.fecha),
+        piezas=cargar_piezas(brand),
+    )
+    return escribir_atomico(dir_metricas(brand) / "resumen.md", texto)

socialctl/metricas/slugs.py

@@ -0,0 +1,89 @@
+"""Link measured items to publishing posts using resultado.json. Only confirmed publications qualify; unmatched external items retain slug None."""
+
+from __future__ import annotations
+
+import json
+import re
+import warnings
+
+from socialctl.brands import Brand
+from socialctl.metricas.modelos import Snapshot
+from socialctl.models import Platform, PostStatus
+
+_ID_DE_VIDEO_TIKTOK = re.compile(r"/video/(\d+)")
+
+
+def _id_de_pieza(red: str, entrada: dict) -> str | None:
+    """Resolve ID used by metrics reader. TikTok publish_id is not video ID; extract actual ID from shared video URL or return None."""
+    if red == Platform.TIKTOK.value:
+        encontrado = _ID_DE_VIDEO_TIKTOK.search(entrada.get("url") or "")
+        return encontrado.group(1) if encontrado else None
+
+    id_pieza = entrada.get("platform_id")
+    return id_pieza if isinstance(id_pieza, str) and id_pieza else None
+
+
+def mapa_de_slugs(brand: Brand) -> dict[tuple[str, str], str]:
+    """Build (platform, item ID) to slug mapping from post results; silently skip corrupt historical files because linking is optional enrichment."""
+    mapa: dict[tuple[str, str], str] = {}
+    carpeta = brand.dir_posts
+    if not carpeta.is_dir():
+        return mapa
+
+    for fichero in sorted(carpeta.glob("*/resultado.json")):
+        try:
+            datos = json.loads(fichero.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        if not isinstance(datos, dict):
+            continue
+        entradas = datos.get("resultados")
+        if not isinstance(entradas, list):
+            continue
+
+        # El slug es el nombre de la CARPETA, no el campo `slug` del JSON:
+        # la carpeta es lo que el gestor tiene que abrir después.
+        slug = fichero.parent.name
+
+        for entrada in entradas:
+            if not isinstance(entrada, dict):
+                continue
+            if entrada.get("status") != PostStatus.PUBLICADO.value:
+                continue
+            red = entrada.get("platform")
+            if not isinstance(red, str):
+                continue
+            id_pieza = _id_de_pieza(red, entrada)
+            if id_pieza is None:
+                continue
+            # Si dos posts reclamaran la misma pieza (un reintento que
+            # duplicó, por ejemplo), gana el primero en orden alfabético de
+            # carpeta, que es estable entre ejecuciones. Si ocurre, avisa.
+            clave = (red, id_pieza)
+            anterior = mapa.get(clave)
+            if anterior is None:
+                mapa[clave] = slug
+            else:
+                warnings.warn(
+                    f"resultado.json: two posts claim the same pair "
+                    f"(red={red!r}, id={id_pieza!r}): post with slug {anterior!r} "
+                    f"is kept; post with slug {slug!r} is discarded. Review "
+                    "those two folders in posts/ to determine which is the "
+                    "actual publication.",
+                    stacklevel=3,
+                )
+
+    return mapa
+
+
+def asignar_slugs(brand: Brand, snapshot: Snapshot) -> None:
+    """Assign matching publishing post slug to snapshot items without overwriting any supplied slug."""
+    mapa = mapa_de_slugs(brand)
+    if not mapa:
+        return
+
+    for platform, lectura in snapshot.redes.items():
+        for pieza in lectura.piezas:
+            if pieza.slug:
+                continue
+            pieza.slug = mapa.get((platform.value, pieza.id))

socialctl/metricas/tiktok.py

@@ -0,0 +1,185 @@
+"""Read TikTok Display API metrics using user.info.stats/video.list. Preserve absent fields as None and inspect error bodies before HTTP status; sanitize any reflected token values."""
+
+from __future__ import annotations
+
+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 (
+    Cuenta,
+    EstadoLectura,
+    LecturaRed,
+    Metricas,
+    Pieza,
+    TipoPieza,
+)
+# Misma clave y mismo mecanismo de señal que YouTube y Meta, importada del
+# mismo sitio en vez de reescrita: ver `CLAVE_ENRIQUECIMIENTO_FALLIDO` en
+# `socialctl/metricas/youtube.py`.
+from socialctl.metricas.youtube import CLAVE_ENRIQUECIMIENTO_FALLIDO
+from socialctl.models import Platform
+
+USER_INFO = "https://open.tiktokapis.com/v2/user/info/"
+VIDEO_LIST = "https://open.tiktokapis.com/v2/video/list/"
+
+CAMPOS_USUARIO = "open_id,follower_count,likes_count,video_count"
+CAMPOS_VIDEO = (
+    "id,title,video_description,create_time,share_url,"
+    "view_count,like_count,comment_count,share_count"
+)
+
+#: Tope de páginas de `video/list`. Existe para que un `has_more` que nunca
+#: se apague (o un cursor que no avance) no deje el comando girando para
+#: siempre: 20 páginas de 20 son 400 vídeos, muy por encima de cualquier
+#: marca de este proyecto.
+MAX_PAGINAS = 20
+
+
+class TikTokLector(Lector):
+    platform = Platform.TIKTOK
+
+    def leer(
+        self, brand: Brand, client: httpx.Client, desde: date | None
+    ) -> LecturaRed:
+        token = obtener_token(brand, self.platform, client)
+        cabeceras = {"Authorization": f"Bearer {token}"}
+
+        usuario = self._get(
+            client, USER_INFO, cabeceras, {"fields": CAMPOS_USUARIO}, "user.info.stats"
+        )["data"].get("user", {})
+        cuenta = Cuenta(
+            seguidores=usuario.get("follower_count"),
+            total_piezas=usuario.get("video_count"),
+            total_vistas=None,  # TikTok no da vistas totales de cuenta
+        )
+
+        piezas: list[Pieza] = []
+        cursor = None
+        for numero_de_pagina in range(1, MAX_PAGINAS + 1):
+            cuerpo: dict = {"max_count": 20}
+            if cursor is not None:
+                cuerpo["cursor"] = cursor
+            try:
+                datos = self._post(
+                    client, VIDEO_LIST, cabeceras, {"fields": CAMPOS_VIDEO}, cuerpo,
+                    "video.list",
+                )["data"]
+            except SinPermiso:
+                # Falta un scope: no es una lectura parcial, es una que no
+                # puede hacerse. Sube tal cual para que el usuario vea el
+                # permiso que falta y el `auth` que lo arregla.
+                raise
+            except Exception as exc:  # noqa: BLE001 - degradar, no perderlo todo
+                if not piezas:
+                    # La primera página falló: no hay nada leído que salvar y
+                    # esto es un fallo de la red entera, no una lectura
+                    # parcial. Sube y `leer_red` lo convierte en `error`.
+                    raise
+                # Hay páginas ya leídas: conservarlas es mejor que tirarlas.
+                # Antes de este arreglo, un fallo en la página 3 perdía las
+                # piezas de la 1 y la 2 -TikTok era el único lector que no
+                # degradaba: YouTube aísla el enriquecimiento pieza a pieza y
+                # Meta reintenta sin insights-. Se marca cada pieza
+                # conservada con `CLAVE_ENRIQUECIMIENTO_FALLIDO`, el mismo
+                # mecanismo que usan las otras dos: una clave que solo existe
+                # cuando algo falló, para que su sola presencia sea la señal
+                # y `resumen.md` la muestre en su columna "Aviso".
+                #
+                # El texto no puede arrastrar el token: los errores de este
+                # lector se construyen con `mensaje_de_error` (ver
+                # `_comprobar`), y el token de TikTok viaja en la cabecera
+                # `Authorization`, nunca en la URL que lleva un
+                # `HTTPStatusError`.
+                motivo = (
+                    f"partial read: page {numero_de_pagina} of "
+                    f"video/list failed ({exc}); preserving the "
+                    f"{len(piezas)} items already read; older items are missing"
+                )
+                for pieza_leida in piezas:
+                    pieza_leida.especificas[CLAVE_ENRIQUECIMIENTO_FALLIDO] = motivo
+                break
+
+            for video in datos.get("videos", []):
+                publicado = datetime.fromtimestamp(
+                    video["create_time"], tz=timezone.utc
+                ).replace(tzinfo=None)
+                if desde is not None and publicado.date() < desde:
+                    continue
+                piezas.append(Pieza(
+                    id=video["id"],
+                    url=video.get("share_url", ""),
+                    titulo=(video.get("title") or video.get("video_description") or "")[:120],
+                    publicado_el=publicado,
+                    tipo=TipoPieza.VERTICAL,  # en TikTok todo es vertical
+                    acumulado=Metricas(
+                        vistas=video.get("view_count"),
+                        likes=video.get("like_count"),
+                        comentarios=video.get("comment_count"),
+                        compartidos=video.get("share_count"),
+                    ),
+                ))
+
+            if not datos.get("has_more"):
+                break
+            cursor = datos.get("cursor")
+
+        return LecturaRed(estado=EstadoLectura.OK, account_id=usuario.get('open_id'), cuenta=cuenta, piezas=piezas)
+
+    # --- peticiones -----------------------------------------------------
+
+    def _comprobar(self, r: httpx.Response, datos: dict, scope: str, token: str) -> dict:
+        error = datos.get("error") or {}
+        codigo = error.get("code", "ok")
+        if codigo != "ok":
+            mensaje = str(error.get("message", ""))
+            if "scope" in codigo or "scope" in mensaje.lower():
+                raise SinPermiso(self.platform, scope)
+            # El texto sale de `mensaje_de_error` y no del `message` crudo:
+            # la forma del error de TikTok es la misma `{"error": {"message":
+            # ...}}` que ese helper ya entiende, y además redacta el token
+            # por si un intermediario reflejó la petición en el cuerpo. Un
+            # `error` de este lector acaba en el snapshot, que se versiona.
+            raise RuntimeError(
+                f"TikTok returned '{codigo}': {mensaje_de_error(r, token)}"
+            )
+        return datos
+
+    def _respuesta(self, r: httpx.Response, scope: str, token: str) -> dict:
+        """Inspect TikTok JSON error body before HTTP status so missing scopes become actionable permission errors even on 401/403; non-JSON bodies fall back to normal HTTP handling."""
+        try:
+            datos = r.json()
+        except ValueError:
+            datos = None
+
+        if isinstance(datos, dict):
+            self._comprobar(r, datos, scope, token)
+
+        r.raise_for_status()
+
+        if not isinstance(datos, dict):
+            raise RuntimeError(
+                f"TikTok returned {r.status_code} with a non-JSON body"
+            )
+        return datos
+
+    def _token(self, cabeceras: dict) -> str:
+        """Token used in this request, for redaction from errors."""
+        return str(cabeceras.get("Authorization", "")).removeprefix("Bearer ")
+
+    def _get(
+        self, client: httpx.Client, url: str, cabeceras: dict, params: dict, scope: str
+    ) -> dict:
+        r = client.get(url, headers=cabeceras, params=params)
+        return self._respuesta(r, scope, self._token(cabeceras))
+
+    def _post(
+        self, client: httpx.Client, url: str, cabeceras: dict,
+        params: dict, cuerpo: dict, scope: str,
+    ) -> dict:
+        r = client.post(url, headers=cabeceras, params=params, json=cuerpo)
+        return self._respuesta(r, scope, self._token(cabeceras))