@jnode/discord

Simple Discord API package for Node.js.

Note: This package requires Node.js v22.4.0 or later to use the built-in WebSocket for Discord gateway connections.

Installation

npm i @jnode/discord

Quick start

Import

const { Client, Attachment } = require('@jnode/discord');

Start a simple "Ping-Pong" bot

const client = new Client('YOUR_BOT_TOKEN');

// Initialize the gateway to receive events
const gateway = client.gateway({
  intents: 3276799 // All intents (ensure they are enabled in dev portal)
});

// Listen for message events
gateway.on('MESSAGE_CREATE', async (message) => {
  if (message.content === '!ping') {
    // Send a reply using the REST client
    await client.request('POST', `/channels/${message.channel_id}/messages`, {
      content: 'Pong!'
    });
  }
});

Sending files (Attachments)

const fs = require('fs');

async function sendImage(channelId) {
  const fileData = fs.readFileSync('./image.png');
  const image = new Attachment('image.png', 'image/png', fileData);

  await client.request('POST', `/channels/${channelId}/messages`, 
    { content: 'Here is your image!' },
    [image] // Pass attachments as an array
  );
}

How it works?

@jnode/discord provides a lightweight wrapper around the Discord REST API and WebSocket Gateway.

1. REST Client (Client): Handles all HTTP requests to Discord (messages, channel management, etc.). It includes built-in support for rate-limit auto-retries and multipart/form-data for file uploads.
2. Gateway (Gateway): An EventEmitter that maintains a WebSocket connection to Discord. it handles heartbeats, identifies your bot, and emits events when things happen on Discord (like a new message or a member joining).

We keep it simple: no heavy abstractions, just the tools you need to interact with the API directly.

Reference

Class: discord.Client

The main controller for interacting with the Discord REST API.

new discord.Client(token[, options])

• token <string> Your Discord Bot token.
• options <Object>
  • baseUrl <string> The API root. Default: 'https://discord.com/api/v10'.
  • autoRetry <boolean> Whether to automatically wait and retry when hit by a 429 Rate Limit. Default: true.

client.request(method, path[, body, attachments, options])

• method <string> HTTP method (e.g., 'GET', 'POST', 'PATCH'). Default: 'GET'.
• path <string> The API endpoint path (e.g., '/channels/123/messages').
• body <Object> The JSON payload to send.
• attachments <discord.Attachment[]> An array of attachment objects for file uploads.
• options <Object>
  • auditLog <string> Reason to be displayed in the Discord Audit Log.
  • headers <Object> Additional HTTP headers.
  • requestOptions <Object> Options passed to the underlying @jnode/request.
• Returns: <Promise> Fulfills with the parsed JSON response, or null if status is 204.

client.gateway([options])

• options <Object> Options for the gateway (see discord.Gateway).
• Returns: <discord.Gateway> A new gateway instance.

Class: discord.Gateway

• Extends: <EventEmitter>

Handles the WebSocket connection to receive real-time events.

new discord.Gateway(client[, options])

• client <discord.Client> An instance of the Discord client.
• options <Object>
  • intents <number> Gateway intents bitmask. Default: 3276799 (All non-privileged).
  • reconnectDelay <number> Delay (ms) before reconnecting after a close. Default: 5000.
  • connectTimeout <number> Timeout (ms) for the initial connection. Default: 5000.
  • apiVersion <number> Discord Gateway version. Default: 10.
  • heartbeatJitter <number> Coefficient for heartbeat interval jitter. Default: 0.9.
  • heartbeatAckTimeout <number> Timeout (ms) to wait for a heartbeat ACK before closing. Default: 3000.
  • presence <Object> Initial presence information.
  • shard <number[]> Array of two integers [shard_id, num_shards].

gateway.send(op[, d])

• op <number> Gateway Opcode.
• d [<any>] Data payload.

Sends a raw event through the gateway.

gateway.close()

Closes the WebSocket connection.

Event: 'socketOpen'

Emitted when the WebSocket connection is established.

Event: 'socketClose'

• event [<CloseEvent>]

Emitted when the WebSocket connection is closed.

Event: 'message'

• data <Object>

Emitted for every raw message received from the gateway.

Event: <DISPATCH_EVENT_NAME>

• data <Object>

Emitted when a specific Discord Dispatch event is received (Opcode 0). E.G., 'READY', 'MESSAGE_CREATE', 'GUILD_CREATE'.

Event: 'error'

• err <Error>

Emitted when a critical gateway error occurs (e.g., invalid token).

Class: discord.Attachment

Represents a file to be uploaded.

new discord.Attachment(filename, type, body)

• filename <string> The name of the file (e.g., 'photo.jpg').
• type <string> The MIME type (e.g., 'image/jpeg').
• body <Buffer> | <string> The actual file content.