JustDiscord

Simple Discord API package for Node.js.

npm install @jnode/discord

Basic Usage

Import JustDiscord

const discord = require('@jnode/discord');

Create a Client

const client = new discord.Client('BOT_TOKEN');

Connect to Discord Gateway

client.connectGateway((gateway) => {
    // receive Discord gateway "READY" event
    gateway.on('READY', (d) => {
        console.log('Connected to Discord.');
    });
});

Class: Client

The main class for interacting with the Discord API and Gateway.

Constructor

new discord.Client(token, options = {})

• token: Your Discord bot token.
• options: An optional object for setting various client options:
  • apiVersion: The Discord API version. Default is 10.
  • apiBase: The base URL of the Discord API. Default is discord.com/api.
  • apiAutoRetry: Whether to auto-retry requests when receiving a 429 error. Default is true.
  • apiThrowError: Whether to throw errors when the API status code is not 2xx. Default is true.
  • gatewayIntents: The gateway intents used for connecting to the Gateway. Default is 0b11111111111111111000110011. You can find more about intents in the Discord Developer Documentation.
  • gatewayUrl: The base URL for the Discord Gateway. Default is wss://gateway.discord.gg.
  • gatewayReconnectDelay: The delay (in milliseconds) before attempting to reconnect to the gateway. Default is 5000. Set to less than 0 to disable auto-reconnect.
  • gatewayConnectTimeout: The timeout (in milliseconds) before giving up on connecting to the gateway. Default is 5000. Set to less than 0 to disable connect timeout.
  • gatewayThrowError: Whether to throw errors when the gateway encounters an issue. Default is true.

Methods

• apiUrl(path): Returns the full API URL with the base, version, and given path.

  • path: API endpoint path. Example: /channels/123456789.
  • Returns: string - The full API URL. Example: https://discord.com/api/v10/channels/123456789.

• async apiRequest(method = 'GET', path = '/', body): Makes an HTTP request to the Discord API, find out more at Discord Developer Documentation.

  • method: HTTP method (e.g. GET, POST, PUT, DELETE). Default is GET.
  • path: API endpoint path. Default is /. Example: /channels/123456789/messages.
  • body: Request body data (will be stringified). Example: { content: 'Hello, Discord!' }.
  • Returns: Promise<RequestResponse> - A promise that resolves to a RequestResponse object.
  • Example:

  client.apiRequest('POST', '/channels/123456789/messages', { content: 'Hello, Discord!' })
  .then(res => {
      if (res.statusCode === 200) {
          console.log('Message sent successfully!');
      } else {
          console.error('Failed to send message:', res.statusCode, res.text());
      }
  }).catch(err => {
      console.error('Error sending message:', err);
  });

• async apiRequestMultipart(method = 'GET', path = '/', body, attachments = []): Makes a multipart HTTP request to the Discord API.

  • method: HTTP method (e.g. GET, POST, PUT, DELETE). Default is GET.
  • path: API endpoint path. Default is /. Example: /channels/123456789/messages.
  • body: Request body data (will be stringified). Example: { content: 'Hello, Discord!' }.
  • attachments: An array of attachments, each attachment is an object:
    • name: Name of the file. Example: image.png
    • type (Optional): Content type of the data. Defaults to application/octet-stream.
    • data (Option 1): Data (string or Buffer) of this file.
    • file (Option 2): Path to a local file.
    • encoded/base64 (Option 3): base64 encoded data string.
    • stream (Option 4): Any readable stream.
  • Returns: Promise<RequestResponse> - A promise that resolves to a RequestResponse object.
  • Example:

  const fs = require('fs').promises;
  
  async function uploadFile(channelId, filePath) {
      const fileData = await fs.readFile(filePath);
      const fileType = 'image/png';
      const fileName = 'my_image.png';
  
      client.apiRequestMultipart('POST', `/channels/${channelId}/messages`, { content: 'Here\'s an image!' }, [{
          name: fileName,
          type: fileType,
          data: fileData
      }]).then(res => {
          if (res.statusCode === 200) {
              console.log('File uploaded successfully!');
          } else {
              console.error('Failed to upload file:', res.statusCode, res.text());
          }
      }).catch(err => {
          console.error('Error uploading file:', err);
      });
  }
  uploadFile('123456789', './my_image.png');

• async connectGateway(cb): Connects to the Discord Gateway.

  • cb: A callback function that takes a gateway object as an argument.
  • Returns: Promise<Gateway> - A promise that resolves to a Gateway object.
  • Example:

  client.connectGateway((gateway) => {
      gateway.on('READY', (data) => {
          console.log('Connected to Discord, user id:', data.user.id);
      });
      gateway.on('MESSAGE_CREATE', (message) => {
          if (message.content === '!ping') {
             console.log('Recieve Ping Message')
          }
      });
  });

Class: Gateway

Manages the Discord Gateway connection for receiving real-time events. You can find more about gateway events in the Discord Developer Documentation.

Events

• socketOpened: Emitted when the WebSocket connection is opened.
  • event: A WebSocket event object.
• socketClosed: Emitted when the WebSocket connection is closed.
  • event: A WebSocket event object.
• socketError: Emitted when a WebSocket error occurs.
  • event: A WebSocket event object.
• socketMessage: Emitted when a raw WebSocket message is received.
  • event: A WebSocket event object.
• message: Emitted when a complete JSON payload is received.
  • data: A JSON object.
• Discord Gateway Event (READY, MESSAGE_CREATE... etc.): The gateway will auto dispatch discord events. Check Discord Developer Documentation for all avaliable events. The event callback will be a data object from discord.

Methods

• async getGatewayUrl(): Retrieves the gateway URL from the Discord API.

  • Returns: Promise<string> - A promise that resolves to the gateway URL.

• connect(): Opens the WebSocket connection to the Discord Gateway.

• sendMessage(op, d = null): Sends a message to the Discord Gateway.

  • op: Opcode of the message. Check Discord Developer Documentation for all avaliable opcodes.
  • d: Payload of the message.
  • Example:

  gateway.sendMessage(1, {}); //send heartbeat
  gateway.sendMessage(2, { //Identify
      token: 'BOT_TOKEN',
      properties: {
          os: process.platform,
          browser: 'Node.js',
          device: 'JustDiscord'
      },
      intents: 0b11111111111111111000110011 //replace with your intents
  });

Class: DiscordAPIError

An error that is thrown when the Discord API returns a non-2xx status code.

Properties

• message: The error message.
• body: The response body.
• headers: The response headers.

Helper functions

• RequestResponse class with properties like:
  • statusCode: Status code.
  • headers: Response headers.
  • text(encoding): Return response body in string, with optional encoding. Example: res.text('utf-8').
  • json(): Return response body in JSON format, or undefined when cannot parse JSON. Example: res.json().