2.7.2 • Published 2 weeks ago

easycordly.js

Licence

MIT

Version

2.7.2

Deps

Size

786 kB

Vulns

Weekly

Summary Dependency Versions

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