Internal API Specification

Exhaustive API specification covering every property, method, and signature on the Medusa instance.

This reference documents every property, service, method signature, and parameter exposed across Medusa. Every building block receives this instance as this.medusa.

Root Medusa Properties

Property	Type	Description
`product`	`string`	Constant product name (`"Medusa"`).
`version`	`string`	Running version string (e.g. `"1.0.0.0"`).
`startedAt`	`Dayjs`	Day.js timestamp representing the start time of the bot.
`running`	`boolean`	`true` once boot sequence completes and modules are active.
`stopping`	`boolean`	`true` while the shutdown lifecycle is executing.
`license`	`object \| null`	License metadata returned from validation servers.
`message`	`string \| null`	Licensing alert message or `null`.
`config`	`Config`	Root configuration manager for `config.json`.
`console`	`Layout`	Structured console logging and ANSI color builder.
`events`	`EventEmitter`	Global event emitter (`medusa.ready`, `medusa.discord.ready`, etc.).
`database`	`Database`	Sequelize database manager and connection supervisor.
`settings`	`Settings`	Key-value settings database storage manager.
`locales`	`Locales`	Localization catalog for all 16 supported languages.
`embeds`	`Embeds`	Standard Discord embed message builder and dispatcher.
`emojis`	`Emojis`	Discord application emoji registry and custom icons.
`logs`	`Logs`	Discord audit logging channel dispatcher.
`permissions`	`Permissions`	Role, user, and rank authorization supervisor.
`audit`	`Audit`	System audit log database manager.
`modules`	`Modules`	Module manager, registry, and subsystem loader.
`leaderboards`	`Leaderboards`	Leaderboard provider registry and pagination engine.
`docs`	`Docs`	In-dashboard module documentation filesystem reader.
`data`	`Data`	On-disk file storage manager in the root `data/` directory.
`api`	`Api`	Express HTTP REST API server on port 3001.
`discord`	`Discord`	Discord.js client manager and gateway supervisor.
`dashboard`	`Dashboard`	Next.js web dashboard process supervisor.
`zero`	`Zero`	Zero Development licensing and update connection API.

Root Medusa Methods

`hasAddon(name)`

Checks whether the active server license includes a specific commercial addon.

Signature: hasAddon(name: string): boolean

Example:

if (this.medusa.hasAddon("Economy")) {
}

`emitAsync(event, ...args)`

Sequentially invokes all asynchronous listeners registered on this.medusa.events.

Signature: emitAsync(event: string, ...args: any[]): Promise<void>

`wait(ms)`

Promise-based execution delay helper.

Signature: wait(ms: number): Promise<void>
Example:
```
await this.medusa.wait(2000);
```

`restart()`

Performs a graceful shutdown and triggers process restart with exit code 75.

Signature: restart(): Promise<void>

`stop(code)`

Gracefully stops all modules, clocks, Discord sessions, HTTP servers, and database connections.

Signature: stop(code?: number): Promise<void>

`installPackages(...packages)`

Checks node_modules for missing npm packages and installs them automatically using bun add or npm install.

Signature: installPackages(...packages: string[]): Promise<void>

Subsystem Accessors (`this.medusa.modules`)

Models (`this.medusa.modules.models`)

get(module: string, name: string): Models | null

Handlers (`this.medusa.modules.handlers`)

get(module: string, name: string): Handlers | null

Routes (`this.medusa.modules.routes`)

get(module: string, name: string): Routes | null

Commands (`this.medusa.modules.commands`)

get(module: string, name: string): Commands | null
find(name: string): Commands | null - Searches all loaded modules.

Events (`this.medusa.modules.events`)

get(module: string, name: string): Events | null

Clocks (`this.medusa.modules.clocks`)

get(module: string, name: string): Clocks | null

Configuration (`this.medusa.modules.config`)

get(module: string, name: string): Configs | null
value(module: string, name: string, key: string): any
values(module: string, name: string): object

Language & Phrases (`this.medusa.modules.lang`)

get(module: string, name: string): Langs | null
value(module: string, name: string, key: string): any
values(module: string, name: string): object
phrase(module: string, name: string, key: string, tokens?: object): string
embed(module: string, name: string, key: string, tokens?: object): EmbedBuilder

Logs (`this.medusa.modules.logs`)

get(module: string, name: string): Logs | null

Custom Pages (`this.medusa.modules.pages`)

get(module: string, name: string): Pages | null
list(): Array<object>

Leaderboards (`this.medusa.modules.leaderboards`)

get(module: string, name: string): Leaderboards | null
all(): Array<{ module: string, provider: Leaderboards, descriptor: object }>

Automation Nodes (`this.medusa.modules.nodes`)

get(module: string, name: string): Nodes | null
all(): Array<{ module: string, node: Nodes, descriptor: object }>

Embeds Service (`this.medusa.embeds`)

Method	Signature	Description
`success(text)`	`(text: string) => EmbedBuilder`	Returns an embed with green `#22c55e` accent and check emoji.
`warn(text)`	`(text: string) => EmbedBuilder`	Returns an embed with amber `#f59e0b` accent and warning emoji.
`error(text)`	`(text: string) => EmbedBuilder`	Returns an embed with red `#ef4444` accent and cross emoji.
`info(emoji, message, colour)`	`(emoji: string, message: string, colour?: string) => EmbedBuilder`	Returns an embed with custom emoji and optional hex color.
`resolve(template, tokens, options)`	`(template: object, tokens?: object, options?: object) => EmbedBuilder`	Resolves embed object with token replacements, footer, and timestamp.
`normalize(template)`	`(template: object) => object`	Normalizes author, footer, thumbnail, image, and color into valid Discord structure.
`hex(value)`	`(value: any) => string \| null`	Formats number or text string into a normalized 6-character hex code (`"#22c55e"`).
`fill(value, tokens)`	`(value: any, tokens?: object) => any`	Recursively replaces `%key%`, `<key>`, and custom emoji placeholders across strings, arrays, and objects.
`serverName()`	`() => string`	Returns configured server name or Discord guild name.
`serverIcon()`	`() => string \| null`	Returns server icon URL or bot avatar URL.
`footerName()`	`() => string`	Returns server name if watermark addon is present; otherwise returns product name.
`send(channelId, content, template, tokens, buttons, selectMenu, components, flags, embeds)`	`(channelId: string, ...) => Promise<Message>`	Dispatches complete message with embeds and interactive components.
`buildComponents(buttons, selectMenu, rawComponents)`	`(buttons?: Array, selectMenu?: object, rawComponents?: Array) => Array`	Builds Discord action rows containing buttons and select menus.

Emoji Registry (`this.medusa.emojis`)

Method	Signature	Description
`get(name)`	`(name: string) => string`	Returns custom Discord emoji markup (e.g. `<:check:12345>`) or empty string.
`has(name)`	`(name: string) => boolean`	Checks whether an emoji name exists in the registry.
`names()`	`() => Array<string>`	Returns all 130+ registered preset emoji names.
`sync()`	`() => Promise<void>`	Uploads missing preset icons to Discord application emojis.

Discord Supervisor (`this.medusa.discord`)

Property / Method	Signature	Description
`client`	`Client`	Underlying Discord.js `Client` instance.
`ready()`	`() => boolean`	Returns `true` if Discord client is authenticated and connected to the gateway.
`resources()`	`() => Promise<object>`	Fetches `{ guildId, channels, categories, roles, emojis, serverIcon }`.
`post(channelId, payload)`	`(channelId: string, payload: object) => Promise<Message>`	Posts a message to a text channel.
`temporary(channelId, payload, seconds)`	`(channelId: string, payload: object, seconds: number) => Promise<Message>`	Posts a message that automatically deletes after the specified duration.
`setUsername(username)`	`(username: string) => Promise<void>`	Updates the Discord bot account username.
`setAvatar(avatar)`	`(avatar: Buffer \| string) => Promise<void>`	Updates the Discord bot account avatar image.
`setPresence(config)`	`(config: object) => void`	Updates Discord presence activity, status, and rotating messages.
`prefix()`	`() => string`	Reads the active prefix for prefix-based commands.

Permissions Supervisor (`this.medusa.permissions`)

Method	Signature	Description
`guard(interaction, node)`	`(interaction: Interaction, node: string) => Promise<boolean>`	Evaluates member permissions. If denied, automatically responds with an ephemeral error embed and returns `false`.
`allowed(member, node)`	`(member: GuildMember, node: string) => boolean`	Evaluates whether a member is authorized for a command or interaction node.
`deny(interaction)`	`(interaction: Interaction) => Promise<void>`	Sends the localized denial embed as an ephemeral reply.
`ranks()`	`() => Array<object>`	Returns all configured permission ranks.
`held(memberOrUserId)`	`(memberOrUserId: any) => Array<object>`	Returns all ranks held by a member based on roles and user ID.
`abilities(memberOrUserId)`	`(memberOrUserId: any) => { grantAll: boolean, abilities: Array<string> }`	Resolves dashboard permissions held by the member.
`allowedDashboard(memberOrUserId, node)`	`(memberOrUserId: any, node: string) => boolean`	Checks whether user has permission to view a dashboard page.

System Audit (`this.medusa.audit`)

Method	Signature	Description
`record(entry)`	`(entry: { type: string, actorId?: string, actorTag?: string, command?: string, success?: boolean, detail?: object, guildId?: string }) => Promise<void>`	Records an audit entry to the database. Queues in memory if database is temporarily offline.
`list(filter)`	`(filter?: { guildId?: string, type?: string, limit?: number }) => Promise<Array<object>>`	Queries audit history ordered descending by creation date.

Disk Storage (`this.medusa.data`)

Method	Signature	Description
`module(id, ...segments)`	`(id: string, ...segments: string[]) => string`	Resolves safe path inside `data/<module>/`.
`path(...segments)`	`(...segments: string[]) => string`	Resolves safe path inside root `data/`.
`ensure(...segments)`	`(...segments: string[]) => string`	Creates directory structure recursively if it does not exist.
`exists(...segments)`	`(...segments: string[]) => boolean`	Checks whether file or directory exists.
`remove(...segments)`	`(...segments: string[]) => void`	Deletes file or directory recursively.

Settings Storage (`this.medusa.settings`)

Method	Signature	Description
`get(key)`	`(key: string) => any`	Reads setting value from in-memory cache.
`set(key, value)`	`(key: string, value: any) => Promise<any>`	Writes value to memory and upserts to database table `medusa_settings`.
`delete(key)`	`(key: string) => Promise<void>`	Removes setting from memory and database.
`all()`	`() => object`	Returns full key-value map of all stored settings.
`reload()`	`() => Promise<number>`	Reloads all settings from the database into memory cache.

Global Settings Catalog

Setting Key	Type	Description
`BOT_ID`	`string`	Discord client ID of the bot application.
`GUILD_ID`	`string`	Primary Discord server snowflake ID.
`DISCORD_TOKEN`	`string`	Discord bot secret token.
`ACCENT_COLOUR`	`string`	Default hex color applied across embeds and UI.
`LANGUAGE`	`string`	Active language code (`"en"`, `"fr"`, `"de"`, etc.).
`SERVER_NAME`	`string`	Custom server name override for messages.
`DASHBOARD_NAME`	`string`	Custom branding name for the web dashboard.
`API_KEYS`	`Array<object>`	Registered external API authentication keys.
`ALLOWED_IPS`	`Array<string>`	Whitelisted client IP addresses.
`MODULES`	`Array<string>`	List of disabled module folder names.
`COMMANDS`	`object`	Custom command prefixes and enabled toggles.
`PERMISSIONS`	`object`	Configured rank priorities, roles, and ability maps.
`module:<id>`	`object`	Configuration values bucket for module `<id>`.
`lang:<id>`	`object`	Language overrides bucket for module `<id>`.
`logs:<id>`	`object`	Channel assignments and toggles for module `<id>`.

Localization Catalog (`this.medusa.locales`)

Method	Signature	Description
`list()`	`() => Array<object>`	Returns all 16 supported language objects with `code`, `name`, `native`, and `discord` mappings.
`codes()`	`() => Array<string>`	Returns array of all 16 locale code strings.
`active()`	`() => string`	Returns the currently active language code from settings.
`isSupported(code)`	`(code: string) => boolean`	Checks if a language code is supported.
`moduleName(id, locale)`	`(id: string, locale?: string) => string`	Resolves localized module display name from `module.<id>.name` in `common.json`.

Database Supervisor (`this.medusa.database`)

Property / Method	Signature	Description
`sequelize`	`Sequelize`	Active Sequelize ORM database connection.
`healthy`	`boolean`	`true` when database connection is live and passing health ticks.
`sync(options)`	`(options?: object) => Promise<void>`	Synchronizes all Sequelize models and runs column migrations.
`close()`	`() => Promise<void>`	Closes database connections cleanly.

Structured Console (`this.medusa.console`)

Property / Method	Signature	Description
`log(level, text)`	`(level: string, text: string) => void`	Logs formatted, timestamped output to stdout and daily log file.
`levels`	`object`	Severity levels: `{ info, success, warning, error, debug, startup }`.
`colors`	`Colors`	ANSI color painter: `colors.green(text)`, `colors.red(text)`, `colors.bright.bold.white(text)`, etc.
`error(target, extra, footer)`	`(target: Error \| string, extra?: string, footer?: string) => void`	Renders a styled ASCII error panel with stack trace and issue location.

Internal API Specification

On this page