@oceanicjs/builders

Builders

Helpful builders for various Discord related things.

This module is specifically built to be compatible with Oceanic.

Get started by using one of our main classes, ComponentBuilder or EmbedBuilder.

Component Builder

// const { ComponentBuilder, (...) } = require("@oceanicjs/builders");
import {
	ComponentBuilder,
	ButtonColors,
	Button,
	SelectMenu,
	TextInput,
} from "@oceanicjs/builders";
import {
	ButtonStyles,
	TextInputStyles,
	MessageActionRow,
	ModalActionRow,
    ComponentTypes,
    ChannelTypes
	} from "oceanic.js";

// undefined can be used to skip uneeded parameters - don't use null!
const builder = new ComponentBuilder();

// add an interaction button (styles 1-4)
// style, customID, label, emoji, disabled
builder.addInteractionButton(ButtonStyles.PRIMARY, "some-custom-id", "My Button Label", { id: null, name: "🐾" }, false);
/*
 we have a ButtonColors export - List: 
PRIMARY   = BLURPLE
SECONDARY = GRAY
SUCCESS   = GREEN
DANGER    = RED
LINK      = URL
*/

// add a url button (style 5)
builder.addURLButton({
	disabled: false,
	emoji: { id: "681748079778463796", name: "paws8", animated: false },
	label: "Click Here",
	url: "https://google.com"
});

// for emojis, we have a helper to convert full emoji strings, or code points into a partial emoji (this method is static)
// emoji, type (default/custom)
ComponentBuilder.emojiToPartial("🐾", "default") // { id: null, name: "🐾", animated: false }
ComponentBuilder.emojiToPartial("<:paws8:681748079778463796>", "custom") // { id: "681748079778463796", name: "paws8", animated: false }
ComponentBuilder.emojiToPartial("<a:owoanim:768551122066472990>", "custom") // { id: "768551122066472990", name: "owoanim", animated: true }

// if the current row has a component in it already, this method will automatically create a new row and add the select menu in that row, the create another row for you to continue using in other methods
// add a select menu
builder.addSelectMenu({
    channelTypes: [ChannelTypes.GUILD_TEXT, ChannelTypes.GUILD_ANNOUNCEMENT],
	customID: "some-custom-id",
	disabled: false,
	maxValues: 3,
	minValues: 1,
	options: [],
	placeholder: "Some Placeholder Here",
    type: ComponentTypes.CHANNEL_SELECT
});
// see https://discord.com/developers/docs/interactions/message-components#select-menu-object-select-option-structure for options structure

// add a text input
builder.addTextInput({
	customID: "some-custom-id",
	label: "Some Label Here",
	maxLength: 100,
	minValue: 20,
	placeholder: "Some Placeholder Here",
	required: true,
	style: TextInputStyles.SHORT,
	value: "Initial Value"
});
// currently SHORT & PARAGRAPH exist

// remove all currently present empty rows (this is already done while converting to JSON)
builder.removeEmptyRows();

// convert all of the added content into JSON, ready to be used as a components property in a message/modal
builder.toJSON();

// most things have a Raw variant, which returns json that can be sent directly to Discord
builder.toJSONRaw();


// a few other things, if you want to add a new row at any time, just call..
builder.addRow();
// this also accepts an array of components, if you want to add them while creating the row

// if you want to construct the components yourself, you can add them via these methods
builder.addComponent(new Button(ButtonColors.RED, "some-custom-id"));
// add in bulk (these will be passed through addComponent one at a time, in order)
builder.addComponents([
	new Button(ButtonStyles.LINK, "https://google.com"),
	new SelectMenu("some-custom-id"),
	new TextInput(TextInputStyles.PARAGRAPH, "Some Label", "some-custom-id")
]);
// these classes all come with their own methods to change things about them, please refer to the code for a list of them. They are all well documented.

// if you want to limit the maxium amount of items we'll put in a row to a different number than 5, you can provide that in the ComponentBuilder constructor, or call setRowLimit
const builder3 = new ComponentBuilder(3);
builder3.setRowMax(2);
// for those of you out there wanting to break things - we don't validate numbers, break it all you want

// for typescript compatibility, you can cast to either MessageActionRow or ModalActionRow. toJSON accepts a generic parameter for this.
builder.toJSON<MessageActionRow>();
builder.toJSON<ModalActionRow>();

// you can also specify it when creating the builder.
const componentBuilder = new ComponentBuilder<MessageActionRow>();
const modalBuilder = new ComponentBuilder<ModalActionRow>();

Embed Builder

// const { EmbedBuilder } = require("@oceanicjs/builders");
import { EmbedBuilder } from "@oceanicjs/builders";

// undefined can be used to skip uneeded parameters - don't use null!
const embed = new EmbedBuilder();

// set author - name, icon url, url
embed.setAuthor("Hello", "https://i.furry.cool/DonPeek.png", "https://furry.cool");
// the get/remove helper methods exist for most functions
console.log(embed.getAuthor()); // { name: "Hello", iconURL: "https://i.furry.cool/DonPeek.png", url: "https://furry.cool" }
embed.removeAuthor();

// set color, accepts a number
embed.setColor(0xFFA500);

// set description
embed.setDescription("hi this is some description content");
console.log(embed.getDescription()); // hi this is some description content"
embed.setDescription("separate parameters will be", "joined by newlines");
console.log(embed.getDescription()); // separate parameters will be
// joined by newlines
embed.setDescription(["arrays are also", "accepted"], ["these will also be", "joined by newlines"]);
console.log(embed.getDescription()); // arrays are also
// accepted
// these will also be
// joined by newlines

// add a field - name, value, inline (optional)
embed.addField("field name", "field value");
embed.addField("field name", "field value", true);
embed.addField("field name", "field value", false);

// add a field with a blank name & value (zero width space) - inline
embed.addBlankField();
embed.addBlankField(true);
embed.addBlankField(false);

// add multiple fields manually
// you can provide embeds as separate parameters, a single array argument, multiple arrays as separate parameters, or a mix of both
embed.addFields({ name: "field name", value: "field value" }, { name: "field name", value: "field value" });
embed.addFields([{ name: "field name", value: "field value" }, { name: "field name", value: "field value" }]);
embed.addFields({ name: "field name", value: "field value" }, [{ name: "field name", value: "field value", inline: true }, { name: "field name", value: "field value", inline: false }]);
embed.addFields([{ name: "field name", value: "field value", inline: true }, { name: "field name", value: "field value", inline: false }], { name: "field name", value: "field value" });
embed.addFields([{ name: "field name", value: "field value", inline: false }, { name: "field name", value: "field value", inline: true }], [{ name: "field name", value: "field value", inline: true }, { name: "field name", value: "field value", inline: false }]);

// set the footer - text, icon url
embed.setFooter("hi", "https://i.furry.cool/DonPride.png");

// set the image - url
embed.setImage("https://i.furry.cool/DonCoffee.png");

// set the timestamp - time (accepts iso timestamp, a Date instance, or "now")
embed.setTimestamp("now");
// to retrieve current value as a Date: getTimestampDate

// set the title - title
embed.setTitle("some title stuff");

// set the url - url
embed.setURL("https://furry.cool");

// convert the embed to a json object
const json = embed.toJSON();
// convert the embed into a json object, inside of an array
const jsonArray = embed.toJSON(true);

// to load an embed from json, use the static loadFromJSON method - this accepts both a singular embed, and multiple embeds
const load1 = EmbedBuilder.loadFromJSON({ title: "embed #1" }); // EmbedBuilder
const load2 = EmbedBuilder.loadFromJSON([ { title: "embed #1" }, { title: "embed #2" } ]); // [EmbedBuilder, EmbedBuilder]
// if you still want to load from an array, but want a singular instance returned, you can set the forceSingular parameter to true
// this will throw away anything but the first embed
const load1FromArray = EmbedBuilder.loadJSON([ { title: "embed #1" } ], true); // EmbedBuilder 

Application Commands

// const { ApplicationCommandBuilder } = require("@oceanicjs/builders");
import { 
    ApplicationCommandBuilder,
    ApplicationCommandOptionBuilder
    } from "@oceanicjs/builders";
import {
    ApplicationCommandTypes,
    Permission,
    ApplicationCommandOptionTypes,
    ChannelTypes
} from "oceanic.js";

const chatInput = new ApplicationCommandBuilder(ApplicationCommandTypes.CHAT_INPUT, "slash-command");

// to allow or disallow usage in dms
chatInput.allowDMUsage(); // setDMPermission(true)
chatInput.disallowDMUsage(); // setDMPermission(false)

// set the default permissions required to use the command
// this accepts: bigint, string, Permission instance (from oceanic), array of permission names, permission names as arguments
chatInput.setDefaultMemberPermissions(3n);
chatInput.setDefaultMemberPermissions("3");
chatInput.setDefaultMemberPermissions(new Permission(3n));
chatInput.setDefaultMemberPermissions(["CREATE_INVITE", "KICK_MEMBERS"]);
chatInput.setDefaultMemberPermissions("CREATE_INVITE", "KICK_MEMBERS"); // provided as separate parameters

// set the description - required for chat input commands
chatInput.setDescription("Some random command");

// set the description localizations - this overrides any present localizations
chatInput.setDescriptionLocalizations({
    "es-ES": "Algún comando aleatorio"
});

// you can also add localizations individually
chatInput.addDescriptionLocalization("de", "irgendein zufälliger Befehl");

// set the name, if you want to change the earlier value for some reason
chatInput.setName("slash-command-test");

// set the name localizations - this overrides any present localizations
chatInput.setNameLocalizations({
    "es-ES": "barra-comando-prueba"
});

// you can also add localizations individually
chatInput.addNameLocalization("de", "schrägstrich-befehlstest");

// options - the add method can be used in various different ways
chatInput.addOption("option1", ApplicationCommandOptionTypes.STRING, {
    description: "Some option.",
    descriptionLocalizations: {
        "es-ES": "Alguna opción.",
        "de": "Einige Optionen."
    },
    nameLocalizations: {
        "es-ES": "opción1",
        "de": "option1"
    },
    required: true,
    choices: [ // setChoices(choices) & addChoice(name, value, nameLocalizations?)
        {
            name: "choice-1",
            value: "one",
            nameLocalizations: {
                "es-ES": "elección-1",
                "de": "wahl-1"
            }
        }
    ]
});
// or, if you prefer to use methods, you can do that too
chatInput.addOption("option2", ApplicationCommandOptionTypes.STRING, (option) => {
    // option is a new ApplicationCommandOptionBuilder instance with prefilled name & type values
    option.setDescription("Another option.")
          .setDescriptionLocalizations({
            "es-ES": "Otra opción."
          })
          .addDescriptionLocalization("de", "Andere Option.")
          .setNameLocalizations({
            "es-ES": "opción2"
          })
          .addNameLocalization("de", "option2")
          .setRequired()
          .setAutocomplete();

    // nothing needs to be returned, any return will be discarded
});

// you can also construct the ApplicationCommandOptionBuilder instance yourself
const option = new ApplicationCommandOptionBuilder(ApplicationCommandOptionTypes.CHANNEL, "channel-option")
    .setDescription("An option that accepts a channel.")
    .setDescriptionLocalizations({
        "es-ES": "Una opción que acepta un canal."
    })
    .addDescriptionLocalization("de", "Eine Option, die einen Kanal akzeptiert.")
    .setNameLocalizations({
        "es-ES": "opción-de-canal"
    })
    .addNameLocalization("de", "kanaloption")
    .setRequired(false) // same as not specifying at all
    .setChannelTypes([ChannelTypes.GUILD_TEXT, ChannelTypes.GUILD_ANNOUNCEMENT]);
    // if you want to convert the option to json for usage elsewhere, a .toJSON() method exists
chatInput.addOption(option);

// you can also do everything yourself, if you feel so inclined
chatInput.addOption({
    name: "integer-option",
    type: ApplicationCommandOptionTypes.INTEGER,
    description: "I'm tired of writing examples",
    descriptionLocalizations: {
        // Discord has no way to chose fem/masc
        "es-ES": "Estoy cansada de escribir ejemplos",
        "de": "Ich bin es leid, Beispiele zu schreiben"
    },
    nameLocalizations: {
        "es-ES": "opción-de-entero",
        "de": "integer-option"
    },
    minValue: 1, // for the builder, this is setMinMax(min, max) - this is for both values & length
    maxValue: 5
});

Install

npm i @oceanicjs/builders