Pular para o conteúdo principal

Guia do Pacote Javascript

O pacote @botgate/botgate-stats-reporter é a forma oficial e mais simples de integrar seu bot com o ecossistema do BotGate. Ele gerencia automaticamente o envio de estatísticas, sincroniza seu Tier em tempo real e oferece métodos para consultar dados da plataforma diretamente do seu código.

📦 Instalação​

Abra o terminal no diretório do seu projeto e execute:

npm install @botgate/botgate-stats-reporter

🚀 Como utilizar​

A integração é feita de forma simples e reativa. Basta instanciar a classe BotGateReporter e iniciar o monitoramento.

Exemplo com Discord.js​

import { Client, GatewayIntentBits } from "discord.js";
import { BotGateReporter } from "@botgate/stats-reporter";

const client = new Client({
  intents: [GatewayIntentBits.Guilds],
});

// Instanciando o reporter
const reporter = new BotGateReporter({
  botId: "SEU_BOT_ID",
  apiKey: "SUA_API_KEY",
  lang: "pt-BR", // Suporta "pt-BR" ou "en-US"
  enableWebhooks: true, // Ativa o servidor interno para receber eventos (votos)
  debug: true, // Opcional: true para logs detalhados, false para logs normais
});

client.once("ready", () => {
  console.log(`Bot logado como ${client.user.tag}`);

  // Inicia o loop automático e o monitoramento de Heartbeats (para Business)
  reporter.start(client);
});

client.login(process.env.DISCORD_TOKEN);

⚙️ Configuração​

Ao instanciar o BotGateReporter, você pode passar as seguintes opções:

ParâmetroTipoObrigatórioDescrição
botIdstringSimID do seu bot no Discord.
apiKeystringSimSua chave de API obtida no painel do BotGate.
langstringNãoIdioma dos logs e respostas da API (pt-BR, en-US). Padrão: "pt-BR".
enableWebhooksbooleanNãoAtiva o servidor interno para receber eventos (votos, etc). Padrão: false.
debugbooleanNãoSe true, exibe logs detalhados no console. Padrão: false.

🛠️ Métodos do Reporter​

Além do monitoramento automático, a biblioteca expõe métodos poderosos para você usar no seu bot:

Monitoramento de Ciclo​

  • reporter.start(client): Inicia o envio automático de estatísticas e heartbeats.
  • reporter.stop(): Para todos os timers e processos em segundo plano.

Consultas de Dados (API v1)​

Todos os métodos abaixo retornam uma Promise<BotGateResponse>.

MétodoDescrição
getBotInfo()Retorna todos os dados do bot, incluindo plano (Tier) e stats.
getBotVotes(botId, limit)Busca os últimos votos e totais (dia/semana/mês).
getApiUsage()Retorna o consumo atual da sua cota de API e pontos de reset.
getStatsHistory(botId, period)Retorna dados históricos de crescimento (daily, weekly, monthly).
getBotAnalytics()Retorna KPIs e tendências avançadas de uso.
sendHeartbeat()Força o envio de um sinal de vida (disponível apenas no plano Business).
handleShardMessage(msg)Processa mensagens IPC em bots com Sharding para emitir eventos de voto.

⚡ Eventos em Tempo Real (Webhooks)​

O @botgate/botgate-stats-reporter agora suporta eventos reativos. Isso permite que você execute código assim que um voto for detectado no BotGate, sem precisar fazer "polling" na API.

1. Configuração Automática (Recomendado)​

Ao ativar o autoConfig: true, o bot descobre seu próprio IP público e registra o endereço técnico de integração no BotGate automaticamente. Isso mantém seus alertas de erro no Discord intactos e ativa a integração de código em paralelo.

const reporter = new BotGateReporter({
  botId: "BOT_ID",
  apiKey: "API_KEY",
  lang: "pt-BR", // Opcional: "pt-BR" (padrão) ou "en-US"
  enableWebhooks: true, // Ativa o servidor interno para receber eventos (votos)
  debug: true, // Opcional: true para logs detalhados, false para logs normais
});

reporter.on("vote", (vote) => {
  console.log(`🎁 Recompensando ${vote.username} (${vote.user_id})`);
  // Lógica de cargos, moedas, etc aqui
});

2. Suporte a Sharding​

Se o seu bot usa ShardingManager, você deve centralizar o servidor de Webhook no arquivo principal (manager) e repassar para os shards.

No Shard (index.js):

const reporter = new BotGateReporter({
  botId: "BOT_ID",
  apiKey: "API_KEY",
  lang: "pt-BR",
  enableWebhooks: false, // Ativa o servidor interno para receber eventos (votos). OBS.: No sharding, é recomendado desativar o webhook no shard e ativar no manager.
});

// Escuta mensagens do Manager e repassa para a lib
process.on("message", (msg) => reporter.handleShardMessage(msg));

reporter.on("vote", (vote) => {
  // Executado em todos os shards simultaneamente
  client.users.send(vote.user_id, "Obrigado por votar! 💎");
});

🧠 Sincronização em Tempo Real​

Diferente de outros SDKs, o @botgate/stats-reporter é reativo e auto-ajustável. Ele monitora as respostas do servidor em cada requisição para garantir que o bot esteja sempre operando no limite máximo de performance do seu plano atual.

  • Upgrade Detectado (Hot Swap): Se você assinar um plano superior (ex: Premium ➔ Business), o servidor enviará os novos limites na resposta de sucesso (200 OK). O SDK detecta isso instantaneamente e acelera o intervalo de postagem (ex: de 5 min para 1 min) sem que você precise reiniciar o bot.
  • Downgrade e Slowdown: Caso o plano expire ou seja alterado para um inferior, o servidor retornará um erro 429 (Too Many Requests) informando o novo tempo de espera. O SDK captura esse erro, lê o novo intervalo e se reconfigura automaticamente para o ritmo mais lento, evitando "flood" de erros no seu console.
  • Grace Period (Tolerância): Implementamos uma margem de segurança de 5 segundos no servidor e no SDK. Isso evita que pequenas variações de milissegundos no cronômetro do Node.js ou latência de rede causem bloqueios por Rate Limit.
  • Gestão de Heartbeat: O monitoramento de uptime (sinal de vida) é ativado ou desativado em tempo real conforme as permissões do seu Tier, garantindo que o seu status no painel seja sempre preciso.

Próximos Passos​