create-chapter 0.2.1 → 0.2.3

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,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/tickets/_gitignore

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

package/templates/tickets/package.json

@@ -0,0 +1,23 @@
+{
+  "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",
+    "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',
+    },
+  },
+});

package/templates/tickets/src/tickets/open.ts

@@ -0,0 +1,81 @@
+import { ChannelType, modal, store } from 'chapterjs';
+import { close } from './close';
+
+// The ticket each person has open: the id of its thread, by person. A
+// store keeps data from one restart to the next, per server: in this
+// server, `tickets.get(member.id)` is the ticket of that member here.
+export const tickets = store<string>();
+
+// The form a ticket starts with. `run` receives the fields typed from
+// their kind: `subject` and `details` are strings, `category` is one of
+// the three values below.
+export const openTicket = modal({
+  title: ({ t }) => t('formTitle'),
+  fields: {
+    subject: {
+      type: 'text',
+      label: ({ t }) => t('formSubject'),
+      style: 'short',
+      maxLength: 80,
+    },
+    category: {
+      type: 'radio',
+      label: ({ t }) => t('formCategory'),
+      options: { Bug: 'bug', Question: 'question', Other: 'other' },
+    },
+    details: {
+      type: 'text',
+      label: ({ t }) => t('formDetails'),
+      style: 'paragraph',
+      minLength: 20,
+      maxLength: 1000,
+    },
+  },
+  async run({ interaction, fields, channel, member, t }) {
+    if (!channel.isText()) {
+      await interaction.reply({ content: t('notHere'), ephemeral: true });
+      return;
+    }
+    // One ticket at a time per person.
+    const open = await tickets.get(member.id);
+    if (open) {
+      await interaction.reply({
+        content: t('alreadyOpen', { thread: `<#${open}>` }),
+        ephemeral: true,
+      });
+      return;
+    }
+    // A private thread: only the people added to it, and the staff, see it.
+    const thread = await channel.startThread(
+      {
+        name: `${fields.category}-${member.displayName}`.slice(0, 100),
+        type: ChannelType.PrivateThread,
+        invitable: false,
+      },
+      `Ticket opened by ${member.user.username}`
+    );
+    await thread.addMember(member);
+    await tickets.set(member.id, thread.id);
+    await thread.send({
+      content: t('opened', { user: member.toString() }),
+      embeds: [
+        {
+          title: fields.subject,
+          description: fields.details,
+          color: 0xc026d3,
+          fields: [
+            { name: t('category'), value: fields.category, inline: true },
+            { name: t('openedBy'), value: member.toString(), inline: true },
+          ],
+        },
+      ],
+      // The close button carries who opened the ticket, so it knows who may
+      // close it besides the staff, and who to tell when it is closed.
+      components: [close({ userId: member.id })],
+    });
+    await interaction.reply({
+      content: t('created', { thread: thread.toString() }),
+      ephemeral: true,
+    });
+  },
+});

package/templates/tickets/src/tickets/panel.ts

@@ -0,0 +1,35 @@
+import { button, command } from 'chapterjs';
+import { openTicket } from './open';
+
+// /ticket panel posts the message people open a ticket from: an embed and
+// a button. Only the staff can post it (`permissions`); Discord hides the
+// command from everyone else. `t` speaks the language of the server.
+export default command({
+  name: 'ticket panel',
+  permissions: ['ManageThreads'],
+  async run({ interaction, channel, t }) {
+    await channel.send({
+      embeds: [
+        {
+          title: t('panelTitle'),
+          description: t('panelText'),
+          color: 0xc026d3,
+        },
+      ],
+      components: [open],
+    });
+    await interaction.reply({ content: t('panelPosted'), ephemeral: true });
+  },
+});
+
+// A button is named by its export (`open`): nothing to register, no id to
+// write. Its label is a function of `t`, run when the message is sent.
+export const open = button({
+  label: ({ t }) => t('openButton'),
+  style: 'primary',
+  emoji: '🎫',
+  async run({ interaction }) {
+    // A form must be the first answer to a click.
+    await interaction.showModal(openTicket);
+  },
+});

package/templates/tickets/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/src/(moderation)/ban.ts

@@ -1,49 +0,0 @@
-import { button, command } from 'chapterjs';
-import { canPunish } from './checks';
-
-// A folder is only a folder: `(moderation)` groups what moderation needs,
-// and the framework reads what these files export, wherever they are.
-// /ban asks for a confirmation, then bans. The command and its button live
-// in the same file: the button is named by its export (`confirmBan`), and
-// `who: 'author'` keeps it for the person who used the command.
-export default command({
-  name: 'ban',
-  permissions: ['BanMembers'],
-  ephemeral: true,
-  options: {
-    target: { type: 'user', required: true },
-    reason: { type: 'string' },
-    days: { type: 'integer', min: 0, max: 7 },
-  },
-  async run({ interaction, options, member, guild, t }) {
-    const target = guild.members.get(options.target.id);
-    if (target && !canPunish(member, target)) {
-      await interaction.reply(t('cannotPunish', { user: target.displayName }));
-      return;
-    }
-    await interaction.reply({
-      content: t('ban.confirm', { user: options.target.username }),
-      components: [
-        confirmBan({
-          userId: options.target.id,
-          days: options.days ?? 0,
-          reason: options.reason ?? '',
-        }),
-      ],
-    });
-  },
-});
-
-export const confirmBan = button({
-  label: ({ t }) => t('ban.yes'),
-  style: 'danger',
-  who: 'author',
-  data: { userId: 'string', days: 'number', reason: 'string' },
-  async run({ interaction, data, guild, user, t }) {
-    await guild.ban(data.userId, {
-      reason: data.reason || t('ban.defaultReason', { by: user.username }),
-      deleteMessageSeconds: data.days * 86_400,
-    });
-    await interaction.update({ content: t('ban.done'), components: [] });
-  },
-});

package/templates/default/src/(moderation)/checks.ts

@@ -1,19 +0,0 @@
-import type { GuildMember } from 'chapterjs';
-
-// Shared code: this file declares nothing, the commands import it. Nothing
-// survives a restart: a real bot keeps its warnings in a database.
-export function canPunish(by: GuildMember, target: GuildMember): boolean {
-  return by.highestRole.position > target.highestRole.position;
-}
-
-const warnings = new Map<string, number>();
-
-export function addWarning(userId: string): number {
-  const count = (warnings.get(userId) ?? 0) + 1;
-  warnings.set(userId, count);
-  return count;
-}
-
-export function warningsOf(userId: string): number {
-  return warnings.get(userId) ?? 0;
-}

package/templates/default/src/(moderation)/kick.ts

@@ -1,27 +0,0 @@
-import { command } from 'chapterjs';
-
-// /kick: the texts come from the language files, like every command here.
-import { canPunish } from './checks';
-
-export default command({
-  name: 'kick',
-  permissions: ['KickMembers'],
-  ephemeral: true,
-  options: {
-    target: { type: 'user', required: true },
-    reason: { type: 'string' },
-  },
-  async run({ interaction, options, member, guild, t }) {
-    const target = guild.members.get(options.target.id);
-    if (!target) {
-      await interaction.reply(t('notHere', { user: options.target.username }));
-      return;
-    }
-    if (!canPunish(member, target)) {
-      await interaction.reply(t('cannotPunish', { user: target.displayName }));
-      return;
-    }
-    await target.kick(options.reason);
-    await interaction.reply(t('kick.done', { user: target.displayName }));
-  },
-});

package/templates/default/src/(moderation)/messages.ts

@@ -1,81 +0,0 @@
-import { language } from 'chapterjs';
-
-// A language may be declared in several places: these texts are added to the
-// en-US and fr of src/messages/, next to the commands that use them. What
-// says `default: true` there decides for the whole language.
-export const en = language({
-  locale: 'en-US',
-  texts: {
-    cannotPunish: 'You can not act on {user}: their role is above yours.',
-    notHere: '{user} is not in this server.',
-    'ban.confirm': 'Ban {user}?',
-    'ban.yes': 'Ban',
-    'ban.defaultReason': 'Banned by {by}',
-    'ban.done': 'Banned.',
-    'kick.done': '{user} was kicked.',
-    'warn.added': '{user} now has {count} warning(s).',
-    // A plural: one form per quantity, picked by `count`.
-    'warn.count': {
-      one: '{user} has {count} warning.',
-      other: '{user} has {count} warnings.',
-    },
-  },
-  // What Discord shows of these commands: their descriptions live here too.
-  commands: {
-    ban: {
-      description: 'Bans a member, after a confirmation',
-      options: {
-        target: { description: 'Who to ban' },
-        reason: { description: 'Why' },
-        days: { description: 'Days of messages to delete' },
-      },
-    },
-    kick: {
-      description: 'Kicks a member',
-      options: {
-        target: { description: 'Who to kick' },
-        reason: { description: 'Why' },
-      },
-    },
-    'warn add': {
-      description: 'Warns a member',
-      options: {
-        target: { description: 'Who to warn' },
-        reason: { description: 'Why' },
-      },
-    },
-    'warn list': {
-      description: 'Counts the warnings of a member',
-      options: { target: { description: 'Whose warnings' } },
-    },
-  },
-});
-
-export const fr = language({
-  locale: 'fr',
-  texts: {
-    cannotPunish:
-      'Vous ne pouvez pas agir sur {user} : son rôle est au-dessus du vôtre.',
-    notHere: '{user} n’est pas sur ce serveur.',
-    'ban.confirm': 'Bannir {user} ?',
-    'ban.yes': 'Bannir',
-    'ban.defaultReason': 'Banni par {by}',
-    'ban.done': 'Banni.',
-    'kick.done': '{user} a été expulsé.',
-    'warn.added': '{user} a maintenant {count} avertissement(s).',
-    'warn.count': {
-      one: '{user} a {count} avertissement.',
-      other: '{user} a {count} avertissements.',
-    },
-  },
-  commands: {
-    // A command can be renamed in a language too: /bannir for French users.
-    ban: {
-      name: 'bannir',
-      description: 'Bannit un membre, après confirmation',
-    },
-    kick: { name: 'expulser', description: 'Expulse un membre' },
-    'warn add': { description: 'Avertit un membre' },
-    'warn list': { description: 'Compte les avertissements d’un membre' },
-  },
-});

package/templates/default/src/(moderation)/warn.ts

@@ -1,42 +0,0 @@
-import { command, event } from 'chapterjs';
-import { addWarning, warningsOf } from './checks';
-
-// Two subcommands in one file: /warn add and /warn list. A subcommand is a
-// matter of `name`, not of folder.
-export const add = command({
-  name: 'warn add',
-  permissions: ['ModerateMembers'],
-  options: {
-    target: { type: 'user', required: true },
-    reason: { type: 'string', required: true },
-  },
-  async run({ interaction, options, t }) {
-    const count = addWarning(options.target.id);
-    await interaction.reply(
-      t('warn.added', { user: options.target.username, count })
-    );
-  },
-});
-
-export const list = command({
-  name: 'warn list',
-  permissions: ['ModerateMembers'],
-  ephemeral: true,
-  options: { target: { type: 'user', required: true } },
-  async run({ interaction, options, t }) {
-    await interaction.reply(
-      t('warn.count', {
-        user: options.target.username,
-        count: warningsOf(options.target.id),
-      })
-    );
-  },
-});
-
-// The event that goes with moderation, next to the commands it follows.
-export const logged = event({
-  name: 'banAdd',
-  run({ user, guild }) {
-    console.log(`${user.username} was banned from ${guild.name}`);
-  },
-});

package/templates/default/src/commands/hello.ts

@@ -1,23 +0,0 @@
-import { asset, command } from 'chapterjs';
-
-// /hello joins your voice channel and plays public/hello.ogg. An Opus file
-// (.ogg, .webm) plays as it is; an .mp3 or a link needs ffmpeg installed.
-export default command({
-  name: 'hello',
-  async run({ interaction, member, t }) {
-    const channel = member.voiceChannel;
-    if (!channel) {
-      await interaction.reply({ content: t('joinVoice'), ephemeral: true });
-      return;
-    }
-    // Answer first: a command has 3 seconds, joining takes a moment.
-    await interaction.reply(t('hello', { channel: channel.name }));
-    const voice = await channel.join();
-    // Whatever happens while it plays, the bot leaves after.
-    try {
-      await voice.play(asset('hello.ogg'));
-    } finally {
-      await voice.leave();
-    }
-  },
-});