chapterjs 0.1.2 → 0.2.0

package/dist/cli/preflight.d.ts

@@ -0,0 +1,36 @@
+import { type GatewayIntentName } from '../discord/intents.js';
+import { type RawApplication } from '../discord/types/application.js';
+import type { RawGuild } from '../discord/types/guild.js';
+import type { Rest } from '../rest/rest.js';
+import type { Log } from './log.js';
+export interface PreflightOptions {
+    rest: Rest;
+    log: Log;
+    /** Whether a person is watching: problems are then waited out. */
+    interactive: boolean;
+    /** How often a fix is looked for while waiting, in milliseconds. */
+    pollInterval: number;
+    /** Stops waiting (the user pressed Ctrl+C). */
+    signal: AbortSignal;
+}
+/** A problem that was explained and that stops the command. */
+export declare class PreflightFailure extends Error {
+}
+/** The privileged intents among `intents` that the application lacks. */
+export declare function missingPrivilegedIntents(intents: number, application: Pick<RawApplication, 'flags'>): GatewayIntentName[];
+/**
+ * The link that adds the bot to one server.
+ * @see https://docs.discord.com/developers/topics/oauth2#bot-authorization-flow
+ */
+export declare function inviteUrl(applicationId: string, guildId: string): string;
+/** Checks the token and returns the application of the bot. */
+export declare function fetchApplication(rest: Rest): Promise<RawApplication>;
+/** Makes sure the bot is in the dev server, and returns that server. */
+export declare function ensureInDevGuild(options: PreflightOptions, applicationId: string, guildId: string): Promise<RawGuild>;
+/**
+ * Makes sure the privileged intents the project needs are enabled.
+ * `filesByIntent` says which files need each intent.
+ */
+export declare function ensurePrivilegedIntents(options: PreflightOptions, application: RawApplication, intents: number, filesByIntent: (intent: GatewayIntentName) => string[]): Promise<void>;
+/** The intents a number contains, as the docs name them, for messages. */
+export declare function describeIntents(intents: number): string;

package/dist/cli/preflight.js

@@ -0,0 +1,122 @@
+// What is checked before connecting: each problem is explained with how to
+// fix it, and when a person is there, the CLI waits for the fix instead of
+// making them start it again.
+import { setTimeout as sleep } from 'node:timers/promises';
+import { GetCurrentApplication, GetGuild } from '../discord/endpoints.js';
+import { intentNames, PRIVILEGED_INTENTS, } from '../discord/intents.js';
+import { ApplicationFlags, } from '../discord/types/application.js';
+import { PermissionFlags } from '../discord/types/permissions.js';
+import { DiscordApiError } from '../rest/errors.js';
+/** A problem that was explained and that stops the command. */
+export class PreflightFailure extends Error {
+}
+/**
+ * The flags an application has when a privileged intent is enabled for it:
+ * the plain one once Discord approved it for a verified bot, the "limited"
+ * one for a bot in fewer than 100 servers.
+ * @see https://docs.discord.com/developers/resources/application#application-object-application-flags
+ */
+const INTENT_FLAGS = {
+    GuildPresences: ApplicationFlags.GatewayPresence | ApplicationFlags.GatewayPresenceLimited,
+    GuildMembers: ApplicationFlags.GatewayGuildMembers |
+        ApplicationFlags.GatewayGuildMembersLimited,
+    MessageContent: ApplicationFlags.GatewayMessageContent |
+        ApplicationFlags.GatewayMessageContentLimited,
+};
+/** What the Developer Portal calls each privileged intent. */
+const PORTAL_NAMES = {
+    GuildPresences: 'Presence Intent',
+    GuildMembers: 'Server Members Intent',
+    MessageContent: 'Message Content Intent',
+};
+/** The privileged intents among `intents` that the application lacks. */
+export function missingPrivilegedIntents(intents, application) {
+    const flags = application.flags ?? 0;
+    return intentNames(intents).filter(name => PRIVILEGED_INTENTS.includes(name) && (flags & INTENT_FLAGS[name]) === 0);
+}
+/**
+ * The link that adds the bot to one server.
+ * @see https://docs.discord.com/developers/topics/oauth2#bot-authorization-flow
+ */
+export function inviteUrl(applicationId, guildId) {
+    const query = new URLSearchParams({
+        client_id: applicationId,
+        scope: 'bot applications.commands',
+        // A dev server is a playground: the bot can do everything there.
+        permissions: PermissionFlags.Administrator.toString(),
+        guild_id: guildId,
+        disable_guild_select: 'true',
+    });
+    return `https://discord.com/oauth2/authorize?${query}`;
+}
+/** Checks the token and returns the application of the bot. */
+export function fetchApplication(rest) {
+    return rest.request(GetCurrentApplication, []);
+}
+async function waitFor(options, check) {
+    for (;;) {
+        await sleep(options.pollInterval, undefined, { signal: options.signal });
+        const result = await check();
+        if (result !== null)
+            return result;
+    }
+}
+/** Makes sure the bot is in the dev server, and returns that server. */
+export async function ensureInDevGuild(options, applicationId, guildId) {
+    const fetch = async () => {
+        try {
+            return await options.rest.request(GetGuild, [guildId]);
+        }
+        catch (error) {
+            // 10004 Unknown Guild, 50001 Missing Access: the bot is not in it.
+            if (error instanceof DiscordApiError &&
+                (error.code === 10004 || error.code === 50001)) {
+                return null;
+            }
+            throw error;
+        }
+    };
+    const guild = await fetch();
+    if (guild)
+        return guild;
+    const explanation = `Your bot is not in your dev server yet (DEV_GUILD_ID=${guildId}).\nOpen this link to add it:\n${inviteUrl(applicationId, guildId)}\nIf the link shows another server, DEV_GUILD_ID is not the ID of a server you manage.`;
+    if (!options.interactive) {
+        options.log.error(explanation);
+        throw new PreflightFailure();
+    }
+    options.log.warn(`${explanation}\nWaiting for the bot to be added...`);
+    const joined = await waitFor(options, fetch);
+    options.log.success(`The bot joined ${joined.name}`);
+    return joined;
+}
+/**
+ * Makes sure the privileged intents the project needs are enabled.
+ * `filesByIntent` says which files need each intent.
+ */
+export async function ensurePrivilegedIntents(options, application, intents, filesByIntent) {
+    let missing = missingPrivilegedIntents(intents, application);
+    if (missing.length === 0)
+        return;
+    const list = missing
+        .map(name => `- ${PORTAL_NAMES[name]}, needed by ${filesByIntent(name).join(', ')}`)
+        .join('\n');
+    const explanation = `Your files need ${missing.length === 1 ? 'an option that is' : 'options that are'} not enabled for your bot:\n${list}\nEnable ${missing.length === 1 ? 'it' : 'them'} under "Privileged Gateway Intents", then save:\nhttps://discord.com/developers/applications/${application.id}/bot`;
+    if (!options.interactive) {
+        options.log.error(explanation);
+        throw new PreflightFailure();
+    }
+    options.log.warn(`${explanation}\nWaiting for you to enable ${missing.length === 1 ? 'it' : 'them'}...`);
+    await waitFor(options, async () => {
+        missing = missingPrivilegedIntents(intents, await fetchApplication(options.rest));
+        return missing.length === 0 ? true : null;
+    });
+    options.log.success('Privileged intents enabled');
+}
+/** The intents a number contains, as the docs name them, for messages. */
+export function describeIntents(intents) {
+    return intentNames(intents)
+        .map(name => name
+        .replace(/[A-Z]/g, (letter, index) => index === 0 ? letter : `_${letter}`)
+        .toUpperCase())
+        .join(', ');
+}

package/dist/cli/project.d.ts

@@ -0,0 +1,135 @@
+import { type CommandEntry } from '../commands/tree.js';
+import { type ComponentEntry } from '../components/router.js';
+import { type LoadedPresence } from '../presence/declaration.js';
+import { type DeclaredCommand, type DeclaredLanguage } from '../messages/declaration.js';
+import { type LoadedMessages } from '../messages/translate.js';
+import type { Locale } from '../discord/types/common.js';
+import { type TaskEntry } from '../tasks/scheduler.js';
+import { type Bot, type BotOptions } from '../core/bot.js';
+import { type GatewayIntentName } from '../discord/intents.js';
+import { type LoadedEvent } from '../events/router.js';
+import { type BuiltFile, type Declaration, type FailedFile } from '../loader/loader.js';
+import type { Log } from './log.js';
+export interface ProjectOptions {
+    /** The folder of the project. */
+    cwd: string;
+    /** The version of the framework. */
+    version: string;
+    log: Log;
+    /**
+     * The files of the project as `chapterjs build` kept them. Without it,
+     * they are read from the `src` folder.
+     */
+    built?: readonly BuiltFile[];
+    /**
+     * Whether the files join voice channels, as `chapterjs build` found.
+     * Without it, the files of `src` are read on every load.
+     */
+    joinsVoice?: boolean;
+    /** Only tests change this. */
+    deferAfter?: number;
+}
+/** What the types of a project are written from, once its files ran. */
+export interface TypesInfo {
+    /** Every language declared, with where. */
+    languages: readonly DeclaredLanguage[];
+    /** The language `t` is typed from, when known. */
+    defaultLocale?: Locale;
+    /** The languages that say `default: true`, as they are now. */
+    languageDefaults: readonly Locale[];
+    /** Every command, and whether its file describes it. */
+    commands: readonly DeclaredCommand[];
+}
+/**
+ * Writes the types of a project (`.chapterjs/`): what the project adds to
+ * 'chapterjs', like the files of `public/`, its languages and its
+ * commands. With the project as it loaded (`info`), a language only
+ * offers the commands without `description`, `t` is typed from the
+ * default language and `default: true` is refused in every language that
+ * says it when another one does; without it (`sync`, which runs nothing),
+ * the commands and the languages are found by reading the files, every
+ * command is offered, and the first language or the one that says
+ * `default: true` types `t`.
+ * @returns how many files were written
+ */
+export declare function writeTypes(cwd: string, info?: TypesInfo): Promise<number>;
+/** The kinds of declarations a project is made of: one per feature. */
+export declare const DECLARATIONS: readonly Declaration<unknown>[];
+/** What a bot of the project is connected with. */
+export interface ConnectOptions {
+    token: string;
+    /** Another REST API than Discord's: only tests use it. */
+    apiUrl?: string | undefined;
+    guildFilter?: BotOptions['guildFilter'];
+    /** Whether what happens outside servers is for this bot. */
+    privateEvents?: boolean;
+    shards?: BotOptions['shards'];
+    identifyGate?: BotOptions['identifyGate'];
+    /** The share of the requests per second this process may send. */
+    globalLimit?: number | undefined;
+    /** Only tests change this. */
+    identifyInterval?: number | undefined;
+    /** Discord refused the bot for good. */
+    onFatal: (bot: Bot) => void;
+}
+/** The files of a project, and what runs them. */
+export interface Project {
+    /**
+     * The last version of each declaration that loaded, by the file and the
+     * export it comes from (`src/ping.ts#default`): what the bot runs.
+     */
+    readonly events: ReadonlyMap<string, LoadedEvent>;
+    readonly commands: ReadonlyMap<string, CommandEntry>;
+    readonly components: ReadonlyMap<string, ComponentEntry>;
+    readonly tasks: ReadonlyMap<string, TaskEntry>;
+    /** The presence declared, or `null` without one. */
+    readonly presence: LoadedPresence | null;
+    /** The languages of the project, assembled, or `null` without any. */
+    readonly messages: LoadedMessages | null;
+    /** What the types of the project are written from, as it loaded. */
+    typesInfo(): TypesInfo;
+    /**
+     * Loads every file (again). A declaration that fails is returned; it
+     * keeps its last working version when it had one.
+     */
+    load(): Promise<FailedFile[]>;
+    /** Shows a failure with its file (and export) and line. */
+    report(failure: FailedFile): void;
+    /** "2 commands, 3 events, 4 components, a presence loaded". */
+    summary(): string;
+    isEmpty(): boolean;
+    /** The files that make an intent necessary. */
+    filesNeeding(intent: GatewayIntentName): string[];
+    /**
+     * The intents the files need right now. Without `privateEvents`, what
+     * only serves private messages is left out: nothing is asked to Discord
+     * for what the bot will not listen to.
+     */
+    intents(privateEvents?: boolean): number;
+    /** Creates a bot that runs the files, and connects it. */
+    connect(options: ConnectOptions): Promise<Bot>;
+    /** Runs the files of the `ready` event: the bot knows its servers. */
+    ready(bot: Bot): void;
+    /**
+     * Gives the bot the presence of the project as it is now (Discord's
+     * default without a presence file). Nothing is sent when it did not
+     * change since the bot was given one.
+     */
+    applyPresence(bot: Bot): boolean;
+    /**
+     * Starts the tasks of the project, with the bot `current` returns (none
+     * while it reconnects). Only one process of a bot runs them.
+     */
+    startTasks(current: () => Bot | null): void;
+    /** Stops the tasks: nothing runs after this. */
+    stopTasks(): void;
+    /** Looks after the memory of the bot `current` returns. */
+    watchMemory(current: () => Bot | null): {
+        stop(): void;
+    };
+}
+/** Whether the folder is a project: it has a `src` folder. */
+export declare function hasSources(cwd: string, log: Log): Promise<boolean>;
+export declare function createProject(options: ProjectOptions): Project;
+/** Says what went wrong in words the developer can act on. */
+export declare function explain(error: unknown, log: Log): void;