@wlix/ceres 0.0.1

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Andrew (e60m5ss / wlix)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+<h1 align="center">@wlix/ceres</h1>
+
+> Node.js library for creating Discord bots
+
+## Installation
+
+```bash
+npm install @wlix/ceres
+# or
+yarn add @wlix/ceres
+# or
+pnpm add @wlix/ceres
+# or
+bun add @wlix/ceres
+```
+
+## Example
+
+```js
+import { Client, ClientIntents } from "@wlix/ceres";
+
+const client = new Client({
+    // replace TOKEN with the bot's token
+    // https://discord.com/developers/applications
+    token: "TOKEN",
+    intents: [
+        // include client intents here
+        ClientIntents.Guilds,
+        ClientIntents.GuildMembers,
+        ClientIntents.GuildMessages,
+    ],
+});
+
+client.once("ready", () => {
+    console.log("Client has been connected to Discord");
+});
+
+client.on("messageCreate", (message) => {
+    if (message.author.bot) return;
+
+    if (message.content === "!ping") {
+        message.reply("Pong!");
+    }
+});
+
+// in case any issues arise
+client.on("debug", console.log);
+client.on("error", console.log);
+
+// connect to Discord
+client.connect();
+```
+
+## Contributing
+
+Pull requests are always welcomed. For more major changes, please open an issue to discuss what you wish to change.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.cjs

@@ -0,0 +1,543 @@
+let discord_api_types_v10 = require("discord-api-types/v10");
+
+//#region src/structures/EventHandler.ts
+/**
+* Class representing a typed EventHandler supporting generics
+*/
+var EventHandler = class {
+	/**
+	* All stored listeners
+	*/
+	#listeners = {};
+	/**
+	* Listen for an event
+	* @param event Event name
+	* @param listener Callback once event is emitted
+	*/
+	on(event, listener) {
+		if (!this.#listeners[event]) this.#listeners[event] = [];
+		this.#listeners[event].push(listener);
+		return this;
+	}
+	/**
+	* Listen for an event once
+	* @param event Event name
+	* @param listener Callback once event is emitted
+	*/
+	once(event, listener) {
+		const wrapped = (...args) => {
+			listener(...args);
+			this.off(event, wrapped);
+		};
+		this.on(event, wrapped);
+		return this;
+	}
+	/**
+	* Remove a registered event listener
+	* @param event Event name
+	* @param listener Callback function to remove
+	*/
+	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
+	*/
+	emit(event, ...args) {
+		if (!this.#listeners[event]) return false;
+		for (const listener of this.#listeners[event]) listener(...args);
+		return true;
+	}
+};
+
+//#endregion
+//#region src/structures/Channel.ts
+/**
+* Class representing a base Channel
+*/
+var Channel = class {
+	/**
+	* The Client associated with this Channel
+	*/
+	client;
+	/**
+	* The Discord channel ID
+	*/
+	id;
+	/**
+	* The Discord channel name
+	*/
+	name;
+	/**
+	* The type of this channel
+	*/
+	type;
+	/**
+	* The ID of the guild this channel is in
+	*/
+	guildId;
+	/**
+	* Instantiate a new Channel (internal)
+	* @param client Associated client
+	* @param data API channel data
+	*/
+	constructor(client, data) {
+		this.client = client;
+		this.id = data.id;
+		this.type = data.type;
+		if ("guild_id" in data) this.guildId = data.guild_id ?? void 0;
+		if ("name" in data) this.name = data.name ?? void 0;
+	}
+	/**
+	* Whether this channel is a guild text channel, a direct message, or a guild announcement channel
+	*/
+	isText() {
+		return this.type === discord_api_types_v10.ChannelType.GuildText || this.type === discord_api_types_v10.ChannelType.DM || this.type === discord_api_types_v10.ChannelType.GuildAnnouncement;
+	}
+	/**
+	* Send a message in this channel
+	* @param props Message data
+	* @returns Created message object
+	*/
+	send(props) {
+		return this.client.createMessage(this.id, typeof props === "string" ? { content: props } : props);
+	}
+};
+
+//#endregion
+//#region src/utils/client-events.ts
+async function handleClientEvent(client, packet) {
+	const { t, d } = packet;
+	client.emit("debug", `[@wlix/ceres Client debug]: Received ${t} event`);
+	switch (t) {
+		case discord_api_types_v10.GatewayDispatchEvents.MessageCreate:
+			client.emit("messageCreate", new Message(client, await client.fetchChannel(d.channel_id), d));
+			break;
+		case discord_api_types_v10.GatewayDispatchEvents.Ready:
+			client.user = new User(client, d.user);
+			client.emit("ready", client);
+			break;
+	}
+}
+
+//#endregion
+//#region src/utils/intents.ts
+const ClientIntents = {
+	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
+};
+
+//#endregion
+//#region src/structures/Client.ts
+/**
+* Class representing a Client connecting to Discord's API
+* @extends EventHandler
+*/
+var Client = class Client extends EventHandler {
+	/**
+	* The URL to connect to when initializing the gateway
+	*/
+	static gatewayUrl = "wss://gateway.discord.gg/?v=10&encoding=json";
+	/**
+	* The URL to connect to when contacting the API
+	*/
+	static baseApiUrl = "https://discord.com/api/v10";
+	/**
+	* The client's intents
+	*/
+	intents;
+	/**
+	* Whether the client is ready
+	*/
+	ready = false;
+	/**
+	* The client's token
+	*/
+	token;
+	/**
+	* The client's user
+	*/
+	user = null;
+	/**
+	* A simple cache for Discord objects
+	*/
+	#cache = {
+		channels: /* @__PURE__ */ new Map(),
+		users: /* @__PURE__ */ new Map()
+	};
+	/**
+	* The client's presence
+	*/
+	#presence;
+	/**
+	* The client's heartbeat interval
+	*/
+	#heartbeatInterval;
+	/**
+	* The client's websocket
+	*/
+	#ws;
+	/**
+	* Instantiate a new Client
+	* @param options Client options
+	* @param options.token Client token
+	*/
+	constructor(options) {
+		super();
+		if (!options?.token) throw new Error("[@wlix/ceres Client]: Client token must be provided as a non-empty string");
+		if (!options?.intents) throw new Error("[@wlix/ceres Client]: Client intents must be provided");
+		this.token = options.token.toLowerCase().startsWith("bot ") ? options.token : "Bot " + options.token;
+		this.intents = options.intents.reduce((bitfield, i) => bitfield | i, 0);
+		if (options.presence) this.#presence = options.presence;
+	}
+	async #apiFetch(path, options) {
+		const res = await fetch(`${Client.baseApiUrl}${path}`, {
+			...options,
+			headers: {
+				Authorization: this.token,
+				"Content-Type": "application/json",
+				...options?.headers ?? {}
+			}
+		});
+		if (!res.ok) throw new Error(`[@wlix/ceres] Discord API error: ${res.status} ${res.statusText}`);
+		return res.json();
+	}
+	/**
+	* Handle incoming packets
+	* @param packet Packet data
+	*/
+	#handlePacket(packet) {
+		const { t, op, d, s } = packet;
+		if (op === 10) {
+			this.#heartbeatInterval = setInterval(() => {
+				this.#ws?.send(JSON.stringify({
+					op: discord_api_types_v10.GatewayOpcodes.Heartbeat,
+					d: s
+				}));
+			}, d.heartbeat_interval);
+			this.#ws?.send(JSON.stringify({
+				op: discord_api_types_v10.GatewayOpcodes.Identify,
+				d: {
+					token: this.token,
+					intents: this.intents,
+					properties: {
+						$os: "linux",
+						$browser: "@wlix/ceres",
+						$device: "@wlix/ceres"
+					},
+					presence: this.#presence ? {
+						status: this.#presence.status,
+						since: null,
+						afk: false,
+						activities: this.#presence.activities ?? []
+					} : {
+						status: "online",
+						since: null,
+						afk: false,
+						activities: []
+					}
+				}
+			}));
+		}
+		if (packet.t) handleClientEvent(this, packet);
+	}
+	/**
+	* Whether the client is ready
+	*/
+	isReady() {
+		return this.user !== null;
+	}
+	/**
+	* Returns the client's user presence
+	*/
+	get presence() {
+		return this.#presence ?? null;
+	}
+	/**
+	* Update the client's token (only when not connected)
+	* @param token New token
+	*/
+	setToken(token) {
+		if (this.#ws) throw new Error("[@wlix/ceres Client]: Cannot change token while connected, disconnect first");
+		if (!token || typeof token !== "string") throw new Error("[@wlix/ceres Client]: Client token must be provided as a non-empty string");
+		this.token = token.toLowerCase().startsWith("bot ") ? token : "Bot " + token;
+		this.emit("debug", "[@wlix/ceres Client debug]: Client token was updated");
+	}
+	/**
+	* Connects the Client to the Discord gateway
+	* @returns Client instance
+	*/
+	async connect() {
+		this.emit("debug", "[@wlix/ceres Client debug]: Connecting to Discord gateway");
+		this.#ws = new WebSocket(Client.gatewayUrl);
+		this.#ws.onopen = () => {
+			this.emit("debug", "[@wlix/ceres Client debug]: WebSocket has been opened");
+		};
+		this.#ws.onmessage = (message) => {
+			this.#handlePacket(JSON.parse(message.data));
+		};
+		this.#ws.onerror = (error) => {
+			this.emit("debug", `[@wlix/ceres Client debug]: WebSocket error: ${error}`);
+		};
+		return this;
+	}
+	/**
+	* Disconnects the client from the Discord gateway
+	*/
+	disconnect() {
+		if (this.#heartbeatInterval) {
+			clearInterval(this.#heartbeatInterval);
+			this.#heartbeatInterval = void 0;
+		}
+		if (this.#ws) {
+			this.#ws.close(1e3, "Client disconnect");
+			this.#ws = void 0;
+		}
+		this.emit("debug", "[@wlix/ceres Client debug]: Disconnected from Discord gateway");
+		this.emit("disconnect");
+	}
+	/**
+	* Fetch a Discord channel by ID
+	* @param id Channel ID
+	* @returns Channel object or null
+	*/
+	async fetchChannel(id) {
+		if (this.#cache.channels.has(id)) return this.#cache.channels.get(id);
+		try {
+			const channel = new Channel(this, await this.#apiFetch(`${discord_api_types_v10.Routes.channel(id)}`));
+			this.#cache.channels.set(id, channel);
+			return channel;
+		} catch (error) {
+			this.emit("error", error);
+			throw error;
+		}
+	}
+	/**
+	* Fetch a user by ID
+	* @param id User ID
+	* @returns User object or null
+	*/
+	async fetchUser(id) {
+		if (this.#cache.users.has(id)) return this.#cache.users.get(id);
+		try {
+			const user = new User(this, await this.#apiFetch(`${discord_api_types_v10.Routes.user(id)}`));
+			this.#cache.users.set(id, user);
+			return user;
+		} catch (error) {
+			this.emit("error", error);
+			throw error;
+		}
+	}
+	/**
+	* Sends a new message as the Client
+	* @returns Created message or null
+	*/
+	async createMessage(channelId, props) {
+		if (!this.isReady()) return null;
+		try {
+			const data = await this.#apiFetch(discord_api_types_v10.Routes.channelMessages(channelId), {
+				method: "POST",
+				body: typeof props === "string" ? JSON.stringify({ content: props }) : JSON.stringify({
+					content: props.content,
+					nonce: props.nonce,
+					tts: props.tts,
+					embeds: props.embeds,
+					allowed_mentions: props.allowedMentions,
+					message_reference: props.messageReference,
+					components: props.components,
+					sticker_ids: props.stickerIds,
+					attachments: props.attachments,
+					flags: props.flags,
+					enforce_nonce: props.enforceNonce
+				})
+			});
+			return new Message(this, await this.fetchChannel(data.channel_id), data);
+		} catch (error) {
+			this.emit("error", error);
+			throw error;
+		}
+	}
+	/**
+	* Update the client's user presence
+	* @param presence Presence data
+	*/
+	setPresence(presence) {
+		this.#presence = presence;
+		if (this.#ws) this.#ws.send(JSON.stringify({
+			op: discord_api_types_v10.GatewayOpcodes.PresenceUpdate,
+			d: {
+				status: presence.status,
+				since: null,
+				afk: false,
+				activities: []
+			}
+		}));
+	}
+};
+
+//#endregion
+//#region src/structures/Message.ts
+/**
+* Class representing a Message
+*/
+var Message = class {
+	/**
+	* The Client associated with this Message
+	*/
+	client;
+	/**
+	* The Discord message ID
+	*/
+	id;
+	/**
+	* The Discord message content
+	*/
+	content;
+	/**
+	* The User who sent this message
+	*/
+	author;
+	/**
+	* The channel where this message is
+	*/
+	channel;
+	/**
+	* The ID of the channel where this message is
+	*/
+	channelId;
+	/**
+	* A Date representing when this message was sent
+	*/
+	timestamp;
+	/**
+	* Instantiate a new Message (internal)
+	* @param client Associated client
+	* @param data API message data
+	*/
+	constructor(client, channel, data) {
+		this.client = client;
+		this.id = data.id;
+		this.content = data.content;
+		this.author = new User(client, data.author);
+		this.channelId = data.channel_id;
+		this.timestamp = new Date(data.timestamp);
+		this.channel = channel;
+	}
+	/**
+	* Reply to a message
+	* @param props Message reply props
+	* @returns Replied message
+	*/
+	async reply(props) {
+		return this.client.createMessage(this.channelId, typeof props === "string" ? {
+			content: props,
+			messageReference: { message_id: this.id }
+		} : {
+			...props,
+			messageReference: { message_id: this.id }
+		});
+	}
+};
+
+//#endregion
+//#region src/structures/User.ts
+/**
+* Class representing a User
+*/
+var User = class {
+	/**
+	* The Client associated with this User
+	*/
+	client;
+	/**
+	* The Discord user ID
+	*/
+	id;
+	/**
+	* The Discord user username
+	*/
+	username;
+	/**
+	* The Discord user's discriminator, or "0" if they have none
+	*/
+	discriminator = "0";
+	/**
+	* Whether this Discord user is a bot
+	*/
+	bot;
+	/**
+	* If the user has a discriminator (i.e., it's not "0"), returns username#discriminator
+	* Else, returns just the username
+	*/
+	get tag() {
+		return this.discriminator === "0" ? this.username : `${this.username}#${this.discriminator}`;
+	}
+	/**
+	* Represent the User as a mention (e.g., <@USERID>)
+	*/
+	toString() {
+		return `<@${this.id}>`;
+	}
+	/**
+	* Instantiate a new User (internal)
+	* @param client Associated client
+	* @param data API user data
+	*/
+	constructor(client, data) {
+		this.client = client;
+		this.id = data.id;
+		this.username = data.username;
+		this.discriminator = data.discriminator;
+		this.bot = data.bot ?? false;
+	}
+};
+
+//#endregion
+Object.defineProperty(exports, 'ActivityType', {
+  enumerable: true,
+  get: function () {
+    return discord_api_types_v10.ActivityType;
+  }
+});
+exports.Channel = Channel;
+Object.defineProperty(exports, 'ChannelType', {
+  enumerable: true,
+  get: function () {
+    return discord_api_types_v10.ChannelType;
+  }
+});
+exports.Client = Client;
+exports.ClientIntents = ClientIntents;
+exports.EventHandler = EventHandler;
+Object.defineProperty(exports, 'GatewayDispatchEvents', {
+  enumerable: true,
+  get: function () {
+    return discord_api_types_v10.GatewayDispatchEvents;
+  }
+});
+exports.Message = Message;
+exports.User = User;
+exports.handleClientEvent = handleClientEvent;