@omnizap-system/omnizap 2.5.12

package/app/modules/analyticsModule/messageAnalysisEventRepository.js

@@ -0,0 +1,83 @@
+import { executeQuery, TABLES } from '../../../database/index.js';
+
+const sanitizeText = (value, maxLength = 255) => {
+  const normalized = String(value || '')
+    .trim()
+    .replace(/\s+/g, ' ')
+    .slice(0, maxLength);
+  return normalized || null;
+};
+
+const sanitizeCommandName = (value) => {
+  const normalized = String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]/g, '')
+    .slice(0, 64);
+  return normalized || null;
+};
+
+const sanitizeBool = (value) => (value ? 1 : 0);
+
+const clampInt = (value, fallback, min, max) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(numeric)));
+};
+
+const sanitizeMetadata = (value) => {
+  if (!value || typeof value !== 'object') return null;
+  try {
+    const asJson = JSON.stringify(value);
+    if (!asJson || asJson === '{}') return null;
+    return asJson;
+  } catch {
+    return null;
+  }
+};
+
+export async function createMessageAnalysisEvent(payload = {}, connection = null) {
+  const messageId = sanitizeText(payload.messageId, 255);
+  const chatId = sanitizeText(payload.chatId, 255);
+  const senderId = sanitizeText(payload.senderId, 255);
+  const senderName = sanitizeText(payload.senderName, 120);
+  const upsertType = sanitizeText(payload.upsertType, 32);
+  const source = sanitizeText(payload.source, 32) || 'whatsapp';
+  const commandPrefix = sanitizeText(payload.commandPrefix, 8);
+  const commandName = sanitizeCommandName(payload.commandName);
+  const messageKind = sanitizeText(payload.messageKind, 48) || 'other';
+  const processingResult = sanitizeText(payload.processingResult, 64) || 'processed';
+  const errorCode = sanitizeText(payload.errorCode, 96);
+  const metadata = sanitizeMetadata(payload.metadata);
+
+  await executeQuery(
+    `INSERT INTO ${TABLES.MESSAGE_ANALYSIS_EVENT}
+      (
+        message_id,
+        chat_id,
+        sender_id,
+        sender_name,
+        upsert_type,
+        source,
+        is_group,
+        is_from_bot,
+        is_command,
+        command_name,
+        command_args_count,
+        command_known,
+        command_prefix,
+        message_kind,
+        has_media,
+        media_count,
+        text_length,
+        processing_result,
+        error_code,
+        metadata
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    [messageId, chatId, senderId, senderName, upsertType, source, sanitizeBool(payload.isGroup), sanitizeBool(payload.isFromBot), sanitizeBool(payload.isCommand), commandName, clampInt(payload.commandArgsCount, 0, 0, 64), payload.commandKnown === null || payload.commandKnown === undefined ? null : sanitizeBool(payload.commandKnown), commandPrefix, messageKind, sanitizeBool(payload.hasMedia), clampInt(payload.mediaCount, 0, 0, 25), clampInt(payload.textLength, 0, 0, 16_000), processingResult, errorCode, metadata],
+    connection,
+  );
+
+  return true;
+}

package/app/modules/gameModule/AGENT.md

@@ -0,0 +1,196 @@
+# GameModule Agent Guide
+
+Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos comandos deste modulo.
+
+## Fonte de Verdade
+
+- arquivo_base: `app/modules/gameModule/commandConfig.json`
+- schema_version: `2.0.0`
+- module_enabled: `true`
+- generated_at: `2026-03-11T02:35:17.177Z`
+
+## Escopo do Modulo
+
+- module: `gameModule`
+- source_files:
+- diceCommand.js
+- total_commands: `1`
+- total_enabled_commands: `1`
+
+## Defaults Schema v2
+
+- inheritance_mode: deep_merge_with_command_overrides
+- compatibility_mode: legacy_and_v2_fields
+- legacy_field_aliases:
+- descricao: description
+- metodos_de_uso: usage
+- permissao_necessaria: permission
+- local_de_uso: contexts
+- informacoes_coletadas: collected_data
+- pre_condicoes: requirements
+- dependencias_externas: dependencies
+- efeitos_colaterais: side_effects
+- observabilidade: observability
+- privacidade: privacy
+- limite_uso_por_plano: plan_limits
+- argumentos: arguments
+- acesso: access
+- defaults.command:
+- enabled: true
+- category: jogos
+- version: 1.0.0
+- stability: stable
+- deprecated: false
+- replaced_by: null
+- risk_level: medium
+- defaults.requirements (legacy view):
+- requer_grupo: nao
+- requer_admin: nao
+- requer_admin_principal: nao
+- requer_google_login: sim
+- requer_nsfw: nao
+- requer_midia: nao
+- requer_mensagem_respondida: nao
+
+## Protocolo de Resposta para IA
+
+- Passo 1: identificar comando pelo token apos o prefixo.
+- Passo 2: resolver alias para nome canonico usando campo `aliases`.
+- Passo 3: validar `enabled`, `pre_condicoes`, permissao e local de uso.
+- Passo 4: se houver erro de uso, responder com `mensagens_uso` (quando existir) ou `metodos_de_uso`.
+- Passo 5: seguir `respostas_padrao` como fallback de texto.
+- Passo 6: considerar `informacoes_coletadas`, `privacidade` e `observabilidade` ao elaborar resposta.
+
+## Regras de Seguranca para IA
+
+- A IA orienta, mas nao executa acao administrativa automaticamente.
+- Nao inventar comandos, subcomandos ou permissao fora do JSON.
+- Sempre informar onde pode usar (grupo/privado) e quem pode usar.
+- Em duvida de permissao, responder com orientacao conservadora.
+
+## Catalogo de Comandos
+
+### dado
+
+- id: game.dado
+- aliases: dice
+- enabled: true
+- categoria: jogos
+- descricao: Rola um dado com numero de lados opcional.
+- permissao_necessaria: usuario comum
+- version: 1.0.0
+- stability: stable
+- deprecated: nao
+- risk_level: low
+- local_de_uso:
+- privado
+- grupo
+- metodos_de_uso:
+- <prefix>dado
+- <prefix>dado 20
+- <prefix>dice 100
+- mensagens_uso (variantes):
+- default:
+- Formato de uso:
+- <prefix>dado
+- <prefix>dado <lados (2-1000)>
+- <prefix>dice <lados (2-1000)>
+- subcomandos:
+- (nenhum)
+- argumentos:
+- lados | tipo: integer | opcional | validacao: 2 a 1000 | default: null | posicao: 0
+- pre_condicoes:
+- requer_grupo: nao
+- requer_admin: nao
+- requer_admin_principal: nao
+- requer_google_login: sim
+- requer_nsfw: nao
+- requer_midia: nao
+- requer_mensagem_respondida: nao
+- rate_limit:
+- max: null
+- janela_ms: null
+- escopo: sem_rate_limit_explicito
+- acesso:
+- somente_premium: nao
+- planos_permitidos: comum, premium
+- limite_uso_por_plano:
+- comum: max=20, janela_ms=300000, escopo=usuario
+- premium: max=75, janela_ms=300000, escopo=usuario
+- informacoes_coletadas:
+- identificador do chat (remoteJid)
+- identificador do remetente (senderJid)
+- texto do comando e argumentos
+- contexto da mensagem (citacao e mencoes, quando existir)
+- numero de lados informado no argumento (quando houver)
+- dependencias_externas:
+- (nenhum)
+- efeitos_colaterais:
+- gera número aleatório
+- envia resultado no chat
+- respostas_padrao:
+- success: Comando executado com sucesso.
+- usage_error: Formato de uso inválido. Consulte metodos_de_uso.
+- permission_error: Permissão insuficiente para executar este comando.
+- sucesso: Comando executado com sucesso.
+- erro_uso: Formato de uso inválido. Consulte metodos_de_uso.
+- erro_permissao: Permissão insuficiente para executar este comando.
+- mensagens_sistema:
+- (nao informado)
+- limites_operacionais:
+- (nao informado)
+- opcoes:
+- toggle_on_off_status.type: toggle
+- toggle_on_off_status.allowed_actions: on, off, status
+- toggle_on_off_status.action_argument: acao
+- add_remove_list.type: list_management
+- add_remove_list.allowed_actions: add, remove, list
+- add_remove_list.action_argument: acao
+- approve_reject.type: moderation_decision
+- approve_reject.allowed_actions: approve, reject
+- approve_reject.action_argument: acao
+- approve_reject.requires_targets: true
+- set_status_reset.type: configuration_window
+- set_status_reset.allowed_actions: set, status, reset
+- set_status_reset.action_argument: valor
+- observabilidade:
+- event_name: command.executed
+- analytics_event: whatsapp_command_dado
+- tags_log: whatsapp, command, gameModule, dado
+- nivel_log: info
+- privacidade:
+- dados_sensiveis:
+- chat_identifier
+- sender_identifier
+- command_content
+- retencao: standard_app_logs
+- base_legal: service_execution_and_legitimate_interest
+- docs:
+- summary: Rola um dado com numero de lados opcional.
+- usage_examples: <prefix>dado, <prefix>dado 20, <prefix>dice 100
+- usage_variants.default: Formato de uso:, <prefix>dado, <prefix>dado <lados (2-1000)>, <prefix>dice <lados (2-1000)>
+- behavior:
+- type: argument_driven
+- allowed_actions: (nenhum)
+- limits:
+- usage_description: lados entre 2 e 1000
+- rate_limit.max: null
+- rate_limit.janela_ms: null
+- rate_limit.escopo: sem_rate_limit_explicito
+- access.somente_premium: false
+- access.planos_permitidos: comum, premium
+- plan_limits.comum.max: 20
+- plan_limits.comum.janela_ms: 300000
+- plan_limits.comum.escopo: usuario
+- plan_limits.premium.max: 75
+- plan_limits.premium.janela_ms: 300000
+- plan_limits.premium.escopo: usuario
+- discovery:
+- keywords: dado, dice, jogos, privado, grupo
+- faq_queries: como usar dado, o que faz dado, comando dado
+- user_phrasings: quero usar dado, me ajuda com dado, rola um dado com
+- suggestion_priority: 100
+- handler:
+- file: diceCommand.js
+- method: handleDiceCommand
+- command_case: dado

package/app/modules/gameModule/commandConfig.json

@@ -0,0 +1,366 @@
+{
+  "schema_version": "2.0.0",
+  "module": "gameModule",
+  "enabled": true,
+  "source_files": ["diceCommand.js"],
+  "defaults": {
+    "inheritance_mode": "deep_merge_with_command_overrides",
+    "compatibility_mode": "legacy_and_v2_fields",
+    "legacy_field_aliases": {
+      "descricao": "description",
+      "metodos_de_uso": "usage",
+      "permissao_necessaria": "permission",
+      "local_de_uso": "contexts",
+      "informacoes_coletadas": "collected_data",
+      "pre_condicoes": "requirements",
+      "dependencias_externas": "dependencies",
+      "efeitos_colaterais": "side_effects",
+      "observabilidade": "observability",
+      "privacidade": "privacy",
+      "limite_uso_por_plano": "plan_limits",
+      "argumentos": "arguments",
+      "acesso": "access"
+    },
+    "command": {
+      "enabled": true,
+      "category": "jogos",
+      "version": "1.0.0",
+      "stability": "stable",
+      "deprecated": false,
+      "replaced_by": null,
+      "risk_level": "medium"
+    },
+    "requirements": {
+      "require_group": false,
+      "require_group_admin": false,
+      "require_bot_owner": false,
+      "require_google_login": true,
+      "require_nsfw_enabled": false,
+      "require_media": false,
+      "require_reply_message": false,
+      "legacy": {
+        "requer_grupo": false,
+        "requer_admin": false,
+        "requer_admin_principal": false,
+        "requer_google_login": true,
+        "requer_nsfw": false,
+        "requer_midia": false,
+        "requer_mensagem_respondida": false
+      }
+    },
+    "pre_condicoes": {
+      "requer_grupo": false,
+      "requer_admin": false,
+      "requer_admin_principal": false,
+      "requer_google_login": true,
+      "requer_nsfw": false,
+      "requer_midia": false,
+      "requer_mensagem_respondida": false
+    },
+    "rate_limit": {
+      "max": null,
+      "janela_ms": null,
+      "escopo": "sem_rate_limit_explicito"
+    },
+    "dependencies": [],
+    "dependencias_externas": [],
+    "responses": {
+      "success": "Comando executado com sucesso.",
+      "usage_error": "Formato de uso inválido. Consulte metodos_de_uso.",
+      "permission_error": "Permissão insuficiente para executar este comando."
+    },
+    "respostas_padrao": {
+      "sucesso": "Comando executado com sucesso.",
+      "erro_uso": "Formato de uso inválido. Consulte metodos_de_uso.",
+      "erro_permissao": "Permissão insuficiente para executar este comando."
+    },
+    "observability": {
+      "event_name": "command.executed",
+      "log_level": "info",
+      "tags": ["whatsapp", "command", "gameModule"]
+    },
+    "privacy": {
+      "data_categories": ["chat_identifier", "sender_identifier", "command_content"],
+      "retention_policy": "standard_app_logs",
+      "legal_basis": "service_execution_and_legitimate_interest"
+    },
+    "access": {
+      "premium_only": false,
+      "allowed_plans": ["comum", "premium"]
+    },
+    "acesso": {
+      "somente_premium": false,
+      "planos_permitidos": ["comum", "premium"]
+    },
+    "plan_limits": {
+      "comum": {
+        "max": 20,
+        "janela_ms": 300000,
+        "escopo": "usuario"
+      },
+      "premium": {
+        "max": 75,
+        "janela_ms": 300000,
+        "escopo": "usuario"
+      }
+    },
+    "limite_uso_por_plano": {
+      "comum": {
+        "max": 20,
+        "janela_ms": 300000,
+        "escopo": "usuario"
+      },
+      "premium": {
+        "max": 75,
+        "janela_ms": 300000,
+        "escopo": "usuario"
+      }
+    },
+    "behavior_templates": {
+      "toggle_on_off_status": {
+        "type": "toggle",
+        "allowed_actions": ["on", "off", "status"],
+        "action_argument": "acao"
+      },
+      "add_remove_list": {
+        "type": "list_management",
+        "allowed_actions": ["add", "remove", "list"],
+        "action_argument": "acao"
+      },
+      "approve_reject": {
+        "type": "moderation_decision",
+        "allowed_actions": ["approve", "reject"],
+        "action_argument": "acao",
+        "requires_targets": true
+      },
+      "set_status_reset": {
+        "type": "configuration_window",
+        "allowed_actions": ["set", "status", "reset"],
+        "action_argument": "valor"
+      }
+    }
+  },
+  "commands": [
+    {
+      "name": "dado",
+      "aliases": ["dice"],
+      "descricao": "Rola um dado com numero de lados opcional.",
+      "metodos_de_uso": ["<prefix>dado", "<prefix>dado 20", "<prefix>dice 100"],
+      "permissao_necessaria": "usuario comum",
+      "limite_de_uso": "lados entre 2 e 1000",
+      "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)", "numero de lados informado no argumento (quando houver)"],
+      "enabled": true,
+      "categoria": "jogos",
+      "subcomandos": [],
+      "argumentos": [
+        {
+          "nome": "lados",
+          "tipo": "integer",
+          "obrigatorio": false,
+          "validacao": "2 a 1000",
+          "default": 6
+        }
+      ],
+      "pre_condicoes": {
+        "requer_grupo": false,
+        "requer_admin": false,
+        "requer_admin_principal": false,
+        "requer_google_login": true,
+        "requer_nsfw": false,
+        "requer_midia": false,
+        "requer_mensagem_respondida": false
+      },
+      "rate_limit": {
+        "max": null,
+        "janela_ms": null,
+        "escopo": "sem_rate_limit_explicito"
+      },
+      "dependencias_externas": [],
+      "efeitos_colaterais": ["gera número aleatório", "envia resultado no chat"],
+      "respostas_padrao": {
+        "sucesso": "Comando executado com sucesso.",
+        "erro_uso": "Formato de uso inválido. Consulte metodos_de_uso.",
+        "erro_permissao": "Permissão insuficiente para executar este comando."
+      },
+      "observabilidade": {
+        "evento_analytics": "whatsapp_command_dado",
+        "tags_log": ["whatsapp", "command", "gameModule", "dado"],
+        "nivel_log": "info"
+      },
+      "privacidade": {
+        "dados_sensiveis": ["identificador do chat", "identificador do remetente", "conteudo textual do comando"],
+        "retencao": "conforme políticas de logs, banco de dados e arquivos temporários da aplicação",
+        "base_legal": "execução do serviço solicitado e legítimo interesse operacional"
+      },
+      "capability_keywords": ["dado", "dice", "jogos", "privado", "grupo"],
+      "faq_patterns": ["como usar dado", "o que faz dado", "comando dado"],
+      "user_phrasings": ["quero usar dado", "me ajuda com dado", "rola um dado com"],
+      "suggestion_priority": 100,
+      "acesso": {
+        "somente_premium": false,
+        "planos_permitidos": ["comum", "premium"]
+      },
+      "limite_uso_por_plano": {
+        "comum": {
+          "max": 20,
+          "janela_ms": 300000,
+          "escopo": "usuario"
+        },
+        "premium": {
+          "max": 75,
+          "janela_ms": 300000,
+          "escopo": "usuario"
+        }
+      },
+      "mensagens_uso": {
+        "default": ["Formato de uso:", "<prefix>dado", "<prefix>dado <lados (2-1000)>", "<prefix>dice <lados (2-1000)>"]
+      },
+      "id": "game.dado",
+      "description": "Rola um dado com numero de lados opcional.",
+      "usage": ["<prefix>dado", "<prefix>dado 20", "<prefix>dice 100"],
+      "docs": {
+        "summary": "Rola um dado com numero de lados opcional.",
+        "usage_examples": ["<prefix>dado", "<prefix>dado 20", "<prefix>dice 100"],
+        "usage_variants": {
+          "default": ["Formato de uso:", "<prefix>dado", "<prefix>dado <lados (2-1000)>", "<prefix>dice <lados (2-1000)>"]
+        }
+      },
+      "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)", "numero de lados informado no argumento (quando houver)"],
+      "requirements": {
+        "require_group": false,
+        "require_group_admin": false,
+        "require_bot_owner": false,
+        "require_google_login": true,
+        "require_nsfw_enabled": false,
+        "require_media": false,
+        "require_reply_message": false,
+        "legacy": {
+          "requer_grupo": false,
+          "requer_admin": false,
+          "requer_admin_principal": false,
+          "requer_google_login": true,
+          "requer_nsfw": false,
+          "requer_midia": false,
+          "requer_mensagem_respondida": false
+        }
+      },
+      "arguments": [
+        {
+          "name": "lados",
+          "type": "integer",
+          "required": false,
+          "default": 6,
+          "enum": null,
+          "description": "2 a 1000",
+          "position": 0,
+          "accepts_mentions": false,
+          "accepts_reply_target": false,
+          "greedy": false,
+          "validation": "2 a 1000"
+        }
+      ],
+      "behavior": {
+        "type": "argument_driven",
+        "allowed_actions": []
+      },
+      "limits": {
+        "usage_description": "lados entre 2 e 1000",
+        "rate_limit": {
+          "max": null,
+          "janela_ms": null,
+          "escopo": "sem_rate_limit_explicito"
+        },
+        "access": {
+          "somente_premium": false,
+          "planos_permitidos": ["comum", "premium"]
+        },
+        "plan_limits": {
+          "comum": {
+            "max": 20,
+            "janela_ms": 300000,
+            "escopo": "usuario"
+          },
+          "premium": {
+            "max": 75,
+            "janela_ms": 300000,
+            "escopo": "usuario"
+          }
+        }
+      },
+      "dependencies": [],
+      "side_effects": ["gera número aleatório", "envia resultado no chat"],
+      "observability": {
+        "event_name": "command.executed",
+        "event_key": "game.dado",
+        "analytics_event": "whatsapp_command_dado",
+        "log_level": "info",
+        "tags": ["whatsapp", "command", "gameModule", "dado"],
+        "legacy": {
+          "evento_analytics": "whatsapp_command_dado",
+          "tags_log": ["whatsapp", "command", "gameModule", "dado"],
+          "nivel_log": "info"
+        }
+      },
+      "privacy": {
+        "data_categories": ["chat_identifier", "sender_identifier", "command_content"],
+        "sensitive_fields": ["remoteJid", "senderJid", "text", "args"],
+        "retention_policy": "standard_app_logs",
+        "retention_notes": "conforme políticas de logs, banco de dados e arquivos temporários da aplicação",
+        "legal_basis": "service_execution_and_legitimate_interest",
+        "legal_basis_notes": "execução do serviço solicitado e legítimo interesse operacional",
+        "legacy": {
+          "dados_sensiveis": ["identificador do chat", "identificador do remetente", "conteudo textual do comando"],
+          "retencao": "conforme políticas de logs, banco de dados e arquivos temporários da aplicação",
+          "base_legal": "execução do serviço solicitado e legítimo interesse operacional"
+        }
+      },
+      "discovery": {
+        "keywords": ["dado", "dice", "jogos", "privado", "grupo"],
+        "faq_queries": ["como usar dado", "o que faz dado", "comando dado"],
+        "user_phrasings": ["quero usar dado", "me ajuda com dado", "rola um dado com"],
+        "suggestion_priority": 100
+      },
+      "access": {
+        "premium_only": false,
+        "allowed_plans": ["comum", "premium"],
+        "legacy": {
+          "somente_premium": false,
+          "planos_permitidos": ["comum", "premium"]
+        }
+      },
+      "plan_limits": {
+        "comum": {
+          "max": 20,
+          "janela_ms": 300000,
+          "escopo": "usuario"
+        },
+        "premium": {
+          "max": 75,
+          "janela_ms": 300000,
+          "escopo": "usuario"
+        }
+      },
+      "version": "1.0.0",
+      "stability": "stable",
+      "deprecated": false,
+      "replaced_by": null,
+      "risk_level": "low",
+      "handler": {
+        "file": "diceCommand.js",
+        "method": "handleDiceCommand",
+        "command_case": "dado"
+      },
+      "compatibility": {
+        "schema": "legacy_v1_and_v2",
+        "legacy_name": "dado",
+        "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"]
+      }
+    }
+  ],
+  "textos": {
+    "usage_header": ""
+  }
+}

package/app/modules/gameModule/diceCommand.js

@@ -0,0 +1,42 @@
+import logger from '#logger';
+import { sendAndStore } from '../../services/messaging/messagePersistenceService.js';
+import { getGameUsageText } from './gameConfigRuntime.js';
+
+const DICE_FACES = ['⚀', '⚁', '⚂', '⚃', '⚄', '⚅'];
+const MAX_SIDES = 1000;
+
+const parseSidesArgument = (rawArg) => {
+  if (!rawArg) return 6;
+  const parsed = Number.parseInt(rawArg, 10);
+  if (!Number.isFinite(parsed)) return null;
+  if (parsed < 2 || parsed > MAX_SIDES) return null;
+  return parsed;
+};
+
+const rollDice = (sides) => Math.floor(Math.random() * sides) + 1;
+
+const buildUsageText = (commandPrefix) => getGameUsageText('dado', { commandPrefix }) || [`Formato de uso:`, `${commandPrefix}dado`, `${commandPrefix}dado <lados (2-${MAX_SIDES})>`, `${commandPrefix}dice <lados (2-${MAX_SIDES})>`].join('\n');
+
+export async function handleDiceCommand({ sock, remoteJid, messageInfo, expirationMessage, args = [], commandPrefix = '/' }) {
+  const sides = parseSidesArgument(args[0]);
+  if (sides === null) {
+    await sendAndStore(sock, remoteJid, { text: `❌ Número de lados inválido.\n\n${buildUsageText(commandPrefix)}` }, { quoted: messageInfo, ephemeralExpiration: expirationMessage });
+    return;
+  }
+
+  const result = rollDice(sides);
+  const face = sides === 6 ? DICE_FACES[result - 1] : '🎲';
+  const messageText = sides === 6 ? `🎲 Você rolou o dado e caiu em *${result}* ${face}` : `🎲 Você rolou um dado de *${sides}* lados e caiu em *${result}*`;
+
+  try {
+    await sendAndStore(sock, remoteJid, { text: messageText }, { quoted: messageInfo, ephemeralExpiration: expirationMessage });
+  } catch (error) {
+    logger.error('handleDiceCommand: erro ao enviar resultado do dado.', {
+      error: error.message,
+      remoteJid,
+      sides,
+      result,
+    });
+    await sendAndStore(sock, remoteJid, { text: '❌ Não foi possível rolar o dado agora. Tente novamente.' }, { quoted: messageInfo, ephemeralExpiration: expirationMessage });
+  }
+}