Utilities

Cross-cutting core utilities: embed builders, permissions, audit records, Discord helpers, and settings.

Every building block receives the shared root medusa instance in its constructor (this.medusa). This instance provides direct access to all shared utilities across the bot.

Embed Builder (`this.medusa.embeds`)

The embeds utility creates standardized Discord embeds, processes variable tokens, and dispatches messages with components.

Status Message Presets

Generate consistent status embeds using built-in presets:

const ok = this.medusa.embeds.success("The operation completed successfully.");

const warn = this.medusa.embeds.warn("This action will expire in 5 minutes.");

const err = this.medusa.embeds.error("You lack the required permissions.");

const info = this.medusa.embeds.info("clock", "Maintenance scheduled tonight.", "#3b82f6");

Custom Embeds (`resolve()`)

Build customized embeds with token substitution:

const embed = this.medusa.embeds.resolve({
    title: "Server Balance Overview",
    description: "Current stats for **%user%** in <server>.",
    color: "#22c55e",
    fields: [
        { name: "Wallet", value: "$%wallet%", inline: true },
        { name: "Bank", value: "$%bank%", inline: true }
    ]
}, {
    user: interaction.user.username,
    wallet: "1,500",
    bank: "25,000"
});

Variable Token Replacements

The fill() method replaces standard variables across strings, arrays, and objects:

Token	Replacement Value
`%server%`, `<server>`, `%guild_name%`	Server display name.
`%server_icon%`, `%guild_icon%`	Guild icon URL.
`%user_avatar%`, `%bot_avatar%`	Bot avatar URL.
`%brand_icon%`	Configured custom brand icon URL or server icon.
`%version%`, `<version>`	Current Medusa version string.
`%name%`, `<name>`	Dashboard or product name.
`%custom_emoji_<name>%`	Custom emoji string resolved from Medusa's emoji registry.
`%<key>%`, `<key>`	Custom token passed in the `tokens` argument.

Sending Messages (`send()`)

Dispatch messages directly to text channels:

await this.medusa.embeds.send(
    channelId,
    "Optional text content",
    embedTemplate,
    { user: "Alex" },
    [
        { style: "success", label: "Claim", customId: "claim_btn" },
        { style: "link", label: "Dashboard", url: "https://zerodev.ca" }
    ]
);

Emoji Registry (`this.medusa.emojis`)

Medusa includes a catalog of over 130 preset icons uploaded directly to Discord as application emojis:

const coinEmoji = this.medusa.emojis.get("coin");
const checkEmoji = this.medusa.emojis.get("check");

if (this.medusa.emojis.has("hammer")) {
    console.log("Hammer emoji is registered.");
}

const availableNames = this.medusa.emojis.names();

Discord Client (`this.medusa.discord`)

Direct access to the Discord connection manager and the underlying Discord.js Client:

if (this.medusa.discord.ready()) {
    const client = this.medusa.discord.client;
}

await this.medusa.discord.post(channelId, {
    content: "System message."
});

await this.medusa.discord.temporary(channelId, {
    content: "This message will self-destruct in 10 seconds."
}, 10);

const resources = await this.medusa.discord.resources();

const prefix = this.medusa.discord.prefix();

Permissions (`this.medusa.permissions`)

Check and enforce authorization for commands, interactions, and dashboard views:

const allowed = await this.medusa.permissions.guard(interaction, "manage");
if (!allowed) return;

const canExecute = this.medusa.permissions.allowed(interaction.member, "economy:manage");

const hasAccess = this.medusa.permissions.allowedDashboard(userId, "overview");

const ranks = this.medusa.permissions.ranks();

Audit Records (`this.medusa.audit`)

Record operational actions to the system database audit log viewable in the dashboard:

await this.medusa.audit.record({
    type: "module",
    actorId: interaction.user.id,
    actorTag: interaction.user.tag,
    command: "item:purchase",
    success: true,
    detail: {
        item: "Sword",
        price: 150
    },
    guildId: interaction.guild.id
});

Querying Audit Records

const logs = await this.medusa.audit.list({
    guildId: interaction.guild.id,
    type: "module",
    limit: 50
});

Module Storage (`this.medusa.data`)

Manage persistent files stored on disk inside the root data/ directory:

const filePath = this.medusa.data.module(this.module, "cache", "export.json");

this.medusa.data.ensure(this.module, "backups");

if (this.medusa.data.exists(this.module, "cache", "export.json")) {
    console.log("File exists.");
}

this.medusa.data.remove(this.module, "cache");

Global Settings (`this.medusa.settings`)

Read and write runtime key-value settings stored in the database:

const accentColour = this.medusa.settings.get("ACCENT_COLOUR");

await this.medusa.settings.set("ACCENT_COLOUR", "#3b82f6");

await this.medusa.settings.delete("TEMPORARY_SETTING");

const allSettings = this.medusa.settings.all();

Structured Console Logging (`this.medusa.console`)

Log structured, timestamped messages to the console with ANSI color formatting:

const { levels, colors } = this.medusa.console;

this.medusa.console.log(levels.info, "General informative message.");
this.medusa.console.log(levels.success, colors.bright.green("Task completed successfully."));
this.medusa.console.log(levels.warning, colors.yellow("Deprecated method called."));
this.medusa.console.log(levels.error, colors.red("Fatal operation error."));
this.medusa.console.log(levels.startup, colors.bright.cyan("Subsystem mounted."));

Utilities

On this page