@danhachuel/thunderbolt 0.3.33 → 0.3.35

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.89
+> **Versão deste manual:** 0.3.35
 > **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.77 install
+npx.cmd --yes @danhachuel/thunderbolt@0.3.35 install
 ```
 
 Linux/macOS:
 
 ```bash
-npx --yes @danhachuel/thunderbolt@0.2.77 install
+npx --yes @danhachuel/thunderbolt@0.3.35 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.
@@ -196,7 +196,7 @@ O Thunderbolt inclui as dez opções de idioma usadas pelo fluxo MoneyPrinterTur
 
 No topo da área principal, o menu nativo de idioma segue o padrão do MoneyPrinterTurbo e mostra o rótulo **Language** acima do selector. Cada opção apresenta o nome e o código, acompanhados por uma imagem SVG local da bandeira; não depende de emojis nem de siglas da fonte do sistema. A escolha fica guardada como `ui_language` em `storage/state/settings.json` e, quando existe um caminho MoneyPrinterTurbo configurado, é sincronizada com `[ui].language` no `config.toml`. O dashboard inicial, o interior das páginas e as abas da barra lateral usam o mesmo idioma seleccionado. O toolbar do Streamlit não é manipulado: o indicador de execução, **Deploy** e o menu de três pontos permanecem nativos e clicáveis. Na Criação de Vídeos e em Roteiros, o selector **Script Language** mantém o catálogo de vídeo independente, mas guarda o código curto; essa escolha é sincronizada com `[ui].video_language`.
 
-Todas as subabas internas e o conteúdo das páginas também são traduzidos nos dez idiomas. Isso inclui títulos, subtítulos, descrições, labels, placeholders, opções, botões, avisos, mensagens de sucesso/erro, estados vazios, métricas, expanderes e blocos Markdown/HTML. Valores técnicos, IDs, URLs, nomes de ficheiros e dados introduzidos pelo utilizador permanecem inalterados. As subabas internas traduzidas incluem: Blueprints/Brandings, Pesquisa pública/Cadastro manual/Contas cadastradas, Upload/Biblioteca, Importar do YouTube/Canais em lote gmail/Cadastro manual, Criar vídeo/Vídeos, Novo roteiro/letra/Histórico guardado, análise de clusters, edição de cortes, Vídeos/Código Python, as quatro opções de Upload, API Keys/Teste de vozes, Serviços e modelos/Fontes de materiais e Client MCP/Servidor MCP/Skill. A ordem e as chaves internas dos widgets permanecem estáveis.
+Todas as subabas internas e o conteúdo das páginas também são traduzidos nos dez idiomas. Isso inclui títulos, subtítulos, descrições, labels, placeholders, opções, botões, avisos, mensagens de sucesso/erro, estados vazios, métricas, expanderes e blocos Markdown/HTML. Valores técnicos, IDs, URLs, nomes de ficheiros e dados introduzidos pelo utilizador permanecem inalterados. As subabas internas traduzidas incluem: Blueprints/Brandings, Pesquisa pública/Cadastro manual/Contas cadastradas, Upload/Biblioteca, Importar do YouTube/Canais em lote gmail/Cadastro manual, Criar vídeo/Vídeos, Novo roteiro/letra/Histórico guardado, análise de clusters, edição de cortes, Vídeos/Código Python, as quatro opções de Upload, API Keys/Teste de vozes, Serviços e modelos/Fontes de materiais, Client MCP/Servidor MCP/Skill e Notificações Geral/Telegram. A ordem e as chaves internas dos widgets permanecem estáveis.
 
 ### Temas Light e Dark
 
@@ -357,7 +357,7 @@ Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
 
 ## 8. Configuração inicial da UI
 
-Na primeira execução, a barra lateral apresenta **Início**, **Niche Finder**, **Pipeline**, **Pipeline TikTok**, **Automação**, **Edição**, **AI Influencers** e **Configurações**. O menu expansível **Automação** contém a subaba **Automação Youtube**. O menu expansível **Edição** contém **Limpador de Metadados**, **Cortes** e **Editor Python**. O menu expansível **AI Influencers** contém **Personagens**, **Redes Sociais**, **Tutorial Meta** e **Tutorial Supabase**, nessa ordem. O **Tutorial Meta** apresenta o guia de configuração de Instagram e credenciais Meta para automações com n8n. O **Tutorial Supabase** apresenta o guia para criar as tabelas `plans` e `posts` e o bucket `instagram-images`, incluindo a ligação para a fonte original no GitHub; as duas frases promocionais da comunidade foram omitidas. O menu expansível **Niche Finder** contém **Niche Finder Kaggle** e **Niche Finder Apify**. A aba **Niche Finder Kaggle** mantém a análise do dataset Kaggle; **Niche Finder Apify** é uma segunda alternativa independente, com actor, dataset, parâmetros, credencial, execução e resultados próprios. O menu **Pipeline** contém **Criação de Vídeos**, **Criação de Músicas**, **Roteiros** e **Upload**. O menu **Configurações** contém **Canais Youtube**, **Blueprints Youtube**, **MCP**, **Contas Google**, **Configuração API** e **Notificações**. Abra **Configurações > Contas Google** para gerir contas Google/YouTube, cartões, documentos de Upload directo, `sessionInfo` por conta, a `INNERTUBE_API_KEY` global, contas adicionais e a configuração global do YouTube. Abra **Configurações > Configuração API** para configurar as restantes API Keys, providers, modelos, serviços e o **Teste de vozes**. A página **Configurações > Notificações** está reservada para futuros eventos locais. Para YouTube, preencha primeiro o par **OAuth Client ID + OAuth Client Secret** em **Contas Google** se pretende autorizar uploads. A **YouTube Data API Key** é uma credencial Google Cloud diferente e fica em **Contas Google**, apenas para o método oficial de métricas; Client ID + Client Secret não formam uma API Key.
+Na primeira execução, a barra lateral apresenta **Início**, **Niche Finder**, **Pipeline**, **Pipeline TikTok**, **Automação**, **Edição**, **AI Influencers** e **Configurações**. O menu expansível **Automação** contém a subaba **Automação Youtube**. O menu expansível **Edição** contém **Limpador de Metadados**, **Cortes** e **Editor Python**. O menu expansível **AI Influencers** contém **Personagens**, **Redes Sociais**, **Tutorial Meta** e **Tutorial Supabase**, nessa ordem. O **Tutorial Meta** apresenta o guia de configuração de Instagram e credenciais Meta para automações com n8n. O **Tutorial Supabase** apresenta o guia para criar as tabelas `plans` e `posts` e o bucket `instagram-images`, incluindo a ligação para a fonte original no GitHub; as duas frases promocionais da comunidade foram omitidas. O menu expansível **Niche Finder** contém **Niche Finder Kaggle** e **Niche Finder Apify**. A aba **Niche Finder Kaggle** mantém a análise do dataset Kaggle; **Niche Finder Apify** é uma segunda alternativa independente, com actor, dataset, parâmetros, credencial, execução e resultados próprios. O menu **Pipeline** contém **Criação de Vídeos**, **Criação de Músicas**, **Roteiros** e **Upload**. O menu **Configurações** contém **Canais Youtube**, **Blueprints Youtube**, **MCP**, **Contas Google**, **Configuração API** e **Notificações**. Abra **Configurações > Contas Google** para gerir contas Google/YouTube, cartões, documentos de Upload directo, `sessionInfo` por conta, a `INNERTUBE_API_KEY` global, contas adicionais e a configuração global do YouTube. Abra **Configurações > Configuração API** para configurar as restantes API Keys, providers, modelos, serviços e o **Teste de vozes**. A página **Configurações > Notificações** contém as subabas **Geral** e **Telegram**. A subaba Geral mantém o histórico e as preferências dos eventos locais; a subaba Telegram envia esses mesmos eventos para o Chat ID configurado. Para YouTube, preencha primeiro o par **OAuth Client ID + OAuth Client Secret** em **Contas Google** se pretende autorizar uploads. A **YouTube Data API Key** é uma credencial Google Cloud diferente e fica em **Contas Google**, apenas para o método oficial de métricas; Client ID + Client Secret não formam uma API Key.
 
 | Configuração | Finalidade |
 |---|---|
@@ -378,6 +378,16 @@ Na primeira execução, a barra lateral apresenta **Início**, **Niche Finder**,
 | Apify API Token | Token pessoal da Apify, guardado mascarado no storage local e usado apenas pela alternativa Apify |
 | Apify Actor ID | Actor usado pela alternativa Apify, por padrão `streamers~youtube-scraper` |
 | Apify polling/timeout | Intervalo de consulta e limite máximo da execução do actor |
+| Telegram Bot Token | Token criado pelo BotFather, guardado apenas no storage local |
+| Telegram Chat ID | Utilizador, grupo ou canal que receberá as notificações |
+| Telegram Proxy | Proxy HTTP/HTTPS/SOCKS opcional para ambientes sem acesso directo |
+| Telegram timeout | Limite de espera de cada envio, entre 5 e 120 segundos |
+
+### Telegram Gateway
+
+Em **Configurações > Notificações > Telegram**, active **Activar notificações Telegram**, introduza o **Telegram Bot Token** criado pelo BotFather e o **Telegram Chat ID** de destino. O botão **Testar chamada API** executa apenas o método read-only `getMe` para validar o bot; não envia uma mensagem de teste. O proxy é opcional e o suporte SOCKS depende das dependências instaladas pelo `requirements.txt`.
+
+Depois de guardar, cada nova notificação permitida pelas preferências da subaba **Geral** é enviada pela Bot API oficial do Telegram através de `sendMessage`. A notificação continua a ser persistida localmente mesmo que o Telegram esteja indisponível, o Chat ID esteja errado ou a API devolva um erro; a falha externa nunca interrompe a produção, os uploads ou a UI. A integração é apenas outbound: não recebe comandos, não faz polling e não expõe o Bot Token em logs, metadados ou no GitHub.
 
 As credenciais devem ser inseridas apenas na configuração local. A Kaggle API Key pertence exclusivamente à alternativa Kaggle. O Apify API Token pertence exclusivamente à alternativa Apify e não é usado para Kaggle; os resultados e histórico Apify ficam separados em `niche_apify_runs.json`. 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.
 
@@ -448,7 +458,7 @@ Ao abrir a página, o Thunderbolt não prepara dados públicos, não descarrega
 
 Os parâmetros da UI são número de clusters entre 2 e 10, suporte mínimo entre 0,01 e 0,50, país, engagement, intervalo de datas e tags, todos dentro da área principal da aba. O núcleo normaliza os dados, calcula engagement, aplica filtros, faz transformação logarítmica e standardização, executa K-Means e calcula itemsets/regras com FP-Growth. Não são apresentados resultados até ao primeiro clique em **Analisar Nichos**; o mesmo botão aplica alterações posteriores aos filtros. Os resultados são DataFrames de clusters, itemsets frequentes, regras de associação e dados analisados; o gráfico de dispersão é criado nativamente com Plotly.
 
-As dependências adicionais — `scikit-learn`, `mlxtend`, `plotly`, `seaborn`, `matplotlib` e `kagglehub` — são instaladas pelo procedimento normal de `npx`. Em instalações existentes, execute novamente `npx.cmd --yes @danhachuel/thunderbolt@0.2.77 install`; o instalador detecta e reutiliza o que já estiver válido.
+As dependências adicionais — `scikit-learn`, `mlxtend`, `plotly`, `seaborn`, `matplotlib` e `kagglehub` — são instaladas pelo procedimento normal de `npx`. Em instalações existentes, execute novamente `npx.cmd --yes @danhachuel/thunderbolt@0.3.35 install`; o instalador detecta e reutiliza o que já estiver válido.
 
 ### Niche Finder Apify
 

package/README.md

@@ -22,7 +22,7 @@ A primeira versão implementa a camada UI independente com:
 | Edição | Menu expansível abaixo de Automação com Limpador de Metadados, Clip Generator local em Cortes e Editor Python inspirado no PYEdit para vídeos e scripts locais |
 | Upload | YouTube via `youtube-automation-agent` adaptado internamente, fallback ordenado API Oficial → Upload directo → Postiz, upload de MP4 para Postiz via API key/MCP configurável, 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 |
-| Configurações | **Contas Google**, **Configuração API** e **Notificações**; API Keys divididas entre **Serviços e modelos** e **Fontes de materiais**, com várias chaves independentes por fonte, além de contas Google/YouTube por cartão, `INNERTUBE_API_KEY` global para todas as contas, providers, TTS, Nano Banana, Postiz, TikTok e Upload-Post |
+| Configurações | **Contas Google**, **Configuração API** e **Notificações**; Notificações contém as subabas **Geral** e **Telegram Gateway**, com envio das mesmas operações locais para um Chat ID; API Keys divididas entre **Serviços e modelos** e **Fontes de materiais**, com várias chaves independentes por fonte, além de contas Google/YouTube por cartão, `INNERTUBE_API_KEY` global para todas as contas, providers, TTS, Nano Banana, Postiz, TikTok e Upload-Post |
 | Launcher | Execução via `npx`, instalação assistida, diagnóstico e preparação para distribuição |
 
 ## Upload-Post — publicação para múltiplas plataformas
@@ -56,7 +56,7 @@ No topo da área principal da aplicação existe o menu nativo de idioma no padr
 
 A UI suporta os temas **Dark** e **Light** através do menu nativo de três pontos do Streamlit, no local original do toolbar. Não existe um selector Theme adicional dentro da página. A configuração distribuída em `.streamlit/config.toml` define **Dark** como base inicial e o menu nativo continua responsável por alternar entre os modos, seguindo o padrão do [MoneyPrinterTurbo](https://github.com/harry0703/MoneyPrinterTurbo). O CSS próprio do Thunderbolt usa cores semânticas, `currentColor` e `color-mix` para acompanhar o tema activo, sem alterar a posição nem a funcionalidade do toolbar, do botão Deploy e do menu principal.
 
-## Navegação da UI 0.2.89
+## Navegação da UI 0.3.35
 
 A barra lateral mantém os níveis principais, nesta ordem: **Início**, **Niche Finder**, **Pipeline**, **Pipeline TikTok**, **Automação**, **Edição**, **AI Influencers** e **Configurações**. **Pipeline** é expansível e contém **Criação de Vídeos**, **Criação de Músicas**, **Roteiros** e **Upload**. **Automação** também é expansível e contém **Automação Youtube**. **Edição** é expansível e contém **Limpador de Metadados**, **Cortes**, **Editor Python** e **Download Mídia**, nessa ordem. **AI Influencers** é expansível e contém **Personagens**, **Redes Sociais**, **Tutorial Meta** e **Tutorial Supabase**, nessa ordem. **Niche Finder** é expansível e contém **Niche Finder Kaggle** e **Niche Finder Apify**. **Configurações** é expansível e contém **Canais Youtube**, **Blueprints Youtube**, **MCP**, **Contas Google**, **Configuração API** e **Notificações**. O Início reúne o dashboard e as filas do Pipeline, sem botões de acções rápidas.
 
@@ -64,7 +64,7 @@ A subaba **Tutorial Supabase** apresenta o guia de criação das tabelas `plans`
 
 O conteúdo interno das páginas também é localizado, não apenas a navegação: títulos, subtítulos, descrições, labels de campos, placeholders, opções de selectores, botões, avisos, mensagens de sucesso/erro, estados vazios, métricas, expanderes e blocos Markdown/HTML são traduzidos no idioma seleccionado através da camada global de conteúdo. Valores técnicos, chaves de estado, IDs de formulários, nomes de ficheiros, URLs e dados introduzidos pelo utilizador permanecem inalterados.
 
-Todas as subabas internas também são localizadas pelo helper nativo de tabs: **Blueprints/Brandings**, **Pesquisa pública/Cadastro manual/Contas cadastradas**, **Upload/Biblioteca**, **Importar do YouTube/Canais em lote gmail/Cadastro manual**, **Criar vídeo/Vídeos**, **Novo roteiro/letra/Histórico guardado**, as três abas de análise de clusters, as quatro abas de cortes, **Vídeos/Código Python**, as quatro opções de Upload, **API Keys/Teste de vozes**, **Serviços e modelos/Fontes de materiais** e **Client MCP/Servidor MCP/Skill**. As chaves técnicas e a ordem funcional permanecem inalteradas.
+Todas as subabas internas também são localizadas pelo helper nativo de tabs: **Blueprints/Brandings**, **Pesquisa pública/Cadastro manual/Contas cadastradas**, **Upload/Biblioteca**, **Importar do YouTube/Canais em lote gmail/Cadastro manual**, **Criar vídeo/Vídeos**, **Novo roteiro/letra/Histórico guardado**, as três abas de análise de clusters, as quatro abas de cortes, **Vídeos/Código Python**, as quatro opções de Upload, **API Keys/Teste de vozes**, **Serviços e modelos/Fontes de materiais**, **Client MCP/Servidor MCP/Skill** e **Notificações/Geral/Telegram**. As chaves técnicas e a ordem funcional permanecem inalteradas.
 
 Dentro de **Configurações > Contas Google**, a UI contém os cartões expansíveis de contas Google/YouTube, `sessionInfo` por conta, documentos de Upload directo, o formulário **Adicionar outra conta Gmail**, o bloco global de `INNERTUBE_API_KEY` e a configuração global do YouTube (OAuth Client ID, OAuth Client Secret e YouTube Data API Key). A página **Configuração API** contém as restantes credenciais, providers, modelos, serviços, Nano Banana, TikTok e Postiz.
 
@@ -72,7 +72,7 @@ Em **Configuração API > API Keys**, a subaba **Fontes de materiais** segue o p
 
 A subaba **Serviços e modelos** mantém as credenciais de providers e serviços que não são fontes de materiais. A chave `gemini_image_api_key` da Nano Banana continua separada de `gemini_api_key` do LLM textual. `INNERTUBE_API_KEY` permanece exclusivamente em **Configurações > Contas Google**, no bloco de configuração global fora dos cartões, e não é duplicada em API Keys.
 
-A página **AI Influencers > Tutorial Meta** apresenta o guia de configuração de uma conta Instagram profissional e das credenciais Meta para automações com n8n, distribuído localmente em `seed/references/guide-instagram.md` e com ligação para a [fonte original no GitHub](https://github.com/gyoridavid/ai_agents_az/blob/main/episode_8/guide-instagram.md). A página **Configurações > Notificações** mantém um histórico persistente de conclusões e falhas, reconcilia estados escritos por componentes locais e disponibiliza um checkbox independente para cada operação mapeada.
+A página **AI Influencers > Tutorial Meta** apresenta o guia de configuração de uma conta Instagram profissional e das credenciais Meta para automações com n8n, distribuído localmente em `seed/references/guide-instagram.md` e com ligação para a [fonte original no GitHub](https://github.com/gyoridavid/ai_agents_az/blob/main/episode_8/guide-instagram.md). A página **Configurações > Notificações** mantém um histórico persistente de conclusões e falhas, reconcilia estados escritos por componentes locais e disponibiliza um checkbox independente para cada operação mapeada. A subaba **Geral** mantém esse centro local; a subaba **Telegram** permite configurar Bot Token, Chat ID e proxy opcional e envia as mesmas notificações pela Bot API oficial, sem polling ou mensagens recebidas.
 
 A página **Edição > Download Mídia** utiliza a API Python do [yt-dlp](https://github.com/yt-dlp/yt-dlp) para descarregar vídeos e áudio de URLs públicas, com qualidade, contentor, formato de áudio, legendas, metadados, playlists, progresso e histórico local em `storage/downloads/` e `storage/state/media_downloads.json`. Conversão e combinação de streams podem exigir FFmpeg.
 
@@ -193,9 +193,9 @@ thunderbolt
 No Windows PowerShell, se `npx` for bloqueado por `npx.ps1`, use directamente `npx.cmd`:
 
 ```powershell
-npx.cmd --yes @danhachuel/thunderbolt@0.2.77 install
-npx.cmd --yes @danhachuel/thunderbolt@0.2.77 doctor
-npx.cmd --yes @danhachuel/thunderbolt@0.2.77
+npx.cmd --yes @danhachuel/thunderbolt@0.3.35 install
+npx.cmd --yes @danhachuel/thunderbolt@0.3.35 doctor
+npx.cmd --yes @danhachuel/thunderbolt@0.3.35
 ```
 
 Como alternativa, pode permitir scripts para o seu utilizador:
@@ -219,7 +219,7 @@ O menu expansível **Niche Finder** contém duas alternativas independentes. **N
 
 A interface apresenta dentro da aba os parâmetros da busca: número de clusters entre 2 e 10, suporte mínimo entre 0,01 e 0,50, país, categoria de engagement, intervalo de datas e tags. A página permanece sem resultados até o primeiro clique em **Analisar Nichos**; depois, se os parâmetros forem alterados, mostra os resultados anteriores e pede novo clique para aplicar os filtros actuais. O núcleo aplica normalização, filtros, `log1p`, `StandardScaler`, K-Means e FP-Growth. Os resultados aparecem em DataFrames para clusters, itemsets frequentes, regras de associação e dados analisados, acompanhados por uma visualização Plotly nativa e pesquisa de palavras nos clusters.
 
-**Niche Finder Apify** é a segunda alternativa e não usa o dataset, filtros, execução ou resultados Kaggle. Define três palavras-chave, período, limite de resultados, Shorts, duração, idioma de legendas e ordenação; depois de clicar em **Pesquisar no Apify**, inicia o actor `streamers~youtube-scraper`, acompanha o run, carrega o dataset, normaliza vídeos, limpa SRT, calcula VSC Ratio e tenta resumir as transcrições com o provider LLM configurado. Os resultados ficam na sessão própria `niche_apify_results`, o histórico pequeno fica em `storage/state/niche_apify_runs.json` e existem exportações JSON/CSV. Configure o **Apify API Token** em **Configuração API > API Keys > Serviços e modelos**. As dependências adicionais são instaladas pelo fluxo normal do pacote: `requests`, `pandas` e os componentes já existentes da análise. Em instalações existentes, execute novamente `npx.cmd --yes @danhachuel/thunderbolt@0.2.77 install`; o instalador detecta e reutiliza componentes já válidos.
+**Niche Finder Apify** é a segunda alternativa e não usa o dataset, filtros, execução ou resultados Kaggle. Define três palavras-chave, período, limite de resultados, Shorts, duração, idioma de legendas e ordenação; depois de clicar em **Pesquisar no Apify**, inicia o actor `streamers~youtube-scraper`, acompanha o run, carrega o dataset, normaliza vídeos, limpa SRT, calcula VSC Ratio e tenta resumir as transcrições com o provider LLM configurado. Os resultados ficam na sessão própria `niche_apify_results`, o histórico pequeno fica em `storage/state/niche_apify_runs.json` e existem exportações JSON/CSV. Configure o **Apify API Token** em **Configuração API > API Keys > Serviços e modelos**. As dependências adicionais são instaladas pelo fluxo normal do pacote: `requests`, `pandas` e os componentes já existentes da análise. Em instalações existentes, execute novamente `npx.cmd --yes @danhachuel/thunderbolt@0.3.35 install`; o instalador detecta e reutiliza componentes já válidos.
 
 ## Editor Python baseado no PYEdit
 

package/app/main.py

@@ -42,7 +42,7 @@ from hermes_ui.music import list_music_files, materialize_suno_audio, request_su
 from hermes_ui.media_downloader import AUDIO_FORMATS, VIDEO_CONTAINERS, VIDEO_QUALITY_OPTIONS, MediaDownloadError, build_download_options, clear_media_download_history, dependency_status, download_media, list_media_downloads, media_download_file
 from hermes_ui.notifications import clear_notifications, list_notifications, mark_all_notifications_read, mark_notification_read, notification_event_catalog, notification_preferences, record_notification, reconcile_persisted_notifications, save_notification_preferences, unread_notification_count
 from hermes_ui.languages import LANGUAGE_CODES, VIDEO_LANGUAGE_CODES, LANGUAGE_FLAG_DATA_URIS, language_code, language_label, ui_language_menu_label, ui_text, video_language_label, video_language_options
-from hermes_ui.api_key_tests import test_apify_credentials, test_kaggle_credentials, test_material_source_credentials, test_nano_banana_credentials, test_postiz_credentials, test_tiktok_credentials, test_upload_post_credentials, test_voice_provider
+from hermes_ui.api_key_tests import test_apify_credentials, test_kaggle_credentials, test_material_source_credentials, test_nano_banana_credentials, test_postiz_credentials, test_telegram_credentials, test_tiktok_credentials, test_upload_post_credentials, test_voice_provider
 from hermes_ui.tutorials import tutorial_body, tutorial_caption, tutorial_title
 
 from hermes_ui.script_documents import list_script_documents, read_script_document, save_script_document, script_storage_path
@@ -4955,93 +4955,166 @@ def render_settings():
             st.warning("A amostra de voz anterior não é um ficheiro de áudio legível e foi removida do estado local. Teste a voz novamente.")
 
 
+def _render_telegram_notification_settings() -> None:
+    """Render Telegram outbound notification settings and a safe diagnostics action."""
+    settings = read_json("settings.json", {})
+    if not isinstance(settings, dict):
+        settings = {}
+    st.subheader("Telegram Gateway")
+    st.caption("Envie para o Telegram as mesmas notificações que aparecem na subaba Geral. A integração usa a Bot API oficial e não recebe mensagens nem inicia polling.")
+    with st.form("telegram_notifications_form"):
+        telegram_enabled = st.checkbox(
+            "Activar notificações Telegram",
+            value=bool(settings.get("telegram_enabled", False)),
+            help="Quando activo, cada nova notificação permitida em Geral é enviada para o Chat ID configurado.",
+        )
+        telegram_cols = st.columns(2)
+        with telegram_cols[0]:
+            telegram_bot_token = st.text_input(
+                "Telegram Bot Token",
+                value=str(settings.get("telegram_bot_token") or ""),
+                type="password",
+                help="Token criado pelo BotFather. Fica guardado apenas no storage local.",
+            )
+            _render_credential_status(telegram_bot_token)
+        with telegram_cols[1]:
+            telegram_chat_id = st.text_input(
+                "Telegram Chat ID",
+                value=str(settings.get("telegram_chat_id") or ""),
+                help="ID do utilizador, grupo ou canal que receberá as notificações; também pode ser um username aceite pelo Telegram.",
+            )
+        telegram_proxy_url = st.text_input(
+            "Proxy Telegram (opcional)",
+            value=str(settings.get("telegram_proxy_url") or ""),
+            help="Proxy HTTP/HTTPS/SOCKS suportado pelo ambiente, quando o acesso directo ao Telegram não estiver disponível.",
+        )
+        telegram_timeout_seconds = st.number_input(
+            "Timeout de envio (segundos)",
+            min_value=5,
+            max_value=120,
+            value=int(settings.get("telegram_timeout_seconds", 15) or 15),
+            step=5,
+        )
+        st.caption("O teste consulta getMe para validar o Bot Token e não envia uma mensagem de teste.")
+        _render_api_test_control(
+            settings,
+            "telegram",
+            lambda: test_telegram_credentials(telegram_bot_token, telegram_chat_id),
+            widget_key="api_test_telegram",
+        )
+        if st.form_submit_button("Guardar configuração Telegram", type="primary", use_container_width=True):
+            settings.update({
+                "telegram_enabled": bool(telegram_enabled),
+                "telegram_bot_token": telegram_bot_token.strip(),
+                "telegram_chat_id": telegram_chat_id.strip(),
+                "telegram_proxy_url": telegram_proxy_url.strip(),
+                "telegram_timeout_seconds": int(telegram_timeout_seconds),
+            })
+            write_json("settings.json", settings)
+            st.success("Configuração Telegram guardada no storage local.")
+            st.rerun()
+
+    if telegram_enabled and telegram_bot_token.strip() and telegram_chat_id.strip():
+        st.success("Telegram está preparado para receber novas notificações.")
+    elif telegram_enabled:
+        st.warning("Telegram está activo, mas ainda falta configurar o Bot Token e o Chat ID.")
+    else:
+        st.info("Telegram está desactivado. As notificações continuam disponíveis na subaba Geral.")
+
+
 def render_notifications():
     st.title("Notificações")
     st.caption("Centro de notificações internas persistentes do Thunderbolt. As conclusões são guardadas no storage local e aparecem quando a aplicação é actualizada.")
-    reconcile_persisted_notifications()
-    preferences = notification_preferences()
-    catalog = notification_event_catalog()
-    notifications = list_notifications(limit=500)
-    unread_count = unread_notification_count()
-    summary_cols = st.columns(3)
-    with summary_cols[0]:
-        st.metric("Não lidas", unread_count)
-    with summary_cols[1]:
-        st.metric("Total guardado", len(notifications))
-    with summary_cols[2]:
-        st.metric("Operações mapeadas", len(catalog))
-
-    action_cols = st.columns([1.4, 1.4, 2.2])
-    with action_cols[0]:
-        if st.button("Marcar todas como lidas", use_container_width=True, disabled=unread_count == 0):
-            mark_all_notifications_read()
-            st.rerun()
-    with action_cols[1]:
-        if st.button("Actualizar notificações", use_container_width=True):
-            reconcile_persisted_notifications()
-            st.rerun()
-    with action_cols[2]:
-        confirm_clear = st.checkbox("Confirmar limpeza do histórico", key="confirm_clear_notifications")
-        if st.button("Limpar histórico", use_container_width=True, disabled=not confirm_clear):
-            clear_notifications()
-            st.session_state.pop("confirm_clear_notifications", None)
-            st.rerun()
+    general_tab, telegram_tab = render_localized_tabs(["Geral", "Telegram"])
 
-    st.divider()
-    st.subheader("Operações notificadas")
-    st.caption("Ligue ou desligue cada tipo de notificação. As preferências ficam guardadas no storage local e aplicam-se às próximas conclusões.")
-    grouped: dict[str, list[dict[str, str]]] = {}
-    for event in catalog:
-        grouped.setdefault(event["category"], []).append(event)
-    with st.form("notification_preferences_form"):
-        pending_preferences: dict[str, bool] = {}
-        for category, events in grouped.items():
-            st.markdown(f"**{category}**")
-            for event in events:
-                pending_preferences[event["code"]] = st.checkbox(
-                    event["label"],
-                    value=bool(preferences.get(event["code"], True)),
-                    help=event["description"],
-                    key=f"notification_preference_{event['code']}",
-                )
-        if st.form_submit_button("Guardar preferências", type="primary", use_container_width=True):
-            save_notification_preferences(pending_preferences)
-            st.success("Preferências de notificação guardadas.")
-            st.rerun()
+    with general_tab:
+        reconcile_persisted_notifications()
+        preferences = notification_preferences()
+        catalog = notification_event_catalog()
+        notifications = list_notifications(limit=500)
+        unread_count = unread_notification_count()
+        summary_cols = st.columns(3)
+        with summary_cols[0]:
+            st.metric("Não lidas", unread_count)
+        with summary_cols[1]:
+            st.metric("Total guardado", len(notifications))
+        with summary_cols[2]:
+            st.metric("Operações mapeadas", len(catalog))
+
+        action_cols = st.columns([1.4, 1.4, 2.2])
+        with action_cols[0]:
+            if st.button("Marcar todas como lidas", use_container_width=True, disabled=unread_count == 0):
+                mark_all_notifications_read()
+                st.rerun()
+        with action_cols[1]:
+            if st.button("Actualizar notificações", use_container_width=True):
+                reconcile_persisted_notifications()
+                st.rerun()
+        with action_cols[2]:
+            confirm_clear = st.checkbox("Confirmar limpeza do histórico", key="confirm_clear_notifications")
+            if st.button("Limpar histórico", use_container_width=True, disabled=not confirm_clear):
+                clear_notifications()
+                st.session_state.pop("confirm_clear_notifications", None)
+                st.rerun()
 
-    st.divider()
-    st.subheader("Histórico de notificações")
-    filter_cols = st.columns([1, 1.4])
-    category_options = ["Todas"] + sorted({event["category"] for event in catalog})
-    with filter_cols[0]:
-        selected_category = st.selectbox("Categoria", category_options, key="notifications_category_filter")
-    with filter_cols[1]:
-        selected_state = st.selectbox("Estado", ["Todas", "Não lidas", "Lidas"], key="notifications_state_filter")
-    category_filter = "" if selected_category == "Todas" else selected_category
-    unread_filter = selected_state == "Não lidas"
-    filtered = list_notifications(limit=500, category=category_filter, unread_only=unread_filter)
-    if selected_state == "Lidas":
-        filtered = [item for item in filtered if item.get("read")]
-    if not filtered:
-        st.info("Ainda não existem notificações para os filtros seleccionados.")
-    for item in filtered:
-        with st.container(border=True):
-            notification_cols = st.columns([3.3, 1.4, 1])
-            with notification_cols[0]:
-                st.write(f"**{item.get('title') or item.get('label') or 'Notificação'}**")
-                st.caption(item.get("message") or "")
-                metadata = item.get("metadata") if isinstance(item.get("metadata"), dict) else {}
-                if metadata:
-                    public_details = " · ".join(f"{key}: {value}" for key, value in metadata.items() if value not in (None, ""))
-                    if public_details:
-                        st.caption(public_details)
-            with notification_cols[1]:
-                st.caption(f"{item.get('category', 'Sistema')} · {item.get('created_at', '—')}")
-                st.write("Lida" if item.get("read") else "Não lida")
-            with notification_cols[2]:
-                if not item.get("read") and st.button("Marcar como lida", key=f"mark_notification_{item.get('id')}", use_container_width=True):
-                    mark_notification_read(str(item.get("id")))
-                    st.rerun()
+        st.divider()
+        st.subheader("Operações notificadas")
+        st.caption("Ligue ou desligue cada tipo de notificação. As preferências ficam guardadas no storage local e aplicam-se às próximas conclusões.")
+        grouped: dict[str, list[dict[str, str]]] = {}
+        for event in catalog:
+            grouped.setdefault(event["category"], []).append(event)
+        with st.form("notification_preferences_form"):
+            pending_preferences: dict[str, bool] = {}
+            for category, events in grouped.items():
+                st.markdown(f"**{category}**")
+                for event in events:
+                    pending_preferences[event["code"]] = st.checkbox(
+                        event["label"],
+                        value=bool(preferences.get(event["code"], True)),
+                        help=event["description"],
+                        key=f"notification_preference_{event['code']}",
+                    )
+            if st.form_submit_button("Guardar preferências", type="primary", use_container_width=True):
+                save_notification_preferences(pending_preferences)
+                st.success("Preferências de notificação guardadas.")
+                st.rerun()
+
+        st.divider()
+        st.subheader("Histórico de notificações")
+        filter_cols = st.columns([1, 1.4])
+        category_options = ["Todas"] + sorted({event["category"] for event in catalog})
+        with filter_cols[0]:
+            selected_category = st.selectbox("Categoria", category_options, key="notifications_category_filter")
+        with filter_cols[1]:
+            selected_state = st.selectbox("Estado", ["Todas", "Não lidas", "Lidas"], key="notifications_state_filter")
+        category_filter = "" if selected_category == "Todas" else selected_category
+        unread_filter = selected_state == "Não lidas"
+        filtered = list_notifications(limit=500, category=category_filter, unread_only=unread_filter)
+        if selected_state == "Lidas":
+            filtered = [item for item in filtered if item.get("read")]
+        if not filtered:
+            st.info("Ainda não existem notificações para os filtros seleccionados.")
+        for item in filtered:
+            with st.container(border=True):
+                notification_cols = st.columns([3.3, 1.4, 1])
+                with notification_cols[0]:
+                    st.write(f"**{item.get('title') or item.get('label') or 'Notificação'}**")
+                    st.caption(item.get("message") or "")
+                    metadata = item.get("metadata") if isinstance(item.get("metadata"), dict) else {}
+                    if metadata:
+                        public_details = " · ".join(f"{key}: {value}" for key, value in metadata.items() if value not in (None, ""))
+                        if public_details:
+                            st.caption(public_details)
+                with notification_cols[1]:
+                    st.caption(f"{item.get('category', 'Sistema')} · {item.get('created_at', '—')}")
+                    st.write("Lida" if item.get("read") else "Não lida")
+                with notification_cols[2]:
+                    if not item.get("read") and st.button("Marcar como lida", key=f"mark_notification_{item.get('id')}", use_container_width=True):
+                        mark_notification_read(str(item.get("id")))
+                        st.rerun()
+
+    with telegram_tab:
+        _render_telegram_notification_settings()
 
 
 def render_models_ai_tutorial():

package/hermes_ui/api_key_tests.py

@@ -213,6 +213,18 @@ def test_postiz_credentials(api_key: str, base_url: str = "https://api.postiz.co
     return _get(f"{base}/integrations", headers={"Authorization": api_key})
 
 
+def test_telegram_credentials(bot_token: str, chat_id: str) -> dict[str, Any]:
+    """Validate the Telegram bot token with getMe without sending a message."""
+    bot_token = str(bot_token or "").strip()
+    chat_id = str(chat_id or "").strip()
+    if not bot_token or not chat_id:
+        return _missing("Introduza o Bot Token e o Chat ID Telegram antes de testar.")
+    result = _get(f"https://api.telegram.org/bot{bot_token}/getMe")
+    if result.get("ok"):
+        result["message"] = "Bot Token Telegram válido. O Chat ID foi aceite localmente; o teste não enviou mensagem."
+    return result
+
+
 def test_material_source_credentials(provider: str, api_key: str) -> dict[str, Any]:
     """Run a read-only provider-specific check for material source cards."""
     provider = str(provider or "").strip().lower()

package/hermes_ui/languages.py

@@ -614,6 +614,27 @@ for _language_code, _tab_translation in TAB_TRANSLATIONS.items():
     UI_TRANSLATIONS[_language_code].update(_tab_translation)
 
 
+_NOTIFICATION_TAB_TRANSLATIONS: dict[str, dict[str, str]] = {
+    "pt": {"Geral": "Geral", "Telegram": "Telegram"},
+    "en": {"Geral": "General", "Telegram": "Telegram"},
+    "zh": {"Geral": "常规", "Telegram": "Telegram"},
+    "de": {"Geral": "Allgemein", "Telegram": "Telegram"},
+    "vi": {"Geral": "Chung", "Telegram": "Telegram"},
+    "tr": {"Geral": "Genel", "Telegram": "Telegram"},
+    "ru": {"Geral": "Общие", "Telegram": "Telegram"},
+    "es": {"Geral": "General", "Telegram": "Telegram"},
+    "id": {"Geral": "Umum", "Telegram": "Telegram"},
+    "it": {"Geral": "Generale", "Telegram": "Telegram"},
+    "pl": {"Geral": "Ogólne", "Telegram": "Telegram"},
+    "ga": {"Geral": "Ginearálta", "Telegram": "Telegram"},
+    "ar": {"Geral": "عام", "Telegram": "Telegram"},
+    "he": {"Geral": "כללי", "Telegram": "Telegram"},
+}
+for _language_code, _notification_tab_translation in _NOTIFICATION_TAB_TRANSLATIONS.items():
+    if _language_code in UI_TRANSLATIONS:
+        UI_TRANSLATIONS[_language_code].update(_notification_tab_translation)
+
+
 TUTORIAL_TRANSLATIONS: dict[str, dict[str, str]] = {
     "pt": {"Tutorial Supabase": "Tutorial Supabase", "Guia de configuração do Supabase para automações com n8n.": "Guia de configuração do Supabase para automações com n8n."},
     "en": {"Tutorial Supabase": "Supabase Tutorial", "Guia de configuração do Supabase para automações com n8n.": "Supabase setup guide for n8n automations."},

package/hermes_ui/notifications.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 import re
 import uuid
 from datetime import datetime, timezone
@@ -40,6 +41,8 @@ EVENT_CATALOG: tuple[dict[str, str], ...] = (
     {"code": "mcp_operation_completed", "category": "Integrações", "label": "Operação MCP concluída", "description": "Quando uma operação mutável de integração MCP terminar com sucesso."},
 )
 EVENTS_BY_CODE = {item["code"]: item for item in EVENT_CATALOG}
+LOGGER = logging.getLogger(__name__)
+
 SENSITIVE_MARKERS = (
     "token",
     "secret",
@@ -119,6 +122,24 @@ def _history() -> list[dict[str, Any]]:
     return [item for item in saved if isinstance(item, dict)]
 
 
+def _dispatch_telegram_notification(entry: dict[str, Any]) -> None:
+    """Deliver a persisted event to Telegram without affecting local flows."""
+    try:
+        settings = storage.read_json("settings.json", {})
+        if not isinstance(settings, dict) or not bool(settings.get("telegram_enabled", False)):
+            return
+        from integrations.telegram_gateway import send_notification_to_telegram
+
+        result = send_notification_to_telegram(entry, settings)
+        if not result.ok:
+            error_type = result.data.get("error_type") if isinstance(result.data, dict) else ""
+            if error_type != "missing_configuration":
+                LOGGER.warning("Telegram notification delivery failed (%s).", error_type or "unknown_error")
+    except Exception as exc:
+        # External notification delivery must never break production, uploads or UI.
+        LOGGER.warning("Telegram notification delivery failed (%s).", type(exc).__name__)
+
+
 def record_notification(
     event_type: str,
     title: str,
@@ -151,6 +172,7 @@ def record_notification(
         "dedupe_key": str(dedupe_key or ""),
     }
     storage.write_json(NOTIFICATIONS_FILE, [entry, *history][:MAX_NOTIFICATIONS])
+    _dispatch_telegram_notification(entry)
     return entry
 
 

package/hermes_ui/storage.py

@@ -96,6 +96,11 @@ DEFAULTS: dict[str, Any] = {
         "youtube_client_secret": "",
         "youtube_batch_accounts": [],
         "youtube_batch_selected_account_id": "",
+        "telegram_enabled": False,
+        "telegram_bot_token": "",
+        "telegram_chat_id": "",
+        "telegram_proxy_url": "",
+        "telegram_timeout_seconds": 15,
         "notification_preferences": {
             "video_completed": True,
             "music_completed": True,

package/integrations/telegram_gateway.py

@@ -0,0 +1,158 @@
+"""Outbound Telegram Gateway integration for persisted Thunderbolt notifications."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Callable
+
+import requests
+
+from .platforms import IntegrationResult
+
+DEFAULT_TELEGRAM_API_BASE_URL = "https://api.telegram.org"
+TELEGRAM_MAX_MESSAGE_LENGTH = 4096
+DEFAULT_TELEGRAM_TIMEOUT = 15
+
+
+class TelegramGatewayAdapter:
+    """Send Thunderbolt notifications through the Telegram Bot API.
+
+    The adapter deliberately implements outbound delivery only. It does not
+    poll Telegram or receive messages, which keeps notification delivery
+    isolated from the production and upload flows.
+    """
+
+    def __init__(self, settings: dict[str, Any] | None = None, *, request_client: Any = requests) -> None:
+        self.settings = settings or {}
+        self.enabled = bool(self.settings.get("telegram_enabled", False))
+        self.bot_token = str(self.settings.get("telegram_bot_token") or os.getenv("TELEGRAM_BOT_TOKEN", "")).strip()
+        self.chat_id = str(self.settings.get("telegram_chat_id") or os.getenv("TELEGRAM_CHAT_ID", "")).strip()
+        self.proxy_url = str(self.settings.get("telegram_proxy_url") or os.getenv("TELEGRAM_PROXY_URL", "")).strip()
+        self.timeout = max(1, int(self.settings.get("telegram_timeout_seconds", DEFAULT_TELEGRAM_TIMEOUT) or DEFAULT_TELEGRAM_TIMEOUT))
+        self._request_client = request_client
+
+    def _error(self, message: str, *, status_code: int | None = None, error_type: str = "") -> IntegrationResult:
+        data: dict[str, Any] = {}
+        if status_code is not None:
+            data["status_code"] = status_code
+        if error_type:
+            data["error_type"] = error_type
+        return IntegrationResult(False, message, data)
+
+    def status(self) -> IntegrationResult:
+        if not self.enabled:
+            return self._error("Telegram está desactivado nas notificações.", error_type="disabled")
+        if not self.bot_token or not self.chat_id:
+            return self._error("Telegram não está configurado: indique o Bot Token e o Chat ID.", error_type="missing_configuration")
+        return IntegrationResult(True, "Telegram configurado para notificações.", {"chat_id_configured": True})
+
+    def _url(self, method: str) -> str:
+        return f"{DEFAULT_TELEGRAM_API_BASE_URL}/bot{self.bot_token}/{method}"
+
+    def _request_kwargs(self, payload: dict[str, Any]) -> dict[str, Any]:
+        kwargs: dict[str, Any] = {"json": payload, "timeout": self.timeout}
+        if self.proxy_url:
+            kwargs["proxies"] = {"http": self.proxy_url, "https": self.proxy_url}
+        return kwargs
+
+    def _post(self, method: str, payload: dict[str, Any]) -> IntegrationResult:
+        try:
+            response = self._request_client.post(self._url(method), **self._request_kwargs(payload))
+        except requests.RequestException as exc:
+            return self._error("Não foi possível contactar o Telegram.", error_type=type(exc).__name__)
+        except Exception as exc:
+            return self._error("A chamada ao Telegram falhou.", error_type=type(exc).__name__)
+
+        status_code = int(getattr(response, "status_code", 0) or 0)
+        if status_code == 429:
+            return self._error("O Telegram limitou a chamada de notificação; tente novamente mais tarde.", status_code=status_code, error_type="rate_limited")
+        if status_code in {401, 403}:
+            return self._error("O Telegram rejeitou o Bot Token ou não permite o envio para este Chat ID.", status_code=status_code, error_type="unauthorized")
+        if status_code < 200 or status_code >= 300:
+            return self._error("O Telegram rejeitou a notificação.", status_code=status_code or None, error_type="http_error")
+        try:
+            payload_response = response.json()
+        except (TypeError, ValueError):
+            return self._error("O Telegram devolveu uma resposta inválida.", status_code=status_code, error_type="invalid_json")
+        if not isinstance(payload_response, dict) or payload_response.get("ok") is not True:
+            return self._error("O Telegram não aceitou a notificação.", status_code=status_code, error_type="api_error")
+        return IntegrationResult(True, "Notificação enviada pelo Telegram.", {"status_code": status_code, "result": payload_response.get("result")})
+
+    @staticmethod
+    def split_message(text: str, *, max_length: int = TELEGRAM_MAX_MESSAGE_LENGTH) -> list[str]:
+        """Split a message at line boundaries while respecting Telegram's limit."""
+        normalized = str(text or "").strip()
+        if not normalized:
+            return []
+        chunks: list[str] = []
+        remaining = normalized
+        while len(remaining) > max_length:
+            cut = remaining.rfind("\n", 0, max_length + 1)
+            if cut < max_length // 2:
+                cut = max_length
+            chunks.append(remaining[:cut].rstrip())
+            remaining = remaining[cut:].lstrip()
+        if remaining:
+            chunks.append(remaining)
+        return chunks
+
+    @staticmethod
+    def format_notification(notification: dict[str, Any]) -> str:
+        """Format an already-redacted local notification for Telegram."""
+        title = str(notification.get("title") or notification.get("label") or "Notificação").strip()
+        message = str(notification.get("message") or "").strip()
+        category = str(notification.get("category") or "Sistema").strip()
+        created_at = str(notification.get("created_at") or "").strip()
+        lines = [title]
+        if message:
+            lines.append(message)
+        details: list[str] = []
+        if category:
+            details.append(f"Categoria: {category}")
+        if created_at:
+            details.append(f"Data: {created_at}")
+        metadata = notification.get("metadata")
+        if isinstance(metadata, dict):
+            for key, value in metadata.items():
+                if value in (None, "", [], {}):
+                    continue
+                details.append(f"{key}: {value}")
+        if details:
+            lines.extend(["", *details])
+        return "\n".join(lines)
+
+    def send_message(self, text: str) -> IntegrationResult:
+        """Send plain text to the configured chat, splitting oversized messages."""
+        status = self.status()
+        if not status.ok:
+            return status
+        chunks = self.split_message(text)
+        if not chunks:
+            return self._error("A notificação Telegram está vazia.", error_type="empty_message")
+        message_ids: list[str] = []
+        for chunk in chunks:
+            result = self._post("sendMessage", {"chat_id": self.chat_id, "text": chunk})
+            if not result.ok:
+                return result
+            message_result = result.data.get("result") if isinstance(result.data, dict) else None
+            if isinstance(message_result, dict) and message_result.get("message_id") is not None:
+                message_ids.append(str(message_result["message_id"]))
+        return IntegrationResult(True, "Notificação enviada pelo Telegram.", {"message_ids": message_ids, "chunks": len(chunks)})
+
+    def send_notification(self, notification: dict[str, Any]) -> IntegrationResult:
+        """Format and send one persisted Thunderbolt notification."""
+        return self.send_message(self.format_notification(notification))
+
+
+def send_notification_to_telegram(notification: dict[str, Any], settings: dict[str, Any] | None = None) -> IntegrationResult:
+    """Convenience function used by the notification persistence layer."""
+    return TelegramGatewayAdapter(settings).send_notification(notification)
+
+
+__all__ = [
+    "DEFAULT_TELEGRAM_API_BASE_URL",
+    "DEFAULT_TELEGRAM_TIMEOUT",
+    "TELEGRAM_MAX_MESSAGE_LENGTH",
+    "TelegramGatewayAdapter",
+    "send_notification_to_telegram",
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danhachuel/thunderbolt",
-  "version": "0.3.33",
+  "version": "0.3.35",
   "description": "Thunderbolt — interface local para operação de canais faceless e motor MoneyPrinterTurbo",
   "license": "MIT",
   "main": "scripts/cli.mjs",
@@ -30,6 +30,7 @@
     ".streamlit/config.toml"
   ],
   "scripts": {
+    "postinstall": "node scripts/npx-cache-compat.mjs",
     "start": "node scripts/cli.mjs",
     "check": "node scripts/cli.mjs --check",
     "pack:check": "npm pack --dry-run"

package/requirements.txt

@@ -1,5 +1,5 @@
 streamlit>=1.37,<2
-requests>=2.31,<3
+requests[socks]>=2.31,<3
 pandas>=2.0,<3
 imageio-ffmpeg>=0.6,<1
 toml>=0.10,<1

package/scripts/npx-cache-compat.mjs

@@ -0,0 +1,15 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const npxCacheRoot = resolve(packageRoot, "../../..");
+const pathParts = npxCacheRoot.split(/[\\/]+/).filter(Boolean).map((part) => part.toLowerCase());
+const isNpxCache = pathParts.includes("_npx");
+const packageJsonPath = resolve(npxCacheRoot, "package.json");
+
+if (isNpxCache && !existsSync(packageJsonPath)) {
+  mkdirSync(npxCacheRoot, { recursive: true });
+  writeFileSync(packageJsonPath, JSON.stringify({ private: true }, null, 2) + "\n", "utf8");
+}
+