chapterjs 0.3.0 → 0.5.0

package/dist/components/button.d.ts

@@ -31,8 +31,12 @@ export interface ButtonLook<Data extends DataShape = DataShape> {
 export type ButtonContext<Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> = InteractiveContext<Data> & TranslationContext & PlaceOf<Where, ComponentInteraction>;
 /** What a file gives to `button()`. */
 export interface ButtonConfig<Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> extends ButtonLook<Data>, InteractiveConfig<Data, Where> {
-    /** What to do when someone clicks the button. */
-    run: (context: ButtonContext<Data, Where>) => unknown;
+    /**
+     * What to do when someone clicks the button. Leave it out for a button
+     * that is only waited for (`message.waitForClick()`): once nothing waits,
+     * a click answers that it is not available any more.
+     */
+    run?: (context: ButtonContext<Data, Where>) => unknown;
 }
 /**
  * What `button()` returns: a declaration the framework finds in the exports
@@ -71,7 +75,8 @@ export interface LoadedButton {
     readonly where: ComponentWhere;
     readonly who: 'everyone' | 'author';
     readonly ephemeral: boolean;
-    readonly run: (context: ButtonContext<DataShape, ComponentWhere>) => unknown;
+    /** `undefined` for a button that is only waited for. */
+    readonly run: ((context: ButtonContext<DataShape, ComponentWhere>) => unknown) | undefined;
 }
 /** Checks what a message gives to change the look of a button. */
 export declare function readLook(what: string, look: unknown): ButtonLook;

package/dist/components/declaration.d.ts

@@ -1,4 +1,4 @@
-import type { Declaration } from '../loader/loader.js';
+import { type Declaration } from '../loader/loader.js';
 import { type LoadedButton } from './button.js';
 import { isEmbedDeclaration } from './embed.js';
 import { type ComponentKind } from './declared.js';
@@ -29,7 +29,7 @@ export declare function findDuplicates<T extends {
         kind: ComponentKind;
         name: string;
     };
-}>(entries: readonly T[]): {
+}>(entries: readonly T[], running?: ReadonlySet<string>): {
     valid: T[];
     conflicts: {
         file: string;

package/dist/components/declaration.js

@@ -4,6 +4,7 @@
 // bound to the name of its export, which is its id and what makes its
 // instances.
 import { Limits } from '../discord/api.js';
+import { bySite } from '../loader/loader.js';
 import { checkEmbed } from '../structures/payload.js';
 import { isDynamic } from './component.js';
 import { readLook, renderButton, } from './button.js';
@@ -93,6 +94,17 @@ function checkRun(what, value, example) {
         fail(`${what} has no "run": the function to run when someone uses it, like ${example}`);
     }
 }
+/**
+ * The `run` of a button or a menu: optional, since one may only be waited
+ * for (`message.waitForClick()`); when given, a function.
+ */
+function checkOptionalRun(what, value, example) {
+    if (value === undefined)
+        return;
+    if (typeof value !== 'function') {
+        fail(`"run" of ${what} is the function to run when someone uses it, like ${example}. Leave it out for one that is only waited for with message.waitForClick().`);
+    }
+}
 function readButton(name, config) {
     if (!isRecord(config)) {
         return fail(`button() needs an object: button({ label: '...', run({ interaction }) { ... } })`);
@@ -118,7 +130,7 @@ function readButton(name, config) {
     if (look.label === undefined && look.emoji === undefined) {
         fail('A button needs a label or an emoji.');
     }
-    checkRun(what, config.run, `async run({ interaction }) { await interaction.update('Done!'); }`);
+    checkOptionalRun(what, config.run, `async run({ interaction }) { await interaction.update('Done!'); }`);
     return Object.freeze({
         kind: 'button',
         name,
@@ -168,7 +180,7 @@ function readSelect(name, config) {
     }
     const options = type === 'string' ? readOptions(what, config.options) : [];
     const placeholder = readPlaceholder(what, config.placeholder);
-    checkRun(what, config.run, `async run({ interaction, values }) { ... }`);
+    checkOptionalRun(what, config.run, `async run({ interaction, values }) { ... }`);
     return Object.freeze({
         kind: 'select',
         name,
@@ -310,18 +322,10 @@ export const componentDeclaration = {
     },
 };
 /** Two components of the same kind with the same name: the later one is left out. */
-export function findDuplicates(entries) {
+export function findDuplicates(entries, running) {
     const seen = new Map();
     const conflicts = [];
-    const valid = [...entries]
-        .sort((a, b) => a.file === b.file
-        ? a.export < b.export
-            ? -1
-            : 1
-        : a.file < b.file
-            ? -1
-            : 1)
-        .filter(entry => {
+    const valid = bySite(entries, running).filter(entry => {
         const key = `${entry.component.kind}:${entry.component.name}`;
         const first = seen.get(key);
         if (!first) {

package/dist/components/render.js

@@ -46,6 +46,11 @@ export function renderComponents(components, t = missingTranslator(null)) {
     const v2 = rows.some(one => one.kind !== 'row');
     // The texts of a piece may be computed now, for who will read the message.
     const raw = rows.map(one => resolve(one, t).raw);
+    // Without the pieces of the new layout, a message is rows only, and
+    // Discord takes 5 of them.
+    if (!v2 && raw.length > Limits.MessageActionRows) {
+        throw new RangeError(`The message has ${raw.length} rows of components: Discord accepts ${Limits.MessageActionRows} at most. A menu takes a row by itself and up to 5 buttons share one: send the rest in another message.`);
+    }
     const total = count(raw);
     if (total > Limits.MessageComponents) {
         throw new RangeError(`The message has ${total} components once its rows are made: Discord accepts ${Limits.MessageComponents} at most.`);

package/dist/components/router.js

@@ -10,6 +10,7 @@ import { ComponentInteraction, ModalInteraction, } from '../structures/interacti
 import { remember } from '../structures/known.js';
 import { toCamelCase } from '../util/case.js';
 import { decodeCustomId, readData } from './custom-id.js';
+import { componentStateOf } from './declared.js';
 import { SELECT_TYPES } from './select.js';
 /** What a component is called, for the person and the developer. */
 const WHAT_OF = {
@@ -130,6 +131,32 @@ export class ComponentRouter {
             this.#options.onError(file, error);
             return refuse(interaction, 'failed', { what });
         }
+        // A click a function of the files waits for (`message.waitForClick()`)
+        // is theirs: the `run` of the component does not run.
+        if (component.kind !== 'modal' && ctx.waiters?.wants('click')) {
+            const click = Object.freeze({
+                messageId: message.id,
+                interaction: interaction,
+                user,
+                member: place.member ?? null,
+                name,
+                data: Object.freeze(values),
+                values: Object.freeze([
+                    ...(data.values ?? []),
+                ]),
+                is: (declared) => {
+                    const state = componentStateOf(declared);
+                    return state?.kind === component.kind && state.bound?.name === name;
+                },
+            });
+            if (ctx.waiters.offer('click', click)) {
+                return this.#waited(interaction);
+            }
+        }
+        if (!component.run) {
+            // Only waited for, and nothing waits any more.
+            return refuse(interaction, 'gone', { what });
+        }
         const context = Object.freeze({
             interaction,
             user,
@@ -160,6 +187,20 @@ export class ComponentRouter {
             run: () => component.run(context),
         });
     }
+    /**
+     * A click taken by a wait: the files answer it where they waited. When
+     * they did not after 2 seconds, nothing changes on screen
+     * (`deferUpdate()`), so the person never sees "This interaction failed".
+     */
+    #waited(interaction) {
+        const timer = setTimeout(() => {
+            if (!interaction.answered && !interaction.deferred) {
+                interaction.deferUpdate().catch(() => { });
+            }
+        }, this.#options.deferAfter ?? 2000);
+        timer.unref();
+        return Promise.resolve();
+    }
     /** What the person picked in a menu, as structures where it applies. */
     #readValues(ctx, raw, type, data) {
         const values = resolveValues(ctx, raw, type, data.values ?? [], data.resolved ?? {});

package/dist/components/select.d.ts

@@ -67,8 +67,11 @@ export interface StringSelectConfig<Options extends SelectOptions, Data extends
      * shown to what your code receives, or a list of `RichOption`.
      */
     options: Options;
-    /** What to do when something is picked. */
-    run: (context: SelectContext<OptionValue<Options>, Data, Where>) => unknown;
+    /**
+     * What to do when something is picked. Leave it out for a menu that is
+     * only waited for (`message.waitForClick()`).
+     */
+    run?: (context: SelectContext<OptionValue<Options>, Data, Where>) => unknown;
 }
 /** A menu of users, roles, users and roles, or channels of the server. */
 export interface EntitySelectConfig<Type extends EntitySelectType, Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> extends SelectConfigBase<Data, Where> {
@@ -76,8 +79,11 @@ export interface EntitySelectConfig<Type extends EntitySelectType, Data extends
     type: Type;
     /** For a menu of channels: the kinds of channels listed. All by default. */
     channelTypes?: readonly ChannelType[];
-    /** What to do when something is picked. */
-    run: (context: SelectContext<EntityValues[Type], Data, Where>) => unknown;
+    /**
+     * What to do when something is picked. Leave it out for a menu that is
+     * only waited for (`message.waitForClick()`).
+     */
+    run?: (context: SelectContext<EntityValues[Type], Data, Where>) => unknown;
 }
 /** What a select file gives to `select()`: a menu of texts, or of things of the server. */
 export type SelectConfig<Options extends SelectOptions = SelectOptions, Type extends EntitySelectType = EntitySelectType, Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> = StringSelectConfig<Options, Data, Where> | EntitySelectConfig<Type, Data, Where>;
@@ -126,7 +132,8 @@ export interface LoadedSelect {
     readonly where: ComponentWhere;
     readonly who: 'everyone' | 'author';
     readonly ephemeral: boolean;
-    readonly run: (context: SelectContext<unknown, DataShape, ComponentWhere>) => unknown;
+    /** `undefined` for a menu that is only waited for. */
+    readonly run: ((context: SelectContext<unknown, DataShape, ComponentWhere>) => unknown) | undefined;
 }
 /** Checks `min` and `max` of a menu, a group of checkboxes or a file upload. */
 export declare function readRange(what: string, given: {

package/dist/core/bot.d.ts

@@ -5,6 +5,7 @@ import { Gateway, type GatewayOptions } from '../gateway/gateway.js';
 import type { ShardEvent } from '../gateway/shard.js';
 import { type RestOptions } from '../rest/rest.js';
 import type { Context } from '../structures/context.js';
+import { type Waiters } from '../waiting/waiters.js';
 /** What a dispatched event is, besides its data. */
 export interface DispatchInfo {
     shardId: number;
@@ -71,11 +72,17 @@ export interface BotOptions {
      * (an outage of Discord). Default: 15000.
      */
     guildsTimeout?: number;
+    /**
+     * What the files wait for (`channel.waitForMessage()`...): in memory by
+     * default.
+     */
+    waiters?: Waiters;
     /** Only tests change these. */
     rest?: Partial<RestOptions>;
     gateway?: Pick<GatewayOptions, 'backoff' | 'identifyInterval'>;
     voice?: {
         secure?: boolean;
+        unavailable?: string;
     };
 }
 export interface Bot {

package/dist/core/bot.js

@@ -9,6 +9,34 @@ import { createContext } from '../structures/entities.js';
 import { GatewayOpcode } from '../discord/codes.js';
 import { GatewayIntent } from '../discord/intents.js';
 import { VoiceManager } from '../voice/connection.js';
+import { MemoryWaiters } from '../waiting/waiters.js';
+import { GetUser } from '../discord/endpoints.js';
+import { toCamelCase } from '../util/case.js';
+/**
+ * Gives a reaction to what waits for one, with who reacted: the member
+ * Discord sends in a server, else the user the bot knows, else asked.
+ * @see https://docs.discord.com/developers/events/gateway-events#message-reaction-add
+ */
+function offerReaction(ctx, data) {
+    const member = data.member && data.guild_id
+        ? ctx.entities.member(data.guild_id, data.member)
+        : null;
+    const known = member?.user ?? ctx.cache.users.get(data.user_id);
+    const user = known
+        ? Promise.resolve(known)
+        : ctx.rest
+            .request(GetUser, [data.user_id])
+            .then(raw => ctx.entities.user(raw));
+    user
+        .then(user => ctx.waiters?.offer('reaction', {
+        messageId: data.message_id,
+        emoji: toCamelCase(data.emoji),
+        user,
+        member,
+    }))
+        // Who reacted could not be known: nothing to give.
+        .catch(() => { });
+}
 /** The server a gateway event belongs to, when it belongs to one. */
 function guildIdOf(event, data) {
     if (typeof data !== 'object' || data === null)
@@ -38,6 +66,8 @@ export function createBot(options) {
         ...options.rest,
     });
     const ctx = createContext({ rest, cache: new Cache(options.cache) });
+    const waiters = options.waiters ?? new MemoryWaiters();
+    ctx.waiters = waiters;
     /** Servers announced by Ready whose data has not come yet, per shard. */
     const pending = new Map();
     let guildsReady = null;
@@ -129,6 +159,15 @@ export function createBot(options) {
             else if (event === 'VOICE_SERVER_UPDATE') {
                 voice.onVoiceServer(data);
             }
+            // What the files wait for: built only when a wait wants it.
+            if (event === 'MESSAGE_CREATE' && waiters.wants('message')) {
+                const message = data;
+                waiters.offer('message', ctx.entities.message(message));
+            }
+            else if (event === 'MESSAGE_REACTION_ADD' &&
+                waiters.wants('reaction')) {
+                offerReaction(ctx, data);
+            }
             options.onDispatch?.(event, data, { shardId, joined, before });
             if (awaited)
                 checkGuilds();
@@ -143,6 +182,9 @@ export function createBot(options) {
         ...(options.voice?.secure === undefined
             ? {}
             : { secure: options.voice.secure }),
+        ...(options.voice?.unavailable === undefined
+            ? {}
+            : { unavailable: options.voice.unavailable }),
     });
     ctx.voice = voice;
     return {
@@ -167,6 +209,8 @@ export function createBot(options) {
                 clearTimeout(guildsTimer);
             guildsTimer = null;
             voice.closeAll();
+            // What the files waited for will not come: they go on with nothing.
+            waiters.close();
             await gateway.close();
         },
         setPresence: presence => gateway.setPresence(presence),

package/dist/discord/api.d.ts

@@ -74,6 +74,8 @@ export declare const Limits: {
     readonly CustomId: 100;
     /** @see https://docs.discord.com/developers/components/reference#component-object */
     readonly MessageComponents: 40;
+    /** @see https://docs.discord.com/developers/components/reference#legacy-message-component-behavior */
+    readonly MessageActionRows: 5;
     /** @see https://docs.discord.com/developers/components/reference#action-row */
     readonly ActionRowButtons: 5;
     /** @see https://docs.discord.com/developers/components/reference#button-button-structure */

package/dist/discord/api.js

@@ -77,6 +77,8 @@ export const Limits = {
     CustomId: 100,
     /** @see https://docs.discord.com/developers/components/reference#component-object */
     MessageComponents: 40,
+    /** @see https://docs.discord.com/developers/components/reference#legacy-message-component-behavior */
+    MessageActionRows: 5,
     /** @see https://docs.discord.com/developers/components/reference#action-row */
     ActionRowButtons: 5,
     /** @see https://docs.discord.com/developers/components/reference#button-button-structure */

package/dist/discord/permissions.d.ts

@@ -12,11 +12,11 @@ export declare const ALL_PERMISSIONS: bigint;
  */
 export declare const ELEVATED_PERMISSIONS: readonly PermissionName[];
 /**
- * A set of permissions that never changes: every operation returns a new
- * set. Discord serializes permissions as text because they don't fit in a
- * regular number.
- * @see https://docs.discord.com/developers/topics/permissions
+ * A permission as people read it: `BanMembers` is "Ban Members". For what
+ * the bot says to the people of a server, never to the developer, who
+ * writes the names as they are.
  */
+export declare function permissionWords(name: PermissionName): string;
 export declare class Permissions {
     /** The permissions as one number, each bit being a permission. */
     readonly bits: bigint;

package/dist/discord/permissions.js

@@ -42,6 +42,19 @@ function resolve(permission) {
  * regular number.
  * @see https://docs.discord.com/developers/topics/permissions
  */
+/** Letters that are said one by one in the name of a permission. */
+const ACRONYMS = { Tts: 'TTS', Vad: 'VAD' };
+/**
+ * A permission as people read it: `BanMembers` is "Ban Members". For what
+ * the bot says to the people of a server, never to the developer, who
+ * writes the names as they are.
+ */
+export function permissionWords(name) {
+    return name
+        .split(/(?=[A-Z])/)
+        .map(word => ACRONYMS[word] ?? word)
+        .join(' ');
+}
 export class Permissions {
     /** The permissions as one number, each bit being a permission. */
     bits;