chapterjs 0.1.2 → 0.1.4

package/dist/structures/interaction.js

@@ -0,0 +1,396 @@
+import { CreateFollowupMessage, CreateInteractionResponse, DeleteOriginalInteractionResponse, EditOriginalInteractionResponse, GetOriginalInteractionResponse, } from '../discord/endpoints.js';
+import { renderedOf } from '../components/instance.js';
+import { InteractionCallbackType, } from '../discord/types/interaction.js';
+import { MessageFlags } from '../discord/types/message.js';
+import { ctxOf, dataOf, IdStructure } from './base.js';
+import { findGuild, knownChannel, knownMember } from './known.js';
+import { buildMessage, } from './payload.js';
+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;
+/** Answers with a change of the message: see `ComponentInteraction.update()`. */
+let updateMessage;
+let deferUpdateMessage;
+let openModal;
+/**
+ * Someone used something of the bot (a command...) and waits for an answer.
+ * Discord wants a first answer within 3 seconds, and accepts edits and
+ * other messages for 15 minutes.
+ * @see https://docs.discord.com/developers/interactions/receiving-and-responding
+ */
+export class Interaction extends IdStructure {
+    /** Who did it. */
+    user;
+    #ephemeral;
+    /**
+     * `deferred`: "thinking…" is shown, the answer is a new message.
+     * `updating`: the answer is a change of the message of the component,
+     * nothing is shown meanwhile.
+     */
+    #state = 'waiting';
+    /** Answers are sent one after the other, in the order they were asked. */
+    #queue = Promise.resolve();
+    static {
+        isUpdating = interaction => interaction.#state === 'updating';
+        updateMessage = (interaction, message) => {
+            const { body, files } = buildMessage(message, {
+                edit: true,
+                t: interaction.#t(interaction.#ephemeral),
+            });
+            return interaction.#run(async () => {
+                const { rest, entities } = ctxOf(interaction);
+                const { id, token, application_id: applicationId, } = dataOf(interaction);
+                if (interaction.#state === 'answered' ||
+                    interaction.#state === 'deferred') {
+                    throw new Error('This interaction was already answered: the message can no longer be changed through it. Use interaction.message.edit() to change the message, or interaction.followUp() to send another one.');
+                }
+                if (interaction.#state === 'updating') {
+                    const raw = await rest.request(EditOriginalInteractionResponse, [applicationId, token], { body, files, auth: false });
+                    interaction.#state = 'answered';
+                    return entities.message(raw, interaction.guildId ?? undefined);
+                }
+                const response = await rest.request(CreateInteractionResponse, [id, token], {
+                    body: { type: InteractionCallbackType.UpdateMessage, data: body },
+                    query: { with_response: true },
+                    files,
+                    auth: false,
+                });
+                interaction.#state = 'answered';
+                const raw = response?.resource?.message ??
+                    (await rest.request(GetOriginalInteractionResponse, [applicationId, token], { auth: false }));
+                return entities.message(raw, interaction.guildId ?? undefined);
+            });
+        };
+        deferUpdateMessage = interaction => interaction.#run(async () => {
+            if (interaction.#state !== 'waiting')
+                return;
+            const { id, token } = dataOf(interaction);
+            await ctxOf(interaction).rest.request(CreateInteractionResponse, [id, token], {
+                body: { type: InteractionCallbackType.DeferredUpdateMessage },
+                auth: false,
+            });
+            interaction.#state = 'updating';
+        });
+        openModal = (interaction, form) => {
+            const rendered = renderedOf(form, 'The form given to showModal()');
+            if (rendered.kind !== 'modal') {
+                throw new TypeError(`showModal() opens a form of src/components/modals/, got a ${rendered.kind}.`);
+            }
+            return interaction.#run(async () => {
+                if (interaction.#state !== 'waiting') {
+                    throw new Error('A form can only be the first answer to an interaction: call interaction.showModal() before reply() or defer(), and the framework waits for it.');
+                }
+                const { id, token } = dataOf(interaction);
+                await ctxOf(interaction).rest.request(CreateInteractionResponse, [id, token], {
+                    body: {
+                        type: InteractionCallbackType.Modal,
+                        // A form is seen by the person alone: in their language.
+                        data: resolve(rendered, translatorOf(ctxOf(interaction), {
+                            person: interaction.locale,
+                            ephemeral: true,
+                        })).raw,
+                    },
+                    auth: false,
+                });
+                interaction.#state = 'answered';
+            });
+        };
+    }
+    constructor(ctx, data, user, { ephemeral = false } = {}) {
+        super(ctx, data);
+        this.user = user;
+        this.#ephemeral = ephemeral;
+    }
+    /** The id of the server; `null` in a private message. */
+    get guildId() {
+        return dataOf(this).guild_id ?? null;
+    }
+    /** The id of the channel it happened in. */
+    get channelId() {
+        return dataOf(this).channel_id ?? this.channel.id;
+    }
+    /** The server it happened in; `null` in a private message. */
+    get guild() {
+        return findGuild(this, this.guildId);
+    }
+    /** The channel it happened in: Discord sends it with the interaction. */
+    get channel() {
+        const id = dataOf(this).channel_id;
+        const channel = (id ? ctxOf(this).cache.channels.get(id) : undefined) ??
+            knownChannel(this);
+        if (!channel?.isTextBased()) {
+            throw new Error('This interaction came without its channel.');
+        }
+        return channel;
+    }
+    /** Who did it, as a member of the server; `null` in a private message. */
+    get member() {
+        return this.guild?.members.get(this.user.id) ?? knownMember(this) ?? null;
+    }
+    /** The language of the person: use it to answer in their language. */
+    get locale() {
+        // Discord sends it with everything a person does (all but pings).
+        return dataOf(this).locale;
+    }
+    /** Whether an answer was sent, or promised with `defer()`. */
+    get answered() {
+        return this.#state !== 'waiting';
+    }
+    /** Whether `defer()` was called and the answer is still to come. */
+    get deferred() {
+        return this.#state === 'deferred' || this.#state === 'updating';
+    }
+    /** The data of the interaction, without its token: a token is a secret. */
+    toJSON() {
+        const { token: _token, ...data } = super.toJSON();
+        return data;
+    }
+    /**
+     * Runs one answer after the previous ones. Written with `await` so that an
+     * error keeps the line of user code that asked for the answer.
+     */
+    async #run(action) {
+        const previous = this.#queue;
+        let release;
+        this.#queue = new Promise(resolve => (release = resolve));
+        await previous;
+        try {
+            return await action();
+        }
+        finally {
+            release();
+        }
+    }
+    /** `t` for an answer: the person when they alone see it, else the server. */
+    #t(ephemeral) {
+        return translatorOf(ctxOf(this), {
+            person: this.locale,
+            guild: this.guild,
+            ephemeral: ephemeral ?? this.#ephemeral,
+        });
+    }
+    #flags(ephemeral, flags = 0) {
+        return (ephemeral ?? this.#ephemeral)
+            ? flags | MessageFlags.Ephemeral
+            : flags;
+    }
+    /**
+     * Answers. If `defer()` was called (by you, or by the framework because
+     * the answer was taking long), this completes the pending answer.
+     * @see https://docs.discord.com/developers/interactions/receiving-and-responding#create-interaction-response
+     */
+    reply(message) {
+        const options = typeof message === 'string' ? { content: message } : message;
+        const { body, files } = buildMessage(options, {
+            t: this.#t(options.ephemeral),
+        });
+        return this.#run(async () => {
+            const { rest, entities } = ctxOf(this);
+            const { id, token, application_id: applicationId } = dataOf(this);
+            if (this.#state === 'answered') {
+                throw new Error('This interaction was already answered. Use interaction.followUp() to send another message, or interaction.edit() to change the answer.');
+            }
+            if (this.#state === 'updating') {
+                // The pending answer is a change of the message of the component:
+                // a new message is a follow-up, which looks the same to the person.
+                const raw = await rest.request(CreateFollowupMessage, [applicationId, token], {
+                    body: {
+                        ...body,
+                        flags: this.#flags(options.ephemeral, body.flags),
+                    },
+                    files,
+                    auth: false,
+                });
+                this.#state = 'answered';
+                return entities.message(raw, this.guildId ?? undefined);
+            }
+            if (this.#state === 'deferred') {
+                // Whether the answer is ephemeral was decided when deferring.
+                const raw = await rest.request(EditOriginalInteractionResponse, [applicationId, token], { body, files, auth: false });
+                this.#state = 'answered';
+                return entities.message(raw, this.guildId ?? undefined);
+            }
+            const response = await rest.request(CreateInteractionResponse, [id, token], {
+                body: {
+                    type: InteractionCallbackType.ChannelMessageWithSource,
+                    data: {
+                        ...body,
+                        flags: this.#flags(options.ephemeral, body.flags),
+                    },
+                },
+                query: { with_response: true },
+                files,
+                auth: false,
+            });
+            this.#state = 'answered';
+            const raw = response?.resource?.message ??
+                (await rest.request(GetOriginalInteractionResponse, [applicationId, token], { auth: false }));
+            return entities.message(raw, this.guildId ?? undefined);
+        });
+    }
+    /**
+     * Tells Discord the answer is coming: the person sees "thinking…" and
+     * `reply()` can then take up to 15 minutes. The framework does it by
+     * itself when an answer takes long; call it yourself to choose when.
+     */
+    defer({ ephemeral } = {}) {
+        return this.#run(async () => {
+            if (this.#state !== 'waiting')
+                return;
+            const { id, token } = dataOf(this);
+            await ctxOf(this).rest.request(CreateInteractionResponse, [id, token], {
+                body: {
+                    type: InteractionCallbackType.DeferredChannelMessageWithSource,
+                    data: { flags: this.#flags(ephemeral) },
+                },
+                auth: false,
+            });
+            this.#state = 'deferred';
+        });
+    }
+    /**
+     * Changes the answer.
+     * @see https://docs.discord.com/developers/interactions/receiving-and-responding#edit-original-interaction-response
+     */
+    edit(message) {
+        const { body, files } = buildMessage(message, {
+            edit: true,
+            t: this.#t(undefined),
+        });
+        return this.#run(async () => {
+            if (this.#state === 'waiting') {
+                throw new Error('There is no answer to edit yet: call interaction.reply() first.');
+            }
+            const { rest, entities } = ctxOf(this);
+            const { token, application_id: applicationId } = dataOf(this);
+            const raw = await rest.request(EditOriginalInteractionResponse, [applicationId, token], { body, files, auth: false });
+            this.#state = 'answered';
+            return entities.message(raw, this.guildId ?? undefined);
+        });
+    }
+    /**
+     * Sends another message, after the answer.
+     * @see https://docs.discord.com/developers/interactions/receiving-and-responding#create-followup-message
+     */
+    followUp(message) {
+        const options = typeof message === 'string' ? { content: message } : message;
+        const { body, files } = buildMessage(options, {
+            t: this.#t(options.ephemeral),
+        });
+        return this.#run(async () => {
+            if (this.#state === 'waiting') {
+                throw new Error('A follow-up comes after an answer: call interaction.reply() first.');
+            }
+            const { rest, entities } = ctxOf(this);
+            const { token, application_id: applicationId } = dataOf(this);
+            const raw = await rest.request(CreateFollowupMessage, [applicationId, token], {
+                body: { ...body, flags: this.#flags(options.ephemeral, body.flags) },
+                files,
+                auth: false,
+            });
+            return entities.message(raw, this.guildId ?? undefined);
+        });
+    }
+    /**
+     * Deletes the answer.
+     * @see https://docs.discord.com/developers/interactions/receiving-and-responding#delete-original-interaction-response
+     */
+    delete() {
+        return this.#run(async () => {
+            const { token, application_id: applicationId } = dataOf(this);
+            await ctxOf(this).rest.request(DeleteOriginalInteractionResponse, [applicationId, token], { auth: false });
+        });
+    }
+}
+/** Someone used a slash command. */
+export class CommandInteraction extends Interaction {
+    /** The command as the person typed it: `/mod ban`. */
+    commandName;
+    constructor(ctx, data, user, options) {
+        super(ctx, data, user, options);
+        this.commandName = options.commandName;
+    }
+    /**
+     * Opens a form, as the answer: `showModal(report({ userId }))`, with a
+     * form of `src/components/modals/`. It must be the first answer, and the
+     * person has as long as they want to fill it in.
+     * @see https://docs.discord.com/developers/interactions/receiving-and-responding#interaction-response-object-modal
+     */
+    showModal(form) {
+        return openModal(this, form);
+    }
+}
+/**
+ * Someone clicked a button or picked something in a select menu of a
+ * message of the bot. It can answer like a command, or change the message
+ * the component is on.
+ * @see https://docs.discord.com/developers/interactions/receiving-and-responding#interaction-object-message-component-data-structure
+ */
+export class ComponentInteraction extends Interaction {
+    /** The message the component is on. */
+    message;
+    constructor(ctx, data, user, options) {
+        super(ctx, data, user, options);
+        this.message = options.message;
+    }
+    /**
+     * Changes the message the component is on, as the answer: its text, its
+     * embeds, its components, its files. Only what you pass changes;
+     * `components: []` removes the buttons and menus.
+     * @see https://docs.discord.com/developers/interactions/receiving-and-responding#interaction-response-object-interaction-callback-type
+     */
+    update(message) {
+        return updateMessage(this, message);
+    }
+    /**
+     * Tells Discord the message will change later: the person sees nothing
+     * meanwhile, and `update()` can then take up to 15 minutes. The
+     * framework does it by itself when an answer takes long.
+     */
+    deferUpdate() {
+        return deferUpdateMessage(this);
+    }
+    /**
+     * Opens a form, as the answer: `showModal(report({ userId }))`, with a
+     * form of `src/components/modals/`. It must be the first answer.
+     * @see https://docs.discord.com/developers/interactions/receiving-and-responding#interaction-response-object-modal
+     */
+    showModal(form) {
+        return openModal(this, form);
+    }
+}
+/**
+ * Someone sent a form of the bot. It can answer like a command; when a
+ * button or a menu opened the form, it can also change their message.
+ * @see https://docs.discord.com/developers/interactions/receiving-and-responding#interaction-object-modal-submit-data-structure
+ */
+export class ModalInteraction extends Interaction {
+    /** The message whose button or menu opened the form; `null` when a command did. */
+    message;
+    constructor(ctx, data, user, options) {
+        super(ctx, data, user, options);
+        this.message = options.message;
+    }
+    /**
+     * Changes the message whose button or menu opened the form, as the
+     * answer. Only what you pass changes.
+     * @see https://docs.discord.com/developers/interactions/receiving-and-responding#interaction-response-object-interaction-callback-type
+     */
+    update(message) {
+        if (!this.message) {
+            return Promise.reject(new Error('This form was opened by a command, not by a button or a menu: there is no message to change. Use interaction.reply().'));
+        }
+        return updateMessage(this, message);
+    }
+    /**
+     * Tells Discord the message that opened the form will change later: the
+     * person sees nothing meanwhile.
+     */
+    deferUpdate() {
+        if (!this.message) {
+            return Promise.reject(new Error('This form was opened by a command, not by a button or a menu: there is no message to change. Use interaction.defer().'));
+        }
+        return deferUpdateMessage(this);
+    }
+}

package/dist/structures/invite.d.ts

@@ -0,0 +1,38 @@
+import type { Snowflake } from '../discord/types/common.js';
+import type { RawInvite, RawInviteMetadata } from '../discord/types/invite.js';
+import { Structure } from './base.js';
+import type { Context } from './context.js';
+import type { User } from './user.js';
+export type InviteData = Omit<RawInvite, 'inviter'> & Partial<RawInviteMetadata>;
+/**
+ * An invite to a server.
+ * @see https://docs.discord.com/developers/resources/invite#invite-object
+ */
+export declare class Invite extends Structure<InviteData> {
+    /** Who created the invite, when Discord says it. */
+    readonly inviter: User | null;
+    constructor(ctx: Context, data: InviteData, inviter: User | null);
+    /** The unique code of the invite (`discord.gg/code`). */
+    get code(): string;
+    /** The link to share. */
+    get url(): string;
+    /** The id of the server the invite leads to. */
+    get guildId(): Snowflake | null;
+    /** The id of the channel the invite leads to. */
+    get channelId(): Snowflake | null;
+    /** When the invite stops working; `null` when it never does. */
+    get expiresAt(): Date | null;
+    /** How many times the invite was used, when Discord says it. */
+    get uses(): number | null;
+    /** How many times the invite can be used; `0` means no limit. */
+    get maxUses(): number | null;
+    /** Whether members who joined with it are kicked when they go offline. */
+    get temporary(): boolean;
+    /**
+     * Deletes the invite: its link stops working.
+     * @see https://docs.discord.com/developers/resources/invite#delete-invite
+     */
+    delete(reason?: string): Promise<void>;
+    /** The link to share. */
+    toString(): string;
+}

package/dist/structures/invite.js

@@ -0,0 +1,57 @@
+import { DeleteInvite } from '../discord/endpoints.js';
+import { ctxOf, dataOf, Structure, toDate } from './base.js';
+/**
+ * An invite to a server.
+ * @see https://docs.discord.com/developers/resources/invite#invite-object
+ */
+export class Invite extends Structure {
+    /** Who created the invite, when Discord says it. */
+    inviter;
+    constructor(ctx, data, inviter) {
+        super(ctx, data);
+        this.inviter = inviter;
+    }
+    /** The unique code of the invite (`discord.gg/code`). */
+    get code() {
+        return dataOf(this).code;
+    }
+    /** The link to share. */
+    get url() {
+        return `https://discord.gg/${this.code}`;
+    }
+    /** The id of the server the invite leads to. */
+    get guildId() {
+        return dataOf(this).guild?.id ?? null;
+    }
+    /** The id of the channel the invite leads to. */
+    get channelId() {
+        return dataOf(this).channel?.id ?? null;
+    }
+    /** When the invite stops working; `null` when it never does. */
+    get expiresAt() {
+        return toDate(dataOf(this).expires_at);
+    }
+    /** How many times the invite was used, when Discord says it. */
+    get uses() {
+        return dataOf(this).uses ?? null;
+    }
+    /** How many times the invite can be used; `0` means no limit. */
+    get maxUses() {
+        return dataOf(this).max_uses ?? null;
+    }
+    /** Whether members who joined with it are kicked when they go offline. */
+    get temporary() {
+        return dataOf(this).temporary ?? false;
+    }
+    /**
+     * Deletes the invite: its link stops working.
+     * @see https://docs.discord.com/developers/resources/invite#delete-invite
+     */
+    async delete(reason) {
+        await ctxOf(this).rest.request(DeleteInvite, [this.code], { reason });
+    }
+    /** The link to share. */
+    toString() {
+        return this.url;
+    }
+}

package/dist/structures/known.d.ts

@@ -0,0 +1,28 @@
+import type { Snowflake } from '../discord/types/common.js';
+import { Structure } from './base.js';
+import type { Channel } from './channel.js';
+import type { Guild } from './guild.js';
+import type { GuildMember } from './member.js';
+interface Known {
+    guild?: Guild | undefined;
+    member?: GuildMember | undefined;
+    channel?: Channel | undefined;
+}
+/** The server a structure came with. */
+export declare function knownGuild(structure: Structure<object>): Guild | undefined;
+/** The member a structure came with (the author, who used a command). */
+export declare function knownMember(structure: Structure<object>): GuildMember | undefined;
+/** The channel a structure came with. */
+export declare function knownChannel(structure: Structure<object>): Channel | undefined;
+/** Keeps what a structure comes with; what is not given is left as it was. */
+export declare function remember(structure: Structure<object>, seen: Known): void;
+/** The server of something that may have one. */
+export declare function findGuild(structure: Structure<object>, guildId: Snowflake | null | undefined): Guild | null;
+/**
+ * The server of something that belongs to one (a member, a role, a channel
+ * of a server): it is always there. Such a thing only reaches user code
+ * from a server the bot is in; anything else is refused loudly rather than
+ * answered with a `null` nobody expects.
+ */
+export declare function guildOf(structure: Structure<object>, guildId: Snowflake): Guild;
+export {};

package/dist/structures/known.js

@@ -0,0 +1,58 @@
+// What a structure was created with. A property like `member.guild` or
+// `message.channel` reads the cache, so it would turn to nothing the moment
+// the cache forgets (the bot is removed from the server, the member leaves,
+// the session starts over) while code still holds the structure. What the
+// structure came with is kept, so that what was there stays there: the
+// cache first, then this.
+//
+// It costs one reference per structure and no allocation for what belongs
+// to a server (members, roles, channels: there can be millions), which keep
+// their server itself. Only what comes with more (a message, an interaction:
+// few, and short-lived) keeps a small object.
+import { ctxOf, originOf, setOrigin, Structure } from './base.js';
+/** A server kept as such is a structure; anything else is a `Known`. */
+const isGuild = (origin) => origin instanceof Structure;
+/** The server a structure came with. */
+export function knownGuild(structure) {
+    const origin = originOf(structure);
+    if (!origin)
+        return undefined;
+    return isGuild(origin) ? origin : origin.guild;
+}
+/** The member a structure came with (the author, who used a command). */
+export function knownMember(structure) {
+    const origin = originOf(structure);
+    return origin && !isGuild(origin) ? origin.member : undefined;
+}
+/** The channel a structure came with. */
+export function knownChannel(structure) {
+    const origin = originOf(structure);
+    return origin && !isGuild(origin) ? origin.channel : undefined;
+}
+/** Keeps what a structure comes with; what is not given is left as it was. */
+export function remember(structure, seen) {
+    const guild = seen.guild ?? knownGuild(structure);
+    const member = seen.member ?? knownMember(structure);
+    const channel = seen.channel ?? knownChannel(structure);
+    // Only a server: the server itself, nothing allocated.
+    setOrigin(structure, member || channel ? { guild, member, channel } : guild);
+}
+/** The server of something that may have one. */
+export function findGuild(structure, guildId) {
+    if (!guildId)
+        return null;
+    return (ctxOf(structure).cache.guilds.get(guildId) ?? knownGuild(structure) ?? null);
+}
+/**
+ * The server of something that belongs to one (a member, a role, a channel
+ * of a server): it is always there. Such a thing only reaches user code
+ * from a server the bot is in; anything else is refused loudly rather than
+ * answered with a `null` nobody expects.
+ */
+export function guildOf(structure, guildId) {
+    const guild = findGuild(structure, guildId);
+    if (!guild) {
+        throw new Error(`The server ${guildId} is not one the bot is in, so what belongs to it can't be read.`);
+    }
+    return guild;
+}