# Utilities

URL: https://zerodev.ca/docs/medusa/developer-documentation/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:

```js
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.");
```

Every preset prefixes the text with its custom emoji and a `•` separator. A leading Markdown heading (`#`, `##`, `###`) is converted to bold text, since Discord only renders a heading as the first character of a description.

### Embed Colour

Every embed is coloured with the global `ACCENT_COLOUR` setting so it matches the accent-coloured custom emojis. A `color` value in a template or a module colour option is kept for design purposes but is overridden with the accent colour when the embed is resolved. Components V2 containers follow the same rule for `accent_color`.

### Custom Embeds (`resolve()`)

Build customized embeds with token substitution:

```js
const embed = this.medusa.embeds.resolve({
    title: "Server Balance Overview",
    description: "Current stats for **%user%** in <server>.",
    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:

```js
await this.medusa.embeds.send(
    channelId,
    "Optional text content",
    embedTemplate,
    { user: "Alex" },
    [
        { style: "secondary", 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:

```js
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`:

```js
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:

```js
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:

```js
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

```js
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:

```js
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:

```js
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:

```js
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."));
```