socialcli 0.3.0__py3-none-any.whl

socialctl/metricas/instagram.py

@@ -0,0 +1,133 @@
+"""Read Instagram Business metrics via Graph API, sharing Facebook token handling, insights parsing and sanitized errors."""
+
+from __future__ import annotations
+
+from datetime import date
+
+import httpx
+
+from socialctl.auth import obtener_token
+from socialctl.authflow import GRAFO
+from socialctl.brands import Brand
+from socialctl.metricas.base import Lector
+from socialctl.metricas.facebook import (
+    CLAVE_ENRIQUECIMIENTO_FALLIDO,
+    POR_PAGINA_META,
+    comprobar_respuesta,
+    fecha_meta,
+    id_de_cuenta,
+    pedir_listado_con_insights,
+    valor_insight,
+)
+from socialctl.metricas.modelos import (
+    Cuenta,
+    EstadoLectura,
+    LecturaRed,
+    Metricas,
+    Pieza,
+    TipoPieza,
+)
+from socialctl.models import Platform
+
+#: Las cinco comprobadas vivas el 2026-09-11 contra @histo.past en la Graph
+#: API v26.0. `views` es la que cuenta reproducciones y aplica a todo tipo de
+#: media, no solo a vídeo; va a `Metricas.vistas`, que es su sitio.
+#:
+#: Retiradas en v26.0, y por eso ausentes de esta lista: `impressions` -el
+#: error lo dice literal: «The Media Insights API does not support the
+#: impressions metric»- y `plays`, sustituida por `views`. A diferencia de
+#: Facebook, aquí `reach` sigue vivo, así que Instagram **sí** conserva su
+#: campo `alcance`.
+METRICAS_MEDIA = "reach,saved,shares,total_interactions,views"
+
+#: El resto de `fields` del listado de medias, sin el bloque de insights.
+#: Igual que `CAMPOS_POST` en `socialctl/metricas/facebook.py`: ninguno de
+#: estos depende de una métrica de insights, así que ninguno se pierde
+#: cuando `pedir_listado_con_insights` reintenta sin ese bloque.
+CAMPOS_MEDIA = "id,caption,media_type,timestamp,permalink,like_count,comments_count"
+
+
+class InstagramLector(Lector):
+    platform = Platform.INSTAGRAM
+
+    def leer(
+        self, brand: Brand, client: httpx.Client, desde: date | None
+    ) -> LecturaRed:
+        token = obtener_token(brand, self.platform, client)
+        ig_id = id_de_cuenta(brand, "instagram", "ig_user_id")
+
+        cuenta_cruda = self._pedir(
+            client, f"{GRAFO}/{ig_id}",
+            {"fields": "followers_count,media_count", "access_token": token},
+        )
+        cuenta = Cuenta(
+            seguidores=cuenta_cruda.get("followers_count"),
+            total_piezas=cuenta_cruda.get("media_count"),
+        )
+
+        # Mismo mecanismo que Facebook (ver `pedir_listado_con_insights` en
+        # `socialctl/metricas/facebook.py`): si Meta retiró el nombre de
+        # alguna métrica pedida, la petición del listado responde 400 y se
+        # reintenta sin el bloque de insights en vez de perder el listado
+        # entero. `motivo_degradacion` es `None` salvo que haya hecho falta
+        # ese reintento.
+        medias, motivo_degradacion = pedir_listado_con_insights(
+            client, f"{GRAFO}/{ig_id}/media", CAMPOS_MEDIA, METRICAS_MEDIA,
+            {"limit": POR_PAGINA_META}, self.platform, "instagram_manage_insights", token,
+        )
+
+        piezas = []
+        for media in medias.get("data", []):
+            publicado = fecha_meta(media["timestamp"])
+            if desde is not None and publicado.date() < desde:
+                continue
+            insights = media.get("insights", {})
+            pieza = Pieza(
+                id=media["id"],
+                url=media.get("permalink", ""),
+                titulo=(media.get("caption") or "")[:120],
+                publicado_el=publicado,
+                tipo=(
+                    # `media_type` solo vale IMAGE, VIDEO o CAROUSEL_ALBUM
+                    # (documentado). Que un reel llegue con
+                    # `media_type: "VIDEO"` es, en cambio, una SUPOSICIÓN
+                    # heredada del plan original: no está entre los datos
+                    # verificados el 2026-09-11 contra @histo.past -esa
+                    # cuenta no tenía ningún reel que comprobar-, así que no
+                    # se afirma como dato comprobado. Si aparece uno con otro
+                    # `media_type`, esta es la primera línea sospechosa.
+                    TipoPieza.VERTICAL
+                    if media.get("media_type") == "VIDEO"
+                    else TipoPieza.IMAGEN
+                ),
+                acumulado=Metricas(
+                    vistas=valor_insight(insights, "views"),
+                    likes=media.get("like_count"),
+                    comentarios=media.get("comments_count"),
+                    guardados=valor_insight(insights, "saved"),
+                    compartidos=valor_insight(insights, "shares"),
+                ),
+                especificas={
+                    "alcance": valor_insight(insights, "reach"),
+                    "interacciones_totales": valor_insight(insights, "total_interactions"),
+                },
+            )
+            if motivo_degradacion is not None:
+                # Señal de lectura parcial, igual que en Facebook: ver
+                # `CLAVE_ENRIQUECIMIENTO_FALLIDO` en
+                # `socialctl/metricas/youtube.py`.
+                pieza.especificas[CLAVE_ENRIQUECIMIENTO_FALLIDO] = motivo_degradacion
+            piezas.append(pieza)
+
+        return LecturaRed(estado=EstadoLectura.OK, account_id=ig_id, cuenta=cuenta, piezas=piezas)
+
+    def _pedir(self, client: httpx.Client, url: str, params: dict) -> dict:
+        # Sin `raise_for_status()`, por lo mismo que en Facebook: el token
+        # viaja en la URL y el mensaje de esa excepción la lleva entera.
+        r = client.get(url, params=params)
+        return comprobar_respuesta(
+            r,
+            self.platform,
+            "instagram_manage_insights",
+            str(params.get("access_token") or ""),
+        )

socialctl/metricas/modelos.py

@@ -0,0 +1,87 @@
+"""Common metrics across four platforms. Missing provider fields are None, never zero; zero is an observed value."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from socialctl.models import Platform
+
+
+class EstadoLectura(str, Enum):
+    """Outcome of a platform metrics read."""
+
+    OK = "ok"
+    ERROR = "error"
+    SIN_CREDENCIALES = "sin_credenciales"
+    SIN_PERMISO = "sin_permiso"
+
+
+class TipoPieza(str, Enum):
+    LARGO = "largo"
+    VERTICAL = "vertical"
+    IMAGEN = "imagen"
+
+
+class Metricas(BaseModel):
+    vistas: int | None = None
+    likes: int | None = None
+    comentarios: int | None = None
+    compartidos: int | None = None
+    guardados: int | None = None
+
+
+class Cuenta(BaseModel):
+    seguidores: int | None = None
+    total_piezas: int | None = None
+    total_vistas: int | None = None
+
+
+class Audiencia(BaseModel):
+    """Channel audience breakdown; currently supplied only by YouTube."""
+
+    paises: dict[str, float] = Field(default_factory=dict)
+    edades: dict[str, float] = Field(default_factory=dict)
+
+
+class Pieza(BaseModel):
+    id: str
+    url: str
+    titulo: str
+    publicado_el: datetime
+    tipo: TipoPieza
+    slug: str | None = None
+    duracion_seg: int | None = None
+    """Actual technical media duration in seconds when provider supplies it; editorial fallback may be entered only when absent."""
+    acumulado: Metricas = Field(default_factory=Metricas)
+    # `ultimos_28_dias` vivía aquí y se ha quitado: ningún lector lo
+    # rellenaba, nadie lo leía (ni `resumen.md`, ni `piezas.yml`, ni el
+    # skill) y salía como `null` en cada pieza de cada snapshot versionado,
+    # sugiriendo un dato que no existe. Un campo que nadie escribe no
+    # documenta un plan, documenta una promesa incumplida. Los snapshots
+    # antiguos que lo llevan se siguen leyendo sin problema: pydantic ignora
+    # las claves que el modelo ya no declara. Si algún día se quiere de
+    # verdad -la ventana de 28 días que da la API de YouTube-, vuelve con el
+    # lector que lo rellene, no antes.
+    especificas: dict[str, Any] = Field(default_factory=dict)
+
+
+class LecturaRed(BaseModel):
+    estado: EstadoLectura
+    account_id: str | None = None
+    failure_code: str | None = None
+    error: str | None = None
+    warnings: list[str] = Field(default_factory=list)
+    observed_at: datetime | None = None
+    cuenta: Cuenta | None = None
+    piezas: list[Pieza] = Field(default_factory=list)
+    audiencia: Audiencia | None = None
+
+
+class Snapshot(BaseModel):
+    fecha: date
+    marca: str
+    redes: dict[Platform, LecturaRed] = Field(default_factory=dict)

socialctl/metricas/piezas.py

@@ -0,0 +1,134 @@
+"""Preserve editorial attributes in <Brand>/metricas/piezas.yml while refreshing technical API/post data. Unknown user keys survive; malformed or duplicate entries warn and degrade gracefully."""
+
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+
+import yaml
+
+from socialctl.brands import Brand
+from socialctl.metricas.almacen import dir_metricas, escribir_atomico
+from socialctl.metricas.modelos import Snapshot
+
+
+class PiezasIlegibles(Exception):
+    """Existing piezas.yml cannot be read and must not be overwritten, since editorial data cannot be regenerated from APIs."""
+
+CAMPOS_EDITORIALES = ("episodio", "pilar", "gancho", "notas")
+"""Editorial fields are initialized empty by stats and never overwritten. Duration is technical and refreshed only when provider supplies it."""
+
+
+def ruta_piezas(brand: Brand) -> Path:
+    return dir_metricas(brand) / "piezas.yml"
+
+
+def cargar_piezas(brand: Brand) -> list[dict]:
+    """Load piezas.yml or return an empty list if absent; reject unreadable or non-list YAML to preserve editorial data."""
+    ruta = ruta_piezas(brand)
+    if not ruta.is_file():
+        return []
+    texto = ruta.read_text(encoding="utf-8")
+    try:
+        datos = yaml.safe_load(texto)
+    except yaml.YAMLError as exc:
+        raise PiezasIlegibles(
+            f"{ruta} is not valid YAML ({exc.__class__.__name__}); it is not "
+            "modified to avoid deleting editorial data. Repair it manually "
+            "—or move it aside to start over—and "
+            "run stats."
+        ) from exc
+    if datos is None and not texto.strip():
+        # Un fichero vacío del todo: no hay nada escrito que perder.
+        return []
+    if not isinstance(datos, list):
+        raise PiezasIlegibles(
+            f"{ruta} should be a list of items but is "
+            f"{type(datos).__name__}; left unchanged to avoid deleting editorial data "
+            "it contains. Repair it manually and rerun stats."
+        )
+    return datos
+
+
+def fusionar(existentes: list[dict], snapshot: Snapshot) -> list[dict]:
+    """Pure merge of provider data and existing editorial entries. Discard malformed entries with warnings; later duplicate identities win, with warnings."""
+    por_clave: dict[tuple, dict] = {}
+    for posicion, entrada_cruda in enumerate(existentes):
+        if not isinstance(entrada_cruda, dict):
+            warnings.warn(
+                f"piezas.yml: entry number {posicion + 1} is not a "
+                f"dictionary (type {type(entrada_cruda).__name__}: "
+                f"{entrada_cruda!r}); ignored. Repair it manually in "
+                "file and rerun stats.",
+                stacklevel=2,
+            )
+            continue
+
+        clave = (entrada_cruda.get("red"), entrada_cruda.get("id"))
+        anterior = por_clave.get(clave)
+        if anterior is not None:
+            identidad = (
+                "without 'red' or 'id'"
+                if clave == (None, None)
+                else f"red={clave[0]!r}, id={clave[1]!r}"
+            )
+            warnings.warn(
+                f"piezas.yml: two entries share the same identity "
+                f"({identidad}): item titled {anterior.get('titulo')!r} is "
+                f"discarded in favor of item titled "
+                f"{entrada_cruda.get('titulo')!r}. Assign distinct 'red' and 'id' values "
+                "in the file to distinguish them.",
+                stacklevel=2,
+            )
+        por_clave[clave] = dict(entrada_cruda)
+
+    for platform, lectura in snapshot.redes.items():
+        for pieza in lectura.piezas:
+            clave = (platform.value, pieza.id)
+            entrada = por_clave.get(clave, {campo: None for campo in CAMPOS_EDITORIALES})
+            entrada.update({
+                "red": platform.value,
+                "id": pieza.id,
+                "tipo": pieza.tipo.value,
+                "publicado_el": pieza.publicado_el.isoformat(),
+                "titulo": pieza.titulo,
+                **({"api_observed_at": (lectura.observed_at.isoformat() if lectura.observed_at else snapshot.fecha.isoformat())} if platform.value == "youtube" else {}),
+            })
+            if pieza.slug is not None:
+                # El cruce con `posts/` lo resolvió: manda el cruce.
+                entrada["slug"] = pieza.slug
+            else:
+                # No se resolvió: una pieza publicada fuera de `socialctl`, o
+                # un TikTok cuyo `resultado.json` no guarda la URL, que es el
+                # caso habitual. Se conserva lo que hubiera, porque puede
+                # haberlo escrito el gestor a mano. Misma regla asimétrica
+                # que `duracion_seg`, y por el mismo motivo: lo que esta
+                # ejecución no trae, no se toca.
+                entrada.setdefault("slug", None)
+            if pieza.duracion_seg is not None:
+                # La red la da: manda la red.
+                entrada["duracion_seg"] = pieza.duracion_seg
+            else:
+                # La red no la da (TikTok, Instagram): se conserva lo que
+                # hubiera, que puede haberlo escrito el gestor a mano.
+                entrada.setdefault("duracion_seg", None)
+            for campo in CAMPOS_EDITORIALES:
+                entrada.setdefault(campo, None)
+            por_clave[clave] = entrada
+
+    return sorted(
+        por_clave.values(),
+        key=lambda e: (e.get("publicado_el") or "", e.get("red") or ""),
+    )
+
+
+def guardar_piezas(brand: Brand, piezas: list[dict]) -> Path:
+    """Atomically rewrite piezas.yml with supplied entries. YAML comments are lost; preserve annotations in notas and retain all user-defined keys."""
+    return escribir_atomico(
+        ruta_piezas(brand),
+        yaml.safe_dump(piezas, allow_unicode=True, sort_keys=False),
+    )
+
+
+def actualizar_piezas(brand: Brand, snapshot: Snapshot) -> Path:
+    return guardar_piezas(brand, fusionar(cargar_piezas(brand), snapshot))

socialctl/metricas/reach.py

@@ -0,0 +1,94 @@
+"""Select and aggregate imported YouTube Reporting thumbnail reach observations."""
+
+from datetime import date, datetime, timedelta, timezone
+import math
+
+REPORT_TYPES = {'channel_reach_basic_a1', 'channel_reach_combined_a1'}
+
+
+def _day(value: str) -> date:
+    if len(value) != 8 or not value.isdigit():
+        raise ValueError('Reporting date must be YYYYMMDD')
+    return date.fromisoformat(f'{value[:4]}-{value[4:6]}-{value[6:]}')
+
+
+def _instant(value: str) -> datetime:
+    when = datetime.fromisoformat(value.replace('Z', '+00:00'))
+    if when.utcoffset() is None:
+        raise ValueError('Report creation time needs timezone')
+    return when.astimezone(timezone.utc)
+
+
+def reach_by_video_day(observations: list[dict]) -> dict[tuple[str, date], dict]:
+    """Prefer the newest report for overlapping video/day keys."""
+    selected = {}
+    for observation in observations:
+        binding = observation.get('binding', {})
+        report_type = binding.get('report_type_id')
+        if binding.get('source') != 'youtubeReporting' or report_type not in REPORT_TYPES:
+            continue
+        report = binding.get('report', {})
+        created = _instant(report['createTime'])
+        report_id = report['id']
+        priority = (created, int(report_type == 'channel_reach_combined_a1'), report_id)
+        for row in observation.get('rows', []):
+            dimensions = row.get('dimensions', {})
+            video_id = dimensions.get('video_id')
+            if not isinstance(video_id, str) or not video_id:
+                continue
+            day = _day(dimensions['date'])
+            metrics = row.get('metrics', {})
+            impressions = metrics.get('video_thumbnail_impressions', {}).get('value')
+            ctr = metrics.get('video_thumbnail_impressions_ctr', {}).get('value')
+            if (type(impressions) is not int or impressions < 0 or
+                    ctr is not None and (not isinstance(ctr, (int, float)) or
+                                         not math.isfinite(ctr) or not 0 <= ctr <= 100)):
+                continue
+            key = (video_id, day)
+            if key not in selected or priority > selected[key]['priority']:
+                selected[key] = {
+                    'impressions': impressions,
+                    'ctr': float(ctr) if ctr is not None else None,
+                    'report_id': report_id,
+                    'report_type': report_type,
+                    'generated_at': created.isoformat(),
+                    'priority': priority,
+                }
+    for item in selected.values():
+        item.pop('priority')
+    return selected
+
+
+def reach_for_video(rows: dict[tuple[str, date], dict], video_id: str,
+                    as_of: date, *, days: int = 28) -> dict | None:
+    """Return count and impression-weighted CTR; absence is None, never zero."""
+    if days < 1:
+        raise ValueError('Positive reporting window required')
+    start = as_of - timedelta(days=days - 1)
+    matched = sorted((day, value) for (vid, day), value in rows.items()
+                     if vid == video_id and start <= day <= as_of)
+    if not matched:
+        return None
+    impressions = sum(value['impressions'] for _, value in matched)
+    ctr_denominator = sum(value['impressions'] for _, value in matched
+                          if value['ctr'] is not None)
+    ctr = (round(sum(value['impressions'] * value['ctr'] for _, value in matched
+                     if value['ctr'] is not None) / ctr_denominator, 2)
+           if ctr_denominator else None)
+    return {
+        'impressions': impressions,
+        'ctr': ctr,
+        'from': start.isoformat(),
+        'through': matched[-1][0].isoformat(),
+        'report_ids': list(dict.fromkeys(value['report_id'] for _, value in matched)),
+        'source': 'youtubeReporting',
+    }
+
+
+def attach_reach(pieces, observations: list[dict], as_of: date) -> None:
+    """Enrich matching YouTube pieces with a bounded Reporting observation."""
+    rows = reach_by_video_day(observations)
+    for piece in pieces:
+        value = reach_for_video(rows, piece.id, as_of)
+        if value is not None:
+            piece.especificas['thumbnail_reach_28d'] = value

socialctl/metricas/reporting_client.py

@@ -0,0 +1,112 @@
+"""Reporting jobs/reports identity chain and explicit bounded CSV downloads."""
+from datetime import date, datetime, time, timedelta, timezone
+import re
+from urllib.parse import urlsplit, unquote
+
+from socialctl.management.youtube_resources import ResourceError
+from socialctl.metricas.analytics_client import AnalyticsClient, REPORTING, complete, encoded, opaque
+from socialctl.metricas.analytics_schema import PACIFIC
+
+MAX_CSV = 16 * 1024 * 1024
+ANALYTICS_SCOPES = {"https://www.googleapis.com/auth/yt-analytics.readonly", "https://www.googleapis.com/auth/yt-analytics-monetary.readonly"}
+
+
+def instant(value):
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        if parsed.tzinfo is None:
+            raise ValueError()
+        return parsed.astimezone(timezone.utc)
+    except (ValueError, TypeError, AttributeError):
+        raise ResourceError("invalid provider timestamp") from None
+
+
+def report_period(report):
+    start, end = instant(report.get("startTime")), instant(report.get("endTime"))
+    local_start, local_end = start.astimezone(PACIFIC), end.astimezone(PACIFIC)
+    if end <= start or local_start.time() != time.min or local_end.time() != time.min or (end-start).days > 366:
+        raise ResourceError("report period must be bounded Pacific midnight intervals")
+    return local_start.date(), local_end.date() - timedelta(days=1)
+
+
+def validate_download_url(value):
+    if not isinstance(value, str) or not 1 <= len(value) <= 1000 or not value.isascii() or any(ord(c) <= 32 for c in value):
+        raise ResourceError("invalid report download URL")
+    parsed = urlsplit(value)
+    if parsed.scheme != "https" or parsed.netloc != "youtubereporting.googleapis.com" or parsed.fragment or parsed.query != "alt=media":
+        raise ResourceError("report download host/query not allowed")
+    if not parsed.path.startswith("/v1/media/") or not re.fullmatch(r"/[A-Za-z0-9._~%/-]+", parsed.path):
+        raise ResourceError("report download path not allowed")
+    segments = parsed.path[len("/v1/media/"):].split("/")
+    if any(not s or unquote(s) in {".", ".."} or any(c in unquote(s) for c in "/\\%?#") for s in segments):
+        raise ResourceError("noncanonical report download path")
+    return value
+
+
+class ReportingClient(AnalyticsClient):
+    def report_types(self, max_pages=100):
+        self.identity()
+        return self.pages(f"{REPORTING}/reportTypes", "reportTypes", {"pageSize": 100, "includeSystemManaged": "true"}, max_pages)
+
+    def jobs(self, max_pages=100):
+        self.identity()
+        result = self.pages(f"{REPORTING}/jobs", "jobs", {"pageSize": 100, "includeSystemManaged": "true"}, max_pages)
+        for row in result["items"]:
+            opaque(row.get("reportTypeId"))
+            if not isinstance(row.get("name"), str):
+                raise ResourceError("job schema invalid")
+        return result
+
+    def job(self, job_id, report_type_id=None):
+        rows = [r for r in complete(self.jobs()) if r["id"] == opaque(job_id)]
+        if len(rows) != 1:
+            raise ResourceError("job not verified for authenticated account")
+        row = self._json(self.service_request("GET", f"{REPORTING}/jobs/{encoded(job_id)}"))
+        if row.get("id") != job_id or row.get("reportTypeId") != rows[0]["reportTypeId"] or report_type_id is not None and row["reportTypeId"] != report_type_id:
+            raise ResourceError("job/report type identity mismatch")
+        return row
+
+    def reports(self, job_id, report_type_id, max_pages=100, created_after=None, start_time_at_or_after=None, start_time_before=None):
+        self.job(job_id, report_type_id)
+        params = {"pageSize": 100}
+        for key, value in {"createdAfter": created_after, "startTimeAtOrAfter": start_time_at_or_after, "startTimeBefore": start_time_before}.items():
+            if value is not None:
+                instant(value)
+                params[key] = value
+        result = self.pages(f"{REPORTING}/jobs/{encoded(job_id)}/reports", "reports", params, max_pages)
+        for row in result["items"]:
+            self._validate_report(row, job_id)
+        return result
+
+    @staticmethod
+    def _validate_report(row, job_id, report_id=None):
+        if row.get("jobId") != job_id or report_id is not None and row.get("id") != report_id:
+            raise ResourceError("report/job identity mismatch")
+        opaque(row.get("id"))
+        report_period(row)
+        instant(row.get("createTime"))
+        validate_download_url(row.get("downloadUrl"))
+        return row
+
+    def report(self, job_id, report_type_id, report_id):
+        self.job(job_id, report_type_id)
+        row = self._json(self.service_request("GET", f"{REPORTING}/jobs/{encoded(job_id)}/reports/{encoded(report_id)}"))
+        return self._validate_report(row, job_id, report_id)
+
+    def download(self, *, job_id, report_type_id, report_id, start_date, end_date):
+        account = self.identity()
+        types = complete(self.report_types())
+        if not any(r["id"] == report_type_id for r in types):
+            raise ResourceError("report type unavailable for authenticated account")
+        row = self.report(job_id, report_type_id, report_id)
+        start, end = report_period(row)
+        if (start.isoformat(), end.isoformat()) != (start_date, end_date):
+            raise ResourceError("explicit report dates mismatch")
+        url = validate_download_url(row["downloadUrl"])
+        # Only this method may call the download transport, after exact discovery
+        # and account/job/type/report/date binding. No bearer follows redirects.
+        data = self._bounded_request("GET", url, max_bytes=MAX_CSV).content
+        if not data:
+            raise ResourceError("empty download; header-only CSV is valid, zero bytes is not")
+        return {"source": "youtubeReporting", "account_id": account, "report_type_id": report_type_id,
+            "job_id": job_id, "report": row, "credential_observation": self.credential_observation}, data