discord-voice-tracker 1.0.0

package/readme.md

@@ -0,0 +1,662 @@
+# Discord Voice Tracker
+
+> 🎙️ A modern, production-ready voice activity tracking system for Discord bots with XP, leveling, and comprehensive statistics.
+
+[![npm version](https://img.shields.io/npm/v/discord-voice-tracker?style=flat-square)](https://www.npmjs.com/package/discord-voice-tracker)
+[![npm downloads](https://img.shields.io/npm/dt/discord-voice-tracker?style=flat-square)](https://www.npmjs.com/package/discord-voice-tracker)
+[![License](https://img.shields.io/npm/l/discord-voice-tracker?style=flat-square)](LICENSE)
+[![Node Version](https://img.shields.io/node/v/discord-voice-tracker?style=flat-square)](https://nodejs.org)
+
+---
+
+## ✨ Features
+
+- 🎯 **Voice Time Tracking** - Track total and per-channel voice activity
+- 💫 **XP & Leveling System** - Automatic XP gain and level progression  
+- 📊 **Statistics & Analytics** - Detailed user stats and session history
+- 🏆 **Leaderboards** - Rank users by voice time, XP, or level
+- ⚙️ **Highly Configurable** - Customize tracking behavior per guild
+- 💾 **Multiple Storage Options** - JSON (built-in) and MongoDB support
+- 🔒 **TypeScript Support** - Full type definitions included
+- 🚀 **Production Ready** - Optimized performance with caching
+- 📦 **Easy Integration** - Simple setup with sensible defaults
+
+---
+
+## 📋 Table of Contents
+
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Slash Commands](#-slash-commands)
+- [Configuration](#-configuration)
+- [Events](#-events)
+- [API Reference](#-api-reference)
+- [Storage Options](#-storage-options)
+- [Examples](#-examples)
+- [Troubleshooting](#-troubleshooting)
+
+---
+
+## 📦 Installation
+
+### Prerequisites
+
+Before installing, make sure you have:
+- **Node.js 18.0.0 or higher** - [Download here](https://nodejs.org/)
+- **A Discord Bot** - [Create one here](https://discord.com/developers/applications)
+
+### Step 1: Install the Package
+
+```bash
+npm install discord-voice-tracker discord.js
+```
+
+**What this does:**
+- Installs `discord-voice-tracker` (this package)
+- Installs `discord.js` (required peer dependency)
+
+### Step 2: (Optional) Install MongoDB
+
+If you want to use MongoDB instead of JSON storage:
+
+```bash
+npm install mongodb
+```
+
+**When to use MongoDB:**
+- ✅ Large servers (1000+ members)
+- ✅ Multiple guilds
+- ✅ Production environments
+- ❌ Small bots or testing (use JSON instead)
+
+---
+
+## 🚀 Quick Start
+
+### Basic Setup (5 minutes)
+
+Create a file called `bot.js`:
+
+```javascript
+// Import required modules
+const { Client, GatewayIntentBits } = require('discord.js');
+const { VoiceManager, JSONStorage } = require('discord-voice-tracker');
+
+// Create Discord client with required intents
+const client = new Client({
+  intents: [
+    GatewayIntentBits.Guilds,           // Required: Access to guilds
+    GatewayIntentBits.GuildVoiceStates, // Required: Voice state updates
+  ],
+});
+
+// Create storage (saves data to ./data folder)
+const storage = new JSONStorage('./data');
+
+// Create voice manager
+const voiceManager = new VoiceManager(client, {
+  storage,                    // Where to save data
+  checkInterval: 5000,        // Check voice activity every 5 seconds
+  debug: true,                // Enable debug logs (disable in production)
+  defaultConfig: {
+    trackBots: false,         // Don't track bot users
+    trackAllChannels: true,   // Track all voice channels
+    xpPerCheck: 5,           // Give 5 XP every 5 seconds in voice
+  },
+});
+
+// Listen for level ups
+voiceManager.on('levelUp', (userData, oldLevel, newLevel) => {
+  console.log(`🎉 User ${userData.userId} leveled up to ${newLevel}!`);
+});
+
+// Initialize when bot is ready
+client.once('ready', async () => {
+  console.log(`✅ Logged in as ${client.user.tag}`);
+  
+  // Initialize voice manager
+  await voiceManager.init();
+  console.log('✅ Voice tracking active!');
+});
+
+// Login with your bot token
+client.login('YOUR_BOT_TOKEN_HERE');
+```
+
+### Run Your Bot
+
+```bash
+node bot.js
+```
+
+**You should see:**
+```
+✅ Logged in as YourBot#1234
+[VoiceTracker DEBUG] Initializing VoiceManager...
+[VoiceTracker DEBUG] Storage initialized
+[VoiceTracker DEBUG] Tracking started with 5000ms interval
+✅ Voice tracking active!
+```
+
+### Test It
+
+1. **Join a voice channel** in your Discord server
+2. **Wait 5-10 seconds**
+3. **Check the console** - you should see tracking activity
+4. **Leave the voice channel**
+5. **Check `data/guilds.json`** - you'll see your data saved!
+
+---
+
+## 💬 Slash Commands
+
+Want users to check their stats? Add these commands to your bot!
+
+### Example: `/stats` Command
+
+```javascript
+const { SlashCommandBuilder, EmbedBuilder } = require('discord.js');
+const { XPCalculator } = require('discord-voice-tracker');
+
+const calculator = new XPCalculator();
+
+// Register the command
+const statsCommand = new SlashCommandBuilder()
+  .setName('stats')
+  .setDescription('View your voice activity statistics')
+  .addUserOption(option =>
+    option
+      .setName('user')
+      .setDescription('User to check (optional)')
+      .setRequired(false)
+  );
+
+// Handle the command
+client.on('interactionCreate', async (interaction) => {
+  if (!interaction.isChatInputCommand()) return;
+  if (interaction.commandName !== 'stats') return;
+
+  const targetUser = interaction.options.getUser('user') || interaction.user;
+  const userData = await voiceManager.getUser(interaction.guildId, targetUser.id);
+
+  if (!userData) {
+    return interaction.reply({
+      content: `${targetUser.username} has no voice activity yet!`,
+      ephemeral: true,
+    });
+  }
+
+  const embed = new EmbedBuilder()
+    .setColor('#5865F2')
+    .setTitle(`📊 Voice Stats for ${targetUser.username}`)
+    .addFields(
+      { name: '⏱️ Total Voice Time', value: calculator.formatVoiceTime(userData.totalVoiceTime), inline: true },
+      { name: '⭐ Level', value: `${userData.level}`, inline: true },
+      { name: '💫 XP', value: `${userData.xp}`, inline: true }
+    );
+
+  await interaction.reply({ embeds: [embed] });
+});
+
+// Register commands when bot is ready
+client.once('ready', async () => {
+  await client.application.commands.create(statsCommand);
+  console.log('✅ Slash commands registered!');
+});
+```
+
+### Available Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `/stats [@user]` | View voice statistics | `/stats @John` |
+| `/leaderboard [type]` | View server leaderboard | `/leaderboard xp` |
+| `/rank [@user]` | Check server rank | `/rank` |
+| `/sessions [@user]` | View recent sessions | `/sessions @John` |
+
+**📖 See [examples/bot.js](examples/bot.js) for complete command implementations!**
+
+---
+
+## ⚙️ Configuration
+
+### Manager Options
+
+```javascript
+const voiceManager = new VoiceManager(client, {
+  // Required
+  storage: storage,                    // Storage adapter (JSONStorage or MongoStorage)
+  
+  // Optional
+  checkInterval: 5000,                 // How often to check (milliseconds)
+  debug: false,                        // Enable debug logging
+  
+  defaultConfig: {
+    // Tracking options
+    trackBots: false,                  // Track bot users
+    trackAllChannels: true,            // Track all voice channels
+    trackMuted: true,                  // Track muted users
+    trackDeafened: true,               // Track deafened users
+    
+    // Channel filters
+    channelIds: [],                    // Specific channels to track (if trackAllChannels: false)
+    minUsersToTrack: 0,               // Minimum users in channel to track (0 = no limit)
+    maxUsersToTrack: 0,               // Maximum users in channel to track (0 = no limit)
+    
+    // Permission filters
+    exemptPermissions: [],            // Users with these permissions won't be tracked
+    
+    // XP & Leveling
+    xpPerCheck: 5,                    // XP to award per check interval
+    voiceTimePerCheck: 5000,          // Voice time to add per check (milliseconds)
+    levelMultiplier: 0.1,             // Level calculation multiplier
+    enableLeveling: true,             // Enable XP/leveling system
+    enableVoiceTime: true,            // Enable voice time tracking
+  },
+});
+```
+
+### Per-Guild Configuration
+
+Change settings for specific servers:
+
+```javascript
+// Get current config
+const config = await voiceManager.getGuildConfig(guildId);
+
+// Modify settings
+config.trackBots = true;              // Now track bots
+config.xpPerCheck = 10;              // Give more XP
+config.channelIds = ['123456789'];   // Only track specific channel
+
+// Save changes
+await voiceManager.saveGuildConfig(guildId, config);
+```
+
+### Advanced Filtering
+
+```javascript
+const config = await voiceManager.getGuildConfig(guildId);
+
+// Only track channels with "voice" in the name
+config.channelFilter = (channel) => {
+  return channel.name.toLowerCase().includes('voice');
+};
+
+// Don't track users with "Muted" role
+config.memberFilter = (member) => {
+  return !member.roles.cache.some(role => role.name === 'Muted');
+};
+
+await voiceManager.saveGuildConfig(guildId, config);
+```
+
+---
+
+## 🎯 Events
+
+Listen to these events to add custom features:
+
+```javascript
+// User gained voice time
+voiceManager.on('voiceTimeGained', (userData, gained) => {
+  console.log(`User gained ${gained}ms of voice time`);
+});
+
+// User gained XP
+voiceManager.on('xpGained', (userData, gained) => {
+  console.log(`User gained ${gained} XP`);
+});
+
+// User leveled up
+voiceManager.on('levelUp', (userData, oldLevel, newLevel) => {
+  console.log(`User leveled up from ${oldLevel} to ${newLevel}!`);
+  
+  // Example: Give a role when reaching level 10
+  if (newLevel === 10) {
+    const guild = client.guilds.cache.get(userData.guildId);
+    const member = guild.members.cache.get(userData.userId);
+    const role = guild.roles.cache.find(r => r.name === 'Active Chatter');
+    if (member && role) {
+      member.roles.add(role);
+    }
+  }
+});
+
+// Voice session started
+voiceManager.on('sessionStart', (session) => {
+  console.log(`Session started for ${session.userId}`);
+});
+
+// Voice session ended
+voiceManager.on('sessionEnd', (session) => {
+  console.log(`Session ended, duration: ${session.duration}ms`);
+});
+
+// Configuration updated
+voiceManager.on('configUpdated', (guildId, config) => {
+  console.log(`Config updated for guild ${guildId}`);
+});
+
+// Error occurred
+voiceManager.on('error', (error) => {
+  console.error('Voice Manager Error:', error);
+});
+
+// Debug messages (only if debug: true)
+voiceManager.on('debug', (message) => {
+  console.log(`[DEBUG] ${message}`);
+});
+```
+
+---
+
+## 📚 API Reference
+
+### VoiceManager
+
+#### Methods
+
+```javascript
+// Initialize the manager
+await voiceManager.init();
+
+// Get user data
+const userData = await voiceManager.getUser(guildId, userId);
+// Returns: { userId, guildId, totalVoiceTime, xp, level, channels, ... }
+
+// Update user data
+await voiceManager.updateUser(guildId, userId, {
+  addVoiceTime: 60000,  // Add 1 minute
+  addXp: 100,           // Add 100 XP
+  setLevel: 5,          // Set to level 5
+  metadata: { ... }     // Custom data
+});
+
+// Get leaderboard
+const leaderboard = await voiceManager.getLeaderboard(guildId, {
+  sortBy: 'xp',        // 'voiceTime', 'xp', or 'level'
+  limit: 10,           // Number of users
+  offset: 0,           // Pagination offset
+});
+
+// Get/save guild config
+const config = await voiceManager.getGuildConfig(guildId);
+await voiceManager.saveGuildConfig(guildId, config);
+
+// Delete data
+await voiceManager.deleteGuild(guildId);
+await voiceManager.deleteUser(guildId, userId);
+
+// Cleanup
+await voiceManager.destroy();
+```
+
+### XPCalculator
+
+```javascript
+const { XPCalculator } = require('discord-voice-tracker');
+const calculator = new XPCalculator();
+
+// Calculate level from XP
+const level = calculator.calculateLevel(1000, 0.1);
+// Returns: 10
+
+// Calculate XP needed for level
+const xpNeeded = calculator.calculateXPForLevel(10, 0.1);
+// Returns: 1000
+
+// Calculate XP to next level
+const xpToNext = calculator.calculateXPToNextLevel(1500, 0.1);
+// Returns: 610
+
+// Calculate progress percentage
+const progress = calculator.calculateLevelProgress(1500, 0.1);
+// Returns: 22 (22%)
+
+// Format voice time to readable string
+const formatted = calculator.formatVoiceTime(3661000);
+// Returns: "1h 1m 1s"
+
+// Calculate average session duration
+const avgDuration = calculator.calculateAverageSessionDuration(
+  totalVoiceTime,
+  totalSessions
+);
+```
+
+---
+
+## 💾 Storage Options
+
+### JSON Storage (Default)
+
+**Best for:** Small to medium bots, testing, single server
+
+```javascript
+const { JSONStorage } = require('discord-voice-tracker');
+
+const storage = new JSONStorage('./data');
+// Creates: ./data/guilds.json and ./data/sessions.json
+```
+
+**Pros:**
+- ✅ No external dependencies
+- ✅ Easy to inspect/edit files
+- ✅ Simple backup (just copy the folder)
+
+**Cons:**
+- ❌ Not suitable for large scale (1000+ users)
+- ❌ No concurrent write protection
+
+### MongoDB Storage
+
+**Best for:** Production, large servers, multiple bots
+
+```javascript
+const { MongoStorage } = require('discord-voice-tracker');
+
+// Make sure to: npm install mongodb
+
+const storage = new MongoStorage(
+  'mongodb://localhost:27017',  // Connection string
+  'voicetracker'                // Database name
+);
+
+// Or with MongoDB Atlas:
+const storage = new MongoStorage(
+  'mongodb+srv://user:pass@cluster.mongodb.net/',
+  'voicetracker'
+);
+```
+
+**Pros:**
+- ✅ Handles large datasets efficiently
+- ✅ Built-in indexing for fast queries
+- ✅ Concurrent write support
+- ✅ Easy to scale
+
+**Cons:**
+- ❌ Requires MongoDB server
+- ❌ More complex setup
+
+---
+
+## 📝 Examples
+
+### Example 1: Basic Bot
+
+```javascript
+const { Client, GatewayIntentBits } = require('discord.js');
+const { VoiceManager, JSONStorage } = require('discord-voice-tracker');
+
+const client = new Client({
+  intents: [
+    GatewayIntentBits.Guilds,
+    GatewayIntentBits.GuildVoiceStates,
+  ],
+});
+
+const storage = new JSONStorage('./data');
+const voiceManager = new VoiceManager(client, { storage });
+
+client.once('ready', async () => {
+  await voiceManager.init();
+  console.log('Bot ready!');
+});
+
+client.login('YOUR_TOKEN');
+```
+
+### Example 2: With Level-Up Rewards
+
+```javascript
+voiceManager.on('levelUp', async (userData, oldLevel, newLevel) => {
+  const guild = client.guilds.cache.get(userData.guildId);
+  const member = await guild.members.fetch(userData.userId);
+  
+  // Level 5: Bronze role
+  if (newLevel === 5) {
+    const role = guild.roles.cache.find(r => r.name === 'Bronze Chatter');
+    await member.roles.add(role);
+  }
+  
+  // Level 10: Silver role
+  if (newLevel === 10) {
+    const role = guild.roles.cache.find(r => r.name === 'Silver Chatter');
+    await member.roles.add(role);
+  }
+  
+  // Level 25: Gold role
+  if (newLevel === 25) {
+    const role = guild.roles.cache.find(r => r.name === 'Gold Chatter');
+    await member.roles.add(role);
+  }
+});
+```
+
+### Example 3: Custom XP Based on Channel
+
+```javascript
+const config = await voiceManager.getGuildConfig(guildId);
+
+// Give more XP in certain channels
+config.channelFilter = (channel) => {
+  if (channel.name === 'study-room') {
+    config.xpPerCheck = 10; // Double XP in study room
+  } else {
+    config.xpPerCheck = 5;  // Normal XP elsewhere
+  }
+  return true; // Track all channels
+};
+
+await voiceManager.saveGuildConfig(guildId, config);
+```
+
+**📖 More examples in [examples/](examples/) folder!**
+
+---
+
+## 🐛 Troubleshooting
+
+### "Module not found: discord-voice-tracker"
+
+**Solution:** Make sure you installed it:
+```bash
+npm install discord-voice-tracker discord.js
+```
+
+### "Cannot find module 'mongodb'"
+
+**Solution:** MongoDB is optional. Install it if you want to use MongoStorage:
+```bash
+npm install mongodb
+```
+
+Or use JSONStorage instead:
+```javascript
+const { JSONStorage } = require('discord-voice-tracker');
+const storage = new JSONStorage('./data');
+```
+
+### Voice tracking not working
+
+**Checklist:**
+1. ✅ Bot has correct intents:
+   - `GatewayIntentBits.Guilds`
+   - `GatewayIntentBits.GuildVoiceStates`
+2. ✅ Called `await voiceManager.init()`
+3. ✅ Bot is in the server
+4. ✅ User is in a voice channel
+5. ✅ Wait at least 5-10 seconds
+
+**Check the logs:**
+```javascript
+const voiceManager = new VoiceManager(client, {
+  storage,
+  debug: true,  // Enable this!
+});
+```
+
+### Stats command shows no data
+
+**Possible causes:**
+1. User hasn't joined voice yet
+2. `trackBots` is false and checking a bot
+3. Config updated and wiped users (see bug fix in docs)
+
+**Solution:**
+```javascript
+const userData = await voiceManager.getUser(guildId, userId);
+if (!userData) {
+  return interaction.reply('No data yet! Join a voice channel first.');
+}
+```
+
+### TypeError: Cannot read property 'users' of null
+
+**Solution:** Guild not initialized. The bot will create it automatically when someone joins voice, or you can create it manually:
+```javascript
+const config = await voiceManager.getGuildConfig(guildId);
+// This creates the guild if it doesn't exist
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙏 Support
+
+- 📖 **Documentation:** [GitHub](https://github.com/yourusername/discord-voice-tracker)
+- 🐛 **Bug Reports:** [Issues](https://github.com/yourusername/discord-voice-tracker/issues)
+- 💬 **Discord:** [Join our server](https://discord.gg/your-invite)
+- ⭐ **Star on GitHub** if you find this useful!
+
+---
+
+## 📊 Stats
+
+![npm](https://img.shields.io/npm/v/discord-voice-tracker?style=flat-square)
+![downloads](https://img.shields.io/npm/dt/discord-voice-tracker?style=flat-square)
+![license](https://img.shields.io/npm/l/discord-voice-tracker?style=flat-square)
+![size](https://img.shields.io/bundlephobia/min/discord-voice-tracker?style=flat-square)
+
+---
+
+**Made with ❤️ by [Async](https://github.com/yourusername)**