vcord.js 1.0.3 → 1.0.5

package/README.md

@@ -0,0 +1,157 @@
+# vcord
+
+A modern, user-friendly Discord bot library built on top of Discord.js, designed to simplify bot development while maintaining powerful functionality.
+
+## Features
+
+- 🚀 Simplified API for common Discord bot operations
+- 📝 Intuitive message handling and manipulation
+- 🎨 Easy-to-use Embed builder
+- 🔧 Custom channel management system
+- 🛠️ Built-in utilities for common bot tasks
+- 🔄 Promise-based API for modern async/await usage
+
+## Installation
+
+```bash
+npm install vcord
+```
+
+## Quick Start
+
+```javascript
+const { Client, EmbedBuilder } = require('vcord');
+
+const client = new Client({
+    intents: ['GUILDS', 'GUILD_MESSAGES', 'MESSAGE_CONTENT']
+});
+
+client.on('ready', () => {
+    console.log(`Logged in as ${client.user.username}`);
+});
+
+client.on('messageCreate', async (message) => {
+    if (message.content === '!ping') {
+        await message.reply('Pong! 🏓');
+    }
+
+    if (message.content === '!embed') {
+        const embed = new EmbedBuilder()
+            .setTitle('Hello World')
+            .setDescription('This is a simple embed!')
+            .setColor('#FF0000');
+        
+        // Send embed directly - no need for toJSON()!
+        await message.reply(embed);
+    }
+});
+
+client.login('YOUR_BOT_TOKEN');
+```
+
+## Key Features
+
+### Message Handling
+
+```javascript
+// Send a message
+await channel.send('Hello World!');
+
+// Reply to a message
+const reply = await message.reply('This is a reply!');
+
+// Edit a message
+await reply.edit('This message has been edited');
+
+// Delete a message
+await reply.delete();
+
+// Add reactions
+await message.react('👍');
+
+// Pin/Unpin messages
+await message.pin();
+await message.unpin();
+```
+
+### Embeds
+
+```javascript
+const embed = new EmbedBuilder()
+    .setTitle('My Embed')
+    .setDescription('This is a description')
+    .setColor('#FF0000')
+    .addField('Field Name', 'Field Value')
+    .setFooter('Footer Text')
+    .setTimestamp();
+
+// Send embed directly - no toJSON() needed!
+await message.reply(embed);
+```
+
+### Custom Channel System
+
+```javascript
+// Set up custom channels
+client.channel('logs', 'LOGS_CHANNEL_ID');
+client.channel('welcome', 'WELCOME_CHANNEL_ID');
+
+// Use custom channels
+const logsChannel = client.channel('logs');
+if (logsChannel) {
+    await logsChannel.send('This is a log message');
+}
+```
+
+### Presence Management
+
+```javascript
+client.setPresence({
+    activities: [{ 
+        name: 'with vcord',
+        type: 'PLAYING'
+    }],
+    status: 'online'
+});
+```
+
+### Server Management
+
+```javascript
+// Create a channel
+const newChannel = await client.createChannel(guildId, {
+    name: 'new-channel',
+    type: 0, // Text Channel
+    topic: 'Channel topic'
+});
+
+// Create a role
+const newRole = await client.createRole(guildId, {
+    name: 'New Role',
+    color: '#FF0000',
+    mentionable: true
+});
+
+// Ban a user
+await client.ban(guildId, userId, 'Reason for ban');
+```
+
+## Error Handling
+
+The library uses Promise-based error handling:
+
+```javascript
+try {
+    await message.reply('Hello!');
+} catch (error) {
+    console.error('Failed to send message:', error);
+}
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details. 

package/docs/README.md

@@ -0,0 +1,48 @@
+# VCord Documentation
+
+VCord is a powerful and lightweight Discord bot framework for JavaScript. It provides an intuitive API for creating Discord bots with both traditional prefix commands and slash commands.
+
+## Table of Contents
+
+1. [Getting Started](./getting-started.md)
+2. [Client](./client.md)
+3. [Commands](./commands.md)
+4. [Structures](./structures.md)
+5. [Events](./events.md)
+6. [Builders](./builders.md)
+7. [Advanced Usage](./advanced.md)
+
+## Features
+
+- Easy-to-use command system
+- Support for both prefix commands and slash commands
+- Built-in command groups and subcommands
+- Powerful event handling
+- Comprehensive structure classes
+- Efficient WebSocket management
+- Built-in permission system
+- Customizable prefix
+- Type-safe builders for slash commands
+
+## Quick Example
+
+```javascript
+const { Client } = require('vcord');
+const { Intents } = require('vcord/client/extentions/intents');
+
+const client = new Client({
+    intents: [
+        Intents.GUILDS,
+        Intents.GUILD_MESSAGES,
+        Intents.MESSAGE_CONTENT
+    ]
+});
+
+client.on('ready', () => {
+    console.log(`Logged in as ${client.user.tag}!`);
+});
+
+client.login('your-token-here');
+```
+
+For more detailed information, check out the specific documentation sections listed in the Table of Contents. 

package/docs/advanced.md

@@ -0,0 +1,347 @@
+# Advanced Usage
+
+This guide covers advanced features and patterns in VCord.
+
+## Custom Caching
+
+VCord provides a flexible caching system that you can customize:
+
+```javascript
+const { Client, Intents } = require('vcord');
+
+const client = new Client({
+    intents: [Intents.GUILDS],
+    cacheOptions: {
+        messageLifetime: 3600, // Cache messages for 1 hour
+        userLifetime: 86400,   // Cache users for 24 hours
+        maxMessages: 1000,     // Maximum messages to cache
+        maxUsers: 10000        // Maximum users to cache
+    }
+});
+```
+
+## Custom Command Handling
+
+You can create custom command handlers:
+
+```javascript
+class CustomCommandHandler {
+    constructor(client) {
+        this.client = client;
+        this.commands = new Map();
+    }
+
+    register(command) {
+        this.commands.set(command.name, command);
+    }
+
+    async handle(message) {
+        const args = message.content.slice(this.client.prefix.length).trim().split(/ +/);
+        const commandName = args.shift().toLowerCase();
+        
+        const command = this.commands.get(commandName);
+        if (!command) return;
+
+        try {
+            await command.execute(message, args);
+        } catch (error) {
+            console.error(error);
+            message.reply('An error occurred while executing the command.');
+        }
+    }
+}
+```
+
+## Custom Events
+
+Create custom events for your bot:
+
+```javascript
+class CustomEvents {
+    constructor(client) {
+        this.client = client;
+    }
+
+    // Custom event that fires when a user levels up
+    async emitLevelUp(user, newLevel) {
+        this.client.emit('levelUp', user, newLevel);
+    }
+
+    // Custom event that fires when a guild milestone is reached
+    async emitGuildMilestone(guild, milestone) {
+        this.client.emit('guildMilestone', guild, milestone);
+    }
+}
+
+// Using custom events
+client.on('levelUp', (user, newLevel) => {
+    console.log(`${user.tag} reached level ${newLevel}!`);
+});
+```
+
+## Advanced Error Handling
+
+Create a robust error handling system:
+
+```javascript
+class ErrorHandler {
+    constructor(client) {
+        this.client = client;
+        this.setupHandlers();
+    }
+
+    setupHandlers() {
+        // Handle Discord-specific errors
+        this.client.on('error', this.handleDiscordError.bind(this));
+        
+        // Handle unhandled promise rejections
+        process.on('unhandledRejection', this.handleUnhandledRejection.bind(this));
+        
+        // Handle uncaught exceptions
+        process.on('uncaughtException', this.handleUncaughtException.bind(this));
+    }
+
+    async handleDiscordError(error) {
+        console.error('Discord Error:', error);
+        
+        // Log to a Discord channel
+        const logChannel = await this.client.channels.fetch('your-log-channel-id');
+        if (logChannel) {
+            await logChannel.send({
+                embeds: [{
+                    title: 'Discord Error',
+                    description: error.message,
+                    color: 0xFF0000,
+                    timestamp: new Date()
+                }]
+            });
+        }
+    }
+
+    handleUnhandledRejection(error) {
+        console.error('Unhandled Promise Rejection:', error);
+    }
+
+    handleUncaughtException(error) {
+        console.error('Uncaught Exception:', error);
+        // Gracefully shutdown the bot
+        this.client.destroy();
+        process.exit(1);
+    }
+}
+```
+
+## Custom Middleware
+
+Create middleware for command handling:
+
+```javascript
+class MiddlewareManager {
+    constructor() {
+        this.middleware = [];
+    }
+
+    use(fn) {
+        this.middleware.push(fn);
+    }
+
+    async execute(context, next) {
+        let index = -1;
+        
+        const runner = async (i) => {
+            if (i <= index) throw new Error('next() called multiple times');
+            index = i;
+            
+            const fn = this.middleware[i];
+            if (i === this.middleware.length) fn = next;
+            if (!fn) return;
+            
+            await fn(context, () => runner(i + 1));
+        };
+        
+        await runner(0);
+    }
+}
+
+// Usage example
+const middleware = new MiddlewareManager();
+
+// Add logging middleware
+middleware.use(async (ctx, next) => {
+    console.log(`Command executed: ${ctx.commandName}`);
+    const start = Date.now();
+    await next();
+    const ms = Date.now() - start;
+    console.log(`Command completed in ${ms}ms`);
+});
+
+// Add permission checking middleware
+middleware.use(async (ctx, next) => {
+    if (!ctx.member.permissions.has('ADMINISTRATOR')) {
+        throw new Error('You need administrator permissions!');
+    }
+    await next();
+});
+```
+
+## Custom Structures
+
+Extend Discord structures with custom functionality:
+
+```javascript
+class CustomGuild {
+    constructor(guild) {
+        this.guild = guild;
+        this.settings = new Map();
+    }
+
+    async loadSettings() {
+        // Load guild settings from database
+    }
+
+    async saveSettings() {
+        // Save guild settings to database
+    }
+
+    async setupAutomod() {
+        // Setup automod rules
+    }
+
+    async createWelcomeChannel() {
+        // Create and setup welcome channel
+    }
+}
+
+class CustomMessage {
+    constructor(message) {
+        this.message = message;
+        this.parsed = this.parseMessage();
+    }
+
+    parseMessage() {
+        // Custom message parsing logic
+        return {
+            command: this.message.content.split(' ')[0],
+            args: this.message.content.split(' ').slice(1),
+            flags: this.parseFlags(this.message.content)
+        };
+    }
+
+    parseFlags(content) {
+        const flags = {};
+        const regex = /--(\w+)(?:=(\w+))?/g;
+        let match;
+        
+        while ((match = regex.exec(content)) !== null) {
+            flags[match[1]] = match[2] || true;
+        }
+        
+        return flags;
+    }
+}
+```
+
+## Advanced Slash Command Features
+
+Create complex slash commands with subcommands and autocomplete:
+
+```javascript
+const { SlashCommandBuilder } = require('vcord');
+
+const command = new SlashCommandBuilder()
+    .setName('manage')
+    .setDescription('Server management commands')
+    .addSubcommandGroup(group =>
+        group
+            .setName('roles')
+            .setDescription('Manage server roles')
+            .addSubcommand(subcommand =>
+                subcommand
+                    .setName('create')
+                    .setDescription('Create a new role')
+                    .addStringOption(option =>
+                        option
+                            .setName('name')
+                            .setDescription('The role name')
+                            .setRequired(true)
+                            .setAutocomplete(true)
+                    )
+                    .addStringOption(option =>
+                        option
+                            .setName('color')
+                            .setDescription('The role color')
+                            .addChoices(
+                                { name: 'Red', value: '#FF0000' },
+                                { name: 'Blue', value: '#0000FF' },
+                                { name: 'Green', value: '#00FF00' }
+                            )
+                    )
+            )
+    );
+
+// Handle autocomplete interactions
+client.on('interactionCreate', async interaction => {
+    if (!interaction.isAutocomplete()) return;
+
+    if (interaction.commandName === 'manage') {
+        const focusedOption = interaction.options.getFocused(true);
+        if (focusedOption.name === 'name') {
+            const choices = ['Moderator', 'Admin', 'VIP', 'Member']
+                .filter(choice => choice.startsWith(focusedOption.value))
+                .slice(0, 25);
+
+            await interaction.respond(
+                choices.map(choice => ({ name: choice, value: choice }))
+            );
+        }
+    }
+});
+```
+
+## Rate Limiting
+
+Implement rate limiting for commands:
+
+```javascript
+class RateLimiter {
+    constructor() {
+        this.limits = new Map();
+    }
+
+    async checkLimit(key, limit, time) {
+        const now = Date.now();
+        const userLimits = this.limits.get(key) || [];
+        
+        // Remove expired timestamps
+        const valid = userLimits.filter(timestamp => now - timestamp < time);
+        
+        if (valid.length >= limit) {
+            return false;
+        }
+        
+        valid.push(now);
+        this.limits.set(key, valid);
+        return true;
+    }
+}
+
+// Usage in commands
+const rateLimiter = new RateLimiter();
+
+client.on('interactionCreate', async interaction => {
+    if (!interaction.isCommand()) return;
+
+    const canExecute = await rateLimiter.checkLimit(
+        interaction.user.id,
+        5,  // 5 commands
+        60000 // per minute
+    );
+
+    if (!canExecute) {
+        await interaction.reply('You are being rate limited!');
+        return;
+    }
+
+    // Execute command
+});
+``` 

package/docs/builders.md

@@ -0,0 +1,136 @@
+# VCord Builders Documentation
+
+VCord provides several builder classes to help you create complex Discord objects easily.
+
+## Table of Contents
+- [SlashCommandBuilder](#slashcommandbuilder)
+- [EmbedBuilder](#embedbuilder)
+- [ComponentBuilder](#componentbuilder)
+  - [ButtonBuilder](#buttonbuilder)
+  - [SelectMenuBuilder](#selectmenubuilder)
+  - [TextInputBuilder](#textinputbuilder)
+
+## SlashCommandBuilder
+
+The `SlashCommandBuilder` class helps you create slash commands with proper validation and type checking.
+
+```javascript
+const { SlashCommandBuilder } = require('vcord');
+
+const command = new SlashCommandBuilder()
+    .setName('userinfo')
+    .setDescription('Get information about a user')
+    .addUserOption(option =>
+        option.setName('target')
+            .setDescription('The user to get info about')
+            .setRequired(false)
+    );
+```
+
+### Methods
+- `setName(name)`: Set the command name (1-32 characters, lowercase)
+- `setDescription(description)`: Set the command description (1-100 characters)
+- `setDefaultPermission(boolean)`: Set if the command is enabled by default
+- `addSubcommand(builder)`: Add a subcommand
+- `addSubcommandGroup(builder)`: Add a subcommand group
+- `addStringOption(builder)`: Add a string option
+- `addIntegerOption(builder)`: Add an integer option
+- `addBooleanOption(builder)`: Add a boolean option
+- `addUserOption(builder)`: Add a user option
+- `addChannelOption(builder)`: Add a channel option
+- `addRoleOption(builder)`: Add a role option
+- `addMentionableOption(builder)`: Add a mentionable option
+- `addNumberOption(builder)`: Add a number option
+- `addAttachmentOption(builder)`: Add an attachment option
+
+## EmbedBuilder
+
+The `EmbedBuilder` class helps you create rich message embeds.
+
+```javascript
+const { EmbedBuilder } = require('vcord');
+
+const embed = new EmbedBuilder()
+    .setTitle('Hello World')
+    .setDescription('This is a description')
+    .setColor('#FF0000')
+    .addFields([
+        { name: 'Field 1', value: 'Value 1' },
+        { name: 'Field 2', value: 'Value 2' }
+    ]);
+```
+
+### Methods
+- `setTitle(title)`: Set the embed title
+- `setDescription(description)`: Set the embed description
+- `setColor(color)`: Set the embed color (hex code or integer)
+- `setTimestamp(timestamp)`: Set the embed timestamp
+- `setFooter(text, iconURL)`: Set the embed footer
+- `setImage(url)`: Set the embed image
+- `setThumbnail(url)`: Set the embed thumbnail
+- `setAuthor(name, iconURL, url)`: Set the embed author
+- `addFields(fields)`: Add multiple fields
+- `addField(name, value, inline)`: Add a single field
+
+## ComponentBuilder
+
+The `ComponentBuilder` class and its subclasses help you create message components.
+
+### ButtonBuilder
+
+```javascript
+const { ButtonBuilder } = require('vcord');
+
+const button = new ButtonBuilder()
+    .setCustomId('click_me')
+    .setLabel('Click Me!')
+    .setStyle('PRIMARY');
+```
+
+### SelectMenuBuilder
+
+```javascript
+const { SelectMenuBuilder } = require('vcord');
+
+const menu = new SelectMenuBuilder()
+    .setCustomId('select')
+    .setPlaceholder('Choose an option')
+    .addOptions([
+        {
+            label: 'Option 1',
+            value: 'option_1',
+            description: 'This is option 1'
+        }
+    ]);
+```
+
+### TextInputBuilder
+
+```javascript
+const { TextInputBuilder } = require('vcord');
+
+const input = new TextInputBuilder()
+    .setCustomId('name')
+    .setLabel('Your Name')
+    .setStyle('SHORT')
+    .setRequired(true);
+```
+
+## Best Practices
+
+1. Always validate user input before creating commands
+2. Use descriptive names and descriptions
+3. Group related commands using subcommands
+4. Keep embed content concise and well-formatted
+5. Use appropriate component styles for better UX
+
+## Error Handling
+
+All builders include built-in validation and will throw descriptive errors if:
+- Required fields are missing
+- Values are invalid
+- Limits are exceeded (e.g., too many fields in an embed)
+
+## Examples
+
+Check the [examples](../example) directory for complete working examples of using builders.