create-chapter 0.2.2 → 0.2.3

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/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 }));
+  },
+});

package/templates/moderation/src/moderation/timeout.ts

@@ -0,0 +1,82 @@
+import { command, timestamp, type GuildMember } from 'chapterjs';
+
+// Someone can only act on people below them, and never on the owner.
+function canModerate(target: GuildMember, by: GuildMember): boolean {
+  return (
+    target.id !== target.guild.ownerId &&
+    target.highestRole.position < by.highestRole.position
+  );
+}
+
+// /timeout keeps someone from writing, reacting and speaking for a while.
+// `permissions` is what a member needs to see and use the command; the bot
+// itself needs Moderate Members. The choices of `duration` are what the
+// person picks from, in minutes.
+export default command({
+  name: 'timeout',
+  permissions: ['ModerateMembers'],
+  options: {
+    user: { type: 'user', required: true },
+    duration: {
+      type: 'integer',
+      required: true,
+      choices: {
+        '5 minutes': 5,
+        '1 hour': 60,
+        '1 day': 60 * 24,
+        '1 week': 60 * 24 * 7,
+      },
+    },
+    reason: { type: 'string', maxLength: 200 },
+  },
+  async run({ interaction, options, guild, member, t }) {
+    const target = await guild.fetchMember(options.user);
+    if (!canModerate(target, member)) {
+      await interaction.reply({
+        content: t('cantModerate', { user: target.toString() }),
+        ephemeral: true,
+      });
+      return;
+    }
+    const until = Date.now() + options.duration * 60 * 1000;
+    await target.timeout(
+      options.duration * 60 * 1000,
+      options.reason ?? `By ${member.user.username}`
+    );
+    await interaction.reply(
+      t('timedOut', {
+        user: target.toString(),
+        until: timestamp(until, 'R'),
+        reason: options.reason ?? t('noReason'),
+      })
+    );
+  },
+});
+
+export const untimeout = command({
+  name: 'untimeout',
+  permissions: ['ModerateMembers'],
+  options: {
+    user: { type: 'user', required: true },
+  },
+  async run({ interaction, options, guild, member, t }) {
+    const target = await guild.fetchMember(options.user);
+    // The same rule as /timeout: nobody lifts what someone above them set.
+    if (!canModerate(target, member)) {
+      await interaction.reply({
+        content: t('cantModerate', { user: target.toString() }),
+        ephemeral: true,
+      });
+      return;
+    }
+    if (!target.isTimedOut) {
+      await interaction.reply({
+        content: t('notTimedOut', { user: target.toString() }),
+        ephemeral: true,
+      });
+      return;
+    }
+    await target.removeTimeout(`By ${member.user.username}`);
+    await interaction.reply(t('timeoutRemoved', { user: target.toString() }));
+  },
+});

package/templates/moderation/src/moderation/warn.ts

@@ -0,0 +1,61 @@
+import { command, store, timestamp } from 'chapterjs';
+
+interface Warning {
+  reason: string;
+  /** Who gave it: a user id. */
+  by: string;
+  /** When, in ms since the epoch: a Date would not survive the file. */
+  at: number;
+}
+
+// The warnings of each member, kept from one restart to the next, per
+// server: `warnings.get(member.id)` in a command is the warnings of that
+// member in the server the command was used in. A warning is forgotten
+// thirty days after the last one was added.
+export const warnings = store<Warning[]>({ expires: '30d' });
+
+export default command({
+  name: 'warn add',
+  permissions: ['ModerateMembers'],
+  options: {
+    user: { type: 'user', required: true },
+    reason: { type: 'string', required: true, maxLength: 200 },
+  },
+  async run({ interaction, options, member, t }) {
+    // Reads, adds and keeps in one go; `list` is undefined the first time.
+    const list = await warnings.update(options.user.id, (list = []) => [
+      ...list,
+      { reason: options.reason, by: member.id, at: Date.now() },
+    ]);
+    await interaction.reply(
+      t('warned', { user: options.user.toString(), count: list.length })
+    );
+  },
+});
+
+export const list = command({
+  name: 'warn list',
+  permissions: ['ModerateMembers'],
+  ephemeral: true,
+  options: {
+    user: { type: 'user', required: true },
+  },
+  async run({ interaction, options, t }) {
+    const list = (await warnings.get(options.user.id)) ?? [];
+    if (list.length === 0) {
+      await interaction.reply(
+        t('noWarnings', { user: options.user.toString() })
+      );
+      return;
+    }
+    await interaction.reply(
+      [
+        t('warningsOf', { user: options.user.toString(), count: list.length }),
+        ...list.map(
+          warning =>
+            `• ${timestamp(warning.at, 'R')} <@${warning.by}>: ${warning.reason}`
+        ),
+      ].join('\n')
+    );
+  },
+});

package/templates/moderation/src/presence.ts

@@ -0,0 +1,6 @@
+import { presence } from 'chapterjs';
+
+// What the bot shows under its name.
+export default presence({
+  activity: { type: 'watching', name: 'the server' },
+});

package/templates/moderation/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/music/.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/music/_gitignore

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

package/templates/music/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "music-bot",
+  "description": "A music player in voice: a queue, buttons, pause, skip and stop",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "chapterjs dev",
+    "start": "chapterjs start",
+    "build": "chapterjs build",
+    "typecheck": "tsc -b",
+    "postinstall": "chapterjs sync"
+  },
+  "dependencies": {
+    "chapterjs": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/templates/music/src/music/leave.ts

@@ -0,0 +1,18 @@
+import { command } from 'chapterjs';
+import { clearQueue } from './queue';
+
+// /leave makes the bot leave the voice channel and forget the queue.
+export default command({
+  name: 'leave',
+  async run({ interaction, guild, t }) {
+    const voice = guild.voice;
+    if (!voice) {
+      await interaction.reply({ content: t('notInVoice'), ephemeral: true });
+      return;
+    }
+    clearQueue(guild);
+    // leave() ends what plays: the loop of play.ts stops too.
+    await voice.leave();
+    await interaction.reply(t('left'));
+  },
+});

package/templates/music/src/music/messages.ts

@@ -0,0 +1,83 @@
+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 (`one`, `other`...): Discord's language rules pick the form.
+export const en = language({
+  locale: 'en-US',
+  default: true,
+  texts: {
+    nothingToPlay:
+      'Send an audio file (.mp3, .ogg...) or a link starting with https://.',
+    joinVoice: 'Join a voice channel first, then ask again.',
+    playing: 'Now playing {song} in {channel}.',
+    queued: 'Added {song} to the queue, at position {position}.',
+    nowPlaying: '▶ {song}, asked by {by}',
+    upNext: {
+      one: 'Up next, {count} song:',
+      other: 'Up next, {count} songs:',
+    },
+    nothingPlaying: 'Nothing is playing.',
+    notWithMe: 'Join my voice channel to control what plays.',
+    notInVoice: 'I am not in a voice channel.',
+    pauseButton: 'Pause / resume',
+    skipButton: 'Skip',
+    stopButton: 'Stop',
+    paused: 'Paused.',
+    resumed: 'Playing again.',
+    skipped: 'Skipped.',
+    stopped: 'Stopped, the queue is empty.',
+    left: 'Bye!',
+  },
+  commands: {
+    play: {
+      description:
+        'Plays a song in your voice channel, or adds it to the queue',
+      options: {
+        file: { description: 'A song to play' },
+        url: { description: 'Or the link of a song or a stream' },
+      },
+    },
+    queue: { description: 'Shows what plays and what comes next' },
+    leave: { description: 'Makes the bot leave the voice channel' },
+  },
+});
+
+export const fr = language({
+  locale: 'fr',
+  texts: {
+    nothingToPlay:
+      'Envoyez un fichier audio (.mp3, .ogg...) ou un lien qui commence par https://.',
+    joinVoice: 'Rejoignez d’abord un salon vocal, puis redemandez.',
+    playing: 'Lecture de {song} dans {channel}.',
+    queued: '{song} ajouté à la file, en position {position}.',
+    nowPlaying: '▶ {song}, demandé par {by}',
+    upNext: {
+      one: 'Ensuite, {count} morceau :',
+      other: 'Ensuite, {count} morceaux :',
+    },
+    nothingPlaying: 'Rien n’est en cours de lecture.',
+    notWithMe: 'Rejoignez mon salon vocal pour contrôler la lecture.',
+    notInVoice: 'Je ne suis pas dans un salon vocal.',
+    pauseButton: 'Pause / reprendre',
+    skipButton: 'Passer',
+    stopButton: 'Stop',
+    paused: 'En pause.',
+    resumed: 'Reprise.',
+    skipped: 'Passé.',
+    stopped: 'Arrêté, la file est vide.',
+    left: 'À plus !',
+  },
+  commands: {
+    play: {
+      description:
+        'Joue une musique dans votre salon vocal, ou l’ajoute à la file',
+      options: {
+        file: { description: 'Une musique à jouer' },
+        url: { description: 'Ou le lien d’une musique ou d’un flux' },
+      },
+    },
+    queue: { description: 'Montre ce qui joue et ce qui suit' },
+    leave: { description: 'Fait quitter le salon vocal au bot' },
+  },
+});

package/templates/music/src/music/play.ts

@@ -0,0 +1,120 @@
+import { button, command, row } from 'chapterjs';
+import { clearQueue, playQueue, queueOf, type Song } from './queue';
+
+// /play adds a song to the queue of the server and starts playing when
+// nothing is. A song is a file sent with the command (an .mp3, an .ogg...)
+// or a link to an audio file or a stream; anything that is not Opus needs
+// ffmpeg installed on the machine that runs the bot.
+export default command({
+  name: 'play',
+  options: {
+    file: { type: 'attachment' },
+    url: { type: 'string' },
+  },
+  async run({ interaction, member, guild, channel, options, t }) {
+    const { file, url } = options;
+    if (
+      (!file && !url) ||
+      (file && !file.contentType?.startsWith('audio/')) ||
+      (url && !/^https?:\/\//.test(url))
+    ) {
+      await interaction.reply({ content: t('nothingToPlay'), ephemeral: true });
+      return;
+    }
+    const voiceChannel = member.voiceChannel;
+    if (!voiceChannel) {
+      await interaction.reply({ content: t('joinVoice'), ephemeral: true });
+      return;
+    }
+    const song: Song = {
+      source: file ?? url!,
+      title: file?.filename ?? url!,
+      requestedBy: member.toString(),
+    };
+    const queue = queueOf(guild);
+    queue.songs.push(song);
+    if (queue.current) {
+      await interaction.reply(
+        t('queued', { song: song.title, position: queue.songs.length })
+      );
+      return;
+    }
+    await interaction.reply({
+      content: t('playing', { song: song.title, channel: voiceChannel.name }),
+      components: [row([pause, skip, stop])],
+    });
+    // Joining the channel the bot is already in changes nothing. The loop
+    // runs until the queue is empty, and the bot leaves by itself.
+    const voice = await voiceChannel.join();
+    await playQueue(guild, voice, text => channel.send(text));
+  },
+});
+
+// The three buttons under "Now playing". A button is named by its export,
+// and `run` receives the same things as a command.
+export const pause = button({
+  label: ({ t }) => t('pauseButton'),
+  emoji: '⏯️',
+  async run({ interaction, guild, member, t }) {
+    const voice = guild.voice;
+    if (!voice?.playing) {
+      await interaction.reply({
+        content: t('nothingPlaying'),
+        ephemeral: true,
+      });
+      return;
+    }
+    if (member.voiceChannel?.id !== voice.channel.id) {
+      await interaction.reply({ content: t('notWithMe'), ephemeral: true });
+      return;
+    }
+    if (voice.paused) voice.resume();
+    else voice.pause();
+    await interaction.reply(voice.paused ? t('paused') : t('resumed'));
+  },
+});
+
+export const skip = button({
+  label: ({ t }) => t('skipButton'),
+  emoji: '⏭️',
+  async run({ interaction, guild, member, t }) {
+    const voice = guild.voice;
+    if (!voice?.playing) {
+      await interaction.reply({
+        content: t('nothingPlaying'),
+        ephemeral: true,
+      });
+      return;
+    }
+    if (member.voiceChannel?.id !== voice.channel.id) {
+      await interaction.reply({ content: t('notWithMe'), ephemeral: true });
+      return;
+    }
+    // stop() ends the current play(): the loop goes on with the next song.
+    voice.stop();
+    await interaction.reply(t('skipped'));
+  },
+});
+
+export const stop = button({
+  label: ({ t }) => t('stopButton'),
+  emoji: '⏹️',
+  style: 'danger',
+  async run({ interaction, guild, member, t }) {
+    const voice = guild.voice;
+    if (!voice) {
+      await interaction.reply({
+        content: t('nothingPlaying'),
+        ephemeral: true,
+      });
+      return;
+    }
+    if (member.voiceChannel?.id !== voice.channel.id) {
+      await interaction.reply({ content: t('notWithMe'), ephemeral: true });
+      return;
+    }
+    clearQueue(guild);
+    voice.stop();
+    await interaction.reply(t('stopped'));
+  },
+});

package/templates/music/src/music/queue-command.ts

@@ -0,0 +1,28 @@
+import { command } from 'chapterjs';
+import { queueOf } from './queue';
+
+// /queue shows what plays and what comes next. A text with {count} may
+// have one form per quantity in the language files: see messages.ts.
+export default command({
+  name: 'queue',
+  ephemeral: true,
+  async run({ interaction, guild, t }) {
+    const queue = queueOf(guild);
+    if (!queue.current) {
+      await interaction.reply(t('nothingPlaying'));
+      return;
+    }
+    const next = queue.songs
+      .slice(0, 10)
+      .map((song, index) => `${index + 1}. ${song.title} (${song.requestedBy})`)
+      .join('\n');
+    const lines = [
+      t('nowPlaying', {
+        song: queue.current.title,
+        by: queue.current.requestedBy,
+      }),
+    ];
+    if (next) lines.push(t('upNext', { count: queue.songs.length }), next);
+    await interaction.reply(lines.join('\n'));
+  },
+});