Cordly

Cordly es una biblioteca de utilidades diseñada para simplificar el desarrollo de bots de Discord utilizando discord.js. Proporciona una serie de herramientas que permiten a los desarrolladores manejar comandos, eventos y bases de datos de forma eficiente y estructurada.

Descripción

Desarrollar bots para Discord puede ser una tarea compleja, especialmente cuando se trata de manejar la lógica de comandos y eventos. Cordly aborda estas complejidades al ofrecer una API intuitiva y fácil de usar que permite a los desarrolladores centrarse en crear experiencias enriquecedoras para sus usuarios. Con características como soporte para múltiples tipos de bases de datos y un enfoque modular, Cordly está diseñado para ser extensible y adaptable a las necesidades de cualquier proyecto.

Características Clave

• Gestión de Comandos y Eventos: Maneja comandos y eventos de manera sencilla, permitiendo una organización clara de la lógica del bot.
• Soporte para Bases de Datos: Proporciona implementaciones para bases de datos en memoria y basadas en JSON, facilitando el almacenamiento de datos.
• Documentación Clara: Documentación accesible y ejemplos prácticos para acelerar el proceso de integración.

Instalación

Para comenzar a utilizar Cordly, necesitas tener Node.js y npm instalados en tu máquina. Puedes descargar Node.js desde su página oficial. Una vez que tengas Node.js instalado, puedes agregar Cordly a tu proyecto utilizando npm. Ejecuta el siguiente comando en tu terminal:

npm install cordly

Logger

La clase Logger proporciona un sistema de registro de mensajes que permite a los desarrolladores realizar un seguimiento de los eventos y errores en su aplicación. Implementa diferentes niveles de log: debug, info, warn, y error. Además, admite la escritura de logs en un archivo y opcionalmente en la consola.

Características

• Niveles de Log: Soporta cuatro niveles de log que permiten clasificar los mensajes:
• debug: Mensajes detallados para depuración.
• info: Mensajes informativos sobre el flujo de la aplicación.
• warn: Advertencias sobre posibles problemas.
• error: Errores o problemas graves.
• Configuración Flexible: Permite configurar la ruta del archivo de log, el nivel mínimo de logs que se registran y la opción de mostrar logs en la consola. ### Opciones de Configuración La clase Logger acepta un objeto de configuración opcional al inicializarse. Las opciones disponibles son:

| Opción | Tipo | Descripción | Valor por defecto | |-----------------|-----------|-----------------------------------------------------------------------------|------------------------------| | filePath | string | Ruta del archivo donde se almacenarán los logs. | '../../logs/bot.log' | | logLevel | LogLevel| Nivel mínimo de logs que se van a registrar. | 'info' | | consoleLogging | boolean | Indica si se deben mostrar los logs en la consola además de registrarlos en el archivo. | true |

Ejemplo de Uso

JavaScript (.js)

const Logger = require('cordly').Logger;

// Crear una instancia del Logger con configuración personalizada
const logger = Logger.getInstance({ logLevel: 'debug', consoleLogging: true });

// Usar el logger
logger.debug('Este es un mensaje de depuración');
logger.info('La aplicación ha iniciado correctamente');
logger.warn('La memoria está cerca del límite');
logger.error('Error de conexión con la base de datos');

Module (.mjs)

import { Logger } from 'cordly';

// Crear una instancia del Logger con configuración personalizada
const logger = Logger.getInstance({ logLevel: 'debug', consoleLogging: true });

// Usar el logger
logger.debug('Este es un mensaje de depuración');
logger.info('La aplicación ha iniciado correctamente');
logger.warn('La memoria está cerca del límite');
logger.error('Error de conexión con la base de datos');

Métodos Disponibles -

getInstance(options)

: Método estático para obtener la instancia única del logger. Acepta opciones de configuración. -

debug(message)

: Registra un mensaje de nivel debug. -

info(message)

: Registra un mensaje de nivel info. -

warn(message)

: Registra un mensaje de nivel warn. -

error(message)

: Registra un mensaje de nivel error.

Ejemplo inizialicacion

const options = {
    filePath: '/var/logs/myapp.log',   // Ruta personalizada para el archivo de logs
    logLevel: 'debug',                  // Registra todos los niveles de logs
    consoleLogging: false                // Desactiva el logging en la consola
};

const logger = Logger.getInstance(options);

EventHandler

La clase EventHandler gestiona la carga, validación y ejecución de eventos en un bot de Discord. Permite cargar eventos desde archivos, validarlos y asignarlos al cliente de Discord para que sean ejecutados cuando ocurra el evento correspondiente.

Características

• Carga Dinámica de Eventos: Permite cargar eventos desde un directorio específico, facilitando la gestión de eventos.
• Validación de Eventos: Asegura que cada evento tenga un método de ejecución válido antes de ser registrado.
• Soporte para Eventos Únicos: Permite que un evento se ejecute solo una vez o cada vez que ocurra, según se especifique.

Interfaz Event

La interfaz Event define la estructura básica de un evento para el bot de Discord, que incluye: | Propiedad | Tipo | Descripción | |-----------|-----------------------------------|-----------------------------------------------------------------------------------------------| | name | keyof ClientEvents | Nombre del evento que se registrará en el cliente de Discord. | | once | boolean | Indica si el evento debe ejecutarse solo una vez. | | execute | (...args: unknown[]) => Promise<void> | void | Método que se ejecuta cuando se activa el evento, recibiendo los argumentos del evento. |

Ejemplo de Uso

Para utilizar EventHandler, primero crea una instancia de la clase pasando el cliente de Discord. Luego, carga los eventos desde un directorio específico.

JavaScript (.js)

const { Client, GatewayIntentBits } = require('discord.js');
const EventHandler = require('cordly').EventHandler;

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

// Cargar eventos desde el directorio './events'
eventHandler.loadEvents('./events');

// Iniciar sesión en Discord
client.login('YOUR_BOT_TOKEN');

Module (.mjs)

import { Client, GatewayIntentBits } from 'discord.js';
import { EventHandler } from 'cordly';

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

// Cargar eventos desde el directorio './events'
eventHandler.loadEvents('./events');

// Iniciar sesión en Discord
client.login('YOUR_BOT_TOKEN');

Carga de Eventos

Los eventos se cargan desde archivos ubicados en un directorio especificado. Cada archivo debe exportar un objeto que implemente la interfaz Event. A continuación se muestra un ejemplo de cómo podría lucir un archivo de evento: Ejemplo de Archivo de Evento (ready.js)

module.exports = {
    name: 'ready',
    once: true,
    execute() {
        console.log('¡El bot está listo!');
    },
};

Ejemplo de Archivo de Evento (messageCreate.js)

module.exports = {
    name: 'messageCreate',
    execute(message) {
        if (message.content === '!ping') {
            message.reply('¡Pong!');
        }
    },
};

Métodos Disponibles -

loadEvents(eventsDir)

: Carga eventos desde un directorio específico. -

getLoadedEvents()

: Devuelve un mapa de los eventos que han sido cargados.

CommandHandler

La clase CommandHandler se encarga de la carga, registro y ejecución de comandos en un bot de Discord. Proporciona un sistema robusto para gestionar comandos, incluyendo características como cooldowns, verificación de roles, y soporte para comandos premium.

Características

• Carga Dinámica de Comandos: Permite cargar comandos desde archivos ubicados en un directorio específico.
• Soporte para Cooldowns: Evita el uso excesivo de un comando por parte de un usuario mediante cooldowns.
• Verificación de Roles y Permisos: Restringe el uso de comandos basándose en roles específicos y permisos requeridos.
• Soporte para Comandos Premium: Permite definir niveles de acceso premium para ciertos comandos.
• Middlewares: Se pueden ejecutar funciones antes de la ejecución del comando.

Interfaz Command

La interfaz Command define la estructura básica de un comando para el bot de Discord, que incluye: | Propiedad | Tipo | Descripción | |-----------------|-------------------------------------------|-----------------------------------------------------------------------------------------------| | name | string | Nombre del comando. | | description | string | Descripción del comando. | | onlyOwner | boolean | Indica si el comando solo puede ser ejecutado por el propietario del bot. | | allowedRoles | string[] | Lista de IDs de roles permitidos para ejecutar el comando. | | premiumLevel | number | Nivel premium requerido para ejecutar el comando. | | enabled | boolean | Indica si el comando está habilitado. | | cooldown | number | Cooldown por usuario en segundos. | | aliases | string[] | Lista de alias para el comando. | | usage | string | Cómo se debe usar el comando. | | category | string | Categoría del comando. | | permissions | bigint[] | Lista de nuevos permisos requeridos para ejecutar el comando. | | execute | (message: Message, args: string[]) => Promise<void> | void | Función que se ejecuta al llamar al comando, recibiendo el mensaje y los argumentos. |

Ejemplo de Uso

Para utilizar CommandHandler, primero crea una instancia de la clase con el prefijo y el ID del propietario del bot. Luego, carga los comandos desde un directorio específico. JavaScript (.js)

const { Client, GatewayIntentBits } = require('discord.js');
const CommandHandler = require('cordly').CommandHandler;

const client = new Client({ intents: [GatewayIntentBits.Guilds] });
const commandHandler = new CommandHandler('!', 'YOUR_OWNER_ID');

// Cargar comandos desde el directorio './comandos'
commandHandler.loadCommandsFromPath('./comandos');

// Manejar mensajes y ejecutar comandos
client.on('messageCreate', (message) => {
    commandHandler.handleMessage(message);
});

// Iniciar sesión en Discord
client.login('YOUR_BOT_TOKEN');

Module (.mjs)

import { Client, GatewayIntentBits } from 'discord.js';
import { CommandHandler } from 'cordly';

const client = new Client({ intents: [GatewayIntentBits.Guilds] });
const commandHandler = new CommandHandler('!', 'YOUR_OWNER_ID');

// Cargar comandos desde el directorio './comandos'
await commandHandler.loadCommandsFromPath('./comandos');

// Manejar mensajes y ejecutar comandos
client.on('messageCreate', (message) => {
    commandHandler.handleMessage(message);
});

// Iniciar sesión en Discord
client.login('YOUR_BOT_TOKEN');

Carga de Comandos

Los comandos se cargan desde archivos ubicados en un directorio especificado. Cada archivo debe exportar un objeto que implemente la interfaz Command. A continuación se muestra un ejemplo de cómo podría lucir un archivo de comando: Ejemplo de Archivo de Comando (ping.js)

module.exports = {
    name: 'ping',
    description: 'Responde con Pong!',
    execute(message) {
        message.reply('Pong!');
    },
};

Métodos Disponibles -

registerCommand(command: Command)

: Registra un nuevo comando. -

loadCommandsFromPath(dirPath: string)

: Carga todos los comandos desde una ruta específica. -

handleMessage(message: Message)

: Maneja el mensaje y ejecuta el comando correspondiente. -

setPrefix(newPrefix: string)

: Cambia el prefijo de los comandos. -

setPremiumUser(userId: string, level: number)

: Establece o actualiza el nivel premium de un usuario. -

getCommandsList()

: Devuelve una lista de nombres de comandos registrados. -

exportCommands(filePath: string)

: Exporta comandos a un archivo JSON.

Consideraciones Finales

Asegúrate de que los archivos de comando estén correctamente estructurados y exporten un objeto que cumpla con la interfaz

Command

. Esto asegurará que el CommandHandler funcione correctamente y que los comandos se ejecuten como se espera. Con CommandHandler, puedes gestionar comandos de forma eficiente y organizada, facilitando la extensión y mantenimiento de tu bot de Discord.

SlashCommandHandler

La clase SlashCommandHandler gestiona la carga, validación, registro y ejecución de comandos Slash en un bot de Discord. Permite a los desarrolladores crear comandos interactivos que los usuarios pueden invocar a través de la interfaz de Discord.

Características

• Carga Dinámica de Comandos: Permite cargar comandos desde archivos ubicados en un directorio específico.
• Validación de Comandos: Asegura que los comandos tengan la estructura adecuada antes de ser registrados.
• Registro en Discord: Registra los comandos en la API de Discord para que estén disponibles en el servidor.
• Manejo de Interacciones: Escucha las interacciones de los usuarios y ejecuta la lógica correspondiente para cada comando.

Interfaz SlashCommand

La interfaz SlashCommand define la estructura básica de un comando Slash para el bot: | Propiedad | Tipo | Descripción | |-----------|-----------------------------------------------------------------|------------------------------------------------------| | data | ApplicationCommandData | Estructura estándar de un comando en Discord. | | execute | (client: Client, interaction: CommandInteraction) => Promise<void> | Lógica de ejecución del comando. |

Ejemplo de Uso

Para utilizar SlashCommandHandler, primero crea una instancia de la clase pasando el cliente de Discord y el directorio de comandos. Luego, carga los comandos y maneja las interacciones de los usuarios.

JavaScript (.js)

const { Client, GatewayIntentBits } = require('discord.js');
const SlashCommandHandler = require('cordly').SlashCommandHandler;

const client = new Client({ intents: [GatewayIntentBits.Guilds] });
const handler = new SlashCommandHandler({
  client: client,
  commandsDir: './commands'
});

// Cargar comandos desde el directorio './commands'
await handler.loadCommands();

// Manejar interacciones de comandos Slash
client.on('interactionCreate', async (interaction) => {
  await handler.handleInteraction(interaction);
});

// Iniciar sesión en Discord
client.login('YOUR_BOT_TOKEN');

Module (.mjs)

import { Client, GatewayIntentBits } from 'discord.js';
import { SlashCommandHandler } from 'cordly';

const client = new Client({ intents: [GatewayIntentBits.Guilds] });
const handler = new SlashCommandHandler({
  client: client,
  commandsDir: './commands'
});

// Cargar comandos desde el directorio './commands'
await handler.loadCommands();

// Manejar interacciones de comandos Slash
client.on('interactionCreate', async (interaction) => {
  await handler.handleInteraction(interaction);
});

// Iniciar sesión en Discord
client.login('YOUR_BOT_TOKEN');

Carga de Comandos

Los comandos se cargan desde archivos ubicados en un directorio específico. Cada archivo debe exportar un objeto que implemente la interfaz SlashCommand. A continuación se muestra un ejemplo de cómo podría lucir un archivo de comando: Ejemplo de Archivo de Comando (ping.js)

module.exports = {
  data: {
    name: 'ping',
    description: 'Responde con Pong!',
  },
  async execute(client, interaction) {
    await interaction.reply('Pong!');
  },
};

Métodos Disponibles -

loadCommands()

: Carga todos los comandos desde el directorio especificado y los registra en Discord. -

handleInteraction(interaction: CommandInteraction)

: Maneja las interacciones recibidas de comandos Slash.

Utilities

La clase Utilities proporciona una colección de funciones útiles que pueden facilitar diversas tareas comunes en JavaScript, como la manipulación de cadenas, la generación de identificadores únicos, la validación de correos electrónicos y URLs, y más.

Métodos Disponibles

1. generateUUID(structure: string = 'xxxxxxxxxxxxxxxx'): string Genera un UUID (Identificador Único Universal) basado en una estructura dada.

• Parámetros: - structure: Estructura del UUID (por defecto: 'xxxxxxxxxxxxxxxx').

• Ejemplo:

  const uuid = Utilities.generateUUID('xx-xx-#xx-##xx');
  console.log(uuid); // 'ab-12-c3d-45ef'

2. getRandomHexColor(): string Genera un color hexadecimal aleatorio. - Ejemplo:

const randomColor = Utilities.getRandomHexColor();
console.log(randomColor); // '#a3e12f'

3. capitalizeWords(str: string): string Convierte la primera letra de cada palabra de una cadena a mayúsculas. Ejemplo:

const result = Utilities.capitalizeWords('hola mundo');
console.log(result); // 'Hola Mundo'

4. toLowerCase(str: string): string Convierte una cadena a minúsculas. Ejemplo:

const lowerStr = Utilities.toLowerCase('Hola Mundo');
console.log(lowerStr); // 'hola mundo'

5. toUpperCase(str: string): string Convierte una cadena a mayúsculas. Ejemplo:

const upperStr = Utilities.toUpperCase('Hola Mundo');
console.log(upperStr); // 'HOLA MUNDO'

6. formatNumber(num: number): string Formatea un número agregando separadores de miles. Ejemplo:

const formatted = Utilities.formatNumber(1234567);
console.log(formatted); // '1,234,567'

7. roundToDecimals(num: number, decimals: number): number Redondea un número a una cantidad específica de decimales. Ejemplo:

const rounded = Utilities.roundToDecimals(3.14159, 2);
console.log(rounded); // 3.14

8. dateDifferenceInDays(start: Date, end: Date): number Calcula la diferencia entre dos fechas en días. Ejemplo:

const daysDiff = Utilities.dateDifferenceInDays(new Date('2023-01-01'), new Date('2023-01-10'));
console.log(daysDiff); // 9

9. getCurrentDate(): Date Obtiene la fecha y hora actual. Ejemplo:

const currentDate = Utilities.getCurrentDate();
console.log(currentDate); // Fri Jan 20 2023 14:35:27 GMT+0000 (UTC)

10. validateEmail(email: string): boolean Valida una dirección de correo electrónico. Ejemplo:

const isValid = Utilities.validateEmail('[email protected]');
console.log(isValid); // true

11. validateURL(url: string): boolean Valida una URL. Ejemplo:

const isValidUrl = Utilities.validateURL('https://www.example.com');
console.log(isValidUrl); // true

ModerationHandler

La clase ModerationHandler permite gestionar acciones de moderación en un bot de Discord utilizando Discord.js. Con este módulo, los desarrolladores pueden implementar funcionalidades como expulsar, banear, silenciar (timeout), quitar el silencio y desbanear a miembros de un servidor.

Características

• Expulsar Miembros: Expulsa a un miembro de un servidor con una razón opcional.
• Banear Miembros: Banea a un miembro del servidor, eliminando opcionalmente sus mensajes de los últimos días.
• Silenciar Miembros (Timeout): Silencia temporalmente a un miembro por un tiempo específico.
• Quitar Silencio: Quita el silencio de un miembro antes de que termine el tiempo asignado.
• Desbanear Miembros: Desbanea a un usuario utilizando su ID.

Ejemplo de Uso

Para utilizar la clase ModerationHandler, debes crear una instancia pasándole un cliente de Discord. Luego puedes llamar a los métodos correspondientes para realizar las acciones de moderación.

JavaScript (.js)

const { Client, GatewayIntentBits } = require('discord.js');
const { ModerationHandler } = require('./ModerationHandler');

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

// Iniciar sesión en Discord
client.login('YOUR_BOT_TOKEN');

// Ejemplo: Expulsar a un miembro mencionado
client.on('messageCreate', async (message) => {
  if (message.content.startsWith('!kick')) {
    const member = message.mentions.members.first();
    if (member) {
      await moderationHandler.kickMember(member, 'Violación de las reglas');
    }
  }
});

Métodos Disponibles

kickMember(member: GuildMember, reason: string = 'No reason provided'): Promise<void> Expulsa a un miembro del servidor.

• member: El miembro que será expulsado.
• reason: (Opcional) Razón de la expulsión.

const member = message.mentions.members.first();
if (member) {
  await moderationHandler.kickMember(member, 'Reglas violadas');
}

banMember(member: GuildMember, reason: string = 'No reason provided', deleteMessageDays: number = 0): Promise<void> Banea a un miembro y opcionalmente elimina sus mensajes de los últimos días.

• member: El miembro que será baneado.
• reason: (Opcional) Razón del baneo.
• deleteMessageDays: (Opcional) Número de días de mensajes a eliminar (0-7).

const member = message.mentions.members.first();
if (member) {
  await moderationHandler.banMember(member, 'Conducta inapropiada', 7);
}

muteMember(member: GuildMember, duration: number, reason: string = 'No reason provided'): Promise<void> Silencia (timeout) a un miembro durante un tiempo especificado.

• member: El miembro que será silenciado.
• duration: Duración del silencio en milisegundos.
• reason: (Opcional) Razón del silencio.

const member = message.mentions.members.first();
if (member) {
  await moderationHandler.muteMember(member, 600000, 'Spam');
}

unmuteMember(member: GuildMember, reason: string = 'No reason provided'): Promise<void> Quita el silencio a un miembro antes de que se complete el tiempo asignado.

• member: El miembro que será desilenciado.
• reason: (Opcional) Razón para quitar el silencio.

const member = message.mentions.members.first();
if (member) {
  await moderationHandler.unmuteMember(member, 'Ha cumplido su castigo');
}

unbanMember(userId: string, reason: string = 'No reason provided'): Promise<void> Desbanea a un usuario usando su ID.

• userId: El ID del usuario a desbanear.
• reason: (Opcional) Razón del desbaneo.

await moderationHandler.unbanMember('123456789012345678', 'Ha apelado con éxito');

GiveawaysManager

La clase GiveawaysManager gestiona la creación, finalización, edición y eliminación de sorteos (giveaways) en Discord. Proporciona una interfaz sencilla para los desarrolladores que desean implementar sorteos en sus bots de Discord utilizando discord.js.

Características

• Inicio y Finalización de Sorteos: Permite iniciar sorteos con opciones personalizables y finalizarlos automáticamente al expirar el tiempo establecido.
• Gestión de Participantes: Maneja la adición y selección de ganadores de forma eficiente.
• Persistencia de Datos: Utiliza una base de datos JSON para almacenar información sobre los sorteos y sus participantes.

Ejemplo de Uso

JavaScript (.js)

const { Client, GatewayIntentBits } = require('discord.js');
const GiveawaysManager = require('cordly').GiveawaysManager;

const client = new Client({ intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent] });
const giveawaysManager = new GiveawaysManager(client, 'giveaways.json');

client.once('ready', async () => {
    console.log(`Logged in as ${client.user.tag}!`);
    
    // Iniciar un nuevo sorteo
    const giveaway = await giveawaysManager.start('channelId', 'guildId', {
        duration: 86400000, // 24 horas
        prize: 'Un regalo especial',
        winnerCount: 1,
        reaction: '🎉',
        onStart: (messageId, channelId) => {
            console.log(`Giveaway iniciado en el canal ${channelId} con el mensaje ID ${messageId}`);
        }
    });
});

client.login('your-token-here');

Métodos Disponibles

start(channelId: string, guildId: string, options: GiveawayOptions): Promise<Giveaway>

• Inicia un nuevo sorteo y lo guarda en la base de datos.

edit(messageId: string, options: Partial<GiveawayOptions>): Promise<Giveaway | null>

• Edita un sorteo existente con nuevas opciones.

delete(messageId: string): Promise<boolean>

• Elimina un sorteo existente de la base de datos.

Ejemplo de Inicialización

Para inicializar GiveawaysManager, simplemente crea una instancia pasando el cliente de Discord y el nombre del archivo donde se almacenarán los sorteos.

const giveawaysManager = new GiveawaysManager(client, './giveaways.json');

Interfaz GiveawayOptions

La interfaz GiveawayOptions define las opciones que se pueden pasar al iniciar un sorteo: | Propiedad | Tipo | Descripción | |--------------------|-----------|--------------------------------------------------------------| | duration | number | Duración del sorteo en milisegundos. | | prize | string | Descripción del premio del sorteo. | | winnerCount | number | Número de ganadores a seleccionar. | | reaction | string | Emoji que los usuarios deben reaccionar para participar. | | onStart | Function| Callback que se llama cuando se inicia el sorteo. | | onEnd | Function| Callback que se llama cuando finaliza el sorteo. | | onStartCallback | Function| Callback alternativo que se llama al iniciar el sorteo. | | onEndCallback | Function| Callback alternativo que se llama al finalizar el sorteo. |

Descripción de las Opciones de Callback

• onStart: Se ejecuta cuando el sorteo comienza, recibiendo el ID del mensaje y el ID del canal.
• onEnd: Se ejecuta cuando el sorteo finaliza, recibiendo los ganadores y el ID del canal.
• onStartCallback: Similar a onStart, pero permite una ejecución adicional de lógica si se necesita.
• onEndCallback: Similar a onEnd, permite una ejecución adicional de lógica si se necesita.