chapterjs 0.4.0 → 0.5.0

package/dist/presence/rotation.d.ts

@@ -0,0 +1,32 @@
+import type { RawGatewayPresenceUpdate } from '../discord/types/gateway-events.js';
+import { type LoadedActivity, type LoadedPresence } from './declaration.js';
+import type { PresenceContext } from './presence.js';
+export interface RotationOptions {
+    /** Sends a presence to the bot of the moment. */
+    apply(raw: RawGatewayPresenceUpdate): void;
+    /** What the functions receive, or `null` while there is no bot to show it. */
+    context(): PresenceContext | null;
+    /** A function of the file threw, or gave something wrong. Said once until it changes. */
+    onError(error: unknown): void;
+    /** The clock, in milliseconds (tests). */
+    now?: () => number;
+}
+/**
+ * Which activity of a list the clock says to show, and how long until the
+ * next one.
+ */
+export declare function activityAt(activities: readonly LoadedActivity[], now: number): {
+    index: number;
+    left: number;
+};
+/** The presence of the project, shown in turn while it is started. */
+export declare class PresenceRotation {
+    #private;
+    constructor(options: RotationOptions);
+    /** Changes the presence (a load, a reload): shown at once when started. */
+    set(presence: LoadedPresence | null): void;
+    /** Starts showing the presence. */
+    start(): void;
+    /** Stops: nothing runs after this. */
+    stop(): void;
+}

package/dist/presence/rotation.js

@@ -0,0 +1,167 @@
+// Shows the activities of the presence in turn, each for its `for`, and
+// runs the functions of the file when their activity comes: the text of an
+// activity, or the list itself.
+//
+// Which activity is shown is read from the clock: the list is a cycle
+// starting at the epoch, so every process of a large bot shows the same
+// activity at the same time, with nothing to coordinate.
+import { checkText, DEFAULT_FOR, DEFAULT_PRESENCE, readActivities, toRaw, } from './declaration.js';
+/** How long to wait for a bot before trying again. */
+const NO_BOT_RETRY = 1_000;
+/**
+ * Which activity of a list the clock says to show, and how long until the
+ * next one.
+ */
+export function activityAt(activities, now) {
+    const cycle = activities.reduce((sum, one) => sum + one.for, 0);
+    let position = now % cycle;
+    for (const [index, activity] of activities.entries()) {
+        if (position < activity.for) {
+            return { index, left: activity.for - position };
+        }
+        position -= activity.for;
+    }
+    // Not reached: the position is below the cycle.
+    return { index: 0, left: activities[0].for };
+}
+/** The presence of the project, shown in turn while it is started. */
+export class PresenceRotation {
+    #options;
+    #now;
+    #presence = null;
+    #started = false;
+    #timer;
+    /** Each tick has its number: one started since then makes it give up. */
+    #generation = 0;
+    /** The list a function gave last, and until when it is used. */
+    #list = null;
+    #listUntil = 0;
+    /** The last text of each activity a function gave, by its place. */
+    #texts = new Map();
+    /** What was said last of each function (`list`, or the place of an activity). */
+    #problems = new Map();
+    constructor(options) {
+        this.#options = options;
+        this.#now = options.now ?? Date.now;
+    }
+    /** Changes the presence (a load, a reload): shown at once when started. */
+    set(presence) {
+        this.#presence = presence;
+        this.#list = null;
+        this.#texts.clear();
+        this.#problems.clear();
+        if (this.#started)
+            void this.#tick();
+    }
+    /** Starts showing the presence. */
+    start() {
+        this.#started = true;
+        void this.#tick();
+    }
+    /** Stops: nothing runs after this. */
+    stop() {
+        this.#started = false;
+        this.#generation++;
+        clearTimeout(this.#timer);
+    }
+    /** What is shown right now, as the gateway sends it: one step of the cycle. */
+    async #tick() {
+        const generation = ++this.#generation;
+        clearTimeout(this.#timer);
+        const current = () => this.#started && generation === this.#generation;
+        const presence = this.#presence;
+        if (!presence) {
+            this.#options.apply(DEFAULT_PRESENCE);
+            return;
+        }
+        const context = this.#options.context();
+        if (!context) {
+            this.#later(NO_BOT_RETRY);
+            return;
+        }
+        let activities;
+        if (typeof presence.activities === 'function') {
+            if (this.#list === null || this.#now() >= this.#listUntil) {
+                try {
+                    const given = await presence.activities(context);
+                    if (!current())
+                        return;
+                    this.#list = readActivities(given);
+                    this.#texts.clear();
+                    this.#problems.delete('list');
+                }
+                catch (error) {
+                    if (!current())
+                        return;
+                    this.#problem('list', error);
+                    // The last good list stays; none at all shows the status alone.
+                    this.#list ??= [];
+                }
+                const cycle = this.#list.reduce((sum, one) => sum + one.for, 0);
+                this.#listUntil = this.#now() + (cycle || DEFAULT_FOR);
+            }
+            activities = this.#list;
+        }
+        else {
+            activities = presence.activities;
+        }
+        if (activities.length === 0) {
+            this.#options.apply(toRaw(presence.status, null, ''));
+            // A function may give activities later.
+            if (typeof presence.activities === 'function') {
+                this.#later(this.#listUntil - this.#now());
+            }
+            return;
+        }
+        const { index, left } = activityAt(activities, this.#now());
+        const activity = activities[index];
+        let text;
+        if (typeof activity.name === 'function') {
+            try {
+                text = checkText(await activity.name(context));
+                if (!current())
+                    return;
+                this.#texts.set(index, text);
+                this.#problems.delete(`name ${index}`);
+            }
+            catch (error) {
+                if (!current())
+                    return;
+                this.#problem(`name ${index}`, error);
+                text = this.#texts.get(index);
+            }
+        }
+        else {
+            text = activity.name;
+        }
+        if (text !== undefined) {
+            this.#options.apply(toRaw(presence.status, activity, text));
+        }
+        const moves = activities.length > 1 ||
+            typeof activity.name === 'function' ||
+            typeof presence.activities === 'function';
+        if (moves) {
+            // A list that ends before this activity does is asked again then.
+            const until = typeof presence.activities === 'function'
+                ? Math.min(left, Math.max(0, this.#listUntil - this.#now()))
+                : left;
+            this.#later(until);
+        }
+    }
+    #later(ms) {
+        if (!this.#started)
+            return;
+        // At least 1 ms: a list asked again on the very boundary.
+        this.#timer = setTimeout(() => void this.#tick(), Math.max(1, ms));
+        // Nothing of the bot waits for it: the gateway keeps the process up.
+        this.#timer.unref();
+    }
+    /** Says what went wrong with a function, once until it changes. */
+    #problem(what, error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (this.#problems.get(what) === message)
+            return;
+        this.#problems.set(what, message);
+        this.#options.onError(error);
+    }
+}

package/dist/rest/errors.d.ts

@@ -15,7 +15,6 @@ export interface DiscordFieldError {
  * @see https://docs.discord.com/developers/reference#error-messages
  */
 export declare function flattenFieldErrors(errors: unknown, path?: string): DiscordFieldError[];
-/** Discord answered a request with an error. */
 export declare class DiscordApiError extends Error {
     readonly name = "DiscordApiError";
     /** The HTTP status of the response (403, 404...). */

package/dist/rest/errors.js

@@ -32,6 +32,19 @@ export function flattenFieldErrors(errors, path = '') {
     return found;
 }
 /** Discord answered a request with an error. */
+/**
+ * What a refusal means, in plain words, for the codes a bot meets most: the
+ * text of Discord names the problem, not what to do about it.
+ * @see https://docs.discord.com/developers/topics/opcodes-and-status-codes#json-json-error-codes
+ */
+const HINTS = {
+    50013: "The bot is missing a permission for this, or acts on someone above it: the owner of the server, or a member or role higher than the bot's highest role.",
+    50001: 'The bot can not see this channel or server: give it View Channel there, or check that it is still in the server.',
+    10008: 'The message does not exist any more: it was deleted.',
+    10003: 'The channel does not exist any more: it was deleted.',
+    10007: 'This person is not a member of the server any more.',
+    50007: 'This person does not accept private messages from the bot: they closed them, or share no server with it.',
+};
 export class DiscordApiError extends Error {
     name = 'DiscordApiError';
     /** The HTTP status of the response (403, 404...). */
@@ -62,7 +75,8 @@ export class DiscordApiError extends Error {
         const details = fieldErrors
             .map(error => `\n  ${error.path || 'request'}: ${error.message}`)
             .join('');
-        super(`Discord refused ${input.method} ${input.route}: ${reason} (${code || input.status})${details}`);
+        const hint = HINTS[code] ? ` ${HINTS[code]}` : '';
+        super(`Discord refused ${input.method} ${input.route}: ${reason} (${code || input.status}).${hint}${details}`);
         this.status = input.status;
         this.code = code;
         this.fieldErrors = fieldErrors;

package/dist/rest/rest.js

@@ -1,5 +1,6 @@
 // The only place that sends HTTP requests to Discord.
 // https://docs.discord.com/developers/reference#http-api
+import { callSite, fromSite } from '../util/call-site.js';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { API_BASE_URL, API_VERSION, AUDIT_LOG_REASON_MAX_LENGTH, userAgent, } from '../discord/api.js';
 import { HttpStatus } from '../discord/codes.js';
@@ -68,7 +69,15 @@ export class RestClient {
             onWait: options.onRateLimit,
         });
     }
-    async request(endpoint, params, options = {}) {
+    request(endpoint, params, options = {}) {
+        // Taken now, while the files are in the stack: a refusal that comes
+        // later still names their line, even when they did not await.
+        const site = callSite();
+        return this.#send(endpoint, params, options).catch((error) => {
+            throw fromSite(error, site);
+        });
+    }
+    async #send(endpoint, params, options) {
         const auth = options.auth ?? true;
         if (auth && this.#tokenRefused)
             throw new InvalidTokenError();

package/dist/store/file-backend.d.ts

@@ -8,7 +8,6 @@ export interface FileStoreBackendOptions {
     sweepEvery?: number;
     now?: () => number;
 }
-/** The data of every store, one file each, loaded on first use. */
 export declare class FileStoreBackend implements StoreBackend {
     #private;
     constructor(dir: string, options?: FileStoreBackendOptions);

package/dist/store/file-backend.js

@@ -12,6 +12,21 @@ export const DATA_FOLDER = 'data';
 /** A name a file can be called: what an export is called. */
 const FILE_NAME = /^[\w.-]+$/;
 /** The data of every store, one file each, loaded on first use. */
+/**
+ * One entry as this backend writes it: `[key parts, value, expiresAt]`. An
+ * entry of another shape makes the whole file one it did not write, rather
+ * than an entry dropped without a word the next time the file is written.
+ */
+function isEntry(entry) {
+    if (!Array.isArray(entry) || entry.length !== 3)
+        return false;
+    const [key, value, expiresAt] = entry;
+    return (Array.isArray(key) &&
+        key.length > 0 &&
+        key.every(part => typeof part === 'string') &&
+        value !== undefined &&
+        (expiresAt === null || typeof expiresAt === 'number'));
+}
 export class FileStoreBackend {
     #dir;
     #stores = new Map();
@@ -55,7 +70,9 @@ export class FileStoreBackend {
             let parsed;
             try {
                 parsed = JSON.parse(text);
-                if (parsed?.version !== 1 || !Array.isArray(parsed.entries)) {
+                if (parsed?.version !== 1 ||
+                    !Array.isArray(parsed.entries) ||
+                    !parsed.entries.every(isEntry)) {
                     throw new Error('not a store file');
                 }
             }

package/dist/store/scope.d.ts

@@ -1,4 +1,4 @@
-/** Runs `fn` for a server (or for none, with `null`). */
+/** Runs `fn` for a server (or for none, with `null`), as one run. */
 export declare function withGuild<T>(guildId: string | null, fn: () => T): T;
 /**
  * The id of the server the current function runs for: `null` when it runs
@@ -6,6 +6,11 @@ export declare function withGuild<T>(guildId: string | null, fn: () => T): T;
  * the framework runs.
  */
 export declare function currentGuildId(): string | null | undefined;
+/**
+ * The run of a function of the files the current code belongs to, or
+ * `undefined` outside any.
+ */
+export declare function currentRun(): object | undefined;
 /**
  * The scope part of a key, for data per server or for the whole bot: the
  * id of the server the code runs for (`guildOf`), or nothing for a global

package/dist/store/scope.js

@@ -4,11 +4,10 @@
 // the routers around every function they run, on an asynchronous context
 // of Node, so it follows the `await`s into the files the function imports.
 import { AsyncLocalStorage } from 'node:async_hooks';
-/** The id of the server the current function runs for, or `null` for none. */
 const scope = new AsyncLocalStorage();
-/** Runs `fn` for a server (or for none, with `null`). */
+/** Runs `fn` for a server (or for none, with `null`), as one run. */
 export function withGuild(guildId, fn) {
-    return scope.run(guildId, fn);
+    return scope.run({ guildId }, fn);
 }
 /**
  * The id of the server the current function runs for: `null` when it runs
@@ -16,6 +15,13 @@ export function withGuild(guildId, fn) {
  * the framework runs.
  */
 export function currentGuildId() {
+    return scope.getStore()?.guildId;
+}
+/**
+ * The run of a function of the files the current code belongs to, or
+ * `undefined` outside any.
+ */
+export function currentRun() {
     return scope.getStore();
 }
 /**

package/dist/structures/channel.d.ts

@@ -1,3 +1,4 @@
+import { type CollectMessagesOptions, type WaitForMessageOptions } from './wait.js';
 import type { CacheStore } from '../cache/store.js';
 import { Permissions, type PermissionResolvable } from '../discord/permissions.js';
 import { ChannelType, type CreateChannelInviteJSONParams, type ModifyGuildChannelJSONParams, type ModifyThreadJSONParams, type RawChannel, type RawForumTag, type RawThreadMember, type StartThreadWithoutMessageJSONParams } from '../discord/types/channel.js';
@@ -117,6 +118,18 @@ export interface TextBasedMethods {
      * @see https://docs.discord.com/developers/resources/message#get-channel-pins
      */
     fetchPins(): Promise<Message[]>;
+    /**
+     * Waits for the next message of the channel that fits: of a person
+     * (`from`), saying something (`matches`). Anyone's but a bot's by
+     * default. Resolves with the message, or `null` when `within` (one
+     * minute by default) passed first. A restart of the bot ends the wait.
+     */
+    waitForMessage(options?: WaitForMessageOptions): Promise<Message | null>;
+    /**
+     * Gathers the messages of the channel that fit, until `within` (one
+     * minute by default) passed or `max` came. Resolves with them, in order.
+     */
+    collectMessages(options?: CollectMessagesOptions): Promise<Message[]>;
 }
 /** What a role or a member is allowed or denied in one channel. */
 export interface PermissionOverwrite {

package/dist/structures/channel.js

@@ -1,3 +1,4 @@
+import { personId, readMatches, readWithin, waitFor, } from './wait.js';
 import { Limits } from '../discord/api.js';
 import { AddThreadMember, BulkDeleteMessages, CreateChannelInvite, CreateWebhook, DeleteChannelPermission, DeleteCloseChannel, DeleteMessage, EditChannelPermissions, FollowAnnouncementChannel, GetChannel, GetChannelInvites, GetChannelMessage, GetChannelMessages, GetChannelPins, GetChannelWebhooks, JoinThread, LeaveThread, ListThreadMembers, ModifyChannel, RemoveThreadMember, SetVoiceChannelStatus, StartThreadInForumOrMediaChannel, StartThreadWithoutMessage, TriggerTypingIndicator, } from '../discord/endpoints.js';
 import { channelMention } from '../discord/formatting.js';
@@ -180,7 +181,30 @@ const textBasedMethods = {
             before = last.pinned_at;
         }
     },
+    async waitForMessage(options = {}) {
+        const [message] = await waitForMessages(this, options, 1);
+        return message ?? null;
+    },
+    collectMessages(options = {}) {
+        const { max } = options;
+        if (max !== undefined && (!Number.isInteger(max) || max < 1)) {
+            throw new RangeError(`"max" is how many messages to gather at most, a whole number from 1: got ${max}.`);
+        }
+        return waitForMessages(this, options, max ?? Infinity);
+    },
 };
+/**
+ * The next messages of a channel that fit the options: what
+ * `waitForMessage()` and `collectMessages()` share.
+ */
+function waitForMessages(channel, options, max) {
+    const within = readWithin(options.within);
+    const from = personId(options.from);
+    const says = readMatches(options.matches);
+    return waitFor(channel, 'message', message => message.channelId === channel.id &&
+        (from ? message.author.id === from : !message.author.bot) &&
+        says(message), within, max);
+}
 /**
  * A channel of a server (not a thread).
  * @see https://docs.discord.com/developers/resources/channel#channel-object

package/dist/structures/context.d.ts

@@ -3,6 +3,7 @@ import type { Snowflake } from '../discord/types/common.js';
 import type { LoadedMessages } from '../messages/translate.js';
 import type { Rest } from '../rest/rest.js';
 import type { VoiceManager } from '../voice/connection.js';
+import type { Waiters } from '../waiting/waiters.js';
 import type { Entities } from './entities.js';
 /**
  * What every structure works with. It never leaves the framework: user code
@@ -22,6 +23,8 @@ export interface Context {
     messages: LoadedMessages | null;
     /** Where the bot is in voice; `null` outside a running bot. */
     voice: VoiceManager | null;
+    /** What the files are waiting for; `null` outside a running bot. */
+    waiters: Waiters | null;
 }
 /** The identity of the bot, for actions that need it. */
 export declare function selfOf(ctx: Context): {

package/dist/structures/entities.js

@@ -220,6 +220,7 @@ export function createContext(input) {
         self: null,
         messages: null,
         voice: null,
+        waiters: null,
     };
     ctx.entities = new Entities(ctx);
     return ctx;

package/dist/structures/interaction.d.ts

@@ -13,6 +13,12 @@ import type { User } from './user.js';
 export type InteractionData = Omit<RawInteraction, 'user' | 'member' | 'message'>;
 /** Only the framework reads how far an interaction was answered. */
 export declare let isUpdating: (interaction: Interaction) => boolean;
+/**
+ * Resolves once every answer asked so far was sent (or refused): what the
+ * framework waits for before saying a function never answered, since an
+ * answer asked without `await` is still on its way when it returns.
+ */
+export declare let answersSent: (interaction: Interaction) => Promise<void>;
 /** An answer to an interaction: its text, or its options. */
 export type InteractionReply = string | InteractionReplyOptions;
 /** The options of an answer: everything a message takes, except `replyTo` and `stickers`. */

package/dist/structures/interaction.js

@@ -1,3 +1,4 @@
+import { callSite, fromSite } from '../util/call-site.js';
 import { CreateFollowupMessage, CreateInteractionResponse, DeleteOriginalInteractionResponse, EditOriginalInteractionResponse, GetOriginalInteractionResponse, } from '../discord/endpoints.js';
 import { renderedOf } from '../components/instance.js';
 import { InteractionCallbackType, } from '../discord/types/interaction.js';
@@ -9,6 +10,12 @@ import { resolve } from '../components/instance.js';
 import { translatorOf } from '../messages/translate.js';
 /** Only the framework reads how far an interaction was answered. */
 export let isUpdating;
+/**
+ * Resolves once every answer asked so far was sent (or refused): what the
+ * framework waits for before saying a function never answered, since an
+ * answer asked without `await` is still on its way when it returns.
+ */
+export let answersSent;
 /** Answers with a change of the message: see `ComponentInteraction.update()`. */
 let updateMessage;
 let deferUpdateMessage;
@@ -33,6 +40,14 @@ export class Interaction extends IdStructure {
     #queue = Promise.resolve();
     static {
         isUpdating = interaction => interaction.#state === 'updating';
+        answersSent = async (interaction) => {
+            // Answers asked while waiting are queued after the ones before.
+            let last = null;
+            while (last !== interaction.#queue) {
+                last = interaction.#queue;
+                await last;
+            }
+        };
         updateMessage = (interaction, message) => {
             const { body, files } = buildMessage(message, {
                 edit: true,
@@ -151,6 +166,8 @@ export class Interaction extends IdStructure {
      * error keeps the line of user code that asked for the answer.
      */
     async #run(action) {
+        // Where the files asked, for an answer refused later (`callSite`).
+        const site = callSite();
         const previous = this.#queue;
         let release;
         this.#queue = new Promise(resolve => (release = resolve));
@@ -158,6 +175,9 @@ export class Interaction extends IdStructure {
         try {
             return await action();
         }
+        catch (error) {
+            throw fromSite(error, site);
+        }
         finally {
             release();
         }

package/dist/structures/message.d.ts

@@ -10,6 +10,7 @@ import type { Guild } from './guild.js';
 import type { GuildMember } from './member.js';
 import { type Embed, type MessageEditOptions, type MessageInput } from './payload.js';
 import type { User } from './user.js';
+import { type WaitedReaction, type Click, type WaitForClickOptions, type WaitForReactionOptions } from './wait.js';
 /** What the message stores: users are kept as structures, not copies. */
 export type MessageData = Omit<RawMessage, 'author' | 'mentions'> & {
     guild_id?: Snowflake;
@@ -148,6 +149,22 @@ export declare class Message extends IdStructure<MessageData> {
      * @see https://docs.discord.com/developers/resources/channel#start-thread-from-message
      */
     startThread(options: Camelize<StartThreadFromMessageJSONParams>, reason?: string): Promise<ThreadChannel>;
+    /**
+     * Waits for a click on a button or a menu of this message: of a person
+     * (`from`), anyone by default. Resolves with the click, to answer with
+     * `click.interaction`, or `null` when `within` (one minute by default)
+     * passed first. A click taken here does not run the `run` of the button;
+     * a button that is only waited for needs none. A restart of the bot ends
+     * the wait.
+     */
+    waitForClick(options?: WaitForClickOptions): Promise<Click | null>;
+    /**
+     * Waits for a reaction added to this message: of a person (`from`),
+     * anyone's but a bot's by default, with an emoji (`emoji`), any by
+     * default. Resolves with it, or `null` when `within` (one minute by
+     * default) passed first. A restart of the bot ends the wait.
+     */
+    waitForReaction(options?: WaitForReactionOptions): Promise<WaitedReaction | null>;
 }
 /** One mechanism to send a message, used by channels, replies and users. */
 export declare function sendMessage(ctx: Context, channelId: Snowflake, message: MessageInput, guildId?: Snowflake): Promise<Message>;

package/dist/structures/message.js

@@ -6,6 +6,7 @@ import { ctxOf, dataOf, idOf, IdStructure, toDate } from './base.js';
 import { findGuild, knownChannel, knownMember } from './known.js';
 import { buildMessage, } from './payload.js';
 import { translatorOf } from '../messages/translate.js';
+import { personId, readEmoji, readWithin, waitFor, } from './wait.js';
 function emojiPath(emoji) {
     if (typeof emoji !== 'string')
         return reactionEmoji(emoji);
@@ -251,6 +252,38 @@ export class Message extends IdStructure {
         const raw = await rest.request(StartThreadFromMessage, [this.channelId, this.id], { body: toSnakeCase(options), reason });
         return entities.channel(raw);
     }
+    /**
+     * Waits for a click on a button or a menu of this message: of a person
+     * (`from`), anyone by default. Resolves with the click, to answer with
+     * `click.interaction`, or `null` when `within` (one minute by default)
+     * passed first. A click taken here does not run the `run` of the button;
+     * a button that is only waited for needs none. A restart of the bot ends
+     * the wait.
+     */
+    async waitForClick(options = {}) {
+        const within = readWithin(options.within);
+        const from = personId(options.from);
+        const [click] = await waitFor(this, 'click', offered => offered.messageId === this.id && (!from || offered.user.id === from), within);
+        return click ?? null;
+    }
+    /**
+     * Waits for a reaction added to this message: of a person (`from`),
+     * anyone's but a bot's by default, with an emoji (`emoji`), any by
+     * default. Resolves with it, or `null` when `within` (one minute by
+     * default) passed first. A restart of the bot ends the wait.
+     */
+    async waitForReaction(options = {}) {
+        const within = readWithin(options.within);
+        const from = personId(options.from);
+        const isEmoji = readEmoji(options.emoji);
+        const [reaction] = await waitFor(this, 'reaction', offered => offered.messageId === this.id &&
+            (from ? offered.user.id === from : !offered.user.bot) &&
+            isEmoji(offered.emoji), within);
+        if (!reaction)
+            return null;
+        const { messageId: _, ...rest } = reaction;
+        return Object.freeze(rest);
+    }
 }
 /** One mechanism to send a message, used by channels, replies and users. */
 export async function sendMessage(ctx, channelId, message, guildId) {