command()

command() declares a slash command, from any file of src/; its name is what people type after the /. It takes one object, CommandConfig, and types run from it. With a type, it declares a menu command instead, used with a right click on a message or a person.

src/commands/ping.ts

import { command } from 'chapterjs';

export default command({
  name: 'ping',
  description: 'Replies with Pong!',
  async run({ interaction }) {
    await interaction.reply('Pong!');
  },
});

How to write a command, its options, its answers and its translations is in the guide, and menu commands in their own page. This page lists what exists.

command<Options extends CommandOptions = {}, Where extends CommandWhere = 'guild', Type extends MenuType | undefined = undefined>(
  config: Type extends MenuType ? MenuConfig<Type, Where> : CommandConfig<Options, Where>
): Type extends MenuType ? MenuDeclaration<Type, Where> : CommandDeclaration<Options, Where>

Declares a command. Export the result from any file of src/. A slash command: name is what people type after the / ('mod ban' for /mod ban). A menu command, with type: used with a right click on a message ('message') or on a person ('user'), name being what the menu shows. Options, Where and Type are inferred from what you pass: you never write them.

CommandDeclaration

interface CommandDeclaration<Options extends CommandOptions = CommandOptions, Where extends CommandWhere = CommandWhere>

What command() returns: a declaration the framework finds in the exports of a file. It keeps the options and the place the file declared.

CommandConfig<Options, Where>

What the file gave to command(), not checked yet.

CommandConfig

What a file gives to command(): what the command is and does.

CommandName

required

What people type after the /: 'ping' is /ping. A subcommand is written with its parents: 'mod ban' is /mod ban, 'mod roles add' is /mod roles add.

string

What the command does, shown under its name (1-100 characters). Here, with locales for its translations; or left out, and every text of the command (description, options, their choices, translations) comes from the language files of the project. One or the other.

(context: CommandContext<Options, Where>) => unknown

required

What to do when someone uses the command.

CommandOptions

What the user can fill in (25 options at most).

CommandLocales<Options>

The command in other languages: Discord shows each person the names and descriptions of their language. Your code always receives the names declared above, whatever the language.Discord documentation

readonly PermissionName[]

The permissions a member needs to use the command. Server admins can change who sees it in the server settings.

CommandWhere

Where the command can be used: 'guild' (in servers, the default), 'dm' (in private messages with the bot) or 'both'. What run receives follows it.

boolean

Only show the command in age-restricted channels.

boolean

Make the answers of the command only visible to who used it.

Cooldown

How long to wait before the command can be used again: '10s' for each person, or { user, channel, guild } for each place. Someone who uses it too soon gets a private answer saying when they can.

CommandAutocomplete<Options, Where>

Suggestions that come from your bot while the person types, for the options named here (a string, integer or number option without choices): each function receives what they typed and returns the suggestions. The person may still type something else.

undefined

Leave it out for a slash command. 'message' or 'user' makes a menu command instead, used with a right click on a message or a person.

CommandName

type CommandName = string

The name of a slash command: lowercase letters, digits, - and _, 32 characters at most ('ping'). A subcommand is written with its parents, separated by spaces: 'mod ban' is /mod ban, 'mod roles add' is /mod roles add (Discord allows nothing deeper).

CommandWhere

CommandWhere = 'guild' | 'dm' | 'both'

Where a command can be used: in servers ('guild'), in private messages with the bot ('dm'), or in both. Discord documentation

Cooldown

Cooldown = Duration | { readonly user?: Duration; readonly channel?: Duration; readonly guild?: Duration }

How long to wait before the command can be used again: a duration, for each person; or one per place, each optional: user for each person, channel for each channel, guild for each server (not for a command of private messages). Someone who uses it too soon gets a private answer saying when they can, and run does not run.

Duration

Each person waits this long between two uses, wherever they are.

Duration

Each channel waits this long, whoever used it.

Duration

Each server waits this long, whoever used it, wherever.

Duration

Duration = `${number}${'s' | 'm' | 'h' | 'd'}${string}`

A duration, as a number and a unit: s, m, h or d, like '30s', '10m', '2h', '1d'. Several parts add up: '1h30m'.

The options

CommandOptions

CommandOptions = Readonly<Record<string, CommandOption>>

The options of a command, by name. A name is made of lowercase letters, digits, - and _, 32 characters at most.

CommandOption

CommandOption = StringOption | NumberOption | ChannelOption | SimpleOption

One option of a command. Every kind has these fields:

string

required

The kind of option: 'string', 'integer', 'number', 'boolean', 'user', 'role', 'channel', 'mentionable' or 'attachment'.

string

What the option is for, shown under its name (1-100 characters). Here when the command has its description here; otherwise in the default language file of the project.

boolean

Whether the user must fill it in. By default it is optional.

StringOption

A text the user types, or picks among choices.

'string'

required

The kind of option: a text.

readonly string[] | Readonly<Record<string, string>>

The only values the user can pick (25 at most): a list, or an object whose keys are what the user sees and values what your code receives.

number

The shortest text accepted, in characters (0 to 6000).

number

The longest text accepted, in characters (1 to 6000).

NumberOption

A whole number (integer) or any number (number).

'integer' | 'number'

required

The kind of option: a whole number, or any number.

readonly number[] | Readonly<Record<string, number>>

The only values the user can pick (25 at most): a list, or an object whose keys are what the user sees and values what your code receives.

number

The smallest value accepted.

number

The largest value accepted.

For an 'integer' option, min, max and the choices must be whole numbers.

ChannelOption

A channel the user picks.

'channel'

required

The kind of option: a channel.

readonly ChannelType[]

The kinds of channels that can be picked. By default, all of them. The values are those of ChannelType.

SimpleOption

True or false, a user, a role, a user or a role, or a file.

'boolean' | 'user' | 'role' | 'mentionable' | 'attachment'

required

The kind of option: what the user picks.

OptionValuesOf

OptionValuesOf<Options extends CommandOptions>

The values of the options, typed from their declaration: a required option is always there, an optional one may be undefined. It is the type of options in run.

`type`	Value
`'string'`	`string`
`'integer'`	`number`
`'number'`	`number`
`'boolean'`	`boolean`
`'user'`	`User`
`'role'`	`Role`
`'channel'`	`Channel`
`'mentionable'`	`User \| Role`
`'attachment'`	`Attachment`

With choices, the value is the union of the choices: 'red' | 'green' for choices: ['red', 'green'], 1 | 2 for choices: { Small: 1, Large: 2 }.

Autocomplete

CommandAutocomplete

CommandAutocomplete<Options extends CommandOptions, Where extends CommandWhere>

The autocomplete of a command: one function per option whose suggestions come from your bot while the person types, by the name of the option. Only a string, integer or number option without choices can have one. The function returns the suggestions (25 at most, Discord shows them in that order), or a promise of them: Discord waits 3 seconds. The person may still type something else.

{
  readonly [Name in <the options that can have suggestions>]?: (
    context: AutocompleteContext<Value, Options, Where>
  ) => readonly Suggestion<Value>[] | Promise<readonly Suggestion<Value>[]>;
}

Value is string for a string option, number | undefined for an integer or number option in the context, and string or number in the suggestions. When no option can have suggestions, no key is accepted, and the editor says why. Discord documentation

AutocompleteContext

AutocompleteContext<Value, Options extends CommandOptions, Where extends CommandWhere>

What an autocomplete function receives, each time the person types in its option. Nothing of it can be answered: the suggestions are what the function returns.

Value

required

What the person has typed so far in the option: a text, maybe empty, for a string option; for an integer or number option, a number, or undefined while what they typed is not one yet.

OptionsSoFar<Options>

required

What the person has filled in so far, this option included.

User

required

Who is typing.

Locale

required

The language of the person: suggest in it when you can.

Translator

The texts of the project in the language of the person, when the project has a language. See Translator.

The place follows where, like CommandContext without its interaction: in a server guild, member and channel (CommandInGuild); in private messages only channel (CommandInDm); with 'both', if (guild) tells which one it is (CommandInPrivate).

OptionsSoFar

OptionsSoFar<Options extends CommandOptions>

The options as the person has filled them in so far, while they type in one of them: every option may be missing, a user, role, channel, mentionable or attachment option is its id.

Suggestion

Suggestion<Value extends string | number> = Value | { name: string; value: Value }

One suggestion for an option: a value, shown as is, or { name, value } to show a text (1-100 characters) and receive another value. The value is a text (100 characters at most) for a string option, a number for an integer or number option.

string

required

What the person sees in the list (1-100 characters).

Value

required

What your run receives when they pick it.

What run receives

CommandContext

CommandContext<Options extends CommandOptions = CommandOptions, Where extends CommandWhere = 'guild'>

What the run function of a command receives. It follows where: in a server, the server, the member and the channel are there; in private messages they do not exist; in both, if (guild) tells which one it is, for everything at once. Whatever where says, it has:

OptionValuesOf<Options>

required

What the user filled in.

User

required

Who used the command.

Translator

The texts of the language files, in the right language. Only when the project has a language: see TranslationContext.

And the rest follows where:

`where`	The rest of the context
`'guild'` (the default)	`CommandInGuild`
`'dm'`	`CommandInDm`
`'both'`	`CommandInGuild \| CommandInPrivate`

CommandInGuild

What a command used in a server receives about where it was used.

GuildCommandInteraction

required

The use of the command: what to answer with.

Guild

required

The server the command was used in.

GuildMember

required

Who used the command, as a member of the server.

GuildTextBasedChannel

required

The channel the command was used in.

CommandInDm

What a command only used in private messages receives: no server.

DmCommandInteraction

required

The use of the command: what to answer with.

DMChannel

required

The private conversation the command was used in.

CommandInPrivate

What a command that works in both places receives when it is used in a private message: guild is null, and checking it tells the rest.

PrivateCommandInteraction

required

The use of the command: what to answer with.

null

required

No server: the command was used in a private message.

null

required

No member: the person is user.

DMChannel

required

The private conversation the command was used in.

The interactions themselves are described in Interaction.

Translations

CommandLocales

CommandLocales<Options extends CommandOptions = CommandOptions> = {
  readonly [Language in Locale]?: CommandTranslation<Options>;
}

The translations of a command, by language. The keys are the values of Locale: fr, de, es-ES…

CommandTranslation

The translation of a command in one language. Everything is optional: what is not translated is shown as declared.

string

The name of the command in that language (same rules as a name).

string

The description of the command in that language (1-100 characters).

{ readonly [Name in keyof Options]?: OptionTranslation }

The translation of each option, by the name declared in options.

OptionTranslation

The translation of one option. Everything is optional.

string

The name of the option in that language (same rules as a name).

string

The description of the option in that language (1-100 characters).

{ readonly [Choice: string]?: string }

What each choice is called in that language. The keys are the choices as declared: the values of a list, or the keys of an object. Each value is 1 to 100 characters.

src/commands/quote.ts

import { command } from 'chapterjs';

export const quote = command({
  type: 'message',
  name: 'Quote',
  async run({ interaction, message }) {
    await interaction.reply(`> ${message.content}`);
  },
});

MenuType

type MenuType = 'message' | 'user';

What a menu command is used on, in the menu people open with a right click (or a long press): a message ('message') or a person ('user'). Discord documentation

MenuConfig

interface MenuConfig<Type extends MenuType = 'message', Where extends CommandWhere = 'guild'>

What a file gives to command() for a menu command: one used on a message or a person, from the menu of a right click. It has no description and no options: what it receives is what it was used on.

Type

required

What the command is used on: 'message' (a right click on a message) or 'user' (a right click on a person).

string

required

What the menu shows (1-32 characters): capitals and spaces are fine, like 'Report message'.

(context: MenuContext<Type, Where>) => unknown

required

What to do when someone uses the command.

MenuLocales

The name in other languages: Discord shows each person the name of their language.Discord documentation

readonly PermissionName[]

The permissions a member needs to use the command. Server admins can change who sees it in the server settings.

CommandWhere

Where the command can be used: 'guild' (in servers, the default), 'dm' (in private messages with the bot) or 'both'. What run receives follows it.

boolean

Only show the command in age-restricted channels.

boolean

Make the answers of the command only visible to who used it.

Cooldown

How long to wait before the command can be used again: '10s' for each person, or { user, channel, guild } for each place.

never

A menu command has no description: Discord only shows its name.

never

A menu command has no options: it receives what it was used on.

never

A menu command has no options to suggest values for.

MenuDeclaration

interface MenuDeclaration<Type extends MenuType = MenuType, Where extends CommandWhere = CommandWhere>

What command() returns for a menu command.

MenuConfig<Type, Where>

What the file gave to command(), not checked yet.

MenuContext

type MenuContext<Type extends MenuType = 'message', Where extends CommandWhere = 'guild'>

What the run function of a menu command receives: what it was used on (message, or target and targetMember), who used it, and the place, which follows where like the one of a slash command (CommandInGuild, CommandInDm, CommandInPrivate).

User

required

Who used the menu.

GuildMessage | PrivateMessage | DmMessage

With type: 'message': the message the menu was used on. A GuildMessage in a server, a PrivateMessage in a private message of a where: 'both' command, a DmMessage with where: 'dm'.

User

With type: 'user': the person the menu was used on.

GuildMember | null

With type: 'user', in a server: that person as a member of the server, or null when they are not in it (any more). null in a private message; absent with where: 'dm'.

Translator

The texts of the language files, in the right language. Only when the project has a language: see TranslationContext.

MenuLocales

type MenuLocales = { readonly [Language in Locale]?: MenuTranslation }

The translations of a menu command, by language.

MenuTranslation

The translation of a menu command in one language: its name.

string

The name shown in the menu in that language (1-32 characters).

The limits

What a file declares is checked when it loads, against the limits of Discord, with a message that says what to write:

What	Limit
A name (command, option, translated name)	Lowercase letters, digits, `-` and `_`, 32 characters at most
A description (command, option, translated description)	1 to 100 characters
Depth of a command	A command, a group and a subcommand: 3 words at most in `name`
Options of a command	25 at most
Choices of an option	1 to 25, each shown as 1 to 100 characters, none twice
`minLength`, `maxLength`	Whole numbers between 0 and 6000, `minLength` not above `maxLength`
`min`, `max`	`min` not above `max`; whole numbers for an `'integer'` option
The translated names of the options	No two options with the same name in one language
`cooldown`	A duration of 1 second at least; no `guild` for a command with `where: 'dm'`
`autocomplete`	A function per option, for a `string`, `integer` or `number` option without `choices`
The name of a menu command (and its translations)	1 to 32 characters, capitals and spaces allowed, no space at either end
Menu commands	15 used on a message and 15 used on a person; a slash command, a message menu and a user menu may share a name
The suggestions (checked when sent)	25 at most (the first ones are kept), each shown as 1 to 100 characters (cut beyond), a text value of 100 characters at most, a number for a number option, whole for an `'integer'` one

Discord documentation

command()

CommandDeclaration

CommandConfig

CommandName

CommandWhere

Cooldown

Duration

The options

CommandOptions

CommandOption

StringOption

NumberOption

ChannelOption

SimpleOption

OptionValuesOf

Autocomplete

CommandAutocomplete

AutocompleteContext

OptionsSoFar

Suggestion

What run receives

CommandContext

CommandInGuild

CommandInDm

CommandInPrivate

Translations

CommandLocales

CommandTranslation

OptionTranslation

Menu commands

MenuType

MenuConfig

MenuDeclaration

MenuContext

MenuLocales

MenuTranslation

The limits