@danhachuel/thunderbolt 0.5.52 → 0.5.54

package/app/main.py

@@ -1521,6 +1521,14 @@ def render_growth_youtube():
         for label in ("Demanda validada", "Qualidade da thumbnail", "Qualidade do título", "Hook — retenção inicial", "Ritmo e edição", "Origem do tráfego", "Conversão em inscritos", "Cadência de publicação")
     ]
     overall = int(selected_record.get("overall_score", 0)) if selected_record else None
+    if selected_record:
+        analytics_state = (selected_record.get("analytics") or {}).get("status", "not_connected")
+        if analytics_state == "ready":
+            st.success("Dados internos activos: YouTube Analytics OAuth aplicado à análise.")
+        elif analytics_state in {"requires_authorization", "not_connected"}:
+            st.info("Dados públicos activos. Para CTR, retenção, tráfego, RPM e demografia, autorize a conta Google proprietária do canal; os valores privados não são estimados como reais.")
+        else:
+            st.warning("A consulta YouTube Analytics não ficou disponível; os cartões afectados estão marcados como estimados ou indisponíveis.")
     color = _growth_score_color(overall) if overall is not None else "#64748b"
     score_text = str(overall) if overall is not None else "—"
     score_suffix = "/100" if overall is not None else ""

package/hermes_ui/growth_youtube.py

@@ -39,7 +39,7 @@ def _safe_int(value: Any, default: int = 0) -> int:
         return default
 
 
-def _public_videos(channel_url: str, limit: int = 10) -> list[dict[str, Any]]:
+def _public_videos(channel_url: str, limit: int = 3) -> list[dict[str, Any]]:
     try:
         import yt_dlp
     except ImportError as exc:
@@ -183,14 +183,15 @@ def analyse_thumbnail_with_paligemma(path: str, card: Mapping[str, Any]) -> dict
 
 
 def _report_markdown(record: Mapping[str, Any]) -> str:
-    lines = [f"# CHANNEL AUDIT REPORT: {record.get('channel_name', 'Canal')}", "", f"- Código: `{record.get('code')}`", "- Plataforma: YouTube", f"- Data: {record.get('created_at')}", f"- Nota geral: **{record.get('overall_score', 0)}/100**", "", "## 1. Projecção financeira e contexto", "", "A análise pública não expõe RPM, país da audiência nem horas de visualização. O relatório não inventa estes valores. Para referência do agente, o YPP usa 1.000 inscritos e 4.000 horas de vídeos longos em 12 meses ou 10 milhões de visualizações de Shorts em 90 dias até 31/01/2027; a partir de 01/02/2027 a meta de Shorts indicada pelo agente é 20 milhões.", "", "## 2. Resumo do diagnóstico", "", "| Pilar | Nota | Métrica observada | Resultado |", "|---|---:|---|---|"]
+    analytics = record.get("analytics") or {}
+    lines = [f"# CHANNEL AUDIT REPORT: {record.get('channel_name', 'Canal')}", "", f"- Código: `{record.get('code')}`", "- Plataforma: YouTube", f"- Data: {record.get('created_at')}", f"- Nota geral: **{record.get('overall_score', 0)}/100**", "", "## 1. Projecção financeira e contexto", "", "A análise pública não expõe RPM, país da audiência nem horas de visualização. O relatório não inventa estes valores. Para referência do agente, o YPP usa 1.000 inscritos e 4.000 horas de vídeos longos em 12 meses ou 10 milhões de visualizações de Shorts em 90 dias até 31/01/2027; a partir de 01/02/2027 a meta de Shorts indicada pelo agente é 20 milhões.", "", "## 2. Resumo do diagnóstico", "", "| Pilar | Nota | Métrica observada | Origem | Diagnóstico |", "|---|---:|---|---|---|"]
     pillar_names = {"Demanda validada": "Demanda", "Qualidade da thumbnail": "Thumbnail", "Qualidade do título": "Título", "Hook — retenção inicial": "Hook", "Ritmo e edição": "Pacing", "Origem do tráfego": "Tráfego", "Conversão em inscritos": "CTA", "Cadência de publicação": "Cadência"}
     for metric in record.get("metrics", []):
-        lines.append(f"| **{pillar_names.get(metric['label'], metric['label'])}** | {metric['score']}/100 | {metric['value']} | {metric['diagnosis']} |")
-    lines += ["", "## 3. Últimos 10 vídeos", "", "| Título | Visualizações | Thumbnail | Transcrição | Nota do título |", "|---|---:|---|---|---:|"]
+        lines.append(f"| **{pillar_names.get(metric['label'], metric['label'])}** | {metric['score']}/100 | {metric['value']} | {metric.get('source', 'unknown')} | {metric['diagnosis']} |")
+    lines += ["", "## 3. Últimos 3 vídeos", "", "| Título | Visualizações | Thumbnail | Transcrição | Nota do título |", "|---|---:|---|---|---:|"]
     for video in record.get("videos", []):
         lines.append(f"| {video.get('title', '').replace('|', '/')} | {video.get('view_count', 0):,} | {video.get('thumbnail_status', '')} | {video.get('transcript_status', '')} | {video.get('title_score', 0)}/100 |")
-    lines += ["", "## 4. Actionable Roadmap — Top 3 prioridades", "", "1. **REMAKE THUMBNAILS** dos vídeos abaixo de 70: aumentar contraste, sujeito claro, emoção forte e máximo de três palavras legíveis no telemóvel.", "2. **REWRITE TITLES** com Curiosity, Clarity e Urgency; colocar a keyword principal no início e usar números/adjectivos de poder quando forem verdadeiros.", "3. **EDIT HOOK**: começar pelo resultado, promessa ou estatística forte e introduzir pattern interrupts a cada 5–8 segundos.", "", "## 5. Estratégia de longo prazo", "", "Construir uma biblioteca de pelo menos 50 vídeos evergreen, publicar com cadência semanal fixa e procurar que Browse Features se torne a principal origem de tráfego. Para um criador solo, consistência supera frequência; melhorar Thumbnail + Título antes de alterar a produção.", "", "## Limitações", "", "CTR, retenção real, origem de tráfego, RPM e horas de visualização exigem dados autorizados do YouTube Studio e não são inventados a partir da página pública."]
+    lines += ["", "## 4. Dados internos do YouTube Studio", "", f"Estado Analytics: **{analytics.get('status', 'not_connected')}**. {analytics.get('message', 'Sem OAuth Analytics autorizado; os valores privados permanecem indisponíveis ou estimados.')}", "", "## 5. Actionable Roadmap — Top 3 prioridades", "", "1. **REMAKE THUMBNAILS** dos vídeos abaixo de 70: aumentar contraste, sujeito claro, emoção forte e máximo de três palavras legíveis no telemóvel.", "2. **REWRITE TITLES** com Curiosity, Clarity e Urgency; colocar a keyword principal no início e usar números/adjectivos de poder quando forem verdadeiros.", "3. **EDIT HOOK**: começar pelo resultado, promessa ou estatística forte e introduzir pattern interrupts a cada 5–8 segundos.", "", "## 6. Estratégia de longo prazo", "", "Construir uma biblioteca de pelo menos 50 vídeos evergreen, publicar com cadência semanal fixa e procurar que Browse Features se torne a principal origem de tráfego. Para um criador solo, consistência supera frequência; melhorar Thumbnail + Título antes de alterar a produção.", "", "## Limitações", "", "CTR, retenção real, origem de tráfego, RPM e horas de visualização exigem dados autorizados do YouTube Studio e não são inventados a partir da página pública."]
     return "\n".join(lines) + "\n"
 
 
@@ -202,9 +203,9 @@ def run_audit(channel: Mapping[str, Any], settings: Mapping[str, Any], *, vision
     channel_url = str(channel.get("url") or channel.get("handle") or "").strip()
     if not channel_url:
         raise RuntimeError("O canal seleccionado não tem URL pública ou handle YouTube.")
-    notify("A buscar o canal e os 10 vídeos mais recentes…")
+    notify("A buscar o canal e os 3 vídeos mais recentes…")
     try:
-        videos = _public_videos(channel_url, 10)
+        videos = _public_videos(channel_url, 3)
     except Exception as exc:
         failed = {"code": code, "channel_id": str(channel.get("id") or ""), "channel_name": str(channel.get("name") or "Canal"), "platform": "YouTube", "created_at": datetime.now(timezone.utc).isoformat(), "status": "failed", "error": str(exc)[:500]}
         analyses = read_json(ANALYSES_FILENAME, [])
@@ -242,19 +243,29 @@ def run_audit(channel: Mapping[str, Any], settings: Mapping[str, Any], *, vision
             try: video["vision"] = analyse_thumbnail_with_paligemma(video["thumbnail_path"], vision_card)
             except Exception as exc: video["vision"] = {"score": 50, "status": "erro", "diagnosis": str(exc)[:220]}
         else: video["vision"] = {"score": 50, "status": "sem_dados", "diagnosis": "Provider Paligemma não configurado."}
+    analytics: dict[str, Any]
+    try:
+        from integrations.youtube_growth_api import query_channel_analytics
+        analytics = query_channel_analytics(channel, settings, STORAGE)
+    except Exception as exc:
+        analytics = {"status": "query_failed", "message": str(exc)[:300]}
+    analytics_values = analytics.get("values", {}) if analytics.get("status") == "ready" else {}
+    analytics_source = "youtube_analytics_oauth" if analytics_values else "estimated_proxy"
+    analytics_note = "YouTube Analytics OAuth" if analytics_values else str(analytics.get("message") or "Sem dados internos; proxy estimado")
     thumb_scores = [int((video.get("vision") or {}).get("score", 50)) for video in videos]
     metrics = [
-        {"label": "Demanda validada", "score": 50, "value": f"{len(videos)} vídeos públicos", "diagnosis": "Amostra pública recolhida; volume de pesquisa/concorrência não disponível."},
-        {"label": "Qualidade da thumbnail", "score": round(sum(thumb_scores) / len(thumb_scores)), "value": f"{len(videos)} thumbnails analisadas", "diagnosis": "Avaliação Paligemma/NIM ou sem dados quando não configurado."},
-        {"label": "Qualidade do título", "score": round(sum(title_scores) / len(title_scores)), "value": f"{len(videos)} títulos analisados", "diagnosis": "Curiosidade, clareza, urgência, palavras-chave e números."},
-        {"label": "Hook — retenção inicial", "score": round(sum(transcript_scores) / len(transcript_scores)), "value": "Análise textual das aberturas", "diagnosis": "Inferência textual; retenção percentual real não está disponível."},
-        {"label": "Ritmo e edição", "score": 50, "value": "Sem vídeo/curva de retenção", "diagnosis": "Requer gráfico de retenção do YouTube Studio."},
-        {"label": "Origem do tráfego", "score": 50, "value": "Sem dados públicos", "diagnosis": "Requer YouTube Studio."},
-        {"label": "Conversão em inscritos", "score": 50, "value": "Sem inscritos por vídeo", "diagnosis": "Requer Analytics autorizado."},
-        {"label": "Cadência de publicação", "score": 50, "value": "Datas públicas recolhidas", "diagnosis": "Cadência detalhada será calculada quando datas válidas forem fornecidas."},
+        {"label": "Demanda validada", "score": 50, "value": f"{len(videos)} vídeos públicos", "source": "public", "diagnosis": "Amostra pública recolhida; volume de pesquisa/concorrência não disponível."},
+        {"label": "Qualidade da thumbnail", "score": round(sum(thumb_scores) / len(thumb_scores)), "value": f"{len(videos)} thumbnails analisadas", "source": "paligemma" if any((video.get("vision") or {}).get("status") == "analisado" for video in videos) else "estimated", "diagnosis": "Avaliação Paligemma/NIM ou sem dados quando não configurado."},
+        {"label": "Qualidade do título", "score": round(sum(title_scores) / len(title_scores)), "value": f"{len(videos)} títulos analisados", "source": "public", "diagnosis": "Curiosidade, clareza, urgência, palavras-chave e números."},
+        {"label": "Hook — retenção inicial", "score": round(sum(transcript_scores) / len(transcript_scores)), "value": "Análise textual das aberturas", "source": "estimated", "diagnosis": "Inferência textual; retenção percentual real não está disponível."},
+        {"label": "Ritmo e edição", "score": _safe_int(analytics_values.get("averageViewPercentage"), 50) if analytics_values else 50, "value": "Percentagem média assistida (OAuth)" if analytics_values else "Proxy: sem curva de retenção", "source": analytics_source, "diagnosis": analytics_note},
+        {"label": "Origem do tráfego", "score": 50, "value": "Dados de tráfego (OAuth)" if analytics_values else "Indisponível sem OAuth", "source": analytics_source if analytics_values else "unavailable", "diagnosis": analytics_note},
+        {"label": "Conversão em inscritos", "score": 50, "value": f"{analytics_values.get('subscribersGained', '—')} ganhos / {analytics_values.get('subscribersLost', '—')} perdidos" if analytics_values else "Indisponível sem Analytics", "source": analytics_source if analytics_values else "unavailable", "diagnosis": analytics_note},
+        {"label": "Cadência de publicação", "score": 50, "value": "Datas públicas recolhidas", "source": "public", "diagnosis": "Cadência detalhada será calculada quando datas válidas forem fornecidas."},
     ]
-    overall = round(sum(metric["score"] for metric in metrics) / len(metrics))
-    record = {"code": code, "channel_id": str(channel.get("id") or ""), "channel_name": str(channel.get("name") or "Canal"), "platform": "YouTube", "created_at": datetime.now(timezone.utc).isoformat(), "overall_score": overall, "score_color": _score_color(overall), "metrics": metrics, "videos": videos, "status": "completed"}
+    weights = {"Qualidade da thumbnail": 0.30, "Qualidade do título": 0.25, "Hook — retenção inicial": 0.25, "Conversão em inscritos": 0.20}
+    overall = round(sum(metric["score"] * weights.get(metric["label"], 0) for metric in metrics) / sum(weights.values()))
+    record = {"code": code, "channel_id": str(channel.get("youtube_channel_id") or channel.get("id") or ""), "channel_name": str(channel.get("name") or "Canal"), "platform": "YouTube", "created_at": datetime.now(timezone.utc).isoformat(), "overall_score": overall, "score_color": _score_color(overall), "score_weights": weights, "analytics": analytics, "metrics": metrics, "videos": videos, "status": "completed"}
     report_path = root / f"{code}.md"
     report_path.write_text(_report_markdown(record), encoding="utf-8")
     record["report_path"] = str(report_path)

package/integrations/youtube_growth_api.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import json
+from datetime import date, timedelta
+from pathlib import Path
+from typing import Any, Mapping
+
+from .youtube_batch import account_status, token_path
+
+ANALYTICS_SCOPE = "https://www.googleapis.com/auth/yt-analytics.readonly"
+
+
+def _text(value: Any) -> str:
+    return str(value or "").strip()
+
+
+def _accounts(settings: Mapping[str, Any]) -> list[dict[str, Any]]:
+    value = settings.get("youtube_batch_accounts", [])
+    return [dict(item) for item in value if isinstance(item, Mapping)] if isinstance(value, list) else []
+
+
+def find_account_for_channel(channel: Mapping[str, Any], settings: Mapping[str, Any]) -> dict[str, Any] | None:
+    channel_id = _text(channel.get("youtube_channel_id") or channel.get("id"))
+    account_id = _text(channel.get("google_account_id"))
+    accounts = _accounts(settings)
+    for account in accounts:
+        if account_id and _text(account.get("id")) == account_id:
+            return account
+        known_channels = account.get("channels", [])
+        if isinstance(known_channels, list) and any(_text(item.get("youtube_channel_id") or item.get("id")) == channel_id for item in known_channels if isinstance(item, Mapping)):
+            return account
+    return None
+
+
+def _load_credentials(account: Mapping[str, Any], storage_root: Path) -> tuple[Any | None, str]:
+    path = token_path(storage_root, dict(account))
+    status = account_status(dict(account), storage_root)
+    if not status.ok:
+        return None, str(status.message)
+    try:
+        from google.auth.transport.requests import Request
+        from google.oauth2.credentials import Credentials
+        raw = json.loads(path.read_text(encoding="utf-8"))
+        scopes = list(raw.get("scopes") or []) if isinstance(raw, dict) else []
+        if ANALYTICS_SCOPE not in scopes:
+            return None, "OAuth autorizado sem o scope YouTube Analytics; é necessária uma nova autorização condicional."
+        credentials = Credentials.from_authorized_user_info(raw, scopes)
+        if credentials.expired and credentials.refresh_token:
+            credentials.refresh(Request())
+            path.write_text(credentials.to_json(), encoding="utf-8")
+        return credentials, "ready"
+    except ImportError:
+        return None, "Dependências Google OAuth/API não instaladas."
+    except (OSError, ValueError, TypeError) as exc:
+        return None, f"Token OAuth inválido: {exc}"
+
+
+def query_channel_analytics(channel: Mapping[str, Any], settings: Mapping[str, Any], storage_root: Path, *, days: int = 28) -> dict[str, Any]:
+    account = find_account_for_channel(channel, settings)
+    if not account:
+        return {"status": "not_connected", "message": "Nenhuma conta Google OAuth compatível com este canal."}
+    credentials, message = _load_credentials(account, storage_root)
+    if credentials is None:
+        return {"status": "requires_authorization", "message": message, "email": _text(account.get("email"))}
+    channel_id = _text(channel.get("youtube_channel_id") or channel.get("id"))
+    if not channel_id:
+        return {"status": "unavailable", "message": "O canal não tem YouTube channel ID."}
+    try:
+        from googleapiclient.discovery import build
+        analytics = build("youtubeAnalytics", "v2", credentials=credentials, cache_discovery=False)
+        end_date = date.today()
+        start_date = end_date - timedelta(days=max(1, days) - 1)
+        response = analytics.reports().query(
+            ids=f"channel=={channel_id}",
+            startDate=start_date.isoformat(),
+            endDate=end_date.isoformat(),
+            metrics="views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained,subscribersLost",
+        ).execute()
+        rows = response.get("rows", [])
+        headers = [item.get("name") for item in response.get("columnHeaders", [])]
+        values = dict(zip(headers, rows[0])) if rows else {}
+        return {"status": "ready", "source": "youtube_analytics_oauth", "window_days": days, "values": values, "email": _text(account.get("email"))}
+    except ImportError:
+        return {"status": "missing_dependencies", "message": "A biblioteca Google API Client ainda não está instalada."}
+    except Exception as exc:
+        return {"status": "query_failed", "message": str(exc)[:300], "email": _text(account.get("email"))}
+
+
+__all__ = ["ANALYTICS_SCOPE", "find_account_for_channel", "query_channel_analytics"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danhachuel/thunderbolt",
-  "version": "0.5.52",
+  "version": "0.5.54",
   "description": "Thunderbolt — interface local para operação de canais faceless e motor MoneyPrinterTurbo",
   "license": "MIT",
   "main": "scripts/cli.mjs",