minecraft-toolkit 0.1.1 → 0.1.3

package/README.md

@@ -128,6 +128,50 @@ const blockedServer = await fetchBlockedServers(); // no token required
 
 `validateGiftCode` returns `true`/`false` for 200/404 responses without throwing.
 
+## Server Status Helpers
+
+Probe Java and Bedrock servers without bringing your own RakNet/TCP logic.
+
+```ts
+import {
+  fetchServerStatus,
+  fetchJavaServerStatus,
+  fetchBedrockServerStatus,
+} from "minecraft-toolkit";
+
+const javaStatus = await fetchJavaServerStatus({ host: "mc.hypixel.net", port: 25565 });
+const bedrockStatus = await fetchBedrockServerStatus({ host: "play.example.net", port: 19132 });
+
+// fetchServerStatus picks the right probe based on the `edition` field
+const autoStatus = await fetchServerStatus({ host: "my.realm.net", edition: "bedrock" });
+
+console.log(javaStatus.players.online, bedrockStatus.motd.text);
+```
+
+Both helpers normalize MOTD text, favicon/Base64 icons, latency, and version info. Errors surface as
+`MinecraftToolkitError` with contextual status codes.
+
+## Minecraft Formatting Renderer
+
+Convert legacy `§` or `&` codes into safe HTML fragments or CSS class spans.
+
+```ts
+import { toHTML, generateCSS, stripCodes, hasCodes, convertPrefix } from "minecraft-toolkit";
+
+const motd = "§aWelcome §lHeroes§r!";
+
+const inline = toHTML(motd); // <span style="color: #55ff55">Welcome ...</span>
+
+const classes = toHTML(motd, { mode: "class", classPrefix: "mc" });
+const css = generateCSS(); // drop into a <style> tag
+
+stripCodes(motd); // "Welcome Heroes!"
+hasCodes(motd); // true
+convertPrefix("&aHi", "toSection"); // "§aHi"
+```
+
+`getMaps()` exposes the color and format metadata if you want to build custom renderers.
+
 ## License
 
 Published under the [MIT](https://github.com/26bz/minecraft-toolkit/blob/main/LICENSE) license.

package/index.d.ts

@@ -0,0 +1,213 @@
+import type { H3 } from "h3";
+
+export interface SkinTexture {
+  url: string;
+  metadata?: {
+    model?: "default" | "slim";
+  };
+}
+
+export interface CapeTexture {
+  url: string;
+}
+
+export interface PlayerProfile {
+  id: string;
+  name: string;
+  profile: Record<string, unknown>;
+  textures: Record<string, unknown>;
+  skin: SkinTexture | null;
+  cape: CapeTexture | null;
+}
+
+export interface PlayerSkin {
+  id: string;
+  name: string;
+  skin: SkinTexture | null;
+  cape: CapeTexture | null;
+}
+
+export interface PlayerSummary {
+  id: string;
+  name: string;
+  skinUrl: string | null;
+  capeUrl: string | null;
+}
+
+export interface BatchResult {
+  username: string;
+  profile?: PlayerProfile;
+  error?: unknown;
+}
+
+export interface BatchOptions {
+  delayMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface SkinMetadataResult {
+  id: string;
+  name: string;
+  skin: SkinTexture | null;
+  cape: CapeTexture | null;
+  hasCape: boolean;
+  dominantColor: string | null;
+}
+
+export function fetchPlayerProfile(username: string): Promise<PlayerProfile>;
+export function fetchPlayerSkin(username: string): Promise<PlayerSkin>;
+export function fetchPlayerUUID(username: string): Promise<{ id: string; name: string }>;
+export function fetchUsernameByUUID(uuid: string): Promise<{ id: string; name: string }>;
+export function fetchNameHistory(uuid: string): Promise<{ name: string; changedAt: Date | null }[]>;
+export function fetchPlayers(usernames: string[], options?: BatchOptions): Promise<BatchResult[]>;
+export function fetchPlayerSummary(username: string): Promise<PlayerSummary>;
+export function playerExists(username: string): Promise<boolean>;
+export function hasSkinChanged(profileA: PlayerProfile, profileB: PlayerProfile): boolean;
+export function fetchSkinMetadata(
+  username: string,
+  options?: {
+    dominantColor?: boolean;
+    sampleRegion?: { x?: number; y?: number; width?: number; height?: number };
+  },
+): Promise<SkinMetadataResult>;
+export function fetchSkinDominantColor(
+  url: string,
+  region?: { x?: number; y?: number; width?: number; height?: number },
+): Promise<string | null>;
+export function resolvePlayer(input: string): Promise<PlayerSkin>;
+
+export function isValidUsername(username: string): boolean;
+export function isUUID(value: string): boolean;
+export function normalizeUUID(uuid: string): string;
+export function uuidWithDashes(uuid: string): string;
+export function uuidWithoutDashes(uuid: string): string;
+
+export type FormattingMode = "inline" | "class";
+
+export interface FormattingOptions {
+  mode?: FormattingMode;
+  classPrefix?: string;
+  animationName?: string;
+  obfuscatedSpeedMs?: number;
+  escapeHtml?: boolean;
+}
+
+export interface FormattingColorMeta {
+  name: string;
+  classSuffix: string;
+  hex: string;
+}
+
+export interface FormattingFormatMeta {
+  name: string;
+  classSuffix: string;
+}
+
+export interface FormattingMaps {
+  colors: Record<string, FormattingColorMeta>;
+  formats: Record<string, FormattingFormatMeta>;
+}
+
+export function toHTML(input: string, options?: FormattingOptions): string;
+export function stripCodes(input: string): string;
+export function generateCSS(options?: FormattingOptions): string;
+export function hasCodes(input: string): boolean;
+export function convertPrefix(input: string, direction?: "toSection" | "toAmpersand"): string;
+export function getMaps(): FormattingMaps;
+
+export function getSkinURL(profile: PlayerProfile | PlayerSkin): string | null;
+export function getCapeURL(profile: PlayerProfile | PlayerSkin): string | null;
+export function getSkinModel(profile: PlayerProfile | PlayerSkin): "default" | "slim";
+export function extractTextureHash(url: string | null): string | null;
+
+export type ServerEdition = "java" | "bedrock" | "auto";
+
+export interface JavaServerStatusOptions {
+  port?: number;
+  timeoutMs?: number;
+  protocolVersion?: number;
+}
+
+export interface BedrockServerStatusOptions {
+  port?: number;
+  timeoutMs?: number;
+}
+
+export interface ServerStatusOptions extends JavaServerStatusOptions {
+  edition?: ServerEdition;
+  type?: ServerEdition;
+}
+
+export interface JavaServerStatus {
+  edition: "java";
+  online: boolean;
+  host: string;
+  port: number;
+  version: {
+    name?: string | null;
+    protocol?: number | null;
+  } | null;
+  players: {
+    max?: number | null;
+    online?: number | null;
+    sample?: Array<{ name: string; id: string }>;
+  } | null;
+  motd: string | null;
+  favicon: string | null;
+  latencyMs: number | null;
+  raw: Record<string, unknown>;
+}
+
+export interface BedrockServerStatus {
+  edition: "bedrock";
+  online: boolean;
+  host: string;
+  port: number;
+  motd: string;
+  version: {
+    protocol: number;
+    name: string;
+  };
+  players: {
+    online: number;
+    max: number;
+  };
+  serverId: string;
+  map: string;
+  gamemode: string;
+  ipv4Port: number;
+  ipv6Port: number | null;
+  raw: string;
+}
+
+export type ServerStatus = JavaServerStatus | BedrockServerStatus;
+
+export function fetchServerStatus(address: string, options?: ServerStatusOptions): Promise<ServerStatus>;
+export function fetchJavaServerStatus(
+  address: string,
+  options?: JavaServerStatusOptions,
+): Promise<JavaServerStatus>;
+export function fetchBedrockServerStatus(
+  address: string,
+  options?: BedrockServerStatusOptions,
+): Promise<BedrockServerStatus>;
+
+export interface PlayerHandlers {
+  profileHandler: any;
+  skinHandler: any;
+  summaryHandler: any;
+  uuidHandler: any;
+  resolverHandler: any;
+}
+
+export function createPlayerHandlers(): PlayerHandlers;
+export function createPlayerApp(options?: { app?: ConstructorParameters<typeof H3>[0] }): {
+  app: H3;
+  handlers: PlayerHandlers;
+};
+export const playerPlugin: (app: H3) => PlayerHandlers;
+
+export function fetchNameChangeInfo(accessToken: string): Promise<any>;
+export function checkNameAvailability(name: string, accessToken: string): Promise<any>;
+export function validateGiftCode(code: string, accessToken: string): Promise<boolean>;
+export function fetchBlockedServers(): Promise<string[]>;

package/index.js

@@ -20,3 +20,16 @@ export {
   fetchBlockedServers,
 } from "./src/player/account/index.js";
 export { createPlayerApp, createPlayerHandlers } from "./src/h3/routes.js";
+export {
+  fetchServerStatus,
+  fetchJavaServerStatus,
+  fetchBedrockServerStatus,
+} from "./src/server/status.js";
+export {
+  toHTML,
+  stripCodes,
+  generateCSS,
+  hasCodes,
+  convertPrefix,
+  getMaps,
+} from "./src/utils/formatting.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-toolkit",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Developer toolkit for working with Mojang Minecraft player data, skins, and utilities.",
   "keywords": [
     "minecraft",
@@ -30,6 +30,7 @@
   "files": [
     "src",
     "index.js",
+    "index.d.ts",
     "README.md",
     "LICENSE"
   ],
@@ -37,11 +38,21 @@
   "sideEffects": false,
   "types": "./index.d.ts",
   "exports": {
-    ".": "./index.js",
-    "./player": "./src/player/profile/index.js",
-    "./skin": "./src/player/skin.js",
-    "./identity": "./src/player/identity/index.js",
-    "./textures": "./src/player/textures.js"
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "scripts": {
+    "test": "vitest",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "prepare": "husky install",
+    "docs:sync": "automd"
   },
   "dependencies": {
     "h3": "2.0.1-rc.14",
@@ -61,14 +72,5 @@
   "engines": {
     "node": ">=18"
   },
-  "scripts": {
-    "test": "vitest",
-    "test:watch": "vitest watch",
-    "test:coverage": "vitest run --coverage",
-    "lint": "oxlint",
-    "lint:fix": "oxlint --fix",
-    "fmt": "oxfmt",
-    "fmt:check": "oxfmt --check",
-    "docs:sync": "automd"
-  }
-}
+  "packageManager": "pnpm@10.30.2"
+}

package/src/h3/routes.js

@@ -1,12 +1,23 @@
-import { H3, defineHandler, definePlugin } from "h3";
+import { H3, defineHandler, definePlugin, readBody, getQuery } from "h3";
 import { MinecraftToolkitError } from "../errors.js";
 import {
   fetchPlayerProfile,
   fetchPlayerSkin,
   fetchPlayerSummary,
   fetchPlayerUUID,
+  fetchPlayers,
+  fetchNameHistory,
+  playerExists,
 } from "../player/profile/index.js";
 import { resolvePlayer } from "../player/resolve.js";
+import {
+  fetchNameChangeInfo,
+  checkNameAvailability,
+  validateGiftCode,
+  fetchBlockedServers,
+} from "../player/account/index.js";
+import { fetchServerStatus } from "../server/status.js";
+import { normalizeAddress, validatePort } from "../utils/validation.js";
 
 function requireParam(event, key, message) {
   const value = event.context.params?.[key];
@@ -42,12 +53,89 @@ export function createPlayerHandlers() {
     return resolvePlayer(input);
   });
 
+  const nameHistoryHandler = defineHandler(async (event) => {
+    const uuid = requireParam(event, "uuid", "UUID parameter is required");
+    return fetchNameHistory(uuid);
+  });
+
+  const existsHandler = defineHandler(async (event) => {
+    const username = requireParam(event, "username", "Username parameter is required");
+    const exists = await playerExists(username);
+    return { username, exists };
+  });
+
+  const batchHandler = defineHandler(async (event) => {
+    const body = (await readBody(event)) ?? {};
+    const usernames = Array.isArray(body.usernames) ? body.usernames : null;
+    if (!usernames || usernames.length === 0) {
+      throw new MinecraftToolkitError("Body must include a non-empty usernames array", {
+        statusCode: 400,
+      });
+    }
+    const delayMs = typeof body.delayMs === "number" ? body.delayMs : undefined;
+    return fetchPlayers(usernames, { delayMs });
+  });
+
+  const nameChangeInfoHandler = defineHandler(async (event) => {
+    const token = requireAccessToken(event);
+    return fetchNameChangeInfo(token);
+  });
+
+  const nameAvailabilityHandler = defineHandler(async (event) => {
+    const name = requireParam(event, "name", "Name parameter is required");
+    const token = requireAccessToken(event);
+    return checkNameAvailability(name, token);
+  });
+
+  const giftCodeValidationHandler = defineHandler(async (event) => {
+    const token = requireAccessToken(event);
+    const body = (await readBody(event)) ?? {};
+    const code = typeof body.code === "string" ? body.code.trim() : "";
+    if (!code) {
+      throw new MinecraftToolkitError("Gift code is required", { statusCode: 400 });
+    }
+    const valid = await validateGiftCode(code, token);
+    return { code, valid };
+  });
+
+  const blockedServersHandler = defineHandler(async () => fetchBlockedServers());
+
+  const serverStatusHandler = defineHandler(async (event) => {
+    const address = normalizeAddress(
+      requireParam(event, "address", "Server address parameter is required"),
+    );
+    const query = getQuery(event);
+    const edition = typeof query.edition === "string" ? query.edition : undefined;
+    const port = typeof query.port === "string" ? validatePort(query.port) : undefined;
+    const timeoutMs =
+      typeof query.timeoutMs === "string" ? Number.parseInt(query.timeoutMs, 10) : undefined;
+    const protocolVersion =
+      typeof query.protocolVersion === "string"
+        ? Number.parseInt(query.protocolVersion, 10)
+        : undefined;
+
+    return fetchServerStatus(address, {
+      edition,
+      port,
+      timeoutMs,
+      protocolVersion,
+    });
+  });
+
   return {
     profileHandler,
     skinHandler,
     summaryHandler,
     uuidHandler,
     resolverHandler,
+    nameHistoryHandler,
+    existsHandler,
+    batchHandler,
+    nameChangeInfoHandler,
+    nameAvailabilityHandler,
+    giftCodeValidationHandler,
+    blockedServersHandler,
+    serverStatusHandler,
   };
 }
 
@@ -75,6 +163,38 @@ export function createPlayerApp(options = {}) {
     meta: { category: "player", resource: "resolve" },
   });
 
+  app.get("/player/:uuid/names", handlers.nameHistoryHandler, {
+    meta: { category: "player", resource: "name-history" },
+  });
+
+  app.get("/player/:username/exists", handlers.existsHandler, {
+    meta: { category: "player", resource: "exists" },
+  });
+
+  app.post("/players/batch", handlers.batchHandler, {
+    meta: { category: "player", resource: "batch" },
+  });
+
+  app.get("/account/namechange", handlers.nameChangeInfoHandler, {
+    meta: { category: "account", resource: "namechange" },
+  });
+
+  app.get("/account/name/:name/availability", handlers.nameAvailabilityHandler, {
+    meta: { category: "account", resource: "name-availability" },
+  });
+
+  app.post("/account/gift-code/validate", handlers.giftCodeValidationHandler, {
+    meta: { category: "account", resource: "gift-code" },
+  });
+
+  app.get("/account/blocked-servers", handlers.blockedServersHandler, {
+    meta: { category: "account", resource: "blocked-servers" },
+  });
+
+  app.get("/server/:address/status", handlers.serverStatusHandler, {
+    meta: { category: "server", resource: "status" },
+  });
+
   return { app, handlers };
 }
 
@@ -82,3 +202,17 @@ export const playerPlugin = definePlugin((app) => {
   const { handlers } = createPlayerApp({ app });
   return handlers;
 });
+
+function requireAccessToken(event) {
+  const header = event.req?.headers?.get?.("authorization") ?? "";
+  if (!header.toLowerCase().startsWith("bearer ")) {
+    throw new MinecraftToolkitError("Authorization header with Bearer token is required", {
+      statusCode: 401,
+    });
+  }
+  const token = header.slice(7).trim();
+  if (!token) {
+    throw new MinecraftToolkitError("Access token is required", { statusCode: 401 });
+  }
+  return token;
+}

package/src/server/bedrock/status.js

@@ -0,0 +1,147 @@
+import { createSocket } from "node:dgram";
+import { randomBytes } from "node:crypto";
+import { DEFAULT_BEDROCK_PORT, RAKNET_MAGIC } from "../../constants.js";
+import { MinecraftToolkitError } from "../../errors.js";
+import { normalizeAddress } from "../../utils/validation.js";
+import { resolveAddress } from "../../utils/network.js";
+import { resolveTimeout, makeError } from "../shared.js";
+
+export async function fetchBedrockServerStatus(address, options = {}) {
+  const normalized = normalizeAddress(address);
+  const { host, port } = resolveAddress(normalized, options.port, DEFAULT_BEDROCK_PORT);
+  const timeoutMs = resolveTimeout(options.timeoutMs);
+
+  return new Promise((resolve, reject) => {
+    const socket = createSocket("udp4");
+    let settled = false;
+
+    const timestamp = BigInt(Date.now());
+    const clientGuid = randomBytes(8);
+    const pingPacket = buildBedrockPingPacket(timestamp, clientGuid);
+
+    const timeout = setTimeout(() => {
+      rejectOnce(
+        new MinecraftToolkitError(`Timed out while querying Bedrock server ${host}:${port}`, {
+          statusCode: 504,
+        }),
+      );
+    }, timeoutMs);
+
+    function cleanup() {
+      clearTimeout(timeout);
+      socket.removeAllListeners();
+      socket.close();
+    }
+
+    function resolveOnce(value) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      resolve(value);
+    }
+
+    function rejectOnce(error) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      reject(
+        error instanceof MinecraftToolkitError
+          ? error
+          : makeError(`Unable to query Bedrock server ${host}:${port}`, error),
+      );
+    }
+
+    socket.once("error", (error) => {
+      rejectOnce(makeError(`Unable to reach Bedrock server ${host}:${port}`, error));
+    });
+
+    socket.on("message", (message) => {
+      try {
+        const status = parseBedrockStatus(message, host, port);
+        resolveOnce(status);
+      } catch (error) {
+        rejectOnce(
+          error instanceof MinecraftToolkitError
+            ? error
+            : makeError("Invalid Bedrock response", error),
+        );
+      }
+    });
+
+    socket.send(pingPacket, port, host, (error) => {
+      if (error) {
+        rejectOnce(makeError(`Failed to send Bedrock ping to ${host}:${port}`, error));
+      }
+    });
+  });
+}
+
+function buildBedrockPingPacket(timestamp, clientGuid) {
+  const buffer = Buffer.alloc(1 + 8 + 16 + 8);
+  let offset = 0;
+  buffer.writeUInt8(0x01, offset);
+  offset += 1;
+  buffer.writeBigInt64BE(timestamp, offset);
+  offset += 8;
+  RAKNET_MAGIC.copy(buffer, offset);
+  offset += RAKNET_MAGIC.length;
+  clientGuid.copy(buffer, offset);
+  return buffer;
+}
+
+function parseBedrockStatus(message, host, port) {
+  if (message.length < 35) {
+    throw new MinecraftToolkitError("Bedrock response too short");
+  }
+  const packetId = message.readUInt8(0);
+  if (packetId !== 0x1c) {
+    throw new MinecraftToolkitError(`Unexpected Bedrock packet id ${packetId}`);
+  }
+  const magic = message.subarray(17, 33);
+  if (!magic.equals(RAKNET_MAGIC)) {
+    throw new MinecraftToolkitError("Invalid RakNet magic");
+  }
+  const stringLength = message.readUInt16BE(33);
+  const totalLength = 35 + stringLength;
+  if (message.length < totalLength) {
+    throw new MinecraftToolkitError("Bedrock payload truncated");
+  }
+  const data = message.subarray(35, totalLength).toString("utf8");
+  const parts = data.split(";");
+  if (parts[0] !== "MCPE") {
+    throw new MinecraftToolkitError("Unexpected Bedrock edition identifier");
+  }
+
+  const protocol = Number.parseInt(parts[2] ?? "0", 10) || 0;
+  const versionName = parts[3] ?? "";
+  const onlinePlayers = Number.parseInt(parts[4] ?? "0", 10) || 0;
+  const maxPlayers = Number.parseInt(parts[5] ?? "0", 10) || 0;
+  const ipv4Port = Number.parseInt(parts[9] ?? `${port}`, 10) || port;
+  const ipv6Port = parts[10] ? Number.parseInt(parts[10], 10) || null : null;
+
+  return {
+    edition: "bedrock",
+    online: true,
+    host,
+    port,
+    motd: parts[1] ?? "",
+    version: {
+      protocol,
+      name: versionName,
+    },
+    players: {
+      online: onlinePlayers,
+      max: maxPlayers,
+    },
+    serverId: parts[6] ?? "",
+    map: parts[7] ?? "",
+    gamemode: parts[8] ?? "",
+    ipv4Port,
+    ipv6Port,
+    raw: data,
+  };
+}

package/src/server/java/status.js

@@ -0,0 +1,259 @@
+import { Socket } from "node:net";
+import { DEFAULT_JAVA_PORT, DEFAULT_PROTOCOL_VERSION } from "../../constants.js";
+import { MinecraftToolkitError } from "../../errors.js";
+import { normalizeAddress } from "../../utils/validation.js";
+import { resolveAddress } from "../../utils/network.js";
+import { resolveTimeout, makeError } from "../shared.js";
+
+export async function fetchJavaServerStatus(address, options = {}) {
+  const normalized = normalizeAddress(address);
+  const { host, port } = resolveAddress(normalized, options.port, DEFAULT_JAVA_PORT);
+  const timeoutMs = resolveTimeout(options.timeoutMs);
+  const protocolVersion = Number.isInteger(options.protocolVersion)
+    ? options.protocolVersion
+    : DEFAULT_PROTOCOL_VERSION;
+
+  return new Promise((resolve, reject) => {
+    const socket = new Socket();
+    socket.setNoDelay(true);
+
+    let buffer = Buffer.alloc(0);
+    let statusPayload = null;
+    let settled = false;
+    let pingStartedAt = 0;
+    let pingFallbackTimer;
+
+    const handshakePacket = buildHandshakePacket(host, port, protocolVersion);
+    const statusRequestPacket = buildStatusRequestPacket();
+
+    function cleanup() {
+      clearTimeout(pingFallbackTimer);
+      socket.removeAllListeners();
+      socket.destroy();
+    }
+
+    function resolveOnce(value) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      resolve(value);
+    }
+
+    function rejectOnce(error) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      reject(
+        error instanceof MinecraftToolkitError
+          ? error
+          : makeError(`Unable to query ${host}:${port}`, error),
+      );
+    }
+
+    function finish(latencyMs = null) {
+      resolveOnce(buildJavaStatus(statusPayload, host, port, latencyMs));
+    }
+
+    socket.setTimeout(timeoutMs, () => {
+      rejectOnce(
+        new MinecraftToolkitError(`Timed out while querying ${host}:${port}`, { statusCode: 504 }),
+      );
+    });
+
+    socket.on("error", (error) => {
+      rejectOnce(makeError(`Unable to reach ${host}:${port}`, error));
+    });
+
+    socket.on("close", () => {
+      if (!settled) {
+        if (statusPayload) {
+          finish(null);
+        } else {
+          rejectOnce(
+            new MinecraftToolkitError(
+              `Connection closed before status was received for ${host}:${port}`,
+            ),
+          );
+        }
+      }
+    });
+
+    socket.on("data", (chunk) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      processPackets();
+    });
+
+    socket.connect(port, host, () => {
+      try {
+        socket.write(handshakePacket);
+        socket.write(statusRequestPacket);
+      } catch (error) {
+        rejectOnce(makeError(`Failed to send status request to ${host}:${port}`, error));
+      }
+    });
+
+    function processPackets() {
+      while (true) {
+        const packet = extractPacket();
+        if (!packet) {
+          break;
+        }
+        const { id, payload } = packet;
+        if (id === 0 && !statusPayload) {
+          try {
+            statusPayload = parseStatusPayload(payload);
+          } catch (error) {
+            rejectOnce(makeError("Invalid status payload", error));
+            return;
+          }
+
+          try {
+            pingStartedAt = Date.now();
+            socket.write(buildPingPacket(pingStartedAt));
+            pingFallbackTimer = setTimeout(() => {
+              if (!settled) {
+                finish(null);
+              }
+            }, 200);
+          } catch {
+            finish(null);
+          }
+        } else if (id === 1 && statusPayload) {
+          const latency = Math.max(0, Date.now() - pingStartedAt);
+          finish(latency);
+        }
+      }
+    }
+
+    function extractPacket() {
+      try {
+        const { value: length, size: lengthSize } = decodeVarInt(buffer, 0);
+        if (buffer.length < lengthSize + length) {
+          return null;
+        }
+        const packetData = buffer.subarray(lengthSize, lengthSize + length);
+        buffer = buffer.subarray(lengthSize + length);
+        const { value: packetId, size: idSize } = decodeVarInt(packetData, 0);
+        const payload = packetData.subarray(idSize);
+        return { id: packetId, payload };
+      } catch {
+        return null;
+      }
+    }
+  });
+}
+
+function buildHandshakePacket(host, port, protocolVersion) {
+  const hostBytes = Buffer.from(host, "utf8");
+  const payload = Buffer.concat([
+    encodeVarInt(protocolVersion),
+    encodeVarInt(hostBytes.length),
+    hostBytes,
+    writePort(port),
+    encodeVarInt(1),
+  ]);
+  return createPacket(0, payload);
+}
+
+function buildStatusRequestPacket() {
+  return createPacket(0, Buffer.alloc(0));
+}
+
+function buildPingPacket(timestampMs) {
+  const payload = Buffer.alloc(8);
+  payload.writeBigInt64BE(BigInt(timestampMs));
+  return createPacket(1, payload);
+}
+
+function createPacket(packetId, payload) {
+  const payloadBuffer = Buffer.concat([encodeVarInt(packetId), payload]);
+  const lengthBuffer = encodeVarInt(payloadBuffer.length);
+  return Buffer.concat([lengthBuffer, payloadBuffer]);
+}
+
+function encodeVarInt(value) {
+  const bytes = [];
+  let current = value >>> 0;
+  do {
+    let byte = current & 0x7f;
+    current >>>= 7;
+    if (current !== 0) {
+      byte |= 0x80;
+    }
+    bytes.push(byte);
+  } while (current !== 0);
+  return Buffer.from(bytes);
+}
+
+function decodeVarInt(buffer, offset = 0) {
+  let numRead = 0;
+  let result = 0;
+  let byte = 0;
+  do {
+    if (offset + numRead >= buffer.length) {
+      throw new RangeError("VarInt extends beyond buffer");
+    }
+    byte = buffer[offset + numRead];
+    result |= (byte & 0x7f) << (7 * numRead);
+    numRead += 1;
+    if (numRead > 5) {
+      throw new RangeError("VarInt is too big");
+    }
+  } while ((byte & 0x80) === 0x80);
+  return { value: result, size: numRead };
+}
+
+function parseStatusPayload(payload) {
+  const { value: stringLength, size } = decodeVarInt(payload, 0);
+  const end = size + stringLength;
+  if (payload.length < end) {
+    throw new RangeError("Status string exceeds payload length");
+  }
+  const json = payload.subarray(size, end).toString("utf8");
+  return JSON.parse(json);
+}
+
+function buildJavaStatus(payload, host, port, latencyMs) {
+  return {
+    edition: "java",
+    online: true,
+    host,
+    port,
+    version: payload.version ?? null,
+    players: payload.players ?? null,
+    motd: stringifyDescription(payload.description) ?? null,
+    favicon: payload.favicon ?? null,
+    latencyMs,
+    raw: payload,
+  };
+}
+
+function stringifyDescription(description) {
+  if (!description) {
+    return null;
+  }
+  if (typeof description === "string") {
+    return description;
+  }
+  if (Array.isArray(description)) {
+    return description.map((entry) => stringifyDescription(entry) ?? "").join("");
+  }
+  if (typeof description === "object") {
+    const text = description.text ?? "";
+    const extra = Array.isArray(description.extra)
+      ? description.extra.map((entry) => stringifyDescription(entry) ?? "").join("")
+      : "";
+    return `${text}${extra}` || null;
+  }
+  return null;
+}
+
+function writePort(port) {
+  const buffer = Buffer.alloc(2);
+  buffer.writeUInt16BE(port, 0);
+  return buffer;
+}

package/src/server/shared.js

@@ -0,0 +1,13 @@
+import { DEFAULT_TIMEOUT_MS } from "../constants.js";
+import { MinecraftToolkitError } from "../errors.js";
+
+export function resolveTimeout(timeout) {
+  if (typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0) {
+    return timeout;
+  }
+  return DEFAULT_TIMEOUT_MS;
+}
+
+export function makeError(message, cause) {
+  return new MinecraftToolkitError(message, { cause });
+}

package/src/server/status.js

@@ -0,0 +1,41 @@
+import { fetchJavaServerStatus } from "./java/status.js";
+import { fetchBedrockServerStatus } from "./bedrock/status.js";
+import { MinecraftToolkitError } from "../errors.js";
+
+export { fetchJavaServerStatus } from "./java/status.js";
+export { fetchBedrockServerStatus } from "./bedrock/status.js";
+
+export async function fetchServerStatus(address, options = {}) {
+  const { edition, type, ...rest } = options;
+  const target =
+    (typeof (edition ?? type) === "string" ? (edition ?? type).trim().toLowerCase() : null) ||
+    "java";
+
+  if (target === "java") {
+    return fetchJavaServerStatus(address, rest);
+  }
+
+  if (target === "bedrock") {
+    return fetchBedrockServerStatus(address, rest);
+  }
+
+  if (target === "auto") {
+    let javaError;
+    try {
+      return await fetchJavaServerStatus(address, rest);
+    } catch (error) {
+      javaError = error;
+    }
+
+    return fetchBedrockServerStatus(address, rest).catch((bedrockError) => {
+      throw new MinecraftToolkitError("Unable to query server status", {
+        statusCode: bedrockError.statusCode ?? javaError?.statusCode ?? 500,
+        cause: bedrockError,
+      });
+    });
+  }
+
+  throw new MinecraftToolkitError('Edition must be "java", "bedrock", or "auto"', {
+    statusCode: 400,
+  });
+}

package/src/utils/formatting.js

@@ -0,0 +1,281 @@
+import { MinecraftToolkitError } from "../errors.js";
+
+const DEFAULT_CLASS_PREFIX = "mc";
+const DEFAULT_ANIMATION_NAME = "mc-obfuscated-flicker";
+const DEFAULT_OBFUSCATED_SPEED_MS = 110;
+
+const COLOR_CODES = freezeNested({
+  0: { name: "black", classSuffix: "black", hex: "#000000" },
+  1: { name: "dark_blue", classSuffix: "dark-blue", hex: "#0000aa" },
+  2: { name: "dark_green", classSuffix: "dark-green", hex: "#00aa00" },
+  3: { name: "dark_aqua", classSuffix: "dark-aqua", hex: "#00aaaa" },
+  4: { name: "dark_red", classSuffix: "dark-red", hex: "#aa0000" },
+  5: { name: "dark_purple", classSuffix: "dark-purple", hex: "#aa00aa" },
+  6: { name: "gold", classSuffix: "gold", hex: "#ffaa00" },
+  7: { name: "gray", classSuffix: "gray", hex: "#aaaaaa" },
+  8: { name: "dark_gray", classSuffix: "dark-gray", hex: "#555555" },
+  9: { name: "blue", classSuffix: "blue", hex: "#5555ff" },
+  a: { name: "green", classSuffix: "green", hex: "#55ff55" },
+  b: { name: "aqua", classSuffix: "aqua", hex: "#55ffff" },
+  c: { name: "red", classSuffix: "red", hex: "#ff5555" },
+  d: { name: "light_purple", classSuffix: "light-purple", hex: "#ff55ff" },
+  e: { name: "yellow", classSuffix: "yellow", hex: "#ffff55" },
+  f: { name: "white", classSuffix: "white", hex: "#ffffff" },
+  g: { name: "minecoin_gold", classSuffix: "minecoin-gold", hex: "#e1c158" },
+  h: { name: "material_quartz", classSuffix: "material-quartz", hex: "#ece6d8" },
+  i: { name: "material_iron", classSuffix: "material-iron", hex: "#cacaca" },
+  j: { name: "material_netherite", classSuffix: "material-netherite", hex: "#4b4946" },
+  n: { name: "material_redstone", classSuffix: "material-redstone", hex: "#b02e26" },
+  p: { name: "material_prismarine", classSuffix: "material-prismarine", hex: "#1ba19b" },
+  q: { name: "material_obsidian", classSuffix: "material-obsidian", hex: "#0b0b0b" },
+  s: { name: "material_crimson", classSuffix: "material-crimson", hex: "#a02c44" },
+  t: { name: "material_gold", classSuffix: "material-gold", hex: "#d8af48" },
+  u: { name: "material_emerald", classSuffix: "material-emerald", hex: "#30c67c" },
+  v: { name: "material_diamond", classSuffix: "material-diamond", hex: "#5be5e5" },
+});
+
+const FORMAT_CODES = freezeNested({
+  k: { name: "obfuscated", classSuffix: "obfuscated" },
+  l: { name: "bold", classSuffix: "bold" },
+  m: { name: "strikethrough", classSuffix: "strikethrough" },
+  n: { name: "underline", classSuffix: "underline" },
+  o: { name: "italic", classSuffix: "italic" },
+});
+
+const VALID_CODE_CHARS = new Set([...Object.keys(COLOR_CODES), ...Object.keys(FORMAT_CODES), "r"]);
+const COLOR_KEYS = new Set(Object.keys(COLOR_CODES));
+
+export function toHTML(input, options) {
+  const value = coerceInput(input);
+  if (!value) {
+    return "";
+  }
+
+  const resolved = resolveRenderOptions(options);
+  const segments = tokenize(value);
+
+  return segments.map((segment) => renderSegment(segment, resolved)).join("");
+}
+
+export function stripCodes(input) {
+  const value = coerceInput(input);
+  return value.replaceAll(/(?:§|&)[0-9a-fghijklmnpqrstuvr]/gi, "");
+}
+
+export function hasCodes(input) {
+  const value = coerceInput(input);
+  for (let i = 0; i < value.length - 1; i += 1) {
+    const candidate = value[i];
+    if (
+      (candidate === "§" || candidate === "&") &&
+      VALID_CODE_CHARS.has(value[i + 1]?.toLowerCase())
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function generateCSS(options) {
+  const resolved = resolveRenderOptions(options);
+  const lines = [];
+
+  lines.push(
+    `.${resolved.classPrefix}-segment { color: inherit; font-weight: inherit; font-style: inherit; }`,
+  );
+
+  Object.values(COLOR_CODES).forEach((entry) => {
+    lines.push(`.${resolved.classPrefix}-color-${entry.classSuffix} { color: ${entry.hex}; }`);
+  });
+
+  lines.push(`.${resolved.classPrefix}-format-bold { font-weight: 700; }`);
+  lines.push(`.${resolved.classPrefix}-format-italic { font-style: italic; }`);
+  lines.push(`.${resolved.classPrefix}-format-underline { text-decoration: underline; }`);
+  lines.push(`.${resolved.classPrefix}-format-strikethrough { text-decoration: line-through; }`);
+  lines.push(
+    `.${resolved.classPrefix}-format-underline.${resolved.classPrefix}-format-strikethrough { text-decoration: underline line-through; }`,
+  );
+  lines.push(
+    `.${resolved.classPrefix}-format-obfuscated { animation: ${resolved.animationName} ${resolved.obfuscatedSpeedMs}ms steps(10, end) infinite; display: inline-block; }`,
+  );
+
+  lines.push(
+    `@keyframes ${resolved.animationName} { 0%, 100% { opacity: 0.8; } 50% { opacity: 0.2; } }`,
+  );
+
+  return lines.join("\n");
+}
+
+export function convertPrefix(input, direction = "toSection") {
+  const value = coerceInput(input);
+
+  const normalized = direction?.toLowerCase();
+  if (normalized !== "tosection" && normalized !== "toampersand") {
+    throw new MinecraftToolkitError("direction must be either 'toSection' or 'toAmpersand'");
+  }
+
+  if (normalized === "toampersand") {
+    return value.replaceAll("§", "&");
+  }
+  return value.replaceAll("&", "§");
+}
+
+export function getMaps() {
+  return {
+    colors: COLOR_CODES,
+    formats: FORMAT_CODES,
+  };
+}
+
+function tokenize(input) {
+  const segments = [];
+  let color = null;
+  const formats = new Set();
+  let buffer = "";
+
+  for (let i = 0; i < input.length; i += 1) {
+    const char = input[i];
+    const next = input[i + 1]?.toLowerCase();
+
+    if ((char === "§" || char === "&") && next && VALID_CODE_CHARS.has(next)) {
+      if (buffer) {
+        segments.push({ text: buffer, color, formats: Array.from(formats) });
+        buffer = "";
+      }
+
+      if (COLOR_KEYS.has(next)) {
+        color = next;
+        formats.clear();
+      } else if (next === "r") {
+        color = null;
+        formats.clear();
+      } else {
+        formats.add(next);
+      }
+      i += 1;
+      continue;
+    }
+
+    buffer += char;
+  }
+
+  if (buffer) {
+    segments.push({ text: buffer, color, formats: Array.from(formats) });
+  }
+
+  return segments;
+}
+
+function renderSegment(segment, options) {
+  const safeText = options.escapeHtml ? escapeHtml(segment.text) : segment.text;
+  const needsStyling = segment.color || segment.formats.length;
+  if (!needsStyling) {
+    return safeText;
+  }
+
+  if (options.mode === "class") {
+    const classNames = buildClassNames(segment, options);
+    return classNames.length
+      ? `<span class="${classNames.join(" ")}">${safeText}</span>`
+      : safeText;
+  }
+
+  const inlineStyle = buildInlineStyle(segment, options);
+  return inlineStyle ? `<span style="${inlineStyle}">${safeText}</span>` : safeText;
+}
+
+function buildClassNames(segment, options) {
+  const classes = [`${options.classPrefix}-segment`];
+
+  if (segment.color) {
+    const colorMeta = COLOR_CODES[segment.color];
+    classes.push(`${options.classPrefix}-color-${colorMeta.classSuffix}`);
+  }
+
+  segment.formats.forEach((code) => {
+    const meta = FORMAT_CODES[code];
+    if (meta) {
+      classes.push(`${options.classPrefix}-format-${meta.classSuffix}`);
+    }
+  });
+
+  return classes;
+}
+
+function buildInlineStyle(segment, options) {
+  const declarations = [];
+  const textDecorations = new Set();
+
+  if (segment.color) {
+    declarations.push(`color: ${COLOR_CODES[segment.color].hex}`);
+  }
+
+  segment.formats.forEach((code) => {
+    switch (code) {
+      case "l":
+        declarations.push("font-weight: 700");
+        break;
+      case "o":
+        declarations.push("font-style: italic");
+        break;
+      case "m":
+        textDecorations.add("line-through");
+        break;
+      case "n":
+        textDecorations.add("underline");
+        break;
+      case "k":
+        declarations.push(
+          `animation: ${options.animationName} ${options.obfuscatedSpeedMs}ms steps(10, end) infinite`,
+        );
+        declarations.push("display: inline-block");
+        break;
+      default:
+        break;
+    }
+  });
+
+  if (textDecorations.size) {
+    declarations.push(`text-decoration: ${Array.from(textDecorations).join(" ")}`);
+  }
+
+  return declarations.join("; ");
+}
+
+function escapeHtml(value) {
+  return value
+    .replaceAll(/&/g, "&amp;")
+    .replaceAll(/</g, "&lt;")
+    .replaceAll(/>/g, "&gt;")
+    .replaceAll(/"/g, "&quot;")
+    .replaceAll(/'/g, "&#39;");
+}
+
+function coerceInput(input) {
+  if (input == null) {
+    return "";
+  }
+  return typeof input === "string" ? input : String(input);
+}
+
+function resolveRenderOptions(options = {}) {
+  const mode = options.mode === "class" ? "class" : "inline";
+  const classPrefix = options.classPrefix ?? DEFAULT_CLASS_PREFIX;
+  const animationName = options.animationName ?? DEFAULT_ANIMATION_NAME;
+  const obfuscatedSpeedMs = Number.isFinite(options.obfuscatedSpeedMs)
+    ? Number(options.obfuscatedSpeedMs)
+    : DEFAULT_OBFUSCATED_SPEED_MS;
+
+  return {
+    mode,
+    classPrefix,
+    animationName,
+    obfuscatedSpeedMs,
+    escapeHtml: options.escapeHtml !== false,
+  };
+}
+
+function freezeNested(map) {
+  Object.values(map).forEach((entry) => Object.freeze(entry));
+  return Object.freeze(map);
+}