easycordly.js (easycordly) v2.7.1

A lib Discord mais fácil, tipada e poderosa.

npm install easycordly.js

✨ Novidades da v2.7.1

| Recurso | O que faz | |---|---| | Comandos por arquivo sem boilerplate | Crie e registre comandos automaticamente via loadCommands ou client.command(). | | Retorno automático | return "Olá" (string, embed ou payload) já responde a interação. | | Argumentos tipados | args: { user: { type: "user" } } — convertidos automaticamente para User, Role, Channel, number… tanto em slash quanto em prefix. | | Sistema de perguntas | await ctx.ask("Qual seu nome?") aguarda a resposta. | | Eventos humanos | memberJoin, buttonClick, messageNew… — em vez dos nomes crus do discord.js. | | Permissões simplificadas | permissions: ["ban", "kick"] em vez de PermissionFlagsBits.BanMembers. | | Auto-embed | ctx.success(), ctx.error(), ctx.warn(), ctx.info() prontos. | | Paginação | await ctx.paginate(pages) — botões ⏮ ◀ ▶ ⏭ automáticos. | | Cooldown visual | cooldown: 5 por comando ou defaultCooldown global — mensagem de tempo restante é enviada automaticamente. | | Middlewares | client.use(async (ctx, next) => { ... }) — autenticação, logs etc. | | Coletores ultra simples | await ctx.awaitMessage() e await ctx.awaitButton(). | | Comandos encadeados | name: "admin.ban" cria /admin ban automaticamente. | | Hot reload | Atualize comandos sem reiniciar o bot. | | Dashboard integrado | Painel web embutido (http://localhost:3000). |

🚀 Quickstart

import { Client } from "easycordly.js";

const client = new Client({
  token:  process.env.TOKEN!,
  prefix: "!",
  owners: ["SEU_ID"],
  defaultCooldown: 3,
  dashboard: { port: 3000 },
  hotReload: { slash: "./dist/commands" },
});

// Comando inline — retorno automático
client.command({
  name: "ping",
  description: "Pong!",
  run: () => `🏓 Pong! ${client.ws.ping}ms`,   // string → reply
});

await client.start();

🧠 Comandos por arquivo (sem boilerplate)

src/commands/say.ts

import { SlashCommand } from "easycordly.js";

export default new SlashCommand({
  name: "say",
  description: "Repete o que você disser",
  args: {
    text: { type: "string", description: "Texto", required: true },
  },
  cooldown: 5,
  run: (ctx) => ctx.args.text,   // retorno automático
});

Carregue toda a pasta:

await client
  .loadCommands("./dist/commands")
  .then(c => c.loadPrefixCommands("./dist/prefix"))
  .then(c => c.loadEvents("./dist/events"))
  .then(c => c.start());

🔢 Argumentos tipados

client.command({
  name: "ban",
  description: "Bane um usuário",
  permissions: ["ban"],
  args: {
    membro: { type: "member", description: "Quem banir" },
    motivo: { type: "string", description: "Motivo", required: false },
    dias:   { type: "integer", min: 0, max: 7, required: false },
  },
  run: async (ctx) => {
    await ctx.args.membro.ban({ reason: ctx.args.motivo ?? "Sem motivo" });
    return ctx.success(`${ctx.args.membro} banido!`);
  },
});

Tipos disponíveis: string, number, integer, boolean, user, member, role, channel, mentionable, attachment.

Funcionam igualzinho em prefix commands (!ban @user spam) — a lib converte sozinha.

❓ Sistema de perguntas

client.command({
  name: "registrar",
  description: "Registro guiado",
  run: async (ctx) => {
    const nome  = await ctx.ask("Qual seu nome?");
    const idade = await ctx.ask("Qual sua idade?");
    return ctx.success(`Olá ${nome}, você tem ${idade} anos!`);
  },
});

Ou para coletar manualmente:

const msg    = await ctx.awaitMessage(30_000);
const button = await ctx.awaitButton("confirm", 60_000);

🎯 Eventos humanos

import { EventHandler } from "easycordly.js";

export default new EventHandler({
  event: "memberJoin",  // ou "buttonClick", "messageNew", "guildJoin"...
  run: (client, member) => console.log(`+ ${member.user.tag}`),
});

Aliases disponíveis: memberJoin, memberLeave, memberUpdate, messageNew, messageEdit, messageDelete, buttonClick, selectMenu, modalSubmit, slashRun, guildJoin, guildLeave, channelNew, channelDelete, roleNew, roleDelete, ready.

🔐 Permissões simplificadas

permissions: ["ban", "kick", "manage_messages"]

Aliases: admin, ban, kick, mute, manage_guild, manage_channels, manage_roles, manage_messages, manage_nicknames, manage_webhooks, audit_log, embed_links, attach_files, mention_everyone, add_reactions… (ver PERMISSION_ALIASES).

💬 Auto-embeds

ctx.success("Tudo certo!");
ctx.error("Algo deu errado.");
ctx.warn("Atenção!");
ctx.info("Dica útil.");

Cada um envia um embed colorido e com ícone — sem boilerplate.

📖 Paginação

import { EmbedBuilder } from "easycordly.js";

const pages = users.map((u, i) =>
  new EmbedBuilder().setTitle(`Página ${i+1}`).setDescription(u.tag)
);

await ctx.paginate(pages);

Botões ⏮ ◀ 1/N ▶ ⏭ aparecem automaticamente.

⏱ Cooldown visual

client.command({
  name: "daily",
  description: "Recompensa diária",
  cooldown: 86400,    // segundos
  run: () => "🎁 Você recebeu 100 moedas!",
});

Se o usuário tentar de novo: ⏳ Aguarde 23h 59m para usar esse comando novamente.

Ou global: defaultCooldown: 3 no Client.

🧩 Middlewares

client.use(async (ctx, next) => {
  console.log(`[CMD] ${ctx.user.tag} → ${ctx.command.name}`);
  if (ctx.command.name === "secreto" && ctx.user.id !== "OWNER") return;
  await next();
});

Encadeie quantos quiser — eles rodam antes do handler do comando.

🧵 Comandos agrupados

client.command({ name: "admin.ban",  description: "Banir",     args: { membro: { type: "member" } }, run: ... });
client.command({ name: "admin.kick", description: "Expulsar",  args: { membro: { type: "member" } }, run: ... });
client.command({ name: "admin.mute", description: "Silenciar", args: { membro: { type: "member" } }, run: ... });

Resultado no Discord:

• /admin ban @user
• /admin kick @user
• /admin mute @user

♻️ Hot reload

new Client({
  // ...
  hotReload: {
    slash:  "./dist/commands",
    prefix: "./dist/prefix",
  },
});

Edite um comando → ele recarrega automaticamente sem reiniciar o bot.

Ou manualmente:

client.enableHotReload({ slash: "./dist/commands" });

📊 Dashboard integrado

new Client({
  // ...
  dashboard: { port: 3000, token: "senha-opcional" },
});

Acesse http://localhost:3000 e veja:

• Status do bot (ping, uptime, guilds, users)
• Lista de slash commands com categoria e cooldown
• Lista de prefix commands com aliases
• Atualização automática a cada 5s

Endpoints API:

• GET /api/stats — JSON com estatísticas
• GET /api/commands — JSON com todos os comandos

🎨 Components V2, Botões, Selects, Embeds, Modals

Tudo da v1 continua funcionando — v2.container, v2.text, v2.section, v2.gallery, v2Button, Embed, Modal, StringSelect, UserSelect, RoleSelect, ChannelSelect, MentionableSelect, Row. Veja os exemplos no código.

📦 Estrutura

src/
├── client/
│   └── Client.ts           — Classe principal + middlewares + cooldown
├── structures/
│   ├── SlashCommand.ts     — Slash + args tipados + auto-build
│   ├── PrefixCommand.ts    — Prefix + args tipados + conversores
│   ├── Event.ts            — Eventos com nomes humanos
│   └── Interaction.ts      — Handler de botão/select/modal
├── managers/
│   ├── Loader.ts           — Auto-load de arquivos
│   ├── Registry.ts         — Registra slashes na API
│   └── HotReload.ts        — fs.watch nos diretórios
├── dashboard/
│   └── Dashboard.ts        — Servidor HTTP nativo (sem deps)
├── utils/
│   ├── context.ts          — Ctx, SlashCtx, PrefixCtx (ask, paginate, ...)
│   ├── permissions.ts      — Aliases de permissão
│   ├── cooldowns.ts        — CooldownManager
│   ├── eventMap.ts         — Nomes humanos de eventos
│   ├── builders.ts         — v2/Embed/Modal/Selects/Buttons
│   ├── time.ts             — Helpers de data/hora
│   └── json.ts             — JsonDB simples
└── types/index.ts          — Tipos e interfaces

Compatibilidade

A v2 é 100% compatível com bots feitos para a v1 — as APIs antigas (v2, v2Button, Embed, mentionReply, loadCommands…) continuam funcionando. As novidades são adições opcionais.

Licença

MIT