create-chapterjs 0.2.2 → 0.3.0

package/templates/community/src/stats/weekly.ts

@@ -0,0 +1,50 @@
+import { ChannelType, task } from 'chapterjs';
+import { communityChannel } from '../welcome/channel';
+
+// A task runs by itself: every Monday at 9:00, in the timezone given. The
+// name of the export is the name of the task. `t` is the default language.
+export const weekly = task({
+  cron: '0 9 * * 1',
+  timezone: 'Europe/Paris',
+  async run({ guilds, t }) {
+    for (const guild of guilds.values()) {
+      const channel = communityChannel(guild, 'general');
+      if (!channel) continue;
+      const channels = [...guild.channels.values()];
+      await channel.send({
+        embeds: [
+          {
+            title: t('statsTitle', { server: guild.name }),
+            color: 0xc026d3,
+            fields: [
+              {
+                name: t('members'),
+                value: String(guild.memberCount ?? '?'),
+                inline: true,
+              },
+              {
+                name: t('textChannels'),
+                value: String(
+                  channels.filter(c => c.type === ChannelType.GuildText).length
+                ),
+                inline: true,
+              },
+              {
+                name: t('voiceChannels'),
+                value: String(
+                  channels.filter(c => c.type === ChannelType.GuildVoice).length
+                ),
+                inline: true,
+              },
+              {
+                name: t('roles'),
+                value: String(guild.roles.size - 1),
+                inline: true,
+              },
+            ],
+          },
+        ],
+      });
+    }
+  },
+});

package/templates/community/src/welcome/channel.ts

@@ -0,0 +1,19 @@
+import type { Guild, TextChannel } from 'chapterjs';
+
+// Plain code, shared by the other files: the channel the bot writes in.
+// The one named like `name` when there is one, else the system channel of
+// the server (where Discord itself says who joined), else nothing.
+export function communityChannel(
+  guild: Guild,
+  name: string
+): TextChannel | null {
+  const channels = [...guild.channels.values()];
+  const named = channels.find(
+    channel => channel.isText() && channel.name === name
+  );
+  if (named?.isText()) return named;
+  const system = guild.systemChannelId
+    ? guild.channels.get(guild.systemChannelId)
+    : undefined;
+  return system?.isText() ? system : null;
+}

package/templates/community/src/welcome/welcome.ts

@@ -0,0 +1,37 @@
+import { embed, event, type GuildMember } from 'chapterjs';
+import { communityChannel } from './channel';
+
+// Runs when someone joins the server. It needs the Server Members Intent:
+// chapterjs dev tells you where to enable it the first time.
+export default event({
+  name: 'memberJoin',
+  async run({ member, guild, t }) {
+    const channel = communityChannel(guild, 'welcome');
+    if (!channel) return;
+    await channel.send({
+      content: t('welcome', { user: member.toString(), server: guild.name }),
+      embeds: [card(member)],
+    });
+  },
+});
+
+// Someone left. `member` is the member as it was, when the bot knew them;
+// `user` is always there.
+export const goodbye = event({
+  name: 'memberLeave',
+  async run({ user, member, guild, t }) {
+    const channel = communityChannel(guild, 'welcome');
+    if (!channel) return;
+    await channel.send(
+      t('goodbye', { name: member?.displayName ?? user.displayName })
+    );
+  },
+});
+
+// An embed is a function of what it shows, reusable from any file.
+export const card = embed((member: GuildMember) => ({
+  title: member.displayName,
+  description: `You are member #${member.guild.memberCount ?? '?'}.`,
+  thumbnail: { url: member.avatarURL() },
+  color: 0xc026d3,
+}));

package/templates/community/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "files": [],
+  "references": [
+    {
+      "path": "./.chapterjs"
+    }
+  ]
+}

package/templates/default/.env.example

@@ -0,0 +1,4 @@
+# Your bot token: https://discord.com/developers/applications → your app → Bot → Reset Token
+BOT_TOKEN=
+# The ID of the server used by `chapterjs dev` (right-click the server → Copy Server ID)
+DEV_GUILD_ID=

package/templates/default/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+.env
+.chapterjs
+data

package/templates/default/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "chapter-bot",
+  "description": "A bot that starts: one event, ready to grow",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "chapterjs dev",
+    "start": "chapterjs start",
+    "build": "chapterjs build",
+    "test": "chapterjs test",
+    "typecheck": "tsc -b",
+    "postinstall": "chapterjs sync"
+  },
+  "dependencies": {
+    "chapterjs": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/templates/default/src/events/ready.ts

@@ -0,0 +1,28 @@
+import { event } from 'chapterjs';
+
+// Your bot is made of the files of src/: each one exports what it declares
+// with a function of 'chapterjs' (event, command, button, task...), and
+// chapterjs dev runs it. This one is an event: `name` says which, and types
+// what `run` receives. `ready` runs once, when the bot is connected.
+export default event({
+  name: 'ready',
+  run({ user, guilds }) {
+    console.log(`${user.username} is online in ${guilds.size} server(s)`);
+  },
+});
+
+// A command is a file like this one, anywhere in src/, with command():
+//
+// import { command } from 'chapterjs';
+//
+// export default command({
+//   name: 'ping',
+//   description: 'Replies with Pong!',
+//   async run({ interaction }) {
+//     await interaction.reply('Pong!');
+//   },
+// });
+//
+// Save it, and /ping shows up in your test server. The other templates of
+// `pnpm create chapterjs` show tickets, music, moderation and a community
+// bot; the docs at https://www.chapterjs.org walk through everything.

package/templates/default/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "files": [],
+  "references": [
+    {
+      "path": "./.chapterjs"
+    }
+  ]
+}

package/templates/moderation/.env.example

@@ -0,0 +1,4 @@
+# Your bot token: https://discord.com/developers/applications → your app → Bot → Reset Token
+BOT_TOKEN=
+# The ID of the server used by `chapterjs dev` (right-click the server → Copy Server ID)
+DEV_GUILD_ID=

package/templates/moderation/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+.env
+.chapterjs
+data

package/templates/moderation/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "moderation-bot",
+  "description": "Timeouts, purge, slowmode, lock, and a log of every moderation action",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "chapterjs dev",
+    "start": "chapterjs start",
+    "build": "chapterjs build",
+    "test": "chapterjs test",
+    "typecheck": "tsc -b",
+    "postinstall": "chapterjs sync"
+  },
+  "dependencies": {
+    "chapterjs": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/templates/moderation/src/moderation/channel.ts

@@ -0,0 +1,67 @@
+import { command } from 'chapterjs';
+
+// /slowmode sets how long people wait between two messages in the channel.
+// 0 removes it.
+export const slowmode = command({
+  name: 'slowmode',
+  permissions: ['ManageChannels'],
+  options: {
+    seconds: { type: 'integer', min: 0, max: 21600, required: true },
+  },
+  async run({ interaction, options, channel, member, t }) {
+    if (!channel.isText()) {
+      await interaction.reply({ content: t('notHere'), ephemeral: true });
+      return;
+    }
+    await channel.edit(
+      { rateLimitPerUser: options.seconds },
+      `By ${member.user.username}`
+    );
+    await interaction.reply(
+      options.seconds === 0
+        ? t('slowmodeOff')
+        : t('slowmodeOn', { count: options.seconds })
+    );
+  },
+});
+
+// /lock keeps everyone from writing in the channel, /unlock gives it back.
+// Both change the permissions of @everyone on the channel only.
+export const lock = command({
+  name: 'lock',
+  permissions: ['ManageChannels'],
+  options: {
+    reason: { type: 'string', maxLength: 200 },
+  },
+  async run({ interaction, options, channel, guild, member, t }) {
+    if (!channel.isText()) {
+      await interaction.reply({ content: t('notHere'), ephemeral: true });
+      return;
+    }
+    await channel.setPermissions(
+      guild.everyoneRole,
+      { deny: ['SendMessages', 'CreatePublicThreads', 'CreatePrivateThreads'] },
+      options.reason ?? `Locked by ${member.user.username}`
+    );
+    await interaction.reply(
+      t('locked', { reason: options.reason ?? t('noReason') })
+    );
+  },
+});
+
+export const unlock = command({
+  name: 'unlock',
+  permissions: ['ManageChannels'],
+  async run({ interaction, channel, guild, member, t }) {
+    if (!channel.isText()) {
+      await interaction.reply({ content: t('notHere'), ephemeral: true });
+      return;
+    }
+    // Deleting the overwrite gives @everyone back what the server says.
+    await channel.deletePermissions(
+      guild.everyoneRole,
+      `Unlocked by ${member.user.username}`
+    );
+    await interaction.reply(t('unlocked'));
+  },
+});

package/templates/moderation/src/moderation/log.ts

@@ -0,0 +1,37 @@
+import { AuditLogEvent, event } from 'chapterjs';
+
+// Every moderation action, whoever did it and however (a command of this
+// bot, another bot, the Discord app), reaches the audit log of the server.
+// This posts the ones below in the channel named mod-log. Discord only
+// sends the audit log to a bot with the View Audit Log permission.
+const ACTIONS: Partial<Record<number, string>> = {
+  [AuditLogEvent.MemberKick]: 'kicked',
+  [AuditLogEvent.MemberBanAdd]: 'banned',
+  [AuditLogEvent.MemberBanRemove]: 'unbanned',
+  [AuditLogEvent.MemberUpdate]: 'updated (timeout, nickname...)',
+  [AuditLogEvent.MessageBulkDelete]: 'purged messages in',
+  [AuditLogEvent.ChannelOverwriteUpdate]: 'changed the permissions of',
+  [AuditLogEvent.ChannelOverwriteCreate]: 'changed the permissions of',
+  [AuditLogEvent.ChannelOverwriteDelete]: 'changed the permissions of',
+};
+
+export default event({
+  name: 'auditLogEntryCreate',
+  async run({ entry, guild }) {
+    const action = ACTIONS[entry.actionType];
+    if (!action || !entry.userId) return;
+    const log = [...guild.channels.values()].find(
+      channel => channel.isText() && channel.name === 'mod-log'
+    );
+    if (!log?.isText()) return;
+    const who = `<@${entry.userId}>`;
+    const target = entry.targetId
+      ? guild.channels.has(entry.targetId)
+        ? `<#${entry.targetId}>`
+        : `<@${entry.targetId}>`
+      : 'something';
+    await log.send(
+      `🛡️ ${who} ${action} ${target}${entry.reason ? `: ${entry.reason}` : ''}`
+    );
+  },
+});

package/templates/moderation/src/moderation/messages.ts

@@ -0,0 +1,158 @@
+import { language } from 'chapterjs';
+
+// The texts of the bot, one language() per language. `t` picks the one of
+// who will read the message. A text with {count} can have one form per
+// quantity: Discord's language rules pick the form.
+export const en = language({
+  locale: 'en-US',
+  default: true,
+  texts: {
+    cantModerate:
+      'You can not moderate {user}: their highest role is above yours.',
+    timedOut: '{user} is timed out until {until}. Reason: {reason}',
+    noReason: 'none given',
+    notTimedOut: '{user} is not timed out.',
+    timeoutRemoved: '{user} can speak again.',
+    purged: {
+      one: '{count} message deleted.',
+      other: '{count} messages deleted.',
+    },
+    notHere: 'This only works in a text channel of the server.',
+    slowmodeOff: 'Slowmode is off.',
+    slowmodeOn: {
+      one: 'Slowmode: one message every {count} second.',
+      other: 'Slowmode: one message every {count} seconds.',
+    },
+    locked: '🔒 This channel is locked. Reason: {reason}',
+    unlocked: '🔓 This channel is open again.',
+    warned: {
+      one: '{user} was warned. They have {count} warning.',
+      other: '{user} was warned. They have {count} warnings.',
+    },
+    noWarnings: '{user} has no warning.',
+    warningsOf: {
+      one: '{user} has {count} warning:',
+      other: '{user} has {count} warnings:',
+    },
+  },
+  commands: {
+    timeout: {
+      description: 'Keeps someone from writing and speaking for a while',
+      options: {
+        user: { description: 'Who' },
+        duration: { description: 'For how long' },
+        reason: { description: 'Why' },
+      },
+    },
+    untimeout: {
+      description: 'Ends the timeout of someone',
+      options: { user: { description: 'Who' } },
+    },
+    purge: {
+      description: 'Deletes the last messages of this channel',
+      options: {
+        count: { description: 'How many, 100 at most' },
+        user: { description: 'Only the messages of this person' },
+      },
+    },
+    slowmode: {
+      description: 'Sets how long people wait between two messages here',
+      options: {
+        seconds: { description: 'Seconds between two messages, 0 for none' },
+      },
+    },
+    lock: {
+      description: 'Keeps everyone from writing in this channel',
+      options: { reason: { description: 'Why' } },
+    },
+    unlock: { description: 'Lets everyone write in this channel again' },
+    'warn add': {
+      description: 'Warns someone; warnings are forgotten after 30 days',
+      options: { user: { description: 'Who' }, reason: { description: 'Why' } },
+    },
+    'warn list': {
+      description: 'Lists the warnings of someone',
+      options: { user: { description: 'Who' } },
+    },
+  },
+});
+
+export const fr = language({
+  locale: 'fr',
+  texts: {
+    cantModerate:
+      'Vous ne pouvez pas modérer {user} : son rôle le plus haut est au-dessus du vôtre.',
+    timedOut:
+      '{user} est exclu temporairement jusqu’à {until}. Raison : {reason}',
+    noReason: 'aucune',
+    notTimedOut: '{user} n’est pas exclu.',
+    timeoutRemoved: '{user} peut de nouveau parler.',
+    purged: {
+      one: '{count} message supprimé.',
+      other: '{count} messages supprimés.',
+    },
+    notHere: 'Ceci ne fonctionne que dans un salon textuel du serveur.',
+    slowmodeOff: 'Le mode lent est désactivé.',
+    slowmodeOn: {
+      one: 'Mode lent : un message toutes les {count} seconde.',
+      other: 'Mode lent : un message toutes les {count} secondes.',
+    },
+    locked: '🔒 Ce salon est verrouillé. Raison : {reason}',
+    unlocked: '🔓 Ce salon est de nouveau ouvert.',
+    warned: {
+      one: '{user} a été averti. Il a {count} avertissement.',
+      other: '{user} a été averti. Il a {count} avertissements.',
+    },
+    noWarnings: '{user} n’a aucun avertissement.',
+    warningsOf: {
+      one: '{user} a {count} avertissement :',
+      other: '{user} a {count} avertissements :',
+    },
+  },
+  commands: {
+    timeout: {
+      description: 'Empêche quelqu’un d’écrire et de parler pendant un moment',
+      options: {
+        user: { description: 'Qui' },
+        duration: { description: 'Pendant combien de temps' },
+        reason: { description: 'Pourquoi' },
+      },
+    },
+    untimeout: {
+      description: 'Met fin à l’exclusion temporaire de quelqu’un',
+      options: { user: { description: 'Qui' } },
+    },
+    purge: {
+      description: 'Supprime les derniers messages de ce salon',
+      options: {
+        count: { description: 'Combien, 100 au plus' },
+        user: { description: 'Seulement les messages de cette personne' },
+      },
+    },
+    slowmode: {
+      description: 'Règle l’attente entre deux messages ici',
+      options: {
+        seconds: { description: 'Secondes entre deux messages, 0 pour aucune' },
+      },
+    },
+    lock: {
+      description: 'Empêche tout le monde d’écrire dans ce salon',
+      options: { reason: { description: 'Pourquoi' } },
+    },
+    unlock: {
+      description: 'Laisse de nouveau tout le monde écrire dans ce salon',
+    },
+    'warn add': {
+      description:
+        'Avertit quelqu’un ; un avertissement est oublié après 30 jours',
+      options: {
+        user: { description: 'Qui' },
+        reason: { description: 'Pourquoi' },
+      },
+    },
+    'warn list': {
+      description: 'Liste les avertissements de quelqu’un',
+      options: { user: { description: 'Qui' } },
+    },
+  },
+});

package/templates/moderation/src/moderation/moderation.test.ts

@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict';
+import { scenario } from 'chapterjs/test';
+import { lock, slowmode } from './channel';
+import purge from './purge';
+import timeout from './timeout';
+import warn, { list } from './warn';
+
+// `chapterjs test` runs these against a Discord in memory: no token, no
+// server. Each scenario starts on a fresh server, with empty stores.
+const mod = {
+  permissions: ['ModerateMembers', 'ManageMessages', 'ManageChannels'],
+} as const;
+
+export default [
+  scenario('warnings add up, per member', async bot => {
+    const alice = bot.member('alice');
+    const by = { by: bot.member('mod', mod) };
+    const first = await bot.use(warn, { user: alice, reason: 'spam' }, by);
+    first.says('They have 1 warning.');
+    const second = await bot.use(warn, { user: alice, reason: 'again' }, by);
+    second.says('They have 2 warnings.');
+
+    const listed = await bot.use(list, { user: alice }, by);
+    listed.isEphemeral().says('has 2 warnings').says('spam').says('again');
+    const nobody = await bot.use(list, { user: bot.member('bob') }, by);
+    nobody.says('has no warning');
+  }),
+
+  scenario(
+    'a timeout needs the permission, and spares the owner',
+    async bot => {
+      const alice = bot.member('alice');
+      const refused = await bot.use(timeout, { user: alice, duration: 5 });
+      refused.isEphemeral().says('ModerateMembers');
+
+      const by = { by: bot.member('mod', mod) };
+      const owner = await bot.use(
+        timeout,
+        { user: bot.owner, duration: 5 },
+        by
+      );
+      owner.isEphemeral().says('You can not moderate');
+
+      const done = await bot.use(timeout, { user: alice, duration: 60 }, by);
+      done.says('is timed out');
+      assert.equal(alice.timedOut, true);
+    }
+  ),
+
+  scenario('purge deletes the last messages', async bot => {
+    await bot.say('one');
+    await bot.say('two');
+    await bot.say('three');
+    const by = { by: bot.member('mod', mod) };
+    const reply = await bot.use(purge, { count: 2 }, by);
+    reply.isDeferred().isEphemeral().says('2 messages deleted.');
+    assert.deepEqual(
+      bot.channel('general').messages.map(message => message.content),
+      ['one']
+    );
+  }),
+
+  scenario('slowmode and lock change the channel', async bot => {
+    const by = { by: bot.member('mod', mod) };
+    const slow = await bot.use(slowmode, { seconds: 5 }, by);
+    slow.says('one message every 5 seconds');
+    assert.equal(bot.channel('general').slowmode, 5);
+
+    const locked = await bot.use(lock, { reason: 'calm down' }, by);
+    locked.says('locked').says('calm down');
+    assert.equal(
+      bot.channel('general').allows(bot.someone, 'SendMessages'),
+      false
+    );
+  }),
+];

package/templates/moderation/src/moderation/purge.ts

@@ -0,0 +1,30 @@
+import { command } from 'chapterjs';
+
+// /purge deletes the last messages of the channel, all of them or only
+// the ones of a person. Discord only deletes in bulk what is less than two
+// weeks old: older messages are left out, and the answer says how many
+// really went.
+export default command({
+  name: 'purge',
+  permissions: ['ManageMessages'],
+  // The answer only the person sees, so the channel is not filled again.
+  ephemeral: true,
+  cooldown: { channel: '5s' },
+  options: {
+    count: { type: 'integer', min: 1, max: 100, required: true },
+    user: { type: 'user' },
+  },
+  async run({ interaction, options, channel, member, t }) {
+    // Deleting takes a moment: tell Discord the answer is coming.
+    await interaction.defer();
+    const messages = await channel.fetchMessages({ limit: options.count });
+    const chosen = options.user
+      ? messages.filter(message => message.author.id === options.user!.id)
+      : messages;
+    const deleted = await channel.bulkDelete(
+      chosen,
+      `Purge by ${member.user.username}`
+    );
+    await interaction.reply(t('purged', { count: deleted }));
+  },
+});