Moderation bot

import { Client, CloakActionError, userMention, roleMention } from '@cloak-software/bot-sdk';

const client = new Client({
  token: process.env.CLOAK_TOKEN!,
  // The bot's identity is published to the server once. Without this file the
  // first run works and every restart after it fails permanently.
  keystorePath: './mod-bot.cloak-keystore.json',
  requiredPermissions: [
    'message_send',
    'message_read_history',
    'message_manage',
    'reaction_add',
    'member_timeout',
    'member_ban',
  ],
  debug: process.env.DEBUG === '1',
});

client.on('ready', async () => {
  console.log(`Logged in as bot ${client.user?.id}`);
  // Presence is persisted account-side, so this is a set-once. Do not re-send
  // it on a timer or after a reconnect.
  await client.setStatus('online').catch((e) => console.error('setStatus', e));
});

client.on('messageCreate', async (msg) => {
  if (msg.authorId === client.user?.id) return; // ignore our own messages
  // messageCreate is unified: a DM arrives here too, with isDM true and a null
  // serverId. Moderation is a server concept, so bail out first.
  if (msg.isDM || !msg.serverId) return;

  const [cmd, ...args] = msg.content.trim().split(/\s+/);
  // A server-scoped handle for every action below.
  const g = client.guild(msg.serverId);

  try {
    // A mention is two halves. userMention() is the pill, which is literal text
    // inside the encrypted body. `mentions` is the ping, a plaintext target the
    // server routes the notification from. Send both, or one of them does
    // nothing at all.
    if (msg.mentionsMe) {
      await msg.reply(`${userMention(msg.authorId)} you rang?`, {
        mentions: [{ userId: msg.authorId }],
      });
      return;
    }

    switch (cmd) {
      case '!ping':
        // React to the command message instead of answering it.
        await msg.react('👍');
        break;

      case '!roles': {
        const roles = await g.fetchRoles();
        // Lower position sorts higher, so ascending is rank order.
        const lines = roles
          .sort((a, b) => (a.position ?? 99) - (b.position ?? 99))
          .map((r) => `${r.name} (${r.memberCount} members)`);
        await msg.reply(lines.length ? lines.join('\n') : 'no roles');
        break;
      }

      case '!bans': {
        const bans = await g.fetchBans();
        await msg.reply(
          bans.length
            ? bans.map((b) => `${b.username ?? b.userId}: ${b.reason || '(no reason)'}`).join('\n')
            : 'no bans',
        );
        break;
      }

      case '!history': {
        const n = Math.min(100, Number(args[0]) || 20);
        const history = await g.fetchMessages(msg.channelId, { limit: n });
        const authors = new Set(history.map((m) => m.authorId));
        await msg.reply(`last ${history.length} messages, ${authors.size} distinct authors`);
        break;
      }

      case '!purge': {
        const n = Math.min(50, Number(args[0]) || 0);
        if (!n) return void (await msg.reply('usage: !purge <n>'));
        // fetchMessages returns fully actionable Messages. Delete the newest n,
        // excluding the command message itself, which is too new to appear.
        // Slow and multi round trip, so show the typing dots while it runs.
        await client.sendTyping(msg.serverId, msg.channelId);
        try {
          const doomed = (await g.fetchMessages(msg.channelId, { limit: n })).reverse();
          for (const m of doomed) {
            await m.delete();
            // Re-assert every few deletes: receivers expire the dots after ~10s.
            // Repeats inside the SDK's throttle window are dropped for free.
            await client.sendTyping(msg.serverId, msg.channelId);
          }
          await msg.reply(`purged ${doomed.length} messages`);
        } finally {
          // An indicator left on lingers for about 10 seconds. Clearing it is
          // the whole reason the false argument exists.
          await client.sendTyping(msg.serverId, msg.channelId, false).catch(() => {});
        }
        break;
      }

      case '!timeout': {
        const [userId, seconds] = args;
        if (!userId || !seconds) return void (await msg.reply('usage: !timeout <userId> <seconds>'));
        await g.timeout(userId, Number(seconds));
        await msg.react('⏳');
        break;
      }

      case '!pin': {
        if (!msg.repliedTo) return void (await msg.reply('reply to the message you want pinned'));
        const target = (
          await g.fetchMessages(msg.channelId, { around: msg.repliedTo.createdAt ?? new Date() })
        ).find((m) => m.messageId === msg.repliedTo?.messageId);
        if (!target) return void (await msg.reply('could not locate that message'));
        await target.pin();
        await msg.react('📌');
        break;
      }

      case '!announce': {
        const text = args.join(' ');
        if (!text) return void (await msg.reply('usage: !announce <text>'));
        // Advisory pre-gate. The server is authoritative and silently drops
        // pings it will not route.
        if (!client.can('mention_roles', msg.serverId)) {
          return void (await msg.reply(
            `no mention_roles here, say it to ${roleMention('Moderators')} yourself`,
          ));
        }
        await g.send(msg.channelId, `@everyone ${text}`, { mentions: ['everyone'] });
        break;
      }
    }
  } catch (e) {
    if (e instanceof CloakActionError) {
      const perm = e.permission ? ` (missing ${e.permission})` : '';
      msg.reply(`denied: ${e.message}${perm}`).catch(() => {});
    } else {
      console.error(cmd, e);
    }
  }
});

// Observe the moderation-relevant events. These fire for the bot's own actions too.
client.on('messageDelete', (e) => console.log(`message ${e.messageId} deleted in ${e.channelId}`));
client.on('pinUpdate', (e) => console.log(`message ${e.messageId} ${e.pinned ? 'pinned' : 'unpinned'}`));
client.on('reactionUpdate', (e) => console.log(`reaction ${e.reactionId} x${e.count} on ${e.messageId}`));
client.on('channelCreate', (e) => console.log(`channel ${e.name} created in ${e.serverId}`));

// Typing is a firehose across every visible channel, and it echoes the bot's
// own sendTyping back. serverId and channelId are always null.
client.on('typing', (e) => {
  if (e.userId === client.user?.id) return;
  console.log(`${e.userId} is ${e.isTyping ? 'typing' : 'no longer typing'} (channel unknown)`);
});

client.login().catch((e) => {
  console.error('login failed', e);
  process.exit(1);
});