🇺🇸 English

✨ Features

• 🚀 Minimal Setup — Start a bot with just a few lines of code
• 🎯 Fluent API — Chained builders for commands, embeds and components
• 🔌 Plugin System — Modular and extensible architecture
• 🛡️ Middlewares — Rate limit, cooldown, permissions and more
• 🌍 i18n — Full internationalization support
• 💾 Cache Manager — Built-in cache system
• 🎨 Components V2 — Support for new Discord components
• 🧪 Testing Utils — Ready-to-use mocks for testing
• 🔥 Hot Reload — Auto reload in development
• 🎭 Decorators — Modern TypeScript decorator syntax

📦 Installation

npm install zcord.js discord.js

🚀 Quick Start

import { ZcordClient } from "zcord.js";

const bot = new ZcordClient({
  intents: "standard", // or "all", "minimal", or GatewayIntentBits[]
  presence: {
    status: "online",
    activities: [{ name: "with Zcord.js", type: "playing" }]
  }
});

await bot.start("YOUR_TOKEN");

📝 Creating Slash Commands

Fluent API

import { cmd } from "zcord.js";

const ping = cmd("ping")
  .slash()
  .description("Shows bot latency")
  .exec(async (interaction) => {
    await interaction.reply(`🏓 Pong! ${interaction.client.ws.ping}ms`);
  });

// Command with options and permissions
const ban = cmd("ban")
  .slash()
  .description("Bans a user")
  .user("target", "User to ban", true)
  .string("reason", "Ban reason")
  .require("BanMembers")
  .cooldown(5)
  .error("🚫 You don't have permission!")
  .exec(async (interaction) => {
    const target = interaction.options.getUser("target", true);
    await interaction.reply(`${target.username} has been banned!`);
  });

// Add to bot
bot.commands.add(ping);
bot.commands.add(ban);
await bot.commands.deploy(); // Global deploy
// or: await bot.commands.deploy("GUILD_ID"); // Guild deploy (instant)

createCommand Style

import { createCommand } from "zcord.js";

createCommand({
  name: "ping",
  description: "Shows latency",
  run: async (interaction) => {
    await interaction.reply(`🏓 ${interaction.client.ws.ping}ms`);
  }
});

// With subcommands
const config = createCommand({
  name: "config",
  description: "Bot settings"
});

config.subcommand({
  name: "view",
  description: "View settings",
  run: async (i) => i.reply("Current settings...")
});

config.subcommand({
  name: "set",
  description: "Change setting",
  options: [
    { type: "string", name: "key", description: "Key", required: true },
    { type: "string", name: "value", description: "Value", required: true }
  ],
  run: async (i) => {
    const key = i.options.getString("key", true);
    const value = i.options.getString("value", true);
    await i.reply(`Set ${key} = ${value}`);
  }
});

🎨 Fluent Embeds

import { embed } from "zcord.js";

const msg = embed()
  .title("🎉 Welcome!")
  .description("Thanks for using **Zcord.js**")
  .color("#5865F2")
  .thumbnail(user.displayAvatarURL())
  .field("📊 Servers", "150", true)
  .field("👥 Users", "10,000", true)
  .footer("Zcord.js • Simple and powerful")
  .timestamp()
  .row()
    .button("✅ Confirm", "confirm").green()
    .button("❌ Cancel", "cancel").red()
    .link("🌐 Website", "https://example.com")
  .done()
  .build();

await interaction.reply(msg);

🔘 Interaction Handlers

Fluent Handlers

import { createHandlers } from "zcord.js";

const handlers = createHandlers()
  .button("confirm", async (i) => {
    await i.reply({ content: "Confirmed!", ephemeral: true });
  })
  .select("colors", async (i) => {
    await i.reply(`You chose: ${i.values.join(", ")}`);
  })
  .modal("feedback", async (i) => {
    const text = i.fields.getTextInputValue("feedback-input");
    await i.reply(`Feedback received: ${text}`);
  });

bot.useHandlers(handlers);

createResponder (with parameters)

import { createResponder, ResponderType } from "zcord.js";

// Simple button
createResponder({
  customId: "confirm",
  types: [ResponderType.Button],
  run: async (interaction) => {
    await interaction.reply("Confirmed!");
  }
});

// Button with parameters
createResponder({
  customId: "delete/:id/:type",
  types: [ResponderType.Button],
  run: async (interaction, { id, type }) => {
    await interaction.reply(`Deleting ${type} ${id}`);
  }
});

// Select menu
createResponder({
  customId: "select-role",
  types: [ResponderType.StringSelect],
  run: async (interaction) => {
    await interaction.reply(`Selected: ${interaction.values[0]}`);
  }
});

🔌 Plugin System

import { createPlugin, ZcordClient } from "zcord.js";

const economyPlugin = createPlugin({
  name: "economy",
  version: "1.0.0",
  
  setup(bot) {
    console.log("Economy plugin loaded!");
  },
  
  onReady(ctx) {
    console.log(`Bot online with ${ctx.client.guilds.cache.size} guilds`);
  },
  
  // Plugin commands
  commands: [
    {
      name: "balance",
      description: "Check your balance",
      run: async (i) => i.reply("Balance: $1000")
    }
  ],
  
  // Plugin middlewares
  middlewares: [
    async (ctx, next) => {
      console.log(`[Economy] ${ctx.type}`);
      await next();
    }
  ]
});

const bot = new ZcordClient();
bot.plugin(economyPlugin);
await bot.start("TOKEN");

🛡️ Middlewares

import { 
  ZcordClient, 
  loggingMiddleware, 
  rateLimitMiddleware,
  cooldownMiddleware,
  guildOnlyMiddleware 
} from "zcord.js";

const bot = new ZcordClient();

// Simple middleware
bot.use(async (ctx, next) => {
  console.log(`[${ctx.type}] ${ctx.interaction.user.username}`);
  await next();
});

// Built-in middlewares
bot.use(loggingMiddleware({ detailed: true }));
bot.use(rateLimitMiddleware({ maxRequests: 10, window: 60000 }));
bot.use(cooldownMiddleware({ default: 3000 }));
bot.use(guildOnlyMiddleware());

// Global error handler
bot.onError(async (error, ctx) => {
  console.error(`Error in ${ctx.type}:`, error);
});

📡 Events

import { createEvent } from "zcord.js";

createEvent({
  name: "Bot Ready",
  event: "ready",
  run: async (client) => {
    console.log(`Logged in as ${client.user.tag}`);
  }
});

createEvent({
  name: "Welcome",
  event: "guildMemberAdd",
  run: async (member) => {
    const channel = member.guild.systemChannel;
    if (channel) {
      await channel.send(`Welcome ${member}!`);
    }
  }
});

🌍 Internationalization (i18n)

import { createI18n } from "zcord.js";

const i18n = createI18n({
  defaultLocale: "en-US",
  translations: {
    "en-US": {
      greeting: "Hello, {name}!",
      commands: { ping: { description: "Shows latency" } }
    },
    "pt-BR": {
      greeting: "Olá, {name}!",
      commands: { ping: { description: "Mostra latência" } }
    }
  }
});

const text = i18n.t("greeting", "en-US", { name: "John" });
// "Hello, John!"

🎭 Decorators (TypeScript)

import { 
  SlashCommand, 
  Execute, 
  StringOption,
  RequirePermissions,
  Cooldown,
  GuildOnly
} from "zcord.js";

@SlashCommand({ name: "echo", description: "Repeats a message" })
@RequirePermissions("SendMessages")
@Cooldown(5000)
@GuildOnly()
class EchoCommand {
  @StringOption({ name: "text", description: "Text to repeat", required: true })
  
  @Execute()
  async run(interaction: ChatInputCommandInteraction) {
    const text = interaction.options.getString("text", true);
    await interaction.reply(text);
  }
}

🔥 Hot Reload (Development)

import { createHotReload, createDevServer } from "zcord.js";

const hotReload = createHotReload({
  paths: ["./src/commands", "./src/events"],
  onReload: (file) => console.log(`Reloaded: ${file}`)
});

const devServer = createDevServer({
  port: 3000,
  client: bot.discord
});

🇧🇷 Português

✨ Funcionalidades

• 🚀 Setup Mínimo — Inicie um bot com poucas linhas de código
• 🎯 API Fluente — Builders encadeados para comandos, embeds e componentes
• 🔌 Sistema de Plugins — Arquitetura modular e extensível
• 🛡️ Middlewares — Rate limit, cooldown, permissões e mais
• 🌍 i18n — Suporte completo a internacionalização
• 💾 Cache Manager — Sistema de cache integrado
• 🎨 Components V2 — Suporte aos novos componentes do Discord
• 🧪 Testing Utils — Mocks prontos para testes
• 🔥 Hot Reload — Recarregamento automático em desenvolvimento
• 🎭 Decorators — Sintaxe moderna com decorators TypeScript

📦 Instalação

npm install zcord.js discord.js

🚀 Início Rápido

import { ZcordClient } from "zcord.js";

const bot = new ZcordClient({
  intents: "standard", // ou "all", "minimal", ou GatewayIntentBits[]
  presence: {
    status: "online",
    activities: [{ name: "com Zcord.js", type: "playing" }]
  }
});

await bot.start("SEU_TOKEN");

📝 Criando Slash Commands

API Fluente

import { cmd } from "zcord.js";

const ping = cmd("ping")
  .slash()
  .description("Mostra a latência do bot")
  .exec(async (interaction) => {
    await interaction.reply(`🏓 Pong! ${interaction.client.ws.ping}ms`);
  });

// Comando com opções e permissões
const ban = cmd("ban")
  .slash()
  .description("Bane um usuário")
  .user("target", "Usuário para banir", true)
  .string("reason", "Motivo do ban")
  .require("BanMembers")
  .cooldown(5)
  .error("🚫 Você não tem permissão!")
  .exec(async (interaction) => {
    const target = interaction.options.getUser("target", true);
    await interaction.reply(`${target.username} foi banido!`);
  });

// Adicionar ao bot
bot.commands.add(ping);
bot.commands.add(ban);
await bot.commands.deploy(); // Deploy global
// ou: await bot.commands.deploy("GUILD_ID"); // Deploy em guild (instantâneo)

Estilo createCommand

import { createCommand } from "zcord.js";

createCommand({
  name: "ping",
  description: "Mostra latência",
  run: async (interaction) => {
    await interaction.reply(`🏓 ${interaction.client.ws.ping}ms`);
  }
});

// Com subcommands
const config = createCommand({
  name: "config",
  description: "Configurações do bot"
});

config.subcommand({
  name: "view",
  description: "Ver configurações",
  run: async (i) => i.reply("Configurações atuais...")
});

config.subcommand({
  name: "set",
  description: "Alterar configuração",
  options: [
    { type: "string", name: "key", description: "Chave", required: true },
    { type: "string", name: "value", description: "Valor", required: true }
  ],
  run: async (i) => {
    const key = i.options.getString("key", true);
    const value = i.options.getString("value", true);
    await i.reply(`Configurado ${key} = ${value}`);
  }
});

🎨 Embeds Fluentes

import { embed } from "zcord.js";

const msg = embed()
  .title("🎉 Bem-vindo!")
  .description("Obrigado por usar **Zcord.js**")
  .color("#5865F2")
  .thumbnail(user.displayAvatarURL())
  .field("📊 Servidores", "150", true)
  .field("👥 Usuários", "10.000", true)
  .footer("Zcord.js • Simples e poderoso")
  .timestamp()
  .row()
    .button("✅ Confirmar", "confirm").green()
    .button("❌ Cancelar", "cancel").red()
    .link("🌐 Site", "https://exemplo.com")
  .done()
  .build();

await interaction.reply(msg);

🔘 Handlers de Interação

Handlers Fluentes

import { createHandlers } from "zcord.js";

const handlers = createHandlers()
  .button("confirm", async (i) => {
    await i.reply({ content: "Confirmado!", ephemeral: true });
  })
  .select("colors", async (i) => {
    await i.reply(`Você escolheu: ${i.values.join(", ")}`);
  })
  .modal("feedback", async (i) => {
    const text = i.fields.getTextInputValue("feedback-input");
    await i.reply(`Feedback recebido: ${text}`);
  });

bot.useHandlers(handlers);

createResponder (com parâmetros)

import { createResponder, ResponderType } from "zcord.js";

// Botão simples
createResponder({
  customId: "confirm",
  types: [ResponderType.Button],
  run: async (interaction) => {
    await interaction.reply("Confirmado!");
  }
});

// Botão com parâmetros
createResponder({
  customId: "delete/:id/:type",
  types: [ResponderType.Button],
  run: async (interaction, { id, type }) => {
    await interaction.reply(`Deletando ${type} ${id}`);
  }
});

// Select menu
createResponder({
  customId: "select-role",
  types: [ResponderType.StringSelect],
  run: async (interaction) => {
    await interaction.reply(`Selecionado: ${interaction.values[0]}`);
  }
});

🔌 Sistema de Plugins

import { createPlugin, ZcordClient } from "zcord.js";

const economyPlugin = createPlugin({
  name: "economy",
  version: "1.0.0",
  
  setup(bot) {
    console.log("Plugin economy carregado!");
  },
  
  onReady(ctx) {
    console.log(`Bot online com ${ctx.client.guilds.cache.size} guilds`);
  },
  
  // Comandos do plugin
  commands: [
    {
      name: "balance",
      description: "Verifica seu saldo",
      run: async (i) => i.reply("Saldo: R$1000")
    }
  ],
  
  // Middlewares do plugin
  middlewares: [
    async (ctx, next) => {
      console.log(`[Economy] ${ctx.type}`);
      await next();
    }
  ]
});

const bot = new ZcordClient();
bot.plugin(economyPlugin);
await bot.start("TOKEN");

🛡️ Middlewares

import { 
  ZcordClient, 
  loggingMiddleware, 
  rateLimitMiddleware,
  cooldownMiddleware,
  guildOnlyMiddleware 
} from "zcord.js";

const bot = new ZcordClient();

// Middleware simples
bot.use(async (ctx, next) => {
  console.log(`[${ctx.type}] ${ctx.interaction.user.username}`);
  await next();
});

// Middlewares prontos
bot.use(loggingMiddleware({ detailed: true }));
bot.use(rateLimitMiddleware({ maxRequests: 10, window: 60000 }));
bot.use(cooldownMiddleware({ default: 3000 }));
bot.use(guildOnlyMiddleware());

// Handler de erro global
bot.onError(async (error, ctx) => {
  console.error(`Erro em ${ctx.type}:`, error);
});

📡 Eventos

import { createEvent } from "zcord.js";

createEvent({
  name: "Bot Ready",
  event: "ready",
  run: async (client) => {
    console.log(`Logado como ${client.user.tag}`);
  }
});

createEvent({
  name: "Welcome",
  event: "guildMemberAdd",
  run: async (member) => {
    const channel = member.guild.systemChannel;
    if (channel) {
      await channel.send(`Bem-vindo ${member}!`);
    }
  }
});

🌍 Internacionalização (i18n)

import { createI18n } from "zcord.js";

const i18n = createI18n({
  defaultLocale: "pt-BR",
  translations: {
    "pt-BR": {
      greeting: "Olá, {name}!",
      commands: { ping: { description: "Mostra latência" } }
    },
    "en-US": {
      greeting: "Hello, {name}!",
      commands: { ping: { description: "Shows latency" } }
    }
  }
});

const text = i18n.t("greeting", "pt-BR", { name: "João" });
// "Olá, João!"

🎭 Decorators (TypeScript)

import { 
  SlashCommand, 
  Execute, 
  StringOption,
  RequirePermissions,
  Cooldown,
  GuildOnly
} from "zcord.js";

@SlashCommand({ name: "echo", description: "Repete uma mensagem" })
@RequirePermissions("SendMessages")
@Cooldown(5000)
@GuildOnly()
class EchoCommand {
  @StringOption({ name: "text", description: "Texto para repetir", required: true })
  
  @Execute()
  async run(interaction: ChatInputCommandInteraction) {
    const text = interaction.options.getString("text", true);
    await interaction.reply(text);
  }
}

🔥 Hot Reload (Desenvolvimento)

import { createHotReload, createDevServer } from "zcord.js";

const hotReload = createHotReload({
  paths: ["./src/commands", "./src/events"],
  onReload: (file) => console.log(`Recarregado: ${file}`)
});

const devServer = createDevServer({
  port: 3000,
  client: bot.discord
});

📄 License / Licença

MIT © Zcord.js