devbotsvotes/README.md

A powerful and feature-rich package for monitoring votes and retrieving information for bots listed on the dev-botlist platform.

Here’s a polished `README.md` tailored for your NPM package with examples and usage instructions:

---


# DevBotsVotes

**DevBotsVotes** is a powerful package that simplifies vote tracking for Discord bots on your bot list platform. It allows you to monitor votes, check user voting status, fetch recent votes, and more with ease.

## Features

- Track new votes in real-time.
- Fetch all votes for your bot.
- Check if a user has voted recently and get the time remaining.
- Get the top voters for your bot.
- Simple integration with Discord bots.
- Built-in support for role assignment for voters.

## Installation

Install the package using npm:

```bash
npm install devbotsvotes
```

## Usage

### Basic Setup

Here’s how to use the `DevBotsVotes` package to track votes for your bot:

```javascript
const VoteNotifier = require('devbotsvotes');

const BOT_ID = 'YOUR_BOT_ID';
const API_TOKEN = 'YOUR_API_TOKEN';

const notifier = new VoteNotifier({ botID: BOT_ID, token: API_TOKEN });

// Start vote monitoring
notifier.start();

// Listen for new votes
notifier.on('vote', (vote) => {
    console.log('New vote detected:', vote);
});

// Stop monitoring when needed
// notifier.stop();
```

### Check If a User Has Voted

You can check if a specific user has voted recently:

```javascript
const userID = 'USER_ID_TO_CHECK';

notifier.hasUserVoted(userID).then((result) => {
    if (result.hasVoted) {
        console.log(`User ${userID} has voted! Time remaining: ${result.timeRemaining}`);
    } else {
        console.log(`User ${userID} has not voted.`);
    }
});
```

### Fetch All Votes

Retrieve all votes for your bot:

```javascript
notifier.getAllVotes().then((votes) => {
    console.log(`Total votes: ${votes.length}`);
    console.log(votes);
});
```

### Fetch Recent Votes

Get votes received in the last specified time period (in milliseconds):

```javascript
const last12Hours = 12 * 60 * 60 * 1000;

notifier.getRecentVotes(last12Hours).then((recentVotes) => {
    console.log('Recent votes:', recentVotes);
});
```

### Fetch Top Voters

Retrieve the top voters for your bot:

```javascript
notifier.getTopVotes().then((topVoters) => {
    console.log('Top voters:', topVoters);
});
```

## Example with Discord.js

Here’s how you can integrate `DevBotsVotes` with a Discord bot to notify a channel when a new vote is received:

```javascript
const { Client, GatewayIntentBits, EmbedBuilder } = require('discord.js');
const VoteNotifier = require('devbotsvotes');

const BOT_ID = 'YOUR_BOT_ID';
const API_TOKEN = 'YOUR_API_TOKEN';
const VOTE_CHANNEL_ID = 'YOUR_CHANNEL_ID';

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

const notifier = new VoteNotifier({ botID: BOT_ID, token: API_TOKEN });

client.once('ready', () => {
    console.log(`Logged in as ${client.user.tag}!`);

    notifier.start();

    notifier.on('vote', async (vote) => {
        const voteChannel = client.channels.cache.get(VOTE_CHANNEL_ID);
        if (voteChannel) {
            const embed = new EmbedBuilder()
                .setTitle('🎉 New Vote Received!')
                .setColor(0x00ff00)
                .setDescription(
                    `👤 **User:** <@${vote.userID}>\n` +
                    `📅 **Date:** ${new Date(vote.voteDate).toLocaleString()}\n` +
                    `🤖 **Bot ID:** \`${vote.botID}\``
                )
                .setFooter({ text: 'Thank you for voting!' })
                .setTimestamp();

            await voteChannel.send({ embeds: [embed] });
        } else {
            console.error('Vote channel not found.');
        }
    });
});

client.login('YOUR_DISCORD_BOT_TOKEN');
```

## API Reference

### `new VoteNotifier(options)`

- **options.botID** (required): The bot's ID.
- **options.token** (required): API token for authentication.
- **options.pollingInterval** (optional): Interval for checking new votes (default: `30000` ms).
- **options.autoRetry** (optional): Automatically retry on API errors (default: `true`).

### Methods

#### `start()`
Starts monitoring votes.

#### `stop()`
Stops monitoring votes.

#### `hasUserVoted(userID)`
Checks if a user has voted recently.
- **Returns**: A promise that resolves to an object:
  ```json
  {
      "hasVoted": true,
      "timeRemaining": "11h 58m 32s",
      "voteDate": "2025-01-21T07:41:13.274Z"
  }
  ```

#### `getAllVotes()`
Fetches all votes for the bot.

#### `getRecentVotes(timeRange)`
Fetches votes within a specific time range (in milliseconds).

#### `getTopVotes()`
Fetches the top voters for the bot.

---


## License

This project is licensed under the [SimPL-2.0 License](https://opensource.org/license/simpl-2-0-html).

---


Feel free to reach out or open an issue for questions or improvements! 🚀