create-chapterjs 0.2.3 → 0.4.0

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,7 @@
+# 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=
+# Only for stores declared with storage: 'redis' (https://www.chapterjs.org/storage#in-redis)
+# REDIS_URL=redis://localhost:6379
+# REDIS_PASSWORD=

package/templates/music/_gitignore

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

package/templates/music/package.json

@@ -0,0 +1,24 @@
+{
+  "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",
+    "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/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/music.test.ts

@@ -0,0 +1,29 @@
+import { scenario } from 'chapterjs/test';
+import leave from './leave';
+import play from './play';
+import queue from './queue-command';
+
+// `chapterjs test` runs these against a Discord in memory: no token, no
+// server, and no voice yet: what can be checked is what the bot says
+// before playing anything.
+export default [
+  scenario('nothing plays at first', async bot => {
+    const reply = await bot.use(queue);
+    reply.isEphemeral().says('Nothing is playing.');
+    const left = await bot.use(leave);
+    left.isEphemeral().says('I am not in a voice channel.');
+  }),
+
+  scenario('play needs a song, then a voice channel', async bot => {
+    const nothing = await bot.use(play);
+    nothing.isEphemeral().says('Send an audio file');
+    const notAudio = await bot.use(play, {
+      file: { name: 'photo.png', type: 'image/png' },
+    });
+    notAudio.isEphemeral().says('Send an audio file');
+    const noVoice = await bot.use(play, {
+      url: 'https://example.com/song.mp3',
+    });
+    noVoice.isEphemeral().says('Join a voice channel first');
+  }),
+];

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

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

@@ -0,0 +1,61 @@
+import type { Attachment, Guild, VoiceConnection } from 'chapterjs';
+
+// Plain code: this file declares nothing, so the framework leaves it alone.
+// It keeps the queue of each server and plays it, song after song.
+
+export interface Song {
+  /** What play() takes: a file sent on Discord, or a link. */
+  source: Attachment | string;
+  title: string;
+  /** Who asked for it: a mention. */
+  requestedBy: string;
+}
+
+interface Queue {
+  songs: Song[];
+  current: Song | null;
+}
+
+const queues = new Map<string, Queue>();
+
+/** The queue of a server, made on first use. */
+export function queueOf(guild: Guild): Queue {
+  let queue = queues.get(guild.id);
+  if (!queue) {
+    queue = { songs: [], current: null };
+    queues.set(guild.id, queue);
+  }
+  return queue;
+}
+
+/**
+ * Plays the queue of a server until it is empty, then leaves the channel.
+ * Called once when the first song is added; a song added meanwhile is
+ * picked up by the loop. A song that can't be played (a dead link, ffmpeg
+ * missing) is skipped and said in the channel.
+ */
+export async function playQueue(
+  guild: Guild,
+  voice: VoiceConnection,
+  say: (text: string) => Promise<unknown>
+): Promise<void> {
+  const queue = queueOf(guild);
+  if (queue.current) return;
+  let song: Song | undefined;
+  while ((song = queue.songs.shift())) {
+    queue.current = song;
+    try {
+      await voice.play(song.source);
+    } catch (error) {
+      await say(`⚠ ${song.title}: ${(error as Error).message}`);
+    }
+  }
+  queue.current = null;
+  // /leave may have made the bot leave already.
+  if (voice.connected) await voice.leave();
+}
+
+/** Empties the queue of a server: when the bot stops or leaves. */
+export function clearQueue(guild: Guild): void {
+  queueOf(guild).songs.length = 0;
+}

package/templates/music/src/presence.ts

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

package/templates/music/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/tickets/.env.example

@@ -0,0 +1,7 @@
+# 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=
+# Only for stores declared with storage: 'redis' (https://www.chapterjs.org/storage#in-redis)
+# REDIS_URL=redis://localhost:6379
+# REDIS_PASSWORD=

package/templates/tickets/_gitignore

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

package/templates/tickets/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "ticket-bot",
+  "description": "Support tickets in private threads: a panel, a form, a close button",
+  "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/tickets/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 tickets' },
+});

package/templates/tickets/src/tickets/close.ts

@@ -0,0 +1,39 @@
+import { button } from 'chapterjs';
+import { tickets } from './open';
+
+// The button at the top of every ticket. Everyone in the thread sees it;
+// the code decides who may use it: the staff, or who opened the ticket.
+// `data` is what the button carries from the message to the click: here
+// who opened the ticket, kept by Discord in the button itself.
+export const close = button({
+  label: ({ t }) => t('closeButton'),
+  style: 'danger',
+  data: { userId: 'string' },
+  async run({ interaction, data, channel, member, guild, t }) {
+    if (!channel.isThread()) {
+      await interaction.reply({ content: t('notATicket'), ephemeral: true });
+      return;
+    }
+    const staff = member.permissions.has('ManageThreads');
+    if (!staff && member.id !== data.userId) {
+      await interaction.reply({ content: t('notYours'), ephemeral: true });
+      return;
+    }
+    // Said in the thread first: archiving it closes it for everyone.
+    await interaction.reply(t('closing', { user: member.toString() }));
+    await channel.edit(
+      { locked: true, archived: true },
+      `Closed by ${member.user.username}`
+    );
+    // The person may open another one.
+    await tickets.delete(data.userId);
+    // Who opened it is told in private, unless they closed it themselves.
+    // A person who refuses private messages is not an error.
+    if (member.id !== data.userId) {
+      const opener = await guild.fetchMember(data.userId).catch(() => null);
+      await opener
+        ?.send(t('closedDm', { ticket: channel.name, server: guild.name }))
+        .catch(() => {});
+    }
+  },
+});

package/templates/tickets/src/tickets/messages.ts

@@ -0,0 +1,68 @@
+import { language } from 'chapterjs';
+
+// The texts of the bot, one language() per language. `t` picks the one of
+// who will read the message: the person for a private answer, the server
+// otherwise. `commands` is what Discord shows of each command.
+export const en = language({
+  locale: 'en-US',
+  default: true,
+  texts: {
+    panelTitle: 'Need help?',
+    panelText:
+      'Open a ticket and the staff will answer you in a private thread.',
+    panelPosted: 'The panel is posted.',
+    openButton: 'Open a ticket',
+    formTitle: 'New ticket',
+    formSubject: 'Subject',
+    formCategory: 'What is it about?',
+    formDetails: 'Tell us more',
+    notHere: 'Tickets can only be opened from a text channel.',
+    opened: 'Thanks {user}, the staff will be with you shortly.',
+    created: 'Your ticket is open: {thread}',
+    alreadyOpen: 'You already have a ticket open: {thread}. Close it first.',
+    category: 'Category',
+    openedBy: 'Opened by',
+    closeButton: 'Close the ticket',
+    notATicket: 'This button only works inside a ticket.',
+    notYours: 'Only the staff, or who opened this ticket, can close it.',
+    closing: 'Ticket closed by {user}.',
+    closedDm: 'Your ticket "{ticket}" on {server} was closed.',
+  },
+  commands: {
+    'ticket panel': {
+      description: 'Posts the message people open tickets from',
+    },
+  },
+});
+
+export const fr = language({
+  locale: 'fr',
+  texts: {
+    panelTitle: 'Besoin d’aide ?',
+    panelText: 'Ouvrez un ticket et le staff vous répondra dans un fil privé.',
+    panelPosted: 'Le panneau est posté.',
+    openButton: 'Ouvrir un ticket',
+    formTitle: 'Nouveau ticket',
+    formSubject: 'Sujet',
+    formCategory: 'De quoi s’agit-il ?',
+    formDetails: 'Dites-nous en plus',
+    notHere: 'Un ticket ne peut être ouvert que depuis un salon textuel.',
+    opened: 'Merci {user}, le staff arrive.',
+    created: 'Votre ticket est ouvert : {thread}',
+    alreadyOpen:
+      'Vous avez déjà un ticket ouvert : {thread}. Fermez-le d’abord.',
+    category: 'Catégorie',
+    openedBy: 'Ouvert par',
+    closeButton: 'Fermer le ticket',
+    notATicket: 'Ce bouton ne fonctionne que dans un ticket.',
+    notYours:
+      'Seul le staff, ou la personne qui a ouvert ce ticket, peut le fermer.',
+    closing: 'Ticket fermé par {user}.',
+    closedDm: 'Votre ticket « {ticket} » sur {server} a été fermé.',
+  },
+  commands: {
+    'ticket panel': {
+      description: 'Poste le message depuis lequel on ouvre un ticket',
+    },
+  },
+});