🎮 Discord PrevNames

Track Discord username & display name changes in real-time with this unofficial module

📚 Documentation

Full documentation available at: https://docs.discprev.xyz

🚀 Overview

Discord PrevNames is an unofficial module that allows you to track and retrieve Discord users' previous usernames and display names. Using Server-Sent Events (SSE), it provides real-time notifications when users change their names and maintains a historical record of these changes. With over 5 million previous names stored in our database, we offer one of the largest Discord name history tracking services available.

✨ Key Features

• Real-time Monitoring - Get instant notifications when users change their names
• Display Name Tracking - Track display name changes in real-time
• Event-Driven Architecture - Built with EventEmitter for easy event handling
• Automatic Reconnection - Maintains stable connection with automatic retry mechanism
• Simple API - Easy-to-use methods for retrieving user history

📦 Installation

npm install discord-prevnames

🎯 Quick Start

const PrevNames = require('discord-prevnames');

async function main() {
    const prevnames = new PrevNames();

    // Listen for name changes
    prevnames.on('prevnamesadd', (data) => {
        console.log('Name change detected:', {
            userId: data.userId,
            type: data.type,
            previousName: data.name,
            changedAt: data.changedAt
        });
    });

    // Get user's name history
    try {
        const history = await prevnames.getUserPrevnames('USER_ID');
        console.log('User history:', history);
    } catch (error) {
        console.error('Error:', error.message);
    }
}

main().catch(console.error);

📊 Event Data Structure

interface NameChangeEvent {
    userId: string;          // Discord User ID
    type: 'displayname';     // Type of name change
    name: string;           // Previous name
    changedAt: string;      // Timestamp of change
}

🔧 API Reference

For complete API documentation, visit https://docs.discprev.xyz

Below is a quick overview of the main features:

Class: PrevNames

Constructor

const prevnames = new PrevNames();

Methods

.on(eventName, callback)

• Listen for name change events
• Returns an unsubscribe function

const unsubscribe = prevnames.on('prevnamesadd', (data) => {
    console.log('New name change:', data);
});

// Later, to stop listening
unsubscribe();

.getUserPrevnames(userId)

• Retrieve user's name history
• Throws error if userId is invalid

async function getUserHistory() {
    try {
        const history = await prevnames.getUserPrevnames('123456789');
        console.log('History:', history);
    } catch (error) {
        console.error('Error:', error.message);
    }
}

.stop()

• Stop listening to name change events
• Removes all event listeners

prevnames.stop();

🌐 API Endpoints

The module interacts with the following endpoints:

GET  /api/users/:userId/prevnames    # Get user's name history
GET  /api/webhooks/prevnames/listen  # Stream real-time name changes

🔐 Error Handling

The module includes built-in error handling for:

• Invalid user IDs
• Network connection issues
• API response errors
• Event stream disruptions

async function handleUserHistory() {
    try {
        const history = await prevnames.getUserPrevnames('invalid_id');
    } catch (error) {
        console.error('Error:', error.message); // "User ID invalid"
    }
}

📈 Advanced Usage

Handling Different Name Change Types

async function trackNameChanges() {
    const prevnames = new PrevNames();
    
    prevnames.on('prevnamesadd', (data) => {
        if (data.type === 'displayname') {
            console.log(`Display name change for user ${data.userId}`);
            console.log(`Previous name: ${data.name}`);
            console.log(`Changed at: ${new Date(data.changedAt).toLocaleString()}`);
        }
    });
    
    // Example of fetching history alongside listening to changes
    try {
        const history = await prevnames.getUserPrevnames('123456789');
        console.log('Initial history:', history);
    } catch (error) {
        console.error('Error fetching history:', error.message);
    }
}

trackNameChanges().catch(console.error);

Auto-Reconnection Handling

The module automatically handles disconnections and reconnects with a 3-second delay:

// The module will automatically:
// 1. Detect disconnections
// 2. Wait 3 seconds
// 3. Attempt to reconnect
// 4. Resume event streaming

🛠️ Future Features

• [ ] Username change tracking
• [ ] Bulk history retrieval
• [ ] Customizable retry intervals
• [ ] Rate limiting protection
• [ ] Filtered event listening
• [ ] Historical data analysis

🤝 Contributing

Contributions are welcome! Feel free to submit issues and pull requests.

📝 License

ISC © Discord Prevnames