Slash commands

client.commands.register(
  {
    name: 'play',
    description: 'play a song',
    options: [{ name: 'query', type: 'string', description: 'what to play', required: true }],
  },
  async (ctx) => {
    await ctx.reply(`playing ${ctx.getString('query')}`);
  },
);

client.commands.register(
  {
    name: 'volume',
    description: 'set the playback volume',
    options: [
      {
        name: 'level',
        type: 'string',
        description: 'how loud',
        required: true,
        choices: ['quiet', 'normal', 'loud'],
      },
      { name: 'announce', type: 'boolean', description: 'say so in the channel' },
    ],
  },
  async (ctx) => {
    const level = ctx.getString('level');
    if (ctx.getBoolean('announce')) await ctx.reply(`volume set to ${level}`);
    else console.log(`[/volume] ${level} (quietly)`);
  },
);

options: [
  { name: 'query', type: 'string', description: 'what to play', required: true },
  { name: 'shuffle', type: 'boolean', description: 'shuffle the queue' },  // optional, last
]

interface CommandContext {
  name: string;
  args: Record<string, string | number | boolean | undefined>;
  source: 'structured' | 'text';
  getString(n: string): string | null;
  getInteger(n: string): number | null;
  getNumber(n: string): number | null;
  getBoolean(n: string): boolean | null;
  message: Message;
  reply(text: string, opts?: SendOptions): Promise<void>;
}

await ctx.message.channel.send('done');   // plain message, no reply notification

client.on('commandError', (e) => {
  console.warn(`/${e.name} failed (${e.reason}):`, e.error);
});

client.on('messageCreate', (msg) => {
  if (msg.authorId === client.user?.id) return;   // never answer yourself
  if (msg.command) return;                        // already handled as a command
  if (msg.isDM || !msg.serverId) return;          // this handler is server-scoped

  if (msg.content.trim() === 'help') {
    const list = client.commands.list().map((d) => `/${d.name}: ${d.description}`).join('\n');
    void msg.channel.send(`commands:\n${list}`);
  }
});

/<name> [args...]

args are, in declared order:
  bare token            -> next unfilled positional option
  "quoted token"        -> same, with spaces preserved
  optName:value         -> named; fills that option wherever it appears
  optName:"value here"  -> named, quoted

The LAST option, if type 'string', is greedy: it consumes the rest of the
line verbatim (unquoted, no escaping) once all earlier options are filled.
Booleans accept true/false/yes/no/1/0 (case-insensitive).

/volume loud announce:true
/volume quiet no
/volume normal

await client.sendCommand(serverId, channelId, 'play', { query: 'never gonna give you up' }, {
  botId: targetBotId,
});

import { Client } from '@cloak-software/bot-sdk';

const token = process.env.CLOAK_TOKEN;
if (!token) throw new Error('Set CLOAK_TOKEN (Cloak > Settings > My Bots)');

const client = new Client({
  token,
  // The bot's identity is published to the server once and cannot be replaced.
  // Without a keystore the identity is per-process: the first run works and
  // every restart afterwards fails permanently.
  keystorePath: './command-bot.cloak-keystore.json',
  requiredPermissions: ['message_send'],
});

client.commands.register(
  {
    name: 'play',
    description: 'play a song',
    options: [{ name: 'query', type: 'string', description: 'what to play', required: true }],
  },
  async (ctx) => {
    console.log(`[/play] from ${ctx.message.authorName} via the ${ctx.source} lane`);
    await ctx.reply(`playing: ${ctx.getString('query')}`);
  },
);

client.on('commandError', (e) => {
  console.warn(`/${e.name} failed (${e.reason}):`, e.error);
});

client.on('error', (e) => console.warn('[cloak-sdk]', e));
client.on('ready', () => {
  console.log(`ready as ${client.user?.id}; ${client.commands.size} commands declared`);
});

await client.login();