minecraft-toolkit 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 26bz https://26bz.com/
+
+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,182 @@
+# minecraft-toolkit
+
+<!-- automd:badges name="minecraft-toolkit" github="26bz/minecraft-toolkit" license -->
+
+[![npm version](https://img.shields.io/npm/v/minecraft-toolkit)](https://npmjs.com/package/minecraft-toolkit)
+[![npm downloads](https://img.shields.io/npm/dm/minecraft-toolkit)](https://npm.chart.dev/minecraft-toolkit)
+[![license](https://img.shields.io/github/license/26bz/minecraft-toolkit)](https://github.com/26bz/minecraft-toolkit/blob/main/LICENSE)
+
+<!-- /automd -->
+
+Lightweight Mojang player utilities (profile, skin, UUID) for Node, Vite, and edge projects.
+
+> This toolkit wraps Mojang APIs. Rate limits and availability still apply. Write endpoints (name change, skin upload) are not yet included.
+
+## Installation
+
+<!-- automd:pm-install name="minecraft-toolkit" -->
+
+```sh
+# ✨ Auto-detect
+npx nypm install minecraft-toolkit
+
+# npm
+npm install minecraft-toolkit
+
+# yarn
+yarn add minecraft-toolkit
+
+# pnpm
+pnpm install minecraft-toolkit
+
+# bun
+bun install minecraft-toolkit
+
+# deno
+deno install minecraft-toolkit
+```
+
+<!-- /automd -->
+
+## Core Helpers
+
+```ts
+import {
+  fetchPlayerProfile,
+  fetchPlayerSkin,
+  fetchPlayerUUID,
+  fetchPlayerSummary,
+  fetchNameHistory,
+  fetchPlayers,
+  resolvePlayer,
+  fetchSkinMetadata,
+} from "minecraft-toolkit";
+
+const profile = await fetchPlayerProfile("26bz");
+const summary = await fetchPlayerSummary("26bz");
+const skin = await fetchPlayerSkin("26bz");
+const uuid = await fetchPlayerUUID("26bz");
+const history = await fetchNameHistory("069a79f444e94726a5befca90e38aaf5");
+const batch = await fetchPlayers(["Notch", "26bz"], { delayMs: 50 });
+const resolved = await resolvePlayer("069a79f444e94726a5befca90e38aaf5");
+const skinMeta = await fetchSkinMetadata("26bz");
+```
+
+Helpers are HTTP-agnostic and run anywhere `fetch` exists (Node 18+, Bun, Workers). All errors surface as `MinecraftToolkitError`.
+
+## Texture & Identity Utilities
+
+```ts
+import {
+  isValidUsername,
+  isUUID,
+  normalizeUUID,
+  uuidWithDashes,
+  uuidWithoutDashes,
+  getSkinURL,
+  getCapeURL,
+  getSkinModel,
+  extractTextureHash,
+} from "minecraft-toolkit";
+
+isValidUsername("26bz"); // true
+uuidWithDashes("069a79f444e94726a5befca90e38aaf5");
+const skinUrl = getSkinURL(await fetchPlayerProfile("26bz"));
+const hash = extractTextureHash(skinUrl);
+const model = getSkinModel(skinUrl); // "slim" | "classic"
+```
+
+## Skin Metadata & Color Sampling
+
+```ts
+import { fetchSkinMetadata, computeSkinDominantColor } from "minecraft-toolkit";
+
+const meta = await fetchSkinMetadata("26bz", {
+  dominantColor: true,
+  sampleRegion: { x: 8, y: 8, width: 8, height: 8 },
+});
+
+console.log(meta.dominantColor); // e.g. "#f2d2a9"
+
+const accent = await computeSkinDominantColor(meta.skin.url, {
+  x: 40,
+  y: 8,
+  width: 8,
+  height: 8,
+});
+```
+
+## Account Helpers
+
+A valid Microsoft/Xbox Live access token is required for `minecraftservices.com` endpoints. Missing or expired tokens throw `MinecraftToolkitError` with `statusCode: 401`.
+
+```ts
+import {
+  fetchNameChangeInfo,
+  checkNameAvailability,
+  validateGiftCode,
+  fetchBlockedServers,
+} from "minecraft-toolkit";
+
+const accessToken = process.env.MC_ACCESS_TOKEN;
+
+const windowInfo = await fetchNameChangeInfo(accessToken);
+const availability = await checkNameAvailability("fresh_name", accessToken);
+const isGiftValid = await validateGiftCode("ABCD-1234", accessToken);
+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.
+Made by [26bz](https://github.com/26bz)
+<br><br>
+<a href="https://github.com/26bz/minecraft-toolkit/graphs/contributors">
+<img src="https://contrib.rocks/image?repo=26bz/minecraft-toolkit" />
+</a>

package/index.js

@@ -0,0 +1,35 @@
+export {
+  fetchPlayerProfile,
+  fetchPlayerSkin,
+  fetchPlayerUUID,
+  fetchUsernameByUUID,
+  fetchNameHistory,
+  fetchPlayers,
+  fetchPlayerSummary,
+  playerExists,
+  hasSkinChanged,
+} from "./src/player/profile/index.js";
+export { fetchSkinMetadata, computeSkinDominantColor } from "./src/player/skin.js";
+export { isValidUsername } from "./src/player/identity/index.js";
+export { getSkinURL, getCapeURL, getSkinModel, extractTextureHash } from "./src/player/textures.js";
+export { resolvePlayer } from "./src/player/resolve.js";
+export {
+  fetchNameChangeInfo,
+  checkNameAvailability,
+  validateGiftCode,
+  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,12 +1,76 @@
 {
   "name": "minecraft-toolkit",
-  "version": "0.1.0",
-  "description": "",
+  "version": "0.1.2",
+  "description": "Developer toolkit for working with Mojang Minecraft player data, skins, and utilities.",
+  "keywords": [
+    "minecraft",
+    "minecraft-api",
+    "minecraft-player",
+    "minecraft-skins",
+    "minecraft-tools",
+    "minecraft-utils",
+    "minecraft-uuid",
+    "mojang",
+    "mojang-api"
+  ],
+  "homepage": "https://github.com/26bz/minecraft-toolkit",
+  "bugs": {
+    "url": "https://github.com/26bz/minecraft-toolkit/issues"
+  },
   "license": "MIT",
-  "author": "",
-  "type": "commonjs",
-  "main": "index.js",
+  "author": {
+    "name": "26bz",
+    "email": "26bz@proton.me",
+    "url": "https://26bz.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/26bz/minecraft-toolkit"
+  },
+  "files": [
+    "src",
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "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"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  }
+    "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",
+    "pngjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "automd": "^0.3.2",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.2",
+    "oxfmt": "^0.36.0",
+    "oxlint": "^1.51.0",
+    "vitest": "^4.0.18"
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx,mjs,cjs}": "pnpm run lint"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@10.30.2"
 }

package/src/constants.js

@@ -0,0 +1,30 @@
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+
+export const PACKAGE_METADATA = {
+  name: pkg.name,
+  version: pkg.version,
+  description: pkg.description,
+};
+
+export const DEFAULT_JAVA_PORT = 25565;
+export const DEFAULT_BEDROCK_PORT = 19132;
+export const DEFAULT_CACHE_TTL_SECONDS = 30;
+export const DEFAULT_TIMEOUT_MS = 5000;
+export const DEFAULT_PROTOCOL_VERSION = 760; // Minecraft 1.20.4
+
+export const MOJANG_PROFILE_BASE = "https://api.mojang.com/users/profiles/minecraft";
+export const SESSION_PROFILE_BASE = "https://sessionserver.mojang.com/session/minecraft/profile";
+export const NAME_HISTORY_BASE = "https://api.mojang.com/user/profiles";
+
+export const USER_AGENT = `${pkg.name}/${pkg.version}`;
+export const DEFAULT_HEADERS = {
+  accept: "application/json",
+  "user-agent": USER_AGENT,
+};
+
+export const RAKNET_MAGIC = Buffer.from([
+  0x00, 0xff, 0xff, 0x00, 0xfe, 0xfe, 0xfe, 0xfe, 0xfd, 0xfd, 0xfd, 0xfd, 0x12, 0x34, 0x56, 0x78,
+]);

package/src/errors.js

@@ -0,0 +1,8 @@
+export class MinecraftToolkitError extends Error {
+  constructor(message, { statusCode = 500, cause } = {}) {
+    super(message);
+    this.name = "MinecraftToolkitError";
+    this.statusCode = statusCode;
+    this.cause = cause;
+  }
+}

package/src/h3/routes.js

@@ -0,0 +1,218 @@
+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];
+  if (!value) {
+    throw new MinecraftToolkitError(message, { statusCode: 400 });
+  }
+  return value;
+}
+
+export function createPlayerHandlers() {
+  const profileHandler = defineHandler(async (event) => {
+    const username = requireParam(event, "username", "Username parameter is required");
+    return fetchPlayerProfile(username);
+  });
+
+  const skinHandler = defineHandler(async (event) => {
+    const username = requireParam(event, "username", "Username parameter is required");
+    return fetchPlayerSkin(username);
+  });
+
+  const summaryHandler = defineHandler(async (event) => {
+    const username = requireParam(event, "username", "Username parameter is required");
+    return fetchPlayerSummary(username);
+  });
+
+  const uuidHandler = defineHandler(async (event) => {
+    const username = requireParam(event, "username", "Username parameter is required");
+    return fetchPlayerUUID(username);
+  });
+
+  const resolverHandler = defineHandler(async (event) => {
+    const input = requireParam(event, "input", "Username or UUID parameter is required");
+    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,
+  };
+}
+
+export function createPlayerApp(options = {}) {
+  const app = new H3(options?.app);
+  const handlers = createPlayerHandlers();
+
+  app.get("/player/:username", handlers.profileHandler, {
+    meta: { category: "player", resource: "profile" },
+  });
+
+  app.get("/player/:username/skin", handlers.skinHandler, {
+    meta: { category: "player", resource: "skin" },
+  });
+
+  app.get("/player/:username/summary", handlers.summaryHandler, {
+    meta: { category: "player", resource: "summary" },
+  });
+
+  app.get("/player/:username/uuid", handlers.uuidHandler, {
+    meta: { category: "player", resource: "uuid" },
+  });
+
+  app.get("/player/:input/resolve", handlers.resolverHandler, {
+    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 };
+}
+
+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/player/account/index.js

@@ -0,0 +1,76 @@
+import { DEFAULT_HEADERS } from "../../constants.js";
+import { MinecraftToolkitError } from "../../errors.js";
+import { fetchJson } from "../../utils/http/index.js";
+
+const API_BASE = "https://api.minecraftservices.com";
+
+function assertAccessToken(accessToken) {
+  if (!accessToken || typeof accessToken !== "string") {
+    throw new MinecraftToolkitError("A valid access token is required", { statusCode: 401 });
+  }
+  return accessToken;
+}
+
+function authHeaders(accessToken) {
+  return {
+    Authorization: `Bearer ${assertAccessToken(accessToken)}`,
+  };
+}
+
+export async function fetchNameChangeInfo(accessToken) {
+  return fetchJson(`${API_BASE}/minecraft/profile/namechange`, {
+    headers: authHeaders(accessToken),
+  });
+}
+
+export async function checkNameAvailability(name, accessToken) {
+  if (!name || typeof name !== "string") {
+    throw new MinecraftToolkitError("Name is required", { statusCode: 400 });
+  }
+  return fetchJson(`${API_BASE}/minecraft/profile/name/${encodeURIComponent(name)}/available`, {
+    headers: authHeaders(accessToken),
+  });
+}
+
+export async function validateGiftCode(code, accessToken) {
+  if (!code || typeof code !== "string") {
+    throw new MinecraftToolkitError("Gift code is required", { statusCode: 400 });
+  }
+
+  const response = await fetch(`${API_BASE}/productvoucher/giftcode/${encodeURIComponent(code)}`, {
+    headers: {
+      ...DEFAULT_HEADERS,
+      ...authHeaders(accessToken),
+    },
+  });
+
+  if (response.status === 200 || response.status === 204) {
+    return true;
+  }
+
+  if (response.status === 404) {
+    return false;
+  }
+
+  throw new MinecraftToolkitError(`Failed to validate gift code ${code}`, {
+    statusCode: response.status,
+  });
+}
+
+export async function fetchBlockedServers() {
+  const response = await fetch(`https://sessionserver.mojang.com/blockedservers`, {
+    headers: DEFAULT_HEADERS,
+  });
+
+  if (!response.ok) {
+    throw new MinecraftToolkitError("Unable to fetch blocked servers", {
+      statusCode: response.status,
+    });
+  }
+
+  const text = await response.text();
+  return text
+    .split("\n")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}

package/src/player/identity/index.js

@@ -0,0 +1,35 @@
+import { MinecraftToolkitError } from "../../errors.js";
+
+const USERNAME_REGEX = /^[a-zA-Z0-9_]{3,16}$/;
+const UUID_HEX = /^[0-9a-fA-F]+$/;
+
+export function isValidUsername(username) {
+  return typeof username === "string" && USERNAME_REGEX.test(username.trim());
+}
+
+export function isUUID(value) {
+  if (typeof value !== "string") {
+    return false;
+  }
+  const normalized = value.replace(/-/g, "");
+  return normalized.length === 32 && UUID_HEX.test(normalized);
+}
+
+export function normalizeUUID(uuid) {
+  if (!isUUID(uuid)) {
+    throw new MinecraftToolkitError("Invalid UUID", { statusCode: 400 });
+  }
+  return uuidWithoutDashes(uuid).toLowerCase();
+}
+
+export function uuidWithDashes(uuid) {
+  const compact = uuidWithoutDashes(uuid);
+  return compact.replace(/(.{8})(.{4})(.{4})(.{4})(.{12})/, "$1-$2-$3-$4-$5");
+}
+
+export function uuidWithoutDashes(uuid) {
+  if (typeof uuid !== "string") {
+    return uuid;
+  }
+  return uuid.replace(/-/g, "");
+}