@omnizap-system/omnizap 2.6.0 → 2.6.2

package/app/modules/menuModule/menus.js

@@ -1,5 +1,6 @@
 import logger from '#logger';
 import { buildAnimeMenu, buildAiMenu, buildMediaMenu, buildMenuCaption, buildQuoteMenu, buildStatsMenu, buildStickerMenu, buildAdminMenu } from './common.js';
+import { resolveDynamicMenuText } from './menuDynamicService.js';
 import getImageBuffer from '../../utils/http/getImageBufferModule.js';
 import { sendAndStore } from '../../services/messaging/messagePersistenceService.js';
 
@@ -11,10 +12,13 @@ const sanitizeLogValue = (value) =>
     .trim();
 
 const sendMenuImage = async (sock, remoteJid, messageInfo, expirationMessage, caption) => {
+  const safeCaption = String(caption || '').trim() || 'Menu indisponível no momento.';
   const imageUrl = process.env[MENU_IMAGE_ENV];
   if (!imageUrl) {
-    logger.error('IMAGE_MENU environment variable not set.');
-    await sendAndStore(sock, remoteJid, { text: 'Ocorreu um erro ao carregar o menu.' }, { quoted: messageInfo, ephemeralExpiration: expirationMessage });
+    logger.warn('IMAGE_MENU environment variable not set. Sending plain-text menu fallback.', {
+      action: 'menu_image_env_missing',
+    });
+    await sendAndStore(sock, remoteJid, { text: safeCaption }, { quoted: messageInfo, ephemeralExpiration: expirationMessage });
     return;
   }
 
@@ -25,7 +29,7 @@ const sendMenuImage = async (sock, remoteJid, messageInfo, expirationMessage, ca
       remoteJid,
       {
         image: imageBuffer,
-        caption,
+        caption: safeCaption,
       },
       { quoted: messageInfo, ephemeralExpiration: expirationMessage },
     );
@@ -33,11 +37,22 @@ const sendMenuImage = async (sock, remoteJid, messageInfo, expirationMessage, ca
     logger.error('Error fetching menu image.', {
       error: sanitizeLogValue(error?.message) || 'unknown_error',
     });
-    await sendAndStore(sock, remoteJid, { text: 'Ocorreu um erro ao carregar a imagem do menu.' }, { quoted: messageInfo, ephemeralExpiration: expirationMessage });
+    await sendAndStore(sock, remoteJid, { text: safeCaption }, { quoted: messageInfo, ephemeralExpiration: expirationMessage });
   }
 };
 
 export async function handleMenuCommand(sock, remoteJid, messageInfo, expirationMessage, senderName, commandPrefix, args = []) {
+  const dynamicCaption = await resolveDynamicMenuText({
+    args,
+    senderName,
+    commandPrefix,
+    remoteJid,
+  });
+  if (dynamicCaption) {
+    await sendMenuImage(sock, remoteJid, messageInfo, expirationMessage, dynamicCaption.trim());
+    return;
+  }
+
   const category = args?.[0]?.toLowerCase();
   const categoryMap = new Map([
     ['figurinhas', (prefix) => buildStickerMenu(prefix)],
@@ -61,6 +76,22 @@ export async function handleMenuCommand(sock, remoteJid, messageInfo, expiration
   await sendMenuImage(sock, remoteJid, messageInfo, expirationMessage, caption);
 }
 
-export async function handleMenuAdmCommand(sock, remoteJid, messageInfo, expirationMessage, commandPrefix) {
+export async function handleMenuAdmCommand(sock, remoteJid, messageInfo, expirationMessage, commandPrefix, args = []) {
+  const safeArgs = Array.isArray(args) ? args.map((value) => String(value || '').trim()).filter(Boolean) : [];
+  const dynamicArgs = safeArgs.length ? safeArgs : ['categoria', 'admin'];
+  const dynamicCaption = await resolveDynamicMenuText({
+    args: dynamicArgs,
+    senderName: 'admin',
+    commandPrefix,
+    remoteJid,
+    menuCommandName: 'menuadm',
+    categoryScopeKeys: ['admin'],
+  });
+
+  if (dynamicCaption) {
+    await sendMenuImage(sock, remoteJid, messageInfo, expirationMessage, dynamicCaption.trim());
+    return;
+  }
+
   await sendMenuImage(sock, remoteJid, messageInfo, expirationMessage, buildAdminMenu(commandPrefix).trim());
 }

package/app/modules/playModule/AGENT.md

@@ -7,13 +7,18 @@ Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos co
 - arquivo_base: `app/modules/playModule/commandConfig.json`
 - schema_version: `2.0.0`
 - module_enabled: `true`
-- generated_at: `2026-03-11T02:35:17.177Z`
+- generated_at: `2026-03-17T04:04:14.195Z`
 
 ## Escopo do Modulo
 
 - module: `playModule`
 - source_files:
 - playCommand.js
+- playCommandHandlers.js
+- playCommandCore.js
+- playCommandMediaClient.js
+- playCommandConstants.js
+- playConfigRuntime.js
 - total_commands: `2`
 - total_enabled_commands: `2`
 
@@ -119,10 +124,10 @@ Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos co
 - texto do comando e argumentos
 - contexto da mensagem (citacao e mencoes, quando existir)
 - link ou termo de busca enviado no comando
-- metadados de fila/download retornados pelo servico de midia
+- metadados de busca/download retornados pelo provedor de midia
 - informacoes de tamanho do arquivo para validacao de limite
 - dependencias_externas:
-- serviço YTDLS/Downloader
+- provedor de midia local (ytmp3 via API)
 - ffmpeg
 - ffprobe
 - efeitos_colaterais:
@@ -244,10 +249,10 @@ Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos co
 - texto do comando e argumentos
 - contexto da mensagem (citacao e mencoes, quando existir)
 - link ou termo de busca enviado no comando
-- metadados de fila/download retornados pelo servico de midia
+- metadados de busca/download retornados pelo provedor de midia
 - informacoes de tamanho e formato de video para validacao
 - dependencias_externas:
-- serviço YTDLS/Downloader
+- provedor de midia local (ytmp3 via API)
 - ffmpeg
 - ffprobe
 - efeitos_colaterais:

package/app/modules/playModule/commandConfig.json

@@ -2,7 +2,7 @@
   "schema_version": "2.0.0",
   "module": "playModule",
   "enabled": true,
-  "source_files": ["playCommand.js"],
+  "source_files": ["playCommand.js", "playCommandHandlers.js", "playCommandCore.js", "playCommandMediaClient.js", "playCommandConstants.js", "playConfigRuntime.js"],
   "defaults": {
     "inheritance_mode": "deep_merge_with_command_overrides",
     "compatibility_mode": "legacy_and_v2_fields",
@@ -62,8 +62,8 @@
       "janela_ms": null,
       "escopo": "sem_rate_limit_explicito"
     },
-    "dependencies": ["serviço YTDLS/Downloader", "ffmpeg", "ffprobe"],
-    "dependencias_externas": ["serviço YTDLS/Downloader", "ffmpeg", "ffprobe"],
+    "dependencies": ["provedor de midia local (ytmp3 via API)", "ffmpeg", "ffprobe"],
+    "dependencias_externas": ["provedor de midia local (ytmp3 via API)", "ffmpeg", "ffprobe"],
     "responses": {
       "success": "Comando executado com sucesso.",
       "usage_error": "Formato de uso inválido. Consulte metodos_de_uso.",
@@ -152,7 +152,7 @@
       "permissao_necessaria": "usuario comum",
       "limite_de_uso": "arquivo ate PLAY_MAX_MB (padrao 100 MB)",
       "local_de_uso": ["privado", "grupo"],
-      "informacoes_coletadas": ["identificador do chat (remoteJid)", "identificador do remetente (senderJid)", "texto do comando e argumentos", "contexto da mensagem (citacao e mencoes, quando existir)", "link ou termo de busca enviado no comando", "metadados de fila/download retornados pelo servico de midia", "informacoes de tamanho do arquivo para validacao de limite"],
+      "informacoes_coletadas": ["identificador do chat (remoteJid)", "identificador do remetente (senderJid)", "texto do comando e argumentos", "contexto da mensagem (citacao e mencoes, quando existir)", "link ou termo de busca enviado no comando", "metadados de busca/download retornados pelo provedor de midia", "informacoes de tamanho do arquivo para validacao de limite"],
       "enabled": true,
       "categoria": "midia",
       "subcomandos": [],
@@ -179,7 +179,7 @@
         "janela_ms": null,
         "escopo": "sem_rate_limit_explicito"
       },
-      "dependencias_externas": ["serviço YTDLS/Downloader", "ffmpeg", "ffprobe"],
+      "dependencias_externas": ["provedor de midia local (ytmp3 via API)", "ffmpeg", "ffprobe"],
       "efeitos_colaterais": ["baixa mídia temporária", "envia áudio no chat"],
       "respostas_padrao": {
         "sucesso": "Comando executado com sucesso.",
@@ -228,7 +228,7 @@
       },
       "permission": "usuario comum",
       "contexts": ["privado", "grupo"],
-      "collected_data": ["identificador do chat (remoteJid)", "identificador do remetente (senderJid)", "texto do comando e argumentos", "contexto da mensagem (citacao e mencoes, quando existir)", "link ou termo de busca enviado no comando", "metadados de fila/download retornados pelo servico de midia", "informacoes de tamanho do arquivo para validacao de limite"],
+      "collected_data": ["identificador do chat (remoteJid)", "identificador do remetente (senderJid)", "texto do comando e argumentos", "contexto da mensagem (citacao e mencoes, quando existir)", "link ou termo de busca enviado no comando", "metadados de busca/download retornados pelo provedor de midia", "informacoes de tamanho do arquivo para validacao de limite"],
       "requirements": {
         "require_group": false,
         "require_group_admin": false,
@@ -290,7 +290,7 @@
           }
         }
       },
-      "dependencies": ["serviço YTDLS/Downloader", "ffmpeg", "ffprobe"],
+      "dependencies": ["provedor de midia local (ytmp3 via API)", "ffmpeg", "ffprobe"],
       "side_effects": ["baixa mídia temporária", "envia áudio no chat"],
       "observability": {
         "event_name": "command.executed",
@@ -357,6 +357,35 @@
         "schema": "legacy_v1_and_v2",
         "legacy_name": "tocar",
         "legacy_fields_present": ["descricao", "metodos_de_uso", "permissao_necessaria", "local_de_uso", "informacoes_coletadas", "argumentos", "pre_condicoes", "dependencias_externas", "efeitos_colaterais", "observabilidade", "privacidade", "acesso", "limite_uso_por_plano"]
+      },
+      "user_experience": {
+        "resumo_usuario": "Tocar reproduz/gera áudio a partir de um link do YouTube ou de um termo de busca. Disponível para todos (não requer premium).",
+        "quando_usar": ["Quando quiser ouvir o áudio de um vídeo do YouTube sem abrir o navegador.", "Quando você tem um link do YouTube e quer ouvir rapidamente no chat.", "Quando prefere buscar por um termo e ouvir o áudio resultante."],
+        "exemplos_reais": [
+          {
+            "situacao": "Usuário tem o link de um vídeo e quer ouvir o áudio.",
+            "comando": "<prefix>tocar https://youtube.com/watch?v=EXEMPLO",
+            "resposta_esperada": "Comando executado com sucesso.",
+            "variacao": "<prefix>tocar https://youtu.be/EXEMPLO."
+          },
+          {
+            "situacao": "Usuário quer ouvir áudio a partir de um termo de busca.",
+            "comando": "<prefix>tocar melhor trilha sonora de cinema",
+            "resposta_esperada": "Comando executado com sucesso.",
+            "variacao": "<prefix>tocar <termo de busca>."
+          },
+          {
+            "situacao": "Usuário envia o comando sem argumento ou com formato incorreto.",
+            "comando": "<prefix>tocar",
+            "resposta_esperada": "Formato de uso inválido. Consulte metodos_de_uso.",
+            "variacao": "<prefix>tocar <link>."
+          }
+        ],
+        "resposta_esperada": ["Comando executado com sucesso.", "Formato de uso inválido. Consulte metodos_de_uso.", "Permissão insuficiente para executar este comando."],
+        "erros_comuns_usuario": ["Não fornecer argumento (link ou termo de busca).", "Link não é de vídeo YouTube válido.", "Formato do comando não segue <prefix>tocar <link> ou <prefix>tocar <termo>.", "Não estar logado com a conta Google quando solicitado.", "Conectividade ruim ou serviço temporariamente indisponível."],
+        "passos_se_der_erro": ["Verifique se o comando usa <prefix>tocar <link> ou <prefix>tocar <termo>.", "Copie o link direto do YouTube ou revise o termo de busca.", "Tente novamente em instantes.", "Caso persista, confirme que a conta Google está disponível e tente novamente.", "Se ainda falhar, informe o contexto (link ou termo usado) para suporte."],
+        "resumo_usuario_origem": "auto_ia_assistida",
+        "resumo_usuario_revisao_pendente": true
       }
     },
     {
@@ -370,7 +399,7 @@
       "permissao_necessaria": "usuario comum",
       "limite_de_uso": "arquivo ate PLAY_MAX_MB (padrao 100 MB)",
       "local_de_uso": ["privado", "grupo"],
-      "informacoes_coletadas": ["identificador do chat (remoteJid)", "identificador do remetente (senderJid)", "texto do comando e argumentos", "contexto da mensagem (citacao e mencoes, quando existir)", "link ou termo de busca enviado no comando", "metadados de fila/download retornados pelo servico de midia", "informacoes de tamanho e formato de video para validacao"],
+      "informacoes_coletadas": ["identificador do chat (remoteJid)", "identificador do remetente (senderJid)", "texto do comando e argumentos", "contexto da mensagem (citacao e mencoes, quando existir)", "link ou termo de busca enviado no comando", "metadados de busca/download retornados pelo provedor de midia", "informacoes de tamanho e formato de video para validacao"],
       "enabled": true,
       "categoria": "midia",
       "subcomandos": [],
@@ -397,7 +426,7 @@
         "janela_ms": null,
         "escopo": "sem_rate_limit_explicito"
       },
-      "dependencias_externas": ["serviço YTDLS/Downloader", "ffmpeg", "ffprobe"],
+      "dependencias_externas": ["provedor de midia local (ytmp3 via API)", "ffmpeg", "ffprobe"],
       "efeitos_colaterais": ["baixa mídia temporária", "envia vídeo no chat"],
       "respostas_padrao": {
         "sucesso": "Comando executado com sucesso.",
@@ -446,7 +475,7 @@
       },
       "permission": "usuario comum",
       "contexts": ["privado", "grupo"],
-      "collected_data": ["identificador do chat (remoteJid)", "identificador do remetente (senderJid)", "texto do comando e argumentos", "contexto da mensagem (citacao e mencoes, quando existir)", "link ou termo de busca enviado no comando", "metadados de fila/download retornados pelo servico de midia", "informacoes de tamanho e formato de video para validacao"],
+      "collected_data": ["identificador do chat (remoteJid)", "identificador do remetente (senderJid)", "texto do comando e argumentos", "contexto da mensagem (citacao e mencoes, quando existir)", "link ou termo de busca enviado no comando", "metadados de busca/download retornados pelo provedor de midia", "informacoes de tamanho e formato de video para validacao"],
       "requirements": {
         "require_group": false,
         "require_group_admin": false,
@@ -508,7 +537,7 @@
           }
         }
       },
-      "dependencies": ["serviço YTDLS/Downloader", "ffmpeg", "ffprobe"],
+      "dependencies": ["provedor de midia local (ytmp3 via API)", "ffmpeg", "ffprobe"],
       "side_effects": ["baixa mídia temporária", "envia vídeo no chat"],
       "observability": {
         "event_name": "command.executed",
@@ -575,10 +604,109 @@
         "schema": "legacy_v1_and_v2",
         "legacy_name": "tocarvideo",
         "legacy_fields_present": ["descricao", "metodos_de_uso", "permissao_necessaria", "local_de_uso", "informacoes_coletadas", "argumentos", "pre_condicoes", "dependencias_externas", "efeitos_colaterais", "observabilidade", "privacidade", "acesso", "limite_uso_por_plano"]
+      },
+      "user_experience": {
+        "resumo_usuario": "Baixe ou reproduza vídeos do YouTube a partir de um link ou de termos de busca. Requer login Google e assinatura Premium. O conteúdo fica disponível no chat.",
+        "quando_usar": ["Quando você tem um link do YouTube que quer baixar para assistir no chat.", "Quando prefere buscar um vídeo pelo título/termo de busca em vez de colar o link.", "Antes de usar, confirme que você tem acesso à assinatura Premium."],
+        "exemplos_reais": [
+          {
+            "situacao": "Baixar vídeo a partir de um link do YouTube.",
+            "comando": "<prefix>tocarvideo https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+            "resposta_esperada": "Comando executado com sucesso.",
+            "variacao": "uso com link direto (alias: playvid)."
+          },
+          {
+            "situacao": "Buscar vídeo pelo termo de busca.",
+            "comando": "<prefix>tocarvideo melhor tutorial de edição de fotos",
+            "resposta_esperada": "Comando executado com sucesso.",
+            "variacao": "uso com termo de busca."
+          },
+          {
+            "situacao": "Tentar usar sem Premium.",
+            "comando": "<prefix>tocarvideo https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+            "resposta_esperada": "Permissão insuficiente para executar este comando.",
+            "variacao": "sem assinatura Premium."
+          }
+        ],
+        "resposta_esperada": ["Comando executado com sucesso.", "Formato de uso inválido. Consulte metodos_de_uso.", "Permissão insuficiente para executar este comando."],
+        "erros_comuns_usuario": ["Esquecer de incluir o link ou termo de busca.", "Enviar link que não é do YouTube.", "Não estar logado com uma conta Google.", "Tentar usar o recurso sem a assinatura Premium."],
+        "passos_se_der_erro": ["Verifique se você está usando o formato correto: <prefix>tocarvideo <link_do_youtube> ou <prefix>tocarvideo <termo>.", "Certifique-se de estar logado com uma conta Google válida.", "Confirme que você possui assinatura Premium ativa para este comando.", "Se o erro persistir, tente novamente após confirmar as informações ou entre em contato com o suporte com a captura de tela do erro."],
+        "resumo_usuario_origem": "auto_ia_assistida",
+        "resumo_usuario_revisao_pendente": true
       }
     }
   ],
+  "limites_operacionais": {
+    "max_search_results": 5,
+    "search_cache_ttl_ms": 60000,
+    "max_search_cache_entries": 500,
+    "max_redirects": 2,
+    "max_concurrent_jobs": 2,
+    "max_error_body_bytes": 65536,
+    "max_meta_body_chars": 512,
+    "retry_backoff_base_ms": 200,
+    "search_retry_count": 1,
+    "thumbnail_retry_count": 1,
+    "thumbnail_timeout_ms": 15000,
+    "max_thumb_bytes": 5242880,
+    "admin_alert_dedupe_window_ms": 120000
+  },
+  "opcoes_execucao": {
+    "media_provider_args": [],
+    "estrategias_formato": {
+      "audio": ["bestaudio/best", "best"],
+      "video": ["bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]/best", "bestvideo*+bestaudio/best", "best"],
+      "audio_extract": {
+        "enabled": true,
+        "format": "mp3",
+        "quality": "0"
+      },
+      "video_merge_output_format": "mp4"
+    }
+  },
   "textos": {
-    "usage_header": ""
+    "usage_header": "",
+    "error_prefix": "❌ Erro: ",
+    "generic_error": "Erro inesperado ao processar sua solicitação.",
+    "user_error_timeout": "A operação demorou mais que o esperado. Tente novamente.",
+    "user_error_technical_generic": "Não foi possível processar sua solicitação agora. Tente novamente em instantes.",
+    "admin_error_title": "Erro no módulo play (diagnóstico).",
+    "wait_audio": "⏳ Processando sua mídia...",
+    "wait_video": "⏳ Processando sua mídia...",
+    "ready_title_audio": "🎵 Áudio pronto!",
+    "ready_title_video": "🎬 Vídeo pronto!",
+    "video_fallback_to_audio": "⚠️ Este link retornou somente áudio. Enviando no formato de áudio.",
+    "anti_bot_with_cookies": "YouTube solicitou verificação anti-bot. Atualize o arquivo .secrets/cookies.txt e tente novamente.",
+    "anti_bot_with_browser_profile": "YouTube solicitou verificação anti-bot no provedor de mídia. Verifique suas credenciais e tente novamente.",
+    "anti_bot_without_cookies": "YouTube solicitou verificação anti-bot no provedor de mídia. Tente novamente em alguns minutos.",
+    "usage_fallback_audio": "🎵 Uso: <prefix>play <link do YouTube ou termo de busca>",
+    "usage_fallback_video": "🎬 Uso: <prefix>playvid <link do YouTube ou termo de busca>",
+    "invalid_media_type": "Tipo de mídia inválido.",
+    "provider_error_generic": "Falha ao processar mídia no provedor.",
+    "provider_timeout_generic": "Timeout ao processar mídia no provedor.",
+    "binary_exec_failed": "Falha ao executar <command>.",
+    "search_invalid_input": "Você precisa informar um link do YouTube ou termo de busca.",
+    "search_not_found": "Nenhum resultado encontrado para a busca.",
+    "search_timeout": "Timeout ao buscar metadados do vídeo.",
+    "search_failed": "Não foi possível buscar o vídeo agora.",
+    "video_unavailable": "Não foi possível acessar este vídeo agora. Tente outro link.",
+    "ffmpeg_not_found": "ffmpeg não encontrado no servidor para processar esta mídia.",
+    "download_timeout": "Timeout ao baixar o arquivo.",
+    "download_failed": "Falha ao baixar o arquivo localmente.",
+    "download_file_not_found": "Não foi possível localizar o arquivo baixado.",
+    "download_invalid_media": "Falha ao baixar mídia válida.",
+    "media_too_big": "O arquivo excede o limite permitido de <max_mb> MB.",
+    "probe_timeout": "Timeout ao analisar o vídeo recebido.",
+    "probe_failed": "Falha ao validar o vídeo recebido.",
+    "transcode_timeout": "Timeout ao normalizar o vídeo para envio.",
+    "transcode_failed": "Falha ao converter o vídeo para um formato compatível.",
+    "transcode_output_invalid": "Falha ao gerar vídeo compatível para envio.",
+    "video_without_streams": "Não foi possível enviar como vídeo: a mídia não possui faixa de vídeo nem áudio.",
+    "thumbnail_timeout": "Timeout ao baixar a thumbnail.",
+    "thumbnail_failed": "Falha ao baixar a thumbnail.",
+    "thumbnail_too_big": "Thumbnail excede o limite permitido.",
+    "http_timeout": "Timeout na requisição HTTP.",
+    "http_failed": "Falha na requisição HTTP.",
+    "content_too_big": "Conteúdo excede o limite permitido."
   }
 }