topgg-vote-logger

A database-agnostic, Discord-bot-focused NPM package for tracking, logging, and rewarding Top.gg votes. It includes custom database integrations and premium Discord webhook log embeds.

Features

• Database Agnostic: Use any database (Postgres, MongoDB, MySQL, Prisma, Redis, etc.) by implementing a simple adapter interface.
• Built-in Supabase Adapter: Start immediately with Supabase out-of-the-box.
• Streak System: Tracks consecutive votes, automatically resetting streaks if more than 36 hours pass between votes.
• Discord Lookup Integration: Resolves current Discord username and avatar dynamically.
• Premium Discord Webhook Log: Sends customized, modern Discord embed logs to your log channel.

Installation

npm install topgg-vote-logger

Database Adapters

1. Default Supabase Setup

Initialize the logger with Supabase credentials:

import { TopGGVoteLogger } from 'topgg-vote-logger';

const logger = new TopGGVoteLogger({
  supabaseUrl: 'YOUR_SUPABASE_URL',
  supabaseKey: 'YOUR_SUPABASE_SERVICE_ROLE_KEY',
  topggWebhookSecret: 'YOUR_WEBHOOK_SECRET',
  discordBotToken: 'YOUR_DISCORD_BOT_TOKEN', // Optional
  discordWebhookUrl: 'YOUR_DISCORD_WEBHOOK_URL', // Optional
  botName: '@MyAwesomeBot', // Optional
  embedColor: 0xff477e, // Optional: Border color (hex integer)
  embedTitle: 'Vote Logged', // Optional: Custom embed title. Supports {username}, {userId}
  embedDescription: '**{username}** has supported the bot!' // Optional: Custom description. Supports {username}, {userId}, {streak}, {totalVotes}
});

Create the SQL schema in your Supabase SQL editor:

create table votes (
  id bigint generated by default as identity primary key,
  created_at timestamp with time zone default timezone('utc'::text, now()) not null,
  user_id text not null,
  bot_id text not null,
  is_weekend boolean not null default false,
  username text,
  avatar_url text,
  streak integer not null default 1,
  total_votes_at_time integer not null default 1
);

2. Custom Database Adapter (Prisma, MongoDB, MySQL, etc.)

To use any other database, implement the IDatabaseAdapter interface and pass it as dbAdapter. See the Database Adapters Guide for full instructions and examples.

import { TopGGVoteLogger } from 'topgg-vote-logger';

// Example: In-Memory Adapter
const myDatabaseAdapter = {
  async getVoteCount(userId) {
    // Return total votes count
  },

  async getLastVote(userId) {
    // Return last vote time and streak
  },

  async saveVote(record) {
    // Save vote record
  },

  async getLeaderboard(limit) {
    // Return monthly leaderboard
  }
};

const logger = new TopGGVoteLogger({
  dbAdapter: myDatabaseAdapter,
  topggWebhookSecret: 'YOUR_WEBHOOK_SECRET',
  discordWebhookUrl: 'YOUR_DISCORD_WEBHOOK_URL'
});

Quick Start (Express Webhook Endpoint)

See the Webhook Setup Guide for details on portal integration.

import express from 'express';

const app = express();
app.use(express.json());

app.post('/api/webhook', async (req, res) => {
  const auth = req.headers.authorization;

  // 1. Verify top.gg authorization header
  if (!logger.verifyWebhook(auth)) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  try {
    // 2. Process vote and log/save
    const result = await logger.handleWebhook(req.body);
    return res.status(200).json({ message: 'Success', result });
  } catch (error) {
    console.error('Webhook error:', error);
    return res.status(500).json({ error: 'Internal Server Error' });
  }
});

app.listen(3000);

Documentation

• Database Adapters Guide: Connect MongoDB, PostgreSQL, Prisma, etc.
• Webhook Setup Guide: Configure Top.gg portal routing.

License

MIT