minecraft-toolkit 0.1.0 → 0.1.1

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,138 @@
+# 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.
+
+## 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,22 @@
+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";

package/package.json

@@ -1,12 +1,74 @@
 {
   "name": "minecraft-toolkit",
-  "version": "0.1.0",
-  "description": "",
+  "version": "0.1.1",
+  "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"
+  },
+  "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"
+  },
   "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",
+    "docs:sync": "automd"
   }
-}
+}

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,84 @@
+import { H3, defineHandler, definePlugin } from "h3";
+import { MinecraftToolkitError } from "../errors.js";
+import {
+  fetchPlayerProfile,
+  fetchPlayerSkin,
+  fetchPlayerSummary,
+  fetchPlayerUUID,
+} from "../player/profile/index.js";
+import { resolvePlayer } from "../player/resolve.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);
+  });
+
+  return {
+    profileHandler,
+    skinHandler,
+    summaryHandler,
+    uuidHandler,
+    resolverHandler,
+  };
+}
+
+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" },
+  });
+
+  return { app, handlers };
+}
+
+export const playerPlugin = definePlugin((app) => {
+  const { handlers } = createPlayerApp({ app });
+  return handlers;
+});

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, "");
+}

package/src/player/profile/index.js

@@ -0,0 +1,144 @@
+import { MOJANG_PROFILE_BASE, SESSION_PROFILE_BASE, NAME_HISTORY_BASE } from "../../constants.js";
+import { MinecraftToolkitError } from "../../errors.js";
+import { fetchJson } from "../../utils/http/index.js";
+import { normalizeUsername } from "../../utils/validation.js";
+import { decodeTexturePayload, getSkinURL, getCapeURL, extractTextureHash } from "../textures.js";
+
+export async function fetchPlayerProfile(username) {
+  const normalizedUsername = normalizeUsername(username);
+  const identity = await fetchJson(
+    `${MOJANG_PROFILE_BASE}/${encodeURIComponent(normalizedUsername)}`,
+    {
+      notFoundMessage: "Player not found",
+    },
+  );
+
+  const sessionProfile = await fetchJson(`${SESSION_PROFILE_BASE}/${identity.id}`);
+  const texturePayload = decodeTexturePayload(sessionProfile.properties);
+
+  return {
+    id: identity.id,
+    name: identity.name,
+    profile: sessionProfile,
+    textures: texturePayload?.textures ?? {},
+    skin: texturePayload?.textures?.SKIN ?? null,
+    cape: texturePayload?.textures?.CAPE ?? null,
+  };
+}
+
+export async function playerExists(username) {
+  const normalizedUsername = normalizeUsername(username);
+  try {
+    await fetchJson(`${MOJANG_PROFILE_BASE}/${encodeURIComponent(normalizedUsername)}`);
+    return true;
+  } catch (error) {
+    if (error instanceof MinecraftToolkitError && error.statusCode === 404) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+export async function fetchPlayerSummary(username) {
+  const profile = await fetchPlayerProfile(username);
+  return {
+    id: profile.id,
+    name: profile.name,
+    skinUrl: getSkinURL(profile),
+    capeUrl: getCapeURL(profile),
+  };
+}
+
+export function hasSkinChanged(profileA, profileB) {
+  const hashA = extractTextureHash(getSkinURL(profileA));
+  const hashB = extractTextureHash(getSkinURL(profileB));
+  return hashA !== hashB;
+}
+
+export async function fetchPlayerSkin(username) {
+  const profile = await fetchPlayerProfile(username);
+  return {
+    id: profile.id,
+    name: profile.name,
+    skin: profile.skin,
+    cape: profile.cape,
+  };
+}
+
+export async function fetchPlayerUUID(username) {
+  const profile = await fetchPlayerProfile(username);
+  return {
+    id: profile.id,
+    name: profile.name,
+  };
+}
+
+export async function fetchUsernameByUUID(uuid) {
+  const response = await fetchJson(`${SESSION_PROFILE_BASE}/${uuid}`, {
+    notFoundMessage: "UUID not found",
+  });
+  return {
+    id: response.id,
+    name: response.name,
+  };
+}
+
+export async function fetchNameHistory(uuid) {
+  const entries = await fetchJson(`${NAME_HISTORY_BASE}/${uuid}/names`, {
+    notFoundMessage: "UUID not found",
+  });
+  return Array.isArray(entries)
+    ? entries.map((entry) => ({
+        name: entry.name,
+        changedAt: entry.changedToAt ? new Date(entry.changedToAt) : null,
+      }))
+    : [];
+}
+
+export async function fetchPlayers(usernames, options = {}) {
+  const { delayMs = 100, signal } = options;
+  if (!Array.isArray(usernames) || usernames.length === 0) {
+    return [];
+  }
+
+  const deduped = Array.from(new Set(usernames.map((name) => normalizeUsername(name))));
+  const results = [];
+
+  for (let index = 0; index < deduped.length; index += 1) {
+    const username = deduped[index];
+    if (signal?.aborted) {
+      throw new MinecraftToolkitError("Batch fetch aborted", { statusCode: 499 });
+    }
+
+    try {
+      const profile = await fetchPlayerProfile(username);
+      results.push({ username, profile });
+    } catch (error) {
+      results.push({ username, error });
+    }
+
+    if (index < deduped.length - 1 && delayMs > 0) {
+      await wait(delayMs, signal);
+    }
+  }
+
+  return results;
+}
+
+function wait(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener?.("abort", onAbort);
+      resolve();
+    }, ms);
+
+    function onAbort() {
+      clearTimeout(timer);
+      reject(new MinecraftToolkitError("Batch fetch aborted", { statusCode: 499 }));
+    }
+
+    if (signal) {
+      signal.addEventListener?.("abort", onAbort, { once: true });
+    }
+  });
+}

package/src/player/resolve.js

@@ -0,0 +1,31 @@
+import { isUUID, normalizeUUID, uuidWithDashes } from "./identity/index.js";
+import { fetchPlayerProfile, fetchPlayerUUID, fetchUsernameByUUID } from "./profile/index.js";
+
+export async function resolvePlayer(input) {
+  if (typeof input !== "string" || input.trim().length === 0) {
+    throw new TypeError("resolvePlayer input must be a non-empty string");
+  }
+
+  const raw = input.trim();
+
+  if (isUUID(raw)) {
+    const normalized = normalizeUUID(raw);
+    const identity = await fetchUsernameByUUID(normalized);
+    const profile = await fetchPlayerProfile(identity.name);
+    return {
+      id: uuidWithDashes(normalized),
+      name: identity.name,
+      skin: profile.skin ?? null,
+      cape: profile.cape ?? null,
+    };
+  }
+
+  const profile = await fetchPlayerProfile(raw);
+  const { id } = await fetchPlayerUUID(raw);
+  return {
+    id: uuidWithDashes(id),
+    name: profile.name,
+    skin: profile.skin ?? null,
+    cape: profile.cape ?? null,
+  };
+}

package/src/player/skin.js

@@ -0,0 +1,93 @@
+import { PNG } from "pngjs";
+import { MinecraftToolkitError } from "../errors.js";
+import { fetchPlayerProfile } from "./profile/index.js";
+
+const HEAD_REGION = { x: 8, y: 8, width: 8, height: 8 };
+
+export async function fetchSkinMetadata(username, options = {}) {
+  const profile = await fetchPlayerProfile(username);
+  const skinUrl = profile.skin?.url ?? null;
+  let dominantColor = null;
+
+  if (skinUrl && options.dominantColor !== false) {
+    dominantColor = await computeSkinDominantColor(skinUrl, options.sampleRegion);
+  }
+
+  return {
+    id: profile.id,
+    name: profile.name,
+    skin: profile.skin,
+    cape: profile.cape,
+    hasCape: Boolean(profile.cape),
+    dominantColor,
+  };
+}
+
+export async function computeSkinDominantColor(url, region = HEAD_REGION) {
+  const png = await fetchPng(url);
+  const { width, height, data } = png;
+  const { x, y, width: regionWidth, height: regionHeight } = clampRegion(region, width, height);
+
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  let samples = 0;
+
+  for (let row = y; row < y + regionHeight; row += 1) {
+    for (let col = x; col < x + regionWidth; col += 1) {
+      const idx = (row * width + col) * 4;
+      const alpha = data[idx + 3] / 255;
+      if (alpha === 0) {
+        continue;
+      }
+      r += data[idx] * alpha;
+      g += data[idx + 1] * alpha;
+      b += data[idx + 2] * alpha;
+      samples += 1;
+    }
+  }
+
+  if (samples === 0) {
+    return null;
+  }
+
+  const avgR = Math.round(r / samples);
+  const avgG = Math.round(g / samples);
+  const avgB = Math.round(b / samples);
+  return rgbToHex(avgR, avgG, avgB);
+}
+
+async function fetchPng(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new MinecraftToolkitError(`Unable to load skin texture: ${url}`, {
+      statusCode: response.status,
+    });
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer());
+  try {
+    return PNG.sync.read(buffer);
+  } catch (error) {
+    throw new MinecraftToolkitError("Unable to decode PNG skin texture", {
+      statusCode: 500,
+      cause: error,
+    });
+  }
+}
+
+function clampRegion(region, width, height) {
+  const x = Math.max(0, Math.min(width - 1, region.x ?? HEAD_REGION.x));
+  const y = Math.max(0, Math.min(height - 1, region.y ?? HEAD_REGION.y));
+  const regionWidth = Math.min(region.width ?? HEAD_REGION.width, width - x);
+  const regionHeight = Math.min(region.height ?? HEAD_REGION.height, height - y);
+  return { x, y, width: regionWidth, height: regionHeight };
+}
+
+function rgbToHex(r, g, b) {
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+
+function toHex(value) {
+  return value.toString(16).padStart(2, "0");
+}

package/src/player/textures.js

@@ -0,0 +1,39 @@
+import { MinecraftToolkitError } from "../errors.js";
+
+export function decodeTexturePayload(properties = []) {
+  const texturesProperty = properties.find((prop) => prop.name === "textures");
+  if (!texturesProperty?.value) {
+    return null;
+  }
+
+  try {
+    const decoded = Buffer.from(texturesProperty.value, "base64").toString("utf8");
+    return JSON.parse(decoded);
+  } catch (error) {
+    throw new MinecraftToolkitError("Unable to decode Mojang texture payload", {
+      statusCode: 500,
+      cause: error,
+    });
+  }
+}
+
+export function getSkinURL(profile) {
+  return profile?.skin?.url ?? null;
+}
+
+export function getCapeURL(profile) {
+  return profile?.cape?.url ?? null;
+}
+
+export function getSkinModel(profile) {
+  const model = profile?.skin?.metadata?.model;
+  return model === "slim" ? "slim" : "default";
+}
+
+export function extractTextureHash(url) {
+  if (!url) {
+    return null;
+  }
+  const match = url.match(/\/texture\/([A-Za-z0-9]+)/);
+  return match ? match[1] : null;
+}

package/src/utils/cache/index.js

@@ -0,0 +1,65 @@
+const DEFAULT_CACHE_TTL_MS = 30 * 1000;
+
+export class ResponseCache {
+  constructor(ttlMs = DEFAULT_CACHE_TTL_MS) {
+    this.ttlMs = ttlMs;
+    this.store = new Map();
+  }
+
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) {
+      return undefined;
+    }
+
+    if (entry.expiresAt <= Date.now()) {
+      this.store.delete(key);
+      return undefined;
+    }
+
+    return entry.value;
+  }
+
+  set(key, value) {
+    this.store.set(key, {
+      value,
+      expiresAt: Date.now() + this.ttlMs,
+    });
+  }
+
+  delete(key) {
+    this.store.delete(key);
+  }
+
+  clear() {
+    this.store.clear();
+  }
+}
+
+export function createCache(options = {}) {
+  if (options.cache === false) {
+    return null;
+  }
+
+  const ttlSeconds = options.cache?.ttlSeconds ?? options.cacheTtl ?? options.ttlSeconds ?? null;
+  if (ttlSeconds === null || ttlSeconds === undefined) {
+    return new ResponseCache();
+  }
+
+  return new ResponseCache(Math.max(ttlSeconds, 0) * 1000);
+}
+
+export async function withCache(cache, key, resolver) {
+  if (!cache) {
+    return resolver();
+  }
+
+  const cached = cache.get(key);
+  if (cached) {
+    return cached;
+  }
+
+  const value = await resolver();
+  cache.set(key, value);
+  return value;
+}

package/src/utils/http/index.js

@@ -0,0 +1,23 @@
+import { DEFAULT_HEADERS } from "../../constants.js";
+import { MinecraftToolkitError } from "../../errors.js";
+
+export async function fetchJson(url, { notFoundMessage, headers } = {}) {
+  const response = await fetch(url, {
+    headers: {
+      ...DEFAULT_HEADERS,
+      ...headers,
+    },
+  });
+
+  if (response.status === 404 && notFoundMessage) {
+    throw new MinecraftToolkitError(notFoundMessage, { statusCode: 404 });
+  }
+
+  if (!response.ok) {
+    throw new MinecraftToolkitError(`Failed to fetch ${url}`, {
+      statusCode: response.status,
+    });
+  }
+
+  return response.json();
+}

package/src/utils/network.js

@@ -0,0 +1,15 @@
+import { validatePort } from "./validation.js";
+
+export function resolveAddress(address, overridePort, fallbackPort) {
+  if (overridePort) {
+    return { host: address, port: validatePort(overridePort) };
+  }
+
+  const parts = address.split(":");
+  if (parts.length > 1 && parts[parts.length - 1] !== "") {
+    const extractedPort = parts.pop();
+    return { host: parts.join(":"), port: validatePort(extractedPort) };
+  }
+
+  return { host: address, port: fallbackPort };
+}

package/src/utils/validation.js

@@ -0,0 +1,28 @@
+import { MinecraftToolkitError } from "../errors.js";
+
+export function normalizeAddress(address) {
+  if (!address || typeof address !== "string") {
+    throw new MinecraftToolkitError("Server address is required", { statusCode: 400 });
+  }
+
+  return address.trim();
+}
+
+export function normalizeUsername(username) {
+  if (!username || typeof username !== "string") {
+    throw new MinecraftToolkitError("Username is required", { statusCode: 400 });
+  }
+
+  return username.trim();
+}
+
+export function validatePort(port) {
+  const parsed = Number(port);
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+    throw new MinecraftToolkitError("Port must be an integer between 1 and 65535", {
+      statusCode: 400,
+    });
+  }
+
+  return parsed;
+}