mcutils-js-api 1.0.5 → 2.0.1

package/README.md

@@ -1,15 +1,20 @@
-# mcutils-js-api
+# Minecraft Utilities - JavaScript API
 
-To install dependencies:
+TypeScript client for the [McUtils API](https://mc.fascinated.cc/api) - server status, player lookups, skins, that sort of thing.
 
 ```bash
-bun install
+bun add mcutils-js-api
 ```
 
-To run:
+```typescript
+import McUtilsAPI from "mcutils-js-api";
 
-```bash
-bun run src/index.ts
-```
+const api = new McUtilsAPI();
+const { player, error } = await api.fetchPlayer("ImFascinated");
 
-This project was created using `bun init` in bun v1.3.1. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+if (error) {
+  console.error(error.message);
+} else {
+  console.log(player?.username);
+}
+```

package/dist/index.d.ts

@@ -1,23 +1,114 @@
 import type { ErrorResponse } from "./types/response/error-response";
-import { BedrockServer } from "./types/server/bedrock-server";
-import type { JavaServer } from "./types/server/java-server";
-/**
- * Fetch a Java Minecraft server.
- *
- * @param host the host to fetch the server using (eg: aetheria.cc)
- * @returns the server or the error (if one occured)
- */
-export declare function fetchJavaServer(host: string): Promise<{
-    server?: JavaServer;
-    error?: ErrorResponse;
-}>;
-/**
- * Fetch a Bedrock Minecraft server.
- *
- * @param host the host to fetch the server using (eg: geo.hivebedrock.network)
- * @returns the server or the error (if one occured)
- */
-export declare function fetchBedrockServer(host: string): Promise<{
-    server?: BedrockServer;
-    error?: ErrorResponse;
-}>;
+import type { BedrockServer } from "./types/server/impl/bedrock-server";
+import type { JavaServer } from "./types/server/impl/java-server";
+import type { CachedPlayer } from "./types/cache/cached-player";
+import type { CachedPlayerName } from "./types/cache/cached-player-name";
+export declare class McUtilsAPI {
+    private readonly endpoint;
+    constructor(endpoint?: string);
+    /**
+     * Build URL search params string from a record of key-value pairs.
+     *
+     * @param params record of param names to string values
+     * @returns query string including leading `?`, or empty string if no params
+     */
+    buildParams(params: Record<string, string>): string;
+    /**
+     * Fetch a Java Minecraft server.
+     *
+     * @param host the host to fetch the server using (eg: aetheria.cc)
+     * @returns the server or the error (if one occurred)
+     */
+    fetchJavaServer(host: string): Promise<{
+        server?: JavaServer;
+        error?: ErrorResponse;
+    }>;
+    /**
+     * Fetch a Bedrock Minecraft server.
+     *
+     * @param host the host to fetch the server using (eg: geo.hivebedrock.network)
+     * @returns the server or the error (if one occurred)
+     */
+    fetchBedrockServer(host: string): Promise<{
+        server?: BedrockServer;
+        error?: ErrorResponse;
+    }>;
+    /**
+     * Fetch whether a server is blocked by Mojang.
+     *
+     * @param host the hostname to check (eg: aetheria.cc)
+     * @returns the blocked status or the error (if one occurred)
+     */
+    fetchServerBlocked(host: string): Promise<{
+        blocked?: boolean;
+        error?: ErrorResponse;
+    }>;
+    /**
+     * Fetch a player by UUID or username.
+     *
+     * @param id the UUID or username of the player (eg: ImFascinated)
+     * @returns the player or the error (if one occurred)
+     */
+    fetchPlayer(id: string): Promise<{
+        player?: CachedPlayer;
+        error?: ErrorResponse;
+    }>;
+    /**
+     * Resolve a username to UUID (or UUID to username).
+     *
+     * @param id the UUID or username to resolve (eg: ImFascinated)
+     * @returns the player name data or the error (if one occurred)
+     */
+    fetchPlayerUuid(id: string): Promise<{
+        playerName?: CachedPlayerName;
+        error?: ErrorResponse;
+    }>;
+    /**
+     * Fetch a server favicon/icon image.
+     *
+     * @param host the hostname of the server (eg: aetheria.cc)
+     * @returns the PNG image or the error (if one occurred)
+     */
+    fetchServerIcon(host: string): Promise<{
+        image?: ArrayBuffer;
+        error?: ErrorResponse;
+    }>;
+    /**
+     * Fetch a server preview image.
+     *
+     * @param platform the platform (java or bedrock)
+     * @param host the hostname of the server (eg: aetheria.cc)
+     * @param size the image size (default: 768)
+     * @returns the PNG image or the error (if one occurred)
+     */
+    fetchServerPreview(platform: string, host: string, size?: number): Promise<{
+        image?: ArrayBuffer;
+        error?: ErrorResponse;
+    }>;
+    /**
+     * Fetch a player's skin image.
+     *
+     * @param id the UUID or username of the player (eg: ImFascinated)
+     * @param extension the image format - png or jpg (default: png)
+     * @returns the skin image or the error (if one occurred)
+     */
+    fetchPlayerSkin(id: string, extension?: string): Promise<{
+        image?: ArrayBuffer;
+        error?: ErrorResponse;
+    }>;
+    /**
+     * Fetch a specific part of a player's skin (eg: head, body).
+     *
+     * @param id the UUID or username of the player (eg: ImFascinated)
+     * @param part the skin part to fetch (eg: head)
+     * @param extension the image format - png or jpg (default: png)
+     * @param size the image size (default: 256)
+     * @param overlays whether to render skin overlay layers (default: false)
+     * @returns the skin part image or the error (if one occurred)
+     */
+    fetchPlayerSkinPart(id: string, part: string, extension?: string, size?: number, overlays?: boolean): Promise<{
+        image?: ArrayBuffer;
+        error?: ErrorResponse;
+    }>;
+}
+export default McUtilsAPI;

package/dist/index.js

@@ -1,35 +1,167 @@
-const API_BASE = process.env.MCUTILS_API_BASE || "https://mc.fascinated.cc/api";
-/**
- * Fetch a Java Minecraft server.
- *
- * @param host the host to fetch the server using (eg: aetheria.cc)
- * @returns the server or the error (if one occured)
- */
-export async function fetchJavaServer(host) {
-    const response = await fetch(`${API_BASE}/server/java/${host}`);
-    if (response.ok) {
-        return {
-            server: (await response.json()),
-        };
-    }
-    return {
-        error: (await response.json()),
-    };
-}
-/**
- * Fetch a Bedrock Minecraft server.
- *
- * @param host the host to fetch the server using (eg: geo.hivebedrock.network)
- * @returns the server or the error (if one occured)
- */
-export async function fetchBedrockServer(host) {
-    const response = await fetch(`${API_BASE}/server/bedrock/${host}`);
-    if (response.ok) {
-        return {
-            server: (await response.json()),
-        };
-    }
-    return {
-        error: (await response.json()),
-    };
+export class McUtilsAPI {
+    constructor(endpoint = "https://mc.fascinated.cc/api") {
+        this.endpoint = endpoint;
+    }
+    /**
+     * Build URL search params string from a record of key-value pairs.
+     *
+     * @param params record of param names to string values
+     * @returns query string including leading `?`, or empty string if no params
+     */
+    buildParams(params) {
+        const str = new URLSearchParams(params).toString();
+        return str ? `?${str}` : "";
+    }
+    /**
+     * Fetch a Java Minecraft server.
+     *
+     * @param host the host to fetch the server using (eg: aetheria.cc)
+     * @returns the server or the error (if one occurred)
+     */
+    async fetchJavaServer(host) {
+        const response = await fetch(`${this.endpoint}/server/java/${host}`);
+        if (response.ok) {
+            return {
+                server: (await response.json()),
+            };
+        }
+        return {
+            error: (await response.json()),
+        };
+    }
+    /**
+     * Fetch a Bedrock Minecraft server.
+     *
+     * @param host the host to fetch the server using (eg: geo.hivebedrock.network)
+     * @returns the server or the error (if one occurred)
+     */
+    async fetchBedrockServer(host) {
+        const response = await fetch(`${this.endpoint}/server/bedrock/${host}`);
+        if (response.ok) {
+            return {
+                server: (await response.json()),
+            };
+        }
+        return {
+            error: (await response.json()),
+        };
+    }
+    /**
+     * Fetch whether a server is blocked by Mojang.
+     *
+     * @param host the hostname to check (eg: aetheria.cc)
+     * @returns the blocked status or the error (if one occurred)
+     */
+    async fetchServerBlocked(host) {
+        const response = await fetch(`${this.endpoint}/server/blocked/${host}`);
+        if (response.ok) {
+            const json = (await response.json());
+            return { blocked: json.blocked };
+        }
+        return {
+            error: (await response.json()),
+        };
+    }
+    /**
+     * Fetch a player by UUID or username.
+     *
+     * @param id the UUID or username of the player (eg: ImFascinated)
+     * @returns the player or the error (if one occurred)
+     */
+    async fetchPlayer(id) {
+        const response = await fetch(`${this.endpoint}/player/${id}`);
+        if (response.ok) {
+            return {
+                player: (await response.json()),
+            };
+        }
+        return {
+            error: (await response.json()),
+        };
+    }
+    /**
+     * Resolve a username to UUID (or UUID to username).
+     *
+     * @param id the UUID or username to resolve (eg: ImFascinated)
+     * @returns the player name data or the error (if one occurred)
+     */
+    async fetchPlayerUuid(id) {
+        const response = await fetch(`${this.endpoint}/player/uuid/${id}`);
+        if (response.ok) {
+            return {
+                playerName: (await response.json()),
+            };
+        }
+        return {
+            error: (await response.json()),
+        };
+    }
+    /**
+     * Fetch a server favicon/icon image.
+     *
+     * @param host the hostname of the server (eg: aetheria.cc)
+     * @returns the PNG image or the error (if one occurred)
+     */
+    async fetchServerIcon(host) {
+        const response = await fetch(`${this.endpoint}/server/icon/${host}`);
+        if (response.ok) {
+            return { image: await response.arrayBuffer() };
+        }
+        return {
+            error: (await response.json()),
+        };
+    }
+    /**
+     * Fetch a server preview image.
+     *
+     * @param platform the platform (java or bedrock)
+     * @param host the hostname of the server (eg: aetheria.cc)
+     * @param size the image size (default: 768)
+     * @returns the PNG image or the error (if one occurred)
+     */
+    async fetchServerPreview(platform, host, size = 768) {
+        const response = await fetch(`${this.endpoint}/server/${platform}/preview/${host}${this.buildParams({ size: String(size) })}`);
+        if (response.ok) {
+            return { image: await response.arrayBuffer() };
+        }
+        return {
+            error: (await response.json()),
+        };
+    }
+    /**
+     * Fetch a player's skin image.
+     *
+     * @param id the UUID or username of the player (eg: ImFascinated)
+     * @param extension the image format - png or jpg (default: png)
+     * @returns the skin image or the error (if one occurred)
+     */
+    async fetchPlayerSkin(id, extension = "png") {
+        const response = await fetch(`${this.endpoint}/player/${id}/skin.${extension}`);
+        if (response.ok) {
+            return { image: await response.arrayBuffer() };
+        }
+        return {
+            error: (await response.json()),
+        };
+    }
+    /**
+     * Fetch a specific part of a player's skin (eg: head, body).
+     *
+     * @param id the UUID or username of the player (eg: ImFascinated)
+     * @param part the skin part to fetch (eg: head)
+     * @param extension the image format - png or jpg (default: png)
+     * @param size the image size (default: 256)
+     * @param overlays whether to render skin overlay layers (default: false)
+     * @returns the skin part image or the error (if one occurred)
+     */
+    async fetchPlayerSkinPart(id, part, extension = "png", size = 256, overlays = false) {
+        const response = await fetch(`${this.endpoint}/player/${id}/skin/${part}.${extension}${this.buildParams({ size: String(size), overlays: String(overlays) })}`);
+        if (response.ok) {
+            return { image: await response.arrayBuffer() };
+        }
+        return {
+            error: (await response.json()),
+        };
+    }
 }
+export default McUtilsAPI;

package/dist/test.js

@@ -0,0 +1,8 @@
+import McUtilsAPI from ".";
+const api = new McUtilsAPI();
+api.fetchJavaServer("aetheria.cc").then((result) => {
+    console.log(result);
+});
+api.fetchPlayer("ImFascinated").then((result) => {
+    console.log(result);
+});

package/dist/types/cache/cache.js

@@ -0,0 +1 @@
+export {};

package/dist/types/cache/cached-player-name.d.ts

@@ -0,0 +1,6 @@
+import type { Cache } from "./cache";
+export type CachedPlayerNameData = {
+    username: string;
+    uniqueId: string;
+};
+export type CachedPlayerName = Cache & CachedPlayerNameData;

package/dist/types/cache/cached-player-name.js

@@ -0,0 +1 @@
+export {};

package/dist/types/cache/cached-player.d.ts

@@ -0,0 +1,3 @@
+import type { Cache } from "./cache";
+import type { Player } from "../player/player";
+export type CachedPlayer = Cache & Player;

package/dist/types/cache/cached-player.js

@@ -0,0 +1 @@
+export {};

package/dist/types/dns/dns-record.d.ts

@@ -0,0 +1,5 @@
+import type { ARecord } from "./impl/a-record";
+import type { SRVRecord } from "./impl/srv-record";
+export type { ARecord } from "./impl/a-record";
+export type { SRVRecord } from "./impl/srv-record";
+export type DnsRecord = ARecord | SRVRecord;

package/dist/types/dns/dns-record.js

@@ -0,0 +1 @@
+export {};

package/dist/types/dns/impl/a-record.d.ts

@@ -0,0 +1,6 @@
+export interface ARecord {
+    type: "A";
+    ttl: number;
+    name?: string;
+    address?: string;
+}

package/dist/types/dns/impl/a-record.js

@@ -0,0 +1 @@
+export {};

package/dist/types/dns/impl/srv-record.d.ts

@@ -0,0 +1,9 @@
+export interface SRVRecord {
+    type: "SRV";
+    ttl: number;
+    name: string;
+    target: string;
+    priority: number;
+    weight: number;
+    port: number;
+}

package/dist/types/dns/impl/srv-record.js

@@ -0,0 +1 @@
+export {};

package/dist/types/player/player.d.ts

@@ -0,0 +1,24 @@
+export type SkinModel = "DEFAULT" | "SLIM";
+export type SkinParts = Record<string, string>;
+export type Skin = {
+    model: SkinModel;
+    legacy: boolean;
+    url: string;
+    parts: SkinParts;
+};
+export type Cape = {
+    id?: string;
+};
+export type ProfileProperty = {
+    name: string;
+    value: string;
+    signature?: string;
+};
+export type Player = {
+    uniqueId: string;
+    username: string;
+    legacyAccount: boolean;
+    skin?: Skin | null;
+    cape?: Cape | null;
+    rawProperties?: ProfileProperty[];
+};

package/dist/types/player/player.js

@@ -0,0 +1 @@
+export {};

package/dist/types/server/{bedrock-server.d.ts → impl/bedrock-server.d.ts}

@@ -1,5 +1,6 @@
-import type { Server } from "./server";
+import type { Server } from "../server";
 export interface BedrockServer extends Server {
+    id: string;
     edition: ServerEdition;
     version: ServerVersion;
     gamemode: ServerGamemode;

package/dist/types/server/{bedrock-server.js → impl/bedrock-server.js}

@@ -1,2 +1 @@
-;
 export {};

package/dist/types/server/impl/java-server.d.ts

@@ -0,0 +1,40 @@
+import type { Server } from "../server";
+export interface JavaServer extends Server {
+    version: ServerVersion;
+    favicon: ServerFavicon | null;
+    modInfo?: ForgeModInfo;
+    forgeData?: ForgeData;
+    preventsChatReports: boolean;
+    enforcesSecureChat: boolean;
+    previewsChat: boolean;
+    mojangBlocked: boolean;
+}
+export type ServerVersion = {
+    name: string;
+    platform: string;
+    protocol: number;
+    protocolName: string;
+};
+export type ServerFavicon = {
+    base64?: string;
+    url: string;
+};
+export type ForgeModInfo = {
+    type: string;
+    modList?: ForgeMod[];
+};
+export type ForgeData = {
+    channels?: ForgeChannel[];
+    mods?: ForgeMod[];
+    truncated: boolean;
+    fmlNetworkVersion: number;
+};
+export type ForgeChannel = {
+    name: string;
+    version: string;
+    required?: boolean;
+};
+export type ForgeMod = {
+    name: string;
+    version: string;
+};

package/dist/types/server/{java-server.js → impl/java-server.js}

@@ -1,2 +1 @@
-;
 export {};

package/dist/types/server/server.d.ts

@@ -1,13 +1,14 @@
-import type { Cache } from "../cache";
+import type { Cache } from "../cache/cache";
+import type { DnsRecord } from "../dns/dns-record";
 export interface Server extends Cache {
     hostname: string;
     ip: string;
     port: number;
     motd: ServerMotd;
     players: ServerPlayers;
-    records: Array<DnsRecord>;
-    location: ServerLocation;
-    asn: AsnData;
+    records: DnsRecord[];
+    location?: ServerLocation | null;
+    asn?: AsnData | null;
 }
 export type ServerMotd = {
     raw: string[];
@@ -15,14 +16,20 @@ export type ServerMotd = {
     html: string[];
     preview: string;
 };
+export type ServerPlayerSampleName = {
+    raw: string;
+    clean: string;
+    html: string;
+};
+export type ServerPlayerSample = {
+    id: string;
+    name: ServerPlayerSampleName;
+    url: string;
+};
 export type ServerPlayers = {
     online: number;
     max: number;
-};
-export type DnsRecord = {
-    type: string;
-    ttl: number;
-    address: string;
+    sample?: ServerPlayerSample[];
 };
 export type ServerLocation = {
     country: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcutils-js-api",
-  "version": "1.0.5",
+  "version": "2.0.1",
   "module": "dist/index.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,5 +14,9 @@
   "devDependencies": {
     "@types/bun": "latest",
     "typescript": "^5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Minecraft-Utilities/JS-API"
   }
 }

package/dist/types/server/java-server.d.ts

@@ -1,18 +0,0 @@
-import type { Server } from "./server";
-export interface JavaServer extends Server {
-    version: ServerVersion;
-    favicon: ServerFavicon;
-    preventsChatReports: boolean;
-    enforcesSecureChat: boolean;
-    previewsChat: boolean;
-    mojangBlocked: boolean;
-}
-export type ServerVersion = {
-    name: string;
-    platform: string;
-    protocol: number;
-    protocolName: string;
-};
-export type ServerFavicon = {
-    url: string;
-};