create-chapter 0.2.2 → 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/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();
-    }
-  },
-});

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

@@ -1,55 +0,0 @@
-import { button, command } from 'chapterjs';
-
-// A command is declared with command() and exported: `name` is what people
-// type after the /. Where the file is and what it is called are up to you:
-// this one could live anywhere in src/.
-export default command({
-  name: 'ping',
-  // Only the person sees the answer, so `t` speaks their language.
-  ephemeral: true,
-  async run({ interaction, t }) {
-    // The button below, with the data it carries, and a text of
-    // src/messages/ in the language of who will read the answer.
-    await interaction.reply({
-      content: t('pong'),
-      components: [again({ count: 1 })],
-    });
-  },
-});
-
-// A button is declared with button() and exported: the name of the export
-// (here `again`) is what tells which one was clicked, you never write an
-// id. `data` is what the button carries from one click to the next.
-export const again = button({
-  label: 'Again',
-  data: { count: 'number' },
-  async run({ interaction, data, t }) {
-    const count = data.count + 1;
-    // Changes the message the button is on, instead of sending a new one.
-    await interaction.update({
-      content: t('again', { count }),
-      components: [again({ count })],
-    });
-  },
-});
-
-// A command can ask for options, typed for you in `run`, suggest values
-// while the person types, and make each person wait between two uses:
-//
-// export const hello = command({
-//   name: 'hello',
-//   description: 'Says hello to someone',
-//   cooldown: '10s',
-//   options: {
-//     who: { type: 'user', description: 'Who to greet', required: true },
-//     greeting: { type: 'string', description: 'How to greet' },
-//   },
-//   autocomplete: {
-//     // Called while the person types in "greeting", with what they typed.
-//     greeting: ({ value }) =>
-//       ['Hello', 'Hi', 'Hey'].filter(word => word.startsWith(value)),
-//   },
-//   async run({ interaction, options }) {
-//     await interaction.reply(`${options.greeting ?? 'Hello'} ${options.who}!`);
-//   },
-// });

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

@@ -1,41 +0,0 @@
-import { command } from 'chapterjs';
-
-// /play plays a song in your voice channel: a file you send with the
-// command, or a link to an audio file or a stream. play() takes both.
-export default command({
-  name: 'play',
-  options: {
-    file: { type: 'attachment' },
-    url: { type: 'string' },
-  },
-  async run({ interaction, member, options, t }) {
-    const { file, url } = options;
-    const song = file ?? url;
-    if (
-      !song ||
-      (file && !file.contentType?.startsWith('audio/')) ||
-      (url && !/^https?:\/\//.test(url))
-    ) {
-      await interaction.reply({ content: t('nothingToPlay'), ephemeral: true });
-      return;
-    }
-    const channel = member.voiceChannel;
-    if (!channel) {
-      await interaction.reply({ content: t('joinVoice'), ephemeral: true });
-      return;
-    }
-    const name = file?.filename ?? url ?? '';
-    await interaction.reply(
-      t('playing', { song: name, channel: channel.name })
-    );
-    // Joining the channel the bot is already in changes nothing, and a new
-    // play() replaces what was playing.
-    const voice = await channel.join();
-    // Whatever happens while it plays, the bot leaves after.
-    try {
-      await voice.play(song);
-    } finally {
-      await voice.leave();
-    }
-  },
-});

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

@@ -1,14 +0,0 @@
-import { event } from 'chapterjs';
-
-// Runs every time someone adds a reaction to a message of your server.
-// Reactions of bots, yours included, are left out: when yours waves back
-// below, this does not run again. Other events work the same way:
-// voiceJoin, pollVoteAdd, banAdd... (see the list of events in the docs).
-export default event({
-  name: 'reactionAdd',
-  async run({ emoji, channel, messageId }) {
-    if (emoji.name !== '👋') return;
-    const message = await channel.fetchMessage(messageId);
-    await message.react('👋');
-  },
-});

package/templates/default/src/messages/en-US.ts

@@ -1,36 +0,0 @@
-import { language } from 'chapterjs';
-
-// A language is declared with language(): `locale` says which one. Each
-// function of your project receives `t`, which picks the language of who
-// will read the message: t('pong'), t('again', { count }).
-export default language({
-  locale: 'en-US',
-  // The language used when the one of a person or of a server is not here.
-  default: true,
-  texts: {
-    pong: 'Pong! in en-US',
-    again: 'Pong in en-US ! ×{count}',
-    joinVoice: 'Join a voice channel first, then ask again.',
-    hello: 'Coming to {channel}!',
-    nothingToPlay:
-      'Send an audio file (.mp3, .ogg...) or a link starting with https://.',
-    playing: 'Playing {song} in {channel}.',
-  },
-  // What Discord shows of each command, by its name: its description, and
-  // the ones of its options. A command described here has none in its file.
-  commands: {
-    ping: {
-      description: 'Replies with Pong!',
-    },
-    hello: {
-      description: 'Says hello in your voice channel',
-    },
-    play: {
-      description: 'Plays a song in your voice channel',
-      options: {
-        file: { description: 'A song to play' },
-        url: { description: 'Or the link of a song or a stream' },
-      },
-    },
-  },
-});

package/templates/default/src/messages/fr.ts

@@ -1,37 +0,0 @@
-import { language } from 'chapterjs';
-
-// Every language has the texts of the default one, with the same
-// {placeholders}: a missing one is reported when the file loads.
-export default language({
-  locale: 'fr',
-  texts: {
-    pong: 'Pong! en fr',
-    again: 'Pong en fr ! ×{count}',
-    joinVoice: 'Rejoignez d’abord un salon vocal, puis redemandez.',
-    hello: 'J’arrive dans {channel} !',
-    nothingToPlay:
-      'Envoyez un fichier audio (.mp3, .ogg...) ou un lien qui commence par https://.',
-    playing: 'Lecture de {song} dans {channel}.',
-  },
-  // What the bot answers by itself can be translated too, phrase by phrase:
-  //
-  // framework: {
-  //   command: 'commande',
-  //   failed: "Quelque chose s'est mal passé avec cette {what}.",
-  // },
-  commands: {
-    ping: {
-      description: 'Répond avec Pong !',
-    },
-    hello: {
-      description: 'Dit bonjour dans votre salon vocal',
-    },
-    play: {
-      description: 'Joue une musique dans votre salon vocal',
-      options: {
-        file: { description: 'Une musique à jouer' },
-        url: { description: 'Ou le lien d’une musique ou d’un flux' },
-      },
-    },
-  },
-});

package/templates/default/src/presence.ts

@@ -1,8 +0,0 @@
-import { presence } from 'chapterjs';
-
-// What your bot shows under its name: its status, and what it is doing.
-// Save this file and chapterjs dev changes it at once.
-export default presence({
-  status: 'online',
-  activity: { type: 'playing', name: 'with ChapterJS' },
-});