chapterjs 0.1.2 → 0.2.0

package/dist/presence.d.ts

@@ -1,92 +0,0 @@
-import type { Client } from './discord/client.js';
-import type { Gateway } from './discord/gateway.js';
-import type { Presence } from './discord/presence.js';
-export interface PresenceContext {
-    client: Client;
-}
-/** Computes one presence. Can be async, e.g. to read from a database. */
-export type PresenceFunction = (context: PresenceContext) => Presence | Promise<Presence>;
-/** One step of a rotation, shown for `duration` milliseconds (minimum 5000). */
-export type PresenceStep = (Presence & {
-    duration: number;
-}) | {
-    duration: number;
-    presence: PresenceFunction;
-};
-/**
- * Computes either a presence or a whole rotation, e.g. from a database.
- * A rotation is played in full, then the function is called again.
- */
-export type PresenceSourceFunction = (context: PresenceContext) => Presence | PresenceStep[] | Promise<Presence | PresenceStep[]>;
-/** Stops listening for changes. */
-export type PresenceWatchCleanup = () => void;
-export interface PresenceDefinition {
-    presence: PresenceSourceFunction;
-    /**
-     * When `presence` returns a single presence: delay before calling it again,
-     * in milliseconds (minimum 5000). Without it, it is called once.
-     */
-    interval?: number;
-    /**
-     * Calls `refresh` whenever the data behind `presence` changes (database
-     * realtime, webhook…) to apply it right away. Return a cleanup function.
-     */
-    watch?: (refresh: () => void) => void | PresenceWatchCleanup | Promise<void | PresenceWatchCleanup>;
-}
-/**
- * - `Presence`: a fixed presence
- * - `PresenceStep[]`: a rotation, each step shown for its own `duration`
- * - a function: a presence or a rotation computed at runtime
- * - `PresenceDefinition`: a function with `interval` and/or `watch`
- */
-export type PresenceInput = Presence | readonly PresenceStep[] | PresenceSourceFunction | PresenceDefinition;
-/** Defines the bot's status and activity in `src/presence.ts`. */
-export declare function definePresence<const T extends PresenceInput>(input: T & CheckDurations<T>): T;
-type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
-type IntegerPart<S extends string> = S extends `${infer I}.${string}` ? I : S;
-type IsAtLeast5000<N extends number> = number extends N ? true : `${N}` extends `-${string}` ? false : `${N}` extends `${string}e+${string}` ? true : IntegerPart<`${N}`> extends `${'5' | '6' | '7' | '8' | '9'}${Digit}${Digit}${Digit}` ? true : IntegerPart<`${N}`> extends `${Exclude<Digit, '0'>}${Digit}${Digit}${Digit}${Digit}${string}` ? true : false;
-/** A required key that can't be provided: its name is the error shown in the editor. */
-type Fails<Key extends string> = {
-    [K in Key]: never;
-};
-type CheckKey<T, Key extends string> = T extends {
-    readonly [K in Key]: infer N extends number;
-} ? IsAtLeast5000<N> extends true ? unknown : Fails<`⛔ ${Key} must be at least 5000 ms`> : unknown;
-type CheckDurations<T> = T extends readonly unknown[] ? {
-    [K in keyof T]: CheckKey<T[K], 'duration'>;
-} : CheckKey<T, 'interval'>;
-/** Recomputes the presence right away, e.g. after updating it in a database. */
-export declare function refreshPresence(): void;
-interface NormalizedStep {
-    /** Without duration, the rotation stops after this step. */
-    duration?: number;
-    presence: PresenceFunction;
-}
-interface PresenceLogger {
-    error: (error: unknown) => void;
-    warn: (message: string) => void;
-}
-/** Every input is normalized into a source giving the steps of each cycle. */
-export interface PresenceSource {
-    load: (context: PresenceContext, warn: (message: string) => void) => Promise<NormalizedStep[]>;
-    watch?: PresenceDefinition['watch'];
-    /**
-     * First presence when it is known without running any code, sent when
-     * connecting: Discord shows it right away instead of a default presence.
-     */
-    initial?: Presence;
-}
-/**
- * Loads `src/presence.ts`, or returns null when the project has none. Errors
- * are prefixed with the file (and line when known).
- */
-export declare function loadPresence(cwd?: string): Promise<PresenceSource | null>;
-export declare function watchPresence(onChange: () => void, cwd?: string): import("fs").FSWatcher | null;
-/**
- * Plays the steps of each cycle in order, then loads the next cycle. Each step
- * waits for its `presence` call to settle, then for its `duration`, so slow
- * calls never overlap. `refresh` (from `watch` or `refreshPresence`) restarts
- * from a fresh cycle. Returns a stop function.
- */
-export declare function startPresenceLoop(gateway: Gateway, source: PresenceSource, log: PresenceLogger): () => void;
-export {};

package/dist/presence.js

@@ -1,250 +0,0 @@
-import { resolve } from 'node:path';
-import { describeLoadError, findFile, importFresh, watchFiles } from './utils/modules.js';
-/** Defines the bot's status and activity in `src/presence.ts`. */
-export function definePresence(input) {
-    return input;
-}
-let activeRefresh = null;
-/** Recomputes the presence right away, e.g. after updating it in a database. */
-export function refreshPresence() {
-    activeRefresh?.();
-}
-const PRESENCE_FILES = ['presence.ts', 'presence.mts', 'presence.js', 'presence.mjs'];
-/** Matches the client throttle, a shorter duration would only skip updates. */
-const MIN_DURATION = 5_000;
-/** A `presence` call taking longer is considered failed. */
-const PRESENCE_TIMEOUT = 10_000;
-/** Delay before calling `presence` again when it gave nothing to show. */
-const RETRY_DELAY = 30_000;
-/** Groups the refresh calls fired by a burst of changes. */
-const REFRESH_DEBOUNCE = 500;
-const srcDir = (cwd) => resolve(cwd, 'src');
-/**
- * Loads `src/presence.ts`, or returns null when the project has none. Errors
- * are prefixed with the file (and line when known).
- */
-export async function loadPresence(cwd = process.cwd()) {
-    const path = findFile(srcDir(cwd), PRESENCE_FILES);
-    if (!path)
-        return null;
-    try {
-        const input = (await importFresh(path)).default;
-        if (!input || (typeof input !== 'object' && typeof input !== 'function')) {
-            throw new Error("doesn't export a presence. Add at the end of the file: export default definePresence({ activity: 'Hello' })");
-        }
-        return normalize(input);
-    }
-    catch (error) {
-        throw new Error(describeLoadError(error, path, cwd), { cause: error });
-    }
-}
-function normalize(input) {
-    if (typeof input === 'function')
-        return { load: fromFunction(input) };
-    if (Array.isArray(input)) {
-        // Written in code: invalid steps are errors, reported before the bot starts
-        if (input.length === 0)
-            throw new Error('the list of presences is empty: add at least one.');
-        const steps = input.map((step, index) => {
-            assertDuration(step.duration, `step ${index + 1}: duration`);
-            return { duration: step.duration, presence: toFunction(step) };
-        });
-        const first = input[0];
-        const initial = 'presence' in first && typeof first.presence === 'function' ? undefined : first;
-        return { load: async () => steps, initial };
-    }
-    if ('presence' in input && typeof input.presence === 'function') {
-        if (input.interval !== undefined)
-            assertDuration(input.interval, 'interval');
-        return { load: fromFunction(input.presence, input.interval), watch: input.watch };
-    }
-    return { load: async () => [{ presence: () => input }], initial: input };
-}
-function fromFunction(fn, interval) {
-    return async (context, warn) => {
-        const result = await fn(context);
-        if (Array.isArray(result))
-            return sanitizeSteps(result, warn);
-        if (result && typeof result === 'object')
-            return [{ duration: interval, presence: () => result }];
-        throw new Error(`presence() returned ${result === undefined ? 'nothing' : JSON.stringify(result)}: it must return a presence, e.g. { activity: 'Hello' }, or a list of steps.`);
-    };
-}
-/**
- * Steps computed at runtime may come from a database edited by someone else,
- * so they are fixed with a warning instead of stopping the bot.
- */
-function sanitizeSteps(steps, warn) {
-    const valid = [];
-    steps.forEach((step, index) => {
-        const name = `step ${index + 1}`;
-        if (!step || typeof step !== 'object' || typeof step.duration !== 'number' || !(step.duration > 0)) {
-            warn(`${name} ignored: it needs a duration in milliseconds, e.g. duration: 10_000.`);
-            return;
-        }
-        let duration = step.duration;
-        if (duration < MIN_DURATION) {
-            warn(`${name}: duration ${duration} ms raised to ${MIN_DURATION} ms (Discord limits how often a presence can change).`);
-            duration = MIN_DURATION;
-        }
-        valid.push({ duration, presence: toFunction(step) });
-    });
-    return valid;
-}
-function toFunction(input) {
-    if ('presence' in input && typeof input.presence === 'function')
-        return input.presence;
-    // Extra keys such as `duration` are ignored when sent to Discord
-    return () => input;
-}
-function assertDuration(value, name) {
-    if (typeof value !== 'number' || value < MIN_DURATION) {
-        throw new Error(`${name} is ${typeof value === 'number' ? `${value} ms` : JSON.stringify(value)}, it must be at least ${MIN_DURATION} ms (${MIN_DURATION / 1000} seconds): ` +
-            'Discord limits how often a bot can change its presence.');
-    }
-}
-export function watchPresence(onChange, cwd = process.cwd()) {
-    return watchFiles(srcDir(cwd), PRESENCE_FILES, onChange);
-}
-/**
- * Plays the steps of each cycle in order, then loads the next cycle. Each step
- * waits for its `presence` call to settle, then for its `duration`, so slow
- * calls never overlap. `refresh` (from `watch` or `refreshPresence`) restarts
- * from a fresh cycle. Returns a stop function.
- */
-export function startPresenceLoop(gateway, source, log) {
-    const context = { client: gateway.client };
-    let stopped = false;
-    /** Incremented on refresh and stop; a run whose generation is outdated exits. */
-    let generation = 0;
-    let lastSteps = null;
-    /**
-     * Issues of the previous and current cycle: an issue already reported in the
-     * previous cycle is not logged again, so a bad row isn't reported every cycle.
-     */
-    let previousIssues = new Set();
-    let currentIssues = new Set();
-    let sleepTimeout;
-    let wake;
-    let refreshTimeout;
-    let cleanupWatch;
-    const report = (level, issue) => {
-        const message = issue instanceof Error ? issue.message : String(issue);
-        const key = `${level}:${message}`;
-        if (currentIssues.has(key))
-            return;
-        currentIssues.add(key);
-        if (!previousIssues.has(key))
-            log[level](message);
-    };
-    const startCycle = () => {
-        previousIssues = currentIssues;
-        currentIssues = new Set();
-    };
-    /** Resolves to false if a refresh or stop happened meanwhile. */
-    const sleep = (ms, id) => new Promise((resolve) => {
-        wake = resolve;
-        sleepTimeout = setTimeout(() => resolve(id === generation), ms);
-    });
-    const loadSteps = async (id) => {
-        try {
-            const warnings = [];
-            const steps = await withTimeout(source.load(context, (message) => warnings.push(message)), PRESENCE_TIMEOUT);
-            if (id !== generation)
-                return null;
-            for (const message of warnings)
-                report('warn', message);
-            if (steps.length > 0)
-                return (lastSteps = steps);
-            report('warn', `presence() returned an empty list, trying again in ${RETRY_DELAY / 1000}s.`);
-            return null;
-        }
-        catch (error) {
-            if (id !== generation)
-                return null;
-            report('error', error);
-            // Keep playing the previous rotation until the next attempt
-            return lastSteps;
-        }
-    };
-    const run = async (id) => {
-        while (id === generation) {
-            startCycle();
-            const steps = await loadSteps(id);
-            if (id !== generation)
-                return;
-            if (!steps) {
-                if (!(await sleep(RETRY_DELAY, id)))
-                    return;
-                continue;
-            }
-            for (const step of steps) {
-                try {
-                    const presence = await withTimeout(Promise.resolve(step.presence(context)), PRESENCE_TIMEOUT);
-                    if (id === generation)
-                        gateway.setPresence(presence);
-                }
-                catch (error) {
-                    // The previous presence stays in place, the rotation goes on
-                    if (id === generation)
-                        report('error', error);
-                }
-                if (id !== generation || step.duration === undefined)
-                    return;
-                if (!(await sleep(step.duration, id)))
-                    return;
-            }
-        }
-    };
-    const restart = () => {
-        generation++;
-        clearTimeout(sleepTimeout);
-        wake?.(false);
-        void run(generation);
-    };
-    const refresh = () => {
-        if (stopped)
-            return;
-        clearTimeout(refreshTimeout);
-        refreshTimeout = setTimeout(restart, REFRESH_DEBOUNCE);
-    };
-    activeRefresh = refresh;
-    restart();
-    if (source.watch) {
-        Promise.resolve()
-            .then(() => source.watch(refresh))
-            .then((cleanup) => {
-            if (!cleanup)
-                return;
-            if (stopped)
-                cleanup();
-            else
-                cleanupWatch = cleanup;
-        })
-            .catch((error) => report('error', error));
-    }
-    return () => {
-        stopped = true;
-        generation++;
-        clearTimeout(sleepTimeout);
-        clearTimeout(refreshTimeout);
-        wake?.(false);
-        if (activeRefresh === refresh)
-            activeRefresh = null;
-        try {
-            cleanupWatch?.();
-        }
-        catch (error) {
-            log.error(error);
-        }
-    };
-}
-function withTimeout(promise, ms) {
-    let timeout;
-    return Promise.race([
-        promise,
-        new Promise((_, reject) => {
-            timeout = setTimeout(() => reject(new Error(`presence() took more than ${ms / 1000}s to return, keeping the previous presence.`)), ms);
-        }),
-    ]).finally(() => clearTimeout(timeout));
-}

package/dist/structures/Channel.d.ts

@@ -1,110 +0,0 @@
-import type { Client } from '../discord/client.js';
-import type { APIChannel, Snowflake } from '../discord/types.js';
-import { Guild } from './Guild.js';
-import { Message } from './Message.js';
-import { type MessageOptions } from './utils.js';
-export declare const ChannelType: {
-    readonly GuildText: 0;
-    readonly DM: 1;
-    readonly GuildVoice: 2;
-    readonly GroupDM: 3;
-    readonly GuildCategory: 4;
-    readonly GuildAnnouncement: 5;
-    readonly AnnouncementThread: 10;
-    readonly PublicThread: 11;
-    readonly PrivateThread: 12;
-    readonly GuildStageVoice: 13;
-    readonly GuildDirectory: 14;
-    readonly GuildForum: 15;
-    readonly GuildMedia: 16;
-};
-export interface FetchMessagesOptions {
-    /** 1 to 100, defaults to 50. */
-    limit?: number;
-    before?: Snowflake;
-    after?: Snowflake;
-    around?: Snowflake;
-}
-export interface CreateThreadOptions {
-    /** 1 to 100 characters. */
-    name: string;
-    /** Minutes of inactivity before the thread is hidden: 60, 1440, 4320 or 10080. */
-    autoArchiveDuration?: 60 | 1440 | 4320 | 10080;
-    /** Seconds between two messages of a user, 0 to 21600. */
-    rateLimitPerUser?: number;
-    /** `ChannelType.PrivateThread` for a private thread. Without message only. */
-    type?: number;
-    /** Whether non-moderators can add other non-moderators. Private threads only. */
-    invitable?: boolean;
-    reason?: string;
-}
-/**
- * A channel or thread. Events often only send its id: fields Discord didn't
- * send are undefined, `fetch()` returns the full channel.
- * https://docs.discord.com/developers/resources/channel#channel-object
- */
-export declare class Channel {
-    readonly client: Client;
-    readonly raw: Partial<APIChannel> & {
-        id: Snowflake;
-    };
-    readonly id: Snowflake;
-    /** See `ChannelType`. Undefined when only the id is known. */
-    readonly type: number | undefined;
-    readonly guildId: Snowflake | null;
-    readonly name: string | null | undefined;
-    readonly topic: string | null | undefined;
-    readonly nsfw: boolean | undefined;
-    readonly position: number | undefined;
-    /** Category of a channel, or parent channel of a thread. */
-    readonly parentId: Snowflake | null | undefined;
-    readonly lastMessageId: Snowflake | null | undefined;
-    /** Slowmode, in seconds. */
-    readonly rateLimitPerUser: number | undefined;
-    constructor(client: Client, raw: Partial<APIChannel> & {
-        id: Snowflake;
-    });
-    /** Server of the channel, null for DMs. */
-    get guild(): Guild | null;
-    get createdAt(): Date;
-    get url(): string;
-    isThread(): boolean;
-    isDM(): boolean;
-    isVoice(): boolean;
-    /** Mention, e.g. `${channel}` in a message. */
-    toString(): string;
-    /** https://docs.discord.com/developers/resources/message#create-message */
-    send(options: MessageOptions): Promise<Message>;
-    /**
-     * Shows "Bot is typing…" for 10 seconds or until the bot sends a message.
-     * https://docs.discord.com/developers/resources/channel#trigger-typing-indicator
-     */
-    sendTyping(): Promise<void>;
-    /** https://docs.discord.com/developers/resources/message#get-channel-message */
-    fetchMessage(id: Snowflake): Promise<Message>;
-    /** Newest first. https://docs.discord.com/developers/resources/message#get-channel-messages */
-    fetchMessages(options?: FetchMessagesOptions): Promise<Message[]>;
-    /**
-     * Deletes 2 to 100 messages at once, none older than 2 weeks.
-     * https://docs.discord.com/developers/resources/message#bulk-delete-messages
-     */
-    bulkDelete(messageIds: Snowflake[], reason?: string): Promise<void>;
-    /** https://docs.discord.com/developers/resources/channel#start-thread-without-message */
-    createThread(options: CreateThreadOptions): Promise<Channel>;
-    /** https://docs.discord.com/developers/resources/channel#get-channel */
-    fetch(): Promise<Channel>;
-    /**
-     * Updates the channel with fields of the documented JSON params (snake_case).
-     * https://docs.discord.com/developers/resources/channel#modify-channel
-     */
-    edit(data: Record<string, unknown>, reason?: string): Promise<Channel>;
-    /** Cannot be undone for guild channels. https://docs.discord.com/developers/resources/channel#deleteclose-channel */
-    delete(reason?: string): Promise<void>;
-}
-export declare function toThreadBody(options: Omit<CreateThreadOptions, 'reason'>): {
-    name: string;
-    type?: number;
-    invitable?: boolean;
-    auto_archive_duration?: 60 | 1440 | 4320 | 10080 | undefined;
-    rate_limit_per_user?: number | undefined;
-};

package/dist/structures/Channel.js

@@ -1,171 +0,0 @@
-import { Guild } from './Guild.js';
-import { Message } from './Message.js';
-import { snowflakeDate, toMessageBody } from './utils.js';
-// https://docs.discord.com/developers/resources/channel#channel-object-channel-types
-export const ChannelType = {
-    GuildText: 0,
-    DM: 1,
-    GuildVoice: 2,
-    GroupDM: 3,
-    GuildCategory: 4,
-    GuildAnnouncement: 5,
-    AnnouncementThread: 10,
-    PublicThread: 11,
-    PrivateThread: 12,
-    GuildStageVoice: 13,
-    GuildDirectory: 14,
-    GuildForum: 15,
-    GuildMedia: 16,
-};
-const THREAD_TYPES = [
-    ChannelType.AnnouncementThread,
-    ChannelType.PublicThread,
-    ChannelType.PrivateThread,
-];
-/**
- * A channel or thread. Events often only send its id: fields Discord didn't
- * send are undefined, `fetch()` returns the full channel.
- * https://docs.discord.com/developers/resources/channel#channel-object
- */
-export class Channel {
-    client;
-    raw;
-    id;
-    /** See `ChannelType`. Undefined when only the id is known. */
-    type;
-    guildId;
-    name;
-    topic;
-    nsfw;
-    position;
-    /** Category of a channel, or parent channel of a thread. */
-    parentId;
-    lastMessageId;
-    /** Slowmode, in seconds. */
-    rateLimitPerUser;
-    constructor(client, raw) {
-        this.client = client;
-        this.raw = raw;
-        this.id = raw.id;
-        this.type = raw.type;
-        this.guildId = raw.guild_id ?? null;
-        this.name = raw.name;
-        this.topic = raw.topic;
-        this.nsfw = raw.nsfw;
-        this.position = raw.position;
-        this.parentId = raw.parent_id;
-        this.lastMessageId = raw.last_message_id;
-        this.rateLimitPerUser = raw.rate_limit_per_user;
-    }
-    /** Server of the channel, null for DMs. */
-    get guild() {
-        return this.guildId ? new Guild(this.client, { id: this.guildId }) : null;
-    }
-    get createdAt() {
-        return snowflakeDate(this.id);
-    }
-    get url() {
-        return `https://discord.com/channels/${this.guildId ?? '@me'}/${this.id}`;
-    }
-    isThread() {
-        return this.type !== undefined && THREAD_TYPES.includes(this.type);
-    }
-    isDM() {
-        return this.type === ChannelType.DM || this.type === ChannelType.GroupDM;
-    }
-    isVoice() {
-        return (this.type === ChannelType.GuildVoice ||
-            this.type === ChannelType.GuildStageVoice);
-    }
-    /** Mention, e.g. `${channel}` in a message. */
-    toString() {
-        return `<#${this.id}>`;
-    }
-    /** https://docs.discord.com/developers/resources/message#create-message */
-    async send(options) {
-        const { body, files } = toMessageBody(options);
-        const message = await this.client.rest.post(`/channels/${this.id}/messages`, {
-            body,
-            files,
-        });
-        return new Message(this.client, {
-            guild_id: this.guildId ?? undefined,
-            ...message,
-        });
-    }
-    /**
-     * Shows "Bot is typing…" for 10 seconds or until the bot sends a message.
-     * https://docs.discord.com/developers/resources/channel#trigger-typing-indicator
-     */
-    async sendTyping() {
-        await this.client.rest.post(`/channels/${this.id}/typing`);
-    }
-    /** https://docs.discord.com/developers/resources/message#get-channel-message */
-    async fetchMessage(id) {
-        const message = await this.client.rest.get(`/channels/${this.id}/messages/${id}`);
-        return new Message(this.client, {
-            guild_id: this.guildId ?? undefined,
-            ...message,
-        });
-    }
-    /** Newest first. https://docs.discord.com/developers/resources/message#get-channel-messages */
-    async fetchMessages(options = {}) {
-        const messages = await this.client.rest.get(`/channels/${this.id}/messages`, {
-            query: { ...options },
-        });
-        return messages.map(message => new Message(this.client, {
-            guild_id: this.guildId ?? undefined,
-            ...message,
-        }));
-    }
-    /**
-     * Deletes 2 to 100 messages at once, none older than 2 weeks.
-     * https://docs.discord.com/developers/resources/message#bulk-delete-messages
-     */
-    async bulkDelete(messageIds, reason) {
-        await this.client.rest.post(`/channels/${this.id}/messages/bulk-delete`, {
-            body: { messages: messageIds },
-            reason,
-        });
-    }
-    /** https://docs.discord.com/developers/resources/channel#start-thread-without-message */
-    async createThread(options) {
-        const { reason, ...thread } = options;
-        const channel = await this.client.rest.post(`/channels/${this.id}/threads`, {
-            body: toThreadBody(thread),
-            reason,
-        });
-        return new Channel(this.client, channel);
-    }
-    /** https://docs.discord.com/developers/resources/channel#get-channel */
-    async fetch() {
-        return new Channel(this.client, await this.client.rest.get(`/channels/${this.id}`));
-    }
-    /**
-     * Updates the channel with fields of the documented JSON params (snake_case).
-     * https://docs.discord.com/developers/resources/channel#modify-channel
-     */
-    async edit(data, reason) {
-        const channel = await this.client.rest.patch(`/channels/${this.id}`, {
-            body: data,
-            reason,
-        });
-        return new Channel(this.client, channel);
-    }
-    /** Cannot be undone for guild channels. https://docs.discord.com/developers/resources/channel#deleteclose-channel */
-    async delete(reason) {
-        await this.client.rest.delete(`/channels/${this.id}`, { reason });
-    }
-}
-export function toThreadBody(options) {
-    const { autoArchiveDuration, rateLimitPerUser, ...rest } = options;
-    return {
-        ...rest,
-        ...(autoArchiveDuration !== undefined && {
-            auto_archive_duration: autoArchiveDuration,
-        }),
-        ...(rateLimitPerUser !== undefined && {
-            rate_limit_per_user: rateLimitPerUser,
-        }),
-    };
-}