discord-prevnames
Version:
Unofficial Discord module to track and retrieve users' previous usernames and display names by ID .
210 lines (160 loc) • 5.95 kB
Markdown
# 🎮 Discord PrevNames
> Track Discord username & display name changes in real-time with this unofficial module
[](https://docs.discprev.xyz)
## 📚 Documentation
Full documentation available at: [https://docs.discprev.xyz](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
```bash
npm install discord-prevnames
```
## 🎯 Quick Start
```javascript
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
```typescript
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](https://docs.discprev.xyz)
Below is a quick overview of the main features:
### Class: PrevNames
#### Constructor
```javascript
const prevnames = new PrevNames();
```
#### Methods
**.on(eventName, callback)**
- Listen for name change events
- Returns an unsubscribe function
```javascript
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
```javascript
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
```javascript
prevnames.stop();
```
## 🌐 API Endpoints
The module interacts with the following endpoints:
```plaintext
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
```javascript
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
```javascript
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:
```javascript
// 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
---
<div align="center">
<strong>Keep track of Discord name changes with ease</strong>
</div>