@danhachuel/thunderbolt 0.5.88 → 0.5.90

package/app/main.py

@@ -8410,6 +8410,22 @@ def render_youtube_frontend_upload_tutorial():
     st.markdown(tutorial_content, unsafe_allow_html=False)
 
 
+def render_youtube_data_api_key_tutorial():
+    """Render the YouTube Data API key guide for public data workflows."""
+    tutorial_path = ROOT / "seed" / "references" / "tutorial-youtube-data-api-key.md"
+    st.title("Tutorial YouTube Data API Key (Public Data)")
+    st.caption("Guia para criar e configurar uma YouTube Data API Key para consultas de dados públicos.")
+    st.markdown("[Abrir documento fonte no Google Drive](https://drive.google.com/file/d/1ypzaR1v8khBxyUQmZ12ZAY0pGTD49mqt/view)")
+    try:
+        tutorial_content = tutorial_path.read_text(encoding="utf-8").strip()
+    except OSError:
+        tutorial_content = ""
+    if not tutorial_content:
+        st.error("O conteúdo local do tutorial não está disponível. Consulte o documento fonte no Google Drive.")
+        return
+    st.markdown(tutorial_content, unsafe_allow_html=False)
+
+
 def render_mcp():
     st.title("MCP")
     st.caption("Clientes externos, servidor MCP do Thunderbolt e a skill local ficam separados para evitar confundir funções diferentes.")
@@ -8812,6 +8828,7 @@ def main():
         ("Tutorial Apify", ":material/menu_book:", "Tutorial Apify"),
         ("Tutorial YouTube Video-Upload Frontend", ":material/video_library:", "Tutorial YouTube Video-Upload Frontend"),
         ("Tutorial OAuth do Google", ":material/key:", "Tutorial OAuth do Google"),
+        ("Tutorial YouTube Data API Key (Public Data)", ":material/vpn_key:", "Tutorial YouTube Data API Key (Public Data)"),
     ]
     settings_items = [
         ("MCP", ":material/hub:", "MCP"),
@@ -8867,7 +8884,7 @@ def main():
         "AI Influencers": "/ai-influencers", "Personagens": "/ai-influencers/personagens", "Geração de Conteúdo IA": "/ai-influencers/geracao-conteudo", "Motion Control": "/ai-influencers/motion-control", "UGC Products": "/ai-influencers/ugc-products", "Redes Sociais": "/ai-influencers/redes-sociais",
         "Edição": "/edicao", "Limpador de Metadados": "/edicao/limpador-metadados", "Cortes": "/edicao/cortes", "Editor Python": "/edicao/editor-python", "Download Mídia": "/edicao/download-midia",
         "Growth": "/growth", "Analista Growth Youtube": "/growth/youtube", "Analista Growth Tiktok": "/growth/tiktok", "Analista Growth Instagram": "/growth/instagram", "Analista Facebook Pages": "/growth/facebook-pages", "Analista Bilibili": "/growth/bilibili",
-        "Documentação": "/documentacao", "Tutorial Meta": "/documentacao/meta", "Tutorial Supabase": "/documentacao/supabase", "Tutorial Kaggle": "/documentacao/kaggle", "Tutorial Apify": "/documentacao/apify", "Tutorial YouTube Video-Upload Frontend": "/documentacao/youtube-video-upload-frontend", "Tutorial OAuth do Google": "/documentacao/oauth-google",
+        "Documentação": "/documentacao", "Tutorial Meta": "/documentacao/meta", "Tutorial Supabase": "/documentacao/supabase", "Tutorial Kaggle": "/documentacao/kaggle", "Tutorial Apify": "/documentacao/apify", "Tutorial YouTube Video-Upload Frontend": "/documentacao/youtube-video-upload-frontend", "Tutorial OAuth do Google": "/documentacao/oauth-google", "Tutorial YouTube Data API Key (Public Data)": "/documentacao/youtube-data-api-key",
         "Configurações": "/configuracoes", "MCP": "/configuracoes/mcp", "Notificações": "/configuracoes/notificacoes", "Logs": "/configuracoes/logs", "Configuração API": "/configuracoes/api",
     }
 
@@ -8989,6 +9006,7 @@ def main():
         "Tutorial Supabase": render_supabase_tutorial,
         "Tutorial YouTube Video-Upload Frontend": render_youtube_frontend_upload_tutorial,
         "Tutorial OAuth do Google": render_google_oauth_tutorial,
+        "Tutorial YouTube Data API Key (Public Data)": render_youtube_data_api_key_tutorial,
         "Configurações": lambda: render_edit_placeholder("Configurações", "Seleccione uma opção no menu expansível."),
         "MCP": render_mcp,
         "Contas Google": render_google_accounts,

package/integrations/youtube_batch.py

@@ -40,9 +40,9 @@ def _authorization_error_message(email: str, exc: Exception) -> str:
     if "redirect_uri_mismatch" in detail.lower():
         return (
             f"A autorização da conta {email} foi rejeitada pelo Google (redirect_uri_mismatch). "
-            f"Use um cliente OAuth do tipo Desktop app ou adicione exactamente {loopback_redirect_uri()} "
-            "em Google Cloud > APIs e serviços > Credenciais > URIs de redireccionamento autorizados. "
-            "Não use uma URI sem a porta, com localhost diferente ou sem a barra final."
+            "Este fluxo usa um callback local loopback; crie ou seleccione uma credencial OAuth do tipo "
+            "Aplicativo para computador (Desktop app), não Aplicativo da Web. "
+            f"A porta predefinida é {loopback_redirect_uri()} e pode mudar automaticamente se estiver ocupada."
         )
     return f"A autorização da conta {email} falhou: {detail}"
 

package/package.json

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

package/seed/references/tutorial-oauth-google.md

@@ -4,7 +4,7 @@ Este tutorial explica como criar um projecto no Google Cloud, activar a YouTube
 
 ## Pré-requisitos
 
-Antes de começar, certifique-se de que tem uma conta Google, acesso ao [Google Cloud Console](https://console.cloud.google.com/) e o Thunderbolt instalado e em execução localmente. A aplicação em execução é necessária para confirmar a URI de redireccionamento OAuth utilizada pelo projecto.
+Antes de começar, certifique-se de que tem uma conta Google, acesso ao [Google Cloud Console](https://console.cloud.google.com/) e o Thunderbolt instalado e em execução localmente. A aplicação em execução é necessária para concluir o callback OAuth local.
 
 ## Passo 1 — Aceder ao Google Cloud Console
 
@@ -68,30 +68,11 @@ Na página da tela de consentimento OAuth, abra o separador **Público-alvo** e,
 
 ## Passo 6 — Criar as credenciais OAuth
 
-No menu lateral, abra **APIs e Serviços → Credenciais** e clique em **+ Criar credenciais → ID do cliente OAuth**. Em **Tipo de aplicativo**, seleccione **Aplicativo da Web** e atribua um nome, por exemplo, `Thunderbolt Web Client`.
+No menu lateral, abra **APIs e Serviços → Credenciais** e clique em **+ Criar credenciais → ID do cliente OAuth**. Em **Tipo de aplicativo**, seleccione **Aplicativo para computador** (também apresentado como **Desktop app**) e atribua um nome, por exemplo, `Thunderbolt Desktop Client`.
 
-### Origens JavaScript autorizadas
+> **Importante:** o Thunderbolt usa `InstalledAppFlow` com um callback local loopback. Não seleccione **Aplicativo da Web**. Essa credencial exige URIs fixas e causa `Erro 400: redirect_uri_mismatch` neste fluxo.
 
-Clique em **Adicionar URI** e introduza a origem onde o frontend é executado, por exemplo:
-
-```text
-http://localhost:3000
-```
-
-Se existir um ambiente de produção, adicione também a origem HTTPS correspondente, por exemplo `https://seudominio.com`.
-
-### URIs de redireccionamento autorizadas
-
-Esta é a parte mais crítica. Clique em **Adicionar URI** e introduza a URI exacta utilizada pelo Thunderbolt para o callback OAuth. Exemplos de desenvolvimento local:
-
-```text
-http://localhost:3000/api/auth/google/callback
-http://localhost:5173/oauth2callback
-```
-
-> **A URI tem de ser exactamente igual à configurada no código do Thunderbolt.** Uma barra final diferente, o uso de `http` em vez de `https` ou uma porta diferente causa o erro `redirect_uri_mismatch`.
-
-Se não souber qual é a URI utilizada, consulte a configuração ou o ficheiro de ambiente do Thunderbolt e confirme também os logs da aplicação.
+Uma credencial **Desktop app** não precisa de **Origens JavaScript autorizadas** nem de adicionar manualmente uma URI de redireccionamento. O Thunderbolt inicia o callback local em `http://127.0.0.1:8765/`; se essa porta estiver ocupada, escolhe automaticamente outra porta loopback livre.
 
 Clique em **Criar**. Na janela apresentada, copie o **ID do cliente (Client ID)** e a **Chave secreta do cliente (Client Secret)** e guarde-os num local seguro.
 
@@ -99,34 +80,26 @@ Clique em **Criar**. Na janela apresentada, copie o **ID do cliente (Client ID)*
 
 ## Passo 7 — Configurar o Thunderbolt
 
-O projecto utiliza variáveis de ambiente para as credenciais OAuth. Localize o ficheiro de ambiente do Thunderbolt, normalmente `.env`, `.env.local` ou o ficheiro de configuração equivalente, e adicione:
+Na aba **Configurações → Configuração API → API Keys Upload → Contas Google**, crie ou edite a conta Google e cole o **Client ID** e o **Client Secret** da credencial **Desktop app**. Guarde a conta e clique em **Autorizar/Reautorizar**.
 
-```env
-GOOGLE_CLIENT_ID=seu_client_id_aqui
-GOOGLE_CLIENT_SECRET=sua_client_secret_aqui
-GOOGLE_REDIRECT_URI=http://localhost:3000/api/auth/google/callback
-```
-
-Substitua `seu_client_id_aqui` e `sua_client_secret_aqui` pelos valores copiados no passo anterior. Confirme que `GOOGLE_REDIRECT_URI` é exactamente igual à URI registada no Google Cloud Console.
+Não é necessário configurar `GOOGLE_REDIRECT_URI` nem adicionar uma URI de callback de `localhost` no Google Cloud Console: o callback loopback é criado pelo `InstalledAppFlow` durante a autorização.
 
 ## Passo 8 — Testar a autenticação
 
-Reinicie o servidor do Thunderbolt para carregar as novas variáveis de ambiente. Abra a interface e tente iniciar sessão com o Google.
+Abra a interface do Thunderbolt e tente autorizar a conta Google.
 
 O fluxo esperado é:
 
 1. O Google apresenta a tela de consentimento com o nome do app e os escopos solicitados.
 2. O utilizador autoriza o acesso.
-3. O Google redirecciona para a URI de callback do Thunderbolt.
-4. A autenticação é concluída com sucesso na aplicação.
+3. O Google redirecciona para o callback local do Thunderbolt.
+4. A autenticação é concluída e o token é guardado no storage local da conta.
 
 ## Solução de problemas
 
 ### Erro `redirect_uri_mismatch`
 
-Este erro significa que a URI enviada pelo Thunderbolt não corresponde exactamente à URI registada no Google Cloud Console.
-
-Verifique a URI utilizada nos logs ou no código do Thunderbolt. Depois, abra **Credenciais**, seleccione o ID do cliente e adicione a URI exacta em **URIs de redireccionamento autorizadas**. Aguarde um a dois minutos para a configuração se propagar, limpe o cache do navegador e tente novamente.
+Este erro ocorre normalmente quando foi criada uma credencial **Aplicativo da Web** para o fluxo local. Abra **APIs e Serviços → Credenciais**, crie uma nova credencial **ID do cliente OAuth → Aplicativo para computador (Desktop app)**, substitua o Client ID e o Client Secret na conta Google do Thunderbolt e tente novamente. Não tente corrigir este fluxo adicionando uma URI de `localhost` numa credencial Web.
 
 ### Erro `invalid_request` ou `access_denied`
 
@@ -134,7 +107,7 @@ Confirme se o seu e-mail foi adicionado como utilizador de teste no passo 5. Ver
 
 ### Mensagem “Acesso bloqueado: solicitação inválida”
 
-Na maioria dos casos, esta mensagem está relacionada com uma URI de redireccionamento incorrecta. Reveja cuidadosamente os passos 6 e 7, verificando protocolo, domínio, porta, caminho e barras finais.
+Confirme primeiro que a credencial é **Aplicativo para computador (Desktop app)** e não **Aplicativo da Web**. Depois confirme que a conta Google foi adicionada como utilizador de teste e que a YouTube Data API v3 está activa.
 
 ## Escopos importantes para o YouTube
 

package/seed/references/tutorial-youtube-data-api-key.md

@@ -0,0 +1,96 @@
+# Tutorial YouTube Data API Key (Public Data)
+
+Este tutorial explica como criar uma **YouTube Data API Key** no Google Cloud e configurá-la no Thunderbolt para consultar dados públicos do YouTube, como vídeos, canais e estatísticas públicas.
+
+> **Fonte:** [Tutorial YouTube Data API Key (Public Data) no Google Drive](https://drive.google.com/file/d/1ypzaR1v8khBxyUQmZ12ZAY0pGTD49mqt/view)
+
+## Quando usar uma API Key
+
+Uma API Key é suficiente para operações com dados públicos, como pesquisar vídeos, consultar canais públicos e obter estatísticas públicas. Ela **não concede acesso a dados privados** da conta nem substitui o OAuth 2.0 para playlists privadas, inscrições privadas ou uploads.
+
+## Passo 1 — Aceder ao Google Cloud Console
+
+Abra o [Google Cloud Console](https://console.cloud.google.com/) e faça login com a conta Google que irá gerir a credencial.
+
+## Passo 2 — Criar ou seleccionar um projecto
+
+No topo da página, abra o selector de projectos junto ao logótipo do Google Cloud. Seleccione **Novo projecto**, dê-lhe um nome, como `Thunderbolt YouTube`, mantenha a organização e a localização predefinidas quando aplicável e clique em **Criar**. Depois de alguns instantes, seleccione o projecto criado.
+
+## Passo 3 — Activar a YouTube Data API v3
+
+No menu lateral, abra **APIs e Serviços → Biblioteca**. Pesquise por **YouTube Data API v3**, abra o resultado correspondente e clique em **Activar**.
+
+> **Importante:** a API não é activada automaticamente em projectos novos. Sem este passo, a API Key não poderá fazer chamadas à YouTube Data API v3.
+
+## Passo 4 — Criar a credencial API Key
+
+No menu lateral, abra **APIs e Serviços → Credenciais** e clique em **+ Criar credenciais → Chave de API**. O Google irá gerar a chave e apresentá-la numa janela. Copie-a e guarde-a num local seguro; depois clique em **Concluído**.
+
+No Thunderbolt, a chave deve ser configurada em **Configurações → Configuração API → API Keys Upload → API Innertube**, no campo `INNERTUBE_API_KEY`. Esta é a chave global usada pelos fluxos que consultam dados públicos do YouTube.
+
+## Passo 5 — Restringir a chave (recomendado)
+
+A restrição reduz o impacto de uma eventual exposição da chave. Na lista de credenciais do Google Cloud, clique no ícone de edição junto à chave criada e, em **Restrições de API**, seleccione **Restringir chave**. Em **Seleccionar APIs**, marque **YouTube Data API v3** e clique em **Guardar**.
+
+Se a chave for usada apenas por uma aplicação local, reveja também as restrições de aplicação disponíveis no Google Cloud e escolha uma configuração compatível com o ambiente onde o Thunderbolt é executado.
+
+## Passo 6 — Configurar e testar no Thunderbolt
+
+1. Abra **Configurações**.
+2. Abra **Configuração API**.
+3. Seleccione **API Keys Upload**.
+4. Abra **API Innertube**.
+5. Cole a YouTube Data API Key no campo `INNERTUBE_API_KEY`.
+6. Guarde a configuração.
+7. Execute uma funcionalidade que consulte dados públicos, como pesquisa ou importação de um canal público.
+
+A API Key não deve ser colocada nos campos Client ID ou Client Secret das **Contas Google**. Esses campos pertencem ao fluxo OAuth 2.0, que é independente da API Key.
+
+## O que é possível fazer com a chave
+
+Com a YouTube Data API v3 e uma API Key, o Thunderbolt pode consultar, conforme o fluxo utilizado:
+
+- Vídeos e respectivos metadados públicos.
+- Canais e informações públicas do canal.
+- Estatísticas públicas de vídeos e canais.
+- Pesquisas de conteúdos públicos.
+- Playlists públicas.
+
+Para criar playlists, fazer uploads, consultar dados privados ou agir em nome da conta Google, utilize o tutorial **OAuth do Google** e autorize a conta através de uma credencial **Aplicativo para computador (Desktop app)**.
+
+## Cota diária
+
+A YouTube Data API v3 aplica uma quota diária por projecto. Cada operação consome unidades de quota diferentes; operações de pesquisa costumam consumir mais unidades do que consultas simples. A quota predefinida é frequentemente apresentada pelo Google como aproximadamente **10.000 unidades por dia**, mas o valor efectivo e as regras podem variar por projecto.
+
+Consulte o consumo em **APIs e Serviços → YouTube Data API v3 → Quotas** no Google Cloud Console. Evite chamadas repetidas desnecessárias e mantenha a chave restrita à API necessária.
+
+## Segurança e manutenção
+
+Nunca publique a API Key em repositórios, capturas de ecrã, mensagens ou páginas públicas. Se a chave for exposta, abra a lista de credenciais no Google Cloud, revogue ou elimine a chave comprometida e crie uma nova. Depois, actualize o valor guardado no Thunderbolt.
+
+A API Key não substitui o Client Secret OAuth e não deve ser partilhada com outras pessoas. Use uma chave separada para cada ambiente quando isso facilitar a auditoria e a revogação.
+
+## Solução de problemas
+
+### A API devolve `SERVICE_DISABLED`
+
+Confirme que o projecto seleccionado é o mesmo projecto associado à API Key e que **YouTube Data API v3** está activa em **APIs e Serviços → Biblioteca**.
+
+### A API devolve `API_KEY_INVALID`
+
+Confirme que copiou a chave completa, sem espaços ou aspas adicionais, e que o valor foi guardado no campo `INNERTUBE_API_KEY` correcto.
+
+### A API devolve `quotaExceeded`
+
+Consulte a quota do projecto no Google Cloud Console, reduza pesquisas repetidas e aguarde a reposição da quota. Se a utilização legítima justificar, consulte as opções de quota apresentadas pelo Google.
+
+### Preciso de dados privados ou uploads
+
+Uma API Key só identifica o projecto e permite chamadas autorizadas para dados públicos. Para dados privados, uploads ou operações em nome de uma conta, configure o OAuth 2.0 através do **Tutorial OAuth do Google**.
+
+## Referências
+
+- [Google Cloud Console](https://console.cloud.google.com/)
+- [YouTube Data API v3](https://developers.google.com/youtube/v3)
+- [Documentação de quotas da YouTube Data API](https://developers.google.com/youtube/v3/determine_quota_cost)
+- [Documento fonte no Google Drive](https://drive.google.com/file/d/1ypzaR1v8khBxyUQmZ12ZAY0pGTD49mqt/view)