Pular para o conteúdo principal

Guia do SDK de Configurações (Dashboard)

O pacote @botgate/sdk é a ferramenta oficial para integrar as configurações do seu bot definidas no Dashboard do BotGate diretamente no seu código.

Diferente do Reporter (que envia dados), este SDK foca em receber e gerenciar as preferências que seus usuários (donos de servidores) definiram para o seu bot, como prefixos personalizados, canais de log, módulos de boas-vindas e muito mais.

📦 Instalação​

No diretório do seu bot, instale o pacote via npm:

npm install @botgate/sdk

🚀 Inicialização​

Para começar, instale o SDK e inicialize-o com a sua apiKey. Recomendamos fazer isso uma única vez na inicialização do seu bot.

import { BotGateSDK } from "@botgate/sdk";

const botgate = new BotGateSDK({
  apiKey: "SUA_API_KEY_AQUI",
  cacheTtl: 300, // (Opcional) Tempo de cache em segundos. Padrão: 5 minutos.
  debug: false, // (Opcional) Ativa logs de monitoramento no console.
});

🛠️ Como utilizar​

O método principal é o getGuildSettings(guildId), que retorna um objeto contendo todas as configurações daquele servidor específico.

Exemplo: Prefixo Dinâmico​

client.on("messageCreate", async (message) => {
  if (message.author.bot || !message.guild) return;

  // Busca as configurações do servidor direto do BotGate
  // O SDK gerencia o cache automaticamente para você
  const settings = await botgate.getGuildSettings(message.guild.id);

  // Usa o prefixo configurado ou o padrão '!'
  const prefix = settings.prefix || "!";

  if (!message.content.startsWith(prefix)) return;

  // Lógica dos seus comandos...
});

📑 Módulos e Campos Suportados​

O BotGate Dashboard oferece um esquema fixo de módulos. Abaixo estão todos os campos disponíveis no objeto settings retornado pelo SDK:

⚙️ Geral (general)​

Configurações básicas de identidade e comportamento.

  • prefix: (String) O prefixo de comandos definido pelo servidor.

👋 Boas-Vindas (welcome)​

Mensagens enviadas quando novos membros entram no servidor.

  • welcome_enabled: (Boolean) Indica se o módulo está ativo.
  • welcome_channel_id: (String) ID do canal de texto para as mensagens.
  • welcome_message: (Object) Objeto de mensagem/embed configurado no Dashboard.

🚪 Saída (leave)​

Mensagens enviadas quando membros saem do servidor.

  • leave_enabled: (Boolean) Indica se o módulo está ativo.
  • leave_channel_id: (String) ID do canal de texto para as mensagens.
  • leave_message: (Object) Objeto de mensagem/embed configurado no Dashboard.

📜 Logs de Auditoria (logs)​

Sistema de monitoramento de eventos. Possui uma configuração global e submódulos específicos.

Configuração Global:

  • logs_enabled: (Boolean) Ativador geral do sistema de logs.
  • logs_channel_id: (String) Canal único onde todos os logs habilitados serão enviados.

Submódulos de Eventos: Cada submódulo possui um campo _enabled (Boolean) e um campo _message (Objeto de Embed).

  • ban_log: Logs de banimentos.
  • kick_log: Logs de expulsões.
  • unban_log: Logs de desbanimentos.
  • message_delete_log: Logs de mensagens apagadas.
  • message_edit_log: Logs de mensagens editadas.
  • role_add_log: Logs de cargos adicionados a membros.
  • role_remove_log: Logs de cargos removidos de membros.

💡 Exemplos de Integração de Logs​

Abaixo estão os exemplos de como implementar cada evento de log utilizando o SDK.

Dica: O campo _message retornado pelo Dashboard já é um objeto compatível com EmbedBuilder do Discord.js.

🔨 Banimentos e Desbanimentos​

// Logs de Banimento (GuildBanAdd)
client.on("guildBanAdd", async (ban) => {
  const settings = await botgate.getGuildSettings(ban.guild.id);
  if (settings.logs_enabled && settings.ban_log_enabled) {
    const channel = ban.guild.channels.cache.get(settings.logs_channel_id);
    if (channel) await channel.send({ embeds: [settings.ban_log_message] });
  }
});

// Logs de Desbanimento (GuildBanRemove)
client.on("guildBanRemove", async (ban) => {
  const settings = await botgate.getGuildSettings(ban.guild.id);
  if (settings.logs_enabled && settings.unban_log_enabled) {
    const channel = ban.guild.channels.cache.get(settings.logs_channel_id);
    if (channel) await channel.send({ embeds: [settings.unban_log_message] });
  }
});

🗑️ Mensagens (Excluídas e Editadas)​

// Mensagem Excluída (MessageDelete)
client.on("messageDelete", async (message) => {
  if (message.author?.bot || !message.guild) return;
  const settings = await botgate.getGuildSettings(message.guild.id);

  if (settings.logs_enabled && settings.message_delete_log_enabled) {
    const channel = message.guild.channels.cache.get(settings.logs_channel_id);
    if (channel)
      await channel.send({ embeds: [settings.message_delete_log_message] });
  }
});

// Mensagem Editada (MessageUpdate)
client.on("messageUpdate", async (oldMsg, newMsg) => {
  if (newMsg.author?.bot || !newMsg.guild || oldMsg.content === newMsg.content)
    return;
  const settings = await botgate.getGuildSettings(newMsg.guild.id);

  if (settings.logs_enabled && settings.message_edit_log_enabled) {
    const channel = newMsg.guild.channels.cache.get(settings.logs_channel_id);
    if (channel)
      await channel.send({ embeds: [settings.message_edit_log_message] });
  }
});

🏷️ Cargos e Membros​

// Mudanças de Cargos (GuildMemberUpdate)
client.on("guildMemberUpdate", async (oldMember, newMember) => {
  const settings = await botgate.getGuildSettings(newMember.guild.id);
  if (!settings.logs_enabled) return;

  const channel = newMember.guild.channels.cache.get(settings.logs_channel_id);
  if (!channel) return;

  // Detectar cargos adicionados
  const addedRoles = newMember.roles.cache.filter(
    (r) => !oldMember.roles.cache.has(r.id),
  );
  if (addedRoles.size > 0 && settings.role_add_log_enabled) {
    await channel.send({ embeds: [settings.role_add_log_message] });
  }

  // Detectar cargos removidos
  const removedRoles = oldMember.roles.cache.filter(
    (r) => !newMember.roles.cache.has(r.id),
  );
  if (removedRoles.size > 0 && settings.role_remove_log_enabled) {
    await channel.send({ embeds: [settings.role_remove_log_message] });
  }
});

🧠 Gerenciamento de Cache​

Para garantir a melhor performance do seu bot e não sobrecarregar a API, o SDK possui um sistema de cache inteligente:

  1. Auto-Cache: Toda busca via getGuildSettings fica salva em memória pelo tempo definido no cacheTtl.
  2. Eficiência: Se mil mensagens chegarem no mesmo segundo, apenas a primeira consultará a API.
  3. Forçar Refresh: Use botgate.getGuildSettings(guildId, true) para ignorar o cache.
  4. Limpeza Manual:
    • botgate.clearCache(guildId) (Específico)
    • botgate.clearCache() (Global)

🛡️ Resiliência​

O SDK foi construído para ser "silencioso". Em caso de falha na API ou timeout, ele retornará um objeto vazio {} em vez de quebrar a execução do seu bot, garantindo estabilidade ao seu projeto.