guilds.js 0.0.3 → 0.0.4

package/README.md

@@ -1,10 +1,10 @@
-<p align="center">
+<div align="center">
   <img
     alt="guilds.js Logo"
     width="85"
-    src="https://cdn.discordapp.com/attachments/1025091872198250597/1475481054004646100/guildslogo1.png?ex=699da450&is=699c52d0&hm=57ded16ddbafe1b094a44e78b1ae5ea2e3c647bd2b830c44354b6e11e6ecf0c5&"
+    src="https://cdn.discordapp.com/attachments/1025091872198250597/1475938039095103669/guilds.js.png?ex=699f4dea&is=699dfc6a&hm=a52d790f5cfa4820e4171126ed454f47ad32f94f5182d781ae08304bb2cdb77e&"
   />
-</p>
+</div>
 
 <div align="center">
   <a href="https://github.com/andrewdku/guilds.js">GitHub</a> | 
@@ -29,15 +29,18 @@ bun add guilds.js
 ## Example
 
 ```js
-import { Client } from "guilds.js";
+import { Client, GatewayIntents } from "guilds.js";
 
 const client = new Client({
     // https://discord.com/developers/applications
-    token: "bot token",
-
-    // client intents (as a number)
-    // example (guilds, guild messages, guild members):
-    intents: 515,
+    token: "TOKEN",
+
+    // client intents
+    intents: [
+        GatewayIntents.Guilds,
+        GatewayIntents.GuildMembers,
+        GatewayIntents.GuildMessages,
+    ],
 });
 
 client.once("ready", () => {
@@ -54,4 +57,4 @@ client.connect();
 
 # License
 
-guilds.js is licensed under the [Apache 2.0 license](LICENSE).
+Licensed under the [Apache License 2.0](LICENSE).

package/dist/index.cjs

@@ -1,7 +1,30 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
+//#region src/utils/color-convert.ts
+/**
+* Converts an integer color to a hex color string
+* @returns Hex string or null
+*/
+function colorIntToHex(color, addHashSymbol = false) {
+	if (color == null || !Number.isFinite(color)) return null;
+	const hex = (color >>> 0 & 16777215).toString(16).padStart(6, "0");
+	return addHashSymbol ? `#${hex}` : hex;
+}
+/**
+* Converts a hex color string to an integer color
+* @returns Color integer or null
+*/
+function hexToColorInt(hex) {
+	if (!hex) return null;
+	hex = hex.trim().replace(/^#/, "");
+	hex = hex.length === 3 ? hex.split("").map((c) => c + c).join("") : hex;
+	if (!/^[0-9a-fA-F]{6}$/.test(hex)) return null;
+	return parseInt(hex, 16);
+}
+
+//#endregion
 //#region src/utils/constants.ts
-const activityTypes = {
+const ActivityTypes = {
 	Competing: 5,
 	Custom: 4,
 	Listening: 2,
@@ -10,15 +33,30 @@ const activityTypes = {
 	Watching: 3
 };
 const baseApiUrl = "https://discord.com/api/v10";
-const errorCodes = [
-	"ClientIntentsError",
-	"ClientPropsError",
-	"ClientTokenError",
-	"DiscordAPIError",
-	"GatewayError",
-	"WebSocketError"
-];
-const opCodes = {
+const GatewayIntents = {
+	AutoModerationConfiguration: 1 << 20,
+	AutoModerationExecution: 1 << 21,
+	DirectMessagePolls: 1 << 25,
+	DirectMessageReactions: 8192,
+	DirectMessages: 4096,
+	DirectMessageTyping: 16384,
+	GuildExpressions: 8,
+	GuildIntegrations: 16,
+	GuildInvites: 64,
+	GuildMembers: 2,
+	GuildMessagePolls: 1 << 24,
+	GuildMessageReactions: 1024,
+	GuildMessages: 512,
+	GuildMessageTyping: 2048,
+	GuildModeration: 4,
+	GuildPresences: 256,
+	Guilds: 1,
+	GuildScheduledEvents: 65536,
+	GuildVoiceStates: 128,
+	GuildWebhooks: 32,
+	MessageContent: 32768
+};
+const GatewayOpcodes = {
 	Dispatch: 0,
 	Heartbeat: 1,
 	HeartbeatACK: 11,
@@ -33,15 +71,41 @@ const opCodes = {
 	VoiceStateUpdate: 3
 };
 
+//#endregion
+//#region src/utils/endpoints.ts
+/** Discord's API v10 endpoints */
+const Endpoints = {
+	gateway() {
+		return `${baseApiUrl}/gateway`;
+	},
+	gatewayBot() {
+		return `${Endpoints.gateway()}/bot`;
+	},
+	user(userId = "@me") {
+		return `${baseApiUrl}/users/${userId}`;
+	}
+};
+
 //#endregion
 //#region src/classes/EventHandler.ts
+/** Class representing a type-safe EventEmitter */
 var EventHandler = class {
 	#listeners = {};
+	/**
+	* Add a new event listener
+	* @param event Event name
+	* @param listener Listener callback
+	*/
 	on(event, listener) {
 		if (!this.#listeners[event]) this.#listeners[event] = [];
 		this.#listeners[event].push(listener);
 		return this;
 	}
+	/**
+	* Add a new event listener which only runs once
+	* @param event Event name
+	* @param listener Listener callback
+	*/
 	once(event, listener) {
 		const wrapped = (...args) => {
 			listener(...args);
@@ -50,11 +114,21 @@ var EventHandler = class {
 		this.on(event, wrapped);
 		return this;
 	}
+	/**
+	* Remove an event name
+	* @param event Event name
+	* @param listener Listener callback
+	*/
 	off(event, listener) {
 		if (!this.#listeners[event]) return this;
 		this.#listeners[event] = this.#listeners[event].filter((l) => l !== listener);
 		return this;
 	}
+	/**
+	* Emit an event
+	* @param event Event name
+	* @param args Event arguments
+	*/
 	async emit(event, ...args) {
 		if (!this.#listeners[event]) return false;
 		for (const listener of this.#listeners[event]) await listener(...args);
@@ -64,6 +138,7 @@ var EventHandler = class {
 
 //#endregion
 //#region src/classes/GuildsError.ts
+/** Class representing a library-related error */
 var GuildsError = class extends Error {
 	static name = "GuildsError";
 	scope;
@@ -78,161 +153,362 @@ var GuildsError = class extends Error {
 };
 
 //#endregion
-//#region src/classes/Routes.ts
-var Routes = class {
-	static gateway(bot = false) {
-		return `${baseApiUrl}/gateway${bot ? "/bot" : ""}`;
+//#region src/classes/RESTManager.ts
+/** Class representing a Discord REST API manager */
+var RESTManager = class {
+	#token;
+	/**
+	* Instantiate a new Discord API manager
+	* @param token Client token
+	*/
+	constructor(token) {
+		this.#token = token;
 	}
-	static user(userId = "@me") {
-		return `${baseApiUrl}/users/${userId}`;
+	/**
+	* Internal request method
+	* @param method HTTP request method
+	* @param endpoint Endpoint URI
+	* @param init Request data
+	*/
+	async #request(method, endpoint, init) {
+		const res = await fetch(endpoint, {
+			method,
+			headers: {
+				Authorization: this.#token,
+				"Content-Type": "application/json",
+				...init?.headers ?? {}
+			},
+			...init
+		});
+		if (!res.ok) throw new GuildsError(`${await res.text().catch(() => null) ?? res.statusText} (${res.status})`, "DiscordAPIError");
+		const json = await res.json().catch(() => null);
+		return Object.assign(res, { data: json });
+	}
+	/**
+	* Create a HTTP DELETE request
+	* @param endpoint Endpoint URI
+	* @param init Request data
+	*/
+	delete(endpoint, init) {
+		return this.#request("DELETE", endpoint, init);
+	}
+	/**
+	* Create a HTTP GET request
+	* @param endpoint Endpoint URI
+	* @param init Request data
+	*/
+	get(endpoint, init) {
+		return this.#request("GET", endpoint, init);
+	}
+	/**
+	* Create a HTTP PATCH request
+	* @param endpoint Endpoint URI
+	* @param init Request data
+	*/
+	patch(endpoint, init) {
+		return this.#request("PATCH", endpoint, init);
+	}
+	/**
+	* Create a HTTP POST request
+	* @param endpoint Endpoint URI
+	* @param init Request data
+	*/
+	post(endpoint, init) {
+		return this.#request("POST", endpoint, init);
+	}
+	/**
+	* Create a HTTP PUT request
+	* @param endpoint Endpoint URI
+	* @param init Request data
+	*/
+	put(endpoint, init) {
+		return this.#request("PUT", endpoint, init);
 	}
 };
 
 //#endregion
-//#region src/classes/DiscordAPI.ts
-var DiscordAPI = class {
-	#token;
-	constructor(token) {
-		if (!token) throw new GuildsError("Token must be provided", "DiscordAPIError");
-		this.#token = token;
+//#region src/classes/User.ts
+/**
+* Class representing a Discord user
+* @see https://docs.discord.com/developers/resources/user
+*/
+var User = class {
+	#client;
+	/** The user's banner color as a color integer */
+	accentColor;
+	/** The user's banner color as a hex color*/
+	accentColorHex;
+	/** The user's about me (client only) */
+	bio;
+	/** Whether the user is an application (bot) */
+	bot = false;
+	/** The user's discriminator, or "0" if they have none */
+	discriminator = "0";
+	/** The user's display name or bot's application name */
+	displayName;
+	/** The user's email (user clients only) */
+	email;
+	/** The user's ID snowflake */
+	id;
+	/** Whether the user has two factor authentication enabled (user clients only) */
+	mfaEnabled;
+	/** The data from Discord's API provided as-is */
+	rawData;
+	/** Whether the user is a Discord system account */
+	system = false;
+	/** The user's username (not to be confused with display name or tag) */
+	username;
+	/** Whether the user's email is verified (user clients only) */
+	verified;
+	constructor(client, data) {
+		if (!client || !(client instanceof Client)) throw new GuildsError("Invalid client provided", "DiscordAPIError");
+		this.#client = client;
+		this.accentColor = data.accent_color;
+		this.accentColorHex = colorIntToHex(data.accent_color || null) || null;
+		this.bio = data.bio ?? null;
+		this.bot = data.bot || false;
+		this.discriminator = data.discriminator || "0";
+		this.email = data.email;
+		this.displayName = data.global_name;
+		this.id = data.id;
+		this.mfaEnabled = data.mfa_enabled;
+		this.rawData = data;
+		this.system = data.system || false;
+		this.username = data.username;
+		this.verified = data.verified;
+		return this;
 	}
-	get token() {
-		return this.#token;
+	/** The client associated with this user */
+	get client() {
+		return this.#client;
 	}
-	async get(input, init) {
-		return await fetch(input, init);
+	/** Get the user's avatar as an image URL */
+	avatarURL(props) {
+		if (!props || !props.size || props.format && typeof props.format !== "string") throw new GuildsError("Invalid user avatar URL props provided", "DiscordAPIError");
+		const avatarHash = this.rawData.avatar;
+		if (!avatarHash) return null;
+		return `https://cdn.discordapp.com/avatars/${this.id}/${avatarHash}.${props.format || (avatarHash.startsWith("a_") ? "gif" : "png")}?size=${props.size}`;
+	}
+	/** `username#0000` or just `username` (if no discriminator) */
+	get tag() {
+		return this.discriminator == "0" ? this.username : `${this.username}#${this.discriminator}`;
+	}
+	/** User mention as a string, e.g. <@123456789> */
+	toString() {
+		return `<@${this.id}>`;
 	}
 };
 
 //#endregion
 //#region src/classes/Client.ts
+/** Class representing a Discord client */
 var Client = class extends EventHandler {
-	#api;
 	#token;
-	#heartbeatInterval;
-	#presence = {
+	/** Gateway heartbeat inteval */
+	heartbeatInterval;
+	/** Last received sequence number */
+	sequenceNumber = null;
+	/** Gateway session ID */
+	sessionId;
+	/** REST manager instance to handle API calls */
+	rest;
+	/** Client intents bitfield */
+	intents;
+	/** Whether the client is ready */
+	ready = false;
+	/** WebSocket connection */
+	ws;
+	/** Client user, or null if not ready */
+	user = null;
+	/** Current presence information */
+	presence = {
 		platform: "desktop",
 		status: "online",
 		activities: []
 	};
-	#sequenceNumber = null;
-	#sessionId;
-	#intents;
-	#ready = false;
-	#ws;
-	get token() {
-		return this.#token;
-	}
-	get intents() {
-		return this.#intents;
-	}
-	get heartbeatInterval() {
-		return this.#heartbeatInterval;
-	}
-	get presence() {
-		return this.#presence;
-	}
-	isReady() {
-		return this.#ready;
-	}
+	/**
+	* Instantiate a new Client
+	* @param props Client options
+	*/
 	constructor(props) {
 		super();
-		if (!props || typeof props !== "object") throw new GuildsError("Invalid client props were provided", "ClientPropsError");
-		if (!props.token || typeof props.token !== "string") throw new GuildsError("Invalid token was provided", "ClientTokenError");
-		if (!props.intents || typeof props.intents !== "number") throw new GuildsError("Invalid intents were provided", "ClientIntentsError");
+		if (!props || typeof props !== "object") throw new GuildsError("Invalid client props provided", "ClientPropsError");
+		if (!props.token || typeof props.token !== "string") throw new GuildsError("Invalid token provided", "ClientTokenError");
+		if (props.intents === null || props.intents === void 0 || Array.isArray(props.intents) == false && typeof props.intents !== "number") throw new GuildsError("Invalid intents provided", "ClientIntentsError");
 		if (props.presence) {
 			if (typeof props.presence !== "object") throw new GuildsError("Invalid client presence was provided", "ClientPropsError");
 			this.setPresence(props.presence);
 		}
 		this.#token = props.token.trim().toLowerCase().startsWith("bot ") ? props.token : `Bot ${props.token}`;
-		this.#intents = props.intents;
-		this.#api = new DiscordAPI(this.#token);
+		this.rest = new RESTManager(this.#token);
+		this.intents = parseIntents(props.intents);
 		return this;
 	}
+	/** The client's token */
+	get token() {
+		return this.#token;
+	}
+	/** Start the connection to Discord's gateway */
 	async connect() {
-		const res = await this.#api.get(Routes.gateway(true));
-		const userRes = await this.#api.get(Routes.user());
-		if (!res.ok || !userRes.ok || !res || !userRes) throw new GuildsError("Failed to connect to Discord", "GatewayError");
-		const data = await res.json();
-		this.#ws = new WebSocket(`${data.url}?v=10&encoding=json`);
-		this.#ws.onmessage = (event) => {
+		const res = await this.rest.get(Endpoints.gatewayBot());
+		const userRes = await this.rest.get(Endpoints.user());
+		if (!res.ok || !userRes.ok) throw new GuildsError("Failed to connect to Discord", "DiscordAPIError");
+		this.user = new User(this, userRes.data);
+		this.lastHeartbeatAck = true;
+		this.destroyed = false;
+		this.#connectWebSocket(res.data.url);
+		return this;
+	}
+	/** Initialize the WebSocket */
+	#connectWebSocket(url) {
+		if (this.destroyed) return;
+		this.ws = new WebSocket(`${url}?v=10&encoding=json`);
+		this.ws.onopen = () => this.emit("debug", "WebSocket connected");
+		this.ws.onerror = (error) => this.emit("error", `WebSocket error: ${error}`);
+		this.ws.onmessage = (event) => {
 			this.#handleGatewayEvent(JSON.parse(event.data.toString()));
 		};
-		return this;
+		this.ws.onclose = (event) => {
+			this.emit("debug", `WebSocket closed: ${event.reason} (${event.code})`);
+			if (!this.destroyed) setTimeout(() => this.#connectWebSocket(url), 3e3);
+		};
 	}
+	destroyed = false;
+	lastHeartbeatAck = true;
+	/** Handle incoming gateway events */
 	#handleGatewayEvent(payload) {
-		if (payload.s !== void 0 && payload.s !== null) this.#sequenceNumber = payload.s;
+		if (payload.s !== void 0 && payload.s !== null) this.sequenceNumber = payload.s;
 		switch (payload.op) {
-			case opCodes.Hello:
+			case GatewayOpcodes.Hello:
 				this.emit("debug", "Received Hello event");
-				this.#heartbeatInterval = setInterval(() => {
-					this.#ws?.send(JSON.stringify({
-						op: opCodes.Heartbeat,
-						d: this.#sequenceNumber
+				if (this.heartbeatInterval) clearInterval(this.heartbeatInterval);
+				this.lastHeartbeatAck = true;
+				this.heartbeatInterval = setInterval(() => {
+					if (!this.lastHeartbeatAck) {
+						this.emit("debug", "Heartbeat ACK failed, reconnecting...");
+						this.ws?.close(4e3, "Heartbeat failed");
+						return;
+					}
+					this.lastHeartbeatAck = false;
+					this.ws?.send(JSON.stringify({
+						op: GatewayOpcodes.Heartbeat,
+						d: this.sequenceNumber
 					}));
 				}, payload.d.heartbeat_interval);
-				this.emit("debug", "Identifying...");
-				this.#ws?.send(JSON.stringify({
-					op: opCodes.Identify,
-					d: {
-						token: this.#token,
-						intents: this.#intents,
-						presence: this.#presence,
-						properties: this.#presence.platform === "desktop" ? {
-							$os: "linux",
-							$browser: "guilds.js",
-							$device: "guilds.js"
-						} : {
-							$os: "Discord Android",
-							$browser: "Discord Android",
-							$device: "Discord Android"
+				if (this.sessionId) {
+					this.ws?.send(JSON.stringify({
+						op: GatewayOpcodes.Resume,
+						d: {
+							token: this.#token,
+							session_id: this.sessionId,
+							seq: this.sequenceNumber
 						}
-					}
-				}));
+					}));
+					this.emit("debug", "Resuming  session...");
+				} else {
+					this.ws?.send(JSON.stringify({
+						op: GatewayOpcodes.Identify,
+						d: {
+							token: this.#token,
+							intents: this.intents,
+							presence: this.presence,
+							properties: this.presence.platform === "desktop" ? {
+								$os: "linux",
+								$browser: "guilds.js",
+								$device: "guilds.js"
+							} : {
+								$os: "Discord Android",
+								$browser: "Discord Android",
+								$device: "Discord Android"
+							}
+						}
+					}));
+					this.emit("debug", "Identifying...");
+				}
+				break;
+			case GatewayOpcodes.HeartbeatACK:
+				this.lastHeartbeatAck = true;
 				break;
-			case opCodes.Dispatch:
+			case GatewayOpcodes.Dispatch:
 				if (payload.t !== "READY") break;
-				this.#sessionId = payload.d.session_id;
-				this.#ready = true;
+				this.sessionId = payload.d.session_id;
+				this.ready = true;
+				this.emit("debug", "Received Dispatch (Ready) event");
 				this.emit("ready", this);
 				break;
 		}
 	}
+	/** Update the client's user presence */
 	setPresence(presence) {
-		this.#presence = {
-			...this.#presence,
+		this.presence = {
+			...this.presence,
 			...presence
 		};
-		if (this.#ws) this.#ws.send(JSON.stringify({
-			op: opCodes.PresenceUpdate,
+		if (this.ws) this.ws.send(JSON.stringify({
+			op: GatewayOpcodes.PresenceUpdate,
 			d: {
-				status: this.#presence.status,
+				status: this.presence.status,
 				since: null,
 				afk: false,
-				activities: (this.#presence.activities ?? []).map((a) => ({
+				activities: (this.presence.activities ?? []).map((a) => ({
 					...a,
-					type: typeof a.type === "string" ? activityTypes[a.type] : a.type
+					type: typeof a.type === "string" ? ActivityTypes[a.type] : a.type
 				}))
 			}
 		}));
 		return this;
 	}
-	async disconnect() {
-		if (this.#heartbeatInterval) clearInterval(this.#heartbeatInterval);
-		if (this.#ws) {
-			this.#ws.close(1e3, "Client disconnected");
-			this.#ws = void 0;
-		}
+	/** Destroy the connection to Discord's gateway */
+	disconnect() {
+		if (this.heartbeatInterval) clearInterval(this.heartbeatInterval);
+		this.ws?.close(1e3, "Client disconnected");
+		this.ws = void 0;
 	}
 };
 
 //#endregion
+//#region src/utils/parse-intents.ts
+/**
+* Parse intents into bitfield
+* @param intents Intents resolvable
+* @returns Parsed intents as a bitfield
+*/
+function parseIntents(intents) {
+	if (typeof intents === "number") return intents;
+	else if (typeof intents === "string") {
+		const value = GatewayIntents[intents];
+		if (typeof value !== "number") throw new GuildsError("Invalid intents provided", "ClientIntentsError");
+		return value;
+	} else if (Array.isArray(intents)) {
+		let bitfield = 0;
+		for (const intent of intents) {
+			if (typeof intent === "number") {
+				bitfield |= intent;
+				continue;
+			}
+			if (typeof intent === "string") {
+				const value = GatewayIntents[intent];
+				if (typeof value !== "number") throw new GuildsError("Invalid intents provided", "ClientIntentsError");
+				bitfield |= value;
+				continue;
+			}
+			throw new GuildsError("Invalid intents provided", "ClientIntentsError");
+		}
+		return bitfield;
+	} else throw new GuildsError("Invalid intents provided", "ClientIntentsError");
+}
+
+//#endregion
+exports.ActivityTypes = ActivityTypes;
 exports.Client = Client;
-exports.DiscordAPI = DiscordAPI;
+exports.Endpoints = Endpoints;
 exports.EventHandler = EventHandler;
+exports.GatewayIntents = GatewayIntents;
+exports.GatewayOpcodes = GatewayOpcodes;
 exports.GuildsError = GuildsError;
-exports.Routes = Routes;
-exports.activityTypes = activityTypes;
+exports.RESTManager = RESTManager;
+exports.User = User;
 exports.baseApiUrl = baseApiUrl;
-exports.errorCodes = errorCodes;
-exports.opCodes = opCodes;
+exports.colorIntToHex = colorIntToHex;
+exports.hexToColorInt = hexToColorInt;
+exports.parseIntents = parseIntents;