chapterjs 0.1.1 → 0.1.4

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,122 @@
+import { type CommandEntry } from '../commands/tree.js';
+import { type ComponentEntry } from '../components/router.js';
+import { type LoadedPresence } from '../presence/convention.js';
+import { type LoadedMessages } from '../messages/translate.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 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;
+}
+/**
+ * Writes the types of a project (`.chapterjs/`): one project per typed
+ * folder (every event, every language file), and what every file gets,
+ * like the files of `public/`. With the commands and the languages as
+ * they loaded, a language file only offers the ones without `description`
+ * in their file, `t` is typed from the default language and `default:
+ * true` is refused in every file when another one says it (`defaults`,
+ * the files that do); without them (`sync`, which runs nothing),
+ * every command is offered and the first language file types `t`.
+ * @returns how many files were written
+ */
+export declare function writeTypes(cwd: string, commands?: ReadonlyMap<string, CommandEntry>, messages?: LoadedMessages | null, defaults?: readonly string[]): Promise<number>;
+/** The conventional folders of a project: one per feature. */
+export declare const CONVENTIONS: readonly [import("../loader/loader.js").Convention<import("../events/convention.js").EventHandler<keyof import("../events/registry.js").EventContexts>>, import("../loader/loader.js").Convention<import("../commands/convention.js").LoadedCommand>, import("../loader/loader.js").Convention<import("../components/convention.js").LoadedComponent>, import("../loader/loader.js").Convention<import("../tasks/convention.js").LoadedTask>, import("../loader/loader.js").Convention<LoadedPresence>, import("../loader/loader.js").Convention<import("../messages/convention.js").LoadedLanguage>];
+/** 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 file that loaded: what the bot runs. */
+    readonly events: ReadonlyMap<string, LoadedEvent>;
+    readonly commands: ReadonlyMap<string, CommandEntry>;
+    readonly components: ReadonlyMap<string, ComponentEntry>;
+    readonly tasks: ReadonlyMap<string, TaskEntry>;
+    /** What `src/presence.ts` declares, or `null` without that file. */
+    readonly presence: LoadedPresence | null;
+    /** The languages of `src/messages/`, assembled, or `null` without any. */
+    readonly messages: LoadedMessages | null;
+    /**
+     * The language files that say `default: true`, as they are now: a file
+     * left out because a second one says it is counted, so that both are
+     * underlined in the editor.
+     */
+    readonly languageDefaults: readonly string[];
+    /**
+     * Loads every file (again). A file that fails is returned; it keeps its
+     * last working version when it had one.
+     */
+    load(): Promise<FailedFile[]>;
+    /** Shows a failure with its file 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;