@danhachuel/thunderbolt 0.2.22 → 0.2.23

package/MANUAL-INSTALACAO.md

@@ -2,7 +2,7 @@
 
 Este manual descreve a instalação local da UI Thunderbolt, baseada no MoneyPrinterTurbo, utilizando o pacote npm `@danhachuel/thunderbolt`. O fluxo recomendado instala automaticamente o ambiente Python, as dependências da aplicação, as dependências do MoneyPrinterTurbo, o Streamlit e o suporte FFmpeg através de `imageio-ffmpeg`.
 
-> **Versão deste manual:** 0.2.22
+> **Versão deste manual:** 0.2.23
 > **Pacote npm:** `@danhachuel/thunderbolt`
 > **Porta padrão da UI:** `localhost:3030`  
 > **Repositório:** [github.com/DanHachuel/thunderbolt](https://github.com/DanHachuel/thunderbolt)
@@ -100,13 +100,13 @@ Execute:
 Windows PowerShell ou MobaXterm:
 
 ```powershell
-npx.cmd --yes @danhachuel/thunderbolt@0.2.22 install
+npx.cmd --yes @danhachuel/thunderbolt@0.2.23 install
 ```
 
 Linux/macOS:
 
 ```bash
-npx --yes @danhachuel/thunderbolt@0.2.22 install
+npx --yes @danhachuel/thunderbolt@0.2.23 install
 ```
 
 A instalação normal é **segura para actualizações**: preserva `storage`, Blueprints, Brandings, configurações e artefactos do utilizador. Remove apenas `.venv`, o clone técnico do MoneyPrinterTurbo e dependências que serão recriadas. Uma pasta antiga sem dados do utilizador, como `C:\Users\<utilizador>\AppData\Local\hermes` da tentativa incompleta, pode ser removida; uma pasta antiga que contenha Blueprints, Brandings ou storage é preservada e apenas avisada no terminal. Feche processos Python, Node, Streamlit e MobaXterm que estejam a usar as pastas antes de executar.
@@ -339,20 +339,20 @@ Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
 
 ## 8. Configuração inicial da UI
 
-Na primeira execução, abra **Configurações** e reveja:
+Na primeira execução, abra **Configurações** e reveja. Para YouTube, preencha primeiro o par **OAuth Client ID + OAuth Client Secret** se pretende autorizar uploads. A **YouTube Data API Key** é uma credencial Google Cloud diferente e fica numa área opcional, apenas para o método oficial de métricas; Client ID + Client Secret não formam uma API Key.
 
 | Configuração | Finalidade |
 |---|---|
 | Porta Streamlit | Definir a porta local da UI |
 | Pasta MoneyPrinterTurbo | Indicar o clone local que será sincronizado com `config.toml` |
-| YouTube Data API Key | Permitir importar nome, handle e métricas públicas de canais |
-| YouTube OAuth Client ID | Identificar a aplicação OAuth 2.0 do Google para operações autenticadas |
-| YouTube OAuth Client Secret | Secret do mesmo cliente OAuth 2.0; não é a Data API Key |
+| YouTube Data API Key (opcional) | Permitir o método oficial Data API para métricas públicas; não é necessária para a página pública nem para OAuth |
+| YouTube OAuth Client ID | Identificar a aplicação OAuth 2.0 do Google para autorizar operações autenticadas, como upload |
+| YouTube OAuth Client Secret | Secret do mesmo cliente OAuth 2.0; não é uma Data API Key nem um token de acesso |
 | YouTube upload principal | Lógica do `youtube-automation-agent` adaptada e executada dentro do Thunderbolt |
 | OAuth directo de redundância | Caminho alternativo accionado automaticamente se o agente falhar |
 | TikTok Client ID/Secret | Credenciais da aplicação; Redirect URI, scopes e autorização ficam no TikTok for Developers Playground |
 
-As chaves devem ser inseridas apenas na configuração local. Não as coloque no GitHub, no `package.json`, em blueprints ou em ficheiros de estado versionados.
+As credenciais devem ser inseridas apenas na configuração local. A Data API Key, o OAuth Client ID e o OAuth Client Secret são valores diferentes; Client ID + Secret não geram uma API Key nem um token OAuth até a conta ser autorizada. Não coloque nenhum deles no GitHub, no `package.json`, em blueprints ou em ficheiros de estado versionados.
 
 ## 9. Testar as áreas principais
 
@@ -361,10 +361,10 @@ Após iniciar a aplicação, valide o seguinte percurso:
 1. **Dashboard:** confirme que a UI abre e mostra o estado local.
 2. **Blueprints:** coloque um JSON em `~/.thunderbolt/storage/blueprints/importados/` (Windows: `%LOCALAPPDATA%\\THUNDERBOLT\storage\blueprints\importados\`) ou use o carregador da interface.
 3. **Brandings:** abra a subaba **Brandings** e confirme a listagem dos ficheiros JSON.
-4. **Canais:** em **Importar do YouTube**, use o método **Página pública — sem API Key** ou a Data API opcional; em **Cadastro manual**, preencha os dados sem qualquer consulta externa.
+4. **Canais:** em **Importar do YouTube**, use o método **Página pública — sem API Key** com um URL `/channel/UC...`, um handle ou uma subpágina `/videos`; o parser resolve o ID, consulta a página pública e tenta o RSS quando necessário. Confirme que o resultado abre o formulário de revisão sem Data API Key. Se o canal não existir ou não fornecer metadados, confirme a mensagem clara e que o formulário de uma pesquisa anterior desaparece. A Data API é opcional e fica separada; em **Cadastro manual**, preencha os dados sem qualquer consulta externa.
 5. **Novo vídeo:** teste primeiro o modo **Canal específico** e depois os modos de lote.
 6. **Novo vídeo > Vídeos:** verifique o estado `to_do` e os botões **Iniciar** e **Parar** dentro da subaba.
-7. **Upload:** autorize primeiro o **youtube-automation-agent** na própria aba, confirme o estado **pronto para publicar**, preencha título/descrição/tags e publique um MP4 real. O botão **Autorizar fallback OAuth** existe apenas para redundância; a Data API Key é exclusivamente para consultas públicas.
+7. **Upload:** configure o OAuth Client ID e Secret, autorize primeiro o **youtube-automation-agent** na própria aba, confirme o estado **pronto para publicar**, preencha título/descrição/tags e publique um MP4 real. O botão **Autorizar fallback OAuth** existe apenas para redundância; a Data API Key, se configurada, é exclusivamente para consultas oficiais públicas e nunca substitui OAuth.
 8. **Limpador de metadado:** suba um vídeo de terceiro, preencha título, preview, links, timestamps e tags, aplique a limpeza e descarregue a cópia limpa e o manifesto JSON. O original fica preservado e vídeos da aba Novo vídeo não são aceites nesta área.
 9. **Configurações:** confirme que os caminhos e credenciais estão locais e não aparecem no Git.
 10. **Novo vídeo:** confirme que `Pexels/Pixabay` substitui o label antigo, que `Estilo IA` aparece apenas em `full_ia` e que `Apenas Música` exige áudio e guarda `background_mode=none`.

package/README.md

@@ -20,7 +20,7 @@ A primeira versão implementa a camada UI independente com:
 | Upload | YouTube via `youtube-automation-agent` adaptado internamente, OAuth directo de redundância, Upload directo experimental, TikTok, Instagram e Facebook Pages no front end |
 | MCP | Catálogo local opcional de Short Video Maker, AutoVio, OpenMontage e OpenCut, com portas editáveis e activação |
 | Limpador de metadado | Upload isolado de vídeos terceiros, limpeza FFmpeg, edição de título/descrição/tags e manifesto JSON |
-| Configurações | Provedores LLM, TTS/voz, preview de vozes, Suno, materiais, Whisper, FFmpeg, YouTube, Upload directo, TikTok Client ID/Secret e Upload-Post |
+| Configurações | Provedores LLM, TTS/voz, preview de vozes, Suno, materiais, Whisper, FFmpeg, OAuth YouTube, Data API Key opcional, Upload directo, TikTok Client ID/Secret e Upload-Post |
 | Launcher | Execução via `npx`, instalação assistida, diagnóstico e preparação para distribuição |
 
 Os adaptadores do MoneyPrinterTurbo e de publicação nas plataformas são ligados pelas configurações locais e pelos pontos de integração em `integrations/`. A UI não inventa dados quando um serviço externo ou credencial não está disponível.
@@ -104,9 +104,9 @@ thunderbolt
 No Windows PowerShell, se `npx` for bloqueado por `npx.ps1`, use directamente `npx.cmd`:
 
 ```powershell
-npx.cmd --yes @danhachuel/thunderbolt@0.2.22 install
-npx.cmd --yes @danhachuel/thunderbolt@0.2.22 doctor
-npx.cmd --yes @danhachuel/thunderbolt@0.2.22
+npx.cmd --yes @danhachuel/thunderbolt@0.2.23 install
+npx.cmd --yes @danhachuel/thunderbolt@0.2.23 doctor
+npx.cmd --yes @danhachuel/thunderbolt@0.2.23
 ```
 
 Como alternativa, pode permitir scripts para o seu utilizador:
@@ -167,15 +167,15 @@ A descrição segue a composição do workflow de referência: preview, secção
 
 ## Canais YouTube
 
-A aba **Canais** está dividida em dois fluxos independentes. Em **Importar do YouTube**, o método padrão **Página pública — sem API Key** consulta a página pública do canal e preenche nome, ID, handle, URL, descrição e thumbnail quando esses dados estão disponíveis. A opção **YouTube Data API — API Key opcional** pode ser escolhida para métricas oficiais quando `youtube_api_key` estiver configurada em **Configurações** ou em `YOUTUBE_API_KEY`.
+A aba **Canais** está dividida em dois fluxos independentes. Em **Importar do YouTube**, o método padrão **Página pública — sem API Key** consulta a página pública do canal e preenche nome, ID, handle, URL, descrição e thumbnail quando esses dados estão disponíveis. A opção **YouTube Data API — API Key opcional** pode ser escolhida para métricas oficiais quando uma **YouTube Data API Key própria** estiver configurada em **Configurações** ou em `YOUTUBE_API_KEY`; essa chave é distinta do OAuth Client ID e Client Secret.
 
-Em **Cadastro manual**, nenhum pedido ao YouTube é feito e não existe qualquer dependência de API Key. O utilizador pode preencher nome, URL, handle, descrição, métricas, thumbnail, idioma, estilo, Blueprint padrão, voz padrão, `DELEGATED_SESSION_ID` e configuração de Automação. A importação pública nunca grava automaticamente: os dados aparecem num formulário de revisão antes de guardar. Cada cartão de canal tem **Activo** e, logo abaixo, **Apagar canal**, com confirmação; tarefas e artefactos não são apagados.
+Em **Cadastro manual**, nenhum pedido ao YouTube é feito e não existe qualquer dependência de API Key. O utilizador pode preencher nome, URL, handle, descrição, métricas, thumbnail, idioma, estilo, Blueprint padrão, voz padrão, `DELEGATED_SESSION_ID` e configuração de Automação. A importação pública nunca grava automaticamente: os dados aparecem num formulário de revisão antes de guardar. A resolução pública aceita URLs `/channel/UC...`, handles e subpáginas; quando existe um ID mas o HTML não traz todos os dados, tenta o feed RSS público. Se o YouTube responder que o canal não existe ou não fornecer metadados, a UI mostra uma mensagem clara e não mantém o formulário de uma pesquisa anterior. Cada cartão de canal tem **Activo** e, logo abaixo, **Apagar canal**, com confirmação; tarefas e artefactos não são apagados.
 
 ## Upload YouTube
 
 O Upload usa como caminho **principal** a lógica do `PublishingSchedulingAgent` do [youtube-automation-agent](https://github.com/darkzOGx/youtube-automation-agent), adaptada para Python e executada dentro do processo Streamlit do Thunderbolt. Não é necessário instalar ou iniciar um segundo servidor Node. O fluxo valida o MP4 real, constrói `snippet/status`, faz upload resumível e tenta enviar thumbnail e legendas.
 
-Na aba **Upload**, configure primeiro o **YouTube OAuth Client ID** e o **YouTube OAuth Client Secret** em **Configurações**. Em seguida, use **Autorizar agente YouTube**. O navegador local abrirá a autorização Google e o token será guardado apenas em `storage/state/youtube_agent_tokens.json`. Se a publicação principal falhar, o Thunderbolt tenta automaticamente o **OAuth directo de redundância**, usando o token local compatível; a Data API Key nunca é usada para publicar.
+Na aba **Upload**, configure primeiro apenas o **YouTube OAuth Client ID** e o **YouTube OAuth Client Secret** em **Configurações**. Em seguida, use **Autorizar agente YouTube**. O navegador local abrirá a autorização Google e o token será guardado apenas em `storage/state/youtube_agent_tokens.json`. Se a publicação principal falhar, o Thunderbolt tenta automaticamente o **OAuth directo de redundância**, usando o token local compatível; a Data API Key nunca é usada para autorizar ou publicar.
 
 Use **Autorizar fallback OAuth** apenas se precisar de uma autorização separada para o caminho de redundância. Os resultados guardam no histórico local qual mecanismo foi utilizado e as tentativas realizadas, sem guardar segredos.
 
@@ -203,7 +203,7 @@ A mesma aba permite **Guardar skill localmente**, copiando `moneyprinterturbo-vi
 
 A subaba **Vídeos**, dentro de **Novo vídeo**, mostra o backlog e permite iniciar/parar tarefas; deixou de existir como botão principal na barra lateral.
 
-A aba **Configurações** contém apenas o TikTok Client ID e o TikTok Client Secret.
+A aba **Configurações** contém apenas o TikTok Client ID e o TikTok Client Secret para TikTok. Para YouTube, o bloco principal pede o OAuth Client ID e Client Secret; a Data API Key, se usada, fica numa área opcional separada. Client ID + Client Secret não formam uma Data API Key nem um token OAuth.
  Redirect URI, scopes, autorização OAuth e tokens são geridos no TikTok for Developers Playground. O adaptador rejeita o upload quando faltam credenciais ou OAuth, em vez de indicar sucesso falso.
 
 ## Segurança

package/app/main.py

@@ -335,7 +335,7 @@ def render_channels():
                 st.rerun()
         if st.session_state.get("yt_message"):
             (st.success if st.session_state.get("yt_ok") else st.warning)(st.session_state["yt_message"])
-        imported = st.session_state.get("yt_import", {})
+        imported = st.session_state.get("yt_import", {}) if st.session_state.get("yt_ok") else {}
         blueprint_items = blueprint_catalog()
         blueprint_ids = [item[0] for item in blueprint_items]
         blueprint_labels = {item[0]: item[1] for item in blueprint_items}
@@ -818,15 +818,16 @@ def render_settings():
         st.subheader("Execução local")
         port = st.number_input("Porta Streamlit", 1, 65535, int(settings.get("port", 3030)))
         moneyprinter_path = st.text_input("Pasta do motor de vídeo", settings.get("moneyprinter_path", ""), key="settings_moneyprinter_path")
-        st.markdown("**YouTube — API pública e OAuth 2.0**")
-        st.caption("A Data API Key consulta canais e estatísticas públicas. O Client ID e o Client Secret são credenciais OAuth 2.0 separadas, usadas para autorizar operações na conta, como upload.")
-        youtube_cols = st.columns(3)
+        st.markdown("**YouTube — OAuth 2.0 e consulta pública**")
+        st.caption("Para autorizar uploads, preencha apenas o YouTube OAuth Client ID e o YouTube OAuth Client Secret. Depois, autorize o agente na aba Upload. Estes dados identificam a aplicação OAuth; não são uma Data API Key nem um token de acesso.")
+        youtube_cols = st.columns(2)
         with youtube_cols[0]:
-            youtube_api_key = text_setting("YouTube Data API Key", "youtube_api_key", secret=True, help_text="Chave criada em Google Cloud > APIs e serviços > Credenciais > Chave de API.")
+            youtube_client_id = text_setting("YouTube OAuth Client ID", "youtube_client_id", help_text="Client ID do OAuth 2.0 criado no Google Cloud. É usado para iniciar a autorização da conta YouTube.")
         with youtube_cols[1]:
-            youtube_client_id = text_setting("YouTube OAuth Client ID", "youtube_client_id", help_text="Client ID do OAuth 2.0 criado no Google Cloud.")
-        with youtube_cols[2]:
-            youtube_client_secret = text_setting("YouTube OAuth Client Secret", "youtube_client_secret", secret=True, help_text="Client Secret do mesmo cliente OAuth 2.0.")
+            youtube_client_secret = text_setting("YouTube OAuth Client Secret", "youtube_client_secret", secret=True, help_text="Client Secret do mesmo cliente OAuth 2.0. Não é uma API Key.")
+        with st.expander("Consulta oficial de métricas — opcional"):
+            st.caption("A YouTube Data API Key é uma credencial Google Cloud separada do OAuth. Só é necessária se escolher o método YouTube Data API para consultar métricas oficiais. Não é necessária para Página pública — sem API Key, para autorizar OAuth ou para fazer upload.")
+            youtube_api_key = text_setting("YouTube Data API Key (opcional)", "youtube_api_key", secret=True, help_text="Credencial separada, criada em Google Cloud > APIs e serviços > Credenciais > Chave de API. Não cole aqui o Client ID nem o Client Secret.")
 
         with st.expander("Upload directo — sessão YouTube Frontend API"):
             st.caption("Campos usados apenas pelo método Upload directo. Não são necessários para o youtube-automation-agent nem para a Data API pública.")

package/integrations/platforms.py

@@ -4,6 +4,7 @@ import json
 import os
 import re
 import xml.etree.ElementTree as ET
+from html import unescape
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
@@ -121,6 +122,69 @@ def _meta_content(document: str, *names: str) -> str:
     return ""
 
 
+def _channel_id_from_source(source: str) -> str:
+    """Extract a channel ID from a direct channel URL or a raw UC... value."""
+    value = (source or "").strip()
+    match = re.search(r"(?<![A-Za-z0-9_-])(UC[A-Za-z0-9_-]{3,})(?![A-Za-z0-9_-])", value)
+    return match.group(1) if match else ""
+
+
+def _canonical_link(document: str) -> str:
+    patterns = [
+        r'<link[^>]+rel=["\']canonical["\'][^>]+href=["\']([^"\']+)["\']',
+        r'<link[^>]+href=["\']([^"\']+)["\'][^>]+rel=["\']canonical["\']',
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, document, flags=re.IGNORECASE)
+        if match:
+            return unescape(match.group(1)).strip()
+    return ""
+
+
+def _jsonld_channel_data(document: str) -> dict[str, Any]:
+    """Read channel-like fields from JSON-LD without requiring a fixed YouTube renderer."""
+    for raw in re.findall(r'<script[^>]+type=["\']application/ld\+json["\'][^>]*>(.*?)</script>', document, flags=re.IGNORECASE | re.DOTALL):
+        try:
+            payload = json.loads(unescape(raw.strip()))
+        except (TypeError, ValueError, json.JSONDecodeError):
+            continue
+        candidates = payload if isinstance(payload, list) else [payload]
+        for candidate in candidates:
+            if not isinstance(candidate, dict):
+                continue
+            candidate_type = candidate.get("@type", "")
+            if candidate_type in {"Person", "Organization", "Brand", "ProfilePage"} or any(key in candidate for key in ("channelId", "identifier", "sameAs")):
+                image = candidate.get("image", "")
+                if isinstance(image, dict):
+                    image = image.get("url", "")
+                identifier = candidate.get("channelId") or candidate.get("identifier", "")
+                if isinstance(identifier, dict):
+                    identifier = identifier.get("value", "")
+                same_as = candidate.get("sameAs", [])
+                if isinstance(same_as, str):
+                    same_as = [same_as]
+                return {
+                    "name": _text_from_node(candidate.get("name")),
+                    "description": _text_from_node(candidate.get("description")),
+                    "url": _text_from_node(candidate.get("url")),
+                    "thumbnail_url": _text_from_node(image),
+                    "youtube_id": _text_from_node(identifier),
+                    "same_as": same_as if isinstance(same_as, list) else [],
+                }
+    return {}
+
+
+def _public_error_from_initial_data(initial_data: dict[str, Any]) -> str:
+    alerts = _find_first_key(initial_data, "alerts")
+    if not isinstance(alerts, list):
+        return ""
+    for alert in alerts:
+        text = _text_from_node(_find_first_key(alert, "text"))
+        if text:
+            return text
+    return ""
+
+
 def _public_page_candidates(source: str) -> list[str]:
     source = source.strip()
     if source.startswith(("http://", "https://")):
@@ -197,73 +261,134 @@ class YouTubeAdapter:
         source = (value or "").strip()
         if not source:
             return IntegrationResult(False, "Introduza o nome, handle, URL ou ID do canal.", {})
+        if source.startswith(("http://", "https://")):
+            host = (urlparse(source).hostname or "").lower()
+            if host != "youtube.com" and not host.endswith(".youtube.com"):
+                return IntegrationResult(False, "O link deve pertencer ao YouTube. Use um URL youtube.com, um handle @nome ou um ID UC... .", {"url": source, "public_lookup": True})
         headers = {
             "User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/124 Safari/537.36",
             "Accept-Language": "pt-BR,pt;q=0.9,en;q=0.8",
             "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
         }
+        direct_id = _channel_id_from_source(source)
+        feed_cache: dict[str, dict[str, Any]] = {}
+
+        def feed_for(channel_id: str) -> dict[str, Any]:
+            if channel_id and channel_id not in feed_cache:
+                feed_cache[channel_id] = _public_feed_data(channel_id, headers)
+            return feed_cache.get(channel_id, {})
+
+        if direct_id:
+            direct_feed = feed_for(direct_id)
+            if direct_feed.get("name"):
+                feed_name = str(direct_feed.get("name", ""))
+            else:
+                feed_name = ""
+        else:
+            feed_name = ""
         last_url = source
         last_error = ""
         for page_url in _public_page_candidates(source):
             last_url = page_url
             try:
-                response = requests.get(page_url, headers=headers, timeout=20)
+                response = requests.get(page_url, headers=headers, timeout=20, allow_redirects=True)
                 response.raise_for_status()
             except requests.RequestException as exc:
-                last_error = str(exc)
+                last_error = f"Falha HTTP: {exc}"
                 continue
             document = response.text or ""
             initial_data = _extract_json_assignment(document, "ytInitialData") or {}
+            public_error = _public_error_from_initial_data(initial_data)
             metadata = _find_first_key(initial_data, "channelMetadataRenderer") or {}
             header = _find_first_key(initial_data, "pageHeaderViewModel") or {}
-            canonical_url = _meta_content(document, "og:url", "twitter:url") or page_url.split("?", 1)[0].rstrip("/")
+            jsonld = _jsonld_channel_data(document)
+            response_url = str(getattr(response, "url", "") or "")
+            canonical_url = (
+                _meta_content(document, "og:url", "twitter:url")
+                or _canonical_link(document)
+                or (response_url if "youtube.com" in response_url else "")
+                or jsonld.get("url", "")
+                or page_url.split("?", 1)[0].rstrip("/")
+            )
             owner_urls = metadata.get("ownerUrls", []) if isinstance(metadata, dict) else []
             if owner_urls:
                 canonical_url = str(owner_urls[0])
-            canonical_url = canonical_url.replace("http://", "https://").removesuffix("/about")
+            canonical_url = canonical_url.replace("http://", "https://").split("?", 1)[0].rstrip("/")
             youtube_id = str(metadata.get("externalId", "")) if isinstance(metadata, dict) else ""
-            if not youtube_id:
-                youtube_id = _channel_id_from_document(document, canonical_url)
-            feed = _public_feed_data(youtube_id, headers)
-            title = _text_from_node(metadata.get("title")) if isinstance(metadata, dict) else ""
-            if not title and isinstance(header, dict):
-                title = _text_from_node(header.get("title"))
-                if not title:
-                    title = _text_from_node(_find_first_key(header, "dynamicTextViewModel"))
-            if not title:
-                title = _meta_content(document, "og:title", "twitter:title") or feed.get("name", "")
-            description = _text_from_node(metadata.get("description")) if isinstance(metadata, dict) else ""
-            description = description or _meta_content(document, "description", "og:description")
-            thumbnail_url = _thumbnail_from_metadata(metadata) or _meta_content(document, "og:image", "twitter:image")
-            handle_match = re.search(r"/@([^/?]+)", canonical_url)
-            handle = f"@{handle_match.group(1)}" if handle_match else ""
-            if not handle:
-                handle_match = re.search(r"/@([^/?]+)", document)
-                handle = f"@{handle_match.group(1)}" if handle_match else ""
+            youtube_id = youtube_id or _channel_id_from_source(canonical_url) or _channel_id_from_document(document, canonical_url)
+            youtube_id = youtube_id or _channel_id_from_source(jsonld.get("youtube_id", "")) or direct_id
+            feed = feed_for(youtube_id)
+            page_title = _text_from_node(metadata.get("title")) if isinstance(metadata, dict) else ""
+            if not page_title and isinstance(header, dict):
+                page_title = _text_from_node(header.get("title"))
+                if not page_title:
+                    page_title = _text_from_node(_find_first_key(header, "dynamicTextViewModel"))
+            page_title = page_title or jsonld.get("name", "") or _meta_content(document, "og:title", "twitter:title")
+            title = page_title or feed.get("name", "") or feed_name
+            page_description = _text_from_node(metadata.get("description")) if isinstance(metadata, dict) else ""
+            page_description = page_description or jsonld.get("description", "") or _meta_content(document, "description", "og:description")
+            description = page_description
+            page_thumbnail = _thumbnail_from_metadata(metadata) or jsonld.get("thumbnail_url", "") or _meta_content(document, "og:image", "twitter:image")
+            thumbnail_url = page_thumbnail
+            handle = ""
+            for handle_source in (canonical_url, *jsonld.get("same_as", []), document):
+                handle_match = re.search(r"/@([^/?\"'\\]+)", str(handle_source))
+                if handle_match:
+                    handle = f"@{handle_match.group(1)}"
+                    break
             subscriber_value = _find_first_key(initial_data, "subscriberCountText")
             video_value = _find_first_key(initial_data, "videoCountText")
             data = {
                 "youtube_id": youtube_id or feed.get("youtube_id", ""),
                 "name": title,
                 "handle": handle,
-                "url": canonical_url,
+                "url": canonical_url or (f"https://www.youtube.com/channel/{youtube_id}" if youtube_id else source),
                 "description": description,
                 "thumbnail_url": thumbnail_url,
                 "subscriber_count": _parse_public_count(subscriber_value),
                 "video_count": _parse_public_count(video_value) or feed.get("video_count"),
                 "view_count": None,
-                "metrics_source": "youtube_public_page",
+                "metrics_source": "youtube_public_page" if (page_title or page_description or page_thumbnail) else ("youtube_public_feed" if feed.get("name") else "youtube_public_page"),
                 "public_lookup": True,
             }
-            if data["name"] or data["youtube_id"] or data["thumbnail_url"]:
+            if public_error and any(marker in public_error.lower() for marker in ("não existe", "nao existe", "não encontrado", "nao encontrado", "not found", "does not exist")):
+                data["public_error"] = public_error
+                return IntegrationResult(False, f"O YouTube indicou que este canal não existe ou não está disponível: {public_error}", data)
+            has_metadata = bool(
+                data["name"]
+                or data["handle"]
+                or data["description"]
+                or data["thumbnail_url"]
+                or data["subscriber_count"] is not None
+                or data["video_count"] is not None
+            )
+            if has_metadata:
                 return IntegrationResult(True, "Canal encontrado publicamente no YouTube, sem API Key. Reveja os dados antes de guardar.", data)
-            last_error = "A página respondeu sem metadados reconhecíveis."
-        return IntegrationResult(False, f"Não foi possível obter dados públicos do YouTube sem API Key. Confirme o URL/handle ou use Cadastro manual. {last_error}".strip(), {"url": last_url, "public_lookup": True})
+            last_error = "O YouTube respondeu, mas não forneceu metadados públicos reconhecíveis para este canal."
+        if direct_id and feed_name:
+            data = {
+                "youtube_id": direct_id,
+                "name": feed_name,
+                "handle": "",
+                "url": f"https://www.youtube.com/channel/{direct_id}",
+                "description": "",
+                "thumbnail_url": "",
+                "subscriber_count": None,
+                "video_count": feed_cache.get(direct_id, {}).get("video_count"),
+                "view_count": None,
+                "metrics_source": "youtube_public_feed",
+                "public_lookup": True,
+            }
+            return IntegrationResult(True, "Canal encontrado no feed público do YouTube, sem API Key. Reveja os dados antes de guardar.", data)
+        data = {"url": last_url, "public_lookup": True}
+        if direct_id:
+            data["youtube_id"] = direct_id
+        return IntegrationResult(False, f"Não foi possível obter dados públicos do YouTube sem API Key. {last_error or 'Confirme o URL/handle ou use Cadastro manual.'}".strip(), data)
 
     def fetch_channel(self, value: str) -> IntegrationResult:
         ref = self.extract_channel_ref(value)
         if not self.api_key:
-            return IntegrationResult(False, "YOUTUBE_API_KEY não configurada; preencha os dados manualmente.", {"url": value, "handle": ref})
+            return IntegrationResult(False, "A YouTube Data API Key própria não está configurada. Escolha Página pública — sem API Key ou adicione uma chave separada em Configurações; o OAuth Client ID e Secret não substituem esta credencial.", {"url": value, "handle": ref, "status": "api_key_not_configured"})
         try:
             params = {"part": "snippet,statistics", "key": self.api_key}
             if ref.startswith("UC"):

package/package.json

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