cord

⚠️ Work in progress. cord is in early development — APIs may change and not all features are stable yet.

A minimal Discord bot library built directly on top of the Discord API — no abstractions you didn't ask for.

import { Bot } from '@neozmmv/cord';

const bot = new Bot(process.env.TOKEN!);

bot.addCommand('ping', 'Replies with Pong!', async (ctx) => {
  await ctx.sendMessage(`Pong! Hey ${ctx.user.username}`);
});

await bot.run();

Why cord?

Most Discord libraries hide everything. cord gives you a clean API without taking away control.

• No manual command registration — addCommand handles it automatically on startup
• No boilerplate — one file, one bot, done
• TypeScript-first — full autocomplete on ctx, commands, and payloads
• Direct API — built on raw WebSocket + REST, no hidden magic
• Event system — listen to any Discord Gateway event with full type safety

Installation

bun add @neozmmv/cord
# or
npm install @neozmmv/cord

Requires Bun or Node.js 18+

Getting Started

1. Create a bot on the Discord Developer Portal

2. Set up your .env:

TOKEN=your_bot_token_here

3. Create your bot:

import { Bot } from '@neozmmv/cord';

const bot = new Bot(process.env.TOKEN!);

bot.addCommand('ping', 'Check if the bot is alive', async (ctx) => {
  await ctx.sendMessage('Pong!');
});

await bot.run();
console.log(`Online as ${bot.user?.username}`);

Commands

bot.addCommand(name, description, handler, guildId?)

Registers a slash command. Pass a guildId to register instantly in a specific server, or omit it for global registration (up to 1 hour to propagate).

// global command
bot.addCommand('help', 'Shows help', async (ctx) => {
  await ctx.sendMessage('Here is the help menu...');
});

// guild-only (instant)
bot.addCommand('admin', 'Admin only', async (ctx) => {
  await ctx.sendMessage('Admin panel');
}, process.env.GUILD_ID);

Command names must be lowercase and can only contain letters and numbers.

Chaining

bot
  .addCommand('ping', 'Ping the bot', pingHandler)
  .addCommand('help', 'Show help', helpHandler)
  .addCommand('info', 'Server info', infoHandler);

Context (slash commands)

Every command handler receives a ctx object:

bot.addCommand('info', 'Get info', async (ctx) => {
  ctx.commandName        // "info"
  ctx.user.username      // who used the command
  ctx.user.id            // their Discord ID
  ctx.guildId            // server ID
  ctx.channelId          // channel ID
  ctx.channel.name       // channel name
  ctx.locale             // user's locale ("en-US", "pt-BR", ...)

  await ctx.sendMessage('Hello!');
  await ctx.sendMessage('Only you can see this!', { ephemeral: true });
  await ctx.editMessage('Updated message!');
});

Events

Listen to any Discord Gateway event with bot.on(). Every event is fully typed — autocomplete works out of the box.

import { Bot, Event } from '@neozmmv/cord';

bot.on(Event.MESSAGE_CREATE, async (ctx) => {
  if (ctx.content === '!hello') {
    const msgId = await ctx.sendMessage(`Hello, ${ctx.author.global_name}!`);
    await ctx.editMessage(msgId, 'Edited!');
  }
});

bot.on(Event.GUILD_MEMBER_ADD, (ctx) => {
  console.log(`New member: ${ctx.user.username}`);
});

Multiple handlers for the same event are supported:

bot.on(Event.MESSAGE_CREATE, handlerOne);
bot.on(Event.MESSAGE_CREATE, handlerTwo); // both will be called

Available Events

Event.READY
Event.RESUMED
Event.CHANNEL_CREATE / UPDATE / DELETE / PINS_UPDATE
Event.GUILD_CREATE / UPDATE / DELETE
Event.GUILD_BAN_ADD / REMOVE
Event.GUILD_EMOJIS_UPDATE / STICKERS_UPDATE
Event.GUILD_MEMBER_ADD / UPDATE / REMOVE
Event.MESSAGE_CREATE / UPDATE / DELETE / DELETE_BULK
Event.MESSAGE_REACTION_ADD / REMOVE / REMOVE_ALL
Event.PRESENCE_UPDATE
Event.TYPING_START
Event.VOICE_STATE_UPDATE / SERVER_UPDATE
Event.INTERACTION_CREATE
Event.THREAD_CREATE / UPDATE / DELETE / MEMBER_UPDATE

Message Context

Handlers for Event.MESSAGE_CREATE receive a MessageContext with helper methods:

bot.on(Event.MESSAGE_CREATE, async (ctx) => {
  ctx.content          // message content
  ctx.author.username  // who sent the message
  ctx.channelId        // channel ID
  ctx.guildId          // server ID

  const msgId = await ctx.sendMessage('Pong!');
  await ctx.editMessage(msgId, 'Pong! (edited)');
});

Intents

cord includes sensible defaults — Guilds, GuildMessages, MessageContent, and GuildMembers. You can customize:

import { Bot, Intent } from '@neozmmv/cord';

// use defaults
const bot = new Bot(process.env.TOKEN!);

// custom intents
const bot = new Bot(process.env.TOKEN!, [
  Intent.Guilds,
  Intent.GuildMessages,
  Intent.GuildVoiceStates,
]);

// extend defaults
const bot = new Bot(process.env.TOKEN!, [
  ...Bot.DEFAULT_INTENTS,
  Intent.GuildVoiceStates,
]);

Some intents like MessageContent and GuildMembers are privileged and must be enabled in the Discord Developer Portal.

How it works

cord connects directly to the Discord Gateway via WebSocket and manages the full lifecycle:

connect → HELLO → IDENTIFY → READY → register commands → listen for events

The heartbeat is handled automatically — your bot stays connected.

License

MIT