chapterjs 0.0.0 → 0.1.1

package/dist/discord/events.js

@@ -0,0 +1,102 @@
+import { GatewayIntents } from './constants.js';
+const { Guilds, GuildMembers, GuildModeration, GuildExpressions, GuildIntegrations, GuildWebhooks, GuildInvites, GuildVoiceStates, GuildPresences, GuildMessages, GuildMessageReactions, GuildMessageTyping, DirectMessages, DirectMessageReactions, DirectMessageTyping, GuildScheduledEvents, AutoModerationConfiguration, AutoModerationExecution, GuildMessagePolls, DirectMessagePolls, } = GatewayIntents;
+/**
+ * Every dispatch event an app can receive, by camelCase name, with the intents
+ * that make Discord send it (0 when it is always sent). An event listed under
+ * several intents (guild and DM) needs any of them; all are requested.
+ *
+ * https://docs.discord.com/developers/events/gateway-events#receive-events
+ * https://docs.discord.com/developers/events/gateway#list-of-intents
+ */
+export const GATEWAY_EVENTS = {
+    ready: 0,
+    resumed: 0,
+    rateLimited: 0,
+    applicationCommandPermissionsUpdate: 0,
+    autoModerationRuleCreate: AutoModerationConfiguration,
+    autoModerationRuleUpdate: AutoModerationConfiguration,
+    autoModerationRuleDelete: AutoModerationConfiguration,
+    autoModerationActionExecution: AutoModerationExecution,
+    channelCreate: Guilds,
+    channelUpdate: Guilds,
+    channelDelete: Guilds,
+    channelInfo: 0,
+    channelPinsUpdate: Guilds | DirectMessages,
+    voiceChannelStatusUpdate: Guilds,
+    voiceChannelStartTimeUpdate: Guilds,
+    threadCreate: Guilds,
+    threadUpdate: Guilds,
+    threadDelete: Guilds,
+    threadListSync: Guilds,
+    threadMemberUpdate: Guilds,
+    // Other members' updates also need the privileged GuildMembers intent
+    threadMembersUpdate: Guilds,
+    entitlementCreate: 0,
+    entitlementUpdate: 0,
+    entitlementDelete: 0,
+    guildCreate: Guilds,
+    guildUpdate: Guilds,
+    guildDelete: Guilds,
+    guildAuditLogEntryCreate: GuildModeration,
+    guildBanAdd: GuildModeration,
+    guildBanRemove: GuildModeration,
+    guildEmojisUpdate: GuildExpressions,
+    guildStickersUpdate: GuildExpressions,
+    guildIntegrationsUpdate: GuildIntegrations,
+    guildMemberAdd: GuildMembers,
+    guildMemberRemove: GuildMembers,
+    guildMemberUpdate: GuildMembers,
+    guildMembersChunk: 0,
+    guildRoleCreate: Guilds,
+    guildRoleUpdate: Guilds,
+    guildRoleDelete: Guilds,
+    guildScheduledEventCreate: GuildScheduledEvents,
+    guildScheduledEventUpdate: GuildScheduledEvents,
+    guildScheduledEventDelete: GuildScheduledEvents,
+    guildScheduledEventUserAdd: GuildScheduledEvents,
+    guildScheduledEventUserRemove: GuildScheduledEvents,
+    guildSoundboardSoundCreate: GuildExpressions,
+    guildSoundboardSoundUpdate: GuildExpressions,
+    guildSoundboardSoundDelete: GuildExpressions,
+    guildSoundboardSoundsUpdate: GuildExpressions,
+    soundboardSounds: 0,
+    integrationCreate: GuildIntegrations,
+    integrationUpdate: GuildIntegrations,
+    integrationDelete: GuildIntegrations,
+    interactionCreate: 0,
+    inviteCreate: GuildInvites,
+    inviteDelete: GuildInvites,
+    messageCreate: GuildMessages | DirectMessages,
+    messageUpdate: GuildMessages | DirectMessages,
+    messageDelete: GuildMessages | DirectMessages,
+    messageDeleteBulk: GuildMessages,
+    messageReactionAdd: GuildMessageReactions | DirectMessageReactions,
+    messageReactionRemove: GuildMessageReactions | DirectMessageReactions,
+    messageReactionRemoveAll: GuildMessageReactions | DirectMessageReactions,
+    messageReactionRemoveEmoji: GuildMessageReactions | DirectMessageReactions,
+    presenceUpdate: GuildPresences,
+    stageInstanceCreate: Guilds,
+    stageInstanceUpdate: Guilds,
+    stageInstanceDelete: Guilds,
+    subscriptionCreate: 0,
+    subscriptionUpdate: 0,
+    subscriptionDelete: 0,
+    typingStart: GuildMessageTyping | DirectMessageTyping,
+    userUpdate: 0,
+    voiceChannelEffectSend: GuildVoiceStates,
+    voiceStateUpdate: GuildVoiceStates,
+    voiceServerUpdate: 0,
+    webhooksUpdate: GuildWebhooks,
+    messagePollVoteAdd: GuildMessagePolls | DirectMessagePolls,
+    messagePollVoteRemove: GuildMessagePolls | DirectMessagePolls,
+};
+/** `messageCreate` → `MESSAGE_CREATE`, as sent by Discord. */
+export function toDispatchName(name) {
+    return name.replace(/[A-Z]/g, letter => `_${letter}`).toUpperCase();
+}
+/** Intents only granted once enabled in the Developer Portal (Bot > Privileged Gateway Intents). */
+export const PRIVILEGED_INTENTS = {
+    GuildMembers: GatewayIntents.GuildMembers,
+    GuildPresences: GatewayIntents.GuildPresences,
+    MessageContent: GatewayIntents.MessageContent,
+};

package/dist/discord/gateway.d.ts

@@ -0,0 +1,61 @@
+import { EventEmitter } from 'node:events';
+import { type Presence } from './presence.js';
+import { RestClient } from './rest.js';
+import { type Client } from './client.js';
+import { User } from '../structures/User.js';
+/** Error emitted with `fatal` when Discord closed the connection for good. */
+export declare class GatewayCloseError extends Error {
+    /** https://docs.discord.com/developers/topics/opcodes-and-status-codes#gateway-gateway-close-event-codes */
+    readonly code: number;
+    constructor(message: string, 
+    /** https://docs.discord.com/developers/topics/opcodes-and-status-codes#gateway-gateway-close-event-codes */
+    code: number);
+}
+export interface GatewayOptions {
+    token: string;
+    /** Bitfield of gateway intents, see `GatewayIntents`. Defaults to `Guilds`. */
+    intents?: number;
+    /** Guild reserved for development, see `dev`. */
+    devGuildId?: string;
+    /**
+     * In dev mode, only events from `devGuildId` reach your handlers.
+     * Otherwise, events from `devGuildId` are ignored so a dev process and a
+     * production process can share the same bot.
+     */
+    dev?: boolean;
+    /** Status and activity shown when the bot connects, see `setPresence`. */
+    presence?: Presence;
+}
+/**
+ * The gateway connection, internal to the framework: only `chapterjs dev`
+ * drives it (login, intents, presence, shutdown). User code gets its
+ * read-only `client`.
+ */
+export declare class Gateway extends EventEmitter {
+    #private;
+    readonly rest: RestClient;
+    /** What handlers receive, see `Client`. */
+    readonly client: Client;
+    /** The bot's user, set once connected. */
+    user: User | null;
+    applicationId: string | null;
+    /** Ids of the guilds the bot is in, as sent in READY. */
+    guildIds: Set<string>;
+    constructor(options: GatewayOptions);
+    /** Connects to the gateway and resolves once the bot is ready. */
+    login(): Promise<User>;
+    /** Bitfield of the gateway intents of the current session. */
+    get intents(): number;
+    /**
+     * Changes the gateway intents. Intents are only sent when identifying, so a
+     * connected client starts a new session (READY is dispatched again).
+     */
+    setIntents(intents: number): void;
+    /** Updates the bot's status and activity, e.g. `{ activity: { type: 'playing', name: 'Minecraft' } }`. */
+    setPresence(presence: Presence): void;
+    /**
+     * Closes the connection. Resolves once Discord acknowledged the close, so the
+     * session ends right away instead of lingering online until it times out.
+     */
+    destroy(): Promise<void>;
+}

package/dist/discord/gateway.js

@@ -0,0 +1,320 @@
+import { EventEmitter } from 'node:events';
+import { API_VERSION, FATAL_CLOSE_CODES, GatewayCloseCodes, GatewayIntents, GatewayOpcodes, } from './constants.js';
+import { toGatewayPresence } from './presence.js';
+import { RestClient } from './rest.js';
+import { createClient } from './client.js';
+import { User } from '../structures/User.js';
+/** Error emitted with `fatal` when Discord closed the connection for good. */
+export class GatewayCloseError extends Error {
+    code;
+    constructor(message, 
+    /** https://docs.discord.com/developers/topics/opcodes-and-status-codes#gateway-gateway-close-event-codes */
+    code) {
+        super(message);
+        this.code = code;
+    }
+}
+/** Events that don't belong to any guild and must always go through. */
+const SYSTEM_EVENTS = new Set([
+    'READY',
+    'RESUMED',
+    'USER_UPDATE',
+    'RATE_LIMITED',
+]);
+/** Guild events carry the guild id in `id` instead of `guild_id`. */
+const GUILD_EVENTS = new Set(['GUILD_CREATE', 'GUILD_UPDATE', 'GUILD_DELETE']);
+/**
+ * Minimum delay between two presence updates. The gateway allows 120 events
+ * per minute per connection and disconnects apps going over it.
+ */
+const PRESENCE_UPDATE_INTERVAL = 5_000;
+/** Any non-1000/1001 close code keeps the session resumable. */
+const RECONNECT_CLOSE_CODE = 4000;
+/**
+ * The gateway connection, internal to the framework: only `chapterjs dev`
+ * drives it (login, intents, presence, shutdown). User code gets its
+ * read-only `client`.
+ */
+export class Gateway extends EventEmitter {
+    rest;
+    /** What handlers receive, see `Client`. */
+    client;
+    /** The bot's user, set once connected. */
+    user = null;
+    applicationId = null;
+    /** Ids of the guilds the bot is in, as sent in READY. */
+    guildIds = new Set();
+    #token;
+    #intents;
+    #devGuildId;
+    #dev;
+    #presence;
+    /** Last presence Discord received, to skip identical updates. */
+    #sentPresence = null;
+    #lastPresenceUpdate = 0;
+    #presenceTimeout = null;
+    #ws = null;
+    #gatewayUrl = '';
+    #resumeGatewayUrl = null;
+    #sessionId = null;
+    #sequence = null;
+    #heartbeatTimeout = null;
+    #heartbeatInterval = null;
+    #heartbeatAcked = true;
+    #destroyed = false;
+    constructor(options) {
+        super();
+        this.#token = options.token;
+        this.#intents = options.intents ?? GatewayIntents.Guilds;
+        this.#devGuildId = options.devGuildId ?? null;
+        this.#dev = options.dev ?? false;
+        this.#presence = options.presence
+            ? toGatewayPresence(options.presence)
+            : null;
+        this.rest = new RestClient(this.#token);
+        this.client = createClient(this);
+    }
+    /** Connects to the gateway and resolves once the bot is ready. */
+    async login() {
+        // https://docs.discord.com/developers/events/gateway#get-gateway-bot
+        const { url } = await this.rest.get('/gateway/bot');
+        this.#gatewayUrl = url;
+        return new Promise((resolve, reject) => {
+            const onReady = (user) => {
+                this.off('fatal', onFatal);
+                resolve(user);
+            };
+            const onFatal = (error) => {
+                this.off('ready', onReady);
+                reject(error);
+            };
+            this.once('ready', onReady);
+            this.once('fatal', onFatal);
+            this.#connect(url);
+        });
+    }
+    /** Bitfield of the gateway intents of the current session. */
+    get intents() {
+        return this.#intents;
+    }
+    /**
+     * Changes the gateway intents. Intents are only sent when identifying, so a
+     * connected client starts a new session (READY is dispatched again).
+     */
+    setIntents(intents) {
+        if (intents === this.#intents)
+            return;
+        this.#intents = intents;
+        if (this.#ws)
+            this.#reconnect(false);
+    }
+    /** Updates the bot's status and activity, e.g. `{ activity: { type: 'playing', name: 'Minecraft' } }`. */
+    setPresence(presence) {
+        this.#presence = toGatewayPresence(presence);
+        this.#flushPresence();
+    }
+    /** Sends the latest presence, at most once every `PRESENCE_UPDATE_INTERVAL`. */
+    #flushPresence() {
+        if (!this.#sessionId || this.#presenceTimeout)
+            return;
+        const wait = this.#lastPresenceUpdate + PRESENCE_UPDATE_INTERVAL - Date.now();
+        if (wait > 0) {
+            this.#presenceTimeout = setTimeout(() => {
+                this.#presenceTimeout = null;
+                this.#flushPresence();
+            }, wait);
+            return;
+        }
+        const presence = JSON.stringify(this.#presence);
+        if (presence === this.#sentPresence)
+            return;
+        if (this.#send(GatewayOpcodes.PresenceUpdate, this.#presence)) {
+            this.#sentPresence = presence;
+            this.#lastPresenceUpdate = Date.now();
+            this.emit('presenceUpdate', this.#presence);
+        }
+    }
+    /**
+     * Closes the connection. Resolves once Discord acknowledged the close, so the
+     * session ends right away instead of lingering online until it times out.
+     */
+    destroy() {
+        this.#destroyed = true;
+        this.#stopHeartbeat();
+        if (this.#presenceTimeout)
+            clearTimeout(this.#presenceTimeout);
+        const ws = this.#ws;
+        this.#ws = null;
+        if (!ws || ws.readyState === WebSocket.CLOSED)
+            return Promise.resolve();
+        return new Promise(resolve => {
+            const timeout = setTimeout(resolve, 1000);
+            ws.addEventListener('close', () => {
+                clearTimeout(timeout);
+                resolve();
+            });
+            ws.close(1000);
+        });
+    }
+    #connect(baseUrl) {
+        const ws = new WebSocket(`${baseUrl}/?v=${API_VERSION}&encoding=json`);
+        this.#ws = ws;
+        ws.addEventListener('message', event => {
+            if (ws !== this.#ws)
+                return;
+            this.#onPayload(JSON.parse(String(event.data)));
+        });
+        ws.addEventListener('close', event => {
+            if (ws !== this.#ws)
+                return;
+            this.#onClose(event.code);
+        });
+    }
+    #send(op, d) {
+        if (this.#ws?.readyState !== WebSocket.OPEN)
+            return false;
+        this.#ws.send(JSON.stringify({ op, d }));
+        return true;
+    }
+    #onPayload(payload) {
+        if (payload.s !== null)
+            this.#sequence = payload.s;
+        switch (payload.op) {
+            case GatewayOpcodes.Hello:
+                this.#startHeartbeat(payload.d.heartbeat_interval);
+                if (this.#sessionId)
+                    this.#resume();
+                else
+                    this.#identify();
+                break;
+            case GatewayOpcodes.Heartbeat:
+                this.#heartbeat();
+                break;
+            case GatewayOpcodes.HeartbeatAck:
+                this.#heartbeatAcked = true;
+                break;
+            case GatewayOpcodes.Reconnect:
+                this.#reconnect(true);
+                break;
+            case GatewayOpcodes.InvalidSession:
+                // d tells whether the session can be resumed; wait 1-5s before re-identifying
+                if (payload.d)
+                    this.#reconnect(true);
+                else
+                    setTimeout(() => this.#reconnect(false), 1000 + Math.random() * 4000);
+                break;
+            case GatewayOpcodes.Dispatch:
+                this.#onDispatch(payload.t, payload.d);
+                break;
+        }
+    }
+    #onDispatch(event, data) {
+        if (event === 'READY') {
+            this.#sessionId = data.session_id;
+            this.#resumeGatewayUrl = data.resume_gateway_url;
+            this.user = new User(this.client, data.user);
+            this.applicationId = data.application.id;
+            this.guildIds = new Set(data.guilds.map((guild) => guild.id));
+            this.emit('ready', this.user);
+        }
+        else if (event === 'RESUMED') {
+            // An update may have been dropped while disconnected
+            this.#flushPresence();
+            this.emit('resumed');
+        }
+        if (this.#shouldDispatch(event, data))
+            this.emit('dispatch', event, data);
+    }
+    #shouldDispatch(event, data) {
+        if (!this.#devGuildId || SYSTEM_EVENTS.has(event))
+            return true;
+        const guildId = GUILD_EVENTS.has(event)
+            ? data?.id
+            : data?.guild_id;
+        // In dev, events without a guild (DMs) are left to the production process
+        return this.#dev
+            ? guildId === this.#devGuildId
+            : guildId !== this.#devGuildId;
+    }
+    // https://docs.discord.com/developers/events/gateway#identifying
+    #identify() {
+        this.#send(GatewayOpcodes.Identify, {
+            token: this.#token,
+            intents: this.#intents,
+            properties: {
+                os: process.platform,
+                browser: 'chapterjs',
+                device: 'chapterjs',
+            },
+            ...(this.#presence && { presence: this.#presence }),
+        });
+        this.#sentPresence = JSON.stringify(this.#presence);
+    }
+    // https://docs.discord.com/developers/events/gateway#resuming
+    #resume() {
+        this.#send(GatewayOpcodes.Resume, {
+            token: this.#token,
+            session_id: this.#sessionId,
+            seq: this.#sequence,
+        });
+    }
+    // https://docs.discord.com/developers/events/gateway#sending-heartbeats
+    #startHeartbeat(interval) {
+        this.#stopHeartbeat();
+        this.#heartbeatAcked = true;
+        this.#heartbeatTimeout = setTimeout(() => {
+            this.#heartbeat();
+            this.#heartbeatInterval = setInterval(() => this.#heartbeat(), interval);
+        }, interval * Math.random());
+    }
+    #stopHeartbeat() {
+        if (this.#heartbeatTimeout)
+            clearTimeout(this.#heartbeatTimeout);
+        if (this.#heartbeatInterval)
+            clearInterval(this.#heartbeatInterval);
+        this.#heartbeatTimeout = this.#heartbeatInterval = null;
+    }
+    #heartbeat() {
+        if (!this.#heartbeatAcked) {
+            // No ACK since the last heartbeat: the connection is zombied
+            this.#reconnect(true);
+            return;
+        }
+        this.#heartbeatAcked = false;
+        this.#send(GatewayOpcodes.Heartbeat, this.#sequence);
+    }
+    #reconnect(resume) {
+        if (this.#destroyed)
+            return;
+        this.#stopHeartbeat();
+        if (!resume)
+            this.#resetSession();
+        const previous = this.#ws;
+        this.#ws = null;
+        // https://docs.discord.com/developers/events/gateway#initiating-a-disconnect
+        // 1000 ends the session right away, so it doesn't linger next to the new one
+        previous?.close(resume ? RECONNECT_CLOSE_CODE : 1000);
+        this.#connect(this.#sessionId && this.#resumeGatewayUrl
+            ? this.#resumeGatewayUrl
+            : this.#gatewayUrl);
+    }
+    #resetSession() {
+        this.#sessionId = null;
+        this.#resumeGatewayUrl = null;
+        this.#sequence = null;
+    }
+    #onClose(code) {
+        this.#stopHeartbeat();
+        if (this.#destroyed)
+            return;
+        const fatal = FATAL_CLOSE_CODES[code];
+        if (fatal) {
+            this.#ws = null;
+            this.emit('fatal', new GatewayCloseError(`${fatal} (close code ${code})`, code));
+            return;
+        }
+        const resumable = code !== GatewayCloseCodes.InvalidSeq &&
+            code !== GatewayCloseCodes.SessionTimedOut;
+        setTimeout(() => this.#reconnect(resumable), 1000);
+    }
+}