chapterjs 0.1.2 → 0.1.4

package/dist/structures/role.js

@@ -0,0 +1,112 @@
+import { cdn } from '../discord/cdn.js';
+import { DeleteGuildRole, ModifyGuildRole } from '../discord/endpoints.js';
+import { roleMention } from '../discord/formatting.js';
+import { Permissions } from '../discord/permissions.js';
+import { toSnakeCase } from '../util/case.js';
+import { ctxOf, dataOf, IdStructure } from './base.js';
+import { guildOf } from './known.js';
+/**
+ * A role of a server.
+ * @see https://docs.discord.com/developers/topics/permissions#role-object
+ */
+export class Role extends IdStructure {
+    /** The id of the server of the role. */
+    guildId;
+    constructor(ctx, data, guildId) {
+        super(ctx, data);
+        this.guildId = guildId;
+    }
+    /** The server of the role. */
+    get guild() {
+        return guildOf(this, this.guildId);
+    }
+    /** The name of the role. */
+    get name() {
+        return dataOf(this).name;
+    }
+    /** The color as a number (`0xff0000`); `0` means no color. */
+    get color() {
+        return dataOf(this).colors?.primary_color ?? dataOf(this).color;
+    }
+    /** Whether members with this role are shown apart in the member list. */
+    get hoist() {
+        return dataOf(this).hoist;
+    }
+    /** Where the role is in the hierarchy: the higher, the more powerful. */
+    get position() {
+        return dataOf(this).position;
+    }
+    /** What the role allows in the server. */
+    get permissions() {
+        return new Permissions(dataOf(this).permissions);
+    }
+    /** Whether the role belongs to an integration (a bot, boosters...). */
+    get managed() {
+        return dataOf(this).managed;
+    }
+    /** Whether everyone can mention the role. */
+    get mentionable() {
+        return dataOf(this).mentionable;
+    }
+    /** The standard emoji shown next to the role, when it has one. */
+    get unicodeEmoji() {
+        return dataOf(this).unicode_emoji ?? null;
+    }
+    /** Whether this is the @everyone role, which every member has. */
+    get isEveryone() {
+        return this.id === this.guildId;
+    }
+    /** The members that have this role, among the ones the bot knows. */
+    get members() {
+        const guild = this.guild;
+        if (!guild)
+            return [];
+        return [...guild.members.values()].filter(member => member.roleIds.includes(this.id));
+    }
+    /** The URL of the icon of the role, when it has one. */
+    iconURL(options) {
+        const icon = dataOf(this).icon;
+        return icon ? cdn.roleIcon(this.id, icon, options) : null;
+    }
+    /**
+     * Whether this role is above another one in the hierarchy. With the same
+     * position, the oldest role is above.
+     * @see https://docs.discord.com/developers/topics/permissions#permission-hierarchy
+     */
+    isHigherThan(other) {
+        if (this.position !== other.position) {
+            return this.position > other.position;
+        }
+        return BigInt(this.id) < BigInt(other.id);
+    }
+    /**
+     * Changes the role.
+     * @see https://docs.discord.com/developers/resources/guild#modify-guild-role
+     */
+    async edit(options, reason) {
+        const { rest, entities } = ctxOf(this);
+        const { permissions, ...rest_ } = options;
+        const body = toSnakeCase(rest_);
+        if (permissions !== undefined) {
+            body.permissions = new Permissions(permissions).toString();
+        }
+        const raw = await rest.request(ModifyGuildRole, [this.guildId, this.id], {
+            body,
+            reason,
+        });
+        return entities.role(this.guildId, raw);
+    }
+    /**
+     * Deletes the role.
+     * @see https://docs.discord.com/developers/resources/guild#delete-guild-role
+     */
+    async delete(reason) {
+        await ctxOf(this).rest.request(DeleteGuildRole, [this.guildId, this.id], {
+            reason,
+        });
+    }
+    /** `<@&id>`: mentions the role when put in a message. */
+    toString() {
+        return this.isEveryone ? '@everyone' : roleMention(this.id);
+    }
+}

package/dist/structures/user.d.ts

@@ -0,0 +1,59 @@
+import { type ImageOptions } from '../discord/cdn.js';
+import type { Locale } from '../discord/types/common.js';
+import type { RawPresenceUpdateEvent } from '../discord/types/gateway-events.js';
+import { UserFlags, type RawUser } from '../discord/types/user.js';
+import type { Camelize } from '../util/case.js';
+import { IdStructure } from './base.js';
+import type { DMChannel } from './channel.js';
+import type { Message } from './message.js';
+import type { MessageInput } from './payload.js';
+export type UserFlagName = keyof typeof UserFlags;
+/**
+ * Whether someone is online and what they are doing: their status, their
+ * activities, and on which devices.
+ * @see https://docs.discord.com/developers/events/gateway-events#presence-update-presence-update-event-fields
+ */
+export type UserPresence = Camelize<Omit<RawPresenceUpdateEvent, 'user' | 'guild_id'>>;
+/**
+ * A Discord account, the same in every server.
+ * @see https://docs.discord.com/developers/resources/user#user-object
+ */
+export declare class User extends IdStructure<RawUser> {
+    /** The unique name of the account (`@name`). */
+    get username(): string;
+    /** The name shown in Discord, when the user chose one. */
+    get globalName(): string | null;
+    /** The name to show: the display name, or else the username. */
+    get displayName(): string;
+    /** `"0"` for users on the current username system. */
+    get discriminator(): string;
+    /** Whether the account is a bot. */
+    get bot(): boolean;
+    /** Whether the account is an official Discord system account. */
+    get system(): boolean;
+    /** The hash of the avatar; use `avatarURL()` to get the image. */
+    get avatar(): string | null;
+    /** The hash of the banner; use `bannerURL()` to get the image. */
+    get banner(): string | null;
+    /** The banner color, as a number (`0xff0000`). */
+    get accentColor(): number | null;
+    /** Only known for the bot itself. */
+    get locale(): Locale | null;
+    /** The public badges of the account, by name. */
+    get flags(): UserFlagName[];
+    /** The URL of the avatar; of the default one when none is set. */
+    avatarURL(options?: ImageOptions): string;
+    /** The URL of the banner, when one is set. */
+    bannerURL(options?: ImageOptions): string | null;
+    /** Asks Discord for the latest data of this user. */
+    fetch(): Promise<User>;
+    /**
+     * Opens the private conversation with this user.
+     * @see https://docs.discord.com/developers/resources/user#create-dm
+     */
+    createDM(): Promise<DMChannel>;
+    /** Sends a private message to this user. */
+    send(message: MessageInput): Promise<Message>;
+    /** `<@id>`: mentions the user when put in a message. */
+    toString(): string;
+}

package/dist/structures/user.js

@@ -0,0 +1,94 @@
+import { cdn } from '../discord/cdn.js';
+import { CreateDm, GetUser } from '../discord/endpoints.js';
+import { userMention } from '../discord/formatting.js';
+import { UserFlags } from '../discord/types/user.js';
+import { ctxOf, dataOf, IdStructure } from './base.js';
+/**
+ * A Discord account, the same in every server.
+ * @see https://docs.discord.com/developers/resources/user#user-object
+ */
+export class User extends IdStructure {
+    /** The unique name of the account (`@name`). */
+    get username() {
+        return dataOf(this).username;
+    }
+    /** The name shown in Discord, when the user chose one. */
+    get globalName() {
+        return dataOf(this).global_name ?? null;
+    }
+    /** The name to show: the display name, or else the username. */
+    get displayName() {
+        return this.globalName ?? this.username;
+    }
+    /** `"0"` for users on the current username system. */
+    get discriminator() {
+        return dataOf(this).discriminator;
+    }
+    /** Whether the account is a bot. */
+    get bot() {
+        return dataOf(this).bot ?? false;
+    }
+    /** Whether the account is an official Discord system account. */
+    get system() {
+        return dataOf(this).system ?? false;
+    }
+    /** The hash of the avatar; use `avatarURL()` to get the image. */
+    get avatar() {
+        return dataOf(this).avatar;
+    }
+    /** The hash of the banner; use `bannerURL()` to get the image. */
+    get banner() {
+        return dataOf(this).banner ?? null;
+    }
+    /** The banner color, as a number (`0xff0000`). */
+    get accentColor() {
+        return dataOf(this).accent_color ?? null;
+    }
+    /** Only known for the bot itself. */
+    get locale() {
+        return dataOf(this).locale ?? null;
+    }
+    /** The public badges of the account, by name. */
+    get flags() {
+        const bits = dataOf(this).public_flags ?? dataOf(this).flags ?? 0;
+        return Object.keys(UserFlags).filter(name => (bits & UserFlags[name]) !== 0);
+    }
+    /** The URL of the avatar; of the default one when none is set. */
+    avatarURL(options) {
+        return this.avatar
+            ? cdn.userAvatar(this.id, this.avatar, options)
+            : cdn.defaultUserAvatar(this.id, this.discriminator);
+    }
+    /** The URL of the banner, when one is set. */
+    bannerURL(options) {
+        return this.banner ? cdn.userBanner(this.id, this.banner, options) : null;
+    }
+    /** Asks Discord for the latest data of this user. */
+    async fetch() {
+        const { rest, entities } = ctxOf(this);
+        return entities.user(await rest.request(GetUser, [this.id]));
+    }
+    /**
+     * Opens the private conversation with this user.
+     * @see https://docs.discord.com/developers/resources/user#create-dm
+     */
+    async createDM() {
+        const { rest, entities, cache } = ctxOf(this);
+        for (const channel of cache.channels.values()) {
+            if (channel.isDM() && channel.recipientId === this.id)
+                return channel;
+        }
+        const raw = await rest.request(CreateDm, [], {
+            body: { recipient_id: this.id },
+        });
+        return entities.channel(raw);
+    }
+    /** Sends a private message to this user. */
+    async send(message) {
+        return (await this.createDM()).send(message);
+    }
+    /** `<@id>`: mentions the user when put in a message. */
+    toString() {
+        return userMention(this.id);
+    }
+}

package/dist/structures/webhook.d.ts

@@ -0,0 +1,46 @@
+import type { Snowflake } from '../discord/types/common.js';
+import type { ModifyWebhookJSONParams, RawWebhook } from '../discord/types/webhook.js';
+import { type Camelize } from '../util/case.js';
+import { IdStructure } from './base.js';
+import type { Message } from './message.js';
+import { type MessageOptions } from './payload.js';
+/** What a message posted with a webhook can contain. */
+export interface WebhookMessageOptions extends Omit<MessageOptions, 'replyTo'> {
+    /** Shows this name instead of the name of the webhook. */
+    username?: string;
+    /** Shows this avatar instead of the avatar of the webhook. */
+    avatarURL?: string;
+    /** Sends the message in this thread of the channel of the webhook. */
+    threadId?: Snowflake;
+}
+/**
+ * A webhook: a way to post messages in a channel under any name.
+ * @see https://docs.discord.com/developers/resources/webhook#webhook-object
+ */
+export declare class Webhook extends IdStructure<Omit<RawWebhook, 'user'>> {
+    /** The default name the webhook posts with. */
+    get name(): string | null;
+    /** The id of the channel the webhook posts in. */
+    get channelId(): Snowflake | null;
+    /** The id of the server of the webhook. */
+    get guildId(): Snowflake | null;
+    /** The data of the webhook, without its token: a token is a secret. */
+    toJSON(): Camelize<Omit<RawWebhook, 'user'>>;
+    /** Whether the bot can post with it: only webhooks it created. */
+    get canSend(): boolean;
+    /**
+     * Posts a message with the webhook.
+     * @see https://docs.discord.com/developers/resources/webhook#execute-webhook
+     */
+    send(message: string | WebhookMessageOptions): Promise<Message>;
+    /**
+     * Changes the name, the avatar or the channel of the webhook.
+     * @see https://docs.discord.com/developers/resources/webhook#modify-webhook
+     */
+    edit(options: Camelize<ModifyWebhookJSONParams>, reason?: string): Promise<Webhook>;
+    /**
+     * Deletes the webhook.
+     * @see https://docs.discord.com/developers/resources/webhook#delete-webhook
+     */
+    delete(reason?: string): Promise<void>;
+}

package/dist/structures/webhook.js

@@ -0,0 +1,79 @@
+import { DeleteWebhook, ExecuteWebhook, ModifyWebhook, } from '../discord/endpoints.js';
+import { toSnakeCase } from '../util/case.js';
+import { ctxOf, dataOf, IdStructure } from './base.js';
+import { buildMessage } from './payload.js';
+import { translatorOf } from '../messages/translate.js';
+/**
+ * A webhook: a way to post messages in a channel under any name.
+ * @see https://docs.discord.com/developers/resources/webhook#webhook-object
+ */
+export class Webhook extends IdStructure {
+    /** The default name the webhook posts with. */
+    get name() {
+        return dataOf(this).name;
+    }
+    /** The id of the channel the webhook posts in. */
+    get channelId() {
+        return dataOf(this).channel_id;
+    }
+    /** The id of the server of the webhook. */
+    get guildId() {
+        return dataOf(this).guild_id ?? null;
+    }
+    /** The data of the webhook, without its token: a token is a secret. */
+    toJSON() {
+        const { token: _token, ...data } = super.toJSON();
+        return data;
+    }
+    /** Whether the bot can post with it: only webhooks it created. */
+    get canSend() {
+        return typeof dataOf(this).token === 'string';
+    }
+    /**
+     * Posts a message with the webhook.
+     * @see https://docs.discord.com/developers/resources/webhook#execute-webhook
+     */
+    async send(message) {
+        const { rest, entities } = ctxOf(this);
+        const token = dataOf(this).token;
+        if (!token) {
+            throw new Error('This webhook was not created by the bot: Discord only lets its creator post with it.');
+        }
+        const options = typeof message === 'string' ? { content: message } : message;
+        const { body, files } = buildMessage(options, {
+            t: translatorOf(ctxOf(this), {
+                guild: this.guildId ? ctxOf(this).cache.guilds.get(this.guildId) : null,
+            }),
+        });
+        const raw = await rest.request(ExecuteWebhook, [this.id, token], {
+            body: {
+                ...body,
+                username: options.username,
+                avatar_url: options.avatarURL,
+            },
+            query: { wait: true, thread_id: options.threadId },
+            files,
+            auth: false,
+        });
+        return entities.message(raw, this.guildId ?? undefined);
+    }
+    /**
+     * Changes the name, the avatar or the channel of the webhook.
+     * @see https://docs.discord.com/developers/resources/webhook#modify-webhook
+     */
+    async edit(options, reason) {
+        const { rest, entities } = ctxOf(this);
+        const raw = await rest.request(ModifyWebhook, [this.id], {
+            body: toSnakeCase(options),
+            reason,
+        });
+        return entities.webhook(raw);
+    }
+    /**
+     * Deletes the webhook.
+     * @see https://docs.discord.com/developers/resources/webhook#delete-webhook
+     */
+    async delete(reason) {
+        await ctxOf(this).rest.request(DeleteWebhook, [this.id], { reason });
+    }
+}

package/dist/tasks/convention.d.ts

@@ -0,0 +1,26 @@
+import type { Convention } from '../loader/loader.js';
+import { type Schedule } from './schedule.js';
+import { type TaskContext } from './task.js';
+/** A task file, checked: what the scheduler works with. */
+export interface LoadedTask {
+    /** The name of the task: the path of the file, without extension. */
+    readonly name: string;
+    readonly schedule: Schedule;
+    readonly onStart: boolean;
+    readonly run: (context: TaskContext) => unknown;
+}
+/**
+ * `src/tasks/`: each file is a task, named after its path. It exports by
+ * default what `task()` returns:
+ *
+ * ```ts
+ * // src/tasks/report.ts
+ * import { task } from 'chapterjs';
+ *
+ * export default task({
+ *   cron: '0 9 * * 1',
+ *   async run({ guilds }) { ... },
+ * });
+ * ```
+ */
+export declare const tasksConvention: Convention<LoadedTask>;

package/dist/tasks/convention.js

@@ -0,0 +1,78 @@
+// `src/tasks/`: one file per task, named after it. What the file declares
+// is checked when it loads, so a wrong duration or cron is explained
+// before the bot waits for it.
+import { parseCron, parseEvery } from './schedule.js';
+import { isTaskFile } from './task.js';
+const fail = (message) => {
+    throw new TypeError(message);
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const KEYS = ['every', 'cron', 'timezone', 'onStart', 'run'];
+/**
+ * `src/tasks/`: each file is a task, named after its path. It exports by
+ * default what `task()` returns:
+ *
+ * ```ts
+ * // src/tasks/report.ts
+ * import { task } from 'chapterjs';
+ *
+ * export default task({
+ *   cron: '0 9 * * 1',
+ *   async run({ guilds }) { ... },
+ * });
+ * ```
+ */
+export const tasksConvention = {
+    folder: 'tasks',
+    one: 'task',
+    many: 'tasks',
+    check(path) {
+        for (const part of path.replace(/\.[^./]+$/, '').split('/')) {
+            if (!/^[A-Za-z0-9_-]+$/.test(part)) {
+                fail(`"${part}" can't be in the name of a task: use letters, digits, - and _ only. The path of the file is the name of the task.`);
+            }
+        }
+    },
+    read(exports, path) {
+        const file = exports.default;
+        const example = `import { task } from 'chapterjs'; export default task({ every: '10m', run() { ... } })`;
+        if (!isTaskFile(file)) {
+            return fail('default' in exports
+                ? `The default export of this file must be what task() returns: ${example}`
+                : `This file has no default export. It should look like: ${example}`);
+        }
+        const config = file.config;
+        if (!isRecord(config)) {
+            return fail(`task() needs an object: task({ every: '10m', run() { ... } })`);
+        }
+        for (const key of Object.keys(config)) {
+            if (!KEYS.includes(key)) {
+                fail(`"${key}" is not something a task has. It can have: ${KEYS.join(', ')}.`);
+            }
+        }
+        if (config.every !== undefined && config.cron !== undefined) {
+            fail(`This task has both "every" and "cron": keep one. "every" is an interval ('10m'), "cron" a time ('0 9 * * *').`);
+        }
+        if (config.every === undefined && config.cron === undefined) {
+            fail(`This task does not say when it runs: add every: '10m' (an interval) or cron: '0 9 * * *' (a time).`);
+        }
+        if (config.every !== undefined && config.timezone !== undefined) {
+            fail(`"timezone" only goes with "cron": an interval is the same in every timezone.`);
+        }
+        const schedule = config.every !== undefined
+            ? parseEvery(config.every)
+            : parseCron(config.cron, config.timezone);
+        if (config.onStart !== undefined && typeof config.onStart !== 'boolean') {
+            fail(`"onStart" is true or false, got ${JSON.stringify(config.onStart) ?? typeof config.onStart}.`);
+        }
+        if (typeof config.run !== 'function') {
+            fail(`This task has no "run": the function to run each time, like async run({ guilds }) { ... }`);
+        }
+        return Object.freeze({
+            name: path.replace(/\.[^./]+$/, ''),
+            schedule,
+            onStart: config.onStart === true,
+            run: config.run,
+        });
+    },
+};

package/dist/tasks/schedule.d.ts

@@ -0,0 +1,54 @@
+/** A duration: every so often. */
+export interface EverySchedule {
+    readonly kind: 'every';
+    /** The text the file gave: `'10m'`. */
+    readonly text: string;
+    readonly ms: number;
+}
+/** A cron expression, in a timezone. */
+export interface CronSchedule {
+    readonly kind: 'cron';
+    /** The text the file gave: `'0 9 * * 1-5'`. */
+    readonly text: string;
+    readonly timezone: string;
+    /** For each field, the values that match. */
+    readonly minutes: ReadonlySet<number>;
+    readonly hours: ReadonlySet<number>;
+    readonly days: ReadonlySet<number>;
+    readonly months: ReadonlySet<number>;
+    readonly weekdays: ReadonlySet<number>;
+    /** Whether the day of month was given (`*` in both day fields means every day). */
+    readonly anyDay: boolean;
+    readonly anyWeekday: boolean;
+}
+export type Schedule = EverySchedule | CronSchedule;
+/** The shortest `every` accepted, in milliseconds. */
+export declare const MIN_EVERY = 1000;
+/**
+ * Parses a duration: a number and a unit, `s`, `m`, `h` or `d`, like
+ * `'30s'`, `'10m'`, `'2h'`, `'1d'`. Several parts add up: `'1h30m'`.
+ */
+export declare function parseEvery(text: unknown): EverySchedule;
+/** Whether a timezone exists, as `Intl` knows them. */
+export declare function isTimezone(name: string): boolean;
+/** The timezone of the machine. */
+export declare const localTimezone: () => string;
+/**
+ * Parses a cron expression: five fields, minute, hour, day of month,
+ * month and day of week, with `*`, lists, ranges, steps and names.
+ * @see https://en.wikipedia.org/wiki/Cron#Cron_expression
+ */
+export declare function parseCron(text: unknown, timezone: unknown): CronSchedule;
+/**
+ * The next moment a cron matches, strictly after `from`; `null` when none
+ * comes in the next five years. Walks the clock of the timezone: minute
+ * by minute within a matching hour, hour by hour otherwise, so a change
+ * of daylight saving time is read, not computed.
+ */
+export declare function nextCron(schedule: CronSchedule, from: Date): Date | null;
+/** The next time a schedule is due, strictly after `from`. */
+export declare function nextRun(schedule: Schedule, from: Date): Date;
+/** What tells one schedule from another: the same key is the same timing. */
+export declare const scheduleKey: (schedule: Schedule) => string;
+/** The schedule in words, for the developer. */
+export declare const describeSchedule: (schedule: Schedule) => string;