Add Minecraft server lookup support to the lib

Lib/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "restfulmc",
-	"version": "1.0.8",
+	"version": "1.0.0",
 	"author": "Braydon (Rainnny) <braydonrainnny@gmail.com>",
 	"description": "A simple, yet useful RESTful API for Minecraft utilizing Springboot.",
 	"keywords": [

Lib/src/lib/restfulmc.ts

@@ -1,5 +1,8 @@
 import { ErrorResponse } from "../types/generic";
-import type { Player } from "../types/player";
+import type { CachedPlayer } from "../types/player";
+import { Platform } from "../types/server";
+import { CachedBedrockMinecraftServer } from "../types/server/bedrock-server";
+import { CachedJavaMinecraftServer } from "../types/server/java-server";
 
 const ENDPOINT = "https://mc.rainnny.club"; // The API endpoint to use
 
@@ -9,14 +12,44 @@ const ENDPOINT = "https://mc.rainnny.club"; // The API endpoint to use
  * @param query the query to search for the player by
  * @returns the promised player
  */
-export const getPlayer = (query: string): Promise<Player> => {
+export const getPlayer = (query: string): Promise<CachedPlayer> => {
 	return new Promise(async (resolve, reject) => {
 		const response: Response = await fetch(`${ENDPOINT}/player/${query}`); // Request the player
 		const json: any = await response.json();
 
 		// Resolve the player
 		if (response.ok) {
-			resolve(json as Player);
+			resolve(json as CachedPlayer);
+		} else {
+			reject(json as ErrorResponse); // The request failed
+		}
+	});
+};
+
+/**
+ * Get a Minecraft server by its platform and hostname.
+ *
+ * @param platform the platform of the server
+ * @param hostname the hostname of the server
+ * @returns the promised server
+ */
+export const getMinecraftServer = (
+	platform: Platform,
+	hostname: string
+): Promise<CachedJavaMinecraftServer | CachedBedrockMinecraftServer> => {
+	return new Promise(async (resolve, reject) => {
+		const response: Response = await fetch(
+			`${ENDPOINT}/server/${platform}/${hostname}`
+		); // Request the server
+		const json: any = await response.json();
+
+		// Resolve the server
+		if (response.ok) {
+			resolve(
+				platform === "java"
+					? (json as CachedJavaMinecraftServer)
+					: (json as CachedBedrockMinecraftServer)
+			);
 		} else {
 			reject(json as ErrorResponse); // The request failed
 		}

Lib/src/types/player.d.ts

@@ -1,4 +1,18 @@
-export type Player = {
+/**
+ * A cacheable {@link Player}.
+ */
+export interface CachedPlayer extends Player {
+	/**
+	 * The unix timestamp of when this
+	 * player was cached, -1 if not cached.
+	 */
+	cached: number;
+}
+
+/**
+ * A Minecraft player.
+ */
+type Player = {
 	/**
 	 * The unique id of this player.
 	 */

Lib/src/types/server.d.ts

@@ -0,0 +1,135 @@
+/**
+ * A model representing a Minecraft server.
+ */
+type MinecraftServer = {
+	/**
+	 * The hostname of this server.
+	 */
+	hostname: string;
+
+	/**
+	 * The IP address of this server, if resolved.
+	 */
+	ip?: string | undefined;
+
+	/**
+	 * The port of this server.
+	 */
+	port: number;
+
+	/**
+	 * The DNS records resolved for this server.
+	 */
+	records: DNSRecord[];
+
+	/**
+	 * The player counts of this server.
+	 */
+	players: Players;
+
+	/**
+	 * The MOTD of this server.
+	 */
+	motd: MOTD;
+};
+
+/**
+ * A representation of a DNS record.
+ */
+type DNSRecord = {
+	/**
+	 * The type of this record.
+	 */
+	type: RecordType;
+
+	/**
+	 * The TTL (Time To Live) of this record.
+	 */
+	ttl: number;
+};
+
+/**
+ * Player count data for a server.
+ */
+type Players = {
+	/**
+	 * The online players on this server.
+	 */
+	online: number;
+
+	/**
+	 * The maximum allowed players on this server.
+	 */
+	max: number;
+
+	/**
+	 * A sample of players on this server, undefined if no sample.
+	 */
+	sample?: PlayerSample[] | undefined;
+};
+
+/**
+ * A sample player.
+ */
+type PlayerSample = {
+	/**
+	 * The ID of this player.
+	 */
+	id: string;
+
+	/**
+	 * The name of this player.
+	 */
+	name: PlayerSampleName;
+};
+
+/**
+ * The name of a sample player.
+ */
+type PlayerSampleName = {
+	/**
+	 * The raw name.
+	 */
+	raw: string;
+
+	/**
+	 * The clean name (no color codes).
+	 */
+	clean: string;
+
+	/**
+	 * The HTML name.
+	 */
+	html: string;
+};
+
+/**
+ * The MOTD for a server.
+ */
+type MOTD = {
+	/**
+	 * The raw MOTD lines.
+	 */
+	raw: string[];
+
+	/**
+	 * The clean MOTD lines (no color codes).
+	 */
+	clean: string[];
+
+	/**
+	 * The HTML MOTD lines.
+	 */
+	html: string[];
+};
+
+/**
+ * A platform a Minecraft
+ * server can operate on.
+ */
+export type Platform = "java" | "bedrock";
+
+/**
+ * Types of a DNS record.
+ */
+type RecordType = "A" | "SRV";

Lib/src/types/server/bedrock-server.d.ts

@@ -0,0 +1,72 @@
+import { MinecraftServer } from "../server";
+
+/**
+ * A cacheable {@link BedrockMinecraftServer}.
+ */
+export interface CachedBedrockMinecraftServer extends BedrockMinecraftServer {
+	/**
+	 * The unix timestamp of when this
+	 * server was cached, -1 if not cached.
+	 */
+	cached: number;
+}
+
+/**
+ * A Bedrock edition {@link MinecraftServer}.
+ */
+interface BedrockMinecraftServer extends MinecraftServer {
+	/**
+	 * The ID of this server.
+	 */
+	id: string;
+
+	/**
+	 * The edition of this server.
+	 */
+	edition: Edition;
+
+	/**
+	 * The version information of this server.
+	 */
+	version: Version;
+
+	/**
+	 * The gamemode of this server.
+	 */
+	gamemode: GameMode;
+}
+
+/**
+ * The edition of a Bedrock server.
+ */
+type Edition = "MCPE" | "MCEE";
+
+/**
+ * Version information for a server.
+ */
+type Version = {
+	/**
+	 * The protocol version of the server.
+	 */
+	protocol: number;
+
+	/**
+	 * The version name of the server.
+	 */
+	name: string;
+};
+
+/**
+ * The gamemode of a server.
+ */
+type GameMode = {
+	/**
+	 * The name of this gamemode.
+	 */
+	name: string;
+
+	/**
+	 * The numeric of this gamemode, -1 if unknown.
+	 */
+	numericId: number;
+};

Lib/src/types/server/java-server.d.ts

@@ -0,0 +1,213 @@
+import { MinecraftServer } from "../server";
+
+/**
+ * A cacheable {@link JavaMinecraftServer}.
+ */
+export interface CachedJavaMinecraftServer extends JavaMinecraftServer {
+	/**
+	 * The unix timestamp of when this
+	 * server was cached, -1 if not cached.
+	 */
+	cached: number;
+}
+
+/**
+ * A Java edition {@link MinecraftServer}.
+ */
+interface JavaMinecraftServer extends MinecraftServer {
+	/**
+	 * The version information of this server.
+	 */
+	version: Version;
+
+	/**
+	 * The favicon of this server, undefined if none.
+	 */
+	favicon?: Favicon | undefined;
+
+	/**
+	 * The Forge mod information for this server, undefined if none.
+	 * <p>
+	 * This is for servers on 1.12 or below.
+	 * </p>
+	 */
+	modInfo?: ModInfo | undefined;
+
+	/**
+	 * The Forge mod information for this server, undefined if none.
+	 * <p>
+	 * This is for servers on 1.13 and above.
+	 * </p>
+	 */
+	forgeData?: ForgeData | undefined;
+
+	/**
+	 * Does this server preview chat?
+	 *
+	 * @see <a href="https://www.minecraft.net/es-mx/article/minecraft-snapshot-22w19a">This for more</a>
+	 */
+	previewsChat: boolean;
+
+	/**
+	 * Does this server enforce secure chat?
+	 */
+	enforcesSecureChat: boolean;
+
+	/**
+	 * Is this server preventing chat reports?
+	 */
+	preventsChatReports: boolean;
+
+	/**
+	 * Is this server on the list
+	 * of blocked servers by Mojang?
+	 *
+	 * @see <a href="https://wiki.vg/Mojang_API#Blocked_Servers">Mojang API</a>
+	 */
+	mojangBanned: boolean;
+}
+
+/**
+ * Version information for a server.
+ */
+type Version = {
+	/**
+	 * The version name of the server.
+	 */
+	name: string;
+
+	/**
+	 * The identified platform of the server, undefined if unknown.
+	 */
+	platform?: string | undefined;
+
+	/**
+	 * The protocol version of the server.
+	 */
+	protocol: number;
+
+	/**
+	 * A list of versions supported by this server.
+	 */
+	supportedVersions: number[];
+
+	/**
+	 * The name of the version for the protocol, undefined if unknown.
+	 */
+	protocolName?: string | undefined;
+};
+
+/**
+ * The favicon for a server.
+ */
+type Favicon = {
+	/**
+	 * The raw Base64 encoded favicon.
+	 */
+	base64: string;
+
+	/**
+	 * The URL to the favicon.
+	 */
+	url: string;
+};
+
+/**
+ * Forge mod information for a server.
+ * <p>
+ * This is for servers on 1.12 or below.
+ * </p>
+ */
+type ModInfo = {
+	/**
+	 * The type of modded server this is.
+	 */
+	type: string;
+
+	/**
+	 * The list of mods on this server, empty if none.
+	 */
+	mods: LegacyForgeMod[];
+};
+
+/**
+ * A legacy Forge mod for a server.
+ */
+type LegacyForgeMod = {
+	/**
+	 * The name of this mod.
+	 */
+	name: string;
+
+	/**
+	 * The version of this mod.
+	 */
+	version: string;
+};
+
+/**
+ * Forge information for a server.
+ * <p>
+ * This is for servers on 1.13 and above.
+ * </p>
+ */
+type ForgeData = {
+	/**
+	 * The list of channels on this server, empty if none.
+	 */
+	channels: ForgeChannel[];
+
+	/**
+	 * The list of mods on this server, empty if none.
+	 */
+	mods: ModernForgeMod[];
+
+	/**
+	 * The version of the FML network.
+	 */
+	fmlNetworkVersion: number;
+
+	/**
+	 * Are the channel and mod lists truncated?
+	 * <p>
+	 * Legacy versions see truncated lists, modern
+	 * versions ignore this truncated flag.
+	 * </p>
+	 */
+	truncated: boolean;
+};
+
+/**
+ * A Forge channel for a server.
+ */
+type ForgeChannel = {
+	/**
+	 * The name of this channel.
+	 */
+	name: string;
+
+	/**
+	 * The version of this channel.
+	 */
+	version: string;
+
+	/**
+	 * Whether this channel is required.
+	 */
+	required: boolean;
+};
+
+/**
+ * A modern Forge mod for a server.
+ */
+type ModernForgeMod = {
+	/**
+	 * The name of this mod.
+	 */
+	name: string;
+
+	/**
+	 * The marker for this mod.
+	 */
+	marker: string;
+};

Lib/test/index.test.ts

@@ -0,0 +1,23 @@
+import { describe, it } from "bun:test";
+import { getMinecraftServer, getPlayer } from "../src";
+import { CachedPlayer } from "../src/types/player";
+import { BedrockMinecraftServer } from "../src/types/server/bedrock-server";
+import { JavaMinecraftServer } from "../src/types/server/java-server";
+
+describe("player", () => {
+	it("Rainnny", async () => {
+		const player: CachedPlayer = await getPlayer("Rainnny");
+		console.log("player found", player.cached);
+	});
+});
+
+describe("server", () => {
+	it("java", async () => {
+		const server: JavaMinecraftServer | BedrockMinecraftServer =
+			await getMinecraftServer("java", "play.wildnetwork.net");
+
+		if ((server as BedrockMinecraftServer).id) {
+		}
+		console.log(server.ip);
+	});
+});